@chenacc/agentbridge 0.1.4 → 0.2.1

package/.env.example

@@ -12,6 +12,27 @@ AGENTBRIDGE_PROJECTS=agentbridge=D:\codex_project\手机远程操控agent
 # Cloudflare quick tunnels set this automatically to https://<random>.trycloudflare.com
 # AGENTBRIDGE_PUBLIC_ORIGIN=https://agent.example.com
 
+# --- Cross-network path selection (read by both the CLI and the DSH plugin) ---
+# Which path the QR code uses. auto tries: named tunnel -> Funnel (only if it is
+# already on) -> Cloudflare quick tunnel -> Tailscale -> ZeroTier -> LAN.
+# AGENTBRIDGE_REMOTE=auto
+# AGENTBRIDGE_NO_TUNNEL=1                             # same as AGENTBRIDGE_REMOTE=lan
+# AGENTBRIDGE_TUNNEL_URL=https://fixed.example.com    # you run the tunnel yourself
+
+# Cloudflare named tunnel (needs `cloudflared tunnel create` + a domain on Cloudflare).
+# AGENTBRIDGE_CLOUDFLARE_TUNNEL=agentbridge
+# AGENTBRIDGE_CLOUDFLARE_HOSTNAME=bridge.example.com
+
+# Private overlays are detected automatically; these only point at unusual installs.
+# AGENTBRIDGE_TAILSCALE=C:\Program Files\Tailscale\tailscale.exe
+# AGENTBRIDGE_ZEROTIER=10.147.20.15
+
+# cloudflared is located on this machine, and downloaded to <data dir>/bin when
+# it is missing.
+# AGENTBRIDGE_CLOUDFLARED=D:\tools\cloudflared.exe   # use your own binary; no search, no download
+# AGENTBRIDGE_CLOUDFLARED_URL=https://mirror.example.com/cloudflared-windows-amd64.exe
+# AGENTBRIDGE_NO_DOWNLOAD=1                          # never fetch cloudflared automatically
+
 # Optional state location and expiry overrides.
 # AGENTBRIDGE_DATA_DIR=D:\agentbridge-data
 # AGENTBRIDGE_PAIRING_TTL_MS=120000

package/README.md

@@ -1,26 +1,62 @@
 # AgentBridge
 
-> 用微信扫一扫打开手机控制台，安全地查看、继续或停止这台电脑上正在运行的编程 Agent——不用把电脑暴露到公网，凭据始终留在本机。
+[![npm version](https://img.shields.io/npm/v/@chenacc/agentbridge?label=%40chenacc%2Fagentbridge&color=0e5a68)](https://www.npmjs.com/package/@chenacc/agentbridge)
+[![npm downloads](https://img.shields.io/npm/dm/@chenacc/agentbridge?color=0e5a68)](https://www.npmjs.com/package/@chenacc/agentbridge)
+[![DSH plugin](https://img.shields.io/npm/v/@chenacc/dsh-agentbridge?label=DSH%20plugin&color=2f6f7e)](https://www.npmjs.com/package/@chenacc/dsh-agentbridge)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+[![stars](https://img.shields.io/github/stars/chenacc1/agentbridge?style=social)](https://github.com/chenacc1/agentbridge/stargazers)
 
-![AgentBridge 架构：电脑上的本地 Bridge 连接已配对手机，并调用获准的编程 Agent 适配器。](./docs/assets/architecture.svg)
+**一条命令，把手机变成这台电脑上 Agent 的遥控器。** 微信扫码即用，不用装 App，也不用和电脑连同一个 Wi-Fi。
+
+| 桌面端在干活 | 手机扫一扫就接管 | 手机端同一份对话 |
+|---|---|---|
+| <img src="./docs/assets/screen-desktop-console.jpg" alt="桌面端控制台" width="330" /> | <img src="./docs/assets/screen-mobile-1.png" alt="手机端控制台 1" width="180" /> | <img src="./docs/assets/screen-mobile-2.png" alt="手机端控制台 2" width="180" /> |
+
+```powershell
+npx @chenacc/agentbridge        # 起桥并直接打印二维码
+```
 
-手机与桌面共享同一份可追加事件流，因此消息、工具活动、审批和任务状态始终同步。电脑是唯一的执行端：手机只下发命令，不运行 Agent，也拿不到任何供应商凭据。
+然后在 Claude Code / Codex / DSH Desktop 里输入 `/phone`，扫二维码即可。凭据和文件访问始终留在本机，手机只下发命令。
+
+> 觉得有用就给个 star：[github.com/chenacc1/agentbridge](https://github.com/chenacc1/agentbridge) —— 不点也不影响任何功能，只影响我有没有动力继续写。
+
+手机与桌面共享同一份可追加事件流，因此消息、工具活动、审批和任务状态始终同步。电脑是唯一的执行端：手机只运行界面，不运行 Agent，也拿不到任何供应商凭据。
+
+默认走 Cloudflare 隧道：手机用流量、在外地都能打开；隧道对外开放，因此自动带一道访问密钥门禁。
+
+**当前版本：** 桥 `@chenacc/agentbridge` **0.2.0** · DSH 插件 `@chenacc/dsh-agentbridge` **0.4.0**（两个包各自发布，见文末「版本与发布」）。
 
 ## 它是怎么工作的
 
+![AgentBridge 架构：电脑上的本地 Bridge 连接已配对手机，并调用获准的编程 Agent 适配器。](./docs/assets/architecture.svg)
+
 ![三端结构：手机控制面、本地 Bridge、电脑执行端](./docs/assets/keyframe-02-three-tier.jpg)
 
 1. **手机** 只负责界面与指令：扫码进入 H5 控制台，选工作区、选会话，发出消息、审批与停止命令。
 2. **本地 Bridge** 是唯一枢纽：校验设备、维持会话与输入租约，把命令写进可追加事件流，再经 SSE 推回手机。
 3. **电脑上的 Agent 子进程** 真正执行任务，凭据与文件访问始终留在本机，手机侧拿不到。
 
+远程时中间多一跳，但入口仍然是桥：
+
+```
+手机 ──公网 HTTPS──> Cloudflare 边缘 ──隧道──> cloudflared（你电脑上的进程）
+                                                      │
+                                                      ▼
+                                        AgentBridge 桥（127.0.0.1:8787）
+                                                      │
+                                                      ▼
+                            Claude Code / Codex / DeepSeek Harness / DSH Desktop 里的那条会话
+```
+
 因为上行与下行共用同一条事件流，桌面端和手机看到的是同一份状态，而不是两套各自猜测的界面。
 
 > 本文中标注为「分镜关键帧」的图片是讲解视频的概念示意图，用于说明结构关系；真实界面见下文「界面」一节。
 
+
 ## 主要能力
 
 - **扫码配对**：一次性、5 分钟有效的二维码；配对后收藏固定回访地址，之后免扫码进入。
+- **跨网络直接可用**：默认自动开 Cloudflare 隧道，二维码就是公网 https 地址，手机无需安装任何 App。
 - **工作区 → 会话导航**：一个抽屉管理「Agent → 项目 → 会话」，Bridge 重启后历史与会话不丢失。
 - **完整对话控制**：流式输出、停止、接管输入、翻看历史，表格 / 公式 / 代码块正确渲染。
 - **远程协作**：审批卡片、提问卡片、限时自动放行（5/10/30 分钟）、消息排队、会话内搜索。
@@ -40,6 +76,7 @@
 | Node.js | **22 或更高**，`node -v` 确认 |
 | 操作系统 | Windows（一键脚本齐全）；Linux / macOS 直接用 `npm start` |
 | Agent 工具 | 可选，按需安装：Claude Code / Codex / DeepSeek Harness / DSH Desktop |
+| cloudflared | **不需要手动准备**：缺了会自动下载（见下一节） |
 
 AgentBridge 不替你安装或登录任何 Agent，只检测本机**已安装且已登录**的那些；没装的显示「未安装」，不会假装可用。
 
@@ -68,7 +105,7 @@ $env:AGENTBRIDGE_PROJECTS = "agentbridge=D:\projects\agentbridge"   # 可选：
 npm start
 ```
 
-打开 [http://127.0.0.1:8787](http://127.0.0.1:8787)，桌面页会显示一次性二维码；手机连同一可信 Wi-Fi，用微信「扫一扫」扫描即可。
+打开 [http://127.0.0.1:8787](http://127.0.0.1:8787)，桌面页会显示一次性二维码，用微信「扫一扫」即可。
 
 > 二维码只用于首次配对，会过期且**只能使用一次**。配对成功后请收藏手机页显示的固定回访地址，之后从收藏进入；不要收藏 `/pair?code=...` 临时链接。
 > `AGENTBRIDGE_PROJECTS` 可以不写：不设时默认把**启动目录**作为唯一可用项目，别名 `workspace`。别名只允许字母、数字、`_`、`-`（≤40 字符）。
@@ -81,61 +118,121 @@ npx @chenacc/agentbridge phone --agent echo
 # 从仓库跑的话：node .\bin\agentbridge.js phone --agent echo
 ```
 
-Echo 适配器不接触任何 AI 工具，只验证「CLI → 本机 Bridge → 生成配对二维码」整条链路。能打印二维码就说明安装正确，扫码后可看到手机与桌面同步。
+Echo 适配器不接触任何 AI 工具，只验证「CLI → 本机 Bridge → 生成配对二维码」整条链路。能打印二维码就说明安装正确，扫码后可看到手机与桌面同步。终端里除了二维码，还会打出两行关键信息：
 
-## 一键启动与停止（Windows）
+```
+网络: 公网地址，手机用流量也能打开
+微信扫码地址: https://xxx.trycloudflare.com/pair?code=…&key=…
+```
 
-| 入口 | 用途 |
-|---|---|
-| `启动 AgentBridge.cmd` | 局域网模式：检查服务健康、避免重复占用 8787、后台启动并打开控制台 |
-| `启动 AgentBridge 远程模式.cmd` | Tailscale 模式，跨网络使用 |
-| `启动 AgentBridge ZeroTier 远程模式.cmd` | ZeroTier 模式，Tailscale 不稳定时使用 |
-| `启动 AgentBridge Cloudflare 远程模式.cmd` | Cloudflare Tunnel，手机不需装任何 App |
-| `安全停止 AgentBridge.cmd` | 安全停止：不误杀其它进程、有任务在跑时拒绝停止、绝不强制 kill |
+第一次运行会自动下载 `cloudflared`（约 55 MB），所以首次可能要等几秒到几十秒；之后再运行就是秒级。
+
+## 网络与远程接入
 
-日志在 `.agentbridge/logs`；桌面快捷方式用 `.\scripts\install-agentbridge-shortcut.ps1` 创建或刷新。
+### 二维码里的地址是怎么定的
 
-## 远程接入方式
+CLI 和插件共用同一套逻辑（`src/remote.js`），按下面的顺序决定二维码写什么：
 
-| 场景 | 模式 | 手机要求 |
+| 优先级 | 条件 | 二维码地址 |
 |---|---|---|
-| 什么都不装、也不连同一个 Wi-Fi（DSH 插件默认） | Cloudflare Tunnel（自动） | 只需浏览器 |
-| 同一可信 Wi-Fi | 局域网 | 浏览器 / 微信 |
-| 跨网络，但属同一私有网络 | Tailscale | 同一 tailnet |
-| Tailscale 不稳定 | ZeroTier | 同一私有网络 |
-| 手机装不了 VPN 类 App | Cloudflare Tunnel | 只需浏览器 |
+| 1 | 设了 `AGENTBRIDGE_PUBLIC_ORIGIN` | 你给的那个（Tailscale、ZeroTier、自己的域名都走这条） |
+| 2 | 已有桥正在用公网地址运行 | 复用它，不再开新通道 |
+| 3 | 设了 `AGENTBRIDGE_NO_TUNNEL=1` 或 `AGENTBRIDGE_REMOTE=lan` | 局域网 |
+| 4 | `AGENTBRIDGE_REMOTE` 指定了某一条（`funnel` / `named` / `tailscale` / `zerotier` / `cloudflare`） | 只试那一条 |
+| 5 | 默认 `auto` | 按下面「五种远程路径」的顺序试，成功即停 |
+| 6 | 全都不成立 | 局域网，日志里逐条说明每条为什么失败 |
+
+### 五种远程路径
+
+`auto`（默认）的尝试顺序：**命名隧道 → Funnel → Cloudflare quick → Tailscale → ZeroTier → 局域网**。下表的“自动”指装好就能用、不需要你手动跑脚本。
+
+| 路径 | 自动？ | 手机要求 | 代价 |
+|---|---|---|---|
+| Cloudflare quick tunnel | ✅ 缺 `cloudflared` 会自己下 | 只需浏览器 | 域名每次重建会变 |
+| 局域网 | ✅ 兜底 | 浏览器 / 微信 | 出门就不可用 |
+| Tailscale（私有地址） | ✅ 已登录且在线才用 | 同一 tailnet（装 App） | 手机要常驻 VPN 类 App |
+| ZeroTier（私有地址） | ✅ 检测到 ZeroTier 网卡才用 | 同一私有网络（装 App） | 同上 |
+| Tailscale Funnel | 🟡 需 `AGENTBRIDGE_REMOTE=funnel` 显式开启；`auto` 只复用已开启的 | 只需浏览器 | 要在 Tailscale 管理台开启 Funnel |
+| Cloudflare 命名隧道 | 🟡 需配隧道名 + 域名 | 只需浏览器 | 域名要托管在 Cloudflare |
+
+Funnel 单独放在“要显式开启”这一档，是因为开启它会改动你 tailnet 的对外暴露配置——这种事不该由一次扫码替你决定。反过来，**已经开着的** Funnel 会被 `auto` 直接复用。
+
+只想用某一条路径：
+
+```powershell
+$env:AGENTBRIDGE_REMOTE = "funnel"    # 或 named | cloudflare | tailscale | zerotier | lan
+agentbridge phone --agent claude
+```
+
+命名隧道需要两个变量：
+
+```powershell
+$env:AGENTBRIDGE_CLOUDFLARE_TUNNEL = "agentbridge"        # cloudflared 里已经建好的隧道名
+$env:AGENTBRIDGE_CLOUDFLARE_HOSTNAME = "bridge.example.com"
+```
+
+当前路径会同时出现在三个地方：CLI 输出的「网络:」一行、桥启动日志的 `Remote path:` 一行、`/api/health` 的 `remoteProvider` 字段——二维码打不开时先看这三处。
 
 ![分镜关键帧：四条网络路径分别接入同一台 Windows Host，其中 Cloudflare 路径还要经过一道访问密钥门禁](./docs/assets/keyframe-09-network-paths.jpg)
 
-任何模式都不要把 TCP 8787 直接映射到公网。Cloudflare 模式额外启用访问密钥闸门（密钥存于 `.agentbridge/access-key`），光有二维码不够。
+任何模式都**不要**把 TCP 8787 直接映射到公网。Cloudflare 模式会额外启用访问密钥闸门，光有二维码不够。
+
+### cloudflared 是自动的
+
+插件和 CLI 都会先在本机找 `cloudflared`（PATH、两处 Program Files、winget 目录、`~/.agentbridge/bin`），都找不到时才从 Cloudflare 官方的 GitHub Releases 下载一份到 `%USERPROFILE%\.agentbridge\bin\cloudflared.exe`：不要管理员权限、不写系统目录、删掉那个文件夹就等于卸载。下载完会先跑一次 `cloudflared --version`，验不过的文件不会留下。
+
+想自己装也行（`winget install --id Cloudflare.cloudflared`），已装的那份优先。断网或代理挡住下载时，一切照常，只是退回局域网。
 
 ### 访问密钥：会不会变、怎么换
 
-密钥就是一句口令，不是账号。门禁只在**用 Cloudflare 隧道启动时**打开——其余模式（局域网 / Tailscale / ZeroTier）默认没有门禁，也就不会有人问你密钥。门禁打开时，所有非本机（loopback）请求都必须带上它：二维码里已内嵌 `?key=…`，手机用它换一个 90 天有效的 cookie（`agentbridge_key`）。
+密钥就是一句口令，不是账号。它只在**对公网开放时**生效（quick tunnel / 命名隧道）；局域网、Tailscale、ZeroTier 默认没有门禁，也就不会有人问你密钥。门禁打开时，所有非本机（loopback）请求都必须带上它：二维码里已内嵌 `?key=…`，手机用它换一个 90 天有效的 cookie（`agentbridge_key`）。
+
+密钥文件有两个位置，取决于谁在开隧道：
 
-**默认是固定的。** `scripts/start-agentbridge.ps1` 里的 `Get-OrCreateAccessKey` 先读 `.agentbridge/access-key`：只要文件存在、内容非空且不短于 16 个字符，就原样复用。所以重启、换端口、换隧道地址都不会改它。会变的情况只有三种：
+| 谁来开隧道 | 密钥文件 |
+|---|---|
+| CLI / DSH 插件（默认路径） | `%USERPROFILE%\.agentbridge\access-key` |
+| 仓库里的一键脚本 `.cmd` | `<仓库>\.agentbridge\access-key` |
 
-1. 删掉（或清空、或写短于 16 个字符）`.agentbridge/access-key`；
-2. 换了一份代码目录（文件跟着目录走，不同 `$bridgeRoot` 各有一把）；
-3. 该目录第一次以 Cloudflare 模式启动。
+两者都是**先读后写**：文件存在、内容非空且不短于 16 个字符就原样复用，所以重启、换端口、换隧道地址都不会改它。会变的只有三种情况：删掉（或清空、或写短于 16 个字符）该文件；换了一份代码目录；该目录第一次以 Cloudflare 模式启动。
 
 **换法**（三步，不需要改代码）：
 
 ```powershell
-scripts\stop-agentbridge.ps1                          # 1. 停桥
-Remove-Item .agentbridge\access-key                   # 2a. 让下次启动生成新串
+# 1. 停掉桥（安全停止脚本，或结束占用 8787 的进程）
+scripts\stop-agentbridge.ps1
+
+# 2a. 让下次启动生成新串
+Remove-Item "$env:USERPROFILE\.agentbridge\access-key"
 # 或者直接写自己的口令（≥16 字符，别加换行）：
-# "my-own-long-passphrase" | Set-Content .agentbridge\access-key -NoNewline -Encoding ascii
-scripts\start-agentbridge.ps1 -CloudflareTunnel       # 3. 启动，窗口会打印新串
+# "my-own-long-passphrase" | Set-Content "$env:USERPROFILE\.agentbridge\access-key" -NoNewline -Encoding ascii
+
+# 3. 重启（重启 DSH Desktop，或再跑一次 agentbridge phone）
 ```
 
-换完所有手机都要重新扫码或用新串（旧 cookie 不再匹配）。注意 Cloudflare 模式下脚本会**无条件**用文件里的值覆盖 `AGENTBRIDGE_ACCESS_KEY` 环境变量，所以“只设环境变量”在那里不管用——想自定义口令就写进文件；非隧道模式下才是靠环境变量。
+换完所有手机都要重新扫码（旧 cookie 不再匹配）。`.agentbridge/` 已在 `.gitignore` 中，密钥不会进版本库；但也别把带 `?key=` 的完整链接贴到公开场合。推送通知的跳转链接默认**不带**密钥（`notifyLink` 需要显式开启），所以换钥匙不影响通知。
+
+### 局域网地址是怎么挑的
+
+自动选地址时会跳过 `169.254.x.x`（网卡没拿到租约时的临时地址，手机根本路由不到）和 Hyper-V / WSL / 蓝牙 / Wi-Fi Direct 这类虚拟网卡，优先真实的 Wi-Fi 或以太网地址。扫码后如果微信弹出「该地址为 IP 地址，请使用域名访问网站」，点「继续访问」即可。
+
+## 一键启动与停止（Windows）
+
+| 入口 | 用途 |
+|---|---|
+| `启动 AgentBridge.cmd` | 局域网模式：检查服务健康、避免重复占用 8787、后台启动并打开控制台 |
+| `启动 AgentBridge 远程模式.cmd` | Tailscale 模式，跨网络使用 |
+| `启动 AgentBridge ZeroTier 远程模式.cmd` | ZeroTier 模式，Tailscale 不稳定时使用 |
+| `启动 AgentBridge Cloudflare 远程模式.cmd` | Cloudflare Tunnel，手机不需装任何 App（不做自动下载，缺 `cloudflared` 会直接报错并提示安装） |
+| `安全停止 AgentBridge.cmd` | 安全停止：不误杀其它进程、有任务在跑时拒绝停止、绝不强制 kill |
+
+这些脚本自己设置 `AGENTBRIDGE_PUBLIC_ORIGIN` 和访问密钥，和 CLI / 插件的自动模式**不要同时用**：同一端口只能有一个桥在跑，后启动的那个会连上已有实例而不是另起一个。
 
-`.agentbridge/` 已在 `.gitignore` 中，密钥不会进版本库；但也别把带 `?key=` 的完整链接贴到公开场合。推送通知的跳转链接默认**不带**密钥（`notifyLink` 需要显式开启），所以换钥匙不会影响通知。
+日志在 `<仓库>\.agentbridge\logs`；桌面快捷方式用 `.\scripts\install-agentbridge-shortcut.ps1` 创建或刷新。
 
 ## 让 Agent 支持 `/phone`
 
-`/phone` 不是 Agent 自带的功能，而是 AgentBridge 往对应客户端里装的一个**技能**（一个 `SKILL.md` 文件）。它只做一件事：在**当前项目目录**里调用 `agentbridge phone --agent <id>`，由 CLI 确保 Bridge 在运行、创建或附加会话、打印一次性二维码。
+`/phone` 不是 Agent 自带的功能，而是 AgentBridge 往对应客户端里装的一个**技能**（一个 `SKILL.md` 文件）。它只做一件事：在**当前项目目录**里调用 `agentbridge phone --agent <id>`，由 CLI 确保 Bridge 在运行、准备公网地址、创建或附加会话、打印一次性二维码。
 
 三个前提，每个 Agent 都一样：
 
@@ -145,16 +242,18 @@ scripts\start-agentbridge.ps1 -CloudflareTunnel       # 3. 启动，窗口会打
 
 技能是纯文本文件，删掉对应的 `SKILL.md` 就等于卸载。
 
-二维码默认是**公网地址**（走 Cloudflare 隧道，手机用流量也能扫）。隧道要用的 `cloudflared` 缺了就自动下载到 `~/.agentbridge/bin`，和 DSH 插件共用同一套逻辑、同一个隧道和同一把访问密钥——DSH 那边已经开着隧道的话，CLI 直接复用，不会再起一条。只想在局域网用就设 `AGENTBRIDGE_NO_TUNNEL=1`；已经有自己的公网入口（命名隧道、Tailscale、ZeroTier）就设 `AGENTBRIDGE_PUBLIC_ORIGIN`。
+二维码默认是**公网地址**，三条路径共用同一套逻辑、同一条隧道、同一把访问密钥：`cloudflared` 缺了就自动下载；DSH 插件已经开着隧道时，CLI 直接复用它，不会再起一条。只想在局域网用就设 `AGENTBRIDGE_NO_TUNNEL=1`；已有自己的公网入口就设 `AGENTBRIDGE_PUBLIC_ORIGIN`。
+
+> 一个例外：如果本机已经有一个**以局域网地址**运行的桥（比如很久以前启动的旧进程），CLI 不会擅自重启它——那会打断正在跑的会话——只会提示本次沿用那个地址。停掉它或重启 DSH Desktop 即可换成公网地址。
 
 ### Claude Code
 
 ```powershell
 # 用户级（默认）：%USERPROFILE%\.claude\skills\phone\SKILL.md
-node .\bin\agentbridge.js install-claude-skill --user
+agentbridge install-claude-skill --user
 
 # 只装给某个项目：<项目>\.claude\skills\phone\SKILL.md
-node .\bin\agentbridge.js install-claude-skill --project --cwd D:\projects\agentbridge
+agentbridge install-claude-skill --project --cwd D:\projects\agentbridge
 ```
 
 重启 Claude Code，在项目目录输入 `/phone`。技能用官方 `${CLAUDE_SESSION_ID}` 绑定**当前这段对话**，不读私有 transcript、不猜路径；只预授权 `agentbridge phone --agent claude …` 这一条命令，不授予通用 Bash 权限。
@@ -165,24 +264,20 @@ node .\bin\agentbridge.js install-claude-skill --project --cwd D:\projects\agent
 
 ```powershell
 # 用户级（默认）：%USERPROFILE%\.agents\skills\phone\SKILL.md
-node .\bin\agentbridge.js install-codex-skill --user
+agentbridge install-codex-skill --user
 ```
 
 重启 Codex 桌面项目，在本地项目会话输入 `/phone`。Codex 没对外提供「当前线程 ID」，所以不带参数时它会在同一项目目录**新建**一个会话并明确标注；只有你已知 thread ID 时才精确附加：
 
 ```powershell
-node .\bin\agentbridge.js phone --agent codex --session <thread-id>
+agentbridge phone --agent codex --session <thread-id>
 ```
 
 ### DSH Desktop
 
 前提：DSH Desktop 已安装，且存在桌面 profile `%USERPROFILE%\.dsh\profiles\desktop\package.json`（或由 `DSH_HOME` 指定）。
 
-**第 0 步：桥。** 插件是遥控器，桥是基站。从 0.2.0 起桥随插件一起安装，**DSH Desktop 启动时插件会自己在后台把它拉起来**，正常情况你什么都不用敲。
-
-从 0.3.0 起，插件默认再开一条 **Cloudflare 隧道**，把桥映射成公网 https 域名，于是手机不必和电脑在同一个 Wi-Fi——扫码、出差、用流量都能开。隧道要用的 `cloudflared`（Cloudflare 官方客户端）同样是自动的：先找本机已有的那份，找不到就自己从官方 GitHub Releases 下到 `~/.agentbridge/bin`（约 55 MB，只下一次，不要管理员权限，下载后跑一次 `cloudflared --version` 验证才留下）。
-
-想自己装也行：`winget install --id Cloudflare.cloudflared`。下不动（断网、公司代理）照样能用，只是退回"手机与电脑同一 Wi-Fi"。想一直走局域网，设 `AGENTBRIDGE_NO_TUNNEL=1`；想用固定域名，去 Cloudflare 建命名隧道并把 `AGENTBRIDGE_PUBLIC_ORIGIN` 指向它。
+**第 0 步：桥。** 插件是遥控器，桥是基站。从 0.2.0 起桥随插件一起安装，**DSH Desktop 启动时插件会自己在后台把它拉起来**；从 0.3.0 起还会再自动开 Cloudflare 隧道。所以正常情况你什么都不用敲，重启桌面等几秒后直接 `/phone`。
 
 只有自动启动失败（沙箱限制、端口被占）才需要手动来一条：
 
@@ -190,21 +285,15 @@ node .\bin\agentbridge.js phone --agent codex --session <thread-id>
 npx @chenacc/agentbridge
 ```
 
-想长期使用、或要改配置（项目白名单、远程通道、通知推送），装成全局命令：
-
-```powershell
-npm install -g @chenacc/agentbridge    # 之后随时 agentbridge phone --agent claude
-```
-
-也可以从仓库跑：`git clone https://github.com/chenacc1/agentbridge.git` → `cd agentbridge` → `npm install` → `npm start`（或双击「启动 AgentBridge.cmd」）。
-
-**第 1 步：装插件（普通用户走市场）**：设置 → 插件市场 → 发现，搜 `AgentBridge` 或 `@chenacc/dsh-agentbridge` → 安装 → 重启 DSH Desktop。等价的命令行安装：
+**第 1 步：装插件（普通用户走市场）**：设置 → 插件市场 → 发现，搜 `AgentBridge` 或 `@chenacc/dsh-agentbridge` → 安装 → 重启 DSH Desktop。等价的手动安装：
 
 ```powershell
 cd "$env:USERPROFILE\.dsh\profiles\desktop"; pnpm add @chenacc/dsh-agentbridge@latest
 # 装完还需把 "@chenacc/dsh-agentbridge" 加进该 package.json 的 dsh.profile.bundles（市场安装会自动做）
 ```
 
+> 市场卡片上显示的版本号来自插件目录快照，每天刷新一次；实际安装拉的是 npm 的 `latest`，所以卡片版本可能比装到的版本旧一天。
+
 **从本地源码装（开发者）**：
 
 ```powershell
@@ -228,26 +317,25 @@ npm run uninstall:dsh-phone
 前提：官方 `dsh` CLI 已安装并配置好模型与凭据，`dsh --profile acp --help` 能打印帮助（而不是弹出浏览器界面）。这个适配器没有斜杠技能，直接用 CLI：
 
 ```powershell
-node .\bin\agentbridge.js phone --agent deepseek-harness
+agentbridge phone --agent deepseek-harness
 ```
 
 ### 一张表汇总
 
-| Agent | 前提 | 要执行的安装命令 | 重启客户端 | 入口 |
-|---|---|---|---|---|
-| Claude Code | 已安装并登录 | `install-claude-skill --user` | 需要 | `/phone` |
-| Codex Desktop | 已安装并登录 | `install-codex-skill --user` | 需要 | `/phone` |
-| DSH Desktop | 存在桌面 profile | `npm run install:dsh-phone` | 需要 | `/phone` |
-| DeepSeek Harness | `dsh --profile acp --help` 可用 | 不需要 | — | `phone --agent deepseek-harness` |
-| Echo | 无 | 不需要 | — | `phone --agent echo` |
-| ZCode | 仅官方 Remote Control / Bot Channel | 不需要 | — | AgentBridge 不代管 |
+| Agent | 前提 | 要执行的安装命令 | 重启客户端 | 入口 | 二维码默认地址 |
+|---|---|---|---|---|---|
+| Claude Code | 已安装并登录 | `agentbridge install-claude-skill --user` | 需要 | `/phone` | 公网 |
+| Codex Desktop | 已安装并登录 | `agentbridge install-codex-skill --user` | 需要 | `/phone` | 公网 |
+| DSH Desktop | 存在桌面 profile | 插件市场安装（或 `pnpm add`） | 需要 | `/phone` | 公网 |
+| DeepSeek Harness | `dsh --profile acp --help` 可用 | 不需要 | — | `phone --agent deepseek-harness` | 公网 |
+| Echo | 无 | 不需要 | — | `phone --agent echo` | 公网 |
+| ZCode | 仅官方 Remote Control / Bot Channel | 不需要 | — | AgentBridge 不代管 | — |
 
 ### 通用说明
 
 - `/phone` 只接受来自本机 loopback 的绝对路径，手机会话无法提交任意目录。
 - 想让 `agentbridge` 成为全局命令，在仓库里跑一次 `npm link`。
-- 仓库目前尚未创建 `v0.1.0` 标签；打上固定标签后，别人可用一行装好 CLI 与 Codex 技能：
-  `npm install --global github:chenacc1/agentbridge#v0.1.0; agentbridge setup codex`
+- 想从固定版本装：`npm install --global github:chenacc1/agentbridge#bridge-v0.1.4`，然后 `agentbridge setup codex` 装技能。
 
 ## 支持的 Agent
 
@@ -278,19 +366,45 @@ node .\bin\agentbridge.js phone --agent deepseek-harness
 
 完整变量见 [`.env.example`](./.env.example)。
 
+**桥本身：**
+
 | 变量 | 默认值 | 含义 |
 |---|---|---|
 | `AGENTBRIDGE_PORT` | `8787` | HTTP 监听端口 |
+| `AGENTBRIDGE_HOST` | `0.0.0.0` | 监听地址 |
 | `AGENTBRIDGE_PROJECTS` | 当前目录 | 项目白名单，分号分隔 `别名=绝对路径` |
-| `AGENTBRIDGE_PUBLIC_ORIGIN` | 第一个 LAN 地址 | 写入二维码的访问地址 |
+| `AGENTBRIDGE_DATA_DIR` | `~/.agentbridge`（CLI / 插件）/ 启动目录（`npm start`） | 会话、事件、密钥、隧道状态的目录 |
+| `AGENTBRIDGE_PUBLIC_ORIGIN` | 自动（公网隧道或局域网地址） | 写进二维码的访问地址；设了它就不再自动开隧道 |
+| `AGENTBRIDGE_ACCESS_KEY` | 未设置 | 访问密钥；对公网开放时自动生成并写入 `access-key` 文件 |
 | `AGENTBRIDGE_PAIRING_TTL_MS` | `300000` | 配对码有效期（5 分钟） |
 | `AGENTBRIDGE_SESSION_TTL_MS` | `259200000` | 设备会话有效期（72 小时） |
 | `AGENTBRIDGE_CLAUDE_MODEL` | 供应商默认 | 可选的 Claude / Kimi 模型 ID |
 | `AGENTBRIDGE_NOTIFY_WEBHOOK` | 未设置 | 通知 Webhook；未设置时该功能静默 |
 
-若自动选择的局域网地址手机访问不到，显式指定 `AGENTBRIDGE_PUBLIC_ORIGIN`；Windows 防火墙提示时只放行「专用网络」。
+**跨网络（CLI 与插件都认）：**
+
+| 变量 | 默认值 | 含义 |
+|---|---|---|
+| `AGENTBRIDGE_REMOTE` | `auto` | 走哪条路径：`auto` / `cloudflare` / `named` / `funnel` / `tailscale` / `zerotier` / `lan` |
+| `AGENTBRIDGE_NO_TUNNEL` | 未设置 | 设为 `1` 等价于 `AGENTBRIDGE_REMOTE=lan` |
+| `AGENTBRIDGE_TUNNEL_URL` | 未设置 | 直接指定隧道域名（给"隧道自己管"的人） |
+| `AGENTBRIDGE_CLOUDFLARE_TUNNEL` | 未设置 | Cloudflare **命名隧道**的名字；设了它 `auto` 会优先用它 |
+| `AGENTBRIDGE_CLOUDFLARE_HOSTNAME` | 未设置 | 命名隧道对应的公网域名 |
+| `AGENTBRIDGE_CLOUDFLARED` | 自动查找 | 用你自己那份 `cloudflared`；设了它既不搜索也不下载 |
+| `AGENTBRIDGE_CLOUDFLARED_URL` | 官方 Releases | 换下载源（内网镜像），下载后照样过 `--version` 校验 |
+| `AGENTBRIDGE_NO_DOWNLOAD` | 未设置 | 设为 `1` 禁止自动下载 `cloudflared` |
+| `AGENTBRIDGE_TAILSCALE` | 自动查找 | 指定 `tailscale` 可执行文件（装在非常规位置时用） |
+| `AGENTBRIDGE_ZEROTIER` | 自动检测网卡 | 直接指定 ZeroTier 分配到的 IPv4 |
+
+**插件 / CLI 专用：**
+
+| 变量 | 默认值 | 含义 |
+|---|---|---|
+| `AGENTBRIDGE_ORIGIN` | `http://127.0.0.1:8787` | 插件连接的本地桥地址 |
+| `AGENTBRIDGE_LOCAL_ORIGIN` | `http://127.0.0.1:8787` | CLI 连接的本地桥地址 |
+| `AGENTBRIDGE_NO_AUTOSTART` | 未设置 | 设为 `1` 关掉"插件加载时自动起桥" |
 
-自动选地址时会跳过 `169.254.x.x`（网卡没拿到租约时的临时地址，手机根本路由不到）和 Hyper-V / WSL / 蓝牙这类虚拟网卡，优先真实的 Wi-Fi 或以太网地址。扫码后如果微信弹出「该地址为 IP 地址，请使用域名访问网站」，点「继续访问」即可；手机上不了网、或者只有手机流量没连同一个 Wi-Fi 时，二维码里的地址是打不开的。
+变量要设在**真正启动 DSH Desktop / 终端的环境里**，不是设在跑桥的另一个窗口里。
 
 ## 安全边界
 
@@ -298,21 +412,54 @@ node .\bin\agentbridge.js phone --agent deepseek-harness
 
 - 二维码里是一次性配对码，不是 Agent 凭据；磁盘只保存设备 token 的 SHA-256 摘要。
 - 设备 cookie 为 `HttpOnly` + `SameSite=Strict`；修改型请求校验同源，命令 ID 防重放，同一会话同时只有一台设备持有输入租约。
+- 对公网开放时访问密钥强制开启，非 loopback 请求一律要求带密钥；密钥不写进命令行、不进日志。
+- 桥的本地管理接口（配对、注册、停止、`cloudflared` 状态）只接受 loopback；即便是同一台机器上的"要求桥重启"这类动作，也要带上插件在启动时生成的一次性 token。
 - Agent 凭据与子进程始终留在电脑上，手机永远不是执行环境。
 - 当前不提供多用户授权、静态加密事件日志、重启后活动子进程恢复或云端 Relay。
 
+> 默认公网可用意味着**二维码等同于钥匙**：别截图外传，也别把带 `?key=` 的链接贴到公开场合。只想在家里用时设 `AGENTBRIDGE_NO_TUNNEL=1`。
+
 ## 验证
 
 ```powershell
-npm run check           # 语法检查
-npm test                # 单元与集成测试（当前 187 项全部通过）
+npm run check           # 语法检查（38 个文件）
+npm test                # 单元与集成测试（当前 240 项全部通过）
+npm run verify:release  # 插件发布验收（17 项：registry / tarball / 可导入性）
+npm run verify:remote   # 端到端验证 Cloudflare 远程链路，需要 cloudflared 与网络
 npm run verify:mobile   # 可选：真实浏览器端到端，需要 Chrome 或 Edge
 ```
 
-其余 `verify:*` 脚本（`navigation`、`models`、`scrim`、`notify`、`attach`、`features`、`blocks`、`questions`、`quicknav`）各自启动真实 Bridge 与无头浏览器做界面验证。
+其余 `verify:*` 脚本（`navigation`、`models`、`scrim`、`notify`、`attach`、`features`、`blocks`、`questions`、`quicknav`、`responsive`、`guide`）各自启动真实 Bridge 与无头浏览器做界面验证。
+
+## 版本与发布
+
+两个 npm 包，各自独立发版，都由 GitHub Actions 用 tag 触发（OIDC 可信发布，带 SLSA provenance）：
+
+| 包 | 当前版本 | tag 前缀 | 装到哪 |
+|---|---|---|---|
+| `@chenacc/agentbridge` | `0.2.0` | `bridge-v*` | 全局命令 / `npx` / 插件依赖 |
+| `@chenacc/dsh-agentbridge` | `0.4.0` | `dsh-v*` | DSH Desktop 的 profile |
+
+最近的阶段性变化：
+
+- **0.2.0（桥）**：路径选择抽成 provider（`src/remote.js`）——Cloudflare quick / 命名隧道 / Tailscale / Tailscale Funnel / ZeroTier 共用一套顺序与回退，`AGENTBRIDGE_REMOTE` 可指定单条；`/api/health` 与启动日志会报出当前走的是哪条。
+- **0.1.1–0.1.4（桥）**：二维码地址改按"能不能被手机路由到"排序（跳过 `169.254` 与虚拟网卡）；`/api/health` 汇报自己广播的地址；新增只有本机 token 能调的自动重启入口；隧道能力下沉到本包，CLI 的 `/phone` 因此也默认公网。
+- **0.4.0（插件）**：改用桥包里的同一套路径选择，本地行为不变但多了 Funnel / Tailscale / ZeroTier 三条可选路径。
+- **0.3.0–0.3.3（插件）**：加载时自动起桥、自动开 Cloudflare 隧道、`cloudflared` 缺失时自动下载。
+
+升级方式：
+
+```powershell
+npm install -g @chenacc/agentbridge@latest            # CLI / 桥
+cd "$env:USERPROFILE\.dsh\profiles\desktop"
+pnpm add @chenacc/dsh-agentbridge@latest              # DSH 插件（或直接在插件市场点安装）
+```
 
 ## 更多文档
 
 - 架构说明：[`docs/architecture/wechat-multi-agent-remote-control.md`](./docs/architecture/wechat-multi-agent-remote-control.md)
 - 功能与前端执行逻辑：[`docs/软件功能与前端执行逻辑.md`](./docs/软件功能与前端执行逻辑.md)
-- 发布流程：[`docs/RELEASING.md`](./docs/RELEASING.md)
+- 发布流程：[`docs/PUBLISHING.md`](./docs/PUBLISHING.md)
+- 安装验收清单：[`docs/verify-plugin-install.md`](./docs/verify-plugin-install.md)
+- 市场收录记录：[`docs/market-submission.md`](./docs/market-submission.md)
+- 版本与更新记录：[`docs/RELEASING.md`](./docs/RELEASING.md)

package/docs/RELEASING.md

@@ -1,21 +1,31 @@
 # Releasing AgentBridge
 
-This repository can be installed directly from a tagged public GitHub release. It does not require npm publication for the first public release.
+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.
+
+## Current state
+
+| Package | Version | Tag prefix | Published by |
+|---|---|---|---|
+| `@chenacc/agentbridge` (bridge + CLI) | 0.1.4 | `bridge-v*` | GitHub Actions on tag push, OIDC trusted publishing, SLSA provenance |
+| `@chenacc/dsh-agentbridge` (DSH plugin) | 0.3.3 | `dsh-v*` | same workflow |
+
+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.
 
 ## GitHub release checklist
 
 1. Choose and add an open-source license. Do not publish before this choice is explicit.
-2. Create a Git repository and confirm no runtime data is staged. `.env`, `.agentbridge/`, logs, and `node_modules/` must remain excluded.
+2. Create a Git repository and confirm no runtime data is staged. `.env`, `.agentbridge/`, `~/.agentbridge/`, logs, and `node_modules/` must remain excluded.
 3. Run the release checks from the repository root:
 
    ```powershell
    npm ci
    npm run check
    npm test
+   npm run verify:release     # plugin packaging acceptance, 17 checks
    npm pack --dry-run
    ```
 
-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.
+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.
 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.
 
 ## User installation
@@ -23,13 +33,13 @@ This repository can be installed directly from a tagged public GitHub release. I
 Windows PowerShell:
 
 ```powershell
-npm install --global github:<github-owner>/<repository>#v0.1.0; agentbridge setup codex
+npm install --global github:<github-owner>/<repository>#bridge-v0.1.4; agentbridge setup codex
 ```
 
 macOS/Linux:
 
 ```bash
-npm install --global github:<github-owner>/<repository>#v0.1.0 && agentbridge setup codex
+npm install --global github:<github-owner>/<repository>#bridge-v0.1.4 && agentbridge setup codex
 ```
 
 `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

@@ -1,6 +1,6 @@
 {
   "name": "@chenacc/agentbridge",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "Control local coding agents from a phone through a secure WeChat QR web console.",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,8 @@
     ".": "./src/server.js",
     "./server": "./src/server.js",
     "./tunnel": "./src/tunnel.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./remote": "./src/remote.js"
   },
   "engines": {
     "node": ">=22"
@@ -64,7 +65,7 @@
     "verify:responsive": "node scripts/verify-responsive.mjs",
     "verify:guide": "node scripts/verify-product-guide.mjs",
     "verify:release": "node scripts/verify-plugin-release.mjs",
-    "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/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",
+    "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",
     "verify:remote": "node scripts/verify-remote-tunnel.mjs"
   },
   "dependencies": {

package/src/cli.js

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import QRCode from "qrcode";
-import { ensureAccessKey, ensureCloudflared, findCloudflared, startQuickTunnel } from "./tunnel.js";
+import { parseMode, resolveRemote } from "./remote.js";
 
 const sourceDir = path.dirname(fileURLToPath(import.meta.url));
 const bridgeRoot = path.resolve(sourceDir, "..");
@@ -137,57 +137,28 @@ function bridgeDataDir() {
 }
 
 /**
- * The public address the QR code should carry, if this run is going to have one.
+ * The address the QR code should carry, if this run is going to have one.
  *
- * Returns null when the machine should stay on the LAN: the user opted out, the
- * bridge is already running under someone else's address, or no tunnel could be
- * brought up. Every one of those is a normal outcome — same-Wi-Fi pairing still
- * works — so the reason is printed instead of thrown.
+ * The path itself is chosen by `src/remote.js`, which the DSH plugin shares — so
+ * "which network am I on" has one answer in both entry points. Returns null when
+ * the machine should stay on the LAN: the user opted out, the bridge is already
+ * running under someone else's address, or no path could be brought up. Every one
+ * of those is a normal outcome — same-Wi-Fi pairing still works — so the reason is
+ * logged instead of thrown.
  */
 export async function resolvePublicOrigin({ health, log = () => {}, env = process.env, dataDir = bridgeDataDir(), timeoutMs = 40_000 } = {}) {
-  const explicit = String(env.AGENTBRIDGE_PUBLIC_ORIGIN ?? "").trim().replace(/\/$/, "");
-  if (explicit) return { origin: explicit, accessKey: null, how: "AGENTBRIDGE_PUBLIC_ORIGIN" };
-
-  const supplied = String(env.AGENTBRIDGE_TUNNEL_URL ?? "").trim().replace(/\/$/, "");
-  if (supplied) return { origin: supplied, accessKey: ensureAccessKey(dataDir), how: "AGENTBRIDGE_TUNNEL_URL" };
-
-  if (env.AGENTBRIDGE_NO_TUNNEL === "1") {
-    log("AGENTBRIDGE_NO_TUNNEL=1: the QR code will only work on this Wi-Fi");
-    return null;
-  }
   // An already-running bridge owns its address; asking it to move would mean
   // restarting a service the user may be using right now.
-  if (health) {
+  if (health && !env.AGENTBRIDGE_PUBLIC_ORIGIN && !env.AGENTBRIDGE_TUNNEL_URL && parseMode(env) !== "lan") {
     const advertised = String(health.advertisedOrigin ?? "");
-    if (describeOrigin(advertised) === "public") return { origin: advertised, accessKey: null, how: "already running" };
+    if (describeOrigin(advertised) === "public") return { origin: advertised, accessKey: null, provider: "already-running", label: "已运行的桥", how: "already running" };
     log(`AgentBridge 已经在以局域网地址运行（${advertised || "unknown"}），本次二维码沿用这个地址。想换公网地址：先停掉它再重跑。`);
     return null;
   }
 
-  let command = findCloudflared({ env, home: os.homedir() });
-  if (!command) {
-    log("没有找到 cloudflared，正在从 Cloudflare 官方 Releases 下载（只下这一次）…");
-    command = await ensureCloudflared({ dataDir, env, log });
-  }
-  if (!command) {
-    log("仍然没有 cloudflared，二维码只能用在这台电脑所在 Wi-Fi 里。");
-    return null;
-  }
-
-  const port = new URL(`http://127.0.0.1:${env.AGENTBRIDGE_PORT ?? "8787"}`).port;
-  try {
-    const tunnel = await startQuickTunnel({
-      command,
-      origin: `http://127.0.0.1:${port}`,
-      dataDir,
-      log,
-      timeoutMs,
-    });
-    return { origin: tunnel.url, accessKey: ensureAccessKey(dataDir), how: tunnel.reused ? "cloudflare（复用已有隧道）" : "cloudflare" };
-  } catch (error) {
-    log(`Cloudflare 隧道没起来，二维码只能用在这台电脑所在 Wi-Fi 里：${error instanceof Error ? error.message : String(error)}`);
-    return null;
-  }
+  const decided = await resolveRemote({ env, dataDir, log, port: String(env.AGENTBRIDGE_PORT ?? "8787") });
+  if (!decided) return null;
+  return { ...decided, how: decided.detail ?? decided.provider };
 }
 
 async function startBridge(origin, env = {}) {
@@ -211,12 +182,16 @@ async function ensureBridge(origin, autoStart, log = () => {}) {
   if (health) return health;
   if (!autoStart) throw new Error(`Bridge is not running at ${origin}`);
 
-  // The tunnel has to exist before the bridge starts, because the address is
-  // baked into the pairing URL at startup — the exact opposite of the DSH
-  // plugin, which keeps a local bridge up and restarts it once a tunnel exists.
+  // The path has to be chosen before the bridge starts, because the address is
+  // baked into the pairing URL at startup — the exact opposite of the DSH plugin,
+  // which keeps a local bridge up and restarts it once the address changes.
   const remote = await resolvePublicOrigin({ log });
-  const env = remote?.accessKey
-    ? { AGENTBRIDGE_PUBLIC_ORIGIN: remote.origin, AGENTBRIDGE_ACCESS_KEY: remote.accessKey }
+  const env = remote
+    ? {
+      AGENTBRIDGE_PUBLIC_ORIGIN: remote.origin,
+      AGENTBRIDGE_REMOTE_PROVIDER: remote.provider ?? "remote",
+      ...(remote.accessKey ? { AGENTBRIDGE_ACCESS_KEY: remote.accessKey } : {}),
+    }
     : {};
   if (await startBridge(origin, env)) {
     if (remote) log(`公网地址就绪：${remote.origin}（${remote.how}）`);
@@ -255,8 +230,12 @@ async function requestPhone(options) {
     return result;
   }
   const qr = await QRCode.toString(result.pairing.url, { type: "terminal", small: true, errorCorrectionLevel: "M" });
+  // Naming the path matters: "it worked yesterday" usually means a different
+  // provider won this time, or none did. The bridge reports which one it was
+  // started with, so this stays right even when the tunnel is reused.
+  const providerLabel = health?.remoteProvider ?? null;
   const network = describeOrigin(result.pairing.url) === "public"
-    ? "公网地址，手机用流量也能打开"
+    ? `公网地址，手机用流量也能打开${providerLabel ? `（${providerLabel}）` : ""}`
     : "局域网地址，手机需与电脑连同一个 Wi-Fi";
   console.log(`\nAgentBridge 已绑定当前对话`);
   console.log(`Agent: ${adapterId}`);
@@ -270,7 +249,11 @@ async function requestPhone(options) {
     console.log(`二维码图片 Markdown: ![微信扫码二维码](${result.qrImageUrl})`);
   }
   console.log(`微信扫码地址: ${result.pairing.url}`);
-  console.log(`电脑端会话: ${origin}/?session=${encodeURIComponent(result.session.id)}\n`);
+  console.log(`电脑端会话: ${origin}/?session=${encodeURIComponent(result.session.id)}`);
+  // Consent-based and once, at the very end: no network call, no token, nothing
+  // the user did not ask for. Star counts are how the plugin market ranks entries,
+  // so asking is fair — clicking on their behalf would not be.
+  console.log("觉得有用？给项目点个星：https://github.com/chenacc1/agentbridge\n");
   return result;
 }
 

package/src/config.js

@@ -174,6 +174,10 @@ export function loadConfig(env = process.env, workspace = process.cwd()) {
     // itself, so the plugin may ask for a restart to change the advertised address
     // without handing that power to anything else that can reach loopback.
     autostartToken: (env.AGENTBRIDGE_AUTOSTART_TOKEN ?? "").trim() || null,
+    // Which network path produced advertisedOrigin. Informational only: the
+    // launcher sets it so /api/health and the startup log can name the path
+    // instead of leaving the user to guess why the address changed.
+    remoteProvider: (env.AGENTBRIDGE_REMOTE_PROVIDER ?? "").trim() || null,
     // Outbound notifications: unset webhook means the feature is simply off.
     notifyWebhook: pick(env, "AGENTBRIDGE_NOTIFY_WEBHOOK", notifyFile.webhook),
     notifyFormat: pick(env, "AGENTBRIDGE_NOTIFY_FORMAT", notifyFile.format ?? "json").toLowerCase(),

package/src/remote.js

@@ -0,0 +1,449 @@
+/**
+ * Which network path a QR code should point at.
+ *
+ * There is more than one way to put a local bridge in front of a phone, and they
+ * differ in what they cost the user: a Cloudflare quick tunnel needs nothing on
+ * the phone but hands out a random hostname; Tailscale Funnel is a fixed hostname
+ * and still needs nothing on the phone; Tailscale and ZeroTier private addresses
+ * are the safest but require an app on the phone and a login.
+ *
+ * So the choice is data, not `if` statements scattered across the CLI and the DSH
+ * plugin: each path is a provider with the same shape, and one resolver walks them
+ * in a documented order. Everything that touches the machine (running `tailscale`,
+ * reading adapters, downloading cloudflared) is injectable, because this module
+ * decides whether a public address exists at all.
+ */
+import os from "node:os";
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import {
+  ensureAccessKey,
+  ensureCloudflared,
+  findCloudflared,
+  readTunnelState,
+  startQuickTunnel,
+  tunnelStatePath,
+} from "./tunnel.js";
+
+/** Run one command and collect its output instead of streaming it. */
+export function runCommand(command, args, { timeoutMs = 15_000, env = process.env } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, args, { windowsHide: true, stdio: ["ignore", "pipe", "pipe"], env });
+    } catch (error) {
+      return resolve({ code: null, stdout: "", stderr: String(error?.message ?? error), missing: true });
+    }
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+    const timer = setTimeout(() => {
+      try { child.kill("SIGKILL"); } catch { /* already gone */ }
+      finish({ code: null, stdout, stderr, timedOut: true });
+    }, timeoutMs);
+    timer.unref?.();
+    child.stdout?.on("data", (chunk) => { stdout += String(chunk); });
+    child.stderr?.on("data", (chunk) => { stderr += String(chunk); });
+    child.once?.("error", (error) => finish({ code: null, stdout, stderr, stderr: String(error?.message ?? error), missing: true }));
+    child.once?.("exit", (code) => finish({ code, stdout, stderr }));
+  });
+}
+
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tailscale: shared detection for the private-address and Funnel providers
+// ---------------------------------------------------------------------------
+
+export function tailscaleCandidates(env = process.env) {
+  const candidates = [];
+  if (env.AGENTBRIDGE_TAILSCALE) candidates.push(env.AGENTBRIDGE_TAILSCALE);
+  if (env.ProgramFiles) candidates.push(path.join(env.ProgramFiles, "Tailscale", "tailscale.exe"));
+  if (env["ProgramFiles(x86)"]) candidates.push(path.join(env["ProgramFiles(x86)"], "Tailscale", "tailscale.exe"));
+  candidates.push("/usr/bin/tailscale", "/usr/local/bin/tailscale", "/opt/homebrew/bin/tailscale");
+  candidates.push("/Applications/Tailscale.app/Contents/MacOS/Tailscale");
+  return candidates;
+}
+
+export function findTailscale({ env = process.env, exists = existsSync } = {}) {
+  if (env.AGENTBRIDGE_TAILSCALE) return exists(env.AGENTBRIDGE_TAILSCALE) ? env.AGENTBRIDGE_TAILSCALE : null;
+  for (const candidate of tailscaleCandidates(env)) {
+    // A bare command name is resolved by the shell, not the filesystem.
+    if (!path.isAbsolute(candidate)) continue;
+    if (exists(candidate)) return candidate;
+  }
+  return "tailscale";
+}
+
+/** The 100.64/10 address Tailscale assigned this node, if it is up. */
+export function tailscaleIpv4(status) {
+  const addresses = Array.isArray(status?.Self?.TailscaleIPs) ? status.Self.TailscaleIPs : [];
+  return addresses.find((address) => /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(String(address))) ?? null;
+}
+
+export function tailscaleDnsName(status) {
+  const name = String(status?.Self?.DNSName ?? "").replace(/\.$/, "");
+  return name || null;
+}
+
+/**
+ * Ask Tailscale what it is doing.
+ *
+ * `BackendState` is the interesting field: "Running" means the node is up and on
+ * a tailnet. "NeedsLogin" and "Stopped" are the two states users actually hit,
+ * and they deserve different advice, so they are reported separately rather than
+ * collapsing into "not available".
+ */
+export async function detectTailscale({ env = process.env, run = runCommand, exists = existsSync } = {}) {
+  const bin = findTailscale({ env, exists });
+  if (!bin) return { available: false, reason: "Tailscale is not installed", bin: null };
+  const result = await run(bin, ["status", "--json"]);
+  if (result.missing) return { available: false, reason: "Tailscale is not installed", bin };
+  if (result.code !== 0) {
+    const detail = `${result.stderr || result.stdout}`.trim();
+    const needsOperator = /access denied|permission|operator/i.test(detail);
+    return {
+      available: false,
+      bin,
+      reason: needsOperator
+        ? "this Windows user cannot read Tailscale status; run `tailscale set --operator=%USERNAME%` once, or start DSH as administrator"
+        : `tailscale status failed: ${detail || `exit ${result.code}`}`,
+    };
+  }
+  const status = parseJson(result.stdout);
+  if (!status) return { available: false, bin, reason: "Tailscale returned unreadable status" };
+  const state = String(status.BackendState ?? "");
+  if (state !== "Running") {
+    return {
+      available: false,
+      bin,
+      status,
+      reason: state === "NeedsLogin"
+        ? "Tailscale is installed but not signed in; open its tray app and log in"
+        : `Tailscale is not running (${state || "unknown"})`,
+    };
+  }
+  return { available: true, bin, status, ipv4: tailscaleIpv4(status), dnsName: tailscaleDnsName(status) };
+}
+
+function tailscaleProvider({ id, label, isPublic }) {
+  return {
+    id,
+    label,
+    isPublic,
+    async probe(ctx) {
+      const found = await detectTailscale({ env: ctx.env, run: ctx.run, exists: ctx.exists });
+      return found.available ? { ready: true, detail: found } : { ready: false, reason: found.reason, detail: found };
+    },
+    async ensure(ctx, probed) {
+      const found = probed.detail;
+      if (!found?.ipv4) {
+        throw new Error("Tailscale is running but has no 100.64/10 address yet");
+      }
+      return { origin: `http://${found.ipv4}:${ctx.port}`, detail: `Tailscale ${found.ipv4}` };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tailscale Funnel: fixed public hostname, nothing to install on the phone
+// ---------------------------------------------------------------------------
+
+export const funnelProvider = {
+  id: "funnel",
+  label: "Tailscale Funnel（固定域名）",
+  isPublic: true,
+  async probe(ctx) {
+    const found = await detectTailscale({ env: ctx.env, run: ctx.run, exists: ctx.exists });
+    if (!found.available) return { ready: false, reason: found.reason };
+    if (!found.dnsName) return { ready: false, reason: "Tailscale has not assigned this node a DNS name yet" };
+    const status = await ctx.run(found.bin, ["funnel", "status"]);
+    const text = `${status.stdout}${status.stderr}`;
+    // `funnel status` prints "No funnel configuration" when nothing is exposed.
+    const enabled = status.code === 0 && !/no funnel|not enabled|no configuration/i.test(text);
+    if (enabled) return { ready: true, detail: found };
+    if (!ctx.allowEnable) {
+      return { ready: false, reason: "Funnel is not enabled for this node (set AGENTBRIDGE_REMOTE=funnel to turn it on)" };
+    }
+    return { ready: true, needsEnable: true, detail: found };
+  },
+  async ensure(ctx, probed) {
+    const found = probed.detail;
+    if (probed.needsEnable) {
+      const start = await ctx.run(found.bin, ["funnel", "--bg", "--https=443", `http://127.0.0.1:${ctx.port}`]);
+      if (start.code !== 0) {
+        const text = `${start.stderr}${start.stdout}`.trim();
+        const hint = /not enabled|Funnel is not|enable/i.test(text)
+          ? " — enable Funnel for this tailnet in the Tailscale admin console (Access controls → Funnel)"
+          : "";
+        throw new Error(`tailscale funnel failed: ${text || `exit ${start.code}`}${hint}`);
+      }
+    }
+    return { origin: `https://${found.dnsName}`, detail: `Tailscale Funnel ${found.dnsName}` };
+  },
+};
+
+// ---------------------------------------------------------------------------
+// ZeroTier: private address, app required on the phone
+// ---------------------------------------------------------------------------
+
+export function zerotierAddress(interfaces = os.networkInterfaces()) {
+  for (const [name, entries] of Object.entries(interfaces)) {
+    if (!/zerotier/i.test(name)) continue;
+    for (const entry of entries ?? []) {
+      if ((entry.family !== "IPv4" && entry.family !== 4) || entry.internal) continue;
+      if (!/^(10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.)/.test(entry.address)) continue;
+      return { address: entry.address, name };
+    }
+  }
+  return null;
+}
+
+export const zerotierProvider = {
+  id: "zerotier",
+  label: "ZeroTier（私有网络）",
+  isPublic: false,
+  async probe(ctx) {
+    const override = String(ctx.env.AGENTBRIDGE_ZEROTIER ?? "").trim();
+    if (override) {
+      if (!/^\d+\.\d+\.\d+\.\d+$/.test(override)) {
+        return { ready: false, reason: `AGENTBRIDGE_ZEROTIER is not an IPv4 address: ${override}` };
+      }
+      return { ready: true, detail: { address: override, name: "AGENTBRIDGE_ZEROTIER" } };
+    }
+    const found = zerotierAddress(ctx.interfaces ?? os.networkInterfaces());
+    if (!found) {
+      return { ready: false, reason: "no ZeroTier adapter with a managed IPv4 address (join a network and authorize this member)" };
+    }
+    return { ready: true, detail: found };
+  },
+  async ensure(ctx, probed) {
+    return { origin: `http://${probed.detail.address}:${ctx.port}`, detail: `ZeroTier ${probed.detail.address}` };
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Cloudflare: quick tunnel (random hostname) and named tunnel (your domain)
+// ---------------------------------------------------------------------------
+
+export const cloudflareProvider = {
+  id: "cloudflare",
+  label: "Cloudflare quick tunnel（自动）",
+  isPublic: true,
+  async probe(ctx) {
+    const command = findCloudflared({ env: ctx.env, home: ctx.home, exists: ctx.exists });
+    if (command) return { ready: true, detail: command };
+    if (ctx.env.AGENTBRIDGE_NO_DOWNLOAD === "1") {
+      return { ready: false, reason: "cloudflared is missing and AGENTBRIDGE_NO_DOWNLOAD=1 forbids fetching it" };
+    }
+    const downloaded = await ensureCloudflared({ dataDir: ctx.dataDir, env: ctx.env, log: ctx.log });
+    if (!downloaded) return { ready: false, reason: "cloudflared is missing and could not be downloaded" };
+    return { ready: true, detail: downloaded };
+  },
+  async ensure(ctx, probed) {
+    const tunnel = await startQuickTunnel({
+      command: probed.detail,
+      origin: `http://127.0.0.1:${ctx.port}`,
+      dataDir: ctx.dataDir,
+      log: ctx.log,
+    });
+    return { origin: tunnel.url, detail: tunnel.reused ? "Cloudflare quick tunnel (reused)" : "Cloudflare quick tunnel" };
+  },
+};
+
+function namedTunnelStatePath(dataDir) {
+  return path.join(dataDir, "cloudflare-named-tunnel.json");
+}
+
+export const namedTunnelProvider = {
+  id: "named",
+  label: "Cloudflare 命名隧道（固定域名）",
+  isPublic: true,
+  async probe(ctx) {
+    const name = String(ctx.env.AGENTBRIDGE_CLOUDFLARE_TUNNEL ?? "").trim();
+    const hostname = String(ctx.env.AGENTBRIDGE_CLOUDFLARE_HOSTNAME ?? "").trim();
+    if (!name) return { ready: false, reason: "AGENTBRIDGE_CLOUDFLARE_TUNNEL is not set" };
+    if (!hostname) return { ready: false, reason: "AGENTBRIDGE_CLOUDFLARE_TUNNEL needs AGENTBRIDGE_CLOUDFLARE_HOSTNAME" };
+    const command = findCloudflared({ env: ctx.env, home: ctx.home, exists: ctx.exists });
+    if (!command) return { ready: false, reason: "cloudflared is missing" };
+    return { ready: true, detail: { command, name, origin: `https://${hostname.replace(/^https?:\/\//, "").replace(/\/$/, "")}` } };
+  },
+  async ensure(ctx, probed) {
+    const { command, name, origin } = probed.detail;
+    const statePath = namedTunnelStatePath(ctx.dataDir);
+    let previous = null;
+    try {
+      previous = JSON.parse(readFileSync(statePath, "utf8"));
+    } catch {
+      previous = null;
+    }
+    const alive = previous && Number.isInteger(previous.pid) && (() => {
+      try {
+        process.kill(previous.pid, 0);
+        return true;
+      } catch (error) {
+        return error?.code === "EPERM";
+      }
+    })();
+    if (alive && previous.tunnel === name) return { origin, detail: `Cloudflare named tunnel ${name} (reused)` };
+
+    const child = spawn(command, ["tunnel", "--no-autoupdate", "run", name], {
+      detached: true,
+      windowsHide: true,
+      stdio: "ignore",
+    });
+    child.unref();
+    if (child.pid) {
+      try {
+        writeFileSync(statePath, JSON.stringify({ pid: child.pid, tunnel: name, origin, startedAt: new Date().toISOString() }, null, 2), "utf8");
+      } catch {
+        // The record only saves a respawn; the tunnel works either way.
+      }
+    }
+    // cloudflared needs a moment before the edge can route the hostname, and the
+    // bridge is about to be started with this origin baked in.
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      try {
+        await ctx.fetch(`${origin}/api/health`, { signal: AbortSignal.timeout(5_000) });
+        return { origin, detail: `Cloudflare named tunnel ${name}` };
+      } catch {
+        // Edge not routing yet, or the bridge is not up — both are expected now.
+      }
+    }
+    return { origin, detail: `Cloudflare named tunnel ${name}` };
+  },
+};
+
+// ---------------------------------------------------------------------------
+// The resolver
+// ---------------------------------------------------------------------------
+
+export const PROVIDER_IDS = ["named", "funnel", "cloudflare", "tailscale", "zerotier"];
+
+const PROVIDERS = {
+  named: namedTunnelProvider,
+  funnel: funnelProvider,
+  cloudflare: cloudflareProvider,
+  tailscale: tailscaleProvider({ id: "tailscale", label: "Tailscale（私有网络）", isPublic: false }),
+  zerotier: zerotierProvider,
+};
+
+/**
+ * `auto` is deliberately not "try the fanciest thing first".
+ *
+ * A named tunnel is only in the list when the user configured one, and Funnel is
+ * only *reused* in auto mode — turning it on changes the user's tailnet, so that
+ * has to be an explicit choice (`AGENTBRIDGE_REMOTE=funnel`). The quick tunnel
+ * comes next because it needs nothing from anyone, and the private overlays come
+ * last: they are safer, but they require an app on the phone, which is exactly
+ * what most people are trying to avoid.
+ */
+export const AUTO_ORDER = ["named", "funnel", "cloudflare", "tailscale", "zerotier"];
+
+export function parseMode(env = process.env) {
+  const raw = String(env.AGENTBRIDGE_REMOTE ?? "").trim().toLowerCase();
+  if (!raw || raw === "auto") return "auto";
+  if (raw === "lan" || raw === "local" || raw === "off" || raw === "none") return "lan";
+  return PROVIDER_IDS.includes(raw) ? raw : "auto";
+}
+
+/**
+ * The public or overlay address the QR code should carry, or null for the LAN.
+ *
+ * Returns the provider that won, because "which path am I on" is the first thing
+ * anyone asks when the QR code does not open.
+ */
+export async function resolveRemote({
+  env = process.env,
+  dataDir,
+  port = String(env.AGENTBRIDGE_PORT ?? "8787"),
+  log = () => {},
+  mode = parseMode(env),
+  providers = PROVIDERS,
+  run = runCommand,
+  fetchImpl = globalThis.fetch,
+  exists = existsSync,
+  home = os.homedir(),
+  interfaces,
+} = {}) {
+  const explicit = String(env.AGENTBRIDGE_PUBLIC_ORIGIN ?? "").trim().replace(/\/$/, "");
+  if (explicit) {
+    return { provider: "explicit", label: "AGENTBRIDGE_PUBLIC_ORIGIN", origin: explicit, accessKey: null, isPublic: !/^http:\/\/(127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.)/.test(explicit) };
+  }
+  const supplied = String(env.AGENTBRIDGE_TUNNEL_URL ?? "").trim().replace(/\/$/, "");
+  if (supplied) {
+    return { provider: "tunnel-url", label: "AGENTBRIDGE_TUNNEL_URL", origin: supplied, accessKey: ensureAccessKey(dataDir), isPublic: true };
+  }
+  if (mode === "lan" || env.AGENTBRIDGE_NO_TUNNEL === "1") {
+    const why = env.AGENTBRIDGE_NO_TUNNEL === "1" ? "AGENTBRIDGE_NO_TUNNEL=1" : `AGENTBRIDGE_REMOTE=${mode}`;
+    log(`${why}: the QR code will work on this Wi-Fi and nowhere else`);
+    return null;
+  }
+
+  const order = mode === "auto" ? AUTO_ORDER : [mode];
+  const reasons = [];
+  for (const id of order) {
+    const provider = providers[id];
+    if (!provider) continue;
+    const ctx = { env, dataDir, port, log, run, fetch: fetchImpl, exists, home, interfaces, allowEnable: mode === id };
+    let probed;
+    try {
+      probed = await provider.probe(ctx);
+    } catch (error) {
+      reasons.push(`${id}: ${error?.message ?? error}`);
+      continue;
+    }
+    if (!probed?.ready) {
+      reasons.push(`${id}: ${probed?.reason ?? "not available"}`);
+      continue;
+    }
+    try {
+      const result = await provider.ensure(ctx, probed);
+      log(`${provider.label} → ${result.origin}`);
+      return {
+        provider: id,
+        label: provider.label,
+        origin: result.origin,
+        detail: result.detail,
+        // Anything reachable from the internet gets the key gate, no exceptions.
+        accessKey: provider.isPublic ? ensureAccessKey(dataDir) : null,
+        isPublic: provider.isPublic,
+      };
+    } catch (error) {
+      reasons.push(`${id}: ${error?.message ?? error}`);
+      continue;
+    }
+  }
+
+  // Every path was tried and refused. Say why, once, instead of silently
+  // pretending the LAN is what the user asked for.
+  if (mode !== "auto" || reasons.length) {
+    log(`no remote path could be brought up, staying on this Wi-Fi only: ${reasons.join("; ")}`);
+  }
+  return null;
+}
+
+/** Forget the named-tunnel record so the next run starts cloudflared again. */
+export function forgetNamedTunnel(dataDir) {
+  try {
+    rmSync(namedTunnelStatePath(dataDir), { force: true });
+  } catch {
+    // Nothing to forget.
+  }
+}
+
+export { tunnelStatePath };

package/src/server.js

@@ -419,6 +419,7 @@ export async function createBridge(options = {}) {
           advertisedOrigin: config.advertisedOrigin,
           accessKeyRequired: Boolean(config.accessKey),
           autostart: config.autostart === true,
+          remoteProvider: config.remoteProvider,
         });
       }
 
@@ -989,6 +990,9 @@ export async function startBridge() {
     bridge.server.listen(bridge.config.port, bridge.config.host, resolve);
   });
   console.log(`AgentBridge running at http://127.0.0.1:${bridge.config.port}`);
+  if (bridge.config.remoteProvider) {
+    console.log(`Remote path: ${bridge.config.remoteProvider} → ${bridge.config.advertisedOrigin}`);
+  }
   console.log(`WeChat scan target: ${bridge.getCurrentPairing().url}`);
   // Silence here used to mean a QR encoding an address the phone could never reach.
   if (new URL(bridge.config.advertisedOrigin).hostname === "127.0.0.1") {