@jackwener/opencli 0.4.1 → 0.4.3

package/CLI-CREATOR.md

@@ -5,7 +5,7 @@
 
 ---
 
-## ⚠️ AI Agent 开发者必读：用 Playwright MCP Bridge 探索
+## AI Agent 开发者必读：用 Playwright MCP Bridge 探索
 
 > [!CAUTION]
 > **你（AI Agent）必须通过 Playwright MCP Bridge 打开浏览器去访问目标网站！**  
@@ -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,40 +530,13 @@ 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)章节。
 
 ---
 
 ## Step 4: 测试
 
-> **⚠️ 构建通过 ≠ 功能正常**。`npm run build` 只验证 TypeScript / YAML 语法，不验证运行时行为。  
+> **构建通过 ≠ 功能正常**。`npm run build` 只验证 TypeScript / YAML 语法，不验证运行时行为。  
 > 每个新命令 **必须实际运行** 并确认输出正确后才算完成。
 
 ### 必做清单
@@ -552,7 +555,7 @@ opencli mysite hot --limit 3 -f json   # JSON 输出确认字段完整
 
 ### tap 步骤调试（intercept 策略专用）
 
-> **⚠️ 不要猜 store name / action name**。先用 evaluate 探索，再写 YAML。
+> **不要猜 store name / action name**。先用 evaluate 探索，再写 YAML。
 
 #### Step 1: 列出所有 Pinia store
 
@@ -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/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, jackwener
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -5,20 +5,84 @@
 
 [中文文档](./README.zh-CN.md)
 
-[![npm](https://img.shields.io/npm/v/@jackwener/opencli)](https://www.npmjs.com/package/@jackwener/opencli)
+[![npm](https://img.shields.io/npm/v/@jackwener/opencli?style=flat-square)](https://www.npmjs.com/package/@jackwener/opencli)
+[![Node.js Version](https://img.shields.io/node/v/@jackwener/opencli?style=flat-square)](https://nodejs.org)
+[![License](https://img.shields.io/npm/l/@jackwener/opencli?style=flat-square)](./LICENSE)
 
-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.
+A CLI tool that turns **any website** into a command-line interface. **57 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
-- 🚀 **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
+## Table of Contents
 
-## 🚀 Quick Start
+- [Highlights](#highlights)
+- [Prerequisites](#prerequisites)
+- [Quick Start](#quick-start)
+- [Built-in Commands](#built-in-commands)
+- [Output Formats](#output-formats)
+- [For AI Agents (Developer Guide)](#for-ai-agents-developer-guide)
+- [Troubleshooting](#troubleshooting)
+- [Releasing New Versions](#releasing-new-versions)
+- [License](#license)
+
+---
+
+## 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.
+- **Dynamic Loader** — Simply drop `.ts` or `.yaml` adapters into the `clis/` folder for auto-registration.
+- **Dual-Engine Architecture** — Supports both YAML declarative data pipelines and robust browser runtime typescript injections.
+
+## Prerequisites
+
+- **Node.js**: >= 18.0.0
+- **Chrome** running **and logged into the target site** (e.g. bilibili.com, zhihu.com, xiaohongshu.com).
+
+> **⚠️ Important**: Browser commands reuse your Chrome login session. You must be logged into the target website in Chrome before running commands. If you get empty data or errors, check your login status first.
+
+OpenCLI needs a way to communicate with your browser. We highly recommend configuring **both** of the following methods for maximum reliability.
+
+### Connection Method A: Playwright MCP Bridge Extension (Primary)
+
+1. Install **[Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm)** extension in Chrome.
+2. Obtain your token by clicking the extension icon in the browser toolbar or from the extension settings page.
+
+**You must configure this token in BOTH your MCP configuration and system environment variables.**
+
+First, add it to your MCP client config (e.g. Claude/Cursor):
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest", "--extension"],
+      "env": {
+        "PLAYWRIGHT_MCP_EXTENSION_TOKEN": "<your-token-here>"
+      }
+    }
+  }
+}
+```
+
+And, so that `opencli` commands can use it directly in the terminal, export it in your shell environment (e.g. `~/.zshrc`):
+
+```bash
+export PLAYWRIGHT_MCP_EXTENSION_TOKEN="<your-token-here>"
+```
+
+### Connection Method B: Chrome 144+ Auto-Discovery (Fallback)
+
+No extensions needed. Just enable Chrome's built-in remote debugging:
+
+1. Open `chrome://inspect#remote-debugging` in Chrome
+2. Check **"Allow remote debugging for this browser instance"**
+3. Set `OPENCLI_USE_CDP=1` before running opencli
+
+*You can also manually specify an endpoint via `OPENCLI_CDP_ENDPOINT` env var.*
+
+## Quick Start
 
 ### Install via npm (recommended)
 
@@ -30,63 +94,39 @@ Then use directly:
 
 ```bash
 opencli list                              # See all commands
+opencli list -f yaml                      # List commands as YAML
 opencli hackernews top --limit 5          # Public API, no browser
 opencli bilibili hot --limit 5            # Browser command
 opencli zhihu hot -f json                 # JSON output
+opencli zhihu hot -f yaml                 # YAML output
 ```
 
-### Install from source
+### Install from source (for developers)
 
 ```bash
 git clone git@github.com:jackwener/opencli.git
-cd opencli && npm install
-npx tsx src/main.ts list
+cd opencli 
+npm install
+npm run build
+npm link      # Link binary globally
+opencli list  # Now you can use it anywhere!
 ```
 
 ### Update
 
 ```bash
-# npm global
-npm update -g @jackwener/opencli
-
-# Or reinstall to latest
 npm install -g @jackwener/opencli@latest
 ```
 
-## 📋 Prerequisites
-
-Browser commands need:
-1. **Chrome** running **and logged into the target site** (e.g. bilibili.com, zhihu.com, xiaohongshu.com)
-2. **[Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm)** extension installed
-3. Configure `PLAYWRIGHT_MCP_EXTENSION_TOKEN` (from the extension settings page) in your MCP config:
-
-```json
-{
-  "mcpServers": {
-    "playwright": {
-      "command": "npx",
-      "args": ["@playwright/mcp@latest", "--extension"],
-      "env": {
-        "PLAYWRIGHT_MCP_EXTENSION_TOKEN": "<your-token>"
-      }
-    }
-  }
-}
-```
-
-Public API commands (`hackernews`, `github search`, `v2ex`) need no browser at all.
-
-> **⚠️ Important**: Browser commands reuse your Chrome login session. You must be logged into the target website in Chrome before running commands. If you get empty data or errors, check your login status first.
-
-## 📦 Built-in Commands
+## Built-in Commands
 
 | Site | Commands | Mode |
 |------|----------|------|
-| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` `subtitle` `dynamic` `ranking` `following` | 🔐 Browser |
+| **bilibili** | `hot` `search` `me` `favorite` ... (11 commands) | 🔐 Browser |
 | **zhihu** | `hot` `search` `question` | 🔐 Browser |
 | **xiaohongshu** | `search` `notifications` `feed` `me` `user` | 🔐 Browser |
 | **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 🔐 Browser |
-| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` | 🔐 Browser |
+| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` `following` `followers` `notifications` `post` `reply` `delete` `like` | 🔐 Browser |
 | **reddit** | `hot` `frontpage` `search` `subreddit` | 🔐 Browser |
 | **weibo** | `hot` | 🔐 Browser |
 | **boss** | `search` | 🔐 Browser |
@@ -100,17 +140,27 @@ Public API commands (`hackernews`, `github search`, `v2ex`) need no browser at a
 | **hackernews** | `top` | 🌐 Public |
 | **bbc** | `news` | 🌐 Public |
 
-## 🎨 Output Formats
+## Output Formats
+
+All built-in commands support `--format` / `-f` with `table`, `json`, `yaml`, `md`, and `csv`.
+The `list` command supports the same format options, and keeps `--json` for backward compatibility.
 
 ```bash
-opencli bilibili hot -f table   # Default: rich table
-opencli bilibili hot -f json    # JSON (pipe to jq, feed to AI)
+opencli list -f yaml            # Command registry as YAML
+opencli bilibili hot -f table   # Default: rich terminal table
+opencli bilibili hot -f json    # JSON (pipe to jq or LLMs)
+opencli bilibili hot -f yaml    # YAML (human-readable structured output)
 opencli bilibili hot -f md      # Markdown
 opencli bilibili hot -f csv     # CSV
-opencli bilibili hot -v         # Verbose: show pipeline steps
+opencli bilibili hot -v         # Verbose: show pipeline debug steps
 ```
 
-## 🧠 AI Agent Workflow
+## For AI Agents (Developer Guide)
+
+If you are an AI assistant tasked with creating a new command adapter for `opencli`, please follow the AI Agent workflow below:
+
+> **Information for AI:** 
+> Before writing any adapter code, you **must** read [CLI-CREATOR.md](./CLI-CREATOR.md). It contains the complete browser exploration workflow, the 5-tier authentication strategy decision tree, and debugging guide. Skipping this will lead to preventable errors.
 
 ```bash
 # 1. Deep Explore — discover APIs, infer capabilities, detect framework
@@ -126,30 +176,30 @@ opencli generate https://example.com --goal "hot"
 opencli cascade https://api.example.com/data
 ```
 
-Explore outputs to `.opencli/explore/<site>/`:
-- `manifest.json` — site metadata, framework detection
-- `endpoints.json` — scored API endpoints with response schemas
-- `capabilities.json` — inferred capabilities with confidence scores
-- `auth.json` — authentication strategy recommendations
+Explore outputs to `.opencli/explore/<site>/` (manifest.json, endpoints.json, capabilities.json, auth.json).
 
-## 🔧 Create New Commands
+## Troubleshooting
 
-See **[CLI-CREATOR.md](./CLI-CREATOR.md)** for the full adapter guide (YAML pipeline + TypeScript).
+- **"Failed to connect to Playwright MCP Bridge"**
+  - Ensure the Playwright MCP extension is installed and **enabled** in your running Chrome.
+  - Restart the Chrome browser if you just installed the extension.
+- **"CDP command failed" or "boss search blocked"**
+  - Some sites (like BOSS Zhipin) actively block Chrome DevTools Protocol connections. OpenCLI falls back to cookie extraction, but ensure you didn't force `--chrome-mode` unnecessarily. 
+- **Empty data returns or 'Unauthorized' error**
+  - Your login session in Chrome might have expired. Open a normal Chrome tab, navigate to the target site, and log in or refresh the page to prove you are human.
+- **Node API errors**
+  - Make sure you are using Node.js >= 18. Some dependencies require modern Node APIs.
 
 ## Releasing New Versions
 
 ```bash
-# Bump version
 npm version patch   # 0.1.0 → 0.1.1
 npm version minor   # 0.1.0 → 0.2.0
-npm version major   # 0.1.0 → 1.0.0
-
-# Push tag to trigger GitHub Actions auto-release
 git push --follow-tags
 ```
 
 The CI will automatically build, create a GitHub release, and publish to npm.
 
-## 📄 License
+## License
 
-MIT
+[BSD-3-Clause](./LICENSE)