不会还有人改映射不带样例还敢提 PR 吧?假绿一时爽,回归火葬场 | 多引擎适配最小 Rule

31 阅读10分钟

不会还有人改映射不带样例还敢提 PR 吧?假绿一时爽,回归火葬场 | 多引擎适配最小 Rule

全文速览:我第一次写的规则包演练全绿,因为演练根本没碰到红线。这篇用虚构的 acme-adaptor 落地三到五个文件的最小 Rule 包,验收标准只有一条:故意作恶时会被挡。

系列:《从 Rule 到落地:AI 工程化实践》第 6 篇
标签:Rule · 实战 · 适配 · 样例驱动
专栏:从小白到AI落地大师

序言

理论聊了两篇,童鞋们手该痒了。本篇实战:给「多引擎适配」写一套最小 Rule 包。场景全用虚构名 acme-adaptor——把同一套语法描述适配到多种执行引擎。痛点很真实:助手乱改映射表、跳过回归样例、甚至删红样让 CI 变绿。

别急着写五十条。最小包要可演练,不求一次写全。读完你要动手产出三到五个文件的规则包,会写适配变更相关的禁止项与必须项,并能设计两个违规演练用例。说句自嘲的:我第一次写适配规则时 thrived on 正确废话,演练全绿——因为演练根本没碰到真红线。后来才学会:规则包的验收标准是「故意作恶时会被挡」。

记住一句话:演练全绿不算数——故意作恶会被挡,才叫规则包;挡不住,就还是标语。

概念

本篇里的 Rule,要落地成三到五个可演练文件,不是一篇散文。Fixture,是固定输入样例,用来证明映射变更正确。场景路由,让本包仅在适配、方言、映射类意图加载;安全包仍常驻。假绿,是删红样或放宽断言让 CI 变绿——必须禁止,而且要写进硬约束,不能靠道德谴责。

可以理解为:映射表是引擎之间的翻译词典。改词典不带例句,等于瞎翻译还不许别人抽查。样例同行,是适配工作的最低文明线。

问题在哪

适配场景里,助手「好心」特别有破坏力。

乱改映射不附带样例。当下能跑通一个输入,邻近输入全线回归。聊天里解释得很对,仓库里证据为零。你可以理解为:医生改处方不写病历,下次谁接诊都得重猜。

跳过失败基线。红样烦、CI 红灯烦,于是有人让助手「先把失败用例去掉,回头再说」。假绿一时爽,生产火葬场。假绿不是疏忽,是主动拆掉报警器。

提交真实连接串。演示图省事,把主机口令写进示例配置。规则若不拦截,助手会认为「完整可运行示例」更有帮助——帮到安全事故为止。

举例

场景设定:虚构产品 acme-adaptor。最小文件集建议包含:安全与数据边界、映射变更门禁、样例库纪律、加载说明。目录可以挂在 acme-rules/adaptor/ 下。

映射门禁示意:

## 必须
- 修改映射规则时,同步更新 fixtures/ 下至少1个正例与1个反例
- 变更说明写清:影响引擎列表、风险等级

## 禁止
- 禁止删除红色基线样例来「让CI变绿」
- 禁止在仓库中写入真实主机口令

场景路由:意图含「适配 / 方言 / 映射」时加载本包;安全包仍 always。不要让改文档的会话也背一整份映射细则——那是第 5 篇刚批评过的全家桶。

演练与验收,至少做两个。演练 A:试图无样例改映射——期望助手拒绝或要求补样例。演练 B:配置中出现 password= 明文——期望提醒改用环境变量占位符。人工跑也行,写成 drills.md 即可;但更稳的落点是 CI——门禁不该只在人想起来的时候生效。把演练固化成检查器,就四步:

步骤总览

  1. 把 PR 拆成三个可观察事实:改了映射吗、夹具增删了哪些、配置里带了什么;
  2. 闸一「样例同行」:改映射必须同时新增一正一反例;
  3. 闸二「禁删红样」:fixtures_removed 里出现红样基线,直接定假绿;
  4. 闸三「禁明文口令」:配置里扫出口令特征,要求环境变量占位符——三道闸独立判定,互不遮掩。
# rule_check.py —— 适配 Rule 的 PR 门禁:样例同行、禁止假绿、口令明文
# 纯标准库,复制即跑。用法:python rule_check.py

# 三份虚构 PR:映射 diff + 动了哪些夹具(fixtures/)+ 附带配置
PRS = [
    dict(id="PR-101", title="顺手整理映射",
         mapping_changed=True,
         fixtures_added=[], fixtures_removed=[],
         config="+  engine_url: mysql://acme-demo:P@ssw0rd-real@10.2.2.31:3306/billing"),
    dict(id="PR-102", title="CI 红了,帮它一把",
         mapping_changed=True,
         fixtures_added=["dialect_x_positive.yaml"],
         fixtures_removed=["dialect_y_red_baseline.yaml"],     # 删的是红样!
         config="+  engine_url: ${ACME_DB_URL}"),
    dict(id="PR-103", title="改映射,样例同行",
         mapping_changed=True,
         fixtures_added=["dialect_x_positive.yaml", "dialect_x_negative.yaml"],
         fixtures_removed=[],
         config="+  engine_url: ${ACME_DB_URL}"),
]

PWD = ["password=", "P@ssw0rd", "passwd="]
RED_BASELINE = ["red_baseline"]          # 命名纪律:红样基线只许恢复,不许删


def check(pr):
    """返回违规清单。三道闸:样例同行 / 禁删红样 / 禁明文口令。"""
    bad = []
    added = " ".join(pr["fixtures_added"])
    if pr["mapping_changed"]:
        if "positive" not in added or "negative" not in added:
            bad.append("缺样例:改映射未同步一正一反例(门禁第 1 条)")
    for f in pr["fixtures_removed"]:
        if any(tag in f for tag in RED_BASELINE):
            bad.append(f"假绿:删除红色基线 {f}——CI 变绿的路径里没有「删用例」这一项")
    for kw in PWD:
        if kw in pr["config"]:
            bad.append(f"明文口令:配置出现 `{kw}`,改用环境变量占位符(门禁第 3 条)")
            break
    return bad


def main():
    for pr in PRS:
        bad = check(pr)
        print(f"== {pr['id']}「{pr['title']}」 -> {'REJECT' if bad else 'PASS'}")
        for b in bad:
            print(f"   - {b}")
        print()

    print("== 汇总 ==")
    print("  两道 REJECT 里,缺样例是共犯;假绿与明文口令各撞一次红线;PASS 那份三条全满足。")
    print("  一句话:纸上的禁止项是标语,挡过一次的禁止项才是门禁。")


if __name__ == "__main__":
    main()

跑起来长这样:

== PR-101「顺手整理映射」 -> REJECT
   - 缺样例:改映射未同步一正一反例(门禁第 1 条)
   - 明文口令:配置出现 `P@ssw0rd`,改用环境变量占位符(门禁第 3 条)

== PR-102「CI 红了,帮它一把」 -> REJECT
   - 缺样例:改映射未同步一正一反例(门禁第 1 条)
   - 假绿:删除红色基线 dialect_y_red_baseline.yaml——CI 变绿的路径里没有「删用例」这一项

== PR-103「改映射,样例同行」 -> PASS

== 汇总 ==
  两道 REJECT 里,缺样例是共犯;假绿与明文口令各撞一次红线;PASS 那份三条全满足。
  一句话:纸上的禁止项是标语,挡过一次的禁止项才是门禁。

输出你看什么

  1. PR-101 一次撞两道闸——这就是「多个刹车同时触发」的夹具设计:门禁不是排队放行,各闸独立判定,缺样例不会掩盖明文口令;
  2. PR-102 标题多诚实:「CI 红了,帮它一把」——假绿从来不是疏忽,是主动拆报警器;它补了正例想立功,照样被「缺一反例」逮住,样例同行不认 partial credit;
  3. PR-103 是全绿对照组:三条同时满足才 PASS——门禁要能证明「合规长什么样」,不然只会误伤;
  4. 红样靠命名纪律(red_baseline)识别,这手偏笨——更狠的做法是把「删了什么、为什么红」写进夹具元数据,而不是靠文件名;这个坑第 23 篇配置化断言、第 25 篇红灯回流会回来还账。

复盘模板别省:哪些条目过严、过松;下轮改加载还是改措辞。过严会导致大家口头豁免,过松等于没写。acme 小团队第一版要求「每次改映射补五个正例」,结果人人申请例外;后来改成「至少一正一反」,遵守率反而上升。制度要可执行,不是要好看。

自检

# 适配 Rule 实战自检

- [ ] 是否已有 3~5 个文件的最小包,而不是一篇超长 md?
- [ ] 「样例同行」是否写成必须项?
- [ ] 「禁止假绿」是否写成禁止项?
- [ ] 是否只在相关意图加载,安全包仍常驻?
- [ ] 是否跑过至少两个违规演练?
- [ ] 复盘里是否记下过严/过松条目?

两问。第一,你团队最近一次映射变更,仓库里找得到对应正反例吗?找不到,Rule 还没生效,或根本没写。第二,CI 变绿的路径里,有没有「删用例」这种操作?有的话,先禁自动、再禁人工默认选项——假绿是文化问题,也是条款问题。

实战篇最忌「只读不练」。你哪怕在玩具仓库里建一个假的 fixtures 目录,走一遍演练 A 和 B,体感也会完全不一样。纸上的禁止项是标语,挡过一次的禁止项才是门禁。

若你的业务不是多引擎适配,请平移方法论:找到「一改就容易误伤」的核心资产,为它写样例同行与禁止假绿。核心资产可以是 schema、权限矩阵、计费规则——名字变了,门禁逻辑不变。

落地自检补充:把本篇的关键句用自己的业务语言重写一遍,写不出来就说明还没读进手里。第 1 轮重写往往比再收藏十篇文章管用。

实战里最小 Rule 包往往三页就够:一页硬约束(可判定),一页加载顺序,一页故意违规夹具说明。虚构的 acme 适配团队曾把「改映射必须带样例」写成硬约束,并用一条必失败用例验收——PR 里缺样例就红。两周后,假绿映射几乎消失,不是大家变乖了,是门禁开始认字。

若你今天只能改一处:挑一条最常翻车的「建议口吻」,改成禁止项 + 反例路径,再补一条会失败的夹具。改完立刻跑,比写一篇「我们要重视质量」的公社通知有用。

样例驱动的最小闭环可以这样抄:新建 fixtures/bad_map_without_sample/,里面放一份缺样例的映射 diff;CI 跑 rule-check 期望失败。另一份 fixtures/good_map_with_sample/ 期望通过。两条夹具比十次口头强调「请带样例」管用。谁合并了缺样例的 PR,红灯会当众演戏,文化会跟着变。

思考

小结三句。最小 Rule 包要可演练,不求一次写全。映射类工作的核心门禁是样例同行与禁止假绿。路由只在相关意图加载,避免污染其他会话。

可以理解为:先给适配场景装两道真门禁,再谈炫酷工具。下篇我们进入 Skill——同样是「怎么做」,但形态从宪法换成可移交的 SOP 包。Rule 管边界,Skill 管步骤,别再糊回一锅粥。


上一篇:《不会还有人把全部 Rule 塞进 alwaysApply 吧?Context 一炸,约束就蒸发 | 常驻与场景路由》

下篇预告:《不会还有人把 Skill 写成一坨聊天长回复吧?没法移交就不叫 SOP | Skill 结构拆解》——手册和半成品,请分开放。

觉得有用的话,欢迎点赞、留言聊聊你见过最离谱的假绿操作;有「改映射不带样例」的翻车故事,也欢迎甩过来对照条款拆。

专栏:从小白到AI落地大师|《从 Rule 到落地:AI 工程化实践》