用途:当某项改动必须在真实 TUI 中验证(watch 模式、引擎状态标签、暂停/恢复、关闭/退出路径)而非依赖单元测试时,使用本技能。
构建与运行:先 cd 到 ralph-tui 目录执行 bun run build 生成 dist/cli.js,再运行 bun /path/to/ralph-tui/dist/cli.js run [flags](运行构建产物而非 dev,以匹配发布代码)。
临时追踪器:每次运行创建独立临时目录,避免复用仓库的 .beads。例如 export RALPH_TEST_DIR="$(mktemp -d ...)" 后 cd 进去,用 bd init 或 bd create 初始化;bd 命令必须在临时目录下执行,否则报 no beads database found。使用 --tracker beads 时必须提供 --epic <id>。
假 agent:插件放在 ~/.config/ralph-tui/plugins/agents/,echo.ts 立即返回 COMPLETE,slowecho.ts 以 500ms 分片休眠约 25s,便于测试迭代中暂停/退出。用 --agent echo / --agent slowecho 选择。
TUI 按键:s 开始、p 暂停/恢复、q→y 退出、d 仪表盘、r 刷新;状态标签有 Waiting、Selecting、Executing、Paused、Complete。
限制与陷阱:非 watch 模式任务完成后进程停留在 Complete,需 --no-tui/--headless 才会退出并打印摘要;中断路径依赖具体构建版本(#431 修复),旧版 Ctrl+C 可能无效;早期启动约 0.7s 内信号处理未安装,需多延迟测试并检查锁文件;Recovered stale session 与 Stale lock 不同;run --resume 可能因重复获取锁失败。外部创建任务后需等待一个轮询周期再判断自动拾取。无需任何外部凭证。