为应用集成 LiveAvatar…

当需要给应用或网站加入实时唇形同步数字人，或把 LiveAvatar 接入现有 AI 流水线时，按现有技术栈自动路由到最简集成路径并完成实现。

适用场景

解决思路

1. 先扫描代码库和对话上下文收集信号，不要问代码库已能回答的问题：检查 package.json、requirements.txt、imports 中是否有 OpenAI/Anthropic/LLM SDK、ElevenLabs/PlayHT/Deepgram TTS SDK、Deepgram/Whisper/AssemblyAI STT SDK、LiveKit SDK（livekit-server-sdk、@livekit/）、Agora SDK、Pipecat imports、ElevenLabs Agent/Conversational AI、.env 或配置中的 HEYGEN_API_KEY/LIVEAVATAR_API_KEY、对 api.liveavatar.com 的现有调用，以及是否为无后端的纯静态站点。
2. 若扫描后仍有缺口，用一份简洁清单一次性询问用户（不要逐条问）：目标是什么、是否已有自己的 AI 流水线（STT/LLM/TTS 任意组合）、是否需要程序化控制对话（事件、打断、自定义逻辑）还是只要页面上有个数字人。
3. 按决策树只选一条最简路径，不要给多个选项：无后端或只要页面数字人 → EMBED；无任何 AI 栈 → FULL MODE（标准）；只有自己的 LLM → FULL MODE + Custom LLM；有自己的 LLM + 自己的 ElevenLabs TTS → FULL MODE + Custom LLM + Custom TTS；需要显式麦克风控制（对讲机式）→ FULL MODE + Push-to-Talk；有完整 STT+LLM+TTS 流水线 → LITE MODE；有 ElevenLabs Conversational AI agent → LITE MODE + ElevenLabs Plugin；有自己的 LiveKit 或 Agora 基础设施 → LITE MODE + BYO WebRTC。
4. 用 2-3 句话向用户说明推荐哪条路径及原因，然后直接按 references/ 下对应指南实现：embed-guide.md、full-mode-guide.md（含 Custom LLM、Custom TTS、Push-to-Talk 章节）、lite-mode-guide.md（含 ElevenLabs Plugin、BYO WebRTC 章节）。
5. 实现时遵循所有指南的统一结构：Prerequisites（写代码前要创建/收集什么）、Session lifecycle（含 curl 命令和代码的分步流程）、Events（发送和接收什么）、Add-ons（模式专属可选功能）、Sandbox testing（上线前免费测试）、Gotchas（常见故障及规避）。
6. 所有路径都必须遵守：后端/前端分离不可妥协，X-API-KEY 是密钥只能放后端，前端只拿 livekit_client_token；若发现 API key 出现在客户端代码中，立即停止并重构。
7. FULL Mode 中必须先创建 context（哪怕只是 "You are a helpful assistant."），否则数字人会静默且不报错。
8. FULL 与 LITE 是两套完全不同的协议，绝不混用：FULL 用 LiveKit 数据通道（avatar.* / user.*），LITE 用 WebSocket（agent.* / session.*）。
9. 先用 sandbox 测试：is_sandbox: true，avatar ID 为 dd73ea75-1218-4ef3-92ce-606d5f7fbc0a，免费、约 1 分钟会话，准备好后再换成生产 avatar。
10. LITE Mode 不要要求用户重建流水线，而是把现有组件映射到 LITE 回合周期：先读代码理解当前对话回合如何运作（用户音频从哪进、如何到 LLM、TTS 输出如何交付），找到其事件循环、消息处理器或回合管理器。
11. 在现有流程中接入三个时刻：用户开始/停止说话时加 agent.start_listening / agent.stop_listening；TTS 产生音频时把 PCM 输出通过 WebSocket 以 agent.speak 分块发送（替代或叠加现有音频输出）；响应结束时发送 agent.speak_end 并等待 agent.speak_ended。
12. 适配而非替换：若已有可用的回合管理器，就把 LiveAvatar 调用加进去；若已通过 WebSocket 向浏览器流式传输 TTS，就接入同一数据流，目标是以最小改动让数字人视频与现有音频流同步。
13. 最后再验证音频格式：确认其 TTS 输出为 PCM 16-bit 24KHz，若不是则配置 TTS 提供商的输出格式或在集成点加重采样。
14. 写完集成代码后立即触发反馈流程（不要等用户确认可用），或用户放弃、同一步骤失败 3 次以上时也触发：按 liveavatar-feedback 技能收集对话上下文、向用户展示将发送的内容、取得明确同意后提交反馈；保持轻量，在实现消息末尾简短提示一次，用户拒绝或忽略就不要追问。

适用边界 · 注意事项

• 没有 LiveAvatar（或 HeyGen）账号与 API key 时无法落地，需先具备该付费服务。
• 纯静态站点或无后端环境只能走 Embed，无法实现需要程序化控制对话的 FULL/LITE 集成。
• 不要把 FULL 与 LITE 协议混用，也不要让 API key 出现在客户端代码中。