前言¶
DeepSeek Harness（DSH）開發智能體時，配置層面的變更（如註冊新工具、修改系統提示詞、調整採樣參數）很容易導致調用行爲發生漂移。開發者通常需要在本地調試或 CI 環境中驗證請求參數是否與預期一致。
dsh-modelprint 專注於解決“當前請求的配置指紋是否與上一次已知良好的配置一致”這一問題。它不依賴網絡請求或模型加載，僅通過讀取本地文件進行對比。
這是什麼¶
這是一個 DSH 插件，用於對每次請求的配置進行指紋識別，並通過 modelprint_check 工具對比當前 live card 與 pinned card，檢測配置漂移。
插件由 jwilson411 維護，基於 MIT 許可證開源。其核心價值在於提供一種輕量級的配置一致性檢查手段，幫助開發者確認 Harness 在組裝請求時，是否使用了預期的 provider、model id、sampling、tool schemas 以及 system-prompt prefix。
核心功能¶
1. 請求指紋識別¶
插件會對 DSH 發出的請求進行標準化，生成一個“card”，包含以下字段：
* provider：提供者名稱。
* model：實際發送的模型 ID。
* temperature：採樣溫度。
* top_p：採樣核值。
* tools_hash：工具列表的 SHA-256 哈希值。
* system_prompt_prefix_hash：系統提示詞前綴的 SHA-256 哈希值。
2. 配置對比與漂移檢測¶
通過 modelprint_check 工具，將生成的 live card 與本地的 pinned card 進行比對。如果存在差異，工具會返回所有不一致的字段名稱。
3. 零依賴與輕量化¶
- 不涉及網絡請求。
- 不加載模型。
- 無需密鑰。
- 僅依賴讀取 pin 文件進行 I/O 操作。
4. 靈活的配置路徑¶
支持通過 cordis.patch.yml 配置 pinPath，也可以通過環境變量 DSH_MODELPRINT_PIN 或默認路徑 modelprint.pin.json 指定 pin 文件位置。
安裝與啓用¶
使用官方 CLI 命令安裝該插件：
dsh plugin --profile web add github:jwilson411/dsh-modelprint
安裝後，插件會自動將其 dsh.bundle.patch 聲明附加到 profile manifest 中，並加載 cordis.patch.yml 配置層。
典型用法¶
1. 配置 Pin 路徑¶
在 cordis.patch.yml 中配置 pin 文件的路徑。優先級爲：配置文件中的 config.pinPath > 環境變量 DSH_MODELPRINT_PIN > 默認的 modelprint.pin.json。
- id: modelprint
config:
pinPath: ./modelprint.pin.json
2. 生成 Pin 文件¶
第一次使用時，可以調用 modelprint_check 並指定一個不存在的 pin 路徑，從返回的 PIN_MISSING 結果中複製 live 字段內容，生成 pin 文件。
{
"provider": "deepseek",
"model": "deepseek-chat",
"temperature": 0.2,
"top_p": null,
"tools_hash": "841e5f22...",
"system_prompt_prefix_hash": "d2c86f05..."
}
3. 調用檢測工具¶
在代碼或 CLI 中調用 modelprint_check 工具。如果不指定 pin 參數，則使用配置的路徑；若指定 request_json，則僅對當前請求進行指紋比對，不會覆蓋 pin 文件。
適用場景與注意¶
適用場景¶
- 在 CI/CD 流程中驗證 Harness 配置是否發生變化。
- 在本地開發中確認工具註冊順序或系統提示詞是否意外修改。
- 需要快速排查請求參數異常的調試環節。
注意事項¶
- 非認證產品：此插件不是水印檢測、權重交換檢測或模型認證工具。它只能證明發起請求的一側配置未變，無法證明模型本身未被替換。
- 故意誤報：插件在檢測到工具列表或系統提示詞發生有意更改時，會產生誤報。這是設計特性，旨在區分“有意的配置變更”和“意外的配置漂移”。
- 環境要求：需要 Node.js 版本 >= 22.14.0。
- 依賴關係：插件依賴於
@deepseek-ai/dsh-tools版本^0.1.1-rc.2。
總結¶
dsh-modelprint 提供了一種基於配置指紋的漂移檢測機制。通過將請求參數固化到 pin 文件中並定期比對，開發者可以更清晰地掌握 Harness 的行爲軌跡。
