dsh-any-agent 0.1.0 → 0.1.1

package/README.md

@@ -66,7 +66,7 @@ DSH (DeepSeek Harness) can do all of that — it has file/shell tools, skills, s
 |  |  |
 |---|---|
 | 🔄 **A dead process never kills a conversation** | The identity lives on disk. A crash, an idle reap, even restarting this whole server costs you nothing — the next call transparently resumes it, memory intact (verified across processes). |
-| 🗣️ **You are never stuck waiting** | Steer a conversation mid-flight — **interject** to stop and redirect (~18 ms to converge), or **queue** a remark for after the current turn. Interrupting never damages the conversation. |
+| 🗣️ **You are never stuck waiting** | Steer a conversation mid-flight — **interject** to stop and redirect (~100 ms to reach idle, measured over four cancelled turns), or **queue** a remark for after the current turn. Interrupting never damages the conversation. |
 | 📡 **Completion notification, not polling** | Long tasks return instantly with a `run_id`; when the turn ends, a **sentinel file** is written atomically so a background task in *your* host wakes you. No polling, no occupied turn. |
 | 🪟 **Many conversations at once** | `dsh_list(only_running)` shows what's live; `dsh_read` gives cursor-based incremental output. Cycle between them like windows. |
 | 🧠 **Reasoning hidden by default** | You get "thought for N chars / M seconds" statistics instead of context-burning prose — and it is never logged, never written to disk. |
@@ -91,7 +91,7 @@ DSH ships two programmable entry points. The `sdk` profile looks simpler, but it
 
 ## 📦 Requirements
 
-- **Node.js ≥ 20**
+- **Node.js ≥ 22.15** — the server uses `zstdDecompressSync` from `node:zlib` to read DSH session headers, and that API does not exist before 22.15
 - **DSH installed** (`@deepseek-ai/dsh`), with working credentials under `~/.dsh`
 - A DSH **profile named `dsh-mcp`** derived from the shipped `acp` template, containing **your own** provider/model config (this repo deliberately ships no provider config)
 
@@ -112,13 +112,31 @@ Then edit `~/.dsh/profiles/dsh-mcp/cordis.patch.yml` and declare your provider a
 
 ### 2. Register the server
 
-**From npm (recommended)**
+**From npm, one command (recommended)**
 
 ```bash
 npm install -g dsh-any-agent
+dsh-any-agent-setup            # detect the clients you have; writes nothing
+dsh-any-agent-setup --yes      # apply
 ```
 
-The `dsh-any-agent` executable is then on your `PATH` and every client below can just call it by name.
+`setup` finds the MCP clients on your machine — **Claude Code, Codex, Cursor, Windsurf, Zed** — and writes the entry into each one it finds, skipping the rest. It is safe by construction:
+
+- **dry-run by default**; `--yes` is required to write anything
+- every file is backed up to `<file>.bak-dsh-<timestamp>` first
+- JSON clients are parsed before and after writing, so a broken config never lands
+- Claude Code and Codex go through their own `mcp add` subcommands rather than a hand-edited file
+- **idempotent** — re-running only changes what differs
+
+```bash
+dsh-any-agent-setup --yes --only cursor,zed     # just these
+dsh-any-agent-setup --yes --permission read-only
+dsh-any-agent-setup --remove --yes               # take it back out
+```
+
+**From a local checkout**
+
+The `dsh-any-agent` executable is on your `PATH` after a global install, so every client below can call it by name. Otherwise point `command` at `node` and `args` at `<checkout>/server/bin/dsh-any-agent.mjs`.
 
 **From a local checkout**
 
@@ -166,7 +184,9 @@ For a local checkout, use `"command": "node"` and `"args": ["/absolute/path/to/s
 ### 3. Try it
 
 ```bash
-node test/smoke.mjs        # no LLM calls, verifies the whole plumbing
+dsh-any-agent --version      # prints the version, starts nothing
+dsh-any-agent --help         # flags, key env vars, docs link
+node test/smoke.mjs          # no LLM calls, verifies the whole plumbing
 ```
 
 ## 🧰 Tools
@@ -191,7 +211,7 @@ MCP tool calls **block**, so `dsh_send` **does not block by default** (`wait=fal
 
 ```text
 1. dsh_send(conversation_id, prompt, wait=false)
-     → { run_id: "run-abc123", background: true }        # returns in ~1 ms
+     → { run_id: "run-abc123", background: true }        # returns without waiting for the turn
 
 2. …keep working on something else (verified: another conversation ran a full turn meanwhile)…
 
@@ -321,8 +341,8 @@ Silent by default — **not one byte is written**.
 | `DSH_MCP_RUNS_DIR` | `<state file dir>/runs` | Root for async completion sentinels (`<this>/<conversation_id>/<run_id>.json`) |
 | `DSH_MCP_LOCKS_DIR` | `<state file dir>/locks` | Holder registrations for the write lock. ⚠️ **All instances must agree on this value**, or they cannot see each other's registrations and will misread each other as an unidentifiable holder (a GUI) and refuse to preempt |
 | `DSH_MCP_LOCK_STALE_MS` | `90000` | How long without a heartbeat before a holder counts as lost (and becomes auto-preemptible by `dsh_takeover`) |
-| `DSH_MCP_IDLE_TTL_MS` | `0` (never reap) | How long a conversation may sit idle before its DSH process is reaped. ★★ **`0` means never reap (the default)**: the server keeps holding the write lock, so **the GUI cannot take it** — opening the conversation there is read-only and still works. Cost: one resident DSH process per conversation (**measured ~120 MB**). Set a millisecond value (e.g. `300000`) to save memory and accept that the lock can be taken |
-| `DSH_MCP_MAX_LIVE` | `8` (≈1 GB) | ★ **How many conversation processes to keep alive at once** (`0` = unlimited). Going over the cap reaps the **least recently used** one (a running turn is never reaped) — "**bounded memory, locks kept where it matters**". Use `4` when memory is tight, `0` on a big machine. To free everything at once: `dsh_release(all=true)` |
+| `DSH_MCP_IDLE_TTL_MS` | `0` (never reap) | How long a conversation may sit idle before its DSH process is reaped. ★★ **`0` means never reap (the default)**: the server keeps holding the write lock, so **the GUI cannot take it** — opening the conversation there is read-only and still works. Cost: one resident DSH process per conversation (**measured 300 MB and 476 MB in two cold starts**). Set a millisecond value (e.g. `300000`) to save memory and accept that the lock can be taken |
+| `DSH_MCP_MAX_LIVE` | `8` (≈2.5–4 GB worst case; see note 8) | ★ **How many conversation processes to keep alive at once** (`0` = unlimited). Going over the cap reaps the **least recently used** one (a running turn is never reaped) — "**bounded memory, locks kept where it matters**". Use `4` when memory is tight, `0` on a big machine. To free everything at once: `dsh_release(all=true)` |
 | `DSH_MCP_LIST_PROBE_TTL_MS` | `10000` | Cache lifetime for `dsh_list`'s on-disk probe (the probe spawns a DSH process and takes ~1 s) |
 | `DSH_MCP_SENTINEL_TTL_MS` | `604800000` (7 days) | Startup pruning age for sentinels; `0` disables pruning |
 | `DSH_MCP_SENTINEL_INCLUDE_REASONING` | unset | `1` writes `result.thinking` into the sentinel (**breaks the never-on-disk guarantee**) |
@@ -371,6 +391,30 @@ The suite **cleans up after itself**: `run.mjs` always ends with `cleanup.mjs`,
 
 > Counts are the numbers each suite prints itself. `smoke`/`prune`/`guards`/`approval-details`/`boundary` run without LLM calls; the rest need a working provider.
 
+### 📏 Numbers in this README must be reproducible
+
+Every figure in this document is either **printed by a test** or **measured with a command you can re-run**. If you change a number, change it to a measurement — not to an estimate, and never to a plausible-looking value.
+
+This section exists because that rule was violated. An early draft claimed `dsh_send(wait=false)` returned "in ~1 ms" (measured: 81 ms), that interruption converged in "~18 ms" (no test ever produced that number — `integration.mjs` only asserts `waited_ms` is between 0 and 25 s; four manual samples gave 91/102/105/119 ms), and that a conversation costs "~120 MB" (measured: 295–476 MB) — the last one contradicting itself in a single sentence, quoting both "120 MB each" and "three = 428 MB".
+
+**Three tiers, and how to state each:**
+
+| Tier | What it means | How to write it |
+|---|---|---|
+| **Tested** | A suite asserts it | Give the number; the suite is the authority |
+| **Measured** | You ran a command | Give the number **and the method**, so a reader can reproduce it |
+| **Estimated** | Derived or bounded | Say so ("roughly", "worst case", "≈") and show the arithmetic |
+
+**Recording a measurement inline.** The memory figures model the pattern — they name the tool, the before/after, and both samples:
+
+```text
+measured 300-480 MB per conversation
+  (Get-Process node: WorkingSet64 summed before vs. after one active
+   conversation reached end_turn; two cold starts gave 476 MB and 295 MB)
+```
+
+**When yours disagrees, say so.** Figures depend on machine, DSH version and load. A measurement outside a documented range is worth an issue — the range is a claim, not decoration.
+
 ## 🔒 The write lock: one writer per conversation at a time
 
 DSH conversations carry a **cross-process write lock**: **it never expires while the holder lives, and no API can take it from a live holder** — so **whoever gets there first decides everything**. This server turns that into "**you can look, we can write**":
@@ -403,7 +447,7 @@ DSH conversations carry a **cross-process write lock**: **it never expires while
 5. **A conversation that dies before its first successful turn may never have materialized on disk** — resume then fails with a clear error. Safe after the first message.
 6. **No renaming** — DSH's title subsystem has no external rename API (`SessionTitleService.rename` requires a live in-process session). Titles are auto-generated from the first message.
 7. **`session/list` returns only `{sessionId, cwd}` and excludes already-open sessions** — titles are filled in by this server from DSH's projection cache.
-8. **"Never reap" costs memory (measured ~120 MB per conversation)** — that is what buys "the GUI can never take the write lock". Two ways to spend less: ① **`DSH_MCP_MAX_LIVE` (default 8** — over the cap, the least recently used process is reaped → bounded memory, locks still held where it matters); ② set `DSH_MCP_IDLE_TTL_MS` to a millisecond value (at the cost of the lock being takeable). To drop to zero right after a batch of work: **`dsh_release(all=true)`** ✓ (lossless, everything resumes on demand).
+8. **"Never reap" costs memory (measured 300–480 MB per conversation)** — that is what buys "the GUI can never take the write lock". Two fresh-start measurements of one active conversation gave 476 MB and 295 MB of added resident memory (the DSH child plus this server); expect the higher figures on a cold process. Two ways to spend less: ① **`DSH_MCP_MAX_LIVE` (default 8** — over the cap, the least recently used process is reaped → bounded memory, locks still held where it matters); ② set `DSH_MCP_IDLE_TTL_MS` to a millisecond value (at the cost of the lock being takeable). To drop to zero right after a batch of work: **`dsh_release(all=true)`** ✓ (lossless, everything resumes on demand).
 
 ## ❓ Why is the profile still called `dsh-mcp`?
 

package/README.zh.md

@@ -66,7 +66,7 @@ DSH（DeepSeek Harness）本身**全都能做** —— 它有文件/shell 工具
 |  |  |
 |---|---|
 | 🔄 **进程死了对话也不丢** | 对话身份在磁盘上。进程崩溃、被空闲回收、甚至整个服务重启，都不影响继续——下次调用自动 `resume`，记忆完整（跨进程实测）。 |
-| 🗣️ **不用傻等** | 回合跑偏了能**插话改口**（打断收敛 ~18ms），或**排队**等这轮跑完再说；打断后会话不损坏。 |
+| 🗣️ **不用傻等** | 回合跑偏了能**插话改口**（约 100ms 收敛到 idle，四次打断实测），或**排队**等这轮跑完再说；打断后会话不损坏。 |
 | 📡 **跑完自动通知** | 长任务 `wait=false` 立刻返回 `run_id`；回合结束时**原子写出哨兵文件**，用你宿主的后台任务等它即可。不轮询、不占轮次。 |
 | 🪟 **多会话并发** | `dsh_list(only_running)` 看谁在跑，`dsh_read` 游标式增量读——像切窗口一样轮流盯。 |
 | 🧠 **灰色思考默认隐藏** | 只给"想了 N 字 / M 秒"的统计，不烧上下文；**不写日志、不落盘**。 |
@@ -91,7 +91,7 @@ DSH 自带两个可编程入口。`sdk` profile 看着更简单，但它的 JSON
 
 ## 📦 前置要求
 
-- **Node.js ≥ 20**
+- **Node.js ≥ 22.15** —— 服务用 `node:zlib` 的 `zstdDecompressSync` 读 DSH 会话头，这个 API 在 22.15 之前不存在
 - **已安装 DSH**（`@deepseek-ai/dsh`），且 `~/.dsh` 下已有可用的 provider 与凭据（GUI 能正常聊天即可）
 
 > 本服务**不自带** provider 配置，也**从不**接收或保存 API 密钥。
@@ -127,13 +127,31 @@ dsh --profile dsh-mcp --from-default-profile acp
 
 ### 2. 注册 MCP 服务
 
-**从 npm 安装（推荐）**
+**从 npm 安装，一条命令（推荐）**
 
 ```bash
 npm install -g dsh-any-agent
+dsh-any-agent-setup            # 检测你装了哪些客户端，不写任何文件
+dsh-any-agent-setup --yes      # 真正写入
 ```
 
-装完 `dsh-any-agent` 命令就在 `PATH` 上，下面每种客户端都可以直接按名字调用。
+`setup` 会找出你机器上的 MCP 客户端 —— **Claude Code、Codex、Cursor、Windsurf、Zed** —— 逐个写进去，没装的跳过。它的安全性是结构性保证的：
+
+- **默认 dry-run**，必须加 `--yes` 才写
+- 每个文件写前备份成 `<file>.bak-dsh-<时间戳>`
+- JSON 类客户端写入前后各解析一次，坏配置绝不落盘
+- Claude Code / Codex 走它们自己的 `mcp add` 子命令，不手改文件
+- **幂等**，重复运行只改变有差异的部分
+
+```bash
+dsh-any-agent-setup --yes --only cursor,zed     # 只装这几个
+dsh-any-agent-setup --yes --permission read-only
+dsh-any-agent-setup --remove --yes               # 全部移除
+```
+
+**从本地目录安装**
+
+全局安装后 `dsh-any-agent` 命令就在 `PATH` 上，下面每种客户端都可以直接按名字调用。否则把 `command` 指向 `node`、`args` 指向 `<解压目录>/server/bin/dsh-any-agent.mjs`。
 
 **从本地目录安装**
 
@@ -181,7 +199,9 @@ tool_timeout_sec = 120.0
 ### 3. 自检
 
 ```bash
-node test/smoke.mjs        # 不调用 LLM，验证整条管道
+dsh-any-agent --version      # 打印版本，不启动任何东西
+dsh-any-agent --help         # 参数、关键环境变量、文档链接
+node test/smoke.mjs          # 不调用 LLM，验证整条管道
 ```
 
 ## 🧰 工具
@@ -206,7 +226,7 @@ MCP 工具调用是**阻塞**的，所以 `dsh_send` **默认就不阻塞**（`w
 
 ```text
 1. dsh_send(conversation_id, prompt, wait=false)
-     → { run_id: "run-abc123", background: true }        # 约 1ms 返回
+     → { run_id: "run-abc123", background: true }        # 不等回合跑完就返回
 
 2. …继续做你自己的事（实测：期间在另一个会话上跑完了一整个回合）…
 
@@ -337,8 +357,8 @@ node bin/dsh-any-agent-workspaces.mjs --purge-test-sessions   # 删测试会话
 | `DSH_MCP_RUNS_DIR` | `<状态文件同目录>/runs` | 异步完成哨兵的根目录（`<此目录>/<会话id>/<run_id>.json`） |
 | `DSH_MCP_LOCKS_DIR` | `<状态文件同目录>/locks` | 写锁"持有者登记"的目录。⚠️ **多个实例必须指向同一个值**，否则彼此看不见对方的持锁登记、会把对方误判成"无法识别的持有者（GUI）"而拒绝抢占 |
 | `DSH_MCP_LOCK_STALE_MS` | `90000` | 持锁登记多久没续心跳就算"持有者失联"（此时可被 `dsh_takeover` 自动抢占） |
-| `DSH_MCP_IDLE_TTL_MS` | `0`（永不回收） | 会话空闲多久回收其 DSH 进程。★★ **`0` = 永不回收（默认）**：本服务一直握着写锁，**GUI 抢不走**（你在 GUI 里点开是**只读**，照样能看 ✓）。代价：每会话常驻一个 DSH 进程（**实测约 120MB**）。设成毫秒数（如 `300000`）可省内存，但要接受"锁可能被 GUI 抢走" |
-| `DSH_MCP_MAX_LIVE` | `8`（≈1GB） | ★ **最多同时保活几个会话进程**（`0` = 不限）。超标时回收**最久没用过**的（**在跑的回合绝不回收**）—— "**内存有界，锁尽量在手**"。内存紧用 `4`，机器大可以 `0`。用完想立刻全放掉：`dsh_release(all=true)` |
+| `DSH_MCP_IDLE_TTL_MS` | `0`（永不回收） | 会话空闲多久回收其 DSH 进程。★★ **`0` = 永不回收（默认）**：本服务一直握着写锁，**GUI 抢不走**（你在 GUI 里点开是**只读**，照样能看 ✓）。代价：每会话常驻一个 DSH 进程（**两次冷启动实测 476MB / 295MB**）。设成毫秒数（如 `300000`）可省内存，但要接受"锁可能被 GUI 抢走" |
+| `DSH_MCP_MAX_LIVE` | `8`（最坏约 2.5–4GB，见第 8 条） | ★ **最多同时保活几个会话进程**（`0` = 不限）。超标时回收**最久没用过**的（**在跑的回合绝不回收**）—— "**内存有界，锁尽量在手**"。内存紧用 `4`，机器大可以 `0`。用完想立刻全放掉：`dsh_release(all=true)` |
 | `DSH_MCP_LIST_PROBE_TTL_MS` | `10000` | `dsh_list` 磁盘探测结果的缓存时长（探测要 spawn 一个 DSH 进程，实测约 1 秒） |
 | `DSH_MCP_SENTINEL_TTL_MS` | `604800000`（7 天） | 启动时清理超过此时长的哨兵；`0` 关闭清理 |
 | `DSH_MCP_SENTINEL_INCLUDE_REASONING` | 未设置 | `1` 会把 `result.thinking` 一并写进哨兵（**打破"思考不落盘"的保证**） |
@@ -387,6 +407,30 @@ node test/cleanup.mjs      # 单独跑收尾清理（只针对临时目录；--d
 
 > 数字取各套件自己打印的汇总。`smoke`/`prune`/`guards`/`approval-details`/`boundary` 不调用模型；其余需要可用的 provider。
 
+### 📏 本文档里的数字必须可复现
+
+这里的每一个数字，要么是**测试打印出来的**，要么是**你用一条命令就能重跑出来的**。要改数字，就改成实测值 —— 不是估算，更不是一个看起来合理的值。
+
+单列这一节，是因为这条规矩被违反过。早期版本的 README 声称 `dsh_send(wait=false)` "在 ~1ms 内返回"（实测 81ms）、打断收敛 "~18ms"（没有任何测试产出过这个数 —— `integration.mjs` 只断言 `waited_ms` 落在 0–25 秒之间；人工实测四次为 91/102/105/119ms）、每会话占用 "~120MB"（实测 295–476MB）—— 最后这个还在同一句话里自相矛盾，同时写着 "每个 120MB" 和 "3 个 = 428MB"。
+
+**三档，以及各自该怎么写：**
+
+| 档位 | 含义 | 写法 |
+|---|---|---|
+| **测试断言** | 有套件在断言它 | 直接给数字，套件就是权威 |
+| **实测** | 你跑过命令 | 给数字 **和测法**，让别人能复现 |
+| **估算** | 推导或上界 | 明确写出来（"约"、"最坏"、"≈"），并给出算法 |
+
+**把测法写在同一处。** 内存那两个数字就是范例 —— 它写清了工具、前后对比、以及两次采样：
+
+```text
+实测 300-480MB / 会话
+  （Get-Process node: 在单个活跃会话跑到 end_turn 前后分别求和 WorkingSet64；
+    两次冷启动分别得到 476MB 和 295MB）
+```
+
+**你的测量和文档不符，就说出来。** 数字依赖机器、DSH 版本和负载。实测落在文档区间之外，值得开个 issue —— 区间是一个主张，不是装饰。
+
 ## 🔒 写锁：一个会话同一时刻只有一个写者
 
 DSH 的会话有**跨进程写锁**：**持有者活着就永不过期，也没有 API 能从活的持有者手里夺走** —— 所以**谁先拿到就决定一切**。本服务把它做成"**你看得见，我们写得动**"：
@@ -420,7 +464,7 @@ DSH 的会话有**跨进程写锁**：**持有者活着就永不过期，也没
 5. **首次成功回合之前就死掉的会话可能尚未落盘** —— 此时 resume 会报清晰错误。发出第一条消息后就安全了。
 6. **不能改名** —— DSH 的标题子系统没有对外改名接口（`SessionTitleService.rename` 需要进程内的活会话）。标题一律由首条消息自动生成。
 7. **`session/list` 只返回 `{sessionId, cwd}`，且排除已打开的会话** —— 对话名由本服务从 DSH 投影缓存补全。
-8. **默认"永不回收"要花内存（实测约 120MB/会话）** —— 换来的是"GUI 抢不走写锁"。两种省内存办法：① **`DSH_MCP_MAX_LIVE`（默认 8**，超标就回收最久没用过的 → 内存有界 ✓ 锁仍尽量在手 ✓）；② 把 `DSH_MCP_IDLE_TTL_MS` 设成毫秒数（代价是锁可能被 GUI 拿走）。一批活干完想立刻归零：**`dsh_release(all=true)`** ✓（无损，之后照样 resume）。
+8. **默认"永不回收"要花内存（实测 300–480MB/会话）** —— 换来的是"GUI 抢不走写锁"。两次冷启动实测单个活跃会话新增常驻内存分别为 476MB 和 295MB（含 DSH 子进程与本服务），冷进程首次偏高。两种省内存办法：① **`DSH_MCP_MAX_LIVE`（默认 8**，超标就回收最久没用过的 → 内存有界 ✓ 锁仍尽量在手 ✓）；② 把 `DSH_MCP_IDLE_TTL_MS` 设成毫秒数（代价是锁可能被 GUI 拿走）。一批活干完想立刻归零：**`dsh_release(all=true)`** ✓（无损，之后照样 resume）。
 
 ## ❓ 为什么 profile 还叫 `dsh-mcp`？
 

package/USAGE-MIGRATION.md

@@ -36,8 +36,18 @@
 
 ### 1.1 确认 DSH 的位置
 
-本服务需要一个明确的 DSH 入口路径。**自动探测只找两处**：npx 缓存、npm 全局安装目录。
-如果你用的是 **DSH 桌面版（Electron）**，探测不到，必须手动指定：
+本服务需要一个 DSH 入口路径。**自动探测只找两处**：npx 缓存、npm 全局安装目录
+（`%APPDATA%\npm\node_modules`、`/usr/local/lib/node_modules`、`/usr/lib/node_modules`）。
+
+**实测结论**：用 `npx @deepseek-ai/dsh` 跑过 DSH 的机器，缓存里就有，**不设 `DSH_BIN` 也能自动找到**
+（已验证：不给 `DSH_BIN` 时握手和建会话都成功）。
+
+但两种情况探测不到，必须手动指定：
+
+- **DSH 桌面版（Electron）** —— 装在 `...\WindowsApps\...\app.asar\dsh\`，探测逻辑不查那里
+- **DSH 装在自定义路径**，或 npx 缓存被清理过
+
+手动找入口文件：
 
 ```powershell
 # 找一下你机器上 DSH 的入口文件
@@ -75,23 +85,73 @@ npm install -g dsh-any-agent
 
 ## 3. 接进你的 agent
 
+### 3.0 一条命令搞定（推荐）
+
+本服务自带一个 setup 命令，**自动检测你装了哪些客户端并写进配置**：
+
+```bash
+# 先看它会改什么（默认不写任何文件）
+dsh-any-agent setup
+
+# 确认后真正写入
+dsh-any-agent setup --yes
+
+# 只装某几个 / 换权限档
+dsh-any-agent setup --yes --only cursor,zed
+dsh-any-agent setup --yes --permission read-only
+
+# 反悔了，全部移除
+dsh-any-agent setup --remove --yes
+```
+
+支持的客户端：**Claude Code、Codex、Cursor、Windsurf、Zed**。没装的那些会被跳过，不算失败。
+
+它做的几件保证安全的事：
+
+- **默认 dry-run**，加 `--yes` 才写
+- 每个文件写前备份成 `<file>.bak-dsh-<时间戳>`
+- JSON 类客户端：写入前解析原文件、写后回读校验，坏文件绝不留在磁盘上
+- Claude Code / Codex 走它们自己的 `mcp add` 子命令，不手改数据库
+- **幂等**：重复运行只会更新变化的部分
+
+> 用 npm 全局安装时命令叫 `dsh-any-agent-setup`（或 `npx dsh-any-agent-setup`）。
+
+---
+
+### 3.1 手工配置（setup 不支持你的客户端时）
+
 所有客户端本质上是同一件事：**告诉它去哪里启动这个 stdio 服务**。
 下面按客户端给出现成配置块，直接复制。
 
 > 🔑 **通用要点**：如果 `dsh-any-agent` 不在 `PATH` 上（或你想用指定的 Node），
 > 把 `command` 换成 node 的绝对路径、`args` 换成 `<安装目录>/bin/dsh-any-agent.mjs`。
 
-### 3.1 Claude Code
+#### Claude Code
 
 ```bash
 # 全局安装的情况
 claude mcp add dsh-any-agent -- dsh-any-agent
 
-# 指定 DSH 入口（强烈建议显式给，避免探测失败）
-claude mcp add dsh-any-agent -e DSH_BIN=<DSH_BIN> -- dsh-any-agent
+# 指定 DSH 入口 + 环境变量（-e 必须紧跟服务名，写在 -- 之后会报
+# "missing required argument 'commandOrUrl'"）
+claude mcp add dsh-any-agent -e DSH_BIN=<DSH_BIN> -e DSH_MCP_PERMISSION=workspace-write -- dsh-any-agent
+
+# 加到用户级配置（默认是项目级）
+claude mcp add dsh-any-agent -s user -e DSH_BIN=<DSH_BIN> -- dsh-any-agent
+```
+
+验证：
+
+```powershell
+claude mcp list | Select-String dsh-any-agent
+# 期望: dsh-any-agent: dsh-any-agent - √ Connected
 ```
 
-### 3.2 Codex（`~/.codex/config.toml`）
+> ⚠️ **前提**：`dsh-any-agent` 必须在 `PATH` 上。如果你只是在仓库里 `npm install`（不加 `-g`），
+> 命令名不会存在，Claude Code 会报 `CONNECTION_CLOSED`。此时改用绝对路径：
+> `claude mcp add dsh-any-agent -e DSH_BIN=<DSH_BIN> -- node <安装目录>/bin/dsh-any-agent.mjs`
+
+#### Codex（`~/.codex/config.toml`）
 
 ```toml
 [mcp_servers.dsh-any-agent]
@@ -109,13 +169,13 @@ DSH_MCP_LOG = "silent"
 
 > 从迁移包安装的话，这段由 `install.cmd` 自动写入，不用手抄。
 
-### 3.3 Cursor / Windsurf / Cline / Continue / Zed（JSON 型通用）
+#### Cursor / Windsurf / Cline / Continue（`mcpServers` 型）
 
-大多数客户端用同一套 `mcpServers` 结构。文件位置各异，通常是：
+这些客户端用同一套 `mcpServers` 结构。配置文件位置：
 
-- Cursor：`~/.cursor/mcp.json` 或项目内 `.cursor/mcp.json`
-- Cline / Continue：客户端设置里的 MCP Servers 面板
-- Zed：`~/.config/zed/settings.json` 的 `context_servers`
+- **Cursor**：`%USERPROFILE%\.cursor\mcp.json`（全局）或项目内 `.cursor/mcp.json`
+- **Windsurf**：`%USERPROFILE%\.codeium\windsurf\mcp_config.json`
+- **Cline / Continue**：客户端设置里的 MCP Servers 面板
 
 ```json
 {
@@ -133,13 +193,36 @@ DSH_MCP_LOG = "silent"
 }
 ```
 
-### 3.4 其他任意 MCP 客户端
+#### Zed（`context_servers` 型，格式不同）
+
+Zed **不用** `mcpServers`。它的键叫 `context_servers`，且 `command` 是**字符串**而非对象：
+
+```json
+{
+  "context_servers": {
+    "dsh-any-agent": {
+      "command": "dsh-any-agent",
+      "args": [],
+      "env": {
+        "DSH_BIN": "<DSH_BIN>",
+        "DSH_MCP_PERMISSION": "workspace-write"
+      }
+    }
+  }
+}
+```
+
+文件位置：Windows 是 `%APPDATA%\Zed\settings.json`，macOS / Linux 是 `~/.config/zed/settings.json`。
+
+> Zed 的远程 MCP 服务器用 `{"url": "...", "headers": {...}}`，但本项目是本地 stdio 服务，用上面的 `command` 形式。
+
+#### 其他任意 MCP 客户端
 
 只要能启动 stdio MCP 服务就行。它只实现四个标准方法
 （`initialize` / `ping` / `tools/list` / `tools/call`），
 不依赖任何宿主专有扩展 —— 连协议版本协商到旧版、不发 `notifications/initialized` 的客户端都测过。
 
-### 3.5 装完先验证
+### 3.2 装完先验证
 
 重启客户端，然后确认它发现了服务。各客户端查看方式不同，Codex 是：
 

package/USAGE-NOTES.en.md

@@ -64,7 +64,7 @@ Practical gotchas and trade-offs you *will* hit when letting Claude / Codex driv
 
 **3.11 ★★ Opening it once hands the conversation to the GUI permanently (measured; harsher than 3.10).** Measured: you open the conversation in the web UI (the GUI takes the lock), then **switch away to another conversation**, then we probe again — **the lock is still held**. So `dsh web` does **not** release it when you navigate away: **once opened, that conversation belongs to the GUI for the entire lifetime of the web process**, and the MCP cannot touch it again until you **restart `dsh web`**. That is why it is "always": it is not taken on every peek, it is taken once and stays taken — so from then on every retry fails until the GUI restarts. Practical advice: (1) never open a conversation the MCP drives, not even once — seeing its title in the list is fine; (2) to read content, have the agent call `dsh_read` and paste the output to you; (3) if you already opened it, **restart `dsh web`** — switching away in the UI does nothing.
 
-**3.12 ★★ The lossless answer: keep the MCP holding the lock (`DSH_MCP_IDLE_TTL_MS=0`).** The full causal chain, all measured: a task finishes, the conversation sits idle for five minutes, **idle reaping kills the child and frees the write lock**, you happen to open that conversation in the web UI right then, **the GUI takes the lock and never returns it** (navigating away ✗, waiting ✗, **archiving ✗** — verified that the archive really landed), and from then on every MCP resume fails. That is "the caller can never get back in after a task". The fix: **`DSH_MCP_IDLE_TTL_MS=0` is now the default** (never reap), so the MCP keeps holding the write lock. Then opening it in the GUI **opens it read-only and you can still read it** (measured: the turns and answers are visible), and probing from a separate instance confirms **the holder is still this server's own PID with a fresh heartbeat** — the lock was never taken. **Neither side is harmed**: you keep visibility, while the MCP's turns keep running and later calls reconnect normally. Zero data loss, zero duplication, zero extra disk. The cost, measured: **~120 MB per live conversation** (three conversations = 428 MB, linear; ten ≈ 1.2 GB). It will not blow up, but it is real. Three ways to control it: ★ **on by default — `DSH_MCP_MAX_LIVE=8`**: over the cap, the **least recently used** process is reaped (a running turn is never reaped), giving "**bounded memory, locks kept where it matters**" ✓; **after a batch of work — `dsh_release(all=true)`** frees everything at once, dropping memory to zero ✓ and it is lossless (the logs are on disk, everything resumes on demand ✓); or set `DSH_MCP_IDLE_TTL_MS` to a millisecond value (at the cost of the lock being takeable ✗). In one line: reaping saves memory but hands the lock away; not reaping spends memory to buy "never silently locked out". Your data is never at risk either way: a GUI-pinned conversation is intact, and the MCP resumes it normally once `dsh web` restarts — what you lose is only immediate usability, not content.
+**3.12 ★★ The lossless answer: keep the MCP holding the lock (`DSH_MCP_IDLE_TTL_MS=0`).** The full causal chain, all measured: a task finishes, the conversation sits idle for five minutes, **idle reaping kills the child and frees the write lock**, you happen to open that conversation in the web UI right then, **the GUI takes the lock and never returns it** (navigating away ✗, waiting ✗, **archiving ✗** — verified that the archive really landed), and from then on every MCP resume fails. That is "the caller can never get back in after a task". The fix: **`DSH_MCP_IDLE_TTL_MS=0` is now the default** (never reap), so the MCP keeps holding the write lock. Then opening it in the GUI **opens it read-only and you can still read it** (measured: the turns and answers are visible), and probing from a separate instance confirms **the holder is still this server's own PID with a fresh heartbeat** — the lock was never taken. **Neither side is harmed**: you keep visibility, while the MCP's turns keep running and later calls reconnect normally. Zero data loss, zero duplication, zero extra disk. The cost, measured: **300–480 MB per live conversation** (two cold starts of a single active conversation added 476 MB and 295 MB; roughly linear, so ten conversations reach 3–5 GB). It will not blow up, but it is real. Three ways to control it: ★ **on by default — `DSH_MCP_MAX_LIVE=8`**: over the cap, the **least recently used** process is reaped (a running turn is never reaped), giving "**bounded memory, locks kept where it matters**" ✓; **after a batch of work — `dsh_release(all=true)`** frees everything at once, dropping memory to zero ✓ and it is lossless (the logs are on disk, everything resumes on demand ✓); or set `DSH_MCP_IDLE_TTL_MS` to a millisecond value (at the cost of the lock being takeable ✗). In one line: reaping saves memory but hands the lock away; not reaping spends memory to buy "never silently locked out". Your data is never at risk either way: a GUI-pinned conversation is intact, and the MCP resumes it normally once `dsh web` restarts — what you lose is only immediate usability, not content.
 
 ## 4. Permissions and safety
 
@@ -81,7 +81,7 @@ Practical gotchas and trade-offs you *will* hit when letting Claude / Codex driv
 | You want | Reality |
 |---|---|
 | Token-by-token streaming | ❌ Cannot enter model context (MCP limitation). Callers get per-step results; humans follow stderr logs |
-| Mid-turn steering | ❌ ACP rejects concurrent prompts. `dsh_interject` is the equivalent: cancel + immediately start a new turn (~18 ms to converge) |
+| Mid-turn steering | ❌ ACP rejects concurrent prompts. `dsh_interject` is the equivalent: cancel + immediately start a new turn (~100 ms to converge — the `waited_ms` field, four samples gave 91/102/105/119 ms, covering only `session/cancel` through reaching idle) |
 | Paste a screenshot | ❌ ACP advertises `promptCapabilities: {image: false}` |
 | Rename a conversation | ❌ DSH's title subsystem has no external rename API; titles come from the first message |
 | Have the agent ask you questions | ⚠️ `ask_user_question` isn't mounted in the sdk/acp profiles; it won't block waiting for you |

package/USAGE-NOTES.md

@@ -168,7 +168,7 @@
   - 用独立实例探测确认：**持有者仍是本服务的 PID、心跳新鲜** → **锁没有被抢走** ✓
   - **两边都不受影响**：你看得见进度，而 MCP 的任务照跑、之后照常接回 ✓
   - **零数据损失、零重复、零磁盘开销** ✓
-- **代价（实测内存）**：每个保活的会话约 **120MB**（3 个 = 428MB，**线性**；10 个 ≈ 1.2GB）✗ 不会"爆"，但确实要花。三种控制手段：
+- **代价（实测内存）**：每个保活的会话约 **300–480MB**（两次冷启动实测单个活跃会话新增 476MB / 295MB；**近似线性**，10 个可达 3–5GB）✗ 不会"爆"，但确实要花。三种控制手段：
   - ★ **默认就有：`DSH_MCP_MAX_LIVE=8`** —— 超过就回收**最久没用过**的那个（**在跑的回合绝不回收**）→ "**内存有界，锁尽量在手**" ✓ 窗口内的会话写锁照握、GUI 抢不走 ✓
   - **一批活干完**：`dsh_release(all=true)` 一次全放掉，内存立刻归零 ✓ **无损**（会话日志都在磁盘上，之后照常 resume ✓）
   - 或把 `DSH_MCP_IDLE_TTL_MS` 设成毫秒数（代价：锁可能被 GUI 拿走 ✗）
@@ -204,7 +204,7 @@
 | 你想要的 | 实际能做到的 |
 |---|---|
 | 逐字流式输出 | ❌ 进不了模型上下文（MCP 固有限制）。调用方拿到的是**分步**结果；人能通过 stderr 日志跟进 |
-| 中途插话让模型即时改向 | ❌ ACP 拒绝并发 prompt。`dsh_interject` 是等价物：**取消 + 立刻开新回合**，历史保留（实测打断收敛 ~18ms） |
+| 中途插话让模型即时改向 | ❌ ACP 拒绝并发 prompt。`dsh_interject` 是等价物：**取消 + 立刻开新回合**，历史保留（打断收敛约 100ms —— 即 `waited_ms` 字段，四次实测 91/102/105/119ms，只含 `session/cancel` 到 idle） |
 | 给 DSH 看截图 | ❌ ACP 自报 `promptCapabilities: {image: false}` |
 | 给会话改个名字 | ❌ DSH 标题子系统没有对外改名接口，标题一律按首条消息自动生成 |
 | 让 agent 主动问我问题 | ⚠️ `ask_user_question` 工具在 sdk/acp profile 里没挂载，它不会卡住等你 |

package/bin/dsh-any-agent.mjs

@@ -14,10 +14,45 @@
  *   DSH_MCP_LOG_STDERR          1 才转发 DSH 子树进程的原始 stderr（可能含思考内容）
  */
 
-import { createLogger } from '../src/config.mjs';
-import { Hub } from '../src/hub.mjs';
-import { createMcpServer } from '../src/mcp.mjs';
-import { listOrphans, pruneDeadMarkers } from '../src/locks.mjs';
+import { SERVER_VERSION } from '../src/mcp.mjs';
+
+/**
+ * `--version` / `--help` must be answered *before* the hub starts: the module
+ * graph above already pulls in config and locks, and starting the hub would
+ * spawn reapers and touch the registry just to print a version string.
+ */
+const argv = process.argv.slice(2);
+if (argv.includes('--version') || argv.includes('-v')) {
+  process.stdout.write(SERVER_VERSION + '\n');
+  process.exit(0);
+}
+if (argv.includes('--help') || argv.includes('-h')) {
+  process.stdout.write(
+    'dsh-any-agent ' + SERVER_VERSION + '\n\n' +
+    'An MCP server that drives DeepSeek Harness (DSH) as a long-lived coding agent.\n' +
+    'Runs as an MCP stdio server; normally launched by your MCP client, not by hand.\n\n' +
+    'Usage:\n' +
+    '  dsh-any-agent                 run the MCP server on stdio\n' +
+    '  dsh-any-agent --version       print the version and exit\n' +
+    '  dsh-any-agent --help          this text\n\n' +
+    'Register it with your client:\n' +
+    '  dsh-any-agent-setup           detect clients and preview (writes nothing)\n' +
+    '  dsh-any-agent-setup --yes     apply\n\n' +
+    'Key environment variables (all optional):\n' +
+    '  DSH_BIN                  path to @deepseek-ai/dsh/lib/bin.js; auto-detected\n' +
+    '  DSH_MCP_PROFILE          DSH profile to drive (default dsh-mcp)\n' +
+    '  DSH_MCP_PERMISSION       danger-full-access | workspace-write | read-only\n' +
+    '  DSH_MCP_APPROVAL         auto-allow | auto-deny | ask\n' +
+    '  DSH_MCP_LOG              silent (default) | info | debug\n\n' +
+    'Docs: https://github.com/xmtlzzz/dsh-any-agent\n',
+  );
+  process.exit(0);
+}
+
+const { createLogger } = await import('../src/config.mjs');
+const { Hub } = await import('../src/hub.mjs');
+const { createMcpServer } = await import('../src/mcp.mjs');
+const { listOrphans, pruneDeadMarkers } = await import('../src/locks.mjs');
 
 const log = createLogger();
 

package/bin/setup.mjs

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+/**
+ * dsh-any-agent setup -- wire this server into the MCP clients you already have.
+ *
+ *   dsh-any-agent setup                     detect and preview; writes nothing
+ *   dsh-any-agent setup --yes               actually write (backs up first)
+ *   dsh-any-agent setup --yes --only cursor,zed
+ *   dsh-any-agent setup --yes --permission read-only
+ *   dsh-any-agent setup --remove --yes      take it back out
+ *
+ * Constraints, each one learned the hard way:
+ *   1. Dry-run by default. Touching someone else's config deserves a preview.
+ *   2. Every file is backed up to <file>.bak-dsh-<stamp> before it is written.
+ *   3. JSON clients: parse the original, build the new object, parse the result
+ *      again, and only then write. A half-written config is worse than none.
+ *   4. A client that is not installed is skipped, not failed.
+ *   5. Claude Code and Codex have their own `mcp` subcommands; prefer them.
+ */
+
+import { existsSync, readFileSync, writeFileSync, copyFileSync, renameSync, unlinkSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const NAME = 'dsh-any-agent';
+
+/** Same source of truth as the server: package.json, not a hard-coded copy. */
+const VERSION = (() => {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8')).version ?? '0.0.0';
+  } catch { return '0.0.0'; }
+})();
+
+const argv = process.argv.slice(2);
+if (argv.includes('--version') || argv.includes('-v')) {
+  process.stdout.write(VERSION + '\n');
+  process.exit(0);
+}
+if (argv.includes('--help') || argv.includes('-h')) {
+  process.stdout.write(
+    'dsh-any-agent-setup ' + VERSION + '\n\n' +
+    'Detect installed MCP clients and register ' + NAME + ' with each.\n\n' +
+    'Usage:\n' +
+    '  dsh-any-agent-setup                     preview (writes nothing)\n' +
+    '  dsh-any-agent-setup --yes               apply\n' +
+    '  dsh-any-agent-setup --yes --only a,b    only these clients\n' +
+    '  dsh-any-agent-setup --yes --permission read-only\n' +
+    '  dsh-any-agent-setup --remove --yes      unregister\n\n' +
+    'Clients: Claude Code, Codex, Cursor, Windsurf, Zed.\n' +
+    'Every write is preceded by a .bak-dsh-<timestamp> backup; JSON clients are\n' +
+    'validated before and after writing; re-running is idempotent.\n',
+  );
+  process.exit(0);
+}
+
+const has = (f) => argv.includes(f);
+const val = (f, d) => {
+  const i = argv.indexOf(f);
+  return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : d;
+};
+
+const WRITE = has('--yes') || has('-y');
+const REMOVE = has('--remove');
+const ONLY = (val('--only', '') || '').split(',').map((s) => s.trim()).filter(Boolean);
+const PERMISSION = val('--permission', 'workspace-write');
+const STAMP = new Date().toISOString().replace(/[:.]/g, '-');
+
+const HOME = homedir();
+const IS_WIN = platform() === 'win32';
+const APPDATA = process.env.APPDATA || join(HOME, 'AppData', 'Roaming');
+
+const log = (s = '') => console.log(s);
+const tick = (s) => log('  OK   ' + s);
+const dash = (s) => log('  ---  ' + s);
+const bang = (s) => log('  FAIL ' + s);
+
+function which(cmd) {
+  const probe = spawnSync(IS_WIN ? 'where' : 'which', [cmd], { encoding: 'utf8', shell: IS_WIN });
+  return probe.status === 0;
+}
+
+function desiredEnv() {
+  const env = { DSH_MCP_PERMISSION: PERMISSION, DSH_MCP_LOG: 'silent' };
+  if (process.env.DSH_BIN) env.DSH_BIN = process.env.DSH_BIN;
+  return env;
+}
+
+/** Prefer this package's own entry point; fall back to the PATH command. */
+function launch() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const sibling = join(here, 'dsh-any-agent.mjs');
+  if (existsSync(sibling)) return { command: process.execPath, args: [sibling], style: 'node + sibling entry' };
+  return { command: NAME, args: [], style: 'PATH command' };
+}
+
+function backup(file) {
+  const dst = file + '.bak-dsh-' + STAMP;
+  copyFileSync(file, dst);
+  return dst;
+}
+
+/** Temp-then-rename so a crash cannot leave a truncated config. */
+function atomicWrite(file, text) {
+  const tmp = file + '.tmp-dsh-' + process.pid;
+  writeFileSync(tmp, text, 'utf8');
+  renameSync(tmp, file);
+}
+
+function parseJson(file) {
+  const raw = readFileSync(file, 'utf8');
+  try {
+    return { json: JSON.parse(raw), raw };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+const CLIENTS = [
+  {
+    id: 'claude',
+    label: 'Claude Code',
+    detect: () => which('claude') && existsSync(join(HOME, '.claude.json')),
+    apply() {
+      const run = (a) => spawnSync('claude', a, { encoding: 'utf8', shell: IS_WIN });
+      const tried = (r) => (((r.stdout || '') + (r.stderr || '')).toLowerCase());
+
+      // Dry-run must not shell out: `claude mcp add` writes immediately, so
+      // previewing by running it would be a write, not a preview.
+      if (!WRITE) {
+        const probe = run(['mcp', 'get', NAME]);
+        const registered = probe.status === 0;
+        if (REMOVE) {
+          return registered
+            ? { preview: 'would be unregistered via \`claude mcp remove\`' }
+            : { skipped: 'not registered' };
+        }
+        return { preview: registered
+          ? 'would be re-registered via \`claude mcp add\` (replacing the existing entry)'
+          : 'would be registered via \`claude mcp add\` (user scope)' };
+      }
+
+      if (REMOVE) {
+        const r = run(['mcp', 'remove', NAME, '-s', 'user']);
+        if (r.status !== 0) {
+          return tried(r).includes('no mcp server named')
+            ? { skipped: 'not registered' }
+            : { error: tried(r).trim().split('\n')[0] || 'claude exited ' + r.status };
+        }
+        return { done: 'removed via \`claude mcp remove\` (user scope)' };
+      }
+
+      // `add` refuses to overwrite, so clear any existing entry first. A
+      // missing entry is the normal path, not an error.
+      const existing = run(['mcp', 'remove', NAME, '-s', 'user']);
+      const hadIt = existing.status === 0;
+
+      const { command, args } = launch();
+      const envs = [];
+      for (const [k, v] of Object.entries(desiredEnv())) envs.push('-e', k + '=' + v);
+      const r = run(['mcp', 'add', NAME, '-s', 'user', ...envs, '--', command, ...args]);
+      if (r.status !== 0) {
+        return { error: tried(r).trim().split('\n')[0] || 'claude exited ' + r.status };
+      }
+      return { done: 'registered via \`claude mcp add\` (user scope)' + (hadIt ? ', replacing the old entry' : '') };
+    },
+  },
+  {
+    id: 'codex',
+    label: 'Codex',
+    detect: () => existsSync(join(HOME, '.codex', 'config.toml')),
+    apply() {
+      const cfg = join(HOME, '.codex', 'config.toml');
+      const raw = readFileSync(cfg, 'utf8');
+      const kept = [];
+      let skip = false;
+      const re = new RegExp('^mcp_servers\\.(?:' + NAME + '|"' + NAME + '")(?:\\.|$)');
+      for (const line of raw.split(/\r?\n/)) {
+        const m = line.match(/^\s*\[([^\]]+)\]\s*(?:#.*)?$/);
+        if (m) skip = re.test(m[1]);
+        if (!skip) kept.push(line);
+      }
+      let out = kept.join('\n').trimEnd();
+      if (!REMOVE) {
+        const { command, args } = launch();
+        const envLines = Object.entries(desiredEnv())
+          .map(([k, v]) => k + ' = ' + JSON.stringify(v)).join('\n');
+        out += (out ? '\n\n' : '') +
+          '[mcp_servers.' + NAME + ']\ncommand = ' + JSON.stringify(command) +
+          '\nargs = ' + JSON.stringify(args) +
+          '\nstartup_timeout_sec = 20.0\ntool_timeout_sec = 120.0\n\n' +
+          '[mcp_servers.' + NAME + '.env]\n' + envLines;
+      }
+      out += '\n';
+      if (out === raw) return { skipped: 'already up to date' };
+      if (!WRITE) return { preview: REMOVE ? 'TOML block would be removed' : 'TOML block would be written' };
+      backup(cfg);
+      atomicWrite(cfg, out);
+      return { done: REMOVE ? 'TOML block removed' : 'TOML block written' };
+    },
+  },
+  { id: 'cursor',   label: 'Cursor',   json: () => join(HOME, '.cursor', 'mcp.json'),                        key: 'mcpServers' },
+  { id: 'windsurf', label: 'Windsurf', json: () => join(HOME, '.codeium', 'windsurf', 'mcp_config.json'),     key: 'mcpServers' },
+  { id: 'zed',      label: 'Zed',      json: () => join(IS_WIN ? APPDATA : join(HOME, '.config'), IS_WIN ? join('Zed','settings.json') : join('zed','settings.json')), key: 'context_servers' },
+];
+
+/** Shared reader/writer for the JSON-shaped clients. */
+function applyJson(c) {
+  const file = c.json();
+  const parsed = parseJson(file);
+  if (parsed.error) return { error: 'existing file is not valid JSON (' + parsed.error + ')' };
+
+  const root = (parsed.json && typeof parsed.json === 'object') ? parsed.json : {};
+  const bag = (root[c.key] && typeof root[c.key] === 'object') ? root[c.key] : {};
+
+  if (REMOVE) {
+    if (!Object.prototype.hasOwnProperty.call(bag, NAME)) return { skipped: 'not present' };
+    delete bag[NAME];
+  } else {
+    const { command, args } = launch();
+    const next = { command, args, env: desiredEnv() };
+    if (JSON.stringify(bag[NAME]) === JSON.stringify(next)) return { skipped: 'already up to date' };
+    bag[NAME] = next;
+  }
+  root[c.key] = bag;
+
+  const text = JSON.stringify(root, null, 2) + '\n';
+  if (text === parsed.raw.trimEnd() + '\n') return { skipped: 'no change' };
+  JSON.parse(text);            // self-check before touching disk
+
+  // Dry-run must stop here. This file used to write unconditionally and only
+  // reported "would write" in the orchestration layer, which meant `setup`
+  // without --yes silently modified every client config it found -- the exact
+  // opposite of what the docs promise.
+  if (!WRITE) return { preview: REMOVE ? 'entry would be removed' : 'entry would be written' };
+
+  backup(file);
+  atomicWrite(file, text);
+  const back = parseJson(file); // self-check after writing
+  if (back.error) return { error: 'wrote a file that no longer parses (' + back.error + '); restore the .bak' };
+  return { done: REMOVE ? 'entry removed' : 'entry written' };
+}
+
+// --- main -----------------------------------------------------------
+
+const lc = launch();
+log('');
+log(WRITE
+  ? (REMOVE ? 'Removing ' + NAME + ' from MCP clients' : 'Installing ' + NAME + ' into MCP clients')
+  : 'Preview only -- nothing is written. Re-run with --yes to apply.');
+log('  permission : ' + PERMISSION);
+log('  launch     : ' + lc.command + (lc.args.length ? ' ' + lc.args.join(' ') : '') + '   (' + lc.style + ')');
+log('  DSH_BIN    : ' + (process.env.DSH_BIN || '(unset -- auto-detect at runtime)'));
+log('');
+
+let changed = 0, skipped = 0, failed = 0;
+
+for (const c of CLIENTS) {
+  if (ONLY.length && !ONLY.includes(c.id)) continue;
+
+  let present = false;
+  try { present = c.detect ? c.detect() : existsSync(c.json()); } catch {}
+  log(c.label + (present ? '' : '   (not installed)'));
+
+  if (!present) { dash('skipped: client not found'); skipped++; log(''); continue; }
+
+  let r;
+  try { r = c.apply ? c.apply() : applyJson(c); }
+  catch (e) { r = { error: e.message }; }
+
+  if (r.error) { bang(r.error); failed++; }
+  else if (r.skipped) { dash('skipped: ' + r.skipped); skipped++; }
+  else if (r.preview) { tick(r.preview); changed++; }
+  else { tick(r.done); changed++; }
+  log('');
+}
+
+log('Summary: ' + changed + ' ' + (WRITE ? 'changed' : 'would change') + ', ' + skipped + ' skipped, ' + failed + ' failed');
+if (!WRITE && changed) log('Nothing was written. Re-run with --yes to apply.');
+if (failed) {
+  log('');
+  log('A failure above left no damage: every writer validates the result and keeps');
+  log('a .bak-dsh-* copy beside the file it touched.');
+}
+process.exit(failed ? 1 : 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-any-agent",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Drive DeepSeek Harness (DSH) as a long-lived coding agent from any MCP client — Claude Code, Codex, Cursor, or your own. Resume-aware, interruptible, approval-capable.",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,8 @@
     "orchestration"
   ],
   "bin": {
-    "dsh-any-agent": "./bin/dsh-any-agent.mjs"
+    "dsh-any-agent": "bin/dsh-any-agent.mjs",
+    "dsh-any-agent-setup": "bin/setup.mjs"
   },
   "files": [
     "bin/",
@@ -39,13 +40,14 @@
   ],
   "scripts": {
     "start": "node ./bin/dsh-any-agent.mjs",
+    "setup": "node ./bin/setup.mjs",
     "test": "node ./test/run.mjs",
     "test:smoke": "node ./test/smoke.mjs",
     "test:guards": "node ./test/guards.mjs",
     "test:prune": "node ./test/prune.mjs"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.15"
   },
   "repository": {
     "type": "git",

package/src/config.mjs

@@ -210,13 +210,13 @@ export const REAP_INTERVAL_MS = Number.isFinite(rawReap) && rawReap >= 200 ? raw
  * 最多同时保活多少个会话进程（`0` = 不限）。
  *
  * 为什么需要它：`IDLE_TTL_MS=0`（永不回收）能保证"GUI 抢不走写锁"，但代价是
- * **每个用过的会话永久占一个 DSH 子进程** —— 实测约 120MB/个（线性），10 个就 ~1.2GB ✗。
+ * **每个用过的会话永久占一个 DSH 子进程** —— 实测约 300-480MB/个（近似线性），10 个可达 3-5GB ✗。
  * 超过上限时**回收最久没用过的那个**（busy 的绝不回收）：
  *   - 保活窗口内的会话：写锁在手，GUI 抢不走 ✓
  *   - 窗口外的：进程回收、内存释放 ✓（下次派活自动 resume，无损 ✓）
  * 即"**内存有界，锁尽量在手**"。
  *
- * **默认 8**（≈1GB）：让"内存有界"成为默认行为，而不是要用户先发现再配 ✗。
+ * **默认 8**（按实测 300-480MB/个，最坏约 2.5-4GB）：让"内存有界"成为默认行为，而不是要用户先发现再配 ✗。
  * 被回收是无损的（会话日志在磁盘上 ✓），代价只是那个会话的写锁会空出来、
  * 且下次派活要 cold start。想做更多并行就调大；机器大也可以设 0（不限）。
  */

package/src/hub.mjs

@@ -1275,7 +1275,7 @@ export class Hub {
    * ★ 但**心跳必须一直续**，两种模式都一样：心跳停了，别的实例 90 秒后就会把我们
    *   判成"卡死"，`dsh_takeover` 于是会**杀掉我们正在跑的回合**。
    *
-   * ★ `DSH_MCP_MAX_LIVE`（保活上限）：`IDLE_TTL_MS=0` 时进程会永远留着（实测约 120MB/个 ✗），
+   * ★ `DSH_MCP_MAX_LIVE`（保活上限）：`IDLE_TTL_MS=0` 时进程会永远留着（实测约 300-480MB/个 ✗），
    *   设了上限就在超标时回收**最久没用过**的那个（busy 的绝不回收）—— "内存有界，锁尽量在手"。
    */
   startReaper() {
@@ -1338,7 +1338,7 @@ export class Hub {
   /**
    * 释放**所有**活着的会话进程（腾内存用，无损：会话日志都在磁盘上，之后照样 resume）。
    *
-   * 场景：默认"永不回收"下每个用过的会话会常驻一个 DSH 进程（实测约 120MB ✗）。
+   * 场景：默认"永不回收"下每个用过的会话会常驻一个 DSH 进程（实测约 300-480MB ✗）。
    * 一批活干完了就调它，内存立刻归零 ✓；下次派活按需 resume ✓。
    */
   async releaseAll() {

package/src/mcp.mjs

@@ -5,11 +5,27 @@
  * 因为混进 stdout 的日志会直接破坏报文。日志默认静默（见 config.createLogger）。
  */
 
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { createHandlers, TOOL_DEFS } from './tools.mjs';
 import { DEFAULT_PERMISSION } from './config.mjs';
 
 const SERVER_NAME = 'dsh-any-agent';
-const SERVER_VERSION = '0.1.0';
+/**
+ * Version comes from package.json so it cannot drift from the published
+ * artifact. The old hard-coded copy is exactly the kind of duplicated fact
+ * that goes stale the moment someone runs `npm version`.
+ */
+export const SERVER_VERSION = (() => {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+    return pkg.version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+})();
 const FALLBACK_PROTOCOL = '2025-06-18';
 
 const INSTRUCTIONS = `这个服务把 DeepSeek Harness (DSH) 当作一个**可长期共事的编码 agent** 来驱动。

package/src/tools.mjs

@@ -211,7 +211,7 @@ export const TOOL_DEFS = [
     description:
       '释放会话占用的 DSH 进程（释放写锁，让用户能在自己的 DSH GUI 里打开同一个会话）。' +
       '会话本体留在磁盘上，之后仍可 resume；forget=true 才会从注册表里摘掉。' +
-      '★ 用完了想一次性腾内存就传 all=true（默认"永不回收"下每个会话约 120MB，全放掉即立刻归零，之后随时 resume）。',
+      '★ 用完了想一次性腾内存就传 all=true（默认"永不回收"下每个会话约 300-480MB，全放掉即立刻归零，之后随时 resume）。',
     inputSchema: S(
       {
         conversation_id: CONV_ID,