最近在给一个团队做数据整理遇到一个挺典型的场景团队一直用 WorkBuddy 记录任务和工时积累了好几百条工作记录但下游的报表系统只接受 DSH 格式的导入文件。一开始大家想的是从 WorkBuddy 导出 Excel 再手工改结果试了两天就放弃了——字段对不上、日期格式混乱、中文经常乱码。后来我写了个小转换工具把 WorkBuddy 导出的 JSON 一键转成 DSH整个过程才算稳定下来。这篇就把整个转换思路和实操过程完整拆一遍包括字段映射怎么设计、日期格式怎么处理、批量转换怎么写脚本、踩过哪些坑。如果你也在用 WorkBuddy 做任务管理或者手头需要把某类业务数据转成 DSH 格式交给下游系统这篇文章可以直接照着抄。1. 为什么要把 WorkBuddy 数据转成 DSH 格式1.1 WorkBuddy 数据不直接可用的三个痛点先说结论WorkBuddy 本身是个挺好用的任务管理工具团队用它记任务、派工、填工时数据都在里面。问题在于它导出的数据格式和下游系统之间天然存在三堵墙。第一堵墙是字段不统一。WorkBuddy 里叫负责人的字段到报表系统里可能叫ownerWorkBuddy 里叫截止时间的字段报表系统里叫deadline一个叫状态另一个叫status而且枚举值还不一样WorkBuddy 里是中文进行中报表系统认英文in_progress。纯手工处理光这一层字段映射就得花大半天。第二堵墙是日期格式。WorkBuddy 导出的时间可能是2025-06-18 14:30:00也可能是 ISO 格式的2025-06-18T14:30:00Z但下游系统往往只认某一种。手改很容易漏掉一旦解析失败整条记录被跳过数据就悄悄丢了。第三堵墙是特殊字符和编码。任务描述里经常出现换行、引号、竖线这类字符直接拼到 DSH 里会把文件结构打乱。再加上中文编码问题Windows 下打开导出的文件经常是一堆乱码。这三堵墙就是文章标题里转换两个字的真正含义——不是简单改个后缀名而是要做一层完整的字段映射、格式归一化、字符转义和编码处理。1.2 DSH 格式在设计上的优势DSH 格式全称是 Data Structured Header带结构化头部的数据文件之所以被很多下游系统选为导入标准是因为它有这几个特点。它的文件头部自带版本声明和字段定义类似身份证上的信息栏。每条记录按照统一的字段模板排列解析器不用猜字段结构看到什么字段就填什么位置。这种设计天然适合批量导入、数据迁移和跨系统数据交换。举个例子一个标准的 DSH 文件长这样#DSH v1.0 task_id:task-1001 task_name:完成用户模块测试 status:in_progress owner:devexample.com deadline:20250618T143000 tags:测试|用户模块 estimated_hours:8.50 --- #DSH v1.0 task_id:task-1002 task_name:修复登录接口超时 status:done owner:opsexample.com deadline:20250617T120000 tags:bug|接口 estimated_hours:3.00注意看每个文件头的#DSH v1.0声明了格式版本字段名:值定义了每条记录的属性---分隔不同记录。这个结构虽然简单但是机器可读性极强解析逻辑只需要十几行代码就能写完而且不容易出歧义。1.3 谁需要这个转换方案我整理下来以下三类人最需要这个转换能力。第一类是团队负责人。他们需要把 WorkBuddy 里的任务和工时汇总成周报、月报但公司统一用某个报表系统不接受 WorkBuddy 的原生导出。第二类是数据管理员。他们负责维护各业务系统的数据字典经常要同步任务数据到数据仓库DSH 就是其中一种标准交换格式。第三类是开发人员。他们接到需求需要写一个自动化脚本让 WorkBuddy 的数据每天定时同步到下游系统减少人工导出导入的重复劳动。无论你是哪一类核心诉求都一样让 WorkBuddy 的数据能被下游系统识别和使用同时保证数据在转换过程中不丢失、不出错。下面的内容就围绕这个目标展开。2. 转换前的准备导出、格式规范与工具环境2.1 从 WorkBuddy 导出原始数据WorkBuddy 支持的数据导出方式主要有两种。第一种是在 Web 端直接导出进到项目的任务列表页面点击导出按钮选择 JSON 或 CSV。第二种是通过开放接口拉取如果团队开了接口权限可以写脚本定时拉取任务和工时数据。我的建议是选 JSON不要选 CSV。原因是 JSON 保留了字段结构层级嵌套不会丢CSV 会把多值字段比如标签拍平成字符串后面还得再做一层拆分。导出之后的 JSON 一般是数组结构里面每个元素是一条任务记录长这样[ { task_id: task-1001, task_name: 完成用户模块测试, status: 进行中, assignee: 张三, assignee_email: devexample.com, due_time: 2025-06-18 14:30:00, tags: [测试, 用户模块], estimate_hours: 8.5 }, { task_id: task-1002, task_name: 修复登录接口超时, status: 已完成, assignee: 李四, assignee_email: opsexample.com, due_time: 2025-06-17 12:00:00, tags: [bug, 接口], estimate_hours: 3 } ]如果导出的是 CSV也没关系可以先在表格软件里另存为 JSON或者用脚本转一下。重点是确认原始数据里有 task_id、task_name、status、assignee、due_time、tags、estimate_hours 这些字段它们基本覆盖了任务管理最核心的属性。2.2 DSH 格式的字段规范在动手写转换脚本之前一定要先把 DSH 格式的字段规范确认清楚。不同下游系统对 DSH 的实现细节可能有差异但核心规则是一致的我列在这里。DSH 文件的字段名以开头后面紧跟字段名冒号后面是字段值一行一个字段。每条记录之间用---分隔文件的第一行必须是#DSH v1.0版本声明。多值字段用竖线|连接比如标签有两个值就写成tags:测试|用户模块。字段值的类型一般分为字符串、整数、浮点数、日期时间四种日期时间统一采用紧凑格式比如20250618T143000表示 2025 年 6 月 18 日 14 点 30 分 00 秒。还有一个容易忽略的规则如果字段值里本身包含了竖线或冒号必须先用反斜杠转义。比如任务名称里写了需求评审v2 版本冒号前面要加\。这些规则如果不提前确认转换脚本写出来很容易被下游系统退回。2.3 准备 Python 环境与转换脚本转换脚本用什么语言写我推荐 Python原因很简单标准库的json和datetime足够处理导出文件不需要安装额外依赖而且字符串处理能力比 shell 脚本强得多遇到特殊字符转义也有灵活的切片和替换方案。环境准备只需要两步。第一步是确认本机装了 Python 3.8 以上版本打开终端敲python3 --version能正常输出版本号就行。第二步是建一个目录把导出的 JSON 文件和下面文章里要用到的转换脚本放到同一个目录方便测试。不需要安装任何第三方库这既是优点也是约束——意味着所有转换逻辑都要用标准库自己实现但好在 DSH 转换并不复杂几十行代码足够。3. 核心转换逻辑字段映射与数据处理细节3.1 字段映射表怎么设计字段映射是整个转换过程的核心。映射表做得好不好直接决定转换后的数据能不能被下游系统接受。我的做法是先在纸上列一张二维表左边是 WorkBuddy 的原始字段右边是 DSH 的目标字段中间写转换规则然后再写代码。这里给出我实际用过的映射表WorkBuddy 字段DSH 字段类型转换规则task_idtask_idstring直接映射task_nametask_namestring去除首尾空格转义特殊字符statusstatusenum中文枚举值映射为英文枚举值assignee_emailownerstring转小写作为责任人标识due_timedeadlinedatetime转换为紧凑时间格式tagstagsarray数组元素用竖线拼接estimate_hoursestimated_hoursfloat保留两位小数无sourcestring补充固定值 workbuddy注意两个细节。第一个是assignee_email映射到owner而不是本来的负责人姓名因为下游系统通常以邮箱作为唯一标识避免重名导致数据错乱。第二个是额外增加了一个source字段标记数据来源方便后期追溯。这类补充字段在实际项目中非常实用尤其是当同一套 DSH 文件可能接收多个来源数据的时候。3.2 日期时间与枚举值的归一化日期时间处理是转换脚本里最容易出问题的地方。WorkBuddy 导出的 due_time 是2025-06-18 14:30:00带空格而 DSH 要求20250618T143000不带空格而且中间多个 T。如果直接用字符串替换把空格删掉会出现2025061814:30:00这种半吊子结果下游系统解析直接报错。正确做法是用datetime.datetime.strptime()解析原始字符串再用strftime()格式化为目标格式。这样不仅格式正确还能顺便校验日期合法性遇到非法日期就直接报错不至于把脏数据传到下游。枚举值归一化同理。WorkBuddy 里中文状态可能有未开始进行中已完成已暂停下游系统认todo、in_progress、done、paused。这一步必须建立显式的枚举映射字典不能靠猜。如果遇到字典里没有的枚举值最好让脚本报错而不是默认填充宁可不转换也不能把错误数据传过去。3.3 特殊字符、空值与多值字段处理特殊字符处理是 DSH 转换的隐藏难点。想一想任务名称可能包含英文双引号、中文冒号、甚至包含竖线比如优先级P0|紧急修复如果不处理竖线会被下游解析成多值分隔符整条记录结构直接崩掉。我的处理方案是写一个escape_value()函数遍历所有字符串字段把|、:、\、换行符\n统一在前面加反斜杠转义。这个函数要在字段映射之前调用因为一旦做了字符串拼接再想区分分隔符和值里的特殊字符就来不及了。空值处理也要有明确策略。比如有些任务没有设置截止时间due_time是空字符串这时候不能直接生成一个空的deadline:这会让下游系统读取失败。我一般会跳过这个字段或者填充一个约定好的默认值比如19700101T000000表示未设置。这个策略要在映射表里写清楚不要写一半忘一半。多值字段 tags 相对简单用|拼接数组元素即可。但如果标签本身也包含竖线很少见但可能还是要先走一遍转义函数再拼接。3.4 转换校验怎么确认数据没丢数据转换最怕的不是转错了格式而是悄悄丢了记录。所以我每次做完转换一定会做输入输出数量校验脚本读进来多少条 JSON 记录最终生成的 DSH 里就应该有多少个---分隔的区块。这个校验用一行代码就能实现数一下 DSH 字符串里---出现次数加一对比输入数组的长度。对不上就是转换过程中有问题立即中止并输出日志不要生成半成品文件。另外一个更细的校验是字段级校验。每一条 DSH 记录必须包含映射表里所有必填字段比如 task_id、task_name、status、owner、deadline。在脚本里用一个assert判断缺字段就直接报错标明是哪条记录缺了什么。这种做法在数据量大的时候特别好用几百条记录里有一条异常日志里一眼就能定位。4. 实操演示从 WorkBuddy JSON 到 DSH 文件的完整跑通4.1 单文件转换命令行直接输出先把核心转换脚本写出来。下面的代码可以直接存成convert.py放在 WorkBuddy 导出文件同目录下运行。import json import datetime import sys def escape_value(value): if not isinstance(value, str): return value value value.replace(\\, \\\\) value value.replace(|, \\|) value value.replace(:, \\:) value value.replace(\n, \\n) return value.strip() def map_status(status): status_map { 未开始: todo, 进行中: in_progress, 已完成: done, 已暂停: paused, } if status not in status_map: raise ValueError(f未知状态: {status}) return status_map[status] def map_deadline(due_time): if not due_time: return 19700101T000000 dt datetime.datetime.strptime(due_time, %Y-%m-%d %H:%M:%S) return dt.strftime(%Y%m%dT%H%M%S) def convert_record(record): lines [#DSH v1.0] lines.append(ftask_id:{escape_value(record[task_id])}) lines.append(ftask_name:{escape_value(record[task_name])}) lines.append(fstatus:{map_status(record[status])}) lines.append(fowner:{escape_value(record[assignee_email].lower())}) lines.append(fdeadline:{map_deadline(record.get(due_time))}) tags record.get(tags) or [] lines.append(ftags:{escape_value(|.join(tags))}) lines.append(festimated_hours:{float(record.get(estimate_hours, 0)):.2f}) lines.append(source:workbuddy) return \n.join(lines) \n--- def main(): input_path sys.argv[1] if len(sys.argv) 1 else workbuddy_export.json output_path sys.argv[2] if len(sys.argv) 2 else output.dsh with open(input_path, r, encodingutf-8) as f: records json.load(f) blocks [] for record in records: blocks.append(convert_record(record)) # 数量校验 content \n.join(blocks) block_count content.count(---) if block_count ! len(records): raise RuntimeError(f记录数量不匹配: 输入 {len(records)} 条, 输出 {block_count} 条) with open(output_path, w, encodingutf-8) as f: f.write(content \n) print(f转换完成: {len(records)} 条记录已写入 {output_path}) if __name__ __main__: main()这个脚本处理的就是前面 JSON 示例里的数据执行完以后会在当前目录生成output.dsh。跑通之后可以先打开 DSH 文件人工抽看两三行确认字段被正确转换。4.2 批量转换写一个批处理脚本单个文件转换只适合测试。实际工作里往往要把一个月的数据按周拆成多个文件或者把团队里不同项目的导出文件分别转换。这时候就需要批量处理。批量处理的脚本逻辑很简单遍历指定目录里的所有.json文件逐个调用之前的转换函数输出到对应的.dsh文件最后汇总打印结果。写出一个 shell 循环也很方便for f in ./data/*.json; do echo 正在转换 $f python3 convert.py $f ${f%.json}.dsh done这个循环会把data目录下所有的 JSON 文件都转成同名 DSH 文件。运行时要注意文件路径别写错建议第一次先建一个test子目录把一两个测试文件放进去试运行确认没问题再处理真正的数据。批量转换最大的好处是省人工同时保证每次转换用的都是同一套规则。手工改能出 10 种不同风格的文件脚本生成的文件永远是同一套格式下游系统导入时省掉大量沟通成本。4.3 对接下游系统前的一步验证转换完成并不代表万事大吉对接下游系统之前最好做一次验证。我有一次把数据转完发给对接方结果对方说导入失败后来排查半天发现是文件编码问题。当时脚本用默认编码输出在 Linux 下是 UTF-8被下载到 Windows 后在老旧系统里打开成了乱码。现在的做法是转换完以后用 Python 读一遍 DSH 文件检查三个点文件开头是不是#DSH v1.0、每条记录的必填字段是不是都在、---分隔符的数量对不对。这三个点检查完再交给下游系统导入。如果对文件编码有要求可以在输出时指定编码。比如明确要 UTF-8 带 BOM把最后写入文件的open改成open(output_path, w, encodingutf-8-sig)。这个决定最好在对接前确认而不是等对方报错了再返工。5. 常见问题排查与避坑经验5.1 中文内容导出后乱码乱码问题基本出在编码环节。WorkBuddy 导出 JSON 时用的是 UTF-8脚本读取时也要指定 UTF-8输出 DSH 时同样指定 UTF-8。只要三个环节有一个不一致就会出现乱码。排查方法很简单在终端打开 DSH 文件如果中文显示成一组带斜杠的 Unicode 转义字符说明json.load时编码不对如果显示成锟斤拷这类乱码说明输出文件的编码不对。对应处理是检查open()的encoding参数统一写成utf-8。如果目标下游系统比较老只认 GBK 编码那就得在输出时把编码改成gb18030同时做好测试。这类问题最好在对接前确认别等数据传过去了再改。5.2 日期字段解析失败日期解析失败通常有两种情况。第一种是数据源里有空字符串或者null前面代码里已经给了默认值方案。第二种是数据源的日期格式不是脚本里写的%Y-%m-%d %H:%M:%S比如时间是2025/06/18或者18-06-2025strptime就会抛出异常。面对不确定的日期格式建议先统计一下导出文件里的日期格式有哪几种然后写个辅助函数逐种尝试解析。我在实际项目里就遇到过同一个月导出的数据日期格式不统一一种带横杠一种带斜杠最后就是写个循环尝试两个格式模板才解决。遇到解析失败别用try...except静默跳过一定要打印错误日志标明是哪条记录的哪个日期字段出了问题。静默跳过是数据迁移最大的坑数据悄悄没了都不知道。5.3 特殊字符把记录截断了这类问题在任务描述比较随意的团队里特别常见。有人喜欢在任务名里加感叹号、加竖线、加引号这些字符直接拼进 DSH 里会把下游解析器搞崩溃。我调试时遇到过一个典型案例任务名是优化订单查询按用户、按时间筛选里面的中文冒号被解析器当成了字段分隔符整条记录被截断成两段。后来加上了转义逻辑把值里的冒号统一替换成\:才解决。这正说明任何用户输入的字段只要进到 DSH都必须经过escape_value()处理千万不要直接f-string拼接。这个顺序不能省省一步都是坑。5.4 大文件转换卡顿与内存占用几百条记录的转换脚本跑起来毫无压力但数据量到几万条的时候一次性把所有输出 block 都存在内存里再写入文件就容易内存吃紧。我处理过的最大一次是单月 3 万多条工时记录把转换逻辑改成逐条处理、流式写入文件内存占用瞬间降下来。改造方法其实很简单把main()里先收集所有 block 再拼接改成打开输出文件循环每条记录每转完一条就写入一条。这样内存里始终只有一条记录的数据文件多大都无所谓。另外输出时可以考虑分文件。比如按月份拆分或者每个项目一个 DSH 文件这样下游系统导入失败时定位问题也更快不用在一个几万条记录的大文件里翻来找去。踩过几次坑之后最大感受是格式转换看起来是个小活但里面全是细节。字段映射表提前设计好能省大部分返工时间日期格式和特殊字符处理一定要在写脚本之前就想清楚而不是等下游系统报错再回头补最后死死守住输入输出数量校验这条底线数据不丢其余的都好商量。WorkBuddy 到 DSH 这个转换方案后续还可以扩展成定时同步任务每天凌晨自动拉取新增任务、转换、推送到下游报表系统。把这个能力做成一个小工具或者平台插件团队里其他人就不用再和格式问题纠缠了这也是我下一步打算做的事。