前言¶

在 DSH 插件开发中，ToolRuntime、MCP JSON-RPC 和 CLI JSON 是三类常见的机器通信表面。如果要在基线版本和观察版本之间做比较，直接重新执行目标可能会引入网络调用、副作用和凭据暴露。

dsh-surface-contract-proof 提供另一种路径：基于已记录的 JSON fixtures，检查三类表面是否仍然保持同一固定语义契约。下面介绍它的功能、边界、安装方式和典型用法。

这是什么¶

dsh-surface-contract-proof 是 MIT 许可的 DSH 插件，维护者为 dongsheng123132。

它读取显式 SHA-256 固定的 JSON fixtures，对记录的 DSH ToolRuntime、MCP JSON-RPC 与 CLI JSON 信封做 content-addressed conformance proof。

该插件要求 Node.js >=22。

核心功能¶

• 校验记录的 DSH ToolRuntime、MCP JSON-RPC 与 CLI JSON 信封，要求恰好三种 surface：dsh-toolruntime、mcp-jsonrpc 和 cli-json。
• 读取显式 SHA-256 固定的 JSON fixtures。
• 将 surface-specific 字段归一化为一个 canonical case digest，并由 manifest 固定每个 expected digest。
• 提供 DSH 工具 dsh_surface_contract_inspect 和 dsh_surface_contract_verify。
• 提供 MCP 别名 surface_contract_inspect 和 surface_contract_verify。
• MCP 表面为 proof-only 且 in-memory，接受有界 inline manifest/fixture JSON，不读写文件，不返回 fixture 主体。

边界与失败策略¶

该插件不执行目标、不启动任意命令、不调用网络服务、不重放副作用、不实现 action core。

当 fixtures 缺失、过期、格式错误、疑似秘密、schema/version 漂移或语义不同时，会 fail closed。

报告只暴露 hashes、identities、statuses 和 differing field names，不暴露请求参数、响应体、CLI 输出、prompts、messages、credentials 或 secrets。

文件路径必须是 workspace-relative 常规文件；拒绝 traversal 和 symlinks。写入原子化、读回，并限制在显式 artifactDir。

安装与启用¶

先确认运行环境满足 Node.js >=22，并按需固定插件 commit：

dsh plugin --profile surface-contract add github:dongsheng123132/dsh-surface-contract-proof#<commit>

安装前建议检查源码与许可证。插件以当前 dsh 进程权限运行，因此不要安装无法确认来源或行为的仓库。

典型用法¶

先做 inspect，拿到 canonical baseline digests，审查后再固定到 manifest：

dsh-surface-contract-proof inspect --workspace . --manifest contract.json

将审查后的摘要固定为 cases[].expectedSha256。

经过上面的步骤后，再做 verify：

dsh-surface-contract-proof verify --workspace . --manifest contract.json --artifactDir artifacts

退出码 0 表示 verified；退出码 2 表示 failed 或 invalid evidence。

DSH 与 MCP 工具¶

DSH 表面暴露：

• dsh_surface_contract_inspect
• dsh_surface_contract_verify

MCP 别名：

• surface_contract_inspect
• surface_contract_verify

MCP 路径保持 proof-only 且 in-memory：它接受有界 inline manifest/fixture JSON，不读写文件，也不返回 fixture 主体。若生成报告，写入限制在显式 artifactDir，并采用原子化、读回方式。

版本说明¶

Version 0.2.0 removes the bundled DSH tool runtime and the default export that stock Cordis Loader misclassified。

适用场景与注意¶

适合已有基线和观察版本 recordings 的场景，尤其是需要检查 DSH ToolRuntime、MCP JSON-RPC 与 CLI JSON 三类表面是否仍符合同一固定契约。

注意以下几点：

• 它不执行目标，不启动任意命令，不调用网络服务，不重放副作用，不实现 action core。
• fixtures 必须是显式 SHA-256 固定的 JSON fixtures。
• 报告只暴露 hashes、identities、statuses 和 differing field names。
• 安装前应检查源码、许可证和固定 commit。

结尾¶

dsh-surface-contract-proof 的价值在于把 DSH 三类机器表面的记录证据固定为可比较的 digest，避免在契约检查中直接重放请求内容。

GitHub：https://github.com/dongsheng123132/dsh-surface-contract-proof

社区目录页：本文已核实资料未包含可核实的目录页 URL；如插件线索中提供了目录页地址，可按该线索访问。