# Chat2DB

**Repository Path**: zhuohaibin/chat2-db

## Basic Information

- **Project Name**: Chat2DB
- **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-07-28
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Chat2DB

基于 AgentScope Java v2 的自然语言转 SQL 系统，技术栈为 Java 25、Spring Boot 4.1、Vue 3 和 TypeScript。

当前已实现：

- 从 MySQL `information_schema` 检索与问题相关的 Schema；
- 使用 AgentScope + DashScope 生成结构化 SQL；
- 通过 AgentScope Toolkit 按需调用 `search_business_semantics`、`search_tables`、`get_table_schema` 和 `explain_sql`；
- 使用 DashScope `text-embedding-v4` 和 Milvus 建立版本化业务语义知识库，以混合重排消除字段、枚举和自然日口径歧义；
- 支持按请求启停知识 Tool、自动运行知识 OFF/ON A/B，并统计 Recall@K、规则采用率和词法降级率；
- 支持知识版本发布、停用、历史查询和回滚，变更自动同步当前 Milvus 向量；
- 对零命中、低置信度和同类型冲突触发 AgentScope 原生 HITL，使用 `ConfirmResult` 跨重启恢复 SQL 生成；
- 将重复人工选择沉淀为待审核知识草稿，不自动污染线上知识；
- 将成功执行且人工审核的查询晋升为 SQL 示例，保存 Schema 指纹并持久化到 Redis/Milvus；
- 通过 `search_sql_examples` Tool 做同 Schema 的示例召回和向量/词法两阶段重排，支持 zero-shot/few-shot A/B；
- 通过结构化 EXPLAIN 反馈驱动 Agent 自动修复 SQL，保留初始候选和最多两轮修复轨迹；
- 通过 Middleware 将模型、工具和 Token 事件实时推送到前端，并支持按会话中断 Agent；
- 启用 AgentScope `OtelTracingMiddleware` 和 OpenTelemetry SDK，记录 Agent → Model/Tool 父子 Span、耗时、重试配置及 Trace ID；
- 内置 `kf-20251105` 可复现评测集，以基准 SQL/候选 SQL 的真实结果集判断正确率，并对比 Generator 单 Agent与可选 Reviewer 双 Agent 的 Token 和延迟；
- 支持 1–5 次重复评测、失败类型分布、Token/延迟标准差、关键 SQL 语义断言，以及同用例同模式的历史基线回归判定；
- 将模型、Prompt、业务知识、SQL 示例、评测集和功能开关冻结为 Agent 配置快照；
- 只有绑定快照的评测报告通过正确率、可执行率、Token、延迟和语义干扰门禁后才能发布，支持稳定版本回滚；
- 使用 JSqlParser 拦截非只读、多语句和越权表访问；
- 自动执行 MySQL `EXPLAIN`，根据扫描行数和执行计划决定是否允许执行；
- 使用 AgentScope Permission Engine 的 `ASK` 规则暂停查询，批准后通过 `ConfirmResult` 恢复 Agent 并执行；
- 前端展示 SQL、EXPLAIN 计划、风险提示和动态结果表格；
- 查询成功后由独立的无数据库 Tool Analysis Agent 生成带行列证据的洞察、异常、建议追问和安全图表；
- 分析输入自动脱敏、截断并限制预算，输出再经确定性数值引用校验；Analysis 评测已纳入配置发布门禁；
- 记录生成、校验、EXPLAIN、授权决定、执行结果及耗时，并将审计持久化到 Redis；
- 使用 Redis DB 8 保存 AgentScope 会话状态。
- 使用固定 session ID 支持会话切换、对话历史、连续追问和服务重启后的上下文续接。
- 对 DashScope 模型、Embedding、Milvus 和 Redis 设置独立 bulkhead、有限重试与熔断；Redis 中断时 AgentState 可临时切换到进程内副本。

## 项目架构

```mermaid
flowchart LR
    U["浏览器 / API 调用方"] --> WEB["Vue 3 + Vite"]
    WEB --> REST["REST 接口层"]
    REST --> APP["应用编排层"]
    APP --> DOMAIN["领域模型与端口"]
    INFRA["基础设施适配器"] --> DOMAIN
    INFRA --> AGENT["AgentScope + DashScope"]
    INFRA --> MYSQL["业务 MySQL"]
    INFRA --> REDIS["Redis DB 8"]
    INFRA --> MILVUS["Milvus"]
    APP --> AUDIT["审计 / Trace / 评测"]
    AUDIT --> REDIS
```

后端采用接近六边形架构的分层方式：应用层依赖领域端口，基础设施层实现端口，接口层只负责 HTTP 协议转换和参数校验。

```text
chat2-db/
├─ pom.xml                         Maven 聚合工程
├─ chat2-db-server/                Java 25 + Spring Boot 后端
│  └─ src/main/
│     ├─ java/com/chat2db/
│     │  ├─ interfaces/rest/       REST、SSE 和异常处理
│     │  ├─ application/           用例编排、会话、审计、评测和发布
│     │  ├─ domain/                领域模型与基础设施端口
│     │  └─ infrastructure/        Agent、MySQL、Redis、Milvus 等适配器
│     └─ resources/
│        ├─ application.yml        默认配置
│        ├─ semantic/              内置业务语义知识
│        └─ evaluation/            内置评测集
├─ chat2-db-web/                   Vue 3 + TypeScript 单页应用
└─ docs/                           系统设计与真实链路验证记录
```

主要分层职责：

| 分层 | 目录 | 职责 |
| --- | --- | --- |
| 接口层 | `interfaces/rest` | 暴露 `/api/v1/**`，转换请求和响应，不实现数据库访问 |
| 应用层 | `application` | 编排 Schema、Agent、语义知识、校验、EXPLAIN、授权、审计和评测 |
| 领域层 | `domain` | 定义业务对象及 `TextToSqlGenerator`、`QueryExecutionGateway` 等端口 |
| 基础设施层 | `infrastructure` | 实现 AgentScope、JDBC、Redis、Milvus、JSqlParser 和 OpenTelemetry 集成 |

自然语言转 SQL 的主链路如下：

```mermaid
sequenceDiagram
    participant UI as 前端
    participant APP as TextToSqlService
    participant KB as 语义知识
    participant DB as MySQL Tools
    participant AG as AgentScope Agent
    participant SAFE as 安全校验
    participant STORE as 审计 / Redis

    UI->>APP: 问题、catalog、sessionId
    APP->>KB: 语义预检与 SQL 示例召回
    KB-->>APP: 向量/词法证据或语义确认请求
    APP->>DB: 检索候选 Schema
    APP->>AG: 问题 + 授权 Schema + 语义证据
    AG->>DB: search_tables / get_table_schema
    AG->>SAFE: explain_sql
    SAFE-->>AG: 风险与修复建议
    AG-->>APP: 结构化 SQL
    APP->>SAFE: JSqlParser 校验 + 最终 EXPLAIN
    APP->>STORE: 保存证据链和会话状态
    APP-->>UI: READY / REJECTED / 等待确认
```

只有通过 Schema 白名单、单条只读 `SELECT` 校验和真实 `EXPLAIN` 的结果才能进入执行授权；实际查询仍需要人工确认。

详细架构见 [系统设计文档](docs/text-to-sql-system-design.md)，真实业务库验证见 [`kf-20251105` 验证记录](docs/verification-kf-20251105.md)、[EXPLAIN 自动修复验证](docs/verification-explain-repair.md) 和 [OpenTelemetry 验证](docs/verification-opentelemetry.md)，后续学习迭代见 [AgentScope Java v2 路线图](docs/next-phase-agentscope-learning-roadmap.md)。

## 开发与启动指南

### 1. 环境要求

- JDK 25；
- Maven 3.8.8+；
- Node.js 20.19+ 和 npm 10+；
- Docker Desktop；
- 完整 Agent 模式需要 DashScope API Key。

确认 Java 和 Maven 使用同一个 JDK 25。若 `mvn -version` 仍显示 Java 17，在当前 PowerShell 中执行：

```powershell
$env:JAVA_HOME='C:\Program Files\Java\jdk-25.0.3'
$env:Path="$env:JAVA_HOME\bin;$env:Path"
mvn -version
```

### 2. 启动外部依赖

默认配置依赖以下本地服务：

| 依赖 | 地址 | 用途 | 故障行为 |
| --- | --- | --- | --- |
| MySQL | `127.0.0.1:3378` | Schema、EXPLAIN、查询执行 | 核心数据库能力不可用 |
| Redis | `127.0.0.1:6379`，DB 8 | 会话、AgentState、审计和评测 | 短时降级到进程内状态 |
| Milvus | `127.0.0.1:19530` | 业务知识和 SQL 示例向量召回 | 降级为词法检索 |

已有容器可以直接启动：

```powershell
docker start mysql
docker start redis
docker start milvus-standalone
docker ps
```

验证 Redis 和 Milvus：

```powershell
docker exec redis redis-cli -a superman -n 8 ping
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:9091/healthz
```

Milvus WebUI 地址为 `http://127.0.0.1:9091/webui/`。项目不包含 `kf-20251105` 的建库 SQL，运行完整业务验证前应确保目标 MySQL 已存在该 catalog 和测试数据。

### 3. 配置运行参数

完整 Agent 模式需要在启动后端的同一个 PowerShell 中设置：

```powershell
$env:DASHSCOPE_API_KEY='你的 DashScope API Key'
```

不要将真实密钥提交到 Git。数据库和 Redis 配置位于 `chat2-db-server/src/main/resources/application.yml`，也可以使用 Spring Boot 环境变量覆盖：

```powershell
$env:CHAT2DB_DATA_SOURCE_JDBC_URL='jdbc:mysql://127.0.0.1:3378/'
$env:CHAT2DB_DATA_SOURCE_USERNAME='root'
$env:CHAT2DB_DATA_SOURCE_PASSWORD='你的 MySQL 密码'
$env:CHAT2DB_REDIS_STATE_PASSWORD='你的 Redis 密码'
```

### 4. 启动后端

在仓库根目录执行：

```powershell
$env:JAVA_HOME='C:\Program Files\Java\jdk-25.0.3'
$env:Path="$env:JAVA_HOME\bin;$env:Path"
$env:DASHSCOPE_API_KEY='你的 DashScope API Key'
mvn -pl chat2-db-server spring-boot:run
```

后端默认监听 `http://localhost:8080`。可以通过以下接口检查状态：

```powershell
Invoke-RestMethod http://localhost:8080/actuator/health
Invoke-RestMethod http://localhost:8080/api/v1/semantic-knowledge/status
Invoke-RestMethod http://localhost:8080/api/v1/data-sources/local/catalogs
```

只开发页面或接口编排时，可以使用 Stub 模式避免调用真实模型：

```powershell
$env:CHAT2DB_AGENT_MODE='stub'
$env:CHAT2DB_KNOWLEDGE_BASE_ENABLED='false'
mvn -pl chat2-db-server spring-boot:run
```

### 5. 启动前端

新开一个 PowerShell：

```powershell
Set-Location chat2-db-web
npm install
npm run dev
```

浏览器访问 `http://localhost:5173`，Vite 会将 `/api` 代理到后端 `8080` 端口。

### 6. 测试与构建

```powershell
# 仓库根目录：运行后端测试
mvn test

# 前端目录：类型检查和生产构建
Set-Location chat2-db-web
npm run typecheck
npm run build
```

## 核心 API

- `POST /api/v1/text2sql/generate`：生成、校验 SQL 并自动运行 EXPLAIN；
- `POST /api/v1/queries/{requestId}:request-approval`：触发 `execute_query`，收到 AgentScope `RequireUserConfirmEvent` 后暂停；
- `POST /api/v1/queries/{requestId}:confirm`：提交 `{ "approved": true|false }`，使用 `ConfirmResult` 恢复或拒绝 Agent；
- `POST /api/v1/queries/{requestId}:analyze`：分析已成功执行且已脱敏的结果集；
- `GET /api/v1/queries/{requestId}/analysis`：读取已缓存的结构化结果洞察；
- `POST /api/v1/analysis-evaluations/runs`：评测引用可信率、图表正确率和外部 Tool 隔离；
- `GET /api/v1/resilience`：查看模型、Embedding、Milvus、Redis 的并发、重试、熔断和等待指标；
- `GET /api/v1/audits/{requestId}`：查看单次查询审计；
- `GET /api/v1/audits?limit=50`：查看最近审计记录；
- `GET /api/v1/data-sources/local/catalogs`：获取业务库列表。
- `POST /api/v1/conversations`：新建固定查询会话；
- `GET /api/v1/conversations`：查询当前用户的持久化会话目录；
- `GET /api/v1/conversations/{sessionId}`：读取会话和历史轮次。
- `GET /api/v1/evaluations/cases`：读取不含基准 SQL 的评测用例；
- `POST /api/v1/evaluations/runs`：运行单 Agent 或 Generator + Reviewer 评测；
- `GET /api/v1/evaluations/runs/{runId}`：读取 Redis 中的评测报告。
- `GET /api/v1/semantic-knowledge/status`：读取 Milvus collection、embedding 模型和同步状态；
- `GET /api/v1/semantic-knowledge/entries?catalog=...`：读取版本化业务语义规则；
- `POST /api/v1/semantic-knowledge/search`：执行 DashScope Embedding + Milvus 混合检索；
- `POST /api/v1/semantic-knowledge/sync`：重新向量化并同步内置知识。
- `POST /api/v1/semantic-knowledge/entries`：发布一个知识版本并同步 Milvus；
- `POST /api/v1/semantic-knowledge/entries/{id}/deactivate`：停用规则；
- `GET /api/v1/semantic-knowledge/entries/{id}/versions`：查看版本历史；
- `POST /api/v1/semantic-knowledge/entries/{id}/rollback?version=...`：回滚并重新同步向量。
- `POST /api/v1/text2sql/{requestId}/semantic-confirmation`：提交语义选择并恢复暂停的 Agent；
- `GET /api/v1/semantic-knowledge/drafts?catalog=...`：读取人工确认形成的待审核草稿。
- `POST /api/v1/sql-examples/from-audit/{requestId}`：将成功执行的查询人工审核为 SQL 示例；
- `GET /api/v1/sql-examples?catalog=...`：查看 SQL 示例；
- `POST /api/v1/sql-examples/{id}/deactivate`：停用 SQL 示例。
- `POST /api/v1/agent-configurations`：冻结当前 Agent 配置候选；
- `POST /api/v1/agent-configurations/{id}/gate?runId=...&analysisRunId=...`：使用 SQL 与 Analysis 绑定报告执行发布门禁；
- `POST /api/v1/agent-configurations/{id}/publish?runId=...&analysisRunId=...`：发布通过门禁的稳定配置；
- `POST /api/v1/agent-configurations/{id}/rollback`：回滚到历史稳定配置。

## 业务语义知识库

位于 `chat2db.knowledge-base`：

- `milvus-endpoint`：Milvus REST 地址，默认 `http://127.0.0.1:19530`；
- `collection`：向量集合名，默认 `chat2db_business_semantics`；
- `embedding-model`：DashScope 向量模型，默认 `text-embedding-v4`；
- `dimension`：向量维度，默认 1024；
- `top-k`：提供给 Agent 的最大知识条数，默认 5；
- `api-key`：默认读取环境变量 `DASHSCOPE_API_KEY`。
- `clarification-confidence-threshold`：低于该相似度触发 HITL，默认 0.60；
- `conflict-score-delta`：同类型候选分差不超过该值时视为冲突，默认 0.05。

内置规则位于 `chat2-db-server/src/main/resources/semantic/kf-20251105.json`。Milvus 不可用时会降级到词法检索，并在 API 和页面明确标记 `LEXICAL_FALLBACK`。

## 查询保护参数

位于 `chat2db.query`：

- `max-rows`：最多返回行数，默认 1000；
- `timeout-seconds`：查询超时，默认 30 秒；
- `max-estimated-rows`：EXPLAIN 单节点最大预估扫描行数，默认 100000；
- `max-full-scan-rows`：允许全表扫描的最大预估行数，默认 10000；超过后触发 Agent 修复；
- `max-result-bytes`：结果集最大估算字节数，默认 5 MiB。

## 验证

```powershell
mvn test
cd chat2-db-web
npm run build
```

会话、AgentState、待授权工具调用和查询审计均写入 Redis DB 8，可在服务重启后继续授权流程。真实验证见 [Permission/HITL 验证记录](docs/verification-hitl-permission.md)。

Agent 可观测性默认通过 `chat2db.observability.enabled=true` 启用。页面中的 OpenTelemetry 瀑布图和查询审计会保存 Trace ID、Span ID、阶段耗时、Token、工具授权摘要、结束原因及错误状态。

评测工作台默认允许 Reviewer 实验，可通过 `chat2db.evaluation.reviewer-enabled` 关闭，并通过 `max-cases-per-run` 控制单次评测规模。Reviewer 没有数据库 Toolkit 和 SQL 执行权限，只输出结构化语义审查意见；基准 SQL 和内部语义断言不通过评测集 API 暴露给前端。完整结果见 [P7 评测验证](docs/verification-evaluation-reviewer.md) 和 [P8 持续评测验证](docs/verification-continuous-evaluation.md)。

P9 Milvus 语义检索、AgentScope Tool 调用、混合重排和审计验证见 [业务语义知识库验证](docs/verification-semantic-knowledge.md)。

P10 请求级知识开关、RAG A/B 指标与版本治理验证见 [知识评测与治理验证](docs/verification-knowledge-evaluation-governance.md)。

P11 AgentScope 语义 HITL、Redis 跨重启恢复和反馈草稿验证见 [语义 HITL 验证](docs/verification-semantic-hitl.md)。