@xiaoqiong0v0/opencode-browser-tool 1.2.0 → 1.3.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
@@ -13,6 +13,32 @@ opencode 插件:Tauri 多 Webview 浏览器外壳 + 零注入视觉元素选
13
13
  }
14
14
  ```
15
15
 
16
+ ## 二进制获取(bt-shell)
17
+
18
+ 插件依赖 Rust 外壳 `bt-shell`。默认**首次使用时后台自动下载**对应平台的 Release 资产到
19
+ `~/.opencode/plugins-data/opencode-browser-tool/<平台三元组>/bt-shell[.exe]`(Windows 即
20
+ `%USERPROFILE%\.opencode\plugins-data\opencode-browser-tool\<triple>\bt-shell.exe`),并**就地覆盖**同一路径
21
+ (不按插件版本建目录);同目录另有 `bt-shell.version.json` 记录该可执行文件的来源
22
+ (`tag` / `asset` / `sha256` / `size` / `downloadedAt` / `sourceUrl`)。下载用 Release 的 `SHA256SUMS` 做
23
+ sha256 校验(**幂等**:sha 与当前 release 期望值一致即跳过;**原子**替换;跨进程 `.lock`;Linux 下载后 `chmod 755`)。下载后台进行、**不阻塞 opencode 启动**;未就绪时工具调用会给出
24
+ 明确提示(下载进度 / 失败原因),不会假装成功。
25
+
26
+ 平台支持与系统依赖:
27
+
28
+ - Windows x64 → `x86_64-pc-windows-msvc`(WebView2,系统自带)
29
+ - Linux x64 → `x86_64-unknown-linux-gnu`,需系统库 `libwebkit2gtk-4.1` / `libgtk-3`(及 appindicator / rsvg 等,见 [docs/linux-support.md](./docs/linux-support.md) §5)
30
+ - 其它平台:暂不提供预编译,请用 `BT_SHELL_PATH` 指定自行构建的二进制
31
+
32
+ > 代理:下载优先调用系统 `curl`(自动遵循 `HTTPS_PROXY`/`HTTP_PROXY`/`NO_PROXY`);无 curl 时回退 Node `fetch`。
33
+
34
+ ## 版本与产物策略
35
+
36
+ - **中间位(minor)**:只要**动了 Rust / 要发新 exe**,就升 `x.Y.0`(如 `1.2.x → 1.3.0`),并为该 `x.Y.0` 新建/更新 Release 挂上二进制。
37
+ - **末位(patch)**:**只改插件**(TS/配置/文档,不改 Rust)时只升末位(如 `1.2.0 → 1.2.1`),**不新发二进制**。
38
+ - **二进制产物永远只挂在 `x.Y.0` 的 Release 上**:插件的 patch 版本**自动推导**出对应的二进制 tag(把 patch 归 0):插件 `1.2.1` → 二进制 tag `v1.2.0`;`1.3.0` → `v1.3.0`;`1.3.0-beta.1` → `v1.3.0`。
39
+ - 因此纯插件改动升级时**复用同一份二进制**,不会重下;只有当推导出的 `x.Y.0` 与缓存中二进制的 sha 不一致(发新 exe)时才重新下载。
40
+ - 如需指向别的二进制发布(如临时验证),用 `BT_SHELL_VERSION` 显式覆盖——它表示**二进制发布版本**(形如 `1.2.0`),**原样使用、不做归 0 推导**。
41
+
16
42
  ## 配置
17
43
 
18
44
  配置文件:`~/.config/opencode/browser-tool.jsonc`(首次运行自动生成)
@@ -32,7 +58,10 @@ opencode 插件:Tauri 多 Webview 浏览器外壳 + 零注入视觉元素选
32
58
  - `BT_BROWSERS_PATH` — 浏览器缓存目录
33
59
  - `BT_SHELL_URL` — **附着模式**:连接到已运行的 shell(完整基地址,如 `http://127.0.0.1:18280`),优先级最高
34
60
  - `BT_SHELL_PORT` — **附着模式**:仅指定端口,等价于 `http://127.0.0.1:<port>`
35
- - `BT_SHELL_PATH` — **启动模式**:指定要 spawn 的 Rust shell 二进制路径(开发用)
61
+ - `BT_SHELL_PATH` — **启动模式**:指定要 spawn 的 Rust shell 二进制路径(开发用;优先级最高,覆盖自动下载与本地构建)
62
+ - `BT_SHELL_NO_DOWNLOAD` — 设为 `1` 时不自动下载(状态 `disabled`;需自行放置二进制或配合 `BT_SHELL_PATH`)
63
+ - `BT_SHELL_DOWNLOAD_BASE` — 覆盖下载根(默认 GitHub Release `https://github.com/xiaoqiong0v0/opencode-browser-tool/releases/download`),可指向镜像/自建
64
+ - `BT_SHELL_VERSION` — 显式指定**二进制发布版本**(形如 `1.2.0`,即 `x.Y.0` 的 Release;**原样使用、不做归 0 推导**;不设时由插件版本自动推导)
36
65
 
37
66
  > **附着模式 vs 启动模式**:设置了 `BT_SHELL_URL`(优先)或 `BT_SHELL_PORT` 时进入附着模式——插件**不 spawn** 任何进程,直接连接该地址的外部 shell;两者都未设置时按启动模式 spawn 本地二进制(`BT_SHELL_PATH` 可覆盖查找路径)。附着模式下 `bt_close` 只关闭浏览器窗口并断开连接,**不会**结束外部 shell 进程(进程不归插件管理)。
38
67
 
@@ -76,12 +105,13 @@ opencode(Bun)
76
105
 
77
106
  | 类别 | 工具 |
78
107
  |------|------|
79
- | **导航** | `bt_navigate`, `bt_go_back`, `bt_go_forward`, `bt_reload`, `bt_close` |
108
+ | **导航** | `bt_navigate`, `bt_go_back`, `bt_go_forward`, `bt_reload`, `bt_open_window`, `bt_close` |
80
109
  | **交互** | `bt_click`, `bt_fill`, `bt_clear`, `bt_select`, `bt_hover`, `bt_drag`, `bt_press_key`, `bt_upload_file`, `bt_iframe_click`, `bt_iframe_fill` |
81
110
  | **标签页** | `bt_list_tabs`, `bt_switch_tab`, `bt_new_tab`, `bt_close_tab`, `bt_click_and_switch_tab` |
82
111
  | **信息** | `bt_screenshot`, `bt_evaluate`, `bt_get_visible_text`, `bt_get_visible_html`, `bt_console_logs`, `bt_get_browser_status`, `bt_get_element_state`, `bt_get_dropdown_options`, `bt_list_records`, `bt_expect_response`, `bt_assert_response`, `bt_get_accessibility_tree` |
83
112
  | **滚动/等待** | `bt_scroll`, `bt_scroll_to_element`, `bt_wait_for_selector`, `bt_resize`, `bt_set_device` |
84
113
  | **设备/工具** | `bt_custom_user_agent`, `bt_devtools`(开发者工具开关) |
114
+ | **媒体/本地** | `bt_fake_audio`, `bt_fake_video`, `bt_profile`, `bt_exports`, `bt_lookup` |
85
115
  | **其他** | `bt_show_notification`, `bt_read_record_content` |
86
116
 
87
117
  ### 工具参数
@@ -97,7 +127,7 @@ opencode(Bun)
97
127
  | `bt_drag` | `sourceSelector`, `targetSelector`(string) 必填 | 从源元素拖到目标元素 |
98
128
  | `bt_press_key` | `key`(string) 必填, `selector`(string) 可选 | 按键(如 Enter/Escape);可指定聚焦元素 |
99
129
  | `bt_upload_file` | `selector`, `filePath`(string) 必填 | 向文件输入框上传文件 |
100
- | `bt_screenshot` | `selector`(string) 可选(当前忽略) | 截取当前视口,返回图片附件(PNG) |
130
+ | `bt_screenshot` | `selector`(string) 可选 | 截取视口;指定 `selector` 时截该元素区域(PNG 图片附件) |
101
131
  | `bt_evaluate` | `script`(string) 必填 | 在页面执行 JS 并返回 JSON 结果 |
102
132
  | `bt_get_visible_text` | `selector`(string) 可选 | 返回页面/元素可见文本 |
103
133
  | `bt_get_visible_html` | `selector`, `removeScripts`(boolean), `removeComments`(boolean), `maxLength`(number) | 返回页面/元素 HTML |
@@ -115,7 +145,7 @@ opencode(Bun)
115
145
  | `bt_click_and_switch_tab` | `selector`(string) 必填 | 点击元素;若触发新标签则自动切换,返回当前 URL |
116
146
  | `bt_iframe_click` | `iframeSelector`, `selector`(string) 必填 | 在 iframe 中点击(仅同源可访问) |
117
147
  | `bt_iframe_fill` | `iframeSelector`, `selector`, `value`(string) 必填 | 在 iframe 中输入(仅同源可访问) |
118
- | `bt_get_browser_status` | 无 | 返回 open/url/title/tabs 数量 |
148
+ | `bt_get_browser_status` | 无 | **纯查询、不启动浏览器**:运行中返回 open/url/title/tabs 数量;未运行时返回未运行提示 + bt-shell 二进制状态(下载中/就绪/失败/禁用) |
119
149
  | `bt_list_tabs` | 无 | 列出标签页(索引+URL) |
120
150
  | `bt_switch_tab` | `index`(number) 必填 | 按位置(0 起)切换标签 |
121
151
  | `bt_new_tab` | `url`(string) 必填 | 新建独立标签页(真多标签)并导航 |
@@ -123,12 +153,18 @@ opencode(Bun)
123
153
  | `bt_get_element_state` | `selector`(string) 必填 | 返回元素可见性/文本/位置 |
124
154
  | `bt_scroll_to_element` | `selector`(string) 必填 | 滚动到元素 |
125
155
  | `bt_get_dropdown_options` | `selector`(string) 必填 | 列出下拉框选项 |
126
- | `bt_custom_user_agent` | `userAgent`(string) 必填 | 设置自定义 User-Agent(仅 Windows 支持) |
156
+ | `bt_custom_user_agent` | `userAgent`(string) 必填 | 设置自定义 User-Agent(Windows/Linux 支持;macOS 未实现) |
157
+ | `bt_open_window` | 无 | 打开浏览器窗口(未启动则启动;已启动幂等) |
158
+ | `bt_fake_audio` | `kind`(string) 必填,`data`/`freq`/`durMs`/`notes`/`digits`(string),`loop`(boolean) | 向页面注入模拟麦克风音频 |
159
+ | `bt_fake_video` | `kind`(string) 必填,`data`/`url`(string),`loop`(boolean) | 向页面注入模拟摄像头画面 |
160
+ | `bt_profile` | `set` / `delete`(string) 可选 | user-data 配置管理:空参列出;`--set` 切换并重启服务;`--delete` 删除(默认/激活项除外) |
161
+ | `bt_exports` | 无 | 显示导出目录与 Edge/Chrome 导出指引 |
162
+ | `bt_lookup` | `csv`, `url`(string) 必填 | 从密码 CSV 按站点匹配并返回凭据(写入临时文件,不进上下文) |
127
163
  | `bt_expect_response` | `url`(string) 必填 | 记录期望匹配的响应模式,清空响应历史后重新捕获 |
128
164
  | `bt_assert_response` | `id`(string) 必填 | 断言是否存在匹配的响应(返回 `url` + `status` 码) |
129
165
  | `bt_get_accessibility_tree` | `selector`, `maxDepth`(number) | 返回页面可访问性树(role/name/value 嵌套结构) |
130
- | `bt_list_records` | 无 | 列出批注/截图记录(索引/标签/说明) |
131
- | `bt_read_record_content` | `id`(number) 必填 | 读取单条记录详情 |
166
+ | `bt_list_records` | 无 | 列出批注/截图记录(索引/标签/说明;截图带 `+img`,已发送带 `[sent]`) |
167
+ | `bt_read_record_content` | `id`(number) 必填 | 读取单条记录详情(截图附带图片大小与落盘路径) |
132
168
 
133
169
  ## 设备预设
134
170
 
@@ -141,7 +177,7 @@ opencode(Bun)
141
177
  | iPhone | `iphone-15-pro`, `iphone-14`, `iphone-13`, `iphone-12`, `iphone-se` |
142
178
  | Android | `pixel-7`, `pixel-6`, `galaxy-s23` |
143
179
 
144
- 切换时自动调整窗口尺寸并运行时修改 UA(UA 修改仅 Windows 支持)。
180
+ 切换时自动调整窗口尺寸并运行时修改 UA(UA 修改 Windows/Linux 支持;macOS 未实现)。
145
181
 
146
182
  ## 批注 / 截图
147
183
 
@@ -161,12 +197,25 @@ opencode(Bun)
161
197
 
162
198
  ## 发布
163
199
 
200
+ 版本规则见上文「版本与产物策略」:**动了 Rust / 发新 exe 才升中间位(minor)**,纯插件改动只升末位(patch);**二进制资产只挂在 `x.Y.0` 的 Release 上**(插件 patch 版本由自身版本推导二进制 tag)。
201
+
164
202
  ```bash
165
- cd rust && cargo build --release
203
+ # 1) 定版本(动 Rust 用 minor;纯插件用 patch)
204
+ npm version <x.y.z> --no-git-tag-version
205
+ # 2) 构建插件产物(清空 dist 再建,避免孤儿 .js)
206
+ npm run build
207
+ # 3) 提交 + 打 tag + 建 Release(tag = v<x.y.z>)
208
+ # 只有动 Rust 时才需要为 x.Y.0 上传各平台二进制 + SHA256SUMS:
209
+ gh release create v<x.y.z> --title v<x.y.z> --notes "..."
210
+ gh release upload v<x.y.z> <各平台二进制> SHA256SUMS --clobber
211
+ # 4) 发布 npm 包(只含 dist;不含二进制)
166
212
  npm publish
167
213
  ```
168
214
 
169
- 只发布 `dist/`(`files: ["dist"]`)。
215
+ - `SHA256SUMS` 每行 `<sha256> <文件名>`(两空格),文件名不带路径。
216
+ - npm 包只带 `dist/`(`files: ["dist"]`);原生二进制由运行时从 Release 下载(见「二进制获取」)。
217
+ - **先本地自测**:可用 `.tmp/publish-local.ps1` 覆盖到 opencode 插件缓存后重启验证(做法与脚本模板见技能 `xqv-plugin-release`)。
218
+ - **部署顺序(exe 文件锁)**:若已有 opencode 实例在跑,`cargo build --release` 会在最后一步报 `failed to remove file ... (os error 5)`(产物不可信)→ 先**退出 opencode**(确认 shell 也退出)→ 构建 → 重新启动。TS 改动需 `npm run build` 重建 `dist/`。
170
219
 
171
220
  ## 开发
172
221
 
@@ -179,4 +228,7 @@ npm run build
179
228
  ## 文档
180
229
 
181
230
  - [docs/v5-tauri-architecture.md](./docs/v5-tauri-architecture.md) — V5 当前架构
182
- - [docs/implementation.md](./docs/implementation.md) — 实施状态
231
+ - [docs/implementation.md](./docs/implementation.md) — 实施状态与关键经验
232
+ - [docs/linux-support.md](./docs/linux-support.md) — Linux 适配、硬性约定,及 §7「平台能力与降级策略」(可信通道/降级矩阵)
233
+ - [docs/linux-verification.md](./docs/linux-verification.md) — Kali/Linux 可信输入复验清单(含 `tests/manual/verify-linux.sh` 一键 15 项)
234
+ - [docs/README.md](./docs/README.md) — docs 索引
package/dist/binary.js ADDED
@@ -0,0 +1,569 @@
1
+ //! 二进制分发:从 GitHub Release 下载 bt-shell 到插件数据目录并校验
2
+ //!
3
+ //! 目录布局(固定路径,就地覆盖;不按插件版本建目录,避免累积与无效重下):
4
+ //! `<pluginDataDir>/<triple>/bt-shell[.exe]` 可执行文件
5
+ //! `<pluginDataDir>/<triple>/bt-shell.version.json` 来源旁文件(tag/asset/sha256/size/…)
6
+ //!
7
+ //! 设计要点:
8
+ //! - 幂等:目标存在 **且** sha256 与"当前插件版本对应 release 的 SHA256SUMS"一致 → 跳过;
9
+ //! **每次都拉 SHA256SUMS 校验**(取不到即失败,不跳过校验),但不会因插件版本变化无条件重下
10
+ //! - 原子:下载到 `<target>.part`,校验通过后 `rename` 替换到最终路径
11
+ //! - 并发:同进程共享 Promise;跨进程用 `<target>.lock`(未过期则等待复用,避免重复下载)
12
+ //! - 有界:`ensureBinary(timeoutMs)` 等待至就绪/超时,不无限等待
13
+ //! - 迁移:启动清理旧布局的版本目录(`<pluginDataDir>/<x.y.z>/`),可移动一份合法资产省一次下载
14
+ //! - 代理:优先用系统 `curl`(自动遵循 HTTPS_PROXY/HTTP_PROXY),不可用时回退 `fetch`
15
+ //!
16
+ //! 环境变量:BT_SHELL_PATH / BT_SHELL_NO_DOWNLOAD / BT_SHELL_DOWNLOAD_BASE / BT_SHELL_VERSION
17
+ import { spawn, spawnSync } from "child_process";
18
+ import { createHash } from "crypto";
19
+ import { chmodSync, closeSync, createWriteStream, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "fs";
20
+ import { dirname, resolve } from "path";
21
+ import { fileURLToPath, pathToFileURL } from "url";
22
+ import { getPluginDataDir } from "./config/index.js";
23
+ const __dirname = dirname(fileURLToPath(import.meta.url));
24
+ /** 默认下载根(不含 `/v<version>/<asset>`),可用 BT_SHELL_DOWNLOAD_BASE 覆盖 */
25
+ const DEFAULT_DOWNLOAD_BASE = "https://github.com/xiaoqiong0v0/opencode-browser-tool/releases/download";
26
+ /** 跨进程锁过期时间(ms):超过则视为陈旧锁可接管 */
27
+ const LOCK_STALE_MS = 10 * 60 * 1000;
28
+ /** 等待其它进程下载完成的上限(ms) */
29
+ const WAIT_OTHER_PROCESS_MS = 60 * 1000;
30
+ /** 版本旁文件名 */
31
+ const SIDECAR_NAME = "bt-shell.version.json";
32
+ /** 旧布局版本目录名(如 `1.2.0`;仅删符合该形态的目录) */
33
+ const LEGACY_VERSION_DIR_RE = /^\d+\.\d+\.\d+([-+][0-9A-Za-z.-]+)?$/;
34
+ /** 当前平台 → Release 资产信息;不支持的平台返回 null */
35
+ export function platformInfo() {
36
+ const { platform, arch } = process;
37
+ if (platform === "win32" && arch === "x64") {
38
+ return { triple: "x86_64-pc-windows-msvc", assetName: "bt-shell-x86_64-pc-windows-msvc.exe" };
39
+ }
40
+ if (platform === "linux" && arch === "x64") {
41
+ return { triple: "x86_64-unknown-linux-gnu", assetName: "bt-shell-x86_64-unknown-linux-gnu" };
42
+ }
43
+ return null;
44
+ }
45
+ /** 插件自身版本(读包元数据;不受 BT_SHELL_VERSION 影响) */
46
+ export function pluginVersion() {
47
+ try {
48
+ const pkg = JSON.parse(readFileSync(resolve(__dirname, "..", "package.json"), "utf-8"));
49
+ if (pkg?.version)
50
+ return String(pkg.version);
51
+ }
52
+ catch {
53
+ // 忽略:回退占位版本
54
+ }
55
+ return "0.0.0";
56
+ }
57
+ /**
58
+ * 二进制发布版本:取插件版本的 `<major>.<minor>.0`(忽略预发布/构建元数据)。
59
+ *
60
+ * 版本策略:二进制产物**只挂在 `x.Y.0` 的 Release 上** —— 动了 Rust 升中间位(minor)并发新 exe;
61
+ * 只改插件升末位(patch),沿用同一二进制 tag。故插件需由自身版本推导二进制 tag:
62
+ * `1.2.1 → 1.2.0`、`1.3.0 → 1.3.0`、`1.3.0-beta.1 → 1.3.0`、`2.0.5 → 2.0.0`。
63
+ */
64
+ export function binaryReleaseVersion(version) {
65
+ const m = String(version).trim().match(/^v?(\d+)\.(\d+)(?:\.\d+)?/);
66
+ if (!m)
67
+ return "0.0.0";
68
+ return `${m[1]}.${m[2]}.0`;
69
+ }
70
+ /**
71
+ * 实际要拉取的二进制发布版本:
72
+ * - `BT_SHELL_VERSION` 显式指定时**原样使用**(不做归 0 推导;形如 `1.2.0`,不带 `v`)
73
+ * - 否则由插件版本推导(`binaryReleaseVersion`)
74
+ */
75
+ export function binaryVersion() {
76
+ const env = process.env.BT_SHELL_VERSION?.trim();
77
+ if (env)
78
+ return env;
79
+ return binaryReleaseVersion(pluginVersion());
80
+ }
81
+ /** 二进制发布 tag:`v<binaryVersion>` */
82
+ export function binaryTag() {
83
+ return `v${binaryVersion()}`;
84
+ }
85
+ /** Release 下载根(含推导后的二进制版本):`<base>/v<major>.<minor>.0` */
86
+ function releaseBase() {
87
+ const base = (process.env.BT_SHELL_DOWNLOAD_BASE?.trim() || DEFAULT_DOWNLOAD_BASE).replace(/\/+$/, "");
88
+ return `${base}/v${binaryVersion()}`;
89
+ }
90
+ /** 本地可执行文件名(固定,不带 triple/版本) */
91
+ function localBinaryName() {
92
+ return process.platform === "win32" ? "bt-shell.exe" : "bt-shell";
93
+ }
94
+ /** 本地 triple 目录名(不支持平台时用 `${platform}-${arch}` 占位) */
95
+ function localTriple() {
96
+ return platformInfo()?.triple ?? `${process.platform}-${process.arch}`;
97
+ }
98
+ /** 固定缓存路径:`<pluginDataDir>/<triple>/bt-shell[.exe]` */
99
+ export function cachedBinaryPath() {
100
+ return resolve(getPluginDataDir(), localTriple(), localBinaryName());
101
+ }
102
+ /** 版本旁文件路径(与可执行文件同目录) */
103
+ export function cachedSidecarPath() {
104
+ return resolve(dirname(cachedBinaryPath()), SIDECAR_NAME);
105
+ }
106
+ /** 供外部(工具提示)使用:二进制的三元组/文件名/下载 URL/缓存路径 */
107
+ export function getBinaryInfo() {
108
+ const info = platformInfo();
109
+ if (!info)
110
+ return null;
111
+ const path = cachedBinaryPath();
112
+ return {
113
+ pluginVersion: pluginVersion(),
114
+ version: binaryVersion(),
115
+ tag: binaryTag(),
116
+ triple: info.triple,
117
+ assetName: info.assetName,
118
+ url: `${releaseBase()}/${info.assetName}`,
119
+ sumsUrl: `${releaseBase()}/SHA256SUMS`,
120
+ path,
121
+ sidecarPath: cachedSidecarPath(),
122
+ };
123
+ }
124
+ // ---- 状态机 ----
125
+ let current = { state: "idle", path: undefined };
126
+ /** 同进程内共享的下载 Promise(并发只下载一次) */
127
+ let inflight = null;
128
+ export function getBinaryStatus() {
129
+ return { ...current };
130
+ }
131
+ function setStatus(next) {
132
+ current = next;
133
+ }
134
+ /** 触发后台下载(幂等;fire-and-forget,失败不抛出) */
135
+ export function startDownload() {
136
+ if (inflight)
137
+ return;
138
+ if (current.state === "ready" || current.state === "disabled" || current.state === "unsupported")
139
+ return;
140
+ inflight = doDownload()
141
+ .catch(() => {
142
+ // 失败原因已写入状态;这里吞掉,避免影响调用方(opencode 启动)
143
+ })
144
+ .finally(() => {
145
+ inflight = null;
146
+ });
147
+ }
148
+ /** 等待二进制就绪或超时(不无限等待);超时返回当前状态 */
149
+ export async function ensureBinary(timeoutMs = 20000) {
150
+ startDownload();
151
+ const deadline = Date.now() + timeoutMs;
152
+ while (Date.now() < deadline) {
153
+ const s = getBinaryStatus();
154
+ if (s.state !== "idle" && s.state !== "downloading")
155
+ return s;
156
+ await sleep(200);
157
+ }
158
+ return getBinaryStatus();
159
+ }
160
+ /** 就绪状态的可读提示文案(供工具在未就绪时返回) */
161
+ export function describeBinaryStatus(s) {
162
+ switch (s.state) {
163
+ case "ready":
164
+ return s.path ?? "ready";
165
+ case "downloading":
166
+ return `bt-shell 正在下载(${s.progress ?? 0}%)… 稍后重试`;
167
+ case "failed":
168
+ return `bt-shell 下载失败:${s.reason ?? "未知原因"};可用 BT_SHELL_DOWNLOAD_BASE 换源、或 BT_SHELL_PATH 手动指定二进制`;
169
+ case "disabled":
170
+ return `bt-shell 自动下载已禁用(BT_SHELL_NO_DOWNLOAD=1);请用 BT_SHELL_PATH 指定二进制,或把它放到 ${s.path ?? cachedBinaryPath()}`;
171
+ case "unsupported":
172
+ return `bt-shell 暂不支持当前平台:${s.reason ?? `${process.platform}/${process.arch}`}`;
173
+ default:
174
+ return "bt-shell 尚未就绪,请稍后重试";
175
+ }
176
+ }
177
+ // ---- 下载主流程 ----
178
+ async function doDownload() {
179
+ const path = cachedBinaryPath();
180
+ if (process.env.BT_SHELL_NO_DOWNLOAD === "1") {
181
+ setStatus({ state: "disabled", reason: "BT_SHELL_NO_DOWNLOAD=1", path });
182
+ return;
183
+ }
184
+ const info = platformInfo();
185
+ if (!info) {
186
+ setStatus({ state: "unsupported", reason: `${process.platform}/${process.arch}`, path });
187
+ return;
188
+ }
189
+ const finalPath = path;
190
+ const partPath = `${finalPath}.part`;
191
+ const lockPath = `${finalPath}.lock`;
192
+ const tag = binaryTag();
193
+ const sourceUrl = `${releaseBase()}/${info.assetName}`;
194
+ mkdirSync(dirname(finalPath), { recursive: true });
195
+ setStatus({ state: "downloading", progress: 0, path: finalPath });
196
+ // 1) 每次都拉 SHA256SUMS 做校验(取不到即失败,不跳过校验)
197
+ let sumsText;
198
+ try {
199
+ sumsText = await fetchText(`${releaseBase()}/SHA256SUMS`);
200
+ }
201
+ catch (e) {
202
+ const hint = notFoundHint(tag, e);
203
+ setStatus({
204
+ state: "failed",
205
+ reason: `无法获取 SHA256SUMS(不跳过校验):${errMsg(e)}${hint ? `;${hint}` : ""}`,
206
+ path: finalPath,
207
+ });
208
+ return;
209
+ }
210
+ const expected = parseSums(sumsText, info.assetName);
211
+ if (!expected) {
212
+ setStatus({ state: "failed", reason: `SHA256SUMS 中未找到 ${info.assetName}`, path: finalPath });
213
+ return;
214
+ }
215
+ // 2) 迁移:清理旧布局版本目录,必要时从旧目录移动合法资产(同盘 rename)
216
+ migrateLegacyDirs(info, finalPath, expected, sourceUrl);
217
+ // 3) 幂等:目标存在且 sha 与当前 release 期望一致 → 跳过(不重下)
218
+ if (existsSync(finalPath) && sha256File(finalPath) === expected) {
219
+ ensureSidecar(finalPath, info, expected, sourceUrl);
220
+ setStatus({ state: "ready", path: finalPath });
221
+ return;
222
+ }
223
+ // 4) 跨进程锁:抢不到则等其它进程下载完成
224
+ if (!acquireLock(lockPath)) {
225
+ const ok = await waitForValidFile(finalPath, expected, WAIT_OTHER_PROCESS_MS);
226
+ if (ok) {
227
+ ensureSidecar(finalPath, info, expected, sourceUrl);
228
+ setStatus({ state: "ready", path: finalPath });
229
+ }
230
+ else {
231
+ setStatus({ state: "failed", reason: "等待其它进程下载超时(可删除 .lock 后重试)", path: finalPath });
232
+ }
233
+ return;
234
+ }
235
+ try {
236
+ try {
237
+ if (existsSync(partPath))
238
+ unlinkSync(partPath);
239
+ }
240
+ catch { }
241
+ await downloadTo(sourceUrl, partPath, (p) => setStatus({ state: "downloading", progress: p, path: finalPath }));
242
+ const got = sha256File(partPath);
243
+ if (got !== expected) {
244
+ safeUnlink(partPath);
245
+ setStatus({
246
+ state: "failed",
247
+ reason: `sha256 校验失败:期望 ${expected.slice(0, 12)}… 实际 ${got.slice(0, 12)}…`,
248
+ path: finalPath,
249
+ });
250
+ return;
251
+ }
252
+ renameSync(partPath, finalPath); // 原子替换
253
+ if (process.platform !== "win32") {
254
+ try {
255
+ chmodSync(finalPath, 0o755);
256
+ }
257
+ catch { }
258
+ }
259
+ ensureSidecar(finalPath, info, expected, sourceUrl);
260
+ setStatus({ state: "ready", path: finalPath });
261
+ }
262
+ catch (e) {
263
+ safeUnlink(partPath);
264
+ const hint = notFoundHint(tag, e);
265
+ setStatus({ state: "failed", reason: `${errMsg(e)}${hint ? `;${hint}` : ""}`, path: finalPath });
266
+ }
267
+ finally {
268
+ releaseLock(lockPath);
269
+ }
270
+ }
271
+ // ---- 迁移:旧布局 `<pluginDataDir>/<x.y.z>/<triple>/<asset>` → 新固定路径 ----
272
+ /**
273
+ * 清理旧布局版本目录(仅匹配 `<x.y.z>` 形态,其它一律不碰)。
274
+ * - dry-run:先把清单打印到日志
275
+ * - 若新路径无合法文件,优先从旧目录"移动"一份 sha 匹配的资产(同盘 rename,省一次下载)
276
+ * - 随后删除全部旧版本目录
277
+ */
278
+ function migrateLegacyDirs(info, finalPath, expected, sourceUrl) {
279
+ const dataDir = getPluginDataDir();
280
+ let entries;
281
+ try {
282
+ entries = readdirSync(dataDir, { withFileTypes: true });
283
+ }
284
+ catch {
285
+ return;
286
+ }
287
+ const legacyDirs = entries
288
+ .filter((e) => e.isDirectory() && LEGACY_VERSION_DIR_RE.test(e.name))
289
+ .map((e) => resolve(dataDir, e.name));
290
+ if (legacyDirs.length === 0)
291
+ return;
292
+ console.log(`[bt-shell][migrate] dry-run 旧版本目录清单: ${legacyDirs.join(", ")}`);
293
+ const newValid = existsSync(finalPath) && sha256File(finalPath) === expected;
294
+ if (!newValid) {
295
+ for (const dir of legacyDirs) {
296
+ const cand = resolve(dir, info.triple, info.assetName);
297
+ try {
298
+ if (existsSync(cand) && sha256File(cand) === expected) {
299
+ mkdirSync(dirname(finalPath), { recursive: true });
300
+ renameSync(cand, finalPath); // 同盘 rename
301
+ console.log(`[bt-shell][migrate] moved ${cand} -> ${finalPath}`);
302
+ break;
303
+ }
304
+ }
305
+ catch {
306
+ // 候选不可用则继续尝试下一个
307
+ }
308
+ }
309
+ }
310
+ else {
311
+ console.log(`[bt-shell][migrate] 新路径已有合法文件,保留 ${finalPath}`);
312
+ }
313
+ for (const dir of legacyDirs) {
314
+ try {
315
+ rmSync(dir, { recursive: true, force: true });
316
+ console.log(`[bt-shell][migrate] removed ${dir}`);
317
+ }
318
+ catch (e) {
319
+ console.log(`[bt-shell][migrate] remove failed ${dir}: ${errMsg(e)}`);
320
+ }
321
+ }
322
+ if (existsSync(finalPath) && sha256File(finalPath) === expected) {
323
+ ensureSidecar(finalPath, info, expected, sourceUrl, "migrated");
324
+ }
325
+ }
326
+ /** 写版本旁文件;已存在且 sha 一致则不动(避免无谓改写 mtime) */
327
+ function ensureSidecar(finalPath, info, sha256, sourceUrl, extra) {
328
+ const sidecarPath = resolve(dirname(finalPath), SIDECAR_NAME);
329
+ try {
330
+ if (existsSync(sidecarPath)) {
331
+ const prev = JSON.parse(readFileSync(sidecarPath, "utf-8"));
332
+ if (prev?.sha256 === sha256 &&
333
+ prev?.asset === info.assetName &&
334
+ prev?.tag === binaryTag()) {
335
+ return;
336
+ }
337
+ }
338
+ const version = {
339
+ tag: binaryTag(),
340
+ pluginVersion: pluginVersion(),
341
+ asset: info.assetName,
342
+ sha256,
343
+ size: statSync(finalPath).size,
344
+ downloadedAt: new Date().toISOString(),
345
+ sourceUrl,
346
+ };
347
+ writeFileSync(sidecarPath, JSON.stringify(version, null, 2), "utf-8");
348
+ console.log(`[bt-shell] 写入版本旁文件 ${sidecarPath}${extra ? ` (${extra})` : ""}`);
349
+ }
350
+ catch (e) {
351
+ console.log(`[bt-shell] 写入版本旁文件失败: ${errMsg(e)}`);
352
+ }
353
+ }
354
+ // ---- 下载实现:curl 优先(自动遵循系统代理),回退 fetch ----
355
+ let curlChecked = false;
356
+ let curlOk = false;
357
+ function curlAvailable() {
358
+ if (!curlChecked) {
359
+ curlChecked = true;
360
+ try {
361
+ curlOk = spawnSync("curl", ["--version"], { stdio: "ignore" }).status === 0;
362
+ }
363
+ catch {
364
+ curlOk = false;
365
+ }
366
+ }
367
+ return curlOk;
368
+ }
369
+ async function downloadTo(url, dest, onProgress) {
370
+ if (curlAvailable())
371
+ return downloadWithCurl(url, dest, onProgress);
372
+ return downloadWithFetch(url, dest, onProgress);
373
+ }
374
+ /** 用系统 curl 下载(curl 自动读取 HTTPS_PROXY/HTTP_PROXY/NO_PROXY 并跟随重定向) */
375
+ async function downloadWithCurl(url, dest, onProgress) {
376
+ const total = curlContentLength(url);
377
+ await new Promise((resolvePromise, reject) => {
378
+ const child = spawn("curl", ["-L", "--fail", "--silent", "--show-error", "-o", dest, url], {
379
+ stdio: ["ignore", "ignore", "pipe"],
380
+ });
381
+ let stderr = "";
382
+ child.stderr?.on("data", (d) => {
383
+ stderr += d.toString();
384
+ });
385
+ const timer = setInterval(() => {
386
+ try {
387
+ const size = statSync(dest).size;
388
+ onProgress(total ? Math.min(100, Math.floor((size * 100) / total)) : undefined);
389
+ }
390
+ catch {
391
+ // .part 尚未创建
392
+ }
393
+ }, 200);
394
+ child.on("error", (e) => {
395
+ clearInterval(timer);
396
+ reject(e);
397
+ });
398
+ child.on("close", (code) => {
399
+ clearInterval(timer);
400
+ if (code === 0)
401
+ resolvePromise();
402
+ else
403
+ reject(new Error(`curl exit ${code}: ${stderr.trim() || "下载失败"}`));
404
+ });
405
+ });
406
+ }
407
+ /** HEAD 取 Content-Length(取不到返回 undefined;进度仍可降级为未知) */
408
+ function curlContentLength(url) {
409
+ try {
410
+ const r = spawnSync("curl", ["-sIL", url], { encoding: "utf-8", maxBuffer: 8 * 1024 * 1024 });
411
+ if (r.status !== 0 || !r.stdout)
412
+ return undefined;
413
+ let total;
414
+ for (const line of r.stdout.split(/\r?\n/)) {
415
+ const m = line.match(/^content-length:\s*(\d+)/i);
416
+ if (m) {
417
+ const n = Number(m[1]);
418
+ if (n > 0)
419
+ total = n;
420
+ }
421
+ }
422
+ return total;
423
+ }
424
+ catch {
425
+ return undefined;
426
+ }
427
+ }
428
+ async function downloadWithFetch(url, dest, onProgress) {
429
+ const res = await fetch(url, { redirect: "follow" });
430
+ if (!res.ok || !res.body)
431
+ throw new Error(`HTTP ${res.status} ${res.statusText}`);
432
+ const total = Number(res.headers.get("content-length") || 0) || undefined;
433
+ const out = createWriteStream(dest);
434
+ const reader = res.body.getReader();
435
+ let received = 0;
436
+ try {
437
+ for (;;) {
438
+ const { done, value } = await reader.read();
439
+ if (done)
440
+ break;
441
+ if (value) {
442
+ received += value.length;
443
+ out.write(Buffer.from(value));
444
+ onProgress(total ? Math.min(100, Math.floor((received * 100) / total)) : undefined);
445
+ }
446
+ }
447
+ }
448
+ finally {
449
+ await new Promise((r) => out.end(() => r()));
450
+ }
451
+ }
452
+ /** 取文本:fetch 优先(无代理时直连);失败回退 curl(代理环境) */
453
+ async function fetchText(url) {
454
+ try {
455
+ const res = await fetch(url, { redirect: "follow" });
456
+ if (!res.ok)
457
+ throw new Error(`HTTP ${res.status} ${res.statusText}`);
458
+ return await res.text();
459
+ }
460
+ catch (e) {
461
+ if (curlAvailable())
462
+ return curlText(url);
463
+ throw e;
464
+ }
465
+ }
466
+ function curlText(url) {
467
+ const r = spawnSync("curl", ["-sL", "--fail", url], { encoding: "utf-8", maxBuffer: 8 * 1024 * 1024 });
468
+ if (r.status !== 0)
469
+ throw new Error(`curl exit ${r.status}: ${(r.stderr || "").trim() || "获取失败"}`);
470
+ return r.stdout || "";
471
+ }
472
+ // ---- 校验/锁/工具 ----
473
+ /** 计算文件 sha256(hex,流式读取,避免大文件占内存) */
474
+ function sha256File(path) {
475
+ const hash = createHash("sha256");
476
+ const fd = openSync(path, "r");
477
+ const buf = Buffer.alloc(1024 * 256);
478
+ try {
479
+ for (;;) {
480
+ const n = readSync(fd, buf, 0, buf.length, null);
481
+ if (n <= 0)
482
+ break;
483
+ hash.update(buf.subarray(0, n));
484
+ }
485
+ }
486
+ finally {
487
+ closeSync(fd);
488
+ }
489
+ return hash.digest("hex");
490
+ }
491
+ /** 从 SHA256SUMS 解析目标资产的 sha256;找不到返回 null */
492
+ function parseSums(text, assetName) {
493
+ for (const line of text.split(/\r?\n/)) {
494
+ const m = line.trim().match(/^([0-9a-fA-F]{64})\s+\*?(.+)$/);
495
+ if (m && m[2].trim() === assetName)
496
+ return m[1].toLowerCase();
497
+ }
498
+ return null;
499
+ }
500
+ /** 抢占跨进程锁(原子创建);陈旧锁可接管;失败返回 false(表示其它进程在下载) */
501
+ function acquireLock(lockPath) {
502
+ try {
503
+ writeFileSync(lockPath, `${process.pid} ${Date.now()}`, { flag: "wx" });
504
+ return true;
505
+ }
506
+ catch (e) {
507
+ if (e?.code !== "EEXIST")
508
+ return true; // 其它错误不阻塞下载
509
+ try {
510
+ const age = Date.now() - statSync(lockPath).mtimeMs;
511
+ if (age > LOCK_STALE_MS) {
512
+ unlinkSync(lockPath);
513
+ return acquireLock(lockPath);
514
+ }
515
+ }
516
+ catch {
517
+ // 锁文件刚被删除等:重试一次
518
+ return acquireLock(lockPath);
519
+ }
520
+ return false;
521
+ }
522
+ }
523
+ function releaseLock(lockPath) {
524
+ safeUnlink(lockPath);
525
+ }
526
+ async function waitForValidFile(path, expected, timeoutMs) {
527
+ const deadline = Date.now() + timeoutMs;
528
+ while (Date.now() < deadline) {
529
+ try {
530
+ if (existsSync(path) && sha256File(path) === expected)
531
+ return true;
532
+ }
533
+ catch { }
534
+ await sleep(300);
535
+ }
536
+ return false;
537
+ }
538
+ function safeUnlink(path) {
539
+ try {
540
+ if (existsSync(path))
541
+ unlinkSync(path);
542
+ }
543
+ catch { }
544
+ }
545
+ function errMsg(e) {
546
+ return e instanceof Error ? e.message : String(e);
547
+ }
548
+ /** Release/资产不存在(HTTP 404 / curl exit 22)时的针对性提示 */
549
+ function notFoundHint(tag, e) {
550
+ const m = errMsg(e).toLowerCase();
551
+ const notFound = m.includes("404") || m.includes("curl exit 22") || m.includes("not found");
552
+ if (!notFound)
553
+ return "";
554
+ return `未找到该版本对应的 Release 资产(tag=${tag});若这是纯插件改动请确认二进制产物仍在 x.Y.0 的 Release 中,若动了 Rust 需先升中间版本号并新开/更新对应 Release`;
555
+ }
556
+ function sleep(ms) {
557
+ return new Promise((r) => setTimeout(r, ms));
558
+ }
559
+ // ---- 独立运行:`node dist/binary.js [--timeout=ms]`〔便于测试〕----
560
+ const isMain = process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
561
+ if (isMain) {
562
+ const arg = process.argv.find((a) => a.startsWith("--timeout="));
563
+ const timeout = arg ? Number(arg.split("=")[1]) : 20000;
564
+ startDownload();
565
+ ensureBinary(Number.isFinite(timeout) ? timeout : 20000).then((s) => {
566
+ console.log(JSON.stringify(s, null, 2));
567
+ process.exit(s.state === "ready" || s.state === "disabled" || s.state === "unsupported" ? 0 : 1);
568
+ });
569
+ }
package/dist/client.js CHANGED
@@ -2,19 +2,24 @@ import { spawn } from "child_process";
2
2
  import { resolve, dirname } from "path";
3
3
  import { existsSync } from "fs";
4
4
  import { fileURLToPath } from "url";
5
- import createLogger from "@xiaoqiong0v0/opencode-plugin-logger";
5
+ import { log } from "./logger.js";
6
+ import { cachedBinaryPath, describeBinaryStatus, ensureBinary } from "./binary.js";
6
7
  const __dirname = dirname(fileURLToPath(import.meta.url));
7
8
  /** 就绪轮询超时(ms) */
8
9
  const READY_TIMEOUT_MS = 20000;
9
10
  /** 就绪轮询间隔(ms) */
10
11
  const READY_POLL_INTERVAL_MS = 300;
11
- // Rust 二进制查找:dist/bin/bt-shell-{platform} 或环境变量覆盖(仅启动模式使用)
12
+ // Rust 二进制查找:优先级 BT_SHELL_PATH → 本地开发构建 → 下载缓存(binary.ts)
12
13
  function resolveShellBinary() {
13
14
  const platform = process.platform === "win32" ? "win-x64" : "linux-x64";
14
15
  const bin = process.platform === "win32" ? "bt-shell.exe" : "bt-shell";
16
+ // 1) 显式指定:最优先(即使文件暂不存在也返回,由 startService 给出明确错误)
17
+ const envPath = process.env.BT_SHELL_PATH;
18
+ if (envPath)
19
+ return envPath;
20
+ // 2) 本地开发构建(保持开发者流程不变)
15
21
  const cargoTargetDir = process.env.CARGO_TARGET_DIR;
16
22
  const candidates = [
17
- process.env.BT_SHELL_PATH,
18
23
  resolve(__dirname, "bin", `bt-shell-${platform}.exe`),
19
24
  resolve(__dirname, "bin", `bt-shell-${platform}`),
20
25
  resolve(__dirname, "..", "rust", "target", "release", bin),
@@ -27,8 +32,8 @@ function resolveShellBinary() {
27
32
  if (c && existsSync(c))
28
33
  return c;
29
34
  }
30
- // 默认:开发环境用 cargo target 产物(release 优先)
31
- return resolve(__dirname, "..", "rust", "target", "release", bin);
35
+ // 3) 下载缓存(未下载时由 startService 先 ensureBinary)
36
+ return cachedBinaryPath();
32
37
  }
33
38
  /** 解析附着模式目标地址:BT_SHELL_URL 优先,其次 BT_SHELL_PORT;均未设置返回 null */
34
39
  function resolveAttachBaseUrl() {
@@ -118,7 +123,6 @@ async function waitForReady(baseUrl, timeoutMessage) {
118
123
  }
119
124
  /** 附着到外部已运行的 shell(不 spawn):等待就绪后记录 base URL */
120
125
  async function attachToService(baseUrl) {
121
- const log = createLogger("opencode-browser-tool");
122
126
  attachMode = true;
123
127
  log.info(`Attaching to existing bt-shell at ${baseUrl} (no spawn)`);
124
128
  await waitForReady(baseUrl, `External bt-shell not ready at ${baseUrl}. Check BT_SHELL_URL/BT_SHELL_PORT and that the shell is running.`);
@@ -127,9 +131,19 @@ async function attachToService(baseUrl) {
127
131
  log.info(`Attached to existing bt-shell at ${baseUrl}`);
128
132
  }
129
133
  export async function startService(nodePath, browsersPath, sessionIsolation, browserType, userDataDir) {
130
- const log = createLogger("opencode-browser-tool");
131
134
  attachMode = false;
132
- const shell = resolveShellBinary();
135
+ let shell = resolveShellBinary();
136
+ // 未就绪:先(有界)等待下载完成;失败/超时给出明确提示
137
+ if (!existsSync(shell)) {
138
+ if (process.env.BT_SHELL_PATH) {
139
+ throw new Error(`BT_SHELL_PATH 指向的二进制不存在:${shell}`);
140
+ }
141
+ const st = await ensureBinary(20000);
142
+ if (st.state !== "ready" || !st.path) {
143
+ throw new Error(describeBinaryStatus(st));
144
+ }
145
+ shell = st.path;
146
+ }
133
147
  // 显式指定端口(release 模式 GUI 程序无控制台,无法解析 stdout)
134
148
  const port = 18000 + Math.floor(Math.random() * 1000);
135
149
  const args = ["--browsers-path", browsersPath || "", "--port", String(port)];
@@ -141,6 +155,16 @@ export async function startService(nodePath, browsersPath, sessionIsolation, bro
141
155
  if (userDataDir)
142
156
  args.push("--user-data-dir", userDataDir);
143
157
  serviceProcess = spawn(shell, args, { stdio: ["ignore", "pipe", "pipe"] });
158
+ // 把 shell 的 stdout/stderr 转发进共享日志:Rust 侧 println!/eprintln! 默认被管道吞掉(无人读取 → 日志永远看不到)
159
+ const forwardShell = (tag) => (chunk) => {
160
+ for (const line of chunk.toString().split(/\r?\n/)) {
161
+ const s = line.trim();
162
+ if (s)
163
+ log.info(`${tag} ${s}`);
164
+ }
165
+ };
166
+ serviceProcess.stdout?.on("data", forwardShell("[shell:out]"));
167
+ serviceProcess.stderr?.on("data", forwardShell("[shell:err]"));
144
168
  // 等待服务就绪(轮询端口)
145
169
  const baseUrl = `http://127.0.0.1:${port}`;
146
170
  await waitForReady(baseUrl, "Service timeout: bt-shell did not start. Build it with: cd rust && cargo build --release");
@@ -149,7 +173,6 @@ export async function startService(nodePath, browsersPath, sessionIsolation, bro
149
173
  log.info(`Shell service ready on port ${port} (${shell})`);
150
174
  }
151
175
  export async function stopService() {
152
- const log = createLogger("opencode-browser-tool");
153
176
  if (attachMode) {
154
177
  // 附着模式:外部 shell 进程不归插件管,只清空本地状态
155
178
  log.info("Detached from external bt-shell (process left running)");
@@ -173,6 +196,35 @@ export async function openWindow() {
173
196
  export function isRunning() {
174
197
  return serviceReady;
175
198
  }
199
+ /**
200
+ * 纯查询:探测 shell 是否在运行,**绝不 spawn**。
201
+ * 仅在本进程已启动/附着(`serviceBaseUrl` 已知)时做一次短超时 HTTP 探测;否则返回 null。
202
+ * 用于 `get_browser_status` 这类只读命令,避免查询也弹出浏览器窗口。
203
+ */
204
+ export async function probeStatus(timeoutMs = 1500) {
205
+ if (!serviceReady || !serviceBaseUrl)
206
+ return null;
207
+ const ac = new AbortController();
208
+ const timer = setTimeout(() => ac.abort(), timeoutMs);
209
+ try {
210
+ const res = await fetch(`${serviceBaseUrl}/api/status`, {
211
+ method: "POST",
212
+ headers: { "Content-Type": "application/json" },
213
+ body: "{}",
214
+ signal: ac.signal,
215
+ });
216
+ if (!res.ok)
217
+ return null;
218
+ const json = await res.json();
219
+ return json?.success ? json.data : null;
220
+ }
221
+ catch {
222
+ return null;
223
+ }
224
+ finally {
225
+ clearTimeout(timer);
226
+ }
227
+ }
176
228
  function cmd(name) {
177
229
  return (params, sessionId) => callApi(`/api/${name}`, params, sessionId);
178
230
  }
package/dist/index.js CHANGED
@@ -6,10 +6,11 @@ import { loadConfig, getConfig, getBrowsersDir, getProfilesDir, getProfileDir, g
6
6
  import { registerLocale, t } from "./i18n/index.js";
7
7
  import en from "./i18n/en.js";
8
8
  import zh from "./i18n/zh.js";
9
- import { configureService, setUserDataDir, ensureService, openWindow, isRunning, stopService, service } from "./client.js";
9
+ import { configureService, setUserDataDir, ensureService, openWindow, isRunning, stopService, service, probeStatus } from "./client.js";
10
+ import { startDownload, getBinaryStatus, describeBinaryStatus } from "./binary.js";
10
11
  import { tool } from "@opencode-ai/plugin";
11
- import createLogger from "@xiaoqiong0v0/opencode-plugin-logger";
12
- const log = createLogger("browser-tool");
12
+ import { log } from "./logger.js";
13
+ import { createSessionIDCache, extractSessionIDFromEvent } from "./session-id.js";
13
14
  const _t = (k) => t(k);
14
15
  /** 降级说明:服务端在无可信通道、退回 untrusted DOM/JS 时返回 degraded,统一在此追加标注 */
15
16
  function degradedNote(r) {
@@ -53,7 +54,7 @@ const COMMANDS = {
53
54
  upload_file: { usage: "--selector --filePath", descKey: "cli.cmd.upload_file", args: [{ flag: "selector" }, { flag: "filePath" }], run: async (a) => { await service.uploadFile(a); return "Uploaded"; } },
54
55
  screenshot: { usage: "[--selector]", descKey: "cli.cmd.screenshot", args: [{ flag: "selector" }], run: async (a) => {
55
56
  const r = await service.screenshot(a);
56
- return { output: `Screenshot taken${a.selector ? ` (element: ${a.selector})` : " (full page)"}`, attachments: [{ type: "file", mime: r.mime || "image/png", data: r.base64, url: "" }] };
57
+ return { output: `Screenshot taken${a.selector ? ` (element: ${a.selector})` : " (full page)"}`, attachments: [{ type: "file", mime: r.mime || "image/png", url: `data:${r.mime || "image/png"};base64,${r.base64}` }] };
57
58
  } },
58
59
  evaluate: { usage: "--script", descKey: "cli.cmd.evaluate", args: [{ flag: "script" }], run: async (a) => JSON.stringify(await service.evaluate(a), null, 2) },
59
60
  get_visible_text: { usage: "[--selector]", descKey: "cli.cmd.get_visible_text", args: [{ flag: "selector" }], run: async (a) => (await service.visibleText(a))?.text || "(no visible text)" },
@@ -90,7 +91,12 @@ const COMMANDS = {
90
91
  iframe_click: { usage: "--iframeSelector --selector", descKey: "cli.cmd.iframe_click", args: [{ flag: "iframeSelector" }, { flag: "selector" }], run: async (a) => { const r = await service.iframeClick(a); return "Clicked in iframe" + degradedNote(r); } },
91
92
  iframe_fill: { usage: "--iframeSelector --selector --value", descKey: "cli.cmd.iframe_fill", args: [{ flag: "iframeSelector" }, { flag: "selector" }, { flag: "value" }], run: async (a) => { const r = await service.iframeFill(a); return "Filled in iframe" + degradedNote(r); } },
92
93
  get_browser_status: { usage: "", descKey: "cli.cmd.get_browser_status", run: async () => {
93
- const s = await service.status();
94
+ // 纯查询:不 spawn、不懒启动(未运行只提示,不弹窗)
95
+ const s = await probeStatus();
96
+ if (!s) {
97
+ const b = getBinaryStatus();
98
+ return `Browser is not running.\nbt-shell: ${describeBinaryStatus(b)}\n(执行任意其它工具会自动启动;也可用 open_window 显式启动)`;
99
+ }
94
100
  if (s.installing && Object.keys(s.installing).length > 0)
95
101
  return `Installing ${Object.entries(s.installing).map(([b, p]) => `${b} (${p})`).join(", ")}.`;
96
102
  if (!s.open)
@@ -115,7 +121,7 @@ const COMMANDS = {
115
121
  const records = await service.annotateRecords();
116
122
  if (!records || !records.length)
117
123
  return "(no records)";
118
- return records.map((r) => { const rect = r.rect ? ` rect=(${r.rect[0]},${r.rect[1]},${r.rect[2]},${r.rect[3]})` : ""; return `[${r.index}] ${r.selector}${rect}${r.note ? ` note="${r.note}"` : ""}`; }).join("\n");
124
+ return records.map((r) => { const rect = r.rect ? ` rect=(${r.rect[0]},${r.rect[1]},${r.rect[2]},${r.rect[3]})` : ""; const img = r.image ? " +img" : ""; const sent = r.sent ? " [sent]" : ""; return `[${r.index}] ${r.selector}${rect}${img}${sent}${r.note ? ` note="${r.note}"` : ""}`; }).join("\n");
119
125
  }
120
126
  catch {
121
127
  return "(no records)";
@@ -125,7 +131,12 @@ const COMMANDS = {
125
131
  const rec = (records || []).find((r) => r.index === a.id);
126
132
  if (!rec)
127
133
  return `(record #${a.id} not found)`;
128
- return `#${rec.index} ${rec.selector}\nrect: ${JSON.stringify(rec.rect)}\nnote: ${rec.note || "(none)"}`;
134
+ let img = "";
135
+ if (rec.image) {
136
+ const p = saveShotImage(log, rec.index, rec.image);
137
+ img = `\nimage: ${Math.round(rec.image.length / 1024)}KB base64` + (p ? ` (saved: ${p})` : "");
138
+ }
139
+ return `#${rec.index} ${rec.selector}\nrect: ${JSON.stringify(rec.rect)}${img}\nnote: ${rec.note || "(none)"}`;
129
140
  }
130
141
  catch {
131
142
  return "(no records)";
@@ -247,7 +258,9 @@ function splitCsvLine(line) {
247
258
  out.push(cur);
248
259
  return out;
249
260
  }
250
- export const opencodeBrowserTool = async ({ client, worktree }) => {
261
+ export const opencodeBrowserTool = async ({ client, worktree, directory, serverUrl }) => {
262
+ // 插件上下文(仅用于诊断:定位 session.list() 为空时是哪个实例/目录)
263
+ pluginCtx = { directory: directory || "", worktree: worktree || "", serverUrl: serverUrl ? String(serverUrl) : "" };
251
264
  registerLocale("en", en);
252
265
  registerLocale("zh", zh);
253
266
  loadConfig(worktree);
@@ -263,20 +276,34 @@ export const opencodeBrowserTool = async ({ client, worktree }) => {
263
276
  // 多用户配置:默认用当前激活配置的独立 WebView2 用户数据目录
264
277
  userDataDir: getProfileDir(getActiveProfile()),
265
278
  });
279
+ // 启动即后台下载 bt-shell(fire-and-forget:不阻塞启动,失败不抛出;状态见 getBinaryStatus)
280
+ startDownload();
266
281
  // 轮询批注发送队列(面板"发送全部" → 推送到对话)
267
- void startAnnotatePoller(client, log);
282
+ void startAnnotatePoller(client);
268
283
  return {
269
284
  event: async ({ event }) => {
270
- if (event.type === "session.deleted") {
271
- const sid = event.data?.sessionID;
272
- if (sid) {
285
+ // 缓存最近会话 id:这是投递批注最可靠的 sessionID 来源
286
+ if (event.type !== "session.deleted") {
287
+ sessionCache.updateFromEvent(event);
288
+ }
289
+ else {
290
+ const delId = extractSessionIDFromEvent(event);
291
+ if (delId) {
292
+ sessionCache.clearIf(delId);
273
293
  try {
274
- await service.closeSession({ _sessionId: sid });
294
+ await service.closeSession({ _sessionId: delId });
275
295
  }
276
296
  catch { }
277
297
  }
278
298
  }
279
299
  },
300
+ // 用户发消息 / 调工具时刷新当前会话 id(参考项目用 ctx.sessionID,此处为等价钩子来源)
301
+ "chat.message": async (input) => {
302
+ sessionCache.updateFromHookInput(input);
303
+ },
304
+ "tool.execute.before": async (input) => {
305
+ sessionCache.updateFromHookInput(input);
306
+ },
280
307
  tool: filterDisabled({
281
308
  bt_cli: tool({
282
309
  description: _t("tool.cli.desc") + "\n" + DESC_INDEX,
@@ -327,7 +354,8 @@ export const opencodeBrowserTool = async ({ client, worktree }) => {
327
354
  }
328
355
  }
329
356
  }
330
- // 透传会话 ID(会话隔离用)
357
+ // 透传会话 ID(会话隔离用),并刷新钩子缓存(兜底:即使钩子未触发也能拿到 sid)
358
+ sessionCache.updateFromHookInput(context);
331
359
  params._sessionId = context?.sessionID || "";
332
360
  try {
333
361
  return await def.run(params);
@@ -344,6 +372,7 @@ export const opencodeBrowserTool = async ({ client, worktree }) => {
344
372
  mode: tool.schema.enum(["simulate", "real"]).optional().describe(_t("tool.set_media_mode.arg.mode")),
345
373
  },
346
374
  async execute(a, context) {
375
+ sessionCache.updateFromHookInput(context);
347
376
  const r = await service.mediaMode({ ...a, _sessionId: context?.sessionID || "" });
348
377
  return `Media mode: ${r.mode}`;
349
378
  },
@@ -393,16 +422,49 @@ function filterDisabled(tools, disabled) {
393
422
  */
394
423
  let annotateTimer = null;
395
424
  let annotateClient = null;
396
- function startAnnotatePoller(client, log) {
425
+ /** 最近一次见到的会话 id 缓存(来自 event/chat.message/tool.execute.before 钩子) */
426
+ const sessionCache = createSessionIDCache();
427
+ /** 已记录过的 sid(避免重复刷屏) */
428
+ let lastLoggedSessionID = "";
429
+ /** 插件上下文(诊断用) */
430
+ let pluginCtx = { directory: "", worktree: "", serverUrl: "" };
431
+ /** 把截图 base64 落盘为临时 PNG,返回路径(失败返回 null);用于发送时保留图片与给出可读路径 */
432
+ function saveShotImage(log, index, b64) {
433
+ try {
434
+ const dir = resolve(getTmpDir());
435
+ mkdirSync(dir, { recursive: true });
436
+ const p = resolve(dir, `shot-${Date.now()}-${index}.png`);
437
+ writeFileSync(p, Buffer.from(b64, "base64"));
438
+ return p;
439
+ }
440
+ catch (e) {
441
+ log.error("save screenshot image failed", e);
442
+ return null;
443
+ }
444
+ }
445
+ function startAnnotatePoller(client) {
397
446
  // 更新 client 引用(插件重载后使用最新 client),但只启动一个轮询器
398
447
  annotateClient = client;
399
448
  if (annotateTimer)
400
449
  return;
401
450
  const POLL_MS = 2000;
451
+ let warnedNotRunning = false;
402
452
  const timer = setInterval(async () => {
403
- // 服务未启动/已关闭:跳过本次轮询(窗口打开后再恢复推送)
404
- if (!isRunning())
453
+ // 观测钩子缓存:首次学到 sid 时记一次(证明 sid 来源可用,与窗口是否打开无关)
454
+ const learned = sessionCache.get();
455
+ if (learned && learned !== lastLoggedSessionID) {
456
+ log.info(`[poller] hook-cache sid=${learned}`);
457
+ lastLoggedSessionID = learned;
458
+ }
459
+ // 服务未启动/已关闭:跳过本次轮询(窗口打开后再恢复推送);仅首次提示,避免刷屏
460
+ if (!isRunning()) {
461
+ if (!warnedNotRunning) {
462
+ log.info("[poller] shell not running; poll skipped (will resume after open_window/tool call)");
463
+ warnedNotRunning = true;
464
+ }
405
465
  return;
466
+ }
467
+ warnedNotRunning = false;
406
468
  const c = annotateClient;
407
469
  if (!c)
408
470
  return;
@@ -410,36 +472,70 @@ function startAnnotatePoller(client, log) {
410
472
  const r = await service.annotateConsumeSent();
411
473
  const records = r?.records || [];
412
474
  if (records.length === 0)
413
- return;
475
+ return; // 空结果不刷屏
476
+ const imgInfo = records
477
+ .filter((x) => x.type === "screenshot" && x.image)
478
+ .map((x) => `#${x.index}:${x.image.length}B`);
479
+ log.info(`[poller] consume-sent -> ${records.length} record(s) ids=[${records.map((x) => x.index).join(",")}] images=[${imgInfo.join(",")}]`);
414
480
  const lines = ["User annotated via panel:", ""];
415
- const parts = [];
416
481
  for (const item of records) {
417
- // 截图记录:附带图片 part(裸 base64),AI 可直接看图
418
- if (item.type === "screenshot" && item.image) {
419
- parts.push({ type: "file", mime: "image/png", data: item.image, url: "" });
420
- }
421
482
  const label = item.type === "screenshot"
422
483
  ? `[#${item.index}] 截图${item.url ? ` @ ${item.url}` : ""}`
423
484
  : `[#${item.index}] ${item.selector || "(no selector)"}${item.url ? ` @ ${item.url}` : ""}`;
424
485
  lines.push(`- ${label}${item.note ? `: ${item.note}` : ""}`);
486
+ // 截图:落盘保留并写入文本路径。与参考实现(opencode-playwright-tool)一致 ——
487
+ // 图片**不经 session.prompt**(服务端对 image/* part 返回 400),而是走
488
+ // 「工具结果附件」(bt_screenshot)或「读记录返回缓存路径」(read_record_content)。
489
+ if (item.type === "screenshot" && item.image) {
490
+ const savedPath = saveShotImage(log, item.index, item.image);
491
+ if (savedPath)
492
+ lines.push(` (image saved: ${savedPath})`);
493
+ }
425
494
  lines.push("");
426
495
  }
427
496
  const text = lines.join("\n");
428
- const bodyParts = [{ type: "text", text }];
429
- for (const p of parts)
430
- bodyParts.push(p);
431
- const sessions = await c.session.list();
432
- if (sessions?.data?.length) {
433
- await c.session.prompt({
434
- path: { id: sessions.data[0].id },
435
- body: { noReply: false, parts: bodyParts },
436
- });
497
+ // 取当前会话 id:优先用钩子缓存(参考项目 ctx.sessionID 的等价物),session.list() 仅兜底
498
+ let sid = sessionCache.get();
499
+ let source = "hook-cache";
500
+ let listLen = "-";
501
+ if (!sid) {
502
+ const sessions = await c.session.list();
503
+ listLen = Array.isArray(sessions?.data) ? sessions.data.length : sessions?.error ? "error" : "none";
504
+ log.info(`[poller] session.list raw=${JSON.stringify(sessions).slice(0, 400)}`);
505
+ sid = sessions?.data?.[0]?.id;
506
+ source = "client.session.list()[0]";
507
+ }
508
+ // 关键诊断:sid 来源/缓存值/list 长度/插件目录(定位"静默失败"断点)
509
+ log.info(`[poller] sid source=${source} cached=${sessionCache.get() || "(EMPTY)"} listLen=${listLen} ctx=${pluginCtx.directory || "(none)"} srv=${pluginCtx.serverUrl || "(none)"} sid=${sid ?? "(EMPTY)"}`);
510
+ if (!sid) {
511
+ const msg = "no session id (hook cache empty and session.list returned none)";
512
+ log.error(`[poller] ${msg}`, new Error(msg));
513
+ try {
514
+ await service.notify({ message: `发送失败: ${msg}`, type: "err" });
515
+ }
516
+ catch { }
517
+ return;
518
+ }
519
+ const send = (parts) => c.session.prompt({ path: { id: sid }, body: { noReply: false, parts } });
520
+ // 只发文本(参考实现同为纯文本;图片由工具附件/缓存路径交付,不在 prompt 里塞图片 part)
521
+ log.info(`[poller] prompt -> sid=${sid} parts=text-only textLen=${text.length}`);
522
+ const res = await send([{ type: "text", text }]);
523
+ const err = res?.error;
524
+ if (err) {
525
+ // 不再静默:写日志 + 页面通知(SDK 返回 {error} 不抛,必须显式检查)
526
+ log.error(`[poller] prompt FAILED sid=${sid}: ${JSON.stringify(err).slice(0, 300)}`, new Error("prompt error"));
527
+ try {
528
+ await service.notify({ message: `发送记录失败: ${JSON.stringify(err).slice(0, 180)}`, type: "err" });
529
+ }
530
+ catch { }
531
+ }
532
+ else {
533
+ log.info(`[poller] prompt OK sid=${sid} delivered ${records.length} record(s)`);
437
534
  }
438
535
  }
439
- catch {
440
- // 服务未就绪/已退出,停止轮询
441
- clearInterval(timer);
442
- annotateTimer = null;
536
+ catch (e) {
537
+ // 不终止轮询(此前 clearInterval 会导致后续发送永久"无反应")
538
+ log.error("annotate poller error", e);
443
539
  }
444
540
  }, POLL_MS);
445
541
  // 不阻塞进程退出
package/dist/logger.js ADDED
@@ -0,0 +1,6 @@
1
+ // 共享日志模块:全局单例 logger,避免各文件重复创建(与 opencode-ssh-tool 的 src/log.ts 同构)
2
+ // 落盘约定由 @xiaoqiong0v0/opencode-plugin-logger 决定:
3
+ // ~/.opencode/plugins-log/<YYYYMMDD>.log,行格式 `[时间] [级别] browser-tool <内容>`
4
+ // 需在 ~/.config/opencode/plugin-logger.jsonc 里 `enabled: true` 才会写文件(默认 false)
5
+ import createLogger from "@xiaoqiong0v0/opencode-plugin-logger";
6
+ export const log = createLogger("browser-tool");
@@ -0,0 +1,47 @@
1
+ // 会话 id 提取与缓存(纯逻辑,便于单测):投递批注时必须拿到"当前会话 id"。
2
+ // 可靠来源是插件钩子上下文(等价于参考项目 opencode-playwright-tool 的 ctx.sessionID),
3
+ // 而不是 client.session.list() —— 后者可能返回空/异常包络(见 docs/implementation.md)。
4
+ // - event: Event.properties.sessionID;
5
+ // session.created/updated/deleted 则挂在 properties.info.id
6
+ // - chat.message / tool.execute.before / shell.env / 工具 execute 的 context: 入参 sessionID
7
+ /** 从 opencode 插件 event 提取 sessionID(兼容 properties / data 两种包络) */
8
+ export function extractSessionIDFromEvent(ev) {
9
+ if (!ev || typeof ev !== "object")
10
+ return "";
11
+ const p = ev.properties ?? ev.data ?? {};
12
+ const sid = p.sessionID ?? p.info?.id;
13
+ return typeof sid === "string" ? sid : "";
14
+ }
15
+ /** 从 chat.message / tool.execute.before / 工具 context 等入参提取 sessionID */
16
+ export function extractSessionIDFromHookInput(input) {
17
+ const sid = input?.sessionID;
18
+ return typeof sid === "string" ? sid : "";
19
+ }
20
+ /** 当前会话 id 缓存:优先于 client.session.list(),避免 list() 为空导致投递静默失败 */
21
+ export function createSessionIDCache() {
22
+ let current = "";
23
+ return {
24
+ /** 从钩子入参刷新;返回本次提取到的 id(可能为 "" 表示未提供) */
25
+ updateFromHookInput(input) {
26
+ const sid = extractSessionIDFromHookInput(input);
27
+ if (sid)
28
+ current = sid;
29
+ return sid;
30
+ },
31
+ /** 从 event 刷新(不用于 session.deleted,删除时用 clearIf) */
32
+ updateFromEvent(ev) {
33
+ const sid = extractSessionIDFromEvent(ev);
34
+ if (sid)
35
+ current = sid;
36
+ return sid;
37
+ },
38
+ get() {
39
+ return current;
40
+ },
41
+ /** 会话被删除时清除缓存(仅当匹配) */
42
+ clearIf(id) {
43
+ if (id && current === id)
44
+ current = "";
45
+ },
46
+ };
47
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xiaoqiong0v0/opencode-browser-tool",
3
- "version": "1.2.0",
3
+ "version": "1.3.0",
4
4
  "description": "opencode 浏览器工具插件:WebView2 外壳渲染 + 零注入视觉元素选取面板",
5
5
  "main": "dist/index.js",
6
6
  "scripts": {
package/dist/devices.js DELETED
@@ -1,26 +0,0 @@
1
- /**
2
- * 内置设备预设表(名称 → User-Agent)
3
- * 空字符串表示使用浏览器默认 UA(桌面类)
4
- * 数据为静态硬编码,不依赖 Playwright 运行时
5
- */
6
- export const DEVICES = {
7
- // 桌面(默认 UA)
8
- "Desktop Chrome": "",
9
- "Desktop Edge": "",
10
- "Desktop Firefox": "",
11
- "Desktop Safari": "",
12
- // iPhone
13
- "iPhone 15 Pro": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1",
14
- "iPhone 14": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.4 Mobile/15E148 Safari/604.1",
15
- "iPhone 13": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.5 Mobile/15E148 Safari/604.1",
16
- "iPhone 12": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1 Mobile/15E148 Safari/604.1",
17
- "iPhone SE (3rd gen)": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.5 Mobile/15E148 Safari/604.1",
18
- // iPad
19
- "iPad Pro 11": "Mozilla/5.0 (iPad; CPU OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1",
20
- "iPad (10th gen)": "Mozilla/5.0 (iPad; CPU OS 16_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.4 Mobile/15E148 Safari/604.1",
21
- "iPad Mini (6th gen)": "Mozilla/5.0 (iPad; CPU OS 15_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.5 Mobile/15E148 Safari/604.1",
22
- // Android
23
- "Pixel 7": "Mozilla/5.0 (Linux; Android 13; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Mobile Safari/537.36",
24
- "Pixel 6": "Mozilla/5.0 (Linux; Android 13; Pixel 6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Mobile Safari/537.36",
25
- "Samsung Galaxy S23": "Mozilla/5.0 (Linux; Android 13; SM-S911B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Mobile Safari/537.36",
26
- };