DSH Browser
面向 DeepSeek Harness、优先无头运行的隔离式浏览器自动化。
托管 Chromium 会话 • 语义引用 • 限定范围观察 • 有界证据
包名：@zseven-w/dsh-browser · 版本：0.1.0-rc.1 · 预发布阶段
English · 简体中文
每个 Agent 独占一个临时 Chrome / Edge / Chromium 用户目录，并通过短期语义引用、确定性高风险拦截和有界证据进行操作。用 `npm install @zseven-w/dsh-browser` 安装；当前是预发布版本，契约（v9）在 rc 之间仍可能变化。
[快速开始](#快速开始) · [工具](#工具) · [安全边界](#安全与证据边界) · [本地开发](#本地开发) · [文档入口](#文档入口)
Browser 驱动真实执行填写 → 点击 → 重新观察。画面是增加展示样式的本地测试页面，不是插件自带面板；全部使用合成数据。
## 产品边界
`dsh-browser` 不接管个人浏览器，也不会把 CSS Selector 暴露给模型。所有工具调用都由 `exec.agent.id` 隔离：Agent 只能观察和操作自己拥有的浏览器 Context。
```text
Agent A ── 临时 Chromium Context A ── opaque refs A
Agent B ── 临时 Chromium Context B ── opaque refs B
└──── 有界 Console / Network 证据
```
插件同时提供 `zsevenBrowserDriver` 服务，作为后续 `dsh-qa` 的稳定编排接口。
## 快速开始
需要 Node.js `>=24.11.0`、pnpm，以及已安装的 Google Chrome、Microsoft Edge 或 Chromium。默认使用 Headless，不使用个人浏览器 Profile。
单独安装 DSH，然后在本仓库根目录构建：
```sh
npm install -g @deepseek-ai/dsh@latest
pnpm install
pnpm run build
```
将已构建的工作区链接到 DSH Web Profile：把占位路径替换为本仓库的绝对路径，然后重启 DSH。
```sh
dsh plugin --profile web add link:/path/to/dsh-browser
dsh web
```
用于生产或 QA 目标前，先配置 Operator 管理的[导航白名单](#operator-导航白名单)。依次调用 `browser_session_start`、`browser_observe`，使用新鲜 ref 执行动作，然后重新观察验证结果；结束时调用 `browser_session_stop`。`confirmed` 收据只证明输入已派发，不代表业务结果成功。
## 工具
| 工具 | 作用 |
| --- | --- |
| `browser_session_start` | 发现已安装的 Chrome / Edge / Chromium，启动独立 Context。 |
| `browser_observe` | 返回有界语义视图（整页，或通过 `within` 限定到某个元素的子树），以及绑定 epoch / fingerprint / expiry 的 opaque ref。 |
| `browser_act` | 实时重新解析并校验目标后执行 `click`、`fill`、`press`、`navigate`、`scroll`、`select` 或 `hover`。 |
| `browser_evidence` | 返回有界、脱敏的 Console 和 Network 元数据。 |
| `browser_session_stop` | 关闭 Context，删除对应的精确临时用户目录。 |
每次 `browser_act` 都返回收据：
- `confirmed`：浏览器完成了经校验的输入派发，但不代表业务结果一定成功。
- `unknown`：动作可能已派发，但取消、导航或运行时异常使最终状态无法确认。
- `rejected`：策略、过期引用、语义变化或 Hit Test 在派发前拒绝动作。
- `failed`：浏览器没能派发动作。
`scroll` 可滚动到视口外控件（按 ref，将目标居中）或翻页（`direction` + 可选 `amount`）；`select` 先按可访问标签、再按精确 value 选择原生 `