dsh-agent-browser
给 DSH 加一个「agent 可共用」的浏览器:右侧栏里是一个真实 Chrome/Edge 的画面(像素流),模型通过 browser_* 工具操作同一个页面。人和 agent 看到的是同一屏、同一份登录态。
怎么用:
docs/usage.md。host 半 + client 半 + 引擎 + 自研 WebSocket / 租约全部在本仓库内实现,运行时零第三方依赖。

说明:「共享登录态」目前指同一个浏览器 profile(插件自己的 profile,可长期登录);接你日常 Chrome 的登录态属于尚未实现的 Copilot 档位。
它和内置 Browser tab / Playwright MCP 的区别
| 内置 Browser tab | Playwright MCP | 本插件 | |
|---|---|---|---|
| 人能看见 | ✅ | ❌ | ✅ 右栏实时画面 |
| agent 能读页面 | ❌ | ✅ | ✅ 快照(e1..eN 引用) |
| 共享人类登录态 | ✅ | ❌ 独立 profile | ✅ 同一浏览器 profile |
| 同一屏协作 | — | — | ✅ 租约(人类可抢占) |
结构
dsh-agent-browser/
├── lib/
│ ├── engine.js 零依赖 CDP 客户端:起浏览器、screencast、快照、点击/输入/滚轮/截图
│ ├── ws.js 零依赖 RFC6455 WebSocket 服务端(帧中转)
│ ├── lease.js 租约:单写者 + 人类抢占 + TTL(agent 30s / 人类 120s)
│ ├── index.js host 半:HTTP 路由 + WS upgrade + 12 个工具
│ └── client.js client 半:右栏 tab(手写 ModuleLoader bundle,只依赖 react)
├── package.json
└── cordis.patch.yml
数据流:Chrome --CDP--> host(engine) --WS 二进制帧--> client <img>;人的点击/滚动 → POST /agent-browser/api/command → CDP;agent → 工具 → 同一个 engine。
工具
| 工具 | 作用 | 租约 |
|---|---|---|
browser_open(url) |
打开网页并返回快照 | 获取 |
browser_snapshot() |
读当前页面(地址/标题/正文/交互元素 eN) | 不占 |
browser_navigate(url) |
跳转 | 获取 |
browser_click(ref | x,y) |
按 eN 引用或视口坐标点击 | 获取 |
browser_type(ref, text, clear?, submit?) |
聚焦并输入(中文走 Input.insertText) |
获取 |
browser_press(key) |
Enter/Tab/Escape/方向键等 | 获取 |
browser_scroll(deltaY) |
滚动 | 获取 |
browser_screenshot(full_page?) |
截图存盘,返回路径 | 获取 |
browser_wait_for(selector? | text?, timeout_ms?) |
等元素/文本出现;超时返回 found=false 而不是报错 |
不占 |
browser_tabs(action, url?, tab_id?) |
list / new / select / close 标签页(不许关最后一个) |
写操作获取 |
browser_eval(expression) |
在页面执行 JS。默认关闭;开启后每次都要右栏批准 + 写审计 | 获取 |
browser_release() |
释放租约 | 释放 |
租约被占时工具不会硬失败重试,而是返回中文提示(谁在占用、可以先 snapshot 观察),避免两个 agent 互相打断。
审批与审计
browser_eval 默认 allowEval: false(工具存在但调用会直接报「已被配置关闭」)。显式打开后:
- agent 调用 → host 通过 WS 广播
{type:"approval", id, title, detail}; - 右栏 pane 弹出遮罩卡片(标题 + 等宽字体显示待执行表达式),用户点「允许执行」或「拒绝」;
- 结果回到 host:允许 → 在页面求值;拒绝/超时(
evalTimeoutMs)/没有打开的客户端 → 抛错给模型; - 无论批准与否都追加一行 JSON 审计:
{at, kind:"eval", owner, expression, approved, reason},默认profileDir/../audit.jsonl。
审计不是只管 eval:每一次工具调用(kind:"tool":工具名 / owner / 耗时 / 入参摘要 / 失败原因)、每一次人类命令(kind:"command")、每一次租约变更(kind:"lease":acquired / preempted / expired / released)、浏览器启停(kind:"session")都会写入同一份 audit.jsonl。
安装
插件是一个普通 npm 包(host 半 + client 半),装进 DSH 的 profile 并登记到 dsh.profile.bundles 后才会被加载:
- 取得插件目录:
git clone本仓库,或npm pack后解包。 - 让 profile 能解析到它——link 到 profile 的
node_modules(或用你惯用的包管理方式安装):$prof = "<DSH_HOME>\profiles\<profile>" New-Item -ItemType Junction -Path "$prof\node_modules\dsh-agent-browser" -Target "<本仓库路径>" - 把包名加进该 profile 的
package.json的dsh.profile.bundles:
(保存为 UTF-8 无 BOM;profile manifest 的"dsh": { "profile": { "bundles": [ "...", "dsh-agent-browser" ] } }JSON.parse对 BOM 敏感。) - 重启 DSH(host 半改动需重启;client 半改动刷新页面即可)。
- 右栏
+里出现「Agent 浏览器」。
卸载
从 dsh.profile.bundles 里删掉 "dsh-agent-browser",移除 profile node_modules 里的链接,重启 DSH。浏览器 profile、截图与审计日志在 profileDir 下,卸载不会自动删除。
配置(cordis.patch.yml 的 config)
| 键 | 默认 | 说明 |
|---|---|---|
viewportWidth / viewportHeight |
1280 / 800 | 兜底视口(没有客户端上报尺寸时用这个)。有右栏 pane 时按面板实际尺寸自动跟随,点击坐标按当前视口换算 |
autoViewport |
true |
是否跟随右栏 pane 尺寸调整浏览器视口;关掉就固定用 viewportWidth/Height |
headless |
true |
无头;调试可设 false 看真窗口 |
executablePath |
自动探测 | Chrome/Edge 路径;自动探测不到时填 |
profileDir |
%LOCALAPPDATA%\dsh-agent-browser\profile |
浏览器用户目录(登录态存这里) |
frameQuality / maxFps |
60 / 30 | 像素流质量与帧率上限(超过丢旧帧;实测滚动可出 40+ fps,30 为清晰度/带宽平衡点) |
hdOnIdle / hdIdleMs / hdQuality |
true / 400 / 80 |
画面静止约 400ms 后补一张按 devicePixelRatio 抓的高清帧(高分屏不发糊);一有运动帧就回到流式 |
idleCloseMs |
600000 | 无人连接时自动关浏览器 |
agentLeaseMs / humanLeaseMs |
30000 / 120000 | 租约 TTL |
leaseWaitMs |
0 | agent 拿不到租约时排队等待上限(0 = 立即返回 busy,由 agent 自己重试;多 agent 场景建议 2000–5000) |
yieldOnContention |
true |
有人在排队时,当前 agent 每次操作完主动让出租约(避免长任务饿死别人) |
allowEval |
false |
是否允许 browser_eval;打开后每次调用仍需右栏批准 |
evalTimeoutMs |
60000 | 等用户批准的超时 |
auditLog |
空 | 审计日志路径;空则写 profileDir/../audit.jsonl |
安全边界
- 只允许
http:///https://(含 loopback),拒绝file:、data:、内嵌凭据 URL。 - 浏览器是独立进程 + 独立 profile,不是 DSH 的 Electron 窗口,页面 JS 碰不到 DSH 的 origin。
- HTTP 路由与 WS upgrade 都先过
ctx.connection.requestRejection(req)(DSH 的会话认证)。 browser_screenshot只写插件自己的 shots 目录。browser_eval默认关闭;开启后每表达式都要用户点「允许执行」,并写审计(表达式 + 批准结果 + 谁发起的)。
已知限制
- 视口默认跟随右栏 pane:窄栏时页面按窄布局重排,点 ⛶ 或让 pane 自动全屏后变成桌面宽度(1280+)。不是"把桌面页缩放进窄栏"。
- 页面若在 iframe 内部,快照脚本只覆盖主框架。
- 首帧要等浏览器进程冷启动(约 1–3s)。
browser_wait_for轮询间隔 150ms,超时上限 60s;browser_eval审批只在右栏 pane 打开时可用(否则直接报"没有客户端")。
排错
- host 半日志在 DSH 的
harness.log,关键字agent-browser:。 - 右栏 tab 不出现:确认 client 半 bundle 已被加载(刷新页面后仍无则重启 DSH)。
- 浏览器起不来:检查
executablePath;残留的DevToolsActivePort会在启动前被清掉。
开发与测试
离线测试不需要安装 DSH、也不需要 Chrome(脚本会自己生成 @deepseek-ai/* 的测试 shim,仅用于解析 import):
node test/run.mjs # 租约 + 排队 + WebSocket + 插件契约,期望 25/25
node test/run.mjs --unit # 只跑纯 JS 单测
需要真实浏览器的测试(会启动本机 Chrome/Edge):
node test/stress.mjs # 多 agent 并发压测:1/2/4 agent 争用 + 人类抢占 + TTL,约 25s
许可证
Apache-2.0,见 LICENSE。
No comments yet. Be the first to write one.