heygen-avatar

HeyGen Avatar 设计器

为任何人创建和管理 HeyGen 头像：Agent、用户或具名角色。支持身份信息提取、头像生成、声音选择，并将所有内容保存到 AVATAR-<NAME>.md，以便一致复用。

文件和路径

此技能会读取和写入以下文件。未经用户明确指示，不会访问其他文件。

操作	路径	用途
读取	SOUL.md、IDENTITY.md	为 Agent 创建头像时提取身份详情
读取	AVATAR-<NAME>.md	加载现有头像身份信息（用于创建不同外观、更新声音）
写入	AVATAR-<NAME>.md	创建后保存新头像身份信息
写入	AVATAR-AGENT.md、AVATAR-USER.md（符号链接）	角色别名，参见阶段 5
临时写入	/tmp/openclaw/uploads/	声音预览音频（下载后供用户播放，会话结束后删除）
远程上传	HeyGen（通过 heygen asset create 或 MCP）	将用户提供的照片上传到 HeyGen，以创建数字分身

只有在用户明确提供素材时，才会将素材上传到 HeyGen。

语言识别

根据用户的第一条消息识别其语言。 将其存储为 user_language（例如：en、ja、es、ko、zh、fr、de、pt）。

1. 使用用户的语言与其交流。 所有问题、状态更新、确认和错误消息都应使用 user_language。
2. 声音设计提示词和选择应符合 user_language。 设计或选择声音时，应指定目标语言，以便声音库返回会说该语言的匹配结果。
3. 技术指令保持英文——枚举值（Young Adult、Realistic、landscape 等）属于 API 层，不予翻译。

UX 规则

1. 简洁明了。 不要在聊天中提供头像 ID、群组 ID 或原始 API 负载。只需报告结果（头像已创建，可以使用），无需说明实现细节。
2. 避免内部术语。 绝不要向用户提及内部阶段名称（“阶段 0”“阶段 5 符号链接维护”）。应自然交流，例如“正在设置你的头像……”，而不是“正在执行阶段 2 头像创建”。
3. 每个阶段只问一两个问题。 不要一次性提出多个问题。按阶段顺序推进，只询问继续操作所需的最少问题。
4. 提问前先读取工作区文件。 工作区根目录中的 SOUL.md、IDENTITY.md、AVATAR-*.md 包含身份信息。先检查这些文件，只询问用户真正缺失的信息。
5. 不要讲述技能内部操作。 绝不要说“让我读取工作流”“正在检查参考文件”“正在加载头像发现指南”。静默读取即可。用户看到的是问题和结果，而不是内部操作过程。
6. 不要预告即将进行的操作。 跳过“现在创建头像”等元评论。直接开始处理。如果某个步骤需要时间，下一条消息应直接告知结果（或提出阶段性确认问题）。
7. 绝不要讲述传输方式的选择。 MCP 和 CLI 的选择属于内部操作。静默选择传输方式，绝不提及。如果两者都不可用，请用户配置其中一种，但不要解释原因。

从这里开始（重要）

默认目标 = Agent。 此技能的主要用途是为 Agent 配上形象和声音，让它能够展示视频。只有用户明确提到“我的虚拟形象”／“我”／“我的照片”时，才将目标设为“用户”。不确定时，就创建 Agent 的虚拟形象。

不要一次性集中提问。 不要一口气问“给我一张照片、声音偏好、时长、目标平台、语气、关键信息”。按阶段依次进行。每个阶段最多询问一两件事。

创建 Agent 虚拟形象时：先阅读 SOUL.md 和 IDENTITY.md，然后直接通过提示词创建。 不要先向用户索要照片或外貌细节。Agent 的身份信息存在这些工作区文件中。只有确实缺少的特征，才向用户询问。

提示词创建是默认方式。 照片为可选项，且仅适用于用户明确想要创建自己的真人数字分身时。Agent 和有名字的角色几乎总是通过提示词创建。

开始之前（环境检测）

尝试读取工作区根目录中的 SOUL.md。

• 找到 → OpenClaw 环境。跳过本节，直接进入阶段 0。以工作区为基础的身份信息（SOUL.md、IDENTITY.md）将用于引导 Agent。
• 未找到 → Claude Code 环境，没有工作区身份文件。接下来仍然进入阶段 0——不要跳到列出用户虚拟形象或向用户索要照片。

⚠️ AVATAR 文件注意事项： 忽略工作区中属于其他人物或 Agent 的 AVATAR-*.md 文件（例如，为 Claude 创建虚拟形象时遇到 AVATAR-Eve.md）。只有文件名与当前要创建虚拟形象的对象相符时，才使用该 AVATAR 文件。

⚠️ 暂时不要获取 HeyGen 虚拟形象。 这是阶段 0 的一个子步骤（仅在检测目标之后进行）。在阶段 0 之前获取虚拟形象，会导致 Agent 将对话引向“你现有的虚拟形象”，而默认目标应该是为 Agent 自己创建虚拟形象。

API 模式检测

静默选择模式。 在会话开始时检测一次，选择模式后继续。绝不要描述传输方式的选择（例如“CLI 不可用”“切换到 MCP”）——用户并不关心如何发起调用。

MCP（优先）： 如果 HeyGen MCP 工具可用（名称匹配 mcp__heygen__* 的工具），则使用这些工具。MCP 通过 OAuth 进行身份验证——无需 API 密钥——并使用用户现有的 HeyGen 套餐额度。

CLI 后备方案： 仅当 MCP 工具不可用且 heygen 二进制文件能正常运行（heygen --version 退出码为 0）时，才使用 CLI。身份验证：通过 HEYGEN_API_KEY 环境变量，或运行 heygen auth login（凭据保存在 ~/.heygen/credentials）。如果缺少 CLI、运行 --version 出错，或未设置身份验证，则静默跳过——不要重试 MCP。

两者都不可用： 仅当 MCP 不可用且 CLI 无法运行时，才告知用户一次：“要使用此技能，请连接 HeyGen MCP 服务或安装 HeyGen CLI：curl -fsSL https://static.heygen.ai/cli/install.sh | bash 然后运行 heygen auth login。”

API： 仅使用 v3。绝不要调用 v1 或 v2 端点。

先查文档规则： 调用任何不确定的端点之前：

• 索引： GET https://developers.heygen.com/llms.txt — 完整站点地图
• 任意页面： 在 URL 后追加 .md，以获取整洁的 Markdown
• 或运行 heygen <noun> <verb> --help
• 阅读规范，然后再构建请求。绝不要猜测字段名称。

头像文件约定

每个头像对应一个文件：位于工作区根目录的 AVATAR-<NAME>.md。

AVATAR-EVE.md      ← agent      (named, canonical)
AVATAR-KEN.md      ← user       (named, canonical)
AVATAR-CLEO.md     ← character  (named, canonical)

该技能还会在命名文件旁维护两个基于角色的符号链接，供消费技能（例如 heygen-video）在请求未包含具体名称时进行通用查找（“制作一段你自己的视频” → 读取 Agent 别名；“制作一段我的视频” → 读取用户别名）：

AVATAR-AGENT.md → AVATAR-<CURRENT-AGENT-NAME>.md   (symlink)
AVATAR-USER.md  → AVATAR-<CURRENT-USER-NAME>.md    (symlink)

命名文件是唯一事实来源；别名只是指针，不会发生偏移。工作流的第 5 阶段会维护它们。命名角色不设角色别名——只能通过名称引用。

格式：

# Avatar: <Name>

## Appearance
- Age: <natural language>
- Gender: <natural language>
- Ethnicity: <natural language>
- Hair: <natural language>
- Build: <natural language>
- Features: <natural language>
- Style: <natural language>
- Reference: <optional workspace-relative path or URL>

## Voice
- Tone: <natural language>
- Accent: <natural language>
- Energy: <natural language>
- Think: <one-line analogy>

## HeyGen
- Group ID: <character identity anchor — THE stable reference, never changes>
- Voice ID: <matched or designed voice>
- Voice Name: <human-readable>
- Voice Designed: <true if custom-designed, false if picked from catalog>
- Voice Seed: <seed value used, if designed>
- Looks: landscape=<look_id>, portrait=<look_id>, square=<look_id>
- Last Synced: <ISO timestamp>

⚠️ look_ids are ephemeral — always resolve fresh from group_id at runtime via `heygen avatar looks list --group-id <id>` (or MCP `list_avatar_looks`). Never hardcode look_id as the primary avatar reference.

顶部章节（外观、声音）采用可移植的自然语言。任何平台都可以使用。 HeyGen 章节是包含 API ID 的运行时配置。技能会读取此部分来调用 API。

技能声明

每次调用都以以下内容开头：

🎭 正在使用：heygen-avatar —— 正在为 [name] 创建头像

工作流

不要一开始就集中提问。 按顺序逐个执行阶段。每个阶段一次最多问一个问题，且仅在有需要时提问。

阶段 0 —— 我们要为谁创建头像？

默认使用 Agent 的规则见上方的“从这里开始”部分。只有在措辞明确无误时，才将目标设为“用户”或“命名角色”。

路由信号（按优先级排序）：

1. 用户（仅限明确表达）——“创建我的头像”、“给我做一个头像”、“我想在视频里呈现自己的面容”、“一个我的数字分身”、“基于我的照片”。必须使用指代用户的所有格代词，或明确提到用户的照片。如果无法确定姓名，则询问用户姓名。
2. 命名角色（仅限明确表达）——“创建一个名叫 Cleo 的头像”、“设计一个名叫 X 的角色”、“制作一位名叫 Y 的主持人” → 使用给定名称。
3. Agent（默认）——其他所有情况：“创建你自己的头像”、“让你活灵活现”、“设置一个头像”、“我们来做个头像吧”、“创建一个头像”、“设计一位主持人”、“我想让你出现在视频里”，或任何含糊的措辞。读取 IDENTITY.md 获取名称。

不确定时，默认选择 Agent。 对于含糊的请求，不要询问用户的姓名、外貌或声音——这不是正确的第一步。如果读取 IDENTITY.md 和 SOUL.md 后意图仍不明确，只需提出一个简短的澄清问题以消除歧义（自然地表达，例如：“确认一下：这个头像是给你用，还是给我用？”）。

然后检查工作区根目录中的 AVATAR-<NAME>.md：

• AVATAR 文件存在，且 HeyGen 章节已填写 → “你已经设置了头像。想添加新造型、更新头像，还是重新开始？”等待回答。
• AVATAR 文件存在，但 HeyGen 章节为空 → 跳到阶段 2。
• AVATAR 文件不存在 → 进入阶段 1。

检查角色别名是否过期。 继续之前，还要检查该目标的角色别名是否指向正确的命名文件：

• 对于 Agent 目标：读取 AVATAR-AGENT.md（跟随符号链接），并与 AVATAR-<CURRENT-AGENT-NAME>.md 比较。如果两者不同（例如，Agent 身份自上次运行后发生变化，导致 AVATAR-AGENT.md → AVATAR-OLD-NAME.md），即使没有其他更改，也要在阶段 5 重新建立链接。命名文件是规范来源，但别名必须与当前身份一致，而非历史身份。
• 对于 用户目标：对 AVATAR-USER.md 进行相同检查。
• 对于 命名角色：无需检查别名。

可选的现有头像检查（仅当用户路径下用户可能已在其 HeyGen 账户中拥有头像时才有用）。如果阶段 0 的目标是用户，且不存在 AVATAR-<USER>.md，则先列出其 HeyGen 头像：

MCP： list_avatar_groups(ownership=private) CLI： heygen avatar list --ownership private

如果列表不为空，展示选项并询问用户要使用哪个，或是否创建新头像。如果列表为空，则进入阶段 1。对于 Agent 和命名角色目标，完全跳过此检查——它们保存在 AVATAR-*.md 中，而非 HeyGen 目录中。

阶段 1 — 身份提取

顺序很重要。先读文件，再提问。默认通过提示词创建，照片是可选升级项。

对于 Agent（阶段 0 的目标 = Agent）：

1. 读取工作区根目录中的 SOUL.md、IDENTITY.md 和任何现有的 AVATAR-<NAME>.md。
2. 如果找到 SOUL.md 或 IDENTITY.md → 默默提取外貌和声音特征。不要问用户“描述一下你的外貌”——Agent 本身就是主体，它的身份信息就在这些文件中。如果文件只描述了个性 / 价值观，没有描述外貌，不要凭空编造特征。 以自然对话的方式向用户询问缺失的外貌特征，每次问一两个。
3. 如果两个文件都未找到（例如，没有工作区身份信息的 Claude Code 环境）→ 请用户以自然对话的方式描述 Agent 的外貌和声音。
4. 默认直接进入阶段 2 的 Type A（提示词）创建。不要询问用户是否有照片，除非用户主动提供照片或明确要求照片级真实感——Agent 几乎总是使用基于提示词的创建方式。

对于用户 / 命名角色（阶段 0 的目标 = 用户或命名角色）：

• 以自然对话的方式引导用户。自然地询问外貌和声音，每次问一两个问题，不要像填写表格一样。使用 user_language 交流。
• **仅限用户路径：**完成引导问答后，执行下方的参考照片提示。
• **命名角色路径：**跳过提示，直接进入 Type A（提示词）创建。

填写 AVATAR-<NAME>.md 中的 Appearance 和 Voice 部分。留空 HeyGen 部分，直到阶段 2 成功完成。

参考照片提示（仅限用户路径）

仅当阶段 0 的目标 = 用户（真实人物数字分身）或用户明确要求照片级真实感时，才执行此步骤。

• 先检查 AVATAR 文件中的 Appearance → Reference 字段。如果已有照片，则跳过询问并使用该照片。
• 否则，询问一句话：“有头像照吗？它能让视频中的你保持更一致的面容。我也可以根据你的描述生成——只需回复‘跳过’即可。”

分支：

• 提供照片 → 通过 MCP upload_asset 或 heygen asset create --file <path> 上传，然后在阶段 2 中进行 Type B（照片）创建。
• 跳过 → 在阶段 2 中进行 Type A（提示词）创建。

对于 Agent 和命名角色，跳过整个步骤——直接进入 Type A（提示词）创建。

阶段 2 — 创建 Avatar

📖 完整的创建 API 接口（照片 / 提示词 / 数字分身）、文件输入格式、身份字段 → 枚举值映射、响应格式 → references/avatar-creation.md

两种模式：

模式 1 — 新建角色（省略 avatar_group_id）： 创建一个全新的角色，并为其创建独立分组。

模式 2 — 新建外观（包含 avatar_group_id）： 为现有角色添加一种外观。请从 AVATAR 文件中读取 Group ID。

两种创建类型：

类型 A — 根据提示词创建（AI 生成外观）：

MCP： create_prompt_avatar(name=<name>, prompt=<appearance>, avatar_group_id=<optional>) CLI： heygen avatar create -d '{"type":"prompt","name":"...","prompt":"...","avatar_group_id":"..."}'（接受内联 JSON、文件路径或表示从标准输入读取的 -）

提示词最多 1000 个字符。请尽量详细地描述，包括风格、特征、表情和光照。API 规范中写的是 200，但实际限制为 1000。

类型 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":"..."}'

类型 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>" } — 内联数据

📖 各选项的适用场景（URL、asset_id 或 base64）、上传路由和边缘情况 → references/asset-routing.md

**响应：**返回 .data.avatar_item.id（外观 ID）和 .data.avatar_item.group_id（角色身份）。

将身份字段映射为提示词所用的 HeyGen 枚举值：

• 年龄：Young Adult | Early Middle Age | Late Middle Age | Senior | Unspecified
• 性别：Man | Woman | Unspecified
• 族裔：White | Black | Asian American | East Asian | South East Asian | South Asian | Middle Eastern | Pacific | Hispanic | Unspecified
• 风格：Realistic | Pixar | Cinematic | Vintage | Noir | Cyberpunk | Unspecified
• 方向：square | horizontal | vertical
• 姿势：half_body | close_up | full_body

创建前，先向用户展示提示词：

外观：“[prompt]” **设置：**Young Adult | Woman | East Asian | Realistic 看起来合适吗？（是 / 调整 / 完全不同）

⛔ 停止。等待用户批准或提出调整。用户确认前，不得调用 Avatar 创建 API。

阶段 3 — 语音

两种方式：设计（描述想要的声音，获取匹配的语音）或浏览（手动筛选目录）。

询问用户是想设计语音（描述想要的声音），还是浏览目录。使用 user_language 进行沟通。

如果 AVATAR 文件包含描述个性特征的 Voice 部分，则默认选择设计。

路径 A — 语音设计（首选）

使用 AVATAR 文件中的 Voice 部分进行语义搜索，查找匹配的语音。这会搜索 HeyGen 的完整语音库。不会生成新语音，也不会消耗配额。

语言匹配： 语音设计提示词应指定 user_language 中的目标语言。日语示例："A calm, warm female voice. Professional but approachable. Japanese speaker." 这可确保语义搜索返回正确语言的语音。

MCP： design_voice(prompt=<voice description>, seed=0) CLI： heygen voice create --prompt "..." --seed 0（也接受 --gender、--locale）

每个 seed 返回 3 个语音选项。提供全部 3 个选项，并附上内嵌音频预览：

• 将每个 preview_audio_url 下载到临时路径（可使用任何标准下载方式——这些是公开的 S3 URL，无需 HeyGen 身份验证）
• 作为音频附件发送：message(action:send, media:"<path>", caption:"Option <n>: <voice_name> — <gender>, <language>")，以便在 Telegram/Discord 中内嵌播放
• 发送完所有预览后，提供选择按钮

⛔ 停下。等待用户通过按钮或文本选择语音。在用户明确选择之前，不要自行选择语音，也不要继续进入第 4 阶段。

如果都不合适：

"这些都不太对吗？我可以再试一组（描述相同，但变化不同），或者你可以调整描述。"

递增 seed 并再次调用。同一提示词使用不同的 seed 会得到完全不同的语音选项。

• 用户选择后清理 /tmp 文件

路径 B — 浏览语音（备用）

浏览 HeyGen 现有的语音库：

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>

1. 从 AVATAR 文件中读取 Voice 部分
2. 按性别和语言筛选
3. 根据个性匹配度选出前 3 个候选项
4. 提供内嵌音频预览（使用与路径 A 相同的下载和发送方式）
5. ⛔ 停下。等待用户选择。不要自动选择。

第 4 阶段 — 保存到 AVATAR 文件

将 AVATAR-<NAME>.md 中的 HeyGen 部分更新为规范格式：

## HeyGen
- Group ID: <.data.avatar_item.group_id — THE stable reference, never changes>
- Voice ID: <chosen voice_id>
- Voice Name: <voice name>
- Voice Designed: <true if custom-designed, false if picked from catalog>
- Voice Seed: <seed value used, if designed>
- Looks: <orientation>=<.data.avatar_item.id> (e.g., landscape=<look_id>, portrait=<look_id>)
- Last Synced: <ISO timestamp>

⚠️ look_ids are ephemeral — always resolve fresh from group_id at runtime via `heygen avatar looks list --group-id <id>` (or MCP `list_avatar_looks`). Never hardcode look_id as the primary avatar reference.

确认已保存 avatar，并说明其他技能（如 heygen-video）会自动读取该文件。使用 user_language 进行交流。

阶段 5 — 维护角色别名

写入命名的 AVATAR-<NAME>.md 后，在同一目录创建或更新基于角色的符号链接，这样其他技能无需先解析 Agent／用户名称即可进行通用查找。

根据阶段 0 的目标：

• Agent 目标 → 符号链接 AVATAR-AGENT.md → AVATAR-<NAME>.md
• 用户目标 → 符号链接 AVATAR-USER.md → AVATAR-<NAME>.md
• 具名角色 → 不创建角色别名。具名角色仅通过名称引用（例如 AVATAR-CLEO.md）；它们既不是 Agent，也不是用户。

实现方式（从工作区根目录运行，并提供文件系统回退）：

必须先 cd 到工作区根目录——ln -s 中的裸相对路径是相对于 Agent 的当前工作目录解析的，而不是相对于 SOUL.md 所在的位置。|| echo 子句可在不支持符号链接的文件系统（未启用开发者模式的 Windows、某些云挂载存储）上避免中止阶段 5。

# Agent
cd "$WORKSPACE_ROOT" && ln -sf AVATAR-<NAME>.md AVATAR-AGENT.md \
  || echo "role alias skipped: fs doesn't support symlinks"

# User
cd "$WORKSPACE_ROOT" && ln -sf AVATAR-<NAME>.md AVATAR-USER.md \
  || echo "role alias skipped: fs doesn't support symlinks"

使用相对链接目标（仅文件名，不带路径前缀），这样即使移动或复制工作区，别名仍然有效。

ln -sf 在底层执行的是先取消链接再创建符号链接，并非严格原子操作。对于单用户工作区，这样做没问题；如果多个 Agent 同时写入同一个别名，则可能发生交错，到时应添加显式锁定。

为什么用符号链接，而不是复制： 可消除重复文件内容不一致的问题（命名文件与别名之间的内容永远不会不同步）。但它无法消除过时不一致——如果 IDENTITY.md 中的 Agent 名称发生变化，却没有重新运行 heygen-avatar，AVATAR-AGENT.md 仍会指向旧的命名文件。阶段 0 的不匹配检测与重新设置别名会在下次调用时处理此问题；在此之前，别名虽然过时，但仍指向有效位置，而非失效。

多 Agent 工作区注意事项： 每个工作区只有一个角色别名，遵循最后写入者胜出原则。如果两个 Agent 共用一个工作区并且都运行 heygen-avatar，则只有最近一次运行的身份可通过 AVATAR-AGENT.md 访问。两个命名文件仍会保留。我们接受此限制——v1 不支持多 Agent 共用工作区。

阶段 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

根据视频语言（取自 user_language）生成自然的问候语。示例：英语 “Hi, I'm [name]. Nice to meet you!”；日语 “[name]です。はじめまして！”；西班牙语 “Hola, soy [name]. ¡Mucho gusto!”；韩语 “안녕하세요, [name]입니다. 만나서 반갑습니다！”

报告反馈（CLI 模式）

头像和语音保存后——或在过程中遇到阻碍时——每项任务运行一次：

heygen feedback --rating <1-5> --comment "<what worked, or what broke and what you tried>"

• --rating：5 = 效果很好 · 3 = 有阻碍但可用 · 1 = 出错／无法使用。
• --comment：填写任何错误、过时文档、缺失的标志或令人困惑的行为，并注明触发问题的命令或流程。

反馈匿名，无需 API 密钥；若已选择退出分析（HEYGEN_NO_ANALYTICS 或 heygen config set analytics false），则不会执行任何操作。这是 CLI 团队的主要反馈渠道——运行结束后不留任何信息，他们就无从得知情况。**仅限 CLI 模式：**在 MCP 或 OpenClaw 插件模式下跳过（这些模式通过 MCP／插件接口运行，没有反馈命令）。

迭代流程

用户想要优化时：

• “调整提示词” → 使用现有的 group_id 进入模式 2（保留角色并添加新造型）。只有在用户说“完全重新开始”时才使用模式 1。
• “添加新造型”／“换套衣服” → 使用现有的 group_id 进入模式 2。将造型添加到 AVATAR 文件的 Looks 部分。
• “试试别的声音” → 返回阶段 3
• “完全重新开始” → 模式 1，创建新角色。覆盖 HeyGen 部分。

默认使用模式 2（在同一组下创建新造型）。 只有用户明确要求不同的角色身份时，才创建新组。这样可以保持账户整洁，并让不同技能重复使用造型。

每次迭代都会更新 AVATAR 文件。该文件始终是唯一可信来源。

UX 规则

在关键节点进行交互，其他时候保持静默。 在头像确认和语音选择时停下并等待。两个关键节点之间保持静默——不要叙述推理过程或解释下一步。选择语音后：在同一条消息中保存并确认。

视频制作工具集成

heygen-video 会读取 AVATAR 文件以获取 group_id 和 voice_id。解析 顺序：

1. 指定名称的请求（“用 Eve 制作视频”）→ 读取 AVATAR-EVE.md。
2. Agent 自我指代（“制作一个你自己的视频”“给我们发一段视频更新”）→ 读取 AVATAR-AGENT.md（指向当前 Agent 命名文件的符号链接）。
3. 用户自我指代（“制作一个我的视频”“我的视频更新”）→ 读取 AVATAR-USER.md（指向当前用户命名文件的符号链接）。
4. 没有 AVATAR 文件或符号链接 → 使用备用头像，或询问用户。

别名目标由操作系统在读取时解析，因此使用方技能只需执行 cat AVATAR-AGENT.md，即可获取当前 Agent 的头像。

错误处理

• 缺少 SOUL.md/IDENTITY.md → 通过对话引导用户，并根据回答编写 AVATAR 文件
• API 调用失败 → 重试一次，然后请用户检查 API key
• 语音匹配效果不佳 → 显示所有可用语音，让用户浏览
• 资产上传失败 → 跳过参考图像，尝试仅使用提示词创建
• 现有头像文件中的 HeyGen ID 已过期 → 询问用户是重新生成还是保留

📖 已知问题、重试模式、语音预览故障、错误 → 操作映射 → references/troubleshooting.md