浏览器自动化插件KasenRi/dsh-browser

@kasenri/dsh-browser

本仓库是 @kasenri/dsh-browser 0.1.0 的可安装发布镜像。
规范源：https://github.com/KasenRi/dsh-orbit-browser-plugins/tree/main/packages/browser
请勿在此处开发功能；请从规范源 monorepo 发布变更。
DeepSeek Harness（DSH）的社区插件。
与 DeepSeek 无关联，亦未获其认可。

将受控的 浏览器自动化 能力以 Cordis 插件形式暴露给 DSH：

- 在 ctx.browserAutomation 上提供 BrowserAutomationService
- 一个面向模型的 agent_browser 工具，用于驱动
agent-browser CLI

Harness 原生基础设施（agents、tools、sessions）
│
▼
@kasenri/dsh-browser
│  BrowserAutomationService + agent_browser 工具
▼
agent-browser CLI  →  Chromium / Chrome（或显式 CDP 端点）

要求

| 组件 | 测试版本 |
|---|---|
| @deepseek-ai/dsh | 0.1.5-rc.2 |
| @deepseek-ai/cordis | 4.0.2 |
| agent-browser | 0.33.2（必须位于 PATH 中） |
| Node.js | >= 22.19.0 |
| 浏览器 | Chromium / Google Chrome（或 Electron/CDP 调试端点） |

DSH 处于开发者预览阶段且迭代迅速；本包仅针对上述版本进行测试，
并不保证兼容未来所有 DSH 版本。

安装

本包已发布至 npm Registry；当更倾向于使用 Git 源时，专用的 Git 分发
镜像仍然可用：

dsh plugin --profile web add @kasenri/dsh-browser
Git 源替代方案，跟踪镜像仓库 HEAD：
dsh plugin --profile web add github:KasenRi/dsh-browser

本包声明了 dsh.bundle 补丁，因此 dsh plugin add 会自动将其注册为
profile 层。安装后请重启 profile（或启动新会话）。

规范源维护于
源 monorepo。
源 monorepo 的带版本 Release tarball 仍可用于手动或离线回退，
但 Market 使用此专用 Git 仓库，以便更新时可将锁定的 commit 与 HEAD 进行比较。

如果 agent-browser 不在 PATH 中，可通过 command 配置键、
executablePath 配置键或 DSH_BROWSER_EXECUTABLE_PATH 环境变量
将插件指向某个可执行文件。

工具输入模式

agent_browser 仅接受以下之一：

| 模式 | 用途 |
|---|---|
| args | 原始 agent-browser argv（例如 ["open", "https://…"]、["snapshot", "-i"]）。 |
| semanticAction | 稳定目标：action + locator/role/name/selector。 |
| job | 简短确定性的多步骤批处理（steps、failFast）。 |
| qa | 页面 QA 预设（url 或 attached、预期文本/选择器、诊断信息）。 |
| electron | 显式 CDP 附加：{ action: "connect", port | url } 或 { action: "probe" }。 |
| sourceLookup | 来自 DOM/React 证据 + 有界工作区扫描的候选源位置。 |
| networkSourceLookup | 失败请求证据 + 候选源/工作区提示。 |

标准工作流：open → snapshot -i → 使用当前的 @refs →
click/fill/select → 页面变化后再次 snapshot -i。

其他选项：stdin（仅用于 batch、eval --stdin、
auth save --password-stdin）、outputPath（以原子 0600 写入
结构化结果）、timeoutMs、sessionMode（auto | fresh）。

它保护什么

- 过期引用 — 引用是页面作用域的；针对不在同一目标最新快照中的
引用的变更，会在任何浏览器调用之前被阻止。
- 标签页漂移 — 意外的活动目标变化（包括 about:blank）
会使引用失效，并通过 tab list + tab  触发恰好一次确定性恢复；
存在歧义时以 tab-drift 失败，而不是进行猜测。
- 产物 — 截图、下载、PDF、HAR/trace/record 文件在报告成功之前
会在磁盘上被验证（存在性、大小、类型）。
- 机密与受保护状态 — .agent-browser 状态、密码存储和
cookie 数据库被阻止；凭据形态的值会从所有
工具输出中脱敏。
- 域限制 — 当配置了 allowedDomains 时，已知 URL 会被
预检，托管上下文会以上游 --allowed-domains 启动，
并验证最终 URL。在启用限制时，CDP 附加（electron/connect）会被拒绝，
因为它无法在现有浏览器上下文上强制执行。
- 人工验证 — CAPTCHA、OTP、passkey、WebAuthn 和 2FA 绝不会
被绕过；该工具会报告它看到的内容并停止。

大型输出会被压缩为有界预览加溢出文件，而不是
被推入模型上下文。

配置

| 键 | 默认值 | 含义 |
|---|---|---|
| command | agent-browser | 要调用的可执行文件。 |
| namespace | — | 可选的 agent-browser 命名空间。 |
| executablePath | DSH_BROWSER_EXECUTABLE_PATH | 用于托管上下文的 Chromium/Chrome 可执行文件。 |
| timeoutMs | 35000 | 每次调用子进程的默认超时。 |
| maxOutputChars | 8000 | 溢出前的内联输出预算。 |
| maxOutputLines | 120 | 溢出前的内联行数预算。 |
| spillDir | ~/.dsh/browser-artifacts | 压缩输出的写入位置。 |
| allowedDomains | [] | 用于严格限制的域允许列表。 |
| registerTool | true | 注册 agent_browser 工具。 |

许可证

MIT