@xiaoqiong0v0/opencode-browser-tool 1.6.0 → 1.9.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.
package/README.md CHANGED
@@ -48,8 +48,7 @@ sha256 校验(**幂等**:sha 与当前 release 期望值一致即跳过;**
48
48
  ```jsonc
49
49
  {
50
50
  "panelLang": "zh",
51
- "toolLang": "en",
52
- "sessionIsolation": false
51
+ "toolLang": "en"
53
52
  }
54
53
  ```
55
54
 
@@ -121,6 +120,8 @@ opencode(Bun)
121
120
 
122
121
  ### 工具参数
123
122
 
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`),被钳制时输出会如实标注。
124
+
124
125
  | 工具 | 参数(类型) | 说明 |
125
126
  |------|------|------|
126
127
  | `bt_navigate` | `url`(string) 必填 | 导航到指定地址(裸域名自动补 http://) |
@@ -132,15 +133,15 @@ opencode(Bun)
132
133
  | `bt_drag` | `sourceSelector`, `targetSelector`(string) 必填 | 从源元素拖到目标元素 |
133
134
  | `bt_press_key` | `key`(string) 必填, `selector`(string) 可选 | 按键(如 Enter/Escape);可指定聚焦元素 |
134
135
  | `bt_upload_file` | `selector`, `filePath`(string) 必填 | 向文件输入框上传文件 |
135
- | `bt_screenshot` | `selector`(string) 可选 | 截取视口;指定 `selector` 时截该元素区域(PNG 图片附件) |
136
+ | `bt_screenshot` | `selector`(string) 可选 | 截取视口;指定 `selector` 时先滚动到可见再截该元素区域,**元素比视口还大也能整块截全**(PNG 图片附件) |
136
137
  | `bt_evaluate` | `script`(string) 必填 | 在页面执行 JS 并返回 JSON 结果 |
137
138
  | `bt_get_visible_text` | `selector`(string) 可选 | 返回页面/元素可见文本 |
138
139
  | `bt_get_visible_html` | `selector`, `removeScripts`(boolean), `removeComments`(boolean), `maxLength`(number) | 返回页面/元素 HTML |
139
140
  | `bt_console_logs` | `type`(string), `search`(string), `limit`(number), `clear`(boolean) | 读取页面控制台日志 |
140
141
  | `bt_go_back` | 无 | 浏览器后退,返回当前 URL |
141
142
  | `bt_go_forward` | 无 | 浏览器前进,返回当前 URL |
142
- | `bt_resize` | `width`, `height`(number) 必填 | 调整窗口尺寸(逻辑像素) |
143
- | `bt_set_device` | `name`(string) 可选 | 应用设备预设(空参数列出 13 种预设) |
143
+ | `bt_resize` | `width`, `height`(number) 必填 | 调整**页面内容区(视口)**尺寸(非 OS 窗口;下限 360×360,低于下限被钳制并在返回标 `clamped`) |
144
+ | `bt_set_device` | `name`(string) 可选 | 应用设备预设(空参数列出 13 种预设;**预设尺寸为内容区(视口)尺寸**) |
144
145
  | `bt_devtools` | `action`(string):`toggle`/`open`/`close` | 开关开发者工具 |
145
146
  | `bt_reload` | 无 | 刷新当前页面;若当前为错误页则**重新导航原 URL**(返回 `retried`) |
146
147
  | `bt_close` | 无 | 退出浏览器外壳 |
@@ -162,7 +163,7 @@ opencode(Bun)
162
163
  | `bt_open_window` | 无 | 打开浏览器窗口(未启动则启动;已启动幂等) |
163
164
  | `bt_fake_audio` | `kind`(string) 必填,`data`/`freq`/`durMs`/`notes`/`digits`(string),`loop`(boolean) | 向页面注入模拟麦克风音频 |
164
165
  | `bt_fake_video` | `kind`(string) 必填,`data`/`url`(string),`loop`(boolean) | 向页面注入模拟摄像头画面 |
165
- | `bt_profile` | `set` / `delete`(string) 可选 | user-data 配置管理:空参列出;`--set` 切换并重启服务;`--delete` 删除(默认/激活项除外) |
166
+ | `bt_profile` | `set` / `delete`(string) 可选 | user-data 配置管理:空参列出;`--set` 切换默认配置(影响**后续新会话**的数据根,不重启浏览器);`--delete` 删除(默认/激活项除外) |
166
167
  | `bt_exports` | 无 | 显示导出目录与 Edge/Chrome 导出指引 |
167
168
  | `bt_lookup` | `csv`, `url`(string) 必填 | 从密码 CSV 按站点匹配并返回凭据(写入临时文件,不进上下文) |
168
169
  | `bt_expect_response` | `url`(string) 必填 | 记录期望匹配的响应模式,清空响应历史后重新捕获 |
@@ -171,9 +172,36 @@ opencode(Bun)
171
172
  | `bt_list_records` | 无 | 列出批注/截图记录(索引/标签/说明;截图带 `+img`,已发送带 `[sent]`) |
172
173
  | `bt_read_record_content` | `id`(number) 必填 | 读取单条记录详情(截图附带图片大小与落盘路径) |
173
174
 
174
- ## 设备预设
175
+ ### 元素截图行为(v1.7.0 起统一)
176
+
177
+ `bt_screenshot --selector <css>` 固定流程:
178
+
179
+ 1. **先滚动**:复用 `scroll_to_element`(立即 `scrollIntoView` 居中 + 轮询等滚动稳定);未到达/未稳定**不吞错**,结果带 `reached`/`stable`/`waitedMs`,工具输出追加对应提示
180
+ 2. **重测 rect**:滚动稳定后重新取元素视口矩形(覆盖懒加载/布局变化后的真位置)
181
+ 3. **rect 完全落在视口内** → 常规 clip 路径(`captureBeyondViewport:false`,同旧版)
182
+ 4. **rect 仍超出视口**(元素比视口还高/宽)→ **越界路径,整块截全**(不做尺寸上限)
183
+ - Windows:CDP `Page.captureScreenshot` + `clip` + `captureBeyondViewport:true`
184
+ - Linux:WebKitGTK `SnapshotRegion::FullDocument` 整页快照 + cairo 按文档坐标裁剪(该 API 只有 Visible/FullDocument 两档、无矩形参数)
185
+ 5. 无 `selector` = 整视口截图(保持现状,无 `--full` 参数)
186
+
187
+ **坐标系(实测,v1.7.0)**:CDP `clip` **恒为文档坐标**(`captureBeyondViewport` true/false 均如此)——传视口坐标会在滚动后的页面截到错误区域(旧版元素截图在滚动页面上即踩此坑);截图层内部统一做 视口坐标 + `scrollX/Y` 换算,调用方一律传视口坐标。
188
+
189
+ 错误口径不变:`element not found: <sel>` / `element has zero size: <sel>`。输出图片尺寸 = 元素 rect × devicePixelRatio。
190
+
191
+ **已知限制**
192
+
193
+ - **sticky/fixed 在越界路径只成像一次**,且两端位置不同:Windows 绘制在「截图瞬间它们在视口中的位置」(换算到文档坐标 ≈ scrollY 处);Linux `FullDocument` 整页渲染下 `sticky` 停在自然流位置、`fixed` 绘制在**文档顶部**
194
+ - Linux(含 WSLg)截图路径已实测通过(见 `docs/implementation.md`);**真实 Linux 桌面(GNOME/KDE)仍待复验**
195
+ - 折下懒加载图(`loading=lazy`)经 cache-bust 实测:滚动前 `complete=false`,自动滚动后加载完成、截图内容非空白
196
+
197
+ ## 设备预设 / 尺寸语义
198
+
199
+ > ⚠️ **行为变更(v1.8.0)**:`bt_resize` 与 `bt_set_device` 的宽高一律指**页面内容区(视口)**尺寸,不再是 OS 窗口尺寸。窗口高 = 内容区高 + 工具栏 72px。**旧脚本若按窗口尺寸理解,高度会偏 72px**。API 返回同时给出 `content` 与 `window` 两组尺寸便于核对。
200
+
201
+ - **内容区下限 360×360**:`bt_resize` 低于下限会被钳制,返回 `clamped:true`(工具输出也标注);窗口 `min_inner_size` 同步为 360×432(= 360 内容高 + 72 工具栏)
202
+ - **窄模式(窗口逻辑宽 < 480)**:面板改为**填满整个窗口**(覆盖式,x=0;页面 webview 保持全宽在下层,关闭面板即见完整页面);工具栏的批注/截图/面板三按钮**去文字只留图标**(媒体查询 `@media (max-width: 479px)`,与 Rust `ui::NARROW_MODE_MAX_W=480` 同步维护)。手机类预设(360~412 宽)天然落入窄模式,避免按钮溢出
175
203
 
176
- 内置 13 种设备预设(窗口尺寸 + User-Agent),可通过 `bt_set_device` 或右侧面板下拉框一键切换:
204
+ 内置 13 种设备预设(**内容区尺寸** + User-Agent),可通过 `bt_set_device` 或右侧面板下拉框一键切换:
177
205
 
178
206
  | 分类 | 预设 |
179
207
  |------|------|
@@ -191,14 +219,14 @@ opencode(Bun)
191
219
  - **批注模式** — 悬停高亮元素(覆盖层自绘),点击元素弹出输入框填写说明;引擎层拦截,弹框/下拉类元素不失焦
192
220
  - **截图模式** — 点击立即截全屏;也可进入截图模式后拖动框选区域(选区可拖拽手柄调整大小),保存时可按需裁剪(遮罩式选区,默认整图,双击还原)
193
221
  - **记录列表** — 面板「AI 功能」区:批注/截图记录卡片(截图带缩略图),显示所属标签 URL 与说明
194
- - **发送** — 面板底部「发送」按钮:所有记录(批注文字 + 截图图片)推送到 opencode 对话;发送后**面板列表清空**(与旧 Playwright 工具一致,仅列表为空),但**记录本身保留**并标记 `[sent]`(`bt_list_records` 仍可读取,截图也可通过 `bt_read_record_content` 取到)。投递为**推送式**:shell 发送后主动通知插件(`POST /notify`),插件收到即拉取并推送到对话(无轮询、无 2s 延迟)
222
+ - **发送** — 面板底部「发送」按钮:所有记录(批注文字 + 截图图片)推送到 opencode 对话;发送后**面板列表清空**(与旧 Playwright 工具一致,仅列表为空),但**记录本身保留**并标记 `[sent]`(`bt_list_records` 仍可读取,截图也可通过 `bt_read_record_content` 取到)。投递为**推送式**:shell 发送后主动通知插件(`POST /notify/<sid>`,按会话归属),插件收到即拉取并推送到对话(无轮询、无 2s 延迟)
195
223
  - 批注和截图**必须填写说明**才能保存/发送,否则弹出提示
196
224
 
197
225
  面板「配置」区:外观主题(跟随系统/浅色/深色)、设备预设下拉(等价 `bt_set_device`)、开发者工具按钮(等价 `bt_devtools`)。
198
226
 
199
227
  ## 多会话
200
228
 
201
- 父子会话共享一个浏览器。开启 `sessionIsolation: true` 后,每个 opencode 会话有独立上下文(cookies/存储隔离)。
229
+ 自 1.9.0 起**每个 opencode 会话独享一个浏览器窗口**:独立进程 / 独立端口 / 独立用户数据目录(`sessions/<profile>/<sid>`),窗口、标签、UA、批注与 cookie/存储全部互不共享(原 `sessionIsolation` 开关已移除,隔离是唯一行为)。例外:附着模式(`BT_SHELL_URL` / `BT_SHELL_PORT`)连接外部单例 shell,放弃会话隔离。
202
230
 
203
231
  ## 发布
204
232
 
package/dist/binary.js CHANGED
@@ -20,6 +20,7 @@ import { chmodSync, closeSync, createWriteStream, existsSync, mkdirSync, openSyn
20
20
  import { dirname, resolve } from "path";
21
21
  import { fileURLToPath, pathToFileURL } from "url";
22
22
  import { getPluginDataDir } from "./config/index.js";
23
+ import { tf } from "./i18n/index.js";
23
24
  import { log } from "./logger.js";
24
25
  const __dirname = dirname(fileURLToPath(import.meta.url));
25
26
  /** 默认下载根(不含 `/v<version>/<asset>`),可用 BT_SHELL_DOWNLOAD_BASE 覆盖 */
@@ -158,21 +159,26 @@ export async function ensureBinary(timeoutMs = 20000) {
158
159
  }
159
160
  return getBinaryStatus();
160
161
  }
161
- /** 就绪状态的可读提示文案(供工具在未就绪时返回) */
162
+ /**
163
+ * 就绪状态的可读提示文案(供工具在未就绪时返回)
164
+ * 约定:输出**不含任何本机绝对路径**(路径只进插件日志,不回流模型上下文)
165
+ */
162
166
  export function describeBinaryStatus(s) {
163
167
  switch (s.state) {
164
168
  case "ready":
165
- return s.path ?? "ready";
169
+ // 只报就绪态;不返回路径(旧版 return s.path 会把绝对 exe 路径回给模型)
170
+ return tf("bin.ready");
166
171
  case "downloading":
167
- return `bt-shell 正在下载(${s.progress ?? 0}%)… 稍后重试`;
172
+ return tf("bin.downloading", { progress: s.progress ?? 0 });
168
173
  case "failed":
169
- return `bt-shell 下载失败:${s.reason ?? "未知原因"};可用 BT_SHELL_DOWNLOAD_BASE 换源、或 BT_SHELL_PATH 手动指定二进制`;
174
+ return tf("bin.failed", { reason: s.reason ?? "unknown" });
170
175
  case "disabled":
171
- return `bt-shell 自动下载已禁用(BT_SHELL_NO_DOWNLOAD=1);请用 BT_SHELL_PATH 指定二进制,或把它放到 ${s.path ?? cachedBinaryPath()}`;
176
+ // 不拼绝对路径(旧版含 s.path ?? cachedBinaryPath());只指环境变量,期望路径见插件日志
177
+ return tf("bin.disabled");
172
178
  case "unsupported":
173
- return `bt-shell 暂不支持当前平台:${s.reason ?? `${process.platform}/${process.arch}`}`;
179
+ return tf("bin.unsupported", { reason: s.reason ?? `${process.platform}/${process.arch}` });
174
180
  default:
175
- return "bt-shell 尚未就绪,请稍后重试";
181
+ return tf("bin.not_ready");
176
182
  }
177
183
  }
178
184
  // ---- 下载主流程 ----
@@ -467,7 +473,7 @@ async function fetchText(url) {
467
473
  function curlText(url) {
468
474
  const r = spawnSync("curl", ["-sL", "--fail", url], { encoding: "utf-8", maxBuffer: 8 * 1024 * 1024 });
469
475
  if (r.status !== 0)
470
- throw new Error(`curl exit ${r.status}: ${(r.stderr || "").trim() || "获取失败"}`);
476
+ throw new Error(`curl exit ${r.status}: ${(r.stderr || "").trim() || "fetch failed"}`);
471
477
  return r.stdout || "";
472
478
  }
473
479
  // ---- 校验/锁/工具 ----
@@ -552,7 +558,7 @@ function notFoundHint(tag, e) {
552
558
  const notFound = m.includes("404") || m.includes("curl exit 22") || m.includes("not found");
553
559
  if (!notFound)
554
560
  return "";
555
- return `未找到该版本对应的 Release 资产(tag=${tag});若这是纯插件改动请确认二进制产物仍在 x.Y.0 的 Release 中,若动了 Rust 需先升中间版本号并新开/更新对应 Release`;
561
+ return tf("bin.release_not_found", { tag });
556
562
  }
557
563
  function sleep(ms) {
558
564
  return new Promise((r) => setTimeout(r, ms));