docs-curate

技能：docs-curate

使用时机

• llmwiki/html/ 或 wiki/sources/draft/ 积累了太多本地文件（长时间工作后生成了许多报告/提案）。
• 感觉“文档很有价值，但杂乱/难以查找/克隆时可能会丢失”。

为什么分为 3 层（而不是只“合并”）

把本地 HTML 合并起来仍然是 LOCAL → 在另一台机器上拉取仓库时仍会丢失（html/draft 文件被 gitignore）。真正“有价值”的是设计决策 / 经验教训 / 模式——它们必须进入 wiki（可迁移 + 会提交）。而渲染产物（html、draft 报告）是临时的 → 归档。工具负责确定性地分类 + 移动 + 建立索引；阅读理解并提升内容的工作由你（Agent）负责。

步骤

1. 计划（dry-run，不动文件）：

   python3 fdk/tools/docs-curate.py plan        # in 3 tầng KEEP / ARCHIVE / PROMOTE?
   

2. 先将真正有价值的内容提升到 wiki——归档前完成（由 Agent 判断）：
   • 对于每个 PROMOTE? 项目，以及每组提案 ARCHIVE 中的每个 draft：阅读内容。如果其中包含 wiki 尚未收录的决策/经验教训/模式 → 将其写成：
     • llmwiki/wiki/sources/adr/ADR-NNN-<slug>.md，用于记录一项决策，或
     • llmwiki/wiki/concepts/<slug>.md，用于记录一个概念/模式。 使用正确的 YAML frontmatter（type:…）+ ## Origin（指向源 draft/commit）。更新 wiki/index.md + wiki/log.md。
   • 如果 wiki/git 中已有 → 跳过，只归档。
   • 不要提升琐碎内容（进度报告、重复渲染产物）。只提升“值得机器/其他人阅读”的内容。
3. 执行（按功能移动 ARCHIVE + 自动重新建立索引）：

   python3 fdk/tools/docs-curate.py apply        # archive theo nhóm + reorg file đã-archive + reindex
   

   • 归档不要平铺：按功能整理到 archive/<group>/ — proposals/（draft+seq 配对文件）、superseded/（被替代的版本）、analysis/（评估是否提升的分析）、reports/。
   • 整理之前已归档的文件（archive 根目录下的平铺文件 → 移入正确分组）——包括已经进入 archive 的文件。
   • 为整个 archive 建立索引：生成 llmwiki/html/archive/INDEX.md（按组编制的索引，仍可找回）+ index.html 仪表板（active）+ wiki/index.md（R3）。
   • 只想重新整理并为 archive 建立索引（不再归档任何内容）：python3 fdk/tools/docs-curate.py reindex。
   • 自定义保留 active 的日期标记数量：apply --keep-dates 3。
4. **验证 + 提交：**确认新的 index.html（active）+ archive/INDEX.md（按组整理的 archive）已生成，且 wiki/index.md 与 R3 一致（dev framework → 运行 fdk-gate）。提交内容包括：新提升的 ADR/concept（archive/ + index 是本地 gitignore 文件）。追加更新 log.md。

规则

• 先 PROMOTE，再 ARCHIVE——绝对不要归档尚未及时提升到 wiki、却包含有价值内容的 draft（本地 gitignore → 丢失就是真的丢失）。
• 归档 = 移动，不是删除——文件移入 archive/，原样保留（仍然是有价值的文档，只是从 active 工作区移出）。
• Canonical（overstack.html、index.html、*-cheatsheet、*-health-dashboard）永远不要归档。
• 职责分明：工具 = 分类/移动/重新建立索引（确定性操作）；Agent = 提升内容（阅读理解）。不要混淆。
• 每个新 wiki 条目都要有 ## Origin；更新 wiki/index.md + wiki/log.md（规则 R2/R3）。