Temporal 时间快进：你没见过的那只“钟”

有那么一阵子，我在调试一套测试，生产上跑得溜溜的，测试环境下却炸成烟花。工作流没问题，活动都完成了，信号也收到了——可每个测试都挂了个 TimeoutError，工作流还没跟测试代码“打个招呼”就一命呜呼。

背后凶手是一只我从来没注意过的“钟”。

今天这篇文章，就来聊聊那个终于让我理解 Temporal 时间快进测试服务器的心智模型。如果你也曾被 WorkflowEnvironment.start_time_skipping() 搞晕，或者遇到过生产没问题，测试却老是超时的离谱现象，欢迎入座！

什么是 Temporal？（30秒极简介绍）

Temporal 是一个工作流编排引擎。你把业务流程写成一个“工作流”（比如一连串步骤），Temporal 保证帮你靠谱地跑完。哪怕有一步挂了，它也会自动重试，服务器崩了还能恢复进度。所有让人抓狂的东西——重试、超时、状态保存、分布式协调——它全包了。

这篇文章只需要知道一件事：你的工作流不是在普通的 Python 环境里跑的，而是“住”在 Temporal 的专属运行时里。 Temporal 负责掌控什么时候发生什么，这一点非常重要。后面一切的谜题都从这里展开。

Temporal 是时间管理员

改变我认知的关键点：Temporal 不会跳过你的代码，它只控制自己的“钟”。

我以前总觉得 Temporal 是个加速器，会让我的代码嗖嗖地快进。其实不是。Temporal 就像内核（kernel）一样，是个大管家，维护着一张“定时事件表”。

比如你的工作流里有：

await workflow.sleep(3600)  # 睡1小时

Temporal 并不会让 Python 代码飞快执行，而是悄悄在自己的时间表上记一笔：

“在当前时间 + 3600秒时叫醒工作流ABC”

又比如你启动一个30秒超时的活动：

“如果活动XYZ在当前时间 + 30秒还没回，算失败”

整体超时10分钟：

“如果工作流ABC在当前时间 + 600秒还没完，直接掐灭”

无论是 sleep、超时、活动期限还是心跳检查，对 Temporal 来说本质都是“定时事件”：到点了，干某事。区别只是干什么——恢复、失败、杀掉——机制完全一样，就是“时间戳+动作”。

这，就是理解时间快进的基础。

时间快进：无聊时就快进

Temporal 的 Python SDK 有两种测试环境：

WorkflowEnvironment.start_time_skipping() —— 下载一个超轻量的 Rust 测试服务器（二进制直接跑，无需 Docker）。这个服务器有一块“虚拟钟表”，能随时快进。
WorkflowEnvironment.start_local() —— 跑一个完整的 Temporal 服务，和生产一模一样，时钟也是实打实的。

时间快进服务器的聪明之处在于：只要它发现啥也没在发生，它就会把自己的时钟跳到下一个事件。

比如你的流程是：

await workflow.sleep(3600)   # 睡1小时
await do_some_activity()
await workflow.sleep(7200)   # 睡2小时

生产上，光这俩 sleep 就得熬3小时。时间快进模式下是这样：

调用 sleep(3600)，时间表登记：“3600秒后恢复”。
发现没别的事干，咻——时钟直接跳到3600秒后。
定时器响了，继续执行，开始活动。
活动在跑——这时服务器不能快进，得等真实的结果。
活动完了，再来个 sleep(7200)，时间表又记一笔。
没事干？再咻——时钟跳7200秒。
定时器响，流程结束。

整个流程花的真实时间，只取决于活动（比如 mock 活动可能只耗几毫秒）。那3小时的 sleep？一秒没浪费，直接“快进到片尾”。

这有个非常关键的结论：

如果你的代码里从不 sleep、不等、不设超时，时间快进模式根本不会提速。

想想看：时间快进只会跳过“无聊时间”——即 Temporal 的时钟处于空闲时。如果整个流程全是计算和逻辑，没有任何等待，时间快进就一点用没有。

当然，现实里的工作流总有各种等待、重试、sleep。关键在于：时间快进不是让代码更快，而是消灭事件之间的“等待时间”。

Handle：你的遥控器

每当你启动一个工作流，Temporal 会给你返回个“handle”。你可以把它想象成餐厅的取餐小票——下单后这张票就是你和厨房沟通的唯一渠道。

handle = await client.start_workflow(
    MyWorkflow.run,
    inputs,
    id="order-123",
    task_queue="kitchen",
)

这会让工作流在 Temporal 里独立运行。handle 就是你的遥控器，有几个常用“按钮”：

handle.result() —— “等我饭好通知我。” 你一直等着，直到结果出来。
handle.query() —— “我的饭现在咋样啦？” 问一句，立马得到当前状态。
handle.signal() —— “再加点芝士！” 给正在跑的工作流发个消息，立刻送达。
handle.cancel() —— “不吃了，取消订单。”

handle 其实就是 temporalio.client.WorkflowHandle，没啥神秘的。关键是你点哪个“按钮”，Temporal 的时间快进服务器会有不同的反应。

`result()` vs `query()` — 你掉的那个坑

这里是我理解彻底反转的地方——也是让我卡壳最久的关键。

handle.result() 就像打电话：“我等着，饭好了一定通知我！” 你在那儿死等。更关键的是，你等的方式会让时间快进服务器理解为：“用户在等结果，我得帮忙快进到流程结束。”

handle.query() 则是打个电话：“现在饭好了吗？没好啊？那挂了哈！” 一次性问答。服务器没理由快进——你没让它等啥。

这里的坑在于：result() 是事件驱动（等“完成”事件），query() 是轮询（问一下返回当前状态）。 按常理，事件驱动总是“更好”，但在时间快进模式下，轮询反而更安全，因为它不会授权 Temporal 快进时钟。

操作	Temporal 理解	是否触发快进
`handle.result()`	“等我做好叫你”	是（服务会快进到结果）
`handle.query()`	“现在状态咋样？”	否（只回答，不快进）
`handle.signal()`	“传个消息”	否（立刻送达）

中间那一列就是全部真相。result() 给了服务器快进的许可，query() 没给。

竞态条件：死于时间旅行

拼图已经齐了，下面说说这些原理怎么凑一起，制造了一个让人抓狂的 bug。

场景设定

我们的工作流有个环节需要用户反馈。每跑完一步（比如分析文档），工作流会暂停，等用户点“继续”。生产环境下，这可能要等几分钟、几小时，用户思考、编辑、喝咖啡。

代码里等待是这样的：

# backend/src/genai/temporal/workflow_executor.py, line 149
await workflow.wait_condition(lambda: waiter.signal_received)

意思就是：“等到 signal_received 变 True 再继续。” 没有超时，爱等多久等多久。生产上OK，用户点了继续，信号发到，流程继续跑。

考试监考的比喻

想象你是监考老师，考试2小时，墙上有钟。

生产环境（真钟）： 学生举手：“老师，我要去拿计算器。” 你等着，计算器送到，学生继续考试，钟上显示45分钟过去，一切正常。

时间快进（魔法钟）： 学生举手：“我要拿计算器。” 你环顾教室，没人写字，没动静，于是咻地一下把钟拨到1小时、1.5小时、2小时——“时间到，交卷！” 学生还没回来，考试挂了。

那边计算器刚进门，钟已经跳到2小时，晚了。

真正发生了什么

来看测试里的实际时间线：

真实时间 0.00s —— 测试启动工作流。Mock 活动瞬间完成（没真I/O）。

真实时间 ~0.02s —— 所有活动结束，工作流进入 wait_condition()，等反馈信号。这时 Temporal 的“时间表”里啥也没在等：没活动、没定时器，只有个等信号的工作流。

真实时间 ~0.02s —— 测试调用了 handle.result()：“等流程结束告诉我。”

时间快进服务器一听：“用户等结果？查查时间表……啥都没挂着，只剩下600秒后的整体超时。那我直接快进600秒吧！”

服务器时钟跳跃： 0s → 600s。

工作流超时，挂了，报 TimeoutError。

真实时间 ~0.03s —— handle.result() 报错返回。

这时，测试里本来有个轮询循环，计划 asyncio.sleep(0.1) 后去 poll 状态、发信号。但这会儿，工作流尸体早凉了，信号只能送给“亡灵”。

整个过程真实时间不到30毫秒，服务器一键“快进到大结局”。

解决方法

明白原理后，解决办法反而很朴素。别在等信号时调用 handle.result()。改用 handle.query() 轮询进度，根据需要发信号，只有确认流程完了再调 result()：

# backend/tests/integration/genai/test_temporal_workflow.py, lines 49-77
async def _run_workflow_with_feedback(handle):
    while True:
        await asyncio.sleep(0.1)    # 测试进程的真实 sleep

        # query() 不触发快进，时钟保持原地
        progress = await handle.query(JurorAnalysisWorkflow.get_progress)

        # 给所有等待反馈的步骤发信号
        for step_id in progress.pending_feedback_steps:
            await handle.signal(
                JurorAnalysisWorkflow.submit_step_feedback,
                StepFeedbackSignal(release_step_id=step_id),
            )

        # 确认流程真正结束后再调 result
        if progress.status == WorkflowStatus.COMPLETED:
            return await handle.result()  # 这时已经完事，result 立刻返回

原理很简单：

query() 不动时钟，工作流静止在 wait_condition 时刻，服务器不快进。
轮询循环用真实时间跑，asyncio.sleep(0.1) 是测试进程自己的等待，不受 Temporal 支配。
信号无视时钟，立刻送达。
只有确定流程完了才调 result()，这时无需再快进，result 也会瞬间返回。

只要你不给服务器快进的机会，工作流的时钟就老老实实等着。

总结：几条硬核法则

心智模型：

Temporal 是时间管理员，不是加速器。它维护一张“定时事件表”。
时间快进只“加速”空闲时，无事可跳就不跳。
没有定时器、超时、sleep，时间快进也无用武之地。

实操守则：

千万别在等信号时 await handle.result()，否则 Temporal 会直接快进到流程超时，信号都来不及送到。
用 handle.query() 轮询工作流状态，查询是被动的，不会影响时钟。
信号任何时候都能送达，不受时钟影响。
只有确认流程结束，再调 handle.result()。

选哪个测试环境：

start_time_skipping() —— 适合自闭型工作流（只有定时器、活动，没有外部交互）。或者依赖信号的流程，但用轮询+信号模式也OK。
start_local() —— 需要流程中途信号/查询的，建议用这个，所有等待都是真实时间，但会慢一些。

我们最终还是选了 start_time_skipping()，因为轮询+信号模式能完美兼容，还能免费享受所有 “sleep/重试/抖动” 的快进。

声明：本文由人类创作，部分内容参考 AI 建议，最终拍板归作者。