一键诊断
问数系统终于可以像普通软件一样测试、定位和回归，而不是只能反复修改 Prompt 后凭感觉试问。
固定阶段时间线
每次查询按固定阶段展示真实耗时：
| 阶段 | 职责 | 常见失败原因 |
|---|---|---|
| Mapper | 说法映射到已发布业务名 | 业务词典缺条目、别名未覆盖 |
| Parser | 生成只含业务名的 S2SQL | 问题跨了事实根、表达形式模型不熟悉 |
| Corrector | 校验成员、过滤、聚合、确认义务 | 引用未发布名称、人工选择没落实 |
| Translator | 绑定冻结路径，编译参数化物理 SQL | 成员不属于任何单一作用域、路径不可达 |
| Guard | 只读 AST 白名单、结果上限、执行超时 | 语句形态不被白名单允许 |
| 执行 | 只读事务访问数据库 | 数据库超时、连接失败 |
阶段定位是排障的第一步：同样一句「答不出来」，在 Mapper 失败要补词典，在 Translator 失败要改模型结构。
模型与向量调用明细
诊断还可见每次模型与向量调用的：
- 用途（哪个阶段、做什么）
- 尝试次数
- 耗时
- prompt 规模
模型调用按用途封顶超时。超时不在传输层重试同一个 prompt——换一种生成是解析器重试链的事。重试时会把上一次的校验拒绝原因（错误码、原话、被拒 SQL）作为事实告诉模型，但不替它改写。
脱敏导出
诊断可导出为 Markdown，导出前自动脱敏：
- 数据库密码
- API key
- 连接串凭据
- 确认 token
可以安全地贴进工单或发给我们排查。
失败记录与质量门禁
- 查询失败记录绑定同一 Revision / Release
- Golden Suite 用真实问题建立回归集
- 真实数据质量报告绑定同一版本
发布新 Release 前跑一遍 Golden Suite，可以发现本次建模改动是否让原本答对的问题退化。
相关配置
KNOWFLOW_OSS_ALLOW_DEBUG_SQL（默认 true）控制授权诊断是否返回物理 SQL。面向业务用户的普通回答永远不暴露内部 Scope、Dataset、语义 ID 或物理 SQL。