第十章：可视化监控——实时掌握 AI 工作进度
📌 本章李明轩在做什么：早上 10:30 公司茶水间，他想瞄一眼"昨晚启动的 4 个循环现在跑成什么样了"。他不可能掏出 MacBook，只能掏手机。Ralph 的 Web 仪表盘就是为这种"人在别处"的场景准备的。
为什么需要可视化
当你告诉 Ralph"去实现这个功能"，然后去做别的事情，你心里可能会有些不安：
- AI 现在在做什么？
- 进行到哪一步了？
- 有没有遇到什么问题？
- 什么时候能完成？
Ralph 提供了两种监控方式：终端界面（TUI）和 Web 仪表盘。
终端界面（TUI）
当你运行 ralph run 时，默认会进入终端界面模式。TUI 由三个区域组成：
[iter 8/150] [LIVE] ⚙️ Builder 12:34 main
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
（AI 实时输出内容在这里滚动显示）
Running: python -m pytest...
test_upper_conversion ... ok
test_lower_conversion ... ok
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
:（输入 : 可以发送实时指引给 AI）
- 顶部 Header：
[iter 当前/最大]迭代计数 ·[LIVE]实时运行 · 当前活跃帽子 · 已用时间 · Git 分支 - 中间内容区：AI 的实时输出流，用
j/k上下滚动，g/G跳顶部/底部 - 底部 Footer：
:输入指引发给 AI；!发送紧急指引（AI 必须先确认才能继续）
TUI 快捷键
| 按键 | 功能 |
|---|---|
h / ← | 查看上一次迭代的输出 |
l / → | 查看下一次迭代的输出 |
j / ↓ | 向下滚动输出内容 |
k / ↑ | 向上滚动输出内容 |
g | 滚动到顶部 |
G | 滚动到底部（最新） |
m | 切换鼠标模式 |
/ | 开始搜索输出内容 |
n / N | 搜索结果的下一个/上一个 |
: | 发送实时指引（下次迭代时 AI 会看到） |
! | 发送紧急指引（阻塞直到 AI 确认） |
w | 进入波浪并行工作者视图 |
q | 退出 TUI（循环继续在后台运行） |
? | 显示帮助 |
不想用 TUI？
如果你只想让 Ralph 跑完再收结果（比如写脚本跑在 CI、或者无头服务器上），可以关掉 TUI 观察模式：
# 方式一：headless 自治模式，命令跑完才返回
ralph run --autonomous -p "任务描述"
# 方式二：只关 TUI，但保留交互通道
ralph run --no-tui -p "任务描述"
⚠️
--autonomous与--no-tui是互斥的，不要同时加；Ralph 会直接报错。--autonomous适合完全无人值守的流水线，--no-tui适合你仍想通过事件注入等方式干预但不要终端花屏幕的场景。
Web 仪表盘（Alpha 功能）
除了终端界面，Ralph 还提供了一个基于 Web 的可视化仪表盘（目前标记为 Alpha 版本，功能仍在积极开发中）。
启动 Web 仪表盘
# 在一个单独的终端窗口启动仪表盘
ralph web
# 输出：
# 🌐 Ralph Web Dashboard starting...
# 📡 API server: http://localhost:3000
# 🖥️ Dashboard: http://localhost:5173
#
# Dashboard opened in browser automatically.
Ralph 会自动打开浏览器，显示仪表盘界面。
常用选项
# 不自动打开浏览器
ralph web --no-open
# 使用自定义端口
ralph web --backend-port 4000
# 指定监控的工作区
ralph web --workspace /path/to/your/project
仪表盘的主要功能
循环概览
仪表盘首页显示所有正在运行或已完成的循环：
┌────────────────────────────────────────────────────────────────┐
│ Ralph Dashboard 🟢 2 active loops │
├────────────────────────────────────────────────────────────────┤
│ Loop #1 Active [8 iter] │
│ Prompt: "实现用户登录功能" │
│ Backend: claude │
│ Current: ⚙️ Builder (step-02:auth-logic) │
│ Started: 12 min ago │
│ ───────────────────────────────────────────────────── │
│ Loop #2 Active [3 iter] │
│ Prompt: "修复 CSS 样式问题" │
│ Backend: kiro │
│ Current: 📋 Planner (analyzing) │
│ Started: 5 min ago │
└────────────────────────────────────────────────────────────────┘
事件流图
点击某个循环，可以看到事件流的可视化图表，用 XYFlow 渲染的流程图，清晰展示哪个帽子激活过、事件是如何流动的：
work.start ──► 📋 Planner ──► tasks.ready ──► ⚙️ Builder ──► review.ready
│
▼
❌ review.rejected
│
▼
⚙️ Builder (retry)
│
▼
✓ review.ready
│
▼
🧪 Critic ──► review.passed
│
▼
🏁 Finalizer
记忆查看器
在仪表盘里可以直接查看和编辑记忆文件，不需要打开终端：
Memories Editor
─────────────────────────────────────────────
## Project Patterns [编辑]
- 使用 FastAPI + SQLAlchemy
- 测试使用 pytest-asyncio
## Fixes Applied [编辑]
- SSL 证书配置...
[+ 添加新记忆] [清理旧记忆]
任务管理
Tasks
─────────────────────────────────────────────
✓ step-01:scaffold 完成 2m前
⟳ step-02:auth-logic 进行中
○ step-03:tests 等待中
○ step-04:deployment 等待中
[手动关闭] [重新打开] [删除]
后台运行与监控
有时候你想启动 Ralph 后完全离开终端（比如晚上下班前启动一个长任务，第二天回来检查结果）：
# 在后台运行 Ralph（使用 nohup 或 screen/tmux）
nohup ralph run -p "重构整个认证模块" > ralph.log 2>&1 &
# 或者用 screen（推荐）
screen -S ralph-session
ralph run -p "重构整个认证模块"
# Ctrl+A, D 脱离 screen 会话
# 第二天回来查看
screen -r ralph-session
# 第二天早上查看循环状态
ralph loops
# 输出示例：
# ID STATUS ITERATIONS RUNTIME DESCRIPTION
# loop-abc ✓ complete 47 2h 13m 重构整个认证模块
#
# Last event: LOOP_COMPLETE
# Output in: .ralph/loops/loop-abc/
诊断模式
当你遇到问题，需要深入了解 Ralph 在做什么时，可以启用诊断模式：
RALPH_DIAGNOSTICS=1 ralph run -p "你的任务"
这会在 .ralph/diagnostics/ 目录里保存三种详细日志：
.ralph/diagnostics/2024-01-15T10-30-00/
├── agent-output.jsonl ← AI 的完整输出（文字、工具调用、结果）
├── orchestration.jsonl ← 帽子激活、事件发布、背压检查的记录
└── errors.jsonl ← 解析错误、验证失败的详细信息
分析这些日志：
# 查看所有工具调用
jq 'select(.type == "tool_call")' .ralph/diagnostics/*/agent-output.jsonl
# 查看所有帽子激活记录
jq 'select(.type == "hat_activation")' .ralph/diagnostics/*/orchestration.jsonl
# 查看所有错误
cat .ralph/diagnostics/*/errors.jsonl
通知集成
不想一直盯着仪表盘？Ralph 可以在循环完成（或失败）时发送通知：
macOS 系统通知（通过 shell 钩子配置，参见第十四章）：
# 在 ralph.yml 里配置循环结束时的通知
hooks:
on_complete:
- command: "osascript -e 'display notification \"Ralph 任务完成！\" with title \"Ralph\"'"
on_blocked:
- command: "osascript -e 'display notification \"Ralph 需要你的帮助\" with title \"Ralph ⚠️\"'"
Telegram 通知（第十二章详细介绍）：
如果你配置了 Telegram 机器人，Ralph 会自动通过 Telegram 发送关键状态更新：
- 循环开始时发送"开始工作了"
- 遇到阻塞时发送"我需要帮助"
- 任务完成时发送"完成了，请查看结果"
清理旧的循环记录
随着时间推移，会积累一些历史记录。可以定期清理：
# 预览会删除什么（不实际删除）
ralph clean --dry-run
# 清理诊断日志
ralph clean --diagnostics
# 查看 .ralph/ 目录的磁盘使用
du -sh .ralph/
对于已完成的并行循环，使用 ralph loops 子命令管理：
# 查看所有循环（包括已完成的）
ralph loops list --all
# 废弃某个循环，清理它的 worktree
ralph loops discard loop-abc
本章小结
- TUI（终端界面）是 Ralph 运行时的实时监控界面，提供快捷键操作
- Web 仪表盘提供更友好的可视化界面，支持流程图、记忆编辑、任务管理
- 可以用 nohup/screen/tmux 在后台长时间运行 Ralph
- 诊断模式（RALPH_DIAGNOSTICS=1）保存详细日志，方便排查问题
- 支持配置完成/失败通知，不需要一直盯着屏幕
能随时看到进度让李明轩安心了不少。但他很快贪心起来——既然 AI 能跑，为什么不让它同时跑 4 个？微信、小红书、知乎、微博 4 个平台的差异化文案完全可以并行。下一章讲并行工作流——全书的高潮，也是"一个人顶一个团队"承诺的兑现。