liveavatar-demo

LiveAvatar 演示

四个精选演示，每个都是真实的开源仓库。此技能会完成所有机械性步骤：克隆、安装、配置资源、配置和启动。

此技能无法做到的事——一开始就说明

你无法验证虚拟形象是否开口说话。 每个演示都止步于麦克风和人的耳朵。不要声称你无法观察到的成功，也不要停下来等待你无法触及的事情。遇到以下情况时，请明确说明：

时机	为什么只能由人来完成
提供 API 密钥	无法获取或猜测
演示 1：npm run setup 提示	交互式 readline。请查看参考说明——错误运行会让用户账户中留下孤立的上下文
演示 1：填写姓名和工作邮箱，然后点击 与 Wayne 聊天	填完这两项之前，提交按钮处于禁用状态
演示 2/3：授予浏览器麦克风权限，然后说话	没有麦克风，就无法对话
演示 4：点击 开始，允许使用麦克风，并回答“准备好了”	虚拟形象会等待你口头说“是”才开始操作
确认虚拟形象已开口说话且口型同步	音频和视频都在真人的浏览器中播放
登录 Vercel / 部署（仅限演示 1 的完整级别）	交互式身份验证

其余工作都由你完成。无需逐条讲解每个命令。

步骤 1：获取 LiveAvatar API 密钥——先于其他任何操作

四个演示都需要它，尽早获取可以减少大部分分支流程。现在就在你的第一条消息中，与演示列表一同索取：

前往 https://app.liveavatar.com/developers 获取 API 密钥，然后粘贴到这里。我来处理后续步骤。

没有 API 密钥，不要继续超过步骤 3。 等待密钥期间，你可以先克隆并安装，这样用户只需粘贴密钥就能运行演示——请告诉他们你正在这么做。

绝不要在环境文件中写入占位符或伪造值。每个安装脚本和入口点都会将文件中的内容视为权威值，而无效密钥会导致 401 错误，看起来像是账户出了问题。

步骤 2：选择演示

除非用户已经指定，否则请展示此表格。

#	演示	功能	技术栈	所需额外密钥
1	AI 销售 Agent	虚拟形象筛选潜在客户，并在通话结束时将摘要写入 Notion + Slack	Next.js 15 / TypeScript、Node 22+	本地运行无需额外密钥；完整销售 Agent 需要 Anthropic + 公共 URL
2	LiveKit Agent（由 LiveAvatar 托管的房间）	由你自己的 LiveKit STT→LLM→TTS 流程驱动虚拟形象。房间由 LiveAvatar 管理	Python 3.10+ / LiveKit Agents	LiveKit Cloud 密钥 + 密钥机密
3	BYO LiveKit Agent	相同的流程，虚拟形象加入你自己的 LiveKit 项目中的房间。符合生产环境架构	Python 3.10+ / LiveKit Agents	LiveKit Cloud 密钥 + 密钥机密 + URL、livekit-cli
4	GPT-Live × Hyperframes × LiveAvatar	全双工语音到语音的 GPT-Live 驱动虚拟形象；其工具调用会以动画 Hyperframes 覆层呈现。一个仓库包含多个采用这一精确架构的分支（语言教师、客服 Agent、扑克教练）——专为由 Agent 一次性生成而构建，之后可改作他用	Node 20.12+ / pnpm / TypeScript	可访问 GPT-Live 的 OpenAI 密钥

选择建议：想要最快运行并能说话的演示 → 1。想查看语音流程且已有 LiveKit Cloud → 2。已在生产环境中运行 LiveKit 房间 → 3。想要语音到语音、GPT-Live、与虚拟形象同步的视觉效果，或想要一个计划改造成自己演示的起点 → 4；参考说明会选择最接近的分支。不要要求用户先确认是否能使用某个特定 GPT-Live 模型，仓库的 .env.example 会跟踪当前版本。“随便给我看看” → 1。

演示 2 和 3 使用同一个仓库，只是入口点不同。如果两者都要，只需克隆一次。

费用——启动前一次性说明

• LiveAvatar 沙盒会话免费，时长限制约为 1 分钟。演示 2 和 3 默认使用沙盒；演示 1 使用共享的公开演示头像。
• 演示 4 没有沙盒——会话一启动就按 LiveAvatar 生产环境费率计费，仅受账户默认会话时长限制；仓库本身未设置任何限制。每轮还会按 OpenAI GPT-Live 音频令牌计费。
• 演示 2 和 3 的 STT/LLM/TTS 费用计入用户的 LiveKit Cloud 项目——包括演示 2，即使房间归 LiveAvatar 所有。 房间所有权和推理费用是分开的。用户常会误以为不是这样。演示 3 还会按 RTC 分钟计费。
• 演示 1 每轮按 Anthropic 令牌计费，且只有在接入大脑后才会产生费用。

第 3 步：预检

只运行所选演示对应的检查。报告任何缺失项及其安装命令；未经询问，不要安装运行时。

演示 1：

node --version                 # need >= 22 (engines.node enforces it)
git --version
lsof -ti tcp:3003              # MUST be empty — see below

dev 和 start 都固定使用端口 3003。端口被占用属于致命错误，不是警告，也不会自动递增。如果 lsof 返回 PID，请释放该端口，或计划绕过 npm，使用 npx next dev --port <free>——并记得交接 URL 也会随之变化。

演示 2 和 3：

git --version
uv --version                   # install: brew install uv

不要将 python3 --version 作为门槛。 uv venv 会读取 pyproject.toml 中的 requires-python，并自行选择兼容的解释器——系统 Python 3.9 与此无关。检查它会导致误报，进而中止原本可行的设置。如果确实无法使用 uv，则改用 python3.13 -m venv .venv && .venv/bin/pip install -e .，并说明你采用了此方法。

演示 3 还需要 lk：运行 brew install livekit-cli（如果无法解析，先添加 tap livekit/livekit），然后运行 lk cloud auth——此操作需要交互，请交给用户完成。

演示 4：

node --version                 # need >= 20.12
pnpm --version                 # install: corepack enable, or brew install pnpm
git --version

端口 8787（服务端）和 5173（Vite）——只有 8787 重要；Vite 会自动换端口，服务端不会。参考文档介绍了如何更改服务端端口。

第 4 步：其余凭据

选择演示后，在同一条消息中索取这些凭据——不要提前询问，因为所需凭据取决于演示。

演示	还需提供	来源
1，本地运行	无	—
1，完整销售大脑	ANTHROPIC_API_KEY	https://console.anthropic.com
2	LIVEKIT_API_KEY、LIVEKIT_API_SECRET	https://cloud.livekit.io → 项目 → Settings → Keys
3	前述两项以及LIVEKIT_URL（wss://….livekit.cloud）	同一页面
4	可访问 GPT-Live 的 OPENAI_API_KEY	https://platform.openai.com — .env.example 中已提供可用默认值 GPT_LIVE_MODEL（以及任何 alpha header）；保留这些值，切勿要求用户提供或确认模型 ID

对于演示 1，先阅读其参考文档中的 Local-vs-Full 部分，并在询问前选定级别——本地运行用不到 Anthropic 密钥，若索取该密钥，会阻碍只有 LiveAvatar 密钥的用户。

切勿询问头像 ID。 每个仓库的 .env.example 中都已提供可用默认值。保留该值。

可选且仅适用于演示 1，除非用户主动提出，否则跳过：NOTION_TOKEN + NOTION_DATABASE_ID、SLACK_WEBHOOK_URL。

克隆到何处

默认使用相对于当前目录的 ../liveavatar-demos/<repo-name>（演示 4 使用 <repo-name>-<branch>，因为所有分支共用同一个仓库名称），并在运行 git clone 前确认路径。切勿克隆到用户的项目目录中——如果当前工作目录 就是 用户的项目目录，请向上移出该目录。如果目标已存在且非空，请停止并询问。

步骤 5：设置并运行

先克隆仓库，再阅读仓库自己的 Agent 文档，然后再运行任何内容：先读 AGENTS.md，再读 CLAUDE.md，然后阅读 docs/ 和 README 的故障排除部分（如果存在）。仓库文档比本技能更新，命令和文件布局以仓库文档为准；下文的参考资料则涵盖仓库文档无法了解的内容——账户级注意事项、计费和路由。如果两者相互矛盾，请遵循仓库文档，并指出差异。

演示	参考资料	仓库自己的 Agent 文档
1 — AI Sales Agent	references/sales-agent.md	README + docs/PROVISIONING.md（没有 AGENTS.md——设置细节见参考资料）
2 — LiveKit 托管房间	references/livekit-agent.md	CLAUDE.md（代码地图）+ docs/liveavatar-hosted-demo.md
3 — 自带 LiveKit	references/livekit-agent.md（自带部分）	CLAUDE.md + docs/byo-livekit-demo.md
4 — GPT-Live × Hyperframes	references/gpt-live-demos.md（分支列表）	AGENTS.md、README.md 以及 docs/ 中的每个文件——全部阅读；这些文档是为 Agent 编写的，是设置和迭代的权威来源

每个演示都必须遵守以下规则：

密钥必须放在仓库指定的环境文件中——绝不能放在已提交的文件中。 演示 1–3 使用 .env.local；演示 4 使用仓库根目录下的 .env（该文件已被 Git 忽略）。两种模式都提供了 .env.example。

使用编辑器工具写入密钥，不要使用 shell 命令。 Shell 历史记录和日志会持久保存。例外情况是从环境变量读取密钥的设置脚本——参考资料涵盖了这些情况。

仅复制 .env.example 并不足够。 这些文件中的密钥值为空，但空值与未设置并不等同。参考资料会列出每个密钥。出错是这些演示无法运行的最常见原因。

绝不要激活 venv。 source .venv/bin/activate 不会在工具调用之间持久生效。每次都使用 uv run <command>。

在后台启动长期运行的进程并读取日志，不要让前台进程一直阻塞。交互式设置脚本除外——请参阅参考资料。

报告你实际看到的就绪信号，然后停止。 每份参考资料都会列出一个就绪信号。每个就绪信号只能证明进程已启动，不能证明虚拟形象正常工作。不要推断更多内容。

步骤 6：交接

只提供以下内容，然后停止：

1. 用户现在必须具体执行的操作。 演示 1：打开 http://localhost:3003，填写姓名和工作邮箱，然后点击 Chat with Wayne。演示 2/3：浏览器标签页会自动打开——允许使用麦克风，然后开始说话。演示 4：打开 http://localhost:5173，点击 Start，允许使用麦克风，并在收到提示时说“ready”。
2. 你无法验证的内容——虚拟形象是否出现、是否说话以及是否同步口型（演示 4：以及叠加效果是否显示在正确位置）。请用户确认。
3. 一个自定义提示。 演示 1：src/lib/ai-sales/brain/prompt-parts/ 中的提示词部分。演示 2/3：src/agent.py 中的 instructions=。演示 4：server/prompts/*.md 中的角色设定——并主动提出可以进一步协助；仓库的 docs/ 介绍了如何添加视觉效果和重新规划整个领域，你可以承担这些工作。
4. 如何停止，以及计费情况。 本地开发服务器不产生费用。会产生费用的是虚拟形象会话——关闭浏览器标签页或进程终止时，会话结束。说明适用哪种情况；对于演示 4，还要说明会话按生产环境费率计费，而非沙盒费率。

不要介绍代码库。他们会问。

遇到问题时

每个参考文档都有一个「注意事项」部分，说明具体故障；包含真实 Agent 文档的演示仓库也会在排障部分说明问题——两处都要查看。一般排查方法：

1. 任何网络调用发生前就崩溃 → 环境变量存在但值为空。先检查 LOG_LEVEL（演示 2/3）；这是最常见的问题，而且回溯信息里没有任何相关内容。
2. 虚拟形象已连接但没有声音 → 问题出在语音链路，而非视频链路。演示 1：缺少上下文（opening_text），或 LLM 配置指向了无法访问的 URL——会静默失败，不会抛出错误。演示 4：GPT-Live 链路认证失败——GPT_LIVE_DEBUG=1 会说明原因；参考文档也会说明哪些内容不要更改。
3. 用户说出第一句话时崩溃（演示 2/3） → 模型权重尚未下载。
4. 创建会话时出现 401 → LIVEAVATAR_API_KEY 错误或缺失。此错误信息明确，并会引用请求正文；请相信它。
5. 创建会话时会话被拒绝 → max_session_duration 超出账户套餐上限，或在沙盒模式下使用了生产环境的虚拟形象 ID。
6. 浏览器中什么都没有 → 先检查浏览器控制台，再查看服务端日志。通常是麦克风权限问题。

如果症状不在参考文档的表格中，请根据日志排查，而不是查看 README。

第 7 步：收集反馈

在演示交接后触发，或者用户在同一步骤尝试 3 次以上仍失败并放弃时触发。如果你因缺少凭据而受阻，且没有任何内容正在运行，则跳过。

如果有 liveavatar-feedback 技能，请按其操作；如果没有，就静默跳过，不要擅自编造反馈渠道。只发一行；如果用户不理会，不要继续催促。

参考资料

• references/sales-agent.md — AI 销售 Agent：交互式设置脚本、本地部署与已部署环境、Vercel、环境变量参考
• references/livekit-agent.md — 两个 LiveKit 演示：通用设置、托管流程、自带方案流程、工作进程部署
• references/gpt-live-demos.md — GPT-Live × Hyperframes：有哪些分支、要阅读哪些仓库文档、适用于 Agent 的安全设置、生产环境计费、迭代等级