godotmaker-cli 0.2.0

package/README.zh-CN.md

@@ -0,0 +1,224 @@
+# godotmaker-cli
+
+> English: [README.md](./README.md)  ·  上手测试指南：[GETTING_STARTED.zh-CN.md](./GETTING_STARTED.zh-CN.md) ([English](./GETTING_STARTED.md))
+
+[GodotMaker](https://github.com/RandallLiuXin/GodotMaker) 的 pipeline 驱动 —— 一个 AI 辅助的文本到 Godot 游戏生成器。本包附带一个 Ink TUI，跨多个独立的选中 agent 会话编排上游 `/gm-*` skill 链，所以你可以 `cd` 到一个空文件夹、跑一条命令，然后看一个 Godot 项目自己长出来。
+
+> 专有软件。你可以安装并使用官方分发版本来创建 Godot 游戏项目；不允许再分发、
+> 反向工程，或用于构建竞争性商业平台。生成的游戏项目和资产归你所有；详见
+> [LICENSE](./LICENSE)。
+
+---
+
+## 环境要求
+
+| 工具 | 版本 | 用途 |
+|---|---|---|
+| Node.js | 22+ | 运行 CLI（Ink 7 要求 Node 22 或更新） |
+| [Claude Code CLI](https://docs.claude.com/en/docs/claude-code) 或 Codex CLI | latest | 选中的 agent 二进制必须在 PATH 上 |
+| [Godot](https://godotengine.org/) | 4.x | 运行生成出来的项目 |
+
+CLI 会在 preflight 时把 GodotMaker framework 自动 publish 到项目里；framework 版本由 `cliConfig.pinnedGodotmakerVersion` 决定（当前 `v0.5.0`）。
+
+---
+
+## 安装
+
+```bash
+npx godotmaker-cli
+# 或者全局安装
+npm install -g godotmaker-cli
+```
+
+本地开发时，从 checkout 运行：
+
+```bash
+npm install
+npm run build
+node cli/dist/run.js --help
+```
+
+下面的示例使用全局 `godotmaker-cli` 命令。如果你用 `npx`，把它替换成
+`npx godotmaker-cli`。
+
+---
+
+## 快速开始
+
+```bash
+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`） |
+| `/peek` | 实时尾巴（1 Hz）查看当前非交互 agent stream 日志 |
+| `/usage` | 当前运行 + 项目累计 token / 花费 / 时长 |
+| `/quit` | 退出。运行中按下也会顺手 abort 选中 agent 并写 resume 检查点（跟 Ctrl-C 同一条路），下次 `godotmaker-cli` 启动 `/start` 即可从中断处恢复。 |
+
+当前 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 记录；费用只有在选中 agent 报告时才显示，否则显示
+`--`。数据持久化到 `.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` 会从保存的检查点**恢复**：
+
+```bash
+godotmaker-cli           # 从上次停下的地方继续
+```
+
+要从头开始：
+
+```bash
+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](https://github.com/RandallLiuXin/GodotMaker)
+- Roadmap：[`ROADMAP.md`](https://github.com/RandallLiuXin/GodotMakerApp/blob/main/ROADMAP.md)（私有）
+- 设计笔记：[`docs/design/cli-design.md`](https://github.com/RandallLiuXin/GodotMakerApp/blob/main/docs/design/cli-design.md)（私有）