# QueryCraft

**Repository Path**: linxiaowen-928/QueryCraft

## Basic Information

- **Project Name**: QueryCraft
- **Description**: QueryCraft 是一个工业化级别的自然语言到 SQL 转换引擎，让用户用自然语言描述查询需求，自动生成对应的 SQL 语句
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-06
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QueryCraft - 自然语言转 SQL 引擎

**独立可运行的自然语言到 SQL 转换系统**

[![GitHub](https://img.shields.io/github/v/tag/linxiaowen-928/QueryCraft?label=version)](https://github.com/linxiaowen-928/QueryCraft)
[![License](https://img.shields.io/github/license/linxiaowen-928/QueryCraft)](https://github.com/linxiaowen-928/QueryCraft/blob/main/LICENSE)

## 📋 项目概述

QueryCraft 是一个工业化级别的自然语言转 SQL 引擎，支持：
- 🗣️ 自然语言查询输入
- 📊 多种数据库方言 (MySQL, PostgreSQL, Hive, Spark, Flink, Iceberg)
- 🔍 智能 Schema 理解与自动发现
- ✅ SQL 验证与评分
- 📈 持续学习与优化
- 🧠 基于 ZhipuAI / DeepSeek / OpenAI

## 🏗️ 架构

```
┌─────────────────────────────────────────────────────────────┐
│                      用户界面层                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Web UI     │  │   REST API   │  │     CLI      │      │
│  │  (React)     │  │  (FastAPI)   │  │  (Command)   │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                          │
┌─────────────────────────────────────────────────────────────┐
│                      核心引擎层                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ NL Parser    │  │ SQL Generator│  │  Validator   │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Schema Store │  │Context Engine│  │   Scorer     │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│  ┌──────────────┐  ┌──────────────┐                         │
│  │Learning Svc  │  │ Query History│                         │
│  └──────────────┘  └──────────────┘                         │
└─────────────────────────────────────────────────────────────┘
                          │
┌─────────────────────────────────────────────────────────────┐
│                      数据源层                                │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐    │
│  │ MySQL  │ │  Hive  │ │ Spark  │ │ Flink  │ │ Iceberg│    │
│  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘    │
└─────────────────────────────────────────────────────────────┘
                          │
┌─────────────────────────────────────────────────────────────┐
│                      AI 模型层                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   ZhipuAI    │  │  DeepSeek    │  │   OpenAI     │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
```

## 📁 目录结构

```
querycraft/
├── backend/                 # Python FastAPI 后端
│   ├── app/
│   │   ├── api/            # API 路由 (routes.py)
│   │   ├── core/           # 核心引擎
│   │   ├── models/         # 数据模型
│   │   ├── services/       # 业务服务
│   │   │   ├── generator.py           # SQL 生成
│   │   │   ├── learning_service.py    # 学习服务
│   │   │   ├── schema_discovery.py    # Schema 发现
│   │   │   └── query_history.py       # 查询历史
│   │   └── config.py       # 配置
│   ├── tests/
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/               # React Web UI (计划中)
│   ├── src/
│   ├── public/
│   ├── package.json
│   └── Dockerfile
├── cli/                    # 命令行工具
│   └── qc.py
├── .github/                # GitHub Actions & Templates
│   ├── ISSUE_TEMPLATE/
│   └── workflows/
├── docker-compose.yml
├── README.md
└── ROADMAP.md
```

## 🚀 快速开始

### 方式一：Docker 启动（推荐）

```bash
# 克隆项目
git clone https://github.com/linxiaowen-928/QueryCraft.git
cd QueryCraft

# 使用 Docker 启动
docker-compose up -d

# 查看日志
docker-compose logs -f
```

### 方式二：手动启动

```bash
# 克隆项目
git clone https://github.com/linxiaowen-928/QueryCraft.git
cd QueryCraft/backend

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

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

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入你的 API Key (ZHIPUAI_API_KEY)

# 启动服务
uvicorn app.main:app --host 0.0.0.0 --port 8080
```

## 🚀 部署指南

### 生产环境部署

对于生产环境部署，建议按照以下步骤进行：

#### 1. 环境变量配置

```bash
# 复制样例配置文件
cp .env.example .env

# 编辑生产环境配置
vim .env
```

生产环境推荐配置：
```bash
# 服务性能配置
SERVER_HOST=0.0.0.0
SERVER_PORT=8080
WORKERS=4 # Gunicorn worker 数量

# API 安全与限制
REQUEST_LIMIT_PER_MINUTE=60 # 每分钟请求限制
MAX_CONTENT_LENGTH=1048576 # 最大请求大小 1MB

# 日志配置
LOG_LEVEL=info
LOG_PATH=/var/log/querycraft/
```

#### 2. Docker 生产部署

```bash
# 构建并启动生产环境
docker-compose -f docker-compose.prod.yml up -d

# 仅升级应用（不停服）
docker-compose -f docker-compose.prod.yml up -d --no-deps --build backend
```

#### 3. 容器监控

启用 health check 用于容器编排工具（如 Kubernetes, Docker Swarm）健康检查：
```yaml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/api/v1/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s
```

#### 4. 故障排查

- **CPU 使用率高**: 检查 SQL 生成的复杂度，可能需要优化或限制查询复杂度
- **内存泄漏**: 监控长时间运行实例，确保 AI 模型 API 调用正常释放
- **连接池耗尽**: 调整 DB 连接参数 `DB_POOL_SIZE` 和 `DB_POOL_TIMEOUT`


## 📡 API 端点

| 端点 | 方法 | 描述 |
|------|------|------|
| `/` | GET | 根路径，项目信息 |
| `/api/v1/health` | GET | 健康检查 |
| `/api/v1/generate` | POST | SQL 生成 |
| `/api/v1/validate` | POST | SQL 验证 |
| `/api/v1/datasources` | GET/POST | 数据源管理 |
| `/api/v1/history` | GET/POST | 查询历史 |

## 📝 API 示例

### 生成 SQL

```bash
curl -X POST http://localhost:8080/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{
    "query": "查询最近 30 天的订单总金额",
    "dialect": "mysql",
    "datasource": "shop_db"
  }'
```

**响应:**
```json
{
  "sql": "SELECT SUM(amount) as total_amount FROM orders WHERE created_at >= DATE_SUB(NOW(), INTERVAL 30 DAY)",
  "confidence": 92,
  "explanation": "根据订单表的 created_at 字段筛选最近 30 天数据，并计算 amount 字段的总和"
}
```

### 验证 SQL

```bash
curl -X POST http://localhost:8080/api/v1/validate \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT * FROM users WHERE id = 1",
    "dialect": "mysql"
  }'
```

### 健康检查

```bash
curl http://localhost:8080/api/v1/health
```

**响应:**
```json
{
  "status": "ok",
  "version": "0.1.0",
  "llm_provider": "zhipuai",
  "timestamp": "2026-03-09T11:34:58.550489"
}
```

## ⚙️ 配置

### 环境变量 (.env)

```bash
# 服务配置
SERVER_HOST=0.0.0.0
SERVER_PORT=8080

# LLM 配置
ZHIPUAI_API_KEY=your_api_key_here
LLM_MODEL=glm-4-flash

# 数据库配置 (可选)
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
```

## ✅ 开发状态

### v0.1.0 - MVP (当前版本)

| 功能 | 状态 | 说明 |
|------|------|------|
| 项目架构设计 | ✅ | FastAPI + React + CLI |
| SQL 生成 API | ✅ | ZhipuAI 已接入 |
| SQL 验证 API | ✅ | 语法检查 + 评分 |
| CLI 工具 | ✅ | `cli/qc.py` |
| Docker 部署 | ✅ | `docker-compose.yml` |
| Schema Discovery | ✅ | 自动发现数据库结构 |
| Learning Service | ✅ | 持续学习与优化 |
| Query History | ✅ | 查询历史记录 |
| MySQL 连接器 | 🚧 | 开发中 |

### 待完成

| 功能 | 优先级 | 计划版本 |
|------|--------|---------|
| PostgreSQL 连接器 | 🔥 高 | v0.2.0 |
| Web UI | 🔥 高 | v0.3.0 |
| Hive/Spark 连接器 | ⏳ 中 | v0.2.0 |
| 用户认证 | ⏳ 中 | v0.4.0 |
| Kubernetes 部署 | ⏳ 低 | v1.0.0 |

## 🤖 GitHub 自动化功能

QueryCraft 集成了 GitHub Issue 自动化处理功能，能够:
1. 自动扫描带有特定标签（help wanted, good first issue, enhancement, bug）的问题
2. 根据问题内容分析复杂度和可行性
3. 自动创建分支、实现功能、修复缺陷并提交 PR
4. 以 linxClawBot 账户身份进行代码贡献

### 环境配置

要启用 GitHub 自动化功能，需确保以下配置：

1. **SSH 配置**: `~/.ssh/config` 中设置两个账户的别名
```
# OpenClaw (Xeon) - 主账户
Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519

# OpenCode - 协作者账户
Host github-collab
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_collab
```

2. **Git 身份配置**: 项目工作目录中使用 linxClawBot 身份
```bash
cd ~/code/QueryCraft
git config user.name "linxClawBot"
git config user.email "linxclawbot@users.noreply.github.com"
```

3. **远程仓库配置**: 使用指定别名进行 PR 推送
```bash
git remote add github-collab git@github-collab:linxiaowen-928/QueryCraft.git
```

### 自动化命令

#### 基础命令操作

```bash
# 检查并处理待处理的 Issues
cd ~/code/QueryCraft/.opencode/skills/github-issue-automator
node cli.js check

# 查看自动化当前状态
node cli.js status

# 列出所有标记的待处理 Issues
node cli.js list

# 处理指定编号的 Issue
node cli.js work 51

# 从文本需求创建新 Issue
node cli.js create-from-request "修复登录页面在移动设备上的显示问题，需要优化CSS样式"

# 获取完整帮助信息
node cli.js get-help
```

### 工作流程详解

1. **发现阶段**: 定期扫描 GitHub 仓库的 Issues，依据预设标签筛选合适的任务
2. **分析阶段**: 使用 AI 解析 issue 内容，评估复杂度并确定最佳实现方案
3. **开发阶段**: 创建专门的工作分支，编写实现代码，并进行必要的测试
4. **提交阶段**: 推送变更代码至远程仓库并自动创建 Pull Request
5. **跟进阶段**: 监控 PR 的审查状态，响应审阅意见并持续改进

## 🛠️ 技术栈

- **后端**: Python 3.10+, FastAPI, SQLAlchemy, Pydantic
- **前端**: React 18, TypeScript, TailwindCSS (计划中)
- **AI**: ZhipuAI (glm-4-flash), DeepSeek, OpenAI
- **部署**: Docker, Docker Compose
- **数据库**: MySQL, PostgreSQL, Hive, Spark, Flink, Iceberg

## 📊 版本里程碑

| 版本 | 目标日期 | 状态 | 重点 |
|------|----------|------|------|
| v0.1.0 | 2026-03-10 | 🚧 开发中 | MVP 核心功能 |
| v0.2.0 | 2026-03-20 | ⏳ 计划中 | 多数据源支持 |
| v0.3.0 | 2026-04-01 | ⏳ 计划中 | Web UI |
| v0.4.0 | 2026-04-15 | ⏳ 计划中 | 企业特性 |
| v1.0.0 | 2026-05-01 | ⏳ 计划中 | 正式版 |

## 🔗 相关链接

- [GitHub 仓库](https://github.com/linxiaowen-928/QueryCraft)
- [Gitee 镜像](https://gitee.com/linxiaowen-928/QueryCraft)
- [开发路线图](ROADMAP.md)
- [问题追踪](https://github.com/linxiaowen-928/QueryCraft/issues)

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE)

---

## 🤖 GitHub 自动化功能

QueryCraft 集成了 GitHub Issue 自动化处理功能，能够:
- 自动扫描和处理特定标签的问题（help wanted, good first issue, enhancement, bug）
- 根据问题内容分析复杂度和可行性
- 自动创建分支、实现代码、提交 PR
- 以 linxClawBot 账户身份贡献代码
- 处理 PR 评审意见并进行相应修复
- 监控 PR 状态直至合并

### 自动化工作流
```bash
# 检查并处理 Issues
cd /home/linx/code/QueryCraft/.opencode/skills/github-issue-automator
node cli.js check

# 列出待处理 Issues
node cli.js list

# 处理指定 Issue
node cli.js work <issue-number>

# 从需求直接创建 Issue
node cli.js create-from-request "需求描述"

# 启动连续自动化处理循环
/ulw-loop github-issue-automator
```

### 功能说明

1. **Issue 扫描与分析**：扫描 GitHub Issues，根据关键词分析难度和可行性
2. **身份管理**：使用预设的 linxClawBot 账户进行 Git/GitHub 操作
3. **分支管理**：为每个 Issue 创建独立分支
4. **实现编码**：根据 Issue 要求生成代码修正
5. **PR 创建**：自动提交 Pull Request 并关联对应的 Issue
6. **评审跟进**：监控 PR 状态，根据评审意见进行进一步修改

### 配置要求

1. **SSH 配置**：支持两个账户（主账户用于审查，linxClawBot 账户用于贡献）
2. **Git 配置**：支持不同上下文下的账户身份自动切换
3. **权限管理**：确保 linxClawBot 在代码库具有推送和 PR 权限

### 适用场景

- 简单 Bug 修复
- 文档改进
- 测试覆盖
- 增强功能（非核心架构修改）
- 代码清理与重构

此功能有助于加速开源项目的开发迭代，减轻维护者的重复工作负担。

*基于 text2sql-engine skill 开发*
*创建时间：2026-03-06*
*最后更新：2026-03-09*

## 🤖 GitHub Issue Automator (AI 助手集成)

本项目集成了 GitHub Issue Automator，用于自动化处理来自 AI 助手的开发任务。

### 功能特点
- 自动检测和分配待处理 Issues
- 智能解析用户功能需求并创建 Issues
- 自动生成代码实现和 PR
- 跟踪 PR 审查进度，响应反馈

### 快速上手

### 命令参考

- `node cli.js check` - 检查并处理待处理 Issues
- `node cli.js status` - 查看技能状态
- `node cli.js list` - 列出待处理 Issues
- `node cli.js work <number>` - 处理指定 Issue
- `node cli.js create-from-request "<requirement text>"` - 从用户需求文本创建新的 GitHub Issue


`git push github-collab <branch>`


### 详细配置指南

完整、详尽的设置和配置指南请参阅：[GitHub Issue Automator 设置和配置指南](docs/github-issue-automator-setup-guide.md)

该文档涵盖了：
- 系统要求和先决条件
- 逐步安装过程
- 配置参数说明
- 身份验证设置
- API端点参考
- 测试和故障排除最佳实践

其中 `github-collab` 是专为 AI 协作者 (linxClawBot) 配置的远程地址。