前言¶
在 DSH 里维护或评审 API 契约时，常见做法是人工对比两份 OpenAPI 文档，或依赖完整语义解析与行为级契约测试。前者容易漏掉「新增必填字段」「参数从可选变必填」「响应类型变更」等结构性破坏；后者成本高，也不总是发布前必跑的一步。下面介绍社区插件 dsh-openapi-diff（维护者 lengrufeng2008），它对两份 OpenAPI JSON 做结构性破坏性变更检查，并在 DSH 中通过工具 openapi_diff 调用，适合在改 spec、发版或安全/治理流程里做快速门禁。
DeepSeek Harness 的理念是「一切皆插件」；插件目录页托管在 SkillHub 等社区站点，与 DeepSeek / 幻方无官方从属关系，安装前请自行核对源码与许可证。
这是什么¶
dsh-openapi-diff 的定位是：针对 OpenAPI JSON 文档，比较「旧版」与「新版」，报告可能破坏客户端或下游集成的结构级差异。仓库：https://github.com/lengrufeng2008/dsh-openapi-diff。SkillHub 分类为 admin-security；当前 GitHub 星标为 0。许可证为 MIT（README Provenance）。
核心功能¶
依据 README 与 package.json 描述，插件关注下列一类变更（均为结构性，而非运行时行为）：
- 删除的 paths、methods、parameters、properties、responses
- 新增必填字段（new required fields）
- 参数由可选变为必填（parameter-became-required）
- 类型变更（type changes）
命令行与库侧入口见仓库 bin/dsh-openapi-diff.mjs 与导出路径 ./diff；在 DSH 侧通过 Cordis bundle（plugin/cordis.patch.yml）集成工具 openapi_diff。
能力边界¶
README Limits 一节说明，使用前应明确预期：
- 仅支持 JSON 格式的 OpenAPI，不支持 YAML 等其它序列化形式（除非你先自行转成 JSON）。
- 检查的是结构性子集：不做完整的
$ref解析，也不处理 oneOf / allOf 的完整语义。 - 不是行为兼容测试或契约测试（contract test）。
- 无报错结果不能证明 API 完全兼容；它只是结构性 diff 辅助，不能替代联调与测试。
环境与依赖¶
package.json 要求 Node.js >= 20，包类型为 ES module（"type": "module"）。
典型用法¶
命令行¶
在仓库根目录，对两份 JSON spec 做对比：
node bin/dsh-openapi-diff.mjs old.json new.json
需要机器可读输出时：
node bin/dsh-openapi-diff.mjs old.json new.json --json
在 DSH 中¶
README 给出的调用方式为：
Use openapi_diff with old=old.json new=new.json.
即在 Harness 会话中让智能体使用 openapi_diff 工具，并传入 old、new 两个 spec 文件路径（或等价参数，以插件实际 schema 为准）。已抓取资料中未给出 SkillHub 或 README 上的 dsh plugin add … 一类安装命令；若从目录页安装，请以 SkillHub 插件页 与仓库文档当时展示的内容为准，勿凭仓库名自行拼接命令。
自测¶
维护者提供的测试命令：
npm test
对应 package.json 中的 node --test test/*.test.mjs。
适用场景与注意¶
适合：需要在改 OpenAPI JSON、合并 PR 或发布前，快速列出「删 path/方法/参数/属性/响应、新必填、类型变」等明显破坏性结构变更的团队；与 admin-security 分类下的治理、变更审查流程可以配合使用（仍须人工判断业务是否真 breaking）。
注意：
- 插件在 当前 DSH 进程权限下运行，能读写的路径与宿主一致；安装或启用前请阅读
plugin/、src/源码及 MIT 许可证。 - 仅 JSON、无完整
$ref/ oneOf / allOf 语义，复杂 spec 可能漏报或误报边界情况，重要发布应结合真实客户端测试。 - 社区插件星标与活跃度会变化；以 GitHub 与目录页为准，本文不引用未在资料中出现的用户案例或数据。
结尾¶
dsh-openapi-diff 提供一份轻量、独立的 OpenAPI JSON 结构性破坏性变更检查，可在 CLI 或 DSH 的 openapi_diff 中使用，用于在完整契约测试之前做快速 diff 门禁。目录页：https://www.skillhub.cn/plugins/lengrufeng2008/dsh-openapi-diff；源码与说明：https://github.com/lengrufeng2008/dsh-openapi-diff。
