perf: Prewarm LiveAvatar browser sessions

[jiejuncai-ly]

修改内容

• 新增会话 prewarm API，并抽离可复用的 Agent dispatch 服务。
• Browser 房间连接后并行启动本地媒体与 Agent dispatch，复用后端预热状态。
• Next 静态资源、logo 与浏览器 API 改用 app-relative 路径，同一 build 原生兼容本地根路径、Gateway /s/<slug> 和 CubeSandbox 动态 /proxy/4003/，不再依赖 HTML 重写代理。
• 将 VAD/ONNX 静态资源路径限定到当前 sandbox session，兼容 Gateway 路径前缀。

原因

原流程串行等待媒体与 Agent 初始化，用户进入会话后才能启动关键链路，导致首屏视频和人脸检测就绪偏慢。旧 CubeSandbox 还需要额外代理重写根路径资源，运行结构不必要地分成 4003/4103 两层。

验证

• 前端测试：142 passed；lint 与 production build 通过。
• 无 HTML 重写的本地、Gateway 前缀和 CubeSandbox 前缀代理实测：页面正常渲染，CSS/JS/logo 全部 200，五个 API 路由均命中 Next。
• 本地 browser 链路端到端通过，dispatch 约 1.1 秒；人脸检测后 face gate 正常解除静音。
• /api/session/prewarm 的每 Session secret 只用于服务端单次授权：执行中或成功后的重复请求返回 409，失败释放 guard 允许 Gateway 重试；测试覆盖消费、并发与失败重试。
• Browser source 的部署支持范围为 Sandbox Chromium；音频/视频并行 getUserMedia 按该运行环境验证。
• 常规 dispatch 默认 8 秒是 lex-main 的既有边界；prewarm 的 worker-ready 与 dispatch 共用总计 20 秒预算，并受 Gateway 30 秒外层超时约束。

[jiejuncai-ly]

本轮 review 已逐项核对：

• prewarmRoomSession 等待 room_audio_input / room_video_input 不改。browser 模式仍通过 lex-voice 的 browser profile 启动这两个 Room Input 服务参与者；它们先入房并等待浏览器原始轨道。usesServerRoomInputDevice() 只决定用户启动阶段是否再次要求 video readiness，不能据此推断 browser 模式没有这两个参与者。
• 本地媒体快速失败仍等待 dispatch 的问题已在 d813831 修复：失败时立即 cancelAgentSessionStart(sessionId)，中止 dispatch fetch，再复用原有统一远端清理路径。
• session identity 的隐式漂移已在 9d160e4 修复：LIVEAVATAR_VOICE_SESSION_ID 进入 appConfig.voiceSessionId，且远端 UI config 不能覆盖。AGENT_NAME 由同一进程 env 同源读取，LiveKit room name 则由 canonical session id 推导，因此不再增加另一套配置入口。

验证：129 tests passed，lint passed，production build passed（仅保留已有 ONNX dynamic-require warning）。真实 cloud template 的 /api/session/prewarm HIL 仍按部署 gate 执行。

[jiejuncai-ly]

更新：routing 已合入，本 PR 已基于最新 lex-main 恢复并完成重新移植与测试；当前分支是正式候选，不再是撤下状态。

[github-actions]

Claude finished @jiejuncai-ly's task in 1m 27s —— View job

---

任务清单

• 拉取 PR diff（origin/lex-main...HEAD）
• 阅读相关约定与既有实现
• 审查 LiveKit room/track 生命周期与浏览器媒体权限失败路径
• 审查 React hook 清理、Next.js 客户端/服务端边界
• 审查环境变量/secret、TypeScript 类型、验证完整性
• 汇总发现并输出 review 结论

Review 结论

通过

本轮唯一新增 commit 8ffb46b（fix: share session coordination across chunks）修复了此前两轮 review 指出的最后一个 P1：session-registry.ts 的 sessions/nextGeneration 与 session-dispatch-service.ts 的 inFlightDispatches 现已按 prewarm-use-guard.ts 的既有模式挂载到 globalThis（__liveavatarRoomSessionRegistry / __liveavatarInFlightDispatches），跨 chunk 场景下并发 dispatch 去重、共享 deadline、cancelAgentSessionStart 取消标记等状态不再退化为独立副本。tests/session-registry.test.mjs 与 tests/session-prewarm.test.mjs 新增了跨模块实例（?chunk= query）用例验证共享效果，实现与测试一致。

问题及建议

未发现需要阻塞合并的问题。残余风险（沿用前两轮未修复的 P2，不阻塞合并）：

• [P2] hooks/useRoom.ts:275-290：本地媒体与 dispatchAgentSession() 并行失败时仍只 throw localInputResult.reason，dispatchResult.reason 仅 console.warn，未体现在最终用户提示中，排障时不易定位 dispatch 侧故障。
• [P2] lib/session-dispatch-readiness.ts:43-54：requireRoomInputParticipantsReady && !hasReadyRoomInputParticipants(...) 的判断在 video-ready 的两个分支中重复书写，建议合并简化。

[github-actions]

Claude finished @jiejuncai-ly's task in 3m 55s —— View job

---

任务清单

• 拉取 PR diff（origin/lex-main...HEAD），聚焦本次 synchronize 新增改动（8ffb46b..d2abb62：fix: support dynamic sandbox proxy paths）
• 阅读相关约定与既有实现（app-config.ts、next.config.ts、hooks/useRoom.ts、lib/session-dispatch-client.ts、lib/session-stop-client.ts、lib/frontend-vad-observer.ts）
• 审查 LiveKit room/track 生命周期与浏览器媒体权限失败路径
• 审查 React hook 清理、Next.js 客户端/服务端边界
• 审查环境变量/secret、TypeScript 类型、验证完整性
• 汇总发现并输出 review 结论

Review 结论

有条件通过

本轮新增 commit d2abb62（fix: support dynamic sandbox proxy paths）将 logo/logoDark、fetch('/api/...')、next.config.ts 的 assetPrefix 等由绝对路径改为相对路径，用于兼容 gateway 动态代理前缀；此前两轮（至 8ffb46b）指出的 P1 已全部修复，其中 useRoom.ts:275-290 的并发失败提示问题已在更早的 e2ddad2 修复（dispatchResult rejection 现在会正确 throw，不再只是 console.warn）。

问题及建议

• [P1] hooks/useRoom.ts:112-114、lib/session-dispatch-client.ts:24、lib/session-stop-client.ts:67、next.config.ts:4：相对路径方案的正确性依赖浏览器当前 URL 以 / 结尾（new URL('api/x', href) 在无尾斜杠时会丢弃最后一级路径段，tests/dynamic-proxy-paths.test.mjs:36-39 中 https://gateway.example/s/session-slug 的用例已经验证并断言了这种"退化"行为，而不是防止它发生）。仓库内没有任何 middleware/redirect 保证 gateway 入口 URL 一定带尾斜杠；若 LexVoice gateway 某个代理路径不带尾斜杠，api/session/dispatch、api/session/stop、api/connection-details 以及 assetPrefix: '.' 产生的静态资源 URL 会一起解析到错误路径，且是静默失败（fetch 404 或路由不到）。建议：a) 与 LexVoice gateway 确认所有代理路径是否强制尾斜杠；b) 或在前端增加保护措施（如检测 window.location.pathname 无尾斜杠时 history.replaceState/重定向补全），而不是仅依赖外部约定。
• [P2] README.md:113：示例配置仍写 logoDark: '/lk-logo-dark.svg'（带前导斜杠），与新的相对路径约定（app-config.ts:225 现为 'lk-logo-dark.png'）不一致，容易误导使用方自定义 logo/logoDark 时继续用绝对路径，从而在 assetPrefix: '.' 下解析失败。建议同步更新文档说明。
• [P2]（沿用上一轮，未修复）lib/session-dispatch-readiness.ts:44,52：requireRoomInputParticipantsReady && !hasReadyRoomInputParticipants(...) 在两个分支中重复书写，可合并简化，不阻塞合并。

其余部分（session-dispatch-service.ts、prewarm-use-guard.ts、session-registry.ts 的跨 chunk 共享状态等）与前两轮审查内容一致，未发现新增问题。