前言¶
在 DeepSeek Harness（DSH）里做联网或页面相关任务时，模型往往需要「看见页面、点按钮、填表单」。常见做法是外挂 Playwright、用 CDP，或让模型猜 CSS 选择器——这些路径要么和 Harness 右栏内置浏览器脱节，要么定位依据不稳定。社区插件 dsh-browser-control 由维护者 neilweixing 提供，分类为「联网工具」，目标是让模型像 ZCode 那样操作 Harness 内置侧边浏览器（右栏 Browser 标签页）：以 ARIA 快照作为定位器唯一依据，用受信任输入触发真实交互，并返回真实截图。
这是什么¶
dsh-browser-control 是一组注册到 DSH 模型工具表里的 browser_* 工具集。它不替代 CDP 或无头浏览器，而是专门绑定 Harness 窗口内 <webview> 承载的页面：观察来自页内代理计算的无障碍树，每个 ref 对应一次快照里真实存在的元素；点击与按键走 sendInputEvent，在元素视口坐标上触发，而不是 el.click()。
与「枚举前 N 个链接」式自动化相比，README 强调三件事：观察是无障碍树快照；每个 ref 绑定被观察到的元素；输入是受信任的底层事件。
核心功能¶
工具一览¶
安装并刷新 Harness 后，下列工具出现在模型工具表中（作用摘自官方 README）：
| 工具 | 作用 |
|---|---|
browser_open |
打开页面或导航已有标签页；mode: "same-site" 可复用同域标签页 |
browser_tabs |
列出本会话浏览器标签页（URL、标题、加载状态、是否挂载） |
browser_close |
关闭一个标签页 |
browser_nav |
back / forward / reload / stop |
browser_snapshot |
无障碍树，每行一个节点：role、可访问名、状态、ref |
browser_locator |
只检查定位器：匹配数量与目标；用于确认存在与读取当前状态 |
browser_act |
一次一个改状态动作：click / dblclick / hover / fill / type / press / select / check / uncheck / focus / scroll |
browser_read |
读可见文本：整页或某个元素 |
browser_wait |
等待定位器状态、可见文本、URL、加载状态 |
browser_console |
读取 console、未捕获错误、页面尝试弹出的原生对话框 |
browser_screenshot |
真实截图，作为图片返回 |
观察与动作的节奏¶
browser_act 每次只执行一个动作并返回结果。下一步应先再观察：查单个元素时优先 browser_locator（最便宜）；需要新的定位依据时再 browser_snapshot。页面变化后，旧 ref 会被明确拒绝（stale-ref / detached），不会静默点到别的元素。
定位器优先级¶
README 给出的匹配顺序如下：
{ "ref": "e12" }—— 精确，来自最新快照{ "role": "button", "name": "保存" }—— 页面自述{ "testid": "submit-order" }—— 有测试 id 时较稳{ "label": "邮箱" }/{ "placeholder": "搜索" }—— 表单字段{ "css": "..." }—— 兜底，仅在树里确实没有可用 role/name 时
匹配到多个元素会报错并要求收紧定位，而不是用 nth 猜位置。
快照示例¶
无障碍树以紧凑缩进树形式返回，隐藏元素（display:none、aria-hidden 等）不出现。示意结构与 README 一致：
- navigation "Main" [ref=e1]
- link "Home" [href=/home] [ref=e2]
- heading "Products" [level=2] [ref=e4]
- region "Filters" [ref=e5]
- textbox "Search products" [placeholder="Type to search"] [ref=e6]
- button "Apply" [testid="apply"] [ref=e10]
架构简述¶
命令路径为：模型调用 browser_*（Host 半）→ Connection RPC 长轮询 → Client 半（页面内）→ 右栏 Browser 的 <webview> → 页内代理 → 结果（含截图字节）回传。Connection RPC 为浏览器到 Host 的单向设计；命令按 Session 隔离；目标定位使用 Harness 内置标记（如 data-sidebar-right-tab、webview[data-sidebar-browser-frame]）与会话元数据，每次调用重新解析目标，避免导航或重载后句柄失效。
安装与启用¶
插件通过插件管理器从本地包目录安装，README 给出的命令为：
# 插件管理器，参数为本地包目录的绝对路径
plugin_manager install_bundle /绝对路径/dsh-browser-control
将 /绝对路径/dsh-browser-control 换成本地插件包目录的绝对路径。安装后刷新 Harness 页面，让 Client 半加载，工具才会进入模型工具表。改完 index.js / client.js 后，需在插件管理器中移除再安装，然后再次刷新。
当前仓库 package.json 标注版本为 2.0.0，许可证为 MIT。
典型用法思路¶
下面是一套可复现的节奏（具体 URL 与页面内容由你的任务决定）：
- 用
browser_open在侧边浏览器打开目标 https 页面。 - 用
browser_snapshot或browser_wait等待加载完成并取得树与ref。 - 用
browser_locator确认要操作的节点存在且唯一。 - 用
browser_act执行一个动作（例如click或fill）。 - 页面变化后重新快照或 locator，再执行下一步；需要视觉确认时调用
browser_screenshot。 - 调试脚本问题时可用
browser_console查看日志与原生对话框尝试。
插件只接受 http/https，禁止内嵌凭据与指向 Harness 自身地址；页面内容在工具描述与运行时 skill 中一律视为不可信数据。
适用场景与注意¶
适合：在 DSH 会话内让模型操作右栏 Browser、做表单填写、导航、读可见文本、截屏佐证，且希望定位与 ZCode 类「树 + ref + 单步动作」流程一致的场景。
不适合或做不到（README「已知限制」）：
- 不是 CDP：无后台标签、网络拦截、无头模式；能力限于
<webview>的executeJavaScript/sendInputEvent/capturePage。 - 截图要求 Harness 窗口可见，否则
capturePage不返回，插件会快速失败并说明原因。 - 不支持文件上传与下载；
file:页面被拒。 alert/confirm/prompt被拒绝，记录到browser_console并以安全默认值应答。
DSH 生态理念是「一切皆插件」；SkillHub 目录页 为社区站点，与 DeepSeek / 幻方无官方从属关系。插件在当前 DSH 进程权限下运行，安装前请自行查阅 GitHub 源码 与 MIT 许可证，确认符合你的安全与合规要求。
结尾¶
dsh-browser-control 把 Harness 侧边浏览器变成可编排的工具面：无障碍树作定位 ground truth、单步 browser_act、受信任输入与真实截图，适合在 Harness 内完成页面任务而不另起一套浏览器自动化栈。
