@jackwener/opencli 0.4.2 → 0.4.4

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 配置文件 AND 环境变量中。**
+
+首先，配置你的 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,28 @@ 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，请遵守以下工作流。
+
+> **快速模式**：只想为某个页面快速生成一个命令？看 [CLI-ONESHOT.md](./CLI-ONESHOT.md) — 给一个 URL + 一句话描述，4 步搞定。
+
+> **完整模式**：在编写任何新代码前，先阅读 [CLI-EXPLORER.md](./CLI-EXPLORER.md)。它包含完整的适配器探索开发指南、API 探测流程、5级认证策略以及常见陷阱。
 
 ```bash
 # 1. Deep Explore — 网络拦截 → 响应分析 → 能力推理 → 框架检测
@@ -127,28 +177,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)

package/SKILL.md

@@ -10,6 +10,11 @@ tags: [cli, browser, web, mcp, playwright, bilibili, zhihu, twitter, github, v2e
 
 > Make any website your CLI. Reuse Chrome login, zero risk, AI-powered discovery.
 
+> [!CAUTION]
+> **AI Agent 必读：创建或修改任何适配器之前，你必须先阅读 [CLI-EXPLORER.md](./CLI-EXPLORER.md)！**
+> 该文档包含完整的 API 发现工作流（必须使用 Playwright MCP Bridge 浏览器探索）、5 级认证策略决策树、平台 SDK 速查表、`tap` 步骤调试流程、分页 API 模板、级联请求模式、以及常见陷阱。
+> **本文件（SKILL.md）仅提供命令参考和简化模板，不足以正确开发适配器。**
+
 ## Install & Run
 
 ```bash
@@ -29,8 +34,8 @@ npm update -g @jackwener/opencli
 
 Browser commands require:
 1. Chrome browser running **(logged into target sites)**
-2. [Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm) extension
-3. Configure `PLAYWRIGHT_MCP_EXTENSION_TOKEN` (from extension settings) in your MCP config
+2. [Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm) extension (default connection mode)
+3. **Alternative**: Chrome 144+ CDP auto-discovery — set `OPENCLI_USE_CDP=1` (no extension needed)
 
 > **Note**: You must be logged into the target website in Chrome before running commands. Tabs opened during command execution are auto-closed afterwards.
 
@@ -129,6 +134,7 @@ opencli ctrip search --query "三亚"      # 搜索目的地
 ```bash
 opencli list                # List all commands
 opencli list --json         # JSON output
+opencli list -f yaml        # YAML output
 opencli validate            # Validate all CLI definitions
 opencli validate bilibili   # Validate specific site
 ```
@@ -157,11 +163,14 @@ opencli verify <site/name> --smoke
 
 ## Output Formats
 
-All commands support `--format` / `-f`:
+All built-in commands support `--format` / `-f` with `table`, `json`, `yaml`, `md`, and `csv`.
+The `list` command supports the same formats and also keeps `--json` as a compatibility alias.
 
 ```bash
+opencli list -f yaml            # YAML command registry
 opencli bilibili hot -f table   # Default: rich table
 opencli bilibili hot -f json    # JSON (pipe to jq, feed to AI agent)
+opencli bilibili hot -f yaml    # YAML (readable structured output)
 opencli bilibili hot -f md      # Markdown
 opencli bilibili hot -f csv     # CSV
 ```
@@ -174,6 +183,15 @@ opencli bilibili hot -v         # Show each pipeline step and data flow
 
 ## Creating Adapters
 
+> [!TIP]
+> **快速模式**：如果你只想为一个具体页面生成一个命令，直接看 [CLI-ONESHOT.md](./CLI-ONESHOT.md)。
+> 只需要一个 URL + 一句话描述，4 步搞定。
+
+> [!IMPORTANT]
+> **完整模式 — 在写任何代码之前，先阅读 [CLI-EXPLORER.md](./CLI-EXPLORER.md)。**
+> 它包含：① AI Agent 浏览器探索工作流（必须用 Playwright MCP 抓包验证 API）② 认证策略决策树 ③ 平台 SDK（如 Bilibili 的 `apiGet`/`fetchJson`）④ YAML vs TS 选择指南 ⑤ `tap` 步骤调试方法 ⑥ 级联请求模板 ⑦ 常见陷阱表。
+> **下方仅为简化模板参考，直接使用极易踩坑。**
+
 ### YAML Pipeline (declarative, recommended)
 
 Create `src/clis/<site>/<name>.yaml`:
@@ -321,7 +339,9 @@ ${{ index + 1 }}
 | `OPENCLI_BROWSER_CONNECT_TIMEOUT` | 30 | Browser connection timeout (sec) |
 | `OPENCLI_BROWSER_COMMAND_TIMEOUT` | 45 | Command execution timeout (sec) |
 | `OPENCLI_BROWSER_EXPLORE_TIMEOUT` | 120 | Explore timeout (sec) |
-| `OPENCLI_EXTENSION_LOCK_TIMEOUT` | 120 | Extension lock timeout (sec) |
+| `OPENCLI_CDP_ENDPOINT` | — | Manual CDP WebSocket endpoint (overrides auto-discovery) |
+| `OPENCLI_USE_CDP` | — | Set to `1` to use Chrome 144+ CDP auto-discovery instead of extension |
+| `OPENCLI_FORCE_EXTENSION` | — | Set to `1` to skip CDP and force extension mode |
 | `PLAYWRIGHT_MCP_EXTENSION_TOKEN` | — | Auto-approve extension connection |
 
 ## Troubleshooting
@@ -329,7 +349,6 @@ ${{ index + 1 }}
 | Issue | Solution |
 |-------|----------|
 | `npx not found` | Install Node.js: `brew install node` |
-| `Timed out connecting to browser` | 1) Chrome must be open 2) Install MCP Bridge extension 3) Click to approve |
-| `Extension lock timed out` | Another opencli command is running; browser commands run serially |
+| `Timed out connecting to browser` | 1) Chrome must be open 2) Enable remote debugging at `chrome://inspect#remote-debugging` or install MCP Bridge extension |
 | `Target page context` error | Add `navigate:` step before `evaluate:` in YAML |
 | Empty table data | Check if evaluate returns JSON string (MCP parsing) or data path is wrong |

package/dist/browser.d.ts

@@ -1,15 +1,33 @@
 /**
- * Browser interaction via Playwright MCP Bridge extension.
- * Connects to an existing Chrome browser through the extension's stdio JSON-RPC.
+ * Browser interaction via Chrome DevTools Protocol.
+ * Connects to an existing Chrome browser through CDP auto-discovery or extension bridge.
  */
+export declare function discoverChromeEndpoint(): Promise<string | null>;
+type ConnectFailureKind = 'missing-token' | 'extension-timeout' | 'extension-not-installed' | 'cdp-timeout' | 'mcp-init' | 'process-exit' | 'unknown';
+type PlaywrightMCPState = 'idle' | 'connecting' | 'connected' | 'closing' | 'closed';
+type ConnectFailureInput = {
+    kind: ConnectFailureKind;
+    mode: 'extension' | 'cdp';
+    timeout: number;
+    hasExtensionToken: boolean;
+    tokenFingerprint?: string | null;
+    stderr?: string;
+    exitCode?: number | null;
+    rawMessage?: string;
+};
+export declare function getTokenFingerprint(token: string | undefined): string | null;
+export declare function formatBrowserConnectError(input: ConnectFailureInput): Error;
+declare function createJsonRpcRequest(method: string, params?: Record<string, any>): {
+    id: number;
+    message: string;
+};
 import type { IPage } from './types.js';
 /**
  * Page abstraction wrapping JSON-RPC calls to Playwright MCP.
  */
 export declare class Page implements IPage {
-    private _send;
-    private _recv;
-    constructor(_send: (msg: string) => void, _recv: () => Promise<any>);
+    private _request;
+    constructor(_request: (method: string, params?: Record<string, any>) => Promise<any>);
     call(method: string, params?: Record<string, any>): Promise<any>;
     goto(url: string): Promise<void>;
     evaluate(js: string): Promise<any>;
@@ -46,16 +64,41 @@ export declare class Page implements IPage {
  * Playwright MCP process manager.
  */
 export declare class PlaywrightMCP {
+    private static _activeInsts;
+    private static _cleanupRegistered;
+    private static _registerGlobalCleanup;
     private _proc;
     private _buffer;
-    private _waiters;
-    private _lockAcquired;
-    private _initialTabCount;
+    private _pending;
+    private _initialTabIdentities;
+    private _closingPromise;
+    private _state;
     private _page;
+    get state(): PlaywrightMCPState;
+    private _sendRequest;
+    private _rejectPendingRequests;
+    private _resetAfterFailedConnect;
     connect(opts?: {
         timeout?: number;
+        forceExtension?: boolean;
     }): Promise<Page>;
     close(): Promise<void>;
-    private _acquireLock;
-    private _releaseLock;
 }
+declare function extractTabEntries(raw: any): Array<{
+    index: number;
+    identity: string;
+}>;
+declare function diffTabIndexes(initialIdentities: string[], currentTabs: Array<{
+    index: number;
+    identity: string;
+}>): number[];
+declare function appendLimited(current: string, chunk: string, limit: number): string;
+declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T>;
+export declare const __test__: {
+    createJsonRpcRequest: typeof createJsonRpcRequest;
+    extractTabEntries: typeof extractTabEntries;
+    diffTabIndexes: typeof diffTabIndexes;
+    appendLimited: typeof appendLimited;
+    withTimeout: typeof withTimeout;
+};
+export {};