发帖
雷达卡
---NL2SQL chatBI Wren skill md文件即skill技能配置
name: wrenai
description: |
WrenAI - Text-to-SQL 与生成式商业智能 (GenBI) 技能。
当用户想要用自然语言查询数据库、生成 SQL、自动创建图表/报表、或进行数据分析时，使用此技能。
支持连接到 PostgreSQL、MySQL、BigQuery、Snowflake、ClickHouse 等多种数据源。
需要用户已部署 WrenAI 服务并配置好数据源。
description_zh: "WrenAI Text-to-SQL 与 GenBI 分析（自然语言查询数据库、生成 SQL、自动可视化）"
description_en: "WrenAI Text-to-SQL & GenBI (natural language DB queries, SQL generation, auto-visualization)"
version: 1.0.0
homepage: https://github.com/Canner/WrenAI
metadata:
openclaw:
emoji: 🗄️
requires:
env:
- WRENAI_API_URL
- WRENAI_API_KEY
primaryEnv: WRENAI_API_URL
security:
credentials_usage: |
This skill connects to a user-deployed WrenAI instance.
API URL and Key are only sent to the configured WrenAI service endpoint.
Database credentials are handled by WrenAI service itself (not by this skill).
allowed_domains:
- "${WRENAI_API_URL:-localhost:3000}"
---
# WrenAI Skill
WrenAI - Open-source Text-to-SQL and Generative Business Intelligence (GenBI) system.
## 核心能力
| 功能 | 说明 |
|------|------|
| **Text-to-SQL** | 将自然语言问题转换为 SQL 查询 |
| **自动图表生成** | 根据查询结果自动推荐图表类型 |
| **多数据源支持** | PostgreSQL, MySQL, BigQuery, Snowflake, ClickHouse, Trino 等 |
| **多模型支持** | OpenAI, DeepSeek, 通义千问, Gemini, Claude, Ollama 等 |
| **MDL 语义建模** | 通过 Modeling Definition Language 定义数据语义 |
## 支持的数据源
| 数据源 | 枚举值 |
|--------|--------|
| PostgreSQL | `postgres` |
| MySQL | `mysql` |
| BigQuery | `bigquery` |
| Snowflake | `snowflake` |
| ClickHouse | `clickhouse` |
| MS SQL Server | `mssql` |
| Oracle | `oracle` |
| Trino | `trino` |
| 本地文件 (CSV) | `local_file` |
| S3 文件 | `s3_file` |
| Minio 文件 | `minio_file` |
| GCS 文件 | `gcs_file` |
## 凭证检查
**Credential Check:**
```bash
if [ -n "$WRENAI_API_URL" ] && [ -n "$WRENAI_API_KEY" ]; then
echo "✅ WrenAI credentials configured"
echo " API URL: $WRENAI_API_URL"
else
echo "⚠️ NO WRENAI CREDENTIALS — setup required"
fi
```
**If ⚠️ NO CREDENTIALS:** Guide the user through setup:
### 前置要求
1. **部署 WrenAI 服务** (二选一):
**方式 A - Docker Compose (推荐):**
```bash
# 克隆仓库
git clone https://github.com/Canner/WrenAI.git
cd WrenAI
# 启动服务
docker-compose up -d
# 访问 http://localhost:3000 配置数据源
```
**方式 B - Kubernetes (生产环境):**
```bash
helm repo add wrenai https://charts.wrenai.cn
helm install wrenai wrenai/wrenai -n wrenai --create-namespace
```
2. **配置环境变量:**
```bash
# 方式 A - 环境变量
export WRENAI_API_URL="http://localhost:3000/api"
export WRENAI_API_KEY="your-wrenai-api-key"
# 方式 B - 配置文件
mkdir -p ~/.config/wrenai
echo "WRENAI_API_URL=http://localhost:3000/api" > ~/.config/wrenai/config.env
echo "WRENAI_API_KEY=your-key" >> ~/.config/wrenai/config.env
```
3. **获取 API Key:**
- 登录 WrenAI Web UI (默认 http://localhost:3000)
- 进入 Settings → API Keys → 创建新 Key
---
## API 调用模板
### 基础配置
```bash
# 读取配置
WRENAI_API_URL="${WRENAI_API_URL:-http://localhost:3000}"
WRENAI_API_KEY="${WRENAI_API_KEY:-}"
# 通用请求头
HEADERS="-H 'Content-Type: application/json'"
[ -n "$WRENAI_API_KEY" ] && HEADERS="$HEADERS -H 'Authorization: Bearer $WRENAI_API_KEY'"
```
### API 端点参考
| 功能 | 方法 | 端点 | 说明 |
|------|------|------|------|
| 发送问题 | POST | `/v1/ask` | Text-to-SQL 主接口 |
| 查询状态 | GET | `/v1/ask/{task_id}` | 获取查询任务状态 |
| 获取结果 | GET | `/v1/ask/{task_id}/result` | 获取查询结果 |
| 获取图表 | GET | `/v1/ask/{task_id}/chart` | 获取推荐的图表配置 |
| 获取历史 | GET | `/v1/history` | 获取问答历史 |
| 数据源列表 | GET | `/v1/datasources` | 列出已配置的数据源 |
| MDL 详情 | GET | `/v1/mdl` | 获取语义模型定义 |
---
## 使用场景与示例
### 场景 1: 自然语言查询数据库
**用户意图:** "查询过去7天每天的销售额"
**执行流程:**
1. 确定数据源 (如果没有指定，使用默认数据源)
2. 构造 API 请求
3. 发送问题到 WrenAI
4. 轮询任务状态直到完成
5. 返回 SQL 和结果
**示例调用:**
```bash
# Step 1: 发送问题
TASK_RESP=$(curl -s -X POST "$WRENAI_API_URL/v1/ask" \
$HEADERS \
-d '{
"question": "过去7天每天的销售额是多少？",
"datasourceId": "postgres_default",
"language": "zh"
}')
# 提取 task_id
TASK_ID=$(echo "$TASK_RESP" | jq -r '.taskId // .id // empty')
# Step 2: 轮询状态 (最多等待60秒)
for i in {1..30}; do
STATUS=$(curl -s "$WRENAI_API_URL/v1/ask/$TASK_ID" \
$HEADERS | jq -r '.status')
if [ "$STATUS" = "success" ] || [ "$STATUS" = "completed" ]; then
echo "查询完成"
break
elif [ "$STATUS" = "failed" ]; then
echo "查询失败"
exit 1
fi
echo "等待查询完成... ($i/30)"
sleep 2
done
# Step 3: 获取结果
curl -s "$WRENAI_API_URL/v1/ask/$TASK_ID/result" $HEADERS | jq .
# Step 4: 获取图表推荐
curl -s "$WRENAI_API_URL/v1/ask/$TASK_ID/chart" $HEADERS | jq .
```
### 场景 2: 直接执行 SQL 查询
**用户意图:** "直接执行这个 SQL: SELECT * FROM sales LIMIT 10"
**示例调用:**
```bash
curl -s -X POST "$WRENAI_API_URL/v1/query" \
$HEADERS \
-d '{
"sql": "SELECT * FROM sales LIMIT 10",
"datasourceId": "postgres_default"
}' | jq .
```
### 场景 3: 获取已配置的数据源
```bash
curl -s "$WRENAI_API_URL/v1/datasources" $HEADERS | jq .
```
### 场景 4: 获取语义模型 (MDL)
```bash
curl -s "$WRENAI_API_URL/v1/mdl" $HEADERS | jq .
```
### 场景 5: 获取问答历史
```bash
# 获取最近20条记录
curl -s "$WRENAI_API_URL/v1/history?limit=20" $HEADERS | jq .
# 按数据源筛选
curl -s "$WRENAI_API_URL/v1/history?datasourceId=postgres_default&limit=20" \
$HEADERS | jq .
```
---
## 错误处理
### HTTP 状态码
| 状态码 | 含义 | 处理方式 |
|--------|------|----------|
| 200 | 成功 | 解析响应体 |
| 400 | 请求参数错误 | 检查 question 格式和数据源 ID |
| 401 | 未认证 | 检查 WRENAI_API_KEY 配置 |
| 403 | 无权限 | 检查数据源访问权限 |
| 404 | 资源不存在 | 检查 task_id 或 datasourceId |
| 422 | 验证错误 | 检查 SQL 语法 |
| 500 | 服务器错误 | 重试或检查 WrenAI 服务状态 |
### 常见错误处理示例
```bash
# 错误处理模板
RESP=$(curl -s -w "\n%{http_code}" -X POST "$WRENAI_API_URL/v1/ask" \
$HEADERS -d '{"question":"..."}')
HTTP_CODE=$(echo "$RESP" | tail -n1)
BODY=$(echo "$RESP" | head -n-1)
if [ "$HTTP_CODE" = "200" ]; then
echo "成功: $BODY" | jq .
else
echo "错误 ($HTTP_CODE): $BODY" | jq .
fi
```
### WrenAI 服务健康检查
```bash
# 检查服务状态
curl -s "$WRENAI_API_URL/health" | jq .
# 检查 LLM 连接
curl -s "$WRENAI_API_URL/v1/status/llm" | jq .
# 检查数据源连接
curl -s "$WRENAI_API_URL/v1/status/datasources" | jq .
```
---
## 配置提示
### 支持的 LLM 提供商
在 WrenAI Web UI 中配置或通过环境变量:
```bash
# OpenAI
export WRENAI_LLM_PROVIDER=openai
export OPENAI_API_KEY=sk-...
# DeepSeek
export WRENAI_LLM_PROVIDER=deepseek
export DEEPSEEK_API_KEY=sk-...
# 阿里通义千问
export WRENAI_LLM_PROVIDER=qwen
export DASHSCOPE_API_KEY=sk-...
# 本地 Ollama
export WRENAI_LLM_PROVIDER=ollama
export OLLAMA_BASE_URL=http://localhost:11434
```
### 多租户配置
```bash
# 组织 ID (用于多租户场景)
export WRENAI_ORG_ID=your-org-id
# 在请求中指定
curl -s -X POST "$WRENAI_API_URL/v1/ask" \
-H "X-Org-ID: your-org-id" \
-H "Authorization: Bearer $WRENAI_API_KEY" \
-d '{"question":"..."}'
```
---
## 响应格式参考
### 成功响应 (Ask)
```json
{
"taskId": "uuid-string",
"status": "pending",
"question": "过去7天每天的销售额是多少？",
"createdAt": "2025-01-15T10:30:00Z"
}
```
### 成功响应 (Result)
```json
{
"sql": "SELECT DATE(created_at) AS day, SUM(amount) AS total\nFROM sales\nWHERE created_at >= CURRENT_DATE - INTERVAL '7 days'\nGROUP BY DATE(created_at)\nORDER BY day",
"columns": ["day", "total"],
"data": [
{"day": "2025-01-08", "total": 15000.00},
{"day": "2025-01-09", "total": 18200.00},
{"day": "2025-01-10", "total": 21000.00}
],
"summary": "过去7天每日销售额数据显示，1月10日达到最高21000元"
}
```
### 图表配置响应 (Chart)
```json
{
"chartType": "line",
"config": {
"xAxis": {"field": "day", "label": "日期"},
"yAxis": {"field": "total", "label": "销售额", "unit": "元"},
"title": "过去7天每日销售额趋势"
},
"reasoning": "选择折线图是因为时间序列数据适合展示趋势变化"
}
```
---
## 限制与注意事项
1. **查询超时:** 默认超时 60 秒，超长查询可能被截断
2. **结果行数:** 默认限制 1000 行，可通过参数调整
3. **SQL 验证:** 某些环境启用了 SQL 语法验证，复杂查询可能被拒绝
4. **数据源连接:** 确保数据源网络可达，WrenAI 服务能访问目标数据库
5. **API 限流:** 高频调用可能触发限流，建议添加适当延迟
---
## 更多信息
- **官方文档:** https://docs.wrenai.cn/
- **GitHub:** https://github.com/Canner/WrenAI
- **API 参考:** https://wrenai.readme.io/reference/welcome
京公网安备 11010802022788号
