前言¶

在 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；如插件線索中提供了目錄頁地址，可按該線索訪問。