try-works/dsh-browser-agent

@try-works/dsh-browser-agent

一个 DeepSeek Harness (DSH) 插件，为你的智能体提供一个真实、可控的
Web 浏览器——一个共享的 Chrome 页面、一个无需密钥的搜索与抓取层级、一个实时
可供人工观看的面板，以及一个凭据隔离的“工作模式”，用于登录和
填写表单，而智能体全程无需看到你的用户名或密码。

运行 DSH 的智能体将获得 25 个工具——15 个浏览器工具、6 个网络/搜索工具，
以及 4 个工作模式工具——它们全部驱动一个共享的 Chrome 页面，该页面在多次调用之间持续存在，
此外还有一个实时面板停靠在 DSH Web GUI 内，实时流式传输
该页面，并让你用真实的鼠标和键盘输入接管操作。

它是什么

这是一个用于 DeepSeek Harness
（由 Cordis 组合）的插件包。它从单个组合行挂载，并分为两
部分：

- 宿主部分（Node 进程）——运行 Chrome（通过
puppeteer-core），注册
25 个工具、打包的技能，以及面板的 HTTP 路由。
- 客户端部分（浏览器包）——面板 UI，挂载到 Web GUI 的
shell.overlay 插槽中。

它是 zenbu-labs/terminal-browser
的一个分支，将终端 UI 替换为 DSH 工具界面和 Web 面板——理念相同
（像素输出，合成输入），构建在 harness 自身的插件、模块
和插槽系统之上。网络搜索层级移植了
dabito/pi-lynx（MIT）的无需密钥引擎链。

为什么重要

只读取文本的智能体难以应对现代 Web：JavaScript 渲染的
页面、登录墙、机器人防护、表单，以及任何需要真实浏览器
会话的内容。此插件通过为智能体提供一个具备其全部能力的真实 Chrome 来弥合这一差距，
同时通过面板让人类保持在环路中，并通过一个隔离凭据的安全层加以保障。Chrome 作为
独立的操作系统进程由插件启动，因此浏览器崩溃绝不会
拖垮 harness——下一次调用只需重新启动即可。

它能做什么

- 一个真实、持久的浏览器——一个共享的 Chrome，可拥有任意数量的标签页
且只有一个处于活动状态。导航、读取、点击、输入、等待、截图、检查
无障碍树，以及管理标签页；页面在多次调用之间保持不变。
- 无需密钥即可搜索——纯 HTTP 搜索与抓取，带有引擎链
（DuckDuckGo Lite → Brave HTML → Mojeek，自动回退）以及 Reddit
访问。无需 Chrome、无需 API 密钥、无需 JS 渲染——最廉价的研究途径。
- 供人类使用的实时面板——DSH Web GUI 中一个右侧停靠、可折叠、可调整大小的窗口，
通过 CDP screencast 流式传输共享页面，并接收
你真实的鼠标/键盘输入。随时观看智能体浏览并接管。
- 工作模式——凭据隔离的 Web 自动化：一个高风险点击审批
门、一个机密防火墙、受监督的登录，以及一个加密的会话保险库
（见下文）。
- 对机器人墙友好 — 三种启动模式：headless（你自己的）、stealth
（我们自己的有头 Chrome，无自动化指纹），以及 My Chrome
（连接到一个你启动的 Chrome，沿用其真实登录状态和身份 ——
这种模式能通过 Cloudflare Turnstile）。
- URL 规范化 — 工具和地址栏接受 URL、主机名、
localhost:port、本地文件路径，或纯搜索文本。

使用场景

- 需要真实页面的研究 — 阅读 JS 渲染的文章、提取
结构化数据、比较商品列表，或抓取浏览器会话背后的 API。
先从无需密钥的网络工具开始；遇到墙时再回退到浏览器。
- 测试和验证你自己的 Web 应用 — 驱动一个正在运行的前端：导航、
填写表单、点击、等待异步内容，然后 browser_screenshot 结果
以确认渲染或布局。实时窗格让你和智能体观看
同一个页面。
- 代表你登录 —— 无需分享你的密码 —
work_login_ 流程让你在窗格中输入凭据，而智能体
被锁定在外，然后仅将会话 cookie 封存进加密保险库。
智能体之后可以恢复该会话，且从未见过密码。
- 事务性 Web 工作流 — 预约（DMV、医生、
牙医）、提交保险理赔、填写多字段的政府或供应商
表单。风险点击门控会在有后果的提交前暂停，让你
亲自批准。
- 检查登录后的站点 — 你的订阅、仪表盘或收件箱
（Gmail、GitHub、某个 SaaS 控制台）。通过窗格登录一次；保险库保留
该会话，work_vault_status 列出它而不暴露值，且
智能体可以重新打开它。

工具一览

全部 25 个工具，分组如下：

- Browser（15 个）：browser_goto、browser_evaluate、browser_screenshot、
browser_click、browser_type、browser_read、browser_wait、
browser_back、browser_forward、browser_reload、browser_a11y、
browser_tabs、browser_tab_open、browser_tab_switch、browser_tab_close。
- Net / search（6 个）：browser_fetch、browser_search、
browser_search_github、browser_search_wikipedia、browser_reddit_search、
browser_reddit_thread。
- Work Mode（4 个）：work_login_begin、work_login_cancel、
work_login_status、work_vault_status。

每一个都在下面的章节中有完整文档。

安装

先决条件：一个带有 profile 的 DSH 部署（窗格需要 Web 界面；
这些工具在任何界面上都能工作）。

install from the npm registry into a profile (the DSH CLI forwards to pnpm
in the profile directory, then reconciles the profile's plugin bundles)
dsh plugin --profile web add @try-works/dsh-browser-agent

插件自身的 bundle 补丁会自动挂载该行 —— 无需手动
编辑 composition。然后重启 dsh web并强制刷新
GUI 标签页（Ctrl+F5），以便获取客户端窗格 bundle。这三个
browser_ 工具会出现在 agent 的工具集中，并且该窗格停靠在 GUI 的右边缘。

新版本发布与供应链策略 — DSH profile 会启用 pnpm 的
minimumReleaseAge 检查。发布时间不足 24 小时的版本会被拒绝，除非它被列在
profile 的 pnpm-workspace.yaml 中：

minimumReleaseAgeExclude:
- '@try-works/dsh-browser-agent@0.2.0||0.2.1'

每个包名一条规则 — 多个版本放在同一行的单个 || 并集中；同一包名的多行会相互遮蔽，只有第一行生效。

本地开发

dsh plugin --profile web add link:D:/path/to/dsh-browser-agent

配置

所有字段都是可选的（schemastery 默认值会填充它们）。通过 profile 的
cordis.patch.yml 覆盖：

- id: dsh-browser-agent
config:
chromePath: 'C:\Program Files\Google\Chrome\Application\chrome.exe'
viewport: { width: 1920, height: 1080 }
navTimeoutMs: 45000
scriptTimeoutMs: 20000
timeoutMs: 60000
headed: false
pane: true

| 字段 | 默认值 | 用途 |
| --- | --- | --- |
| chromePath | Windows 上的系统 Chrome | Chrome/Chromium 可执行文件的绝对路径。 |
| viewport | 1920 × 1080 | 新页面的默认视口（以及有头窗口大小）。 |
| navTimeoutMs | 45000 | page.goto 导航超时。 |
| scriptTimeoutMs | 20000 | page.setDefaultTimeout（脚本/求值超时）。 |
| timeoutMs | 60000 | 每个工具的执行超时。 |
| headed | false | 启动一个可见的 Chrome 窗口，而不是无头模式。该窗口与窗格显示的是同一个共享页面 — 同一个浏览器的两个视图。需要桌面会话。 |
| pane | true | 在 Web GUI 中提供浏览器窗格。无头/TUI 组合没有 Web 服务器，因此无论如何窗格都不会在那里挂载。 |
| userDataDir | ''（临时 profile） | Chrome profile 目录。为空 = 每次启动使用全新的临时 profile。设置绝对路径可在多次启动之间持久化 cookie、登录状态和存储（注意：没有过期时间的会话 cookie 仍然仅在会话内有效）。 |
| connectUrl | ''（禁用） | 用于 My Chrome 模式的 CDP 浏览器 URL。设置后，窗格的模式切换可以连接到你自己用 chrome.exe --remote-debugging-port=9222 --user-data-dir= 启动的 Chrome，采用其真实标签页、登录状态和指纹 — 这是能通过机器人防护墙（例如 Cloudflare Turnstile）的模式。在连接模式下，启动标志会被忽略。 |
| stealth | false | 隐身插件模式：启动我们自己的 Chrome，不带 --enable-automation（因此 navigator.webdriver 为 false）、有头模式、禁用 AutomationControlled、持久化 profile。相比普通 puppeteer，对抗机器人墙的成功率高得多，但仍不是你的个人指纹 — 要确保万无一失，请使用 My Chrome 模式。 |
| searchEngines | 'ddg,brave,mojeek' | 网络搜索工具的引擎链，按顺序尝试：ddg（DuckDuckGo Lite）、brave（Brave HTML）和 mojeek（Mojeek——对数据中心 IP 最宽容）。 |
| siteSearchIntervalMs | 3000 | 连续网络搜索之间的最小延迟（出于速率限制的礼貌考虑；适用于每次搜索，而不仅是站点过滤搜索）。 |
| fallbackOnEmpty | true | 当一个引擎返回无结果时，继续使用下一个引擎。 |
| fetchTimeoutMs | 15000 | 网络工具（fetch/search/reddit）的每请求超时时间。 |

网络工具（无需密钥的搜索与抓取）

网络层是 pi-lynx 引擎链的移植（browser_search =
DuckDuckGo Lite → Brave HTML → Mojeek，带自动回退），外加
纯 HTTP 页面抓取和 Reddit 访问——无需 Chrome、无需 API 密钥、无需 JS
渲染。这些是研究中最廉价的途径；browser-search
技能的分诊会将它们排在首位，并在数据中心 IP 被限流时降级到浏览器工具。

| 工具 | 功能 |
| --- | --- |
| browser_fetch | 通过纯 HTTP 将 URL 抓取为可读文本：{url, finalUrl, status, text, truncated, links}。 |
| browser_search | 搜索网络：返回排序后的 {title, snippet, domain, url} 行，以及引擎提供的即时答案（如有）。site: "github" \| "wikipedia" \| 、engine: "auto" \| "ddg" \| "brave"、maxResults。 |
| browser_search_github | 限定于 github.com 的 browser_search——仓库、issue、讨论。 |
| browser_search_wikipedia | 限定于 en.wikipedia.org 的 browser_search。 |
| browser_reddit_search | Reddit 帖子搜索（优先 old.reddit HTML，回退到公开 JSON 搜索）：标题、subreddit、作者、得分、评论数、永久链接。 |
| browser_reddit_thread | 通过公开 .json 端点获取 Reddit 帖子：帖子字段加热门评论。 |

浏览器工具

| 工具 | 功能 |
| --- | --- |
| browser_goto | 导航共享页面并返回 {url, finalUrl, status, title, text, links}——最多 6000 字符的提取标题/段落/列表文本和 25 个链接。 |
| browser_evaluate | 在页面上下文中运行 JavaScript 表达式（可使用 document、window、DOM）并返回可 JSON 序列化的结果。 |
| browser_screenshot | 将当前页面捕获为 PNG/JPEG data URL（{dataUrl, mime, bytes}）；fullPage 用于整页高度。 |
| browser_click | 点击第一个匹配 CSS 选择器的元素；返回被点击的标签/文本，或带消息的 ok: false。 |
| browser_type | 使用真实按键事件向 input/textarea/select 输入文本（React 安全）；返回字段值。 |
| browser_read | 选择器的内部文本（默认：整个 body），最多 6000 字符，并附匹配数。 |
| browser_wait | 等待选择器出现（异步内容完成），然后返回其文本。 |
| browser_back / browser_forward / browser_reload | 活动标签页的历史导航。 |
| browser_a11y | 紧凑的无障碍树（角色/名称/值，最多 400 个节点）——屏幕阅读器所消费的内容。 |
| browser_tabs | 列出标签页（index、url、title、active）；其他工具作用于活动标签页。 |
| browser_tab_open / browser_tab_switch / browser_tab_close | 管理标签页；弹出窗口和 target=_blank 链接会作为新标签页打开。 |

页面是共享且持久的：用 browser_goto 访问某个站点，用 browser_evaluate
与其 DOM 交互，用 browser_screenshot 查看它——全都是同一个标签页。

URL 处理

browser_goto 和窗格的地址栏接受以下输入（与终端浏览器的
参考语义一致）：

- 完整 URL（https://…、data:、mailto:、about:、view-source: 等）
- 类似主机名的输入（example.com/docs、localhost:5173——对
localhost/127.0.0.1 使用 http://，否则使用 https://）
- 已存在的绝对路径或经 ~ 展开的本地路径（以 file:// 打开）
- 其他任何内容 → 一次 Google 搜索

浏览器窗格

展开时，窗格以全高停靠在右边缘（就像一个镜像的
侧边栏）；折叠时，它会收缩为一条细长的垂直栏，并带有一个切换按钮。
其左边缘是一个拖拽手柄——拖动可调整大小（从紧凑的约 10% 到
窗口的约 80%），宽度在重新加载后仍会保留，整个 GUI 会围绕
它重新布局。标题栏在地址栏旁边带有后退 / 前进 / 重新加载按钮，
标签条末尾有一个浏览器模式切换。

浏览器模式

标签条中的 Plugin / My Chrome 切换可切换智能体所驱动的浏览器——
随时实时切换：

- Plugin——此插件启动的实例（默认无头模式，使用
配置的视口/配置文件）。
- My Chrome——你自己启动并启用了调试功能的 Chrome，
通过 CDP 连接。Chrome 只会在非默认配置文件上打开调试端口，
因此请使用专用配置文件目录启动它（例如桌面
快捷方式：chrome.exe --remote-debugging-port=9222 --user-data-dir=C:\Users\you\.dsh\chrome-debug-profile），
设置 connectUrl，然后切换到 My Chrome。在该 Chrome 中登录一次——
登录状态会保留在那里——它会与你的普通 Chrome 并行运行。由于
插件从不触碰其身份标识（没有自动化标志，不更改 UA/视口），
诸如 Cloudflare Turnstile 之类的机器人防护墙会看到一个真实的
会话。切回只会断开连接；你的 Chrome 及其标签页绝不会被插件
关闭。（配置文件无法在不同目录之间复制：
Chrome 的 App-Bound Encryption 会丢弃移动到不同配置文件
路径的 cookie——专用配置文件才是应该登录的那个。）

该窗格是一个真正的双向远程：

- 帧输出——窗格订阅 GET /browser-pane/stream（SSE）。
宿主端驱动 Chrome 的 Page.startScreencast（仅在视觉
变化时发送 JPEG 帧——不轮询截图）并推送每一帧及其页面
URL。屏幕录制会跟随其订阅者：第一个客户端启动它，
最后一个会停止它，后加入的订阅者会立即收到当前状态和最后一帧的重放。
- 输入 — 指针和键盘事件会提交到 /browser-pane/input，并通过 CDP Input 域（Input.dispatchMouseEvent / Input.dispatchKeyEvent）到达页面。保真度与终端浏览器参考实现一致：双击/三击计数、修饰键位掩码（鼠标和按键上的 Shift/Ctrl/Cmd/Alt）、带行模式档位缩放的分数滚轮累积、失焦时释放按住的键，以及当窗格拥有页面时的焦点模拟。
- 地址栏 — POST /browser-pane/goto 导航共享页面。

| 路由 | 用途 |
| --- | --- |
| GET /browser-pane/stream | SSE 帧 + 状态流（frame / state 事件）。 |
| POST /browser-pane/input | 合成输入：{type: mouse-move \| mouse-down \| mouse-up \| wheel \| key-down \| key-up, …}。 |
| POST /browser-pane/goto | 导航：{url}。 |
| POST /browser-pane/mode | 切换浏览器模式：{mode: 'own' \| 'connect'}。 |

工作原理

一个包，两半，都从单个组合行挂载：

宿主半部分（Node 进程） — 运行浏览器、工具、技能和窗格服务器：

- 一个 BrowserRuntime 拥有一个延迟启动的 Chrome 和一个标签页会话：任意数量的标签页，一个处于活动状态。在崩溃或断开连接时，缓存句柄会被清除，下一次调用会重新启动。
- 所有工具都注册到宿主的 tools 注册表上；打包的技能注册到 skills 上，每个技能以其捆绑的 skills// 目录作为资源基础。
- 窗格服务器在共享 Web 服务器（ctx.webServer）上注册上述三个路由，且仅在存在该服务器时注册。请求体在路由边界由 schemastery schema 解析。
- 标签页：弹出窗口和 target=_blank 链接会作为新标签页打开（终端浏览器的标签页即弹出窗口模型），窗格的标签条会镜像该会话，因此窗格、工具和任何有头窗口永远不会对哪个页面处于活动状态产生分歧。空白目标永远不会被关闭（正在创建中的页面也是空白的）；外部目标一旦带有真实 URL 就会被接管。
- 后台节流被禁用，因此当 Chrome 被遮挡时帧仍会持续流动。

客户端半部分（浏览器 bundle） — 窗格 UI：

- package.json 声明了 dsh.client（platform: "web"），构建后的 bundle 通过 exports["./client"] 导出。DSH 客户端模块宿主会扫描已启用条目中的 dsh.client 包，在 /plugins/@try-works/dsh-browser-agent/client.js 提供该 bundle，客户端内核将其作为 cordis 插件采用——无需额外的组合行。
- 窗格注册到 GUI 布局声明的全帧 shell.overlay 槽位中，停靠在右边缘。该 bundle 使用 React.createElement 编写（无 JSX）；react 本身是 shell 预置的平台模块，因此该 bundle 不携带框架字节。

生命周期 — 注册被包裹在一个 ctx.effect 生成器中（该
dsh-recursive-mode 模式）：卸载插件会注销工具和
技能，拆除窗格路由和屏幕录制，释放按住的按键，并
关闭 Chrome。

捆绑技能

该捆绑包在 ctx.skills 上注册了八个打包技能（dsh-plugin
打包技能标准：每个 skills//SKILL.md 都随包发布，
并以目录 resourceBase 注册，因此相对引用会相对于捆绑包的副本进行解析）：

| 技能 | 教给智能体的内容 |
| --- | --- |
| browser-search | 跨两个层级查找和阅读网络来源——先使用网络工具（最便宜），然后是 web_search，最后是浏览器工具——包括路由分诊和完整操作手册（references/search-engine-access-guide.md——网络引擎壁垒（DDG 突发限流、Brave 429、Mojeek 可靠性）、SearXNG 回退、Reddit 403 浏览器层级路径、Wayback Machine、站内搜索和 API 路由）。 |
| browser-navigation | 在共享页面中移动：URL 形式（URL、主机名、localhost 端口、文件路径、搜索文本）、阅读 browser_goto 摘要、重定向/状态/超时，以及单一共享页面模型。 |
| browser-interaction | 通过 browser_evaluate 进行 DOM 自动化：读取状态、点击、输入、填写表单、滚动、等待异步内容、JSON 安全结果，以及将多次读取批量合并为一次 evaluate。 |
| browser-visual-check | 使用 browser_screenshot（视口/整页，PNG/JPEG）验证渲染效果，并为观看实时窗格的人类保持共享页面整洁可读。 |
| browser-multitab | 同时处理多个页面：标签页工具、其他工具作用于哪个标签页、弹窗即标签页，以及标签页使用规范。 |
| work-login | 受监督登录流程（在模型看不到凭据的情况下登录）：work_login_begin/cancel/status、窗格中的登录横幅、Seal/Abort，以及会话保险库。 |
| work-appointment | 事务性预约工作流（DMV、医生、保险）：找到表单、填写表单，让高风险点击门控处理具有后果的提交。 |
| work-forms | 表单填写机制和 Work Mode 规则：绝不输入密码，绝不编造个人数据，提交前先询问。 |

Work Mode

达到 ChatGPT Work 同等水平的凭据隔离网络自动化。启用后
（workMode.enabled: true），四层机制将凭据和具有后果的
操作置于模型无法触及之处：

1. 高风险点击门控（tools/pre-execute）——对表单提交、
发送/删除/取消动词或美元金额按钮的点击会在
派发前被拦截，并经由审批栈路由。没有审批渠道 = 该
点击被拒绝（故障关闭）。
2. 机密防火墙（tools/post-execute）——document.cookie、JWT、
持有者令牌、password=/token= 赋值，以及
browser_evaluate/browser_read/browser_fetch 结果中的 Set-Cookie 行，
会在模型看到之前被脱敏为
[redacted]。
3. 受监督登录——work_login_begin（或窗格中的 Sign in 按钮）
在用户直接将凭据输入实时窗格时，暂停所有 browser_* 工具（合成 CDP 输入——值永远不会进入模型上下文）。Seal 捕获会话 cookie；Abort 丢弃。
4. 会话保险库——已密封的会话以 AES-256-GCM 加密形式持久化存储在
~/.dsh/vault（vault.key 权限 0600 + sessions.vault）。work_vault_status
仅列出源 + cookie 名称；恢复/撤销是窗格路由。

配置

- id: dsh-browser-agent
config:
workMode:
enabled: true            # default false
approveSubmit: true      # ask before form-submit clicks
approveSend: true        # ask before send-like clicks
approveAmountsUsd: true  # ask before dollar-amount clicks
allowlist: []            # hostnames that never ask
vaultDir: ''               # empty = ~/.dsh/vault

模型的工具

- work_login_begin / work_login_cancel / work_login_status——驱动并
检查受监督的登录流程（从不涉及凭据）。
- work_vault_status——列出已密封的会话（仅源 + cookie 名称）。

开发

pnpm install     # links the type-only harness devDependencies
pnpm build       # tsc declarations + tsdown: lib/index.js (host) and lib/client.js (client)
pnpm typecheck   # tsc --noEmit
pnpm test        # offline tests: net, gates, firewall, login-mode, vault

各层级均采用 TDD 开发：test/net.test.ts 针对 test/fixtures/ 中已提交的
fixtures 离线运行，test/gates.test.ts / test/firewall.test.ts /
test/login-mode.test.ts / test/vault.test.ts 测试 Work Mode 的纯
核心，而 test/net.live.test.ts 在选择性启用时测试真实引擎
（在 PowerShell 中运行 $env:DSH_BROWSER_LIVE = '1'; node --import tsx --test test/net.live.test.ts）。
实时测试套件容忍已记录的障碍——来自数据中心 IP 的 DDG Lite
限流和 Reddit 403 被视为环境状态而非失败；解析器由离线 fixtures 证明。

prepublishOnly 运行 pnpm build，因此 npm publish 始终发布全新的
产物。

发布

pwsh scripts/publish.ps1 -CheckOnly   # verify the npm token without publishing
pwsh scripts/publish.ps1              # build + publish the current version

该脚本从令牌文件中读取一个临时的 npm 自动化令牌（对
@try-works 具有发布权限），在命令执行期间将其写入本地 .npmrc，
并在 finally 中删除它——令牌永远不会存储在此仓库中。成功发布后，将
配置文件从 link: 安装迁移出去：

dsh plugin --profile web add @try-works/dsh-browser-agent

许可证

ISC——参见 LICENSE。此包派生自
zenbu-labs/terminal-browser
（ISC）；参见 NOTICE。