@chenacc/agentbridge 0.1.3 → 0.2.0

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 (9) hide show
  1. package/.env.example +21 -0
  2. package/README.md +199 -73
  3. package/docs/RELEASING.md +15 -5
  4. package/package.json +9 -2
  5. package/src/cli.js +108 -9
  6. package/src/config.js +4 -0
  7. package/src/remote.js +449 -0
  8. package/src/server.js +4 -0
  9. package/src/tunnel.js +448 -0
package/.env.example CHANGED
@@ -12,6 +12,27 @@ AGENTBRIDGE_PROJECTS=agentbridge=D:\codex_project\手机远程操控agent
12
12
  # Cloudflare quick tunnels set this automatically to https://<random>.trycloudflare.com
13
13
  # AGENTBRIDGE_PUBLIC_ORIGIN=https://agent.example.com
14
14
 
15
+ # --- Cross-network path selection (read by both the CLI and the DSH plugin) ---
16
+ # Which path the QR code uses. auto tries: named tunnel -> Funnel (only if it is
17
+ # already on) -> Cloudflare quick tunnel -> Tailscale -> ZeroTier -> LAN.
18
+ # AGENTBRIDGE_REMOTE=auto
19
+ # AGENTBRIDGE_NO_TUNNEL=1 # same as AGENTBRIDGE_REMOTE=lan
20
+ # AGENTBRIDGE_TUNNEL_URL=https://fixed.example.com # you run the tunnel yourself
21
+
22
+ # Cloudflare named tunnel (needs `cloudflared tunnel create` + a domain on Cloudflare).
23
+ # AGENTBRIDGE_CLOUDFLARE_TUNNEL=agentbridge
24
+ # AGENTBRIDGE_CLOUDFLARE_HOSTNAME=bridge.example.com
25
+
26
+ # Private overlays are detected automatically; these only point at unusual installs.
27
+ # AGENTBRIDGE_TAILSCALE=C:\Program Files\Tailscale\tailscale.exe
28
+ # AGENTBRIDGE_ZEROTIER=10.147.20.15
29
+
30
+ # cloudflared is located on this machine, and downloaded to <data dir>/bin when
31
+ # it is missing.
32
+ # AGENTBRIDGE_CLOUDFLARED=D:\tools\cloudflared.exe # use your own binary; no search, no download
33
+ # AGENTBRIDGE_CLOUDFLARED_URL=https://mirror.example.com/cloudflared-windows-amd64.exe
34
+ # AGENTBRIDGE_NO_DOWNLOAD=1 # never fetch cloudflared automatically
35
+
15
36
  # Optional state location and expiry overrides.
16
37
  # AGENTBRIDGE_DATA_DIR=D:\agentbridge-data
17
38
  # AGENTBRIDGE_PAIRING_TTL_MS=120000
package/README.md CHANGED
@@ -1,10 +1,14 @@
1
1
  # AgentBridge
2
2
 
3
- > 用微信扫一扫打开手机控制台，安全地查看、继续或停止这台电脑上正在运行的编程 Agent——不用把电脑暴露到公网，凭据始终留在本机。
3
+ > 用手机（微信扫码即可）查看、继续或停止这台电脑上正在运行的编程 Agent。凭据和文件访问始终留在本机，手机只下发命令。
4
+ >
5
+ > 默认走 Cloudflare 隧道：手机用流量、在外地都能打开，不必和电脑连同一个 Wi-Fi；隧道对外开放，因此自动带一道访问密钥门禁。
4
6
 
5
7
  ![AgentBridge 架构：电脑上的本地 Bridge 连接已配对手机，并调用获准的编程 Agent 适配器。](./docs/assets/architecture.svg)
6
8
 
7
- 手机与桌面共享同一份可追加事件流，因此消息、工具活动、审批和任务状态始终同步。电脑是唯一的执行端：手机只下发命令，不运行 Agent，也拿不到任何供应商凭据。
9
+ 手机与桌面共享同一份可追加事件流，因此消息、工具活动、审批和任务状态始终同步。电脑是唯一的执行端：手机只运行界面，不运行 Agent，也拿不到任何供应商凭据。
10
+
11
+ **当前版本：** 桥 `@chenacc/agentbridge` **0.1.4** · DSH 插件 `@chenacc/dsh-agentbridge` **0.3.3**（两个包各自发布，见文末「版本与发布」）。
8
12
 
9
13
  ## 它是怎么工作的
10
14
 
@@ -14,6 +18,18 @@
14
18
  2. **本地 Bridge** 是唯一枢纽：校验设备、维持会话与输入租约，把命令写进可追加事件流，再经 SSE 推回手机。
15
19
  3. **电脑上的 Agent 子进程** 真正执行任务，凭据与文件访问始终留在本机，手机侧拿不到。
16
20
 
21
+ 远程时中间多一跳，但入口仍然是桥：
22
+
23
+ ```
24
+ 手机 ──公网 HTTPS──> Cloudflare 边缘 ──隧道──> cloudflared（你电脑上的进程）
25
+ │
26
+ ▼
27
+ AgentBridge 桥（127.0.0.1:8787）
28
+ │
29
+ ▼
30
+ Claude Code / Codex / DeepSeek Harness / DSH Desktop 里的那条会话
31
+ ```
32
+
17
33
  因为上行与下行共用同一条事件流，桌面端和手机看到的是同一份状态，而不是两套各自猜测的界面。
18
34
 
19
35
  > 本文中标注为「分镜关键帧」的图片是讲解视频的概念示意图，用于说明结构关系；真实界面见下文「界面」一节。
@@ -21,6 +37,7 @@
21
37
  ## 主要能力
22
38
 
23
39
  - **扫码配对**：一次性、5 分钟有效的二维码；配对后收藏固定回访地址，之后免扫码进入。
40
+ - **跨网络直接可用**：默认自动开 Cloudflare 隧道，二维码就是公网 https 地址，手机无需安装任何 App。
24
41
  - **工作区 → 会话导航**：一个抽屉管理「Agent → 项目 → 会话」，Bridge 重启后历史与会话不丢失。
25
42
  - **完整对话控制**：流式输出、停止、接管输入、翻看历史，表格 / 公式 / 代码块正确渲染。
26
43
  - **远程协作**：审批卡片、提问卡片、限时自动放行（5/10/30 分钟）、消息排队、会话内搜索。
@@ -40,6 +57,7 @@
40
57
  | Node.js | **22 或更高**，`node -v` 确认 |
41
58
  | 操作系统 | Windows（一键脚本齐全）；Linux / macOS 直接用 `npm start` |
42
59
  | Agent 工具 | 可选，按需安装：Claude Code / Codex / DeepSeek Harness / DSH Desktop |
60
+ | cloudflared | **不需要手动准备**：缺了会自动下载（见下一节） |
43
61
 
44
62
  AgentBridge 不替你安装或登录任何 Agent，只检测本机**已安装且已登录**的那些；没装的显示「未安装」，不会假装可用。
45
63
 
@@ -68,7 +86,7 @@ $env:AGENTBRIDGE_PROJECTS = "agentbridge=D:\projects\agentbridge" # 可选：
68
86
  npm start
69
87
  ```
70
88
 
71
- 打开 [http://127.0.0.1:8787](http://127.0.0.1:8787)，桌面页会显示一次性二维码；手机连同一可信 Wi-Fi，用微信「扫一扫」扫描即可。
89
+ 打开 [http://127.0.0.1:8787](http://127.0.0.1:8787)，桌面页会显示一次性二维码，用微信「扫一扫」即可。
72
90
 
73
91
  > 二维码只用于首次配对，会过期且**只能使用一次**。配对成功后请收藏手机页显示的固定回访地址，之后从收藏进入；不要收藏 `/pair?code=...` 临时链接。
74
92
  > `AGENTBRIDGE_PROJECTS` 可以不写：不设时默认把**启动目录**作为唯一可用项目，别名 `workspace`。别名只允许字母、数字、`_`、`-`（≤40 字符）。
@@ -81,61 +99,121 @@ npx @chenacc/agentbridge phone --agent echo
81
99
  # 从仓库跑的话：node .\bin\agentbridge.js phone --agent echo
82
100
  ```
83
101
 
84
- Echo 适配器不接触任何 AI 工具，只验证「CLI → 本机 Bridge → 生成配对二维码」整条链路。能打印二维码就说明安装正确，扫码后可看到手机与桌面同步。
102
+ Echo 适配器不接触任何 AI 工具，只验证「CLI → 本机 Bridge → 生成配对二维码」整条链路。能打印二维码就说明安装正确，扫码后可看到手机与桌面同步。终端里除了二维码，还会打出两行关键信息：
85
103
 
86
- ## 一键启动与停止（Windows）
104
+ ```
105
+ 网络: 公网地址，手机用流量也能打开
106
+ 微信扫码地址: https://xxx.trycloudflare.com/pair?code=…&key=…
107
+ ```
87
108
 
88
- | 入口 | 用途 |
89
- |---|---|
90
- | `启动 AgentBridge.cmd` | 局域网模式：检查服务健康、避免重复占用 8787、后台启动并打开控制台 |
91
- | `启动 AgentBridge 远程模式.cmd` | Tailscale 模式，跨网络使用 |
92
- | `启动 AgentBridge ZeroTier 远程模式.cmd` | ZeroTier 模式，Tailscale 不稳定时使用 |
93
- | `启动 AgentBridge Cloudflare 远程模式.cmd` | Cloudflare Tunnel，手机不需装任何 App |
94
- | `安全停止 AgentBridge.cmd` | 安全停止：不误杀其它进程、有任务在跑时拒绝停止、绝不强制 kill |
109
+ 第一次运行会自动下载 `cloudflared`（约 55 MB），所以首次可能要等几秒到几十秒；之后再运行就是秒级。
110
+
111
+ ## 网络与远程接入
95
112
 
96
- 日志在 `.agentbridge/logs`；桌面快捷方式用 `.\scripts\install-agentbridge-shortcut.ps1` 创建或刷新。
113
+ ### 二维码里的地址是怎么定的
97
114
 
98
- ## 远程接入方式
115
+ CLI 和插件共用同一套逻辑（`src/remote.js`），按下面的顺序决定二维码写什么：
99
116
 
100
- | 场景 | 模式 | 手机要求 |
117
+ | 优先级 | 条件 | 二维码地址 |
101
118
  |---|---|---|
102
- | 什么都不装、也不连同一个 Wi-Fi（DSH 插件默认） | Cloudflare Tunnel（自动） | 只需浏览器 |
103
- | 同一可信 Wi-Fi | 局域网 | 浏览器 / 微信 |
104
- | 跨网络，但属同一私有网络 | Tailscale | 同一 tailnet |
105
- | Tailscale 不稳定 | ZeroTier | 同一私有网络 |
106
- | 手机装不了 VPN 类 App | Cloudflare Tunnel | 只需浏览器 |
119
+ | 1 | 设了 `AGENTBRIDGE_PUBLIC_ORIGIN` | 你给的那个（Tailscale、ZeroTier、自己的域名都走这条） |
120
+ | 2 | 已有桥正在用公网地址运行 | 复用它，不再开新通道 |
121
+ | 3 | 设了 `AGENTBRIDGE_NO_TUNNEL=1` 或 `AGENTBRIDGE_REMOTE=lan` | 局域网 |
122
+ | 4 | `AGENTBRIDGE_REMOTE` 指定了某一条（`funnel` / `named` / `tailscale` / `zerotier` / `cloudflare`） | 只试那一条 |
123
+ | 5 | 默认 `auto` | 按下面「五种远程路径」的顺序试，成功即停 |
124
+ | 6 | 全都不成立 | 局域网，日志里逐条说明每条为什么失败 |
125
+
126
+ ### 五种远程路径
127
+
128
+ `auto`（默认）的尝试顺序：**命名隧道 → Funnel → Cloudflare quick → Tailscale → ZeroTier → 局域网**。下表的“自动”指装好就能用、不需要你手动跑脚本。
129
+
130
+ | 路径 | 自动？ | 手机要求 | 代价 |
131
+ |---|---|---|---|
132
+ | Cloudflare quick tunnel | ✅ 缺 `cloudflared` 会自己下 | 只需浏览器 | 域名每次重建会变 |
133
+ | 局域网 | ✅ 兜底 | 浏览器 / 微信 | 出门就不可用 |
134
+ | Tailscale（私有地址） | ✅ 已登录且在线才用 | 同一 tailnet（装 App） | 手机要常驻 VPN 类 App |
135
+ | ZeroTier（私有地址） | ✅ 检测到 ZeroTier 网卡才用 | 同一私有网络（装 App） | 同上 |
136
+ | Tailscale Funnel | 🟡 需 `AGENTBRIDGE_REMOTE=funnel` 显式开启；`auto` 只复用已开启的 | 只需浏览器 | 要在 Tailscale 管理台开启 Funnel |
137
+ | Cloudflare 命名隧道 | 🟡 需配隧道名 + 域名 | 只需浏览器 | 域名要托管在 Cloudflare |
138
+
139
+ Funnel 单独放在“要显式开启”这一档，是因为开启它会改动你 tailnet 的对外暴露配置——这种事不该由一次扫码替你决定。反过来，**已经开着的** Funnel 会被 `auto` 直接复用。
140
+
141
+ 只想用某一条路径：
142
+
143
+ ```powershell
144
+ $env:AGENTBRIDGE_REMOTE = "funnel" # 或 named | cloudflare | tailscale | zerotier | lan
145
+ agentbridge phone --agent claude
146
+ ```
147
+
148
+ 命名隧道需要两个变量：
149
+
150
+ ```powershell
151
+ $env:AGENTBRIDGE_CLOUDFLARE_TUNNEL = "agentbridge" # cloudflared 里已经建好的隧道名
152
+ $env:AGENTBRIDGE_CLOUDFLARE_HOSTNAME = "bridge.example.com"
153
+ ```
154
+
155
+ 当前路径会同时出现在三个地方：CLI 输出的「网络:」一行、桥启动日志的 `Remote path:` 一行、`/api/health` 的 `remoteProvider` 字段——二维码打不开时先看这三处。
107
156
 
108
157
  ![分镜关键帧：四条网络路径分别接入同一台 Windows Host，其中 Cloudflare 路径还要经过一道访问密钥门禁](./docs/assets/keyframe-09-network-paths.jpg)
109
158
 
110
- 任何模式都不要把 TCP 8787 直接映射到公网。Cloudflare 模式额外启用访问密钥闸门（密钥存于 `.agentbridge/access-key`），光有二维码不够。
159
+ 任何模式都**不要**把 TCP 8787 直接映射到公网。Cloudflare 模式会额外启用访问密钥闸门，光有二维码不够。
160
+
161
+ ### cloudflared 是自动的
162
+
163
+ 插件和 CLI 都会先在本机找 `cloudflared`（PATH、两处 Program Files、winget 目录、`~/.agentbridge/bin`），都找不到时才从 Cloudflare 官方的 GitHub Releases 下载一份到 `%USERPROFILE%\.agentbridge\bin\cloudflared.exe`：不要管理员权限、不写系统目录、删掉那个文件夹就等于卸载。下载完会先跑一次 `cloudflared --version`，验不过的文件不会留下。
164
+
165
+ 想自己装也行（`winget install --id Cloudflare.cloudflared`），已装的那份优先。断网或代理挡住下载时，一切照常，只是退回局域网。
111
166
 
112
167
  ### 访问密钥：会不会变、怎么换
113
168
 
114
- 密钥就是一句口令，不是账号。门禁只在**用 Cloudflare 隧道启动时**打开——其余模式（局域网 / Tailscale / ZeroTier）默认没有门禁，也就不会有人问你密钥。门禁打开时，所有非本机（loopback）请求都必须带上它：二维码里已内嵌 `?key=…`，手机用它换一个 90 天有效的 cookie（`agentbridge_key`）。
169
+ 密钥就是一句口令，不是账号。它只在**对公网开放时**生效（quick tunnel / 命名隧道）；局域网、Tailscale、ZeroTier 默认没有门禁，也就不会有人问你密钥。门禁打开时，所有非本机（loopback）请求都必须带上它：二维码里已内嵌 `?key=…`，手机用它换一个 90 天有效的 cookie（`agentbridge_key`）。
115
170
 
116
- **默认是固定的。** `scripts/start-agentbridge.ps1` 里的 `Get-OrCreateAccessKey` 先读 `.agentbridge/access-key`：只要文件存在、内容非空且不短于 16 个字符，就原样复用。所以重启、换端口、换隧道地址都不会改它。会变的情况只有三种：
171
+ 密钥文件有两个位置，取决于谁在开隧道：
117
172
 
118
- 1. 删掉（或清空、或写短于 16 个字符）`.agentbridge/access-key`；
119
- 2. 换了一份代码目录（文件跟着目录走，不同 `$bridgeRoot` 各有一把）；
120
- 3. 该目录第一次以 Cloudflare 模式启动。
173
+ | 谁来开隧道 | 密钥文件 |
174
+ |---|---|
175
+ | CLI / DSH 插件（默认路径） | `%USERPROFILE%\.agentbridge\access-key` |
176
+ | 仓库里的一键脚本 `.cmd` | `<仓库>\.agentbridge\access-key` |
177
+
178
+ 两者都是**先读后写**：文件存在、内容非空且不短于 16 个字符就原样复用，所以重启、换端口、换隧道地址都不会改它。会变的只有三种情况：删掉（或清空、或写短于 16 个字符）该文件；换了一份代码目录；该目录第一次以 Cloudflare 模式启动。
121
179
 
122
180
  **换法**（三步，不需要改代码）：
123
181
 
124
182
  ```powershell
125
- scripts\stop-agentbridge.ps1 # 1. 停桥
126
- Remove-Item .agentbridge\access-key # 2a. 让下次启动生成新串
183
+ # 1. 停掉桥（安全停止脚本，或结束占用 8787 的进程）
184
+ scripts\stop-agentbridge.ps1
185
+
186
+ # 2a. 让下次启动生成新串
187
+ Remove-Item "$env:USERPROFILE\.agentbridge\access-key"
127
188
  # 或者直接写自己的口令（≥16 字符，别加换行）：
128
- # "my-own-long-passphrase" | Set-Content .agentbridge\access-key -NoNewline -Encoding ascii
129
- scripts\start-agentbridge.ps1 -CloudflareTunnel # 3. 启动，窗口会打印新串
189
+ # "my-own-long-passphrase" | Set-Content "$env:USERPROFILE\.agentbridge\access-key" -NoNewline -Encoding ascii
190
+
191
+ # 3. 重启（重启 DSH Desktop，或再跑一次 agentbridge phone）
130
192
  ```
131
193
 
132
- 换完所有手机都要重新扫码或用新串（旧 cookie 不再匹配）。注意 Cloudflare 模式下脚本会**无条件**用文件里的值覆盖 `AGENTBRIDGE_ACCESS_KEY` 环境变量，所以“只设环境变量”在那里不管用——想自定义口令就写进文件；非隧道模式下才是靠环境变量。
194
+ 换完所有手机都要重新扫码（旧 cookie 不再匹配）。`.agentbridge/` 已在 `.gitignore` 中，密钥不会进版本库；但也别把带 `?key=` 的完整链接贴到公开场合。推送通知的跳转链接默认**不带**密钥（`notifyLink` 需要显式开启），所以换钥匙不影响通知。
195
+
196
+ ### 局域网地址是怎么挑的
197
+
198
+ 自动选地址时会跳过 `169.254.x.x`（网卡没拿到租约时的临时地址，手机根本路由不到）和 Hyper-V / WSL / 蓝牙 / Wi-Fi Direct 这类虚拟网卡，优先真实的 Wi-Fi 或以太网地址。扫码后如果微信弹出「该地址为 IP 地址，请使用域名访问网站」，点「继续访问」即可。
199
+
200
+ ## 一键启动与停止（Windows）
201
+
202
+ | 入口 | 用途 |
203
+ |---|---|
204
+ | `启动 AgentBridge.cmd` | 局域网模式：检查服务健康、避免重复占用 8787、后台启动并打开控制台 |
205
+ | `启动 AgentBridge 远程模式.cmd` | Tailscale 模式，跨网络使用 |
206
+ | `启动 AgentBridge ZeroTier 远程模式.cmd` | ZeroTier 模式，Tailscale 不稳定时使用 |
207
+ | `启动 AgentBridge Cloudflare 远程模式.cmd` | Cloudflare Tunnel，手机不需装任何 App（不做自动下载，缺 `cloudflared` 会直接报错并提示安装） |
208
+ | `安全停止 AgentBridge.cmd` | 安全停止：不误杀其它进程、有任务在跑时拒绝停止、绝不强制 kill |
133
209
 
134
- `.agentbridge/` 已在 `.gitignore` 中，密钥不会进版本库；但也别把带 `?key=` 的完整链接贴到公开场合。推送通知的跳转链接默认**不带**密钥（`notifyLink` 需要显式开启），所以换钥匙不会影响通知。
210
+ 这些脚本自己设置 `AGENTBRIDGE_PUBLIC_ORIGIN` 和访问密钥，和 CLI / 插件的自动模式**不要同时用**：同一端口只能有一个桥在跑，后启动的那个会连上已有实例而不是另起一个。
211
+
212
+ 日志在 `<仓库>\.agentbridge\logs`；桌面快捷方式用 `.\scripts\install-agentbridge-shortcut.ps1` 创建或刷新。
135
213
 
136
214
  ## 让 Agent 支持 `/phone`
137
215
 
138
- `/phone` 不是 Agent 自带的功能，而是 AgentBridge 往对应客户端里装的一个**技能**（一个 `SKILL.md` 文件）。它只做一件事：在**当前项目目录**里调用 `agentbridge phone --agent <id>`，由 CLI 确保 Bridge 在运行、创建或附加会话、打印一次性二维码。
216
+ `/phone` 不是 Agent 自带的功能，而是 AgentBridge 往对应客户端里装的一个**技能**（一个 `SKILL.md` 文件）。它只做一件事：在**当前项目目录**里调用 `agentbridge phone --agent <id>`，由 CLI 确保 Bridge 在运行、准备公网地址、创建或附加会话、打印一次性二维码。
139
217
 
140
218
  三个前提，每个 Agent 都一样：
141
219
 
@@ -145,14 +223,18 @@ scripts\start-agentbridge.ps1 -CloudflareTunnel # 3. 启动，窗口会打
145
223
 
146
224
  技能是纯文本文件，删掉对应的 `SKILL.md` 就等于卸载。
147
225
 
226
+ 二维码默认是**公网地址**，三条路径共用同一套逻辑、同一条隧道、同一把访问密钥：`cloudflared` 缺了就自动下载；DSH 插件已经开着隧道时，CLI 直接复用它，不会再起一条。只想在局域网用就设 `AGENTBRIDGE_NO_TUNNEL=1`；已有自己的公网入口就设 `AGENTBRIDGE_PUBLIC_ORIGIN`。
227
+
228
+ > 一个例外：如果本机已经有一个**以局域网地址**运行的桥（比如很久以前启动的旧进程），CLI 不会擅自重启它——那会打断正在跑的会话——只会提示本次沿用那个地址。停掉它或重启 DSH Desktop 即可换成公网地址。
229
+
148
230
  ### Claude Code
149
231
 
150
232
  ```powershell
151
233
  # 用户级（默认）：%USERPROFILE%\.claude\skills\phone\SKILL.md
152
- node .\bin\agentbridge.js install-claude-skill --user
234
+ agentbridge install-claude-skill --user
153
235
 
154
236
  # 只装给某个项目：<项目>\.claude\skills\phone\SKILL.md
155
- node .\bin\agentbridge.js install-claude-skill --project --cwd D:\projects\agentbridge
237
+ agentbridge install-claude-skill --project --cwd D:\projects\agentbridge
156
238
  ```
157
239
 
158
240
  重启 Claude Code，在项目目录输入 `/phone`。技能用官方 `${CLAUDE_SESSION_ID}` 绑定**当前这段对话**，不读私有 transcript、不猜路径；只预授权 `agentbridge phone --agent claude …` 这一条命令，不授予通用 Bash 权限。
@@ -163,28 +245,20 @@ node .\bin\agentbridge.js install-claude-skill --project --cwd D:\projects\agent
163
245
 
164
246
  ```powershell
165
247
  # 用户级（默认）：%USERPROFILE%\.agents\skills\phone\SKILL.md
166
- node .\bin\agentbridge.js install-codex-skill --user
248
+ agentbridge install-codex-skill --user
167
249
  ```
168
250
 
169
251
  重启 Codex 桌面项目，在本地项目会话输入 `/phone`。Codex 没对外提供「当前线程 ID」，所以不带参数时它会在同一项目目录**新建**一个会话并明确标注；只有你已知 thread ID 时才精确附加：
170
252
 
171
253
  ```powershell
172
- node .\bin\agentbridge.js phone --agent codex --session <thread-id>
254
+ agentbridge phone --agent codex --session <thread-id>
173
255
  ```
174
256
 
175
257
  ### DSH Desktop
176
258
 
177
259
  前提：DSH Desktop 已安装，且存在桌面 profile `%USERPROFILE%\.dsh\profiles\desktop\package.json`（或由 `DSH_HOME` 指定）。
178
260
 
179
- **第 0 步：桥。** 插件是遥控器，桥是基站。从 0.2.0 起桥随插件一起安装，**DSH Desktop 启动时插件会自己在后台把它拉起来**，正常情况你什么都不用敲。
180
-
181
- 从 0.3.0 起，插件默认再开一条 **Cloudflare 隧道**，把桥映射成公网 https 域名，于是手机不必和电脑在同一个 Wi-Fi——扫描、出差、用流量都能开。这一步需要一个 Cloudflare 官方小工具：
182
-
183
- ```powershell
184
- winget install --id Cloudflare.cloudflared
185
- ```
186
-
187
- 没装也不影响使用，只是退回"手机与电脑同一 Wi-Fi"。想一直走局域网，设 `AGENTBRIDGE_NO_TUNNEL=1`；想用固定域名，去 Cloudflare 建命名隧道并把 `AGENTBRIDGE_PUBLIC_ORIGIN` 指向它。
261
+ **第 0 步：桥。** 插件是遥控器，桥是基站。从 0.2.0 起桥随插件一起安装，**DSH Desktop 启动时插件会自己在后台把它拉起来**；从 0.3.0 起还会再自动开 Cloudflare 隧道。所以正常情况你什么都不用敲，重启桌面等几秒后直接 `/phone`。
188
262
 
189
263
  只有自动启动失败（沙箱限制、端口被占）才需要手动来一条：
190
264
 
@@ -192,21 +266,15 @@ winget install --id Cloudflare.cloudflared
192
266
  npx @chenacc/agentbridge
193
267
  ```
194
268
 
195
- 想长期使用、或要改配置（项目白名单、远程通道、通知推送），装成全局命令：
196
-
197
- ```powershell
198
- npm install -g @chenacc/agentbridge # 之后随时 agentbridge phone --agent claude
199
- ```
200
-
201
- 也可以从仓库跑：`git clone https://github.com/chenacc1/agentbridge.git` → `cd agentbridge` → `npm install` → `npm start`（或双击「启动 AgentBridge.cmd」）。
202
-
203
- **第 1 步：装插件（普通用户走市场）**：设置 → 插件市场 → 发现，搜 `AgentBridge` 或 `@chenacc/dsh-agentbridge` → 安装 → 重启 DSH Desktop。等价的命令行安装：
269
+ **第 1 步：装插件（普通用户走市场）**：设置 → 插件市场 → 发现，搜 `AgentBridge` 或 `@chenacc/dsh-agentbridge` → 安装 → 重启 DSH Desktop。等价的手动安装：
204
270
 
205
271
  ```powershell
206
272
  cd "$env:USERPROFILE\.dsh\profiles\desktop"; pnpm add @chenacc/dsh-agentbridge@latest
207
273
  # 装完还需把 "@chenacc/dsh-agentbridge" 加进该 package.json 的 dsh.profile.bundles（市场安装会自动做）
208
274
  ```
209
275
 
276
+ > 市场卡片上显示的版本号来自插件目录快照，每天刷新一次；实际安装拉的是 npm 的 `latest`，所以卡片版本可能比装到的版本旧一天。
277
+
210
278
  **从本地源码装（开发者）**：
211
279
 
212
280
  ```powershell
@@ -230,26 +298,25 @@ npm run uninstall:dsh-phone
230
298
  前提：官方 `dsh` CLI 已安装并配置好模型与凭据，`dsh --profile acp --help` 能打印帮助（而不是弹出浏览器界面）。这个适配器没有斜杠技能，直接用 CLI：
231
299
 
232
300
  ```powershell
233
- node .\bin\agentbridge.js phone --agent deepseek-harness
301
+ agentbridge phone --agent deepseek-harness
234
302
  ```
235
303
 
236
304
  ### 一张表汇总
237
305
 
238
- | Agent | 前提 | 要执行的安装命令 | 重启客户端 | 入口 |
239
- |---|---|---|---|---|
240
- | Claude Code | 已安装并登录 | `install-claude-skill --user` | 需要 | `/phone` |
241
- | Codex Desktop | 已安装并登录 | `install-codex-skill --user` | 需要 | `/phone` |
242
- | DSH Desktop | 存在桌面 profile | `npm run install:dsh-phone` | 需要 | `/phone` |
243
- | DeepSeek Harness | `dsh --profile acp --help` 可用 | 不需要 | — | `phone --agent deepseek-harness` |
244
- | Echo | 无 | 不需要 | — | `phone --agent echo` |
245
- | ZCode | 仅官方 Remote Control / Bot Channel | 不需要 | — | AgentBridge 不代管 |
306
+ | Agent | 前提 | 要执行的安装命令 | 重启客户端 | 入口 | 二维码默认地址 |
307
+ |---|---|---|---|---|---|
308
+ | Claude Code | 已安装并登录 | `agentbridge install-claude-skill --user` | 需要 | `/phone` | 公网 |
309
+ | Codex Desktop | 已安装并登录 | `agentbridge install-codex-skill --user` | 需要 | `/phone` | 公网 |
310
+ | DSH Desktop | 存在桌面 profile | 插件市场安装（或 `pnpm add`） | 需要 | `/phone` | 公网 |
311
+ | DeepSeek Harness | `dsh --profile acp --help` 可用 | 不需要 | — | `phone --agent deepseek-harness` | 公网 |
312
+ | Echo | 无 | 不需要 | — | `phone --agent echo` | 公网 |
313
+ | ZCode | 仅官方 Remote Control / Bot Channel | 不需要 | — | AgentBridge 不代管 | — |
246
314
 
247
315
  ### 通用说明
248
316
 
249
317
  - `/phone` 只接受来自本机 loopback 的绝对路径，手机会话无法提交任意目录。
250
318
  - 想让 `agentbridge` 成为全局命令，在仓库里跑一次 `npm link`。
251
- - 仓库目前尚未创建 `v0.1.0` 标签；打上固定标签后，别人可用一行装好 CLI 与 Codex 技能：
252
- `npm install --global github:chenacc1/agentbridge#v0.1.0; agentbridge setup codex`
319
+ - 想从固定版本装：`npm install --global github:chenacc1/agentbridge#bridge-v0.1.4`，然后 `agentbridge setup codex` 装技能。
253
320
 
254
321
  ## 支持的 Agent
255
322
 
@@ -280,19 +347,45 @@ node .\bin\agentbridge.js phone --agent deepseek-harness
280
347
 
281
348
  完整变量见 [`.env.example`](./.env.example)。
282
349
 
350
+ **桥本身：**
351
+
283
352
  | 变量 | 默认值 | 含义 |
284
353
  |---|---|---|
285
354
  | `AGENTBRIDGE_PORT` | `8787` | HTTP 监听端口 |
355
+ | `AGENTBRIDGE_HOST` | `0.0.0.0` | 监听地址 |
286
356
  | `AGENTBRIDGE_PROJECTS` | 当前目录 | 项目白名单，分号分隔 `别名=绝对路径` |
287
- | `AGENTBRIDGE_PUBLIC_ORIGIN` | 第一个 LAN 地址 | 写入二维码的访问地址 |
357
+ | `AGENTBRIDGE_DATA_DIR` | `~/.agentbridge`（CLI / 插件）/ 启动目录（`npm start`） | 会话、事件、密钥、隧道状态的目录 |
358
+ | `AGENTBRIDGE_PUBLIC_ORIGIN` | 自动（公网隧道或局域网地址） | 写进二维码的访问地址；设了它就不再自动开隧道 |
359
+ | `AGENTBRIDGE_ACCESS_KEY` | 未设置 | 访问密钥；对公网开放时自动生成并写入 `access-key` 文件 |
288
360
  | `AGENTBRIDGE_PAIRING_TTL_MS` | `300000` | 配对码有效期（5 分钟） |
289
361
  | `AGENTBRIDGE_SESSION_TTL_MS` | `259200000` | 设备会话有效期（72 小时） |
290
362
  | `AGENTBRIDGE_CLAUDE_MODEL` | 供应商默认 | 可选的 Claude / Kimi 模型 ID |
291
363
  | `AGENTBRIDGE_NOTIFY_WEBHOOK` | 未设置 | 通知 Webhook；未设置时该功能静默 |
292
364
 
293
- 若自动选择的局域网地址手机访问不到，显式指定 `AGENTBRIDGE_PUBLIC_ORIGIN`；Windows 防火墙提示时只放行「专用网络」。
365
+ **跨网络（CLI 与插件都认）：**
366
+
367
+ | 变量 | 默认值 | 含义 |
368
+ |---|---|---|
369
+ | `AGENTBRIDGE_REMOTE` | `auto` | 走哪条路径：`auto` / `cloudflare` / `named` / `funnel` / `tailscale` / `zerotier` / `lan` |
370
+ | `AGENTBRIDGE_NO_TUNNEL` | 未设置 | 设为 `1` 等价于 `AGENTBRIDGE_REMOTE=lan` |
371
+ | `AGENTBRIDGE_TUNNEL_URL` | 未设置 | 直接指定隧道域名（给"隧道自己管"的人） |
372
+ | `AGENTBRIDGE_CLOUDFLARE_TUNNEL` | 未设置 | Cloudflare **命名隧道**的名字；设了它 `auto` 会优先用它 |
373
+ | `AGENTBRIDGE_CLOUDFLARE_HOSTNAME` | 未设置 | 命名隧道对应的公网域名 |
374
+ | `AGENTBRIDGE_CLOUDFLARED` | 自动查找 | 用你自己那份 `cloudflared`；设了它既不搜索也不下载 |
375
+ | `AGENTBRIDGE_CLOUDFLARED_URL` | 官方 Releases | 换下载源（内网镜像），下载后照样过 `--version` 校验 |
376
+ | `AGENTBRIDGE_NO_DOWNLOAD` | 未设置 | 设为 `1` 禁止自动下载 `cloudflared` |
377
+ | `AGENTBRIDGE_TAILSCALE` | 自动查找 | 指定 `tailscale` 可执行文件（装在非常规位置时用） |
378
+ | `AGENTBRIDGE_ZEROTIER` | 自动检测网卡 | 直接指定 ZeroTier 分配到的 IPv4 |
379
+
380
+ **插件 / CLI 专用：**
381
+
382
+ | 变量 | 默认值 | 含义 |
383
+ |---|---|---|
384
+ | `AGENTBRIDGE_ORIGIN` | `http://127.0.0.1:8787` | 插件连接的本地桥地址 |
385
+ | `AGENTBRIDGE_LOCAL_ORIGIN` | `http://127.0.0.1:8787` | CLI 连接的本地桥地址 |
386
+ | `AGENTBRIDGE_NO_AUTOSTART` | 未设置 | 设为 `1` 关掉"插件加载时自动起桥" |
294
387
 
295
- 自动选地址时会跳过 `169.254.x.x`（网卡没拿到租约时的临时地址，手机根本路由不到）和 Hyper-V / WSL / 蓝牙这类虚拟网卡，优先真实的 Wi-Fi 或以太网地址。扫码后如果微信弹出「该地址为 IP 地址，请使用域名访问网站」，点「继续访问」即可；手机上不了网、或者只有手机流量没连同一个 Wi-Fi 时，二维码里的地址是打不开的。
388
+ 变量要设在**真正启动 DSH Desktop / 终端的环境里**，不是设在跑桥的另一个窗口里。
296
389
 
297
390
  ## 安全边界
298
391
 
@@ -300,21 +393,54 @@ node .\bin\agentbridge.js phone --agent deepseek-harness
300
393
 
301
394
  - 二维码里是一次性配对码，不是 Agent 凭据；磁盘只保存设备 token 的 SHA-256 摘要。
302
395
  - 设备 cookie 为 `HttpOnly` + `SameSite=Strict`；修改型请求校验同源，命令 ID 防重放，同一会话同时只有一台设备持有输入租约。
396
+ - 对公网开放时访问密钥强制开启，非 loopback 请求一律要求带密钥；密钥不写进命令行、不进日志。
397
+ - 桥的本地管理接口（配对、注册、停止、`cloudflared` 状态）只接受 loopback；即便是同一台机器上的"要求桥重启"这类动作，也要带上插件在启动时生成的一次性 token。
303
398
  - Agent 凭据与子进程始终留在电脑上，手机永远不是执行环境。
304
399
  - 当前不提供多用户授权、静态加密事件日志、重启后活动子进程恢复或云端 Relay。
305
400
 
401
+ > 默认公网可用意味着**二维码等同于钥匙**：别截图外传，也别把带 `?key=` 的链接贴到公开场合。只想在家里用时设 `AGENTBRIDGE_NO_TUNNEL=1`。
402
+
306
403
  ## 验证
307
404
 
308
405
  ```powershell
309
- npm run check # 语法检查
310
- npm test # 单元与集成测试（当前 187 项全部通过）
406
+ npm run check # 语法检查（38 个文件）
407
+ npm test # 单元与集成测试（当前 240 项全部通过）
408
+ npm run verify:release # 插件发布验收（17 项：registry / tarball / 可导入性）
409
+ npm run verify:remote # 端到端验证 Cloudflare 远程链路，需要 cloudflared 与网络
311
410
  npm run verify:mobile # 可选：真实浏览器端到端，需要 Chrome 或 Edge
312
411
  ```
313
412
 
314
- 其余 `verify:*` 脚本（`navigation`、`models`、`scrim`、`notify`、`attach`、`features`、`blocks`、`questions`、`quicknav`）各自启动真实 Bridge 与无头浏览器做界面验证。
413
+ 其余 `verify:*` 脚本（`navigation`、`models`、`scrim`、`notify`、`attach`、`features`、`blocks`、`questions`、`quicknav`、`responsive`、`guide`）各自启动真实 Bridge 与无头浏览器做界面验证。
414
+
415
+ ## 版本与发布
416
+
417
+ 两个 npm 包，各自独立发版，都由 GitHub Actions 用 tag 触发（OIDC 可信发布，带 SLSA provenance）：
418
+
419
+ | 包 | 当前版本 | tag 前缀 | 装到哪 |
420
+ |---|---|---|---|
421
+ | `@chenacc/agentbridge` | `0.2.0` | `bridge-v*` | 全局命令 / `npx` / 插件依赖 |
422
+ | `@chenacc/dsh-agentbridge` | `0.4.0` | `dsh-v*` | DSH Desktop 的 profile |
423
+
424
+ 最近的阶段性变化：
425
+
426
+ - **0.2.0（桥）**：路径选择抽成 provider（`src/remote.js`）——Cloudflare quick / 命名隧道 / Tailscale / Tailscale Funnel / ZeroTier 共用一套顺序与回退，`AGENTBRIDGE_REMOTE` 可指定单条；`/api/health` 与启动日志会报出当前走的是哪条。
427
+ - **0.1.1–0.1.4（桥）**：二维码地址改按"能不能被手机路由到"排序（跳过 `169.254` 与虚拟网卡）；`/api/health` 汇报自己广播的地址；新增只有本机 token 能调的自动重启入口；隧道能力下沉到本包，CLI 的 `/phone` 因此也默认公网。
428
+ - **0.4.0（插件）**：改用桥包里的同一套路径选择，本地行为不变但多了 Funnel / Tailscale / ZeroTier 三条可选路径。
429
+ - **0.3.0–0.3.3（插件）**：加载时自动起桥、自动开 Cloudflare 隧道、`cloudflared` 缺失时自动下载。
430
+
431
+ 升级方式：
432
+
433
+ ```powershell
434
+ npm install -g @chenacc/agentbridge@latest # CLI / 桥
435
+ cd "$env:USERPROFILE\.dsh\profiles\desktop"
436
+ pnpm add @chenacc/dsh-agentbridge@latest # DSH 插件（或直接在插件市场点安装）
437
+ ```
315
438
 
316
439
  ## 更多文档
317
440
 
318
441
  - 架构说明：[`docs/architecture/wechat-multi-agent-remote-control.md`](./docs/architecture/wechat-multi-agent-remote-control.md)
319
442
  - 功能与前端执行逻辑：[`docs/软件功能与前端执行逻辑.md`](./docs/软件功能与前端执行逻辑.md)
320
- - 发布流程：[`docs/RELEASING.md`](./docs/RELEASING.md)
443
+ - 发布流程：[`docs/PUBLISHING.md`](./docs/PUBLISHING.md)
444
+ - 安装验收清单：[`docs/verify-plugin-install.md`](./docs/verify-plugin-install.md)
445
+ - 市场收录记录：[`docs/market-submission.md`](./docs/market-submission.md)
446
+ - 版本与更新记录：[`docs/RELEASING.md`](./docs/RELEASING.md)
package/docs/RELEASING.md CHANGED
@@ -1,21 +1,31 @@
1
1
  # Releasing AgentBridge
2
2
 
3
- This repository can be installed directly from a tagged public GitHub release. It does not require npm publication for the first public release.
3
+ This repository can be installed directly from a tagged public GitHub release. Both npm packages are now published as well, and those tags are what the release workflow watches.
4
+
5
+ ## Current state
6
+
7
+ | Package | Version | Tag prefix | Published by |
8
+ |---|---|---|---|
9
+ | `@chenacc/agentbridge` (bridge + CLI) | 0.1.4 | `bridge-v*` | GitHub Actions on tag push, OIDC trusted publishing, SLSA provenance |
10
+ | `@chenacc/dsh-agentbridge` (DSH plugin) | 0.3.3 | `dsh-v*` | same workflow |
11
+
12
+ Pushing `bridge-v0.1.5` publishes the bridge; pushing `dsh-v0.3.4` publishes the plugin. See [`PUBLISHING.md`](./PUBLISHING.md) for the full procedure and the market side of a release.
4
13
 
5
14
  ## GitHub release checklist
6
15
 
7
16
  1. Choose and add an open-source license. Do not publish before this choice is explicit.
8
- 2. Create a Git repository and confirm no runtime data is staged. `.env`, `.agentbridge/`, logs, and `node_modules/` must remain excluded.
17
+ 2. Create a Git repository and confirm no runtime data is staged. `.env`, `.agentbridge/`, `~/.agentbridge/`, logs, and `node_modules/` must remain excluded.
9
18
  3. Run the release checks from the repository root:
10
19
 
11
20
  ```powershell
12
21
  npm ci
13
22
  npm run check
14
23
  npm test
24
+ npm run verify:release # plugin packaging acceptance, 17 checks
15
25
  npm pack --dry-run
16
26
  ```
17
27
 
18
- 4. Create a versioned commit and annotated tag such as `v0.1.0`, then push both the branch and tag to the public GitHub repository.
28
+ 4. Create a versioned commit and annotated tag — `bridge-v0.1.5` for the bridge, `dsh-v0.3.4` for the plugin — then push both the branch and tag to the public GitHub repository.
19
29
  5. On a clean machine with Node.js 22+ and Codex installed, verify the installation command below, restart Codex, and invoke `/phone` from a local-project conversation.
20
30
 
21
31
  ## User installation
@@ -23,13 +33,13 @@ This repository can be installed directly from a tagged public GitHub release. I
23
33
  Windows PowerShell:
24
34
 
25
35
  ```powershell
26
- npm install --global github:<github-owner>/<repository>#v0.1.0; agentbridge setup codex
36
+ npm install --global github:<github-owner>/<repository>#bridge-v0.1.4; agentbridge setup codex
27
37
  ```
28
38
 
29
39
  macOS/Linux:
30
40
 
31
41
  ```bash
32
- npm install --global github:<github-owner>/<repository>#v0.1.0 && agentbridge setup codex
42
+ npm install --global github:<github-owner>/<repository>#bridge-v0.1.4 && agentbridge setup codex
33
43
  ```
34
44
 
35
45
  `agentbridge setup codex` writes the user-level Codex skill. The package's CLI is installed globally and the generated skill records the installed CLI path, so do not replace this workflow with a temporary `npx` execution.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chenacc/agentbridge",
3
- "version": "0.1.3",
3
+ "version": "0.2.0",
4
4
  "description": "Control local coding agents from a phone through a secure WeChat QR web console.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -33,6 +33,13 @@
33
33
  "bin": {
34
34
  "agentbridge": "bin/agentbridge.js"
35
35
  },
36
+ "exports": {
37
+ ".": "./src/server.js",
38
+ "./server": "./src/server.js",
39
+ "./tunnel": "./src/tunnel.js",
40
+ "./package.json": "./package.json",
41
+ "./remote": "./src/remote.js"
42
+ },
36
43
  "engines": {
37
44
  "node": ">=22"
38
45
  },
@@ -58,7 +65,7 @@
58
65
  "verify:responsive": "node scripts/verify-responsive.mjs",
59
66
  "verify:guide": "node scripts/verify-product-guide.mjs",
60
67
  "verify:release": "node scripts/verify-plugin-release.mjs",
61
- "check": "node --check src/server.js && node --check src/cli.js && node --check src/config.js && node --check src/cc-switch-models.js && node --check src/workspaces/workspace-catalog.js && node --check src/conversations/conversation-catalog.js && node --check src/adapters/capabilities.js && node --check src/adapters/claude.js && node --check src/adapters/codex.js && node --check src/adapters/deepseek-harness.js && node --check src/adapters/dsh-desktop.js && node --check src/dsh-desktop-channels.js && node --check src/event-store.js && node --check src/notifier.js && node --check src/attachments.js && node --check src/session-manager.js && node --check integrations/dsh-phone/lib/index.js && node --check integrations/dsh-phone/lib/tunnel.js && node --check src/adapters/zcode-native.js && node --check public/adapter-capabilities.js && node --check public/workspace-navigation.js && node --check public/markdown.js && node --check public/highlight.js && node --check public/transcript.js && node --check public/app.js && node --check scripts/verify-workspace-ui.mjs && node --check scripts/verify-message-blocks.mjs && node --check scripts/verify-background-scrim.mjs && node --check scripts/verify-model-control.mjs && node --check scripts/verify-notifications.mjs && node --check scripts/verify-attachments.mjs && node --check scripts/verify-features.mjs && node --check scripts/verify-quick-nav.mjs && node --check scripts/verify-questions.mjs && node --check scripts/verify-responsive.mjs && node --check scripts/verify-product-guide.mjs && node --check scripts/verify-plugin-release.mjs",
68
+ "check": "node --check src/server.js && node --check src/cli.js && node --check src/config.js && node --check src/cc-switch-models.js && node --check src/workspaces/workspace-catalog.js && node --check src/conversations/conversation-catalog.js && node --check src/adapters/capabilities.js && node --check src/adapters/claude.js && node --check src/adapters/codex.js && node --check src/adapters/deepseek-harness.js && node --check src/adapters/dsh-desktop.js && node --check src/dsh-desktop-channels.js && node --check src/event-store.js && node --check src/notifier.js && node --check src/attachments.js && node --check src/session-manager.js && node --check integrations/dsh-phone/lib/index.js && node --check src/tunnel.js && node --check src/remote.js && node --check src/adapters/zcode-native.js && node --check public/adapter-capabilities.js && node --check public/workspace-navigation.js && node --check public/markdown.js && node --check public/highlight.js && node --check public/transcript.js && node --check public/app.js && node --check scripts/verify-workspace-ui.mjs && node --check scripts/verify-message-blocks.mjs && node --check scripts/verify-background-scrim.mjs && node --check scripts/verify-model-control.mjs && node --check scripts/verify-notifications.mjs && node --check scripts/verify-attachments.mjs && node --check scripts/verify-features.mjs && node --check scripts/verify-quick-nav.mjs && node --check scripts/verify-questions.mjs && node --check scripts/verify-responsive.mjs && node --check scripts/verify-product-guide.mjs && node --check scripts/verify-plugin-release.mjs",
62
69
  "verify:remote": "node scripts/verify-remote-tunnel.mjs"
63
70
  },
64
71
  "dependencies": {