从一次“重新发送 / 重新生成”开始，聊聊流式聊天状态机到底解决了什么问题

最近在整理自己的 HarmonyOS 聊天 Demo。发现聊天页里有一个问题很容易被忽略：

AI 回复失败以后到底应该让使用者点“重新发送”，还是点“重新生成”？

使用者痛点：回复失败后没有明确的操作指引。导致使用者不知所措，体验大幅下降。

这个问题看起来只是一个按钮文案问题。但真正往下想，会发现它其实牵出了整个流式聊天模块的状态设计。老实说，

说到比如。

使用者消息什么时候算发送成功？AI 消息什么时候从“思考中”变成“生成中”？说起来，最终一帧 done 里如果带 error，算成功还是失败？流式返回一半断了应该让使用者重新发送问题，还是让 AI 重新生成回答？历史记录恢复时如果某条消息还停在 STREAMING，应该怎么处理？怎么说呢，

使用者痛点：上述模糊不清的状态让 UI 难以给出准确反馈。导致页面卡顿、错误提示不明确。

这些问题如果一开始没有想清楚，代码很容易变成一堆 if else魔法字符串和临时兜底。

这次重构，我没有继续在旧逻辑上补判断。而是把聊天消息抽象成了一套更明确的状态机，而且把错误也类型化。

这篇文章就从一个最常见的场景开始，聊聊这次重构到底解决了什么问题。

一. 先想一个最简单的需求

假设使用者在聊天框里输入：

帮我生成一份日报

接下来点击发送。

站在使用者角度。他只看到两件事：

我的问题发出去了 AI 开始回复了

使用者痛点：使用者只能看到“已发送”和“正在回复”，却无法得知背后到底经历了哪些细分步骤。

但站在代码角度，这个过程其实至少包含两条消息：

userMessage：使用者发出的那条问题
aiMessage：AI 即将生成的那条回复

正常发送时代码要先做几件事：

创建使用者消息 userMessage。状态为 SENDING
创建 AI 占位消息 aiMessage，状态为 THINKING
生成历史上下文快照 historySnapshot
把这两条消息 push 到 historyMessage
调用 runStream 发起 SSE 流式请求

说白了使用者点一次发送，页面上其实先插入了两条消息。

使用者消息负责展示“我刚刚问了什么”。

AI 消息负责接收后续一段段流式返回的内容。

二. 最粗暴的方案：用字符串和 boolean 硬判断

一开始最容易想到的写法是：

全局用 isLoading 判断是否正在生成AI 空内容时显示“AI 思考中...”失败时把 content 改成“生成失败，请稍后重试”停止时往正文里拼一个 “”

这种写法能不能跑？能，但问题也很明显。

• 第一，消息状态不清楚。老实说，

一样是 content 为空。它可能代表：

AI 正在思考
AI 没有收到任何回复
历史记录里内容丢失
刚创建了占位消息

使用者痛点：UI 无法区分这些不同场景，只能统一显示 “加载中”，导致误导或卡死界面。

• 第二，失败原因不清楚。按理说，

aiMessage.content = '生成失败。请稍后重试'

那这句话到底代表什么？网络断了，接口超时？业务错误，done 帧里没有任何文本和卡片？所有这些根本无法从文字判断出来。

• 第三，UI 逻辑会被文案绑架。其实，

content === '生成失败，请稍后重试'
content.includes

If product changes wording。logic breaks.

User Pain Point:The UI becomes fragile;a simple copy‑write change can break functionality.

三. 为什么需要 MessageStatus

This refactor introduces StatusMessage.ets,enumerating every possible state:

export enum MessageStatus {
SENDING = 'sending',THINKING = 'thinking',STREAMING = 'streaming',DONE = 'done',STOPPED = 'stopped',FAILED = 'failed'。}

A single field now tells us everything about a message.

• User messages have three states:
  • SENDING – waiting for server acknowledgment.
  • DONE – server accepted.
• User messages have five states:
  • T​HINKING – request accepted,waiting first token.
  • S​TREAMING – tokens are coming.
  • D​ONE – normal completion.
  • S​TOPPED – user stopped generation.

为什么 STREAMING 不是终态？ts STREAMING -> DONE STREAMING -> FAILED STREAMING -> STOPPED

User Pain Point: Without a clear terminal flag,UI may keep showing a spinner forever after app restart.

ts export function isTerminal: boolean { return status === MessageStatus.DONE || status === MessageStatus.STOPPED || status === MessageStatus.FAILED;}

This helper is used when restoring chat history: any lingering T​REAMING -state is forced into E​RROR ,prompting user to retry.

四. 为什么还需要 ChatError ts export enum ChatErrorType { NETWORK_ERROR = 'NETWORK_ERROR',SERVER_ERROR = 'SERVER_ERROR',EMPTY_REPLY = 'EMPTY_REPLY'。} Three concrete error types replace vague strings. * **Network error** → onError callbacks. * **Server business error** → meta.error inside done frame. * **Empty reply** → no text & no card after stream ends. Conversion flow: ts ChatError.network ChatError.server ChatError.empty Then map to UI hint via `error.toUserHint`. User Pain Point: Developers no longer need to guess *** something failed;说起来，logs contain precise error categories and UI text stays decoupled from logic.

---