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 workflo

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 的完整过程：关键决策点：直接访问 fans/follow 页面（不是首页），页面加载就会触发 following API 看到 URL 里没有 /wbi/ → 不需要签名 → 直接用 fetchJson 而非 apiGet API 返回 code: 0 + 非空 list → Tier 2 Cookie 策略确认核心流程 Step 1: 发现 API 1a. 自动化发现（推荐） OpenCLI 内置 Deep Explore，自动分析网站网络请求：输出到 .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 模式手动确认：关注抓包结果中的关键信息： 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 自动检测前端框架。如果需要手动确认： Vue + Pinia 的站点（如小红书）可以直接通过 Store Action 绕过签名。 Step 2: 选择认证策略 OpenCLI 提供 5 级认证策略。使用 cascade 命令自动探测：策略决策树各策略对比 Tier 策略速度复杂度适用场景实例 1 public ⚡ ~1s 最简公开 API，无需登录 Hacker News, V2EX 2 cookie 🔄 ~7s 简单 Cookie 认证即可 Bilibili, Zhihu, Reddit 3 header 🔄 ~7s 中等需要 CSRF token 或 Bearer Twitter GraphQL 4 intercept 🔄 ~10s 较高请求有复杂签名小红书 (Pinia + XHR) 5 ui 🐌 ~15s+ 最高无 API，纯 DOM 解析遗留网站 Step 2.5: 准备工作（写代码之前）先找模板：从最相似的现有适配器开始不要从零开始写。先看看同站点已有哪些适配器：最高效的方式是复制最相似的适配器，然后改 3 个地方： 1. name → 新命令名 2. API URL → 你在 Step 1 发现的端点 3. 字段映射 → 对应新 API 的字段平台 SDK 速查表写 TS 适配器之前，先看看你的目标站点有没有现成的 helper 函数可以复用： Bilibili ( clis/bilibili/utils.ts ) 函数用途何时使用 fetchJson(page, url) 带 Cookie 的 fetch + JSON 解析普通 Cookie tier API apiGet(page, path, {signed, params}) 带 Wbi 签名的 API 调用 URL 含 /wbi/ 的接口 getSelfUid(page) 获取当前登录用户的 UID "我的xxx" 类命令 resolveUid(page, input) 解析用户输入的 UID(支持数字/URL) uid 参数处理 wbiSign(page, params) 底层 Wbi 签名生成通常不直接用， apiGet 已封装 stripHtml(s) 去除 HTML 标签清理富文本字段如何判断需不需要 apiGet ？看 Network 请求 URL：含 /wbi/ 或 w rid= → 必须用 apiGet(..., { signed: true }) 不含 → 直接用 fetchJson 其他站点（Twitter、小红书等）暂无专用 SDK，直接用 page.evaluate + fetch 即可。 Step 3: 编写适配器适配器格式：统一使用 TypeScript 所有适配器统一使用 TypeScript cli() API。YAML adapter 格式已不再支持。场景模式示例简单 fetch + 数据映射 TS cli() + func() v2ex/hot.ts , hackernews/top.ts navigate + evaluate(fetch) + 数据映射 TS cli() + func() zhihu/hot.ts Pinia Store Action 触发 TS cli() + func() xiaohongshu/feed.ts , xiaohongshu/notifications.ts 复杂 JS 逻辑（state 读取、条件分支） TS cli() + func() xiaohongshu/me.ts , bilibili/me.ts XHR 拦截 + 签名 TS cli() + func() xiaohongshu/search.ts GraphQL / 分页 / Wbi 签名 TS cli() + func() bilibili/search.ts , twitter/search.ts 通用模式：分页 API 很多 API 使用 pn （页码）+ ps （每页数量）分页。标准处理模式：大多数站点的 ps 上限是 20~50。超过会被静默截断或返回错误。方式 A: TS cli() + func() （标准模式，推荐）文件路径: clis/<site /<name .ts ，放入即自动注册。 Tier 1 — 公开 API 模板 Tier 2 — Cookie 认证模板（最常用）关键 : page.evaluate 内的 fetch 运行在浏览器页面内，自动携带 credentials: 'include' ，无需手动处理 Cookie。进阶 — 带搜索参数 Tier 4 — Store Action + Interceptor（intercept 策略）适用于 Vue + Pinia/Vuex 的网站（如小红书），使用 installInterceptor 捕获 store action 触发的请求：方式 B: TypeScript 适配器（进阶模式）适用于需要嵌入 JS 代码读取 Pinia state、XHR 拦截、GraphQL、分页、复杂数据转换等场景。文件路径: clis/<site /<name .ts 。文件将会在运行时被动态扫描并注册（切勿在 index.ts 中手动 import ）。 Tier 3 — Header 认证（Twitter） Tier 4 — XHR/Fetch 双重拦截 (Twitter/小红书通用模式) 拦截核心思路：不自己构造签名，而是利用 installInterceptor 劫持网站自己的 XMLHttpRequest 和 fetch ，让网站发请求，我们直接在底层取出解析好的 response.json() 。级联请求（如 BVID→CID→字幕）的完整模板和要点见下方[进阶模式: 级联请求]( 进阶模式级联请求 cascading requests)章节。 Step 4: 测试构建通过 ≠ 功能正常。 npm run build 只验证 TypeScript 语法，不验证运行时行为。每个新命令必须实际运行并确认输出正确后才算完成。必做清单 tap 步骤调试（intercept 策略专用）不要猜 store name / action name 。先用 evaluate 探索，再写 TS 适配器。 Step 1: 列出所有 Pinia store 在浏览器中打开目标网站后： Step 2: 查看 store 的 action 名称故意写一个错误 action 名，tap 会返回所有可用 actions： Step 3: 用 network requests 确认 capture 模式完整流程 Verbose 模式 & 输出验证 Step 5: 提交发布文件放入 clis/<site / 即自动注册（TS 文件无需手动 import），然后：架构理念：OpenCLI 内建 Zero Dependency jq 数据流 — 所有解析在 evaluate 的原生 JS 内完成，TS func() 内直接处理数据，无需依赖系统 jq 二进制。进阶模式: 级联请求 (Cascading Requests) 当目标数据需要多步 API 链式获取时（如 BVID → CID → 字幕列表 → 字幕内容），在 TS func() 内按步骤串联即可。模板代码关键要点步骤注意事项提取中间 ID 优先从 INITIAL STATE 拿，避免额外 API 调用 Wbi 签名 B 站 /wbi/ 接口强制校验 w rid ，纯 fetch 会被 403 空值断言即使 HTTP 200，核心字段可能为空串（风控降级） CDN URL 常以 // 开头，记得补 https: JSON.stringify 拼接 URL 到 evaluate 时必须用它转义，避免注入常见陷阱陷阱表现解决方案缺少 navigate evaluate 报 Target page context 错误在 evaluate 前加 page.goto() 步骤嵌套字段访问 ${{ item.node?.title }} 不工作在 evaluate 中 flatten 数据，不在模板中用 optional chaining 缺少 strategy: public 公开 API 也启动浏览器，7s → 1s 公开 API 加上 strategy: public + browser: false evaluate 返回字符串 map 步骤收到 "" 而非数组 pipeline 有 auto parse，但建议在 evaluate 内 .map() 整形搜索参数被 URL 编码 ${{ args.query }} 被浏览器二次编码在 evaluate 内用 encodeURIComponent() 手动编码 Cookie 过期返回 401 / 空数据在浏览器里重新登录目标站点 Extension tab 残留 Chrome 多出 chrome extension:// tab 已自动清理；若残留，手动关闭即可 TS evaluate 格式 () = {} 报 result is not a function TS 中 page.evaluate() 必须用 IIFE： (async () = { ... })() 页面异步加载 evaluate 拿到空数据（store state 还没更新）在 evaluate 内用 polling 等待数据出现，或增加 wait 时间 evaluate 内嵌大段 JS 调试困难，字符串转义问题把逻辑放在 func() 内，用原生 TS 编写风控被拦截(伪200) 获取到的 JSON 里核心数据是 "" (空串) 极易被误判。必须添加断言！无核心数据立刻要求升级鉴权 Tier 并重新配置 Cookie API 没找见 explore 工具打分出来的都拿不到深层数据点击页面按钮诱发懒加载数据，再结合 getInterceptedRequests 获取用 AI Agent 自动生成适配器最快的方式是让 AI Agent 完成全流程：生成的候选 TS 保存在 .opencli/explore/mysite/candidates/ ，可直接复制到 clis/mysite/ 并微调。 Record Workflow record 是为「无法用 explore 自动发现」的页面（需要登录操作、复杂交互、SPA 内路由）准备的手动录制方案。工作原理拦截器特性：同时 patch window.fetch 和 XMLHttpRequest 只捕获 Content Type: application/json 的响应过滤纯对象少于 2 个 key 的响应（避免 tracking/ping）跨 tab 隔离：每个 tab 独立缓冲区，轮询时分别 drain 幂等注入：同一 tab 二次注入时先 restore 原始函数再重新 patch，不丢失已捕获数据使用步骤页面类型与捕获预期页面类型预期捕获量说明列表/搜索页多（5~20+）每次搜索/翻页都会触发新请求详情页（只读）少（1~5）首屏数据一次性返回，后续操作走 form/redirect SPA 内路由跳转中等路由切换会触发新接口，但首屏请求在注入前已发出需要登录的页面视操作而定确保 Chrome 已登录目标网站注意：如果页面在导航完成前就发出了大部分请求（服务端渲染 / SSR 注水），拦截器会错过这些请求。解决方案：在页面加载完成后，手动触发能产生新请求的操作（搜索、翻页、切 Tab、展开折叠项等）。候选 TS 微调生成的候选 TS 是起点，通常需要微调（尤其是 tae 等内部系统）：候选结构（自动生成，可能需要调整）：转换为 TS CLI （参考 clis/tae/add expense.ts 风格）：转换要点： 1. URL 中的动态 ID（ procInsId 、 taskId 等）提取为 args 2. captured.json 里的真实 body 结构用于确定正确的数据路径（如 content.operatorRecords ） 3. tae 系统统一用 { success, content, errorCode, errorMsg } 外层包裹，取数据要走 content. 4. 认证方式：cookie（ credentials: 'include' ），不需要额外 header 5. 文件放入 clis/<site / ，无需手动注册， npm run build 后自动发现故障排查现象原因解法捕获 0 条请求拦截器注入失败，或页面无 JSON API 检查 daemon 是否运行： curl localhost:19825/status 捕获量少（1~3 条）页面是只读详情页，首屏数据已在注入前发出手动操作触发更多请求（搜索/翻页），或换用列表页候选 TS 为 0 捕获到的 JSON 都没有 array 结构直接看 captured.json 手写 TS CLI 新开的 tab 没有被拦截轮询间隔内 tab 已关闭缩短 poll 500 二次运行 record 时数据不连续正常，每次 record 启动都是新的 automation window 无需处理

qiaomu-opencli-explorer