dsh-baton-mcp 0.0.1 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JialaoLiu
+
+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

@@ -1,3 +1,187 @@
-# dsh-baton-mcp
+<p align="center">
+  <img src="./assets/readme/hero.gif" width="100%" alt="dsh-baton: pass the baton from Claude Code or Codex to DeepSeek Harness, watch it run live, and get it handed back when it's done">
+</p>
 
-This name is reserved for [dsh-baton](https://github.com/JialaoLiu/dsh-baton). The real release is coming soon.
+<p align="center">
+  English | <a href="README.zh-CN.md">中文</a> · Unofficial; not affiliated with DeepSeek.
+</p>
+
+<p align="center">
+  macOS · Windows (<a href="WINDOWS.md">guide</a>) · Node.js ≥ 22.15 · zero dependencies · MIT
+</p>
+
+<p align="center">
+  <img src="./assets/readme/features.svg" width="100%" alt="Create workspaces and sessions, continue a session, run live in the Harness UI labelled with the sender, get woken when it is done, no extra API key, macOS and Windows with zero dependencies">
+</p>
+
+<p align="center">
+  <img src="./assets/readme/flow.gif" width="100%" alt="Typical flow: create a workspace, send the task, wait in the background, follow up in the same session">
+</p>
+
+## See it run
+
+One Codex chat starts a task, queues a follow-up, steers the running turn, and waits for all three:
+
+<p align="center">
+  <img src="./assets/demos/s3-queue-en.gif" width="100%" alt="Codex on the left starts a DeepSeek task, queues a follow-up, steers the running turn and waits; DeepSeek Harness on the right runs each one live">
+</p>
+
+Codex and Claude take turns in the same Harness session, and every message is labelled with who sent it:
+
+<p align="center">
+  <img src="./assets/demos/s8-relay-en-zoom.gif" width="100%" alt="Harness chat where messages alternate between Codex and Claude, each labelled Sent by ChatGPT or Sent by Claude from another chat">
+</p>
+
+<p align="center"><a href="docs/demos.md">More demos →</a></p>
+
+## Quick start
+
+<p align="center">
+  <img src="./assets/readme/install.svg" width="100%" alt="Step 1: run npx -y dsh-baton-mcp setup. Step 2: in Harness open Plugins, Add plugin, paste, Install, Enable now. Step 3: in a new chat, ask for dsh_list_workspaces">
+</p>
+
+Requires DeepSeek Harness ≥ 0.2.1-rc.2 (signed in), Node.js ≥ 22.15. On Windows, see [WINDOWS.md](WINDOWS.md).
+
+**1. Run setup** in a terminal:
+
+```bash
+npx -y dsh-baton-mcp setup
+```
+
+dsh-baton has no dependencies. `setup` copies itself to `~/.dsh-baton/app`, a folder that stays put (npx's cache does not), and registers the MCP server once, user-wide, for Claude Code and Codex: every new conversation, in any folder, has the `dsh_*` tools. It writes `~/.claude.json` and `~/.codex/config.toml` directly (a backup of each is kept as `*.bak-dsh-baton`), so it also works when only the desktop apps are installed and `claude` / `codex` are not on your `PATH`. Running it again is safe.
+
+**2. Paste in Harness.** `setup` copies the plugin folder path to your clipboard:
+
+**Plugins** (插件) → **Add plugin** (添加插件) → paste → **Install** (安装) → **Enable now** (立即启用)
+
+**3. Check.** Start a **new** conversation in Claude Code or Codex and ask it to call `dsh_list_workspaces`. It lists your Harness workspaces.
+
+**Or let Claude Code or Codex do it:** paste *"Run `npx -y dsh-baton-mcp setup`, then tell me the Harness step it prints."*
+
+**How each client waits** (nothing to configure):
+- **Claude Code** waits for a run in the background (the `wait_command` that `dsh_send` returns) and is woken once, when the run ends.
+- **Codex** waits inside `dsh_wait`, up to 270 s per call, just under its 300 s tool timeout. An unfinished wait returns only the state, so Codex calls again without summarising. Codex gets no `wait_command`: its terminal cannot wake it, so it would poll.
+- Codex asks you to approve MCP tool calls: approve the `dsh-baton` tools. For unattended `codex exec` runs, add `--approve-for-me`.
+
+**Updating:** run `npx -y dsh-baton-mcp@latest setup` again, then restart Harness to load plugin changes; new conversations pick up MCP server changes.
+
+**Removing:** `npx -y dsh-baton-mcp setup --remove`, then Harness → Plugins → dsh-baton-host → Uninstall, then `setup --remove` once more to delete `~/.dsh-baton/app`.
+
+**Upgrading from dsh-bridge**: run `setup` as above. It replaces the old `dsh-bridge` MCP entries; in Harness, uninstall `dsh-bridge-host`, then add the new path. `DSH_BRIDGE_*` variables and an existing `~/.dsh-bridge` folder keep working for now. Tools get a new prefix (`mcp__dsh-baton__…`), so update any permission allowlists.
+
+**From source** (to follow `main` or to change the code): `git clone https://github.com/JialaoLiu/dsh-baton.git` and `node dsh-baton/src/cli.mjs setup`. setup then registers the clone itself; update with `git pull`.
+
+<details>
+<summary>Manual registration and the Claude desktop app</summary>
+
+`setup` writes the same entries these commands would (with the absolute path of `node`, since desktop apps start MCP servers without your shell's `PATH`):
+
+```bash
+claude mcp add dsh-baton -s user -- "$(command -v node)" "$PWD/dsh-baton/src/server.mjs"
+codex mcp add dsh-baton -- "$(command -v node)" "$PWD/dsh-baton/src/server.mjs"
+```
+
+`-s user` matters: without it, Claude Code registers the server for the current project folder only.
+
+**Claude desktop app (optional)**: for the chat app's connectors (separate from Claude Code), add this to `~/Library/Application Support/Claude/claude_desktop_config.json` and restart the app. It shows as a "Local dev" connector.
+
+```json
+{ "mcpServers": { "dsh-baton": { "command": "/absolute/path/to/node", "args": ["/absolute/path/to/dsh-baton/src/server.mjs"] } } }
+```
+
+</details>
+
+## How it works
+
+<p align="center">
+  <img src="./assets/readme/architecture.svg" width="100%" alt="MCP clients call dsh-baton-mcp over stdio; it reaches the dsh-baton-host plugin inside Harness through an owner-only local socket; the plugin drives Harness sessions live, with dsh headless as fallback">
+</p>
+
+<p align="center">
+  <img src="./assets/readme/comparison.svg" width="100%" alt="Plugin vs headless: only the plugin shows runs live in the Harness UI, continues desktop sessions and uses desktop agent presets; both reuse the desktop sign-in">
+</p>
+
+## Tools
+
+<p align="center">
+  <img src="./assets/readme/tools.svg" width="100%" alt="Workspaces: list, create, rename. Sessions: list, read, activity, rename. Runs: send, status, wait, cancel, list runs">
+</p>
+
+<p align="center">
+  <img src="./assets/readme/states.svg" width="100%" alt="Run states: queued, running, waiting, completed, failed, cancelled, and interrupted when Harness restarts mid-run. A busy session takes followup (queued) or steer (interjects) messages">
+</p>
+
+<details>
+<summary>Full tool reference</summary>
+
+| Tool | What it does |
+|---|---|
+| `dsh_list_workspaces` | Workspaces in the Harness sidebar |
+| `dsh_create_workspace` | Register a folder as a workspace (creates the folder if missing); returns the existing one if already registered |
+| `dsh_list_sessions` | Sessions newest first, with title, folder and running state; filter by folder or text. Archived sessions are left out |
+| `dsh_read_session` | Recent prompts and replies of one session (with tool names); `archived: true` for an archived session |
+| `dsh_send` | Send a message: `session_id` continues that session; `cwd` or `workspace_id` starts a new one (a `cwd` that is not a workspace yet is registered first). Returns a `run_id` at once. In Harness the message is marked "Sent by Claude / ChatGPT from another chat". An archived session is refused: unarchive it in Harness, or start a new session |
+| `dsh_status` | Run progress: state, recent text and tool calls, final reply; `waiting_on` when the turn is over but sub-agents or jobs still run; `human_interjections` when someone typed in the Harness UI mid-run; state `interrupted` for a run cut short by a Harness restart |
+| `dsh_wait` | Wait for the run to end: up to 270 s per call for Codex, 50 s for other clients. Still going: returns `timed_out` with just the state; call it again. Clients that can wait in the background use `dsh_send`'s `wait_command` instead. `dsh_status` is a one-off look, not a way to wait |
+| `dsh_session_activity` | What a session is doing now: running turn, sub-agents (any depth), background jobs; `archived: true` for an archived session |
+| `dsh_cancel` | Stop everything a session is doing, by `run_id` or `session_id`: turn, sub-agents, jobs (queued messages stay) |
+| `dsh_rename_session` | Rename a session |
+| `dsh_rename_workspace` | Rename a workspace (sidebar title only; the folder is not moved) |
+| `dsh_list_runs` | Recent runs |
+
+</details>
+
+## CLI
+
+```bash
+dsh-baton workspaces
+dsh-baton new-workspace ~/code/new-app --title "New App"
+dsh-baton sessions --cwd ~/code/new-app
+dsh-baton send --cwd ~/code/new-app "Scaffold the project"
+dsh-baton send --session session-xxxx "Next: add tests"
+dsh-baton send --session session-xxxx --mode steer "Interjection: don't change the API"
+dsh-baton wait hrun-xxxx              # blocks, prints the final reply; exit 0 on success
+dsh-baton status hrun-xxxx
+dsh-baton activity session-xxxx       # running turn, sub-agents, background jobs
+dsh-baton cancel --session session-xxxx
+dsh-baton rename session-xxxx "New title"
+dsh-baton rename-workspace ~/code/new-app "New name"
+```
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `DSH_BATON_BACKEND` | `auto` | `auto`, `host` or `headless` |
+| `DSH_BATON_HOME` | `~/.dsh-baton` | Socket and headless run records |
+| `DSH_BATON_SOCKET` | `$DSH_BATON_HOME/host.sock` | Plugin socket path (must match on both sides); on Windows mapped to a per-user named pipe |
+| `DSH_BATON_WAIT_S` | `270` for Codex, else `50` | How long one `dsh_wait` call waits; set it only if you raised the client's tool timeout, and keep it below that |
+| `DSH_BIN` | the `dsh` inside the macOS app, else `PATH` | Harness CLI for headless mode |
+| `DSH_HOME` | `~/.dsh` | Harness data folder (headless session reads) |
+| `DSH_BATON_ACCOUNT` | `1` | `0` uses the API-key route in headless mode |
+| `DSH_BATON_PATCHES` | empty | Extra headless `--patch` overlays, `:`-separated |
+
+<details>
+<summary>Headless fallback details</summary>
+
+When the plugin is unreachable, the MCP server falls back to Harness's `dsh headless` command. It can only continue sessions it created itself (headless does not load agent presets such as `standard`), and new sessions do not appear in the desktop sidebar. By default [`patches/account.patch.yml`](patches/account.patch.yml) reuses the desktop app's DeepSeek account sign-in, so no API key is needed.
+
+</details>
+
+## Security and limits
+
+<p align="center">
+  <img src="./assets/readme/security.svg" width="100%" alt="Owner-only channel (socket 0600 on macOS and Linux, per-user named pipe on Windows), no network port, Harness sandbox and approvals apply">
+</p>
+
+<p align="center">
+  <img src="./assets/readme/limits.svg" width="100%" alt="Good to know: a message typed in the UI mid-run is flagged on the run as a human interjection, run records survive a Harness restart (cut-short runs show interrupted), Claude Code is woken once when a run ends and Codex waits up to 270 s per call">
+</p>
+
+Any process running as your OS user can drive Harness through the socket, the same as running `dsh` directly. dsh-baton relies on Harness 0.2.1-series internal service APIs, so a major Harness update may need a follow-up release.
+
+<p align="center"><a href="docs/demos.md">More demos →</a></p>
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,189 @@
+<p align="center">
+  <img src="./assets/readme/zh/hero.gif" width="100%" alt="dsh-baton：让 Claude Code 或 Codex 把接力棒交给 DeepSeek Harness，界面实时可见，跑完那一刻就交回给你">
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> | 中文 · 非官方项目，与 DeepSeek 无关。
+</p>
+
+<p align="center">
+  macOS · Windows（<a href="WINDOWS.md">说明</a>）· Node.js ≥ 22.15 · 零依赖 · MIT
+</p>
+
+<p align="center">
+  <img src="./assets/readme/zh/features.svg" width="100%" alt="新建工作区和对话、续接指定对话、界面实时可见并标明发送方、完成即唤醒、不用另配 key、macOS 和 Windows 零依赖">
+</p>
+
+<p align="center">
+  <img src="./assets/readme/zh/flow.gif" width="100%" alt="典型流程：新建工作区、派发任务、后台等待、在同一个对话里续接追问">
+</p>
+
+## 实际演示
+
+一个 Codex 对话里完成新建、排队、插队和等待：
+
+<p align="center">
+  <img src="./assets/demos/s3-queue-zh.gif" width="100%" alt="左边 Codex 给 DeepSeek 派任务，再排队一条追问、插队修改正在跑的任务并等待；右边 DeepSeek Harness 实时执行">
+</p>
+
+Codex 和 Claude 轮流往同一个 Harness 对话发消息，每条都标明是谁发的：
+
+<p align="center">
+  <img src="./assets/demos/s8-relay-zh-zoom.gif" width="100%" alt="Harness 对话里 Codex 和 Claude 的消息交替出现，每条都带“由 ChatGPT / Claude 从另一个聊天发送”的标签">
+</p>
+
+<p align="center"><a href="docs/demos.zh-CN.md">更多演示 →</a></p>
+
+## 快速上手
+
+<p align="center">
+  <img src="./assets/readme/zh/install.svg" width="100%" alt="第一步：运行 npx -y dsh-baton-mcp setup。第二步：Harness → 插件 → 添加插件 → 粘贴 → 安装 → 立即启用。第三步：新开对话，让它调用 dsh_list_workspaces">
+</p>
+
+需要：DeepSeek Harness ≥ 0.2.1-rc.2 并已登录；Node.js ≥ 22.15。Windows 见 [WINDOWS.md](WINDOWS.md)。
+
+**1. 运行 setup**，在终端里：
+
+```bash
+npx -y dsh-baton-mcp setup
+```
+
+dsh-baton 没有任何依赖。`setup` 会把自己复制到 `~/.dsh-baton/app` 这个固定的文件夹（npx 的缓存目录会变），然后在用户级别给 Claude Code 和 Codex 注册一次 MCP 服务器：之后在任何文件夹新开的对话都有 `dsh_*` 工具。它直接写 `~/.claude.json` 和 `~/.codex/config.toml`（各留一份 `*.bak-dsh-baton` 备份），所以只装了桌面应用、`claude` / `codex` 不在 `PATH` 里也能用。重复运行也没问题。
+
+**2. 在 Harness 里粘贴。**`setup` 已经把插件文件夹路径复制到剪贴板：
+
+**插件** → **添加插件** → 粘贴 → **安装** → **立即启用**
+
+**3. 检查。**在 Claude Code 或 Codex 里**新开**一个对话，让它调用 `dsh_list_workspaces`，应该会列出你的 Harness 工作区。
+
+**也可以让 Claude Code 或 Codex 帮你装：** 发给它 *"运行 `npx -y dsh-baton-mcp setup`，然后告诉我它提示的 Harness 那一步。"*
+
+**各客户端怎么等待**（不需要配置）：
+- **Claude Code** 在后台等待任务（`dsh_send` 返回的 `wait_command`），任务结束时只被唤醒一次。
+- **Codex** 在 `dsh_wait` 里等待，每次最多 270 秒，刚好低于它 300 秒的工具超时。没做完时只返回状态，Codex 会直接再调用，不会去总结进度。Codex 不会收到 `wait_command`：它的终端无法在命令结束时唤醒它，只能轮询。
+- Codex 调用 MCP 工具时会请你批准，批准 `dsh-baton` 的工具即可；无人值守的 `codex exec` 加上 `--approve-for-me`。
+
+**更新：** 再运行一次 `npx -y dsh-baton-mcp@latest setup`，然后重启 Harness 以加载插件改动；新开的对话会用上 MCP 服务器的改动。
+
+**卸载：** `npx -y dsh-baton-mcp setup --remove`，再到 Harness → 插件 → dsh-baton-host → 卸载，最后再运行一次 `setup --remove` 删除 `~/.dsh-baton/app`。
+
+**从 dsh-bridge 升级：**照上面运行 `setup`。它会替换掉旧的 `dsh-bridge` MCP 注册；在 Harness 里先卸载 `dsh-bridge-host`，再添加新路径。`DSH_BRIDGE_*` 环境变量和已有的 `~/.dsh-bridge` 文件夹暂时继续可用。工具前缀变成 `mcp__dsh-baton__…`，权限白名单里写了旧前缀的要改一下。
+
+**从源码安装**（想跟进 `main` 或改代码）：`git clone https://github.com/JialaoLiu/dsh-baton.git`，再运行 `node dsh-baton/src/cli.mjs setup`。这时 setup 注册的就是克隆目录本身，更新用 `git pull`。
+
+<details>
+<summary>手动注册与 Claude 桌面应用</summary>
+
+`setup` 写入的内容和下面两条命令等价（用 `node` 的绝对路径，因为桌面应用启动 MCP 服务器时没有你 shell 的 `PATH`）：
+
+```bash
+claude mcp add dsh-baton -s user -- "$(command -v node)" "$PWD/dsh-baton/src/server.mjs"
+codex mcp add dsh-baton -- "$(command -v node)" "$PWD/dsh-baton/src/server.mjs"
+```
+
+`-s user` 很关键：不加的话，Claude Code 只给当前项目文件夹注册。
+
+**Claude 桌面应用（可选）**：聊天应用的连接器（和 Claude Code 是两回事），把下面这段加到 `~/Library/Application Support/Claude/claude_desktop_config.json`，然后重启应用，会显示为 "Local dev" 连接器。
+
+```json
+{ "mcpServers": { "dsh-baton": { "command": "/node 的绝对路径", "args": ["/dsh-baton 的绝对路径/src/server.mjs"] } } }
+```
+
+</details>
+
+## 工作原理
+
+<p align="center">
+  <img src="./assets/readme/zh/architecture.svg" width="100%" alt="MCP 客户端通过 stdio 调用 dsh-baton-mcp，再经仅当前用户可访问的本地套接字连到 Harness 里的 dsh-baton-host 插件，插件驱动 Harness 的对话并实时显示；插件不可用时退回 dsh headless">
+</p>
+
+<p align="center">
+  <img src="./assets/readme/zh/comparison.svg" width="100%" alt="插件和 headless 对比：只有插件能在 Harness 界面实时可见、续接桌面版的对话、使用桌面版智能体预设；两者都沿用桌面版登录">
+</p>
+
+## 工具
+
+<p align="center">
+  <img src="./assets/readme/zh/tools.svg" width="100%" alt="工作区：列出、新建、改名。对话：列出、读取、当前活动、改名。运行：发送、状态、等待、取消、列出最近运行">
+</p>
+
+<p align="center">
+  <img src="./assets/readme/zh/states.svg" width="100%" alt="运行状态：queued、running、waiting、completed、failed、cancelled，Harness 中途重启则为 interrupted。对话正忙时，followup 进排队栏，steer 在下一步插话">
+</p>
+
+<details>
+<summary>完整工具说明</summary>
+
+| 工具 | 作用 |
+|---|---|
+| `dsh_list_workspaces` | 列出 Harness 侧边栏里的工作区 |
+| `dsh_create_workspace` | 把一个文件夹登记为工作区（文件夹不存在会先创建）；已登记的直接返回原来那个 |
+| `dsh_list_sessions` | 列出对话（最新在前），带标题、目录、是否在跑；可按目录或关键字过滤。已归档的对话不会列出 |
+| `dsh_read_session` | 读某个对话最近的消息和回复（含用到的工具名）；已归档的对话会带 `archived: true` |
+| `dsh_send` | 发消息。带 `session_id` 续接那个对话；带 `cwd` 或 `workspace_id` 新开对话（`cwd` 还不是工作区时会先登记）。立即返回 `run_id`。Harness 里这条消息会标注「由 Claude / ChatGPT 从另一个聊天发送」。已归档的对话会被拒绝：先在 Harness 里取消归档，或新开对话 |
+| `dsh_status` | 查看运行进度：状态、最近的文字和工具调用、最终回复；回合结束但子智能体/后台任务还在跑时给出 `waiting_on`；中途有人在 Harness 界面里发消息时给出 `human_interjections`；被 Harness 重启打断的任务状态为 `interrupted` |
+| `dsh_wait` | 等运行结束：Codex 每次最多等 270 秒，其他客户端 50 秒。没做完会带 `timed_out`，只返回状态，再调用一次即可。能在后台等待的客户端改用 `dsh_send` 返回的 `wait_command`。`dsh_status` 只用来看一眼，不用来等待 |
+| `dsh_session_activity` | 对话此刻在做什么：正在跑的回合、子智能体（任意层级）、后台任务；已归档的对话会带 `archived: true` |
+| `dsh_cancel` | 按 `run_id` 或 `session_id` 停掉整个对话的工作：当前回合、子智能体、后台任务（排队中的消息不会被删） |
+| `dsh_rename_session` | 给对话改名 |
+| `dsh_rename_workspace` | 给工作区改名（只改侧边栏标题，不动文件夹） |
+| `dsh_list_runs` | 列出最近的运行 |
+
+</details>
+
+## 命令行
+
+```bash
+dsh-baton workspaces
+dsh-baton new-workspace ~/code/new-app --title "New App"
+dsh-baton sessions --cwd ~/code/new-app
+dsh-baton send --cwd ~/code/new-app "搭项目骨架"
+dsh-baton send --session session-xxxx "继续：补上测试"
+dsh-baton send --session session-xxxx --mode steer "插话：先别改 API"
+dsh-baton wait hrun-xxxx              # 阻塞到结束，打印最终回复；成功退出码 0
+dsh-baton status hrun-xxxx
+dsh-baton activity session-xxxx       # 正在跑的回合、子智能体、后台任务
+dsh-baton cancel --session session-xxxx
+dsh-baton rename session-xxxx 新标题
+dsh-baton rename-workspace ~/code/new-app 新名字
+```
+
+（从源码运行时用 `node src/cli.mjs …`。）
+
+## 配置（环境变量）
+
+| 变量 | 默认值 | 作用 |
+|---|---|---|
+| `DSH_BATON_BACKEND` | `auto` | `auto`、`host` 或 `headless` |
+| `DSH_BATON_HOME` | `~/.dsh-baton` | 套接字和 headless 运行记录的位置 |
+| `DSH_BATON_SOCKET` | `$DSH_BATON_HOME/host.sock` | 插件套接字路径（插件和 MCP 两边要一致）；Windows 上映射为按用户区分的命名管道，见 [WINDOWS.md](WINDOWS.md) |
+| `DSH_BATON_WAIT_S` | Codex 为 `270`，其他为 `50` | 一次 `dsh_wait` 等多久；只有调大了客户端的工具超时才需要设，并且要小于那个超时 |
+| `DSH_BIN` | macOS 应用内的 `dsh`，否则查 `PATH` | headless 模式用的 Harness 命令行 |
+| `DSH_HOME` | `~/.dsh` | Harness 数据目录（headless 模式读取对话用） |
+| `DSH_BATON_ACCOUNT` | `1` | headless 模式下设为 `0` 则改用 API key 路线 |
+| `DSH_BATON_PATCHES` | 空 | headless 模式额外的 `--patch` 覆盖文件，用 `:` 分隔 |
+
+<details>
+<summary>headless 后备模式说明</summary>
+
+插件不可用时，MCP 服务器会自动改用 Harness 自带的 `dsh headless` 命令。它只能续接自己新建的对话，不能续接桌面版里建的对话（headless 不加载 `standard` 等智能体预设）；新建的对话也不会出现在桌面版侧边栏。默认通过 [`patches/account.patch.yml`](patches/account.patch.yml) 沿用桌面版的 DeepSeek 账号登录，不需要 API key。
+
+</details>
+
+## 安全与限制
+
+<p align="center">
+  <img src="./assets/readme/zh/security.svg" width="100%" alt="仅当前用户可连（macOS/Linux 用 0600 套接字，Windows 用按用户的命名管道），不开网络端口，沿用 Harness 的沙箱和审批">
+</p>
+
+<p align="center">
+  <img src="./assets/readme/zh/limits.svg" width="100%" alt="使用须知：任务进行中在界面里发的话会作为人工插话记到任务上；任务记录在 Harness 重启后还在，被打断的标为 interrupted；Claude Code 结束时唤醒一次，Codex 每次最多等 270 秒">
+</p>
+
+任何能以你的身份运行程序的进程都能通过这个套接字驱动 Harness，这和直接运行 `dsh` 的权限一样。本项目依赖 Harness 0.2.1 系列的内部服务接口，Harness 大版本更新后可能需要跟进。
+
+<p align="center"><a href="docs/demos.zh-CN.md">更多演示 →</a></p>
+
+## 许可证
+
+MIT

package/WINDOWS.md

@@ -0,0 +1,113 @@
+# dsh-baton on Windows
+
+dsh-baton runs on Windows 10/11 with the same tools and behaviour as on macOS. This page covers what differs and how to check that everything is connected.
+
+Verified on Windows 11 with DeepSeek Harness 0.2.1-rc.2 (desktop app), Node.js 22.23, Codex 0.163 and Claude Code 2.1.
+
+## What is different on Windows
+
+- **The control socket is a named pipe.** Node cannot listen on a Unix socket file on Windows. The plugin and the MCP server therefore map the socket path to a named pipe, `\\.\pipe\dsh-baton-<hash>`. The hash is taken from the path, `%USERPROFILE%\.dsh-baton\host.sock` by default, so every Windows user gets their own pipe.
+  - `DSH_BATON_HOME` / `DSH_BATON_SOCKET` still move it. A path is mapped the same way on both sides, and a value that is already `\\.\pipe\…` is used as is.
+  - There is no file to clean up: the pipe disappears when Harness exits.
+  - Access: Windows' default pipe security lets other standard users only read it, so they cannot drive Harness through it. Administrators and SYSTEM can, as with any process you run.
+- **The headless backend uses Harness's own CLI.** The desktop app ships no `dsh.exe`. Harness ≥ 0.2.1 has a launcher at `resources\runtime\cli\bin\dsh.cmd`; older builds only have the CLI packed in `resources\app.asar`, which runs on the app's own Electron binary. dsh-baton finds it automatically, in this order:
+  1. `DSH_BIN`, if set;
+  2. `dsh` on `PATH`, preferring `.exe` / `.cmd` / `.bat` over extensionless shims (Harness's "add dsh to PATH" setting puts `dsh.cmd` there);
+  3. the Harness install, either the default `%LOCALAPPDATA%\Programs\DeepSeek Harness` or any `InstallLocation` from the uninstall registry entries, so a custom folder such as `E:\Software\DeepSeek Harness` works. There its `dsh.cmd` launcher is used, or the packed CLI on older builds.
+
+  A `.cmd` launcher is started through `cmd.exe`.
+- **Cancelling stops the whole process tree** of that one run (`taskkill /PID <pid> /T /F`). It never kills by image name.
+
+## Install
+
+Requires DeepSeek Harness ≥ 0.2.1-rc.2 and Node.js ≥ 22.15. In PowerShell:
+
+```powershell
+npx -y dsh-baton-mcp setup
+```
+
+`setup` copies itself to `%USERPROFILE%\.dsh-baton\app` (npx's cache is not a stable place) and registers the MCP server once, user-wide, for Claude Code (`%USERPROFILE%\.claude.json`) and Codex (`%USERPROFILE%\.codex\config.toml`), with the absolute path of `node`. It edits the files directly, so it works with the desktop apps alone: their `claude.exe` / `codex.exe` are usually not on `PATH`. It also copies the plugin path to the clipboard.
+
+Then, in Harness: **Plugins / 插件** → **Add plugin / 添加插件** → paste the path it copied (`%USERPROFILE%\.dsh-baton\app\host`) → **Install / 安装** → **Enable now / 立即启用**. The pipe appears right away (see [Verify](#verify)); if it does not, restart Harness.
+
+Nothing else to configure: Claude Code waits for a run in the background (Git Bash runs the `wait_command` that `dsh_send` returns), and Codex waits up to 270 s per `dsh_wait` call, under its 300 s tool timeout. Approve the `dsh-baton` tools when Codex asks; for unattended `codex exec`, add `--approve-for-me`.
+
+Remove: `npx -y dsh-baton-mcp setup --remove`, then Harness → Plugins → dsh-baton-host → Uninstall, then `setup --remove` once more to delete the app folder.
+
+Upgrading from dsh-bridge: `setup` replaces the old MCP entries and reuses an existing `%USERPROFILE%\.dsh-bridge` (the app then goes to `.dsh-bridge\app`). Uninstall `dsh-bridge-host` in Harness, then add the path `setup` copied. With the hoisted profile layout, uninstalling may leave a `node_modules\dsh-bridge-host` link behind in `%USERPROFILE%\.dsh\profiles\desktop`; `setup --remove` deletes such a leftover link (old or new name) once the profile no longer lists the plugin.
+
+From source instead: `git clone https://github.com/JialaoLiu/dsh-baton.git C:\dev\dsh-baton` and `node C:\dev\dsh-baton\src\cli.mjs setup`; the plugin path is then `C:\dev\dsh-baton\host`.
+
+### If the Plugins page cannot uninstall or install it
+
+**Uninstall fails with `ERR_PNPM_UNEXPECTED_STORE`** ("Unexpected store location"), or Add plugin says the plugin is already installed (该插件已安装) while Uninstall fails. This happens when the profile was installed by an older Harness build that used another pnpm store. Move the profile onto the current store once, and the Plugins page works again:
+
+1. Quit Harness from its menu (应用 → 退出), including its tray icon.
+2. Rename `%USERPROFILE%\.dsh\profiles\desktop\node_modules` to keep it as a backup, for example `node_modules.old-store`.
+3. Reinstall the profile with Harness's bundled pnpm, without `--store-dir`. Set `$app` to your Harness folder, for example `E:\Software\DeepSeek Harness` for a custom install.
+
+   ```powershell
+   $app = "$env:LOCALAPPDATA\Programs\DeepSeek Harness"
+   $env:ELECTRON_RUN_AS_NODE = '1'
+   $env:DSH_DESKTOP_NODE_EXECUTABLE = "$app\DeepSeek Harness.exe"
+   $env:Path = "$app\resources\runtime\bin;$env:Path"
+   cd "$env:USERPROFILE\.dsh\profiles\desktop"
+   # Harness ≥ 0.2.1; older builds have it at resources\runtime\pnpm\bin\pnpm.mjs
+   $pnpm = "$app\resources\runtime\primary-runtime\dependencies\pnpm\bin\pnpm.mjs"
+   & "$app\DeepSeek Harness.exe" $pnpm install --frozen-lockfile
+   ```
+
+   Pass no `--store-dir` or `--config.node-linker`. If you do not rename `node_modules` first, pnpm wants exactly the `storeDir` and `nodeLinker` recorded in `node_modules\.modules.yaml` and aborts on any other value (`ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`). Recent profiles use `nodeLinker: hoisted` with the store under `%LOCALAPPDATA%\pnpm\store`.
+
+4. Start Harness. Plugins → dsh-baton-host → Uninstall now works; then Add plugin as above. A failed uninstall earlier may have left the plugin switched off: switch it on if so.
+
+`dsh plugin --profile desktop` cannot do this: it refuses with "profile "desktop" is managed exclusively by the Electron application".
+
+## Verify
+
+1. **The plugin is up.** Harness is running, and the pipe exists:
+
+   ```powershell
+   [IO.Directory]::GetFiles('\\.\pipe\') | Select-String dsh-baton
+   ```
+
+2. **The MCP server reaches it.** Run this from the repo:
+
+   ```powershell
+   node -e "import('./src/core.mjs').then(async c => { console.log(c.hostSocket()); console.log(await c.hostCall('ping')) })"
+   ```
+
+   It prints the same pipe and `{ name: 'dsh-baton-host', version: …, pid: … }`.
+3. **The clients see it, user-wide.** `claude mcp get dsh-baton` shows `Scope: User config` and `✓ Connected`, and `codex mcp list` shows `dsh-baton … enabled`. Start a new conversation: the `dsh_*` tools are there without reconnecting.
+4. **A real round trip.** Ask the client: *"Use dsh-baton: dsh_send with cwd C:\temp\dsh-test and message 'Reply with exactly one word: pong', then dsh_wait on the run_id."*
+   - It should come back `completed` with `pong`.
+   - The new session shows up under the `dsh-test` workspace in the Harness sidebar.
+
+## Headless backend (no plugin)
+
+`DSH_BATON_BACKEND=headless`, or `auto` when the plugin is not running, runs one-shot turns through the CLI described above.
+
+It needs credentials that the standalone CLI can read:
+- **Desktop account sign-in** (the default): the account must be signed in.
+- **API-key route** (`DSH_BATON_ACCOUNT=0`): needs `DEEPSEEK_API_KEY` in the environment, or stored through the web Models page.
+
+A key stored only in the desktop app's settings is not visible to the headless CLI. Without one, the run fails with `ACCOUNT_SIGN_IN_REQUIRED` or `MISSING_CREDENTIAL`. The host plugin route has no such requirement.
+
+## Tests
+
+```powershell
+npm test
+```
+
+The suite runs on Windows with named pipes. Two POSIX-only checks are skipped: file modes, and refusing a regular file at the socket path.
+
+---
+
+## 中文要点
+
+- **套接字改为命名管道。** Windows 上 Node 不能监听 Unix 套接字文件，所以同一路径被映射成按用户区分的命名管道 `\\.\pipe\dsh-baton-<哈希>`。插件和 MCP 两边算法一致，`DSH_BATON_SOCKET` 仍然可用，Harness 退出后管道自动消失。
+- **headless 用 Harness 自带的 CLI。** Harness ≥ 0.2.1 自带 `resources\runtime\cli\bin\dsh.cmd`；更早的版本只有打包在 `app.asar` 里的 CLI，由 Harness 自己的 exe 以 Node 模式运行。会按顺序自动查找：`DSH_BIN`、`PATH` 里的 `dsh`、默认安装位置，以及注册表里的自定义安装目录。
+- **插件用 Harness 插件页安装。** 插件 → 添加插件 → 粘贴 `%USERPROFILE%\.dsh-baton\app\host` → 安装 → 立即启用（`setup` 已把路径复制到剪贴板）。
+- **一条命令注册 MCP。** `npx -y dsh-baton-mcp setup` 把自己复制到 `%USERPROFILE%\.dsh-baton\app`，再直接写 Claude Code 和 Codex 的用户级配置（用 `node` 的绝对路径），桌面版的 `claude` / `codex` 不在 `PATH` 里也没关系。之后新开对话就有 `dsh_*` 工具；Codex 每次最多等 270 秒，不用再配超时。
+- **插件页卸不掉或装不上时**（`ERR_PNPM_UNEXPECTED_STORE`，或提示"该插件已安装"）：是旧版 Harness 装 profile 时用了另一个 pnpm store。一次性修好：从菜单退出 Harness，把 `%USERPROFILE%\.dsh\profiles\desktop\node_modules` 改名备份，用 Harness 自带的 pnpm 运行 `install --frozen-lockfile`（不加 `--store-dir`；`$app` 改成你的安装目录，比如 `E:\Software\DeepSeek Harness`），再启动 Harness，插件页的卸载和添加就正常了；如果插件被关掉了，记得重新打开。
+- **headless 需要独立凭据。** 要么登录账户，要么设置 `DEEPSEEK_API_KEY`。桌面版里保存的 Key，headless CLI 读不到。

package/host/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JialaoLiu
+
+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/host/README.md

@@ -0,0 +1,37 @@
+# dsh-baton-host
+
+DeepSeek Harness plugin for [dsh-baton](../README.md). It runs inside the Harness host (desktop app or `dsh web`) and serves a local, owner-only Unix socket (`~/.dsh-baton/host.sock`; a per-user named pipe on Windows, see [WINDOWS.md](../WINDOWS.md)). Through it, an MCP client can list and create workspaces, create sessions, continue a specific session, and wait for its turn to finish. All of this goes through Harness's own session controller, so the messages show up live in the Harness UI.
+
+DeepSeek Harness 插件，配合 [dsh-baton](../README.zh-CN.md) 使用。它运行在 Harness 内部，只开一个当前用户才能访问的本地套接字，让 MCP 客户端能新建工作区和对话、续接指定对话、等待任务完成。所有操作都走 Harness 官方会话服务，界面实时可见。
+
+## Install / 安装
+
+Harness → Plugins / 插件 → Add plugin / 添加插件 → `dsh-baton-host` → Install / 安装 → Enable now / 立即应用
+
+Then connect the MCP server / 然后接入 MCP 服务器: see [dsh-baton](../README.md).
+
+## Socket protocol / 套接字协议
+
+Newline-delimited JSON: request `{"id", "method", "params"}`, reply `{"id", "result"}` or `{"id", "error"}`.
+
+| Method | Params |
+|---|---|
+| `ping` | — |
+| `workspaces` | — |
+| `create_workspace` | `path`, `title?`, `create_dir?` (default `true`) |
+| `list_sessions` | `cwd?`, `query?`, `limit?` |
+| `read_session` | `session_id`, `last?` |
+| `send` | `message`, and `session_id` or `cwd` or `workspace_id`; `mode?` (`followup` \| `steer`) |
+| `status` | `run_id`, `tail?` |
+| `wait` | `run_id`, `timeout_s?` |
+| `activity` | `session_id` |
+| `cancel` | `run_id` or `session_id` |
+| `rename_session` | `session_id`, `title` |
+| `rename_workspace` | `workspace_id` or `path`, `title` |
+| `list_runs` | `limit?` |
+
+`DSH_BATON_SOCKET` / `DSH_BATON_HOME` in the Harness process environment move the socket.
+
+## License
+
+MIT

package/host/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh-baton-host bundle layer: mounts the single host plugin row.
+- insert:
+    - id: dsh-baton-host
+      name: dsh-baton-host