OpenCLI 深度解析：把任何网站变成你的命令行工具

OpenCLI - 一个AI原生的CLI运行时框架，能让任何网站、Electron桌面应用或本地二进制文件变成标准化的命令行接口。

---

📚 目录

1. 什么是 OpenCLI？
2. 核心特性
3. 快速开始
4. 使用场景
5. 工作原理
6. 高级功能
7. 核心架构
8. 开发自己的适配器

---

什么是 OpenCLI？

OpenCLI 是一个革命性的开源工具，由开发者 jackwener 于2026年3月14日发布[[5]]。它的核心理念是：让任何网站和工具都能成为你的命令行界面。

核心价值

传统的浏览器自动化工具（如 Puppeteer、Playwright）虽然功能强大，但对于日常简单内容采集、AI Agent 工具链和终端快速操作来说过于重量级[[27]]。OpenCLI 填补了这个空白，提供了一个轻量级、确定性的 CLI 接口层。

三大核心能力：

1. 网站 → CLI：将网站变成确定性命令行工具
2. 浏览器自动化：直接控制实时浏览器
3. Electron 应用控制：从终端控制桌面应用

为什么需要 OpenCLI？

想象一下这些场景：

• 你想从 B站、知乎、小红书获取热门内容，但不想打开浏览器
• 你需要让 AI Agent 自动操作某个网站，但不想写复杂的自动化脚本
• 你想统一管理各种 CLI 工具（gh、docker、obsidian等）

OpenCLI 就是为了解决这些问题而生。

---

核心特性

🌟 亮点功能

1. CLI All Electron

将 Antigravity Ultra、Cursor、Codex、ChatGPT、Notion 等 Electron 应用变成 CLI 工具，让 AI 能够原生控制自己[[1]]。

2. 浏览器自动化

通过 opencli browser 命令，AI Agent 可以直接控制浏览器：点击、输入、提取、截图——任何交互都可完全脚本化[[1]]。

3. 70+ 预构建适配器

支持包括：

• 中文平台：Bilibili、知乎、小红书、贴吧、虎扑、1688、豆瓣等
• 国际平台：Reddit、Twitter/X、HackerNews、Amazon、GitHub等
• AI工具：Gemini、NotebookLM、ChatGPT Desktop等

4. 账户安全

复用 Chrome/Chromium 的登录状态，凭证永远不会离开浏览器[[1]]。这意味着：

• ✅ 零风控：使用你自己的浏览器会话
• ✅ 零凭证存储：不需要保存账号密码
• ✅ 反检测：内置反指纹识别和风险规避措施

5. AI Agent 就绪

提供完整的 AI 辅助工作流[[21]]：

• explore：发现网站 API 和能力
• synthesize：生成适配器
• generate：一键生成新 CLI
• cascade：自动探测认证策略

6. External CLI Hub

作为通用 CLI 枢纽，可以注册任何本地工具（gh、docker、obsidian等），实现统一发现和自动安装[[20]]。

7. 零 LLM 成本

运行时不消耗任何 token，运行10,000次也不花钱[[1]]。

---

快速开始

1. 安装 OpenCLI

npm install -g @jackwener/opencli

2. 安装 Browser Bridge 扩展

OpenCLI 通过轻量级的 Browser Bridge 扩展和本地守护进程连接到 Chrome/Chromium[[1]]。

步骤：

1. 从 GitHub Releases 下载最新的 opencli-extension.zip
2. 解压文件
3. 打开 chrome://extensions，启用开发者模式
4. 点击加载已解压的扩展程序，选择解压后的文件夹

3. 验证安装

opencli doctor
opencli daemon status

4. 运行你的第一个命令

# 查看所有可用命令
opencli list

# 获取 HackerNews 热门内容
opencli hackernews top --limit 5

# 获取 B站热门
opencli bilibili hot --limit 5

# 获取知乎热榜
opencli zhihu hot --limit 10

5. 输出格式

所有命令都支持多种输出格式[[1]]：

# JSON 格式（适合管道传输到 jq 或 LLM）
opencli bilibili hot -f json

# CSV 格式（适合电子表格）
opencli bilibili hot -f csv

# Markdown 格式
opencli zhihu hot -f md

# 详细模式（显示管道调试步骤）
opencli bilibili hot -v

---

使用场景

场景 1：作为人类用户

当你想要可靠的命令而不是实时浏览器会话时：

# 查看 B站历史记录
opencli bilibili history

# 搜索小红书笔记
opencli xiaohongshu search "AI工具" --limit 10

# 下载 Twitter 用户媒体
opencli twitter download elonmusk --limit 20 --output ./twitter

# 获取知乎问题详情
opencli zhihu question "https://www.zhihu.com/question/xxx"

场景 2：AI Agent 使用

AI Agent 有两个入口点[[1]]：

1. 创建可重用命令（使用 opencli-explorer skill）：

# 安装技能
npx skills add jackwener/opencli --skill opencli-explorer

# Agent 会：
# 1. 探索网站 API
# 2. 生成适配器
# 3. 创建可重用命令

2. 实时浏览器控制（使用 opencli-browser skill）：

npx skills add jackwener/opencli --skill opencli-browser

# 浏览器命令包括：
# open, click, type, select, wait, screenshot, scroll, eval 等

场景 3：下载媒体内容

OpenCLI 支持从多个平台下载图片、视频和文章[[1]]：

# 下载小红书笔记（图片+视频）
opencli xiaohongshu download abc123 --output ./xhs

# 下载 B站视频（需要 yt-dlp）
opencli bilibili download BV1xxx --output ./bilibili

# 下载知乎文章（Markdown格式）
opencli zhihu download --url "https://zhuanlan.zhihu.com/p/xxx" --with-images

场景 4：作为 CLI 枢纽

统一管理你的所有 CLI 工具[[1]]：

# 注册本地工具
opencli register mycli

# 使用 GitHub CLI
opencli gh pr list --limit 5

# 使用 Docker
opencli docker ps

# 使用 Obsidian
opencli obsidian search query="AI"

场景 5：控制 Electron 桌面应用

直接从终端控制桌面应用[[1]]：

# 控制 Cursor IDE
opencli cursor composer "实现一个排序算法"

# 控制 ChatGPT Desktop
opencli chatgpt ask "解释量子计算"

# 控制 Notion
opencli notion search query="项目计划"

---

工作原理

整体架构

OpenCLI 的架构设计非常巧妙，主要由以下几个部分组成：

┌─────────────────────────────────────────────────────────┐
│                    User / AI Agent                      │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                   OpenCLI Core                          │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   CLI Hub   │  │   Registry   │  │  Discovery   │  │
│  └─────────────┘  └──────────────┘  └──────────────┘  │
└─────────┬──────────────┬─────────────────┬────────────┘
          │              │                 │
          ▼              ▼                 ▼
   ┌──────────┐   ┌──────────┐     ┌──────────────┐
   │ Adapters │   │ Browser  │     │  External    │
   │  (TS)    │   │  Daemon  │     │    CLIs      │
   └──────────┘   └──────────┘     └──────────────┘
                        │
                        ▼
              ┌─────────────────┐
              │ Chrome Extension│
              │ (Browser Bridge)│
              └─────────────────┘
                        │
                        ▼
              ┌─────────────────┐
              │  Chrome/Chrome  │
              │   (Logged-in)   │
              └─────────────────┘

核心组件详解

1. 适配器层（Adapter Layer）

所有网站和应用的接口都通过 TypeScript 适配器实现[[1]]：

// 示例：一个简单的适配器
import { cli } from '@jackwener/opencli/registry';

export default cli({
  name: 'bilibili',
  commands: {
    hot: {
      description: '获取B站热门',
      args: {
        limit: { type: 'number', default: 10 }
      },
      async run({ limit }) {
        // 通过浏览器获取数据
        const data = await browser.evaluate(() => {
          // 提取页面数据
          return document.querySelectorAll('.video-card');
        });
        return data.slice(0, limit);
      }
    }
  }
});

关键设计决策：

• 所有适配器已从 YAML 迁移到 TypeScript[[1]]
• 使用包导出（@jackwener/opencli/registry）而非相对导入[[1]]
• 适配器位于根目录 clis/，与核心运行时分离[[1]]

2. 浏览器桥接（Browser Bridge）

这是 OpenCLI 的核心创新点：

传统方案的问题：

• Selenium/Playwright：需要独立的浏览器实例，容易被检测
• 需要处理复杂的认证流程
• 容易被网站反爬虫机制识别

OpenCLI 的方案：

1. 复用现有浏览器：使用你已经在登录的 Chrome/Chromium
2. Chrome DevTools Protocol (CDP)：通过 CDP 直接控制浏览器
3. Browser Bridge 扩展：轻量级扩展，建立 WebSocket 连接
4. 本地守护进程：管理浏览器连接和命令执行

工作流程：

1. 用户执行: opencli bilibili hot
         ↓
2. OpenCLI 发现 bilibili 适配器
         ↓
3. 适配器通过 CDP 连接到浏览器
         ↓
4. Browser Bridge 扩展接收命令
         ↓
5. 在已登录的浏览器中执行操作
         ↓
6. 提取数据并返回

3. 反检测机制

OpenCLI 内置了强大的反检测功能[[1]]：

// 核心反检测措施
- 修补 navigator.webdriver 属性
- 模拟 window.chrome 对象
- 伪造插件列表
- 清理 ChromeDriver/Playwright 全局变量
- 从 Error 堆栈中剥离 CDP 帧
- 广泛的风险控制规避措施

这使得 OpenCLI 能够绕过大多数网站的反爬虫机制。

4. 认证策略（Cascade）

OpenCLI 提供智能的认证策略发现[[1]]：

# 自动探测认证路径
opencli cascade https://api.example.com/data

5层认证策略[[1]]：

1. PUBLIC：公开端点，无需认证
2. COOKIE：使用浏览器 Cookie
3. HEADER：使用自定义请求头
4. OAUTH：OAuth 流程
5. MANUAL：需要人工干预

核心原理：从探索到生成

OpenCLI 提供了一套完整的 AI 辅助工作流来创建新适配器[[21]]：

步骤 1：探索（Explore）

opencli explore https://example.com --site mysite

探索过程：

1. 打开目标网站
2. 捕获网络请求
3. 分析 DOM 结构
4. 识别 API 端点
5. 记录用户交互

步骤 2：合成（Synthesize）

opencli synthesize mysite

合成过程：

1. 读取探索数据
2. 生成 TypeScript 适配器代码
3. 定义命令和参数
4. 创建数据提取逻辑

步骤 3：生成（Generate）

opencli generate https://example.com --goal "获取热门内容"

一键生成：

• 自动执行 explore → synthesize → register 流程
• 生成可用的 CLI 命令
• 或提供结构化解释（如果受阻）

步骤 4：级联（Cascade）

opencli cascade https://api.example.com/data

认证探测：

• 测试公开端点
• 尝试 Cookie 认证
• 尝试自定义 Header
• 返回最佳认证策略

---

高级功能

1. 自我修复协议（Self-Repair Protocol）

这是 OpenCLI 的最新特性[[1]]：

问题：网站结构变化导致适配器失效

解决方案：AI Agent 自动诊断并修复适配器

# 当命令失败时
opencli zhihu hot

# 错误输出包含 AutoFix 提示
# "Hint: Re-run with OPENCLI_DIAGNOSTIC=1 for repair context"

# 启动诊断
OPENCLI_DIAGNOSTIC=1 opencli zhihu hot

# AI Agent 会：
# 1. 诊断失败原因
# 2. 修复适配器
# 3. 重试命令
# 4. 最多 3 轮修复

安全边界[[1]]：

• 只修改适配器文件，不修改核心代码
• 仅修改 sourcePath 指定的文件
• AUTH_REQUIRED 和 BROWSER_CONNECT 是硬停止（报告但不修改）
• 最多 3 轮修复

2. 插件系统

扩展 OpenCLI 功能[[1]]：

# 安装插件
opencli plugin install github:user/opencli-plugin-my-tool

# 查看插件
opencli plugin list

# 更新插件
opencli plugin update --all

# 卸载插件
opencli plugin uninstall my-tool

官方插件示例：

• opencli-plugin-github-trending：GitHub 热门项目
• opencli-plugin-hot-digest：多平台热门聚合
• opencli-plugin-juejin：稀土掘金热门
• opencli-plugin-vk：VK（俄罗斯社交平台）

3. Skills 系统（AI Agent 技能）

为 AI Agent 提供可重用的技能包[[1]]：

# 安装所有技能
npx skills add jackwener/opencli

# 或单独安装
npx skills add jackwener/opencli --skill opencli-usage
npx skills add jackwener/opencli --skill opencli-browser
npx skills add jackwener/opencli --skill opencli-explorer
npx skills add jackwener/opencli --skill opencli-oneshot
npx skills add jackwener/opencli --skill opencli-autofix

技能说明：

• opencli-usage：基础使用指南
• opencli-browser：浏览器控制技能
• opencli-explorer：适配器创建技能
• opencli-oneshot：一键生成（URL + 目标）
• opencli-autofix：自动修复技能

4. 退出代码规范

OpenCLI 遵循 Unix sysexits.h 约定[[1]]：

代码	含义	使用场景
0	成功	命令正常完成
1	通用错误	意外/未分类的失败
2	使用错误	参数错误或未知命令
66	空结果	无数据返回 (EX_NOINPUT)
69	服务不可用	Browser Bridge 未连接
75	临时失败	命令超时——重试
77	需要认证	未登录目标网站
78	配置错误	缺少凭证或配置错误
130	中断	Ctrl-C / SIGINT

实用示例：

# 自动认证
opencli github issues 2>/dev/null
[ $? -eq 77 ] && opencli github auth

# 重试逻辑
until opencli spotify status; do
  [ $? -eq 75 ] && sleep 5 || break
done

5. 性能优化

最新版本引入了快速路径优化[[1]]：

// 轻量级命令绕过完整发现流程
- --version：直接返回版本
- --get-completions：基于清单快速补全
- completion <shell>：生成 shell 补全脚本

// 使用动态 import() 延迟加载重模块
// 避免为简单命令加载 discovery/registry/Commander 等

---

核心架构深度解析

目录结构

opencli/
├── src/                    # 核心运行时
│   ├── main.ts            # 入口点
│   ├── registry.ts        # 适配器注册表
│   ├── discovery.ts       # 适配器发现
│   ├── launcher.ts        # 命令启动器
│   ├── browser/           # 浏览器控制
│   │   ├── cdp.ts        # CDP 连接
│   │   ├── daemon.ts     # 守护进程
│   │   └── bridge.ts     # 扩展通信
│   └── utils/            # 工具函数
├── clis/                 # 适配器目录
│   ├── bilibili/         # B站适配器
│   ├── zhihu/           # 知乎适配器
│   └── twitter/         # Twitter 适配器
├── extension/           # Browser Bridge 扩展
├── skills/              # AI Agent 技能
└── scripts/             # 构建脚本

数据流

命令执行流程：

// 1. 用户输入
opencli bilibili hot --limit 10

// 2. 主入口 (main.ts)
async function main() {
  // 快速路径检查
  if (argv[0] === '--version') {
    console.log(version);
    return;
  }
  
  // 完整启动路径（动态导入）
  const { run } = await import('./cli');
  await run(argv);
}

// 3. 适配器发现 (discovery.ts)
async function discoverAdapters() {
  // 扫描内置适配器
  const builtIn = await scanBuiltInAdapters();
  
  // 扫描用户适配器
  const userAdapters = await scanUserAdapters();
  
  // 扫描外部 CLI
  const externalCLIs = await scanExternalCLIs();
  
  return [...builtIn, ...userAdapters, ...externalCLIs];
}

// 4. 命令注册 (registry.ts)
function registerAdapter(adapter) {
  const { name, commands } = adapter;
  
  for (const [cmdName, cmdDef] of Object.entries(commands)) {
    program
      .command(`${name} ${cmdName}`)
      .description(cmdDef.description)
      .action(async (args) => {
        // 执行适配器命令
        const result = await cmdDef.run(args);
        output(result, args.format);
      });
  }
}

// 5. 浏览器连接 (browser/cdp.ts)
async function connectToBrowser() {
  // 连接到本地守护进程
  const wsUrl = await daemon.getStatus();
  
  // 建立 CDP 连接
  const client = await CDP({
    target: wsUrl,
    port: 19825
  });
  
  return client;
}

// 6. 执行命令 (adapters/bilibili/hot.ts)
export default cli({
  name: 'bilibili',
  commands: {
    hot: {
      async run({ limit }) {
        // 通过 CDP 控制浏览器
        const client = await connectToBrowser();
        
        // 导航到热门页面
        await client.Runtime.evaluate({
          expression: 'window.location.href = "https://www.bilibili.com/v/popular"'
        });
        
        // 等待页面加载
        await client.Page.loadEventFired();
        
        // 提取数据
        const videos = await client.Runtime.evaluate({
          expression: `
            Array.from(document.querySelectorAll('.video-card')).map(card => ({
              title: card.querySelector('.title').textContent,
              author: card.querySelector('.up-name').textContent,
              views: card.querySelector('.view').textContent
            }))
          `
        });
        
        return videos.slice(0, limit);
      }
    }
  }
});

守护进程架构

Daemon（守护进程） 是 OpenCLI 的核心组件：

// daemon/index.ts
import WebSocket from 'ws';
import { CDPClient } from './cdp';

class Daemon {
  private wss: WebSocket.Server;
  private clients: Map<string, CDPClient>;
  
  constructor() {
    // 创建 WebSocket 服务器
    this.wss = new WebSocket.Server({ port: 19825 });
    
    this.wss.on('connection', (ws) => {
      this.handleConnection(ws);
    });
  }
  
  private async handleConnection(ws: WebSocket) {
    ws.on('message', async (message) => {
      const cmd = JSON.parse(message.toString());
      
      switch (cmd.type) {
        case 'EVALUATE':
          const result = await this.evaluate(cmd.expression);
          ws.send(JSON.stringify({ result }));
          break;
          
        case 'CLICK':
          await this.click(cmd.selector);
          ws.send(JSON.stringify({ success: true }));
          break;
          
        case 'TYPE':
          await this.type(cmd.selector, cmd.text);
          ws.send(JSON.stringify({ success: true }));
          break;
      }
    });
  }
  
  async evaluate(expression: string) {
    // 通过 CDP 执行 JavaScript
    const client = await this.getClient();
    const { result } = await client.Runtime.evaluate({ expression });
    return result.value;
  }
}

Browser Bridge 扩展

扩展架构（extension/）：

// extension/background.ts
chrome.runtime.onConnect.addListener((port) => {
  port.onMessage.addListener((message) => {
    // 转发消息到页面
    if (message.type === 'EVALUATE') {
      chrome.tabs.query({ active: true }, (tabs) => {
        chrome.tabs.sendMessage(tabs[0].id, message, (response) => {
          port.postMessage(response);
        });
      });
    }
  });
});

// extension/content.js
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'EVALUATE') {
    try {
      const result = eval(message.expression);
      sendResponse({ result });
    } catch (error) {
      sendResponse({ error: error.message });
    }
  }
});

---

开发自己的适配器

方法 1：AI 自动生成（推荐）

# 一键生成
opencli generate https://example.com/hot --goal "获取热门列表"

# AI 会自动：
# 1. 探索网站结构
# 2. 识别 API 和数据格式
# 3. 生成 TypeScript 适配器
# 4. 注册到 OpenCLI

方法 2：手动创建

步骤 1：创建适配器目录

cd ~/.opencli/clis
mkdir mysite
cd mysite

步骤 2：编写适配器

// ~/.opencli/clis/mysite/hot.ts
import { cli, browser } from '@jackwener/opencli/registry';

export default cli({
  name: 'mysite',
  description: '我的网站适配器',
  commands: {
    hot: {
      description: '获取热门内容',
      args: {
        limit: {
          type: 'number',
          description: '返回数量',
          default: 10,
          positional: true
        },
        category: {
          type: 'string',
          description: '分类',
          choices: ['tech', 'science', 'art']
        }
      },
      async run({ limit, category }) {
        // 导航到页面
        await browser.open(`https://example.com/hot/${category || ''}`);
        
        // 等待页面加载
        await browser.wait({ selector: '.item', timeout: 5000 });
        
        // 提取数据
        const items = await browser.evaluate(() => {
          return Array.from(document.querySelectorAll('.item')).map(el => ({
            title: el.querySelector('.title')?.textContent?.trim(),
            author: el.querySelector('.author')?.textContent?.trim(),
            url: el.querySelector('a')?.href,
            score: el.querySelector('.score')?.textContent?.trim()
          }));
        });
        
        return items.slice(0, limit);
      }
    },
    
    search: {
      description: '搜索内容',
      args: {
        query: {
          type: 'string',
          description: '搜索关键词',
          positional: true
        }
      },
      async run({ query }) {
        // 使用网络请求（如果有 API）
        const response = await fetch(`https://api.example.com/search?q=${query}`);
        const data = await response.json();
        
        return data.results.map(item => ({
          title: item.title,
          url: item.url,
          summary: item.summary
        }));
      }
    }
  }
});

步骤 3：测试适配器

# 查看新命令
opencli list | grep mysite

# 运行命令
opencli mysite hot --limit 5
opencli mysite search "AI"

方法 3：使用探索工具

# 1. 探索网站
opencli explore https://example.com --site mysite

# 这会：
# - 打开浏览器
# - 记录网络请求
# - 分析 DOM 结构
# - 保存探索数据到 ~/.opencli/explore/mysite.json

# 2. 合成适配器
opencli synthesize mysite

# 这会：
# - 读取探索数据
# - 生成适配器代码
# - 保存到 ~/.opencli/clis/mysite/

# 3. 测试生成的适配器
opencli mysite <command>

适配器 API 参考

核心导入：

import { cli, browser, logger, errors } from '@jackwener/opencli/registry';

Browser API：

// 导航
await browser.open(url);
await browser.back();

// 交互
await browser.click(selector);
await browser.type(selector, text);
await browser.select(selector, value);
await browser.keys(keys); // 键盘输入

// 等待
await browser.wait({ selector: '.item', timeout: 5000 });
await browser.wait({ networkIdle: true });

// 提取
const result = await browser.evaluate(() => {
  return document.querySelector('.title').textContent;
});

const html = await browser.state(); // 获取页面状态

// 截图
await browser.screenshot({ path: './screenshot.png' });

// 滚动
await browser.scroll({ direction: 'down', amount: 500 });

// 网络
const requests = await browser.network({ url: /api/ });

错误处理：

import { SelectorError, EmptyResultError, AuthError } from '@jackwener/opencli/errors';

try {
  const items = await browser.evaluate(extractData);
  if (items.length === 0) {
    throw new EmptyResultError('没有找到任何内容');
  }
  return items;
} catch (error) {
  if (error.message.includes('登录')) {
    throw new AuthError('需要登录才能访问');
  }
  throw error;
}

---

实战案例

案例 1：构建跨平台热门聚合器

# 创建聚合脚本
cat > aggregate-hot.sh << 'EOF'
#!/bin/bash

# 获取各平台热门
opencli bilibili hot -f json --limit 10 > bilibili.json
opencli zhihu hot -f json --limit 10 > zhihu.json
opencli xiaohongshu feed -f json --limit 10 > xhs.json
opencli hackernews top -f json --limit 10 > hn.json
opencli reddit hot -f json --limit 10 > reddit.json

# 合并数据
jq -s '{
  bilibili: .[0],
  zhihu: .[1],
  xiaohongshu: .[2],
  hackernews: .[3],
  reddit: .[4],
  timestamp: now
}' *.json > aggregated.json

echo "聚合完成：aggregated.json"
EOF

chmod +x aggregate-hot.sh
./aggregate-hot.sh

案例 2：AI Agent 自动化工作流

// AI Agent 技能：自动发布内容
import { OpenCLI } from '@jackwener/opencli/sdk';

async function publishToPlatforms(content) {
  const cli = new OpenCLI();
  
  // 发布到小红书
  await cli.run('xiaohongshu', 'publish', {
    title: content.title,
    content: content.body,
    images: content.images
  });
  
  // 发布到知乎
  await cli.run('zhihu', 'answer', {
    question: content.questionUrl,
    content: content.body
  });
  
  // 发布到 Twitter
  await cli.run('twitter', 'post', {
    text: content.title,
    media: content.images
  });
}

// 使用
await publishToPlatforms({
  title: 'AI 工具推荐',
  body: '今天推荐一个超好用的工具...',
  images: ['./screenshot1.png', './screenshot2.png'],
  questionUrl: 'https://www.zhihu.com/question/xxx'
});

案例 3：监控和告警

#!/bin/bash
# 监控竞品价格

while true; do
  # 获取商品价格
  price=$(opencli amazon product ASIN123 --format json | jq '.price')
  
  # 检查价格
  if [ "$price" -lt 100 ]; then
    # 发送通知
    curl -X POST https://api.telegram.org/botXXX/sendMessage \
      -d "chat_id=YYY" \
      -d "text=价格降到 $price！"
  fi
  
  # 等待 1 小时
  sleep 3600
done

---

故障排查

常见问题

1. 扩展未连接

症状：

Error: Extension not connected

解决方案[[1]]：

# 检查扩展是否启用
# 打开 chrome://extensions
# 确保 Browser Bridge 扩展已启用

# 重启守护进程
opencli daemon restart

# 验证连接
curl localhost:19825/status

2. 无法访问 Chrome 扩展 URL

症状：

Cannot access a chrome-extension:// URL

解决方案[[1]]：

# 暂时禁用其他扩展
# 某些扩展可能会干扰 Browser Bridge

3. 空数据或认证错误

症状：

EmptyResultError: 没有找到任何内容
AuthError: 需要登录

解决方案[[1]]：

# 1. 在 Chrome 中打开目标网站
# 2. 确认已登录
# 3. 保持浏览器运行
# 4. 重试命令

4. Node API 错误

症状：

Error: Node API not available

解决方案[[1]]：

# 检查 Node 版本
node --version  # 需要 >= 20.0.0

# 或使用 Bun
brew install bun
bun --version   # 需要 >= 1.0

5. 守护进程问题

诊断命令[[1]]：

# 检查状态
opencli daemon status

# 查看日志
curl localhost:19825/logs

# 手动启动
opencli daemon start --verbose

调试技巧

# 启用详细日志
opencli bilibili hot --verbose

# 使用调试模式
DEBUG=opencli:* opencli bilibili hot

# 查看网络请求
opencli browser --devtools

# 诊断工具
opencli doctor

---

性能优化

1. 使用快速路径

轻量级命令自动使用快速路径[[1]]：

# 这些命令绕过完整发现流程
opencli --version
opencli completion bash
opencli list --get-completions

2. 缓存适配器

# 适配器缓存在 ~/.opencli/clis/
# 首次使用后会被缓存

# 手动预缓存
opencli plugin install --all

3. 复用浏览器连接

// 不要每次都创建新连接
const browser = await browser.connect(); // 复用现有连接

// 批量操作
const results = await Promise.all([
  browser.evaluate(extractData1),
  browser.evaluate(extractData2),
  browser.evaluate(extractData3)
]);

---

最佳实践

1. 适配器设计

✅ 好的做法：

// 使用明确的错误类型
if (!element) {
  throw new SelectorError('.item', '元素未找到');
}

if (results.length === 0) {
  throw new EmptyResultError('搜索无结果');
}

// 提供有用的错误信息
throw new AuthError('请在 Chrome 中登录目标网站');

❌ 避免：

// 通用错误
throw new Error('出错了');

// 静默失败
return []; // 不区分空结果和错误

2. 性能考虑

// ✅ 好的：批量操作
const items = await browser.evaluate(() => {
  return Array.from(document.querySelectorAll('.item')).map(el => ({
    title: el.querySelector('.title').textContent,
    price: el.querySelector('.price').textContent
  }));
});

// ❌ 避免：多次 evaluate
const titles = await browser.evaluate(() => 
  document.querySelectorAll('.title')
);
const prices = await browser.evaluate(() => 
  document.querySelectorAll('.price')
);

3. 错误恢复

// 实现重试逻辑
async function withRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(1000 * (i + 1)); // 指数退避
    }
  }
}

// 使用
const data = await withRetry(() => 
  opencli.bilibili.hot()
);

---

社区和贡献

项目统计

• Stars: 14.4k+ [[5]]
• Forks: 1.3k+ [[5]]
• Contributors: 130+ [[5]]
• 内置适配器: 79+ [[1]]
• 最新版本: v1.6.9 (2026-04-08) [[5]]

如何贡献

# 1. Fork 项目
git clone git@github.com:jackwener/opencli.git

# 2. 安装依赖
cd opencli
npm install

# 3. 构建
npm run build

# 4. 链接到全局
npm link

# 5. 运行测试
npm test

# 6. 提交 PR
git commit -m "feat: add new adapter"
git push origin main

贡献类型

1. 新增适配器：为未支持的网站创建适配器
2. 改进文档：完善使用指南和示例
3. Bug 修复：报告并修复问题
4. 性能优化：提升执行效率
5. 插件开发：开发社区插件

---

未来展望

路线图

基于最近的更新和讨论[[1]]：

1. 更多适配器：覆盖更多国内外平台
2. 更强的 AI 集成：更智能的适配器生成和修复
3. 性能提升：更快的启动和执行速度
4. 云同步：适配器配置云端同步
5. 企业版：团队协作和权限管理

技术趋势

OpenCLI 代表了几个重要趋势：

1. AI 原生工具：为 AI Agent 设计的接口
2. 低代码自动化：无需编写复杂脚本
3. 确定性接口：统一的 CLI 抽象层
4. 浏览器即平台：复用现有登录状态

---

总结

OpenCLI 是一个革命性的工具，它：

✅ 简化了浏览器自动化：无需编写复杂脚本
✅ 保护了账户安全：复用浏览器登录状态
✅ 降低了 AI Agent 门槛：统一的 CLI 接口
✅ 提高了开发效率：70+ 预构建适配器
✅ 支持自定义扩展：灵活的插件系统

适用场景：

• 📊 数据收集和监控
• 🤖 AI Agent 工具链
• 🔄 自动化工作流
• 🛠️ 快速原型开发
• 📱 跨平台内容管理

开始使用：

npm install -g @jackwener/opencli
opencli doctor
opencli bilibili hot --limit 5

OpenCLI 正在重新定义我们与网站和工具的交互方式——让一切变得像命令行一样简单。

---

参考资料

• GitHub 仓库: https://github.com/jackwener/opencli [[5]]
• 官方文档: https://opencli.info/
• 中文文档: README.zh-CN.md [[13]]
• 技能包: skills/ 目录 [[1]]
• 适配器示例: clis/ 目录 [[1]]
• 故障排查: TESTING.md, PRIVACY.md [[1]]

---

最后更新：2026-04-09
基于 OpenCLI v1.6.9