changyinliangbaikai/dsh-b2us-chrome-tool

dsh-b2us-chrome-tool

面向 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 认证，并限制大小、并发、超时和资源生命周期。 |

工作原理

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 与用户完成。

完整威胁模型和信任假设见安全模型。

环境要求

- Node.js ^22.19.0 || >=24.0.0
- Google Chrome 125 或更高版本
- 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。

独立开发或安装

安装依赖并运行仓库完整门禁：

npm ci
npm run check

生成 token，构建并打包插件，然后将 tarball 安装到隔离的 DSH profile：

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 包含完整默认配置。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 路径。

仓库结构

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/              架构、安全、开发与验证证据

开发与验证

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 质量；这些验收层必须单独执行和报告。详见开发与验证及已记录的验证证据。

已知限制

- 普通 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 版本。

文档

- 架构设计
- 安全模型
- 开发与验证
- Browser Worker 设计
- 已记录的验证证据

许可证

MIT