zhoujie
2ba87c8f6e
- 新增 GitHub Issue 模板（Bug 报告、功能请求）和 Pull Request 模板 - 新增 Code of Conduct（贡献者行为准则）和 Security Policy（安全政策） - 新增 CI 工作流（GitHub Actions），包含 ruff 代码检查和导入验证 - 新增开发依赖文件 requirements-dev.txt 📦 build(ci): 配置 GitHub Actions 持续集成 - 在 push 到 main 分支和 pull request 时自动触发 CI - 添加 lint 任务执行 ruff 代码风格检查 - 添加 import-check 任务验证核心服务模块导入 ♻️ refactor(structure): 重构项目目录结构 - 将根目录的 6 个服务模块迁移至 services/ 包 - 更新所有相关文件的导入语句（main.py、ui/、services/） - 根目录仅保留 main.py 作为唯一 Python 入口文件 🔧 chore(config): 调整配置和资源文件路径 - 将 config.json 移至 config/ 目录，更新相关引用 - 将个人头像图片移至 assets/faces/ 目录，更新 .gitignore - 更新 Dockerfile 和 docker-compose.yml 中的配置路径 📝 docs(readme): 完善 README 文档 - 添加项目状态徽章（Python 版本、License、CI） - 更新项目结构图反映实际目录布局 - 修正使用指南中的 Tab 名称和操作路径 - 替换 your-username 占位符为格式提示 🗑️ chore(cleanup): 清理冗余文件 - 删除旧版备份文件、测试脚本、临时记录和运行日志 - 删除散落的个人图片文件（已归档至 assets/faces/）
56 lines
3.4 KiB
Markdown
56 lines
3.4 KiB
Markdown
## Context
|
||
|
||
当前项目根目录同时存在 6 个业务服务文件（`config_manager.py`、`llm_service.py`、`sd_service.py`、`mcp_client.py`、`analytics_service.py`、`publish_queue.py`）与 `services/` 包目录并列，架构层次混乱。`services/` 下游代码（`scheduler.py` 等）通过裸名导入（flat import）引用这些文件，依赖 Python 将根目录隐式加入 `sys.path` 这一运行时特性。
|
||
|
||
迁移约束：
|
||
- `services/__init__.py` 已存在，`services/` 是合法 Python 包
|
||
- 所有受影响文件共约 20 处 import，分布在 `main.py`、`ui/app.py`、`ui/tab_create.py`、`services/*.py`
|
||
- 必须保证 Python 不产生循环导入（circular import）
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
- 将 6 个服务文件移入 `services/`，根目录只保留 `main.py` 一个 Python 文件
|
||
- 所有 import 使用绝对路径（`from services.xxx import ...`），保持一致性、可读性
|
||
- `services/` 内部文件之间使用相对导入（`from .xxx import ...`），减少路径依赖
|
||
- 不引入任何新的运行时依赖或行为变更
|
||
|
||
**Non-Goals:**
|
||
- 不拆分或合并任何模块的内部逻辑
|
||
- 不更改 `services/__init__.py` 的公开导出（除非需要兼容性垫片）
|
||
- 不迁移 `ui/` 下的文件（已有独立模块结构）
|
||
|
||
## Decisions
|
||
|
||
**决策 1：外部文件用绝对导入 `from services.xxx import ...`**
|
||
- `main.py`、`ui/app.py`、`ui/tab_create.py` 均从根目录运行，绝对导入路径清晰、错误信息可读
|
||
- 替代：在 `services/__init__.py` 重新导出所有符号（向后兼容）→ 增加维护负担，拒绝
|
||
|
||
**决策 2：`services/` 内文件之间用相对导入 `from .xxx import ...`**
|
||
- 避免 `services/` 内部对根目录的隐式依赖，打包或测试时不受 `sys.path` 影响
|
||
- 替代：也用绝对导入 → 可行但不如相对导入内聚
|
||
|
||
**决策 3：分两阶段迁移（先移文件，再改 import）**
|
||
- 防止中间状态同时修改多文件导致错误难以定位
|
||
- 迁移顺序：`config_manager` → `mcp_client` → `llm_service` → `sd_service` → `analytics_service` → `publish_queue`（按依赖深度从浅到深）
|
||
|
||
**决策 4：不添加兼容性垫片（shim）**
|
||
- 项目无外部 PyPI 消费者，无向后兼容压力，直接修改所有 import 更干净
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- **[风险] `services/` 内循环导入** → 缓解：迁移前用 `grep` 确认依赖关系，`config_manager` 通常是叶节点（最少依赖），优先迁移
|
||
- **[风险] `ui/app.py` 在迁移中途启动失败** → 缓解：一次性修改所有文件 import，不留半迁移状态；迁移后立即用 `ast.parse()` 验证语法
|
||
- **[风险] Dockerfile `COPY . .` 已是整目录复制** → 无影响，`services/` 子目录正常复制
|
||
- **[风险] CI 首次运行可能因 GitHub Secrets 缺失（如无 `GITHUB_TOKEN`）报错** → 缓解：CI 仅做静态检查，不需要 Secrets
|
||
|
||
## Migration Plan
|
||
|
||
1. 将 6 个文件 `Move-Item` 到 `services/`
|
||
2. 批量替换所有外部文件（`main.py`、`ui/*.py`）中的 import：`from xxx` → `from services.xxx`
|
||
3. 批量替换 `services/*.py` 中的内部 import：`from xxx` → `from .xxx`
|
||
4. 语法验证：对所有修改文件执行 `ast.parse()`
|
||
5. 启动验证：`python -c "from ui.app import build_app"` 确认无导入错误
|
||
|
||
**回滚方案：** 删除 `services/` 下新迁移的文件，将 git 恢复（或手动移回根目录），改回 import）
|