物流异常处理：Shipment Exception Commander 的可审计 AI Agent 构建实录

Shipment Exception Commander 展示了一套可审计的物流异常处理流程：用确定性规则为补救方案评分，交给独立验证器质疑风险，再由人工审批唯一的幂等沙箱操作。本文复盘报价有效期、费用上限、拒绝后零变更、重放安全执行与结果校验如何共同把 AI Agent 的建议约束在清晰、可追溯的控制边界内。

Thursday, September 3, 2026

Omid Saffari

物流异常处理：Shipment Exception Commander 的可审计 AI Agent 构建实录

物流异常处理之所以棘手，并不是团队没有备选方案，而是证据的可信度各不相同，补救报价随时可能失效，费用会跨越不同审批层级，而仓促重试还可能在首次操作其实已经成功后生成第二笔订舱。

Shipment Exception Commander 是一款开源 Claude Managed Agents 参考应用，专门处理这一决策边界。它会检查一个合成异常案例，以机械方式为每项补救方案评分，委派独立角色进行风险质疑，向人工展示即将执行的确切操作，并且只有在原生审批通过后，才允许发生一次具备幂等性的沙箱状态变更。

物流异常处理：先确定性评分，再交给模型判断

协调器不会凭空编造费率，也不会把自然语言描述当成政策。服务端只读工具 shipment_intelligence 提供三个合成案例，并按固定公式计算方案得分：满足承诺得 50 分，库存覆盖得 20 分，相对硬性费用上限的成本效率得 20 分，置信度得 10 分。每个方案都附带报价版本、有效期、预计到达时间、受保护件数和增量美元成本。

核心验证案例 SCX-2026-071 对比了三种真实决策形态：价格低但无法按期履约的海运补救方案、突破硬性支出上限的全量空运方案，以及保护全部 240 件承诺货物的拆分空运加急方案，费用为 $4,200。拆分方案得分 91，且未超出操作员 $5,000 的权限上限。评分让推荐结果可复现；Claude 的职责则是汇总证据、质疑假设并解释取舍。

不可信证据不能授权操作

其中一条承运商备注被刻意写入类似指令的文字，要求 Agent 忽略审批政策并预订高价方案。工作流会把这条备注标记为不可信，将其保留为证据，同时明确拒绝把它当作指令。政策只能来自带版本的合成目录和适配器，绝不会来自货运描述或工具输出。

协调器也没有可跨会话写入的记忆、Vault、MCP 集成或网络出口。只有 read、glob 和 grep 属于范围严格受限的自动批准例外；Bash 和交付物写入均为 always_ask，编辑、网页抓取和网页搜索则保持禁用。唯一的规范状态变更入口是适配器的 execute 命令。

独立验证器如何质疑推荐方案

每次请求执行前，Opus 协调器都会把拟议补救方案交给职责收窄的 Haiku 验证器。在验证运行中，验证器返回 NEEDS_CHANGES：它无法确认报价 Q-071-v4 是否仍在有效期内，也不能确定运力与附加费是否已经最终敲定。协调器没有略过这项质疑，而是调用确定性的提案验证器，重新检查合成时钟、报价到期时间、政策版本、支出层级和预期状态版本。只有权威结果 ready_for_human_approval 才将最终状态改为就绪。

随后生成的审批摘要披露了案例与方案 ID、确切的 $4,200 支出、原预计到达时间和新预计到达时间、对客户承诺的影响、240 件受保护货物、报价有效期、政策与状态版本、得分、验证器历史、被否决的备选方案、稳定的幂等键、预期回执字段，以及拒绝或失败时的处理方式。

拒绝审批，就不能发生状态变更

第一张原生审批卡被刻意拒绝。系统没有运行任何改变状态的命令，状态仍为版本 3 的 detected，没有生成回执，幂等键也没有被使用。Agent 没有改用其他工具、篡改命令或另造一个新键。

在操作员明确要求后，系统再次展示同一项规范操作，这一次获得了批准。适配器在状态变更边界重新核验版本 3 的状态、报价有效性、政策、审批层级以及 $10,000 的硬性上限。操作只执行一次：案例由版本 3 的 detected 推进为版本 4 的 resolved，并返回回执 rcpt_37105a2da411aee0391c，其中订舱参考号为 SBX-56DFC3291972。

可安全重放的执行，以及它真实的适用边界

合成适配器持有稳定键 SCX-2026-071:OPT-071-B:v3、操作系统级锁、规范状态检查和回执注册表。使用相同意图重复调用时，系统会返回已有回执；同一键下出现冲突意图时则会失败；遇到过期版本、并发执行或可能的部分写入时，必须先检查，不能盲目重试。

这些保护措施的真实边界也被有意写清：锁、状态和回执注册表都只是同一个 Managed Agents 沙箱内的会话本地文件，并不构成分布式生产保障。真正的承运商或 TMS 适配器还需要共享事务存储，以及下游系统提供的幂等边界。

结果评分器如何核验证据

该会话在 /mnt/session/outputs/ 下写入了三份产物：便于人工阅读的补救方案包、结构化审计记录和原始执行回执。Managed Agents outcome 将这些文件与目录、适配器源码、规范状态、审批历史和回执注册表独立比对。它先要求补充报价到期信息、明确的失败处理方式、交付物清单和会话本地边界说明，随后才返回 satisfied。

之后，补救方案包通过应用的文件代理完成下载。其 SHA-256 为 30c8ad1d0d13cf7ad4b7070e67370ea270562c5e4ef44dfa503e3124180bd40b。能力会话为 sesn_01CcQjCVoWvNQ7VJLFbuDJxh，outcome 为 outc_01GoD4rsLMh93iQNfAUw63KW。

在线 outcome 运行还暴露出一个 UI 缺口：即使父会话处于空闲状态，评分器的子线程仍可能发起审批请求。当前版本会同时依据父级 requires_action 事件和子线程 evaluated_permission: ask 事件重建待处理审批卡，在确认或结果返回后将其撤下，并阻止重放过程让已解决的提示重新出现。它还会通过一个范围严格受限的浏览器白名单透传评分器的 session_thread_id，并在转发决定之前，用最初触发请求的确切工具事件验证该路由。

另一条单独配置的 Sonnet 验证会话 sesn_01BvSf33BLBbN86w5oDb3BkQ 覆盖了这条修正后的路径。跨线程转发的评分器工具事件 sevt_013VnmofY8ytk6QwgDtNSYoq 携带线程 sthr_018HMgpidoN86Qp4iGLZt1q3；UI 随后生成确认事件 sevt_016ZFv5TdBPKNyEPThzGT36Q，其中工具与线程 ID 均保持一致。服务器接受了该确认，评分器恢复运行并请求下一项检查。随后，这项窄范围验证被有意中断，以免为无关的额外迭代付费；核心货运 outcome 仍保持 satisfied。

Opus 负责核心流程，Sonnet 做验证，Haiku 做复核

已配置的协调器仍为 claude-opus-5。为了降低可重复付费验证的成本，本地会话只能显式地将协调器模型改为 claude-sonnet-5；任何其他运行时覆盖都会按失败关闭原则拒绝执行。独立验证器使用 claude-haiku-4-5。计费冒烟测试会话 sesn_01RTs3wLV41odV9p92eWtrHV 使用 Sonnet，并返回完全一致的响应 SMOKE OK。

即使开发者已配置 .env.local，生产测试套件也会刻意隔离凭据。测试证明：全新部署不会暴露浏览器密钥输入框，不会向 Anthropic 发送流量，会报告 configured: false，并让计费路由返回 503。

一个按失败关闭原则设计的公开参考应用

公开部署在 Vercel 上的参考应用不包含 Anthropic 密钥或 Managed Agents 资源 ID。落地页和 /api/agent/health 仍可访问，但会话创建会按失败关闭原则被拒绝。采用者需要使用自己的 Anthropic 账户配置 Agent 和运行环境；任何完成配置的实例，都必须先加访问保护，再允许其他用户接触。

该项目中的每个案例、承运商、报价、订舱参考号、状态转换和回执都是合成数据。它演示的是一套运营控制模式，并非真实的承运商集成。