Metadata-Version: 2.4
Name: ai-clihub
Version: 0.2.1
Summary: An AI-first registry for local command-line tools and reusable CLI scenarios.
Author: duo121
License-Expression: MIT
Project-URL: Documentation, https://github.com/duo121/clihub
Project-URL: Repository, https://github.com/duo121/clihub
Project-URL: Issues, https://github.com/duo121/clihub/issues
Keywords: cli,registry,ai,developer-tools,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# CLI Hub

[English README](README_EN.md)

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

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

## 安装

```bash
pipx install ai-clihub
```

安装后检查：

```bash
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 调用：

```bash
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 调用：

```bash
clihub list --json
```

AI 能拿到：

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

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

用户对 AI 说：

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

AI 调用：

```bash
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 调用：

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

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

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

### 5. 先预览再执行

用户对 AI 说：

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

AI 调用：

```bash
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 调用：

```bash
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
