WorkBuddy数据转DSH格式：字段映射与自动化转换脚本实战

最近在给一个团队做数据整理，遇到一个挺典型的场景：团队一直用 WorkBuddy 记录任务和工时，积累了好几百条工作记录，但下游的报表系统只接受 DSH 格式的导入文件。一开始大家想的是从 WorkBuddy 导出 Excel 再手工改，结果试了两天就放弃了——字段对不上、日期格式混乱、中文经常乱码。后来我写了个小转换工具，把 WorkBuddy 导出的 JSON 一键转成 DSH，整个过程才算稳定下来。

这篇就把整个转换思路和实操过程完整拆一遍，包括字段映射怎么设计、日期格式怎么处理、批量转换怎么写脚本、踩过哪些坑。如果你也在用 WorkBuddy 做任务管理，或者手头需要把某类业务数据转成 DSH 格式交给下游系统，这篇文章可以直接照着抄。

1. 为什么要把 WorkBuddy 数据转成 DSH 格式

1.1 WorkBuddy 数据不直接可用的三个痛点

先说结论：WorkBuddy 本身是个挺好用的任务管理工具，团队用它记任务、派工、填工时，数据都在里面。问题在于它导出的数据格式和下游系统之间，天然存在三堵墙。

第一堵墙是字段不统一。WorkBuddy 里叫"负责人"的字段，到报表系统里可能叫"owner"；WorkBuddy 里叫"截止时间"的字段，报表系统里叫"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:dev@example.com @deadline:20250618T143000 @tags:测试|用户模块 @estimated_hours:8.50 --- #DSH v1.0 @task_id:task-1002 @task_name:修复登录接口超时 @status:done @owner:ops@example.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": "dev@example.com", "due_time": "2025-06-18 14:30:00", "tags": ["测试", "用户模块"], "estimate_hours": 8.5 }, { "task_id": "task-1002", "task_name": "修复登录接口超时", "status": "已完成", "assignee": "李四", "assignee_email": "ops@example.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 的目标字段，中间写转换规则，然后再写代码。

这里给出我实际用过的映射表：

注意两个细节。第一个是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(f"@task_id:{escape_value(record['task_id'])}") lines.append(f"@task_name:{escape_value(record['task_name'])}") lines.append(f"@status:{map_status(record['status'])}") lines.append(f"@owner:{escape_value(record['assignee_email'].lower())}") lines.append(f"@deadline:{map_deadline(record.get('due_time'))}") tags = record.get("tags") or [] lines.append(f"@tags:{escape_value('|'.join(tags))}") lines.append(f"@estimated_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", encoding="utf-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", encoding="utf-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", encoding="utf-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-2025，strptime就会抛出异常。

面对不确定的日期格式，建议先统计一下导出文件里的日期格式有哪几种，然后写个辅助函数逐种尝试解析。我在实际项目里就遇到过同一个月导出的数据日期格式不统一，一种带横杠，一种带斜杠，最后就是写个循环尝试两个格式模板才解决。

遇到解析失败别用try...except静默跳过，一定要打印错误日志，标明是哪条记录的哪个日期字段出了问题。静默跳过是数据迁移最大的坑，数据悄悄没了都不知道。

5.3 特殊字符把记录截断了

这类问题在任务描述比较随意的团队里特别常见。有人喜欢在任务名里加感叹号、加竖线、加引号，这些字符直接拼进 DSH 里，会把下游解析器搞崩溃。

我调试时遇到过一个典型案例：任务名是"优化订单查询：按用户、按时间筛选"，里面的中文冒号被解析器当成了字段分隔符，整条记录被截断成两段。后来加上了转义逻辑，把值里的冒号统一替换成\:才解决。

这正说明，任何用户输入的字段只要进到 DSH，都必须经过escape_value()处理，千万不要直接f-string拼接。这个顺序不能省，省一步都是坑。

5.4 大文件转换卡顿与内存占用

几百条记录的转换脚本跑起来毫无压力，但数据量到几万条的时候，一次性把所有输出 block 都存在内存里再写入文件，就容易内存吃紧。我处理过的最大一次是单月 3 万多条工时记录，把转换逻辑改成逐条处理、流式写入文件，内存占用瞬间降下来。

改造方法其实很简单：把main()里"先收集所有 block 再拼接"改成"打开输出文件，循环每条记录，每转完一条就写入一条"。这样内存里始终只有一条记录的数据，文件多大都无所谓。

另外输出时可以考虑分文件。比如按月份拆分，或者每个项目一个 DSH 文件，这样下游系统导入失败时定位问题也更快，不用在一个几万条记录的大文件里翻来找去。

踩过几次坑之后最大感受是：格式转换看起来是个小活，但里面全是细节。字段映射表提前设计好，能省大部分返工时间；日期格式和特殊字符处理，一定要在写脚本之前就想清楚，而不是等下游系统报错再回头补；最后死死守住"输入输出数量校验"这条底线，数据不丢，其余的都好商量。

WorkBuddy 到 DSH 这个转换方案，后续还可以扩展成定时同步任务，每天凌晨自动拉取新增任务、转换、推送到下游报表系统。把这个能力做成一个小工具或者平台插件，团队里其他人就不用再和格式问题纠缠了，这也是我下一步打算做的事。