N2SQL Pro

SKILL.md

# NL2SQL Skill

**自然语言转 SQL（Natural Language to SQL）** - 用自然语言提问，AI 自动生成并执行 SQL，返回可读结果。

## 功能描述

NL2SQL 是一个将自然语言查询转换为 SQL 的工具，支持 CSV/Excel 文件上传、图表生成、结果导出。

### 核心能力

- 📤 **多格式支持**：CSV、Excel 文件上传
- 🌍 **双语支持**：中文/英文自然语言查询
- 🤖 **AI 驱动**：GPT-4 智能 SQL 生成
- 📊 **可视化**：柱状图、折线图、饼图一键生成
- 🔒 **安全设计**：完全离线，不连接真实数据库

### 适用场景

1. 数据分析师快速查询数据
2. 非技术人员自助取数
3. 快速验证数据假设
4. 生成数据报告

## 使用方式

### 命令行

```bash
# 基本查询
python -m scripts.main "哪个产品的销量最高？" -f data/sales.csv

# 生成图表
python -m scripts.main "每月销售额趋势" -f data/sales.csv --chart line

# 导出结果
python -m scripts.main "查看前10名客户" -f data/customers.csv --format csv -o result.csv
```

### Python API

```python
from scripts import NL2SQLService, QueryRequest

service = NL2SQLService(api_key="your-api-key")

request = QueryRequest(
    question="哪个产品的销量最高？",
    files=["data/sales.csv"],
    chart_type="bar",
    explain=True
)

response = service.query(request)

if response.success:
    print(f"SQL: {response.sql}")
    print(f"结果: {response.data}")
```

## 参数说明

### QueryRequest

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| question | str | ✅ | 自然语言问题 |
| files | List[str] | ✅ | 文件路径列表 |
| chart_type | str | ❌ | 图表类型：bar/line/pie/scatter/area/histogram |
| explain | bool | ❌ | 是否解释 SQL |
| output_format | str | ❌ | 输出格式：markdown/json/csv |

### QueryResponse

| 字段 | 类型 | 说明 |
|------|------|------|
| success | bool | 是否成功 |
| sql | str | 生成的 SQL |
| explanation | str | SQL 解释 |
| row_count | int | 结果行数 |
| columns | List[str] | 列名列表 |
| data | List[dict] | 结果数据 |
| chart_base64 | str | 图表 base64 |
| error | str | 错误信息 |

## 套餐说明

| 套餐 | 月费 | 查询次数 | 数据库连接 | 图表 | 导出 |
|------|------|---------|-----------|------|------|
| FREE | 免费 | 10次/月 | 1个 | 基础 | CSV |
| BSC | ¥29 | 500次/月 | 5个 | 基础 | CSV |
| Pro | ¥99 | 3000次/月 | 20个 | 高级 | Excel/PDF |
| Max | ¥299 | 无限次 | 无限 | 全部 | 全部 |

## 技术栈

- **解析**: pandas, openpyxl
- **AI**: OpenAI GPT-4
- **图表**: matplotlib
- **执行**: pandasql (SQL on DataFrame)

## 注意事项

1. API Key 格式：`SQL-FREE` / `SQL-BSC` / `SQL-STD` / `SQL-PRO` / `SQL-ENT` 开头
2. Token 验证 API：`POST https://geo-api.yk-global.com/validate`
3. 响应字段是 `valid`（不是 `success`）
4. 网络错误时自动降级到 FREE tier

## ClawHub Slug

`nl2sql-pro`