# Wiki

> 在需要沉淀、查找、整理或迁移项目长期知识时使用；维护 docs/wiki 下的项目 wiki，包括架构、约定、术语、流程、决策背景、模块知识和现有文档转入 wiki。

- Skill: `swm8023/wiki` (Agent Skill)
- Install (CLI): `npx skillmds@latest add swm8023/wiki`
- Raw SKILL.md: https://api.skillmd.com/api/skills/swm8023/wiki/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: swm8023 (https://skillmd.com/u/swm8023)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/swm8023/wiki

---


# wiki

## 目标

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

## 铁律

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

## 文件结构

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

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

```text
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`

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

# [Topic]

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

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

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

# [页面标题]

[正文]
```

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

## 统一入口流程

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

1. 判断内容是否值得沉淀：架构、模块职责、术语、项目约定、稳定流程、常见问题、已确认决策背景。
2. 搜索 `docs/wiki/` 时只读取文件路径和每个 `.md` 文件的第一行摘要。不要扫描全文，不要递归读取目录内容正文。
3. 按路径、slug、关键词和第一行摘要，判断是否已有匹配目录或可更新页面。
4. 读取与本次知识相关的少量候选页面正文及必要来源，确认实际范围、已有内容和可能冲突，不在用户批准前禁止必要只读探索。
5. 有匹配页面时形成具体更新内容；已有授权覆盖目标和内容就直接写入，否则说明准备追加或改写什么并确认目标。
6. 需要新建、拆分或处理内容冲突时，基于已读内容给出目录、页面和具体变更建议；只确认尚未授权的目标或实质选择，不逐项重问已有决定。

没有覆盖目标与内容的用户授权，不创建文件、不更新页面、不迁移内容。用户直接指定页面和更新目标、当前对话已有对应批准，或上游 skill 已交接确认目标时，都视为已有授权；不再重复确认同一更新。

`scope` 已确认的目标沿用其边界：已批准 spec 的同步可以更新或创建用户确认过的最小必要 wiki；已确认对话契约的小任务只能更新用户确认过的已有 wiki，不能自动创建新目录或页面，除非用户明确授权。仍遵守摘要扫描、渐进读取和只写稳定知识的规则。

目标选择或写入内容需要确认时，先完成相关正文读取并形成可审阅的具体建议，再询问；不以“建议更新”冒充用户授权。始终只读取与本次写入直接相关的文件，不全库加载正文。

## 创建新页面流程

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

1. 先用 wiki 路径和第一行摘要定位候选目录，再按需读取相关说明页和候选正文以判断是否确需新页面。
2. 如果有匹配目录，向用户推荐：
   - 目标目录：`docs/wiki/<topic>/`
   - 页面文件：`<page>.md`
   - 页面标题：`# [标题]`
   - 第一行摘要：`> 摘要：...`
3. 如果没有匹配目录，向用户推荐：
   - 新目录：`docs/wiki/<topic>/`
   - 目录说明页：`docs/wiki/<topic>/<topic>.md`
   - 知识页：`docs/wiki/<topic>/<page>.md`
   - 两个文件各自的摘要和标题
4. 目标和内容已有授权时直接创建，否则先提交具体建议，获得确认后创建。
5. 按模板写入摘要、标题和正文；正文不强制章节。
6. 目录边界变化时更新对应的目录说明页。

不要因为没有完美目录就扩大范围；需要尚未授权的新目录或页面时先给出具体建议并确认。

## 更新已有页面流程

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

1. 先用 wiki 路径和第一行摘要找候选页面，再读取与更新直接相关的正文。
2. 依据页面实际内容形成具体更新建议：
   - 追加新章节
   - 改写现有章节
   - 更新摘要
   - 拆分到新页面
3. 已有授权覆盖目标和内容时直接更新；否则展示具体变更建议并确认未决项。
4. 只修改与本次知识相关的部分，保留页面原有范围。
5. 如果页面范围变化，同步更新第一行 `> 摘要：...`。
6. 如果目录边界发生变化，同步更新目录说明页。

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

## 从现有文档转入流程

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

1. 读取用户指定的来源文档，判断更适合全文转入、摘要转入还是拆分转入，并提取候选主题、关键词和来源路径。
2. 扫描路径和第一行摘要匹配候选，再读取少量候选正文，判断转入方式及具体影响。
3. 如果有匹配页面，说明具体转入内容和方式；授权已覆盖时不重问，否则确认目标或实质选择。
4. 如果只有匹配目录，向用户推荐在该目录下创建哪个页面。
5. 如果没有匹配目录，向用户推荐新目录、新目录说明页和新知识页。
6. 在必要正文读取完成、目标与转入方式获授权后写入或创建文件，不把只读探索放到确认之后。
7. 按确认的方式写入 wiki，保留来源链接。

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

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

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

## 完成前检查

- 每个新增/修改页面第一行都是 `> 摘要：...`，并且有标题。
- 每个新增目录都有同名说明页，说明页第一行也是摘要。
- 新增目录或目录边界变化时，相关目录说明页已更新。
- 有文件或链接来源时记录其路径或链接；只有当前对话中的已确认事实时如实说明来源，不编造链接，也不因此重新请求同一写入批准。
- 转入方式（全文、摘要或拆分）符合用户确认，没有混入未确认猜测。