@tunnelbox/dsh-tunnelbox 0.1.3 → 0.1.4

package/README.md

@@ -1,144 +1,128 @@
-# @tunnelbox/dsh-tunnelbox
-
-tunnelbox 的 **DeepSeek Harness（dsh）原生 Cordis 插件**——跑在 dsh 进程内，让手机远程驱动完整的 DeepSeek Harness（agent/session/工具/审批/中止）。
-
-```
-手机 PWA ──WSS──► relay ──WSS──► 本插件（dsh 进程内） ──ctx.agents/session/approval──► DeepSeek Harness
-                                        (dsh --profile tunnelbox)
-```
-
-## 与旧实现（plugin/dsh 外部桥）的区别
-
-| | 旧：`plugin/dsh`（外部进程桥） | 新：`@tunnelbox/dsh-tunnelbox`（原生插件） |
-|---|---|---|
-| 形态 | `node dist/index.js` 独立进程 + JSON-RPC 驱动 `sdk-minimal` | `dsh --profile tunnelbox` 进程内 Cordis 插件 |
-| 能力位 | streaming/thinking ✅；permission ❌；abort ❌ | **全部 true**（permission/abort 原生支持） |
-| 审批 | 无（sdk-minimal 固定 danger-full-access） | `ctx.approval`（approval/request waterfall）→ 手机 `permission.request` |
-| 中止 | 无 | `agent.cancel({kind:"user"})` |
-| 工具 | 黑盒透传 | `ctx.tools`/`ctx.shell`/`ctx.fs` 等 harness 全部服务 |
-| 配置 | 环境变量 | schemastery Schema + cordis.yml，支持 HMR |
-| 会话 | 直读 JSONL | `ctx.sessions` + 持久化；JSONL 仅做列表/历史 |
-
-## 能力位（agent.info.capabilities）
-
-| 能力 | 值 | 实现 |
-|---|---|---|
-| streaming | true | `ctx.on("session/event")` → `message.part`（delta） |
-| thinking | true | `reasoning-delta` → thinking 部件 |
-| permission | **true** | `approval/request` → 手机审批 → `allowed-once/rejected`（超时 fail-closed） |
-| commands | true | 适配器命令 `/new` `/help` |
-| abort | **true** | `agent.cancel` → 前端「停止」 |
-
-## 目录结构
-
-```
-plugin/dsh-tunnelbox/
-├── package.json          # dsh.bundle.patch 声明
-├── cordis.patch.yml      # 插件层（install 时并入 profile）
-├── scripts/build.mjs     # esbuild 打包 → dist/index.mjs（external @deepseek-ai/*）
-└── src/
-    ├── index.ts          # 插件入口（name/inject/Config/apply）
-    ├── bridge.ts         # relay 连接 + 协议 ↔ harness 映射 + Agent 生命周期
-    ├── map.ts            # 会话事件 → Part/ChatMessage 映射（复用旧桥逻辑）
-    ├── sessions.ts       # JSONL 会话列表/历史/删除
-    └── shims.d.ts        # @deepseek-ai/* 宽松类型声明
-```
-
-## 构建
-
-```bash
-cd plugin && npm install          # workspaces 根（含 dsh-tunnelbox）
-cd dsh-tunnelbox && npm run build  # 产出 dist/index.mjs
-```
-
-## 安装到 dsh profile
-
-```bash
-dsh plugin --profile tunnelbox add ./plugin/dsh-tunnelbox   # pnpm link + 追加 bundles
-dsh --profile tunnelbox --dump-config                    # 确认 tunnelbox-dsh 层
-```
-
-> profile 目录：`$DSH_HOME/profiles/tunnelbox/`，bundles = `@deepseek-ai/dsh-base` + `@tunnelbox/dsh-tunnelbox`。
-
-## 运行
-
-```bash
-export DSH_HOME=...                # dsh home（默认 ~/.dsh，含凭证/会话）
-dsh --profile tunnelbox            # 启动 harness + 插件 → 连接中继 → 打印二维码
-```
-
-- 凭证：dsh 的 `credentials` 服务自动读 `$DSH_HOME/.credentials.yaml`（无需手动传 key）；
-- 模型/工作目录可在 profile 的 cordis.yml 配置，或环境变量覆盖。
-
-## 构建与环境（中继默认注入）
-
-源码不含任何中继 URL 字面量。默认中继在**构建时**由 `--env` 选择注入（读取 `plugin/env/.env.*`）：
-
-| 命令 | 对应环境 | 注入默认 |
-|---|---|---|
-| `npm run build:dev` | 开发 | 来自 `.env.development`（`ws://192.168.1.124:8081`） |
-| `npm run build:test` | 测试 | 来自 `.env.test`（`wss://relay.wxngrok.com`） |
-| `npm run build:prod` / `npm run build` | 生产（默认） | 来自 `.env.production`（`wss://relay.tunnelbox.top`） |
-
-运行期解析顺序：`TUNNELBOX_RELAY_URL` > profile 配置 `relayUrl` > 构建注入默认（缺省 production）。构建/安装到 profile 后零参数运行即连对应中继；切换环境需用对应命令重新构建并安装。
-
-## 配置（Schema）
-
-| 字段 | 默认 | 说明 |
-|---|---|---|
-| `relayUrl` | `""`（见上：构建注入默认；运行可被 `TUNNELBOX_RELAY_URL` 或 profile 配置覆盖） | tunnelbox 中继地址 |
-| `provider` | `deepseek-official` | LLM provider |
-| `model` | `deepseek-v4-flash` | 模型 |
-| `cwd` | `process.cwd()` | agent 工作目录（会话按 workspace 分目录持久化） |
-
-profile 内可用 overlay 手动钉死（如 cordis.patch.yml）：
-
-```yaml
-- id: tunnelbox-dsh
-  config:
-    relayUrl: 'ws://192.168.1.124:8081'
-    model: 'deepseek-v4-flash'
-    cwd: 'D:/workspace/project'
-```
-
-## 协议映射（与 adapter 接口规范 v0.2 一致）
-
-| 手机消息 | 处理 |
-|---|---|
-| `session.prompt` | `ensureAgent(sessionID)`（无文件则 create / 有则 resume）→ `agent.followup(createUserMessage(text))` |
-| `session.messages` | 活动会话：`eventsToMessages(session.events)`；否则读 JSONL |
-| `session.list` | JSONL 扫描 + 活动会话合并 |
-| `session.create` | 返回占位（首次 prompt 落盘） |
-| `session.delete` | `handle.dispose()` + 删 JSONL |
-| `session.abort` | `agent.cancel({kind:"user"})` |
-| `permission.reply` | 解析 pending 审批 → `allowed-once/rejected` + 回执 `permission.replied` |
-| 流式 | `session/event` → `streamEventTo` → `message.part` |
-
-## 安全
-
-- 审批策略由 `@deepseek-ai/dsh-base` 的 `approval`/`sandbox-policy` 决定（默认 `workspace-write` + `ask`）；
-  如需全放开：`DSH_PERMISSION_MODE=danger-full-access`（此时审批 policy 为 `never`，手机端不再弹卡）。
-- 手机端发 `session.prompt` 即驱动 dsh 在配置的 `cwd` 内工作，请勿把敏感工程目录暴露给不受信手机。
-
-## 备注
-
-- 旧 `plugin/dsh`（sdk-minimal 外部桥）已删除，本插件是唯一的 dsh 集成方式；
-- 若 dsh 线协议/事件结构变化，仅需升级 `@tunnelbox/dsh-tunnelbox`（依赖 harness 原生事件，天然跟随 dsh 版本）。
-- **ask-user 选择/提问 + 审批**：安装本插件即在其 bundle patch 里**自动挂载官方 `@deepseek-ai/dsh-tool-ask-user`**（`ask_user_question` 工具）。提问与审批是**同构的 agent-scoped 瀑布 seam**（dsh ≥0.1.2：`ctx.userQuestions.ask` → `user-questions/request`，审批为 `approval/request`）。本插件按运行环境自动选择应答方式：
-  - **remote（`dsh web`/api-remotes 在场，如 `--profile web` 与 web UI 共存）**：本插件作为 **typert Remote Event 客户端**接入官方多端广播——选择/审批在**手机与 dsh web 同显、谁答谁得**（官方网关先答先得，未答端自动收 cancel 静默移除）。手机作答经中继回插件再 `$events/result` 回网关；手机**忽略/关闭/超时 = 让位**（不干扰浏览器继续作答）；明确选择/允许/拒绝 = 决定（全局生效）。
-  - **local（headless `tunnelbox` profile）**：注册**本地瀑布应答者**（手机唯一作答）：手机在线且归属可路由 → 推送 `question.request`/`permission.request`，作答回填；离线 → `next()` 委托（headless 无其它应答者即按官方 fail/NO_PROVIDER）。
-  - 旧版 `registerProvider` 单 provider 槽位与 host-apiproxy `events.mux` 已在官方运行时移除，本插件不再使用。
-  - 升级 dsh 时注意把 `package.json` 的 `@deepseek-ai/*` peerDependencies 对齐到实际运行时版本（当前机器为 `0.1.2-rc.1`）。
-
-## 多 agent 隔离
-
-每个 `dsh --profile <name>` 是独立进程，天然隔离（不同 profile 可配不同 cwd/模型/工具集/审批策略）。同机跑多个：
-
-```bash
-# 实例 A：工程目录 + workspace-write 审批
-DSH_HOME=~/.dsh-a dsh --profile tunnelbox --patch ./a.patch.yml
-# 实例 B：另一工程目录 + danger-full-access
-DSH_HOME=~/.dsh-b DSH_PERMISSION_MODE=danger-full-access dsh --profile tunnelbox --patch ./b.patch.yml
-```
-
-手机端每个实例按 `type=dsh` + 独立 agentID（各自 `remote-state.dsh.json`）区分。
+# @tunnelbox/dsh-tunnelbox
+
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+**Official website:** [www.tunnelbox.top](https://www.tunnelbox.top)
+
+**tunnelbox DeepSeek Harness (dsh) plugin:** run dsh on your computer and drive it from your phone — agents, sessions, tools, approvals, abort. It runs **inside the dsh (Cordis) process** and dials **out** to a relay only (no public IP, no port forwarding).
+
+```
+Phone app ──WSS──► relay ──WSS──► this plugin (inside dsh) ──ctx.agents/session/approval──► DeepSeek Harness
+                                        (dsh --profile tunnelbox)
+```
+
+## Quick start (install → run → pair → use)
+
+Follow these steps once on a computer that has DeepSeek Harness installed.
+
+### Step 0 — Prepare your phone
+
+Install the tunnelbox App (Android & iOS) from the official website: **https://www.tunnelbox.top**
+
+- Sign in / create an account when prompted.
+
+### Step 1 — Install the plugin into a dsh profile
+
+```bash
+dsh plugin --profile tunnelbox add @tunnelbox/dsh-tunnelbox
+dsh --profile tunnelbox --dump-config        # optional: confirm the tunnelbox-dsh bundle layer
+```
+
+### Step 2 — Run dsh with the profile
+
+```bash
+dsh --profile tunnelbox
+```
+
+dsh starts the harness plus this plugin, which connects to the relay and prints a **pairing QR code + pairing code** in the terminal. Credentials are read automatically from `$DSH_HOME/.credentials.yaml` (default `~/.dsh/`).
+
+### Step 3 — Pair with your phone
+
+In the phone app tap **Scan to pair** and scan the QR (or type the pairing code manually). The code is single-use and valid for about 10 minutes.
+
+- Once bound, later starts print "connected account — open the app and pick this computer" and do not refresh the code. To unbind, see the app settings.
+
+### Step 4 — Use it from your phone
+
+In the app, open this computer and you can start agents/sessions, send messages, watch streaming output, approve tool requests, answer structured questions, and abort a running session.
+
+## Configuration
+
+The plugin is configured through the profile's `cordis.yml` (fields below) or env vars.
+
+| Field / env | Default | Description |
+|---|---|---|
+| `relayUrl` / `TUNNELBOX_RELAY_URL` | built-in default | tunnelbox relay address |
+| `provider` | `deepseek-official` | LLM provider |
+| `model` | `deepseek-v4-flash` | Model |
+| `cwd` | `process.cwd()` | Agent working directory (sessions persist per-workspace) |
+| `DSH_PERMISSION_MODE` | - | `danger-full-access` = full access (approval never prompts on the phone) |
+
+Example profile overlay (`cordis.patch.yml`):
+
+```yaml
+- id: tunnelbox-dsh
+  config:
+    relayUrl: 'wss://chat.example.com'
+    model: 'deepseek-v4-flash'
+    cwd: 'D:/workspace/project'
+```
+
+## Capabilities
+
+| Capability | Value | Notes |
+|---|---|---|
+| streaming | ✅ | dsh session events → live deltas |
+| thinking | ✅ | `reasoning-delta` → thinking parts |
+| permission | ✅ | dsh approval requests → phone approval card (timeout = fail-closed deny) |
+| commands | ✅ | `/new`, `/help` |
+| abort | ✅ | `agent.cancel` → phone stop button |
+| questions | ✅ | `ask_user_question` tool → structured phone question card |
+
+## Approvals & security
+
+- Approval policy is governed by dsh's `approval` / `sandbox-policy` (default `workspace-write` + ask). With both the dsh web UI and your phone present, approvals/questions show on both — whoever answers first decides (the other side is cancelled automatically).
+- `DSH_PERMISSION_MODE=danger-full-access` fully disables prompts (approval policy becomes `never`; no phone card).
+- Don't expose sensitive project directories to an untrusted phone.
+
+## Running multiple instances
+
+Each `dsh --profile <name>` is an independent process, naturally isolated (own cwd/model/tools/approval policy):
+
+```bash
+DSH_HOME=~/.dsh-a dsh --profile tunnelbox --patch ./a.patch.yml   # project A + workspace-write
+DSH_HOME=~/.dsh-b DSH_PERMISSION_MODE=danger-full-access dsh --profile tunnelbox --patch ./b.patch.yml
+```
+
+Each instance appears separately on the phone by `type=dsh` + its own agentID.
+
+## Multilingual
+
+User-visible output supports 8 languages (`zh-CN` / `zh-TW` / `en-US` / `ja-JP` / `ko-KR` / `fr-FR` / `de-DE` / `es-ES`). Resolution order: `TUNNELBOX_LANG` > saved `remote-state.dsh.json.lang` > system locale > `en-US`.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| No QR / pairing code on screen | Restart dsh; the plugin prints it at startup |
+| Plugin layer missing in the profile | `dsh plugin --profile tunnelbox add @tunnelbox/dsh-tunnelbox`, then `--dump-config` |
+| Phone asks for credentials/relay mismatch | Confirm `relayUrl` / `TUNNELBOX_RELAY_URL`; check `~/.tunnelbox/tunnelbox.log` |
+| Use your own relay | Set `relayUrl` in the profile config or `TUNNELBOX_RELAY_URL` |
+
+## State files
+
+- `~/.tunnelbox/remote-state.dsh.json` — agentID / relay / bound state / language
+- `~/.tunnelbox/remote-pairing.json` — latest pairing info
+- `~/.tunnelbox/tunnelbox.log` — plugin log
+
+## Uninstall
+
+```bash
+dsh plugin --profile tunnelbox remove @tunnelbox/dsh-tunnelbox
+```
+
+Remove `~/.tunnelbox` (all adapters' shared state) only if you no longer use any tunnelbox adapter.
+
+## Development
+
+Implementation details (protocol mapping, source layout, design decisions, untested items) are kept in the source repository as `DEV.md` next to this package, plus the protocol spec under the repo's `docs/`.

package/README.zh-CN.md

@@ -0,0 +1,128 @@
+# @tunnelbox/dsh-tunnelbox
+
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+**官网：** [www.tunnelbox.top](https://www.tunnelbox.top)
+
+**tunnelbox DeepSeek Harness（dsh）原生 Cordis 插件**：在电脑上运行 dsh，用手机远程驱动完整的 DeepSeek Harness——agent / session / 工具 / 审批 / 中止。它跑在 **dsh（Cordis）进程内**，只向中继发出站连接（无需公网 IP / 端口映射）。
+
+```
+手机 App ──WSS──► relay ──WSS──► 本插件（dsh 进程内） ──ctx.agents/session/approval──► DeepSeek Harness
+                                        (dsh --profile tunnelbox)
+```
+
+## 快速上手（安装 → 运行 → 配对 → 使用）
+
+在装有 DeepSeek Harness 的电脑上，按以下步骤操作一次即可。
+
+### 第 0 步 — 准备手机
+
+在官网下载并安装 tunnelbox App（Android / iOS 均已上架）：**https://www.tunnelbox.top**
+
+- 按提示登录/注册账号。
+
+### 第 1 步 — 安装插件到 dsh profile
+
+```bash
+dsh plugin --profile tunnelbox add @tunnelbox/dsh-tunnelbox
+dsh --profile tunnelbox --dump-config        # 可选：确认已含 tunnelbox-dsh 插件层
+```
+
+### 第 2 步 — 用该 profile 运行 dsh
+
+```bash
+dsh --profile tunnelbox
+```
+
+dsh 启动 harness 与本插件，插件连接中继并在终端打印**配对二维码 + 配对码**。凭证自动读取 `$DSH_HOME/.credentials.yaml`（默认 `~/.dsh/`）。
+
+### 第 3 步 — 与手机配对
+
+在手机 App 点「扫一扫配对」，扫描二维码（或手动输入配对码）。配对码一次性有效，约 10 分钟。
+
+- 绑定后，之后的启动会打印「已绑定账号，从手机「我的电脑」直接连接」，不再刷新码；换手机需先在 App 设置解绑。
+
+### 第 4 步 — 在手机上使用
+
+在 App 里打开这台电脑，即可启动 agent/会话、发消息、看流式输出、审批工具请求、回答结构化提问、中止运行中的会话。
+
+## 配置
+
+插件经 profile 的 `cordis.yml`（下列字段）或环境变量配置。
+
+| 字段 / 环境变量 | 默认 | 说明 |
+|---|---|---|
+| `relayUrl` / `TUNNELBOX_RELAY_URL` | 构建注入默认 | tunnelbox 中继地址 |
+| `provider` | `deepseek-official` | LLM provider |
+| `model` | `deepseek-v4-flash` | 模型 |
+| `cwd` | `process.cwd()` | agent 工作目录（会话按工作区分目录持久化） |
+| `DSH_PERMISSION_MODE` | - | `danger-full-access` = 全放开（审批不再弹手机卡） |
+
+profile overlay 示例（cordis.patch.yml）：
+
+```yaml
+- id: tunnelbox-dsh
+  config:
+    relayUrl: 'wss://chat.example.com'
+    model: 'deepseek-v4-flash'
+    cwd: 'D:/workspace/project'
+```
+
+## 能力位
+
+| 能力 | 值 | 说明 |
+|---|---|---|
+| streaming | ✅ | dsh 会话事件 → 实时增量 |
+| thinking | ✅ | `reasoning-delta` → thinking 部件 |
+| permission | ✅ | dsh 审批请求 → 手机审批卡（超时 fail-closed 拒绝） |
+| commands | ✅ | `/new`、`/help` |
+| abort | ✅ | `agent.cancel` → 前端「停止」 |
+| questions | ✅ | `ask_user_question` 工具 → 手机结构化提问卡 |
+
+## 审批与安全
+
+- 审批策略由 dsh 的 `approval` / `sandbox-policy` 决定（默认 `workspace-write` + ask）。当 dsh web UI 与手机同时在时，审批/提问两端同显——**谁先答谁得**，另一端自动取消。
+- `DSH_PERMISSION_MODE=danger-full-access` 完全关闭弹卡（approval policy 变 `never`，手机不再显示审批卡）。
+- 请勿把敏感工程目录暴露给不受信手机。
+
+## 多实例隔离
+
+每个 `dsh --profile <name>` 是独立进程，天然隔离（各自 cwd/模型/工具集/审批策略）：
+
+```bash
+DSH_HOME=~/.dsh-a dsh --profile tunnelbox --patch ./a.patch.yml   # 工程 A + workspace-write
+DSH_HOME=~/.dsh-b DSH_PERMISSION_MODE=danger-full-access dsh --profile tunnelbox --patch ./b.patch.yml
+```
+
+手机端每个实例按 `type=dsh` + 独立 agentID 区分。
+
+## 多语言
+
+用户可见输出支持 8 种语言（`zh-CN` / `zh-TW` / `en-US` / `ja-JP` / `ko-KR` / `fr-FR` / `de-DE` / `es-ES`）。解析顺序：`TUNNELBOX_LANG` > `remote-state.dsh.json` 的 `lang` > 系统 locale > 默认 `en-US`。
+
+## 故障排查
+
+| 问题 | 解决 |
+|---|---|
+| 没有二维码/配对码 | 重启 dsh；插件启动时会打印 |
+| profile 里没有插件层 | `dsh plugin --profile tunnelbox add @tunnelbox/dsh-tunnelbox`，再 `--dump-config` |
+| 手机连不上/中继不符 | 确认 `relayUrl` / `TUNNELBOX_RELAY_URL`；查看 `~/.tunnelbox/tunnelbox.log` |
+| 使用自建中继 | 在 profile 配置设 `relayUrl`，或设 `TUNNELBOX_RELAY_URL` |
+
+## 状态文件
+
+- `~/.tunnelbox/remote-state.dsh.json` — agentID / 中继地址 / 绑定状态 / 语言
+- `~/.tunnelbox/remote-pairing.json` — 最新配对信息
+- `~/.tunnelbox/tunnelbox.log` — 插件日志
+
+## 卸载
+
+```bash
+dsh plugin --profile tunnelbox remove @tunnelbox/dsh-tunnelbox
+```
+
+仅当不再使用任何 tunnelbox 适配器时，才删除 `~/.tunnelbox`（各适配器共享状态）。
+
+## 开发
+
+实现细节（协议映射、源码结构、决策记录、待实测项）保存在源码仓库中本包旁的 `DEV.md` 与仓库 `docs/` 下。

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@tunnelbox/dsh-tunnelbox",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "tunnelbox 的 dsh 原生 Cordis 插件：手机远程驱动 DeepSeek Harness（agent/session/tools/审批/中止）",
   "type": "module",
   "main": "./dist/index.mjs",
   "files": [
     "dist",
-    "cordis.patch.yml"
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh-CN.md"
   ],
   "publishConfig": {
     "access": "public"