# OCS × AI 题库中间件

给 [OCS 网课助手](https://github.com/ocsjs/ocsjs)（超星学习通等刷课/答题脚本）用的本地 AI 题库中间件：
OCS 把题目转成 JSON 发给本服务，本服务调用 DeepSeek 返回答案，再由 OCS 自动选择/填写。

支持：
- 文字题：单选 / 多选 / 判断 / 填空
- **图片题 / 公式题**：图片直接交给 DeepSeek 视觉模型（`deepseek-flash`）识别，无需本地 OCR
- OCS 5.0+「图片题优化」：浏览器端把图片转成 base64 数组随请求上传（免疫图床防盗链）
- 旧版 OCS（图片以 URL 文本内嵌在题目里）：中间件自动带 Referer 下载图片再识别

## 目录结构

```
ai_client.py            DeepSeek 调用、图片抽取/下载/base64、多模态消息构建
server.py               FastAPI 服务（POST /api/search）
generate_ocs_config.py  生成 OCS「题库配置」JSON
gen_config.bat          双击生成题库配置并保存 ocs_config.json
run.bat                 双击启动中间件
config.example.yaml     配置示例（复制为 config.yaml 后填 API Key）
tests/                  测试（含真实 API 的 E2E 与离线单测）
```

## 快速开始

1. 安装依赖：

   ```bat
   py -m pip install -r requirements.txt
   ```

2. 复制配置并填入 DeepSeek API Key：

   ```bat
   copy config.example.yaml config.yaml
   ```

3. 双击 `run.bat` 启动（默认监听 `http://127.0.0.1:8777`）。

4. 双击 `gen_config.bat`，把生成的 `ocs_config.json` 内容整个粘贴到
   OCS → ⚙️ 全局设置 → 题库配置，保存。

5. OCS → 高级设置 → 勾选「图片题优化」（默认开启），然后开始自动答题。

> OCS 5.0+ 的题库配置必须包含 `images` / `suggestion_title` / `suggestion_options` 三个字段，
> 否则会提示「当前题库配置暂不支持图片、公式等题目处理」。用 `gen_config.bat` 重新生成即可。

## 接口

`POST /api/search`

```json
{
  "title": "题干",
  "type": "single | multiple | judgement | completion",
  "options": "A. xxx\nB. xxx",
  "images": ["data:image/png;base64,..."],
  "suggestion_title": "题干 [图片1]",
  "suggestion_options": "A. [图片2]\nB. [图片3]"
}
```

返回：`{"code": 1, "question": "...", "answer": "B"}`（多选用 `#` 分隔，如 `A#C`）。

## 模型说明

| 用途 | 模型 | 说明 |
| --- | --- | --- |
| 文字题 | `deepseek-v4-pro` | 推理更强，只支持文字 |
| 图片题 | `deepseek-flash` | DeepSeek 唯一支持图片输入的模型 |

在 `config.yaml` 的 `ai.model` / `ai.vision_model` 中配置。

## 测试

```bat
set PYTHONIOENCODING=utf-8
py tests\test_vision_e2e.py            :: 旧版 URL 图片链路（真实 API）
py tests\test_ocs_images_e2e.py        :: OCS 5.0 base64 图片链路（真实 API）
py tests\test_ocs5_contract.py         :: OCS 5.0 题库配置契约（离线）
py tests\test_ocs5_adversarial_e2e.py  :: 对抗性测试（真实 API，--offline-only 可零花费）
```

## 免责声明

本项目仅供学习交流使用，请遵守所在平台的服务条款。