godotmaker-cli

English: README.md · 上手测试指南：GETTING_STARTED.zh-CN.md (English)

GodotMaker 的 pipeline 驱动 —— 一个 AI 辅助的文本到 Godot 游戏生成器。本包附带一个 Ink TUI，跨多个独立的选中 agent 会话编排上游 /gm-* skill 链，所以你可以 cd 到一个空文件夹、跑一条命令，然后看一个 Godot 项目自己长出来。

专有软件。你可以安装并使用官方分发版本来创建 Godot 游戏项目；不允许再分发、 反向工程，或用于构建竞争性商业平台。生成的游戏项目和资产归你所有；详见 LICENSE。

环境要求

| 工具 | 版本 | 用途 | |---|---|---| | Node.js | 22+ | 运行 CLI（Ink 7 要求 Node 22 或更新） | | Claude Code CLI 或 Codex CLI | latest | 选中的 agent 二进制必须在 PATH 上 | | Godot | 4.x | 运行生成出来的项目 |

CLI 会在 preflight 时把 GodotMaker framework 自动 publish 到项目里；framework 版本由 cliConfig.pinnedGodotmakerVersion 决定（当前 v0.7.0）。

安装

npx godotmaker-cli
# 或者全局安装
npm install -g godotmaker-cli

本地开发时，从 checkout 运行：

npm install
npm run build
node cli/dist/run.js --help

下面的示例使用全局 godotmaker-cli 命令。如果你用 npx，把它替换成 npx godotmaker-cli。

快速开始

mkdir my-pong-game && cd my-pong-game
godotmaker-cli

TUI 会在 preflight 后进入 idle。输入 /start 后走完 9 个阶段的 pipeline；结束后按 q 退出。需要启动后立刻开跑时传 --auto-start。

┌─ godotmaker-cli ───────────────────────────────────┐
│ /home/user/my-pong-game                            │
│ iter 1/3   build 1/3   eval --                     │
├────────────────────────────────────────────────────┤
│ ✓  scaffold     0:04                               │
│ ✓  gdd          1:12                               │
│ ✓  asset        0:38                               │
│ ▶  build        0:21                               │
│    verify       --                                 │
│    evaluate     --                                 │
│    fixgap       --                                 │
│    accept       --                                 │
│    finalize     --                                 │
├─ session ──────────────────────────────────────────┤
│ [tool] Bash                                        │
│ [agent] Implementing Pong scene per PLAN.md...     │
│ [tool] Write src/Ball.gd                           │
└────────────────────────────────────────────────────┘
running… (/pause to pause, Ctrl-C to exit; /help for commands)

交互阶段

scaffold、gdd、accept 需要用户输入（游戏名、设计问题、accept / fix / done 决定）。当 pipeline 进到这些阶段时，TUI 挂起、把终端交给一个新的选中 agent 会话、那个会话退出后恢复 —— 跟 git commit 打开 $EDITOR 是同一种模式。会有短暂屏幕闪烁，是预期行为。

生命周期

cli 启动后进入 idle 状态，显示 preflight 摘要（框架版本、选中 agent 探测、 pipeline 参数）。输入 /start 才会真正开跑。pause 之后再次 /start 从中断处恢复。需要跳过 idle 直接开跑就传 --auto-start —— stdin 不是 TTY 时（CI、管道自动化）会自动启用。

快捷键

| 键 | 效果 | |---|---| | q | 输入栏为空且 pipeline 不在运行时退出（idle / paused / finished / failed 都可用） | | Ctrl-C | 退出。运行中按下时，cli 的 unmount-cleanup 钩子会顺手杀掉当前选中 agent 子进程，并把 resume 检查点写入 pipeline_state.json，下次 godotmaker-cli 启动 /start 即可从中断处继续。不退出只暂停（cli 保持挂载、可立即 /start 恢复）请用 /pause slash 命令。 |

Slash 命令

TUI 底部有一个常驻输入栏。输入下面任一命令然后回车：

| 命令 | 效果 | |---|---| | /help | 列出所有命令和快捷键 | | /start | 启动（或 pause 后恢复）pipeline | | /pause | 暂停正在运行的 pipeline；下次 /start 从中断处恢复 | | /refresh | 重置当前 run 的 iteration / build 预算；允许在 idle / paused / finished / failed 状态使用（running 中需先 /pause） | | /goto <state> | 手动设置下一次 /start 的 resume 目标；允许在 idle / paused / failed 状态使用 | | /peek | 实时尾巴（1 Hz）查看当前非交互 agent stream 日志 | | /usage | 当前运行 + 项目累计 token / 时长 | | /quit | 退出。运行中按下也会顺手 abort 选中 agent 并写 resume 检查点（跟 Ctrl-C 同一条路），下次 godotmaker-cli 启动 /start 即可从中断处恢复。 |

/goto 是手动恢复 override。合法 state 是 scaffold、gdd、asset、 build、verify、evaluate、fixgap、accept、finalize。

当前 iteration / build try / 最近一次评估的 verdict 都直接显示在 TUI 顶部的 Header 里，没有单独的 overlay。eval 单元格在 approve 时显示 ✓ approved（绿色），reject 时显示 ✗ Nc+Mm（黄色，N/M 分别是 critical / major issue 数量），还没跑过 /gm-evaluate 时显示 --。

任意键关闭一个打开的 overlay。Esc 清空输入栏。未识别的命令会显示一个临时消息，下次按键清掉。

输入 / 会在输入栏正下方弹出实时建议列表，列出所有以你已输入字符开头 的命令。Up / Down 上下选择（环形回绕），Tab 把高亮命令补全到 输入栏（不执行），Enter 直接补全并执行高亮命令（也就是说 /h + Enter 直接跑 /help）。匹配区分大小写 —— /H 不会匹配 /help，与 parser 行为一致。前缀没匹配时建议列表自动隐藏，此时 Enter 会照常给出 unknown command — try /help 提示。

/peek 仅在非交互态（build / verify / asset / evaluate / fixgap / finalize）下有意义 —— 这些状态里 选中 agent 以非交互模式运行由 cli 托管。 交互态（scaffold / gdd / accept）里 交互 agent 直接接管终端，cli 没有任何 可窥探的东西；这种时候敲 /peek 会看到 "no active agent session to tail" 提示。Overlay 每秒刷新一次；任意键关闭。

/usage 分三块显示：当前运行（按 state 拆分的实时 token / 输出 / 时长）、项目累计（自首次运行以来的总和）和 最近运行 （最近 10 次完成的运行，每次一行）。Token 来自选中 agent 的 stream 或本地 session 记录。数据持久化到 .godotmaker/usage.json（紧挨着 pipeline_state.json）—— 把这个文件跟项目一起搬迁就能保留历史。 交互态（scaffold / gdd / accept）会尽力从本地 session 记录恢复 token， 并始终贡献时长。Header 始终展示当前运行的简写总数，/usage 用来看细节。

Flags

| Flag | 效果 | |---|---| | --agent <claude-code\|codex> | 为本次启动选择 agent runtime，覆盖项目配置和 CLI 全局配置 | | --max-iterations <n> | Generator-Evaluator 迭代次数上限（默认 3） | | --model <name> | 覆盖 build / evaluate 用的 agent model（默认值取决于 --agent） | | --fresh | 清掉保存的状态，重新开始 | | --dry-run | 不启动 agent 走完 pipeline（写 stub 产物；用于 CI / 接线检查） | | -h, --help | 打印帮助并退出 |

Agent 选择优先级是：--agent、项目 .godotmaker/config.yaml、 ~/.godotmaker/cli/config.yaml，最后才是默认 claude-code。

Spawn 出来的非交互 agent 会话的 idle-timeout（默认 900 秒 = 15 分钟）在 ~/.godotmaker/cli/config.yaml 里配 idle_timeout_seconds，不走命令行 flag。timer 在每次收到 stdout/stderr 时刷新，只有真静默才会触发 kill。

Pipeline 写出的文件

都在你项目下的 .godotmaker/ 目录里：

| 文件 | 写者 | 用途 | |---|---|---| | pipeline_state.json | Core | resume 检查点（当前 state、iteration、build 尝试次数） | | stage.jsonl | 上游 skill | 每个 /gm-* 完成一行；Core 做 freshness 检查 | | evaluation.json | /gm-evaluate | 最近一次的二元 verdict + 分类 issue；evaluate → accept / fixgap 路由依据 | | final_report.json | /gm-finalize | 成功跑完的总结 | | usage.json | Core | /usage 用的 token / 时长历史（lifetime 累计 + 最近 10 次运行）—— 见 R-314 | | config.yaml | （可选，由你写） | 项目级 flag 默认值 —— 见 core 里的 loadConfig |

Godot 项目本身（project.godot、GDD.md、PLAN.md、scenes、scripts、…）放在项目根目录，由上游 skill 拥有，Core 永不写它们。

Resume vs fresh

默认情况下，在同一目录再次运行 godotmaker-cli 会从保存的检查点恢复：

godotmaker-cli           # 从上次停下的地方继续

要从头开始：

godotmaker-cli --fresh   # 删除 pipeline_state.json + stage.jsonl + evaluation.json + final_report.json

用户写的文件（GDD.md、PLAN.md、scenes、scripts）--fresh 不会动。

Dry-run 模式

--dry-run（或环境变量 GMA_DRY_RUN=1）让 CLI 走完整个状态图但不启动 agent。Stub 处理器写出每个 /gm-* skill 本应产生的产物（project.godot、GDD.md、evaluation.json、final_report.json，加上对应的 stage.jsonl 事件），让 pipeline 跑到 finalize。用它来：

• 不烧 token 验证你的安装（Node / 路径 / config）
• 给 CI 配管做 pre-flight
• 没有 agent 账号也能演示 TUI

Stub 永远走 happy path（verify=pass、evaluate=approve、accept=accept）；要触发 fail / fixgap 分支必须用真实选中 agent 会话。

故障排除

选中 agent CLI 不在 PATH 上 —— 安装选中 agent CLI 然后重新打开终端。用 claude --version 或 codex --version 验证。

Pipeline 卡在 scaffold、project.godot 没出现 —— /gm-scaffold 非零退出。检查上游 skills 装好了、选中 agent 也认证了。

崩溃后再跑读到陈旧的 stage 事件 —— 用 --fresh 清掉 .godotmaker/stage.jsonl 重新开始。

TUI 看起来坏了 / 行被截断 —— TUI 需要真实 TTY。管道（godotmaker-cli | tee log）或者 CI runner 没 PTY 的环境目前不支持。

链接

• 上游框架：GodotMaker
• Roadmap：ROADMAP.md（私有）
• 设计笔记：docs/design/cli-design.md（私有）