reviewing-api-reference

reviewing-api-reference — SKILL.md

**变体：**标准 · **适用时机：**将已完成（或修订后）的已发布 API 参考文档作为验收关卡进行评审——检查客户端开发者能否据此完成集成，以及文档是否与提交的 api-spec 契约保持一致，然后输出 VERDICT: approve|revise 和可执行的评审意见。

概述

此技能是 API 参考文档编写/评审技能对中的评审部分。评审者加载此技能时，手中持有一份已完成并发布的 API 参考文档——供集成客户端开发者阅读、以便调用 API 的面向使用者文档（入门指南、身份验证、逐端点参考、事件/Webhook、共享对象类型、分页、错误与速率限制、代码示例、API 更新日志）。此技能围绕一个问题评判该文档：客户端开发者能否仅凭这份参考文档完成身份验证、发起首次调用并集成所有操作？文档中记录的每个端点、结构和错误是否都能追溯到上游 api-spec 契约——没有偏差，也没有捏造内容？它会应用一份固定的 11 项可用性与契约一致性检查清单——与 API 参考文档作者遵循的标准相同，确保编写标准和评审标准不偏离——然后输出一个可由机器解析的单一判定，以及作者可以在一轮修订中处理的评审意见。这是一道验收关卡：它不会编写、修复或改写参考文档；它只负责评判并返回评审意见，由编写者进行修订。

最关键的一项检查是 api-spec 一致性（条件 5）：API 参考文档源自工程 api-spec 线协议契约，评审者会抽查文档中的端点、参数、结构和错误，并与提交的 api-spec 进行核对。内容偏差或捏造/无依据的端点是影响最大的缺陷类别。

何时启用

• 已完成并发布的 API 参考文档需要在面向集成开发者发布前作出接受/修订决定。
• 你是某份 API 参考文档的独立评审者/关卡把关者，该文档刚由编写者完成，并且你有上游 api-spec 可用于核对一致性。
• 在此前给出 revise 判定后，对修订版 API 参考文档重新评审。
• 评审现有参考文档的修订（上游契约变更后的差异）——采用限定差异范围的路径（条件 11）。

请勿在以下情况启用：

• 编写或修复 API 参考文档 → 使用 API 参考文档编写技能（该技能按此技能采用的同一标准编写）。此技能不会编写文档。
• 评审面向最终用户的产品指南——供使用产品的非技术人员阅读的任务帮助文档 → 使用用户指南评审技能。受众不同，标准也不同。
• 评审开发者采用/集成指南——介绍 SDK/CLI/平台用法和概念，并指向此参考文档的指南 → 使用开发者指南评审技能。该技能评判采用指南的叙述内容；此技能评判其链接到的端点目录/参考文档。
• 评审工程 api-spec——线协议契约本身（操作、完整模式、内部错误模型）→ 使用专门的关卡技能 reviewing-api-spec（通用的 design-review 会将 api-spec 工件划归该技能）。该技能审核契约；此技能评判基于该契约生成并发布、面向使用者的参考文档。
• 检查模板/章节是否符合要求 → 这是模板方面的工作。此技能评判质量是否达到标准，而不是检查是否包含每个标题。
• 评估项目正在运行的 API 实现 → 此关卡评判的是参考文档，而不是运行中的服务。

工作流

第 1 步：以全新、独立的视角通读整份参考文档，并调出 api-spec

从头到尾阅读 API 参考文档，设想自己是第一次接触该 API 的集成开发者，不受作者的框架引导。你的立场是集成开发者的把关人：只有当某项发现表明开发者无法按文档说明进行身份验证、发起首次调用或集成某项操作，或者参考文档偏离了约定时，这项发现才有分量。识别该参考文档所对应的 API 类型（精简的少量端点 API 密钥工具、涵盖多种资源的广泛平台，还是事件驱动／Webhook API）——第 2 步的比例校准取决于此。至关重要的是，加载提交的上游 api-spec：它是你的端点覆盖检查清单和一致性基准。如果未提交 api-spec，现在就记录下来——你将在第 4 步将其标记为一项假设，并根据现有材料判断可用性，因为缺少约定就无法完整执行一致性检查。对于修订，还要记录变更请求／约定变更差异——这会启用限定于变更范围的路径（条件 11）。

第 2 步：运行可用性与约定一致性检查清单——逐项判断条件

针对以下每项条件，判定为通过或存在缺口。只有存在真实且明确的缺陷时，条件才算未通过——“我会用不同方式组织这些端点”不算缺口。对于每项缺口，记录准确位置和缺失内容（第 4 步会将其转化为可执行的发现）。这些条件是统一来源的标准（api-reference 作者也以相同条件为准）；不要另设内部标准。

1. 首次调用可达。 入门指南与身份验证结合起来，让开发者能够端到端地完成身份验证并成功进行首次调用，可直接复制粘贴，且在介绍任何高级功能之前即可实现。身份验证部分要说明所用方案／流程（API key／具体的 OAuth2 流程）、获取凭据的位置和发送凭据的方式，并展示身份验证失败（401／403）的情况，而不只是成功案例。缺陷：缺少入门指南或身份验证说明；未说明方案／流程；没有失败案例；或者入门路径需要猜测才能完成一次可用调用。
2. 每项操作都有文档说明。 交付的 api-spec 中的每项操作——包括契约中声明的事件／webhook（就此条件而言，事件也算作“操作”）——都要包含以下全部内容：用途、带类型的参数（必填／可选及约束）、完整的请求示例、完整的响应示例和错误响应。缺陷：契约中的操作／事件缺失；或者文档中的操作只有 200 响应正文，没有参数／完整示例／错误说明。
3. 将错误作为一等内容处理。 统一记录一次错误响应格式（采用 Problem Details 格式的正文——RFC 9457 application/problem+json，或 API 自身统一的格式），其中包含与 HTTP 状态码不同的机器可读 code；包含状态码表（原因 + 解决办法），并使用语义正确的状态码（429 表示速率限制、409 表示冲突、410 表示已 sunset——而非笼统使用 400）；每个端点都要有错误条目。缺陷：参考文档只涵盖 2xx 成功路径；只笼统说明错误，没有针对各端点的条目；或使用了错误的状态码类别。
4. 记录速率限制。 说明限制、429 信号、Retry-After、适用时的 RateLimit-*／X-RateLimit-* 标头（注明在 429 响应中会由 Retry-After 取代）、退避和抖动，以及用于安全重试写入操作的幂等键。缺陷：会限制速率／接受写入操作的 API 未记录这些内容（不限制速率的轻量 API 可合理省略此项——参见“适度性”）。
5. 与交付的 api-spec 保持一致——不偏离、不编造。 参考文档中的每个端点、字段类型、必填／可选标记、错误代码、事件和身份验证方案都能追溯到上游 api-spec。参考文档可以补充说明文字、入门内容和完整示例；但不得重新定义、违背或凭空编造契约内容。缺陷：文档中的端点／事件未由契约声明（属于编造／孤立内容）；字段／类型／必填标记／错误／身份验证与契约矛盾；契约声明的操作缺失；或者参考文档是对生成式目录的手动重新录入副本（会造成偏离风险）。抽查文档中的端点、参数、结构和错误，并与交付的 api-spec 对照——这是关键维度；影响最大的问题是参考文档偏离契约。
6. 示例可运行。 提供 curl 和至少一种语言的示例，使用符合实际情况且与架构完全一致的值——示例若与架构矛盾（包含契约未声明的字段、错误的类型或状态码），即为缺陷。仅当存在官方 SDK 时才提供更多语言的示例。缺陷：没有可运行的示例；或示例与契约中的结构矛盾。
7. 说明版本管理和弃用。 说明版本的表示方式、开发者如何固定版本／升级、哪些情况属于破坏性变更，以及带日期的变更日志；此外，对于任何已弃用的接口，要说明弃用／日落机制（Deprecation／Sunset，日落后返回 410 Gone）以及迁移路径／指南。缺陷：对有版本管理的 API 未说明版本管理；或已弃用的端点没有迁移路径（仅有 v1 且没有任何弃用内容的 API 可合理地只提供简要说明）。
8. 每种结构只定义一次。 共享对象／数据类型集中放在核心对象部分定义，并由各端点／事件块引用，而不是在每个端点中重新定义。缺陷：可复用资源在每个端点中都重新定义（会造成偏离风险），而不是通过引用复用。
9. 内容有据可依，明确呈现缺口。 端点／事件须与 api-spec 一致；约定须符合既定实践；真实存在的缺口（例如缺少使用场景、未记录的限制）须作为明确的假设／待解决问题呈现，而不是为了显得完整而编造。缺陷：为了让内容看起来完整而编造内容，没有标明其为缺口。
10. 分页／列表操作约定（按需适用）。对于包含列表操作的 API，参考文档须在参考文档层面统一说明分页模型（游标／偏移量）、标准参数名称、响应元数据（has_more／next_cursor）、默认页大小及已记录的最大页大小、最后一页的信号，以及稳定且有平局裁决的排序（使用唯一的次级键，确保跨页排序具有确定性）。缺陷：列表端点未说明分页模型／最大页大小／有平局裁决的排序。不包含列表操作的 API 不适用此项——不要凭空制造缺口。
11. 修订——针对变更后的契约重新同步增量内容（仅适用于修订）。收到变更请求／变更契约的增量内容后，变更部分须达到要求；增量内容须重新与（现已变更的）api-spec 同步（增量内容须符合条件 5）；示例须重新同步（符合条件 6——架构变更后不能保留过时示例）；端点变更／删除时须记录弃用／迁移信息（符合条件 7）；还须更新文档自身的版本号和修订日志（与 API 变更日志区分开）。审查范围仅限增量变更——不对未变更的目录进行全面复审。首次从零构建时不适用（未提交变更请求——根据输入信号判断）。 适度原则。“开发者能否据此完成集成”取决于 API 的规模。精简的 API 可以合理地省略不需要的章节：如果没有列表操作，就不需要分页（条件 10 不适用）；等 SDK 存在后再补充 SDK／语言表格；变更日志可以从一行开始；如果 API 没有速率限制，就不需要速率限制说明；在适用之前，无需介绍 Webhook／弃用；首次构建时，条件 11 不适用。这是恰当的规模匹配，不是缺漏。评估时应看开发者能否完成集成，而不是字数或章节数。规模虽小但内容完整、满足所有适用条件的参考文档，应予通过。（无论规模如何，条件 2 和 5 仍然适用：必须包含每个契约操作／事件，且所有内容都必须能追溯到契约。）

第 3 步：判定结果

• approve — 所有适用条件均通过。客户端开发者可以按照参考文档完成身份验证、发起首次调用，并集成所有操作；所有内容也都能追溯到 api-spec。即使你能想到文风上的改进，也应予通过；标准是可用性与契约一致性，而非完美无缺，更不是内容越多越好。
• revise — 一个或多个条件存在明确的缺漏，妨碍集成（例如：缺少或未记录某项操作或事件；内容与契约不一致，或编造了契约中没有的端点；缺少入门／身份验证说明或身份验证失败情形；端点只说明了成功路径；示例与架构定义矛盾；列表 API 未说明分页；已弃用端点没有迁移路径；修订时遗漏更新，导致示例过时；内容系编造，等等）。

不要为了表示自己做过工作或索要锦上添花的内容而要求修改。一个条件要么满足，要么不满足。

第 4 步：给出判定结果和可执行的问题说明

将判定结果单独写成一行——原样输出 VERDICT: approve 或 VERDICT: revise，不得加代码围栏、引号或其他文字（此处的围栏仅用于说明）：

VERDICT: approve

然后在后续行列出问题。判定为 revise 时，每条问题说明都必须可执行——指出未通过的条件、具体位置以及修复方法，使作者能够一次性解决。判定为 approve 时，可以附上非阻塞说明；不得让这些说明暗示必须修改。

如果未提供 api-spec，请在问题说明中将此情况明确列为假设（例如：“未提供 api-spec — 一致性（条件 5）仅根据参考文档内部是否一致进行判断；请提供契约以便完整追溯”），并根据现有内容评估其他条件。不得悄然略过无法执行的一致性检查。

好的问题说明会指出缺漏及修复方法：

revise — api-spec 一致性（条件 5），“POST /v1/refunds”：参考文档记录了此端点，但提供的 api-spec 未声明 refunds 操作。修复方法：删除这个无对应契约的端点；或者，如果契约本应包含此操作，则将问题反馈给 api-spec 作者。参考文档不得编造契约中未声明的端点。

revise — 分页约定（条件 10），“GET /v1/widgets”：此列表端点记录了 limit，但未说明每页最大条目数，也未说明稳定排序时的次级排序键，因此不同分页之间的顺序不确定。修复方法：说明每页最大条目数和次级排序键（例如，先按 created 排序，再按 id 排序）。

revise — 修订（条件 11），“Charge 对象”：api-spec 新增了 currency，且文档已说明此字段，但完整响应示例和 Python 示例仍未包含它。修复方法：同步更新 Charge 示例和代码样例，加入 currency（条件 6）。

不好的问题说明既含糊又无法执行：

错误文档可以写得更全面。（哪个端点？哪些错误？如何修复？）

规则

硬性规则（绝不违反）：

• 只输出一行裁定：VERDICT: approve 或 VERDICT: revise——该字面标记必须单独占一行，行内不得有其他内容。下游工具会解析它。不得使用其他裁定措辞。
• 只评审，不撰写。 返回问题；不要改写、修复或补全参考文档。由编写者负责修改。
• 统一评审标准。 根据第 2 步的十一项条件进行评审——作者撰写时也遵循同一标准。不得自行增加条件或采用更严格的个人标准。
• api-spec-consistency 是决定性维度。 对照提交的 api-spec抽查文档中列出的端点、参数、结构、事件和错误。虚构或无对应依据的端点；与契约相矛盾的字段、类型、必填标记、错误或认证信息；参考文档缺少契约中规定的操作或事件；或手动重抄生成的目录，都是影响最大的缺陷（条件 5）。
• 不要错误地要求修改。 只要参考文档满足所有适用条件，就应批准，即便小型 API 的文档较精简也一样。只要仍覆盖契约，按比例精简不是缺陷。只有存在明确指出的实际缺口时才要求修改。API 风格补充和 Webhook 文档编写技巧是辅助参考，评审依据是最终效果（Webhook 参考文档应依据条件 2/3/5 评审，绝不能以“添加 Webhook/GraphQL 章节”为由要求修改）；渲染后文档站点的功能（搜索、交互式试用 / Postman、a11y/i18n）不在评审范围内——绝不能据此要求修改 Markdown 参考文档。
• 不要错误地批准。 不要为了迎合而忽略真实缺口。阻断性缺口必须判为 revise。
• 只涵盖成功路径属于缺口。 若某个端点只展示 2xx 响应正文，没有参数、可操作示例或错误响应，则不满足条件 2。
• 示例与架构不符属于缺口。 工作示例或代码示例使用了契约未声明的字段，或类型/状态码有误，则不满足条件 6——包括修订后仍未更新的过时示例。
• 虚构属于缺口，不是依据。 将虚构的端点、参数、状态码、事件或限制作为事实陈述，则不满足条件 9——应将真实缺口标记为假设/待确认问题。
• 缺少 api-spec 必须标明，不能默默放过。 如果没有提供契约，必须明确列为假设，并注明无法完整检查一致性（条件 5）；其余部分依据现有材料评审。
• 修订评审仅针对变更内容（条件 11）。 对修订版，检查变更部分——与变更后的契约重新同步、示例重新同步、记录弃用/迁移情况，以及更新文档版本和修订日志——而不是重新全面评审未变更的目录。全新首次构建不适用。
• 依据提供给文档的上游内容进行评审。 根据其 depends_on 集合（主要是 api-spec）评估参考文档。未提供的上游内容绝不是要求修改的理由。但如果参考文档忽略了已提供的上游内容（例如，没有反映已提交 api-spec 中的操作），则可以据此提出问题。
• 每项修改意见都必须可执行——指出未满足的条件、具体位置和明确的修复方式。不要提出含糊的意见。

偏好（可覆盖）：

• 按严重程度排列问题——先列阻断性缺口（优先列出 api-spec-consistency 不一致或虚构内容），再列较轻的问题。
• 在每项问题中注明条件编号/名称，方便作者对应评审标准。
• 批准意见尽量精简，并明确说明其不构成阻断。

容易踩坑之处

• 以内容完整为标准审批，而不是以能否集成为标准。 每个章节都可能齐全，但 API 仍然无法集成（没有可执行的首次调用、端点只展示 200 响应正文、示例与架构相矛盾）。要判断开发者能否据此完成集成，而不是模板是否填满。
• 看似一致的偏差。 参考文档和 api-spec 单独看都可能没有问题，彼此却存在出入——参考文档展示了契约中从未声明的字段、契约中删掉了某个端点，或参考文档漏掉了某个错误。发现这种问题的唯一办法，就是逐一核对文档中的端点／数据结构／错误与提交的 api-spec（条件 5）。这是危害最大、也最容易漏掉的缺陷。
• 捏造的／无契约支撑的端点。 参考文档可能记载了一个看起来合理、但契约中并未声明的端点。应逐一抽查端点索引与 api-spec 是否对应；没有契约依据的端点是缺陷，不是覆盖范围。
• 只写成功路径的端点。 只展示 200 响应正文就结束的端点条目看似完整，实际却让开发者只能靠试错来了解失败情形。每项操作都需要参数、至少一个完整示例以及错误响应（条件 2／3）。
• 示例与架构不符，包括修订之后。 curl 或代码示例使用了契约中没有的字段（或类型／状态码错误），就会悄无声息地出错。尤其在修订后，架构已更改但示例未更新，示例看起来可以运行，实际却无法运行（条件 6／11）。
• 重新手工录入生成的目录。 如果端点目录是从 OpenAPI 生成的，手工重新录入一份副本很快就会出现偏差。手动维护生成目录的副本是值得指出的偏差风险（条件 5）；生成的目录本身保持更新则没有问题。
• 主观评判分页。 条件 10 是结构性要求——对于列表 API，是否记录了模型／上限／平局时的排序规则？——而不是“分页设计是否优雅”。对于非列表 API，条件 10 不适用；不要凭空制造问题。
• 忽视缺少契约这一盲点。 如果没有提交 api-spec，就无法完整执行一致性检查——不要因此默认批准。应指出这一点（条件 5 部分无法检查），并评判其余部分。
• 系统性过度标记（误判为需修订）。 被要求找问题的审阅者容易过度纠正，把合格的参考文档判为有缺陷。应根据标准校准：只有存在明确、真实的缺陷时，才算未满足条件；不能因为内容组织方式或示例写法与你不同就判定有问题。听起来似乎合理的吹毛求疵，是审阅中最常见的错误。
• 将篇幅与 API 规模相称的参考文档误判为需修订。 对于精简的 API，精简的参考文档才是恰当的——少量端点、没有分页（条件 10 不适用）、仅一行的变更日志、没有 SDK 表格、没有 Webhook、没有弃用说明。这是篇幅适当，而不是文档不足。因篇幅短而人为制造缺陷，会导致本可避免的反复修订；应按 API 类型校准（条件 2 和 5 仍然适用）。
• 要求为 API 不具备的功能面添加章节。 仅 REST 的 API 无需 Webhook／GraphQL 章节；非列表 API 无需分页章节。这些补充要求只是编写辅助工具——应通过现有条件评判结果，绝不要强制要求某个章节（这就是凭空创造条件的陷阱）。
• 不要与 user-guide、developer-guide 或 design-review 关卡混为一谈。 此项审查针对的是已发布的开发者参考文档／端点目录。user-guide-review 审查的是面向最终用户的产品帮助文档；developer-guide-review 审查的是 SDK／CLI 的采用说明；reviewing-api-spec 则把关工程层面的 api-spec 契约。这里不要套用面向最终用户、采用说明或线级契约的标准。
• 结论标记写法不符。 “Approved”、“LGTM”、“needs work”，或埋在段落中的结论都无法解析。请单独一行输出原样的 VERDICT: approve|revise。

反模式

• 盖章式批准。 为了避免来回修改而草草浏览后就批准——放过虚构的端点、偏离契约的内容，或只有成功路径的代码块，最终会导致集成失败或在构建过程中途产生支持工单。
• 跳过 api-spec 溯源核对。 “参考文档看起来前后一致，我就批准吧”——不对照提交的契约进行抽查，就会漏掉影响最大的缺陷类别（条件 5）。这正是此关卡要禁止的捷径。
• 吹毛求疵式要求修改。 因端点排序偏好、措辞偏好，或把锦上添花的内容伪装成缺口而阻止通过。只有真正影响可用性或一致性的阻碍才应要求修改。
• 悄悄改写。 “直接修正示例反而更容易”——在评审过程中代为编写会打破产出与评判的分工，也剥夺作者了解差距并从中学习的机会。
• 凭空增加条件。 添加门槛中没有的私有要求（“还应附上 Postman 集合 / GraphQL 变体 / 交互式试用”），会导致评审门槛偏离产出门槛，并引发不必要的修改要求。只评判这 11 项条件；附加项 / DX 功能不属于评审条件。
• 追求面面俱到。 对不需要分页、多语言 SDK 矩阵、webhook 或冗长变更日志的轻量 API 提出这些要求。门槛衡量的是开发者能否完成集成，而不是参考文档是否尽可能庞大。
• 对修订内容进行完整复审。 针对变更部分，却重新评判整个未变更的目录，而不是遵循限定于变更范围的流程（条件 11）——既浪费时间，也不符合协议。
• 含糊其辞的结论。 “大体批准，但……”或给出两行结论。必须且只能给出一个决定，并且只能包含一个标记。

输出

对一份已发布（或已修订）的 API 参考文档给出单一评审结果：

• 一行结论——单独一行逐字写出 VERDICT: approve 或 VERDICT: revise。
• 问题项——若结论为 revise，每个阻碍项各给出一条可执行的问题说明（未通过的条件 + 位置 + 具体修复方法）；若结论为 approve，可选择提供非阻碍性备注。

当前待评审的参考文档是文本形式——包含端点章节、围栏请求 / 响应示例，以及围栏代码样例（通过本地文档后端提供的 Markdown）；评审方法与门槛独立于媒介（未来渲染后的文档网站只会改变媒介——搜索 / 试用 / 无障碍 / 国际化由该网站负责——不会改变评判标准）。抽象消费者是负责协调产出 -> 评审循环的任何组件：approve 表示接受该 API 参考文档，供开发者集成时使用；revise 则将问题项返回给产出方，供其进行有范围限制的修订。

相关内容

• api-reference-authoring 技能（authoring-api-reference）——这组技能中负责产出的部分；它编写的参考文档遵循与本技能评判时相同的 11 项可用性 + 契约一致性门槛。将二者配对使用，可以确保门槛只有一个来源，避免产出与评审的门槛发生偏移。
• 上游 api-spec（authoring-api-spec）——工程线缆契约，参考文档中的每个端点、字段、事件和错误均由其派生；此关卡会检查参考文档是否与提交的 api-spec 一致（条件 5）。api-spec 本身在工程阶段由 reviewing-api-spec 把关，不属于此处的评审范围。
• user-guide-review 技能——用于把关面向最终用户的产品指南（供使用产品的非技术人员阅读）。文档类型 / 受众不同。
• developer-guide-review 技能——用于把关 SDK / CLI / 平台的采用与集成说明，说明中会链接到这份参考文档。文档类型 / 门槛不同；本技能评判的是它所链接的端点目录。
• design-review 技能——用于把关通用工程设计文档（规格说明 / 计划 / RFC / ADR）。上游的工程 api-spec 线缆契约有专门的把关技能 reviewing-api-spec（design-review 不涵盖该内容）。关卡 / 产物不同；它不适用于已发布、供使用者阅读的参考文档。
• api-reference template / content-template 工具——负责章节的结构；本技能评判的是质量是否达到门槛，而不是结构是否符合要求。

渐进式披露

• references/usability-consistency-bar.md — 各条件的通过／缺口信号，以及针对新增和深化条件的具体发现示例（认证流程深度、Problem Details 错误、RateLimit／幂等性、弃用／日落、分页条件 10、限定差异范围的修订条件 11）。需要了解某个条件的详细信号时再加载。
• references/sources.md — 审查方法和单一来源标准的研究溯源。仅在需要审查指导依据时加载。

正文篇幅限制

• description 不超过 1,024 个字符（agentskills.io 上限）。在列表中，Claude 会将 description 和 when_to_use 的总长度截断至 1,536 个字符。
• 正文不超过约 500 行／5,000 个 token——每轮都会保留在上下文中。
• 每个参考文件：超过 10k 个 token 时警告，超过 25k 个 token 时错误。参考文件总计：超过 25k 个 token 时警告，超过 50k 个 token 时错误。

更新日志

• 1.1.0（2026-06-14）——生产级重构（增量式；与 authoring-api-reference 的 Step-6 自检采用单一来源）。标准从 9 个增至 11 个条件：新增 条件 10 分页／列表操作约定（按需适用）和 条件 11 限定差异范围的修订（由输入信号触发，绿地项目不适用）；深化条件 1（认证流程深度）、条件 3（RFC 9457 Problem Details + 机器可读代码）、条件 4（RateLimit-*／抖动／幂等性）、条件 7（Sunset／Deprecation 机制 + 迁移）；条件 5 的条件文本保持原样（关键内容），并深化检查方法（SSoT／契约测试，不手动重新输入目录）；条件 2 现在包含契约声明的事件／webhook。API 风格补充说明和 webhook 文档技巧仍作为辅助内容，按结果评判；渲染媒介的 DX（搜索／试用／无障碍／国际化）明确排除。新增 references/usability-consistency-bar.md；sources.md 调整为可移植版本。VERDICT: approve|revise + 输入契约保持不变。
• 1.0.0（2026-06-05）——初次审查发布。