@jackwener/opencli 0.9.5 → 0.9.8

package/CONTRIBUTING.md

@@ -0,0 +1,167 @@
+# Contributing to OpenCLI
+
+Thanks for your interest in contributing to OpenCLI.
+
+## Quick Start
+
+```bash
+# 1. Fork & clone
+git clone git@github.com:<your-username>/opencli.git
+cd opencli
+
+# 2. Install dependencies
+npm install
+
+# 3. Build
+npm run build
+
+# 4. Run a few checks
+npx tsc --noEmit
+npx vitest run src/
+
+# 5. Link globally (optional, for testing `opencli` command)
+npm link
+```
+
+## Adding a New Site Adapter
+
+This is the most common type of contribution. Start with YAML when possible, and use TypeScript only when you need browser-side logic or multi-step flows.
+
+### YAML Adapter (Recommended for data-fetching commands)
+
+Create a file like `src/clis/<site>/<command>.yaml`:
+
+```yaml
+site: mysite
+name: trending
+description: Trending posts on MySite
+domain: www.mysite.com
+strategy: public      # public | cookie | header
+browser: false        # true if browser session is needed
+
+args:
+  limit:
+    type: int
+    default: 20
+    description: Number of items
+
+pipeline:
+  - fetch:
+      url: https://api.mysite.com/trending
+
+  - map:
+      rank: ${{ index + 1 }}
+      title: ${{ item.title }}
+      score: ${{ item.score }}
+      url: ${{ item.url }}
+
+  - limit: ${{ args.limit }}
+
+columns: [rank, title, score, url]
+```
+
+See [`hackernews/top.yaml`](src/clis/hackernews/top.yaml) for a real example.
+
+### TypeScript Adapter (For complex browser interactions)
+
+Create a file like `src/clis/<site>/<command>.ts`:
+
+```typescript
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'mysite',
+  name: 'search',
+  description: 'Search MySite',
+  domain: 'www.mysite.com',
+  strategy: Strategy.COOKIE,
+  args: [
+    { name: 'query', required: true, help: 'Search query' },
+    { name: 'limit', type: 'int', default: 10, help: 'Max results' },
+  ],
+  columns: ['title', 'url', 'date'],
+
+  func: async (page, kwargs) => {
+    const { query, limit = 10 } = kwargs;
+    await page.goto('https://www.mysite.com');
+
+    const data = await page.evaluate(`
+      (async () => {
+        const res = await fetch('/api/search?q=${encodeURIComponent(query)}', {
+          credentials: 'include'
+        });
+        return (await res.json()).results;
+      })()
+    `);
+
+    return data.slice(0, Number(limit)).map((item: any) => ({
+      title: item.title,
+      url: item.url,
+      date: item.created_at,
+    }));
+  },
+});
+```
+
+Use `opencli explore <url>` to discover APIs and see [CLI-EXPLORER.md](./CLI-EXPLORER.md) if you need the full adapter workflow.
+
+### Validate Your Adapter
+
+```bash
+# Validate YAML syntax and schema
+opencli validate
+
+# Test your command
+opencli <site> <command> --limit 3 -f json
+
+# Verbose mode for debugging
+opencli <site> <command> -v
+```
+
+## Testing
+
+See [TESTING.md](./TESTING.md) for the full guide and exact test locations.
+
+```bash
+npx vitest run src/           # Unit tests
+npx vitest run tests/e2e/     # E2E tests
+npx vitest run                # All tests
+```
+
+## Code Style
+
+- **TypeScript strict mode** — avoid `any` where possible.
+- **ES Modules** — use `.js` extensions in imports (TypeScript output).
+- **Naming**: `kebab-case` for files, `camelCase` for variables/functions, `PascalCase` for types/classes.
+- **No default exports** — use named exports.
+
+## Commit Convention
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat(twitter): add thread command
+fix(browser): handle CDP timeout gracefully
+docs: update CONTRIBUTING.md
+test(reddit): add e2e test for save command
+chore: bump vitest to v4
+```
+
+Common scopes: site name (`twitter`, `reddit`) or module name (`browser`, `pipeline`, `engine`).
+
+## Submitting a Pull Request
+
+1. Create a feature branch: `git checkout -b feat/mysite-trending`
+2. Make your changes and add tests when relevant
+3. Run the checks that apply:
+   ```bash
+   npx tsc --noEmit           # Type check
+   npx vitest run src/        # Unit tests
+   opencli validate           # YAML validation (if applicable)
+   ```
+4. Commit using conventional commit format
+5. Push and open a PR
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [Apache-2.0 License](./LICENSE).

package/README.md

@@ -1,7 +1,7 @@
 # OpenCLI
 
 > **Make any website or Electron App your CLI.**  
-> Zero risk · Reuse Chrome login · AI-powered discovery · 80+ commands · 19 sites
+> Zero risk · Reuse Chrome login · AI-powered discovery · Browser + Desktop automation
 
 [中文文档](./README.zh-CN.md)
 
@@ -22,6 +22,7 @@ Turn ANY Electron application into a CLI tool! Recombine, script, and extend app
 - [Prerequisites](#prerequisites)
 - [Quick Start](#quick-start)
 - [Built-in Commands](#built-in-commands)
+- [Download Support](#download-support)
 - [Output Formats](#output-formats)
 - [For AI Agents (Developer Guide)](#for-ai-agents-developer-guide)
 - [Remote Chrome (Server/Headless)](#remote-chrome-serverheadless)
@@ -43,7 +44,7 @@ Turn ANY Electron application into a CLI tool! Recombine, script, and extend app
 
 ## Prerequisites
 
-- **Node.js**: >= 18.0.0
+- **Node.js**: >= 20.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.
@@ -143,34 +144,99 @@ npm install -g @jackwener/opencli@latest
 
 ## Built-in Commands
 
-**26 sites · 119 commands** — run `opencli list` for the live registry.
-
-| Site | Commands | Count | Mode |
-|------|----------|:-----:|------|
-| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` `thread` `following` `followers` `notifications` `post` `reply` `delete` `like` `article` `follow` `unfollow` `bookmark` `unbookmark` | 18 | 🔐 Browser |
-| **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `read` `user` `user-posts` `user-comments` `upvote` `save` `comment` `subscribe` `saved` `upvoted` | 15 | 🔐 Browser |
-| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `subtitle` `dynamic` `ranking` `following` `user-videos` | 11 | 🔐 Browser |
-| **cursor** | `status` `send` `read` `new` `dump` `composer` `model` `extract-code` | 8 | 🖥️ Desktop |
-| **codex** | `status` `send` `read` `new` `extract-diff` `model` | 6 | 🖥️ Desktop |
-| **v2ex** | `hot` `latest` `topic` `daily` `me` `notifications` | 6 | 🌐 / 🔐 |
-| **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 6 | 🔐 Browser |
-| **antigravity** | `status` `send` `read` `new` `evaluate` | 5 | 🖥️ Desktop |
-| **xiaohongshu** | `search` `notifications` `feed` `me` `user` | 5 | 🔐 Browser |
-| **chatgpt** | `status` `new` `send` `read` | 4 | 🖥️ Desktop |
-| **xiaoyuzhou** | `podcast` `podcast-episodes` `episode` | 3 | 🌐 Public |
-| **youtube** | `search` `video` `transcript` | 3 | 🔐 Browser |
-| **zhihu** | `hot` `search` `question` | 3 | 🔐 Browser |
-| **boss** | `search` `detail` | 2 | 🔐 Browser |
-| **coupang** | `search` `add-to-cart` | 2 | 🔐 Browser |
-| **bbc** | `news` | 1 | 🌐 Public |
-| **ctrip** | `search` | 1 | 🔐 Browser |
-| **github** | `search` | 1 | 🌐 Public |
-| **hackernews** | `top` | 1 | 🌐 Public |
-| **linkedin** | `search` | 1 | 🔐 Browser |
-| **reuters** | `search` | 1 | 🔐 Browser |
-| **smzdm** | `search` | 1 | 🔐 Browser |
-| **weibo** | `hot` | 1 | 🔐 Browser |
-| **yahoo-finance** | `quote` | 1 | 🔐 Browser |
+Run `opencli list` for the live registry.
+
+| Site | Commands | Mode |
+|------|----------|------|
+| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` `thread` `following` `followers` `notifications` `post` `reply` `delete` `like` `article` `follow` `unfollow` `bookmark` `unbookmark` `download` | 🔐 Browser |
+| **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `read` `user` `user-posts` `user-comments` `upvote` `save` `comment` `subscribe` `saved` `upvoted` | 🔐 Browser |
+| **cursor** | `status` `send` `read` `new` `dump` `composer` `model` `extract-code` `ask` `screenshot` `history` `export` | 🖥️ Desktop |
+| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `subtitle` `dynamic` `ranking` `following` `user-videos` `download` | 🔐 Browser |
+| **codex** | `status` `send` `read` `new` `extract-diff` `model` `ask` `screenshot` `history` `export` | 🖥️ Desktop |
+| **chatwise** | `status` `new` `send` `read` `ask` `model` `history` `export` `screenshot` | 🖥️ Desktop |
+| **notion** | `status` `search` `read` `new` `write` `sidebar` `favorites` `export` | 🖥️ Desktop |
+| **discord-app** | `status` `send` `read` `channels` `servers` `search` `members` | 🖥️ Desktop |
+| **v2ex** | `hot` `latest` `topic` `daily` `me` `notifications` | 🌐 / 🔐 |
+| **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 🔐 Browser |
+| **antigravity** | `status` `send` `read` `new` `evaluate` | 🖥️ Desktop |
+| **chatgpt** | `status` `new` `send` `read` `ask` | 🖥️ Desktop |
+| **xiaohongshu** | `search` `notifications` `feed` `me` `user` `download` | 🔐 Browser |
+| **xiaoyuzhou** | `podcast` `podcast-episodes` `episode` | 🌐 Public |
+| **zhihu** | `hot` `search` `question` `download` | 🔐 Browser |
+| **youtube** | `search` `video` `transcript` | 🔐 Browser |
+| **boss** | `search` `detail` | 🔐 Browser |
+| **coupang** | `search` `add-to-cart` | 🔐 Browser |
+| **bbc** | `news` | 🌐 Public |
+| **ctrip** | `search` | 🔐 Browser |
+| **github** | `search` | 🌐 Public |
+| **hackernews** | `top` | 🌐 Public |
+| **linkedin** | `search` | 🔐 Browser |
+| **reuters** | `search` | 🔐 Browser |
+| **smzdm** | `search` | 🔐 Browser |
+| **weibo** | `hot` | 🔐 Browser |
+| **yahoo-finance** | `quote` | 🔐 Browser |
+
+## Download Support
+
+OpenCLI supports downloading images, videos, and articles from supported platforms.
+
+### Supported Platforms
+
+| Platform | Content Types | Notes |
+|----------|---------------|-------|
+| **xiaohongshu** | Images, Videos | Downloads all media from a note |
+| **bilibili** | Videos | Requires `yt-dlp` installed |
+| **twitter** | Images, Videos | Downloads from user media tab or single tweet |
+| **zhihu** | Articles (Markdown) | Exports articles with optional image download |
+
+### Prerequisites
+
+For video downloads from streaming platforms, you need to install `yt-dlp`:
+
+```bash
+# Install yt-dlp
+pip install yt-dlp
+# or
+brew install yt-dlp
+```
+
+### Usage Examples
+
+```bash
+# Download images/videos from Xiaohongshu note
+opencli xiaohongshu download --note-id abc123 --output ./xhs
+
+# Download Bilibili video (requires yt-dlp)
+opencli bilibili download --bvid BV1xxx --output ./bilibili
+opencli bilibili download --bvid BV1xxx --quality 1080p  # Specify quality
+
+# Download Twitter media from user
+opencli twitter download --username elonmusk --limit 20 --output ./twitter
+
+# Download single tweet media
+opencli twitter download --tweet-url "https://x.com/user/status/123" --output ./twitter
+
+# Export Zhihu article to Markdown
+opencli zhihu download --url "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
+
+# Export with local images
+opencli zhihu download --url "https://zhuanlan.zhihu.com/p/xxx" --download-images
+```
+
+### Pipeline Step (for YAML adapters)
+
+The `download` step can be used in YAML pipelines:
+
+```yaml
+pipeline:
+  - fetch: https://api.example.com/media
+  - download:
+      url: ${{ item.imageUrl }}
+      dir: ./downloads
+      filename: ${{ item.title | sanitize }}.jpg
+      concurrency: 5
+      skip_existing: true
+```
 
 ## Output Formats
 
@@ -215,7 +281,7 @@ Explore outputs to `.opencli/explore/<site>/` (manifest.json, endpoints.json, ca
 
 See **[TESTING.md](./TESTING.md)** for the full testing guide, including:
 
-- Current test coverage (unit + E2E tests across 19 sites)
+- Current test coverage (unit + E2E tests across browser and desktop adapters)
 - How to run tests locally
 - How to add tests when creating new adapters
 - CI/CD pipeline with sharding
@@ -237,7 +303,7 @@ npx vitest run tests/e2e/                    # E2E tests
 - **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.
+  - Make sure you are using Node.js >= 20. Some dependencies require modern Node APIs.
 - **Token issues**
   - Run `opencli doctor` to diagnose token configuration across all tools.
 

package/README.zh-CN.md

@@ -1,7 +1,7 @@
 # OpenCLI
 
 > **把任何网站或 Electron 应用变成你的命令行工具。**  
-> 零风控 · 复用 Chrome 登录 · AI 自动发现接口 · 80+ 命令 · 19 站点
+> 零风控 · 复用 Chrome 登录 · AI 自动发现接口 · 浏览器与桌面端自动化
 
 [English](./README.md)
 
@@ -9,7 +9,7 @@
 [![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 将任何网站或 Electron 应用（如 Antigravity）变成命令行工具 — B站、知乎、小红书、Twitter/X、Reddit、YouTube 等 [19 个站点](#内置命令) — 复用浏览器登录态，AI 驱动探索。
+OpenCLI 将任何网站或 Electron 应用（如 Antigravity）变成命令行工具 — B站、知乎、小红书、Twitter/X、Reddit、YouTube 等[多种站点与应用](#内置命令) — 复用浏览器登录态，AI 驱动探索。
 
 🔥 **opencli 支持 CLI 化所有 electron 应用！最强大更新来袭！** 🔥
 CLI all electron！现在支持把所有 electron 应用 CLI 化，从而组合出各种神奇的能力。
@@ -24,6 +24,7 @@ CLI all electron！现在支持把所有 electron 应用 CLI 化，从而组合
 - [前置要求](#前置要求)
 - [快速开始](#快速开始)
 - [内置命令](#内置命令)
+- [下载支持](#下载支持)
 - [输出格式](#输出格式)
 - [致 AI Agent（开发者指南）](#致-ai-agent开发者指南)
 - [远程 Chrome（服务器/无头环境）](#远程-chrome服务器无头环境)
@@ -36,7 +37,7 @@ CLI all electron！现在支持把所有 electron 应用 CLI 化，从而组合
 ## 亮点
 
 - **CLI All Electron** — 支持把所有 electron 应用（如 Antigravity Ultra）CLI 化，让 AI 控制自己！
-- **多站点覆盖** — B站、知乎、小红书、Twitter、Reddit 等 19 个站点，80+ 命令
+- **多站点覆盖** — 覆盖 B站、知乎、小红书、Twitter、Reddit，以及多种桌面应用
 - **零风控** — 复用 Chrome 登录态，无需存储任何凭证
 - **自修复配置** — `opencli setup` 自动发现 Token；`opencli doctor` 诊断 10+ 工具配置；`--fix` 一键修复
 - **AI 原生** — `explore` 自动发现 API，`synthesize` 生成适配器，`cascade` 探测认证策略
@@ -44,7 +45,7 @@ CLI all electron！现在支持把所有 electron 应用 CLI 化，从而组合
 
 ## 前置要求
 
-- **Node.js**: >= 18.0.0
+- **Node.js**: >= 20.0.0
 - **Chrome** 浏览器正在运行，且**已登录目标网站**（如 bilibili.com、zhihu.com、xiaohongshu.com）
 
 > **⚠️ 重要**：大多数命令复用你的 Chrome 登录状态。运行命令前，你必须已在 Chrome 中打开目标网站并完成登录。如果获取到空数据或报错，请先检查你的浏览器登录状态。
@@ -144,34 +145,99 @@ npm install -g @jackwener/opencli@latest
 
 ## 内置命令
 
-**26 个站点 · 119 命令** — 运行 `opencli list` 查看完整注册表。
-
-| 站点 | 命令 | 数量 | 模式 |
-|------|------|:----:|------|
-| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` `thread` `following` `followers` `notifications` `post` `reply` `delete` `like` `article` `follow` `unfollow` `bookmark` `unbookmark` | 18 | 🔐 浏览器 |
-| **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `read` `user` `user-posts` `user-comments` `upvote` `save` `comment` `subscribe` `saved` `upvoted` | 15 | 🔐 浏览器 |
-| **antigravity** | `status` `send` `read` `new` `evaluate` | 5 | 🖥️ 桌面端 |
-| **chatgpt** | `status` `new` `send` `read` | 4 | 🖥️ 桌面端 |
-| **codex** | `status` `send` `read` `new` `extract-diff` `model` | 6 | 🖥️ 桌面端 |
-| **cursor** | `status` `send` `read` `new` `dump` `composer` `model` `extract-code` | 8 | 🖥️ 桌面端 |
-| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `subtitle` `dynamic` `ranking` `following` `user-videos` | 11 | 🔐 浏览器 |
-| **v2ex** | `hot` `latest` `topic` `daily` `me` `notifications` | 6 | 🌐 / 🔐 |
-| **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 6 | 🔐 浏览器 |
-| **xiaohongshu** | `search` `notifications` `feed` `me` `user` | 5 | 🔐 浏览器 |
-| **xiaoyuzhou** | `podcast` `podcast-episodes` `episode` | 3 | 🌐 公开 |
-| **youtube** | `search` `video` `transcript` | 3 | 🔐 浏览器 |
-| **zhihu** | `hot` `search` `question` | 3 | 🔐 浏览器 |
-| **boss** | `search` `detail` | 2 | 🔐 浏览器 |
-| **coupang** | `search` `add-to-cart` | 2 | 🔐 浏览器 |
-| **bbc** | `news` | 1 | 🌐 公共 API |
-| **ctrip** | `search` | 1 | 🔐 浏览器 |
-| **github** | `search` | 1 | 🌐 公共 API |
-| **hackernews** | `top` | 1 | 🌐 公共 API |
-| **linkedin** | `search` | 1 | 🔐 浏览器 |
-| **reuters** | `search` | 1 | 🔐 浏览器 |
-| **smzdm** | `search` | 1 | 🔐 浏览器 |
-| **weibo** | `hot` | 1 | 🔐 浏览器 |
-| **yahoo-finance** | `quote` | 1 | 🔐 浏览器 |
+运行 `opencli list` 查看完整注册表。
+
+| 站点 | 命令 | 模式 |
+|------|------|------|
+| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` `thread` `following` `followers` `notifications` `post` `reply` `delete` `like` `article` `follow` `unfollow` `bookmark` `unbookmark` `download` | 🔐 浏览器 |
+| **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `read` `user` `user-posts` `user-comments` `upvote` `save` `comment` `subscribe` `saved` `upvoted` | 🔐 浏览器 |
+| **cursor** | `status` `send` `read` `new` `dump` `composer` `model` `extract-code` `ask` `screenshot` `history` `export` | 🖥️ 桌面端 |
+| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `subtitle` `dynamic` `ranking` `following` `user-videos` `download` | 🔐 浏览器 |
+| **codex** | `status` `send` `read` `new` `extract-diff` `model` `ask` `screenshot` `history` `export` | 🖥️ 桌面端 |
+| **chatwise** | `status` `new` `send` `read` `ask` `model` `history` `export` `screenshot` | 🖥️ 桌面端 |
+| **notion** | `status` `search` `read` `new` `write` `sidebar` `favorites` `export` | 🖥️ 桌面端 |
+| **discord-app** | `status` `send` `read` `channels` `servers` `search` `members` | 🖥️ 桌面端 |
+| **v2ex** | `hot` `latest` `topic` `daily` `me` `notifications` | 🌐 / 🔐 |
+| **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 🔐 浏览器 |
+| **antigravity** | `status` `send` `read` `new` `evaluate` | 🖥️ 桌面端 |
+| **chatgpt** | `status` `new` `send` `read` `ask` | 🖥️ 桌面端 |
+| **xiaohongshu** | `search` `notifications` `feed` `me` `user` `download` | 🔐 浏览器 |
+| **xiaoyuzhou** | `podcast` `podcast-episodes` `episode` | 🌐 公开 |
+| **zhihu** | `hot` `search` `question` `download` | 🔐 浏览器 |
+| **youtube** | `search` `video` `transcript` | 🔐 浏览器 |
+| **boss** | `search` `detail` | 🔐 浏览器 |
+| **coupang** | `search` `add-to-cart` | 🔐 浏览器 |
+| **bbc** | `news` | 🌐 公共 API |
+| **ctrip** | `search` | 🔐 浏览器 |
+| **github** | `search` | 🌐 公共 API |
+| **hackernews** | `top` | 🌐 公共 API |
+| **linkedin** | `search` | 🔐 浏览器 |
+| **reuters** | `search` | 🔐 浏览器 |
+| **smzdm** | `search` | 🔐 浏览器 |
+| **weibo** | `hot` | 🔐 浏览器 |
+| **yahoo-finance** | `quote` | 🔐 浏览器 |
+
+## 下载支持
+
+OpenCLI 支持从各平台下载图片、视频和文章。
+
+### 支持的平台
+
+| 平台 | 内容类型 | 说明 |
+|------|----------|------|
+| **小红书** | 图片、视频 | 下载笔记中的所有媒体文件 |
+| **B站** | 视频 | 需要安装 `yt-dlp` |
+| **Twitter/X** | 图片、视频 | 从用户媒体页或单条推文下载 |
+| **知乎** | 文章（Markdown） | 导出文章，可选下载图片到本地 |
+
+### 前置依赖
+
+下载流媒体平台的视频需要安装 `yt-dlp`：
+
+```bash
+# 安装 yt-dlp
+pip install yt-dlp
+# 或者
+brew install yt-dlp
+```
+
+### 使用示例
+
+```bash
+# 下载小红书笔记中的图片/视频
+opencli xiaohongshu download --note-id abc123 --output ./xhs
+
+# 下载B站视频（需要 yt-dlp）
+opencli bilibili download --bvid BV1xxx --output ./bilibili
+opencli bilibili download --bvid BV1xxx --quality 1080p  # 指定画质
+
+# 下载 Twitter 用户的媒体
+opencli twitter download --username elonmusk --limit 20 --output ./twitter
+
+# 下载单条推文的媒体
+opencli twitter download --tweet-url "https://x.com/user/status/123" --output ./twitter
+
+# 导出知乎文章为 Markdown
+opencli zhihu download --url "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
+
+# 导出文章并下载图片到本地
+opencli zhihu download --url "https://zhuanlan.zhihu.com/p/xxx" --download-images
+```
+
+### Pipeline Step（用于 YAML 适配器）
+
+`download` step 可以在 YAML 管线中使用：
+
+```yaml
+pipeline:
+  - fetch: https://api.example.com/media
+  - download:
+      url: ${{ item.imageUrl }}
+      dir: ./downloads
+      filename: ${{ item.title | sanitize }}.jpg
+      concurrency: 5
+      skip_existing: true
+```
 
 ## 输出格式
 
@@ -220,7 +286,7 @@ opencli cascade https://api.example.com/data
 - **返回空数据，或者报错 "Unauthorized"**
   - Chrome 里的登录态可能已经过期（甚至被要求过滑动验证码）。请打开当前 Chrome 页面，在新标签页重新手工登录或刷新该页面。
 - **Node API 错误 (如 parseArgs, fs 等)**
-  - 确保 Node.js 版本 `>= 18`。旧版不支持我们使用的现代核心库 API。
+  - 确保 Node.js 版本 `>= 20`。旧版不支持我们使用的现代核心库 API。
 - **Token 问题**
   - 运行 `opencli doctor` 诊断所有工具的 Token 配置状态。
   - 使用 `opencli doctor --live` 测试浏览器连通性。

package/dist/browser/discover.js

@@ -9,6 +9,18 @@ import * as path from 'node:path';
 let _cachedMcpServerPath;
 let _existsSync = fs.existsSync;
 let _execSync = execSync;
+function isSupportedMcpEntrypoint(candidate) {
+    const normalized = candidate.replace(/\\/g, '/').toLowerCase();
+    return normalized.endsWith('/@playwright/mcp/cli.js') ||
+        normalized.endsWith('/mcp-server-playwright') ||
+        normalized.endsWith('/mcp-server-playwright.js');
+}
+function resolveSupportedMcpPath(candidate) {
+    const trimmed = candidate?.trim();
+    if (!trimmed || !_existsSync(trimmed))
+        return null;
+    return isSupportedMcpEntrypoint(trimmed) ? trimmed : null;
+}
 export function resetMcpServerPathCache() {
     _cachedMcpServerPath = undefined;
 }
@@ -67,8 +79,9 @@ export function findMcpServerPath() {
     // Try npx resolution (legacy package name)
     try {
         const result = _execSync('npx -y --package=@playwright/mcp which mcp-server-playwright 2>/dev/null', { encoding: 'utf-8', timeout: 10000 }).trim();
-        if (result && _existsSync(result)) {
-            _cachedMcpServerPath = result;
+        const resolved = resolveSupportedMcpPath(result);
+        if (resolved) {
+            _cachedMcpServerPath = resolved;
             return _cachedMcpServerPath;
         }
     }
@@ -76,8 +89,9 @@ export function findMcpServerPath() {
     // Try which
     try {
         const result = _execSync('which mcp-server-playwright 2>/dev/null', { encoding: 'utf-8', timeout: 5000 }).trim();
-        if (result && _existsSync(result)) {
-            _cachedMcpServerPath = result;
+        const resolved = resolveSupportedMcpPath(result);
+        if (resolved) {
+            _cachedMcpServerPath = resolved;
             return _cachedMcpServerPath;
         }
     }
@@ -87,9 +101,10 @@ export function findMcpServerPath() {
         if (!_existsSync(base))
             continue;
         try {
-            const found = _execSync(`find "${base}" -name "cli.js" -path "*playwright*mcp*" 2>/dev/null | head -1`, { encoding: 'utf-8', timeout: 5000 }).trim();
-            if (found) {
-                _cachedMcpServerPath = found;
+            const found = _execSync(`find "${base}" -type f -path "*/@playwright/mcp/cli.js" 2>/dev/null | head -1`, { encoding: 'utf-8', timeout: 5000 }).trim();
+            const resolved = resolveSupportedMcpPath(found);
+            if (resolved) {
+                _cachedMcpServerPath = resolved;
                 return _cachedMcpServerPath;
             }
         }

package/dist/browser.test.js

@@ -1,4 +1,6 @@
 import { afterEach, describe, it, expect, vi } from 'vitest';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import { PlaywrightMCP, __test__ } from './browser/index.js';
 afterEach(() => {
     __test__.resetMcpServerPathCache();
@@ -228,6 +230,27 @@ describe('browser helpers', () => {
             });
         }
     });
+    it('ignores non-server playwright cli paths discovered from fallback scans', () => {
+        const wrongCli = '/root/.npm/_npx/e41f203b7505f1fb/node_modules/playwright/lib/mcp/terminal/cli.js';
+        const npxCacheBase = path.join(os.homedir(), '.npm', '_npx');
+        const existsSync = vi.fn((candidate) => {
+            const value = String(candidate);
+            return value === npxCacheBase || value === wrongCli;
+        });
+        const execSync = vi.fn((command) => {
+            if (String(command).includes('npm root -g'))
+                return '/missing/global/node_modules\n';
+            if (String(command).includes('--package=@playwright/mcp which mcp-server-playwright'))
+                return `${wrongCli}\n`;
+            if (String(command).includes('which mcp-server-playwright'))
+                return '';
+            if (String(command).includes(`find "${npxCacheBase}"`))
+                return `${wrongCli}\n`;
+            throw new Error(`unexpected command: ${String(command)}`);
+        });
+        __test__.setMcpDiscoveryTestHooks({ existsSync, execSync: execSync });
+        expect(__test__.findMcpServerPath()).toBeNull();
+    });
 });
 describe('PlaywrightMCP state', () => {
     it('transitions to closed after close()', async () => {

package/dist/build-manifest.d.ts

@@ -8,4 +8,30 @@
  * Usage: npx tsx src/build-manifest.ts
  * Output: dist/cli-manifest.json
  */
+interface ManifestEntry {
+    site: string;
+    name: string;
+    description: string;
+    domain?: string;
+    strategy: string;
+    browser: boolean;
+    args: Array<{
+        name: string;
+        type?: string;
+        default?: any;
+        required?: boolean;
+        positional?: boolean;
+        help?: string;
+        choices?: string[];
+    }>;
+    columns?: string[];
+    pipeline?: any[];
+    timeout?: number;
+    /** 'yaml' or 'ts' — determines how executeCommand loads the handler */
+    type: 'yaml' | 'ts';
+    /** Relative path from clis/ dir, e.g. 'bilibili/hot.yaml' or 'bilibili/search.js' */
+    modulePath?: string;
+}
+export declare function parseTsArgsBlock(argsBlock: string): ManifestEntry['args'];
+export declare function buildManifest(): ManifestEntry[];
 export {};