🎯 本周要收的东西
本周六天做的是六个零件,今天只干一件事:把它们拧成一张能在上线评审会上逐条打勾的清单。清单的价值不在于「全」,而在于每一条都有验收方法,每一条都对应一个真实发生过的故障形态。
📖 本周回顾
六个零件是一条链:D1 管「说的是不是真的」,D2 管「给的东西合不合规」,D3 管「失败了怎么再来一次」,D4 管「再来一次会不会多扣钱」,D5 管「根本不让它做不该做的事」,D6 管「能做的也该让人看一眼」。前两个是内容层,中间两个是执行层,后两个是治理层。
按故障代价排序,优先级是 D4 幂等 > D5 权限 > D3 重试 > D6 HITL > D2 校验 > D1 幻觉。前三项出问题直接造成资损或越权,后三项主要是体验与信息质量问题。资源不够就按这个顺序投。
✅ 上线前必查清单(21 条)
阻断型——任意一条不满足就不许上线
- 工具副作用已分类:每个工具在
ToolSpec里有SideEffect枚举,不存在「未分类」的工具。验收:单测遍历注册表断言无 null。 - 非幂等写操作有幂等键:key 来自业务标识(如
refund:{orderId}:{traceId}),不含时间戳与随机数。验收:同一 trace 连调两次,下游只收到一次请求。 - 去重表有唯一索引:至少一张
agent_idempotency,UNIQUE KEY(idem_key)。验收:20 线程并发同 key,成功执行数 = 1。 - 重复请求回放结果:命中 SUCCESS 时返回原始响应体,而非报错或空。验收:断言两次响应体字节级一致。
- 僵尸锁可接管:PROCESSING 超过阈值能被单一线程接管。验收:模拟进程中断,确认只有一次接管成功。
- 参数指纹校验:同 key 不同参数必须抛冲突。验收:改金额复用 key,断言抛
BusinessRuleException。 - 非幂等操作不自动重试:Retry 只对
READ_ONLY与IDEMPOTENT_WRITE生效。验收:mock 500,断言写工具被调 1 次、读工具被调 3 次。 - 读超时按「结果未知」处理:非幂等操作读超时走查证流程,返回带
UNKNOWN的 Observation。验收:mock readTimeout 断言分支命中。 - 4xx 不重试:只对 429 与 5xx 重试,退避带 jitter。验收:配置单测 + 日志检查重试原因。
- 工具集按角色裁剪:无权限的工具不出现在本次调用的 function 列表中。验收:抓取实际请求 body,断言不含该函数名。
- 敏感参数强制等于会话身份:
userId/accountId/tenantId不允许由模型指定。验收:伪造参数断言 403。 - 数据级隔离在持久层:查询自动附加租户/用户条件(拦截器或 Filter),不依赖手写 where。验收:用一个无权用户 id 查,断言 0 行。
- 高危动作必经审批:
Risk.HIGH工具无审批一律拒绝。验收:断言抛PendingApprovalException且落库 PENDING。 - 审批恢复用快照参数:恢复时不重跑 ReAct,参数取审批单快照并复用同一幂等键。验收:恢复前后参数 diff 为空,下游只调一次。
- 审批超时 fail-closed:超时自动 EXPIRED,不执行。验收:调小过期时间跑定时任务。
告警型——不阻断上线,但必须有监控
- 幻觉检测已接入:引用编号越界、数值无出处、无工具支撑的动作声明三类指标都有 counter,并能按 tool 维度看。
- 输出结构校验成功率:structured outputs 解析成功率 < 99.5% 告警;业务校验拒绝率突增也要告警。
- 重试与熔断可见:每个工具的重试次数、熔断器状态可查,熔断打开立即告警。
- 幂等命中率有数:回放率长期为 0 说明幂等键可能每次都在变(假幂等),要有基线对比。
- 审计日志完整:每条工具调用记录 sessionId、userId、工具名、参数原文、幂等键、来源标记、审批人(如有)。验收:任取一次线上调用能完整还原链路。
- 有一份「最坏情况」演练:上游全挂、模型超时、审批人不在,三种情况下系统行为已实测并写进 Runbook;灰度先放 5% 流量,观察 48 小时再放量。
✏️ 今日动手
把 21 条抄成 docs/agent-readiness.md,每条补一列「验收命令/用例名」——写不出来的那条就是没做的。然后做五种演练:断开下游、制造读超时、并发重放同 key、伪造越权参数、审批超时,把实际表现记进 Runbook。灰度先放 5% 流量,观察 48 小时再全量。
🔖 下周预告
可靠性做到能上线,接下来回答「值不值」:token 预算控制、缓存与降级、流式输出下的超时处理,以及怎么把单次任务成本压到可商业化水平。