Shiroha Quiz
Shiroha Quiz 是一个轻量、开源的刷题工具，支持自导入题库、练习、考试与多端使用。
你手里有 Word、Excel、TXT、JSON，或者题目和答案分开的文件。Shiroha Quiz 尝试把这些内容自动识别成可练习、可考试、可复盘的个人题库。
当前主要有两条公开使用线：
- Web 版：适合电脑整理题库，支持导入、练习、考试、错题、备份、AI 与 OCR。
- Android 原生版：当前主推，Kotlin + Compose 原生实现，支持 AI、多空填空、背题/斩题、图片题和智能复习。
[!IMPORTANT]
更新节奏：最近工作稍微闲了一些，应该会开始恢复更新。问题反馈仍欢迎提交。
快速开始
| 你的情况 | 下载什么 | 入口 |
| --- | --- | --- |
| Android 手机 | 原生版 APK，文件名以 -native-release.apk 结尾 | 下载 |
| Windows 电脑 | Web ZIP，解压后双击 打开Shiroha Quiz.cmd | 下载 |
| 先体验一下 | 在线版，免安装 | 打开在线版 |
原生版与 Web 版使用独立版本号，不是新旧关系。下载时认文件名即可，当前版本以 Releases/latest 为准。
当前仍处于测试阶段，不建议用于高风险正式考试场景。重要题库请定期备份。
原生版与 Web 版区别
| 维度 | Android 原生版 | Web 版 | | --- | --- | --- | | 使用方式 | 安装 APK，Android 8.0+ | 解压后双击启动器，免安装 | | 数据存储 | 本地 SharedPreferences | 浏览器 LocalStorage | | 离线能力 | 除 AI、在线文档识别外可离线 | 基础功能可离线，扩展库可按需下载 | | 文档识别 | MinerU 在线 OCR、DOCX 图片提取 | PDF.js 文字层解析、OCR 测试区 | | 特色 | 背题、斩题、智能复习、暗夜模式、平板适配 | 桌面题库清洗、OCR、AI 导入与单题解析 | | 适合 | 手机日常刷题 | 电脑整理题库与快速使用 |
展开查看两端详细差异
刷题与考试
双端都有
- 支持随机练习、顺序练习、考试、错题复习、收藏和学习记录。
- 支持单选、多选、判断、填空（含多空）和简答题。
- 支持顺序练习进度、题目快速编辑、考试倒计时和答题卡。
- 答错题目可进入错题本，学习记录可用于后续复盘。
- 即时练习 / 批量练习：可选择立即判题、自动下一题，也可整组提交。
- 背题模式：直接查看答案与解析，不计入普通练习记录。
- 斩题：把已经掌握的题移出普通练习池，并可随时恢复。
- 智能复习：根据错题状态安排到期复习。
- 选项打乱：练习与考试可独立控制。
- 字号与紧凑模式：题干、选项字号可调，适合长题阅读。
- 错题作用域：可在当前题库 / 全部题库之间切换，并按掌握状态筛选。
- 优先未做题：随机组题时优先抽取尚未练习过的题，数量不足再从已做题补足。
- 考试细化设置：可按题型设置题量、分值和时长，并支持滑动切题。
- 考试结果可按题型汇总得分。
- 更偏桌面端快速刷题与题库整理，不提供背题、斩题和智能复习。
题库导入与文档处理
双端都有
- 支持
docx、xlsx/csv、txt、json和粘贴文本导入。 - 支持“题目文件 + 答案文件”双文件导入。
- 自动识别题号、题干、选项、答案、解析、题型和分区。
- 支持导入预览、异常提示、手动修正和全文查找 / 替换。
- 支持普通 JSON、跨端备份和图片题数据互通。
- DOCX 内嵌图片提取并绑定到题目。
- 材料题 / 共用题干、集中答案区等复杂格式的专门解析与回归保护。
- MinerU 在线 OCR：支持扫描 PDF 识别、图片提取与人工绑定。
- PDF.js 直接解析文字层 PDF。
- OCR 测试区：扫描 PDF 可转为文本或 DOCX 后再人工核对导入。
- 更适合在电脑上先做全文清洗，再进入识别预览。
AI 功能
双端都有
- AI 导入核对、补解析和结构化结果优先。
- 练习页支持单题 AI 解析与连续追问。
- 确认后的 AI 解析可以保存回题库。
- 支持 DeepSeek、OpenAI 兼容接口和自定义接口。
- 无答案题 AI 临时参考答案：默认关闭，只用于本次判题，不写回题库，也不进入错题本。
- API Key 使用 Android Keystore 加密保存。
- AI 可用于整理原始题库文本后再进入导入流程。
- 可连接 Ollama / LM Studio 等本机 OpenAI 兼容服务。
- 单题追问可产出可独立保存的完整解析草稿。
备份与跨端
双端都有
- 支持本地完整备份与恢复。
- Web 与原生版题库格式互通。
- 图片题可通过 ZIP 保留素材并跨端导入。
- 支持 WebDAV 云备份与远程恢复。
- 可选每天 / 每周自动 WebDAV 备份，并设置网络、充电和旧备份保留条件。
- 支持 WebDAV 远程列表、SHA-256 校验，以及合并 / 覆盖恢复。
界面与平台能力
Android 原生版
- Kotlin + Jetpack Compose + Material3 原生界面。
- 支持浅色 / 暗夜模式、Shiroha 模式、平板侧边导航和系统返回键。
- 主要面向手机和平板日常刷题。
- HTML + CSS + JavaScript，浏览器直接运行。
- 支持本地启动器和在线版，主要面向电脑端题库整理与快速使用。
两端题库与备份格式持续保持互通；具体功能变化以 CHANGELOG 和 Releases 为准。
当前能力
刷题与考试
- 题型：单选、多选、判断、填空（含多空）、简答题。
- 练习：随机练习、顺序练习、考试、错题复习、收藏与学习记录。
- 范围与进度：支持题库分组、跨题库练习范围和顺序练习进度。
- 原生特色：即时/批量练习、随机练习优先未做题、背题、斩题、选项打乱、字号调整和智能复习。
- 考试：支持倒计时、答题卡、交卷提醒和结果统计。
- 快速编辑：练习中可直接修改题目并写回来源题库。
- 学习记录：每轮练习或考试生成独立记录，支持逐题复盘与只看错题筛选。
题库导入
- 格式：支持
docx、xlsx/csv、txt、json、文字层pdf和粘贴文本。 - 双文件导入：支持“题目文件 + 答案文件”自动匹配。
- 自动解析：识别题号、题干、选项、答案、解析、题型和分区。
- 核对与修正：支持导入预览、异常提示、手动修正、全文查找/替换。
- 原生版：支持 DOCX 内嵌图片提取、材料题/共用题干和集中答案区等复杂格式。
- Web 版：支持 PDF.js 文字层解析，并提供扫描 PDF OCR 测试兜底。
- 原生解析器持续维护真实题库回归测试，复杂边界说明放在专项文档中。
AI 辅助
- AI 导入：Web 与原生版均支持整理 / 核对 / 补解析，优先使用结构化题目结果。
- 单题 AI：练习页可按需解析与追问，确认后保存解析。
- 临时参考答案：原生版可选启用，默认关闭，不写回题库、不进入错题本。
- 接口：支持 DeepSeek、OpenAI 兼容接口和自定义接口；Web 版也可连接 Ollama / LM Studio。
AI 结果仅作辅助参考；使用外部 AI 服务时，题目文本会发送给你配置的服务商。API Key 不写入题库备份。
备份与跨端
- 本地备份：支持完整数据备份和恢复。
- 跨端互通：Web 与原生版题库格式互通，图片题可通过 ZIP 保留素材。
- WebDAV：支持云备份与远程恢复，原生版还可选自动备份。
- 密钥存储：原生版 API Key 使用 Android Keystore 加密保存。
使用说明
Web 版
- 从 Releases 下载 Web ZIP 并解压。
- 双击
打开Shiroha Quiz.cmd，脚本会启动本地服务并打开浏览器，无需预装 Python。 - 在 导入题库 中粘贴文本或上传文件。
- 在 识别预览 中核对题型、答案和解析后导入。
- 进入 练习 或 考试 开始使用。
不建议直接双击index.html。PDF/OCR 依赖 Web Worker 和 ES module，file://下部分能力会失效，而且数据来源与启动器模式不同。
Android 原生版
- 安装
*-native-release.apk。 - 在 导入 页面选择文件或粘贴文本。
- 在 核对页 检查识别结果，必要时手动修正或使用 AI 辅助。
- 选择 练习、考试、背题 等模式开始使用。
- 错题、收藏、学习记录和智能复习会保存在本机。
数据备份建议
- 重要题库导入后及时导出备份。
- 换设备、清缓存、卸载 App 前先备份。
- Web 版建议固定使用同一种访问方式，在线版、本地服务和
file://的数据互不相通。 - Web JSON 与原生备份可跨端导入；含图片题建议使用 ZIP。
- WebDAV 使用方式见 WebDAV 云备份使用指南。
导入格式与策略
推荐优先使用结构清晰的 docx、xlsx / csv、txt 或 JSON。旧版 .doc、.xls、.xlsm 建议先另存为新版格式。
基本流程：
上传 / 粘贴
→ 自动解析
→ 识别预览
→ 人工核对
→ 导入题库详细文档：
如果原始题库很乱，也可以先用 AI 做格式清洗，但建议只统一题号、选项、答案和解析格式，不修改题意、不编造答案。下载与更新
每次正式发布通常提供 Android 原生 APK 与 Web ZIP。近期功能变化以 Release 说明和 CHANGELOG 为准，README 只保留当前稳定能力概览。Web ZIP 不包含约 88 MB 的 PDF.js / MathJax / Tesseract 离线扩展资源，可在 apps/web/libs/ 下按需下载；联网时也可使用 CDN 兜底。
以下为开发者内容。
仓库结构
shiroha-quiz/
├── apps/
│ ├── web/ # Web 版
│ └── android/ # Android 工程
│ └── app/src/native/ # 原生 Compose 源码
│ ├── ai/ # AI
│ ├── importer/ # 导入解析
│ ├── document/ # 文档识别
│ ├── security/ # 密钥存储
│ ├── state/ # 状态管理
│ ├── sync/ # WebDAV
│ └── ui/ # Compose UI
├── docs/ # 文档索引见 docs/README.md
├── test/ # 回归与 Web 测试
├── assets/ # 宣传素材
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
└── README.mdAndroid 工程仍保留两个 flavor：
| Flavor | 包名 | 技术路线 |
| --- | --- | --- |
| web | com.yiqiu.shirohaquiz | 历史 WebView 壳 |
| native | com.reqir.shirohaquiz | Kotlin + Jetpack Compose + Material3 |
本地运行
Web
apps/web/打开Shiroha Quiz.cmd也可以使用任意静态服务器：
npx serve apps/web在线版：https://reiqr.github.io/shiroha-quiz
Android
cd apps/android
./gradlew assembleNativeReleaseWindows PowerShell：
.\gradlew.bat assembleNativeRelease测试与回归
解析器外部回归：
.\run-regression.ps1原生 JVM 单元测试：
cd apps/android
.\gradlew.bat :app:testNativeDebugUnitTestWebDAV 请求测试：
node --test test/web-webdav/request.test.cjsAI 练习回归位于 test/web-ai-practice/，需要 Node、Playwright 和可用的 Chromium / Edge。
相关说明：
开发状态与文档
历史开发计划已归档到 docs/archive/。当前功能状态以 README、CHANGELOG、Releases 和原生开发进度为准。
参与贡献 / 提交反馈
欢迎通过 Issue 提交 Bug、题库兼容问题、导入失败样例、功能建议或文档修正。
提交时请注明平台（原生版 / Web 版），方便定位问题。
贡献者
感谢以下贡献者：
许可证
本项目采用 GPL-3.0 开源。