loop — 工程化编排

/loop 进入目标驱动的自循环：LLM 先探索项目现状，经用户确认后规划任务清单，逐步执行并验证，失败时自动纠正。

工作原理

/loop <目标>
  → 探索项目上下文（只读工具）
  → 用户确认探索结果 → 规划带验证命令的任务清单
  → 用户确认计划 → 逐任务执行 → 验证 → ✓ 通过 / ✗ 自纠重试
  → 汇总报告

与 harness 的关键区别：每个主要阶段都需用户确认后才进入下一步。

架构

AgentLoop (编排器: 探索→规划→执行→验证→汇总)
  └── ChatService._call_llm_with_tools()
        └── HarnessEngine (工具循环内核，复用 harness 引擎)
              ├── StreamEngine (流式传输 + watchdog)
              └── ToolExecutor (工具执行)

/loop 运行在 harness 之上——每个任务执行内部调用 harness 工具循环。AgentLoop 在其外围添加结构化阶段和用户确认门控。

阶段流水线

阶段 1：探索

LLM 使用只读工具（kg_find_symbol、read_file、glob_files、grep_content）了解项目现状——文件路径、已有接口、技术栈。

探索摘要展示给用户，提供三个选项：

操作	效果
回车	接受探索结果，进入规划
输入文字	提供修正/补充，重新探索
q	取消循环

阶段 2：规划

LLM 将目标拆解为 JSON 任务清单。每个任务包含：

字段	说明
`desc`	任务描述（具体到可直接执行）
`constraints`	技术/设计/命名约束
`acceptance`	可验证的验收标准
`verify`	机器可判定的验证命令（可选）

任务清单展示给用户，提供三个选项：

操作	效果
回车	确认计划，开始执行
输入文字	提供修正，重新规划
q	取消循环

阶段 3：执行

任务顺序执行。每个任务：

进入 harness 工具循环（LLM 读取文件、编辑代码、运行命令）
首轮强制只读工具（先探索再动手）
harness 循环结束后运行 verify 命令
失败时：将失败原因回灌进任务（自纠），最多重试 3 次

阶段 4：汇总

报告每个任务的完成状态：

目标完成情况：4/5 任务验证通过
目标：为 users 表添加 phone_number 字段

[OK] 任务1: 创建迁移 SQL — 验证通过
[OK] 任务2: 更新 SQLAlchemy 模型 — 验证通过
[OK] 任务3: 更新 API 端点 — 验证通过（尝试 2 次）
[OK] 任务4: 添加验证 — 验证通过
[!!] 任务5: 运行测试 — 验证失败: test_phone_format FAILED

标记	含义
`[OK]`	验证通过
`[!!]`	3 次自纠重试后仍失败

双闸控制

闸门	限制	用途
任务轮次	MAX_ROUNDS = 20	总任务数硬上限
单步重试	MAX_RETRIES = 3	每个任务的自纠重试次数
异议重做	MAX_REDO = 3	探索/规划阶段的最大重做次数

3 次失败不会中断循环——步骤标记为 [!!]，循环继续执行后续任务。

验证策略

默认模式

编译/语法检查命令正常执行（如 py_compile、mvn compile、pytest）
启动类命令被拦截（npm start、python app.py 等），自动降级为编译检查

--run 模式

/loop --run <目标> 允许执行启动类命令：

允许长驻进程命令
超时时用户选择：降级编译检查 / 重试 / 跳过
适用于确实需要启动应用验证的任务

自动降级映射

启动命令	降级为
`spring-boot:run`	`mvn compile -q`
`npm start`	`npm run build --if-present`
`python app.py`	`python -m py_compile app.py`
`flask run`	`python -m py_compile app.py`
`django runserver`	`python manage.py check`

何时使用 /loop

适合	不太适合
可分解的任务	探索性研究
多文件重构	单次快速编辑
迁移脚本	需要创造性决策的任务
CI/CD 流水线变更	模糊的需求

示例：数据库迁移

/loop 为 users 表添加 phone_number 字段：
1. 创建迁移 SQL 文件
2. 在 SQLAlchemy 模型中添加字段
3. 更新所有返回用户数据的 API 端点
4. 添加手机号格式验证
5. 运行测试并验证

/loop 会：

探索项目，找到现有模型、端点和测试模式
展示探索摘要供你确认
生成带具体文件路径和验证命令的任务清单
展示计划供你确认
按顺序执行每个任务（含自纠重试）
报告通过/失败状态的结果

示例：依赖升级

/loop 将 httpx 从 0.24 升级到 0.27：
1. 更新 requirements.txt
2. 运行 pip install
3. 修复所有导入错误
4. 运行测试套件
5. 如需要更新 CI 配置

使用技巧

明确验证标准

/loop 在每个步骤都有清晰的成功标准时表现最佳：

# 好 — 清晰的验证
/loop 重构 auth 模块：
1. 将 login/register 移到 auth/service.py
2. 更新所有引用这些函数的文件（验证：grep 返回 0 个旧导入）
3. 运行测试（验证：所有测试通过）

# 模糊 — 难以验证
/loop 重构 auth 模块

确认时提供修正

在每个确认门控处，你可以输入修正而不是直接回车：

探索后："你漏掉了 utils/auth.py 的辅助函数——规划时请包含它们"
规划后："任务 3 还应该更新 docs/api.md 中的 API 文档"

这会将你的反馈注入后重新执行该阶段。

每步内部使用 harness

你同时获得两者的优势：

harness 处理每个步骤内的复杂性（文件读取、编辑、命令执行）
/loop 在步骤之间提供结构和验证