交互与用户体验 / 系统课时
定义消息状态和组件数据契约
定义消息状态和组件数据契约
一次对话需要同时管理历史消息、流式内容和正在执行的请求。本课把会话、消息、内容块、来源引用与请求拆成独立数据契约,再用可运行的 TypeScript 验证状态更新和按钮生成。完成后,消息组件只负责展示,不必直接处理网络事件。
学习目标
- 区分会话、消息、内容块、来源和请求各自保存的字段。
- 用联合类型表达角色、消息状态、请求状态与内容类型。
- 验证流式完成、迟到片段与操作权限的行为。
把会话数据与请求状态分开
同一会话可以有多轮请求,但每个请求只负责一个响应消息。推荐用稳定 ID 连接对象,避免把请求进度、引用弹窗和按钮开关全部塞进消息正文。
| 对象 | 必要字段 | 负责的问题 |
|---|---|---|
Conversation |
id、title、messageIds |
决定消息所属会话和展示顺序 |
Message |
id、conversationId、role、status、blocks、requestId? |
记录发言者及可展示内容 |
ContentBlock |
id、type,以及文本或图片字段 |
让一条消息支持不同内容类型 |
SourceRef |
id、title、locator |
以来源 ID 支持准确定位引用 |
ChatRequest |
id、responseMessageId、status、error? |
记录发送、执行、取消和失败 |
role 使用 user、assistant、tool;tool 可以进入独立的工具活动区域,不应自动当成助手正文。文本块中的 citationIds 引用来源表,图片块仅存 assetId 和替代文本,由资源层解析实际地址。

用 TypeScript 固定并验证契约
以下代码是完整的最小运行示例。保存为 contract.ts;在临时文件夹安装 TypeScript 5.x 后,依次执行 npx tsc --strict --target ES2022 --module commonjs contract.ts 和 node contract.js。selectMessage 相当于组件适配层,网络事件不直接修改按钮。
type Role = "user" | "assistant" | "tool";
type MessageStatus = "pending" | "streaming" | "completed" | "stopped" | "failed";
type RequestStatus = "queued" | "running" | "succeeded" | "cancelled" | "failed";
type ContentBlock =
| { id: string; type: "text"; text: string; citationIds: string[] }
| { id: string; type: "image"; assetId: string; alt: string };
type SourceRef = { id: string; title: string; locator: string };
type Conversation = { id: string; title: string; messageIds: string[] };
type Message = {
id: string; conversationId: string; role: Role;
requestId?: string; status: MessageStatus; blocks: ContentBlock[];
};
type ChatRequest = {
id: string; conversationId: string; responseMessageId: string;
status: RequestStatus; error?: { code: string; retryable: boolean };
};
type ChatState = {
conversation: Conversation;
messages: Record<string, Message>;
requests: Record<string, ChatRequest>;
sources: Record<string, SourceRef>;
};
type Action = "copy" | "view_sources" | "stop" | "retry";
function activeMessage(state: ChatState, request: ChatRequest): Message | undefined {
if (request.conversationId !== state.conversation.id) return;
const message = state.messages[request.responseMessageId];
if (message?.conversationId !== request.conversationId ||
message.requestId !== request.id || message.role !== "assistant") return;
if (message.status === "pending" || message.status === "streaming") return message;
}
// 流式片段仅能写入仍在运行的请求对应的消息。
function appendText(state: ChatState, requestId: string, chunk: string): void {
const request = state.requests[requestId];
if (!request || request.status !== "running") return;
const message = activeMessage(state, request);
const first = message?.blocks[0];
if (!message || first?.type !== "text") return;
first.text += chunk;
message.status = "streaming";
}
function complete(state: ChatState, requestId: string): void {
const request = state.requests[requestId];
if (!request || request.status !== "running") return;
const message = activeMessage(state, request);
if (!message) return;
request.status = "succeeded";
message.status = "completed";
}
// 操作和来源是派生的组件属性,不写回原始消息。
function selectMessage(state: ChatState, id: string) {
const message = state.messages[id];
const request = message.requestId ? state.requests[message.requestId] : undefined;
const ids = message.blocks.flatMap(b => b.type === "text" ? b.citationIds : []);
const sources = [...new Set(ids)].flatMap(sourceId =>
state.sources[sourceId] ? [state.sources[sourceId]] : []);
const actions: Action[] = [];
if (message.role === "assistant") {
const hasText = message.blocks.some(b => b.type === "text" && b.text.length > 0);
if (hasText && (message.status === "completed" || message.status === "stopped")) actions.push("copy");
if (sources.length > 0 && message.status === "completed") actions.push("view_sources");
if (request?.status === "running") actions.push("stop");
if (request?.status === "failed" && request.error?.retryable) actions.push("retry");
}
return { role: message.role, status: message.status, blocks: message.blocks, sources, actions };
}
const user: Message = {
id: "m1", conversationId: "c1", role: "user", status: "completed",
blocks: [{ id: "b1", type: "text", text: "上传失败怎么办?", citationIds: [] }]
};
const assistant: Message = {
id: "m2", conversationId: "c1", role: "assistant", requestId: "r1", status: "pending",
blocks: [{ id: "b2", type: "text", text: "", citationIds: ["s1"] }]
};
const state: ChatState = {
conversation: { id: "c1", title: "上传排错", messageIds: ["m1", "m2"] },
messages: { m1: user, m2: assistant },
requests: { r1: { id: "r1", conversationId: "c1", responseMessageId: "m2", status: "queued" } },
sources: { s1: { id: "s1", title: "上传规范", locator: "第 3 节" } }
};
state.requests.r1.status = "running";
appendText(state, "r1", "先检查文件大小限制。");
complete(state, "r1");
appendText(state, "r1", "迟到片段不会写入。");
const view = selectMessage(state, "m2");
const text = view.blocks.map(b => b.type === "text" ? b.text : "[图片]").join("");
console.log(`消息数=${state.conversation.messageIds.length}`);
console.log(`请求=${state.requests.r1.status},消息=${view.status}`);
console.log(`内容=${text}`);
console.log(`来源=${view.sources[0].title}·${view.sources[0].locator}`);
console.log(`操作=${view.actions.join("、")}`);预期输出:
消息数=2
请求=succeeded,消息=completed
内容=先检查文件大小限制。
来源=上传规范·第 3 节
操作=copy、view_sources示例先把请求从 queued 置为 running,接收一个文本片段,再由明确的完成事件将请求和消息分别置为终态。最后追加的“迟到片段”被拒绝,因此不会混入已经完成的回答。
按事件而不是按动画推进状态
请求状态描述网络任务,消息状态描述读者眼前的内容;二者相关,却不应该共享同一个布尔值 loading。
| 收到的事件 | 请求状态 | 助手消息状态 | 可观察结果 |
|---|---|---|---|
| 创建请求 | queued |
pending |
占位消息等待响应 |
| 服务端接受 | running |
pending |
等待首个片段,可停止 |
| 收到文本片段 | running |
streaming |
保留并逐步显示内容 |
| 收到完成事件 | succeeded |
completed |
停止按钮消失,开放复制和有效引用 |
| 取消得到确认 | cancelled |
stopped |
保留部分文本并标记已停止 |
| 请求失败 | failed |
failed |
显示错误;可重试性由 error.retryable 决定 |
让组件只消费派生属性
MessageList 按 conversation.messageIds 取出消息,传给 selectMessage;MessageCard 根据 role 与 status 绘制外框,BlockRenderer 根据 type 渲染文本或图片,ActionBar 只读取 actions。来源面板读取已解析的 sources,不要把任意字符串当作可跳转地址。
可以按下面的验收顺序操作:
- 请求运行时检查操作仅出现
stop;文本片段进入后,消息变为streaming,原文不会丢失。 - 完成事件到达后检查
stop消失,出现copy和view_sources;再次注入相同请求 ID 的文本片段,内容必须保持不变。 - 将请求置为
failed并写入error: { code: "REQUEST_TIMEOUT", retryable: true },同时将消息置为failed;此时只允许出现retry,重试创建新 ID。 - 删除来源表中的
s1再选择消息:没有有效来源时,view_sources不应显示;来源缺失必须记录诊断信息,不能伪造跳转链接。
TypeScript 联合类型只能检查编译期调用,不能保证服务端返回的 JSON 合法。实际接入时还需在数据入口校验 role、status、内容块字段和关联 ID;校验失败应转入可诊断的错误处理,而不是让组件猜测数据形状。