---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