间隔重复系统（Spaced Repetition System）是高效学习的利器，但传统工具如 Anki 和 Mochi 在数据所有权和编辑体验上存在诸多限制。Hashcards 应运而生，它采用纯文本存储、本地优先的设计理念，将间隔重复系统的核心功能与 Unix 哲学完美结合。本文将深入探讨 Hashcards 的工程实现细节，包括文件格式设计、调度算法集成、数据持久化策略以及实际工作流。
设计哲学：纯文本与本地优先
Hashcards 的核心设计理念可以概括为两点：纯文本存储和本地优先。与 Anki 使用专有数据库或 Mochi 依赖云端同步不同，Hashcards 将用户的闪卡集合存储为普通的 Markdown 文件。这种设计带来了多重优势：
- 完全的数据所有权：用户拥有闪卡文件的完全控制权，无需担心服务关闭或数据迁移问题
- 无缝的编辑体验：可以使用任何文本编辑器（Vim、VS Code、Sublime Text 等）编辑闪卡
- 版本控制友好：闪卡文件天然适合 Git 版本控制，可以追踪历史变更、分支合并
- 脚本化操作：可以使用 Unix 工具（grep、awk、sed）或编程语言批量处理闪卡
正如 Hashcards 作者 Fernando Borretti 所言："Markdown files in a Git repo gives me a level of ownership that other approaches lack." 这种设计哲学反映了对用户数据主权的尊重，也符合现代开发者对透明度和控制权的需求。
文件格式设计：简约而不简单
Hashcards 的文件格式设计体现了 "最小化摩擦" 的原则。闪卡集合是一个目录结构，每个 Markdown 文件代表一个牌组：
Cards/
Math.md
Chemistry.md
Astronomy.md
...
每个牌组文件的内容格式如下：
Q: What is the role of synaptic vesicles?
A: They store neurotransmitters for release at the synaptic terminal.
Q: What is a neurite?
A: A projection from a neuron: either an axon or a dendrite.
C: Speech is [produced] in [Broca's] area.
C: Speech is [understood] in [Wernicke's] area.
格式设计的工程考量
- 卡片类型标识：
Q:表示问答卡，C:表示填空卡（Cloze deletion） - 填空语法优化：使用方括号
[]而非 Mochi 的花括号{{}}，因为方括号在美式键盘上无需按 Shift 键 - 多行支持：问答卡使用多行格式而非单行分隔符，以支持复杂的多行内容
- 视觉分隔：空行分隔不同卡片，便于人工阅读和编辑
这种格式设计经过了反复迭代。最初版本使用单行格式 问题 / 答案，但无法优雅处理多行内容。最终方案在简洁性和功能性之间找到了平衡点。
FSRS 算法集成：现代间隔重复调度
Hashcards 采用 FSRS（Free Spaced Repetition Scheduler）算法，这是目前最先进的间隔重复调度算法。与 Anki 默认的 SM-2 算法相比，FSRS 在保持相同记忆率的情况下可以减少约 30% 的复习时间。
FSRS 的核心概念
FSRS 基于三组件记忆模型（DSR Model），将记忆状态建模为三个变量：
- 可提取性（Retrievability, R）：回忆概率，范围 [0, 1]
- 稳定性（Stability, S）：记忆衰减到 90% 概率所需时间（天）
- 难度（Difficulty, D）：记忆难度，范围 [1, 10]
算法的核心方程是：
[ R(t) = \left( 1 + F\frac{t}{S} \right)^C ]
其中 (t) 是距离上次复习的天数，( F ) 和 ( C ) 是控制曲线形状的常数。这个方程描述了记忆随时间衰减的数学模型。
四等级评分系统
FSRS 使用四等级评分系统，比 Mochi 的两按钮系统更精细：
- 1 分（忘记）：完全无法回忆
- 2 分（困难）：能够回忆但很困难
- 3 分（良好）：正常回忆
- 4 分（容易）：轻松回忆
每个等级对应不同的稳定性更新策略，算法会根据用户的评分动态调整下次复习间隔。
内容寻址与数据持久化
Hashcards 采用内容寻址机制：每张卡片通过其文本内容的哈希值唯一标识。这种设计带来了重要的工程优势：
哈希标识的优势
- 确定性标识：相同内容的卡片具有相同 ID，便于去重和合并
- 编辑安全：修改卡片内容会生成新哈希，旧版本仍可追踪
- 引用完整性：复习历史通过哈希引用卡片，即使卡片内容修改，历史记录仍然有效
SQLite 数据库设计
虽然闪卡内容存储在纯文本文件中，但复习性能数据需要结构化存储。Hashcards 使用 SQLite 数据库存储以下信息：
-- 简化的数据库模式
CREATE TABLE cards (
hash TEXT PRIMARY KEY, -- 卡片内容哈希
deck_path TEXT, -- 所属牌组路径
stability REAL, -- 记忆稳定性
difficulty REAL, -- 记忆难度
last_review INTEGER, -- 上次复习时间戳
next_review INTEGER, -- 下次复习时间戳
review_count INTEGER, -- 复习次数
lapse_count INTEGER -- 忘记次数
);
CREATE TABLE reviews (
id INTEGER PRIMARY KEY,
card_hash TEXT, -- 关联卡片哈希
timestamp INTEGER, -- 复习时间
grade INTEGER, -- 评分 (1-4)
elapsed_days REAL, -- 距离上次复习天数
FOREIGN KEY (card_hash) REFERENCES cards(hash)
);
这种混合存储策略结合了纯文本的灵活性和关系数据库的查询能力。数据库文件与闪卡文件存储在同一目录，便于整体备份和同步。
工程实现细节
命令行接口设计
Hashcards 提供简洁的命令行接口：
# 启动复习会话
$ hashcards drill ./Cards
# 查看统计信息
$ hashcards stats ./Cards
# 导出复习数据
$ hashcards export ./Cards --format csv
hashcards drill 命令启动本地 Web 服务器（默认端口 8000），提供图形化的复习界面。这种设计分离了数据存储（纯文本）和用户界面（Web），既保持了数据的可访问性，又提供了良好的用户体验。
卡片解析器实现
卡片解析器需要处理多种边缘情况：
// 简化的解析逻辑
fn parse_card(lines: &[String]) -> Option<Card> {
if lines.is_empty() {
return None;
}
let first_line = &lines[0];
if first_line.starts_with("Q:") {
// 解析问答卡
parse_qa_card(lines)
} else if first_line.starts_with("C:") {
// 解析填空卡
parse_cloze_card(lines)
} else {
None
}
}
fn parse_cloze_card(lines: &[String]) -> Card {
let content = lines.join("\n");
let cloze_pattern = Regex::new(r"\[([^\]]+)\]").unwrap();
let cloze_count = cloze_pattern.captures_iter(&content).count();
Card {
content,
card_type: CardType::Cloze(cloze_count),
hash: sha256(&content),
}
}
复习调度器实现
复习调度器需要集成 FSRS 算法：
struct FSRScheduler {
params: FSRSParams, // FSRS 参数
retention_target: f64, // 目标记忆率 (默认 0.9)
}
impl FSRScheduler {
fn schedule_review(&self, card: &mut Card, grade: Grade) {
let elapsed_days = self.calculate_elapsed_days(card);
let retrievability = self.calculate_retrievability(elapsed_days, card.stability);
// 更新稳定性和难度
card.stability = self.update_stability(card.stability, card.difficulty, grade, retrievability);
card.difficulty = self.update_difficulty(card.difficulty, grade);
// 计算下次复习间隔
let interval = self.calculate_interval(card.stability, self.retention_target);
card.next_review = now() + interval_days(interval);
// 记录复习历史
self.record_review(card.hash, grade, elapsed_days);
}
}
实际工作流与最佳实践
Git 版本控制工作流
Hashcards 与 Git 的集成创造了独特的工作流：
- 分支学习：为不同学习主题创建分支
- 提交信息规范：使用有意义的提交信息记录学习进展
- 合并复习：定期合并分支，保持知识体系完整
- 历史追溯：通过 Git 历史查看学习历程
# 典型的工作流示例
$ git checkout -b neuroscience-chapter3
$ vim Cards/Neuroscience.md # 添加新卡片
$ git add Cards/Neuroscience.md
$ git commit -m "添加第三章：突触传递相关卡片"
$ hashcards drill ./Cards # 复习卡片
$ git checkout main
$ git merge neuroscience-chapter3
脚本化卡片生成
纯文本格式便于脚本化操作。例如，从 CSV 生成语言学习卡片：
import csv
import hashlib
def generate_flashcards(csv_path, output_path):
with open(csv_path, 'r', encoding='utf-8') as f:
reader = csv.DictReader(f)
with open(output_path, 'w', encoding='utf-8') as out:
for row in reader:
english = row['english']
french = row['french']
# 生成双向卡片
out.write(f"Q: What is the French for '{english}'?\n")
out.write(f"A: {french}\n\n")
out.write(f"Q: What is the English for '{french}'?\n")
out.write(f"A: {english}\n\n")
# 生成填空卡片
out.write(f"C: '{english}' in French is [{french}].\n\n")
# 使用 Makefile 自动化
# Makefile 内容：
# all: Cards/French.md
#
# Cards/French.md: data/vocabulary.csv
# python generate_cards.py $< $@
跨平台同步策略
虽然 Hashcards 是本地优先工具，但可以通过多种方式实现跨设备同步：
- Git 远程仓库：使用 GitHub、GitLab 或自建 Git 服务器
- 同步工具：使用 Syncthing、Dropbox、Nextcloud 等
- 定时同步脚本：编写自动化同步脚本
#!/bin/bash
# 同步脚本示例
cd ~/Flashcards
git pull origin main
hashcards drill ./Cards
# 复习完成后自动提交和推送
git add .
git commit -m "复习记录 $(date)"
git push origin main
性能优化与监控
数据库索引优化
对于大型闪卡集合（数千张卡片），数据库性能至关重要：
-- 创建优化索引
CREATE INDEX idx_cards_next_review ON cards(next_review);
CREATE INDEX idx_cards_deck ON cards(deck_path);
CREATE INDEX idx_reviews_card ON reviews(card_hash);
-- 定期清理旧数据
DELETE FROM reviews WHERE timestamp < unixepoch('now', '-365 days');
复习负载均衡
为了避免 "复习堆积" 问题，可以实施负载均衡策略：
impl ReviewScheduler {
fn balance_daily_reviews(&self, cards: &[Card], max_per_day: usize) -> Vec<Card> {
let mut due_cards: Vec<_> = cards.iter()
.filter(|c| c.is_due())
.collect();
// 按优先级排序：逾期时间 > 稳定性 > 难度
due_cards.sort_by(|a, b| {
a.days_overdue()
.partial_cmp(&b.days_overdue())
.unwrap()
.reverse()
.then(a.stability.partial_cmp(&b.stability).unwrap())
.then(a.difficulty.partial_cmp(&b.difficulty).unwrap())
});
due_cards.into_iter()
.take(max_per_day)
.cloned()
.collect()
}
}
学习进度监控
通过分析复习数据监控学习效果：
import sqlite3
import pandas as pd
from datetime import datetime, timedelta
def analyze_learning_progress(db_path):
conn = sqlite3.connect(db_path)
# 计算每日复习统计
daily_stats = pd.read_sql("""
SELECT
date(timestamp, 'unixepoch') as date,
COUNT(*) as review_count,
AVG(grade) as avg_grade,
SUM(CASE WHEN grade = 1 THEN 1 ELSE 0 END) as forgot_count
FROM reviews
WHERE timestamp > unixepoch('now', '-30 days')
GROUP BY date
ORDER BY date
""", conn)
# 计算记忆保留率
retention_rate = pd.read_sql("""
SELECT
deck_path,
COUNT(*) as total_cards,
AVG(stability) as avg_stability,
SUM(CASE WHEN next_review > unixepoch() THEN 1 ELSE 0 END) as active_cards
FROM cards
GROUP BY deck_path
""", conn)
return {
'daily_stats': daily_stats,
'retention_by_deck': retention_rate,
'estimated_review_time': calculate_review_time(daily_stats)
}
局限性与未来方向
当前局限性
- 多媒体支持有限：纯文本格式不适合图像、音频等多媒体内容
- 学习曲线较陡：需要命令行操作和 Git 知识
- 移动端支持不足：主要面向桌面环境
- 社区生态薄弱：缺乏 Anki 那样的插件生态系统
改进方向
- 渐进式增强：为高级用户提供扩展格式支持
- 图形界面封装：开发更友好的桌面应用
- 移动端适配：开发移动应用或 PWA
- 标准化格式：推动纯文本闪卡格式成为开放标准
结语
Hashcards 代表了间隔重复系统设计的新范式：将复杂的学习算法与简单的数据格式相结合，将用户的数据所有权放在首位。通过纯文本存储、内容寻址、FSRS 算法和 Git 集成，它创造了一个透明、可控、高效的学习环境。
对于技术用户来说，Hashcards 提供了无与伦比的灵活性和控制力。对于普通用户，它展示了软件设计应该如何尊重用户的数据主权。正如开源运动所倡导的，真正的工具应该赋予用户权力，而不是将用户锁定在特定的平台或格式中。
在数据隐私日益重要的今天，Hashcards 的设计哲学值得所有工具开发者借鉴。它证明，优秀的用户体验不需要以牺牲用户控制权为代价，透明度和功能性可以和谐共存。
资料来源：