前言¶
DeepSeek Harness（DSH）右侧栏自带 @deepseek-ai/dsh-client-ui-sidebar-browser：用 Electron <webview> 渲染真实网页，带地址栏、历史与独立会话。官方能力主要停在导航——Agent 能打开页面，却无法在用户眼前那张页面上点击、输入、读取正文或滚动。
若直接改 DSH 官方 bundle，每次升级都要重打补丁，还可能影响侧边栏链接等行为。社区插件 dsh-live-browser（维护者 c347087870，分类：客户端）在不修改 DSH 任何文件的前提下，向官方侧边栏浏览器挂载的 guest 文档注入操作接口，并向模型注册 25 个 browser_* 工具，操作的正是当前 Session 侧边栏里用户正在看的那一页。
这是什么¶
dsh-live-browser 是 DSH 服务端插件（package.json 中 dsh.kind 为 server，客户端 bundle 平台为 web）。当前仓库版本 0.3.0，许可证 MIT，依赖 Node.js ≥20，面向 DSH 0.2.x。
一句话：真实 webview 渲染 + 注入命令层，让 Agent 对侧边栏浏览器做快照、交互、导航与有限导出，且按「一个对话一个浏览器」绑定 Session，避免命令跑到别的对话面板。
核心功能¶
与官方侧边栏浏览器的关系¶
插件不替换官方组件，而是找到 webview[data-sidebar-browser-frame="webview"]，向每个 guest 注入 lib/agent-script.js（纯 DOM：快照带稳定 ref、点击、输入、按键、选择、悬停、滚动、读正文、等待、文件附加、canvas/SVG 转 PNG 等），并通过桥接把宿主侧工具调用排到客户端执行。
25 个 browser_* 工具（摘要）¶
| 类别 | 工具 |
|---|---|
| 状态与面板 | browser_status、browser_open_panel |
| 导航 | browser_navigate、browser_back、browser_forward、browser_reload |
| 读页 | browser_snapshot、browser_read_text |
| 交互 | browser_click、browser_type、browser_press、browser_select、browser_hover |
| 滚动与等待 | browser_scroll、browser_wait |
| 脚本 | browser_eval（受 allowEval 控制） |
| 导出 | browser_screenshot（canvas/SVG/元素栅格化，非原生窗口截屏） |
| 标签页 | browser_tabs、browser_tab_new（无 tab 参数指定其他标签；焦点 guest 或最新 guest） |
| 文件 | browser_upload、browser_downloads |
| 确认 | browser_confirm（敏感动作，配合 confirmSensitive） |
自动打开侧边栏浏览器¶
Agent 不会要求用户先手动开浏览器，也不会开系统外部窗口。命令进入队列后，客户端 bundle 持续轮询；若当前 Session 没有浏览器页面，会调用 openTabIn(sessionId, 'browser', …) 在发起请求的对话里打开标签页，guest 就绪后再执行。冷启动时一句 browser_navigate 即可在右侧栏弹出标签并加载 URL。
与「改官方 bundle」的对比（README 归纳）¶
| 本插件 | 直接改官方 bundle | |
|---|---|---|
| 点击 / 输入 / 读取 / 滚动 | 可以 | 可以 |
| 页面图表导出 PNG | 可以（页面 canvas/SVG） | 可以 |
| 截原生窗口 | 不行 | 可以 |
| DSH 升级 | 可继续使用 | 需逐版重补丁 |
| 对现有功能风险 | 无 | 可能破坏侧边栏链接等 |
已知限制（结构化失败，不假装成功）¶
browser_tab_close/browser_tab_activate：侧边栏标签 id 内部不可控，需用户手动点标签。browser_reset_profile：无会话清理 API，工具返回操作说明。- 原生窗口像素：
browser_screenshot走 DOM 层栅格化，适合图表类内容。
安装与启用¶
需要 DSH 0.2.x 与 Node.js 20 以上。插件在 package.json 里声明了 DSH 组合包，安装时 DSH 会自动注册。
从 GitHub 安装（Web / CLI profile）¶
dsh plugin --profile web install c347087870/dsh-live-browser
桌面版 profile 由 Electron 应用独占：在界面 插件 → 添加插件，粘贴 https://github.com/c347087870/dsh-live-browser，然后重启 DSH。
从 npm 安装¶
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
若 /dsh-live-browser 路由返回 HTTP 405，通常表示插件未加载（需重启；宿主工具仅在进程启动时注册）。
本地开发不要用目录 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 |
空 | 截图目录；空则 ~/.dsh/storages/dsh-live-browser/images |
downloadsDir |
空 | 下载列表目录；空则系统「下载」文件夹 |
只读页面、禁止在页内跑代码时，将 allowEval 设为 false：browser_eval 会返回 executed: false，并提示改用 browser_snapshot / browser_read_text。
典型用法¶
下面介绍一种可复现的冷启动流程（与 README「浏览器会自己打开」一致）。
- 安装插件并重启 DSH，确认日志中出现 25 个工具加载信息。
- 在某一 Session 中让 Agent 调用
browser_navigate，传入目标 URL；若无打开页面，右侧栏会自动出现浏览器标签并加载。 - 用
browser_snapshot获取带ref的节点列表，再用browser_click、browser_type等按ref或选择器交互。 - 需要正文时用
browser_read_text；需要等待元素或延迟时用browser_wait。 - 图表类页面导出 PNG 时用
browser_screenshot（依赖页面 canvas/SVG，不是整窗截屏）。
开发与维护侧可用本地页面做实机验证（README 开发脚本）：
node scripts/verify-in-browser.mjs --serve
再用 browser_* 工具驱动 DSH 侧边栏内置浏览器；该脚本属于仓库 scripts/，不在发布产物 files 列表内，需从 GitHub 源码树获取。
工作原理（简述）¶
工具调用经 lib/bridge.js 入队，客户端 client.js 长轮询：无 guest 则开侧边栏浏览器；页面命令注入 guest 脚本；浏览器命令操作 guest 元素（如 loadURL）；标签页命令走侧边栏服务。结果经 settle 回到工具层。面板 HTTP 走 lib/rpc.js 注册的 /dsh-live-browser 前缀路由，请求校验同源与回环主机。
安全与权限¶
插件以当前 DSH 进程权限 运行，能读写与你本机用户相同的文件范围（路由虽拒跨站与非回环调用方，本机进程仍可伪造相关头）。安装前应阅读仓库源码与 MIT 许可证，并理解：
browser_eval可在当前加载的任意页面执行 JavaScript，这是工具设计目的，也是allowEval存在的原因。confirmSensitive开启时，敏感动作需用户确认；无确认通道时拒绝而非放行。
适用场景与注意¶
适合：需要在 DSH 窗口内完成「看同一页网页 + Agent 自动化」的开发者；希望随 DSH 升级而少改动的侧边栏浏览器自动化；表单填写、读页、站内图表导出等 DOM 层任务。
不适合或需知：依赖关闭/切换指定标签页 API、清理浏览器 profile、或整窗像素截屏的场景；对 browser_eval 有严格禁用时需关闭 allowEval 并改用快照与读文本。
安装注意：package.json 等文件若带 UTF-8 BOM，DSH 可能拒绝安装并报 JSON 解析错误；仓库提供 npm run strip-bom 供维护者使用。改插件源码后必须重启 DSH，工具与路由不会热加载。
结尾¶
dsh-live-browser 补上了 DSH 官方侧边栏浏览器在 Agent 侧的交互缺口：不改 DSH 本体、按 Session 驱动用户眼前的 webview，并提供可配置的安全边界。插件托管于 GitHub，社区目录页可检索安装说明与元数据。
- 目录页：https://www.skillhub.cn/plugins/c347087870/dsh-live-browser
- GitHub：https://github.com/c347087870/dsh-live-browser
