在学习和记忆大量知识时Anki 凭借其科学的间隔重复算法成为了许多人的首选工具。然而手动制作高质量的卡片不仅耗时耗力而且难以保持格式一致。特别是当需要从多种数据源如网页、文档、数据库或 API批量导入内容时一个自动化的卡片生成流程就显得尤为重要。Hanky 正是为了解决这一痛点而生的 ETL 风格框架它允许开发者通过编写简单的数据处理脚本来实现卡片数据的自动抽取、转换和加载极大地提升了 Anki 卡片制作的效率和可维护性。本文将详细介绍 Hanky 框架的核心概念、安装配置、使用方法并通过一个完整的实战案例展示如何利用它来构建个性化的自动化记忆系统。1. 背景与核心概念1.1 什么是 ETLETL 是数据仓库领域的常见术语代表抽取Extract、转换Transform、加载Load三个核心步骤。在日常开发中我们经常需要从各种来源获取数据进行清洗、格式化等操作然后存入目标系统。例如从 CSV 文件读取用户信息验证并转换手机号码格式最后插入数据库。Hanky 将这一成熟的数据处理模式应用到了 Anki 卡片制作领域使得卡片生成过程变得模块化、可编程。1.2 Anki 与间隔重复系统Anki 是一款开源的间隔重复记忆软件它通过算法合理安排复习时间帮助用户高效记忆。其核心是卡片Note和卡片类型Note Type。每张卡片包含多个字段如“正面”、“反面”并属于特定的卡片类型。虽然 Anki 自带图形界面支持手动添加和导入 CSV但对于复杂、动态或大批量的数据源编程方式接入更为灵活。1.3 Hanky 框架的定位Hanky 是一个轻量级的 Python 框架它定义了清晰的 ETL 流程来生成 Anki 卡片包.apkg 文件。开发者只需实现数据抽取、转换的逻辑Hanky 负责处理 Anki 卡片模型构建和文件打包。它与 Anki 官方提供的ankiPython 库如genanki兼容但提供了更高层次的抽象强调流程的规范性和可复用性。简单来说你可以把 Hanky 看作一个“卡片流水线”的组装工具。2. 环境准备与版本说明2.1 基础环境要求在开始使用 Hanky 之前请确保你的系统满足以下基本要求操作系统Windows 10/11, macOS 10.14, 或主流的 Linux 发行版如 Ubuntu 18.04。本文示例将在 Windows 11 和 Ubuntu 22.04 上进行验证。Python 版本Python 3.8 或更高版本。Hanky 利用了较新的 Python 特性低版本可能无法运行。包管理工具推荐使用pip进行包安装。2.2 安装 Hanky 框架Hanky 可以通过 PyPI 直接安装。打开你的终端Windows 用户可使用 PowerShell 或 CMD执行以下命令pip install hanky如果你的环境中有多个 Python 版本请确保使用正确的pip例如pip3pip3 install hanky为了隔离项目环境强烈建议使用虚拟环境如venv。以下是在项目目录中创建并激活虚拟环境的步骤# 创建项目目录并进入 mkdir my_anki_etl cd my_anki_etl # 创建虚拟环境Windows python -m venv venv # 激活虚拟环境Windows PowerShell venv\Scripts\Activate.ps1 # 激活虚拟环境Windows CMD venv\Scripts\activate.bat # 创建虚拟环境macOS/Linux python3 -m venv venv # 激活虚拟环境macOS/Linux source venv/bin/activate # 在激活的虚拟环境中安装 Hanky pip install hanky2.3 验证安装安装完成后可以通过 Python 交互界面快速验证 Hanky 是否可用import hanky print(hanky.__version__) # 输出安装的版本号如果没有报错并显示版本号例如0.1.0说明安装成功。2.4 可选依赖根据你的数据源类型可能还需要安装额外的库。例如如果要从网站抓取数据可能需要requests和beautifulsoup4如果处理 Excel 文件则需要openpyxl或pandas。这些可以在需要时单独安装pip install requests beautifulsoup4 openpyxl pandas3. Hanky 核心概念与架构3.1 核心组件Hanky 框架围绕几个核心概念构建理解它们对正确使用框架至关重要。Pipeline管道这是 ETL 流程的容器负责将各个处理阶段串联起来。一个管道对应一个完整的卡片生成任务。Extractor抽取器负责从数据源获取原始数据。数据源可以是文件、数据库、API 等。你需要实现一个继承自hanky.Extractor的类。Transformer转换器负责将抽取到的原始数据转换成适合 Anki 卡片的格式。例如清理文本、添加 HTML 标签、计算额外字段等。你需要实现一个继承自hanky.Transformer的类。Loader加载器负责将转换后的数据打包成 Anki 卡片包.apkg 文件。Hanky 提供了默认的加载器通常无需自定义。3.2 工作流程一个典型的 Hanky 工作流程如下定义卡片模型Note Model确定你的卡片包含哪些字段如“单词”、“音标”、“释义”、“例句”。实现 Extractor编写代码从目标数据源读取数据通常返回一个字典列表每个字典代表一条原始记录。实现 Transformer编写代码将原始记录映射到卡片模型的字段上并进行必要的清洗和格式化。配置并运行 Pipeline将上述组件组装起来指定输出文件路径然后执行管道。3.3 与 genanki 的关系Hanky 底层依赖于genanki库来生成 Anki 包文件。genanki提供了操作 Anki 卡片、模型和卡包的低级 API而 Hanky 在其之上构建了 ETL 模式使代码结构更清晰更易于测试和维护。如果你熟悉genanki会发现 Hanky 的学习成本很低。4. 完整实战案例从单词列表生成 Anki 卡片本案例将演示一个完整的流程从一个简单的 JSON 文件模拟单词列表中读取数据经过转换后生成一个包含单词、音标、词性和释义的 Anki 卡片包。4.1 创建项目结构首先创建如下所示的目录和文件结构my_anki_project/ ├── venv/ # 虚拟环境目录由之前命令创建 ├── data/ │ └── words.json # 原始数据文件 ├── etl/ │ ├── __init__.py │ ├── extractors.py # 存放抽取器 │ └── transformers.py # 存放转换器 └── main.py # 主程序组装和运行管道4.2 准备原始数据在data/words.json文件中放入以下示例数据。这模拟了从某个词典 API 或数据库获取的原始数据。[ { word: abate, pronunciation: /əˈbeɪt/, part_of_speech: verb, definition: to become less strong }, { word: cogent, pronunciation: /ˈkəʊdʒ(ə)nt/, part_of_speech: adjective, definition: clearly and persuasively expressed }, { word: dearth, pronunciation: /dəːθ/, part_of_speech: noun, definition: a scarcity or lack of something } ]4.3 实现抽取器Extractor在etl/extractors.py文件中我们创建一个从 JSON 文件读取数据的抽取器。# etl/extractors.py import json from hanky import Extractor class JsonWordExtractor(Extractor): def __init__(self, file_path): self.file_path file_path def extract(self): 从JSON文件抽取原始单词数据 try: with open(self.file_path, r, encodingutf-8) as f: data json.load(f) print(f成功从 {self.file_path} 加载 {len(data)} 条记录。) return data except FileNotFoundError: print(f错误文件 {self.file_path} 未找到。) return [] except json.JSONDecodeError: print(f错误文件 {self.file_path} 不是有效的JSON格式。) return []这个抽取器很简单它打开指定的 JSON 文件将其内容解析为 Python 列表并返回。extract方法是所有抽取器必须实现的核心方法。4.4 实现转换器Transformer在etl/transformers.py文件中我们创建一个转换器将原始数据转换为 Anki 卡片所需的格式。# etl/transformers.py from hanky import Transformer class BasicWordTransformer(Transformer): def transform(self, raw_data): 将原始单词数据转换为Anki卡片字段 notes_data [] for item in raw_data: # 构建每个卡片的字段数据 note_fields { Word: item.get(word, ), # 单词 Pronunciation: item.get(pronunciation, ), # 音标 PartOfSpeech: item.get(part_of_speech, ), # 词性 Definition: item.get(definition, ) # 释义 } notes_data.append(note_fields) print(f转换完成共处理 {len(notes_data)} 张卡片。) return notes_data转换器的transform方法接收抽取器返回的原始数据raw_data然后遍历每一条记录从中提取出需要的字段并按照我们预设的卡片字段名如 ‘Word’, ‘Pronunciation’重新组织成一个新的字典。所有这些新字典组成的列表就是转换后的数据。4.5 定义 Anki 卡片模型在main.py中我们需要使用genanki来定义一个卡片模型。这个模型规定了卡片长什么样有哪些字段。# main.py import genanki from hanky import Pipeline from etl.extractors import JsonWordExtractor from etl.transformers import BasicWordTransformer # 1. 定义Anki卡片模型Note Model # 每个模型需要一个唯一的model_id随机生成一个大的数字即可 MY_WORD_MODEL genanki.Model( 1607392319, # 随机且唯一的模型ID Simple Word Model, fields[ {name: Word}, {name: Pronunciation}, {name: PartOfSpeech}, {name: Definition}, ], templates[ { name: Card 1, qfmt: {{Word}}br{{Pronunciation}}, # 卡片正面显示单词和音标 afmt: {{FrontSide}}hr idanswer{{PartOfSpeech}}br{{Definition}}, # 卡片反面额外显示词性和释义 }, ])这里我们定义了一个简单的模型包含四个字段。templates部分定义了卡片正反面如何显示这些字段。qfmt是问题面正面的格式afmt是答案面反面的格式。{{FrontSide}}表示在答案面也显示正面的内容。4.6 组装并运行管道继续在main.py中编写代码将各个组件组装起来并运行。# main.py (接上文代码) def main(): # 2. 创建管道实例 pipeline Pipeline( extractorJsonWordExtractor(./data/words.json), # 指定数据源 transformerBasicWordTransformer(), # 指定转换器 modelMY_WORD_MODEL, # 指定卡片模型 deck_nameMy Vocabulary Deck, # 指定卡组名称 output_path./output/my_vocabulary.apkg # 指定输出路径 ) # 3. 运行ETL管道 print(开始ETL流程...) success pipeline.run() if success: print(Anki牌组生成成功) print(f文件已保存至 {pipeline.output_path}) else: print(生成过程出现错误。) if __name__ __main__: main()4.7 运行与验证在项目根目录下运行主程序python main.py如果一切顺利你将在控制台看到类似以下的输出开始ETL流程... 成功从 ./data/words.json 加载 3 条记录。 转换完成共处理 3 张卡片。 Anki牌组生成成功 文件已保存至 ./output/my_vocabulary.apkg现在打开 Anki 软件选择“文件” - “导入”然后选择生成的my_vocabulary.apkg文件。导入后你会在牌组列表中找到 “My Vocabulary Deck”里面包含三张单词卡片。正面显示单词和音标点击显示答案后会看到词性和释义。5. 进阶用法与最佳实践5.1 处理复杂数据源上面的例子使用了静态 JSON 文件。在实际项目中你的数据源可能更复杂。从网页抓取可以在Extractor中使用requests和BeautifulSoup。# etl/extractors.py (示例) import requests from bs4 import BeautifulSoup class WebPageExtractor(Extractor): def __init__(self, url): self.url url def extract(self): response requests.get(self.url) soup BeautifulSoup(response.text, html.parser) # ... 解析网页提取数据 ... return extracted_data_list从数据库读取可以使用sqlite3、pymysql等库。# etl/extractors.py (示例) import sqlite3 class DatabaseExtractor(Extractor): def __init__(self, db_path, query): self.db_path db_path self.query query def extract(self): conn sqlite3.connect(self.db_path) cursor conn.cursor() cursor.execute(self.query) # 将查询结果转换为字典列表 columns [col[0] for col in cursor.description] data [dict(zip(columns, row)) for row in cursor.fetchall()] conn.close() return data5.2 实现复杂的转换逻辑转换器是添加业务逻辑的地方可以做很多事情数据清洗去除多余空格、纠正拼写错误。内容增强调用词典 API 获取更详细的释义、例句或发音文件。HTML 格式化为释义和例句添加样式使其在 Anki 中更美观。# etl/transformers.py (示例) class EnhancedWordTransformer(Transformer): def transform(self, raw_data): notes_data [] for item in raw_data: # 示例添加简单的HTML格式 definition_html fdiv stylecolor: blue;{item[definition]}/div note_fields { Word: item[word], Pronunciation: item[pronunciation], PartOfSpeech: fi({item[part_of_speech]})/i, # 斜体 Definition: definition_html # 蓝色字体 } notes_data.append(note_fields) return notes_data5.3 配置管理与错误处理使用配置文件将文件路径、API 密钥等信息放在配置文件如config.ini或config.json中避免硬编码。# config.json { data_source: ./data/words.json, deck_name: My Deck, output_dir: ./output }# main.py import json with open(config.json, r) as f: config json.load(f) pipeline Pipeline( extractorJsonWordExtractor(config[data_source]), # ... 其他参数使用config中的值 ... )增强错误处理在Extractor和Transformer的关键步骤添加try-except块记录日志避免因单条数据错误导致整个流程失败。5.4 卡片模型设计最佳实践保持简洁不要在一个卡片上堆砌过多信息这违背了间隔重复的初衷。字段原子化每个字段只存储一类信息如将“例句”和“例句翻译”分成两个字段方便后期处理和样式调整。利用 CSS在卡片模型中使用自定义 CSS 来统一卡片样式提升美观度。# 在genanki.Model中增加css参数 MY_WORD_MODEL genanki.Model( # ... model_id, name, fields, templates ... css .card { font-family: arial; font-size: 20px; text-align: center; color: black; background-color: white; } .part-of-speech { font-style: italic; color: green; } ) # 然后在模板中使用class # qfmt: {{Word}}brspan classpronunciation{{Pronunciation}}/span6. 常见问题与排查思路在使用 Hanky 过程中可能会遇到一些典型问题。下表列出了常见现象、原因及解决方法。问题现象可能原因解决思路运行python main.py报ModuleNotFoundError: No module named hanky1. Hanky 未安装。2. 未在正确的虚拟环境中运行。3. Python 环境混乱。1. 运行pip install hanky确认安装。2. 检查终端提示符前是否有(venv)字样确保虚拟环境已激活。3. 使用which python(macOS/Linux) 或where python(Windows) 检查当前使用的 Python 解释器是否正确。管道运行成功但生成的 .apkg 文件导入 Anki 后无内容或报错。1. 转换器返回的数据格式不正确。2. 卡片模型的字段名与转换器输出的字段名不匹配。3. 数据本身为空。1. 在Transformer的transform方法中打印notes_data检查其结构是否为字典列表且字典的 key 与模型字段名完全一致。2. 仔细核对Model的fields的name和Transformer输出字典的 key。3. 检查Extractor是否成功获取到了数据。导入 Anki 时提示“无效的包文件”。1. 文件在生成过程中被损坏。2. 使用的genanki库版本与 Anki 版本不兼容。1. 尝试重新运行管道生成文件。2. 确保使用的是较新版本的hanky和genanki。可以尝试更新pip install --upgrade hanky genanki。3. 检查 Anki 是否为最新版本。从网络或数据库抽取数据时程序卡住或报错。1. 网络连接问题。2. 数据库连接字符串或查询语句错误。3. 目标网站有反爬机制。1. 检查网络是否通畅。2. 在Extractor的extract方法中添加详细的异常捕获和打印定位错误源头。3. 对于网站抓取考虑添加请求头User-Agent、设置超时时间、使用会话Session。转换后的卡片内容格式混乱。在Transformer中直接使用了包含特殊字符如换行符的文本未进行 HTML 转义或处理。1. 在将文本填入字段前使用html.escape()进行转义。2. 或者有计划地使用 HTML 标签如br换行来格式化内容并确保整个字段是有效的 HTML 片段。7. 总结Hanky 框架将 ETL 这一经典的数据处理模式引入 Anki 卡片制作为需要批量、自动化管理记忆内容的用户提供了强大的工具。通过本文的学习你应该已经掌握了 Hanky 的核心概念、基本用法以及一些进阶技巧。从简单的本地文件处理到复杂的网络数据抓取Hanky 都能通过清晰的代码结构帮助你完成任务。关键要点回顾流程标准化ETL 模式抽取、转换、加载使卡片生成代码易于理解、测试和复用。灵活可扩展通过自定义Extractor和Transformer可以接入任何数据源并实现复杂的转换逻辑。基于成熟生态底层基于稳定的genanki库保证了生成的 Anki 包文件的兼容性。下一步你可以尝试将你的个人笔记如 Markdown 文件通过 Hanky 转换成 Anki 卡片。集成在线词典 API如 Merriam-Webster 或 Free Dictionary API来自动丰富卡片内容。为你的卡片设计更复杂的模板和 CSS 样式使其更符合你的审美和学习习惯。自动化是提升学习效率的利器希望 Hanky 能成为你知识管理工具箱中重要的一员。如果在实践过程中遇到问题别忘了参考本文的常见问题部分或仔细查阅 Hanky 和 genanki 的官方文档。
