swm8023 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，都先走匹配流程：
- 判断内容是否值得沉淀：架构、模块职责、术语、项目约定、稳定流程、常见问题、已确认决策背景。
- 搜索
docs/wiki/时只读取文件路径和每个.md文件的第一行摘要。不要扫描全文，不要递归读取目录内容正文。 - 按路径、slug、关键词和第一行摘要，判断是否已有匹配目录或可更新页面。
- 读取与本次知识相关的少量候选页面正文及必要来源，确认实际范围、已有内容和可能冲突，不在用户批准前禁止必要只读探索。
- 有匹配页面时形成具体更新内容；已有授权覆盖目标和内容就直接写入，否则说明准备追加或改写什么并确认目标。
- 需要新建、拆分或处理内容冲突时，基于已读内容给出目录、页面和具体变更建议；只确认尚未授权的目标或实质选择，不逐项重问已有决定。
没有覆盖目标与内容的用户授权，不创建文件、不更新页面、不迁移内容。用户直接指定页面和更新目标、当前对话已有对应批准，或上游 skill 已交接确认目标时，都视为已有授权；不再重复确认同一更新。
scope 已确认的目标沿用其边界：已批准 spec 的同步可以更新或创建用户确认过的最小必要 wiki；已确认对话契约的小任务只能更新用户确认过的已有 wiki，不能自动创建新目录或页面，除非用户明确授权。仍遵守摘要扫描、渐进读取和只写稳定知识的规则。
目标选择或写入内容需要确认时，先完成相关正文读取并形成可审阅的具体建议，再询问；不以“建议更新”冒充用户授权。始终只读取与本次写入直接相关的文件，不全库加载正文。
创建新页面流程
适用：用户提供新的长期知识，且匹配流程没有找到可更新页面。
- 先用 wiki 路径和第一行摘要定位候选目录，再按需读取相关说明页和候选正文以判断是否确需新页面。
- 如果有匹配目录，向用户推荐：
- 目标目录：
docs/wiki/<topic>/ - 页面文件：
<page>.md - 页面标题：
# [标题] - 第一行摘要：
> 摘要：...
- 目标目录：
- 如果没有匹配目录，向用户推荐：
- 新目录：
docs/wiki/<topic>/ - 目录说明页：
docs/wiki/<topic>/<topic>.md - 知识页：
docs/wiki/<topic>/<page>.md - 两个文件各自的摘要和标题
- 新目录：
- 目标和内容已有授权时直接创建，否则先提交具体建议，获得确认后创建。
- 按模板写入摘要、标题和正文；正文不强制章节。
- 目录边界变化时更新对应的目录说明页。
不要因为没有完美目录就扩大范围；需要尚未授权的新目录或页面时先给出具体建议并确认。
更新已有页面流程
适用：用户给出的知识与已有 wiki 页面范围匹配。
- 先用 wiki 路径和第一行摘要找候选页面，再读取与更新直接相关的正文。
- 依据页面实际内容形成具体更新建议：
- 追加新章节
- 改写现有章节
- 更新摘要
- 拆分到新页面
- 已有授权覆盖目标和内容时直接更新；否则展示具体变更建议并确认未决项。
- 只修改与本次知识相关的部分，保留页面原有范围。
- 如果页面范围变化，同步更新第一行
> 摘要：...。 - 如果目录边界发生变化，同步更新目录说明页。
不要把不相关知识塞进一个“差不多相关”的页面；范围不合适时推荐新页面。
从现有文档转入流程
适用：用户要求把 spec、plan、handoff、README 或散落文档转成 wiki。
- 读取用户指定的来源文档，判断更适合全文转入、摘要转入还是拆分转入，并提取候选主题、关键词和来源路径。
- 扫描路径和第一行摘要匹配候选，再读取少量候选正文，判断转入方式及具体影响。
- 如果有匹配页面，说明具体转入内容和方式；授权已覆盖时不重问，否则确认目标或实质选择。
- 如果只有匹配目录，向用户推荐在该目录下创建哪个页面。
- 如果没有匹配目录，向用户推荐新目录、新目录说明页和新知识页。
- 在必要正文读取完成、目标与转入方式获授权后写入或创建文件，不把只读探索放到确认之后。
- 按确认的方式写入 wiki，保留来源链接。
转入方式由用户意图和内容价值决定：
- 用户明确要归档原文，或原文整体仍然稳定有用时，可以全文转入。
- 如果来源是 spec、plan、handoff 或会话文档，默认先说明哪些内容适合长期保存；用户确认全文归档时再全文转入。
- 如果一个来源跨多个主题，推荐拆分到多个 wiki 页面，并让用户确认映射。
- 如果只需要沉淀结论，摘要或整理转入即可。
默认保留原文档，并在 wiki 页中记录来源。只有用户明确要求清理旧文档时，才移动或删除原文件。
完成前检查
- 每个新增/修改页面第一行都是
> 摘要：...，并且有标题。 - 每个新增目录都有同名说明页，说明页第一行也是摘要。
- 新增目录或目录边界变化时，相关目录说明页已更新。
- 有文件或链接来源时记录其路径或链接；只有当前对话中的已确认事实时如实说明来源，不编造链接，也不因此重新请求同一写入批准。
- 转入方式（全文、摘要或拆分）符合用户确认，没有混入未确认猜测。