核心分析¶

问题核心：评估何时应选择 hashcards，以及哪些使用场景是不适合的。

何时推荐使用¶

• 技术用户首选：你偏好在编辑器中用 Markdown 管理卡片并把学习流程纳入代码式工作流（Makefile、脚本）。
• 重视数据所有权与审计：需要可 diff、可回溯的学习记录并希望本地保存所有数据（无云依赖）。
• 希望脚本化/可编排：需要把卡片生成、检查、导出等步骤自动化（CI、pre-commit hooks）。

不建议使用的场景¶

• 需要内建云同步或移动客户端：hashcards 不提供官方云/移动客户端，跨设备实时同步需自行实现。
• 依赖复杂模板/多字段笔记：仅支持 front-back 与 cloze 两种类型，不适合需要 Anki 风格复杂模板与牌组逻辑的用户。
• 多人协作或高并发写入：SQLite 与本地设计假定单用户使用，多人并发会引入一致性与锁竞争问题。

替代方案简要对比¶

• Anki/AnkiConnect：如果你需要丰富模板、移动端与广泛插件生态，Anki 更成熟，但会牺牲纯文本可审计性。
• 服务化 SRS（带服务器/同步）：适合团队或跨设备同步，但需要运行/托管额外基础设施。

重要提示：在选择前衡量你对“可审计/可脚本化”与“移动/同步/模板丰富性”之间的优先级；hashcards 在前者占优。

总结：hashcards 适合单机、技术导向且重视数据可控性的用户；若你的首要需求是跨设备无缝体验或复杂卡型，则应选择更完整的 GUI/服务化替代方案。

核心分析¶

项目定位：hashcards 的核心问题是让间隔重复（SRS）以纯文本为第一公民、可审计且可脚本化地运作，避免被封闭客户端或二进制笔记库锁定。

技术特点¶

• 纯文本存储：卡片以 Markdown/plain-text 文件为源，便于在编辑器中编辑并用 VCS 跟踪。
• 内容寻址：卡片 ID 为卡片文本哈希，编辑会显式重置该卡的进度，保证可追溯性。
• 本地状态存储：使用 SQLite (hashcards.db) 保存表现与历史，所有数据本地化，隐私友好。
• 现代调度：采用 FSRS 调度算法以提高复习效率。

实用建议¶

1. 开始步骤：用 git 管理卡片目录，创建 Markdown 卡片，运行 hashcards drill <DIR> 启动本地复习界面（默认 http://localhost:8000）。
2. 组织策略：使用 TOML frontmatter 指定 deck 名称，保持文件名与目录结构一致以便于检索。

注意事项¶

• 编辑即重置：任何文本改动会改变哈希并重置进度；在大规模编辑前备份 hashcards.db 或导出数据。
• 会话保存时机：进度仅在会话结束时保存，浏览器崩溃或提前关闭会导致丢失未提交的更改。

重要提示：该工具面向熟悉命令行与 VCS 的用户；非技术用户可能面对构建与运行的学习成本。

总结：hashcards 以内容寻址与纯文本工作流为核心，为技术用户提供了可审计、可编排且高效的本地 SRS 方案，适合对数据可控性有较高要求的场景。

核心分析¶

问题核心：新用户面临的主要障碍是构建/运行环境、会话保存语义与资源路径管理。熟悉命令行与文本工具的用户会更快上手。

技术分析¶

• 上手要点：
• 需要 Rust 的 cargo 或可用的二进制发布来构建/安装（make、sudo make install）。
• 启动复习用 hashcards drill <DIR>，默认在 http://localhost:8000 打开本地 web 界面。
• 常见问题：
• 会话未即时保存：进度仅在会话结束时保存，浏览器崩溃会丢失未提交评分。
• 资源路径错误：图片/音频路径默认相对 deck，需要使用 @/ 或维护一致目录结构。
• 编辑导致重置：频繁微调会改变哈希并重置进度。

推荐入门流程¶

1. 环境准备：安装 rustup/cargo 或获取项目发布的二进制；验证 hashcards --help 可用。
2. 示例仓库：克隆并试用作者的示例卡片库，观察 drill 行为。
3. 版本控制：把卡片目录放入 git，并在每次大改动前 git commit。
4. 备份：在大规模改动前备份 hashcards.db 或导出 JSON (hashcards export)。
5. 路径规范：统一图片/音频相对路径或使用 @/ 约定。

重要提示：始终在做批量编辑前备份数据库，并在复习会话完成后再关闭浏览器以确保进度保存。

总结：对于目标技术用户，哈希卡的上手成本主要在环境与工作流约定，通过示例仓库、版本控制与备份策略可以快速减少常见失误并稳定使用体验。

核心分析¶

问题核心：内容寻址（卡片 ID = 文本哈希）提高了可追溯性与确定性，但会使编辑行为直接影响学习进度，带来实际操作上的摩擦。

技术分析¶

• 优势：
• 确定性：任何变更都会显式导致哈希变化，避免了“看似相同但内部不同”的不一致问题。
• 可审计：结合 VCS，可以完整地追溯每次文本变更与进度重置的时间点。
• 挑战：
• 频繁重置：微小格式化或编辑器自动换行会重置进度，影响学习连续性。
• 数据库膨胀：删除/重命名后会产生 orphan 条目，需要手动清理。

实用建议¶

1. 建立编辑规范：约定空白、换行与 Markdown 风格，避免无意义修改触发哈希变化。
2. 预备操作：在批量重写或格式化前，git commit 与备份 hashcards.db；必要时导出 JSON 用于后续迁移。
3. 脚本化迁移：若必须批量修改文本，可编写脚本计算旧哈希到新哈希的映射，并在 SQLite 中迁移相应的表现记录（或在外部保留映射以参考）。
4. 定期清理：使用 hashcards orphans list/delete 清理数据库与源不一致的条目。

重要提示：若常做微调且不想丢失进度，考虑在修改策略上优先用 追加 或创造新卡而非改写现有卡，或先导出历史以便重建映射。

总结：内容寻址带来审计与确定性好处，但会增加编辑成本。通过规范、备份与脚本化迁移可将风险降至可控水平。

核心分析¶

问题核心：如何把 hashcards 融入 git + Makefile 的自动化工作流以实现可重复的维护、备份与部署？

技术分析¶

• 可用构件：hashcards 提供 drill、check、orphans、export 等 CLI，可被 Makefile 和 CI 脚本调用；卡片为纯文本，适合用标准 Unix 工具处理。
• 常见自动化场景：校验、备份、导出、启动复习、清理孤立条目。

推荐实践（Makefile 模式）¶

1. 基本目标：
   - make check → hashcards check cards/
   - make export → hashcards export cards/ > exports/$(date).json
   - make orphans-clean → hashcards orphans delete cards/
2. 备份策略：在 make export 前先停止可能的复习会话或检测端口占用，确保导出的一致性；将 JSON 导出与 hashcards.db 备份一起保存到版本库外的归档位置。
3. Git 集成：在 pre-commit hook 中运行 make check 或更轻量的脚本以防止提交格式错误的卡片。
4. 模板与新卡流程：定义 make new 以创建标准 Markdown 模板并自动 git add，保证卡片格式一致。

注意事项¶

• 会话冲突：复习会话写入与自动化脚本同时访问 SQLite 时可能造成锁，需要在脚本中处理互斥。
• 大规模修改：在批量修改卡片前通过 make export 备份数据并在更改后验证 orphan 条目。

重要提示：把文本目录作为事实源（single source of truth），通过 Makefile 将常用命令编排成可重复的步骤，可以大幅降低手动错误并便于审计。

总结：hashcards 的 CLI 设计天然适合与 git + Makefile 集成；通过封装检查、备份与导出步骤，你可以实现可靠且可审计的自动化工作流。

核心分析¶

问题核心：如何在日常与大规模使用中保证 hashcards.db 与纯文本源的一致性，管理孤立条目，并制定可维护的归档策略？

技术分析¶

• 可用工具：hashcards check（完整性检查）、hashcards orphans list/delete（管理孤立条目）、hashcards export（导出 JSON）是维护一致性的主要手段。
• 常见问题：数据库会保留已删除卡片的历史（orphans）；批量编辑会产生大量新哈希；并发写入会导致 SQLite 锁争用。

维护与操作流程（推荐）¶

1. 每日/每次修改前后：
   - git commit 文本变化；
   - hashcards export 导出当前状态到 timestamped JSON，作为热备份；
2. 一致性检查：在 CI 或定期任务中运行 hashcards check，发现语法或解析问题提前修复；
3. 孤立条目处理：定期运行 hashcards orphans list，人工审查后使用 orphans delete 清理数据库；
4. 批量修改策略：在批量重写前备份 hashcards.db 并生成旧哈希到新哈希的映射脚本，以便必要时迁移表现记录；
5. 大集合集成：按主题分 deck 并对老旧数据归档（备份旧的 hashcards.db 到只读归档），避免单一数据库无限增长。

并发与自动化注意事项¶

• 避免并发写入：在自动化脚本中实现文件锁或检测复习会话端口，确保在做导出/写数据库时没有活动会话。
• 备份优先：任何迁移或批量改动前先导出 JSON 并备份数据库文件。

重要提示：孤立条目本身不是错误，但会造成历史与源的不一致；定期审查并决定是删除还是迁移关联表现数据。

总结：结合内置 CLI、git 与脚本化流程，你可以在单用户与中等规模集合下维持高一致性；对大规模或并发场景，需引入分区、归档或集中化状态服务。