Table of Contents

返回实用 AI 工作流课程

目标循环会重复执行,直到明确的结果通过检查或触发停止规则。 有用的循环会读取当前状态,执行一个范围明确的操作,检查结果,并记录发生的情况。“继续尝试”这样的开放式指令没有可靠的完成规则。

学习目标: 你将运行一个有界实验循环,其中包含一个已知会失败的检查,并记录停止决策。

要点

  • 目标: 用可观察的条件描述结果。
  • 状态: 当前文件、输出、错误和源代码修订版本。
  • 检查: 与目标相关的测试或审查。
  • 重试预算: 针对一次失败允许的最大尝试次数。
  • 停止规则: 要求结束任务或请求人员决策的条件。

开始之前

前置材料: 任务包 、 验证记录 和 委派课程 。预留 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 检查失败进行一次范围明确的编辑
每次编辑之后记录准确测试、计数、无效值的非零退出码和已更改文件接受、诊断或停止
预算耗尽时记录剩余失败和当前差异不再尝试,直接移交

练习并检查

**你的成果:**受控失败测试、前后观察到的输出、尝试日志,以及最终接受或停止的决定。如果第一次编辑就通过,记录一次尝试即可。不要为了填满日志而编造第二次失败。

**完成检查:**契约注明了来源、文件范围、可观察检查、重试上限、至少一项立即停止条件和移交方式。记录包含真实红色测试、后续检查结果,以及通过或因预算耗尽而停止的结果。第二次尝试要指出新的原因,并且与第一次不同。

检查理解情况

  1. **问题:**第一次红色契约测试证明了什么?**答案:**启动项目缺少所需的状态筛选功能,证明来自编辑前编写的测试。
  2. **问题:**即使还有重试次数,循环何时也必须停止?**答案:**发生范围外更改、权限不明确或要求冲突时。

故障排除

  • **循环重复同一失败:**停止并提出新的原因假设。
  • **检查越来越宽松:**恢复原始验收标准。
  • **外部结果不确定:**再次尝试前检查当前状态。
  • **预算耗尽:**移交失败记录,不要隐瞒问题。

下一步

继续学习可选的 专业代理评估 ,或直接进入 AI 工作流课程结业项目 。如需了解运行时选项,请阅读 代理运行框架指南 。

课程导航: 上一课:代理委派 , 课程大纲 。