# AI 题库服务 API 文档

## 概述

本服务是 Nuxt/Nitro 版 OCS AI 答题接口，兼容 OCS AnswererWrapper。服务端使用 OpenAI 兼容 Chat Completions 流式接口生成答案，最终返回 OCS 可直接处理的 JSON。

## 搜索接口

**URL**：`/api/search`

**方法**：`GET` 或 `POST`

`POST` 支持 JSON body、`application/x-www-form-urlencoded` body 和 `multipart/form-data` body。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `title` | string | 是 | 题目内容 |
| `type` | string | 否 | `single`、`multiple`、`judgement`、`completion` |
| `options` | string | 否 | 选项内容 |

成功响应：

```json
{
  "code": 1,
  "question": "中国的首都是哪个城市？",
  "answer": "北京"
}
```

失败响应：

```json
{
  "code": 0,
  "msg": "未提供问题内容"
}
```

## 健康检查

**URL**：`/api/health`

**方法**：`GET`

```json
{
  "status": "ok",
  "message": "AI题库服务运行正常",
  "version": "1.1.0",
  "cache_enabled": true,
  "model": "gpt-3.5-turbo"
}
```

## 清空缓存

**URL**：`/api/cache/clear`

**方法**：`POST`

若配置了 `ACCESS_TOKEN`，需要通过 `X-Access-Token` 请求头或 `token` 查询参数传递。

```json
{
  "success": true,
  "message": "缓存已清除"
}
```

## 统计信息

**URL**：`/api/stats`

**方法**：`GET`

若配置了 `ACCESS_TOKEN`，需要通过 `X-Access-Token` 请求头或 `token` 查询参数传递。

```json
{
  "version": "1.1.0",
  "uptime": 123.45,
  "model": "gpt-3.5-turbo",
  "cache_enabled": true,
  "cache_size": 1,
  "qa_records_count": 1
}
```

## OCS 配置示例

```json
[
  {
    "name": "AI智能题库",
    "homepage": "http://localhost:3000",
    "url": "http://localhost:3000/api/search",
    "method": "get",
    "type": "GM_xmlhttpRequest",
    "contentType": "json",
    "data": {
      "title": "${title}",
      "type": "${type}",
      "options": "${options}"
    },
    "handler": "return (res)=> res.code === 1 ? [res.question, res.answer] : [res.msg, undefined]"
  }
]
```

多选题答案会返回 `A#B` 或答案文本 `北京#上海` 这类字符串，不返回数组。部署到自定义域名时，需要按 OCS 文档把相关域名加入脚本 `@connect`。