📦 浏览器Harness

browser-harness 把 LLM Agent 接到用户已登录、已打开的真实 Chrome——不是 Playwright 起的临时窗口，不是隐私模式，不是清 cookie 的容器。 长寿命 Python 守护进程持有 CDP WebSocket，多个 Agent（Python 或 TS）通过 JSON-line IPC 同时操作同一标签页。

致谢：Chrome 接管 / CDP 握手 / 对话框处理 / 76 个站点 domain-skills 全部来自 Browser Use 团队上游 browser-use/browser-harness。本 skill 仅薄封装。

给 AI 的使用说明（核心） 用户意图 → 命令 用户说什么 → 调用 → 然后做什么

首次 / 安装 / 接到我的 Chrome scripts/run.sh setup 按提示完成 uv tool install + npm install -g browser-harness-ts + browser-harness --setup；最后跑 doctor 确认绿灯

体检现在能不能用 scripts/run.sh doctor 报告：守护进程是否运行、当前标签页 URL/title

在当前页跑这段 JS： scripts/run.sh js '' 把 expr 注入页面上下文执行；返回 JSON 序列化结果

点击 / 滚动 / 输入 / 截图 scripts/run.sh exec '' 通过 bhts -c 跑任意 BH 方法序列；snippet 内 bh 已就绪

截当前页 scripts/run.sh shot [path] 默认 ./shot.png；用户给路径就用该路径

读当前页信息 scripts/run.sh page 输出 {url,title,viewport,scroll,pageSize} JSON

列打开的标签页 scripts/run.sh tabs 排除 chrome:// 等内部页

切到匹配 的标签页 scripts/run.sh switch '' 在 url/title 中匹配；多匹配优先 url 精确包含

开新标签 scripts/run.sh open '' 新建标签 + 等加载完

把文件传到当前页 scripts/run.sh upload '' '' 等价 DOM.setFileInputFiles

之前在 xxx 站做过的事 先读 agent-workspace/domain-skills//.md，再调上述命令 别重摸选择器；优先用沉淀知识

关键约束（必须遵守）

• 共享真实 Chrome，不开新窗口。任何“我帮你启动浏览器”都错。
• 守护进程必须先跑。setup 后需用户至少执行一次 browser-harness --setup（接 chrome://inspect）。失败时跑 doctor，把输出原文贴给用户。
• 不替用户点开 chrome://inspect 链接。守护进程附着时打印的一次性 URL，必须原文转给用户自己点。
• JS snippet 不能闭包外部变量。代码序列化后送 Chrome 执行；看不见 Node 变量。需传参用 JSON.stringify 拼进字符串。
• 写域知识，不写“我做过什么”。发现稳定选择器 / 私有 API / 框架坑，写进 agent-workspace/domain-skills//.md。
• 永不在 domain-skills 文件写 cookie / token / session / 密码——这些目录会进 git。
• CDP 调用无自动重试。网络抖动 / 标签关闭 / Chrome 升级时报错立即抛；把错误原文报给用户。

错误恢复对照 browser-harness daemon "default" not running → 跑 setup；若已 setup，提示重跑 browser-harness --setup failed to discover Chrome /json/version → Chrome 未开远程调试。提示：关 Chrome → setup 会指导重启加 --remote-debugging-port=9222 JavaScript evaluation failed: ReferenceError → snippet 引用页面不存在的变量；先用 js 'document.title' 确认上下文 no element for → 选择器不在 DOM；先 js 查长度，再考虑 iframe（bh.iframeTarget） Target ... not found → 标签页关闭或刷新后 sessionId 失效；调 bh.ensureRealTab() 重附着

配合 domain-skills 工作 agent-workspace/domain-skills//*.md 是“长期记忆”。做站点任务前先读，勿零样本摸索。 上游 76 个站点知识在 browser-harness Python 包内；本机 agent-workspace/domain-skills/ 是你自沉淀，与上游不冲突。写法见 reference.md。

完成证据格式 BROWSER_RESULT

• intent: <用户原话或概括>
• actions: <顺序列 bhts 命令>
• final_page: <最终 URL + title>
• evidence: <截图路径 / 提取数据 / 或 “已写入 domain-skills//.md”>
• caveats: <若某步靠假设而非验证，明说>

安装与依赖 scripts/run.sh setup # 一次性 scripts/run.sh doctor # 验证

安全说明

• 不发送浏览数据到远程，CDP 流量本机闭环。
• AI 可见用户完整登录态；涉敏感页须先获授权，优先只读明确字段。
• 截图仅写本地，勿上传除非用户授权。
• 守护进程监听本机 socket（默认 ~/.cache/browser-harness/.sock），不接远程。
• 共享机器请审计 Chrome 9222 端口。