/moai loop

自主迭代修复循环命令。AI 自行诊断问题、修复并验证,直到所有错误都被解决 为止自动重复这一过程。

信息

一句话总结: /moai loop 是名为 “Ralph Engine” 的自主修复引擎。 通过反复执行 诊断 → 修复 → 验证,自动解决代码中的所有问题。

信息

斜杠命令: 在 Claude Code 中输入 /moai:loop 即可直接执行此命令。仅输入 /moai 会显示所有可用子命令列表。

编写代码时,类型错误、lint 警告、测试失败等多个问题可能同时出现。与其手动逐个修复,不如执行 /moai loop,让 AI 自动迭代修复 所有问题。

与 /moai fix 只修复 一次 不同,/moai loop 会 持续重复直到满足完成条件。

这个循环是 v3 第二大支柱 智能体循环工程 的代表案例。循环自行诊断与修复,无需人在每个错误上介入,而循环留下的观察则作为挽具学习(递归式自我学习)的原料被积累。引擎实现位于 internal/ralph/engine.go —— 每次迭代的 Decide() 按优先级顺序判定 continue / converge / request_review / abort 之一。

/moai loop 是 goal 引擎之上的预设。如果说 /moai goal "<条件>" 是用户直接声明完成条件的通用循环,那么 /moai loop 就是预先填入"直到清空诊断工具发现的问题队列"这一条件的预设。

/moai goal "go test ./... exits 0; 所有 AC 记录为 PASS"
/moai goal status | clear

如果终态可以表达为条件表达式,用 /moai goal;如果是"把工具发现的问题全部消灭",用 /moai loop。

> /moai loop

无需任何参数,执行后会自动找到并修复当前项目的所有问题。

限制迭代次数:

# 最多迭代 20 次
> /moai loop --max 20

注意

为防止无限循环,默认值为 10 次 (ralph.yaml 的 loop.max_iterations)。 迭代上限优先级依次为 CLI --max 标志 > ralph.yaml loop.max_iterations > workflow.yaml loop_prevention.max_iterations。

除默认扫描镜头(LSP · lint · 测试失败 · 评审镜头 [安全, @MX])之外,用 opt-in 镜头拓宽扫描范围:

只有镜头发现的东西才会进入队列,循环绝不执行扫描队列之外的"凭空改进"。

/moai loop 每次迭代 (iteration) 都经过以下过程。

flowchart TD
    Start["执行 /moai loop"] --> Diag

    subgraph Diag["第 1 步: 并行诊断"]
        D1["LSP 诊断
检查类型错误"]
        D2["AST-grep 诊断
检查结构模式"]
        D3["运行测试
检测失败测试"]
        D4["测量覆盖率
确认是否低于 85%"]
    end

    Diag --> Collect["第 2 步: 收集问题"]
    Collect --> Todo["第 3 步: 生成 TODO
修复工作列表"]
    Todo --> Fix["第 4 步: 顺序修复
逐一安全修复"]
    Fix --> Verify["第 5 步: 验证
确认修复结果"]
    Verify --> Check{满足完成
条件?}
    Check -->|否| Diag
    Check -->|是| Done["明示循环完成"]

4 种诊断工具 同时 运行,快速掌握项目的所有问题。

信息

什么是并行诊断? 4 种诊断 同时 执行,比逐个顺序 执行快约 4 倍。这样收集到的问题会合并为 一个列表。

将并行诊断中发现的所有问题整理为一个列表。

发现的问题(示例):
  [LSP] src/auth/service.py:42 - 无法将 "int" 赋值给 "str" 类型
  [LSP] src/auth/router.py:15 - "User" 类型未定义
  [AST] src/utils/helper.py:3 - 未使用的 import "os"
  [TEST] tests/test_auth.py::test_login - AssertionError
  [COV] src/auth/service.py - 覆盖率 62%(目标 85%)

基于收集到的问题自动生成修复工作列表 (TODO)。此时会考虑 依赖顺序 来决定修复次序。

例如缺少类型定义时,先添加该类型,再修改使用该类型的代码。

逐一顺序 修复 TODO 列表中的项目。并行修复可能相互冲突,因此安全地逐一处理。

修复结束后再次运行诊断,确认问题是否解决。若仍有剩余问题,则回到第 1 步继续迭代。

为防止无限循环,有两道安全装置。让循环无限运转也是令牌浪费,因此安全装置同时守护稳定性与令牌经济学。

flowchart TD
    A[执行迭代] --> B{超过最大
迭代次数?}
    B -->|是: 超过 100 次| C["强制结束
向用户报告"]
    B -->|否| D{连续 5 次
无进展?}
    D -->|是: 重复相同错误| E["检测到死锁状态
请求用户介入"]
    D -->|否| F[继续下一次迭代]

注意

发生死锁状态怎么办? AI 连续 5 次未能修复同一错误时, 会自动中断并请求用户介入。此时请直接 查看错误内容或提供提示。

/moai loop 在 同时满足以下三个条件 时结束循环。

/moai fix 和 /moai loop 看起来相似,但有核心差异。

flowchart TD
    subgraph Fix["/moai fix(一次性)"]
        F1[并行扫描] --> F2[收集问题]
        F2 --> F3[级别分类]
        F3 --> F4[修复]
        F4 --> F5[验证]
        F5 --> F6[完成]
    end

    subgraph Loop["/moai loop(迭代)"]
        L1[并行诊断] --> L2[收集问题]
        L2 --> L3[生成 TODO]
        L3 --> L4[顺序修复]
        L4 --> L5[验证]
        L5 --> L6{完成?}
        L6 -->|否| L1
        L6 -->|是| L7[完成]
    end

信息

选择指南: 错误不多时用 /moai fix 快速解决。错误 较多或问题相互关联时,/moai loop 更有效。

/moai loop 命令的智能体委派流程:

flowchart TD
    User["用户请求"] --> Orchestrator["MoAI 编排器"]
    Orchestrator --> ManagerDDD["manager-develop 智能体"]

    ManagerDDD --> Diagnose["并行诊断"]
    Diagnose --> LSP["LSP"]
    Diagnose --> AST["AST-grep"]
    Diagnose --> Test["测试"]
    Diagnose --> Cov["覆盖率"]

    LSP --> Todo["生成 TODO"]
    AST --> Todo
    Test --> Todo
    Cov --> Todo

    Todo --> Loop["开始循环"]

    Loop --> Fix["向 manager-develop
委派修复"]
    Fix --> Verify["sync-auditor
验证"]

    Verify --> Complete{"完成条件?"}
    Complete -->|否| Loop
    Complete -->|是| Done["完成"]

智能体角色:

假设用 /moai run 实现代码后,仍残留多个错误。

# 确认当前状态
$ pytest --tb=short
# 3 个测试失败
# 覆盖率: 71%

# 确认 LSP 错误
# 5 个类型错误, 2 个未定义引用

# 执行 loop
> /moai loop

执行日志:

[迭代 1/100]
  诊断: LSP 错误 5 个, 测试失败 3 个, 覆盖率 71%
  TODO: 生成 7 项修复工作
  修复: 解决 5 个类型错误
  验证: LSP 错误 0 个, 测试失败 2 个, 覆盖率 71%

[迭代 2/100]
  诊断: 测试失败 2 个, 覆盖率 71%
  TODO: 生成 2 项修复工作
  修复: 修改测试逻辑 2 处
  验证: LSP 错误 0 个, 测试失败 0 个, 覆盖率 74%

[迭代 3/100]
  诊断: 覆盖率 74%(目标 85%)
  TODO: 生成 3 项添加测试的工作
  修复: 补充缺失的测试用例
  验证: LSP 错误 0 个, 测试失败 0 个, 覆盖率 87%

满足完成条件!
  - LSP 错误: 0 个
  - 测试: 全部通过
  - 覆盖率: 87%

DONE

在这个例子中,/moai loop 仅用 3 次迭代就解决了所有问题。如果手动处理,需要逐个确认并修复每个错误。

可以用 --max 标志限制迭代次数,或用 Ctrl+C 中断。当前状态会被保存,以后可以重新开始。

请使用 --errors 标志只修复错误、跳过警告,或用 --lens 标志调整扫描范围:

# 只修复错误(跳过警告)
> /moai loop --errors

# 添加死代码、覆盖率透镜
> /moai loop --lens clean,coverage

/moai loop 只负责错误修复循环。/moai 则从 SPEC 生成到实现、文档化,自动执行 完整工作流。

/moai loop 的目标是消灭诊断工具(LSP、测试、linter)发现的问题,而 /moai goal 是朝着用户声明的任意完成条件(例: “AC-001~AC-010 全部达成”)持续轮次。/moai loop 是 goal 引擎的预设。

AI 连续 N 次未能解决同一失败签名时(停滞检测),会自动中断并附带 5 段式证据判定请求用户介入。此时请直接查看代码或提供提示。

• /moai fix - 一次性自动修复
• /moai - 完全自主自动化
• TRUST 5 质量系统
• 领域驱动开发