Chrome 代理浏览器
简体中文 | English
一个给 DeepSeek Harness 用的、接近 Codex 体验的浏览器操作器： 通过 Chrome DevTools 协议直接驱动你本机已安装的 Chrome / Edge，窗口真实可见，随时可以接管。
DSH >=0.2.0-rc.1 <0.3.0 · Node >=22 · MIT ·
安装
需要 DSH 0.2.0-rc.1 ~ 0.2.x、Node 22 以上，以及 Chrome / Chromium / Edge。没有构建步骤，也没有运行时依赖。
# npm（推荐）
dsh plugin --profile <profile> add dsh-browser-agent@0.1.0
# 直接从 GitHub 安装
dsh plugin --profile <profile> add github:naije-c/dsh-browser-agent#v0.1.0
# github.com 慢或被墙时，用 release 的 tarball 地址
dsh plugin --profile <profile> add https://codeload.github.com/naije-c/dsh-browser-agent/tar.gz/refs/tags/v0.1.0
# 或者链接本地目录
dsh plugin --profile <profile> add file:D:/path/to/dsh-browser-agent
桌面版在 插件 → 添加插件 的输入框里填同样的 spec 即可，然后启用这个 bundle。之后就可以直接说：
打开 example.com，读一下页面，第一条链接是什么？
npm 包名是 dsh-browser-agent；加 @0.1.0 锁版本，不加则跟随最新发布。
和别的方案比
| 本插件 | 代价 | |
|---|---|---|
| 浏览器 | 用你已安装的 Chrome / Edge | 不下载 Chromium、不装 Electron |
| 隔离 | 独立 profile：%LOCALAPPDATA%\dsh-browser-agent\profile |
不碰你日常的 cookie |
| 读取 | 页面侧 Map 保活的 ref（#7） |
点击不用重新快照 |
| 输入 | 元素中心的真实鼠标 / 滚轮 / 键盘事件 | 框架表现与真人一致 |
| 视觉 | 截图以附件图片返回 | 模型能看到布局而不只是文字 |
| 体量 | 12 个小工具 | 无第三方运行时、不改宿主 |
工具
| 工具 | 作用 |
|---|---|
browser_status |
解析到的可执行文件、profile、连接状态、标签页列表 |
browser_open |
导航（裸域名补 https）并等待加载 |
browser_read |
URL、标题、滚动位置、带 ref 的可交互元素、可见文本 |
browser_click |
按 ref 真实左键点击；无盒元素回退到 DOM click |
browser_type |
聚焦输入框、替换内容（Input.insertText），可选回车 |
browser_key |
Enter、Tab、Escape、PageDown、Control+A… |
browser_scroll |
向上/向下滚轮 |
browser_history |
当前标签页前进 / 后退 |
browser_tabs |
list / new / select / close |
browser_eval |
在页面执行表达式并返回 JSON |
browser_wait |
固定延时、选择器或可见文本 |
browser_screenshot |
视口或整页 PNG |
配置
每个字段都有可用默认值，在 profile 补丁里覆盖该行即可。
| 字段 | 默认 | 含义 |
|---|---|---|
chromePath |
自动探测 | 浏览器可执行文件绝对路径 |
userDataDir |
%LOCALAPPDATA%\dsh-browser-agent\profile |
agent 专用 profile 目录 |
browserUrl |
空 | 附着到已开调试端口的浏览器，如 http://127.0.0.1:9222 |
headless |
false |
不显示窗口 |
windowWidth / windowHeight |
1280 / 900 |
启动窗口尺寸 |
maxElements |
150 |
browser_read 默认元素上限 |
navigateTimeoutMs |
20000 |
导航等待预算 |
screenshotDir |
系统临时目录 | 无附件服务时 PNG 落盘位置 |
# ~/.dsh/profiles/<profile>/cordis.patch.yml
- id: browser-agent
name: 'dsh-browser-agent'
config:
headless: false
windowWidth: 1440
接管你正在用的 Chrome（扩展模式）
Chrome 136 起禁止在默认 profile 上开 --remote-debugging-port，所以默认的「独立 profile 启动」只能拿到一个空 profile。扩展模式改由浏览器扩展自己发起调试会话（chrome.debugger），于是可以直接操作你日常那个窗口——登录态、扩展（比如 Tampermonkey）、已开的标签都在。
- 把插件行配置改为
transport: extension并重载该插件； - 调一次
browser_status，记下它打印的 bridge 地址 与 token； chrome://extensions→ 开右上角「开发者模式」→「加载已解压的扩展程序」→ 选仓库里的extension/目录；- 点扩展图标，填端口与 token，点 Save and reconnect；
- 再调
browser_status，看到extension: connected就成了。
这个模式里 browser_open 默认新开标签，不会劫持你当前的页面。Chrome 顶部会出现「正在调试此浏览器」横幅；agent 此时能读到你所有已登录站点，用完卸载扩展或把配置改回 transport: spawn 即可。通道细节与排障见 extension/README.md。
用已登录的浏览器
agent profile 初始为空，第一次登录后会保存在该 profile 里，后续复用。
若想用它直接以你日常身份浏览，就把带调试端口的 Chrome 起在另一个目录，然后配 browserUrl：
& "$env:ProgramFiles\Google\Chrome\Application\chrome.exe" `
--remote-debugging-port=9222 `
--user-data-dir="$env:TEMP\chrome-agent-profile"
Chrome 136 起不允许在默认 profile 上开调试端口，所以必须换目录；需要带登录态时，
在 Chrome 关闭状态下把日常 profile 的 Local State 与 Default\Cookies 拷过去。
安全与隐私
- agent 共用一个浏览器 profile，它创建的 cookie 会跨会话保留。不要把
userDataDir指向个人 profile。 - 页面文本、截图、
browser_eval的结果会作为普通工具结果发给你自己配置的模型； 除此之外没有任何数据外流：本插件没有遥测，也不调用外部服务。 browser_eval会在页面里执行任意 JavaScript。- 页面没渲染出来的东西它看不到；付款、发布这类不可逆操作仍建议人来看一眼。
排障
| 现象 | 原因与处理 |
|---|---|
connection to github.com timed out after 5000ms |
DSH 对 Git spec 会先跑 5 秒 git ls-remote 预检。改用 npm 或上面的 tarball 地址，或把 plugin-manager 行的 githubConnectionTimeoutMs 调大 |
EPERM: rename …node_modules\<name>_tmp_… |
之前 link: 安装残留的 junction。cmd /c rmdir <profile>\node_modules\dsh-browser-agent 清掉后重试 |
窗口打开后一直 about:blank |
站点还没提交（被墙、验证码页）。返回的 URL 就是实情；在可见窗口里过掉验证码再继续 |
Page.captureScreenshot 要重试 |
后台标签页可能不给帧；插件会先把页面提到前台并回退到软件抓取，再调一次通常就好 |
| 升级后工具消失 | bundle 每个 Host 进程只加载一次。禁用再启用该行，或重启 DSH |
npm 上看到两个版本（0.0.0-stage 与真实版本） |
首次发布时 npm 自动加的占位版本，latest 指向真实版本；不要 @0.0.0-stage |
开发
node --check index.js && node --check lib/cdp.js && node --check lib/page.js
node test/expressions.test.mjs # 页面侧表达式（DOM shim）
node test/cdp-probe.mjs # 针对运行中浏览器的 CDP 往返
node scripts/screenshot.mjs <url> <out.png> [--viewport]
test/fixture.html 与 test/long.html 是这些检查用的确定性页面；CI 在 Node 22 上跑语法与单测。
index.js 插件入口：配置 + 12 个 browser_* 工具
lib/cdp.js DevTools 客户端、Chrome 探测/启动/重连
lib/page.js 页面侧快照与 ref 解析（注入源码）
locale/ 中英文插件元数据
cordis.patch.yml 本 bundle 插入的行
test/ 确定性 fixture 与离线检查
scripts/ 开发用脚本
发布
发版由 GitHub Actions 完成，用 npm trusted publishing（OIDC），不需要任何 token：
- 改
package.json的version并提交； git tag -a v0.1.1 -m "v0.1.1" && git push --tags；- release.yml 先校验「tag 与 manifest 版本一致」，跑语法检查和页面侧单测，再执行
npm publish --provenance。
前置条件只需配一次：在 npm 包页面的 Access 里添加 Trusted Publisher —— owner naije-c、repository dsh-browser-agent、workflow release.yml。未配置时工作流会停在发布这一步，不会留下半成品版本。
已验证
DSH 0.2.1-rc.2（desktop profile）、Chrome 157.0.8103.39、Windows 11。
| 检查 | 证据 |
|---|---|
| 安装与激活 | 安装后多次禁用/启用均返回 application: applied；npm tarball 安装 1.6 秒完成 |
| 启动本机 Chrome | 首次 browser_open 在专用 profile 上拉起 chrome.exe |
| 插件重载后重连 | browser_status 认出旧端口，下一次调用直接重连、不重启浏览器 |
| ref 稳定性 | fixture 页多次读取，#1…#5 不变；只有复选框显示 [unchecked] |
| 真实鼠标 | browser_click #3 让 Count: 0 → 1；点 #4 切换复选框 |
| 中文/emoji 输入 | browser_type #1 输入 DeepSeek 驾驭者 🚀，页面 handler 记录一致 |
| 输入 + 回车 | 百度搜索框提交并跳转 |
| 键盘/滚轮/历史 | End 滚到 2751/2751；滚轮 800px；back 返回 |
| 标签页 | new / select / close 都能切换实际驱动的页面 |
| 截图 | 视口 1899x1209、整页 1214x3454，均以图片形式回传 |
未验证：Plugins 面板里这个 bundle 的标题、描述、图标的实际渲染（资源已安装且可解析，但没有去驱动面板本身）。
路线图
- 侧栏观察面板：实时画面、直接接管、元素点选回填。
- 登录态导入：从日常 profile 拷
Local State与 cookies。 - 控制台与网络读取，服务调试类任务。
许可
MIT。欢迎 issue 与 PR；已发布内容见 CHANGELOG.md。
No comments yet. Be the first to write one.