Skip to main content
Glama

agent-worker-mcp

把本机多个 coding agent(DSH、Kimi Code CLI)统一暴露成一个 MCP worker,让 Claude Code / Codex CLI / ChatGPT(桌面)/ Claude Desktop 这些 leader 把重活派给它,并按任务选择执行体。

角色模型:leader(决策、编排)通过 MCP 调用 worker;worker 按任务选择执行体(backend=dsh|kimi,默认 dsh),在真实项目目录里执行长任务(读代码、改文件、跑命令、跑测试),只回传结果与可验收的证据。

现状(本地已验证)

项

状态

单元测试

✅ 216/217 通过(pnpm test;1 项 Windows-only 用例在 macOS/Linux 跳过)

真实链路烟测

✅ MCP Client → worker → 真实 DSH:问答 + 写文件(hello-dsh.txt)全链路通过

长驻后端(M1)

✅ 默认 backend=sdk:真实烟测首任务 9s(含一次初始化)、第二任务 3s;大仓库真实任务 18.4s(含 initialize);headless 保留为 fallback

远程传输(M2a)

✅ WORKER_TRANSPORT=http:真实 HTTP 冒烟通过(/healthz 200、无 token 401、MCP HTTP 客户端跑真实任务 8s)

审批桥(M2b)

✅ worker_result 检测审批阻断 → elicitation 询问授权 → 以 danger-full-access 重试(4 个单测覆盖;真实 DSH 审批场景未端到端实测)

运维治理(M3)

✅ 任务 TTL 自动清理 + 数量上限(超额淘汰最老已结束任务)、每仓库并发配额、审计日志(worker_audit)、任务列表(worker_tasks)、完整产物分页读取(worker_read_result)

批量/检索/观测(M4)

✅ worker_batch_run/status/result 批量派发与聚合、worker_search 历史任务内容检索、worker_metrics 指标快照、轻量 OTel span 导出(真实冒烟捕获到 2 条 dsh.task span)

编码与写文件

✅ workspace-write 中文 UTF-8 写入/读回(字节 E4 B8 AD…);read-only 中文输出经 worker 自动双层兼容修复后回归正常(实测 read-only / workspace-write 均返回 中文探针:你好、无 �)

Windows ACL 沙箱降级(v0.6.6 → v0.9.2)

✅ 公司仓库等「仅 Modify ACL」目录请求 workspace-write 时会遇 SetNamedSecurityInfoW failed (Win32 5): grantWrite;worker 按 worktree(workspace-write)→ danger-full-access 两级兜底,worker_result.sandbox_fallback/effective_permission_mode 记录实际模式。v0.9.2 起:① 首条 ACL 失败 fail-fast 立即中止 attempt;② worktree 再失败会二次升级 full;③ attempts/sandbox_blocked 完整归因;④ WORKER_ALLOW_FULL_ACCESS_FALLBACK=0 可禁止自动全权。worktree 根目录同样必须「完全控制」(默认 ~/dsh-worktrees 满足;改到 D 盘受限目录会失效)

委派粒度策略(v0.6.4)

✅ 规则改为「一个 worker_run = 一个可验收工作单元(实现+自测+证据),禁止微任务」;长轮询上限 25s→可配 120s(WORKER_STATUS_WAIT_MAX_S),减少 leader 往返;规则已写入 ~/AGENTS.md、~/.codex/AGENTS.md、worker instructions 与 docs/delegation-playbook.md

执行记录分析(v0.6.5)

✅ 分析 11-02~11-09 的 64 个任务/200 条审计:修复「长任务被空闲回收误杀」(11 分钟任务、13.3M token 沉没)与「read-only 任务被 ACL 文本误判 failed」;新增 worker_status 实时 tokens/steps/tool_calls、worker_result.partial_output/failure_kind、token 预算护栏 WORKER_MAX_TASK_TOKENS、ACL 失败 cwd 缓存(报告见 D:\work\tmp\dsh-record-analysis\DSH-MCP执行记录分析-2026-11-09.md)

续聊恢复(v0.6.3)

✅ DSH SDK 协议无 resume;worker 重建后用旧 session_id 续聊会报 session "..." already exists。worker 自动换新 session id 重试,并把上一轮任务/结果摘要作为「续聊上下文」拼入;真实两进程验证:A 建 session → B 续聊 succeeded(output=ok2),事件含 session_resume_fallback

易用性升级(v0.7.0)

✅ auto 模式 + cwd 能力缓存(跨进程,避免每次撞 ACL)+ 自动 worktree(受限仓库改到可写 worktree)+ 能力缓存 TTL 可调 + 瞬态失败自动重试 + 失败诊断 + worker_run(wait_s) 单调用等待 + MCP 调用/字节指标 + 任务完成 webhook/命令通知

性能与协议(v0.8.0)

✅ worker_status 有界事件摘要(单条 ≤2KiB、单次 ≤16KiB,可配)、session_id 实时回填与别名锁、事件追加串行化(避免并发写坏 JSONL)、auto 模式优先 worktree

结构化证据(v0.9.0)

✅ worker_result.evidence(命令+退出码/编辑/git 变更+diff)与 outcome(completed/needs_decision/failed/cancelled);[DSH:NEEDS_DECISION] 决策协议;worker_status 默认 detail=summary;`worker_read_result(source=diff

证据补全(v0.9.1)

✅ evidence.edits 支持真实 DSH 的 write/edit/apply_patch 与 file_path;untracked 文件渲染进 diff.patch(new file + + untracked: N files)

worktree 安全与归因(v0.9.2)

✅ ACL fail-fast(首条命令 ACL 失败立即中止 attempt,不再空转烧 token);worktree 重试失败后二次升级 danger-full-access;worker_result.attempts(逐次尝试+首次决策文本)、sandbox_blocked/sandbox_blocked_detail 结构化归因;取消/失败不再丢 ACL 归因,也不会「命令全失败却 succeeded」;worktree 按 TTL 自动 git worktree remove/prune 清理

worktree 根记忆与审批桥(v0.9.3)

✅ worktree 根 ACL 不可用会被写入能力缓存(同 root 的后续任务直接跳过 worktree 尝试,复用 WORKER_CAPABILITY_TTL_H TTL 后自动重试);审批桥在 elicitation 不可用/用户拒绝时返回结构化 approval.retry_args(permission_mode=danger-full-access + cwd + timeout_s),leader 可直接重提

仓库级并发与合入指引(v0.9.4)

✅ 并发配额改为按 git 仓库根 计(同仓库不同子目录、worktree 任务也串行;非 git 目录回退按 cwd);worker_result.worktree.base_commit + merge_hint(base_commit / patch_path / 可直接执行的 apply_command / 审阅提示),worktree 改动可结构化合入原仓库(不自动 apply)

目标测量(v0.6)

✅ worker 侧 DSH token 计量(worker_result.usage.tokens / worker_metrics.tokens)+ A/B 对照工具 + leader 用量扫描器;真实首测:加速 2.29x、leader token 省 46.0%、cost 省 31.1%、达成率 2/2

用量与成本(v0.10.0,合并自本机在用版 bridge)

✅ worker_usage 按天/cwd 聚合任务数、状态分布、耗时、DSH token 与费用估算(WORKER_PRICE_* 单价 / WORKER_USD_CNY 汇率);worker_result.usage.cost_usd/cost_cny、worker_metrics.cost;worker_result 支持 offset/max_chars 分页续读

幂等与防孤儿(v0.10.0,合并自本机在用版 bridge)

✅ worker_run(idempotency_key) 重复提交返回同一 task(落盘索引 + 进程内并发去重,默认 24h);stdio 模式下父进程退出(stdin end/close)会终止运行中 worker,避免孤儿进程

macOS 适配(v0.10.0)

✅ 非 Windows 允许主目录作为 cwd(Windows 保留 ACL 沙箱限制)、兼容旧配置 WORKER_ALLOWED_ROOTS、默认超时 900→1800s、新增 scripts/monitor-thread.py(Codex thread 配额/token 监控);macOS 实测 sdk 后端 + 桌面 app 内置 CLI(0.2.2)(经 wrapper 暴露)真实任务跑通

cwd 安全校验

✅ Windows 拒绝用户主目录(ACL 沙箱限制);macOS/Linux 允许(v0.10.0 起,与在用版 bridge 对齐)

Claude Code 接入

✅ 已注册(user scope)并实测连通:claude mcp get dsh → √ Connected;claude -p 真实调用 worker_describe 成功

Codex 接入

✅ 已写入 ~/.codex/config.toml,codex mcp get dsh 解析正常;已实测真实调用:ChatGPT/Codex 桌面 app(OpenAI.Codex 26.1103)17:54 按会话拉起 v0.9.1 worker,MCP initialize 返回 serverInfo.version=0.9.1、13/13 工具与白名单一致、approve 免打扰生效(13 次工具调用无弹窗)

ChatGPT 桌面 app

✅ 已实测:本机 ChatGPT 桌面入口即 OpenAI.Codex 包(ChatGPT.exe 是包内 shell,codex.exe app-server 拉起 worker),共享 ~/.codex/config.toml;2026-11-10 真实委派任务(4a530bab)跑通 MCP 全链路(失败点是 D 盘 worktree 根 ACL,见 v0.9.2)

ChatGPT web

⏸ 后置(需要 OpenAI Secure MCP Tunnel 或自建 HTTPS + OAuth)

Claude Desktop(MCPB)

⚠️ 未实测(examples/mcpb-manifest.json 已给出模板)

注册记录(2026-11-02):Claude 侧改的是 ~/.claude.json;Codex 侧在 ~/.codex/config.toml 末尾追加了 [mcp_servers.dsh],改前已备份为 config.toml.bak-dsh-registration-20261102。 撤销:claude mcp remove dsh -s user;codex mcp remove dsh(或从 config.toml 删掉对应块)。

Related MCP server: muster

架构

leader(Claude Code / Codex / ChatGPT / Claude Desktop)
   │  MCP over stdio(本地)或 Streamable HTTP /mcp + Bearer(远程)
   ▼
agent-worker-mcp(本进程)
   │  worker_run 立即返回 task_id;任务后台执行
   │  任务落盘:meta.json / events.jsonl / result.txt
   ▼  后端可切换(WORKER_BACKEND)
   ├─ sdk(默认):长驻 `dsh --profile sdk`,一次 initialize,之后每个任务只发 session/prompt
   └─ headless:`dsh --profile headless --json "<task>"`,每任务一个进程
   │  NDJSON 事件:session → status/tool_call/tool_result → final
   ▼
真实文件系统 / shell(cwd 必须是项目目录;默认 workspace-write)

快速开始

cd C:\path\to\agent-worker-mcp
pnpm install
pnpm build
pnpm test          # 216 个单测(1 项 Windows-only 跳过)
pnpm smoke         # 真实 DSH 集成烟测(约 30–60s)

macOS/Linux 同样适用:把 cd C:\path\to\agent-worker-mcp 换成仓库路径即可。macOS 上 DSH 用桌面 app 自带的 CLI(sdk 后端,见下文「macOS / Linux + Codex 部署」),不要重复安装 pnpm 全局 dsh。

worker 通过 stdio 工作,自身不监听任何端口。需要它时由 leader 拉起子进程。

本机安装(推荐 pnpm 全局)

源码仓库只用于开发(pnpm build / pnpm test);MCP 客户端加载 pnpm 全局安装的正式包,不要指向源码仓库。

pnpm add -g agent-worker-mcp@latest      # 安装/升级
pwsh -File scripts/mcp-entry.ps1       # 输出 MCP 入口(pnpm 全局包内 dist/index.js)

把输出的入口配置给 leader(Codex/ChatGPT 的 ~/.codex/config.toml 或 Claude Code):

[mcp_servers.dsh]
command = "node"
args = ["<scripts/mcp-entry.ps1 输出的路径>"]
  • 升级:pnpm update -g agent-worker-mcp → 重启 leader 会话;若入口路径变化,用 scripts/mcp-entry.ps1 刷新配置;

  • 不要用 cmd /c agent-worker-mcp 作为 MCP 入口:cmd 包装下 worker_describe 正常但真实任务会卡住(已实测),必须用 node + 全局包入口;

  • 源码开发调试可选:scripts/deploy.ps1 部署到独立目录(内容等价 npm 包),不用于本机日常使用。

macOS / Linux + Codex 部署(从本机在用版 bridge 迁移)

本仓库同时兼容 Windows 与 macOS/Linux。若你之前在生产用的是零依赖单文件版 bridge(~/scripts/dsh-mcp/server.mjs,v2.2.0,工具面 4 个:dsh_dispatch / dsh_job / worker_usage / worker_status),v0.10.0 已把它的核心能力合并进来:

能力

在用版 server.mjs

本仓库 v0.10.0

派活/等待/取消

dsh_dispatch / dsh_job

worker_run / worker_status / worker_result / worker_cancel(另有批量、结构化证据、worktree、审批桥)

用量与成本

worker_usage(解析 dsh 会话日志)

worker_usage(按天/cwd,基于任务记录)+ worker_result.usage.cost_* + worker_metrics.cost

幂等键

idempotency_key

✅ 同语义(落盘索引,默认 24h)

防孤儿进程

stdin 关闭 → kill worker

✅ stdio 模式已对齐

cwd 白名单

WORKER_ALLOWED_ROOTS

兼容该变量;主变量仍是 WORKER_ALLOWED_CWDS

默认超时

1800s

1800s(v0.10.0 起;旧默认 900s 偏小)

输出续读

字节 offset / max_bytes

worker_result(offset, max_chars) 字符分页 + worker_read_result

DSH 版本与凭据(macOS 实测,2026-11-11):

  • 唯一安装:桌面 app 自带的 CLI(本机 DeepSeek Harness.app,CLI 版本 0.2.2-rc.1)。它的 sdk profile 能复用 GUI 凭据:实测 v0.10.0 WORKER_BACKEND=sdk + 该 CLI 真实任务跑通(worker_run → worker_result.output、usage.tokens 与费用估算全部正常),无需在 MCP 配置里写 API key。

  • app 路径含空格(DeepSeek Harness.app),而 WORKER_DSH_COMMAND 走 shell:true 会被拆开,所以必须用无空格 wrapper 暴露入口(见迁移步骤 2.5)。

  • 不要为 worker 单独 pnpm add -g @deepseek-ai/dsh:会与 app 内置 CLI 重复安装。本机曾同时存在 pnpm 全局 0.1.5-rc.2 与 app 内置 0.2.2-rc.1,已移除前者;两者版本不一致还会导致事件格式/凭据行为差异。

  • app 内置 CLI 的 headless(--json)在独立 CLI 进程下可能读不到 GUI credentials service(MISSING_CREDENTIAL),所以 macOS 上优先 sdk 后端。

  • 结论:macOS 上 WORKER_BACKEND=sdk + WORKER_DSH_COMMAND 指向 wrapper(内部 exec app 内置 CLI)。

迁移步骤(保留在用版作为回滚):

  1. 备份 Codex 配置:cp ~/.codex/config.toml ~/.codex/config.toml.bak-before-agent-worker-mcp

  2. 构建本仓库:

    cd ~/workspace/code/github/agent-worker-mcp
    pnpm install && pnpm build

2.5. 创建 app 内置 CLI 的无空格入口 wrapper(macOS;路径按本机替换):

printf '#!/bin/sh\nexec "/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" "$@"\n' > ~/scripts/dsh-app-cli.sh
chmod +x ~/scripts/dsh-app-cli.sh
~/scripts/dsh-app-cli.sh --version   # 应输出版本号(如 0.2.2-rc.1)
  1. 安装 pnpm 全局正式包(pnpm add -g agent-worker-mcp@latest),把 ~/.codex/config.toml 的 [mcp_servers.dsh-worker] 指向 pnpm 全局 bin shim(command = $(pnpm bin -g)/agent-worker-mcp,升级后自动跟随,无需改路径;也可用 node + 构建产物 dist/index.js),并补上 sdk 后端与白名单(路径按本机替换):

    [mcp_servers.dsh-worker]
    command = "/Users/<you>/Library/pnpm/bin/agent-worker-mcp"
    args = []
    cwd = "/Users/<you>"
    enabled = true
    startup_timeout_sec = 60
    tool_timeout_sec = 1800
    default_tools_approval_mode = "approve"
    
    [mcp_servers.dsh-worker.env]
    HOME = "/Users/<you>"
    DSH_HOME = "/Users/<you>/.dsh"
    WORKER_BACKEND = "sdk"
    WORKER_DSH_COMMAND = "/Users/<you>/scripts/dsh-app-cli.sh"
    WORKER_DSH_PATCH = "off"
    WORKER_ALLOWED_ROOTS = "/Users/<you>"
    WORKER_MAX_CONCURRENT = "4"
    WORKER_TIMEOUT_S = "1800"
    PATH = "/Users/<you>/.nvm/versions/node/v24.19.0/bin:/Users/<you>/Library/pnpm/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
  2. 重启 Codex / ChatGPT 桌面 app(MCP 工具目录在握手时协商),先在会话里调用 worker_describe / worker_usage 验证,再跑一个真实任务。 也可不挂载直接自检:

    printf '%s\n' \
     '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \
     '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
     | WORKER_BACKEND=headless node dist/index.js 2>/dev/null | tail -1 | head -c 400
  3. 回滚:还原第 1 步的配置备份并重启 leader 即可。

两版可并存对比(用不同的 MCP server 名);它们的任务目录互不冲突(在用版 ~/.dsh-mcp/jobs vs 本仓库 $DSH_HOME/mcp-tasks)。

通过 npm 使用

包名:agent-worker-mcp(只发布构建产物;本机仍需安装 DSH)。

npm i -g agent-worker-mcp      # 或直接用 npx
npx -y agent-worker-mcp        # 由 MCP 客户端拉起(stdio)

MCP 客户端配置可用:

{
  "mcpServers": {
    "dsh": { "command": "npx", "args": ["-y", "agent-worker-mcp"] }
  }
}

注意:npm 包不包含 DSH 本体;worker 通过 dsh(PATH)、WORKER_DSH_DIR 或 WORKER_DSH_CLI 找到本机 DSH。

接入 leader

1) Claude Code(最省事)

claude mcp add --scope user --transport stdio dsh -- node "C:\path\to\agent-worker-mcp\dist\index.js"
claude mcp list
claude mcp get dsh

带环境变量时注意 --env 的位置(放在 server 名之前):

claude mcp add --scope user --transport stdio --env WORKER_DEFAULT_CWD="D:\work\repo" dsh -- node "C:\path\to\agent-worker-mcp\dist\index.js"

等价 .mcp.json 见 examples/claude-mcp.json。

避免每次弹授权:把 dsh 工具加入用户级 allowlist(~/.claude/settings.json 的 permissions.allow):

["mcp__agent-worker-mcp__worker_run", "mcp__agent-worker-mcp__worker_status", "mcp__agent-worker-mcp__worker_result", "mcp__agent-worker-mcp__worker_cancel", "mcp__agent-worker-mcp__worker_describe",
 "mcp__agent-worker-mcp__worker_tasks", "mcp__agent-worker-mcp__worker_audit", "mcp__agent-worker-mcp__worker_read_result", "mcp__agent-worker-mcp__worker_batch_run",
 "mcp__agent-worker-mcp__worker_batch_status", "mcp__agent-worker-mcp__worker_batch_result", "mcp__agent-worker-mcp__worker_search", "mcp__agent-worker-mcp__worker_metrics",
 "mcp__agent-worker-mcp__worker_usage"]

本机已写入(备份 settings.json.bak-dsh-allow-20261102)。安全边界仍由 worker 的 permission_mode / 审批桥承担。

2) Codex CLI / IDE

把下面加到 ~/.codex/config.toml(完整示例见 examples/codex-config.toml):

[mcp_servers.dsh]
command = "node"
args = ["C:\\path\\to\\agent-worker-mcp\\dist\\index.js"]
startup_timeout_sec = 30          # 默认 10;worker 自身启动很快,留余量
tool_timeout_sec = 300            # 默认 60;allow worker_status 长轮询(wait_s≤120s)
enabled_tools = ["worker_run", "worker_status", "worker_result", "worker_cancel", "worker_describe", "worker_tasks", "worker_audit", "worker_read_result", "worker_batch_run", "worker_batch_status", "worker_batch_result", "worker_search", "worker_metrics", "worker_usage"]
# approve = 不再询问(auto 仍会按风险询问);安全边界由 worker 的 permission_mode(默认 workspace-write)兜底
default_tools_approval_mode = "approve"

# 桌面端对 MCP 工具的审批可被 per-tool 覆盖(14 个工具都要写)
[mcp_servers.dsh.tools.worker_run]
approval_mode = "approve"
# ……其余工具同理:worker_status / worker_result / worker_cancel / worker_describe / worker_tasks / worker_audit /
# worker_read_result / worker_batch_run / worker_batch_status / worker_batch_result / worker_search / worker_metrics / worker_usage

[mcp_servers.dsh.env]
WORKER_DEFAULT_CWD = "C:\\path\\to\\your\\project"

校验:codex mcp get dsh(本机已配置为 default_tools_approval_mode: approve + per-tool approve;改前备份 config.toml.bak-dsh-approve-20261102)。改完需完全退出并重开 Codex/ChatGPT 桌面 app,配置在 app 启动时加载。

3) ChatGPT 桌面 app

调研显示 ChatGPT 桌面 app、Codex CLI、IDE 扩展共享同一份 ~/.codex/config.toml,所以按上面 Codex 的配置配好后重启桌面 app 即可使用(未实测,若无效请反馈)。

4) ChatGPT web(后置)

ChatGPT web 只接受远程 MCP(Streamable HTTP / SSE),不接受 stdio。两条路:

  • 推荐:OpenAI Secure MCP Tunnel(需要 Platform 组织 + tunnel_id + runtime API key):

    tunnel-client init --sample sample_mcp_stdio_local --profile dsh-local \
      --tunnel-id tunnel_xxxxxxxx --mcp-command "node C:\\path\\to\\agent-worker-mcp\\dist\\index.js"
    tunnel-client run --profile dsh-local

    然后在 ChatGPT → Plugins → + → Add custom MCP server → Connection 选 Tunnel → Create。 注意 Tunnel 硬限制:单请求 120s / 10 MiB / 600 rpm,所以必须用本 worker 的异步任务模型(run 立即返回 + 轮询)。

  • 或自建 HTTPS + OAuth 2.1(工作量大,暂未实现)。

5) Claude Desktop(本地 MCPB)

模板见 examples/mcpb-manifest.json。需要把 dist/ 与 node_modules 一起打包进 MCPB 扩展,用 mcpb pack 生成 .mcpb 后拖入 Claude Desktop(未实测)。

工具面

工具

作用

关键参数

worker_run

提交任务,立即返回 task_id

task(必填)、cwd(必填,项目目录)、session_id?、permission_mode?、timeout_s?、idempotency_key?

worker_status

查状态 + 有界事件摘要;默认 detail=summary 只回状态/异常事件 + last_text,detail=events 回全部事件;终态带 outcome

task_id、cursor?、wait_s?、detail?(summary/events)

worker_result

取最终结果;验收优先看 evidence(命令退出码/变更文件/diff 摘要)与 outcome,output 是 DSH 叙述;传 offset/max_chars 可直接分页续读

task_id、offset?、max_chars?

worker_cancel

取消任务(杀进程树)

task_id

worker_tasks

列出最近任务摘要(回顾/继续轮询)

limit?(1–100)、status?

worker_audit

读取审计事件(任务生命周期/审批决定)

limit?(1–200)

worker_read_result

分页读取落盘产物

task_id、source?(result/events/diff/evidence)、offset?、max_chars?

worker_batch_run

批量并行派发(每项可带 cwd/session/权限)

tasks[](1–maxBatchTasks)

worker_batch_status

批量聚合状态(整体状态 + 子任务 + 计数)

batch_id、wait_s?

worker_batch_result

批量聚合结果(输出/错误/耗时)

batch_id、max_output_chars?

worker_search

在历史任务的输出与工具结果里检索

query、limit?

worker_metrics

计数/耗时分位/排队/后端/OTel 状态 + token 与估算费用汇总

—

worker_usage

按时间窗口聚合用量与费用(任务数/状态/耗时/DSH token/估算费用,按 cwd 分布)

days?(1–90)、cwd?

worker_describe

返回入口/默认值/限制,供 leader 自适应

—

典型调用序列(leader 视角):

// 1) 提交
{ "name": "worker_run", "arguments": { "task": "修复 utils.ts 的空指针,并跑 pnpm test 验证", "cwd": "D:\\work\\repo" } }
// → { task_id, status: "queued", session_id, cwd, hint }

// 2) 轮询(每次最多等 25s;运行中会收到 notifications/progress)
{ "name": "worker_status", "arguments": { "task_id": "...", "cursor": 0, "wait_s": 20 } }

// 3) 结束后取结果
{ "name": "worker_result", "arguments": { "task_id": "..." } }

状态机:

queued ──▶ running ──▶ succeeded
   │           ├──▶ failed(超时/DSH 报错)
   │           ├──▶ cancelled
   └──▶ 不会出现:被取消的排队任务会直接 cancelled

多轮续聊:把首次 worker_run 返回的 session_id 传给下一次 worker_run;同一 session 的任务串行执行(DSH 侧单写者),不同 session 并行(受 WORKER_MAX_CONCURRENT 限制)。

让 leader 主动委派(可选,推荐)

MCP 只把工具摆给 leader,是否调用由 leader 模型自己决定,协议层无法强制。想提高“自动委派”概率,三档手段(从弱到强):

  1. 工具描述/instructions(已内置):worker_run 描述与 server instructions 写明「一个任务 = 一个可验收工作单元(实现+自测+证据);禁止微任务;长轮询 60–120s」——这是 ChatGPT web / Claude Desktop 等远程 leader 唯一可用的杠杆。

  2. 指令文件(本地 leader 有效):

    • Claude Code:~/.claude/CLAUDE.md(本机通过 @~/AGENTS.md 引用);

    • Codex:~/.codex/AGENTS.md(全局);或项目内 AGENTS.md(就近生效)。 本机已写入「粗粒度委派」规则(AGENTS.md.bak-dsh-coarse-20261102 为改前备份)。

  3. Hook(仅 Claude Code 等支持 hook 的 host):UserPromptSubmit 每次注入提醒,最稳但配置成本最高。

注意:远程 leader(ChatGPT web / Claude Desktop)读不到本地指令文件,只能靠第 1 条 + 用户明说「用 dsh 跑」。

粒度怎么定(关键)

  • 一个 worker_run 覆盖「定位 → 实现 → 自测 → 证据」,典型:一个功能点 / 一个 bug / 一个测试修复批次 / 一次跨文件重构;

  • 少于 3 次工具调用或 2 分钟内能做完的事,leader 自己做;不要拆成多个 dsh 任务;

  • 只有独立可并行(用 worker_batch_run)、需要决策、风险隔离时才拆分;

  • 轮询用 worker_status(wait_s=60~120),不要在 DSH 执行期间重复劳动;

  • 详细模板、反例/正例、验收动作、如何用 scripts/leader-usage.mjs 验证:docs/delegation-playbook.md。

目标达成率测量(leader 提速 / 省 token)

目标前提:Codex/ChatGPT、Claude Code 作为 leader,通过本 worker 把重活交给 DSH。核对方式:同任务 A/B 对照(leader 自己做 vs 委派 DSH)。

# A/B 对照(会真实消耗 leader 额度;只读分析类任务最安全)
pnpm measure:ab -- --cwd D:\work\repo --task "统计 src 下 ts 文件数量并列出最大的 3 个(只读分析)" --runs 3 --expect "src"

# 持续观察 leader 自己的会话用量(不跑基准)
pnpm measure:leader -- --since-hours 24

报告包含:加速比、leader token 节省率、cost 节省率、正确性守门、DSH token、DSH token / 省下 leader token,以及目标达成率 x/2 或 x/3。

  • 口径/公式/协议/局限:docs/measurement.md

  • 真实首测(单样本,任务:统计 src 下 ts 文件并列出最大 3 个):加速 2.29x、leader token 省 46.0%、cost 省 31.1%、达成率 2/2;报告样例在 measure-runs/report-*.md。

  • leader token 来自 Claude Code -p --output-format json 的 usage/cost;Codex 用 scripts/leader-usage.mjs 从 rollout 聚合;ChatGPT web 无本地计量(见文档局限)。

配置(环境变量)

变量

默认

说明

WORKER_TRANSPORT

stdio

MCP 传输:stdio(本地 leader)/ http(Streamable HTTP,远程 leader)

WORKER_HTTP_HOST

127.0.0.1

HTTP 监听地址;0.0.0.0 时必须设 token

WORKER_HTTP_PORT

7391

HTTP 端口(0 = 随机)

WORKER_HTTP_TOKEN

无

HTTP Bearer token;非回环地址必填

WORKER_DSH_CLI

自动探测

@deepseek-ai/dsh/lib/bin.js 的绝对路径(用 node 启动,最稳)

WORKER_DSH_COMMAND

—

完整命令(如 dsh),通过 shell 启动;优先级低于 WORKER_DSH_CLI

WORKER_DSH_DIR

—

DSH 安装目录(自动拼 node_modules/@deepseek-ai/dsh/lib/bin.js)

WORKER_PROFILE

headless

headless 后端使用的 profile

WORKER_BACKEND

sdk

执行后端:sdk(长驻,默认)/ headless(每任务一进程)

WORKER_SDK_PROFILE

sdk

长驻后端使用的 DSH profile

WORKER_SDK_PROVIDER

deepseek-official

SDK 后端 provider

WORKER_SDK_MODEL

deepseek-flash

SDK 后端 model(进程级固定)

WORKER_SDK_REASONING_EFFORT

无

推理强度(可选,如 max)

WORKER_SDK_MAX_TOKENS

无

单次输出 token 上限(可选)

WORKER_SDK_IDLE_MIN

10

后端空闲多少分钟回收(1–240)

WORKER_SDK_INIT_TIMEOUT_S

300

后端 initialize 超时(秒);失败自动重试 1 次,仍失败则自动降级 headless

WORKER_DEFAULT_CWD

无

省略 cwd 时使用;没设则用 worker 进程 cwd(stdio 启动时通常是 leader 的项目目录)

WORKER_ALLOWED_CWDS

无

分号分隔的允许目录白名单(设置后只能在这些目录下跑)

WORKER_ALLOWED_ROOTS

无

兼容旧版 bridge 的允许目录写法(平台分隔符:POSIX :、Windows ;);WORKER_ALLOWED_CWDS 优先

WORKER_PERMISSION_MODE

auto

默认 auto(worker 按 cwd 能力自动适配);也可显式 read-only / workspace-write / danger-full-access

WORKER_TIMEOUT_S

1800

单任务默认超时(秒);旧默认 900s 实测偏小(v0.10.0 起改 1800)

WORKER_MAX_CONCURRENT

2

全局并发任务上限(1–8,另受同 session 串行约束)

WORKER_MAX_CONCURRENT_PER_CWD

1

同一 git 仓库根(含子目录/worktree 任务)的并发上限;非 git 目录回退按 cwd 计(防止单项目占满)

WORKER_TASK_TTL_MIN

1440

已结束任务保留分钟数,超时自动清理

WORKER_TASK_MAX

500

任务数上限;超额先淘汰最老的已结束任务

WORKER_CLEANUP_INTERVAL_MIN

10

自动清理间隔(分钟)

WORKER_AUDIT_DIR

$DSH_HOME/mcp-audit

审计日志目录(audit.jsonl)

WORKER_BATCH_DIR

$DSH_HOME/mcp-batches

批量任务元数据目录

WORKER_BATCH_MAX

8

单次批量提交的最大任务数(1–32)

WORKER_OTEL_ENDPOINT

无

OTLP/HTTP traces 端点(如 http://127.0.0.1:4318/v1/traces);空 = 关闭

WORKER_OTEL_SERVICE

agent-worker-mcp

OTel service.name

WORKER_DSH_PATCH

apply

DSH 兼容补丁:apply(启动时自动检测+修复①pwsh 编码前缀 ②输出 GBK 兜底解码)/ notify / off

WORKER_ACL_FALLBACK

danger-full-access

workspace-write ACL 失败后的目标模式:danger-full-access(第二级升级)/ read-only / off。执行顺序固定为「原目录 workspace-write → worktree workspace-write → 目标模式」,每级失败都会重新判定

WORKER_ACL_FAIL_FAST

1

首条命令 ACL 失败即立即中止当前 attempt(不再等模型空转/长超时),进入降级决策

WORKER_ALLOW_FULL_ACCESS_FALLBACK

1

是否允许自动升级 danger-full-access;发布给他人使用建议设 0(保持 fail-closed,由 leader 显式选择);read-only 降级不受影响

WORKER_STATUS_WAIT_MAX_S

120

worker_status 单次长轮询等待上限(秒,5–600);调大可减少 leader 轮询次数

WORKER_MAX_TASK_TOKENS

0

暂缓启用:单任务 DSH token 预算,默认 0=不限制、不产生任何行为。实现已完成但按当前决定不开启;待积累 ≥20 条成功任务后,再按任务类型 p90×1.5 校准并启用(totalTokens 94–98% 是 cacheRead,若控成本需另按 input+output 折算)

WORKER_CAPABILITY_CACHE

1

cwd 能力缓存(落盘,auto 模式据此选权限模式),跨 worker 进程;同时记录「worktree 根 ACL 不可用」,避免同 root 反复创建+失败

WORKER_CAPABILITY_TTL_H

24

cwd / worktree 根能力缓存 TTL(小时);修好 ACL 后等 TTL 过期或删缓存文件即可重新尝试 worktree

WORKER_RETRY_TRANSIENT

1

后端崩溃/初始化失败时自动重试一次

WORKER_AUTO_WORKTREE

1

ACL 受限仓库自动创建可写 worktree(仅干净 git 仓库)。worktree 根目录必须对当前用户完全控制,否则 worktree 同样会 ACL 失败

WORKER_WORKTREE_ROOT

~/dsh-worktrees

自动 worktree 根目录;不要指向 ACL 受限的盘/目录(如企业仓库所在的受限 D 盘),默认的用户主目录满足

WORKER_WORKTREE_CLEANUP

1

终态任务过期后自动 git worktree remove/prune(不影响任务证据 diff.patch)

WORKER_WORKTREE_TTL_MIN

1440

worktree 保留时长(分钟),超时由清理任务移除

WORKER_NOTIFY_WEBHOOK

无

任务结束 POST 通知(JSON)

WORKER_NOTIFY_CMD

无

任务结束执行命令(WORKER_NOTIFY_JSON 环境变量传事件)

WORKER_MAX_RESULT_CHARS

40000

结果超长时落盘阈值

WORKER_IDEM_TTL_H

24

幂等键有效期(小时,0 = 永不过期);worker_run(idempotency_key) 重试去重

WORKER_IDEM_DIR

$DSH_HOME/mcp-idem

幂等键索引落盘目录

WORKER_PRICE_INPUT_PER_MTOK

0.28

费用估算:输入 token 单价(美元/百万 token)

WORKER_PRICE_CACHE_READ_PER_MTOK

0.028

费用估算:cacheRead 单价(美元/百万 token)

WORKER_PRICE_OUTPUT_PER_MTOK

0.42

费用估算:输出 token 单价(美元/百万 token)

WORKER_USD_CNY

6.65

费用估算展示用美元兑人民币汇率

WORKER_MAX_STATUS_EVENTS

100

单次 worker_status 最多返回多少条事件(仍受字节预算限制)

WORKER_MAX_STATUS_PAYLOAD_BYTES

16384

单次 worker_status 结构化载荷(JSON)的 UTF-8 字节上限;超出时只返回能放下的摘要并标记 events_truncated

WORKER_EVIDENCE_GIT

1

是否采集 git 证据(status/diff 摘要 + diff.patch);置 0 关闭

WORKER_REPORT_PROTOCOL

1

是否向任务文本注入 [DSH:NEEDS_DECISION] 汇报协议页脚

WORKER_STATUS_DETAIL

summary

worker_status 默认 detail;置 events 回退到旧行为

DSH_HOME

~/.dsh

DSH 状态目录(会透传给子进程)

权限模式说明(DSH 侧行为):

  • read-only:只读任务;

  • workspace-write(默认):项目目录内可读写、可跑命令;越界/提权操作会被 DSH 审批 fail-closed 拒绝(headless 没有审批通道);

  • danger-full-access:全权,谨慎使用(只在明确信任的任务上开)。

任务落盘与恢复

$DSH_HOME/mcp-tasks/<task_id>/
  meta.json      状态、cwd、session、退出码、错误(含 usageTokens 与幂等键)
  events.jsonl   DSH --json 事件流(追加写)
  result.txt     输出超长时的完整结果
$DSH_HOME/mcp-idem/
  idem-<key-hash>.json   幂等键 → task_id 索引(默认保留 24h)

审计日志(append-only,独立于任务目录):$DSH_HOME/mcp-audit/audit.jsonl,记录 task_created / task_started / task_succeeded|failed|cancelled / approval_*;可用 worker_audit 查询。

worker 重启时,未完成的 queued/running 任务会被标记为 failed(interrupted: worker restarted before the task finished),不会假装成功。

安全模型

  • 只走 stdio 或显式 HTTP:默认 stdio 不监听端口;HTTP 模式必须 Bearer token(0.0.0.0 无 token 直接拒绝启动)。

  • cwd 校验:拒绝用户主目录及其祖先目录(Windows ACL 沙箱会让 shell 工具不可用),可加 WORKER_ALLOWED_CWDS 白名单。

  • 默认 fail-closed:无人值守没有审批通道(两种后端一致),需要审批的操作一律拒绝,不会静默放权。

  • 取消即杀进程树(Windows taskkill /T /F),避免僵尸 DSH。

  • 输出有界:超长结果落盘,避免撑爆 leader 上下文。

已知限制

  1. 冷启动:sdk 后端首次任务支付一次 initialize(本机实测 7–30s,随机器负载波动),之后每任务只付模型时间(实测 3s 级);headless 后端每任务 4–11s(fallback)。initialize 超时默认 300s,失败自动重试 1 次;仍失败则自动降级 headless 重跑同一任务(避免 leader 直接看到一次失败)。

  2. sdk 后端没有 cancel 协议:worker_cancel 等价于杀掉该 cwd 的后端进程,下次任务自动重建(已实测);同一 cwd + 权限模式共享一个后端。

  3. sdk 后端模型/权限是进程级:模型由 WORKER_SDK_MODEL 固定;不同 permission_mode 会走不同后端进程。

  4. session_id 复用仅在同一个后端进程生命周期内可靠;进程被回收/杀掉后同 id 行为未验证。

  5. --json 事件流对非 final 字段有 8 KiB / 32 KiB 截断,final 无损;完整轨迹看 events.jsonl。

  6. 同一 session_id 只能串行;并发续聊需拆成不同 session。

  7. Progress 通知依赖 leader 传 progressToken;不传时只是没有进度事件,不影响任务。

  8. HTTP 模式是无状态的:每个请求独立创建 server/transport,不做 MCP 会话;进度通知只在单次请求的 SSE 流内有效。

  9. 任务会被自动清理:超过 WORKER_TASK_TTL_MIN 的已结束任务(含落盘目录)会被删除,之后查询返回 task_not_found。

  10. 授权弹窗由 leader 侧配置决定:Codex/ChatGPT 的「不询问」值是 approve(auto 仍会按风险询问;writes 只对写工具询问;prompt 全问),建议 default_tools_approval_mode = "approve" + 每个工具的 [mcp_servers.dsh.tools.<tool>] approval_mode = "approve",并完全退出重开 app;Claude Code 用 permissions.allow。桌面端另有已知 bug(openai/codex#40793、#20289:部分版本线程内仍每次询问、忽略 approval_mode),遇到底座 bug 只能点「始终允许」、升级 app 或改用 Claude Code/CLI。关闭逐次确认后安全边界由 worker 的 permission_mode(默认 workspace-write)与审批桥 fail-closed 兜底。

  11. initialize 偶发卡顿:initialize 正常 7–30s;曾出现 >120s 超时(旧默认值)导致任务失败,现已改为 300s + 重试 + headless 降级,并在错误里带 stderr 证据。

  12. Windows ACL 沙箱要求目录为「完全控制」:DSH 的 workspace-write 会给工作目录写能力 SID + Low 标签,要求调用方对目录拥有完全控制(含 WRITE_OWNER);公司仓库常见继承 ACL 只有 Modify → SetNamedSecurityInfoW failed (Win32 5)。v0.9.2 起降级链为「原目录 workspace-write → worktree workspace-write → WORKER_ACL_FALLBACK」:首条 ACL 失败即 fail-fast 中止,worktree 再失败会 二次升级;结果里 attempts / sandbox_blocked(_detail) / sandbox_fallback / effective_permission_mode 显式记录,绝不静默假成功。worktree 根目录本身也必须完全控制(2026-11-10 真实任务因 D:\work\worktrees\dsh 只有 Modify 而空转,已由 fail-fast + 二次升级修复);可用 WORKER_ACL_FALLBACK=read-only|off 收紧。

  13. 自动升级的 full access 无沙箱:任务在 danger-full-access 下可读写当前用户能访问的任意路径;这是为「调用简单」有意选择的 B 方案,请配合 WORKER_ALLOWED_CWDS 限定目录、审计日志与 git 回滚使用;高敏感仓库建议用 read-only 或 off。

  14. 审计日志无轮转:audit.jsonl 持续追加,长期使用需自行归档/切割。

  15. ChatGPT 直连未打通:需要 Secure MCP Tunnel(无配额未实测)或自建 HTTPS + OAuth 2.1(OAuth 未实现);本地 HTTP + Bearer 给不了 ChatGPT。

  16. 审批桥 v0 是粗粒度:只做「检测审批阻断 → elicitation 询问 → 整任务以 danger-full-access 重试」,且真实 DSH 审批场景尚未端到端实测。

  17. 批量/检索的边界:批量元数据(batch_id → task_ids)落盘可跨重启,但子任务本身仍受 TTL 清理;worker_search 只扫内存中保留的任务(被清理的历史任务搜不到)。

  18. OTel 是轻量实现:不引 OTel SDK,只把每个任务的 span 以 OTLP/HTTP JSON 推送(best-effort,3s 超时);指标是 worker_metrics 拉取式快照,未做 OTLP metrics 推送。

  19. read-only 下的 pwsh 编码问题(已自动双层修复):DSH 的 dsh-pwsh-local 会给每条命令前缀 [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false);read-only 的 Windows ACL 沙箱以 ConstrainedLanguage 启动 pwsh,构造 .NET 类型被拒 → 每次调用两条 InvalidOperation: 无法创建类型…。跳过该前缀后,无控制台 spawn 的 pwsh 又会按系统代码页(GBK)写 stdout/stderr,而 DSH 固定按 UTF-8 解码 → 中文输出/错误乱码。worker 启动时自动修两层:① 前缀改为仅非 ConstrainedLanguage 执行;② dsh-subprocess-local 的输出解码改为「UTF-8 严格解码失败 → GBK 兜底」(合法 UTF-8 输出不受影响)。均带备份、幂等;DSH 升级后下次启动自动重打。可用 WORKER_DSH_PATCH=notify|off 关闭自动修复,手动脚本见 scripts/patch-dsh-pwsh-encoding.ps1 与 scripts/patch-dsh-output-decoding.ps1。

  20. ChatGPT web / Claude Desktop 两条远程/打包路径尚未实测。

  21. 续聊 session 不能跨后端恢复(已自动恢复):DSH SDK 协议只有 initialize/session/prompt/shutdown,没有 resume/restore;worker 重启或后端重建后用旧 session id 续聊会报 session "..." already exists。worker 自动换新 session id 重试一次,并把上一轮任务/结果摘要作为「续聊上下文」拼进新指令(事件 session_resume_fallback 可见;结果里的 session_id 是新 id)。同一后端存活时则正常续聊、不触发恢复。

  22. 长任务空闲回收(v0.6.5 已修):此前 sweep() 只看 lastUsedAt,运行超过 10 分钟的任务会被回收杀掉(真实 11 分钟任务、13.3M token 沉没);现在有 in-flight prompt 的后端不会被回收,任务结束刷新时间。

  23. read-only 的 ACL 误判(v0.6.5 已修):此前只要事件/最终文本里出现 SetNamedSecurityInfoW 就会被当作写沙箱失败,导致已产出完整报告的只读任务被标 failed;现在仅「非 read-only 模式 + tool_result.isError」才判定。

  24. token 预算默认关闭:WORKER_MAX_TASK_TOKENS=0;建议真实使用设 3M–8M,防止单个失控任务烧掉大量额度。超限任务会被取消并标 failed(不是用户取消),事件流有 token_budget_exceeded。

  25. 自动 worktree 只对干净 git 仓库生效:有未提交改动/非 git 仓库不会复制(直接进入 ACL 降级链的下一级)。worktree 默认按 WORKER_WORKTREE_TTL_MIN(24h)自动 git worktree remove/prune;清理前如需合入,用 worker_result.worktree 路径审查,diff.patch 证据不受清理影响。

  26. 完成通知是外部通道:MCP 协议无法主动唤醒空闲 leader;WORKER_NOTIFY_WEBHOOK/NOTIFY_CMD 用于 webhook/桌面通知,未配置时不发通知。

  27. 发布/外部用户建议:设 WORKER_ALLOW_FULL_ACCESS_FALLBACK=0 保持 fail-closed;确认 WORKER_WORKTREE_ROOT 位于用户完全控制目录;ACL 失败时 worker_result.failure_kind=sandbox_acl + sandbox_blocked_detail 会给出 icacls / 换 worktree root / 显式传 permission_mode 三种修法。

  28. worktree 改动不会自动合入(v0.9.4):worker_result.merge_hint 给出 base_commit / patch_path / 可直接执行的 apply_command 与审阅提示;先 worker_read_result(source=diff) 审阅(patch 可能含 .dsh-* 探针文件与二进制占位),确认后再执行 apply。并发配额自 v0.9.4 起按 git 仓库根 计(同仓库子目录任务串行,非 git 目录按 cwd)。

排错

现象

处理

leader 里工具列表没有 dsh_*

检查命令路径、node 版本(需 ≥20);Claude Code 用 claude mcp get dsh 看状态与日志

DSH worker 错误 [invalid_cwd]

传具体项目目录;不要用 C:\Users\<user> 这类主目录

DSH worker 错误 [task_not_finished]

任务还没结束:先 worker_status 轮询到终态,再 worker_result

任务 failed 且 error 提到 approval

当前任务需要审批(如写工作区外):换 permission_mode=danger-full-access 或把操作限定在 cwd 内

Codex/ChatGPT 桌面端每次调用仍弹授权

确认 config.toml 中是 default_tools_approval_mode = "approve"(不是 auto)+ 13 个 per-tool approve,并完全退出重开 app;仍复现则是桌面端已知 bug(openai/codex#40793),可点「始终允许」、升级 app,或改用 Claude Code / codex exec(CLI 尊重配置)

read-only 任务中文输出乱码 / stderr 出现 InvalidOperation: 无法创建类型…

worker 启动时自动修复两层(前缀 + GBK 兜底解码);若调成 notify/off,手动跑 scripts/patch-dsh-pwsh-encoding.ps1 和 scripts/patch-dsh-output-decoding.ps1

任务报 SetNamedSecurityInfoW failed (Win32 5): grantWrite(...)

该目录 ACL 只有 Modify(常见于公司仓库):worker 默认自动升级 danger-full-access 重试,结果里 sandbox_fallback/effective_permission_mode 可见;不想用全权则设 WORKER_ACL_FALLBACK=read-only 或 off

续聊报 session "..." already exists

正常降级路径:worker 自动换新 session id + 带上本地「续聊上下文」重试(事件 session_resume_fallback),无需手动处理;若任务需要严格原会话历史,请在同一 worker 进程/后端存活期内续聊

找不到 DSH 入口

设 WORKER_DSH_CLI=D:\dsh-harness\node_modules\@deepseek-ai\dsh\lib\bin.js

想看真实参数/限制

调 worker_describe

开发

src/
  index.ts         stdio 入口(生产环境装配)
  server.ts        MCP 工具注册(14 个工具 + instructions)
  task-manager.ts  异步任务:排队/并发/session 串行/每仓库配额/TTL 清理/状态机/长轮询/恢复/审计
  dsh-runner.ts    headless 后端:spawn dsh、NDJSON 解析、超时、杀进程树、stderr 尾部
  sdk-backend.ts   sdk 后端:长驻进程、initialize、prompt、session.event 映射、取消=杀进程
  sdk-pool.ts      按 cwd + 权限模式缓存后端,空闲回收
  sdk-runner.ts    用长驻后端实现 TaskRunner
  fallback-runner.ts  sdk 启动失败时自动降级 headless(仅基础设施失败触发)
  sandbox-errors.ts  Windows ACL 沙箱失败识别(grantWrite Win32 5)与降级判定/提示
  jsonrpc-line.ts  换行 JSON-RPC 客户端(请求/通知/超时/关闭)
  http-server.ts   Streamable HTTP 传输(无状态、Bearer、/healthz)
  approval.ts      审批阻断检测(供 worker_result 的审批桥使用)
  audit.ts         append-only 审计日志(JSONL)
  artifacts.ts     任务产物的安全分页读取(worker_read_result)
  evidence.ts      从事件提取结构化证据:命令退出码/标记/编辑聚合(预算内)
  git-evidence.ts  git 基线/变更文件/diff.patch 采集(超时与失败不影响任务)
  report-protocol.ts 汇报协议页脚注入 + [DSH:NEEDS_DECISION] 检测  batch-manager.ts 批量任务(fan-out):创建、聚合状态/结果、取消
  search.ts        历史任务内容检索(输出 + 工具结果)
  otel.ts          轻量 OTLP/HTTP span 导出(无 SDK 依赖)
  usage.ts         DSH token 用量提取/累加(headless step_end 与 sdk assistant/message)
  pricing.ts       DeepSeek 单价与费用估算(USD/CNY,v0.10.0 合并自在用版 bridge)
  usage-report.ts  用量/成本聚合(worker_usage 工具,按天/按 cwd)
  idempotency.ts   幂等键落盘索引(worker_run idempotency_key 去重)
  dsh-patch.ts     DSH 兼容补丁:启动时检测/修复 pwsh 编码前缀(apply/notify/off)
  ndjson.ts        NDJSON 解析(跨 chunk/CRLF/脏行)
  output.ts        输出落盘与摘要
  keyed-lock.ts    session 级串行锁
  config.ts        环境变量、DSH 入口探测、cwd 校验
  store.ts         meta.json / events.jsonl 落盘
test/              216 个单测 + 真实 DSH 烟测(`test/mcp-smoke.ts`、`test/http-smoke.ts`)
examples/          多端接入示例(Claude / Codex / MCPB / 远程接入)
scripts/           部署与运维:deploy.ps1(源码→运行目录)/ patch-dsh-pwsh-encoding / patch-dsh-output-decoding / measure-goals / leader-usage / monitor-thread.py(Codex thread 配额/token 监控,兼容两版任务落盘)
docs/              measurement.md(目标口径/公式/A/B 协议/局限)、delegation-playbook.md(委派粒度与任务模板)
pnpm test          # 单元测试(假 DSH fixture,不耗模型 token)
pnpm smoke         # 真实 DSH 全链路(stdio,消耗少量 token)
pnpm smoke:http    # 真实 HTTP 传输冒烟(healthz / 401 / 真实任务)
pnpm measure:ab    # 目标达成率 A/B(leader 自己做 vs 委派 DSH;消耗 leader 额度)
pnpm measure:leader# 扫描 leader 会话用量(Claude transcripts + Codex rollouts)
pnpm build         # tsc 产物到 dist/

测试覆盖:NDJSON 解析/截断、输出落盘、session 锁、dsh 进程超时与取消、任务管理器(并发/每仓库配额/session 串行/长轮询/恢复/取消/TTL 清理/数量上限/审计)、JSON-RPC 客户端、SDK 长驻后端与池、HTTP 传输(鉴权/healthz)、审批桥、新增只读工具、DSH token 用量提取与累加、DSH 兼容补丁(编码前缀 + GBK 兜底解码;apply/notify/off/幂等/版本漂移)。v0.10.0 追加:费用估算(单价/汇率)、worker_usage 聚合、幂等键(落盘命中/TTL/forget/prune)、worker_result 分页、配置合并项(默认 1800s、WORKER_ALLOWED_ROOTS 兼容、单价覆盖)。

发布到 npm(维护者)

采用 npm Trusted Publishing(OIDC 绑定 GitHub Actions),CI 发布不需要 NPM_TOKEN。

  1. 首次发布必须手动(npm 上还不存在该包时无法配置 Trusted Publisher):

    npm login          # 浏览器/2FA
    pnpm build
    npm publish --access public
  2. 在 npm 包页面 → Settings → Trusted Publishing → GitHub Actions:

    • Organization/user:tongsh6

    • Repository:agent-worker-mcp

    • Workflow filename:publish.yml

    • 保存时按需输入 2FA。

  3. 之后发布只需打 tag:

    npm version patch --no-git-tag-version
    git add -A && git commit -m "chore(release): vX.Y.Z"
    git tag vX.Y.Z && git push --follow-tags

    Actions 会执行 pnpm test → pnpm build → npm publish --access public --provenance(OIDC,无 token)。

  4. 也可在 Actions → publish → Run workflow 手动触发。

注意:npm Trusted Publisher 要求使用较新的 npm CLI(workflow 里用 Node 24),且 workflow 文件名必须与配置一致。

License:MIT(见 LICENSE)。 14. 退出码来自文本标记:[exit code: N] / [killed by signal] / [timed out] / [sandbox: ...] 由 worker 从工具输出解析;DSH 若改格式,exit_code 会退化为 null 并保留 markers 原文,不会给错值。 15. git 证据的 pre_existing 是文件级:只能标记「任务开始前已脏」的文件,无法区分同一文件里任务前后各自的改动行。 16. 决策协议依赖 DSH 遵守标记:[DSH:NEEDS_DECISION] 由模型按页脚输出;不遵守时退化为 completed + 叙述,不做启发式猜测;可用 worker_metrics.outcomes 观察遵守率。 17. worker_status 默认 detail 变更(v0.9.0):默认不再回传 tool_call/tool_result/text 事件;需要旧行为时传 detail=events 或设 WORKER_STATUS_DETAIL=events。

路线图

  • M1 ✅ 已完成(2026-11-02):长驻 dsh --profile sdk 后端(默认),一次 initialize 后每任务只发 prompt;保留 headless fallback。

  • M2 🟡 部分完成(2026-11-02):HTTP 传输(无状态 Streamable HTTP + Bearer + /healthz)与审批桥 v0 已实现并测试;ChatGPT 直连需 Secure MCP Tunnel(无配额)或 OAuth 2.1(未实现),见 examples/remote-access.md。

  • M3 ✅ 已完成(2026-11-02):任务 TTL 清理 + 数量上限、每 cwd 并发配额(v0.9.4 起按 git 仓库根)、审计日志(worker_audit)、worker_tasks、worker_read_result。

  • M4 ✅ 已完成(2026-11-02):批量派发(fan-out)/ 历史任务检索 / 指标快照 / 轻量 OTel span 导出。

  • M5 ✅ 已完成(2026-11-02):目标达成率测量——worker 侧 DSH token 计量、A/B 对照工具、leader 用量扫描器、口径文档。

  • M6 ✅ 已完成(2026-11-11,v0.10.0):合并本机 Codex 在用版 bridge(server.mjs v2.2.0)的能力——worker_usage 用量/成本、幂等键、stdin 防孤儿、macOS cwd 适配、worker_result 分页续读、scripts/monitor-thread.py。

设计依据与市场调研见 本机分析报告(未随仓库提供)。

Available Tools

13 tools
dsh_audit查询审计日志A
Read-only

读取最近的审计事件(任务创建/开始/结束/取消、审批决定等),用于追溯与排障。

Inputs: limit.

dsh_batch_result获取批量任务结果A
Read-only

返回批量中每个任务的最终输出/错误/耗时;单条输出超过 max_output_chars 会截断(完整内容用 dsh_read_result)。

Inputs: batch_id (required), max_output_chars.

dsh_batch_run批量提交 DSH 任务A
Destructive

一次并行派发多个彼此独立、各自可验收的工作单元(每个任务仍应覆盖「实现+自测+证据」),立即返回 batch_id;用 dsh_batch_status / dsh_batch_result 聚合查询。不要用它串行拆解同一工作流。

Inputs: tasks (required).

dsh_batch_status查询批量任务状态A
Read-only

返回批量任务的整体状态、各子任务状态与计数;wait_s>0 时轮询到批量结束或超时。

Inputs: batch_id (required), wait_s.

dsh_cancel取消 DSH 任务A
Destructive

取消排队中或运行中的任务:运行中的任务会杀掉整个进程树。

Inputs: task_id (required).

dsh_describe描述 DSH worker 能力A
Read-only

返回 worker 版本、DSH 入口、默认参数与限制,便于 leader 自适应调用方式。

Inputs: no named parameters.

dsh_metrics查看运行指标A
Read-only

返回任务计数、耗时分位(avg/p50/p95/max)、DSH 侧 token 汇总、并发限制、排队情况、后端与 OTel 状态;用于 leader 自适应与「省 token/提速」核对。

Inputs: no named parameters.

dsh_read_result读取任务完整产物A
Read-only

当 dsh_result 因输出过长落盘(返回 artifacts)时,用本工具分页读取完整结果或事件日志;仅限任务目录内。

Inputs: task_id (required), offset, source, max_chars.

dsh_result获取 DSH 任务结果A
Read-only

任务结束后获取最终结果(含完整输出、退出码、耗时)。输出过大时会自动落盘并返回文件路径。任务未结束时返回错误。

Inputs: task_id (required).

dsh_run提交 DSH 任务A
Destructive

把一个可验收的完整工作单元(功能点/bug/测试修复批次/跨文件重构)交给本机 DSH 异步执行,立即返回 task_id。DSH 自己规划并执行多步工具调用(读代码、改文件、跑测试),一次任务应覆盖「实现 + 自测 + 证据」;不要提交单步/逐文件微任务。之后用 dsh_status 长轮询(wait_s 60–120)到终态,dsh_result 取结果;中断用 dsh_cancel。cwd 传当前项目绝对路径。

Inputs: task (required), cwd, wait_s, timeout_s, +2 more.

dsh_status查询 DSH 任务状态A
Read-only

查询任务状态与增量事件。status 为 succeeded/failed/cancelled 表示结束。用 wait_s 长轮询(建议 60–120s)一次等更久,减少 leader 往返;不要用 5–25s 高频轮询。

Inputs: task_id (required), cursor, wait_s.

dsh_tasks列出 DSH 任务B
Read-only

列出最近的任务摘要(task_id / 状态 / 任务预览 / cwd / 时间 / 错误),用于回顾历史与继续轮询。

Inputs: limit, status.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 13 tools

    Disambiguation4/5

    The lifecycle tools (run/status/result/cancel) and their batch counterparts (batch_run/batch_status/batch_result) are clearly separated by purpose. Minor overlap exists between dsh_result and dsh_read_result, and between dsh_tasks and dsh_search, but descriptions make the boundaries clear.

    Naming Consistency5/5

    All tools use a consistent dsh_ prefix with snake_case verb_noun patterns (dsh_run, dsh_status, dsh_batch_run, dsh_read_result). The batch family mirrors the single-task family predictably.

    Tool Count5/5

    13 tools is well within the ideal 3-15 range and each earns its place: core lifecycle, batch orchestration, result reading, search, audit, metrics, and introspection.

    Completeness5/5

    The surface covers the full async task lifecycle: submit, poll, fetch result, cancel, batch dispatch/status/result, large-output pagination, search, audit trail, metrics, and worker introspection. No obvious dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables launching and supervising local Codex and Claude Code agent sessions and one-shot tasks, exposing run, list, stop, and output operations over MCP with session-scoped permissions and sandbox controls.
      2
      264 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Connects ChatGPT and MCP clients to authorized local development environments, enabling secure file access, shell execution, persistent tasks, browser/desktop control, and remote management of projects.
      19
      MIT
    • A
      license
      D
      quality
      C
      maintenance
      Enables controlled local developer operations including file and process management, shell execution, SSH, WSL, Docker, Git, browser and desktop automation, media processing, and asynchronous jobs through MCP.
      146
      MIT