dsh-builtin-browser 0.4.6 → 0.4.8

package/docs/user-guide.md

@@ -24,9 +24,9 @@ dsh plugin --profile web add <本仓库路径>
 | `dsh-builtin-browser` | 包名本身 | **惰性根行**:不注册任何东西(空 `apply()`),只用来声明包名 —— 宿主的客户端插件扫描靠精确包名读到 `dsh.client`,少了这行设置栏不会出现 |
 | `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_*` 模型侧工具 |
+| `tool-browser` | `dsh-builtin-browser/tool-browser` | `dsh_browser_*` 模型侧工具 |
 
-> 没有桌面外壳时插件**自托管**:自己拉起一个标题为 `dsh-browser` 的 Electron 窗口,`browser_*` 工具照常可用。
+> 没有桌面外壳时插件**自托管**:自己拉起一个标题为 `dsh-browser` 的 Electron 窗口,`dsh_browser_*` 工具照常可用。
 
 ## 配置
 
@@ -36,20 +36,20 @@ dsh plugin --profile web add <本仓库路径>
 | `browser-electron` | `httpOnly` | 布尔 | `true` | 仅允许 HTTP(S) 导航;`file:`/`data:` 等拒绝 |
 | `browser-electron` | `snapshotMaxElements` | 数字 | `60` | 快照最多收录的交互元素数 |
 | `browser-electron` | `contentMaxChars` | 数字 | 未设置(按格式分档) | 内容抓取的字符上限。**不设**时按格式取分档默认(html 50 000、json 50 000、txt 20 000、markdown 20 000);**设了**就是操作者的值,覆盖分档默认。单次调用的 `maxChars` 优先级最高 |
-| `browser-electron` | `downloadDir` | 字符串 | 系统下载目录(自动识别 `Downloads`/`下载`/`下載`,或 `XDG_DOWNLOAD_DIR`) | 限定 `browser_download` 与 `browser_screenshot` 保存路径必须位于该目录内且不覆盖已有文件;默认收敛到系统下载目录,可改沙箱目录 |
+| `browser-electron` | `downloadDir` | 字符串 | 系统下载目录(自动识别 `Downloads`/`下载`/`下載`,或 `XDG_DOWNLOAD_DIR`) | 限定 `dsh_browser_download` 与 `dsh_browser_screenshot` 保存路径必须位于该目录内且不覆盖已有文件;默认收敛到系统下载目录,可改沙箱目录 |
 | `tool-browser` | `timeoutMs` | 数字 | `60000` | 工具协作超时(ms) |
 | `tool-browser` | `tabTools` | 布尔 | `true` | 是否注册标签管理工具 |
-| `tool-browser` | `allowedActions` | 字符串数组 | 不限制 | **部署级**动作白名单,对该部署里的每个任务生效(单个任务仍可用 `browser_restrict` 再收窄);`READ_ONLY_TOOLS` 与 `browser_restrict` 无论列表怎么写都不拦。`cordis.patch.yml` 默认给的是空 `config: {}`(等于不限制) |
+| `tool-browser` | `allowedActions` | 字符串数组 | 不限制 | **部署级**动作白名单,对该部署里的每个任务生效(单个任务仍可用 `dsh_browser_restrict` 再收窄);`READ_ONLY_TOOLS` 与 `dsh_browser_restrict` 无论列表怎么写都不拦。`cordis.patch.yml` 默认给的是空 `config: {}`(等于不限制) |
 
 ## 快速上手(给 agent 的提示词示例)
 
 ```
-1. browser_open 打开 https://example.com
-2. 慢站点先 browser_wait(url=…) 等页面就绪,再 browser_snapshot 查看可交互元素
-3. 需要填表时用 browser_fill(按 name/label/placeholder 匹配,一次填多个字段)
-4. 需要截图确认时用 browser_screenshot(可 savePath 存文件,大页面用 maxWidth 缩小)
-5. 需要滚动/回退/按键时用 browser_scroll / browser_back / browser_forward / browser_key
-6. 遇到验证码(browser_challenge 或快照标注 CHALLENGE)时,停下请用户处理
+1. dsh_browser_open 打开 https://example.com
+2. 慢站点先 dsh_browser_wait(url=…) 等页面就绪,再 dsh_browser_snapshot 查看可交互元素
+3. 需要填表时用 dsh_browser_fill(按 name/label/placeholder 匹配,一次填多个字段)
+4. 需要截图确认时用 dsh_browser_screenshot(可 savePath 存文件,大页面用 maxWidth 缩小)
+5. 需要滚动/回退/按键时用 dsh_browser_scroll / dsh_browser_back / dsh_browser_forward / dsh_browser_key
+6. 遇到验证码(dsh_browser_challenge 或快照标注 CHALLENGE)时,停下请用户处理
 7. 每次操作后告知用户你在页面上做了什么
 ```
 
@@ -64,58 +64,58 @@ dsh plugin --profile web add <本仓库路径>
 
 **定位:先用语义,再考虑坐标**
 
-- **`browser_a11y` 是理解页面的首选**,它给出每个交互节点的**角色**(button/textbox/…)与**可访问名称**,比读 DOM 更接近"这页面上有什么";`browser_snapshot` 给出可点击元素的**引用与坐标**。
+- **`dsh_browser_a11y` 是理解页面的首选**,它给出每个交互节点的**角色**(button/textbox/…)与**可访问名称**,比读 DOM 更接近"这页面上有什么";`dsh_browser_snapshot` 给出可点击元素的**引用与坐标**。
 - **两者都带 `selector`**:无 id 且无 name 时是空串。**有 `selector` 就优先用它**,它比坐标稳定 —— 页面滚动、布局变化都不会让它失效,而坐标会。
 - **优先用 DOM 语义而非坐标**:表单提交优先 `form.requestSubmit()`;点击优先 `element.click()`;坐标点击是最后手段。
-- **`browser_click` 的 `target`(css/text)本质上就是语义定位**,能用它就别自己算坐标 —— 它会把元素滚进视野并在中心点击,坐标抖动、像素比、iframe 偏移都由它处理。
-- **选中正确的元素**:页面常有隐藏副本(如移动端按钮),用 `browser_execute` 过滤可见元素(`getBoundingClientRect()` 宽高 > 0、`getComputedStyle` 非 `display:none`),再取坐标。
+- **`dsh_browser_click` 的 `target`(css/text)本质上就是语义定位**,能用它就别自己算坐标 —— 它会把元素滚进视野并在中心点击,坐标抖动、像素比、iframe 偏移都由它处理。
+- **选中正确的元素**:页面常有隐藏副本(如移动端按钮),用 `dsh_browser_execute` 过滤可见元素(`getBoundingClientRect()` 宽高 > 0、`getComputedStyle` 非 `display:none`),再取坐标。
 - **取坐标后立即点击**:中间不要插入其他操作(填表、滚动会移动元素,旧坐标立即失效)。
 - **点击前验证命中**:`document.elementFromPoint(x, y)` 确认该坐标确实是目标元素,再执行真实点击。
 - **DPR 注意**:CDP 输入使用 CSS 像素;高 DPI 屏上若点击落空,用 `elementFromPoint` 校准,不要盲试坐标。
 
 **截图与内容:先问"我要的是判断还是像素"**
 
-- **能用文本就用文本。** `browser_snapshot` / `browser_a11y` / `browser_content` 给出同一页面的文本表示;**没有图像输入能力的模型看截图什么也得不到**,只会花钱。截图留给布局、图表、设计核对这类**必须看像素**的事。
-- **`browser_screenshot` 带 `maxWidth`/`maxHeight` 时,结果里会返回 `width`/`height`**(实际像素尺寸)。需要控制成本时用它确认降采样生效了,而不是自己解码 data URL。
-- **`browser_content` 的 `maxChars` 是按格式分档的**(html/json 默认 5 万,其余 2 万),单次传 `maxChars` 优先于设置里的 `contentMaxChars`。
+- **能用文本就用文本。** `dsh_browser_snapshot` / `dsh_browser_a11y` / `dsh_browser_content` 给出同一页面的文本表示;**没有图像输入能力的模型看截图什么也得不到**,只会花钱。截图留给布局、图表、设计核对这类**必须看像素**的事。
+- **`dsh_browser_screenshot` 带 `maxWidth`/`maxHeight` 时,结果里会返回 `width`/`height`**(实际像素尺寸)。需要控制成本时用它确认降采样生效了,而不是自己解码 data URL。
+- **`dsh_browser_content` 的 `maxChars` 是按格式分档的**(html/json 默认 5 万,其余 2 万),单次传 `maxChars` 优先于设置里的 `contentMaxChars`。
 
 **动作开关:三个门是操作者(人)的,不是你的**
 
-设置页里的**执行页面脚本**、**下载文件到磁盘**、**写入登录态** 由人控制,**任何 `browser_*` 工具都改不了它们**。关掉时对应调用会明确报错,一眼能认出:
+设置页里的**执行页面脚本**、**下载文件到磁盘**、**写入登录态** 由人控制,**任何 `dsh_browser_*` 工具都改不了它们**。关掉时对应调用会明确报错,一眼能认出:
 
 | 谁被关 | 报的错误码 | 哪些工具会遇到 |
 | --- | --- | --- |
-| 执行页面脚本 | `BROWSER_EXECUTE_DISABLED` | `browser_execute`、以及需要页内脚本的工具 |
-| 下载文件到磁盘 | `BROWSER_DOWNLOAD_DISABLED` | `browser_download` |
-| 写入登录态 | `BROWSER_AUTH_WRITE_DISABLED` | `browser_auth` 的 `restore` |
-| 读取 cookie | `BROWSER_AUTH_DISABLED` | `browser_auth` 的 `flush` |
+| 执行页面脚本 | `BROWSER_EXECUTE_DISABLED` | `dsh_browser_execute`、以及需要页内脚本的工具 |
+| 下载文件到磁盘 | `BROWSER_DOWNLOAD_DISABLED` | `dsh_browser_download` |
+| 写入登录态 | `BROWSER_AUTH_WRITE_DISABLED` | `dsh_browser_auth` 的 `restore` |
+| 读取 cookie | `BROWSER_AUTH_DISABLED` | `dsh_browser_auth` 的 `flush` |
 
 **看到这些码不要重试、不要绕路** —— **它是人的决定,不是可以克服的故障**,直接告诉人"需要他在设置里打开"。
 
 另外几个容易认错来源的码:`BROWSER_DOWNLOAD_BLOCKED` / `BROWSER_SCREENSHOT_BLOCKED` 是**保存路径被沙箱拒绝**(不是开关问题,换路径而不是找开关);`BROWSER_DOWNLOAD_UNSUPPORTED` 是**该载体没有这个能力**(比如非自托管浏览器)。
 
-`browser_restrict` **不一样** —— 那是**你自己**设的临时白名单,你有权设也有权解除;它不该被用来绕过上面三个门。
+`dsh_browser_restrict` **不一样** —— 那是**你自己**设的临时白名单,你有权设也有权解除;它不该被用来绕过上面三个门。
 
 **失败怎么读**
 
 - **`CDP error: ...` 是浏览器答了但拒绝**(比如元素已经不在)—— 多半是页面变了,重新快照再试,不要盲目重复同一动作。
 - **超时 / 连接类错误**才是浏览器可能有问题;这类错误会触发一次自动探测,通常下一条命令就能恢复。
-- **`BROWSER_SESSION_UNKNOWN`** 说明会话没了(浏览器被替换过);`browser_reset_session` 重建本任务的会话。
-- **同一个动作连续失败两次就换策略**:换 `selector`、换语义定位、或者用 `browser_snapshot` 重新看页面 —— **不要第三次用同样的坐标**。
+- **`BROWSER_SESSION_UNKNOWN`** 说明会话没了(浏览器被替换过);`dsh_browser_reset_session` 重建本任务的会话。
+- **同一个动作连续失败两次就换策略**:换 `selector`、换语义定位、或者用 `dsh_browser_snapshot` 重新看页面 —— **不要第三次用同样的坐标**。
 
-**`browser_history` 与动作集**
+**`dsh_browser_history` 与动作集**
 
-- `browser_history` **默认只给 20 条**,要更多自己传 `limit`。
-- **可重放的动作有六种**:`navigate` / `click` / `type` / `scroll` / `key` / `execute`。不是每种历史记录都能 `browser_replay`,遇到不可重放的会明确报错。
+- `dsh_browser_history` **默认只给 20 条**,要更多自己传 `limit`。
+- **可重放的动作有六种**:`navigate` / `click` / `type` / `scroll` / `key` / `execute`。不是每种历史记录都能 `dsh_browser_replay`,遇到不可重放的会明确报错。
 
 ## 多任务并行
 
 每个 DSH 会话(任务)拥有独立的浏览器会话(独立标签页与历史),并发任务互不干扰:
 
-- `browser_session` 查看本任务的会话与标签;
-- `browser_reset_session` 关闭并重建本任务的会话(崩溃或卡死后用它恢复)。
+- `dsh_browser_session` 查看本任务的会话与标签;
+- `dsh_browser_reset_session` 关闭并重建本任务的会话(崩溃或卡死后用它恢复)。
 
-登录态(cookie)为所有任务共享;可用 `browser_auth` 导出/恢复,重启后不丢。注意 **`flush` 只导出当前页所属站点的 cookie**(按本会话所在页面的 URL 收敛),页面 URL 未知时**直接拒绝**而不是扩大范围去读整台机器的 cookie 罐;`restore` 会向任意域写 cookie,所以 `browser_auth` **同样受 `browser_restrict` 白名单约束**,不属于只读豁免。
+登录态(cookie)为所有任务共享;可用 `dsh_browser_auth` 导出/恢复,重启后不丢。注意 **`flush` 只导出当前页所属站点的 cookie**(按本会话所在页面的 URL 收敛),页面 URL 未知时**直接拒绝**而不是扩大范围去读整台机器的 cookie 罐;`restore` 会向任意域写 cookie,所以 `dsh_browser_auth` **同样受 `dsh_browser_restrict` 白名单约束**,不属于只读豁免。
 
 ## FAQ
 
@@ -131,7 +131,7 @@ DSH Desktop 上②命中即可用(0.1.18+ 插件自带 electron 包;44+ 二进
 确保 Electron ≥ 40(33.x 有合成器缺陷)。自托管截图优先走原生 `capturePage`,多视图/窗口未激活时自动兜底到 CDP。
 
 **Q:浏览器窗口不见了?**
-窗口标题为 `dsh-browser`(自托管)。若子进程崩溃(或宿主 DSH 重启)会自动重启;崩溃前已打开的会话在**下一次调用时自动重建**——仅页面状态丢失,无需手动 `browser_reset_session`。`browser_reset_session` 仍可用于主动重置。
+窗口标题为 `dsh-browser`(自托管)。若子进程崩溃(或宿主 DSH 重启)会自动重启;崩溃前已打开的会话在**下一次调用时自动重建**——仅页面状态丢失,无需手动 `dsh_browser_reset_session`。`dsh_browser_reset_session` 仍可用于主动重置。
 
 **Q:设置里的 `contentMaxChars` 改了没反应?**
 先确认改的是哪一层。优先级从高到低是:**单次调用的 `maxChars`** > **配置里的 `contentMaxChars`** > **按格式的分档默认**(html/json 50 000,txt/markdown 20 000)。`contentMaxChars` 的作用就是给这个部署换一个默认值:不设时才用分档,设了就盖过分档。若改了没反应,通常是那一次调用自己传了 `maxChars`。
@@ -140,18 +140,74 @@ DSH Desktop 上②命中即可用(0.1.18+ 插件自带 electron 包;44+ 二进
 能。该载体观察进程退出并清掉**已失效的会话映射**,下一次调用会**重新拉起**浏览器并继续工作;重新拉起前会先 kill 旧进程并**最多等 3 秒**它真正退出,且**只认本次启动写下的 `DevToolsActivePort`**(被杀掉的浏览器没机会清理那个文件,照读会连到别的 Chromium 或 `node --inspect` 上)。反过来,页面只是**慢**不会让插件杀掉你的窗口:命令超时只把连接标记为存疑,下一次调用先用 `Browser.getVersion` 探一次再决定是否丢弃,只有 socket 已关闭才重启。
 
 **Q:下载报 CORS 错误?**
-`browser_download` 在页面上下文内 `fetch`,受同源/CORS 约束;跨域文件请先在同源页面内操作,或直接请求用户提供。仅支持 HTTP(S) URL;`savePath` 必须为绝对路径且位于 `downloadDir` 内(默认系统下载目录,自动识别 `Downloads`/`下载`/`下載`),不覆盖已有文件;`browser_screenshot` 的 `savePath` 受同一套限制。
+`dsh_browser_download` 在页面上下文内 `fetch`,受同源/CORS 约束;跨域文件请先在同源页面内操作,或直接请求用户提供。仅支持 HTTP(S) URL;`savePath` 必须为绝对路径且位于 `downloadDir` 内(默认系统下载目录,自动识别 `Downloads`/`下载`/`下載`),不覆盖已有文件;`dsh_browser_screenshot` 的 `savePath` 受同一套限制。
 
 **Q:如何禁止 agent 乱点?**
-`browser_restrict` 设置白名单(如只允许 `browser_snapshot`/`browser_content`);传空列表解除。注意它是防误操作的**软护栏**,模型可自行解除,不是安全边界。
+`dsh_browser_restrict` 设置白名单(如只允许 `dsh_browser_snapshot`/`dsh_browser_content`);传空列表解除。注意它是防误操作的**软护栏**,模型可自行解除,不是安全边界。
 
-要一个**模型自己解不掉**的限制,用设置页「Agent 能做什么」的三个开关(执行页面脚本 / 下载文件到磁盘 / 写入登录状态):它们写在设置文档里,而没有任何工具能写那个文档,所以模型只能被拒 —— 这与 `browser_restrict` 的区别不是"谁更强",而是"谁能改"。部署级(对所有人生效)还可以用 `tool-browser` 的 `allowedActions` 配置,见 `cordis.patch.yml` 的注释。
+要一个**模型自己解不掉**的限制,用设置页「Agent 能做什么」的三个开关(执行页面脚本 / 下载文件到磁盘 / 写入登录状态):它们写在设置文档里,而没有任何工具能写那个文档,所以模型只能被拒 —— 这与 `dsh_browser_restrict` 的区别不是"谁更强",而是"谁能改"。部署级(对所有人生效)还可以用 `tool-browser` 的 `allowedActions` 配置,见 `cordis.patch.yml` 的注释。
 
 ## 故障排查
 
 | 现象 | 可能原因 | 处理 |
 | --- | --- | --- |
-| `BROWSER_SESSION_UNKNOWN` | 会话已被关闭/重建(如 `browser_reset_session` 后仍引用旧会话) | `browser_session` 查看现状;或 `browser_reset_session` 重建 |
-| 工具超时 | 页面卡死/未渲染完成 | 稍后重试;`browser_reset` 重置标签 |
+| `BROWSER_SESSION_UNKNOWN` | 会话已被关闭/重建(如 `dsh_browser_reset_session` 后仍引用旧会话) | `dsh_browser_session` 查看现状;或 `dsh_browser_reset_session` 重建 |
+| 工具超时 | 页面卡死/未渲染完成 | 稍后重试;`dsh_browser_reset` 重置标签 |
 | 导航被拒 | 非 HTTP(S) 协议 | 检查 URL;`httpOnly` 配置 |
-| 快照为空 | 页面尚未加载 | 等待后重试 `browser_snapshot` |
+| 快照为空 | 页面尚未加载 | 等待后重试 `dsh_browser_snapshot` |
+
+## 验证过的版本
+
+| 组件 | 版本 |
+| --- | --- |
+| DeepSeek Harness(dsh) | `0.2.1-alpha.1`(peer 声明 `>=0.1.1-rc.2 <0.3.0`;更早的 `0.2.0-rc.2`、`0.1.x` 亦有实测记录) |
+| Electron | `44.0.0`(推荐 ≥ 40;33.x 存在合成器缺陷) |
+| Node.js | `22.20.0` |
+| 本机 Chrome / Edge(可选载体) | `154.0.8037.58` / `154.0.4258.37` |
+| 操作系统 | Windows 10 (10.0.26200) |
+
+> 插件声明 `electron >= 30`。**核心链路在 Windows 上完整实测**;系统浏览器的查找已适配 Linux 与 macOS(先查 `PATH`,再查各平台的惯例安装位置,均可用 `DSH_BROWSER_CHROME_PATH` / `DSH_BROWSER_EDGE_PATH` 覆盖),但这两个平台上的**端到端链路尚未实测**,暂不承诺。
+
+> **宿主兼容性可以随时复验**:`node scripts/verify-host-compat.mjs` 会用某个 profile 里**真实安装**的 `@deepseek-ai/*` 包组装一个宿主,加载本插件的编译产物并真调两个工具。详见[开发](development.md)。
+
+## 更新方式(两端不同)
+
+插件在两种宿主里各有一份安装,更新路径也不同 —— **更新其中一端不会连带更新另一端**。
+
+**桌面端(DSH Desktop)**
+
+- 插件是桌面端 profile 里的依赖(profile 目录通常是 `$DSH_HOME/profiles/desktop`)。更新它 = 把该 profile 里的依赖更新到新版本,然后**重启 DSH Desktop**,客户端设置栏与工具才会换成新代码。
+- **桌面端还多一步,而 Web 端没有**:让插件驱动侧栏的那条 bridge 装在**桌面端自己的安装目录**里(`resources/app/`),插件更新**不会**带上它。桌面端升级会替换该目录、bridge 随之消失,所以请重跑一次:
+  ```bash
+  node desktop-bridge/install.mjs            # 幂等;已装则只刷新模块
+  node desktop-bridge/install.mjs --revert   # 回滚
+  ```
+  bridge 不在时插件自动退回自托管(多出一个独立窗口),功能不中断。
+- 浏览器内核默认由桌面端自带的 Electron 提供,插件不会再下载一份 Electron;也可以在设置里改用它自己装的 Chrome / Edge。
+- **升级桌面端本身不会带上插件**,按上面的方法单独更新它。
+
+**Web 端(`dsh web`)**
+
+- 插件是 web profile 里的依赖(`$DSH_HOME/profiles/web`),更新后**重启 `dsh web`** 生效。
+- Web 端**没有侧栏、也没有 bridge**:共享浏览器由插件自托管拉起。首次安装可能需要 Electron 二进制;若包管理器的构建白名单拦下了它(pnpm v10+ 会拦 `electron` 的 postinstall),执行一次 `npx install-electron` 补上即可。
+- 同样可以在设置里改用本机 Chrome / Edge —— 这是两端**行为一致**的选项。
+- 更新方式与首次安装它时一致(按 npm 包名 `dsh-builtin-browser`、按 GitHub 仓库 `wqty123/dsh-browser`,或本地目录)。
+
+**两端一致的体验**
+
+- 工具集、设置页里的「浏览器」栏、浏览历史与 cookie 的持久化行为完全相同;差别只在页面由谁承载(桌面端=官方侧栏,Web 端=插件自托管窗口,或你在设置里指定的本机浏览器)。
+- 升级不会丢数据:浏览历史与设置都在 `$DSH_HOME/dsh-builtin-browser-host/`(`history.jsonl`、`settings.json`),登录状态在同一 profile 目录里 —— 包括使用本机浏览器时的 `<chrome|edge>-profile`。
+- 升级后如果历史记录不符合预期,先去「设置 → 浏览器」确认这些开关:历史默认**开**、侧栏自动展开默认**开**、会话结束时自动关闭浏览器默认**关**、载体默认**内置**。
+
+## 从 0.4.7 升级到 0.4.8
+
+**这是一个改名版本:34 个工具从 `browser_*` 移入 `dsh_browser_*`,功能一字未改。**
+
+| | |
+| --- | --- |
+| **只装这一个浏览器插件** | **不必更新。** 旧版继续正常工作。 |
+| **还装了别的浏览器插件**(尤其腾讯 BrowserSkill) | **建议更新**,否则对方那套工具注册不上。 |
+
+改名原因见 [README 的工具名空间一节](../README.md#工具名空间)。更新后 `browser_open` → `dsh_browser_open`(其余同理),并**重启 DSH** 使其生效。
+
+> **0.4.8 起,一个名字被占不再毁掉整套工具。** 此前 34 个工具是顺序直接注册的,一个重名抛错会中断余下的注册,表现成"插件装了但没反应"。现在每个工具独立注册,碰撞只产生一条点名报错的日志(`could not register dsh_browser_xxx`),其余工具照常可用。

package/docs/why-browser.md

@@ -26,13 +26,13 @@ LLM agent 需要"上网"。传统做法是给 agent 一个**无头浏览器**(Pl
 | 真实页面渲染 | ✅ | 部分 | ✅ |
 | 复杂交互(填表/点击/拖拽) | ✅ | ❌ | ✅ |
 | 用户可见、可接管 | ❌ | ❌ | ✅ |
-| 保留登录态 | 需手动管理 | ❌ | ✅(`browser_auth` + cookie 落盘) |
+| 保留登录态 | 需手动管理 | ❌ | ✅(`dsh_browser_auth` + cookie 落盘) |
 | 人工处理验证码 | ❌ 卡死 | ❌ | ✅ 请用户点一下即可 |
 | 多任务并行 | 需多实例 | – | ✅ 任务级会话隔离 |
 
 ## 设计取舍
 
-- **登录态共享**:所有任务共享同一份 cookie(符合"用户登录一次,agent 到处可用");需要搬运时用 `browser_auth` 手动导出/恢复 —— 它的 `flush` **只导出当前页所属站点的 cookie**(按本会话所在页面的 URL 收敛,页面 URL 未知时拒绝而不是放宽),所以"导出"是逐站点的一步,不是一次性打包整个 cookie 罐。
+- **登录态共享**:所有任务共享同一份 cookie(符合"用户登录一次,agent 到处可用");需要搬运时用 `dsh_browser_auth` 手动导出/恢复 —— 它的 `flush` **只导出当前页所属站点的 cookie**(按本会话所在页面的 URL 收敛,页面 URL 未知时拒绝而不是放宽),所以"导出"是逐站点的一步,不是一次性打包整个 cookie 罐。
 - **任务级会话隔离**:每个 DSH 会话(任务)拥有独立的浏览器会话(标签页与历史),并发任务互不抢页面;自托管载体下**每个会话连窗口都各自一份**(窗口按会话 id 分组,窗口标题带任务标识),侧栏与本机浏览器载体则是同一个宿主里切换当前可见视图。
 - **装好即用**:不依赖桌面外壳。有外壳时嵌入外壳视图;纯 `dsh web` 时插件自托管——自己拉起 Electron 窗口,通过本机 TCP JSON-RPC 驱动。
 - **边界清晰**:可见视图、浏览器列布局属于宿主外壳;插件只负责 seam、provider 与工具,不含任何 UI。
@@ -41,5 +41,5 @@ LLM agent 需要"上网"。传统做法是给 agent 一个**无头浏览器**(Pl
 ## 什么场景不适合
 
 - 需要**无头批量抓取**(成千上万页面):请用专门的抓取工具/服务,不必开窗口。
-- 需要**每个任务完全独立的登录态**(互不可见):本插件默认共享 cookie;如需强隔离,可用多个 DSH 实例或 `browser_auth` 手动管理。
+- 需要**每个任务完全独立的登录态**(互不可见):本插件默认共享 cookie;如需强隔离,可用多个 DSH 实例或 `dsh_browser_auth` 手动管理。
 - 需要**浏览器列 UI / 布局管理**:那是宿主外壳的配套,本插件不包含。

package/lib/browser/types.d.ts

@@ -58,7 +58,7 @@ export interface BrowserScrollRequest {
 }
 /** Press one named key (Enter, Tab, arrows, …). */
 export interface BrowserKeyRequest {
-    /** Key name from the supported set (see the browser_key tool). */
+    /** Key name from the supported set (see the dsh_browser_key tool). */
     readonly key: string;
 }
 /**
@@ -333,7 +333,7 @@ export interface BrowserSnapshotElement {
     /**
      * True when the element lives inside an (same-origin) iframe: coordinates
      * are still top-document, but DOM selectors are frame-scoped — reach the
-     * element via `iframe.contentDocument` in browser_execute.
+     * element via `iframe.contentDocument` in dsh_browser_execute.
      */
     readonly frame?: boolean;
 }

package/lib/browser-electron/bridge-connection.d.ts

@@ -23,6 +23,7 @@ export interface BridgeEndpoint {
 export declare class BridgeConnection {
     private endpoint;
     private readonly endpointPath?;
+    private readonly onLost?;
     private socket;
     private buffer;
     /** Outstanding requests by id. */
@@ -34,11 +35,14 @@ export declare class BridgeConnection {
     private idLessBridge;
     /** True once this connection may only have one request in flight at a time. */
     private serialisable;
+    /** True once the shell behind this connection has been reported gone. */
+    private lostNotified;
     /**
      * @param endpoint - the shell's published bridge endpoint.
      * @param endpointPath - where that endpoint is republished, so a moved port can be followed.
+     * @param onLost - called once when this connection concludes the shell behind it is gone.
      */
-    constructor(endpoint: BridgeEndpoint, endpointPath?: string | undefined);
+    constructor(endpoint: BridgeEndpoint, endpointPath?: string | undefined, onLost?: (() => void) | undefined);
     /**
      * Re-read the published endpoint, and adopt it if the shell has moved.
      *
@@ -53,6 +57,8 @@ export declare class BridgeConnection {
      * @returns true when a different endpoint was adopted.
      */
     private refreshEndpoint;
+    /** Report once that the shell is gone, so the surface can fall back instead of dialling it. */
+    private notifyLost;
     /**
      * Send one request, reusing the socket if it is still healthy.
      *

package/lib/browser-electron/bridge-connection.js

@@ -33,6 +33,15 @@ const MAX_BUFFER_BYTES = 128 * 1024 * 1024;
  * client then falls back to arrival order, which is what the protocol guaranteed before.
  */
 const REQUEST_ID_FIELD = 'bridgeRequestId';
+/**
+ * How long the published endpoint may go un-refreshed before its shell is presumed gone.
+ *
+ * A live shell rewrites the file every fifteen seconds (its keep-alive), so four missed refreshes
+ * is not a slow shell — it is a shell that exited and left its last write behind. The distinction
+ * matters because the file is the ONLY thing that says where the bridge is: a tombstone names a
+ * port nobody owns, and a client that trusts it dials that port for the rest of its life.
+ */
+const ENDPOINT_TTL_MS = 60_000;
 /**
  * A reusable connection to the bridge.
  *
@@ -51,6 +60,7 @@ const REQUEST_ID_FIELD = 'bridgeRequestId';
 export class BridgeConnection {
     endpoint;
     endpointPath;
+    onLost;
     socket;
     buffer = '';
     /** Outstanding requests by id. */
@@ -62,13 +72,17 @@ export class BridgeConnection {
     idLessBridge = false;
     /** True once this connection may only have one request in flight at a time. */
     serialisable = false;
+    /** True once the shell behind this connection has been reported gone. */
+    lostNotified = false;
     /**
      * @param endpoint - the shell's published bridge endpoint.
      * @param endpointPath - where that endpoint is republished, so a moved port can be followed.
+     * @param onLost - called once when this connection concludes the shell behind it is gone.
      */
-    constructor(endpoint, endpointPath) {
+    constructor(endpoint, endpointPath, onLost) {
         this.endpoint = endpoint;
         this.endpointPath = endpointPath;
+        this.onLost = onLost;
     }
     /**
      * Re-read the published endpoint, and adopt it if the shell has moved.
@@ -90,6 +104,13 @@ export class BridgeConnection {
             const raw = JSON.parse(readFileSync(this.endpointPath, 'utf8'));
             if (typeof raw.port !== 'number' || typeof raw.token !== 'string')
                 return false;
+            // A shell that exited stops refreshing the file, and what it left names a port nobody owns.
+            // Trusting it is how a host ends up dialling a dead port for the rest of the process's life
+            // — reported as "the browser stopped working and only restarting DSH brought it back".
+            if (endpointExpired(raw.updatedAt)) {
+                this.notifyLost();
+                return false;
+            }
             if (raw.port === this.endpoint.port && raw.token === this.endpoint.token)
                 return false;
             this.endpoint = {
@@ -105,6 +126,18 @@ export class BridgeConnection {
             return false;
         }
     }
+    /** Report once that the shell is gone, so the surface can fall back instead of dialling it. */
+    notifyLost() {
+        if (this.lostNotified)
+            return;
+        this.lostNotified = true;
+        try {
+            this.onLost?.();
+        }
+        catch {
+            // A listener must never break the transport: the caller's error is the one that matters.
+        }
+    }
     /**
      * Send one request, reusing the socket if it is still healthy.
      *
@@ -126,6 +159,14 @@ export class BridgeConnection {
         // when the condition could not clear, spun until the process ran out of heap.
         // Follow the shell if its bridge moved to a new port (see refreshEndpoint).
         this.refreshEndpoint();
+        // The shell behind this connection is gone, and the endpoint file says so. Refusing here is
+        // what turns a permanent ECONNREFUSED into one named error the surface can act on — by
+        // falling back to the browser it hosts itself, instead of dialling a dead port until DSH is
+        // restarted.
+        if (this.lostNotified) {
+            throw new Error('dsh-builtin-browser: the desktop shell that backed this browser has exited '
+                + '(its published endpoint stopped being refreshed)');
+        }
         let socket = this.ensureSocket();
         if (this.serialisable && this.queue.length > 0) {
             this.reset(new Error('dsh-builtin-browser: bridge connection reopened so replies stay attributable'));
@@ -281,8 +322,22 @@ export class BridgeConnection {
             entry.reject(error);
     }
 }
-/** The request id a raw answer line echoes back, when it carries one. */
-function echoOf(line) {
+/**
+ * Whether a published endpoint has gone un-refreshed long enough to be a tombstone.
+ *
+ * A missing or unparseable stamp is NOT expired: an older bridge that never wrote one must keep
+ * working, and guessing "stale" from absence would break every shell that predates the field.
+ * @param updatedAt - the file's own refresh stamp, when it carries one.
+ */
+function endpointExpired(updatedAt) {
+    if (typeof updatedAt !== 'string')
+        return false;
+    const at = Date.parse(updatedAt);
+    if (!Number.isFinite(at))
+        return false;
+    return Date.now() - at > ENDPOINT_TTL_MS;
+}
+/** The request id a raw answer line echoes back, when it carries one. */ function echoOf(line) {
     try {
         const answer = JSON.parse(line);
         const value = answer[REQUEST_ID_FIELD];

package/lib/browser-electron/desktop-bridge-host.d.ts

@@ -94,10 +94,21 @@ export declare class DesktopBridgeViewHost implements ElectronBrowserViewHost {
      * the desktop sidebar is the carrier — by design, not by omission.
      */
     private userActionHandler;
+    /** Told when the shell behind this bridge exits; see `onLost`. */
+    private lostListener;
     /**
      * @param endpoint - the shell's published bridge endpoint.
      */
     private constructor();
+    /**
+     * Called by the transport once the shell behind it is gone.
+     *
+     * Forwarded rather than acted on here: only the entry point owns the swap back to the self-hosted
+     * browser, and a host that tried to replace itself would be reaching outside its own contract.
+     */
+    private reportLost;
+    /** Register the "this carrier is gone" listener (see the interface's `onLost`). */
+    onLost(listener: () => void): void;
     /**
      * Find a usable desktop bridge, if this surface has one.
      *

package/lib/browser-electron/desktop-bridge-host.js

@@ -111,12 +111,32 @@ export class DesktopBridgeViewHost {
      * the desktop sidebar is the carrier — by design, not by omission.
      */
     userActionHandler;
+    /** Told when the shell behind this bridge exits; see `onLost`. */
+    lostListener;
     /**
      * @param endpoint - the shell's published bridge endpoint.
      */
     constructor(endpoint, sessionId) {
         this.owner = sessionId !== undefined && sessionId !== String.fromCharCode(39, 39) ? sessionId : randomUUID();
-        this.connection = new BridgeConnection(endpoint, bridgeEndpointPath());
+        this.connection = new BridgeConnection(endpoint, bridgeEndpointPath(), () => this.reportLost());
+    }
+    /**
+     * Called by the transport once the shell behind it is gone.
+     *
+     * Forwarded rather than acted on here: only the entry point owns the swap back to the self-hosted
+     * browser, and a host that tried to replace itself would be reaching outside its own contract.
+     */
+    reportLost() {
+        try {
+            this.lostListener?.();
+        }
+        catch {
+            // The listener's failure is not the transport's problem.
+        }
+    }
+    /** Register the "this carrier is gone" listener (see the interface's `onLost`). */
+    onLost(listener) {
+        this.lostListener = listener;
     }
     /**
      * Find a usable desktop bridge, if this surface has one.

package/lib/browser-electron/entry.d.ts

@@ -5,7 +5,7 @@
  * `ctx.electronViewHost`, that host is used (embedded, human-machine shared
  * view). Otherwise the plugin self-hosts: it spawns its own Electron child
  * (`host-main.js`) and drives it over a local TCP JSON-RPC socket, so
- * installing the plugin is enough for `browser_*` tools to work on any
+ * installing the plugin is enough for `dsh_browser_*` tools to work on any
  * surface.
  * @module dsh-browser/browser-electron
  */
@@ -27,7 +27,7 @@ export interface Config {
     /** Allow navigation only to HTTP(S) URLs. Default true. */
     readonly httpOnly?: boolean;
     /**
-     * Directory `browser_download` save paths must resolve inside (prevents a
+     * Directory `dsh_browser_download` save paths must resolve inside (prevents a
      * prompt-injected agent from writing arbitrary machine paths). Default:
      * the user's Downloads folder; override to confine downloads elsewhere.
      */