Ralph Wiggum 入门第 3 部分：Ralph TUI 监控与可视化

让 Ralph Wiggum 自主运行很强大——但盲目监控循环就像信任一个你看不到的飞行员。Ralph-TUI 通过提供一个实时面板来解决可视化问题，让你看到 AI 代理的每一次迭代、任务和决策。

可视化问题

当 Ralph Wiggum 在自主模式下运行时，它独立操作——读取规格、创建计划、构建功能、运行测试，持续数小时甚至数天地迭代。这种自主性是它的优势，但也带来了一个关键挑战：不不断检查文件你就看不到发生了什么。

循环可能：

• 在一个失败的测试上卡了 30 分钟
• 因为对计划的理解有误而在错误的任务上迭代
• 生成了成千上万行你永远不会看的日志
• 做出你想早点发现的架构决策

Ralph-TUI 登场：一个终端界面，在不中断执行的情况下提供对自主循环的实时可视化。就像给你的自动驾驶加上了一个驾驶舱。

为什么会有 Ralph-TUI

Ralph-TUI 的诞生是为了弥合「完全自主」和「完全不透明」之间的鸿沟。虽然 Ralph Wiggum 擅长独立工作，但长时间运行的构建（3 小时以上、多天项目）需要可观测性，原因有三：

1. 调试效率：实时发现问题，而不是在 100 次迭代之后才发现
2. 进度跟踪：知道哪些任务已完成、进行中或待处理
3. 建立信心：实时看到代理的推理和决策过程
4. 无需手动管理：自动化我们在 第 1 部分 和 第 2 部分 中手动设置的所有提示模板、文件管理和迭代跟踪

Ralph-TUI 与 Ralph Wiggum 并行运行——它不控制或中断循环。把它想象成一个监控面板，而不是方向盘。

OpenCode 用户的替代方案： opencode-ralph-wiggum 内置了卡顿检测功能，当代理卡住时会自动识别并实时显示。

什么时候用 Ralph-TUI，什么时候不用

适合使用 Ralph-TUI 的场景：

• 长时间运行的构建（3 小时以上）
• 有 20 个以上任务的多天项目
• 引导式 PRD 创建（/ralph-tui-prd 技能会引导你完成）
• 调试有问题的循环（当 Ralph 卡住时）
• 团队协作（多人监控进度）
• 学习 Ralph 如何处理复杂问题

可以跳过 Ralph-TUI 的场景：

• 快速的 1-2 个任务构建（不到 30 分钟）
• 你已经运行过几十次的成熟工作流
• 自定义提示模板（如果你需要精细控制，使用 第 2 部分 的 Bash 循环）
• 资源受限的环境（Ralph-TUI 增加的开销很小，但还是有一些）
• CI/CD 流水线（使用基于文件的日志记录）

安装与设置

Ralph-TUI 需要 Bun 作为运行时。如果你还没有 Bun，先安装：

curl -fsSL https://bun.sh/install | bash

重启终端（或运行 source ~/.zshrc）将 Bun 加载到你的 PATH 中。

然后用 Bun 全局安装 Ralph-TUI：

bun install -g ralph-tui

为什么用 Bun？ Ralph-TUI 使用 Bun 原生模块来提升性能。用 npm 安装会出现 Cannot find module '@opentui/core-darwin-arm64' 错误。

安装后，运行设置命令来为你的项目配置 Ralph TUI：

ralph-tui setup

设置向导让你选择问题跟踪器：

• JSON File Tracker — 在本地 prd.json 文件中跟踪任务（最简单的选项，无依赖）
• Beads Issue Tracker — 使用 bd CLI 跟踪问题，从 .beads/beads.jsonl 解析
• Beads + BV（智能模式） — 使用 bv --robot-triage 的图感知任务选择

什么是 Beads？ Beads 是 Steve Yegge 为 AI 编程代理设计的基于 Git 的问题跟踪器。任务以基于哈希的 ID（如 bd-a1b2）存储在 .beads/beads.jsonl 中，这防止了多代理工作流中的合并冲突。它支持层级任务（Epic → 任务 → 子任务）和通过 bd dep add 的依赖跟踪。

什么是 BV？ 「智能模式」选项使用 bv（beads viewer）——一个图感知的优先级排序引擎。不让 Claude 解析 JSONL 然后猜测优先级，bv --robot-triage 计算 PageRank、关键路径、中介中心性和环路检测来确定性地推荐最高影响力的任务。提示模板中的 selectionReason 解释了为什么选择该任务。

它还会在 ~/.claude/skills/ 中安装三个技能作为斜杠命令：

• /ralph-tui-prd — 交互式创建产品需求文档
• /ralph-tui-create-json — 将 PRD 转换为 prd.json 格式
• /ralph-tui-create-beads — 将 PRD 转换为 Beads 问题跟踪格式

什么是技能（Skills）？ 技能是专门的知识模块，当你通过斜杠命令调用时 Claude 会自动加载。它们用领域特定的提示和工作流扩展 Claude 的能力。详见 精通第 5 部分：技能 了解创建和使用技能的方法。

首次启动验证：

ralph-tui --version

你应该看到版本信息（0.3.0 或更高）。

使用 Ralph TUI 创建 PRD

在 Ralph 能够自主构建之前，它需要一份清晰的规格。/ralph-tui-prd 技能通过交互式对话将你的粗略想法转化为结构化的产品需求文档。

第 1 步：描述你的功能

运行 /ralph-tui-prd 并用自然语言描述你想构建的东西：

你不需要正式的规格说明——像和同事说话一样解释你的功能就行。包括关于你现有配置、目标用户和任何约束的上下文。

第 2 步：审查 PRD 预览

在提出澄清问题后，技能会生成 PRD 预览：

第 3 步：选择输出格式

技能会问你想要哪种格式——JSON 文件还是 Beads 问题——然后自动转换 PRD。完成后，Ralph TUI 显示运行自主循环的界面。

Ralph TUI 如何管理上下文

和 第 2 部分 中介绍的 Bash 循环方式一样，Ralph TUI 在每次迭代时启动一个全新的上下文窗口。这是使长时间运行的自主构建成为可能的核心洞察。

为什么全新上下文很重要

标准的代理循环会受到上下文累积的困扰——每一次失败的尝试都留在对话历史中。几次迭代之后，模型需要处理一长串噪音才能专注于当前任务。Ralph TUI 通过每个周期生成新的代理实例来解决这个问题。

进度保存在文件和 Git 中，而不是 LLM 的上下文窗口里。当上下文填满时，你会得到一个拥有全新上下文的新代理。

关键文件

Ralph TUI 使用这些文件在迭代间维护状态：

• prd.json — 任务定义和状态
• .ralph-tui/progress.md — 跨迭代的上下文摘要
• .ralph-tui-session.json — 暂停/恢复的会话状态
• .ralph-tui/config.toml — 项目配置
• .ralph-tui/iterations/ — 迭代日志（iteration-{N}-{taskId}.log）

执行周期

每次迭代遵循这个模式：

1. 选择任务 — 从 prd.json 中选取优先级最高的未完成任务
2. 构建提示 — 用任务上下文渲染 Handlebars 模板
3. 执行代理 — 用干净的上下文生成新的 Claude 实例
4. 检测完成 — 解析输出中的任务完成信号
5. 更新跟踪器 — 标记任务完成，记录迭代，循环

这种架构意味着每个 PRD 项目应该小到在一个上下文窗口内能完成。如果任务太大，将其拆分为子任务。

核心功能深度解析

Ralph-TUI 提供五个核心能力，改变你与自主循环交互的方式：

1. 带键盘控制的实时可视化

实时观看代理输出。浏览日志，回滚查看之前的迭代，跳转到特定任务——所有这些都不会中断自主循环。

为什么重要： 长时间的构建会生成成千上万行日志。Ralph-TUI 过滤噪音，高亮关键事件（测试失败、提交、任务转换），让你专注于重要的内容。

2. 任务编排

Ralph-TUI 自动显示：

• 当前正在执行哪个任务
• 任务优先级（基于 IMPLEMENTATION_PLAN.md）
• 已完成 vs 待处理的任务
• 估计的进度百分比

这回答了一个问题：「我们构建到哪了？」

3. 会话持久化（暂停/恢复）

需要停止监控但让 Ralph 继续运行？Ralph-TUI 会话是持久的。关闭终端，去吃午饭，之后恢复——进度跟踪会继续。

使用场景： 启动一个 6 小时的构建，监控 30 分钟，关闭 Ralph-TUI，稍后再回来查看。会话会显示你不在的时候发生的一切。

4. 子代理追踪

当 Ralph 生成子代理（Subagent）来处理测试、Lint 或子任务时，Ralph-TUI 会追踪调用栈。查看哪个子代理是活跃的、它在做什么、以及它何时返回主循环。

什么是子代理？ 子代理是具有独立上下文窗口的专业 AI 工作者，Claude 生成它们来并行处理特定任务。它们可以运行测试、Lint 代码或处理子任务，而不消耗主代理的上下文。详见 精通第 6 部分：子代理 获取完整解释。

为什么重要： 复杂的构建会使用 5-10 个子代理。没有追踪，你会失去对嵌套执行的可视化。

5. 跨迭代上下文追踪

Ralph-TUI 在迭代之间维护上下文。查看：

• 第 10 次和第 11 次迭代之间发生了什么变化
• 每次迭代中修改了哪些文件
• 跨迭代的测试结果（同一个测试失败了 3 次？）

这把一连串事件变成了一个连贯的叙事。

常见使用场景

场景 1：长时间运行的构建（3 小时以上）

场景： 将一个遗留代码库从 CommonJS 迁移到 ESM，涉及 200 多个文件，更新导入、修复类型错误，并确保所有测试通过。

Ralph-TUI 工作流：

1. 下午 2 点启动 Ralph 循环
2. 在另一个 tmux 窗格中启动 Ralph-TUI
3. 监控 30 分钟确保 Ralph 正确理解了规格
4. 从 tmux 分离（Ctrl+B, d）
5. 下午 6 点通过 tmux attach 回来查看
6. 查看底部状态：「12 completed | 1 in progress | 2 pending」
7. 导出日志并验证测试结果

Ralph-TUI 的价值： 没有它，你不知道 Ralph 是在任务 3 就卡住了还是成功完成了所有任务——直到你手动检查文件。

场景 2：多天项目

场景： 用 2 天时间构建一个复杂的微服务架构，50 多个任务。

Ralph-TUI 工作流：

1. 第 1 天上午 9 点：启动 Ralph，用 Ralph-TUI 监控
2. 第 1 天下午 6 点：Ralph 进行到任务 23/50。导出日志，关闭 Ralph-TUI，让 Ralph 继续运行
3. 第 2 天上午 9 点：再次启动 Ralph-TUI——会话显示进度（任务 24-38 已完成）
4. 第 2 天中午：Ralph 完成。审查完整的日志导出

Ralph-TUI 的价值： 会话持久化意味着你不会失去对长时间运行期间发生了什么的可视化。日志显示了你不在时 Ralph 做出的每一个决定。

场景 3：CI/CD 集成

场景： 在 GitHub Actions 工作流或远程服务器中运行 Ralph，实现自动化功能构建。

Ralph TUI 支持用于 CI/CD 流水线的无头模式：

ralph-tui run --headless

这在没有交互控制的情况下自主执行代理。

远程监控： 你可以使用 Ralph TUI 的远程管理从本地机器监控无头实例：

# 在远程/CI 服务器上
ralph-tui run --listen --prd ./prd.json

# 在你的本地机器上
ralph-tui remote add ci server.example.com:7890 --token <TOKEN>
ralph-tui

TUI 显示本地和远程实例的标签页，带有连接状态指示器。安全功能包括双层 Token、审计日志和自动 Token 轮换。

详细的远程设置请参阅 Ralph TUI 文档。

最佳实践

始终从新分支开始

启动 Ralph 之前，创建一个专用的功能分支：

git checkout -b feature/my-ralph-task

为什么重要：

• Ralph 频繁提交——隔离它们可以保持你的主分支干净
• 出问题时容易回滚（git checkout main && git branch -D feature/my-ralph-task）
• 准备合并时有干净的 PR 历史
• 多个 Ralph 运行可以在不同分支上并行工作

不要在 main/master 上运行 Ralph。 如果 Ralph 陷入循环或犯了架构错误，在你的主分支上回退几十个提交会很痛苦。

什么时候暂停/恢复

暂停（按 Space）当：

• 你看到错误想仔细阅读日志
• 你正在用 / 搜索特定事件
• 你想复制粘贴日志输出

恢复（再按 Space）当：

• 你分析完了
• 你想看到实时更新

不要无限期暂停——日志缓冲区仍在后台增长。如果暂停超过 30 分钟，考虑导出日志并重启 Ralph-TUI。

动态调整迭代次数

需要比原来计划更多的迭代？或者想提前结束？

• + — 增加当前运行的迭代次数
• - — 减少剩余迭代次数

用 + 当：

• Ralph 进展顺利但迭代次数快用完了
• 某个任务比预期更复杂，需要更多周期
• 你想延长过夜运行而不需要重启

用 - 当：

• Ralph 完成了核心工作，剩余任务是可选的
• 你需要释放资源给另一个构建
• 当前方法不起作用，你想优雅地停止

这比杀掉进程好——Ralph 会干净地完成当前迭代，在停止前提交进度。

日志管理

定期导出日志（长时间构建每 1-2 小时一次）：

• 按 e 导出
• 描述性地命名文件：ralph-build-iteration-1-to-25.txt

为什么： 如果 Ralph 在 6 小时后崩溃，你会有到上次导出为止的日志。没有导出，你可能失去所有内容。

自动化： 用 cron 每小时自动导出：

0 * * * * cd /path/to/project && ralph-tui export --output logs/ralph-$(date +\%Y-\%m-\%d-\%H-\%M).txt

多会话处理

Ralph-TUI 每个项目支持一个会话。如果你在不同目录中启动多个 Ralph 循环：

# 终端 1
cd /projects/api-v1 && ralph loop PROMPT_plan.md

# 终端 2
cd /projects/api-v2 && ralph loop PROMPT_plan.md

你可以用不同的 Ralph-TUI 实例来监控：

# Ralph-TUI 1
cd /projects/api-v1 && ralph-tui run

# Ralph-TUI 2
cd /projects/api-v2 && ralph-tui run

每个 Ralph-TUI 通过目录上下文连接到各自的 Ralph 循环。

Tmux 多会话工作流：

# 创建 tmux 会话
tmux new -s ralph-monitoring

# 分成 4 个窗格
Ctrl+B, % (垂直分割)
Ctrl+B, " (左窗格水平分割)
Ctrl+B, " (右窗格水平分割)

# 窗格 1：Ralph 循环 1
cd /projects/api-v1 && ralph loop PROMPT_plan.md

# 窗格 2：Ralph-TUI 1
cd /projects/api-v1 && ralph-tui run

# 窗格 3：Ralph 循环 2
cd /projects/api-v2 && ralph loop PROMPT_plan.md

# 窗格 4：Ralph-TUI 2
cd /projects/api-v2 && ralph-tui run

现在你可以并排监控两个自主构建了。

资源监控

Ralph-TUI 本身很轻量（约 20 MB 内存，低于 1% CPU），但长时间运行的会话可能会累积日志消耗磁盘空间。

检查磁盘使用：

du -sh ~/.ralph-tui/sessions ~/.ralph-tui/archives

如果超过 1 GB，清理旧会话：

rm ~/.ralph-tui/sessions/*.json
rm -rf ~/.ralph-tui/archives/2025-*  # 删除 2025 年的归档

自动清理： 在 ~/.ralph-tui/config.json 中添加：

{
  "cleanup": {
    "enabled": true,
    "maxAge": 7
  }
}

这会删除 7 天以上的会话和归档。

接下来

你现在对 Ralph 的自主循环有了完整的可视化。

在 第 4 部分：高级模式与故障排除 中，我们将介绍高级提示工程、常见陷阱、全面的故障排除策略和企业级模式，让你成为 Ralph 专家。