需要为代理、用户或命名角色创建可复用的 HeyGen…

当还没有头像、需要先用 HeyGen Avatar V 创建持久化的脸+声身份，并把 avatar_id/voice_id 交给视频技能复用时使用。

适用场景

解决思路

1. 从用户第一条消息检测语言并保存为 user_language；之后所有问题、状态更新、确认和错误消息都用 user_language 沟通。
2. 设计或选择声音时在提示中明确目标语言，让语音库返回匹配该语言的声音。
3. 技术枚举值保留英文，例如 Young Adult、Realistic、landscape，不翻译。
4. 聊天中保持简洁，不显示 avatar IDs、group IDs 或原始 API payload；只报告结果，例如头像已创建、可用。
5. 不向用户提内部阶段名，例如 Phase 0、Phase 5 Symlink Maintenance；用自然语言，例如「正在设置你的头像…」。
6. 每个阶段只问一两个问题，不要批量问；按阶段顺序走，只问继续所需的最少问题。
7. 先读 workspace 根下 SOUL.md、IDENTITY.md、AVATAR-*.md 获取身份；只问真正缺失的信息。
8. 不叙述技能内部，不要说「let me read the workflow」「checking the reference files」「loading the avatar discovery guide」；静默读取。
9. 不要宣布即将做什么，跳过「Creating the avatar now」等 meta 评论；直接做，下一步让用户听到结果或检查点问题。
10. 不叙述 transport 选择；静默选择 MCP 或 CLI；若二者不可用，请用户配置一个但无需解释原因。
11. 默认目标是 agent：主要用途是给 agent 脸+声以呈现视频；只有明确 “my avatar”“me”“my photo” 才路由到 user。
12. 不要批量问问题；按阶段走，每阶段最多一两个问题。
13. 对 agent 头像，先读 SOUL.md 和 IDENTITY.md，然后直接走 prompt-based creation；不要先问用户照片或外貌细节。
14. 默认使用 prompt-based 创建；只有用户明确要真人数字孪生时才 opt-in 照片。
15. 环境检测：尝试从 workspace 根读取 SOUL.md；找到则为 OpenClaw，跳过环境检测节并直接到 Phase 0。
16. 若未找到 SOUL.md，则为 Claude Code 环境且无 workspace 身份文件；仍去 Phase 0，不要跳到列出用户头像或问照片。
17. 忽略 workspace 中属于不同人或 agent 的 AVATAR-*.md，例如为 Claude 创建时遇到 AVATAR-Eve.md；只使用名称与当前创建对象匹配的 AVATAR 文件。
18. 在 Phase 0 目标检测前不要获取 HeyGen avatars。
19. 静默检测 API 模式一次并继续；MCP 优先：若存在匹配 mcp__heygen__* 的工具则使用；MCP 通过 OAuth 认证，无需 API key，消耗用户现有 HeyGen 计划 credits。
20. CLI fallback：若 MCP 不可用且 heygen --version 退出码 0，则使用 CLI；认证用 HEYGEN_API_KEY 环境变量或 heygen auth login，持久化到 ~/.heygen/credentials。
21. 若 CLI 缺失、--version 报错或未认证，静默跳过 CLI，不要重试 MCP。
22. 若 MCP 和 CLI 都不可用，只告诉用户一次：连接 HeyGen MCP server 或安装 HeyGen CLI：curl -fsSL https://static.heygen.ai/cli/install.sh | bash，然后 heygen auth login。
23. 仅使用 API v3；绝不调用 v1 或 v2 endpoint。
24. 对不确定的 endpoint，先查文档：GET https://developers.heygen.com/llms.txt 获取索引；在任意页面 URL 后加 .md 获取干净 markdown；或运行 heygen <noun> <verb> --help；读 spec 后再构建请求，不要猜字段名。
25. 每个 avatar 在 workspace 根写一个文件 AVATAR-<NAME>.md；agent、user、character 都用命名 canonical 文件。
26. 同时维护基于角色的 symlink：AVATAR-AGENT.md → AVATAR-<CURRENT-AGENT-NAME>.md，AVATAR-USER.md → AVATAR-<CURRENT-USER-NAME>.md，供消费技能按角色泛化查找。
27. named files 是 single source of truth；aliases 只是指针，不应漂移；named characters 不设 role alias，只按名称引用。
28. AVATAR 文件格式包含 Appearance、Voice 用自然语言；HeyGen 段含 Group ID、Voice ID、Voice Name、Voice Designed、Voice Seed、Looks、Last Synced。
29. 在 HeyGen 段记录 Group ID 作为稳定 character identity anchor，永不变化。
30. 记录 look_ids 但标识其 ephemeral；运行时总是通过 heygen avatar looks list --group-id <id> 或 MCP list_avatar_looks 从 group_id 重新解析，永不硬编码 look_id 作为主要 avatar 引用。
31. 每次调用开始输出：🎭 **Using: heygen-avatar** — creating an avatar for [name]。
32. Phase 0 判断创建对象；按路由信号优先级：user 仅显式，例如 “create my avatar”“make me an avatar”“I want my face in a video”“a digital twin of me”“based on my photo”，需要所有格或明确照片，若名字不明显则问名字。
33. named character 仅显式，例如 “create an avatar called Cleo”“design a character named X”“build a presenter named Y”，用给定名字。
34. agent 为默认：其余如 “create your avatar”“bring yourself to life”“set up an avatar”“let's make an avatar”“create an avatar”“design a presenter”“I want you to appear in videos” 或任何含糊说法；读 IDENTITY.md 获取名字。
35. 当不确定时默认 agent；不要在含糊请求中先问用户名、外貌或声音；若读完 IDENTITY.md + SOUL.md 仍含糊，问一个简短澄清问题，例如「quick check: this avatar is for you, or for me?」。
36. 然后检查 workspace 根 AVATAR-<NAME>.md：若存在且 HeyGen 段已填，则问「你已设置头像。要添加新 look、更新它，还是重新开始？」并等待。
37. 若 AVATAR 文件存在但 HeyGen 段为空，跳到 Phase 2。
38. 若没有 AVATAR 文件，进入 Phase 1。
39. 角色别名 staleness check：agent 目标读 AVATAR-AGENT.md，跟随 symlink，并对比 AVATAR-<CURRENT-AGENT-NAME>.md；若不同，即使无其他变化，也在 Phase 5 重新链接。
40. user 目标同样检查 AVATAR-USER.md；named character 无 alias 可检查。
41. 可选 existing-avatar check：仅当 Phase 0 目标=user 且无 AVATAR-<USER>.md 时，先列其 HeyGen avatars：MCP list_avatar_groups(ownership=private)，CLI heygen avatar list --ownership private。
42. 若列表非空，展示选项并问用哪个或是否新建；若空，进入 Phase 1；agent 和 named-character 目标完全跳过此检查。
43. Phase 1 顺序：文件优先，问题其次；prompt-based 是默认路径，photo 是 opt-in upgrade。
44. 对 agent：读 SOUL.md、IDENTITY.md 和已有 AVATAR-<NAME>.md。
45. 若找到 SOUL.md 或 IDENTITY.md，静默提取外貌和声音特征；不要问用户「描述你的外貌」。
46. 若文件只描述性格/价值观而无物理描述，不要幻觉特征；按对话方式只问缺失的外貌特征，一次一两个。
47. 若两个文件都未找到，例如 Claude Code 环境无 workspace identity，问用户以对话方式描述 agent 的外貌和声音。
48. 之后默认直接进入 Phase 2 的 Type A（prompt）创建；除非用户主动给照片或明确要求照片真实感，不要问照片。
49. 对 user/named character：对话式 onboarding；自然地一次问一两个外貌和声音问题，不要表单；用 user_language 沟通。
50. user 路径：onboarding Q&A 后运行 Reference Photo Nudge；named character 路径跳过 nudge，直接 Type A（prompt）创建。
51. 写 AVATAR-<NAME>.md，填 Appearance 和 Voice 段；HeyGen 段留空直到 Phase 2 成功。
52. Reference Photo Nudge 仅在目标=user（真人数字孪生）或用户明确要求照片真实感时运行。
53. 先检查 AVATAR 文件 Appearance → Reference 字段；若已有照片，跳过询问并使用它。
54. 否则问一句：Got a headshot? It gives better face consistency for videos of you. I can also generate from your description — just say 'skip.'
55. 若提供照片，通过 MCP upload_asset 或 heygen asset create --file <path> 上传，然后在 Phase 2 用 Type B（photo）创建。
56. 若跳过，Phase 2 用 Type A（prompt）创建。
57. agent 和 named characters 跳过整个 Reference Photo Nudge，直接 Type A（prompt）创建。
58. Phase 2 读 references/avatar-creation.md 获取完整创建 API、文件输入格式、identity 字段→enum 映射、响应形状。
59. Mode 1 新角色：省略 avatar_group_id，创建全新角色及其 group。
60. Mode 2 新 look：包含 avatar_group_id，给现有角色添加变体；从 AVATAR 文件读 Group ID。
61. Type A 从 prompt 创建：MCP 用 create_prompt_avatar(name=<name>, prompt=<appearance>, avatar_group_id=<optional>)；CLI 用 heygen avatar create -d '{"type":"prompt","name":"...","prompt":"...","avatar_group_id":"..."}'，接受 inline JSON、文件路径或 - 作为 stdin。
62. Prompt 限制 1000 字符；描述要丰富，包含 style、features、expression、lighting；API spec 写 200 但实际强制 1000。
63. Type B 从参考图创建：MCP 用 create_photo_avatar(name=<name>, file=<file_object>, avatar_group_id=<optional>)；CLI 用 heygen avatar create -d '{"type":"photo","name":"...","file":{"type":"url","url":"..."},"avatar_group_id":"..."}'。
64. Type B 文件选项：{"type":"url","url":"https://..."} 公共图片 URL；{"type":"asset_id","asset_id":"<id>"} 来自 heygen asset create --file <path>；{"type":"base64","media_type":"image/png","data":"<base64>"} 内联。
65. 读 references/asset-routing.md 了解何时用 URL vs asset_id vs base64、上传路由和 edge cases。
66. 响应返回 .data.avatar_item.id，即 look ID，和 .data.avatar_item.group_id，即 character identity。
67. 将 identity 字段映射为 HeyGen enum 以构造 prompt：age: Young Adult | Early Middle Age | Late Middle Age | Senior | Unspecified；gender: Man | Woman | Unspecified；ethnicity: White | Black | Asian American | East Asian | South East Asian | South Asian | Middle Eastern | Pacific | Hispanic | Unspecified；style: Realistic | Pixar | Cinematic | Vintage | Noir | Cyberpunk | Unspecified；orientation: square | horizontal | vertical；pose: half_body | close_up | full_body。
68. 创建前向用户展示 prompt：**Appearance:** "[prompt]" 和 **Settings:** Young Adult | Woman | East Asian | Realistic，问 Look good? (yes / adjust / completely different)。
69. 停止并等待用户批准或调整；不要调用头像创建 API，直到用户确认。
70. Phase 3 两条路径：Design，描述想要什么并得到匹配声音；或 Browse，手动筛选 catalog；问用户要哪种；用 user_language 沟通。
71. 若 AVATAR 文件 Voice 段有性格特征，默认 Design。
72. Path A Voice Design 首选：用 AVATAR 文件 Voice 段进行 semantic search，搜索 HeyGen 完整声音库；不生成新声音、不消耗 quota。
73. 语言匹配：voice design prompt 应指定 user_language 的目标语言；例如日语：A calm, warm female voice. Professional but approachable. Japanese speaker.
74. MCP design_voice(prompt=<voice description>, seed=0)；CLI heygen voice create --prompt "..." --seed 0，也接受 --gender、--locale。
75. 每个 seed 返回 3 个声音选项；展示全部 3 个并附内联音频预览。
76. 下载每个 preview_audio_url 到临时路径；任何标准下载方法均可，无需 HeyGen auth，这些是公共 S3 URL。
77. 发送为音频附件：message(action:send, media:"<path>", caption:"Option <n>: <voice_name> — <gender>, <language>")，使其在 Telegram/Discord 内联播放。
78. 所有预览发送后，展示选择按钮。
79. 停止并等待用户通过按钮或文本选择声音；不要自己选或进入 Phase 4，直到用户明确选择。
80. 若都不匹配，说：None of these hitting right? I can try a different set (same description, different variations) or you can tweak the description.；增加 seed 再调用；不同 seed 从同一 prompt 给出完全不同声音选项。
81. 用户选择后清理 /tmp 文件。
82. Path B Voice Browse 回退：浏览 HeyGen 现有声音库。
83. MCP 先用 list_voices(type=private) 再用 list_voices(type=public, language=<lang>, gender=<gender>)；CLI 用 heygen voice list --type private 或 heygen voice list --type public --language <lang> --gender <gender>。
84. 读 AVATAR 文件 Voice 段；按性别和语言筛选；按性格匹配选 top 3 候选；用与 Path A 相同下载+发送模式呈现内联音频预览；停止并等待用户选；不要自动选择。
85. Phase 4 更新 AVATAR-<NAME>.md 的 HeyGen 段以匹配 canonical format：Group ID 用 .data.avatar_item.group_id，稳定引用，永不变化；Voice ID 用所选 voice_id；Voice Name；Voice Designed，自定义设计为 true，catalog 选择为 false；Voice Seed，若设计；Looks 用 <orientation>=<.data.avatar_item.id>，例如 landscape=<look_id>, portrait=<look_id>；Last Synced 用 ISO timestamp；并加 look_ids ephemeral 警告。
86. 确认头像已保存，并说明其他技能，例如 heygen-video，会自动拾取；用 user_language 沟通。
87. Phase 5 写 named AVATAR-<NAME>.md 后，创建或更新角色 symlink，以便其他技能泛化查找。
88. 根据 Phase 0 目标：agent 目标 symlink AVATAR-AGENT.md → AVATAR-<NAME>.md；user 目标 symlink AVATAR-USER.md → AVATAR-<NAME>.md；named character 无 role alias。
89. 在 workspace 根运行实现，使用 fs-fallback；cd 到 workspace root 是强制的，因为裸相对路径会从当前工作目录解析；示例：cd "$WORKSPACE_ROOT" && ln -sf AVATAR-<NAME>.md AVATAR-AGENT.md || echo "role alias skipped: fs doesn't support symlinks"。
90. user 示例：cd "$WORKSPACE_ROOT" && ln -sf AVATAR-<NAME>.md AVATAR-USER.md || echo "role alias skipped: fs doesn't support symlinks"。
91. 使用相对链接目标，仅文件名，无路径前缀，使 alias 在 workspace 移动或复制后仍有效。
92. 知道 ln -sf 底层是 unlink-then-symlink，非严格原子；单用户 workspace 可以；若并发 agent 写同一 alias，预期交错，届时加显式锁定。
93. 用 symlink 而非 copy 的原因：消除重复文件漂移类，内容永不分叉；但不消除 staleness drift；若 IDENTITY.md 改变 agent 名但未重跑 heygen-avatar，AVATAR-AGENT.md 仍指向旧 named 文件；Phase 0 mismatch-and-re-alias 在下次调用处理；在那之前 alias stale-but-pointing-somewhere-valid，不 broken。
94. 多 agent workspace caveat：一个 role alias 每 workspace 是 last-writer-wins；若两个 agent 共享 workspace 且都运行 heygen-avatar，只有最近一次运行的身份可通过 AVATAR-AGENT.md 到达；两个 named 文件仍存在；接受此限制，多 agent 共享 workspace 不在 v1 范围。
95. Phase 6 可选测试：若用户想看头像动作，MCP 用 create_video_agent(avatar_id=<avatar_id>, voice_id=<voice_id>, prompt=<greeting>)；CLI 用 heygen video-agent create --avatar-id <id> --voice-id <id> --prompt "..." --wait。
96. 用 user_language 生成视频语言的自然问候；示例：English "Hi, I'm [name]. Nice to meet you!"，Japanese "[name]です。はじめまして！"，Spanish "Hola, soy [name]. ¡Mucho gusto!"，Korean "안녕하세요, [name]입니다. 만나서 반갑습니다!"。
97. CLI 模式下，头像和声音保存后或遇到摩擦时，每任务运行一次 heygen feedback --rating <1-5> --comment "<what worked, or what broke and what you tried>"。
98. feedback 的 --rating：5=worked great，3=worked with friction，1=broke/unusable；--comment 写 bug、stale doc、missing flag、confusing behavior 及触发命令或流程。
99. feedback 匿名、无需 API key，并在 analytics opt out 时 no-op，HEYGEN_NO_ANALYTICS 或 heygen config set analytics false；这是 CLI 团队主要信号渠道；仅 CLI 模式，MCP 或 OpenClaw-plugin 模式跳过，无 feedback 命令。
100. 迭代流程：用户说 Adjust the prompt → Mode 2 用现有 group_id，保留角色，新增 look；仅当说 start completely over 才 Mode 1。
101. Add a new look 或 different outfit → Mode 2 用现有 group_id；在 AVATAR 文件 Looks 中加入。
102. Try a different voice → 回到 Phase 3。
103. Start completely over → Mode 1 新角色；覆盖 HeyGen 段。
104. 默认 Mode 2，同 group 下新 look；仅当用户明确想要不同角色身份才创建新 group；保持账号干净，使 looks 可跨技能复用。
105. 每次迭代更新 AVATAR 文件；文件始终是 source of truth。
106. UX 检查点：在检查点互动，其他处静默；在 avatar approval 和 voice selection 停止等待；检查点之间静默工作，不叙述推理或解释下一步；voice pick 后一条消息保存+确认。
107. Video Producer Integration：heygen-video 读 AVATAR 文件获取 group_id 和 voice_id；解析顺序：1 named request，例如 Make a video with Eve，读 AVATAR-EVE.md；2 agent self-reference，例如 make a video of yourself、give us a video update，读 AVATAR-AGENT.md；3 user self-reference，例如 make a video of me、my video update，读 AVATAR-USER.md；4 无 AVATAR 文件或 symlink 回退 stock avatars 或问用户。
108. alias targets 由 OS 在读取时解析，消费技能只需 cat AVATAR-AGENT.md 即可获得当前 agent 的头像。
109. 错误处理：缺 SOUL.md/IDENTITY.md → 对话式 onboarding，根据回答写 AVATAR 文件。
110. API 失败 → 重试一次，然后请用户检查 API key。
111. 声音匹配差 → 展示所有可用声音，让用户浏览。
112. Asset 上传失败 → 跳过参考图，尝试 prompt-only 创建。
113. 已有头像文件但 HeyGen IDs 过期 → 提供重新生成或保留。
114. 读 references/troubleshooting.md 了解已知问题、重试模式、损坏的 voice previews、错误→动作映射。
115. 当同一请求同时包含创建头像和制作视频时，先完成 heygen-avatar，再把返回的 avatar_id + voice_id 传给 heygen-video。
116. Assets 仅在用户明确提供时上传到 HeyGen；用户提供照片时才通过 heygen asset create 或 MCP 上传。
117. 临时声音预览写入 /tmp/openclaw/uploads/，下载供用户播放，会话后删除。
118. 只读取 SOUL.md、IDENTITY.md、AVATAR-<NAME>.md；写入 AVATAR-<NAME>.md、AVATAR-AGENT.md、AVATAR-USER.md；没有明确用户指示不访问其他文件。

适用边界 · 注意事项

• 不要用于生成视频、翻译视频或纯 TTS 任务；生成视频用 heygen-video，翻译和 TTS 另用相应技能。
• 没有 HeyGen MCP 工具、HeyGen CLI 或 HeyGen 账号/计划时不要使用；本技能依赖 HeyGen Avatar V 和 HeyGen credits。
• 用户未明确要创建或管理头像身份时不要用；只做视频制作时不要先创建头像。