返回
oh-my-claudecode 教程系列 开发工具

oh-my-claudecode 教程 8：验证与调试 - Ralph 循环与 Trace 系统

Ralph 模式的核心是持久验证循环，配合 Trace 系统的证据追踪，确保任务真正完成。本文详解验证机制、调试流程和错误恢复策略。

教程概述

Ralph 模式的核心哲学是不达目的不罢休。通过执行 → 验证 → 修复的持久循环，配合 Trace 系统的证据追踪，确保每个任务都被真正完成。

你将学到

  • ✅ Ralph 持久验证循环的工作原理
  • ✅ Trace 证据追踪系统
  • ✅ 调试工作流程
  • ✅ 错误恢复机制

验证哲学

证据而非断言

flowchart LR
    A[任务执行] --> B{如何确认完成？}
    B -->|断言| C["AI 说完成了"]
    B -->|证据| D["可验证的结果"]

    C --> E[可能实际未完成]
    D --> F[确定性完成]

    style C fill:#ffebee
    style D fill:#e8f5e9

验证规模选择

任务规模 验证层级 示例
小型 Haiku 快速验证 单函数修复
中型 Sonnet 标准验证 功能模块
大型/安全 Opus 深度验证 认证系统

Ralph 验证循环

核心架构

flowchart TD
    A[开始任务] --> B[执行阶段]
    B --> C[验证阶段]
    C --> D{验证通过？}
    D -->|否| E[分析失败原因]
    E --> F[修复阶段]
    F --> B
    D -->|是| G{Architect 审核}
    G -->|拒绝| E
    G -->|通过| H[完成]

    style A fill:#e1f5ff
    style H fill:#e8f5e9
    style E fill:#fff3e0

迭代限制

ralph:
  max_iterations: 10      # 最大迭代次数
  max_fix_attempts: 3     # 单轮最大修复次数
  timeout_minutes: 60     # 总超时时间

状态追踪

stateDiagram-v2
    [*] --> Planning
    Planning --> Execution
    Execution --> Verification
    Verification --> Fixed: 通过
    Verification --> Fixing: 失败
    Fixing --> Execution
    Fixed --> [*]

    note right of Verification
        验证阶段决定
        是否继续循环
    end note

验证阶段详解

功能验证

flowchart TD
    A[功能验证] --> B[需求对照]
    A --> C[测试执行]
    A --> D[边界检查]

    B --> E{所有需求满足？}
    C --> F{测试通过率？}
    D --> G{边界情况处理？}

    E --> H[综合评估]
    F --> H
    G --> H

验证清单：

## 功能验证清单

- [ ] 核心功能正常工作
- [ ] 边界情况正确处理
- [ ] 错误处理适当
- [ ] 性能符合预期
- [ ] 用户体验良好

代码审查验证

flowchart TD
    A[代码审查] --> B[代码质量]
    A --> C[安全检查]
    A --> D[最佳实践]

    B --> E[命名规范]
    B --> F[代码结构]
    B --> G[注释完整]

    C --> H[敏感数据处理]
    C --> I[权限检查]

    D --> J[SOLID 原则]
    D --> K[DRY 原则]

测试验证

# 运行测试套件
npm test

# 检查覆盖率
npm run coverage

# 运行 E2E 测试
npm run e2e

测试通过标准：

verification:
  test_pass_rate: 100%    # 测试通过率
  coverage_minimum: 80%   # 最低覆盖率
  e2e_required: true      # 是否需要 E2E

Trace 证据追踪系统

什么是 Trace？

Trace 系统提供证据驱动的调试能力：

  • 竞争假设追踪
  • 证据收集与评估
  • 不确定性量化
  • 下一步建议

工作流程

flowchart TD
    A[问题发现] --> B[生成假设]
    B --> C1[假设 1]
    B --> C2[假设 2]
    B --> C3[假设 3]

    C1 --> D1[收集证据]
    C2 --> D2[收集证据]
    C3 --> D3[收集证据]

    D1 --> E[评估证据]
    D2 --> E
    D3 --> E

    E --> F{结论明确？}
    F -->|否| G[生成新假设]
    G --> B
    F -->|是| H[确定根因]

    style A fill:#ffebee
    style H fill:#e8f5e9

使用 Trace

# 启动 trace 模式
/oh-my-claudecode:trace

# 或使用关键词
trace the authentication failure

Trace 输出示例

## Trace Report: Authentication Failure

### Hypotheses

| Hypothesis | Confidence | Evidence For | Evidence Against |
|-----------|------------|--------------|------------------|
| Token expired | 70% | Session created 2h ago | Token valid for 24h |
| Database connection failed | 20% | No DB errors in logs | Connection pool healthy |
| User permissions changed | 10% | User was active | Permission audit clean |

### Evidence Collected

1. **Log entry 14:32:01** - "Authentication failed for [email protected]"
2. **Token validation** - Token is valid, not expired
3. **Database query** - User record exists and is active

### Recommended Next Steps

1. Check session storage for corruption
2. Verify JWT secret configuration
3. Review recent permission changes

### Uncertainty Level: Medium (40%)

Primary uncertainty: Session storage state unknown

调试工作流程

标准调试流程

flowchart TD
    A[发现 Bug] --> B[复现问题]
    B --> C[定位范围]
    C --> D[收集信息]
    D --> E[生成假设]
    E --> F[验证假设]
    F --> G{找到根因？}
    G -->|否| E
    G -->|是| H[实施修复]
    H --> I[验证修复]
    I --> J{问题解决？}
    J -->|否| B
    J -->|是| K[完成]

    style A fill:#ffebee
    style K fill:#e8f5e9

使用 Debugger 代理

# 启动调试任务
/team 1:debugger "fix the TypeError in UserService"

# 或者使用 ralph 模式进行持久调试
ralph: debug and fix the authentication flow

调试策略

策略 适用场景 示例
二分法 大范围问题 禁用一半代码定位
日志分析 运行时问题 添加日志追踪
断点调试 逻辑问题 使用 debugger 语句
回归测试 修复验证 确保不引入新问题

错误恢复机制

部分失败处理

flowchart TD
    A[任务执行] --> B[部分失败]
    B --> C{关键任务？}
    C -->|是| D[重试]
    C -->|否| E[跳过并记录]
    D --> F{重试次数？}
    F -->|< 最大| A
    F -->|>= 最大| G[升级处理]
    E --> H[继续其他任务]
    G --> I[人工介入]
    H --> J[整合结果]

    style B fill:#fff3e0
    style I fill:#ffebee

状态恢复

# 查看当前状态
omc status

# 恢复上次任务
omc resume

# 从特定状态恢复
omc resume --from <state-id>

检查点机制

sequenceDiagram
    participant User
    participant Ralph
    participant Checkpoint

    User->>Ralph: 开始任务
    Ralph->>Checkpoint: 创建检查点 1
    Ralph->>Ralph: 执行阶段 1
    Ralph->>Checkpoint: 创建检查点 2
    Ralph->>Ralph: 执行阶段 2
    Ralph->>Ralph: 失败！
    Ralph->>Checkpoint: 恢复到检查点 2
    Ralph->>Ralph: 重试阶段 2

实战案例

案例 1：修复测试套件

ralph: fix all failing tests in the authentication module

执行过程：

flowchart TD
    A[运行测试] --> B[15 个失败]
    B --> C[分析失败原因]
    C --> D[分类修复]
    D --> E[修复 5 个]
    E --> F[运行测试]
    F --> G[10 个失败]
    G --> H[继续修复]
    H --> I[修复 5 个]
    I --> J[运行测试]
    J --> K[5 个失败]
    K --> L[继续修复]
    L --> M[修复 5 个]
    M --> N[运行测试]
    N --> O[全部通过]
    O --> P[Architect 审核]
    P --> Q[完成]

    style A fill:#ffebee
    style Q fill:#e8f5e9

案例 2：调试性能问题

trace the slow API response in /api/users

Trace 过程：

## Hypotheses

1. **Database query slow** (60% confidence)
   - Evidence: Query takes 2.5s
   - Against: Index exists on queried columns

2. **N+1 query problem** (30% confidence)
   - Evidence: Multiple small queries observed
   - Against: ORM has eager loading

3. **Network latency** (10% confidence)
   - Evidence: None yet
   - Against: Same datacenter

## Recommended: Add query logging to confirm hypothesis 1

案例 3：修复编译错误

/team 1:debugger "fix all TypeScript compilation errors"

调试流程：

  1. 运行 tsc --noEmit 收集错误
  2. 分类错误类型
  3. 按依赖顺序修复
  4. 验证修复结果
  5. 确保无新增错误

最佳实践

1. 及时保存检查点

# 手动创建检查点
omc checkpoint save "before-refactor"

# 列出检查点
omc checkpoint list

2. 验证优先级

flowchart TD
    A[验证顺序] --> B[1. 功能正确性]
    B --> C[2. 测试通过]
    C --> D[3. 代码质量]
    D --> E[4. 性能]
    E --> F[5. 文档完整]

    style B fill:#ffebee
    style F fill:#e8f5e9

3. 合理使用代理

调试阶段 推荐代理
问题定位 Debugger
根因分析 Tracer
实施修复 Executor
结果验证 Verifier

常见问题

Q1：验证循环无限进行？

检查配置：

ralph:
  max_iterations: 10
  convergence_check: true  # 启用收敛检查

Q2：Trace 无法确定根因？

增加信息收集：

# 启用详细日志
DEBUG=* npm start

# 收集更多证据
trace --deep the problem

Q3：修复后引入新问题？

使用回归测试：

# 运行完整测试套件
npm test

# 运行 E2E 测试
npm run e2e

小结

验证与调试是确保质量的关键：

关键要点

  • ✅ 证据驱动，不是断言
  • ✅ Ralph 循环确保任务完成
  • ✅ Trace 系统帮助定位根因
  • ✅ 检查点机制支持恢复

验证检查清单

## 完成验证清单

- [ ] 功能需求全部满足
- [ ] 测试 100% 通过
- [ ] 代码审查通过
- [ ] 无安全漏洞
- [ ] 性能符合预期
- [ ] 文档已更新

系列导航：