后台委派 HuntercodeT/dsh-staff

dsh-staff

把任务交给 DeepSeek Harness，然后继续做别的事。

从 Claude Code 或 Codex 内部把工作委派给一个后台 dsh agent —— 它运行在自己的上下文中，使用自己的工具，并在进行过程中汇报进度。

CI
License: MIT
Claude Code
Codex
Benchmark

安装 · 用法 · 配置 · 速度 · 基准测试 · 中文测评

$ /dsh:researcher survey how session resume is wired through this repo

Started background research job.
job id: research-muf88u1c-236a3811 (pid 41207)
model: deepseek-flash profile: unrestricted timeout: 60m
Collect: run wait research-muf88u1c-236a3811 --timeout 10m

$ wait research-muf88u1c-236a3811 --timeout 10m
Job research-muf88u1c-236a3811 (research, done)

Summary
The runner decides in a single ternary in run() — runner/index.mjs:235 …

[dsh-staff] mode=research model=deepseek-flash dsh_status=SUCCESS duration=154s

该任务会阅读代码、运行命令，并把答案写入文件。你的会话不会被阻塞，其上下文也不会消耗在搜索上：在一个实测任务中，委派消耗了 49.6k 编排器 token，而内联完成同样的工作消耗了 70.6k。

委派真正的用途。 agent 在自己的上下文中进行搜索 —— 它打开的每个文件、运行的每条命令、走过的每条死路。回到你会话中的是答案。这是这些测量所证实的唯一好处，并且它会随着调查规模的增大而增长。另一个好处是并行性：任务是分离的进程，因此当单个会话串行工作时，多个任务可以同时运行。

[!IMPORTANT]
委派不会让事情变得更快。 它比在自己的会话中工作多消耗约 23% 的墙上时钟时间。它换来的是上下文余量和并行性。如果你想要速度 —— 或者只是想听听第二个模型的意见 —— 请改为在自己的会话中切换模型。那只是一个标志，不需要这一整套机制。

安装

npm i -g @deepseek-ai/dsh # 全局安装，不要用 npx —— npx 每次调用都会重新解析（每次约 3 秒）
export DEEPSEEK_API_KEY=

这个仓库是面向两种宿主环境的插件市场：

Claude Code
claude plugin marketplace add /path/to/dsh-staff
claude plugin install dsh@dsh-staff

Codex
codex plugin marketplace add /path/to/dsh-staff
codex plugin add dsh@dsh-staff

先一次性配置好 dsh profile，然后对整个链路做冒烟测试：

node companion/dsh-companion.mjs setup
node companion/dsh-companion.mjs ask --prompt "Reply with exactly: ok"

如果它打印出 ok，就大功告成了。setup 会在 $DSH_HOME/profiles/ 下创建一个 dsh-staff profile，安装 runner 及其 overlay，并报告你的密钥是否可见。

[!NOTE]
每次升级后都要重新运行 setup —— runner 就位于那个 profile 内部，所以在重新安装之前，新版本不会带来任何变化。

[!WARNING]
在 Codex 中，要以非沙箱方式运行。 dsh 需要 $DSH_HOME、网络以及工作目录；默认的命令沙箱至少会隐藏其中之一。请使用 codex exec --dangerously-bypass-approvals-and-sandbox，或者以交互方式用提权后的权限批准。

三种角色

| | 适用于 | 备注 |
| 🧩 staffer | 另外两种都不适合的任何任务 | 极简提示词 —— 没有角色，没有输出格式；仅凭任务文本本身塑造结果 |
| 🔍 researcher | 调研与深度分析 | 自行收集证据，返回结构化报告 |
| 🔧 implementer | 对工作区进行修改 | companion 会随结果一并报告 git 差异，并告知调用方去检查它 |

这三种都在后台运行。还有一种内部的 ask 模式 —— 无工具、前台运行 —— 主要用于对链路做冒烟测试。

使用任务

派发任务会立即返回一个任务 id。

| 命令 | 作用 |
| wait --timeout 10m | 阻塞直到完成 —— 打印结果时退出码 0，仍在运行时退出码 2 |
| result | 已完成的输出 |
| observe | 进度快照：最近的工具调用、最新文本 |
| cancel | 停止任务并清理进程树 |
| continue --job | 在同一对话中继续追问 |
| restart | 以全新的预算重新运行，保留旧记录 |

进度是真实的投影，而不是一个转圈动画 —— runner 会为每次工具调用和每条助手消息流式输出一条记录，因此 observe 会返回最近五次调用及其输入和输出摘录，并限制在 8 KiB 以内，这样失控的任务就不会淹没你的上下文。

超时是被妥善处理的，而不是被吞掉：一个在产生文本后触及时限的任务会连同警告一起交付那段文本；一个什么都没产生的任务会报告 attention，并附上对话 id、最后一次快照，以及一条用于继续的确切命令。

在宿主会话中，你通常通过 jobs 技能来使用这一切，而不是手动输入命令。

配置

全部通过环境变量 —— 没有需要学习的配置文件。

export DEEPSEEK_API_KEY=bash
export DEEPSEEK_BASE_URL=https://your-gateway/v1 # 可选：任何兼容 OpenAI 的端点
export DSH_STAFF_DEFAULT_MODEL=deepseek-flash # 你的端点所提供的任意 id
export DSH_STAFF_THINKING=off # 可选，参见“速度”一节

[!TIP]
DEEPSEEK_BASE_URL 必须包含 API 路径前缀。 dsh 请求的是 ${base}/chat/completions，因此位于 /v1 下的网关需要写成 https://host/v1。如果只指向裸主机名，你会得到 STREAM_CLOSED: SSE stream ended without [DONE]——这其实是 dsh 把 HTML 页面当作事件流来解析了。它读起来像流式传输的 bug，但并不是。

模型 id 属于你的端点。 内置的各角色默认值是 DeepSeek 的公开 id；网关通常会给它们加上不同的命名空间。设置一次 DSH_STAFF_DEFAULT_MODEL，就不用每次都传 --model 了。

权限

两个配置文件，映射到 dsh 自带的预设上——无需维护单独的允许列表。

| 配置文件 | dsh 预设 | 审批 | 何时使用 |
| unrestricted （默认） | danger-full-access | 从不 | 无头运行——没有任何东西可以回应提示 |
| restricted | workspace-write | 询问 | 用于让某个模式不去触碰任何东西 |

在无头运行中，没有人会回应审批，因此在 restricted 下，第一个需要审批的工具调用会返回空响应。这两个配置文件都不是针对不可信输入的沙箱——那种情况请使用隔离的检出目录。

遥测

dsh 默认启用了向 DeepSeek 导出 OTEL 会话。由于这通常指向私有仓库，安装的覆盖层会禁用该插件，并且每次运行还会设置 DSH_TELEMETRY_DISABLED=1。若要重新启用，请撤销这两项。

速度

最大的一个杠杆是关闭模型的推理阶段： bash
export DSH_STAFF_THINKING=off

deepseek-flash 在每次回答前都会进行推理，而智能体循环在每一次往返中都要为此付出代价。在两种任务形态上测量，同一端点，该标志是唯一的变量：

| 任务 | 独立运行 | 委派运行 |
| 🔍 研究 | 489s → 133s (−73%) | 515s → 184s (−64%) |
| 🔧 实现 | 209s → 103s (−51%) | 189s → 124s (−34%) |

每个分支的质量都保持不变——研究任务上的引用完全相同，而在编码任务上，四者都产出了结构相同、可正常工作的代码，关闭推理的运行甚至更为详尽。

它默认关闭，因为推理是模型进行规划的方式：对于需要判断力的工作保留它，对于机械性步骤则关闭它。它也是委派看起来要花费 3.4 倍与实际上只花费 23% 之间的差别——因此在得出任何关于委派开销的结论之前，请先关闭它。

到底该不该委派？

docs/BENCHMARK.md（中文）包含了与内联运行相同任务的完整对比、将模型与运行框架区分开的对照实验、质量检查，以及一个没有测量出任何结果的假设——并如实记录为如此。

局限性

- 没有可用的测试套件。 npm test 会故意失败，而不是假装通过。legacy-tests/ 下继承的测试套件针对的是本分支已重命名的文件；移植其中与提供方无关的那一半是这里最大的未完成工作。
- 没有模式强制输出。 结构化输出请求被放在提示词中传递，并不会被强制执行——dsh 没有响应模式（response schema）的等价物。
- dsh 是开发者预览版，其维护者预计会有破坏兼容性的变更。runner/index.mjs 按名称依赖 agents.create、agents.resume 和 session/event 事件流；其中任何一项发生变化都会首先导致故障。
- 这里的测量都是单次运行。 相同配置下的相同任务曾产生 163 秒和 269 秒的结果。可用于选择工作方式，但不适合用于引用。

工作原理

setup 将 runner/index.mjs 作为 Cordis 插件安装到 dsh 配置文件中，替换 dsh 自带的一次性运行器。自带的运行器在每次调用时都会创建一个新会话，并且只打印最终的助手消息——这使得委派运行框架无法继续对话或观察长时间运行的任务。这两种能力在 dsh 核心中已经存在（AgentRegistry.resume() 加载持久化会话；session/event 是实时追加的事件流）；只是没有在那里暴露出来。替换后的运行器将它们暴露出来：

- 会话恢复——使 continue 和 restart 得以工作。
- 记录流，以 NDJSON 格式输出 init / step_update / result——observe、cancel 和超时报告读取的就是它。

其他一切都属于 dsh：它的工具、沙箱、权限预设、压缩、子代理。配套程序（companion/dsh-companion.mjs）负责作业状态机、文件锁定、工作区守卫和 CLI。

贡献

CONTRIBUTING.md——安装设置、耗费了真实调试时间的陷阱、CI 能检查什么和不能检查什么，以及移植测试套件会涉及哪些工作。

致谢与许可 MIT。dsh-staff 是 Keli（pkuwkl）的 agy-staff 的一个分支，从 Google 的 Antigravity CLI 重新定位到 DeepSeek Harness。作业状态机、文件锁定、流式工作器、工作区观察、提示模板和 CLI 界面均源自该项目；dsh 运行器、提供程序层和配置文件覆盖层是本项目的原创内容。两者均为 MIT 许可，上游版权声明保留在 LICENSE 中。