[English](./README.md) | **简体中文**
# dsh-b2us-chrome-tool
面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的安全、本地 Chrome 自动化插件。
`dsh-b2us-chrome-tool` 通过 Chrome Manifest V3 扩展和经过身份验证的 loopback 桥接，连接用户正在使用的 Chrome 会话。它把受限的标签页、语义 DOM、页面交互、截图、可验证定位器和网络观测能力注册为 DSH tools，同时将原始页面数据隔离在独立 Browser Worker 中。
> [!IMPORTANT]
> 本项目面向本地开发和受信任环境。它不会读取 Chrome 密码库，不会选择密码管理器候选项，也不会把密码输入框的值返回给 Agent。
> [!NOTE]
> `dsh-b2us-chrome-tool` 是项目与仓库名称。为保持兼容，当前可安装 npm 包、Cordis row、运行时路由和既有数据路径仍使用技术标识 `dsh-auto-chrome-tool`，因此安装及配置示例会继续使用该标识。
## Harness 0.1.2-rc.1 兼容性
`0.4.2` 将全部 DSH 精确 peer 版本提升到 `0.1.2-rc.1`，不支持混用不同 Harness/插件预发布版本。Harness 在该版本中将可变的 Session 事件数组改为私有成员，因此插件现只通过公开、不可变的 `snapshotEvents()` 与 `eventAt()` 访问历史。
本次兼容调整不会改变 tools、Cordis row、HTTP 路由、扩展协议或持久化数据目录，也不需要迁移数据。请同时升级 Harness 与本插件，再重启 Profile。
## 核心能力
| 领域 | 插件能力 |
| --- | --- |
| 复用现有 Chrome 会话 | 控制用户已授权的现有浏览器标签页，无需另建自动化 Profile。 |
| 语义页面访问 | 返回有界的可访问名称、角色、状态和短期 opaque 元素引用，不向模型倾倒整页源码。 |
| 源侧检索 | `page.find` 先在页面运行时对相关元素排序，再把有限结果返回给模型。 |
| 可验证定位器 | `page.locator` 在实时 DOM 中生成 CSS/XPath 候选，并证明每个候选只能唯一命中目标元素。 |
| 页面交互 | 支持点击、按精确名称点击、非敏感文本输入、选择、滚动、等待和结构化提取。 |
| 截图与网络数据 | 将截图以及受限的 Fetch/XHR 元数据或正文保存为 opaque artifact，并执行脱敏、配额和过期控制。 |
| 上下文隔离 | fresh Browser Worker 接收页面数据和 Worker 专属工具；父 Agent 只接收有界的类型化结果。 |
| 可恢复交付 | 分别报告浏览器执行和文件交付状态；artifact 复制失败时可单独重试，而不重复登录、提交等浏览器动作。 |
| 安装引导 | 检测 Chrome，经 DSH 审批后准备随包扩展，并提供中英文 Harness 设置页查看状态、下载扩展及完成配对。 |
| 纵深防护 | bridge 仅监听 loopback，校验扩展 Origin，执行双向 nonce/HMAC 认证，并限制大小、并发、超时和资源生命周期。 |
## 工作原理
```text
DeepSeek Harness / 父 Agent
├─ 状态、授权安装、任务委派、artifact 交付
└─ fresh Browser Worker Session
└─ Worker 专属的标签页、页面、定位器、截图和网络工具
└─ 经过身份验证的 loopback WebSocket bridge
└─ Chrome MV3 service worker
├─ 标签页与受限截图
├─ frame-aware DOM runtime
└─ 按需启用且经过脱敏的 network runtime
```
父 Agent 不能直接调用标签页、页面或网络低层工具。页面内容始终视为不可信输入；低层结果只保留一个 Worker 推理步骤；确定性 rollover checkpoint 不包含页面文本、网络正文、输入内容或元素引用。
## 安全边界
- WebSocket 服务只接受 `127.0.0.1`、`::1` 或 `localhost`。
- 配对 token 至少 16 个字符。token 不会写入扩展源码、URL 或 WebSocket 帧；双方通过绑定随机数的 HMAC-SHA-256 证明持有同一 token。
- 只有 `chrome-extension://` Origin 可以进入鉴权阶段；正式部署建议把构建后的固定扩展 ID 写入 `allowedExtensionIds`。
- 插件不提供任意 JavaScript 执行或任意 Chrome DevTools Protocol 命令。
- 密码、OTP、CVV、token、secret 等字段只返回 `sensitive` 与 `filled` 状态，并拒绝向这些字段注入文本。
- Cookie、Authorization、API key、token、session 等网络数据会被脱敏；认证类 endpoint 默认不保留正文。
- 截图和网络正文 artifact 受配额、TTL 和 Worker 所有权约束，只能交付到发起 Session 的工作目录之下。
- 扩展准备必须经过 DSH 原生审批路径；插件不会修改 Chrome Profile、Preferences、Cookies、密码库或扩展策略。
- 加载 unpacked 扩展和授予本地网络权限的最终决定始终由 Chrome 与用户完成。
完整威胁模型和信任假设见[安全模型](./docs/SECURITY.md)。
## 环境要求
- Node.js `^22.19.0 || >=24.0.0`
- Google Chrome 125 或更高版本
- [`package.json`](./package.json) 声明的精确 DSH `0.1.2-rc.1` 与 Cordis `4.0.2` peer 版本
- 至少 16 个字符的 bridge token，通过 `authToken` 或 `DSH_AUTO_CHROME_TOKEN` 提供
## 快速开始
### 桌面版内置安装
当桌面发行版已经内置本插件时，不要重复执行 `dsh plugin add`。
1. 在 Harness 中打开 **设置 → 插件 → Chrome 浏览器**。
2. 下载扩展 ZIP，并将其解压到长期保留的目录。
3. 打开 `chrome://extensions`，启用**开发者模式**，选择**加载已解压的扩展程序**，并选中包含 `manifest.json` 的解压目录。
4. 将 Harness 设置页显示的主机、端口和配对 token 复制到扩展弹窗，然后点击**配对并连接**。
5. 如果 Chrome 询问本地网络访问权限，请允许。返回 Harness 刷新状态，直至扩展和 bridge 均显示已连接。
设置页只读取同源 loopback 状态，并下载当前已安装插件包中的 MV3 bundle；它不会扫描 Chrome Profile 或静默安装扩展。桌面宿主必须提供 `authToken` 或 `DSH_AUTO_CHROME_TOKEN`；缺少有效 token 时插件会 fail closed。
### 独立开发或安装
安装依赖并运行仓库完整门禁：
```bash
npm ci
npm run check
```
生成 token，构建并打包插件，然后将 tarball 安装到隔离的 DSH profile：
```bash
export DSH_AUTO_CHROME_TOKEN="$(openssl rand -hex 32)"
npm run build
npm pack
dsh plugin --profile web add ./dsh-auto-chrome-tool-0.4.2.tgz
dsh --profile web --dump-config
```
发布 tarball 内置 `fflate` 与 `ws` 两项运行时依赖，可用于离线安装。DSH 与 Cordis 仍由宿主以 peer dependency 提供，不会复制进插件包。
## 配置
包自带的 [`cordis.patch.yml`](./cordis.patch.yml) 包含完整默认配置。DSH patch 会替换整个 `config` 对象而不是进行深合并，因此覆盖 row 时需要保留部署所需的全部字段。
| 配置项 | 用途与默认值 |
| --- | --- |
| `host` / `port` | loopback bridge 地址；`127.0.0.1:17321`。 |
| `authToken` | 共享配对 token；为空时读取 `DSH_AUTO_CHROME_TOKEN`。 |
| `allowedExtensionIds` | 可选扩展 ID 白名单；空数组表示允许任何同时持有正确 token 的合法扩展 Origin。 |
| `artifactMaxBytes` / `artifactTtlHours` | 内部 artifact 总配额与保留时间；256 MiB、24 小时。 |
| `chromeExecutablePath` | 可选 Chrome 可执行文件绝对路径；为空时检查各平台标准目录和 `PATH`。 |
| `extensionInstallDir` | 稳定扩展准备目录；默认使用用户目录下的 `.dsh-auto-chrome-tool/extension`。 |
| `openChromeOnInstall` | 授权准备完成后打开 `chrome://extensions`；默认 `true`。 |
| `browserWorkerLlmProvider` / `browserWorkerModel` | 可选的 Worker 专用模型路由；两项必须同时配置。 |
| `browserWorkerSoftTokenLimit` / `browserWorkerHardTokenLimit` | fresh generation 换代阈值；96K、128K tokens。 |
| `browserWorkerMaxSteps` / `browserWorkerMaxToolCalls` | 单任务执行上限；32 个步骤、40 次浏览器调用。 |
| `browserParentMaxDelegationsPerTurn` | 父 Agent 单回合委派上限；8 次。 |
| `browserParentMaxUnsuccessfulDelegationsPerTurn` | 出现 2 次 blocked 或 failed 结果后打开仅限本回合的浏览器熔断。 |
观察、提取、网络预览、超时、历史、并发和消息大小等其他限制，以配置 schema 和默认 patch 为准。
## 工具隔离
父 Agent 只能看到以下浏览器相关工具：
- `browser_status`
- `browser_extension_status`
- `browser_extension_install`
- `browser_delegate_task`
- `browser_artifact_deliver`
fresh Browser Worker 获得低层 `browser_tabs_*`、`browser_page_*` 和 `browser_network_*` 工具目录。执行阶段还会使用进程内身份 guard 强制执行同一边界，手工构造 tool call 也不能绕过 scoped catalog。
为 Selenium 或 Playwright 等可复用自动化生成定位器时，应要求 Worker 捕获已验证定位器。开放 Shadow DOM 会返回经过验证的 host chain；子 iframe 定位器只保证在 frame 文档内唯一，仍需单独验证 frame-switch 路径。
## 仓库结构
```text
src/
browser-worker/ fresh Worker Session、隔离、预算、checkpoint
bridge/ 鉴权 WebSocket 会话与生命周期
client/ Harness 设置页与中英文文案
config/ Schemastery 配置和解析
domain/ 共享 JSON 与错误模型
extension/ MV3 background、DOM 和 network runtime
protocol/ 版本化 DSH ↔ 扩展协议
services/ 浏览器控制、定位器与 artifact 服务
settings/ 同源状态和扩展下载路由
setup/ Chrome 检测、授权准备与启动引导
tools/ 按能力拆分的 DSH tool 定义
extension/ manifest、popup/options UI 和扩展构建产物
tests/ 单元、集成、打包、Client 与 snapshot 测试
docs/ 架构、安全、开发与验证证据
```
## 开发与验证
```bash
npm run typecheck
npm test
npm run test:coverage
npm run test:snapshot
npm run test:built
npm run build
npm run check
npm pack --dry-run
```
`npm run check` 是交付前必须通过的仓库本地门禁，覆盖严格类型检查、Host/Web/扩展构建产物、行为与生命周期测试、宿主侧逐文件覆盖率门槛、打包后行为，以及已评审的无密钥 tool catalog snapshot。
自动化扩展模拟只证明协议和 bridge 行为，不能证明真实 Chrome MV3 连接、Chrome 权限弹窗、桌面打包或主观 UI 质量；这些验收层必须单独执行和报告。详见[开发与验证](./docs/DEVELOPMENT.md)及[已记录的验证证据](./docs/VERIFICATION.md)。
## 已知限制
- 普通 content script 无法控制 `chrome://`、Chrome Web Store、其他扩展页面或 closed Shadow Root。
- 子 frame 定位器只在对应 frame 文档内唯一；插件不会臆造 iframe selector chain。
- opaque DOM 引用刻意保持短期有效；导航或相关语义变化后必须重新获取。
- 打开 DevTools 可能抢占 `chrome.debugger` 会话；网络捕获会明确报告 detach。
- 普通 Chrome 仍需人工完成**开发者模式 → 加载已解压的扩展程序**确认；插件不会绕过 Chrome 安装策略。
- 扩展需要广域站点权限和 debugger 权限，才能实现全页 DOM 控制、截图及按需网络正文捕获。
- Browser Worker 隔离是 DSH 进程内的 Agent/Session/tool/context 边界，并非操作系统进程级隔离。
- DSH `0.1.2-rc.1` 仍为预发布依赖，本项目有意固定精确 peer 版本。
## 文档
- [架构设计](./docs/ARCHITECTURE.md)
- [安全模型](./docs/SECURITY.md)
- [开发与验证](./docs/DEVELOPMENT.md)
- [Browser Worker 设计](./docs/PAGE_ANALYST_DESIGN.md)
- [已记录的验证证据](./docs/VERIFICATION.md)
## 许可证
[MIT](./LICENSE)