前言¶

在 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_act 每次只执行一个动作并返回结果。下一步应先再观察：查单个元素时优先 browser_locator（最便宜）；需要新的定位依据时再 browser_snapshot。页面变化后，旧 ref 会被明确拒绝（stale-ref / detached），不会静默点到别的元素。

定位器优先级¶

README 给出的匹配顺序如下：

1. { "ref": "e12" } —— 精确，来自最新快照
2. { "role": "button", "name": "保存" } —— 页面自述
3. { "testid": "submit-order" } —— 有测试 id 时较稳
4. { "label": "邮箱" } / { "placeholder": "搜索" } —— 表单字段
5. { "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 与页面内容由你的任务决定）：

1. 用 browser_open 在侧边浏览器打开目标 https 页面。
2. 用 browser_snapshot 或 browser_wait 等待加载完成并取得树与 ref。
3. 用 browser_locator 确认要操作的节点存在且唯一。
4. 用 browser_act 执行一个动作（例如 click 或 fill）。
5. 页面变化后重新快照或 locator，再执行下一步；需要视觉确认时调用 browser_screenshot。
6. 调试脚本问题时可用 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 内完成页面任务而不另起一套浏览器自动化栈。

• 目录页：https://www.skillhub.cn/plugins/neilweixing/dsh-browser-control
• 源码与文档：https://github.com/neilweixing/dsh-browser-control