WorkBuddy到DSH迁移实战：格式转换、配置映射与自动化校验闭环

如果你也像我一样每天的工作记录都丢在WorkBuddy里攒了大半年之后突然发现数据分析侧只认DSH格式那你大概能体会我当时的处境。我当时的第一个念头是自己写个脚本做转换磨了两天脚本最后还是老实改用workbuddy-to-dsh把一堆边界情况交给这个现成的工具处理。这篇文章我打算把它从安装到自动化完整地走一遍。不是照着README念一遍而是把我自己在真实迁移过程中趟过的坑、验证过的命令、最后留用的配置全部摊开来说。不管是刚听说这个工具、第一次跑通命令的小白还是已经在手动写脚本转换、想找一个更稳方案的开发者应该都能从里面找到对应自己的那一段。1. 为什么要做WorkBuddy到DSH的迁移1.1 两种工具的根本定位差异WorkBuddy是我一直在用的一款轻量工作记录工具它的核心是把一天的时间切成一个个工作片段每个片段包含项目名、任务描述、开始时间、结束时间、标签。它擅长的是“记录”这件事数据以一种非常简单直观的形式存在本机基本就是一个JSON文件加一个可选的CSV导出字段命名完全按照日常用语来谁打开都能看明白。DSH则完全是另一侧的产物。它的定位是“消费”服务于数据管道、看板、统计报表这类下游场景。DSH要求每条记录是一个扁平事件字段有严格约定事件ID、事件类型、来源、发生时间、持续时间、附加指标JSON。字段名是英文驼峰式时间戳统一用UTC毫秒时长必须是浮点小时数。这两者之间的差异导致了一个很尴尬的局面数据在WorkBuddy里看着非常有条理但到了DSH这边完全不认。你没法把WorkBuddy的嵌套JSON直接丢给DSH的导入接口字段名对不上时间格式对不上项目的划分逻辑也不一样。于是workbuddy-to-dsh这个转换工具的出现也就顺理成章了。1.2 手工处理为什么总是翻车可能有朋友会说不就转个格式吗我写个脚本半小时就搞定了。我一开始也是这么想的后来发现真正的问题不在格式而在边界情况太多。最典型的是时间。WorkBuddy记录的是本地时间DSH要求UTC时间戳带毫秒而且跨天的工作片段要么自动拆分、要么得明确标记。第二是项目名合并问题同一个项目在WorkBuddy里叫“官网改版”在DSH里必须映射成web-redesign这样的英文标识否则下游报表的项目维度就是乱的。第三是时长字段WorkBuddy里是分钟整数DSH里要求浮点小时并保留两位小数。这些规则一次两次人工处理还能应付一旦数据量到几千条手工脚本就很容易在某一条边界数据上暴雷而且你很难发现。更麻烦的是每次导出的数据都会有细微的差异脚本今天能跑明天可能就挂。workbuddy-to-dsh的价值就是把这些规则集中、可配置、可验证地固化下来不用每次迁移都重新造一遍轮子。2. 安装与首次验证2.1 运行环境与安装命令这个工具基于Python开发要求Python 3.9及以上。它用到了比较新的类型注解和内置的zoneinfo时区库如果你还在用Python 3.8安装的时候会直接报依赖解析错误不用怀疑是装错了包版本不够就是版本不够。安装方式就一条命令pip install workbuddy-to-dsh如果你跟我一样系统里同时存在多个Python环境强烈建议用虚拟环境避免和系统自带的包管理搅在一起python3 -m venv .wb2dsh source .wb2dsh/bin/activate pip install workbuddy-to-dsh装完先确认版本这是排查后续一切问题的基础workbuddy2dsh --version正常会输出类似workbuddy2dsh 0.4.2这样一行。如果这里提示command not found多半是虚拟环境没激活或者pip的bin目录不在PATH里。macOS和Linux上常见的是前者Windows上常见的是后者处理方式大同小异把对应目录加进PATH就行。2.2 用--help快速建立全局认识我不太喜欢一上来就翻完整的文档习惯先跑一条命令建立骨架式的认识workbuddy2dsh --help输出里会把所有子命令列出来。这个工具的命令结构并不复杂核心就三个子命令convert、preview、validate外加一个全局的--config参数。这个设计思路我很认可先预览、再校验、最后转换三步分开而不是一把梭到底。看清楚命令结构之后再逐个看参数比一开始就捧着文档啃要高效得多。你会在后面逐步意识到preview和validate在正式迁移中起的作用比convert还大初期很容易被忽略但它们在数据迁移里恰恰是帮你省最多时间的两个命令。3. 核心命令与参数详解3.1 convert命令的完整参数convert命令负责真正的转换逻辑它的参数虽然不算多但每个都有讲究不搞清楚就很容易在后期出现问题。参数默认值作用--input必填WorkBuddy导出的源文件路径--output必填转换后的DSH文件路径--config./config.yaml映射配置决定字段怎么对应--project-map无项目名映射表JSON格式可替代配置文件里的映射段--tag-filter无按标签过滤只转换带指定标签的记录--merge-bynone将连续同项目的片段合并可选day或none--tzlocal源数据时区强烈建议显式指定举个例子一条最基本的转换命令长这样workbuddy2dsh convert \ --input workbuddy-export.json \ --output sessions.dsh.json \ --config workbuddy.yaml第一次跑的时候我建议把顺序固定下来先写--input和--output再看--config。以后每次执行都保持同样的参数顺序既方便看日志也方便写自动化脚本的时候不容易漏参数。3.2 配置文件里的映射逻辑配置文件是这个工具的灵魂。它做的事情本质上是“字段级翻译”把WorkBuddy里叫task_name的字段翻译成DSH里叫event_type的字段顺带做枚举值替换。source: timezone: Asia/Shanghai mapping: event_id: session_id event_type: task_name source: constant:workbuddy timestamp: start_time duration_hours: duration_minutes project_map: 官网改版: web-redesign 数据统计任务: analytics-report 内部工具开发: internal-tool transform: duration_divisor: 60 timestamp_format: utc-millismapping段里冒号左边是DSH的目标字段右边是WorkBuddy的源字段。constant:workbuddy这种写法表示不取自源数据直接写死一个常量。这个技巧很实用因为DSH要求每条事件必须有来源标识而WorkBuddy数据本身没有这个字段用常量填充是最干净的解法。project_map解决项目名不一致的问题这是整个工具里最容易被低估的一段配置。transform里的duration_divisor: 60意思是把分钟除以60转成小时这是时长单位转换最常用的动作。这个配置文件是YAML格式好处是注释友好坏处是字段一多容易写错缩进。我的建议是从官方示例模板改起不要从零写。缩进错了工具会直接报解析错误但解析通过了也不代表映射是对的所以后面一定要配合preview命令做确认。3.3 preview与validate为什么不能省preview命令不产生输出文件只把转换结果的前20条打印到屏幕。它的价值在于低成本检查字段映射有没有生效、项目名有没有被正确替换、时长是不是变成了预期的小时数这些都是屏幕上扫一眼就能确认的事情。workbuddy2dsh preview --input workbuddy-export.json --config workbuddy.yamlvalidate则是对转换后的DSH文件做全面合规检查。它会检查必填字段是否存在、时间戳是否可解析、duration_hours是否在合理范围内、事件ID是否重复。这一条命令我建议在每次转换之后都跑一遍养成习惯workbuddy2dsh validate --input sessions.dsh.json如果校验不过它会输出具体错误记录的定位提示比如“第42条记录duration_hours为负值”而不是笼统地告诉你“格式错误”。这一点对排查问题来说价值很大因为数据量大了以后你不可能人工逐条去翻问题出在哪直接定位到行号能省掉大量时间。4. 一次完整的数据迁移实战4.1 从WorkBuddy导出源数据我假设一个具体场景这也是我真实处理过的场景某团队要把过去三个月的工时记录从WorkBuddy迁移到DSH体系里用来跑月度工时报表。第一步永远是从WorkBuddy里导出原始数据。导出时我建议勾选全部字段不要精简。道理很简单映射阶段字段越多越好多余的可以在配置里忽略但缺失的到后面再补就麻烦了你得重新导出重跑。导出得到的JSON大概长这样[ { session_id: WB-20241001-001, project: 官网改版, task_name: 前端联调, start_time: 2024-10-01 09:12:00, end_time: 2024-10-01 10:40:00, duration_minutes: 88, tags: [前端, 联调, 关键路径] } ]拿到这个文件之后先别急着转换。先看一眼总条数再随机翻几条确认时间字段有没有缺失。我踩过的一个坑是WorkBuddy偶尔会因为软件异常退出在导出文件里留下几条没有end_time的记录。这种脏数据如果直接进转换流程时长字段会变成空最终导致DSH统计出来的总工时明显偏小而且很难追查。4.2 编写并验证映射配置基于上面的数据配置文件可以这样写source: timezone: Asia/Shanghai mapping: event_id: session_id event_type: task_name source: constant:workbuddy timestamp: start_time duration_hours: duration_minutes project_map: 官网改版: web-redesign 数据统计任务: analytics-report transform: duration_divisor: 60 timestamp_format: utc-millis rules: drop_missing_end_time: true注意最后我加了一条drop_missing_end_time: true让转换器直接丢弃没有结束时间的记录。它对统计报表影响不大但避免了脏数据污染目标端。如果你不想丢数据也可以改成fill_zero: true把缺失的时长记成0然后在DSH侧单独标记处理。配置写完先跑previewworkbuddy2dsh preview --input workbuddy-export.json --config workbuddy.yaml预览输出里重点看三样东西第一条记录的时间戳是否变成了UTC毫秒、event_type是否正确映射、duration_hours是否从88分钟变成了1.47小时。这三处都对映射基本就靠谱了。4.3 执行转换并进入校验闭环预览确认无误后执行转换workbuddy2dsh convert \ --input workbuddy-export.json \ --output sessions.dsh.json \ --config workbuddy.yaml转换过程完全在本地执行不涉及网络请求速度非常快几千条记录通常是秒级完成。这也是我敢直接在命令行里反复跑的原因错了重来成本极低。转换完成后再执行校验workbuddy2dsh validate --input sessions.dsh.json校验通过会有类似ALL RECORDS VALID的提示。如果提示有错误它会给你一个错误码。我整理了几个高频错误码的含义供你排查时对照错误码含义常见原因E1001缺少必填字段源记录字段被删或映射写错E1007时间戳无法解析时区不规范或时间格式变了E1009时长不在合理范围除零、负值或单位配错E1010事件ID重复多批次导出存在重叠4.4 批量导入DSH存储端校验通过之后最后一步是把sessions.dsh.json导入到DSH的存储端。导入这一步不属于本工具的范围不同团队的DSH实现方式不一样但有个通用规律DSH导入接口通常支持批量提交一次最好控制在500条以内单条数据过大容易触发网关超时。我个人的做法是写一个简单的分片导入脚本把文件按500行切分逐批提交。这样即使中间某批失败也能从断点续传不用重跑整个转换。split -l 500 -d sessions.dsh.json part-切出来之后按文件名顺序导入即可。导入完成后在DSH侧抽查一两天的数据和WorkBuddy里的原始记录对一下总时长。偏差在1%以内基本就没问题超过这个幅度就要回头查映射配置了。5. 我在实际使用中踩过的坑5.1 时区问题时间漂移了8小时这个坑几乎每个做数据迁移的人都会遇到。WorkBuddy默认用本地时区记录时间DSH要求UTC时间戳。如果配置文件里忘记写source.timezone工具会采用默认的local而这个local取的是运行转换时所在机器的时区。问题出在跨机器执行时你在自己电脑上转一遍是对的放上服务器定时跑服务器时区如果是UTC同一份源数据转出来的时间戳就会整体偏移8小时月度报表的时间分布直接错位。我当时是怎么发现的呢是某个月的工时分布图上所有任务都集中在凌晨两点到上午十点明显不是人类的作息。我的教训是配置里永远显式写死时区不要依赖“本地时区”这个不确定项。写Asia/Shanghai还是写UTC不重要重要的是写出来、写对。这样不管在哪台机器上跑结果都完全一致。5.2 重复事件ID多批次导出的重叠问题有一次我在校验阶段收到大量E1010报错提示事件ID重复。一开始我以为是工具的去重逻辑有bug后来排查发现是源数据的问题团队里有人手动跑了两次导出第二次导出的文件里包含了第一次的全部记录导致ID大面积重复。解决思路分两层。第一层是在源端去重比较所有记录的时间和片段描述只保留一份。第二层是在工具端处理给事件ID加前缀批次号比如在配置里设置id_prefix: batch2024q4这样即使两批数据ID相同转出来的事件ID也不冲突。这个参数比较隐蔽我也是翻源码的时候才发现的但实用性很强。5.3 标签文本规范化WorkBuddy里的标签是人手打的自由度很大。“前端”“前端 ”“前端,联调”这些看起来差不多的标签在数据库里其实是三个不同字符串。DSH侧的统计是按精确匹配做的标签不统一报表上的分类就会碎成一片。我用的办法是在配置里加一个tag_normalize段tag_normalize: trim: true collapse_spaces: true map: 前端 : 前端 前端开发: 前端先做前后空格清理再做同义词归一。这个功能不需要专门写脚本配置文件里声明就行。做完归一之后DSH侧的周报里前端类工时占比明显回升原因就是之前大量带尾随空格的“前端”被当成独立标签统计漏掉了。6. 从手动到自动定时转换与校验闭环6.1 用cron做每日自动转换数据迁移不是一次性的WorkBuddy每天都有新记录DSH需要保持更新。手动跑命令撑不了几天迟早要自动化。最简单的方案是cron定时任务。假设每个周日的晚上十点把本周新数据转一次0 22 * * 0 cd /data/workbuddy-to-dsh python3 -m venv .venv .venv/bin/workbuddy2dsh convert --input weekly-export.json --output weekly.dsh.json --config weekly.yaml .venv/bin/workbuddy2dsh validate --input weekly.dsh.json weekly.log 21这条任务有两个细节值得注意。一是每一次调度都显式走一遍venv的bin目录避免因为环境变量变化导致命令找不到二是把validate放在convert后面用串联校验失败就不会进入后续逻辑。日志重定向到weekly.log出问题的时候有迹可循。6.2 用文件监听做近实时转换如果业务上要求DSH数据的延迟在分钟级cron就不够了。可以用watchdog写一个简单的目录监听脚本一旦WorkBuddy导出的目录里出现新文件就立刻触发转换。from watchdog.observers import Observer from watchdog.events import FileSystemEventHandler import subprocess class ExportHandler(FileSystemEventHandler): def on_created(self, event): if event.is_directory: return if not event.src_path.endswith(.json): return subprocess.run([ workbuddy2dsh, convert, --input, event.src_path, --output, event.src_path.replace(.json, .dsh.json), --config, /data/workbuddy/config.yaml ]) if __name__ __main__: observer Observer() observer.schedule(ExportHandler(), /data/workbuddy/exports, recursiveFalse) observer.start() observer.join()这个脚本很轻量适合单机场景。注意on_created只在文件新建时触发如果导出工具是覆盖写入同一个文件就需要改用on_modified同时加一个文件长度检查防止文件写到一半就被拿去转换产出残缺数据。6.3 用Git钩子做转换前的质量闸门最后分享一个进阶玩法把转换步骤嵌进Git工作流里在提交前强制校验。做法是在仓库里加一个pre-commit钩子逻辑很简单如果本次提交涉及WorkBuddy导出文件就先转成DSH格式再校验结果不过就阻止提交。#!/bin/sh # .git/hooks/pre-commit STAGED_EXPORT$(git diff --cached --name-only | grep workbuddy.*\.json$) if [ -n $STAGED_EXPORT ]; then for f in $STAGED_EXPORT; do workbuddy2dsh convert --input $f --output /tmp/check.dsh.json --config config.yaml if ! workbuddy2dsh validate --input /tmp/check.dsh.json; then echo 转换校验失败请检查 $f exit 1 fi done fi这个方案的核心思路是把质量检查前移让问题在进入版本库之前就被拦下来。对团队协作来说这比事后排查要省心得多因为每个人提交时都会触发检查脏数据根本没有机会流到DSH侧。我自己的体会是workbuddy-to-dsh最大的价值不在于它一次性解决了转换问题而在于它提供了一套可重复、可校验、可自动化的数据流转闭环。配置好之后每周只需要看一眼校验日志剩下的活都交给定时任务去跑了。对任何一个长期维护数据管道的人来说这种“配置一次、稳定运行”的状态才是最舒服的。