# 闸门和契约互相甩锅时，我让 WorkBuddy 智能体在发版前自己暴露问题

## 一、发版最后一天，闸门炸了

那天上午，发版流程走到最后一步。WorkBuddy 智能体审图团队的终核闸门 lead_gate 初跑，屏幕上跳出 2 个 ERROR。

那一刻空气有点凝固——整个意见包是 WorkBuddy智能体一晚上加一整天生成出来的，外发审核的截止时间就在眼前，闸门偏偏在最后一步拦路。

先交代背景。这是一个舞台机械／灯光／音响三专业的系统性重审项目：218 页施工交底图，图纸载体是 DWG（AutoCAD 的原生图纸文件格式），WorkBuddy 智能体没法直接"看"矢量图，要先做栅格化（把矢量图渲染成固定像素的图像，相当于把图纸拍照）。审图的方式是逐页栅格目验——AI 智能体读栅格图、发现疑点，再回读文字层（图纸文件里内嵌的、可以选中复制的文字信息层）核实，最后生成审查意见。意见按严重程度分 A/B/C/D 四个等级（A 最重、D 一般），记录在结构化意见表里。

我们团队搭了一套 AI 智能体审图团队：AI 智能体负责读图、目验、意见初稿，python 脚本负责发版闸门。发版流程八步：图纸清单派单 → 栅格目验 → 意见初稿 → 数据文件生成 → 闸门检查 → 意见包组装 → 外发审核 → 归档。lead_gate 是最后一道闸门，检查全部交付物的落位、结构和命名——闸门不过，意见包不能外发。

而这两个 ERROR 是这样的：闸门脚本里硬编码"审核工作记录.md 移入 08"，但《模板调用契约》Class 6 规定 md 与 docx 同落 04。同一类问题还有一处——R34 规定四张表（意见表、清单表、跟踪表、汇总表）都是 6 列，实际列结构与契约不符。

问题来了：数据文件是按契约生成的。要让闸门通过，要么改数据（文件挪回 08、四表重切），要么改闸门（修硬编码）。AI 智能体生成的数据错了吗？没有。是闸门的配置和契约冲突了。

## 二、两难时刻：改数据，还是改闸门？

按常理，数据文件已经生成完了，重做成本高；改闸门脚本不过几行代码，成本最低。团队一开始的讨论方向甚至偏向"改数据迁就闸门"——毕竟数据是 AI 智能体生成的，改起来"机器不心疼"。

但这个方向当天就被否决了。原因很直接：下游环节读的是契约。意见包组装脚本、外发审核脚本，全都按契约的落位和结构读数据。如果把文件挪回 08 去迁就闸门的硬编码，组装脚本立刻找不到文件——等于把问题从"闸门一处 ERROR"放大成"下游全线断流"。

这就是闸门和契约冲突时的核心原则：**改闸门、不迁就数据**。契约是业务语义基准，所有下游环节都按它运行；闸门只是执行工具，工具的配置错了就改工具。数据不欠工具的债，工具欠数据的适配。

这个原则还有一层更深的含义。这次冲突里，AI 智能体生成的数据完全正确——218 页逐页目验、19 条意见、A/B/C/D 分级，全部符合契约。冲突的根不在数据侧，在配置侧。如果每次发版都靠"改数据迁就闸门"蒙混过关，那等于给闸门的硬编码错误长期续命，下次契约再演进，同样的 ERROR 还会复发。

## 三、复盘：为什么闸门和契约会"打架"

当天完成修正后，团队做了复盘。冲突的三个根因，现在看得很清楚：

**根因一：两个权威源，没有一个统一基准。** 业务语义的权威存在两处：契约文档（人可读，业务标准）和闸门脚本里的硬编码规则（机器可读，执行配置）。两处一致时相安无事；一旦分叉，该改谁没有决策机制，全靠人当场拍脑袋。这次就是拍脑袋拍出了"改数据"的弯路。

**根因二：契约演进了，闸门没跟上。** 契约 Class 6"md+docx 同落"是后来明确细化的条款，闸门脚本里的落位硬编码没同步更新。漂移是结构性的：契约每改一次，闸门不手动同步就产生一处漂移点。这不是"谁写错了"，是机制缺失——没有自动互校，漂移只能靠终核闸门"炸"出来。

**根因三：检测时机太晚。** lead_gate 是八步里的最后一步。同一处漂移，在第四步（数据文件生成）之前发现，代价是几行代码；在第八步发现，代价是全部数据返工。当天这处漂移吃掉了发版最后阶段的大量精力，还差点误了外发审核。

这三条归结成一句话：配置漂移是必然的，但爆发时机是可控的。我们要做的，是把检测时机从第八步前移到第四步之前——在数据生成之前，让 AI 智能体先做一次闸门与契约的互校。

## 四、方案：给发版八步插一个 preflight 环节

方案一句话：新增 preflight 环节，让 AI 智能体在数据文件生成之前，先做闸门与契约的互校，把配置漂移挡在发版前段。

改造后的发版八步：

1. 图纸清单派单
2. 栅格目验（AI 智能体读图）
3. 意见初稿生成
4. **preflight（新增）：闸门与契约互校**
5. 数据文件生成
6. 闸门检查（lead_gate 等）
7. 意见包组装
8. 外发审核与归档

preflight 做四件事：

- 契约条款解析：把人可读的契约条款转成结构化规则集，含规则编号、适用范围、比较维度、基准值；
- 闸门源码扫描：把闸门脚本（双副本）里的硬编码常量和规则表达提取出来；
- 逐维比对：按落位、列结构、等级、命名四个维度逐一比对；
- 输出漂移清单：ERROR 级漂移直接阻断发版；每条漂移记录带来源归属，明确是闸门侧还是契约侧。

四个比较维度的设计思路：

- **落位**：交付物该落哪个目录。契约说 04、闸门硬编码 08，即漂移——这次冲突的直接来源；
- **列结构**：意见表等应为 6 列。R34 那处四表列结构不符就是这维度抓出来的；
- **等级**：A/B/C/D 四个等级与意见级别的映射关系，契约与闸门是否一致；
- **命名**：文件命名规范在契约与闸门检查中是否一致。

这套设计与行业里 WH/T 参数锚库的思路是同构的：行业把关键参数固化成锚库，防止"每个人手里一份参数、版本各不一样"；preflight 让契约充当"基准值"，闸门硬编码充当"实测值"，在发版前完成一致性校验。逻辑相同，载体不同。

## 五、工程实现：preflight 的 python 骨架

实现用 python，分四个模块：契约规则解析、闸门硬编码扫描、互校比对、双副本同步修正。下面是实际实现的简化版，可直接复制改路径运行。

**契约条款解析**——把《模板调用契约》转成结构化规则：

```python
# contract_rules.py — 契约条款结构化解析
import re
from dataclasses import dataclass

@dataclass
class ContractRule:
    rule_id: str      # 规则编号，如 R20 / R34
    scope: str        # 适用范围，如 Class 6 模板
    dimension: str    # 比较维度：position / columns / grade / naming
    expect: str       # 基准值，如落位目录 "04"
    raw: str          # 原始条款文本，便于追溯

def parse_contract(path: str) -> list[ContractRule]:
    rules = []
    with open(path, encoding="utf-8") as f:
        for line in f:
            m = re.search(r"R(\d+)\s*[\[【]?(.+?)[\]】]?\s*[：:]\s*(.+)", line)
            if not m:
                continue
            rid, scope, body = m.group(1), m.group(2), m.group(3)
            rules.append(ContractRule(
                rule_id=f"R{rid}", scope=scope,
                dimension=_guess_dim(body), expect=_expect(body),
                raw=line.strip()))
    return rules

def _guess_dim(body: str) -> str:
    if "列" in body:
        return "columns"
    if any(k in body for k in ("落", "移", "存")):
        return "position"
    if "等级" in body or "ABCD" in body.upper():
        return "grade"
    return "naming"

def _expect(body: str) -> str:
    nums = re.findall(r"\d{2}", body)   # 两位数字，如落位目录 "04" / "08"
    return nums[0] if nums else body.strip()
```

**preflight 主流程**——互校比对 + 阻断发版：

```python
# preflight.py — 闸门与契约互校，检测配置漂移
from contract_rules import parse_contract
import ast, pathlib

def scan_gates(gate_files: list[str]) -> list[dict]:
    found = []
    for fp in gate_files:
        tree = ast.parse(pathlib.Path(fp).read_text(encoding="utf-8"))
        for node in ast.walk(tree):
            # 捕获含路径 / 落位关键字的字符串常量
            if isinstance(node, ast.Constant) and isinstance(node.value, str):
                if any(k in node.value for k in ("04", "08", ".md", ".docx")):
                    found.append({"file": fp, "line": node.lineno,
                                  "value": node.value})
    return found

def preflight(contract_path: str, gate_files: list[str]) -> list[dict]:
    rules = parse_contract(contract_path)
    hardcoded = scan_gates(gate_files)
    drifts = []
    for r in rules:
        if r.dimension == "position":
            for h in hardcoded:
                if r.expect not in h["value"]:
                    drifts.append({
                        "rule_id": r.rule_id,
                        "dimension": "position",
                        "contract_expect": f"落位 {r.expect}",
                        "gate_hardcoded": h["value"],
                        "gate_file": h["file"],
                        "gate_line": h["line"],
                        "attribution": "闸门侧",   # 来源归属
                        "level": "ERROR",
                    })
    return drifts

if __name__ == "__main__":
    drifts = preflight("template_contract.md",
                       ["template_position_gate.py", "lead_gate.py"])
    for d in drifts:
        print(f"[{d['level']}] {d['rule_id']} {d['dimension']}: "
              f"契约={d['contract_expect']} "
              f"闸门={d['gate_hardcoded']} @{d['gate_file']}:{d['gate_line']}")
    raise SystemExit(1 if drifts else 0)   # 有漂移 → 阻断发版
```

用这套 preflight 跑这个项目，输出的就是 R20 那处漂移记录：契约=落位 04，闸门=审核工作记录.md 移入 08。

**结构检查断言**——R34 的列结构漂移不能靠常量扫描发现，需要结构检查：

```python
# 断言示例：意见表必须为 6 列（R34）
def assert_table_columns(table_md: str, rule_id: str = "R34"):
    header = table_md.splitlines()[0]
    cols = header.count("|") - 1
    assert cols == 6, \
        f"{rule_id} 违规：意见表应为 6 列，实际检测到 {cols} 列"
```

**双副本同步修正**——改闸门后，两个副本必须同步：

```bash
# 修正闸门：R20 落位 2 处 + R34 列检查 2 处，同步到双副本
cp template_position_gate.py market_pkg/tools/
cp template_position_gate.py cache/tools/
cp lead_gate.py          market_pkg/tools/
cp lead_gate.py          cache/tools/

# 重跑 preflight 验证（双副本同时扫描）
python preflight.py --contract template_contract.md \
  --gates market_pkg/tools/*.py cache/tools/*.py

# 四表重塑 + docx 重生成（数据按契约基准走，不迁就闸门）
python reshape_tables.py --contract template_contract.md
python rebuild_docx.py
```

## 六、踩坑实录：四个差点翻车的瞬间

**坑 1：只改了一个副本，第二天 ERROR 复发。** 现象：修正后 preflight 全绿，第二天发版 lead_gate 又报 ERROR。成因：闸门脚本存在双副本——市场包（对外交付用）和缓存（执行用），当时只改了市场包，漏了缓存。解法：preflight 同时扫描双副本，修正步骤显式做双副本同步。后来我们把"双副本一致性"写进了 preflight 的检查清单本身，让它永远不再漏。

**坑 2：第一反应是"改数据迁就闸门"，下游立刻炸。** 现象：把文件挪回 08 后，意见包组装脚本立刻报缺文件。成因：下游环节读的是契约，不是闸门。解法：原则决策——改闸门、不迁就数据。这个坑说明：闸门与契约冲突时，人的第一反应往往是"改数据适配闸门"，但正确方向永远是"改闸门适配业务基准"。

**坑 3：preflight v0 只查齐套性，没查结构。** 现象：preflight v0 只检查"文件存在"，四张表的列结构漂移（R34）顺利通过 preflight，在终核闸门才炸。成因：齐套性检查只是第一层，preflight 必须同时查"结构是否符合契约"。解法：preflight 增加结构检查——断言校验列数、表头、落位等结构字段。齐套性告诉你"文件在"，结构告诉你"文件对"，preflight 两层都要有。

**坑 4：漂移报告不带归属，三个人吵了半天。** 现象：检测到漂移，但报告只说"闸门与契约冲突"，三个人为"是闸门的问题还是契约的问题"争论半天。成因：漂移记录缺少来源归属字段。解法：每条漂移记录带归属字段（闸门侧／契约侧），同时给出契约基准值与闸门实测值。提前归属，让修正责任一步到位，不用再开对齐会。

## 七、验证与结论：preflight 上线后的效果

preflight 机制落地后，效果是直接的：

- 这次项目的两个漂移点（R20 落位、R34 列结构）全部在 preflight 阶段暴露，没有拖到终核闸门；
- 双副本同步修正后，后续发版 preflight 全绿，lead_gate 的 ERROR 清零；
- 当天的重审返工（4 处修正＋双副本同步＋四表重塑＋docx 重生成）在当日完成，外发审核按时进行，没有延误。

三条结论，也是这次实战沉淀下来的方法论：

1. **配置漂移应该在 preflight 拦截，而不是在终核期爆发。** 漂移是必然的，但爆发时机是可控的——检测前移一步，返工代价降一个量级；
2. **闸门与契约冲突时，改闸门、不迁就数据。** 契约是业务语义基准，闸门是执行工具，工具适配基准，而不是反过来；
3. **preflight 是通用机制，不是一次性补丁。** 比较维度（落位／列结构／等级／命名）可插拔，契约条款可结构化，接入 CI/CD 发版流水线后，每次发版漂移自动暴露，不需要人肉盯终核。

最后说回这次项目：某城市交响音乐厅舞台机械／灯光／音响三专业的系统性重审，218 页图纸全量栅格目验，AI 智能体当日生成审查意见初稿、人工复核定稿、外发意见 19 条。引入的 preflight 机制，正是那次重审当日复盘得出的提速措施之一。如果你的团队也有"两个权威源互校"的发版场景——两个配置文件互相打架、AI 智能体生成的数据背锅、问题拖到最后一步才爆——建议在终核闸门之前加一道 preflight 互校。让 AI 智能体在发版前就把问题暴露出来，而不是等到终核闸门爆 ERROR 才发现。


那天上午，发版流程走到最后一步。WorkBuddy 智能体审图团队的终核闸门 lead_gate 初跑，屏幕上跳出 2 个 ERROR。

闸门和契约互相甩锅时，我让 WorkBuddy智能体在发版前自己暴露问题

发版最后一步，AI 智能体审图团队的终核闸门突然报 2 个 ERROR：闸门脚本硬编码的规则与《模板调用契约》互相打架，218 页重审的意见包卡在发版关口。本文复盘这次三专业重审实战：冲突的三个根因、改闸门不迁就数据的原则决策、在发版八步中插入 preflight 环节让 AI 智能体在数据生成前完成闸门与契约互校的完整实现（含可运行的 python 代码）。附 4 个真实踩坑：双副本漏改致 ER

人工智能

在发版流程中，WorkBuddy智能体通过新增preflight环节，在数据生成前自动互校闸门与契约，提前暴露配置漂移（如R20落位、R34列结构问题），避免终核阶段返工。该方法强调“改闸门不迁就数据”，实现双副本同步与CI/CD集成，显著降低返工成本，确保外发审核按时完成。

代码解释

智能体

WorkBuddy 

Python

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

闸门和契约互相甩锅时，我让 WorkBuddy智能体在发版前自己暴露问题-腾讯云开发者社区-腾讯云

闸门和契约互相甩锅时，我让 WorkBuddy智能体在发版前自己暴露问题

闸门和契约互相甩锅时，我让 WorkBuddy智能体在发版前自己暴露问题

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐