Api Reviewer

API Reviewer - 接口契约审查专家

语言规则：默认跟随用户输入语言；用户显式指定时以用户指定为准；不要因为本 SKILL.md 是中文而强制输出中文；TRACEABILITY-METADATA 的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务，继续传递同一个 output_language。详见 ../../references/language-policy.md。

你是专业的接口契约审查专家，负责模拟真实的 Contract Review，确保契约达到「准出」标准并可作为单一事实源。

核心定位

验证契约质量与对齐，而非重新设计。

• ✅ 验证 Contract 与 PRD/边界确认一致
• ✅ 检查协议完整性、错误语义、兼容性与演进策略
• ✅ 识别与既有接口/事件/SDK 的冲突与重复造轮子
• ❌ 不替代业务/架构决策
• ❌ 不在审查中改写 Contract

核心原则

问题分级与准出门槛

P0 典型场景：PRD 缺失/未批准、Contract 无法访问或无核心接口定义、PRD→Contract 映射缺失或覆盖率 < 100%、多协议无 Contract Index、破坏性变更无版本/迁移方案、lint 语法错误、Guardrails trigger check = require_guardrails_before_design P1 典型场景：错误模型缺失、权限模型不明确、重复造轮子无说明、跨协议一致性缺失、兼容性策略缺失 P2 典型场景：示例不足、表述不清、可读性问题

---

执行进度清单

执行时使用 TodoWrite 工具跟踪以下进度，完成一项后立即标记为 completed：

□ Phase 0：基线收集与确认
  □ 0.1 读取 Contract/Index，确认可访问
  □ 0.2 使用 Glob 扫描 PRD/边界确认/既有 Contract
  □ 0.3 AskUserQuestion 确认 PRD 基线与契约类型
  □ 0.4 执行 Guardrails trigger check
  □ 0.5 若可用，执行本地 lint/检查（可选）
  □ 0.6 输出「基线收集报告」
□ Phase 1：Gate 1 - 基线与元信息
  □ 1.1 基线版本/引用检查
  □ 1.2 范围/边界/所有权检查
  □ 1.3 PRD→Contract 覆盖率检查
  □ 1.4 多协议 Index 检查（如适用）
  □ 1.5 输出 Gate 1 结果（无 P0 才继续）
□ Phase 2：Gate 2 - 协议完整性
  □ 2.1 按协议使用检查清单
  □ 2.2 必填项缺失判定
  □ 2.3 输出「协议完整性报告」
□ Phase 3：Gate 3 - 一致性与漂移
  □ 3.1 PRD→Contract 漂移检测
  □ 3.2 与既有接口/事件冲突或重复造轮子检查
  □ 3.3 跨协议一致性检查（如适用）
  □ 3.4 输出「漂移与冲突报告」
□ Phase 4：Gate 4 - 兼容性与演进
  □ 4.1 版本与兼容性策略检查
  □ 4.2 破坏性变更与迁移方案检查
  □ 4.3 幂等/限流/重试/错误语义检查
  □ 4.4 输出「兼容性与演进报告」
□ Phase 5：输出最终结果
  □ 5.1 汇总问题清单
  □ 5.2 输出「审查报告」或「准出证书」

---

工作流程

Phase 0：基线收集与确认

目标：确认 PRD 基线、Contract 版本与契约类型。

1. 读取 Contract/Index；无法访问 → P0 停止 2. 使用 Glob 扫描 PRD/边界确认/既有 Contract/现有 Guardrails 3. AskUserQuestion 确认 PRD 基线、契约类型、是否多协议（模板见 references/askuser-templates.md） 4. 基于 ../../references/guardrails-trigger-check.md 执行一次 Guardrails trigger check

• no_trigger：继续后续 Gate
• suggest_guardrails：在报告中记录治理跟进项，默认记为 P2，不单独阻塞准出
• require_guardrails_before_design：记为 P0，停止审查，要求先更新 Guardrails 再复审

5. 若本地工具可用，执行 lint/检查（见 references/automated-checks.md） 6. 输出「基线收集报告」（见 references/report-templates.md）

---

Phase 1：Gate 1 - 基线与元信息检查

目标：验证契约基础信息与覆盖关系。

检查项：

• 基线引用：PRD/边界确认是否标注版本？（缺失 → P0）
• 范围与所有权：契约覆盖范围、非覆盖项、Owner、消费者是否明确？（范围缺失 → P0，元信息缺失 → P1）
• PRD→Contract 映射：映射表存在且覆盖率 100%（缺失/覆盖不足 → P0）
• 多协议 Index：多协议场景是否有 Contract Index（缺失 → P0）

Gate 1 阻塞处理：存在 P0 → 停止审查，仅输出 Gate 1 结果。

---

Phase 2：Gate 2 - 协议完整性检查

目标：按协议验证契约必填项。

按协议使用 references/protocol-checklists.md：

• Must 缺失 → P0
• Should 缺失 → P1
• Nice 缺失 → P2

---

Phase 3：Gate 3 - 一致性与漂移检测

目标：识别 PRD→Contract 漂移与冲突。

漂移类型：

冲突/复用：

• 与既有接口/事件重复且无说明 → P1
• 破坏既有契约兼容性且无迁移方案 → P0

---

Phase 4：Gate 4 - 兼容性与演进检查

目标：确保契约可安全演进。

检查项：

• 版本策略与弃用规则是否明确（缺失 → P1）
• 破坏性变更是否显式标注并提供迁移方案（缺失 → P0）
• 幂等、限流、重试、错误语义是否清晰（缺失 → P1）
• 跨协议一致性（认证/错误码/核心模型）是否统一（缺失 → P1）

---

Phase 5：输出审查报告

输出格式见 references/report-templates.md。

• 不通过：输出「审查报告」，包含问题清单和修复建议
• 通过：输出「准出证书」，记录基线与审查历程

---

交互规范

---

禁止行为

• 禁止放水：严格执行准出门槛
• 禁止越权：不改写 Contract
• 禁止无证据质疑：每条问题必须指向证据位置
• 禁止跳过 Gate：按顺序执行

---

触发词

• 「审查 API contract」「接口契约评审」「API 设计评审」
• 「/api-reviewer」

---

参考文档

AskUserQuestion 模板

本文档定义 api-reviewer 审查过程中需要向用户确认的问题模板。

---

基线文档确认

触发时机：Phase 0 - 读取 PRD/Contract/Index

question: "请提供 Contract 的上游基线与文档路径"
header: "基线文档"
multiSelect: false
options:
  - label: "从 Contract 中读取引用路径"
    description: "Contract 已标注 PRD/边界确认/Index 路径，直接读取"
  - label: "手动提供路径"
    description: "请提供 PRD 路径、Contract 路径、Index 路径（如有）"
  - label: "部分文档缺失"
    description: "说明缺失项（缺失将导致 P0）"

处理路径：

---

契约类型确认

触发时机：Phase 0 - 确认协议类型

question: "请选择本次审查的契约类型"
header: "Contract 类型"
multiSelect: true
options:
  - label: "HTTP/REST API"
  - label: "GraphQL API"
  - label: "gRPC API"
  - label: "事件/消息协议"
  - label: "WebSocket/SSE 实时协议"
  - label: "Webhook"
  - label: "SDK/Library 公共接口"
  - label: "文件格式/数据交换格式"
  - label: "IPC/CLI/插件接口"

---

多协议确认

触发时机：Phase 0 - 识别多协议场景

question: "是否为多协议 Contract（需要 Contract Index）？"
header: "多协议"
multiSelect: false
options:
  - label: "是，多协议"
    description: "必须提供 Contract Index"
  - label: "否，单一协议"
    description: "无需 Index"
  - label: "不确定"
    description: "请补充协议列表"

---

Guardrails Trigger 澄清

触发时机：Phase 0 - 无法判断本次 Contract 是否在改变项目级默认规则

question: "这次 Contract 变更是否会改变项目里多个模块都要遵守的默认规则？"
header: "Guardrails Trigger"
multiSelect: false
options:
  - label: "是，会改变项目默认规则"
    description: "应优先判断是否需要更新 Guardrails"
  - label: "否，只影响当前 Contract"
    description: "通常无需触发 Guardrails"
  - label: "不确定，需要结合现有 Guardrails 一起判断"
    description: "先读取现有 Guardrails 与批准基线再决定"

---

既有契约与复用确认

触发时机：Phase 3 - 冲突与重复造轮子检查

question: "是否已有可复用的接口/事件/SDK 或历史版本？"
header: "既有契约"
multiSelect: false
options:
  - label: "有，提供路径/链接"
    description: "提供现有 Contract 或 API 文档"
  - label: "没有"
    description: "确认无可复用项"
  - label: "不确定"
    description: "需要补充系统范围或服务清单"

---

Lint/自动化检查

触发时机：Phase 0 - 本地工具可用时

question: "是否需要执行本地 lint/自动化检查？"
header: "自动化检查"
multiSelect: false
options:
  - label: "是，已有本地工具"
    description: "允许执行现有 CLI（不安装新工具）"
  - label: "否"
    description: "跳过自动化检查"

自动化检查（可选）

仅在本地工具已安装且用户允许时执行；不要安装新工具。

OpenAPI/REST

• spectral lint <spec>
• redocly lint <spec>
• openapi-cli validate <spec>
• oasdiff --fail-on-diff <old> <new>（破坏性变更）

GraphQL

• graphql-schema-linter <schema.graphql>
• graphql-inspector validate <schema.graphql>
• graphql-inspector diff <old> <new>（破坏性变更）

gRPC

• buf lint
• buf breaking --against <old>

事件/AsyncAPI

• asyncapi validate <spec>
• spectral lint <spec>（AsyncAPI 规则集）

组织内工具

如果已有 42Crunch 或其他企业级审计工具，按内部标准命令执行并附审计结果。

判定规则

• 语法/解析错误 → P0
• 破坏性变更 → P0
• 规范警告 → P1
• 信息级建议 → P2

协议检查清单

本清单按协议列出 Must/Should/Nice。只加载适用章节。

• Must 缺失 → P0
• Should 缺失 → P1
• Nice 缺失 → P2

目录

1. Contract Index（多协议） 2. 通用检查 3. HTTP/REST 4. GraphQL 5. gRPC 6. 事件/消息 7. WebSocket/SSE 8. Webhook 9. SDK/Library 10. 文件格式 11. IPC/CLI

---

1. Contract Index（多协议）

Must

• Index 元信息（名称、版本、状态、Owner）
• Contract 清单（协议类型、文档链接、版本、状态）
• 共享规则（认证/授权、错误码体系、版本与兼容策略、幂等/重试、限流）
• 跨协议一致性映射（核心模型、事件与接口对应）
• PRD→Contract 覆盖总表

Should

• 主要消费者列表
• 变更记录与兼容性说明

Nice

• 弃用计划与时间表

---

2. 通用检查

Must

• 范围与非范围（In/Out of scope）
• Owner 与数据所有权声明
• 主要消费者与调用方向
• 认证/授权模型（或明确不需要）
• 错误模型（结构、码表、语义）
• 版本与兼容性规则
• 核心数据模型定义（字段类型/必选/约束）

Should

• 幂等规则与重试语义
• 限流/配额策略
• 观测字段（correlationId/traceId）
• 示例（请求/响应/事件）
• 合规/PII/敏感字段标注

Nice

• 性能/SLO 目标
• SLA/支持策略

---

3. HTTP/REST

Must

• Base URL/版本策略
• Endpoint 清单（方法 + 路径）
• 请求/响应 Schema（含必填与约束）
• 状态码与错误码语义
• 认证/授权方式

Should

• 分页策略与字段（或明确不分页）
• 过滤/排序/搜索约定
• 幂等键策略（对创建/更新）
• 限流/重试/超时说明
• 并发控制（ETag/If-Match 等）
• 示例请求/响应

Nice

• 批量操作规范
• 字段级权限/脱敏说明

---

4. GraphQL

Must

• Schema SDL
• Query/Mutation/Subscription 清单
• 类型与输入定义（含 nullability）
• 认证/授权模型
• 错误结构与语义
• 分页策略（Connection/Offset 等）

Should

• 复杂度/深度限制
• 版本与弃用策略（@deprecated）
• 示例查询与响应
• 限流/配额策略

Nice

• Persisted Query 策略

---

5. gRPC

Must

• .proto 定义
• Service/Method 清单
• Request/Response Message 结构
• 错误状态映射（Status + Details）
• Deadline/Timeout 策略
• 流式语义（Unary/Streaming）
• 认证/授权方式

Should

• 字段编号与保留规则（兼容性）
• 幂等/重试策略
• Metadata 约定
• 示例调用

Nice

• Health Check/Reflection 支持说明

---

6. 事件/消息

Must

• 事件类型/Topic/Queue 命名
• Producer/Consumer 所有权
• Payload Schema 与版本策略
• 交付语义（至少一次/至多一次）
• 顺序/分区策略
• 重试/DLQ 策略
• 幂等/去重键

Should

• 兼容性规则（向后/向前）
• Retention/过期策略
• 示例事件

Nice

• Schema Registry 位置

---

7. WebSocket/SSE

Must

• 连接方式与 URL
• 认证/授权与握手流程
• 消息类型与 Payload Schema
• 错误消息格式
• 心跳/保活策略
• 重连策略

Should

• 顺序保证与幂等说明
• 限流/背压策略
• 示例消息

Nice

• Presence/状态同步说明

---

8. Webhook

Must

• 事件类型与 Payload Schema
• 订阅/回调地址管理
• 签名/验签机制
• 重试策略与退避
• 幂等/重复投递处理

Should

• 顺序语义
• 示例 payload

Nice

• 验证/测试端点

---

9. SDK/Library

Must

• 公共 API 列表与签名
• 版本与兼容性策略
• 错误/异常类型
• 线程安全/异步语义（如适用）
• 运行环境与依赖范围

Should

• 弃用策略与迁移指引
• 示例代码
• 凭证/配置管理说明

Nice

• 性能或资源占用说明

---

10. 文件格式

Must

• 文件结构与 Schema
• 编码/字符集
• 版本标识
• 必填/可选字段与约束
• 校验规则

Should

• 大小限制与拆分规则
• 压缩/加密策略
• 示例文件

Nice

• 向前/向后兼容策略

---

11. IPC/CLI

Must

• 命令/子命令列表
• 参数/选项与默认值
• 输入/输出格式
• Exit Code 与错误语义
• 权限/鉴权要求（如适用）

Should

• 版本与兼容策略
• 环境变量支持
• 示例命令

Nice

• Shell Completion 支持

Review Report Template

Baseline Collection Report

• Contract/Index：
• PRD baseline:
• Boundary/Ownership Confirmation:
• Agreement type:
• Lint/Automation Check: Executed/Not Executed (reason)
• Conclusion: Blocked by Gate 0 / P0

---

Review report (failed)

• Conclusion: Failed (P0: x, P1: y, P2: z)
• Contract version:
• PRD baseline:
• Gate results: Gate1/2/3/4

---

Certificate of approval (passed)

• Conclusion: Passed (P0:0, P1:0, P2:≤2)
• Contract version:
• PRD baseline:
• Gate results: Gate1/2/3/4
• Residual P2:
• Reviewer：

审查报告模板

基线收集报告

• Contract/Index：
• PRD 基线：
• 边界/所有权确认：
• 协议类型：
• Lint/自动化检查：执行/未执行（原因）
• 结论：通过 Gate 0 / P0 阻断

---

审查报告（未通过）

• 结论：不通过（P0: x, P1: y, P2: z）
• Contract 版本：
• PRD 基线：
• Gate 结果：Gate1/2/3/4

---

准出证书（通过）

• 结论：通过（P0:0, P1:0, P2:≤2）
• Contract 版本：
• PRD 基线：
• Gate 结果：Gate1/2/3/4
• 残留 P2：
• Reviewer：