fix: remove duplicate and unused imports in chatgpt adapters

Replace raw Error throws with appropriate CliError subclasses:
- chatgpt/status.ts: ConfigError for platform limitation
- chatgpt/ask.ts: ConfigError for platform limitation
- chatgpt/new.ts: ConfigError for platform limitation
- chatgpt/read.ts: ConfigError for platform limitation, CommandExecutionError for read failures

This enables better error handling and user-facing error messages.

.agents/skills/cross-project-adapter-migration/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: cross-project-adapter-migration
+description: "Cross-project CLI command migration workflow for opencli. Use when importing commands from external CLI projects (python/node) like rdt-cli, twitter-cli, etc. Covers: source analysis → gap matrix → batch migration → README/SKILL.md update."
+---
+
+# Cross-Project Adapter Migration
+
+> 从外部 CLI 项目（Python/Node/Go 等）批量迁移命令到 opencli 的标准化流程。
+
+## When to Use
+
+- 用户说"把 xxx-cli 的命令迁移过来"
+- 用户说"看看 xxx 项目有什么可以借鉴的"
+- 用户说"对齐 xxx-cli 的功能"
+- 在为新平台扩展 opencli 时，发现已有第三方 CLI 工具
+
+## Prerequisites
+
+- 熟悉 [CLI-EXPLORER.md](file:///Users/jakevin/code/opencli/CLI-EXPLORER.md)（adapter 开发决策树）
+- 熟悉 [SKILL.md](file:///Users/jakevin/code/opencli/SKILL.md)（命令参考 & 模板）
+
+---
+
+## Phase 1: 源项目分析
+
+### 1.1 克隆 & 理解源项目
+
+```bash
+# 克隆源项目到 /tmp 做分析
+git clone <source_repo_url> /tmp/<source-cli>
+```
+
+分析重点：
+- **命令列表**：找到所有可用命令（查看 CLI 入口文件、help 输出或 README）
+- **认证方式**：Cookie？API Key？OAuth？浏览器自动化？
+- **数据源**：公开 API？GraphQL？页面抓取？
+- **输出字段**：每个命令返回哪些数据字段
+
+### 1.2 生成命令清单
+
+列出源项目所有命令，包括：
+
+| 命令 | 类型 | API/方法 | 输出字段 |
+|------|------|---------|---------|
+| `xxx feed` | Read | `GET /api/feed` | title, author, time |
+| `xxx post` | Write | `POST /api/tweet` | status, id |
+
+---
+
+## Phase 2: 功能对比矩阵
+
+### 2.1 查看 opencli 现有命令
+
+```bash
+ls src/clis/<site>/     # 查看已有适配器
+opencli list | grep <site>  # 确认已注册命令
+```
+
+### 2.2 生成对比矩阵
+
+对每个源项目命令，标注三种状态：
+
+| 功能 | 源项目 | opencli 现有 | 行动 |
+|------|--------|-------------|------|
+| feed | ✅ `xxx feed` | ❌ 无 | ✅ **新增** |
+| search | ✅ `xxx search` | ✅ `search.ts` | ❌ 已有，跳过 |
+| hot | ✅ `xxx hot` | ⚠️ `hot.yaml`（不完整） | ✅ **增强** |
+| like | ✅ `xxx like` | ✅ `like.ts` | ❌ 已有，跳过 |
+
+### 2.3 筛选迁移目标
+
+去掉已有的、低价值的，保留高价值缺失命令，按 Read/Write 分类：
+
+**筛选原则**：
+- ✅ 高使用频率的命令优先
+- ✅ 已有但不完整的命令标记为"增强"
+- ❌ 源项目特有但 opencli 架构不支持的功能（如需要持久化存储的）跳过
+- ❌ 与现有功能完全重复的跳过
+
+---
+
+## Phase 3: 批量实现
+
+> [!IMPORTANT]
+> 实现前必须查阅 [CLI-EXPLORER.md](file:///Users/jakevin/code/opencli/CLI-EXPLORER.md) 确认策略选择。
+
+### 3.1 选择实现方式
+
+基于决策树分类：
+
+| 类别 | 方式 | 适用条件 |
+|------|------|---------|
+| **Read + 简单 API** | YAML pipeline | 纯 fetch/select/map，无复杂 JS |
+| **Read + GraphQL/分页/签名** | TypeScript adapter | 需要 JS 逻辑 |
+| **Write 操作** | TypeScript + `Strategy.UI` | 点击/输入等 DOM 操作 |
+| **Write + API** | TypeScript + `Strategy.COOKIE/HEADER` | 直接 POST API |
+
+### 3.2 实现顺序
+
+**先 Read 后 Write，先 YAML 后 TS**：
+
+1. **Phase A**: YAML Read 适配器（最快，通常每个 10-20 行）
+2. **Phase B**: TS Read 适配器（需要 evaluate/intercept 的）
+3. **Phase C**: TS Write 适配器（需 UI 自动化或 POST API）
+
+### 3.3 实现模板
+
+#### YAML Read 适配器模板（Cookie 策略）
+
+```yaml
+site: <site>
+name: <command>
+description: <描述>
+domain: www.<site>.com
+strategy: cookie
+browser: true
+
+args:
+  limit:
+    type: int
+    default: 20
+
+pipeline:
+  - navigate: https://www.<site>.com
+  - evaluate: |
+      (async () => {
+        const res = await fetch('<api_endpoint>', { credentials: 'include' });
+        const d = await res.json();
+        return (d.data?.items || []).map(item => ({
+          title: item.title,
+          // ... map source fields
+        }));
+      })()
+  - map:
+      rank: ${{ index + 1 }}
+      title: ${{ item.title }}
+  - limit: ${{ args.limit }}
+
+columns: [rank, title]
+```
+
+#### TS Write 适配器模板（UI 策略）
+
+```typescript
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: '<site>',
+  name: '<command>',
+  description: '<描述>',
+  strategy: Strategy.UI,
+  args: [{ name: 'target', required: true, help: '<参数说明>' }],
+  columns: ['status', 'message'],
+  func: async (page, kwargs) => {
+    await page.goto(`https://www.<site>.com/${kwargs.target}`);
+    await page.wait({ text: '<expected_text>', timeout: 10 });
+
+    // 获取 snapshot 找到目标按钮
+    const snapshot = await page.accessibility.snapshot();
+    // 点击按钮 ...
+
+    return [{ status: 'success', message: '<action> completed' }];
+  },
+});
+```
+
+### 3.4 公共模式复用
+
+迁移过程中如果发现多个适配器共享逻辑，考虑提取到 `src/clis/<site>/utils.ts` 工具文件：
+
+```typescript
+// src/clis/<site>/utils.ts
+export async function fetchWithAuth(page, url) { ... }
+export function parseItem(raw) { ... }
+```
+
+---
+
+## Phase 4: 验证 & 发布
+
+### 4.1 构建验证
+
+```bash
+npx tsc --noEmit                    # TypeScript 编译检查
+opencli list | grep <site>          # 确认所有命令已注册
+```
+
+### 4.2 运行验证（关键！）
+
+每个新命令必须实际运行：
+
+```bash
+# Read 命令
+opencli <site> <command> --limit 3 -f json
+opencli <site> <command> --limit 3 -v   # verbose 查看 pipeline
+
+# Write 命令（谨慎！会实际操作）
+opencli <site> <command> <test_target>
+```
+
+### 4.3 更新文档
+
+迁移完成后必须更新以下文件：
+
+1. **README.md** — 在对应平台区域添加新命令示例
+2. **SKILL.md** — 在 Commands Reference 中添加新命令
+
+### 4.4 提交 & 推送
+
+```bash
+git add -A
+git commit -m "feat(<site>): migrate <N> commands from <source-cli>
+
+- Phase A: <N> YAML adapters (read operations)
+- Phase B: <N> TS adapters (write operations)
+- Source: <source_repo_url>"
+git push
+```
+
+---
+
+## Checklist
+
+- [ ] 源项目命令清单已生成
+- [ ] 对比矩阵已确认，高价值缺失命令已筛选
+- [ ] 用户确认迁移范围
+- [ ] Phase A: YAML Read 适配器已完成
+- [ ] Phase B: TS Read 适配器已完成
+- [ ] Phase C: TS Write 适配器已完成
+- [ ] `npx tsc --noEmit` 编译通过
+- [ ] 所有新命令已实际运行验证
+- [ ] README.md 已更新
+- [ ] SKILL.md 已更新
+- [ ] 已 commit + push
+
+## 实战案例参考
+
+### rdt-cli → opencli Reddit（2026-03-16）
+
+- **源项目**: `rdt-cli`（25 个 Python 命令）
+- **筛选结果**: 13 个高价值命令
+- **实现**: 7 个 YAML（read） + 6 个 TS（write）
+- **产出**: +11 文件，+767 行代码，Reddit 适配器从 4 → 15（+275%）
+
+### twitter-cli → opencli Twitter（2026-03-16）
+
+- **源项目**: `twitter-cli`（20+ Python 命令）
+- **筛选结果**: 11 个待实现
+- **策略**: Read 用 `Strategy.COOKIE` + GraphQL fetch，Write 用 `Strategy.UI`

.agents/workflows/cross-project-adapter-migration.md

@@ -0,0 +1,54 @@
+---
+description: Migrate commands from an external CLI project into opencli adapters
+---
+
+// turbo-all
+
+## Steps
+
+1. Clone the source CLI project for analysis:
+```bash
+git clone <source_repo_url> /tmp/<source-cli>
+```
+
+2. Analyze source project: list all commands, auth method, API endpoints, and output fields.
+
+3. Check existing opencli adapters for the target site:
+```bash
+ls src/clis/<site>/
+opencli list | grep <site>
+```
+
+4. Generate a comparison matrix table (source commands vs opencli existing). Mark each as: ✅ **New** / ✅ **Enhance** / ❌ **Skip**. Ask user to confirm which commands to migrate.
+
+5. Implement YAML Read adapters first (highest ROI, 10-20 lines each). Place files in `src/clis/<site>/<name>.yaml`.
+
+6. Implement TS Read adapters for complex cases (GraphQL, pagination, signing). Place files in `src/clis/<site>/<name>.ts`.
+
+7. Implement TS Write adapters using `Strategy.UI` or `Strategy.COOKIE`. Place files in `src/clis/<site>/<name>.ts`.
+
+8. Verify build:
+```bash
+npx tsc --noEmit
+```
+
+9. Verify all commands are registered:
+```bash
+opencli list | grep <site>
+```
+
+10. Run each new command to verify it works:
+```bash
+opencli <site> <command> --limit 3 -f json
+```
+
+11. Update README.md with new command examples in the appropriate platform section.
+
+12. Update SKILL.md Commands Reference with new commands.
+
+13. Commit and push:
+```bash
+git add -A
+git commit -m "feat(<site>): migrate <N> commands from <source-cli>"
+git push
+```

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,83 @@
+name: "🐛 Bug Report"
+description: Report a bug or unexpected behavior in OpenCLI
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. A short reproduction and any error output are usually enough.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of the bug.
+      placeholder: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: How can we reproduce this behavior?
+      value: |
+        1. Run `opencli ...`
+        2. ...
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: OpenCLI Version
+      description: "Run `opencli --version` to find out."
+      placeholder: "0.8.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: node-version
+    attributes:
+      label: Node.js Version
+      options:
+        - "20.x"
+        - "22.x"
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - macOS
+        - Linux
+        - Windows
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Screenshots
+      description: |
+        Paste any relevant error output. Run with `-v` for verbose logs:
+        ```
+        opencli <command> -v
+        ```
+      render: shell
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 📖 Documentation
+    url: https://github.com/jackwener/opencli#readme
+    about: Check the README and docs before opening an issue.
+  - name: 🧪 Testing Guide
+    url: https://github.com/jackwener/opencli/blob/main/TESTING.md
+    about: How to run and write tests for OpenCLI.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,42 @@
+name: "✨ Feature Request"
+description: Suggest a new feature or improvement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have an idea to make OpenCLI better? We'd love to hear it!
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Feature Description
+      description: A clear and concise description of the feature you'd like.
+    validations:
+      required: true
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use Case
+      description: What problem does this solve? Who benefits from this feature?
+      placeholder: "As a user, I want to ... so that ..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed Solution
+      description: If you have a specific implementation in mind, describe it here.
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any alternative approaches you've thought about?
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/new_site_adapter.yml

@@ -0,0 +1,57 @@
+name: "🌐 New Site Adapter Request"
+description: Request support for a new website
+title: "[Site]: "
+labels: ["new-adapter"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Want OpenCLI to support a new site? Tell us about it!
+
+  - type: input
+    id: site-name
+    attributes:
+      label: Site Name
+      description: The name of the website.
+      placeholder: "e.g. Product Hunt"
+    validations:
+      required: true
+
+  - type: input
+    id: site-url
+    attributes:
+      label: Site URL
+      description: The main URL of the website.
+      placeholder: "https://www.producthunt.com"
+    validations:
+      required: true
+
+  - type: textarea
+    id: commands
+    attributes:
+      label: Desired Commands
+      description: What commands would you like? List them with a brief description.
+      value: |
+        - `hot` — trending / popular items
+        - `search` — search the site
+    validations:
+      required: true
+
+  - type: textarea
+    id: api-examples
+    attributes:
+      label: Example Links or API Endpoints
+      description: Share any example page URLs or API endpoints if you have them (optional).
+      placeholder: |
+        Example page: https://www.producthunt.com/posts/example
+        GET https://api.producthunt.com/v2/posts?order=votes
+        Response: { "posts": [{ "name": "...", "tagline": "..." }] }
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Willing to Contribute?
+      options:
+        - label: I'm willing to submit a PR for this adapter

.github/actions/setup-chrome/action.yml

@@ -0,0 +1,26 @@
+name: Setup Chrome + xvfb
+description: Install real Chrome and xvfb virtual display for headed browser testing
+
+outputs:
+  chrome-path:
+    description: Path to the installed Chrome binary
+    value: ${{ steps.setup-chrome.outputs.chrome-path }}
+
+runs:
+  using: composite
+  steps:
+    - name: Install real Chrome (stable)
+      uses: browser-actions/setup-chrome@v1
+      id: setup-chrome
+      with:
+        chrome-version: stable
+
+    - name: Verify Chrome installation
+      shell: bash
+      run: |
+        echo "Chrome path: ${{ steps.setup-chrome.outputs.chrome-path }}"
+        ${{ steps.setup-chrome.outputs.chrome-path }} --version
+
+    - name: Install xvfb for headed mode
+      shell: bash
+      run: sudo apt-get install -y xvfb

.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+
+updates:
+  # npm dependencies
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "chore(deps)"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "chore(ci)"

.github/pull_request_template.md

@@ -0,0 +1,31 @@
+## Description
+
+<!-- Briefly describe your changes and link to any related issues. -->
+
+Related issue:
+
+## Type of Change
+
+- [ ] 🐛 Bug fix
+- [ ] ✨ New feature
+- [ ] 🌐 New site adapter
+- [ ] 📝 Documentation
+- [ ] ♻️ Refactor
+- [ ] 🔧 CI / build / tooling
+
+## Checklist
+
+- [ ] I ran the checks relevant to this PR
+- [ ] I updated tests or docs if needed
+- [ ] I included output or screenshots when useful
+
+### Documentation (if adding/modifying an adapter)
+
+- [ ] Added doc page under `docs/adapters/` (if new adapter)
+- [ ] Updated `docs/adapters/index.md` table (if new adapter)
+- [ ] Updated sidebar in `docs/.vitepress/config.mts` (if new adapter)
+
+## Screenshots / Output
+
+<!-- If applicable, paste CLI output or screenshots here. -->
+

.github/workflows/build-extension.yml

@@ -0,0 +1,65 @@
+name: Build Chrome Extension
+
+on:
+  push:
+    branches: [ "main" ]
+    tags: [ "v*.*.*" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: 'npm'
+          cache-dependency-path: extension/package-lock.json
+
+      - name: Install extension dependencies
+        run: npm ci
+        working-directory: extension
+
+      - name: Build extension
+        run: npm run build
+        working-directory: extension
+
+      - name: Prepare extension package
+        run: |
+          rm -rf extension-package
+          mkdir -p extension-package
+          cp extension/manifest.json extension-package/
+          cp -R extension/dist extension-package/
+          cp -R extension/icons extension-package/
+
+      - name: Create Extension ZIP
+        run: |
+          cd extension-package
+          zip -r ../opencli-extension.zip .
+
+      - name: Upload Artifacts (Action Run)
+        uses: actions/upload-artifact@v7
+        with:
+          name: opencli-extension-build
+          path: |
+            opencli-extension.zip
+          retention-days: 7
+
+      - name: Attach to GitHub Release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v2.6.1
+        with:
+          files: |
+            opencli-extension.zip
+          draft: false
+          prerelease: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/ci.yml

@@ -2,19 +2,28 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, dev]
   pull_request:
-    branches: [main]
+    branches: [main, dev]
+  schedule:
+    - cron: '0 8 * * 1'  # Weekly Monday 08:00 UTC — smoke tests
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
-  check:
+  # ── Fast gate: typecheck + build ──
+  build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: '22'
+          cache: 'npm'
 
       - name: Install dependencies
         run: npm ci
@@ -24,3 +33,73 @@ jobs:
 
       - name: Build
         run: npm run build
+
+  # ── Unit tests (vitest shard) ──
+  unit-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: ['20', '22']
+        shard: [1, 2]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run unit tests (Node ${{ matrix.node-version }}, shard ${{ matrix.shard }}/2)
+        run: npm test -- --reporter=verbose --shard=${{ matrix.shard }}/2
+
+  adapter-test:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run focused adapter tests
+        run: npm run test:adapter -- --reporter=verbose
+
+  # ── Smoke tests (scheduled / manual only) ──
+  smoke-test:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Setup Chrome + xvfb
+        uses: ./.github/actions/setup-chrome
+        id: setup-chrome
+
+      - name: Build
+        run: npm run build
+
+      - name: Run smoke tests
+        run: |
+          xvfb-run --auto-servernum --server-args="-screen 0 1280x720x24" \
+            npx vitest run tests/smoke/ --reporter=verbose
+        env:
+          OPENCLI_BROWSER_EXECUTABLE_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}
+    timeout-minutes: 15

.github/workflows/doc-check.yml

@@ -0,0 +1,36 @@
+name: Doc Check
+
+on:
+  pull_request:
+    branches: [main, dev]
+
+concurrency:
+  group: doc-check-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ── Adapter doc coverage ──
+  doc-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Check adapter doc coverage
+        run: bash scripts/check-doc-coverage.sh --strict
+
+  # ── VitePress build validation ──
+  docs-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build docs (catches broken links & sidebar refs)
+        run: npm run docs:build

.github/workflows/docs.yml

@@ -0,0 +1,17 @@
+name: Trigger Website Rebuild (Docs Updated)
+
+on:
+  push:
+    branches: [main]
+    paths: ['docs/**']
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger opencli-website rebuild
+        uses: peter-evans/repository-dispatch@v4
+        with:
+          token: ${{ secrets.WEBSITE_DEPLOY_TOKEN }}
+          repository: jackwener/opencli-website
+          event-type: docs-updated

.github/workflows/e2e-headed.yml

@@ -0,0 +1,41 @@
+name: E2E Headed Chrome
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+  workflow_dispatch:
+
+concurrency:
+  group: e2e-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  e2e-headed:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Setup Chrome + xvfb
+        uses: ./.github/actions/setup-chrome
+        id: setup-chrome
+
+      - name: Build
+        run: npm run build
+
+      - name: Run E2E tests (headed Chrome + xvfb)
+        run: |
+          xvfb-run --auto-servernum --server-args="-screen 0 1280x720x24" \
+            npx vitest run tests/e2e/ --reporter=verbose
+        env:
+          OPENCLI_BROWSER_EXECUTABLE_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}

.github/workflows/pkg-pr-new.yml

@@ -0,0 +1,30 @@
+name: Publish Any Commit
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+
+permissions: {}
+
+jobs:
+  publish:
+    if: ${{ vars.PKG_PR_NEW_ENABLED == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish to pkg.pr.new
+        run: npx pkg-pr-new publish

.github/workflows/release.yml

@@ -13,9 +13,9 @@ jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: '22'
           registry-url: 'https://registry.npmjs.org'
@@ -26,11 +26,8 @@ jobs:
       - name: Type check
         run: npx tsc --noEmit
 
-      - name: Build
-        run: npm run build
-
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v2.6.1
         with:
           generate_release_notes: true
 
@@ -38,3 +35,10 @@ jobs:
         run: npm publish --provenance --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Trigger website rebuild
+        uses: peter-evans/repository-dispatch@v4
+        with:
+          token: ${{ secrets.WEBSITE_DEPLOY_TOKEN }}
+          repository: jackwener/opencli-website
+          event-type: version-released

.github/workflows/security.yml

@@ -0,0 +1,36 @@
+name: Security Audit
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+  schedule:
+    - cron: '0 9 * * 1'  # Weekly Monday 09:00 UTC
+
+permissions:
+  contents: read
+
+concurrency:
+  group: security-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: npm audit (production)
+        run: npm audit --omit=dev --audit-level=high
+
+      - name: Check for known vulnerabilities
+        run: npx --yes audit-ci@^7 --high --skip-dev

.gitignore

@@ -1,4 +1,24 @@
 node_modules/
 dist/
+!extension/dist/
 *.tsbuildinfo
 .opencli/
+.mcp.json
+*.log
+.DS_Store
+
+# VitePress
+docs/.vitepress/dist
+docs/.vitepress/cache
+
+# Extensions & Secrets
+*.pem
+*.crx
+*.zip
+.envrc
+.windsurf
+.claude
+.cortex
+
+# Database files
+*.db

CHANGELOG.md

@@ -0,0 +1,159 @@
+# Changelog
+
+## [1.3.2](https://github.com/jackwener/opencli/compare/v1.3.1...v1.3.2) (2026-03-24)
+
+
+### Features
+
+* **error-handling:** refine error handling with semantic error types and emoji-coded output ([#312](https://github.com/jackwener/opencli/issues/312)) ([b4d64ca](https://github.com/jackwener/opencli/commit/b4d64ca))
+
+
+### Bug Fixes
+
+* **security:** replace execSync with execFileSync to prevent command injection ([#309](https://github.com/jackwener/opencli/issues/309)) ([41aedf6](https://github.com/jackwener/opencli/commit/41aedf6))
+* remove duplicate getErrorMessage import in discovery.ts ([#315](https://github.com/jackwener/opencli/issues/315)) ([75f4237](https://github.com/jackwener/opencli/commit/75f4237))
+* **e2e:** broaden xiaoyuzhou skip logic for overseas CI runners ([#316](https://github.com/jackwener/opencli/issues/316)) ([a170873](https://github.com/jackwener/opencli/commit/a170873))
+
+
+### Documentation
+
+* **SKILL.md:** sync command reference — add missing sites and desktop adapters ([#314](https://github.com/jackwener/opencli/issues/314)) ([8bf750c](https://github.com/jackwener/opencli/commit/8bf750c))
+
+
+### Chores
+
+* pre-release cleanup — fix dependencies, sync docs, reduce code duplication ([#311](https://github.com/jackwener/opencli/issues/311)) ([c9b3568](https://github.com/jackwener/opencli/commit/c9b3568))
+
+
+## [1.3.1](https://github.com/jackwener/opencli/compare/v1.3.0...v1.3.1) (2026-03-22)
+
+
+### Features
+
+* **plugin:** add update command, hot reload after install, README section ([#307](https://github.com/jackwener/opencli/issues/307)) ([966f6e5](https://github.com/jackwener/opencli/commit/966f6e5))
+* **yollomi:** add new commands and update documentation ([#235](https://github.com/jackwener/opencli/issues/235)) ([ea83242](https://github.com/jackwener/opencli/commit/ea83242))
+* **record:** add live recording command for API capture ([#300](https://github.com/jackwener/opencli/issues/300)) ([dff0fe5](https://github.com/jackwener/opencli/commit/dff0fe5))
+* **weibo:** add weibo search command ([#299](https://github.com/jackwener/opencli/issues/299)) ([c7895ea](https://github.com/jackwener/opencli/commit/c7895ea))
+* **v2ex:** add node, user, member, replies, nodes commands ([#282](https://github.com/jackwener/opencli/issues/282)) ([a83027d](https://github.com/jackwener/opencli/commit/a83027d))
+* **hackernews:** add new, best, ask, show, jobs, search, user commands ([#290](https://github.com/jackwener/opencli/issues/290)) ([127a974](https://github.com/jackwener/opencli/commit/127a974))
+* **doubao-app:** add Doubao AI desktop app CLI adapter ([#289](https://github.com/jackwener/opencli/issues/289)) ([66c4b84](https://github.com/jackwener/opencli/commit/66c4b84))
+* **doubao:** add doubao browser adapter ([#277](https://github.com/jackwener/opencli/issues/277)) ([9cdc127](https://github.com/jackwener/opencli/commit/9cdc127))
+* **xiaohongshu:** add publish command for 图文 note automation ([#276](https://github.com/jackwener/opencli/issues/276)) ([a6d993f](https://github.com/jackwener/opencli/commit/a6d993f))
+* **weixin:** add weixin article download adapter & abstract download helpers ([#280](https://github.com/jackwener/opencli/issues/280)) ([b7c6c02](https://github.com/jackwener/opencli/commit/b7c6c02))
+
+
+### Bug Fixes
+
+* **tests:** use positional arg syntax in browser search tests ([#302](https://github.com/jackwener/opencli/issues/302)) ([4343ec0](https://github.com/jackwener/opencli/commit/4343ec0))
+* **xiaohongshu:** improve search login-wall handling and detail output ([#298](https://github.com/jackwener/opencli/issues/298)) ([f8bf663](https://github.com/jackwener/opencli/commit/f8bf663))
+* ensure standard PATH is available for external CLIs ([#285](https://github.com/jackwener/opencli/issues/285)) ([22f5c7a](https://github.com/jackwener/opencli/commit/22f5c7a))
+* **xiaohongshu:** scope image selector to avoid downloading avatars ([#293](https://github.com/jackwener/opencli/issues/293)) ([3a21be6](https://github.com/jackwener/opencli/commit/3a21be6))
+* add turndown dependency to package.json ([#288](https://github.com/jackwener/opencli/issues/288)) ([2a52906](https://github.com/jackwener/opencli/commit/2a52906))
+
+
+## [1.3.0](https://github.com/jackwener/opencli/compare/v1.2.3...v1.3.0) (2026-03-21)
+
+
+### Features
+
+* **daemon:** harden security against browser CSRF attacks ([#268](https://github.com/jackwener/opencli/issues/268)) ([40bd11d](https://github.com/jackwener/opencli/commit/40bd11d))
+
+
+### Performance
+
+* smart page settle via DOM stability detection ([#271](https://github.com/jackwener/opencli/issues/271)) ([4b976da](https://github.com/jackwener/opencli/commit/4b976da))
+
+
+### Refactoring
+
+* doctor defaults to live mode, remove setup command entirely ([#263](https://github.com/jackwener/opencli/issues/263)) ([b4a8089](https://github.com/jackwener/opencli/commit/b4a8089))
+
+
+## [1.2.3](https://github.com/jackwener/opencli/compare/v1.2.2...v1.2.3) (2026-03-21)
+
+
+### Bug Fixes
+
+* replace all about:blank with data: URI to prevent New Tab Override interception ([#257](https://github.com/jackwener/opencli/issues/257)) ([3e91876](https://github.com/jackwener/opencli/commit/3e91876))
+* harden resolveTabId against New Tab Override extension interception ([#255](https://github.com/jackwener/opencli/issues/255)) ([112fdef](https://github.com/jackwener/opencli/commit/112fdef))
+
+
+## [1.2.2](https://github.com/jackwener/opencli/compare/v1.2.1...v1.2.2) (2026-03-21)
+
+
+### Bug Fixes
+
+* harden browser automation pipeline (resolves [#249](https://github.com/jackwener/opencli/issues/249)) ([#251](https://github.com/jackwener/opencli/issues/251)) ([71b2c39](https://github.com/jackwener/opencli/commit/71b2c39))
+
+
+## [1.2.1](https://github.com/jackwener/opencli/compare/v1.2.0...v1.2.1) (2026-03-21)
+
+
+### Bug Fixes
+
+* **twitter:** harden timeline review findings ([#236](https://github.com/jackwener/opencli/issues/236)) ([4cd0409](https://github.com/jackwener/opencli/commit/4cd0409))
+* **wikipedia:** fix search arg name + add random and trending commands ([#231](https://github.com/jackwener/opencli/issues/231)) ([1d56dd7](https://github.com/jackwener/opencli/commit/1d56dd7))
+* resolve inconsistent doctor --live report (fix [#121](https://github.com/jackwener/opencli/issues/121)) ([#224](https://github.com/jackwener/opencli/issues/224)) ([387aa0d](https://github.com/jackwener/opencli/commit/387aa0d))
+
+
+## [1.2.0](https://github.com/jackwener/opencli/compare/v1.1.0...v1.2.0) (2026-03-21)
+
+
+### Features
+
+* **douban:** add movie adapter with search, top250, subject, marks, reviews commands ([#239](https://github.com/jackwener/opencli/issues/239)) ([70651d3](https://github.com/jackwener/opencli/commit/70651d3))
+* **devto:** add devto adapter ([#234](https://github.com/jackwener/opencli/issues/234)) ([ea113a6](https://github.com/jackwener/opencli/commit/ea113a6))
+* **twitter:** add --type flag to timeline command ([#83](https://github.com/jackwener/opencli/issues/83)) ([e98cf75](https://github.com/jackwener/opencli/commit/e98cf75))
+* **google:** add search, suggest, news, and trends adapters ([#184](https://github.com/jackwener/opencli/issues/184)) ([4e32599](https://github.com/jackwener/opencli/commit/4e32599))
+* add douban, sinablog, substack adapters; upgrade medium to TS ([#185](https://github.com/jackwener/opencli/issues/185)) ([bdf5967](https://github.com/jackwener/opencli/commit/bdf5967))
+* **xueqiu:** add earnings-date command ([#211](https://github.com/jackwener/opencli/issues/211)) ([fae1dce](https://github.com/jackwener/opencli/commit/fae1dce))
+* **browser:** advanced DOM snapshot engine with 13-layer pruning pipeline ([#210](https://github.com/jackwener/opencli/issues/210)) ([d831b04](https://github.com/jackwener/opencli/commit/d831b04))
+* **instagram,facebook:** add write actions and extended commands ([#201](https://github.com/jackwener/opencli/issues/201)) ([eb0ccaf](https://github.com/jackwener/opencli/commit/eb0ccaf))
+* **grok:** add opt-in --web flow for grok ask ([#193](https://github.com/jackwener/opencli/issues/193)) ([fcff2e4](https://github.com/jackwener/opencli/commit/fcff2e4))
+* **tiktok:** add TikTok adapter with 15 commands ([#202](https://github.com/jackwener/opencli/issues/202)) ([4391ccf](https://github.com/jackwener/opencli/commit/4391ccf))
+* add Lobste.rs, Instagram, and Facebook adapters ([#199](https://github.com/jackwener/opencli/issues/199)) ([ce484c2](https://github.com/jackwener/opencli/commit/ce484c2))
+* **medium:** add medium adapter ([#190](https://github.com/jackwener/opencli/issues/190)) ([06c902a](https://github.com/jackwener/opencli/commit/06c902a))
+* plugin system (Stage 0-2) ([1d39295](https://github.com/jackwener/opencli/commit/1d39295))
+* make primary args positional across all CLIs ([#242](https://github.com/jackwener/opencli/issues/242)) ([9696db9](https://github.com/jackwener/opencli/commit/9696db9))
+* **xueqiu:** make primary args positional ([#213](https://github.com/jackwener/opencli/issues/213)) ([fb2a145](https://github.com/jackwener/opencli/commit/fb2a145))
+
+
+### Refactoring
+
+* replace hardcoded skipPreNav with declarative navigateBefore field ([#208](https://github.com/jackwener/opencli/issues/208)) ([a228758](https://github.com/jackwener/opencli/commit/a228758))
+* **boss:** extract common.ts utilities, fix missing login detection ([#200](https://github.com/jackwener/opencli/issues/200)) ([ae30763](https://github.com/jackwener/opencli/commit/ae30763))
+* type discovery core ([#219](https://github.com/jackwener/opencli/issues/219)) ([bd274ce](https://github.com/jackwener/opencli/commit/bd274ce))
+* type browser core ([#218](https://github.com/jackwener/opencli/issues/218)) ([28c393e](https://github.com/jackwener/opencli/commit/28c393e))
+* type pipeline core ([#217](https://github.com/jackwener/opencli/issues/217)) ([8a4ea41](https://github.com/jackwener/opencli/commit/8a4ea41))
+* reduce core any usage ([#216](https://github.com/jackwener/opencli/issues/216)) ([45cee57](https://github.com/jackwener/opencli/commit/45cee57))
+* fail fast on invalid pipeline steps ([#237](https://github.com/jackwener/opencli/issues/237)) ([c76f86c](https://github.com/jackwener/opencli/commit/c76f86c))
+
+## [1.1.0](https://github.com/jackwener/opencli/compare/v1.0.6...v1.1.0) (2026-03-20)
+
+
+### Features
+
+* add antigravity serve command — Anthropic API proxy ([35a0fed](https://github.com/jackwener/opencli/commit/35a0fed8a0c1cb714298f672c19f017bbc9a9630))
+* add arxiv and wikipedia adapters ([#132](https://github.com/jackwener/opencli/issues/132)) ([3cda14a](https://github.com/jackwener/opencli/commit/3cda14a2ab502e3bebfba6cdd9842c35b2b66b41))
+* add external CLI hub for discovery, auto-installation, and execution of external tools. ([b3e32d8](https://github.com/jackwener/opencli/commit/b3e32d8a05744c9bcdfef96f5ff3085ac72bd353))
+* add sinafinance 7x24 news adapter ([#131](https://github.com/jackwener/opencli/issues/131)) ([02793e9](https://github.com/jackwener/opencli/commit/02793e990ef4bdfdde9d7a748960b8a9ed6ea988))
+* **boss:** add 8 new recruitment management commands ([#133](https://github.com/jackwener/opencli/issues/133)) ([7e973ca](https://github.com/jackwener/opencli/commit/7e973ca59270029f33021a483ca4974dc3975d36))
+* **serve:** implement auto new conv, model mapping, and precise completion detection ([0e8c96b](https://github.com/jackwener/opencli/commit/0e8c96b6d9baebad5deb90b9e0620af5570b259d))
+* **serve:** use CDP mouse click + Input.insertText for reliable message injection ([c63af6d](https://github.com/jackwener/opencli/commit/c63af6d41808dddf6f0f76789aa6c042f391f0b0))
+* xiaohongshu creator flows migration ([#124](https://github.com/jackwener/opencli/issues/124)) ([8f17259](https://github.com/jackwener/opencli/commit/8f1725982ec06d121d7c15b5cf3cda2f5941c32a))
+
+
+### Bug Fixes
+
+* **docs:** use base '/' for custom domain and add CNAME file ([#129](https://github.com/jackwener/opencli/issues/129)) ([2876750](https://github.com/jackwener/opencli/commit/2876750891bc8a66be577b06ead4db61852c8e81))
+* **serve:** update model mappings to match actual Antigravity UI ([36bc57a](https://github.com/jackwener/opencli/commit/36bc57a9624cdfaa50ffb2c1ad7f9c518c5e6c55))
+* type safety for wikiFetch and arxiv abstract truncation ([4600b9d](https://github.com/jackwener/opencli/commit/4600b9d46dc7b56ff564c5f100c3a94c6a792c06))
+* use UTC+8 for XHS timestamp formatting (CI timezone fix) ([03f067d](https://github.com/jackwener/opencli/commit/03f067d90764487f0439705df36e1a5c969a7f98))
+* **xiaohongshu:** use fixed UTC+8 offset in trend timestamp formatting (CI timezone fix) ([593436e](https://github.com/jackwener/opencli/commit/593436e4cb5852f396fbaaa9f87ef1a0b518e76d))
+
+## [1.0.6](https://github.com/jackwener/opencli/compare/v1.0.5...v1.0.6) (2026-03-20)
+
+
+### Bug Fixes
+
+* use %20 instead of + for spaces in Bilibili WBI signed requests ([#126](https://github.com/jackwener/opencli/issues/126)) ([4cabca1](https://github.com/jackwener/opencli/commit/4cabca12dfa6ca027b938b80ee6b940b5e89ea5c)), closes [#125](https://github.com/jackwener/opencli/issues/125)

CLI-EXPLORER.md

@@ -0,0 +1,724 @@
+# CLI-EXPLORER — 适配器探索式开发完全指南
+
+> 本文档教你（或 AI Agent）如何为 OpenCLI 添加一个新网站的命令。  
+> 从零到发布，覆盖 API 发现、方案选择、适配器编写、测试验证全流程。
+
+> [!TIP]
+> **只想为一个具体页面快速生成一个命令？** 看 [CLI-ONESHOT.md](./CLI-ONESHOT.md)（~150 行，4 步搞定）。
+> 本文档适合从零探索一个新站点的完整流程。
+
+---
+
+## AI Agent 开发者必读：用浏览器探索
+
+> [!CAUTION]
+> **你（AI Agent）必须通过浏览器打开目标网站去探索！**  
+> 不要只靠 `opencli explore` 命令或静态分析来发现 API。  
+> 你拥有浏览器工具，必须主动用它们浏览网页、观察网络请求、模拟用户交互。
+
+### 为什么？
+
+很多 API 是**懒加载**的（用户必须点击某个按钮/标签才会触发网络请求）。字幕、评论、关注列表等深层数据不会在页面首次加载时出现在 Network 面板中。**如果你不主动去浏览和交互页面，你永远发现不了这些 API。**
+
+### AI Agent 探索工作流（必须遵循）
+
+| 步骤 | 工具 | 做什么 |
+|------|------|--------|
+| 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 写适配器 |
+
+### 常犯错误
+
+| ❌ 错误做法 | ✅ 正确做法 |
+|------------|------------|
+| 只用 `opencli explore` 命令，等结果自动出来 | 用浏览器工具打开页面，主动浏览 |
+| 直接在代码里 `fetch(url)`，不看浏览器实际请求 | 先在浏览器中确认 API 可用，再写代码 |
+| 页面打开后直接抓包，期望所有 API 都出现 | 模拟点击交互（展开评论/切换标签/加载更多） |
+| 遇到 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 策略确认
+
+---
+
+## 核心流程
+
+```
+ ┌─────────────┐     ┌─────────────┐     ┌──────────────┐     ┌────────┐
+ │ 1. 发现 API  │ ──▶ │ 2. 选择策略  │ ──▶ │ 3. 写适配器   │ ──▶ │ 4. 测试 │
+ └─────────────┘     └─────────────┘     └──────────────┘     └────────┘
+   explore             cascade             YAML / TS            run + verify
+```
+
+---
+
+## Step 1: 发现 API
+
+### 1a. 自动化发现（推荐）
+
+OpenCLI 内置 Deep Explore，自动分析网站网络请求：
+
+```bash
+opencli explore https://www.example.com --site mysite
+```
+
+输出到 `.opencli/explore/mysite/`：
+
+| 文件 | 内容 |
+|------|------|
+| `manifest.json` | 站点元数据、框架检测（Vue2/3、React、Next.js、Pinia、Vuex） |
+| `endpoints.json` | 已发现的 API 端点，按评分排序，含 URL pattern、方法、响应类型 |
+| `capabilities.json` | 推理出的功能（`hot`、`search`、`feed`…），含置信度和推荐参数 |
+| `auth.json` | 认证方式检测（Cookie/Header/无认证），策略候选列表 |
+
+### 1b. 手动抓包验证
+
+Explore 的自动分析可能不完美，用 verbose 模式手动确认：
+
+```bash
+# 在浏览器中打开目标页面，观察网络请求
+opencli explore https://www.example.com --site mysite -v
+
+# 或直接用 evaluate 测试 API
+opencli bilibili hot -v   # 查看已有命令的 pipeline 每步数据流
+```
+
+关注抓包结果中的关键信息：
+- **URL pattern**: `/api/v2/hot?limit=20` → 这就是你要调用的端点
+- **Method**: `GET` / `POST`
+- **Request Headers**: Cookie? Bearer? 自定义签名头（X-s、X-t）?
+- **Response Body**: JSON 结构，特别是数据在哪个路径（`data.items`、`data.list`）
+
+### 1c. 高阶 API 发现捷径法则 (Heuristics)
+
+在开始死磕复杂的抓包拦截之前，按照以下优先级进行尝试：
+
+1. **后缀爆破法 (`.json`)**: 像 Reddit 这样复杂的网站，只要在其 URL 后加上 `.json`（例如 `/r/all.json`），就能在带 Cookie 的情况下直接利用 `fetch` 拿到极其干净的 REST 数据（Tier 2 Cookie 策略极速秒杀）。另外如功能完备的**雪球 (xueqiu)** 也可以走这种纯 API 的方式极简获取，成为你构建简单 YAML 的黄金标杆。
+2. **全局状态查找法 (`__INITIAL_STATE__`)**: 许多服务端渲染 (SSR) 的网站（如小红书、Bilibili）会将首页或详情页的完整数据挂载到全局 window 对象上。与其去拦截网络请求，不如直接 `page.evaluate('() => window.__INITIAL_STATE__')` 获取整个数据树。
+3. **主动交互触发法 (Active Interaction)**: 很多深层 API（如视频字幕、评论下的回复）是懒加载的。在静态抓包找不到数据时，尝试在 `evaluate` 步骤或手动打断点时，主动去**点击（Click）页面上的对应按钮**（如"CC"、"展开全部"），从而诱发隐藏的 Network Fetch。
+4. **框架探测与 Store Action 截断**: 如果站点使用 Vue + Pinia，可以使用 `tap` 步骤调用 action，让前端框架代替你完成复杂的鉴权签名封装。
+5. **底层 XHR/Fetch 拦截**: 最后手段，当上述都不行时，使用 TypeScript 适配器进行无侵入式的请求抓取。
+
+### 1d. 框架检测
+
+Explore 自动检测前端框架。如果需要手动确认：
+
+```bash
+# 在已打开目标网站的情况下
+opencli evaluate "(()=>{
+  const vue3 = !!document.querySelector('#app')?.__vue_app__;
+  const vue2 = !!document.querySelector('#app')?.__vue__;
+  const react = !!window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  const pinia = vue3 && !!document.querySelector('#app').__vue_app__.config.globalProperties.\$pinia;
+  return JSON.stringify({vue3, vue2, react, pinia});
+})()"
+```
+
+Vue + Pinia 的站点（如小红书）可以直接通过 Store Action 绕过签名。
+
+---
+
+## Step 2: 选择认证策略
+
+OpenCLI 提供 5 级认证策略。使用 `cascade` 命令自动探测：
+
+```bash
+opencli cascade https://api.example.com/hot
+```
+
+### 策略决策树
+
+```
+直接 fetch(url) 能拿到数据？
+  → ✅ Tier 1: public（公开 API，不需要浏览器）
+  → ❌ fetch(url, {credentials:'include'}) 带 Cookie 能拿到？
+       → ✅ Tier 2: cookie（最常见，evaluate 步骤内 fetch）
+       → ❌ → 加上 Bearer / CSRF header 后能拿到？
+              → ✅ Tier 3: header（如 Twitter ct0 + Bearer）
+              → ❌ → 网站有 Pinia/Vuex Store？
+                     → ✅ Tier 4: intercept（Store Action + XHR 拦截）
+                     → ❌ Tier 5: ui（UI 自动化，最后手段）
+```
+
+### 各策略对比
+
+| Tier | 策略 | 速度 | 复杂度 | 适用场景 | 实例 |
+|------|------|------|--------|---------|------|
+| 1 | `public` | ⚡ ~1s | 最简 | 公开 API，无需登录 | Hacker News, V2EX |
+| 2 | `cookie` | 🔄 ~7s | 简单 | Cookie 认证即可 | Bilibili, Zhihu, Reddit |
+| 3 | `header` | 🔄 ~7s | 中等 | 需要 CSRF token 或 Bearer | Twitter GraphQL |
+| 4 | `intercept` | 🔄 ~10s | 较高 | 请求有复杂签名 | 小红书 (Pinia + XHR) |
+| 5 | `ui` | 🐌 ~15s+ | 最高 | 无 API，纯 DOM 解析 | 遗留网站 |
+
+---
+
+## 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/clis/bilibili/utils.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？先看决策树
+
+```
+你的 pipeline 里有 evaluate 步骤（内嵌 JS 代码）？
+  → ✅ 用 TypeScript (src/clis/<site>/<name>.ts)，保存即自动动态注册
+  → ❌ 纯声明式（navigate + tap + map + limit）？
+       → ✅ 用 YAML (src/clis/<site>/<name>.yaml)，保存即自动注册
+```
+
+| 场景 | 选择 | 示例 |
+|------|------|------|
+| 纯 fetch/select/map/limit | YAML | `v2ex/hot.yaml`, `hackernews/top.yaml` |
+| navigate + evaluate(fetch) + map | YAML（评估复杂度） | `zhihu/hot.yaml` |
+| navigate + tap + map | YAML ✅ | `xiaohongshu/feed.yaml`, `xiaohongshu/notifications.yaml` |
+| 有复杂 JS 逻辑（Pinia state 读取、条件分支） | TS | `xiaohongshu/me.ts`, `bilibili/me.ts` |
+| XHR 拦截 + 签名 | TS | `xiaohongshu/search.ts` |
+| GraphQL / 分页 / Wbi 签名 | TS | `bilibili/search.ts`, `twitter/search.ts` |
+
+> **经验法则**：如果你发现 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`，放入即自动注册。
+
+#### Tier 1 — 公开 API 模板
+
+```yaml
+# src/clis/v2ex/hot.yaml
+site: v2ex
+name: hot
+description: V2EX 热门话题
+domain: www.v2ex.com
+strategy: public
+browser: false
+
+args:
+  limit:
+    type: int
+    default: 20
+
+pipeline:
+  - fetch:
+      url: https://www.v2ex.com/api/topics/hot.json
+
+  - map:
+      rank: ${{ index + 1 }}
+      title: ${{ item.title }}
+      replies: ${{ item.replies }}
+
+  - limit: ${{ args.limit }}
+
+columns: [rank, title, replies]
+```
+
+#### Tier 2 — Cookie 认证模板（最常用）
+
+```yaml
+# src/clis/zhihu/hot.yaml
+site: zhihu
+name: hot
+description: 知乎热榜
+domain: www.zhihu.com
+
+pipeline:
+  - navigate: https://www.zhihu.com       # 先加载页面建立 session
+
+  - evaluate: |                            # 在浏览器内发请求，自动带 Cookie
+      (async () => {
+        const res = await fetch('/api/v3/feed/topstory/hot-lists/total?limit=50', {
+          credentials: 'include'
+        });
+        const d = await res.json();
+        return (d?.data || []).map(item => {
+          const t = item.target || {};
+          return {
+            title: t.title,
+            heat: item.detail_text || '',
+            answers: t.answer_count,
+          };
+        });
+      })()
+
+  - map:
+      rank: ${{ index + 1 }}
+      title: ${{ item.title }}
+      heat: ${{ item.heat }}
+      answers: ${{ item.answers }}
+
+  - limit: ${{ args.limit }}
+
+columns: [rank, title, heat, answers]
+```
+
+> **关键**: `evaluate` 步骤内的 `fetch` 运行在浏览器页面内，自动携带 `credentials: 'include'`，无需手动处理 Cookie。
+
+#### 进阶 — 带搜索参数
+
+```yaml
+# src/clis/zhihu/search.yaml
+site: zhihu
+name: search
+description: 知乎搜索
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Search query
+  limit:
+    type: int
+    default: 10
+
+pipeline:
+  - navigate: https://www.zhihu.com
+
+  - evaluate: |
+      (async () => {
+        const q = encodeURIComponent('${{ args.query }}');
+        const res = await fetch('/api/v4/search_v3?q=' + q + '&t=general&limit=${{ args.limit }}', {
+          credentials: 'include'
+        });
+        const d = await res.json();
+        return (d?.data || [])
+          .filter(item => item.type === 'search_result')
+          .map(item => ({
+            title: (item.object?.title || '').replace(/<[^>]+>/g, ''),
+            type: item.object?.type || '',
+            author: item.object?.author?.name || '',
+            votes: item.object?.voteup_count || 0,
+          }));
+      })()
+
+  - map:
+      rank: ${{ index + 1 }}
+      title: ${{ item.title }}
+      type: ${{ item.type }}
+      author: ${{ item.author }}
+      votes: ${{ item.votes }}
+
+  - limit: ${{ args.limit }}
+
+columns: [rank, title, type, author, votes]
+```
+
+#### Tier 4 — Store Action Bridge（`tap` 步骤，intercept 策略推荐）
+
+适用于 Vue + Pinia/Vuex 的网站（如小红书），无须手动写 XHR 拦截代码：
+
+```yaml
+# src/clis/xiaohongshu/notifications.yaml
+site: xiaohongshu
+name: notifications
+description: "小红书通知"
+domain: www.xiaohongshu.com
+strategy: intercept
+browser: true
+
+args:
+  type:
+    type: str
+    default: mentions
+    description: "Notification type: mentions, likes, or connections"
+  limit:
+    type: int
+    default: 20
+
+columns: [rank, user, action, content, note, time]
+
+pipeline:
+  - navigate: https://www.xiaohongshu.com/notification
+  - wait: 3
+  - tap:
+      store: notification       # Pinia store name
+      action: getNotification   # Store action to call
+      args:                     # Action arguments
+        - ${{ args.type | default('mentions') }}
+      capture: /you/            # URL pattern to capture response
+      select: data.message_list # Extract sub-path from response
+      timeout: 8
+  - map:
+      rank: ${{ index + 1 }}
+      user: ${{ item.user_info.nickname }}
+      action: ${{ item.title }}
+      content: ${{ item.comment_info.content }}
+  - limit: ${{ args.limit | default(20) }}
+```
+
+> **`tap` 步骤自动完成**：注入 fetch+XHR 双拦截 → 查找 Pinia/Vuex store → 调用 action → 捕获匹配 URL 的响应 → 清理拦截。  
+> 如果 store 或 action 找不到，会返回 `hint` 列出所有可用的 store actions，方便调试。
+
+| tap 参数 | 必填 | 说明 |
+|---------|------|------|
+| `store` | ✅ | Pinia store 名称（如 `feed`, `search`, `notification`） |
+| `action` | ✅ | Store action 方法名 |
+| `capture` | ✅ | URL 子串匹配（匹配网络请求 URL） |
+| `args` | ❌ | 传给 action 的参数数组 |
+| `select` | ❌ | 从 captured JSON 中提取的路径（如 `data.items`） |
+| `timeout` | ❌ | 等待网络响应的超时秒数（默认 5s） |
+| `framework` | ❌ | `pinia` 或 `vuex`（默认自动检测） |
+
+### 方式 B: TypeScript 适配器（编程式）
+
+适用于需要嵌入 JS 代码读取 Pinia state、XHR 拦截、GraphQL、分页、复杂数据转换等场景。
+
+文件路径: `src/clis/<site>/<name>.ts`。文件将会在运行时被动态扫描并注册（切勿在 `index.ts` 中手动 `import`）。
+
+#### Tier 3 — Header 认证（Twitter）
+
+```typescript
+// src/clis/twitter/search.ts
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'twitter',
+  name: 'search',
+  description: 'Search tweets',
+  strategy: Strategy.HEADER,
+  args: [{ name: 'query', required: true, positional: true }],
+  columns: ['rank', 'author', 'text', 'likes'],
+  func: async (page, kwargs) => {
+    await page.goto('https://x.com');
+    const data = await page.evaluate(`
+      (async () => {
+        // 从 Cookie 提取 CSRF token
+        const ct0 = document.cookie.split(';')
+          .map(c => c.trim())
+          .find(c => c.startsWith('ct0='))?.split('=')[1];
+        if (!ct0) return { error: 'Not logged in' };
+
+        const bearer = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D...';
+        const headers = {
+          'Authorization': 'Bearer ' + decodeURIComponent(bearer),
+          'X-Csrf-Token': ct0,
+          'X-Twitter-Auth-Type': 'OAuth2Session',
+        };
+
+        const variables = JSON.stringify({ rawQuery: '${kwargs.query}', count: 20 });
+        const url = '/i/api/graphql/xxx/SearchTimeline?variables=' + encodeURIComponent(variables);
+        const res = await fetch(url, { headers, credentials: 'include' });
+        return await res.json();
+      })()
+    `);
+    // ... 解析 data
+  },
+});
+```
+
+#### Tier 4 — XHR/Fetch 双重拦截 (Twitter/小红书 通用模式)
+
+```typescript
+// src/clis/xiaohongshu/user.ts
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'xiaohongshu',
+  name: 'user',
+  description: '获取用户笔记',
+  strategy: Strategy.INTERCEPT,
+  args: [{ name: 'id', required: true }],
+  columns: ['rank', 'title', 'likes', 'url'],
+  func: async (page, kwargs) => {
+    await page.goto(`https://www.xiaohongshu.com/user/profile/${kwargs.id}`);
+    await page.wait(5);
+
+    // XHR/Fetch 底层拦截：捕获所有包含 'v1/user/posted' 的请求
+    await page.installInterceptor('v1/user/posted');
+
+    // 触发后端 API：模拟人类用户向底部滚动2次
+    await page.autoScroll({ times: 2, delayMs: 2000 });
+
+    // 提取所有被拦截捕获的 JSON 响应体
+    const requests = await page.getInterceptedRequests();
+    if (!requests || requests.length === 0) return [];
+
+    let results = [];
+    for (const req of requests) {
+      if (req.data?.data?.notes) {
+        for (const note of req.data.data.notes) {
+           results.push({
+             title: note.display_title || '',
+             likes: note.interact_info?.liked_count || '0',
+             url: `https://explore/${note.note_id || note.id}`
+           });
+        }
+      }
+    }
+
+    return results.slice(0, 20).map((item, i) => ({
+      rank: i + 1, ...item,
+    }));
+  },
+});
+```
+
+> **拦截核心思路**：不自己构造签名，而是利用 `installInterceptor` 劫持网站自己的 `XMLHttpRequest` 和 `fetch`，让网站发请求，我们直接在底层取出解析好的 `response.json()`。
+
+> **级联请求**（如 BVID→CID→字幕）的完整模板和要点见下方[进阶模式: 级联请求](#进阶模式-级联请求-cascading-requests)章节。
+
+---
+
+## Step 4: 测试
+
+> **构建通过 ≠ 功能正常**。`npm run build` 只验证 TypeScript / YAML 语法，不验证运行时行为。  
+> 每个新命令 **必须实际运行** 并确认输出正确后才算完成。
+
+### 必做清单
+
+```bash
+# 1. 构建（确认语法无误）
+npm run build
+
+# 2. 确认命令已注册
+opencli list | grep mysite
+
+# 3. 实际运行命令（最关键！）
+opencli mysite hot --limit 3 -v        # verbose 查看每步数据流
+opencli mysite hot --limit 3 -f json   # JSON 输出确认字段完整
+```
+
+### tap 步骤调试（intercept 策略专用）
+
+> **不要猜 store name / action name**。先用 evaluate 探索，再写 YAML。
+
+#### Step 1: 列出所有 Pinia store
+
+在浏览器中打开目标网站后：
+
+```bash
+opencli evaluate "(() => {
+  const app = document.querySelector('#app')?.__vue_app__;
+  const pinia = app?.config?.globalProperties?.\$pinia;
+  return [...pinia._s.keys()];
+})()"
+# 输出: ["user", "feed", "search", "notification", ...]
+```
+
+#### Step 2: 查看 store 的 action 名称
+
+故意写一个错误 action 名，tap 会返回所有可用 actions：
+
+```
+⚠  tap: Action not found: wrongName on store notification
+💡 Available: getNotification, replyComment, getNotificationCount, reset
+```
+
+#### Step 3: 用 network requests 确认 capture 模式
+
+```bash
+# 在浏览器打开目标页面，查看网络请求
+# 找到目标 API 的 URL 特征（如 "/you/mentions"、"homefeed"）
+```
+
+#### 完整流程
+
+```
+ ┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌────────┐
+ │ 1. navigate  │ ──▶ │ 2. 探索 store │ ──▶ │ 3. 写 YAML   │ ──▶ │ 4. 测试 │
+ │    到目标页面  │     │ name/action  │     │    tap 步骤   │     │ 运行验证 │
+ └──────────────┘     └──────────────┘     └──────────────┘     └────────┘
+```
+
+### Verbose 模式 & 输出验证
+
+```bash
+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: 提交发布
+
+文件放入 `src/clis/<site>/` 即自动注册（YAML 或 TS 无需手动 import），然后：
+
+```bash
+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` 二进制。
+
+---
+
+## 进阶模式: 级联请求 (Cascading Requests)
+
+当目标数据需要多步 API 链式获取时（如 `BVID → CID → 字幕列表 → 字幕内容`），必须使用 **TS 适配器**。YAML 无法处理这种多步逻辑。
+
+### 模板代码
+
+```typescript
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+import { apiGet } from './utils.js'; // 复用平台 SDK
+
+cli({
+  site: 'bilibili',
+  name: 'subtitle',
+  strategy: Strategy.COOKIE,
+  args: [{ name: 'bvid', required: true }],
+  columns: ['index', 'from', 'to', 'content'],
+  func: async (page: IPage | null, kwargs: any) => {
+    if (!page) throw new Error('Requires browser');
+
+    // Step 1: 建立 Session
+    await page.goto(`https://www.bilibili.com/video/${kwargs.bvid}/`);
+
+    // Step 2: 从页面提取中间 ID (__INITIAL_STATE__)
+    const cid = await page.evaluate(`(async () => {
+      return window.__INITIAL_STATE__?.videoData?.cid;
+    })()`);
+    if (!cid) throw new Error('无法提取 CID');
+
+    // Step 3: 用中间 ID 调用下一级 API (自动 Wbi 签名)
+    const payload = await apiGet(page, '/x/player/wbi/v2', {
+      params: { bvid: kwargs.bvid, cid },
+      signed: true, // ← 自动生成 w_rid
+    });
+
+    // Step 4: 检测风控降级 (空值断言)
+    const subtitles = payload.data?.subtitle?.subtitles || [];
+    const url = subtitles[0]?.subtitle_url;
+    if (!url) throw new Error('subtitle_url 为空，疑似风控降级');
+
+    // Step 5: 拉取最终数据 (CDN JSON)
+    const items = await page.evaluate(`(async () => {
+      const res = await fetch(${JSON.stringify('https:' + url)});
+      const json = await res.json();
+      return { data: json.body || json };
+    })()`);
+
+    return items.data.map((item, idx) => ({ ... }));
+  },
+});
+```
+
+### 关键要点
+
+| 步骤 | 注意事项 |
+|------|----------|
+| 提取中间 ID | 优先从 `__INITIAL_STATE__` 拿，避免额外 API 调用 |
+| Wbi 签名 | B 站 `/wbi/` 接口**强制校验** `w_rid`，纯 `fetch` 会被 403 |
+| 空值断言 | 即使 HTTP 200，核心字段可能为空串（风控降级） |
+| CDN URL | 常以 `//` 开头，记得补 `https:` |
+| `JSON.stringify` | 拼接 URL 到 evaluate 时必须用它转义，避免注入 |
+
+---
+
+## 常见陷阱
+
+| 陷阱 | 表现 | 解决方案 |
+|------|------|---------|
+| 缺少 `navigate` | evaluate 报 `Target page context` 错误 | 在 evaluate 前加 `navigate:` 步骤 |
+| 嵌套字段访问 | `${{ item.node?.title }}` 不工作 | 在 evaluate 中 flatten 数据，不在模板中用 optional chaining |
+| 缺少 `strategy: public` | 公开 API 也启动浏览器，7s → 1s | 公开 API 加上 `strategy: public` + `browser: false` |
+| evaluate 返回字符串 | map 步骤收到 `""` 而非数组 | pipeline 有 auto-parse，但建议在 evaluate 内 `.map()` 整形 |
+| 搜索参数被 URL 编码 | `${{ args.query }}` 被浏览器二次编码 | 在 evaluate 内用 `encodeURIComponent()` 手动编码 |
+| Cookie 过期 | 返回 401 / 空数据 | 在浏览器里重新登录目标站点 |
+| Extension tab 残留 | Chrome 多出 `chrome-extension://` tab | 已自动清理；若残留，手动关闭即可 |
+| TS evaluate 格式 | `() => {}` 报 `result is not a function` | TS 中 `page.evaluate()` 必须用 IIFE：`(async () => { ... })()` |
+| 页面异步加载 | evaluate 拿到空数据（store state 还没更新） | 在 evaluate 内用 polling 等待数据出现，或增加 `wait` 时间 |
+| YAML 内嵌大段 JS | 调试困难，字符串转义问题 | 超过 10 行 JS 的命令改用 TS adapter |
+| **风控被拦截(伪200)** | 获取到的 JSON 里核心数据是 `""` (空串) | 极易被误判。必须添加断言！无核心数据立刻要求升级鉴权 Tier 并重新配置 Cookie |
+| **API 没找见** | `explore` 工具打分出来的都拿不到深层数据 | 点击页面按钮诱发懒加载数据，再结合 `getInterceptedRequests` 获取 |
+
+---
+
+## 用 AI Agent 自动生成适配器
+
+最快的方式是让 AI Agent 完成全流程：
+
+```bash
+# 一键：探索 → 分析 → 合成 → 注册
+opencli generate https://www.example.com --goal "hot"
+
+# 或分步执行：
+opencli explore https://www.example.com --site mysite           # 发现 API
+opencli explore https://www.example.com --auto --click "字幕,CC"  # 模拟点击触发懒加载 API
+opencli synthesize mysite                                        # 生成候选 YAML
+opencli verify mysite/hot --smoke                                # 冒烟测试
+```
+
+生成的候选 YAML 保存在 `.opencli/explore/mysite/candidates/`，可直接复制到 `src/clis/mysite/` 并微调。

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)。

CONTRIBUTING.md

@@ -0,0 +1,208 @@
+# 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
+npm test
+npm run test:adapter
+
+# 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:
+  query:
+    positional: true
+    type: str
+    required: true
+    description: Search keyword
+  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', positional: true, 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
+```
+
+## Arg Design Convention
+
+Use **positional** for the primary, required argument of a command (the "what" — query, symbol, id, url, username). Use **named options** (`--flag`) for secondary/optional configuration (limit, format, sort, page, filters, language, date).
+
+**Rule of thumb**: Think about how the user will type the command. `opencli xueqiu stock SH600519` is more natural than `opencli xueqiu stock --symbol SH600519`.
+
+| Arg type | Positional? | Examples |
+|----------|-------------|----------|
+| Main target (query, symbol, id, url, username) | ✅ `positional: true` | `search '茅台'`, `stock SH600519`, `download BV1xxx` |
+| Configuration (limit, format, sort, page, type, filters) | ❌ Named `--flag` | `--limit 10`, `--format json`, `--sort hot`, `--location seattle` |
+
+Do **not** convert an argument to positional just because it appears first in the file. If the argument is optional, acts like a filter, or selects a mode/configuration, it should usually stay a named option.
+
+YAML example:
+```yaml
+args:
+  query:
+    positional: true     # ← primary arg, user types it directly
+    type: str
+    required: true
+  limit:
+    type: int            # ← config arg, user types --limit 10
+    default: 20
+```
+
+TS example:
+```typescript
+args: [
+  { name: 'query', positional: true, required: true, help: 'Search query' },
+  { name: 'limit', type: 'int', default: 10, help: 'Max results' },
+]
+```
+
+## Testing
+
+See [TESTING.md](./TESTING.md) for the full guide and exact test locations.
+
+```bash
+npm test                      # Core unit tests (non-adapter)
+npm run test:adapter         # Focused adapter tests: zhihu/twitter/reddit/bilibili
+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
+   npm test                   # Core unit tests
+   npm run test:adapter       # Focused adapter tests (if you touched adapter logic)
+   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).

LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 jackwener
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,67 +1,355 @@
 # OpenCLI
 
-> **Make any website your CLI.** 操控 Chrome 无风控风险，复用登录，CLI 化全部网站。
+> **Make any website, Electron App, or Local Tool your CLI.**  
+> Zero risk · Reuse Chrome login · AI-powered discovery · Universal CLI Hub
 
-OpenCLI 是一个 AI Native 的 CLI 工具，通过 Chrome 浏览器 + Playwright MCP Bridge 扩展，将任何网站变成命令行工具。
+[中文文档](./README.zh-CN.md)
 
-## ✨ 特性
+[![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)
 
-- 🌐 **CLI 化全部网站** — 支持 Bilibili、知乎、GitHub、Twitter、V2EX、Hacker News 等
-- 🔐 **零风控风险** — 复用 Chrome 已登录状态，无需存储密码
-- 🤖 **AI Native** — AI agent 可直接探索网站并自动生成新命令
-- 📝 **声明式 YAML** — 用 YAML 定义 pipeline，无需写代码
-- 🔌 **TypeScript 扩展** — 复杂场景用 TS 编写适配器
+A CLI tool that turns **any website**, **Electron app**, or **local CLI tool** into a command-line interface — Bilibili, Zhihu, 小红书, Twitter/X, Reddit, YouTube, Antigravity, `gh`, `docker`, and [many more](#built-in-commands) — powered by browser session reuse and AI-native discovery.
 
-## 🚀 快速开始
+**Built for AI Agents**: Simply configure an instruction in your global `AGENT.md` or `.cursorrules` guiding the AI to execute `opencli list` via Bash to discover available tools. Register your favorite local CLIs (`opencli register mycli`), and the AI will automatically learn how to invoke all your tools perfectly!
+
+**CLI All Electron Apps! The Most Powerful Update Has Arrived!**
+Turn ANY Electron application into a CLI tool! Recombine, script, and extend applications like Antigravity Ultra seamlessly. Now AI can control itself natively. Unlimited possibilities await!
+
+---
+
+## Highlights
+
+- **CLI All Electron** — CLI-ify apps like Antigravity Ultra! Now AI can control itself natively using cc/openclaw!
+- **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.
+- **External CLI Hub** — Discover, auto-install, and passthrough commands to any external CLI (gh, obsidian, docker, etc). Zero setup.
+- **Self-healing setup** — `opencli doctor` diagnoses and auto-starts the daemon, extension, and live browser connectivity.
+- **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.
+
+## Why opencli?
+
+There are many great browser automation tools. Here's when opencli is the right choice:
+
+| Your need | Best tool | Why |
+|-----------|-----------|-----|
+| Scheduled data extraction from specific sites | **opencli** | Pre-built adapters, deterministic JSON, zero LLM cost |
+| AI agent needs reliable site operations | **opencli** | Hundreds of commands, structured output, fast deterministic response |
+| Explore an unknown website ad-hoc | Browser-Use, Stagehand | LLM-driven general browsing for one-off tasks |
+| Large-scale web crawling | Crawl4AI, Scrapy | Purpose-built for throughput and scale |
+| Control desktop Electron apps from terminal | **opencli** | CDP + AppleScript — the only CLI tool that does this |
+
+**What makes opencli different:**
+
+- **Zero LLM cost** — No tokens consumed at runtime. Run 10,000 times and pay nothing.
+- **Deterministic** — Same command, same output schema, every time. Pipeable, scriptable, CI-friendly.
+- **Broad coverage** — 50+ sites across global and Chinese platforms (Bilibili, Zhihu, Xiaohongshu, Reddit, HackerNews, and more), plus desktop Electron apps via CDP.
+
+> For a detailed comparison with Browser-Use, Crawl4AI, Firecrawl, and others, see the [Comparison Guide](./docs/comparison.md).
+
+## Prerequisites
+
+- **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.
+
+OpenCLI connects to your browser through a lightweight **Browser Bridge** Chrome Extension + micro-daemon (zero config, auto-start).
+
+### Browser Bridge Extension Setup
+
+You can install the extension via either method:
+
+**Method 1: Download Pre-built Release (Recommended)**
+1. Go to the GitHub [Releases page](https://github.com/jackwener/opencli/releases) and download the latest `opencli-extension.zip`.
+2. Unzip the file and open `chrome://extensions`, enable **Developer mode** (top-right toggle).
+3. Click **Load unpacked** and select the unzipped folder.
+
+**Method 2: Load Source (For Developers)**
+1. Open `chrome://extensions` and enable **Developer mode**.
+2. Click **Load unpacked** and select the `extension/` directory from this repository.
+
+That's it! The daemon auto-starts when you run any browser command. No tokens, no manual configuration.
+
+> **Tip**: Use `opencli doctor` for ongoing diagnosis:
+> ```bash
+> opencli doctor            # Check extension + daemon connectivity
+> ```
+
+## Quick Start
+
+### Install via npm (recommended)
 
 ```bash
-# 安装依赖
-cd ~/code/ai-native-cli && npm install
-
-# 列出所有命令
-npx tsx src/main.ts list
-
-# 公共 API（无需浏览器）
-npx tsx src/main.ts hackernews top --limit 10
-npx tsx src/main.ts github search --keyword "typescript"
-
-# 浏览器命令（需要 Chrome + Playwright MCP Bridge 扩展）
-npx tsx src/main.ts bilibili hot --limit 10
-npx tsx src/main.ts zhihu hot --limit 10
-npx tsx src/main.ts twitter trending --limit 10
+npm install -g @jackwener/opencli
 ```
 
-## 📋 前置要求
-
-浏览器命令需要：
-1. Chrome 浏览器正在运行
-2. 安装 [Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm) 扩展
-3. 首次使用时点击扩展图标批准连接
-
-## 📦 内置命令
-
-| 站点 | 命令 | 说明 | 模式 |
-|------|------|------|------|
-| bilibili | hot, search, me, favorite, history, feed, user-videos | 热门 / 搜索 / 个人 / 收藏 / 历史 / 动态 / 投稿 | 🔐 浏览器 |
-| zhihu | hot, search | 热榜 / 搜索 | 🔐 浏览器 |
-| github | trending, search | Trending / 搜索 | 🔐 / 🌐 公共 |
-| twitter | trending | 热门话题 | 🔐 浏览器 |
-| v2ex | hot, latest | 热门 / 最新 | 🔐 浏览器 |
-| hackernews | top | 热门故事 | 🌐 公共 API |
-
-## 🎨 输出格式
+Then use directly:
 
 ```bash
-opencli bilibili hot -f table   # 默认表格
-opencli bilibili hot -f json    # JSON（适合管道和 AI agent）
+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 (for developers)
+
+```bash
+git clone git@github.com:jackwener/opencli.git
+cd opencli 
+npm install
+npm run build
+npm link      # Link binary globally
+opencli list  # Now you can use it anywhere!
+```
+
+### Update
+
+```bash
+npm install -g @jackwener/opencli@latest
+```
+
+## Built-in Commands
+
+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` `accept` `reply-dm` `block` `unblock` `hide-reply` | 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` `dump` `extract-diff` `model` `ask` `screenshot` `history` `export` | Desktop |
+| **chatwise** | `status` `new` `send` `read` `ask` `model` `history` `export` `screenshot` | Desktop |
+| **doubao** | `status` `new` `send` `read` `ask` | Browser |
+| **doubao-app** | `status` `new` `send` `read` `ask` `screenshot` `dump` | 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` `node` `user` `member` `replies` `nodes` `daily` `me` `notifications` | Public / Browser |
+| **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` `earnings-date` | Browser |
+| **antigravity** | `status` `send` `read` `new` `dump` `extract-code` `model` `watch` | Desktop |
+| **chatgpt** | `status` `new` `send` `read` `ask` | Desktop |
+| **xiaohongshu** | `search` `notifications` `feed` `user` `download` `publish` `creator-notes` `creator-note-detail` `creator-notes-summary` `creator-profile` `creator-stats` | Browser |
+| **apple-podcasts** | `search` `episodes` `top` | Public |
+| **xiaoyuzhou** | `podcast` `podcast-episodes` `episode` | Public |
+| **zhihu** | `hot` `search` `question` `download` | Browser |
+| **weixin** | `download` | Browser |
+| **youtube** | `search` `video` `transcript` | Browser |
+| **boss** | `search` `detail` `recommend` `joblist` `greet` `batchgreet` `send` `chatlist` `chatmsg` `invite` `mark` `exchange` `resume` `stats` | Browser |
+| **coupang** | `search` `add-to-cart` | Browser |
+| **bbc** | `news` | Public |
+| **bloomberg** | `main` `markets` `economics` `industries` `tech` `politics` `businessweek` `opinions` `feeds` `news` | Public / Browser |
+| **ctrip** | `search` | Browser |
+| **devto** | `top` `tag` `user` | Public |
+| **dictionary** | `search` `synonyms` `examples` | Public |
+| **arxiv** | `search` `paper` | Public |
+| **wikipedia** | `search` `summary` `random` `trending` | Public |
+| **hackernews** | `top` `new` `best` `ask` `show` `jobs` `search` `user` | Public |
+| **linkedin** | `search` | Browser |
+| **reuters** | `search` | Browser |
+| **smzdm** | `search` | Browser |
+| **weibo** | `hot` `search` | Browser |
+| **yahoo-finance** | `quote` | Browser |
+| **sinafinance** | `news` | 🌐 Public |
+| **barchart** | `quote` `options` `greeks` `flow` | Browser |
+| **chaoxing** | `assignments` `exams` | Browser |
+| **grok** | `ask` | Browser |
+| **hf** | `top` | Public |
+| **jike** | `feed` `search` `create` `like` `comment` `repost` `notifications` `post` `topic` `user` | Browser |
+| **jimeng** | `generate` `history` | Browser |
+| **yollomi** | `generate` `video` `edit` `upload` `models` `remove-bg` `upscale` `face-swap` `restore` `try-on` `background` `object-remover` | Browser |
+| **linux-do** | `hot` `latest` `search` `categories` `category` `topic` | Public |
+| **stackoverflow** | `hot` `search` `bounties` `unanswered` | Public |
+| **steam** | `top-sellers` | Public |
+| **weread** | `shelf` `search` `book` `highlights` `notes` `notebooks` `ranking` | Browser |
+| **douban** | `search` `top250` `subject` `marks` `reviews` `movie-hot` `book-hot` | Browser |
+| **facebook** | `feed` `profile` `search` `friends` `groups` `events` `notifications` `memories` `add-friend` `join-group` | Browser |
+| **google** | `news` `search` `suggest` `trends` | Public |
+| **instagram** | `explore` `profile` `search` `user` `followers` `following` `follow` `unfollow` `like` `unlike` `comment` `save` `unsave` `saved` | Browser |
+| **lobsters** | `hot` `newest` `active` `tag` | Public |
+| **medium** | `feed` `search` `user` | Browser |
+| **sinablog** | `hot` `search` `article` `user` | Browser |
+| **substack** | `feed` `search` `publication` | Browser |
+| **tiktok** | `explore` `search` `profile` `user` `following` `follow` `unfollow` `like` `unlike` `comment` `save` `unsave` `live` `notifications` `friends` | Browser |
+
+
+### External CLI Hub
+
+OpenCLI acts as a universal hub for your existing command-line tools. It provides unified discovery, automatic installation, and pure passthrough execution.
+
+| External CLI | Description | Commands Example |
+|--------------|-------------|------------------|
+| **gh** | GitHub CLI | `opencli gh pr list --limit 5` |
+| **obsidian** | Obsidian vault management | `opencli obsidian search query="AI"` |
+| **docker** | Docker command-line interface | `opencli docker ps` |
+| **readwise** | Readwise & Reader CLI | `opencli readwise login` |
+| **gws** | Google Workspace CLI — Docs, Sheets, Drive, Gmail, Calendar | `opencli gws docs list` |
+
+**Zero Configuration**: OpenCLI purely passes your inputs to the underlying binary via standard I/O streams. The external CLI works exactly as it naturally would, maintaining its standard output formats.
+
+**Auto-Installation**: If you run `opencli gh ...` and `gh` is not installed on your system, OpenCLI will automatically try to install it using your system's package manager (e.g., `brew install gh`) before seamlessly re-running the command.
+
+**Register Your Own**:
+Add any local CLI to your OpenCLI registry so AI agents can automatically discover it via the `opencli list` command.
+```bash
+opencli register mycli
+```
+
+### Desktop App Adapters
+
+Each desktop adapter has its own detailed documentation with commands reference, setup guide, and examples:
+
+| App | Description | Doc |
+|-----|-------------|-----|
+| **Cursor** | Control Cursor IDE — Composer, chat, code extraction | [Doc](./docs/adapters/desktop/cursor.md) |
+| **Codex** | Drive OpenAI Codex CLI agent headlessly | [Doc](./docs/adapters/desktop/codex.md) |
+| **Antigravity** | Control Antigravity Ultra from terminal | [Doc](./docs/adapters/desktop/antigravity.md) |
+| **ChatGPT** | Automate ChatGPT macOS desktop app | [Doc](./docs/adapters/desktop/chatgpt.md) |
+| **ChatWise** | Multi-LLM client (GPT-4, Claude, Gemini) | [Doc](./docs/adapters/desktop/chatwise.md) |
+| **Notion** | Search, read, write Notion pages | [Doc](./docs/adapters/desktop/notion.md) |
+| **Discord** | Discord Desktop — messages, channels, servers | [Doc](./docs/adapters/desktop/discord.md) |
+| **Doubao** | Control Doubao AI desktop app via CDP | [Doc](./docs/adapters/desktop/doubao-app.md) |
+
+## 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 |
+| **weixin** | Articles (Markdown) | Exports WeChat Official Account articles |
+
+### 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 abc123 --output ./xhs
+
+# Download Bilibili video (requires yt-dlp)
+opencli bilibili download BV1xxx --output ./bilibili
+opencli bilibili download BV1xxx --quality 1080p  # Specify quality
+
+# Download Twitter media from user
+opencli twitter download 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 "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
+
+# Export with local images
+opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --download-images
+
+# Export WeChat article to Markdown
+opencli weixin download --url "https://mp.weixin.qq.com/s/xxx" --output ./weixin
+```
+
+
+
+## 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 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 debug steps
 ```
 
-## 🔧 创建新命令
+## Plugins
 
-参考 [SKILL.md](./SKILL.md) 了解 YAML 和 TypeScript 两种方式创建新的 CLI 适配器。
+Extend OpenCLI with community-contributed adapters. Plugins use the same YAML/TS format as built-in commands and are automatically discovered at startup.
 
-## 📄 License
+```bash
+opencli plugin install github:user/opencli-plugin-my-tool  # Install
+opencli plugin list                                         # List installed
+opencli plugin update my-tool                               # Update to latest
+opencli plugin uninstall my-tool                            # Remove
+```
 
-MIT
+| Plugin | Type | Description |
+|--------|------|-------------|
+| [opencli-plugin-github-trending](https://github.com/ByteYue/opencli-plugin-github-trending) | YAML | GitHub Trending repositories |
+| [opencli-plugin-hot-digest](https://github.com/ByteYue/opencli-plugin-hot-digest) | TS | Multi-platform trending aggregator |
+| [opencli-plugin-juejin](https://github.com/Astro-Han/opencli-plugin-juejin) | YAML | 稀土掘金 (Juejin) hot articles |
+
+See [Plugins Guide](./docs/guide/plugins.md) for creating your own plugin.
+
+## 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
+opencli explore https://example.com --site mysite
+
+# 2. Synthesize — generate YAML adapters from explore artifacts
+opencli synthesize mysite
+
+# 3. Generate — one-shot: explore → synthesize → register
+opencli generate https://example.com --goal "hot"
+
+# 4. Strategy Cascade — auto-probe: PUBLIC → COOKIE → HEADER
+opencli cascade https://api.example.com/data
+```
+
+Explore outputs to `.opencli/explore/<site>/` (manifest.json, endpoints.json, capabilities.json, auth.json).
+
+## Testing
+
+See **[TESTING.md](./TESTING.md)** for how to run and write tests.
+
+## Troubleshooting
+
+- **"Extension not connected"**
+  - Ensure the opencli Browser Bridge extension is installed and **enabled** in `chrome://extensions`.
+- **"attach failed: Cannot access a chrome-extension:// URL"**
+  - Another Chrome extension (e.g. youmind, New Tab Override, or AI assistant extensions) may be interfering. Try **disabling other extensions** temporarily, then retry.
+- **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.
+- **Node API errors**
+  - Make sure you are using Node.js >= 20. Some dependencies require modern Node APIs.
+- **Daemon issues**
+  - Check daemon status: `curl localhost:19825/status`
+  - View extension logs: `curl localhost:19825/logs`
+
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=jackwener/opencli&type=Date)](https://star-history.com/#jackwener/opencli&Date)
+
+
+
+## License
+
+[Apache-2.0](./LICENSE)

README.zh-CN.md

@@ -0,0 +1,353 @@
+# OpenCLI
+
+> **把任何网站、本地工具、Electron 应用变成能够让 AI 调用的命令行！**  
+> 零风控 · 复用 Chrome 登录 · AI 自动发现接口 · 全能 CLI 枢纽
+
+[English](./README.md)
+
+[![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 将任何网站、本地 CLI 或 Electron 应用（如 Antigravity）变成命令行工具 — B站、知乎、小红书、Twitter/X、Reddit、YouTube，以及 `gh`、`docker` 等[多种站点与工具](#内置命令) — 复用浏览器登录态，AI 驱动探索。
+
+**专为 AI Agent 打造**：只需在全局 `.cursorrules` 或 `AGENT.md` 中配置简单指令，引导 AI 通过 Bash 执行 `opencli list` 来检索可用的 CLI 工具及其用法。随后，将你常用的 CLI 列表整合注册进去（`opencli register mycli`），AI 便能瞬间学会自动调用相应的本地工具！
+
+**opencli 支持 CLI 化所有 electron 应用！最强大更新来袭！**
+CLI all electron！现在支持把所有 electron 应用 CLI 化，从而组合出各种神奇的能力。
+如果你在使用诸如 Antigravity Ultra 等工具时觉得不够灵活或难以扩展，现在通过 OpenCLI 把他 CLI 化，轻松打破界限。
+现在，**AI 可以自己控制自己**！结合 cc/openclaw 就可以远程控制任何 electron 应用！无限玩法！！
+
+---
+
+## 亮点
+
+- **CLI All Electron** — 支持把所有 electron 应用（如 Antigravity Ultra）CLI 化，让 AI 控制自己！
+- **多站点覆盖** — 覆盖 B站、知乎、小红书、Twitter、Reddit，以及多种桌面应用
+- **零风控** — 复用 Chrome 登录态，无需存储任何凭证
+- **外部 CLI 枢纽** — 统一发现、自动安装、透传执行 `gh`、`docker` 等本地 CLI
+- **自修复配置** — `opencli doctor` 自动启动 daemon，诊断扩展和浏览器连接状态
+- **AI 原生** — `explore` 自动发现 API，`synthesize` 生成适配器，`cascade` 探测认证策略
+- **动态加载引擎** — 声明式的 `.yaml` 或者底层定制的 `.ts` 适配器，放入 `clis/` 文件夹即可自动注册生效
+
+## 为什么选 opencli？
+
+浏览器自动化工具很多，opencli 适合什么场景？
+
+| 你的需求 | 最佳工具 | 原因 |
+|----------|----------|------|
+| 定时从特定站点提取结构化数据 | **opencli** | 预定义适配器，确定性 JSON 输出，零 LLM 成本 |
+| AI Agent 需要可靠的站点操作 | **opencli** | 数百条命令，结构化输出，快速确定性响应 |
+| 临时探索未知网站 | Browser-Use、Stagehand | LLM 驱动的通用浏览，适合一次性任务 |
+| 大规模网页爬取 | Crawl4AI、Scrapy | 专为吞吐量和规模设计 |
+| 从终端控制桌面 Electron 应用 | **opencli** | CDP + AppleScript，目前唯一能做到这一点的 CLI 工具 |
+
+**opencli 的核心差异：**
+
+- **零 LLM 成本** — 运行时不消耗任何 token，跑一万次不花一分钱
+- **确定性** — 同一命令永远返回同一结构，可管道化、可脚本化、CI 友好
+- **覆盖广泛** — 50+ 站点，横跨全球与中国平台（B站、知乎、小红书、Reddit、HackerNews 等），并支持通过 CDP 控制桌面 Electron 应用
+
+> 与 Browser-Use、Crawl4AI、Firecrawl 等工具的详细对比，请查看 [Comparison Guide](./docs/comparison.md)。
+
+## 前置要求
+
+- **Node.js**: >= 20.0.0
+- **Chrome** 浏览器正在运行，且**已登录目标网站**（如 bilibili.com、zhihu.com、xiaohongshu.com）
+
+> **⚠️ 重要**：大多数命令复用你的 Chrome 登录状态。运行命令前，你必须已在 Chrome 中打开目标网站并完成登录。如果获取到空数据或报错，请先检查你的浏览器登录状态。
+
+OpenCLI 通过轻量化的 **Browser Bridge** Chrome 扩展 + 微型 daemon 与浏览器通信（零配置，自动启动）。
+
+### Browser Bridge 扩展配置
+
+你可以选择以下任一方式安装扩展：
+
+**方式一：下载构建好的安装包（推荐）**
+1. 到 GitHub [Releases 页面](https://github.com/jackwener/opencli/releases) 下载最新的 `opencli-extension.zip`。
+2. 解压后打开 Chrome 的 `chrome://extensions`，启用右上角的 **开发者模式**。
+3. 点击 **加载已解压的扩展程序**，选择解压后的文件夹。
+
+**方式二：加载源码（针对开发者）**
+1. 同样在 `chrome://extensions` 开启 **开发者模式**。
+2. 点击 **加载已解压的扩展程序**，选择本仓库代码树中的 `extension/` 文件夹。
+
+完成！运行任何 opencli 浏览器命令时，后台微型 daemon 会自动启动与浏览器通信。无需配 API Token，零代码配置。
+
+> **Tip**：后续诊断用 `opencli doctor`：
+> ```bash
+> opencli doctor            # 检查扩展和 daemon 连通性
+> ```
+
+## 快速开始
+
+### npm 全局安装（推荐）
+
+```bash
+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
+npm run build
+npm link      # 链接到全局环境
+opencli list  # 可以在任何地方使用了！
+```
+
+### 更新
+
+```bash
+npm install -g @jackwener/opencli@latest
+```
+
+## 内置命令
+
+运行 `opencli list` 查看完整注册表。
+
+| 站点 | 命令 | 模式 |
+|------|------|------|
+| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` `thread` `following` `followers` `notifications` `post` `reply` `delete` `like` `article` `follow` `unfollow` `bookmark` `unbookmark` `download` `accept` `reply-dm` `block` `unblock` `hide-reply` | 浏览器 |
+| **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` `dump` `extract-diff` `model` `ask` `screenshot` `history` `export` | 桌面端 |
+| **chatwise** | `status` `new` `send` `read` `ask` `model` `history` `export` `screenshot` | 桌面端 |
+| **doubao** | `status` `new` `send` `read` `ask` | 浏览器 |
+| **doubao-app** | `status` `new` `send` `read` `ask` `screenshot` `dump` | 桌面端 |
+| **notion** | `status` `search` `read` `new` `write` `sidebar` `favorites` `export` | 桌面端 |
+| **discord-app** | `status` `send` `read` `channels` `servers` `search` `members` | 桌面端 |
+| **v2ex** | `hot` `latest` `topic` `node` `user` `member` `replies` `nodes` `daily` `me` `notifications` | 公开 / 浏览器 |
+| **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` `earnings-date` | 浏览器 |
+| **antigravity** | `status` `send` `read` `new` `dump` `extract-code` `model` `watch` | 桌面端 |
+| **chatgpt** | `status` `new` `send` `read` `ask` | 桌面端 |
+| **xiaohongshu** | `search` `notifications` `feed` `user` `download` `publish` `creator-notes` `creator-note-detail` `creator-notes-summary` `creator-profile` `creator-stats` | 浏览器 |
+| **apple-podcasts** | `search` `episodes` `top` | 公开 |
+| **xiaoyuzhou** | `podcast` `podcast-episodes` `episode` | 公开 |
+| **zhihu** | `hot` `search` `question` `download` | 浏览器 |
+| **weixin** | `download` | 浏览器 |
+| **youtube** | `search` `video` `transcript` | 浏览器 |
+| **boss** | `search` `detail` `recommend` `joblist` `greet` `batchgreet` `send` `chatlist` `chatmsg` `invite` `mark` `exchange` `resume` `stats` | 浏览器 |
+| **coupang** | `search` `add-to-cart` | 浏览器 |
+| **bbc** | `news` | 公共 API |
+| **bloomberg** | `main` `markets` `economics` `industries` `tech` `politics` `businessweek` `opinions` `feeds` `news` | 公共 API / 浏览器 |
+| **ctrip** | `search` | 浏览器 |
+| **devto** | `top` `tag` `user` | 公开 |
+| **dictionary** | `search` `synonyms` `examples` | 公开 |
+| **arxiv** | `search` `paper` | 公开 |
+| **wikipedia** | `search` `summary` `random` `trending` | 公开 |
+| **hackernews** | `top` `new` `best` `ask` `show` `jobs` `search` `user` | 公共 API |
+| **linkedin** | `search` | 浏览器 |
+| **reuters** | `search` | 浏览器 |
+| **smzdm** | `search` | 浏览器 |
+| **weibo** | `hot` `search` | 浏览器 |
+| **yahoo-finance** | `quote` | 浏览器 |
+| **sinafinance** | `news` | 🌐 公开 |
+| **barchart** | `quote` `options` `greeks` `flow` | 浏览器 |
+| **chaoxing** | `assignments` `exams` | 浏览器 |
+| **grok** | `ask` | 浏览器 |
+| **hf** | `top` | 公开 |
+| **jike** | `feed` `search` `create` `like` `comment` `repost` `notifications` `post` `topic` `user` | 浏览器 |
+| **jimeng** | `generate` `history` | 浏览器 |
+| **yollomi** | `generate` `video` `edit` `upload` `models` `remove-bg` `upscale` `face-swap` `restore` `try-on` `background` `object-remover` | 浏览器 |
+| **linux-do** | `hot` `latest` `search` `categories` `category` `topic` | 公开 |
+| **stackoverflow** | `hot` `search` `bounties` `unanswered` | 公开 |
+| **steam** | `top-sellers` | 公开 |
+| **weread** | `shelf` `search` `book` `highlights` `notes` `notebooks` `ranking` | 浏览器 |
+| **douban** | `search` `top250` `subject` `marks` `reviews` `movie-hot` `book-hot` | 浏览器 |
+| **facebook** | `feed` `profile` `search` `friends` `groups` `events` `notifications` `memories` `add-friend` `join-group` | 浏览器 |
+| **google** | `news` `search` `suggest` `trends` | 公开 |
+| **instagram** | `explore` `profile` `search` `user` `followers` `following` `follow` `unfollow` `like` `unlike` `comment` `save` `unsave` `saved` | 浏览器 |
+| **lobsters** | `hot` `newest` `active` `tag` | 公开 |
+| **medium** | `feed` `search` `user` | 浏览器 |
+| **sinablog** | `hot` `search` `article` `user` | 浏览器 |
+| **substack** | `feed` `search` `publication` | 浏览器 |
+| **tiktok** | `explore` `search` `profile` `user` `following` `follow` `unfollow` `like` `unlike` `comment` `save` `unsave` `live` `notifications` `friends` | 浏览器 |
+
+
+### 外部 CLI 枢纽
+
+OpenCLI 也可以作为你现有命令行工具的统一入口，负责发现、自动安装和纯透传执行。
+
+| 外部 CLI | 描述 | 示例 |
+|----------|------|------|
+| **gh** | GitHub CLI | `opencli gh pr list --limit 5` |
+| **obsidian** | Obsidian 仓库管理 | `opencli obsidian search query="AI"` |
+| **docker** | Docker 命令行工具 | `opencli docker ps` |
+| **readwise** | Readwise / Reader CLI | `opencli readwise login` |
+| **gws** | Google Workspace CLI — Docs, Sheets, Drive, Gmail, Calendar | `opencli gws docs list` |
+
+**零配置透传**：OpenCLI 会把你的输入原样转发给底层二进制，保留原生 stdout / stderr 行为。
+
+**自动安装**：如果你运行 `opencli gh ...` 时系统中还没有 `gh`，OpenCLI 会优先尝试通过系统包管理器安装，然后自动重试命令。
+
+**注册自定义本地 CLI**：
+
+```bash
+opencli register mycli
+```
+
+### 桌面应用适配器
+
+每个桌面适配器都有自己详细的文档说明，包括命令参考、启动配置与使用示例：
+
+| 应用 | 描述 | 文档 |
+|-----|-------------|-----|
+| **Cursor** | 控制 Cursor IDE — Composer、对话、代码提取等 | [Doc](./docs/adapters/desktop/cursor.md) |
+| **Codex** | 在后台（无头）驱动 OpenAI Codex CLI Agent | [Doc](./docs/adapters/desktop/codex.md) |
+| **Antigravity** | 在终端直接控制 Antigravity Ultra | [Doc](./docs/adapters/desktop/antigravity.md) |
+| **ChatGPT** | 自动化操作 ChatGPT macOS 桌面客户端 | [Doc](./docs/adapters/desktop/chatgpt.md) |
+| **ChatWise** | 多 LLM 客户端（GPT-4、Claude、Gemini） | [Doc](./docs/adapters/desktop/chatwise.md) |
+| **Notion** | 搜索、读取、写入 Notion 页面 | [Doc](./docs/adapters/desktop/notion.md) |
+| **Discord** | Discord 桌面版 — 消息、频道、服务器 | [Doc](./docs/adapters/desktop/discord.md) |
+| **Doubao** | 通过 CDP 控制豆包桌面应用 | [Doc](./docs/adapters/desktop/doubao-app.md) |
+
+## 下载支持
+
+OpenCLI 支持从各平台下载图片、视频和文章。
+
+### 支持的平台
+
+| 平台 | 内容类型 | 说明 |
+|------|----------|------|
+| **小红书** | 图片、视频 | 下载笔记中的所有媒体文件 |
+| **B站** | 视频 | 需要安装 `yt-dlp` |
+| **Twitter/X** | 图片、视频 | 从用户媒体页或单条推文下载 |
+| **知乎** | 文章（Markdown） | 导出文章，可选下载图片到本地 |
+| **微信公众号** | 文章（Markdown） | 导出微信公众号文章为 Markdown |
+
+### 前置依赖
+
+下载流媒体平台的视频需要安装 `yt-dlp`：
+
+```bash
+# 安装 yt-dlp
+pip install yt-dlp
+# 或者
+brew install yt-dlp
+```
+
+### 使用示例
+
+```bash
+# 下载小红书笔记中的图片/视频
+opencli xiaohongshu download abc123 --output ./xhs
+
+# 下载B站视频（需要 yt-dlp）
+opencli bilibili download BV1xxx --output ./bilibili
+opencli bilibili download BV1xxx --quality 1080p  # 指定画质
+
+# 下载 Twitter 用户的媒体
+opencli twitter download elonmusk --limit 20 --output ./twitter
+
+# 下载单条推文的媒体
+opencli twitter download --tweet-url "https://x.com/user/status/123" --output ./twitter
+
+# 导出知乎文章为 Markdown
+opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
+
+# 导出并下载图片
+opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --download-images
+
+# 导出微信公众号文章为 Markdown
+opencli weixin download --url "https://mp.weixin.qq.com/s/xxx" --output ./weixin
+```
+
+
+
+## 输出格式
+
+所有内置命令都支持 `--format` / `-f`，可选值为 `table`、`json`、`yaml`、`md`、`csv`。
+`list` 命令也支持同样的格式参数，同时继续兼容 `--json`。
+
+```bash
+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         # 详细模式：展示管线执行步骤调试信息
+```
+
+## 插件
+
+通过社区贡献的插件扩展 OpenCLI。插件使用与内置命令相同的 YAML/TS 格式，启动时自动发现。
+
+```bash
+opencli plugin install github:user/opencli-plugin-my-tool  # 安装
+opencli plugin list                                         # 查看已安装
+opencli plugin update my-tool                               # 更新到最新
+opencli plugin uninstall my-tool                            # 卸载
+```
+
+| 插件 | 类型 | 描述 |
+|------|------|------|
+| [opencli-plugin-github-trending](https://github.com/ByteYue/opencli-plugin-github-trending) | YAML | GitHub Trending 仓库 |
+| [opencli-plugin-hot-digest](https://github.com/ByteYue/opencli-plugin-hot-digest) | TS | 多平台热榜聚合 |
+| [opencli-plugin-juejin](https://github.com/Astro-Han/opencli-plugin-juejin) | YAML | 稀土掘金热门文章 |
+
+详见 [插件指南](./docs/zh/guide/plugins.md) 了解如何创建自己的插件。
+
+## 致 AI Agent（开发者指南）
+
+如果你是一个被要求查阅代码并编写新 `opencli` 适配器的 AI，请遵守以下工作流。
+
+> **快速模式**：只想为某个页面快速生成一个命令？看 [CLI-ONESHOT.md](./CLI-ONESHOT.md) — 给一个 URL + 一句话描述，4 步搞定。
+
+> **完整模式**：在编写任何新代码前，先阅读 [CLI-EXPLORER.md](./CLI-EXPLORER.md)。它包含完整的适配器探索开发指南、API 探测流程、5级认证策略以及常见陷阱。
+
+```bash
+# 1. Deep Explore — 网络拦截 → 响应分析 → 能力推理 → 框架检测
+opencli explore https://example.com --site mysite
+
+# 2. Synthesize — 从探索成果物生成 evaluate-based YAML 适配器
+opencli synthesize mysite
+
+# 3. Generate — 一键完成：探索 → 合成 → 注册
+opencli generate https://example.com --goal "hot"
+
+# 4. Strategy Cascade — 自动降级探测：PUBLIC → COOKIE → HEADER
+opencli cascade https://api.example.com/data
+```
+
+探索结果输出到 `.opencli/explore/<site>/`。
+
+## 常见问题排查
+
+- **"Extension not connected" 报错**
+  - 确保你当前的 Chrome 已安装且**开启了** opencli Browser Bridge 扩展（在 `chrome://extensions` 中检查）。
+- **"attach failed: Cannot access a chrome-extension:// URL" 报错**
+  - 其他 Chrome 扩展（如 youmind、New Tab Override 或 AI 助手类扩展）可能产生冲突。请尝试**暂时禁用其他扩展**后重试。
+- **返回空数据，或者报错 "Unauthorized"**
+  - Chrome 里的登录态可能已经过期。请打开当前 Chrome 页面，在新标签页重新手工登录或刷新该页面。
+- **Node API 错误 (如 parseArgs, fs 等)**
+  - 确保 Node.js 版本 `>= 20`。
+- **Daemon 问题**
+  - 检查 daemon 状态：`curl localhost:19825/status`
+  - 查看扩展日志：`curl localhost:19825/logs`
+
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=jackwener/opencli&type=Date)](https://star-history.com/#jackwener/opencli&Date)
+
+
+
+## License
+
+[Apache-2.0](./LICENSE)

SKILL.md

@@ -1,119 +1,624 @@
 ---
 name: opencli
-description: "OpenCLI — Make any website your CLI. Zero setup, AI-powered. Turn any website into CLI commands via Chrome browser."
-version: 0.1.0
+description: "OpenCLI — Make any website or Electron App your CLI. Zero risk, AI-powered, reuse Chrome login."
+version: 1.3.1
 author: jackwener
-tags: [cli, browser, web, mcp, playwright, bilibili, zhihu, twitter, github, v2ex, hackernews, 哔哩哔哩, 知乎, AI, agent]
+tags: [cli, browser, web, chrome-extension, cdp, bilibili, zhihu, twitter, github, v2ex, hackernews, reddit, xiaohongshu, xueqiu, youtube, boss, coupang, yollomi, AI, agent]
 ---
 
 # OpenCLI
 
-> Make any website your CLI. 操控 Chrome 无风控风险，复用登录，CLI 化全部网站。
+> Make any website or Electron App your CLI. Reuse Chrome login, zero risk, AI-powered discovery.
 
-## 安装
+> [!CAUTION]
+> **AI Agent 必读：创建或修改任何适配器之前，你必须先阅读 [CLI-EXPLORER.md](./CLI-EXPLORER.md)！**
+> 该文档包含完整的 API 发现工作流（必须使用浏览器探索）、5 级认证策略决策树、平台 SDK 速查表、`tap` 步骤调试流程、分页 API 模板、级联请求模式、以及常见陷阱。
+> **本文件（SKILL.md）仅提供命令参考和简化模板，不足以正确开发适配器。**
+
+## Install & Run
 
 ```bash
-cd ~/code/ai-native-cli
-npm install
-```
+# npm global install (recommended)
+npm install -g @jackwener/opencli
+opencli <command>
 
-## 使用方式
-
-```bash
-# 通过 npx 运行（推荐）
+# Or from source
+cd ~/code/opencli && npm install
 npx tsx src/main.ts <command>
 
-# 或者构建后运行
-npm run build && node dist/main.js <command>
+# Update to latest
+npm update -g @jackwener/opencli
 ```
 
-## 前置要求
+## Prerequisites
 
-浏览器命令需要：
-1. Chrome 浏览器正在运行
-2. 安装 [Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm) 扩展
-3. 点击扩展图标批准连接
+Browser commands require:
+1. Chrome browser running **(logged into target sites)**
+2. **opencli Browser Bridge** Chrome extension installed (load `extension/` as unpacked in `chrome://extensions`)
+3. No further setup needed — the daemon auto-starts on first browser command
 
-公共 API 命令（hackernews、github search）无需浏览器。
+> **Note**: You must be logged into the target website in Chrome before running commands. Tabs opened during command execution are auto-closed afterwards.
 
-## 内置命令
+Public API commands (`hackernews`, `v2ex`) need no browser.
 
-### 数据查询
+## Commands Reference
+
+### Data Commands
 
 ```bash
-# Bilibili
+# Bilibili (browser)
 opencli bilibili hot --limit 10          # B站热门视频
-opencli bilibili search --keyword "rust"  # 搜索视频
+opencli bilibili search "rust"            # 搜索视频 (query positional)
 opencli bilibili me                       # 我的信息
 opencli bilibili favorite                 # 我的收藏
 opencli bilibili history --limit 20       # 观看历史
 opencli bilibili feed --limit 10          # 动态时间线
 opencli bilibili user-videos --uid 12345  # 用户投稿
+opencli bilibili subtitle --bvid BV1xxx   # 获取视频字幕 (支持 --lang zh-CN)
+opencli bilibili dynamic --limit 10       # 动态
+opencli bilibili ranking --limit 10       # 排行榜
+opencli bilibili following --limit 20     # 我的关注列表 (支持 --uid 查看他人)
 
-# 知乎
+# 知乎 (browser)
 opencli zhihu hot --limit 10             # 知乎热榜
-opencli zhihu search --keyword "AI"      # 搜索
+opencli zhihu search "AI"                # 搜索 (query positional)
+opencli zhihu question 34816524            # 问题详情和回答 (id positional)
 
-# GitHub
-opencli github trending --limit 10       # GitHub Trending
-opencli github search --keyword "cli"    # 搜索仓库（无需浏览器）
+# 小红书 (browser)
+opencli xiaohongshu search "美食"           # 搜索笔记 (query positional)
+opencli xiaohongshu notifications             # 通知（mentions/likes/connections）
+opencli xiaohongshu feed --limit 10           # 推荐 Feed
+opencli xiaohongshu user xxx               # 用户主页 (id positional)
+opencli xiaohongshu creator-notes --limit 10   # 创作者笔记列表
+opencli xiaohongshu creator-note-detail --note-id xxx  # 笔记详情
+opencli xiaohongshu creator-notes-summary      # 笔记数据概览
+opencli xiaohongshu creator-profile            # 创作者资料
+opencli xiaohongshu creator-stats              # 创作者数据统计
 
-# Twitter/X
+# 雪球 Xueqiu (browser)
+opencli xueqiu hot-stock --limit 10      # 雪球热门股票榜
+opencli xueqiu stock --symbol SH600519   # 查看股票实时行情
+opencli xueqiu watchlist                 # 获取自选股/持仓列表
+opencli xueqiu feed                      # 我的关注 timeline
+opencli xueqiu hot --limit 10            # 雪球热榜
+opencli xueqiu search "特斯拉"            # 搜索 (query positional)
+
+# GitHub (via gh External CLI)
+opencli gh repo list                     # 列出仓库 (passthrough to gh)
+opencli gh pr list --limit 5             # PR 列表
+opencli gh issue list                    # Issue 列表
+
+# Twitter/X (browser)
 opencli twitter trending --limit 10      # 热门话题
+opencli twitter bookmarks --limit 20     # 获取收藏的书签推文
+opencli twitter search "AI"              # 搜索推文 (query positional)
+opencli twitter profile elonmusk         # 用户资料
+opencli twitter timeline --limit 20      # 时间线
+opencli twitter thread 1234567890        # 推文 thread（原文 + 回复）
+opencli twitter article 1891511252174299446 # 推文长文内容
+opencli twitter follow elonmusk          # 关注用户
+opencli twitter unfollow elonmusk        # 取消关注
+opencli twitter bookmark https://x.com/... # 收藏推文
+opencli twitter unbookmark https://x.com/... # 取消收藏
 
-# V2EX
+# Reddit (browser)
+opencli reddit hot --limit 10            # 热门帖子
+opencli reddit hot --subreddit programming  # 指定子版块
+opencli reddit frontpage --limit 10      # 首页 /r/all
+opencli reddit popular --limit 10        # /r/popular 热门
+opencli reddit search "AI" --sort top --time week  # 搜索（支持排序+时间过滤）
+opencli reddit subreddit rust --sort top --time month  # 子版块浏览（支持时间过滤）
+opencli reddit read --post-id 1abc123    # 阅读帖子 + 评论
+opencli reddit user spez                 # 用户资料（karma、注册时间）
+opencli reddit user-posts spez           # 用户发帖历史
+opencli reddit user-comments spez        # 用户评论历史
+opencli reddit upvote --post-id xxx --direction up  # 投票（up/down/none）
+opencli reddit save --post-id xxx        # 收藏帖子
+opencli reddit comment --post-id xxx "Great!"  # 发表评论 (text positional)
+opencli reddit subscribe --subreddit python  # 订阅子版块
+opencli reddit saved --limit 10          # 我的收藏
+opencli reddit upvoted --limit 10        # 我的赞
+
+# V2EX (public + browser)
 opencli v2ex hot --limit 10              # 热门话题
 opencli v2ex latest --limit 10           # 最新话题
+opencli v2ex topic 1024                  # 主题详情 (id positional)
+opencli v2ex daily                       # 每日签到 (browser)
+opencli v2ex me                          # 我的信息 (browser)
+opencli v2ex notifications --limit 10    # 通知 (browser)
 
-# Hacker News
-opencli hackernews top --limit 10        # 热门故事（无需浏览器）
+# Hacker News (public)
+opencli hackernews top --limit 10        # Top stories
+
+# BBC (public)
+opencli bbc news --limit 10             # BBC News RSS headlines
+
+# 微博 (browser)
+opencli weibo hot --limit 10            # 微博热搜
+
+# BOSS直聘 (browser)
+opencli boss search "AI agent"          # 搜索职位 (query positional)
+opencli boss detail --security-id xxx    # 职位详情
+opencli boss recommend --limit 10        # 推荐职位
+opencli boss joblist --limit 10          # 职位列表
+opencli boss greet --security-id xxx     # 打招呼
+opencli boss batchgreet --job-id xxx     # 批量打招呼
+opencli boss send --uid xxx "消息内容"    # 发消息 (text positional)
+opencli boss chatlist --limit 10         # 聊天列表
+opencli boss chatmsg --security-id xxx   # 聊天记录
+opencli boss invite --security-id xxx    # 邀请沟通
+opencli boss mark --security-id xxx      # 标记管理
+opencli boss exchange --security-id xxx  # 交换联系方式
+opencli boss resume                    # 简历管理
+opencli boss stats                     # 数据统计
+
+# YouTube (browser)
+opencli youtube search "rust"            # 搜索视频 (query positional)
+opencli youtube video "https://www.youtube.com/watch?v=xxx"  # 视频元数据
+opencli youtube transcript "https://www.youtube.com/watch?v=xxx"  # 获取视频字幕/转录
+opencli youtube transcript "xxx" --lang zh-Hans --mode raw  # 指定语言 + 原始时间戳模式
+
+# Yahoo Finance (browser)
+opencli yahoo-finance quote --symbol AAPL  # 股票行情
+
+# Sina Finance
+opencli sinafinance news --limit 10 --type 1  # 7x24实时快讯 (0=全部 1=A股 2=宏观 3=公司 4=数据 5=市场 6=国际 7=观点 8=央行 9=其它)
+
+# Reuters (browser)
+opencli reuters search "AI"              # 路透社搜索 (query positional)
+
+# 什么值得买 (browser)
+opencli smzdm search "耳机"              # 搜索好价 (query positional)
+
+# 携程 (browser)
+opencli ctrip search "三亚"              # 搜索目的地 (query positional)
+
+# Antigravity (Electron/CDP)
+opencli antigravity status              # 检查 CDP 连接
+opencli antigravity send "hello"        # 发送文本到当前 agent 聊天框
+opencli antigravity read                # 读取整个聊天记录面板
+opencli antigravity new                 # 清空聊天、开启新对话
+opencli antigravity dump               # 导出 DOM 和快照调试信息
+opencli antigravity extract-code        # 自动抽取 AI 回复中的代码块
+opencli antigravity model claude        # 切换底层模型
+opencli antigravity watch               # 流式监听增量消息
+
+# Barchart (browser)
+opencli barchart quote --symbol AAPL     # 股票行情
+opencli barchart options --symbol AAPL   # 期权链
+opencli barchart greeks --symbol AAPL    # 期权 Greeks
+opencli barchart flow --limit 20         # 异常期权活动
+
+# Jike 即刻 (browser)
+opencli jike feed --limit 10             # 动态流
+opencli jike search "AI"                 # 搜索 (query positional)
+opencli jike create "内容"                # 发布动态 (text positional)
+opencli jike like xxx                    # 点赞 (id positional)
+opencli jike comment xxx "评论"           # 评论 (id + text positional)
+opencli jike repost xxx                  # 转发 (id positional)
+opencli jike notifications               # 通知
+
+# Linux.do (public)
+opencli linux-do hot --limit 10          # 热门话题
+opencli linux-do latest --limit 10       # 最新话题
+opencli linux-do search "rust"           # 搜索 (query positional)
+opencli linux-do topic 1024              # 主题详情 (id positional)
+
+# StackOverflow (public)
+opencli stackoverflow hot --limit 10     # 热门问题
+opencli stackoverflow search "typescript"  # 搜索 (query positional)
+opencli stackoverflow bounties --limit 10  # 悬赏问题
+
+# WeRead 微信读书 (browser)
+opencli weread shelf --limit 10          # 书架
+opencli weread search "AI"               # 搜索图书 (query positional)
+opencli weread book xxx                  # 图书详情 (book-id positional)
+opencli weread highlights xxx            # 划线笔记 (book-id positional)
+opencli weread notes xxx                 # 想法笔记 (book-id positional)
+opencli weread ranking --limit 10        # 排行榜
+
+# Jimeng 即梦 AI (browser)
+opencli jimeng generate --prompt "描述"  # AI 生图
+opencli jimeng history --limit 10        # 生成历史
+
+# Yollomi yollomi.com (browser — 需在 Chrome 登录 yollomi.com，复用站点 session)
+opencli yollomi models --type image      # 列出图像模型与积分
+opencli yollomi generate "提示词" --model z-image-turbo   # 文生图
+opencli yollomi video "提示词" --model kling-2-1        # 视频
+opencli yollomi upload ./photo.jpg       # 上传得 URL，供 img2img / 工具链使用
+opencli yollomi remove-bg <image-url>    # 去背景（免费）
+opencli yollomi edit <image-url> "改成油画风格"        # Qwen 图像编辑
+
+# Grok (default + explicit web)
+opencli grok ask --prompt "问题"         # 提问 Grok（兼容默认路径）
+opencli grok ask --prompt "问题" --web   # 显式 grok.com consumer web UI 路径
+
+# HuggingFace (public)
+opencli hf top --limit 10                # 热门模型
+
+# 超星学习通 (browser)
+opencli chaoxing assignments             # 作业列表
+opencli chaoxing exams                   # 考试列表
+
+# Douban 豆瓣 (browser)
+opencli douban search "三体"              # 搜索 (query positional)
+opencli douban top250                     # 豆瓣 Top 250
+opencli douban subject 1234567            # 条目详情 (id positional)
+opencli douban marks --limit 10           # 我的标记
+opencli douban reviews --limit 10         # 短评
+
+# Facebook (browser)
+opencli facebook feed --limit 10          # 动态流
+opencli facebook profile username         # 用户资料 (id positional)
+opencli facebook search "AI"              # 搜索 (query positional)
+opencli facebook friends                  # 好友列表
+opencli facebook groups                   # 群组
+opencli facebook events                   # 活动
+opencli facebook notifications            # 通知
+opencli facebook memories                 # 回忆
+opencli facebook add-friend username      # 添加好友 (id positional)
+opencli facebook join-group groupid       # 加入群组 (id positional)
+
+# Instagram (browser)
+opencli instagram explore                 # 探索
+opencli instagram profile username        # 用户资料 (id positional)
+opencli instagram search "AI"             # 搜索 (query positional)
+opencli instagram user username           # 用户详情 (id positional)
+opencli instagram followers username      # 粉丝 (id positional)
+opencli instagram following username      # 关注 (id positional)
+opencli instagram follow username         # 关注用户 (id positional)
+opencli instagram unfollow username       # 取消关注 (id positional)
+opencli instagram like postid             # 点赞 (id positional)
+opencli instagram unlike postid           # 取消点赞 (id positional)
+opencli instagram comment postid "评论"   # 评论 (id + text positional)
+opencli instagram save postid             # 收藏 (id positional)
+opencli instagram unsave postid           # 取消收藏 (id positional)
+opencli instagram saved                   # 已收藏列表
+
+# TikTok (browser)
+opencli tiktok explore                    # 探索
+opencli tiktok search "AI"                # 搜索 (query positional)
+opencli tiktok profile username           # 用户资料 (id positional)
+opencli tiktok user username              # 用户详情 (id positional)
+opencli tiktok following username         # 关注列表 (id positional)
+opencli tiktok follow username            # 关注 (id positional)
+opencli tiktok unfollow username          # 取消关注 (id positional)
+opencli tiktok like videoid               # 点赞 (id positional)
+opencli tiktok unlike videoid             # 取消点赞 (id positional)
+opencli tiktok comment videoid "评论"     # 评论 (id + text positional)
+opencli tiktok save videoid               # 收藏 (id positional)
+opencli tiktok unsave videoid             # 取消收藏 (id positional)
+opencli tiktok live                       # 直播
+opencli tiktok notifications              # 通知
+opencli tiktok friends                    # 朋友
+
+# Medium (browser)
+opencli medium feed --limit 10            # 动态流
+opencli medium search "AI"                # 搜索 (query positional)
+opencli medium user username              # 用户主页 (id positional)
+
+# Substack (browser)
+opencli substack feed --limit 10          # 订阅动态
+opencli substack search "AI"              # 搜索 (query positional)
+opencli substack publication name         # 出版物详情 (id positional)
+
+# Sinablog 新浪博客 (browser)
+opencli sinablog hot --limit 10           # 热门
+opencli sinablog search "AI"              # 搜索 (query positional)
+opencli sinablog article url              # 文章详情
+opencli sinablog user username            # 用户主页 (id positional)
+
+# Lobsters (public)
+opencli lobsters hot --limit 10           # 热门
+opencli lobsters newest --limit 10        # 最新
+opencli lobsters active --limit 10        # 活跃
+opencli lobsters tag rust                 # 按标签筛选 (tag positional)
+
+# Google (public)
+opencli google news --limit 10            # 新闻
+opencli google search "AI"                # 搜索 (query positional)
+opencli google suggest "AI"               # 搜索建议 (query positional)
+opencli google trends                     # 趋势
+
+# DEV.to (public)
+opencli devto top --limit 10              # 热门文章
+opencli devto tag javascript --limit 10   # 按标签 (tag positional)
+opencli devto user username               # 用户文章 (username positional)
+
+# Steam (public)
+opencli steam top-sellers --limit 10      # 热销游戏
+
+# Wikipedia (public)
+opencli wikipedia search "AI"             # 搜索 (query positional)
+opencli wikipedia summary "Python"        # 摘要 (title positional)
 ```
 
-### 管理命令
+### Desktop Adapter Commands
 
 ```bash
-opencli list                # 列出所有可用命令
-opencli list --json         # JSON 格式输出
-opencli validate            # 验证所有 CLI 定义
-opencli validate bilibili   # 验证指定站点
+# Cursor (desktop — CDP via Electron)
+opencli cursor status                    # 检查连接
+opencli cursor send "message"            # 发送消息
+opencli cursor read                      # 读取回复
+opencli cursor new                       # 新建对话
+opencli cursor dump                      # 导出 DOM 调试信息
+opencli cursor composer                  # Composer 模式
+opencli cursor model claude              # 切换模型
+opencli cursor extract-code              # 提取代码块
+opencli cursor ask "question"            # 一键提问并等回复
+opencli cursor screenshot                # 截图
+opencli cursor history                   # 对话历史
+opencli cursor export                    # 导出对话
+
+# Codex (desktop — headless CLI agent)
+opencli codex status                     # 检查连接
+opencli codex send "message"             # 发送消息
+opencli codex read                       # 读取回复
+opencli codex new                        # 新建对话
+opencli codex dump                       # 导出调试信息
+opencli codex extract-diff               # 提取 diff
+opencli codex model gpt-4                # 切换模型
+opencli codex ask "question"             # 一键提问并等回复
+opencli codex screenshot                 # 截图
+opencli codex history                    # 对话历史
+opencli codex export                     # 导出对话
+
+# ChatGPT (desktop — macOS AppleScript/CDP)
+opencli chatgpt status                   # 检查应用状态
+opencli chatgpt new                      # 新建对话
+opencli chatgpt send "message"           # 发送消息
+opencli chatgpt read                     # 读取回复
+opencli chatgpt ask "question"           # 一键提问并等回复
+
+# ChatWise (desktop — multi-LLM client)
+opencli chatwise status                  # 检查连接
+opencli chatwise new                     # 新建对话
+opencli chatwise send "message"          # 发送消息
+opencli chatwise read                    # 读取回复
+opencli chatwise ask "question"          # 一键提问并等回复
+opencli chatwise model claude            # 切换模型
+opencli chatwise history                 # 对话历史
+opencli chatwise export                  # 导出对话
+opencli chatwise screenshot              # 截图
+
+# Notion (desktop — CDP via Electron)
+opencli notion status                    # 检查连接
+opencli notion search "keyword"          # 搜索页面
+opencli notion read                      # 读取当前页面
+opencli notion new                       # 新建页面
+opencli notion write "content"           # 写入内容
+opencli notion sidebar                   # 侧边栏导航
+opencli notion favorites                 # 收藏列表
+opencli notion export                    # 导出
+
+# Discord App (desktop — CDP via Electron)
+opencli discord-app status               # 检查连接
+opencli discord-app send "message"       # 发送消息
+opencli discord-app read                 # 读取消息
+opencli discord-app channels             # 频道列表
+opencli discord-app servers              # 服务器列表
+opencli discord-app search "keyword"     # 搜索
+opencli discord-app members              # 成员列表
+
+# Doubao App 豆包桌面版 (desktop — CDP via Electron)
+opencli doubao-app status                # 检查连接
+opencli doubao-app new                   # 新建对话
+opencli doubao-app send "message"        # 发送消息
+opencli doubao-app read                  # 读取回复
+opencli doubao-app ask "question"        # 一键提问并等回复
+opencli doubao-app screenshot            # 截图
+opencli doubao-app dump                  # 导出 DOM 调试信息
 ```
 
-### AI 工作流（为 AI Agent 设计）
+### Management Commands
 
 ```bash
-opencli explore <url>                 # 探索网站，生成 API 发现成果物
-opencli synthesize <site>             # 从探索成果物合成候选 CLI
-opencli generate <url> --goal "hot"   # 一键：探索 → 合成 → 注册
-opencli verify <site/name> --smoke    # 验证 + Smoke 测试
+opencli list                # List all commands (including External CLIs)
+opencli list --json         # JSON output
+opencli list -f yaml        # YAML output
+opencli install <name>      # Auto-install an external CLI (e.g., gh, obsidian)
+opencli register <name>     # Register a local custom CLI for unified discovery
+opencli validate            # Validate all CLI definitions
+opencli validate bilibili   # Validate specific site
+opencli doctor              # Diagnose browser bridge (auto-starts daemon, includes live test)
 ```
 
-## 输出格式
-
-所有命令支持 `--format` / `-f` 选项：
+### AI Agent Workflow
 
 ```bash
-opencli bilibili hot -f table   # 默认表格
-opencli bilibili hot -f json    # JSON
+# Deep Explore: network intercept → response analysis → capability inference
+opencli explore <url> --site <name>
+
+# Synthesize: generate evaluate-based YAML pipelines from explore artifacts
+opencli synthesize <site>
+
+# Generate: one-shot explore → synthesize → register
+opencli generate <url> --goal "hot"
+
+# Record: YOU operate the page, opencli captures every API call → YAML candidates
+# Opens the URL in automation window, injects fetch/XHR interceptor into ALL tabs,
+# polls every 2s, auto-stops after 60s (or press Enter to stop early).
+opencli record <url>                            # 录制，site name 从域名推断
+opencli record <url> --site mysite             # 指定 site name
+opencli record <url> --timeout 120000          # 自定义超时（毫秒，默认 60000）
+opencli record <url> --poll 1000               # 缩短轮询间隔（毫秒，默认 2000）
+opencli record <url> --out .opencli/record/x   # 自定义输出目录
+# Output:
+#   .opencli/record/<site>/captured.json        ← 原始捕获数据（带 url/method/body）
+#   .opencli/record/<site>/candidates/*.yaml    ← 高置信度候选适配器（score ≥ 8，有 array 结果）
+
+# Strategy Cascade: auto-probe PUBLIC → COOKIE → HEADER
+opencli cascade <api-url>
+
+# Explore with interactive fuzzing (click buttons to trigger lazy APIs)
+opencli explore <url> --auto --click "字幕,CC,评论"
+
+# Validate: validate adapter definitions
+opencli validate
+```
+
+## Output Formats
+
+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
 ```
 
-## 调试
+## Verbose Mode
 
 ```bash
-opencli bilibili hot -v         # 显示 pipeline 每步详情
+opencli bilibili hot -v         # Show each pipeline step and data flow
 ```
 
-## 创建新的 CLI 适配器
+## Record Workflow
 
-### YAML 方式（声明式，推荐）
+`record` 是为「无法用 `explore` 自动发现」的页面（需要登录操作、复杂交互、SPA 内路由）准备的手动录制方案。
 
-在 `src/clis/<site>/<name>.yaml` 创建文件：
+### 工作原理
+
+```
+opencli record <url>
+  → 打开 automation window 并导航到目标 URL
+  → 向所有 tab 注入 fetch/XHR 拦截器（幂等，可重复注入）
+  → 每 2s 轮询一次：发现新 tab 自动注入，drain 所有 tab 的捕获缓冲区
+  → 超时（默认 60s）或按 Enter 停止
+  → 分析捕获到的 JSON 请求：去重 → 评分 → 生成候选 YAML
+```
+
+**拦截器特性**：
+- 同时 patch `window.fetch` 和 `XMLHttpRequest`
+- 只捕获 `Content-Type: application/json` 的响应
+- 过滤纯对象少于 2 个 key 的响应（避免 tracking/ping）
+- 跨 tab 隔离：每个 tab 独立缓冲区，轮询时分别 drain
+- 幂等注入：同一 tab 二次注入时先 restore 原始函数再重新 patch，不丢失已捕获数据
+
+### 使用步骤
+
+```bash
+# 1. 启动录制（建议 --timeout 给足操作时间）
+opencli record "https://example.com/page" --timeout 120000
+
+# 2. 在弹出的 automation window 里正常操作页面：
+#    - 打开列表、搜索、点击条目、切换 Tab
+#    - 凡是触发网络请求的操作都会被捕获
+
+# 3. 完成操作后按 Enter 停止（或等超时自动停止）
+
+# 4. 查看结果
+cat .opencli/record/<site>/captured.json        # 原始捕获
+ls  .opencli/record/<site>/candidates/          # 候选 YAML
+```
+
+### 页面类型与捕获预期
+
+| 页面类型 | 预期捕获量 | 说明 |
+|---------|-----------|------|
+| 列表/搜索页 | 多（5~20+） | 每次搜索/翻页都会触发新请求 |
+| 详情页（只读） | 少（1~5） | 首屏数据一次性返回，后续操作走 form/redirect |
+| SPA 内路由跳转 | 中等 | 路由切换会触发新接口，但首屏请求在注入前已发出 |
+| 需要登录的页面 | 视操作而定 | 确保 Chrome 已登录目标网站 |
+
+> **注意**：如果页面在导航完成前就发出了大部分请求（服务端渲染 / SSR 注水），拦截器会错过这些请求。
+> 解决方案：在页面加载完成后，手动触发能产生新请求的操作（搜索、翻页、切 Tab、展开折叠项等）。
+
+### 候选 YAML → TS CLI 转换
+
+生成的候选 YAML 是起点，通常需要转换为 TypeScript（尤其是 tae 等内部系统）：
+
+**候选 YAML 结构**（自动生成）：
+```yaml
+site: tae
+name: getList          # 从 URL path 推断的名称
+strategy: cookie
+browser: true
+pipeline:
+  - navigate: https://...
+  - evaluate: |
+      (async () => {
+        const res = await fetch('/approval/getList.json?procInsId=...', { credentials: 'include' });
+        const data = await res.json();
+        return (data?.content?.operatorRecords || []).map(item => ({ ... }));
+      })()
+```
+
+**转换为 TS CLI**（参考 `src/clis/tae/add-expense.ts` 风格）：
+```typescript
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'tae',
+  name: 'get-approval',
+  description: '查看报销单审批流程和操作记录',
+  domain: 'tae.alibaba-inc.com',
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    { name: 'proc_ins_id', type: 'string', required: true, positional: true, help: '流程实例 ID（procInsId）' },
+  ],
+  columns: ['step', 'operator', 'action', 'time'],
+  func: async (page, kwargs) => {
+    await page.goto('https://tae.alibaba-inc.com/expense/pc.html?_authType=SAML');
+    await page.wait(2);
+    const result = await page.evaluate(`(async () => {
+      const res = await fetch('/approval/getList.json?taskId=&procInsId=${kwargs.proc_ins_id}', {
+        credentials: 'include'
+      });
+      const data = await res.json();
+      return data?.content?.operatorRecords || [];
+    })()`);
+    return (result as any[]).map((r, i) => ({
+      step: i + 1,
+      operator: r.operatorName || r.userId,
+      action: r.operationType,
+      time: r.operateTime,
+    }));
+  },
+});
+```
+
+**转换要点**：
+1. URL 中的动态 ID（`procInsId`、`taskId` 等）提取为 `args`
+2. `captured.json` 里的真实 body 结构用于确定正确的数据路径（如 `content.operatorRecords`）
+3. tae 系统统一用 `{ success, content, errorCode, errorMsg }` 外层包裹，取数据要走 `content.*`
+4. 认证方式：cookie（`credentials: 'include'`），不需要额外 header
+5. 文件放入 `src/clis/<site>/`，无需手动注册，`npm run build` 后自动发现
+
+### 故障排查
+
+| 现象 | 原因 | 解法 |
+|------|------|------|
+| 捕获 0 条请求 | 拦截器注入失败，或页面无 JSON API | 检查 daemon 是否运行：`curl localhost:19825/status` |
+| 捕获量少（1~3 条） | 页面是只读详情页，首屏数据已在注入前发出 | 手动操作触发更多请求（搜索/翻页），或换用列表页 |
+| 候选 YAML 为 0 | 捕获到的 JSON 都没有 array 结构 | 直接看 `captured.json` 手写 TS CLI |
+| 新开的 tab 没有被拦截 | 轮询间隔内 tab 已关闭 | 缩短 `--poll 500` |
+| 二次运行 record 时数据不连续 | 正常，每次 `record` 启动都是新的 automation window | 无需处理 |
+
+## Creating Adapters
+
+> [!TIP]
+> **快速模式**：如果你只想为一个具体页面生成一个命令，直接看 [CLI-ONESHOT.md](./CLI-ONESHOT.md)。
+> 只需要一个 URL + 一句话描述，4 步搞定。
+
+> [!IMPORTANT]
+> **完整模式 — 在写任何代码之前，先阅读 [CLI-EXPLORER.md](./CLI-EXPLORER.md)。**
+> 它包含：① AI Agent 浏览器探索工作流 ② 认证策略决策树 ③ 平台 SDK（如 Bilibili 的 `apiGet`/`fetchJson`）④ YAML vs TS 选择指南 ⑤ `tap` 步骤调试方法 ⑥ 级联请求模板 ⑦ 常见陷阱表。
+> **下方仅为简化模板参考，直接使用极易踩坑。**
+
+### YAML Pipeline (declarative, recommended)
+
+Create `src/clis/<site>/<name>.yaml`:
 
 ```yaml
 site: mysite
 name: hot
-description: Hot topics on mysite
+description: Hot topics
 domain: www.mysite.com
 strategy: cookie        # public | cookie | header | intercept | ui
 browser: true
@@ -130,11 +635,13 @@ pipeline:
   - evaluate: |
       (async () => {
         const res = await fetch('/api/hot', { credentials: 'include' });
-        return await res.json();
+        const d = await res.json();
+        return d.data.items.map(item => ({
+          title: item.title,
+          score: item.score,
+        }));
       })()
 
-  - select: data.items
-
   - map:
       rank: ${{ index + 1 }}
       title: ${{ item.title }}
@@ -145,9 +652,24 @@ pipeline:
 columns: [rank, title, score]
 ```
 
-### TypeScript 方式（编程式，更灵活）
+For public APIs (no browser):
 
-在 `src/clis/<site>/<name>.ts` 创建并在 `clis/index.ts` 中 import：
+```yaml
+strategy: public
+browser: false
+
+pipeline:
+  - fetch:
+      url: https://api.example.com/hot.json
+  - select: data.items
+  - map:
+      title: ${{ item.title }}
+  - limit: ${{ args.limit }}
+```
+
+### TypeScript Adapter (programmatic)
+
+Create `src/clis/<site>/<name>.ts`. It will be automatically dynamically loaded (DO NOT manually import it in `index.ts`):
 
 ```typescript
 import { cli, Strategy } from '../../registry.js';
@@ -155,76 +677,96 @@ import { cli, Strategy } from '../../registry.js';
 cli({
   site: 'mysite',
   name: 'search',
-  strategy: Strategy.COOKIE,
-  args: [{ name: 'keyword', required: true }],
+  strategy: Strategy.INTERCEPT, // Or COOKIE
+  args: [{ name: 'query', required: true, positional: true }],
   columns: ['rank', 'title', 'url'],
   func: async (page, kwargs) => {
-    const data = await page.evaluate(`
-      async () => {
-        const res = await fetch('/api/search?q=${kwargs.keyword}', { credentials: 'include' });
-        return await res.json();
-      }
-    `);
-    return data.items.map((item, i) => ({
-      rank: i + 1,
-      title: item.title,
-      url: item.url,
+    await page.goto('https://www.mysite.com/search');
+    
+    // Inject native XHR/Fetch interceptor hook
+    await page.installInterceptor('/api/search');
+    
+    // Auto scroll down to trigger lazy loading
+    await page.autoScroll({ times: 3, delayMs: 2000 });
+    
+    // Retrieve intercepted JSON payloads
+    const requests = await page.getInterceptedRequests();
+    
+    let results = [];
+    for (const req of requests) {
+      results.push(...req.data.items);
+    }
+    return results.map((item, i) => ({
+      rank: i + 1, title: item.title, url: item.url,
     }));
   },
 });
 ```
 
-## Pipeline 步骤参考
+**When to use TS**: XHR interception (`page.installInterceptor`), infinite scrolling (`page.autoScroll`), cookie extraction, complex data transforms (like GraphQL unwrapping).
 
-| 步骤 | 说明 | 示例 |
-|------|------|------|
-| `navigate` | 导航到 URL | `navigate: https://example.com` |
-| `fetch` | HTTP 请求（使用浏览器 cookie） | `fetch: { url: "...", params: { q: "${{ args.keyword }}" } }` |
-| `evaluate` | 执行 JavaScript | `evaluate: \| (async () => { ... })()` |
-| `select` | 选取 JSON 路径 | `select: data.items` |
-| `map` | 映射字段 | `map: { title: "${{ item.title }}" }` |
-| `filter` | 过滤 | `filter: item.score > 100` |
-| `sort` | 排序 | `sort: { by: score, order: desc }` |
-| `limit` | 限制数量 | `limit: ${{ args.limit }}` |
-| `snapshot` | 获取页面快照 | `snapshot: { interactive: true }` |
-| `click` | 点击元素 | `click: ${{ ref }}` |
-| `type` | 输入文本 | `type: { ref: "@1", text: "hello" }` |
-| `wait` | 等待 | `wait: 2` 或 `wait: { text: "loaded" }` |
-| `press` | 按键 | `press: Enter` |
+## Pipeline Steps
 
-## 模板语法
+| Step | Description | Example |
+|------|-------------|---------|
+| `navigate` | Go to URL | `navigate: https://example.com` |
+| `fetch` | HTTP request (browser cookies) | `fetch: { url: "...", params: { q: "..." } }` |
+| `evaluate` | Run JavaScript in page | `evaluate: \| (async () => { ... })()` |
+| `select` | Extract JSON path | `select: data.items` |
+| `map` | Map fields | `map: { title: "${{ item.title }}" }` |
+| `filter` | Filter items | `filter: item.score > 100` |
+| `sort` | Sort items | `sort: { by: score, order: desc }` |
+| `limit` | Cap result count | `limit: ${{ args.limit }}` |
+| `intercept` | Declarative XHR capture | `intercept: { trigger: "navigate:...", capture: "api/hot" }` |
+| `tap` | Store action + XHR capture | `tap: { store: "feed", action: "fetchFeeds", capture: "homefeed" }` |
+| `snapshot` | Page accessibility tree | `snapshot: { interactive: true }` |
+| `click` | Click element | `click: ${{ ref }}` |
+| `type` | Type text | `type: { ref: "@1", text: "hello" }` |
+| `wait` | Wait for time/text | `wait: 2` or `wait: { text: "loaded" }` |
+| `press` | Press key | `press: Enter` |
 
-使用 `${{ expression }}` 进行模板替换：
+## Template Syntax
 
 ```yaml
-# 引用参数
-${{ args.keyword }}
+# Arguments with defaults
+${{ args.query }}
 ${{ args.limit | default(20) }}
 
-# 引用当前 item（在 map/filter 中）
+# Current item (in map/filter)
 ${{ item.title }}
 ${{ item.data.nested.field }}
 
-# 索引（从 0 开始）
+# Index (0-based)
 ${{ index }}
 ${{ index + 1 }}
 ```
 
-## 环境变量
+## 5-Tier Authentication Strategy
 
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `OPENCLI_BROWSER_CONNECT_TIMEOUT` | 30 | 浏览器连接超时（秒） |
-| `OPENCLI_BROWSER_COMMAND_TIMEOUT` | 45 | 命令执行超时（秒） |
-| `OPENCLI_BROWSER_EXPLORE_TIMEOUT` | 120 | Explore 超时（秒） |
-| `OPENCLI_EXTENSION_LOCK_TIMEOUT` | 120 | 扩展锁超时（秒） |
-| `PLAYWRIGHT_MCP_EXTENSION_TOKEN` | — | 自动批准扩展连接 |
+| Tier | Name | Method | Example |
+|------|------|--------|---------|
+| 1 | `public` | No auth, Node.js fetch | Hacker News, V2EX |
+| 2 | `cookie` | Browser fetch with `credentials: include` | Bilibili, Zhihu |
+| 3 | `header` | Custom headers (ct0, Bearer) | Twitter GraphQL |
+| 4 | `intercept` | XHR interception + store mutation | 小红书 Pinia |
+| 5 | `ui` | Full UI automation (click/type/scroll) | Last resort |
 
-## 错误排查
+## Environment Variables
 
-| 错误 | 解决方案 |
-|------|----------|
-| `npx not found` | 安装 Node.js: `brew install node` |
-| `Timed out connecting to browser` | 1) 确认 Chrome 已打开 2) 安装 Playwright MCP Bridge 扩展 3) 点击扩展图标批准 |
-| `Extension lock timed out` | 等待其他 opencli 命令完成，浏览器命令需串行运行 |
-| `Request timed out` | 增大 `OPENCLI_BROWSER_COMMAND_TIMEOUT` 或检查网络 |
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENCLI_DAEMON_PORT` | 19825 | Daemon listen port |
+| `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_VERBOSE` | — | Show daemon/extension logs |
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| `npx not found` | Install Node.js: `brew install node` |
+| `Extension not connected` | 1) Chrome must be open 2) Install opencli Browser Bridge extension |
+| `Target page context` error | Add `navigate:` step before `evaluate:` in YAML |
+| Empty table data | Check if evaluate returns correct data path |
+| Daemon issues | `curl localhost:19825/status` to check, `curl localhost:19825/logs` for extension logs |

TESTING.md

@@ -0,0 +1,251 @@
+# Testing Guide
+
+> 面向开发者和 AI Agent 的测试参考手册。
+
+## 目录
+
+- [测试架构](#测试架构)
+- [当前覆盖范围](#当前覆盖范围)
+- [本地运行测试](#本地运行测试)
+- [如何添加新测试](#如何添加新测试)
+- [CI/CD 流水线](#cicd-流水线)
+- [浏览器模式](#浏览器模式)
+- [站点兼容性](#站点兼容性)
+
+---
+
+## 测试架构
+
+测试分为三层，全部使用 **vitest** 运行：
+
+```text
+tests/
+├── e2e/                           # E2E 集成测试（子进程运行真实 CLI）
+│   ├── helpers.ts                 # runCli() / parseJsonOutput() 共享工具
+│   ├── public-commands.test.ts    # 公开 API 命令
+│   ├── browser-public.test.ts     # 浏览器命令（公开数据）
+│   ├── browser-auth.test.ts       # 需登录命令（graceful failure）
+│   ├── management.test.ts         # 管理命令（list / validate / verify / help）
+│   └── output-formats.test.ts     # 输出格式校验
+├── smoke/
+│   └── api-health.test.ts         # 外部 API、adapter 定义、命令注册健康检查
+src/
+└── **/*.test.ts                   # 单元测试（当前 32 个文件）
+```
+
+| 层 | 位置 | 当前文件数 | 运行方式 | 用途 |
+|---|---|---:|---|---|
+| 单元测试 | `src/**/*.test.ts` | 32 | `npx vitest run src/` | 内部模块、pipeline、adapter 工具函数 |
+| E2E 测试 | `tests/e2e/*.test.ts` | 5 | `npx vitest run tests/e2e/` | 真实 CLI 命令执行 |
+| 烟雾测试 | `tests/smoke/*.test.ts` | 1 | `npx vitest run tests/smoke/` | 外部 API 与注册完整性 |
+
+---
+
+## 当前覆盖范围
+
+### 单元测试（32 个文件）
+
+| 领域 | 文件 |
+|---|---|
+| 核心运行时与输出 | `src/browser.test.ts`, `src/browser/dom-snapshot.test.ts`, `src/build-manifest.test.ts`, `src/capabilityRouting.test.ts`, `src/doctor.test.ts`, `src/engine.test.ts`, `src/interceptor.test.ts`, `src/output.test.ts`, `src/plugin.test.ts`, `src/registry.test.ts`, `src/snapshotFormatter.test.ts` |
+| pipeline 与下载 | `src/download/index.test.ts`, `src/pipeline/executor.test.ts`, `src/pipeline/template.test.ts`, `src/pipeline/transform.test.ts` |
+| 站点 / adapter 逻辑 | `src/clis/apple-podcasts/commands.test.ts`, `src/clis/apple-podcasts/utils.test.ts`, `src/clis/bloomberg/utils.test.ts`, `src/clis/chaoxing/utils.test.ts`, `src/clis/coupang/utils.test.ts`, `src/clis/google/utils.test.ts`, `src/clis/grok/ask.test.ts`, `src/clis/twitter/timeline.test.ts`, `src/clis/weread/utils.test.ts`, `src/clis/xiaohongshu/creator-note-detail.test.ts`, `src/clis/xiaohongshu/creator-notes-summary.test.ts`, `src/clis/xiaohongshu/creator-notes.test.ts`, `src/clis/xiaohongshu/search.test.ts`, `src/clis/xiaohongshu/user-helpers.test.ts`, `src/clis/xiaoyuzhou/utils.test.ts`, `src/clis/youtube/transcript-group.test.ts`, `src/clis/zhihu/download.test.ts` |
+
+这些测试覆盖的重点包括：
+
+- Browser Bridge、DOM snapshot、interceptor、capability routing
+- manifest 生成、命令发现、插件安装与注册表
+- 输出格式渲染与 snapshot formatting
+- pipeline 模板求值、执行器与变换步骤
+- 各站点 adapter 的数据归一化、参数处理与容错逻辑
+
+### E2E 测试（5 个文件）
+
+| 文件 | 当前覆盖范围 |
+|---|---|
+| `tests/e2e/public-commands.test.ts` | `bloomberg`、`apple-podcasts`、`hackernews`、`v2ex`、`xiaoyuzhou`、`google suggest` 等公开命令 |
+| `tests/e2e/browser-public.test.ts` | `bbc`、`bloomberg`、`bilibili`、`weibo`、`zhihu`、`reddit`、`twitter`、`xueqiu`、`reuters`、`youtube`、`smzdm`、`boss`、`ctrip`、`coupang`、`xiaohongshu`、`google`、`yahoo-finance`、`v2ex daily` |
+| `tests/e2e/browser-auth.test.ts` | `bilibili`、`twitter`、`v2ex`、`xueqiu`、`linux-do`、`xiaohongshu` 的需登录命令 graceful failure |
+| `tests/e2e/management.test.ts` | `list`、`validate`、`verify`、`--version`、`--help`、unknown command |
+| `tests/e2e/output-formats.test.ts` | `json` / `yaml` / `csv` / `md` 输出格式校验 |
+
+### 烟雾测试（1 个文件）
+
+| 文件 | 当前覆盖范围 |
+|---|---|
+| `tests/smoke/api-health.test.ts` | `hackernews`、`v2ex` 公开 API 可用性，`validate` 全量 adapter 校验，以及命令注册表基础完整性 |
+
+### 快速核对命令
+
+需要刷新测试清单时，直接以仓库文件为准：
+
+```bash
+find src -name '*.test.ts' | sort
+find tests/e2e -name '*.test.ts' | sort
+find tests/smoke -name '*.test.ts' | sort
+```
+
+---
+
+## 本地运行测试
+
+### 前置条件
+
+```bash
+npm ci                # 安装依赖
+npm run build         # 编译（E2E / smoke 测试需要 dist/main.js）
+```
+
+### 运行命令
+
+```bash
+# 全部单元测试
+npx vitest run src/
+
+# 全部 E2E 测试（会真实调用外部 API / 浏览器）
+npx vitest run tests/e2e/
+
+# 全部 smoke 测试
+npx vitest run tests/smoke/
+
+# 单个测试文件
+npx vitest run src/clis/apple-podcasts/commands.test.ts
+npx vitest run tests/e2e/management.test.ts
+
+# 全部测试
+npx vitest run
+
+# watch 模式（开发时推荐）
+npx vitest src/
+```
+
+### 浏览器命令本地测试须知
+
+- opencli 通过 Browser Bridge 扩展连接已运行的 Chrome 浏览器
+- E2E 测试通过 `tests/e2e/helpers.ts` 里的 `runCli()` 调用已构建的 `dist/main.js`
+- `browser-public.test.ts` 使用 `tryBrowserCommand()`，站点反爬或地域限制导致空数据时会 warn + pass
+- `browser-auth.test.ts` 验证 **graceful failure**，重点是不 crash、不 hang、错误信息可控
+- 如需测试完整登录态，保持 Chrome 登录态并安装 Browser Bridge 扩展，再手动运行对应测试
+
+---
+
+## 如何添加新测试
+
+### 新增 YAML Adapter（如 `src/clis/producthunt/trending.yaml`）
+
+1. `opencli validate` 的 E2E / smoke 测试会覆盖 adapter 结构校验
+2. 根据 adapter 类型，在对应测试文件补一个 `it()` block
+
+```typescript
+// 如果 browser: false（公开 API）→ tests/e2e/public-commands.test.ts
+it('producthunt trending returns data', async () => {
+  const { stdout, code } = await runCli(['producthunt', 'trending', '--limit', '3', '-f', 'json']);
+  expect(code).toBe(0);
+  const data = parseJsonOutput(stdout);
+  expect(Array.isArray(data)).toBe(true);
+  expect(data.length).toBeGreaterThanOrEqual(1);
+  expect(data[0]).toHaveProperty('title');
+}, 30_000);
+```
+
+```typescript
+// 如果 browser: true 但可公开访问 → tests/e2e/browser-public.test.ts
+it('producthunt trending returns data', async () => {
+  const data = await tryBrowserCommand(['producthunt', 'trending', '--limit', '3', '-f', 'json']);
+  expectDataOrSkip(data, 'producthunt trending');
+}, 60_000);
+```
+
+```typescript
+// 如果 browser: true 且需登录 → tests/e2e/browser-auth.test.ts
+it('producthunt me fails gracefully without login', async () => {
+  await expectGracefulAuthFailure(['producthunt', 'me', '-f', 'json'], 'producthunt me');
+}, 60_000);
+```
+
+### 新增管理命令（如 `opencli export`）
+
+在 `tests/e2e/management.test.ts` 添加测试；如果新命令会影响输出格式，也同步补 `tests/e2e/output-formats.test.ts`。
+
+### 新增内部模块
+
+在对应源码旁创建 `*.test.ts`，优先和被测模块放在同一目录下，便于发现与维护。
+
+### 决策流程图
+
+```text
+新增功能 → 是内部模块？ → 是 → src/ 下加 *.test.ts
+                ↓ 否
+         是 CLI 命令？ → browser: false? → tests/e2e/public-commands.test.ts
+                              ↓ true
+                        公开数据？ → tests/e2e/browser-public.test.ts
+                              ↓ 需登录
+                        tests/e2e/browser-auth.test.ts
+```
+
+---
+
+## CI/CD 流水线
+
+### `ci.yml`
+
+| Job | 触发条件 | 内容 |
+|---|---|---|
+| `build` | push/PR 到 `main`,`dev` | `tsc --noEmit` + `npm run build` |
+| `unit-test` | push/PR 到 `main`,`dev` | Node `20` 与 `22` 双版本运行 `src/` 单元测试，按 `2` shard 并行 |
+| `smoke-test` | `schedule` 或 `workflow_dispatch` | 安装真实 Chrome，`xvfb-run` 执行 `tests/smoke/` |
+
+### `e2e-headed.yml`
+
+| Job | 触发条件 | 内容 |
+|---|---|---|
+| `e2e-headed` | push/PR 到 `main`,`dev`，或手动触发 | 安装真实 Chrome，`xvfb-run` 执行 `tests/e2e/` |
+
+E2E 与 smoke 都使用 `./.github/actions/setup-chrome` 准备真实 Chrome，并通过 `OPENCLI_BROWSER_EXECUTABLE_PATH` 注入浏览器路径。
+
+### Sharding
+
+单元测试使用 vitest 内置 shard，并在 Node `20` / `22` 两个版本上运行：
+
+```yaml
+strategy:
+  matrix:
+    node-version: ['20', '22']
+    shard: [1, 2]
+steps:
+  - run: npx vitest run src/ --reporter=verbose --shard=${{ matrix.shard }}/2
+```
+
+---
+
+## 浏览器模式
+
+opencli 通过 Browser Bridge 扩展连接浏览器：
+
+| 条件 | 模式 | 使用场景 |
+|---|---|---|
+| 扩展已安装 / 已连接 | Extension 模式 | 本地用户，连接已登录的 Chrome |
+| 无扩展 token | CLI 自行拉起浏览器 | CI、无登录态或纯自动化场景 |
+
+CI 中使用 `OPENCLI_BROWSER_EXECUTABLE_PATH` 指定真实 Chrome 路径：
+
+```yaml
+env:
+  OPENCLI_BROWSER_EXECUTABLE_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}
+```
+
+---
+
+## 站点兼容性
+
+GitHub Actions 的美国 runner 上，部分站点会因为地域限制、登录要求或反爬而返回空数据。当前 E2E 对这些场景采用 warn + pass 策略，避免偶发站点限制把整条 CI 打红。
+
+| 站点 | CI 表现 | 常见原因 |
+|---|---|---|
+| `hackernews`、`bbc`、`v2ex`、`bloomberg` | 通常返回数据 | 公开接口或公开页面 |
+| `yahoo-finance`、`google` | 通常返回数据 | 页面公开，但仍可能受限流影响 |
+| `bilibili`、`zhihu`、`weibo`、`xiaohongshu`、`xueqiu` | 容易空数据 | 地域限制、反爬、登录要求 |
+| `reddit`、`twitter`、`youtube` | 容易空数据 | 登录态、cookie、机器人检测 |
+| `smzdm`、`boss`、`ctrip`、`coupang`、`linux-do` | 结果波动较大 | 地域限制、风控或页面结构变动 |
+
+> 如果需要更稳定的浏览器 E2E 结果，优先使用具备目标站点网络可达性的 self-hosted runner。

docs/.vitepress/config.mts

@@ -0,0 +1,210 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  base: '/docs/',
+  title: 'OpenCLI',
+  description: 'Make any website or Electron App your CLI — AI-powered, account-safe, self-healing.',
+
+  head: [
+    ['meta', { property: 'og:title', content: 'OpenCLI Documentation' }],
+    ['meta', { property: 'og:description', content: 'Make any website or Electron App your CLI.' }],
+    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
+  ],
+
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en',
+      themeConfig: {
+        nav: [
+          { text: 'Guide', link: '/guide/getting-started' },
+          { text: 'Adapters', link: '/adapters/' },
+          { text: 'Developer', link: '/developer/contributing' },
+          { text: 'Advanced', link: '/advanced/cdp' },
+        ],
+        sidebar: {
+          '/guide/': [
+            {
+              text: 'Guide',
+              items: [
+                { text: 'Getting Started', link: '/guide/getting-started' },
+                { text: 'Installation', link: '/guide/installation' },
+                { text: 'Comparison', link: '/comparison' },
+                { text: 'Browser Bridge', link: '/guide/browser-bridge' },
+                { text: 'Troubleshooting', link: '/guide/troubleshooting' },
+                { text: 'Plugins', link: '/guide/plugins' },
+              ],
+            },
+          ],
+          '/adapters/': [
+            {
+              text: 'Adapters Overview',
+              items: [
+                { text: 'All Adapters', link: '/adapters/' },
+              ],
+            },
+            {
+              text: 'Browser Adapters',
+              collapsed: false,
+              items: [
+                { text: 'Twitter / X', link: '/adapters/browser/twitter' },
+                { text: 'Reddit', link: '/adapters/browser/reddit' },
+                { text: 'Bilibili', link: '/adapters/browser/bilibili' },
+                { text: 'Zhihu', link: '/adapters/browser/zhihu' },
+                { text: 'Xiaohongshu', link: '/adapters/browser/xiaohongshu' },
+                { text: 'Weibo', link: '/adapters/browser/weibo' },
+                { text: 'YouTube', link: '/adapters/browser/youtube' },
+                { text: 'Xueqiu', link: '/adapters/browser/xueqiu' },
+                { text: 'V2EX', link: '/adapters/browser/v2ex' },
+                { text: 'Bloomberg', link: '/adapters/browser/bloomberg' },
+                { text: 'LinkedIn', link: '/adapters/browser/linkedin' },
+                { text: 'Coupang', link: '/adapters/browser/coupang' },
+                { text: 'BOSS Zhipin', link: '/adapters/browser/boss' },
+                { text: 'Ctrip', link: '/adapters/browser/ctrip' },
+                { text: 'Reuters', link: '/adapters/browser/reuters' },
+                { text: 'SMZDM', link: '/adapters/browser/smzdm' },
+                { text: 'Jike', link: '/adapters/browser/jike' },
+                { text: 'Jimeng', link: '/adapters/browser/jimeng' },
+                { text: 'Yollomi', link: '/adapters/browser/yollomi' },
+                { text: 'LINUX DO', link: '/adapters/browser/linux-do' },
+                { text: 'Chaoxing', link: '/adapters/browser/chaoxing' },
+                { text: 'Grok', link: '/adapters/browser/grok' },
+                { text: 'WeRead', link: '/adapters/browser/weread' },
+                { text: 'Douban', link: '/adapters/browser/douban' },
+                { text: 'Sina Blog', link: '/adapters/browser/sinablog' },
+                { text: 'Substack', link: '/adapters/browser/substack' },
+              ],
+            },
+            {
+              text: 'Public API Adapters',
+              collapsed: false,
+              items: [
+                { text: 'HackerNews', link: '/adapters/browser/hackernews' },
+                { text: 'Dev.to', link: '/adapters/browser/devto' },
+                { text: 'Dictionary', link: '/adapters/browser/dictionary' },
+                { text: 'BBC', link: '/adapters/browser/bbc' },
+                { text: 'Apple Podcasts', link: '/adapters/browser/apple-podcasts' },
+                { text: 'Xiaoyuzhou', link: '/adapters/browser/xiaoyuzhou' },
+                { text: 'Yahoo Finance', link: '/adapters/browser/yahoo-finance' },
+                { text: 'arXiv', link: '/adapters/browser/arxiv' },
+                { text: 'Barchart', link: '/adapters/browser/barchart' },
+                { text: 'Hugging Face', link: '/adapters/browser/hf' },
+                { text: 'Sina Finance', link: '/adapters/browser/sinafinance' },
+                { text: 'Stack Overflow', link: '/adapters/browser/stackoverflow' },
+                { text: 'Wikipedia', link: '/adapters/browser/wikipedia' },
+              ],
+            },
+            {
+              text: 'Desktop Adapters',
+              collapsed: false,
+              items: [
+                { text: 'Cursor', link: '/adapters/desktop/cursor' },
+                { text: 'Codex', link: '/adapters/desktop/codex' },
+                { text: 'Antigravity', link: '/adapters/desktop/antigravity' },
+                { text: 'ChatGPT', link: '/adapters/desktop/chatgpt' },
+                { text: 'ChatWise', link: '/adapters/desktop/chatwise' },
+                { text: 'Notion', link: '/adapters/desktop/notion' },
+                { text: 'Discord', link: '/adapters/desktop/discord' },
+              ],
+            },
+          ],
+          '/developer/': [
+            {
+              text: 'Developer Guide',
+              items: [
+                { text: 'Contributing', link: '/developer/contributing' },
+                { text: 'Testing', link: '/developer/testing' },
+                { text: 'Architecture', link: '/developer/architecture' },
+                { text: 'YAML Adapter Guide', link: '/developer/yaml-adapter' },
+                { text: 'TypeScript Adapter Guide', link: '/developer/ts-adapter' },
+                { text: 'AI Workflow', link: '/developer/ai-workflow' },
+              ],
+            },
+          ],
+          '/advanced/': [
+            {
+              text: 'Advanced',
+              items: [
+                { text: 'Chrome DevTools Protocol', link: '/advanced/cdp' },
+                { text: 'Electron Apps', link: '/advanced/electron' },
+                { text: 'Remote Chrome', link: '/advanced/remote-chrome' },
+                { text: 'Download Support', link: '/advanced/download' },
+              ],
+            },
+          ],
+        },
+      },
+    },
+    zh: {
+      label: '中文',
+      lang: 'zh-CN',
+      link: '/zh/',
+      themeConfig: {
+        nav: [
+          { text: '指南', link: '/zh/guide/getting-started' },
+          { text: '适配器', link: '/zh/adapters/' },
+          { text: '开发者', link: '/zh/developer/contributing' },
+          { text: '进阶', link: '/zh/advanced/cdp' },
+        ],
+        sidebar: {
+          '/zh/guide/': [
+            {
+              text: '指南',
+              items: [
+                { text: '快速开始', link: '/zh/guide/getting-started' },
+                { text: '安装', link: '/zh/guide/installation' },
+                { text: 'Browser Bridge', link: '/zh/guide/browser-bridge' },
+                { text: '插件', link: '/zh/guide/plugins' },
+              ],
+            },
+          ],
+          '/zh/adapters/': [
+            {
+              text: '适配器概览',
+              items: [
+                { text: '所有适配器', link: '/zh/adapters/' },
+              ],
+            },
+          ],
+          '/zh/developer/': [
+            {
+              text: '开发者指南',
+              items: [
+                { text: '贡献指南', link: '/zh/developer/contributing' },
+              ],
+            },
+          ],
+          '/zh/advanced/': [
+            {
+              text: '进阶',
+              items: [
+                { text: 'Chrome DevTools Protocol', link: '/zh/advanced/cdp' },
+              ],
+            },
+          ],
+        },
+      },
+    },
+  },
+
+  themeConfig: {
+    search: {
+      provider: 'local',
+    },
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/jackwener/opencli' },
+      { icon: 'npm', link: 'https://www.npmjs.com/package/@jackwener/opencli' },
+    ],
+
+    editLink: {
+      pattern: 'https://github.com/jackwener/opencli/edit/main/docs/:path',
+      text: 'Edit this page on GitHub',
+    },
+
+    footer: {
+      message: 'Released under the Apache-2.0 License.',
+      copyright: 'Copyright © 2024-present jackwener',
+    },
+  },
+})

docs/adapters/browser/apple-podcasts.md

@@ -0,0 +1,28 @@
+# Apple Podcasts
+
+**Mode**: 🌐 Public · **Domain**: `podcasts.apple.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli apple-podcasts search` | |
+| `opencli apple-podcasts episodes` | |
+| `opencli apple-podcasts top` | |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli apple-podcasts search --limit 5
+
+# JSON output
+opencli apple-podcasts search -f json
+
+# Verbose mode
+opencli apple-podcasts search -v
+```
+
+## Prerequisites
+
+- No browser required — uses public API

docs/adapters/browser/arxiv.md

@@ -0,0 +1,27 @@
+# arXiv
+
+**Mode**: 🌐 Public · **Domain**: `arxiv.org`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli arxiv search` | Search arXiv papers |
+| `opencli arxiv paper` | Get arXiv paper details by ID |
+
+## Usage Examples
+
+```bash
+# Search for papers
+opencli arxiv search "transformer attention" --limit 10
+
+# Get paper details by arXiv ID
+opencli arxiv paper 2301.00001
+
+# JSON output
+opencli arxiv search "LLM" -f json
+```
+
+## Prerequisites
+
+- No browser required — uses public arXiv API

docs/adapters/browser/barchart.md

@@ -0,0 +1,33 @@
+# Barchart
+
+**Mode**: 🔐 Browser · **Domain**: `barchart.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli barchart quote` | Stock quote with price, volume, and key metrics |
+| `opencli barchart options` | Options chain with greeks, IV, volume, and open interest |
+| `opencli barchart greeks` | Options greeks overview (IV, delta, gamma, theta, vega) |
+| `opencli barchart flow` | Unusual options activity / options flow |
+
+## Usage Examples
+
+```bash
+# Get stock quote
+opencli barchart quote AAPL
+
+# View options chain
+opencli barchart options TSLA
+
+# Options greeks overview
+opencli barchart greeks NVDA
+
+# Unusual options flow
+opencli barchart flow --limit 20 -f json
+```
+
+## Prerequisites
+
+- Chrome running and able to open `barchart.com`
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/bbc.md

@@ -0,0 +1,26 @@
+# BBC News
+
+**Mode**: 🌐 Public · **Domain**: `bbc.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli bbc news` | |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli bbc news --limit 5
+
+# JSON output
+opencli bbc news -f json
+
+# Verbose mode
+opencli bbc news -v
+```
+
+## Prerequisites
+
+- No browser required — uses public API

docs/adapters/browser/bilibili.md

@@ -0,0 +1,47 @@
+# Bilibili
+
+**Mode**: 🔐 Browser · **Domain**: `bilibili.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli bilibili hot` | |
+| `opencli bilibili search` | |
+| `opencli bilibili me` | |
+| `opencli bilibili favorite` | |
+| `opencli bilibili history` | |
+| `opencli bilibili feed` | |
+| `opencli bilibili subtitle` | |
+| `opencli bilibili dynamic` | |
+| `opencli bilibili ranking` | |
+| `opencli bilibili following` | |
+| `opencli bilibili user-videos` | |
+| `opencli bilibili download` | |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli bilibili hot --limit 5
+
+# Search videos
+opencli bilibili search 黑神话 --limit 10
+
+# Read one creator's videos
+opencli bilibili user-videos 2 --limit 10
+
+# Fetch subtitles
+opencli bilibili subtitle BV1xx411c7mD --lang zh-CN
+
+# JSON output
+opencli bilibili hot -f json
+
+# Verbose mode
+opencli bilibili hot -v
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** bilibili.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/bloomberg.md

@@ -0,0 +1,70 @@
+# Bloomberg
+
+**Mode**: 🌐 / 🔐 Mixed · **Domains**: `feeds.bloomberg.com`, `www.bloomberg.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli bloomberg main` | Bloomberg homepage top stories from RSS |
+| `opencli bloomberg markets` | Bloomberg Markets top stories from RSS |
+| `opencli bloomberg economics` | Bloomberg Economics top stories from RSS |
+| `opencli bloomberg industries` | Bloomberg Industries top stories from RSS |
+| `opencli bloomberg tech` | Bloomberg Tech top stories from RSS |
+| `opencli bloomberg politics` | Bloomberg Politics top stories from RSS |
+| `opencli bloomberg businessweek` | Bloomberg Businessweek top stories from RSS |
+| `opencli bloomberg opinions` | Bloomberg Opinion top stories from RSS |
+| `opencli bloomberg feeds` | List the RSS feed aliases used by the adapter |
+| `opencli bloomberg news <link>` | Read a standard Bloomberg story/article page and return title, summary, media links, and article text |
+
+## What works today
+
+- RSS-backed listing commands work without a browser:
+  - `main`
+  - `markets`
+  - `economics`
+  - `industries`
+  - `tech`
+  - `politics`
+  - `businessweek`
+  - `opinions`
+  - `feeds`
+- `bloomberg news` works on standard Bloomberg story/article pages that expose `#__NEXT_DATA__` and are accessible to your current Chrome session.
+
+## Current limitations
+
+- Audio pages and some other non-standard Bloomberg URLs may fail.
+- Some Bloomberg pages can return bot-protection or access-gated responses instead of article data.
+- This adapter is for data retrieval/extraction only. It does **not** bypass Bloomberg paywall, login, entitlement, or other access checks.
+
+## Usage Examples
+
+```bash
+# List supported RSS feed aliases
+opencli bloomberg feeds
+
+# Fetch Bloomberg homepage headlines
+opencli bloomberg main --limit 5
+
+# Fetch a section feed as JSON
+opencli bloomberg tech --limit 3 -f json
+
+# Read a standard article page
+opencli bloomberg news https://www.bloomberg.com/news/articles/2026-03-19/example -f json
+
+# Relative article paths also work
+opencli bloomberg news /news/articles/2026-03-19/example
+```
+
+## Prerequisites
+
+- RSS commands do not require Chrome.
+- `bloomberg news` requires:
+  - Chrome running
+  - a Chrome session that can already access the target Bloomberg article page
+  - the [Browser Bridge extension](/guide/browser-bridge)
+
+## Notes
+
+- RSS commands support `--limit` with a maximum of 20 items.
+- If `bloomberg news` fails on a page from RSS, try a different standard story/article link first; not every Bloomberg URL in feeds is a normal article page.

docs/adapters/browser/boss.md

@@ -0,0 +1,28 @@
+# BOSS Zhipin
+
+**Mode**: 🔐 Browser · **Domain**: `zhipin.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli boss search` | |
+| `opencli boss detail` | |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli boss search --limit 5
+
+# JSON output
+opencli boss search -f json
+
+# Verbose mode
+opencli boss search -v
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** zhipin.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/chaoxing.md

@@ -0,0 +1,39 @@
+# 超星学习通 (Chaoxing)
+
+**Mode**: 🔐 Browser · **Domain**: `mooc2-ans.chaoxing.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli chaoxing assignments` | 学习通作业列表 |
+| `opencli chaoxing exams` | 学习通考试列表 |
+
+## Usage Examples
+
+```bash
+# List all assignments
+opencli chaoxing assignments --limit 20
+
+# Filter exams by course name
+opencli chaoxing exams --course "高等数学"
+
+# Filter exams by status
+opencli chaoxing exams --status ongoing
+
+# JSON output
+opencli chaoxing assignments -f json
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--course` | Filter by course name (fuzzy match) |
+| `--status` | Filter by status: `all`, `upcoming`, `ongoing`, `finished` |
+| `--limit` | Max number of results (default: 20) |
+
+## Prerequisites
+
+- Chrome running and **logged into** mooc2-ans.chaoxing.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/coupang.md

@@ -0,0 +1,28 @@
+# Coupang
+
+**Mode**: 🔐 Browser · **Domain**: `coupang.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli coupang search` | |
+| `opencli coupang add-to-cart` | |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli coupang search --limit 5
+
+# JSON output
+opencli coupang search -f json
+
+# Verbose mode
+opencli coupang search -v
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** coupang.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/ctrip.md

@@ -0,0 +1,27 @@
+# Ctrip (携程)
+
+**Mode**: 🔐 Browser · **Domain**: `ctrip.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli ctrip search` | |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli ctrip search --limit 5
+
+# JSON output
+opencli ctrip search -f json
+
+# Verbose mode
+opencli ctrip search -v
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** ctrip.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/devto.md

@@ -0,0 +1,35 @@
+# Dev.to
+
+**Mode**: 🌐 Public · **Domain**: `dev.to`
+
+Fetch the latest and greatest developer articles from the DEV community without needing an API key.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli devto top` | Top DEV.to articles of the day |
+| `opencli devto tag` | Latest articles for a specific tag |
+| `opencli devto user` | Recent articles from a specific user |
+
+## Usage Examples
+
+```bash
+# Top articles today
+opencli devto top --limit 5
+
+# Articles by tag (positional argument)
+opencli devto tag javascript
+opencli devto tag python --limit 20
+
+# Articles by a specific author
+opencli devto user ben
+opencli devto user thepracticaldev --limit 5
+
+# JSON output
+opencli devto top -f json
+```
+
+## Prerequisites
+
+- No browser required — uses the public DEV.to API

docs/adapters/browser/dictionary.md

@@ -0,0 +1,27 @@
+# Dictionary
+
+**Mode**: 🌐 Public · **Domain**: `api.dictionaryapi.dev`
+
+Search the open dictionary to quickly fetch native definitions, part of speech contexts, and phonetic pronunciations directly in your IDE terminal.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli dictionary search` | Fetch the exact definition of a word |
+| `opencli dictionary synonyms` | Find related synonyms for a word |
+| `opencli dictionary examples` | Read real-world sentence usage examples |
+
+## Usage Examples
+
+```bash
+# Look up a complex term
+opencli dictionary search serendipity
+
+# Discover phonetics
+opencli dictionary search ephemeral
+```
+
+## Prerequisites
+
+- No browser required — utilizes the fast, open JSON definitions API.

docs/adapters/browser/douban.md

@@ -0,0 +1,48 @@
+# 豆瓣 (Douban)
+
+**Mode**: 🔐 Browser (Cookie) · **Domain**: `douban.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli douban search` | 搜索豆瓣电影、图书或音乐 |
+| `opencli douban top250` | 豆瓣电影 Top 250 |
+| `opencli douban subject` | 条目详情 |
+| `opencli douban marks` | 我的标记 |
+| `opencli douban reviews` | 我的短评 |
+| `opencli douban movie-hot` | 豆瓣电影热门榜单 |
+| `opencli douban book-hot` | 豆瓣图书热门榜单 |
+
+## Usage Examples
+
+```bash
+# 搜索电影
+opencli douban search "流浪地球"
+
+# 搜索图书
+opencli douban search --type book "三体"
+
+# 搜索音乐
+opencli douban search --type music "周杰伦"
+
+# 电影 Top 250
+opencli douban top250 --limit 10
+
+# 条目详情
+opencli douban subject 1292052
+
+# 电影热门
+opencli douban movie-hot --limit 10
+
+# 图书热门
+opencli douban book-hot --limit 10
+
+# JSON output
+opencli douban top250 -f json
+```
+
+## Prerequisites
+
+- Chrome logged into `douban.com`
+- Browser Bridge extension installed

docs/adapters/browser/doubao.md

@@ -0,0 +1,35 @@
+# doubao
+
+Browser adapter for [Doubao Chat](https://www.doubao.com/chat).
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli doubao status` | Check whether the page is reachable and whether Doubao appears logged in |
+| `opencli doubao new` | Start a new Doubao conversation |
+| `opencli doubao send "..."` | Send a message to the current Doubao chat |
+| `opencli doubao read` | Read the visible Doubao conversation |
+| `opencli doubao ask "..."` | Send a prompt and wait for a reply |
+
+## Prerequisites
+
+- Chrome is running
+- You are already logged into [doubao.com](https://www.doubao.com/)
+- Playwright MCP Bridge / browser bridge is configured for OpenCLI
+
+## Examples
+
+```bash
+opencli doubao status
+opencli doubao new
+opencli doubao send "帮我总结这段文档"
+opencli doubao read
+opencli doubao ask "请写一个 Python 快速排序示例" --timeout 90
+```
+
+## Notes
+
+- The adapter targets the web chat page at `https://www.doubao.com/chat`
+- `new` first tries the visible "New Chat / 新对话" button, then falls back to the new-thread route
+- `ask` uses DOM polling, so very long generations may need a larger `--timeout`

docs/adapters/browser/facebook.md

@@ -0,0 +1,36 @@
+# Facebook
+
+**Mode**: 🔐 Browser · **Domain**: `facebook.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli facebook profile` | Get user/page profile info |
+| `opencli facebook notifications` | Get recent notifications |
+| `opencli facebook feed` | Get news feed posts |
+| `opencli facebook search` | Search people, pages, posts |
+
+## Usage Examples
+
+```bash
+# View a profile
+opencli facebook profile zuck
+
+# Get notifications
+opencli facebook notifications --limit 10
+
+# News feed
+opencli facebook feed --limit 5
+
+# Search
+opencli facebook search "OpenAI" --limit 5
+
+# JSON output
+opencli facebook profile zuck -f json
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** facebook.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/google.md

@@ -0,0 +1,62 @@
+# Google
+
+**Mode**: 🌐 / 🔐 Mixed · **Domains**: `google.com`, `suggestqueries.google.com`, `news.google.com`, `trends.google.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli google search <keyword>` | Search Google and extract results from the page |
+| `opencli google suggest <keyword>` | Get Google search suggestions |
+| `opencli google news [keyword]` | Get Google News headlines (top stories or search) |
+| `opencli google trends` | Get Google Trends daily trending searches |
+
+## What works today
+
+- Public API commands work without a browser:
+  - `suggest` — JSON API, no auth needed
+  - `news` — RSS feed, supports top stories and keyword search
+  - `trends` — RSS feed, supports different regions
+- `google search` uses browser mode to extract results from google.com.
+
+## Current limitations
+
+- `google search` may trigger CAPTCHA in Standalone browser mode. Extension mode (with an established Chrome session) is more reliable.
+- Google frequently changes its DOM structure. If `search` stops returning results, selectors may need updating.
+- Snippet extraction may return empty for some results depending on Google's layout.
+
+## Usage Examples
+
+```bash
+# Search Google
+opencli google search "typescript tutorial" --limit 10
+
+# Get search suggestions
+opencli google suggest python
+
+# Get top news headlines
+opencli google news --limit 5
+
+# Search news for a topic
+opencli google news "artificial intelligence" --limit 10 --lang en --region US
+
+# Get trending searches in Japan
+opencli google trends --region JP --limit 10
+
+# Output as JSON
+opencli google search "machine learning" -f json
+```
+
+## Prerequisites
+
+- `suggest`, `news`, `trends` do not require Chrome.
+- `search` requires:
+  - Chrome running (or Standalone mode will auto-launch)
+  - For best results, use the [Browser Bridge extension](/guide/browser-bridge) with an established Google session
+
+## Notes
+
+- `suggest` defaults to `--lang zh-CN`; other commands default to `--lang en`.
+- `news` supports `--lang` and `--region` parameters for localized results.
+- `trends` traffic values are raw strings (e.g. "500K+", "1,000,000+"), not numeric.
+- `search` output includes three result types: `result` (standard), `snippet` (featured answer box), and `paa` (People Also Ask).

docs/adapters/browser/grok.md

@@ -0,0 +1,53 @@
+# Grok
+
+**Mode**: Default Grok adapter + optional explicit consumer web path · **Domain**: `grok.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli grok ask` | Keep the default Grok ask behavior |
+| `opencli grok ask --web` | Use the explicit grok.com consumer web UI flow |
+
+## Usage Examples
+
+```bash
+# Default / compatibility path
+opencli grok ask --prompt "Explain quantum computing in simple terms"
+
+# Explicit consumer web path
+opencli grok ask --prompt "Explain quantum computing in simple terms" --web
+
+# Best-effort fresh chat on the consumer web path
+opencli grok ask --prompt "Hello" --web --new
+
+# Set custom timeout (default: 120s)
+opencli grok ask --prompt "Write a long essay" --web --timeout 180
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--prompt` | The message to send (required) |
+| `--timeout` | Wait timeout in seconds (default: 120) |
+| `--new` | Start a new chat before sending (default: false) |
+| `--web` | Opt into the explicit grok.com consumer web flow (default: false) |
+
+## Behavior
+
+- `opencli grok ask` keeps the upstream/default behavior intact.
+- `opencli grok ask --web` switches to the newer hardened consumer-web implementation.
+- The `--web` path adds stricter composer detection, clearer blocked/session-gated hints, and waits for a stabilized assistant bubble before returning.
+
+## Prerequisites
+
+- The Grok adapter still depends on browser-backed access to `grok.com`
+- For `--web`, Chrome should already be running with an authenticated Grok consumer session
+- [Browser Bridge extension](/guide/browser-bridge) installed
+
+## Caveats
+
+- `--web` drives the Grok consumer web UI in the browser, not an API.
+- It depends on an already-authenticated session and can fail if Grok shows login, challenge, rate-limit, or other session-gating UI.
+- It may break when the Grok composer DOM, submit button behavior, or message bubble structure changes.

docs/adapters/browser/hackernews.md

@@ -0,0 +1,42 @@
+# HackerNews
+
+**Mode**: 🌐 Public · **Domain**: `news.ycombinator.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli hackernews top` | Hacker News top stories |
+| `opencli hackernews new` | Hacker News newest stories |
+| `opencli hackernews best` | Hacker News best stories |
+| `opencli hackernews ask` | Hacker News Ask HN posts |
+| `opencli hackernews show` | Hacker News Show HN posts |
+| `opencli hackernews jobs` | Hacker News job postings |
+| `opencli hackernews search <query>` | Search Hacker News stories |
+| `opencli hackernews user <username>` | Hacker News user profile |
+
+## Usage Examples
+
+```bash
+# Top stories
+opencli hackernews top --limit 5
+
+# Newest stories
+opencli hackernews new --limit 10
+
+# Search stories
+opencli hackernews search "machine learning" --limit 5
+
+# User profile
+opencli hackernews user pg
+
+# JSON output
+opencli hackernews top -f json
+
+# Sort search by date
+opencli hackernews search "rust" --sort date
+```
+
+## Prerequisites
+
+- No browser required — uses public API

docs/adapters/browser/hf.md

@@ -0,0 +1,42 @@
+# Hugging Face
+
+**Mode**: 🌐 Public · **Domain**: `huggingface.co`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli hf top` | Top upvoted Hugging Face papers |
+
+## Usage Examples
+
+```bash
+# Today's top papers
+opencli hf top --limit 10
+
+# All papers (no limit)
+opencli hf top --all
+
+# Specific date
+opencli hf top --date 2025-03-01
+
+# Weekly/monthly top papers
+opencli hf top --period weekly
+opencli hf top --period monthly
+
+# JSON output
+opencli hf top -f json
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--limit` | Number of papers (default: 20) |
+| `--all` | Return all papers, ignoring limit |
+| `--date` | Date in `YYYY-MM-DD` format (defaults to most recent) |
+| `--period` | Time period: `daily`, `weekly`, or `monthly` (default: daily) |
+
+## Prerequisites
+
+- No browser required — uses public Hugging Face API

docs/adapters/browser/instagram.md

@@ -0,0 +1,46 @@
+# Instagram
+
+**Mode**: 🔐 Browser · **Domain**: `instagram.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli instagram profile` | Get user profile info |
+| `opencli instagram search` | Search users |
+| `opencli instagram user` | Get recent posts from a user |
+| `opencli instagram explore` | Discover trending posts |
+| `opencli instagram followers` | List user's followers |
+| `opencli instagram following` | List user's following |
+| `opencli instagram saved` | Get your saved posts |
+
+## Usage Examples
+
+```bash
+# View a user's profile
+opencli instagram profile nasa
+
+# Search users
+opencli instagram search nasa --limit 5
+
+# View a user's recent posts
+opencli instagram user nasa --limit 10
+
+# Discover trending posts
+opencli instagram explore --limit 20
+
+# List followers/following
+opencli instagram followers nasa --limit 20
+opencli instagram following nasa --limit 20
+
+# Get your saved posts
+opencli instagram saved --limit 10
+
+# JSON output
+opencli instagram profile nasa -f json
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** instagram.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/jd.md

@@ -0,0 +1,27 @@
+# JD.com
+
+**Mode**: 🔐 Browser · **Domain**: `item.jd.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli jd item <sku>` | Fetch product details (price, images, specs) |
+
+## Usage Examples
+
+```bash
+# Get product details by SKU
+opencli jd item 100291143898
+
+# Limit detail images
+opencli jd item 100291143898 --images 5
+
+# JSON output
+opencli jd item 100291143898 -f json
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** jd.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/jike.md

@@ -0,0 +1,45 @@
+# 即刻 (Jike)
+
+**Mode**: 🔐 Browser · **Domain**: `web.okjike.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli jike feed` | 即刻首页动态流 |
+| `opencli jike search` | 搜索即刻帖子 |
+| `opencli jike post` | 帖子详情及评论 |
+| `opencli jike topic` | 话题详情 |
+| `opencli jike user` | 用户资料 |
+| `opencli jike create` | 发布即刻动态 |
+| `opencli jike comment` | 评论即刻帖子 |
+| `opencli jike like` | 点赞即刻帖子 |
+| `opencli jike repost` | 转发即刻帖子 |
+| `opencli jike notifications` | 即刻通知 |
+
+## Usage Examples
+
+```bash
+# View feed
+opencli jike feed --limit 10
+
+# Search posts
+opencli jike search "AI" --limit 20
+
+# View post details and comments
+opencli jike post <post-id>
+
+# Create a new post
+opencli jike create --content "Hello Jike!"
+
+# Like a post
+opencli jike like <post-id>
+
+# JSON output
+opencli jike feed -f json
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** web.okjike.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/jimeng.md

@@ -0,0 +1,39 @@
+# 即梦AI (Jimeng)
+
+**Mode**: 🔐 Browser · **Domain**: `jimeng.jianying.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli jimeng generate` | 即梦AI 文生图 — 输入 prompt 生成图片 |
+| `opencli jimeng history` | 查看生成历史 |
+
+## Usage Examples
+
+```bash
+# Generate an image
+opencli jimeng generate --prompt "一只在星空下的猫"
+
+# Use a specific model
+opencli jimeng generate --prompt "cyberpunk city" --model high_aes_general_v50
+
+# Set custom wait timeout
+opencli jimeng generate --prompt "sunset landscape" --wait 60
+
+# View generation history
+opencli jimeng history --limit 10
+```
+
+### Options (generate)
+
+| Option | Description |
+|--------|-------------|
+| `--prompt` | Image description prompt (required) |
+| `--model` | Model: `high_aes_general_v50` (5.0 Lite), `high_aes_general_v42` (4.6), `high_aes_general_v40` (4.0) |
+| `--wait` | Wait seconds for generation (default: 40) |
+
+## Prerequisites
+
+- Chrome running and **logged into** jimeng.jianying.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/linkedin.md

@@ -0,0 +1,33 @@
+# LinkedIn
+
+**Mode**: 🔐 Browser · **Domain**: `linkedin.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli linkedin search` | |
+| `opencli linkedin timeline` | Read posts from your LinkedIn home feed |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli linkedin search --limit 5
+
+# Read your home timeline
+opencli linkedin timeline --limit 5
+
+# JSON output
+opencli linkedin search -f json
+
+opencli linkedin timeline -f json
+
+# Verbose mode
+opencli linkedin search -v
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** linkedin.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/linux-do.md

@@ -0,0 +1,45 @@
+# LINUX DO
+
+**Mode**: 🔐 Browser · **Domain**: `linux.do`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli linux-do hot` | 热门话题 |
+| `opencli linux-do latest` | 最新话题 |
+| `opencli linux-do categories` | 板块列表 |
+| `opencli linux-do category` | 板块话题 |
+| `opencli linux-do search` | 搜索话题 |
+| `opencli linux-do topic` | 话题详情 |
+
+## Usage Examples
+
+```bash
+# Hot topics this week
+opencli linux-do hot --limit 20
+
+# Hot topics by period
+opencli linux-do hot --period daily
+opencli linux-do hot --period monthly
+
+# Latest topics
+opencli linux-do latest --limit 10
+
+# List all categories
+opencli linux-do categories
+
+# Search topics
+opencli linux-do search "NixOS"
+
+# View topic details
+opencli linux-do topic 12345
+
+# JSON output
+opencli linux-do hot -f json
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** linux.do
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/lobsters.md

@@ -0,0 +1,32 @@
+# Lobsters
+
+**Mode**: 🌐 Public · **Domain**: `lobste.rs`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli lobsters hot` | Hottest stories |
+| `opencli lobsters newest` | Latest stories |
+| `opencli lobsters active` | Most active discussions |
+| `opencli lobsters tag` | Stories by tag |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli lobsters hot --limit 10
+
+# Filter by tag
+opencli lobsters tag --tag rust --limit 5
+
+# JSON output
+opencli lobsters hot -f json
+
+# Verbose mode
+opencli lobsters hot -v
+```
+
+## Prerequisites
+
+None — all commands use the public JSON API, no browser or login required.

docs/adapters/browser/medium.md

@@ -0,0 +1,32 @@
+# Medium
+
+**Mode**: 🌗 Mixed · **Domain**: `medium.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli medium feed` | Get hot Medium posts, optionally scoped to a topic |
+| `opencli medium search` | Search Medium posts by keyword |
+| `opencli medium user` | Get recent articles by a user |
+
+## Usage Examples
+
+```bash
+# Get the general Medium feed
+opencli medium feed --limit 10
+
+# Search posts by keyword
+opencli medium search ai
+
+# Get articles by a user
+opencli medium user @username
+
+# Topic feed as JSON
+opencli medium feed --topic programming -f json
+```
+
+## Prerequisites
+
+- `opencli medium search` can run without a browser
+- `opencli medium feed` and `opencli medium user` require Browser Bridge access to `medium.com`

docs/adapters/browser/reddit.md

@@ -0,0 +1,50 @@
+# Reddit
+
+**Mode**: 🔐 Browser · **Domain**: `reddit.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli reddit hot` | |
+| `opencli reddit frontpage` | |
+| `opencli reddit popular` | |
+| `opencli reddit search` | |
+| `opencli reddit subreddit` | |
+| `opencli reddit read` | |
+| `opencli reddit user` | |
+| `opencli reddit user-posts` | |
+| `opencli reddit user-comments` | |
+| `opencli reddit upvote` | |
+| `opencli reddit save` | |
+| `opencli reddit comment` | |
+| `opencli reddit subscribe` | |
+| `opencli reddit saved` | |
+| `opencli reddit upvoted` | |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli reddit hot --limit 5
+
+# Read one subreddit
+opencli reddit subreddit python --limit 10
+
+# Read a post thread
+opencli reddit read 1abc123 --depth 2
+
+# Comment on a post
+opencli reddit comment 1abc123 "Great post"
+
+# JSON output
+opencli reddit hot -f json
+
+# Verbose mode
+opencli reddit hot -v
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** reddit.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/reuters.md

@@ -0,0 +1,27 @@
+# Reuters
+
+**Mode**: 🔐 Browser · **Domain**: `reuters.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli reuters search` | |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli reuters search --limit 5
+
+# JSON output
+opencli reuters search -f json
+
+# Verbose mode
+opencli reuters search -v
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** reuters.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/sinablog.md

@@ -0,0 +1,36 @@
+# 新浪博客 (Sina Blog)
+
+**Mode**: 🌐 Public (search) / 🔐 Browser (hot, article, user) · **Domain**: `blog.sina.com.cn`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli sinablog hot` | 获取新浪博客热门文章/推荐 |
+| `opencli sinablog search` | 搜索新浪博客文章（通过新浪搜索，无需浏览器） |
+| `opencli sinablog article` | 获取新浪博客单篇文章详情 |
+| `opencli sinablog user` | 获取新浪博客用户的文章列表 |
+
+## Usage Examples
+
+```bash
+# 热门文章
+opencli sinablog hot --limit 10
+
+# 搜索文章（公开 API，无需浏览器）
+opencli sinablog search "人工智能"
+
+# 文章详情
+opencli sinablog article "https://blog.sina.com.cn/s/blog_xxx.html"
+
+# 用户文章列表
+opencli sinablog user 1234567890 --limit 10
+
+# JSON output
+opencli sinablog hot -f json
+```
+
+## Prerequisites
+
+- `search` command: No login required (public API)
+- `hot`, `article`, `user` commands: Chrome with `blog.sina.com.cn` accessible, Browser Bridge extension installed

docs/adapters/browser/sinafinance.md

@@ -0,0 +1,35 @@
+# 新浪财经 (Sina Finance)
+
+**Mode**: 🌐 Public · **Domain**: `finance.sina.com.cn`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli sinafinance news` | 新浪财经 7×24 小时实时快讯 |
+
+## Usage Examples
+
+```bash
+# Latest financial news
+opencli sinafinance news --limit 20
+
+# Filter by type
+opencli sinafinance news --type 1   # A股
+opencli sinafinance news --type 2   # 宏观
+opencli sinafinance news --type 6   # 国际
+
+# JSON output
+opencli sinafinance news -f json
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--limit` | Max results, up to 50 (default: 20) |
+| `--type` | News type: `0`=全部, `1`=A股, `2`=宏观, `3`=公司, `4`=数据, `5`=市场, `6`=国际, `7`=观点, `8`=央行, `9`=其它 |
+
+## Prerequisites
+
+- No browser required — uses public API

docs/adapters/browser/smzdm.md

@@ -0,0 +1,27 @@
+# SMZDM (什么值得买)
+
+**Mode**: 🔐 Browser · **Domain**: `smzdm.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli smzdm search` | |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli smzdm search --limit 5
+
+# JSON output
+opencli smzdm search -f json
+
+# Verbose mode
+opencli smzdm search -v
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** smzdm.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/stackoverflow.md

@@ -0,0 +1,35 @@
+# Stack Overflow
+
+**Mode**: 🌐 Public · **Domain**: `stackoverflow.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli stackoverflow hot` | Hot questions |
+| `opencli stackoverflow search` | Search questions |
+| `opencli stackoverflow bounties` | Questions with active bounties |
+| `opencli stackoverflow unanswered` | Unanswered questions |
+
+## Usage Examples
+
+```bash
+# Hot questions
+opencli stackoverflow hot --limit 10
+
+# Search questions
+opencli stackoverflow search "async await" --limit 20
+
+# Active bounties
+opencli stackoverflow bounties --limit 10
+
+# Unanswered questions
+opencli stackoverflow unanswered --limit 10
+
+# JSON output
+opencli stackoverflow hot -f json
+```
+
+## Prerequisites
+
+- No browser required — uses public Stack Exchange API

docs/adapters/browser/steam.md

@@ -0,0 +1,26 @@
+# Steam
+
+**Mode**: 🌐 Public · **Domain**: `store.steampowered.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli steam top-sellers` | Top selling games on Steam |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli steam top-sellers
+
+# Limit results
+opencli steam top-sellers --limit 5
+
+# JSON output
+opencli steam top-sellers -f json
+```
+
+## Prerequisites
+
+- No login required (public API)

docs/adapters/browser/substack.md

@@ -0,0 +1,38 @@
+# Substack
+
+**Mode**: 🌐 Public (search) / 🔐 Browser (feed, publication) · **Domain**: `substack.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli substack feed` | Substack 热门文章 Feed |
+| `opencli substack search` | 搜索 Substack 文章和 Newsletter（无需浏览器） |
+| `opencli substack publication` | 获取特定 Substack Newsletter 的最新文章 |
+
+## Usage Examples
+
+```bash
+# 热门 Feed
+opencli substack feed --limit 10
+
+# 按分类浏览
+opencli substack feed --category tech --limit 10
+
+# 搜索文章（公开 API，无需浏览器）
+opencli substack search "AI"
+
+# 搜索 Newsletter
+opencli substack search "technology" --type publications
+
+# 查看特定 Newsletter 的最新文章
+opencli substack publication "https://example.substack.com" --limit 10
+
+# JSON output
+opencli substack search "AI" -f json
+```
+
+## Prerequisites
+
+- `search` command: No login required (public API)
+- `feed`, `publication` commands: Chrome with `substack.com` accessible, Browser Bridge extension installed

docs/adapters/browser/tiktok.md

@@ -0,0 +1,68 @@
+# TikTok
+
+**Mode**: 🔐 Browser · **Domain**: `tiktok.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli tiktok profile` | Get user profile info |
+| `opencli tiktok search` | Search videos |
+| `opencli tiktok explore` | Trending videos from explore page |
+| `opencli tiktok user` | Get recent videos from a user |
+| `opencli tiktok following` | List accounts you follow |
+| `opencli tiktok friends` | Friend suggestions |
+| `opencli tiktok live` | Browse live streams |
+| `opencli tiktok notifications` | Get notifications |
+| `opencli tiktok like` | Like a video |
+| `opencli tiktok unlike` | Unlike a video |
+| `opencli tiktok save` | Add to Favorites |
+| `opencli tiktok unsave` | Remove from Favorites |
+| `opencli tiktok follow` | Follow a user |
+| `opencli tiktok unfollow` | Unfollow a user |
+| `opencli tiktok comment` | Comment on a video |
+
+## Usage Examples
+
+```bash
+# View a user's profile
+opencli tiktok profile --username tiktok
+
+# Search videos
+opencli tiktok search "cooking" --limit 10
+
+# Trending explore videos
+opencli tiktok explore --limit 20
+
+# Browse live streams
+opencli tiktok live --limit 10
+
+# List who you follow
+opencli tiktok following
+
+# Friend suggestions
+opencli tiktok friends --limit 10
+
+# Like/unlike a video
+opencli tiktok like --url "https://www.tiktok.com/@user/video/123"
+opencli tiktok unlike --url "https://www.tiktok.com/@user/video/123"
+
+# Save/unsave (Favorites)
+opencli tiktok save --url "https://www.tiktok.com/@user/video/123"
+opencli tiktok unsave --url "https://www.tiktok.com/@user/video/123"
+
+# Follow/unfollow
+opencli tiktok follow --username nasa
+opencli tiktok unfollow --username nasa
+
+# Comment on a video
+opencli tiktok comment --url "https://www.tiktok.com/@user/video/123" --text "Great!"
+
+# JSON output
+opencli tiktok profile --username tiktok -f json
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** tiktok.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/twitter.md

@@ -0,0 +1,50 @@
+# Twitter / X
+
+**Mode**: 🔐 Browser · **Domain**: `twitter.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli twitter trending` | |
+| `opencli twitter bookmarks` | |
+| `opencli twitter profile` | |
+| `opencli twitter search` | |
+| `opencli twitter timeline` | |
+| `opencli twitter thread` | |
+| `opencli twitter following` | |
+| `opencli twitter followers` | |
+| `opencli twitter notifications` | |
+| `opencli twitter post` | |
+| `opencli twitter reply` | |
+| `opencli twitter delete` | |
+| `opencli twitter like` | |
+| `opencli twitter article` | |
+| `opencli twitter follow` | |
+| `opencli twitter unfollow` | |
+| `opencli twitter bookmark` | |
+| `opencli twitter unbookmark` | |
+| `opencli twitter block` | |
+| `opencli twitter unblock` | |
+| `opencli twitter hide-reply` | |
+| `opencli twitter download` | |
+| `opencli twitter accept` | |
+| `opencli twitter reply-dm` | |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli twitter trending --limit 5
+
+# JSON output
+opencli twitter trending -f json
+
+# Verbose mode
+opencli twitter trending -v
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** twitter.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/v2ex.md

@@ -0,0 +1,53 @@
+# V2EX
+
+**Mode**: 🌐 / 🔐 · **Domain**: `v2ex.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli v2ex hot` | Hot topics |
+| `opencli v2ex latest` | Latest topics |
+| `opencli v2ex topic <id>` | Topic detail |
+| `opencli v2ex node <name>` | Topics by node |
+| `opencli v2ex user <username>` | Topics by user |
+| `opencli v2ex member <username>` | User profile |
+| `opencli v2ex replies <id>` | Topic replies |
+| `opencli v2ex nodes` | All nodes (sorted by topic count) |
+| `opencli v2ex daily` | Daily hot |
+| `opencli v2ex me` | My profile (auth required) |
+| `opencli v2ex notifications` | My notifications (auth required) |
+
+## Usage Examples
+
+```bash
+# Hot topics
+opencli v2ex hot --limit 5
+
+# Browse topics in a node
+opencli v2ex node python
+
+# View topic replies
+opencli v2ex replies 1000
+
+# User's topics
+opencli v2ex user Livid
+
+# User profile
+opencli v2ex member Livid
+
+# List all nodes
+opencli v2ex nodes --limit 10
+
+# JSON output
+opencli v2ex hot -f json
+```
+
+## Prerequisites
+
+Most commands (`hot`, `latest`, `topic`, `node`, `user`, `member`, `replies`, `nodes`) use the public V2EX API and **require no browser or login**.
+
+For `daily`, `me`, and `notifications`:
+
+- Chrome running and **logged into** v2ex.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/web.md

@@ -0,0 +1,30 @@
+# Web
+
+**Mode**: 🔐 Browser · **Domain**: any URL
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli web read <url>` | Fetch any web page and export as Markdown |
+
+## Usage Examples
+
+```bash
+# Read a web page and save as Markdown
+opencli web read https://example.com/article
+
+# Custom output directory
+opencli web read https://example.com/article --output ./my-articles
+
+# Skip image download
+opencli web read https://example.com/article --download-images false
+
+# JSON output
+opencli web read https://example.com/article -f json
+```
+
+## Prerequisites
+
+- Chrome running
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/weibo.md

@@ -0,0 +1,31 @@
+# Weibo (微博)
+
+**Mode**: 🔐 Browser · **Domain**: `weibo.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli weibo hot` | |
+| `opencli weibo search` | Search Weibo posts by keyword |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli weibo hot --limit 5
+
+# JSON output
+opencli weibo hot -f json
+
+# Search
+opencli weibo search "OpenAI" --limit 5
+
+# Verbose mode
+opencli weibo hot -v
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** weibo.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/weixin.md

@@ -0,0 +1,33 @@
+# WeChat (微信公众号)
+
+**Mode**: 🔐 Browser · **Domain**: `mp.weixin.qq.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli weixin download` | 下载微信公众号文章为 Markdown 格式 |
+
+## Usage Examples
+
+```bash
+# Export article to Markdown
+opencli weixin download --url "https://mp.weixin.qq.com/s/xxx" --output ./weixin
+
+# Export with locally downloaded images
+opencli weixin download --url "https://mp.weixin.qq.com/s/xxx" --download-images
+
+# Export without images
+opencli weixin download --url "https://mp.weixin.qq.com/s/xxx" --no-download-images
+```
+
+## Output
+
+Downloads to `<output>/<article-title>/`:
+- `<article-title>.md` — Markdown with frontmatter (title, author, publish time, source URL)
+- `images/` — Downloaded images (if `--download-images` is enabled, default: true)
+
+## Prerequisites
+
+- Chrome running and **logged into** mp.weixin.qq.com (for articles behind login wall)
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/weread.md

@@ -0,0 +1,48 @@
+# 微信读书 (WeRead)
+
+**Mode**: 🔐 Browser · **Domain**: `weread.qq.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli weread shelf` | List books on your bookshelf |
+| `opencli weread search` | Search books on WeRead |
+| `opencli weread book` | View book details |
+| `opencli weread ranking` | Book rankings by category |
+| `opencli weread notebooks` | List books that have highlights or notes |
+| `opencli weread highlights` | List your highlights (underlines) in a book |
+| `opencli weread notes` | List your notes (thoughts) on a book |
+
+## Usage Examples
+
+```bash
+# View your bookshelf
+opencli weread shelf --limit 20
+
+# Search books
+opencli weread search "三体"
+
+# View book details
+opencli weread book <book-id>
+
+# Book rankings
+opencli weread ranking --limit 10
+
+# List books with notes/highlights
+opencli weread notebooks
+
+# View highlights for a book
+opencli weread highlights <book-id>
+
+# View your notes
+opencli weread notes <book-id>
+
+# JSON output
+opencli weread shelf -f json
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** weread.qq.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/wikipedia.md

@@ -0,0 +1,30 @@
+# Wikipedia
+
+**Mode**: 🌐 Public · **Domain**: `wikipedia.org`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli wikipedia search` | Search Wikipedia articles |
+| `opencli wikipedia summary` | Get Wikipedia article summary |
+
+## Usage Examples
+
+```bash
+# Search articles
+opencli wikipedia search "quantum computing" --limit 10
+
+# Get article summary
+opencli wikipedia summary "Artificial intelligence"
+
+# Use with other languages
+opencli wikipedia search "人工智能" --lang zh
+
+# JSON output
+opencli wikipedia search "Rust" -f json
+```
+
+## Prerequisites
+
+- No browser required — uses public Wikipedia API

docs/adapters/browser/xiaohongshu.md

@@ -0,0 +1,38 @@
+# Xiaohongshu (小红书)
+
+**Mode**: 🔐 Browser · **Domain**: `xiaohongshu.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli xiaohongshu search` | Search notes by keyword (returns title, author, likes, URL) |
+| `opencli xiaohongshu notifications` | |
+| `opencli xiaohongshu feed` | |
+| `opencli xiaohongshu user` | |
+| `opencli xiaohongshu download` | |
+| `opencli xiaohongshu creator-notes` | |
+| `opencli xiaohongshu creator-note-detail` | |
+| `opencli xiaohongshu creator-notes-summary` | |
+| `opencli xiaohongshu creator-profile` | |
+| `opencli xiaohongshu creator-stats` | |
+
+## Usage Examples
+
+```bash
+# Search for notes
+opencli xiaohongshu search 美食 --limit 10
+
+# JSON output
+opencli xiaohongshu search 旅行 -f json
+
+# Other commands
+opencli xiaohongshu feed
+opencli xiaohongshu notifications
+opencli xiaohongshu download <url>
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** xiaohongshu.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/xiaoyuzhou.md

@@ -0,0 +1,28 @@
+# Xiaoyuzhou (小宇宙)
+
+**Mode**: 🌐 Public · **Domain**: `xiaoyuzhou.fm`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli xiaoyuzhou podcast` | |
+| `opencli xiaoyuzhou podcast-episodes` | |
+| `opencli xiaoyuzhou episode` | |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli xiaoyuzhou podcast --limit 5
+
+# JSON output
+opencli xiaoyuzhou podcast -f json
+
+# Verbose mode
+opencli xiaoyuzhou podcast -v
+```
+
+## Prerequisites
+
+- No browser required — uses public API

docs/adapters/browser/xueqiu.md

@@ -0,0 +1,42 @@
+# Xueqiu (雪球)
+
+**Mode**: 🔐 Browser · **Domain**: `xueqiu.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli xueqiu feed` | |
+| `opencli xueqiu earnings-date` | |
+| `opencli xueqiu hot-stock` | |
+| `opencli xueqiu hot` | |
+| `opencli xueqiu search` | |
+| `opencli xueqiu stock` | |
+| `opencli xueqiu watchlist` | |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli xueqiu feed --limit 5
+
+# Search stocks
+opencli xueqiu search 茅台
+
+# View one stock
+opencli xueqiu stock SH600519
+
+# Upcoming earnings dates
+opencli xueqiu earnings-date SH600519 --next
+
+# JSON output
+opencli xueqiu feed -f json
+
+# Verbose mode
+opencli xueqiu feed -v
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** xueqiu.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/yahoo-finance.md

@@ -0,0 +1,27 @@
+# Yahoo Finance
+
+**Mode**: 🔐 Browser · **Domain**: `finance.yahoo.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli yahoo-finance quote` | |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli yahoo-finance quote AAPL
+
+# JSON output
+opencli yahoo-finance quote TSLA -f json
+
+# Verbose mode
+opencli yahoo-finance quote NVDA -v
+```
+
+## Prerequisites
+
+- Chrome running and able to open `finance.yahoo.com`
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/yollomi.md

@@ -0,0 +1,69 @@
+# Yollomi
+
+**Mode**: 🔐 Browser · **Domain**: `yollomi.com`
+
+AI image/video generation and editing on [yollomi.com](https://yollomi.com). Uses the same `/api/ai/*` routes as the web app; authentication is your **logged-in Chrome session** (NextAuth cookies).
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli yollomi generate` | Text-to-image / image-to-image |
+| `opencli yollomi video` | Text-to-video / image-to-video |
+| `opencli yollomi edit` | Qwen image edit (prompt + image) |
+| `opencli yollomi upload` | Upload a local file → public URL for other commands |
+| `opencli yollomi models` | List image / video / tool models and credit costs |
+| `opencli yollomi remove-bg` | Remove background (free) |
+| `opencli yollomi upscale` | Image upscaling |
+| `opencli yollomi face-swap` | Face swap between two images |
+| `opencli yollomi restore` | Photo restoration |
+| `opencli yollomi try-on` | Virtual try-on |
+| `opencli yollomi background` | AI background for product/object images |
+| `opencli yollomi object-remover` | Remove objects (image + mask URLs) |
+
+## Usage Examples
+
+```bash
+# List models
+opencli yollomi models --type image
+
+# Text-to-image (default model: z-image-turbo)
+opencli yollomi generate "a red apple on a wooden table"
+
+# Choose model and aspect ratio
+opencli yollomi generate "sunset" --model flux-schnell --ratio 16:9
+
+# Image-to-image: upload first, then pass URL
+opencli yollomi upload ./photo.png
+opencli yollomi generate "oil painting style" --model flux-2-pro --image "https://..."
+
+# Video
+opencli yollomi video "waves on a beach" --model kling-2-1
+
+# Tools
+opencli yollomi remove-bg https://example.com/image.png
+opencli yollomi upscale https://example.com/image.png --scale 4
+opencli yollomi edit https://example.com/in.png "make it vintage"
+```
+
+### Common options
+
+| Option | Applies to | Description |
+|--------|------------|-------------|
+| `--model` | `generate`, `video` | Model id (see `yollomi models`) |
+| `--ratio` | `generate`, `video` | Aspect ratio, e.g. `1:1`, `16:9` |
+| `--image` | `generate`, `video` | Image URL for img2img / i2v |
+| `--output` | Most | Output directory (default `./yollomi-output`) |
+| `--no-download` | Several | Print URLs only, skip saving files |
+
+## Prerequisites
+
+- Chrome running and **logged into** [yollomi.com](https://yollomi.com) (Google OAuth)
+- [Browser Bridge extension](/guide/browser-bridge) installed; daemon connects on first command
+
+The CLI ensures the automation tab is on `yollomi.com` before calling APIs (same-origin `fetch` with session cookies).
+
+## Notes
+
+- **Credits**: Each model consumes account credits; insufficient credits returns HTTP 402.
+- **Upload**: Local paths for tools are not accepted directly — use `yollomi upload` to get a URL, or pass an existing HTTPS image URL.

docs/adapters/browser/youtube.md

@@ -0,0 +1,29 @@
+# YouTube
+
+**Mode**: 🔐 Browser · **Domain**: `youtube.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli youtube search` | |
+| `opencli youtube video` | |
+| `opencli youtube transcript` | |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli youtube search --limit 5
+
+# JSON output
+opencli youtube search -f json
+
+# Verbose mode
+opencli youtube search -v
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** youtube.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/browser/zhihu.md

@@ -0,0 +1,30 @@
+# Zhihu
+
+**Mode**: 🔐 Browser · **Domain**: `zhihu.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli zhihu hot` | |
+| `opencli zhihu search` | |
+| `opencli zhihu question` | |
+| `opencli zhihu download` | |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli zhihu hot --limit 5
+
+# JSON output
+opencli zhihu hot -f json
+
+# Verbose mode
+opencli zhihu hot -v
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** zhihu.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

docs/adapters/desktop/antigravity.md

@@ -0,0 +1,49 @@
+# Antigravity
+
+🔥 **CLI All Electron Apps! The Most Powerful Update Has Arrived!** 🔥
+
+Turn your local Antigravity desktop application into a programmable AI node via Chrome DevTools Protocol (CDP). This allows you to compose complex LLM workflows entirely through the terminal by manipulating the actual UI natively, bypassing any API restrictions.
+
+## Prerequisites
+
+Start the Antigravity desktop app with the Chrome DevTools `remote-debugging-port` flag:
+
+```bash
+# Start Antigravity in the background
+/Applications/Antigravity.app/Contents/MacOS/Electron \
+  --remote-debugging-port=9224
+```
+
+> Depending on your installation, the executable might be named differently, e.g., `Antigravity` instead of `Electron`.
+
+Then set the target port:
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9224"
+```
+
+## Commands
+
+### `opencli antigravity status`
+Check the Chromium CDP connection. Returns the current window title and active internal URL.
+
+### `opencli antigravity send <message>`
+Send a text prompt to the AI. Automatically locates the Lexical editor input box, types the prompt securely, and hits Enter.
+
+### `opencli antigravity read`
+Scrape the entire current conversation history block as pure text.
+
+### `opencli antigravity new`
+Click the "New Conversation" button to instantly clear the UI state and start fresh.
+
+### `opencli antigravity dump`
+Dump the current DOM and snapshot artifacts to `/tmp` for reverse-engineering and selector debugging.
+
+### `opencli antigravity extract-code`
+Extract any multi-line code blocks from the current conversation view. Ideal for automated script extraction (e.g. `opencli antigravity extract-code > script.sh`).
+
+### `opencli antigravity model <name>`
+Quickly target and switch the active LLM engine. Example: `opencli antigravity model claude` or `opencli antigravity model gemini`.
+
+### `opencli antigravity watch`
+A long-running, streaming process that continuously polls the Antigravity UI for chat updates and outputs them in real-time to standard output.

docs/adapters/desktop/chatgpt.md

@@ -0,0 +1,44 @@
+# ChatGPT
+
+Control the **ChatGPT macOS Desktop App** directly from the terminal. OpenCLI supports two automation approaches for ChatGPT.
+
+## Approach 1: AppleScript (Default, No Setup)
+
+The current built-in commands use native AppleScript automation — no extra launch flags needed.
+
+### Prerequisites
+1. Install the official [ChatGPT Desktop App](https://openai.com/chatgpt/mac/) from OpenAI.
+2. Grant **Accessibility permissions** to your terminal app in **System Settings → Privacy & Security → Accessibility**.
+
+### Commands
+- `opencli chatgpt status`: Check if the ChatGPT app is currently running.
+- `opencli chatgpt new`: Activate ChatGPT and press `Cmd+N` to start a new conversation.
+- `opencli chatgpt send "message"`: Copy your message to clipboard, activate ChatGPT, paste, and submit.
+- `opencli chatgpt read`: Read the last visible message from the focused ChatGPT window via the Accessibility tree.
+- `opencli chatgpt ask "message"`: Send a prompt and wait for the visible reply in one shot.
+
+## Approach 2: CDP (Advanced, Electron Debug Mode)
+
+ChatGPT Desktop is also an Electron app and can be launched with a remote debugging port:
+
+```bash
+/Applications/ChatGPT.app/Contents/MacOS/ChatGPT \
+  --remote-debugging-port=9224
+```
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9224"
+```
+
+> The CDP approach is primarily for advanced automation and future desktop-only commands. The built-in command set above still works in the default AppleScript path unless you explicitly route through `OPENCLI_CDP_ENDPOINT`.
+
+## How It Works
+
+- **AppleScript mode**: Uses `osascript` to control ChatGPT, `pbcopy`/`pbpaste` to paste prompts, and the macOS Accessibility tree to read visible chat messages.
+- **CDP mode**: Connects via Chrome DevTools Protocol to the Electron renderer process.
+
+## Limitations
+
+- macOS only (AppleScript dependency)
+- AppleScript mode requires Accessibility permissions
+- `read` returns the last visible message in the focused ChatGPT window — scroll first if the message you want is not visible

docs/adapters/desktop/chatwise.md

@@ -0,0 +1,38 @@
+# ChatWise
+
+Control the **ChatWise Desktop App** from the terminal via Chrome DevTools Protocol (CDP). ChatWise is an Electron-based multi-LLM client supporting GPT-4, Claude, Gemini, and more.
+
+## Prerequisites
+
+1. Install [ChatWise](https://chatwise.app/).
+2. Launch with remote debugging port:
+   ```bash
+   /Applications/ChatWise.app/Contents/MacOS/ChatWise \
+     --remote-debugging-port=9228
+   ```
+
+## Setup
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9228"
+```
+
+## Commands
+
+### Diagnostics
+- `opencli chatwise status`: Check CDP connection status.
+- `opencli chatwise screenshot`: Export DOM + accessibility snapshot.
+
+### Chat
+- `opencli chatwise new`: Start a new conversation (`Cmd+N`).
+- `opencli chatwise send "message"`: Send a message to the active chat.
+- `opencli chatwise read`: Read the current conversation.
+- `opencli chatwise ask "prompt"`: Send + wait for response + return it (one-shot).
+
+### AI Features
+- `opencli chatwise model`: Get the current AI model.
+- `opencli chatwise model gpt-4`: Switch to a different model.
+
+### Organization
+- `opencli chatwise history`: List conversations from the sidebar.
+- `opencli chatwise export`: Export conversation as Markdown.

docs/adapters/desktop/codex.md

@@ -0,0 +1,36 @@
+# Codex
+
+Control the **OpenAI Codex Desktop App** headless or headfully via Chrome DevTools Protocol (CDP). Because Codex is built on Electron, OpenCLI can directly drive its internal UI, automate slash commands, and manipulate its AI agent threads.
+
+## Prerequisites
+
+1. You must have the official OpenAI Codex app installed.
+2. Launch it via the terminal and expose the remote debugging port:
+   ```bash
+   # macOS
+   /Applications/Codex.app/Contents/MacOS/Codex --remote-debugging-port=9222
+   ```
+
+## Setup
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
+```
+
+## Commands
+
+### Diagnostics
+- `opencli codex status`: Checks connection and reads the current active window URL/title.
+- `opencli codex dump`: Dumps the full UI DOM and Accessibility tree into `/tmp`.
+- `opencli codex screenshot`: Captures DOM + snapshot artifacts of the current window.
+
+### Agent Manipulation
+- `opencli codex new`: Simulates `Cmd+N` to start a completely fresh and isolated Git Worktree thread context.
+- `opencli codex send "message"`: Robustly finds the active Thread Composer and injects your text.
+  - *Pro-tip*: You can trigger internal shortcuts, e.g., `opencli codex send "/review"`.
+- `opencli codex ask "message"`: Send + wait + read in one shot.
+- `opencli codex read`: Extracts the entire current thread history and AI reasoning logs.
+- `opencli codex extract-diff`: Automatically scrapes any visual Patch chunks and Code Diffs.
+- `opencli codex model`: Get the currently active AI model.
+- `opencli codex history`: List recent conversation threads from the sidebar.
+- `opencli codex export`: Export the current conversation as Markdown.

docs/adapters/desktop/cursor.md

@@ -0,0 +1,37 @@
+# Cursor
+
+Control the **Cursor IDE** from the terminal via Chrome DevTools Protocol (CDP). Since Cursor is built on Electron (VS Code fork), OpenCLI can drive its internal UI, automate Composer interactions, and manipulate chat sessions.
+
+## Prerequisites
+
+1. Install [Cursor](https://cursor.sh/).
+2. Launch it with the remote debugging port:
+   ```bash
+   /Applications/Cursor.app/Contents/MacOS/Cursor --remote-debugging-port=9226
+   ```
+
+## Setup
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9226"
+```
+
+## Commands
+
+### Diagnostics
+- `opencli cursor status`: Check CDP connection status.
+- `opencli cursor dump`: Dump the full DOM and Accessibility snapshot to `/tmp/cursor-dom.html` and `/tmp/cursor-snapshot.json`.
+- `opencli cursor screenshot`: Capture DOM + snapshot artifacts of the current window.
+
+### Chat Manipulation
+- `opencli cursor new`: Press `Cmd+N` to start a new file/tab.
+- `opencli cursor send "message"`: Inject text into the active Composer/Chat input and submit.
+- `opencli cursor ask "message"`: Send + wait + read in one shot.
+- `opencli cursor read`: Extract the full conversation history from the active chat panel.
+
+### AI Features
+- `opencli cursor composer "prompt"`: Open the Composer panel (`Cmd+I`) and send a prompt for inline AI editing.
+- `opencli cursor model`: Get the currently active AI model (e.g., `claude-4.5-sonnet`).
+- `opencli cursor extract-code`: Extract all code blocks from the current conversation.
+- `opencli cursor history`: List recent chat/composer sessions from the sidebar.
+- `opencli cursor export`: Export the current conversation as Markdown.

docs/adapters/desktop/discord.md

@@ -0,0 +1,28 @@
+# Discord
+
+Control the **Discord Desktop App** from the terminal via Chrome DevTools Protocol (CDP).
+
+## Prerequisites
+
+Launch with remote debugging port:
+```bash
+/Applications/Discord.app/Contents/MacOS/Discord --remote-debugging-port=9232
+```
+
+## Setup
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9232"
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli discord-app status` | Check CDP connection |
+| `opencli discord-app send "message"` | Send a message in the active channel |
+| `opencli discord-app read` | Read recent messages |
+| `opencli discord-app channels` | List channels in the current server |
+| `opencli discord-app servers` | List all joined servers |
+| `opencli discord-app search "query"` | Search messages (Cmd+F) |
+| `opencli discord-app members` | List online members |

docs/adapters/desktop/doubao-app.md

@@ -0,0 +1,35 @@
+# Doubao App (豆包桌面版)
+
+Control the **Doubao AI Desktop App** via Chrome DevTools Protocol (CDP).
+
+## Prerequisites
+
+1. Launch Doubao Desktop with remote debugging enabled:
+   ```bash
+   /Applications/Doubao.app/Contents/MacOS/Doubao --remote-debugging-port=9225
+   ```
+2. Set the CDP endpoint:
+   ```bash
+   export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9225"
+   ```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli doubao-app status` | Check CDP connection status |
+| `opencli doubao-app new` | Start a new conversation |
+| `opencli doubao-app send "message"` | Send a message to the current chat |
+| `opencli doubao-app read` | Read the latest assistant reply |
+| `opencli doubao-app ask "message"` | Send a prompt and wait for the reply |
+| `opencli doubao-app screenshot` | Capture a screenshot of the app window |
+| `opencli doubao-app dump` | Export DOM and snapshot debug info |
+
+## How It Works
+
+Connects to the Doubao Electron app via CDP, injecting JavaScript into the renderer process to control the chat UI — sending messages, reading replies, and capturing screenshots.
+
+## Limitations
+
+- Requires Doubao Desktop to be launched with `--remote-debugging-port`
+- macOS / Linux / Windows (Electron-based, platform independent)

docs/adapters/desktop/notion.md

@@ -0,0 +1,29 @@
+# Notion
+
+Control the **Notion Desktop App** from the terminal via Chrome DevTools Protocol (CDP).
+
+## Prerequisites
+
+Launch with remote debugging port:
+```bash
+/Applications/Notion.app/Contents/MacOS/Notion --remote-debugging-port=9230
+```
+
+## Setup
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9230"
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli notion status` | Check CDP connection |
+| `opencli notion search "query"` | Quick Find search (Cmd+P) |
+| `opencli notion read` | Read the current page content |
+| `opencli notion new "title"` | Create a new page (Cmd+N) |
+| `opencli notion write "text"` | Append text to the current page |
+| `opencli notion sidebar` | List pages from the sidebar |
+| `opencli notion favorites` | List pages from the Favorites section |
+| `opencli notion export` | Export page as Markdown |

docs/adapters/index.md

@@ -0,0 +1,71 @@
+# All Adapters
+
+Run `opencli list` for the live registry.
+
+## Browser Adapters
+
+| Site | Commands | Mode |
+|------|----------|------|
+| **[twitter](/adapters/browser/twitter)** | `trending` `bookmarks` `profile` `search` `timeline` `thread` `following` `followers` `notifications` `post` `reply` `delete` `like` `article` `follow` `unfollow` `bookmark` `unbookmark` `download` `accept` `reply-dm` `block` `unblock` `hide-reply` | 🔐 Browser |
+| **[reddit](/adapters/browser/reddit)** | `hot` `frontpage` `popular` `search` `subreddit` `read` `user` `user-posts` `user-comments` `upvote` `save` `comment` `subscribe` `saved` `upvoted` | 🔐 Browser |
+| **[bilibili](/adapters/browser/bilibili)** | `hot` `search` `me` `favorite` `history` `feed` `subtitle` `dynamic` `ranking` `following` `user-videos` `download` | 🔐 Browser |
+| **[zhihu](/adapters/browser/zhihu)** | `hot` `search` `question` `download` | 🔐 Browser |
+| **[xiaohongshu](/adapters/browser/xiaohongshu)** | `search` `notifications` `feed` `user` `download` `publish` `creator-notes` `creator-note-detail` `creator-notes-summary` `creator-profile` `creator-stats` | 🔐 Browser |
+| **[xueqiu](/adapters/browser/xueqiu)** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` `earnings-date` | 🔐 Browser |
+| **[youtube](/adapters/browser/youtube)** | `search` `video` `transcript` | 🔐 Browser |
+| **[v2ex](/adapters/browser/v2ex)** | `hot` `latest` `topic` `node` `user` `member` `replies` `nodes` `daily` `me` `notifications` | 🌐 / 🔐 |
+| **[bloomberg](/adapters/browser/bloomberg)** | `main` `markets` `economics` `industries` `tech` `politics` `businessweek` `opinions` `feeds` `news` | 🌐 / 🔐 |
+| **[weibo](/adapters/browser/weibo)** | `hot` `search` | 🔐 Browser |
+| **[linkedin](/adapters/browser/linkedin)** | `search` `timeline` | 🔐 Browser |
+| **[coupang](/adapters/browser/coupang)** | `search` `add-to-cart` | 🔐 Browser |
+| **[boss](/adapters/browser/boss)** | `search` `detail` `recommend` `joblist` `greet` `batchgreet` `send` `chatlist` `chatmsg` `invite` `mark` `exchange` `resume` `stats` | 🔐 Browser |
+| **[ctrip](/adapters/browser/ctrip)** | `search` | 🔐 Browser |
+| **[reuters](/adapters/browser/reuters)** | `search` | 🔐 Browser |
+| **[smzdm](/adapters/browser/smzdm)** | `search` | 🔐 Browser |
+| **[jike](/adapters/browser/jike)** | `feed` `search` `post` `topic` `user` `create` `comment` `like` `repost` `notifications` | 🔐 Browser |
+| **[jimeng](/adapters/browser/jimeng)** | `generate` `history` | 🔐 Browser |
+| **[yollomi](/adapters/browser/yollomi)** | `generate` `video` `edit` `upload` `models` `remove-bg` `upscale` `face-swap` `restore` `try-on` `background` `object-remover` | 🔐 Browser |
+| **[linux-do](/adapters/browser/linux-do)** | `hot` `latest` `categories` `category` `search` `topic` | 🔐 Browser |
+| **[chaoxing](/adapters/browser/chaoxing)** | `assignments` `exams` | 🔐 Browser |
+| **[grok](/adapters/browser/grok)** | `ask` | 🔐 Browser |
+| **[doubao](/adapters/browser/doubao)** | `status` `new` `send` `read` `ask` | 🔐 Browser |
+| **[weread](/adapters/browser/weread)** | `shelf` `search` `book` `ranking` `notebooks` `highlights` `notes` | 🔐 Browser |
+| **[douban](/adapters/browser/douban)** | `search` `top250` `subject` `marks` `reviews` `movie-hot` `book-hot` | 🔐 Browser |
+| **[facebook](/adapters/browser/facebook)** | `feed` `profile` `search` `friends` `groups` `events` `notifications` `memories` `add-friend` `join-group` | 🔐 Browser |
+| **[instagram](/adapters/browser/instagram)** | `explore` `profile` `search` `user` `followers` `following` `follow` `unfollow` `like` `unlike` `comment` `save` `unsave` `saved` | 🔐 Browser |
+| **[medium](/adapters/browser/medium)** | `feed` `search` `user` | 🔐 Browser |
+| **[sinablog](/adapters/browser/sinablog)** | `hot` `search` `article` `user` | 🔐 Browser |
+| **[substack](/adapters/browser/substack)** | `feed` `search` `publication` | 🔐 Browser |
+| **[tiktok](/adapters/browser/tiktok)** | `explore` `search` `profile` `user` `following` `follow` `unfollow` `like` `unlike` `comment` `save` `unsave` `live` `notifications` `friends` | 🔐 Browser |
+
+## Public API Adapters
+
+| Site | Commands | Mode |
+|------|----------|------|
+| **[hackernews](/adapters/browser/hackernews)** | `top` `new` `best` `ask` `show` `jobs` `search` `user` | 🌐 Public |
+| **[bbc](/adapters/browser/bbc)** | `news` | 🌐 Public |
+| **[devto](/adapters/browser/devto)** | `top` `tag` `user` | 🌐 Public |
+| **[dictionary](/adapters/browser/dictionary)** | `search` `synonyms` `examples` | 🌐 Public |
+| **[apple-podcasts](/adapters/browser/apple-podcasts)** | `search` `episodes` `top` | 🌐 Public |
+| **[xiaoyuzhou](/adapters/browser/xiaoyuzhou)** | `podcast` `podcast-episodes` `episode` | 🌐 Public |
+| **[yahoo-finance](/adapters/browser/yahoo-finance)** | `quote` | 🌐 Public |
+| **[arxiv](/adapters/browser/arxiv)** | `search` `paper` | 🌐 Public |
+| **[barchart](/adapters/browser/barchart)** | `quote` `options` `greeks` `flow` | 🌐 Public |
+| **[hf](/adapters/browser/hf)** | `top` | 🌐 Public |
+| **[sinafinance](/adapters/browser/sinafinance)** | `news` | 🌐 Public |
+| **[stackoverflow](/adapters/browser/stackoverflow)** | `hot` `search` `bounties` `unanswered` | 🌐 Public |
+| **[wikipedia](/adapters/browser/wikipedia)** | `search` `summary` `random` `trending` | 🌐 Public |
+| **[lobsters](/adapters/browser/lobsters)** | `hot` `newest` `active` `tag` | 🌐 Public |
+
+## Desktop Adapters
+
+| App | Description | Commands |
+|-----|-------------|----------|
+| **[Cursor](/adapters/desktop/cursor)** | Control Cursor IDE | `status` `send` `read` `new` `dump` `composer` `model` `extract-code` `ask` `screenshot` `history` `export` |
+| **[Codex](/adapters/desktop/codex)** | Drive OpenAI Codex CLI agent | `status` `send` `read` `new` `extract-diff` `model` `ask` `screenshot` `history` `export` |
+| **[Antigravity](/adapters/desktop/antigravity)** | Control Antigravity Ultra | `status` `send` `read` `new` `dump` `extract-code` `model` `watch` |
+| **[ChatGPT](/adapters/desktop/chatgpt)** | Automate ChatGPT macOS app | `status` `new` `send` `read` `ask` |
+| **[ChatWise](/adapters/desktop/chatwise)** | Multi-LLM client | `status` `new` `send` `read` `ask` `model` `history` `export` `screenshot` |
+| **[Notion](/adapters/desktop/notion)** | Search, read, write pages | `status` `search` `read` `new` `write` `sidebar` `favorites` `export` |
+| **[Discord](/adapters/desktop/discord)** | Desktop messages & channels | `status` `send` `read` `channels` `servers` `search` `members` |
+| **[Doubao App](/adapters/desktop/doubao-app)** | Doubao AI desktop app via CDP | `status` `new` `send` `read` `ask` `screenshot` `dump` |

docs/advanced/cdp.md

@@ -0,0 +1,103 @@
+# Connecting OpenCLI via CDP (Remote/Headless Servers)
+
+If you cannot use the opencli Browser Bridge extension (e.g., in a remote headless server environment without a UI), OpenCLI provides an alternative: connecting directly to Chrome via **CDP (Chrome DevTools Protocol)**.
+
+Because CDP binds to `localhost` by default for security reasons, accessing it from a remote server requires an additional networking tunnel.
+
+This guide is broken down into three phases:
+1. **Preparation**: Start Chrome with CDP enabled locally.
+2. **Network Tunnels**: Expose that CDP port to your remote server using either **SSH Tunnels** or **Reverse Proxies**.
+3. **Execution**: Run OpenCLI on your server.
+
+---
+
+## Phase 1: Preparation (Local Machine)
+
+First, you need to start a Chrome browser on your local machine with remote debugging enabled.
+
+**macOS:**
+```bash
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir="$HOME/chrome-debug-profile" \
+  --remote-allow-origins="*"
+```
+
+**Linux:**
+```bash
+google-chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir="$HOME/chrome-debug-profile" \
+  --remote-allow-origins="*"
+```
+
+**Windows:**
+```cmd
+"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
+  --remote-debugging-port=9222 ^
+  --user-data-dir="%USERPROFILE%\chrome-debug-profile" ^
+  --remote-allow-origins="*"
+```
+
+> **Note**: The `--remote-allow-origins="*"` flag is often required for modern Chrome versions to accept cross-origin CDP WebSocket connections (e.g. from reverse proxies like ngrok).
+
+Once this browser instance opens, **log into the target websites you want to use** (e.g., bilibili.com, zhihu.com) so that the session contains the correct cookies.
+
+---
+
+## Phase 2: Remote Access Methods
+
+Once CDP is running locally on port `9222`, you must securely expose this port to your remote server. Choose one of the two methods below depending on your network conditions.
+
+### Method A: SSH Tunnel (Recommended)
+
+If your local machine has SSH access to the remote server, this is the most secure and straightforward method.
+
+Run this command on your **Local Machine** to forward the remote server's port `9222` back to your local port `9222`:
+
+```bash
+ssh -R 9222:localhost:9222 your-server-user@your-server-ip
+```
+
+Leave this SSH session running in the background.
+
+### Method B: Reverse Proxy (ngrok / frp / socat)
+
+If you cannot establish a direct SSH connection (e.g., due to NAT or firewalls), you can use an intranet penetration tool like `ngrok`.
+
+Run this command on your **Local Machine** to expose your local port `9222` to the public internet securely via ngrok:
+
+```bash
+ngrok http 9222
+```
+
+This will print a forwarding URL, such as `https://abcdef.ngrok.app`. **Copy this URL**.
+
+---
+
+## Phase 3: Execution (Remote Server)
+
+Now switch to your **Remote Server** where OpenCLI is installed. 
+
+Depending on the network tunnel method you chose in Phase 2, set the `OPENCLI_CDP_ENDPOINT` environment variable and run your commands.
+
+### If you used Method A (SSH Tunnel):
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://localhost:9222"
+opencli doctor                    # Verify connection
+opencli bilibili hot --limit 5    # Test a command
+```
+
+### If you used Method B (Reverse Proxy like ngrok):
+
+```bash
+# Use the URL you copied from ngrok earlier
+export OPENCLI_CDP_ENDPOINT="https://abcdef.ngrok.app"
+opencli doctor                    # Verify connection
+opencli bilibili hot --limit 5    # Test a command
+```
+
+> *Tip: If you provide a standard HTTP/HTTPS CDP endpoint, OpenCLI requests the `/json` target list and picks the most likely inspectable app/page target automatically. If multiple app targets exist, you can further narrow selection with `OPENCLI_CDP_TARGET` (for example `antigravity` or `codex`).*
+
+If you plan to use this setup frequently, you can persist the environment variable by adding the `export` line to your `~/.bashrc` or `~/.zshrc` on the server.

docs/advanced/download.md

@@ -0,0 +1,67 @@
+# 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 |
+| **weixin** | Articles (Markdown) | Exports WeChat Official Account articles |
+
+## Prerequisites
+
+For video downloads from streaming platforms, 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
+
+# Download Twitter media from user
+opencli twitter download 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 "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
+
+# Export with local images
+opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --download-images
+
+# Export WeChat article to Markdown
+opencli weixin download --url "https://mp.weixin.qq.com/s/xxx" --output ./weixin
+```
+
+## Pipeline Step (YAML Adapters)
+
+The `download` step can be used in YAML pipelines:
+
+::: v-pre
+```yaml
+pipeline:
+  - fetch: https://api.example.com/media
+  - download:
+      url: ${{ item.imageUrl }}
+      dir: ./downloads
+      filename: ${{ item.title | sanitize }}.jpg
+      concurrency: 5
+      skip_existing: true
+```
+:::

docs/advanced/electron.md

@@ -0,0 +1,125 @@
+---
+description: How to CLI-ify and automate any Electron Desktop Application via CDP
+---
+
+# CLI-ifying Electron Applications (Skill Guide)
+
+Based on the successful automation of **Cursor**, **Codex**, **Antigravity**, **ChatWise**, **Notion**, and **Discord** desktop apps, this guide serves as the standard operating procedure (SOP) for adapting ANY Electron-based application into an OpenCLI adapter.
+
+## Core Concept
+
+Electron apps are essentially local Chromium browser instances. By exposing a debugging port (CDP — Chrome DevTools Protocol) at launch time, we can use the Browser Bridge to pierce through the UI layer, accessing and controlling all underlying state including React/Vue components and Shadow DOM.
+
+> **Note:** Not all desktop apps are Electron. WeChat (native Cocoa) and Feishu/Lark (custom Lark Framework) embed Chromium but do NOT expose CDP. For those apps, use the AppleScript + clipboard approach instead (see [Non-Electron Pattern](#non-electron-pattern-applescript)).
+
+### Launching the Target App
+```bash
+/Applications/AppName.app/Contents/MacOS/AppName --remote-debugging-port=9222
+```
+
+### Verifying Electron
+```bash
+# Check for Electron Framework in the app bundle
+ls /Applications/AppName.app/Contents/Frameworks/Electron\ Framework.framework
+# If this directory exists → Electron → CDP works
+# If not → check for libEGL.dylib (embedded Chromium/CEF, CDP may not work)
+```
+
+## The 5-Command Pattern (CDP / Electron)
+
+Every new Electron adapter should implement these 5 commands in `src/clis/<app_name>/`:
+
+### 1. `status.ts` — Connection Test
+```typescript
+export const statusCommand = cli({
+  site: 'myapp',
+  name: 'status',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,       // Requires CDP connection
+  args: [],
+  columns: ['Status', 'Url', 'Title'],
+  func: async (page: IPage) => {
+    const url = await page.evaluate('window.location.href');
+    const title = await page.evaluate('document.title');
+    return [{ Status: 'Connected', Url: url, Title: title }];
+  },
+});
+```
+
+### 2. `dump.ts` — Reverse Engineering Core
+Modern app DOMs are huge and obfuscated. **Never guess selectors.** Dump first, then extract precise class names with AI or `grep`:
+```typescript
+const dom = await page.evaluate('document.body.innerHTML');
+fs.writeFileSync('/tmp/app-dom.html', dom);
+const snap = await page.snapshot({ interactive: false });
+fs.writeFileSync('/tmp/app-snapshot.json', JSON.stringify(snap, null, 2));
+```
+
+### 3. `send.ts` — Advanced Text Injection
+Electron apps often use complex rich-text editors (Monaco, Lexical, ProseMirror). Setting `.value` directly is ignored by React state.
+
+**Best practice:** Use `document.execCommand('insertText')` to perfectly simulate real user input, fully piercing React state:
+```javascript
+const composer = document.querySelector('[contenteditable="true"]');
+composer.focus();
+document.execCommand('insertText', false, 'Hello');
+```
+Then submit with `await page.pressKey('Enter')`.
+
+### 4. `read.ts` — Context Extraction
+Don't extract the entire page text. Use `dump.ts` output to find the real "conversation container":
+- Look for semantic selectors: `[role="log"]`, `[data-testid="conversation"]`, `[data-content-search-turn-key]`
+- Format output as Markdown — readable by both humans and LLMs
+
+### 5. `new.ts` — Keyboard Shortcuts
+Many GUI actions respond to native shortcuts rather than button clicks:
+```typescript
+const isMac = process.platform === 'darwin';
+await page.pressKey(isMac ? 'Meta+N' : 'Control+N');
+await page.wait(1); // Wait for re-render
+```
+
+## Environment Variable
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
+```
+
+## Non-Electron Pattern (AppleScript)
+
+For native macOS apps (WeChat, Feishu) that don't expose CDP:
+```typescript
+export const statusCommand = cli({
+  site: 'myapp',
+  strategy: Strategy.PUBLIC,
+  browser: false,       // No browser needed
+  func: async (page: IPage | null) => {
+    const output = execSync("osascript -e 'application \"MyApp\" is running'", { encoding: 'utf-8' }).trim();
+    return [{ Status: output === 'true' ? 'Running' : 'Stopped' }];
+  },
+});
+```
+
+Core techniques:
+- **status**: `osascript -e 'application "AppName" is running'`
+- **send**: `pbcopy` → activate window → `Cmd+V` → `Enter`
+- **read**: `Cmd+A` → `Cmd+C` → `pbpaste`
+- **search**: Activate → `Cmd+F`/`Cmd+K` → `keystroke "query"`
+
+## Pitfalls & Gotchas
+
+1. **Port conflicts (EADDRINUSE)**: Only one app per port. Use unique ports: Codex=9222, ChatGPT=9224, Cursor=9226, ChatWise=9228, Notion=9230, Discord=9232
+2. **IPage abstraction**: OpenCLI wraps the browser page as `IPage` (`src/types.ts`). Use `page.pressKey()` and `page.evaluate()`, NOT direct DOM APIs
+3. **Timing**: Always add `await page.wait(0.5)` to `1.0` after DOM mutations. Returning too early disconnects prematurely
+4. **AppleScript requires Accessibility**: Terminal app must be granted permission in System Settings → Privacy & Security → Accessibility
+
+## Port Assignment Table
+
+| App | Port | Mode |
+|-----|------|------|
+| Codex | 9222 | CDP |
+| ChatGPT | 9224 | CDP / AppleScript |
+| Cursor | 9226 | CDP |
+| ChatWise | 9228 | CDP |
+| Notion | 9230 | CDP |
+| Discord App | 9232 | CDP |

docs/advanced/remote-chrome.md

@@ -0,0 +1,72 @@
+# Remote Chrome
+
+Run OpenCLI on a server or headless environment by connecting to a remote Chrome instance.
+
+## Use Cases
+
+- Running CLI commands on a remote server
+- CI/CD automation with headed browser
+- Shared team browser sessions
+
+## Setup
+
+### 1. Start Chrome on the Remote Machine
+
+```bash
+# On the remote machine (or your Mac)
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222
+```
+
+### 2. SSH Tunnel (If Needed)
+
+If the remote Chrome is on a different machine, create an SSH tunnel:
+
+```bash
+# On your local machine or server
+ssh -L 9222:127.0.0.1:9222 user@remote-host
+```
+
+::: warning
+Use `127.0.0.1` instead of `localhost` in the SSH command to avoid IPv6 resolution issues that can cause timeouts.
+:::
+
+### 3. Configure OpenCLI
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
+```
+
+### 4. Verify
+
+```bash
+# Test the connection
+curl http://127.0.0.1:9222/json/version
+
+# Run a diagnostic
+opencli doctor
+```
+
+## CI/CD Integration
+
+For CI/CD environments, use a real Chrome instance with `xvfb`:
+
+::: v-pre
+```yaml
+steps:
+  - uses: browser-actions/setup-chrome@latest
+    id: setup-chrome
+  - run: |
+      xvfb-run --auto-servernum \
+        ${{ steps.setup-chrome.outputs.chrome-path }} \
+        --remote-debugging-port=9222 &
+```
+:::
+
+Set the browser executable path:
+::: v-pre
+```yaml
+env:
+  OPENCLI_BROWSER_EXECUTABLE_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}
+```
+:::

docs/comparison.md

@@ -0,0 +1,125 @@
+# Comparison Guide
+
+OpenCLI occupies a specific niche in the browser automation ecosystem. This guide honestly evaluates where opencli excels, where it's a viable option, and where other tools are a better fit.
+
+## At a Glance
+
+| Tool | Approach | Best for |
+|------|----------|----------|
+| **opencli** | Pre-built adapters (YAML/TS) | Deterministic site commands, broad platform coverage, desktop apps |
+| **Browser-Use** | LLM-driven browser control | General-purpose AI browser automation |
+| **Crawl4AI** | Async web crawler | Large-scale data crawling |
+| **Firecrawl** | Scraping API / self-hosted | Clean markdown extraction, managed or self-hosted infrastructure |
+| **agent-browser** | Browser primitive CLI | Token-efficient AI agent browsing |
+| **Stagehand** | AI browser framework | Developer-friendly browser automation |
+| **Skyvern** | Visual AI automation | Cross-site generalized workflows |
+
+## Scenario Comparison
+
+### 1. Scheduled Batch Data Extraction
+
+> "I want to pull trending posts from Bilibili/Reddit/HackerNews every hour into my pipeline."
+
+| Tool | Fit | Notes |
+|------|-----|-------|
+| **opencli** | Best | One command, structured JSON output, zero runtime cost. Runs in cron/CI without tokens or API keys. |
+| Crawl4AI | Good | Strong for large-scale crawling, but requires writing extraction logic per site. |
+| Firecrawl | Viable | Managed service with clean output, but costs scale with volume. |
+| Browser-Use / Stagehand | Poor | LLM inference on every run is slow, expensive, and non-deterministic for repeated tasks. |
+
+**Why opencli wins here:** A command like `opencli bilibili hot -f json` returns the same structured schema every time, costs nothing to run, and finishes in seconds. For recurring data extraction from known sites, pre-built adapters beat LLM-driven approaches on cost, speed, and reliability.
+
+### 2. AI Agent Site Operations
+
+> "My AI agent needs to search Twitter, read Reddit threads, or post to Xiaohongshu."
+
+| Tool | Fit | Notes |
+|------|-----|-------|
+| **opencli** | Best | Structured JSON output, fast deterministic execution, hundreds of commands ready to use. |
+| agent-browser | Good | Token-efficient browser primitives, but requires LLM reasoning for every step. |
+| Browser-Use | Viable | General-purpose, but each operation costs tokens and takes 10-60s. |
+| Stagehand | Viable | Good DX, but same LLM-per-action cost model. |
+
+**Why opencli wins here:** When your agent needs `twitter search "AI news" -f json`, a deterministic command that returns in seconds is strictly better than an LLM clicking through a webpage. The agent saves tokens for reasoning, not navigation.
+
+### 3. Authenticated Operations (Login-Required Sites)
+
+> "I need to access my bookmarks, post content, or interact with sites that require login."
+
+| Tool | Fit | Notes |
+|------|-----|-------|
+| **opencli** | Best | Reuses your Chrome login session via Browser Bridge. No credentials stored or transmitted. |
+| Browser-Use | Viable | Can use browser profiles, but credential management is manual. |
+| Firecrawl | Poor | Cloud service cannot access your authenticated sessions. |
+| Crawl4AI | Poor | Requires manual cookie/session injection. |
+
+**Why opencli wins here:** The Browser Bridge extension reuses your existing Chrome login state in real-time. You log in once in Chrome, and opencli commands work immediately. No OAuth setup, no API keys, no credential files.
+
+### 4. General Web Browsing & Exploration
+
+> "I need to explore an unknown website, fill forms, or navigate complex multi-step flows."
+
+| Tool | Fit | Notes |
+|------|-----|-------|
+| Browser-Use | Best | LLM-driven, handles arbitrary websites and flows. |
+| Stagehand | Best | Clean API for `act()`, `extract()`, `observe()` on any page. |
+| agent-browser | Good | Token-efficient primitives for AI agents. |
+| Skyvern | Good | Visual AI that generalizes across sites. |
+| **opencli** | Poor | Only works with sites that have pre-built adapters. Cannot handle arbitrary websites. |
+
+**opencli is not the right tool here.** If you need to explore unknown websites or handle one-off tasks on sites without adapters, use an LLM-driven browser tool. opencli trades generality for determinism and cost.
+
+### 5. Desktop App Control
+
+> "I want to script Cursor, ChatGPT, Notion, or other Electron apps from the terminal."
+
+| Tool | Fit | Notes |
+|------|-----|-------|
+| **opencli** | Best | 8 desktop adapters via CDP + AppleScript. The only CLI tool with this capability. |
+| All others | N/A | Browser automation tools cannot control desktop applications. |
+
+**This is unique to opencli.** No other tool in this comparison can send a prompt to ChatGPT desktop, extract code from Cursor, or write to Notion pages via CLI.
+
+## Key Trade-offs
+
+### opencli's Strengths
+
+- **Zero LLM cost** — No tokens consumed at runtime. Run 10,000 times for free.
+- **Deterministic output** — Same command always returns the same schema. Pipeable, scriptable, CI-friendly.
+- **Speed** — Adapter commands return in seconds, not minutes.
+- **Broad platform coverage** — 50+ sites spanning global platforms (Reddit, HackerNews, Twitter, YouTube) and Chinese platforms (Bilibili, Zhihu, Xiaohongshu, Douban, Weibo) with adapters that understand local anti-bot patterns.
+- **Desktop app control** — CDP adapters for Cursor, Codex, Notion, ChatGPT, Discord, and more.
+- **Easy to extend** — Drop a `.yaml` or `.ts` adapter into the `clis/` folder for auto-registration. Contributing a new site adapter is straightforward.
+
+### opencli's Limitations
+
+- **Coverage requires adapters** — opencli only works with sites that have pre-built adapters. Adding a new site means writing a YAML or TypeScript adapter.
+- **Adapter maintenance** — When a website updates its DOM or API, the corresponding adapter may need updating. The community maintains these, but breakage is possible.
+- **Not general-purpose** — Cannot handle arbitrary websites. For unknown sites, pair opencli with a general browser tool as a fallback.
+
+## Complementary Usage
+
+opencli works best alongside general-purpose browser tools, not as a replacement:
+
+```
+Has adapter?  ──yes──▶  opencli (fast, free, deterministic)
+     │
+     no
+     │
+     ▼
+One-off task?  ──yes──▶  Browser-Use / Stagehand (LLM-driven)
+     │
+     no
+     │
+     ▼
+Recurring?    ──yes──▶  Write an opencli adapter, then use opencli
+```
+
+## Further Reading
+
+- [Architecture Overview](./developer/architecture.md)
+- [Writing a YAML Adapter](./developer/yaml-adapter.md)
+- [Writing a TypeScript Adapter](./developer/ts-adapter.md)
+- [Testing Guide](./developer/testing.md)
+- [AI Workflow](./developer/ai-workflow.md)
+- [Contributing Guide](./developer/contributing.md)

docs/developer/ai-workflow.md

@@ -0,0 +1,66 @@
+# AI Workflow
+
+OpenCLI is designed with AI agents in mind. This guide covers the AI-native discovery and code generation tools.
+
+## Quick Mode (One-Shot)
+
+Generate a single command for a specific page URL — just a URL + one-line goal, 4 steps done:
+
+```bash
+opencli generate https://example.com --goal "trending"
+```
+
+This runs: explore → synthesize → register in one shot.
+
+For the complete one-shot workflow details, see [CLI-ONESHOT.md](https://github.com/jackwener/opencli/blob/main/CLI-ONESHOT.md).
+
+## Full Mode (Explorer Workflow)
+
+### Step 1: Deep Explore
+
+Discover APIs, infer capabilities, and detect framework:
+
+```bash
+opencli explore https://example.com --site mysite
+```
+
+Outputs to `.opencli/explore/<site>/`:
+- `manifest.json` — Site metadata
+- `endpoints.json` — Discovered API endpoints
+- `capabilities.json` — Inferred capabilities
+- `auth.json` — Authentication strategy details
+
+### Step 2: Synthesize
+
+Generate YAML adapters from explore artifacts:
+
+```bash
+opencli synthesize mysite
+```
+
+### Step 3: Strategy Cascade
+
+Auto-probe authentication strategies: `PUBLIC → COOKIE → HEADER`:
+
+```bash
+opencli cascade https://api.example.com/data
+```
+
+### Step 4: Validate & Test
+
+```bash
+opencli validate                           # Validate generated YAML
+opencli <site> <command> --limit 3 -f json # Test the command
+```
+
+## 5-Tier Authentication Strategy
+
+The explorer uses a decision tree to determine the best authentication approach:
+
+1. **PUBLIC** — No auth, direct API call
+2. **COOKIE** — Reuse Chrome session cookies
+3. **HEADER** — Custom auth headers
+4. **BROWSER** — Full browser automation
+5. **CDP** — Chrome DevTools Protocol for Electron apps
+
+For the complete browser exploration workflow and debugging guide, see [CLI-EXPLORER.md](https://github.com/jackwener/opencli/blob/main/CLI-EXPLORER.md).

docs/developer/architecture.md

@@ -0,0 +1,103 @@
+# Architecture
+
+OpenCLI is built on a **Dual-Engine Architecture** that supports both declarative YAML pipelines and programmatic TypeScript adapters.
+
+## High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                     opencli CLI                      │
+│              (Commander.js entry point)               │
+├─────────────────────────────────────────────────────┤
+│                   Engine Layer                        │
+│  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
+│  │   Registry   │  │   Dynamic    │  │   Output   │ │
+│  │  (commands)  │  │   Loader     │  │ Formatter  │ │
+│  └──────────────┘  └──────────────┘  └────────────┘ │
+├─────────────────────────────────────────────────────┤
+│                 Adapter Layer                         │
+│  ┌─────────────────┐  ┌──────────────────────────┐  │
+│  │  YAML Pipeline  │  │  TypeScript Adapters     │  │
+│  │  (declarative)  │  │  (browser/desktop/AI)    │  │
+│  └─────────────────┘  └──────────────────────────┘  │
+├─────────────────────────────────────────────────────┤
+│              Connection Layer                         │
+│  ┌─────────────────┐  ┌──────────────────────────┐  │
+│  │ Browser Bridge  │  │  CDP (Chrome DevTools)   │  │
+│  │ (Extension+WS)  │  │  (Electron apps)         │  │
+│  └─────────────────┘  └──────────────────────────┘  │
+└─────────────────────────────────────────────────────┘
+```
+
+## Core Modules
+
+### Registry (`src/registry.ts`)
+Central command registry. All adapters register their commands via the `cli()` function with metadata: site, name, description, domain, strategy, args, columns.
+
+### Discovery (`src/discovery.ts`)
+CLI discovery and manifest loading. Discovers commands from YAML and TypeScript adapter files, parses YAML pipelines, and registers them into the central registry.
+
+### Execution (`src/execution.ts`)
+Command execution: argument validation, lazy loading of adapter modules, and executing the appropriate handler function.
+
+### Commander Adapter (`src/commanderAdapter.ts`)
+Bridges the Registry commands to Commander.js subcommands. Handles positional args, named options, browser session wiring, and output formatting. Isolates all Commander-specific logic so the core is framework-agnostic.
+
+### Browser (`src/browser.ts`)
+Manages connections to Chrome via the Browser Bridge WebSocket daemon. Handles JSON-RPC messaging, tab management, and extension/standalone mode switching.
+
+### Pipeline (`src/pipeline/`)
+The YAML pipeline engine. Processes declarative steps:
+- **fetch** — HTTP requests with cookie/header strategies
+- **map** — Data transformation with template expressions
+- **limit** — Result truncation
+- **filter** — Conditional filtering
+- **download** — Media download support
+
+### Output (`src/output.ts`)
+Unified output formatting: `table`, `json`, `yaml`, `md`, `csv`.
+
+## Authentication Strategies
+
+OpenCLI uses a 3-tier authentication strategy:
+
+| Strategy | How It Works | When to Use |
+|----------|-------------|-------------|
+| `public` | Direct HTTP fetch, no auth | Public APIs (HackerNews, BBC) |
+| `cookie` | Reuse Chrome cookies via Browser Bridge | Logged-in sites (Bilibili, Zhihu) |
+| `header` | Custom auth headers | API-key based services |
+| `intercept` | Network request interception | GraphQL/XHR capture (Twitter) |
+| `ui` | DOM interaction via accessibility snapshot | Desktop apps, write operations |
+
+## Directory Structure
+
+```
+src/
+├── main.ts              # Entry point
+├── cli.ts               # Commander.js CLI setup + built-in commands
+├── commanderAdapter.ts  # Registry → Commander bridge
+├── discovery.ts         # CLI discovery, manifest loading, YAML parsing
+├── execution.ts         # Arg validation, command execution
+├── registry.ts          # Command registry
+├── serialization.ts     # Command serialization helpers
+├── runtime.ts           # Browser session & timeout management
+├── browser/             # Browser Bridge connection
+├── output.ts            # Output formatting
+├── doctor.ts            # Diagnostic tool
+├── pipeline/            # YAML pipeline engine
+│   ├── runner.ts
+│   ├── template.ts
+│   ├── transform.ts
+│   └── steps/
+│       ├── fetch.ts
+│       ├── map.ts
+│       ├── limit.ts
+│       ├── filter.ts
+│       └── download.ts
+└── clis/                # Site adapters
+    ├── twitter/
+    ├── reddit/
+    ├── bilibili/
+    ├── cursor/
+    └── ...
+```

docs/developer/contributing.md

@@ -0,0 +1,138 @@
+# Contributing
+
+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
+npm test
+npm run test:adapter
+
+# 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`:
+
+::: v-pre
+```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`](https://github.com/jackwener/opencli/blob/main/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;
+    // ... browser automation logic
+    return data.slice(0, Number(limit)).map((item: any) => ({
+      title: item.title,
+      url: item.url,
+      date: item.created_at,
+    }));
+  },
+});
+```
+
+### Validate Your Adapter
+
+```bash
+opencli validate               # Validate YAML syntax and schema
+opencli <site> <command> --limit 3 -f json   # Test your command
+opencli <site> <command> -v    # Verbose mode for debugging
+```
+
+## 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
+```
+
+## 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:
+   ```bash
+   npx tsc --noEmit           # Type check
+   npm test                   # Core unit tests
+   npm run test:adapter       # Focused adapter tests (if adapter logic changed)
+   opencli validate           # YAML validation (if applicable)
+   ```
+4. Commit using conventional commit format
+5. Push and open a PR

docs/developer/testing.md

@@ -0,0 +1,261 @@
+# Testing Guide
+
+> 面向开发者和 AI Agent 的测试参考手册。
+
+## 目录
+
+- [测试架构](#测试架构)
+- [当前覆盖范围](#当前覆盖范围)
+- [本地运行测试](#本地运行测试)
+- [如何添加新测试](#如何添加新测试)
+- [CI/CD 流水线](#cicd-流水线)
+- [浏览器模式](#浏览器模式)
+- [站点兼容性](#站点兼容性)
+
+---
+
+## 测试架构
+
+测试分为三层，全部使用 **vitest** 运行：
+
+```text
+tests/
+├── e2e/                           # E2E 集成测试（子进程运行真实 CLI）
+│   ├── helpers.ts                 # runCli() / parseJsonOutput() 共享工具
+│   ├── public-commands.test.ts    # 公开 API 命令
+│   ├── browser-public.test.ts     # 浏览器命令（公开数据）
+│   ├── browser-auth.test.ts       # 需登录命令（graceful failure）
+│   ├── management.test.ts         # 管理命令（list / validate / verify / help）
+│   └── output-formats.test.ts     # 输出格式校验
+├── smoke/
+│   └── api-health.test.ts         # 外部 API、adapter 定义、命令注册健康检查
+src/
+├── **/*.test.ts                   # 核心单元测试（默认 `unit` project）
+└── clis/{zhihu,twitter,reddit,bilibili}/**/*.test.ts  # 聚焦 adapter tests
+```
+
+| 层 | 位置 | 当前文件数 | 运行方式 | 用途 |
+|---|---|---:|---|---|
+| 单元测试 | `src/**/*.test.ts`（排除 `src/clis/**`） | - | `npm test` | 内部模块、pipeline、runtime |
+| Adapter 测试 | `src/clis/{zhihu,twitter,reddit,bilibili}/**/*.test.ts` | - | `npm run test:adapter` | 保留 4 个重点站点的 adapter 覆盖 |
+| E2E 测试 | `tests/e2e/*.test.ts` | 5 | `npx vitest run tests/e2e/` | 真实 CLI 命令执行 |
+| 烟雾测试 | `tests/smoke/*.test.ts` | 1 | `npx vitest run tests/smoke/` | 外部 API 与注册完整性 |
+
+---
+
+## 当前覆盖范围
+
+### 单元测试与 Adapter 测试
+
+| 领域 | 文件 |
+|---|---|
+| 核心运行时与输出 | `src/browser.test.ts`, `src/browser/dom-snapshot.test.ts`, `src/build-manifest.test.ts`, `src/capabilityRouting.test.ts`, `src/doctor.test.ts`, `src/engine.test.ts`, `src/interceptor.test.ts`, `src/output.test.ts`, `src/plugin.test.ts`, `src/registry.test.ts`, `src/snapshotFormatter.test.ts` |
+| pipeline 与下载 | `src/download/index.test.ts`, `src/pipeline/executor.test.ts`, `src/pipeline/template.test.ts`, `src/pipeline/transform.test.ts` |
+| 聚焦 adapter 逻辑 | `src/clis/zhihu/download.test.ts`, `src/clis/twitter/timeline.test.ts`, `src/clis/reddit/read.test.ts`, `src/clis/bilibili/dynamic.test.ts` |
+
+这些测试覆盖的重点包括：
+
+- Browser Bridge、DOM snapshot、interceptor、capability routing
+- manifest 生成、命令发现、插件安装与注册表
+- 输出格式渲染与 snapshot formatting
+- pipeline 模板求值、执行器与变换步骤
+- 各站点 adapter 的数据归一化、参数处理与容错逻辑
+
+### E2E 测试（5 个文件）
+
+| 文件 | 当前覆盖范围 |
+|---|---|
+| `tests/e2e/public-commands.test.ts` | `bloomberg`、`apple-podcasts`、`hackernews`、`v2ex`、`xiaoyuzhou`、`google suggest` 等公开命令 |
+| `tests/e2e/browser-public.test.ts` | `bbc`、`bloomberg`、`bilibili`、`weibo`、`zhihu`、`reddit`、`twitter`、`xueqiu`、`reuters`、`youtube`、`smzdm`、`boss`、`ctrip`、`coupang`、`xiaohongshu`、`google`、`yahoo-finance`、`v2ex daily` |
+| `tests/e2e/browser-auth.test.ts` | `bilibili`、`twitter`、`v2ex`、`xueqiu`、`linux-do`、`xiaohongshu` 的需登录命令 graceful failure |
+| `tests/e2e/management.test.ts` | `list`、`validate`、`verify`、`--version`、`--help`、unknown command |
+| `tests/e2e/output-formats.test.ts` | `json` / `yaml` / `csv` / `md` 输出格式校验 |
+
+### 烟雾测试（1 个文件）
+
+| 文件 | 当前覆盖范围 |
+|---|---|
+| `tests/smoke/api-health.test.ts` | `hackernews`、`v2ex` 公开 API 可用性，`validate` 全量 adapter 校验，以及命令注册表基础完整性 |
+
+### 快速核对命令
+
+需要刷新测试清单时，直接以仓库文件为准：
+
+```bash
+find src -name '*.test.ts' | sort
+find tests/e2e -name '*.test.ts' | sort
+find tests/smoke -name '*.test.ts' | sort
+```
+
+---
+
+## 本地运行测试
+
+### 前置条件
+
+```bash
+npm ci                # 安装依赖
+npm run build         # 编译（E2E / smoke 测试需要 dist/main.js）
+```
+
+### 运行命令
+
+```bash
+# 默认核心单元测试（不含大多数 adapter tests）
+npm test
+
+# 聚焦 adapter tests（只保留 4 个重点站点）
+npm run test:adapter
+
+# 全部 E2E 测试（会真实调用外部 API / 浏览器）
+npx vitest run tests/e2e/
+
+# 全部 smoke 测试
+npx vitest run tests/smoke/
+
+# 单个测试文件
+npx vitest run src/clis/apple-podcasts/commands.test.ts
+npx vitest run tests/e2e/management.test.ts
+
+# 全部测试
+npx vitest run
+
+# watch 模式（开发时推荐）
+npx vitest src/
+```
+
+### 浏览器命令本地测试须知
+
+- opencli 通过 Browser Bridge 扩展连接已运行的 Chrome 浏览器
+- E2E 测试通过 `tests/e2e/helpers.ts` 里的 `runCli()` 调用已构建的 `dist/main.js`
+- `browser-public.test.ts` 使用 `tryBrowserCommand()`，站点反爬或地域限制导致空数据时会 warn + pass
+- `browser-auth.test.ts` 验证 **graceful failure**，重点是不 crash、不 hang、错误信息可控
+- 如需测试完整登录态，保持 Chrome 登录态并安装 Browser Bridge 扩展，再手动运行对应测试
+
+---
+
+## 如何添加新测试
+
+### 新增 YAML Adapter（如 `src/clis/producthunt/trending.yaml`）
+
+1. `opencli validate` 的 E2E / smoke 测试会覆盖 adapter 结构校验
+2. 根据 adapter 类型，在对应测试文件补一个 `it()` block
+
+```typescript
+// 如果 browser: false（公开 API）→ tests/e2e/public-commands.test.ts
+it('producthunt trending returns data', async () => {
+  const { stdout, code } = await runCli(['producthunt', 'trending', '--limit', '3', '-f', 'json']);
+  expect(code).toBe(0);
+  const data = parseJsonOutput(stdout);
+  expect(Array.isArray(data)).toBe(true);
+  expect(data.length).toBeGreaterThanOrEqual(1);
+  expect(data[0]).toHaveProperty('title');
+}, 30_000);
+```
+
+```typescript
+// 如果 browser: true 但可公开访问 → tests/e2e/browser-public.test.ts
+it('producthunt trending returns data', async () => {
+  const data = await tryBrowserCommand(['producthunt', 'trending', '--limit', '3', '-f', 'json']);
+  expectDataOrSkip(data, 'producthunt trending');
+}, 60_000);
+```
+
+```typescript
+// 如果 browser: true 且需登录 → tests/e2e/browser-auth.test.ts
+it('producthunt me fails gracefully without login', async () => {
+  await expectGracefulAuthFailure(['producthunt', 'me', '-f', 'json'], 'producthunt me');
+}, 60_000);
+```
+
+### 新增管理命令（如 `opencli export`）
+
+在 `tests/e2e/management.test.ts` 添加测试；如果新命令会影响输出格式，也同步补 `tests/e2e/output-formats.test.ts`。
+
+### 新增内部模块
+
+在对应源码旁创建 `*.test.ts`，优先和被测模块放在同一目录下，便于发现与维护。
+
+### 决策流程图
+
+```text
+新增功能 → 是内部模块？ → 是 → src/ 下加 *.test.ts
+                ↓ 否
+         是 CLI 命令？ → browser: false? → tests/e2e/public-commands.test.ts
+                              ↓ true
+                        公开数据？ → tests/e2e/browser-public.test.ts
+                              ↓ 需登录
+                        tests/e2e/browser-auth.test.ts
+```
+
+---
+
+## CI/CD 流水线
+
+### `ci.yml`
+
+| Job | 触发条件 | 内容 |
+|---|---|---|
+| `build` | push/PR 到 `main`,`dev` | `tsc --noEmit` + `npm run build` |
+| `unit-test` | push/PR 到 `main`,`dev` | Node `20` 与 `22` 双版本运行核心 `unit` tests，按 `2` shard 并行 |
+| `adapter-test` | push/PR 到 `main`,`dev` | Node `22` 运行聚焦的 `zhihu/twitter/reddit/bilibili` adapter tests |
+| `smoke-test` | `schedule` 或 `workflow_dispatch` | 安装真实 Chrome，`xvfb-run` 执行 `tests/smoke/` |
+
+### `e2e-headed.yml`
+
+| Job | 触发条件 | 内容 |
+|---|---|---|
+| `e2e-headed` | push/PR 到 `main`,`dev`，或手动触发 | 安装真实 Chrome，`xvfb-run` 执行 `tests/e2e/` |
+
+E2E 与 smoke 都使用 `./.github/actions/setup-chrome` 准备真实 Chrome，并通过 `OPENCLI_BROWSER_EXECUTABLE_PATH` 注入浏览器路径。
+
+### Sharding
+
+单元测试使用 vitest 内置 shard，并在 Node `20` / `22` 两个版本上运行：
+
+::: v-pre
+```yaml
+strategy:
+  matrix:
+    node-version: ['20', '22']
+    shard: [1, 2]
+steps:
+  - run: npm test -- --reporter=verbose --shard=${{ matrix.shard }}/2
+```
+:::
+
+---
+
+## 浏览器模式
+
+opencli 通过 Browser Bridge 扩展连接浏览器：
+
+| 条件 | 模式 | 使用场景 |
+|---|---|---|
+| 扩展已安装 / 已连接 | Extension 模式 | 本地用户，连接已登录的 Chrome |
+| 无扩展 token | CLI 自行拉起浏览器 | CI、无登录态或纯自动化场景 |
+
+CI 中使用 `OPENCLI_BROWSER_EXECUTABLE_PATH` 指定真实 Chrome 路径：
+
+::: v-pre
+```yaml
+env:
+  OPENCLI_BROWSER_EXECUTABLE_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}
+```
+:::
+
+---
+
+## 站点兼容性
+
+GitHub Actions 的美国 runner 上，部分站点会因为地域限制、登录要求或反爬而返回空数据。当前 E2E 对这些场景采用 warn + pass 策略，避免偶发站点限制把整条 CI 打红。
+
+| 站点 | CI 表现 | 常见原因 |
+|---|---|---|
+| `hackernews`、`bbc`、`v2ex`、`bloomberg` | 通常返回数据 | 公开接口或公开页面 |
+| `yahoo-finance`、`google` | 通常返回数据 | 页面公开，但仍可能受限流影响 |
+| `bilibili`、`zhihu`、`weibo`、`xiaohongshu`、`xueqiu` | 容易空数据 | 地域限制、反爬、登录要求 |
+| `reddit`、`twitter`、`youtube` | 容易空数据 | 登录态、cookie、机器人检测 |
+| `smzdm`、`boss`、`ctrip`、`coupang`、`linux-do` | 结果波动较大 | 地域限制、风控或页面结构变动 |
+
+> 如果需要更稳定的浏览器 E2E 结果，优先使用具备目标站点网络可达性的 self-hosted runner。

docs/developer/ts-adapter.md

@@ -0,0 +1,87 @@
+# TypeScript Adapter Guide
+
+Use TypeScript adapters when you need browser-side logic, multi-step flows, DOM manipulation, or complex data extraction that goes beyond simple API fetching.
+
+## Basic Structure
+
+```typescript
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'mysite',
+  name: 'search',
+  description: 'Search MySite',
+  domain: 'www.mysite.com',
+  strategy: Strategy.COOKIE,      // PUBLIC | COOKIE | HEADER
+  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;
+
+    // Navigate and extract data
+    await page.goto('https://www.mysite.com');
+
+    const data = await page.evaluate(`
+      (async () => {
+        const res = await fetch('/api/search?q=${encodeURIComponent(String(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,
+    }));
+  },
+});
+```
+
+## Strategy Types
+
+| Strategy | Constant | Use Case |
+|----------|----------|----------|
+| Public | `Strategy.PUBLIC` | No auth needed |
+| Cookie | `Strategy.COOKIE` | Browser session cookies |
+| Header | `Strategy.HEADER` | Custom headers/tokens |
+
+## The `page` Object
+
+The `page` parameter provides browser interaction methods:
+
+- `page.goto(url)` — Navigate to a URL
+- `page.evaluate(script)` — Execute JavaScript in the page context
+- `page.waitForSelector(selector)` — Wait for an element
+- `page.click(selector)` — Click an element
+- `page.type(selector, text)` — Type text into an input
+
+## The `kwargs` Object
+
+Contains parsed CLI arguments as key-value pairs. Always destructure with defaults:
+
+```typescript
+const { query, limit = 10, format = 'json' } = kwargs;
+```
+
+## AI-Assisted Development
+
+Use the AI workflow tools to accelerate adapter creation:
+
+```bash
+# Discover APIs and page structure
+opencli explore https://example.com --site mysite
+
+# Auto-generate adapter from explore artifacts
+opencli synthesize mysite
+
+# One-shot: explore → synthesize → register
+opencli generate https://example.com --goal "trending"
+```
+
+See [AI Workflow](/developer/ai-workflow) for the complete guide.

docs/developer/yaml-adapter.md

@@ -0,0 +1,108 @@
+# YAML Adapter Guide
+
+YAML adapters are the recommended way to add new commands when the site offers a straightforward API. They use a declarative pipeline approach — no TypeScript required.
+
+## Basic Structure
+
+::: v-pre
+```yaml
+site: mysite          # Site identifier
+name: trending        # Command name (opencli mysite trending)
+description: ...      # Help text
+domain: www.mysite.com
+strategy: public      # public | cookie | header
+browser: false        # true if browser session is needed
+
+args:                 # CLI arguments
+  limit:
+    type: int
+    default: 20
+    description: Number of items
+
+pipeline:             # Data processing steps
+  - fetch:
+      url: https://api.mysite.com/trending
+
+  - map:
+      rank: ${{ index + 1 }}
+      title: ${{ item.title }}
+
+  - limit: ${{ args.limit }}
+
+columns: [rank, title, score, url]
+```
+:::
+
+## Pipeline Steps
+
+### `fetch`
+Fetch data from a URL. Supports template expressions for dynamic URLs.
+
+::: v-pre
+```yaml
+- fetch:
+    url: https://api.example.com/search?q=${{ args.query }}
+    headers:
+      Accept: application/json
+```
+:::
+
+### `map`
+
+::: v-pre
+Transform each item in the result array. Use `${{ item.xxx }}` for field access and `${{ index }}` for position.
+
+```yaml
+- map:
+    rank: ${{ index + 1 }}
+    title: ${{ item.title }}
+    url: https://example.com${{ item.path }}
+```
+:::
+
+### `limit`
+Truncate results to N items.
+
+::: v-pre
+```yaml
+- limit: ${{ args.limit }}
+```
+:::
+
+### `filter`
+Filter items by condition.
+
+::: v-pre
+```yaml
+- filter: ${{ item.score > 100 }}
+```
+:::
+
+### `download`
+Download media files.
+
+::: v-pre
+```yaml
+- download:
+    url: ${{ item.imageUrl }}
+    dir: ./downloads
+    filename: ${{ item.title | sanitize }}.jpg
+```
+:::
+
+## Template Expressions
+
+::: v-pre
+Use `${{ ... }}` for dynamic values:
+
+| Expression | Description |
+|-----------|-------------|
+| `${{ args.limit }}` | CLI argument |
+| `${{ item.title }}` | Current item field |
+| `${{ index }}` | Current index (0-based) |
+| `${{ item.x \| sanitize }}` | Pipe filters |
+:::
+
+## Real Example
+
+See [`src/clis/hackernews/top.yaml`](https://github.com/jackwener/opencli/blob/main/src/clis/hackernews/top.yaml).

docs/guide/browser-bridge.md

@@ -0,0 +1,37 @@
+# Browser Bridge Setup
+
+> **⚠️ Important**: Browser commands reuse your Chrome login session. You must be logged into the target website in Chrome before running commands.
+
+OpenCLI connects to your browser through a lightweight **Browser Bridge** Chrome Extension + micro-daemon (zero config, auto-start).
+
+## Extension Installation
+
+### Method 1: Download Pre-built Release (Recommended)
+
+1. Go to the GitHub [Releases page](https://github.com/jackwener/opencli/releases) and download the latest `opencli-extension.zip`.
+2. Unzip the file and open `chrome://extensions`, enable **Developer mode** (top-right toggle).
+3. Click **Load unpacked** and select the unzipped folder.
+
+### Method 2: Load Unpacked Source (For Developers)
+
+1. Open `chrome://extensions` and enable **Developer mode**.
+2. Click **Load unpacked** and select the `extension/` directory from the repository.
+
+## Verification
+
+That's it! The daemon auto-starts when you run any browser command. No tokens, no manual configuration.
+
+```bash
+opencli doctor            # Check extension + daemon connectivity
+```
+
+## How It Works
+
+```
+┌─────────────┐     WebSocket      ┌──────────────┐     Chrome API     ┌─────────┐
+│  opencli    │ ◄──────────────► │  micro-daemon │ ◄──────────────► │  Chrome  │
+│  (Node.js)  │    localhost:19825  │  (auto-start) │    Extension       │ Browser  │
+└─────────────┘                    └──────────────┘                    └─────────┘
+```
+
+The daemon manages the WebSocket connection between your CLI commands and the Chrome extension. The extension executes JavaScript in the context of web pages, with access to the logged-in session.

docs/guide/getting-started.md

@@ -0,0 +1,57 @@
+# Getting Started
+
+> **Make any website or Electron App your CLI.**
+> Zero risk · Reuse Chrome login · AI-powered discovery · Browser + Desktop automation
+
+[![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)](https://github.com/jackwener/opencli/blob/main/LICENSE)
+
+OpenCLI turns **any website** or **Electron app** into a command-line interface — Bilibili, Zhihu, 小红书, Twitter/X, Reddit, YouTube, Antigravity, and [many more](/adapters/) — powered by browser session reuse and AI-native discovery.
+
+## Highlights
+
+- **CLI All Electron** — CLI-ify apps like Antigravity Ultra! Now AI can control itself natively.
+- **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.
+- **Self-healing setup** — `opencli doctor` auto-starts the daemon and diagnoses extension + live browser connectivity.
+- **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.
+
+## Quick Start
+
+### Install via npm
+
+```bash
+npm install -g @jackwener/opencli
+```
+
+### Basic Usage
+
+```bash
+opencli list                              # See all commands
+opencli hackernews top --limit 5          # Public API, no browser
+opencli bilibili hot --limit 5            # Browser command
+opencli zhihu hot -f json                 # JSON output
+```
+
+### Output Formats
+
+All built-in commands support `--format` / `-f`:
+
+```bash
+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)
+opencli bilibili hot -f md      # Markdown
+opencli bilibili hot -f csv     # CSV
+opencli bilibili hot -v         # Verbose: show pipeline debug
+```
+
+## Next Steps
+
+- [Installation details](/guide/installation)
+- [Browser Bridge setup](/guide/browser-bridge)
+- [Plugins — extend with community adapters](/guide/plugins)
+- [All available adapters](/adapters/)
+- [For developers / AI agents](/developer/contributing)