AlexYue
31f58ae699
- Add VitePress with full navigation, sidebar, i18n (en/zh), local search - Create 50+ doc pages: guide, adapters (browser + desktop), developer, advanced - Migrate content from README.md, CONTRIBUTING.md, TESTING.md, CDP.md, CLI-ELECTRON.md - Migrate all 11 adapter READMEs to structured documentation - Add new pages: architecture, yaml-adapter guide, ts-adapter guide, ai-workflow - Add GitHub Actions workflow for deploying to GitHub Pages - Add Chinese locale pages (getting-started, installation, browser-bridge, etc.) - Add docs:dev, docs:build, docs:preview npm scripts
4.8 KiB
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.
Engine (src/engine.ts)
Command discovery and execution engine. Discovers commands from the registry, parses arguments, executes the appropriate adapter, and routes output through the formatter.
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 |
Directory Structure
src/
├── main.ts # Entry point
├── engine.ts # Command execution engine
├── registry.ts # Command registry
├── browser.ts # 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/
└── ...