longmiaoo/dsh-native-browser

dsh-native-browser

面向 DSH 原生的控制平面，让你在已使用的 Chrome 中实现快速、可观测且可由人工操控的浏览体验。

Status: alpha
Chrome first
License: MIT

dsh-native-browser 让 DSH 智能体能够操作你已经在使用的 Chrome：现有标签页、已登录的会话以及常规扩展，同时具备低延迟的语义观察、可靠的操作、可见的交接以及安全的中断能力。

本项目并不试图成为另一个通用型 Chrome MCP 服务器。Google 官方的 Chrome DevTools for agents 是 DevTools 检查、网络分析、性能追踪、Lighthouse、CSS 和内存调试的天然上游能力层。dsh-native-browser 专注于通用 MCP 服务器不负责的产品层：DSH 对话身份、精确的标签页归属、短期租约、审批策略、操作结果语义、可见的智能体存在感以及即时的人工接管。

目标不是另一个薄薄的 click(x, y) 封装。该设计是一个有状态的浏览器运行时，灵感来自 Codex 的 Chrome 集成中最出色的部分：

- 一个通过 Native Messaging 连接到本地运行时的 Manifest V3 Chrome 扩展；
- 基于 CDP 的控制，无需启动第二个浏览器配置文件；
- 以无障碍树优先的观察方式，配合紧凑的增量更新；
- 稳定的元素引用，加上可操作性检查和命中目标检查；
- 对现有标签页、智能体创建的标签页以及回合结束清理的明确归属；
- 当可见的 DSH UI 切换到另一个对话时，自动释放控制权；
- 即时的人工中断和可恢复的交接；
- 在验证浏览器输入后，仅用于展示的虚拟指针以及点击/滚轮脉冲；
- 截图作为视觉回退方案，而非页面结构的默认来源。

定位

长期方向是 DSH 原生编排，并在合适之处使用第一方 Chrome 能力，而不是对 Chrome DevTools 进行分叉。

| 关注点 | Chrome DevTools for agents | dsh-native-browser |
|---|---|---|
| 主要职责 | 对 Chrome DevTools 的通用 MCP/CLI 访问 | DSH 原生的个人浏览器控制与人机交互体验 |
| 浏览器状态 | 受管配置文件、调试端点或 Chrome 自动连接 | 在用户现有配置文件中显式认领的标签页 |
| 观察 | 带可复用 UID 的无障碍快照 | 有界 AX 窗口、文档纪元、作用域引用和增量观察 |
| 操作结果 | 浏览器输入分发加上有界导航/DOM 稳定等待 | 分发前命中验证、持久化操作日志以及已验证/未知的结果语义 |
| 归属 | 选中的页面或显式页面 ID | DSH 所有者、标签页租约、对话焦点撤销和交接 |
| 人类可见性 | 有头浏览器；目前尚未内置视觉光标 | 仅用于展示的虚拟指针、点击/滚轮脉冲以及扩展的 Stop 控件 |
| 深度调试 | 网络、控制台、CSS、Lighthouse、trace 和堆工具 | 计划通过可选的官方 DevTools 提供程序实现，而不是重新实现 |
| 浏览器范围 | 官方支持 Chrome 和 Chrome for Testing | 先支持 Chrome，同时提供可移植契约和早期 Edge 兼容性门禁 |

当前 alpha 版本仅提供原生 Chromium 路径。chrome-devtools-mcp 的适配器是计划中的提供程序，而不是已实现的功能。它必须通过附加冲突、生命周期、隐私和延迟门禁，才能共享或替换活动浏览器会话的任何部分。关于两个示例，说明为什么 DSH 控制平面仍然有用，请参阅上游讨论：视觉光标支持 和 静默输入误报。

产品基准：Codex

体验基准是 OpenAI Codex 中的浏览器集成：浏览器工作应当感觉像一次连续、可观察的协作，而不是一连串互不关联的远程调用。目标是在可衡量的方面实现体验对等，而不是协议兼容、视觉模仿或使用 OpenAI 私有实现细节。

dsh-native-browser 特别对以下行为进行基准测试：

- 使用用户已经所在的浏览器： 保留已登录状态、打开的标签页和正常的 Chrome 扩展，而不是让日常工作从一次性的自动化配置文件中开始。
- 保持快速路径的语义化： 首先检查紧凑的可访问状态和稳定的元素引用；仅当像素包含必要信息时才使用截图和视觉。
- 让操作既可见又可信： 显示虚拟指针以便人类观察，在输入前立即重新验证命中目标，并验证生成的页面状态，而不是将输入分发视为成功。
- 让人类保持掌控： Stop、直接用户交互、交接、租约到期以及切换可见的 DSH 对话都会撤销控制权，而不会将权限转移给另一个对话。
- 在不泄露所有权的情况下保持连续性： 在工具调用之间保持浏览器连接和观察活动，同时将每个标签页、引用和延续绑定到其所有者、文档纪元（epoch）和连接纪元。
- 保持工作区整洁： 区分用户声明的标签页和代理创建的标签页，关闭临时工作，仅保留明确的交付物或交接内容。
对等性声明需要证据。发布门禁应跟踪真实 Chrome 工作流上的端到端动作延迟、观测大小、过期目标率、已验证动作成功率、重复动作率、中断延迟、对话切换撤销以及标签页清理正确性。在这些门禁广泛通过之前，本 README 将 Codex 描述为基准——而非已完成的等价性声明。

项目状态

公开 alpha——可用于选择性加入的 Chrome 测试，尚未达到生产就绪。 该包包含类型化运行时、每用户 Broker、Native Messaging 主机、共享的 Chrome/Edge 扩展构建、Chromium AX/动作提供程序、一个小型 DSH Web 前台对话桥接以及九个 DSH 工具，包括有界实时页面窗口、单独批准的动作批次以及仅元数据的帧发现。Chrome 设置仍为手动，扩展以未打包方式加载，广泛的页面兼容性、视觉模型准确性以及生产加固仍属于验收工作，而非已完成的声明。

目前已验证：确定性契约/安全测试；将精确的 npm tarball 安装到全新的 DSH 0.1.5-rc.1 配置文件中；在隔离的 Chrome-for-Testing 配置文件中组装本地技术栈；以及在自有夹具上于现有本地 Chrome 配置文件中进行的一次端到端运行。真实的 MV3 扩展、由 Chrome 启动的 Native Host、Unix socket、Broker、已安装的 DSH ToolRuntime、AX 动作、截图附件以及交接路径均已得到验证。实时门禁还覆盖延迟结果、取消、Stop、回合结束后延迟批准，以及 Broker 重启且不重放。尚未有任何敏感业务账户工作流或生产视觉模型准确性声明通过验收。有关确切证据和限制，请参阅开发设置和实现进度。

早期 Edge 兼容性冒烟测试也在隔离的 Edge 配置文件中通过，使用相同的 runtime-core：20 个未更改的执行器夹具预言，外加批次、分页、导航、Stop 和交接检查。这是一个架构门禁，而非正式的 Edge 发布支持；请参阅保留的证据。

范围
帧发现现在会在真实的隔离 Chrome 和 Edge 测试中映射同进程和递归 OOPIF 文档。显式的 browser_observe 帧读取支持同源祖先链，具有独立的子引用/增量，以及通过 frame + query + 可选 rootRef 进行精确的子文档或已知区域查询；browser_read_page({frame,...}) 提供有界的子文档/区域窗口；显式的同源/同进程子点击使用 browser_act({frame,...})，并带有仅限子级的文本验证，包括默认有界视图之外的反馈。其他子操作和跨源批准仍待处理。仅凭帧来源只是元数据，而非权限。截图检查会检查所有已附加的会话；包含外部或不透明后代的可见顶层 iframe 分支会在 MV3 内部被遮蔽，然后字节才会跨 Native Messaging 传输，而不完整的几何信息仍会以失败关闭方式处理。此遮蔽已存在于 main 上，但是在当前已发布的 0.1.0-alpha.2 包之后添加的。参见帧发现。

首个生产版本的范围包括：

- 首先支持 macOS 上的 Google Chrome 稳定版；Windows/Linux 支持遵循单独的安装程序和兼容性门禁；
- 用户现有的 Chrome 配置文件和已认证会话；
- DSH web 和 desktop 配置文件；
- 语义浏览、截图、下载、对话框、文件和多标签页工作流；
- 仅本地的控制平面，具有显式权限和可审计的生命周期事件。

架构接口从第一天起就是跨浏览器的。推迟的生产支持包括：

- Edge 和其他 Chromium 品牌（共享引擎；在正式支持前进行早期冒烟测试）、Firefox 和 Safari（单独的提供程序）；
- 托管/远程浏览器农场；
- CAPTCHA 绕过或隐身声明；
- 直接向模型暴露任意不受限制的 CDP。

计划架构

flowchart LR
W[Visible DSH conversation] -->|opaque session ID| T
A[DSH agent] --> T[Browser tool adapter]
T --> R[Persistent browser runtime]
R --> G[Ownership / policy / journal]
G --> P{Capability router}

P -->|current default| N[Native Chromium provider]
N --> H[Local native host]
H  E[Chrome MV3 extension]
E  C[Claimed Chrome tabs via chrome.debugger / CDP]

P -.->|planned optional route| D[Chrome DevTools MCP adapter]
D -.-> M[Official DevTools MCP sidecar]
M -.-> X[Managed or explicitly connected Chrome]

C --> O[AX / DOM / screenshot observations]
O --> R
U[Human using Chrome]  C
U -. interrupt / handoff .-> R
运行时将实时浏览器对象和事件订阅保持在模型上下文之外。模型接收紧凑的、有类型的观察结果和稳定的引用；运行时在操作前立即执行新鲜度、可见性、稳定性和命中目标检查。能力路由器将暴露一个面向 DSH 的小型接口，并在内部选择一个符合条件的提供方，因此添加 DevTools 或未来的 Edge/Firefox 提供方不会用数十个厂商特定的工具淹没模型。

计划中的 DevTools 适配器是互补的：常规浏览、租约、虚拟指针和人工接管仍保留在原生控制路径上；专门的调试可以委托给官方实现。路由器不会假设两个提供方可以同时附加到同一目标。

当前设计是 v2 运行时实现计划，包括 Vision Router 集成。早期的架构、研究和协议文档是历史输入；它们不会覆盖 v2 计划，也不描述所有当前的实现细节。

DSH 发现元数据

该包被组织为 DSH 捆绑包，并包含生态系统使用的发现术语：

- npm 关键词：dsh-plugin、deepseek-harness、browser-automation、computer-use、chrome-extension；
- GitHub 主题：dsh-plugin、deepseek-harness、browser-automation、computer-use、browser-agent；
- 捆绑包声明：package.json 中的 dsh.bundle.patch；
- 针对 DSH 0.1.5 候选发布版本以及 web/desktop 配置文件的兼容性声明。

安装 alpha 版本

前提条件：macOS、Google Chrome、DSH 0.1.5-rc.1、Node.js 22.19 或更高版本，以及 pnpm 11。npm 包附带已构建的 JavaScript，安装期间不会运行构建脚本。

dsh plugin --profile web add dsh-native-browser@0.1.0-alpha.2
dsh plugin --profile web exec dsh-native-browser extension-path --browser=chrome

打开 chrome://extensions，启用开发者模式，选择 加载已解压的扩展程序，然后选择打印出的目录。记录 Chrome 生成的 32 字符扩展 ID，然后注册原生消息传递主机：

dsh plugin --profile web exec dsh-native-browser install-host --browser=chrome --extension-id=

使用显式允许列表启动本地 Broker。来源是精确的且包含端口；为其他站点重复使用 --allow-origin：

dsh plugin --profile web exec dsh-native-browser broker --allow-origin=https://example.com
在 Chrome 中打开一个允许的页面，点击扩展程序，批准该标签页，然后重启 DSH 配置文件。approvalMode 默认为 per-action。高级测试者可以在其配置文件补丁的 native-browser 行中选择 per-lease，或选择 trusted 并提供一个非空的精确 trustedOrigins 列表。受信任模式仅对这些精确的来源移除重复的 DSH 提示；扩展程序同意、实时租约检查、Stop 和来源检查仍然适用。在使用已登录的页面之前，请参阅显式设置和诊断指南。

对于个人 Chrome 配置文件，显式个人模式使允许的标签页无需提示，并在无凭据的 HTTP(S) 根导航中跟随同一标签页：

dsh plugin --profile web exec dsh-native-browser broker --access-mode=personal

- id: native-browser
config:
approvalMode: personal

Broker 和适配器设置必须同时存在，否则声明将失败关闭。扩展程序在启动时协商 Broker 的显式个人模式能力，然后无需弹出窗口点击即可暴露普通 HTTP(S) 标签页；声明仍然选择一个标签页，并且每个操作仍然受其短标签页作用域租约的限制。开发清单声明了 HTTP(S) 主机访问权限，Chrome 在安装扩展程序时会呈现该权限，因此个人模式和虚拟指针在跨站点导航后仍然可用。前台对话切换、租约到期、交接、断开连接以及扩展程序 Stop 按钮都会撤销控制。此 alpha 版本没有可靠的语义分类器来处理支付、发布或破坏性操作，因此请勿在这些工作流中使用个人模式。

当可见的 DSH UI 切换对话时，客户端桥接会在新选择的对话可以声明控制之前，释放其他对话拥有的浏览器作用域。新对话永远不会继承先前的租约。因此，切换离开会有意中断正在进行的浏览器任务，而不是让后台聊天继续驱动 Chrome。

使用当前 alpha 版本

当前发布的 npm 版本是 0.1.0-alpha.2。以下示例使用 DSH web 配置文件；如果插件安装到了其他配置文件，请一致地替换 web。

启动浏览会话

1. 确保已按上述说明安装了解压后的扩展程序和 Native Messaging 主机。升级 npm 包后，请在 chrome://extensions 上重新加载解压后的扩展程序；扩展程序文件由已安装的包版本提供，不会在已运行的 Chrome 扩展程序内部自动更新。
2. 在终端中启动一个 Broker 并保持其运行。对于普通的个人浏览：

dsh plugin --profile web exec dsh-native-browser broker --access-mode=personal

DSH 配置文件补丁中匹配的 native-browser 行必须使用：

- id: native-browser
config:
approvalMode: personal

更改补丁后，重启该 DSH 配置文件。若要改为保留显式的逐操作或逐租约批准，请使用精确的 --allow-origin= 条目启动 Broker，并使用上文所述的相应适配器批准模式。不要针对同一运行时目录同时运行受限 Broker 和个人 Broker。
3. 在 Chrome 中打开你想要使用的标签页。当 Chrome 或扩展程序请求站点访问权限时，仅将其授予目标标签页/站点。扩展程序弹出窗口同时也是紧急停止控件。
4. 正常与 DSH 对话。代理会自动发现 browser_* 工具；用户无需构造租约 ID、元素引用、文档纪元或请求 ID。

首次运行的安全提示词：

列出我当前 Chrome 中可用的标签页，只汇报，不做任何操作。
接管标题为“Example Domain”的标签页，读取页面内容，然后释放浏览器控制。
在我指定的标签页中填写这个测试表单，提交前先停下来让我确认。

对于较长的任务，请明确标识目标标签页并说明停止条件。DSH 将认领该标签页，观察其语义页面状态，执行受支持的操作，并在被要求时通过 browser_handoff 释放它。认领是独占的：另一个 DSH 对话无法复用它。切换可见的 DSH 对话会主动撤销前一个对话的浏览器控制权，因此请让新选择的对话重新认领该标签页。

此版本能做什么

- 列出已连接的 Chrome 实例和符合条件的现有标签页；
- 认领一个标签页并读取有界的可访问文本、控件和命名区域；
- 导航、点击、填写、追加文本、按下受支持的按键、设置复选框/单选按钮状态、滚动并发送经过验证的滚轮事件；
- 运行最多包含八个显式操作的有界批次，在遭到拒绝、出现不确定情况或验证失败时停止；
- 翻阅大型语义文档并读取受支持的同源子框架；
- 将当前视口捕获为 DSH 附件，并将控制权交还给用户；
- 在验证点击或滚轮派发后显示一个短暂的虚拟指针。

正常的快速路径是语义观察，而不是屏幕截图。此插件会发布屏幕截图附件，但本身不运行视觉模型；视觉定位需要具备视觉能力的 DSH 会话以及单独配置的工具，例如 dsh-vision-router。已发布的 0.1.0-alpha.2 包在包含跨源或不透明框架的普通页面上可能会安全失败。当前的 main 则会改为对安全定位的外部框架区域进行遮蔽，但当框架清单或遮蔽几何信息不完整时仍会安全失败。当屏幕截图被拒绝时，文本读取和语义操作仍可能在已授权的根页面上正常工作。

检查安装

使用 chrome://extensions 显示的扩展程序 ID：

dsh plugin --profile web exec dsh-native-browser doctor --browser=chrome --extension-id=
dsh plugin --profile web exec dsh-native-browser status
doctor 报告 ready 证明本地注册、Broker 协议和匹配的已连接扩展是健康的；它不会授予标签页租约，也不证明任意站点都受支持。如果 DSH 未列出任何标签页，请检查正在运行的 Broker 模式、扩展/站点同意情况，以及 DSH 适配器是否使用了匹配的审批模式。在截图捕获期间出现通用的 Remote operation failed 目前可能意味着跨源框架策略拒绝了该图像；请改为读取/观察页面，并在重试前检查 DSH 跟踪。

开发

先决条件：Node.js 22.19 或更高版本以及 pnpm 11。

pnpm install
pnpm check
pnpm test
pnpm test:chrome
pnpm pack

仅建议使用明确标注版本的 alpha 进行测试。请勿将其用于支付、破坏性业务操作、密码输入或无人值守操作。

在提交更改之前，请参阅 CONTRIBUTING.md。安全敏感问题应遵循 SECURITY.md，而不是公开 issue。

致谢

本项目受益于浏览器代理生态系统中出色的工作：

- Chrome DevTools for agents，由 Google ChromeDevTools 维护，展示了基于标准的 MCP 接口如何使 Chrome 自动化、调试和性能分析广泛可用。在适用的情况下，其 DevTools 能力是未来首选的集成路径。
- OpenAI Codex 启发了这样一个产品目标：让浏览器感觉连续、可见，并且易于交还给人类。dsh-native-browser 是基于公开行为和文档的独立实现；它与 OpenAI 无关联，也未获得其认可。
- DeepSeek Harness 提供了本包所构建的插件、配置文件、工具和审批模型。
- Chrome DevTools Protocol、Chromium Accessibility 和 Chrome Extensions 平台提供了原生提供程序背后的浏览器原语。
- Puppeteer 和 Playwright 为弹性浏览器生命周期、定位器、可操作性及测试提供了有价值的参考实现。
- dsh-vision-router 帮助塑造了可选的视觉回退边界：截图和视觉是对语义观察的补充，而不是替代。

名称和商标属于其各自所有者。致谢并不意味着赞助或认可。未来纳入的第三方源代码将保留其所需的许可证和声明信息。

设计原则

1. 快速路径是语义化的。 对于日常工作使用 AX/DOM 状态，仅在像素承载关键含义的地方使用图像。
2. 动作验证现实。 重新解析目标、滚动、等待稳定、命中测试、执行操作，然后观察产生的变化。
3. 浏览器状态有归属。 现有用户标签页会被认领和释放；代理标签页会被跟踪和清理。
4. 人类控制立即生效。 用户交互或扩展停止操作会取消进行中的工作，并产生可恢复的状态。
5. 对话焦点是控制边界。 切换可见的 DSH 对话会撤销后台浏览器作用域；权限被释放，绝不转移。
6. 能力是显式的。 敏感操作范围狭窄、受策略门控且可审计；原始 CDP 是内部传输。
7. 性能是被测量的。 延迟、观察大小、过期引用率、操作成功率和恢复行为都是基准门槛。

虚拟指针提高了可观测性，但绝不是输入原语：语义发现和最后一刻的命中测试先选择目标，浏览器派发真实输入，然后扩展才绘制指针。绘制失败不能授权、重新定位目标、延迟或重放操作。

许可证

MIT