OpenCLI：让任何网站成为你的命令行工具

OpenCLI：让任何网站成为你的命令行工具

引言：Web 数据访问的困境

作为开发者，你可能经常遇到这样的场景：

• 想快速获取 Bilibili 热门视频，但不想打开浏览器滚动页面
• 需要在 CI/CD 中自动抓取 T@witter 数据，但 API 每月 $100 起步
• 想让 AI 助手帮你搜索小红书，但它无法直接访问需要登录的网站

传统方案的痛点：

OpenCLI 的核心洞察：既然你的浏览器已经登录了这些网站，为什么不直接复用它？

# 一条命令，结构化数据
opencli bilibili hot --limit 5 -f json

# 管道组合，Unix 哲学
opencli xiaohongshu search --query "AI" | jq '.[] | .title'

# 甚至支持桌面应用
opencli cursor ch@t "Fix the auth bug"

核心创新：不解析 HTML，而是拦截 JSON API

这是理解 OpenCLI 的关键 —— 它避开了 HTML 解析的复杂性。

传统爬虫的困境

用户请求 → 加载 HTML → 解析 DOM → 提取数据
          (页面结构易变、反爬虫检测、维护困难)

问题在于：

• HTML 结构随时会改（.title → .title-text → [data-title]）
• 需要等待 JS 渲染（何时完成？懒加载如何处理？）
• 反爬虫容易检测（Puppeteer、Selenium 的特征）

OpenCLI 的巧妙设计

用户请求 → 网络流量 → 拦截 JSON API → 提取数据
          (API 结构稳定、版本化、无需解析 HTML)

实际案例：获取 Bilibili 热门视频

传统方式（HTML 解析）：

//  容易失败
await page.goto('https://www.bilibili.com/ranking');
const titles = await page.$$eval('.video-title', els =>
  els.map(e => e.textContent)
);
// 问题：CSS 选择器可能随时改变

OpenCLI 方式（JSON 拦截）：

//  稳定可靠
await page.goto('https://www.bilibili.com');
page.on('network', (req) => {
  if (req.url.includes('/x/web-interface/popular')) {
    const data = JSON.parse(req.response);
    return data.data.list;  // 明确的路径
  }
});
// 优势：API 路径稳定（很少变更）

为什么 JSON API 更稳定？

关键数据：OpenCLI 的 87+ 个适配器中，95% 基于 JSON API，失效率远低于传统 HTML 爬虫。

架构设计：分层通信模型

OpenCLI 如何在不启动独立浏览器的情况下，复用你已登录的 Chrome？

传统方案的困境

OpenCLI 的三层架构

┌──────────────────────────────────────┐
│  CLI 进程 (Node.js)                  │
│  opencli bilibili hot                │
└────────────┬─────────────────────────┘
             │ HTTP POST
             ↓
┌──────────────────────────────────────┐
│  本地守护进程 (localhost:19825)      │
│  • 自动启动                          │
│  • 安全验证（Origin + 自定义头）     │
└────────────┬─────────────────────────┘
             │ WebSocket
             ↓
┌──────────────────────────────────────┐
│  Chrome 扩展后台脚本                 │
│  • 命令                          │
│  • 调用 DevTools Protocol            │
└────────────┬─────────────────────────┘
             │ CDP
             ↓
┌──────────────────────────────────────┐
│  Chrome 页面实例                     │
│  • 执行 JavaScript                   │
│  • 复用 Cookie（已登录）             │
└──────────────────────────────────────┘

关键创新：工作区隔离

想象你同时运行多个任务：

opencli xiaohongshu search "旅游" &  # 后台任务 1
opencli bilibili hot &               # 后台任务 2
opencli zhihu hot                    # 前台任务

传统方案需要启动 3 个浏览器实例（~600MB 内存、3×3 秒启动时间）。

OpenCLI 的方案：单个浏览器，多个独立标签页

┌────────────────────────┐
│  Chrome 窗口           │
│                        │
│  [标签1: 用户正常浏览] │
│  [标签2: workspace="xiaohongshu"] ← 后台任务 1
│  [标签3: workspace="bilibili"]    ← 后台任务 2
│  [标签4: workspace="zhihu"]       ← 前台任务
└────────────────────────┘

性能对比：

传统方案：
  3 个独立 Chrome → 启动 9 秒 → 600MB 内存

OpenCLI：
  1 个 Chrome + 守护进程 → 启动 0.5 秒 → 200MB 内存
  加速 18 倍 

类比说明： 就像图书馆的阅览室 —— 传统方案是每个人占一整层楼（浏览器实例），OpenCLI 是每个人占一个独立阅览室（标签页）—— 共享基础设施（电力、网络、门禁卡），但各自独立工作。

认证管理：五层策略体系

你可能会问：OpenCLI 如何处理不同网站的登录和 token？

OpenCLI 的核心理念：不存储任何凭证，而是复用浏览器的认证状态。

五层认证策略

OpenCLI 根据网站的认证复杂度，自动选择最合适的策略：

Tier 1: PUBLIC（无需认证）
  → 示例：HackerNews、arXiv
  → 方式：直接 HTTP 请求
  → Token：无

Tier 2: COOKIE（复用浏览器 Cookie）
  → 示例：Bilibili、小红书、T@witter
  → 方式：页面内 fetch() 自动携带 Cookie
  → Token：浏览器管理，OpenCLI 不存储

Tier 2.5: LOCALSTORAGE（从浏览器提取 Bearer Token）
  → 示例：Notion、Linear、现代 SaaS
  → 方式：从 localStorage 读取 access_token
  → Token：临时提取，不持久化

Tier 3: HEADER（提取 CSRF Token）
  → 示例：T@witter（需要 x-csrf-token）
  → 方式：从 meta 标签或 localStorage 提取
  → Token：每次请求时动态获取

Tier 4: INTERCEPT（拦截并注入头）
  → 示例：企业微信、加密 API
  → 方式：劫持 fetch/XHR，自动注入认证头
  → Token：由网站自己的 JS 生成

Tier 5: UI（最后手段）
  → 示例：强反爬虫网站
  → 方式：直接操作 UI，不涉及 API
  → Token：无（纯 UI 自动化）

实际案例演示

案例 1：Bilibili（COOKIE 策略）

// 用户已在 Chrome 中登录 Bilibili
// OpenCLI 执行时：

pipeline: [
  { navigate: 'https://www.bilibili.com' },  // 加载页面（Cookie 自动携带）
  { evaluate: `
    (async () => {
      const res = await fetch('https://api.bilibili.com/x/web-interface/popular', {
        credentials: 'include'  // ← 关键：复用 Cookie
      });
      return res.json();
    })()
  `}
]

// OpenCLI 不知道也不存储 Cookie
// 完全由浏览器管理

案例 2：Notion（LOCALSTORAGE 策略）

// 现代 SaaS 应用通常将 token 存在 localStorage
pipeline: [
  { navigate: 'https://www.notion.so' },
  { evaluate: `
    (async () => {
      // 从 localStorage 提取 token
      const token = localStorage.getItem('access_token');

      const res = await fetch('https://api.notion.com/v1/pages', {
        headers: {
          'Authorization': 'Bearer ' + token  // ← 临时提取
        }
      });
      return res.json();
    })()
  }
]

// token 不会被 OpenCLI 存储
// 只在执行时临时读取

案例 3：T@witter（HEADER 策略）

// T@witter 需要 CSRF token
pipeline: [
  { navigate: 'https://twitter.com' },
  { evaluate: `
    (async () => {
      // 动态提取 CSRF token
      const csrf = document.querySelector('[name="csrf-token"]')?.content;

      const res = await fetch('https://api.twitter.com/graphql/...', {
        headers: {
          'x-csrf-token': csrf,  // ← 每次动态获取
        },
        credentials: 'include'
      });
      return res.json();
    })()
  }
]

安全边界

你可能担心：这样安全吗？

OpenCLI 的安全设计：

关键原则：

OpenCLI 的角色 = 代码执行者
认证的管理者 = 浏览器本身

OpenCLI 从不：
   存储密码
   导出 Cookie
   持久化 Token
   跨域传输凭证

OpenCLI 只是：
   在浏览器环境内执行 JavaScript
   利用浏览器自动携带 Cookie 的机制
   临时读取页面可访问的数据（和网页 JS 权限相同）

类比： OpenCLI 就像浏览器的开发者工具（DevTools Console）—— 你在 Console 里执行 fetch() 也会自动携带 Cookie，但这不意味着 Console "管理"了你的 Token。OpenCLI 的权限范围和 DevTools 完全相同。

自动适配器生成：30 秒完成

OpenCLI 最强大的功能：让 AI 自动将网站转化为 CLI。

完整流程演示

$ opencli generate  --goal "hot movies"

背后发生了什么：

[1/4] 探索 API (10s)
  → 浏览器打开 douban.com
  → 网络流量
  → 捕获 3 个 JSON 请求
  → 过滤噪音（日志、埋点、心跳）
   保留 1 个有价值 API

[2/4] 分析结构 (5s)
  → API: /api/movie/hot
  → 响应: { data: { items: [...] } }
  → 字段匹配：title, director, rating
  → 参数推断：limit (从 ?count=20)
   推断完成

[3/4] 生成代码 (5s)
  → 认证策略：cookie
  → 生成管线：navigate → evaluate → map → limit
  → 保存到：~/.opencli/clis/douban/hot.js
   代码已生成

[4/4] 验证输出 (10s)
  → 执行管线
  → 返回 25 条数据
   验证通过

────────────────────────────────
 新命令已就绪！

  opencli douban hot
  opencli douban hot --limit 10 -f json
────────────────────────────────

关键技术：规则引擎而非 LLM

你可能会问：这是用 GPT 生成的吗？

答案：不是！OpenCLI 使用 100% 规则引擎，零 LLM 调用。

字段角色检测（模式匹配）：

const FIELD_ROLES = {
  title:  ['title', 'name', 'text', 'subject'],
  author: ['author', 'username', 'owner', 'up_name'],
  score:  ['score', 'likes', 'view_count', 'play'],
  time:   ['time', 'created_at', 'publish_time']
};

// 自动匹配
detectFieldRoles(['title', 'owner.name', 'stat.view'])
// → { title: 'title', author: 'owner.name', score: 'stat.view' }

能力名称推断（URL 规则）：

const url = "https://api.example.com/popular";
if (url.includes('hot') || url.includes('popular')) return 'hot';
if (url.includes('search')) return 'search';
// → 推断为 'hot'

为什么不用 LLM？

README 的承诺："Zero LLM cost — Run 10,000 times and pay nothing."

API 变更应对：多层防御

你可能担心：外部 API 会变更，适配器岂不是会失效？

OpenCLI 设计了 5 层防御机制：

第 1 层：自动修复（v1.7.0 新特性）

$ opencli bilibili hot

[第一次尝试]
  → 提取路径: data.list
   返回: null (API 改为 data.result.items)

[自动修复]
  → 重新探测 API 响应
  → 发现新路径: data.result.items
  → 更新适配器

[第二次尝试]
   成功！

成功率：80% 的 API 变更可自动修复（主要是路径变化）。

第 2 层：结构化诊断

自动修复失败时，生成详细诊断报告：

$ OPENCLI_DIAGNOSTIC=1 opencli xiaohongshu search --query "旅游" 2> diag.json

诊断报告包含：

• 错误详情（代码、消息、堆栈）
• 适配器源码（含行号）
• 浏览器状态（DOM 快照、网络请求、控制台错误）

AI Agent 可基于诊断报告自动修复，或人工快速定位问题。

第 3 层：重新生成

最简单粗暴的方法：

rm ~/.opencli/clis/xiaohongshu/search.js
opencli generate  --goal "search"

完全基于最新 API，自动适应结构变化。

第 4 层：降级到 UI 自动化

当 API 完全加密或失效：

// 从 API 方式降级到 UI 方式
pipeline: [
  { navigate: 'https://www.bilibili.com/ranking' },
  { wait: 2000 },
  { select: '.rank-item .title' },  // CSS 选择器
  { map: { title: '${{ item.textContent }}' } }
]

虽然慢且不稳定，但作为最后手段仍可用。

第 5 层：社区维护

CHANGELOG 显示活跃维护：

v1.7.3 (2026-04-15) - 2 天前
  • 修复：小红书签名 URL (#996)
  • 修复：douban ask 响应解析 (#933)

v1.7.0 (2026-04-11) - 大版本
  • 87+ 适配器更新
  • 自动修复协议

维护频率：大版本 2-3 个月，小修复 1-2 周，Issue 响应 1-3 天。

AI Agent 集成：Skills 系统

OpenCLI 不是为了替代人工，而是为了让 AI Agent 能自动化操作网站。

Skills 设计哲学

OpenCLI 提供 4 个 Skills，覆盖不同场景：

opencli-usage（基础使用）
    ↓ 命令不存在
opencli-oneshot（快速生成单个命令）
    ↓ 失败
opencli-explorer（完整探索式开发）
    ↓ 适配器失效
opencli-autofix（自动修复）

Agent 的命令发现机制

你可能好奇：Agent 是靠运行 opencli list 知道有哪些命令的吗？

答案：不是！主要靠 Skills 文档中的静态命令列表。

skills/opencli-usage/commands.md（829 行）包含所有命令的详细参考：

## Bilibili 
```bash
opencli bilibili hot --limit 10          # B站热门视频
opencli bilibili search "rust"            # 搜索视频 (query positional)
opencli bilibili me                       # 当前用户信息

Arguments:

• --limit - Number of items (default: 20)
• -f, --format - Output format: json, yaml, csv, table

**优势**：

| 维度 | Skills 文档 | `opencli list` |
|------|------------|----------------|
| **加载速度** | 一次性（加载 Skill 时） | 每次运行（200-500ms） |
| **信息丰富度** | 包含示例、参数说明 | 只有命令名 |
| **离线能力** |  已在上下文中 |  需要执行 |
| **搜索能力** |  语义搜索（按能力、场景） |  精确匹配 |

### 自主决策边界

Agent **可以且应该**自动使用 `opencli generate`，但有明确规则：

** 自动执行**：
- 用户明确要求："帮我生成 xxx.com 的 CLI"
- 适配器失效：自动修复（透明，用户无感知）

**️ 询问用户**：
- 间接需求："给我 newsite.com 的数据"（该网站无适配器）

** 不自动执行**：
- 用户只是问问题："OpenCLI 支持哪些网站？"
- 风险场景：银彳、支付等敏感网站

**设计原则**：

自动化（优先尝试）

• 人机协作（必要时询问）
• 透明修复（用户无感知）
• 明确边界（不越权）

---

## 实战案例：从网页到 CLI

让我们通过真实案例理解完整流程。

### 场景：用户想获取小红书搜索结果

**传统方案**：
```python
# 需要编写 100+ 行代码
from selenium import webdriver
driver = webdriver.Chrome()
driver.get('https://www.xiaohongshu.com')
# 处理登录、反爬虫、懒加载...
# 3 小时后放弃

OpenCLI 方案：

# 方式 1：使用现成命令（已内置）
opencli xiaohongshu search --query "旅游" -f json

# 方式 2：如果没有，30 秒生成
opencli generate  --goal "search"

拦截过程解析

当执行 opencli xiaohongshu search --query "旅游" 时：

1. 浏览器打开 xiaohongshu.com
2. 所有网络请求
3. 捕获到 15 个 JSON 请求：
    /api/sns/web/v1/search/notes?keyword=旅游
    /api/sns/web/v1/user/info (单条，过滤)
    /fe_api/burdock/weixin/v2/shield (噪音，过滤)
   ...

4. 分析有价值请求：
   URL: /api/sns/web/v1/search/notes
   响应: { data: { items: [...] } }
   字段: id, title, user.nickname, cover.url

5. 执行管线：
   navigate → evaluate (fetch API) → map (字段映射) → limit

6. 返回结构化数据（JSON/CSV/YAML/Table）

关键点：

• 不需要解析 HTML
• 直接拿 JSON 数据
• 字段路径明确（data.items[].title）
• 复用登录态（Cookie 自动携带）

对比分析：OpenCLI vs 传统方案

适用场景：

推荐使用 OpenCLI：

• 需要快速访问多个网站数据
• CI/CD 中的自动化采集
• AI Agent 集成网站能力
• 需要统一的 CLI 接口

不推荐使用 OpenCLI：

• 需要极高性能（毫秒级响应）
• 深度定制反爬虫逻辑
• 纯静态网站（无 JSON API）

总结与展望

OpenCLI 的核心价值可以用三个关键词概括：

1. 零成本

传统方案：
  开发时间 30 分钟 × $50/小时 = $25
  T@witter API: $100/月
  年成本 = $1225

OpenCLI：
  开发时间 30 秒
  运行成本 $0
  年成本 = $0

节省 100% 

2. 零维护

传统爬虫：
  网站改版 → 代码失效 → 人工修复（2 小时）
  发生频率：每季度 1 次
  年维护成本：8 小时

OpenCLI：
  API 变更 → 自动修复（80%）→ 人工介入（20%）
  年维护成本：1.6 小时

节省 80% 时间 

3. AI 原生

OpenCLI 从设计之初就是为 AI Agent 准备的：

• 确定性输出：JSON/YAML/CSV，AI 直接解析
• 统一接口：87+ 网站，同一套命令规范
• Skills 系统：Agent 可自动发现、使用、生成命令
• 自动修复：适配器失效时 AI 自动诊断修复

未来方向

随着 AI Agent 的普及，OpenCLI 这样的工具将不再是可选项，而是基础设施：

1. 适配器生态：社区贡献的适配器市场
2. 自动回归测试：每日验证所有适配器可用性
3. 跨平台支持：Firefox、Safari、云端浏览器
4. 可视化调试器：图形化管线编辑和实时预览

快速开始

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

# 2. 安装浏览器扩展
# 下载 
# 在 chrome://extensions 加载解压后的文件夹

# 3. 验证
opencli doctor

# 4. 使用
opencli bilibili hot --limit 5
opencli twitter trending
opencli xiaohongshu search --query "AI"

# 5. 生成新命令
opencli generate  --goal "hot posts"

OpenCLI 代表了 Web 自动化的新范式 —— 从"手动编写爬虫"到"自动生成 CLI"，从"付费 API"到"零成本运行"。通过巧妙的架构设计和规则引擎，它在成本、性能和易用性之间找到了最佳平衡点。

更重要的是，作为 AI 原生工具，OpenCLI 正在成为连接 Web 和 AI Agent 的桥梁 —— 让任何网站都能成为 Agent 的工具箱。