wiki

目标

把跨任务、跨会话仍有价值的项目知识持久化到 docs/wiki/。wiki 记录当前事实、长期约定和可复用背景；临时计划、执行 checklist 或会话流水只有在用户明确要求归档时才转入。

铁律

每个 wiki 文件第一行必须是摘要。扫描 wiki 时只读路径和第一行摘要；需要更多内容时再按候选页面渐进读取。

文件结构

wiki 根目录固定为 docs/wiki/。

每个主题目录都必须有一个与目录同名的说明页，用于直接说明该目录维护的范围、边界和内容：

docs/wiki/
  <topic>/
    <topic>.md
    <page>.md

规则：

• docs/wiki/<topic>/<topic>.md 直接描述该目录维护的范围、边界和内容。
• 目录摘要写在同名说明页第一行，例如 docs/wiki/<topic>/<topic>.md。
• 文件和目录名使用小写 kebab-case。

Wiki 模板

模板只固定可发现性所需的骨架：第一行摘要和标题。正文按内容本身组织，不强制章节。

目录说明页：docs/wiki/<topic>/<topic>.md

> 摘要：本目录维护 [topic] 的范围、边界和内容。

# [Topic]

[该目录维护的范围、边界和内容说明。]

知识页：docs/wiki/<topic>/<page>.md

> 摘要：本页维护 [具体主题] 的长期知识。

# [页面标题]

[正文]

默认只写稳定知识。猜测、临时状态、未批准方案不要写进 wiki。临时计划、一次性任务步骤和会话流水只有在用户明确要求归档时才转入，并标清来源。

统一入口流程

创建、更新、从现有文档转入 wiki，都先走匹配流程：

1. 判断内容是否值得沉淀：架构、模块职责、术语、项目约定、稳定流程、常见问题、已确认决策背景。
2. 搜索 docs/wiki/ 时只读取文件路径和每个 .md 文件的第一行摘要。不要扫描全文，不要递归读取目录内容正文。
3. 按路径、slug、关键词和第一行摘要，判断是否已有匹配目录或可更新页面。
4. 如果有匹配页面，向用户确认是否更新该页面，并说明会追加或改写什么内容。
5. 如果只有匹配目录，向用户确认是否在该目录下新建页面，并推荐文件名和标题。
6. 如果没有匹配目录，向用户确认是否新建目录和页面，并推荐目录名、说明页名、页面名和标题。

没有用户确认，不创建文件、不更新页面、不迁移内容。

例外：scope skill 在出口选择时已向用户列出并获得确认的 wiki 文件，视为已授权，不再重复确认。已批准 spec 的同步可以更新或创建用户确认过的最小必要 wiki；已确认对话内 plan 的小任务只能更新用户确认过的已有 wiki，不能自动创建新目录或页面。两者仍必须遵守摘要扫描、渐进读取和只写稳定知识的规则。

确认候选后，才读取相关页面全文和必要来源文档。仍然只读取与本次写入直接相关的文件。

创建新页面流程

适用：用户提供新的长期知识，且匹配流程没有找到可更新页面。

1. 只用 wiki 路径和第一行摘要判断候选目录。
2. 如果有匹配目录，向用户推荐：

- 目标目录：docs/wiki/<topic>/ - 页面文件：<page>.md - 页面标题：# [标题] - 第一行摘要：> 摘要：...

1. 如果没有匹配目录，向用户推荐：

- 新目录：docs/wiki/<topic>/ - 目录说明页：docs/wiki/<topic>/<topic>.md - 知识页：docs/wiki/<topic>/<page>.md - 两个文件各自的摘要和标题

1. 用户确认后再创建文件。
2. 按模板写入摘要、标题和正文；正文不强制章节。
3. 目录边界变化时更新对应的目录说明页。

不要因为没有完美目录就直接新建；先给出推荐并等用户确认。

更新已有页面流程

适用：用户给出的知识与已有 wiki 页面范围匹配。

1. 只用 wiki 路径和第一行摘要找候选页面。
2. 向用户说明推荐更新哪个页面，以及预计怎么更新：

- 追加新章节 - 改写现有章节 - 更新摘要 - 拆分到新页面

1. 用户确认后，读取候选页面全文。
2. 只修改与本次知识相关的部分，保留页面原有范围。
3. 如果页面范围变化，同步更新第一行 > 摘要：...。
4. 如果目录边界发生变化，同步更新目录说明页。

不要把不相关知识塞进一个“差不多相关”的页面；范围不合适时推荐新页面。

从现有文档转入流程

适用：用户要求把 spec、plan、handoff、README 或散落文档转成 wiki。

1. 读取用户指定的来源文档，判断更适合全文转入、摘要转入还是拆分转入，并提取候选主题、关键词和来源路径。
2. 扫描 wiki 时仍只读路径和第一行摘要，匹配可更新页面或目录。
3. 如果有匹配页面，向用户确认是否转入该页面，并说明推荐的转入方式和会影响哪些内容。
4. 如果只有匹配目录，向用户推荐在该目录下创建哪个页面。
5. 如果没有匹配目录，向用户推荐新目录、新目录说明页和新知识页。
6. 用户确认后，再读取目标页面全文或创建新文件。
7. 按确认的方式写入 wiki，保留来源链接。

转入方式由用户意图和内容价值决定：

• 用户明确要归档原文，或原文整体仍然稳定有用时，可以全文转入。
• 如果来源是 spec、plan、handoff 或会话文档，默认先说明哪些内容适合长期保存；用户确认全文归档时再全文转入。
• 如果一个来源跨多个主题，推荐拆分到多个 wiki 页面，并让用户确认映射。
• 如果只需要沉淀结论，摘要或整理转入即可。

默认保留原文档，并在 wiki 页中记录来源。只有用户明确要求清理旧文档时，才移动或删除原文件。

完成前检查

• 每个新增/修改页面第一行都是 > 摘要：...，并且有标题。
• 每个新增目录都有同名说明页，说明页第一行也是摘要。
• 新增目录或目录边界变化时，相关目录说明页已更新。
• 来源路径或链接已记录。
• 转入方式（全文、摘要或拆分）符合用户确认，没有混入未确认猜测。