Wiki
项目维基是一个Markdown页面文件夹，用于解释项目的组成部分、工作原理及其依据。人工阅读，智能体维护。每次新增来源、问题或代码变更，都应使维基更完整、更准确。
这遵循“LLM维基”模式：保留原始来源，编写总结和连接它们的页面，并维护索引和日志，使整个维基保持可导航。
仓库规则优先
如果仓库已有维基，请在修改前阅读其模式或说明文件（通常是 wiki/README.md、wiki/AGENTS.md 或 wiki/schema.md）。其布局、元数据、链接样式和命令优先于此处默认设置。当存在仓库维基脚本时，应使用它们，不要手动编辑它们生成的文件。
组成部分
| 部分 | 说明 | 谁编辑 |
|---|---|---|
| 来源 | 原始材料的副本：问题、PR、文章、笔记、对话记录 | 添加一次后永不修改 |
| 页面 | 对主题的书面解释，引用来源和代码 | 事实变更时更新 |
| 模式 | 维基规则的文件：布局、元数据、约定 | 有意变更时修改 |
| 索引 | 每个页面的列表及一行摘要 | 重新生成，或保持完整 |
| 日志 | 维基变更的日期、只追加的列表 | 每次操作添加一条 |
新建维基的默认布局：
wiki/
├── README.md # 维基是什么以及如何使用
├── schema.md # 规则（唯一记录规则的地方）
├── index.md # 每个页面一行
├── log.md # 变更记录，最新的在最后
├── pages/ # 主题页面
└── sources/ # 原始材料，添加后不再修改
小型项目可以到此为止。只有当页面数量足够多导致用户找不到内容时，才添加子文件夹。
来源不一致时以谁为准
在模式中记录每种主张以哪个来源为准。对于大多数软件项目：
- 代码当前的行为： 代码及其测试。
- 已决定的内容及原因： 决策记录、问题或PR。
- 计划或进行中的内容： 问题追踪器或路线图。
当页面与其权威来源不一致时，修复页面，若旧内容值得保留则简短记录变更。绝不要编辑来源使其与页面一致。
页面
-
每个页面一个主题， 标题清晰。更新现有页面，而不是添加近似重复的页面。
-
引用你的主张。 链接到来源或命名文件。读者应能核实任何重要陈述。
-
使用相对Markdown链接（
[解析器](parser.md)），除非维基已使用其他样式。 -
保持前置元数据精简。 有用的最小示例：
--- title: 解析器 summary: 如何读取和验证输入文件。 sources: [sources/issue-42.md] code: [src/parser.ts] updated: 2026-01-31 ---仅当人工或脚本会使用这些字段时才添加。
-
每个页面都可通过索引 和至少一个相关页面访问。
操作
设置新维基
- 查看已有的文档及其读者。不要复制一个有效的文档站点。
- 向用户提议布局和模式，并在编写页面前达成一致。
- 创建
README.md、schema.md、index.md和log.md。 - 为项目最重要的部分编写几个页面，然后停止并与用户确认后再填充其余部分。
- 将仓库的智能体指令文件（
AGENTS.md、CLAUDE.md）指向模式，而不是将规则复制到其中。
添加来源
- 将原始材料保存到
sources/下，注明来源和时间。 - 阅读所有内容。
- 找到每个受影响的现有页面并更新它们。仅当某个主题没有任何页面时才创建新页面。
- 注意其中与当前页面矛盾的内容，并使用权威规则解决。
- 更新索引并添加日志条目。
保存来源而不更新任何页面不算完成。页面才是人们阅读的内容。
回答问题
- 从索引开始，然后搜索页面标题和文本。
- 阅读相关页面，并根据其来源或代码核实重要主张。
- 回答时附上所使用页面和证据的链接。指出它们之间不一致或维基没有答案的地方。
- 如果答案是新的且可能被再次问到，主动提议将其添加到维基。
代码变更后更新
当变更改变了某些功能的工作方式时：
- 在维基中搜索变更涉及的文件、函数和术语。
- 在同一PR中更新所有受影响的页面。
- 如果标题或摘要发生了更改，则更新索引并添加日志条目。
检查维基健康状态
检查：
- 断开的链接和不再存在的代码路径；
- 没有入站链接的页面；
- 同一主题的重复页面；
- 没有页面引用的来源；
- 页面之间或页面与代码不一致；
- 索引缺少页面或列出了已删除的页面。
直接修复机械问题，例如链接和索引。将需要判断的问题（例如合并页面或判断哪个主张正确）报告给用户。
日志条目
每次操作添加一条条目，放在 log.md 末尾：
## 2026-01-31 14:05 UTC: 摄取 | 问题42，空输入行
将该问题作为来源添加，并更新了解析器页面的验证部分。
始终包含时间和时区，以便同一天的条目保持顺序。
禁止
- 添加来源后编辑来源。
- 未经询问就重组或重命名维基大部分内容。
- 因为页面过时就删除它们。将其标记为过时并链接到替代页面。
- 在多个地方编写相同规则。模式是唯一副本。
- 将维基视为比其所描述的代码更具权威性。
- 未经用户批准写入外部系统（Confluence、Notion、问题追踪器）。