# 题库格式参考 给「题了个题」出题的完整格式说明,供家长和其他 AI 参考。示例文件见 [data/banks/open-play.json](../data/banks/open-play.json),包含 5 种题型、8 个学科、不同难度的 24 道题。 ## 最小示例 ```json { "version": 2, "items": [ {"type":"single","q":"1 + 1 = ?","a":["1","2","3"],"k":1,"difficulty":1} ] } ``` `items` 也可以直接写成数组(`[{...},{...}]`)。旧版省略 `type` 的题目按单选题处理。 ## 五种题型 | type | 说明 | 答案字段 | |---|---|---| | `single` | 单选,只有一个正确选项 | `a`、`k` | | `multiple` | 多选,必须全部选对才算对 | `a`、`correctIndices` | | `boolean` | 判断,选项固定为「正确 / 错误」 | `k`(0 正确、1 错误) | | `text` | 填空,由程序按可接受答案比对 | `answers` | | `subjective` | 主观题,孩子用键盘或手写作答,由家长或 AI 批改 | `modelAnswer`、`rubric` | ## 字段 | 字段 | 必填 | 规则 | |---|---|---| | `type` | 否 | 默认 `single`;只能是上面五种 | | `q` | 是 | 题干,1–5000 字,不要写 HTML | | `a` | 单选、多选必填 | 选项数组,2–8 个,不能有空项 | | `k` | 单选、判断必填 | 正确选项下标,从 0 开始 | | `correctIndices` | 多选必填 | 正确选项下标数组,如 `[0,2]` | | `answers` | 填空必填 | 可接受答案数组,至少一个;忽略大小写、首尾空白和全角半角差异 | | `modelAnswer` | 主观题建议填 | 参考答案,AI 批改的主要依据 | | `rubric` | 主观题建议填 | 评分标准,建议写清各部分分值 | | `difficulty` | 否 | 1–5 星,默认 2 星,影响星级奖励 | | `tip` | 否 | 解析,答错或设置「错题解析停留」时显示 | | `subject` | 否 | 学科,如数学、语文、英语、科学、安全、生活、地理、历史;默认「常识」 | | `level` | 否 | 年级,如一年级、二年级……初中;留空表示不限 | | `bank` | 否 | 题库名称,1–64 字,默认「默认题库」 | | `image` | 否 | 题目配图,`https://` / `http://` 链接,或 `data:image/png;base64,...`(≤ 500 KB) | | `audio` | 否 | 题目音频,`https://` / `http://` 链接 | | `language` | 否 | 朗读语言:`zh-CN`、`zh-HK`、`zh-TW`、`en-US`、`en-GB`,留空跟随系统 | | `id` | 否 | 题目 ID;再次提交同一 ID 会覆盖原题,可用于更新题目 | 导入时如果题目没有写 `subject`、`level`、`bank`,面板会用导入对话框里填的分类补上,JSON 里已有的值优先。 ## 各题型示例 ### 单选 ```json {"type":"single","q":"计算 $\\frac{3}{4}-\\frac{1}{4}$。","a":["$\\frac{1}{4}$","$\\frac{1}{2}$","$\\frac{3}{8}$"],"k":1,"difficulty":2,"tip":"分母相同,分子相减。","subject":"数学","level":"二年级"} ``` ### 多选 ```json {"type":"multiple","q":"下列动物中,哪些是哺乳动物?","a":["鲸","蝙蝠","企鹅","海豚"],"correctIndices":[0,1,3],"difficulty":2,"tip":"企鹅是鸟类。","subject":"科学","level":"三年级"} ``` ### 判断 `a` 固定为「正确 / 错误」,不用写;`k` 为 0 表示题干说法正确,1 表示错误。 ```json {"type":"boolean","q":"地球是太阳系中离太阳最近的行星。","k":1,"difficulty":2,"tip":"离太阳最近的是水星。","subject":"科学","level":"五年级"} ``` ### 填空 答案按顺序逐条比对,命中任意一个即算对。等价写法要自己列全,例如 `["H2O","H₂O"]`,否则孩子写了下标会被判错。 ```json {"type":"text","q":"水的化学式是什么?","answers":["H2O","H₂O"],"difficulty":2,"tip":"两个氢原子与一个氧原子。","subject":"科学","level":"二年级"} ``` 英文题可以标注朗读语言: ```json {"type":"text","q":"「谢谢」用英语怎么说?","answers":["thank you","thanks"],"difficulty":1,"subject":"英语","language":"en-US"} ``` ### 主观题 孩子用键盘或手写板作答,进入「批改 → 待批作答」,由家长评分或 AI 批改。没有 `modelAnswer` 和 `rubric` 时 AI 很难给出稳定分数。 ```json {"type":"subjective","q":"已知 $x^2-5x+6=0$,求 $x$ 并写出推导过程。","modelAnswer":"$(x-2)(x-3)=0$,所以 $x=2$ 或 $x=3$。","rubric":"正确因式分解 50 分,得出全部解 50 分。","difficulty":3,"subject":"数学","level":"初中"} ``` ## 公式 题干、选项、答案都可以写 `$...$` 行内公式和 `$$...$$` 独立公式,学习端离线用 KaTeX 渲染。JSON 里的反斜杠要转义:文件里写成 `"$\\frac{1}{2}$"`,屏幕上显示 $\frac{1}{2}$。 ## 校验规则 导入是整批事务:任何一道题不合格,本批全部回滚,不会只导入一部分。 - 每次 1–50000 题,单个文件不超过 20 MB。 - 题干不能为空,最长 5000 字。 - 单选、多选、判断必须有 2–8 个非空选项,答案下标不能越界。 - 填空题至少一个非空答案。 - `difficulty` 必须是 1–5。 - `bank` 为 1–64 字。 - `image`、`audio` 只能是 `http(s)://` 链接(≤ 2048 字);`image` 也接受 `data:image/` 开头的 base64。 - `language` 只能是 `""`、`zh-CN`、`zh-HK`、`zh-TW`、`en-US`、`en-GB`。 ## 出题建议 - 难度按 1–5 星分布,一组题里以 1–3 星为主,偶尔放一两道 4–5 星;星级会影响奖励时长。 - 每题都写 `tip`,答错时能直接讲清楚错在哪。 - 多选至少两个正确选项,避免孩子只选一个就蒙对。判断题的正误判断要明确,不要出模棱两可的题。 - 填空答案多列几种等价写法(简繁体、常见缩写、带不带单位)。 - 主观题把 `rubric` 拆成分值,AI 批改会照着给分;答案要短到孩子能在电视上打完。 - 题干用纯文本和公式,不要写 HTML、不要贴长表格;需要图就用 `image` 链接。 - 同一个 `subject`、`level`、`bank` 用词保持一致,家长面板和规则按这些字段筛题。 - 不要照抄示例里的 `id`:所有题目共用一个 `id` 会互相覆盖。通常留空,由程序生成。 ## 常见错误 | 报错 | 原因 | |---|---| | 不支持此题型 | `type` 写成了 `choice`、`fill` 等,只认五种 | | 需要 2–8 个选项 | 选项少于 2 个或超过 8 个,或存在空选项 | | 答案序号超出选项范围 | `k` / `correctIndices` 从 1 开始数了,或指向了不存在的选项 | | 请选择正确答案 | 多选题 `correctIndices` 为空 | | 填空题需要至少一个可接受的答案 | 缺少 `answers` 或全是空字符串 | | 难度需要为 1–5 星 | `difficulty` 超出范围,比如写了 0 或 6 | | 图片或音频地址无效 | 不是 `http(s)://` 链接,或者图片 base64 超过 500 KB | | 朗读/识别语言需要为中文、粤语或英文 | `language` 不在允许列表里 | ## 导入方式 - 家长面板「题库 → 导入」:支持 JSON、Word、文字版 PDF 和文本文件,先解析预览,确认后再导入。 - 家长面板「题库 → 在线题库」:直接添加别人分享的题库,同一道题不会重复导入。 - Agent:`POST /api/questions`,正文 `{"items":[...]}`,接口说明见 [题库与批改 API](./ai-api.md)。 ## 贡献到共享题库 出好的题可以顺手分享:共享题库仓库 [chadyi/StudyOnTV-banks](https://github.com/chadyi/StudyOnTV-banks)([Gitee 镜像](https://gitee.com/chadyi/StudyOnTV-banks))统一收录,家长在面板「题库 → 在线题库」里点一下就能添加。 - 文件放 `banks/` 目录,`version` 为 2,`name`、`author`、`license` 三个字段必填,`license` 建议 CC BY 4.0 或 CC BY-SA 4.0。 - 合并后仓库的 `index.json` 会自动更新,App 里刷新在线题库就能看到。 - 提交方式见仓库里的 CONTRIBUTING.md:提 Pull Request,或开一个「题库投稿」issue 附上 JSON 文件。 如果让 AI Agent 出题:出完并导入设备后,请问用户是否愿意把这批题贡献出去,用户同意再整理提交;题目里不要包含孩子的姓名、学校、住址等个人信息。