前言¶
在 DeepSeek Harness (DSH) 的開發流程中，驗證構建產物或文件的完整性是一項常見需求。直接讀取文件內容不僅會佔用上下文窗口，還可能暴露敏感數據。傳統的文本哈希工具往往需要將文件內容輸入模型，這不符合安全與效率的原則。dsh-file-checksum 解決了這個問題，它通過 DSH 活躍的文件系統提供程序，僅計算文件的原始 SHA-256 或 SHA-512 校驗和，而不將文件內容傳遞給模型。
插件介紹¶
dsh-file-checksum 是一個用於 DeepSeek Harness 的只讀插件，由開發者 yan9651688 維護，採用 MIT 許可證。
該插件的核心價值在於“不暴露內容”。它通過 ctx.fs 讀取文件，不調用 shell、不繞過文件系統提供程序、不訪問網絡。它計算文件的原始字節哈希值，並返回結構化的校驗和結果，供模型用於驗證文件完整性。
安裝與配置¶
安裝該插件需要使用 DSH 的插件管理命令。
1、添加插件到指定 profile：
dsh plugin --profile web add github:yan9651688/dsh-file-checksum
2、爲了確保安裝的可復現性，建議固定特定 commit：
dsh plugin --profile web add github:yan9651688/dsh-file-checksum#<commit-sha>
安裝完成後，啓動該 profile 即可使用。
工具使用¶
插件提供了一個名爲 file_checksum 的工具。
參數說明：
| 參數名 | 必填 | 說明 |
|---|---|---|
file_path |
是 | 絕對路徑，或相對於當前 agent 會話工作區的路徑 |
algorithm |
否 | 哈希算法，sha256（默認）或 sha512 |
expected |
否 | 期望的十六進制校驗值。工具返回 match 或 mismatch |
典型用法示例：
在提示詞中，可以直接要求模型使用該工具：
Use file_checksum to verify dist/app.tgz against this SHA-256: <digest>
返回結果：
工具返回結構化 JSON 數據，包含路徑、算法、校驗值、字節數以及驗證狀態。
{
"path": "/workspace/dist/app.tgz",
"algorithm": "sha256",
"digest": "...",
"bytes": 12345,
"verification": "match"
}
如果校驗不匹配，返回的 JSON 中 verification 爲 mismatch。如果文件缺失、不是常規文件、過大或不可讀，則返回錯誤。
配置項¶
插件默認配置了一個 64 MiB 的單文件大小限制，防止內存溢出。
在 profile 的配置中，可以通過 maxBytes 參數調整該限制，最高可配置至 256 MiB。
- insert:
- id: file-checksum
name: dsh-file-checksum
config:
maxBytes: 67108864
數據與安全¶
該插件在設計上注重安全性：
- 只讀操作：插件聲明爲只讀，不調用 shell，不訪問環境變量、憑證或網絡。
- 原始字節：讀取文件內容時不經過 shell，直接通過
ctx.fs處理，且結果不包含文件內容本身。 - 併發控制：校驗調用被聲明爲互斥，防止在 Native 或 Code Mode 批處理中同時調用導致內存超限。
- 完整性記錄：成功或失敗的讀取都會通過 DSH 的
fs/observed事件記錄，與內置文件讀取行爲保持一致。
已知限制¶
在使用該插件時，需要注意以下限制：
- 單文件調用：每次調用僅支持計算一個文件。不支持目錄和 Git 樹哈希。
- 大小限制：超過
maxBytes的文件會被拒絕，不支持流式讀取或截斷。 - 版本兼容：插件依賴 DSH 0.1.0-rc.6 及兼容的 0.1.x 版本。由於 DSH 處於開發者預覽階段，上游的破壞性變更可能需要插件更新。
- 純 ESM：該插件使用純 ESM JavaScript 編寫，GitHub 安裝無需構建步驟。
結語¶
dsh-file-checksum 爲 DeepSeek Harness 提供了一種安全、高效的文件完整性校驗手段。它利用 DSH 的文件系統能力，在不泄露內容的前提下完成了哈希計算，適合用於構建流程驗證、文件分發校驗等場景。
插件目錄：https://www.skillhub.cn/plugins/yan9651688/dsh-file-checksum
GitHub 倉庫：https://github.com/yan9651688/dsh-file-checksum
