nl2sql-analyst/
├── SKILL.md                                    # 主规则文件（20 条硬规则 + 6 阶段状态机）
├── README.md                                   # 本文件
├── TECH_ARCHITECTURE.html                      # 技术架构文档（HTML）
├── references/
│   ├── semantic_readiness_assessment.md        # 语义就绪度评估标准（6 维度评分体系）
│   ├── fingerprint_sync.md                     # 分层指纹计算与变更同步机制
│   ├── candidate_value_discovery.md            # 候选值发现与绑定锁定
│   ├── sql_safety_checklist.md                 # SQL 确定性安全检查清单
│   ├── sql_semantic_review.md                  # SQL 语义二次审查
│   ├── answer_traceability.md                  # 答案结果溯源
│   ├── confidence_scoring.md                   # 置信度评分标准（5 维度评分）
│   ├── confidence_debt_registry.md             # 置信度债务管理与闭环验证
│   ├── confirmation_playbook.md                # 确认流程（双路径机制）
│   ├── query_clarification.md                  # 追问补槽流程
│   ├── large_schema_memory.md                  # 大库三层架构（1000+ 表）
│   ├── metadata_api_backend.md                 # API 后端规范
│   ├── database_dialects.md                    # 多数据库方言识别
│   ├── dialect_query_guide.md                  # SQL 方言适配指南（含 ClickHouse 安全规则）
│   └── jdbc_dictionary_builder.md              # JDBC 建字典工具（可选）
└── scripts/
    └── jdbc_dictionary_builder/
        └── JdbcDictionaryBuilder.java          # Java 只读元数据读取工具

用户：帮我连这个库问数，JDBC 是 jdbc:mysql://host:3306/mydb，用户名 readonly
AI：
  1. 识别数据源类型和方言（MySQL）
  2. [可选] 询问是否配置通知渠道（飞书webhook/企微机器人）
  3. 读取 information_schema，全库画像
  4. 执行语义就绪度评估（6 维度评分）
  5. 输出评估报告 + 等级（S/A/B/C/D）
  6. 根据等级走双路径：
     - S/A 级：AI 本地建字典草稿 -> 输出确认问题 -> 用户确认
     - B/C/D 级：输出待补充备注清单 -> 维护人员改库 -> 重新评估
  7. 确认完成后写入 confirmed_semantics + 绑定指纹
  8. 进入稳定问数

用户：昨天日报提交情况怎么样？
AI：
  1. 定位涉及的表（rep_daily_reports）
  2. 校验三层指纹（结构/枚举/行数）-> 全部一致
  3. 检查槽位 -> 完整
  4. [候选值发现] "昨天"= 2026-07-26 -> 锁定为 report_date 原值
  5. 生成 SQL -> SQL 安全检查 -> 语义二次审查 -> 只读执行
  6. Sanity check
  7. 计算置信度（5 维度）-> 🟢 92/100（S 级）
  8. 生成答案 + 溯源记录写入文件
  9. 输出结果 + 置信度评估 + 查询逻辑说明
  10. [后处理] 置信度 >= B 级 -> 无债务写入

用户：库存周转率是多少？
AI：
  1. 定位表（fin_inventory）-> 校验指纹 -> 查询
  2. 计算置信度 -> 🟠 58/100（C 级）
  3. 扣分原因：fin_invoice.invoice_type 枚举值未确认（C1 -18）
  4. 输出结果 + 置信度评估（标注低可信）
  5. [后处理] 写入置信度债务表
  6. 影响次数 >= 2 -> 触发通知
  7. 已配置飞书 webhook -> 推送通知：
     "表 fin_invoice 的字段 invoice_type 枚举值未确认，
      建议执行 ALTER TABLE ... COMMENT '发票类型：1=增值税，2=普通...'"
  8. 状态变 notified

维护人员执行 ALTER TABLE fin_invoice MODIFY invoice_type INT COMMENT '发票类型：1=增值税专票，2=普通发票';
  ↓
用户下次查询涉及 fin_invoice 时
  ↓
AI 指纹校验 -> 结构指纹变了 -> 读取最新元数据 -> 发现注释变好了
  ↓
自动更新字典 -> 债务状态变 resolved
  ↓
计算置信度 -> 🟡 82/100（A 级，回升）
  ↓
债务状态变 verified ✅ 闭环完成

用户：帮我连这个库问数...（未提供通知渠道配置）
AI：
  1. 正常完成初始化和建字典
  2. 低置信度债务写入 confidence_debt.md，状态 pending_unnotified
  3. 在问数结果中提示：
     "字段 sys_users.enable 已第 3 次导致低置信度。
      当前未配置通知渠道。可手动查看 confidence_debt.md，
      或配置飞书webhook后由 AI 自动推送。"

用户（后期）：配置飞书通知，webhook 地址是 https://xxx
AI：
  1. 更新 notification_config.md
  2. 扫描 pending_unnotified 债务
  3. 达到阈值的批量推送
  4. 回复："已配置飞书通知，已推送 3 条历史未通知债务"

阶段 0    识别数据源 + 元数据后端 + [可选]通知渠道配置
  ↓
阶段 0.5  语义就绪度评估（6 维度评分 -> S/A/B/C/D 级）
  ↓
阶段 1    建立实时结构证据层（大库走三层架构）
  ↓
阶段 2    STOP-1 确认口径（双路径：A 本地建字典 / B 输出待补充清单）
  ↓
阶段 3    写入确认口径 + 绑定三层指纹
  ↓
阶段 4    问数前分层指纹校验（只校验涉及表）+ 槽位补全
  ↓
阶段 5    候选值发现 -> SQL 安全检查 -> 语义审查 -> 只读查询
           -> 置信度评级 -> 答案+溯源 -> 债务后处理 -> 输出结果

 1. 读取确认口径
 2. 按需读取结构证据
 3. 候选值发现与锁定
 4. SQL 证据闭环
 5. SQL 确定性安全检查（约 25 条机械规则）
 6. SQL 语义二次审查（6 维度独立审查）
 7. 只读执行
 8. Sanity check
 9. 计算置信度（5 维度）
10. 生成答案 + 溯源记录写入文件
11. 输出结果 + 置信度 + 查询逻辑说明
12. 置信度后处理（债务写入/通知/闭环验证）

pending_unnotified -> pending -> notified -> fixing -> resolved -> verified ✅
      （未配置渠道）   （达到阈值）  （已通知）  （修复中）（已修复）（置信度回升）
                                                                    ↓
                                                            （置信度未回升）
                                                                    ↓
                                                              重新 pending

用户说"张三的日报"
  ↓
SELECT DISTINCT staff_id, name FROM sys_users WHERE name LIKE '%张三%' LIMIT 50
  ↓
返回：[('ZS001','张三'), ('ZS002','张三丰')]
  ↓
追问用户选择 -> 锁定 staff_id='ZS001'
  ↓
正式 SQL 只能用 staff_id='ZS001'，禁止猜值

用户：配置飞书通知，webhook 地址是 https://open.feishu.cn/open-apis/bot/v2/hook/xxx