当 assistant-ui/AI SDK 后端路由缺少…

为 assistant-ui AI SDK 后端路由接入 Langfuse/LangSmith/Helicone，并用 @assistant-ui/react-o11y 渲染已收集的 SpanData 列表。

适用场景

解决思路

1. 先查阅 https://www.assistant-ui.com/llms.txt 获取最新 API。
2. 按 provider 查阅参考文档：./references/langfuse.md（OpenTelemetry 设置、trace attributes、serverless flushing）、./references/langsmith.md（wrapAISDK、metadata、serverless flushing）、./references/helicone.md（AI SDK 与 OpenAI SDK 路由的 Helicone proxy 设置）、./references/react-o11y.md（SpanResource、导出的 span primitive part、span contracts、timeline attributes、styled TraceWaterfall）。
3. 只接入一个负责 telemetry 目的地的 provider 集成：需要跨 agent turn、tool calls、model calls 的分层 trace 时用 Langfuse；需要与 LangChain/LangGraph 工具链共享 traces/evals/prompt management 时用 LangSmith；需要在不改变 AI SDK 调用形态下获得 request logs、costs、latency、prompt diffs 时用 Helicone。
4. Langfuse 消费 AI SDK 在启用 experimental_telemetry 时发出的 OpenTelemetry spans；用它承载分层 trace。
5. LangSmith 通过 wrapAISDK(ai) 包装 AI SDK 函数；使用时调用包装后的函数，而不是原始 ai 函数。
6. Helicone 代理 provider 请求；用它记录请求日志、成本、延迟和 prompt diff，且不改变 AI SDK 调用形态。
7. Langfuse 与 Helicone 可以同时使用，因为一个消费 OpenTelemetry spans，另一个代理 provider 流量；LangSmith 是独立 wrapper 路径。
8. 按实现顺序：先选负责 telemetry 目的地的 provider 集成。
9. 在服务端添加该 provider 的环境变量，以及启动 instrumentation 或 provider 配置。
10. 先 instrument 一个 route，并验证真实请求能到达 provider dashboard。
11. 在生产中把 traces 视为可靠之前，添加 serverless flushing。
12. 只有产品需要应用内 trace 视图时，才用 react-o11y 渲染单独的 SpanData[] feed。
13. 将 provider credentials 和 instrumentation 保留在服务端；不要把 provider key、Langfuse user ID、LangSmith metadata 或 Helicone header 放进客户端组件。
14. 路由示例使用 openai("gpt-5.6-luna")，await convertToModelMessages(messages)，并返回 AI SDK UI message response。
15. 集成页面不使用 assistant-ui route helper；若 route 需要 helper，从 @assistant-ui/ai-sdk 导入；旧安装中 @assistant-ui/react-ai-sdk 重新导出同一 API。
16. 从真实 auth 和 thread state 解析 trace attributes。
17. 用 SpanResource({ spans }) 接收完整原始 SpanData[] 列表；它会规范化 parent relationships、按 start time 排序可见 spans，并管理 collapse state。
18. 将 SpanResource 挂载在隔离的 provider root：`const config = AuiConfig({ span: SpanResource({ spans }) }); <AuiProvider extends={null} config={config}><SpanPrimitive.Children components={{ Span: SpanRow }} /></AuiProvider>;`
19. SpanRow 组件会自动限定到一个可见 span。
20. 当 rows 需要共享时间轴时，使用 SpanPrimitive.Timeline 和 SpanPrimitive.TimelineBar。
21. 当数据更适合 styled flat message 和 tool waterfall 时，使用复制出的 TraceWaterfall element。
22. 在 Vercel、Lambda 或其他 serverless runtime 中 traces 消失时：Langfuse 在函数退出前需要 await langfuseSpanProcessor.forceFlush()，或使用部署特定的 waitUntil 路径。
23. 在 serverless runtime 中 traces 消失时：LangSmith 在函数退出前需要 await client.awaitPendingTraceBatches()。
24. Langfuse 没有 spans 时：在每个被 trace 的 streamText 或 generateText 调用上设置 experimental_telemetry: { isEnabled: true }。
25. Langfuse 没有 spans 时：只在 Node runtime 注册 LangfuseSpanProcessor；OpenTelemetry 不在 edge runtime 运行。
26. LangSmith 不 trace route 时：调用从 wrapAISDK(ai) 解构出的函数，不要调用来自 ai 的原始函数。
27. LangSmith 不 trace route 时：在 runtime environment 中设置 LANGSMITH_TRACING=true。
28. Helicone 流量仍直接去 OpenAI 时：provider baseURL 必须是 https://oai.helicone.ai/v1，并且请求必须同时携带 Helicone-Auth 和 provider authorization header。
29. react-o11y 视图不渲染 rows 时：用 AuiConfig({ span: SpanResource({ spans }) }) 挂载 SpanResource，并在 <AuiProvider extends={null} config={config}> 下渲染。
30. react-o11y 视图不渲染 rows 时：传入完整的 SpanData[] 列表；SpanPrimitive.Children 读取当前 span scope，且不会 fetch traces。
31. 文档中的 span 组件缺失时：SpanPrimitive.ChildByIndex 当前源码未重新导出；需要显式 index scoping 时，使用已导出的 SpanByIndexProvider 配合 row component。

适用边界 · 注意事项

• 不要用 @assistant-ui/react-o11y 向 provider 发送 traces 或从 assistant runtime 推导 spans；它只渲染应用已经收集的 SpanData。
• 若需求是 streaming transport、初始 application wiring、Assistant Cloud persistence 或 copied styled trace UI，不要用本技能，应分别使用 streaming、setup、cloud、elements。
• 不要把 provider key、Langfuse user ID、LangSmith metadata 或 Helicone header 放入客户端组件。