有界 AI 代理循环:检查、重试与停止规则

Table of Contents
目标循环会重复执行,直到明确的结果通过检查或触发停止规则。 有用的循环会读取当前状态,执行一个范围明确的操作,检查结果,并记录发生的情况。“继续尝试”这样的开放式指令没有可靠的完成规则。
学习目标: 你将运行一个有界实验循环,其中包含一个已知会失败的检查,并记录停止决策。
要点
- 目标: 用可观察的条件描述结果。
- 状态: 当前文件、输出、错误和源代码修订版本。
- 检查: 与目标相关的测试或审查。
- 重试预算: 针对一次失败允许的最大尝试次数。
- 停止规则: 要求结束任务或请求人员决策的条件。
开始之前
前置材料: 任务包 、 验证记录 和 委派课程 。预留 45 分钟。难度为中级。使用一份全新的合成实验副本,这样你会预先知道第一次检查会失败。
编写循环契约
**对于按状态筛选的请求,**请在任何重试之前定义契约:
目标:支持 --status open|done,同时不改变默认输出。
来源:docs/requirements.md,修订版 1。
允许的文件:task_report.py 和针对性测试。
检查:单元测试、计数 4/2/2、无效值返回非零退出码。
重试预算:首次尝试后最多修改两次。
立即停止:来源冲突、意外的文件变更、机密泄露,
或与此请求无关的基线检查失败。
交接:报告最终差异、命令、输出、尝试次数和未解决的问题。
**预算是任务策略,**不是产品默认设置。两次重试足以诊断一个小型实验任务,同时避免掩盖重复失败。生产任务需要单独确定风险和审查方式。
使用状态表
| 步骤 | 要记录的状态 | 决策 |
|---|---|---|
| 读取 | 源代码修订版本和初始结果 | 初始状态不同则停止 |
| 操作 | 已更改的文件和执行的操作 | 拒绝范围外更改 |
| 检查 | 具体测试和手动输出 | 接受或诊断 |
| 重试 | 失败原因和新假设 | 仅在预算内继续 |
| 移交 | 最终状态和下一位负责人 | 通过或受阻后停止 |
记录每次尝试,而不只记录最后一条消息。 三次未记录的编辑之后测试才通过,无法说明发生了什么变化。用简短日志记录失败、修订后的假设和新证据。
分析一次失败
第一次尝试示例: 代理添加筛选功能和测试。open 输出 2,但 --status invalid 输出 0 并正常退出。要求规定无效值必须返回非零退出码。将该检查标记为失败。
诊断: 检查参数验证逻辑。代理把未知值当作空匹配,而不是错误。请求一项范围明确的修正,在计数之前验证允许的值。重新运行无效值用例和所有先前检查。
尝试 1:无效状态返回成功,因此验收失败。
发现的原因:没有验证允许的值。
尝试 2 的请求:拒绝不支持的值,并保留 4/2/2 的计数。
所需证据:完整测试运行,以及无效命令的退出状态。
第二次尝试的预期结果: 对 invalid 返回清楚的错误和非零退出码,同时有效计数保持不变。如果第二次尝试仍然失败,只有在确定新原因后才使用最后一次重试。重复同一请求不属于诊断。
处理含糊结果
进程停止但没有结果,不代表成功。 如果工具在可能写入文件后超时,重新运行之前先检查文件和 Git 状态。如果连接的服务报告结果未知,重复外部操作之前先读取当前状态。在实验之外,重复发送、发布或写入会带来实际风险。
**停下来进行人工审查,**如果要求与另一项已批准来源冲突、权限阻止操作、重试预算耗尽,或请求的操作跨越发布边界。移交内容应说明准确状态和待解决的决策。
区分循环与监控器
编辑循环在有限任务内运行,并在每次操作后检查结果。定时监控器稍后启动,用来检查某个条件。监控器需要独立的运行频率、变更阈值、通知规则和停止条件。不要把实验中的编辑循环变成定期任务。下一课会在启用持久运行的系统之前先评估它们。
运行受控循环
从未修改的实验开始。 两个基线测试都通过。在新解压的副本中创建 tests/test_loop_contract.py,并加入下面的检查。该文件定义了启动项目中不存在的目标功能,不属于维护中的启动 ZIP。
"""One controlled failing check for the status-filter exercise."""
import subprocess
import sys
import unittest
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
class LoopContractTests(unittest.TestCase):
def test_open_status_count(self):
result = subprocess.run(
[sys.executable, str(ROOT / "task_report.py"),
str(ROOT / "tasks.json"), "--status", "open"],
capture_output=True, text=True, check=False,
)
self.assertEqual(result.returncode, 0, result.stderr)
self.assertEqual(result.stdout.strip(), "Total tasks: 2")
if __name__ == "__main__":
unittest.main()
运行 python3 -m unittest discover -s tests -v。 两个原始测试应该通过,新契约测试应该失败,因为启动项目不支持 --status。记录实际错误。如果你按第 0 课的说明初始化了 Git,也记录 git status --short。否则,将已更改文件与未修改的解压副本进行比较。在 Windows 上,如果环境使用 launcher,请运行 py -3。
**把预算设为三次尝试:**第一次编辑,最多再修正两次。把上面的循环契约交给代理,并请求一次范围明确的编辑。每次尝试之后检查已更改文件,重新运行所有测试,并运行默认命令、open、done 和无效值命令。下一次尝试之前先记录失败原因。如果检查通过、无关的基线检查失败、出现范围外更改,或第三次尝试失败,就停止。
**学习路线:**记录红色测试之后,在这份新副本中应用 第 5 课完整答案 。重新运行相同检查,并记录没有执行代理编辑。保留受控契约测试。不要为了让它通过而弱化或删除测试。
| 尝试 | 状态和观察 | 决策 |
|---|---|---|
| 编辑之前 | 两个基线测试通过,新 open 检查失败 | 进行一次范围明确的编辑 |
| 每次编辑之后 | 记录准确测试、计数、无效值的非零退出码和已更改文件 | 接受、诊断或停止 |
| 预算耗尽时 | 记录剩余失败和当前差异 | 不再尝试,直接移交 |
练习并检查
**你的成果:**受控失败测试、前后观察到的输出、尝试日志,以及最终接受或停止的决定。如果第一次编辑就通过,记录一次尝试即可。不要为了填满日志而编造第二次失败。
**完成检查:**契约注明了来源、文件范围、可观察检查、重试上限、至少一项立即停止条件和移交方式。记录包含真实红色测试、后续检查结果,以及通过或因预算耗尽而停止的结果。第二次尝试要指出新的原因,并且与第一次不同。
检查理解情况
- **问题:**第一次红色契约测试证明了什么?**答案:**启动项目缺少所需的状态筛选功能,证明来自编辑前编写的测试。
- **问题:**即使还有重试次数,循环何时也必须停止?**答案:**发生范围外更改、权限不明确或要求冲突时。
故障排除
- **循环重复同一失败:**停止并提出新的原因假设。
- **检查越来越宽松:**恢复原始验收标准。
- **外部结果不确定:**再次尝试前检查当前状态。
- **预算耗尽:**移交失败记录,不要隐瞒问题。
下一步
继续学习可选的 专业代理评估 ,或直接进入 AI 工作流课程结业项目 。如需了解运行时选项,请阅读 代理运行框架指南 。


