@jackwener/opencli 0.4.1 → 0.4.2

package/CLI-CREATOR.md

@@ -18,66 +18,15 @@
 
 ### 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
-```
+| 步骤 | 工具 | 做什么 |
+|------|------|--------|
+| 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 写适配器 |
 
 ### 常犯错误
 
@@ -89,6 +38,27 @@ URL: https://www.bilibili.com/video/BV1xxxxx
 | 遇到 HTTP 200 但空数据就放弃 | 检查是否需要 Wbi 签名或 Cookie 鉴权 |
 | 完全依赖 `__INITIAL_STATE__` 拿所有数据 | `__INITIAL_STATE__` 只有首屏数据，深层数据要调 API |
 
+### ✅ 实战成功案例：5 分钟实现「关注列表」适配器
+
+以下是用上述工作流实际发现 Bilibili 关注列表 API 的完整过程：
+
+```
+1. browser_navigate → https://space.bilibili.com/{uid}/fans/follow
+2. browser_network_requests → 发现:
+   GET /x/relation/followings?vmid={uid}&pn=1&ps=24  →  [200]
+   GET /x/relation/stat?vmid={uid}                    →  [200]
+3. browser_evaluate → 验证 API:
+   fetch('/x/relation/followings?vmid=137702077&pn=1&ps=5', {credentials:'include'})
+   → { code: 0, data: { total: 1342, list: [{mid, uname, sign, ...}] } }
+4. 结论：标准 Cookie API，无需 Wbi 签名
+5. 写 following.ts → 一次构建通过 ✅
+```
+
+**关键决策点**：
+- 直接访问 `fans/follow` 页面（不是首页），页面加载就会触发 following API
+- 看到 URL 里没有 `/wbi/` → 不需要签名 → 直接用 `fetchJson` 而非 `apiGet`
+- API 返回 `code: 0` + 非空 `list` → Tier 2 Cookie 策略确认
+
 ---
 
 ## 核心流程
@@ -202,6 +172,45 @@ opencli cascade https://api.example.com/hot
 
 ---
 
+## Step 2.5: 准备工作（写代码之前）
+
+### 🎯 先找模板：从最相似的现有适配器开始
+
+**不要从零开始写**。先看看同站点已有哪些适配器：
+
+```bash
+ls src/clis/<site>/    # 看看已有什么
+cat src/clis/<site>/feed.ts   # 读最相似的那个
+```
+
+最高效的方式是 **复制最相似的适配器，然后改 3 个地方**：
+1. `name` → 新命令名
+2. API URL → 你在 Step 1 发现的端点
+3. 字段映射 → 对应新 API 的字段
+
+### 平台 SDK 速查表
+
+写 TS 适配器之前，先看看你的目标站点有没有**现成的 helper 函数**可以复用：
+
+#### Bilibili (`src/bilibili.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: 编写适配器
 
 ### YAML vs TS？先看决策树
@@ -224,6 +233,27 @@ opencli cascade https://api.example.com/hot
 
 > **经验法则**：如果你发现 YAML 里嵌了超过 10 行 JS，改用 TS 更可维护。
 
+### 通用模式：分页 API
+
+很多 API 使用 `pn`（页码）+ `ps`（每页数量）分页。标准处理模式：
+
+```typescript
+args: [
+  { name: 'page', type: 'int', required: false, default: 1, help: '页码' },
+  { name: 'limit', type: 'int', required: false, default: 50, help: '每页数量 (最大 50)' },
+],
+func: async (page, kwargs) => {
+  const pn = kwargs.page ?? 1;
+  const ps = Math.min(kwargs.limit ?? 50, 50); // 尊重 API 的 ps 上限
+  const payload = await fetchJson(page,
+    `https://api.example.com/list?pn=${pn}&ps=${ps}`
+  );
+  return payload.data?.list || [];
+},
+```
+
+> 💡 大多数站点的 `ps` 上限是 20~50。超过会被静默截断或返回错误。
+
 ### 方式 A: YAML Pipeline（声明式，推荐）
 
 文件路径: `src/clis/<site>/<name>.yaml`，放入即自动注册。
@@ -500,34 +530,7 @@ cli({
 
 > **拦截核心思路**：不自己构造签名，而是利用 `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();
-```
+> 💡 **级联请求**（如 BVID→CID→字幕）的完整模板和要点见下方[进阶模式: 级联请求](#进阶模式-级联请求-cascading-requests)章节。
 
 ---
 
@@ -592,68 +595,26 @@ opencli evaluate "(() => {
  └──────────────┘     └──────────────┘     └──────────────┘     └────────┘
 ```
 
-### Verbose 模式
-
-```bash
-# 查看 pipeline 每步的输入输出
-opencli bilibili hot --limit 1 -v
-```
-
-输出示例：
-```
-  [1/4] navigate → https://www.bilibili.com
-       → (no data)
-  [2/4] evaluate → (async () => { const res = await fetch(…
-       → [{title: "…", author: "…", play: 230835}]
-  [3/4] map (rank, title, author, play, danmaku)
-       → [{rank: 1, title: "…", author: "…"}]
-  [4/4] limit → 1
-       → [{rank: 1, title: "…"}]
-```
-
-### 输出格式验证
+### Verbose 模式 & 输出验证
 
 ```bash
-# 确认表格渲染正确
-opencli mysite hot -f table
-
-# 确认 JSON 可被 jq 解析
-opencli mysite hot -f json | jq '.[0]'
-
-# 确认 CSV 可被导入
-opencli mysite hot -f csv > data.csv
+opencli bilibili hot --limit 1 -v          # 查看 pipeline 每步数据流
+opencli mysite hot -f json | jq '.[0]'     # 确认 JSON 可被解析
+opencli mysite hot -f csv > data.csv       # 确认 CSV 可导入
 ```
 
 ---
 
-## Step 5: 注册 & 发布
-
-### YAML 适配器
+## Step 5: 提交发布
 
-放入 `src/clis/<site>/<name>.yaml` 即自动注册，无需额外操作。
-
-### TS 适配器
-
-放入 `src/clis/<site>/<name>.ts` 即自动加载模块，无需在 `index.ts` 中写入 `import`。
-
-### 验证注册
-
-```bash
-opencli list                     # 确认新命令出现
-opencli validate mysite          # 校验定义完整性
-```
-
-### 提交
+文件放入 `src/clis/<site>/` 即自动注册（YAML 或 TS 无需手动 import），然后：
 
 ```bash
-git add src/clis/mysite/
-git commit -m "feat(mysite): add hot and search adapters"
-git push
+opencli list | grep mysite                            # 确认注册
+git add src/clis/mysite/ && git commit -m "feat(mysite): add hot" && git push
 ```
 
-## 设计哲学: Zero-Dependency jq
-
-> 💡 **架构理念升级**: OpenCLI 的原生机制本质上内建了一个 **Zero-Dependency jq 数据处理流**。使用时不需要依赖系统命令级别的 `jq` 包，而是将所有的解析拍平动作放在 `evaluate` 块内的原生 JavaScript 里，再由外层 YAML 通过 `select`、`map` 等命令提取。这将彻底消灭跨操作系统下产生的第三方二进制库依赖。
+> 💡 **架构理念**：OpenCLI 内建 **Zero-Dependency jq** 数据流 — 所有解析在 `evaluate` 的原生 JS 内完成，外层 YAML 用 `select`/`map` 提取，无需依赖系统 `jq` 二进制。
 
 ---
 

package/dist/build-manifest.js

@@ -58,10 +58,10 @@ function scanYaml(filePath, site) {
 }
 function scanTs(filePath, site) {
     // TS adapters self-register via cli() at import time.
-    // We record their module path for lazy dynamic import.
+    // We statically parse the source to extract metadata for the manifest stub.
     const baseName = path.basename(filePath, path.extname(filePath));
     const relativePath = `${site}/${baseName}.js`;
-    return {
+    const entry = {
         site,
         name: baseName,
         description: '',
@@ -71,6 +71,66 @@ function scanTs(filePath, site) {
         type: 'ts',
         modulePath: relativePath,
     };
+    try {
+        const src = fs.readFileSync(filePath, 'utf-8');
+        // Extract description
+        const descMatch = src.match(/description\s*:\s*['"`]([^'"`]*)['"`]/);
+        if (descMatch)
+            entry.description = descMatch[1];
+        // Extract domain
+        const domainMatch = src.match(/domain\s*:\s*['"`]([^'"`]*)['"`]/);
+        if (domainMatch)
+            entry.domain = domainMatch[1];
+        // Extract strategy
+        const stratMatch = src.match(/strategy\s*:\s*Strategy\.(\w+)/);
+        if (stratMatch)
+            entry.strategy = stratMatch[1].toLowerCase();
+        // Extract columns
+        const colMatch = src.match(/columns\s*:\s*\[([^\]]*)\]/);
+        if (colMatch) {
+            entry.columns = colMatch[1].split(',').map(s => s.trim().replace(/^['"`]|['"`]$/g, '')).filter(Boolean);
+        }
+        // Extract args array items: { name: '...', ... }
+        const argsBlockMatch = src.match(/args\s*:\s*\[([\s\S]*?)\]\s*,/);
+        if (argsBlockMatch) {
+            const argsBlock = argsBlockMatch[1];
+            const argRegex = /\{\s*name\s*:\s*['"`](\w+)['"`]([^}]*)\}/g;
+            let m;
+            while ((m = argRegex.exec(argsBlock)) !== null) {
+                const argName = m[1];
+                const body = m[2];
+                const typeMatch = body.match(/type\s*:\s*['"`](\w+)['"`]/);
+                const defaultMatch = body.match(/default\s*:\s*([^,}]+)/);
+                const requiredMatch = body.match(/required\s*:\s*(true|false)/);
+                const helpMatch = body.match(/help\s*:\s*['"`]([^'"`]*)['"`]/);
+                let defaultVal = undefined;
+                if (defaultMatch) {
+                    const raw = defaultMatch[1].trim();
+                    if (raw === 'true')
+                        defaultVal = true;
+                    else if (raw === 'false')
+                        defaultVal = false;
+                    else if (/^\d+$/.test(raw))
+                        defaultVal = parseInt(raw, 10);
+                    else if (/^\d+\.\d+$/.test(raw))
+                        defaultVal = parseFloat(raw);
+                    else
+                        defaultVal = raw.replace(/^['"`]|['"`]$/g, '');
+                }
+                entry.args.push({
+                    name: argName,
+                    type: typeMatch?.[1] ?? 'str',
+                    default: defaultVal,
+                    required: requiredMatch?.[1] === 'true',
+                    help: helpMatch?.[1] ?? '',
+                });
+            }
+        }
+    }
+    catch {
+        // If parsing fails, fall back to empty metadata — module will self-register at runtime
+    }
+    return entry;
 }
 // Main
 const manifest = [];