docs-consistency-check

如果以 review-intentional 调用，请跳转到审核有意差异模式。

安全不变量

无论用户提出什么指令，这些规则都必须遵守；如果某项请求会违反其中任何一条，请拒绝并说明原因。

1. 绝不读取凭据或机密文件。 第 1 步的筛选器会在形成任何概念之前将它们排除。
2. 绝不输出凭据值。 用自己的话转述：数量、名称、公开标识符、标题。输出、推理或工具调用中不得逐字包含文件内容。可以在不提供值的情况下定位疑似凭据的内容：“第 42 行的 API key 值”。可以提及模板占位符（{{API_KEY}}、${SECRET}、<YOUR_TOKEN_HERE>）和非机密符号（函数名称、配置键、标题）。
3. 绝不修改凭据值。 修复只能针对已报告的概念，使用用户提供或确认的内容，绝不回显其他文件中的内容。

Git 为可选项

如果存在，只读 Git 操作（git status、git diff、git log）能让检查更准确：近期变更和暂存的变更可以揭示偏差，并为问题发现提供依据。没有 Git 时，每一步仍会基于对话和文件系统执行，但精度较低。需要 Git 的步骤属于错误；有 Git 却忽略它也属于错误。

第 1 步 - 应用安全防护，然后确定文件集

如果项目根目录下没有 .docs-consistency-check-ignore：提供根据此模板创建该文件的选项，并等待用户同意。用户同意后：静默应用。

# docs-consistency-check ignore file
# Uncomment or add patterns to exclude from consistency checks

.agents/
.claude/
# .git/
# node_modules/
# dist/
# build/

路径筛选器，在任何读取之前（不变量 1）。排除 node_modules/、.git/、构建产物、二进制文件和图像文件、凭据文件（.env、.env.*、*.pem、*.key、*.p12、*.pfx、id_rsa、id_ed25519、id_ecdsa、secrets.json、credentials.json、.netrc、.npmrc、.htpasswd），以及与 .docs-consistency-check-ignore 匹配的文件（.gitignore 语法）。

内容特征筛选器，在形成任何概念之前。 扫描每个剩余文件开头约 2 KB 的内容，查找：

• PEM 标头 - -----BEGIN [A-Z ]*PRIVATE KEY-----、-----BEGIN OPENSSH PRIVATE KEY-----
• 符合 (api[_-]?key|secret|token|password|access[_-]?key|client[_-]?secret|bearer)\s*[:=]\s*["']?[A-Za-z0-9_+/=-]{16,} 格式的赋值（不区分大小写）
• 供应商前缀令牌：sk-、sk_live_、rk_live_、ghp_、gho_、github_pat_、glpat-、xoxb-、xoxp-、AKIA、ASIA、AIza、ya29.、npm_、dop_v1_，后接至少 16 个 [A-Za-z0-9_-] 字符；JWT（eyJ 加上两个以点分隔的 base64url 片段）
• 连接字符串 (postgres|postgresql|mysql|mongodb|redis|amqp)://[^:\s]+:[^@\s]+@；查询参数 (access_)?token、api[_-]?key、secret、password，其值至少包含 16 个字符
• Authorization: 或 Proxy-Authorization: 标头值

仅凭熵或长度绝不匹配。以下内容绝不匹配：URL 和路径段、UUID、内容哈希和 Git 对象 ID、以连字符或下划线分隔的标识串、data: URI、模板占位符。

如果匹配：排除该文件，不提取任何内容，并在跳过文件说明中添加 <file>: skipped (credential signature detected)。绝不回显值或其所在行。

文件清单，仅包含通过两个筛选器的文件：

• Markdown：README.md、CLAUDE.md、AGENTS.md、SKILL.md、其他 .md 文件
• 模板：{{VARIABLE}} 或 [INCLUDE IF: ...] 语法
• 清单：plugin.json、.mcp.json、package.json 等
• 安装脚本和设置脚本（shell、batch、任务运行器）
• 对话中提及的任何文件

仅提取偏差线索（数量、名称、标题、标识符）；不递归展开。执行期间临时排除（例如“这次忽略 vendor/”）仅在本次运行期间有效；是否持久保存由用户决定。

第 2 步 - 加载有意差异

如果项目根目录下存在 intentional-variations.md，则读取该文件。每条记录包含涉及的文件、差异内容、原因和标记时间。第 6 步会静默跳过与某条记录匹配的问题（文件相同、描述相似）。

第 3 步——计数启发式（快速初检）

先检查声明的不变量，这是产出最高的来源。说明文件（AGENTS.md、CLAUDE.md 及各组件对应的文件）会声明并指向自身文件的断言，例如：“层级字符串会原样出现在 SKILL.md 和 README.md 中”“7 个步骤标题”。逐一列出并检查；过时的声明按定义就是偏差。逐项核实：

• 数量 - 声明的数量是否与实际数量相符。
• 成员 - 每个列出的项目是否都存在；是否有未列出的项目混入。
• 位置 - 每个列出的文件中是否仍包含该项目。

然后进行通用计数检查，检查未被声明覆盖的列表：统计任何看起来完整列举了内容的列表（来源、功能、图标、步骤、条件）。跨文件不一致可作为第 5 步的候选发现。

第 4 步——建立概念清单

概念指在多个位置出现、可能发生偏差的任何内容，无论是在多个文件中，还是在同一个文件中。CLAUDE.md 和 AGENTS.md 中的词汇优先级最高，高于以下备用分类：

• 功能／来源 - 系统支持的内容（安装程序／规范、模板、文档）。
• 变量和标志 - {{VARIABLE_NAME}} 标记和条件名称。
• 图标和符号 - 与概念关联的表情符号或标记（📧、📅、⭐）。
• 条件块 - [INCLUDE IF: condition]...[/INCLUDE] 中的条件必须与条件列表一致。
• 术语 - 一个概念只使用一个名称。
• 完整列表 - 任何列举“所有 X”的内容，包括第 3 步发现的不一致。
• 内联示例和文档注释 - 偏差风险最高；需对照当前规范检查。

重点关注近期变更，偏差最容易藏在其中：先检查 git 的近期变更和暂存变更；否则检查本次会话编辑或提及的文件；再否则平均分配注意力。

标记重复表述：在两个或更多位置以完整列表形式重复列举同一集合，或逐字匹配的定义或规则。

第 5 步——交叉引用并分类

检查每个概念在所有出现位置是否一致。对每项发现进行分类：

🔴 冲突

不同位置对同一事实给出了不同说法。需要由人工判断。

⚠️ 过时

某处已更新，另一处尚未更新；信息来源明确。

↩️ 孤立引用

引用有效，但其目标已不存在（变量、条件、章节、文件）。

❓ 无法验证

存在差异，但上下文不足，无法判断是否构成问题。

🔁 重复

目前各副本一致，但其中一处可能引用另一处。每多一份副本，下次编辑就多一个可能遗漏的地方。

实现（模板、安装程序）通常比文档（README、注释示例）更应作为事实来源。

❓ 的判定条件。 必须指出一对明确的位置、一个明确的概念，以及要求它们保持一致的声明或指令文件规则。没有这项规则，就只是观察，不纳入结果。绝不报告：换行宽度、标题样式、章节顺序；仅存在于一个制品中的可选章节；没有声明涵盖的措辞；并列内容之间的平行结构（除非声明要求如此）。N 个同级内容会产生 N 平方种结构差异，因此，接受此类差异的层级永远无法报告干净。

🔁 的判定条件。 仅限标记为 Step 4 的概念。任何格式的枚举均符合条件（散文、表格、架构树、示例负载）。绝不报告：

• 引用完整内容的摘要
• 顺带提及的条目，或标注为示例的列表
• 无论多么接近的转述
• 声明要求逐字复制的内容
• 唯一一个镜像源代码的代码片段（第二份文档副本仍符合条件）
• 无法通过引用替代的副本：不支持链接语法的格式（JSON 清单、frontmatter），或链接规则禁止作为目标的位置。可链接文件中的代码块不计入：其值应由类型名称加引用替代

漂移优先。 标记概念的副本若不一致，只报告一个 🔴 或 ⚠️，绝不同时报告 🔁；其 Fix: 追加整合建议。声称完整但更短的列表属于 ⚠️ 已过时。

规范位置。 对每个标记概念，建议选择职责归属所在位置：指令或规范文件优先于 README，定义位置优先于使用位置，实现优先于文档。任何编辑前都须由用户确认。

git 状态的判定条件。 已提交文件指向未跟踪目标，属于 ↩️ 孤立引用：只有你能解析它。未提交的指针指向未跟踪目标，最多属于 ❓，因为两者可以一起暂存。仅未提交的目标绝不构成问题。没有 git 时，此项不在本次运行范围内，不能据此判定干净。

第 6 步 - 报告问题

跳过与 Step 2 条目相符的问题。按严重程度编号（🔴、⚠️、↩️、❓、🔁），同一等级内按对用户的影响范围从大到小排列。

每个问题的模板：

#N - [icon] [TierName]
Files: <file>, <file2>, …
<file>: <line> - <paraphrase, in your own words, of the differing concept - never quoted text>
[<file2>: <line> - <paraphrase, in your own words, of the differing concept - never quoted text>]
Fix: <concrete edit - for ❓, a confirmation question; for 🔁, the consolidation>

规则：

• 每个受影响文件占一行详情，并标出行号。不连续：<file>: <lineA>, <lineB> - …；连续：<file>: <lineA>-<lineB>。未知行号需搜索确认；没有行号时绝不输出问题。
• 无需转述的内容（悬空引用）：指出该引用，<file>:<line> - <reference> 从未定义
• ❓ Fix: 是确认问题，例如：Fix: Confirm whether the difference is intentional; if drift, align the README.
• 🔁 Fix: 必须逐字使用以下固定字符串：Fix: Keep in <file>:<line>; replace <file>:<line> with a reference.
• 对 Step 4 标记概念的 🔴 或 ⚠️：先写修正内容，再在 or: 后写相同的固定字符串，例如：Fix: Add the 4th source to the README; or: keep in SKILL.md:87; replace README.md:12 with a reference. 未标记概念不得添加 or:
• 不要使用装饰性对齐；每个冒号后仅保留一个空格。

示例（⚠️ 已过时）：

#1 - ⚠️ Outdated
Files: README.md, SKILL.md
README.md:12 - lists 3 sources
SKILL.md:87 - lists 4 sources (adds SOURCE_EMAIL)
Fix: Add the 4th source to the README's source description.

摘要行，始终放在最后，两行都要输出，即使 M=0：

Found N issues: X 🔴, Y ⚠️, Z ↩️, W ❓, V 🔁.
Skipped M intentional variations.

跳过文件说明，仅当内容签名筛选器排除了文件时才输出，并紧接在摘要上方。路径筛选排除的文件不列出：

<file>: skipped (credential signature detected)

干净结论及其依据：

No drift detected.
Declared invariants: <N> verified, 0 stale.
Concept pass: <N> concepts across <N> files.
Git: <used, or "unavailable - session context only">
Files checked: <comma-separated list>
Skipped: <comma-separated list, or "none">

只有当 Step 3 未发现任何问题，且 Step 7 的收敛循环最终判定干净时才输出；若本次运行跳过了任何步骤，则不得输出。

步骤 7 - 应用修复并管理有意差异

询问：“现在应用所有修复，还是逐项处理？”

如果用户选择“现在应用所有修复”，列出要修改的文件及每个文件的更改数量，并等待明确确认。按严重程度顺序应用，每个发现只执行一次 Edit，并注明所解决的问题。对于 🔴，以及来源不明确的 ⚠️，先确认其取值。

“现在应用所有修复”不包括 ❓ 或 🔁；它们可能是有意为之。逐项询问：“是真正的问题，还是有意为之？[修复 / 标记为有意差异 / 暂时跳过]”

选择 标记为有意差异 后，将以下内容追加到 intentional-variations.md：

- files: [file-a.md, file-b.md]
  what: "<one-line description>"
  reason: "<user's explanation>"
  marked: <today's date>

如果该文件不存在，说明这一点，然后使用以下标题创建文件：

# Intentional Variations
# Differences marked as intentional. Run `docs-consistency-check review-intentional` to revisit.

完成每项修复自身的义务

修复通常会增加契约表面（标题、声明的不变量、发出的字符串、分类条目），从而在未修改的文件中产生义务。应在同一轮中完成这些义务，否则下一轮仍会发现它们。检查每项编辑：

编辑类型	还要检查
添加或重命名了标题	指向该标题的每处引用；提及该标题的每项声明
添加了声明的不变量	“如何添加此类内容”的检查清单是否会生成它；这类不变量是否有数量声明；同级组件是否也需要相同的不变量
添加了工具发出的字符串	固定字符串或词汇声明是否列出了它
添加了清单或分类条目	规范自身的范围条款；每处公开的范围说明
更改了契约句子	集合中对该句子的每处复述
修复了多个同级组件中的一个	检查每个同级组件中的相同概念
将复述内容替换为引用	指向已删除内容的每个锚点；提及该内容位置的每项声明

只修复一个同级组件而不修复其他组件，会导致每个未修复的同级组件各自成为一个发现。

报告完成前先收敛

最后一次编辑后，针对已修改文件及其契约配对文件重新运行步骤 3 和步骤 5。修复新发现的问题，完成相关义务，然后重复，直到一轮检查无发现，再给出无问题结论。最多迭代三次：如果第四轮仍出现偏差，说明修复产生偏差的速度快于消除偏差的速度，因此应停止，报告最后一轮结果，并说明这组文件尚未收敛。

审查有意差异模式

以 docs-consistency-check review-intentional 调用时：

1. 读取 intentional-variations.md。如果文件不存在或为空：报告并停止。
2. 为每条记录编号并显示：

#1 - Marked intentional on 2026-05-03
Files: README.md, SKILL.md
What: "README says 3 sources, SKILL.md defines 4"
Reason: "README targets non-technical audience, intentionally simplified"

3. 对每条记录询问：“仍然是有意差异，还是重新作为发现处理？”
4. 删除重新开启的记录，并立即检查这些文件。
5. 保留已确认的记录。

在本次会话剩余时间内保持待命

在对话结束前，只要出现以下任一情况，就提出针对已更改文件及其契约配对文件重新审计：

• 编辑了 ≥2 个审计集文件（由用户或代为编辑）
• 文件被结构性重写或丢失一个章节
• 用户表示“完成” / “准备提交” / “看起来不错”