最佳实践：生产级 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_cyclemetric_gamingbudget_*- （可选）
human_abort
单测锁定该顺序。变更需 RFC。
五、安全与合规
| 实践 | 说明 |
|---|---|
| 最小工具集 | 按任务动态挂载，不默认全家桶 |
| 路径白名单 | 写工具默认不可越狱 |
| 密钥 | 工具侧注入，不进 Prompt |
| PII | Trace 脱敏；记忆写回二次脱敏 |
| 人审点 | 支付、对外发送、删生产数据 |
| 审计 | 谁在何时以何预算启动环 |
六、多 Agent 生产约束
- 默认流水线或主管–工人；禁止自由讨论拓扑。
- 全局预算池 + 子配额；子 Agent 耗尽不得偷全局。
- handoff 无工件 → 拒绝。
- 同对角色短时互传过多 → L08 停止。
- Reviewer 不可拥有「改测试」权限。
七、评测与优化
| 实践 | 原因 |
|---|---|
| 确定性评测优先 | 抗刷分 |
| 金标版本化 | 可复现 |
| 优化器看不到金标原文 | 防泄漏 |
| 双指标 | 代理分 + 业务分 |
| 平台期早停 | 省钱 |
| 定期人工抽检 | 校正 Judge 漂移 |
八、可观测与告警
8.1 黄金信号
- 成功率（按任务类型）
cost_per_successstop_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%，用看板证伪。