前言¶
在 DeepSeek Harness（DSH）里和 agent 讨论接口时，常见做法是边聊边写文档或直接在代码里改路由。问题在于：命名、分页、错误码、版本往往写到一半才暴露分歧；接口一改，也很难用同一套标准判断会不会伤到已有客户端。
@jojonadam/dsh-api-contract（GitHub：JOJO-Adam/dsh-api-contract）面向的是接口这一层：契约先行、可被机器校验、变更用同一把尺子评审。它不是「让 AI 写一份接口文档」，而是把开接口、审 OpenAPI、判破坏性变更、定错误契约等步骤放进可重复触发的技能流程。维护者为 JOJO-Adam，社区目录分类为「工作流」。
这是什么¶
一句话定位：API contract studio for DeepSeek Harness——契约优先编写、破坏性变更评审、错误契约、版本与文档（README 与 package 描述中概括为 contract-first authoring、breaking-change review、error contracts、versioning、docs）。
插件当前版本为 0.1.0（见 package.json），许可证 MIT。运行环境要求：Node.js >= 20，DSH >= 0.2.0-rc.2。
核心功能¶
装完之后，README 列出的能力包括：
- 开新接口：把必须早定的七件事（资源边界、命名、分页、错误、鉴权、幂等、版本）一次问清楚，而不是写到一半才发现分歧。
- 写/审 OpenAPI：资源导向的路径设计、
components复用、请求响应约定，以及那些会悄悄变成破坏性变更的反模式。 - 判破坏性变更：按变更类型给出客户端具体坏在哪，含「未知字段」这类常被忽略的兼容例外。
- 定错误契约：HTTP 状态码与业务错误码的分工，以及业务失败仍返 200 的反模式。
- 版本与弃用：什么时候才真需要新版本、版本放哪、四步弃用流程。
- 文档与示例：文档从契约生成，示例质量的四个层次。
边界（同样来自 README）：只管接口层（契约、演进、文档），不替代框架选型与代码规范；变更检测以你提供的契约文件为准，没有契约时应先补契约；不生成可直接上线的服务端实现。
安装与启用¶
安装命令须使用资料原文，区分 Web 与桌面 profile：
# Web 版
dsh plugin --profile web add @jojonadam/dsh-api-contract
# 桌面版
dsh plugin --profile desktop add @jojonadam/dsh-api-contract
DSH 插件以当前 dsh 进程权限运行。安装前建议自行查看 GitHub 仓库 源码与 MIT 许可证，确认符合团队安全与合规要求。
典型用法¶
README 说明：直接用自然语言即可触发，也可显式点名技能。例如：
- 「帮我设计一个订单接口的契约」
- 「这次把 status 改成枚举算不算破坏性变更」
- 「错误码怎么设计」
经过上面的步骤，你和 agent 讨论接口时会先拿到一份能落地的契约；要改接口时，它会先告诉你这次会不会伤到现有客户端。
适用场景与注意¶
适合谁：需要在 agent 协作下做 REST/OpenAPI 契约设计、评审接口变更、统一错误与版本策略的团队或个人；已有或计划维护 OpenAPI 契约文件的场景与「变更以契约文件为准」的设定一致。
注意：
- 生态上 DSH 的理念是「一切皆插件」；SkillHub 目录页 为社区站点，与 DeepSeek / 幻方无官方从属关系，不要当作官方应用商店。
- 无契约文件时，插件侧的第一件事是补契约，而不是凭空做破坏性对比。
- 星标与版本以你安装时仓库/目录页为准；撰写时 GitHub 公开星标为 0。
结尾¶
dsh-api-contract 的价值在于把接口层的判断变成可复核的流程：契约先行 → 机器可校验 → 变更用同一标准评审。若要安装或查看详情，可访问 SkillHub 插件页 与 GitHub：JOJO-Adam/dsh-api-contract。
