# AI Chat API

简要说明：提供基于外部大模型（当前支持 OpenAI）的简单对话接口。默认路由前缀 `/ai`，统一使用 JSON 请求/响应，并沿用 `service/internal/common/response.Response` 包装。

## 前置条件
- 配置：`config.toml`
  ```toml
  [mcp]
  enable = true  # 仅启用 MCP 时会自动注册 ai_chat 工具；HTTP 接口与 MCP 各自独立

  [ai]
  enable = true
  provider = "openai"
  model = "gpt-4o-mini"
  api_key_env = "OPENAI_API_KEY"
  ```
- 环境变量：启动进程前导出对应的 Key，例如：`export OPENAI_API_KEY=sk-...`
- 构建/运行：`go build ./...` 或 `go run ./`

## 通用响应格式
```json
{
  "code": 0,          // 0=成功，非0=失败
  "msg": "ok",       // 简短提示
  "data": {},         // 成功时返回的业务数据
  "error": ""        // 失败时的底层错误信息
}
```

## 接口一览
| 方法 | 路径 | 功能 |
| ---- | ---- | ---- |
| POST | /ai/chat | 发送用户提示词，获取模型回复 |

## POST /ai/chat
- 功能：调用外部 AI 模型生成文本回复。
- Content-Type: `application/json`

### 请求体
| 字段 | 类型 | 必填 | 说明 |
| ---- | ---- | :--: | ---- |
| prompt | string | 是 | 用户输入内容 |
| system | string | 否 | 系统指令/角色设定 |
| model | string | 否 | 覆盖默认模型（不填则使用配置中的 `ai.model`） |

### 成功响应
`data` 字段为：
```json
{
  "text": "模型生成的回复文本"
}
```
完整示例：
```json
{
  "code": 0,
  "msg": "ok",
  "data": {"text": "SQL 索引用于加速查询..."}
}
```

### 失败示例
```json
{
  "code": 2,
  "msg": "AI 调用失败",
  "error": "openai request failed: status 401"
}
```

### cURL 示例
```bash
curl -X POST http://127.0.0.1:8080/ai/chat \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "解释 SQL 索引的作用",
    "system": "你是数据库助手"
  }'
```

## MCP ai_chat（补充说明）
当 `[mcp].enable=true` 时，MCP 服务会注册工具 `ai_chat`（与 HTTP 路由独立）。参数含义与 HTTP 相同，客户端通过 MCP 协议的 `tools/call` 请求调用。