Agent Skills
返回列表
API契约风险审查(多端适配)

API契约风险审查(多端适配)

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md,安装 @qixiantech/api-contract-risk-check。

技能介绍

要解决的问题

团队在发版或对外公开 API 前,往往手翻 OpenAPI 文档找 破坏性变更、鉴权声明与公开面不一致、以及 Schema 层面的可见结构问题。人工对照两份规范既费时,也容易漏掉端点删除、方法变更或请求兼容性这类 high_risk 信号。本技能只做契约文档侧的结构化审查,不代替你对真实环境的渗透或回归测试。

技能如何工作

你向 Skill 提交解析后的 OpenAPI JSON(不接受 YAML 字符串),并填写 review_mode、authentication_expected、public_api 等字段;若选 breaking_change 模式,还需提供与当前产品对应的 previous_spec 真实上一版规范。服务通过 HTTPS 分析规范,返回 summary、score、grade、findings、recommendations、risks、breaking_changes、review_scope 等,供屏幕终端用表格/卡片展示,或由语音终端朗读 presentation.speech_text。

接入 ARC v2.1 时,同一笔付费履约可在多端保持 result_digest 一致;Agent 需自行声明终端能力,并安全保管 signed_receipt,跨设备取回不会重新下单或重复收费。付费走 SkillHub Agent Pay(¥4.99/次):首次业务请求可能返回 HTTP 402,完成微信支付后带原幂等键与订单头重试同一 URL。

边界与注意点

  • 工具 只识别规范中可见的结构问题,不验证服务端真实行为、权限绕过、业务逻辑或性能。
  • 兼容性检查不解析外部 $ref,也不完整推演 allOf / oneOf / anyOf;复杂模型仍需契约测试。
  • 破坏性变更输出是客户端兼容性预警;能否发布仍要结合版本策略、迁移期与消费者清单。
  • 提交前删除不必要的身份信息、密钥与商业秘密,并取得用户同意;服务不会读取硬件类型,跨端取回不能只靠订单号或 OpenID。

使用场景

  • 发版前把当前版 OpenAPI JSON 交给技能,检查端点删除与方法变更等 high_risk 项
  • 对外宣称公开 API 时,核对 public_api 与 authentication_expected 在规范里是否自洽
  • 大版本迁移前用 breaking_change 模式并附上 previous_spec,拉取 breaking_changes 清单做迁移排期
  • 接口评审会上需要 score、grade 与 findings 结构化输出,而不是口头扫一遍 YAML

适合人员

  • 负责 API 版本策略的后端工程师,需要在不发版探测的情况下做破坏性变更预警
  • 维护对外 OpenAPI 契约的技术写作者,要定期审查鉴权与公开范围字段是否一致
  • 平台团队在 SkillHub/ARC 宿主里集成 Pay Skill,需要按 402 与履约凭证完成付费重试与跨端取回
  • 做客户端 SDK 升级的工程师,想对照 recommendations 与 design_findings 排回归范围