前言¶
在 DSH（DeepSeek Harness）里做联网或表单类任务时，常见做法是再套一层「浏览器 Agent」：多一个 LLM、多一套 API key，步骤还往往藏在黑盒里。若你希望 DSH 自己的 agent 就是大脑——写出的 Python 留在会话历史里、可读可审计——就需要把浏览器控制面直接注册成会话工具。
dsh-browser-harness（维护者 chaserchan）做的是这件事：把 browser-use 的 Browser Harness 接到 DSH，让 agent 通过 browser_run 执行 Python，在本地驱动真实 Chrome（导航、点击、填表、无障碍树、JS/CDP、截图）。不需要额外的 LLM，也不需要 API key（Autopilot 除外，见后文）。插件在 SkillHub 分类为「联网工具」，仓库 chaserchan/dsh-browser-harness，许可 MIT。
这是什么¶
Browser Harness 不是「又一个 LLM agent」，而是给 coding agent 用的浏览器控制面。DSH agent 写每一行 Python，Harness 在 Chrome 上执行；状态主要落在 daemon 附着的那块标签页上，而不是跨次调用的 Python 进程变量里。
插件当前版本 0.4.4（以 package.json 为准），面向 web profile 的 DSH（engines.dsh 要求 >=0.1.0-rc.6 <0.2.0，Node >=22.13）。
核心功能¶
会话工具¶
| 工具 | 作用 |
|---|---|
browser_run({ code, timeoutMs?, lane? }) |
把一段 Python 交给 Harness 执行；print() 输出即返回值；返回 {ok, exitCode, stdout, stderr, hint}。ok=false 时先读 hint。 |
browser_status({}) |
体检：命令解析来源、模式、BU_NAME/CDP、doctor、autopilot 状态；browser_run 报错时先调它。 |
browser_autopilot({ url, goal, lane? }) |
目标式自动化；仅配置了 TypeSafe API Key 时可用（未配置时工具拒绝，且系统提示词不注入该工具）。 |
插件还会把 函数速查表与操作纪律 注入系统提示词，agent 知道 Harness 侧有哪些函数、哪些不存在。
人机协同（0.2.0 起）¶
典型场景：开发者账号申请、平台注册、复杂表单——agent 能填的自动填，登录/验证码/扫码等交还用户。
流程概括：
agent：打开页面 → show_tab() 让你看到 → form_fields() 摸清表单 → 普通字段自动填
agent：遇到登录/验证码/扫码/支付 → show_tab() + 说明「这步你来」
你： 在浏览器里完成
agent：wait_url_change() 检测跳转 → 继续 → page_brief() 汇报
每个 browser_run 会自动注入 helper（零 import 直调），例如：
ax_list() # 可交互元素 [{role,name,cx,cy}]
ax_click(role=None, text=None)
form_fields()
fill_field(字段名, 值)
show_tab()
wait_url_change(旧url)
page_brief() # {url,title,elements,text}
人机协同需要 看得到 Chrome：默认 dedicated（有头专用浏览器）即可，agent 与你在同一标签页交替操作。
多会话并发：lane 车道（0.3.0 起）¶
多个 DSH 会话共用一个 harness daemon 会抢「当前 tab」。0.3.0 起可为 browser_run 指定 lane：每个 lane = 独立具名 daemon（BU_NAME=<buPrefix>-<lane>）+ 持久专属标签页，跨 lane 可真并行，同一 lane 内调用串行。
browser_run({ code, lane: "apple" }) # 任务 A
browser_run({ code, lane: "router" }) # 任务 B，与 A 并行
单任务可不传 lane（按会话隔离）；多任务并行时为每个并行任务固定 lane 名，同一任务始终带同一 lane。调试可用 browser_status({}) 的 lanes.active，或 browser_run({ code: 'print(list_tabs())', lane: 'apple' }) 查看某车道 tab。
Autopilot（0.4.0，条件启用）¶
配置 TypeSafe API Key 后，可用 Jev（TypeSafe 开源的 System One 浏览器模型，非 LLM）做目标式自动化：
browser_autopilot({ url: "https://...", goal: "完成开发者账号注册并进入控制台" })
没配 key：工具直接拒绝，模型甚至看不到该工具。配了 key：settings 热加载即可用。执行还需本机安装 jev-ultrafast，并在插件 config 中设置 autopilotCommand（例如 'uvx jev-ultrafast'）。Key 也可通过环境变量 TYPESAFE_API_KEY / TEXT_MODEL_API_KEY（设置面板优先）。
安装与启用¶
1. 安装 Harness CLI（前置）¶
uv tool install browser-use # 完整版（含 agent 库，依赖较多）
# 或更轻的等价物（推荐）：
uv tool install browser-harness # 同一份 harness，依赖只有 4~5 个纯 Python 包
装完建议立刻关闭 Harness 默认遥测（stdout 尾部最多 20KB 会上报）：
browser-use telemetry disable
2. 安装 DSH 插件¶
dsh plugin --profile web add dsh-browser-harness
或从本地路径：
dsh plugin --profile web add file:/path/to/dsh-browser-harness
装完后 dsh --profile web --dump-config 中应出现：
- id: browser-harness
name: dsh-browser-harness
配置要点¶
在 profile 的 cordis.patch.yml 里用 id 定向覆盖（不要 - insert:）：
- id: browser-harness
config:
mode: dedicated # dedicated（默认）| system
command: browser-use # 或 browser-harness，或绝对路径
timeoutMs: 120000
cdpPort: 9334
chromeArgs: ['--proxy-server=http://127.0.0.1:7890'] # 需要代理时
| 键 | 默认 | 说明 |
|---|---|---|
mode |
dedicated |
自起专用 Chrome，与日常浏览器隔离；system 附着正在用的 Chrome |
command |
自动解析 | Harness 可执行文件；建议显式配置（见「已知陷阱」） |
buName |
dsh-browser |
具名 daemon 的后台 tab |
cdpUrl / cdpPort |
空 / 9334 |
自带 CDP 时填 cdpUrl |
userDataDir |
~/.dsh-browser-profile |
dedicated 独立配置目录 |
chromeArgs |
[] |
代理、窗口大小等 |
timeoutMs |
120000 |
单次执行预算，上限 600000 |
restoreTab |
true |
是否用 BU_NAME 独立后台 tab |
autopilotCommand |
空 | jev 运行体命令 |
同配置也可用环境变量：DSH_BROWSER_USE_MODE / DSH_BROWSER_USE_BIN / DSH_BROWSER_USE_PORT / DSH_BROWSER_USE_PROFILE。
TypeSafe / Text Model Key 在 DSH 设置页 → 通用设置 → 浏览器自动化（本插件注册的配置区）。
典型用法¶
最小验证思路¶
browser_status({})确认command、commandSource、模式与 CDP。browser_run({ code: '...' })里写 Harness Python（如打开 URL、print标题）；输出在stdout。- 需要与用户交替操作时，在代码里调用
show_tab()、wait_url_change()等 helper。 - 多会话并行时为各任务固定
lane字符串。
具体 Harness API 以插件注入的速查表为准；README 中的 e2e 思路是「真机打开网页并把 title 打回来」（见仓库 node test/e2e.mjs）。
适用场景与注意¶
适合：需要在 DSH 会话里可复现地操作真实页面——抓信息、填表、半自动注册、与用户在同一 Chrome 标签上协同——且接受「agent 写 Python、Harness 执行」的架构。
权限与安全：browser_run 允许 agent 执行 任意 Python，是代码执行式设计的固有属性；插件不额外提权、不提供沙箱。只在你信任的环境使用；安装前请自行查看源码与 MIT 许可证。插件以当前 dsh 进程权限运行。
已知陷阱（README 原文要点）：
- PATH 上的
browser-use可能是旧版原子 CLI（如 v0.12.3），不认 stdin Python 协议；报错时看browser_status.command与commandSource，并建议显式设config.command。 - 插件已在用户代码前前置
ensure_daemon()，缓解冷启动超时。 - 每次
browser_run是新 Python 进程，变量不跨调用；持久状态在 tab。 - 同一 daemon 只有一个当前 tab；无 lane 时插件内部串行排队。
- dedicated 模式 Chrome 不继承系统代理；外网需
chromeArgs配代理。
结尾¶
dsh-browser-harness 把 Browser Harness 注册为 DSH 工具，本地、无额外 LLM/API key 即可用 Python 驱动 Chrome；可选 TypeSafe key 启用 browser_autopilot。社区目录页：SkillHub - dsh-browser-harness；源码与完整说明：GitHub - chaserchan/dsh-browser-harness。
