很多AI Agent的Demo演示看起来赏心悦目：用户只需点击一个按钮，后端调用模型，页面即刻展示结果。整个流程丝滑顺畅，一气呵成，非常适合在演示场景中展示。

然而，一旦将Agent集成到真实的业务系统中，问题就会变得异常具体且棘手：模型运行了90秒，页面是应该继续等待还是直接超时？用户希望取消任务，是直接终止进程，还是等待一个安全的执行点优雅地停止？生成提案失败后，点击“重试”是否会导致重复执行？服务重启后，那些状态显示为“运行中”的任务该如何妥善处理？任务可能从质检页面、工作台、提案页面等多个入口发起，最终又在哪里统一查看和管控？

这些问题，听起来或许不如Prompt、Function Calling、模型路由等概念那么“高大上”，但它们恰恰是决定一个Agent系统能否真正“落地应用”的关键所在。当完整地走完一轮工程化实践后，我最大的感受是：**将状态机转化为用户可感知、可操作的产品体验，其难度和挑战丝毫不亚于模型本身的设计。**

此前，我们探讨了AgentTask和AgentStep的后端状态机设计，包括任务如何落库、步骤如何记录、worker如何声明任务、lease如何续租。这次，我们将在此基础上更进一步，聚焦于如何将这些状态机转化为用户能够理解并操作的产品体验。以当前正在构建的AI小说创作系统为例，我们将围绕以下五个核心问题展开：

如果你正在从事Agent工程化工作，而不仅仅是构建一个简单的聊天框，那么这些问题基本上是无法回避的。

01. 先给结论

关于Agent长任务体验，我最终沉淀下来的设计原则可以概括为五条：

对应到系统中，就是几条关键的链路：

如果说之前探讨的是“Agent如何运行”，那么这次要讨论的就是：**这些状态如何转化为用户看得见、摸得着的产品体验。**

02. 为什么这不是UI细节

许多AI功能最初是这样实现的：一个“生成”按钮，点击后显示“生成中”，完成后显示“生成成功”或“生成失败”。对于短任务来说，这没有问题，但Agent执行的是长任务。

尤其是在小说创作场景中，一个Agent任务可能包含多个步骤：读取作品上下文、检查章节计划、推荐写作技能、生成草稿、进行连续性审核、创建提案、等待用户应用定稿、提取记忆……每一步都可能出错，都需要被管理。

用户等待的并非一次接口响应，而是一条包含多个环节的执行链路。如果页面仅显示“AI正在生成”，用户很快就会失去控制感。他不知道：到底是在读取上下文，还是在调用模型？是卡住了，还是正在运行？取消操作会不会留下半成品？失败后点击“继续”会不会导致重复生成？刷新页面后，还能不能看到任务状态？

因此，长任务体验绝不能仅仅被视为UI层面的细节问题。它是Agent工程化中不可或缺的一部分，是连接后端状态机与用户预期的桥梁。

03. 轮询不是无脑setInterval

任务状态落库后，前端最直接的方法就是轮询。但轮询绝不能无脑进行。如果页面不可见时仍在轮询、任务已结束时仍在轮询、每个组件都自行发起轮询、任务状态变化后不刷新关联数据……最终只会导致无意义的请求和状态不同步的混乱局面。

在我们的工作台里，有一个专门的useAgentTasks hook来管理任务列表、轮询、取消和重试。它首先定义了活跃任务的范围：pending（任务已创建，等待worker声明）和running（任务正在执行）。然后，轮询逻辑会根据页面可见性来决定是否运行。

真正的查询逻辑是这样的：

首先，只有在存在活跃任务时才进行轮询，任务结束后立即停止。其次，页面不可见时也停止轮询，避免浪费资源。最后，当任务状态发生变化时，要能触发刷新聚合数据。因为一个Agent任务完成后，可能会影响提案列表、章节状态、质检结果、记忆提取状态等多个相关数据源。

所以，这个hook里还记录了一个任务状态快照，通过对比前后两次快照，来判断是否需要触发相关数据的刷新。这段逻辑解决的不仅仅是“显示任务列表”，而是**Agent任务状态变化后，工作台其他面板是否需要一起刷新**。这才是长任务体验中经常被忽略，但又至关重要的地方。

04. 任务面板：把状态翻译成动作

用户不能只看状态，他更需要操作任务。例如：运行中时可以取消，失败后需要重试，中断后可以继续执行，待审核时应该进入审核流程。

工作台里的章节任务面板正是这样设计的：它将每个任务状态映射为清晰的动作。关键不是按钮的样式，而是状态到操作的映射关系：

这样一来，用户看到的就不再是一堆冰冷的技术状态（如pending、running），而是一组可理解、可操作的动作（如“取消”、“继续执行”）。这就是把状态机产品化的核心。

05. 取消：不是前端隐藏，而是后端命令

取消按钮绝不能只是前端把任务从列表里移除。它必须落到实处，落到后端命令。

背后的逻辑体现了一个重要区别：对于未运行的任务，直接将其状态更新为“cancelled”；而对于运行中的任务，则写入一个“cancelled_requested_at”信号。这意味着，取消不是强杀，而是一个安全停止协议。Worker会在步骤执行的边界检查这个信号，在到达一个安全点时优雅地停止任务。

这才是用户点击“取消”按钮背后真正的工程含义：**一个优雅的、可追溯的、安全的停止命令，而不是一个简单粗暴的隐藏动作。**

06. 重试：按钮背后要有幂等协议

重试按钮也容易做错。很多系统简单地把“重试”理解为“重新请求一次”，这在AI Agent场景下非常危险。因为一个重试请求可能真的在后端创建了新任务，只是前端因为网络抖动没拿到响应。如果用户再点一次，就会创建另一条新任务，导致重复执行。

所以，前端在发起重试时，必须生成并复用稳定的操作键。它的策略是：对于同一次失败任务的多次重试请求，复用同一个键；只有当重试成功后，才删除这个键，下一轮新重试时再生成新的。这样，即使前端因网络问题重复发送请求，后端也能通过幂等性保证任务只被创建一次。

这就是为什么我一直强调：**重试不是简单的“再试一次”，而是一个必须具备幂等协议的操作。**

07. 提案重试：为什么必须带修订版本

普通任务重试只需要操作键，但提案任务不一样。因为提案是基于某个章节的特定版本生成的。如果用户在提案失败后又编辑了章节内容，那么重试就不能再基于旧版本进行。

因此，在“write_chapter_proposal”任务的重试逻辑中，前端必须读取当前章节的修订版本（版本号），并将其作为参数传给后端。后端在接收到请求后，会进行“CAS”操作，即比较当前章节版本与请求中的“expected_revision”是否一致。只有一致时，才会执行重试。

这里的本质是**Compare-And-Set（CAS）**。不是所有失败的任务都能无脑重试。如果任务和章节内容有关，必须确认当前版本仍然匹配。这也是长任务体验与业务一致性紧密结合的地方。

08. 中断恢复：别留下永远运行中的任务

服务重启、worker崩溃、模型调用超时，都可能导致任务卡在“running”状态。如果系统没有恢复策略，用户就会看到一个永远“运行中”的任务，这对产品体验来说几乎是灾难。

我们的统一worker在启动时会执行恢复逻辑。它并不是简单地将所有“running”任务标记为“failed”，而是做了更精细的处理：

为什么记忆提取任务可以回到待处理状态？因为它基于已定稿的章节版本提取记忆，输入来源是不可变的，重试风险较低。而提案生成则不同，它涉及模型生成内容，用户需要知道这次生成已经中断，不能假装还在继续。这就是“中断恢复”不是一句口号，而是每类任务都要有不同策略的具体体现。

09. 自动退避：哪些失败可以系统自己恢复

不是所有失败都应该让用户点击按钮。比如记忆提取这种任务，如果来源版本有效，只是提取服务短暂失败，可以自动延迟重试。我们的统一worker里有一段记忆任务退避重试的逻辑：它会记录失败次数，并按照5秒、15秒、45秒的间隔递增延迟，自动创建新的重试任务。

这里有一个明确的边界：对于“memory_source_invalid”这种不可恢复的错误，系统会停止自动重试，等待人工介入；而对于临时性的失败，系统会按退避策略自动恢复；如果超过最大重试次数，则保留失败状态。这就是自动恢复和人工干预的分界，系统能判断是临时失败就自动恢复，发现来源不可信就停止，寻求人工介入。

10. 任务中心：把散落的Agent任务收回来

工作台内的任务面板解决的是“当前章节”的任务，但Agent系统一旦复杂起来，就会产生很多任务：单章写作闭环、自动写作流水线、批量规则修复、质量闭环、自主驾驶提案生成、记忆提取……这些任务不能散落在各个页面里。所以，前端需要一个独立的“Agent任务中心”页面。

这个任务中心不仅支持按状态（全部、进行中、需处理）筛选，还支持一个非常实用的功能：**深度链接。**例如，质检页创建了修复任务，可以直接跳转到任务中心并自动选中那个任务。这对复杂Agent系统至关重要，因为用户不一定从任务中心发起任务，他可能来自质检问题列表、章节工作台、自动写作入口、提案审核面板等各个地方。任务中心要能接住这些来源，为用户提供统一的查看和管理入口。

11. 任务详情：进度要来自真实步骤

任务中心不只是列表，它还要展示选中任务的详细步骤。当用户选中一个任务时，会加载该任务的步骤列表。如果选中的任务仍在活跃状态，系统会持续刷新任务和步骤信息。进度条的计算也不是前端随便估算的，而是根据真实的AgentStep记录来计算的，用户看到的是系统真实状态，而不是安慰性的“预计进度”。

12. 错误协议：失败后要告诉前端下一步

长任务体验里还有一个容易忽略的问题：错误返回。如果所有错误都只是返回一个简单的“failed”，前端完全不知道下一步该做什么——是让用户刷新、重试、跳转，还是停止操作？

因此，我们的系统里有一个稳定的操作错误协议。错误信息不仅包含错误码和描述，还包含一个“retry_class”字段，告诉前端这个错误应该如何处理，例如“do_not_retry”（禁止重试）、“refresh_and_confirm”（刷新后确认）等。此外，还会附带跳转链接，比如任务中心的URL，让前端可以引导用户去查看。如果一个命令已经在执行中，它也会返回一个可轮询的目标，让前端知道应该复用原操作键继续轮询。

让前端可以清晰地知道：这个错误能不能重试？是否需要刷新后确认？是否应该跳转到任务中心？是否应该复用原操作键继续轮询？**长任务系统最怕的不是失败，而是失败后，系统和用户都不知道下一步该怎么办。**

13. 可以直接拿走的检查表

如果你也在做Agent长任务，可以用下面这张表自查一下：

这张表看起来非常工程，但它决定的，是用户**敢不敢把任务交给Agent**。

14. 和第4篇的关系

之前我们聊的是状态机本身：AgentTask和AgentStep怎么设计，worker怎么声明任务，lease怎么续租，运行中的任务怎么恢复。而这次讲的，是状态机如何变成产品体验：什么时候轮询，状态怎么展示，哪些状态能取消，哪些状态能继续，重试怎么带幂等键，提案重试怎么带修订版本，任务中心怎么统一接住任务，错误怎么告诉前端下一步动作。

从架构师视角看，这两层必须一起设计。如果只有后端状态机，用户看不到也操作不了；如果只有前端按钮，后端没有命令协议和状态约束，就会留下脏数据和重复执行。所以，**Agent长任务体验的本质，是后端状态机与前端产品设计的无缝融合。**

15. 总结

这篇文章的核心观点很简单：用户不是在等待一个模型返回，而是在和一个会执行、会停顿、会失败、会等待审核、会恢复的业务能力协作。所以，我们必须让它**看得见、停得住、续得上、查得到、错得明白、恢复得安全**。

当这些体验全部打通之后，Agent就不再是一个“后台黑盒任务”，而是一个用户敢点、团队敢查、系统敢恢复的业务执行者。

如果你正在做Agent系统，可以先不急着把工具越接越多。先问自己一句：**当一个任务失败时，你的用户和系统，知道下一步该做什么吗？** 这个问题想清楚了，Agent才真正开始接近一个可靠的业务系统。