@chenacc/agentbridge 0.1.0 → 0.1.2

package/README.md

@@ -43,33 +43,42 @@
 
 AgentBridge 不替你安装或登录任何 Agent，只检测本机**已安装且已登录**的那些；没装的显示「未安装」，不会假装可用。
 
-### 四步装好
+### 两种装法
+
+**想马上用（推荐）**：不用下载仓库，一条命令起桥并直接打印二维码。
 
 ```powershell
-# 1. 取代码（尚未发布到 npm，目前从仓库获取）
-git clone https://github.com/chenacc1/agentbridge.git
-cd agentbridge
+npx @chenacc/agentbridge
+```
 
-# 2. 装依赖（运行时只有 katex 和 qrcode 两个）
-npm install
+要长期使用、或改配置（项目白名单、远程通道、通知推送），装成全局命令：
 
-# 3. 声明手机可以访问的项目目录：别名=绝对路径，分号分隔
-$env:AGENTBRIDGE_PROJECTS = "agentbridge=D:\projects\agentbridge"
+```powershell
+npm install -g @chenacc/agentbridge
+agentbridge phone --agent claude
+```
 
-# 4. 启动
+**要改代码或跑测试**：从仓库来。
+
+```powershell
+git clone https://github.com/chenacc1/agentbridge.git
+cd agentbridge
+npm install
+$env:AGENTBRIDGE_PROJECTS = "agentbridge=D:\projects\agentbridge"   # 可选：别名=绝对路径，分号分隔
 npm start
 ```
 
 打开 [http://127.0.0.1:8787](http://127.0.0.1:8787)，桌面页会显示一次性二维码；手机连同一可信 Wi-Fi，用微信「扫一扫」扫描即可。
 
 > 二维码只用于首次配对，会过期且**只能使用一次**。配对成功后请收藏手机页显示的固定回访地址，之后从收藏进入；不要收藏 `/pair?code=...` 临时链接。
-> 第 3 步可以不写：不设 `AGENTBRIDGE_PROJECTS` 时默认把**启动目录**作为唯一可用项目，别名 `workspace`。别名只允许字母、数字、`_`、`-`（≤40 字符）。
+> `AGENTBRIDGE_PROJECTS` 可以不写：不设时默认把**启动目录**作为唯一可用项目，别名 `workspace`。别名只允许字母、数字、`_`、`-`（≤40 字符）。
 > 这些变量必须设在**真正启动 Bridge 的那个终端**里；`.env.example` 只是一份清单，程序不会自动读取 `.env` 文件。
 
 ### 装完自检
 
 ```powershell
-node .\bin\agentbridge.js phone --agent echo
+npx @chenacc/agentbridge phone --agent echo
+# 从仓库跑的话：node .\bin\agentbridge.js phone --agent echo
 ```
 
 Echo 适配器不接触任何 AI 工具，只验证「CLI → 本机 Bridge → 生成配对二维码」整条链路。能打印二维码就说明安装正确，扫码后可看到手机与桌面同步。
@@ -90,6 +99,7 @@ Echo 适配器不接触任何 AI 工具，只验证「CLI → 本机 Bridge →
 
 | 场景 | 模式 | 手机要求 |
 |---|---|---|
+| 什么都不装、也不连同一个 Wi-Fi（DSH 插件默认） | Cloudflare Tunnel（自动） | 只需浏览器 |
 | 同一可信 Wi-Fi | 局域网 | 浏览器 / 微信 |
 | 跨网络，但属同一私有网络 | Tailscale | 同一 tailnet |
 | Tailscale 不稳定 | ZeroTier | 同一私有网络 |
@@ -166,7 +176,17 @@ node .\bin\agentbridge.js phone --agent codex --session <thread-id>
 
 前提：DSH Desktop 已安装，且存在桌面 profile `%USERPROFILE%\.dsh\profiles\desktop\package.json`（或由 `DSH_HOME` 指定）。
 
-**第 0 步：先把桥跑起来。** 插件是遥控器，桥是基站；没有桥，`/phone` 只会告诉你"无法连接 AgentBridge"。最省事是一条命令（自动起桥并直接打印二维码）：
+**第 0 步：桥。** 插件是遥控器，桥是基站。从 0.2.0 起桥随插件一起安装，**DSH Desktop 启动时插件会自己在后台把它拉起来**，正常情况你什么都不用敲。
+
+从 0.3.0 起，插件默认再开一条 **Cloudflare 隧道**，把桥映射成公网 https 域名，于是手机不必和电脑在同一个 Wi-Fi——扫描、出差、用流量都能开。这一步需要一个 Cloudflare 官方小工具：
+
+```powershell
+winget install --id Cloudflare.cloudflared
+```
+
+没装也不影响使用，只是退回"手机与电脑同一 Wi-Fi"。想一直走局域网，设 `AGENTBRIDGE_NO_TUNNEL=1`；想用固定域名，去 Cloudflare 建命名隧道并把 `AGENTBRIDGE_PUBLIC_ORIGIN` 指向它。
+
+只有自动启动失败（沙箱限制、端口被占）才需要手动来一条：
 
 ```powershell
 npx @chenacc/agentbridge
@@ -272,6 +292,8 @@ node .\bin\agentbridge.js phone --agent deepseek-harness
 
 若自动选择的局域网地址手机访问不到，显式指定 `AGENTBRIDGE_PUBLIC_ORIGIN`；Windows 防火墙提示时只放行「专用网络」。
 
+自动选地址时会跳过 `169.254.x.x`（网卡没拿到租约时的临时地址，手机根本路由不到）和 Hyper-V / WSL / 蓝牙这类虚拟网卡，优先真实的 Wi-Fi 或以太网地址。扫码后如果微信弹出「该地址为 IP 地址，请使用域名访问网站」，点「继续访问」即可；手机上不了网、或者只有手机流量没连同一个 Wi-Fi 时，二维码里的地址是打不开的。
+
 ## 安全边界
 
 ![访问边界：本地配对与管理接口只允许 loopback；远程访问使用私有网络或受访问密钥保护的隧道。](./docs/assets/security-boundaries.svg)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chenacc/agentbridge",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Control local coding agents from a phone through a secure WeChat QR web console.",
   "license": "MIT",
   "type": "module",
@@ -58,7 +58,8 @@
     "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/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/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 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",
+    "verify:remote": "node scripts/verify-remote-tunnel.mjs"
   },
   "dependencies": {
     "katex": "0.19.1",