Agent 编排：用 Loop 把一件事迭代到合格

一句话

Loop 是把一件事拆成若干节点、让 Agent 一轮轮跑到验收通过为止的流水线；列表页的说明就是「将复杂任务拆成模块化流水线，循环迭代直到验收通过」。

在哪打开

侧边栏「Agent」组里的「Loop」。点「新建 Loop」只有一个入口：说清要做什么。

主要动作

• 说清需求 → 生成模块图（主入口）：选「老项目建模」（先读仓库取证）或「新项目设计」，填需求、约束和（老项目）仓库目录 → 结果：生成带依赖的模块图并进编辑器，审图后再保存运行。详见「从需求生成模块图」。
• 待确认项：编辑器顶部显示「待确认 N」。点开是几条判据——验收标准有没有可机械判定的判据、参数有没有声明、产出落在哪、成本有没有上限。带「定位」的直接跳到对应节点；都在这里补，不必先跑一遍才发现。
• 从示例改（次要入口）：新建弹窗底部折叠着示例，内置「图文创作」「内容工厂」「代码任务」「研究简报」「通用 worker」，以及你自己存下的示例。示例是合格样例与词汇表，不是起点——真实需求几乎都要改，不如先说需求。
• 存为示例：编辑器工具条上的书签按钮，把当前编排（图 + 参数 / 轮次 / 成本上限）存成示例，下次「从示例改」直接可用；同名覆盖。示例是跑出来的产物，不用维护模板矩阵。
• 运行：卡片点「运行」，填参数后点「开始运行」→ 结果：跳到运行详情；限制（参数按输入 Schema 生成，没声明参数时会提示「该 Loop 无需输入参数」）。
• 看运行 / 中止：运行详情里有「流程执行图」「运行结果」「执行步骤」，运行中可点「中止」。
• 人工审批：跑到人工闸门会显示「等待人工审批：通过后继续，打回则中止。」，给「通过 / 打回」。
• 验收节点怎么判断：验收节点的输出要按契约 ACCEPT_JSON 给：{ accepted, score, criteria[{key, pass, reason}], feedback, feedbackTarget }。判定方式三选一：「按 accepted 布尔」「分数达到阈值」或「全部标准通过」，阈值是面板上的「通过阈值 minScore（0..1）」。输出里没有布尔字段时一律按不通过。自检节点走另一套契约：要有 ok 和 issues。
• 验收标准要带判据：面板里每条标准分「做到什么算完成」和「怎么判」两栏，判据必须是可机械观察的（命令与退出码、字段与期望值、数量、状态码）。判据为空或写成「体验好、文案清晰」这类主观话时会标黄——那不是风格问题，是这条标准根本无法判定，验收只能凭印象，循环也就停不下来。
• 重跑与自愈：验收不通过不是整轮重跑——按 feedbackTarget（没写就用回边目标）把目标节点及其后继标成待重跑、清掉它们的输出，下一轮只重跑这一截。每条连线的「回边上限」缺省等于「轮次 − 1」，到顶就按迭代上限收尾并保留最佳结果。单个节点还有「重试」次数，主要用于解析失败时带错误信息重试。自动自愈要同时满足：同一种失败签名累计 ≥3 次、当前没有待处理候选、距上次 ≥10 分钟，且只产出候选、不自动上线。
• 成本上限与最大轮数：工具条上直接填「轮次」和「成本上限$」。达到成本上限就以最佳结果收尾；自适应停止下分数连续几轮没改善也会收尾；强制停止时恢复分数最高的那一版。
• 看健康与优化：点「优化」进入健康与优化页，可见成功率、平均成本、平均轮次、首轮通过率、最佳分数与失败签名，也能点「手动优化」。

字段 / 状态说明

名称	含义	什么时候用
任务（task）	让 Agent 干一件具体的事，按输出契约收结构化结果	流水线的主体步骤
验收（accept）	对照标准判定上游结果并打分	需要一个「合格线」
反馈整理（feedback）	把上游验收的反馈写进上下文，供目标节点下一轮读取	告诉它下一轮改什么
扇出（split）	并发跑多个子任务：固定个数 / 按列表项 / 自定义子任务	一次处理一批
汇聚（merge）	把扇出结果合起来：汇聚为数组或按 key 合并	扇出之后收口
投产（publish）	把结果发出去：存草稿、发布、代码交付或仅草稿	通过验收后的落地动作（⚠ 当前版本只保存配置，执行定义尚未接入投产，运行不会真的发布/提交）
停止方式	自适应停止 / 固定轮次 / 手动	想让它自己判断什么时候停
工作目录	Agent 执行目录，可留空	代码类任务要指到仓库
失败签名	同一类失败反复出现就聚成一类：schema / accept-never-pass / cost-blowup / timeout / publish-failed	排查「为什么老是不过」

与其它功能的关系

• 投产节点能直接建草稿、发布到平台，或在工作目录里做一次 git 提交交付。
• 扇出是并发跑的，默认同时 4 个，可用环境变量 BANYAN_FANOUT_CONCURRENCY 覆盖。
• 健康度与失败签名喂给「自我纠正」：它只产出候选，不动正在用的版本；候选可「提升」为生产版本或「拒绝」。

限制与注意

• Loop 不等于表单的工作流：一个在侧边栏「Agent」里手动运行，一个挂在表单提交上自动触发。
• 投产节点尚未接入执行：执行定义目前只跑「任务」与「验收」，图里的投产节点不会真的发出去；编辑器「待确认」会如实标出这条，验收通过后的产物先手动交付。
• 成本上限填 0 表示不设上限，只有大于 0 时才封顶。
• 扇出里任何一个子任务失败，整个扇出节点就算失败。
• 投产节点做了 dry-run：探针试跑时不会真的发出去，只记录意图。
• 打了「已收敛」的 Loop 不再自动优化，要继续只能手动优化。

常见问题

Q：Loop 能挂到表单上自动跑吗？ A：界面上 Loop 只有「运行」入口，没有跟表单绑定的设置；表单那边用的是「工作流」。

Q：验收为什么老是不通过？ A：先看验收节点的提示词里那份 JSON 契约有没有被改坏——输出缺布尔字段会被直接判为不通过。

Q：它停下来了，结果为什么不是最后一轮？ A：成本封顶或迭代到顶时会保留分数最高的那一版，原因写在运行指标里。

Q：为什么老是同一种失败？ A：去健康与优化页看「失败签名」出现了几次；同一签名累计 ≥3 次且冷却期已过，系统会自己跑一次优化，但只产出候选。

Q：示例里没有我要的，要自己搭吗？ A：不用。新建时直接写需求生成模块图；跑顺之后把编排「存为示例」，下次就从它改——示例是跑出来的，不是预设的。

Q：「待确认」里的条目必须清理干净吗？ A：至少要清掉两条会影响收敛的：验收标准要有判据、参数要声明。成本上限和投产归属按你的情况定——不填也能跑，只是花多少、产出落在哪由你事后兜。