qiaomu-model-cli

KO | EN

gitlite — search

#javascript #ai #machine-learning #linux #docker #macos #nodejs #windows #awesome-list #pytorch #openai #mcp #ios #open-source

qiaomu-model-cli

(★ 43)

并发调用本机 Grok 4.5、Kimi K3 与 Claude Code，带实时心跳和独立日志 | Concurrent local model CLI orchestration with live progress and isolated logs.

qiaomu-model-cli Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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)](https://raw.githubusercontent.com/joeseesun/qiaomu-model-cli/main/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/

---

# 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

qiaomu-model-cli

qiaomu-model-cli Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

qiaomu-model-cli

qiaomu-model-cli Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README