xiaoluolyg 文档更新
以源码为唯一事实来源，系统性核对并更新项目文档。保证多语言文档对齐、配置表准确、代码引用正确、章节编号连续。
核心原则
- 源码即真理 — 默认值、枚举值、标志列表一律以源码为准，文档记载不作为依据。
- 多语言 1:1 — 每种语言的文档必须完整配对，发现缺口时须先向用户确认，不自行补全。
- 文档不写版本号 —
vX.Y.Z很快过时，用功能描述替代。 - 编号必须连续 — 插入/删除章节后递增所有后续章节号。
- 就地修复 — 范围和结构决策（更新哪些文件、是否新建语言文档）需先确认；内容错误（数值、列表、编号）审计到即直接写入，不等二次确认。
操作流程
读取约束：每次只读 1–3 个文件，避免单次读取过多导致上下文溢出。
0. 确定范围
若用户未指定目标文档：
- 搜索项目根目录下常见文档目录（
doc/、docs/、README*.md） - 列出找到的文档列表，请用户确认本次更新范围
- 范围确认后再进入后续流程，不自行决定
1. 清点与配对
列出所有语言的文档目录，建立跨语言映射表，标出缺口。发现缺口时向用户报告，不自行创建。
2. 提取源码事实
根据文档主题定位权威源码文件。常见对照关系：
| 文档主题 | 权威源码 |
|---|---|
| 配置表 | 配置文件、环境变量模板 |
| CLI / 命令 | 命令解析器、枚举定义、常量集合 |
| 模块功能 | 对应模块的入口文件、枚举类、路由表 |
| API 文档 | 路由定义、接口描述文件 |
在源码中搜索关键符号，定位后读取具体内容。
3. 逐文件审计
配置表审计：
- 每个配置项在源码配置文件中是否存在？
- 默认值是否与源码一致？（区分配置文件默认值和环境变量默认值）
- 环境变量名是否与模板文件吻合？
- 源码中已有但文档未收录的新条目？
代码引用审计：
- 文档提到的类名、枚举成员、常量 → 与源码定义逐一核对
- 文档提到的文件路径 → 确认实际存在
- 文档描述的功能范围 → 与源码实现比对，是否遗漏新增能力
结构检查：
- 章节编号连续，无跳跃无重复
- 无过期版本标签
- 交叉引用链接可跳转
- 专有名词/产品名称全文统一
4. 修复
| 修复类型 | 操作 |
|---|---|
| 补缺失章节 | 在正确位置插入，然后所有后续章节号 +1 |
| 修正数值 | 以源码值为准，覆盖文档中的错误值 |
| 补全列表 | 新增遗漏的枚举成员、环境变量、配置项 |
| 移除版本标签 | 去掉版本号，改用功能描述 |
| 修正错别字 | 统一产品名、修正文字错误 |
重编号要领：插入新章节后，逐个修改后续章节号 +1，不得批量替换，以免误改其他位置出现的相同数字。
5. 验收
- 检查所有标题编号，确认连续无重复
- 多语言文档数量与配对状态符合步骤 1 的确认结果
- 抽查 2–3 处修复行确认内容正确
- 交叉引用链接可跳转
常见陷阱
- 配置里写的 ≠ 运行时用的 — 配置文件记录相对路径，运行时会拼接工作目录前缀（如
agent/skills→workspace/agent/skills/）。文档应记录配置文件中的原始值，而非运行时解析后的路径。 - 配置注释可能过时 — 注释标注"60秒"但实际值为
3600的情况较为常见。应以实际值为准，注释不可作为依据。 - 区分配置变量和环境变量 — 仅出现在环境变量模板中、未在配置文件中定义的变量，不应归入配置表章节，应单独放在"仅环境变量可配置"区域。
- 插入章节后需修改其后所有编号 — 不得仅修改下一节，其后各节的编号均需递增 +1。
- 在 markdown 表格中做查找替换须谨慎 — 表格每列用
|分隔，搜索短文本时易匹配到相邻列的分隔符，应携带足够的上下文以确保定位准确。