---
name: Qiaomu Model CLI
slug: qiaomu-model-cli
category: AI Engineering
description: A CLI wrapper for running local Grok, Kimi Code, and Claude Code CLIs with their strongest default models. Supports concurrent batch jobs, dependent dual pipelines, artifact verification, and retries for AI agent workflows.
github: "https://github.com/joeseesun/qiaomu-model-cli"
language: Python
stars: 42
forks: 8
install: "npx degit https://github.com/joeseesun/qiaomu-model-cli ~/.claude/skills/qiaomu-model-cli"
installs_to: ~/.claude/skills/qiaomu-model-cli
source_path: SKILL.md
collection_size: 1
category_size: 2451
added: 2026-08-11T07:21:27.369Z
last_synced: 2026-08-11T07:21:27.369Z
canonical_url: "https://dirskills.com/skills/qiaomu-model-cli"
---

# Qiaomu Model CLI

A CLI wrapper for running local Grok, Kimi Code, and Claude Code CLIs with their strongest default models. Supports concurrent batch jobs, dependent dual pipelines, artifact verification, and retries for AI agent workflows.

**Install:**

```bash
npx degit https://github.com/joeseesun/qiaomu-model-cli ~/.claude/skills/qiaomu-model-cli
```

## README

# qiaomu-model-cli

> 在 Agent 里稳定调用本机 **Grok CLI（grok-4.5）**、**Kimi Code CLI（K3 1M）** 和 **Claude Code CLI（默认 Fable 5）**：支持真正并发、原生流事件、产物验收、中断清理与失败项重试。

**中文** | [English](#english)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)

## 为什么值得用

- 不想每次手写 `grok -p ...` / `kimi -p ...` / `claude -p ...` 参数
- 需要 Grok 原生能力：实时搜索、X 检索、`image_gen`/`/imagine`、`/imagine-video`
- 需要 Kimi K3 1M 做前端 UI/CSS/组件实现
- 需要 Claude Fable 5 / Opus 4.8 / Sonnet 5 做复杂编码、重构或 review
- 希望有明确路由：什么时候用 Grok、Kimi 或 Claude
- 希望三个模型真正同时开工，而不是调用端逐个等待且长时间没有进度
- 希望“退出码 0”之外还能检查页面、文件和构建命令是否真的完成
- 希望中断后不留后台进程，并且只重跑失败项

## 安装

```bash
npx skills add joeseesun/qiaomu-model-cli
```

验证：

```bash
ls ~/.agents/skills/qiaomu-model-cli
python3 ~/.agents/skills/qiaomu-model-cli/scripts/check_env.py
```

## 你可以这样说

- “用 grok cli 搜一下 @vista8 最近 3 条帖子”
- “用 grok 4.5 生成一张产品海报”
- “用 kimi k3 把这个 landing page 前端重做成杂志感”
- “先用 grok 查资料，再用 kimi 写前端单页”
- “用 Claude Code 的 Fable 5 完成这个多文件重构”
- “用 Opus 4.8 review 这个分支，不要改文件”
- “分别用 Grok 4.5、Kimi K3 和 Claude Opus 4.8 各做一版，并排比较”
- “检查一下本机 grok/kimi/claude cli 是否可用”

## 它会做什么

1. 路由任务到 Grok、Kimi 或 Claude
2. 默认使用强模型：`grok-4.5` / `kimi-code/k3` / Claude `fable`
3. 为搜索、生图、生视频、前端和复杂编码任务注入对应提示词
4. 独立任务用 `batch` 并发启动；有数据依赖的任务用 `dual` 顺序衔接
5. 默认解析三家 CLI 的原生 JSON 流，立即输出安全的生命周期、工具和活动事件
6. 用 `expects` / `verify_commands` 做 Done Gate，避免“模型说完成但文件不存在”
7. `Ctrl-C` 终止全部活动进程组；`retry --summary` 只执行失败 job
8. 内存只保留有限输出尾部，完整日志以私有权限持续落盘

## 默认模型

| CLI | 默认模型 | 典型场景 |
|---|---|---|
| `grok` | `grok-4.5` | X/Web 搜索、研究、生图、生视频、通用 agent |
| `kimi` | `kimi-code/k3`（1M context） | 前端 UI/CSS/React/Vue、长上下文改码 |
| `claude` | `fable`（Fable 5） | 最复杂的编码、推理和长任务 |

Claude Code 也可显式使用 `--model opus`（当前 Opus 4.8）或 `--model sonnet`（当前 Sonnet 5）。动态别名会跟随各系列最新版本；要完全复现时再使用完整模型 ID。

## 快速开始

```bash
# 环境检查
python3 scripts/check_env.py

# Grok：X/实时搜索
python3 scripts/qiaomu_model_cli.py grok --task x-search --prompt "查 @openai 最新一条主帖，给正文和链接"

# Grok：生图
python3 scripts/qiaomu_model_cli.py grok --task image --prompt "极简黑白 AI coding 海报"

# Grok：生视频
python3 scripts/qiaomu_model_cli.py grok --task video --prompt "一只猫在爵士酒吧弹钢琴"

# Kimi：前端
python3 scripts/qiaomu_model_cli.py kimi --task frontend --prompt "优化 hero 区层级和移动端间距" --cwd .

# Claude：最强模型做复杂编码（默认 Fable 5）
python3 scripts/qiaomu_model_cli.py claude --task coding --prompt "完成多文件重构并跑项目测试" --cwd .

# Claude：指定 Opus 4.8 或 Sonnet 5 系列
python3 scripts/qiaomu_model_cli.py claude --model opus --task review --prompt "审查当前分支，不要改文件" --cwd .
python3 scripts/qiaomu_model_cli.py claude --model sonnet --task frontend --prompt "修复移动端布局" --cwd .

# Grok / Kimi / Claude 各做一份：一次调用并发启动
python3 scripts/qiaomu_model_cli.py batch \
  --config examples/batch-homepages.json \
  --max-workers 3 \
  --log-dir logs/model-run

# 只重跑上次失败的 job
python3 scripts/qiaomu_model_cli.py retry \
  --summary logs/model-run/summary.json \
  --log-dir logs/model-retry
```

## 并发与依赖

`batch` 只用于彼此独立的任务，例如三家模型各写一份页面、各做一次 review。每个写入型 job 必须使用独立 `cwd`，避免互相覆盖。配置示例见 [`examples/batch-homepages.json`](examples/batch-homepages.json)。

```text
独立：Grok ─┐
      Kimi ─┼─ 同时启动 → 各自日志 → summary.json
    Claude ─┘

依赖：Grok 研究 → Kimi 接收研究结果后实现
```

`dual` 是第二种情况，因此保持串行。把独立横评误用成 `dual`，或在调用端连续跑三个单命令，都会浪费等待时间。

`batch` 的 `prompt_file` 与 `cwd` 相对配置文件解析。配置可用顶层 `defaults` 复用公共字段。每次运行会生成：

```text
<job>.stdout.log
<job>.stderr.log
<job>.response.txt
<job>.result.json
<job>.verify-N.stdout.log
<job>.verify-N.stderr.log
events.jsonl
state.json
run-config.json
summary.json
```

进度以脱敏 JSONL 写到 `stderr`，完整规范化事件写入 `events.jsonl`。默认每 15 秒一次 heartbeat；它证明进程仍存活，但最终成功仍由 Provider 退出码和 Done Gate 共同决定。原始流可能含任务正文，因此 run 目录是 `0700`，文件是 `0600`。

**2026-07-21 实测：** 同一 batch 中三个真实 CLI 的 `started` 事件落在 2 ms 内；Kimi K3 用时 8.514 秒、Claude Opus 用时 10.128 秒、Grok 4.5 用时 28.281 秒，最终 3/3 成功。总等待由最慢任务决定，不再把三家耗时相加。

## Done Gate 与失败重试

文件任务建议在每个 job 或 `defaults` 中声明验收条件：

```json
{
  "defaults": {
    "native_stream": true,
    "expects": [{"path": "index.html", "min_bytes": 1000}],
    "verify_commands": [
      {"argv": ["npm", "run", "build"], "timeout": 180}
    ]
  },
  "jobs": [
    {"id": "kimi", "provider": "kimi", "task": "frontend", "prompt": "写个人主页", "cwd": "./work/kimi"}
  ]
}
```

`expects` 只能指向 job 的 `cwd` 内部；`verify_commands` 是 argv 数组，不经过 shell。Provider 成功但验收失败时 job 返回 code `3`。修正环境后运行：

```bash
python3 scripts/qiaomu_model_cli.py retry --summary logs/model-run/summary.json
```

重试会读取私有 `run-config.json`，筛选失败 job，并创建新的 run 目录；成功结果不会重复消耗时间和额度。

## 扩展 Provider

三家差异已拆到 `scripts/qmc/providers/`。新增 Provider 只需实现 `ProviderAdapter` 的命令构造、任务校验和流事件解析，再在 registry 注册；批调度、日志、取消、验收和重试无需改动。完整约束见 [`references/provider-adapters.md`](references/provider-adapters.md)。

## 前置条件

- [ ] 已安装 Grok CLI，并可执行 `grok --version`
- [ ] 已登录 Grok（`grok login` 或有效 `XAI_API_KEY`）
- [ ] 已安装 Kimi Code CLI，并可执行 `kimi -V`
- [ ] 已登录 Kimi（`kimi login`）
- [ ] 已安装 Claude Code，并可执行 `claude --version`
- [ ] Claude 登录/Provider 可用（`claude auth status`）
- [ ] Python 3.10+

## 输出示例

```text
provider: grok
model: grok-4.5
task: x-search
status: ok
---
1. 2026-07-21 ...
正文...
链接: https://x.com/...
```

```text
provider: claude
model: fable
task: coding
status: ok
---
Changed: src/..., tests/...
Verified: project tests passed
```

## 风险与边界

- 会调用本机已登录的 Grok/Kimi/Claude 账号能力，可能产生模型与媒体生成成本
- 不读取、不输出 token/cookie/auth.json 明文
- 不保证第三方 CLI 版本永远兼容；参数以本机 `--help` 为准
- Claude 的 `bypassPermissions` 可直接执行命令和修改工作区，只应在可信项目中使用；可用更严格权限模式覆盖
- 搜索/生图/生视频必须以 CLI 实际返回为准，禁止编造

## Troubleshooting

| 症状 | 可能原因 | 处理 |
|---|---|---|
| `grok: command not found` | 未安装或不在 PATH | 安装 Grok CLI，并确认 `~/.local/bin` 等在 PATH |
| Grok 要求登录 | 凭证过期 | 运行 `grok login` |
| `kimi: command not found` | 未安装 Kimi Code | 安装后确认 `kimi -V` |
| Kimi 报 cannot combine `--prompt` with `--yolo/--auto` | 当前 CLI 限制 | 只用 `-p`，不要叠 yolo/auto |
| `claude: command not found` | 未安装 Claude Code | 安装/更新后确认 `claude --version` |
| Claude 别名存在但调用卡住 | 登录、网关或 Provider 不支持当前模型 | 跑 `claude auth status` 和 `claude doctor`，不要把别名检测当成调用成功 |
| Fable 对部分任务回退到 Opus | Fable 5 的安全分类器触发 | 如实报告回退；不要声称全程由 Fable 完成 |
| 生图/生视频无产物 | 工具不可用、权限或安全拦截 | 查看 CLI 原文错误；重试或换任务描述 |
| X 搜索结果空 | 网络/权限/检索失败 | 跑 `python3 scripts/check_env.py`，再用更具体 query 重试 |
| 多模型任务只有第一家在跑 | 调用端逐个执行单命令 | 改用一个 `batch --config ... --max-workers N` 调用 |
| 日志长时间不更新 | Provider 尚未产生原生流事件 | 看 heartbeat 判断存活；原始 stdout/stderr 仍持续落盘 |
| 一个模型超时或中断后仍有子进程 | 旧版未统一管理进程组 | 升级到 1.3.0；超时、`Ctrl-C` 和退出都会清理活动进程组 |
| 并发模型互相覆盖文件 | 多个写入 job 共用 cwd | 为每个 job 创建独立目录或 worktree；不要共享写入目录 |
| CLI 返回成功但网页不存在 | 仅检查了退出码 | 在 job 中加入 `expects` 和 `verify_commands` |
| 只想重跑失败模型 | 再次执行了整个 batch | 使用 `retry --summary <上次 summary.json>` |

## 目录结构

```text
qiaomu-model-cli/
├── SKILL.md
├── README.md
├── agents/interface.yaml
├── manifest.json
├── references/
├── scripts/
│   └── qmc/providers/
├── examples/
├── tests/
├── evals/
└── reports/
```

## 致谢

- xAI Grok CLI
- Moonshot Kimi Code CLI
- Anthropic Claude Code CLI
- Qiaomu skill packaging conventions

## License

MIT

## 联系

- 向阳乔木 / Joe
- X: https://x.com/vista8
- GitHub: https://github.com/joeseesun/

---

<a id="english"></a>

# English

> A Qiaomu agent skill for calling local **Grok CLI (grok-4.5)**, **Kimi Code CLI (K3 1M)**, and **Claude Code CLI (Fable 5 by default)** with concurrent fan-out, native stream events, artifact gates, reliable cancellation, and failed-job retry.

## Install

```bash
npx skills add joeseesun/qiaomu-model-cli
python3 ~/.agents/skills/qiaomu-model-cli/scripts/check_env.py
```

## Defaults

- Grok: `grok-4.5` for live search, research, image/video, multi-tool agent work
- Kimi: `kimi-code/k3` (1M context) for frontend UI work
- Claude: `fable` (Fable 5) for maximum capability; `opus` (Opus 4.8) and `sonnet` (Sonnet 5) as explicit alternatives

## Quick start

```bash
python3 scripts/qiaomu_model_cli.py grok --task x-search --prompt "..."
python3 scripts/qiaomu_model_cli.py kimi --task frontend --prompt "..." --cwd .
python3 scripts/qiaomu_model_cli.py claude --task coding --prompt "..." --cwd .
python3 scripts/qiaomu_model_cli.py batch --config examples/batch-homepages.json --max-workers 3
python3 scripts/qiaomu_model_cli.py retry --summary logs/model-run/summary.json
```

Use `batch` for independent jobs and a separate cwd for every writer. Declare `expects` and argv-only `verify_commands` for generated artifacts. Use `dual` only when Kimi must consume Grok's output. Run artifacts are private, memory capture is bounded, and `retry` executes only failed jobs from a prior summary.

## Boundaries

No secret printing. No fabricated search/media results. No direct `main` pushes from this skill.

## License

MIT