# dsh-browser 实施与验收

本文拥有 v0.2 的发布范围、自动化证据入口和 AC-1 至 AC-9 映射。产品要求见[需求文档](01-需求文档.md)，安装步骤见根目录 [README](../README.md)。

## 1. 发布范围

v0.2 包含以下可交付行为：

- 可通过 `dsh plugin` 安装的 `dsh-browser` bundle，挂载 browser Provider、审批策略、模型工具和 Web 设置卡片。
- 经过认证的 Direct WebSocket 开发模式。
- Chrome Native Messaging 生产模式、Native host 可执行文件构建和用户级安装器。
- 全部 HTTP/HTTPS 标签页默认可用、非网页 URL 拒绝和注入前页面 origin 复核。
- 结构化页面快照、稳定元素 `ref`、截断报告和 stale-ref 拒绝。
- 导航、历史、刷新、新标签页、点击、输入、滚动、按键和条件等待。
- 默认注册、可由 profile 移除的页面表达式执行。
- Agent 控制页面期间的置顶控制提示、页面内虚拟鼠标、标签页临时鼠标图标、Agent owner 生命周期、并发请求和快照隔离。
- Harness 工具 schema、模型可见渲染、UI render intent 和审批流水线。

截图、上传、下载、弹窗、网络诊断、跨 origin iframe、closed shadow root 和通用 CDP 不属于 v0.2 验收范围。`debugger` 只用于 `Runtime.evaluate`。

## 2. 自动化证据

| 层级 | 权威入口 | 证明的行为 |
|---|---|---|
| 协议与 Provider | `tests/bridge.test.mjs` | 握手、认证、Origin、版本、能力、取消、超时、回复校验、连接替换、卸载和端口释放。 |
| Native host | `tests/native-host.test.mjs` | 4 字节 framing、扩展 origin 拒绝、token/transport 注入和双向转发。 |
| 安装器 | `tests/installer.test.mjs` | 私有配置、可执行文件副本、正确 `allowed_origins`、权限为 `0600` 的启动环境文件、通用 `.env` 不变和卸载。 |
| 工具组装 | `tests/tool-browser.test.mjs`、`tests/policy.test.mjs` | 工具 schema、渲染、UI intent、evaluate 开关、Agent owner 保留与 idle 释放、workspace-write 审批和 danger-full-access 委托。 |
| Profile 集成 | `scripts/profile-smoke.mjs` | 发行 tarball 的 `dsh plugin add`、扩展准备 bin、bundle manifest、dump-config、实际插件加载和释放端口。 |
| Keyless transcript | `examples/keyless-browser.mjs`、`tests/keyless-snapshot.test.mjs` | 组装应用的工具 schema、模型结果和 UI intent 快照。 |
| Direct Chromium | `tests/chromium-direct.e2e.mjs` | 内部开发传输配置、跨 HTTP origin 默认访问、浏览器内部页拒绝、后台创建与操作时保持活动标签页不变、历史导航、真实 DOM 快照与操作、并发控制提示、Agent idle 前的虚拟鼠标保留、标签页临时图标及快照隔离、CDP 表达式、截断、stale ref 和审批拒绝无副作用。 |
| Native Chromium | `tests/chromium-native.e2e.mjs` | 真实扩展 ID、Native host 安装、无需 Popup 操作的自动连接、默认页面读取和 bridge 重启恢复。 |

## 3. 验收标准映射

| 编号 | 自动化证明 |
|---|---|
| AC-1 | `pnpm smoke:profile` 在隔离 `DSH_HOME` 安装发行 tarball，通过安装包 bin 准备扩展，检查 `dsh.profile.bundles` 和四个配置行，并实际启动到凭据解析阶段。 |
| AC-2 | `tests/bridge.test.mjs` 拒绝错误 token、普通网页 Origin、错误版本和未知能力，并证明失败握手不替换有效连接。 |
| AC-3 | Direct Chromium E2E 无需站点授权即可读取第二个 HTTP origin，同时从列表隐藏 `about:blank` 并以 `UNSUPPORTED_URL` 拒绝其快照。 |
| AC-4 | Direct Chromium E2E 从快照取得 `documentId + ref`，完成 input、textarea、select、contenteditable 和点击操作。 |
| AC-5 | Direct Chromium E2E 通过真实 ToolRuntime、ApprovalService 和 browser-policy 拒绝 `browser_type`，随后直接读取真实 input 值证明页面未变化。 |
| AC-6 | bridge 测试覆盖取消、超时、连接替换和卸载；Direct Chromium E2E 覆盖文本与元素截断。 |
| AC-7 | `pnpm test:chromium` 顺序执行 Direct 与 Native 两条真实 Chromium 流程；Direct 流程覆盖标签页、历史、DOM 操作和默认启用的表达式，Native 流程在 bridge 重启后恢复。 |
| AC-8 | `pnpm test:snapshot` 比较 keyless runnable example 与 `tests/snapshots/keyless-browser.expected.json`。 |
| AC-9 | Direct Chromium E2E 启动两个并发页面等待并检查共享指示，再通过真实工具调用证明虚拟鼠标在工具结束后保持显示、对应 Agent 进入 idle 后移除；测试同时验证原 favicon 恢复、导航后重新注入，并证明页面正文与返回快照不包含扩展指示元素。 |

## 4. 验证命令

从本仓库运行：

```sh
pnpm typecheck
pnpm test
pnpm test:snapshot
pnpm smoke
pnpm smoke:profile
pnpm test:chromium
git diff --check
```

`pnpm test` 会先构建全部工作区包并运行无浏览器单测。`pnpm test:chromium` 会构建 Native host 单文件可执行程序并启动真实 Chromium。

`pnpm smoke:profile` 默认把父目录视为 DeepSeek Harness 根目录；其他布局通过 `DSH_HARNESS_ROOT` 指定。该检查要求 Harness host 构建产物存在，因为它验证实际发布入口，而不是只解析 YAML。

## 5. 完成判据

v0.2 完成需要本节全部命令通过，并且根 README 的生产安装流程能在隔离 Harness profile 中得到与自动化证据一致的三个组件链路。启动 Harness 前必须导入专用环境文件，不得依赖 `$DSH_HOME/.env` 注入 `DSH_BROWSER_*`。任何 AC 缺少当前自动化证明时，版本不满足发布判据。