doc-update

文档更新

以源码为唯一事实来源，系统性核对并更新项目文档。保证多语言文档对齐、配置表准确、代码引用正确、章节编号连续。

核心原则

1. 源码即真理 — 默认值、枚举值、标志列表一律以源码为准，文档记载不作为依据。
2. 多语言 1:1 — 每种语言的文档必须完整配对，发现缺口时须先向用户确认，不自行补全。
3. 文档不写版本号 — vX.Y.Z 很快过时，用功能描述替代。
4. 编号必须连续 — 插入/删除章节后递增所有后续章节号。
5. 就地修复 — 范围和结构决策（更新哪些文件、是否新建语言文档）需先确认；内容错误（数值、列表、编号）审计到即直接写入，不等二次确认。

---

操作流程

读取约束：每次只读 1–3 个文件，避免单次读取过多导致上下文溢出。

0. 确定范围

若用户未指定目标文档：

1. 搜索项目根目录下常见文档目录（doc/、docs/、README*.md）
2. 列出找到的文档列表，请用户确认本次更新范围
3. 范围确认后再进入后续流程，不自行决定

1. 清点与配对

列出所有语言的文档目录，建立跨语言映射表，标出缺口。发现缺口时向用户报告，不自行创建。

2. 提取源码事实

根据文档主题定位权威源码文件。常见对照关系：

文档主题	权威源码
配置表	配置文件、环境变量模板
CLI / 命令	命令解析器、枚举定义、常量集合
模块功能	对应模块的入口文件、枚举类、路由表
API 文档	路由定义、接口描述文件

在源码中搜索关键符号，定位后读取具体内容。

3. 逐文件审计

配置表审计：

• 每个配置项在源码配置文件中是否存在？
• 默认值是否与源码一致？（区分配置文件默认值和环境变量默认值）
• 环境变量名是否与模板文件吻合？
• 源码中已有但文档未收录的新条目？

代码引用审计：

• 文档提到的类名、枚举成员、常量 → 与源码定义逐一核对
• 文档提到的文件路径 → 确认实际存在
• 文档描述的功能范围 → 与源码实现比对，是否遗漏新增能力

结构检查：

• 章节编号连续，无跳跃无重复
• 无过期版本标签
• 交叉引用链接可跳转
• 专有名词/产品名称全文统一

4. 修复

修复类型	操作
补缺失章节	在正确位置插入，然后所有后续章节号 +1
修正数值	以源码值为准，覆盖文档中的错误值
补全列表	新增遗漏的枚举成员、环境变量、配置项
移除版本标签	去掉版本号，改用功能描述
修正错别字	统一产品名、修正文字错误

重编号要领：插入新章节后，逐个修改后续章节号 +1，不得批量替换，以免误改其他位置出现的相同数字。

5. 验收

• 检查所有标题编号，确认连续无重复
• 多语言文档数量与配对状态符合步骤 1 的确认结果
• 抽查 2–3 处修复行确认内容正确
• 交叉引用链接可跳转

---

常见陷阱

• 配置里写的 ≠ 运行时用的 — 配置文件记录相对路径，运行时会拼接工作目录前缀（如 agent/skills → workspace/agent/skills/）。文档应记录配置文件中的原始值，而非运行时解析后的路径。
• 配置注释可能过时 — 注释标注"60秒"但实际值为 3600 的情况较为常见。应以实际值为准，注释不可作为依据。
• 区分配置变量和环境变量 — 仅出现在环境变量模板中、未在配置文件中定义的变量，不应归入配置表章节，应单独放在"仅环境变量可配置"区域。
• 插入章节后需修改其后所有编号 — 不得仅修改下一节，其后各节的编号均需递增 +1。
• 在 markdown 表格中做查找替换须谨慎 — 表格每列用 | 分隔，搜索短文本时易匹配到相邻列的分隔符，应携带足够的上下文以确保定位准确。