前言¶

在 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 倉庫。