# 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-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# docs 索引 · 四道闸门

单人开发，8 阶段压成 4 道闸门。压的是**文档份数**，不是决策顺序。

| 闸门 | 文件 | 何时过闸 | 状态 |
|---|---|---|---|
| G1 定范围 | [G1-定范围.md](./G1-定范围.md) | 目标用户 / 成功数字 / 审批者三题有答案 | ✅ 已过闸<br>用户=A 业务同学 · 准确率目标 75% · 审批者同一人 |
| G2 定形状 | [G2-定形状.md](./G2-定形状.md) | SSE 事件表能倒推出界面区块；`SqlDialect` 与 State 已冻结 | ✅ 已定稿<br>8 事件 / 6 接口 / 3 冻结结构 · 契约已机器化 |
| G3 切片开发 | [G3-切片开发.md](./G3-切片开发.md) | 每个切片动工前填「决策清单」，随代码提交 | ✅ S1~S4 全部落地，S5 决策清单 10 条<br>Java 54 / Python 30 / 契约 27 断言 |
| G4 评测与交付 | [G4-评测与交付.md](./G4-评测与交付.md) | 一条命令跑出指标表 + 新人按手册能跑通 | 🟡 首次 L4 已完成（§9）<br>SC-1 严格 0.46 **未达 75%**；§6 快速开始手册待补 |
| — 活动文件 | [决策日志.md](./决策日志.md) | 全程随手记，不设过闸 | 🟢 D-01~D-31 持续 |

## 仓库结构地图

| 目录 | 职责 | 关键入口 |
|---|---|---|
| `contracts/` | **契约单一真源**（机器读）：JSON Schema → 生成 `contracts_py/` 与 `contracts.d.ts` | `validate.py`（27 例）、`generate.sh` |
| `gateway/` | Java 数据网关：白名单 / 单语句 / EXPLAIN 成本门 / 一次性票据 / 只读执行 / 独立审计库 | Spring Boot 3.5.7 · JDK 25 |
| `orchestrator/` | Python 编排层：FastAPI + LangGraph 10 节点图、SSE、checkpoint、真/假模型 | `app/main.py` · `.env.example` |
| `ui/` | Vue3 前端：A~G 区块、SSE 消费、审批交互、结果表与流式结论 | `src/App.vue` · `vite.config.ts` |
| `eval/` | G4 评测：Golden 集、能力边界样本、指纹、L1~L4 回归 | `run_all.py` · `golden.json` · `results/` |
| `tools/` | 开发辅助脚本（与产品运行时无关） | `seed_demo_data.py` 演示数据播种/回滚 |
| `docs/` | 四道闸门、决策日志、历史归档（人类读） | 本文件 |

文档负责「为什么这么定」，`contracts/` 负责「这么定之后怎么被强制」。两者不能互相替代：文档不会让测试变红，schema 不会解释取舍。

**一条命令跑 L1~L4**（项目根目录）：

```bash
orchestrator/.venv/Scripts/python.exe eval/run_all.py
```

L1~L3 无需外部依赖；L4 需要网关与编排层在线，不在线会明确标 `SKIPPED` 并打印启动命令，不会伪造指标。

## 端口：设计值与本地演示值

G2 §1.3 / G4 §6 记的是**设计定稿值** `8080 / 8000 / 5173`。本机因其他项目长期占用 5173、且为避免与 WorkBuddy 端口碰撞，实际演示改用：

| 进程 | 设计值 | 本地演示值 |
|---|---|---|
| Java 网关 | 8080 | **18080** |
| Python 编排 | 8000 | **18000** |
| Vue 前端 | 5173 | **5180** |

`orchestrator/.env` 与 `ui/vite.config.ts` 按演示值配置；改设计端口时两处与文档要一起改。

## 三条不可压缩项

1. **接口契约与 State schema 必须在 G2 冻结**——三进程跨语言，改一次伤筋动骨。
2. **Golden 集要早于评测攒完**——已落地 50 条（分桶 15/10/10/8/5/2，每条有真实结果指纹），不是临时凑题。
3. **决策日志全程写**——面试追问「为什么不上向量库」时，靠当时记录的原始理由。

## 已归档

- 原 8 阶段骨架（00~07）已合并进四份闸门文档，原件于 2026-10-29 删除（见 D-08）。
- [archive/项目交接文档-2026-10-28.md](./archive/项目交接文档-2026-10-28.md)：开做前的**初始设想**，⚠️ **已过时**。其中 MyBatis、JDK 21、conda/Python 3.13、`deepseek-flash` 不可用、长期记忆 Store 等说法已被 D 系列决策推翻或实现阶段否决。**只读归档，不可当现状使用**；判断现状以四道闸门 + 决策日志为准。