@jackwener/opencli 0.4.0 → 0.4.1

package/CLI-CREATOR.md

@@ -3,6 +3,94 @@
 > 本文档教你（或 AI Agent）如何为 OpenCLI 添加一个新网站的命令。  
 > 从零到发布，覆盖 API 发现、方案选择、适配器编写、测试验证全流程。
 
+---
+
+## ⚠️ AI Agent 开发者必读：用 Playwright MCP Bridge 探索
+
+> [!CAUTION]
+> **你（AI Agent）必须通过 Playwright MCP Bridge 打开浏览器去访问目标网站！**  
+> 不要只靠 `opencli explore` 命令或静态分析来发现 API。  
+> 你拥有 Playwright MCP 工具，必须主动用它们浏览网页、观察网络请求、模拟用户交互。
+
+### 为什么？
+
+很多 API 是**懒加载**的（用户必须点击某个按钮/标签才会触发网络请求）。字幕、评论、关注列表等深层数据不会在页面首次加载时出现在 Network 面板中。**如果你不主动去浏览和交互页面，你永远发现不了这些 API。**
+
+### AI Agent 探索工作流（必须遵循）
+
+```
+ Step 0: 用 Playwright MCP 打开浏览器
+   ↓
+ Step 1: 导航到目标页面，观察页面结构
+   ↓
+ Step 2: 查看 Network 请求（browser_network_requests）
+   ↓
+ Step 3: 模拟用户交互（点击按钮/标签/展开评论）
+   ↓
+ Step 4: 再次查看 Network，发现新触发的 API
+   ↓
+ Step 5: 分析 API 的请求参数、响应结构、鉴权方式
+   ↓
+ Step 6: 编写适配器代码
+```
+
+### 具体操作步骤
+
+**Step 0: 打开浏览器**
+```
+工具: browser_navigate
+URL: https://www.bilibili.com/video/BV1xxxxx
+```
+
+**Step 1: 获取页面快照，了解页面结构**
+```
+工具: browser_snapshot
+→ 观察页面上有哪些可交互元素（按钮、标签、链接）
+```
+
+**Step 2: 查看已有的网络请求**
+```
+工具: browser_network_requests
+→ 筛选出 JSON API 端点（忽略静态资源）
+→ 记录 URL pattern、请求头、响应结构
+```
+
+**Step 3: 模拟用户交互发现深层 API**
+```
+工具: browser_click (点击"字幕"按钮、"评论"标签、"关注"链接等)
+工具: browser_wait_for (等待数据加载)
+```
+
+**Step 4: 再次抓包，发现新 API**
+```
+工具: browser_network_requests
+→ 对比 Step 2，找出新触发的 API 端点
+```
+
+**Step 5: 用 evaluate 测试 API 可行性**
+```
+工具: browser_evaluate
+代码: async () => {
+  const res = await fetch('https://api.bilibili.com/x/player/wbi/v2?bvid=BV1xxx&cid=123', 
+    { credentials: 'include' });
+  return await res.json();
+}
+→ 验证返回的数据结构和字段
+→ 如果返回空/403：检查是否需要签名（Wbi）或特殊 Header
+```
+
+### 常犯错误
+
+| ❌ 错误做法 | ✅ 正确做法 |
+|------------|------------|
+| 只用 `opencli explore` 命令，等结果自动出来 | 用 MCP Bridge 打开浏览器，主动浏览页面 |
+| 直接在代码里 `fetch(url)`，不看浏览器实际请求 | 先在浏览器中确认 API 可用，再写代码 |
+| 页面打开后直接抓包，期望所有 API 都出现 | 模拟点击交互（展开评论/切换标签/加载更多） |
+| 遇到 HTTP 200 但空数据就放弃 | 检查是否需要 Wbi 签名或 Cookie 鉴权 |
+| 完全依赖 `__INITIAL_STATE__` 拿所有数据 | `__INITIAL_STATE__` 只有首屏数据，深层数据要调 API |
+
+---
+
 ## 核心流程
 
 ```

package/README.md

@@ -7,7 +7,7 @@
 
 [![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. **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.
+A CLI tool that turns **any website** into a command-line interface. **47 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
 
@@ -82,7 +82,7 @@ Public API commands (`hackernews`, `github search`, `v2ex`) need no browser at a
 
 | Site | Commands | Mode |
 |------|----------|------|
-| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` `subtitle` `dynamic` `ranking` | 🔐 Browser |
+| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` `subtitle` `dynamic` `ranking` `following` | 🔐 Browser |
 | **zhihu** | `hot` `search` `question` | 🔐 Browser |
 | **xiaohongshu** | `search` `notifications` `feed` `me` `user` | 🔐 Browser |
 | **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 🔐 Browser |
@@ -95,7 +95,7 @@ Public API commands (`hackernews`, `github search`, `v2ex`) need no browser at a
 | **reuters** | `search` | 🔐 Browser |
 | **smzdm** | `search` | 🔐 Browser |
 | **ctrip** | `search` | 🔐 Browser |
-| **github** | `trending` `search` | 🔐 / 🌐 |
+| **github** | `search` | 🌐 Public |
 | **v2ex** | `hot` `latest` `topic` | 🌐 Public |
 | **hackernews** | `top` | 🌐 Public |
 | **bbc** | `news` | 🌐 Public |

package/README.zh-CN.md

@@ -11,7 +11,7 @@ OpenCLI 通过 Chrome 浏览器 + [Playwright MCP Bridge](https://github.com/nic
 
 ## ✨ 亮点
 
-- 🌐 **46 个命令，17 个站点** — B站、知乎、小红书、Twitter、Reddit、雪球(xueqiu)、GitHub、V2EX、Hacker News、BBC、微博、BOSS直聘、Yahoo Finance、路透社、什么值得买、携程、YouTube
+- 🌐 **47 个命令，17 个站点** — B站、知乎、小红书、Twitter、Reddit、雪球(xueqiu)、GitHub、V2EX、Hacker News、BBC、微博、BOSS直聘、Yahoo Finance、路透社、什么值得买、携程、YouTube
 - 🔐 **零风控** — 复用 Chrome 登录态，无需存储任何凭证
 - 🤖 **AI 原生** — `explore` 自动发现 API，`synthesize` 生成适配器，`cascade` 探测认证策略
 - 🚀 **动态加载引擎** — 只需将 `.ts` 或 `.yaml` 适配器放入 `clis/` 文件夹即可自动注册生效
@@ -83,7 +83,7 @@ npm install -g @jackwener/opencli@latest
 
 | 站点 | 命令 | 模式 |
 |------|------|------|
-| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` `subtitle` `dynamic` `ranking` | 🔐 浏览器 |
+| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` `subtitle` `dynamic` `ranking` `following` | 🔐 浏览器 |
 | **zhihu** | `hot` `search` `question` | 🔐 浏览器 |
 | **xiaohongshu** | `search` `notifications` `feed` `me` `user` | 🔐 浏览器 |
 | **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 🔐 浏览器 |
@@ -96,7 +96,7 @@ npm install -g @jackwener/opencli@latest
 | **reuters** | `search` | 🔐 浏览器 |
 | **smzdm** | `search` | 🔐 浏览器 |
 | **ctrip** | `search` | 🔐 浏览器 |
-| **github** | `trending` `search` | 🔐 / 🌐 |
+| **github** | `search` | 🌐 公共 API |
 | **v2ex** | `hot` `latest` `topic` | 🌐 公共 API |
 | **hackernews** | `top` | 🌐 公共 API |
 | **bbc** | `news` | 🌐 公共 API |

package/SKILL.md

@@ -52,6 +52,7 @@ opencli bilibili user-videos --uid 12345  # 用户投稿
 opencli bilibili subtitle --bvid BV1xxx   # 获取视频字幕 (支持 --lang zh-CN)
 opencli bilibili dynamic --limit 10       # 动态
 opencli bilibili ranking --limit 10       # 排行榜
+opencli bilibili following --limit 20     # 我的关注列表 (支持 --uid 查看他人)
 
 # 知乎 (browser)
 opencli zhihu hot --limit 10             # 知乎热榜
@@ -70,9 +71,10 @@ opencli xueqiu hot-stock --limit 10      # 雪球热门股票榜
 opencli xueqiu stock --symbol SH600519   # 查看股票实时行情
 opencli xueqiu watchlist                 # 获取自选股/持仓列表
 opencli xueqiu feed                      # 我的关注 timeline
+opencli xueqiu hot --limit 10            # 雪球热榜
+opencli xueqiu search --keyword "特斯拉"  # 搜索
 
-# GitHub (trending=browser, search=public)
-opencli github trending --limit 10       # GitHub Trending
+# GitHub (public)
 opencli github search --keyword "cli"    # 搜索仓库
 
 # Twitter/X (browser)

package/dist/build-manifest.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Build-time CLI manifest compiler.
+ *
+ * Scans all YAML/TS CLI definitions and pre-compiles them into a single
+ * manifest.json for instant cold-start registration (no runtime YAML parsing).
+ *
+ * Usage: npx tsx src/build-manifest.ts
+ * Output: dist/cli-manifest.json
+ */
+export {};

package/dist/build-manifest.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Build-time CLI manifest compiler.
+ *
+ * Scans all YAML/TS CLI definitions and pre-compiles them into a single
+ * manifest.json for instant cold-start registration (no runtime YAML parsing).
+ *
+ * Usage: npx tsx src/build-manifest.ts
+ * Output: dist/cli-manifest.json
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLIS_DIR = path.resolve(__dirname, 'clis');
+const OUTPUT = path.resolve(__dirname, '..', 'dist', 'cli-manifest.json');
+function scanYaml(filePath, site) {
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const def = yaml.load(raw);
+        if (!def || typeof def !== 'object')
+            return null;
+        const strategyStr = def.strategy ?? (def.browser === false ? 'public' : 'cookie');
+        const strategy = strategyStr.toUpperCase();
+        const browser = def.browser ?? (strategy !== 'PUBLIC');
+        const args = [];
+        if (def.args && typeof def.args === 'object') {
+            for (const [argName, argDef] of Object.entries(def.args)) {
+                args.push({
+                    name: argName,
+                    type: argDef?.type ?? 'str',
+                    default: argDef?.default,
+                    required: argDef?.required ?? false,
+                    help: argDef?.description ?? argDef?.help ?? '',
+                    choices: argDef?.choices,
+                });
+            }
+        }
+        return {
+            site: def.site ?? site,
+            name: def.name ?? path.basename(filePath, path.extname(filePath)),
+            description: def.description ?? '',
+            domain: def.domain,
+            strategy: strategy.toLowerCase(),
+            browser,
+            args,
+            columns: def.columns,
+            pipeline: def.pipeline,
+            timeout: def.timeout,
+            type: 'yaml',
+        };
+    }
+    catch (err) {
+        process.stderr.write(`Warning: failed to parse ${filePath}: ${err.message}\n`);
+        return null;
+    }
+}
+function scanTs(filePath, site) {
+    // TS adapters self-register via cli() at import time.
+    // We record their module path for lazy dynamic import.
+    const baseName = path.basename(filePath, path.extname(filePath));
+    const relativePath = `${site}/${baseName}.js`;
+    return {
+        site,
+        name: baseName,
+        description: '',
+        strategy: 'cookie',
+        browser: true,
+        args: [],
+        type: 'ts',
+        modulePath: relativePath,
+    };
+}
+// Main
+const manifest = [];
+if (fs.existsSync(CLIS_DIR)) {
+    for (const site of fs.readdirSync(CLIS_DIR)) {
+        const siteDir = path.join(CLIS_DIR, site);
+        if (!fs.statSync(siteDir).isDirectory())
+            continue;
+        for (const file of fs.readdirSync(siteDir)) {
+            const filePath = path.join(siteDir, file);
+            if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+                const entry = scanYaml(filePath, site);
+                if (entry)
+                    manifest.push(entry);
+            }
+            else if ((file.endsWith('.ts') && !file.endsWith('.d.ts') && file !== 'index.ts') ||
+                (file.endsWith('.js') && !file.endsWith('.d.js') && file !== 'index.js')) {
+                manifest.push(scanTs(filePath, site));
+            }
+        }
+    }
+}
+// Ensure output directory exists
+fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
+fs.writeFileSync(OUTPUT, JSON.stringify(manifest, null, 2));
+const yamlCount = manifest.filter(e => e.type === 'yaml').length;
+const tsCount = manifest.filter(e => e.type === 'ts').length;
+console.log(`✅ Manifest compiled: ${manifest.length} entries (${yamlCount} YAML, ${tsCount} TS) → ${OUTPUT}`);