WorkBuddy JSON转DSH：Python自动化实现任务数据周报汇总

每年到周五下午，我和团队就会被同一件事折磨：WorkBuddy里的任务明明记得清清楚楚，但要整理出一份能汇报的交付状态数据，却总得在导出、复制、求和、改格式之间反复折腾。后来我实在受不了这种“手工搬运数据”的日子，就写了一个小工具workbuddy-to-dsh，每周五定时把WorkBuddy的JSON备份转成统一结构的交付状态报告，跑完直接可以接报表、接周报、推群消息。这篇教程就是记录这个工具从想法、设计到踩坑的全过程，凡是还在用WorkBuddy管项目、又需要向不同人汇报数据的，或者单纯想知道任务数据怎么从“记录形态”变成“统计形态”的，都可以照着做一遍。

1. 为什么我会写workbuddy-to-dsh：一个让人头疼的数据孤岛问题

1.1 每周五的“数据搬运工”当够了

我们团队的工作流原本是这个样子：每天早会上，大家打开WorkBuddy过一遍任务列表，把新需求拆成子任务，排优先级，标记预计工时。开发人员会在完成任务后补一条时间记录，点一下“结束计时”就算闭环。整个过程用起来确实顺手，任务的状态、归属、工时、标签都被记录得很有条理。

但是到了周五下午要出交付周报的时候，麻烦就来了。产品要看功能模块分布，测试要看Bug占比和回归情况，管理层只想知道“这个迭代到底能不能按时发”。WorkBuddy自带的图表页不是不能看，可它不支持把两个项目的进度并排对比，也不支持按自定义字段做分组统计，更不允许我导出成一个扁平的、可供Excel或BI直接消费的数据表。我唯一能做的，就是打开导出功能，拿到一堆JSON，再手动转成Excel里的透视表。

这个过程听起来没什么，真正做过的人都知道有多崩溃。首先，WorkBuddy导出的JSON是嵌套结构，一个项目下一堆任务，每个任务下又挂若干条时间记录，时间记录里还有开始时间和结束时间。如果你只是单次查看，这个结构很合理；可你要统计“本周投入了多少工时”，就得遍历所有时间记录做求和，稍微漏一层嵌套，数字就对不上。其次，手动整理必然伴随版本错乱。我今天导出一份，明天同事又导出一份，两边的数据时间点不一样，最后汇总出来的数字连我们自己都不敢信。

1.2 记录型数据和统计型数据之间，缺了一层转换

我后来想明白一件事：WorkBuddy本质上是一个“记录型”工具，它擅长把每天发生的事情逐条记下来，但它不擅长直接回答“整体怎么样了”这个问题。而周报、汇报、看板、BI分析需要的恰恰是“统计型”数据：项目分布、状态汇总、工时累计、按期交付比例。这中间缺的，就是一个把记录型JSON转换成统计型JSON的自动化环节。

这个环节其实不复杂，核心无非三步：分组、映射、聚合。按项目把任务分组，把WorkBuddy的字段一一对应成我想要的统一字段，再把工时、任务数按状态累加起来。听起来很简单，但如果没有一个工具固定下来，每周做一遍还是烦，而且每次都会因为手滑漏掉几个任务。于是我用Python写了一个转换脚本，起名叫workbuddy-to-dsh，意思就是把WorkBuddy的数据转换成DSH格式。这个脚本最开始只有几十行，后来随着团队需求增加，陆续加上了配置项、自定义字段和定时任务的支持，才慢慢变成现在这个可以被大家直接使用的样子。

1.3 DSH到底是什么，为什么它比临时报表更靠谱

很多同事第一次看到“DSH”都会问，这是不是哪家公司的私有协议。其实这里DSH是我的缩写，全称叫Delivery Status Hub，也就是“交付状态中心”。它不是什么神秘格式，而是一套我定义的JSON结构，专门用来统一表达“项目当前的交付情况”。你可以把它理解成一个标准化的快递面单：包裹里有多少件货、几件已经妥投、几件还在路上、一共耗时多少，一眼就能看完，想深入查每一件货的明细也能点到。

DSH结构最大的价值在于稳定。以前我每周可能换一种整理方式，今天用Excel透视表，明天用在线文档，统计口径跟着我的心情变。现在DSH把这个口径固定下来了：项目总数、任务总数、完成数、进行中数、阻塞数、累计工时，每次输出字段都一样。下游不管是接一个简单的HTML看板，还是接Power BI，甚至只是发一段文本周报到群里，都可以无脑复用这套结构。数据结构化带来的好处就是，你不必每次重新解释字段含义，工具和人都能快速对接。

2. 转换前的准备：导出WorkBuddy数据与DSH目标结构

2.1 环境依赖：只需要一个Python环境

工具本身非常轻量，只依赖Python标准库里的json和datetime，不需要装数据库，也不需要额外起服务。我平时用的是Python 3.10，如果你的机器上已经装好了Python 3.9以上版本，基本开箱即用。第一次使用，建议先建一个虚拟环境，避免依赖弄乱系统的全局环境：

python3 -m venv wb2dsh-env source wb2dsh-env/bin/activate pip install workbuddy-to-dsh

安装完成后，用workbuddy-to-dsh --version确认版本号能正常打印。这里有个很容易被忽略的小细节：如果你用的是Windows，虚拟环境激活命令是wb2dsh-env\Scripts\activate，不是source。团队里有同事在这个地方卡过几分钟，所以我顺手记一下。

工具原理上并不复杂，你可以把它理解成一个管道：入口是WorkBuddy导出的JSON，出口是DSH格式的JSON。管道中间跑着几个纯函数，一个负责加载数据，一个负责字段映射，一个负责聚合统计。所以就算你不用现成的包，自己按下面的代码写一份也没有问题。

2.2 从WorkBuddy导出原始数据

要从WorkBuddy拿到原始数据，通常在项目空间的“设置”里找到“数据导出”，选择“完整备份（JSON）”，然后点导出。这里特别强调一句：一定要选完整备份，不要选“当前视图导出”。视图导出只会把当前筛选条件下的数据带出来，一旦你上周筛选了一个标签、这周忘了改，导出的数据就少了一大截，转换出来自然也是错的。完整备份会带上所有项目和任务，哪怕有些项目已经归档了，数据还在，后面想回溯也方便。

导出的文件一般是workbuddy_export_YYYY-MM-DD.json这样的命名。拿到文件后不要急着做任何操作，先复制一份放到work/目录下当作原始数据留档，转换用的文件再复制一份放到input/目录，这样万一转出来有问题，还能回头核对原始数据，不会因为改坏文件而彻底丢了依据。

2.3 DSH目标结构：先想好再动手

很多初学者拿到WorkBuddy的JSON后会直接开始写代码，把所有字段一股脑塞进输出文件。我建议你反过来，先花半小时把目标结构定下来。因为字段映射一旦写进代码，后期要改就牵一发动全身；而如果先想清楚“到底要输出什么”，后面每一步都顺。

我常用的DSH结构是这样组织的：

{ "meta": { "schema_version": "1.0", "generated_at": "2025-06-20T14:30:00+08:00", "source": "workbuddy_export_2025-06-20.json" }, "projects": [ { "id": "prj-1001", "name": "官网改版", "total_task_count": 36, "completed_task_count": 21, "active_task_count": 12, "blocked_task_count": 3, "total_minutes": 8640, "tasks": [ { "id": "task-3012", "title": "首页首屏性能优化", "status": "done", "priority": "high", "tag": "performance", "duration_minutes": 320, "assignee": "zhangwei" } ] } ] }

这里最顶层是meta，记录生成时间、来源文件、schema版本。meta这个东西很多人会忽略，但它对排查问题特别重要。哪天你打开一个DSH文件，发现数据像是旧版的，先看meta里的generated_at就知道是哪次转换生成的，不用瞎猜。projects数组则是核心，每个项目先放聚合字段，再放任务明细。聚合字段用于快速汇报，tasks数组用于深入分析，两者结合，既能看全貌又能查细节。

3. 动手转换：核心字段映射与完整配置步骤

3.1 字段映射表：WorkBuddy怎么变成DSH

转换这件事，本质是回答“两个模型之间怎么翻译”。WorkBuddy里的一个任务，到了DSH里应该是什么？我列了一张映射表，写清楚原始字段和目标字段的对应关系，这也是整个转换逻辑的起点：

这张表里，真正需要动脑子的只有两处：状态枚举和时间求合。状态枚举很关键，因为WorkBuddy的语言和DSH的口径未必一致。比如WorkBuddy里有“paused”这个状态，DSH的汇报口径里可能没有暂停这一类，那你就要决定它算“进行中”还是算“阻塞”。没有绝对正确的答案，完全取决于团队怎么看这项任务：暂停两周还在等外部依赖，我会归到blocked；只是短暂中断、下周马上继续，我会归到active。这个决定最好由团队负责人做，而不是写代码的人拍脑袋。

时间合也没有看起来那么简单。WorkBuddy的time_entries里，每条记录都有started_at和ended_at，但并不是每条都有结束时间，有些人开了计时器忘记关。此外，WorkBuddy自身显示时长时可能已经做过单位换算，但导出JSON里的原始单位在不同版本之间并不一致。为了避免被脏数据坑到，我在转换时统一用“结束时间减开始时间”得出分钟数，而不是信任字段里的现成数字。

3.2 编写一个最简单的转换脚本

如果你不想用现成工具，只想知道底层逻辑，下面这段Python脚本是我的核心逻辑精简版，去掉错误处理也能跑通：

import json from collections import defaultdict from datetime import datetime, timezone, timedelta

def load_export(path): with open(path, "r", encoding="utf-8") as f: return json.load(f)

def norm_status(raw): mapping = { "todo": "todo", "待开始": "todo", "in_progress": "active", "进行中": "active", "done": "done", "已完成": "done", "paused": "blocked", "已暂停": "blocked" } if isinstance(raw, str): return mapping.get(raw.lower(), "unknown") return "unknown"

def duration_of(entries): total = 0.0 for entry in entries or []: start = entry.get("started_at") end = entry.get("ended_at") if start and end: start_dt = datetime.fromisoformat(start.replace("Z", "+00:00")) end_dt = datetime.fromisoformat(end.replace("Z", "+00:00")) total += (end_dt - start_dt).total_seconds() / 60 elif start and not end: # 没有结束时间默认不算，或者你希望用什么策略都可以在这里改 continue return total

def convert(export): projects = defaultdict(lambda: { "name": "", "total_task_count": 0, "completed_task_count": 0, "active_task_count": 0, "blocked_task_count": 0, "total_minutes": 0, "tasks": [] }) for task in export.get("tasks", []): pid = task.get("project_id", "unknown") proj = projects[pid] if not proj["name"]: proj["name"] = task.get("project_name", pid) duration = duration_of(task.get("time_entries")) status = norm_status(task.get("status")) proj["tasks"].append({ "id": task.get("id"), "title": task.get("name", ""), "status": status, "priority": (task.get("priority") or "medium").lower(), "tag": (task.get("tags") or ["general"])[0], "duration_minutes": round(duration, 1), "assignee": task.get("assignee", ""), "created_at": task.get("created_at", "") }) proj["total_task_count"] += 1 proj["total_minutes"] += round(duration, 1) if status == "done": proj["completed_task_count"] += 1 elif status == "active": proj["active_task_count"] += 1 elif status == "blocked": proj["blocked_task_count"] += 1 return [ {"id": pid, "name": p["name"], "total_task_count": p["total_task_count"], "completed_task_count": p["completed_task_count"], "active_task_count": p["active_task_count"], "blocked_task_count": p["blocked_task_count"], "total_minutes": p["total_minutes"], "tasks": p["tasks"]} for pid, p in projects.items() ]

ifname== "main": export = load_export("workbuddy_export.json") result = convert(export) print(json.dumps(result, ensure_ascii=False, indent=2))

注意这段代码里我对“没有结束时间”的条目做了默认忽略处理。这个决定要慎重，因为一旦团队里有人习惯不关计时器，累计工时会偏小，导致你汇报出来的投入比实际少很多。更稳妥的做法是额外输出一个warnings数组，把“哪些任务存在未完成时间记录”列出来，人工核对。因为自动化流程里最怕的不是报错，而是输出看起来正常、数据实际是错的。

3.3 把映射规则抽出来，用配置文件代替改代码

总改代码不是长久之计。团队大了以后，总有人会提出不同的统计口径。产品这边说“等待外部才算阻塞”，测试那边说“Bug回归不算新任务”，如果都靠我改代码，光是联调就累死。于是我把映射规则和聚合口径抽到了配置文件里。

config.yaml示例如下：

status_mapping: todo: todo in_progress: active done: done paused: blocked

tag_preference: first group_by: project_id minute_precision: 1

extras: iteration: task.custom_fields.iteration source: task.custom_fields.source

有了配置文件以后，谁想调整分类规则，只要改yaml里的一行，重新跑一遍命令就能生效。我自己经历过一次真实调整：团队决定把“阻塞”细分成“等待外部”和“内部阻塞”两类。当时我以为要写半天代码，结果就是在status_mapping里加两行映射，再把DSH聚合字段里多算一个计数，前后不到十分钟。配置化的另一个好处是，团队成员都能看懂统计口径长什么样，不会出现“这个计数是怎么算的”这种一问三不知的情况。

3.4 跑一下：输入输出和验证

工具准备好之后，完整的命令行是这样的：

workbuddy-to-dsh convert
--input ./workbuddy_export_2025-06-20.json
--output ./dsh_2025-06-20.json
--config ./config.yaml

看到命令行返回success后，不要急着收工，我每次都会做三件事验证：第一，检查项目数量，看是否和WorkBuddy里的项目数一致；第二，抽查几个任务的时间求和，取一个已知耗时的任务，手动算一遍，对比生成结果；第三，用jq做一次JSON合法性检查，顺带看看顶层meta字段生成时间是否正确。命令如下：

jq '.meta, .projects[0].name' dsh_2025-06-20.json

如果发现项目数量对不上，优先检查WorkBuddy导出的tasks数组里有没有“孤儿任务”——也就是project_id指向一个并不存在的项目。转换器会把孤儿任务归入一个名为unknown的项目里，这样你一眼就能发现问题，再回WorkBuddy检查是删了项目、没删任务，还是导出时漏了什么。

4. 跑通后的几个坑：日期、时区、耗时统计与附件处理

工具能跑只是第一步，真正把它当成每周都跑的稳定服务，你很快会遇到一批边界问题。这些坑不是代码逻辑的问题，而是数据本身的特殊情况所致，但处理不好会让整个统计结果失真。

4.1 日期字段的时区陷阱，比你想的更早发作

WorkBuddy导出的created_at通常带时区信息，比如2025-06-20T08:30:00+08:00。如果转换服务和WorkBuddy在同一时区，看起来没问题；但很多团队的自动任务跑在服务器上，而服务器常常配置成UTC时间。你周五下午五点跑转换，服务器上显示的是上午九点，如果代码里直接取datetime.now()，生成时间会比真实时间慢八个小时。

更隐蔽的问题是，不同系统对ISO字符串末尾的“Z”支持不一样。有的运行环境不认“Z”这个时区标记，直接抛异常。我统一用replace("Z", "+00:00")先把字符串标准化，再转成datetime对象，最后再依据目标时区输出：

from datetime import datetime, timezone, timedelta

def to_target_timezone(raw, tz_offset_hours=8): dt = datetime.fromisoformat(raw.replace("Z", "+00:00")) target = timezone(timedelta(hours=tz_offset_hours)) return dt.astimezone(target).isoformat()

时区不严谨，通常不是当天报错，而是到做周维度聚合那天突然发现所有任务的时间都偏移了几小时，查起来特别费劲。所以我在代码里强制统一：所有时间字段在进入DSH之前，一律转成+08:00的ISO字符串。

4.2 时间记录里总有“还没结束”的条目

只要团队里有人习惯开着计时器过夜，你就一定会遇到只有started_at、没有ended_at的时间记录。如果代码忽略了这种记录，累计工时就会偏小；如果默认用当前时间当作结束时间，可能又把半天没动的任务算成十几个工时。两条路都不完美。

我的处理方式是：遇到没有ended_at的条目，在输出文件的meta.warnings里记录一条，例如“task-2041存在未结束的时间记录，已忽略或估算”。同时支持配置项allow_open_entries，默认为false，也就是忽略这些条目；如果你希望乐观估算，可以改成true，让它用“当前转换时间减去开始时间”估算时长，但必须同时打开warning提示，方便人工复核。这个开关要在配置里写得清楚，否则过两个月你自己都会忘。

4.3 附件链接需要做前缀拼接

WorkBuddy导出里的附件字段通常不是完整URL，而是相对路径，比如/files/abc.pdf。下游要直接打开这个附件，就得根据WorkBuddy的实例地址拼接。我在转换命令里加了一个--base-url参数：

workbuddy-to-dsh convert --input ./export.json --output ./out.json --base-url https://workbuddy.example.com

转换时，工具会把附件字段开头的/files/拼成https://workbuddy.example.com/files/。这个看起来很小的细节，能让DSH下游的看板页面直接点击附件，不需要再手动导航到WorkBuddy里找文件。如果你团队用的是私有云盘存储，还可以在config里加一条attachment_prefix规则，例如把/files/整体替换成https://cloud.example.com/shared/。

4.4 没有任务的项目，会从报表里“消失”

一个项目刚立项、还没开始拆任务时，它的total_task_count是0。很多报表工具在画饼状图或者做筛选时，默认把计数为0的数据行过滤掉，于是这个项目就从看板里神秘消失了。第一次遇到这个问题时，我盯着Excel里的图表看了半天，还以为是代码丢了一个项目。

解决办法是，在DSH输出里为每个项目增加一个status_summary字段，当total_task_count为0时，标记为empty。下游收到empty就直接显示“计划中”，而不是整行隐藏。这虽然只是一个很小的设计决策，但直接影响看板类工具的呈现完整度，也算是对“数据可视化”这条链路的尊重。

4.5 一次时差问题的完整排查链路

为了让你对这类问题怎么排查有一个直观印象，我讲一次真实的踩坑过程。某个周一早上，同事跟我说DSH数据统计里有一项任务的创建时间不对，比WorkBuddy里的时间正好晚了八小时。我第一反应是看生成日志，结果发现转换时间没问题，于是开始怀疑是不是读取的时候出了问题。

我先取出一条异常任务的原始JSON，确认它的created_at是2025-06-20T08:30:00+08:00。然后我在代码里逐行打印加载后的datetime对象，发现转换后变成2025-06-20T00:30:00+08:00。这显然不是加的八小时，而是减了八小时。我继续追，发现问题出在fromisoformat读取时，系统把末尾的+08:00解析成了UTC偏移，然后把datetime对象存成UTC时间，并没有改变显示上的绝对时间。真正让我意外的是，后续输出时我用astimezone(timezone.utc)做了统一，而这个统一操作把原本的+08:00时间误当作UTC再次转换，导致时间差被叠加了一次。

排查的关键是分两层看：读取阶段只负责把字符串变成时间对象，输出阶段才做时区转换。两个阶段如果都做转换，就会重复偏移。最后我把读取和输出两个逻辑拆开，读取时只保留原始时间字符串，输出时统一转目标时区，问题彻底解决。这里学到的一条经验是：如果自动化程序输出的时间不对，先不要改计算逻辑，把“输入时区转换”和“输出时区转换”分开看，绝大多数偏移问题都出在这两个环节叠加。

5. 进阶玩法：定时自动化与自定义字段扩展

基础转换跑顺之后，你就已经从“手搓汇报”升级成了“脚本生成汇报”。再往后，要解决的是怎么让这个流程自动化到不需要你记得去跑，以及怎么让DSH适配团队自己的业务字段。

5.1 用crontab把转换变成定时任务

以Linux服务器为例，如果你希望每周五下午五点半生成当周交付状态，只需要在crontab里写一行：

30 17 * * 5 cd /opt/workbuddy-to-dsh && python -m wb2dsh.cli convert --input ./data/latest_export.json --output ./output/dsh_$(date +%Y-%m-%d).json --config ./config.yaml >> ./logs/convert.log 2>&1

这里把输入文件固定成latest_export.json，就需要有一个步骤先把WorkBuddy最新导出下载到本地。如果WorkBuddy支持开放API，你可以在转换命令前再加一个curl或python请求，把导出文件下载下来；如果不支持API，就得靠团队成员周五手动导出一次。我的经验是，导出这个动作可以退化，但转换和汇总绝不能退化，因为人一旦忙起来就会忘记，而定时任务只要配置好就不会忘。

Windows环境则可以靠“任务计划程序”实现类似效果。我团队里有人用Windows笔记本做主力机，他配置的触发器是每周五17:30，操作为运行bat脚本，bat内容就是上面那一串命令。注意cron里的百分号需要转义为%；如果你照抄学习资料时发现日期文件名变成了奇怪的内容，基本都是这个转义问题。

5.2 自定义字段透传与常见误区

WorkBuddy允许为任务添加自定义字段，比如“迭代版本”“需求来源”“业务线”。默认转换脚本只映射常见字段，自定义字段必须通过extras配置透传。前面config.yaml里已经写了一行示例，实际效果是DSH任务对象里自动多出iteration和source两个字段。这个功能很适合按业务维度做聚合，比如统计不同迭代版本的完成率，或者对比不同需求来源的任务耗时。

透传时有一个容易踩的坑：尽量保持自定义字段的原始类型，不要顺手转成字符串。举个例子，WorkBuddy里“预估工时”字段如果是数字类型，透传后也应该是数字，这样下游才能做数值求和；如果被统一转成字符串，后续画图时还得重新解析。我在工具里默认透传是保留类型的，除非你在配置里明确指定了cast_type。这也是一个“默认不做、显式才做”的原则，目的就是减少心智负担。

5.3 接上团队通知机器人，周报进入全自动

DSH既然是结构化数据，后面接什么都方便。我现在的流程是：转换完成后，自动读一遍DSH里的projects聚合字段，拼成一段简短的文本，推送到企业微信群的机器人接口。内容通常长这样：

本周交付摘要

• 项目数：6
• 完成任务：42
• 进行中：18
• 阻塞：3
• 投入工时：128.5h

实现上就是遍历projects数组求和，然后构造一个POST请求。如果你用的是钉钉或者飞书，原理完全一样，只是消息格式有差异。这一步接完后，周五下午的周报流程彻底闭环：数据自动导出、自动转换、自动预警、自动推送，我只需要在群里看一眼结果对不对。省下来的时间，我就会像现在这样写写教程，或者干脆早点下班。

说了这么多，我自己最大的体会是，写好一个转换工具，难点从来不是写代码，而是想清楚“谁会用这个数据、按什么口径用”。workbuddy-to-dsh真正解决的不是转换动作本身，而是把团队对交付状态的认知统一到了一个固定结构里。如果你也正在被各种记录型任务软件绑住手脚，每天花大量时间做手工汇报，不妨花一下午把这个链路搭起来。一开始可能只是省下每周两小时，到后面你会发现，团队讨论时终于有了同一份数据作为依据，很多争论都自然消失了。