用 HeyGen v3 Video Agent…

当需要通过 HeyGen 生成主持人出镜视频（个性化视频、讲解、教程、产品演示等）时，按 v3 Video Agent 流水线从想法到成片并交付。

适用场景

解决思路

1. 手动检查更新时运行 `"${SKILL_DIR}/scripts/update-check.sh"`；该脚本仅按需，不要在技能调用时自动执行。
2. 以视频制作人身份引导用户从想法到成片，不要只做表单或 CLI wrapper。
3. 若打算直接驱动 HeyGen（调用 `api.heygen.com` 的 curl，或使用已弃用的 `POST /v1/video.generate`、`POST /v2/video/generate`、`GET /v2/avatars`、`GET /v1/avatar.list`），停止；改走 MCP、OpenClaw plugin 或 `heygen` CLI 的本 pipeline；只用 v3，绝不调 v1/v2。
4. 文件与路径：读 `AVATAR-<NAME>.md` 加载头像身份（group_id、voice_id）；读 `AVATAR-AGENT.md`、`AVATAR-USER.md` 角色符号链接；写 `heygen-video-log.jsonl`，每生成一个视频追加一行 JSON；临时写 `/tmp/openclaw/uploads/` 用于语音预览音频（用户播放后删除）；通过 `heygen asset create` 或 MCP 远程上传用户文件到 HeyGen 作为 B-roll/reference；头像创建、写 AVATAR 文件、维护角色符号链接交给 `heygen-avatar`，本技能只读 AVATAR 文件。
5. UX：保持简洁，聊天中不出现 video IDs、session IDs、原始 API payload，只报告视频链接、缩略图等结果。
6. UX：不对用户提内部 pipeline 阶段名（Frame Check、Prompt Craft、Pre-Submit Gate、Framing Correction），用自然语言，例如“我来调整横屏构图”。
7. UX：静默轮询：后台进程或子代理轮询视频完成，不要重复发“Checking status…”；仅在视频就绪交付时说话，或超过 5 分钟给一次“比平时久”的更新。
8. UX：干净交付：视频完成发送视频文件/链接和一行摘要（时长、所用头像），不要 dump 每个 API 字段。
9. UX：跨技能不要批量问：同时触发 heygen-avatar 和 heygen-video 时顺序运行；先完成 heygen-avatar（身份→头像就绪），再开始 heygen-video Discovery；不要预先发覆盖两个技能的合并问卷。
10. UX：先读工作区文件再问：检查根目录 `AVATAR-<NAME>.md` 等已有头像状态，只问真正缺失项。
11. UX：不叙述技能内部：不说“让我读头像工作流”“检查参考文件”“加载 prompt-craft 指南”，静默读取。
12. UX：不预告即将做什么：跳过“现在创建视频”“让我调用 API”等元评论；直接做；如需说话 <10 词。
13. UX：不叙述传输选择：MCP vs CLI vs OpenClaw plugin 是内部细节；会话开始静默选择，之后不提，也不说“CLI 坏了，切到 MCP”。
14. 语言：从首条消息检测用户语言存 `user_language`；所有提问、状态更新、确认、错误消息都用 `user_language`。
15. 语言：脚本和旁白用 `user_language` 生成，除非用户明确要求其他语言。
16. 语言：技术指令保持英文：Frame Check corrections、motion verbs、style blocks、script framing directive 是 API 级指令，Video Agent 用英文解释，绝不翻译。
17. 语言：Discovery 第 10 项 Language 自动填 `user_language`，用户可覆盖为不同视频语言。
18. 语言：语音选择必须匹配视频语言；按 `language` 参数过滤语音，并在 API 调用设置 `voice_settings.locale`。
19. API 模式检测：会话开始选一种 transport，不混用、不中途切换、不叙述。检测顺序：OpenClaw plugin 模式：若在 OpenClaw 内且 `video_generate` 暴露 `heygen/video_agent_v3` 模型（用户安装 @heygen/openclaw-plugin-heygen），优先 `video_generate({ model: "heygen/video_agent_v3", ... })` 生成；插件处理 auth（`HEYGEN_API_KEY`）、session creation、polling、three-tier backoff、error surfacing；头像发现、语音列表、头像创建仍走 MCP 或 CLI，仅最终 video-generate 走 `video_generate`；Frame Check 仍在提交前运行。
20. API 模式检测：CLI 模式（API-key override）：若环境有 `HEYGEN_API_KEY` 且 `heygen --version` 退出 0，用 CLI；API-key 存在是明确直连 API 信号，短路 MCP 检测，不问问题。
21. API 模式检测：MCP 模式：未设 `HEYGEN_API_KEY` 且工具集中可见 HeyGen MCP 工具（匹配 `mcp__heygen__*`）；OAuth 认证，使用现有 plan credits。
22. API 模式检测：CLI 模式（fallback）：MCP 工具不可用且 `heygen --version` 退出 0；认证用 `heygen auth login`（持久化到 `~/.heygen/credentials`）。
23. API 模式检测：两者皆无：一次告知用户：`To use this skill, connect the HeyGen MCP server or install the HeyGen CLI: curl -fsSL https://static.heygen.ai/cli/install.sh | bash then heygen auth login`。
24. 硬规则：绝不调用 `curl api.heygen.com/...`。
25. 硬规则：OpenClaw plugin 模式生成步骤只用 `video_generate`；插件可用时绝不用 `heygen ...` CLI 做 generate；avatar/voice discovery 仍用 MCP 或 CLI。
26. 硬规则：MCP 模式只用 `mcp__heygen__*` 工具；绝不运行 `heygen ...` CLI；MCP 工具名就是 API。
27. 硬规则：CLI 模式只用 `heygen ...` 命令；运行 `heygen <noun> <verb> --help` 发现参数。
28. 硬规则：绝不跨界；操作块中只读当前模式列；当前模式未暴露某功能时告知用户，不切换 transport。
29. OpenClaw plugin-mode generate call：使用 `await video_generate({ model: "heygen/video_agent_v3", prompt: scriptWithFrameCheckNotes, aspectRatio: "16:9" 或 "9:16", providerOptions: { avatar_id, voice_id, style_id, callback_url, callback_id } });`；插件安装 `openclaw plugins install clawhub:@heygen/openclaw-plugin-heygen`；插件文档 https://github.com/heygen-com/openclaw-plugin-heygen。
30. MCP tool names（仅 MCP 模式）：`create_video_agent`、`get_video_agent_session`、`get_video`、`list_avatar_groups`、`list_avatar_looks`、`get_avatar_look`、`create_photo_avatar`、`create_prompt_avatar`、`create_digital_twin`、`list_voices`、`design_voice`、`create_speech`、`list_video_agent_styles`、`create_video_translation`。
31. CLI command groups（仅 CLI 模式）：`heygen video-agent {create,get,send,stop,styles,resources,videos}`、`heygen video {get,list,download,delete}`、`heygen avatar {list,get,consent,create,looks}`（含 `heygen avatar looks {list,get,update}`）、`heygen voice {list,create,speech}`、`heygen video-translate {create,get,languages}`、`heygen lipsync {create,get}`、`heygen asset create`、`heygen user me get`、`heygen auth {login,logout,status}`；每个子命令支持 `--help`；运行 `heygen --help` 看完整 noun 列表。
32. 不要查找 API endpoints；没有 `api-reference.md` lookup 步骤；MCP 用工具名，CLI 用 `heygen ... --help`；若在搜 REST endpoint，停止，说明处于错误心智模型。
33. CLI 输出：stdout JSON，stderr `{error:{code,message,hint}}` envelope，退出码 `0` ok · `1` API · `2` usage · `3` auth · `4` timeout；见 references/troubleshooting.md；创建命令加 `--wait` 阻塞完成，而非手写 poll loop。
34. Mode Detection：Vague idea（“make a video about X”）→ Full Producer，从 Discovery 开始。
35. Mode Detection：有 written prompt → Enhanced Prompt，从 Prompt Craft 开始。
36. Mode Detection：“Just generate”/跳过问题 → Quick Shot，从 Generate 开始。
37. Mode Detection：“Interactive”/与 agent 迭代 → Interactive Session，从 Generate 开始（实验性）。
38. 语言无关路由：按用户意图匹配，不按字面关键词，不管输入语言。
39. Quick Shot avatar 规则：无 AVATAR 文件则省略 `avatar_id`，让 Video Agent 自动选择；有 AVATAR 文件则使用它，且 Frame Check 仍运行。
40. Dry-Run 模式：用户说 dry run/preview，跑完整 pipeline，但在 Generate 展示 creative preview，不调用 API。
41. 非英语视频：同样 pipeline；脚本用视频语言；style blocks、motion verbs、frame check corrections 保持英文。
42. 默认 Full Producer；宁可问一个聪明问题，也不生成平庸视频。
43. First Look 首轮头像检查：在会话第一个视频请求 Discovery 前运行一次。
44. 检查 workspace root 的 `AVATAR-*.md`；目录也可能含角色符号链接 `AVATAR-AGENT.md`、`AVATAR-USER.md`，由 heygen-avatar Phase 5 维护；扫描时按 resolved target 去重，避免同一头像加载两次。
45. 找到 AVATAR：读取文件，从 HeyGen 段提取 `Group ID` 和 `Voice ID`，预加载为 Discovery 默认；实际 `avatar_id`（look_id）在 Frame Check 从 group_id 重新解析；绝不直接使用存储的 look_id。
46. 未找到 AVATAR：在视频创建前运行 `heygen-avatar` skill 创建头像；告诉用户会先设置头像以保证视频一致外观，约一分钟；用 `user_language` 沟通；heygen-avatar 完成并写 AVATAR 文件后返回继续 Discovery，预加载新头像。
47. Avatar readiness gate（阻塞）：加载头像后（现有 AVATAR 文件或新建），视频生成前验证就绪；调用 `list_avatar_looks(group_id=<group_id>)`（CLI: `heygen avatar looks list --group-id <group_id>`）确认 `preview_image_url` 非 null；若 null，每 10s 轮询最多 5min；此检查通过前不要进入 Discovery；未就绪头像提交会静默失败。
48. Quick Shot 例外：用户明确说 skip avatar/use stock/just generate，跳过此步，不用头像继续。
49. Discovery：访谈用户，对话式，跳过已回答项；不要一次批量问全部；一次问一到两项；大多数请求已有上下文可推断；只问真正缺失。
50. Discovery 收集 10 项：Purpose、Audience、Duration、Tone、Distribution（landscape/portrait）、Assets、Key message、Visual style、Avatar、Language（从 `user_language` 自动检测，确认视频语言是否不同于聊天语言）；驱动语音选择（`language` filter）、脚本语言、`voice_settings.locale`。
51. Assets：每条资产两种路径——Path A Contextualize：读取/分析，把信息烘入脚本，用于参考材料、授权墙内容；Path B Attach：通过 `heygen asset create --file <path>` 上传到 HeyGen（或在 video-agent create 中包含为 `files[]` 条目），用于观众应看到的视觉；A+B Both：为脚本总结并附加原件；完整路由矩阵和上传示例见 references/asset-routing.md。
52. Assets 关键规则：HTML URLs 不能放 `files[]`（Video Agent 拒绝 `text/html`）；网页总是 Path A。
53. Assets 关键规则：优先 download → upload → `asset_id`，而不是 `files[]{url}`（CDN/WAF 常阻止 HeyGen）。
54. Assets 关键规则：URL 不可访问时告知用户；绝不从未访问来源编造内容。
55. 多主题拆分：多个不同主题时建议分开视频。
56. Style Selection：两种方法可单独或组合。API Styles（`style_id`）：MCP `list_video_agent_styles(tag=<tag>, limit=20)`，按 tag 过滤，返回 style_id、name、thumbnail_url、preview_video_url、tags、aspect_ratio；CLI `heygen video-agent styles list --tag cinematic --limit 10`；Tags：`cinematic`、`retro-tech`、`iconic-artist`、`pop-culture`、`handmade`、`print`；把 `style_id`/`--style-id` 传给 video-agent create。
57. 选择风格前向用户展示缩略图+预览视频；按 tag 浏览，展示 3-5 个选项带预览，让用户选；若风格有固定 `aspect_ratio`，匹配 orientation。
58. 设置 `style_id` 后，prompt 的 Visual Style Block 可选；style 控制 scene layout、transitions、pacing、aesthetic；仍可加具体 media type guidance 或 color overrides。
59. Prompt Styles：通过提示词文本完全手动控制；选一个风格，复制 STYLE block，粘贴到 prompt 末尾（在脚本内容之后）。
60. 选风格：先匹配情绪，再匹配内容；问“What should the viewer FEEL?”。
61. Style blocks 保持英文，不管视频内容语言；它们是给 Video Agent 渲染引擎的技术指令，不是观众可见文本。
62. Mood-to-Style Guide：Personal/intimate→Soft Signal、Quiet Drama；Natural/earthy→Warm Grain、Earth Pulse；Nostalgic/historical→Heritage Reel；Data-driven/analytical→Swiss Pulse、Digital Grid；Elegant/premium→Velvet Standard、Geometric Bold；Cultural/global→Silk Route、Folk Frequency；Investigative/serious→Contact Sheet、Shadow Cut；Fun/lighthearted→Play Mode、Carnival Surge；Philosophical/abstract→Dream State；Punk/grassroots/raw→Deconstructed；Hype/loud/high-energy→Maximalist Type；Tech-forward/futuristic→Data Drift；Breaking/urgent→Red Wire。
63. Quick Reference 20 styles：1 Soft Signal 亲密温暖，用于个人故事、健康；2 Warm Grain 有机友好，用于环境、可持续；3 Quiet Drama 人文沉思，用于人物、传记；4 Heritage Reel 怀旧复古，用于历史、回顾；5 Silk Route 流动神秘，用于全球事务、跨文化；6 Swiss Pulse 临床精确，用于数据密集、分析；7 Geometric Bold 极简优雅，用于生活方式、视觉散文；8 Velvet Standard 高端永恒，用于奢侈品、投资者更新；9 Digital Grid 系统技术，用于基础设施、工程；10 Contact Sheet 编辑调查，用于新闻、深度报道；11 Folk Frequency 文化鲜明，用于节日、美食、传统；12 Earth Pulse 扎根社区，用于社区、草根；13 Dream State 超现实诗意，用于专栏、哲学；14 Play Mode 俏皮不敬，用于娱乐、流行文化；15 Carnival Surge 欢庆狂喜，用于里程碑、炒作；16 Shadow Cut 暗黑电影感，用于曝光、调查；17 Deconstructed 工业原始，用于科技新闻、朋克能量；18 Maximalist Type 响亮动感，用于重大公告、发布；19 Data Drift 未来沉浸，用于 AI/科技、创新；20 Red Wire 紧急即时，用于突发新闻、危机。
64. Production Performance（40+ 视频）：1 Deconstructed 所有主题最可靠；2 Swiss Pulse 最适合数据密集内容；3 Digital Grid 适合科技主题；4 Geometric Bold 优雅多用途；5 Maximalist Type 高能量，少用。
65. Copy-Paste Style Blocks：SOFT SIGNAL (Sagmeister)：暖琥珀/奶油、灰玫瑰、鼠尾草绿；手写风格文字；近景构图；慢速漂移和浮动；柔和溶解与暖光漏。
66. Copy-Paste Style Blocks：WARM GRAIN (Eksell)：大地色——赭石、森林绿、陶土、奶油；有机圆润构图；16mm 胶片颗粒；圆角无衬线；轻柔擦除和软切。
67. Copy-Paste Style Blocks：QUIET DRAMA (Ray)：柔和暖色——深褐、深棕、柔金；肖像构图；干净衬线；强单源对比；慢速淡出到黑。
68. Copy-Paste Style Blocks：HERITAGE REEL (Cassandre)：褪色金、酒红、海军蓝、深褐水洗；优雅居中衬线；暗角与老化胶片颗粒；圈入圈出转场。
69. Copy-Paste Style Blocks：SILK ROUTE (Abedini)：珠宝色——深青、酒红、金、青金石蓝；分层构图，所有景深活跃；优雅字距；流动溶解和平滑形变。
70. Copy-Paste Style Blocks：SWISS PULSE (Müller-Brockmann)：黑白+电蓝 #0066FF；网格锁定；Helvetica Bold；动画计数器；对角线强调；网格擦除转场。
71. Copy-Paste Style Blocks：GEOMETRIC BOLD (Tanaka)：每帧最多 3 个平色；60% 负空间；粗体字作为主元素；单焦点；随拍干净切换。
72. Copy-Paste Style Blocks：VELVET STANDARD (Vignelli)：黑、白、一个强调色金 #c9a84c；细全大写、宽字距；大量负空间；慢速优雅交叉溶解。
73. Copy-Paste Style Blocks：DIGITAL GRID (Crouwel)：等宽字体；深色 #0a0a0a 配青色 #00E5FF、琥珀 #FFB300；像素网格叠加；终端美学；干净擦除转场。
74. Copy-Paste Style Blocks：CONTACT SHEET (Brodovitch)：高对比黑白，低饱和强调色；照片编辑式构图；粗无衬线注释；原始颗粒；随拍硬切；快速缩放。
75. Copy-Paste Style Blocks：FOLK FREQUENCY (Terrazas)：鲜明民俗色——亮粉、钴蓝、太阳黄、翡翠；粗圆字体；民俗艺术节奏；丰富手工纹理；节庆节奏彩色擦除。
76. Copy-Paste Style Blocks：EARTH PULSE (Ghariokwu)：暖饱和——焦橙、深绿、浓黄；粗表现字体；宽社区构图；随拍节奏切；冻结帧。
77. Copy-Paste Style Blocks：DREAM STATE (Tomaszewski)：柔和调色板+一个超现实强调色；细优雅浮动字体；柔边、大气雾；慢速形变溶解——绝不用硬切。
78. Copy-Paste Style Blocks：PLAY MODE (Ahn Sang-soo)：电蓝、亮粉、青柠绿；弹跳弹簧物理；超大倾斜文字；记分卡、XP 条；流行切、弹跳效果。
79. Copy-Paste Style Blocks：CARNIVAL SURGE (Lins)：最大色彩——亮粉 #FF1493、黄 #FFE000、青 #00CED1；拼贴分层；文字巨大且倾斜；彩纸爆发；猛切、闪帧。
80. Copy-Paste Style Blocks：SHADOW CUT (Hillmann)：深黑、冷灰+血红强调；尖锐棱角文字；重阴影；慢速爬行推近；硬切到黑；黑色电影张力。
81. Copy-Paste Style Blocks：DECONSTRUCTED (Brody)：深灰 #1a1a1a、锈橙 #D4501E；文字倾斜、重叠；粗粝纹理、扫描线故障；猛切带闪帧。
82. Copy-Paste Style Blocks：MAXIMALIST TYPE (Scher)：红、黄、黑、白——最大对比；文字就是视觉；不同尺度重叠，占 50-80% 画面；动感一切；猛切、闪帧。
83. Copy-Paste Style Blocks：DATA DRIFT (Anadol)：虹彩——紫 #7c3aed、青 #06b6d4、深黑；流体形变构图；细未来字体；液体溶解；粒子聚合成数字。
84. Copy-Paste Style Blocks：RED WIRE (Tartakover)：红、黑、白、紧急黄；粗压缩全大写；分屏、滚动条、时间戳；急切、闪帧；零喘息空间。
85. When to use which：用户无强视觉偏好→浏览 API styles，选一个；用户要特定品牌色/字体/运动→prompt style；用户要策展外观+特定媒体类型→`style_id` + 选择性 prompt additions。
86. Avatar：完整头像发现流程、创建 API、语音选择见 references/avatar-discovery.md。
87. AVATAR 文件解析（任何外部头像 lookup 前运行）：请求暗示特定主体时，先尝试 workspace root 匹配 AVATAR 文件。Named subject→`AVATAR-<NAME>.md`；Agent self-reference→`AVATAR-AGENT.md`；User self-reference→`AVATAR-USER.md`；无主体→跳过，在步骤 1 问。`AVATAR-AGENT.md` 和 `AVATAR-USER.md` 是角色符号链接，读取时解析到当前 agent/user 的命名 AVATAR 文件；读取后当普通 AVATAR 文件。若 AVATAR 文件存在且有 HeyGen 段，提取 `group_id` + `voice_id` 并继续 Frame Check；跳过其余发现流程。
88. Discovery flow（无 AVATAR 文件适用）：问“Visible presenter or voice-over only?”；若 voice-over→无 `avatar_id`，在 prompt 写 state；若 presenter→先查私有头像，再公共（group-first browsing）；始终展示预览图，不仅列名字；头像确定后确认语音偏好。
89. 关键规则：设置 `avatar_id` 时，不要在 prompt 描述头像外观；说“the selected presenter”。这是头像不匹配第一原因。
90. Script 结构按类型：Product Demo Hook→Problem→Solution→CTA；Explainer Context→Core concept→Takeaway；Tutorial What we'll build→Steps→Recap；Sales Pitch Pain→Vision→Product→CTA；Announcement Hook→What changed→Why it matters→Next。脚本语言用视频语言；script framing directive 保持英文。只写内容结构，不要指定每 scene 时长，让 Video Agent 自然 pacing。
91. Critical On-Screen Text：提取每个字面屏幕元素（numbers、quotes、handles、URLs、CTAs）到 `CRITICAL ON-SCREEN TEXT` block；否则 Video Agent 会总结/改写。
92. Script Framing（CRITICAL）：Video Agent 把脚本当概念传达，不是逐字演讲；始终在 prompt 加 directive：“This script is a concept and theme to convey — not a verbatim transcript. You have full creative freedom to expand, elaborate, add examples, and fill the duration naturally. Do not pad with silence or pauses.”；否则会用死气凑时长。
93. Voice Rules：为耳朵写；短句；主动语态；缩略形式可以。
94. Present the Script：向用户展示完整脚本、词数、估计时长；Prompt Craft 前获得批准。
95. Prompt Craft：把脚本转成优化 Video Agent prompt。Construction Rules：1 Narrator framing：有 `avatar_id` 时“The selected presenter [explains]...”；无时描述 desired presenter 或“Voice-over narration only.” 2 Duration signal：在 prompt 陈述目标时长。3 Script freedom directive：始终包含 Script 的 framing directive。4 Asset anchoring：具体，如“Use the attached screenshot as B-roll when discussing features.” 5 Tone calibration：具体词，“confident and conversational”/“energetic, like a tech YouTuber.” 6 One topic：明确陈述。7 Style block at end：内容/脚本先，所有风格指令（颜色、媒体类型、运动偏好）作为 block 堆在 prompt 底部。8 Language separation：脚本内容和旁白用视频语言；所有技术指令——script framing directive、style block、media type guidance、motion verbs（SLAMS、CASCADE 等）、frame check corrections——保持英文；Video Agent 内部工具响应英文命令。
96. Prompt Approach：≤60s 对话式→Natural Flow（脚本+语气+时长，无 scene labels）；>60s、data-heavy、precision→Scene-by-Scene（每 scene 有 scene labels 带 visual type + VO）。
97. Visual Style Block：每个 prompt 应以 style block 结束；否则视觉逐 scene 不一致。默认 catchall（HeyGen 团队，用户无强偏好时）：“Use minimal, clean styled visuals. Blue, black, and white as main colors. Leverage motion graphics as B-rolls and A-roll overlays. Use AI videos when necessary. When real-world footage is needed, use Stock Media. Include an intro sequence, outro sequence, and chapter breaks using Motion Graphics.” 品牌特定：包含 hex codes（`#1E40AF`）、font families（`Inter`）、每种 scene type 偏好哪些 media types。Style presets 见 references/official-prompt-guide.md。
98. Media Type Selection：Video Agent 支持三种；明确指导否则可能猜错。Data/stats/brand elements/diagrams→Motion Graphics（动画文字、图表、图标）；Abstract concepts/custom scenarios→AI-Generated（stock 覆盖不了的图像/视频）；Real environments/human emotions→Stock Media（股票库真实素材）。在 prompt 明确：“Use motion graphics for the statistics, stock footage for the office scene, AI-generated visuals for the futuristic concept.” 完整矩阵见 references/prompt-craft.md；20 named visual styles 见 references/prompt-styles.md；motion vocabulary 和 B-roll 见 references/motion-vocabulary.md。
99. Orientation：YouTube/web/LinkedIn→`"landscape"`；TikTok/Reels/Shorts→`"portrait"`；默认→`"landscape"`。
100. Frame Check：设置 `avatar_id` 时自动运行，在 Generate 前；向 Video Agent prompt 追加 correction notes；不生成图像、不创建新 look。
101. Frame Check SUBAGENT RULE：Frame Check 必须在 main session 运行；构建完整、已修正 prompt，FRAMING NOTE/BACKGROUND NOTE 已嵌入，然后 spawn subagent 用 finished payload；Subagent 只 submit、poll、deliver。
102. Avatar ID Resolution（总是先运行）：绝不信存储的 `look_id`——looks 临时且会删除；总是从 `group_id` 重新解析。MCP：`list_avatar_looks(group_id=<group_id>)` 返回 group 所有 looks。CLI：`heygen avatar looks list --group-id <group_id> --limit 20`。从响应选匹配目标 orientation 的 look，用第一个匹配。若 group 无 looks，告知用户。规则：AVATAR 文件只存 `group_id`，运行时解析 `look_id`。
103. Frame Check Steps：1 获取 avatar look metadata：`get_avatar_look(look_id=<avatar_id>)`（CLI: `heygen avatar looks get <avatar_id>`）→提取 `avatar_type`、`preview_image_url`、`image_width`、`image_height`。2 确定 orientation：width > height = landscape，height > width = portrait，width == height = square。fetch 失败=assume portrait。3 确定 background：`photo_avatar`→Video Agent 处理环境；`studio_avatar`→检查 transparent/solid/empty；`digital_twin`→always has background。4 把适当 correction note(s) 追加到 Video Agent prompt 末尾；就这样，无图像生成、无新 looks。
104. Correction Matrix：`photo_avatar` 匹配→无；`photo_avatar` 不匹配或 square→Framing note；`studio_avatar` 匹配且有背景→无；`studio_avatar` 匹配且无背景→Background note；`studio_avatar` 不匹配或 square 且有背景→Framing note；`studio_avatar` 不匹配或 square 且无背景→Framing note + Background note；`digital_twin` 匹配且有背景→无；`digital_twin` 不匹配或 square 且有背景→Framing note。
105. Framing Note：portrait/square avatar→landscape video 使用原文指定文本：`FRAMING NOTE: The selected avatar image is in {source} orientation but this video is landscape (16:9). Frame the presenter from the chest up, centered in the landscape canvas. Use AI Image tool to generative fill to extend the scene horizontally with a complementary background environment that matches the video's tone (studio, office, or contextually appropriate setting). Do NOT add black bars or pillarboxing. The avatar should feel natural in the 16:9 frame.`
106. Framing Note：landscape/square avatar→portrait video 使用原文指定文本：`FRAMING NOTE: The selected avatar image is in {source} orientation but this video is portrait (9:16). Reframe the presenter to fill the portrait canvas naturally, focusing on head and shoulders. Use AI Image tool to generative fill to extend vertically if needed. Do NOT add letterboxing. The avatar should fill the portrait frame comfortably.`
107. Background Note（仅 studio_avatar 且无背景）：追加 `BACKGROUND NOTE: The selected avatar has no background or a transparent backdrop. Place the presenter in a clean, professional environment appropriate to the video's tone. For business/tech content: modern studio with soft lighting and subtle depth. For casual content: bright, minimal space with natural light. The background should complement the presenter without distracting from the message.` 完整模板见 references/frame-check.md。
108. Generate Pre-Submit Gate：Frame Check：若 `avatar_id` 设置，确保 Frame Check 已运行且 correction notes 已追加。Narrator framing check：若 `avatar_id` 设置，prompt 不得描述 avatar 外观；用“the selected presenter”。Dry-run：展示 creative preview（一行方向→scenes with tone/visual cues→“say go or tell me what to change”），等“go”。Full Producer：用户已批准脚本，继续。Quick Shot：立即生成。
109. Submit Step 1：运行 Frame Check（若 `avatar_id` 设置）—仅 main session；提交前运行，构建 corrected prompt，FRAMING NOTE 或 BACKGROUND NOTE 已追加。
110. Submit Step 2：在 main session 构建完整 payload；spawn subagent 前组装全部参数：`--prompt` 已嵌入 Frame Check notes 的 corrected prompt；`--avatar-id` 从 group_id 解析的 look_id；`--voice-id` 确认的 voice_id；`--style-id` 可选；`--orientation` `landscape` 或 `portrait`。此 payload 是给 subagent 的 handoff；subagent 收到 finished args，不修改 prompt，不重跑 Frame Check，不查 avatar IDs。
111. Submit Step 3：Subagent spawn pattern（批量或非阻塞生成）：生成多个视频或想非阻塞轮询时，每个视频 spawn 一个 subagent 带 finished args；Subagent 只 submit + poll + deliver；所有创意决策、Frame Check、prompt 构建在主 session 在 spawn 前完成。BATCH RULE：并行生成 N 个视频，subagents 分批 2–3 max；同时提交太多导致队列拥塞，全部卡 `thinking` 15+ min；提交 batch 1，等完成，再提交 batch 2。
112. Submit Step 4：提交。MCP：`create_video_agent(prompt=<prompt>, avatar_id=<look_id>, voice_id=<voice_id>, style_id=<optional>, orientation=<orientation>)`。CLI：`heygen video-agent create`，加 `--wait --timeout 45m` 阻塞完成，或省略 `--wait` 手动 poll；总是把 `--wait` 与 `--timeout 45m` 配对——CLI 默认 20m，但 Video Agent 常 20-45m，默认会中途超时。示例命令 `heygen video-agent create --prompt "..." --avatar-id "..." --voice-id "..." --orientation landscape --wait --timeout 45m`。CLI 在提交后 stdout 返回 JSON `{"data": {"video_id": "...", "session_id": "..."}}`；加 `--wait` 阻塞到完成并输出最终 status object；不加 `--wait` 立即返回，用 `heygen video-agent get <id>` poll。
113. 总是立即捕获 `session_id`；Session URL：`https://app.heygen.com/video-agent/{session_id}`。若丢失，可通过 `heygen video-agent list` 恢复（items 含 `session_id`、`created_at`、`title`），但仍应优先立即捕获。
114. Polling：MCP `get_video_agent_session(session_id=<session_id>)` 返回 status、progress、video_id；CLI `heygen video-agent get <session_id>`（或拿到 `video_id` 后用 `heygen video get <video-id>`）。每个视频总墙钟时间 20–45 分钟；传了 `--wait` 则 CLI 处理 polling with exponential backoff；手动 poll 首次 5 min，然后每 60s 至 45 min。状态流：`thinking` → `generating` → `completed` | `failed`。卡在 `thinking` >15 min 无进展→向用户 flag。
115. Delivery：1 从 completed status response 获取 `video_url`（S3 mp4），或用 `heygen video get <video_id> | jq -r '.data.video_page_url'` 获取 shareable link。2 本地下载 MP4：`heygen video download <video_id>`（写文件并在 stdout 输出 `{"asset", "message", "path"}`——链 `.path`）。3 通过 message 工具内联发送：`message(action:send, media:"<downloaded-path>", caption:"Your video is ready! 🎬\n📊 Duration: [actual]s vs [target]s ([percentage]%)")`，使视频在 Telegram/Discord 内联播放而非外链。4 也分享 HeyGen dashboard 编辑链接：`https://app.heygen.com/videos/<video_id>`。始终报告 duration accuracy；发送后清理下载文件。
116. Deliver：状态 DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT。
117. Self-Evaluation Log：每次生成后追加到 `heygen-video-log.jsonl`，JSON 字段包括 `timestamp`、`video_id`、`session_id`、`prompt_type`、`target_duration`、`actual_duration`、`duration_ratio`、`avatar_id`、`voice_id`、`style_id`、`orientation`、`aspect_correction`、`avatar_type`、`files_attached`、`status`、`concerns`、`topic`。示例值见原文。
118. 若用户要改动：根据反馈调整 prompt，重新生成；绝不用完全相同 prompt 重试。
119. Report feedback（仅 CLI 模式）：视频交付后或遇到摩擦，每任务运行一次 `heygen feedback --rating <1-5> --comment "<what worked, or what broke and what you tried>"`；`--rating` 5=很好 · 3=有摩擦 · 1=坏/不可用；`--comment` 写 bug、过期文档、缺失 flag、困惑行为及触发命令/流程；匿名、无需 API key，analytics 选择退出时 no-op（`HEYGEN_NO_ANALYTICS` 或 `heygen config set analytics false`）；这是 CLI 团队主要信号渠道；仅 CLI 模式，MCP 或 OpenClaw-plugin 模式跳过。
120. Best Practices：前 5s 放 hook，首 5s = 80% 留存。
121. Best Practices：每个视频一个想法；单主题结果显著更好。
122. Best Practices：为耳朵写；如果你不会对朋友说，就重写。
123. Known issues 见 references/troubleshooting.md。

适用边界 · 注意事项

• 不用于头像创建或身份设置（先用 heygen-avatar）。
• 不用于无主持人的电影镜头或 b-roll。
• 不用于翻译视频、仅 TTS 或流媒体头像。