@tunnelbox/claude-code 0.1.1 → 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.
- package/README.md +147 -120
- package/dist/index.mjs +1645 -242
- package/official-plugin/.claude-plugin/plugin.json +10 -10
- package/official-plugin/bin/tunnelbox +4 -4
- package/official-plugin/bin/tunnelbox.cmd +3 -3
- package/official-plugin/bin/tunnelbox.mjs +332 -274
- package/official-plugin/hooks/hooks.json +26 -16
- package/official-plugin/skills/pair/SKILL.md +12 -12
- package/official-plugin/skills/status/SKILL.md +10 -0
- package/package.json +42 -38
- package/official-plugin/commands/pair.md +0 -10
- package/official-plugin/commands/status.md +0 -9
package/README.md
CHANGED
|
@@ -1,120 +1,147 @@
|
|
|
1
|
-
# @tunnelbox/claude-code
|
|
2
|
-
|
|
3
|
-
tunnelbox 的 **Claude Code 适配器**（B 类，独立进程）：手机远程驱动电脑上的 Claude Code（会话/流式/工具审批/中止/删除），复用 `@tunnelbox/core`（RelayClient/状态/二维码）。
|
|
4
|
-
|
|
5
|
-
```
|
|
6
|
-
手机 PWA ──WSS──► relay ──WSS──► 本适配器（电脑上常驻 Node 进程）
|
|
7
|
-
└─ @anthropic-ai/claude-agent-sdk query()
|
|
8
|
-
└─ 拉起本机 claude CLI 子进程
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
## 前置条件
|
|
12
|
-
|
|
13
|
-
- Node.js ≥ 22（`RelayClient` 依赖全局 `WebSocket`）；
|
|
14
|
-
- 本机已安装并登录 **Claude Code CLI**（`claude --version` 可用、`~/.claude/.credentials.json` 存在）。SDK
|
|
15
|
-
|
|
16
|
-
> 适配器运行在**电脑**上，与 opencode/dsh 一样只向中继发出站 WebSocket；手机端无需安装任何 Claude SDK。
|
|
17
|
-
|
|
18
|
-
## 构建与运行
|
|
19
|
-
|
|
20
|
-
```bash
|
|
21
|
-
cd plugin && npm install # workspaces 根（含 claude-code 及 claude-agent-sdk）
|
|
22
|
-
cd claude-code && npm run build # 产出 dist/index.mjs
|
|
23
|
-
node dist/index.mjs # 或 npm start
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
|
35
|
-
|
|
36
|
-
| `
|
|
37
|
-
| `
|
|
38
|
-
| `
|
|
39
|
-
| `
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
##
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
-
|
|
86
|
-
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
1
|
+
# @tunnelbox/claude-code
|
|
2
|
+
|
|
3
|
+
tunnelbox 的 **Claude Code 适配器**（B 类，独立进程）：手机远程驱动电脑上的 Claude Code（会话/流式/工具审批/中止/删除），复用 `@tunnelbox/core`（RelayClient/状态/二维码）。
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
手机 PWA ──WSS──► relay ──WSS──► 本适配器（电脑上常驻 Node 进程）
|
|
7
|
+
└─ @anthropic-ai/claude-agent-sdk query()
|
|
8
|
+
└─ 拉起本机 claude CLI 子进程
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## 前置条件
|
|
12
|
+
|
|
13
|
+
- Node.js ≥ 22（`RelayClient` 依赖全局 `WebSocket`）；
|
|
14
|
+
- 本机已安装并登录 **Claude Code CLI**（`claude --version` 可用、`~/.claude/.credentials.json` 存在）。SDK 的 `query()` 会在本机拉起 `claude` 子进程——常驻长活模式下每个会话首次建立时拉起一次、跨轮复用（见「会话与工作区」）。
|
|
15
|
+
|
|
16
|
+
> 适配器运行在**电脑**上，与 opencode/dsh 一样只向中继发出站 WebSocket；手机端无需安装任何 Claude SDK。
|
|
17
|
+
|
|
18
|
+
## 构建与运行
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
cd plugin && npm install # workspaces 根（含 claude-code 及 claude-agent-sdk）
|
|
22
|
+
cd claude-code && npm run build # 产出 dist/index.mjs（默认注入 production 中继）
|
|
23
|
+
node dist/index.mjs # 或 npm start
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
本地连 dev 中继：`npm run build:dev` 后 `node dist/index.mjs`（构建已注入 `ws://192.168.1.124:8081`，无需再设环境变量）。
|
|
27
|
+
|
|
28
|
+
**配对引导（智能，无需任何环境变量）**：启动自动连接中继并以 relay 的真实绑定状态为准——**未绑定** → 自动申请配对码并打印二维码框引导配对；**已绑定** → 打印「已绑定账号，从手机「我的电脑」直接连接」，不重复刷码。需要随时再取一个码：`node dist/index.mjs --pair`（强制申请并打印一次，已绑定时附提示）。
|
|
29
|
+
|
|
30
|
+
> 首次运行时若 SDK 缺失会提示先 `npm install`。
|
|
31
|
+
|
|
32
|
+
## 配置
|
|
33
|
+
|
|
34
|
+
| 配置 | 默认 | 说明 |
|
|
35
|
+
|---|---|---|
|
|
36
|
+
| `TUNNELBOX_RELAY_URL` | state 里保存的地址（`~/.tunnelbox/remote-state.claude-code.json`） | 中继地址（如 `wss://chat.example.com`） |
|
|
37
|
+
| `TUNNELBOX_CWD` | `process.cwd()` | 默认工作区；也可在手机上通过工作区列表切换 |
|
|
38
|
+
| `TUNNELBOX_CLAUDE_MODE` | `default` | 每回合 `permissionMode`：`default/plan/acceptEdits/bypassPermissions/dontAsk/auto`。`bypassPermissions` 全放行且能力位 `permission=false`（危险，慎用）；该模式会同时设置 SDK 要求的 `allowDangerouslySkipPermissions=true`。`dontAsk`/`auto` 下未预批准的工具不会触发 `canUseTool`，手机审批通道基本不工作 |
|
|
39
|
+
| `TUNNELBOX_CLAUDE_MODEL` | claude 默认 | 模型覆盖（`options.model`） |
|
|
40
|
+
| `TUNNELBOX_CLAUDE_THINKING` | claude 默认 | `off \| adaptive \| enabled[:budget]` → `options.thinking` / `maxThinkingTokens` |
|
|
41
|
+
| `TUNNELBOX_CLAUDE_MAX_THINKING_TOKENS` | - | 思考 token 上限 |
|
|
42
|
+
| `TUNNELBOX_CLAUDE_ENV_*` | - | 透传给 claude 子进程的环境变量（前缀去掉，如 `TUNNELBOX_CLAUDE_ENV_ANTHROPIC_BASE_URL=…` → `options.env`）。**子进程 env 继承自适配器 `process.env`**（SDK `options.env` 是整体替换而非合并，适配器会自动并入 `process.env`，此配置仅在其上覆盖） |
|
|
43
|
+
| `TUNNELBOX_CLAUDE_DIALOG_KINDS` | 空 | `request_user_dialog` kind 白名单（逗号分隔，实验性，需实测后填真实 kind） |
|
|
44
|
+
| `TUNNELBOX_CLAUDE_ASK_USER_QUESTION` | 开 | Claude `AskUserQuestion`（模型向你提问）→ 手机**结构化提问卡**（question.request，多题/多选/自定义），作答后以 `allow+updatedInput.answers` 回填（实测该工具经 `canUseTool` 送达）；设 `0` 关闭（自动拒绝，不做审批） |
|
|
45
|
+
| `TUNNELBOX_CLAUDE_PLUGIN_DIR` | 包内 `official-plugin/` | 覆盖要加载的**官方 Claude Code 插件**目录（Agent SDK `options.plugins`） |
|
|
46
|
+
| `TUNNELBOX_CLAUDE_WARM` | 关 | （已停用）常驻长活会话天然免逐条冷启动，预热池不再参与驱动；保留 env 仅为兼容旧配置 |
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_CWD=D:/workspace/project \
|
|
50
|
+
TUNNELBOX_CLAUDE_MODE=default TUNNELBOX_CLAUDE_THINKING=adaptive node dist/index.mjs
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
> 模式为会话级：`session.prompt.agent:"plan"` 会把该会话切到 plan 模式，`"build"` 切回默认。
|
|
54
|
+
|
|
55
|
+
## 多语言
|
|
56
|
+
|
|
57
|
+
适配器用户可见输出遵循仓库硬性约定（8 语言 `zh-CN / zh-TW / en-US / ja-JP / ko-KR / fr-FR / de-DE / es-ES`；文案唯一数据源 `plugin/core/locales/*.json`，缺 key 回退 `en-US`）。**核心进程（`node dist/index.mjs`）输出已全量本地化**，随语言切换：
|
|
58
|
+
|
|
59
|
+
- **语言解析**：`TUNNELBOX_LANG` > `remote-state.claude-code.json` 的 `lang` > 系统 locale 检测 > 默认 `en-US`（`resolveLang`，`index.ts`/`bridge.ts` 一致）。
|
|
60
|
+
- **设置运行语言**（语言不打包，与 opencode 一致）：`npm run setup -- --lang en-US` 把语言写入 state（保留 agentID/绑定），之后 `node dist/index.mjs` 即按该语言输出；`--lang help` 列出支持语言：
|
|
61
|
+
```bash
|
|
62
|
+
npm run setup -- --lang en-US # 设为英文
|
|
63
|
+
npm run setup -- --lang zh-CN # 改回中文
|
|
64
|
+
npm run setup # 查看当前语言
|
|
65
|
+
```
|
|
66
|
+
- 已覆盖：启动横幅与参数告警（index）、连接/配对/断线/重连日志、`/help` 与会话标题、工作区错误、审批卡 prompt 与各类 fail-closed message、AskUserQuestion/结构化提问与对话框日志、MCP elicitation、会话/历史读取错误、工具结果截断提示等（`bridge.ts`/`sessions.ts`/`map.ts`/`dialog.ts`）。
|
|
67
|
+
- 终端配对框 `printPairing` 按同一语言输出。
|
|
68
|
+
- 官方插件 `bin/tunnelbox.mjs`（独立 `claude --plugin-dir` 会话的审批决策 message）为自包含纯源码分发（不经 esbuild，无法读 `core/locales`），内置精简双语字典（`zh-CN`/回退 `en-US`）。
|
|
69
|
+
|
|
70
|
+
## 能力位（agent.info.capabilities）
|
|
71
|
+
|
|
72
|
+
| 能力 | 值 | 实现 |
|
|
73
|
+
|---|---|---|
|
|
74
|
+
| streaming | true | `includePartialMessages` 流事件（text/thinking delta）→ `message.part` |
|
|
75
|
+
| thinking | true | 模型开启思考时 `thinking_delta` → thinking 部件 |
|
|
76
|
+
| permission | 默认 true | `canUseTool` → 手机审批（离线/断线/超时 fail-closed 拒绝）；`mode=bypassPermissions` 时为 false（不注册 canUseTool） |
|
|
77
|
+
| commands | true | 适配器命令 `/new` `/help` |
|
|
78
|
+
| abort | **true** | 手机 `session.abort` → 常驻 query `interrupt()` 打断当前轮（会话进程保持存活） |
|
|
79
|
+
|
|
80
|
+
## 会话与工作区
|
|
81
|
+
|
|
82
|
+
- **会话 id = Claude 会话 UUID**：新会话由适配器生成 UUID（`query options.sessionId` 固定 id，首次 prompt 落盘）；也能在列表里看到并 resume 你在终端里开过的既有会话。
|
|
83
|
+
- 数据源：`claude-agent-sdk` 的 `listSessions / getSessionInfo / getSessionMessages / deleteSession`（不手读 JSONL），会话/凭证沿用 `~/.claude`，与本地 Claude Code 互不干扰。
|
|
84
|
+
- 工作区 = 会话的 `cwd`；跨会话并行（每会话一个**常驻子进程**），同一会话运行中禁止再发。
|
|
85
|
+
- **常驻长活会话（streaming-input）**：每个会话首次手机消息时 `query({ prompt: 常开 AsyncIterable })` 拉起一个 claude 子进程并**保持存活**（官方 Streaming Input Mode / 长活进程，无顶层会话超时）；后续消息经 `PushChannel` 推入**同一进程**续聊，无逐条冷启动延迟、上下文连续。每轮以 `result` 消息结束（广播 `session.updated` + idle），进程继续等待下一轮。
|
|
86
|
+
- `session.abort` → `query.interrupt()` 打断当前轮；`session.delete` / 适配器退出 → `channel.end()` + `query.close()` 结束子进程。子进程异常退出后，下一次消息以 `resume` 自动重建常驻会话续上下文。
|
|
87
|
+
- 历史拉取会把 `tool_result` 折叠成独立的 `role:"tool"` 卡（结果截断 ≤2KB）；断线期间的流式增量不补发，重连后由手机重拉 `session.messages` 恢复。
|
|
88
|
+
|
|
89
|
+
## 工具审批（安全）
|
|
90
|
+
|
|
91
|
+
- 每个会话的 `permissionMode` 由配置/agent 决定（会话建立时生效；手机切 plan/build 会在会话内 `setPermissionMode` 热切）+ `canUseTool` 拦截：中继在线 → 推手机审批卡（允许/拒绝/总是允许→写入 session 级建议规则）；**中继断线 / 120s 超时 / 中止 → 一律自动拒绝（fail-closed）**，绝不自动放行；断线瞬间会即时清掉所有待审批，无需等满超时。
|
|
92
|
+
- 与 CLI 交互提示一致：审批卡片展示 Claude 的原生提示（`title`/`description`）。
|
|
93
|
+
- 手机在线时审批**优先于 PC**：适配器是 headless 独立进程，claude 子进程无本地 TUI，审批全部经 `canUseTool` 回包；离线时没有本地兜底（拒绝），与 opencode（TUI 兜底）/ dsh（dsh web 兜底）不同，详见 `docs/适配器接口规范.md` §3.3。
|
|
94
|
+
|
|
95
|
+
## 对话框 / MCP elicitation（实验性）
|
|
96
|
+
|
|
97
|
+
- `request_user_dialog`（Claude 的"选择/确认"阻塞对话框）：已实现 `onUserDialog` + `supportedDialogKinds`；kind 白名单走 `TUNNELBOX_CLAUDE_DIALOG_KINDS`（**默认空 → SDK 不发任何对话框**，fail-closed）。启用后按 `dialog.ts` 的启发式映射把 payload 转成手机 `choice/input` 卡，作答值回填 `UserDialogResult.completed`。
|
|
98
|
+
- MCP elicitation：`mode=url` 弹手机审批卡（允许=accept）；`form` 及其余保持自动拒绝。
|
|
99
|
+
- ⚠️ 对话框 payload/result 是 kind 相关结构、随 CLI 版本演进：以上映射为**实验性**，需装有 claude CLI 后按实际抓包校正 `dialog.ts` 与 `bridge.ts` 的 `onUserDialog`。
|
|
100
|
+
|
|
101
|
+
## 官方插件（official-plugin）
|
|
102
|
+
|
|
103
|
+
本包同时包含一个**符合 Claude Code 官方插件规范**的插件（`official-plugin/`，随 npm 发布），
|
|
104
|
+
由 Agent SDK 在每个驱动会话里加载（`options.plugins`）——功能需求主通道仍是 SDK 桥（流式/会话/审批），插件提供会话内扩展：
|
|
105
|
+
|
|
106
|
+
- 斜杠技能 `/tunnelbox:pair`、`/tunnelbox:status`（`skills/pair`、`skills/status`，Claude Code 插件中 `commands/` 与 `skills/` 都注册为技能，统一放 `skills/` 避免同名重复）：在 Claude 会话里直接取/查手机配对状态（`bin/tunnelbox.mjs`，自包含 Node，状态存 `CLAUDE_PLUGIN_DATA`）。
|
|
107
|
+
- 审批**双通道规避**：SDK 桥会注入 `TUNNELBOX_SDK_SESSION=1`，插件 `PermissionRequest` hook 检测到后**不拦截**（交给 `canUseTool`），避免双弹；
|
|
108
|
+
仅当独立 `claude --plugin-dir ./official-plugin` 本地会话时，hook 才把当回合工具审批转发到手机（未绑定/中继不可达时不输出，交本地询问）。
|
|
109
|
+
- hook 输出为 **PermissionRequest 官方 schema**：`{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"|"deny","message":…,"updatedPermissions":[…]}}}`（exit 0 + 单行 JSON）；deny 原因放 `message`；手机「总是允许」（`always`）时把 hook 输入 `permission_suggestions` 原样回填 `updatedPermissions`。`hooks/hooks.json` 拆两条 matcher：精确工具列表（`Bash|Edit|Write|WebFetch|WebSearch|NotebookEdit|Task|Agent`）+ 正则 `mcp__.*`（真实 MCP 工具名前缀是小写 `mcp__`，`MCP.*` 匹配不到）。
|
|
110
|
+
- `bin` 提示文案精简双语（`zh-CN`/其余回退 `en-US`，取 `TUNNELBOX_LANG`/系统 locale）；完整 8 语言与唯一数据源（`plugin/core/locales/*.json`）见下「多语言」。
|
|
111
|
+
|
|
112
|
+
本地直接体验插件：`claude --plugin-dir ./plugin/claude-code/official-plugin`（校验：`claude plugin validate ./plugin/claude-code/official-plugin`）。
|
|
113
|
+
|
|
114
|
+
> 决策：功能主体始终由 Agent SDK 桥承担（列表/流式/审批/中止）；official-plugin 只是**会话内扩展子集**（配对/状态/可选审批），不是实现远程功能所必需。
|
|
115
|
+
|
|
116
|
+
## 目录结构
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
plugin/claude-code/
|
|
120
|
+
├── package.json
|
|
121
|
+
├── tsconfig.json
|
|
122
|
+
├── scripts/build.mjs # esbuild 单文件 dist/index.mjs（external @anthropic-ai/*、qrcode）
|
|
123
|
+
├── scripts/setup.mjs # 设置运行语言（--lang 写 state，对齐 opencode；语言不打包）
|
|
124
|
+
├── scripts/smoke.mjs # 冒烟：连本地中继验证配对流程（不驱动 claude）
|
|
125
|
+
├── official-plugin/ # ★ 官方 Claude Code 插件（随包发布，SDK options.plugins 加载）
|
|
126
|
+
│ ├── .claude-plugin/plugin.json
|
|
127
|
+
│ ├── skills/ # 斜杠技能（commands/ 与 skills/ 都注册为技能，统一用 skills/，避免同名重复）
|
|
128
|
+
│ │ ├── pair/SKILL.md
|
|
129
|
+
│ │ └── status/SKILL.md
|
|
130
|
+
│ ├── hooks/hooks.json # PermissionRequest → bin/tunnelbox.mjs ask（SDK 会话不拦截）
|
|
131
|
+
│ └── bin/ # tunnelbox.mjs / tunnelbox(.cmd) PATH 壳
|
|
132
|
+
└── src/
|
|
133
|
+
├── index.ts # 入口：env 解析（mode/model/thinking/dialogKinds…）+ 连接中继
|
|
134
|
+
├── bridge.ts # relay 连接/配对/消息路由/常驻长活会话（query+PushChannel）/审批/对话框/elicitation
|
|
135
|
+
├── dialog.ts # request_user_dialog kind → 手机卡 启发式映射（实验性）
|
|
136
|
+
├── warm.ts # （已停用，保留）CLI 子进程预热池，常驻会话不再需要
|
|
137
|
+
├── map.ts # SDK 流事件/内容块 → 协议 Part/ChatMessage（tool_result→tool 卡；TurnStreamer 跨轮复用）
|
|
138
|
+
├── sessions.ts # claude-agent-sdk 会话接口封装
|
|
139
|
+
└── globals.d.ts # WebSocket 全局类型
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## 备注
|
|
143
|
+
|
|
144
|
+
- 基准依赖：`@anthropic-ai/claude-agent-sdk`（当前 ^0.3.258，随包 Claude Code 2.1.x；SDK 版本与 Claude Code 版本同步对应）。
|
|
145
|
+
- 本适配器状态文件独立：`~/.tunnelbox/remote-state.claude-code.json`（tunnelbox 独立根目录，与各适配器并存不冲突）。
|
|
146
|
+
- 已按官方契约修正/明确的点：子进程 `env` 自动并入适配器 `process.env`（SDK `options.env` 为整体替换）；`bypassPermissions` 自动置 `allowDangerouslySkipPermissions`；**常驻长活会话**（streaming-input：每会话一个 `query({prompt:常开 AsyncIterable})`，`result` 为轮界、进程跨轮存活，`session.abort` 走 `query.interrupt()`）；`warm` 预热池已停用（常驻会话免冷启动）。
|
|
147
|
+
- 尚未验证项（需装有 claude CLI 并登录后可实跑验证）：流式增量粒度与 assistant 兜底去重（SDK 自述一次 turn 多个 assistant 消息共享 message.id、每条 content 只装一块）、`Options.sessionId` 固定 UUID 能否进 `listSessions`、`redacted_thinking`/`signature_delta` 展示、`TUNNELBOX_CLAUDE_DIALOG_KINDS` 真实 kind 载荷、approval 帧——相关兜底/实验性代码均已就位。
|