@babtab/relay 0.1.0 → 0.2.0

package/README.zh-TW.md

@@ -7,84 +7,63 @@
 
 Babtab Chrome 擴充功能的**本機中轉伺服器**：把你的 AI Agent（Cursor / Pi / Claude Code / …）接到你真正的 Chrome 上。
 
-MV3 擴充功能自己不能 listen port，所以需要這支小程式當橋樑。跑在 `localhost`，流量不出你的電腦；Relay 只負責轉發，**看不到你的頁面內容**。
+MV3 擴充功能自己不能 listen port，所以需要這支小程式當橋樑。跑在 `localhost`，流量不出你的電腦；Relay 會在記憶體中轉發請求與結果（包含頁面觀察及截圖），不會儲存頁面內容。
 
-## 連線方式（3 個角色）
+## 使用者快速開始（0.2.0）
 
-```text
-AI Agent（Cursor / Pi …） ←→ Relay（本機 :3000） ←→ Chrome 擴充功能（含 Side Panel）
-     用 MCP 設定連過來              只做轉發與配對              真正在分頁上動手的人
-```
-
-## 使用者快速開始（不用 clone、不用 install）
-
-### 步驟 1：安裝 Chrome 擴充功能
-
-`chrome://extensions` → 開啟**開發者模式** → **載入未封裝項目** → 選 `dist` 資料夾。
-
-> 上架 Chrome 商店後，這步會變成「去商店按安裝」。
-
-### 步驟 2：啟動 Relay（二選一，效果一樣）
+需要 Node.js 20+ 與對應新版外掛。一般使用者從 **Chrome Web Store 安裝 Babtab**；開發者模式只供本機測試。
 
-```bash
-# A. 有 Node 20+ 的人：免安裝，直接跑
-npx @babtab/relay
-
-# B. 不想裝 Node 的人：去 GitHub Release 下載對應系統的執行檔
-./babtab-relay-darwin-arm64   # macOS Apple Silicon 為例
-```
+1. 開啟 Babtab Side Panel，按 **Add to Cursor**。
+2. 在 Cursor 確認加入／啟用 Babtab；Cursor 自動啟動本機橋接程式。
+3. 回到外掛，確認工具名稱後按 **Approve**。
+4. 在一般網站分頁，對 AI 說 **Use babtab to observe the current tab**；需要網站授權時在外掛批准。
 
-看到以下訊息就是起來了（預設 port `3000`）：
+不用先啟動 Relay、不用設定 port、不用保持終端機開啟。使用時保留 Chrome。
+首次 npm 下載需要網路；憑證固定保存在 `~/.babtab/`，更換工作目錄不影響連線。
 
-```text
-[babtab-relay] listening on http://127.0.0.1:3000
-```
+### 其他 AI 工具
 
-進階用法（換 port、指定 token 存檔位置）：
+開啟 **Other AI tools / install with a command**，選工具並複製專屬指令：
 
 ```bash
-PORT=3001 npx @babtab/relay
-BABTAB_TOKEN_FILE=~/.babtab/relay-tokens.json npx @babtab/relay
+npx -y @babtab/relay@0.2.0 setup --target windsurf --port 3000 --device <外掛提供的deviceId>
 ```
 
-> `npx` 不是安裝，是「下載來跑一次」，關掉終端機就停了。
-
-### 步驟 3：擴充功能連上 Relay
+只需執行一次。指令保留其他 server、備份舊設定，寫入由 AI 工具自動啟動的 MCP 設定。
+接著重載／啟用 MCP，再回 Chrome 批准配對。
+自動啟動支援 Cursor、Claude Code、Windsurf、Copilot、Codex、Claude Desktop、Antigravity、Devin、Kimi、Hermes；Pi／Manual 沿用進階 HTTP 流程。
 
-1. 在 Chrome 開任意網站，點工具列的 Babtab 圖示開啟 **Side Panel**
-2. Relay URL 預設已填好 `ws://127.0.0.1:3000`，不用改
-3. 按 **"Save & Connect"**
+### 自動啟動與重連
 
-這一步是把你的 Chrome 註冊成 Relay 上的一台 device。
+AI 工具啟動 `babtab-relay stdio --device … --client … --port 3000`，橋接程式啟動或重用本機 Relay。
+未配對時可列出工具，實際操作仍須人工批准。多個 AI 工具共用 Relay；持有 Relay 的工具結束後，剩餘工具會接手。
+中斷中的動作會回報錯誤，不會自動重送。
 
-### 步驟 4：AI Agent 連上 Relay（以 Cursor 為例）
+自動模式的憑證保存在 `~/.babtab/`（可透過 `BABTAB_DATA_DIR` 覆寫）。
+重新開啟 Chrome／AI 工具後會自動重連。明確按 **Disconnect** 後，自動重連會停止，需再按 Reconnect。
 
-1. 在 Side Panel 同一頁選你的 Agent → 按 **"Copy config"**
-2. 貼到 `~/.cursor/mcp.json` 的 `mcpServers`（只想給單一專案用，就放該專案的 `.cursor/mcp.json`）：
+### 從 0.1.x 升級
 
-```json
-{
-  "mcpServers": {
-    "babtab": {
-      "url": "http://127.0.0.1:3000/mcp",
-      "headers": { "Authorization": "Bearer 剛拿到的token" }
-    }
-  }
-}
-```
+先關掉舊的手動 Relay，更新外掛，再重新加入 AI 工具並批准一次。
+自動模式使用新的固定憑證目錄。若 port 被其他服務或舊版 Relay 佔用，會顯示錯誤；
+可在 **Advanced connection settings** 換 port，再重新加入 AI 工具。
 
-3. Panel 出現 `Controlled by: cursor` 就通了。
+### 進階：手動或遠端 Relay
 
-驗證一句話（在 Agent 裡下）：
+仍可執行 `npx @babtab/relay` 啟動獨立 HTTP Relay。
+外掛 **Advanced connection settings** 可設定 port／URL 並按 **Save & Connect**；也保留手動產生 HTTP 設定。
 
-> 用 browser_observe 看我現在 Chrome 開的分頁，然後告訴我標題和網址
+手動模式沿用 `BABTAB_TOKEN_FILE` 或啟動目錄的 `./data/relay-tokens.json`。
+遠端部署須明確設定 `HOST` 並使用 TLS（`wss://`／`https://`）；先讓外掛連上 Relay，
+再跑 `setup --target <tool> --relay-url https://… --device <id>`。
 
-## 常見問題
+### 常見問題
 
-- **按 "Save & Connect"沒反應？** 先看 Relay 終端機有沒有 `listening`，再確認 URL 是 `ws://127.0.0.1:3000` 且 port 跟 Relay 一致。
-- **配對碼過期？** 配對碼只有短暫有效，超時就重新按一次 "Copy config"。
-- **想換 token？** 重跑一次步驟 4 會產生新 token，記得同步更新 `mcp.json`。
-- **Agent 跟 Chrome 不在同一台電腦？**（進階）把 Relay 放到 VPS 上，Side Panel 的 Relay URL 改成你的 `wss://…` 即可，流程不變。
+- **Cursor 沒開啟？** 展開按鈕下方的 setup 指令，執行一次，再重載／啟用 MCP。
+- **沒出現配對要求？** 確认 AI 工具的 PATH 找得到 Node 20+／`npx`，且 Babtab 已啟用；保持外掛面板開啟。MCP 日誌會顯示啟動錯誤。
+- **配對碼過期？** 保持 AI 工具執行，橋接程式會自動取得新碼。
+- **斷線？** 開啟 AI 工具和 Chrome；若先前主動 Disconnect，請在外掛按 Reconnect。
+- **憑證遺失或撤銷？** 重新批准配對；橋接程式不會跳過人工批准。
 
 ## 隱私說明
 

package/SECURITY.md

@@ -10,28 +10,29 @@ Local-first relay. No hosted service, no telemetry, no account.
 
 Older versions: upgrade via `npx @babtab/relay@latest`.
 
-## What the relay sees (and never sees)
+## What the relay sees
 
-The relay routes **metadata only**: device/client IDs, method names
-(`browser_observe`, `browser_click`, …), pairing codes, auth tokens.
+The relay forwards request parameters and results in memory, including entered
+values, page observations and screenshots. It does not persist page content or
+log request/response bodies. It must be trusted by the extension and the agent.
 
-It **never** receives, stores, or logs:
+The token store (`BABTAB_TOKEN_FILE`, default `./data/relay-tokens.json`) contains
+bearer tokens, client names, device IDs, scopes and expiry. Device credentials
+stay in extension local storage and are verified from the first WebSocket frame;
+the relay does not persist them. Use TLS for every non-loopback deployment.
 
-- page DOM, screenshots, or extracted page content,
-- browser credentials, cookies, or API keys belonging to other tools,
-- fill/select input values (the extension redacts them before display,
-  and the relay never persists request bodies).
+## Device authentication upgrade
 
-Token store (`BABTAB_TOKEN_FILE`, default `./data/relay-tokens.json`)
-holds random bearer tokens + scope + expiry only. Treat that file like
-a password: `chmod 600`, never commit it, never send it to anyone.
+Update both relay and extension, then re-pair agents using the new `dev_v2_`
+device ID. Knowledge of the public ID alone no longer permits registration or
+pairing approval. Old unauthenticated device connections are rejected.
 
 ## Running it safely
 
 - Bind is localhost by default (`http://127.0.0.1:3000`). Do not expose
   it to a LAN / public IP unless you understand that anyone who can
   reach the port can attempt pairing.
-- Pairing codes are 6-digit, single-use, and expire quickly. Approve
+- Pairing codes are 6-digit and expire quickly. Approve
   only codes you just requested; reject anything you don't recognize.
 - HIGH-risk browser actions (submit, pay, delete, publish, password
   fill) always require explicit approval in the extension Side Panel —