先把不客气的话说在前面：设计 Agent 的工作，八成不在「让它变聪明」，而在「让它失败得体面」。聪明的部分模型每天都在替你长，而体面的部分——门控、降级、留痕、停手——只能由设计者亲手做。
我桌上跑着好几套 Agent：一个负责探测渠道、一个负责生图出画、一个跑服务器巡检、一个剪视频但坚持人审。它们性格各异，但踩过同一个坑之后都长成了同一种模样。这篇文章就是把那种模样拆开给你看。
本文所有原则均来自这些系统的真实设计与事故复盘；三枚小样可以在页面上直接玩；文末附件出处清单。
ERRORS FIRST
先设计它出错的样子，再设计它聪明的样子
做 demo 的时候你只需要展示成功路径；做产品的时候，成功路径是模型的事，失败路径才是你的事。
造物手记 · 01演示级的 Agent 与生产级的 Agent，差距不在能力清单上，在三个反直觉的设计习惯上：工具越多不是越强，是爆炸面越大；失败不是异常分支，是主流程的一部分；日志不是调试附属品，是产品功能。
| 维度 | 演示级 | 生产级 |
|---|---|---|
| 工具 | 什么都接，越多越酷 | 分级授权：只读 / 提议 / 执行，写操作过门 |
| 失败 | 弹个红字「出错了」 | 有语义的错误码、有候选的降级链、有条件的停手 |
| 记忆 | 塞进上下文就算记住 | 版本化写入、可回滚、长期记忆与工作记忆分开 |
| 观测 | console.log 打天下 | 时间线轨迹、出站脱敏、成本核算、可回放 |
| 人类 | 出问题才来找你 | 危险动作前有停点，审批留痕，随时可接管 |
一个来自渠道探测 Agent 的真实规矩：「不能黑盒」——每次探测必须有时间线日志（脱敏后的请求头、载荷、错误全文、重试原因、计价过程），前端点开状态徽章就能查。这条规矩立下之后，我排查问题的平均时间从「一个晚上」掉到「一眼」。
接下来的四章，就是这个表格的四行展开。每一章配一枚可以上手玩的小样——它们的背面都写满了我翻过的车。
TOOLS AS PERMISSIONS
工具即权限：把「请不要」从提示词里删掉
教 Agent 自律是个愿望；给 Agent 装一扇门是事实。工具设计的本质是权限设计。
造物手记 · 02我的 Agent 工作台（hermes-agent-workbench）立项时只写了一条硬要求：工具执行必须受控审批、写入必须可回滚。后来所有 Agent 都沿用了这套骨架。核心模式一句话：提议与执行分离——Agent 可以提出任何操作（propose），但「落地」必须过一道服务端门控，而门默认是关的。
- 工具按动作分级
只读随便读；写操作必须提案；删除、对外发送、花钱这类不可逆动作，必须停下来等人。工具列表不是能力清单，是权限矩阵。
- 门控放在服务端，不放在提示词里
不是叮嘱模型「请不要删除」，而是执行删除的函数默认根本不存在于工具集里。提示词是愿望，代码是事实——开天窗的是代码，不是文笔。
- 一切可回滚
写操作走版本化写入：每次落盘先留旧版本，出错一行指令回到上一版。连记忆也是文件，文件也有版本——敢让 Agent 写东西的前提，是它写坏了能撤。
下面这枚小样，就是一个最小可用的门控：Agent 想动七个容器，但它能做到的只是「递交一份提议」。
小样 01 · 审批门控
REQUEST · 提议
GATE · 门控
AUDIT · 审计
- --:--:--等待第一条记录……
门的默认状态：关。Agent 只能提议，不能执行。
# 工具权限表（示意）
tools:
read.containers: auto # 只读：直接给
propose.restart: gated # 写：先提案，等人批
execute.delete: gated + audit # 不可逆：双重门 + 强制留痕
policy:
default: off # 新接入的工具默认关闭
redaction: outbound # 出站请求强制脱敏
rollback: versioned-writes # 写操作留旧版本，一键回滚反面教材是我自己：早期版本把「重启容器」直接做成了工具，Agent 在一个循环里重启了同一个服务十一次——每一次都"成功"。工具的能力边界，就是 Agent 的事故半径。
FAILURE AS MAIN PATH
失败是主流程：错误码、降级链与停手条件
对 Agent 而言，失败不是「如果」，是「每天几点」。设计问题变成三个：怎么分类、怎么切换、什么时候停。
造物手记 · 03- 错误要分类，不要一锅炖
401 / 402 / 403（钥匙与余额问题）→ 立即停，换渠道是掩耳盗铃；超时 / 5xx / 无可用账号 → 降级；429 限流 → 冷却后再来。把错误码当说明书读，而不是当失败读。
- 候选要有顺序和理由
降级链不是随机备胎：按质量优先、成本优先、稳定优先分组排序，每一次切换都写进轨迹——为什么切、切到哪、结果如何，事后能回放。
- 停手是一种功能
连续失败、风控特征（403）、预算超限，都要能自动熔断。"停下来"必须做成系统默认行为，而不是靠操作者的意志力——晚上十一点的你没有白天清醒。
这枚小样把降级链演出来：主渠道被"制造故障"之后，任务应该悄无声息地换一条路走；三条路全断时，它应该利落地停手、冷却、通知人。
小样 02 · 降级链
每按一次，当前渠道"断供"一次——看看任务是怎么走完全程的。
两个真实错误码，教我最多的：「no_available_account」——服务商自己也没货了（上游账号池空）。看到它不要重试，这是自白书不是偶发故障。还有那次风控封 IP：早期图快，60 秒内对一个站点连发 5 个模型，换来一个无自动解除的封禁。现在的探测纪律（同站 ≥15 秒、每分钟 ≤4 次、连续失败自动停手）全是那次事故长出来的。
OBSERVABILITY
看得见，才敢托付
信任不是感觉，是证据。Agent 敢被托付的程度，正比于你能「看见」它做过什么。
造物手记 · 04- 轨迹是一等公民
每一步留痕：请求前的意图、脱敏后的载荷、上游返回的原始错误、重试与降级的原因、收尾时的成本核算。日志不是给开发者调试的福利，是给操作者的界面。
- 出站必须脱敏
日志里出现钥匙、令牌、私人域名——在写下去之前就遮起来。审计要回答「发过什么」，但不需要把秘密再抄一份。脱敏做在出站口，不在查看时。
- 产物要自审，汇报要如实
视觉任务截帧看一眼，数值任务断言跑一遍；「完成」要有收据。Agent 的自述不算证据，diff、截图、断言才算——3dviz-pro-max 的十步工作流里，第八步就是「跑起来、截帧、自审」。
小样三号和前两个不太一样：它不演示某个机制，它演示「你终于能看见发生了什么」。跑一次任务，然后把「脱敏」关掉再跑一次，对比两遍日志。
小样 03 · 日志时间线
时间线从 queued 开始，到成本核算结束——每一步都能回放。
一个验收标准：你不需要问 Agent「刚才到底发生了什么」。如果每次事故都要靠问它、猜它、复现它，说明日志还没做成产品，只是做了个习惯。
HUMAN IN THE LOOP
人类站在哪：停点、工作台与缺席条款
门控的位置，就是人的位置。设计问题不是「要不要人」，而是人怎么被找、什么时候不该被找。
造物手记 · 05- 停点放在「不可逆」和「花大钱」的前面
删除、对外发送、大额消耗 → 必停；查询、读取、本地计算 → 别打扰。审批疲劳是所有门控的头号杀手：一天敲两百次「同意」，第二百零一次你也不会看。
- 给人一座工作台，而不是一个弹窗
剪辑人审工作台是范例：AI 产出候选 → 人在工作台上逐段校正 → 确定性导出。人不是「点确定」的橡皮图章，人是在和 Agent 分工——把判断留给人，把体力留给它。
- 缺席条款：没人应答时，系统要安全地不做
审批门超时 = 拒绝（不是批准），危险动作没人应答就不发生。同理，任何「完成」都要能出示收据；任何「失败」都要原样上报——不美化措辞的汇报，是 Agent 最贵的品格。
所以一个 Agent 的完整样子是：它在门里干活，干不了就降级，降不了就停手；每一步留下轨迹，关键一步抬起头来看人。聪明是模型给的，这套东西是设计给的。
结语：能力靠模型，品格靠系统
这篇文章没有教你让 Agent 更聪明的任何技巧——那样的话术每天都有新鲜的。它想说的是另一半：Agent 设计的本质，是失败治理学。工具是权限，失败是主流程，日志是产品，人是停点。把这四样做扎实，Agent 的能力覆盖能画出多远，你就可以放心让它画多远。
如果你今天就要开始：最小骨架十分钟能搭完——提议 / 审批 / 审计 / 回滚，四件套摆上，再往上加能力。然后你会经历我经历过的所有事故，但它们会以"一条审计记录"而不是"一场灾难"的形式到来。
速查卡 · QUICK REFERENCE
- 工具分三级：只读 / 提议 / 执行；新工具默认关闭
- 门控在服务端，不在提示词里；写入版本化、可回滚
- 错误分类先行：401/402/403 停，超时/5xx 降，429 冷却
- 降级链要排序、要留痕；停手是功能，不是失败
- 出站脱敏；轨迹可回放；产物自审（截帧 / 断言）
- 审批超时＝拒绝；「完成」要有收据，失败不美化
原则出处：hermes-agent-workbench（受控审批 · 可回滚工具执行，开源）· 渠道探测 Agent 的探测纪律与时间线日志 · 图片工坊的候选降级链 · 剪辑人审工作台 · 3dviz-pro-max 十步工作流。本页三枚小样由 Agent 现场编写，等你上手。