Avatar Agent Builder

从零开发交互式数字人智能体。无需安装任何 CLI，skill 自带三个完整模板。

安装（30 秒，一次性的）

在空项目目录下创建 skill 目录，把本 skill 文件夹放进去：

mkdir -p .claude/skills
cp -r /path/to/avatar-agent-builder .claude/skills/

重启 Claude Code。之后直接在对话里说需求。

场景识别

根据用户需求，自动匹配三种模式之一，从 templates/ 目录复制对应模板：

| 用户描述 | 匹配模式 | 模板 | |---------|---------|------| | "挂号" "办证" "理赔" "开户" "流程" "步骤" "引导" "表单" | 业务流 | templates/flow/ | | "聊天" "客服" "对话" "问答" "助手" "陪聊" | 纯对话 | templates/chat/ | | "展示 SDK" "教学" "教程" "看看有什么能力" "配置项" | 能力展示 | templates/sdk/ |

开发流程

模式一：业务流（最常用）

1. 复制模板到目标目录

cp -r .claude/skills/avatar-agent-builder/templates/flow/* .

2. 改 package.json name 字段

3. 定义业务流程 — 改 src/config/state-machine.ts

{
  layout: 'half_center' | 'pip',
  widgetType: 'picker'|'input'|'text'|'confirm'|null,
  subtitleText: '数字人说的话',
  inputMode: 'llm'|'regex'|'passthrough'|'none',
  nextState: 'next_step',
}

4. 写 System Prompt — 改 src/config/llm-prompts.ts

5. 调 Widget 配置 — picker 选项、input 校验规则

6. 本地跑起来

cd my-project
pnpm install
pnpm dev

模式二：纯对话

cp -r .claude/skills/avatar-agent-builder/templates/chat/* .
# 改 src/config/personas.ts 人设 → pnpm install → pnpm dev

模式三：能力展示

cp -r .claude/skills/avatar-agent-builder/templates/sdk/* .
# 直接可用 → pnpm install → pnpm dev

关键规则

1. SDK 凭证在手填面板：APP ID/SECRET 在 UI 输入，不写代码里
2. LLM/ASR 凭证走 .env：不在 UI 暴露
3. 字幕自渲染：订阅 onWidgetEvent + CSS 隐藏 SDK 内置字幕
4. SDK 销毁顺序：interrupt → offlineMode → destroy

排错

| 现象 | 原因 | 检查 | |------|------|------| | 白屏 | SDK CDN 没加载 | index.html 是否有 <script src="xmovAvatar@latest.js"> | | 初始化失败 | APP ID/SECRET 不对 | 控制台 lastInitError | | 数字人不说话 | SSML 没包 <speak> | sdk.speak(\<speak>${text}</speak>`, true, true)| | ASR 无声 | 非 HTTPS/localhost | 本地 localhost 调试 | | LLM 不回复 | 模型名错了 | 用qwen-flash而非qwen3.6-flash` |

参考文档

• 问 SDK API 用法 → reference/sdk-api.md（完整 API 参考 + 错误码）
• 学 LLM+ASR+SDK 开发 → reference/agent-dev.md（开发指南）
• 做业务场景 → reference/business-flow.md（状态机+实战示例）