# NL2SQL-Agent **Repository Path**: yechen653/nl2-sql-agent ## Basic Information - **Project Name**: NL2SQL-Agent - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-07 - **Last Updated**: 2026-11-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # NL2SQL Agent > 用自然语言问数据库;在给出答案前先自查一遍,在执行前让人确认一次,执行时只读、限行、全程留痕。 单机三进程 MVP。业务同学提问 → 生成 SQL → **干跑校验**(白名单 / 单语句 / EXPLAIN 成本门)→ **人工审批** → 凭一次性票据只读执行 → 流式解读结果。模型产出的 SQL 被视为**不可信输入**,因此 Python 侧没有数据库驱动、Java 侧不接触模型。 - 状态:**已交付并冻结**(D-36)。G1~G3 已过闸、S1~S4 落地、G4 四轮评测(SC-1 严格 **0.46 → 0.74 → 0.86**,已达标);ims 已接入,后续演进在 ims 仓 - 仓库: 分支 `master` - **已集成到库存订单系统**: 后续演进在该仓,本仓为交付基线 - 文档索引:[docs/README.md](./docs/README.md) 决策记录:[决策日志](./docs/决策日志.md)(D-01~D-31) ## 目录 1. [解决什么问题](#1-解决什么问题) 2. [核心特性](#2-核心特性) 3. [架构与信任边界](#3-架构与信任边界) 4. [一次提问的完整链路](#4-一次提问的完整链路) 5. [安全模型](#5-安全模型) 6. [契约与接口](#6-契约与接口) 7. [目录结构](#7-目录结构) 8. [技术栈](#8-技术栈) 9. [安装与配置](#9-安装与配置) 10. [启动与验证](#10-启动与验证) 11. [评测体系](#11-评测体系) 12. [设计决策索引](#12-设计决策索引) 13. [已知边界与路线图](#13-已知边界与路线图) 14. [故障排查](#14-故障排查) 15. [文档索引](#15-文档索引) --- ## 1. 解决什么问题 不会写 SQL 的业务同学(运营 / 产品 / 销售支持)想问「上个月华东新客复购率多少」,通常要向数据组提需求等 1~3 天,或自己拼 Excel 被质疑口径。这个项目的目标不是让 SQL 生成得更快,而是让**结果可信**。 | | 人直接写 SQL | 贴表结构给聊天模型 | 本项目 | |---|---|---|---| | 意图对齐 | 人自己负责 | 模型猜,无人复核 | 审批条用**人话描述**让人确认「是不是我要问的」 | | 出错时 | 自己排查 | 只看到一段 SQL | 能定位是干跑拒了、自纠没收敛、还是执行超时 | | 模型胡说时 | — | 可能把 SQL 直接贴进生产库执行 | **物理上写不进去**:Python 无 DB 驱动,Java 只读 | | 结果口径 | 自己知道 | 常常不写 | 结论文本必须写筛选条件、时间范围、聚合方式 | | 留痕 | 无 | 无 | 被拒 / 干跑失败 / 超时也写审计 | **产品定位的硬约束**(G1 §2,D-10):目标用户是业务同学,不是分析师。他看不出 `LEFT JOIN` 和 `INNER JOIN` 的差别,只能判断「这句话是不是我要问的那个问题」。所以:SQL 卡片默认折叠、审批条必须给≤120 字的人话摘要、错误提示必须是业务语言、解释必须写口径。 **明确不做的**(G1 §4,均写了触发条件):写操作(INSERT/UPDATE/DDL)、多轮追问、向量库语义检索、多用户权限、微服务/消息队列、图表可视化、MySQL 以外方言的实现。这些不是遗漏,是范围决策。 ## 2. 核心特性 **① 干跑校验(dry-run)**:SQL 不直接执行,先过白名单(按 JSqlParser 解析出的**真实表名**,不是执行计划里的别名)、单语句检查、`EXPLAIN FORMAT=JSON` 成本估算。通过才签发一次性票据。 **② 人工审批**:LangGraph `interrupt()` 暂停图,SSE 推一条**自包含**的审批条(人话摘要 + SQL 首行 + 风险标签 + 执行计划摘要)。自包含是因为刷新页面后前序 `sql` / `plan` 事件已经丢了,靠前端拼凑必然白屏。`resume` 回传 `approval_id`,重复提交幂等。 **③ 报错自纠**:干跑失败时把错误码、错误信息、**已试过的 SQL 清单**一起喂回模型,最多 2 轮;同一错误码连续出现两次即停,避免烧 token 又写不出新东西。模型侧故障(限流 / 超时)不走自纠——那不是 SQL 的问题。 **④ 结果解读**:执行结果一次性发 `row` 事件(≤200 行 + `truncated` 标记),随后流式 `token` 生成业务语言结论。prompt 明确禁止推测样本里没有的结论、禁止把 `LIMIT 20` 猜成「已截断」。 **⑤ 可量化评测**:Golden 集 50 条、结果指纹比对、六项指标、失败逐条归因、一条命令回归。详见 [§11 评测体系](#11-评测体系)。 **⑥ 契约单一真源**:JSON Schema → 生成 Python pydantic 模型与 `contracts.d.ts`。字段写错会在测试里变红,不是联调时才发现。详见 [§6 契约与接口](#6-契约与接口)。 ## 3. 架构与信任边界 ``` ┌──────────────────────┐ SSE: POST /api/ask, /api/resume ┌──────────────────────────┐ │ Vue3 UI :5180 │ ─────────────────────────────────► │ Python 编排层 :18000 │ │ A~G 七个区块 │ ◄───────────────────────────────── │ FastAPI + LangGraph │ └──────────────────────┘ step/sql/plan/interrupt/ │ 8 节点图 + checkpoint │ token/row/error/done └────────────┬─────────────┘ │ HTTP ═══ 物理信任边界:Python 无 DB 驱动 ═══ │ /api/schema │ /api/dry-run ▼ /api/execute ┌──────────────────────────┐ │ Java 网关 :18080 │ │ 白名单/单语句/EXPLAIN │ │ 成本门/票据/审计 │ └────────────┬─────────────┘ │ JDBC 只读 ┌───────────────────────────┴──────────┐ ▼ ▼ ┌─────────────────┐ ┌─────────────────────┐ │ MySQL ims :3306 │ │ nl2sql_audit(独立库)│ │ 被查业务库 │ │ 审计表,只授 INSERT │ └─────────────────┘ └─────────────────────┘ ``` | 能力 | Python | Java | UI | 谁明确不做 | |---|---|---|---|---| | schema 快照提供 | — | ✅ | — | Java 不做检索 | | schema 检索(BM25) | ✅ | — | — | Java 侧无分词依赖 | | SQL 生成 / 自纠 / 解读 | ✅ | — | — | **Java 绝不接触模型** | | 白名单 / 单语句 / EXPLAIN | — | ✅ | — | **Python 不做安全判定** | | 执行 / 限行 / 超时 | — | ✅ | — | **Python 拿不到 DB 连接** | | 审批状态机 | ✅ | — | 展示 | Java 不记审批,只验票据 | | 审计留痕 | — | ✅ | — | Python 不写审计(会被绕过) | **为什么必须三进程**(D-02):如果一个进程里既跑 LLM 又握 DB 连接,安全就只能靠代码自觉——prompt 注入让模型吐出 `DROP TABLE`,靠的就是某一行正则。拆开之后边界是物理的。反过来推演单体:安全防线与业务逻辑共享进程、一个 bug 同时失效;审计与业务共享事务边界,业务回滚会带走审计;想加第二个人或换数据库都得动同一个部署单元。 **为什么网关是旁路不是代理**:业务系统的正常流量完全不经过网关,只有 NL2SQL 发起的查询才走这条链。所以「所有 DB 调用都要过一遍 Java,会拖累高并发」这个担心不成立。若将来集成进有业务流量的库,需要改 JDBC URL 指向只读从库(G4 §7.1 前置条件 #3)——范围扫描的 IO 会把索引页挤出 buffer pool,而这个劣化**在网关自己的指标里看不见**。 **端口**:G2 §1.3 / G4 §6 是设计定稿值;本机因其他项目占用 5173、并避免与本地工具端口碰撞,演示用另一组。 | 进程 | 设计值 | 本地演示值 | 独立重启 | |---|---|---|---| | MySQL | 3306 | 3306 | — | | Java 网关 | 8080 | **18080** | ✅ | | Python 编排 | 8000 | **18000** | ✅(未完结会话靠 checkpoint 恢复) | | Vue 前端 | 5173 | **5180** | ✅ | 三进程 ≠ 微服务:没有注册中心、路由、容器编排、消息队列,各自 `main()` 起来,配置靠 `.env` 与 `application.yml`。 ## 4. 一次提问的完整链路 LangGraph 图共 **8 个节点**(`NodeName` 契约枚举): ``` entry ──► pick_schema ──► generate_sql ──► validate ──┬── 通过 ──► request_approval ▲ │ │ │ └── 失败 ──► self_correct │ └────────────────────────────────────────┘ │ (≤2 轮,同错即停)│ ▼ approve ──► execute ──► interpret ──► END reject ──► 带理由回 generate_sql ``` `validate` 节点调网关 `/api/dry-run`,`execute` 节点调 `/api/execute`。**中断期间图停在 checkpoint**,SSE 流静默但不发 `done`;`done` 由 `GraphRunner`(传输层)统一发,因为 `interrupt()` 抛异常后节点重入会重复推事件。 ### SSE 事件(8 类) | 事件 | 关键字段 | 作用 | |---|---|---| | `step` | `node`, `status(running/ok/failed/skipped)`, `elapsed_ms`, `error_code` | 时间轴;同时是异常时定位「哪个节点崩了」的依据 | | `sql` | `sql`, `dialect`, `retry`, `human_summary` | SQL 卡片;`retry>0` 表示自纠第 N 轮。人话摘要与 SQL 同一次 LLM 调用产出,不能事后补 | | `plan` | 复用 `PlanModel`(`nodes`, `total_rows_est`, `risk`…) | 执行计划。**发事件前必须裁掉 `error` 与 `dryrun_ticket`**,否则票据会泄漏给前端 | | `interrupt` | `thread_id`, `approval_id`, `human_summary`, `sql_preview`, `risk`, `plan_summary` | 审批条;自包含,刷新后由 `GET /api/session` 重放 | | `token` | `delta` | 仅用于结论文本,**不用于 SQL**(D-18) | | `row` | `columns`, `rows`, `truncated`, `row_count`, `elapsed_ms` | 一次性发全部结果(≤200 行,D-15),不做前端拼接 | | `error` | `code`, `message`, `retriable`, `node` | 受理后出错走 SSE 200 + `error`;未被受理走 4xx 普通 JSON(前端按此分流) | | `done` | `thread_id`, `status(ok/failed/rejected)`, `total_ms`, `retry_total` | 唯一终止信号;`total_ms` 只累计节点耗时,**不含审批等待** | > `done.status` 是 3 态,与 `SessionStatus` 的 5 态(`running` / `waiting_approval` / `done` / `failed` / `rejected`)不是同一个枚举。混用会在契约校验那一步才炸。 ### 实测时序(2026-11-07,真模型 + 真 MySQL) ``` POST /api/ask → 5×step → sql → plan → interrupt 2448 ms(generate_sql 2289 ms,占 93%) POST /api/resume → row(20 行 / 网关 321 ms) → 96×token → done(ok) 2235 ms done.total_ms = 4437(只累计节点耗时,不含审批等待) ``` 前端七个区块(G2 §3):A 提问 / B 时间轴 / C SQL 卡片(默认折叠)/ D 审批条(sticky,≤30vh,按钮常驻)/ E 结果表 / F 结论文本 / G 历史侧栏。 ## 5. 安全模型 | # | 防线 | 机制 | |---|---|---| | 1 | 物理隔离 | Python 无数据库驱动,Java 不接触模型 | | 2 | 白名单 | `gateway.datasources.main.tables` 五张表;启动时校验表存在性,缺表 fail-fast | | 3 | 语法与单语句 | JSqlParser 解析真实表名(执行计划的 `table_name` 可能是别名,D-26);拒绝多语句与写操作 | | 4 | 只读 | 数据库账号只授 `SELECT`,连接建立即 `SET SESSION TRANSACTION READ ONLY` | | 5 | 成本门 / 限行 / 超时 | `limits.max-scan-rows=100000`、`max-rows=200`、`timeout-ms=10000` | **一次性执行票据**(D-14):干跑通过才签发,绑定 `sha256(sql)`,TTL 1800 秒,存进程内 `ConcurrentHashMap`,**先消费再校验哈希**。`/api/execute` 必须凭票,所以审批通过后无法偷换 SQL;重复 resume 幂等。多实例 / 网关重启会让票据失效,这是已知限制(G4 §7.1)。 **成本门为什么在执行前**:`LIMIT` 与 `setMaxRows(200)` 只约束**结果行数**,不约束**扫描行数**——`COUNT(*)` / `GROUP BY` / 带 `ORDER BY` 的查询扫描量一点不减。超时只能减少连接占用时间,已经烧掉的 IO 退不回来,被挤出 buffer pool 的索引页也不会自己回来。所以取 `EXPLAIN` 各表 `rows_examined_per_scan` 之和,超阈值在干跑阶段直接拒(`E_QUERY_TOO_EXPENSIVE`)。 **审计**(D-23 / D-24):写在独立库 `nl2sql_audit`,独立账号只授 `INSERT`(可改的审计等于没有审计)。执行路径 **fail-closed**:写不进审计就不返回数据;干跑路径 best-effort,只告警——两处都 fail-closed 会让审计库一抖就拖死整个问数功能。身份字段 `user_id` / `tenant_id` / `approver` 一路透传到审计表。 **已声明的能力边界**:`t_order_item` 约 18.9 万行且无时间列索引,不带 `order_status=1` 的全表聚合会被成本门拒。这是产品边界而非缺陷(D-29),样本在 `eval/boundary.json`;前端 F 区会给出原因与下一步建议。**不通过调阈值或放宽评分口径来粉饰指标**。 ## 6. 契约与接口 `contracts/` 是机器读的真源,`docs/` 是人读的解释。表格靠自觉,schema 会让测试变红:Java 里写 `ticket` 而不是 `dryrun_ticket`、`status` 混用 `done`/`ok`、审批条缺 `human_summary`、响应多包一层 `result`——这 8 类真实漂移全部由 `additionalProperties: false` + `enum` + `required` 在 0.1 秒内拦下。 ``` contracts/ ├── common.json 共用类型:PlanNode / PlanModel / ErrorCode / 各类枚举 ├── events.json 8 个 SSE 事件 payload ├── http/*.json 8 个接口的请求 / 响应,可单独 $ref 与断言 ├── samples/ 合法样本(也是「真实响应长什么样」的文档) ├── invalid/broken.json 8 个必须被拦下的错样本 ├── validate.py 合法必须过、错样本必须红(27 例) ├── generate.sh 生成 Python 模型 + TS 类型 └── generated/ ├── contracts_py/ pydantic v2 模型(extra='forbid') └── contracts.d.ts 前端零 wire 类型定义,全部 import type 自这里 ``` 改完 `*.json` 后(**Git Bash**): ```bash bash contracts/generate.sh # 生成双端产物,内部自带 27 例契约校验 orchestrator/.venv/Scripts/python.exe -m pytest eval/tests -q # L1 指纹单测 ``` 生成器固定用 Python 3.12(D-22),与项目 3.14 解耦;产物要单独验证能在 3.14 上 import。 ### HTTP 接口 | 服务 | 接口 | 说明 | |---|---|---| | 编排层 | `POST /api/ask` | SSE 流;带 `thread_id` 且有待审批项时重放 `interrupt` | | | `POST /api/resume` | SSE 流;`approval_id` 必须与当前待审批项一致 | | | `GET /api/session/{thread_id}` | 状态快照,用于刷新恢复;只对会话所有者可见(否则 404) | | | `GET /api/healthz` | 存活探针,**免鉴权**;不查库不查模型,返回 `auth_required` 便于自查配置 | | | `GET /api/readyz` | 就绪探针,**免鉴权**;只探网关 `/api/healthz`(2s 超时),不可达返回 503 | | 网关 | `GET /api/healthz` | 存活探针,**免鉴权**(`auth.enabled=true` 时也放行) | | | `GET /api/schema` | 全量表结构快照 + etag(60s 缓存) | | | `POST /api/dry-run` | 校验 + EXPLAIN + 签发票据,**不执行** | | | `POST /api/execute` | 凭票只读执行 + 审计 | 调用方认证(`ORCH_API_KEYS` 非空时生效):`/api/*` 必须带 `X-API-Key` 与 `X-User-Id`,两者缺一即 401/400;请求体里的 `user_id`/`approver` 若与 `X-User-Id` 不一致直接 400(审计只能记一个人)。接入细节见 [接入对接单](./docs/接入对接单.md)。 ### 错误码(`ErrorCode` 契约枚举,17 个) | 类别 | 码 | |---|---| | SQL 校验 | `E_SQL_PARSE` `E_UNKNOWN_TABLE` `E_NOT_WHITELISTED` `E_MULTI_STATEMENT` `E_DIALECT_MISMATCH` | | 执行准入 | `E_TICKET_INVALID` `E_QUERY_TOO_EXPENSIVE` `E_EXEC_TIMEOUT` `E_ACCESS_DENIED` | | 会话 / 审批 | `E_APPROVAL_MISMATCH` `E_REASON_REQUIRED` `E_SESSION_FINISHED` | | 模型 / 依赖 | `E_LLM_UNAVAILABLE` `E_STRUCTURED_OUTPUT` `E_SCHEMA_UNAVAILABLE` | | 其他 | `E_UNAUTHORIZED` `E_INTERNAL` | **对外归并成 4 类**(调用方前端只处理这 4 类,新增码不用改前端):`contracts/error-map.json` 给出 `LLM_FAILED` / `SQL_REJECTED` / `EXEC_FAILED` / `UPSTREAM_DOWN` 的逐码映射与中文备注。它是派生映射,真源仍是枚举;`contracts/validate.py` 会断言「枚举有的码必须都归类、归类里不许有枚举外的码」,漏一个直接校验失败。 > `E_ACCESS_DENIED` 是 2026-11-11 收紧成列级授权后新增的:MySQL 1142(表/对象级)与 1143(列级)不能再落 `E_SQL_PARSE`——否则模型会把「这列无权读」当成「语法写错」反复改语法。它允许一轮自纠(模型常只是顺手多投影了一列),同码连出即停。 > 自造错误码会被 `events.coerce_code()` 收敛成 `E_INTERNAL`,把真实故障伪装成内部错误。模型侧异常必须只用契约里已有的码。 ## 7. 目录结构 ``` NL2SQL-Agent/ ├── README.md 本文件(项目门面) ├── .gitignore 全仓库唯一一份 ├── .gitattributes 统一 LF(防 generate.sh 在 Windows 检出成 CRLF) ├── .editorconfig 统一缩进与编码 ├── contracts/ 契约单一真源(机器读)+ generated/ 双端产物 ├── gateway/ Java 网关 ┐ ├── orchestrator/ Python 编排层 ├ 三个可运行进程,各自持有依赖真源 │ ├── pyproject.toml │ │ ├── src/nl2sql/ 标准 src 布局 │ │ └── tests/ │ ├── ui/ Vue3 前端 ┘ ├── eval/ G4 评测:Golden 集、指纹、L1~L4 回归、results/ ├── scripts/ 开发辅助脚本(seed_demo_data.py) ├── docs/ 四道闸门 + 决策日志 + archive/ └── var/ 运行时数据(评测缓存 / 会话检查点),不入库 ``` | 目录 | 关键文件 | 职责 | |---|---|---| | `gateway/` | `pom.xml`、`dialect/MysqlDialect.java`、`service/DryRunService.java`、`service/ExecuteService.java`、`ticket/TicketStore.java` | 安全判定与执行 | | `orchestrator/src/nl2sql/` | `graph.py`、`nodes/`、`llm/deepseek.py`、`llm/prompts.py`、`stream.py`、`api.py` | 编排、模型、SSE | | `ui/src/` | `App.vue`、`components/`、`composables/useSession.ts`、`lib/sse.ts` | 展示与状态机,不做任何判定 | | `eval/` | `golden.json`、`boundary.json`、`fingerprint.py`、`build_golden.py`、`run_eval.py`、`run_all.py` | 评测与回归 | | `docs/` | `G1~G4-*.md`、`决策日志.md`、`archive/` | 过程文档 | **为什么不在仓库根套全局 `src/` 或 `apps/`**:多语言 monorepo,Maven / Vite / uv 各有项目根,多一层目录不改变任何依赖关系。只在 Python 侧采用标准 `src/` 布局 + 可编辑安装(`uv sync` 后 `nl2sql` 可直接导入),其余保持各自生态惯例。 ## 8. 技术栈 | 层 | 技术 | 版本 / 备注 | |---|---|---| | 网关 | Java **25**(Temurin)、Spring Boot **3.5.7**、Maven 3.9 | `spring-boot-starter-web` + `jdbc`,**JdbcTemplate 而非 MyBatis**(只有一张审计表、一条固定 INSERT,MyBatis 的卖点全是零消费) | | | JSqlParser **4.4** | 解析真实表名,执行计划的 `table_name` 是别名(D-26) | | | Jackson | `SNAKE_CASE` + `default-property-inclusion: always`(null 必须序列化,否则前端拿到 `undefined` 把「没索引」当成「有索引值」) | | 编排 | Python **3.14.8** + uv | `src/` 布局,包名 `nl2sql` | | | FastAPI ≥0.118、uvicorn ≥0.37、sse-starlette ≥3.0 | 前端用 `@microsoft/fetch-event-source` 处理 POST 上的 SSE(`\n\n` 分帧 / 多行 data / 心跳注释 / AbortController);原生 `EventSource` 只支持 GET | | | LangGraph ≥1.1.2 + `AsyncSqliteSaver` | `interrupt` / `Command(resume=...)` / checkpoint;Saver 在 `.aio` 子模块 | | | pydantic ≥2.11、httpx ≥0.28 | `trust_env=False` 绕开本机系统代理 | | 模型 | DeepSeek OpenAI 兼容接口 | 配置为 `deepseek-chat`;`/models` 实测返回 `deepseek-flash` / `deepseek-v4-pro`,`deepseek-chat` 是兼容别名,服务端实际以 `deepseek-flash` 执行 | | | 结构化输出 | httpx 直连 `tools` + 强制 `tool_choice`,**不用** `with_structured_output`;`temperature=0`,超时 60s | | 前端 | Vue **3.5**、Vite **6**、TypeScript ~5.7 | `@microsoft/fetch-event-source`;纯类型引用 `contracts.d.ts` | | 数据 | MySQL **8** | 被查库 `ims` + 独立审计库 `nl2sql_audit` | | 测试 | pytest + pytest-asyncio、JUnit 5 / MockMvc、jsonschema | L1~L4 见 §11 | ## 9. 安装与配置 > 本机开发的最短路径。**生产部署**(数据库授权、配置项清单、构建产物、启动顺序、nginx/systemd)见 [docs/部署手册.md](./docs/部署手册.md)。 ### 9.1 前置 - MySQL 8(本机 3306)、JDK 25、Maven 3.9、uv、Node 22(用户本机用 nvm 管理,`nvm use 22`) - 一个可用的 DeepSeek Key ### 9.2 数据库 建库与导入被查库数据(本项目复用库存订单库 `ims`,已有数据可跳过),然后建两个**最小权限账号**: ```sql CREATE DATABASE IF NOT EXISTS nl2sql_audit DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci; GRANT SELECT ON ims.* TO 'nl2sql_ro'@'%'; GRANT INSERT ON nl2sql_audit.* TO 'nl2sql_audit'@'%'; ``` 审计表 DDL(**Git Bash**): ```bash mysql -u root -p < gateway/src/main/resources/sql/mysql/sql_audit.sql ``` 白名单在 `gateway/src/main/resources/application.yml`,默认五张表:`t_user` / `t_product` / `t_stock` / `t_order` / `t_order_item`。**换被查库只需三处**:连接串、白名单、`GRANT SELECT`;上层 Controller / Service / 契约不用改(D-24)。 需要更有区分度的演示数据时(**Git Bash**,在 `orchestrator/` 下执行;只 INSERT、带 `DEMO` 标记、`--clean` 可精确回滚,绝不改动压测基线数据): ```bash cd /e/studyRecord/project/NL2SQL-Agent/orchestrator NL2SQL_SEED_PASSWORD='' uv run --with pymysql python ../scripts/seed_demo_data.py --seed ``` **PowerShell**:先单独执行 `$env:NL2SQL_SEED_PASSWORD='<口令>'`,再执行 `uv run --with pymysql python ..\scripts\seed_demo_data.py --seed`。 ### 9.3 两个不入库的配置文件 | 文件 | 从模板复制 | 含什么 | |---|---|---| | `orchestrator/.env` | `.env.example` | DeepSeek Key、模型名、网关地址、`llm_mode`、超时、重试上限 | | `gateway/src/main/resources/application-local.yml` | `.template` | 只读账号 / 审计账号的 URL 与口令 | 主要变量(`.env.example`): | 变量 | 默认 | 说明 | |---|---|---| | `ORCH_LLM_MODE` | `fake` | 改 `deepseek` 才接真模型;**缺 Key 会在启动时 fail-fast**,不是第一次提问才炸 | | `ORCH_DEEPSEEK_API_KEY` | 空 | 只从环境变量 / `.env` 读,代码里不写默认值 | | `ORCH_DEEPSEEK_MODEL` | `deepseek-chat` | 兼容别名,实际执行 `deepseek-flash` | | `ORCH_GATEWAY_MODE` | `real` | `fake` 用于离线演示与单测 | | `ORCH_GATEWAY_BASE_URL` | `http://127.0.0.1:18080` | 与网关实际端口一致 | | `ORCH_LLM_TIMEOUT_S` | `60` | 短了会让自纠第二轮悄悄变成 `E_LLM_UNAVAILABLE`,看起来像模型变笨 | | `ORCH_LLM_TEMPERATURE` | `0` | 同一问题两次跑出两条 SQL,审计就无法复现 | | `ORCH_DB_PATH` | `var/checkpoints.sqlite` | checkpoint,可随时删;与 MySQL 审计库无关 | | `ORCH_MAX_RETRY` / `ORCH_TOP_K_TABLES` | `3` / `3` | 自纠上限 / schema 检索 Top-K | | `ORCH_API_KEYS` | 空 | 逗号分隔的调用方 key。**空 = 关闭认证(单机自用)**;非空则 `/api/*` 必须带 `X-API-Key` + `X-User-Id`,探针例外 | 网关侧关键配置(`application.yml`): | 配置 | 值 | 说明 | |---|---|---| | `gateway.limits.max-scan-rows` | `100000` | 成本门阈值,**执行前**拒绝 | | `gateway.limits.max-rows` | `200` | 结果行数上限,超过标 `truncated` | | `gateway.limits.timeout-ms` | `10000` | 超时强杀连接 | | `gateway.ticket.ttl-seconds` | `1800` | 必须 ≥ 审批最长等待时间 | | `gateway.schema.cache-seconds` | `60` | etag 变化时自然失效 | | `gateway.auth.enabled` | `false` | 单机 MVP 关闭,集成时打开并配 keys | ### 9.4 安装依赖(**Git Bash**) ```bash cd /e/studyRecord/project/NL2SQL-Agent/orchestrator && uv sync cd /e/studyRecord/project/NL2SQL-Agent/ui && npm install cd /e/studyRecord/project/NL2SQL-Agent/gateway && JAVA_HOME="D:/SDK/java/jdk/temurin@25.0.5" /d/SDK/java/mvn-3.9/bin/mvn -q test ``` `uv sync` 会把 `nl2sql` 以可编辑方式装进 `.venv`;前端 `package-lock.json` 已入库;Java 侧无需额外安装(Maven 首次运行会下载依赖)。 ## 10. 启动与验证 > **生产部署**(jar + uvicorn + nginx + systemd、数据库授权、启动顺序、升级回滚、安全清单)见 **[docs/部署手册.md](./docs/部署手册.md)**。本节只是本机跑起来的最短路径。 **Git Bash**,三个终端各一条,顺序为 MySQL → 网关 → 编排层 → UI: ```bash cd /e/studyRecord/project/NL2SQL-Agent/gateway && JAVA_HOME="D:/SDK/java/jdk/temurin@25.0.5" /d/SDK/java/mvn-3.9/bin/mvn -q spring-boot:run -Dspring-boot.run.arguments=--server.port=18080 cd /e/studyRecord/project/NL2SQL-Agent/orchestrator && .venv/Scripts/python.exe -m uvicorn nl2sql.main:app --host 127.0.0.1 --port 18000 cd /e/studyRecord/project/NL2SQL-Agent/ui && npm run dev ``` **PowerShell**(Windows PowerShell 5.1 不支持 `&&`,用分号;三个终端各一条,可整段复制): ```powershell $env:JAVA_HOME = "D:\SDK\java\jdk\temurin@25.0.5" Set-Location E:\studyRecord\project\NL2SQL-Agent\gateway; D:\SDK\java\mvn-3.9\bin\mvn -q spring-boot:run "-Dspring-boot.run.arguments=--server.port=18080" Set-Location E:\studyRecord\project\NL2SQL-Agent\orchestrator; .venv\Scripts\python.exe -m uvicorn nl2sql.main:app --host 127.0.0.1 --port 18000 Set-Location E:\studyRecord\project\NL2SQL-Agent\ui; npm run dev ``` 健康检查在 PowerShell 里要写 `curl.exe`(`curl` 是 `Invoke-WebRequest` 的别名,参数不兼容),例如 `curl.exe -s --noproxy "*" http://127.0.0.1:18000/api/healthz`。 健康检查(**Git Bash**): ```bash curl -s --noproxy '*' http://127.0.0.1:18080/api/schema -o /dev/null -w "gateway %{http_code}\n" curl -s --noproxy '*' http://127.0.0.1:18000/api/healthz curl -s --noproxy '*' http://127.0.0.1:5180/ -o /dev/null -w "ui %{http_code}\n" ``` 打开 。端到端不走 UI 也可以(**Git Bash**): ```bash curl -sN --noproxy '*' -X POST http://127.0.0.1:18000/api/ask \ -H "Content-Type: application/json" \ -d '{"question":"上个月已支付的订单里,销量最高的 10 个商品是哪些?","dialect":"mysql","user_id":"u_demo","thread_id":"demo01"}' ``` 从 `interrupt` 事件取 `approval_id`,再: ```bash curl -sN --noproxy '*' -X POST http://127.0.0.1:18000/api/resume \ -H "Content-Type: application/json" \ -d '{"thread_id":"demo01","approval_id":"<上一步的值>","decision":"approve","approver":"u_demo"}' ``` **PowerShell** 用 `Invoke-WebRequest` 或 `curl.exe`(注意 PowerShell 的 `curl` 别名是 `Invoke-WebRequest`,参数不兼容,显式写 `curl.exe`)。 推荐先试能过成本门的问题:`已支付订单里实付金额最高的 20 笔`、`10 月和 9 月已支付金额对比`、`上个月已支付的订单里销量最高的 10 个商品`。不带 `order_status=1` 的全表聚合会被拒,前端 F 区会解释原因。 ## 11. 评测体系 ### 分层 | 层 | 对象 | 调真模型 | 外部依赖 | 预算 | |---|---|---|---|---| | L1 单元 | 节点、纯函数、指纹 | 否 | 无 | <10s | | L2 契约 | 8 个 HTTP 接口的 JSON Schema | 否 | 无 | <5s | | L3 端到端 | 完整图 + 假模型回放 | 否 | 无(假网关) | <30s | | L3b SC-3 故障注入 | 自纠回路(收敛 / 止损 / 重试上限) | 否 | 无 | <5s | | L3c SC-4 抽检状态 | 人工审批记录的通过率 | 否 | 无 | <1s | | L4 评测 | Golden 集 50 条 | 是(结果可缓存) | 18000 / 18080 | <10min | **顺序纪律**:L1~L3 必须能在无 Key、无 Java、无 MySQL 时全部通过,否则每次改一行代码都要等外部依赖,评测很快就会被跳过。 **一条命令**(项目根目录,**Git Bash / PowerShell 同形**): ```bash orchestrator/.venv/Scripts/python.exe eval/run_all.py ``` L4 不在线会明确标 `SKIPPED` 并打印启动命令,**不会伪造指标**。逐条结果缓存在 `var/eval-cache/`,key 含模型名 + prompt 版本哈希;改指标算法不重烧模型,改 prompt 则自动失效。`--with-java` 额外跑 Java 网关单测(自动带 JDK 25 的 `JAVA_HOME`),`--skip-l4` 只跑离线层。 **L3b / L3c 是「测量通道」不是「指标值」**:前者用 `ScriptedLLM` 按剧本注入故障,验证自纠回路按设计工作(故意注入的不可恢复样本不进 SC-3 分母);后者读 `var/approval-samples.json` 的人工抽检记录,无记录时输出 `n/a` 而非编一个 100%。报告名带 prompt 版本,避免同日同提交改两次 prompt 时对照数据被覆盖。 ### Golden 集 50 条,分桶配额 `single 15 / agg 10 / join 10 / time 8 / group 5 / nested 2`(难桶 ≤30%)。每条含 `question` / `gold_sql` / `result_fingerprint` / `bucket` / `tables` / `dialect` / `order_matters` / `notes`。 **为什么比结果不比 SQL 文本**:同义 SQL 太多(`JOIN` vs 子查询、投影顺序不同),比文本会系统性低估准确率。指纹做法是:列名**不进哈希**(模型别名不可控)、行内按值排序、行间排序、数值统一 `n:` 前缀消掉 `int`/`float`/`Decimal` 的表示差异,再 sha256;TOP-N 题用 `order_matters` 保留名次(这是已知精度上限)。 **gold 指纹必须走与模型侧相同的网关链路**(`eval/build_golden.py` 对 `gold_sql` 也发 dry-run → execute)。若 gold 用 pymysql 直连,`LIMIT 200` 截断与数值序列化都会不一致,测出来的是测量误差。 另有 `eval/boundary.json` 12 条能力边界样本,验证「拒绝得可解释、不误执行」,**不计入 SC-1**。 ### 当前实测(2026-11-11 最新一轮,模型 `deepseek-chat`,prompt `53388149`,基准 `g8c05`) | 码 | 指标 | 实测 | 目标 | 判定 | |---|---|---|---|---| | SC-1 | 执行准确率(严格) | **0.86(43/50)** | ≥0.75 | ✅ 达标 | | SC-1' | 宽松(允许多投影列) | 0.90(45/50) | 参考值 | — | | SC-2 | 可执行率 | 1.00(50/50) | ≥0.92 | 达标 | | SC-3 | 自纠收敛率 | `n/a`(0 首轮失败) | ≥0.60 | 真链路样本不可测;已有离线故障注入通道 | | SC-4 | 审批通过率 | `n/a` | 0.85 区间 | 无真人审批记录,不编数字;已有人工抽检通道 | | SC-5 | P95 端到端 | 3248 ms | ≤20s | 达标 | | SC-6 | 干跑 P95 | 16 ms | ≤1.5s | 达标 | **一次修复带来的变化**:首次评测(2026-11-07)SC-1 严格 **0.46**、宽松 0.86,27 条失败里 20 条只是模型多 SELECT 了几列。给 `SQL_SYSTEM` 加「只投影问题明确要求的列」+ 注入当前日期后,同一套指标复测 **0.74**(修好 15 条、模型抖动变差 1 条,净 +14),多投影列 20 → 1、年份幻觉 2 → 0。宽松值反而从 0.86 降到 0.78,不是退化:语义等价的题被修成严格命中后这个「严格 + 语义等价」的和会自然下降。 随后补 schema digest 索引信息,SC-1 保持 0.74 无退化 —— 索引信息作用于**自纠路径**,不是首轮生成;针对性验证里自纠一次就把预估扫描从 161,281 降到 80,641 并通过成本门。 **两个 `n/a` 的处理**:SC-3 有 `eval/run_self_correct.py` 的离线故障注入样本(8/8 机制符合预期),SC-4 有 `eval/approval_rate.py` 的人工抽检通道;两者都**不能冒充真链路指标**,所以报告里仍标 `n/a` 并写明原因。 **0.74 → 0.86 是修基准,不是改模型。** 13 条失败逐条定性后发现 6 条是测量基准自己不合格:gold 擅自加 `LIMIT`(题面没要求)、题面用了「演示订单/演示商品」这类造数标记、题面歧义(「多少可售库存」可读成总和)。修完这 6 条后 **无一条回归**。剩余 7 条如实保留:2 条选列不同、2 条多投影(宽松已捞回)、2 条 TOP-N 并列(已知上限)、1 条样本设计缺陷(答案超 `max-rows: 200` 被截断)。逐条清单与「哪些允许动、哪些绝不动」的判据见 [G4 §12](./docs/G4-评测与交付.md)。 改题前后两次的逐题对比见 `eval/results/20261111-d371095-53388149-bc97.json`(0.74)与 `20261111-2166fb5-53388149-bc97-g8c05.json`(0.86);首次评测的 27 条归因与四个测量基准坑见 [G4 §9](./docs/G4-评测与交付.md)。 **样本集边界(引用数字时必须一起引用)**:这 50 条是「现有成本门能力范围内」的样本,不是任意业务问题的无偏抽样。不带 `order_status=1` 的全表聚合在 boundary 单独报告。 产物:`eval/results/<日期>-.json`(逐条明细 + 归因)、`.txt`(摘要)、`trends.csv`(每次一行趋势)。完整落地记录见 [G4 §9](./docs/G4-评测与交付.md)。 ## 12. 设计决策索引 决策日志共 **D-01~D-32**,每条记录「问题 / 选项 / 选择 / 理由 / 反悔条件」。分组摘要: | 主题 | 编号 | 结论摘要 | |---|---|---| | 架构 | D-02, D-04, D-05, D-06, D-08, D-09 | 三进程非微服务;接口按多库设计、实现只做 MySQL;JDK 25 + Python 3.14/uv;8 阶段压成 4 道闸门;详细设计改成切片内决策清单 | | 范围与指标 | D-01, D-03, D-10, D-11, D-12 | BM25 不上向量库;复用库存订单库;目标用户是业务同学;准确率 75% 不憋 85%;提问者与审批者同一人 | | 协议与契约 | D-13, D-15~D-22 | schema 用 GET+etag;`row` 一次性发;新增 session 快照;不做流内自动重连;`token` 只用于结论;JSON Schema 单一真源;Java 手写 record;生成器锁 Python 3.12 | | 安全与解耦 | D-14, D-23~D-26 | 干跑票据;身份透传 + 白名单分组 + 鉴权骨架;方言两轴解耦 + 审计独立库;单库可换但不做多库共存;白名单按解析器真实表名 | | 落地修正 | D-27~D-32 | 事件由传输层发、两个 status 枚举、审批人闭环;风险标签只信 EXPLAIN、错误码必须来自契约;成本门认边界、索引信息独立成片;前端 sticky 审批条与恢复时间轴;双口径准确率、SC-3/SC-4 不造数;修 prompt 后全量复测、索引信息必须同步 Etag、测量通道与指标值分离 | 三条最值得追问的: - **D-02 为什么不是单体**:安全防线与业务逻辑共享进程、一个 bug 同时失效;审计与业务共享事务边界会被回滚带走。 - **D-14 为什么必须凭票**:审批人看到的是「这条 SQL」,若执行时能换成另一条,审批就退化成形式主义。票据把审批与执行绑定到同一个 `sha256(sql)`。 - **D-31 为什么不把 0.46 修好看**:不调成本门阈值、不放宽评分口径、不删难题。27 条失败逐条归因后,D-32 用「修生成行为 + 同一套指标全量复测」把 0.46 提到 0.74,而不是改评分规则。 - **D-32 为什么修完先看回归再看涨幅**:修好 15 条的同时也会弄坏 1 条(模型抖动);只看涨幅会把回归藏在净收益里。同理,改了测量基准或样本集,必须先证明「没把别的东西弄坏」。 ## 13. 已知边界与路线图 | 项 | 现状 | 触发条件 / 备注 | |---|---|---| | G4 §6 快速开始 | ✅ 已回填 | 指向本 README §9~§10;干净目录新 clone 仍需人工验证一次(两个含密钥的本地文件不入库) | | SC-1 严格准确率 | **0.86,已达标** | 0.46 → 修 prompt 0.74 → 修基准 0.86。剩余 7 条如实失败(详见 G4 §12);不调阈值、不放宽评分、不删难题 | | Q1 schema digest 补索引 | ✅ 已完成 | 契约 `TableMeta.indexes` + Java 查 `information_schema.statistics` + Python digest + `Etag` 同步;真链路自纠 161281 → 80641 通过成本门 | | Q2 Java 侧契约 `pattern` | ✅ 已完成 | `IdentityGuard` 校验身份字段,契约一致性由测试读 JSON 断言;非法 `user_id` 现在返回 400 `E_UNAUTHORIZED` | | Q3 `RiskTag.cross_join` | ✅ 已完成 | `CartesianJoinDetector` 用 AST 检显式 CROSS JOIN / 无 ON 的 JOIN;逗号连接带 WHERE 的隐式情况明示为边界,不误报 | | SC-3 / SC-4 | 通道已建,值仍 `n/a` | 离线故障注入 8/8 验证回路;人工抽检模板 + 计算脚本待真人记录。**都不冒充真链路指标** | | Q4 审计表无只读回查账号 | 设计使然 | `nl2sql_ro` 无 `nl2sql_audit` 权限;要出审计报表需另授只读账号 | | 长期记忆 / 多轮 / 图表 / 多用户 | 未实现 | G1 §4 Out of Scope,均有触发条件 | | 票据与 checkpoint 存储 | 进程内 Map / 本地 SQLite | 多实例或容器化时需换 Redis / PostgresSaver(G4 §7.1) | | 模型 | `deepseek-chat` 别名 → 实际 `deepseek-flash` | `/models` 已不返回 `deepseek-chat`;别「顺手升级」到 `deepseek-v4-pro`(实测约 5.9s,慢约 5 倍) | **不为「感觉有点久」做性能优化**:实测端到端 P95 3472ms,SC-5 目标 ≤20s,余量约 4 倍。首屏 2.3 秒的干等来自 D-18(`token` 只用于结论)这个冻结决策,要改需先改决策、再补 SSE 事件。 ## 14. 故障排查 只收**真实踩过的坑**(G4 §7): | 现象 | 根因 | 处理 | |---|---|---| | 本地请求卡住 / 502 | 系统代理(7897 等)拦本地请求 | httpx 传 `trust_env=False` | | 生成 SQL 末尾带分号 | DeepSeek 自动补 | `clean_sql` 去掉,否则可能被判多语句 | | JOIN 全部被 `E_NOT_WHITELISTED` 拒 | `EXPLAIN` 的 `table_name` 是别名(`o` / `i`) | 改用 JSqlParser 解析真实表名(D-26) | | 审批条报「全表扫描」但 EXPLAIN 是 `ref` | 模型自报的 `risk` 会说假话 | 只用 `plan.risk`(EXPLAIN 测量),模型 risk 降级为离线评测数据(D-28) | | 限流被显示成 `E_INTERNAL` | 自造错误码在 `except` 块里触发契约校验失败 | `coerce_code` 收敛,只用契约枚举内的码 | | 解读写「结果已截断」但实际未截断 | 模板只在截断时加标记,省略被模型读成否定 | 改成显式肯定句「未截断(这是全部结果)」 | | 加时间范围后预估行数一字不降 | 该列无索引 | 成本门看的是扫描行数不是结果行数;补索引或认边界(Q1 / D-29) | | `ConnectionResetError [WinError 10054]` | 页面刷新 / 关闭导致客户端提前断连 | asyncio 回调无害,图仍在 checkpoint 里等人审批 | | 单测突然每条变 2 秒 | `.env` 落盘后 `llm_mode=deepseek`,测试真连模型 | conftest 用 autouse fixture 强制 fake(环境隔离) | | 刷新后时间轴只剩后半段 | 重放流只推 resume 之后的 step | 先用 session 快照的 `timings`/`sql` 初始化视图再挂流 | | Git Bash 的 `/tmp` 与 Windows Python 的 `\tmp` 不通 | MSYS 路径转换 | 脚本用 stdin heredoc 或绝对路径 | | `nohup` 起的 uvicorn 被收掉 | 脱离会话管理 | 用受管后台任务;长驻进程由使用者自己起 | | 前端起在 5173 被别的项目占用 | 端口冲突 | 本项目固定 5180 + `strictPort: true` | | 评测缓存全失效、L4 重跑 50 条 | 路径重构后 `run_eval.py` 的 `PROMPTS` 常量仍指向旧 `app/` 目录 | 缓存键依赖的外部路径也是重构的一部分 | ## 15. 文档索引 | 文档 | 内容 | |---|---| | **[docs/部署手册.md](./docs/部署手册.md)** | **部署专用**:调用链与端口、JDK/Python/Node 前置、数据库授权与审计表、配置项、构建、启动顺序、校验、升级回滚、单实例约束、安全清单、部署故障排查 | | [docs/接入对接单.md](./docs/接入对接单.md) | 给 ims 的接入约定:身份透传、探针语义、错误码四类映射、风险责任划分 | | [docs/README.md](./docs/README.md) | 四道闸门索引、仓库结构、端口对照 | | [G1 定范围](./docs/G1-定范围.md) | 目标用户、成功标准、FR 清单、范围边界 | | [G2 定形状](./docs/G2-定形状.md) | 拓扑与信任边界、界面 A~G、SSE 协议、错误码表 | | [G3 切片开发](./docs/G3-切片开发.md) | S1~S5 决策清单与落地记录 | | [G4 评测与交付](./docs/G4-评测与交付.md) | 测试分层、Golden 规范、指标定义、回归流程、§9 首次评测报告 | | [决策日志](./docs/决策日志.md) | D-01~D-31,每条能回答「当时为什么这么选」 | | [contracts/README.md](./contracts/README.md) | 契约为什么是断言而不是文档 | | [docs/archive/](./docs/archive/) | 2026-10-28 开做前的初始设想,⚠️ 已过时,只读归档 | --- 远程: 分支:`master`