前言¶
在 DeepSeek Harness（DSH）里做需要「看网页、点按钮、填表单」的智能体任务时，常见做法是再挂一套 Playwright 或 Puppeteer，或者通过代理改页面。那样多开一个浏览器进程，和 DSH 右侧栏里用户正在看的页面往往也不是同一份会话。dsh-sidebar-browser-agent 走的是另一条路：把 Agent 的工具接到 DSH Desktop 右侧栏的 Electron <webview> 上，用 executeJavaScript、sendInputEvent、capturePage 和 loadURL 完成读页与操作，不注入代理、不改写 DOM。
下面按「这是什么 → 能做什么 → 怎么装 → 怎么用 → 边界与注意」介绍该插件。事实以 GitHub 仓库 README 与 package.json 为准。
这是什么¶
- 名称：
dsh-sidebar-browser-agent（侧栏浏览器 Agent 控制） - 维护者：Hesitate-P
- 分类：联网工具（社区目录 SkillHub）
- 当前版本：
0.5.5（MIT 许可证） - 定位：让 Harness 里的 Agent 管理右侧栏标签页，并在真实页面上观察、点击、输入、滚动、执行受限 JS、截图。
插件向 Agent 暴露两个工具：sidebar_browser 管标签页与侧栏展示；sidebar_page 管单页内的观察与操作。二者都运行在 Electron 原生 guest 上，而不是无头 Chrome。
核心功能¶
观察页面¶
snapshot 返回紧凑的语义树，节点带 e12 这类 ref；头部包含 viewport、滚动位置和 dpr；会遍历 open shadow root 与同源 iframe，视口外元素标 [offscreen]。
read 可读整页文本、交互元素或 HTML，也可按 ref / CSS selector 读单个元素的文本、属性、状态和包围盒。每次操作结果里附带 view，说明侧栏是否挂载、展开，以及当前标签是否在前台。
使用规则（README 强调）：以 snapshot 为页面事实来源并尽量复用，直到失效；每次只做一个会改状态的动作；eval 仅作最后手段，不用它读页、枚举元素或探测选择器；截图只在需要视觉证据时使用。
操作页面¶
定位支持 ref、CSS selector、可见文本或 x/y 坐标。动作包括 click、dblclick、rightClick、hover、focus、clear、type（填值或真实键盘输入）、press、selectOption、check/uncheck、drag、scroll、scrollIntoView 等。
会改变页面状态的动作返回 observed，记录 URL/标题/滚动变化、DOM 变更计数、新标签、焦点和录到的对话框，多数情况下不必立刻再 snapshot 整页。
等待、导航与批量¶
提供 waitForSelector、waitForLoadState、waitForURL、waitForNavigation。open / navigate / reload / back / forward 可带 waitUntil。batch 在一次调用里顺序执行多步页面动作（不可嵌套，且不能包含 screenshot / upload / download）。
截图与标签页¶
截图支持 viewport、clip 与整页 fullPage，以图片附件返回。list 返回各标签的 title、url、loading、zoom、viewport 等；open 可用 reuse 复用同站标签；show / hide 控制侧栏展开；另有 zoom、viewport、finalize（deliverable / handoff 标记）。
对话框、视口、历史与文件¶
页面内 alert / confirm / prompt 由桥接记录，不阻塞系统弹窗；用 dialog 读取记录并设置 dismiss / accept / answer 策略。viewport 可调整 guest 尺寸做响应式检查，reset 恢复。
download 在页面会话内 fetch（保留登录 Cookie），经环回流式写入 Host 的 Downloads 或指定 path。upload 从 Host 经环回把本地文件流注入页面，附加到 <input type=file> 或拖放区，不弹系统文件选择框；受 profile 中 allowUploads 等配置约束。
安装与启用¶
插件要求 DSH 版本范围为 >=0.2.2-rc.1 <0.3.0，Node >=20。在目标 profile 下执行：
dsh plugin --profile <profile> add dsh-sidebar-browser-agent
将 <profile> 换成你实际使用的 DSH profile 名称。安装前建议在 GitHub 仓库 查看源码与 MIT 许可证；插件以当前 dsh 进程权限运行，与其他 DSH 插件相同，安装前应自行评估信任边界。
客户端通过 cordis.patch.yml 注入 @deepseek-ai/dsh-client-ui-sidebar-right，在 Web 端可管理标签，页面内容级操作需要 DSH Desktop（Electron 原生 webview）。
典型用法思路¶
README 未给出单条复制即跑的 CLI 示例，但 Agent 侧的工作流可以概括为：
- 用
sidebar_browser的open/list/show打开或聚焦右侧栏标签。 - 用
sidebar_page的snapshot建立当前页的 ref 地图。 - 按 ref 或 selector 执行单次 click、type、
scrollIntoView等，读返回的observed判断是否已跳转或 DOM 已变。 - 需要证据时再
screenshot；需要稳定 DOM 时用waitForSelector或waitForLoadState，而不是连续eval轮询。
多步固定流程可打包进一次 batch 调用，减少往返。跨步骤复用同一次 snapshot 里的 ref，避免在新快照后仍使用旧 ref（会得到 [stale-ref]）。
适用场景与限制¶
适合：需要在 DSH 会话里让 Agent 操作用户侧栏里「真实打开的页面」——例如查资料、填内网表单、在已登录站点上下载文件（走页面 Cookie 的 download），且希望与 Playwright 并列进程解耦的场景。
不适合或需注意：
- 只操作 DSH 右侧栏原生浏览器，不能控系统 Chrome/Safari，也不是无头浏览器。
- Web 版 DSH 只能管理标签，不能读点页面内容。
- 页面文本是数据而非指令；不要把页面内容直接塞进
eval。 - 截图时会话须可见；
fullPage会短暂 resize guest；页面 CSS 高度超过 20000 px 时截图为截断并标记 truncated。 eval、原生输入、上传、域名白名单受 profile 配置约束；上传单文件 ≤256 MB、单次合计 ≤512 MB 等限制见 README。- 只能访问宿主侧栏浏览器允许的 HTTP(S) 页面。
社区目录（SkillHub）是独立的插件索引站点，与 DeepSeek / 幻方无官方从属关系；当前 GitHub 星标约为 1，选型时可结合仓库 Issues 与 CHANGELOG 自行判断维护节奏。
结尾¶
dsh-sidebar-browser-agent 把 Agent 工具直接绑在 DSH 右侧栏 Electron webview 上，用 sidebar_browser 与 sidebar_page 完成读、点、输、滚、截图和标签管理，避免再为侧栏页面单独起一套浏览器自动化栈。安装命令见上文；详细 API 与变更记录以仓库为准。
- 目录页：https://www.skillhub.cn/plugins/Hesitate-P/dsh-sidebar-browser-agent
- GitHub：https://github.com/Hesitate-P/dsh-sidebar-browser-agent
