API 设计评审器

解决什么问题

团队在迭代中不断新增或修改 API 端点，Review 时容易陷入细节争论：命名风格不统一、HTTP 方法用错、状态码语义含糊、错误响应格式各写各的。等到上线才发现破坏性变更已经合入，v2 迁移成本被推高。

如何工作

这个技能在一轮评审内交付结构化结果，核心分三步。

规范审查（Lint）
逐项核对命名约定（资源用 kebab-case，字段用 camelCase）、HTTP 方法语义、URL 结构、状态码、错误响应结构与文档完整性。

破坏性变更检测
对比新旧两份 spec，识别端点删除、字段改名、类型变更、新增必填字段、状态码变化等，每条给出迁移动作建议。

质量评分卡
按一致性 30%、文档质量 20%、安全实现 20%、可用性 15%、性能模式 15% 加权打分，映射 A–F 等级。

最终输出结构化工件 ApiReview，包含 lint 问题列表、破坏性变更与迁移方案、评分卡、放行结论（approve 或 changes_required）。如果存在 breaking change，必须版本号升级或提供兼容方案后才可放行。同时附自然语言摘要，列出最该先改的 3 条。

适用边界

仅做设计层评审，不替代接口功能测试。安全项以实际实现与官方标准为准，不替用户编造接口数据。