dsh-action-outbox: DeepSeek Harness 工具副作用批量審覈

前言¶

DeepSeek Harness（DSH）智能體在運行過程中會產生大量外部寫入操作。本地代碼檢查點（如 Git worktree）可以恢復代碼，但無法撤回已發出的評論、郵件、部署或支付。DeepSeek Harness 論文中提到的應對方案有兩種：一是延遲輸出直到提交，二是定義領域特定的補償策略。本插件實現了更強的通用方案——延遲輸出直到提交，不依賴外部系統具備原子事務能力。

這是什麼¶

dsh-action-outbox 是一個爲 DeepSeek Harness 設計的持久化批量審覈收件箱插件，由用戶 JimChen-g 維護。它允許 DSH 智能體在執行工具副作用前，先在本地暫存具體的工具調用，進行完整檢查、編輯和審覈，最後一次性提交。

插件的核心價值在於：暫存期間零目標分發，只有在明確批准並提交後，副作用纔會真正執行。

核心功能¶

該插件提供以下能力：

Web 側邊欄收件箱：提供可視化的批量審覈界面，展示完整的參數 JSON、工具來源、指紋、哈希值、字節數，支持複製和下載。
編輯與替換：提供 action_outbox_replace 工具，允許在審覈前修改暫存工具的名稱、參數或摘要。任何修改都會失效舊的摘要和哈希值。
容錯處理：
- Fail-closed 長審覈：截斷的審覈卡片無法單獨授權提交，必須先完整打開收件箱確認。
- 崩潰安全恢復：提交過程中的進程崩潰會導致狀態變爲 recovery_required，未收到持久化成功回執的操作標記爲 ambiguous，不再自動重試。
持久化與重啓：暫存批次以 0600 權限的狀態文件持久化。重啓後，草稿會自動變爲 needs_reapproval 狀態，要求重新檢查當前策略和工具。
演示引導：內置“Copy safe demo prompt”，提供安全的本地文件寫入演示路徑。

安裝與啓用¶

使用預構建的 tarball 安裝（無需安裝時構建權限）：

curl -LO https://github.com/JimchengChina/dsh-action-outbox/releases/download/v0.3.0/dsh-action-outbox-0.3.0.tgz
npx @deepseek-ai/dsh plugin --profile web add ./dsh-action-outbox-0.3.0.tgz

或者從 Git 標籤安裝：

dsh plugin --profile web add github:JimchengChina/dsh-action-outbox#v0.3.0

插件通過 cordis.patch.yml 自身激活，瀏覽器端僅貢獻到官方的 sidebar.footer.action 和 shell.overlay 插槽。

典型用法¶

智能體工作流通常包含以下步驟：

調用 action_outbox_begin({ label }) 開始一個新批次。
調用 action_outbox_stage({ tool, arguments, summary? }) 暫存一個或多個工具調用。
可選調用 action_outbox_unstage({ action_id }) 或 action_outbox_replace({ action_id, ... }) 進行調整。
調用 action_outbox_review() 進行審覈。
在 Web 界面的“批量審覈收件箱”中檢查完整批次。如果審覈預覽被截斷，需先在收件箱中完整查看並確認。
在收件箱編輯後，點擊“Run fresh review”。審覈通過後，按鈕變爲“Next: copy exact commit prompt”。複製該提示詞並粘貼到對話中。僅收件箱審覈不會直接寫入聊天曆史。
調用 action_outbox_commit({ expected_digest: digest, approval_nonce }) 提交，或調用 action_outbox_discard() 放棄。

重要提示：不要只讓智能體使用“最新的審覈結果”。模型可能看到的最新審覈是歷史對話中的舊結果。必須粘貼收件箱生成的精確提交提示詞，或者要求智能體先調用 action_outbox_review 並緊接着調用 action_outbox_commit。

配置與安全語義¶

配置示例¶

插件支持通過配置文件控制行爲：

- id: action-outbox
  name: dsh-action-outbox
  config:
    include: ['github_*', 'slack_*', 'deploy_*']
    exclude: ['github_get_*', 'github_list_*']
    enforce: ['github_create_*', 'github_update_*', 'slack_send', 'deploy_*']
    requireApproval: true
    rejectDuplicateActions: true
    persistPending: true
    stateFile: ''
    maxPendingMs: 1800000
    maxActions: 20
    maxArgumentBytes: 65536
    resultPreviewChars: 2000
    approvalPreviewChars: 4000

include / exclude：控制哪些工具可以被暫存或例外。
enforce：強制使用收件箱路由，拒絕直接調用。
persistPending：默認啓用，持久化未提交的草稿和恢復回執。
stateFile：指定狀態文件路徑，默認爲 $DSH_HOME/action-outbox/state.json。

安全語義¶

零目標分發：暫存和編輯操作僅更新本地有界狀態，不會調用目標工具。
完整可見性：收件箱保留完整的規範 JSON，緊湊卡片會報告截斷情況，不能作爲唯一的審批界面。
TOCTOU 保護：在關鍵邊界檢查摘要、一次性 nonce、實時策略、工具身份和指紋。
可撤銷性：暫存、取消暫存和替換操作會清除所有之前的審覈、確認和 nonce。
重啓重新授權：重啓後，待處理草稿僅恢復爲 needs_reapproval，並獲取新的 nonce。

適用場景與注意¶

此插件適合需要在 Web 環境下對 DSH 智能體的外部副作用進行人工干預和審覈的開發者。

使用前請確保理解插件的“Fail-closed”機制。在提交前，discard 操作能保證沒有暫存的目標被執行。所有變更都會產生不同的授權狀態，即使調用者保留了舊的摘要或 nonce。

插件許可證爲 MIT。

結語¶

dsh-action-outbox 爲 DeepSeek Harness 提供了一個嚴謹的“審查優先，提交一次”的工作流機制。通過持久化的收件箱和完善的崩潰恢復機制，它解決了智能體外部寫入不可逆的痛點。