feat: 前端组件准备

2026-05-22 15:02:31 +08:00
parent 397ccdca13
commit 5e05bf4f63
62 changed files with 6903 additions and 878 deletions
@@ -0,0 +1,111 @@
+# 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`。