# 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

```bash
# 装
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](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](SECURITY.md)。

## Star History

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

## References

- 📖 [CLAUDE.md](CLAUDE.md) — 架构 + 当前状态
- 📋 [docs/chatgpt-handoff.md](docs/chatgpt-handoff.md) — ChatGPT 设计对话
- 📋 [docs/deep-research-report (2).md](docs/deep-research-report%20(2).md) — 战略重塑调研
- 📋 [docs/issues/backlog.md](docs/issues/backlog.md) — 10 个 starter issues
- 📋 [docs/integrations/claude-code-mcp.md](docs/integrations/claude-code-mcp.md) — Claude Code 5 分钟接入
- 📋 [docs/strategic/x-twitter-integration.md](docs/strategic/x-twitter-integration.md) — X 集成分析
- [browser-use](https://github.com/browser-use/browser-use) — fork 选型
- [Playwright](https://playwright.dev) — 浏览器底层
- [Model Context Protocol](https://modelcontextprotocol.io/) — Anthropic MCP spec
- [OpenAI Operator](https://openai.com/index/introducing-operator/) — takeover/watch mode 参考
- [Anthropic Computer Use](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/computer-use-tool) — sandbox 参考

## License

**Apache-2.0** — 见 [LICENSE](LICENSE)。stealth 插件在独立仓库。