Qiaomu Opencli Explorer

CLI-EXPLORER — 适配器探索式开发完全指南

本文档教你（或 AI Agent）如何为 OpenCLI 添加一个新网站的命令。 从零到发布，覆盖 API 发现、方案选择、适配器编写、测试验证全流程。

[!TIP] 只想为一个具体页面快速生成一个命令？ 看 opencli-oneshot skill（~150 行，4 步搞定）。 本文档适合从零探索一个新站点的完整流程。

[!TIP] 想要全自动生成？ 直接运行 opencli generate <url> [--goal <goal>]，内部会自动走完 explore → synthesize → cascade → verify 全流程。 返回 SkillOutput（success / blocked / needs-human-check）。如果自动生成失败或需要人工介入，再按本文档的手动流程继续。

AI Agent 开发者必读：用浏览器探索

[!CAUTION] 你（AI Agent）必须通过浏览器打开目标网站去探索！ 不要只靠 opencli explore 命令或静态分析来发现 API。 你拥有浏览器工具，必须主动用它们浏览网页、观察网络请求、模拟用户交互。

为什么？

很多 API 是懒加载的（用户必须点击某个按钮/标签才会触发网络请求）。字幕、评论、关注列表等深层数据不会在页面首次加载时出现在 Network 面板中。如果你不主动去浏览和交互页面，你永远发现不了这些 API。

AI Agent 探索工作流（必须遵循）

常犯错误

实战成功案例：5 分钟实现「关注列表」适配器

以下是用上述工作流实际发现 Bilibili 关注列表 API 的完整过程：

1. browser_navigate → https://space.bilibili.com/{uid}/fans/follow
2. browser_network_requests → 发现:
   GET /x/relation/followings?vmid={uid}&pn=1&ps=24  →  [200]
   GET /x/relation/stat?vmid={uid}                    →  [200]
3. browser_evaluate → 验证 API:
   fetch('/x/relation/followings?vmid=137702077&pn=1&ps=5', {credentials:'include'})
   → { code: 0, data: { total: 1342, list: [{mid, uname, sign, ...}] } }
4. 结论：标准 Cookie API，无需 Wbi 签名
5. 写 following.ts → 一次构建通过

关键决策点：

• 直接访问 fans/follow 页面（不是首页），页面加载就会触发 following API
• 看到 URL 里没有 /wbi/ → 不需要签名 → 直接用 fetchJson 而非 apiGet
• API 返回 code: 0 + 非空 list → Tier 2 Cookie 策略确认

核心流程

 ┌─────────────┐     ┌─────────────┐     ┌──────────────┐     ┌────────┐
 │ 1. 发现 API  │ ──▶ │ 2. 选择策略  │ ──▶ │ 3. 写适配器   │ ──▶ │ 4. 测试 │
 └─────────────┘     └─────────────┘     └──────────────┘     └────────┘
   explore             cascade             TS (cli() API)       run + verify

Step 1: 发现 API

1a. 自动化发现（推荐）

OpenCLI 内置 Deep Explore，自动分析网站网络请求：

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

输出到 .opencli/explore/mysite/：

1b. 手动抓包验证

Explore 的自动分析可能不完美，用 verbose 模式手动确认：

# 在浏览器中打开目标页面，观察网络请求
opencli explore https://www.example.com --site mysite -v

# 或直接用 evaluate 测试 API
opencli bilibili hot -v   # 查看已有命令的 pipeline 每步数据流

关注抓包结果中的关键信息：

• URL pattern: /api/v2/hot?limit=20 → 这就是你要调用的端点
• Method: GET / POST
• Request Headers: Cookie? Bearer? 自定义签名头（X-s、X-t）?
• Response Body: JSON 结构，特别是数据在哪个路径（data.items、data.list）

1c. 高阶 API 发现捷径法则 (Heuristics)

在开始死磕复杂的抓包拦截之前，按照以下优先级进行尝试：

1. 后缀爆破法 (`.json`): 像 Reddit 这样复杂的网站，只要在其 URL 后加上 .json（例如 /r/all.json），就能在带 Cookie 的情况下直接利用 fetch 拿到极其干净的 REST 数据（Tier 2 Cookie 策略极速秒杀）。另外如功能完备的雪球 (xueqiu) 也可以走这种纯 API 的方式极简获取，成为你构建简单 TS pipeline 适配器的黄金标杆。
2. 全局状态查找法 (`__INITIAL_STATE__`): 许多服务端渲染 (SSR) 的网站（如小红书、Bilibili）会将首页或详情页的完整数据挂载到全局 window 对象上。与其去拦截网络请求，不如直接 page.evaluate('() => window.__INITIAL_STATE__') 获取整个数据树。
3. 主动交互触发法 (Active Interaction): 很多深层 API（如视频字幕、评论下的回复）是懒加载的。在静态抓包找不到数据时，尝试在 evaluate 步骤或手动打断点时，主动去点击（Click）页面上的对应按钮（如"CC"、"展开全部"），从而诱发隐藏的 Network Fetch。
4. 框架探测与 Store Action 截断: 如果站点使用 Vue + Pinia，可以使用 tap 步骤调用 action，让前端框架代替你完成复杂的鉴权签名封装。
5. 底层 XHR/Fetch 拦截: 最后手段，当上述都不行时，使用 TypeScript 适配器进行无侵入式的请求抓取。

1d. 框架检测

Explore 自动检测前端框架。如果需要手动确认：

# 在已打开目标网站的情况下
opencli evaluate "(()=>{
  const vue3 = !!document.querySelector('#app')?.__vue_app__;
  const vue2 = !!document.querySelector('#app')?.__vue__;
  const react = !!window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
  const pinia = vue3 && !!document.querySelector('#app').__vue_app__.config.globalProperties.\$pinia;
  return JSON.stringify({vue3, vue2, react, pinia});
})()"

Vue + Pinia 的站点（如小红书）可以直接通过 Store Action 绕过签名。

Step 2: 选择认证策略

OpenCLI 提供 5 级认证策略。使用 cascade 命令自动探测：

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

策略决策树

直接 fetch(url) 能拿到数据？
  → ✅ Tier 1: public（公开 API，不需要浏览器）
  → ❌ fetch(url, {credentials:'include'}) 带 Cookie 能拿到？
       → ✅ Tier 2: cookie（最常见，evaluate 步骤内 fetch）
       → ❌ → 加上 Bearer / CSRF header 后能拿到？
              → ✅ Tier 3: header（如 Twitter ct0 + Bearer）
              → ❌ → 网站有 Pinia/Vuex Store？
                     → ✅ Tier 4: intercept（Store Action + XHR 拦截）
                     → ❌ Tier 5: ui（UI 自动化，最后手段）

各策略对比

Step 2.5: 准备工作（写代码之前）

先找模板：从最相似的现有适配器开始

不要从零开始写。先看看同站点已有哪些适配器：

ls clis/<site>/    # 看看已有什么
cat clis/<site>/feed.ts   # 读最相似的那个

最高效的方式是 复制最相似的适配器，然后改 3 个地方：

1. name → 新命令名
2. API URL → 你在 Step 1 发现的端点
3. 字段映射 → 对应新 API 的字段

平台 SDK 速查表

写 TS 适配器之前，先看看你的目标站点有没有现成的 helper 函数可以复用：

Bilibili (clis/bilibili/utils.ts)

如何判断需不需要 `apiGet`？看 Network 请求 URL：

• 含 /wbi/ 或 w_rid= → 必须用 apiGet(..., { signed: true })
• 不含 → 直接用 fetchJson

其他站点（Twitter、小红书等）暂无专用 SDK，直接用 page.evaluate + fetch 即可。

Step 3: 编写适配器

适配器格式：统一使用 TypeScript

所有适配器统一使用 TypeScript cli() API。YAML adapter 格式已不再支持。

所有新适配器 → TypeScript (clis/<site>/<name>.ts)，保存即自动动态注册

通用模式：分页 API

很多 API 使用 pn（页码）+ ps（每页数量）分页。标准处理模式：

args: [
  { name: 'page', type: 'int', required: false, default: 1, help: '页码' },
  { name: 'limit', type: 'int', required: false, default: 50, help: '每页数量 (最大 50)' },
],
func: async (page, kwargs) => {
  const pn = kwargs.page ?? 1;
  const ps = Math.min(kwargs.limit ?? 50, 50); // 尊重 API 的 ps 上限
  const payload = await fetchJson(page,
    `https://api.example.com/list?pn=${pn}&ps=${ps}`
  );
  return payload.data?.list || [];
},