CLI-Hub Meta-Skill 实战指南：用 cli-hub 发现、安装与编排 Agent 原生 CLI

CLI-Hub 是 CLI-Anything 生态的「应用市场」：它把面向专业软件（图像编辑、3D 建模、视频制作、知识管理、本地大模型等）的 Agent 原生命令行接口整理为可按类别浏览、可搜索、可一键安装的注册表，并用「工作流矩阵（Matrix）」把多个 CLI 打包为 能力 × 提供者 的完整工作流。本文以 skills/cli-hub-meta-skill/SKILL.md 为核心骨架，结合 cli-hub 包的真实源码，完整讲解 cli-hub 的安装、检索、安装、矩阵预检与作用域安装、预览消费等全部操作，读完即可让 Agent 在一个环境里按需发现并组合任意软件能力。

一、CLI-Hub 是什么：Agent 原生软件的「应用市场」

CLI-Anything 项目的目标是把「所有软件变成 Agent 原生」（Making ALL Software Agent-Native）。落到工程上，它由两部分组成：

• 一个个独立的 harness 包：每个专业软件对应一个独立的 Python 包 cli-anything-<name>，提供独立入口 cli-anything-<name>，为真实软件后端提供带状态的操作、JSON 输出、REPL 模式；
• cli-hub 包管理器（即 cli-anything-hub）：负责从注册表发现这些 CLI、解析名称、安装/卸载/更新，并编排多 CLI 的矩阵工作流。

SKILL.md 中给出了一组覆盖范围：创意工作流（图像编辑、3D 建模、视频制作、音频处理、乐谱）、生产力工具（办公套件、知识管理、直播）、AI 平台（本地 LLM、图像生成、AI API、研究助手）、通信（视频会议与协作）、开发（制图、浏览器自动化、网络管理）、内容生成（AI 文档与媒体创作）。每类 CLI 都支持状态化操作、面向 Agent 的 JSON 输出、REPL 模式，并接入真实软件后端——而不是模拟器。

二、快速上手：安装与发现

SKILL.md 的 Quick Start 提供了最小可用链路：

# 安装 CLI-Hub 包管理器
pip install cli-anything-hub

# 浏览所有可用 CLI
cli-hub list

# 按类别或关键词搜索
cli-hub search image
cli-hub search "3d modeling"

# 安装一个 CLI
cli-hub install gimp

# 查看某个 CLI 的详细信息
cli-hub info gimp

从源码看，cli-hub list 还支持 -c/--category、-s/--source（harness / public / npm / all）过滤，以及 --json 机器可读输出；列表会按类别分组，并给已安装项打上绿色圆点标记，最后汇总「N CLIs available（M harness, K public）, X installed」与全部类别清单（见 cli-hub/cli_hub/cli.py）。

cli-hub install <name> 成功后会提示三种运行方式：cli-anything-<name> 直接运行、cli-hub launch <name> 启动，以及（对 npm 类公共 CLI）npx 方式（cli.py）。

三、底层机制：cli-hub 是 pip 之上的轻量包装

SKILL.md 明确指出：cli-hub 是 pip 的轻量包装。执行 cli-hub install gimp 时，它安装的是另一个独立 Python 包 cli-anything-gimp，每个 CLI 都是独立的 pip 包，cli-hub 只负责从注册表解析名字并跟踪安装状态。这一点在源码中有三重印证：

1. 双注册表合并：cli-hub/cli_hub/registry.py 从 registry.json（harness 注册表）与 public_registry.json（公共 CLI 注册表）拉取数据，为每条记录打上 _source 标签（harness / public），合并后统一对外提供 fetch_all_clis、get_cli、search_clis、list_categories；
2. 本地缓存：注册表缓存在 ~/.cli-hub/registry_cache.json，TTL 为 1 小时（CACHE_TTL = 3600），网络失败时回退到旧缓存（见 registry.py）。本仓库根目录下的 registry.json 与 public_registry.json 就是这两份注册表的内容源；
3. 安装策略分发：cli-hub/cli_hub/installer.py 根据每条记录的 install_strategy（或按来源推断）分发到五种执行器：pip（harness 包，python -m pip install）、npm（全局 npm install -g <package>）、uv、command（通用的 install_cmd 脚本）、bundled（随宿主应用自带、仅检测入口是否存在）。安装成功后写入 ~/.cli-hub/installed.json 记录版本、入口与策略（installer.py）。

因此「cli-hub install gimp 之后运行 cli-anything-gimp」在机制上是两个独立 pip 包的协作：hub 负责分发，harness 负责与真实软件后端交互。

四、Workflow Matrices：把「一个任务」打包成「能力 × 提供者」

SKILL.md 提出了核心概念：单个 CLI 只是一件工具，而 matrix（矩阵） 是把整个工作流打包成 能力（capabilities）× 提供者（providers） 的结构——例如 video-creation 会把 text.transcribe、visual.generate 这类意图映射到 harness CLI、公共 CLI、Python 库、原生二进制和云 API 上。当任务横跨多个工具（产出一个视频、设计一张图、构建一个游戏）时，应该先找矩阵而不是逐个工具手动拼装。

本仓库中的 cli-hub-matrix/video-creation/SKILL.md 就是一个完整的 v3 能力型矩阵实例，包含 script.storyboard、video.search、video.download、music.download、visual.capture、visual.generate、audio.synthesize、text.transcribe、text.caption、composite.assemble、quality.review 等十余项能力，每一项能力都列出多个 provider 及其 Kind、Requires、Cost、Quality、Offline 五元组——例如 text.transcribe 的 provider 从本地 cli-anything-videocaptioner（harness-cli）到 openai-whisper（python）再到 AssemblyAI / Deepgram（api）一应俱全。矩阵注册数据对应 matrix_registry.json。

4.1 标准 Agent 序列：先预检，再安装

SKILL.md 给出了矩阵使用的标准动作顺序，其设计原则是 preflight before you install（安装前先预检）：

cli-hub matrix list                                   # 浏览所有矩阵
cli-hub can "transcribe audio"                        # 跨矩阵查找该能力
cli-hub matrix search "video subtitle"                # 搜索；显示匹配到的能力
cli-hub matrix preflight video-creation --json        # 当前环境哪些可用？(exit 3 = 有缺口)
cli-hub matrix preflight video-creation -c text.transcribe --fix-hints   # 单个能力 + 安装提示
cli-hub matrix install video-creation --capability text.transcribe       # 只安装任务所需的部分
# 安装完成后，矩阵 SKILL.md 会在本地渲染出带 provider 选择规则的版本——务必阅读

• cli-hub can <query> 在所有矩阵的能力粒度上做搜索（search_capabilities，见 cli-hub/cli_hub/matrix.py），每个命中结果都携带当前机器的 provider 可用性，无命中时退出码为 1；
• cli-hub matrix preflight <name> 检查矩阵中各 provider 的 requires（env 变量 / 二进制 / Python 包三类）在本环境是否齐备（matrix.py）。--fix-hints 会在缺失 provider 下方打印可复制的安装命令（优先使用注册表里的 install_hint，否则推导为 cli-hub install <cli>，见 provider_install_hint）；
• cli-hub matrix install <name> --capability <id> 通过 resolve_install_scope 把能力解析为矩阵 clis[] 的一个子集，只安装该能力背后的 CLI（installer.py）。

4.2 退出码契约

矩阵命令族有严格的退出码约定（在 cli.py 定义为 EXIT_OK / EXIT_FAIL / EXIT_USAGE / EXIT_PARTIAL，并在 preflight、install、doctor 中落实）：

退出码	含义
0	成功 / 全部能力有可用 provider
1	失败 / 未找到 / 矩阵不存在
2	用法错误（如 --capability 与 --recipe 同时使用、未知能力 id）
3	部分成功 / 存在能力缺口（如 preflight 发现 gap、install 部分失败）

4.3 作用域安装：绝不无脑装全量

SKILL.md 强调：不要为「单能力任务」整装一个包含 14 个 CLI 的矩阵。可用的作用域控制有三把闸：

• --capability <id>：只装某个能力背后的 CLI；
• --recipe <id>：只装某个 recipe（配方，声明工作流需要哪些能力，而非顺序）用到的 CLI；
• --only a,b：直接指定矩阵成员子集（逗号分隔）。

三者互斥，同时给出会报用法错误（resolve_install_scope 在 matrix.py 中显式检查）。安装前用 --dry-run 预览计划且零副作用：它会输出「将跳过哪些已装项、将经 pip/npm/uv 安装哪些、哪些不在注册表、哪些是 matrix install 管不到的（Python 库/原生二进制/云 API/agent 技能），并给出汇总数字与可复制的最终安装命令」（_render_dry_run，cli.py）。所有矩阵子命令都支持 --json。

安装失败后的两条补救路径：

# 重试上次失败的 CLI（只重试失败的，不重复安装成功的）
cli-hub matrix install <name> --resume

# 审计安装完整性：检查矩阵成员是否已安装、入口是否在 PATH
cli-hub matrix doctor <name>

--resume 依据 ~/.cli-hub/matrix_state.json 中上次安装的逐项结果，只挑出 status == "failed" 的成员重试，且不能与 --capability/--recipe/--only 混用（installer.py）；matrix doctor 则逐成员核对 installed.json 记录与入口可执行文件是否存在，给出 cli-hub install <name> 修复命令（installer.py）。

4.4 安装后：本地渲染的矩阵 SKILL.md

矩阵安装完成后，会在本地渲染一份「带环境事实」的 SKILL.md，路径为 ~/.cli-hub/matrix/<name>/SKILL.md，并把 references/ 与 scripts/ 资产复制到同目录，保证文档内相对链接可解析（cli-hub/cli_hub/matrix_skill.py）。渲染时注入的段落包括：Installed CLI Skills（成员 CLI 的入口、规范技能路径、本地技能路径、安装状态表）、Capability Provider Overview（每个能力的 provider、质量/成本/离线/安装状态与 requires）、Recipes 与 Known Gaps。技能内容的来源有三级查找链：仓库 checkout（cli-hub-matrix/<name>/）→ wheel 内置数据（cli_hub/_matrix_data/，由 cli-hub/setup.py 构建时从仓库根目录 cli-hub-matrix 同步打包）→ 发布 URL。也就是说：即便没有仓库检出，wheel 也自带矩阵内容；Agent 阅读本地渲染版即可拿到「这台机器上到底能用谁」的结论。

五、Live Catalog：自动更新的在线目录

SKILL.md 指向一个自动更新的在线目录，提供：按类别组织的完整 CLI 列表、每个工具一行式的 cli-hub install 命令、完整描述与用法模式。仓库内的 registry.json / public_registry.json / matrix_registry.json 即为注册表的离线镜像，cli-hub 运行时会优先拉取线上版本并按小时缓存。注意：目录是动态更新的，安装前用 cli-hub search / cli-hub list 拉到的才是当前最新列表。

六、预览消费（Preview Consumption）：harness 发布，hub 消费

部分 harness 支持预览工作流，SKILL.md 给出了清晰的分工：

• cli-anything-<software> preview ...：创建或更新真实的预览产物；
• cli-hub previews ...：检视、渲染、监听或打开这些已存在的产物。

典型用法：

# harness 侧：发布预览状态
cli-anything-blender --json --project scene.blend-cli.json preview capture --recipe quick

# cli-hub 侧：检视或打开生成的 bundle / 实时会话
cli-hub previews inspect /path/to/bundle-or-session
cli-hub previews html /path/to/bundle-or-session -o page.html
cli-hub previews watch /path/to/session --open
cli-hub previews open /path/to/bundle-or-session

对于实时会话（live session），cli-hub previews 读取三类文件：session.json（当前头部）、trajectory.json（追加式历史）、当前 bundle 的 manifest 与产物。inspect 会先判定目标是 bundle（含 manifest.json）还是 live session（含 session.json）再走不同渲染路径；watch / open 会渲染 live.html、起一个本地静态服务器并轮询（默认 --poll-ms 1500）刷新（cli.py，解析逻辑见 cli-hub/cli_hub/preview.py）。设计意图是「生成与消费解耦」：软件侧专注产出可核查的预览证据，hub 侧统一负责查看与打开。

七、完整使用流程（How to Use 六步）

SKILL.md 的标准流程总结为六步：

1. 安装 hub：pip install cli-anything-hub（要求 Python ≥ 3.10，依赖仅 click>=8.0 与 requests>=2.28，见 setup.py）；
2. 找到工具：cli-hub search <keyword> 或 cli-hub list -c <category>；
3. 安装：cli-hub install <name>（安装 cli-anything-<name> pip 包；公共 CLI 则走 npm/uv/command 策略）；
4. 运行：cli-anything-<name> 进入 REPL，或 cli-anything-<name> <command> 一次性执行；
5. JSON 输出：所有 CLI 都支持 --json 标志，输出机器可读结果供 Agent 解析；
6. 预览能力：可用预览的 CLI 先 cli-anything-<name> preview ... --json 发布，再用 cli-hub previews ... 检视或打开。

八、一个端到端示例工作流

# 安装 hub
pip install cli-anything-hub

# 找到需要的东西
cli-hub search video

# 安装它
cli-hub install kdenlive

# 用 JSON 输出使用它
cli-anything-kdenlive --json project create --name my-project

若任务更复杂（比如「给一段录屏加字幕转成成片」），则上升为矩阵用法：

# 1. 找到承载该能力的所有矩阵
cli-hub can "transcribe audio"

# 2. 对候选矩阵做预检，确认本机可用性（--fix-hints 给出补齐命令）
cli-hub matrix preflight video-creation -c text.transcribe --fix-hints

# 3. 只安装该能力需要的 CLI，而非 14 个全装；先用 --dry-run 预览零副作用
cli-hub matrix install video-creation --capability text.transcribe --dry-run
cli-hub matrix install video-creation --capability text.transcribe

# 4. 阅读本地渲染的矩阵 SKILL.md，按其 provider 选择规则干活

九、更多资料入口

• 每个软件的具体用法：仓库 skills 目录下的 cli-anything-<name>/SKILL.md（例如 skills/cli-anything-kdenlive/SKILL.md），registry.json 中每条记录也通过 skill_md 字段指向它；
• 矩阵的完整能力定义与配方：cli-hub-matrix/video-creation/SKILL.md 及其 references 参考模块、scripts/video_doctor.py；
• hub 全部源码：cli-hub/cli_hub（CLI 入口 cli.py、注册表 registry.py、矩阵逻辑 matrix.py、安装器 installer.py、技能渲染 matrix_skill.py），测试见 cli-hub/tests。

适用前提说明：cli-hub 的功能依赖网络可访问注册表与对应软件后端；harness 类 CLI 通常要求目标软件已安装（如 Kdenlive、OBS、GIMP），公共 CLI 与云 API provider 则需要相应运行时或 API 密钥。矩阵的 preflight 正是为回答「本机缺什么」而设计，建议作为每次矩阵任务的第一步。