1. 这个工具到底是干什么的
先别急着看命令，我花两分钟把这个工具的定位讲清楚，你后面用起来会顺手很多。WorkBuddy 是一款很多团队在用的日常工作计划管理工具，它把个人的任务、会议、待办事项全部收拢到时间线里，操作界面非常宽松，适合快速记录。而 DSH 则是一套紧凑型的数据交换格式，全称可以理解为“可扩展的轻量级结构化描述”，它长得有点像带缩进的文本清单，但每一行都承载了明确的层级关系和字段含义，非常适合脚本解析、跨系统同步和长期归档。
问题在于，WorkBuddy 默认的导出格式和 DSH 并不兼容。WorkBuddy 导出的通常是带时间戳的扁平文本，或者一份自定义结构的数据文件，字段命名里混杂着用户别名、中文备注、重复规则等。DSH 却要求严格缩进、字段名固定、时间格式化必须统一。你要是手动去整理，一次两次还行，任务一多就彻底崩溃了——我有一次迁移了近八个月的任务记录，三千多条，每个条目还要拆成标题、日期、优先级、重复策略四五个字段，整理到后面眼睛全是花的。
workbuddy-to-dsh 就是为了解决这个痛点出现的转换工具。它把 WorkBuddy 导出数据作为输入，经过字段映射、格式归一化、时间重排，最终输出一份标准 DSH 文档。整个过程在命令行执行，不需要手动打开编辑器去逐行修改，跑完之后还自带校验功能，能直接提示哪一行没转成功。简单说，你只需要做两件事：导出原始数据，然后运行一条命令。剩下的事情工具帮你处理。
这套方案最适合三类人。第一类是正在从 WorkBuddy 迁移到新计划系统，需要保留全部历史任务的个人用户；第二类是团队内部统一用 DSH 做数据归档，需要定期把成员的任务数据汇总上来的管理员；第三类是开发者，想把 WorkBuddy 的数据接进自己写的自动化流程里，用 DSH 做中间格式。不管你是哪一种，读完这篇教程，应该都能独立跑通整个流程。
2. 环境安装和前置准备
工欲善其事，必先利其器。这个工具本身是一个开源命令行程序，主要用 Python 编写，依赖很少，安装过程非常顺畅。我建议你在干净的环境里操作，避免和系统自带的脚本工具混淆。
2.1 确认基础环境
首先确认你的电脑上已经安装了 Python 3.8 及以上的版本。绝大多数现代操作系统都自带 Python，Mac 用户注意一下，系统自带的 Python 版本可能偏旧，建议先装一个 Homebrew 再通过它安装新版 Python。Windows 用户去官网下载安装包即可，安装时记得勾选“Add Python to PATH”选项，否则后面命令行会找不到 python 指令。
确认版本只需要一条命令：
python3 --version如果输出Python 3.8.x或更高版本，说明环境没有问题。如果提示找不到命令，检查一下系统环境变量或者重新安装。
2.2 安装 workbuddy-to-dsh
我推荐用 pip 安装，这是最省事的方式。在终端里执行：
pip3 install workbuddy-to-dsh安装过程一般几十秒就结束。如果你的机器上有多个 Python 环境，建议加上参数指定用户目录安装，避免权限问题：
pip3 install --user workbuddy-to-dsh安装完成后验证一下：
workbuddy-to-dsh --version能正常输出版本号就说明安装成功。这一步看起来不起眼，但跳过的话后面很容易遇到“找不着配置文件”“模块无法加载”这类奇怪问题，所以别偷懒。
2.3 准备一份示例数据
正式转换之前，强烈建议你先准备一份小规模的测试数据。直接在 WorkBuddy 里导出最近一两天的任务，内容不需要多，五六条就行，关键是要包含不同类型：带日期的、带重复规则的、只写了备注的、有优先级的。这样转换完成后，你可以快速核对每一类字段是否正确映射。
我把测试数据放在专门的目录里，比如~/wb_test/，后面所有操作都在这个目录下进行。用真实数据直接跑也完全可以，但万一出错了，排查起来会很麻烦。先跑通小例子再上完整数据，这是处理数据转换类任务一贯的做法，省时间。
提示：WorkBuddy 的导出文件后缀名可能是
.json、.txt或者.workbuddy，tool 本身不挑格式，它能自动识别常见的几种结构。但如果你拿到的文件是加密打包过的，那得先解锁才能用，这个是另一个话题了。
3. 核心配置逐项拆解
这个工具之所以灵活，是因为它支持通过配置文件控制整个转换过程。你不写配置文件也行，工具会用一套默认规则工作，但那种情况只适合最简单的数据。真正用起来之后，你会发现这些配置项才是精华所在。
3.1 数据源与输出类型的配置
配置文件是config.yaml格式，放在当前工作目录下，工具启动时自动读取。最基础的配置段长这样：
input: path: "./data/workbuddy_export.json" type: "auto" encoding: "utf-8" output: path: "./data/output.dsh" mode: "overwrite" line-ending: "lf"input.path指定原始文件的路径，支持绝对路径和相对路径。input.type默认是auto，表示让工具自己判断文件类型。如果你明确知道文件结构，也可以手动指定json、plain等类型，跳过自动识别阶段，转换速度会稍微快一点。
output.mode有两个选项，overwrite表示覆盖已有文件，append表示追加写。注意，append适合多个文件分批合并到同一个 DSH 文件的场景，但用之前最好确认目标文件不存在重复条目，否则后面去重会比较麻烦。
output.line-ending我建议固定用lf。Windows 用户默认可能是crlf，但 DSH 格式的解析器基本都按lf处理，混用换行符在跨系统传输时偶尔会触发解析警告，没必要冒这个险。
3.2 字段映射规则
WorkBuddy 导出的字段名通常比较随意，比如创建时间叫created_at，截止日期叫due_date，优先级叫priority_text。而 DSH 规范里这些字段名是固定的，直接原样输出会导致校验不过关。所以你需要定义一份映射表：
mapping: task_id: "id" title: "title" createdAt: "created-at" dueDateTime: "due-at" priority: "priority" status: "state" tags: "tags" notes: "description"这里的规则很简单，左边是 WorkBuddy 原始数据里的字段名，右边是 DSH 目标字段名。工具在转换时会自动执行名称替换。我用过不少转换工具，字段映射这步做得这么直接的确实不多，大部分都要写脚本才能实现。它省去的不是一次两次的事，而是每次迁移都要重写的重复劳动。
需要注意一个细节：映射表是逐字段匹配的，如果原始数据里某个字段不存在，工具不会报错，而是把该字段直接跳过。这会导致输出 DSH 里缺几行。如果你想强制要求某些字段必须存在，可以单独加一个required-fields列表：
required-fields: - title - due-at - state如果有缺失，转换完成后工具会把缺失的条目单独列在报告末尾，方便你回头补充数据。这个设计非常实用，省得你一个个去核。
3.3 过滤与转换规则
WorkBuddy 里常常堆积着一些历史遗留的完成项，或者标记为删除的旧任务。这些数据转换到 DSH 里意义不大，徒增体积。所以配置文件里提供了过滤段：
filter: exclude-status: ["completed", "cancelled"] exclude-if-empty: ["title", "due-at"] only-tags: ["daily", "weekly"]exclude-status按状态排除整条记录，exclude-if-empty排除某个关键字段为空的数据，only-tags则只保留带有特定标签的内容。这三个条件可以同时生效，工具会先做标签筛选，再检查字段完整性，最后过滤状态。
此外，时间字段的格式化也可以在这里统一处理。WorkBuddy 导出的时间格式可能是2027-01-15 09:30:00，也可能是带时区的 ISO 格式。DSH 默认要求是YYYY-MM-DDTHH:mm:ss这种紧凑格式。通过配置：
time: input-format: "auto" output-format: "iso" timezone: "Asia/Shanghai"input-format设置为auto，工具能自动识别大多数常见格式。output-format是最终输出的样式，支持iso、timestamp两种。我一般选iso，因为可读性好，脚本解析也不费劲。timezone这栏值得格外注意，如果原始数据里带了 UTC 时间，而你在国内使用，不设置时区的话，转换后的时间会和你手机上看到的时间差 8 个小时，很影响阅读，所以这栏建议还是写上。
4. 完整实操：从 WorkBuddy 到 DSH 的一趟流程
前面讲了概念和配置，这部分我就按实际操作来走一遍。假设现在我在某个普通工作日的下午，刚从 WorkBuddy 导出了完整的项目任务数据，接下来要把它们转换成 DSH 格式，并检查转换结果。
4.1 导出 WorkBuddy 原始数据
登录 WorkBuddy 之后，在任务列表页找到导出按钮。不同版本功能位置略有差异，一般在设置菜单或者工具栏的“...”里。导出时选择“完整数据”，不要选“仅当前视图”，因为当前视图往往只包含筛选后的部分任务，转换到 DSH 会导致历史数据遗漏。文件格式选择“JSON”，这是转换工具支持得最好的类型。
导出完成后，把文件命名为workbuddy_export.json，放到刚才准备好的工作目录里。这里有个操作习惯要养成：保留一份原始文件的备份，再把副本用于转换。因为 WorkBuddy 的导出接口偶尔会生成半截文件，万一你拿到手的文件本身就不完整，转换结果自然不可靠，有备份可以及时发现对比。
4.2 编写并检查配置文件
在目录里新建config.yaml，按前面说过的结构填写。我以一份典型的个人任务数据为例：
input: path: "./workbuddy_export.json" type: "auto" output: path: "./output.dsh" mode: "overwrite" mapping: id: "id" taskName: "title" timeline: "due-at" priorityLabel: "priority" filter: exclude-status: ["done", "trash"] time: output-format: "iso" timezone: "Asia/Shanghai"这里有几个细节我想特别讲一下。我的 WorkBuddy 字段里，任务名是taskName，时间字段是timeline，都是比较特殊的命名，所以映射表必须手动定义。如果你的字段命名和默认规则一致，比如就是title和due-date，那映射表甚至可以留空，工具会按默认规则匹配。
写完配置文件之后，我习惯先跑一遍语法检查：
workbuddy-to-dsh validate-config ./config.yaml这条命令不会执行转换，只是检查 YAML 语法、字段名是否有拼写错误、映射规则是否合理。特别是 YAML 文件对缩进非常敏感，一个空格错了就会导致解析失败。这种小问题在编辑器里看着不明显，跑一次校验命令立刻暴露。
4.3 执行转换命令
配置检查通过后，执行核心命令：
workbuddy-to-dsh convert --config ./config.yaml执行过程会输出日志信息，正常情况下你会看到类似下面的内容：
[INFO] 读取输入文件: ./workbuddy_export.json [INFO] 自动识别文件结构: JSON(扁平) [INFO] 任务总数: 1260 [INFO] 过滤后保留: 843 [INFO] 字段映射完成: 843 [INFO] 生成 DSH 文档: ./output.dsh [INFO] 校验通过: 843 条记录, 0 条异常 [INFO] 耗时: 2.86秒看到校验通过基本就稳了。如果日志末尾出现校验失败或警告，说明存在问题项，需要进一步排查。
转换完成之后，建议打开output.dsh查看一下开头几行。一份合格的 DSH 文档长这样：
task: 季度总结报告 due-at: 2027-03-31T18:00:00 priority: high state: active tags: [work, review] description: 汇总产品、运营、研发三端数据 task: 准备分享材料 due-at: 2027-03-15T09:00:00 priority: medium state: active tags: [meeting]每一级缩进代表层级关系，字段名清晰，值格式统一。如果你看到的输出完全符合这种结构，说明转换过程一切正常。
4.4 校验数据完整性
工具自带的校验逻辑主要是检查必填字段是否缺失、时间格式是否合规、缩进是否污染。但格式正确不代表内容正确，字段的映射是否准确还需要人工抽查。
我自己的习惯是抽三组数据对比：第一组是最近创建的任务，第二组是最早的历史任务，第三组是带重复规则的任务。分别检查它们在 WorkBuddy 里的原始记录和 DSH 里输出是否对应。重点看时间字段有没有偏移、任务标题有没有被截断、优先级是否正确。
如果抽查没问题，就可以删除前面的备份文件了。如果发现异常，保留原始导出文件，回头排查配置。
4.5 批量转换多个文件
有些团队是按周导出 WorkBuddy 数据的，一个月下来手上有四五个文件。此时可以借助工具支持的批量模式，把多个文件转换并合并到一个 DSH 文档：
workbuddy-to-dsh convert-batch --input-dir ./exports/ --config ./config.yaml --output ./all.dsh这个命令会读取exports目录下所有可识别的文件，按文件名排序依次转换，然后合并输出。合并时工具会自动去重，只要两个文件的id字段相同，后导入的不会覆盖先导入的，而是保留第一条。这在处理跨周导出时非常有用，不会因为任务跨了两周就出现两条重复记录。
5. 常见报错与排查实录
数据转换工具最怕的就是遇到问题不知道怎么查。这里我把自己真实踩过的坑整理成一份速查表，每条都对应具体的解决方案。
5.1 文件读取失败：编码问题
现象：Log 报UnicodeDecodeError: 'utf-8' codec can't decode byte 0xb7 in position xx，日志停在“读取输入文件”这一步。
原因：WorkBuddy 导出的文件可能不是 UTF-8 编码，尤其是从 Windows 客户端导出的数据，很可能携带 GBK 或 GB2312 编码的戍余字符。
解决办法：在配置文件的input段里修改encoding字段：
input: encoding: "gbk"如果改完还报错，把文件用编辑器转一下编码再用。这个坑出现的频率不低，而且毫无规律，所以拿到导出文件后我建议第一时间看一眼文件编码，别等转换报错了再查。
5.2 字段映射后大量缺失
现象：转换完成后，日志显示过滤后保留 500 条，但输出的 DSH 里有很多记录缺少due-at字段。
原因：配置文件里的mapping名字写错了。比如 WorkBuddy 里实际字段是timeline，你映射表里写的timelinee，多打了一个字符，工具匹配不到值就会跳过。
解决办法：执行前先跑一下字段预览命令：
workbuddy-to-dsh preview-fields ./workbuddy_export.json这条命令把输入文件里的所有字段名和样例值列出来，照着这个列表去写映射表，基本不会出错。我现在每次拿到一份新结构的数据，都会先跑一遍这个命令，比对着文档猜名字高效得多。
另一个技巧是先映射核心字段id、title、due-at，跑一版看效果，再逐步补充其他字段。一次性写好全部映射当然很好，但字段一多容易出错，分两步走更稳。
5.3 日期时间偏移了 8 小时
现象：转换后 DSH 里所有时间比 WorkBuddy 里显示的时间提前了 8 小时。
原因：WorkBuddy 内部存储的是 UTC 标准时间，界面上显示的是你本地时间，两者的差异由浏览器或者客户端处理。转换工具读取到的数据是原始 UTC 值，如果没有指定时区，它不会自动转换。
解决办法：在time配置里设置正确的timezone：
time: timezone: "Asia/Shanghai"严格来说，这不是工具的 bug，而是数据本身带了时区信息在实际场景中的必经环节。我建议不管你在哪个时区，都显式地写明这一项，依赖默认值很容易出问题。
5.4 大文件转换卡住或无响应
现象：文件超过 20MB 之后，转换耗时急剧上升，甚至看起来像卡死了。
原因：工具默认在内存里构建完整的 DSH 结构，文件一大，内存占用飙升，加上日志输出量大，看起来就像没反应。
解决办法：分批转换，不要一次处理整个大文件。在 WorkBuddy 导出时按月份分多次导出，每份控制在 5MB 以内。如果已经有一份大文件，也可以用工具自带的分块参数：
workbuddy-to-dsh convert --config ./config.yaml --chunk-size 2000--chunk-size 2000表示每处理 2000 条记录写一次输出并释放内存。我实测下来，分块后 20MB 文件的转换时间从十几分钟降到三分钟左右，效果非常明显。
5.5 特殊字符导致 DSH 解析异常
现象：部分任务标题里带了引号、方括号、冒号，转换后的 DSH 文档被其他解析器读取时频繁报错。
原因：DSH 格式里一些特殊字符需要转义，但默认转换规则不会主动处理。
解决办法：在配置里开启特殊字符转义：
output: escape: true开启后，工具会自动把标题中的"、[、]、#等字符转换成适合 DSH 格式的转义写法。我之前有一批任务标题里夹杂了大量中文书名号和括号，没开转义之前每次解析都出问题，开了之后整个世界安静了。
6. 日常使用心得与几个延伸技巧
工具终究只是辅助，真正决定效率的是你对数据的理解和使用习惯。这里分享几个我用顺手之后一直在坚持的做事方式。
第一个心得是数据迁移类操作保持“前一小步，后一大步”的节奏。换系统不是特别激进的事，先把最近一个月的任务转换过去用一阵子，确认流程丝滑了，再批量处理全量数据。很多人在这一步着急，结果时间和字段映射的问题在导入后集中爆发，乱成一锅粥。我见过不止一个人在这种场景下陷入困局，浪费了两个整天在手工核对数据。分批迁移，每次验证，远远比一次性全量迁移更可靠。
第二个心得是 DSH 输出非常适合做二次加工。因为它是纯文本结构化格式，你可以直接用脚本读取、统计、转成表格。我后来写了一个小工具，每天定时跑一次 workbuddy-to-dsh，再把 DSH 文件解析成 Markdown 周报，自动发给团队群里。整个过程完全无人值守，省了每周五下午的整理时间。这条链路里 workbuddy-to-dsh 承担了最脏最累的格式转换工作，其他脚本只需要处理干净的 DSH 文档即可。
第三个技巧是给配置文件留一份模板，每次迁移新数据时复制模板再修改。毕竟不同时间段导出文件的字段结构可能略有调整，保留一份常用配置模板能省掉重新填写映射表的重复劳动。我现在的模板里有完整的注释，每个配置项写成什么样、为什么这么写，都标得清清楚楚。下次换机器或者帮团队成员搭环境，直接把模板扔过去改两行就能用。
这个工具本身能做的事情也有一些边界值得留意。它不提供反向转换，也就是 DSH 转回 WorkBuddy 的格式需要靠其他方法。另外，WorkBuddy 的附件文件只是记录引用路径，不会把文件本身打包进 DSH，所以迁移历史数据时，附件要单独备份。理解了这些边界，你对整个数据流程的把控会更游刃有余。
最后，如果你只是想把当前手里的数据快速整理成 DSH 文档，跑一次工具就够了；但如果你想建立一套稳定的任务数据流转管道，那建议把配置、校验、批量处理这些步骤都固化成脚本。数据转换这件事，一次性的手动操作看起来很轻松，但长期看还是在自动化里挣扎一次，未来能省下无数时间。
