Opencli Explorer

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

> 从零到发布：API 发现 → 认证策略 → 写适配器 → 测试验证。

## 先选路径

| 情况 | 走这里 |
|------|--------|
| 只要为一个具体页面生成一个命令 | [opencli-oneshot skill](../opencli-oneshot/SKILL.md) |
| 想先让机器自动试一遍 | `opencli generate <url> [--goal <goal>]`，失败再回来 |
| 新站点 / 多个命令 / oneshot 卡住了 | 继续往下读本文档 |
| 产物要提 PR | 本文档 + `clis/<site>/` + `npm run build` |
| 只是本地私用，不提 PR | 本文档 + `~/.opencli/clis/<site>/` |

---

## 核心流程

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

---

## AI Agent 必读：必须用浏览器探索

> [!CAUTION]
> **必须通过浏览器打开目标网站去探索！** 不要只靠静态分析。
> 很多 API 是**懒加载**的——字幕、评论、关注列表等深层数据只有点击后才触发。

### 浏览器探索工作流

| 步骤 | 命令 | 做什么 |
|------|------|--------|
| 0. 打开页面 | `opencli browser open <url>` | 导航到目标页面，开始捕获 |
| 1. 观察元素 | `opencli browser state` | 查看可交互元素（按钮/标签），带 `[N]` 索引 |
| 2. 首次抓包 | `opencli browser network` | 列出捕获的 JSON API 请求 |
| 3. 模拟交互 | `opencli browser click <N>` | 点击按钮触发懒加载 API |
| 4. 二次抓包 | `opencli browser network` | 找出新触发的 API |
| 5. 查看响应 | `opencli browser network --detail <N>` | 查看完整响应体 |
| 6. 验证 API | `opencli browser eval "fetch(...).then(r=>r.json())"` | 确认 API 可复现 |

### 常犯错误

| ❌ 错误做法 | ✅ 正确做法 |
|------------|------------|
| 只用 `opencli explore`，等结果出来 | 用 `opencli browser open` 主动浏览 |
| 不看浏览器请求，直接写代码 | 先 `opencli browser network` 确认 API |
| 打开页面后直接抓包 | 用 `opencli browser click` 模拟交互触发懒加载 |
| HTTP 200 但数据为空就放弃 | 检查是否需要签名或 Cookie 鉴权（伪 200 风控） |
| 依赖 `__INITIAL_STATE__` 拿所有数据 | `__INITIAL_STATE__` 只有首屏数据，深层要调 API |
| `opencli browser network` 为空 | 重新 `open` 刷新捕获；或检查 API 是否在独立 domain |

### 实战示例：5 分钟实现「关注列表」适配器

```bash
opencli browser open https://space.bilibili.com/{uid}/fans/follow
opencli browser network
#   [0] GET 200 /x/relation/followings?vmid={uid}&pn=1&ps=24
opencli browser network --detail 0
# 确认数据结构：{ code: 0, data: { total: 1342, list: [{mid, uname, ...}] } }
opencli browser eval "fetch('/x/relation/followings?vmid=137702077&pn=1&ps=5', {credentials:'include'}).then(r=>r.json())"
# → 有数据，结论：Tier 2 Cookie，写 following.js
```

---

## Step 1: 发现 API

### 主路径：浏览器主动探索

用上方工作流打开页面 → 模拟交互 → 抓包。关注：

- **URL pattern**：`/api/v2/hot?limit=20` → 要调用的端点
- **Method**：GET / POST
- **Request Headers**：Cookie? Bearer? 自定义签名头（X-s、X-t）?
- **Response Body**：数据路径（`data.items`、`data.list`）

### 高阶捷径（按优先级尝试）

1. **后缀爆破法 (`.json`)**：Reddit、雪球等，URL 加 `.json` 直接拿 REST 数据（Tier 2 秒杀）
2. **全局状态法 (`__INITIAL_STATE__`)**：SSR 站点（B站、小红书）首页数据挂载在 window 上
3. **主动交互触发法**：懒加载 API 需要点击按钮（"CC"、"展开全部"）才触发
4. **框架 Store 截断**：Vue + Pinia 站点，Store Action 代替你完成签名
5. **XHR/Fetch 拦截**：最后手段，用 `installInterceptor` 抓包

### 框架检测

```bash
opencli browser eval "(()=>{
  const vue3 = !!document.querySelector('#app')?.__vue_app__;
  const pinia = vue3 && !!document.querySelector('#app').__vue_app__.config.globalProperties.\$pinia;
  const react = !!window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
  return JSON.stringify({vue3, pinia, react});
})()"
```

Vue + Pinia → 可用 Store Action 绕过签名（Tier 4）。

---

## Step 2: 选择认证策略

```bash
opencli cascade https://api.example.com/hot   # 自动探测
```

### 策略决策树

```
fetch(url) 直接能拿到？
  → ✅ Tier 1: public（browser: false，~1s）
  → ❌ fetch(url, {credentials:'include'}) 带 Cookie 能拿到？
       → ✅ Tier 2: cookie（最常见）
       → ❌ localStorage 有 token，Bearer header 能拿到？
              → ✅ Tier 2.5: localStorage Bearer（现代 SaaS 主流）