# sql-assistant

**Repository Path**: superBigHuang/sql-assistant

## Basic Information

- **Project Name**: sql-assistant
- **Description**: 自然语言sql查询
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-21
- **Last Updated**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SQL 助手

基于 LLM 的智能 SQL 查询助手，支持自然语言转 SQL、流式输出、数据分析与案例沉淀。

## 功能特性

- **自然语言转 SQL**：通过讯飞星火大模型将业务问题转换为标准 SQL
- **两阶段处理**：第一跳规范化问题，第二跳生成 SQL，Prompt 精简到 ≤5000 字符
- **wiki 知识库驱动**：所有业务规则从 wiki 动态加载，代码无硬编码
- **精准检索**：基于规范化 JSON 检索，表≤3张，规则≤2条
- **流式输出**：SSE 实时推送思考过程与 SQL 生成进度
- **三层安全校验**：关键字黑名单 + 查询类型白名单 + 执行限制
- **数据分析**：自动统计数值列、检测异常值
- **案例沉淀**：将优质查询案例回存知识库

## 系统架构

![系统整体架构图](img/系统整体架构图.png)

![两阶段处理流程图](img/两阶段处理流程图.png)

![查询处理流程图](img/查询处理流程图.png)

### 两阶段架构

| 阶段 | 模型 | 职责 | Prompt 预算 |
|------|------|------|------------|
| 第一跳 | 小模型/轻量模型 | 问题规范化，输出结构化 JSON | < 1000 字符 |
| 第二跳 | 讯飞星火 | 基于 JSON + 精简知识生成 SQL | ≤ 5000 字符 |

**规范化 JSON 示例**：
```json
{
  "entity": "订单",
  "filters": [
    {"field_hint": "业务类型", "operator": "eq", "value": "海运"},
    {"field_hint": "创建人", "operator": "eq", "value": "黄能"}
  ],
  "return_fields": ["订单号", "创建日期"],
  "limit_hint": 100
}
```

## 核心原则

| 原则 | 说明 |
|------|------|
| **Prompt 从 wiki 构建** | 禁止在代码中硬编码任何业务规则、字段映射、表名、SQL 模板 |
| **校验只做技术检查** | 检查表名/字段是否存在（查 information_schema），不做业务层面修正 |
| **错误透明化** | LLM 生成的 SQL 有错误直接报错返回，不静默修正 |
| **wiki 是唯一知识源** | 新增业务规则只需编辑 wiki，无需修改代码 |

详见 [CLAUDE.md](CLAUDE.md) 禁止事项清单。

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | React + TypeScript + Vite + Tailwind CSS 4 + Framer Motion |
| 后端 | FastAPI + Python 3.10+ |
| LLM | 讯飞星火 (OpenAI 兼容格式) |
| 知识检索 | wiki 规则文件直读 + 关键词匹配 |
| 数据库 | SQL Server (pymssql) |

## 项目结构

```
sql-assistant/
├── app/                        # FastAPI 应用
│   ├── main.py                 # 入口，CORS 配置
│   └── routers/
│       └── query.py            # API 路由
├── core/                       # 核心模块
│   ├── query_normalizer.py     # 查询规范化器（第一跳）
│   ├── rag_retriever.py        # RAG 检索器（关键词匹配 + wiki 规则直读）
│   ├── sql_executor.py         # SQL 执行器（技术性校验）
│   ├── data_analyzer.py        # 数据分析器
│   └── case_recorder.py        # 案例回存器
├── security/                   # 安全模块
│   └── interceptor.py          # 三层安全拦截器
├── llm_gateway/                # LLM 网关
│   └── spark_client.py         # 讯飞星火客户端（Prompt 从 wiki 构建）
├── frontend/                   # React 前端
│   ├── src/
│   │   ├── App.tsx             # 主应用
│   │   ├── components/ui/
│   │   │   └── ai-chat.tsx     # AI 对话组件
│   │   └── main.tsx            # 入口
│   └── vite.config.ts          # Vite 配置
├── utils/                      # 工具模块
│   ├── logger.py               # 日志工具
│   └── formatter.py            # 格式化工具
├── config/                     # 配置
│   └── settings.py             # 配置管理
├── platforms/                  # 平台适配 (飞书/Discord)
├── scripts/                    # 脚本
├── img/                        # 架构图
└── requirements.txt            # Python 依赖
```

## 快速开始

### 1. 环境准备

```bash
# 克隆项目
cd D:\cloud_file\test\sql-assistant

# 创建虚拟环境
python -m venv venv
venv\Scripts\activate

# 安装后端依赖
pip install -r requirements.txt

# 安装前端依赖
cd frontend
npm install
```

### 2. 配置

在 `config/settings.py` 中配置：

```python
# 数据库配置
DB_HOST = "192.168.252.10"
DB_PORT = 1433
DB_NAME = "khwl"

# LLM 配置
SPARK_API_KEY = "your-api-key"
SPARK_BASE_URL = "https://maas-api.cn-huabei.xfyun.cn/v1"
```

### 3. 启动服务

```bash
# 启动后端 (端口 8000)
uvicorn app.main:app --reload

# 启动前端 (端口 3000)
cd frontend
npm run dev
```

> wiki 规则文件直读，无需初始化向量库。RAG 检索器启动时自动加载知识库目录。

访问 http://localhost:3000

## API 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/query` | 普通查询 |
| POST | `/api/query/stream` | 流式查询 (SSE) |
| POST | `/api/validate-sql` | SQL 安全校验 |
| POST | `/api/save` | 案例沉淀 |
| GET | `/api/tables` | 获取表列表 |
| GET | `/api/health` | 健康检查 |

## 查询流程

```
用户问题 → LLM规范化(第一跳) → 精准检索 → Prompt构建 → LLM生成SQL(第二跳) → 安全校验 → 执行查询 → 数据分析 → 前端展示
```

### Prompt 结构（基于规范化结果构建）

```
## 结构化查询意图
entity: 订单
filters: [{业务类型=海运}, {创建人=黄能}]
return_fields: [订单号, 创建日期]

## 相关表结构（≤3张）
### BZ_ORDER_HEAD
| 字段名 | 类型 | 说明 |
...

## 相关术语/枚举规则（≤2条）
- "海运" → FIRST_CATEGORY = '1'

## 相关案例（≤1个）
...

## 原始问题（兜底）
黄能最近创建的海运出口订单
```

### SSE 事件类型

| 事件 | 说明 |
|------|------|
| `normalized_query` | 规范化结果（第一跳输出） |
| `rag_result` | RAG 检索结果 |
| `llm_input` | LLM 输入内容 |
| `sql_chunk` | SQL 片段 (流式) |
| `validate_result` | 校验结果 |
| `stage` | 阶段进度 |
| `result` | 最终结果 |

## 安全校验

三层校验机制：

| 层级 | 检查内容 | 示例 |
|------|---------|------|
| 关键字黑名单 | 禁止危险操作 | INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, EXEC, GRANT, REVOKE, MERGE |
| 查询类型白名单 | 仅允许安全查询 | SELECT ✓, WITH ✓, 其他 ✗ |
| 执行限制 | 防止资源滥用 | 结果集上限 500 条，执行超时 30 秒，禁止 SQL 注释 |

## 知识库架构

![知识库三层架构图](img/知识库三层架构图.png)

```
SqlKnowledgeVault/
│
├── db-schema/                    # 原始资料层：表结构文档
│   ├── BZ_ORDER_HEAD.md         # 每张表一个文件，含双向链接
│   ├── OA_AllStaff.md
│   └── ... (978 张表)
│
├── sql-rule/                     # 原始资料层：业务规则
│   ├── sql-编写规范.md
│   ├── 业务类型与状态码对照.md
│   └── 表关联关系.md
│
├── sql-examples/                 # 案例层：沉淀的优质案例
│   └── {YYYY-MM-DD}.md
│
├── wiki/                         # 规则层：按两阶段职责拆分
│   ├── prompts/
│   │   ├── query-normalization.md
│   │   └── sql-generation.md
│   ├── normalization/
│   │   ├── business-type-split.md
│   │   ├── latest-limit-rule.md
│   │   ├── person-name-semantics.md
│   │   └── time-expression-semantics.md
│   ├── retrieval/
│   │   ├── entity-mapping.md
│   │   ├── keyword-mapping.md
│   │   └── enum-mapping.md
│   └── sql/
│       ├── person-role-join.md
│       └── time-field-selection.md
│
└── schema/                       # 规范层：元数据规范
    └── METADATA.md
```

### 各层职责

| 层级 | 目录 | 职责 | 维护方式 |
|-----|------|------|---------|
| 原始资料层 | db-schema/, sql-rule/ | 存储表结构和业务规则 | 手动维护 |
| 规则层 | wiki/prompts/ | Prompt 模板 | 手动维护 |
| 规则层 | wiki/normalization/ | 第一跳语义规范化规则 | 手动维护 |
| 规则层 | wiki/retrieval/ | 精准检索映射规则 | 手动维护 |
| 规则层 | wiki/sql/ | 第二跳 SQL 生成规则 | 手动维护 |
| 案例层 | sql-examples/ | 存储优质 SQL 案例 | 手动沉淀 |
| 规范层 | schema/ | 定义元数据规范 | 手动维护 |

### 双向链接

wiki 文件通过 Obsidian 双向链接 `[[文件名]]` 关联：

```markdown
# wiki 中引用表名
- 订单表 [[BZ_ORDER_HEAD]]
- 用户表 [[OA_AllStaff]]

# 表结构中引用关联表
| create_user | varchar(100) | NO | 创建人 [[OA_AllStaff]] |
```

双向链接用于知识导航和 RAG 检索增强。

## 开发

### 运行测试

```bash
# 后端测试
pytest

# 前端测试
cd frontend
npx playwright test
```

### 代码规范

```bash
# Python
black .
isort .

# TypeScript
npm run lint
```

## 扩展规则

新增业务规则无需修改代码：

1. 按规则职责编辑 `SqlKnowledgeVault/wiki/normalization/`、`retrieval/`、`sql/` 下对应 `.md` 文件
2. wiki 文件保存后自动生效，无需初始化向量库

## 相关文档

- [CLAUDE.md](CLAUDE.md) - 项目规范与禁止事项清单
- [doc/需求/LLM-wiki知识库重构/](doc/需求/LLM-wiki知识库重构/) - wiki 知识库重构设计文档
- [doc/需求/查询前置规范化层方案/](doc/需求/查询前置规范化层方案/) - 两阶段架构设计文档

## License

MIT