OpenCLI

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

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

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

• 它能做什么：看 功能概述
• 它怎么工作：看 架构原理
• 怎么继续扩展：看 开发指南

快速开始

安装

npm install -g @lyhue1991/opencli

常用命令

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
• 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
• Plugins Guide
• AI Workflow

架构原理

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

总体结构

┌────────────────────────────────────────────────────────┐
│                        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

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

• Developer Architecture

6. AI 工作流

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

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

完整说明见：

• AI Workflow

开发指南

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

路径一：增加内置 YAML adapter

适用于：

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

文件位置：

src/clis/<site>/<command>.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

路径二：增加内置 TypeScript adapter

适用于：

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

文件位置：

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

最小示例：

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

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

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

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
• opencli-creator skill

路径四：开发 plugin

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

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

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

进一步说明见：

• Plugins Guide

路径五：注册外部 CLI

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

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 统一发现与调用

开发与验证

常用开发命令：

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

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

opencli validate
npm run typecheck

相关文档

• Getting Started
• Browser Bridge Setup
• Plugins Guide
• Developer Architecture
• YAML Adapter Guide
• TypeScript Adapter Guide
• AI Workflow
• Adapters Index

License

Apache-2.0