ai-clihub 0.2.1

An AI-first registry for local command-line tools and reusable CLI scenarios.

CLI Hub

English README

clihub 是一个 AI 原生命令行工具，用来注册、发现和调用用户本机的 CLI 工具与场景。

• 主命令：clihub
• PyPI 包名：ai-clihub
• 安装方式：pipx install ai-clihub

安装

pipx install ai-clihub

安装后检查：

clihub --help
clihub list --json

用户只需要做什么

用户只需要用自然语言对 AI 提需求。

用户不需要学习这个 CLI。

典型提问方式：

• “调用 CLI Hub，帮我把命令 python3 -m http.server 注册起来。”
• “调用 CLI Hub，看看我之前注册过哪些工具。”
• “调用 CLI Hub，帮我找一个能开本地静态文件服务的命令。”
• “调用 CLI Hub，用之前注册过的文件服务工具，把 ./public 暴露出来。”
• “调用 CLI Hub，把下载视频和转 mp4 记成一个场景。”

AI 调用流程示例

1. 注册一个新命令

用户对 AI 说：

调用 CLI Hub，帮我把命令 python3 -m http.server 注册起来。

AI 调用：

clihub inspect "python3 -m http.server" --json
clihub register "python3 -m http.server" --id http-server --summary "Serve a local directory over HTTP." --tag web --capability http.serve --json

AI 能拿到：

• 原始命令
• 入口可执行文件
• help / version 探测结果
• usage 片段
• 自动摘要或人工补充摘要

2. 查看当前已经注册了什么

用户对 AI 说：

调用 CLI Hub，看看我现在都注册过什么工具。

AI 调用：

clihub list --json

AI 能拿到：

• 已注册 tool 列表
• 每个工具的 id
• 对应的原始命令
• 一句话用途摘要

3. 按用户意图匹配最合适的工具

用户对 AI 说：

调用 CLI Hub，帮我找一个能开本地静态文件服务的命令。

AI 调用：

clihub resolve "serve a local static file directory" --json
clihub show http-server --json

规则：

• AI 应该先 resolve，再 show
• 如果候选结果不唯一，AI 不应该猜
• AI 应该基于工具用途来匹配，而不是要求用户记住命令名

4. 用已注册工具真正执行任务

用户对 AI 说：

调用 CLI Hub，用之前注册过的文件服务工具，把 ./public 暴露出来。

AI 调用：

clihub resolve "serve ./public as a local file server" --json
clihub show http-server --json
clihub exec http-server -- --directory ./public

AI 最终实际运行的底层命令会是：

python3 -m http.server --directory ./public

5. 先预览再执行

用户对 AI 说：

调用 CLI Hub，用你找到的那个文件服务命令先给我看看会怎么执行。

AI 调用：

clihub resolve "serve ./public as a local file server" --json
clihub exec http-server --dry-run --json -- --directory ./public

规则：

• AI 可以先 dry-run，再真正执行
• dry-run 适合高风险操作或参数不确定时使用

6. 把多个命令步骤记成场景

用户对 AI 说：

调用 CLI Hub，把下载视频和转 mp4 这两个步骤记成一个场景。

AI 调用：

clihub scenario register ...
clihub scenario validate download-and-transcode --json
clihub scenario run download-and-transcode --dry-run --json

规则：

• 场景适合“多个命令组成的固定流程”
• AI 应该先 validate
• 真正执行前可以先 dry-run

AI 应该如何使用 CLI Hub

标准模式是：

1. 用户说“帮我记住这个命令”时，用 inspect + register
2. 用户说“我之前都注册过什么”时，用 list
3. 用户按用途找工具时，用 resolve
4. 需要看完整记录时，用 show
5. 真正执行时，用 exec
6. 需要多步骤流程时，用 scenario

给 AI 的规则：

• 优先使用 --json
• 注册前先 inspect
• 执行前优先 resolve
• resolve 结果不唯一时不要猜
• 需要底层命令细节时再 show
• 需要自检时先 --dry-run
• 如果工具不存在，就告诉用户先注册

命令

• inspect：检查一个原始命令，读取 help / version / usage
• register：把原始命令注册成可检索工具
• list：列出当前已注册工具或场景
• resolve：把用户意图匹配到具体工具
• show：查看某个工具或场景的完整记录
• exec：执行某个已注册工具
• doctor：实时检查工具状态
• refresh：重新探测并刷新工具记录
• scenario：注册、校验、预览、运行多步骤场景

License

MIT