dsh-live-browser
让 agent 操作 DSH 自带的侧边栏浏览器：真实 webview 渲染，注入命令层，可点击、输入、读取和滚动用户眼前那张页面；每个对话各自一页，并补齐标签页右键批量关闭。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:c347087870/dsh-live-browser#0c84640024cef596ad793190301f3efbd5de1a5eLive Browser 以 dsh-live-browser 发布，当前版本为 0.4.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
让 agent 操作 DSH 自带的那个浏览器 —— 就在 DSH 里，什么都不离开窗口。
中文 | English
DSH 自带的 @deepseek-ai/dsh-client-ui-sidebar-browser 会在右侧栏渲染一个真正的
Electron <webview>，带地址栏、历史记录和独立的浏览器会话。但它只开放了导航能力：
agent 能打开页面，却点不了、输不进、读不到、滚不动。
这个插件在不修改 DSH 任何文件的前提下补上这一段：找到官方插件挂载的那些 guest，
往每个文档里注入一套操作接口，再给模型 25 个 browser_* 工具，操作的正是用户眼前那张页面。
顺带把标签页右键菜单补全：关闭其他标签页 / 关闭全部标签页 / 关闭右侧所有标签页。
需要 DSH 0.2.x 与 Node.js 20 以上。插件在 package.json 里声明了 DSH 组合包，安装时
DSH 会自动注册。
# Web / CLI profile
dsh plugin --profile web install c347087870/dsh-live-browser
桌面版的 profile 由 Electron 应用独占，请从界面安装：插件 → 添加插件，粘贴
https://github.com/c347087870/dsh-live-browser，然后重启 DSH。
dsh plugin --profile web install dsh-live-browser
node -e "const p=require('./node_modules/dsh-live-browser/package.json');console.log(p.version, p.dsh)"
dsh.bundle.patch 必须存在，lib/index.js 必须存在。重启后日志里会出现
[dsh-live-browser] loaded: 25 tools, driving the DSH sidebar browser。
本地开发不要用 junction（
mklink /J、ln -s）：Node 会解析真实路径，于是schemastery去源码目录找而不是去 profile 找。要么复制整个包目录，要么用dsh plugin安装。
DSH 会把这些渲染在插件的设置卡片里。每一项都有默认值，不动也能用。
| 配置 | 默认 | 含义 |
|---|---|---|
confirmSensitive | true | 标记为 sensitive 的动作执行前先问用户 |
allowEval | true | 是否允许 browser_eval 在页面里执行任意 JavaScript |
autoOpenPanel | true | 命令到达但没有页面时，自动打开侧边栏浏览器 |
commandTimeoutMs | 30000 | 单次命令等待面板执行的超时（毫秒） |
openPanelWaitMs | 8000 | 打开面板后等待其就绪的时间 |
maxSnapshotNodes | 400 | browser_snapshot 默认节点上限 |
maxTextChars | 12000 | browser_read_text 默认字符上限 |
waitTimeoutMs | 10000 | browser_wait 默认超时（毫秒） |
uploadMaxBytes | 16777216 | browser_upload 单个文件的上限 |
imageDir | 空 | browser_screenshot 的图片目录；留空用 ~/.dsh/storages/dsh-live-browser/images |
downloadsDir | 空 | browser_downloads 读取的目录；留空用系统「下载」文件夹 |
想让 agent 只读页面、不在页面里跑代码，就把 allowEval 关掉。browser_eval 随后
返回 executed: false，并提示改用 browser_snapshot / browser_read_text。
agent 不会先让你去开浏览器，也永远不会去开外部窗口：
openTabIn(sessionId, 'browser', …) 打开浏览器标签页，等 guest 挂载好再执行。所以冷启动时一句 browser_navigate，表现就是右侧栏自己弹出一个标签页并加载目标地址。
DSH 每个 Session 一个侧边栏，插件遵守这个边界：
exec.agent.session.id）。keepMounted），
但它们被标了 hidden，不能被当成你眼前这一页。openTabIn(sessionId, …) 在发起请求的那个对话里打开，
而不是在屏幕上恰好显示的那个对话里。这消除了老的故障模式：在 A 对话要页面，没等它出来就切到 B，结果浏览器出现在 B。
为什么打开动作放在渲染层：侧边栏整个在客户端，它的宿主模块什么都不贡献，所以没有 宿主服务可调。客户端那一半通过
ctx.reflect.provide发布sidebarRight，插件用的就是这个。
| 本插件 | 直接改官方 bundle | |
|---|---|---|
| 点击 / 输入 / 读取 / 滚动 | 可以 | 可以 |
| 把页面图表导成 PNG | 可以，用页面自己的 canvas/SVG | 可以 |
| 截原生窗口 | 不行 | 可以 |
| 经得起 DSH 升级 | 可以 | 不行，每个版本都要重打补丁 |
| 对现有功能的风险 | 无 | 可能破坏侧边栏的链接处理 |
工具调用
│ bridge.call(method, params) lib/bridge.js
▼
命令队列 ──────► 面板长轮询 client.js
│
├─ 还没有 guest → 打开侧边栏浏览器（openTabIn 本对话）
├─ 页面命令 → 注入到 guest 里的脚本
├─ 浏览器命令 → guest 元素本身（loadURL/goBack…）
└─ 标签页命令 → 侧边栏服务
│
settle(result)
▼
工具结果
右键标签页 ──► 菜单 DOM 装饰（client.js）──► 关闭其他 / 全部 / 右侧
lib/bridge.js —— 队列与长轮询。冷调用会在队列里留够时间让客户端把标签页开出来；
始终等不到面板的调用会带着可操作的提示失败，而不是一直挂着。lib/agent-script.js —— 注入每个 guest 文档的脚本。纯 DOM：带稳定 ref 的快照、
点击、输入、按键、选择、悬停、滚动、读正文、执行表达式、等待、附加文件、canvas/SVG 转 PNG。lib/rpc.js —— 挂在 DSH web server 上的一个前缀路由（/dsh-live-browser），说面板那套
简单的请求/响应信封。每个请求都校验同源与回环主机，因为这个路由既能写文件（saveImage）
也能读文件（readUpload）。lib/config.js / lib/schema.js —— 配置值与 DSH 渲染的表单。取值部分不依赖第三方包，
所以工具层和测试不需要 node_modules 就能跑。client.js —— 找到当前对话那个侧边栏里的
webview[data-sidebar-browser-frame="webview"]，注入脚本，需要时打开标签页，跑轮询循环。
后台对话的侧边栏还挂在 DOM 里（keepMounted），但被标了 hidden，插件不会误认；
同一栏里有多个标签时，挑真正有布局盒子的那个，而不是最后挂载的那个。标签页右键菜单
也在这里补三项：监听 contextmenu，等 DSH 的菜单 portal 出现后追加按钮，仍然不改 DSH。
整体包在 IIFE 里：DSH 会把多个插件 bundle 塞进同一个 combo <script>，顶层 const
会跟邻居撞名。connection.rpc.handle在 dsh 0.2.1-rc.2 上，这个 API 用
owner.effect(() => owner.webServer.register(route)) 建路由，而 owner 是 connection
插件自己的 context —— 它从没声明过 webServer 依赖。于是属性读取抛
cannot get property "webServer" without inject，effect 把错误吞掉，面板请求全部落到
静态前端兜底，表现为 HTTP 405。直接在 webServer 上注册是同一个调用，只是绕开了
那层坏掉的间接。
| 工具 | 作用 |
|---|---|
browser_status | 面板是否打开、当前是什么页面 |
browser_open_panel | 打开侧边栏浏览器（也会自动发生） |
browser_navigate / back / forward / reload | 导航 |
browser_snapshot | 无障碍风格的节点列表，带稳定 ref |
browser_read_text | 可见正文，可用选择器限定范围 |
browser_click / type / press / select / hover | 页面交互 |
browser_scroll / wait | 滚动与等待 |
browser_eval | 在页面里执行一段 JS 表达式 |
browser_screenshot | 把图表（canvas/SVG）或元素导出成 PNG |
browser_tabs / tab_new | 列出标签页、新建标签页 |
browser_upload | 给文件输入框附加本地文件 |
browser_downloads | 列出下载目录里的文件 |
browser_confirm | 请用户确认一个不可撤销的动作 |
侧边栏把标签页 id 留在内部。插件操作的是获得焦点的那个 guest；没有焦点时，用当前对话的
右侧栏里真正显示着的那个标签页 —— 访问过的标签页都会保活挂在 DOM 里，按挂载顺序取最后一个
会点到看不见的页面。也没有 tab 参数去指别处 —— 这个参数以前存在却被静默丢弃，会让调用方
误以为自己指定了某个标签页。browser_tabs 仍然可以列出当前有哪些。
右键标签页的菜单里，插件补了三个动作：关闭其他标签页、关闭全部标签页、 关闭右侧所有标签页（当前标签右侧的全部，当前标签保留；没得关时置灰）。顺序取自当前 分栏的标签条，分栏两侧互不影响；菜单本体仍是 DSH 的，插件不接管它。浮动分栏没有标签条， 因此不提供这组动作。
有三件事 DSH 不开放给插件，插件以结构化结果如实报告，而不是假装成功：
browser_tab_close / browser_tab_activate —— 侧边栏的标签 id 是内部的，工具会
请你自己去点标签。browser_reset_profile —— 浏览器会话没有开放清理接口，工具返回操作步骤。browser_screenshot 改为让
页面自己栅格化它的 <canvas>/<svg>，而这正是图表。browser_eval 会在当前加载的任何页面里执行任意 JavaScript。这是这个工具存在的意义，
也是 allowEval 存在的原因。confirmSensitive 开着时，标记为 sensitive 的动作会先问用户；没有确认通道时是拒绝，
不是放行。/dsh-live-browser 路由拒绝跨站与非回环的调用方。本机进程仍能伪造这些头，但它本来就能
读写和你一样的文件。node test/test-all.mjs
十三个套件，分两类：
npm test 即可。test/fixtures/ 里的 CDP
夹具驱动真实页面，这个夹具只为测试而存在；实际发的插件从不直接碰 Chrome。
用 node scripts/ensure-browser.mjs 起一个，或者让它们报 SKIP。「DOM 行为」和「端到端链路」原本也要真浏览器，现在改成在 jsdom 里跑同一份注入脚本，
所以不需要 Chrome。图表导出没跟着改，因为 jsdom 的 canvas 要额外装原生包 canvas，
为了跑测试把编译依赖架到使用者机器上不划算。
test/test-rpc-http.mjs 需要一个正在运行的 DSH：
node test/test-rpc-http.mjs "http://127.0.0.1:PORT/?token=..."
测试浏览器的路径可以用 DSH_TEST_CDP_PORT、DSH_TEST_PROFILE_DIR、
DSH_TEST_DOWNLOAD_DIR 覆盖。
本地改源码后，必须重启 DSH：宿主插件的工具注册只在进程启动时发生，文件变化 不会热生效。重启前
browser_*工具和/dsh-live-browser路由都不存在（路由返回 HTTP 405 就是没加载的信号）。
package.json 这类文件如果开头混进 UTF-8 BOM，DSH 会报
installation rejected: Cannot validate installed package dsh-live-browser:
SyntaxError: Unexpected token ... is not valid JSON
然后把 package.json、pnpm-lock.yaml 和 node_modules 整体回滚——插件装不上，
但代码本身毫无问题，现象是「工具和路由都不存在」，极难排查。
Windows 上用 PowerShell 的 Set-Content、Out-File 写文件很容易带上 BOM。仓库里带了
巡检脚本：
npm run strip-bom # 扫掉全仓库文本文件的 BOM
test/test-package-integrity.mjs 也会检查这一点，并核对 files 里声明的每个文件是否
真实存在、exports 指向的入口是否存在、运行时代码有没有 console.log 残留。
凡是依赖真实渲染的行为，都在 DSH 侧边栏的内置浏览器里跑过一遍。做法是先
node scripts/verify-in-browser.mjs --serve 起本地页面，再用 browser_* 工具驱动。
结论（实测通过）：
pointerover, pointerenter, pointerdown, mousedown, pointerup, mouseup, click，
且每个事件恰好一次。只监听 pointerdown 的库（拖拽类、React 合成事件）也能收到。+A）、
Control+a 清空、Enter 在 textarea 里插入换行。browser_type 能写入，编辑键也能作用在可编辑 div 上。browser_snapshot，ref 数量稳定，不随快照次数增长。<a> 会真实导航，落点页面的标题与正文都变了。这几个行为里有三个曾经是真 bug：pointer 事件根本没派发、编辑键只发 keydown
不改值、修饰键被模板字符串的反斜杠吞掉导致 Control+a 解析成 +a。
scripts/ 下这几个只在开发和维护时用，发布产物里不含它们：
| 脚本 | 用途 |
|---|---|
ensure-browser.mjs | 起一个测试用的 Chrome，供需要真实页面的套件使用 |
strip-bom.mjs | 扫掉全仓库文本文件的 BOM（见上节，DSH 会因此拒绝安装） |
verify-in-browser.mjs | 生成内置浏览器实机验证用的页面，--serve 起本地服务，--check 自检 |
audit-tools.mjs | 核对「工具 → 方法 → 客户端处理器」这条链有没有断的 |
audit-plugins.mjs | 扫一遍本地 profile 里装了哪些插件、版本与兼容性 |
wrap-client-iife.mjs | 把客户端 bundle 包成 IIFE，避免与同页其他插件顶层声明撞名 |
verify-isolation.mjs | 验证包成 IIFE 后，与别的插件声明混在同一个 script 里仍能解析 |
插件可以直接从 GitHub 或 npm 安装，不需要任何注册步骤。如果要被那些索引 GitHub 的社区
插件市场收录，仓库带上 dsh-plugin topic 即可，它们会按自己的节奏重新扫描。
browser_status / browser_open_panel 按当前对话判断面板，别的对话的面板不再算数。autoOpenPanel 此前只声明未生效，现在关闭后命令不会自动打开面板。MIT