UBA — Universal Browser Brain

The open-source Browser Brain for AI agents — API-first execution, real browser identity, local-first secrets.

中文:UBA 是一个面向 Claude、GPT 与任意 Agent 的开源 Browser Brain 运行时。它让模型拥有人类级网页感知、语义理解、长期浏览记忆、真实浏览器身份。

Why UBA (v0.2 重塑 2026-07-19)

最强烈差异化(从调研报告 7 得出):

• ❌ 不是 "另一个 browser-use fork"
• ❌ 不是 "反检测浏览器"(stealth 降级为独立插件)
• ❌ 不是 "AI 浏览器产品"(不做完整 UX)
• ✅ 是 "Browser Brain Runtime" —— 跨层聚合 6 个能力层,只做基础设施层,不做应用层

核心承诺:

• API 优先 —— GitHub/X 写动作走官方 API(OAuth Device Flow,短期 token)
• 真实身份浏览器 —— 用户自己 Chrome + CDP attach,不是 stealth 伪造
• 本地优先 —— 凭据存系统 keychain,token 不出机
• MCP 优先 —— Claude / Cursor / Continue 任何 MCP 客户端可直接调
• Apache-2.0 —— 企业友好 + 专利授权清晰

What UBA Is

✅ 面向 LLM 的 Browser Brain Runtime(开源) ✅ 把页面变成 page.json(统一观测对象) ✅ 三层记忆(Factual / Episodic / Semantic) ✅ Reflection(动作后自动 diff + failure cause) ✅ Approval Policy(高风险动作人类接管) ✅ Secret Vault(系统 keychain 存凭据) ✅ Local-first by default, cloud only by consent ✅ Apache-2.0 license

What UBA Is Not

❌ 反检测浏览器(stay stealth 主题不在主叙事,降到独立插件) ❌ 完整 AI 浏览器产品(Comet / Dia 那种) ❌ 另一个 browser-use fork(差异化在 Memory + Reflection + Secret Vault) ❌ SaaS(本地为主)

Core Concepts: 6 层架构 + 双执行面

Claude Agent
     |
   MCP / CLI / SDK
     |
UBA Orchestrator
┌─────────────────────────────────┐
│ 1. Browser Core                  │  ← Provider 抽象
│ 2. Perception                    │  ← a11y + screenshot + DOM
│ 3. Brain Engine    → page.json   │  ← 语义化 + risk
│ 4. Planning + Approval           │  ← 候选 + 审批
│ 5. Reflection                    │  ← diff + retry
│ 6. Memory OS                     │  ← 3 张表 + Secret Vault
└─────────────────────────────────┘
     |
┌────────────────┐  ┌────────────────┐
│ API Executor   │  │ Browser Exec   │
│ (GitHub/X)     │  │ (CDP/extension)│
└────────────────┘  └────────────────┘

每层都有官方文档。

Quick Start

# 装
git clone https://github.com/kezhu-ai/uba.git
cd uba
uv sync

# 启动 MCP server(stdio 模式)
uv run uba-server

# Claude Code 配置 ~/.claude/mcp.json:
# {
#   "mcpServers": {
#     "uba": {
#       "command": "uv",
#       "args": ["--directory", "PATH/TO/uba", "run", "uba-server"]
#     }
#   }
# }

然后在 Claude Code 里说:

"用 uba 打开知乎,看看 AI Agent 热榜前 10"

Demo

(待录屏:同一任务"普通 browser automation vs UBA"对比,展示 page.json + 第二次访问时记忆被调出)

Architecture

(完整 mermaid 架构图:6 层 + 双执行面,API 优先 + 浏览器兜底)

page.json Schema

(uba/core/page.py 的 Pydantic 模型,字段包括: session_id / url / site / page_type / auth_state / user_goal / summary / entities[] / primary_actions[] / risk_flags[] / memory_hooks{} / evidence{})

v0.2 计划扩展:regions / selector_candidates / recent_actions / site_facts(报告 7 Page Understanding Graph)

Memory Schema

三层:

• SQLite: sessions / page_observations / action_logs / reflections / preferences / site_playbooks
• Secret Vault:~/.uba/secrets.vault.json(Fernet 加密)或系统 keychain
• LanceDB(v0.3):embeddings 多模态语义检索

CLI and MCP

15 个核心 MCP 工具:

• browse_navigate / browse_snapshot / browse_click(ref=eN) / browse_type(ref=eN, text)
• browse_screenshot / browse_extract / browse_sessions / browse_solve_captcha
• uba_observe / uba_plan / uba_act / uba_reflect / uba_recall / uba_run(高阶闭环)
• uba_twitter_search / uba_twitter_user_timeline(X Free API 只读)

Providers(可插拔)

Provider	用途	默认
本地 Chrome CDP attach	真实身份(报告 7 推荐)	v0.3 默认
Patchright	自动化底层(API 兼容 Playwright)	v0.2 默认
CloakBrowser	选配,stealth 增强	v0.3 降级为独立插件
Camoufox	Firefox 路径反检测	v0.3 选配
远程 Browser(Browserless / Kernel)	CI/企业部署	选配

Safety and Privacy

• Local-first by default, cloud only by consent
• 浏览器 profile 只读快照(不直接写用户原始 profile)
• 敏感字段(凭证/cookie/密码)绝不入 memory retrieval
• Approval Policy:高风险动作(支付/登录/发信/表单提交)默认 require approval
• 域名 allowlist(默认拒绝银行/政府/医疗)
• 一键删除站点记忆:uba forget --site zhihu.com

参考 OpenAI Operator 的 takeover / Anthropic 的 sandbox 实践。

Local-First Design

默认所有数据本地:

• ~/.uba/memory.db — SQLite
• ~/.uba/secrets.vault — 系统 keychain(WIN/macOS/Linux)+ Fernet 兜底
• ~/.uba/profiles/<session>/ — 浏览器 profile(只读快照)

不上传 telemetry / crash report。

Roadmap

版本	重点	状态
v0.1	6 层架构骨架 + 15 MCP 工具 + page.json v0.1	✅ 2026-07-19 release
v0.2	Secret Vault + GitHub App Device Flow + X Free API + 战略重塑	✅ 2026-07-19
v0.3	CDP attach(真实身份)+ LanceDB semantic + Page Understanding Graph	🔜 计划
v0.4	browse_with_goal LLM 决策循环 + Site Playbook 自动学习	🔜
v1.0	10k star + 1+ enterprise user + public benchmark	🔜

Benchmarks and Evals

(待 v0.3 公开 20-50 任务基准,衡量:

• action success rate
• token cost per task
• memory recall precision/recall
• recovery rate from failure
• v0.2 已有 60 个单元测试,覆盖核心)

Contributing

三层入口:

1. Provider / Plugin — 加新浏览器后端、新 LLM 适配
2. Site Playbook — 贡献某站点的结构经验(知乎怎么登录、淘宝怎么下单)
3. Memory / Eval — 基准、召回、反思逻辑

详见 CONTRIBUTING.md。

Governance

• 维护者:@uba-agent-core
• RFC 流程:大改动走 rfcs/
• License:Apache-2.0(核心)+ 独立 stealth 插件仓库(规避 license 风险)
• 中文社区 + 英文社区双语

Security Policy

报告 7 强约束:

• GitHub 走 App + Device Flow(不是 PAT 网页自动化)
• X 走 OAuth 2.0 PKCE(短期 token)
• 凭据走系统 keychain(不存明文)
• 2FA / 验证码默认 human-in-the-loop(不绕过)
• 审批 + 审计 + 速率限制(防止滥用)

详见 SECURITY.md。

Star History

(开始攒,目标是 v1.0 前 10k stars)

References

• 📖 CLAUDE.md — 架构 + 当前状态
• 📋 docs/chatgpt-handoff.md — ChatGPT 设计对话
• 📋 docs/deep-research-report (2).md — 战略重塑调研
• 📋 docs/issues/backlog.md — 10 个 starter issues
• 📋 docs/integrations/claude-code-mcp.md — Claude Code 5 分钟接入
• 📋 docs/strategic/x-twitter-integration.md — X 集成分析
• browser-use — fork 选型
• Playwright — 浏览器底层
• Model Context Protocol — Anthropic MCP spec
• OpenAI Operator — takeover/watch mode 参考
• Anthropic Computer Use — sandbox 参考

License

Apache-2.0 — 见 LICENSE。stealth 插件在独立仓库。