qiaomu-opencli-explorer

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha ccd4e8bab454 · 23 Oct 2026Report an issue or request a re-scan

• Publisherjoeseesun GitHub userOwner of the repository this skill is read from
• Source folderjoeseesun/opencli-skill/qiaomu-opencli-explorerThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdictccd4e8bab454A new audit runs when the source changes
• Repository statusNot archivedLast push 196 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Use when creating a new OpenCLI adapter from scratch, adding support for a new website or platform, exploring a site's API endpoints via browser DevTools, or when a user asks to automatically generate a CLI for a…

---
name: qiaomu-opencli-explorer
description: Use when creating a new OpenCLI adapter from scratch, adding support for a new website or platform, exploring a site's API endpoints via browser DevTools, or when a user asks to automatically generate a CLI for a website (e.g. "帮我生成 xxx.com 的 cli"). Covers automated generation, API discovery workflow, authentication strategy selection, TS adapter writing, and testing.
author: joeseesun
upstream: jackwener/opencli
tags: [opencli, adapter, browser, api-discovery, cli, web-scraping, automation, generate]
---

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

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

> [!TIP]
> **只想为一个具体页面快速生成一个命令?** 看 [opencli-oneshot skill](../opencli-oneshot/SKILL.md)(~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 探索工作流(必须遵循)

| 步骤 | 工具 | 做什么 |
|------|------|--------|
| 0. 打开浏览器 | `browser_navigate` | 导航到目标页面 |
| 1. 观察页面 | `browser_snapshot` | 观察可交互元素(按钮/标签/链接) |
| 2. 首次抓包 | `browser_network_requests` | 筛选 JSON API 端点,记录 URL pattern |
| 3. 模拟交互 | `browser_click` + `browser_wait_for` | 点击"字幕""评论""关注"等按钮 |
| 4. 二次抓包 | `browser_network_requests` | 对比步骤 2,找出新触发的 API |
| 5. 验证 API | `browser_evaluate` | `fetch(url, {credentials:'include'})` 测试返回结构 |
| 6. 写代码 | — | 基于确认的 API 写适配器 |

### 常犯错误

| ❌ 错误做法 | ✅ 正确做法 |
|------------|------------|
| 只用 `opencli explore` 命令,等结果自动出来 | 用浏览器工具打开页面,主动浏览 |
| 直接在代码里 `fetch(url)`,不看浏览器实际请求 | 先在浏览器中确认 API 可用,再写代码 |
| 页面打开后直接抓包,期望所有 API 都出现 | 模拟点击交互(展开评论/切换标签/加载更多) |
| 遇到 HTTP 200 但空数据就放弃 | 检查是否需要 Wbi 签名或 Cookie 鉴权 |
| 完全依赖 `__INITIAL_STATE__` 拿所有数据 | `__INITIAL_STATE__` 只有首屏数据,深层数据要调 API |

### 实战成功案例: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,自动分析网站网络请求:

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

输出到 `.opencli/explore/mysite/`:

| 文件 | 内容 |
|------|------|
| `manifest.json` | 站点元数据、框架检测(Vue2/3、React、Next.js、Pinia、Vuex) |
| `endpoints.json` | 已发现的 API 端点,按评分排序,含 URL pattern、方法、响应类型 |
| `capabilities.json` | 推理出的功能(`hot`、`search`、`feed`...),含置信度和推荐参数 |
| `auth.json` | 认证方式检测(Cookie/Header/无认证),策略候选列表 |

### 1b. 手动抓包验证

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

```bash
# 在浏览器中打开目标页面,观察网络请求
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 自动检测前端框架。如果需要手动确认:

```bash
# 在已打开目标网站的情况下
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` 命令自动探测:

```bash
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 自动化,最后手段)
```

### 各策略对比

| Tier | 策略 | 速度 | 复杂度 | 适用场景 | 实例 |
|------|------|------|--------|---------|------|
| 1 

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/joeseesun/opencli-skill
git -C opencli-skill checkout ccd4e8bab454

Works in

1. 2026-10-23
   ✓SAFE B 89 / 100

   first audit · source ccd4e8bab454

Questions about qiaomu-opencli-explorer

• github.com/joeseesun/opencli-skill/tree/main/qiaomu-opencli-expl — the audited source at commit ccd4e8bab454 and every finding aboveObserved · 23 Oct 2026

Spotted something wrong? Report a correction · Methodology