契约与闸门打架该改谁？用 AI 智能体 preflight 把配置漂移挡在发版前------以舞台工艺审图专家包闸门冲突为例
一、背景痛点：发版前夜的配置"隐形炸弹"
在舞台工艺审图专家包的迭代里，我们踩过最痛的一类坑不是算法错了，而是配置漂移：同一份事实，在"硬编码闸门"和"权威契约"两个地方各说各话。闸门是脚本里写死的检查规则，契约是专家包对外承诺的规范文档，两者本该同义，但版本一多就各执一词。
这类问题有个共同特征------平时风平浪静，直到发版前的终核（final gate）才集中爆发。配置漂移在终核才爆，等于把 bug 养到上线前夜，留给修复的窗口被压缩到几小时，还往往连着市场包、缓存双副本一起改，风险成倍放大。
二、核心问题：两个权威源打架，到底改谁
当闸门报错说"你不符合我"，而数据其实符合契约时，真正的工程问题是：谁才是权威？
我们的判定原则只有一条------权威契约是唯一权威，闸门只是契约的执行者。闸门为了省事把规则写硬，一旦与契约语义冲突，错的一定是闸门，不是数据。
有人会想"改数据迁就闸门更快"，但这正是工程纪律的陷阱。改数据等于让事实向错误断言低头，下次换版本同样的漂移会换个编号再来一遍。改闸门不迁就数据，是工程纪律的底线。
三、实证：一次终核期爆发的 2 ERROR 事件
某城市交响音乐厅舞台工艺三专业（机械/灯光/音响）重审项目中，终核闸门 lead_gate 首跑直接报 2 个 ERROR，发版被迫卡停。
根因有两处，都是典型的"闸门 vs 契约"漂移：
- R20 落位冲突：闸门硬编码"审核工作记录.md 移入 08 目录"，但《模板调用契约》Class 6 权威定义写的是"md+docx 同落 04 目录"。闸门抄了一条旧规则，契约早已更新，两者打架。
- R34 四表非 6 列：闸门断言四张汇总表必须是 6 列，可实际是 4 列。问题不在于表错了，而在于闸门的列数假设与权威契约对表格结构的约定不一致。
值得注意，这类矛盾靠单点断言完全发现不了------闸门自认正确，数据自认合规，只有把两者摆到一起互校，冲突才显性化。
四、解法：改闸门不迁就数据
处置原则一句话：改闸门不迁就数据。
具体动作有三步：
- 修正
template_position_gate.py与lead_gate.py共 4 处硬编码逻辑，让闸门对齐 Class 6 契约的"04 目录"权威定义，并去掉对 6 列的强假设。 - 同步改市场包＋缓存双副本------只改主副本会留下影子漂移，下次从缓存加载又炸。
- 将那 4 张表重塑为 6 列，docx 重生成，让数据与契约真正同构。
修复后复跑，lead_gate 的 2 个 ERROR 清零。关键在于：我们没有动一行"权威契约认为正确"的数据语义，只让闸门回归契约。
五、流程与代码：把互校搬进 preflight
根因清楚了，但治标还要治本。我们给发版八步加了一道 preflight（出厂前体检）：在终核之前，先让"硬编码闸门"和"权威契约"两个权威源互相校验，任何语义冲突在 preflight 期就亮红灯。
python
# preflight：两权威源互校，拦截配置漂移
def preflight(gate_rules: dict, contract: dict) -> list:
"""
gate_rules: 硬编码闸门抽取出的规则（如目录落位、列数假设）
contract: 权威契约解析出的定义（如 Class 6 的 04 目录、6 列约定）
返回 drifts: 配置漂移清单
"""
drifts = []
# 目录落位互校：闸门说 08，契约说 04 → 漂移
if gate_rules.get("md_dir") != contract.get("md_dir"):
drifts.append({
"code": "R20",
"gate": gate_rules["md_dir"],
"contract": contract["md_dir"],
"fix": "改闸门对齐权威契约"
})
# 表格列数互校
if gate_rules.get("table_cols") != contract.get("table_cols"):
drifts.append({
"code": "R34",
"gate": gate_rules["table_cols"],
"contract": contract["table_cols"],
"fix": "改闸门假设 / 重塑表结构对齐契约"
})
return drifts
# 发版八步中，preflight 早于终核
drifts = preflight(extract_gate_rules(), parse_contract())
assert not drifts, f"配置漂移未清：{drifts}" # 有漂移则发版闸门不放行这套脚本的本质，是让 AI 智能体检查 在发版前自动跑通"两源互校"。两个权威源互校，比任何单点断言都可靠------单点断言只会自我证实，互校才会暴露矛盾。
六、结论：preflight 是出厂前体检
回到开头那个问题：契约与闸门打架时改谁？答案是唯一的------改闸门，对齐权威契约，绝不迁就数据。
更进一步的工程结论是：配置漂移应在发版八步的 preflight 期拦截，而非终核期爆发。 把"两源互校"前置到 preflight，等于在出厂前给发版做一次体检，让 R20、R34 这类冲突在写代码的当天就被看见，而不是养到上线前夜。
preflight 不是锦上添花，是给发版装一道出厂前体检。 当 AI 工程里的专家包开始多版本、多副本并行，靠人肉对齐闸门与契约终会失守；把互校固化成脚本、固化进发版流程，才是配置漂移的真正解药。