1. 先搞清楚 Hanky 到底解决什么实际问题如果你用过 Anki 做知识卡片肯定遇到过这种情况手头有一堆笔记、代码片段、API 文档或者网页内容想批量转成 Anki 卡片但手动复制粘贴太费时间格式还容易乱。Hanky 就是专门解决这个痛点的 ETL 风格框架——它把数据提取Extract、转换Transform、加载Load这套流程标准化让你能用代码批量处理各种来源的内容自动生成标准化的 Anki 卡片。和直接手敲卡片或者用 Anki 的 CSV 导入相比Hanky 最大的优势是能处理非结构化数据。比如你可以写个脚本抓取 GitHub 项目的 README把代码示例和说明自动拆分成问答卡或者把一长段技术文档按章节转成记忆点。它不是一个独立工具而是基于 Python 的框架你需要写少量代码定义数据流但一旦跑通后续批量更新或调整格式会非常高效。适合用 Hanky 的人至少得懂一点 Python 基础语法能在本地跑通脚本。如果你经常需要把技术文档、学习笔记、代码注释批量转化成复习材料这个框架能省下大量重复劳动。但如果你只是偶尔做几张卡片或者数据来源很固定比如纯文本列表可能直接用手动导入更直接。2. 环境准备和依赖确认Hanky 本身是 Python 包官方要求 Python 3.8。我建议先用python --version确认本地版本低于 3.8 的话需要升级。虚拟环境不是必须但如果你经常折腾不同 Python 项目最好用venv或conda隔离一下避免包冲突。核心依赖就两个hanky框架本身和genankiAnki 牌组生成的底层库。安装命令很简单pip install hanky genanki如果网络不稳定可以换国内镜像源比如pip install -i https://pypi.tuna.tsinghua.edu.cn/simple hanky genanki安装完成后不要急着写复杂脚本先跑个最小验证样例。打开 Python 解释器输入import hanky print(hanky.__version__)能输出版本号就说明基础环境没问题。如果报错优先看 pip 是否最新、网络是否通畅、Python 环境是否混用比如系统自带的 Python 和 Homebrew 安装的冲突。除了 Python 环境还需要本机安装 Anki 桌面版免费版就行因为 Hanky 生成的是.apkg文件需要导入 Anki 才能同步到手机或网页端。Anki 的安装直接官网下载对应系统版本按向导完成即可这里不展开。3. 理解 ETL 在卡片生成中的具体环节Hanky 的 ETL 流程和传统数据工程很像但针对卡片生成做了简化。三个环节的具体任务如下提取Extract数据来源可以是本地文件txt、md、json、csv、网页链接、数据库查询结果甚至 API 返回的数据。Hanky 不限制数据获取方式你可以用requests抓网页、用pandas读表格、用os.walk遍历目录——只要最终能拿到结构化或半结构化的 Python 对象比如字典列表、字符串数组就行。转换Transform这是最需要定制代码的部分。原始数据往往不能直接当卡片用比如一篇技术博客可能包含标题、代码块、说明文字你需要拆解成“问题-答案”对。转换环节就是写 Python 函数处理原始数据返回卡片的字段内容。常见操作包括文本清洗去空格、换行符标准化、分段、提取关键句、添加标签等。加载LoadHanky 通过genanki库把转换后的数据打包成 Anki 可识别的牌组Deck和模型Model。你需要定义卡片模板比如基础型、反转型、填空型指定哪些字段对应正面、背面、标签然后调用导出函数生成.apkg文件。整个流程的核心是“配置优于重复劳动”。一旦写好 ETL 脚本下次只需更新数据源重新运行就能批量刷新卡片内容特别适合追更技术文档、同步代码库注释或定期复习重点。4. 从单条数据跑通最小可行流程新手最容易犯的错误是一开始就想处理几百条数据结果卡在格式报错或路径问题上。我建议先用一条样例数据跑通全流程再扩展批量处理。以下是一个可运行的完整示例假设你有一个 Python 列表里面是简单的问答对想转成 Anki 卡片。先创建demo.py文件内容如下from hanky import Extractor, Transformer, Loader # 1. 提取环节模拟数据源 class DemoExtractor(Extractor): def extract(self): return [ {question: Python 的列表推导式语法, answer: [x for x in iterable]}, {question: 如何安装 Python 包, answer: 使用 pip install 包名} ] # 2. 转换环节清洗或增强字段这里直接返回 class DemoTransformer(Transformer): def transform(self, record): return { front: record[question], back: record[answer], tags: python基础 } # 3. 加载环节定义卡片模板并导出 class DemoLoader(Loader): def load(self, records): from genanki import Deck, Model, Note, Package # 定义卡片模型模板 model_id 1607392319 model Model( model_id, 简单问答模型, fields[{name: Front}, {name: Back}], templates[{ name: 卡片1, qfmt: {{Front}}, afmt: {{FrontSide}}hr idanswer{{Back}}, }] ) # 创建牌组 deck_id 2059400110 deck Deck(deck_id, 演示牌组) # 添加卡片 for record in records: note Note( modelmodel, fields[record[front], record[back]] ) deck.add_note(note) # 导出文件 Package(deck).write_to_file(demo_cards.apkg) print(生成完成demo_cards.apkg) # 运行流程 extractor DemoExtractor() transformer DemoTransformer() loader DemoLoader() data extractor.extract() transformed_data [transformer.transform(record) for record in data] loader.load(transformed_data)在终端执行python demo.py如果同级目录生成demo_cards.apkg文件就可以双击导入 Anki。导入时 Anki 会询问是否合并到现有牌组选“添加”即可。这个例子虽然简单但包含了 ETL 三个核心类的继承和调用顺序。成功跑通后你就能清楚看到数据怎么流动后续再改数据源或转换逻辑就有底了。5. 处理真实场景的复杂数据源单条样例跑通后接下来处理更真实的数据源。比如把本地 Markdown 文件的技术笔记转成卡片。假设你有一个notes.md文件内容如下# Git 命令 ## 基础操作 - git init: 初始化仓库 用途创建新的 Git 仓库 ## 分支管理 - git branch: 查看分支 用途列出所有本地分支目标是提取每个命令作为问题用途作为答案。提取环节需要读取文件并解析段落转换环节要用正则或字符串分割提取命令和说明。修改提取器类import re class MarkdownExtractor(Extractor): def __init__(self, file_path): self.file_path file_path def extract(self): with open(self.file_path, r, encodingutf-8) as f: content f.read() # 用正则匹配 - 命令: 说明 格式 pattern r- (.?):\s*(.) matches re.findall(pattern, content) records [] for cmd, desc in matches: records.append({command: cmd, description: desc}) return records转换器类调整字段映射class MarkdownTransformer(Transformer): def transform(self, record): return { front: fGit 命令{record[command]}, back: record[description], tags: git }主流程部分只需替换 extractor 实例extractor MarkdownExtractor(notes.md)这种基于正则的提取比较脆弱如果 Markdown 格式不统一容易漏数据。更稳妥的做法是先用 Markdown 解析库比如mistune把文档转成 AST再遍历节点提取内容。但一开始不必追求完美先保证基础流程能处理标准格式再逐步增强容错性。6. 定制卡片模板和样式默认的卡片模板可能不符合你的复习习惯。Hanky 通过genanki的 Model 类支持自定义模板和 CSS 样式。比如你想把答案隐藏为点击展开并且调整字体大小可以这样修改加载器中的 model 定义model Model( model_id, 增强型问答模型, fields[{name: Front}, {name: Back}], templates[{ name: 卡片1, qfmt: div classcard h3{{Front}}/h3 /div , afmt: div classcard h3{{Front}}/h3 hr div classanswer {{Back}} /div /div , }], css .card { font-family: Arial; font-size: 18px; text-align: center; } .answer { color: #2c3e50; margin-top: 10px; } )Anki 桌面版还支持在导入后继续调整模板但如果在生成阶段就固定样式批量更新时能保持一致性。对于技术类卡片我习惯添加等宽字体显示代码片段code { font-family: Courier New, monospace; background: #f4f4f4; padding: 2px 4px; }样式调整不需要每次重跑整个 ETL 流程可以单独修改模板代码重新执行加载环节即可。如果牌组已存在Anki 会提示是否更新模板选“是”会把新样式应用到所有现有卡片。7. 批量任务的稳定性处理单文件处理没问题后就要考虑批量任务了。比如每周抓取技术博客更新或者定期导出代码注释。这时不能只关注功能能否跑通还要处理异常和重复数据。输入文件遍历如果数据源是多个文件建议先用os.listdir或glob获取文件列表再逐个处理。但不要一次性加载所有文件内容到内存容易爆内存。更好的方式是逐个文件提取-转换-加载或者用生成器分批处理。重复卡片去重Anki 默认根据字段内容去重。但如果你经常增量更新数据源可能生成重复问题。可以在转换环节加逻辑判断比如维护一个已处理问题的集合或者根据标题、标签等生成唯一 ID。异常处理批量任务中个别数据格式错误不应该导致整个流程崩溃。用 try-except 包裹转换逻辑transformed_data [] for record in data: try: transformed_record transformer.transform(record) transformed_data.append(transformed_record) except Exception as e: print(f转换失败{record}错误{e}) continue # 跳过这条继续处理下一个日志记录批量任务一定要有日志记录处理了多少条、成功多少、失败多少、失败原因。可以用 Python 的logging模块或者简单写文件with open(process.log, w) as log_file: for i, record in enumerate(data): try: # 处理逻辑 log_file.write(f成功处理第{i}条数据\n) except Exception as e: log_file.write(f第{i}条处理失败{e}\n)这些稳定性措施在数据量小的时候可能显得多余但一旦任务规模上去能帮你快速定位问题避免重头再来。8. 与现有工作流集成Hanky 最大的价值不是替代现有工具而是桥接不同数据源和 Anki。常见集成场景包括CI/CD 流水线如果团队有技术文档库可以在文档更新后自动触发卡片生成。比如在 GitHub Actions 里添加步骤执行 Hanky 脚本把生成的.apkg文件作为制品上传供团队成员下载同步。笔记软件对接很多开发者用 Obsidian、Logseq 等工具记技术笔记。这些软件通常支持插件或导出功能可以定期把笔记导出为 Markdown再用 Hanky 转换。甚至可以直接在笔记软件里用模板语法标注哪些内容要生成卡片提取环节直接解析这些标注。API 数据同步比如把 Stack Overflow 的收藏问题、GitHub 的 star 项目描述、技术新闻摘要自动转成复习卡片。这类需求需要写特定的提取器但转换和加载逻辑可以复用。集成关键是要明确触发时机和输出目录。我一般会单独建个anki_output文件夹按日期子目录存放每次生成的牌组方便追溯和回滚。如果导入 Anki 后发现问题可以根据日期找到对应的源数据和脚本版本排查。9. 常见问题排查顺序第一次用 Hanky 最容易卡住的几个点按排查优先级排列1. 导入 Anki 时报错或卡片空白先检查加载环节的字段名是否和模板定义一致。比如模板用{{Front}}但转换器返回的字段名是front小写就会显示空白。字段名大小写必须完全匹配。2. 提取环节拿不到数据如果是文件路径问题先用os.path.exists确认文件是否存在如果是网络请求先单独测试 URL 能否访问如果是解析逻辑先打印中间结果看正则或解析器是否匹配预期内容。3. 生成的文件无法导入.apkg文件损坏常见原因是模型 ID 或牌组 ID 重复。确保每次生成使用不同的随机 ID可以用random.randint生成大整数或者固定 ID 但每次彻底重建牌组。4. 批量任务内存溢出数据量太大时不要一次性把所有记录加载到列表。用生成器分批处理或者直接边提取边转换边加载减少内存峰值。5. 中文显示乱码确保每个环节都指定了 UTF-8 编码文件读取、网络请求返回文本、Anki 模板。可以在模板的 CSS 里显式指定字体font-family: Microsoft YaHei, sans-serif;。遇到问题先隔离环节单独测试提取器能否输出预期数据再测试转换器能否正确处理单条记录最后检查加载器生成的卡片字段。用最小数据量复现问题比在几百条数据里盲目改代码高效得多。10. 什么时候不该用 Hanky虽然 Hanky 能自动化卡片生成但并不是所有场景都适合数据源极度不规则如果每个条目的格式差异很大需要大量人工判断才能拆分写转换规则的成本可能高于手动制作卡片。卡片数量很少如果每次只需要生成十几张卡片而且后续很少更新手动操作可能更直接。Hanky 的优势在批量化和可重复性。对 Anki 高级功能依赖强比如需要复杂的卡片间隔算法、多媒体嵌入、插件交互等Hanky 生成的基础卡片可能无法满足还需要在 Anki 里二次编辑。没有编程基础如果完全不会 Python学习成本会比直接使用 Anki 高很多。虽然 Hanky 的 ETL 抽象很清晰但终究需要写代码。对于大多数技术学习者我建议先手动做一段时间卡片明确自己需要记忆什么、怎么组织复习再考虑用 Hanky 自动化那些来源固定、格式规整的内容。工具是加速器但替代不了对学习内容本身的理解。Hanky 最适合的场景是你有稳定更新的结构化或半结构化数据源技术文档、代码库、API 文档等需要定期同步到 Anki并且愿意花一次性的时间搭建自动化流程。一旦跑通长期能节省大量复制粘贴时间让精力更集中在内容本身而不是格式整理上。
