zhenyu CLI 智能体调用指南

总览与心智模型

zhenyu 是 MoneyPrinterTurbo 品牌化后的统一 CLI 入口，设计目标就是"人类和 AI Agent 都能用"。它把视频生成、任务管理、配置查询、声音/数字人枚举、环境自检、本地 RPC 全部收口到一个命令下。

CLI 有一条对 Agent 最关键的约定：每个子命令都支持 --json。加上 --json 后：
- stdout 永远是一行纯 JSON（即便内部有 loguru 噪声，也会被重定向后只回吐最后一行合法 JSON）；
- 退出码（exit code）直接表示成败：0 = 成功，非 0 = 失败；
- 失败时返回 {"ok": false, "error": "...", "hint": "..."}，hint 是可执行的下一步建议。

把固定三步法刻进流程，可规避绝大多数坑：先 health 自检 → 再 generate/do 生成 → 后 tasks show/retry 查状态与补救。

何时使用

• 生成短视频（一句话 NL 入口，或精确参数入口）
• 查看 / 重跑 / 删除历史任务
• 枚举可用 TTS 声音、数字人形象、当前配置
• 热改配置（如切换 LLM provider、设置 API Key）
• 让 Agent 通过本地 HTTP RPC 远程驱动 zhenyu（无 CLI 进程时）

调用方式（三选一）

<MPT_DIR> 指包含 zhenyu_cli.py 的目录（通常是 MoneyPrinterTurbo 仓库根）。必须在 <MPT_DIR> 内执行，否则 storage/、resource/ 等相对路径会解析错。

1. Windows 批处理包装（推荐人类/简单调用）
   zhenyu.bat / zhenyu.cmd 会自动设置 PYTHONPATH 并用自带 .venv\Scripts\python.exe 运行。
   bat cd /d "<MPT_DIR>" zhenyu.bat health --json

2. 直接调 Python（Agent 最可控，跨平台）
   bash cd "<MPT_DIR>" ".venv/Scripts/python.exe" zhenyu_cli.py tasks list --json
   在 Git Bash / POSIX 下把反斜杠改成 /，例如
   "<MPT_DIR>/.venv/Scripts/python.exe" zhenyu_cli.py do "生成 3 条竖屏女声视频" --json。

3. 本地 RPC 服务（远程 / 无本地进程时）
   先启动 zhenyu serve（默认 127.0.0.1:8600），再用 HTTP 调用，见下文"RPC 模式"。

> 凡是 Agent 调用，一律加 --json；人类阅读时可省略 --json 看表格化输出。

Agent 黄金规则

1. 永远加 --json：拿到纯净单行 JSON，靠 exit_code + ok 字段判成败。
2. 接入前先 health：自检 python / config / 状态后端 / LLM key / ffmpeg / 数字人，任何一项 FAIL 都先解决再生成。
3. 判成败看退出码与 ok：不要只看"有没有输出"。generate 在 JSON 模式下捕获 stdout，若内部不是合法 JSON，会回退成 {"ok": rc==0, "raw_output": "..."}——务必检查 exit_code。
4. 任务状态后端默认是 MemoryState（进程内）：CLI 进程 A 生成的任务，在进程 B（或 WebUI）里可能看不到，除非 config.toml 里 enable_redis = true。需要跨进程共享任务时先 config set app.enable_redis true 并重启。
5. 删除任务必须 --yes：不带 --yes 时会卡在 input() 等待确认；Agent 调用一律带 --yes（或 --json 下返回 code 2: 需要 --yes 确认删除）。
6. do 是规则解析，不是 LLM：毫秒级、零模型依赖，但只认识关键词表（见 references/cli-reference.md）。语义模糊或要精确控制时改用 generate。

推荐三步法（思路）

# 1) 自检（首次接入 / 环境变更后必跑）
zhenyu.bat health --json
# 确认 checks 全部 ok=true。重点看 llm.key_configured 与 ffmpeg。

# 2) 看现有任务，拿到可重试的 task_id
zhenyu.bat tasks list --json --size 20

# 3a) 快速生成（一句话，规则解析）
zhenyu.bat do "生成 3 条 60 秒竖屏女声讲解 AI 的视频" --json
# 或先 dry-run 预览解析结果，再决定是否真跑：
zhenyu.bat do "生成 3 条竖屏女声视频" --dry-run

# 3b) 精确生成（显式参数，最可控）
zhenyu.bat generate --video-subject "..." --video-count 3 --video-aspect 9:16 \
        --voice-name "zh-CN-XiaoxiaoNeural-Female" --stop-at video --json

# 4) 轮询状态
zhenyu.bat tasks show <id> --json
# state: -1=失败, 0=待处理, 1=完成, 4=处理中

# 5) 失败补救：用原参数原地重跑（从 storage/tasks/<id>/script.json 重建，跨进程安全）
zhenyu.bat tasks retry <id> --json
# 想保留原目录、作为新任务重跑：tasks retry <id> --as-new --json

子命令速查

完整参数表、do 的 NL 关键词映射、config set 示例，见 references/cli-reference.md。

错误处理

• 退出码约定：0 成功；非 0 失败。--json 下失败体为 {"ok": false, "error": "...", "hint": "..."}；exit_code 同样非 0。
• 常见失败与处置：
• health 中 llm FAIL → config set app.<provider>_api_key <KEY> 后重试。
• ffmpeg FAIL → 安装/配置 ffmpeg 路径（app.utils.utils.get_ffmpeg_binary()）。
• tasks show 返回"任务不存在" → 可能状态后端是 MemoryState 且任务在另一进程；改用 enable_redis=true 或同进程内查询。
• generate 回退 raw_output → 解析失败，检查 exit_code，必要时用 tasks retry。
• do 解析为空 → 换 generate 显式参数，或调整自然语言用关键词（见参考文档）。

RPC 模式（远程驱动）

适合"控制端没有 zhenyu 进程 / 要并发编排多个能力"的场景。

# 启动（后台常驻）
cd "<MPT_DIR>"
".venv/Scripts/python.exe" zhenyu_cli.py serve --port 8600

• POST /run body: {"args": ["tasks", "list", "--json"]} → 返回 {"exit_code": 0, "output": "<单行JSON>"}
• args 也接受字符串：{"args": "tasks list --json"} 会被 shlex 拆分。
• 所有命令内部强制追加 --json，便于机器消费。
• 禁止嵌套执行 serve 自身（返回 exit_code 400）。
• GET /health → {"ok": true, "service": "zhenyu"}
• 串行执行（内置锁），避免并发流水线互相污染。

Agent 通过 RPC 驱动时，把每次 POST /run 当成一次 CLI 调用：解析 exit_code 与 output 里的 JSON 即可。

常见踩坑速记

• 忘了加 --json → stdout 混入表格/日志，Agent 很难解析；统一加。
• 在错误目录执行 → storage/、resource/ 相对路径找不到；先 cd <MPT_DIR>。
• 以为 do 能理解任意中文 → 它是关键词匹配，长句/比喻会失效；精确需求走 generate。
• 跨进程看不到任务 → MemoryState 限制；开 enable_redis=true。
• config set 后 WebUI/serve 不生效 → 写回即生效于"下次 CLI 调用"，但运行中的 WebUI/serve 需重启才重载配置。
• tasks delete 不带 --yes → 卡在交互确认；Agent 必带 --yes。