用途:通过 tmux 分屏运行 ralph 并捕获实时输出,复现与调试 TUI 渲染问题,例如特定提供方导致的乱码、仅在实时出现的流式渲染异常、布局损坏,以及为缺陷报告采集 TUI 状态。
主要能力:用 tmux 识别当前窗格、创建与列出分屏窗格、在指定窗格中修正 shell、发送命令、捕获输出,以及退出或强制终止 TUI、关闭分屏。
必要用法与关键命令: 识别当前窗格:tmux display-message -p '#{session_name}:#{window_index}.#{pane_index}' 创建分屏:tmux split-window -h -t SESSION:WINDOW -c /path/to/repo 列出窗格:tmux list-panes -t SESSION:WINDOW 修正窗格内 shell:tmux send-keys -t PANE "exec /path/to/fish" Enter 发送命令:tmux send-keys -t PANE "command" Enter 捕获输出:tmux capture-pane -t PANE -p -S -60 退出 TUI:tmux send-keys -t PANE q 强制停止:tmux send-keys -t PANE C-c 关闭分屏:tmux kill-pane -t PANE 清理后启动:先 rm -f .ralph/loop.lock 与 git worktree prune;再以 target/release/ralph run -c CONFIG.yml -p 'prompt' --max-iterations N 启动(或用 cargo run --bin ralph -- run ...)。捕获前注意 Pi/Kiro 需 15-30 秒才开始流式输出。
常见限制与错误:分屏默认继承 tmux 服务器的 bash,工具可能 command not found,需切换到 fish;存在 .ralph/loop.lock 时会生成 worktree 循环;配置缺少 cli.backend: pi 时会改用 claude,缺少 hat 的 name 字段会导致配置解析错误;过早捕获看到空内容;TUI 已退出时发送 q 会成为下一条命令的前缀。