docs-updater

文档更新器

找出文档描述与代码行为之间的偏差，然后修正文档。以代码为准：绝不虚构代码不具备的功能、命令或能力。

开始时声明：“我正在使用 docs-updater 技能，使文档与代码保持一致。”

在 bash 中运行 shell 代码片段（Windows 上使用 Git Bash）。

0. 设置

此技能会读取 docs/agents/docs.md、docs/agents/workspace.md、 docs/agents/issue-tracker.md 和 docs/agents/human-follow-up.md。请遵循 .agents/skills/docs-updater/settings/README.md 中的说明来读取这些文件，并补全任何缺失的文件；其定义文件位于该 README 旁边。

1. 模式和范围

从参数或调用方的指示中获取这两项：

• 模式 — fix（默认）会编辑文档；check 不做任何编辑，只报告偏差。
• 范围 — 差异范围（<base>..HEAD）、更改列表，或不指定范围以完整审查每个 Doc map 条目。

调用方可能会添加约束；请遵循这些约束。来自 ship：分支尚未合并，因此不要改动归 ship 所有的文档，也不要声称工作已经发布——不得更改路线图、归档、发布或合并状态，也不得更改看板。描述此分支实现的内容仍属于范围。来自 end-session：按照其说明处理本次会话的工作，无论是否已合并。

2. 找出范围内的文档

对于差异范围：

git diff --stat "$range"
git diff --name-status "$range"

阅读差异本身，而不只是文件列表。跳过生成的副本（由 Generated-config check 重新生成的镜像），改为阅读其源文件。也跳过 Doc map 标记为 frozen 的技能正文（这些技能已安装，此处绝不编辑）：只阅读其更改对其他文档中声明的影响，例如设置重命名或新增命令。如果仓库会安装自身的技能，则跳过已安装副本，绝不跳过它所基于的源文件。将每项更改与每个 Doc map 条目的 when 相匹配：其中列出的路径，以及更改类型（新增端点、命令变更、新增设置、移除功能）。when 是信号，不是限制：即使某项更改与某个文档的 when 不匹配，只要它明显会影响该文档，也属于范围，并应在报告中注明，以便扩展 Doc map。纯重构通常不需要修改文档；应说明这一点，而不是凭空编造文档更改。更改列表也采用同样的匹配方式。完整审查时，每个条目都在范围内。

然后搜索差异中被移除或重命名的名称（设置、命令、文件、标志、“四项全部”之类的数量），以及含义被扩大或缩小的名称：对这些名称的过时引用都属于偏差，无法通过任何 when 预判。对于差异新增到枚举集合中的成员（标记、设置、技能），应改为搜索其同类项：只列出已有成员而未包含新成员的列表，如今已不完整。请按文档中的写法搜索名称，通常会使用反引号（`frozen`），以免被常见词汇淹没搜索结果。搜索范围要比 Doc map 更广，并跳过生成的副本和 frozen 文档：

• 每个受版本控制的 Markdown 文件（git ls-files '*.md'）；
• 如果存在其检出目录，也要从其自身根目录搜索配套仓库；
• 每个 Wiki：Follow-up wiki，以及任何位于 Wiki 中的 Doc map 条目；当更改发生在默认分支时，在临时位置使用只读克隆进行搜索。

Doc map 未列出的文档中若有匹配项，也应像其他文档一样修复，并在报告中注明，以便扩展映射。Wiki 应等到合并后再处理，以免页面指向尚不存在的文件：在未合并的分支上运行时（包括每次 ship 运行）都跳过 Wiki 搜索，并报告合并后仍需搜索 Wiki。下一次运行 end-session 或任何在默认分支上的运行都应执行该搜索，并修复搜索发现的问题。

3. 对照代码检查每份文档

阅读范围内的每份文档，然后根据其真实来源核实变更可能影响的每项陈述：优先检查 Drift probes，否则直接检查代码、清单、配置和 CI 工作流。可执行配置优先于说明文字。统计探针列出的内容，不要轻信文档中的数字（CI 作业按顶层键统计，而不是按每个 name: 统计）。

范围内的运行会报告在范围外发现的偏差（探针所反驳的旧说法），但不会修复：这类偏差应由各自的变更处理。完整审计则会修复这些偏差。

配套文档。 设置了 Private companion 时，必须先确认已检出配套仓库，再阅读或编辑其中的文档；并从配套仓库自身的根目录检查（git -C private status、git -C private log）：外层仓库的历史绝不能作为其证据。若未检出配套仓库，请检查公开文档，并报告哪些配套文档检查无法执行；不要创建任何内容来代替它。

4. 修复（修复模式）

编辑每份存在偏差的文档，并遵循其标记：

• frozen — 绝不编辑。append-only — 只能添加，不能更改。amend-only — 添加一条注明日期的修订说明。
• owner-only — 报告偏差；由用户编辑。
• ship-owned — 留给 ship 处理。在 ship 之外，至多添加一条 Unreleased 变更日志条目；绝不添加版本、日期或带日期的章节。
• pinned — 其他检查会对其进行指纹校验，任何编辑，即使只是修改链接，也会导致该检查失败，直到更新它所指向的固定项。仅在变更需要时编辑；先确认此次编辑不会改变固定项保护的内容（需求、矩阵行），然后在同一变更中更新固定项，并在报告中同时指出两者，以便调用方在 PR 中说明原因。范围内需要保持不变的 pinned 文档，应保留其固定项；仍须检查固定项与文档是否一致，并报告其当前有效。

编写文档时，要让下一位读者信任其中的内容：

• 每项事实只设一处权威来源。 在 Doc map 指定的位置更新事实，并从其他位置链接到该处，而不是复制内容。精简入口文件（CLAUDE.md 导入 AGENTS.md）不应包含自己的内容。
• 描述现状，而非计划。 项目指南描述已实现的行为。工作状态——状态、下一步、待办事项——应记录在问题跟踪项中，而非 Markdown：文档可以说明最终契约（“密钥位于保管库中”），但不能描述待执行的操作。
• 保留长期有效的规则。 历史记录应放在变更日志和 ADR 中；文档记录当前规则，也可以引用确立该规则的问题跟踪项。对于同时包含两者的文档（例如，在设计旁附有调研），更新当前状态的陈述，并保留有日期的发现原文。只有代码表明某项已知限制已修复时，才能将其删除。
• 决策与术语。 绝不要为使已采纳的 ADR 与代码一致而编辑它；应报告矛盾。当术语表（CONTEXT.md）定义了某个术语时，应链接到该定义，而不要重新陈述；也不要为了符合新术语而重命名代码。
• 保密信息务必保密。 Doc map 的 Never in public docs 列表中的任何内容，以及密钥、凭据、账户标识符、线上资源名称或指向配套仓库的链接，都不得写入公开文档。安全弱点应通过 Security findings 流程处理，绝不能放到公开页面。
• 生成文件。 修改源文件，绝不修改生成的副本；然后运行 Generated-config check 的重新生成命令。除非收到要求，否则不要改动 Agent 和技能的 frontmatter。
• 设置步骤 仅在前置条件、命令或端口确实发生变化时才修改。

所有编辑都保持未提交状态，无论在公开检出库还是配套仓库中：由调用方提交；若技能单独运行，则由用户提交。

5. 人工操作

列出此次变更遗留的所有必要人工操作（访问权限设置、仪表板变更、凭据、手动检查），或者说明没有。通过 ship 或 end-session 运行时，将列表返回给调用方，由调用方对所有操作统一执行后续流程。独立运行时，请自行执行 .agents/skills/docs-updater/settings/human-follow-up.md 中的 ## Procedure。无论哪种情况，后续操作都不能只记录在文档中。

6. 验证

• Docs validation，在各命令指定的文件夹中运行（未指定时在仓库根目录运行）。
• 设置要求运行时，执行 Generated-config check。
• 执行 git diff --check 检查空白字符错误。
• 检查所有已编辑文档中的链接和锚点是否有效：相对路径必须存在，且 #anchors 必须与目标中的标题匹配。

此次运行的编辑导致的失败必须在报告前修复。切勿屏蔽或规避真实失败；应如实报告。

7. 报告

无论哪种模式，都先报告私有内容泄露。然后每份文档占一行，并使用纯文本标签：

• current — 已对照代码检查，无需更改；
• changed — 说明更改内容（修复模式）；
• drift — 说明不一致之处及其来源：检查模式下未修复；或仅凭代码无法判断（功能已禁用或移除？）；或文档标记为 owner-only 或 frozen。

然后报告没有匹配到任何 Doc map 项的 when 的变更、发现的人工操作（以及独立运行时的后续操作链接或发布阻碍）、验证结果、无法运行的配套检查，以及编辑尚未提交。