/moai fix

一次性自动修复命令。并行扫描 代码中的错误后 一次性修复。

信息

一句话总结: /moai fix 是"快速清扫工具"。将代码中堆积的 lint 错误、类型错误 一次性扫净 并修复。

信息

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

开发过程中,import 排序会被打乱、类型会不匹配、lint 警告会堆积。与其逐个查找修复,不如执行 /moai fix,让 AI 自动发现并修复问题。

与 /moai loop 不同,它 只执行 1 次,适合想快速把当前状态清理干净的时候。从循环系列来看,/moai fix 是 单次(1 回)预设 —— 对无需迭代的明确错误跑循环纯属令牌浪费,选择与任务大小相称的最便宜工具,才是令牌经济学视角下的正确选择。

> /moai fix

无需任何参数,执行后会扫描当前项目的错误并自动修复可修复的项目。

可以在不修复的情况下预览将进行哪些变更:

> /moai fix --dry

使用此选项时,不修改实际代码,仅显示发现的问题与预期变更。

限制修复的级别:

# 仅修复 Level 1-2(格式化、lint)
> /moai fix --level 2

# 仅修复 Level 1(仅格式化)
> /moai fix --level 1

/moai fix 分 5 步执行。

flowchart TD
    Start["执行 /moai fix"] --> Scan

    subgraph Scan["第 1 步: 并行扫描"]
        S1["LSP 扫描
检查类型错误"]
        S2["AST-grep 扫描
检查结构模式"]
        S3["Linter 扫描
检查代码风格"]
    end

    Scan --> Collect["第 2 步: 收集问题"]
    Collect --> Classify["第 3 步: 级别分类
(Level 1~4)"]
    Classify --> Fix["第 4 步: 自动/经批准修复"]
    Fix --> Verify["第 5 步: 验证"]
    Verify --> Done["完成"]

3 种工具 同时 扫描代码。

将扫描结果合并为一个列表。

发现的问题(示例):
  [Level 1] src/api/router.py:3 - 需要排序 import
  [Level 1] src/models/user.py:15 - 多余空白
  [Level 2] src/utils/helper.py:8 - 未使用的变量 "temp"
  [Level 2] src/auth/service.py:22 - 多余的 else 语句
  [Level 3] src/auth/service.py:45 - 缺少错误处理
  [Level 4] src/db/connection.py:12 - SQL Injection 可能性

将收集到的问题 按风险程度分为 4 个级别。级别不同,是否自动修复也不同。安全的交给机器处理,危险的需要人的批准 —— 将自主性与安全门禁并置的挽具设计原则在这里同样适用。

flowchart TD
    Issue[发现的问题] --> L1{Level 1?}
    L1 -->|是| Auto1["自动修复
无需批准"]
    L1 -->|否| L2{Level 2?}
    L2 -->|是| Auto2["自动修复
仅记录日志"]
    L2 -->|否| L3{Level 3?}
    L3 -->|是| Approve3["用户批准后
修复"]
    L3 -->|否| Approve4["必须用户批准
建议人工审查"]

不影响代码行为 的形式性问题。AI 自动修复。

实际修复示例:

# 修复前 (Level 1 问题)
import os
import sys
from pathlib import Path
import json

# 修复后(自动修复)
import json
import os
import sys
from pathlib import Path

影响代码质量的 轻微 问题。AI 自动修复并留下日志。

实际修复示例:

# 修复前 (Level 2 问题)
def get_user(user_id):
    result = db.query(user_id)
    if result:
        return result
    else:           # 多余的 else
        return None

# 修复后(自动修复)
def get_user(user_id):
    result = db.query(user_id)
    if result:
        return result
    return None

可能改变代码行为 的问题。经用户批准后修复。

向用户展示的内容:

[Level 3] src/auth/service.py:45
  问题: 认证失败时缺少错误处理
  建议: 添加 try-except 块,在认证失败时返回恰当的错误响应

  是否批准? (y/n)

影响安全 的严重问题。必须经用户批准,并建议人工审查。

注意

发现 Level 4 问题时,AI 不会自动修复。安全漏洞若修复不当可能造成更大问题,请务必亲自确认后再修复。

信息

选择指南:

• “提交前只想快速清理 lint 错误” → /moai fix
• “测试失败很多,想全部修复” → /moai loop

/moai fix 是单次(1 回)流水线,因此可能残留一次扫描-修复-验证无法解决的问题。残留问题的种类:

• Level 4 手动项 (安全·架构 —— 禁止自动修复)
• 未解决的错误 (在 repair 阶段未能修复的项)
• Phase 5 回归守卫失败 (既未回退也未报告的回归)

出现此类残留时,fix 工作流会把它持久化到 .moai/state/loop-verdict-<id>.json,记为 exit_kind: "one-shot-residue"、iterations_used: 1。该 schema 与 /moai loop 的残留持久化 schema 相同。

报告对可再修复的残留仅 建议 进入 /moai loop,fix 工作流不会自动调用 /moai loop 或其他子命令。用户亲自重新进入 /moai loop 后,持久化的残留会作为条目并入循环的扫描队列,由 goal-preset 扫荡清空。

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

flowchart TD
    User["用户请求"] --> Orchestrator["MoAI 编排器"]
    Orchestrator --> Parallel["并行扫描"]

    Parallel --> LSP["LSP 扫描"]
    Parallel --> AST["AST-grep 扫描"]
    Parallel --> Linter["Linter 扫描"]

    LSP --> Collect["收集问题"]
    AST --> Collect
    Linter --> Collect

    Collect --> Classify["级别分类"]
    Classify --> Fix["执行修复"]

    Fix --> Level12["Level 1-2
自动修复"]
    Fix --> Level34["Level 3-4
需批准"]

    Level12 --> Verify["验证"]
    Level34 --> UserApprove["用户批准"]
    UserApprove --> Verify

    Verify --> Complete["完成"]

智能体角色:

实现新功能后,想在提交前清理代码。

# 确认当前状态
$ ruff check src/
# 发现 12 个 lint 警告

# 执行 fix
> /moai fix

执行日志:

[并行扫描]
  LSP: 发现 2 个错误
  AST-grep: 发现 3 个模式违规
  Linter: 发现 12 个警告

[问题分类]
  Level 1 (格式化): 7 个 → 自动修复
  Level 2 (lint): 8 个 → 自动修复
  Level 3 (逻辑): 2 个 → 需批准
  Level 4 (安全): 0 个

[Level 1-2 自动修复完成]
  - import 排序 5 处
  - 删除行尾空白 2 处
  - 删除未使用变量 3 处
  - 删除多余 else 2 处
  - 修正类型提示 2 处
  - 修正命名规则 1 处

[Level 3 批准请求]
  问题 1: src/auth/service.py:45
    问题: 令牌过期时缺少错误处理
    建议: 添加 TokenExpiredError 异常处理
    → 已批准: 修复完成

  问题 2: src/api/router.py:78
    问题: 缺少输入值验证
    建议: 用 Pydantic 模型添加输入验证
    → 已批准: 修复完成

[验证]
  LSP 错误: 0 个
  Linter 警告: 0 个
  所有修复均已验证。

完成: 修复了 17 个问题

是的,Level 3-4 问题需要逐个批准。不过可以先用 --dry 确认,只批准重要的项目。

可以用 Git 回退。建议在修复前提交,或用 git stash 备份。

请使用 --path 标志:

> /moai fix --path src/auth/

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

• /moai loop - 迭代修复循环
• /moai - 完全自主自动化
• TRUST 5 质量系统