一天一个开源项目（第74篇）：OpenCLI - 把任意网站变成零成本 CLI 工具的 AI Agent 基础设施

引言

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

这是「一天一个开源项目」系列的第 74 篇文章。今天介绍的项目是 OpenCLI （GitHub）。

让 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 的核心理念：「编译期智能 vs 运行期智能」的系统设计哲学
• CDP（Chrome DevTools Protocol）驱动真实 Chrome 会话的技术实现
• Adapter 生命周期：探索 → 合成 → 生成 → 级联验证
• Self-Repair Protocol：Adapter 自动修复机制
• 91 个内置 Adapter 的使用方式 + 为新网站生成 Adapter

前置知识

• 了解 CLI 工具的基本使用
• 基本的 TypeScript / Node.js 知识（可选，用于理解源码）
• 了解 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 工具链的代表作，其系统设计思维明显受数据库领域影响------「确定性执行」「一次编译多次运行」都是典型的数据库优化思想。

项目数据

• ⭐ GitHub Stars: 15,600+
• 🍴 Forks: 1,500+
• 🐛 Open Issues: 39
• 🔀 Open PRs: 49
• 📝 总提交: 845
• 📦 最新版本: v1.7.0（2026 年 4 月 11 日）
• 📄 License: Apache 2.0
• 🔌 内置 Adapters: 91 个

---

主要功能

核心作用

当前 AI Agent 与 Web 交互面临两个根本矛盾：

问题一：运行时成本

传统方案（Browser Use / Stagehand 等）：
任务执行 → LLM 分析 DOM → LLM 决策点击位置 → LLM 验证结果 → LLM...
每次执行消耗大量 token，100 次执行 = 100 次 LLM 调用

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

问题二：账号安全

传统爬虫 / 自动化方案：
浏览器控制程序需要 Cookie / 密码 → 凭证暴露给代码 → 安全风险

OpenCLI 方案：
Browser Bridge Extension 连接用户正在运行的 Chrome
→ 复用已登录会话 → 凭证从不离开浏览器
→ 账号就像普通用户在操作

使用场景

1. AI Agent 的稳定工具层

   • 为 Claude Code、Codex 等 AI 工具提供可靠的 Web 操作接口，代替不稳定的"每次截图让 LLM 分析"方案

2. 日常命令行效率工具

   • opencli bilibili trending | head -10 实时获取 B 站热榜
   • opencli twitter search "AI agent" --format csv > output.csv 导出搜索结果

3. 私有网站自动化

   • 为公司内网应用、个人常用网站生成 CLI 接口，实现数据提取和操作自动化

4. Electron 桌面应用控制

   • 通过 CDP 驱动 Cursor、Notion、Discord、ChatGPT Desktop 等 Electron 应用执行自动化操作

5. CI/CD 数据采集

   • 标准 Unix exit codes 使 OpenCLI 可无缝接入 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 覆盖主流平台：

分类	支持平台
视频	Bilibili、YouTube
社交	Twitter/X、GitHub
搜索	Bing、DuckDuckGo
新闻	Hacker News、Product Hunt
购物	多平台
本地工具	Obsidian、Docker（通过 CLI Hub）

三大操作模式

模式一：内置 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"

# 执行 JS 脚本
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 Use	Stagehand	Playwright
运行时 LLM 成本	✅ 零	❌ 每次调用	❌ 部分调用	✅ 零
账号安全	✅ 复用已登录 Chrome	❌ 需注入凭证	❌ 需注入凭证	❌ 需手动管理
AI Agent 友好	✅ 原生 Skills	✅ 直接用	✅ 直接用	需包装
执行稳定性	✅ 确定性	❌ LLM 随机性	中	✅ 高
自我修复	✅ Self-Repair Protocol	靠 LLM 重试	无	无
学习成本	低（CLI 直接用）	中（Python API）	中（TS API）	高（需写脚本）

为什么选择 OpenCLI？

• 成本最优：只在生成 Adapter 时消耗 LLM，后续执行成本归零
• 安全最优：凭证永远不离开本地浏览器
• 稳定最优：确定性执行，不受模型版本更新影响
• 数据库工程师设计：System-level 思维，Self-Repair Protocol 等设计严谨

---

项目详细剖析

整体架构

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 实例。这一设计的关键收益：

1. 复用所有已登录的网站 Session（Twitter、GitHub、公司内网......）
2. 触发正常的人类浏览器指纹（反爬虫更难检测）
3. 凭证从不暴露给 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. 返回结构化数据（CLI 框架负责格式化输出）
        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 最复杂也最有价值的功能，分为四个命令：

# 步骤一：explore
# 在真实浏览器中录制交互行为，分析页面结构和认证方式
opencli explore https://target-site.com

# 步骤二：synthesize
# 将录制的交互行为合成为 Adapter 结构草稿
opencli synthesize

# 步骤三：generate
# AI 辅助将草稿转化为完整、可执行的 Adapter 代码，并自动测试验证
opencli generate --url https://target-site.com --action "提取文章列表"

# 步骤四：cascade
# 验证认证策略（处理 OAuth、Cookie、2FA 等场景），确保 Adapter 在真实环境中可用
opencli cascade

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

AI Agent Skills 集成

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

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

Skill	用途
opencli-explorer	引导 AI 完成探索 + 生成 Adapter 的完整流程
opencli-browser	低级浏览器控制（click、type、screenshot、eval、网络抓包）
opencli-usage	帮助 AI 发现哪些 Adapter 可用
opencli-oneshot	单次执行特定操作，快速实验

在 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 执行）

---

项目地址与资源

官方资源

• 🌟 GitHub : github.com/jackwener/O...
• 📦 npm : @jackwener/opencli
• 🐛 Issue Tracker : github.com/jackwener/O...
• 📦 Releases : github.com/jackwener/O...

作者其他项目

• opencode-ios: iOS 端 AI 编程助手
• Apache Arrow/DataFusion Committer 贡献列表

同赛道参考项目

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

---

总结与展望

核心要点回顾

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

适用人群

• AI Agent 开发者：需要为 Agent 提供稳定、零成本 Web 操作接口的工程师
• 自动化爱好者：希望将常用网站变成命令行工具，接入自己工作流的开发者
• 注重数据安全的团队：不愿意将账号凭证暴露给 AI 工具的企业用户
• Claude Code / Codex 重度用户：希望扩展 AI 工具网页操作能力的开发者

一个设计启示

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

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

---

欢迎来我的个人主页找到更多有用的知识和有趣的产品