← Back to home@changyinliangbaikai

dsh-b2us-chrome-tool

No description

Stars
0
Language
TypeScript
Created
Aug 29, 2026
Updated
Aug 31, 2026
Browser
GitHub repo

Introduction

dsh-auto-chrome-tool

dsh-auto-chrome-tool 是一个面向 DeepSeek Harness（DSH）的本地浏览器控制插件。它通过 Chrome Manifest V3 扩展连接用户正在使用的浏览器，把经过白名单约束的标签页、DOM 交互、截图和网络观测能力注册为 DSH tools。

当前版本面向本地开发和受信任环境。它不会读取 Chrome 密码库，不会选择密码管理器候选项，也不会把密码输入框的值返回给 Agent。

能力

  • 标签页：列出、打开、导航、关闭。
  • 页面观察：返回可访问名称、角色、状态和短期有效的 opaque 元素引用。
  • 源侧查找：page.find 在页面运行时先做语义检索，只返回排序后的命中元素，不把整页源码交给模型。
  • 可验证定位器：page.locator 在真实 DOM 中生成 CSS/XPath 候选并逐一做唯一性复验，供 Agent 编写可直接验证的 Selenium 等自动化脚本。
  • 页面操作：点击、输入普通文本、选择、滚动、等待和结构化提取。
  • Artifact：截图和完整网络正文先写内部短期存储，Worker 只看到 opaque ID 与安全元数据；可信宿主再按父会话 cwd 交付，不向 Worker 暴露路径。
  • 网络观测：按标签页、按需附加 chrome.debugger，捕获 Fetch/XHR 元数据及受限正文。
  • 安装助手：DSH 启动时检测 Google Chrome；首次需要浏览器能力时通过 DSH 原生一次性审批准备扩展，并打开 chrome://extensions。
  • 设置页面：在“设置 → 插件 → Chrome 浏览器”直接查看 Chrome、扩展与本地桥接状态，下载随桌面版内置的配套扩展，并复制配对参数。
  • 安全边界：仅监听 loopback、扩展 Origin 校验、双向 nonce/HMAC 配对、大小/并发/超时限制、敏感字段与网络凭据脱敏。
  • 上下文隔离：主 Agent 用 browser_delegate_task 声明浏览器目标及 typed deliverables；页面数据进入插件内置的 fresh Browser Worker 独立 Session，父会话只收到受限结构化结果。
  • 可恢复交付：浏览器执行状态与 artifact 交付状态分别返回；交付失败为 partial，可用 browser_artifact_deliver 单独重试，不重复登录、提交等页面动作。
  • 独立换代：Worker 默认 96K soft / 128K hard token 阈值，使用不含页面正文和 ref 的确定性 checkpoint 启动新一代，最多 4 次。

结构

src/
  client/       # Harness Web 设置页、状态校验、安装引导与中英文文案
  browser-worker/ # 独立 Agent/Session、工具隔离、结果淘汰、checkpoint 与 rollover
  bridge/       # WebSocket 会话、请求关联与生命周期
  config/       # DSH Schemastery 配置
  domain/       # JSON、错误等共享模型
  extension/    # MV3 后台、DOM runtime、network runtime
  protocol/     # DSH ↔ 扩展的版本化消息协议
  services/     # 浏览器控制与 artifact 服务
  setup/        # Chrome 定位、扩展校验/部署、DSH 审批与启动提示
  settings/     # 同源状态/扩展下载路由与 ZIP 生成
  tools/        # 按领域拆分的 DSH tool 定义
extension/      # manifest、popup/options UI、构建输出
tests/
  unit/         # 协议、引用、脱敏等纯逻辑测试
  integration/  # 真实 loopback WebSocket 模拟通信
  fixtures/     # 页面测试夹具
docs/           # 架构、安全和验证说明

详细边界见 docs/ARCHITECTURE.md，安全模型见 docs/SECURITY.md，本次实测结果见 docs/VERIFICATION.md。

构建

要求 Node.js ^22.19.0 || >=24.0.0。

npm install
npm run check

产物：

  • DSH 插件：lib/
  • Harness Web 设置页：lib/client.js
  • 可加载的 Chrome 扩展：extension/dist/

配置与安装

桌面版内置场景

桌面壳已经随运行时装入本插件时，用户无需再执行 dsh plugin add。打开 设置 → 插件 → Chrome 浏览器 即可完成后续操作：

  1. 查看当前系统是否检测到 Google Chrome，以及本地桥接是否等待连接。
  2. 点击“下载扩展 ZIP”，将其解压到长期保留的目录。
  3. 在 chrome://extensions 开启“开发者模式”，选择“加载已解压的扩展程序”，并选中包含 manifest.json 的解压目录。
  4. 在设置页复制主机、端口和配对令牌，填入扩展弹窗后点击“配对并连接”。如 Chrome 询问本地网络访问权限，请允许。
  5. 返回设置页点击“重新检测”，确认“配套扩展”和“本地桥接”均显示已连接。

设置页只通过 Harness Web Host 的同源 loopback 路由读取状态与下载当前包内的 MV3 bundle；它不会扫描 Chrome Profile，也不会静默安装扩展、修改 Preferences 或绕过 Chrome 的最终确认。配对令牌默认隐藏，只在这个本机设置页中按需显示或复制。

桌面打包方仍须在启动 Host 时提供至少 16 字符的 authToken 或 DSH_AUTO_CHROME_TOKEN。未提供时设置页会明确显示桥接未启用，而不会生成弱令牌或自动改变部署配置。

独立开发/安装

先生成至少 16 字符的随机 token，例如：

export DSH_AUTO_CHROME_TOKEN="$(openssl rand -hex 32)"

构建并打包后安装到独立 DSH profile：

npm run build
npm pack
dsh plugin --profile web add ./dsh-auto-chrome-tool-0.4.1.tgz
dsh --profile web --dump-config

发布 tarball 会内置 fflate 与 ws 两项运行时依赖，因此可以由桌面壳的离线安装页在全新 Profile 中安装；安装过程不需要访问 npm registry。DSH/Cordis 单例仍通过 peer dependency 使用宿主版本，不会被复制进插件包。

也可以在 profile 对 dsh-auto-chrome-tool 的完整 config 进行覆盖。DSH patch 会替换整份配置而不是深合并，覆盖时请保留所需字段。allowedExtensionIds: [] 表示允许任意 Chrome 扩展 Origin 在持有正确 token 时配对；正式使用建议填入构建后的固定扩展 ID。artifact 默认最多保留 256 MiB、24 小时，可用 artifactMaxBytes 和 artifactTtlHours 调整。

启动检测与授权安装

插件加载时会按 macOS、Windows、Linux 的标准位置和 PATH 检测 Google Chrome：

  • 未检测到 Chrome：启动日志和新 Agent 的非唤醒上下文会明确标记插件不可用；浏览器操作会 fail closed，并提示先安装 Chrome。
  • 检测到 Chrome但扩展未准备：browser_extension_status 返回安装状态；首次浏览器操作会要求主 Agent 先调用 browser_extension_install。
  • browser_extension_install 必须经过 DSH tools/pre-execute → ctx.approval 的一次性用户授权。无 Agent、无审批通道、拒绝或取消时均不会写文件。
  • 授权后，插件校验随包发布的 MV3 bundle，将其原子部署到稳定的用户目录，再打开 chrome://extensions。它不会读取或修改 Chrome profile、密码库、Cookies 或 Preferences。

Chrome 官方安全策略不允许普通本地程序仅凭自己的授权弹窗，静默安装未上架扩展；Chrome 137 起，正式版 Chrome 也不再接受 --load-extension。因此最后一步必须由 Chrome 自己确认：

  1. 打开 chrome://extensions，启用“开发者模式”。
  2. 选择“加载已解压的扩展程序”，目录指向 browser_extension_install 返回的 installPath。
  3. 打开扩展弹窗，填写设置页显示的主机、端口和相同 token（默认组合为 ws://127.0.0.1:17321）。
  4. 点击“连接 DSH”。Chrome 147+ 可能询问本地网络访问权限；该首次连接必须由这次用户点击触发。

DSH 的审批请求必须位于一个正在执行的 Agent 回合内，插件初始化阶段本身不能合法发起审批。因此“启动提示”采用 DSH 官方的 agent/session-start + agent.inject() 非唤醒上下文；用户第一次实际需要浏览器能力时，安装 tool 才触发可审计的一次性授权，不会为无关任务自动唤醒模型。

可选配置：

  • chromeExecutablePath：自动检测失败时指定 Google Chrome 可执行文件。
  • extensionInstallDir：扩展稳定部署目录；留空时使用用户目录下的 .dsh-auto-chrome-tool/extension。
  • openChromeOnInstall：授权部署后是否自动打开 chrome://extensions，默认 true。
  • browserWorkerLlmProvider / browserWorkerModel：成对设置专用 Worker 模型；留空时继承父 Agent 路由。
  • browserWorkerSoftTokenLimit / browserWorkerHardTokenLimit：独立压力阈值，默认 96000 / 128000，hard 必须大于 soft。
  • browserWorkerMaxRollovers：单任务最多 fresh generation 换代次数，默认 4。
  • browserWorkerMaxSteps / browserWorkerMaxToolCalls：单任务模型步骤与浏览器调用硬上限，默认 32 / 40。
  • browserWorkerMaxNoProgressActions / browserWorkerMaxRepeatedFailures：无进展动作与同错重试熔断，默认 8 / 3。
  • browserWorkerTaskTimeoutMs：单任务墙钟超时，默认 180000；触发后返回有界结构化失败。
  • browserParentMaxDelegationsPerTurn / browserParentMaxUnsuccessfulDelegationsPerTurn：同一父 Session 当前 Agent 回合内，跨 fresh Worker 累计的委派总数与失败/阻塞结果上限，默认 8 / 2。达到上限后仅阻止后续 browser_delegate_task，新用户回合自动复位，不会取消主 Agent 或限制 DSH 的其他工具和子代理。
  • browserWorkerMaxObservationElements / browserWorkerMaxObservationTextChars：页面观察宿主硬上限，默认 200 / 24000。
  • browserWorkerMaxExtractionChars、browserWorkerMaxNetworkEntries、browserWorkerMaxNetworkPreviewChars：提取、网络列表与正文预览上限。

正常模型目录中，主 Agent 只能看到状态、安装、browser_delegate_task 与 browser_artifact_deliver 五个浏览器相关工具。tab/page/network 低层工具仅对带进程内 Worker 身份的 fresh child 可见；执行器还会以 monotonic guard 再校验一次，不能通过手工构造 tool call 绕过。

用户要求“保存到当前目录”时，主 Agent 应在委派参数中声明 destination.scope=session-cwd 和可选的 portable relative path。宿主拒绝绝对路径、..、符号链接祖先、跨平台非法名称和默认覆盖；collision=rename 才会选择数字后缀。Worker 只负责生成并声明 artifact，不调用 shell、文件工具或 file://。委派参数也拒绝明文密码、token 和 API key；登录凭据应由 Chrome 自动填充，缺少可信凭据能力时应停止并请求用户处理。

动态页面上的已命名主 frame 控件应优先使用 browser_page_click_named：查找、唯一精确匹配和点击在 content script 的同一个事件循环内完成。普通 opaque ref 仅在目标元素自身仍连接且语义指纹未改变时有效；页面其他区域的时钟、轮询或样式更新不会再让全页 ref 一并失效。

编写 Selenium、Playwright 等可复用脚本时，主 Agent 应把“读取真实定位器”作为浏览器委派目标。Browser Worker 对目标调用 browser_page_locator 后只得到 opaque locator ID；扩展在当前 Document 或开放 Shadow Root 中生成最多 8 个 CSS/XPath 候选并确认每个候选只命中同一元素，Host 再将可信 bundle 交给父 Agent。推荐顺序为稳定 id、测试属性、name/aria-label、稳定 class，最后才是结构路径；UUID、长哈希和连续数字等动态值不会被当作稳定锚点。

返回的 recommended、candidates 均包含 verified=true、matchCount=1、stability 和 strategy。开放 Shadow DOM 额外返回从外到内的 shadowPath，且不会伪造不可用的 XPath；子 iframe 返回 FRAME_LOCAL_SELECTOR，在没有另行验证 frame-switch 路径时不得直接生成占位选择器。父 Agent 仍须真实运行生成的脚本，失败时重新读取页面和定位器后再修复，不能把“生成过选择器”等同于 Selenium 已验证成功。

连接成功后，后台 service worker 会维持连接并通过 alarm 恢复。若本地网络权限被拒绝，请在扩展的站点/本地网络权限设置中恢复后重试。

安装时 Chrome 会显示“读取和更改网站数据”以及调试器相关的高权限警告，这是全站 DOM 控制、截图和按需网络响应正文捕获所必需的。扩展不会在安装后自动附加调试器：截图时仅执行一次受限的 Page.captureScreenshot 并立即释放由本次操作创建的会话；持续网络捕获只有在 browser_network_start 明确调用后才会附加到指定标签页。

常用命令

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

测试矩阵和真实 Chrome E2E 的限制见 docs/DEVELOPMENT.md。

已知限制

  • chrome://、Chrome Web Store、其他扩展页面和 closed shadow root 不能由普通 content script 控制。
  • 子 iframe 的元素定位器只保证在该 frame 文档内唯一；当前版本不会猜测 Selenium 的 iframe 选择器链。
  • DOM 引用只在创建它的文档快照内有效；导航或重新观察后应重新获取引用。
  • 打开 DevTools 可能抢占 chrome.debugger 会话，网络捕获会明确报告 detach。
  • 当前 loopback WebSocket transport 为可替换边界；高安全部署建议后续实现 Native Messaging transport。
  • 普通 Chrome 的本地 unpacked 扩展仍需要 Chrome 自己完成“开发者模式 / 加载已解压”确认；全自动静默部署只属于 Chrome Web Store 或受管企业策略场景。
  • DSH 0.1.1 仍处于 Developer Preview，本项目把宿主 SDK 固定为经验证的精确版本。
  • Browser Worker 与插件位于同一 Node 进程；当前保证 Agent/Session/工具/上下文边界，不宣称操作系统进程级隔离。

License

MIT