ploop/docs/plan/document-structure-refactor-plan.md
2026-08-31 15:27:34 +08:00

5.1 KiB
Raw Permalink Blame History

PLoop 当前文档边界收敛实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

目标: 让 V1 当前契约、实施计划与已被取代的 P0 原型各自只有一个明确归属,避免后续实现将历史文档误读为当前规范。

方案: 保留现有七个 docs/ 顶级分类。将平台和双语数据的持久契约归入 design/,将旧 P0 原型收拢到 design/legacy/,保留 plan/ 仅承载实施顺序、工作项和实时状态;所有入口链接在同一次迁移中更新。

技术栈: Markdown、仓库内相对链接、标准库只读链接/锚点审计。

依据: 文档贡献约定、D-016、R-002。

全局约束

  • 不改变 R-001 的用户验收、D-008/D-010 的范围决定、任何 benchmark 口径或 M0a 的真实实施状态。
  • requirements/ 只保留用户结果与产品范围;具体技术组成由 design/ 与 decisions/ 负责。
  • 历史 P0 原型必须保留可追溯说明和替代它的决定,不能伪装为当前 V1 规范。
  • 全部仓库内 Markdown 相对路径和标题锚点必须在迁移后可解析;不校验外部 URL。

Task 1:建立本次文档迁移的追踪边界

文件:

  • 新建:docs/plan/work-items/W-M0a-02-document-current-state-boundaries.md
  • 修改:docs/plan/TODO.md
  • 修改:docs/plan/traceability.md

输入: R-002、D-016、当前 M0a 状态。

输出: 一个唯一的、可完成的 M0a 叶子工作项;TODO 与追踪矩阵仅记录状态和链接。

  • 新建工作项,列明允许路径为 docs/ 与根 README.md,禁止修改产品契约或应用代码。
  • 在 TODO 中将该工作项列为当前 M0a 叶子任务;完成时写入迁移文件清单与审计命令结果。
  • 在追踪矩阵中将 M0a 的文档边界收敛列为完成证据摘要。

Task 2:以事实归属迁移当前规范与历史原型

文件:

  • 移动:docs/plan/iteration-1-platform-plan.md → docs/design/v1-platform-contract.md
  • 移动:docs/plan/p0-multihop-rag-bilingual-plan.md → docs/design/multihop-rag-bilingual-contract.md
  • 移动:docs/design/p0-runtime-design.md → docs/design/legacy/p0-runtime-prototype.md
  • 移动:docs/design/p0-dataset-and-cases.md → docs/design/legacy/p0-synthetic-dataset-and-cases.md
  • 修改:上述四份文档的标题和状态说明。

输入: 当前平台范围 D-010、双语数据范围 D-008。

输出: design/ 拥有当前平台/数据契约,design/legacy/ 显式保存被取代的 P0 行为和合成数据探索。

  • 创建 design/legacy/ 并迁移四份文档,不复制第二份内容。
  • 将两份当前文档改名为 V1 契约,说明其边界而非实时实施状态。
  • 在两份 legacy 文档首段指明它们的历史性质、替代决定和只可作为原型/调研参考的边界。

Task 3:更新事实所有者、入口与状态记录

文件:

  • 修改:README.md、docs/README.md
  • 修改:docs/requirements/R-001-v1-rag-evaluation-platform.md
  • 修改:docs/decisions/decisions.md
  • 修改:docs/plan/TODO.md、docs/plan/traceability.md
  • 修改:所有引用旧路径的 docs/**/*.md

输入: Task 2 的最终路径。

输出: 入口只展示当前规范;历史条目被明确标记;已收敛的问题不再混在待确认列表。

  • 将 docs/README.md 的分类表、根 README 的导航和计划索引指向新路径;根入口不再将 legacy P0 文档列为当前设计。
  • 将 R-001 的技术栈名称下沉为对平台契约/决定的引用,同时保留其浏览器操作、异步运行、受控 adapter 和隔离验收。
  • 把 Q-001 放到“已收敛的历史问题”,保留其原始语义和 D-010 链接;Q-002/Q-003 继续保留为待确认。
  • 将 W-M0a-02 设为 DONE,恢复 TODO 的下一步为工程工具链的下一叶子工作项。

Task 4:执行文档验证与收尾审阅

文件:

  • 修改:docs/plan/document-structure-refactor-plan.md
  • 修改:docs/plan/work-items/W-M0a-02-document-current-state-boundaries.md

输入: 所有仓库内 Markdown 文件。

输出: 可复现的链接/锚点审计证据和已完成的计划复核。

  • 运行只读标准库审计:提取相对 Markdown 链接,确认目标文件存在,并确认带锚点的目标包含对应标题 slug;最终结果为 checked=196 markdown_files=42 errors=0。
  • 搜索旧路径、过期“等待范围决策”状态与“已由 D-010 收敛”仍位于待确认区的残留;旧路径只保留在本计划与已完成工作项的迁移记录中,过期状态无残留。
  • 将本计划的复选框与 W-M0a-02 的完成证据更新为实际命令及结果;未声称尚未建立的 make check-docs 已存在。