@xiaoqiong0v0/opencode-browser-tool 1.10.1 → 1.10.2
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 +118 -80
- package/dist/index.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# opencode-browser-tool
|
|
2
2
|
|
|
3
|
-
opencode 插件:Tauri 多 Webview 浏览器外壳 +
|
|
3
|
+
opencode 插件:Tauri 多 Webview 浏览器外壳 + 零注入视觉元素选取面板。对外只注册 **2 个工具**:`bt_cli`(命令行式分发器,内含 **47 条**浏览器自动化命令)与 `bt_set_media_mode`(摄像头/麦克风真伪切换),见下文「工具」。
|
|
4
4
|
|
|
5
5
|
> 架构演进:V1-V3 使用 Playwright 注入式面板(存在弹框类元素无法批注的问题);V4 改为 Rust Shell + 原始调试协议;V5 迁移到 Tauri 2 多 Webview(跨平台)。
|
|
6
6
|
|
|
@@ -15,12 +15,12 @@ opencode 插件:Tauri 多 Webview 浏览器外壳 + 零注入视觉元素选
|
|
|
15
15
|
|
|
16
16
|
## 二进制获取(bt-shell)
|
|
17
17
|
|
|
18
|
-
插件依赖 Rust 外壳 `bt-shell
|
|
18
|
+
插件依赖 Rust 外壳 `bt-shell`。默认在**插件加载时(opencode 启动)就后台自动下载**对应平台的 Release 资产到
|
|
19
19
|
`~/.opencode/plugins-data/opencode-browser-tool/<平台三元组>/bt-shell[.exe]`(Windows 即
|
|
20
20
|
`%USERPROFILE%\.opencode\plugins-data\opencode-browser-tool\<triple>\bt-shell.exe`),并**就地覆盖**同一路径
|
|
21
21
|
(不按插件版本建目录);同目录另有 `bt-shell.version.json` 记录该可执行文件的来源
|
|
22
|
-
(`tag` / `asset` / `sha256` / `size` / `downloadedAt` / `sourceUrl`)。下载用 Release 的 `SHA256SUMS` 做
|
|
23
|
-
sha256 校验(**幂等**:sha 与当前 release 期望值一致即跳过;**原子**替换;跨进程 `.lock`;Linux 下载后 `chmod 755
|
|
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`);未就绪时工具调用会给出
|
|
24
24
|
明确提示(下载进度 / 失败原因),不会假装成功。
|
|
25
25
|
|
|
26
26
|
平台支持与系统依赖:
|
|
@@ -43,20 +43,29 @@ sha256 校验(**幂等**:sha 与当前 release 期望值一致即跳过;**
|
|
|
43
43
|
|
|
44
44
|
## 配置
|
|
45
45
|
|
|
46
|
-
配置文件:`~/.config/opencode/browser-tool.jsonc
|
|
46
|
+
配置文件:`~/.config/opencode/browser-tool.jsonc`(首次运行自动生成,默认值均为 `en`)
|
|
47
47
|
|
|
48
48
|
```jsonc
|
|
49
49
|
{
|
|
50
|
-
"panelLang": "
|
|
50
|
+
"panelLang": "en",
|
|
51
51
|
"toolLang": "en"
|
|
52
52
|
}
|
|
53
53
|
```
|
|
54
54
|
|
|
55
55
|
项目级配置放 `<项目根目录>/.opencode/browser-tool.jsonc`,会覆盖全局。
|
|
56
56
|
|
|
57
|
-
|
|
57
|
+
生成的配置还支持(可选项,见 `src/config/index.ts:27-35,246-274`):
|
|
58
|
+
|
|
59
|
+
- `browsersPath` — 浏览器缓存目录(等价 `BT_BROWSERS_PATH`)
|
|
60
|
+
- `cacheDir` — 插件缓存根(默认 `~/.opencode/plugins-cache/opencode-browser-tool`,下设 `sessions/<profile>/<sid>`、`user-data/<profile>`、`exports`、`tmp`)
|
|
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` 等于没有命令入口,慎用。
|
|
63
|
+
|
|
64
|
+
环境变量(优先级最高,`src/config/index.ts:223-240`):
|
|
58
65
|
- `BT_LANG` — 同时设置 panelLang 和 toolLang
|
|
66
|
+
- `BT_PANEL_LANG` / `BT_TOOL_LANG` — 分别只设置面板 UI 语言 / 工具描述语言
|
|
59
67
|
- `BT_BROWSERS_PATH` — 浏览器缓存目录
|
|
68
|
+
- `BT_NODE_PATH` — Node.js 可执行路径
|
|
60
69
|
- `BT_SHELL_URL` — **附着模式**:连接到已运行的 shell(完整基地址,如 `http://127.0.0.1:18280`),优先级最高
|
|
61
70
|
- `BT_SHELL_PORT` — **附着模式**:仅指定端口,等价于 `http://127.0.0.1:<port>`
|
|
62
71
|
- `BT_SHELL_TOKEN` — **鉴权令牌**:本地 API 所有 `/api/*` 请求必须带 `x-bt-token`。**附着模式下必须设置**,且外部 shell 启动时要用同一值(`--token <token>` 或同值环境变量);启动模式下由插件随机生成并通过 `--token` 传给 shell,无需手动设置
|
|
@@ -66,7 +75,7 @@ sha256 校验(**幂等**:sha 与当前 release 期望值一致即跳过;**
|
|
|
66
75
|
- `BT_SHELL_VERSION` — 显式指定**二进制发布版本**(形如 `1.2.0`,即 `x.Y.0` 的 Release;**原样使用、不做归 0 推导**;不设时由插件版本自动推导)
|
|
67
76
|
- `BT_SHELL_NOTIFY_URL` — 插件通知地址(**推送式投递**;一般由插件自动通过 `--notify-url` / `/api/notify-url` 设置,仅在手动启动 shell 时需自行指定)
|
|
68
77
|
|
|
69
|
-
> **附着模式 vs 启动模式**:设置了 `BT_SHELL_URL`(优先)或 `BT_SHELL_PORT` 时进入附着模式——插件**不 spawn** 任何进程,直接连接该地址的外部 shell;两者都未设置时按启动模式 spawn 本地二进制(`BT_SHELL_PATH` 可覆盖查找路径)。附着模式下 `
|
|
78
|
+
> **附着模式 vs 启动模式**:设置了 `BT_SHELL_URL`(优先)或 `BT_SHELL_PORT` 时进入附着模式——插件**不 spawn** 任何进程,直接连接该地址的外部 shell;两者都未设置时按启动模式 spawn 本地二进制(`BT_SHELL_PATH` 可覆盖查找路径)。附着模式下 `close` 命令只断开本地连接(**不关闭外部窗口、不结束外部进程**;进程不归插件管理)。
|
|
70
79
|
>
|
|
71
80
|
> **附着模式必须设置 `BT_SHELL_TOKEN`**:外部 shell 启动时的令牌必须与插件侧环境变量一致(见下方示例),否则插件启动即报 `client.attach_need_token`,不会去连一个注定 401 的端点。令牌未设置时 shell 会随机生成,因此手动启动的 shell 务必显式传 `--token`(或用同值环境变量)。
|
|
72
81
|
|
|
@@ -106,82 +115,106 @@ opencode(Bun)
|
|
|
106
115
|
- 页面零注入残留脚本,弹框类元素可正常批注
|
|
107
116
|
- 所有工具调用通过 `POST http://127.0.0.1:PORT/api/{command}` 通信,并统一带鉴权头 `x-bt-token`(无 CORS、拒绝任何带 `Origin` 的请求;唯一例外是页面事件桥 `/api/page-event`,见上)
|
|
108
117
|
- 除 spawn 本地 shell 外,也可用 `BT_SHELL_URL` / `BT_SHELL_PORT` **附着到已运行的 shell**(不 spawn,适用于 shell 跑在 WSL/Linux、插件跑在 Windows;**必须同时设置 `BT_SHELL_TOKEN`**,外部 shell 用同一令牌启动)
|
|
109
|
-
-
|
|
118
|
+
- 跨平台代码: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 未实现
|
|
110
119
|
- 真多标签:每标签独立 page Webview,切换不重载;`target=_blank` / `window.open` 链接通过 WebView2 原生事件拦截并打开为新标签。**关闭标签会释放该标签的页面实例**(预创建池的 3 个 webview 保留复用,池外动态创建的实例直接销毁),反复开关标签不会累积页面进程
|
|
111
120
|
- 地址栏/标题/图标**事件驱动同步(无轮询)**:导航用 `on_navigation`(请求即更新)+ `on_page_load`(完成后读真实 `location.href`/`title`);站内 SPA(`pushState`/`replaceState`/`popstate`/`hashchange`)与标题/图标变化由注入脚本上报 `POST /api/page-event`。`TabState.url` 只反映**最后一次真实导航请求**,内部/错误 scheme(`chrome-error:`/`about:`/`tauri:`/`data:` 等)不覆盖地址栏
|
|
112
|
-
- 刷新语义:标签处于错误页(`errored`)时,工具栏刷新 / `
|
|
121
|
+
- 刷新语义:标签处于错误页(`errored`)时,工具栏刷新 / `reload` 命令**重新导航原 URL**(而非刷错误页);否则走原生 reload
|
|
113
122
|
- 窗口无标题栏,自定义窗口按钮在标签行右侧;最小尺寸 360×432(逻辑像素;内容区最小 360×360,含 72px 工具栏)
|
|
114
123
|
|
|
115
124
|
## 工具
|
|
116
125
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
|
120
|
-
|
|
121
|
-
|
|
|
122
|
-
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
126
|
+
插件**只注册 2 个工具**(`src/index.ts:376-463`):
|
|
127
|
+
|
|
128
|
+
| 工具 | 参数 | 说明 |
|
|
129
|
+
|------|------|------|
|
|
130
|
+
| `bt_cli` | `args`(string,可选) | 唯一入口:命令行式分发器,一条命令字符串执行一项浏览器操作;`args` 省略或为 `help` / `--help` / `-h` 时返回完整帮助(命令名、用法、说明、示例) |
|
|
131
|
+
| `bt_set_media_mode` | `mode`(string):`simulate` \| `real`,可选 | 切换摄像头/麦克风设备:`simulate`=模拟设备(默认,配合 `fake_audio` / `fake_video`);`real`=真实设备(不可用时回落 simulate)。省略 `mode` 只查询当前模式。切真实设备属敏感操作,单独保留工具以维持 `ask` 权限 |
|
|
132
|
+
|
|
133
|
+
### bt_cli 调用语法
|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
bt_cli({ args: "<command> [--flag value ...]" })
|
|
137
|
+
```
|
|
127
138
|
|
|
128
|
-
|
|
139
|
+
- **命令名不带 `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
|
|
129
144
|
|
|
130
|
-
|
|
145
|
+
示例:
|
|
131
146
|
|
|
132
|
-
|
|
147
|
+
```text
|
|
148
|
+
bt_cli({ args: "help" })
|
|
149
|
+
bt_cli({ args: "navigate --url https://example.com" })
|
|
150
|
+
bt_cli({ args: "click --selector #submit" })
|
|
151
|
+
bt_cli({ args: "fill --selector #q --value \"hello world\"" })
|
|
152
|
+
bt_cli({ args: "screenshot --selector .chart" })
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### `--timeout`(下表标 ⏱ 的 17 条命令支持)
|
|
156
|
+
|
|
157
|
+
- 单位**毫秒**,`--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`
|
|
159
|
+
- **未传时走各命令自己的默认,并非统一 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
|
+
|
|
161
|
+
### 命令参考(47 条)
|
|
162
|
+
|
|
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" })` 的实际输出为准。
|
|
164
|
+
|
|
165
|
+
| 命令 | 参数(usage 原文) | 说明 |
|
|
133
166
|
|------|------|------|
|
|
134
|
-
| `
|
|
135
|
-
| `
|
|
136
|
-
| `
|
|
137
|
-
| `
|
|
138
|
-
| `
|
|
139
|
-
| `
|
|
140
|
-
| `
|
|
141
|
-
| `
|
|
142
|
-
| `
|
|
143
|
-
| `
|
|
144
|
-
| `
|
|
145
|
-
| `
|
|
146
|
-
| `
|
|
147
|
-
| `
|
|
148
|
-
| `
|
|
149
|
-
| `
|
|
150
|
-
| `
|
|
151
|
-
| `
|
|
152
|
-
| `
|
|
153
|
-
| `
|
|
154
|
-
| `
|
|
155
|
-
| `
|
|
156
|
-
| `
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
159
|
-
| `
|
|
160
|
-
| `
|
|
161
|
-
| `
|
|
162
|
-
| `
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
166
|
-
| `
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
169
|
-
| `
|
|
170
|
-
| `
|
|
171
|
-
| `
|
|
172
|
-
| `
|
|
173
|
-
| `
|
|
174
|
-
| `
|
|
175
|
-
| `
|
|
176
|
-
| `
|
|
177
|
-
| `
|
|
178
|
-
| `
|
|
179
|
-
| `
|
|
180
|
-
| `
|
|
167
|
+
| `navigate` | `--url <地址>` 必填 | 导航浏览器到 URL(裸域名自动补 `http://`) |
|
|
168
|
+
| `click` ⏱ | `--selector` 必填 | 点击页面元素 |
|
|
169
|
+
| `fill` ⏱ | `--selector --value` 必填 | 填写输入框(`--value` 可传 `@file:` 路径) |
|
|
170
|
+
| `clear` ⏱ | `--selector` 必填 | 清空输入框 |
|
|
171
|
+
| `select` ⏱ | `--selector --value` 必填 | 选择下拉框选项 |
|
|
172
|
+
| `hover` ⏱ | `--selector` 必填 | 悬停到元素 |
|
|
173
|
+
| `drag` ⏱ | `--sourceSelector --targetSelector` 必填 | 拖拽元素到目标 |
|
|
174
|
+
| `press_key` ⏱ | `--key` 必填,`[--selector]` | 按下键盘按键;`--selector` 指定先聚焦的元素 |
|
|
175
|
+
| `upload_file` ⏱ | `--selector --filePath` 必填 | 上传文件到输入框 |
|
|
176
|
+
| `screenshot` ⏱ | `[--selector]` | 截取页面/元素截图(返回图片附件;带 `--selector` 先滚动到元素再截) |
|
|
177
|
+
| `evaluate` ⏱ | `--script` 必填 | 在页面执行 JS,返回结果 |
|
|
178
|
+
| `get_visible_text` | `[--selector]` | 获取页面可见文本 |
|
|
179
|
+
| `get_visible_html` | `[--selector --removeScripts --removeComments --maxLength]` | 获取页面 HTML 结构(`--removeScripts` / `--removeComments` 为布尔开关;`--maxLength` 超出时输出标注截断) |
|
|
180
|
+
| `console_logs` | `[--type --search --limit --clear]` | 获取浏览器控制台日志(`--clear` 读取后清空) |
|
|
181
|
+
| `go_back` | 无 | 浏览器后退,返回当前 URL |
|
|
182
|
+
| `go_forward` | 无 | 浏览器前进,返回当前 URL |
|
|
183
|
+
| `resize` | `--width --height` 必填 | 调整页面内容区尺寸(视口,非 OS 窗口;窗口高 = 内容高 + 工具栏 72px;下限 360×360,低于下限被钳制并标 `clamped`) |
|
|
184
|
+
| `set_device` | `[--name]` | 应用设备预设(不传 `--name` 列出预设;预设尺寸为内容区(视口)尺寸) |
|
|
185
|
+
| `devtools` | `[--action]` | 打开/关闭开发者工具:`open`/`close`/`toggle`(缺省 `toggle`)。Windows 无法真正关闭,`close` 如实返回不支持并提示用 F12 手动切换;Linux 可正常开关 |
|
|
186
|
+
| `reload` | 无 | 刷新当前页面;当前为错误页时**重新导航原 URL**(返回 `retried`) |
|
|
187
|
+
| `open_window` | 无 | 打开浏览器窗口(未启动则启动;已启动幂等) |
|
|
188
|
+
| `close` | 无 | 关闭浏览器(与手动关窗同一语义)。关闭后其它命令返回指引(`Browser is closed. Call open_window…`),**绝不自动重开**,需 `open_window` 显式打开;attach 模式只断开本地关联(不关外部窗口/进程) |
|
|
189
|
+
| `show_notification` | `--message` 必填,`[--type]` | 页面显示通知气泡(`--type`:`ok`/`bad`/`err`) |
|
|
190
|
+
| `scroll` | `[--direction --amount]` | 滚动页面(`--direction`:`up`/`down`/`left`/`right`,缺省 `down`;`--amount` 缺省 300px) |
|
|
191
|
+
| `wait_for_selector` ⏱ | `--selector` 必填 | 等待元素出现 |
|
|
192
|
+
| `click_and_switch_tab` | `--selector` 必填 | 点击元素;若触发新标签则自动切换,返回当前 URL |
|
|
193
|
+
| `iframe_click` ⏱ | `--iframeSelector --selector` 必填 | 在 iframe 内点击元素(仅同源可访问) |
|
|
194
|
+
| `iframe_fill` ⏱ | `--iframeSelector --selector --value` 必填 | 在 iframe 内填写输入框(仅同源可访问) |
|
|
195
|
+
| `get_browser_status` | 无 | **纯查询、不启动浏览器**:运行中返回 open/url/title/tabs 数量;未运行时返回未运行提示 + bt-shell 二进制状态(下载中/就绪/失败/禁用) |
|
|
196
|
+
| `list_tabs` | 无 | 列出所有打开的标签(索引+URL) |
|
|
197
|
+
| `switch_tab` | `--index` 必填 | 按索引(0 起)切换标签 |
|
|
198
|
+
| `new_tab` | `--url` 必填 | 打开新标签并导航(真多标签) |
|
|
199
|
+
| `close_tab` | `[--index]` | 关闭标签;省略则关当前激活标签。关闭会**释放该标签的页面实例**(池内 webview 回池复用,池外实例销毁) |
|
|
200
|
+
| `get_element_state` ⏱ | `--selector` 必填 | 元素存在/可见/文本/位置(rect) |
|
|
201
|
+
| `scroll_to_element` ⏱ | `--selector` 必填 | 滚动到元素可见;未到达/未稳定不吞错,输出带 `reached`/`stable`/`waitedMs` |
|
|
202
|
+
| `get_dropdown_options` ⏱ | `--selector` 必填 | 列出下拉框选项(当前选中项标 `*`) |
|
|
203
|
+
| `custom_user_agent` | `--userAgent` 必填 | 设置自定义 User-Agent(Windows/Linux 支持;macOS 未实现) |
|
|
204
|
+
| `expect_response` | `--url` 必填 | 记录期望匹配的响应模式,清空响应历史后重新捕获 |
|
|
205
|
+
| `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`) |
|
|
208
|
+
| `read_record_content` | `--id` 必填 | 按 id 读取单条记录详情(截图落盘为临时 PNG 并给出大小与路径) |
|
|
209
|
+
| `fake_audio` | `--kind` 必填,`[--data --freq --durMs --notes --digits --loop]` | 向 fake 麦克风注入音频(`kind`:tone/seq/dtmf/noise/audio/ambient/stop) |
|
|
210
|
+
| `fake_video` | `--kind` 必填,`[--data --url --loop]` | 向 fake 摄像头注入画面(`kind`:image/video/auto/stop) |
|
|
211
|
+
| `profile` | `[--set <name> \| --delete <name>]` | user-data 配置管理:空参列出;`--set` 切换默认配置(影响**后续新会话**的数据根,不重启运行中的浏览器);`--delete` 删除(default/激活项除外) |
|
|
212
|
+
| `exports` | 无 | 显示导出目录与 Edge/Chrome 密码/书签导出指引 |
|
|
213
|
+
| `lookup` | `--csv <path> --url <site>` 必填 | 从密码 CSV 按站点匹配并返回 `@file:` 临时文件路径(密码不进上下文,用完即删) |
|
|
181
214
|
|
|
182
215
|
### 元素截图行为(v1.7.0 起统一)
|
|
183
216
|
|
|
184
|
-
`
|
|
217
|
+
`screenshot --selector <css>` 固定流程:
|
|
185
218
|
|
|
186
219
|
1. **先滚动**:复用 `scroll_to_element`(立即 `scrollIntoView` 居中 + 轮询等滚动稳定);未到达/未稳定**不吞错**,结果带 `reached`/`stable`/`waitedMs`,工具输出追加对应提示
|
|
187
220
|
2. **重测 rect**:滚动稳定后重新取元素视口矩形(覆盖懒加载/布局变化后的真位置)
|
|
@@ -193,7 +226,11 @@ opencode(Bun)
|
|
|
193
226
|
|
|
194
227
|
**坐标系(实测,v1.7.0)**:CDP `clip` **恒为文档坐标**(`captureBeyondViewport` true/false 均如此)——传视口坐标会在滚动后的页面截到错误区域(旧版元素截图在滚动页面上即踩此坑);截图层内部统一做 视口坐标 + `scrollX/Y` 换算,调用方一律传视口坐标。
|
|
195
228
|
|
|
196
|
-
错误口径不变:`element not found: <sel>` / `element has zero size: <sel
|
|
229
|
+
错误口径不变:`element not found: <sel>` / `element has zero size: <sel>`。**输出图片尺寸**:
|
|
230
|
+
|
|
231
|
+
- **Windows**:元素/区域截图走 CDP `clip`,`scale` 固定 `1`(`rust/src/control/screenshot.rs:148`)→ 输出为**选区 CSS 像素 1:1**,插件不额外乘 DPR;无 `--selector` 的整视口截图**不带 `clip`/`scale`**(`rust/src/control/screenshot.rs:150`),由 WebView2/CDP 默认整屏捕获、插件不做缩放
|
|
232
|
+
- **Linux**(v1.10.0 起):WebKitGTK 快照面按**设备像素**输出,裁剪前用 webview 的 `scale_factor` 做 CSS→设备像素换算——`设备像素 = round(CSS 像素 × k)`,`k` 取 `WidgetExt::scale_factor`(非有限或 ≤0 时回退 `1.0`)(`rust/src/control/screenshot.rs:196-199,228-233,293-294,305-314`)。因此 **HiDPI(k>1)下输出尺寸 = 选区 CSS 尺寸 × k,不再是 1:1**;旧文档「CSS 像素 = 设备像素」的 1:1 假设(仅 WSLg dpr=1 时恰好成立)已作废。无 `--selector` 的 `Visible` 整视口快照同样按该缩放输出
|
|
233
|
+
|
|
197
234
|
|
|
198
235
|
**已知限制**
|
|
199
236
|
|
|
@@ -203,12 +240,12 @@ opencode(Bun)
|
|
|
203
240
|
|
|
204
241
|
## 设备预设 / 尺寸语义
|
|
205
242
|
|
|
206
|
-
> ⚠️ **行为变更(v1.8.0)**:`
|
|
243
|
+
> ⚠️ **行为变更(v1.8.0)**:`resize` 与 `set_device` 的宽高一律指**页面内容区(视口)**尺寸,不再是 OS 窗口尺寸。窗口高 = 内容区高 + 工具栏 72px。**旧脚本若按窗口尺寸理解,高度会偏 72px**。API 返回同时给出 `content` 与 `window` 两组尺寸便于核对。
|
|
207
244
|
|
|
208
|
-
- **内容区下限 360×360**:`
|
|
245
|
+
- **内容区下限 360×360**:`resize` 低于下限会被钳制,返回 `clamped:true`(工具输出也标注);窗口 `min_inner_size` 同步为 360×432(= 360 内容高 + 72 工具栏)
|
|
209
246
|
- **窄模式(窗口逻辑宽 < 480)**:面板改为**填满整个窗口**(覆盖式,x=0;页面 webview 保持全宽在下层,关闭面板即见完整页面);工具栏的批注/截图/面板三按钮**去文字只留图标**(媒体查询 `@media (max-width: 479px)`,与 Rust `ui::NARROW_MODE_MAX_W=480` 同步维护)。手机类预设(360~412 宽)天然落入窄模式,避免按钮溢出
|
|
210
247
|
|
|
211
|
-
内置 14 种设备预设(**内容区尺寸** + User-Agent),可通过 `
|
|
248
|
+
内置 14 种设备预设(**内容区尺寸** + User-Agent),可通过 `set_device`(不带 `--name` 即列出清单)或右侧面板下拉框一键切换:
|
|
212
249
|
|
|
213
250
|
| 分类 | 预设(内容区尺寸) |
|
|
214
251
|
|------|------|
|
|
@@ -225,11 +262,11 @@ opencode(Bun)
|
|
|
225
262
|
|
|
226
263
|
- **批注模式** — 悬停高亮元素(覆盖层自绘),点击元素弹出输入框填写说明;引擎层拦截,弹框/下拉类元素不失焦
|
|
227
264
|
- **截图模式** — 点击立即截全屏;也可进入截图模式后拖动框选区域(选区可拖拽手柄调整大小),保存时可按需裁剪(遮罩式选区,默认整图,双击还原)
|
|
228
|
-
- **记录列表** — 面板「AI 功能」区:批注/截图记录卡片(截图带缩略图),显示所属标签 URL
|
|
229
|
-
- **发送** — 面板底部「发送」按钮:所有记录(批注文字 + 截图图片)推送到 opencode 对话;发送后**面板列表清空**(与旧 Playwright 工具一致,仅列表为空),但**记录本身保留**并标记 `[sent]`(`
|
|
265
|
+
- **记录列表** — 面板「AI 功能」区:批注/截图记录卡片(截图带缩略图),显示所属标签 URL 与说明。**记录上限 200 条**,超出丢最旧(`rust/src/ui/annotate.rs:395,403-406`)
|
|
266
|
+
- **发送** — 面板底部「发送」按钮:所有记录(批注文字 + 截图图片)推送到 opencode 对话;发送后**面板列表清空**(与旧 Playwright 工具一致,仅列表为空),但**记录本身保留**并标记 `[sent]`(`list_records` 仍可读取,截图也可通过 `read_record_content` 取到)。投递为**推送式**:shell 发送后主动通知插件(`POST /notify/<sid>`,按会话归属),插件收到即拉取并推送到对话(无轮询、无 2s 延迟)。**待发送队列上限 500 条**,超出丢最旧(`rust/src/ui/mod.rs:1369,1464-1466`)
|
|
230
267
|
- 批注和截图**必须填写说明**才能保存/发送,否则弹出提示
|
|
231
268
|
|
|
232
|
-
面板「配置」区:外观主题(跟随系统/浅色/深色)、设备预设下拉(等价 `
|
|
269
|
+
面板「配置」区:外观主题(跟随系统/浅色/深色)、设备预设下拉(等价 `set_device`)、开发者工具按钮(等价 `devtools`)。
|
|
233
270
|
|
|
234
271
|
## 多会话
|
|
235
272
|
|
|
@@ -242,7 +279,8 @@ opencode(Bun)
|
|
|
242
279
|
```bash
|
|
243
280
|
# 1) 定版本(动 Rust 用 minor;纯插件用 patch)
|
|
244
281
|
npm version <x.y.z> --no-git-tag-version
|
|
245
|
-
# 2)
|
|
282
|
+
# 2) 构建插件产物(npm run build = tsc,src/**/*.ts → dist/,增量、**不清空 dist**)
|
|
283
|
+
# 改过文件名/删过源文件时先手动清 dist 再建,避免孤儿 .js(Windows:Remove-Item -Recurse -Force dist)
|
|
246
284
|
npm run build
|
|
247
285
|
# 3) 提交 + 打 tag + 建 Release(tag = v<x.y.z>)
|
|
248
286
|
# 只有动 Rust 时才需要为 x.Y.0 上传各平台二进制 + SHA256SUMS:
|
|
@@ -254,7 +292,7 @@ npm publish
|
|
|
254
292
|
|
|
255
293
|
- `SHA256SUMS` 每行 `<sha256> <文件名>`(两空格),文件名不带路径。
|
|
256
294
|
- npm 包只带 `dist/`(`files: ["dist"]`);原生二进制由运行时从 Release 下载(见「二进制获取」)。
|
|
257
|
-
-
|
|
295
|
+
- **先本地自测**:需覆盖安装到 opencode 插件缓存后重启验证;**本地覆盖安装的脚本需自备**(`.tmp/` 被 gitignore、仓库不含该文件),做法与脚本模板见技能 `xqv-plugin-release`。
|
|
258
296
|
- **部署顺序(exe 文件锁)**:若已有 opencode 实例在跑,`cargo build --release` 会在最后一步报 `failed to remove file ... (os error 5)`(产物不可信)→ 先**退出 opencode**(确认 shell 也退出)→ 构建 → 重新启动。TS 改动需 `npm run build` 重建 `dist/`。
|
|
259
297
|
|
|
260
298
|
## 开发
|
package/dist/index.js
CHANGED
|
@@ -186,7 +186,7 @@ const COMMANDS = {
|
|
|
186
186
|
return _t("cli.out.no_records");
|
|
187
187
|
} } },
|
|
188
188
|
read_record_content: { usage: "--id", descKey: "cli.cmd.read_record_content", args: [{ flag: "id" }], run: async (a) => { try {
|
|
189
|
-
const records = await service.annotateRecords(sidArgs(a));
|
|
189
|
+
const records = await service.annotateRecords({ ...sidArgs(a), includeImages: true });
|
|
190
190
|
const rec = (records || []).find((r) => r.index === a.id);
|
|
191
191
|
if (!rec)
|
|
192
192
|
return _t("cli.out.record_not_found", { id: a.id });
|