Yunti Browser Runtime

让 AI Agent 稳定操作你正在使用的 Chrome / Edge。

本地优先 · MCP 原生 · Content Script + CDP 双通道 · 无远程账号依赖

快速开始 · 核心能力 · 工作原理 · 交给-agent-安装 · 文档

Yunti Browser Runtime 是一个面向 MCP Agent 的本地浏览器运行时。它把 Agent、 本地 Bridge 和浏览器扩展连接起来，让 Codex、Claude Code、Cursor、Cline 等工具 能够观察和操作用户真实浏览器中的页面。

English: A local-first MCP browser runtime that lets AI agents inspect and operate the user's existing Chromium browser through a local bridge and extension, with no hosted account or remote browser required.

为什么是 Yunti

很多浏览器自动化方案需要启动一套独立浏览器、上传会话到云端，或要求 Agent 自己 处理易失效的页面选择器。Yunti 选择另一条路径：让 Agent 安全接入用户已经登录、 已经打开的本地浏览器，同时把页面恢复和执行诊断做成运行时能力。

| 关注点 | Yunti 的选择 | | --- | --- | | 浏览器 | 操作用户本机 Chrome / Edge 和已有登录状态 | | 接入协议 | 标准 MCP，和具体 Agent 平台解耦 | | 操作后端 | Content Script 与 Chrome DevTools Protocol 都是一等能力 | | 页面定位 | observe → fresh uid → action → verify，并保留 selector / coordinate / CDP 回退 | | 会话稳定性 | 每个浏览器实例一条 controller 通道，旧 session、睡眠标签和 MV3 恢复由 runtime 处理 | | 数据边界 | Bridge 默认只监听 127.0.0.1，无远程服务、无平台账号、默认无 token | | Agent 行为 | 结构化错误、共享重试预算、写操作不确定性与恢复建议 |

0.2.6 可靠性基线

0.2.6 用 38 个确定性复杂场景和真实 Edge 15 分钟耐久测试验证动态页面能力。 benchmark 通过 38/38 场景、114 次尝试和 397 次 MCP 调用；Edge 连续运行 900.168 秒，完成 840 个业务循环和 22,410/22,410 次成功工具调用，覆盖 全部 52/52 个 MCP 工具，重复写入为 0，调用 p95 / max 为 213 / 956 ms。

查看耐久测试设计与完整验收标准

快速开始

1. 安装 Runtime

要求 Node.js 22 或更高版本：

npm install -g yunti-browser-runtime

本地默认不需要 npm token，也不需要 Yunti 账号。

2. 接入你的 Agent

让 CLI 针对 Agent 生成 MCP 配置和 skill 安装指引：

yunti-browser-runtime print-config -- --agent codex --human

支持的 --agent 示例：codex、claude-code、cursor、cline。把输出的 MCP 配置加入 Agent 后，新建或重载 Agent 会话。Agent 启动 MCP server 时会自动启动 本地 Bridge，通常不需要另开一个 bridge 进程。

3. 加载浏览器扩展

获取扩展目录：

echo "$(npm root -g)/yunti-browser-runtime/extension"

然后完成一次浏览器侧加载：

1. Chrome 打开 chrome://extensions，Edge 打开 edge://extensions。
2. 开启“开发者模式”。
3. 点击“加载已解压的扩展程序”。
4. 选择上面输出的 extension 目录。

Chrome / Edge 不允许 npm 静默安装未上架扩展，因此这一步需要用户在浏览器中确认。 加载完成后，扩展会自动连接 http://127.0.0.1:48887、维护 controller 心跳并按需 接入可访问页面。默认不需要填写 token、打开 popup、保存设置或手动刷新页面。

4. 验证连接

yunti-browser-runtime doctor

看到 runtime、Bridge、extension/controller 版本一致后，让 Agent 调用：

yunti_list_browser_targets

Agent 应能看到 Chrome / Edge 的可访问标签页，并可直接使用 tabId、targetId 或 browserSessionId 开始操作。

交给 Agent 安装

不想自己逐步配置时，把下面整段复制给 Agent：

请帮我安装并接入 Yunti Browser Runtime。它是一个本地浏览器运行时，让你通过 MCP 操作我本机 Chrome/Edge 页面。

请按步骤引导并尽可能替我执行命令，不要跳步：

1. 确认本机有 Node.js 22+。
2. 执行：npm install -g yunti-browser-runtime
3. 执行：yunti-browser-runtime print-config -- --agent 当前Agent名称 --human
4. 根据输出把 MCP server 配置加入当前 Agent；如果输出包含 skill 安装命令，替我执行。当前 Agent 不支持 SKILL.md 时，把 skill 内容加入项目或系统指令。
5. 告诉我 MCP server 会自动启动本地 Bridge，一般不需要单独运行 bridge。
6. 输出扩展目录：$(npm root -g)/yunti-browser-runtime/extension
7. 只有浏览器“加载已解压的扩展程序”这一步需要我确认：引导我打开 chrome://extensions 或 edge://extensions，开启开发者模式并选择该目录。
8. 告诉我默认 Bridge URL 是 http://127.0.0.1:48887，本地默认不需要 token，不需要打开 popup、保存设置或刷新页面。
9. 执行：yunti-browser-runtime doctor
10. doctor 正常后调用 yunti_list_browser_targets；选择目标页面并调用 yunti_get_page_snapshot 或 yunti_observe_page 验证控制能力。

不要遗漏 packaged skill 的安装或接入。不要默认要求我刷新页面、切换标签、重启浏览器或填写 token。页面路由异常时先使用 controller、tabId/targetId 和结构化 recoveryAction 自动恢复；只有浏览器明确阻止注入且自动恢复失败时，才请求我处理。

核心能力

观察与定位

• 获取全部浏览器实例、标签页和 targets。
• 读取轻量页面上下文、完整元素快照和可交互 DOM 观察结果。
• 为每次观察生成独立作用域的 fresh uid，重渲染后旧 uid 不会误命中新元素。
• 支持开放 Shadow DOM、同源 iframe、滚动容器、深层等待和增量观察。
• 对网络、控制台、DOM 和学习记忆中的敏感信息进行脱敏。

页面操作

• 点击、悬停、输入、批量填表、选择、按键、滚动、拖拽和上传文件。
• 统一 actionability 与 bounded auto-wait，检查元素是否出现、可见、可编辑和可接收事件。
• 支持标签页新建、关闭、切换、导航、窗口尺寸和设备仿真。
• 使用 observe / snapshot / screenshot / evaluate / network / console 验证执行结果。

CDP 与诊断

• 直接发送 Chrome DevTools Protocol 命令。
• 覆盖跨域 iframe、Canvas、精确输入、浏览器 targets、仿真和追踪等场景。
• 捕获脱敏网络请求、控制台消息、CDP events 和性能 trace。
• Content Script 和 CDP 可按页面能力自由组合，不人为弱化 CDP。

稳定恢复

• 每个浏览器或 profile 维护独立 controller，Chrome、Edge 和多 profile 可以同时在线。
• 页面 session 是 live tab 元数据，不为每个页面创建独立长轮询。
• 旧 browserSessionId 可通过 tabId / targetId 自动恢复。
• Edge 睡眠标签页使用有界 probe / injection；必要时短暂激活后恢复原活动标签。
• 协议或版本不匹配立即失败，retryBudget=0，避免 Agent 陷入无效循环。
• 写操作超时会标记 resultUncertain，要求先验证页面状态再决定是否重放。

工作原理

flowchart LR
    A["MCP Agent<br/>Codex · Claude Code · Cursor · Cline"]
    M["Yunti MCP Server<br/>52 browser tools"]
    B["Local Bridge<br/>127.0.0.1:48887"]
    C["Browser Controller<br/>one channel per browser/profile"]
    P["Chrome / Edge Tabs<br/>existing login and page state"]
    D["Content Script + CDP<br/>observe · act · diagnose · recover"]

    A <-->|stdio MCP| M
    M <-->|local HTTP| B
    B <-->|controller heartbeat and tool queue| C
    C --> P
    P <--> D
    D --> C

所有组件都运行在本机。MCP server 负责工具契约，Bridge 负责路由与诊断，扩展中的 controller 负责浏览器实例级通信，具体页面由 Content Script 或 CDP 执行动作。

Agent 推荐工作流

get_tool_usage_hints
        ↓
list_browser_targets → 选择目标浏览器与页面
        ↓
observe_page → 获取 fresh uid 与页面状态
        ↓
click / fill / select / scroll / CDP
        ↓
observe / wait / screenshot / network / console → 验证结果

失败时读取 code、retryable、retryBudget、recoveryAction 和 resultUncertain。整个恢复链共享一个预算，不重复使用已失效的 session，也不在 写操作结果不确定时盲目重放。

工具概览

| 类别 | 代表工具 | | --- | --- | | Targets | yunti_list_browser_targets, yunti_get_browser_target, yunti_select_page | | Observe | yunti_observe_page, yunti_find_elements, yunti_get_page_snapshot, yunti_take_snapshot | | Actions | yunti_click, yunti_fill, yunti_fill_form, yunti_select, yunti_scroll, yunti_drag | | Lifecycle | yunti_new_page, yunti_close_page, yunti_navigate_page, yunti_wait_for | | Diagnostics | yunti_take_screenshot, yunti_list_network_requests, yunti_list_console_messages | | CDP | yunti_cdp_send_command, yunti_cdp_detach, yunti_get_cdp_events | | Memory | yunti_remember_learning, yunti_get_learning_memory, yunti_forget_learning_memory |

查看全部工具、参数规则和最小用例

CLI

yunti-browser-runtime --help
yunti-browser-runtime doctor
yunti-browser-runtime print-config -- --agent codex --human
yunti-browser-runtime bridge
yunti-browser-runtime console
yunti-browser-runtime package-extension
yunti-browser-runtime soak-test

| 命令 | 用途 | | --- | --- | | doctor | 检查 Node、Bridge、扩展、协议和浏览器 controller | | print-config | 输出目标 Agent 的 MCP 配置与 skill 安装指引 | | bridge | 独立启动本地 Bridge，通常只用于调试 | | console | 启动 Bridge 并显示可选的脱敏本地运行状态页 | | package-extension | 生成版本化扩展 zip | | soak-test | 运行至少 15 分钟的全工具浏览器耐久测试 |

安全与隐私

• 默认 Bridge 仅绑定 127.0.0.1:48887，本地模式不要求 token。
• 只有显式绑定非 loopback 地址时才强制要求 Bridge token。
• 不返回原始 cookie、Authorization header、密码或疑似 token 字段。
• 网络日志、请求体预览、DOM 观察和学习记忆均包含脱敏策略。
• 提交、删除、购买、发布、生产数据修改或敏感文件上传等操作应由 Agent 先获得确认。
• CDP 调试横幅只是 Chrome 的运行状态提示；权限判断基于动作影响，而不是使用的后端。

查看权限、数据边界与威胁模型

可靠性演进

• 0.2.6：38/38 复杂场景 benchmark、观察作用域 uid、同源 iframe / 开放 Shadow DOM 深层等待、Shadow DOM 坐标操作，以及 Edge p95 / 最大延迟门禁。
• 0.2.5：协议与 live version 门禁、多浏览器实例隔离、跨实例 tabId 路由、统一 重试预算、新标签页 ready contract，以及 15 分钟全工具耐久测试。
• 0.2.4：Edge 睡眠标签页恢复、有界消息与注入、poll watchdog；Agent 不应默认要求用户刷新、切换标签或重启 Edge。
• 0.2.3：每个浏览器实例收敛为一条 controller transport，旧 session 和页面路由 可按 target 自动恢复，CDP 恢复为一等后端。
• 0.2.2：扩展在线状态从“必须存在页面 session”调整为浏览器级 controller 心跳。
• 0.2.0：observe-first、fresh uid、结构化恢复诊断、数据脱敏和可选本地控制台。

查看当前状态 · 查看路线图 · 查看 Page Agent / browser-use 竞品研究

开发与验证

git clone https://github.com/dingguangyi0/yunti-browser-runtime.git
cd yunti-browser-runtime
npm install
npm test
npm run release:check

真实浏览器短 E2E：

npx playwright-core install chromium
YUNTI_E2E=1 npm run test:e2e

完整 15 分钟耐久测试：

npm run test:soak

短跑只用于开发 runner，不可作为发布证据：

npm run test:soak -- --duration-seconds=180 --allow-short

npm run release:check 会检查公开文档、本地残留、版本一致性、CLI、doctor、语法、 全部单元测试、npm 包内容和扩展 zip 内容。

文档导航

| 文档 | 内容 | | --- | --- | | 安装指南 | Codex、Claude Code、Cursor、Cline 接入与故障恢复 | | 工具指南 | 工具列表、参数、路由规则和操作用例 | | Agent 工作流契约 | Agent 的默认操作、确认和恢复策略 | | 15 分钟耐久测试 | 复杂 fixture、覆盖契约、产物与通过标准 | | 安全说明 | 权限、隐私、数据脱敏和本地边界 | | 0.2.6 发布说明 | 当前版本目标、实现与验收 | | 项目状态 | 阶段总览、实测证据和后续工作 | | 路线图 | 后续版本与能力规划 | | 发布手册 | npm 发布、扩展打包与发布后验证 |

FAQ

扩展先注册浏览器级 controller，并通过 tab inventory 发现可访问页面。页面操作到来时， runtime 会使用 tabId / targetId 建立或恢复具体页面路由。普通 http / https 页面 不需要用户逐页刷新；浏览器内置页、扩展页和策略禁止注入的页面不在可操作范围内。

Bridge 默认只监听 127.0.0.1。共享机器加固或自定义网络部署可以设置 YUNTI_BROWSER_BRIDGE_TOKEN；绑定非 loopback 地址时 token 为必需项。

DOM 页面适合 fresh uid 与语义动作；跨域 frame、Canvas、浏览器 target、精确输入、 仿真和性能追踪更适合 CDP。两种后端互补，Agent 应选择成功率和可验证性更高的路径。

先读取结构化恢复字段，丢弃旧 ID，然后最多列出一次 targets，并通过目标页的 tabId 或 targetId 进行一次有预算的恢复。页面超时不代表 controller 或整个浏览器离线。

参与项目

欢迎提交 Issue、可复现 fixture、浏览器兼容性证据和 Pull Request。涉及新工具或行为 修改时，请同时补充工具契约、测试、Agent 指引，并确保 15 分钟 soak coverage 不会 遗漏新增公开工具。

• 报告问题
• 项目初衷
• 执行计划

License

MIT