@tunnelbox/dsh-tunnelbox 0.1.0 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +144 -127
  2. package/cordis.patch.yml +5 -3
  3. package/dist/index.mjs +1664 -76
  4. package/package.json +8 -1
package/README.md CHANGED
@@ -1,127 +1,144 @@
1
- # @tunnelbox/dsh-tunnelbox
2
-
3
- tunnelbox 的 **DeepSeek Harness（dsh）原生 Cordis 插件**——跑在 dsh 进程内，让手机远程驱动完整的 DeepSeek Harness（agent/session/工具/审批/中止）。
4
-
5
- ```
6
- 手机 PWA ──WSS──► relay ──WSS──► 本插件（dsh 进程内） ──ctx.agents/session/approval──► DeepSeek Harness
7
- (dsh --profile tunnelbox)
8
- ```
9
-
10
- ## 与旧实现（plugin/dsh 外部桥）的区别
11
-
12
- | | 旧：`plugin/dsh`（外部进程桥） | 新：`@tunnelbox/dsh-tunnelbox`（原生插件） |
13
- |---|---|---|
14
- | 形态 | `node dist/index.js` 独立进程 + JSON-RPC 驱动 `sdk-minimal` | `dsh --profile tunnelbox` 进程内 Cordis 插件 |
15
- | 能力位 | streaming/thinking ✅；permission ❌；abort ❌ | **全部 true**（permission/abort 原生支持） |
16
- | 审批 | 无（sdk-minimal 固定 danger-full-access） | `ctx.approval`（approval/request waterfall）→ 手机 `permission.request` |
17
- | 中止 | 无 | `agent.cancel({kind:"user"})` |
18
- | 工具 | 黑盒透传 | `ctx.tools`/`ctx.shell`/`ctx.fs` 等 harness 全部服务 |
19
- | 配置 | 环境变量 | schemastery Schema + cordis.yml，支持 HMR |
20
- | 会话 | 直读 JSONL | `ctx.sessions` + 持久化；JSONL 仅做列表/历史 |
21
-
22
- ## 能力位（agent.info.capabilities）
23
-
24
- | 能力 | 值 | 实现 |
25
- |---|---|---|
26
- | streaming | true | `ctx.on("session/event")` → `message.part`（delta） |
27
- | thinking | true | `reasoning-delta` → thinking 部件 |
28
- | permission | **true** | `approval/request` → 手机审批 → `allowed-once/rejected`（超时 fail-closed） |
29
- | commands | true | 适配器命令 `/new` `/help` |
30
- | abort | **true** | `agent.cancel` → 前端「停止」 |
31
-
32
- ## 目录结构
33
-
34
- ```
35
- plugin/dsh-tunnelbox/
36
- ├── package.json # dsh.bundle.patch 声明
37
- ├── cordis.patch.yml # 插件层（install 时并入 profile）
38
- ├── scripts/build.mjs # esbuild 打包 → dist/index.mjs（external @deepseek-ai/*）
39
- └── src/
40
- ├── index.ts # 插件入口（name/inject/Config/apply）
41
- ├── bridge.ts # relay 连接 + 协议 ↔ harness 映射 + Agent 生命周期
42
- ├── map.ts # 会话事件 → Part/ChatMessage 映射（复用旧桥逻辑）
43
- ├── sessions.ts # JSONL 会话列表/历史/删除
44
- └── shims.d.ts # @deepseek-ai/* 宽松类型声明
45
- ```
46
-
47
- ## 构建
48
-
49
- ```bash
50
- cd plugin && npm install # workspaces 根（含 dsh-tunnelbox）
51
- cd dsh-tunnelbox && npm run build # 产出 dist/index.mjs
52
- ```
53
-
54
- ## 安装到 dsh profile
55
-
56
- ```bash
57
- dsh plugin --profile tunnelbox add ./plugin/dsh-tunnelbox # pnpm link + 追加 bundles
58
- dsh --profile tunnelbox --dump-config # 确认 tunnelbox-dsh 层
59
- ```
60
-
61
- > profile 目录：`$DSH_HOME/profiles/tunnelbox/`，bundles = `@deepseek-ai/dsh-base` + `@tunnelbox/dsh-tunnelbox`。
62
-
63
- ## 运行
64
-
65
- ```bash
66
- export DSH_HOME=... # dsh home（默认 ~/.dsh，含凭证/会话）
67
- dsh --profile tunnelbox # 启动 harness + 插件 → 连接中继 → 打印二维码
68
- ```
69
-
70
- - 凭证：dsh 的 `credentials` 服务自动读 `$DSH_HOME/.credentials.yaml`（无需手动传 key）；
71
- - 模型/工作目录可在 profile 的 cordis.yml 配置，或环境变量覆盖。
72
-
73
- ## 配置（Schema）
74
-
75
- | 字段 | 默认 | 说明 |
76
- |---|---|---|
77
- | `relayUrl` | `""`（取 remote-state.dsh.json） | tunnelbox 中继地址 |
78
- | `provider` | `deepseek-official` | LLM provider |
79
- | `model` | `deepseek-v4-flash` | 模型 |
80
- | `cwd` | `process.cwd()` | agent 工作目录（会话按 workspace 分目录持久化） |
81
-
82
- 示例（profile 的 cordis.patch.yml 覆盖）：
83
-
84
- ```yaml
85
- - id: tunnelbox-dsh
86
- config:
87
- relayUrl: 'wss://chat.example.com'
88
- model: 'deepseek-v4-flash'
89
- cwd: 'D:/workspace/project'
90
- ```
91
-
92
- ## 协议映射（与 adapter 接口规范 v0.2 一致）
93
-
94
- | 手机消息 | 处理 |
95
- |---|---|
96
- | `session.prompt` | `ensureAgent(sessionID)`（无文件则 create / 有则 resume）→ `agent.followup(createUserMessage(text))` |
97
- | `session.messages` | 活动会话：`eventsToMessages(session.events)`；否则读 JSONL |
98
- | `session.list` | JSONL 扫描 + 活动会话合并 |
99
- | `session.create` | 返回占位（首次 prompt 落盘） |
100
- | `session.delete` | `handle.dispose()` + 删 JSONL |
101
- | `session.abort` | `agent.cancel({kind:"user"})` |
102
- | `permission.reply` | 解析 pending 审批 → `allowed-once/rejected` + 回执 `permission.replied` |
103
- | 流式 | `session/event` → `streamEventTo` → `message.part` |
104
-
105
- ## 安全
106
-
107
- - 审批策略由 `@deepseek-ai/dsh-base` 的 `approval`/`sandbox-policy` 决定（默认 `workspace-write` + `ask`）；
108
- 如需全放开：`DSH_PERMISSION_MODE=danger-full-access`（此时审批 policy 为 `never`，手机端不再弹卡）。
109
- - 手机端发 `session.prompt` 即驱动 dsh 在配置的 `cwd` 内工作，请勿把敏感工程目录暴露给不受信手机。
110
-
111
- ## 备注
112
-
113
- - 旧 `plugin/dsh`（sdk-minimal 外部桥）已删除，本插件是唯一的 dsh 集成方式；
114
- - 若 dsh 线协议/事件结构变化，仅需升级 `@tunnelbox/dsh-tunnelbox`（依赖 harness 原生事件，天然跟随 dsh 版本）。
115
-
116
- ## 多 agent 隔离
117
-
118
- 每个 `dsh --profile <name>` 是独立进程，天然隔离（不同 profile 可配不同 cwd/模型/工具集/审批策略）。同机跑多个：
119
-
120
- ```bash
121
- # 实例 A：工程目录 + workspace-write 审批
122
- DSH_HOME=~/.dsh-a dsh --profile tunnelbox --patch ./a.patch.yml
123
- # 实例 B：另一工程目录 + danger-full-access
124
- DSH_HOME=~/.dsh-b DSH_PERMISSION_MODE=danger-full-access dsh --profile tunnelbox --patch ./b.patch.yml
125
- ```
126
-
127
- 手机端每个实例按 `type=dsh` + 独立 agentID（各自 `remote-state.dsh.json`）区分。
1
+ # @tunnelbox/dsh-tunnelbox
2
+
3
+ tunnelbox 的 **DeepSeek Harness（dsh）原生 Cordis 插件**——跑在 dsh 进程内，让手机远程驱动完整的 DeepSeek Harness（agent/session/工具/审批/中止）。
4
+
5
+ ```
6
+ 手机 PWA ──WSS──► relay ──WSS──► 本插件（dsh 进程内） ──ctx.agents/session/approval──► DeepSeek Harness
7
+ (dsh --profile tunnelbox)
8
+ ```
9
+
10
+ ## 与旧实现（plugin/dsh 外部桥）的区别
11
+
12
+ | | 旧：`plugin/dsh`（外部进程桥） | 新：`@tunnelbox/dsh-tunnelbox`（原生插件） |
13
+ |---|---|---|
14
+ | 形态 | `node dist/index.js` 独立进程 + JSON-RPC 驱动 `sdk-minimal` | `dsh --profile tunnelbox` 进程内 Cordis 插件 |
15
+ | 能力位 | streaming/thinking ✅；permission ❌；abort ❌ | **全部 true**（permission/abort 原生支持） |
16
+ | 审批 | 无（sdk-minimal 固定 danger-full-access） | `ctx.approval`（approval/request waterfall）→ 手机 `permission.request` |
17
+ | 中止 | 无 | `agent.cancel({kind:"user"})` |
18
+ | 工具 | 黑盒透传 | `ctx.tools`/`ctx.shell`/`ctx.fs` 等 harness 全部服务 |
19
+ | 配置 | 环境变量 | schemastery Schema + cordis.yml，支持 HMR |
20
+ | 会话 | 直读 JSONL | `ctx.sessions` + 持久化；JSONL 仅做列表/历史 |
21
+
22
+ ## 能力位（agent.info.capabilities）
23
+
24
+ | 能力 | 值 | 实现 |
25
+ |---|---|---|
26
+ | streaming | true | `ctx.on("session/event")` → `message.part`（delta） |
27
+ | thinking | true | `reasoning-delta` → thinking 部件 |
28
+ | permission | **true** | `approval/request` → 手机审批 → `allowed-once/rejected`（超时 fail-closed） |
29
+ | commands | true | 适配器命令 `/new` `/help` |
30
+ | abort | **true** | `agent.cancel` → 前端「停止」 |
31
+
32
+ ## 目录结构
33
+
34
+ ```
35
+ plugin/dsh-tunnelbox/
36
+ ├── package.json # dsh.bundle.patch 声明
37
+ ├── cordis.patch.yml # 插件层（install 时并入 profile）
38
+ ├── scripts/build.mjs # esbuild 打包 → dist/index.mjs（external @deepseek-ai/*）
39
+ └── src/
40
+ ├── index.ts # 插件入口（name/inject/Config/apply）
41
+ ├── bridge.ts # relay 连接 + 协议 ↔ harness 映射 + Agent 生命周期
42
+ ├── map.ts # 会话事件 → Part/ChatMessage 映射（复用旧桥逻辑）
43
+ ├── sessions.ts # JSONL 会话列表/历史/删除
44
+ └── shims.d.ts # @deepseek-ai/* 宽松类型声明
45
+ ```
46
+
47
+ ## 构建
48
+
49
+ ```bash
50
+ cd plugin && npm install # workspaces 根（含 dsh-tunnelbox）
51
+ cd dsh-tunnelbox && npm run build # 产出 dist/index.mjs
52
+ ```
53
+
54
+ ## 安装到 dsh profile
55
+
56
+ ```bash
57
+ dsh plugin --profile tunnelbox add ./plugin/dsh-tunnelbox # pnpm link + 追加 bundles
58
+ dsh --profile tunnelbox --dump-config # 确认 tunnelbox-dsh 层
59
+ ```
60
+
61
+ > profile 目录：`$DSH_HOME/profiles/tunnelbox/`，bundles = `@deepseek-ai/dsh-base` + `@tunnelbox/dsh-tunnelbox`。
62
+
63
+ ## 运行
64
+
65
+ ```bash
66
+ export DSH_HOME=... # dsh home（默认 ~/.dsh，含凭证/会话）
67
+ dsh --profile tunnelbox # 启动 harness + 插件 → 连接中继 → 打印二维码
68
+ ```
69
+
70
+ - 凭证：dsh 的 `credentials` 服务自动读 `$DSH_HOME/.credentials.yaml`（无需手动传 key）；
71
+ - 模型/工作目录可在 profile 的 cordis.yml 配置，或环境变量覆盖。
72
+
73
+ ## 构建与环境（中继默认注入）
74
+
75
+ 源码不含任何中继 URL 字面量。默认中继在**构建时**由 `--env` 选择注入（读取 `plugin/env/.env.*`）：
76
+
77
+ | 命令 | 对应环境 | 注入默认 |
78
+ |---|---|---|
79
+ | `npm run build:dev` | 开发 | 来自 `.env.development`（`ws://192.168.1.124:8081`） |
80
+ | `npm run build:test` | 测试 | 来自 `.env.test`（`wss://relay.wxngrok.com`） |
81
+ | `npm run build:prod` / `npm run build` | 生产（默认） | 来自 `.env.production`（`wss://relay.tunnelbox.top`） |
82
+
83
+ 运行期解析顺序：`TUNNELBOX_RELAY_URL` > profile 配置 `relayUrl` > 构建注入默认（缺省 production）。构建/安装到 profile 后零参数运行即连对应中继；切换环境需用对应命令重新构建并安装。
84
+
85
+ ## 配置（Schema）
86
+
87
+ | 字段 | 默认 | 说明 |
88
+ |---|---|---|
89
+ | `relayUrl` | `""`（见上：构建注入默认；运行可被 `TUNNELBOX_RELAY_URL` 或 profile 配置覆盖） | tunnelbox 中继地址 |
90
+ | `provider` | `deepseek-official` | LLM provider |
91
+ | `model` | `deepseek-v4-flash` | 模型 |
92
+ | `cwd` | `process.cwd()` | agent 工作目录（会话按 workspace 分目录持久化） |
93
+
94
+ profile 内可用 overlay 手动钉死（如 cordis.patch.yml）：
95
+
96
+ ```yaml
97
+ - id: tunnelbox-dsh
98
+ config:
99
+ relayUrl: 'ws://192.168.1.124:8081'
100
+ model: 'deepseek-v4-flash'
101
+ cwd: 'D:/workspace/project'
102
+ ```
103
+
104
+ ## 协议映射（与 adapter 接口规范 v0.2 一致）
105
+
106
+ | 手机消息 | 处理 |
107
+ |---|---|
108
+ | `session.prompt` | `ensureAgent(sessionID)`（无文件则 create / 有则 resume）→ `agent.followup(createUserMessage(text))` |
109
+ | `session.messages` | 活动会话：`eventsToMessages(session.events)`；否则读 JSONL |
110
+ | `session.list` | JSONL 扫描 + 活动会话合并 |
111
+ | `session.create` | 返回占位（首次 prompt 落盘） |
112
+ | `session.delete` | `handle.dispose()` + 删 JSONL |
113
+ | `session.abort` | `agent.cancel({kind:"user"})` |
114
+ | `permission.reply` | 解析 pending 审批 → `allowed-once/rejected` + 回执 `permission.replied` |
115
+ | 流式 | `session/event` → `streamEventTo` → `message.part` |
116
+
117
+ ## 安全
118
+
119
+ - 审批策略由 `@deepseek-ai/dsh-base` 的 `approval`/`sandbox-policy` 决定（默认 `workspace-write` + `ask`）；
120
+ 如需全放开：`DSH_PERMISSION_MODE=danger-full-access`（此时审批 policy 为 `never`，手机端不再弹卡）。
121
+ - 手机端发 `session.prompt` 即驱动 dsh 在配置的 `cwd` 内工作，请勿把敏感工程目录暴露给不受信手机。
122
+
123
+ ## 备注
124
+
125
+ - 旧 `plugin/dsh`（sdk-minimal 外部桥）已删除，本插件是唯一的 dsh 集成方式；
126
+ - 若 dsh 线协议/事件结构变化，仅需升级 `@tunnelbox/dsh-tunnelbox`（依赖 harness 原生事件，天然跟随 dsh 版本）。
127
+ - **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`）。本插件按运行环境自动选择应答方式：
128
+ - **remote（`dsh web`/api-remotes 在场，如 `--profile web` 与 web UI 共存）**：本插件作为 **typert Remote Event 客户端**接入官方多端广播——选择/审批在**手机与 dsh web 同显、谁答谁得**（官方网关先答先得，未答端自动收 cancel 静默移除）。手机作答经中继回插件再 `$events/result` 回网关；手机**忽略/关闭/超时 = 让位**（不干扰浏览器继续作答）；明确选择/允许/拒绝 = 决定（全局生效）。
129
+ - **local（headless `tunnelbox` profile）**：注册**本地瀑布应答者**（手机唯一作答）：手机在线且归属可路由 → 推送 `question.request`/`permission.request`，作答回填；离线 → `next()` 委托（headless 无其它应答者即按官方 fail/NO_PROVIDER）。
130
+ - 旧版 `registerProvider` 单 provider 槽位与 host-apiproxy `events.mux` 已在官方运行时移除，本插件不再使用。
131
+ - 升级 dsh 时注意把 `package.json` 的 `@deepseek-ai/*` peerDependencies 对齐到实际运行时版本（当前机器为 `0.1.2-rc.1`）。
132
+
133
+ ## 多 agent 隔离
134
+
135
+ 每个 `dsh --profile <name>` 是独立进程，天然隔离（不同 profile 可配不同 cwd/模型/工具集/审批策略）。同机跑多个：
136
+
137
+ ```bash
138
+ # 实例 A：工程目录 + workspace-write 审批
139
+ DSH_HOME=~/.dsh-a dsh --profile tunnelbox --patch ./a.patch.yml
140
+ # 实例 B：另一工程目录 + danger-full-access
141
+ DSH_HOME=~/.dsh-b DSH_PERMISSION_MODE=danger-full-access dsh --profile tunnelbox --patch ./b.patch.yml
142
+ ```
143
+
144
+ 手机端每个实例按 `type=dsh` + 独立 agentID（各自 `remote-state.dsh.json`）区分。
package/cordis.patch.yml CHANGED
@@ -1,3 +1,5 @@
1
- - insert:
2
- - id: tunnelbox-dsh
3
- name: '@tunnelbox/dsh-tunnelbox'
1
+ - insert:
2
+ - id: tunnelbox-dsh
3
+ name: '@tunnelbox/dsh-tunnelbox'
4
+ - id: tool-ask-user
5
+ name: '@deepseek-ai/dsh-tool-ask-user'