mirror of
https://github.com/jackwener/OpenCLI.git
synced 2026-09-14 18:25:42 +08:00
jakevin
70b1145b5e
* refactor: remove version field from GenerateOutcome and EarlyHint All consumers are in the same repo and evolve together — version field adds ceremony without practical value at this stage. Keeps schema_version in VerifiedArtifactMetadata (sidecar file format). * refactor: migrate all 123 CLI adapters from YAML to TypeScript Remove YAML as an adapter format entirely. All adapters now use TypeScript with cli() from @jackwener/opencli/registry. - Convert 123 YAML adapter files to TypeScript via batch script - Remove YAML scanning from discovery.ts (registerYamlCli, yaml import) - Remove scanYaml() and shouldReplaceManifestEntry() from build-manifest.ts - Change synthesize.ts to output JSON candidates (internal format) - Change generate-verified.ts to write .ts adapter files instead of .yaml - Delete yaml-schema.ts (dead code) and scripts/yaml-to-ts.mjs (one-time tool) - Update all tests to match new format Closes discussion in #OpenCLI thread 47ddba82. * fix: close YAML migration gaps in plugin scaffold, validation, and scan - plugin-scaffold.ts: generate hello.ts (TS pipeline) instead of hello.yaml - plugin.ts validatePluginStructure: no longer accept .yaml as valid command file - plugin.ts scanPluginCommands: remove .yaml/.yml from scanned extensions - discovery.ts: add explicit log.warn() when YAML files detected in clis/ or plugins/ - plugin.test.ts: update all test fixtures from .yaml to .js - plugin-scaffold.test.ts: update hello.yaml references to hello.ts - Delete dead src/yaml-schema.ts Resolves PR #887 review blockers from @mbp-codex-pr0. * refactor: complete YAML removal across docs, skills, record, and binance adapters Code changes: - record.ts: candidate output changed from .yaml (yaml.dump) to .json (JSON.stringify), removed js-yaml import - src/clis/binance: convert all 11 YAML adapters to TypeScript cli() format - binance/commands.test.ts: rewrite to use registry instead of yaml.load - skill-generate.test.ts, diagnostic.test.ts: update mock paths from .yaml to .ts - build-manifest.ts, synthesize.ts: update stale YAML comments Documentation: - README.md: remove .yaml from Dynamic Loader, fix plugin types, fix synthesize comment - README.zh-CN.md: fix synthesize comment - CONTRIBUTING.md: replace YAML Adapter section with Pipeline Adapter (TS), update arg examples - docs/developer/yaml-adapter.md: replaced with deprecation redirect - docs/developer/architecture.md: remove YAML pipeline references - docs/developer/contributing.md: remove YAML adapter section - docs/developer/ai-workflow.md: YAML → TS in synthesize description - docs/guide/getting-started.md: remove .yaml from loader, update engine description - docs/guide/plugins.md: remove YAML plugin option, update plugin types - docs/index.md, docs/comparison.md: remove YAML adapter references - docs/zh/guide/plugins.md: remove .yaml from scan description Skills: - opencli-explorer/SKILL.md: rewrite YAML vs TS decision tree to TS-only - opencli-oneshot/SKILL.md: replace YAML templates with TS cli() templates - opencli-generate/SKILL.md: YAML artifact path → TS artifact path - opencli-usage/SKILL.md, plugins.md: update adapter format references * fix: clean up remaining YAML adapter references in docs - docs/zh/guide/plugins.md: replace YAML plugin example with TS pipeline - docs/developer/testing.md: YAML Adapter heading → Adapter, remove validate line - TESTING.md: same fix in root testing doc - CONTRIBUTING.md: remove "YAML validation" comment - docs/.vitepress/config.mts: mark YAML Adapter Guide as (Deprecated) in nav - docs/advanced/download.md: remove "YAML Adapters" from pipeline step heading
104 lines
5.7 KiB
Markdown
104 lines
5.7 KiB
Markdown
# Architecture
|
|
|
|
OpenCLI is built on a **Dual-Engine Architecture** that supports both declarative pipelines and programmatic TypeScript adapters.
|
|
|
|
## High-Level Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ opencli CLI │
|
|
│ (Commander.js entry point) │
|
|
├─────────────────────────────────────────────────────┤
|
|
│ Engine Layer │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
|
|
│ │ Registry │ │ Dynamic │ │ Output │ │
|
|
│ │ (commands) │ │ Loader │ │ Formatter │ │
|
|
│ └──────────────┘ └──────────────┘ └────────────┘ │
|
|
├─────────────────────────────────────────────────────┤
|
|
│ Adapter Layer │
|
|
│ ┌─────────────────┐ ┌──────────────────────────┐ │
|
|
│ │ 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 TypeScript adapter files, parses 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 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
|
|
├── 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/ # 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/
|
|
└── ...
|
|
```
|