talking-avatar-skill

Talking Avatar

创建一段专注的语音对话，使用固定的角色肖像，其嘴部姿势会根据实际远程音频变化。接受照片或角色描述，生成标准肖像和小型嘴部精灵图，并围绕 OpenAI Realtime 构建应用。

协调所需技能

• 每次生成或编辑标准肖像或嘴部帧时，都使用 imagegen。生成前请阅读完整说明。
• 使用 openai-docs，并在适用时使用 openai-platform-api-key，核实当前的 Realtime WebRTC 端点、会话架构、模型、语音和凭证流程。切勿将此技能中的模型示例视为当前事实。
• 界面工作请使用可用的前端设计技能。
• 如果存在 .openai/hosting.json，请遵循 sites-building 和 sites-hosting 完成部署。
• 除非用户明确要求，否则不要添加背景、服装、角色模式或多个角色。默认产品只有一个头像和一段对话。

选择输入路径

1. 提供了照片： 使用 view_image 查看照片，将其作为身份参考，并保留脸型、肤色、发型、眼镜、胡须和鲜明特征。
2. 描述了角色： 将描述规范化为具体的视觉规格。仅在缺少会实质影响身份的细节时提问，例如照片写实风格还是插画风格。否则采用恰当的默认设置继续。
3. 确定角色名称、简洁的人设、应用名称、语言和首选语音。可以安全推断时，请采用合理的默认值。

创建或编辑头像资源前，请阅读 references/image-pipeline.md。

构建资源集

1. 生成一张标准的正面肖像，光线均匀，嘴唇闭合。固定画布、裁剪范围、头部位置、视线、姿势、服装、背景和光线。
2. 基于这张标准图像，生成三个独立且保留身份特征的编辑版本：
   • soft：嘴唇微微分开；
   • round：自然呈圆形的元音口型；
   • open：自然的中度张开口型。
3. 在每个编辑提示词中重复不变项。只改变即时的嘴唇和口腔内部。若眼睛、下颌、眼镜、头部、胡须、服装或光线发生移动或变化，请舍弃该帧。
4. 从所有三个语音帧中裁出完全相同的最小实用矩形。保留足够的周围皮肤以便羽化，但不要交付完整画面的语音图像。
5. 默认仅保存以下项目资源：
   • public/avatar/avatar-base.jpg
   • public/avatar/mouth-soft.png
   • public/avatar/mouth-round.png
   • public/avatar/mouth-open.png
6. 运行 scripts/validate_avatar_assets.py --dir <project>/public/avatar 并修复所有失败项。

绝不要为完整肖像制作动画。只替换嘴部贴片。

构建或集成应用

优先使用现有且可运行的技术栈。新建项目时，使用 Next.js 或 vinext，因为用户的 API 密钥必须经过服务器路由；只有在已有安全后端时才使用纯 Vite。

对于兼容的新 Next/vinext 项目，使用已验证的核心脚手架：

python3 <skill-dir>/scripts/scaffold_app.py \
  --target <project-dir> \
  --character-name "Mira" \
  --app-name "Mira Live" \
  --persona "a concise, curious field researcher" \
  --model "<verified-realtime-model>" \
  --transcription-model "<verified-transcription-model>" \
  --voice "<verified-realtime-voice>"

目标项目必须已包含框架配置和依赖。若缺少 framer-motion 和 @phosphor-icons/react，请安装。仅在新初始化的项目中，且检查过将被替换的文件后，才使用 --force。对于现有产品，应从 assets/starter/ 复制或改造单个文件，而不是覆盖其架构。

更改 Realtime 路由、API 密钥流程或事件处理前，请阅读 references/app-contract.md。

实现自然的唇形同步

阅读 references/realtime-lipsync.md，并遵守其中的行为规范：

• 分析远程输出 MediaStream，而不是麦克风输入或 Realtime 事件的触发频率。
• 每个动画帧都对音频采样，不更新 React 状态。
• 可见的嘴部姿势更新频率不高于约 96 ms 一次。
• 平滑处理起音和衰减，根据滚动峰值进行归一化，并在短暂无声后闭嘴。
• 按顺序切换相邻姿势（closed → soft → round → open），不要跳跃切换。
• 设置 DOM data-mouth 属性，并通过 CSS 恰好显示一个补丁。
• 完全保持肖像图像像素静止。

不要使用预制的无限嘴部动画。response.output_audio.delta 可以标识说话状态，但不能提供唇形同步时间信息。

保留 BYOK 安全边界

• 要求用户在应用内输入 OpenAI API 密钥。
• 仅将密钥保存在组件内存中；绝不使用本地存储、会话存储、IndexedDB、分析工具、日志或源文件。
• 通过 HTTPS 将密钥一次性发送到同源会话路由，在协商后清除客户端状态，并返回 Cache-Control: no-store。
• 绝不将长期有效的密钥直接暴露给 Realtime WebRTC 对等连接。
• 将上游身份验证和速率限制错误映射为简短的用户可见错误，不回显响应正文或机密信息。

交付前验证

1. 运行生产构建。
2. 运行 lint，并在可用时运行入门回归测试。
3. 确认源代码包含 AnalyserNode、requestAnimationFrame、90–110 ms 的姿势更新间隔、相邻姿势步进逻辑，并且不包含 CSS @keyframes mouth-* 循环。
4. 确认所有嘴部补丁尺寸完全一致，并且在桌面端和移动端都与标准嘴部位置对齐。
5. 确认说话时只有嘴部发生变化；眨眼、头部晃动、姿势漂移和整帧替换均不符合要求。
6. 确认麦克风静音、扬声器静音、中断、转录文本增量、输入文本消息、断开连接清理、音频上下文清理、空状态、连接错误和无效密钥错误。
7. 如果用户要求进行浏览器视觉 QA，请测试一轮实时语音对话，并根据观察到的语音调整时序。否则，不要声称已通过浏览器视觉验证唇形同步。
8. 在用户要求部署或当前托管技能要求部署时进行部署，然后返回线上 URL。

交付内容

返回可运行的应用、最终头像资源路径、生成提示词集、使用的是照片模式还是描述模式、该次运行所验证的 Realtime 模型／语音、验证结果，以及适用时的部署 URL。