@xiaoqiong0v0/opencode-browser-tool 1.11.0 → 1.12.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
@@ -1,6 +1,6 @@
1
1
  # opencode-browser-tool
2
2
 
3
- opencode 插件:Tauri 多 Webview 浏览器外壳 + 零注入视觉元素选取面板。对外只注册 **2 个工具**:`bt_cli`(命令行式分发器,内含 **47 条**浏览器自动化命令)与 `bt_set_media_mode`(摄像头/麦克风真伪切换),见下文「工具」。
3
+ opencode 插件:Tauri 多 Webview 浏览器外壳 + 零注入视觉元素选取面板。对外只注册 **2 个工具**:`bt_cli`(命令行式分发器,内含 **50 条**浏览器自动化命令)与 `bt_set_media_mode`(摄像头/麦克风真伪切换),见下文「工具」。
4
4
 
5
5
  > 架构演进:V1-V3 使用 Playwright 注入式面板(存在弹框类元素无法批注的问题);V4 改为 Rust Shell + 原始调试协议;V5 迁移到 Tauri 2 多 Webview(跨平台)。
6
6
 
@@ -20,7 +20,7 @@ opencode 插件:Tauri 多 Webview 浏览器外壳 + 零注入视觉元素选
20
20
  `%USERPROFILE%\.opencode\plugins-data\opencode-browser-tool\<triple>\bt-shell.exe`),并**就地覆盖**同一路径
21
21
  (不按插件版本建目录);同目录另有 `bt-shell.version.json` 记录该可执行文件的来源
22
22
  (`tag` / `pluginVersion` / `asset` / `sha256` / `size` / `downloadedAt` / `sourceUrl`,`src/binary.ts:69-79`)。下载用 Release 的 `SHA256SUMS` 做
23
- sha256 校验(**幂等**:sha 与当前 release 期望值一致即跳过;**原子**替换;跨进程 `.lock`;Linux 下载后 `chmod 755`)。下载在插件初始化时即发起、后台进行、**不阻塞 opencode 启动**(`src/index.ts:342-343`);未就绪时工具调用会给出
23
+ sha256 校验(**幂等**:sha 与当前 release 期望值一致即跳过;**原子**替换;跨进程 `.lock`;Linux 下载后 `chmod 755`)。下载在插件初始化时即发起、后台进行、**不阻塞 opencode 启动**(`src/index.ts:760`);未就绪时工具调用会给出
24
24
  明确提示(下载进度 / 失败原因),不会假装成功。
25
25
 
26
26
  平台支持与系统依赖:
@@ -54,14 +54,22 @@ sha256 校验(**幂等**:sha 与当前 release 期望值一致即跳过;**
54
54
 
55
55
  项目级配置放 `<项目根目录>/.opencode/browser-tool.jsonc`,会覆盖全局。
56
56
 
57
- 生成的配置还支持(可选项,见 `src/config/index.ts:27-35,246-274`):
57
+ 生成的配置还支持(可选项,见 `src/config/index.ts:54-72,247-275`):
58
58
 
59
59
  - `browsersPath` — 浏览器缓存目录(等价 `BT_BROWSERS_PATH`)
60
60
  - `cacheDir` — 插件缓存根(默认 `~/.opencode/plugins-cache/opencode-browser-tool`,下设 `sessions/<profile>/<sid>`、`user-data/<profile>`、`exports`、`tmp`)
61
61
  - `nodePath` — Node.js 可执行路径(等价 `BT_NODE_PATH`)
62
- - `disabledTools` — **按已注册工具名**禁用工具。bt_cli 合并后注册的工具名只有 `bt_cli` 与 `bt_set_media_mode`(`src/index.ts:376-463`、过滤逻辑 `src/index.ts:493-500`),因此只有写这两个名字才生效;旧的 47 个分工具名(`close`、`custom_user_agent`…)或不带前缀的命令名**不再有效、会被静默忽略**(自动生成配置的注释示例同样偏旧,以本节为准)。禁用 `bt_cli` 等于没有命令入口,慎用。
62
+ - `disabledTools` — **按已注册工具名**禁用工具。bt_cli 合并后注册的工具名只有 `bt_cli` 与 `bt_set_media_mode`(`src/index.ts:806-905`、过滤逻辑 `src/index.ts:935-942`),因此只有写这两个名字才生效;旧的按命令拆分的工具名(`close`、`custom_user_agent`…)或不带前缀的命令名**不再有效、会被静默忽略**(自动生成配置的注释示例同样偏旧,以本节为准)。禁用 `bt_cli` 等于没有命令入口,慎用。
63
+ - `consoleBufferBytes` / `networkBufferBytes` — console / network 日志流的**字节预算**,默认各 **8 MiB**(8 388 608,跨 tab 全局共享);超出按最旧逐出并计入 `dropped`(等价 `BT_CONSOLE_BUFFER_MB` / `BT_NETWORK_BUFFER_MB`,env 以 **MB** 计)
64
+ - `networkBurstWindowMs` — network 聚合窗口,默认 **2000 ms**:仅当与上一条同 key 且间隔 ≤ 该值才累加 `count`(等价 `BT_NETWORK_BURST_MS`)
65
+ - `consoleInject` — Linux console 注入猴补开关,默认 **Linux `true` / Windows `false`**;Windows 走 CDP 不需要注入(等价 `BT_CONSOLE_INJECT`)
66
+ - `webview2Args` — **仅 Windows** 的 WebView2 额外启动参数(透传为 `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS`,与进程已有值合并、已包含则不重复),默认四个参数(`src/config/index.ts:40-48`):
67
+ - `--disable-features=CalculateNativeWinOcclusion`(关窗口遮挡计算)
68
+ - `--disable-background-timer-throttling` / `--disable-renderer-backgrounding` / `--disable-backgrounding-occluded-windows`(窗口被遮挡/后台时不节流、不挂起 renderer,否则 `ExecuteScript` 可能永不回调 → 同步等 UI 的调用永久阻塞)
63
69
 
64
- 环境变量(优先级最高,`src/config/index.ts:223-240`):
70
+ 动机是 **RDP 断连/切后台时 DWM 合成暂停**会让依赖 GPU 合成的 WebView2 卡住 UI 线程。**默认保留 GPU 合成**(不加 `--disable-gpu-compositing`);确实需要 CPU 合成排障时自行追加。写**空串**表示**不加任何参数**(`src/config/index.ts:368-378`)。等价 env `BT_WEBVIEW2_ARGS`(优先级更高)
71
+
72
+ 环境变量(优先级最高,`src/config/index.ts:293-319`):
65
73
  - `BT_LANG` — 同时设置 panelLang 和 toolLang
66
74
  - `BT_PANEL_LANG` / `BT_TOOL_LANG` — 分别只设置面板 UI 语言 / 工具描述语言
67
75
  - `BT_BROWSERS_PATH` — 浏览器缓存目录
@@ -74,12 +82,18 @@ sha256 校验(**幂等**:sha 与当前 release 期望值一致即跳过;**
74
82
  - `BT_SHELL_DOWNLOAD_BASE` — 覆盖下载根(默认 GitHub Release `https://github.com/xiaoqiong0v0/opencode-browser-tool/releases/download`),可指向镜像/自建
75
83
  - `BT_SHELL_VERSION` — 显式指定**二进制发布版本**(形如 `1.2.0`,即 `x.Y.0` 的 Release;**原样使用、不做归 0 推导**;不设时由插件版本自动推导)
76
84
  - `BT_SHELL_NOTIFY_URL` — 插件通知地址(**推送式投递**;一般由插件自动通过 `--notify-url` / `/api/notify-url` 设置,仅在手动启动 shell 时需自行指定)
85
+ - `BT_CONSOLE_BUFFER_MB` / `BT_NETWORK_BUFFER_MB` — console / network 日志流字节预算(**MB**,默认各 8;对应配置项 `consoleBufferBytes` / `networkBufferBytes`)
86
+ - `BT_NETWORK_BURST_MS` — network 聚合窗口(ms,默认 2000;对应配置项 `networkBurstWindowMs`)
87
+ - `BT_CONSOLE_INJECT` — Linux console 注入开关(`1`/`0`;默认 Linux `1`、其它平台 `0`;对应配置项 `consoleInject`)
88
+ - `BT_WEBVIEW2_ARGS` — **仅 Windows**:WebView2 额外启动参数(覆盖配置项 `webview2Args`;**空串=不加任何参数**;默认见上方 `webview2Args` 的四个参数;与进程已有 `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS` 合并)
77
89
 
78
90
  > **附着模式 vs 启动模式**:设置了 `BT_SHELL_URL`(优先)或 `BT_SHELL_PORT` 时进入附着模式——插件**不 spawn** 任何进程,直接连接该地址的外部 shell;两者都未设置时按启动模式 spawn 本地二进制(`BT_SHELL_PATH` 可覆盖查找路径)。附着模式下 `close` 命令只断开本地连接(**不关闭外部窗口、不结束外部进程**;进程不归插件管理)。
79
91
  >
80
92
  > **附着模式必须设置 `BT_SHELL_TOKEN`**:外部 shell 启动时的令牌必须与插件侧环境变量一致(见下方示例),否则插件启动即报 `client.attach_need_token`,不会去连一个注定 401 的端点。令牌未设置时 shell 会随机生成,因此手动启动的 shell 务必显式传 `--token`(或用同值环境变量)。
93
+ >
94
+ > **日志流配置只在启动模式生效**:`consoleBufferBytes` / `networkBufferBytes` / `networkBurstWindowMs` / `consoleInject` 由插件 spawn shell 时以 env 下发;**附着模式下插件只读不传**(外部进程不归插件管),要改缓冲/窗口/注入需在**启动外部 shell 的环境里**自行设置同名 `BT_*` 变量。`webview2Args` 同理:它是 spawn 时塞进子进程环境的 `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS`,附着模式下对已存在的外部进程无效(Windows 下需在启动外部 shell 的环境里设该变量)。
81
95
 
82
- **本地 API 语义**:`/api/*` 只监听 `127.0.0.1`,且只服务插件进程——所有请求必须带 `x-bt-token`(服务端常量时间比较)。**`Origin` 规则(1.11.0 起)**:只有**面板自身 origin 白名单**(`http://tauri.localhost` / `https://tauri.localhost` / `tauri://localhost`,精确匹配、不带端口/子域)放行;**其它任何 `Origin`(`null`、外部站点、子域变体、带端口)仍一律 403**,插件 Node `fetch` 不带 `Origin` 不受影响。**CORS 只对面板 origin 最小恢复**:预检 `OPTIONS` 回 204 + 精确回显该 origin 的 `Access-Control-Allow-Origin`(允许 `POST, OPTIONS` 与 `content-type, x-bt-token` 头),实际响应(含 401)也带精确 ACAO + `Vary: Origin`,**永不通配 `*`**;非面板来源的响应不带任何 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` 调用,其 origin 也在白名单内(**令牌仍是最终闸门**);页面注入脚本无法持有令牌,故服务端仅对**精确路径 `/api/page-event`** 豁免 `Origin` 与令牌校验(不做前缀匹配),该端点只更新标签 url/title/icon、不执行任何操作。
96
+ **本地 API 语义**:`/api/*` 只监听 `127.0.0.1`,且只服务插件进程——所有请求必须带 `x-bt-token`(服务端常量时间比较)。**`Origin` 规则(1.11.0 起)**:只有**面板自身 origin 白名单**(`http://tauri.localhost` / `https://tauri.localhost` / `tauri://localhost`,精确匹配、不带端口/子域)放行;**其它任何 `Origin`(`null`、外部站点、子域变体、带端口)仍一律 403**,插件 Node `fetch` 不带 `Origin` 不受影响。**CORS 只对面板 origin 最小恢复**:预检 `OPTIONS` 回 204 + 精确回显该 origin 的 `Access-Control-Allow-Origin`(允许 `POST, OPTIONS` 与 `content-type, x-bt-token` 头),实际响应(含 401)也带精确 ACAO + `Vary: Origin`,**永不通配 `*`**;非面板来源的响应不带任何 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` 调用,其 origin 也在白名单内(**令牌仍是最终闸门**);页面注入脚本无法持有令牌,故服务端对**两个精确路径**豁免 `Origin` 与令牌校验(精确匹配、不做前缀匹配):**`/api/page-event`** 与 **`/api/console-log`**(1.12.0 增)。两者的共同限制:**只写缓冲、不执行任何内容**(前者只更新标签 url/title/icon;后者只把页面 console 条目写进该标签的日志缓冲,body ≤ 256 KiB、超 200 条/秒丢弃并计数),**均无敏感回读**;`OPTIONS` 对它们同样不豁免(非面板 origin 仍 405)。残余风险:同机/页面侧可伪造这两个端点的写入(地址栏/标题错乱、日志缓冲被灌入伪造条目),但拿不到任何令牌或页面数据;若将来给它们加敏感字段或副作用,**必须重新评估豁免**。
83
97
 
84
98
  **WSL / Linux 附着示例**(shell 跑在 WSL,插件跑在 Windows 宿主):
85
99
 
@@ -113,7 +127,7 @@ opencode(Bun)
113
127
 
114
128
  - 浏览器渲染引擎(WebView2 / WebKitGTK / WKWebView,随平台)直接绘制到插件窗口
115
129
  - 页面零注入残留脚本,弹框类元素可正常批注
116
- - 所有工具调用通过 `POST http://127.0.0.1:PORT/api/{command}` 通信,并统一带鉴权头 `x-bt-token`(**除面板 origin 白名单外拒绝任何带 `Origin` 的请求**;面板 origin 走最小 CORS 预检,见上。唯一鉴权豁免是页面事件桥 `/api/page-event`)
130
+ - 所有工具调用通过 `POST http://127.0.0.1:PORT/api/{command}` 通信,并统一带鉴权头 `x-bt-token`(**除面板 origin 白名单外拒绝任何带 `Origin` 的请求**;面板 origin 走最小 CORS 预检,见上。鉴权豁免只有**两个精确路径**:页面事件桥 `/api/page-event` 与 console 回传 `/api/console-log`,均只写缓冲、无敏感回读)
117
131
  - 除 spawn 本地 shell 外,也可用 `BT_SHELL_URL` / `BT_SHELL_PORT` **附着到已运行的 shell**(不 spawn,适用于 shell 跑在 WSL/Linux、插件跑在 Windows;**必须同时设置 `BT_SHELL_TOKEN`**,外部 shell 用同一令牌启动)
118
132
  - 跨平台代码:Windows / Linux / macOS;**预编译二进制只发 Windows x64 与 Linux x64**,macOS 需自行构建(`cargo build --release`)且功能不完整:截图待实现(`rust/src/control/screenshot.rs:4`)、DevTools 无法真正关闭(`close_supported = cfg!(target_os = "linux")`,`rust/src/service.rs:1063`)、自定义 UA 未实现
119
133
  - 真多标签:每标签独立 page Webview,切换不重载;`target=_blank` / `window.open` 链接通过 WebView2 原生事件拦截并打开为新标签。**关闭标签会释放该标签的页面实例**(预创建池的 3 个 webview 保留复用,池外动态创建的实例直接销毁),反复开关标签不会累积页面进程
@@ -123,7 +137,7 @@ opencode(Bun)
123
137
 
124
138
  ## 工具
125
139
 
126
- 插件**只注册 2 个工具**(`src/index.ts:376-463`):
140
+ 插件**只注册 2 个工具**(`src/index.ts:806-905`):
127
141
 
128
142
  | 工具 | 参数 | 说明 |
129
143
  |------|------|------|
@@ -137,10 +151,11 @@ bt_cli({ args: "<command> [--flag value ...]" })
137
151
  ```
138
152
 
139
153
  - **命令名不带 `bt_` 前缀**:写 `click`、`navigate`、`list_tabs`,**不是** `bt_click` / `bt_navigate` / `bt_list_tabs`(旧文档里的 `bt_*` 名称既不是工具名也不是命令名)
140
- - **分词**:按 shell 风格切分(`string-argv` 0.3.2,`src/index.ts:3` 引入、`:388-390` 使用),含空格的值用引号包裹,如 `fill --selector #q --value "hello world"`;**只按引号配对切分、不处理反斜杠转义**——值里要出现引号就改用**另一种引号**包外层(如 `get_visible_text --selector "[title='a b']"`),写成 `--value "a\"b"` 会把 `\` 原样带进值里
141
- - **flag 解析**:第一个 token 为命令名,其余交给 `node:util.parseArgs`(`src/index.ts:285-291`);**未知 flag 直接报错并回显该命令用法**(输出可自愈,不必先调 help)
142
- - **敏感值 `@file:`**:值写成 `@file:<路径>` 时由插件读取文件内容作为实际值,**内容不进模型上下文**(`src/index.ts:404-435`)。只允许读插件临时目录(全局 tmp 或本会话 tmp)内的文件,其余路径一律拒绝;`lookup` 生成的密码临时文件即用于 `fill --value @file:...`,位于全局 tmp 的用完即删
143
- - 会话归属由插件自动透传(每会话独立浏览器实例,见「多会话」),`args` 里**不需要**也**不支持**传会话 id
154
+ - **分词**:按 shell 风格切分(`string-argv` 0.3.2,`src/index.ts:3` 引入、`:819` 使用),含空格的值用引号包裹,如 `fill --selector #q --value "hello world"`;**只按引号配对切分、不处理反斜杠转义**——值里要出现引号就改用**另一种引号**包外层(如 `get_visible_text --selector "[title='a b']"`),写成 `--value "a\"b"` 会把 `\` 原样带进值里
155
+ - **flag 解析**:第一个 token 为命令名,其余交给 `node:util.parseArgs`(`src/index.ts:683-702`);**未知 flag 直接报错并回显该命令用法**(输出可自愈,不必先调 help)
156
+ - **敏感值 `@file:`**:值写成 `@file:<路径>` 时由插件读取文件内容作为实际值,**内容不进模型上下文**。flag 值上的 `@file:` 只允许读插件临时目录(全局 tmp 或本会话 tmp)内的文件,其余路径一律拒绝;`lookup` 生成的密码临时文件即用于 `fill --value @file:...`,位于全局 tmp 的用完即删。**`evaluate` 的位置参数项**额外允许读**工作区目录**内的脚本文件(见下方「evaluate:多脚本顺序执行」);**`type --text @file:`** 与 `evaluate` 同口径(工作区目录 + 插件 tmp,且**不删除**源文件,便于反复输入同一段文本)
157
+ - **全局 flag `--private-session`**(任何命令都可带,`src/index.ts:683-702,839-846`):用**调用者自己的 sid** 建私有浏览器实例,不与根会话共用;并且对**同一子会话粘住**——首次用过之后,后续不带该 flag 也继续私有(根会话带它等价于自身)。典型场景:子代理需要**独立的浏览器环境做隔离测试**(自己的 cookie/登录态与窗口,不污染主会话)。根会话自己带它等价于自身(合法但无实际差别)。注意它紧跟某个 string flag 时会被当成该 flag 的值(`parseArgs` 行为),要写就写在命令名之后或命令末尾
158
+ - **会话归属由插件自动透传**(见「多会话」):实例按会话隔离,但 **task 子代理会话默认归并到根会话**——沿 `Session.parentID` 回溯到最顶层,用**根 sid** 作路由键,于是主会话与所有子会话共用同一 bt-shell 实例、同一数据目录 `sessions/<profile>/<根 sid>/`,窗口标题取根会话标题。`args` 里**不需要**也**不支持**传会话 id
144
159
 
145
160
  示例:
146
161
 
@@ -152,15 +167,64 @@ bt_cli({ args: "fill --selector #q --value \"hello world\"" })
152
167
  bt_cli({ args: "screenshot --selector .chart" })
153
168
  ```
154
169
 
155
- ### `--timeout`(下表标 ⏱ 的 17 条命令支持)
170
+ ### `--timeout`(下表标 ⏱ 的 18 条命令支持)
156
171
 
157
172
  - 单位**毫秒**,`--timeout 800` 可让卡住的操作约 0.8s 返回(快失败);**未列出的命令不接受该 flag**
158
- - 钳制区间 `[100, 60000]`:插件侧(`src/index.ts:80-81,96-98`)与 Rust 服务端(`rust/src/service.rs:96-97,104-116`)**同口径二次钳制**(直连 HTTP 也安全);非正整数直接报错拒绝;被钳制时输出如实标注 `(clamped to …ms)`,服务端响应体带 `timeoutMs` / `timeoutClamped`
173
+ - 钳制区间 `[100, 60000]`:插件侧(`src/index.ts:107-108,116-126`)与 Rust 服务端(`rust/src/service.rs:96-97,104-116`)**同口径二次钳制**(直连 HTTP 也安全);非正整数直接报错拒绝;被钳制时输出如实标注 `(clamped to …ms)`,服务端响应体带 `timeoutMs` / `timeoutClamped`
159
174
  - **未传时走各命令自己的默认,并非统一 15s**:eval / CDP / 截图 / `wait_for_selector` 默认 **15s**(`rust/src/ui/mod.rs:35`、`rust/src/control/cdp.rs:27`、`rust/src/control/screenshot.rs:23`、`rust/src/service.rs:609`);点击类(click / hover / drag / press_key 等)的稳定等待默认 **700ms**(`rust/src/control/mouse.rs:19,177-178`);`fill` / `select` 的读回校验默认 **2500ms**(`rust/src/control/input.rs:343`)
160
175
 
161
- ### 命令参考(47 条)
176
+ ### `evaluate`:多脚本顺序执行(插件侧,零 Rust 改动)
177
+
178
+ 位置参数按**给定顺序**逐项执行,`@file:<路径>` 读文件内容作为脚本,其余参数当作内联 JS:
179
+
180
+ ```text
181
+ bt_cli({ args: "evaluate @file:scripts/hook.js @file:scripts/collect.js \"console.log(1)\"" })
182
+ bt_cli({ args: "evaluate \"1+1\"" }) # 单个内联脚本
183
+ bt_cli({ args: "evaluate --script \"1+1\"" }) # 单项旧写法(输出仍为裸结果 "2")
184
+ bt_cli({ args: "evaluate @file:a.js @file:bad.js --continue-on-error" })
185
+ ```
186
+
187
+ - **串行、按顺序**:前一项 `await` 结束后才发下一项,绝不并行
188
+ - **默认遇错即停**(`stop`);`--continue-on-error` 继续执行后续项(`continued`)
189
+ - **`--script` 只能单独用**:与位置参数同时给会报错(避免执行顺序歧义)
190
+ - **文件读取安全边界**:只允许读**工作区目录**(插件 `setAppDirectory` 记录的 opencode `directory`)与**插件 tmp**(全局 tmp / 本会话 tmp)内的文件;其余路径**直接拒绝且不读取**。相对路径相对**工作区目录**解析(不是插件 cwd),并做 `isInsideDir` containment 校验。单文件 ≤ **256 KiB**、合计 ≤ **1 MiB**,超限报错
191
+ - **文件项在执行前统一读入**:任一项路径越界 / 读取失败 / 超限 → 整次调用**不执行任何脚本**(不留半截副作用)
192
+
193
+ 输出(每条结果截断到 500 字符;失败信息经 `sanitizeForModel`,不含绝对路径):
194
+
195
+ ```text
196
+ evaluate: 3 item(s), 2 ok, 1 failed (stop)
197
+ [1] file scripts/hook.js ok 3ms → <result>
198
+ [2] text ok 0ms → <result>
199
+ [3] file scripts/bad.js FAILED 1ms → SyntaxError: ...
200
+ ```
201
+
202
+ 全部成功时首行是 `evaluate: N item(s), N ok`;`--continue-on-error` 时标注 `(continued)`。单项 `--script` 保持旧输出(结果 JSON + 可能的 timeout 提示)。
203
+
204
+ ### 持久注入规则(`inject`)
205
+
206
+ 把 JS 存成**规则**:文档加载完成时若当前 URL 命中,就自动执行(不必每次 `evaluate`)。
162
207
 
163
- > 唯一真源:`src/index.ts:101-268` 的 `COMMANDS`(本表与之逐条对应,条数、flag 名、可选性均以代码为准)。说明取自 `src/i18n/en.ts` 的 `cli.cmd.*`(`src/i18n/en.ts:24-70`,中文对照见 `src/i18n/zh.ts`)。参数列中**不带 `[]` 者为必填**;⏱ = 支持 `--timeout ms`。完整命令/参数/help 以 `bt_cli({ args: "help" })` 的实际输出为准。
208
+ ```text
209
+ bt_cli({ args: "inject add --match \"*ygpm.zhihjy.cn*\" --file scripts/hook.js --order 10" })
210
+ bt_cli({ args: "inject add --match \"re:^https://example\\.com/\" --text \"console.log(1)\" --disabled" })
211
+ bt_cli({ args: "inject list" })
212
+ bt_cli({ args: "inject test --url https://ygpm.zhihjy.cn/a" }) # 只算命中,不执行
213
+ bt_cli({ args: "inject disable --id r1" })
214
+ ```
215
+
216
+ - **存储**:`sessions/<profile>/<sid>/inject/rules.json`(随会话数据目录,**会话删除即清理**);写入用临时文件 + rename **原子替换**
217
+ - **匹配语法**:`--match` 传 glob(`*` 通配,如 `*host*`)或 `re:<正则>`(如 `re:^https://x\.com/`);多条命中按 `--order` **升序**执行(未给 `--order` 时由服务端取默认)
218
+ - **执行时机**:该标签文档加载完成(Windows `Page.loadEventFired`、Linux `WebKitWebView::load-changed` FINISHED)→ 取该标签当前 URL → 命中 enabled 规则 → 逐条**串行**执行 items(单条 15s 超时);失败**不阻塞页面加载**、不向页面抛异常,结果只写回规则的 `last`
219
+ - **失败自动禁用**:`last` 记录 `ok` / `failed` / `error`;同一规则连续失败 **3** 次(`failStreak >= 3`)自动置 `enabled=false`,`last.error` 保留原因(`inject list` 显示错误首行)
220
+ - **上限**:规则 ≤ **20** 条;单条 items 合计 ≤ **256 KiB**;全部 ≤ **1 MiB**。超限在插件侧直接拒绝,不把坏规则写进存储
221
+ - **`--file` 读取**:只允许**工作区目录**(插件记录的 opencode `directory`)与**插件 tmp**(全局 tmp / 本会话 tmp),与 `evaluate` 同一套 containment;单条 ≤ **256 KiB**。文件内容在插件侧转成 `{ kind:"text", code, name:"<basename>" }` 发送,**Rust 不接触路径**;`--text` 的 name 固定为 `text`
222
+ - **`inject list` 只给结构**:`id / order / enabled / match / items / last`(ok、failed + 最近错误首行),明细只显示每个 item 的 `name` + 字节数,**绝不回显脚本内容**
223
+ - **与 `evaluate` 的区别**:`evaluate` 是**一次性**在当前页面执行并返回结果;`inject` 是**持久规则**,命中 URL 后每次加载都执行,结果只写回规则(不回模型),需用 `inject list` 查看
224
+
225
+ ### 命令参考(50 条,与 `COMMANDS` 一致)
226
+
227
+ > 唯一真源:`src/index.ts:435-658` 的 `COMMANDS`(本表与之逐条对应,条数、flag 名、可选性均以代码为准)。说明取自 `src/i18n/en.ts` 的 `cli.cmd.*`(`src/i18n/en.ts:49-98`,中文对照见 `src/i18n/zh.ts`)。参数列中**不带 `[]` 者为必填**;⏱ = 支持 `--timeout ms`。完整命令/参数/help 以 `bt_cli({ args: "help" })` 的实际输出为准。
164
228
 
165
229
  | 命令 | 参数(usage 原文) | 说明 |
166
230
  |------|------|------|
@@ -172,12 +236,15 @@ bt_cli({ args: "screenshot --selector .chart" })
172
236
  | `hover` ⏱ | `--selector` 必填 | 悬停到元素 |
173
237
  | `drag` ⏱ | `--sourceSelector --targetSelector` 必填 | 拖拽元素到目标 |
174
238
  | `press_key` ⏱ | `--key` 必填,`[--selector]` | 按下键盘按键;`--selector` 指定先聚焦的元素 |
239
+ | `type` ⏱ | `--text <文本\|@file:<路径>>` 必填,`[--selector] [--enter]` | **向当前焦点插入文本(不清空已有内容)**;`--selector` 先聚焦该元素,`--enter` 插入后回车;`--text` 支持 `@file:`(与 `evaluate` 同一套 containment)。xterm/终端/contenteditable 用它,表单替换用 `fill` |
175
240
  | `upload_file` ⏱ | `--selector --filePath` 必填 | 上传文件到输入框 |
176
241
  | `screenshot` ⏱ | `[--selector]` | 截取页面/元素截图(返回图片附件;带 `--selector` 先滚动到元素再截) |
177
- | `evaluate` ⏱ | `--script` 必填 | 在页面执行 JS,返回结果 |
242
+ | `evaluate` ⏱ | `[<js 文本>\|@file:<路径>]...`(或单个 `--script`) | 在页面执行 JS,返回结果。位置参数按**顺序**逐项执行(`@file:` 读脚本文件,其余为内联 JS);默认遇错即停,`--continue-on-error` 继续;`--script` 只能单独用(与位置参数同时给会报错) |
243
+ | `inject` | `[add --match <glob\|re:...> [--file <path>]... [--text <code>]... [--order N] [--disabled] \| list \| remove\|enable\|disable --id <id> \| clear \| test --url <url>]` | 持久注入规则:URL 命中时在文档加载完成后执行 items(新增/列表/删除/清空/启用/禁用/试算命中,详见「持久注入规则」一节) |
178
244
  | `get_visible_text` | `[--selector]` | 获取页面可见文本 |
179
245
  | `get_visible_html` | `[--selector --removeScripts --removeComments --maxLength]` | 获取页面 HTML 结构(`--removeScripts` / `--removeComments` 为布尔开关;`--maxLength` 超出时输出标注截断) |
180
- | `console_logs` | `[--type --search --limit --clear]` | 获取浏览器控制台日志(`--clear` 读取后清空) |
246
+ | `console_logs` | `[--type --group burst\|none --phase --search --limit --tab --include-internal --clear --no-dedupe]` | 获取缓冲的控制台日志:`--type` = `all`/`log`/`info`/`warn`/`error`/`debug`/`exceptions`;`--group burst`(默认)合并同内容连续重复,`none` 逐条;`--phase` 过滤 `load`/`interactive`/`action:<cmd>`;`--tab N` 按标签过滤,N 是 `list_tabs` 打印的**0 基索引**(`--tab 0` = 第一个标签;不是内部 id);`--include-internal` 显示浏览器内部日志(CDP `Log.entryAdded` 的 `source=violation\|deprecation`,如 `[DOM] Password field …`),默认不显示;`--limit` 默认 30;`--clear` 读取后清空;`--no-dedupe` 等价 `--group=none`。条目带 `(xN)`/`phase=`/`source=`(`cdp`/`injected`/`native`),异常附 stack 首行 |
247
+ | `network_logs` | `[--type --status 2xx\|3xx\|4xx\|5xx\|N --failed --search --group burst\|key\|none --phase --limit --tab --include-headers --reveal-secrets --clear --no-dedupe]` | 获取缓冲的网络请求:`--type` = `all`/`xhr`/`fetch`/`doc`/`script`/`image`/`font`/`other`;`--status` 支持区间写法或具体码;`--failed` 只看失败(`status=0` + `failure`);`--group burst`(默认,同 key 且间隔 ≤ `networkBurstWindowMs` 才合并)/`key`(忽略 phase 与间隔)/`none`;`--tab N` 同 `console_logs`(`list_tabs` 的 0 基索引);`--include-headers` 附加 headers(默认 `Authorization`/`Cookie`/`Set-Cookie` → `<redacted>`);`--reveal-secrets` 显示原值(**必须配合 `--include-headers`**,单独使用会明确报错;**风险见下**);`--clear` 读取后清空;`--no-dedupe` 等价 `--group=none` |
181
248
  | `go_back` | 无 | 浏览器后退,返回当前 URL |
182
249
  | `go_forward` | 无 | 浏览器前进,返回当前 URL |
183
250
  | `resize` | `--width --height` 必填 | 调整页面内容区尺寸(视口,非 OS 窗口;窗口高 = 内容高 + 工具栏 72px;下限 360×360,低于下限被钳制并标 `clamped`) |
@@ -201,10 +268,10 @@ bt_cli({ args: "screenshot --selector .chart" })
201
268
  | `scroll_to_element` ⏱ | `--selector` 必填 | 滚动到元素可见;未到达/未稳定不吞错,输出带 `reached`/`stable`/`waitedMs` |
202
269
  | `get_dropdown_options` ⏱ | `--selector` 必填 | 列出下拉框选项(当前选中项标 `*`) |
203
270
  | `custom_user_agent` | `--userAgent` 必填 | 设置自定义 User-Agent(Windows/Linux 支持;macOS 未实现) |
204
- | `expect_response` | `--url` 必填 | 记录期望匹配的响应模式,清空响应历史后重新捕获 |
271
+ | `expect_response` | `--url` 必填 | 记录期望匹配的响应模式与起点(**不清空** `network_logs` 历史;`assert_response` 只匹配起点之后的请求) |
205
272
  | `assert_response` | `--id` 必填 | 断言是否存在匹配的响应(返回 `url` + `status` 码) |
206
- | `get_accessibility_tree` ⏱ | `[--selector --maxDepth]` | 获取可访问性树(role/name/value 嵌套)。`--maxDepth` 缺省 8;服务端硬上限 **depth 64 / 节点 5000**,超出静默截断并记日志(`rust/src/control/accessibility.rs:355,359,551`) |
207
- | `list_records` | 无 | 列出面板批注/截图记录(索引/选择器/rect/说明;截图带 `+img`,已发送带 `[sent]`)。记录上限 **200** 条,超出丢最旧(`rust/src/ui/annotate.rs:395,403-406`) |
273
+ | `get_accessibility_tree` ⏱ | `[--selector --maxDepth]` | 获取可访问性树(role/name/value 嵌套)。`--maxDepth` 缺省 8;服务端硬上限 **depth 64 / 节点 5000**,超出静默截断并记日志(`rust/src/control/accessibility.rs:362,366,572`) |
274
+ | `list_records` | 无 | 列出面板批注/截图记录(索引/选择器/rect/说明;截图带 `+img`,已发送带 `[sent]`)。记录上限 **200** 条,超出丢最旧(`rust/src/ui/annotate.rs:461,467-475`) |
208
275
  | `read_record_content` | `--id` 必填 | 按 id 读取单条记录详情(截图落盘为临时 PNG 并给出大小与路径) |
209
276
  | `fake_audio` | `--kind` 必填,`[--data --freq --durMs --notes --digits --loop]` | 向 fake 麦克风注入音频(`kind`:tone/seq/dtmf/noise/audio/ambient/stop) |
210
277
  | `fake_video` | `--kind` 必填,`[--data --url --loop]` | 向 fake 摄像头注入画面(`kind`:image/video/auto/stop) |
@@ -212,6 +279,34 @@ bt_cli({ args: "screenshot --selector .chart" })
212
279
  | `exports` | 无 | 显示导出目录与 Edge/Chrome 密码/书签导出指引 |
213
280
  | `lookup` | `--csv <path> --url <site>` 必填 | 从密码 CSV 按站点匹配并返回 `@file:` 临时文件路径(密码不进上下文,用完即删) |
214
281
 
282
+ ### `fill` vs `type` vs `press_key`(三种输入方式别混用)
283
+
284
+ | 命令 | 语义 | 典型场景 |
285
+ |---|---|---|
286
+ | `fill --selector --value` | **替换**:先聚焦 → 全选 → 插入 → 读回校验 | 普通表单输入框(`input`/`textarea`):要把原值整段换成新值 |
287
+ | `type --text [--selector] [--enter]` | **插入**:不选中、不清空,直接插到光标处(可选先聚焦、可选回车) | xterm/终端、`contenteditable` 富文本、需要逐段追加或在已有内容后继续输入 |
288
+ | `press_key --key [--selector]` | **单个按键**(含 Enter/Tab/方向键/Delete/F1-F12) | 触发快捷键、提交、删一个字符、方向键选择下拉项 |
289
+
290
+ - **为什么要有 `type`**:`fill` 是替换语义 + 读回校验,在 xterm 里会把终端已有内容清掉、且读不到 `input.value`;`press_key` 一次只能一个键,多字符文本要自己拼接。`type` 走同一条可信注入通道(Windows `Input.insertText`、Linux GDK 逐字符),一次插入整段文本,**不需要用 `evaluate` 伪造 `InputEvent`/`KeyboardEvent`**(伪造事件 `isTrusted=false`,不少终端/富文本组件不认)。
291
+ - **组合用法**:先 `type --text "ls" --enter`(终端里执行命令);富文本追加后如未触发组件自身的保存逻辑,再配合 `press_key --key Tab` 或在表单场景改用 `fill`。
292
+
293
+ ### 日志流能力矩阵(1.12.0)
294
+
295
+ | 能力 | Windows(WebView2 + CDP) | Linux(WebKitGTK) |
296
+ |---|---|---|
297
+ | console 采集 | `Runtime.enable` + `Log.enable`(`consoleAPICalled` / `entryAdded` / `exceptionThrown`) | 页面注入(`console.*` + `onerror` + `unhandledrejection` + 1s 重挂检测 + 同源 iframe 汇总,`sendBeacon` 批量回传);开关 `consoleInject` |
298
+ | console `source` | `cdp` / `native`(浏览器自身日志) | `injected` |
299
+ | network 采集 | `Network.enable`(`requestWillBeSent` / `responseReceived` / `loadingFailed` / `loadingFinished`) | WebKitGTK `resource-load-started` + `notify::response`(补 method/mime/耗时/failed) |
300
+ | `initiator` | `<type> <scriptUrl>:<line>`,无则 `other` | `subresource` / `document`(**无脚本行号**) |
301
+ | `phase` | 主帧 `Page.frameNavigated` / `Page.loadEventFired` + 动作窗口(子帧导航不置 `load`) | `load-changed` + 动作窗口 |
302
+ | 失败请求 | `status=0` + `failure`(如 `net::ERR_ABORTED`) | 同样 `status=0` + `failure`(字段来自 WebKitGTK 事件) |
303
+
304
+ - **动作归因(两平台)**:工具命令 `click` / `fill` / `select` / `press_key` / `navigate` 等执行期间开窗、结束后保留 **3s 宽限**(硬上限 60s;并发命令取最新,窗口不叠加),窗口内条目记 `phase=action:<cmd>`。
305
+ - **跨导航保留**:日志缓冲在 shell 侧、按标签归属,导航不清空;关闭标签释放该标签记录,关闭会话释放全部。
306
+ - **默认预算 8 MiB**:console / network 各自独立预算,且**跨 tab 全局共享**(逐出全局最旧,不是每 tab 各 8 MiB);超限丢最旧并累加 `dropped`(输出末尾标注)。
307
+
308
+ > ⚠ **`--reveal-secrets` 风险**:默认对 `Authorization` / `Cookie` / `Set-Cookie` 做 `<redacted>` 脱敏;`--reveal-secrets` 会把这些头**原样返回给模型并进入对话上下文**(可能含会话令牌/密码)。仅在排障必要时临时使用,用完及时收尾;不要把输出粘到外部系统。
309
+
215
310
  ### 元素截图行为(v1.7.0 起统一)
216
311
 
217
312
  `screenshot --selector <css>` 固定流程:
@@ -262,7 +357,7 @@ bt_cli({ args: "screenshot --selector .chart" })
262
357
 
263
358
  - **批注模式** — 悬停高亮元素(覆盖层自绘),点击元素弹出输入框填写说明;引擎层拦截,弹框/下拉类元素不失焦
264
359
  - **截图模式** — 点击立即截全屏;也可进入截图模式后拖动框选区域(选区可拖拽手柄调整大小),保存时可按需裁剪(遮罩式选区,默认整图,双击还原)
265
- - **记录列表** — 面板「AI 功能」区:批注/截图记录卡片(截图带缩略图),显示所属标签 URL 与说明。**记录上限 200 条**,超出丢最旧(`rust/src/ui/annotate.rs:395,403-406`)
360
+ - **记录列表** — 面板「AI 功能」区:批注/截图记录卡片(截图带缩略图),显示所属标签 URL 与说明。**记录上限 200 条**,超出丢最旧(`rust/src/ui/annotate.rs:461,467-475`)
266
361
  - **发送** — 面板底部「发送」按钮:所有记录(批注文字 + 截图图片)推送到 opencode 对话;发送后**面板列表清空**(与旧 Playwright 工具一致,仅列表为空),但**记录本身保留**并标记 `[sent]`(`list_records` 仍可读取,截图也可通过 `read_record_content` 取到)。投递为**推送式**:shell 发送后主动通知插件(`POST /notify/<sid>`,按会话归属),插件收到即拉取并推送到对话(无轮询、无 2s 延迟)。**待发送队列上限 500 条**,超出丢最旧(`rust/src/ui/mod.rs:1369,1464-1466`)
267
362
  - 批注和截图**必须填写说明**才能保存/发送,否则弹出提示
268
363
 
@@ -270,7 +365,14 @@ bt_cli({ args: "screenshot --selector .chart" })
270
365
 
271
366
  ## 多会话
272
367
 
273
- 自 1.9.0 起**每个 opencode 会话独享一个浏览器窗口**:独立进程 / 独立端口 / 独立用户数据目录(`sessions/<profile>/<sid>`),窗口、标签、UA、批注与 cookie/存储全部互不共享(`sessionIsolation` / `browserType` 配置项及 `--session-isolation` / `--browser` 参数自 1.9.0 已删除,会话隔离是唯一行为;旧配置文件里的这两项会被忽略)。例外:附着模式(`BT_SHELL_URL` / `BT_SHELL_PORT`)连接外部单例 shell,放弃会话隔离。
368
+ 浏览器实例**按会话隔离**:独立进程 / 独立端口 / 独立用户数据目录,窗口、标签、UA、批注与 cookie/存储互不共享(`sessionIsolation` / `browserType` 配置项及 `--session-isolation` / `--browser` 参数自 1.9.0 已删除,会话隔离是唯一行为;旧配置文件里的这两项会被忽略)。
369
+
370
+ **但「会话」不等于「窗口」**(1.11.1 起):**task 子代理会话默认归并到根会话**。插件沿 `Session.parentID` 回溯到最顶层,用**根 sid** 作浏览器路由键(`browserKey`),主会话与它的**所有**子会话共用同一 bt-shell 实例、同一数据目录 `sessions/<profile>/<根 sid>/`,窗口标题取**根会话**标题——子代理调 `bt_cli` 不会再各开一个窗口。
371
+
372
+ - **回溯限制**:单跳查询 `client.session.get` 超时 **1.5s**,最多回溯 **5 跳**;失败 / 超时 / 成环 / 超限都回退调用者自己的 raw sid 且**不缓存**(下次调用重试),只打 warn 日志——不会把子会话错认成根并长期钉住。
373
+ - **主子默认共用,私有需显式**:要让某个子会话用自己的实例(独立 cookie/登录态/窗口做隔离测试),给它加全局 flag `--private-session`;该标志对**同一子会话粘住**(首次之后不带也保持私有)。
374
+ - **删除会话**:删**子会话**只清该 sid 的关闭标记 / 附着记录,**不关根实例、不删根数据目录**(与根共用一份);删**根会话 / 无父会话 / 私有会话**时才回收实例与数据目录。
375
+ - 例外:附着模式(`BT_SHELL_URL` / `BT_SHELL_PORT`)连接外部单例 shell,放弃会话隔离。
274
376
 
275
377
  ## 发布
276
378
 
package/dist/client.js CHANGED
@@ -12,6 +12,7 @@ import { fileURLToPath } from "url";
12
12
  import { log } from "./logger.js";
13
13
  import { getNotifyUrlForSession } from "./notify-server.js";
14
14
  import { tf } from "./i18n/index.js";
15
+ import { getLogStreamEnv, getWebviewEnv } from "./config/index.js";
15
16
  import { cachedBinaryPath, describeBinaryStatus, ensureBinary } from "./binary.js";
16
17
  import { sanitizeForModel } from "./util/sanitize.js";
17
18
  const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -34,6 +35,10 @@ export function setAppDirectory(dir) {
34
35
  if (dir)
35
36
  appDirectory = dir;
36
37
  }
38
+ /** 取已记录的应用/项目目录(即工作区目录;从未记录时返回空串) */
39
+ export function getAppDirectory() {
40
+ return appDirectory;
41
+ }
37
42
  // Rust 二进制查找:优先级 BT_SHELL_PATH → 本地开发构建(含 opencode 应用目录)→ 下载缓存(binary.ts)
38
43
  // 注意:用 `.tmp/publish-local.ps1` 覆盖到 ~/.cache/opencode/packages/... 后,插件 dist 的相对路径
39
44
  // (`<install>/../rust/...`)已指向缓存目录而非仓库 → 必须借助 opencode 传入的 directory 定位本地构建。
@@ -303,7 +308,10 @@ async function spawnForSession(sid, shell) {
303
308
  args.push("--notify-url", notifyUrl);
304
309
  let proc;
305
310
  try {
306
- proc = spawn(shell, args, { stdio: ["ignore", "pipe", "pipe"] });
311
+ // 日志流配置(1.12.0)以 env 传给 shell:console/network 缓冲预算、network 聚合窗口、
312
+ // Linux 注入开关。附着模式不在本函数(不 spawn → 不传,配置由外部启动者负责)。
313
+ const env = { ...process.env, ...getLogStreamEnv(), ...getWebviewEnv() };
314
+ proc = spawn(shell, args, { stdio: ["ignore", "pipe", "pipe"], env });
307
315
  }
308
316
  catch (e) {
309
317
  // spawn 同步失败(如文件被锁):换不含路径的文案,避免绝对路径经错误消息回流模型
@@ -806,10 +814,14 @@ export const service = {
806
814
  select: cmd("select"),
807
815
  hover: cmd("hover"),
808
816
  pressKey: cmd("press-key"),
817
+ typeText: cmd("type"),
809
818
  drag: cmd("drag"),
810
819
  uploadFile: cmd("upload-file"),
811
820
  screenshot: cmd("screenshot"),
812
821
  evaluate: cmd("evaluate"),
822
+ // 持久注入规则:/api/inject/rules(add/list/remove/clear/enable/disable)、/api/inject/test
823
+ injectRules: cmd("inject/rules"),
824
+ injectTest: cmd("inject/test"),
813
825
  visibleText: cmd("visible-text"),
814
826
  visibleHtml: cmd("visible-html"),
815
827
  elementState: cmd("element-state"),
@@ -838,6 +850,7 @@ export const service = {
838
850
  accessibility: cmd("accessibility"),
839
851
  notify: cmd("notify"),
840
852
  consoleLogs: cmd("console-logs"),
853
+ networkLogs: cmd("network-logs"),
841
854
  expectResponse: cmd("expect-response"),
842
855
  assertResponse: cmd("assert-response"),
843
856
  panelConfig: cmd("panel-config"),
@@ -15,7 +15,40 @@ const WINDOWS_RESERVED_NAMES = new Set([
15
15
  ...Array.from({ length: 9 }, (_, i) => `COM${i + 1}`),
16
16
  ...Array.from({ length: 9 }, (_, i) => `LPT${i + 1}`),
17
17
  ]);
18
- const defaults = { panelLang: "en", toolLang: "en" };
18
+ /** console / network 日志流的默认字节预算:8 MiB(1.12.0) */
19
+ export const DEFAULT_LOG_BUFFER_BYTES = 8 * 1024 * 1024;
20
+ /** network 同 key 合并窗口默认值(ms):间隔 ≤ 此值才累加 count(1.12.0) */
21
+ export const DEFAULT_NETWORK_BURST_MS = 2000;
22
+ /** console 注入默认开关:Linux 开、其它平台关(Windows 走 CDP,无需注入)(1.12.0) */
23
+ export const DEFAULT_CONSOLE_INJECT = process.platform === "linux";
24
+ /**
25
+ * WebView2 额外启动参数默认值(仅 Windows 生效)。
26
+ *
27
+ * 背景:RDP 会话断开/切后台时,DWM 合成暂停;WebView2 若依赖 GPU 合成会阻塞,
28
+ * 进而卡死 UI 线程(我们的同步 UI 调用再把整个进程拖死)。
29
+ * - `--disable-gpu-compositing`:改用 CPU 合成,断开会话不阻塞
30
+ * - `--disable-features=CalculateNativeWinOcclusion`:关闭窗口遮挡计算(后台/隐藏窗口卡死常见诱因)
31
+ *
32
+ * 可用配置 `webview2Args` 或 env `BT_WEBVIEW2_ARGS` 覆盖;设为空串表示不加任何参数。
33
+ */
34
+ export const DEFAULT_WEBVIEW2_ARGS = [
35
+ // 关闭窗口遮挡计算(隐藏/后台窗口卡死常见诱因;前台渲染不受影响)
36
+ "--disable-features=CalculateNativeWinOcclusion",
37
+ // 关键:窗口被遮挡/后台时不要节流或挂起 renderer,
38
+ // 否则 ExecuteScript 可能永不回调 → 同步等 UI 的调用会永久阻塞
39
+ "--disable-background-timer-throttling",
40
+ "--disable-renderer-backgrounding",
41
+ "--disable-backgrounding-occluded-windows",
42
+ ].join(" ");
43
+ const defaults = {
44
+ panelLang: "en",
45
+ toolLang: "en",
46
+ consoleBufferBytes: DEFAULT_LOG_BUFFER_BYTES,
47
+ networkBufferBytes: DEFAULT_LOG_BUFFER_BYTES,
48
+ networkBurstWindowMs: DEFAULT_NETWORK_BURST_MS,
49
+ consoleInject: DEFAULT_CONSOLE_INJECT,
50
+ webview2Args: DEFAULT_WEBVIEW2_ARGS,
51
+ };
19
52
  let _config = { ...defaults };
20
53
  let _worktree = "";
21
54
  /** 获取 opencode 全局配置目录 */
@@ -187,9 +220,41 @@ function applyConfigFile(config, filePath) {
187
220
  config.disabledTools = fileConfig.disabledTools;
188
221
  if (fileConfig.cacheDir !== undefined)
189
222
  config.cacheDir = fileConfig.cacheDir;
223
+ // 日志流配置:非法值(非正数/类型不对)静默忽略,保留默认(配置解析本身不抛错)
224
+ if (typeof fileConfig.webview2Args === "string")
225
+ config.webview2Args = fileConfig.webview2Args;
226
+ const consoleBytes = toPositiveInt(fileConfig.consoleBufferBytes);
227
+ if (consoleBytes !== undefined)
228
+ config.consoleBufferBytes = consoleBytes;
229
+ const networkBytes = toPositiveInt(fileConfig.networkBufferBytes);
230
+ if (networkBytes !== undefined)
231
+ config.networkBufferBytes = networkBytes;
232
+ const burstMs = toPositiveInt(fileConfig.networkBurstWindowMs);
233
+ if (burstMs !== undefined)
234
+ config.networkBurstWindowMs = burstMs;
235
+ if (typeof fileConfig.consoleInject === "boolean")
236
+ config.consoleInject = fileConfig.consoleInject;
190
237
  }
191
238
  catch { }
192
239
  }
240
+ /** 取正整数字面值(字符串数字也接受);非法返回 undefined(配置/环境变量共用) */
241
+ function toPositiveInt(raw) {
242
+ if (raw === undefined || raw === null || raw === "")
243
+ return undefined;
244
+ const n = Number(raw);
245
+ return Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined;
246
+ }
247
+ /** 解析布尔开关:`1/true/on/yes` → true,`0/false/off/no` → false,其它 → undefined */
248
+ function parseBoolFlag(raw) {
249
+ if (raw === undefined)
250
+ return undefined;
251
+ const v = raw.trim().toLowerCase();
252
+ if (["1", "true", "on", "yes"].includes(v))
253
+ return true;
254
+ if (["0", "false", "off", "no"].includes(v))
255
+ return false;
256
+ return undefined;
257
+ }
193
258
  function applyEnv(config) {
194
259
  if (process.env.BT_LANG && isValidLang(process.env.BT_LANG)) {
195
260
  config.panelLang = process.env.BT_LANG;
@@ -207,6 +272,74 @@ function applyEnv(config) {
207
272
  if (process.env.BT_NODE_PATH) {
208
273
  config.nodePath = process.env.BT_NODE_PATH;
209
274
  }
275
+ // 日志流配置:环境变量按 MB 传入(与传给 shell 的 env 同名同单位),内部统一存字节
276
+ const consoleMb = toPositiveInt(process.env.BT_CONSOLE_BUFFER_MB);
277
+ if (consoleMb !== undefined)
278
+ config.consoleBufferBytes = consoleMb * 1024 * 1024;
279
+ const networkMb = toPositiveInt(process.env.BT_NETWORK_BUFFER_MB);
280
+ if (networkMb !== undefined)
281
+ config.networkBufferBytes = networkMb * 1024 * 1024;
282
+ const burstMs = toPositiveInt(process.env.BT_NETWORK_BURST_MS);
283
+ if (burstMs !== undefined)
284
+ config.networkBurstWindowMs = burstMs;
285
+ const inject = parseBoolFlag(process.env.BT_CONSOLE_INJECT);
286
+ if (inject !== undefined)
287
+ config.consoleInject = inject;
288
+ }
289
+ /**
290
+ * 字节预算 → 传给 shell 的 MB 字符串。
291
+ *
292
+ * shell 侧 `BT_*_BUFFER_MB` 只接受**整数** u64(小数会被判非法并回退默认),
293
+ * 因此这里向上取整到整数 MB(至少 1),宁可多给预算也不静默缩水:8 MiB → "8",
294
+ * 1.5 MiB → "2"。
295
+ */
296
+ export function bytesToMbString(bytes) {
297
+ return String(Math.max(1, Math.ceil(bytes / (1024 * 1024))));
298
+ }
299
+ /**
300
+ * 构造传给 shell 的日志流环境变量(spawn 模式专用)。
301
+ *
302
+ * 键名与 Rust 侧读取口径一致:`BT_CONSOLE_BUFFER_MB` / `BT_NETWORK_BUFFER_MB` 为 MB,
303
+ * `BT_NETWORK_BURST_MS` 为毫秒,`BT_CONSOLE_INJECT` 为 `1`/`0`。
304
+ * **附着模式不传**:外部 shell 的缓冲配置由外部启动者负责(见 README「附着模式」)。
305
+ *
306
+ * @param cfg 生效配置(已合并文件与环境变量)
307
+ * @returns 仅新增/覆盖这 4 个键的环境变量表
308
+ */
309
+ export function buildLogStreamEnv(cfg) {
310
+ // 非正数视为未配置(配置层已过滤;这里兜底直接调用方传入的坏值)
311
+ const bytes = (v) => typeof v === "number" && Number.isFinite(v) && v > 0 ? v : DEFAULT_LOG_BUFFER_BYTES;
312
+ const ms = (v) => typeof v === "number" && Number.isFinite(v) && v > 0 ? v : DEFAULT_NETWORK_BURST_MS;
313
+ return {
314
+ BT_CONSOLE_BUFFER_MB: bytesToMbString(bytes(cfg.consoleBufferBytes)),
315
+ BT_NETWORK_BUFFER_MB: bytesToMbString(bytes(cfg.networkBufferBytes)),
316
+ BT_NETWORK_BURST_MS: String(Math.floor(ms(cfg.networkBurstWindowMs))),
317
+ BT_CONSOLE_INJECT: (cfg.consoleInject ?? DEFAULT_CONSOLE_INJECT) ? "1" : "0",
318
+ };
319
+ }
320
+ /** 取当前生效配置对应的 shell 日志流环境变量 */
321
+ export function getLogStreamEnv() {
322
+ return buildLogStreamEnv(getConfig());
323
+ }
324
+ /**
325
+ * 取 spawn shell 时需追加的 WebView2 环境变量(仅 Windows)。
326
+ *
327
+ * 优先级:env `BT_WEBVIEW2_ARGS` > 配置 `webview2Args` > `DEFAULT_WEBVIEW2_ARGS`;
328
+ * 结果与进程已有 `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS` 合并(已包含则不重复)。
329
+ * 返回空对象表示不加任何参数(空串显式关闭)。
330
+ */
331
+ export function getWebviewEnv() {
332
+ if (process.platform !== "win32")
333
+ return {};
334
+ const cfg = getConfig();
335
+ const fromEnv = process.env.BT_WEBVIEW2_ARGS;
336
+ const raw = fromEnv !== undefined ? fromEnv : (cfg.webview2Args ?? DEFAULT_WEBVIEW2_ARGS);
337
+ const args = String(raw).trim();
338
+ if (!args)
339
+ return {};
340
+ const existing = (process.env.WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS || "").trim();
341
+ const merged = !existing ? args : existing.includes(args) ? existing : `${existing} ${args}`;
342
+ return { WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS: merged };
210
343
  }
211
344
  function isValidLang(lang) {
212
345
  return ["en", "zh"].includes(lang);
@@ -232,6 +365,16 @@ function generateDefaultConfig(filePath) {
232
365
  // 禁用的工具列表(可选,工具名不加 bt_ 前缀)
233
366
  // "disabledTools": ["close", "custom_user_agent"],
234
367
 
368
+ // console / network 日志流缓冲字节预算(可选,默认各 8 MiB;等价 BT_CONSOLE_BUFFER_MB / BT_NETWORK_BUFFER_MB)
369
+ // "consoleBufferBytes": 8388608,
370
+ // "networkBufferBytes": 8388608,
371
+
372
+ // network 聚合窗口毫秒(可选,默认 2000;同期同 key 的请求才合并计数;等价 BT_NETWORK_BURST_MS)
373
+ // "networkBurstWindowMs": 2000,
374
+
375
+ // Linux console 注入猴补(可选,默认 Linux true / Windows false;Windows 走 CDP 无需注入;等价 BT_CONSOLE_INJECT)
376
+ // "consoleInject": false,
377
+
235
378
  // 1.9.0 起「每会话独立浏览器实例」为唯一行为(原 sessionIsolation 开关从未生效,已移除);
236
379
  // browserType 同理移除(--browser 从不被 bt-shell 解析)。旧配置里若仍写着这两项会被忽略。
237
380