dsh-api-contract

dsh-api-contract · JOJO&Adam

装完之后，你和 agent 讨论接口时会先拿到一份能落地的契约；要改接口时，它会先告诉你这次会不会伤到现有客户端。

不是"让 AI 写个接口文档"，是把接口这一层的判断变成可复核的流程：契约先行 → 可被机器校验 → 变更用同一把尺子评审。

安装

# Web 版
dsh plugin --profile web add @jojonadam/dsh-api-contract
# 桌面版
dsh plugin --profile desktop add @jojonadam/dsh-api-contract

装完能做什么

• 开新接口：把必须早定的七件事（资源边界、命名、分页、错误、鉴权、幂等、版本）一次问清楚，而不是写到一半才发现分歧
• 写/审 OpenAPI：资源导向的路径设计、components 复用、请求响应约定，以及那些会悄悄变成破坏性变更的反模式
• 判破坏性变更：按变更类型给出客户端具体坏在哪，含"未知字段"这种常被忽略的兼容例外
• 定错误契约：HTTP 状态码与业务错误码的分工，业务失败返 200 的反模式
• 版本与弃用：什么时候才真需要新版本、版本放哪、四步弃用流程
• 文档与示例：文档从契约生成，示例质量的四个层次

怎么触发

直接用自然语言，例如「帮我设计一个订单接口的契约」「这次把 status 改成枚举算不算破坏性变更」「错误码怎么设计」；也可以显式点名技能。

边界

• 只管接口这一层（契约、演进、文档）；不替代你们的框架选型与代码规范
• 变更检测以你提供的契约文件为准；没有契约文件时，第一件事是补契约
• 不生成可直接上线的服务端实现

许可

MIT