HybridBrowser

一个面向 AI Agent 的浏览器能力层，支持真实浏览器操作，采用 CLI + MCP 双入口。

• GitHub：https://github.com/sunshanpeng/hybrid-browser
• npm：https://www.npmjs.com/package/@sunshanpeng/hybrid-browser

当前状态（2026-03-01）

• 版本：0.1.2
• 阶段：Phase 1 完成 + CLI MVP 第一版完成
• 构建：npm run build ✅

30 秒上手（推荐，免源码）

方式 A：直接 npx（零安装）

# 查看帮助
npx -y --package @sunshanpeng/hybrid-browser hybridbrowser --help

# 初始化会话
npx -y --package @sunshanpeng/hybrid-browser hybridbrowser session init --session demo --mode state --json

# 导航
npx -y --package @sunshanpeng/hybrid-browser hybridbrowser nav https://example.com --session demo --headless --json

方式 B：全局安装

npm i -g @sunshanpeng/hybrid-browser

hybridbrowser --help
hybridbrowser session init --session demo --mode state --json

MCP 接入（Codex / Claude Code 等）

HybridBrowser 的 MCP 入口是 stdio。

推荐命令（基于 npm 包）

npx -y --package @sunshanpeng/hybrid-browser hybridbrowser-mcp

在 MCP 客户端配置中可写为：

{
  "mcpServers": {
    "hybridbrowser": {
      "command": "npx",
      "args": ["-y", "--package", "@sunshanpeng/hybrid-browser", "hybridbrowser-mcp"]
    }
  }
}

本地源码方式（开发者）

npm install
npm run build
npm run mcp:stdio
# 等价于：node dist/index.js

接入后可调用工具：

• browser_navigate
• browser_snapshot
• browser_click
• browser_type
• browser_scroll
• browser_wait_for
• browser_get_content

建议最小验证流程：

1. browser_navigate("https://example.com")
2. browser_snapshot()
3. browser_get_content("text")

已实现能力

MCP（stdio）

• browser_navigate
• browser_snapshot
• browser_click
• browser_type
• browser_scroll
• browser_wait_for
• browser_get_content（markdown/text/screenshot）

CLI（MVP）

• session init/info/clear
• nav
• snapshot
• act click/type
• content
• fetch（基于 Playwright request，复用同会话 Cookie）
• run（多步流程编排，单进程保留页面上下文）
• run --file（从 YAML/JSON 文件加载流程）
• resume / run-state（人工接入后恢复）
• handoff-ui --port 7788（本地人工接管面板，网页点 Resume）
• session export/import（会话目录导出与恢复）
• act press/wait/select（补齐关键交互动作）

基础反检测

• Playwright + Chromium
• playwright-extra + stealth plugin

快速开始（CLI）

# 初始化会话
hybridbrowser session init --session demo --mode state --json

# 导出/导入会话
hybridbrowser session export --session demo --out /tmp/hb-export --json
hybridbrowser session import --session demo2 --in /tmp/hb-export/demo --json

# 导航
hybridbrowser nav https://example.com --session demo --headless --json

# HTTP 直请求（复用会话）
hybridbrowser fetch https://example.com --session demo --method GET --json

尚未完成（下一阶段）

• fetch 返回体结构化（JSON 自动识别、二进制处理）
• 人工接管（wait_for_human + UI）
• MCP 与 CLI 全量能力对齐

核心设计方向

采用“三层同源”架构，避免能力重复实现：

1. Core Runtime：浏览器、会话、HTTP 的统一能力
2. CLI Adapter：hybridbrowser 子命令（优先用于 Skill）
3. MCP Adapter：将同一套能力暴露为 MCP tools

会话设计（重点）

为支持“登录 → 浏览 → 填表”多步流程，会话支持双模式：

• state 模式：基于 storageState，速度快，实现简单
• profile 模式：基于 user-data-dir 持久 profile，抗风控更稳

详细命令与 JSON 规范见：

• https://github.com/sunshanpeng/hybrid-browser/blob/main/docs/CLI_SPEC_v0.1.md
• https://github.com/sunshanpeng/hybrid-browser/blob/main/docs/CODEX_INTEGRATION.md

本地开发

npm install
npm run dev     # MCP server
npm run build
npm start

目录（当前）

src/
  cli.ts
  index.ts
  server.ts
  browser.ts
  runtime/
    session.ts
    browser-runtime.ts
  tools/
    navigate.ts
    snapshot.ts
    click.ts
    type.ts
    scroll.ts
    wait.ts
    content.ts

测试

需求先写测试用例，再开发实现。当前测试与案例对照见：

• https://github.com/sunshanpeng/hybrid-browser/blob/main/docs/FEATURE_TEST_MATRIX.md
• https://github.com/sunshanpeng/hybrid-browser/blob/main/tests/TEST_CASES.md

核心回归用例（TC-01 ~ TC-12）已覆盖：

• 会话生命周期（state/profile）、导入导出
• 单命令路径（nav/snapshot/content）
• run 多步、run --file、wait_for_human/resume、run-state
• handoff-ui 恢复
• MCP tools/list 能力清单

执行：

npm run build
npm test