交互与用户体验 / 系统课时

定义消息状态和组件数据契约

定义消息状态和组件数据契约

一次对话需要同时管理历史消息、流式内容和正在执行的请求。本课把会话、消息、内容块、来源引用与请求拆成独立数据契约,再用可运行的 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 相当于组件适配层,网络事件不直接修改按钮。

ts
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("、")}`);

预期输出:

text
消息数=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,不要把任意字符串当作可跳转地址。

可以按下面的验收顺序操作:

  1. 请求运行时检查操作仅出现 stop;文本片段进入后,消息变为 streaming,原文不会丢失。
  2. 完成事件到达后检查 stop 消失,出现 copy 和 view_sources;再次注入相同请求 ID 的文本片段,内容必须保持不变。
  3. 将请求置为 failed 并写入 error: { code: "REQUEST_TIMEOUT", retryable: true },同时将消息置为 failed;此时只允许出现 retry,重试创建新 ID。
  4. 删除来源表中的 s1 再选择消息:没有有效来源时,view_sources 不应显示;来源缺失必须记录诊断信息,不能伪造跳转链接。

TypeScript 联合类型只能检查编译期调用,不能保证服务端返回的 JSON 合法。实际接入时还需在数据入口校验 role、status、内容块字段和关联 ID;校验失败应转入可诊断的错误处理,而不是让组件猜测数据形状。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

定义消息状态和组件数据契约

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通