mcpField
A
aif-loop

aif-loop

github.com/lee-toAgent 工作流1.1k94 次安装今天更新
代码仓库

关于 aif-loop

aif-loop 是用于按已确认标准反复生成和评估产物的 AI Factory 技能。它会保存循环状态与事件记录,支持跨会话继续处理。

主要功能

  1. 01执行六个有明确约定的阶段
  2. 02按定义的检查项评估产物
  3. 03评估未通过时改进产物
  4. 04持久化状态和事件历史
  5. 05恢复、停止、列出或查看循环

适用场景

  1. 01迭代完善项目文档
  2. 02按要求评估生成的配置
  3. 03在后续会话继续处理产物任务

安装

复制下面的命令,在终端中运行。

$npx skills add https://github.com/lee-to/ai-factory --skill aif-loop

安装后在 Claude Code 中输入/aif-loop确认已加载。

包含的文件

除 SKILL.md 外,安装时一起下载的参考资料和脚本。

references/
ACTIVE-TIME-BUDGET.md
CONTEXT-MANAGEMENT.md
CRITERIA-TEMPLATES.md
PHASE-CONTRACTS.md
RULE-SCHEMA.md
TERMINAL-REPORT.md

详细介绍

Loop - 反思迭代工作流

通过严格的阶段约定、评估规则和跨会话持久化状态,运行以结果为导向的迭代循环。

步骤 0:加载配置

首先: 如果 .ai-factory/config.yaml 存在,则读取它以解析:

  • 路径: paths.description、paths.architecture、paths.rules_file、paths.roadmap、paths.plan、paths.plans 和 paths.evolution
  • 语言: 提示词使用 language.ui,生成的内容使用 language.artifacts

如果 config.yaml 不存在,则使用默认值:

  • 路径:所有产物均使用 .ai-factory/
  • 语言:en(英语)

术语:

  • loop = 针对某个任务别名的一次完整执行(存储在 run.json 中,由 run_id 标识)
  • 迭代 = loop 内的一个周期

核心思路

每次迭代执行 6 个阶段,并尽可能并行执行:

  1. PLAN - 为当前迭代制定简短计划
  2. PRODUCE - 生成一个 artifact.md ← 与 PREPARE 并行运行
  3. PREPARE - 根据规则生成检查脚本和测试定义 ← 与 PRODUCE 并行运行
  4. EVALUATE - 对产物运行已准备好的检查和内容规则,并为结果评分。使用并行 Task Agent 处理相互独立的检查组
  5. CRITIQUE - 提出明确的问题和修复方案(仅在未通过时执行)
  6. REFINE - 根据评析重写产物(仅在未通过时执行)
         PLAN
           │
    ┌──────┴──────┐
    ↓             ↓          ← parallel (Task tool)
 PRODUCE      PREPARE
 (artifact)   (checks)
    ↓             ↓
    └──────┬──────┘
           ↓
       EVALUATE              ← parallel check execution (Task tool)
       ┌───┼───┐
       ↓   ↓   ↓
      exec content aggregate
       └───┼───┘
           ↓
       CRITIQUE (if fail)
           ↓
       REFINE (if fail)

当质量达到要求、不再存在重大问题、用户停止运行、进展停滞或触发资源保护条件时停止(可选的时间预算、迭代次数上限)。完整的优先顺序见步骤 5。

持久化约定

在解析后的演进目录中,状态文件严格使用 3+1 个(仅在 loop 运行期间存在 current.json):

<resolved evolution dir>/current.json
<resolved evolution dir>/<task-alias>/run.json
<resolved evolution dir>/<task-alias>/history.jsonl
<resolved evolution dir>/<task-alias>/artifact.md

除非用户明确要求,否则不要创建额外的索引文件或按迭代划分的文件夹树。

文件职责
  • current.json:仅指向活动的 loop;当 loop 变为 completed/stopped/failed 时删除
  • run.json:当前 loop 状态的唯一真实来源
  • history.jsonl:仅追加的事件日志(每行一个 JSON 对象)
  • artifact.md:产物内容的唯一真实来源(在 PRODUCE 和 REFINE 阶段后写入,绝不在 run.json 中重复存储)

命令模式

解析 $ARGUMENTS:

  • status - 显示 current.json 中的活动 loop 状态,然后停止
  • resume [alias] - 继续活动 loop 或指定别名的 loop
  • stop [reason] - 使用指定原因停止活动 loop(若省略,则使用 user_stop)
  • new <task> 或不指定模式并提供任务文本 - 启动新的 loop
  • list - 列出所有任务别名及其状态(running/stopped/completed/failed)
  • history [alias] - 显示某个 loop 的事件历史(默认为活动 loop)
  • clean [alias|--all] - 删除已停止/已完成/已失败的 loop 文件(需要用户确认;删除前务必确认)

如果没有任务且不存在活动 loop,则向用户询问任务提示词。

步骤 0:加载上下文

如果以下文件存在,请阅读:

  • 已解析的 description 路径
  • 已解析的 architecture 路径
  • 已解析的 RULES.md 路径

使用这些文件,确保输出符合项目约定。

阅读 .ai-factory/skill-context/aif-loop/SKILL.md——如果文件存在,则必须阅读。

此文件包含项目专属规则,这些规则由 /aif-evolve 根据补丁、代码库约定和技术栈分析逐步积累而成。这些规则针对当前项目量身定制。

如何应用 skill-context 规则:

  • 将其视为此技能通用指令的项目级覆盖规则
  • 如果 skill-context 规则与本 SKILL.md 中的通用规则冲突,以 skill-context 规则为准(更具体的上下文优先——这与嵌套 CLAUDE.md 文件遵循相同原则)
  • 如果不存在冲突,则同时应用两者:SKILL.md 中的通用规则 + 项目规则
  • 即使 skill-context 规则看似与此技能的默认规则矛盾,也不要忽略——这是因为项目经验已经证明默认规则不够完善
  • 关键: skill-context 规则适用于此技能的所有输出——包括生成的产物、运行状态和评估标准。如果 skill-context 规则要求“产物必须包含 X”或“评估必须检查 Y”,则必须遵守。生成违反 skill-context 规则的循环输出属于缺陷。

执行要求: 生成任何输出产物后,都要根据所有 skill-context 规则进行检查。如果违反了任何规则,请在向用户展示前修正。

步骤 0.1:处理非迭代命令

如果命令是 status、stop、list、history 或 clean,则执行相应操作后停止:

  • status:读取 current.json;如果文件存在,则读取其指向的 run.json,并显示 alias | status | iteration | phase | current_step | last_score | updated_at;如果设置了预算,还要显示 completed_phase_seconds / max_completed_phase_seconds;如果文件不存在,则报告当前没有正在运行的循环
  • stop [reason]:仅停止当前处于运行状态的循环;设置 run.json.status = "stopped" 和 run.json.stop.reason = <reason or "user_stop">,向 history.jsonl 追加 stopped 事件,然后删除 current.json(清除活动指针)并退出
  • list:扫描已解析的演进目录,读取每个 run.json,并显示 alias | status | iteration | last_score | updated_at 表格
  • history [alias]:读取该 alias(或活动循环)的 history.jsonl,并显示格式化的事件时间线
  • clean [alias|--all]:显示将要删除的内容,并通过 AskUserQuestion 请求用户明确确认,然后删除循环目录。仅清理已停止、已完成或已失败的循环——拒绝清理正在运行的循环。必要时更新 current.json。

步骤 1:初始化或恢复循环

1.1 确保目录存在
mkdir -p <resolved evolution dir>
1.2 别名和 ID(新循环)

生成:

  • task_alias:小写连字符格式的 slug(3–64 个字符)
  • run_id:<task_alias>-<yyyyMMdd-HHmmss>
1.3 写入 current.json
{
  "active_run_id": "courses-api-ddd-20260218-120000",
  "task_alias": "courses-api-ddd",
  "status": "running",
  "updated_at": "2026-02-18T12:00:00Z"
}
1.4 写入初始 run.json
{
  "run_id": "courses-api-ddd-20260218-120000",
  "task_alias": "courses-api-ddd",
  "status": "running",
  "iteration": 1,
  "max_iterations": 4,
  "max_completed_phase_seconds": null,
  "completed_phase_seconds": 0,
  "phase_started_epoch_seconds": null,
  "phase": "A",
  "current_step": "PLAN",
  "task": {
    "prompt": "OpenAPI 3.1 spec + DDD notes + JSON examples",
    "ideal_result": "..."
  },
  "criteria": {
    "name": "loop_default_v1",
    "version": 1,
    "phase": {
      "A": { "threshold": 0.8, "active_levels": ["A"] },
      "B": { "threshold": 0.9, "active_levels": ["A", "B"] }
    },
    "rules": []
  },
  "plan": [],
  "prepared_checks": null,
  "evaluation": null,
  "critique": null,
  "stop": { "passed": false, "reason": "" },
  "last_score": 0,
  "stagnation_count": 0,
  "created_at": "2026-02-18T12:00:00Z",
  "updated_at": "2026-02-18T12:00:00Z"
}
1.5 恢复逻辑

恢复循环时:

  1. 读取 run.json,获取 current_step 和 iteration
  2. 读取 history.jsonl 中的最后一个事件,以确认状态一致
  3. 如果 run.json.current_step 表明某个阶段曾被中断:
    • 从该阶段重新执行(不要跳过)
    • PRODUCE_PREPARE:始终重新运行 PRODUCE 和 PREPARE(具有幂等性——产物会被覆盖,检查项会重新生成)
  4. 如果 run.json.status 为 stopped、completed 或 failed,则告知用户并建议使用 new(对于 failed 运行,还要显示 history.jsonl 中最后一个 phase_error 事件,以便用户了解出错原因)
  5. 丢弃过期的 phase_started_epoch_seconds:在中断的阶段实际重新启动时,将其设为当前的 date +%s。中断的尝试不计入预算——只有已累积的 completed_phase_seconds(来自已完成的阶段片段)会保留(参见 references/ACTIVE-TIME-BUDGET.md)。

第 2 步:交互式设置(新循环)

快速模式(默认,先确认)

如果任务提示中包含足够的上下文,可以推断任务类型和理想结果:

  1. 从提示中自动检测任务类型(API 规范、代码、文档、配置)
  2. 从 references/CRITERIA-TEMPLATES.md 加载匹配的模板
  3. 起草推断出的规则、阶段阈值(回退值:A=0.8,B=0.9)、最大迭代次数(默认:4)以及已完成阶段的时间预算(默认:none;仅根据 references/ACTIVE-TIME-BUDGET.md 中的设置规则推断)
  4. 将推断出的设置作为摘要草案展示,并在最大迭代次数旁显示标准化后的预算
  5. 始终通过 AskUserQuestion 明确询问用户是否确认成功标准(规则/阈值),即使任务文本中已包含这些标准
  6. 始终通过 AskUserQuestion 明确询问用户是否确认最大迭代次数,即使任务文本中已包含迭代次数
  7. 只要草拟的值不是 null,就始终明确询问用户是否确认时间预算,并始终提供 none 作为选项
  8. 如果用户更改了标准、最大迭代次数或预算,更新草案并重新确认全部三个字段
  9. 只有在明确确认后,才开始第 1 次迭代
  10. 如果无法自动检测任务类型(提示存在歧义或混合了多种类型),则立即转入完整设置流程
完整设置

关键防护措施:

  • 即使任务提示中已写明成功标准和最大迭代次数,也始终重新询问并明确确认。

在开始第一次迭代前,提出简洁的设置问题:

  1. 任务类型——产物属于哪种类型?(API 规范、代码、文档、配置、其他)——用于从 references/CRITERIA-TEMPLATES.md 加载模板
  2. 理想结果的定义
  3. 强制检查项(测试、模式/契约、具体要求)
  4. 质量阈值(A/B 阶段)
  5. 最大迭代次数(默认:4)
  6. 已完成阶段的时间预算(秒,默认:none)——明确提供 none 选项;领域级超时不等同于循环预算
  7. 重大问题的判定标准
  8. 明确确认:“确认这些成功标准吗?”
  9. 明确确认:“确认最大迭代次数 = N 吗?”
  10. 预算不为 none 时,明确确认:“确认时间预算 = N 秒吗?”

根据回答生成评估规则:

  • 从 references/CRITERIA-TEMPLATES.md 加载匹配的模板作为起点
  • 根据理想结果和强制检查项添加任务专属规则
  • 开始前让用户审核并调整规则

将回答和生成的规则保存在 run.json.criteria 中(作为可复现的快照)。

在用户明确确认之前,绝不将从任务文本中解析出的标准、迭代限制或时间预算视为最终值。

持久化前的标准化规则:

  • run.json.max_iterations 是迭代次数限制的唯一事实来源
  • run.json.max_completed_phase_seconds 是时间预算的唯一事实来源;该字段为可选项——除非用户要求并确认预算,否则保存为 null(无限制)。不含该字段的运行文件按 null 处理。允许的值为 null 或正整数秒数;字符串、0、负数或小数均为验证失败(phase_error),绝不进行强制转换——请参阅 references/ACTIVE-TIME-BUDGET.md
  • 每条规则都必须扩展为完整的 RULE-SCHEMA 格式(id、description、severity、weight、phase、check)
  • 如果模板简写中省略了 weight,则根据严重性推导(fail=2,warn=1,info=0)

第 3 步:阶段契约

运行阶段前,加载:

  • references/PHASE-CONTRACTS.md——每个阶段的严格输入/输出契约
  • references/RULE-SCHEMA.md——规则格式和分数计算
3.1 阶段
  • PLAN - 生成迭代计划(顺序执行)
  • PRODUCE - 生成产物(与 PREPARE 并行执行)
  • PREPARE - 根据规则和任务提示词生成检查脚本/定义(与 PRODUCE 并行执行)
  • EVALUATE - 运行已准备的检查和内容规则,并汇总分数(通过 Task 并行执行检查组)
  • CRITIQUE - 识别问题并提供修复说明(顺序执行,仅在失败时执行)
  • REFINE - 对产物应用修复(顺序执行,仅在失败时执行)
3.2 并行执行模型

通过 Task 工具实现两个层级的并行:

  1. 阶段间:PLAN 完成后,PRODUCE 和 PREPARE 作为并行的 Task Agent 运行。两者都只依赖 PLAN 的输出。
  2. 阶段内:EVALUATE 为独立检查组启动并行的 Task Agent(通过 Bash 执行可执行检查,通过 Read/Grep 检查内容规则),并将结果汇总为最终分数。
3.3 阶段输出格式

每个阶段都会生成其定义的输出(参见 PHASE-CONTRACTS.md)。不使用封套包装。不输出路由器内容。

第 4 步:迭代执行

每次迭代:

  1. 设置 run.json.current_step = "PLAN",运行 PLAN 阶段
  2. 设置 run.json.current_step = "PRODUCE_PREPARE",启动两个并行的 Task Agent:
    • 任务 A(PRODUCE):生成产物 → 写入 artifact.md
    • 任务 B(PREPARE):根据规则和计划生成检查脚本/定义
    • 等待两者完成
  3. 设置 run.json.current_step = "EVALUATE",运行 EVALUATE 阶段:
    • 为独立检查组启动并行的 Task Agent:
      • 可执行检查(编译、lint、测试)→ 使用 Bash 的 Task
      • 内容规则(结构、完整性、风格)→ 使用 Read/Grep 的 Task
    • 汇总结果并计算分数
  4. 如果 passed=false:
    • 首先按优先级顺序评估第 5 步的停止条件。 如果满足其中任何一项,则以相应原因停止,而不是继续执行——第 5 步会在迭代继续前检查,绝不会在之后检查
    • 否则:设置 run.json.current_step = "CRITIQUE",运行 CRITIQUE 阶段
    • 设置 run.json.current_step = "REFINE",运行 REFINE 阶段
    • 将更新后的产物写入 artifact.md
    • 增加迭代计数并继续
  5. 如果 phase=A 且 passed=true:
    • 切换到 phase=B,启用 B 级规则
    • 设置 run.json.current_step = "PREPARE",使用 phase=B 重新运行 PREPARE,以生成 B 级检查项(不运行 PLAN/PRODUCE——产物已通过 A 级评估)
    • 设置 run.json.current_step = "EVALUATE",使用已准备的 B 级检查项评估同一产物
    • 如果 B 级评估也通过 → 成功停止(threshold_reached)
    • 如果 B 级评估失败 → 继续执行 CRITIQUE → REFINE,然后增加迭代计数
  6. 如果 phase=B 且 passed=true:
    • 成功停止(threshold_reached)
回退为顺序执行

如果 Task 工具不可用或返回错误,则回退为顺序执行:PLAN → PRODUCE → PREPARE → EVALUATE → CRITIQUE → REFINE。循环必须能够在没有并行执行的情况下正常运行。

在此回退过程中,PRODUCE_PREPARE 仍是一个逻辑步骤:current_step 不拆分,PRODUCE 和 PREPARE 之间不会触发预算停止,并行尝试失败后的顺序重试仍计为同一时间段。

第 5 步:停止条件

优先级约定

在同一阶段边界,可能同时满足多个条件。以下编号顺序是冲突时的判定顺序,而非一组彼此独立的检查:从上到下评估,并将第一个匹配项报告为 stop.reason。完成条件优先于资源条件,因此成功完成的运行不会因为恰好在同一时刻耗尽资源而被重新标记为 stopped。

  1. threshold_reached — phase=B 且 passed=true
  2. no_major_issues — phase=B,且当前评估中没有任何 fail 严重级别的规则未通过:只剩下 warn/info,并且没有更严格的阶段。此条件绝不会在 phase=A 触发——A 阶段评估通过后会进入 phase=B(步骤 4.5)或继续优化,因此不会跳过 B 阶段规则
  3. user_stop — 用户明确停止
  4. stagnation — stagnation_count >= 2(参见下方“停滞规则”)
  5. budget_exceeded — 已设置 max_completed_phase_seconds,且 completed_phase_seconds >= max_completed_phase_seconds
  6. iteration_limit — iteration >= run.max_iterations

有意将 budget_exceeded 排在 iteration_limit 之前:时间是无法挽回的外部资源,因此两者同时触发时,指出预算耗尽更有用。关键在于,所有位置的顺序必须一致——此列表会原样重复出现在 docs/loop.md 和 subagents/claude/agents/loop-orchestrator.md 中,三处内容必须保持同步。

已完成阶段的时间预算

run.json.max_completed_phase_seconds 是已完成阶段片段所用时间的可选上限;值为 null 或未设置表示不设上限。此上限是软限制——仅在阶段边界检查,不会在阶段(或其重试)执行过程中将其中断,因此运行时间最多可能超出正在执行阶段的时长。只有已完成的阶段片段会计入:按定义,中断的阶段不计入,而非偶然漏计。完整约定——类型和不变量、边界测量、将 PRODUCE_PREPARE 和重试视为单个片段、时钟回拨、诊断信息和设置规则:references/ACTIVE-TIME-BUDGET.md。

停滞规则

跟踪分数进展:

  • delta = score - last_score
  • 如果 delta < 0.02 且没有严重级别为 fail 的阻碍项,则递增 stagnation_count
  • 如果 stagnation_count >= 2,则以 stagnation 停止

步骤 6:持久化写入(每一步)

每次阶段输出后:

  1. 更新 run.json(包括 current_step)
  2. 向 history.jsonl 追加事件
  3. 更新 current.json.updated_at
  4. 在 PRODUCE 和 REFINE 阶段后将 artifact.md 写入磁盘
  5. 在 REFINE 覆盖 artifact.md 之前,将先前产物的 SHA-256 哈希保存到 refinement_done 事件载荷中的 "previous_artifact_hash",以便验证完整性且不使历史记录臃肿
  6. 设置了 max_completed_phase_seconds 时,按照 references/ACTIVE-TIME-BUDGET.md,在每个阶段边界更新 completed_phase_seconds / phase_started_epoch_seconds,并在同一次 run.json 写入中完成——绝不单独计时

事件名称:

  • run_started
  • plan_created
  • artifact_created
  • checks_prepared
  • evaluation_done
  • critique_done
  • refinement_done
  • phase_switched
  • iteration_advanced
  • phase_error
  • stopped
  • failed

history.jsonl 示例行:

{"ts":"2026-02-18T12:01:10Z","run_id":"courses-api-ddd-20260218-120000","iteration":1,"phase":"A","step":"EVALUATE","event":"evaluation_done","status":"ok","payload":{"score":0.72,"passed":false}}

步骤 7:循环后

工件状态(在报告任何数值前先确认)

停止可能发生在任意阶段边界,因此工件可能不存在(not_created)、从未评估(unevaluated)、比存储的评估更新(stale,通过 evaluation.artifact_hash 检测),或已评估(evaluated)。只有状态为 evaluated 时,才能报告数值型 final_score 或成功距离信息块;其他三种状态均应打印 final_score: unavailable,并说明原因;如果之前有过评分,还要给出 last_evaluated_score。完整契约、输出格式和各状态规则:references/TERMINAL-REPORT.md。

循环停止后(无论何种原因):

  1. 显示最终状态摘要(iteration、max_iterations、phase、artifact_status、按上述规则给出的 final score、stop reason)
  2. 如果 stop reason 为 iteration_limit 或 budget_exceeded,artifact_status 为 evaluated,且该评估的 passed=false,则必须包含成功距离详情:
    • 当前阶段阈值和最终评分
    • 与阈值的数值差距(threshold - score,下限为 0)
    • 剩余未通过的 fail 严重级别规则数量,以及阻塞规则 ID
    • 规则进度(passed_rules / total_rules)
  3. 如果 stop reason 为 budget_exceeded,还要包含预算诊断信息——completed_phase_seconds、max_completed_phase_seconds、overshoot_seconds、last_completed_step——并在 stopped 事件负载中重复这些信息(references/ACTIVE-TIME-BUDGET.md)
  4. 询问用户将最终工件保存到何处(默认:保存在 <resolved evolution dir>/<alias>/artifact.md)——当 artifact_status 为 not_created 时,完全跳过步骤 4-5,并说明工件不存在,不要提供不存在的文件
  5. 提供将工件复制到用户指定路径的选项
  6. 根据工件类型建议后续技能:
    • API 规范 -> 使用 /aif-plan 实施
    • 代码 -> 使用 /aif-verify 检查
    • 文档 -> 使用 /aif-docs 集成
  7. 根据停止原因更新 run.json.status;如果 current.json 指向此循环,则删除 current.json(不再有活动循环):
停止原因状态
threshold_reachedcompleted
no_major_issuescompleted
user_stopstopped
iteration_limitstopped
stagnationstopped
budget_exceededstopped
phase_errorfailed

映射适用于按 Step 5 优先级契约选定的原因,因此,在同一边界触发资源保护条件和完成保护条件时,绝不会将已完成的运行从 completed 降级为 stopped。

步骤 8:面向用户的响应格式

每次迭代后显示简洁摘要——不要将完整的 run.json 或 artifact.md 内容倾倒到对话中。工件已保存在磁盘上;重复内容会浪费上下文。

迭代摘要格式
── Iteration {N}/{max} | Phase {A|B} | Score: {score} | {PASS|FAIL} ──
Plan: {1-line summary of plan focus}
Hash: {first 8 chars of artifact SHA-256}
Changed: {list of added/modified sections, or "initial generation"}
Failed: {comma-separated rule IDs, or "none"}
Warnings: {comma-separated rule IDs, or "none"}
Artifact: <resolved evolution dir>/<alias>/artifact.md
  • Hash — 让用户无需阅读完整工件即可确认查看的是哪个版本
  • Changed — 显示迭代间实际发生的变化,仅凭摘要即可发现回归

如果 passed=false,附上一段简洁的批评摘要(每个问题列出规则 ID 和一行修复指示)。不要重复完整工件或完整评估对象。

当循环以 reason=iteration_limit 或 reason=budget_exceeded 终止、artifact_status 为 evaluated 且 passed=false 时,在最终响应中附加简洁的 distance_to_success 信息块。对于其他任何 artifact_status,改为打印步骤 7 中的 final_score: unavailable 信息块——绝不可基于不属于当前工件的评估计算差距。

完整输出例外情况

仅在以下情况下显示完整的产物内容(而不只是摘要):

  1. 循环终止 — 最后一轮迭代输出完整产物;但如果 artifact_status 为 not_created,则说明未生成产物以及循环停止的原因
  2. Phase A → B 转换 — 在转换节点完整显示通过 Phase A 的产物一次,以便查看(仍会根据 Step 4 立即进行 B 级评估)
  3. 用户明确请求 — 用户在循环中途要求查看完整产物

Step 9:上下文管理

每轮迭代都会生成大量上下文(子 Agent 结果、评估数据、批评意见)。所有循环状态都会持久化到磁盘;清除上下文不会丢失任何内容,resume 会根据文件完整重建状态。

建议在第 2 轮迭代后、Phase A → B 转换时,以及任何 iteration >= 3 的迭代后清除上下文。切勿强制或自动清除;由用户决定。

具体措辞和理由:references/CONTEXT-MANAGEMENT.md。

错误恢复

阶段输出无效

如果某个阶段产生的输出不符合其约定:

  1. 使用事件 phase_error 将错误记录到 history.jsonl
  2. 使用相同输入重试该阶段一次
  3. 如果重试仍失败,则以 reason=phase_error 停止循环并显示错误
run.json 已损坏

如果 run.json 缺失或无法解析:

  1. 读取 history.jsonl,重建最近一次已知状态
  2. 根据最近的事件(上次迭代、阶段、分数等)重建 run.json
  3. 如果 history.jsonl 也缺失或为空,则告知用户并建议开始一个新循环

重要规则

  1. run.json 是当前状态的唯一可信来源(不存储产物内容)
  2. 磁盘上的 artifact.md 是产物内容的唯一可信来源;切勿在 run.json 中重复存储
  3. history.jsonl 仅允许追加;不要编辑旧事件
  4. 保持循环快速:计划简短、批评有针对性、改写尽量少
  5. 除 3+1 个持久化文件外,不要创建额外文件
  6. 评估器必须保持严格,不得发挥创意
  7. 优化器只修改通过失败规则所必需的内容
  8. 从简单方案开始,仅在指标显示有需要时增加复杂性
  9. 阶段失败后,必须恰好重试一次,然后再停止
  10. 默认使用精简的迭代摘要(Step 8)。仅允许在 Step 8 所列例外情况下输出完整产物;绝不要在对话中完整输出 run.json
  11. 在关键节点(Step 9)建议清除上下文——第 2 轮迭代后、阶段转换时,或当迭代轮数 >= 3 时

示例

/aif-loop new OpenAPI 3.1 spec + DDD notes + JSON examples
/aif-loop resume
/aif-loop resume courses-api-ddd
/aif-loop status
/aif-loop stop
/aif-loop list
/aif-loop history
/aif-loop history courses-api-ddd
/aif-loop clean courses-api-ddd
/aif-loop clean --all

评论

支持 Markdown