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/）
3.4 KiB
3.4 KiB
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
- 将 6 个文件
Move-Item到services/ - 批量替换所有外部文件（
main.py、ui/*.py）中的 import：from xxx→from services.xxx - 批量替换
services/*.py中的内部 import：from xxx→from .xxx - 语法验证：对所有修改文件执行
ast.parse() - 启动验证：
python -c "from ui.app import build_app"确认无导入错误
回滚方案： 删除 services/ 下新迁移的文件，将 git 恢复（或手动移回根目录），改回 import）