DeepSeek Harness (DSH) 采用插件化架构，旨在通过模块化工具解决特定开发场景的痛点。在 API 接口的维护与调用过程中，保持接口定义（OpenAPI 规范）与客户端代码的一致性，以及及时识别版本升级带来的破坏性变更，是开发者常遇到的问题。dsh-api-contract 插件正是为此设计，它能在本地直接解析规范并生成类型化代码。
插件定位与基础信息¶
这是一个工作流类插件，由 uckkk 维护，采用 MIT 开源许可证。它是一个纯 Node 实现，不依赖网络或外部服务。
核心能力包括：
* 解析 OpenAPI 3.x 规范（支持 JSON 或 YAML）。
* 生成 TypeScript 类型化客户端（基于 fetch）。
* 生成 Python 类型化客户端（基于 requests）。
* 检测破坏性变更，包括删除接口路径/方法、删除必填参数、参数类型变化、响应结构变化等。
安装与启用¶
通过官方插件命令安装：
dsh plugin add github:uckkk/dsh-api-contract
安装完成后，需要在项目的 package.json 配置文件中，将插件加入 dsh.profile.bundles 列表，使其在会话中可用：
{
"dsh": {
"profile": {
"bundles": ["dsh-api-contract"]
}
}
}
典型用法¶
安装并启用后，可以在 DSH 会话中直接调用插件提供的工具。
1. 生成类型化客户端
根据指定的 OpenAPI 规范文件生成客户端代码。以下命令生成一个 TypeScript 客户端：
gen_client(spec="openapi.yaml", lang="typescript", outDir="./src/api")
2. 检测破坏性变更
在升级接口规范版本前，对比新旧规范以发现潜在的破坏性变更。以下命令对比两个版本：
diff_spec(oldSpec="openapi.v1.", newSpec="openapi.v2.")
适用场景与注意事项¶
- 技术栈：TypeScript 客户端直接使用浏览器原生的
fetch；Python 客户端依赖requests库，使用前需确保已安装（pip install requests）。 - 源码安全：插件以当前 DSH 进程的权限在本机运行第三方代码。请务必在安装前审阅其源码，确认无安全风险后再使用。
- 格式支持：支持 JSON 以及常见的块结构 YAML（支持嵌套映射、序列、
$ref引用等）。
总结¶
dsh-api-contract 为 DSH 环境提供了一套完整的接口契约管理方案。通过解析 OpenAPI 规范生成类型化客户端并审计破坏性变更，可以减少手动维护代码的出错率，提升 API 交互的规范性。
