AGENTS

Wiki 维护规则

定位

• 本 Wiki 是独立仓库，位于外层项目的 external/wiki/。
• Wiki 应先建立稳定的信息架构，再逐个主题核对和更新，不能根据一次局部修改临时拼接内容。
• 文档必须描述当前事实，不保留旧结构、旧路径或历史行为的兼容说明。
• 用户文档说明怎么使用；开发文档说明实现、边界、维护和验证，两者不要混写。

事实来源

• 代码、测试和构建配置是技术事实源，Wiki 不能用旧 Wiki 内容自证。
• 更新技术页前，应读取该主题对应的实现、测试、配置和直接依赖。
• Wiki 与实现冲突时，以当前实现为准，并同时搜索和修正其他页面中的同义旧说法。
• 临时计划、TODO、阶段进度和交接状态容易失效，应放到 issue，不作为长期技术文档保留。

页面组织

• 同一主题只保留一个承载完整细节的权威页。
• 总览、首页、架构入口和索引页负责导航、范围和阅读顺序，不复制权威页的大段内容。
• 页面短不代表内容不足。路由页职责完整时应保持简洁，不为增加字数堆叠重复信息。
• 旧页面应逐页决定保留、合并、拆分、重写或删除，不能仅因数量多而批量删除，也不能全部原样保留。
• 合并页面前，先把仍然有效且唯一的信息迁移到目标权威页，再删除来源页。
• 技术索引只收录已经完成代码核对的权威页。

默认语言与文件名

• 默认入口为英文 Home.md，中文入口为 首页.md。
• 英文页面使用可读的英文文件名，例如 Encoding-and-Decoding.md。
• 中文页面使用可读的中文文件名，例如 开发文档-专题-编码与解码.md。
• 不使用 ZH-*、*-EN.md 等会让 GitHub Wiki 页面标题显示语言代码的命名方式。
• GitHub Wiki 的页面标题会受到文件名影响，因此中英文页面都必须使用读者可直接理解的文件名。
• 英文首页、英文总览和英文导航中的普通入口必须链接英文页，不能误跳到中文页。

中英文配对

• 每个英文内容页顶部必须提供 [中文](中文页面名)。
• 每个中文内容页顶部必须提供 [English](English-Page-Name)。
• 两个链接必须互相指回正确的对应页。
• 中英文对应页必须具有相同的标题层级、主题范围和事实密度。
• 翻译应自然表达相同知识，不要求逐句直译，但不能一边只有摘要、另一边包含完整细节。
• 新增、重命名、合并或删除页面时，必须同时处理对应语言页面及所有反向链接。

首页、侧边栏与 Pages 列表

• Home.md 保持默认英文首页，并在顶部提供中文切换。
• 首页.md 在顶部提供 English 切换。
• _Sidebar.md 是共用导航，每个双语入口保持“英文在左、中文在右”。
• 侧边栏的英文链接文本和目标均应为英文，中文链接文本和目标均应为中文。
• 右侧 Pages 列表使用页面文件名生成可见标题，不能只靠页面内 H1 修正，因此文件命名本身必须可读。
• 新增权威页后，根据其层级更新首页、用户或开发总览、技术索引和 _Sidebar.md，但不要把所有细节页都堆进主导航。

标题与链接

• 每个内容页只能有一个一级标题 #。
• 页面内部使用稳定的 Wiki 相对链接，不写本机绝对路径。
• 重命名或删除页面后，必须检查整个 Wiki 的入站链接，不能留下断链。
• 链接文本应说明目标内容，避免大量使用“这里”“详情”等无意义文字。
• 页面标题、文件名、导航文字和对应语言应一致。

内容写法

• 先说明页面范围和读者，再展开核心事实、边界、操作或维护方法。
• 对复杂主题优先说明主链路、不变量、失败边界和验证入口。
• 不重复可以通过一个稳定链接获得的长篇内容。
• 不把某次改动过程、提交差异或临时调试记录写成永久设计结论。
• 代码符号、协议字段、命令和配置值使用反引号；普通产品名称和章节标题不滥用代码格式。
• 用户页避免暴露无助于操作的实现细节；开发页避免只描述界面现象而缺少实现边界。

逐页审核流程

1. 阅读待审核页面及其直接链接的权威页，标记重复、冲突和陈旧内容。
2. 定位主题对应的代码、测试、配置、入口和依赖，核对每项技术事实。
3. 决定保留、合并、拆分、重写或删除。
4. 先整理一个语言版本的完整事实，再建立或同步另一语言版本。
5. 搜索全 Wiki 的同义旧说法、旧文件名和旧链接并统一修正。
6. 更新必要的总览、索引和侧边栏入口。
7. 验证链接、双语正反向配对、标题层级、H1 数量和 Markdown 格式。
8. 只有完成以上检查后，才在审核清单中标记完成。

完成标准

每轮 Wiki 修改至少确认：

• 所有本地 Wiki 链接目标存在。
• 每个内容页只有一个 H1。
• 每个英文页都有中文对应页和正确的反向链接。
• 每个中文页都有英文对应页和正确的反向链接。
• 中英文对应页标题层级一致。
• _Sidebar.md 的双语顺序和目标正确。
• 英文默认入口没有误链中文页。
• 不存在旧文件名、旧页面名或已删除页面的残留引用。
• Markdown 差异检查无空白错误。
• 页面统计只在确有用途时记录；新增或删除页面后必须同步更新，避免数字漂移。

提交范围

• Wiki 修改应在 external/wiki/ 独立仓库内检查和提交。
• 提交前只查看并纳入 Wiki 仓库范围内属于本次工作的文件。
• 不把外层仓库或其他子仓库的修改混入 Wiki 提交说明。
• 提交消息应概括文档结构和内容变化，不记录与 Wiki 无关的应用实现细节。