mirror of
https://github.com/jackwener/OpenCLI.git
synced 2026-09-14 18:25:42 +08:00
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
91 lines
4.8 KiB
Markdown
91 lines
4.8 KiB
Markdown
# 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/
|
|
└── ...
|
|
```
|