OpenCLI 深度解析：当任意网站变成零成本 CLI 工具——AI Agent 基础设施的新范式

引言

"AI 在生成阶段消耗智能，在执行阶段不消耗。"

让 AI Agent 操作浏览器，目前主流方案是每次都让 LLM 实时理解页面 DOM 或截图，再决定怎么点击。这种方式有两个根本问题：每次执行都要消耗大量 token，且结果不稳定——同一个操作，模型可能今天成功、明天因为页面微小变动就失败。

OpenCLI 的思路完全不同：先生成，后执行。用 AI 一次性为某个网站生成一个确定性的 CLI Adapter，之后每次执行这个 Adapter 时，完全不需要调用 LLM——成本是零，稳定性是 100%。

更关键的是，OpenCLI 通过 Chrome Extension 复用用户已登录的真实 Chrome 会话，账号凭证永远不会暴露给外部系统。

15.6k Stars，来自 Apache Arrow/DataFusion PMC 成员 jackwener 的作品，是目前 AI Agent 工具链基础设施赛道最值得关注的开源项目之一。

项目背景

项目简介

OpenCLI 的完整定位是：将网站、浏览器会话、Electron 应用和本地工具转化为确定性 CLI 接口，同时服务于人类用户和 AI Agent。

这句话包含了三个关键词：

• 确定性（Deterministic）：Adapter 执行结果可预测，不依赖 LLM 随机性
• CLI 接口：任何 AI Agent 都能通过标准 Shell 命令调用
• 人类 + AI 双场景：既可以作为日常命令行工具，也可以作为 AI Agent 的工具层

项目的哲学来自数据库领域的核心思想——查询优化：在编译期（查询规划）消耗算力做最优决策，运行期（查询执行）按计划高效执行，不在运行时再做昂贵决策。OpenCLI 将这个思路迁移到 Web 自动化领域。

作者介绍

• 作者：jackwener（真名 jakevin）
• 地点：杭州，中国
• GitHub 粉丝：2,200+
• PMC 成员 & Committer：Apache Arrow、Apache DataFusion、Apache Doris
• 工作经历：MegaETH、SelectDB（ClickHouse 国内厂商）、ByteDance RDS、NebulaGraph
• 技术专长：数据库查询引擎、Rust、Java、Go、Python、C++
• 相关项目：opencode-ios（iOS 端 AI 编程助手）

jackwener 是资深数据库 / 基础设施工程师，OpenCLI 是他跨界 AI Agent 工具链的代表作，其系统设计思维明显受数据库领域影响——"确定性执行""一次编译多次运行"都是典型的数据库优化思想。

项目数据

主要功能

核心作用：解决 AI Agent 与 Web 交互的两大矛盾

问题一：运行时成本

传统方案（Browser Use / Stagehand 等）每次执行都要消耗大量 token：

任务执行 → LLM 分析 DOM → LLM 决策点击位置 → LLM 验证结果 → LLM...
100 次执行 = 100 次 LLM 调用

OpenCLI 方案：

[一次] 生成 Adapter（消耗 LLM）→ 写入 .js 文件
[多次] 执行 Adapter（零 LLM，纯 JS 确定性执行）
100 次执行 = 1 次 LLM 调用

问题二：账号安全

传统爬虫 / 自动化方案需要将 Cookie / 密码暴露给代码，存在安全风险。OpenCLI 通过 Browser Bridge Extension 连接用户正在运行的 Chrome，复用已登录会话，凭证从不离开浏览器——账号就像普通用户在操作。

使用场景

• AI Agent 的稳定工具层：为 Claude Code、Codex 等 AI 工具提供可靠的 Web 操作接口
• 日常命令行效率工具：opencli bilibili trending | head -10 实时获取 B 站热榜
• 私有网站自动化：为公司内网应用、个人常用网站生成 CLI 接口
• Electron 桌面应用控制：通过 CDP 驱动 Cursor、Notion、Discord、ChatGPT Desktop 等
• CI/CD 数据采集：标准 Unix exit codes 无缝接入 CI/CD pipeline

快速开始

# 1. 全局安装 OpenCLI
npm install -g @jackwener/opencli

# 2. 克隆仓库，加载 Browser Bridge Chrome 扩展
git clone https://github.com/jackwener/OpenCLI.git
# 打开 chrome://extensions
# 开启「开发者模式」
# 点击「加载已解压的扩展程序」→ 选择 extension/ 目录

# 3. 验证连接状态
opencli doctor

# 4. 立即使用内置 Adapter
opencli bilibili trending --format json
opencli bilibili search "Rust 教程" --limit 20
opencli browser screenshot --url https://github.com

# 5. 为 AI Agent 安装 Skills
npx skills add jackwener/opencli

内置 Adapter 一览

91 个内置 Adapter 覆盖主流平台：

三大操作模式

模式一：内置 Adapter 直接执行

# 获取 Bilibili 热榜，JSON 格式输出
opencli bilibili trending --format json

# 搜索 GitHub 仓库
opencli github search "react hooks" --sort stars --limit 20

# 输出格式支持：json / csv / yaml / markdown / table
opencli hacker-news top --format table

模式二：实时浏览器控制

opencli browser screenshot --url https://example.com --output ./screenshot.png
opencli browser click --selector "#submit-button"
opencli browser type --selector "input[name=search]" --text "OpenCLI"
opencli browser eval --script "document.title"
opencli browser network --url https://api.example.com

模式三：Adapter 生成（核心功能）

# 探索模式：录制浏览行为，分析页面结构
opencli explore https://some-new-website.com

# 合成：从录制行为生成 Adapter 草稿
opencli synthesize

# 生成并验证：AI 辅助生成 + 自动测试验证
opencli generate --url https://some-new-website.com --action "获取文章列表"

# 级联验证：自动发现认证策略（OAuth/Cookie/2FA）
opencli cascade

项目详细剖析

整体架构

OpenCLI 的架构分为四层，核心是 Browser Bridge Extension 和 CDP 协议：

┌─────────────────────────────────────────┐
│         AI Agent / Human User            │
└──────────────┬──────────────────────────┘
               │ opencli <command> [--format json]
┌──────────────▼──────────────────────────┐
│           OpenCLI CLI Layer             │
│   Commander.js + Plugin Registry        │
│  execution.ts / commanderAdapter.ts     │
└──────────────┬──────────────────────────┘
               │ CDP Protocol (WebSocket)
┌──────────────▼──────────────────────────┐
│       Browser Bridge Extension          │
│  （Chrome 扩展，本地 WebSocket 服务器）  │
└──────────────┬──────────────────────────┘
               │ 复用真实用户会话
┌──────────────▼──────────────────────────┐
│         Chrome / Chromium               │
│   （用户正在运行的真实浏览器实例）        │
└─────────────────────────────────────────┘

关键设计决策：OpenCLI 不启动独立无头浏览器（如 Puppeteer/Playwright 的做法），而是通过 Chrome Extension 的 native messaging API 连接到用户正在运行的 Chrome 实例。这一设计的关键收益：

• 复用所有已登录的网站 Session（Twitter、GitHub、公司内网……）
• 触发正常的人类浏览器指纹（反爬虫更难检测）
• 凭证从不暴露给 Node.js 进程

项目目录结构

OpenCLI/
├── src/
│   ├── cli.ts              # CLI 入口
│   ├── main.ts             # 主程序
│   ├── commanderAdapter.ts # Commander.js 命令解析
│   ├── execution.ts        # 命令执行引擎
│   ├── plugin.ts           # 插件系统
│   ├── registry.ts         # Adapter 注册表
│   ├── generate.ts         # Adapter 生成器
│   ├── generate-verified.ts# 带验证的生成器
│   ├── browser/            # CDP 浏览器控制层
│   └── pipeline/           # 执行流水线
├── clis/                   # 91 个内置 Adapter（.js 文件）
│   ├── bilibili.js
│   ├── github.js
│   ├── hackernews.js
│   └── ...
├── extension/               # Browser Bridge Chrome Extension
├── skills/                  # AI Agent Skills 定义
│   ├── opencli-explorer/   # 探索和生成 Adapter
│   ├── opencli-browser/    # 低级浏览器控制
│   ├── opencli-usage/      # 帮助发现
│   └── opencli-oneshot/    # 单次执行
└── package.json

Adapter 的结构解剖

每个 Adapter 是一个标准 JS 模块，定义了"如何从某个网站提取结构化数据"：

// clis/hackernews.js（简化示意）
module.exports = {
  name: 'hacker-news',
  description: 'Fetch Hacker News stories',
  commands: {
    top: {
      description: 'Get top stories',
      options: [
        { flag: '--limit <n>', description: 'Number of stories', default: 30 }
      ],
      execute: async (options, browser) => {
        // 1. 导航到目标页面
        await browser.goto('https://news.ycombinator.com/');

        // 2. 使用确定性 CSS 选择器提取数据
        const stories = await browser.eval(`
          Array.from(document.querySelectorAll('.athing'))
            .slice(0, ${options.limit})
            .map(el => ({
              rank: el.querySelector('.rank')?.innerText,
              title: el.querySelector('.titleline > a')?.innerText,
              url: el.querySelector('.titleline > a')?.href,
              points: el.nextElementSibling?.querySelector('.score')?.innerText
            }))
        `);

        // 3. 返回结构化数据
        return stories;
      }
    }
  }
};

这种设计的关键：

• execute 函数是纯确定性的——给定相同页面，总是返回相同结构
• 不依赖 LLM 做运行时决策
• CSS 选择器如果因页面更新失效，触发 Self-Repair Protocol

Self-Repair Protocol（v1.7.0 新功能）

这是 OpenCLI 最有技术含量的设计之一。当 Adapter 执行失败时，系统自动启动修复流程，无需人工介入：

Adapter 执行
      ↓
失败（选择器不匹配 / 页面结构变化）
      ↓
[第1步] 开启结构化诊断（OPENCLI_DIAGNOSTIC=1）
  → 捕获错误类型、DOM 快照、执行上下文
      ↓
[第2步] 发送诊断信息给 LLM
  → 分析：哪个选择器失效了？页面结构怎么变了？
      ↓
[第3步] LLM 生成修复后的 Adapter 代码
      ↓
[第4步] 自动替换并重试（最多 3 次）
      ↓
成功 → 保存修复后的 Adapter
失败（3 次后）→ 上报给用户，需要手动介入

这个设计把 LLM 的使用控制在必要时刻（修复），而非常规执行路径，是对成本和稳定性的精准权衡。

Adapter 生成流程：四步级联

为新网站生成 Adapter 是 OpenCLI 最复杂也最有价值的功能，分为四个命令：

四个命令可以逐步执行（调试每一步），也可以一次性运行完整流程。

AI Agent Skills 集成

OpenCLI 提供了 4 个原生 Skills，可以直接在 Claude Code 等工具中使用：

# 安装所有 Skills
npx skills add jackwener/opencli

在 Claude Code 中的实际使用场景：

用户："帮我抓取 Hacker News 今日 Top 20 并整理成报告"

Claude Code:

1. 调用 opencli-usage → 发现 hackernews Adapter 可用
2. 调用 opencli-oneshot → opencli hacker-news top --limit 20 --format json
3. 解析 JSON 数据，生成 Markdown 报告
4. 全程零额外 LLM 调用（步骤 2 是纯 CLI 执行）

横向对比

核心要点回顾

• 编译期 vs 运行期：OpenCLI 最核心的设计哲学——AI 只在生成 Adapter 时参与，执行时完全不调用 LLM，这是来自数据库查询优化思想的跨领域迁移
• 账号安全模型：Browser Bridge Extension 复用真实 Chrome 会话，凭证从不暴露——这是与其他浏览器自动化工具最本质的区别
• Self-Repair Protocol：Adapter 失效时的自动修复机制，把 LLM 使用限制在"必要时刻"，兼顾稳定性和成本
• 四步 Adapter 生成：explore → synthesize → generate → cascade，系统化的 Adapter 创建流程
• 数据库工程师的严谨性：作为 Apache Arrow/DataFusion PMC 成员，jackwener 将基础设施工程的确定性思维带入了 AI 工具链赛道

一个设计启示

OpenCLI 的成功揭示了一个通用的工程原理：AI 系统的成本最优解，往往是尽量将 AI 决策前移到设计时或首次运行时，而非每次运行时。 这个思路不只适用于 Web 自动化——代码模板生成、工作流规划、系统配置优化，都有类似的优化空间。

当 AI 工具的使用成本仍然较高，"一次生成，多次执行"的模式将在更多领域涌现。

项目地址与资源

• 🌟 GitHub: github.com/jackwener/OpenCLI
• 📦 npm: @jackwener/opencli
• 📖 官方文档: opencli.jakevin.com

同赛道参考项目

• Browser Use — Python AI 浏览器自动化
• Stagehand — TypeScript AI 浏览器自动化
• Playwright — 底层浏览器自动化框架

本文属于「一天一个开源项目」系列，如果你觉得这类内容有帮助，欢迎关注程序员茄子获取更多深度技术解析。