Chat SDK智能体实现生成式UI流式输出：json-render技术解析

从纯文本到动态界面：Chat SDK 智能体的 UI 进化

聊天机器人长期被困在纯文本的盒子里。即便底层模型能力越来越强，用户在 Slack 或 Teams 里看到的仍然是一段段文字，复杂的表格、图表只能靠 ASCII 或图片勉强表达。json-render 与 Chat SDK 的结合正在改变这一点——智能体可以在对话过程中流式生成结构化 UI 卡片，并以各平台的原生格式直接呈现。

这项能力的核心思路并不复杂：用一份带类型的组件目录约束模型的输出空间，让模型写 JSON 而非自由发挥，再由渲染层把 JSON 翻译成目标平台能识别的卡片格式。约束换来了确定性，模型在目录边界内工作，输出天然可校验。

工作原理：类型化目录加 JSON 规格

整个链路依赖一个关键抽象——类型化组件目录。开发者通过 defineCatalog 定义 schema 和可用组件集合，目录内置了表格、图表、按钮等标准组件定义。智能体拿到目录生成的 prompt 后，输出的是描述界面的 JSON 规格，而不是任意 HTML 或 Markdown。

代码结构相当紧凑。以 lib/bot.ts 为例，先定义目录，然后在 onNewMention 回调里调用 streamText 让模型流式生成 JSON，最后用 streamCard 把文本流转成聊天卡片。系统提示直接来自 catalog.prompt()，模型被明确告知可用的组件和规格格式。

这种设计把「画什么」和「怎么画」彻底解耦。模型只负责产出规格，json-render 负责把规格映射为 Chat SDK 卡片，各平台适配器再负责最终的格式落地——Slack 走 Block Kit，Teams 走 Adaptive Cards。开发者不需要为每种消息形态单独开发和维护一套工具。

streamText 是 Vercel AI SDK 提供的流式补全接口，它返回一个异步的可读流，模型每生成一段 token 就立刻向下游推送，而不是等整段响应结束才返回。这与普通 generateText 的区别在于延迟性质：后者的首字节时间等于完整生成时间，前者则把等待拆散到整个生成过程中。配套的 streamObject、toDataStreamResponse 等工具让前端或服务端能够增量消费结构化输出，Chat SDK 的 streamCard 正是在这一层之上做节流与卡片映射。理解这一点有助于判断流式 UI 的延迟下限：它取决于模型首个有效 token 的到达时间，而非卡片组件的渲染开销。

流式渲染：边写边更新的卡片体验

streamCard 的行为值得细看。它并非等模型写完整份 JSON 再一次性贴出卡片，而是在根元素一有内容后就先发布，随后随着新元素流入持续更新消息。默认的编辑频率上限是每 500 毫秒一次，恰好与 Chat SDK 自身的流式间隔对齐。

这个节流设计很务实。聊天平台的 API 对消息编辑频率有隐性成本，过于频繁地更新既浪费配额也容易触发限流。500 毫秒的窗口让界面看起来是「实时生长」的，又不会给平台适配器造成压力。流结束后，消息定格为经过校验的最终卡片。

对用户而言，感受接近「看着界面被一笔笔画出来」。对智能体应用来说，这意味着长耗时任务可以在执行过程中持续反馈中间状态，而不是让用户对着「正在输入」的提示干等。

校验与平台限制：让失败可修复

生成式 UI 最大的风险是模型输出不合规。toCard 承担了守门人角色，它会逐个检查元素的 props 是否符合组件 schema，不合规则抛出 CardSpecError。关键在于，每个问题都会生成一条可读的 issue，开发者可以把这份问题清单回传给模型，让它产出修正后的规格。

这是把校验错误转化为模型可消费的反馈信号，形成闭环。比起简单报错重试，这种带上下文的纠错路径成功率更高。

平台限制是另一道坎。单条消息能承载的内容有上限，Chat SDK 适配器在超出限制时会降级处理——比如 Slack 适配器会把第二张表格转成代码块。这种静默降级有时可以接受，有时则会破坏信息表达。开发者可以向 streamCard 传入 limits 参数，让超出限制的规格直接被拒绝，从而主动控制降级行为。

CardSpecError 属于「结构化校验错误」这一类设计模式：错误对象不只携带失败信息，还包含机器可解析的问题列表（通常标注元素路径、期望类型、实际取值），使调用方可以程序化地决定重试还是降级。与之相对的是抛出字符串异常，后者只能整体重试。在生成式 UI 场景里，把这类错误序列化后拼进下一轮 prompt，本质上是一种「自我修正」循环，与工具调用失败后回传错误信息给模型的机制同源。需要注意的是，重试应设次数上限并保留原始错误，否则容易在模型持续产出同类不合规输出时陷入无限循环，徒增 token 消耗。

实践意义与适用边界

这套方案把生成式 UI 从概念验证推向可落地的工程实践。类型化目录解决了输出可控性，流式渲染解决了响应体验，校验反馈解决了一致性，平台适配器解决了跨平台成本。四个问题各有对应机制，组合起来构成一条完整链路。

适用场景也相对清晰：需要展示结构化数据的智能体，比如报表查询、监控面板、任务看板类应用，能从表格和图表组件中直接受益。反过来，如果对话以纯文本问答为主，引入这套渲染链路反而增加复杂度。

还有一点需要留意：目录的组件覆盖面决定了智能体的表达上限。目录之外的需求只能退回文本表示，这意味着目录设计本身就是产品设计的一部分，需要预判真实对话中出现的界面形态。文档和 playground 提供了上手入口，实际效果仍需在具体平台的限制下验证。