Moufa Xingyun Avatar — Development skill for Claude Code

魔珐星云数字人 · Agent 接入指南

把一个**只会回文字的 Agent**，升级成一个**会说话、有口型、有表情动作的 3D 数字人前台**。

核心闭环：

用户提问 → Agent 生成文字 → 数字人 speak() 实时表达（语音 + 口型 + 表情 + 动作）

你只负责把 Agent 的文字喂给 `speak()`，魔珐星云（Xmov）SDK 负责把它实时变成数字人的语音、口型、表情和动作。

这是一份**开发指南 + 可跑示例**。想直接让 AI 帮你接入，把 [`SKILL.md`](./SKILL.md) 作为 Claude 技能加载即可（见下方「作为 Claude 技能使用」）。

---

这能干什么

• 给客服 / 导览 / 政务讲解 / 企业展厅等场景的 Agent，加一个可实时交互的虚拟形象。
• 过去做「语音驱动数字人」开发成本高；现在用魔珐星云的 SDK，几乎零门槛就能给 Agent 装上一个可交互形象。
• 形象 / 音色 / 表演风格在魔珐后台按 appId 配好，代码侧默认不用操心。

---

快速开始

0. 先拿凭证（必需）

登录**魔珐星云官网 → 应用中心 → 创建「具身驱动应用」**，拿到该应用的：

• appId（应用 ID）
• appSecret（应用密钥）

1. 配置与启动

cd demo
cp .env.example .env        # 填入你的 appId / appSecret
npm install
npm start                   # → http://localhost:5173

• 没填凭证：自动降级为 stub 占位数字人（同样的 speak/listen/think/idle 接口），可先排练 UI 与交互流程。
• 没填 ANTHROPIC_API_KEY：Agent 后端自动用内置 mock 话术，整条链路照样跑通。

2. 验收

• 打开页面 → 看到加载进度 → 3D 数字人渲染出来（不是空屏 = init() 成功）。
• 输入一句话 → 数字人开口、口型对得上 → 说完回到 interactive_idle。
• 浏览器控制台 onMessage 无「不支持的配置」或鉴权错误。

---

仓库结构

.
├── README.md            ← 本文件
├── SKILL.md             ← Claude 技能：让 AI 照着它帮你接入
└── demo/                ← 可跑示例（Express + 前端）
    ├── server.js        ← 注入凭证(/config.js) + Agent 接口(mock/Claude)
    ├── .env.example     ← 凭证模板
    ├── package.json
    └── public/
        ├── index.html   ← 页面（含粒子背景、状态徽标、形象切换栏）
        ├── app.js       ← 创建数字人、状态机、流式喂话、形象切换
        └── styles.css

---

关键事实 / 踩坑（实测）

1. 构造后必须 await avatar.init() —— 漏了它只建实例、不下载、不连接、不渲染，你会对着空屏发懵。最常见的坑。
2. 默认不要下发 config —— 形象配置在后台按 appId 自动拉取。把别的账号的 look_name/figure_name 塞进 config，生产网关会直接拒：Error 1: ttsa request error: 不支持的配置。只有确知是本账号的真实资源时才传 config。
3. appSecret 走客户端 —— 这是该 SDK 的既定用法（浏览器侧 new 时就要传）。因此务必：
   • 绝不硬编码进公开仓库；由服务端注入（见 server.js 的 /config.js），.env 必须 gitignore。
   • 一旦通过公网 / 隧道 / 录屏暴露过，及时到后台轮换 appSecret。
4. speak(text, isStart, isEnd) 三参数：内容、是否本轮开始、是否本轮结束。一次说完 `speak(