@jackwener/opencli 0.4.2 → 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 打开浏览器去访问目标网站！**  
@@ -38,7 +38,7 @@
 | 遇到 HTTP 200 但空数据就放弃 | 检查是否需要 Wbi 签名或 Cookie 鉴权 |
 | 完全依赖 `__INITIAL_STATE__` 拿所有数据 | `__INITIAL_STATE__` 只有首屏数据，深层数据要调 API |
 
-### ✅ 实战成功案例：5 分钟实现「关注列表」适配器
+### 实战成功案例：5 分钟实现「关注列表」适配器
 
 以下是用上述工作流实际发现 Bilibili 关注列表 API 的完整过程：
 
@@ -51,7 +51,7 @@
    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 → 一次构建通过 ✅
+5. 写 following.ts → 一次构建通过
 ```
 
 **关键决策点**：
@@ -174,7 +174,7 @@ opencli cascade https://api.example.com/hot
 
 ## Step 2.5: 准备工作（写代码之前）
 
-### 🎯 先找模板：从最相似的现有适配器开始
+### 先找模板：从最相似的现有适配器开始
 
 **不要从零开始写**。先看看同站点已有哪些适配器：
 
@@ -207,7 +207,7 @@ cat src/clis/<site>/feed.ts   # 读最相似的那个
 - 含 `/wbi/` 或 `w_rid=` → 必须用 `apiGet(..., { signed: true })`
 - 不含 → 直接用 `fetchJson`
 
-> 💡 其他站点（Twitter、小红书等）暂无专用 SDK，直接用 `page.evaluate` + `fetch` 即可。
+> 其他站点（Twitter、小红书等）暂无专用 SDK，直接用 `page.evaluate` + `fetch` 即可。
 
 ---
 
@@ -252,7 +252,7 @@ func: async (page, kwargs) => {
 },
 ```
 
-> 💡 大多数站点的 `ps` 上限是 20~50。超过会被静默截断或返回错误。
+> 大多数站点的 `ps` 上限是 20~50。超过会被静默截断或返回错误。
 
 ### 方式 A: YAML Pipeline（声明式，推荐）
 
@@ -530,13 +530,13 @@ cli({
 
 > **拦截核心思路**：不自己构造签名，而是利用 `installInterceptor` 劫持网站自己的 `XMLHttpRequest` 和 `fetch`，让网站发请求，我们直接在底层取出解析好的 `response.json()`。
 
-> 💡 **级联请求**（如 BVID→CID→字幕）的完整模板和要点见下方[进阶模式: 级联请求](#进阶模式-级联请求-cascading-requests)章节。
+> **级联请求**（如 BVID→CID→字幕）的完整模板和要点见下方[进阶模式: 级联请求](#进阶模式-级联请求-cascading-requests)章节。
 
 ---
 
 ## Step 4: 测试
 
-> **⚠️ 构建通过 ≠ 功能正常**。`npm run build` 只验证 TypeScript / YAML 语法，不验证运行时行为。  
+> **构建通过 ≠ 功能正常**。`npm run build` 只验证 TypeScript / YAML 语法，不验证运行时行为。  
 > 每个新命令 **必须实际运行** 并确认输出正确后才算完成。
 
 ### 必做清单
@@ -555,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
 
@@ -614,7 +614,7 @@ opencli list | grep mysite                            # 确认注册
 git add src/clis/mysite/ && git commit -m "feat(mysite): add hot" && git push
 ```
 
-> 💡 **架构理念**：OpenCLI 内建 **Zero-Dependency jq** 数据流 — 所有解析在 `evaluate` 的原生 JS 内完成，外层 YAML 用 `select`/`map` 提取，无需依赖系统 `jq` 二进制。
+> **架构理念**：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)

package/README.zh-CN.md

@@ -5,21 +5,84 @@
 
 [English](./README.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)
 
-OpenCLI 通过 Chrome 浏览器 + [Playwright MCP Bridge](https://github.com/nichochar/playwright-mcp) 扩展，将任何网站变成命令行工具。不存密码、不泄 token，直接复用浏览器已登录状态。
+OpenCLI 通过 Chrome 浏览器 + [Playwright MCP Bridge](https://github.com/nichochar/playwright-mcp) 扩展，将任何网站变成命令行工具。57个内置命令。不存密码、不泄 token，直接复用浏览器已登录状态。
 
-## ✨ 亮点
+---
 
-- 🌐 **47 个命令，17 个站点** — B站、知乎、小红书、Twitter、Reddit、雪球(xueqiu)、GitHub、V2EX、Hacker News、BBC、微博、BOSS直聘、Yahoo Finance、路透社、什么值得买、携程、YouTube
-- 🔐 **零风控** — 复用 Chrome 登录态，无需存储任何凭证
-- 🤖 **AI 原生** — `explore` 自动发现 API，`synthesize` 生成适配器，`cascade` 探测认证策略
-- 🚀 **动态加载引擎** — 只需将 `.ts` 或 `.yaml` 适配器放入 `clis/` 文件夹即可自动注册生效
-- 📝 **双引擎架构设计**:
-  - **YAML 声明式引擎**：大部分适配器只需极简的 ~30 行 YAML 声明
-  - **原生浏览器注入引擎**：提供高级 TS API（`installInterceptor`、`autoScroll`）轻松实现 XHR 劫持、GraphQL 解包及状态库注入
+## 目录
 
-## 🚀 快速开始
+- [亮点](#亮点)
+- [前置要求](#前置要求)
+- [快速开始](#快速开始)
+- [内置命令](#内置命令)
+- [输出格式](#输出格式)
+- [致 AI Agent（开发者指南）](#致-ai-agent开发者指南)
+- [常见问题排查](#常见问题排查)
+- [版本发布](#版本发布)
+- [License](#license)
+
+---
+
+## 亮点
+
+- **57 个命令，17 个站点** — B站、知乎、小红书、Twitter、Reddit、雪球(xueqiu)、GitHub、V2EX、Hacker News、BBC、微博、BOSS直聘、Yahoo Finance、路透社、什么值得买、携程、YouTube
+- **零风控** — 复用 Chrome 登录态，无需存储任何凭证
+- **AI 原生** — `explore` 自动发现 API，`synthesize` 生成适配器，`cascade` 探测认证策略
+- **动态加载引擎** — 声明式的 `.yaml` 或者底层定制的 `.ts` 适配器，放入 `clis/` 文件夹即可自动注册生效
+
+## 前置要求
+
+- **Node.js**: >= 18.0.0
+- **Chrome** 浏览器正在运行，且**已登录目标网站**（如 bilibili.com、zhihu.com、xiaohongshu.com）
+
+> **⚠️ 重要**：大多数命令复用你的 Chrome 登录状态。运行命令前，你必须已在 Chrome 中打开目标网站并完成登录。如果获取到空数据或报错，请先检查你的浏览器登录状态。
+
+为了让 OpenCLI 能够联通你的浏览器，你需要配置连接方式。**强烈建议以下两种方式都配置上**，互为后备：
+
+### 连接方式 A：Playwright MCP Bridge 扩展（首选）
+
+1. 安装 **[Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm)** 扩展
+2. 在浏览器插件栏点击该插件，或者在插件设置页获取你的 Extension Token。
+
+**你必须将这个 Token 同时配置到你的 MCP 配置文件以及环境变量中。**
+
+首先，配置你的 MCP 客户端（如 Claude/Cursor 等）：
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest", "--extension"],
+      "env": {
+        "PLAYWRIGHT_MCP_EXTENSION_TOKEN": "<你的-token>"
+      }
+    }
+  }
+}
+```
+
+并且，为了让 `opencli` 命令行也能直接使用它，你必须在你的终端系统环境变量中导出它（建议写进 `~/.zshrc` 或 `~/.bashrc`）：
+
+```bash
+export PLAYWRIGHT_MCP_EXTENSION_TOKEN="<你的-token>"
+```
+
+### 连接方式 B：Chrome 144+ CDP 自动发现（备选）
+
+无需安装任何扩展。只需开启 Chrome 内置的远程调试：
+
+1. 在 Chrome 中打开 `chrome://inspect#remote-debugging`
+2. 勾选 **"允许对此浏览器实例进行远程调试" (Allow remote debugging for this browser instance)**
+3. 运行时设置环境变量 `OPENCLI_USE_CDP=1`
+
+*也可通过 `OPENCLI_CDP_ENDPOINT` 环境变量手动指定 CDP endpoint 地址。*
+
+## 快速开始
 
 ### npm 全局安装（推荐）
 
@@ -31,63 +94,39 @@ npm install -g @jackwener/opencli
 
 ```bash
 opencli list                              # 查看所有命令
+opencli list -f yaml                      # 以 YAML 列出所有命令
 opencli hackernews top --limit 5          # 公共 API，无需浏览器
 opencli bilibili hot --limit 5            # 浏览器命令
 opencli zhihu hot -f json                 # JSON 输出
+opencli zhihu hot -f yaml                 # YAML 输出
 ```
 
-### 从源码安装
+### 从源码安装（面向开发者）
 
 ```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      # 链接到全局环境
+opencli list  # 可以在任何地方使用了！
 ```
 
 ### 更新
 
 ```bash
-# npm 全局更新
-npm update -g @jackwener/opencli
-
-# 或直接安装最新版
 npm install -g @jackwener/opencli@latest
 ```
 
-## 📋 前置要求
-
-浏览器命令需要：
-1. **Chrome** 浏览器正在运行，且**已登录目标网站**（如 bilibili.com、zhihu.com、xiaohongshu.com）
-2. 安装 **[Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm)** 扩展
-3. 在 MCP 配置中设置 `PLAYWRIGHT_MCP_EXTENSION_TOKEN`（从扩展设置页获取）：
-
-```json
-{
-  "mcpServers": {
-    "playwright": {
-      "command": "npx",
-      "args": ["@playwright/mcp@latest", "--extension"],
-      "env": {
-        "PLAYWRIGHT_MCP_EXTENSION_TOKEN": "<your-token>"
-      }
-    }
-  }
-}
-```
-
-公共 API 命令（`hackernews`、`github search`、`v2ex`）无需浏览器。
-
-> **⚠️ 重要**：浏览器命令复用你的 Chrome 登录状态。运行命令前，你必须已在 Chrome 中登录目标网站。如果获取到空数据或报错，请先检查登录状态。
-
-## 📦 内置命令
+## 内置命令
 
 | 站点 | 命令 | 模式 |
 |------|------|------|
-| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `user-videos` `subtitle` `dynamic` `ranking` `following` | 🔐 浏览器 |
+| **bilibili** | `hot` `search` `me` `favorite` ...（共11个） | 🔐 浏览器 |
 | **zhihu** | `hot` `search` `question` | 🔐 浏览器 |
 | **xiaohongshu** | `search` `notifications` `feed` `me` `user` | 🔐 浏览器 |
 | **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 🔐 浏览器 |
-| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` | 🔐 浏览器 |
+| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` `following` `followers` `notifications` `post` `reply` `delete` `like` | 🔐 浏览器 |
 | **reddit** | `hot` `frontpage` `search` `subreddit` | 🔐 浏览器 |
 | **weibo** | `hot` | 🔐 浏览器 |
 | **boss** | `search` | 🔐 浏览器 |
@@ -101,17 +140,27 @@ npm install -g @jackwener/opencli@latest
 | **hackernews** | `top` | 🌐 公共 API |
 | **bbc** | `news` | 🌐 公共 API |
 
-## 🎨 输出格式
+## 输出格式
+
+所有内置命令都支持 `--format` / `-f`，可选值为 `table`、`json`、`yaml`、`md`、`csv`。
+`list` 命令也支持同样的格式参数，同时继续兼容 `--json`。
 
 ```bash
-opencli bilibili hot -f table   # 默认：表格
-opencli bilibili hot -f json    # JSON（可 pipe 给 jq 或 AI agent）
+opencli list -f yaml            # 用 YAML 列出命令注册表
+opencli bilibili hot -f table   # 默认：富文本表格
+opencli bilibili hot -f json    # JSON（适合传给 jq 或者各类 AI Agent）
+opencli bilibili hot -f yaml    # YAML（更适合人类直接阅读）
 opencli bilibili hot -f md      # Markdown
 opencli bilibili hot -f csv     # CSV
-opencli bilibili hot -v         # 详细模式：展示 pipeline 每步数据
+opencli bilibili hot -v         # 详细模式：展示管线执行步骤调试信息
 ```
 
-## 🧠 AI Agent 工作流
+## 致 AI Agent（开发者指南）
+
+如果你是一个被要求查阅代码并编写新 `opencli` 适配器的 AI，请遵守以下工作流。
+
+> **给 AI 的提示：**
+> 在编写任何新代码前，你**必须首先阅读 [CLI-CREATOR.md](./CLI-CREATOR.md)**。它包含了完整的适配器开发指南、API 探测流程、5级认证策略以及常见陷阱。如果你跳过这一步直接写代码，会导致很多不必要的错误。
 
 ```bash
 # 1. Deep Explore — 网络拦截 → 响应分析 → 能力推理 → 框架检测
@@ -127,28 +176,30 @@ opencli generate https://example.com --goal "hot"
 opencli cascade https://api.example.com/data
 ```
 
-探索结果输出到 `.opencli/explore/<site>/`：
-- `manifest.json` — 站点元数据、框架检测结果
-- `endpoints.json` — 评分排序的 API 端点，含响应 schema
-- `capabilities.json` — 推理出的能力及置信度
-- `auth.json` — 认证策略建议
+探索结果输出到 `.opencli/explore/<site>/`。
 
-## 🔧 创建新命令
+## 常见问题排查
 
-查看 **[CLI-CREATOR.md](./CLI-CREATOR.md)** 了解完整的适配器开发指南（YAML pipeline + TypeScript）。
+- **"Failed to connect to Playwright MCP Bridge"** 报错
+  - 确保你当前的 Chrome 已安装且**开启了** Playwright MCP Bridge 浏览器插件。
+  - 如果是刚装完插件，需要重启 Chrome 浏览器。
+- **"CDP command failed" / "被风控拦截"**
+  - 有些网站（例如 BOSS 直聘）会因为开了 DevTools 或者 CDP 端口拦截验证。OpenCLI 有 cookie 降级机制，通常不需要干预，不用去强行加上 CDP 标识参数即可。
+- **返回空数据，或者报错 "Unauthorized"**
+  - Chrome 里的登录态可能已经过期（甚至被要求过滑动验证码）。请打开当前 Chrome 页面，在新标签页重新手工登录或刷新该页面。
+- **Node API 错误 (如 parseArgs, fs 等)**
+  - 确保 Node.js 版本 `>= 18`。旧版不支持我们使用的现代核心库 API。
 
 ## 版本发布
 
 ```bash
-# 升级版本号
 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
 
-# 推送 tag，GitHub Actions 自动发 release 并发布到 npm
+# 推送 tag，GitHub Actions 将自动执行发版和 npm 发布
 git push --follow-tags
 ```
 
-## 📄 License
+## License
 
-MIT
+[BSD-3-Clause](./LICENSE)