csv quiz practice

Obsidian 刷题插件 / CSV-based Quiz Plugin for Obsidian

基于 CSV 文件的 Obsidian 刷题插件。将你的题库写入 CSV，然后在 Obsidian 中刷题、标记、筛选、统计正确率；支持将题库编译为 .cqv 产物分发给使用者。

A CSV-based quiz practice plugin for Obsidian. Write your question bank in a CSV file, then practice with filtering, tagging, and progress tracking; compile your bank into a .cqv artifact for distribution.

快速开始 / Quick Start

1. 在 vault 根目录创建 题库.csv（也可在设置中指定其他路径） Create 题库.csv in your vault root (or set a custom path in settings)

2. 点击左侧 ribbon 的图书图标，或执行命令 打开刷题面板 Click the book icon in the left ribbon, or run the command 打开刷题面板

3. 开始刷题 Start practicing

CSV 格式 / CSV Format

CSV 文件必须为 BOM 前缀的 UTF-8 编码，15 列：

The CSV file must be BOM-prefixed UTF-8 with 15 columns:

序号,题干,选项A,选项B,选项C,选项D,正确答案,标签,一级分类,二级分类,三级分类,收藏,掌握,重复,错题

示例行 / Example Row

1,1+1=?,1,2,3,4,B,#数学 #加法,#数学,,,1,,,

状态文件（sidecar）/ State File

每个题库在同目录下有一个同名的状态文件（题库.csv.sidecar.json），保存该题库的全部使用状态：答题记录、统计、记忆卡片（FSRS）、筛选、收藏/掌握/错题、标签与分类的修改等。切换题库时各题库状态相互独立、自动恢复，不会互相覆盖。

Each question bank has a same-name state file next to it (题库.csv.sidecar.json), holding all per-bank state: answer records, statistics, FSRS cards, filters, favorite/mastered/wrong flags, and edits to tags/categories. Switching banks restores each bank's own progress automatically — no overwriting.

• 状态写入为原子操作（临时文件 + 重命名），并每 30 分钟保留一份备份（.bak）；状态文件损坏或缺失时自动从备份恢复 State writes are atomic (temp file + rename) with a 30-minute backup (.bak); corrupted or missing state files are auto-recovered from backup
• 重置进度请使用设置页「重置刷题进度」按钮；手动删除状态文件会被备份自动恢复 Reset progress via the settings page "Reset Progress" button; manually deleting the state file is auto-restored from backup
• 升级自旧版本时，旧进度自动迁移至状态文件，原 data.json 备份为 data.json.bak（如需回滚可手工恢复） When upgrading from older versions, legacy progress is migrated automatically and data.json is backed up as data.json.bak for manual rollback

功能 / Features

刷题 / Practice

• 选择答案后实时反馈对错，显示正确答案 Instant feedback on answer selection with the correct answer shown
• 答对自动跳转：可设置延迟秒数后自动进入下一题 Auto-advance: auto-next with configurable delay on correct answer
• 随机题目顺序：每次加载时重新排列题目；开关切换保留答题进度，仅重排显示顺序（关闭时恢复 CSV 默认顺序） Random order: shuffle questions on each load; toggling preserves progress and only reorders (off = back to CSV order)
• 随机选项顺序：每题选项随机排列 Random options: shuffle answer options per question
• 键盘切题：面板聚焦时左右方向键切换上/下一题（输入框中不受影响） Keyboard navigation: arrow keys move between questions when the panel is focused (inputs unaffected)
• 滑动切题（移动端）：面板内左右滑动切换题目，可设置关闭 Swipe navigation (mobile): swipe left/right to switch questions, configurable

练习模式 / Practice Modes

• 随机考试：按当前筛选条件从全部题目（不限未答）随机抽取作为考试集，题数可在设置中修改（默认 100，不足自适应） Random exam: pick a configurable number of questions (default 100, respecting current filters, answered or not) as an exam set
• 记忆练习（FSRS 间隔重复）：基于记忆曲线的智能复习 Memory practice (FSRS spaced repetition): smart review based on memory curve
  • 选题 = 到期复习题（按紧迫度排序）+ 每日新题（数量可配置，按自然日累计，每题库独立配额） Practice set = due reviews (sorted by urgency) + daily new questions (configurable quota, per-day, per-bank)
  • 答对按 FSRS 拉长复习间隔，答错进入再学习并在当天重现 Correct answers extend intervals via FSRS; mistakes trigger relearning and reappear the same day
  • 练习集中显著标明题目来源：🆕 新题 / 🔁 复习 Question source is clearly labeled: 🆕 new / 🔁 review
  • 掌握参与评分（可关闭）：掌握题答对按 Easy（少复习）、其余一律 Good；收藏不参与评分（避免难度虚高与间隔压缩）；答错一律 Again Mastery-aware rating (optional): mastered questions answered correctly count as Easy, others as Good; favorites do not affect rating (prevents artificial difficulty inflation and interval compression); wrong answers always count as Again
  • 练习模式下统计显示本次会话答题结果，不污染全局正确率 Practice mode shows per-session stats, leaving global accuracy untouched
  • 题目页眉底部可折叠「记忆卡片」信息栏，查看每题 FSRS 状态（难度/稳定性/到期时间等） Collapsible "memory card" panel shows each question's FSRS state (difficulty/stability/due, etc.)
  • 首次启用时若已有答题记录但无记忆数据，会提示重置进度后再开始 First enable with existing progress but no memory data prompts a reset before starting

筛选 / Filtering

• 标签筛选：点击标签芯片切换，支持多标签交集 Tag filter: clickable tag chips with multi-tag intersection matching
• 分类筛选：三级分类联动下拉筛选 Category filter: 3-level cascading dropdown filters
• 标记筛选：收藏/掌握/重复/错题三态切换（不限 / 仅 / 否） Boolean filters: favorite/mastered/repeat/wrong — three states (any / yes / no)
• 未答题筛选：仅显示未作答 / 仅显示已作答 Unanswered filter: show only unanswered / only answered questions
• 筛选结果自动更新题目列表和进度；每个题库记住自己的筛选 Question list and progress update automatically on filter change; filters are remembered per bank

编辑 / Editing

• 答题过程中可编辑当前题目的标签、分类和标记（收藏/掌握/重复/错题） Edit tags, categories, and flags of the current question during practice
• 修改自动保存到状态文件（不修改题库文件本身） Changes auto-save to the state file (the bank file itself is not modified)
• 导出修改到 CSV（编辑者用）：把状态文件中的标签/分类/重复修改写回 CSV 并清除对应覆盖，随题库一起发布 Export changes to CSV (for bank authors): write tag/category/repeat edits from the state file back into the CSV and clear the overrides, so they ship with the bank

编译产物（.cqv）/ Compiled Bank (.cqv)

• 设置页「优化题库」：把 CSV 编译为同目录 .cqv 二进制产物（校验题号质量，可附一句备注），随产物分发 Settings page "Optimize Bank": compile the CSV into a .cqv binary artifact next to it (ID quality validated, optional note), for distribution
• 使用者把 .cqv 设为题库路径即可使用：产物只读、解析更快、不会被误改；产物更新后状态按题号自动对齐 Consumers set the .cqv as the bank path: read-only, faster to load, safe from accidental edits; state stays aligned by question ID when the artifact is updated
• .cqv 与同名 CSV 的状态文件相互独立（同题库换格式 = 换状态） The .cqv and its CSV counterpart keep separate state files (switching format = separate state)

进度持久化 / Persistence

• 答题记录、正确率、当前进度自动保存到状态文件 Answers, accuracy, and current position are automatically saved to the state file
• 关闭后重新打开，自动恢复到上次位置与上次题库 Resumes from where you left off after reopening Obsidian
• 多题库切换：切换题库路径时保留各自进度，切换前自动落盘；有进度的题库切换时弹轻量确认 Multi-bank switching: each bank keeps its own progress, flushed before switching; a light confirmation appears when switching away from a bank with progress
• 分项重置进度：重置时可选「仅清理刷题记录 / 仅删除记忆卡片 / 重置题目顺序 / 全部重置」，筛选条件保留；全部重置会清空状态标记并重读题库 Selective reset: choose to clear answer records only, memory cards only, reset question order, or everything (filters preserved); a full reset also clears state flags and reloads the bank

设置项 / Settings

安装 / Installation

1. Obsidian 设置 → 社区插件 → 浏览 → 搜索 "csv quiz practice" Obsidian Settings → Community plugins → Browse → Search "csv quiz practice"

2. 或手动安装：将 main.js + manifest.json + styles.css 复制到 vault 的 .obsidian/plugins/csv-quiz-practice/，然后重载 Obsidian Or install manually: copy main.js, manifest.json, and styles.css to your vault's .obsidian/plugins/csv-quiz-practice/ and reload Obsidian