前言¶
在 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
