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 提供了一个严谨的“审查优先，提交一次”的工作流机制。通过持久化的收件箱和完善的崩溃恢复机制，它解决了智能体外部写入不可逆的痛点。