AI Agent for Data 续篇:把 L3 契约层和 L2 受约束 NL2SQL 真正做出来(带牙齿)

[xg-gh-25]

这是 #36《AI Agent for Data:从幻觉到精准》的续篇 —— 从蓝图到落地证据。

---

一句话: 数据 Agent 的正确性,不来自更聪明的模型,也不来自更整齐的文档——来自让一条违反数据契约的查询在结构上跑不起来。上一篇讲了"应该有 L3";这一篇讲"L3 从散文变成有牙齿的门,是怎么做的,踩了哪些坑"。

目标受众: 正在建数据 Agent 的技术负责人、平台/数据工程师、AI 工程师
关系: 读过 #36 再读这篇;#36 是 What/Why,这篇是 How + 落地后的诚实复盘。

---

回到 #36 的承诺

#36 提了四层参考架构(L1 基础设施 / L2 执行+权限 / L3 语义契约 / L4 Agent+Skills),核心论点是:行业通病是跳过 L3——L4 直接连 L2,后果是真相碎片化、变更静默出错、准确性靠运气。

#36 还留了两个"下一步"没做完,只画了蓝图:

1. L3 从散文变成可执行——当时的语义知识散落在 skill 代码的 SQL 和旁边的注释里,是"文档态":Agent 读的散文,不是校验器能执行的结构。
2. L2 受约束 NL2SQL——在 catalog 词表约束下生成 SQL(~95%),补认证模式(L1)覆盖不到的长尾。
3. 进化循环——高频 L2 查询自动沉淀为 L1 认证模式,让契约"越用越聪明"。

这篇就是这三件事的落地报告。不是又一份设计,是做出来之后的证据 + 诚实的坑。

---

L3:从"文档态"到"契约态"

文档态知识会静默腐烂

一个成熟的数据 Agent skill 家族有一个 knowledge/ 目录——几千行高质量 markdown,描述表语义、必填 filter、粒度规则、已知陷阱。它看起来是契约层。它不是。

它是文档态:Agent 会读的散文。真正的 SQL 内联在每个 skill 的代码里,语义事实活在旁边的注释里。于是:

• 每个 skill 各自漂移——同一张表在三个 skill 里被三种微妙不同的方式查询。
• 一整类生产 bug 藏在内联 SQL 里:一个静默返回全零的查询(引擎拒绝了某个坏谓词,错误被吞掉);"通常都在但不总在"的 filter。
• 散文说"永远用字面量钉住 cycle,别用子查询"——代码却反着来,因为散文不会执行。

关键的 tell: 只有 Agent 读的知识,和只有 Agent 读的 SOUL/AGENT 规则有完全相同的失败模式——恰好在你最自信的时候被绕过。(这是认知层"高置信度→跳过流程"那个 bug,在数据层的翻版。)

修法:契约即数据 + fail-closed 的门

两个产物,都零依赖(纯标准库,所以能作为裸文件拷贝分发到每个消费 skill):

1. catalog(机器可读契约): 一个纯 dict 模块,逐表声明:列、枚举值、必填 filter、粒度注记、和已知陷阱(在这个数据源上本身就坏的 SQL 形状的可匹配签名)。它是"数据是什么"的权威。不是散文——是校验器能对着执行的结构。

2. validate(那道门): 一个函数,在任何 SQL 执行前,拿它引用的每张表对照 catalog 检查。Fail-closed:一条命中已知陷阱、或漏了必填 filter 的查询抛异常、跑不起来。不在 catalog 里的表放行(超出契约范围,记日志)。

"Robust" 的定义是:一条违规查询无法执行——不是"文档更漂亮了"。

放在哪:单一权威

契约和它治理的 SDK 放在一起(共享查询代码已经在那,靠现成的同步机制分发),不是放在给人看的判断文档里。给人看的文档讲为什么/怎么用、指向契约;catalog 是唯一的、机器可读的是什么。一个权威,两类受众。

---

最核心的设计判据:Trap vs Mandatory-filter(它们是两个物种)

这是整个设计里最重要的一条区分。做错了,门会同时既误杀又漏放。

	Trap(陷阱)	Mandatory-filter(必填过滤)
匹配什么	只匹配坏的 SQL(会报错 / 静默污染的形状)	断言一个不变量——每条合法查询都必须满足
误杀风险	≈ 零(坏就是坏)	高——不变量极容易被过度声明
放在共享门上	安全,可以普遍强制	危险——只和"你忘掉的那条最刁钻的真实查询"一样安全

优先用 trap。只有当你能说清"为什么没有任何一条合法查询可能省掉它"时,才加 mandatory-filter——然后立刻去找那条省掉它的查询。

实战里,一个我笃定是不变量的 filter("所有分析查询都会过滤 record-type = X"),结果有三条合法的省略者(一个 owner 查找、一个跨类目聚合、一个按账户抓取)。每次"收窄"这个 filter,都还能再抓到一条真实查询。正确的修法不是继续收窄——是把它删掉,把这个约定写进粒度注记。约定属于 review,不属于 fail-closed 的门。

这是"指标服务于结果,不是取代判断":门服务于正确性,不服务于 filter 数量。为了让门"看起来更严"而多加一条 mandatory-filter,恰好是把一个共享入口变成误杀机器。

---

Trap 的轴:表级 vs 引擎级

Trap 有一个必须选对的轴,否则会同时既过度触发又触发不足:

• 表特定缺陷 → 逐表 trap。 例:某一张表(一个联邦/外部视图)拒绝一个 scalar-subquery-in-WHERE,而完全相同的模式在兄弟表上是合法的。就只在那张表上 trap 它——让合法模式在别处依然合法。
• 方言缺陷 → 引擎级 trap。 当一个数据源迁移引擎(如 Athena → Redshift),整个方言构造会引擎级地坏掉,不是逐表(CAST(x AS DOUBLE) → 要 DOUBLE PRECISION;SUBSTR → SUBSTRING)。把这类 trap 按引擎建,应用到任何表解析到该引擎的查询上——让同一个构造在新引擎上报错、在旧引擎上放行。

选对这个轴,才能让一张表保留它合法的子查询、另一张表拒绝它;让一个方言构造在新引擎上触发、在旧引擎上通过。

---

两条不可妥协的纪律(用血换来的)

1. 只 trap 观测到的失败——下 trap 前先活体探测。
不要因为文档说某模式会坏就 trap 它。先拿它去真实数据源上跑。我对每个方言模式都做了活体探测:确认坏的形式会报错 且 正确的形式能跑,然后才写 regex——并验证 regex 会跳过正确的变体(AS DOUBLE 不能匹配 AS DOUBLE PRECISION;SUBSTR( 不能匹配 SUBSTRING()。一个在共享门上误杀的 trap,比没有 trap 更糟。

2. 拒绝 trap 那些易误杀的模式。
两个候选方言 trap 被故意留作文档,而非门:一个保留字裸词(会匹配列别名、注释、数据),一个在另一个引擎上合法的分区构造。纪律的一部分,是知道哪些规则你绝不该机械化。

---

L2:受约束 NL2SQL——三道结构性闸门

L3 建好后,#36 的第二级("受约束生成,~95%,只服务探索性提问")就有了地基。L2 的入口把一个自然语言问题变成一个安全的答案,靠的是每条路径都过的三道结构性闸门 + 强制的出处披露:

NL 问题
 → 解析意图(指标 / 范围 / 窗口)
 → 路由:  (A) 命中认证模板 → 填 typed slots   [tier=certified ~100%,领导层唯一路径]
           (B) 无模板 → 受约束生成(catalog 词表内) [tier=constrained ~95%,只服务探索]
 → 门 1  L3 validate_query()   (契约无效 → 跑不起来)
 → 门 2  semantic_check()      (契约有效但语义错:跨口径/跨measure/粒度/usage-split)
 → 门 3  tier 门(结构性)       (leadership 上下文结构上拿不到 constrained 答案)
 → 执行(client.query,本身又被 L3 门一次)
 → 出处:{tier, caliber, confidence, caveats}  (永远披露)

门 3 是这轮最硬的一条认知:"要 Agent 记得调用的安全门,不是门"

第一版的 tier 纪律是一个建议性函数 require_tier()——要 Agent 在把数字当权威呈现前记得调用它。这正是那个反复出现的失败模式:一个只有 Agent 记得才生效的门。adversarial 判它 CRITICAL。

改成结构性:usage_context 变成必填参数(无默认);一个 leadership/formal/report/authoritative 上下文在构造上就拿不到 constrained(~95%)答案——直接抛异常。你无法为一个权威场景取得一个 ~95% 的数字,by construction。只有 exploratory 能走 constrained。

安全不来自信任模型(或信任 Agent 会记得),来自结构。一道依赖"记得调用"的门,和只有 Agent 会读的散文规则,是同一个失败家族。

门 2:semantic_check——挡"合法但错"

L3 挡的是契约无效(未知表/列、漏必填 filter、命中 trap)——"这查询到底能不能跑"。它挡不住一条完美合法、但语义错误的 SQL:数字回来了,看着没问题,却被静默地错误校准。这些才是真正上过线的 bug:

• 跨不兼容的 measure 求和(子集 ⊆ 超集,却把两者相加 → 重复计数);
• 跨口径比较(一个表的相对单位 vs 另一个表的绝对 USD,可能差两个数量级);
• 把一个没有某维度拆分的 measure 硬按该维度拆;
• 粒度不诚实(把一个细粒度行读成一个总量;需要 __TOTAL__ 哨兵维度全钉住)。

semantic_check 是专挡这一类的 fail-closed 预检。它是"查询跑了"和"答案对了"之间的差别。

---

为什么 adversarial gate 是全部的重点

跨 6 个 pipeline run,我自己的绿色测试套件从来都不够。每一个 run,一个 fresh-context 的 adversarial reviewer 都找到我的测试抓不到的东西——因为我的测试只覆盖了我想到的形状:

• 原始 bug 会复发,如果用 IN (SELECT …) 重写而不是 = (SELECT …)——我的 trap regex 只匹配 =。(这个门存在的意义就是挡这个 bug,而它正从下一个 LLM 会产生的变体走回来。)
• trap 是表级而非列级——同样的失败击中那张表上的任何列,不止我硬编码的那一个。
• 声明 ≠ 强制:三张 catalog 表声明了却从未真正被门。
• 一个共享 filter 在真实查询一跑就误杀了一条已上线的查询。
• 嵌套括号 / CTE 包裹的子查询绕过了第一版 trap regex。

而且 L2 这轮更狠——我 pass-1 的修复,pass-2 发现它误杀了真实查询:收窄门的动作,把一条合法的"三 measure 并排选"的真实周报查询给拒了;账户名里含某个枚举词的查询触发了误杀。

可复用的 tell: 一个 regex-on-SQL 校验器的盲点,恰好就是模型接下来会产生的那个变体。要 trap 失败类(<列> (= | IN) (…SELECT,嵌套,CTE 前缀),不是你见过的那一个实例。一套绿色的自写测试证明的是"你测了你想到的";adversary 测的是"你没想到的"。在共享门上,那个 gap 是能打爆生产的。所以 L2 的语义门要跑两轮 adversarial:pass-1 抓 bug,pass-2 抓 pass-1 引入的误杀。

---

进化循环:L2→L1 自动沉淀(以及一条诚实的人工闸门边界)

#36 画的进化循环是:高频 L2 查询自动沉淀为 L1 认证模式,让契约"越用越聪明"。落地后,这个循环的形状是四段——但有一条关键的诚实边界必须讲清:

阶段 1 观测(自动):  每次走 L2(constrained)执行,记录:原始问题 / 生成的 SQL /
                     涉及的表列 / 是否成功 / 用户是否追问修正。
阶段 2 聚类(半自动):同一类 SQL pattern 被多次生成(不同用户/时间/相似意图)
                     → 自动聚类 → 提取可参数化模板 → 标记为"候选认证模式"。
阶段 3 沉淀(人工审核 + 一键发布): 领域专家审 SQL 逻辑 / 参数化 / filter 规则
                     → 通过 → 发布为认证模式 → catalog 版本递增。
阶段 4 加速(自动):  下次相同意图 → 直接命中认证模式 → 走 L1 → 更快更准。

为什么阶段 3 必须是人工闸门,绝不能自动写

这是落地时我们钉死的一条设计红线,也是 #36 蓝图里最容易被误读的地方:

certified(L1)= leadership-safe = 人工核验过 caliber。如果把一条高频 constrained 查询自动升级成 certified,你恰好击穿了刚在 L2 建起来的 tier 门。

L2 的门 3 结构性地保证:领导层拿不到一个 ~95% 的答案。可一旦"自动 promote"把某条 constrained 查询变成 certified,它就自动进入了 leadership 的合法路径——一条从没被人核验过 caliber 的 SQL,现在被当成权威数字。这不是进化,是给自己开的后门。

所以正确的循环是 观测 → 聚类 → 浮出候选(报告) → 人工认证 → 发布,不是 auto-write。自动化负责发现和推荐(这部分省人力、越用越聪明);人工闸门负责把一条查询认证为权威(这部分是信任的来源,不能省)。

一句话:进化循环让系统自动告诉你"该为哪个 pattern 建认证模式"(基于真实使用,不是猜测);但"这条 SQL 可以当权威数字"这个判断,永远是人下的。自动化提议,人工处置。

衡量进化健康度

指标	含义	健康方向
L1 命中率	多少 % 查询走了认证模式	↑(目录覆盖全)
L2 门通过率	生成的 SQL 过三道门执行的比例	↑(约束有效)
候选沉淀周期	首次 L2 查询 → 成为认证模式的天数	↓
候选队列长度	待人工审核的候选数	不应持续增长(及时审)
catalog drift	引用了不存在表/列的查询数	应为 0(全被 deny)

---

诚实残留(这是防复发,不全是抓新 bug)

诚实比完美重要。落地后清楚知道还没根除的:

• 方言 trap 今天抓 0 个活 bug——代码库已经迁移离开了那些坏形状。它们是防御性的:结构性地挡住方言 bug 这一类卷土重来。这是发一个 trap 的正当理由,但必须诚实说清——价值是"这一类回不来了",不是"我们抓到了 N 个 bug"。(把两者混为一谈,和把一个通过的 eval case 说成"系统懂这个"、而其实考官被喂了答案,是同一种夸大。)
• 粒度/覆盖类的运行时错误没有静态门能挡(如某日粒度表的保留期导致某些日期返回 0)——本质是运行时数据覆盖问题,只能在取数处 clamp + 在粒度注记里记录。
• tier 诚实性依赖 Agent 如实分类 usage_context——门 3 结构性地拒绝了 leadership→constrained,但"这次提问算不算 leadership"这个分类,仍是 Agent 下的判断。披露缓解,非结构性根除。
• semantic_check 是启发式 backstop,不是证明——L3 的 trap(只匹配坏 SQL)才是更强的保证。语义门覆盖已知的"合法但错"形状,不覆盖未知的。

---

转移方法(任何数据 Agent 契约层都能用)

1. 盘点现实,不是直觉——grep 每张 skill 真正查的表(执行过的 SQL 里的 FROM/JOIN),不是你记得的那些。列对照真实 SQL 核验,不是注释(注释正是那个腐烂了的东西)。
2. 契约即数据,和它治理的代码一起分发,单一权威。
3. 一个所有查询都流经的入口——就在那里下门。
4. Trap > filter。 下 trap 前先活体探测。选对表级/引擎级轴。拒绝易误杀的 trap。
5. 上线前做静态证明:把每一条真实生产查询过一遍门——全部必须通过(零误杀)——外加对 trap 做变异证明(在坏形式上会触发)。
6. adversarial gate,fresh context——它找到你测试没想到的变体。语义门跑两轮:第二轮抓第一轮引入的误杀。
7. 诚实报告——防御性 vs 现场抓 bug;约定 vs 强制;自动发现 vs 人工认证。

---

回到大 thesis

这是四层数据 Agent 架构里"L3 从文档态到契约态"这一步的落地(L1 基础设施 · L2 执行+权限 · L3 语义契约 · L4 Agent/skills)。行业通病是整个跳过 L3(L4 直连 L2)。有一个散文的 L3 是半步;把它做成可执行、fail-closed 才是把"文档化的数据语义"变成"系统产不出错查询"。再往上一级,就是这篇讲的 L2 受约束 NL2SQL + 进化循环(自动发现、人工认证)。

一条数据 Agent 正确性的天花板,不是模型 IQ——是你把多少数据纪律,编码成了模型无法绕过的强制。

---

方法论层面。所有领域细节(真实表名、数字、客户)是内部信息,已刻意排除——可复用的模式才是重点。落地证据来自 6 个 pipeline run 构建的一个数据 Agent skill 家族的 L3 契约层 + L2 受约束 NL2SQL,每个 run 都过强制的 fresh-context adversarial gate。