Skip to content

About

OCSJS 的 AI 答题协议桥接与多后端调度层 | A pluggable AI answering bridge for OCSJS, featuring multi-backend orchestration, dynamic policy routing, multimodal support, and resilient fallback.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

OCSJS AI 桥接服务

OCSJS 的 AI 答题协议桥接与多后端调度层 —— 把 OCSJS 的题库请求翻译成可插拔的 AI 后端调用,OCS 端只需填一份题库配置。

  • 协议桥接 — 实现与原版题库服务一致的 POST /v1/answer,OCS 端零改动
  • 多后端编排 — 本地 Ollama、OpenAI 兼容、OpenAI Responses 平级可插拔;一份配置可挂多个后端
  • 动态策略路由 — 按题型选候选链,也可用 policy.js 按时段、开关或题目特征动态调整顺序
  • 多模态 — 图片题支持浏览器直传 data URL 或服务端下载,按后端能力自动过滤
  • 弹性降级 — 全程受总时间预算约束,失败自动换候选并给出原因,绝不返回猜测的答案

运行期零第三方依赖,只需 Node.js 22.9+。服务本体已在 Windows 端到端实测,Linux 未在开发环境实测 —— 部署前请先跑 npm run doctor(见「已知限制」)。


安装

# 1) 安装依赖(仅开发依赖:typescript / tsx)
npm install

# 2) 准备配置
cp config.example.jsonc config.jsonc
cp .env.example .env
#    编辑 .env:至少填 SERVICE_ACCESS_TOKEN、OLLAMA_BASE_URL、OLLAMA_MODEL

# 3) 部署自检:逐项确认运行环境、配置与后端连通性
npm run doctor

# 4) 构建并启动
npm run build
npm start

启动后:

curl http://127.0.0.1:8000/health

/health 会返回版本、监听地址、脱敏后的后端清单与路由,可用于 OCS 的题库连通性探测。

Linux 常驻运行见 deploy/README.md;Windows 可一键启动:

.\deploy\start.bat

配置 OCSJS

在 OCS → 通用 → 全局设置 → 题库配置 中粘贴 ocs-answerer-wrapper.json.example 的内容,并把两处占位符换成你的实际值:

  • https://your-service.example.com → 你的服务地址
  • change-me → 与 .env 中 SERVICE_ACCESS_TOKEN 相同的值

请求使用原版 OCS 提供的 title / options / type 三个字段(5.x 可再加 images,见下),期望返回:

res.code === 1 ? [res.question, res.answer] : [res.message, undefined]

OCSJS 5.x

模板已适配 5.x,可直接用:

  • responseType: "json" —— contentType 在 5.x 已标记废弃(旧写法仍能跑)
  • data.images 用字段解析器提交 env.images —— 5.x 会自己把题干/选项里的图片下载并转成 PNG data URL 传过来,服务端不必再按 URL 下载一次,能绕开超星图片的登录态/防盗链。注意不能写成 "images": "${images}":占位符替换是字符串替换,数组会被逗号拼接、破坏 data URL。
  • 域名白名单:5.x 会校验题库 URL 是否在脚本头 @connect 里。用全域名通用版(@connect *)不受限;否则需把服务地址加进 @connect。
  • 保存配置前会做恶意代码检测(仅警告不阻断)。本模板的 handler 只读 res 字段,不会触发。

建议的高级设置:

  • 搜题最大耗时 — 设为界面允许的最大值(180 秒);服务端 deadline_seconds 默认 170 秒,预留了网络与序列化余量
  • 线程数量 — 先用 1;本地模型建议保持较低并发(服务端已按 max_concurrency 限制每个后端)
  • 答案分隔符 — 保留默认的 #
  • 初次测试建议选择「不保存也不提交」

配置参考

config.jsonc 支持注释与尾随逗号,字符串里可用 ${VAR} / ${VAR:-默认值} 引用环境变量。 引用了未设置且无默认值的变量时,启动会直接失败并指出字段路径,不会静默使用错误地址。

服务与限额

字段 默认值 说明
server.listen 0.0.0.0:8000 监听地址;只想本机访问可改 127.0.0.1:8000
server.access_token 空 与 OCS 题库配置里的 X-Access-Token 一致;留空则不校验(仅限本机调试)
server.deadline_seconds 170 总时间预算,所有后端尝试共享,不叠加
server.max_body_bytes 8388608 请求体上限
server.cors_origins [] OCS 走 GM_xmlhttpRequest,无需 CORS;留空即不发送 CORS 头
limits.image_timeout_seconds 30 单张图片下载超时
limits.max_images 24 单题最多处理图片数
limits.max_image_bytes 12582912 单张图片大小上限
limits.min_attempt_seconds 5 剩余预算低于该值就不再尝试候选后端
limits.image_concurrency 4 图片并发下载数
answer.separator # 多答案分隔符,必须包含 #
answer.require_declared_images true 题目声明有图却一张都读不到时拒绝作答

后端(backends)

三种 kind 对应三种上游协议:

kind 请求 图片传递 结构化输出 推理开关
ollama POST {base_url}/api/chat message.images(纯 base64) format: "json" think
openai_chat POST {base_url}/v1/chat/completions content 里的 image_url response_format 无(忽略 reasoning_effort)
openai_responses POST {base_url}/v1/responses input_image text.format reasoning.effort

公共字段:

字段 说明
name 后端唯一名,路由通过它引用
base_url 站点根地址、/v1 地址或完整端点都可;远端地址强制 https,本机回环可用 http
model 模型名
capabilities.vision 是否支持图片输入,默认 false
capabilities.thinking 是否支持「思考」开关,默认 false
timeout_seconds 单次尝试硬超时(运行时会再与剩余预算取小)
max_concurrency 该后端并发上限
api_key openai_chat / openai_responses 必填
reasoning_effort 仅 openai_responses 使用
endpoint_path 需要自定义端点时使用

能力必须如实声明:服务不会按模型名推断能力。声明 vision: false 的后端在遇到图片题时会被跳过并记入 warnings;若所有候选都不支持视觉,请求会明确失败。

想确认本机 Ollama 各模型的实际能力,可只读查询:

curl http://<ollama-host>:11434/api/tags

响应里每个模型的 capabilities 字段即为其支持的能力列表。

路由(routes)

"routes": [
  { "type": "multiple",   "backends": ["online-responses", "ollama-local"] },
  { "type": "*",          "backends": ["ollama-local"] }
]
  • backends 是候选链:按顺序尝试,失败换下一个,直到成功或用尽预算
  • type 精确匹配优先,"*" 为兜底;同一题型命中多条时以第一条为准
  • 常见题型:single / multiple / judgement / completion / line / fill / reader,以及上游自定义题型
  • /v1/answer 不提供后端选择字段(OCS 也传不了),选择与降级完全由服务端决定

推荐起步策略:本地 Ollama 承担纯文本题,在线后端承担多选、主观题与图片题(按实测质量调整)。

策略钩子(可选)

routes 是静态规则;需要按时间、题目特征或临时开关动态决定时,可启用一个用户自写的 JS 文件:

"policy": {
  "file": "./policy.js",   // 相对 config.jsonc 所在目录
  "timeout_ms": 100        // 执行超时,超时回退默认顺序
}

每次请求前调用文件导出的 decide(ctx),返回后端名数组(按尝试顺序):

// 与宿主机时区无关的小时取法(服务器不是 UTC+8 时必需)
function hourIn(now, timeZone = "Asia/Shanghai") {
  return Number(
    new Intl.DateTimeFormat("en-US", { timeZone, hour: "numeric", hourCycle: "h23" }).format(now),
  );
}

export function decide(ctx) {
  const hour = hourIn(ctx.now);
  if (ctx.hasImages) return ["deepseek-flash"];
  if (hour >= 22 || hour < 8) return ["qwen-deepseek", "deepseek-flash"]; // 夜间折扣
  if (ctx.questionType === "judgement") return ["ollama-local"];          // 简单题本地
  return ["deepseek-flash", "ollama-local"];
}

ctx 提供 now / questionType / hasImages / imageCount / backendNames / defaultOrder。

  • 返回 null、undefined 或空数组 → 回退 routes 的默认顺序
  • 抛错、超时、返回未知后端名 → 回退默认并把原因写进响应 warnings(不会中断答题)
  • 想临时关闭某个后端:返回的数组里不含它即可
  • 可返回对象覆盖单次参数:[{ name: "deepseek-flash", timeoutSeconds: 30, think: false }]
  • 改文件无需重启(按 mtime 热重载,下一个请求生效)

完整示例见 policy.example.js。注意:decide 每次答题前都会执行,不要在里面发网络请求或做阻塞操作。


运行行为

超时预算

收到请求 ──── 总预算 170s ────────────────────────────►
   候选 1 [min(自身超时, 剩余)]   候选 2 [min(自身超时, 剩余)]
                                  └─ 成功即返回;剩余 < min_attempt_seconds 则放弃
  • 单候选计时使用整数毫秒,并保留 timeout_seconds: 0.1 等有效小数配置
  • 浏览器在发送完整请求体后断开,服务端取消对应上游任务
  • 任何单个候选都不可能吃穿总预算
  • 剩余预算消耗过半后不再开启「思考」,把时间留给出答案
  • 全部候选耗尽仍未成功 → code:0 并列出每个候选的失败原因

降级规则

情况 处理
连接失败 / 超时 / HTTP 4xx-5xx / 响应非 JSON / 缺 answer / 空答案 后端级:记 warning,换下一候选
题目含图但一张都读不出 题目级:立即 code:0,不降级
候选后端 vision: false 却遇到图片题 跳过该候选并记 warning
所有候选都不具备视觉能力 明确报错,不静默猜测
模型输出夹带解释、带 Markdown 围栏 容错解析并记入 warnings

响应格式

成功:

{
  "code": 1,
  "message": "ok",
  "question": "中国的首都是哪座城市?",
  "answer": "北京",
  "confidence": 1,
  "model": "ollama-local/qwen3.5:9b",
  "warnings": []
}

失败(HTTP 仍为 200,与既有服务一致):

{ "code": 0, "message": "所有候选后端均未能作答(ollama-local: 上游返回 HTTP 404..." }

X-Access-Token 无效时返回 HTTP 401;请求体超限返回 HTTP 413。


开发

npm run typecheck         # 源码 + 测试的类型检查
npm test                  # 单元与契约测试
npm run doctor            # 部署自检:环境 / 配置 / 每个后端真实连通性
npm run smoke             # 接真实 Ollama 的 10 项实测(需要 .env 里的 OLLAMA_* 可用)
npm run smoke:multi       # 多后端降级实测(真实 HTTP + 真实上游,使用临时配置)
npm run smoke:routing     # 按题型路由实测(两个真实模型,用响应 model 字段证明分流)
npm run smoke:concurrency # 并发实测:模拟 OCS 多线程搜题,验证并发闸与结果隔离
npm run show-config       # 打印脱敏后的配置摘要

目录结构:

src/
  server.ts        入口:配置 → 服务 → 优雅关闭
  config.ts        JSONC 解析、${ENV} 展开、启动校验、敏感值擦除
  httpapi.ts       /v1/answer 与 /health、鉴权、限额
  routing.ts       候选链、超时预算、能力过滤、降级
  normalize.ts     题型与选项归一、图片标记、挖空标记   ┐
  images.ts         data URL 校验、下载、MIME 嗅探       ├ 领域层(与协议无关)
  format.ts        答案 → OCS 可回填字符串               ┘
  prompt.ts        中立请求模型
  upstream/        三个协议适配器 + 容错解析

关键边界:领域层只实现一次,三种适配器共用——OCS 的回填行为不会因为换后端而变化。


故障排查

现象 原因与处理
启动报「配置校验失败」 消息里会指出字段路径;常见是未设置 OLLAMA_BASE_URL 之类被引用的环境变量
启动报「后端凭据缺失」 openai_chat / openai_responses 后端没有 api_key
code:0 且提示「没有拿到任何可读图片」 题目图片 URL 需要登录态或已过期;可在浏览器侧安装异步取图补丁,让 OCS 提交 data URL
code:0 且提示「不具备视觉能力」 候选后端都声明了 vision: false;为图片题配置支持视觉的后端
code:0 且提示「时间预算不足」 前面的候选耗时过长;提高 deadline_seconds、降低 timeout_seconds,或把更快的后端排到前面
日志出现「上游响应里没有 message.content」或「上游返回了空 content」 Ollama 的偶发行为:请求成功(HTTP 200)但正文为空,实测多发于并发请求或长时间思考后。已自动关闭 thinking 重试一次;若重试仍失败,日志里会带上 done_reason / eval_count / thinking 长度,据此判断是截断、空输出还是上游格式变化
单题耗时经常 30–70 秒 capabilities.thinking 为 true 时模型会先长时间思考。实测同一题关闭思考后从 30–70 秒降到 4–10 秒,代价是答案质量略降;预算紧张或并发较多时建议关闭
答案与预期格式不符 查看响应 warnings,其中记录了跳过的后端与解析容错过程

已知限制

  • 原版 OCS 不传图片数组 — 图片 URL 混在题干或选项文本里,由服务端下载;受登录态保护的地址可能下载失败
  • 原版 OCS 不传 DOM 结构 — 下划线、挖空样式、共用选项对应关系、材料层级无法复原;这类题以 OCS 自身能提取和回填的内容为准
  • 本地小模型的格式稳定性弱于线上模型 — 建议按题型路由,并把关键题型交给更强的后端
  • 验证范围(请先读这一条) — 服务本体在开发环境(Windows)完成了端到端实测:题库协议、三种上游协议、路由与预算、并发、降级都有真实链路证据。 Linux 端未在开发环境实测:开发机没有 Linux(无 WSL 发行版、无容器/虚拟化工具)。跨平台风险已通过契约测试与静态审计排除——运行期零第三方依赖、无原生模块、纯 ESM、未使用任何平台相关 API——但"没跑过"就是没跑过。 所以部署到任何平台前,请先运行 npm run doctor:它会打印当前平台与架构,并真实请求配置里的每个后端。这是部署流程的第一步,不是遗留待办

许可

代码以 GPL-3.0-only 授权,见 LICENSE。

About

OCSJS 的 AI 答题协议桥接与多后端调度层 | A pluggable AI answering bridge for OCSJS, featuring multi-backend orchestration, dynamic policy routing, multimodal support, and resilient fallback.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages