dsh-any-agent 0.3.7 → 0.3.8

package/CHANGELOG.md

@@ -7,7 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-Post-0.3.7 hardening.
+Post-0.3.8 hardening.
+
+## [0.3.8] — 2026-11-02
+
+### Changed
+
+- `npm test` now works without a local DSH: smoke still checks handshake and
+  the tool table, then skips session-dependent sections instead of failing, so
+  all offline suites run. `npm run test:all` is the explicit full-suite entry.
+- Added the `model-suites` workflow for a self-hosted runner with DSH and
+  provider credentials; hosted runners print an explicit skip.
+- Added an English `USAGE-MIGRATION.en.md` and linked it from the English
+  README and `/en/` install section.
+
+### Testing
+
+- Removed the remaining always-true `check(..., true)` assertions; cleanup
+  checks now assert actual release/forget results or timeout state.
+- `prune` runs with an isolated `DSH_HOME` so it cannot touch real tombstones.
+- Added 8 static accessibility tests for both locales (28 website tests total
+  counting the existing site/release/demo suites).
+- `readHeaderAsync` now uses `StringDecoder` for multi-byte UTF-8 boundaries.
+
+### Website
+
+- `robots.txt` now mirrors the complete Cloudflare Managed crawler list, not
+  just the four most common bots.
 
 ## [0.3.7] — 2026-11-02
 
@@ -670,7 +696,8 @@ First public release, published to npm as [`dsh-any-agent`](https://www.npmjs.co
   profiles, sessions and client configs. The product name changed; the on-disk
   contract did not. See the README FAQ.
 
-[Unreleased]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.7...HEAD
+[Unreleased]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.8...HEAD
+[0.3.8]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.7...v0.3.8
 [0.3.7]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.6...v0.3.7
 [0.3.6]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.5...v0.3.6
 [0.3.5]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.4...v0.3.5

package/DESIGN.md

@@ -2,7 +2,15 @@
 
 > 目标：做一个 MCP Server，让 **Codex / Claude Code** 能调用 **DeepSeek Harness (DSH)** 当"外包工程师"——写代码、搭脚手架、跑任务，并且 DSH 自己还能挂它自己的 MCP。
 >
-> 本文只谈**功能与接口**，不写实现代码；其中 M2/M3 工具（`dsh_rename` 等）是分期计划，不是当前 0.3.7 的缺失功能。技术判断最初基于 DSH 0.1.7-rc.2，当前验证基线是 **DSH 0.2.1-rc.5**（见 §2 证据）。
+> 本文只谈**功能与接口**，不写实现代码；其中 M2/M3 工具（`dsh_rename` 等）是分期计划，不是当前 0.3.8 的缺失功能。技术判断最初基于 DSH 0.1.7-rc.2，当前验证基线是 **DSH 0.2.1-rc.5**（见 §2 证据）。
+
+## 当前实现状态（0.3.8）
+
+当前对外暴露 11 个工具，均已实现并有回归：
+
+`dsh_start`、`dsh_send`、`dsh_list`、`dsh_read`、`dsh_get`、`dsh_interject`、`dsh_interrupt`、`dsh_release`、`dsh_takeover`、`dsh_approval_decide`、`dsh_status`
+
+本文后续出现的 `dsh_resume`、`dsh_rename`、`dsh_delete`、`dsh_transcript`、`dsh_diff`、`dsh_doctor` 等属于 M2/M3 路线图，**不是当前版本的缺失**。当前版本的能力边界以 README 的 Known limitations 与 USAGE-NOTES 为准。
 
 ---
 

package/README.md

@@ -15,7 +15,7 @@
 
 </div>
 
-🧪 815 checks green on 0.3.7 on this machine (851 when all nine client fixtures exist); 519 of them are in the client-registration suites (555 with all fixtures) · 🔌 MCP over stdio · 📦 Zero dependencies · 📜 MIT
+🧪 815 checks green on 0.3.8 on this machine (851 when all nine client fixtures exist); 519 of them are in the client-registration suites (555 with all fixtures) · 🔌 MCP over stdio · 📦 Zero dependencies · 📜 MIT
 
 An MCP server that drives DeepSeek Harness as a **long-lived coding agent**. Hand it a goal, let it write code and run scripts, steer it mid-flight, and collect the result when you are ready.
 
@@ -33,7 +33,7 @@ dsh-any-agent-setup --yes
 
 The second command previews the changes; `--yes` applies them. Reconnect your client's MCP server, then ask your agent to start a DSH conversation in your project, dispatch a task, and collect the result. The [dispatch workflow](#-workflow-dispatch-then-collect-later) shows the tool sequence.
 
-> **Before your first task:** read the [Usage Notes](USAGE-NOTES.en.md), especially the model-config and external-MCP permission boundaries. External MCP tools bypass DSH's sandbox. For a fresh machine, follow the [migration guide](USAGE-MIGRATION.md).
+> **Before your first task:** read the [Usage Notes](USAGE-NOTES.en.md), especially the model-config and external-MCP permission boundaries. External MCP tools bypass DSH's sandbox. For a fresh machine, follow the [migration guide](USAGE-MIGRATION.en.md).
 
 <details>
 <summary>Full contents</summary>
@@ -550,11 +550,15 @@ Silent by default — **not one byte is written**.
 ## 🧪 Tests
 
 ```bash
-node test/run.mjs          # all offline suites (no LLM calls; needs DSH for smoke)
-node test/run.mjs --all    # offline + model-backed suites
+npm test                   # offline suites; smoke skips DSH sections if no DSH
+npm run test:all           # offline + model-backed suites (needs DSH/provider)
 node test/cleanup.mjs      # suite teardown on its own (test-created dirs only; --dry-run to preview)
 ```
 
+Model-backed suites are not part of the hosted CI matrix (they need a real DSH
+install and provider credentials). Run them locally, or dispatch the
+`model-suites` workflow with a self-hosted runner that has DSH configured.
+
 The suite **cleans up after itself**: `run.mjs` always ends with `cleanup.mjs`, which removes sessions and workspace registrations whose cwd is **a test-created directory** (`tmpdir()/dsh-any-agent-*` or `Desktop/dsh-any-agent-test-*`). Real project sessions — including projects under `%TEMP%` — and your live state directory are never touched. To remove `Desktop/dsh-any-agent-test-*` artifacts explicitly, run `node bin/dsh-any-agent-workspaces.mjs --purge-test-sessions`.
 
 | Suite | Checks | Covers |
@@ -595,11 +599,11 @@ The suite **cleans up after itself**: `run.mjs` always ends with `cleanup.mjs`,
 | `list` | 13 | **the cost of `dsh_list`** (measured): a default call with the on-disk probe takes ~1 s (it spawns a DSH process) while **repeated calls hit a cache and drop to single-digit milliseconds**; `only_running=true` and `include_closed=false` **skip the probe** with equivalent semantics (unopened on-disk sessions are simply excluded) |
 | `reasoning-check` | 8 | **reasoning visibility**: `reasoning=hide` returns no thinking body but non-zero stats; `reasoning=full` returns the text and the rendered section |
 
-**`node test/run.mjs` runs 815 checks on a machine with five client fixtures (851 with all nine)** — smoke 29 + 786 offline checks (822 with nine). Every suite exited 0 on 0.3.7; none needs a provider (smoke needs a DSH install for its session-creation section).
+**`node test/run.mjs` runs 815 checks on a machine with five client fixtures (851 with all nine)** — smoke 29 + 786 offline checks (822 with nine). Every suite exited 0 on 0.3.8; none needs a provider (smoke skips its session-creation sections when DSH is absent).
 
 That is **519 assertions in the client-registration suites alone** (`setup` 41, `removal-scope` 24, `config-safety` 406, `real-configs` 48; 555 with all nine fixtures), which is where the 0.3 work actually is.
 
-The model-backed suites (`smoke` 29, `boundary` 46, `integration` 30, `async` 16, `sentinel` 36, `timeout` 38, `lock` 79, `cycle` 36, `concurrency` 31, `capability` 22, `workspace-effect` 24, `acceptance` 36, `multi` 19, `permission` 11, `list` 13, `reasoning-check` 8) total 474 and were last measured in full on 0.3.7 — they need a working provider, so re-run them yourself before trusting a release: `node test/run.mjs --all`. `acceptance` now **skips explicitly** when the DSH profile has no IDA MCP (`mcp__ida__*`).
+The model-backed suites (`smoke` 29, `boundary` 46, `integration` 30, `async` 16, `sentinel` 36, `timeout` 38, `lock` 79, `cycle` 36, `concurrency` 31, `capability` 22, `workspace-effect` 24, `acceptance` 36, `multi` 19, `permission` 11, `list` 13, `reasoning-check` 8) total 474 and were last measured in full on 0.3.8 — they need a working provider, so re-run them yourself before trusting a release: `node test/run.mjs --all`. `acceptance` now **skips explicitly** when the DSH profile has no IDA MCP (`mcp__ida__*`).
 
 > Three different totals are intentional: `node test/run.mjs` (815/851), the CI offline job (786/822, no smoke), and the model-backed set (474 nominal). Counts are the numbers each suite prints itself; don't use one number for a different runner.
 

package/README.zh.md

@@ -15,7 +15,7 @@
 
 </div>
 
-🧪 0.3.7 本机 815 项检查全绿（九种客户端配置齐全时 851 项；其中 519 项属于客户端注册器套件，齐全时 555 项） · 🔌 MCP over stdio · 📦 零依赖 · 📜 MIT
+🧪 0.3.8 本机 815 项检查全绿（九种客户端配置齐全时 851 项；其中 519 项属于客户端注册器套件，齐全时 555 项） · 🔌 MCP over stdio · 📦 零依赖 · 📜 MIT
 
 一个 MCP 服务端，把 DeepSeek Harness 当作**长驻的编码 agent** 来驱动。开个会话、扔个目标，它自己写代码、跑脚本、派子代理；你随时能看、能插话、能回头验收。
 
@@ -565,11 +565,14 @@ node bin/dsh-any-agent-workspaces.mjs --purge-test-sessions   # 删测试会话
 ## 🧪 测试
 
 ```bash
-node test/run.mjs          # 全部离线套件（不消耗 token；smoke 段需要装 DSH）
-node test/run.mjs --all    # 离线 + 需要模型的套件
+npm test                   # 全部离线套件；没有 DSH 时 smoke 自动跳过会话段
+npm run test:all           # 离线 + 需要模型的套件（需要 DSH/provider）
 node test/cleanup.mjs      # 单独跑收尾清理（只清测试自己造的目录；--dry-run 可预演）
 ```
 
+模型套件不在 GitHub 托管 CI 里（需要真实 DSH、provider 与凭据）。在本机跑，
+或用 `model-suites` workflow 指定一台装好 DSH 的 self-hosted runner。
+
 测试套件**会自己收尾**：`run.mjs` 结束时必定执行 `cleanup.mjs`，它只清理 cwd 在**测试自己造的目录**（`tmpdir()/dsh-any-agent-*` 或桌面 `dsh-any-agent-test-*`）里的会话与工作区登记。**用户在 `%TEMP%` 里自己的真实项目、以及你的状态目录都不会被碰**。要连桌面测试目录一起清，可显式跑 `node bin/dsh-any-agent-workspaces.mjs --purge-test-sessions`。
 
 | 套件 | 检查数 | 覆盖 |
@@ -610,11 +613,11 @@ node test/cleanup.mjs      # 单独跑收尾清理（只清测试自己造的目
 | `list` | 13 | **`dsh_list` 的开销**（实测驱动）：含磁盘探测的默认调用约 1 秒（要 spawn 一个 DSH 进程），**连续调用命中缓存降到个位数毫秒**；`only_running=true` 与 `include_closed=false` **跳过探测**且语义等价（不把磁盘上的未打开会话算进来） |
 | `reasoning-check` | 8 | **思考可见性**：`reasoning=hide` 不返回思考正文但统计非零；`reasoning=full` 返回正文且渲染出思考段 |
 
-**`node test/run.mjs` 在本机 5/9 客户端配置时跑 815 项（九种齐全时 851 项）** —— smoke 29 + 离线套件 786 项（九种齐全时 822 项）。0.3.7 上全部退出码 0；都不需要 provider（smoke 的建会话段需要装 DSH）。
+**`node test/run.mjs` 在本机 5/9 客户端配置时跑 815 项（九种齐全时 851 项）** —— smoke 29 + 离线套件 786 项（九种齐全时 822 项）。0.3.8 上全部退出码 0；都不需要 provider（没有 DSH 时 smoke 自动跳过建会话段）。
 
 其中 **519 项属于客户端注册器套件**（`setup` 41、`removal-scope` 24、`config-safety` 406、`real-configs` 48；九种齐全时 555 项）—— 0.3 的活其实都在这里。
 
-需要模型的套件（`smoke` 29、`boundary` 46、`integration` 30、`async` 16、`sentinel` 36、`timeout` 38、`lock` 79、`cycle` 36、`concurrency` 31、`capability` 22、`workspace-effect` 24、`acceptance` 36、`multi` 19、`permission` 11、`list` 13、`reasoning-check` 8）合计 474 项，**最近一次完整实测在 0.3.7** —— 它们要可用 provider，发版前请自己重跑一遍：`node test/run.mjs --all`。`acceptance` 在没有 IDA MCP（`mcp__ida__*`）时会明确 **skip**。
+需要模型的套件（`smoke` 29、`boundary` 46、`integration` 30、`async` 16、`sentinel` 36、`timeout` 38、`lock` 79、`cycle` 36、`concurrency` 31、`capability` 22、`workspace-effect` 24、`acceptance` 36、`multi` 19、`permission` 11、`list` 13、`reasoning-check` 8）合计 474 项，**最近一次完整实测在 0.3.8** —— 它们要可用 provider，发版前请自己重跑一遍：`node test/run.mjs --all`。`acceptance` 在没有 IDA MCP（`mcp__ida__*`）时会明确 **skip**。
 
 > 三个总数是刻意分开的：`node test/run.mjs`（815/851）、CI 离线 job（786/822，不含 smoke）、需要模型的集合（名义 474）。数字取各套件自己打印的汇总，不在这里手抄；不要把一个数字套到另一个 runner 上。
 

package/USAGE-MIGRATION.en.md

@@ -0,0 +1,160 @@
+# Moving to a new machine / first-time setup (English)
+
+This is the short English version of `USAGE-MIGRATION.md`. It covers a fresh
+install, registering the MCP server with your client, and the checks worth
+doing before you trust it with real work.
+
+## 1. Prerequisites
+
+| Item | Requirement |
+|---|---|
+| Node.js | **≥ 22.15** (`zstdDecompressSync` is required) |
+| DSH | DeepSeek Harness installed and able to answer a normal chat turn |
+| Provider | A model route configured in DSH, with credentials available through `~/.dsh/.credentials.yaml` or environment variables |
+
+> The order matters. This server does **not** ship a provider or credentials.
+> On first start it copies the model route from an existing DSH profile. If DSH
+> itself is not configured, the first call fails with a provider error.
+
+## 2. Install and register
+
+```bash
+npm install -g dsh-any-agent
+
+# Preview only: reads configs, writes nothing
+dsh-any-agent-setup
+
+# Apply
+dsh-any-agent-setup --yes
+
+# Limit to some clients, or choose a permission tier
+dsh-any-agent-setup --yes --only cursor,zed
+dsh-any-agent-setup --yes --permission workspace-write
+
+# Remove only this server's entry
+dsh-any-agent-setup --remove --yes
+```
+
+Supported clients: **Claude Code, Claude Desktop, Codex, Cursor, Windsurf,
+Zed, Gemini CLI, opencode, VS Code**. Clients that are not installed are
+reported as skipped, not failed.
+
+The writer is deliberately conservative:
+
+- preview mode never writes and never starts a child process;
+- every changed file is backed up as `<file>.bak-dsh-<stamp>`;
+- JSON/JSONC/TOML edits are text-level and only touch the
+  `dsh-any-agent` entry (indentation, key order, CRLF, BOM and comments are
+  preserved);
+- malformed or read-only configs are refused rather than overwritten;
+- a second `--yes` is a no-op;
+- `setup` does **not** invoke client CLIs such as `claude mcp get` (that can
+  make Claude Code rewrite `~/.claude.json`).
+
+## 3. Manual configuration (optional)
+
+If your client is not covered by setup, add a stdio MCP server. For example:
+
+Codex `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.dsh-any-agent]
+command = "dsh-any-agent"
+args = []
+startup_timeout_sec = 20.0
+tool_timeout_sec = 120.0
+```
+
+Generic JSON client:
+
+```json
+{
+  "mcpServers": {
+    "dsh-any-agent": {
+      "command": "dsh-any-agent",
+      "args": []
+    }
+  }
+}
+```
+
+`setup --yes` writes the absolute node path, the entry file, and
+`DSH_MCP_PERMISSION` / `DSH_MCP_LOG`; the examples above assume
+`dsh-any-agent` is on `PATH`.
+
+## 4. First start and profile bootstrap
+
+On first start the server creates `~/.dsh/profiles/dsh-mcp/` and copies the
+model route from an existing DSH profile (`home` → `desktop` → `web` →
+`headless` → `acp`, first usable one). It uses a built-in zero-dependency YAML
+subset parser, so no extra npm package is needed.
+
+What is copied: `apiKeyEnv`, `baseURL`, `api`, `models`, reasoning metadata.
+What is stripped: literal API keys, nested `headers`, and URL userinfo. The
+generated profile includes the three permission presets but **never**
+`defaultPreset` (that would override the permission tier at session creation).
+
+Credentials remain in DSH's own credential store; this project never owns them.
+Set `DSH_MCP_BOOTSTRAP=0` to disable profile writing entirely, or
+`DSH_MCP_ROUTE_SOURCE=<profile>` / `__home__` to pin the route source.
+
+## 5. Permission tiers
+
+| Tier | Meaning |
+|---|---|
+| `read-only` | DSH's sandbox is read-only; approvals are forced to `auto-deny` |
+| `workspace-write` | Writes are limited to the workspace by DSH's sandbox |
+| `danger-full-access` | No workspace sandbox |
+
+The server's raw default is `danger-full-access` when `DSH_MCP_PERMISSION` is
+not set; `setup` writes `workspace-write` into the client config. Out-of-
+workspace approval requests default to `auto-allow`; pass `on_approval=ask`
+when creating a session if you want `dsh_approval_decide` to adjudicate them.
+
+`read-only` is a hard boundary at this layer: `read-only + auto-allow/ask` is
+rejected, and the server reads back the session's recorded permission tier
+after create/resume. External MCP tools mounted in DSH are outside DSH's
+sandbox; read `USAGE-NOTES.en.md` before using them with untrusted data.
+
+## 6. Verify
+
+```bash
+dsh-any-agent --version
+dsh-any-agent-setup --help
+dsh-any-agent-setup                 # preview should show your clients
+```
+
+In the client, ask the agent to call `dsh_start` with a small project
+directory, then `dsh_send` a short prompt and `dsh_get` the result. If the
+client cannot see the server, restart the client after setup.
+
+## 7. Common problems
+
+- **`DSH CLI entry not found`** — set `DSH_BIN` to
+  `.../node_modules/@deepseek-ai/dsh/lib/bin.js`, or install DSH in a location
+  the server can discover.
+- **`no adapter registered for provider` / no API key** — DSH itself is not
+  configured, or the profile route was not copied. Open DSH once, configure a
+  model, then restart the MCP server.
+- **`session ... is already owned by an active write handle`** — the session
+  is held by another process (often the DSH GUI). Use `dsh_status` to see
+  `lock_holder`; use `dsh_release` on the other instance or `dsh_takeover`
+  when the holder is a stale dsh-any-agent process. Never kill a GUI process.
+- **Nothing happens when waiting for completion** — use the returned
+  `sentinel_file`; a turn that is interrupted by a process exit may not land
+  one. Inspect the workspace and re-dispatch.
+- **Old state after upgrading** — the registry moved from
+  `<repo>/.state/conversations.json` to
+  `$DSH_HOME/.dsh-any-agent/conversations.json`; the first 0.3.x start
+  migrates it automatically. Use `DSH_MCP_STATE` to override.
+
+## 8. Upgrade / rollback
+
+`npm install -g dsh-any-agent@latest` upgrades the server. Client configs are
+not rewritten by an upgrade; run `dsh-any-agent-setup` again only if you want
+to refresh the entry or permission env. `dsh-any-agent-restore` can restore a
+client config from a `.bak-dsh-*` backup.
+
+For the full Chinese guide, environment-variable reference, write-lock
+measurements and website deployment notes, see `USAGE-MIGRATION.md`,
+`README.md` and `USAGE-NOTES.en.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-any-agent",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Drive DeepSeek Harness (DSH) as a long-lived coding agent from any MCP client — Claude Code, Claude Desktop, Codex, Cursor, Windsurf, Zed, Gemini CLI, opencode, VS Code. Resume-aware, interruptible, approval-capable, and it only ever touches the one config entry it owns.",
   "type": "module",
   "license": "MIT",
@@ -36,6 +36,7 @@
     "USAGE-NOTES.en.md",
     "USAGE-NOTES.md",
     "USAGE-MIGRATION.md",
+    "USAGE-MIGRATION.en.md",
     "CHANGELOG.md",
     "LICENSE",
     "DESIGN.md",
@@ -45,6 +46,7 @@
     "start": "node ./bin/dsh-any-agent.mjs",
     "setup": "node ./bin/setup.mjs",
     "test": "node ./test/run.mjs",
+    "test:all": "node ./test/run.mjs --all",
     "test:smoke": "node ./test/smoke.mjs",
     "test:guards": "node ./test/guards.mjs",
     "test:prune": "node ./test/prune.mjs",

package/src/workspace.mjs

@@ -19,6 +19,7 @@ import { copyFileSync, createReadStream, readFileSync, writeFileSync, existsSync
 import { randomUUID } from 'node:crypto';
 import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
 import { tmpdir } from 'node:os';
+import { StringDecoder } from 'node:string_decoder';
 import { createZstdDecompress, zstdDecompressSync } from 'node:zlib';
 import { DSH_HOME, REGISTER_WORKSPACE } from './config.mjs';
 
@@ -245,6 +246,7 @@ export async function readHeaderAsync(file, { timeoutMs = 5000, maxHeaderBytes =
     let settled = false;
     let buf = '';
     let timer = null;
+    const decoder = new StringDecoder('utf8');
     const rs = createReadStream(file);
     const zs = createZstdDecompress();
     const finish = (value) => {
@@ -268,12 +270,15 @@ export async function readHeaderAsync(file, { timeoutMs = 5000, maxHeaderBytes =
     rs.on('error', () => finish(null));
     zs.on('error', () => finish(null));
     zs.on('data', (chunk) => {
-      buf += chunk.toString('utf8');
+      // 用 StringDecoder 处理跨 chunk 的多字节 UTF-8（中文/emoji 路径），
+      // 避免 chunk.toString() 把字符截成乱码。
+      buf += decoder.write(chunk);
       const nl = buf.search(/\r?\n/);
       if (nl >= 0) parseLine(buf.slice(0, nl));
       else if (buf.length > maxHeaderBytes) finish(null);
     });
     zs.on('end', () => {
+      buf += decoder.end();
       const line = buf.split(/\r?\n/).find(Boolean);
       if (line) parseLine(line);
       else finish(null);