人工智能AI AgentAI 应用前端后端即时通讯交互助手工具调用【免费下载链接】holaOSOpen-source agentic workspace enterprises can make their own. Connect the systems you already run — 100 integrations, MCP, chat tools, apps, browser, local files — with shared memory. Any agent (Claude Code, Codex), any model, or BYOK. Set up in clicks, not months. Local-first: your data never leaves your machines.项目地址https://gitcode.com/GitHub_Trending/ho/holaOS点击查看免费下载导读本文以 holaOS仓库GitHub_Trending/ho/holaOS中的架构规划文档《Native Chrome CDP Agent Control Plan》为骨架完整讲解其核心目标与设计让 Agent 通过 Chrome DevTools ProtocolCDP控制本地真实安装的 Chrome 浏览器同时保持现有browser_*工具面不变。文章会结合仓库中的工具定义、运行时能力路由、Electron 主进程与 CDP 驱动模块、工作区隔离 e2e 测试等真实源码说明从Electron 内嵌浏览器切换到托管真实 Chrome的抽象层设计、工具映射、配置变更、打包调整、测试要求与分阶段推进路径让读者既能照规划落地也能在源码中找到对应实现依据。一、规划背景为什么要给 Agent 真实 Chrome 控制能力1.1 目标与现状差距规划文档开篇明确了目标让 Agent 控制本地真实安装的 Chrome 浏览器通过 CDP 协议驱动同时尽可能保留现有的browser_*工具契约。在此之前holaOS 桌面端的浏览器能力由三层组成Harness 工具定义runtime/harnesses/src/desktop-browser-tools.ts定义了 Agent 可见的browser_*工具集合Runtime 能力代理路由runtime/api-server/src/app.ts以 HTTP 路由暴露浏览器能力桌面端实现apps/desktop/electron/main.ts真正执行浏览器操作的 Electron 侧。规划明确指出当时的桌面层并没有控制原生 Chrome而是控制 ElectronBrowserView并通过本地浏览器服务暴露出来。由此推导出三点结论Agent 已有稳定的工具契约、Runtime 已有稳定的能力 API、主要缺口在 Electron 侧的 executor/backend。这决定了后续所有工作的边界不动契约、不动 API只换执行后端。1.2 当前实现为何不是薄浏览器抽象文档点出关键问题现有浏览器服务与 Electron 原语强耦合——页面读取来自 ElectronwebContents求值使用executeJavaScript截图使用capturePage标签页是 ElectronBrowserView实例Browser 面板 UI 按原生内嵌视图的尺寸与挂载方式设计因此它是一个 Electron 内嵌浏览器实现而非跨引擎的薄抽象层。要支持原生 Chrome via CDP必须新增一个桌面后端在保留既有浏览器服务契约的前提下替换执行层。二、现有浏览器能力的真实结构源码佐证2.1 Agent 工具面不止 12 个规划文档列举了 12 个核心工具而从源码看工具面已经远超这个范围。runtime/harnesses/src/desktop-browser-tools.ts中的DESKTOP_BROWSER_TOOL_IDS完整定义了 30 个工具 idbrowser_navigate、browser_open_tab、browser_select_tab、browser_close_tab、browser_get_state、browser_find、browser_act、browser_wait、browser_evaluate、browser_debug、browser_click、browser_context_click、browser_type、browser_press、browser_scroll、browser_back、browser_forward、browser_reload、browser_screenshot、browser_list_tabs、browser_list_downloads、browser_get_console、browser_get_errors、browser_list_requests、browser_get_request、browser_storage_get、browser_storage_set、browser_cookies_get、browser_cookies_set。每个工具都带完整的input_schema与语义说明例如browser_get_state支持modestate|text|structured|visual、detailcompact|standard、scopemain|viewport|focused|dialog|active_dialog|modal、max_nodes、since_revision与changed_only增量快照browser_act支持click|double_click|hover|focus|fill|type|press|select|check|uncheck|scroll_into_view并内置wait_for/post_state稳定机制browser_scroll支持direction/amount/delta_y组合。这说明工具契约覆盖了导航、标签管理、DOM 读取、交互、调试、下载、控制台、网络、存储与 Cookie 全链路是规划中保留工具契约不动的坚实基础。2.2 Runtime 能力路由runtime/api-server/src/app.ts中浏览器能力以三条路由暴露GET /api/v1/capabilities/browser能力状态查询可用性、URL、状态GET /api/v1/capabilities/browser/profiles浏览器 Profile 列表POST /api/v1/capabilities/browser/profiles/launch/.../close启动与关闭 ProfilePOST /api/v1/capabilities/browser/tools/:toolId按工具 id 分发执行运行时配置在runtime/api-server/src/runtime-config.ts中维护一组desktopBrowser*字段enabled、url、auth_token、allowed_domains、blocked_actions、confirm_actions、untrusted_boundaries。这与规划中runtime 只跟踪单条 desktop browser 能力 URL/token 对的描述一致也预告了后续要为原生 Chrome 后端扩展配置。2.3 桌面端实现BrowserView 会话分区桌面端当前实现集中在apps/desktop/electron/main.ts为每个工作区创建浏览器状态、用session.fromPartition(...)实现工作区隔离、创建BrowserView标签页、通过 ElectronwebContents驱动导航与交互并在本地提供认证 HTTP 服务。这就是规划中当前浏览器服务的全部面貌。三、与原生 Chrome 的差距分析3.1 差距清单能力维度Electron 内嵌实现原生 Chrome via CDP页面读取webContentsPlaywrightpage/ CDPPage域页面求值executeJavaScriptpage.evaluate/Runtime.evaluate截图capturePagepage.screenshot/Page.captureScreenshot标签页BrowserView实例CDP page/target工作区隔离session.fromPartition(...)每工作区独立user-data-dir面板 UI内嵌原生视图 bounds 同步与 Agent 后端解耦3.2 推荐范围Agent-only 托管 Chrome规划强调Phase 1 只做Agent 专用的托管 Chrome 后端保留browser_*工具契约、保留 runtime 能力路由、替换或扩展 Electron 浏览器服务后端不把原生 Chrome 作为可见 Browser 面板的第一实现。这是在不把 Browser 面板变成独立产品重设计的前提下交付真实 Chrome 控制的最小路径。四、推荐技术方案详解4.1 在 Electron 中引入浏览器后端抽象规划建议在桌面浏览器服务内部定义一个后端接口操作集包括工作区初始化、标签页创建、活动标签查询、导航、求值、截图、历史导航、标签列表、生命周期与清理。保留现有 Electron 内嵌浏览器实现同时新增针对原生 Chrome/CDP 的实现。这本质是策略模式同一服务契约两种执行后端。4.2 用 Playwright 的 CDP 连接驱动 Chrome规划推荐的技术路径从 Electron 主进程以--remote-debugging-portport启动 Chrome分配专属--user-data-dirworkspace-specific-dir通过chromium.connectOverCDP(...)连接常规流程用 Playwright page/context 对象高级场景用 CDP session 直连4.3 仓库中已经落地的同类实现profile-cdp.ts规划文档描述的目标在仓库中已有直接印证apps/desktop/electron/profile-cdp.ts正是为某个 Profile 生成的 Chromium真实 Chrome提供 CDP 驱动的模块。其头部注释写道每个 Profile 由 main.tslaunchProfileChromium以真实 Chrome 方式携带--remote-debugging-port启动本模块通过 PlaywrightconnectOverCDP连接该端口暴露底层浏览器原语——executeJavaScript、页面信息、导航、截图、输入——从而让同一套 Agent 浏览器工具作用于启动后的 Profile 窗口而不是内嵌的 Electron BrowserView经 CDP 驱动的完整对等实现。几个与规划一一对应的实现细节connect 重试逻辑冷启动 Chrome 打开调试端口可能耗时新user-data-dir首次运行可能数秒connect()以 250ms 间隔最多重试 80 次约 20 秒一旦端口可达立即返回进程存活接管adoptprofileCdpTryAdopt以 1.5s 超时单次探测端口若发现已存活的 Chrome例如应用重启后残留的 detached 进程则直接复用避免二次 spawn 的 Chrome 因--user-data-dir单例约束而只是转发--new-window后退出断连清理注册browser.on(disconnected)自动从连接表移除disconnectProfileCdp显式关闭 CDP 连接页面级 CDP sessionpageCdp用 WeakMap 按 page 缓存newCDPSession(page)在需要底层协议时如Page.getNavigationHistory计算前进/后退可用性直接session.send(...)每会话标签隔离ProfileConnection.pageBySession以 agent session id 为 key 记录各自的活动页并发 Agent 共享 Cookie 但互不抢占对方页面activePage还会把窗口刚打开的空 landing 页about:blank/新标签页认领给第一个驱动的会话避免孤儿标签堆积。这些代码既是规划用 Playwright CDP 连接、必要时下沉 CDP session的落地证明也提示了实现托管 Chrome 后端时应复用的成熟模式。4.4 工具执行映射规划给出了清晰的映射表本文整理并对照源码字段扩展现有工具原生 Chrome 后端映射说明browser_navigatepage.goto(url)profileCdpNavigate以waitUntil: domcontentloaded、30s 超时导航仅在仍停留about:blank时抛错避免子资源超时中断导航browser_open_tab新建 page 并可选置前profileCdpOpenTab绑定为会话活动页并bringToFront()browser_get_state在活动页求值 DOM 提取脚本由 api-server 注入 JS经 evaluate →page.evaluate执行browser_clickDOM 索引方式或 locator 化动作可保持现有 DOM-first 提取逻辑不变browser_type向匹配元素填充/输入对应profileCdpKeyboard的insert_text含 clear submitbrowser_press活动页键盘按键page.keyboard.press(key)browser_scroll滚动求值或滚轮输入profileCdpMouse也覆盖hover/context等真实输入browser_back/browser_forward/browser_reloadpage 导航辅助前进/后退可用性由Page.getNavigationHistory判定browser_screenshotpage 截图profileCdpScreenshot支持 png/jpeg、fullPage、qualitybrowser_list_tabs从托管 page 列表派生由context.pages()过滤isClosed()得到规划特别强调runtime/api-server/src/desktop-browser-tools.ts中现有的 DOM-first 提取逻辑可以第一阶段保持不变——Agent 的丰富元素模型get_state/find/click-by-index/scroll由 api-server 注入 JS 产生只要忠实复现evaluate整套元素模型就免费复用了这正是 profile-cdp.ts 注释中reproducing evaluate faithfully reproduces the whole element model for free的设计精髓。4.5 面板分离Agent 后端与可见面板解耦规划的判断是现有 Browser 面板围绕内嵌原生视图 bounds 同步构建原生 Chrome 不能直接替换而不重设计面板。因此第一阶段将Agent 浏览器后端与可见 Browser 面板后端分离面板继续使用 ElectronBrowserView直到有独立的 UX 决策再替换。五、工作区隔离重建5.1 从会话分区到独立 Chrome Profile当前工作区隔离依赖 Electron 会话分区session.fromPartition(...)。对原生 Chrome等价物是每个工作区一个托管 Chrome Profile即每个工作区一个专属user-data-dir。这样保证Cookie 按工作区隔离、localStorage 按工作区隔离、Service Worker 与站点数据按工作区隔离、工作区恢复行为一致。规划明确警告默认复用用户日常 Chrome Profile 是错误默认值。这也是产品原则——Agent 的浏览器活动不应污染用户真实浏览数据。5.2 源码侧的现实进展仓库当前实现的浏览器服务已围绕工作区级 profile工作证据来自apps/desktop/e2e/browser-workspace-isolation.test.mjs其测试用例断言desktop browser keeps isolated workspace profiles, restores state on switch, and persists across relaunch。测试通过x-holaboss-workspace-id头区分工作区分别向 workspace-a / workspace-b 写入 localStorage 键值再验证各自读到自己的值——这正是规划中workspace A 与 workspace B 隔离、localStorage 隔离验收点的雏形。在apps/desktop/electron/main.ts中也能看到配套实现按 profile 生成--user-data-dir真实 Chrome profile--remote-debugging-port关闭时先停掉活的 Chromium 再清理目录避免在其运行时抹掉user-data-dir还包含未知调试端口的残留 Chrome 清理逻辑用--user-data-dirdir作为识别 needle。这些为每个工作区一个托管 Chrome 实例提供了可直接沿用的基础设施。六、标签页与页面模型映射当前持久化的浏览器状态存储标签 id、URL、标题、书签、下载与历史。原生 Chrome 后端需要映射为 CDP/Playwright 概念现有概念原生 Chrome 映射工作区托管 Chrome Profile / 托管浏览器实例标签页page/target id活动标签工作区状态中的选中 page id打开标签新建 page弹窗/新窗口拦截并规整为工作区标签状态恢复逻辑应在工作区重新激活时重新打开此前持久化的标签页。仓库中 profile-cdp 的landing 页认领与按会话绑定 page机制正是这一模型的运行态实现恢复后首个会话复用空白页而非新建标签避免标签堆积。七、配置变更规划指出当前 runtime 配置只跟踪单条桌面浏览器能力 URL/token 对新后端很可能需要额外配置backend typeelectron_embedded或native_chrome_cdpChrome 可执行文件路径覆盖多平台发现失败时的兜底远程调试 host/port 设置调试端点监听地址工作区 Chrome 数据根目录user-data-dir的父目录策略启动托管 Chrome 或附加到已有实例spawn vs adopt 的开关对照runtime/api-server/src/runtime-config.ts现状现有desktopBrowser*字段尚无 backend type 维度新增字段需要同时体现在能力 payload 解析capabilitiesPayload.desktop_browser与运行时状态上报browser_stateavailable/unavailable/enabled_unconfigured两处形成闭环。八、打包变更playwright 依赖的运行时化规划的判断在apps/desktop/package.json中得到精确验证playwright位于devDependencies^1.58.2而playwright-core已在dependencies1.60.0。profile-cdp.ts 正是使用playwright-core——仅连接、不捆绑数百 MB 浏览器二进制的库——来 attach 到已 spawn 的 Chrome。若 Electron 主进程在生产环境用 Playwright 做 CDP 控制至少需要将所需客户端包移入 runtime dependency 或显式打包验证 Electron 打包路径在asar下仍可用确保打包后的桌面应用能解析所选 CDP 客户端需要的运行时文件九、测试要求9.1 单元与集成测试规划列出的测试点Chrome 可执行文件解析Chrome 进程启动与关闭端点就绪失败路径对应 profile-cdp 的 20 秒重试超时与报错工作区 Profile 隔离标签持久化与恢复服务认证与路由行为9.2 端到端测试扩展现有桌面浏览器 e2e 覆盖工作区 A 与工作区 B 隔离localStorage 隔离browser-workspace-isolation.test.mjs已覆盖该模式重启后的标签恢复Agent 工具调用路由进原生 Chrome 后端弹窗规整为标签十、Phase 1 非目标与推荐默认决策10.1 非目标不把可见 Browser 面板替换为外部 Chrome默认不附加到用户日常 Chrome Profile除非后端证明必要不重设计 Agent 工具契约在基础导航与 DOM 交互可用前不阻塞于高级 CDP-only 特性10.2 推荐默认决策默认实现方向为Holaboss 启动托管 Chrome、每个工作区一个隔离 Chrome Profile、第一阶段仅 Agent 使用、现有 Browser 面板保持不变。这以最小架构爆炸半径blast radius为 Agent 带来真实 Chrome 控制能力。十一、分阶段推进路线Phase 1引入后端抽象 → 在 feature flag 后新增托管原生 Chrome 后端 → 既有工具不变 → 支持导航、开标签、状态读取、点击、输入、按键、滚动、截图Phase 2加固恢复行为 → 改进弹窗/下载/历史处理 → 改进重连与崩溃恢复Phase 3决定面向用户的 Browser 面板是保持内嵌还是新增独立的原生 Chrome 模式十二、相关源码地图关注点文件Agent 工具定义30 个browser_*runtime/harnesses/src/desktop-browser-tools.tsRuntime 能力路由runtime/api-server/src/app.tsRuntime 配置runtime/api-server/src/runtime-config.ts桌面主进程BrowserView Chrome spawn CDP 编排apps/desktop/electron/main.tsCDP 驱动模块connectOverCDP 落地实现apps/desktop/electron/profile-cdp.tsBrowser 面板协议与内部类型apps/desktop/shared/browser-pane-protocol.ts、apps/desktop/electron/browser-pane/types.ts工作区隔离 e2eapps/desktop/e2e/browser-workspace-isolation.test.mjs依赖声明playwright-core 运行时 / playwright 开发期apps/desktop/package.json结语从规划文档到仓库现状holaOS 的原生 Chrome CDP 控制是一条边界清晰、分阶段推进的演进路径稳定的工具契约与能力 API 不变Electron 侧引入后端抽象用playwright-coreconnectOverCDP连接以--remote-debugging-port 每工作区--user-data-dir启动的托管 Chrome第一阶段仅服务 Agent、可见面板维持原状。apps/desktop/electron/profile-cdp.ts已经证明这条路线的可行性后续工作是在此基础上补齐恢复、弹窗、重连与打包细节逐步把 Agent 的浏览器体验从内嵌 Electron 视图升级为真实 Chrome 的完整兼容能力。赞分享人工智能AI AgentAI 应用前端后端即时通讯交互助手工具调用【免费下载链接】holaOSOpen-source agentic workspace enterprises can make their own. Connect the systems you already run — 100 integrations, MCP, chat tools, apps, browser, local files — with shared memory. Any agent (Claude Code, Codex), any model, or BYOK. Set up in clicks, not months. Local-first: your data never leaves your machines.项目地址https://gitcode.com/GitHub_Trending/ho/holaOS点击查看免费下载相关推荐使用Websocat实现Chrome DevTools协议(CDP)的自动化交互使用Websocat实现Chrome DevTools协议 CDP 的自动化交互 概述 Websocat是一个功能强大的WebSocket工具可以用于与各种WCLI网络Browser-Use CDP使用Chrome调试协议深度集成Browser Use CDP使用Chrome调试协议深度集成 概述 Browser Use作为现代化的浏览器自动化框架其核心能力建立在Chrome Dev人工智能AI Agent浏览器控制GUI 自动化MCP 服务【亲测免费】 Chrome DevTools 协议CDP开源项目教程Chrome DevTools 协议CDP开源项目教程 1. 项目目录结构及介绍 本教程基于 Chrome DevTools Protocol https:开发工具上一篇DataHub Quickstart 故障排查完全指南从 CLI 启动失败到 Docker 容器异常的实战处理下一篇Agent Governance Toolkit 破坏性变更迁移指南从 ACS 重定向到策略引擎契约的完整升级路径创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考