设计哲学

当前立场：约束候选，不许诺答案

Forge 的产品边界是 Evaluate → Enforce → Explain：Direct SQL 与 Forge JSON 都是待验证的候选格式。生成约束、确定性编译、运行时控制与证据各自承担责任，任何一层通过都不等于业务答案正确或生产安全认证。公开源码与本地未发布 v2 候选的差异见架构设计，尚未关闭的发布阻断见验证边界。

四个核心信念

1. 约束是自由的前提

收窄模型输出空间可以约束部分结构错误，但输出空间大小与实际错误率并不是普遍单调关系。约束是否改善答案，需要同模型、同数据与版本绑定的对照证据。

Forge 的做法是大幅收窄输出空间：

动态 Schema 对多数表名/列引用提供枚举约束
JOIN 类型必须显式选择，不存在默认的无类型 JOIN
filter 和 having 分离为独立字段

这些结构约束只在 Provider 严格执行动态 Schema 的相应字段上成立；表达式、业务语义和算法选择仍需验证。Provider 不满足所需协议时不应静默切换为无门禁 SQL 执行。

2. 候选生成与可信执行分离

上游生成：Direct SQL 或 Forge JSON 候选
Compiler：将支持范围内的 Forge JSON 确定性编译为 SQL
Runtime：评估、执行门禁、QueryRun 与证据解释

这个分离意味着：

可审计：审核必须绑定实际 SQL 和版本，候选修改不能沿用旧批准；这是应验证的不变量，不是无限安全保证
可调试：保留输入类型、SQL hash、版本与失败阶段；Direct SQL 不必先转成 Forge JSON
可升级：生成器和编译器可独立演进，但每次变化仍需回归验证

3. Registry 是组织的数据资产

Registry 不是静态的 schema 文件，它是组织知识的沉淀：

结构层（forge sync 自动生成）：表结构、列名、低基数枚举值
语义层（对话式维护）：复购率 = 下过 >=2 次订单的用户 / 下过 >=1 次订单的用户

经审阅的使用反馈可以改善 Registry；错误规则也会让错误更稳定。更多使用不自动带来更准确的语义，变更必须经过业务确认、作用域审查和回归。

4. 修复确定性缺陷，不猜测用户意图

Compiler 应在支持的语义内保持确定性：修复明确的格式和作用域缺陷，但不根据参考答案猜测意图、不静默补齐缺失 CTE 输出或结果列。编译器变更也可能回归，必须由行为测试约束。

Prompt 改动是独立实验；需要同时观察正确题回退、成本和失败，不因一个 probe 改善就推广。

历史自有实验曾记录 14 个 _coerce 修复和 Case 39：3.0 -> 9.0；这是早期 LLM 评分记录，不是当前整体准确率或安全证据。

工程洞察

Alias 作用域有明确边界。 许多数据库不允许同层 SELECT 引用同层 agg alias。_expand_aliases() 仅展开本层表达式中的未限定 agg/window 列引用。SQLGlot AST 定位原文后单次替换，保留限定源列、常量、函数/类型名和子查询内部作用域；CTE缺失输出不猜测补齐。

新能力文档导致过拟合。 每向 prompt 添加新能力说明，模型就有过度使用的倾向。加了 CTE 文档后，简单 GROUP BY 也被包成 CTE。对策：每个新能力必须配一个「何时不用」的反例。

历史语义消歧实验。 早期 J -> J+Sem 的 LLM 评分提升了 0.17，编译失败率从 0.5% 降到 0.0%。这只描述当时样本，不支持“无损提升”的普遍承诺；规则本身也可能错误或引入回归。

历史自我质疑与当前结论

下列 GLM-5 与 MiniMax 数据保留早期探索原成绩，不是当前统一基线。

GLM-5（强推理模型）的测试数据打了一个问号：Forge 74.3% vs 直接 SQL 74.4%，几乎相同。而 MiniMax（中等能力模型）的数据支持 Forge 的逻辑：65.0% vs 57.5%，差距 +7.5pp。

这指向一个不舒服的假说：当模型足够强，“生成错误”这个错误类型本身就在萎缩。

什么还成立

思考之后，有几件事我们认为仍然成立，与模型能力无关：

Registry 语义层的价值——“复购率”的分母定义是业务问题，再强的模型也无法凭空知道
审计链的价值——用户审核的 SQL = 实际执行的 SQL，这在企业场景里是硬需求
弱模型场景仍大量存在——私有化部署的现实是许多团队用本地中小模型

还不清楚的事

DSL 是否需要更薄，以及哪些语义应由 Registry 承担，仍需要具体实验。
当前产品主张已不押注 Forge JSON 的总体准确率优势，而是生成后的验证、受控执行与可追溯证据。

最新公开 BIRD 500 题同候选重放为 Forge 313/500、Direct SQL 314/500，未证明总体优势；完整生成与重放、成本及验证边界见基准测试。

本页为精简版。完整内容参见 docs/philosophy.md。