前言¶

在 DeepSeek Harness (DSH) 插件生态中，给智能体赋予文件系统权限时，审计是一个两难问题：既要证明它做了什么，又不能把文件内容泄露出去。jwilson411/dsh-mutation-receipt 插件通过生成追加式的 JSONL 收据来解决这个问题。它记录操作路径、类型以及 SHA256 哈希值，但不记录文件内容。

插件介绍¶

这是一个 DeepSeek Harness 函数插件。它将文件系统操作转化为可引用的追加式 JSONL 收据。每行包含路径、操作类型以及操作前后的 SHA256 哈希值。

核心功能¶

• 追加式 JSONL 收据：每行记录一次文件操作，包含时间戳、会话 ID、操作类型、路径、SHA256 之前和之后。
• 元数据记录：记录路径、操作类型（op，如 create/update/delete）以及 SHA256 哈希值。
• 无内容设计：插件不存储文件内容，不存储 diff，不存储预览。
• 主机驱动记录：不自动遍历文件系统，由主机在发生操作时主动调用 recordMutation 函数。
• CLI 工具：提供 mutation-receipt show 命令用于查看收据。

安装与启用¶

使用官方安装命令：

dsh plugin --profile default add github:jwilson411/dsh-mutation-receipt

该插件依赖于 @deepseek-ai/dsh-tools@0.1.1-rc.2 和 @deepseek-ai/cordis@^4.0.1，要求 Node.js 版本 >= 22.14.0。

典型用法¶

主机必须主动调用 recordMutation 来记录操作。对于 update 和 delete 操作，必须提供 sha256_before。

import { recordMutation } from 'dsh-mutation-receipt'

// 在写入前计算 SHA256
const { sha256: before } = hashFile('notes/hello.txt', workspaceRoot)

recordMutation({
  workspaceRoot,                      // 必填：所有路径相对于此根目录
  receiptPath,                        // 必填：追加式 JSONL 文件路径
  sessionId: 'sess-1',                // 可选
  op: 'update',                       // 'create' | 'update' | 'delete'
  path: 'notes/hello.txt',            // 相对路径
  sha256_before: before,              // 更新和删除操作必填
  sha256_after: '...',                // 可选，若不提供则从磁盘读取
})

使用 CLI 工具查看收据：

mutation-receipt show --receipt ./mutation-receipt.jsonl --root /path/to/workspace -n 10 --json

适用场景与注意¶

• 适用场景：需要审计智能体文件操作、合规追踪、无内容泄露的审计日志。
• 重要限制：
  • 不是备份：仅提供哈希证明文件曾存在或被修改，无法恢复内容。
  • 不是 DLP 即服务：不扫描、不分类、不拦截，无法判断数据是否敏感。
  • 本地运行：文件内容、收据和路径都不会离开机器，无网络请求。
  • 非自动扫描：不遍历文件系统，只有被调用的 recordMutation 才会被记录。
  • 必填哈希：更新和删除操作必须提供 sha256_before，否则报错。
  • 安全检查：插件会对路径进行校验，拒绝绝对路径或包含 .. 的路径，确保收据不泄露机器真实路径。

结尾¶

该插件通过仅记录元数据和哈希值，在审计和隐私之间提供了平衡。它不存储内容，也不离开本地机器。要查看更多细节或提交问题，请访问 GitHub 仓库。