@jackwener/opencli 0.2.0 → 0.4.0

package/CLI-CREATOR.md

@@ -51,7 +51,17 @@ opencli bilibili hot -v   # 查看已有命令的 pipeline 每步数据流
 - **Request Headers**: Cookie? Bearer? 自定义签名头（X-s、X-t）?
 - **Response Body**: JSON 结构，特别是数据在哪个路径（`data.items`、`data.list`）
 
-### 1c. 框架检测
+### 1c. 高阶 API 发现捷径法则 (Heuristics)
+
+在开始死磕复杂的抓包拦截之前，按照以下优先级进行尝试：
+
+1. **后缀爆破法 (`.json`)**: 像 Reddit 这样复杂的网站，只要在其 URL 后加上 `.json`（例如 `/r/all.json`），就能在带 Cookie 的情况下直接利用 `fetch` 拿到极其干净的 REST 数据（Tier 2 Cookie 策略极速秒杀）。另外如功能完备的**雪球 (xueqiu)** 也可以走这种纯 API 的方式极简获取，成为你构建简单 YAML 的黄金标杆。
+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 自动检测前端框架。如果需要手动确认：
 
@@ -110,9 +120,9 @@ opencli cascade https://api.example.com/hot
 
 ```
 你的 pipeline 里有 evaluate 步骤（内嵌 JS 代码）？
-  → ✅ 用 TypeScript (src/clis/<site>/<name>.ts)，需在 index.ts 注册
+  → ✅ 用 TypeScript (src/clis/<site>/<name>.ts)，保存即自动动态注册
   → ❌ 纯声明式（navigate + tap + map + limit）？
-       → ✅ 用 YAML (src/clis/<site>/<name>.yaml)，放入即自动注册
+       → ✅ 用 YAML (src/clis/<site>/<name>.yaml)，保存即自动注册
 ```
 
 | 场景 | 选择 | 示例 |
@@ -310,7 +320,7 @@ pipeline:
 
 适用于需要嵌入 JS 代码读取 Pinia state、XHR 拦截、GraphQL、分页、复杂数据转换等场景。
 
-文件路径: `src/clis/<site>/<name>.ts`，还需要在 `src/clis/index.ts` 中 import 注册。
+文件路径: `src/clis/<site>/<name>.ts`。文件将会在运行时被动态扫描并注册（切勿在 `index.ts` 中手动 `import`）。
 
 #### Tier 3 — Header 认证（Twitter）
 
@@ -353,84 +363,83 @@ cli({
 });
 ```
 
-#### Tier 4 — Store Action + XHR 拦截（小红书）
+#### Tier 4 — XHR/Fetch 双重拦截 (Twitter/小红书 通用模式)
 
 ```typescript
-// src/clis/xiaohongshu/search.ts
+// src/clis/xiaohongshu/user.ts
 import { cli, Strategy } from '../../registry.js';
 
 cli({
   site: 'xiaohongshu',
-  name: 'search',
-  description: '搜索小红书笔记',
-  strategy: Strategy.COOKIE,   // 实际是 intercept 模式
-  args: [{ name: 'keyword', required: true }],
-  columns: ['rank', 'title', 'author', 'likes', 'type'],
+  name: 'user',
+  description: '获取用户笔记',
+  strategy: Strategy.INTERCEPT,
+  args: [{ name: 'id', required: true }],
+  columns: ['rank', 'title', 'likes', 'url'],
   func: async (page, kwargs) => {
-    await page.goto('https://www.xiaohongshu.com');
-    await page.wait(2);
-
-    const data = await page.evaluate(`
-      (async () => {
-        const app = document.querySelector('#app')?.__vue_app__;
-        const pinia = app?.config?.globalProperties?.$pinia;
-        if (!pinia?._s) return { error: 'Page not ready' };
-
-        const searchStore = pinia._s.get('search');
-        if (!searchStore) return { error: 'Search store not found' };
-
-        // XHR 拦截：捕获 store action 发出的请求
-        let captured = null;
-        const origOpen = XMLHttpRequest.prototype.open;
-        const origSend = XMLHttpRequest.prototype.send;
-        XMLHttpRequest.prototype.open = function(m, u) {
-          this.__url = u;
-          return origOpen.apply(this, arguments);
-        };
-        XMLHttpRequest.prototype.send = function(b) {
-          if (this.__url?.includes('search/notes')) {
-            const x = this;
-            const orig = x.onreadystatechange;
-            x.onreadystatechange = function() {
-              if (x.readyState === 4 && !captured) {
-                try { captured = JSON.parse(x.responseText); } catch {}
-              }
-              if (orig) orig.apply(this, arguments);
-            };
-          }
-          return origSend.apply(this, arguments);
-        };
-
-        try {
-          // 触发 Store Action，让网站自己签名发请求
-          searchStore.mutateSearchValue('${kwargs.keyword}');
-          await searchStore.loadMore();
-          await new Promise(r => setTimeout(r, 800));
-        } finally {
-          // 恢复原始 XHR
-          XMLHttpRequest.prototype.open = origOpen;
-          XMLHttpRequest.prototype.send = origSend;
+    await page.goto(`https://www.xiaohongshu.com/user/profile/${kwargs.id}`);
+    await page.wait(5);
+
+    // XHR/Fetch 底层拦截：捕获所有包含 'v1/user/posted' 的请求
+    await page.installInterceptor('v1/user/posted');
+
+    // 触发后端 API：模拟人类用户向底部滚动2次
+    await page.autoScroll({ times: 2, delayMs: 2000 });
+
+    // 提取所有被拦截捕获的 JSON 响应体
+    const requests = await page.getInterceptedRequests();
+    if (!requests || requests.length === 0) return [];
+
+    let results = [];
+    for (const req of requests) {
+      if (req.data?.data?.notes) {
+        for (const note of req.data.data.notes) {
+           results.push({
+             title: note.display_title || '',
+             likes: note.interact_info?.liked_count || '0',
+             url: `https://explore/${note.note_id || note.id}`
+           });
         }
+      }
+    }
 
-        if (!captured?.success) return { error: captured?.msg || 'Search failed' };
-        return (captured.data?.items || []).map(i => ({
-          title: i.note_card?.display_title || '',
-          author: i.note_card?.user?.nickname || '',
-          likes: i.note_card?.interact_info?.liked_count || '0',
-          type: i.note_card?.type || '',
-        }));
-      })()
-    `);
-
-    if (!Array.isArray(data)) return [];
-    return data.slice(0, kwargs.limit || 20).map((item, i) => ({
+    return results.slice(0, 20).map((item, i) => ({
       rank: i + 1, ...item,
     }));
   },
 });
 ```
 
-> **XHR 拦截核心思路**：不自己构造签名，而是劫持网站自己的 `XMLHttpRequest`，让网站的 Store Action 发出正确签名的请求，我们只是"窃听"响应。用完后必须恢复原始方法。
+> **拦截核心思路**：不自己构造签名，而是利用 `installInterceptor` 劫持网站自己的 `XMLHttpRequest` 和 `fetch`，让网站发请求，我们直接在底层取出解析好的 `response.json()`。
+
+#### 进阶场景 1: 级联请求 (Cascading Requests) 与鉴权绕过
+
+部分 API 获取是非常复杂的连环请求（例如 B 站获取视频字幕：先需要 `bvid` 获取核心 `cid`，再通过 `cid` 获取包含签名/Wbi 的字幕列表拉取地址，最后 fetch 真实的 CDN 资源）。在此类场景中，你必须在一个 `evaluate` 块内部或者在 TypeScript Node 端编排整个请求链条：
+
+```typescript
+// 真实场景：B站获取视频字幕的级联获取思路
+const subtitleUrls = await page.evaluate(async (bvid) => {
+  // Step 1: 拿 CID (通常可以通过页面全局状态极速提取)
+  const cid = window.__INITIAL_STATE__?.videoData?.cid;
+  
+  // Step 2: 依据 BVID 和 CID 拿字幕配置 (可能需要携带 W_RID 签名或依赖浏览器当前登录状态 Cookie)
+  const res = await fetch(\`/x/player/wbi/v2?bvid=\${bvid}&cid=\${cid}\`, { credentials: 'include' });
+  const data = await res.json();
+  
+  // Step 3: 风控拦截/未登录降级空值检测 (Anti-Bot Empty Value Detection) ⚠️ 极其重要
+  // 很多大厂 API 只要签名失败或无强登录 Cookie 依然会返回 HTTP 200，但把关键 URL 设为 ""
+  const firstSubUrl = data.data?.subtitle?.subtitles?.[0]?.subtitle_url;
+  if (!firstSubUrl) {
+    throw new Error('被风控降级或需登录：拿不到真实的 subtitle_url，请检查 Cookie 状态 (Tier 2/3)');
+  }
+  
+  return firstSubUrl;
+}, kwargs.bvid);
+
+// Step 4: 拉取最终的 CDN 静态文件 (无鉴权)
+const finalRes = await fetch(subtitleUrls.startsWith('//') ? 'https:' + subtitleUrls : subtitleUrls);
+const subtitles = await finalRes.json();
+```
 
 ---
 
@@ -537,11 +546,7 @@ opencli mysite hot -f csv > data.csv
 
 ### TS 适配器
 
-在 `src/clis/index.ts` 添加 import：
-
-```typescript
-import './mysite/search.js';
-```
+放入 `src/clis/<site>/<name>.ts` 即自动加载模块，无需在 `index.ts` 中写入 `import`。
 
 ### 验证注册
 
@@ -558,6 +563,74 @@ git commit -m "feat(mysite): add hot and search adapters"
 git push
 ```
 
+## 设计哲学: Zero-Dependency jq
+
+> 💡 **架构理念升级**: OpenCLI 的原生机制本质上内建了一个 **Zero-Dependency jq 数据处理流**。使用时不需要依赖系统命令级别的 `jq` 包，而是将所有的解析拍平动作放在 `evaluate` 块内的原生 JavaScript 里，再由外层 YAML 通过 `select`、`map` 等命令提取。这将彻底消灭跨操作系统下产生的第三方二进制库依赖。
+
+---
+
+## 进阶模式: 级联请求 (Cascading Requests)
+
+当目标数据需要多步 API 链式获取时（如 `BVID → CID → 字幕列表 → 字幕内容`），必须使用 **TS 适配器**。YAML 无法处理这种多步逻辑。
+
+### 模板代码
+
+```typescript
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+import { apiGet } from '../../bilibili.js'; // 复用平台 SDK
+
+cli({
+  site: 'bilibili',
+  name: 'subtitle',
+  strategy: Strategy.COOKIE,
+  args: [{ name: 'bvid', required: true }],
+  columns: ['index', 'from', 'to', 'content'],
+  func: async (page: IPage | null, kwargs: any) => {
+    if (!page) throw new Error('Requires browser');
+
+    // Step 1: 建立 Session
+    await page.goto(`https://www.bilibili.com/video/${kwargs.bvid}/`);
+
+    // Step 2: 从页面提取中间 ID (__INITIAL_STATE__)
+    const cid = await page.evaluate(`(async () => {
+      return window.__INITIAL_STATE__?.videoData?.cid;
+    })()`);
+    if (!cid) throw new Error('无法提取 CID');
+
+    // Step 3: 用中间 ID 调用下一级 API (自动 Wbi 签名)
+    const payload = await apiGet(page, '/x/player/wbi/v2', {
+      params: { bvid: kwargs.bvid, cid },
+      signed: true, // ← 自动生成 w_rid
+    });
+
+    // Step 4: 检测风控降级 (空值断言)
+    const subtitles = payload.data?.subtitle?.subtitles || [];
+    const url = subtitles[0]?.subtitle_url;
+    if (!url) throw new Error('subtitle_url 为空，疑似风控降级');
+
+    // Step 5: 拉取最终数据 (CDN JSON)
+    const items = await page.evaluate(`(async () => {
+      const res = await fetch(${JSON.stringify('https:' + url)});
+      const json = await res.json();
+      return { data: json.body || json };
+    })()`);
+
+    return items.data.map((item, idx) => ({ ... }));
+  },
+});
+```
+
+### 关键要点
+
+| 步骤 | 注意事项 |
+|------|----------|
+| 提取中间 ID | 优先从 `__INITIAL_STATE__` 拿，避免额外 API 调用 |
+| Wbi 签名 | B 站 `/wbi/` 接口**强制校验** `w_rid`，纯 `fetch` 会被 403 |
+| 空值断言 | 即使 HTTP 200，核心字段可能为空串（风控降级） |
+| CDN URL | 常以 `//` 开头，记得补 `https:` |
+| `JSON.stringify` | 拼接 URL 到 evaluate 时必须用它转义，避免注入 |
+
 ---
 
 ## 常见陷阱
@@ -574,6 +647,8 @@ git push
 | TS evaluate 格式 | `() => {}` 报 `result is not a function` | TS 中 `page.evaluate()` 必须用 IIFE：`(async () => { ... })()` |
 | 页面异步加载 | evaluate 拿到空数据（store state 还没更新） | 在 evaluate 内用 polling 等待数据出现，或增加 `wait` 时间 |
 | YAML 内嵌大段 JS | 调试困难，字符串转义问题 | 超过 10 行 JS 的命令改用 TS adapter |
+| **风控被拦截(伪200)** | 获取到的 JSON 里核心数据是 `""` (空串) | 极易被误判。必须添加断言！无核心数据立刻要求升级鉴权 Tier 并重新配置 Cookie |
+| **API 没找见** | `explore` 工具打分出来的都拿不到深层数据 | 点击页面按钮诱发懒加载数据，再结合 `getInterceptedRequests` 获取 |
 
 ---
 
@@ -586,9 +661,10 @@ git push
 opencli generate https://www.example.com --goal "hot"
 
 # 或分步执行：
-opencli explore https://www.example.com --site mysite   # 发现 API
-opencli synthesize mysite                                # 生成候选 YAML
-opencli verify mysite/hot --smoke                        # 冒烟测试
+opencli explore https://www.example.com --site mysite           # 发现 API
+opencli explore https://www.example.com --auto --click "字幕,CC"  # 模拟点击触发懒加载 API
+opencli synthesize mysite                                        # 生成候选 YAML
+opencli verify mysite/hot --smoke                                # 冒烟测试
 ```
 
 生成的候选 YAML 保存在 `.opencli/explore/mysite/candidates/`，可直接复制到 `src/clis/mysite/` 并微调。

package/README.md

@@ -7,14 +7,16 @@
 
 [![npm](https://img.shields.io/npm/v/@jackwener/opencli)](https://www.npmjs.com/package/@jackwener/opencli)
 
-A CLI tool that turns **any website** into a command-line interface. **28+ commands** across **16 sites** — bilibili, zhihu, xiaohongshu, twitter, reddit, github, v2ex, hackernews, bbc, weibo, boss, yahoo-finance, reuters, smzdm, ctrip, youtube — powered by browser session reuse and AI-native discovery.
+A CLI tool that turns **any website** into a command-line interface. **46 commands** across **17 sites** — bilibili, zhihu, xiaohongshu, twitter, reddit, xueqiu, github, v2ex, hackernews, bbc, weibo, boss, yahoo-finance, reuters, smzdm, ctrip, youtube — powered by browser session reuse and AI-native discovery.
 
 ## ✨ Highlights
 
 - 🔐 **Account-safe** — Reuses Chrome's logged-in state; your credentials never leave the browser
 - 🤖 **AI Agent ready** — `explore` discovers APIs, `synthesize` generates adapters, `cascade` finds auth strategies
-- 📝 **Declarative YAML** — Most adapters are ~30 lines of YAML pipeline
-- 🔌 **TypeScript escape hatch** — Complex adapters (XHR interception, GraphQL) in TS
+- 🚀 **Dynamic Loader** — Simply drop `.ts` or `.yaml` adapters into the `clis/` folder for auto-registration
+- 📝 **Dual-Engine Architecture**:
+  - **YAML Declarative Engine**: Most adapters are minimal ~30 lines of YAML pipeline
+  - **Native Browser Injection Engine**: Advanced TypeScript utilities (`installInterceptor`, `autoScroll`) for XHR hijacking, GraphQL unwrapping, and store mutation
 
 ## 🚀 Quick Start
 
@@ -80,11 +82,12 @@ Public API commands (`hackernews`, `github search`, `v2ex`) need no browser at a
 
 | Site | Commands | Mode |
 |------|----------|------|
-| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` | 🔐 Browser |
+| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` `subtitle` `dynamic` `ranking` | 🔐 Browser |
 | **zhihu** | `hot` `search` `question` | 🔐 Browser |
-| **xiaohongshu** | `search` `notifications` `feed` | 🔐 Browser |
-| **twitter** | `trending` | 🔐 Browser |
-| **reddit** | `hot` | 🔐 Browser |
+| **xiaohongshu** | `search` `notifications` `feed` `me` `user` | 🔐 Browser |
+| **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 🔐 Browser |
+| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` | 🔐 Browser |
+| **reddit** | `hot` `frontpage` `search` `subreddit` | 🔐 Browser |
 | **weibo** | `hot` | 🔐 Browser |
 | **boss** | `search` | 🔐 Browser |
 | **youtube** | `search` | 🔐 Browser |
@@ -131,7 +134,7 @@ Explore outputs to `.opencli/explore/<site>/`:
 
 ## 🔧 Create New Commands
 
-See **[SKILL.md](./SKILL.md)** for the full adapter guide (YAML pipeline + TypeScript).
+See **[CLI-CREATOR.md](./CLI-CREATOR.md)** for the full adapter guide (YAML pipeline + TypeScript).
 
 ## Releasing New Versions
 

package/README.zh-CN.md

@@ -11,11 +11,13 @@ OpenCLI 通过 Chrome 浏览器 + [Playwright MCP Bridge](https://github.com/nic
 
 ## ✨ 亮点
 
-- 🌐 **28+ 命令，16 个站点** — B站、知乎、小红书、Twitter、Reddit、GitHub、V2EX、Hacker News、BBC、微博、BOSS直聘、Yahoo Finance、路透社、什么值得买、携程、YouTube
+- 🌐 **46 个命令，17 个站点** — B站、知乎、小红书、Twitter、Reddit、雪球(xueqiu)、GitHub、V2EX、Hacker News、BBC、微博、BOSS直聘、Yahoo Finance、路透社、什么值得买、携程、YouTube
 - 🔐 **零风控** — 复用 Chrome 登录态，无需存储任何凭证
 - 🤖 **AI 原生** — `explore` 自动发现 API，`synthesize` 生成适配器，`cascade` 探测认证策略
-- 📝 **声明式 YAML** — 大部分适配器只需 ~30 行 YAML
-- 🔌 **TypeScript 扩展** — 复杂场景（XHR 拦截、GraphQL）可用 TS 编写
+- 🚀 **动态加载引擎** — 只需将 `.ts` 或 `.yaml` 适配器放入 `clis/` 文件夹即可自动注册生效
+- 📝 **双引擎架构设计**:
+  - **YAML 声明式引擎**：大部分适配器只需极简的 ~30 行 YAML 声明
+  - **原生浏览器注入引擎**：提供高级 TS API（`installInterceptor`、`autoScroll`）轻松实现 XHR 劫持、GraphQL 解包及状态库注入
 
 ## 🚀 快速开始
 
@@ -81,11 +83,12 @@ npm install -g @jackwener/opencli@latest
 
 | 站点 | 命令 | 模式 |
 |------|------|------|
-| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` | 🔐 浏览器 |
+| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` `subtitle` `dynamic` `ranking` | 🔐 浏览器 |
 | **zhihu** | `hot` `search` `question` | 🔐 浏览器 |
-| **xiaohongshu** | `search` `notifications` `feed` | 🔐 浏览器 |
-| **twitter** | `trending` | 🔐 浏览器 |
-| **reddit** | `hot` | 🔐 浏览器 |
+| **xiaohongshu** | `search` `notifications` `feed` `me` `user` | 🔐 浏览器 |
+| **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 🔐 浏览器 |
+| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` | 🔐 浏览器 |
+| **reddit** | `hot` `frontpage` `search` `subreddit` | 🔐 浏览器 |
 | **weibo** | `hot` | 🔐 浏览器 |
 | **boss** | `search` | 🔐 浏览器 |
 | **youtube** | `search` | 🔐 浏览器 |
@@ -132,7 +135,7 @@ opencli cascade https://api.example.com/data
 
 ## 🔧 创建新命令
 
-查看 **[SKILL.md](./SKILL.md)** 了解完整的适配器开发指南（YAML pipeline + TypeScript）。
+查看 **[CLI-CREATOR.md](./CLI-CREATOR.md)** 了解完整的适配器开发指南（YAML pipeline + TypeScript）。
 
 ## 版本发布
 

package/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: opencli
 description: "OpenCLI — Make any website your CLI. Zero risk, AI-powered, reuse Chrome login."
-version: 0.1.0
+version: 0.4.0
 author: jackwener
-tags: [cli, browser, web, mcp, playwright, bilibili, zhihu, twitter, github, v2ex, hackernews, reddit, xiaohongshu, AI, agent]
+tags: [cli, browser, web, mcp, playwright, bilibili, zhihu, twitter, github, v2ex, hackernews, reddit, xiaohongshu, xueqiu, AI, agent]
 ---
 
 # OpenCLI
@@ -49,6 +49,9 @@ opencli bilibili favorite                 # 我的收藏
 opencli bilibili history --limit 20       # 观看历史
 opencli bilibili feed --limit 10          # 动态时间线
 opencli bilibili user-videos --uid 12345  # 用户投稿
+opencli bilibili subtitle --bvid BV1xxx   # 获取视频字幕 (支持 --lang zh-CN)
+opencli bilibili dynamic --limit 10       # 动态
+opencli bilibili ranking --limit 10       # 排行榜
 
 # 知乎 (browser)
 opencli zhihu hot --limit 10             # 知乎热榜
@@ -59,6 +62,14 @@ opencli zhihu question --id 34816524     # 问题详情和回答
 opencli xiaohongshu search --keyword "美食"  # 搜索笔记
 opencli xiaohongshu notifications             # 通知（mentions/likes/connections）
 opencli xiaohongshu feed --limit 10           # 推荐 Feed
+opencli xiaohongshu me                         # 我的信息
+opencli xiaohongshu user --uid xxx             # 用户主页
+
+# 雪球 Xueqiu (browser)
+opencli xueqiu hot-stock --limit 10      # 雪球热门股票榜
+opencli xueqiu stock --symbol SH600519   # 查看股票实时行情
+opencli xueqiu watchlist                 # 获取自选股/持仓列表
+opencli xueqiu feed                      # 我的关注 timeline
 
 # GitHub (trending=browser, search=public)
 opencli github trending --limit 10       # GitHub Trending
@@ -66,10 +77,17 @@ opencli github search --keyword "cli"    # 搜索仓库
 
 # Twitter/X (browser)
 opencli twitter trending --limit 10      # 热门话题
+opencli twitter bookmarks --limit 20     # 获取收藏的书签推文
+opencli twitter search --keyword "AI"    # 搜索推文
+opencli twitter profile --username elonmusk  # 用户资料
+opencli twitter timeline --limit 20      # 时间线
 
 # Reddit (browser)
 opencli reddit hot --limit 10            # 热门帖子
 opencli reddit hot --subreddit programming  # 指定子版块
+opencli reddit frontpage --limit 10      # 首页
+opencli reddit search --keyword "AI"     # 搜索
+opencli reddit subreddit --name rust     # 子版块浏览
 
 # V2EX (public)
 opencli v2ex hot --limit 10              # 热门话题
@@ -128,6 +146,9 @@ opencli generate <url> --goal "hot"
 # Strategy Cascade: auto-probe PUBLIC → COOKIE → HEADER
 opencli cascade <api-url>
 
+# Explore with interactive fuzzing (click buttons to trigger lazy APIs)
+opencli explore <url> --auto --click "字幕,CC,评论"
+
 # Verify: smoke-test a generated adapter
 opencli verify <site/name> --smoke
 ```
@@ -209,7 +230,7 @@ pipeline:
 
 ### TypeScript Adapter (programmatic)
 
-Create `src/clis/<site>/<name>.ts` and import in `clis/index.ts`:
+Create `src/clis/<site>/<name>.ts`. It will be automatically dynamically loaded (DO NOT manually import it in `index.ts`):
 
 ```typescript
 import { cli, Strategy } from '../../registry.js';
@@ -217,27 +238,33 @@ import { cli, Strategy } from '../../registry.js';
 cli({
   site: 'mysite',
   name: 'search',
-  strategy: Strategy.COOKIE,
+  strategy: Strategy.INTERCEPT, // Or COOKIE
   args: [{ name: 'keyword', required: true }],
   columns: ['rank', 'title', 'url'],
   func: async (page, kwargs) => {
-    await page.goto('https://www.mysite.com');
-    const data = await page.evaluate(`
-      (async () => {
-        const res = await fetch('/api/search?q=${kwargs.keyword}', {
-          credentials: 'include'
-        });
-        return await res.json();
-      })()
-    `);
-    return data.items.map((item, i) => ({
+    await page.goto('https://www.mysite.com/search');
+    
+    // Inject native XHR/Fetch interceptor hook
+    await page.installInterceptor('/api/search');
+    
+    // Auto scroll down to trigger lazy loading
+    await page.autoScroll({ times: 3, delayMs: 2000 });
+    
+    // Retrieve intercepted JSON payloads
+    const requests = await page.getInterceptedRequests();
+    
+    let results = [];
+    for (const req of requests) {
+      results.push(...req.data.items);
+    }
+    return results.map((item, i) => ({
       rank: i + 1, title: item.title, url: item.url,
     }));
   },
 });
 ```
 
-**When to use TS**: XHR interception (小红书), cookie extraction (Twitter ct0), Wbi signing (Bilibili), auto-pagination, complex data transforms.
+**When to use TS**: XHR interception (`page.installInterceptor`), infinite scrolling (`page.autoScroll`), cookie extraction, complex data transforms (like GraphQL unwrapping).
 
 ## Pipeline Steps
 

package/dist/browser.d.ts

@@ -23,7 +23,11 @@ export declare class Page implements IPage {
     click(ref: string): Promise<void>;
     typeText(ref: string, text: string): Promise<void>;
     pressKey(key: string): Promise<void>;
-    wait(seconds: number): Promise<void>;
+    wait(options: number | {
+        text?: string;
+        time?: number;
+        timeout?: number;
+    }): Promise<void>;
     tabs(): Promise<any>;
     closeTab(index?: number): Promise<void>;
     newTab(): Promise<void>;
@@ -31,6 +35,12 @@ export declare class Page implements IPage {
     networkRequests(includeStatic?: boolean): Promise<any>;
     consoleMessages(level?: string): Promise<any>;
     scroll(direction?: string, amount?: number): Promise<void>;
+    autoScroll(options?: {
+        times?: number;
+        delayMs?: number;
+    }): Promise<void>;
+    installInterceptor(pattern: string): Promise<void>;
+    getInterceptedRequests(): Promise<any[]>;
 }
 /**
  * Playwright MCP process manager.

package/dist/browser.js

@@ -110,8 +110,14 @@ export class Page {
     async pressKey(key) {
         await this.call('tools/call', { name: 'browser_press_key', arguments: { key } });
     }
-    async wait(seconds) {
-        await this.call('tools/call', { name: 'browser_wait_for', arguments: { time: seconds } });
+    async wait(options) {
+        if (typeof options === 'number') {
+            await this.call('tools/call', { name: 'browser_wait_for', arguments: { time: options } });
+        }
+        else {
+            // Pass directly to native wait_for, which supports natively awaiting text strings without heavy DOM polling
+            await this.call('tools/call', { name: 'browser_wait_for', arguments: options });
+        }
     }
     async tabs() {
         return this.call('tools/call', { name: 'browser_tabs', arguments: { action: 'list' } });
@@ -134,6 +140,88 @@ export class Page {
     async scroll(direction = 'down', amount = 500) {
         await this.call('tools/call', { name: 'browser_press_key', arguments: { key: direction === 'down' ? 'PageDown' : 'PageUp' } });
     }
+    async autoScroll(options = {}) {
+        const times = options.times ?? 3;
+        const delayMs = options.delayMs ?? 2000;
+        const js = `
+      async () => {
+        const maxTimes = ${times};
+        const maxWaitMs = ${delayMs};
+        for (let i = 0; i < maxTimes; i++) {
+          const lastHeight = document.body.scrollHeight;
+          window.scrollTo(0, lastHeight);
+          await new Promise(resolve => {
+            let timeoutId;
+            const observer = new MutationObserver(() => {
+              if (document.body.scrollHeight > lastHeight) {
+                clearTimeout(timeoutId);
+                observer.disconnect();
+                setTimeout(resolve, 100); // Small debounce for rendering
+              }
+            });
+            observer.observe(document.body, { childList: true, subtree: true });
+            timeoutId = setTimeout(() => {
+              observer.disconnect();
+              resolve(null);
+            }, maxWaitMs);
+          });
+        }
+      }
+    `;
+        await this.evaluate(js);
+    }
+    async installInterceptor(pattern) {
+        const js = `
+      () => {
+        window.__opencli_xhr = window.__opencli_xhr || [];
+        window.__opencli_patterns = window.__opencli_patterns || [];
+        if (!window.__opencli_patterns.includes('${pattern}')) {
+          window.__opencli_patterns.push('${pattern}');
+        }
+        
+        if (!window.__patched_xhr) {
+          const checkMatch = (url) => window.__opencli_patterns.some(p => url.includes(p));
+
+          const XHR = XMLHttpRequest.prototype;
+          const open = XHR.open;
+          const send = XHR.send;
+          XHR.open = function(method, url) {
+            this._url = url;
+            return open.call(this, method, url, ...Array.prototype.slice.call(arguments, 2));
+          };
+          XHR.send = function() {
+            this.addEventListener('load', function() {
+              if (checkMatch(this._url)) {
+                try { window.__opencli_xhr.push({url: this._url, data: JSON.parse(this.responseText)}); } catch(e){}
+              }
+            });
+            return send.apply(this, arguments);
+          };
+
+          const origFetch = window.fetch;
+          window.fetch = async function(...args) {
+            let u = typeof args[0] === 'string' ? args[0] : (args[0] && args[0].url) || '';
+            const res = await origFetch.apply(this, args);
+            setTimeout(async () => {
+              try {
+                if (checkMatch(u)) {
+                  const clone = res.clone();
+                  const j = await clone.json();
+                  window.__opencli_xhr.push({url: u, data: j});
+                }
+              } catch(e) {}
+            }, 0);
+            return res;
+          };
+          window.__patched_xhr = true;
+        }
+      }
+    `;
+        await this.evaluate(js);
+    }
+    async getInterceptedRequests() {
+        return (await this.evaluate('() => window.__opencli_xhr')) || [];
+    }
 }
 /**
  * Playwright MCP process manager.
@@ -153,7 +241,11 @@ export class PlaywrightMCP {
             throw new Error('Playwright MCP server not found. Install: npm install -D @playwright/mcp');
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => reject(new Error(`Timed out connecting to browser (${timeout}s)`)), timeout * 1000);
-            this._proc = spawn('node', [mcpPath, '--extension'], {
+            const mcpArgs = [mcpPath, '--extension'];
+            if (process.env.OPENCLI_BROWSER_EXECUTABLE_PATH) {
+                mcpArgs.push('--executablePath', process.env.OPENCLI_BROWSER_EXECUTABLE_PATH);
+            }
+            this._proc = spawn('node', mcpArgs, {
                 stdio: ['pipe', 'pipe', 'pipe'],
                 env: { ...process.env, ...(process.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN ? { PLAYWRIGHT_MCP_EXTENSION_TOKEN: process.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN } : {}) },
             });

package/dist/clis/bilibili/dynamic.d.ts

@@ -0,0 +1 @@
+export {};