跳转至

目录分层重构记录（2026-09-26）

分支 refactor/layering（基于 c4e231c）· 4 个独立可 revert 的提交 · 验收 11 项全过 本文是版本叙事（做了什么、踩了什么坑）；目录结构权威描述见 architecture.md §3，放置规则见仓库根 AGENTS.md 末节。

1. 重构目标与结果

消除四项结构债，纯结构重构，零行为变更（路由 URL / 页面渲染 / SQL / 函数签名 / 端口 5010 全部不变）：

# 问题 结果
1 app.py 单文件巨石（838 行、30 路由、5 过滤器） 7 行入口 + src/web/ 10 蓝图
2 src/ 16 模块平铺无域 src/{kg,llm,pipeline,content} 四域包
3 scripts/ 18 脚本平铺 scripts/{build,sync,kg,deploy,ops} 五分类
4 双导入路径（try/except 回退裸导入）+ sys.path.insert ×16 全仓绝对导入 from src.<pkg>.<module>，path hack 清零，pip install -e . 接管

2. 提交清单

阶段 Commit 内容
1 0e7ee63 src/ 16 模块 git mv 归四包；try/except 双分支导入收敛为绝对导入；全仓裸导入清零
2 52efbd3 app.py → create_app 工厂 + get_db/close_db/过滤器迁移；30 路由按域拆 10 蓝图（views/ 9 文件 + api.py）；函数体逐字搬运
3 4e65153 pyproject.toml（deps 迁自 requirements.txt；py-modules=["app"]、包名保留 src）；scripts/ 五分类；16 处 sys.path.insert 全删
4 bed7ed6 README/CLAUDE/AGENTS/docs/skills/diagrams 全量路径同步（约 170 处）；AGENTS.md 增「代码放置规则」
收尾 （本次） CI workflow 路径修复 + 本文 + architecture §3 重写

每阶段完成后 run_tests.py 均 242 通过 / 0 失败 / 2 跳过，与重构前基线一致；核心路由冒烟（含详情页真实 ID）全部 200。

3. 任务书之外发现并修复的问题

  1. __file__ 相对定位随移动失效：kg_schema._BASE_DIR 少一层导致 data/graph.db 打不开（测试当场抓出）；scripts 的 Path(__file__).parent.parent 全部改 parents[2] 锚定仓库根。
  2. 任务书 §3.2 未列的裸导入约 30 处：etl.py 函数内 from trends import/import daily/import viewpoint、run_tests.py 12 处、build_static_site.py 6 处局部导入等，全部一并绝对化。
  3. run_tests 的子进程调用与 install_skill 路径对象：指向旧位置的 scripts/install_skill.py、scripts/build_static_site.py 子进程命令和 MCP/SYNC 路径常量，已随移动更新；run_tests 加载同目录 mcp_server 改用 importlib shim（不再依赖目录 path hack）。
  4. CI 遗漏（文档清扫未覆盖 .github/）：deploy-site.yml 三处脚本路径 + 需补 pip install -e .，已在收尾提交修复。
  5. 全局 skills 重装：~/.zcode/skills/{xgb-wiki,xgb-sync} 内嵌绝对路径随旧位置失效，跑 python scripts/ops/install_skill.py 刷新。

4. 对使用方式的影响（⚠️ 唯一新增前置）

  • 新克隆/新环境必须先 pip install -e .——脚本（scripts/**）与 app.py 的 from src.* import 不再依赖任何 path hack，靠可编辑安装解析。已写入 README 快速开始、CLAUDE.md 常用命令与 CI workflow。
  • 常用命令一律换新路径，例如：
python scripts/sync/sync_data.py          # 数据同步（原 scripts/sync_data.py）
python scripts/ops/run_tests.py           # 全功能测试 242 项
python scripts/build/build_static_site.py # 静态站构建
python app.py                             # Web 入口不变
  • Web 开发方式变化：新路由写进 src/web/views/<域>.py 对应蓝图，不再堆 app.py；模板过滤器在 src/web/helpers.py。

5. 放置规则（同 AGENTS.md）

  • 新页面路由 → src/web/views/<域>.py 对应蓝图，禁止回到 app.py 堆叠
  • 新 KG/本体逻辑 → src/kg/；LLM/问答 → src/llm/；同步与解析 → src/pipeline/；内容生成 → src/content/
  • 新脚本 → scripts/{build,sync,kg,deploy,ops}/ 对应子目录，一律绝对导入 from src.xxx import
  • 一次性验证脚本不进仓库；如需留存放 scratch/（自行加入 .gitignore）
  • 依赖方向：web → {kg,llm,content} → {pipeline,config}；config 不依赖任何模块

6. 验收记录

11 项验收（测试全绿 / 路由一致 / 入口瘦身 / 蓝图齐全 / 域分包 / 无裸导入 / 无 path hack / 可安装 / 文档同步 / git log --follow 历史保留 / 4 提交规范）全部通过，逐项输出见重构会话汇报；git mv 保证全部 34 个移动文件历史可追溯。