@liyuera/dsh-chrome-browser 0.3.0 → 0.5.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.
Files changed (100) hide show
  1. package/README.md +238 -12
  2. package/extension/icons/icon-128.png +0 -0
  3. package/extension/icons/icon-16.png +0 -0
  4. package/extension/icons/icon-32.png +0 -0
  5. package/extension/icons/icon-48.png +0 -0
  6. package/extension/manifest.json +12 -5
  7. package/extension/service-worker.js +772 -70
  8. package/lib/activity.d.ts +65 -0
  9. package/lib/activity.d.ts.map +1 -0
  10. package/lib/activity.js +111 -0
  11. package/lib/activity.js.map +1 -0
  12. package/lib/backend.d.ts +235 -11
  13. package/lib/backend.d.ts.map +1 -1
  14. package/lib/backend.js +429 -40
  15. package/lib/backend.js.map +1 -1
  16. package/lib/cdp.d.ts +7 -1
  17. package/lib/cdp.d.ts.map +1 -1
  18. package/lib/cdp.js +17 -1
  19. package/lib/cdp.js.map +1 -1
  20. package/lib/chrome.d.ts +8 -0
  21. package/lib/chrome.d.ts.map +1 -1
  22. package/lib/chrome.js +20 -0
  23. package/lib/chrome.js.map +1 -1
  24. package/lib/client/BrowserActivity.d.ts +22 -0
  25. package/lib/client/BrowserActivity.d.ts.map +1 -0
  26. package/lib/client/BrowserActivity.js +100 -0
  27. package/lib/client/BrowserActivity.js.map +1 -0
  28. package/lib/client/activity.d.ts +27 -0
  29. package/lib/client/activity.d.ts.map +1 -0
  30. package/lib/client/activity.js +57 -0
  31. package/lib/client/activity.js.map +1 -0
  32. package/lib/client/index.d.ts +4 -6
  33. package/lib/client/index.d.ts.map +1 -1
  34. package/lib/client/index.js +13 -19
  35. package/lib/client/index.js.map +1 -1
  36. package/lib/client/tab-catalog.d.ts +11 -1
  37. package/lib/client/tab-catalog.d.ts.map +1 -1
  38. package/lib/client/tab-catalog.js.map +1 -1
  39. package/lib/client/tab-source.d.ts +8 -2
  40. package/lib/client/tab-source.d.ts.map +1 -1
  41. package/lib/client/tab-source.js.map +1 -1
  42. package/lib/client.js +177 -13
  43. package/lib/client.js.map +1 -1
  44. package/lib/console-events.d.ts +32 -0
  45. package/lib/console-events.d.ts.map +1 -0
  46. package/lib/console-events.js +106 -0
  47. package/lib/console-events.js.map +1 -0
  48. package/lib/console-log.d.ts +107 -0
  49. package/lib/console-log.d.ts.map +1 -0
  50. package/lib/console-log.js +158 -0
  51. package/lib/console-log.js.map +1 -0
  52. package/lib/expressions.d.ts +71 -2
  53. package/lib/expressions.d.ts.map +1 -1
  54. package/lib/expressions.js +277 -14
  55. package/lib/expressions.js.map +1 -1
  56. package/lib/extension-package.d.ts +49 -0
  57. package/lib/extension-package.d.ts.map +1 -1
  58. package/lib/extension-package.js +115 -0
  59. package/lib/extension-package.js.map +1 -1
  60. package/lib/help.d.ts +89 -0
  61. package/lib/help.d.ts.map +1 -0
  62. package/lib/help.js +94 -0
  63. package/lib/help.js.map +1 -0
  64. package/lib/index.d.ts +4 -2
  65. package/lib/index.d.ts.map +1 -1
  66. package/lib/index.js +30 -9
  67. package/lib/index.js.map +1 -1
  68. package/lib/presentation.d.ts +130 -0
  69. package/lib/presentation.d.ts.map +1 -0
  70. package/lib/presentation.js +361 -0
  71. package/lib/presentation.js.map +1 -0
  72. package/lib/routes.d.ts +3 -8
  73. package/lib/routes.d.ts.map +1 -1
  74. package/lib/routes.js +24 -109
  75. package/lib/routes.js.map +1 -1
  76. package/lib/skill.d.ts +50 -0
  77. package/lib/skill.d.ts.map +1 -0
  78. package/lib/skill.js +164 -0
  79. package/lib/skill.js.map +1 -0
  80. package/lib/text.d.ts +21 -0
  81. package/lib/text.d.ts.map +1 -1
  82. package/lib/text.js +18 -0
  83. package/lib/text.js.map +1 -1
  84. package/lib/tools.d.ts +22 -4
  85. package/lib/tools.d.ts.map +1 -1
  86. package/lib/tools.js +493 -75
  87. package/lib/tools.js.map +1 -1
  88. package/lib/ws.d.ts +9 -2
  89. package/lib/ws.d.ts.map +1 -1
  90. package/lib/ws.js +49 -19
  91. package/lib/ws.js.map +1 -1
  92. package/package.json +5 -3
  93. package/lib/bindings.d.ts +0 -23
  94. package/lib/bindings.d.ts.map +0 -1
  95. package/lib/bindings.js +0 -49
  96. package/lib/bindings.js.map +0 -1
  97. package/lib/client/TabPicker.d.ts +0 -54
  98. package/lib/client/TabPicker.d.ts.map +0 -1
  99. package/lib/client/TabPicker.js +0 -329
  100. package/lib/client/TabPicker.js.map +0 -1
package/README.md CHANGED
@@ -6,21 +6,225 @@ Chrome 浏览器控制插件(host + 浏览器半边):通过 Chrome 扩展桥(默
6
6
 
7
7
  | 工具/入口 | 说明 |
8
8
  | --- | --- |
9
- | `chrome_tabs` | 列出你的 Chrome 所有标签页(id/title/url/active),并带 `session` 字段(本会话选中的标签页) |
10
- | `chrome_read` | 读取标签页标题、URL、可见文本(`innerText`,按 `readTextLimit` 截断,可选 HTML) |
9
+ | `chrome_tabs` | 列出你的 Chrome 所有标签页(id/title/url/active) |
10
+ | `chrome_read` | `mode: 'text'`(默认)读标题、URL 与可见文本(**窗口 + 续读游标**,可选 HTML);`mode: 'interactive'` 列出可交互元素及其状态(见下) |
11
11
  | `chrome_navigate` | 标签页导航到 URL(默认等待 `readyState=complete`) |
12
- | `chrome_open` | 新开前台标签页 |
12
+ | `chrome_open` | 新开前台标签页;**默认等加载完成**(`readyState=complete`,上限 `waitLoadMs`)后返回,返回的标题已是加载后的标题。**URL 只接受 http/https/file**,其它 scheme 在开标签页**之前**就报错 |
13
+ | `chrome_close` | 按 id 关闭一个标签页;**`tabId` 必填,不接受 `active`**——关掉用户正在看的那一页几乎总是错的 |
13
14
  | `chrome_screenshot` | PNG 截图落盘,返回路径/字节数/视口尺寸;模型用 `read_image` 查看 |
14
- | `chrome_click` | CSS 选择器 `element.click()`(可选 `all` 批量) |
15
+ | `chrome_click` | CSS 选择器 `element.click()`(可选 `all` 批量)。返回**实际派发点击**的元素数(不是匹配到的数量),并报告「存在但不可点」的原因 |
16
+ | `chrome_hover` | 悬停到元素上,展开只在 hover 时出现的菜单/工具条 |
15
17
  | `chrome_type` | 聚焦输入框并输入文本(默认先全选替换) |
16
- | `chrome_eval` | 在页面上下文执行 JS 表达式,按值返回(≤200k 字符) |
18
+ | `chrome_select` | 按 **option value**(不是显示文本)选中 `<select>` 的一项;值不存在时**列出可用值** |
19
+ | `chrome_press` | 按一个键(可选先聚焦某元素):Enter 提交、Escape 关闭、Tab/方向键切换;**Enter 会显式提交所属表单并报告 `submitted`** |
20
+ | `chrome_eval` | 在页面上下文执行 JS 表达式,按值返回(≤200k 字符);**页面 CSP 禁止 `eval` 时自动改走调试通道并在结果里说明**(`world: "debugger"`) |
21
+ | `chrome_wait` | 等元素达到某个状态(`visible` / `hidden` / `attached` / `detached`);**`satisfied: false` 表示超时,不是成功** |
22
+ | `chrome_console` | 采集/读取某个标签页的控制台(`action: start / read / stop`);**必须在页面出问题之前 start**,含浏览器自身抛的错误(资源加载失败、CSP 拦截) |
23
+ | `chrome_request_help` | 停下来请用户做只有人能做的事(登录、验证码、二次验证),等用户答复;`completed: false` 表示用户跳过了,不要重试 |
17
24
  | `@` 标签页分组 | 在输入框敲 `@` 时列出实时标签页(行内是「标题 + URL」),选中插入一个引用芯片;发送后消息里只有这个引用,标签页的 URL 与 tabId 由宿主注入一条上下文消息给模型 |
25
+ | 活动状态条 | 输入框上方,只在**插件正在调用工具时**出现:脉冲点 + Chrome 图标 + 正在做什么(如「点击 · 标签页 7」)。空闲时不渲染任何东西 |
26
+ | `/chrome-browser` skill | 注册一个 agent skill:讲清什么时候用、调用顺序、失败怎么办、有哪些边界。模型通过 `skill` 工具读它,你也可以直接敲 `/chrome-browser`。宿主没有 skill 服务时静默跳过,工具照常可用 |
27
+
28
+ ### chrome_read:两个阅读模式
29
+
30
+ **`mode: 'text'`(默认)** —— 返回页面可见文本的**一个窗口**,不是一个死胡同:
31
+
32
+ | 字段 | 含义 |
33
+ | --- | --- |
34
+ | `text` | 从 `offset` 开始的 `readTextLimit` 个码点(默认 30000) |
35
+ | `textChars` | 整篇文档的码点数 |
36
+ | `offset` | 这个窗口的起点 |
37
+ | `nextOffset` | **还有内容时**给出,下次传 `offset: nextOffset` 接着读 |
38
+ | `textTruncated` | 是否还有没读到的内容 |
39
+
40
+ 超出预算时 `text` 末尾会附一行说明(如 `…[window 0-30000 of 81000 code points; pass offset=30000 for the rest]`),所以模型能自己发现该继续读,而不是以为页面就这么长。
41
+
42
+ **`mode: 'interactive'`** —— 列出**可交互元素**,每个带:
43
+
44
+ | 字段 | 含义 |
45
+ | --- | --- |
46
+ | `selector` | **可直接喂给 `chrome_click` / `chrome_type`** 的选择器(优先用唯一 id,否则是带 `:nth-of-type` 的短路径,最多 4 层) |
47
+ | `role` / `name` | ARIA role(缺省用标签名)与可读名称(aria-label / 文本 / value / placeholder / title / name) |
48
+ | `inView` | 中心点是否在视口内 |
49
+ | `disabled` | 原生 `disabled` 或 `aria-disabled="true"` |
50
+ | `covered` | 中心点命中测试落在别的元素上——真实点击会打偏 |
51
+
52
+ - 命中判定与 `chrome_click` 的 `warnings` **用的是同一个探针**,所以两处的 `covered` 是同一个意思。
53
+ - 无尺寸、`display:none`、`visibility:hidden` 的元素**直接从清单里剔除**(`matched` 仍计入它们,所以 `shown < matched` 说明有元素被剔除)。
54
+ - 单次最多 150 条。
55
+ - **同一屏信息比 `innerText` 小一到两个数量级,而且读完就能直接操作**——所以在点击/输入之前优先用它。
56
+
57
+ > 只覆盖**主框架**:iframe 内的元素不在清单里,与 `chrome_read` 的文本限制一致。
58
+
59
+ ### 工具卡片与并发
60
+
61
+ 九个工具都声明了 UI 呈现与会话调度所需的元数据,模型侧收到的 JSON 不受影响:
62
+
63
+ - **卡片**:调用中显示语义标题(如「读取标签页 42」「导航到 https://…」),完成后换成结果卡片——标签页列表带 ▶ 标记活动页、读取卡片显示页面标题与字符数(可交互模式显示元素清单与禁用/遮挡标记)、截图卡片显示文件名与大小。`chrome_type` 的调用与结果卡片都**不显示输入内容**(可能是密码)。
64
+ - **并发**:`chrome_tabs` 与 `chrome_read` 声明为并发安全,可与其他调用并行;其余七个要么改页面要么独占扩展桥,保持串行。DSH 的调度器对「未声明」一律按独占处理,所以这里是显式声明「哪些能并行」,而不是显式禁止。
65
+
66
+ ### chrome_click 的返回值:派发 ≠ 生效
67
+
68
+ `element.click()` 会**绕过命中测试**——它能在真实指针永远到不了的元素上触发。所以 `chrome_click` 区分两件事:
69
+
70
+ | 字段 | 含义 |
71
+ | --- | --- |
72
+ | `matched` | 选择器匹配到几个元素 |
73
+ | `clicked` | 其中几个**实际派发了点击事件** |
74
+ | `warnings[]` | 派发了、但真实用户点不到的原因 |
75
+
76
+ - **原生 `disabled` 的元素不派发事件**,因此不计入 `clicked`;全都禁用时调用直接抛错,而不是返回一个假的成功。
77
+ - 不可见(无尺寸 / `display:none` / `visibility:hidden`)、视口外、被其他元素遮挡(中心点命中测试落在别处)、`aria-disabled="true"` 的元素**仍会派发**,但会在 `warnings` 里逐条说明。
78
+ - 结果卡片同样显示这些警告(带 ⚠),`已点击 1/5 个元素` 这种标题表示选择器比预期宽。
79
+
80
+ **看到 `clicked` 不等于页面有反应。** 页面没变化时先看 `warnings`,再用 `chrome_read` 确认状态。
81
+
82
+ ### chrome_console:采集必须在出问题之前开始
83
+
84
+ ```
85
+ chrome_console { action: 'start', tabId } ← 先开
86
+ chrome_navigate / chrome_click / 让用户复现 ← 再做
87
+ chrome_console { action: 'read', tabId } ← 再看
88
+ chrome_console { action: 'stop', tabId } ← 收尾
89
+ ```
90
+
91
+ - **不回溯**:没 start 之前发生的事不会补记,`read` 会直接报错提示你先 start。
92
+ - **含浏览器自己抛的消息**:资源加载失败、CSP 拦截、弃用警告——这些不是页面的 `console.*` 调用,任何「包装 `console`」的方案都拿不到。这也是这里用调试器而不是注入脚本的原因。
93
+ - **续读用游标**:`read` 返回 `cursor`,下次传 `since: cursor` 就只拿新增的,不会重复。
94
+ - **内存有硬上限,且与运行时长无关**:见下。
95
+
96
+ #### 采集占多少内存
97
+
98
+ | 界 | 值 |
99
+ | --- | --- |
100
+ | 单条文本 | 4096 字符(超出截断并标记) |
101
+ | 单标签页条数 | 200(环形,丢最旧) |
102
+ | 单标签页文本 | 256 KB 字符 |
103
+ | 同时采集的标签页 | 5(起第 6 个时释放最久未用的) |
104
+
105
+ **进程内上限 = 5 × 256 KB ≈ 1.25 MB(ASCII)~ 2.5 MB(中文)**,跑多久都是这个数——界是条数 + 字节数,**不是时间**。时间上界约束不了内存:一个 `while(true) console.log()` 两秒就能写出几十万条。
106
+
107
+ - 单条超大日志**不会冲掉整个缓冲**:只保留它的头部加截断标记。
108
+ - `read` 返回的 `dropped` 告诉你读之前淘汰了多少条,避免把「最近 200 条」误当成全部。
109
+ - **不落盘**:缓冲只在宿主进程内存里,不写会话日志。只有模型显式 `read` 回来的内容才会进入对话记录——和 `chrome_read` 的暴露面一样。
110
+ - `stop`、插件卸载、标签页关闭都会释放缓冲。
111
+
112
+ #### 采集的代价
113
+
114
+ 扩展后端用 `chrome.debugger` 附着到被采集的那个标签页,所以**只有那一个标签页顶部会出现 Chrome 的「已开始调试此浏览器」提示条**,`stop` 后消失。模型不会对你没让它采集的标签页这么做。
115
+
116
+ CDP 后端不涉及扩展,直接在一次长驻 CDP 会话上订阅事件。
117
+
118
+ > ⚠️ **升级到本版本后必须重新加载扩展**(`chrome://extensions` → 重新加载)。扩展新增了 `debugger` 权限,Chrome 不会自动授予。
119
+
120
+
121
+ ### 交互原语:wait / hover / press / select
122
+
123
+ **`chrome_wait`** —— 现代页面是异步渲染的,「读完再点」会读到还没出现的元素。之前只能自己用 `chrome_eval` 轮询,现在:
124
+
125
+ ```
126
+ chrome_wait { selector: '#result', state: 'visible', timeoutMs: 10000 }
127
+ ```
128
+
129
+ | `state` | 含义 |
130
+ | --- | --- |
131
+ | `visible`(默认) | 存在、有布局盒、且不是 `display:none` / `visibility:hidden` |
132
+ | `hidden` | 不存在,或不可见 |
133
+ | `attached` / `detached` | 只看存在性,不看可见性 |
134
+
135
+ - **`satisfied: false` 表示「超时了」,不是「成功了」** —— 用它之前先看这个字段。
136
+ - 每 100ms 轮询一次;上界默认 10000ms、最大 300000ms。
137
+ - 后端无关:CDP 用一条会话轮询,扩展桥走既有的 `eval` 通道。
138
+
139
+ **`chrome_hover`** —— 展开只在悬停时出现的菜单、工具条、操作行:
140
+
141
+ ```
142
+ chrome_hover { selector: '#row-menu' }
143
+ ```
144
+
145
+ - 事件是**合成的**:会送达页面挂的监听器,但**不会设置浏览器自身的 hover 状态**——纯靠 CSS `:hover` 规则显示的元素可能仍然不出现。两个后端行为一致(扩展桥拿不到真实指针输入)。
146
+ - 典型用法:`chrome_hover` → `chrome_read { mode: 'interactive' }` 看展开了什么。
147
+ - 选择器没有匹配时直接抛错,不返回假的成功。
148
+
149
+ **`chrome_press`** —— 按键:
150
+
151
+ ```
152
+ chrome_press { key: 'Enter', selector: '#search' } // 先聚焦再按
153
+ chrome_press { key: 'Escape' } // 按在当前焦点上
154
+ ```
155
+
156
+ - 合成键盘事件**不触发浏览器的默认行为**:输入框里按 Enter 既不会插入换行也不会提交表单。所以表达式在按下后**显式调用所属表单的 `requestSubmit()`**,并把这件事报成 `submitted: true`。
157
+ - 同时带上 `keyCode`(13/27/9/方向键…),因为仍有库在读这个废弃字段。
158
+ - 三个事件 `keydown` / `keypress` / `keyup` 都会派发。
159
+ - 聚焦 `Tab`、关闭浮层的 `Escape` 会让页面自己处理,`submitted` 保持 `false`。
160
+
161
+ **`chrome_select`** —— 下拉选择,按 **option 的 `value`** 而不是显示文本:
162
+
163
+ ```
164
+ chrome_select { selector: '#country', value: 'CA' }
165
+ ```
166
+
167
+ - 通过**原型 setter** 设值并派发 `input` + `change`,所以受控组件会更新。
168
+ - **值不存在时不报成功**:直接抛错并列出可用值 —— `has no option with value "XX"; available values: US, CA`。
169
+ - 目标不是 `<select>` 时明确说明,并指向 `chrome_type` / `chrome_click`。
170
+
171
+ ### chrome_request_help:撞到登录墙时停下来问人
172
+
173
+ ```
174
+ chrome_request_help { reason: '请在打开的 example.com 页面里登录,然后选「已完成,继续」' }
175
+ ```
176
+
177
+ 模型撞到登录页/验证码/二次验证时,**之前只能干瞪眼或者乱试**。现在它会停下来问你,并在你答复后继续。
178
+
179
+ | 返回 | 含义 |
180
+ | --- | --- |
181
+ | `completed: true` | 你已经做完了 → 模型应**重新读一次页面**再决定下一步 |
182
+ | `completed: false` | 你选了「跳过」,或直接关掉了提问 → 模型**停止这条路径**,不要反复重试 |
183
+ | `note` | 你补充的说明(如果有) |
184
+
185
+ - 问题只给**两个**选项,所以**空答复或未知答复一律算「没完成」**——不会把「用户没回答」读成「用户同意了」。
186
+ - 走 DSH 的 `ctx.userQuestions` 服务。**宿主没有这个服务时**(精简组合、或被委派的子 agent 调用),工具会明确报错说明无法联系用户,而不是假装成功或挂住。
187
+ - 委派的子 agent 提问会被告知「子 agent 没有人工应答者」,这是宿主的策略,插件不绕过。
188
+
189
+ ### 活动状态条:让用户看见 Agent 在干什么
190
+
191
+ 插件在你的浏览器里操作时,**DSH 界面里原本没有任何指示**——用户只能盯着自己的页面看它自己变化。
192
+
193
+ 现在输入框上方会出现一条状态条,**只在真的有工具在跑时**出现:
194
+
195
+ ```
196
+ ● 🟢 点击 标签页 7
197
+ ```
198
+
199
+ - **空闲时完全不渲染**——常驻徽章是噪音,而每次调用的细节已经在对话里的工具卡片上。
200
+ - 数据来自插件自己的 `GET /chrome-browser/activity?sessionId=…`:`ctx.tools.register` 的每个定义都被包了一层,执行期间登记、结束即释放。
201
+ - 客户端每秒探一次(走 900ms 缓存),因此**每个打开的会话视图**都有一条本地回环 GET。宿主不可达时状态条保持隐藏,不闪错误。
202
+ - `chrome_request_help` 在跑时显示「等待你操作」——这正是需要用户抬头的时刻。
203
+ - 状态**不落盘、不进模型请求**:它只影响界面。
18
204
 
19
205
  ## 浏览器连接模式
20
206
 
21
207
  **默认 = 扩展后端(推荐)**:控制的就是你**日常运行的 Chrome 本身**——不重启、不复制 profile、无额外窗口。扩展的获取与加载步骤见[安装 → 2. 装配套 Chrome 扩展](#2-装配套-chrome-扩展)。
22
208
 
23
- 改了 `extension/` 里的文件后,必须在 `chrome://extensions` 点该扩展的「重新加载」才会生效——Chrome 不会自动重读已加载的解压扩展。
209
+ 改了 `extension/` 里的文件后,**从 0.5.0 起插件会自己让扩展重载**——见下。
210
+
211
+ ### 扩展的自动更新
212
+
213
+ Chrome 不会重读「加载已解压」扩展的文件,所以插件自己补了一条握手:
214
+
215
+ 1. 扩展连上时(以及每 20 秒一次心跳)自报三样东西:「**自己这份代码的指纹**」(`BUILD_HASH`,一个烤进 service worker 的常量)、`manifest.version`、以及它能处理的 op 列表;
216
+ 2. 宿主对**包内 `extension/` 的文件**算出同样的指纹(文件名 + `0x00` + 内容,按名排序);
217
+ 3. 不一致且扩展支持 `reload` → 宿主请它 `chrome.runtime.reload()`,Chrome 从磁盘重读,新代码生效。
218
+
219
+ **为什么指纹必须是常量,不能在扩展里现算**:实测过——`fetch(chrome.runtime.getURL(...))` 在 service worker 里读到的是**磁盘上的文件**,不是 Chrome 已加载的那份。运行时自算指纹会**每次都报新值**:宿主以为扩展是最新的,而用户实际跑着旧代码,毫无迹象。只有随着已加载代码一起被读出来的常量才能说明「现在跑的是哪份」。
220
+
221
+ 指纹由 `npm run extension:stamp` 写入;忘了盖章时 `tests/extension-package.spec.ts` 会直接失败,所以这不是一件需要记的事。**实测过 `chrome.runtime.reload()` 确实从磁盘重读**(不只是 manifest,service worker 也是),而 worker 被 Chrome 唤醒**不会**重读。
222
+
223
+ 于是 **npm 升级插件后不用再碰 `chrome://extensions`**。
224
+
225
+ - **同一个指纹只问一次**:如果某次 `reload` 没能读到新文件(比如目录被换掉),宿主不会反复重载——它会停下并在 `/chrome-browser/ext/status` 里报 `stale: true`、`autoReloadAsked: true`,此时需要手动重载一次。换了一个指纹(又一次升级)则会重新尝试,所以同一进程内的多次升级都能落地。
226
+ - **能力检查**:宿主只会发扩展自报支持的 op。扩展文件比插件旧时直接报「扩展不支持 X,请在 chrome://extensions 重新加载该扩展」,而不是让扩展回一个 `unknown op` 这种看不出原因的内部错误。
227
+ - **首次安装仍需手动**:Chrome 没有以编程方式安装解压扩展的接口,新用户在 `chrome://extensions` 加载一次是绕不过去的(除非上架 Chrome 应用商店)。
24
228
 
25
229
  之后扩展通过本地 WebSocket(`/chrome-browser/ext/ws`)与插件通信:列真实标签页(自带站点图标)、读取/点击/输入/求值/导航/新开/截图。扩展没连上时 `@` 菜单不出现标签页分组,`/chrome-browser/ext/status` 会报 `connected:false`。
26
230
 
@@ -112,21 +316,29 @@ $DSH_HOME/profiles/<profile>/node_modules/@liyuera/dsh-chrome-browser/extension/
112
316
 
113
317
  模型可见的输入/输出只有八个工具 JSON 结果,加上被引用标签页的上下文:每次 `chrome_read` 最多携带约 `readTextLimit` 字符的页面文本;`chrome_screenshot` 只返回文件路径与元数据,页面视觉内容需通过 `read_image` 再读取;`chrome_eval` 结果上限 200k 字符。从 `@` 菜单选中标签页时,客户端在草稿里插入一个引用芯片,它序列化成 `@"标题"`——用户消息里只有这个引用(宿主按文本形状投影成引用芯片),宿主随后在用户消息后注入一条本插件的上下文消息(`## Referenced Chrome tabs`),逐个列出被引用标签页的 `tabId` 与 URL,模型照着 id 调 `chrome_*` 即可。同名标签页会列出全部候选并提示向用户确认;引用没有匹配到任何在开的标签页(已关闭,或那其实是带空格的文件路径)时不注入任何东西。插件不做会话级标签页绑定,一次选择只影响它所在的那条消息。本插件不发任何 provider 请求,无 LLM/KV-cache 影响。
114
318
 
319
+ 工具卡片与并发分类是**宿主 + 客户端**的呈现信息,不进入模型请求:模型拿到的是与以前逐字节相同的八个工具 JSON 结果与同一组 tool schema。skill 正文只在被调用时加载,目录里常驻的只有一行 description。
320
+
115
321
  ## 开发
116
322
 
117
323
  ```sh
118
324
  npm install --no-save --legacy-peer-deps # 首次:本地 react/@types 供客户端构建
119
325
  npm run build # tsc -b --force + tsdown(客户端 bundle 到 lib/client.js)
120
326
  npx vitest run # 单测
327
+ npm run typecheck:tests # 类型检查 src + tests
121
328
  DSH_CHROME_SMOKE=1 npx vitest run tests/smoke.spec.ts # headless Chrome 全链路 + user 模式路径
122
329
  ```
123
330
 
124
331
  构建产物 `lib/`(含 `lib/client.js` 浏览器 bundle)提交进本仓库,安装即用,无需在目标机器构建。
125
332
 
333
+ **为什么需要 `typecheck:tests`**:`tsc -b` 只编译 `src`,而 vitest 只转译不做类型检查——所以测试里的假实现和真实接口漂移**不会报错**,只在某个用例恰好走到那条路径时才炸。这个检查已经抓到过:假后端漏了新增的接口方法、路由改了参数个数但调用点没跟上、`fakeProc` 定义在别的 `describe` 里(闭包捕获了名字却从未被调用,于是用例一直「通过」)。它只看本包的诊断——`paths` 别名会把 harness 其他项目的源码拉进同一个程序,那些错误属于它们自己的构建。
334
+
126
335
  ## Known Limitations and Deferred Work
127
336
 
128
- - **composer 上方的标签页选择框已停用**:`@` 分组取代了它。组件与注册代码都留在原处(`src/client/TabPicker.tsx` 与 `src/client/index.ts` 的 `TAB_PICKER_VISIBLE`),把常量改成 `true` 即恢复那一行。
129
- - **选中标签页只插入一个引用,不做会话绑定**:`chrome_*` 省略 `tabId` 时不会自动落到这个标签页(原来的 `/chrome-browser/select` 绑定路由仍在,但已无调用方);模型用的是注入上下文里的 `tabId`。
337
+ - **`@` 菜单插入的是引用,不是绑定**:选中一个标签页只插入引用芯片,**不绑定会话**,
338
+ 所以没有「本会话选中的标签页」这回事。`chrome_*` 省略 `tabId`(或写 `active`)时用的是
339
+ **用户当前正在看的那个标签页**——用户明确指定页面时不要省略,模型应当用注入上下文里的 `tabId`。
340
+ (原先的 `TabPicker` 组件、`SessionBindings` 与 `/chrome-browser/select`、`/chrome-browser/state`
341
+ 两个路由只服务于这条已废弃的绑定,已一并删除。)
130
342
  - **引用靠标题匹配**:注入的上下文按 `@"标题"` 去实时标签页里找同名标签页,同名多个时列出全部候选让模型确认;发送前被关掉的标签页不注入上下文(引用仍在,但模型需要自己调 `chrome_tabs`)。
131
343
  - **消息里的引用芯片由宿主按文本形状投影**:`@"名字"` 在宿主的消息投影(`projectUserText`)里是"文件型"引用——带文件图标,且在传了 `openFile` 的页面上可点击,点击会走宿主「打开文件」流程(找不到同名文件会报错)。这是宿主对任何 `@名字` 文本的通用规则,插件层没有别的形状可选。
132
344
  - **带空格的文件引用与本插件的引用同形**:两者都是 `@"…"`;匹配不到任何在开的标签页时本插件不注入任何东西,所以不会污染文件引用的消息。
@@ -134,11 +346,25 @@ DSH_CHROME_SMOKE=1 npx vitest run tests/smoke.spec.ts # headless Chrome 全链
134
346
  - **Chrome 未连接时 `@` 分组不出现**:扩展未安装/未打开时列表抓取失败,只在控制台留一条记录,不占菜单空间;原因查询走 `/chrome-browser/ext/status`。
135
347
  - **owned 模式重启 dsh 后需首次调用恢复窗口**:专用 Chrome 的窗口在 dsh 重启后不会自动弹出,第一次使用工具/选择器时拉起(profile 持久化,标签页都在)。
136
348
  - **user 模式只支持手动带调试端口启动的 Chrome**:插件不自动接管、不重启;`autoRelaunch` 打开时仍建议先把 dsh 界面移到别的浏览器再使用。
137
- - **点击/输入是 DOM 事件 + CDP Input**:不模拟真实指针/MIME 手势,对依赖真实 pointer 事件或 iframe/shadow DOM 深层结构的页面不完全可靠;这些场景可用 `chrome_eval` 绕过。
349
+ - **点击/输入是 DOM 事件 + CDP Input**:不模拟真实指针/MIME 手势,对依赖真实 pointer 事件或 iframe/shadow DOM 深层结构的页面不完全可靠;这些场景可用 `chrome_eval` 绕过。`chrome_click` 已把「派发了但真实用户点不到」的情形报进 `warnings`,但**警告是启发式**:命中测试在 shadow DOM 内按元素自己的 root 进行,闭合 shadow root 与 iframe 内部无法判定。
350
+ - **等加载有上限,超时不报错**:`chrome_open` / `chrome_navigate` 默认等 `readyState=complete`,但最多等 `waitLoadMs`(默认 8000)。长轮询页面、挂住的资源不会等到底——到点就返回当前状态,由模型读一次再决定。要等**某个元素**出现就用 `chrome_wait`(同样超时不报错,靠 `satisfied` 判断)。
351
+ - **`chrome_hover` 是合成事件**:送达页面监听器,但不设置浏览器自身的 hover 状态,纯 CSS `:hover` 显示的元素可能仍不出现。
352
+ - **键盘、指针与下拉的保真度有上限**:`chrome_press` 的按键、`chrome_hover` 的指针、`chrome_select` 的赋值都是**合成事件**——送达页面监听器,但不产生浏览器默认行为。Enter 提交靠显式 `requestSubmit()` 兜底;依赖真实按键序列(组合键、输入法)或真实指针的组件仍可能不响应,这些场景退回 `chrome_eval`。
353
+ - **页面 CSP 会改变 `chrome_eval` 的执行通道**:`script-src` 里没有 `'unsafe-eval'` 的站点(GitHub 就是)主世界不能 `eval`,插件会自动改走 **`chrome.debugger` 的 `Runtime.evaluate`**(和 CDP 后端同一条路)并在结果里报 `world: "debugger"`。**代价是该标签页会出现调试提示条**,且已打开 DevTools 时无法附着——所以它只是回退,默认仍走无感的普通注入。
354
+ - **`chrome_eval` 的失败是错误,不是 `null`**:语法错误、运行时异常、CSP 拦截以前都会静默变成 `null`,现在会带着原始信息报错。
355
+ - **`chrome_open` 拒绝它驱动不了的 scheme**:`data:`、`chrome:`、`devtools:` 这类页面扩展注不进去,以前会**先把标签页建出来再失败**——那个标签页读不了、跑不了 JS、连导航走都不行。现在在创建前就报错,不留僵尸标签页。`file:` 可以开,但**它依赖一个浏览器设置**:扩展默认没有文件访问权限,要在 `chrome://extensions` 里为该扩展打开「允许访问文件网址」;没开的话 `file://` 页面会和 `data:` 一样读不到(本机已开启,实测 `chrome_open file://` + `chrome_read` 正常)。CDP 模式没有这个限制。
356
+ - **`about:blank` 只能开、不能导航过去**:扩展注不进空白页,所以空白标签页读不了、点不了、跑不了 JS。`chrome_open` 允许开一个(当**临时中转页**用,随后 `chrome_navigate` 走),并且**不会等它加载**(没东西可等);但 `chrome_navigate` 拒绝导航到 `about:blank`——那会丢弃页面上原有的内容,只剩一个谁也读不了的标签页。
357
+ - **`chrome_close` 不猜目标**:`tabId` 是必填的精确 id。省略或写 `active` 都会报错——关掉「用户当前正在看的标签页」几乎总是错的。关闭窗口的最后一个标签页会连带关闭该窗口。
358
+ - **扩展自动更新依赖 `chrome.runtime.reload()` 能读到磁盘上的新文件**:这是该 API 的预期行为,但已加载的解压扩展由 Chrome 缓存,所以插件**只尝试一次**并在失败时明确报告,而不是无限重载。状态见 `/chrome-browser/ext/status`。
359
+ - **`chrome_screenshot` 会在该标签页显示调试提示条**:它走 `chrome.debugger` 的 `Page.captureScreenshot`(与 CDP 后端同一条路),因此在标签页处于后台时照样可用,也**不会返回陈旧帧**。代价是 Chrome 在该标签页顶部显示「正在调试」提示条,且已打开 DevTools 时无法附着(会明确报错)。如果该标签页已被 `chrome_console` 采集,则复用同一会话,不产生第二次附着。
360
+ - ~~截图要求窗口可见~~:旧实现走 `chrome.tabs.captureVisibleTab`,窗口被遮挡时报 `image readback failed`,窗口停止重绘时**返回上一帧**(实测两张相隔数秒的截图逐字节相同,而返回的路径与字节数不会告诉你它是陈旧的)。已改为调试通道。
361
+ - **活动状态条是轮询的**:客户端每秒发一次本地回环 GET。将来若接入会话事件流可以去掉轮询,目前用的是插件已有的路由机制。
362
+ - **人工求助依赖宿主的提问服务**:`chrome_request_help` 在 `ctx.userQuestions` 缺席的组合、以及被委派的子 agent 里不可用(会明确报错)。
138
363
  - **文本读取只覆盖主框架**的 `innerText`(iframe 内容不在其中)。
139
- - 不暴露网络拦截、性能追踪、多窗口管理等更宽的 CDP 能力。
364
+ - **控制台采集会丢两类内容**:桥断开期间产生的消息直接丢弃(缓冲在宿主,收不到就没有);扩展 service worker 被 Chrome 挂起时采集会中断,重连后自动重新附着,但中断窗口内的消息不补。用 `dropped` 和「有没有 start 过」来判断你看到的窗口是否完整。
365
+ - 不暴露网络拦截(只有控制台里那部分错误文本)、性能追踪、多窗口管理等更宽的 CDP 能力。
140
366
  - 截图默认写入系统临时目录,随系统清理。
141
- - 每次工具调用为每个标签页新建一次 CDP 会话(约数十毫秒开销),未做连接复用;需要高频操作时可后续加常驻会话层。
367
+ - 每次工具调用为每个标签页新建一次 CDP 会话(约数十毫秒开销),未做连接复用;需要高频操作时可后续加常驻会话层。控制台采集是例外:它持有一条长驻会话。
142
368
  - 会话标签页绑定是内存态(重启后清空),不做持久化。
143
369
 
144
370
  ## 卸载
@@ -147,7 +373,7 @@ DSH_CHROME_SMOKE=1 npx vitest run tests/smoke.spec.ts # headless Chrome 全链
147
373
  dsh plugin --profile desktop remove @liyuera/dsh-chrome-browser
148
374
  ```
149
375
 
150
- 再到 `chrome://extensions` 移除 `dsh Chrome Bridge` 扩展。卸载插件不会关闭你的 Chrome(CDP 的 owned 专用实例除外)。
376
+ 再到 `chrome://extensions` 移除 `dsh Chrome Control` 扩展。卸载插件不会关闭你的 Chrome(CDP 的 owned 专用实例除外)。
151
377
 
152
378
  ## 许可
153
379
 
Binary file
Binary file
Binary file
Binary file
@@ -1,13 +1,14 @@
1
1
  {
2
2
  "manifest_version": 3,
3
- "name": "dsh Chrome Bridge",
4
- "description": "Bridges the local dsh agent to this Chrome instance: list tabs, read pages, click/type, run JS and capture screenshots. Runs on the machine only.",
5
- "version": "0.1.0",
3
+ "name": "dsh Chrome Control",
4
+ "description": "Lets the local dsh agent drive this Chrome: list tabs, read pages, click and type, run JS, capture screenshots, read console output. Talks to dsh on this machine only.",
5
+ "version": "0.3.0",
6
6
  "permissions": [
7
7
  "tabs",
8
8
  "scripting",
9
9
  "alarms",
10
- "storage"
10
+ "storage",
11
+ "debugger"
11
12
  ],
12
13
  "host_permissions": [
13
14
  "<all_urls>"
@@ -15,5 +16,11 @@
15
16
  "background": {
16
17
  "service_worker": "service-worker.js"
17
18
  },
18
- "minimum_chrome_version": "110"
19
+ "minimum_chrome_version": "110",
20
+ "icons": {
21
+ "16": "icons/icon-16.png",
22
+ "32": "icons/icon-32.png",
23
+ "48": "icons/icon-48.png",
24
+ "128": "icons/icon-128.png"
25
+ }
19
26
  }