# dsh-browser 需求文档

本文定义 v0.2 浏览器自动化能力的产品范围和验收要求。协议字段、配置默认值和安装命令分别由源码、[通信设计](03-通信方式设计.md)和根目录 [README](../README.md) 拥有。

## 1. 产品目标

dsh-browser 让 DeepSeek Harness agent 操作用户已经打开并明确授权的 Chromium 标签页，不启动独立无头浏览器。工具结果通过 Harness 的普通工具流水线进入模型上下文、会话日志、审批和回放。

- G1：支持网页调研、表单操作、产品回归测试和本地 Web 应用联调。
- G2：页面读取和操作使用稳定元素引用，模型不需要猜测 CSS selector。
- G3：生产模式采用 Chrome Native Messaging 约束扩展身份，开发模式提供经过认证的回环 WebSocket 直连。
- G4：扩展默认访问浏览器 profile 中全部 HTTP/HTTPS 页面，修改操作进入 Harness 审批流水线。
- G5：协议具备版本协商、能力协商、消息校验、取消、超时和有界结果。

## 2. 交付组件

| 组件 | 交付形式 | 责任 |
|---|---|---|
| Harness 插件 | 可安装 `dsh-browser` bundle | 提供 `ctx.browser`、模型工具、权限策略、连接 Provider 和 DSH Web 设置卡片。 |
| 浏览器扩展 | Chrome/Edge MV3 扩展 | 采集 HTTP/HTTPS 页面上下文、显示控制提示并执行浏览器动作。 |
| Native host | 本地可执行程序与 NativeMessagingHosts 清单 | 校验扩展 ID，承载原生消息，连接 Harness 并转发统一协议。 |

开发模式允许扩展直接连接 Harness 回环 WebSocket。该模式不替代生产 Native host，也不取消认证、协议校验或 HTTP/HTTPS 目标限制。

## 3. 使用场景

- 场景 A：agent 读取一个或多个 HTTP/HTTPS 页面，提取和比较信息。
- 场景 B：agent 根据结构化页面快照定位输入框、按钮和链接，完成表单流程。
- 场景 C：agent 操作本地测试环境，执行导航、点击、输入、等待和断言。
- 场景 D：agent 在用户确认后执行提交表单、删除数据或页面表达式等高风险操作。
- 场景 E：浏览器、扩展 service worker、Native host 或 Harness 重启后恢复连接，不重放旧修改操作。

## 4. 功能需求

### 4.1 页面观察

| 编号 | 需求 |
|---|---|
| FR-1 | 列出当前扩展可见且可操控的标签页，返回 tab id、window id、URL、标题和激活状态。 |
| FR-2 | 后续命令按精确 tab id 在后台访问标签页，不改变用户当前激活的标签页或浏览器窗口焦点。 |
| FR-3 | 返回页面 URL、标题、可见文本和可交互元素；每个元素包含在当前 `documentId` 内稳定的 `ref`、role、name、状态和值摘要。 |
| FR-4 | 快照准确报告文本和元素获取上限造成的截断，不把部分结果标记为完整。 |
| FR-5 | 支持等待页面加载、URL、文本或元素状态，超时返回结构化错误。 |

### 4.2 页面操作

| 编号 | 需求 |
|---|---|
| FR-6 | 导航到 HTTP/HTTPS URL，并在加载或超时后返回新页面快照。 |
| FR-7 | 按快照 `ref` 点击元素；CSS selector 只作为显式高级参数保留。 |
| FR-8 | 按快照 `ref` 输入文本，兼容 input、textarea、select 和 contenteditable，并触发页面框架可观察的事件。 |
| FR-9 | 支持滚动、按键、后退、前进、刷新和在后台创建新标签页。 |
| FR-10 | 页面动作返回操作结果和当前 `documentId`，调用方自行决定是否获取后续快照。 |
| FR-11 | 页面表达式执行默认启用，仍受 HTTP/HTTPS 目标限制和 Harness 审批控制，并限制结果大小；profile 可以显式移除该工具。 |

### 4.3 连接与协议

| 编号 | 需求 |
|---|---|
| FR-12 | 客户端先完成 `hello` 握手，提交协议版本、客户端版本、客户端身份、认证信息和能力列表。 |
| FR-13 | 版本、身份或认证不匹配时连接失败，不进入命令状态。 |
| FR-14 | 每条请求、回复和取消消息通过 id 关联，一个请求只能结算一次。 |
| FR-15 | 调用方取消或超时时，bridge 立即结算本地请求并向浏览器端发送取消消息。 |
| FR-16 | 连接替换、断线和插件卸载结算全部在途请求，并等待监听器、套接字和服务器停止。 |
| FR-17 | 扩展 service worker 启动时自动连接 Native host，并通过 Chrome alarms 在浏览器、service worker、host 或 Harness 重启后恢复；生产 Popup 不要求用户配置传输、端口、token 或手工连接。 |

### 4.4 授权与审批

| 编号 | 需求 |
|---|---|
| FR-18 | 扩展默认允许浏览器 profile 中全部 HTTP/HTTPS 页面；Popup 只显示自动连接状态和安装 Native host 所需的扩展 ID。 |
| FR-19 | 标签页列表返回全部 HTTP/HTTPS 页面，但不返回浏览器内部页面、扩展页面、浏览器商店、文件 URL 或空 URL。 |
| FR-20 | 激活、新建、导航、历史操作、刷新、点击、输入、滚动、按键和表达式执行默认返回 Harness `ask`；列表、快照和等待默认允许。 |
| FR-21 | Harness 权限预设可以取消交互审批，但不能绕过 HTTP/HTTPS 目标限制。 |
| FR-22 | Agent 首次操作可操控页面后显示置顶控制提示、虚拟鼠标和 favicon 标记；连续浏览器工具之间保留这些指示，并在对应 Agent 进入 idle、被销毁或连接断开时移除。没有 Agent owner 的直接调用至少显示一秒。指示不得进入页面快照、元素引用或文本等待。 |

## 5. 非功能需求

| 编号 | 类别 | 需求 |
|---|---|---|
| NFR-1 | 安全 | 回环 WebSocket 需要高熵 token 并拒绝普通网页 Origin；Native host 清单只允许安装时指定的扩展 ID。 |
| NFR-2 | 隐私 | 安装文档说明全部 HTTP/HTTPS 标签页的标题、URL、正文、表单值和操作结果可能进入模型上下文及 Harness 会话日志。 |
| NFR-3 | 可靠 | 断线、超时、取消和卸载达到静止状态，不遗留端口、定时器或未结算 Promise。 |
| NFR-4 | 性能 | 文本、元素数量、消息大小、表达式结果和等待时间具有配置或协议上限。 |
| NFR-5 | 兼容 | 支持 Node 22.19+、Chromium MV3，以及 `>=0.1.0-rc.5 <0.2.0` 的 Harness 插件 API。 |
| NFR-6 | 可观测 | 连接状态、客户端身份、版本错误、权限拒绝和命令超时具有稳定错误码与可诊断日志。 |
| NFR-7 | 可测试 | 协议和工具逻辑可无浏览器测试；Direct 与 Native 两条真实 Chromium 链路具有端到端测试。 |

## 6. 约束与非目标

- 扩展不能监听 TCP；Direct 模式由扩展外拨 WebSocket，Native 模式由扩展发起 `connectNative`。
- MV3 service worker 可能休眠，恢复不能只依赖普通长定时器。
- 快照与 DOM 动作的页面注入运行在扩展隔离世界，不依赖页面 JavaScript 闭包；页面表达式在临时 CDP 隔离 execution context 中执行。
- v0.2 只读取顶层文档，不承诺跨 origin iframe、closed shadow root 或 CDP 可访问性树。
- v0.2 不提供截图、上传、下载、弹窗、网络诊断或跨机器浏览器控制。
- Firefox 和 Safari 不在支持范围内。

## 7. 验收标准

| 编号 | 验收标准 |
|---|---|
| AC-1 | `dsh plugin --profile web add github:justwe-bot/dsh-browser` 后，profile 的 `dsh.profile.bundles` 包含 `dsh-browser`，`--dump-config` 显示 provider、policy、tool 和 Web settings 行，并能实际加载这些行。 |
| AC-2 | 无认证、错误 token、普通网页 Origin、未知能力和错误协议版本均不能执行命令或替换当前有效连接。 |
| AC-3 | 不同 HTTP origin 的标签页无需站点授权即可出现在列表中并被读取；浏览器内部页不出现在列表中，按 tab id 调用时返回稳定拒绝错误。 |
| AC-4 | 快照返回交互元素 `ref`；使用 `documentId + ref` 可以完成点击和输入，不需要预先知道 CSS selector。 |
| AC-5 | 修改操作在 `workspace-write` 权限预设下发起审批，用户拒绝时真实页面无副作用。 |
| AC-6 | 截断标志、取消、超时、连接替换和卸载均由自动化测试覆盖。 |
| AC-7 | 真实 Chromium 测试完成 Direct 与 Native 连接、授权、快照、导航、点击、输入、等待和断线恢复。 |
| AC-8 | 组装后的 Harness keyless snapshot 固定工具 schema、模型可见结果和 UI render intent。 |
| AC-9 | 真实 Chromium 测试验证控制提示固定在页面顶部，并发请求共享提示，Agent 工具结束后仍保留虚拟鼠标，Agent 进入 idle 后自动移除，且提示文字不进入页面正文或浏览器工具返回值。 |