@jackwener/opencli 0.4.2 → 0.4.4

package/{CLI-CREATOR.md → CLI-EXPLORER.md}

@@ -1,11 +1,15 @@
-# CLI-CREATOR — 适配器开发完全指南
+# CLI-EXPLORER — 适配器探索式开发完全指南
 
 > 本文档教你（或 AI Agent）如何为 OpenCLI 添加一个新网站的命令。  
 > 从零到发布，覆盖 API 发现、方案选择、适配器编写、测试验证全流程。
 
+> [!TIP]
+> **只想为一个具体页面快速生成一个命令？** 看 [CLI-ONESHOT.md](./CLI-ONESHOT.md)（~150 行，4 步搞定）。
+> 本文档适合从零探索一个新站点的完整流程。
+
 ---
 
-## ⚠️ AI Agent 开发者必读：用 Playwright MCP Bridge 探索
+## AI Agent 开发者必读：用 Playwright MCP Bridge 探索
 
 > [!CAUTION]
 > **你（AI Agent）必须通过 Playwright MCP Bridge 打开浏览器去访问目标网站！**  
@@ -38,7 +42,7 @@
 | 遇到 HTTP 200 但空数据就放弃 | 检查是否需要 Wbi 签名或 Cookie 鉴权 |
 | 完全依赖 `__INITIAL_STATE__` 拿所有数据 | `__INITIAL_STATE__` 只有首屏数据，深层数据要调 API |
 
-### ✅ 实战成功案例：5 分钟实现「关注列表」适配器
+### 实战成功案例：5 分钟实现「关注列表」适配器
 
 以下是用上述工作流实际发现 Bilibili 关注列表 API 的完整过程：
 
@@ -51,7 +55,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 +178,7 @@ opencli cascade https://api.example.com/hot
 
 ## Step 2.5: 准备工作（写代码之前）
 
-### 🎯 先找模板：从最相似的现有适配器开始
+### 先找模板：从最相似的现有适配器开始
 
 **不要从零开始写**。先看看同站点已有哪些适配器：
 
@@ -207,7 +211,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 +256,7 @@ func: async (page, kwargs) => {
 },
 ```
 
-> 💡 大多数站点的 `ps` 上限是 20~50。超过会被静默截断或返回错误。
+> 大多数站点的 `ps` 上限是 20~50。超过会被静默截断或返回错误。
 
 ### 方式 A: YAML Pipeline（声明式，推荐）
 
@@ -530,13 +534,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 +559,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 +618,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/CLI-ONESHOT.md

@@ -0,0 +1,216 @@
+# CLI-ONESHOT — 单点快速 CLI 生成
+
+> 给一个 URL + 一句话描述，4 步生成一个 CLI 命令。
+> 完整探索式开发请看 [CLI-EXPLORER.md](./CLI-EXPLORER.md)。
+
+---
+
+## 输入
+
+| 项目 | 示例 |
+|------|------|
+| **URL** | `https://x.com/jakevin7/lists` |
+| **Goal** | 获取我的 Twitter Lists |
+
+---
+
+## 流程
+
+### Step 1: 打开页面 + 抓包
+
+```
+1. browser_navigate → 打开目标 URL
+2. 等待 3-5 秒（让页面加载完、API 请求触发）
+3. browser_network_requests → 筛选 JSON API
+```
+
+**关键**：只关注返回 `application/json` 的请求，忽略静态资源。
+如果没有自动触发 API，手动点击目标按钮/标签再抓一次。
+
+### Step 2: 锁定一个接口
+
+从抓包结果中找到**那个**目标 API。看这几个字段：
+
+| 字段 | 关注什么 |
+|------|----------|
+| URL | API 路径 pattern（如 `/i/api/graphql/xxx/ListsManagePinTimeline`） |
+| Method | GET / POST |
+| Headers | 有 Cookie? Bearer? CSRF? 自定义签名? |
+| Response | 数据在哪个路径（如 `data.list.lists`） |
+
+### Step 3: 验证接口能复现
+
+在 `browser_evaluate` 中用 `fetch` 复现请求：
+
+```javascript
+// Tier 2 (Cookie): 大多数情况
+fetch('/api/endpoint', { credentials: 'include' }).then(r => r.json())
+
+// Tier 3 (Header): 如 Twitter 需要额外 header
+const ct0 = document.cookie.match(/ct0=([^;]+)/)?.[1];
+fetch('/api/endpoint', {
+  headers: { 'Authorization': 'Bearer ...', 'X-Csrf-Token': ct0 },
+  credentials: 'include'
+}).then(r => r.json())
+```
+
+如果 fetch 能拿到数据 → 用 YAML 或简单 TS adapter。
+如果 fetch 拿不到（签名/风控）→ 用 intercept 策略。
+
+### Step 4: 套模板，生成 adapter
+
+根据 Step 3 判定的策略，选一个模板生成文件。
+
+---
+
+## 认证速查
+
+```
+fetch(url) 直接能拿到？              → Tier 1: public   (YAML, browser: false)
+fetch(url, {credentials:'include'})？ → Tier 2: cookie   (YAML)
+加 Bearer/CSRF header 后拿到？        → Tier 3: header   (TS)
+都不行，但页面自己能请求成功？          → Tier 4: intercept (TS, installInterceptor)
+```
+
+---
+
+## 模板
+
+### YAML — Cookie/Public（最简）
+
+```yaml
+# src/clis/<site>/<name>.yaml
+site: mysite
+name: mycommand
+description: "一句话描述"
+domain: www.example.com
+strategy: cookie          # 或 public (加 browser: false)
+
+args:
+  limit:
+    type: int
+    default: 20
+
+pipeline:
+  - navigate: https://www.example.com/target-page
+
+  - evaluate: |
+      (async () => {
+        const res = await fetch('/api/target', { credentials: 'include' });
+        const d = await res.json();
+        return (d.data?.items || []).map(item => ({
+          title: item.title,
+          value: item.value,
+        }));
+      })()
+
+  - map:
+      rank: ${{ index + 1 }}
+      title: ${{ item.title }}
+      value: ${{ item.value }}
+
+  - limit: ${{ args.limit }}
+
+columns: [rank, title, value]
+```
+
+### TS — Intercept（抓包模式）
+
+```typescript
+// src/clis/<site>/<name>.ts
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'mysite',
+  name: 'mycommand',
+  description: '一句话描述',
+  domain: 'www.example.com',
+  strategy: Strategy.INTERCEPT,
+  browser: true,
+  args: [
+    { name: 'limit', type: 'int', default: 20 },
+  ],
+  columns: ['rank', 'title', 'value'],
+  func: async (page, kwargs) => {
+    // 1. 导航
+    await page.goto('https://www.example.com/target-page');
+    await page.wait(3);
+
+    // 2. 注入拦截器（URL 子串匹配）
+    await page.installInterceptor('target-api-keyword');
+
+    // 3. 触发 API（滚动/点击）
+    await page.autoScroll({ times: 2, delayMs: 2000 });
+
+    // 4. 读取拦截的响应
+    const requests = await page.getInterceptedRequests();
+    if (!requests?.length) return [];
+
+    let results: any[] = [];
+    for (const req of requests) {
+      const items = req.data?.data?.items || [];
+      results.push(...items);
+    }
+
+    return results.slice(0, kwargs.limit).map((item, i) => ({
+      rank: i + 1,
+      title: item.title || '',
+      value: item.value || '',
+    }));
+  },
+});
+```
+
+### TS — Header（如 Twitter GraphQL）
+
+```typescript
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'twitter',
+  name: 'mycommand',
+  description: '一句话描述',
+  domain: 'x.com',
+  strategy: Strategy.HEADER,
+  browser: true,
+  args: [
+    { name: 'limit', type: 'int', default: 20 },
+  ],
+  columns: ['rank', 'name', 'value'],
+  func: async (page, kwargs) => {
+    await page.goto('https://x.com');
+    const data = await page.evaluate(`(async () => {
+      const ct0 = document.cookie.match(/ct0=([^;]+)/)?.[1];
+      if (!ct0) return { error: 'Not logged in' };
+      const bearer = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D...';
+      const res = await fetch('/i/api/graphql/QUERY_ID/Endpoint', {
+        headers: {
+          'Authorization': 'Bearer ' + decodeURIComponent(bearer),
+          'X-Csrf-Token': ct0,
+          'X-Twitter-Auth-Type': 'OAuth2Session',
+        },
+        credentials: 'include',
+      });
+      return res.json();
+    })()`);
+    // 解析 data...
+    return [];
+  },
+});
+```
+
+---
+
+## 测试（必做）
+
+```bash
+npm run build                              # 语法检查
+opencli list | grep mysite                 # 确认注册
+opencli mysite mycommand --limit 3 -v      # 实际运行
+```
+
+---
+
+## 就这样，没了
+
+写完文件 → build → run → 提交。有问题再看 [CLI-EXPLORER.md](./CLI-EXPLORER.md)。

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,28 @@ 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:
+
+> **Quick mode**: To generate a single command for a specific page URL, see [CLI-ONESHOT.md](./CLI-ONESHOT.md) — just a URL + one-line goal, 4 steps done.
+
+> **Full mode**: Before writing any adapter code, read [CLI-EXPLORER.md](./CLI-EXPLORER.md). It contains the complete browser exploration workflow, the 5-tier authentication strategy decision tree, and debugging guide.
 
 ```bash
 # 1. Deep Explore — discover APIs, infer capabilities, detect framework
@@ -126,30 +177,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)