yan9651688/dsh-file-checksum

dsh-file-checksum

一个小型、只读的 DeepSeek Harness 插件，通过当前激活的 Harness 文件系统提供程序为文件计算 SHA-256 或 SHA-512。

与文本哈希工具不同，file_checksum 读取文件的原始字节，而不会将其内容放入模型对话中。它适用于当前 DSH 配置文件所挂载的文件系统，包括兼容的远程提供程序。

安装

直接从 GitHub 安装到某个配置文件：

dsh plugin --profile web add github:yan9651688/dsh-file-checksum

如需可复现的安装，请固定一个提交：

dsh plugin --profile web add github:yan9651688/dsh-file-checksum#

然后照常启动该配置文件：

dsh --profile web --dump-config
dsh --profile web

本仓库提供的是纯 ESM JavaScript，因此从 GitHub 安装不需要 prepare 构建或 pnpm 的 allowBuilds 条目。

工具

file_checksum 接受以下参数：

| 参数 | 是否必需 | 描述 |
| --- | --- | --- |
| file_path | 是 | 绝对路径，或相对于当前 agent 会话工作区的路径。 |
| algorithm | 否 | sha256（默认）或 sha512。 |
| expected | 否 | 预期的十六进制摘要。该工具会返回 match 或 mismatch。 |

示例提示：

Use file_checksum to verify dist/app.tgz against this SHA-256:

规范结果以结构化形式提供给 Native 和 Code Mode 调用方：

{
"path": "/workspace/dist/app.tgz",
"algorithm": "sha256",
"digest": "...",
"bytes": 12345,
"verification": "match"
}

校验和不匹配是一个成功的工具结果，其 verification: "mismatch"；文件缺失、不是常规文件、过大或不可读则属于工具错误。

配置

该 bundle 默认将整个文件限制为 64 MiB：

- insert:
- id: file-checksum
name: dsh-file-checksum
config:
maxBytes: 67108864

在后续的配置文件补丁中覆盖该行，以选择不同的正整数，最大可达 256 MiB。存在此限制是因为当前的 DSH 原始字节文件系统 API 返回的是完整的有界文件，而不是字节流。

数据与安全

- 通过 ctx.fs 读取；它不会调用 shell，也不会绕过当前激活的文件系统提供程序。
- 只读取一个常规文件，绝不写入或删除文件。
- 将校验和调用声明为独占，因此一个 Native 或 Code Mode 批次无法使配置的整文件内存限制成倍增加。
- 不访问环境变量、凭据或网络。
- 返回摘要、字节数、显示路径和校验状态；不返回文件内容。
- 通过 DSH 的 fs/observed 事件记录成功或缺失的读取，与内置的文件读取行为一致。
- 摘要用于标识内容完整性。它不是加密，也不会使敏感数据变得可以安全共享。

已知限制

- 每次调用只处理一个文件；不支持目录和 Git 树哈希。
- 大于 maxBytes 的文件会被拒绝，而不是以流式传输或截断的方式处理。
- 不同的代理或会话仍可能并发运行调用；每次调用最多可缓冲 maxBytes。
- 该插件面向 DSH 0.1.0-rc.6 及后续兼容的 0.1.x 版本。DeepSeek Harness 仍处于开发者预览阶段，因此上游的破坏性变更可能需要更新插件。

开发

npm install
npm test
npm pack --dry-run

这些测试会挂载真实的 Cordis 上下文、工具注册表以及本地 DSH 文件系统提供程序。它们覆盖标准哈希向量、二进制字节、预期摘要比较、会话相对路径、文件系统观察、错误情况以及生命周期清理。

许可证

MIT