浏览器直控桥lyd123qw2008/pi-control-chrome

pi-control-chrome

English · 简体中文

面向 Pi、Codex 和 DSH 的、与 Codex 对齐的 Chrome 和 Edge 浏览器控制。它通过本地 WebSocket Bridge 和 Manifest V3 扩展复用用户现有的 Chromium 配置文件。

Stage 1/2 核心实现已完成。后续阶段的能力仍单独记录在 FEATURES.md 中。

它提供什么

- 复用当前的 Chrome 或 Edge 配置文件、登录状态、Cookie、扩展和标签页。
- 让 Pi 检查并认领显式选定的现有标签页，默认不移动它们。
- 将 Agent 创建的标签页放入专用的蓝色 Pi 标签组。
- 跟踪 Agent 所有权、会话、handoff 和 deliverable 生命周期状态。
- 在回合结束时关闭未标记的 Agent 临时标签页，释放已认领的用户标签页而不关闭它们，并仅保留为当前回合标记的 handoff 或 deliverable 标签页。
- 提供 DOM、无障碍、定位器、坐标和原生 CDP 控制。
- 默认返回有界的语义页面状态：可见/可操作的快照节点、20,000 字符/200 节点的快照和 DOM-CUA 预算，以及共享的 12,000 字符提取预算。默认包含同源 iframe 文本，并带有有界的 frames 诊断信息；传入 includeFrames: false 可仅检查外壳。browser_snapshot 保留 refs 和 snapshotId，而 Pi/DSH 投影省略重复的原始无障碍和 frameTree 数据；Bridge 公布 capabilities.compactResponses 并协商紧凑的页面读取响应，而未指定的模式对较旧的消费者保持原始兼容；当标签页元数据已带有标题和 URL 时，投影不会在页面结果中重复它们，并且在没有可用语义状态时，完整页面文本保留给 browser_extract。
- 无障碍读取优先使用真实的 Chromium AX 树，并支持完整、增量差异和未更改状态；可操作/可聚焦的 AX 节点可能带有文档作用域的 aN refs，这些 refs 需要匹配的 snapshotId 才能进行操作。敏感值在 AX 和定位器结果中保持脱敏。如果 Accessibility 域不可用，读取会安全地回退到 DOM 语义树。仅在需要完整 AX 状态时传入 disableDiffing: true。快照、无障碍、提取和 DOM-CUA 读取接受可选的 selector、includeFrames 和输出预算。Pi 和 DSH 适配器在分发前省略空的可选 selector、snapshotId、incarnation 和截图 path 字段。
- 普通 role/name、label 和可访问文本定位器、等待和交互目标现在优先尝试 Chromium AX。AX 解析计算出的 role/name/state，然后在现有 document/frame 围栏下映射当前后端 DOM 节点；成功的操作将内部来源暴露为 resolvedBy: "chromium_ax"。AX 歧义、不完整的树和不安全的 DOM 映射会安全失败。只有 Accessibility 域不可用，或者仅文本目标的自定义可点击元素在 AX 中不存在时，才使用有界 DOM 回退；选择器、测试 ID 和占位符仍由 DOM 驱动。
- 在通过 Bridge 返回之前，将 browser_evaluate 结果限制为深度 8、2,000 个数组项、200 个对象字段和 200,000 个字符。
- 支持截图、页面提取、Console、Network、JavaScript 对话框、文件上传、下载和剪贴板文本。Console 和 Network 列表每次读取最多保留 200 个条目和 20,000 个序列化字符；Console 读取支持有界的 only: "errors" 过滤以及 since/nextSince 游标，包括 pageerror 事件。
- browser_probe_interaction 只执行一个显式页面操作，并在返回前提供操作前后的文档身份、操作确认、操作后的 Console 错误、稳定状态以及操作后的目标状态，用于 UI 回归诊断。它绝不会重放不确定的副作用。
- 捕获普通活动标签页视口截图，而无需打开 DevTools 调试器会话；整页和后台标签页捕获使用短暂的会话自有调试器租约。
- 在 MV3 worker 重启后持久保留调试器租约身份。普通清理会报告未经验证的旧租约，而不是分离未跟踪的目标；显式陈旧恢复会在分离前验证当前标签页围栏和 CDP 目标身份。
- 使用标签页围栏和文档身份来围栏标签页句柄。快照引用和 DOM-CUA 节点 ID 是其原始文档内的实时观察：标题/焦点变化、用户切换标签页、后续观察以及无关的 DOM 变动不会使其失效；原始已分离节点只有在强等价替换唯一时才能重新绑定一次。导航、重新加载和文档替换仍是硬边界，并会以 BROWSER_DOCUMENT_CHANGED 拒绝旧观察；标签页关闭和标签页围栏变化会以 BROWSER_TAB_CLOSED 和 BROWSER_TAB_FENCE_CHANGED 拒绝它们；navigate(wait: false)、back、forward 和 reload 返回一个标记为 transitionPending 的标签页，其句柄省略不稳定的 URL/title 和文档化身字段，因此在进行文档绑定工作之前请等待或重新观察。只读页面读取会重新观察用户标签页，并在其文档变化时重试一次，而丢失文档身份的副作用操作会返回不确定结果，并且不会自动重放。
- 通过应用心跳保持 Manifest V3 Bridge 套接字活跃，防止空闲 worker 挂起在长时间浏览器等待期间造成可避免的连接代际抖动。
- 包含一个可复用的 pi-control-chrome Skill。浏览器工具 schema 在该 Skill 为当前会话显式加载之前保持隐藏；捆绑的 CLI 仍可用于显式的人工/开发者工作流和测试。

语义页面交互

常见的点击和表单工具接受语义化的 target，例如 { "role": "button", "name": "Submit" }、{ "label": "Email" }、{ "placeholder": "Search" }、{ "text": "Next" } 或 { "testId": "submit-button" }。语义交互会等待一个可见匹配项，并在目标缺失、隐藏、禁用或存在歧义时失败关闭；仅当多个匹配是有意为之的时候，才使用显式的从零开始的 index。操作会在可见性过滤之后应用该索引，因此隐藏的重复控件不会消耗它。Role/name、label 和可访问文本目标优先使用 Chromium 计算出的 AX 语义，并在成功映射的操作上返回 resolvedBy: "chromium_ax"；CSS 选择器、测试 ID 和占位符继续通过 DOM 解析。同源 iframe AX 节点参与同一个有界语义读取，而跨源 frame 内容仍是一个诊断边界。browser_snapshot 返回文档作用域的实时 eN 引用和一个 snapshotId；在每次基于 ref 的交互或元素状态等待时，传入匹配的 snapshotId。解析器首先使用原始已连接元素，并允许一次唯一的、强等价的同文档重新绑定；CSS 选择器仍然受支持。

操作和元素状态定位器使用的文本目标会将匹配的文本叶子节点投射到其最近的可操作祖先，因此 isEnabled 和 browser_wait 会报告接收该操作的控件的状态。browser_wait 支持 load、url、text、text_gone、visible、hidden 和 enabled。文本条件使用 text；元素条件使用与交互所接受的相同语义 target。url 和 urlIncludes 可以约束每个等待条件。当目标没有可见匹配项时，hidden 会成功，包括目标不存在或多个隐藏匹配项的情况；visible 和 enabled 要求一个可见匹配项，多个可见匹配项会失败关闭。对于 visible 和 enabled，显式索引会在可见性过滤之后应用。浏览器页面匹配在选定的标签页内运行，而 Bridge 继续强制执行现有的浏览器目标和连接代际围栏。如果产生副作用的交互在导航后丢失了其注入结果，它会报告不确定的结果，并且绝不会自动重放。

架构

Pi Extension
↕ WebSocket
127.0.0.1 Local Bridge
↕ WebSocket
Chrome / Edge Manifest V3 Extension
↕
Current Chromium Profile
Bridge 绑定到回环地址，并要求本地配对令牌才能进行 WebSocket 操作。其 /pair 引导响应有意向该回环端口上的任何调用者开放，以便未打包的扩展无需读取主机令牌文件即可配对；因此，任何能够访问该端口的本地进程或已安装扩展都被信任拥有浏览器控制权。请让 Bridge 端口远离网络代理。主机启动的实例会暴露一个非机密的实例 ID、启动器标签和能力列表；当 Bridge 暴露 capabilities.localUserRestart: true 且没有待处理的浏览器请求时，同一本地用户控制域中的任何已配对 DSH 或 Pi Host 都可以请求协作式重启。实例 ID 可防止过期的重启竞争，而重启锁会串行化并发请求。当未知的旧版 Bridge 未暴露本地用户能力时，它们保持不受影响。安装扩展并完成本地配对即为信任步骤；正常的浏览器操作不会请求重复的逐操作授权。

安装

从 npm 安装（推荐）

pi install npm:pi-control-chrome

从 GitHub 安装

pi install git:github.com/lyd123qw2008/pi-control-chrome

从本地检出安装

pi install /pi-control-chrome

该包通过其 package.json 中的 pi 清单注册 Pi 扩展和捆绑的 Skill。它需要 Node.js 22 或更高版本。

DSH 集成

此仓库还包含独立的 @lyd123qw2008/dsh-tool-control-chrome 包。它将相同的浏览器控制界面注册为面向模型的 DeepSeek Harness 工具，并通过本地 Bridge 路由调用。在活动的 DSH Profile 中安装该 DSH 包：

dsh plugin --profile web add @lyd123qw2008/dsh-tool-control-chrome

然后，在手动安装时，将其 cordis.patch.yml 中的 insert 条目合并到现有的 cordis.patch.yml 中（dsh plugin --profile web add 会自动应用该捆绑补丁），并将 Bridge 设置保留在 /settings.yaml 中。
DSH 包复用了本项目的 Bridge 和 Manifest V3 扩展。其默认的 lazyTools: true 模式最初仅暴露 pi-control-chrome Skill 元数据；在 Skill 成功加载后，全部 43 个 browser_ 工具会在该 Agent 中注册，并在当前 Agent 会话的后续轮次中保持活跃。在轮次结束时，宿主会关闭未标记的 Agent 临时标签页，释放已认领的用户标签页但不关闭它们，并解除会话调试器租约。Bridge、浏览器工具和 Browser 绑定在后续轮次中仍然可用。模型必须调用 browser_mark_handoff 或 browser_mark_deliverable，才能在当前轮次清理过程中保留某个 Agent 标签页，并在需要时于后续轮次中重复该标记。只有用户明确要求关闭临时标签页、释放认领或清理浏览器任务时，才可触发 browser_cleanup；它会立即执行任务清理，同时保留惰性工具和健康的 Bridge。browser_context_reset 是另一个由用户明确请求的独立操作，用于最终确定资源并停用惰性工具。Agent 和插件销毁时会重试最终清理；恢复失败会阻止复用同一会话 ID 的替代 Agent，直到清理成功。将 lazyTools 设为 false 可实现即时可见性。Pi 会一次性注册相同的原生工具，但在显式执行 /skill:pi-control-chrome 展开或另一次成功的 Skill 激活之前，会通过其活跃工具集将其隐藏。普通网页搜索不会激活浏览器控制。DSH 包还提供仅供人工使用的 /chrome status、/chrome targets、/chrome profile [browserId]、/chrome connect、/chrome disconnect、/chrome doctor、/chrome restart 和 /chrome tabs 命令。它不会自动安装浏览器扩展、读取 Chrome Profile 文件，也不会将 Bridge 暴露到回环地址之外。

Codex CLI 和 Desktop

该仓库包含一个 Codex 插件清单和一个本地 MCP stdio 适配器。在安装包含此适配器的包版本后，使用 codex mcp add pi-control-chrome -- pi-control-chrome-codex 注册它，或将 codex mcp add 指向本检出目录中的 codex/mcp-server.mjs。该适配器复用现有的 Bridge，并暴露受限的 Codex 浏览器工具集，包括在用户明确确认后的 browser_restart；它不会打开额外的 MCP 端口。有关设置和安全规则，请参阅 codex/README.md。

加载浏览器扩展

Pi 无法自动安装未打包的浏览器扩展。请在 Chrome 或 Edge 中一次性加载共享的 extension/ 目录：

1. 打开 chrome://extensions 或 edge://extensions。
2. 启用 开发者模式。
3. 选择 加载已解压的扩展程序。
4. 选择仓库或已安装包中的 extension/ 目录。
5. 启动或重新加载 Pi。

在 Pi 中检查连接：

/chrome status
/chrome targets
/chrome profile
/chrome tabs
该扩展由 Chrome 和 Edge 共享，并使用 Chromium Manifest V3 能力检测，而非针对不同浏览器的单独实现。现在，一个 Bridge 可以同时保持多个已识别的浏览器目标连接。每个目标以其稳定的 browserId 为键；请求使用目标限定的路由和连接代际隔离，因此 Profile A 的较新连接无法替换 Profile B，也无法满足 Profile A 的过期请求。当有多个目标可用时，请使用 /chrome profile  或 browser_status/Skill CLI 的 --browser-id 显式选择一个；运行时绝不会根据最新连接或活动窗口进行猜测。

Skill CLI

捆绑的脚本用于显式的人工/开发者工作流和自动化测试。它们直接连接到 Bridge，不得由模型 shell 调用以替代受 Skill 门控的原生工具：

node skills/pi-control-chrome/scripts/browser.mjs status --browser-id
node skills/pi-control-chrome/scripts/browser.mjs tabs --browser-id  --json
node skills/pi-control-chrome/scripts/browser.mjs group --browser-id  --json
node skills/pi-control-chrome/scripts/browser.mjs view https://example.com --browser-id  --session example-session --turn 1 --screenshot "$env:TEMP\example.png"
node skills/pi-control-chrome/scripts/browser.mjs cleanup --browser-id  --session  [--recover-stale]

受管理的 CLI 命令使用显式的生命周期标识：open 和 cleanup 需要 --session ，而 view 需要同时提供 --session  和 --turn ，除非它被显式设为临时操作。CLI 不会从进程 ID 推导归属关系，因此后续调用可以安全地操作相同的标签页。仅在扩展运行时变更后做出显式恢复决策时，才使用 cleanup --recover-stale；它会遗忘匹配的未知化身归属记录，而不会关闭这些标签页，并在 recovered 中报告其 ID 以供人工检查。

捆绑的脚本支持以下环境变量。当本地 Bridge 使用另一个回环端口时，Pi 扩展也接受 PI_CONTROL_CHROME_BRIDGE_PORT；其主机仍为 127.0.0.1：

PI_CONTROL_CHROME_BRIDGE_HOST   # bundled CLI only
PI_CONTROL_CHROME_BRIDGE_PORT   # bundled CLI and Pi extension

已检入的浏览器扩展仍连接到 127.0.0.1:17318，并且其 manifest CSP 允许列表固定为该端点。在将 Pi 扩展或 DSH 客户端指向另一个端点之前，请使用匹配的重新构建的扩展和 CSP。
模型浏览器工作请使用原生的 browser_ Pi 或 DSH 工具。它们会保留当前 Agent 会话、目标身份以及标签页所有权保护。用户标签页仍是有效的浏览器目标，但在用户或 DSH UI 处于活动状态时，其文档可能被替换；只读页面读取会重新观察一次正在变化的文档，而产生副作用的操作则保留严格的文档防护。自动化浏览器验证应使用 Agent 拥有的测试标签页或隔离的浏览器配置文件，而不是活动的 DSH GUI 标签页。

开发与测试

cd /pi-control-chrome
npm install
npm run check
npm test
npm run test:pi:lifecycle
npm run test:skill
npm run pack:check
npm run test:package-install

npm run test:skill 需要已连接的 Chrome 或 Edge 配置文件以及本地 Bridge。它会创建临时 Agent 标签页，因此当存在多个就绪目标时，它会跳过而不是选择其中一个；仅对明确授权的目标设置 PI_CONTROL_CHROME_TEST_BROWSER_ID。高覆盖率的浏览器冒烟测试是：

npm run smoke:e2e

多目标验收测试会启动所配置浏览器（默认为 Edge，或在选中时使用 Chrome for Testing）的两个隔离临时配置文件，并验证显式路由、目标断开隔离以及同一配置文件重连防护：

npm run smoke:e2e:multi-profile

冒烟测试默认使用 Edge。当前工作树已在 Edge 和 Chrome for Testing 149.0.7827.55 上通过了相同的隔离覆盖。使用以下命令针对 Chrome for Testing 运行：

$env:PI_CONTROL_CHROME_BROWSER = "\chrome-for-testing\chrome.exe"
npm run smoke:e2e

这会请求一个唯一的临时 --user-data-dir，而不是普通用户配置文件。如果浏览器进程在扩展握手之前退出，测试框架会失败，这可以检测常见的 Windows 单例委托；Chrome for Testing 提供了最可靠的隔离可执行文件。已安装的 Google Chrome 可能会拒绝命令行未打包扩展标志；对于普通配置文件检查，请从 chrome://extensions 手动加载 extension/。

设计原则

1. 一次安装，低摩擦运行。 扩展安装和本地配对是面向用户的信任步骤。
2. 扩展是浏览器能力的边界。 Pi 仅通过本地 Bridge 与其通信。
3. 默认保留用户标签页。 认领标签页会建立控制所有权；它不会将标签页移入 Agent 组。
4. Agent 标签页可回收。 Agent 创建的标签页带有所有权和会话元数据，并根据生命周期策略进行清理。
5. Chrome 和 Edge 共享同一实现。 该扩展使用 Manifest V3 和能力检测。
6. 在不复制私有 Codex 运行时代码的情况下对齐可观察行为。 Pi 使用自己的 Bridge 协议和 Extension API。
7. 能力层，而非站点适配器。 插件理解页面结构、身份、安全边界和通用原语；产品的 DOM、工作流和字段名属于调用方 Skill。参见能力层与个性化层。

文档

- ARCHITECTURE.md — 英文架构文档。
- README-zh-CN.md — 简体中文指南。
- FEATURES.md — 功能范围与未来工作。
- CODEX-ALIGNMENT.zh-CN.md — Codex 行为对齐说明。
- DECISIONS.zh-CN.md — 项目决策。
- docs/RELEASE-CHECKLIST.zh-CN.md — 包/版本、依赖、PR、npm 发布及活跃 DSH Profile 发布检查清单。
- skills/pi-control-chrome-release/SKILL.md — Pi 和 DSH 包的可执行发布流程。
- skills/pi-control-chrome/SKILL.md — 内置 Pi Skill。
- CHANGELOG.md — 发布历史。
- BROWSER-ACTIVATION-DESIGN.zh-CN.md — 浏览器能力激活与按需 Skill 设计。
- docs/BROWSER-LIFECYCLE-CODEX-ALIGNED.zh-CN.md — 已实现的 Codex 对齐浏览器生命周期。
- docs/BROWSER-OUTPUT-COMPACTION-DESIGN.zh-CN.md — 已实现的有界模型面向浏览器输出与 AX 修订设计。
- docs/AGENT-BROWSER-RUNTIME-DESIGN.zh-CN.md — Agent 优先的实时引用运行时设计、实现状态及 AX 运行时状态。

当前未来范围

以下条目计划在后续阶段实现，不阻塞当前浏览器控制循环：

- WebMCP、GSuite 导出及浏览历史 API。
- 专用媒体下载接口。
- 超出当前 Bridge 目标与扩展能力握手的的能力发现。
- Chrome Web Store 和 Edge 加载项发布包。
- 专用的 Brave 和 Chromium 验收覆盖。
- 跨 Bridge 编排及单会话内同时多目标控制。

许可证

MIT。参见 LICENSE。