Agent 工作流为什么必须先定义输入、输出和 Gate？

多 Agent 系统最容易出现的错觉，是“节点越多越智能”。没有契约时，复杂度只会让错误更难定位。

每一个节点都应该能被检查

一个节点至少要明确接收什么输入、输出什么结构、什么情况下算成功、什么情况下必须阻断。

Gate 的价值不是拖慢系统

Gate 用来阻止高风险结果继续传播。答案冲突、隐私风险、样本不完整等情况不应该被“自动继续”掩盖。

契约让模块可以替换

当上下游只依赖稳定数据结构，而不是依赖某一个具体 Skill、模型或 Agent 时，模块才能升级、替换和回滚。

自动化系统最危险的是错误地成功

显式失败比悄悄把错误结果传给下游更安全。系统应该把不确定性暴露出来，而不是为了“跑完流程”隐藏风险。

输入契约应该写到什么程度

不要只写“输入一份文档”。需要明确字段、允许为空的内容、来源、格式、最大范围和敏感信息边界。输入越模糊，后面越容易用 Prompt 去补一个本该由数据结构解决的问题。

输出契约让下游不依赖某个模型

如果下游只认 JSON 字段、状态码和证据位置，那么上游模型从 A 换成 B 时，只要仍满足契约，整条链路就不必重写。这也是模块化系统能够持续升级的基础。

Gate 需要记录“为什么没过”

只返回 PASS / FAIL 还不够。最好同时记录失败类型、证据、建议回退节点和是否可人工接管。这样失败样本才能进入下一轮测试，而不是成为一次性异常。

建议把每个 Agent 节点写成一张“契约卡”

一张契约卡至少包含：节点名称、输入字段、允许缺失项、输出结构、证据来源、成功条件、失败类型、回退节点、是否需要人工确认、日志里必须保留什么。这样做看起来比直接写 Prompt 慢，但它会显著降低后期维护成本。因为当模型变化、Skill 被替换或上下游调整时，团队不需要重新猜这个节点原来为什么存在，只要检查新模块是否仍满足契约。复杂工作流真正可维护的核心，不是节点数量，而是契约是否清楚。

格物的方法始终从真实问题开始：先看清，再结构化，再进入使用。