npm - dsh-mcp-worker - Versions diffs - 0.7.1 → 0.7.2 - Mend

dsh-mcp-worker 0.7.1 → 0.7.2

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 (5) hide show

package/LICENSE CHANGED Viewed

@@ -1,21 +1,21 @@
-MIT License
-Copyright (c) 2026 tongsh6
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+Copyright (c) 2026 tongsh6
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -1,460 +1,460 @@
-# dsh-mcp-worker
-把本机 **DSH（DeepSeek Harness）** 暴露成一个 **MCP worker**，让 **Claude Code / Codex CLI / ChatGPT（桌面）/ Claude Desktop** 这些 leader 把重活交给它跑。
-> 角色模型：leader（决策、编排）通过 MCP 调用 worker（DSH）；worker 在真实项目目录里执行长任务（读代码、改文件、跑命令、跑测试），只把结果回传。
-## 现状（本地已验证）
-| 项 | 状态 |
-|---|---|
-| 单元测试 | ✅ 127/127 通过（`pnpm test`） |
-| 真实链路烟测 | ✅ MCP Client → worker → 真实 DSH：问答 + 写文件（`hello-dsh.txt`）全链路通过 |
-| 长驻后端（M1） | ✅ 默认 `backend=sdk`：真实烟测首任务 9s（含一次初始化）、第二任务 **3s**；大仓库真实任务 18.4s（含 initialize）；`headless` 保留为 fallback |
-| 远程传输（M2a） | ✅ `DSH_MCP_TRANSPORT=http`：真实 HTTP 冒烟通过（`/healthz` 200、无 token 401、MCP HTTP 客户端跑真实任务 8s） |
-| 审批桥（M2b） | ✅ `dsh_result` 检测审批阻断 → elicitation 询问授权 → 以 `danger-full-access` 重试（4 个单测覆盖；真实 DSH 审批场景未端到端实测） |
-| 运维治理（M3） | ✅ 任务 TTL 自动清理 + 数量上限（超额淘汰最老已结束任务）、每 cwd 并发配额、审计日志（`dsh_audit`）、任务列表（`dsh_tasks`）、完整产物分页读取（`dsh_read_result`） |
-| 批量/检索/观测（M4） | ✅ `dsh_batch_run/status/result` 批量派发与聚合、`dsh_search` 历史任务内容检索、`dsh_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） | ✅ 公司仓库等「仅 Modify ACL」目录请求 workspace-write 时会遇 `SetNamedSecurityInfoW failed (Win32 5): grantWrite`；worker 检测后自动升级为 **danger-full-access + 新 session** 重试，`dsh_result.sandbox_fallback` / `effective_permission_mode` 记录实际模式（真实受限仓库验证：succeeded、output=ok、30s）；可用 `DSH_MCP_ACL_FALLBACK=read-only` 或 `off` 收紧 |
-| 委派粒度策略（v0.6.4） | ✅ 规则改为「一个 dsh_run = 一个可验收工作单元（实现+自测+证据），禁止微任务」；长轮询上限 25s→可配 120s（`DSH_MCP_STATUS_WAIT_MAX_S`），减少 leader 往返；规则已写入 `~/AGENTS.md`、`~/.codex/AGENTS.md`、worker instructions 与 [docs/delegation-playbook.md](docs/delegation-playbook.md) |
-| 执行记录分析（v0.6.5） | ✅ 分析 11-02~11-09 的 64 个任务/200 条审计：修复「长任务被空闲回收误杀」（11 分钟任务、13.3M token 沉没）与「read-only 任务被 ACL 文本误判 failed」；新增 `dsh_status` 实时 `tokens/steps/tool_calls`、`dsh_result.partial_output/failure_kind`、token 预算护栏 `DSH_MCP_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 可调 + 瞬态失败自动重试 + 失败诊断 + `dsh_run(wait_s)` 单调用等待 + MCP 调用/字节指标 + 任务完成 webhook/命令通知 |
-| 目标测量（v0.6） | ✅ worker 侧 DSH token 计量（`dsh_result.usage.tokens` / `dsh_metrics.tokens`）+ A/B 对照工具 + leader 用量扫描器；真实首测：加速 **2.29x**、leader token 省 **46.0%**、cost 省 **31.1%**、达成率 2/2 |
-| cwd 安全校验 | ✅ 传用户主目录会被拒绝（Windows ACL 沙箱限制） |
-| Claude Code 接入 | ✅ 已注册（user scope）并实测连通：`claude mcp get dsh` → `√ Connected`；`claude -p` 真实调用 `dsh_describe` 成功 |
-| Codex 接入 | ✅ 已写入 `~/.codex/config.toml`，`codex mcp get dsh` 解析正常（工具白名单/超时/审批模式生效；未做真实调用） |
-| ChatGPT 桌面 app | ⚠️ 未实测（调研显示它与 Codex 共享 `~/.codex/config.toml`，配法同 Codex） |
-| 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 删掉对应块）。
-## 架构
-```
-leader（Claude Code / Codex / ChatGPT / Claude Desktop）
-   │  MCP over stdio（本地）或 Streamable HTTP /mcp + Bearer（远程）
-   ▼
-dsh-mcp-worker（本进程）
-   │  dsh_run 立即返回 task_id；任务后台执行
-   │  任务落盘：meta.json / events.jsonl / result.txt
-   ▼  后端可切换（DSH_MCP_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）
-```
-## 快速开始
-```powershell
-cd C:\path\to\dsh-mcp-worker
-pnpm install
-pnpm build
-pnpm test          # 127 个单测
-pnpm smoke         # 真实 DSH 集成烟测（约 30–60s）
-```
-worker 通过 **stdio** 工作，自身不监听任何端口。需要它时由 leader 拉起子进程。
-## 部署（源码与运行分离）
-源码仓库只用于开发（`pnpm build` / `pnpm test`）；**MCP 客户端只加载运行目录**，不要指向仓库内的 `dist`。
-```powershell
-# 在源码仓库里构建并部署到运行目录（示例：D:\dsh-mcp-worker）
-pnpm build
-pwsh -File scripts/deploy.ps1 -Target D:\dsh-mcp-worker
-```
-- MCP 入口应为运行目录：`D:\dsh-mcp-worker\dist\index.js`；
-- 运行目录包含 `dist/` + 生产依赖（`pnpm install --prod`）+ package 元数据，不含测试/开发依赖；
-- 更新流程：`git pull` → `pnpm install` → `pnpm test` → `scripts/deploy.ps1` → 重启 leader 会话；
-- 默认运行目录可用 `DSH_MCP_WORKER_HOME` 指定，也可直接 `pnpm deploy`（等价于执行该脚本）。
-## 通过 npm 使用
-包名：`dsh-mcp-worker`（只发布构建产物；本机仍需安装 DSH）。
-```powershell
-npm i -g dsh-mcp-worker      # 或直接用 npx
-npx -y dsh-mcp-worker        # 由 MCP 客户端拉起（stdio）
-```
-MCP 客户端配置可用：
-```json
-{
-  "mcpServers": {
-    "dsh": { "command": "npx", "args": ["-y", "dsh-mcp-worker"] }
-  }
-}
-```
-注意：npm 包**不包含 DSH 本体**；worker 通过 `dsh`（PATH）、`DSH_MCP_DSH_DIR` 或 `DSH_MCP_DSH_CLI` 找到本机 DSH。
-## 接入 leader
-### 1) Claude Code（最省事）
-```powershell
-claude mcp add --scope user --transport stdio dsh -- node "C:\path\to\dsh-mcp-worker\dist\index.js"
-claude mcp list
-claude mcp get dsh
-```
-带环境变量时注意 `--env` 的位置（放在 server 名之前）：
-```powershell
-claude mcp add --scope user --transport stdio --env DSH_MCP_DEFAULT_CWD="D:\work\repo" dsh -- node "C:\path\to\dsh-mcp-worker\dist\index.js"
-```
-等价 `.mcp.json` 见 [examples/claude-mcp.json](examples/claude-mcp.json)。
-**避免每次弹授权**：把 dsh 工具加入用户级 allowlist（`~/.claude/settings.json` 的 `permissions.allow`）：
-```json
-["mcp__dsh__dsh_run", "mcp__dsh__dsh_status", "mcp__dsh__dsh_result", "mcp__dsh__dsh_cancel", "mcp__dsh__dsh_describe",
- "mcp__dsh__dsh_tasks", "mcp__dsh__dsh_audit", "mcp__dsh__dsh_read_result", "mcp__dsh__dsh_batch_run",
- "mcp__dsh__dsh_batch_status", "mcp__dsh__dsh_batch_result", "mcp__dsh__dsh_search", "mcp__dsh__dsh_metrics"]
-```
-> 本机已写入（备份 `settings.json.bak-dsh-allow-20261102`）。安全边界仍由 worker 的 `permission_mode` / 审批桥承担。
-### 2) Codex CLI / IDE
-把下面加到 `~/.codex/config.toml`（完整示例见 [examples/codex-config.toml](examples/codex-config.toml)）：
-```toml
-[mcp_servers.dsh]
-command = "node"
-args = ["C:\\path\\to\\dsh-mcp-worker\\dist\\index.js"]
-startup_timeout_sec = 30          # 默认 10；worker 自身启动很快，留余量
-tool_timeout_sec = 300            # 默认 60；allow dsh_status 长轮询（wait_s≤120s）
-enabled_tools = ["dsh_run", "dsh_status", "dsh_result", "dsh_cancel", "dsh_describe", "dsh_tasks", "dsh_audit", "dsh_read_result", "dsh_batch_run", "dsh_batch_status", "dsh_batch_result", "dsh_search", "dsh_metrics"]
-# approve = 不再询问（auto 仍会按风险询问）；安全边界由 worker 的 permission_mode（默认 workspace-write）兜底
-default_tools_approval_mode = "approve"
-# 桌面端对 MCP 工具的审批可被 per-tool 覆盖（13 个工具都要写）
-[mcp_servers.dsh.tools.dsh_run]
-approval_mode = "approve"
-# ……其余工具同理：dsh_status / dsh_result / dsh_cancel / dsh_describe / dsh_tasks / dsh_audit /
-# dsh_read_result / dsh_batch_run / dsh_batch_status / dsh_batch_result / dsh_search / dsh_metrics
-[mcp_servers.dsh.env]
-DSH_MCP_DEFAULT_CWD = "C:\\path\\to\\your\\project"
-```
-校验：`codex mcp get dsh`（本机已配置为 `default_tools_approval_mode: approve` + 13 个 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）：
-  ```bash
-  tunnel-client init --sample sample_mcp_stdio_local --profile dsh-local \
-    --tunnel-id tunnel_xxxxxxxx --mcp-command "node C:\\path\\to\\dsh-mcp-worker\\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](examples/mcpb-manifest.json)。需要把 `dist/` 与 `node_modules` 一起打包进 MCPB 扩展，用 `mcpb pack` 生成 `.mcpb` 后拖入 Claude Desktop（**未实测**）。
-## 工具面
-| 工具 | 作用 | 关键参数 |
-|---|---|---|
-| `dsh_run` | 提交任务，**立即**返回 `task_id` | `task`（必填）、`cwd`（必填，项目目录）、`session_id?`、`permission_mode?`、`timeout_s?` |
-| `dsh_status` | 查状态 + 增量事件，支持长轮询 | `task_id`、`cursor?`、`wait_s?`（0–25） |
-| `dsh_result` | 取最终结果（输出过大自动落盘） | `task_id` |
-| `dsh_cancel` | 取消任务（杀进程树） | `task_id` |
-| `dsh_tasks` | 列出最近任务摘要（回顾/继续轮询） | `limit?`（1–100）、`status?` |
-| `dsh_audit` | 读取审计事件（任务生命周期/审批决定） | `limit?`（1–200） |
-| `dsh_read_result` | 分页读取落盘的完整结果或事件日志 | `task_id`、`source?`（result/events）、`offset?`、`max_chars?` |
-| `dsh_batch_run` | 批量并行派发（每项可带 cwd/session/权限） | `tasks[]`（1–`maxBatchTasks`） |
-| `dsh_batch_status` | 批量聚合状态（整体状态 + 子任务 + 计数） | `batch_id`、`wait_s?` |
-| `dsh_batch_result` | 批量聚合结果（输出/错误/耗时） | `batch_id`、`max_output_chars?` |
-| `dsh_search` | 在历史任务的输出与工具结果里检索 | `query`、`limit?` |
-| `dsh_metrics` | 计数/耗时分位/排队/后端/OTel 状态 | — |
-| `dsh_describe` | 返回入口/默认值/限制，供 leader 自适应 | — |
-典型调用序列（leader 视角）：
-```jsonc
-// 1) 提交
-{ "name": "dsh_run", "arguments": { "task": "修复 utils.ts 的空指针，并跑 pnpm test 验证", "cwd": "D:\\work\\repo" } }
-// → { task_id, status: "queued", session_id, cwd, hint }
-// 2) 轮询（每次最多等 25s；运行中会收到 notifications/progress）
-{ "name": "dsh_status", "arguments": { "task_id": "...", "cursor": 0, "wait_s": 20 } }
-// 3) 结束后取结果
-{ "name": "dsh_result", "arguments": { "task_id": "..." } }
-```
-状态机：
-```
-queued ──▶ running ──▶ succeeded
-   │           ├──▶ failed（超时/DSH 报错）
-   │           ├──▶ cancelled
-   └──▶ 不会出现：被取消的排队任务会直接 cancelled
-```
-多轮续聊：把首次 `dsh_run` 返回的 `session_id` 传给下一次 `dsh_run`；**同一 session 的任务串行执行**（DSH 侧单写者），不同 session 并行（受 `DSH_MCP_MAX_CONCURRENT` 限制）。
-## 让 leader 主动委派（可选，推荐）
-MCP 只把工具摆给 leader，**是否调用由 leader 模型自己决定**，协议层无法强制。想提高“自动委派”概率，三档手段（从弱到强）：
-1. **工具描述/instructions**（已内置）：`dsh_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 跑」。
-### 粒度怎么定（关键）
-- 一个 `dsh_run` 覆盖「定位 → 实现 → 自测 → 证据」，典型：一个功能点 / 一个 bug / 一个测试修复批次 / 一次跨文件重构；
-- 少于 3 次工具调用或 2 分钟内能做完的事，leader 自己做；不要拆成多个 dsh 任务；
-- 只有独立可并行（用 `dsh_batch_run`）、需要决策、风险隔离时才拆分；
-- 轮询用 `dsh_status(wait_s=60~120)`，不要在 DSH 执行期间重复劳动；
-- 详细模板、反例/正例、验收动作、如何用 `scripts/leader-usage.mjs` 验证：[docs/delegation-playbook.md](docs/delegation-playbook.md)。
-## 目标达成率测量（leader 提速 / 省 token）
-目标前提：Codex/ChatGPT、Claude Code 作为 leader，通过本 worker 把重活交给 DSH。核对方式：**同任务 A/B 对照**（leader 自己做 vs 委派 DSH）。
-```powershell
-# 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](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 无本地计量（见文档局限）。
-## 配置（环境变量）
-| 变量 | 默认 | 说明 |
-|---|---|---|
-| `DSH_MCP_TRANSPORT` | `stdio` | MCP 传输：`stdio`（本地 leader）/ `http`（Streamable HTTP，远程 leader） |
-| `DSH_MCP_HTTP_HOST` | `127.0.0.1` | HTTP 监听地址；`0.0.0.0` 时必须设 token |
-| `DSH_MCP_HTTP_PORT` | `7391` | HTTP 端口（`0` = 随机） |
-| `DSH_MCP_HTTP_TOKEN` | 无 | HTTP Bearer token；非回环地址必填 |
-| `DSH_MCP_DSH_CLI` | 自动探测 | `@deepseek-ai/dsh/lib/bin.js` 的绝对路径（用 `node` 启动，最稳） |
-| `DSH_MCP_DSH_COMMAND` | — | 完整命令（如 `dsh`），通过 shell 启动；优先级低于 `DSH_MCP_DSH_CLI` |
-| `DSH_MCP_DSH_DIR` | — | DSH 安装目录（自动拼 `node_modules/@deepseek-ai/dsh/lib/bin.js`） |
-| `DSH_MCP_PROFILE` | `headless` | `headless` 后端使用的 profile |
-| `DSH_MCP_BACKEND` | `sdk` | 执行后端：`sdk`（长驻，默认）/ `headless`（每任务一进程） |
-| `DSH_MCP_SDK_PROFILE` | `sdk` | 长驻后端使用的 DSH profile |
-| `DSH_MCP_SDK_PROVIDER` | `deepseek-official` | SDK 后端 provider |
-| `DSH_MCP_SDK_MODEL` | `deepseek-flash` | SDK 后端 model（进程级固定） |
-| `DSH_MCP_SDK_REASONING_EFFORT` | 无 | 推理强度（可选，如 `max`） |
-| `DSH_MCP_SDK_MAX_TOKENS` | 无 | 单次输出 token 上限（可选） |
-| `DSH_MCP_SDK_IDLE_MIN` | `10` | 后端空闲多少分钟回收（1–240） |
-| `DSH_MCP_SDK_INIT_TIMEOUT_S` | `300` | 后端 initialize 超时（秒）；失败自动重试 1 次，仍失败则自动降级 headless |
-| `DSH_MCP_DEFAULT_CWD` | 无 | 省略 `cwd` 时使用；没设则用 worker 进程 cwd（stdio 启动时通常是 leader 的项目目录） |
-| `DSH_MCP_ALLOWED_CWDS` | 无 | 分号分隔的允许目录白名单（设置后只能在这些目录下跑） |
-| `DSH_MCP_PERMISSION_MODE` | `auto` | 默认 `auto`（worker 按 cwd 能力自动适配）；也可显式 `read-only` / `workspace-write` / `danger-full-access` |
-| `DSH_MCP_TIMEOUT_S` | `900` | 单任务默认超时（秒） |
-| `DSH_MCP_MAX_CONCURRENT` | `2` | 全局并发任务上限（1–8，另受同 session 串行约束） |
-| `DSH_MCP_MAX_CONCURRENT_PER_CWD` | `1` | 同一 cwd 的并发上限（防止单项目占满） |
-| `DSH_MCP_TASK_TTL_MIN` | `1440` | 已结束任务保留分钟数，超时自动清理 |
-| `DSH_MCP_TASK_MAX` | `500` | 任务数上限；超额先淘汰最老的已结束任务 |
-| `DSH_MCP_CLEANUP_INTERVAL_MIN` | `10` | 自动清理间隔（分钟） |
-| `DSH_MCP_AUDIT_DIR` | `$DSH_HOME/mcp-audit` | 审计日志目录（`audit.jsonl`） |
-| `DSH_MCP_BATCH_DIR` | `$DSH_HOME/mcp-batches` | 批量任务元数据目录 |
-| `DSH_MCP_BATCH_MAX` | `8` | 单次批量提交的最大任务数（1–32） |
-| `DSH_MCP_OTEL_ENDPOINT` | 无 | OTLP/HTTP traces 端点（如 `http://127.0.0.1:4318/v1/traces`）；空 = 关闭 |
-| `DSH_MCP_OTEL_SERVICE` | `dsh-mcp-worker` | OTel `service.name` |
-| `DSH_MCP_DSH_PATCH` | `apply` | DSH 兼容补丁：`apply`（启动时自动检测+修复①pwsh 编码前缀 ②输出 GBK 兜底解码）/ `notify` / `off` |
-| `DSH_MCP_ACL_FALLBACK` | `danger-full-access` | workspace-write 沙箱 ACL 授权失败时的自动升级策略：`danger-full-access`（默认，B 方案：升级为全权重试）/ `read-only`（只读重试）/ `off`（直接失败并给修法）。注意 full access 无沙箱 |
-| `DSH_MCP_STATUS_WAIT_MAX_S` | `120` | `dsh_status` 单次长轮询等待上限（秒，5–600）；调大可减少 leader 轮询次数 |
-| `DSH_MCP_MAX_TASK_TOKENS` | `0` | **暂缓启用**：单任务 DSH token 预算，默认 `0`=不限制、不产生任何行为。实现已完成但按当前决定不开启；待积累 ≥20 条成功任务后，再按任务类型 p90×1.5 校准并启用（`totalTokens` 94–98% 是 cacheRead，若控成本需另按 input+output 折算） |
-| `DSH_MCP_CAPABILITY_CACHE` | `1` | cwd 能力缓存（落盘，auto 模式据此选权限模式），跨 worker 进程 |
-| `DSH_MCP_CAPABILITY_TTL_H` | `24` | cwd 能力缓存 TTL（小时） |
-| `DSH_MCP_RETRY_TRANSIENT` | `1` | 后端崩溃/初始化失败时自动重试一次 |
-| `DSH_MCP_AUTO_WORKTREE` | `1` | ACL 受限仓库自动创建可写 worktree（仅干净 git 仓库） |
-| `DSH_MCP_WORKTREE_ROOT` | `~/dsh-worktrees` | 自动 worktree 根目录 |
-| `DSH_MCP_NOTIFY_WEBHOOK` | 无 | 任务结束 POST 通知（JSON） |
-| `DSH_MCP_NOTIFY_CMD` | 无 | 任务结束执行命令（`DSH_MCP_NOTIFY_JSON` 环境变量传事件） |
-| `DSH_MCP_MAX_RESULT_CHARS` | `40000` | 结果超长时落盘阈值 |
-| `DSH_MCP_MAX_STATUS_EVENTS` | `100` | 单次 `dsh_status` 最多返回多少条事件 |
-| `DSH_MCP_TASKS_DIR` | `$DSH_HOME/mcp-tasks` | 任务落盘根目录 |
-| `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、退出码、错误
-  events.jsonl   DSH --json 事件流（追加写）
-  result.txt     输出超长时的完整结果
-```
-审计日志（append-only，独立于任务目录）：`$DSH_HOME/mcp-audit/audit.jsonl`，记录 `task_created` / `task_started` / `task_succeeded|failed|cancelled` / `approval_*`；可用 `dsh_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 工具不可用），可加 `DSH_MCP_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 协议**：`dsh_cancel` 等价于杀掉该 cwd 的后端进程，下次任务自动重建（已实测）；同一 cwd + 权限模式共享一个后端。
-3. **sdk 后端模型/权限是进程级**：模型由 `DSH_MCP_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. **任务会被自动清理**：超过 `DSH_MCP_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)`。worker 默认按 **B 方案**：检测到该失败后自动升级 `danger-full-access` 重试（结果里 `sandbox_fallback` + `effective_permission_mode` 显式记录，不掩盖）；可用 `DSH_MCP_ACL_FALLBACK=read-only|off` 收紧。
-13. **自动升级的 full access 无沙箱**：任务在 `danger-full-access` 下可读写当前用户能访问的任意路径；这是为「调用简单」有意选择的 B 方案，请配合 `DSH_MCP_ALLOWED_CWDS` 限定目录、审计日志与 git 回滚使用；高敏感仓库建议用 `read-only` 或 `off`。
-10. **审计日志无轮转**：`audit.jsonl` 持续追加，长期使用需自行归档/切割。
-11. **ChatGPT 直连未打通**：需要 Secure MCP Tunnel（无配额未实测）或自建 HTTPS + OAuth 2.1（OAuth 未实现）；本地 HTTP + Bearer 给不了 ChatGPT。
-12. **审批桥 v0 是粗粒度**：只做「检测审批阻断 → elicitation 询问 → 整任务以 danger-full-access 重试」，且真实 DSH 审批场景尚未端到端实测。
-13. **批量/检索的边界**：批量元数据（`batch_id → task_ids`）落盘可跨重启，但子任务本身仍受 TTL 清理；`dsh_search` 只扫内存中保留的任务（被清理的历史任务搜不到）。
-14. **OTel 是轻量实现**：不引 OTel SDK，只把**每个任务的 span** 以 OTLP/HTTP JSON 推送（best-effort，3s 超时）；指标是 `dsh_metrics` 拉取式快照，未做 OTLP metrics 推送。
-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 升级后下次启动自动重打。可用 `DSH_MCP_DSH_PATCH=notify|off` 关闭自动修复，手动脚本见 `scripts/patch-dsh-pwsh-encoding.ps1` 与 `scripts/patch-dsh-output-decoding.ps1`。
-16. ChatGPT web / Claude Desktop 两条远程/打包路径尚未实测。
-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）。同一后端存活时则正常续聊、不触发恢复。
-18. **长任务空闲回收（v0.6.5 已修）**：此前 `sweep()` 只看 `lastUsedAt`，运行超过 10 分钟的任务会被回收杀掉（真实 11 分钟任务、13.3M token 沉没）；现在有 in-flight prompt 的后端不会被回收，任务结束刷新时间。
-19. **read-only 的 ACL 误判（v0.6.5 已修）**：此前只要事件/最终文本里出现 `SetNamedSecurityInfoW` 就会被当作写沙箱失败，导致已产出完整报告的只读任务被标 failed；现在仅「非 read-only 模式 + tool_result.isError」才判定。
-20. **token 预算默认关闭**：`DSH_MCP_MAX_TASK_TOKENS=0`；建议真实使用设 3M–8M，防止单个失控任务烧掉大量额度。超限任务会被取消并标 failed（不是用户取消），事件流有 `token_budget_exceeded`。
-21. **自动 worktree 只对干净 git 仓库生效**：有未提交改动/非 git 仓库会退回原目录的降级模式；worktree 创建后保留供 leader 审查，需自行清理。
-22. **完成通知是外部通道**：MCP 协议无法主动唤醒空闲 leader；`DSH_MCP_NOTIFY_WEBHOOK`/`NOTIFY_CMD` 用于 webhook/桌面通知，未配置时不发通知。
-## 排错
-| 现象 | 处理 |
-|---|---|
-| leader 里工具列表没有 dsh_* | 检查命令路径、`node` 版本（需 ≥20）；Claude Code 用 `claude mcp get dsh` 看状态与日志 |
-| `DSH worker 错误 [invalid_cwd]` | 传具体项目目录；不要用 `C:\Users\<user>` 这类主目录 |
-| `DSH worker 错误 [task_not_finished]` | 任务还没结束：先 `dsh_status` 轮询到终态，再 `dsh_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` 可见；不想用全权则设 `DSH_MCP_ACL_FALLBACK=read-only` 或 `off` |
-| 续聊报 `session "..." already exists` | 正常降级路径：worker 自动换新 session id + 带上本地「续聊上下文」重试（事件 `session_resume_fallback`），无需手动处理；若任务需要严格原会话历史，请在同一 worker 进程/后端存活期内续聊 |
-| 找不到 DSH 入口 | 设 `DSH_MCP_DSH_CLI=D:\dsh-harness\node_modules\@deepseek-ai\dsh\lib\bin.js` |
-| 想看真实参数/限制 | 调 `dsh_describe` |
-## 开发
-```
-src/
-  index.ts         stdio 入口（生产环境装配）
-  server.ts        MCP 工具注册（13 个工具 + instructions）
-  task-manager.ts  异步任务：排队/并发/session 串行/每 cwd 配额/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      审批阻断检测（供 dsh_result 的审批桥使用）
-  audit.ts         append-only 审计日志（JSONL）
-  artifacts.ts     任务产物的安全分页读取（dsh_read_result）
-  batch-manager.ts 批量任务（fan-out）：创建、聚合状态/结果、取消
-  search.ts        历史任务内容检索（输出 + 工具结果）
-  otel.ts          轻量 OTLP/HTTP span 导出（无 SDK 依赖）
-  usage.ts         DSH token 用量提取/累加（headless step_end 与 sdk assistant/message）
-  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/              127 个单测 + 真实 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
-docs/              measurement.md（目标口径/公式/A/B 协议/局限）、delegation-playbook.md（委派粒度与任务模板）
-```
-```powershell
-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 进程超时与取消、任务管理器（并发/每 cwd 配额/session 串行/长轮询/恢复/取消/TTL 清理/数量上限/审计）、JSON-RPC 客户端、SDK 长驻后端与池、HTTP 传输（鉴权/healthz）、审批桥、新增只读工具、DSH token 用量提取与累加、DSH 兼容补丁（编码前缀 + GBK 兜底解码；apply/notify/off/幂等/版本漂移）。
-## 发布到 npm（维护者）
-采用 **npm Trusted Publishing（OIDC 绑定 GitHub Actions）**，CI 发布不需要 `NPM_TOKEN`。
-1. **首次发布必须手动**（npm 上还不存在该包时无法配置 Trusted Publisher）：
-   ```powershell
-   npm login          # 浏览器/2FA
-   pnpm build
-   npm publish --access public
-   ```
-2. 在 npm 包页面 → Settings → Trusted Publishing → GitHub Actions：
-   - Organization/user：`tongsh6`
-   - Repository：`dsh-mcp-worker`
-   - Workflow filename：`publish.yml`
-   - 保存时按需输入 2FA。
-3. 之后发布只需打 tag：
-   ```powershell
-   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](LICENSE)）。
-## 路线图
-- **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](examples/remote-access.md)。
-- **M3 ✅ 已完成（2026-11-02）**：任务 TTL 清理 + 数量上限、每 cwd 并发配额、审计日志（`dsh_audit`）、`dsh_tasks`、`dsh_read_result`。
-- **M4 ✅ 已完成（2026-11-02）**：批量派发（fan-out）/ 历史任务检索 / 指标快照 / 轻量 OTel span 导出。
-- **M5 ✅ 已完成（2026-11-02）**：目标达成率测量——worker 侧 DSH token 计量、A/B 对照工具、leader 用量扫描器、口径文档。
-> 设计依据与市场调研见 `本机分析报告（未随仓库提供）`。
+# dsh-mcp-worker
+把本机 **DSH（DeepSeek Harness）** 暴露成一个 **MCP worker**，让 **Claude Code / Codex CLI / ChatGPT（桌面）/ Claude Desktop** 这些 leader 把重活交给它跑。
+> 角色模型：leader（决策、编排）通过 MCP 调用 worker（DSH）；worker 在真实项目目录里执行长任务（读代码、改文件、跑命令、跑测试），只把结果回传。
+## 现状（本地已验证）
+| 项 | 状态 |
+|---|---|
+| 单元测试 | ✅ 127/127 通过（`pnpm test`） |
+| 真实链路烟测 | ✅ MCP Client → worker → 真实 DSH：问答 + 写文件（`hello-dsh.txt`）全链路通过 |
+| 长驻后端（M1） | ✅ 默认 `backend=sdk`：真实烟测首任务 9s（含一次初始化）、第二任务 **3s**；大仓库真实任务 18.4s（含 initialize）；`headless` 保留为 fallback |
+| 远程传输（M2a） | ✅ `DSH_MCP_TRANSPORT=http`：真实 HTTP 冒烟通过（`/healthz` 200、无 token 401、MCP HTTP 客户端跑真实任务 8s） |
+| 审批桥（M2b） | ✅ `dsh_result` 检测审批阻断 → elicitation 询问授权 → 以 `danger-full-access` 重试（4 个单测覆盖；真实 DSH 审批场景未端到端实测） |
+| 运维治理（M3） | ✅ 任务 TTL 自动清理 + 数量上限（超额淘汰最老已结束任务）、每 cwd 并发配额、审计日志（`dsh_audit`）、任务列表（`dsh_tasks`）、完整产物分页读取（`dsh_read_result`） |
+| 批量/检索/观测（M4） | ✅ `dsh_batch_run/status/result` 批量派发与聚合、`dsh_search` 历史任务内容检索、`dsh_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） | ✅ 公司仓库等「仅 Modify ACL」目录请求 workspace-write 时会遇 `SetNamedSecurityInfoW failed (Win32 5): grantWrite`；worker 检测后自动升级为 **danger-full-access + 新 session** 重试，`dsh_result.sandbox_fallback` / `effective_permission_mode` 记录实际模式（真实受限仓库验证：succeeded、output=ok、30s）；可用 `DSH_MCP_ACL_FALLBACK=read-only` 或 `off` 收紧 |
+| 委派粒度策略（v0.6.4） | ✅ 规则改为「一个 dsh_run = 一个可验收工作单元（实现+自测+证据），禁止微任务」；长轮询上限 25s→可配 120s（`DSH_MCP_STATUS_WAIT_MAX_S`），减少 leader 往返；规则已写入 `~/AGENTS.md`、`~/.codex/AGENTS.md`、worker instructions 与 [docs/delegation-playbook.md](docs/delegation-playbook.md) |
+| 执行记录分析（v0.6.5） | ✅ 分析 11-02~11-09 的 64 个任务/200 条审计：修复「长任务被空闲回收误杀」（11 分钟任务、13.3M token 沉没）与「read-only 任务被 ACL 文本误判 failed」；新增 `dsh_status` 实时 `tokens/steps/tool_calls`、`dsh_result.partial_output/failure_kind`、token 预算护栏 `DSH_MCP_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 可调 + 瞬态失败自动重试 + 失败诊断 + `dsh_run(wait_s)` 单调用等待 + MCP 调用/字节指标 + 任务完成 webhook/命令通知 |
+| 目标测量（v0.6） | ✅ worker 侧 DSH token 计量（`dsh_result.usage.tokens` / `dsh_metrics.tokens`）+ A/B 对照工具 + leader 用量扫描器；真实首测：加速 **2.29x**、leader token 省 **46.0%**、cost 省 **31.1%**、达成率 2/2 |
+| cwd 安全校验 | ✅ 传用户主目录会被拒绝（Windows ACL 沙箱限制） |
+| Claude Code 接入 | ✅ 已注册（user scope）并实测连通：`claude mcp get dsh` → `√ Connected`；`claude -p` 真实调用 `dsh_describe` 成功 |
+| Codex 接入 | ✅ 已写入 `~/.codex/config.toml`，`codex mcp get dsh` 解析正常（工具白名单/超时/审批模式生效；未做真实调用） |
+| ChatGPT 桌面 app | ⚠️ 未实测（调研显示它与 Codex 共享 `~/.codex/config.toml`，配法同 Codex） |
+| 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 删掉对应块）。
+## 架构
+```
+leader（Claude Code / Codex / ChatGPT / Claude Desktop）
+   │  MCP over stdio（本地）或 Streamable HTTP /mcp + Bearer（远程）
+   ▼
+dsh-mcp-worker（本进程）
+   │  dsh_run 立即返回 task_id；任务后台执行
+   │  任务落盘：meta.json / events.jsonl / result.txt
+   ▼  后端可切换（DSH_MCP_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）
+```
+## 快速开始
+```powershell
+cd C:\path\to\dsh-mcp-worker
+pnpm install
+pnpm build
+pnpm test          # 127 个单测
+pnpm smoke         # 真实 DSH 集成烟测（约 30–60s）
+```
+worker 通过 **stdio** 工作，自身不监听任何端口。需要它时由 leader 拉起子进程。
+## 部署（源码与运行分离）
+源码仓库只用于开发（`pnpm build` / `pnpm test`）；**MCP 客户端只加载运行目录**，不要指向仓库内的 `dist`。
+```powershell
+# 在源码仓库里构建并部署到运行目录（示例：D:\dsh-mcp-worker）
+pnpm build
+pwsh -File scripts/deploy.ps1 -Target D:\dsh-mcp-worker
+```
+- MCP 入口应为运行目录：`D:\dsh-mcp-worker\dist\index.js`；
+- 运行目录包含 `dist/` + 生产依赖（`pnpm install --prod`）+ package 元数据，不含测试/开发依赖；
+- 更新流程：`git pull` → `pnpm install` → `pnpm test` → `scripts/deploy.ps1` → 重启 leader 会话；
+- 默认运行目录可用 `DSH_MCP_WORKER_HOME` 指定，也可直接 `pnpm deploy`（等价于执行该脚本）。
+## 通过 npm 使用
+包名：`dsh-mcp-worker`（只发布构建产物；本机仍需安装 DSH）。
+```powershell
+npm i -g dsh-mcp-worker      # 或直接用 npx
+npx -y dsh-mcp-worker        # 由 MCP 客户端拉起（stdio）
+```
+MCP 客户端配置可用：
+```json
+{
+  "mcpServers": {
+    "dsh": { "command": "npx", "args": ["-y", "dsh-mcp-worker"] }
+  }
+}
+```
+注意：npm 包**不包含 DSH 本体**；worker 通过 `dsh`（PATH）、`DSH_MCP_DSH_DIR` 或 `DSH_MCP_DSH_CLI` 找到本机 DSH。
+## 接入 leader
+### 1) Claude Code（最省事）
+```powershell
+claude mcp add --scope user --transport stdio dsh -- node "C:\path\to\dsh-mcp-worker\dist\index.js"
+claude mcp list
+claude mcp get dsh
+```
+带环境变量时注意 `--env` 的位置（放在 server 名之前）：
+```powershell
+claude mcp add --scope user --transport stdio --env DSH_MCP_DEFAULT_CWD="D:\work\repo" dsh -- node "C:\path\to\dsh-mcp-worker\dist\index.js"
+```
+等价 `.mcp.json` 见 [examples/claude-mcp.json](examples/claude-mcp.json)。
+**避免每次弹授权**：把 dsh 工具加入用户级 allowlist（`~/.claude/settings.json` 的 `permissions.allow`）：
+```json
+["mcp__dsh__dsh_run", "mcp__dsh__dsh_status", "mcp__dsh__dsh_result", "mcp__dsh__dsh_cancel", "mcp__dsh__dsh_describe",
+ "mcp__dsh__dsh_tasks", "mcp__dsh__dsh_audit", "mcp__dsh__dsh_read_result", "mcp__dsh__dsh_batch_run",
+ "mcp__dsh__dsh_batch_status", "mcp__dsh__dsh_batch_result", "mcp__dsh__dsh_search", "mcp__dsh__dsh_metrics"]
+```
+> 本机已写入（备份 `settings.json.bak-dsh-allow-20261102`）。安全边界仍由 worker 的 `permission_mode` / 审批桥承担。
+### 2) Codex CLI / IDE
+把下面加到 `~/.codex/config.toml`（完整示例见 [examples/codex-config.toml](examples/codex-config.toml)）：
+```toml
+[mcp_servers.dsh]
+command = "node"
+args = ["C:\\path\\to\\dsh-mcp-worker\\dist\\index.js"]
+startup_timeout_sec = 30          # 默认 10；worker 自身启动很快，留余量
+tool_timeout_sec = 300            # 默认 60；allow dsh_status 长轮询（wait_s≤120s）
+enabled_tools = ["dsh_run", "dsh_status", "dsh_result", "dsh_cancel", "dsh_describe", "dsh_tasks", "dsh_audit", "dsh_read_result", "dsh_batch_run", "dsh_batch_status", "dsh_batch_result", "dsh_search", "dsh_metrics"]
+# approve = 不再询问（auto 仍会按风险询问）；安全边界由 worker 的 permission_mode（默认 workspace-write）兜底
+default_tools_approval_mode = "approve"
+# 桌面端对 MCP 工具的审批可被 per-tool 覆盖（13 个工具都要写）
+[mcp_servers.dsh.tools.dsh_run]
+approval_mode = "approve"
+# ……其余工具同理：dsh_status / dsh_result / dsh_cancel / dsh_describe / dsh_tasks / dsh_audit /
+# dsh_read_result / dsh_batch_run / dsh_batch_status / dsh_batch_result / dsh_search / dsh_metrics
+[mcp_servers.dsh.env]
+DSH_MCP_DEFAULT_CWD = "C:\\path\\to\\your\\project"
+```
+校验：`codex mcp get dsh`（本机已配置为 `default_tools_approval_mode: approve` + 13 个 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）：
+  ```bash
+  tunnel-client init --sample sample_mcp_stdio_local --profile dsh-local \
+    --tunnel-id tunnel_xxxxxxxx --mcp-command "node C:\\path\\to\\dsh-mcp-worker\\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](examples/mcpb-manifest.json)。需要把 `dist/` 与 `node_modules` 一起打包进 MCPB 扩展，用 `mcpb pack` 生成 `.mcpb` 后拖入 Claude Desktop（**未实测**）。
+## 工具面
+| 工具 | 作用 | 关键参数 |
+|---|---|---|
+| `dsh_run` | 提交任务，**立即**返回 `task_id` | `task`（必填）、`cwd`（必填，项目目录）、`session_id?`、`permission_mode?`、`timeout_s?` |
+| `dsh_status` | 查状态 + 增量事件，支持长轮询 | `task_id`、`cursor?`、`wait_s?`（0–25） |
+| `dsh_result` | 取最终结果（输出过大自动落盘） | `task_id` |
+| `dsh_cancel` | 取消任务（杀进程树） | `task_id` |
+| `dsh_tasks` | 列出最近任务摘要（回顾/继续轮询） | `limit?`（1–100）、`status?` |
+| `dsh_audit` | 读取审计事件（任务生命周期/审批决定） | `limit?`（1–200） |
+| `dsh_read_result` | 分页读取落盘的完整结果或事件日志 | `task_id`、`source?`（result/events）、`offset?`、`max_chars?` |
+| `dsh_batch_run` | 批量并行派发（每项可带 cwd/session/权限） | `tasks[]`（1–`maxBatchTasks`） |
+| `dsh_batch_status` | 批量聚合状态（整体状态 + 子任务 + 计数） | `batch_id`、`wait_s?` |
+| `dsh_batch_result` | 批量聚合结果（输出/错误/耗时） | `batch_id`、`max_output_chars?` |
+| `dsh_search` | 在历史任务的输出与工具结果里检索 | `query`、`limit?` |
+| `dsh_metrics` | 计数/耗时分位/排队/后端/OTel 状态 | — |
+| `dsh_describe` | 返回入口/默认值/限制，供 leader 自适应 | — |
+典型调用序列（leader 视角）：
+```jsonc
+// 1) 提交
+{ "name": "dsh_run", "arguments": { "task": "修复 utils.ts 的空指针，并跑 pnpm test 验证", "cwd": "D:\\work\\repo" } }
+// → { task_id, status: "queued", session_id, cwd, hint }
+// 2) 轮询（每次最多等 25s；运行中会收到 notifications/progress）
+{ "name": "dsh_status", "arguments": { "task_id": "...", "cursor": 0, "wait_s": 20 } }
+// 3) 结束后取结果
+{ "name": "dsh_result", "arguments": { "task_id": "..." } }
+```
+状态机：
+```
+queued ──▶ running ──▶ succeeded
+   │           ├──▶ failed（超时/DSH 报错）
+   │           ├──▶ cancelled
+   └──▶ 不会出现：被取消的排队任务会直接 cancelled
+```
+多轮续聊：把首次 `dsh_run` 返回的 `session_id` 传给下一次 `dsh_run`；**同一 session 的任务串行执行**（DSH 侧单写者），不同 session 并行（受 `DSH_MCP_MAX_CONCURRENT` 限制）。
+## 让 leader 主动委派（可选，推荐）
+MCP 只把工具摆给 leader，**是否调用由 leader 模型自己决定**，协议层无法强制。想提高“自动委派”概率，三档手段（从弱到强）：
+1. **工具描述/instructions**（已内置）：`dsh_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 跑」。
+### 粒度怎么定（关键）
+- 一个 `dsh_run` 覆盖「定位 → 实现 → 自测 → 证据」，典型：一个功能点 / 一个 bug / 一个测试修复批次 / 一次跨文件重构；
+- 少于 3 次工具调用或 2 分钟内能做完的事，leader 自己做；不要拆成多个 dsh 任务；
+- 只有独立可并行（用 `dsh_batch_run`）、需要决策、风险隔离时才拆分；
+- 轮询用 `dsh_status(wait_s=60~120)`，不要在 DSH 执行期间重复劳动；
+- 详细模板、反例/正例、验收动作、如何用 `scripts/leader-usage.mjs` 验证：[docs/delegation-playbook.md](docs/delegation-playbook.md)。
+## 目标达成率测量（leader 提速 / 省 token）
+目标前提：Codex/ChatGPT、Claude Code 作为 leader，通过本 worker 把重活交给 DSH。核对方式：**同任务 A/B 对照**（leader 自己做 vs 委派 DSH）。
+```powershell
+# 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](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 无本地计量（见文档局限）。
+## 配置（环境变量）
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `DSH_MCP_TRANSPORT` | `stdio` | MCP 传输：`stdio`（本地 leader）/ `http`（Streamable HTTP，远程 leader） |
+| `DSH_MCP_HTTP_HOST` | `127.0.0.1` | HTTP 监听地址；`0.0.0.0` 时必须设 token |
+| `DSH_MCP_HTTP_PORT` | `7391` | HTTP 端口（`0` = 随机） |
+| `DSH_MCP_HTTP_TOKEN` | 无 | HTTP Bearer token；非回环地址必填 |
+| `DSH_MCP_DSH_CLI` | 自动探测 | `@deepseek-ai/dsh/lib/bin.js` 的绝对路径（用 `node` 启动，最稳） |
+| `DSH_MCP_DSH_COMMAND` | — | 完整命令（如 `dsh`），通过 shell 启动；优先级低于 `DSH_MCP_DSH_CLI` |
+| `DSH_MCP_DSH_DIR` | — | DSH 安装目录（自动拼 `node_modules/@deepseek-ai/dsh/lib/bin.js`） |
+| `DSH_MCP_PROFILE` | `headless` | `headless` 后端使用的 profile |
+| `DSH_MCP_BACKEND` | `sdk` | 执行后端：`sdk`（长驻，默认）/ `headless`（每任务一进程） |
+| `DSH_MCP_SDK_PROFILE` | `sdk` | 长驻后端使用的 DSH profile |
+| `DSH_MCP_SDK_PROVIDER` | `deepseek-official` | SDK 后端 provider |
+| `DSH_MCP_SDK_MODEL` | `deepseek-flash` | SDK 后端 model（进程级固定） |
+| `DSH_MCP_SDK_REASONING_EFFORT` | 无 | 推理强度（可选，如 `max`） |
+| `DSH_MCP_SDK_MAX_TOKENS` | 无 | 单次输出 token 上限（可选） |
+| `DSH_MCP_SDK_IDLE_MIN` | `10` | 后端空闲多少分钟回收（1–240） |
+| `DSH_MCP_SDK_INIT_TIMEOUT_S` | `300` | 后端 initialize 超时（秒）；失败自动重试 1 次，仍失败则自动降级 headless |
+| `DSH_MCP_DEFAULT_CWD` | 无 | 省略 `cwd` 时使用；没设则用 worker 进程 cwd（stdio 启动时通常是 leader 的项目目录） |
+| `DSH_MCP_ALLOWED_CWDS` | 无 | 分号分隔的允许目录白名单（设置后只能在这些目录下跑） |
+| `DSH_MCP_PERMISSION_MODE` | `auto` | 默认 `auto`（worker 按 cwd 能力自动适配）；也可显式 `read-only` / `workspace-write` / `danger-full-access` |
+| `DSH_MCP_TIMEOUT_S` | `900` | 单任务默认超时（秒） |
+| `DSH_MCP_MAX_CONCURRENT` | `2` | 全局并发任务上限（1–8，另受同 session 串行约束） |
+| `DSH_MCP_MAX_CONCURRENT_PER_CWD` | `1` | 同一 cwd 的并发上限（防止单项目占满） |
+| `DSH_MCP_TASK_TTL_MIN` | `1440` | 已结束任务保留分钟数，超时自动清理 |
+| `DSH_MCP_TASK_MAX` | `500` | 任务数上限；超额先淘汰最老的已结束任务 |
+| `DSH_MCP_CLEANUP_INTERVAL_MIN` | `10` | 自动清理间隔（分钟） |
+| `DSH_MCP_AUDIT_DIR` | `$DSH_HOME/mcp-audit` | 审计日志目录（`audit.jsonl`） |
+| `DSH_MCP_BATCH_DIR` | `$DSH_HOME/mcp-batches` | 批量任务元数据目录 |
+| `DSH_MCP_BATCH_MAX` | `8` | 单次批量提交的最大任务数（1–32） |
+| `DSH_MCP_OTEL_ENDPOINT` | 无 | OTLP/HTTP traces 端点（如 `http://127.0.0.1:4318/v1/traces`）；空 = 关闭 |
+| `DSH_MCP_OTEL_SERVICE` | `dsh-mcp-worker` | OTel `service.name` |
+| `DSH_MCP_DSH_PATCH` | `apply` | DSH 兼容补丁：`apply`（启动时自动检测+修复①pwsh 编码前缀 ②输出 GBK 兜底解码）/ `notify` / `off` |
+| `DSH_MCP_ACL_FALLBACK` | `danger-full-access` | workspace-write 沙箱 ACL 授权失败时的自动升级策略：`danger-full-access`（默认，B 方案：升级为全权重试）/ `read-only`（只读重试）/ `off`（直接失败并给修法）。注意 full access 无沙箱 |
+| `DSH_MCP_STATUS_WAIT_MAX_S` | `120` | `dsh_status` 单次长轮询等待上限（秒，5–600）；调大可减少 leader 轮询次数 |
+| `DSH_MCP_MAX_TASK_TOKENS` | `0` | **暂缓启用**：单任务 DSH token 预算，默认 `0`=不限制、不产生任何行为。实现已完成但按当前决定不开启；待积累 ≥20 条成功任务后，再按任务类型 p90×1.5 校准并启用（`totalTokens` 94–98% 是 cacheRead，若控成本需另按 input+output 折算） |
+| `DSH_MCP_CAPABILITY_CACHE` | `1` | cwd 能力缓存（落盘，auto 模式据此选权限模式），跨 worker 进程 |
+| `DSH_MCP_CAPABILITY_TTL_H` | `24` | cwd 能力缓存 TTL（小时） |
+| `DSH_MCP_RETRY_TRANSIENT` | `1` | 后端崩溃/初始化失败时自动重试一次 |
+| `DSH_MCP_AUTO_WORKTREE` | `1` | ACL 受限仓库自动创建可写 worktree（仅干净 git 仓库） |
+| `DSH_MCP_WORKTREE_ROOT` | `~/dsh-worktrees` | 自动 worktree 根目录 |
+| `DSH_MCP_NOTIFY_WEBHOOK` | 无 | 任务结束 POST 通知（JSON） |
+| `DSH_MCP_NOTIFY_CMD` | 无 | 任务结束执行命令（`DSH_MCP_NOTIFY_JSON` 环境变量传事件） |
+| `DSH_MCP_MAX_RESULT_CHARS` | `40000` | 结果超长时落盘阈值 |
+| `DSH_MCP_MAX_STATUS_EVENTS` | `100` | 单次 `dsh_status` 最多返回多少条事件 |
+| `DSH_MCP_TASKS_DIR` | `$DSH_HOME/mcp-tasks` | 任务落盘根目录 |
+| `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、退出码、错误
+  events.jsonl   DSH --json 事件流（追加写）
+  result.txt     输出超长时的完整结果
+```
+审计日志（append-only，独立于任务目录）：`$DSH_HOME/mcp-audit/audit.jsonl`，记录 `task_created` / `task_started` / `task_succeeded|failed|cancelled` / `approval_*`；可用 `dsh_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 工具不可用），可加 `DSH_MCP_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 协议**：`dsh_cancel` 等价于杀掉该 cwd 的后端进程，下次任务自动重建（已实测）；同一 cwd + 权限模式共享一个后端。
+3. **sdk 后端模型/权限是进程级**：模型由 `DSH_MCP_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. **任务会被自动清理**：超过 `DSH_MCP_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)`。worker 默认按 **B 方案**：检测到该失败后自动升级 `danger-full-access` 重试（结果里 `sandbox_fallback` + `effective_permission_mode` 显式记录，不掩盖）；可用 `DSH_MCP_ACL_FALLBACK=read-only|off` 收紧。
+13. **自动升级的 full access 无沙箱**：任务在 `danger-full-access` 下可读写当前用户能访问的任意路径；这是为「调用简单」有意选择的 B 方案，请配合 `DSH_MCP_ALLOWED_CWDS` 限定目录、审计日志与 git 回滚使用；高敏感仓库建议用 `read-only` 或 `off`。
+10. **审计日志无轮转**：`audit.jsonl` 持续追加，长期使用需自行归档/切割。
+11. **ChatGPT 直连未打通**：需要 Secure MCP Tunnel（无配额未实测）或自建 HTTPS + OAuth 2.1（OAuth 未实现）；本地 HTTP + Bearer 给不了 ChatGPT。
+12. **审批桥 v0 是粗粒度**：只做「检测审批阻断 → elicitation 询问 → 整任务以 danger-full-access 重试」，且真实 DSH 审批场景尚未端到端实测。
+13. **批量/检索的边界**：批量元数据（`batch_id → task_ids`）落盘可跨重启，但子任务本身仍受 TTL 清理；`dsh_search` 只扫内存中保留的任务（被清理的历史任务搜不到）。
+14. **OTel 是轻量实现**：不引 OTel SDK，只把**每个任务的 span** 以 OTLP/HTTP JSON 推送（best-effort，3s 超时）；指标是 `dsh_metrics` 拉取式快照，未做 OTLP metrics 推送。
+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 升级后下次启动自动重打。可用 `DSH_MCP_DSH_PATCH=notify|off` 关闭自动修复，手动脚本见 `scripts/patch-dsh-pwsh-encoding.ps1` 与 `scripts/patch-dsh-output-decoding.ps1`。
+16. ChatGPT web / Claude Desktop 两条远程/打包路径尚未实测。
+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）。同一后端存活时则正常续聊、不触发恢复。
+18. **长任务空闲回收（v0.6.5 已修）**：此前 `sweep()` 只看 `lastUsedAt`，运行超过 10 分钟的任务会被回收杀掉（真实 11 分钟任务、13.3M token 沉没）；现在有 in-flight prompt 的后端不会被回收，任务结束刷新时间。
+19. **read-only 的 ACL 误判（v0.6.5 已修）**：此前只要事件/最终文本里出现 `SetNamedSecurityInfoW` 就会被当作写沙箱失败，导致已产出完整报告的只读任务被标 failed；现在仅「非 read-only 模式 + tool_result.isError」才判定。
+20. **token 预算默认关闭**：`DSH_MCP_MAX_TASK_TOKENS=0`；建议真实使用设 3M–8M，防止单个失控任务烧掉大量额度。超限任务会被取消并标 failed（不是用户取消），事件流有 `token_budget_exceeded`。
+21. **自动 worktree 只对干净 git 仓库生效**：有未提交改动/非 git 仓库会退回原目录的降级模式；worktree 创建后保留供 leader 审查，需自行清理。
+22. **完成通知是外部通道**：MCP 协议无法主动唤醒空闲 leader；`DSH_MCP_NOTIFY_WEBHOOK`/`NOTIFY_CMD` 用于 webhook/桌面通知，未配置时不发通知。
+## 排错
+| 现象 | 处理 |
+|---|---|
+| leader 里工具列表没有 dsh_* | 检查命令路径、`node` 版本（需 ≥20）；Claude Code 用 `claude mcp get dsh` 看状态与日志 |
+| `DSH worker 错误 [invalid_cwd]` | 传具体项目目录；不要用 `C:\Users\<user>` 这类主目录 |
+| `DSH worker 错误 [task_not_finished]` | 任务还没结束：先 `dsh_status` 轮询到终态，再 `dsh_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` 可见；不想用全权则设 `DSH_MCP_ACL_FALLBACK=read-only` 或 `off` |
+| 续聊报 `session "..." already exists` | 正常降级路径：worker 自动换新 session id + 带上本地「续聊上下文」重试（事件 `session_resume_fallback`），无需手动处理；若任务需要严格原会话历史，请在同一 worker 进程/后端存活期内续聊 |
+| 找不到 DSH 入口 | 设 `DSH_MCP_DSH_CLI=D:\dsh-harness\node_modules\@deepseek-ai\dsh\lib\bin.js` |
+| 想看真实参数/限制 | 调 `dsh_describe` |
+## 开发
+```
+src/
+  index.ts         stdio 入口（生产环境装配）
+  server.ts        MCP 工具注册（13 个工具 + instructions）
+  task-manager.ts  异步任务：排队/并发/session 串行/每 cwd 配额/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      审批阻断检测（供 dsh_result 的审批桥使用）
+  audit.ts         append-only 审计日志（JSONL）
+  artifacts.ts     任务产物的安全分页读取（dsh_read_result）
+  batch-manager.ts 批量任务（fan-out）：创建、聚合状态/结果、取消
+  search.ts        历史任务内容检索（输出 + 工具结果）
+  otel.ts          轻量 OTLP/HTTP span 导出（无 SDK 依赖）
+  usage.ts         DSH token 用量提取/累加（headless step_end 与 sdk assistant/message）
+  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/              127 个单测 + 真实 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
+docs/              measurement.md（目标口径/公式/A/B 协议/局限）、delegation-playbook.md（委派粒度与任务模板）
+```
+```powershell
+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 进程超时与取消、任务管理器（并发/每 cwd 配额/session 串行/长轮询/恢复/取消/TTL 清理/数量上限/审计）、JSON-RPC 客户端、SDK 长驻后端与池、HTTP 传输（鉴权/healthz）、审批桥、新增只读工具、DSH token 用量提取与累加、DSH 兼容补丁（编码前缀 + GBK 兜底解码；apply/notify/off/幂等/版本漂移）。
+## 发布到 npm（维护者）
+采用 **npm Trusted Publishing（OIDC 绑定 GitHub Actions）**，CI 发布不需要 `NPM_TOKEN`。
+1. **首次发布必须手动**（npm 上还不存在该包时无法配置 Trusted Publisher）：
+   ```powershell
+   npm login          # 浏览器/2FA
+   pnpm build
+   npm publish --access public
+   ```
+2. 在 npm 包页面 → Settings → Trusted Publishing → GitHub Actions：
+   - Organization/user：`tongsh6`
+   - Repository：`dsh-mcp-worker`
+   - Workflow filename：`publish.yml`
+   - 保存时按需输入 2FA。
+3. 之后发布只需打 tag：
+   ```powershell
+   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](LICENSE)）。
+## 路线图
+- **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](examples/remote-access.md)。
+- **M3 ✅ 已完成（2026-11-02）**：任务 TTL 清理 + 数量上限、每 cwd 并发配额、审计日志（`dsh_audit`）、`dsh_tasks`、`dsh_read_result`。
+- **M4 ✅ 已完成（2026-11-02）**：批量派发（fan-out）/ 历史任务检索 / 指标快照 / 轻量 OTel span 导出。
+- **M5 ✅ 已完成（2026-11-02）**：目标达成率测量——worker 侧 DSH token 计量、A/B 对照工具、leader 用量扫描器、口径文档。
+> 设计依据与市场调研见 `本机分析报告（未随仓库提供）`。

package/dist/config.js CHANGED Viewed

@@ -13,7 +13,7 @@ export function loadConfig(env = process.env) {
         .map((part) => resolve(part));
     return {
         name: 'dsh-mcp-worker',
-        version: '0.7.1',
+        version: '0.7.2',
         backend: env.DSH_MCP_BACKEND?.trim() === 'headless' ? 'headless' : 'sdk',
         transport: env.DSH_MCP_TRANSPORT?.trim() === 'http' ? 'http' : 'stdio',
         http: {

package/dist/dsh-patch.js CHANGED Viewed

@@ -22,19 +22,19 @@ const DECODE_FINAL_TARGET = 'text: Buffer.concat(this.chunks).toString("utf8"),'
 const DECODE_FINAL_REPLACEMENT = 'text: decodeStreamText(Buffer.concat(this.chunks)),';
 const DECODE_MARKER = 'function decodeStreamText(';
 const DECODE_BACKUP_SUFFIX = '.bak-dsh-mcp-decoding';
-const DECODE_HELPER = `
-/** DSH 兼容补丁：ConstrainedLanguage 下 pwsh 可能按系统代码页输出；UTF-8 严格解码失败时回退 GBK。 */
-function decodeStreamText(buffer) {
-\ttry {
-\t\treturn new TextDecoder("utf-8", { fatal: true }).decode(buffer);
-\t} catch {
-\t\ttry {
-\t\t\treturn new TextDecoder("gbk").decode(buffer);
-\t\t} catch {
-\t\t\treturn buffer.toString("utf8");
-\t\t}
-\t}
-}
+const DECODE_HELPER = `
+/** DSH 兼容补丁：ConstrainedLanguage 下 pwsh 可能按系统代码页输出；UTF-8 严格解码失败时回退 GBK。 */
+function decodeStreamText(buffer) {
+\ttry {
+\t\treturn new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+\t} catch {
+\t\ttry {
+\t\t\treturn new TextDecoder("gbk").decode(buffer);
+\t\t} catch {
+\t\t\treturn buffer.toString("utf8");
+\t\t}
+\t}
+}
 `;
 /** 从 DSH 入口 `.../@deepseek-ai/dsh/lib/bin.js` 推导 @deepseek-ai 作用域目录。 */
 export function resolveDshScopeDir(dsh) {

package/package.json CHANGED Viewed

@@ -1,57 +1,57 @@
-{
-  "name": "dsh-mcp-worker",
-  "version": "0.7.1",
-  "description": "把本机 DSH（DeepSeek Harness）暴露为 MCP worker，供 Claude Code / Codex / ChatGPT 等 leader 调用",
-  "type": "module",
-  "bin": {
-    "dsh-mcp-worker": "dist/index.js"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "smoke": "tsx test/mcp-smoke.ts",
-    "smoke:http": "tsx test/http-smoke.ts",
-    "start": "node dist/index.js",
-    "measure:ab": "node scripts/measure-goals.mjs ab",
-    "measure:leader": "node scripts/leader-usage.mjs",
-    "deploy": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/deploy.ps1"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "1.30.0",
-    "zod": "^3.25.76"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.0",
-    "tsx": "^4.19.2",
-    "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
-  },
-  "license": "MIT",
-  "author": "tongsh6",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/tongsh6/dsh-mcp-worker.git"
-  },
-  "homepage": "https://github.com/tongsh6/dsh-mcp-worker#readme",
-  "bugs": {
-    "url": "https://github.com/tongsh6/dsh-mcp-worker/issues"
-  },
-  "keywords": [
-    "mcp",
-    "mcp-server",
-    "dsh",
-    "deepseek",
-    "claude-code",
-    "codex",
-    "chatgpt",
-    "worker",
-    "delegation"
-  ],
-  "files": [
-    "dist"
-  ]
-}
+{
+  "name": "dsh-mcp-worker",
+  "version": "0.7.2",
+  "description": "把本机 DSH（DeepSeek Harness）暴露为 MCP worker，供 Claude Code / Codex / ChatGPT 等 leader 调用",
+  "type": "module",
+  "bin": {
+    "dsh-mcp-worker": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "smoke": "tsx test/mcp-smoke.ts",
+    "smoke:http": "tsx test/http-smoke.ts",
+    "start": "node dist/index.js",
+    "measure:ab": "node scripts/measure-goals.mjs ab",
+    "measure:leader": "node scripts/leader-usage.mjs",
+    "deploy": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/deploy.ps1"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "license": "MIT",
+  "author": "tongsh6",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tongsh6/dsh-mcp-worker.git"
+  },
+  "homepage": "https://github.com/tongsh6/dsh-mcp-worker#readme",
+  "bugs": {
+    "url": "https://github.com/tongsh6/dsh-mcp-worker/issues"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "dsh",
+    "deepseek",
+    "claude-code",
+    "codex",
+    "chatgpt",
+    "worker",
+    "delegation"
+  ],
+  "files": [
+    "dist"
+  ]
+}