用途
本技能是一份适配器探索式开发的完整指南，用于教会开发者或 AI Agent 为 OpenCLI 添加一个新网站的命令。文档从零到发布，覆盖 API 发现、方案选择、适配器编写、测试验证全流程。若只想为一个具体页面快速生成命令，可参考 opencli-oneshot skill（约 150 行、4 步）；若想要全自动生成，可运行 opencli generate <url> [--goal <goal>]，其内部会自动完成 explore → synthesize → cascade → verify 全流程，并返回 SkillOutput（success / blocked / needs-human-check）。自动生成失败或需人工介入时，再按本文档的手动流程继续。
主要能力
浏览器探索工作流
文档强调 AI Agent 必须通过浏览器打开目标网站进行探索，不能只靠 opencli explore 命令或静态分析来发现 API。原因在于许多 API 是懒加载的，例如字幕、评论、关注列表等深层数据不会在页面首次加载时出现在 Network 面板中，必须主动浏览和交互才能发现。
给出的探索步骤为： 0. 打开浏览器（browser_navigate），导航到目标页面；
- 观察页面（browser_snapshot），观察可交互元素；
- 首次抓包（browser_network_requests），筛选 JSON API 端点并记录 URL pattern；
- 模拟交互（browser_click + browser_wait_for），点击「字幕」「评论」「关注」等按钮；
- 二次抓包，对比步骤 2 找出新触发的 API；
- 验证 API（browser_evaluate），用 fetch(url, {credentials:'include'}) 测试返回结构；
- 基于确认的 API 写代码。
文档还列出常见错误与正确做法的对比，例如不要只用 opencli explore 等结果自动出来，而应用浏览器工具主动浏览；不要直接在代码里 fetch(url) 而不看浏览器实际请求；不要遇到 HTTP 200 但空数据就放弃，应检查是否需要 Wbi 签名或 Cookie 鉴权；不要完全依赖 INITIAL_STATE 拿所有数据，因其只有首屏数据。
文档以 Bilibili「关注列表」适配器为实战成功案例，演示了从导航到 fans/follow 页面、抓包发现 following 与 stat 接口、用 evaluate 验证 API、判断无需 Wbi 签名、到写出 following.ts 一次构建通过的全过程，并总结关键决策点：直接访问 fans/follow 页面可触发 following API；URL 中没有 /wbi/ 即不需要签名，应直接用 fetchJson 而非 apiGet；返回 code: 0 且 list 非空即确认 Tier 2 Cookie 策略。
核心流程
核心流程分为四步：1. 发现 API（explore）；2. 选择策略（cascade）；3. 写适配器（TypeScript cli() API）；4. 测试（run + verify）。
Step 1 发现 API 包括：自动化发现（opencli explore <url> --site <site>，输出 manifest.json、endpoints.json、capabilities.json、auth.json 到 .opencli/explore/<site>/）；手动抓包验证（opencli explore -v 或 opencli bilibili hot -v 查看每步数据流），关注 URL pattern、Method、Request Headers、Response Body。
还给出高阶 API 发现捷径法则：后缀爆破法（如在 URL 后加 .json，如 Reddit 的 /r/all.json，可在带 Cookie 情况下直接 fetch 拿到干净 REST 数据）；全局状态查找法（SSR 网站如小红书、Bilibili 会把数据挂到 window.INITIAL_STATE，可用 page.evaluate 获取）；主动交互触发法（点击「CC」「展开全部」等诱发隐藏请求）；框架探测与 Store Action 截断（Vue + Pinia 站点可调用 action 让前端完成鉴权签名）；底层 XHR/Fetch 拦截（最后手段）。文档还给出框架检测的 evaluate 代码示例，用于判断 Vue3、Vue2、React、Pinia。
认证策略选择
OpenCLI 提供 5 级认证策略，可用 opencli cascade <url> 自动探测。决策树为：直接 fetch(url) 能拿到数据则 Tier 1 public；带 Cookie 能拿到则 Tier 2 cookie；加 Bearer / CSRF header 能拿到则 Tier 3 header；网站有 Pinia/Vuex Store 则 Tier 4 intercept；否则 Tier 5 ui（UI 自动化，最后手段）。
各策略对比：Tier 1 public 约 1s，最简，适用公开 API（Hacker News、V2EX）；Tier 2 cookie 约 7s，简单，适用 Cookie 认证（Bilibili、Zhihu、Reddit）；Tier 3 header 约 7s，中等，适用需要 CSRF token 或 Bearer（Twitter GraphQL）；Tier 4 intercept 约 10s，较高，适用请求有复杂签名（小红书 Pinia + XHR）；Tier 5 ui 约 15s+，最高，适用无 API、纯 DOM 解析的遗留网站。
编写适配器
文档说明所有适配器统一使用 TypeScript cli() API，YAML adapter 格式已不再支持。新适配器放在 clis/<site>/<name>.ts，保存即自动动态注册。文档按场景给出模式对应示例：简单 fetch + 数据映射（v2ex/hot.ts、hackernews/top.ts）；navigate + evaluate(fetch) + 数据映射（zhihu/hot.ts）；Pinia Store Action 触发（xiaohongshu/feed.ts、xiaohongshu/notifications.ts）；复杂 JS 逻辑（xiaohongshu/me.ts、bilibili/me.ts）；XHR 拦截 + 签名（xiaohongshu/search.ts）；GraphQL / 分页 / Wbi 签名（bilibili/search.ts、twitter/search.ts）。
文档给出分页 API 的通用模式（page 与 limit 参数，ps 上限通常 20~50，超过会静默截断或报错），并提供 Tier 1 公开 API 模板（v2ex/hot.ts）、Tier 2 Cookie 认证模板（zhihu/hot.ts）、带搜索参数的进阶模板（zhihu/search.ts）、Tier 4 Store Action + Interceptor 模板（xiaohongshu/notifications.ts）、Tier 3 Header 认证模板（twitter/search.ts）、Tier 4 XHR/Fetch 双重拦截模板（xiaohongshu/user.ts）等完整代码。
其中关键点包括：page.evaluate 内的 fetch 运行在浏览器页面内，自动携带 credentials: 'include'，无需手动处理 Cookie；拦截核心思路是不自己构造签名，而用 installInterceptor 劫持网站自身的 XMLHttpRequest 和 fetch，让网站发请求并在底层取出解析好的 response.json()。
文档还提供平台 SDK 速查表，例如 Bilibili 的 clis/bilibili/utils.ts 中 fetchJson、apiGet、getSelfUid、resolveUid、wbiSign、stripHtml 等函数的用途与使用时机，并说明判断是否需要 apiGet 的方法：URL 含 /wbi/ 或 w_rid= 时必须用 apiGet(..., { signed: true })，不含则直接用 fetchJson。其他站点（Twitter、小红书等）暂无专用 SDK，直接用 page.evaluate + fetch。
测试验证
文档强调构建通过不等于功能正常，npm run build 只验证 TypeScript 语法，不验证运行时行为；每个新命令必须实际运行并确认输出正确后才算完成。必做清单包括：npm run build 构建；opencli list | grep mysite 确认注册；opencli mysite hot --limit 3 -v 查看每步数据流；opencli mysite hot --limit 3 -f json 确认字段完整。
针对 intercept 策略，文档给出 tap 步骤调试流程：先用 evaluate 列出所有 Pinia store；再故意写错 action 名以获取可用 action 列表（错误信息会提示 Available actions）；最后用 network requests 确认 capture 模式，找到目标 API 的 URL 特征。
适用场景
适用于需要为 OpenCLI 扩展新网站或平台支持、需要从零探索一个新站点完整流程、需要在浏览器 DevTools 中探索网站 API 端点、需要选择认证策略并编写 TypeScript 适配器、需要调试 Pinia Store Action 或 XHR 拦截的场景。
限制与说明
文档指出 opencli explore 自动化分析可能不完美，需用 verbose 模式手动确认；部分接口需要 Wbi 签名或 Cookie 鉴权；分页 API 的 ps 上限通常为 20~50；INITIAL_STATE 只有首屏数据，深层数据需调 API；UI 自动化被列为最后手段。本技能的价格、授权、收费等信息暂未提供。