# Ralph Loop 详解

## 问题：智能体惰性

AI 智能体有时会在完成部分任务后找借口停下来：
- "时间差不多了，我们下次继续"
- "这已经足够好了"
- "剩下的可以以后再做"

这种现象称为"智能体惰性"(Agentic Laziness)。

## 解决方案：Ralph Loop

Ralph Loop 本质上是一个 for 循环，在智能体声明完成后再次检查，确保真正完成。

### 核心逻辑

```
for iteration in range(MAX_ITERATIONS):
    result = agent.work(task)
    
    if "DONE" in result and verify_completion():
        print("✅ 任务真正完成")
        break
    else:
        agent.continue("你确定完成了吗？请验证：{success_criteria}")
```

### 实现方式

#### 1. 在 CHANGELOG.md 中声明状态

```markdown
**Ralph Loop 状态**:
```
迭代: 1/20
成功标准: 所有测试通过，覆盖率>80%
```
```

#### 2. 每次会话开始检查

```
1. 读取 CHANGELOG.md 的 Ralph Loop 状态
2. 检查是否已达到成功标准
3. 如果未达到，继续工作
4. 如果达到，标记完成
```

#### 3. 每次迭代更新

```markdown
**Ralph Loop 状态**:
```
迭代: 3/20
成功标准: ✅ 所有测试通过，覆盖率>80%
结果: 完成
```
```

### 成功标准设计

好的成功标准应该是：
- **可量化** - 可以用数字衡量
- **可验证** - 有明确的验证方式
- **有意义** - 与项目目标相关

**示例**：

| 任务 | 成功标准 |
|------|----------|
| 实现功能 | 所有测试通过 |
| 性能优化 | 响应时间 < 100ms |
| 代码重构 | 测试覆盖率 > 80% |
| 文档编写 | 所有 API 有文档 |
| Bug 修复 | Bug 不再复现 |

### 最大迭代次数

默认 20 次，根据任务复杂度调整：
- 简单任务：5-10 次
- 中等任务：10-20 次
- 复杂任务：20-50 次

### 与 HEARTBEAT 集成

可以将 Ralph Loop 检查加入心跳：

```markdown
## HEARTBEAT.md

### 当前 Ralph Loop 任务

```
项目: {项目名}
迭代: {当前}/{最大}
成功标准: {标准}
```

检查：是否需要继续推进？
```

这样即使会话中断，下一次心跳时也会自动继续。

## 实战案例

### 案例：任务计划表项目

```markdown
迭代 1: 项目初始化
- 创建 PROJECT.md, CHANGELOG.md
- 未完成：核心功能未实现

迭代 2: 技术栈调整
- 发现 Python 不可用
- 迁移到 TypeScript
- 未完成：代码未写

迭代 3: 核心实现
- 实现 Task, TaskStore 类
- 22 个测试全部通过
- CLI 工作正常
- ✅ 成功标准达成

结果: 3 次迭代完成项目
```

## 注意事项

1. **不要无限循环** - 设置合理的最大迭代次数
2. **记录进度** - 每次迭代都要更新 CHANGELOG
3. **验证真正完成** - 不是智能体说完成就完成，要用测试验证
4. **失败方法记录** - 如果某次迭代失败，记录原因防止重复