agent-worker-mcp 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +575 -2
  3. package/dist/approval.js +39 -0
  4. package/dist/approval.js.map +1 -0
  5. package/dist/artifacts.js +44 -0
  6. package/dist/artifacts.js.map +1 -0
  7. package/dist/audit.js +40 -0
  8. package/dist/audit.js.map +1 -0
  9. package/dist/batch-manager.js +200 -0
  10. package/dist/batch-manager.js.map +1 -0
  11. package/dist/capability-store.js +72 -0
  12. package/dist/capability-store.js.map +1 -0
  13. package/dist/config.js +242 -0
  14. package/dist/config.js.map +1 -0
  15. package/dist/dsh-patch.js +210 -0
  16. package/dist/dsh-patch.js.map +1 -0
  17. package/dist/dsh-runner.js +137 -0
  18. package/dist/dsh-runner.js.map +1 -0
  19. package/dist/errors.js +9 -0
  20. package/dist/errors.js.map +1 -0
  21. package/dist/event-summary.js +95 -0
  22. package/dist/event-summary.js.map +1 -0
  23. package/dist/evidence.js +195 -0
  24. package/dist/evidence.js.map +1 -0
  25. package/dist/fallback-runner.js +83 -0
  26. package/dist/fallback-runner.js.map +1 -0
  27. package/dist/git-evidence.js +187 -0
  28. package/dist/git-evidence.js.map +1 -0
  29. package/dist/http-server.js +159 -0
  30. package/dist/http-server.js.map +1 -0
  31. package/dist/idempotency.js +102 -0
  32. package/dist/idempotency.js.map +1 -0
  33. package/dist/index.js +188 -0
  34. package/dist/index.js.map +1 -0
  35. package/dist/jsonrpc-line.js +151 -0
  36. package/dist/jsonrpc-line.js.map +1 -0
  37. package/dist/keyed-lock.js +43 -0
  38. package/dist/keyed-lock.js.map +1 -0
  39. package/dist/kimi-acp-backend.js +572 -0
  40. package/dist/kimi-acp-backend.js.map +1 -0
  41. package/dist/kimi-pool.js +108 -0
  42. package/dist/kimi-pool.js.map +1 -0
  43. package/dist/kimi-runner.js +117 -0
  44. package/dist/kimi-runner.js.map +1 -0
  45. package/dist/ndjson.js +64 -0
  46. package/dist/ndjson.js.map +1 -0
  47. package/dist/notifier.js +46 -0
  48. package/dist/notifier.js.map +1 -0
  49. package/dist/otel.js +88 -0
  50. package/dist/otel.js.map +1 -0
  51. package/dist/output.js +29 -0
  52. package/dist/output.js.map +1 -0
  53. package/dist/pricing.js +36 -0
  54. package/dist/pricing.js.map +1 -0
  55. package/dist/repo-root.js +53 -0
  56. package/dist/repo-root.js.map +1 -0
  57. package/dist/report-protocol.js +43 -0
  58. package/dist/report-protocol.js.map +1 -0
  59. package/dist/router-runner.js +12 -0
  60. package/dist/router-runner.js.map +1 -0
  61. package/dist/sandbox-errors.js +26 -0
  62. package/dist/sandbox-errors.js.map +1 -0
  63. package/dist/sdk-backend.js +300 -0
  64. package/dist/sdk-backend.js.map +1 -0
  65. package/dist/sdk-pool.js +110 -0
  66. package/dist/sdk-pool.js.map +1 -0
  67. package/dist/sdk-runner.js +128 -0
  68. package/dist/sdk-runner.js.map +1 -0
  69. package/dist/search.js +59 -0
  70. package/dist/search.js.map +1 -0
  71. package/dist/server.js +936 -0
  72. package/dist/server.js.map +1 -0
  73. package/dist/store.js +97 -0
  74. package/dist/store.js.map +1 -0
  75. package/dist/task-manager.js +1213 -0
  76. package/dist/task-manager.js.map +1 -0
  77. package/dist/types.js +4 -0
  78. package/dist/types.js.map +1 -0
  79. package/dist/usage-report.js +87 -0
  80. package/dist/usage-report.js.map +1 -0
  81. package/dist/usage.js +60 -0
  82. package/dist/usage.js.map +1 -0
  83. package/dist/worktree-cleanup.js +158 -0
  84. package/dist/worktree-cleanup.js.map +1 -0
  85. package/dist/worktree.js +43 -0
  86. package/dist/worktree.js.map +1 -0
  87. package/package.json +59 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 tongsh6
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,576 @@
1
- # Temporary Holding Version
1
+ # agent-worker-mcp
2
+
3
+ 把本机**多个 coding agent(DSH、Kimi Code CLI)**统一暴露成一个 **MCP worker**,让 **Claude Code / Codex CLI / ChatGPT(桌面)/ Claude Desktop** 这些 leader 把重活派给它,并**按任务选择执行体**。
4
+
5
+ > 角色模型:leader(决策、编排)通过 MCP 调用 worker;worker 按任务选择执行体(`backend=dsh|kimi`,默认 dsh),在真实项目目录里执行长任务(读代码、改文件、跑命令、跑测试),只回传结果与**可验收的证据**。
6
+
7
+ ## 现状(本地已验证)
8
+
9
+ | 项 | 状态 |
10
+ |---|---|
11
+ | 单元测试 | ✅ 216/217 通过(`pnpm test`;1 项 Windows-only 用例在 macOS/Linux 跳过) |
12
+ | 真实链路烟测 | ✅ MCP Client → worker → 真实 DSH:问答 + 写文件(`hello-dsh.txt`)全链路通过 |
13
+ | 长驻后端(M1) | ✅ 默认 `backend=sdk`:真实烟测首任务 9s(含一次初始化)、第二任务 **3s**;大仓库真实任务 18.4s(含 initialize);`headless` 保留为 fallback |
14
+ | 远程传输(M2a) | ✅ `WORKER_TRANSPORT=http`:真实 HTTP 冒烟通过(`/healthz` 200、无 token 401、MCP HTTP 客户端跑真实任务 8s) |
15
+ | 审批桥(M2b) | ✅ `worker_result` 检测审批阻断 → elicitation 询问授权 → 以 `danger-full-access` 重试(4 个单测覆盖;真实 DSH 审批场景未端到端实测) |
16
+ | 运维治理(M3) | ✅ 任务 TTL 自动清理 + 数量上限(超额淘汰最老已结束任务)、每仓库并发配额、审计日志(`worker_audit`)、任务列表(`worker_tasks`)、完整产物分页读取(`worker_read_result`) |
17
+ | 批量/检索/观测(M4) | ✅ `worker_batch_run/status/result` 批量派发与聚合、`worker_search` 历史任务内容检索、`worker_metrics` 指标快照、轻量 OTel span 导出(真实冒烟捕获到 2 条 `dsh.task` span) |
18
+ | 编码与写文件 | ✅ workspace-write 中文 UTF-8 写入/读回(字节 `E4 B8 AD…`);read-only 中文输出经 worker **自动双层兼容修复**后回归正常(实测 read-only / workspace-write 均返回 `中文探针:你好`、无 `�`) |
19
+ | 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 盘受限目录会失效) |
20
+ | 委派粒度策略(v0.6.4) | ✅ 规则改为「一个 worker_run = 一个可验收工作单元(实现+自测+证据),禁止微任务」;长轮询上限 25s→可配 120s(`WORKER_STATUS_WAIT_MAX_S`),减少 leader 往返;规则已写入 `~/AGENTS.md`、`~/.codex/AGENTS.md`、worker instructions 与 [docs/delegation-playbook.md](docs/delegation-playbook.md) |
21
+ | 执行记录分析(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`) |
22
+ | 续聊恢复(v0.6.3) | ✅ DSH SDK 协议无 resume;worker 重建后用旧 `session_id` 续聊会报 `session "..." already exists`。worker 自动换新 session id 重试,并把上一轮任务/结果摘要作为「续聊上下文」拼入;真实两进程验证:A 建 session → B 续聊 succeeded(output=ok2),事件含 `session_resume_fallback` |
23
+ | 易用性升级(v0.7.0) | ✅ `auto` 模式 + cwd 能力缓存(跨进程,避免每次撞 ACL)+ 自动 worktree(受限仓库改到可写 worktree)+ 能力缓存 TTL 可调 + 瞬态失败自动重试 + 失败诊断 + `worker_run(wait_s)` 单调用等待 + MCP 调用/字节指标 + 任务完成 webhook/命令通知 |
24
+ | 性能与协议(v0.8.0) | ✅ `worker_status` 有界事件摘要(单条 ≤2KiB、单次 ≤16KiB,可配)、`session_id` 实时回填与别名锁、事件追加串行化(避免并发写坏 JSONL)、auto 模式优先 worktree |
25
+ | 结构化证据(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|evidence)`;`worker_metrics.outcomes/rework/evidence` |
26
+ | 证据补全(v0.9.1) | ✅ `evidence.edits` 支持真实 DSH 的 `write`/`edit`/`apply_patch` 与 `file_path`;untracked 文件渲染进 `diff.patch`(`new file` + `+ untracked: N files`) |
27
+ | 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` 清理 |
28
+ | 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 可直接重提 |
29
+ | 仓库级并发与合入指引(v0.9.4) | ✅ 并发配额改为按 **git 仓库根** 计(同仓库不同子目录、worktree 任务也串行;非 git 目录回退按 cwd);`worker_result.worktree.base_commit` + `merge_hint`(`base_commit` / `patch_path` / 可直接执行的 `apply_command` / 审阅提示),worktree 改动可结构化合入原仓库(不自动 apply) |
30
+ | 目标测量(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 |
31
+ | 用量与成本(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` 分页续读 |
32
+ | 幂等与防孤儿(v0.10.0,合并自本机在用版 bridge) | ✅ `worker_run(idempotency_key)` 重复提交返回同一 task(落盘索引 + 进程内并发去重,默认 24h);stdio 模式下父进程退出(stdin end/close)会终止运行中 worker,避免孤儿进程 |
33
+ | 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 暴露)真实任务跑通 |
34
+ | cwd 安全校验 | ✅ Windows 拒绝用户主目录(ACL 沙箱限制);macOS/Linux 允许(v0.10.0 起,与在用版 bridge 对齐) |
35
+ | Claude Code 接入 | ✅ 已注册(user scope)并实测连通:`claude mcp get dsh` → `√ Connected`;`claude -p` 真实调用 `worker_describe` 成功 |
36
+ | 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 次工具调用无弹窗) |
37
+ | 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) |
38
+ | ChatGPT web | ⏸ 后置(需要 OpenAI Secure MCP Tunnel 或自建 HTTPS + OAuth) |
39
+ | Claude Desktop(MCPB) | ⚠️ 未实测(`examples/mcpb-manifest.json` 已给出模板) |
40
+
41
+ > 注册记录(2026-11-02):Claude 侧改的是 `~/.claude.json`;Codex 侧在 `~/.codex/config.toml` 末尾追加了 `[mcp_servers.dsh]`,改前已备份为 `config.toml.bak-dsh-registration-20261102`。
42
+ > 撤销:`claude mcp remove dsh -s user`;`codex mcp remove dsh`(或从 config.toml 删掉对应块)。
43
+
44
+ ## 架构
45
+
46
+ ```
47
+ leader(Claude Code / Codex / ChatGPT / Claude Desktop)
48
+ │ MCP over stdio(本地)或 Streamable HTTP /mcp + Bearer(远程)
49
+ ▼
50
+ agent-worker-mcp(本进程)
51
+ │ worker_run 立即返回 task_id;任务后台执行
52
+ │ 任务落盘:meta.json / events.jsonl / result.txt
53
+ ▼ 后端可切换(WORKER_BACKEND)
54
+ ├─ sdk(默认):长驻 `dsh --profile sdk`,一次 initialize,之后每个任务只发 session/prompt
55
+ └─ headless:`dsh --profile headless --json "<task>"`,每任务一个进程
56
+ │ NDJSON 事件:session → status/tool_call/tool_result → final
57
+ ▼
58
+ 真实文件系统 / shell(cwd 必须是项目目录;默认 workspace-write)
59
+ ```
60
+
61
+ ## 快速开始
62
+
63
+ ```powershell
64
+ cd C:\path\to\agent-worker-mcp
65
+ pnpm install
66
+ pnpm build
67
+ pnpm test # 216 个单测(1 项 Windows-only 跳过)
68
+ pnpm smoke # 真实 DSH 集成烟测(约 30–60s)
69
+ ```
70
+
71
+ > macOS/Linux 同样适用:把 `cd C:\path\to\agent-worker-mcp` 换成仓库路径即可。macOS 上 DSH 用桌面 app 自带的 CLI(`sdk` 后端,见下文「macOS / Linux + Codex 部署」),**不要重复安装 pnpm 全局 dsh**。
72
+
73
+ worker 通过 **stdio** 工作,自身不监听任何端口。需要它时由 leader 拉起子进程。
74
+
75
+ ## 本机安装(推荐 pnpm 全局)
76
+
77
+ 源码仓库只用于开发(`pnpm build` / `pnpm test`);**MCP 客户端加载 pnpm 全局安装的正式包**,不要指向源码仓库。
78
+
79
+ ```powershell
80
+ pnpm add -g agent-worker-mcp@latest # 安装/升级
81
+ pwsh -File scripts/mcp-entry.ps1 # 输出 MCP 入口(pnpm 全局包内 dist/index.js)
82
+ ```
83
+
84
+ 把输出的入口配置给 leader(Codex/ChatGPT 的 `~/.codex/config.toml` 或 Claude Code):
85
+
86
+ ```toml
87
+ [mcp_servers.dsh]
88
+ command = "node"
89
+ args = ["<scripts/mcp-entry.ps1 输出的路径>"]
90
+ ```
91
+
92
+ - 升级:`pnpm update -g agent-worker-mcp` → 重启 leader 会话;若入口路径变化,用 `scripts/mcp-entry.ps1` 刷新配置;
93
+ - **不要用 `cmd /c agent-worker-mcp` 作为 MCP 入口**:cmd 包装下 `worker_describe` 正常但真实任务会卡住(已实测),必须用 `node` + 全局包入口;
94
+ - 源码开发调试可选:`scripts/deploy.ps1` 部署到独立目录(内容等价 npm 包),不用于本机日常使用。
95
+ ## macOS / Linux + Codex 部署(从本机在用版 bridge 迁移)
96
+
97
+ 本仓库同时兼容 Windows 与 macOS/Linux。若你之前在生产用的是**零依赖单文件版 bridge**(`~/scripts/dsh-mcp/server.mjs`,v2.2.0,工具面 4 个:`dsh_dispatch` / `dsh_job` / `worker_usage` / `worker_status`),v0.10.0 已把它的核心能力合并进来:
98
+
99
+ | 能力 | 在用版 server.mjs | 本仓库 v0.10.0 |
100
+ |---|---|---|
101
+ | 派活/等待/取消 | `dsh_dispatch` / `dsh_job` | `worker_run` / `worker_status` / `worker_result` / `worker_cancel`(另有批量、结构化证据、worktree、审批桥) |
102
+ | 用量与成本 | `worker_usage`(解析 dsh 会话日志) | `worker_usage`(按天/cwd,基于任务记录)+ `worker_result.usage.cost_*` + `worker_metrics.cost` |
103
+ | 幂等键 | `idempotency_key` | ✅ 同语义(落盘索引,默认 24h) |
104
+ | 防孤儿进程 | stdin 关闭 → kill worker | ✅ stdio 模式已对齐 |
105
+ | cwd 白名单 | `WORKER_ALLOWED_ROOTS` | 兼容该变量;主变量仍是 `WORKER_ALLOWED_CWDS` |
106
+ | 默认超时 | 1800s | 1800s(v0.10.0 起;旧默认 900s 偏小) |
107
+ | 输出续读 | 字节 `offset` / `max_bytes` | `worker_result(offset, max_chars)` 字符分页 + `worker_read_result` |
108
+
109
+ **DSH 版本与凭据(macOS 实测,2026-11-11)**:
110
+
111
+ - **唯一安装:桌面 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**。
112
+ - **app 路径含空格**(`DeepSeek Harness.app`),而 `WORKER_DSH_COMMAND` 走 `shell:true` 会被拆开,所以必须用无空格 wrapper 暴露入口(见迁移步骤 2.5)。
113
+ - **不要为 worker 单独 `pnpm add -g @deepseek-ai/dsh`**:会与 app 内置 CLI 重复安装。本机曾同时存在 pnpm 全局 `0.1.5-rc.2` 与 app 内置 `0.2.2-rc.1`,已移除前者;两者版本不一致还会导致事件格式/凭据行为差异。
114
+ - app 内置 CLI 的 `headless`(`--json`)在独立 CLI 进程下可能读不到 GUI credentials service(`MISSING_CREDENTIAL`),所以 macOS 上优先 `sdk` 后端。
115
+ - 结论:macOS 上 `WORKER_BACKEND=sdk` + `WORKER_DSH_COMMAND` 指向 wrapper(内部 exec app 内置 CLI)。
116
+
117
+ 迁移步骤(保留在用版作为回滚):
118
+
119
+ 1. 备份 Codex 配置:`cp ~/.codex/config.toml ~/.codex/config.toml.bak-before-agent-worker-mcp`
120
+ 2. 构建本仓库:
121
+ ```bash
122
+ cd ~/workspace/code/github/agent-worker-mcp
123
+ pnpm install && pnpm build
124
+ ```
125
+ 2.5. 创建 app 内置 CLI 的无空格入口 wrapper(macOS;路径按本机替换):
126
+ ```bash
127
+ printf '#!/bin/sh\nexec "/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" "$@"\n' > ~/scripts/dsh-app-cli.sh
128
+ chmod +x ~/scripts/dsh-app-cli.sh
129
+ ~/scripts/dsh-app-cli.sh --version # 应输出版本号(如 0.2.2-rc.1)
130
+ ```
131
+ 3. 安装 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 后端与白名单(路径按本机替换):
132
+ ```toml
133
+ [mcp_servers.dsh-worker]
134
+ command = "/Users/<you>/Library/pnpm/bin/agent-worker-mcp"
135
+ args = []
136
+ cwd = "/Users/<you>"
137
+ enabled = true
138
+ startup_timeout_sec = 60
139
+ tool_timeout_sec = 1800
140
+ default_tools_approval_mode = "approve"
141
+
142
+ [mcp_servers.dsh-worker.env]
143
+ HOME = "/Users/<you>"
144
+ DSH_HOME = "/Users/<you>/.dsh"
145
+ WORKER_BACKEND = "sdk"
146
+ WORKER_DSH_COMMAND = "/Users/<you>/scripts/dsh-app-cli.sh"
147
+ WORKER_DSH_PATCH = "off"
148
+ WORKER_ALLOWED_ROOTS = "/Users/<you>"
149
+ WORKER_MAX_CONCURRENT = "4"
150
+ WORKER_TIMEOUT_S = "1800"
151
+ PATH = "/Users/<you>/.nvm/versions/node/v24.19.0/bin:/Users/<you>/Library/pnpm/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
152
+ ```
153
+ 4. 重启 Codex / ChatGPT 桌面 app(MCP 工具目录在握手时协商),先在会话里调用 `worker_describe` / `worker_usage` 验证,再跑一个真实任务。
154
+ 也可不挂载直接自检:
155
+ ```bash
156
+ printf '%s\n' \
157
+ '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \
158
+ '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
159
+ | WORKER_BACKEND=headless node dist/index.js 2>/dev/null | tail -1 | head -c 400
160
+ ```
161
+ 5. 回滚:还原第 1 步的配置备份并重启 leader 即可。
162
+
163
+ > 两版可并存对比(用不同的 MCP server 名);它们的任务目录互不冲突(在用版 `~/.dsh-mcp/jobs` vs 本仓库 `$DSH_HOME/mcp-tasks`)。
164
+
165
+ ## 通过 npm 使用
166
+
167
+ 包名:`agent-worker-mcp`(只发布构建产物;本机仍需安装 DSH)。
168
+
169
+ ```powershell
170
+ npm i -g agent-worker-mcp # 或直接用 npx
171
+ npx -y agent-worker-mcp # 由 MCP 客户端拉起(stdio)
172
+ ```
173
+
174
+ MCP 客户端配置可用:
175
+
176
+ ```json
177
+ {
178
+ "mcpServers": {
179
+ "dsh": { "command": "npx", "args": ["-y", "agent-worker-mcp"] }
180
+ }
181
+ }
182
+ ```
183
+
184
+ 注意:npm 包**不包含 DSH 本体**;worker 通过 `dsh`(PATH)、`WORKER_DSH_DIR` 或 `WORKER_DSH_CLI` 找到本机 DSH。
185
+
186
+ ## 接入 leader
187
+
188
+ ### 1) Claude Code(最省事)
189
+
190
+ ```powershell
191
+ claude mcp add --scope user --transport stdio dsh -- node "C:\path\to\agent-worker-mcp\dist\index.js"
192
+ claude mcp list
193
+ claude mcp get dsh
194
+ ```
195
+
196
+ 带环境变量时注意 `--env` 的位置(放在 server 名之前):
197
+
198
+ ```powershell
199
+ 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"
200
+ ```
201
+
202
+ 等价 `.mcp.json` 见 [examples/claude-mcp.json](examples/claude-mcp.json)。
203
+
204
+ **避免每次弹授权**:把 dsh 工具加入用户级 allowlist(`~/.claude/settings.json` 的 `permissions.allow`):
205
+
206
+ ```json
207
+ ["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",
208
+ "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",
209
+ "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",
210
+ "mcp__agent-worker-mcp__worker_usage"]
211
+ ```
212
+
213
+ > 本机已写入(备份 `settings.json.bak-dsh-allow-20261102`)。安全边界仍由 worker 的 `permission_mode` / 审批桥承担。
214
+
215
+ ### 2) Codex CLI / IDE
216
+
217
+ 把下面加到 `~/.codex/config.toml`(完整示例见 [examples/codex-config.toml](examples/codex-config.toml)):
218
+
219
+ ```toml
220
+ [mcp_servers.dsh]
221
+ command = "node"
222
+ args = ["C:\\path\\to\\agent-worker-mcp\\dist\\index.js"]
223
+ startup_timeout_sec = 30 # 默认 10;worker 自身启动很快,留余量
224
+ tool_timeout_sec = 300 # 默认 60;allow worker_status 长轮询(wait_s≤120s)
225
+ 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"]
226
+ # approve = 不再询问(auto 仍会按风险询问);安全边界由 worker 的 permission_mode(默认 workspace-write)兜底
227
+ default_tools_approval_mode = "approve"
228
+
229
+ # 桌面端对 MCP 工具的审批可被 per-tool 覆盖(14 个工具都要写)
230
+ [mcp_servers.dsh.tools.worker_run]
231
+ approval_mode = "approve"
232
+ # ……其余工具同理:worker_status / worker_result / worker_cancel / worker_describe / worker_tasks / worker_audit /
233
+ # worker_read_result / worker_batch_run / worker_batch_status / worker_batch_result / worker_search / worker_metrics / worker_usage
234
+
235
+ [mcp_servers.dsh.env]
236
+ WORKER_DEFAULT_CWD = "C:\\path\\to\\your\\project"
237
+ ```
238
+
239
+ 校验:`codex mcp get dsh`(本机已配置为 `default_tools_approval_mode: approve` + per-tool `approve`;改前备份 `config.toml.bak-dsh-approve-20261102`)。改完需**完全退出并重开** Codex/ChatGPT 桌面 app,配置在 app 启动时加载。
240
+
241
+ ### 3) ChatGPT 桌面 app
242
+
243
+ 调研显示 ChatGPT 桌面 app、Codex CLI、IDE 扩展**共享同一份** `~/.codex/config.toml`,所以按上面 Codex 的配置配好后重启桌面 app 即可使用(**未实测**,若无效请反馈)。
244
+
245
+ ### 4) ChatGPT web(后置)
246
+
247
+ ChatGPT web 只接受**远程 MCP**(Streamable HTTP / SSE),不接受 stdio。两条路:
248
+
249
+ - **推荐**:OpenAI Secure MCP Tunnel(需要 Platform 组织 + `tunnel_id` + runtime API key):
250
+ ```bash
251
+ tunnel-client init --sample sample_mcp_stdio_local --profile dsh-local \
252
+ --tunnel-id tunnel_xxxxxxxx --mcp-command "node C:\\path\\to\\agent-worker-mcp\\dist\\index.js"
253
+ tunnel-client run --profile dsh-local
254
+ ```
255
+ 然后在 ChatGPT → Plugins → `+` → Add custom MCP server → Connection 选 Tunnel → Create。
256
+ 注意 Tunnel 硬限制:**单请求 120s / 10 MiB / 600 rpm**,所以必须用本 worker 的异步任务模型(`run` 立即返回 + 轮询)。
257
+ - 或自建 HTTPS + OAuth 2.1(工作量大,暂未实现)。
258
+
259
+ ### 5) Claude Desktop(本地 MCPB)
260
+
261
+ 模板见 [examples/mcpb-manifest.json](examples/mcpb-manifest.json)。需要把 `dist/` 与 `node_modules` 一起打包进 MCPB 扩展,用 `mcpb pack` 生成 `.mcpb` 后拖入 Claude Desktop(**未实测**)。
262
+
263
+ ## 工具面
264
+
265
+ | 工具 | 作用 | 关键参数 |
266
+ |---|---|---|
267
+ | `worker_run` | 提交任务,**立即**返回 `task_id` | `task`(必填)、`cwd`(必填,项目目录)、`session_id?`、`permission_mode?`、`timeout_s?`、`idempotency_key?` |
268
+ | `worker_status` | 查状态 + 有界事件摘要;默认 `detail=summary` 只回状态/异常事件 + `last_text`,`detail=events` 回全部事件;终态带 `outcome` | `task_id`、`cursor?`、`wait_s?`、`detail?`(summary/events) |
269
+ | `worker_result` | 取最终结果;验收优先看 `evidence`(命令退出码/变更文件/diff 摘要)与 `outcome`,`output` 是 DSH 叙述;传 `offset/max_chars` 可直接分页续读 | `task_id`、`offset?`、`max_chars?` |
270
+ | `worker_cancel` | 取消任务(杀进程树) | `task_id` |
271
+ | `worker_tasks` | 列出最近任务摘要(回顾/继续轮询) | `limit?`(1–100)、`status?` |
272
+ | `worker_audit` | 读取审计事件(任务生命周期/审批决定) | `limit?`(1–200) |
273
+ | `worker_read_result` | 分页读取落盘产物 | `task_id`、`source?`(result/events/diff/evidence)、`offset?`、`max_chars?` |
274
+ | `worker_batch_run` | 批量并行派发(每项可带 cwd/session/权限) | `tasks[]`(1–`maxBatchTasks`) |
275
+ | `worker_batch_status` | 批量聚合状态(整体状态 + 子任务 + 计数) | `batch_id`、`wait_s?` |
276
+ | `worker_batch_result` | 批量聚合结果(输出/错误/耗时) | `batch_id`、`max_output_chars?` |
277
+ | `worker_search` | 在历史任务的输出与工具结果里检索 | `query`、`limit?` |
278
+ | `worker_metrics` | 计数/耗时分位/排队/后端/OTel 状态 + token 与估算费用汇总 | — |
279
+ | `worker_usage` | 按时间窗口聚合用量与费用(任务数/状态/耗时/DSH token/估算费用,按 cwd 分布) | `days?`(1–90)、`cwd?` |
280
+ | `worker_describe` | 返回入口/默认值/限制,供 leader 自适应 | — |
281
+
282
+ 典型调用序列(leader 视角):
283
+
284
+ ```jsonc
285
+ // 1) 提交
286
+ { "name": "worker_run", "arguments": { "task": "修复 utils.ts 的空指针,并跑 pnpm test 验证", "cwd": "D:\\work\\repo" } }
287
+ // → { task_id, status: "queued", session_id, cwd, hint }
288
+
289
+ // 2) 轮询(每次最多等 25s;运行中会收到 notifications/progress)
290
+ { "name": "worker_status", "arguments": { "task_id": "...", "cursor": 0, "wait_s": 20 } }
291
+
292
+ // 3) 结束后取结果
293
+ { "name": "worker_result", "arguments": { "task_id": "..." } }
294
+ ```
295
+
296
+ 状态机:
297
+
298
+ ```
299
+ queued ──▶ running ──▶ succeeded
300
+ │ ├──▶ failed(超时/DSH 报错)
301
+ │ ├──▶ cancelled
302
+ └──▶ 不会出现:被取消的排队任务会直接 cancelled
303
+ ```
304
+
305
+ 多轮续聊:把首次 `worker_run` 返回的 `session_id` 传给下一次 `worker_run`;**同一 session 的任务串行执行**(DSH 侧单写者),不同 session 并行(受 `WORKER_MAX_CONCURRENT` 限制)。
306
+
307
+ ## 让 leader 主动委派(可选,推荐)
308
+
309
+ MCP 只把工具摆给 leader,**是否调用由 leader 模型自己决定**,协议层无法强制。想提高“自动委派”概率,三档手段(从弱到强):
310
+
311
+ 1. **工具描述/instructions**(已内置):`worker_run` 描述与 server `instructions` 写明「一个任务 = 一个可验收工作单元(实现+自测+证据);禁止微任务;长轮询 60–120s」——**这是 ChatGPT web / Claude Desktop 等远程 leader 唯一可用的杠杆**。
312
+ 2. **指令文件**(本地 leader 有效):
313
+ - Claude Code:`~/.claude/CLAUDE.md`(本机通过 `@~/AGENTS.md` 引用);
314
+ - Codex:`~/.codex/AGENTS.md`(全局);或项目内 `AGENTS.md`(就近生效)。
315
+ 本机已写入「粗粒度委派」规则(`AGENTS.md.bak-dsh-coarse-20261102` 为改前备份)。
316
+ 3. **Hook**(仅 Claude Code 等支持 hook 的 host):UserPromptSubmit 每次注入提醒,最稳但配置成本最高。
317
+
318
+ > 注意:远程 leader(ChatGPT web / Claude Desktop)读不到本地指令文件,只能靠第 1 条 + 用户明说「用 dsh 跑」。
319
+
320
+ ### 粒度怎么定(关键)
321
+
322
+ - 一个 `worker_run` 覆盖「定位 → 实现 → 自测 → 证据」,典型:一个功能点 / 一个 bug / 一个测试修复批次 / 一次跨文件重构;
323
+ - 少于 3 次工具调用或 2 分钟内能做完的事,leader 自己做;不要拆成多个 dsh 任务;
324
+ - 只有独立可并行(用 `worker_batch_run`)、需要决策、风险隔离时才拆分;
325
+ - 轮询用 `worker_status(wait_s=60~120)`,不要在 DSH 执行期间重复劳动;
326
+ - 详细模板、反例/正例、验收动作、如何用 `scripts/leader-usage.mjs` 验证:[docs/delegation-playbook.md](docs/delegation-playbook.md)。
327
+
328
+ ## 目标达成率测量(leader 提速 / 省 token)
329
+
330
+ 目标前提:Codex/ChatGPT、Claude Code 作为 leader,通过本 worker 把重活交给 DSH。核对方式:**同任务 A/B 对照**(leader 自己做 vs 委派 DSH)。
331
+
332
+ ```powershell
333
+ # A/B 对照(会真实消耗 leader 额度;只读分析类任务最安全)
334
+ pnpm measure:ab -- --cwd D:\work\repo --task "统计 src 下 ts 文件数量并列出最大的 3 个(只读分析)" --runs 3 --expect "src"
335
+
336
+ # 持续观察 leader 自己的会话用量(不跑基准)
337
+ pnpm measure:leader -- --since-hours 24
338
+ ```
339
+
340
+ 报告包含:加速比、leader token 节省率、cost 节省率、正确性守门、DSH token、`DSH token / 省下 leader token`,以及**目标达成率 x/2 或 x/3**。
341
+
342
+ - 口径/公式/协议/局限:[docs/measurement.md](docs/measurement.md)
343
+ - 真实首测(单样本,任务:统计 src 下 ts 文件并列出最大 3 个):**加速 2.29x、leader token 省 46.0%、cost 省 31.1%、达成率 2/2**;报告样例在 `measure-runs/report-*.md`。
344
+ - leader token 来自 Claude Code `-p --output-format json` 的 `usage/cost`;Codex 用 `scripts/leader-usage.mjs` 从 rollout 聚合;ChatGPT web 无本地计量(见文档局限)。
345
+
346
+ ## 配置(环境变量)
347
+
348
+ | 变量 | 默认 | 说明 |
349
+ |---|---|---|
350
+ | `WORKER_TRANSPORT` | `stdio` | MCP 传输:`stdio`(本地 leader)/ `http`(Streamable HTTP,远程 leader) |
351
+ | `WORKER_HTTP_HOST` | `127.0.0.1` | HTTP 监听地址;`0.0.0.0` 时必须设 token |
352
+ | `WORKER_HTTP_PORT` | `7391` | HTTP 端口(`0` = 随机) |
353
+ | `WORKER_HTTP_TOKEN` | 无 | HTTP Bearer token;非回环地址必填 |
354
+ | `WORKER_DSH_CLI` | 自动探测 | `@deepseek-ai/dsh/lib/bin.js` 的绝对路径(用 `node` 启动,最稳) |
355
+ | `WORKER_DSH_COMMAND` | — | 完整命令(如 `dsh`),通过 shell 启动;优先级低于 `WORKER_DSH_CLI` |
356
+ | `WORKER_DSH_DIR` | — | DSH 安装目录(自动拼 `node_modules/@deepseek-ai/dsh/lib/bin.js`) |
357
+ | `WORKER_PROFILE` | `headless` | `headless` 后端使用的 profile |
358
+ | `WORKER_BACKEND` | `sdk` | 执行后端:`sdk`(长驻,默认)/ `headless`(每任务一进程) |
359
+ | `WORKER_SDK_PROFILE` | `sdk` | 长驻后端使用的 DSH profile |
360
+ | `WORKER_SDK_PROVIDER` | `deepseek-official` | SDK 后端 provider |
361
+ | `WORKER_SDK_MODEL` | `deepseek-flash` | SDK 后端 model(进程级固定) |
362
+ | `WORKER_SDK_REASONING_EFFORT` | 无 | 推理强度(可选,如 `max`) |
363
+ | `WORKER_SDK_MAX_TOKENS` | 无 | 单次输出 token 上限(可选) |
364
+ | `WORKER_SDK_IDLE_MIN` | `10` | 后端空闲多少分钟回收(1–240) |
365
+ | `WORKER_SDK_INIT_TIMEOUT_S` | `300` | 后端 initialize 超时(秒);失败自动重试 1 次,仍失败则自动降级 headless |
366
+ | `WORKER_DEFAULT_CWD` | 无 | 省略 `cwd` 时使用;没设则用 worker 进程 cwd(stdio 启动时通常是 leader 的项目目录) |
367
+ | `WORKER_ALLOWED_CWDS` | 无 | 分号分隔的允许目录白名单(设置后只能在这些目录下跑) |
368
+ | `WORKER_ALLOWED_ROOTS` | 无 | **兼容旧版 bridge** 的允许目录写法(平台分隔符:POSIX `:`、Windows `;`);`WORKER_ALLOWED_CWDS` 优先 |
369
+ | `WORKER_PERMISSION_MODE` | `auto` | 默认 `auto`(worker 按 cwd 能力自动适配);也可显式 `read-only` / `workspace-write` / `danger-full-access` |
370
+ | `WORKER_TIMEOUT_S` | `1800` | 单任务默认超时(秒);旧默认 900s 实测偏小(v0.10.0 起改 1800) |
371
+ | `WORKER_MAX_CONCURRENT` | `2` | 全局并发任务上限(1–8,另受同 session 串行约束) |
372
+ | `WORKER_MAX_CONCURRENT_PER_CWD` | `1` | 同一 **git 仓库根**(含子目录/worktree 任务)的并发上限;非 git 目录回退按 cwd 计(防止单项目占满) |
373
+ | `WORKER_TASK_TTL_MIN` | `1440` | 已结束任务保留分钟数,超时自动清理 |
374
+ | `WORKER_TASK_MAX` | `500` | 任务数上限;超额先淘汰最老的已结束任务 |
375
+ | `WORKER_CLEANUP_INTERVAL_MIN` | `10` | 自动清理间隔(分钟) |
376
+ | `WORKER_AUDIT_DIR` | `$DSH_HOME/mcp-audit` | 审计日志目录(`audit.jsonl`) |
377
+ | `WORKER_BATCH_DIR` | `$DSH_HOME/mcp-batches` | 批量任务元数据目录 |
378
+ | `WORKER_BATCH_MAX` | `8` | 单次批量提交的最大任务数(1–32) |
379
+ | `WORKER_OTEL_ENDPOINT` | 无 | OTLP/HTTP traces 端点(如 `http://127.0.0.1:4318/v1/traces`);空 = 关闭 |
380
+ | `WORKER_OTEL_SERVICE` | `agent-worker-mcp` | OTel `service.name` |
381
+ | `WORKER_DSH_PATCH` | `apply` | DSH 兼容补丁:`apply`(启动时自动检测+修复①pwsh 编码前缀 ②输出 GBK 兜底解码)/ `notify` / `off` |
382
+ | `WORKER_ACL_FALLBACK` | `danger-full-access` | workspace-write ACL 失败后的目标模式:`danger-full-access`(第二级升级)/ `read-only` / `off`。执行顺序固定为「原目录 workspace-write → worktree workspace-write → 目标模式」,每级失败都会重新判定 |
383
+ | `WORKER_ACL_FAIL_FAST` | `1` | 首条命令 ACL 失败即立即中止当前 attempt(不再等模型空转/长超时),进入降级决策 |
384
+ | `WORKER_ALLOW_FULL_ACCESS_FALLBACK` | `1` | 是否允许自动升级 `danger-full-access`;**发布给他人使用建议设 `0`**(保持 fail-closed,由 leader 显式选择);`read-only` 降级不受影响 |
385
+ | `WORKER_STATUS_WAIT_MAX_S` | `120` | `worker_status` 单次长轮询等待上限(秒,5–600);调大可减少 leader 轮询次数 |
386
+ | `WORKER_MAX_TASK_TOKENS` | `0` | **暂缓启用**:单任务 DSH token 预算,默认 `0`=不限制、不产生任何行为。实现已完成但按当前决定不开启;待积累 ≥20 条成功任务后,再按任务类型 p90×1.5 校准并启用(`totalTokens` 94–98% 是 cacheRead,若控成本需另按 input+output 折算) |
387
+ | `WORKER_CAPABILITY_CACHE` | `1` | cwd 能力缓存(落盘,auto 模式据此选权限模式),跨 worker 进程;同时记录「worktree 根 ACL 不可用」,避免同 root 反复创建+失败 |
388
+ | `WORKER_CAPABILITY_TTL_H` | `24` | cwd / worktree 根能力缓存 TTL(小时);修好 ACL 后等 TTL 过期或删缓存文件即可重新尝试 worktree |
389
+ | `WORKER_RETRY_TRANSIENT` | `1` | 后端崩溃/初始化失败时自动重试一次 |
390
+ | `WORKER_AUTO_WORKTREE` | `1` | ACL 受限仓库自动创建可写 worktree(仅干净 git 仓库)。**worktree 根目录必须对当前用户完全控制**,否则 worktree 同样会 ACL 失败 |
391
+ | `WORKER_WORKTREE_ROOT` | `~/dsh-worktrees` | 自动 worktree 根目录;不要指向 ACL 受限的盘/目录(如企业仓库所在的受限 D 盘),默认的用户主目录满足 |
392
+ | `WORKER_WORKTREE_CLEANUP` | `1` | 终态任务过期后自动 `git worktree remove/prune`(不影响任务证据 `diff.patch`) |
393
+ | `WORKER_WORKTREE_TTL_MIN` | `1440` | worktree 保留时长(分钟),超时由清理任务移除 |
394
+ | `WORKER_NOTIFY_WEBHOOK` | 无 | 任务结束 POST 通知(JSON) |
395
+ | `WORKER_NOTIFY_CMD` | 无 | 任务结束执行命令(`WORKER_NOTIFY_JSON` 环境变量传事件) |
396
+ | `WORKER_MAX_RESULT_CHARS` | `40000` | 结果超长时落盘阈值 |
397
+ | `WORKER_IDEM_TTL_H` | `24` | 幂等键有效期(小时,0 = 永不过期);`worker_run(idempotency_key)` 重试去重 |
398
+ | `WORKER_IDEM_DIR` | `$DSH_HOME/mcp-idem` | 幂等键索引落盘目录 |
399
+ | `WORKER_PRICE_INPUT_PER_MTOK` | `0.28` | 费用估算:输入 token 单价(美元/百万 token) |
400
+ | `WORKER_PRICE_CACHE_READ_PER_MTOK` | `0.028` | 费用估算:cacheRead 单价(美元/百万 token) |
401
+ | `WORKER_PRICE_OUTPUT_PER_MTOK` | `0.42` | 费用估算:输出 token 单价(美元/百万 token) |
402
+ | `WORKER_USD_CNY` | `6.65` | 费用估算展示用美元兑人民币汇率 |
403
+ | `WORKER_MAX_STATUS_EVENTS` | `100` | 单次 `worker_status` 最多返回多少条事件(仍受字节预算限制) |
404
+ | `WORKER_MAX_STATUS_PAYLOAD_BYTES` | `16384` | 单次 `worker_status` 结构化载荷(JSON)的 UTF-8 字节上限;超出时只返回能放下的摘要并标记 `events_truncated` |
405
+ | `WORKER_EVIDENCE_GIT` | `1` | 是否采集 git 证据(status/diff 摘要 + diff.patch);置 0 关闭 |
406
+ | `WORKER_REPORT_PROTOCOL` | `1` | 是否向任务文本注入 `[DSH:NEEDS_DECISION]` 汇报协议页脚 |
407
+ | `WORKER_STATUS_DETAIL` | `summary` | `worker_status` 默认 detail;置 `events` 回退到旧行为 || `WORKER_TASKS_DIR` | `$DSH_HOME/mcp-tasks` | 任务落盘根目录 |
408
+ | `DSH_HOME` | `~/.dsh` | DSH 状态目录(会透传给子进程) |
409
+
410
+ 权限模式说明(DSH 侧行为):
411
+ - `read-only`:只读任务;
412
+ - `workspace-write`(默认):项目目录内可读写、可跑命令;越界/提权操作会被 DSH 审批 **fail-closed 拒绝**(headless 没有审批通道);
413
+ - `danger-full-access`:全权,谨慎使用(只在明确信任的任务上开)。
414
+
415
+ ## 任务落盘与恢复
416
+
417
+ ```
418
+ $DSH_HOME/mcp-tasks/<task_id>/
419
+ meta.json 状态、cwd、session、退出码、错误(含 usageTokens 与幂等键)
420
+ events.jsonl DSH --json 事件流(追加写)
421
+ result.txt 输出超长时的完整结果
422
+ $DSH_HOME/mcp-idem/
423
+ idem-<key-hash>.json 幂等键 → task_id 索引(默认保留 24h)
424
+ ```
425
+
426
+ 审计日志(append-only,独立于任务目录):`$DSH_HOME/mcp-audit/audit.jsonl`,记录 `task_created` / `task_started` / `task_succeeded|failed|cancelled` / `approval_*`;可用 `worker_audit` 查询。
427
+
428
+ worker 重启时,未完成的 `queued/running` 任务会被标记为 `failed`(`interrupted: worker restarted before the task finished`),不会假装成功。
429
+
430
+ ## 安全模型
431
+
432
+ - **只走 stdio 或显式 HTTP**:默认 stdio 不监听端口;HTTP 模式必须 Bearer token(`0.0.0.0` 无 token 直接拒绝启动)。
433
+ - **cwd 校验**:拒绝用户主目录及其祖先目录(Windows ACL 沙箱会让 shell 工具不可用),可加 `WORKER_ALLOWED_CWDS` 白名单。
434
+ - **默认 fail-closed**:无人值守没有审批通道(两种后端一致),需要审批的操作一律拒绝,不会静默放权。
435
+ - **取消即杀进程树**(Windows `taskkill /T /F`),避免僵尸 DSH。
436
+ - **输出有界**:超长结果落盘,避免撑爆 leader 上下文。
437
+
438
+ ## 已知限制
439
+
440
+ 1. **冷启动**:`sdk` 后端首次任务支付一次 initialize(本机实测 7–30s,随机器负载波动),之后每任务只付模型时间(实测 3s 级);`headless` 后端每任务 4–11s(fallback)。initialize 超时默认 300s,失败自动重试 1 次;仍失败则**自动降级 headless** 重跑同一任务(避免 leader 直接看到一次失败)。
441
+ 2. **sdk 后端没有 cancel 协议**:`worker_cancel` 等价于杀掉该 cwd 的后端进程,下次任务自动重建(已实测);同一 cwd + 权限模式共享一个后端。
442
+ 3. **sdk 后端模型/权限是进程级**:模型由 `WORKER_SDK_MODEL` 固定;不同 `permission_mode` 会走不同后端进程。
443
+ 4. **session_id 复用**仅在同一个后端进程生命周期内可靠;进程被回收/杀掉后同 id 行为未验证。
444
+ 5. `--json` 事件流对非 `final` 字段有 8 KiB / 32 KiB 截断,`final` 无损;完整轨迹看 `events.jsonl`。
445
+ 6. 同一 `session_id` 只能串行;并发续聊需拆成不同 session。
446
+ 7. Progress 通知依赖 leader 传 `progressToken`;不传时只是没有进度事件,不影响任务。
447
+ 8. **HTTP 模式是无状态的**:每个请求独立创建 server/transport,不做 MCP 会话;进度通知只在单次请求的 SSE 流内有效。
448
+ 9. **任务会被自动清理**:超过 `WORKER_TASK_TTL_MIN` 的已结束任务(含落盘目录)会被删除,之后查询返回 `task_not_found`。
449
+ 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 兜底。
450
+ 11. **initialize 偶发卡顿**:initialize 正常 7–30s;曾出现 >120s 超时(旧默认值)导致任务失败,现已改为 300s + 重试 + headless 降级,并在错误里带 stderr 证据。
451
+ 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` 收紧。
452
+ 13. **自动升级的 full access 无沙箱**:任务在 `danger-full-access` 下可读写当前用户能访问的任意路径;这是为「调用简单」有意选择的 B 方案,请配合 `WORKER_ALLOWED_CWDS` 限定目录、审计日志与 git 回滚使用;高敏感仓库建议用 `read-only` 或 `off`。
453
+ 10. **审计日志无轮转**:`audit.jsonl` 持续追加,长期使用需自行归档/切割。
454
+ 11. **ChatGPT 直连未打通**:需要 Secure MCP Tunnel(无配额未实测)或自建 HTTPS + OAuth 2.1(OAuth 未实现);本地 HTTP + Bearer 给不了 ChatGPT。
455
+ 12. **审批桥 v0 是粗粒度**:只做「检测审批阻断 → elicitation 询问 → 整任务以 danger-full-access 重试」,且真实 DSH 审批场景尚未端到端实测。
456
+ 13. **批量/检索的边界**:批量元数据(`batch_id → task_ids`)落盘可跨重启,但子任务本身仍受 TTL 清理;`worker_search` 只扫内存中保留的任务(被清理的历史任务搜不到)。
457
+ 14. **OTel 是轻量实现**:不引 OTel SDK,只把**每个任务的 span** 以 OTLP/HTTP JSON 推送(best-effort,3s 超时);指标是 `worker_metrics` 拉取式快照,未做 OTLP metrics 推送。
458
+ 15. **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`。
459
+ 16. ChatGPT web / Claude Desktop 两条远程/打包路径尚未实测。
460
+ 17. **续聊 session 不能跨后端恢复(已自动恢复)**:DSH SDK 协议只有 `initialize/session/prompt/shutdown`,没有 resume/restore;worker 重启或后端重建后用旧 session id 续聊会报 `session "..." already exists`。worker 自动换新 session id 重试一次,并把上一轮任务/结果摘要作为「续聊上下文」拼进新指令(事件 `session_resume_fallback` 可见;结果里的 `session_id` 是新 id)。同一后端存活时则正常续聊、不触发恢复。
461
+ 18. **长任务空闲回收(v0.6.5 已修)**:此前 `sweep()` 只看 `lastUsedAt`,运行超过 10 分钟的任务会被回收杀掉(真实 11 分钟任务、13.3M token 沉没);现在有 in-flight prompt 的后端不会被回收,任务结束刷新时间。
462
+ 19. **read-only 的 ACL 误判(v0.6.5 已修)**:此前只要事件/最终文本里出现 `SetNamedSecurityInfoW` 就会被当作写沙箱失败,导致已产出完整报告的只读任务被标 failed;现在仅「非 read-only 模式 + tool_result.isError」才判定。
463
+ 20. **token 预算默认关闭**:`WORKER_MAX_TASK_TOKENS=0`;建议真实使用设 3M–8M,防止单个失控任务烧掉大量额度。超限任务会被取消并标 failed(不是用户取消),事件流有 `token_budget_exceeded`。
464
+ 21. **自动 worktree 只对干净 git 仓库生效**:有未提交改动/非 git 仓库不会复制(直接进入 ACL 降级链的下一级)。worktree 默认按 `WORKER_WORKTREE_TTL_MIN`(24h)自动 `git worktree remove/prune`;清理前如需合入,用 `worker_result.worktree` 路径审查,`diff.patch` 证据不受清理影响。
465
+ 22. **完成通知是外部通道**:MCP 协议无法主动唤醒空闲 leader;`WORKER_NOTIFY_WEBHOOK`/`NOTIFY_CMD` 用于 webhook/桌面通知,未配置时不发通知。
466
+ 23. **发布/外部用户建议**:设 `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` 三种修法。
467
+ 24. **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)。
468
+
469
+ ## 排错
470
+
471
+ | 现象 | 处理 |
472
+ |---|---|
473
+ | leader 里工具列表没有 dsh_* | 检查命令路径、`node` 版本(需 ≥20);Claude Code 用 `claude mcp get dsh` 看状态与日志 |
474
+ | `DSH worker 错误 [invalid_cwd]` | 传具体项目目录;不要用 `C:\Users\<user>` 这类主目录 |
475
+ | `DSH worker 错误 [task_not_finished]` | 任务还没结束:先 `worker_status` 轮询到终态,再 `worker_result` |
476
+ | 任务 `failed` 且 error 提到 approval | 当前任务需要审批(如写工作区外):换 `permission_mode=danger-full-access` 或把操作限定在 cwd 内 |
477
+ | 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 尊重配置) |
478
+ | `read-only` 任务中文输出乱码 / stderr 出现 `InvalidOperation: 无法创建类型…` | worker 启动时自动修复两层(前缀 + GBK 兜底解码);若调成 `notify/off`,手动跑 `scripts/patch-dsh-pwsh-encoding.ps1` 和 `scripts/patch-dsh-output-decoding.ps1` |
479
+ | 任务报 `SetNamedSecurityInfoW failed (Win32 5): grantWrite(...)` | 该目录 ACL 只有 Modify(常见于公司仓库):worker 默认自动升级 `danger-full-access` 重试,结果里 `sandbox_fallback`/`effective_permission_mode` 可见;不想用全权则设 `WORKER_ACL_FALLBACK=read-only` 或 `off` |
480
+ | 续聊报 `session "..." already exists` | 正常降级路径:worker 自动换新 session id + 带上本地「续聊上下文」重试(事件 `session_resume_fallback`),无需手动处理;若任务需要严格原会话历史,请在同一 worker 进程/后端存活期内续聊 |
481
+ | 找不到 DSH 入口 | 设 `WORKER_DSH_CLI=D:\dsh-harness\node_modules\@deepseek-ai\dsh\lib\bin.js` |
482
+ | 想看真实参数/限制 | 调 `worker_describe` |
483
+
484
+ ## 开发
485
+
486
+ ```
487
+ src/
488
+ index.ts stdio 入口(生产环境装配)
489
+ server.ts MCP 工具注册(14 个工具 + instructions)
490
+ task-manager.ts 异步任务:排队/并发/session 串行/每仓库配额/TTL 清理/状态机/长轮询/恢复/审计
491
+ dsh-runner.ts headless 后端:spawn dsh、NDJSON 解析、超时、杀进程树、stderr 尾部
492
+ sdk-backend.ts sdk 后端:长驻进程、initialize、prompt、session.event 映射、取消=杀进程
493
+ sdk-pool.ts 按 cwd + 权限模式缓存后端,空闲回收
494
+ sdk-runner.ts 用长驻后端实现 TaskRunner
495
+ fallback-runner.ts sdk 启动失败时自动降级 headless(仅基础设施失败触发)
496
+ sandbox-errors.ts Windows ACL 沙箱失败识别(grantWrite Win32 5)与降级判定/提示
497
+ jsonrpc-line.ts 换行 JSON-RPC 客户端(请求/通知/超时/关闭)
498
+ http-server.ts Streamable HTTP 传输(无状态、Bearer、/healthz)
499
+ approval.ts 审批阻断检测(供 worker_result 的审批桥使用)
500
+ audit.ts append-only 审计日志(JSONL)
501
+ artifacts.ts 任务产物的安全分页读取(worker_read_result)
502
+ evidence.ts 从事件提取结构化证据:命令退出码/标记/编辑聚合(预算内)
503
+ git-evidence.ts git 基线/变更文件/diff.patch 采集(超时与失败不影响任务)
504
+ report-protocol.ts 汇报协议页脚注入 + [DSH:NEEDS_DECISION] 检测 batch-manager.ts 批量任务(fan-out):创建、聚合状态/结果、取消
505
+ search.ts 历史任务内容检索(输出 + 工具结果)
506
+ otel.ts 轻量 OTLP/HTTP span 导出(无 SDK 依赖)
507
+ usage.ts DSH token 用量提取/累加(headless step_end 与 sdk assistant/message)
508
+ pricing.ts DeepSeek 单价与费用估算(USD/CNY,v0.10.0 合并自在用版 bridge)
509
+ usage-report.ts 用量/成本聚合(worker_usage 工具,按天/按 cwd)
510
+ idempotency.ts 幂等键落盘索引(worker_run idempotency_key 去重)
511
+ dsh-patch.ts DSH 兼容补丁:启动时检测/修复 pwsh 编码前缀(apply/notify/off)
512
+ ndjson.ts NDJSON 解析(跨 chunk/CRLF/脏行)
513
+ output.ts 输出落盘与摘要
514
+ keyed-lock.ts session 级串行锁
515
+ config.ts 环境变量、DSH 入口探测、cwd 校验
516
+ store.ts meta.json / events.jsonl 落盘
517
+ test/ 216 个单测 + 真实 DSH 烟测(`test/mcp-smoke.ts`、`test/http-smoke.ts`)
518
+ examples/ 多端接入示例(Claude / Codex / MCPB / 远程接入)
519
+ scripts/ 部署与运维:deploy.ps1(源码→运行目录)/ patch-dsh-pwsh-encoding / patch-dsh-output-decoding / measure-goals / leader-usage / monitor-thread.py(Codex thread 配额/token 监控,兼容两版任务落盘)
520
+ docs/ measurement.md(目标口径/公式/A/B 协议/局限)、delegation-playbook.md(委派粒度与任务模板)
521
+ ```
522
+
523
+ ```powershell
524
+ pnpm test # 单元测试(假 DSH fixture,不耗模型 token)
525
+ pnpm smoke # 真实 DSH 全链路(stdio,消耗少量 token)
526
+ pnpm smoke:http # 真实 HTTP 传输冒烟(healthz / 401 / 真实任务)
527
+ pnpm measure:ab # 目标达成率 A/B(leader 自己做 vs 委派 DSH;消耗 leader 额度)
528
+ pnpm measure:leader# 扫描 leader 会话用量(Claude transcripts + Codex rollouts)
529
+ pnpm build # tsc 产物到 dist/
530
+ ```
531
+
532
+ 测试覆盖: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` 兼容、单价覆盖)。
533
+
534
+ ## 发布到 npm(维护者)
535
+
536
+ 采用 **npm Trusted Publishing(OIDC 绑定 GitHub Actions)**,CI 发布不需要 `NPM_TOKEN`。
537
+
538
+ 1. **首次发布必须手动**(npm 上还不存在该包时无法配置 Trusted Publisher):
539
+ ```powershell
540
+ npm login # 浏览器/2FA
541
+ pnpm build
542
+ npm publish --access public
543
+ ```
544
+ 2. 在 npm 包页面 → Settings → Trusted Publishing → GitHub Actions:
545
+ - Organization/user:`tongsh6`
546
+ - Repository:`agent-worker-mcp`
547
+ - Workflow filename:`publish.yml`
548
+ - 保存时按需输入 2FA。
549
+ 3. 之后发布只需打 tag:
550
+ ```powershell
551
+ npm version patch --no-git-tag-version
552
+ git add -A && git commit -m "chore(release): vX.Y.Z"
553
+ git tag vX.Y.Z && git push --follow-tags
554
+ ```
555
+ Actions 会执行 `pnpm test` → `pnpm build` → `npm publish --access public --provenance`(OIDC,无 token)。
556
+ 4. 也可在 Actions → publish → Run workflow 手动触发。
557
+
558
+ > 注意:npm Trusted Publisher 要求使用较新的 npm CLI(workflow 里用 Node 24),且 workflow 文件名必须与配置一致。
559
+
560
+ License:MIT(见 [LICENSE](LICENSE))。
561
+ 14. **退出码来自文本标记**:`[exit code: N]` / `[killed by signal]` / `[timed out]` / `[sandbox: ...]` 由 worker 从工具输出解析;DSH 若改格式,`exit_code` 会退化为 `null` 并保留 `markers` 原文,不会给错值。
562
+ 15. **git 证据的 pre_existing 是文件级**:只能标记「任务开始前已脏」的文件,无法区分同一文件里任务前后各自的改动行。
563
+ 16. **决策协议依赖 DSH 遵守标记**:`[DSH:NEEDS_DECISION]` 由模型按页脚输出;不遵守时退化为 `completed` + 叙述,不做启发式猜测;可用 `worker_metrics.outcomes` 观察遵守率。
564
+ 17. **`worker_status` 默认 detail 变更(v0.9.0)**:默认不再回传 tool_call/tool_result/text 事件;需要旧行为时传 `detail=events` 或设 `WORKER_STATUS_DETAIL=events`。
565
+ ## 路线图
566
+
567
+ - **M1 ✅ 已完成(2026-11-02)**:长驻 `dsh --profile sdk` 后端(默认),一次 initialize 后每任务只发 prompt;保留 `headless` fallback。
568
+ - **M2 🟡 部分完成(2026-11-02)**:HTTP 传输(无状态 Streamable HTTP + Bearer + `/healthz`)与审批桥 v0 已实现并测试;ChatGPT 直连需 Secure MCP Tunnel(无配额)或 OAuth 2.1(未实现),见 [examples/remote-access.md](examples/remote-access.md)。
569
+ - **M3 ✅ 已完成(2026-11-02)**:任务 TTL 清理 + 数量上限、每 cwd 并发配额(v0.9.4 起按 git 仓库根)、审计日志(`worker_audit`)、`worker_tasks`、`worker_read_result`。
570
+ - **M4 ✅ 已完成(2026-11-02)**:批量派发(fan-out)/ 历史任务检索 / 指标快照 / 轻量 OTel span 导出。
571
+ - **M5 ✅ 已完成(2026-11-02)**:目标达成率测量——worker 侧 DSH token 计量、A/B 对照工具、leader 用量扫描器、口径文档。
572
+ - **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`。
573
+
574
+ > 设计依据与市场调研见 `本机分析报告(未随仓库提供)`。
575
+
2
576
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.