# OmniBrowse-Agent

OmniBrowse-Agent 是一个以证据为核心的浏览器研究 Agent：接收研究问题后，使用真实浏览器（Playwright）在公开网页上导航、点击、滚动、输入和采集，优先通过 DOM、ARIA、表格及网络响应提取事实，必要时再调用视觉模型兜底，最后生成带来源、采集时间、置信度和证据引用的 Markdown 报告。成本、步数和视觉调用受预算闸门控制；登录、验证码及敏感操作转人工处理，不绕过站点安全机制。

> 当前定位：可演示、可测试、可扩展的单机工程原型。未实现能力会在 [Roadmap](#roadmap) 中明确标注。

## 演示

启动本地 Web Demo 后，在浏览器中输入研究问题即可看到实时浏览画面、Set-of-Marks（SoM）标记、动作轨迹、事实与证据，以及最终报告。

![Web Demo：任务结果与 AI 分析](docs/screenshots/web-demo1.png)

![Web Demo：实时浏览、动作轨迹、事实证据与最终报告](docs/screenshots/web-demo2.png)

演示流程支持两种入口：问题中包含 `http(s)://` 绝对网址时直接导航；未包含网址时从默认百度搜索页开始。遇到登录或验证码页面，任务会暂停，用户在可见浏览器中完成处理后点击恢复，系统会重新检查页面状态。

## 已实现特性

- **Web 演示**：`python run_web.py` 启动本地界面，默认监听 `http://127.0.0.1:8766/`；展示浏览帧、事件流、AI 分析、事实证据、成本和报告。
- **受控浏览器**：Playwright Chromium、独立 BrowserContext、标签页管理、SoM 元素定位、`page_version` 防止使用过期元素映射。
- **浏览动作**：导航、点击、输入、滚动、后退和选择；敏感或状态变更动作需要人工确认。
- **确定性提取**：文本、标题、链接、ARIA、表格、JSON-LD、SVG 文本、网络响应和 ECharts 数据。
- **长页与晚渲染处理**：模型侧页面文本上限 24,000 字符；对可滚动长页按需滚动采集；交互元素不足时进行有界等待；无效果动作和无进展指纹用于终止空转。
- **模型路由**：普通文本决策使用配置的 `cheap_text` 模型（默认 GLM，支持本地 Ollama 兜底）；视觉只在需要时使用，支持 GLM 视觉接口或本地 `qwen2.5-vl`。
- **证据化结果**：SQLite 保存任务、步骤、事实、证据、模型调用、预算事件和报告；报告包含来源 URL、页面版本、提取方法、置信度和证据片段。
- **预算控制**：使用整数 `microcny` 账本（1 CNY = 1,000,000 microcny），可限制成本、Token、步数、页面数、时长、视觉调用和强推理调用。
- **CLI 与 Browser MCP**：提供 `omnibrowse run/resume` 任务命令，以及 stdio 传输的 `omnibrowse-browser-mcp` 服务。
- **安全边界**：仅允许 HTTP(S)，出口代理在 DNS/IP 层阻止回环、私网、链路本地和云元数据地址；网页内容作为不可信数据，不能修改安全策略或预算。
- **测试与 CI**：pytest 分层测试（unit / contract / integration / e2e）与 GitHub Actions 的 Python 3.11/3.12 检查。

## 快速开始

### Web Demo（推荐）

```powershell
py -3.11 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m playwright install chromium
Copy-Item .env.example .env
python run_web.py
```

然后打开 <http://127.0.0.1:8766/>。如需填写 GLM API Key，请只写入本地、不会提交到 Git 的 `.env` 文件；未配置外部模型时仍可运行本地流程，但 AI 分析能力会受配置影响。

也可以使用已安装的入口：

```powershell
omnibrowse-web --port 8765
```

### CLI

`TaskSpec` 使用 JSON 文件描述目标网页、提取方法和事实规则：

```powershell
omnibrowse run --task-spec task.json
omnibrowse resume --task-id <task_id>
```

命令输出结构化 JSON，报告和制品路径由配置中的数据库与 artifacts 目录决定。

### Browser MCP（stdio）

```powershell
omnibrowse-browser-mcp
```

服务按需启动 Chromium。工具层会校验 URL、会话、标签页、`page_version`、动作类型和提取模式。

## 配置

复制 `.env.example` 为 `.env` 后按需修改。配置按用途分为以下前缀：

| 前缀 | 用途 |
| --- | --- |
| `APP_*` | 运行环境、日志、SQLite 数据库和 artifacts 路径 |
| `BROWSER_*` | headless、视口和浏览器超时 |
| `MODEL_*` / `BIGMODEL_API_KEY` / `GLM_*` | 文本、视觉模型及其端点 |
| `BUDGET_*` | 成本、Token、步数、页面、时长和视觉调用上限 |
| `RETENTION_*` | 制品保留时间与清理周期 |

密钥、Cookie、Token 和真实账号数据不得提交到仓库。

## 架构

```mermaid
flowchart TD
    U[用户研究问题] --> W[Web Demo / CLI]
    W --> G[有界工作流]
    G --> B[Browser Gateway]
    B --> M[Browser MCP]
    M --> P[Playwright Chromium]
    B --> X[确定性提取器]
    X --> F[SQLite 事实与证据账本]
    X --> Q{确定性证据足够?}
    Q -->|否且预算允许| V[视觉模型兜底]
    V --> F
    Q -->|是| R[报告渲染器]
    F --> R
    R --> O[Markdown 报告]
```

- `src/omnibrowse_agent/web/`：本地 Web Demo、任务状态、事件、人工恢复和展示接口。
- `src/omnibrowse_agent/graph/`：任务状态流转、浏览/提取/验证/写作和预算终止。
- `src/omnibrowse_agent/browser_gateway/`：对 Browser MCP 的结构化网关与 stdio 客户端。
- `src/omnibrowse_agent/models/`：文本动作决策、答案合成和视觉模型适配器。
- `src/omnibrowse_agent/extraction/`：声明式、确定性事实提取。
- `src/omnibrowse_agent/storage/`：SQLite 迁移、任务/事实/证据/报告持久化和制品登记。
- `browser_vision_mcp/`：Playwright、SoM、提取、artifact 和受控网络出口实现。

## 项目结构

```text
OmniBrowse-Agent/
├── src/omnibrowse_agent/   # 应用、编排、模型、存储与报告
├── browser_vision_mcp/     # Browser MCP 服务及浏览器安全策略
├── tests/                  # unit / contract / integration / e2e
├── docs/                   # 设计书、ADR、术语表与演示截图
├── .env.example            # 配置模板
└── run_web.py              # 8766 端口 Web Demo 启动脚本
```

## 测试与开发

```powershell
ruff check .
pytest
```

GitHub Actions 会在 Python 3.11 和 3.12 上安装开发依赖并执行 Ruff 与 pytest。更完整的架构、契约和安全说明见 [项目设计书](docs/PROJECT_DESIGN.md)、[交接文档](docs/README_HANDOFF.md) 和 [AGENTS.md](AGENTS.md)。

## 安全与成本原则

- 仅访问用户授权范围内的公开 HTTP(S) 页面；不访问 `file://`、内网或云元数据地址。
- CAPTCHA、登录、双因素认证、上传、提交、支付、删除、发布及其他敏感操作必须人工处理或确认。
- 网页中的文字和指令是不可信数据，不能覆盖系统目标、预算、安全策略或工具权限。
- DOM、ARIA、表格和网络数据优先于模型；视觉模型只作为局部兜底，且受调用次数和成本上限约束。
- 无法确认的事实保留为 `unknown`，不通过猜测补全数值。

## Roadmap（规划中 / 未实现）

以下项目属于后续规划，不应视为当前版本承诺：

- 多租户 SaaS、分布式浏览器集群和高可用会话池。
- PDF、下载文件和大体积附件的完整解析流水线。
- 以向量数据库作为补充的跨页面语义检索（SQLite 仍是事实真源）。
- 更完整的图表适配器、评测平台和成本回归基准。
- OpenTelemetry/Langfuse 等增强型可观测性与远程部署。

## License

本项目以 [MIT License](LICENSE) 发布。