Chainlit 生产前端：4个修复让AI Agent活过演示期

AI Agent 的演示项目通常把 UI 当成事后贴上去的聊天框，仿佛只要调通 API 就万事大吉。

但真实用户一旦上线，UI 反而变成整个系统里状态最密集的一层：登录会话、WebSocket 长连接、流式返回的半截消息、线程历史，还有那些三个星期后重新加载页面依然必须活着的交互式图表。

整个设计有一个硬约束：UI 本身不感知任何贷款业务逻辑。它只负责把 {prompt, customer_name, conversation_id} 三个字段 POST 到 Agent 的 /invocations 端点，然后把返回的流式结果渲染出来。

同一个代码路径，通过一个环境变量切换就能同时驱动本地的容器和部署在 AWS Bedrock AgentCore 上的远端服务。后面所有的贷款逻辑都在端点那头，UI 的工作只有四件事：传输、身份、渲染和持久化。下面的内容就按这四块展开，顺序正是被故障教会的顺序。

第一块是登录，这里用了一套真正的 OAuth 2.0 授权码流程，对接 Keycloak，完全不搞 demo 密码验证那种玩具方案。传统的单机 compose 环境里最容易踩的坑叫“双主机名分裂”：浏览器是通过 https://localhost:8543 访问 Keycloak 的，但 UI 的后端在容器网络中交换授权码时，必须用 https://keycloak:8443 去请求。

Chainlit 内置的 Keycloak provider 所有 URL 都从同一个基底派生，根本表达不出这种分裂。解决方式是注册一个很小的派生类，把内部通信用的 base_url 和浏览器重定向用的 authorize_url 明确分开：base_url 拿 OAUTH_KEYCLOAK_INTERNAL_URL，authorize_url 拿 OAUTH_KEYCLOAK_PUBLIC_URL 拼接 openid-connect 路径。这样两边各走各的主机名，才不会出现登录完成却拿不到令牌的诡异报错。

还有两个登录细节，同样是出过故障才加上的。一笔贷款会话的时长往往超过 30 分钟，而默认的访问令牌有效期也刚好是 30 分钟。这个栈的下游每一跳都会校验转发过来的令牌，如果聊天中途令牌过期却选择硬关对话，用户毫无准备就会被打断。

所以 UI 做了原地续期：每次新一轮对话开始前，如果令牌已过期或者即将在 60 秒内过期，就先用刷新令牌换取新的访问令牌，再把它塞进用户元数据。Keycloak 那边还会下发一个轮换后的刷新令牌，确保长期会话不会因令牌过期而静默失败。与之配合的是登录失败时的处理：一旦发现刷新令牌也失效了，就抛出一个 _ReloginRequired 信号， UI 顶部弹出一条明确提示让用户重新登录，而不是给一片空白屏幕或者一串看不懂的 JSON 报错。

第二块是流式传输的护栏。Chainlit 基于 WebSocket 把 Agent 端返回的流式消息逐步推给前端，但中途用户可能关闭标签页、网络抖动后重连，甚至同一段话被推了两次。针对这些情况，前端做了几项处理：首先，在 WebSocket 断开后不立即清空当前对话，而是先展示一个“连接中断”的状态条，待重连成功后自动恢复。

其次，显示消息时用消息 ID 去重，保证同一条流式答案不会被重复渲染成两段一样的文字；最后，在每次 POST /invocations 之前检查当前线程状态，如果发现已有正在运行的任务，就用警告提示用户等待当前回答结束，避免同一个会话里并发提交导致的后端状态混乱。这几处都是上线后才暴露出来的，本地单用户测试时永远碰不到。

第三块是持久化和线程恢复。用户关闭浏览器或者一周后再回来，期望看到和历史助理的完整对话，而不仅仅是最近的几条。Chainlit 自身提供了 SQLite/Postgres 的持久化层，但考验出现在带交互组件的线程里。

这个贷款 Agent 的返回里包含 Plotly 图表，一旦线程被持久化后重新加载，普通 Markdown 和文本消息可以原样复现，可图表必须从缓存或数据源中重新构建。解决方案是在对话存入数据库时，把 Plotly 图表的 JSON 描述一并写入自定义字段，并在线程恢复时用 Plotly.react 重新挂载到 DOM 上。页面加载三周后点开一问历史，那个关于还款计划的桑基图依然能交互，全靠这个 JSON 序列化与重新挂载机制，图表才获得了长期可用的交互体验。