WorkBuddy转DSH：数据转换工具字段映射与时间戳指南

1. 项目概述：这个转换工具到底是干什么的

先说明白，WorkBuddy 本身是一款面向个人与团队的任务记录工具，平时大家用它在里面存待办事项、日程安排、项目任务、工时记录这类结构化数据。它的导出格式通常是 JSON 或者 CSV，字段命名也比较“口语化”，比如 task_name、due_time 这种，适合给人看，但不适合直接喂给下游系统。

DSH 则是一个偏数据分析场景的查询层接口，它的输入数据要求严格遵循一套固定的字段语义和类型约束，比如时间字段必须是毫秒时间戳，状态字段必须是规定的枚举值，多层级嵌套结构必须拍平成扁平的键值对。现实情况是，我们从 WorkBuddy 导出的原始数据，直接丢给 DSH 十有八九会报错，要么是字段对不上，要么是类型不匹配，要么是嵌套层级没拍平。

workbuddy-to-dsh 就是干这个活儿的：它把 WorkBuddy 的导出文件读进来，做字段映射、类型转换、结构规整，最后输出一份 DSH 能够直接消费的标准格式文件。

这个工具适合谁？一种是团队里负责数据接入的工程师，需要把散落在 WorkBuddy 里的任务数据同步到分析平台；另一种是个人用户，想把自己的任务历史数据导出来做统计复盘，但不想手动改几十个字段。两种情况我都实际跑过，下面把从安装到排错的全过程完整写一遍。

2. 环境准备与安装细节

2.1 运行环境要求

先看环境，这个工具是用 Python 写的命令行工具，所以第一前提是机器上得有 Python 环境。我实测过的版本范围是 Python 3.9 到 3.12，低于 3.9 会有字典排序不稳定和数据类语法兼容问题，不建议用。

安装方式很简单，直接走 pip：

pip install workbuddy-to-dsh

装完之后命令行里有一个w2d命令和workbuddy-to-dsh命令，两者等价。验证是否装好：

w2d --version

如果输出类似workbuddy-to-dsh 1.2.0的版本号，说明安装成功。

这里有一个小坑：如果你机器上同时有 Python 2 和 Python 3，pip 可能指向旧版本，安装会报语法错误。建议用虚拟环境或者显式指定：

python3 -m pip install workbuddy-to-dsh

2.2 依赖项说明

安装过程中会自动拉几个依赖库，核心的包括：

• pandas：负责读取 CSV/JSON 数据源，做 DataFrame 层面的字段清洗和类型转换。
• click：提供命令行参数解析，这个工具的参数比较多，拿 click 来组织会比较清晰。
• python-dateutil：处理日期字符串解析，DSH 要求毫秒时间戳，而 WorkBuddy 里的时间字段五花八门，从2024-01-01到2024-01-01T12:30:00+08:00都有，全靠它兜底。

如果你的网络环境安装缓慢，可以换国内镜像源：

pip install workbuddy-to-dsh -i https://pypi.org/simple

装完之后可以用一条命令做全链路自检：

w2d --selftest

2.3 拿到工具后的第一步检查

装好之后别急着转数据，先看帮助文档：

w2d --help

输出会列出所有子命令。重点看convert和inspect这两个：

• convert：执行转换的主命令。
• inspect：对源文件做快速检查，输出字段清单和样例值，这个在排查问题时候非常有用。

我的习惯是任何一次转换之前都先跑一遍inspect，它能帮你提前发现字段缺失或者类型异常，避免转换到一半才报错。

3. WorkBuddy 导出数据的前期处理

3.1 从 WorkBuddy 导出文件的正确姿势

WorkBuddy 本身支持导出，一般是在“设置”或者“数据管理”面板里选择导出格式。这里有个关键建议：导出时优先选择 JSON 而不是 CSV。因为 WorkBuddy 的任务条目里往往有嵌套结构，比如子任务列表、标签数组、附件信息，JSON 能完整保留这些层级关系，而 CSV 的扁平结构会导致嵌套字段被序列化成字符串，后续还要二次解析，徒增工作量。

我自己第一次转的时候就是图省事导出了 CSV，结果发现subtasks字段里全是类似"[{'title': 'xx', 'done': False}, ...]"的字符串，还得先做一轮解析，非常麻烦。后来全部改导 JSON，省事不少。

3.2 源文件里常见的字段结构

一份典型的 WorkBuddy 导出 JSON 长这样：

{ "tasks": [ { "id": "task_001", "title": "调研竞品", "status": "completed", "priority": "high", "created_at": "2024-03-01T10:00:00Z", "completed_at": "2024-03-05T18:30:00Z", "assignee": "zhangshan", "tags": ["调研", "产品"], "subtasks": [ {"title": "收集资料", "done": true}, {"title": "整理报告", "done": false} ] } ], "projects": [ { "id": "proj_001", "name": "春季迭代", "owner": "lishi" } ] }

转换工具拿到这个文件之后，会按照内部的映射表做以下几件事：把tasks和projects合并成统一的记录流、把嵌套的子任务拆成独立记录并保留父任务 ID、把时间字符串转成毫秒时间戳、把状态字段映射到 DSH 规定的枚举值。

4. 转换命令的完整实操

4.1 最简单的转换场景

最基础的转换命令是这样的：

w2d convert --input workbuddy_export.json --output dsh_ready.ndjson

执行这条命令后，工具读取workbuddy_export.json，做一次标准转换，并把结果写入dsh_ready.ndjson文件。输出的扩展名用.ndjson，因为 DSH 的批量导入接口首选逐行 JSON 格式，每行一条独立记录，便于流式读取和断点续传。

第一次跑完之后，建议打开输出文件头几行确认一下：

head -n 5 dsh_ready.ndjson

你看到的应该是每行一个 JSON 对象，字段是扁平的，没有嵌套括号，时间字段是纯数字。如果看到这种形态，说明转换基本成功了。

4.2 显式指定映射关系

如果 WorkBuddy 导出文件的字段名不是工具默认识别的那套（比如你用的是国际化版本，字段叫TaskName而不是title），就需要手动指定映射。工具支持一个 JSON 格式的映射文件：

w2d convert -i workbuddy_export.json -o output.ndjson \ --mapping custom_mapping.json

映射文件内容示例：

{ "title": "TaskName", "status": "State", "created_at": "CreationTime", "completed_at": "DoneTime", "assignee": "Owner" }

左边是 DSH 目标字段，右边是 WorkBuddy 源文件里的实际字段名。

这里有个注意事项：映射字段的时候不要自作聪明把两个源字段合并到一个目标字段里，比如有人想把first_name和last_name拼成full_name再映射。这个工具目前不支持这种合并操作，遇到这种情况我会用一段简单的预处理脚本先把源文件处理掉，再交给w2d去转换。

4.3 时间字段格式的处理策略

DSH 对时间字段要求很严格，必须是毫秒级 Unix 时间戳。而 WorkBuddy 导出的时间字段通常长这样：2024-03-01T10:00:00Z、2024/03/01 10:00:00，偶尔还有2024-03-01 10:00:00 +0800这种带时区的写法。

工具默认做了这些处理：

• 将 ISO 8601 格式字符串解析为 datetime 对象；
• 统一折算成 UTC 时间；
• 转换成毫秒时间戳输出。

假设你有一项任务的created_at是2024-03-01T10:00:00+08:00，转换后你会得到一个类似1709265600000的数字。这个数字就是 2024 年 3 月 1 日 02:00:00 UTC 的毫秒时间戳。

如果你希望保持原来的时区不做转换，可以用--timezone keep参数：

w2d convert -i input.json -o output.ndjson --timezone keep

但是我强烈不建议这么做。DSH 的很多聚合分析功能都假设数据是规范 UTC 时间，一旦混入不同时区的原始时间，后续做按小时聚合统计的时候会出现莫名其妙的偏移问题。我踩过一次这个坑，折腾很久才发现是时区没统一。

4.4 状态字段的取值映射

WorkBuddy 的任务状态一般有todo、in_progress、completed、archived，而 DSH 侧接受的枚举值通常是OPEN、IN_PROGRESS、DONE、CLOSED。工具内部默认做了映射：

WorkBuddy 原始值	DSH 目标值
todo	OPEN
in_progress	IN_PROGRESS
completed	DONE
archived	CLOSED

如果你的系统里状态值不是上面这套，比如用了finished来表示完成，那就需要在映射文件里补充：

{ "status": "status", "status_values": { "finished": "DONE", "waiting": "OPEN", "doing": "IN_PROGRESS" } }

4.5 批量转换项目目录

如果你手上不止一个 WorkBuddy 导出文件，而是一整个目录，可以用--input-dir参数：

w2d convert --input-dir ./exports/ --output-dir ./converted/ \ --pattern "*.json" --merge

这里--merge的作用是把目录里所有文件转换成同一个输出文件，而不是每个源文件单独输出。注意：--merge只对格式相同的文件有效，如果不同文件的字段结构差异很大，合并会产生大量空字段，建议分开转换。

5. 转换过程的核心原理

5.1 内部处理管线

整个转换过程可以拆成五个阶段，拿一次实测数据来解释：

第一，输入解析阶段。工具根据文件扩展名判断解析器：.json走 JSON 解析，.csv走 CSV 解析。JSON 解析时关注的是根节点是数组还是对象，如果根节点是对象，就找常见的集合字段名（tasks、items、data）作为记录列表。

第二，字段标准化阶段。根据内部默认映射或者你提供的自定义映射，把源字段名统一成目标字段名。这个阶段还会丢弃不在映射表里的字段。我的建议是：别指望工具自动保留所有字段，DSH 的数据模型是固定的，多出来的字段要么丢弃，要么放进extra_data这个兜底字段。

第三，类型转换阶段。把字符串类型的数字转成int、把时间字符串转成时间戳、把布尔字符串转成真正的布尔值。

第四，嵌套结构拍平阶段。把数组类型的字段拆出来。比如tags: ["调研", "产品"]会变成两条记录，task_id相同，但tag字段分别取调研和产品。

第五，输出阶段。按目标格式写出文件，默认是 NDJSON，同时支持--format csv和--format jsonl两种。

5.2 嵌套数据的拍平逻辑

嵌套数据的拍平是这个工具比较有特点的地方，也最容易让人困惑。举例来说，一条 task 记录里有三个子任务，工具不是把它们塞在一个字段里，而是拆成三行独立的记录输出，共用同一个父任务 ID。

这样做的好处是 DSH 侧做查询时不需要额外的 JSON 解析函数，直接按条件过滤就能拿到子任务数据。代价是如果你只想要父任务的统计信息，需要先去重。

实际使用中我发现一个规律：拍平之后的数据量会明显增多，原文件 100 条任务，拍平后可能变成 300 多条记录。这不是 bug，而是设计如此，方便下游做明细级分析。

5.3 为什么不建议直接用脚本处理

有人会问，字段映射和类型转换这种小事，自己用 Python 写个脚本不就行了？为什么非要引入这个工具？

我自己一开始也是这么干的，写了几十行脚本处理，结果发现两个硬伤。第一，边界情况太多。WorkBuddy 的导出格式会因为版本更新而改变字段结构，今天是subtasks，明天可能变成children，脚本就要跟着改。这个工具把常见的格式变体都兜住了，省心。第二，DSH 的时间戳和枚举转换规则里有不少隐含细节，自己写脚本很难一次想全。

6. 常见问题与排查技巧实录

6.1 转换报错：字段无法识别

错误信息长这样：

Error: unknown field 'assignee_name' in source record

原因：源文件里的字段名不在默认映射表中，也没在自定义映射文件里给出对应关系。

排查步骤：

1. 先跑w2d inspect -i workbuddy_export.json查看所有字段名。
2. 确认这个字段在 DSH 模型里确实需要，如果不需要，忽略即可。
3. 如果需要，就在自定义映射文件里补上对应关系。

这里要提醒一句：检查字段名时注意大小写和前后空格。WorkBuddy 有些版本会导出AssigneeName而不是assignee_name，肉眼看不出来，inspect输出里会忠实地显示出来。

6.2 时间戳处理导致的时间偏移

有一次我转换完成后，发现部分任务的时间比实际时间早了 8 小时。排查过程如下：

翻了一下映射文件，发现问题出在--timezone keep这个参数上。当时为了让时间看起来“和原数据一致”，特意加了这个参数，结果 DSH 侧做的是 UTC 运算，8 小时的时区偏差就产生了。

处理办法很简单：去掉--timezone keep，让工具统一转成 UTC。之后用 DSH 查询一个特定时间窗口的任务数量，和 WorkBuddy 页面上的数字核对了一遍，能够对应上。

6.3 非标准 JSON 导致的解析失败

WorkBuddy 有些老版本导出的 JSON 文件根本不是一个合法的 JSON 文档，而是每行一个 JSON 对象的“流式风格”。工具默认按标准 JSON 解析这种文件会直接抛异常。

实际上这个工具有两种解析模式，.json后缀默认走标准 JSON，如果文件实际是逐行 JSON，把后缀改成.jsonl或者显式指定：

w2d convert -i workbuddy_export.txt -o output.ndjson --input-format jsonl

这是我在处理一个超大导出文件时发现的用法，当时那个文件有 2 万多行，标准 JSON 解析器内存占用很高，改成 jsonl 流式解析之后内存占用下降了一个数量级。

6.4 内存占用过高

默认情况下工具会把整个文件读入内存做处理，一个 500MB 的 JSON 文件峰值内存可能会飙到 2GB 以上。如果你的机器内存有限，有两个办法：

办法一，加--stream参数启用流式处理模式，工具会逐条读取源记录、逐条转换、逐条写出。代价是不支持跨记录的聚合或排序操作，但大多数转换场景不需要这些。

办法二，先过滤再转换。用--filter-field status --filter-value completed只处理已完成的任务，减小数据量。

6.5 中文编码与乱码问题

如果你在 Windows 环境下操作，而且源文件里面有中文，需要注意输出文件的编码。默认输出是 UTF-8，但 Windows 的某些工具会错误地以 GBK 编码打开文件导致乱码。

处理办法：明确指定 UTF-8 带 BOM 格式：

w2d convert -i input.json -o output.ndjson --encoding utf-8-sig

这样输出的文件用任何常见编辑器打开都不会乱码，代价是文件开头多了 3 个字节的 BOM 标记。不过 DSH 导入端通常能自动识别跳过 BOM，所以问题不大。

7. 完整案例复盘：从 WorkBuddy 到 DSH 的一次真实迁移

最后用一个我实际经历过的完整案例把整个流程串起来。

背景：团队三个月前开始用 WorkBuddy 管理迭代任务，现在要把历史任务数据导入 DSH 做效率分析。源文件是 WorkBuddy 后台导出的workbuddy_backup_20240310.json，大小 186MB，文件里面的任务数据大概有几万条。

操作流程：

第一步，先检查环境，确认 Python 版本和工具版本都满足要求。

python3 --version w2d --version

第二步，用inspect查看源文件结构：

w2d inspect -i workbuddy_backup_20240310.json | head -n 40

这一步我发现了两个问题：一是导出的时间字段没有按默认的created_at命名，而是用了creationTimestamp；二是状态字段是中文的，不是英文枚举值。

第三步，创建自定义映射文件team_mapping.json：

{ "title": "title", "status": "status", "created_at": "creationTimestamp", "completed_at": "completionTimestamp", "assignee": "assignee", "priority": "priority", "status_values": { "未开始": "OPEN", "进行中": "IN_PROGRESS", "已完成": "DONE", "已归档": "CLOSED" }, "extra_data": "metadata" }

第四步，内存评估。源文件 186MB，按工具默认模式估算内存占用会在 600MB 以上，我部署的服务器只有 1GB 内存，果断加--stream参数。

第五步，执行转换：

w2d convert -i workbuddy_backup_20240310.json \ -o dsh_import_20240310.ndjson \ --mapping team_mapping.json \ --stream

转换耗时约 40 秒，输出文件 210MB，比源文件大了一些，原因是拍平子任务后记录条数增加了。

第六步，验证输出。随机抽取 10 条记录，手动核对时间戳转换和状态映射是否符合预期。又写了一小段校验脚本，检查所有记录里有没有空 ID、空 title，以及时间戳是否都在合理范围内。

第七步，导入 DSH。用 DSH 的批量导入接口把 NDJSON 文件上传，导入完成后再跑一条聚合查询验证数据可用性。

这个案例跑完之后，我最大的体会有三点：第一，映射文件一定提前跟实际数据对齐，不要照抄文档；第二，大型文件优先考虑流式模式，提前算好内存预算；第三，转换完成后必须做抽样核对，不能只盯着不报错就以为万事大吉。

工具本身不复杂，复杂的是数据本身的多样性。你把这两层的功课都做足了，从 WorkBuddy 到 DSH 的数据通路就能稳定跑起来，后续维护也不会三天两头出幺蛾子。