npm package: @lyhue1991/opencli
Description: Make any website or Electron App your CLI. AI-powered.
Author: jackwener
Latest version: 0.1.0

# OpenCLI

> 把网站、Electron 应用、本地命令行工具统一封装成可调用的 CLI 接口。

[![npm](https://img.shields.io/npm/v/@lyhue1991/opencli?style=flat-square)](https://www.npmjs.com/package/@lyhue1991/opencli)
[![Node.js Version](https://img.shields.io/node/v/@lyhue1991/opencli?style=flat-square)](https://nodejs.org)
[![License](https://img.shields.io/npm/l/@lyhue1991/opencli?style=flat-square)](./LICENSE)

OpenCLI 是一个 TypeScript CLI 框架，用来把已有能力整理成稳定、可组合、可脚本化的命令行接口。它既可以直接封装网站和 Electron 应用，也可以把现有本地 CLI 纳入统一入口，并为 AI Agent 提供浏览器操作、接口探索和适配器生成能力。

如果你第一次接触这个项目，先看这三个问题：

- 它能做什么：看 [功能概述](#功能概述)
- 它怎么工作：看 [架构原理](#架构原理)
- 怎么继续扩展：看 [开发指南](#开发指南)

## 快速开始

### 安装

```bash
npm install -g @lyhue1991/opencli
```

### 常用命令

```bash
opencli list
opencli list -f yaml
opencli hackernews top --limit 5
opencli zhihu hot -f json
opencli plugin list
opencli gh pr list --limit 5
```

### 浏览器命令前提

大多数浏览器类命令会复用你当前 Chrome 或 Chromium 的登录态，因此需要先满足两点：

- 浏览器已经登录目标网站
- 已安装 Browser Bridge 扩展

详细安装与诊断见：

- [Browser Bridge Setup](./docs/guide/browser-bridge.md)
- `opencli doctor`
- `opencli daemon status`

## 功能概述

OpenCLI 解决的是“把已有能力变成稳定 CLI 接口”的问题，核心能力包括：

### 1. 网站 CLI 化

将网页或站点能力封装为 `opencli <site> <command>`，适合热榜、搜索、详情读取、下载、账号信息获取等场景。

- 支持公开接口访问
- 支持复用浏览器 Cookie 登录态
- 支持基于请求头、拦截或 UI 的更复杂访问方式

### 2. Electron 应用 CLI 化

通过 Chrome DevTools Protocol 连接 Electron 应用，把桌面端能力纳入命令行调用链路。

- 适合桌面端自动化
- 适合数据提取与操作编排
- 适合让 AI Agent 操作已有 Electron 工具

### 3. 外部 CLI 聚合

OpenCLI 可以作为本地 CLI 的统一入口，把 `gh`、`docker`、`vercel` 等工具纳入同一命令空间。

- 支持内置外部 CLI 注册表
- 支持注册已安装的本地命令
- 支持移除用户自定义注册

### 4. AI 辅助适配器开发

仓库内置了面向 AI Agent 的浏览器操作与策略探测能力：

- `opencli operate`：打开页面、读取状态、点击、执行脚本、查看网络请求
- `opencli cascade`：探测更适合的认证策略
- `skills/opencli-creator/SKILL.md`：指导 AI Agent 完成新 adapter 的发现、编写与测试流程

### 5. 浏览器操作能力

`opencli operate` 提供一组面向 AI Agent 的浏览器控制命令，可用于：

- 打开页面、读取状态、点击、输入、等待
- 执行页面脚本、提取 HTML / 文本 / 属性
- 查看自动采集到的网络请求

### 6. 可扩展生态

OpenCLI 支持多种扩展方式：

- 内置 adapter
- 用户自定义 adapter
- plugin
- 外部 CLI register/unregister

参考入口：

- [Adapters Index](./docs/adapters/index.md)
- [Plugins Guide](./docs/guide/plugins.md)
- [AI Workflow](./docs/developer/ai-workflow.md)

## 架构原理

OpenCLI 的核心不是某个单独站点脚本，而是一套统一的“发现、注册、装配、执行、输出”框架。

### 总体结构

```text
┌────────────────────────────────────────────────────────┐
│                        opencli                         │
│                     src/main.ts                        │
└────────────────────────────────────────────────────────┘
                          │
                          ▼
┌────────────────────────────────────────────────────────┐
│  发现与注册                                             │
│  - src/discovery.ts                                    │
│  - src/build-manifest.ts                               │
│  - src/registry.ts                                     │
└────────────────────────────────────────────────────────┘
                          │
                          ▼
┌────────────────────────────────────────────────────────┐
│  命令装配层                                             │
│  - src/cli.ts                                          │
│  - src/commanderAdapter.ts                             │
└────────────────────────────────────────────────────────┘
                          │
                          ▼
┌────────────────────────────────────────────────────────┐
│  执行层                                                 │
│  - src/execution.ts                                    │
└────────────────────────────────────────────────────────┘
                          │
             ┌────────────┼────────────┐
             ▼            ▼            ▼
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ YAML Pipeline  │ │ TS Adapter     │ │ External CLI   │
│ src/pipeline/* │ │ src/clis/**/*.ts│ │ src/external.ts│
└────────────────┘ └────────────────┘ └────────────────┘
             │            │
             ▼            ▼
┌────────────────────────────────────────────────────────┐
│  运行时连接层                                           │
│  - Browser Bridge + daemon                             │
│  - Electron CDP                                        │
│  - Node fetch / local process                          │
└────────────────────────────────────────────────────────┘
```

### 1. 命令发现与注册

启动入口在 `src/main.ts`。

OpenCLI 启动后会：

- 发现内置 commands
- 发现用户目录下的 commands
- 发现 plugins
- 将它们统一注册到全局 registry

相关模块：

- `src/discovery.ts`
- `src/registry.ts`
- `src/build-manifest.ts`

生产环境优先走 manifest 快路径，减少运行时 YAML 解析和 TS 模块加载开销；TypeScript adapter 支持按需懒加载。

### 2. 统一命令模型

OpenCLI 在 `src/registry.ts` 中定义统一命令模型。无论命令来自：

- 内置 YAML adapter
- 内置 TypeScript adapter
- plugin
- 用户本地 adapter

最终都会收敛为同一类命令对象，包含这些核心字段：

- `site`
- `name`
- `description`
- `strategy`
- `browser`
- `args`
- `columns`
- `func` 或 `pipeline`

这让命令装配和执行层可以对不同来源一视同仁。

### 3. 双引擎 adapter 模型

#### YAML adapter

适合结构稳定、偏读取型、可声明式描述的命令。

- 入口目录：`src/clis/<site>/*.yaml`
- 执行引擎：`src/pipeline/`
- 常见步骤：`fetch`、`map`、`limit`、`filter`、`download`

优势是：

- 声明式
- 易读
- 易生成
- 很适合 AI 探索后自动合成

#### TypeScript adapter

适合更复杂的浏览器交互、多步流程、DOM 操作、写操作和多源聚合逻辑。

- 入口目录：`src/clis/<site>/*.ts`
- 通过 `cli({...})` 直接注册

优势是：

- 表达能力更强
- 更适合复杂控制流和错误处理
- 更适合浏览器行为与数据处理混合场景

### 4. 执行链路

实际执行由 `src/execution.ts` 负责，核心流程包括：

1. 参数校验与类型转换
2. 执行前 hook
3. 判断是否需要 browser session
4. 必要时预导航到目标域名
5. 执行 `func` 或 `pipeline`
6. 处理超时、异常与退出码
7. 执行后 hook

命令行装配则由 `src/cli.ts` 与 `src/commanderAdapter.ts` 负责，把 registry 中的命令挂到 Commander 子命令树上。

### 5. 运行时连接方式

OpenCLI 会根据命令能力选择不同执行介质：

- `public`：直接 HTTP 请求
- `cookie`：复用浏览器登录态
- `header`：使用自定义请求头
- `intercept`：依赖请求拦截或签名线索
- `ui`：直接基于页面交互执行
- Electron：通过 CDP 连接桌面应用

Browser Bridge 详细说明见：

- [Browser Bridge Setup](./docs/guide/browser-bridge.md)

更完整的开发者架构说明见：

- [Developer Architecture](./docs/developer/architecture.md)

### 6. AI 工作流

AI 相关能力围绕 adapter 调研、策略判断与浏览器操作展开：

```text
operate
  ↓
读取页面状态、执行交互、查看网络请求
  ↓
cascade
  ↓
判断最合适的认证策略
  ↓
opencli-creator skill
  ↓
编写并测试 adapter
```

完整说明见：

- [AI Workflow](./docs/developer/ai-workflow.md)

## 开发指南

如果你想继续增加 OpenCLI 的能力，优先从下面五条路径里选最简单的一条。

### 路径一：增加内置 YAML adapter

适用于：

- 公开 API
- 结构稳定的数据抓取
- 简单读取型命令

文件位置：

```text
src/clis/<site>/<command>.yaml
```

最小示例：

```yaml
site: mysite
name: hot
description: Hot items
domain: www.example.com
strategy: public
browser: false

args:
  limit:
    type: int
    default: 10

pipeline:
  - fetch:
      url: https://api.example.com/hot
  - map:
      rank: ${{ index + 1 }}
      title: ${{ item.title }}
      url: ${{ item.url }}
  - limit: ${{ args.limit }}

columns: [rank, title, url]
```

进一步说明见：

- [YAML Adapter Guide](./docs/developer/yaml-adapter.md)

### 路径二：增加内置 TypeScript adapter

适用于：

- 多步骤浏览器交互
- DOM 操作
- 写操作
- 复杂提取与聚合逻辑

文件位置：

```text
src/clis/<site>/<command>.ts
```

最小示例：

```typescript
import { cli, Strategy } from '../../registry.js';

cli({
  site: 'mysite',
  name: 'search',
  description: 'Search MySite',
  domain: 'www.example.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'],
  func: async (page, kwargs) => {
    const data = await page.evaluate(`...`);
    return data;
  },
});
```

进一步说明见：

- [TypeScript Adapter Guide](./docs/developer/ts-adapter.md)

### 路径三：利用 AI 工作流辅助开发 adapter

这是本仓库面向 AI Agent 的适配器开发路径。

```bash
opencli operate open https://example.com
opencli operate state
opencli operate network
opencli cascade https://example.com/api/data
```

适合：

- 新站点快速探测
- 为 AI Agent 提供可验证的页面与网络上下文
- 配合 `skills/opencli-creator/SKILL.md` 从零编写 adapter

进一步说明见：

- [AI Workflow](./docs/developer/ai-workflow.md)
- [`opencli-creator` skill](./skills/opencli-creator/SKILL.md)

### 路径四：开发 plugin

如果你不想直接改主仓库，推荐用 plugin 扩展。

```bash
opencli plugin create my-plugin
opencli plugin install file:///path/to/my-plugin
opencli plugin list
```

plugin 同样支持 YAML 和 TypeScript，两者都能被启动时自动发现。

进一步说明见：

- [Plugins Guide](./docs/guide/plugins.md)

### 路径五：注册外部 CLI

如果能力已经由成熟命令行工具提供，就不一定需要重新实现 adapter，可以在本机先安装该工具，再注册到 OpenCLI。

```bash
brew install gh
opencli register mycli
opencli unregister mycli
opencli gh pr list --limit 5
opencli docker ps
```

说明：

- 外部 CLI 的安装由 `npm`、`brew` 等包管理器负责
- OpenCLI 只负责注册、发现和透传执行

适合：

- 已有 CLI 的能力聚合
- 团队内部工具统一入口
- AI Agent 统一发现与调用

## 开发与验证

常用开发命令：

```bash
npm run dev
npm run build
npm run typecheck
npm test
npm run test:adapter
npm run test:e2e
```

新增或修改 adapter 后，通常至少执行：

```bash
opencli validate
npm run typecheck
```

## 相关文档

- [Getting Started](./docs/guide/getting-started.md)
- [Browser Bridge Setup](./docs/guide/browser-bridge.md)
- [Plugins Guide](./docs/guide/plugins.md)
- [Developer Architecture](./docs/developer/architecture.md)
- [YAML Adapter Guide](./docs/developer/yaml-adapter.md)
- [TypeScript Adapter Guide](./docs/developer/ts-adapter.md)
- [AI Workflow](./docs/developer/ai-workflow.md)
- [Adapters Index](./docs/adapters/index.md)

## License

[Apache-2.0](./LICENSE)