@xiaoqiong0v0/opencode-browser-tool 1.9.0 → 1.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -59,25 +59,32 @@ sha256 校验(**幂等**:sha 与当前 release 期望值一致即跳过;**
59
59
  - `BT_BROWSERS_PATH` — 浏览器缓存目录
60
60
  - `BT_SHELL_URL` — **附着模式**:连接到已运行的 shell(完整基地址,如 `http://127.0.0.1:18280`),优先级最高
61
61
  - `BT_SHELL_PORT` — **附着模式**:仅指定端口,等价于 `http://127.0.0.1:<port>`
62
+ - `BT_SHELL_TOKEN` — **鉴权令牌**:本地 API 所有 `/api/*` 请求必须带 `x-bt-token`。**附着模式下必须设置**,且外部 shell 启动时要用同一值(`--token <token>` 或同值环境变量);启动模式下由插件随机生成并通过 `--token` 传给 shell,无需手动设置
62
63
  - `BT_SHELL_PATH` — **启动模式**:指定要 spawn 的 Rust shell 二进制路径(开发用;优先级最高,覆盖自动下载与本地构建)
63
64
  - `BT_SHELL_NO_DOWNLOAD` — 设为 `1` 时不自动下载(状态 `disabled`;需自行放置二进制或配合 `BT_SHELL_PATH`)
64
65
  - `BT_SHELL_DOWNLOAD_BASE` — 覆盖下载根(默认 GitHub Release `https://github.com/xiaoqiong0v0/opencode-browser-tool/releases/download`),可指向镜像/自建
65
66
  - `BT_SHELL_VERSION` — 显式指定**二进制发布版本**(形如 `1.2.0`,即 `x.Y.0` 的 Release;**原样使用、不做归 0 推导**;不设时由插件版本自动推导)
66
67
  - `BT_SHELL_NOTIFY_URL` — 插件通知地址(**推送式投递**;一般由插件自动通过 `--notify-url` / `/api/notify-url` 设置,仅在手动启动 shell 时需自行指定)
67
68
 
68
- > **附着模式 vs 启动模式**:设置了 `BT_SHELL_URL`(优先)或 `BT_SHELL_PORT` 时进入附着模式——插件**不 spawn** 任何进程,直接连接该地址的外部 shell;两者都未设置时按启动模式 spawn 本地二进制(`BT_SHELL_PATH` 可覆盖查找路径)。附着模式下 `bt_close` 只关闭浏览器窗口并断开连接,**不会**结束外部 shell 进程(进程不归插件管理)。
69
+ > **附着模式 vs 启动模式**:设置了 `BT_SHELL_URL`(优先)或 `BT_SHELL_PORT` 时进入附着模式——插件**不 spawn** 任何进程,直接连接该地址的外部 shell;两者都未设置时按启动模式 spawn 本地二进制(`BT_SHELL_PATH` 可覆盖查找路径)。附着模式下 `bt_close` 只断开本地连接(**不关闭外部窗口、不结束外部进程**;进程不归插件管理)。
70
+ >
71
+ > **附着模式必须设置 `BT_SHELL_TOKEN`**:外部 shell 启动时的令牌必须与插件侧环境变量一致(见下方示例),否则插件启动即报 `client.attach_need_token`,不会去连一个注定 401 的端点。令牌未设置时 shell 会随机生成,因此手动启动的 shell 务必显式传 `--token`(或用同值环境变量)。
72
+
73
+ **本地 API 语义**:`/api/*` 只监听 `127.0.0.1`,且只服务插件进程——所有请求必须带 `x-bt-token`(服务端常量时间比较);**任何带 `Origin` 头的请求一律 403**(浏览器跨源必带,插件 Node `fetch` 不带),服务端**不返回任何 CORS 头**、`OPTIONS` 直接 405。令牌在 shell 实例创建期确定、运行期不可变;若提供了 `--user-data-dir`,令牌还会写到 `<user-data-dir>/bt-auth-token`(Unix `chmod 600`)供排查。日志只打印令牌前 4 位与长度。**同进程的两个合法调用方各有例外**:面板 Webview 通过 Tauri `invoke("api_token")` 读取本实例令牌(只存 JS 内存,不写 DOM/HTML/日志)后再带 `x-bt-token` 调用;页面注入脚本无法持有令牌,故服务端仅对**精确路径 `/api/page-event`** 豁免 `Origin` 与令牌校验(不做前缀匹配),该端点只更新标签 url/title/icon、不执行任何操作。
69
74
 
70
75
  **WSL / Linux 附着示例**(shell 跑在 WSL,插件跑在 Windows 宿主):
71
76
 
72
77
  ```bash
73
- # WSL 内:构建并启动 Linux 版 shell,监听 18280
78
+ # WSL 内:构建并启动 Linux 版 shell,监听 18280(令牌须与宿主 BT_SHELL_TOKEN 完全一致)
74
79
  cd rust && cargo build --release
75
- ./target/release/bt-shell --port 18280
80
+ BT_SHELL_TOKEN=my-secret-token ./target/release/bt-shell --port 18280
81
+ # 等价:./target/release/bt-shell --port 18280 --token my-secret-token
76
82
  ```
77
83
 
78
84
  ```bash
79
85
  # Windows 宿主:设置环境变量后重启 opencode(WSL2 支持从宿主经 localhost 访问)
80
86
  set BT_SHELL_URL=http://127.0.0.1:18280
87
+ set BT_SHELL_TOKEN=my-secret-token
81
88
  ```
82
89
 
83
90
  ⚠ WSL 内启动 shell 时**不要**设置 `WEBKIT_DISABLE_DMABUF_RENDERER` / `WEBKIT_DISABLE_COMPOSITING_MODE`——它们会破坏透明合成(覆盖层渲染成黑块/透出桌面),详见 [docs/linux-support.md](./docs/linux-support.md)。
@@ -97,13 +104,13 @@ opencode(Bun)
97
104
 
98
105
  - 浏览器渲染引擎(WebView2 / WebKitGTK / WKWebView,随平台)直接绘制到插件窗口
99
106
  - 页面零注入残留脚本,弹框类元素可正常批注
100
- - 所有工具调用通过 `POST http://127.0.0.1:PORT/api/{command}` 通信
101
- - 除 spawn 本地 shell 外,也可用 `BT_SHELL_URL` / `BT_SHELL_PORT` **附着到已运行的 shell**(不 spawn,适用于 shell 跑在 WSL/Linux、插件跑在 Windows)
107
+ - 所有工具调用通过 `POST http://127.0.0.1:PORT/api/{command}` 通信,并统一带鉴权头 `x-bt-token`(无 CORS、拒绝任何带 `Origin` 的请求;唯一例外是页面事件桥 `/api/page-event`,见上)
108
+ - 除 spawn 本地 shell 外,也可用 `BT_SHELL_URL` / `BT_SHELL_PORT` **附着到已运行的 shell**(不 spawn,适用于 shell 跑在 WSL/Linux、插件跑在 Windows;**必须同时设置 `BT_SHELL_TOKEN`**,外部 shell 用同一令牌启动)
102
109
  - 跨平台:Windows / Linux / macOS
103
- - 真多标签:每标签独立 page Webview,切换不重载;`target=_blank` / `window.open` 链接通过 WebView2 原生事件拦截并打开为新标签
110
+ - 真多标签:每标签独立 page Webview,切换不重载;`target=_blank` / `window.open` 链接通过 WebView2 原生事件拦截并打开为新标签。**关闭标签会释放该标签的页面实例**(预创建池的 3 个 webview 保留复用,池外动态创建的实例直接销毁),反复开关标签不会累积页面进程
104
111
  - 地址栏/标题/图标**事件驱动同步(无轮询)**:导航用 `on_navigation`(请求即更新)+ `on_page_load`(完成后读真实 `location.href`/`title`);站内 SPA(`pushState`/`replaceState`/`popstate`/`hashchange`)与标题/图标变化由注入脚本上报 `POST /api/page-event`。`TabState.url` 只反映**最后一次真实导航请求**,内部/错误 scheme(`chrome-error:`/`about:`/`tauri:`/`data:` 等)不覆盖地址栏
105
112
  - 刷新语义:标签处于错误页(`errored`)时,工具栏刷新 / `bt_reload` **重新导航原 URL**(而非刷错误页);否则走原生 reload
106
- - 窗口无标题栏,自定义窗口按钮在标签行右侧;最小尺寸 500×400(逻辑像素)
113
+ - 窗口无标题栏,自定义窗口按钮在标签行右侧;最小尺寸 360×432(逻辑像素;内容区最小 360×360,含 72px 工具栏)
107
114
 
108
115
  ## 工具
109
116
 
@@ -120,7 +127,7 @@ opencode(Bun)
120
127
 
121
128
  ### 工具参数
122
129
 
123
- > **`--timeout ms`(可选,1.9.0 起)** —— 阻塞型命令(如 `bt_click` / `bt_fill` / `bt_evaluate` / `bt_screenshot` / `bt_wait_for_selector` 等)均支持按次传 `--timeout`,钳制到 `[100, 60000]` 毫秒;未传走服务端默认(15s),传小值可让慢操作**快失败**(如 `--timeout 800` 让卡住的 `evaluate` 在约 0.8s 返回 `eval timeout`),被钳制时输出会如实标注。
130
+ > **`--timeout ms`(可选,1.9.0 起)** —— 共 **17 条命令声明**带 `timeout` 参数(`src/index.ts:106-193`;其中 `bt_wait_for_selector` 原本就有该参数,其余 16 条为 1.9.0 起新增),均支持按次传 `--timeout`,钳制到 `[100, 60000]` 毫秒(`rust/src/service.rs:96-97,104-115`);未传走服务端默认(15s),传小值可让慢操作**快失败**(如 `--timeout 800` 让卡住的 `evaluate` 在约 0.8s 返回 `eval timeout`),被钳制时输出会如实标注。
124
131
 
125
132
  | 工具 | 参数(类型) | 说明 |
126
133
  |------|------|------|
@@ -141,10 +148,10 @@ opencode(Bun)
141
148
  | `bt_go_back` | 无 | 浏览器后退,返回当前 URL |
142
149
  | `bt_go_forward` | 无 | 浏览器前进,返回当前 URL |
143
150
  | `bt_resize` | `width`, `height`(number) 必填 | 调整**页面内容区(视口)**尺寸(非 OS 窗口;下限 360×360,低于下限被钳制并在返回标 `clamped`) |
144
- | `bt_set_device` | `name`(string) 可选 | 应用设备预设(空参数列出 13 种预设;**预设尺寸为内容区(视口)尺寸**) |
145
- | `bt_devtools` | `action`(string):`toggle`/`open`/`close` | 开关开发者工具 |
151
+ | `bt_set_device` | `name`(string) 可选 | 应用设备预设(空参数列出 14 种预设;**预设尺寸为内容区(视口)尺寸**) |
152
+ | `bt_devtools` | `action`(string):`toggle`/`open`/`close` | 开关开发者工具。**Windows 无法真正关闭**(wry/WebView2 无关闭 API),`close` 会如实返回不支持并提示用 F12 手动切换;Linux 可正常开关 |
146
153
  | `bt_reload` | 无 | 刷新当前页面;若当前为错误页则**重新导航原 URL**(返回 `retried`) |
147
- | `bt_close` | 无 | 退出浏览器外壳 |
154
+ | `bt_close` | 无 | 关闭浏览器外壳(`bt_close` 与手动关窗同一语义)。关闭后后续工具调用返回指引(`browser closed … call open_window`),**绝不自动重开**,需 `bt_open_window` 显式打开;attach 模式下只断开本地关联(不关闭外部窗口/进程) |
148
155
  | `bt_show_notification` | `message`(string), `type`(string):`ok`/`bad`/`err` | 显示页面通知气泡 |
149
156
  | `bt_scroll` | `direction`(string):`up`/`down`/`left`/`right`, `amount`(number) | 滚动页面 |
150
157
  | `bt_wait_for_selector` | `selector`, `timeout`(number, ms) | 等待元素出现 |
@@ -155,7 +162,7 @@ opencode(Bun)
155
162
  | `bt_list_tabs` | 无 | 列出标签页(索引+URL) |
156
163
  | `bt_switch_tab` | `index`(number) 必填 | 按位置(0 起)切换标签 |
157
164
  | `bt_new_tab` | `url`(string) 必填 | 新建独立标签页(真多标签)并导航 |
158
- | `bt_close_tab` | `index`(number) 可选 | 关闭指定标签;缺省关闭当前激活标签 |
165
+ | `bt_close_tab` | `index`(number) 可选 | 关闭指定标签;缺省关闭当前激活标签。关闭会**释放该标签的页面实例**(池内 webview 回池复用,池外实例销毁) |
159
166
  | `bt_get_element_state` | `selector`(string) 必填 | 返回元素可见性/文本/位置 |
160
167
  | `bt_scroll_to_element` | `selector`(string) 必填 | 滚动到元素 |
161
168
  | `bt_get_dropdown_options` | `selector`(string) 必填 | 列出下拉框选项 |
@@ -186,7 +193,7 @@ opencode(Bun)
186
193
 
187
194
  **坐标系(实测,v1.7.0)**:CDP `clip` **恒为文档坐标**(`captureBeyondViewport` true/false 均如此)——传视口坐标会在滚动后的页面截到错误区域(旧版元素截图在滚动页面上即踩此坑);截图层内部统一做 视口坐标 + `scrollX/Y` 换算,调用方一律传视口坐标。
188
195
 
189
- 错误口径不变:`element not found: <sel>` / `element has zero size: <sel>`。输出图片尺寸 = 元素 rect × devicePixelRatio。
196
+ 错误口径不变:`element not found: <sel>` / `element has zero size: <sel>`。**输出图片尺寸**:元素/区域截图(Windows CDP `clip` 固定 `scale:1`,`rust/src/control/screenshot.rs:148`;Linux cairo 裁剪不缩放,`rust/src/control/screenshot.rs:277`)为**选区 CSS 像素 1:1**(插件不额外乘 DPR;Linux 实现按「CSS 像素 = 设备像素」的 1:1 假设,WSLg dpr=1 实测);无 `selector` 的整视口截图**不带 `clip`/`scale`**(`rust/src/control/screenshot.rs:150`),由平台默认整屏捕获、插件不做缩放(具体像素尺寸取决于 WebView2/CDP 默认;Linux `Visible` 快照按上述 1:1 假设输出)。
190
197
 
191
198
  **已知限制**
192
199
 
@@ -201,14 +208,14 @@ opencode(Bun)
201
208
  - **内容区下限 360×360**:`bt_resize` 低于下限会被钳制,返回 `clamped:true`(工具输出也标注);窗口 `min_inner_size` 同步为 360×432(= 360 内容高 + 72 工具栏)
202
209
  - **窄模式(窗口逻辑宽 < 480)**:面板改为**填满整个窗口**(覆盖式,x=0;页面 webview 保持全宽在下层,关闭面板即见完整页面);工具栏的批注/截图/面板三按钮**去文字只留图标**(媒体查询 `@media (max-width: 479px)`,与 Rust `ui::NARROW_MODE_MAX_W=480` 同步维护)。手机类预设(360~412 宽)天然落入窄模式,避免按钮溢出
203
210
 
204
- 内置 13 种设备预设(**内容区尺寸** + User-Agent),可通过 `bt_set_device` 或右侧面板下拉框一键切换:
211
+ 内置 14 种设备预设(**内容区尺寸** + User-Agent),可通过 `bt_set_device` 或右侧面板下拉框一键切换:
205
212
 
206
- | 分类 | 预设 |
213
+ | 分类 | 预设(内容区尺寸) |
207
214
  |------|------|
208
- | 桌面 | `desktop-1080p`, `desktop-1440p` |
209
- | iPad | `ipad-pro-11`, `ipad-10`, `ipad-mini-6` |
210
- | iPhone | `iphone-15-pro`, `iphone-14`, `iphone-13`, `iphone-12`, `iphone-se` |
211
- | Android | `pixel-7`, `pixel-6`, `galaxy-s23` |
215
+ | 桌面 | `desktop-720p`(1024×720), `desktop-1080p`(1920×1080), `desktop-900p`(1440×900) |
216
+ | iPad | `ipad-pro-11`(834×1194), `ipad-10`(820×1180), `ipad-mini-6`(744×1133) |
217
+ | iPhone | `iphone-15-pro`(393×852), `iphone-14`(390×844), `iphone-13`(390×844), `iphone-12`(390×844), `iphone-se`(375×667) |
218
+ | Android | `pixel-7`(412×915), `pixel-6`(411×914), `galaxy-s23`(360×780) |
212
219
 
213
220
  切换时自动调整窗口尺寸并运行时修改 UA(UA 修改 Windows/Linux 支持;macOS 未实现)。
214
221
 
@@ -226,7 +233,7 @@ opencode(Bun)
226
233
 
227
234
  ## 多会话
228
235
 
229
- 自 1.9.0 起**每个 opencode 会话独享一个浏览器窗口**:独立进程 / 独立端口 / 独立用户数据目录(`sessions/<profile>/<sid>`),窗口、标签、UA、批注与 cookie/存储全部互不共享(原 `sessionIsolation` 开关已移除,隔离是唯一行为)。例外:附着模式(`BT_SHELL_URL` / `BT_SHELL_PORT`)连接外部单例 shell,放弃会话隔离。
236
+ 自 1.9.0 起**每个 opencode 会话独享一个浏览器窗口**:独立进程 / 独立端口 / 独立用户数据目录(`sessions/<profile>/<sid>`),窗口、标签、UA、批注与 cookie/存储全部互不共享(`sessionIsolation` / `browserType` 配置项及 `--session-isolation` / `--browser` 参数自 1.9.0 已删除,会话隔离是唯一行为;旧配置文件里的这两项会被忽略)。例外:附着模式(`BT_SHELL_URL` / `BT_SHELL_PORT`)连接外部单例 shell,放弃会话隔离。
230
237
 
231
238
  ## 发布
232
239
 
@@ -254,10 +261,16 @@ npm publish
254
261
 
255
262
  ```bash
256
263
  npm install
264
+ # 1) 前端产物(frontend/dist;tauri.conf.json 的 build.frontendDist 指向它,Rust 编译期嵌入)
265
+ npm run build:frontend # 等价:cd frontend && npm install && npm run build
266
+ # 2) Rust 外壳(开发构建;发布用 cargo build --release)
257
267
  cd rust && cargo build
258
- npm run build
268
+ # 3) 插件 TS → dist/
269
+ cd .. && npm run build
259
270
  ```
260
271
 
272
+ > **Windows 构建前置**:Tauri 的 Windows 资源需要 `rust/icons/icon.ico`(Tauri 默认图标路径)。该目录被 `.gitignore` 忽略、仓库不含图标源文件,需自行准备 `rust/icons/icon.ico`(可另放 `icon.png`)。Linux 构建不需要该图标。
273
+
261
274
  ## 日志
262
275
 
263
276
  插件侧统一使用公共包 `@xiaoqiong0v0/opencode-plugin-logger`,项目内由 `src/logger.ts` 导出共用实例。日志写入
package/dist/binary.js CHANGED
@@ -22,6 +22,7 @@ import { fileURLToPath, pathToFileURL } from "url";
22
22
  import { getPluginDataDir } from "./config/index.js";
23
23
  import { tf } from "./i18n/index.js";
24
24
  import { log } from "./logger.js";
25
+ import { sanitizeForModel } from "./util/sanitize.js";
25
26
  const __dirname = dirname(fileURLToPath(import.meta.url));
26
27
  /** 默认下载根(不含 `/v<version>/<asset>`),可用 BT_SHELL_DOWNLOAD_BASE 覆盖 */
27
28
  const DEFAULT_DOWNLOAD_BASE = "https://github.com/xiaoqiong0v0/opencode-browser-tool/releases/download";
@@ -131,7 +132,8 @@ export function getBinaryStatus() {
131
132
  return { ...current };
132
133
  }
133
134
  function setStatus(next) {
134
- current = next;
135
+ // reason 会经 describeBinaryStatus 回流模型:写入状态时先脱敏(保留错误分类信息,去掉本机路径)
136
+ current = next.reason ? { ...next, reason: sanitizeForModel(next.reason) } : next;
135
137
  }
136
138
  /** 触发后台下载(幂等;fire-and-forget,失败不抛出) */
137
139
  export function startDownload() {
@@ -164,22 +166,31 @@ export async function ensureBinary(timeoutMs = 20000) {
164
166
  * 约定:输出**不含任何本机绝对路径**(路径只进插件日志,不回流模型上下文)
165
167
  */
166
168
  export function describeBinaryStatus(s) {
169
+ let raw;
167
170
  switch (s.state) {
168
171
  case "ready":
169
172
  // 只报就绪态;不返回路径(旧版 return s.path 会把绝对 exe 路径回给模型)
170
- return tf("bin.ready");
173
+ raw = tf("bin.ready");
174
+ break;
171
175
  case "downloading":
172
- return tf("bin.downloading", { progress: s.progress ?? 0 });
176
+ raw = tf("bin.downloading", { progress: s.progress ?? 0 });
177
+ break;
173
178
  case "failed":
174
- return tf("bin.failed", { reason: s.reason ?? "unknown" });
179
+ raw = tf("bin.failed", { reason: s.reason ?? "unknown" });
180
+ break;
175
181
  case "disabled":
176
182
  // 不拼绝对路径(旧版含 s.path ?? cachedBinaryPath());只指环境变量,期望路径见插件日志
177
- return tf("bin.disabled");
183
+ raw = tf("bin.disabled");
184
+ break;
178
185
  case "unsupported":
179
- return tf("bin.unsupported", { reason: s.reason ?? `${process.platform}/${process.arch}` });
186
+ raw = tf("bin.unsupported", { reason: s.reason ?? `${process.platform}/${process.arch}` });
187
+ break;
180
188
  default:
181
- return tf("bin.not_ready");
189
+ raw = tf("bin.not_ready");
190
+ break;
182
191
  }
192
+ // 最后一道闸:无论 reason 来自哪个分支,返回模型前统一脱敏
193
+ return sanitizeForModel(raw);
183
194
  }
184
195
  // ---- 下载主流程 ----
185
196
  async function doDownload() {