AI聊天如何流式渲染商品卡片commerce-agents的Presentation工具与UI事件流完全解析【免费下载链接】commerce-agentsReference blueprint for building shopping and merchant agents with Claude. Examples in retail, commerce, telecom, and entertainment included.项目地址: https://gitcode.com/gh_mirrors/co/commerce-agentscommerce-agents 是 Anthropic 开源的 Claude 商业 Agent 参考蓝图内置零售、出行、电信、娱乐四个可运行的电商示例。这篇文章带你完整看懂它的核心交互AI 聊天窗口里的商品卡片是如何流式渲染的——即Presentation 工具在模型还在打字时就把卡片骨架通过UI 事件流ui/ui_partial事件逐张推到前端的过程。为什么不让模型直接吐出卡片做 AI 购物助手时最直觉的做法是让模型直接输出商品 JSON前端照单全收。commerce-agents 的设计恰恰相反它把一次回答拆成三个角色模型只做判断选哪些商品product_id、为什么选、按什么顺序服务端补全事实标题、价格、图片等所有事实字段由服务器从会话内的目录记录中拼接join进来前端只渲染可信数据用户永远不会看到模型编出来的价格或标题。这套契约的入口是 commerce_common/presentation.py 中的PresentationComponent每个展示组件 一个工具name 前端识别的组件名component 参数校验模型payload_model 两个拼接钩子enrich全量、enrich_partial增量。统一的执行器run_presentation只干三件事校验 → 补全 → 发射一个ui事件校验失败或钩子拒绝时则回一条错误信息给模型重试。Presentation 工具一份组件-工具契约以购物 Agent 的present_products为例看 shopping_agent/tools/presentation.py 的载荷定义模型发的是picksproduct_id 不超过 140 字的推荐理由前端收到的却是items——每个商品被补全成完整的目录记录。补全逻辑在 shopping_agent/enrichment.pyenrich_products把模型选的product_id与seen_products本会话搜索结果逐一匹配匹配不上的 id 直接丢弃并在结果里附一条已跳过未知 id的备注告诉模型全部落空则抛出PresentationRefused调用被门闸gate拦下同类组件还有present_comparison对比表、present_plan购买计划、present_guide选购指南、checkout购物车渲染等统一注册进PRESENTATION_COMPONENTS字典。对新手最实用的启示是前端组件 工具名 事件里的component字符串三者一一对应加一种新卡片只需新增一份规格不需要改动核心包见文末延伸阅读。UI 事件流从打字机到商品卡的完整清单一个回答轮次turn会以 SSEServer-Sent Events持续推送事件。commerce_common/streaming.py 的模块 docstring 就是完整的事件表核心与卡片渲染相关的有事件作用卡片渲染中的时机text_delta增量助手文本打字机效果的正文tool_call/tool_result工具调用与结果卡片正在准备中的状态行ui_partial组件流式中间帧卡片边生成边长出来ui组件最终帧带stream_id定稿替换掉最后的中间帧progress/error/turn_complete状态行 / 错误 / 结束收尾与降级每个事件由to_sse打包成一个 SSE 帧示例服务在 examples/demo_common/host.py 的stream_turn里用 FastAPI 的StreamingResponsemedia_typetext/event-stream逐帧发出前端的 examples/web-shared/protocol.ts 定义了完全对应的事件类型。注意一个设计细节commerce_common/turn.py 的outcome_events会给每个ui事件盖上stream_id即工具调用的 id让最终帧和它前面的所有ui_partial帧天然配对——这是流式渲染能接得上的关键。渐进式渲染模型还没写完卡片已经开始长这是 commerce-agents 最有意思的部分。模型生成工具参数本身也是流式的commerce-agents 选择边解析边渲染急切流式输入请求把展示工具标记为eager_input_streaming参数一边生成一边以 JSON 片段到达容错解析parse_partial_jsonstreaming.py把还没写完的 JSON补全成可解析对象——正在书写的字符串连同它的键一起被整体跳过所以卡片上不会出现半句话增量补全StreamedRound.frame 调用组件的enrich_partial钩子如partial_products只从会话状态同步读数据并用partial_signature判断是否发生了结构性变化标题出现、列表长度变化——只有结构变了才发ui_partial保证流保持轻量前端逐条滴灌examples/web-shared/turn.ts 为每张卡片维护一个 slot键为轮次-组件-序号状态机是pending → partial → final失败重试时变retrying一次性到达的多条中间帧会被切进队列以 180ms临近定稿时 80ms的节奏逐条渲染所以卡片是一件一件长出来而不是瞬间蹦出整屏。最终ui事件携带同一个stream_id到达时前端的 slot 队列被冲刷卡片一次性定格为final状态替换最后的中间帧。出错时的兜底门闸、重试与降级流式卡片最怕渲染了一半结果服务端说这调用不合法。commerce-agents 对此有完整方案溯源门闸provenance gate模型引用了本会话没出现过的product_id会被丢弃并注明原因全部无效时调用以blocked状态返回模型收到的是先搜索再挑结果这样的可执行指引见 shopping_agent/gates.py参数流坏了JSON 始终没解析成功时该调用以错误结果回填、轮次照常继续模型会被要求重发这次调用前端不闪退中间帧已渲染的卡片进入retrying状态——保留已显示的内容、变暗等待重试成功则复用同一个 DOM 节点避免用户看到的卡片消失重来。这套错误也是流的一部分的思路正是流式 UI 与一次性 JSON 响应的本质区别。自己动手4 步复刻流式商品卡片如果你的产品也想要边生成边出卡commerce-agents 给出的路径非常清晰定契约为卡片写一个 pydantic 载荷模型模型能发什么和component名前端渲染什么写 enrich 钩子全量钩子做校验补全拒绝时抛PresentationRefused再写一个同步的enrich_partial钩子从会话状态读增量数据注册并交给执行器构造PresentationComponent交给run_presentationui/ui_partial事件就会自动进入 SSE 流前端按component注册渲染器参照 examples/retail/storefront-web/components/generative/ 的做法每个垂直业务只在自己的目录里加卡片组件核心事件处理零改动。 官方配套文档 plugins/commerce-builder/skills/commerce-ui-tools/SKILL.md 用一页篇幅总结了上述契约含如何给出行、电信、娱乐等新行业添加垂直组件是最佳延伸阅读。小结commerce-agents 用三个设计换来了又快又可信的流式商品卡片组件即工具的 Presentation 契约让前端永远只渲染服务端补全过的数据ui/ui_partial共享stream_id的 UI 事件流让中间帧 定稿帧无缝衔接parse_partial_json 结构签名 前端滴灌队列让卡片在模型还在输出参数时就开始逐件生长。理解这套模式你基本就掌握了 AI 聊天界面中一切生成式卡片的实现骨架。【免费下载链接】commerce-agentsReference blueprint for building shopping and merchant agents with Claude. Examples in retail, commerce, telecom, and entertainment included.项目地址: https://gitcode.com/gh_mirrors/co/commerce-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考