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

GitHub : github.com/jackwener/o...

引言：Web 数据访问的困境

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

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

传统方案的痛点：

方案	问题
手动爬虫	每个网站一套代码、反爬虫升级就失效、维护成本高
付费 API	昂贵、功能受限、小网站根本没有 API
Puppeteer	重量级、启动慢（3-5 秒）、无法复用登录态

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

bash 复制代码

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

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

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

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

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

传统爬虫的困境

css 复制代码

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

问题在于：

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

OpenCLI 的巧妙设计

css 复制代码

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

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

传统方式（HTML 解析）：

javascript 复制代码

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

OpenCLI 方式（JSON 拦截）：

javascript 复制代码

// ✅ 稳定可靠
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 更稳定？

维度	HTML 结构	JSON API
变更频率	高（UI 改版就变）	低（有版本控制）
数据位置	模糊（需要猜测选择器）	明确（`data.list.items`）
向后兼容	无保证	通常有兼容策略
反爬虫	检测 DOM 操作	复用登录态，不被检测

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

架构设计：分层通信模型

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

传统方案的困境

方案	问题
Puppeteer	启动独立浏览器、无法复用登录态、每次冷启动 3-5 秒
CDP 直连	需要 Chrome 启动时加 `--remote-debugging-port`、安全风险

OpenCLI 的三层架构

scss 复制代码

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

关键创新：工作区隔离

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

bash 复制代码

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

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

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

css 复制代码

┌────────────────────────┐
│  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 根据网站的认证复杂度，自动选择最合适的策略：

yaml 复制代码

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

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

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

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

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

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

实际案例演示

javascript 复制代码

// 用户已在 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 策略）

javascript 复制代码

// 现代 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 存储
// 只在执行时临时读取

javascript 复制代码

// Twitter 需要 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 的安全设计：

层面	防护措施
凭证存储	❌ 不存储任何 Cookie、Token、密码
通信隔离	✅ Origin 检查 + 自定义头验证（防 CSRF）
日志脱敏	✅ 自动过滤 Authorization、Cookie 等敏感头
会话隔离	✅ 每个工作区独立（不会相互污染）
权限最小化	✅ 只在浏览器上下文中读取，不跨域传输

关键原则：

复制代码

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

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

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

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

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

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

完整流程演示

bash 复制代码

$ opencli generate https://www.douban.com --goal "hot movies"

背后发生了什么：

scss 复制代码

[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 调用。

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

typescript 复制代码

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 规则）：

typescript 复制代码

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

为什么不用 LLM？

维度	规则引擎	LLM
成本	免费	$0.01-0.1/次
速度	毫秒级	秒级
确定性	100%	有随机性
可调试	可追踪	黑盒

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

API 变更应对：多层防御

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

OpenCLI 设计了 5 层防御机制：

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

bash 复制代码

$ opencli bilibili hot

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

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

[第二次尝试]
  ✓ 成功！

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

第 2 层：结构化诊断

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

bash 复制代码

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

诊断报告包含：

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

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

第 3 层：重新生成

最简单粗暴的方法：

bash 复制代码

rm ~/.opencli/clis/xiaohongshu/search.js
opencli generate https://www.xiaohongshu.com --goal "search"

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

第 4 层：降级到 UI 自动化

当 API 完全加密或失效：

javascript 复制代码

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

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

第 5 层：社区维护

CHANGELOG 显示活跃维护：

scss 复制代码

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，覆盖不同场景：

markdown 复制代码

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

Agent 的命令发现机制

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

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

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

markdown 复制代码

## 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

markdown 复制代码

**优势**：

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

### 自主决策边界

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

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

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

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

**设计原则**：

自动化（优先尝试）

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

yaml 复制代码

---

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

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

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

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

OpenCLI 方案：

bash 复制代码

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

# 方式 2：如果没有，30 秒生成
opencli generate https://www.xiaohongshu.com --goal "search"

拦截过程解析

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

bash 复制代码

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 传统方案

维度	手动爬虫	Puppeteer	付费 API	OpenCLI
开发成本	30-60 分钟/网站	20-40 分钟	注册+集成	30 秒（自动生成）
运行成本	免费	免费	$100+/月	免费
登录态	需手动管理	独立会话	API Key	复用浏览器
维护成本	高（页面改版就失效）	高	低（官方维护）	中（自动修复 + 社区）
启动速度	快	慢（3-5 秒）	快	快（0.5 秒）
确定性	低	低	高	高（基于 API）
AI 友好	❌	❌	⚠️	✅（Skills 系统）

适用场景：

推荐使用 OpenCLI：

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

不推荐使用 OpenCLI：

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

总结与展望

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

1. 零成本

bash 复制代码

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

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

节省 100% 💰

2. 零维护

erlang 复制代码

传统爬虫：
  网站改版 → 代码失效 → 人工修复（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 这样的工具将不再是可选项，而是基础设施：

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

快速开始

bash 复制代码

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

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

# 3. 验证
opencli doctor

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

# 5. 生成新命令
opencli generate https://yoursite.com --goal "hot posts"

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

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

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