authoring-api-spec

authoring-api-spec — SKILL.md

变体： standard · 适用场景： 编写 API 接口的工程线级契约，达到仅凭契约，客户端即可集成、服务端即可实现的标准，且对数据结构、错误或身份验证均无歧义。

概述

此技能介绍如何编写高质量的 API 规范，即 API 接口的工程线级契约。它说明每个操作在线上的形式：请求和响应的数据结构（字段、类型、必填/可选、约束）、身份验证模型、错误模型及完整示例。此技能承载的是编写者的判断力——研究方法和质量标准，而非章节列表。它假定有两位协作者：负责提供章节结构的 api-spec template tool，以及用于依据成熟 API 设计实践夯实契约的深度研究能力。编写者会收到上游 feature-spec（API 必须暴露的行为），以及可能提供的 architecture-doc（服务边界）和 data-model（资源所映射到的实体）——绝不是一张白纸。必须达到的标准是：契约可实现、可调用——客户端工程师能够正确调用每个操作，服务端工程师能够据此实现，且无需询问作者；数据结构、错误或身份验证均无歧义。

何时启用

• 根据已批准的 feature-spec 编写 API 规范，其中列明 API 必须暴露的行为。
• 说明 API 接口的操作、请求/响应架构、身份验证、错误模型和示例（REST、GraphQL 或 RPC/gRPC）。
• 填写 api-spec 模板，其中的每个操作都包含经过研究、决策完备且类型完整的内容。
• 修订已批准的 api-spec，并将其作为有版本记录的增量变更（新增/修改操作、添加/移除字段、将参数设为必填、停用操作）——参见步骤 6。

请勿在以下情况启用：

• 设计持久化数据模型（存储的实体及其关系）→ 这是独立事项，且属于本技能的上游。api-spec 描述线上的 DTO，并引用数据模型；DTO 并非存储的行。
• 编写面向使用者发布的 API 参考文档（最终用户阅读的说明文档，通常由此契约生成）→ 这是独立的下游文档，面向不同的受众。
• 编写实现/架构（端点背后的服务如何构建）→ 这是设计层，不是接口。
• 审查或评定已完成的 api-spec → 使用 reviewing-api-spec（专用质量关卡，与本技能步骤 7 的标准同源）；本技能仅用于产出。
• 编写 feature-spec 本身（即行为）→ 这是本技能的上游输入。

输入

阅读计划交给你的每一份文档——即你的 depends_on 集合（由上游文档发现流程确定、能够为本文档提供信息的文档）——并将本文档的内容追溯到这些文档。不要假设输入固定不变：此技能提到的典型上游文档是方法指导，不是对你收到的文档数量设定上限。要做到自成一体——根据你实际收到的任何上下文来编写文档；如果缺少预期的参考文档，就基于现有内容继续，并将缺失之处明确列为假设，绝不要编造内容来填补。并且，只要有研究能力可用，就使用它（deep-research），让文档全面且详尽，而不只是填充模板。

能力上下文（如有提供）： 如果调用方注入了 capability_record（来自 capability-map.yaml product_capabilities 的记录），请在步骤 1 前阅读它。它定义了你的范围边界：owns = 你负责的实体；refs = 你引用但不负责的实体；publishes/consumes = 你要呈现的事件；entry_points/exit_points = 用户进入和离开的方式；has_ui/has_api/has_persistence = 适用的界面。若存在此记录，必须将其视为硬性约束——不得超出其定义的范围。

工作流

步骤 1：从模板工具获取结构——不要自行编造大纲

从 api-spec 模板工具（全面版）获取章节结构。不要在此重述或重新推导章节列表；此技能提供的是如何妥善填充这些章节的方法。如果没有可用模板，请获取一份全面的 api-spec 结构（请求生成，或采用以下规范章节：API 概览、操作列表、各操作的请求与响应、共享数据类型、身份验证与授权、错误模型、分页/筛选/速率限制、示例、待解决问题），然后继续。

如果存在 capability_record：将 entry_points 作为 API 操作公开；为 publishes/consumes 事件纳入异步操作；将 refs 字段标记为只读的跨能力引用。

步骤 2：先选择 API 风格——然后以该风格的表示法采用同等严格程度

项目只采用一种 API 风格。先选定一种，再用该风格的表示法呈现契约；但三种风格的严格程度（类型化架构、完整错误、身份验证、示例）都相同：

• REST → OpenAPI/JSON-Schema 规范：端点表（方法 + 路径）、类型化参数和请求体、按 HTTP 状态码列出的响应、可复用架构、声明的安全方案。
• GraphQL → SDL：类型化的对象/标量/枚举/输入类型、Query/Mutation/Subscription 根字段，以及顶层 errors 数组中的错误。
• RPC / gRPC → proto service/rpc 方法签名，以及类型化的请求和响应消息、状态码。

不要强制非 REST 项目采用 OpenAPI——OpenAPI 是 REST 风格，不是唯一格式。此技能教授的是适用于项目所用风格的契约严格性。

步骤 3：加载上游文档；依据 feature-spec 确定覆盖范围

阅读已批准的 feature-spec 及任何上游上下文（architecture-doc、data-model）——它们是你的输入，不是空白页。feature-spec 中的行为是操作覆盖清单：API 必须公开的每项行为都要对应一个或多个操作；每项操作都必须追溯到某项行为（不得出现无依托或凭空编造的端点）。通过引用将每项资源映射到 data-model 的实体——注明传输 DTO 与存储实体之间的差异（计算得出、派生或省略的字段）；不要重复或违背 data-model。如果上游信息不足，请将缺口明确列为待解决问题或注明为假设，绝不要默默编造结构。

步骤 4：通过研究夯实契约

开展深入研究，依据成熟的 API 设计实践夯实契约，包括 REST/HTTP 语义和状态码、JSON-Schema/OpenAPI 严谨性、GraphQL SDL、RPC/gRPC、一致的命名、错误建模（例如 REST 的 RFC 9457 Problem Details）、版本管理和身份验证模式；研究应针对本产品的 API 范围，而非泛泛讨论“API 规范”。如果没有研究能力，切勿捏造字段名、限制、状态码或错误码——应将其明确标记为待验证的假设，并在构建前进行验证。

步骤 5：按各部分的方法执行

按照此方法填写模板的各个部分。精简轻量 API 不需要的部分，并按实际需要分配篇幅。

• API 概览 — 说明 风格 + 传输方式、基础 URL/端点，以及明确的 版本控制方案（URL 路径 /v1 最清晰明确且最常见——仅按主要版本号划分，遵循 AIP-185；从一开始就规划版本控制）。在此一次性说明命名和日期/时间约定。
• 版本控制政策——对变更分类 + 规划弃用（从第一天起就说明）。说明 哪些情况算作破坏性变更：增量变更 = 新增一个可选字段/操作/枚举值，兼容宽容读取的客户端会忽略该内容（客户端必须忽略未知响应字段）；破坏性变更 = 移除/重命名/缩窄类型/新增必填项/更改默认值/语义变更（AIP-180 中的源代码/线缆格式/语义变更）。并说明移除操作的 弃用 → 终止生命周期：Deprecation（RFC 9745，即开始弃用的日期）→ 迁移窗口 → Sunset（RFC 8594，即可能停止响应的日期；Sunset ≥ Deprecation）+ 已发布的迁移路径。此处说明的是 政策；在变更中弃用某个具体操作这一 行为 属于步骤 6（修订）。
• 资源/操作列表 — 预先为每项操作列出一行（方法+路径 / 根字段 / Service.Method），以便在查看每项操作的详细信息前快速浏览接口范围。
• 每项操作的请求 + 响应——两侧都要完整指定类型。 每个参数/实参/字段都要包含 类型、必填/可选标记和约束（长度、枚举、格式、范围）。每种响应都要对应一个 状态码（或 gRPC 状态 / GraphQL 数据与错误），并注明其正文架构。审慎选择状态码——创建时使用 201 + Location，无正文成功时使用 204，区分 401（未认证）和 403（禁止访问/权限范围不足），冲突时使用 409，验证失败时使用 422/400；不要所有情况都用 200。只说明成功路径的操作 尚未完成。
• 共享数据类型 — 每种可复用 DTO 只定义 一次，并按名称引用（$ref / SDL 类型 / proto 消息）；不要在不同操作中重复内联定义相同结构。这些是 线缆格式类型——如果某个 DTO 是存储实体的投影，请引用数据模型，不要重复描述。
• 身份验证 + 授权 — 指明方案（API 密钥 / OAuth 2.0 + 具体流程——面向用户/公共客户端使用授权码 + PKCE，服务间通信使用客户端凭据 / JWT / mTLS）、凭据的传递位置，以及 授权模型：每个非公开操作都要注明所需的范围/角色，并与操作列表中的授权范围列对应（只写“已认证”而不逐项注明授权范围是不完整的）。说明令牌生命周期 + HTTPS + 不得将密钥放在 URL 中。
• 错误模型——错误目录，而不只是成功路径。 为整个 API 定义 一种统一的错误结构（例如 REST 使用 RFC 9457 Problem Details；GraphQL 使用 errors 数组；gRPC 使用 google.rpc.Status），其中包含 机器可读代码（客户端据此分支处理——HTTP 状态码粒度太粗）、人类可读消息（供日志使用，不用于面向终端用户的显示）和 请求/跟踪 ID。然后逐项 列出每个操作的所有命名失败情形（验证失败、身份验证失败、禁止访问、未找到、冲突、速率受限、服务器错误），并注明其状态码 及是否可重试（429/5xx 可在遵循 Retry-After 并采用退避策略后重试；4xx 不可重试——重试无济于事）。这是 API 规范中最常被遗漏的部分——请认真处理。
• 分页 / 筛选 / 排序 / 速率限制 — 对于集合操作，选择一种分页策略（大型/动态/面向用户的集合使用基于游标的分页；小型/静态集合使用偏移分页），定义请求参数 + 响应封装（下一个游标 / 是否有更多 / Link 标头）+ 默认/最大页面大小；列出可筛选和可排序的字段，并指定稳定的平局判定字段；说明速率限制 + 相关标头 + 429 的处理方式。
• 完整示例 — 每项主要操作至少提供一组完整的请求/响应示例，且与架构一致（字段名、类型、状态码均相同）。示例与架构矛盾即为缺陷。

步骤 6：修订已批准的契约（增量变更场景）

如果契约已存在，且有人提出变更，只修改增量部分，不要重画整个契约。范围 = 受影响的操作 + 其请求/响应架构 + 共享类型 + 相关错误情况（如果变更具有破坏性，还包括版本控制部分）。然后：

1. 对变更分类——增量变更还是破坏性变更。 增量变更（新增可选字段、新增操作、容错读取方会忽略的新增可选响应字段、新增可选错误情况）在当前版本中发布。破坏性变更（移除/重命名字段或操作、收窄类型、将可选字段改为必填、变更默认值/语义、移除枚举值）不得在同一版本中原地修改。作为小幅的版本内编辑发布破坏性变更，会悄然破坏所有正在运行的客户端——这是修订契约时最严重的缺陷。
2. 破坏性变更属于版本变更事件，而非编辑。 将其转到新版本（/v2、新的日期固定版本），并让旧接口走完弃用 → 停用生命周期（Deprecation → 迁移窗口 → Sunset，Sunset ≥ Deprecation），同时提供迁移指南（旧版→新版映射）。绝不能悄然修改或删除旧操作。
3. 分析向后/向前兼容性——向后兼容：现有版本继续可用；向前兼容：新字段设为可选/提供默认值，允许新增枚举值，操作的含义绝不悄然改变。
4. 为增量变更更新版本和变更日志——递增文档自身的版本（§10 修订历史，与 API 版本不同），并添加变更日志条目（增量/破坏性）；将退役操作标记为已弃用，而非悄然删除。
5. 指出对下游/上游的连锁影响——该变更会影响下游的 api-reference（根据变更后的契约和弃用标记重新同步/生成）、基于该契约构建的实现和测试计划、正在运行的客户端（这正是需要停用窗口的原因），以及发布运行手册；必须先修订上游的 feature-spec（新行为会促成新操作）。明确指出这些影响；不要让下游读者自行发现。

全新项目的首份契约可跳过步骤 6（没有之前的版本需要修订）。

步骤 7：交付前对照无歧义标准进行自检

确认以下各项均满足（这是运行时审查门禁 reviewing-api-spec 的审核标准；作者和门禁共用此标准，以免标准出现偏差）：

1. 已说明风格、基础信息和版本控制 — 已提供 API 风格、基础 URL/端点和具体的版本控制方案；已说明破坏性与非破坏性变更规则，以及弃用→停用政策。
2. 已列出并追踪每项操作 — 操作列表完整；每项操作都对应上游功能规范中的行为（没有无依据或臆造的端点，也没有遗漏）。
3. 已完整定义每项操作的请求和响应类型 — 请求和响应均已完整定义类型，每个字段都标明必填/可选及约束，每个响应都对应一个状态码。只定义成功路径的操作不合格。
4. 身份验证和逐项操作授权 — 已说明身份验证方案（以及适用于每种客户端类型的 OAuth 流程）；每项非公开操作都注明所需的范围/角色；已说明令牌生命周期和 HTTPS；没有任何操作默认开放。
5. 错误模型完整 — 错误格式保持一致（机器可读代码、消息和请求 ID），并且按操作列出所有命名的失败情形及其是否可重试。只列出 2xx 响应的规范不合格。
6. 共享类型只定义一次并通过引用使用 — 可复用 DTO 只定义一次并通过引用使用；传输类型引用数据模型，而非重复陈述或与之矛盾。
7. 已规定分页和速率限制 — 集合操作定义了分页；已说明速率限制和标头。
8. 示例齐备且一致 — 每项主要操作至少提供一组请求/响应示例，且与架构完全一致。
9. 命名和版本控制保持一致 — 在整个 API 表面统一应用。
10. 有依据、诚实且单向 — 操作和结构反映功能规范和数据模型（并非臆造；缺口应作为假设/开放问题列出，而非凭空补全）；与 api-reference 保持单向关系（本契约是已发布参考文档的事实来源；绝不能从后者反向推导）；如果存在实时 API，对当前操作/结构的描述必须与已发布的 API 表面一致（全新开发：不适用）。
11. （仅修改时）变更范围明确、分类清楚且已版本化 — 对于变更请求：变更涉及的操作满足第 1–10 条；变更已分类为增量或破坏性；破坏性变更包含新版本、弃用→停用计划和迁移指南；已分析向后/向前兼容性；已标明向前/向下游的连带影响；文档版本已更新，并附有变更日志；已退役的操作标记为弃用，而非删除。对于全新开发的首次构建：不适用。

输入不足门禁： 如果 API 必须公开的某项行为无法通过研究确定，也无法有依据地纳入契约，则应将其列为阻塞项（“操作定义不足 — 需要产品/工程决策”），而不是臆造结构。如果 api-spec 中的结构、错误和身份验证全是猜测，就无法据此调用。

规则

硬性规则（绝不违反）：

• 每项操作的两端都要注明类型。 请求和响应都必须完整注明类型，明确每个字段是必需还是可选，并注明约束；每种响应都必须对应一个状态码。字段未注明类型或状态未注明，都不算完成。
• 列举所有错误情况。 每项操作都要列出失败情况（验证、身份验证、未找到、冲突、速率限制、服务器错误）及状态码，不能只写成功路径。仅包含成功路径的操作是不完整的。
• 错误格式保持一致。 整个 API 共用一种错误响应格式（机器可读代码 + 消息 + 请求 ID）；不要为每个端点设计不同的错误响应体。
• 引用数据模型，不要重新定义。 线上的 DTO 通过引用映射到上游数据模型中的实体；注明差异。绝不要重述或违背已存储的架构。DTO 不等同于已存储的行。
• 与 api-reference 保持单向关系。 已发布的、面向使用者的 api-reference 是此契约的下游使用者，通常由契约生成。此契约是 api-reference 的事实来源；绝不要根据已发布的文档反向推导契约（那会颠倒依赖关系）。数据模型是上游，api-reference 是下游。
• 破坏性变更要发布新版本，不能原地修改。 修订时，区分新增变更与破坏性变更；破坏性变更要迁移到新版本，并遵循 Deprecation→Sunset 生命周期，提供迁移路径；绝不要在同一版本下悄悄修改或删除仍在使用的操作（步骤 6）。
• 每项操作都要追溯到 feature-spec 中的行为。 不得有孤立或臆造的操作，也不得遗漏行为。覆盖范围以 feature-spec 为准。
• 严谨性不依赖风格，也不局限于 OpenAPI。 使用项目所选风格的表示法（REST 用 OpenAPI，GraphQL 用 SDL，RPC 用 proto）；无论风格如何，都要保持同等严谨。不要强行将 OpenAPI 用于非 REST API。
• 示例必须符合架构。 每个示例都必须使用架构声明的确切字段名称、类型和状态码。示例与架构矛盾即为缺陷。
• 绝不捏造。 不要为了看起来完整而臆造字段名称、限制、状态码或错误代码。没有来源时，应将其明确标记为待验证的假设，并在构建前验证。
• 组合，不要重复。 章节结构采用模板工具中的结构；本技能负责填充内容。不要另行粘贴一套大纲。
• 写契约，不写实现，也不写已发布的参考文档。 规定接口（线上数据格式），而非服务的构建方式，也非面向最终用户的说明文字。
• 能力边界（提供了 capability_record 时）。 文档输出范围必须限定在该记录的边界内。产出边界之外的内容（例如将 refs 实体当作自有实体来描述，或设计超出 exit_point 的流程），即属越界，等同于臆造规格中不存在的内容。

偏好（可覆盖）：

• “全面”指提高输出的目标，但仍要适度：契约要完整（每项操作都有类型、错误情况齐全、注明身份验证），而非追求篇幅。精简的 API 应省略不需要的章节。
• REST 错误响应体优先采用 RFC 9457 Problem Details；大型或动态集合优先采用基于游标的分页。
• 除非项目已采用基于请求头或日期的版本规范，否则优先使用 URL 路径版本控制（/v1）。

易错点

• 仅考虑成功路径的操作。 只指定 200 响应体就结束，是 API 规范中最常见的缺陷。每个操作都必须列出 4xx/5xx 失败情况及其状态码——错误目录是契约的一部分，不是事后补充的内容。
• 将数据模型重新定义为 DTO。 在行内重新定义已存储实体，会偏离（并与）上游数据模型矛盾。应引用数据模型；只说明线路格式不同之处（计算得出／派生／省略的字段）。
• 混淆契约与已发布的参考文档。 这是构建所依据的工程契约；面向使用者的参考文档（通常由它生成）是另一个下游文档，面向不同受众。不要在这里编写面向最终用户的说明文档。
• 只盯着 OpenAPI。 将 OpenAPI 用于 GraphQL 或 gRPC API 并不合适。选择项目的一种风格，并使用对应的表示法（SDL／proto）。
• 与架构不一致的示例。 示例中出现架构未声明的字段（或类型／状态错误），会在不知不觉中破坏契约。示例必须与声明的结构保持一致。
• 重复模板大纲。 在内容（或此技能）中重新列出章节，会与模板工具重复并逐渐偏离——应结合判断填写模板中的章节。

对照示例——表面合规但规格不足 vs 可调用（用于自检）：

方面	规格不足（拒绝）	可调用（可交付）
操作追溯	“有一个用于发票的端点。”	“POST /v1/invoices 实现功能规格 §3.2 创建发票；映射 Invoice 数据模型实体（省略 internalLedgerId）。”
请求	“接收发票字段。”	“请求体：amount（整数，必填，>0，以最小货币单位计）、currency（字符串，必填，ISO-4217）、dueDate（字符串，可选，RFC-3339）。”
响应	“返回发票。”	“201 → Invoice 架构（第 4 节）；Location 标头设为新资源。”
错误模型	“会返回错误。”	“400 validation_error（字段无效）、401 unauthorized、403 forbidden（缺少 invoices:write）、409 conflict（幂等键重复）——全部采用共享的 Problem-Details 结构。”
身份验证	“需要身份验证。”	“OAuth 2.0 bearer；需要 invoices:write 作用域。”
示例	“参见文档。”	“请求／响应示例使用 amount: 5000、currency: \"USD\"；201 响应体与 Invoice 架构完全一致。”

如果你填写的内容读起来像左栏——适用于任何 API、没有类型、没有状态码、没有错误情况——那就还没完成。

反模式

• “我会只规范成功路径；错误情况显而易见。” 并非如此——必须逐一列出失败情况及其状态码，否则客户端无法处理。
• “我会将实体重新定义为请求／响应结构。” 应引用数据模型；重复定义会偏离并与之矛盾。只说明线路格式的差异。
• “OpenAPI 是标准，我会用它规范所有内容。” OpenAPI 是 REST 风格；GraphQL API 需要 SDL，gRPC API 需要 proto。应与项目风格保持一致。
• “这也是 API 参考文档，所以我会写面向最终用户的说明。” 契约和已发布的参考文档面向不同文档类型和受众；应将此文档保持为工程契约。
• “我会自己写大纲。” 这会与模板工具重复——使用模板工具提供的结构。
• “跳过调研，我懂 REST。” 调研的依据是此产品的接口、命名和错误模型，而不是 API 理论。
• “改动很小，我会直接修改字段。” 在相同版本中进行破坏性更改（重命名／删除／收窄类型／新增必填字段）会在不知不觉中破坏所有正在使用的客户端——应对其分类，安排到新版本，并采用包含迁移指南的 Deprecation→Sunset 生命周期（步骤 6）。

输出

一份全面的 API 规范，满足第 7 步无歧义标准（已说明风格、基础规范、版本控制［以及破坏性变更规则和弃用／停用政策］；列出每项操作，完整追溯，并完整定义请求和响应两侧的类型及状态码；指定身份验证和各项操作的授权；提供完整的错误模型，列明每种失败情况并注明是否可重试；共享类型只定义一次，并引用数据模型；说明分页和速率限制；示例齐全且前后一致；命名和版本控制一致；以 api-reference 为依据且仅朝一个方向流动；不捏造内容）——如有变更，以带版本号的增量修订形式修订（第 6 步：将变更分类为增量式／破坏性，破坏性变更转入新版本，并遵循弃用→停用流程，同时标明影响范围）。产物为文本形式——端点表格、带围栏的模式代码块（JSON / OpenAPI 片段 / SDL / proto）以及请求／响应示例对；方法和标准不依赖媒介。抽象使用者包括依照契约进行集成的客户端工程师、负责实现契约的服务端工程师、通常根据契约生成下游已发布 api-reference 的人员，以及 reviewing-api-spec 把关流程（该流程验证同一标准）。api-spec 依赖 feature-spec（并引用 data-model）作为输入。其结构由模板工具提供；此技能负责保证内容质量。

相关内容

• api-spec 模板工具（例如内容／模板网关）——提供此技能要填充的章节结构。与其组合使用；切勿重复其提纲。
• 深度研究能力——以成熟的 API 设计实践（REST/HTTP、OpenAPI/JSON-Schema、GraphQL SDL、gRPC、错误建模、版本控制、身份验证）为契约提供依据。
• feature-spec 编写技能——产出上游 feature-spec，其所定义的行为由此契约对外呈现。
• 架构文档和 data-model（如有）——提供上游背景：服务边界，以及传输 DTO 引用的实体。
• reviewing-api-spec——专门用于评审最终 api-spec 的把关流程；它验证同一无歧义标准（其条件与此技能第 7 步的自检项逐项对应，且仅有一个事实来源），确保作者和把关流程的标准不偏离。（通用的 design-review 会将 api-spec 产物交由此对应流程评审。）
• 面向使用者的 API-reference 技能——生成下游已发布参考文档，与此契约是不同的文档，且通常由契约生成。

渐进式披露

• references/contract-method.md——深入介绍契约主干：风格选择＋操作／方法语义（RFC 9110）＋状态码选择＋请求和响应两侧的类型＋完整错误模型（RFC 9457＋机器码＋可重试性）＋身份验证／各项操作的授权＋分页／平局判定规则。在填写某一章节需要具体操作细节时加载。
• references/versioning-and-amend.md——深入介绍版本控制和演进：方案（URL 路径／请求头／基于日期，AIP-185）、破坏性与非破坏性变更分类（AIP-180）、弃用→停用生命周期（RFC 9745/8594），以及第 6 步修订方法和向前／向下的影响范围。在进行版本控制或修订时加载。
• references/sources.md——方法和质量标准的研究出处（OpenAPI、JSON Schema、GraphQL SDL、gRPC/protobuf、RFC 9110/9457、RFC 8594/9745、AIP-180/185、REST 设计及错误／分页指南）。仅在核查指导依据时加载。

正文篇幅预算

• description ≤ 1,024 个字符（agentskills.io 上限）。
• 正文约 500 行／5,000 个 token（软性目标——质量优先；若持续超过 700 行／7,000 个 token，则标记）。
• 大量内容放在 references/ 中，按需加载。

更新日志

• 1.3.0（2026-06-21）— capability_record 上下文注入：可选的调用方注入 capability_record，在步骤 1 中使用（范围边界来自 entry_points/publishes/consumes/refs）；新增 capability_boundary 规则；放宽正文预算，改为目标值。未注入记录时优雅回退。
• 1.2.0（2026-06-15）— 重构为面向生产环境的配套技能（与全新推出的 reviewing-api-spec 配套版本共用单一来源）。新增修订方法（步骤 6：将变更归类为增量式或破坏性 → 破坏性变更需创建新版本，并遵循 Deprecation→Sunset 生命周期 → 兼容性 → 版本号 + 更新日志 → 对 api-reference/impl/clients 的上游/下游连锁影响）。深化版本管理（破坏性与非破坏性变更分类 + 弃用→日落策略、AIP-180/185 + RFC 8594/9745）、逐操作授权（每个非公开操作都要注明其权限范围 + 按客户端类型指定 OAuth 流程）、错误模型（机器可读代码 + 请求 ID + 是否可重试）、状态码选择以及单向性与 api-reference 的规则。将自检扩展至步骤 7（深化 cond-1/4/5/10 + 新增 cond-11 修订）——与配套版本的 11 项条件逐项保持一致。将关卡引用重新指向 reviewing-api-spec。新增 references/contract-method.md + references/versioning-and-amend.md。未删减此前的任何覆盖内容。
• 1.1.0（2026-06-04）— 初始审核版本。