1. 工具定位与使用场景1.1 workbuddy-to-dsh 到底解决什么问题先直接说结论workbuddy-to-dsh是一个把 WorkBuddy 平台里的工作数据包括任务、项目、时间记录、日志备注等批量转换为 DSH 标准目录结构的命令行工具。说白了它就是个格式转换器帮你在两个系统之间做数据迁移节省手动复制粘贴的时间避免漏数据。WorkBuddy 我估计不少做数据标注、远程协作、灵活用工的朋友都接触过它本身是一个任务管理和工作流追踪平台你在上面接任务、提交结果、记录工时平台会生成一份包含了所有工作痕迹的数据快照。但问题是WorkBuddy 的导出格式往往是一个大的 JSON 压缩包或者结构复杂的 CSV 表字段命名跟平台内部逻辑绑定直接拿去给 DSHData Science Hub这类数据分析平台用根本对不上号。DSH 这类平台通常期望的数据结构是标准化的每个工作项有唯一 ID、有清晰的时间戳、有用户标识、有任务分类。而 WorkBuddy 导出的数据里这些信息可能分散在不同嵌套字段中甚至混杂着大量无关的过程日志。workbuddy-to-dsh干的事情就是把这些杂乱的数据做一次映射、清洗、重组最后输出成 DSH 能直接吃的标准目录。这个工具最典型的应用场景有三个个人数据归档把你在 WorkBuddy 上的完整工作历史导出转成 DSH 格式作为个人工作履历的标准化存档。团队数据迁移整个团队更换工作流平台需要把历史数据从 WorkBuddy 批量平移进 DSH 平台。数据分析前置处理DSH 平台需要导入 WorkBuddy 的数据做效率分析但原始导出格式不符合入库规范。我自己试下来最大的感受是这东西不是万能的但只要你 WorkBuddy 导出的数据本身是完整的它能把 95% 以上的脏活累活给你干完剩下那 5% 也就是核对和补字段的功夫。1.2 你适合用这个工具吗在动手之前先花 10 秒钟判断一下你是否需要它省得白折腾。符合以下任一情况你大概率用得上你的 WorkBuddy 账号里累积了超过几百条任务记录手动搬不太现实。你们团队的工作日志、工时记录要定期同步到 DSH 做产出分析。你需要把 WorkBuddy 数据导出后作为第三方工具的数据源而第三方工具只认 DSH 目录规范。你已经试过手动整理发现 WorkBuddy 的嵌套 JSON 结构实在头疼嵌套三层起步看得眼睛发花。不符合这些情况的话比如只是偶尔导出一两张表看一眼直接手工处理可能更快工具反而显得多余。我见过不少人在没搞清楚自己需求的情况下就上手结果卡在环境配置上最后抱怨工具不好用。其实不是工具不行是场景没选对。workbuddy-to-dsh的价值在“批量、重复、规范化”你要是只有几条数据不用折腾。2. 环境准备与安装2.1 依赖环境与安装步骤workbuddy-to-dsh是一个用 Python 写的命令行工具安装过程非常常规。前提是你电脑上得有 Python 3.8 以上的环境。还没装 Python 的话去官网下载安装包安装时记得勾选“Add Python to PATH”这一步很多人会漏漏了之后命令行里敲python会提示找不到命令。装 Python 这个环节我多说一句别贪新别装 3.13 以上版本倒不是说不能用而是部分依赖库的编译版本可能还没跟上到时候报错你看不懂浪费时间。我实测下来 Python 3.10 和 3.11 最稳。安装工具只需要一行命令pip install workbuddy-to-dsh如果你的机器上有多个 Python 版本可能需要用pip3代替pip。装完之后不用急着跑先确认一下版本号。workbuddy-to-dsh --version能输出版本号说明安装成功。如果提示command not found多半是 Python 的 Scripts 目录没加进 PATH去系统环境变量里补一下就行。2.2 验证安装是否成功除了看版本号我建议再做一步验证用工具自带的示例数据跑一遍完整流程。第一次用就从真实数据开始容易出问题因为你不知道问题是出在数据上还是工具上。先拿官方示例数据练手确认工具本身没问题再上真实数据排错范围能缩小一半。workbuddy-to-dsh --example这个命令会在当前目录生成一份示例的 WorkBuddy 导出文件和对应的说明文档。跑一遍workbuddy-to-dsh convert看到输出目录里出现标准 DSH 结构的文件就说明整个链路是通的。这一步花不了 5 分钟但能帮你省下后面 1 小时的排查时间。我一开始跳过了这步直接用生产数据跑报了个编码错误我以为是工具的问题排查半天才发现是自己数据里的 UTF-8 BOM 头导致的浪费了不少时间。3. 核心功能与原理拆解3.1 三种数据来源的适配workbuddy-to-dsh支持三种输入方式对应不同用户的导出习惯。第一种是 JSON 压缩包这是 WorkBuddy 后台直接导出的原始格式。点击导出后平台会给你一个.zip文件里面基本包含了你账号下的全部数据包括任务详情、工时记录、评论、附件元信息等。这种格式最完整嵌套也最深。第二种是 CSV 表格目录适合那些导出时选择了按任务拆分的用户。WorkBuddy 允许按任务维度导出 CSV每个任务一个文件夹里面放着task_info.csv、timelog.csv、notes.csv等表格。这种导出方式更干净但可能丢失部分关联信息。第三种是单文件 JSON通常是调用 WorkBuddy API 拉取的数据快照。需要你安装了相关的客户端脚本自己先提取出来。workbuddy-to-dsh能识别三种格式自动判断入口。判断依据是--input参数后面跟的是文件夹还是文件如果是文件夹再看里面是直接有 JSON 文件还是一个.zip。上传数据时建议保持导出的原始结构不变不要手动改文件夹名或者把里面的文件挪位置否则工具在遍历时可能匹配不到预期文件报错。3.2 映射规则与 DSH 目录结构这是整个工具的核心逻辑。WorkBuddy 的数据模型和 DSH 的目录规范不是一一对应的工具内部有一套映射规则你需要了解它不然转换完发现字段变少了你会一头雾水。WorkBuddy 里的一个 Task任务在 DSH 规范里大致对应一个“WorkItem”。两者的核心字段映射逻辑大致这样WorkBuddy 字段DSH 字段说明task.task_idid任务唯一标识直接透传task.titletitle任务标题task.statusstatus状态字段做了一组枚举映射task.created_atcreated_at创建时间时区统一转成 UTCtask.deadlinedue_date截止时间缺失时留空task.owner.usernameassignee从嵌套结构里取出来submission.resultoutput_ref提交结果引用路径timelog.duration_minutesduration_seconds单位转换分钟转秒状态字段的映射是重点。WorkBuddy 的状态可能有几十种自定义值DSH 规范只认pending、in_progress、completed、failed、cancelled五种。工具内置了一张映射表凡是表里没有的状态统一归为pending并在转换日志里标记 WARNING提示你手动确认。这个设计比较保守宁可丢状态也不乱归类避免 DSH 平台收到非法枚举值导致入库失败。时间字段的处理也值得一提。WorkBuddy 导出时间默认是带时区的 ISO 8601 格式比如2025-06-01T10:00:0008:00。DSH 规范要求所有时间统一为 UTC工具在转换时会做时区归一化。如果你的 WorkBuddy 数据里时间没有带时区后缀工具会假设它是服务器时区通常是 UTC这时候就可能导致你看到的本地时间和转换后的时间对不上。这种情况建议在导出前确认一下 WorkBuddy 设置里的时区配置。输出目录结构长这样output/ metadata.json work_items/ YYYYMMDD/ item_1234/ data.json attachments/ item_1235/ data.jsonmetadata.json记录了整个转换任务的元信息包括源文件哈希值、转换时间、工具版本、发生过的 WARNING 列表。这个文件很有用排查问题全靠它。work_items目录按日期分组存放转换后的数据每天一个文件夹方便按时间维度批量处理。3.3 关键参数详解这个工具的参数不算多但每个都很关键用错一个结果就差很多。我把最常用的一组参数拆开揉碎了讲。workbuddy-to-dsh convert \ --input ./workbuddy_export.zip \ --output ./dsh_ready \ --format zip \ --mapping custom_mapping.json \ --workspace my_workspace \ --on-warning continue--format指定输入格式有zip、csv、json三种可选。如果这里不填工具会根据--input指向的路径后缀自动判断。我建议最好手动指定原因是有时候你给的目录里既有.zip又有拆出来的文件夹自动判断可能会选错。--mapping是高级玩法。如果你团队自定义了 WorkBuddy 的任务状态或者需要把某些自定义字段也带出来可以直接传一个 JSON 文件的路径里面写上补充的映射规则。默认映射表覆盖了常规情况但如果你的数据有特殊字段不加--mapping的话那些自定义字段就被丢弃了。--workspace参数给输出数据打一个工作区标签。DSH 平台通常区分多个工作区比如“标注组A”和“标注组B”加了标签之后导入平台时会自动归入对应空间。不加也行默认用源数据的 workspace 字段。--on-warning决定遇到警告时如何处理可选continue和abort。我建议选continue让转换过程跑完结束后再集中看 WARNING 日志逐条决定哪些要补处理。直接abort的话经常一个不痛不痒的未知状态字段就中断整批转换很不划算。4. 实操最完整的迁移流程4.1 从 WorkBuddy 导出数据这一步是在 WorkBuddy 平台内操作的。登录你的账号进入个人中心或团队管理后台找到“数据导出”入口点击导出后会有一个数据包生成的过程通常需要等几分钟。数据量大的话可能更久正常导出后你会收到一个下载链接或站内通知。我要提醒两个容易踩的坑第一个坑是导出范围的选择。很多导出界面会默认只导出“最近30天”的数据你得仔细看改成“全部时间”或者按需勾选时间范围。我见过有人导出完高高兴兴拿去转换结果发现数据少了一大半MP回来一看只导出了最近一个季度。第二个坑是附件的处理。WorkBuddy 的任务可能会关联附件文件导出时默认可能只包含元数据不包含附件本身。如果你后续需要在 DSH 里访问原始附件导出时务必勾选“包含附件文件”。这会导致导出文件变大不少但换来的是数据的完整性。导出完成后你会拿到一个.zip文件不要解压直接把它作为workbuddy-to-dsh的输入。工具支持直接读取压缩包让它自己解压到临时目录处理这样避免了解压后文件编码问题导致的路径错乱。4.2 执行转换的命令与参数数据导出完成后执行转换命令。以下是我用下来最顺手的一套命令workbuddy-to-dsh convert \ --input ./workbuddy_export_202506.zip \ --output ./dsh_output \ --format zip \ --on-warning continue \ --verbose--verbose参数会输出详细的进度信息包括当前处理到哪个任务、是否发生警告、映射了哪些字段。跑批量转换的时候看着进度条心里踏实不至于黑屏卡住不知道死活。执行过程中你会看到类似这样的日志[INFO] 开始解析 workbuddy_export_202506.zip [INFO] 解压完成3,286 个文件 [INFO] 发现 1,024 个任务2,341 条工时记录 [INFO] 正在映射字段... [WARNING] 任务 1024 状态 unknown_status 未命中映射表已归为 pending [INFO] 转换完成输出目录 dsh_output看到 WARNING 不要慌这很正常。重点是转换完成后去做两件事一是打开metadata.json看 WARNING 汇总二是抽查几个重点任务的输出文件。4.3 数据完整性校验转换结果对不对不能靠眼睛看要有一个验证思路。我的做法分三步。第一步数量核对。转换日志会显示“发现多少任务、多少工时记录”你要打开 WorkBuddy 平台后台的任务列表核对总数是否一致。这个步骤最笨但最有效数量对不上说明导出阶段就漏了不用继续往下查。第二步抽查字段映射。用文本编辑器打开任意一个data.json重点看几个关键字段ID 是否和 WorkBuddy 里的一致、时间是否转换成了 UTC、状态是否落在 DSH 的五种枚举值里。不需要每个都看随机抽 10 条过一遍。第三步检查附件引用。如果你导出时勾选了附件这个工具默认会保留附件的相对路径。注意工具只拷贝引用信息不负责真的把附件文件归类到attachments/目录下。也就是说原始附件文件需要你手动从 WorkBuddy 导出包里拷贝到输出目录对应的attachments/文件夹。这一步容易忽略做完了才算是真正的完整迁移。我强烈建议转换完成后就把metadata.json归档一份。它相当于这次转换的“快递单号”以后如果数据对不上追查起来有依据。不加这一步时间久了根本想不起来一批数据是从哪导出的、用了什么映射版本。5. 常见问题与排查技巧5.1 高频问题速查表把这段时间我遇到的以及身边朋友问得最多的问题列成一张表可以直接照着排查。问题现象可能原因解决办法安装时报pip: command not foundpip 没有单独加进 PATH用python -m pip install workbuddy-to-dsh代替转换报编码错误UnicodeDecodeError数据文件带 UTF-8 BOM 头用--encoding utf-8-sig参数指定编码提示找不到任务文件导出内容里没有包含任务明细回 WorkBuddy 导出界面勾选包含任务详情后再导出时间字段比本地时间差 8 小时WorkBuddy 时区设置为服务器 UTC且导出未包含时区信息在 WorkBuddy 设置里将时区改为你所在时区重新导出自定义字段丢失没有提供--mapping文件写一个自定义映射 JSON把需要保留的字段列进去转换后状态全变成 pending自定义状态没在默认映射表里查看 WARNING 日志把映射规则补充到--mapping文件输出目录为空但无报错--input指向了错误的子目录确认--input指向的目录直接包含任务数据而不是外层包装目录数据量大时内存占用过高工具默认一次性读入所有任务加入--chunk-size 500参数分批次处理5.2 数据丢失的排查思路工具跑完了但你发现 DSH 里导入的数据少了一个字段甚至少了一条记录。这种问题最有排查价值我给你一个标准思路照着来不会乱。先去翻metadata.json里面记录了整个转换过程的所有异常。重点看两个字段warnings_count和skipped_items。skipped_items是个列表记录了哪些条目因为什么问题被跳过。大部分情况下数据显示不全的根因都能在这里找到。如果metadata.json显示一切正常但数据还是不对那就是源数据的问题。这时候回到 WorkBuddy 导出包的原始文件手动找到出问题的那条任务看它是不是缺了某个必填字段。我碰到过一种情况某个任务在 WorkBuddy 里task_id是空的导出时生成了一串临时 ID但工具在映射时判断“ID 缺失”直接跳过。这种属于源头脏数据只能在 WorkBuddy 里补全后再重新导出。还有一类隐蔽问题是附件路径。DSH 的output_ref字段如果不带具体的文件名只有目录路径会导致 DSH 平台在读取附件时找不到文件。解决方法是检查data.json中attachments数组里的路径是否都能在输出目录里找到对应文件。排查数据问题我最大的经验是别瞎猜原因先看工具日志再看源数据最后才是找工具的问题。90% 的情况不是工具 bug而是源数据本身就脏。5.3 编码问题与跨平台兼容性workbuddy-to-dsh处理编码问题的方式比较保守默认按 UTF-8 读取。Windows 系统下从 WorkBuddy 导出的 CSV 文件经常带一个 BOM 头Byte Order Mark这在记事本里看不见但 Python 读的时候会把\ufeff当成第一个字符导致第一列字段名不匹配进而整行解析失败。这个问题好解决加个参数指定编码就行workbuddy-to-dsh convert --input ./export --encoding utf-8-sig另外提醒一句输出目录的路径尽量不要有中文和空格。工具本身支持但 DSH 平台在后续读取时部分内部组件对非 ASCII 路径支持不太好出现过读取失败的情况。统一用英文命名的目录省心。6. 实操过程与习惯养成6.1 批量转换的注意点如果你要处理的是整个团队的 WorkBuddy 导出几十个甚至上百个压缩包我建议你做一个简单的批量脚本而不是手动一个个跑。在 Linux 或 Mac 上写一个几行的 Shell 循环就行Windows 上用 PowerShell 也差不多。for f in ./exports/*.zip; do workbuddy-to-dsh convert --input $f --output ./done/$(basename $f .zip) done跑完之后批量检查每个输出目录里的metadata.json把warnings_count不为 0 的挑出来单独处理。这样做的好处是你的注意力只需要集中在有异常的批次上不需要每个都人工盯一遍。批量处理还有一个好处是可以对比不同批次之间的数据结构差异。比如你发现 A 批次有 20 个 WARNINGB 批次只有 3 个说明两个批次的源数据可能是在不同时间段导出的WorkBuddy 平台的数据结构有过调整这时候把两个批次的metadata.json放在一起对比很容易看出差异点。6.2 给长期使用者的建议数据迁移这件事做完一次不意味着结束。如果你打算把 WorkBuddy 的数据持续同步到 DSH我建议你固定一套流程形成习惯。这也是我反复强调的“标准化”思路。时间维度上按批次归档不要让所有的输出文件都堆在一个目录里。一个月一个文件夹命名带上日期比如dsh_output_202506找数据的时候非常方便。字段维度上建一个自定义映射文件的模板。把你团队在 WorkBuddy 里用到的状态枚举、自定义标签、人员别名都整理好存成一份标准的mapping.json放到固定的配置目录。每次转换都用同一份映射文件保证批次之间字段映射的一致性。校验维度上跑完转换后不要急着收工花三分钟看一眼日志和元数据。我养成习惯之后漏数据这类问题基本没有再出现过。因为只要有一次数据对不上往前查就是一条清晰的日志链路。写在最后做数据迁移久了你会发现工具本身只是冰山上的一角更多的时间花在理解数据、验证数据、修正异常上。我自己的体会是第一次用workbuddy-to-dsh的时候光是搞懂映射规则就花了半天。但搞清楚之后后面每次迁移都很快几分钟跑完剩下时间就是各种核对和验证。最后再分享一个小技巧转换完的data.json里其实藏着一个“时间线”字段按时间倒序排列了该任务在 WorkBuddy 上的所有状态变更记录。DSH 平台默认不会展示这个字段的完整细节但分析任务流转效率时这个时间线比任何统计报表都直观。你可以基于它自己算某个环节的平均耗时这个数据反而是整个迁移过程中最有价值的副产品。