dsh-canary-decision-proof：離線驗證 Canary 決策的證據生成器

在漸進式交付流程中，決策（promote、abort 或 pause）直接決定了服務狀態。雖然控制器負責執行這些決策，但驗證決策的依據至關重要。現有的做法往往依賴運行時狀態或模糊的日誌，缺乏確定的證據鏈。dsh-canary-decision-proof 提供了一種離線、確定性的方法，證明已記錄的 canary 決策遵循了顯式、僅哈希的策略。

這是什麼¶

這是一個控制器無關的離線證據驗證器。它不執行 rollout，不查詢 live metrics，不進行認證或授權，也不證明統計顯著性或用戶結果。它的核心職責是接收提供的證據，通過嚴格的邏輯規則進行重算，並生成一份內容尋址的報告。如果證據不完整，它會失敗到 pause。

核心功能¶

該插件通過以下機制實現決策的可驗證性：

證據完整性校驗：插件會檢查證據是否包含必要的指紋（artifact digest）、環境信息、收據、分析窗口、最大流量、最小窗口長度、觀察者閾值、新鮮度以及指標規則。如果證據不完整、過期、未綁定或採樣不足，判定邏輯會優先觸發 pause。
確定性指標計算：指標值使用正固定點整數 (valueMicros)。對於“越高越好”的指標，迴歸值爲 (baseline - canary) / baseline；對於“越低越好”的指標，迴歸值爲 (canary - baseline) / baseline。使用整數基點進行判斷，確保計算結果的確定性。
決策優先級：插件定義了明確的決策優先級順序：
- 證據不完整、過期或無效 → pause
- 存在失敗的指標 → abort
- 其他情況 → promote
輸出內容尋址報告：插件在顯式的工作區相對 artifactDir 下寫入報告。它拒絕路徑轉義和符號鏈接，僅生成包含哈希、計數、時間戳、定點比較、檢查和裁決的報告，不包含原始業務文本或密鑰。

環境與兼容性¶

依賴環境：需要 Node.js 22 或更高版本。
DSH 版本兼容：與 DSH >= 0.1.2-alpha.4 兼容。
權限注意：該插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證。

典型用法¶

插件提供了 inspect 和 verify 兩個主要命令，用於查看和驗證證據。

# 驗證證據並輸出報告
node bin/dsh-canary-decision-proof.mjs verify examples/promote.json

# 檢查證據詳情
node bin/dsh-canary-decision-proof.mjs inspect examples/promote.json

除了命令行工具，插件還通過 dsh_canary_decision_inspect、dsh_canary_decision_verify 暴露接口，並支持通過獨立的 stdio MCP 服務器調用 canary_decision_inspect 和 canary_decision_verify。

適用場景¶

該插件適合需要嚴格審計決策邏輯的場景。例如，在需要證明某次 promote 決策確實滿足所有預設閾值和窗口條件時，可以使用此插件進行離線複覈。它不適用於需要實時流量控制或自動回滾的場景（這通常由 dsh-ankh-guard 等插件負責）。

總結¶

dsh-canary-decision-proof 專注於“證明”而非“執行”。它將決策依據固化爲可驗證的證據，爲漸進式交付提供了審計層面的確定性。對於需要嚴格合規或複雜回滾策略的團隊，這是一個可控、離線的輔助驗證工具。

目錄頁：dsh-canary-decision-proof
源碼倉庫：github.com/dongsheng123132/dsh-canary-decision-proof