## 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)