Release v0.0.5

修复

• MySQL 数据源上发布前质量检查的指标取样必然失败：翻译时没传数据源方言，按 PostgreSQL 语法（双引号标识符）渲染，MySQL 以 1064 拒绝。
• MySQL 数据源上问数命中查询规则或补了默认时间窗时失败：这两处重新翻译同样漏传方言，现在与首次翻译用同一个方言。
• 指标取样失败时只显示 mysql query failed，看不出原因；现在带出数据库给出的原话（不含 SQL 原文），与问数失败的提示一致。

Release v0.0.4

[0.0.4] - 2026-09-25

自 v0.0.3 以来的全部改动。镜像 knowflowai/analytics:v0.0.4（linux/amd64、linux/arm64）。

本版有几处行为调整（0.x 阶段的合同变化），升级前请看「变更」一节。

新增

• 建模期用数据核对：字段、关系、指标旁可以就地查数（主标识唯一率与空值率、关系覆盖率与基数、指标取样、样例行），不必等到发布前质量报告。结果按对象内容寻址缓存：对象一改键就变，改名不会让已有结论失效。读缓存不碰业务库；真去量一次走限流，单条语句上限 8 秒，量不出来的结论不进缓存。新增接口 GET/POST .../fact-checks。
• 列画像落库：AI 建模第一步算出的列画像（唯一率、空值率、取值分布）保存下来并绑定 schema 快照，建模页可以直接看到。
• 数据否决 AI 断言的主标识：模型说某列是主标识时，实测唯一率低于 0.95 且行数不少于 100 就降为外部标识，并在争议说明里写出实测数字；没有画像时沿用规则结论，不凭空发明主标识。
• 手工新建指标：界面只问「这个指标怎么算」——对一列做统计（原子指标），或由其它指标计算（复合指标）；表达式免写，维度选列、复合指标选两个指标和一个运算。
• 受治理原语 ENTITY_SHARE 与 RANK_OF：「满足条件的实体占比」「某个实体排第几」由编译器按意图展开（先按实体聚合再比阈值；先在全体上排名再取目标），不再靠提示词约定。这两类写错时 SQL 合法、执行成功，只是数字不对，编译器从 SQL 上判断不出来，所以只能做成原语。
• 编译器新增检查：时间粒度不得比指标声明的 time_granularity 更细（S2SQL_TIME_GRANULARITY_TOO_FINE）；声明了 requires_explicit_time 的指标必须带时间条件（EXPLICIT_TIME_REQUIRED）；数值阈值必须是数字，如 '2万'（S2SQL_NON_NUMERIC_THRESHOLD）。
• 层级树收进发布版本：DimensionValueSpec.parent_value 记录取值的上级，发布时读一次父子配对。按父级筛选（如父科目）能覆盖到下级明细，问数期不再读客户库。
• 业务词典与取值业务名进入提示：词典声明的成员和受治理取值的业务名交给模型；答案里用到、但问题里没有精确命中的成员（即模型自己猜的）随本次回答一起报告。
• 诊断：模型生成 SQL 失败时记下每次尝试的原始输出（截断），阶段明细上限提到 32 KB。
• 评测：用例保存权威 SQL 与结果列，少样本示例不再凭投影现编。

变更

• 作用域由模型在 FROM 中声明，取代 0.0.2 的「生成后逐个作用域试译、按成败反推」。目录按作用域分组呈现，模型写 FROM 作用域名；同一条查询能在多个作用域里翻译时，不再靠粒度收敛或弹卡猜测。
• 主标识改为按需要求（对齐 Cube）：单独一张表不需要主标识就能被问到，只有参与一对多连接、且带可加度量时才需要。每张实表都有默认计数：有主标识的数键（实体数），没有的数行（COUNT(*)，说明里写明数的是行）。
• 一对多扇出按主标识去重算对，不再一刀切拒绝：放大的连接照跑，SELECT DISTINCT(分组维度 + 事实根主标识) 把重复行塌回去，再接回事实根聚合。没有主标识时仍然拒绝；多对多永远不开放；已有安全路径的实体冻结路由不变。
• 外部标识可以分组：只隐藏主标识（它等于按行分组），账户号、门店号这类外部标识可以作为分组维度；它们仍然不进取值字典。
• 模型超时或候选被拒时直接拒答，不再退回规则兜底：规则兜底给出的往往是一个看起来正常的错误数字。
• 问数默认不让模型思考：思维链不改变结构化输出的正确性，只增加延迟（实测 10.5 秒对 0.8 秒）；可以通过配置打开。请求里指定的模型现在对 SQL 生成也生效，此前只作用于结果解读。
• SQL 读超时默认 60 秒；整个问题有一个总时长预算。
• 别名审核不再阻塞发布。
• 提示词规则块收成固定常量：编译器已经会拒的写法删掉，组合写法改成经翻译器验证过的样例（4 → 11 条）。
• 界面按 Ant Design 5 规范统一，主色改为 #2b7de9。

修复

• 「某个值占整体多少」的分母被同一维度过滤成分子本身，结果恒为 1。
• BETWEEN 区间谓词被误判为丢失条件而拒绝。
• 零行的聚合结果被当成成功。
• 裸数字、问题里的数字字面量被当成某个维度的取值。
• Mapper 命中的成员不一定属于该数据集，现在按成员归属过滤。
• 别名与父科目在查询期兑现。
• 名字随作用域变化的标识列导致整份生成目录被放弃。
• AI 建模：已评审的候选重跑整条失败、物理列名带空格失败、慢模型上别名批次超时导致整条失败、被自己的完备性校验拒掉。
• 建模页：普通字段改名不保存、删除路由正在使用的关系报 500、关系挂着的字段降为普通字段后连线消失、普通字段显示成「待确认」、点「应用」白屏、数行数的指标没有单位被误报。
• 发布前试问复用语义索引，不再每次重建。
• 数据源页顶栏铺满可用宽度。

Release v0.0.3

新增

• 多数据源：数据源成为一等实体，可按项目绑定，一个项目里可同时接多个库。
• MySQL 方言：sqlglot 是方言权威，只保留三处经真库实测的例外——时间截断会丢日期类型、生成的 SQL 里不能出现 %（驱动会当参数占位符）、DECIMAL 除法会截断占比精度。五种时间粒度与同比自连接、占比窗口在真 MySQL 上与 PostgreSQL 逐行比对一致。pymysql 已随镜像分发。
• 上传表格：Excel 落库成数据源，走与数据库表相同的建模与问数链路；支持一次导入多张工作表、追加或替换、删除。
• 流式问数：POST /v1/analytics/query:stream 按阶段推送事件；「理解问题」完成时带上模型认出的语义成员。
• 结果解读：结果返回之后异步生成一段话，只允许引用结果里字面出现过的数字，禁止自行计算合计、占比或同环比。默认关闭，开启后不推迟结果返回。
• 助手级问数配置：单次请求可覆盖返回行数、默认时间窗、多轮改写、自洽次数、模型与温度；留空即跟随部署默认，因此不改变既有部署的行为。
• 默认时间窗：问题没写时间范围时按配置补最近 N 天。问题里明确说了的时间一个字不动；补上的窗在回答上可见，并可一键改回不限时间。
• 文本 S2SQL 续跑：下钻与重跑在文本 S2SQL 上做确定性编辑（换过滤值、增减分组维度、换指标、换时间窗），保住原查询的时间粒度与期间比形状；形状不支持时明确拒绝，不静默降级。
• 问数反馈：把「用户说了、系统没接住」的说法收进一个收件箱，含拒答、澄清、模型自己猜的、取值不认识、点赞、点踩六类；按说法聚合、可分页、可标记已处理，并能一键补进业务词典。点踩必须选原因。
• 发布管理：线上版本可切换到任意一个已发布版本，发布历史按序号展示。
• 可观测性：每个查询阶段带真实耗时；诊断可见每次模型与向量调用的用途、尝试次数、耗时与 prompt 规模。

变更

• 作用域选择改为「生成后确定性反推」。此前先按局部证据选定作用域再让模型作答，选错时模型被锁在错误范围里只能硬凑，六道治理关全部放行——用户拿到的是一个看起来正常的错误数字。现在最终 LLM 看到候选作用域成员的并集并写出业务名 S2SQL，编译器逐个真实作用域尝试确定性翻译，恰好一个成功即绑定，零个说明跨了事实根，多个按粒度收敛取最粗。模型提议、编译器裁定：校验比选择容易。
• 澄清退成兜底：业务对象卡整体删除，只保留同名语义元素与跨事实根的指标短语两类。
• 多轮改写默认开启，并加两道确定性门：原话已经点名指标就不改写；改写后多出原话没有的分组维度就作废回退。改写只能补口径，不能替用户加问题。
• 最终 LLM 的指标/维度目录从逐条字典改为带表头的竖线表。实测 prompt 均值 6161→4744 字符，端到端 14.8s→11.7s。
• 模型调用按用途封顶超时；超时不在传输层重试同一个 prompt，换一种生成是解析器重试链的事。重试时把上一次的校验拒绝原因（错误码、原话、被拒 SQL）作为事实告诉模型，不替它改写。

修复

• 模型表达不了某个条件时会自己发明「永不成立」的过滤条件顶掉它，执行成功 0 行，界面显示「查询成功，但没有返回数据」——用户读到的是一句关于自己业务的假话。现在任一 WHERE/HAVING 经常量折叠归约为 FALSE 即拒绝。
• 0 行且过滤值不在该维度已发布取值里时，指名道姓说出来；编辑相似度 ≥0.6 才给近似建议（卡布奇洛→卡布奇诺 给建议，摩卡、深圳 不猜）。措辞是「不在已发布取值里」而不是「不存在」。
• 「每组取前 N」整类问题答不出来。
• 一个词恰好是某维度的取值时，不再当成用户要的过滤条件。
• 带 GROUP BY 的语句判为聚合查询，聚合只写在 ORDER BY 里的写法不再被判成明细查询而拒绝。
• 期间比：治理聚合显式写出来与裸指标引用同义；同一指标既裸写在投影又出现在比率里时，按治理聚合补齐。
• 时间维不参与同名歧义结算——它进查询是因为「按月」「同比」必须落在时间轴上，与某个名词怎么读无关。此前会陷入选一次弹一次的无限澄清。
• 查询自己写的 LIMIT 到顶不再被误报成「超出上限」。
• 派生时间列与期间比列没有别名时按业务名命名，不再出现内部列名。
• 从已发布版本派生草稿时丢掉语义上下文的评审记录。
• 数据源不能是服务自己的 catalog 库（否则内部表会被当业务表建模）；裸 postgresql:// 统一钉到 psycopg 3。