如果你也跟我一样备考 DSH德国大学入学德语考试期间一直在用 WorkBuddy 屯词卡那你大概率会遇到这个问题词库越来越大等到按考试主题整理备考材料时完全无从下手。workbuddy-to-dsh 这个转换工具就是专门解决这个场景的它能把 WorkBuddy 导出的学习记录转成 DSH 备考用的结构化材料包括分类词汇表、高频表达句库、口语话题卡和统计报告。我自己从安装到跑通全流程用了一整天中间踩了不少坑这篇就按实际使用顺序把完整过程写下来适合正在用 WorkBuddy、准备考 DSH 的德语学习者参考也适合需要批量整理学习数据的人作为思路借鉴。1. 为什么要把 WorkBuddy 数据转成 DSH 备考材料1.1 WorkBuddy 里攒的东西跟 DSH 要考的东西是两套结构WorkBuddy 这类学习工具的设计思路是帮你快速记录学习过程中的碎片。我在里面记的东西大概有这么几类生词卡单词、释义、一到两句例句。听力练习里碰到的固定搭配。阅读材料里摘出来的长难句。口语练习时突然想到的句式。这些记录最大的特征是它们跟着学习时间线走而不是跟着考试维度走。比如前几个月我跟着教程学标签用的是第1课第2课这种后期开始啃新闻和播客标签又变成新闻环境博客科技。时间一长标签体系完全失控。DSH 考试需要的是另一套结构。它的词汇不是按课文排的而是按主题领域排的。写作和口语需要有观点表达句库听力需要学术场景的高频提示词阅读需要能快速定位的长难句训练。如果你直接拿着 WorkBuddy 的原始导出数据去复习会出现几个问题环境相关的词散落在几十个课程标签下面根本拉不齐。同一个词出现三次原形、变位、派生词统计时还当成三条。例句有些是完整句子有些只是一个名词短语做口语卡时根本没法直接用。这是我备考第三周的真实状态软件里攒了 3000 多条内容但真正按 DSH 模块开始复习时能直接用的不到一半。当时硬着头皮用 Excel 筛了两天词汇表最后还漏掉了一堆口语表达。1.2 DSH 备考材料的三个刚需手工整理为什么效率太低DSH 备考材料有三个方面是硬需求手工整理的性价比很低。第一个按主题域拉词汇表。DSH 阅读和写作话题高度集中在几个固定领域Studium 与 Wissenschaft、Umwelt 与 Nachhaltigkeit、Technik 与 Digitalisierung、Gesellschaft 与 Integration、Wirtschaft 与 Arbeit、还有 Gesundheit。每个主题下需要几百个核心词汇最好按词频排好序高频优先背。问题是你从原始标签里根本分不出来哪些词归属于哪个领域。第二个按考试模块拆句库。同样是 Ich bin der Meinung, dass...这种表达用在口语表态、议论文写作、听力速记里侧重点完全不同。WorkBuddy 的原始数据里没有这个维度它只记录什么时候遇到的和当时的标签是什么。第三个可量化的复习进度。3000 条词卡到底覆盖了多少环境词汇C1 难度以上的占比是多少没有统计报告你根本不知道自己的薄弱面在哪。手工数的话数完都该考试了。这三件事手工都能做但不是不能做的意思而是投入产出比太低。我当时在 Excel 里按标签逐项筛一百多个标签一个个看还要手工合并近义标签两天下来眼睛都花了。这种重复性、机械性的工作本来就应该交给一个固定逻辑的转换工具。1.3 workbuddy-to-dsh 到底做了什么不是搬家是重新结构化我的理解workbuddy-to-dsh 的核心逻辑并不复杂总共三步读取 WorkBuddy 导出的记录按字段解析成统一的中间格式。通过内置的标签映射表把用户自定义标签归一到 DSH 常考主题域。按模板生成备考材料词汇表、句库、口语卡、统计报告各一份。关键是第二步和第三步的设计。标签映射解决的是分类混乱的问题输出模板解决的是材料形态不匹配的问题。你给它一条原始数据它输出到词汇表里就已经是被整理过的形态了。举个例子我在 WorkBuddy 里存的是Umwelt / die Nachhaltigkeit / nachhaltige Entwicklung / 新闻 / C1。转完之后在词汇表里看到的是主题Umwelt | 词条die Nachhaltigkeit | 用法nachhaltige Entwicklung | 语料来源新闻类听力 | 难度C1。这个思路其实不限于德语学习工具任何记录格式和使用格式不一致的场合都需要这么一层转换。只不过 workbuddy-to-dsh 把 DSH 备考的领域知识直接做进了默认配置里这也是我选它而不是继续用 Excel 的原因。2. 在动手转换前先把环境和测试数据准备好2.1 运行环境与依赖workbuddy-to-dsh 目前是 Python 写的所以第一步是确认本机有没有 Python 环境。python3 --version pip3 --version建议使用 Python 3.9 以上版本。我在 3.10 环境下跑得没问题有朋友反馈 3.7 上存在部分依赖兼容问题旧版本就别折腾了直接升级解释器更省事。如果你平时用 conda 管理环境建议单独建一个虚拟环境别跟其他项目的依赖混在一起否则 pandas 版本冲突能卡上半小时。建虚拟环境的方法看个人习惯我用的是 venvpython3 -m venv w2d-env source w2d-env/bin/activateWindows 下的激活命令是w2d-env\Scripts\activate激活成功后命令行前面会出现(w2d-env)前缀这一步能确认环境已经切过来了。2.2 安装 workbuddy-to-dsh 的两种方式方式一直接 pip 安装。既然项目已经发布到 PyPI一条命令就搞定pip install workbuddy-to-dsh方式二从源码仓库安装。如果你是从代码托管平台上看到这个项目的clone 下来本地安装git clone https://git.example.com/path/to/workbuddy-to-dsh.git cd workbuddy-to-dsh pip install -e .两种方式我优先建议方式一前提是你能确认安装的版本里包含convert子命令。装完之后跑一下workbuddy-to-dsh --help如果输出里列出了convert、validate、build-theme-map这些子命令说明版本没问题。我最初装过一个很老的提交里面只有convert没有模板定制功能排查了半天才发现是版本问题。2.3 先用 3 条测试数据验证流程正式转换之前强烈建议先跑一遍测试数据。这一步能帮你把环境问题和数据问题分开省得后面面对大文件时自我怀疑。先建一个test_export.csv手工放 3 条词条topic,word,meaning,example,source,level Umwelt,die Nachhaltigkeit,可持续性,Wir müssen die Nachhaltigkeit der Landwirtschaft sichern.,news,C1 Studium,die Vorlesung,讲座,Die Vorlesung beginnt um zehn Uhr.,campus,B2 Technik,die Automatisierung,自动化,Die Automatisierung verändert die Arbeitswelt.,news,B2然后跑一次最小转换命令workbuddy-to-dsh convert -i test_export.csv -o test_output/ --format md看到输出目录里有vocabulary_umwelt.md、vocabulary_studium.md、vocabulary_technik.md这些文件说明链路是通的后续对真实数据操作才有把握。这一步花不了五分钟实际价值很大。3. 从 WorkBuddy 导出数据转换前必须搞懂的一步3.1 WorkBuddy 的导出格式与字段说明不同版本的 WorkBuddy 导出字段可能不完全一样但大多数词库类工具都会包含这些核心字段字段含义是否可空转换时的作用topic自定义标签可空参与主题域映射word词条必填词汇表主键meaning释义可空词汇表释义列example例句或上下文可空句库、口语卡素材source来源标记可空影响句库归类level难度标记可空影响排序权重这里最需要注意的是word字段它是必填的。其它字段缺失最多是生成的材料不完整但word缺失或全空转换程序会直接跳过这条记录并在统计里标记为 invalid。导出格式我建议优先选 CSV 而不是 JSON。CSV 可以用 Excel 或 VSCode 快速预览方便在转换之前就发现问题。导出完成后用文本编辑器打开文件检查一下表头字段是否跟上面表格对应得上不一致就先手动改表头。3.2 导出后先看这几点第一看编码。Windows 下导出的 CSV 经常是 ANSI 或 GBK 编码直接按 UTF-8 读德语特殊字符会全部变成乱码。正确做法是先用文本编辑器打开文件看右下角编码类型。如果不是 UTF-8可以在转换命令里加--encoding gbk参数也可以先另存为 UTF-8 再喂给工具。第二看空字段。在 Excel 里筛选一下 example 列看看空格占比。如果 70% 的词条都没有例句后面生成的口语话题卡基本是废的。这种情况只能在 WorkBuddy 里先补一批例句再导出或者接受词汇表里出现大量空白位。第三看标签数量分布。用数据透视表统计 topic 列数一下你有多少个不重复的标签。如果超过 30 个基本就要认真写映射表了。我的旧数据里环境环保ClimateKlima四种标签其实都指向同一个主题这就是需要归一的典型情况。3.3 自定义标签与 DSH 主题域的映射关系workbuddy-to-dsh 内置了一套默认映射表覆盖常见的标签写法大约是这样自定义标签示例DSH 主题域环境、环保、Climate、Klima、NachhaltigkeitUmwelt大学、学业、留学、Studium、ForschungStudium科技、AI、Digitalisierung、AutomatisierungTechnik社会、社会问题、Integration、MigrationGesellschaft健康、医疗、GesundheitGesundheit经济、就业、Arbeit、WirtschaftWirtschaft默认映射能覆盖一部分情况但每个人自己的标签系统大概率跟默认表对不上。所以工具提供了自定义映射文件格式是 JSON{ 环境: Umwelt, 环保: Umwelt, Climate: Umwelt, 气候: Umwelt, 大学: Studium, 学业: Studium }然后在转换命令里指定workbuddy-to-dsh convert -i workbuddy_export.csv -o output/ --theme-map my_mapping.json映射没有覆盖到的标签会全部归入uncategorized主题。最后你会拿到一个vocabulary_uncategorized.md里面就是要手动整理的剩余部分。我第一次全量转换时3000 多条里跑出来 444 条未分类就是因为映射表写得太抠。4. 核心命令与参数跑通一次完整的转换流程4.1 命令与参数说明工具的核心子命令是convert常用参数可以按三组理解输入输出、映射与过滤、输出格式。参数作用默认值-i, --input输入 CSV/JSON 文件路径无-o, --output输出目录./dsh_output--format输出格式md/csv/ankimd--theme-map自定义标签映射 JSON 文件builtin--exam-level目标水平B2或C1C1--dedupe是否去重true/falsetrue--keep-empty-examples是否保留无例句词条false--encoding输入文件编码utf-8参数之间是叠加关系。比如需要指定编码、使用自定义映射、保留空例句一条命令写完就行workbuddy-to-dsh convert -i export.csv -o my_dsh/ \ --encoding gbk \ --theme-map my_mapping.json \ --exam-level C1 \ --keep-empty-examples true \ --format md建议先用workbuddy-to-dsh convert --help看一下你安装版本的实际参数列表不同版本之间可能有细微差异别把这里当唯一标准。4.2 完整示例把 3000 条词卡变成 DSH 备考包拿我自己当时那批数据举例文件是workbuddy_202402_export.csv里面 3124 行有效词条。我执行的命令是workbuddy-to-dsh convert \ -i workbuddy_202402_export.csv \ -o dsh_202402/ \ --theme-map my_mapping.json \ --exam-level C1 \ --dedupe true \ --format md运行过程中的输出大致是这样[INFO] 读取文件: workbuddy_202402_export.csv [INFO] 共读取 3124 条记录其中 8 条无效 [INFO] 标签映射完成2680 条成功归类444 条未分类 [INFO] 去重完成去除 156 条重复词条剩余 2968 条 [INFO] 按难度过滤后C1 级别主要材料 2143 条B2 级别辅助材料 825 条 [INFO] 输出目录: dsh_202402/ [INFO] 生成文件: [INFO] - vocabulary_umwelt.md [INFO] - vocabulary_studium.md [INFO] - vocabulary_technik.md [INFO] - vocabulary_gesellschaft.md [INFO] - vocabulary_gesundheit.md [INFO] - vocabulary_wirtschaft.md [INFO] - vocabulary_uncategorized.md [INFO] - phrases_hoeren_hochschule.md [INFO] - phrases_sprechen_meinung.md [INFO] - dsh_stats.json [INFO] 耗时 2.4 秒这一步跑完手里就是按 DSH 主题分类、带难度标注、带统计的备考底稿。我当时的第一感受是两天手工没拉完的词汇程序两秒跑完了。4.3 进阶用法自定义模板与 Anki 导出如果对默认 Markdown 排版不满意可以在当前目录放一个template_vocab.md.j2模板文件用 Jinja2 语法控制每条词汇的展示方式。工具检测到模板文件后就会用它替换默认排版。### {{ word }} **释义**{{ meaning }} **例句**{{ example }} **来源**{{ source }} | **难度**{{ level }}如果你是 Anki 用户把--format anki加上输出就是两列 CSV一列是词条含例句一列是释义。直接导入 Anki 做卡片复习比自己手抄快太多。workbuddy-to-dsh convert -i export.csv -o anki_deck/ --format anki --exam-level B2导入 Anki 时字段分隔符按默认逗号处理别勾选 HTML 转义否则德语引号会被转义成quot;卡片看起来会很难受。5. 输出文件拆解这份 DSH 备考包到底怎么用5.1 分类词汇表的结构生成的vocabulary_umwelt.md大致长这样## Thema: Umwelt环境 | 词条 | 释义 | 例句 | 难度 | | --- | --- | --- | --- | | die Nachhaltigkeit | 可持续性 | Die Landwirtschaft muss nachhaltig gestaltet werden. | C1 | | der Klimawandel | 气候变化 | Der Klimawandel betrifft alle Länder. | C1 | | erneuerbar | 可再生的 | Erneuerbare Energien werden immer wichtiger. | B2 |这个表看起来简单但排序逻辑是有讲究的同主题内先按难度降序排C1 在前同一难度内按内置语料词频降序排。也就是说越可能在 DSH 阅读题里碰到的词越靠前复习时优先背它们。如果你的 WorkBuddy 词条没有 difficulty 字段工具会按词条长度和是否包含复合词做一个估算标记为auto-C1或auto-B2。这个估算不一定准建议导出前尽量在 WorkBuddy 里手动标好级别实测效果比自动判断靠谱得多。5.2 高频表达与听力句库source 字段标记为听力hoeren / campus / news的词条会额外汇总到phrases_hoeren_hochschule.md。这个文件按场景再分三块课堂讲座、小组讨论、学术报告。每一块都保留原始上下文里的时间状语和连接词方便你做听写时定位信息点。听力句库我自己是这么用的不做逐句背诵每天挑 10 句做听写、对照、跟读三步。因为这些句子都来自自己记录过的内容语境熟悉比去外面买一套听力材料更能贴合现有水平。等这 10 句完全吃透再换下一批。5.3 口语话题卡的生成逻辑phrases_sprechen_meinung.md是从 Gesellschaft、Technik、Umwelt 等主题下抽取带有明显观点标记meiner Meinung nach、ich bin überzeugt、einerseits/andererseits的例句做成的。每一个话题卡包含三个部分话题模板比如Sollte ... weiter vorangetrieben werden?表态句比如Ich bin der Meinung, dass ...支撑论据从你的例句库里匹配到的两三个真实论点句。举个例子## Thema: Technik / Automatisierung Frage: Sollte die Automatisierung in der Industrie weiter vorangetrieben werden? Meinung: Ich bin überzeugt, dass die Automatisierung langfristig mehr Arbeitsplätze schafft. Argument 1: Die Automatisierung übernimmt gefährliche und monotone Tätigkeiten. Argument 2: Sie ermöglicht höhere Produktivität, was der gesamten Wirtschaft zugutekommt.这里要特别注意如果 WorkBuddy 里词条没有配套例句口语卡就只剩话题框架没有实际论据内容复习价值大打折扣。这也是我反复强调例句字段不能为空的原因。6. 实操中踩过的五个坑与完整排查思路6.1 德语特殊字符全部变成乱码我第一次全量转换生成的词汇表里 ä ö ü ß 全变成了äö这种乱码。第一反应是工具坏了排查之后才发现是编码问题。排查链路是这样的先用文本编辑器打开原始 CSV确认是 GBK 编码再检查工具默认读取编码是 UTF-8最后在命令里强制指定输入编码workbuddy-to-dsh convert -i export.csv -o out/ --encoding gbk跑完再看输出正常了。这里多说一句GBK 编码下德语字符能正常显示但转成 UTF-8 之后用 Excel 打开又可能乱码所以我在保存最终输出文件时又手动转存了一次 UTF-8。经验就是所有文本类工程文件统一用 UTF-8 是最省心的选择。6.2 标签映射遗漏主题未分类一大堆有一次跑完转换发现vocabulary_uncategorized.md里有 444 条打开一看全是环境环境学Nachhaltigkeitsthemen这种跟环境相关的边缘标签。原因很简单我映射表里只把环境和环保归到了 Umwelt漏掉了气候KlimaClimate这些近义写法。排查链路也清晰打开输出目录里的dsh_stats.json看uncategorized_labels数组里面会列出所有未命中的原始标签和各自数量。按数量从多到少补进映射文件然后重新跑一次转换workbuddy-to-dsh convert -i export.csv -o out/ --theme-map my_mapping.json补完之后未分类从 444 降到了 37 条剩下的确实无法归入任何 DSH 主题域手动忽略就行。这里有个经验映射表是一次性投入后面每次新导出都能复用值得花时间维护好。6.3 同一单词的不同形态被当成多个词条我的数据里lernen、lernt、gelernt、das Lernen同时存在。工具去重之后依然全部保留因为它的简易去重只做完全匹配不会识别德语词形变化。结果词汇表词条数虚高复习时还会重复劳动。排查链路先看dsh_stats.json里的去重报告确认确实是因为词形变化导致的再决定处理方案。方案一是在 WorkBuddy 里导出前手动统一词条为原形方案二找工具有没有词形还原开关当前这个版本是不支持的。我最终用的是方案一的变体批量导出后在 CSV 里用查找替换把常见变位词尾统一掉。这个坑本质上是录入习惯问题。后来我在 WorkBuddy 里立了一个规矩单词一律存原形词组按整体存动词原型在括号里标用法比如lernen (lernt, gelernt)。这样导出之后基本可以直接用省掉了大量清洗功夫。6.4 例句为空口语卡内容空洞--keep-empty-examples默认是 false意思是无例句词条不会进入句库和口语卡。我一开始没注意这个参数跑完之后发现phrases_sprechen_meinung.md里只有 12 个话题卡对应的论据还全是空架子。排查链路回原始 CSV 统计 example 列空值率。我那批数据里 60% 的词条没有例句就是因为在 WorkBuddy 里记录时偷懒了只存了单词和释义。解决思路分两步。短期把--keep-empty-examples true打开让词汇表至少保留这些词条先保证词汇量覆盖长期在 WorkBuddy 里给高频词补例句每次只补 20 条一周就能把最核心的 100 个词条补完。补例句的过程本身就是复习效率并不低。6.5 大文件转换卡死后来我把一年的学习数据都导出文件接近 5 万行一次性执行 convert跑了十几分钟没反应最后直接内存不足退出。原因在于工具的去重逻辑会把全部数据加载进内存重复比较时开销偏高。排查链路先缩小输入范围。WorkBuddy 支持按日期区间导出我就改成按月导出每次 4000 到 6000 条转换时间控制在几秒内。跑完再用简单脚本把多个输出合并。如果你必须一次性处理 5 万条以上的数据建议先确认有没有流式处理相关的参数我后来在更新版本里见过类似能力但不是默认开启的。分批转虽然麻烦一点但稳定不崩溃我之后就一直是按季度导出、批次转换、最后合并输出的固定流程。7. 一点使用体会工具能帮你提效但代替不了备考本身跑通整个流程之后我对学习数据转备考材料这件事有了几点真切体会。第一工具带来的最大收益不是省时间而是逼着你把数据结构化。以前我在 WorkBuddy 里加词条标签想怎么打就怎么打后来为了让映射表稳定我会下意识在记录时就把标签归到标准清单里。数据规范了后面所有处理和复习都顺畅了。第二转换生成的词汇表是备考底稿不是最终材料。我自己还会继续加工比如给口语话题卡补充两个自己的例子给听力句库按难易度重排。工具负责把碎片整理成有序的架子架子上怎么挂东西还是要自己动手。第三映射表建议当成长期资产维护。我现在的 my_mapping.json 已经有超过 80 组标签映射每次 WorkBuddy 导出新数据跑转换命令时直接复用基本不用改。这比每次整理 Excel 都重新做一遍分类要轻松太多。最后分享一个小技巧如果你也像我一样平时会在 WorkBuddy 里存不少新闻标题做阅读素材转换完成后不妨多留意一下vocabulary_uncategorized.md。这里面往往藏着一些不在 DSH 大纲里、但非常实用的当代德语表达顺手抄到自己的积累本上也算意外收获。