Menu
适配器探索式开发 — 从零创建 OpenCLI 适配器，支持新网站/平台。 涵盖 API 发现、认证策略选择、TS 适配器编写和测试验证。 当用户要求为网站生成 CLI、探索网站 API 时使用。
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/changzhi777/SpideHarness --skill spide-explorerThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Based on SOC occupation classification
Showing SKILL.md
| name | spide-explorer |
| description | 适配器探索式开发 — 从零创建 OpenCLI 适配器，支持新网站/平台。 涵盖 API 发现、认证策略选择、TS 适配器编写和测试验证。 当用户要求为网站生成 CLI、探索网站 API 时使用。 |
| category | meta |
从零到发布：API 发现 → 认证策略 → 写适配器 → 测试验证。
npm install -g @jackwener/opencli
opencli doctor
| 情况 | 走这里 |
|---|---|
| 只要为一个具体页面生成一个命令 | spide-oneshot skill |
| 想先让机器自动试一遍 | 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
必须通过浏览器打开目标网站去探索！ 不要只靠静态分析。 很多 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 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.ts
.json)：Reddit、雪球等，URL 加 .json 直接拿 REST 数据__INITIAL_STATE__)：SSR 站点（B站、小红书）首页数据挂载在 window 上installInterceptor 抓包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});
})()"
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 主流）
→ ❌ 加 CSRF header 后能拿到？
→ ✅ Tier 3: header（如 Twitter ct0 + Bearer）
→ ❌ 网站有 Pinia/Vuex Store？
→ ✅ Tier 4: intercept（Store Action + XHR 拦截）
→ ❌ Tier 5: ui（UI 自动化，最后手段）
| Tier | 策略 | 速度 | 适用场景 | 实例 |
|---|---|---|---|---|
| 1 | public | ~1s | 公开 API，无需登录 | Hacker News, V2EX |
| 2 | cookie | ~7s | Cookie 认证即可 | Bilibili, Zhihu, Reddit |
| 2.5 | localStorage Bearer | ~7s | JWT 存 localStorage | Slock, Linear, Notion |
| 3 | header | ~7s | 需要 CSRF token 或 Bearer | Twitter GraphQL |
| 4 | intercept | ~10s | 请求有复杂签名 | 小红书 (Pinia + XHR) |
| 5 | ui | ~15s+ | 无 API，纯 DOM 解析 | 遗留网站 |
ls clis/<site>/ # 看同站点已有什么
cat clis/<site>/feed.ts # 读最相似的那个
改 3 处即可：name、API URL、字段映射。
所有适配器统一使用 TypeScript cli() API，放入 clis/<site>/<name>.ts 即自动注册。
完整模板（Tier 1~4）、分页模式、错误处理规范 → adapter-templates.md
级联请求、tap 调试、抗变更模式 → advanced-patterns.md
手动录制方案 → record-workflow.md
构建通过 ≠ 功能正常。必须实际运行并确认输出。
# Repo 贡献：build 后直接运行
npm run build
opencli list | grep mysite # 确认注册
opencli mysite mycommand --limit 3 -v # 实际运行
# 私人 adapter（~/.opencli/clis/）：一键验证
opencli browser verify <site>/<name>
Done 标准：命令运行后返回非空表格，且字段符合预期。
| 陷阱 | 表现 | 解决方案 |
|---|---|---|
缺少 navigate | Target page context 错误 | 在 evaluate 前加 page.goto() |
缺少 strategy: public | 公开 API 也启动浏览器 | 加 strategy: Strategy.PUBLIC + browser: false |
| 风控被拦截（伪 200） | JSON 里核心数据是空串 | 必须断言！返回 { error, help } 提示重新登录 |
| SPA 返回 HTML | fetch('/api/xxx') 返回 <!DOCTYPE html> | API 在独立 domain，搜 JS bundle 找 baseURL |
| 文件写错目录 | opencli list 找不到命令 | Repo 放 clis/<site>/ + build；私用放 ~/.opencli/clis/<site>/ |
| TS evaluate 格式 | () => {} 报错 | 必须用 IIFE：(async () => { ... })() |
| Cookie 过期 | 返回 401 / 空数据 | 在浏览器里重新登录目标站点 |
# 一键：探索 → 分析 → 合成 → 注册
opencli generate https://www.example.com --goal "hot"
# 或分步：
opencli explore https://www.example.com --site mysite
opencli synthesize mysite
opencli verify mysite/hot --smoke