在 Cline 中使用 Ralph Wiggum 的完整指南

🎯 什么是 Ralph Wiggum？

Ralph Wiggum 是一个自动化 AI 编码工具，通过 bash 循环脚本让 Cline 自主完成多个任务。每次迭代都启动一个新的 Cline 进程，确保上下文始终清晰。

📋 核心理念

每次循环 = 全新的 Cline 会话

  • ✅ 避免上下文窗口溢出
  • ✅ 防止长时间会话后的性能下降
  • ✅ 每个任务都有干净的起点
  • ✅ 通过磁盘文件（specs/、历史记录）共享状态

🚀 如何在 Cline 中使用

步骤 1：初始化 Ralph Wiggum

在 Cline 中输入：

使用 https://github.com/fstandhartinger/ralph-wiggum 为我的项目设置 Ralph Wiggum

Cline 会引导你完成：

  1. 创建必要的目录结构（specs/、scripts/、logs/）
  2. 下载 ralph-loop.sh 脚本
  3. 项目访谈 - 了解你的项目愿景和目标
  4. 创建项目宪法 - 为所有会话提供指导原则

步骤 2：编写规范文件

在 specs/ 目录创建功能规范文件，关键是清晰的验收标准：

示例：specs/user-login.md

# Feature: 用户登录功能

## 需求
- 手机号+验证码登录
- 登录状态持久化
- 自动跳转到首页

## 验收标准
- [ ] 用户可以输入手机号
- [ ] 点击发送验证码后收到验证码
- [ ] 输入正确验证码后登录成功
- [ ] 刷新页面后登录状态保持
- [ ] 登录后自动跳转到首页
- [ ] 所有相关测试通过

**完成时输出：** `<promise>DONE</promise>`

💡 关键要点：

  • ✅ 验收标准要具体、可测试
  • ✅ 避免模糊的描述如"功能正常"
  • ✅ 每个标准应该能明确验证
  • ✅ 必须包含 <promise>DONE</promise> 输出要求

步骤 3：运行 Ralph 循环

在终端中运行（不在 Cline 中运行）：

# 开始自动化循环
./scripts/ralph-loop.sh

# 限制最大迭代次数
./scripts/ralph-loop.sh 10

发生了什么？

循环 1: Cline 启动 → 读取 spec → 实现 → 测试 → 提交 → 输出 DONE → Cline 关闭
循环 2: 新 Cline 启动 → 读取下一个 spec → 实现 → 测试 → 提交 → 输出 DONE → Cline 关闭
循环 3: 新 Cline 启动 → ...

每次循环都是全新的 Cline 实例，上下文不会累积！

步骤 4：查看日志

所有输出都保存在 logs/ 目录：

# 查看会话日志
cat logs/ralph_*_session_*.log

# 查看特定迭代日志
cat logs/ralph_*_iter_1_*.log

🎮 两种工作模式

1. Build 模式（默认）

./scripts/ralph-loop.sh

Cline 会：

  • 选择一个未完成的 spec
  • 实现功能
  • 运行测试
  • 提交代码
  • 输出 <promise>DONE</promise>

2. Plan 模式（可选）

./scripts/ralph-loop.sh plan

Cline 会：

  • 创建详细的实施计划
  • 分解成小任务
  • 保存到 IMPLEMENTATION_PLAN.md

📁 项目结构

your-project/
├── specs/                    # 功能规范
│   ├── user-login.md
│   ├── dashboard.md
│   └── ...
├── scripts/                  # Ralph 脚本
│   ├── ralph-loop.sh
│   └── ...
├── logs/                     # 日志文件
│   ├── ralph_*_session_*.log
│   └── ralph_*_iter_*.log
├── ralph_history.txt         # 历史记录（突破/阻塞/学习）
├── IMPLEMENTATION_PLAN.md    # 实施计划（可选）
└── CONSTITUTION.md           # 项目宪法（可选）

⚠️ 重要注意事项

1. 启用自动执行模式

为了 Ralph 自主工作，需要在启动 Cline 时使用危险模式：

# VSCode 中的 Cline 设置
# 或者在命令行中：
cline --dangerously-skip-permissions

⚠️ 仅在沙盒/测试环境中使用！

2. 完成信号很关键

Cline 必须输出 <promise>DONE</promise> 才算完成。

  • bash 脚本会检查这个信号
  • 如果没有输出，会重试当前 spec
  • 确保在 spec 中明确说明要输出这个信号

3. 测试作为护栏

  • 每个 spec 应包含"测试通过"作为验收标准
  • Cline 在所有测试通过前不应输出完成信号
  • 这确保了代码质量

💡 最佳实践

✅ 好的 Spec 写法

## 验收标准
- [ ] 用户点击登录按钮后显示加载状态
- [ ] API 返回成功后跳转到首页
- [ ] API 返回失败后显示错误提示
- [ ] 登录组件的单元测试全部通过

❌ 差的 Spec 写法

## 验收标准
- [ ] 登录功能正常工作
- [ ] 没有 bug

编写技巧

  1. 一个 spec 一个功能 - 不要混合多个不相关的功能
  2. 验收标准可量化 - 能够明确验证是否完成
  3. 包含测试要求 - 确保代码质量
  4. 说明完成信号 - 提醒 Cline 输出 <promise>DONE</promise>

🔄 典型工作流

第1天：规划阶段
├─ 在 Cline 中：初始化 Ralph，创建项目结构
├─ 编写 5-10 个功能 spec
└─ 运行 ./scripts/ralph-loop.sh plan（可选）

第2天：开发阶段
├─ 运行 ./scripts/ralph-loop.sh
├─ Ralph 自动完成所有 spec
└─ 查看日志，验证结果

第3天：调整优化
├─ 根据结果调整未完成的 spec
├─ 继续运行 ralph-loop.sh
└─ 直到所有功能完成

🔗 相关资源

🎯 总结

在 Cline 中使用 Ralph Wiggum 的关键：

  1. ✅ 让 Cline 帮你设置项目结构
  2. ✅ 编写清晰、可测试的 spec
  3. ✅ 在终端运行 ralph-loop.sh（不在 Cline 中）
  4. ✅ 每个循环都是全新的 Cline 会话
  5. ✅ 通过 <promise>DONE</promise> 信号标记完成

让 Ralph 做 Ralph 的事 - 信任 AI 的自主能力，专注于编写好的规范！

Agent Skill Cline