# Doc Update

> 以源码为唯一事实来源，系统性核对并更新项目文档，确保内容与实现一致、多语言文档 1:1 对齐、结构完整。

- Skill: `xiaoluolyg/doc-update` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xiaoluolyg/doc-update`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiaoluolyg/doc-update/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: xiaoluolyg (https://skillmd.com/u/xiaoluolyg)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xiaoluolyg/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 表格中做查找替换须谨慎** — 表格每列用 `|` 分隔，搜索短文本时易匹配到相邻列的分隔符，应携带足够的上下文以确保定位准确。