最佳实践：生产级 Agent Loop 工程准则

七天实战

规范落地后，用 Loop Engineering 子站做教学演示可以，但 生产以本文检查单与失败模式为准。并与 Hermes 最佳实践、DSH 最佳实践叠用：前者管工具与角色，后者管运行时，本文管循环收敛。

总则：五条不可谈判

无外部验收，不上自主环。
无多维预算，不上生产流量。
无 Trace，不排障、不复盘、不扩容。
评测只读，优化可写——权限永分家。
能单环解决，不引入多 Agent。

一、任务卡与拓扑选型规范

1.1 任务卡必填字段（团队模板）

字段	要求
goal	一句话，无形容词堆砌
acceptance	可脚本化；附命令
fatal_conditions	列表
budget	steps/tokens/wall/cost/danger_tools
topology	枚举 + 一句话理由
tool_allow / deny	显式
human_gates	哪些步骤必须人批
owner	on-call 归属

缺失字段的任务，CI 应拒绝启动 Agent Job。

1.2 拓扑决策树

二、预算与限幅

维度	建议默认（可按产品调）	超限动作
steps	8–20	失败停止 + 告警
tokens	按模型定价折算日预算	降级小模型或停止
wall clock	2–10 分钟交互；批处理另议	取消工具
danger tools	0–2 次/任务	强制人审
replan	≤2	人审
reflect	≤2	接受当前最佳或失败

冷却：同一 goal_hash 在 N 分钟内失败超过 K 次，进入冷却，防止用户狂点「再试」。

三、Observation 与上下文卫生

3.1 压缩策略

内容类型	策略
测试日志	保留失败块 + 末尾摘要
HTML/DOM	抽文本与关键 selector
截图描述	限长；重复哈希熔断
搜索结果	Top-k 标题+snippet
代码文件	按需切片，禁止全仓倾倒

3.2 每 K 步折叠

保留：原始目标、约束、当前计划、未解决问题列表。丢弃：中间寒暄、重复工具成功回执。

四、停止条件优先级（全局统一）

实现必须按固定顺序裁决，禁止各业务自定义互相矛盾的顺序：

acceptance 成功
fatal / 权限拒绝
fingerprint / plan_oscillation / handoff_cycle
metric_gaming
budget_*
（可选）human_abort

单测锁定该顺序。变更需 RFC。

五、安全与合规

实践	说明
最小工具集	按任务动态挂载，不默认全家桶
路径白名单	写工具默认不可越狱
密钥	工具侧注入，不进 Prompt
PII	Trace 脱敏；记忆写回二次脱敏
人审点	支付、对外发送、删生产数据
审计	谁在何时以何预算启动环

六、多 Agent 生产约束

默认流水线或主管–工人；禁止自由讨论拓扑。
全局预算池 + 子配额；子 Agent 耗尽不得偷全局。
handoff 无工件 → 拒绝。
同对角色短时互传过多 → L08 停止。
Reviewer 不可拥有「改测试」权限。

七、评测与优化

实践	原因
确定性评测优先	抗刷分
金标版本化	可复现
优化器看不到金标原文	防泄漏
双指标	代理分 + 业务分
平台期早停	省钱
定期人工抽检	校正 Judge 漂移

八、可观测与告警

8.1 黄金信号

成功率（按任务类型）
cost_per_success
stop_reason 分布
steps/tokens P95
L02/L05/L08 计数

8.2 告警示例

条件	级别
L05 假完成率过高	P1
日费用超预算	P1
fingerprint 激增	P2
审批队列等待过久	P2

九、发布与灰度

仿真回归绿。
影子模式：环跑但不落副作用（或只写暂存）。
小流量灰度，盯 cost_per_success。
全量；保留一键切回开环或人工。

禁止：临休假前首次全量高风险 Loop。

十、反模式完整表（团队海报级）

反模式	看起来像	实际伤害	纠正
续聊推进	很勤奋	空转烧钱	空回合熔断
加轮数提质	简单	振荡或中毒	改拓扑或评测
多 Agent 装逼	架构炫	传球环	单环加强工具
模型验收	省事	假完成	外部脚本
全家桶工具	万能	选错加越权	动态挂载
记忆无门禁	个性化	污染	WriteBackGate
无 Trace 上线	快	不可运维	阻断发布
CI 无限 Agent	自动化	账单爆炸	org cap
改测试变绿	高分	诚信崩溃	权限分离
Prompt 当状态机	灵活	不可测	显式状态

十一、代码评审关注点（Loop PR）

Reviewer 提问清单：

停止顺序是否被改？单测呢？
新工具是只读还是副作用？并行策略？
Observation 最大长度？
失败模式 ID 是否新增文档？
预算默认是否写在配置中心？
是否增加人审点或误删人审点？

十二、事件复盘模板

标题：日期 Loop 事故
影响：任务类型 / 花费 / 用户数
stop_reason 与失败模式 ID：
Trace 链接：
根因（5 Whys）：
为何检测未拦住：
短期缓解：
长期修复（拓扑/预算/权限/评测）：
跟进行：

复盘输出必须改检查单或单测，否则算无效复盘。

十三、与控制隐喻的健康用法

允许在设计评审说：「我们在积分饱和」= 重试计数顶满却仍加力。
禁止在工单写：「把 Kp 调到 1.2 修复 Agent」。
健康映射表：

隐喻	Agent 含义
饱和	预算或限流触顶
延迟	工具 P99 与上下文膨胀
噪声	无关键 Observation
振荡	计划或策略来回翻
开环	无验收反馈

十四、落地 30 天计划

周	目标
1	统一任务卡 + Stop 顺序单测
2	Trace schema 上线 + 仪表盘
3	影子模式跑三大核心任务
4	灰度 + 复盘一次演练

完成后团队才算「有 Loop Engineering」，而不是「会调几句 Prompt」。更多疑难见 FAQ；学习路径见从零到一。

十五、配置即代码

预算、工具白名单、人审点、拓扑枚举应进 Git，走 PR。推荐结构：

configs/loops/
  task_types.yaml
  stop_policy.yaml
  tool_profiles.yaml

运行时只读这些文件；紧急热修走 Feature Flag，并在 24h 内回写 Git。

十六、SLA 与用户体验

对终端用户暴露的不是「Agent 很智能」，而是：

预计最长等待（由 wall budget 推导）
当前步骤可读摘要（来自 Trace）
失败时的可操作下一步（重试 / 改目标 / 转人工）

隐藏内部失败模式编号给用户，但工单系统必须保留编号。交互式产品建议：步数进度条 + 「停止」按钮映射 human_abort。

十七、团队角色分工

角色	Loop 相关职责
Agent 平台工程师	Runtime、StopJudge、Trace schema
应用开发	任务卡、验收脚本、工具白名单
SRE / 平台	费用帽、告警、沙箱容量
安全	人审策略、脱敏、红队
产品	用户可见进度与失败文案
值班	按失败模式 ID 处置 runbook

缺少平台工程师时，应用组容易把 Prompt 当架构——用本检查单做门禁，比加人更先见效。

十八、Runbook 片段（可直接粘贴）

fingerprint_loop（L02）

打开 Trace，确认重复的 tool+args。
若业务需要探索：提高 limit 或对 args 做规范化豁免字段。
若属死磕：引导用户改目标或切换 Plan–Execute。
记录是否 Observation 未提示「已尝试」。

acceptance_miss_but_model_done（L05）

核对验收命令与环境变量。
确认 StopJudge 未把 assistant 文本当成功。
补单测：伪造「已完成」文本，期望继续或失败而非成功。

十九、度量驱动的迭代节奏

双周迭代只允许动三类旋钮之一为主：拓扑、评测、工具描述。禁止「本迭代同时加 Agent、加轮数、换模型」的大爆炸。每次变更必须带假设：我们相信改 X 会使 cost_per_success 下降 Y%，用看板证伪。

总则：五条不可谈判​

一、任务卡与拓扑选型规范​

1.1 任务卡必填字段（团队模板）​

1.2 拓扑决策树​

二、预算与限幅​

三、Observation 与上下文卫生​

3.1 压缩策略​

3.2 每 K 步折叠​

四、停止条件优先级（全局统一）​

五、安全与合规​

六、多 Agent 生产约束​

七、评测与优化​

八、可观测与告警​

8.1 黄金信号​

8.2 告警示例​

九、发布与灰度​

十、反模式完整表（团队海报级）​

十一、代码评审关注点（Loop PR）​

十二、事件复盘模板​

十三、与控制隐喻的健康用法​

十四、落地 30 天计划​

十五、配置即代码​

十六、SLA 与用户体验​

十七、团队角色分工​

十八、Runbook 片段（可直接粘贴）​

fingerprint_loop（L02）​

acceptance_miss_but_model_done（L05）​

十九、度量驱动的迭代节奏​