dsh-builtin-browser 0.1.12 → 0.1.13

package/README.en.md

@@ -12,6 +12,16 @@
 
 <h4 align="center">The agent drives a real, visible browser the human can watch and take over at any time — both operate the <b>same page</b>.</h4>
 
+## Documentation
+
+| Goal | Entry |
+| --- | --- |
+| Why a shared real browser, and how it differs from headless approaches | [Why a shared real browser](docs/why-browser.md) |
+| Installation, configuration, day-to-day use | [User guide](docs/user-guide.md) |
+| All 20 tools: parameters, output, examples | [Tool reference](docs/tool-reference.md) |
+| How the seam / provider / tools layers and self-hosting work | [Architecture](docs/architecture.md) |
+| Documentation index and README split | [Docs index](docs/README.md) |
+
 ## What is this
 
 `dsh-builtin-browser` adds browser capability to [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness):

package/README.md

@@ -12,6 +12,16 @@
 
 <h4 align="center">agent 驱动一个真实、可见、可随时人工接管的浏览器——人与 agent 操作的是<b>同一个页面</b>。</h4>
 
+## 文档
+
+| 目标 | 入口 |
+| --- | --- |
+| 了解插件为什么存在、与无头方案的区别 | [为什么做共享真实浏览器](docs/why-browser.md) |
+| 安装、配置与日常使用 | [用户指南](docs/user-guide.md) |
+| 全部 20 个工具的参数、输出与示例 | [工具参考](docs/tool-reference.md) |
+| 了解 seam / provider / 工具三层与自托管实现 | [架构说明](docs/architecture.md) |
+| 查看全部文档与 README 分工 | [文档索引](docs/README.md) |
+
 ## 这是什么
 
 `dsh-builtin-browser` 给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供浏览器能力:

package/docs/README.md

@@ -0,0 +1,18 @@
+# dsh-builtin-browser 文档索引
+
+按"你想做什么"选择入口:
+
+| 目标 | 入口 |
+| --- | --- |
+| 了解插件为什么存在、与无头方案的区别 | [为什么做共享真实浏览器](why-browser.md) |
+| 安装、配置、日常使用与常见问题 | [用户指南](user-guide.md) |
+| 全部 20 个工具的参数、输出与示例 | [工具参考](tool-reference.md) |
+| 了解 seam / provider / 工具三层与自托管实现 | [架构说明](architecture.md) |
+| 回到项目首页 | [README](../README.md) |
+
+## 各篇概览
+
+- **[为什么做共享真实浏览器](why-browser.md)** — 定位、设计理念、与 Playwright 等无头方案的对比、边界与取舍。
+- **[用户指南](user-guide.md)** — 环境要求、安装、配置项、快速上手、操作纪律、FAQ 与故障排查。
+- **[工具参考](tool-reference.md)** — 每个 `browser_*` 工具的参数、输出、守卫与示例。
+- **[架构说明](architecture.md)** — 三层结构、`ElectronBrowserViewHost` 接缝、自托管 RPC 子进程、截图通道、Electron 版本选择。

package/docs/architecture.md

@@ -0,0 +1,75 @@
+# 架构说明
+
+## 三层结构
+
+```
+agent (browser_* 工具)
+  → ctx.browser (seam, dsh-builtin-browser/browser)
+  → dsh-builtin-browser/browser-electron (provider)
+  → ElectronBrowserViewHost (由宿主外壳提供)
+  → WebContentsView + webContents.debugger (CDP)
+```
+
+### seam 层(`src/browser/`)
+
+`BrowserRuntime` 以 Cordis Service 形式注册为 `ctx.browser`:
+
+- **provider 注册**:`registerBrowserProvider(provider)` 登记一个实现 `BrowserProvider` 接口的 provider,重名抛 `BROWSER_DUPLICATE_PROVIDER`;disposer 挂在注册方自身的 fiber 上,插件重载时正确清理。
+- **provider 选择**(执行期解析,不依赖顺序):
+  - 配置了 id 且注册且可用 → 该 provider
+  - 配置了 id 但未注册 → `BROWSER_PROVIDER_CONFIGURED_MISSING`
+  - 配置了 id 但不可用 → `BROWSER_PROVIDER_CONFIGURED_UNAVAILABLE`
+  - 未配置、恰一个可用 → 自动选择
+  - 未配置、多个可用 → `BROWSER_PROVIDER_AMBIGUOUS`
+  - 未配置、无可用 → `BROWSER_PROVIDER_UNAVAILABLE`
+- 所有请求/结果类型(`BrowserProvider` 接口、`BrowserError` 错误码)定义在 `src/browser/types.ts`。
+
+### provider 层(`src/browser-electron/`)
+
+`ElectronBrowserProvider` 通过 `ElectronBrowserViewHost` 接缝操作视图,与 Electron 解耦:
+
+- 会话 = 有序标签列表 + 历史;每次 `open()` 新建会话(工具层按任务缓存复用);
+- 每个标签对应一个视图(handle);`showActive` 让宿主把活动标签的视图置顶;
+- 页面驱动全部走 CDP:`Page.navigate` / `Runtime.evaluate` / `Input.dispatchMouseEvent` / `Input.insertText` / `Page.captureScreenshot`(兜底);
+- **截图优先走宿主原生 `capturePage`**(新增 `capture` 通道):CDP `captureScreenshot` 在窗口存在多个(隐藏)视图时会挂起,原生捕获对可见视图快速可靠,失败时自动回退 CDP(临时摘除其他视图保证单视图状态);
+- 所有 CDP 调用都有超时兜底(`withTimeout`),避免卡死工具调用;
+- 历史记录单调递增的 seq,截断(500 条)后不回绕;失败导航只记一条。
+
+### 工具层(`src/tool-browser/`)
+
+20 个 `browser_*` 工具,按**调用方任务**(`exec.agent.id`)维护独立浏览器会话:
+
+- 会话缓存 `sessionsByTask`:同一任务复用同一会话,并发首开去重;
+- `browser_reset_session` 关闭本任务会话并遗忘映射(即使 close 抛错也清除,下次调用重建);
+- `browser_restrict` 维护模块级白名单,守卫所有非只读工具;
+- 输出 schema 与返回值严格一致(DSH 运行时会校验,`additionalProperties: false` 下多一个字段都会报错)。
+
+## 自托管实现(纯 `dsh web`)
+
+没有桌面外壳时,`RemoteElectronViewHost` 接管:
+
+```
+父进程(DSH)                        子进程(Electron main)
+RemoteElectronViewHost  ──TCP JSON-RPC──▶  host-main.js
+  resolveElectronPath()                    BrowserWindow('dsh-browser')
+  ElectronChildClient                      WebContentsView × N
+  DeferredRemoteView(物化缓存)              webContents.debugger(CDP)
+```
+
+- **协议**:本机 loopback TCP,每行一个 JSON(`{ id, op, ... }` ↔ `{ id, ok, result|err }`);
+- **Electron 定位**:① peer 依赖 → ② `ELECTRON_PATH` → ③ 锚点与 pnpm store 中**版本最新**者(33.x 有合成器缺陷,建议 ≥ 40);
+- **稳健性**:子进程/套接字都有 `error` 监听(否则未捕获事件会炸掉整个 DSH 进程);子进程退出自动重启;物化失败可重试;下载有 256MB 上限与 60s 超时;cookie 导出/恢复有 30s 超时;
+- **视图可见性**:多标签/多会话时,`showView` 隐藏其他视图并把目标视图置顶(remove+re-add),确保用户看到的是活动标签;
+- **孤儿防护**:父进程断开时子进程自动退出,不留僵尸窗口;
+- **cookie 落盘**:子进程使用独立 userData 目录(`<DSH_HOME>/dsh-builtin-browser-host`),登录态跨重启保留(另有 `browser_auth` 手动导出/恢复)。
+
+## 关键设计决策
+
+| 决策 | 原因 |
+| --- | --- |
+| 任务级会话隔离,共享 cookie | 并行任务不抢页面;登录一次到处可用 |
+| 原生 capturePage 优先,CDP 兜底 | CDP 截图多视图挂起;原生捕获窗口未激活时失败——两通道互补 |
+| 自动选最新 Electron | 33.x 合成器缺陷导致截图间歇失败 |
+| 独立 userData | 多实例争用默认目录导致 GPU 缓存/会话锁冲突 |
+| withTimeout 全覆盖 | 卡死的 CDP 调用必须能被工具超时兜底 |
+| 输出 schema 严格匹配 | DSH 运行时会校验返回值,多字段即报错 |

package/docs/tool-reference.md

@@ -0,0 +1,82 @@
+# 工具参考
+
+全部 20 个 `browser_*` 工具。守卫列:✅ 表示该动作受 `browser_restrict` 白名单约束;只读工具永不拦截。
+
+## 页面与导航
+
+| 工具 | 参数 | 输出 | 守卫 | 说明 |
+| --- | --- | --- | --- | --- |
+| `browser_open` | `url`(必填), `newTab?` | 快照(url/title/elements/truncated/challenge) | ✅ | 打开 URL,返回带编号元素的快照;`newTab: true` 在新标签打开 |
+| `browser_snapshot` | – | 快照 | – | 交互元素(输入框/按钮/链接)编号清单,供定位与点击 |
+| `browser_content` | `format`(html/markdown/txt/json,必填), `selector?`, `maxChars?`, `timeoutMs?` | `{ content, truncated }` | – | 抓取页面内容;`selector` 限定区域 |
+| `browser_challenge` | – | `{ blocked, kind?, reason?, hint? }` | – | 检测人机验证(CAPTCHA/Cloudflare/reCAPTCHA/hCaptcha/Turnstile);阻塞时请用户处理 |
+
+## 页面操作
+
+| 工具 | 参数 | 输出 | 守卫 | 说明 |
+| --- | --- | --- | --- | --- |
+| `browser_execute` | `script`(必填), `args?` | `{ ok, value? / exception? }` | ✅ | 在页面执行 JS;脚本以 `return` 开头或作为表达式;`args` 以 `arguments[0..n]` 传入 |
+| `browser_click` | `x`, `y`(必填) | `{ clicked }` | ✅ | 视口坐标点击(配合截图做视觉定位) |
+| `browser_type` | `text`(必填) | `{ typed }` | ✅ | 向聚焦元素输入文本(CDP `Input.insertText`) |
+| `browser_fill` | `fields`(必填,数组), `submit?` | `{ fields[], submitted }` | ✅ | 批量填表;字段按 `selector`/`name`/`label`/`placeholder` 匹配,值支持字符串/数字/布尔;单个字段失败不影响其余;`submit: true` 提交表单 |
+
+## 标签与会话
+
+| 工具 | 参数 | 输出 | 守卫 | 说明 |
+| --- | --- | --- | --- | --- |
+| `browser_list_tabs` | – | `{ session, tabs[] }` | – | 当前会话的标签列表 |
+| `browser_switch_tab` | `tabId`(必填) | `{ switched }` | ✅ | 按 id 切换标签;自托管下同步切换可见视图 |
+| `browser_close_tab` | `tabId`(必填) | `{ closed }` | – | 关闭标签;关闭活动标签后激活下一个 |
+| `browser_reset` | – | `{ reset }` | ✅ | 关闭本任务所有标签,回到一个空白标签 |
+| `browser_session` | – | `{ session, tabs[] }` | – | 查看本任务的浏览器会话与标签 |
+| `browser_reset_session` | – | `{ reset }` | ✅ | 关闭并重建本任务的浏览器会话(崩溃/卡死后恢复) |
+
+## 历史与下载
+
+| 工具 | 参数 | 输出 | 守卫 | 说明 |
+| --- | --- | --- | --- | --- |
+| `browser_history` | – | `{ entries[] }` | – | 操作日志(最新在后),含 seq/action/ok/params/result/error |
+| `browser_replay` | `seq`(必填) | `{ replayed }` | ✅ | 按序号回放某一步(navigate/execute/click/type) |
+| `browser_download` | `url`(必填), `savePath`(必填) | `{ path }` | ✅ | 带会话 cookie 下载到本地(上限 256MB,受 CORS 约束) |
+
+## 登录态与安全
+
+| 工具 | 参数 | 输出 | 守卫 | 说明 |
+| --- | --- | --- | --- | --- |
+| `browser_auth` | `action`(flush/restore,必填), `cookies?` | `{ cookies[]? / restored? }` | ✅ | 导出/恢复 cookie(自托管可用);flush 返回 cookie 列表,restore 带列表写回 |
+| `browser_restrict` | `allowed?` | `{ restrictedTo[] }` | – | 设置动作白名单;空列表解除;未知工具名报错 |
+
+## 截图
+
+| 工具 | 参数 | 输出 | 守卫 | 说明 |
+| --- | --- | --- | --- | --- |
+| `browser_screenshot` | `fullPage?`, `savePath?` | `{ dataUrl, path? }` | – | PNG 截图;`savePath` 落盘供视觉模型读取 |
+
+## 常用组合
+
+**调研一个网站**
+```
+browser_open https://site → browser_content format=markdown → browser_snapshot → 逐页浏览
+```
+
+**登录并下载文件**
+```
+browser_open https://site/login → browser_fill(用户名/密码) submit=true →
+等待跳转 → browser_download(url, savePath)
+```
+
+**表单填写(React/Vue 页面)**
+```
+browser_snapshot → browser_fill(fields=[{name:'email',value:'a@b.c'},{label:'密码',value:'***'}], submit=true)
+```
+
+**误操作恢复**
+```
+browser_reset_session → browser_open(重新开始)
+```
+
+**遇到验证码**
+```
+browser_challenge → 阻塞 → 提示用户:"页面出现人机验证,请在共享浏览器窗口完成,完成后告诉我" →
+browser_snapshot 复查
+```

package/docs/user-guide.md

@@ -0,0 +1,94 @@
+# 用户指南
+
+## 环境要求
+
+- DeepSeek Harness(dsh)且安装了 `web` profile
+- **Electron 运行时**(可选 peer 依赖):桌面外壳自带;纯 `dsh web` 下插件自动定位 Electron 二进制(建议 ≥ 40,33.x 存在截图合成器缺陷)
+
+## 安装
+
+```sh
+# 从 npm 安装(已发布)
+dsh plugin --profile web add dsh-builtin-browser
+
+# 或从源码目录(独立仓库,一插件一仓库)
+dsh plugin --profile web add <本仓库路径>
+```
+
+安装会链接插件、把 `dsh-builtin-browser` 加入 profile 的 bundle 层,并挂载三行:
+
+| 行 | 子路径 | 角色 |
+| --- | --- | --- |
+| `browser` | `dsh-builtin-browser/browser` | `ctx.browser` 能力 seam(始终挂载) |
+| `browser-electron` | `dsh-builtin-browser/browser-electron` | Electron CDP provider |
+| `tool-browser` | `dsh-builtin-browser/tool-browser` | `browser_*` 模型侧工具 |
+
+> 没有桌面外壳时插件**自托管**:自己拉起一个标题为 `dsh-browser` 的 Electron 窗口,`browser_*` 工具照常可用。
+
+## 配置
+
+| 行 | 配置项 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| `browser-electron` | `viewHost` | 对象 | 必填 | 宿主提供的 `ElectronBrowserViewHost`(通常 `!!js ctx.get('electronViewHost')`) |
+| `browser-electron` | `httpOnly` | 布尔 | `true` | 仅允许 HTTP(S) 导航;`file:`/`data:` 等拒绝 |
+| `browser-electron` | `snapshotMaxElements` | 数字 | `60` | 快照最多收录的交互元素数 |
+| `browser-electron` | `contentMaxChars` | 数字 | `100000` | 内容抓取默认字符上限 |
+| `tool-browser` | `timeoutMs` | 数字 | `60000` | 工具协作超时(ms) |
+| `tool-browser` | `tabTools` | 布尔 | `true` | 是否注册标签管理工具 |
+
+## 快速上手(给 agent 的提示词示例)
+
+```
+1. browser_open 打开 https://example.com
+2. browser_snapshot 查看页面有哪些可交互元素(带编号)
+3. 需要填表时用 browser_fill(按 name/label/placeholder 匹配,一次填多个字段)
+4. 需要截图确认时用 browser_screenshot(可 savePath 存文件)
+5. 遇到验证码(browser_challenge 或快照标注 CHALLENGE)时,停下请用户处理
+6. 每次操作后告知用户你在页面上做了什么
+```
+
+## 操作纪律
+
+- **优先用 DOM 语义而非坐标**:表单提交优先 `form.requestSubmit()`;点击优先 `element.click()`;坐标点击是最后手段。
+- **选中正确的元素**:页面常有隐藏副本(如移动端按钮),用 `browser_execute` 过滤可见元素(`getBoundingClientRect()` 宽高 > 0、`getComputedStyle` 非 `display:none`),再取坐标。
+- **取坐标后立即点击**:中间不要插入其他操作(填表、滚动会移动元素,旧坐标立即失效)。
+- **点击前验证命中**:`document.elementFromPoint(x, y)` 确认该坐标确实是目标元素,再执行真实点击。
+- **DPR 注意**:CDP 输入使用 CSS 像素;高 DPI 屏上若点击落空,用 `elementFromPoint` 校准,不要盲试坐标。
+
+## 多任务并行
+
+每个 DSH 会话(任务)拥有独立的浏览器会话(独立标签页与历史),并发任务互不干扰:
+
+- `browser_session` 查看本任务的会话与标签;
+- `browser_reset_session` 关闭并重建本任务的会话(崩溃或卡死后用它恢复)。
+
+登录态(cookie)为所有任务共享;可用 `browser_auth` 导出/恢复,重启后不丢。
+
+## FAQ
+
+**Q:纯 `dsh web` 能用吗?**
+能。插件自托管:自己拉起 Electron 窗口,无需桌面外壳。
+
+**Q:找不到 Electron?**
+插件按顺序自动定位:① peer 依赖 `require('electron')` → ② `ELECTRON_PATH` 环境变量 → ③ DSH 锚点与 pnpm 虚拟仓库中版本最新者。都找不到时报清晰错误,可 `dsh plugin --profile web add electron` 或设置 `ELECTRON_PATH`。
+
+**Q:截图失败或挂起?**
+确保 Electron ≥ 40(33.x 有合成器缺陷)。自托管截图优先走原生 `capturePage`,多视图/窗口未激活时自动兜底到 CDP。
+
+**Q:浏览器窗口不见了?**
+窗口标题为 `dsh-browser`(自托管)。若子进程崩溃会自动重启;重启后旧会话失效,调用 `browser_reset_session` 重建。
+
+**Q:下载报 CORS 错误?**
+`browser_download` 在页面上下文内 `fetch`,受同源/CORS 约束;跨域文件请先在同源页面内操作,或直接请求用户提供。
+
+**Q:如何禁止 agent 乱点?**
+`browser_restrict` 设置白名单(如只允许 `browser_snapshot`/`browser_content`);传空列表解除。
+
+## 故障排查
+
+| 现象 | 可能原因 | 处理 |
+| --- | --- | --- |
+| `BROWSER_SESSION_UNKNOWN` | 子进程重启后旧会话失效 | `browser_reset_session` |
+| 工具超时 | 页面卡死/未渲染完成 | 稍后重试;`browser_reset` 重置标签 |
+| 导航被拒 | 非 HTTP(S) 协议 | 检查 URL;`httpOnly` 配置 |
+| 快照为空 | 页面尚未加载 | 等待后重试 `browser_snapshot` |

package/docs/why-browser.md

@@ -0,0 +1,45 @@
+# 为什么做共享真实浏览器
+
+## 问题
+
+LLM agent 需要"上网"。传统做法是给 agent 一个**无头浏览器**(Playwright/Puppeteer 等)或**网页抓取工具**:
+
+- 无头浏览器:agent 在看不见的页面里操作,用户无法确认它在做什么,也无法中途接管;遇到登录、验证码、人机检测时寸步难行。
+- 网页抓取:只能读不能交互,且大量现代网站依赖 JS 渲染,抓到的内容失真。
+
+这两条路都绕开了"用户"——浏览器成了 agent 的私有工具,而不是用户和 agent 共用的工具。
+
+## 方案:共享真实浏览器
+
+`dsh-builtin-browser` 的思路很朴素:**让 agent 驱动用户眼前那个真实的浏览器窗口**。
+
+- 浏览器是原生 `WebContentsView`,用户直接看到 agent 的每一步操作(打开页面、填写表单、点击、滚动);
+- 用户**随时可以上手接管**:输入、点击、登录、过验证码——做完之后 agent 继续;
+- agent 通过 CDP 在同一个页面里执行 JS,拿到的是与用户所见完全一致的真实 DOM。
+
+一句话:浏览器不是 agent 的"黑盒工具",而是**用户与 agent 之间的共享工作台**。
+
+## 与无头方案的能力对比
+
+| 能力 | 无头浏览器 | 网页抓取 | 本插件(共享真实浏览器) |
+| --- | --- | --- | --- |
+| 真实页面渲染 | ✅ | 部分 | ✅ |
+| 复杂交互(填表/点击/拖拽) | ✅ | ❌ | ✅ |
+| 用户可见、可接管 | ❌ | ❌ | ✅ |
+| 保留登录态 | 需手动管理 | ❌ | ✅(`browser_auth` + cookie 落盘) |
+| 人工处理验证码 | ❌ 卡死 | ❌ | ✅ 请用户点一下即可 |
+| 多任务并行 | 需多实例 | – | ✅ 任务级会话隔离 |
+
+## 设计取舍
+
+- **登录态共享**:所有任务共享同一份 cookie(符合"用户登录一次,agent 到处可用");需要隔离时用 `browser_auth` 手动导出/恢复。
+- **任务级会话隔离**:每个 DSH 会话(任务)拥有独立的浏览器会话(标签页与历史),并发任务互不抢页面;但窗口只有一个,当前活动的任务视图可见。
+- **装好即用**:不依赖桌面外壳。有外壳时嵌入外壳视图;纯 `dsh web` 时插件自托管——自己拉起 Electron 窗口,通过本机 TCP JSON-RPC 驱动。
+- **边界清晰**:可见视图、浏览器列布局属于宿主外壳;插件只负责 seam、provider 与工具,不含任何 UI。
+- **人机验证不硬刚**:检测到 Cloudflare/reCAPTCHA/hCaptcha/Turnstile 时停下,请用户在共享窗口人工完成,而不是盲目重试。
+
+## 什么场景不适合
+
+- 需要**无头批量抓取**(成千上万页面):请用专门的抓取工具/服务,不必开窗口。
+- 需要**每个任务完全独立的登录态**(互不可见):本插件默认共享 cookie;如需强隔离,可用多个 DSH 实例或 `browser_auth` 手动管理。
+- 需要**浏览器列 UI / 布局管理**:那是宿主外壳的配套,本插件不包含。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Shared real browser plugin for DeepSeek Harness: install-and-use — a visible native browser the human can take over, driven by the agent over CDP. DOM-level interaction (React/Vue safe), per-task session isolation, cookie persistence (browser_auth), CAPTCHA detection, batch form fill (browser_fill), authenticated download, history/replay, action restriction",
   "type": "module",
   "main": "lib/index.js",
@@ -31,6 +31,7 @@
   "files": [
     "lib",
     "src",
+    "docs",
     "cordis.patch.yml",
     "README.md",
     "README.en.md",