[!NOTE] 最近空闲时间沉迷「黑夜君临」，更新不会很勤快（）祝大家刷题顺利~

Shiroha Quiz 一个轻量、开源的刷题工具，支持自导入题库、练习、考试、与多端使用。

Shiroha Quiz 解决一个很实际的问题：

你手里有题库——Word、Excel、TXT、JSON，或者题目和答案分开的文件。但格式不统一，整理成本高，即使整理完了也只能翻看，没法真正做题。Shiroha Quiz 把它们自动识别导入，变成可练习、可考试、可错题复盘的个人题库。文字层 PDF 作为辅助支持，扫描件 / 图片型 PDF 暂不作为主要推荐格式。

当前项目包含三条线：

• Web 版：基础刷题流程完整稳定，题库导入、刷题考试、错题复习均已就绪。
• Android WebView 壳版：Web 资源打包进 APK，离线加载，逻辑与 Web 版一致。
• Android 原生 Compose 版：Kotlin + Compose 原生实现，当前主开发线，暗夜模式、AI 解析、背题模式、斩题功能、智能复习、收藏、快速编辑、错题复盘等增强功能均已落地。

• Web 端功能完整，在线即可使用。
• Android WebView 版，该版本仅过渡参考。
• Android 原生 Compose 版暗夜模式、AI 解析、表格导入、背题模式、斩题功能、智能复习、题目收藏、快速编辑、顺序练习进度记忆、保存退出继续练习、错题复盘均已落地。
• 内置 C1 科目一题库，方便首次体验。

练习模式

• 支持随机抽题或题库顺序两种组题方式，偏好自动记忆
• 单选题/多选题选项选择，判断题对错切换，填空/简答文本输入
• 支持即时练习与批量练习：即时练习可选择”选择后立即判题”和”答对后自动下一题”，单选/判断题支持”选后自动下一题”，批量练习保留整组提交
• 支持题目快速编辑：练习中可从题目右上角直接修改当前题目
• 支持题目收藏：练习中一键收藏题目，在收藏页集中查看
• 支持背题模式：练习页直接显示答案与解析，不计入正确率、不加入错题本、不生成普通练习记录
• 支持斩题功能：可把一眼会的题移出普通练习池，并在题库详情中集中管理和恢复
• 支持顺序练习进度记忆：下次可从上次顺序练习进度继续，退出练习时可选择保存当前位置
• 支持字号缩放：题干与选项字号可独立调整，紧凑选项模式减少卡片间距适合长题快速阅读
• 提交后选项着色区分正误，顶部卡片可收起
• 答错的题自动进入错题本
• 完成全部题目后展示总结：正确率、错题数、重新练习入口

考试模式

• 按题型自定义题目数量与分值，设置考试时长，偏好自动记忆
• 实时倒计时，到时自动交卷
• 答题卡快速跳题，未答题目交卷前提醒，支持滑动切题
• 考试不受背题模式和斩题功能影响：不会提前显示答案，也不会过滤已斩题
• 交卷后展示各题型得分、正确率和明细报告

错题本

• 练习与考试中答错的题自动收录，记录首次出错时间和累计错误次数
• 支持按题库、题型和掌握状态筛选错题
• 错题本展示“错 X 次 / 对 Y 次”，用于保留进入错题本后的历史累计表现
• 错题可重新练习，连续答对 2 次后自动标记为已掌握
• 再次答错会清空连续答对次数，并回到未掌握状态
• 支持手动标记掌握 / 取消掌握，状态调整不会篡改历史答对次数
• 支持智能复习模式：根据错题表现自动安排到期复习，首页同步待复习数量
• 斩题与错题掌握互相独立：斩题用于移出普通练习池，错题掌握用于错题复习状态

刷题记录

• 每轮练习或考试生成一条独立记录
• 记录详情支持逐题复盘，查看每道题的作答与正误
• 按时间倒序排列，方便回顾学习轨迹

多题型支持

• 单选题、多选题、判断题、填空题、简答题

多格式支持

• 上传 docx 文件（推荐），也支持 xlsx/xls 表格、txt、json、文字层 pdf 或粘贴纯文本
• 原生版支持 docx 内嵌图片提取，Web 版支持 PDF.js 解析
• 原生版兼容 Web 导出的图片题 JSON：支持旧 Markdown base64 图片和新的 images 数组结构
• 扫描件/图片型 PDF 暂不支持

双文件导入

• 题目文件和答案文件分别上传，自动匹配题号
• 支持 “1-10：D A A B C…” 范围格式和 “1.D 2.A” 配对格式
• 答案文件缺失题号时按顺序自动对应

识别与预览

• 自动识别题号、题干、选项、答案、解析和题型
• 兼容题型大小写和常见别名，如 single/SINGLE、multiple/MULTIPLE、judge/JUDGE 等
• 支持分区标题继承题型（如 “一、单选题” 下所有题自动归为单选）
• 原生版支持共用题干 / 材料题兜底识别，并可将集中答案解析区合并回对应题目
• 填空题关键词覆盖更广（空白、空格、横线、括号内等），减少简答题误判
• 识别结果预览：逐题查看题型、答案和异常标记，核对筛选器按需显示
• 识别失败时可手动切换解析策略或调整文本后重试

手动修正

• 预览中可逐题修改题型、答案和题干
• 文本编辑器支持查找/替换，可正则匹配批量修改导入原文
• 支持批量编辑和删除异常题目

备份恢复

• 全部数据一键导出为 JSON 备份文件，Web 端与原生端导出格式互通，可相互导入
• 原生端导出 ZIP 含图片素材，Web 端同样可直接导入并自动转换
• 支持批量导出单个题库 JSON
• 恢复时可选合并或覆盖现有数据

• AI 核对：导入结果可发送至 AI 自动校验题型、答案和解析
• AI 解析：AI 自动生成题目解析，适合补全缺解析或解析过短的题目
• 支持 DeepSeek、OpenAI 兼容接口和自定义接口，可配置 API 地址、API Key 与模型名称
• 支持仅处理异常题、控制单批处理数量、超时时间和保存阈值
• AI 建议会先进入核对流程，便于人工确认后再写入题库

• 暗夜模式 / 浅色模式切换，偏好会持久化保存
• Shiroha 模式：统一管控开屏图、页面插画和应用图标，可在更通用的场景下关闭角色元素
• 二级页面支持系统侧边返回映射，减少误退到桌面的情况
• 阅读显示偏好可调：题干/选项字号独立控制，支持紧凑选项模式
• 统一的 Design Token 间距与颜色系统，卡片、按钮、底部导航保持一致质感

Releases 页面提供两个 APK，根据需求选择：

• 内置完整 Web 页面，离线可用
• 功能完整，仅做必要维护，不再作为主要开发线
• 下载约 6 MB

• Kotlin + Compose 纯原生实现，当前主要开发线
• 启动更快，界面更流畅，体积更小（约 5 MB）
• 暗夜模式、AI 功能、表格导入、背题模式、斩题功能、错题复盘、跨端互通均已落地

两个版本可同时安装，互不冲突（包名不同）。

Android 工程通过 productFlavors 维护两个版本，共享同一 Gradle 项目：

1. 打开 apps/web/index.html，或访问 在线版。
2. 进入 导入题库，粘贴文本或上传文件。
3. 系统自动识别题型、选项、答案和解析。
4. 在识别预览中确认题目无误。
5. 进入 刷题练习 或 考试模式 开始使用。
6. 答错的题会进入 错题本。
7. 定期在 设置/导出 中导出备份。

1. 安装 *-native-release.apk，进入首页查看当前题库和学习状态。
2. 在 导入 页面上传 docx、表格、txt、json 或粘贴文本。
3. 在核对页检查题型、答案、解析和异常标记，必要时用全文编辑或 AI 核对辅助清洗。
4. 在 练习 中选择普通练习、即时反馈、自动下一题或背题模式。
5. 遇到一眼会的题，可以开启斩题功能，把它移出普通练习池。
6. 答错的题会进入 错题本，连续答对 2 次后自动标记为已掌握。
7. 在 记录 中复盘每轮练习或考试的逐题结果。

Shiroha Quiz 的题库和记录保存在本地存储中（Web 端使用浏览器 LocalStorage，原生版使用 SharedPreferences）。

建议：

• 重要题库导入后，及时导出全部数据备份。
• 换设备、清理缓存、卸载 App 前，务必先导出备份 JSON 或 ZIP。
• 从 Shiroha Quiz 导出的备份 JSON/ZIP，应在 设置/导出 → 导入配置 / 备份 JSON/ZIP 中导入。
• Web 端导出的 JSON 可直接导入原生端；原生端导出的 ZIP 也可导入 Web 端，含图片题库完全互通。
• 原生端会兼容题型大小写差异和图片字段差异，减少跨端导入时的题型丢失与 base64 文本外露。
• 备份 JSON、批量题库 JSON 不要放进普通题库导入区解析。

支持 docx（推荐）、xlsx/xls 表格、txt、json、粘贴纯文本、题目+答案双文件导入，也可辅助解析文字层 pdf。系统自动识别题号、题干、选项、答案、解析、题型、分区/分卷；原生版额外加强了共用题干、材料题和集中答案解析区的兜底合并能力。导入后会进入识别预览，供逐题确认。

详细说明：

• 所有支持的题库导入格式
• 题库导入策略与使用指南
• 题目导入解析方法说明
• 标准题库格式示例：Markdown / Word / PDF

如果原题库格式非常混乱，且题目没有保密需求，可以先使用 LLM 智能体进行数据清洗，例如豆包、深度求索、通义千问等。清洗目标不是改题，而是统一题号、选项、答案和解析格式。

shiroha-quiz/
├── .github/                         # Issue 模板与 GitHub Actions
├── apps/
│   ├── web/                         # Web 版
│   │   ├── index.html               # Web 入口
│   │   ├── app.js                   # Web 主逻辑
│   │   ├── styles.css               # Web 样式
│   │   ├── question-bank.js         # 内置题库数据
│   │   ├── media/                   # Web 插画素材
│   │   ├── data/                    # 内置题库
│   │   └── libs/                    # PDF.js 等本地库
│   └── android/                     # Android 工程
│       ├── app/
│       │   ├── build.gradle.kts
│       │   ├── src/main/            # 通用入口、Manifest、图标与 WebView 内置 Web 资源
│       │   ├── src/web/             # WebView 壳版入口
│       │   ├── src/native/          # 原生 Compose 版源码
│       │   │   ├── ai/              # AI 客户端与提示词
│       │   │   ├── importer/        # 题库导入引擎
│       │   │   │   ├── assets/      #   素材提取与绑定
│       │   │   │   ├── model/       #   导入数据模型
│       │   │   │   ├── parser/      #   文本 / 表格 / 双文件解析
│       │   │   │   ├── score/       #   解析策略评分
│       │   │   │   └── validate/    #   导入结果校验
│       │   │   ├── state/           # 全局状态管理
│       │   │   ├── ui/              # Compose UI
│       │   │   │   ├── app/         #   App Shell
│       │   │   │   ├── components/  #   可复用组件
│       │   │   │   ├── screens/     #   各页面
│       │   │   │   └── theme/       #   主题与设计 Token
│       │   │   └── util/            # 工具类
│       │   ├── src/test/            # 通用单元测试
│       │   └── src/testNative/      # 原生版解析器测试
│       ├── build.gradle.kts
│       ├── settings.gradle.kts
│       ├── gradle.properties
│       └── gradlew / gradlew.bat
├── docs/                            # 使用说明、导入格式、架构与开发文档
│   ├── web/
│   ├── native/
│   └── universal/
├── test/                            # 解析器回归测试
│   └── native-parser-regression/
├── assets/                          # 宣传图与素材源文件
├── packages/                        # 跨端模块接口说明
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
└── README.md

apps/web/ 是纯静态页面，无需构建。

# 方式一：直接打开
apps/web/index.html

# 方式二：本地静态服务
npx serve apps/web

在线版：

https://reiqr.github.io/shiroha-quiz

进入 Android 工程目录：

cd apps/android

构建 WebView 壳版本：

./gradlew assembleWebRelease

构建原生 Compose 版本：

./gradlew assembleNativeRelease

Windows PowerShell 可使用：

.\gradlew.bat assembleWebRelease
.\gradlew.bat assembleNativeRelease

构建输出通常位于：

apps/android/app/build/outputs/

下载入口：

• GitHub Releases
• 在线体验

最新版本请以 GitHub Releases 为准。当前仓库文档记录的主要版本线为：

• 统一发布版：v2.2.0-beta
• Web 版：v0.5.2-alpha
• 原生 Compose 版：v0.7.2-native

v0.7.x-native 阶段的原生版重点包含：题目搜索功能、填空题可作答并自动判分、简答题支持输入作答、AI 核对/清洗提示词收紧、导入解析边界收口、题库一二级分组管理、共用题干/材料题兜底解析、LaTeX/OMML 数学公式识别、导入预览数学公式格式化、cases 分段显示优化、首页紧凑布局阈值调整、题干中含”格式”时的分区误识别修复、显示异常设备上题目文本不再被省略截断，以及退出练习时保存顺序进度。v0.5.x-native 阶段已完成智能复习模式、题目收藏与快速编辑、字号缩放与紧凑选项、批量自动切题、顺序练习进度记忆、练习页布局优化、危险操作二次确认、阅读显示偏好和构建缓存等能力。

每次发布包含 Android APK 及相关说明文档。

当前为 beta 测试阶段，功能尚在完善中，不建议用于高风险正式考试场景。

详见 30.1-30.4 / 30.5-31 / 31.0-31.5 / 31.5-32。

欢迎通过 Issue 提交：

• Bug 反馈
• 题库格式兼容问题
• 导入失败样例
• UI / 交互优化建议
• Android 适配问题
• 文档补充建议

详见：

• CONTRIBUTING.md
• CHANGELOG.md

本项目采用 GPL-3.0 开源。