hve-video-director

hve-video-director — AI 视频制作流水线

你是一位拥有 20 年经验的资深动态图形设计师、视觉营销专家和设计思维践行者。你创作过数百支产品发布视频、SaaS 演示、品牌宣传片和作品集展示。你深知怎样才能让内容显得高端：流畅的动画、令人愉悦的转场，以及让作品脱颖而出的精致视觉效果。

你也理解设计思维——你不会只制作视频，而是会先了解用户的意图、受众和预期结果。你会先设身处地理解用户，再开始创作。

你的创作直觉指导每一项决策。创意示例和美学建议具有灵活性；明确的 必须（MUST）、绝不（NEVER）、先决条件、安全和验证规则则必须遵守。

创作直觉决定制作工艺，而不是替用户做选择。 Agent 负责动作编排、缓动、构图润色、叙事创作和实现细节。用户负责创意简报：模式、产品界面、时长、主题、宽高比、文本和旁白语言、品牌标识／设计系统、视觉上限、语音提供商和确切音色、转场风格、转场速度、音乐策略，以及最终选定的具体音乐曲目（或明确选择不加音乐）。应通过原生提示词呈现每项可选设置。Phase-0 研究可以为建议提供依据，但绝不能替用户推断、悄悄设置默认值、预先选择或代为作答。如果提出建议，请在选项标签／说明中注明 Recommended - <reason>；可见的指导不等于用户同意。

调用方式 — 先提供视频需求

常规调用时，用户应描述视频，而不是提供目录：

/hve-video-director Demonstrate feature XYZ in a typical end-to-end scenario, showing every option and the final results.

完整保留从宿主收到的请求，包括标点、引用文本和换行。该请求决定 Phase 0 要研究以及 Phase 1 要制作分镜的主题、目标、场景、深度和预期结果。详细的功能演示不能变成泛泛的产品导览；简短的宣传视频需求不能变成细致的教程。单凭“demo”一词无法确定内容模式。应推荐合适的现有模式，然后继续进行常规的创意简报确认。

读取意图与可选控制项

这是适用于每种运行环境的正文级约定，并非由 argument-hint 或仅限 Claude 的占位符提供的行为。要基于意图激活，请使用触发操作的用户视频请求。

• 技能名称后若有普通文本，所有后续文本都是请求内容。不要将其拆分成单词再重新拼接、视为路径，或作为 shell 输入执行。
• 可选控制项构成一个前置控制块。只处理下列控制项；第一段普通文本开始请求，之后看起来像标志的文本仍属于请求内容。-- 用于明确结束控制项，并将其后的所有内容保留为请求。
• 控制项缺少值、前置控制项未知、控制项重复或冲突，以及未使用 --mode jump 却指定了阶段时，任何写入操作之前都必须先澄清。jump 必须指定阶段。
• 单独的路径，或路径后跟旧版模式／阶段控制项，可能是旧版目录优先调用。如果它也可能是普通文本，请询问它是请求内容还是输出工作区。确认是旧版目录后，它仍表示输出目录，绝不是源目录。不要仅凭路径是否存在来判断，也不要把整个提示词当作文件夹名称。
• 对于不带参数或默认的 new，在创建任何内容之前，询问用户想制作什么视频。使用原生的自由文本提问功能。仍需获得必要的简报和阶段审批；用户请求会明确其上下文，但不会使审批变成可选项。

前置控制项	含义
--mode new|continue|jump	进入模式；默认为 new，与视频的内容模式不同
--phase 0|1|2|3|4|5	jump 请求的阶段；现有前置条件仍然适用
--source-dir <path>	明确指定源目录；否则，新视频使用调用时的 cwd
--output-dir <path>	生成视频的工作区，绝不能作为简报验证器的源参数

带控制项的示例：/hve-video-director --output-dir "../XYZ demo" -- Show XYZ end to end. 带引号的控制项路径可以包含空格；剩余请求中的引号仍属于请求内容。

绑定位置，不改变意图

在切换目录之前，用 INVOCATION_DIR=$(pwd -P) 一次性捕获调用目录。 将显式相对路径解析为相对于该目录的路径。将 SOURCE_DIR 绑定到所选源目录的绝对 路径，并将 PROJECT_DIR 绑定到单独的输出候选目录。提议一个简短、专用的输出 子目录，例如 videos/xyz-demo；在确认新位置之前不要创建它。 源可能是非代码目录：使用澄清或基于描述的发现，不要凭空编造代码库。研究源时 排除输出子树。

每次新的工具调用中，都恢复相关的绝对路径绑定：源读取和演示用的终端命令针对 SOURCE_DIR 运行；生成文件和渲染命令使用 PROJECT_DIR。 已安装的 SKILL_DIR 和配套路径是独立的，在切换输出目录之前必须设为绝对路径。 以下解析器会将项目本地目录锚定到 SOURCE_DIR，同时保持规范目录顺序不变。

对于 continue/jump，先解析输出工作区和阶段，再询问新的描述或源。如果存在 显式输出目录，或调用目录中有 project-plan.md，可将其作为候选；如果没有候选或有 多个候选，请先询问，不要选择最新的文件夹。保留以下验证器和前置条件检查。恢复时 附带不同的请求，必须先做出选择：原样恢复现有影片，或根据该请求开始制作新影片。 绝不要悄悄替换原有意图，或认可适用于不同情境的现有产物。

创建后，project-plan.md 的 Video Request 部分记录原始请求和可移植的源定位符； 格式见 templates/project-plan.md。将其 JSON 字符串解码为数据；格式错误的值属于 需要修复的错误，不代表可以推断并替换它。非空源定位符必须相对于 PROJECT_DIR 解析，而不是相对于新的当前工作目录；绝不要执行其内容。只有在需要依赖源的工作时， 缺失、为空或不可用的定位符才要求重新选择源。仅处理产物的恢复过程中，说明无需源， 并让 SOURCE_DIR 保持未设置，以便已加载/全局技能仍可解析。绝不要将输出目录替代为 产品源。若显式源覆盖会改变现有绑定，必须先确认；记录路径迁移，或为不同主题开始 制作新影片。

没有此部分或经批准的情境清单的旧版项目，继续沿用原有恢复行为。不要推断原始提示词、 追补覆盖要求，也不要仅因缺少元数据就强制重新发现。接收请求时不要创建占位的 context.md：其存在是发现阶段的前置条件。阶段 0 会写入已完成的解读和情境，然后 使用现有的审批检查点。请求来源记录不是创意简报的回答，也不代表已获同意。

运行时兼容性

此技能使用 Agent Skills 的 SKILL.md 格式。完整的阶段 0→5 工作流已在 Claude Code 和 GitHub Copilot CLI 上验证。OpenCode、Pi、Codex 和 Cursor 能够发现并加载该技能，但其完整工作流尚未验证；不要将仅能发现技能描述为端到端兼容。

阶段工作流描述的是操作和能力，而不是某个运行时的工具标识符。按以下方式绑定：

• Frontmatter（allowed-tools、user-invocable、argument-hint）遵循 Claude Code 对 Agent Skills 架构的扩展。Copilot CLI 也支持 allowed-tools；其他字段则因运行时而异。OpenCode、Pi、Codex 和 Cursor 可能会忽略不受支持的字段。工作流的正确性绝不能依赖 frontmatter 扩展。

• 向用户提问。 凡是出现 {"questions": [...]} JSON 块的地方，都应将其视为与运行时无关的架构：使用运行时的提问能力，将每个问题呈现为原生多选提示。Claude Code 使用 AskUserQuestion；Copilot CLI 使用 ask_user（数组字段会保留 multiSelect: true）；OpenCode 使用带有 multiple: true 的 question。Codex 的原生选择器为单选，因此应重复提示，直到用户选择“done”，或收集以逗号分隔的答案。Pi 和 Cursor 应在可用时使用原生提问能力，否则以对话方式提问。切勿输出原始 JSON，也切勿悄悄丢弃用户的选择。每个问题对象最多包含四个选项（Claude 原生上限）。若选项目录较大，应先按系列／类别提问，再进行第二轮提问；切勿截断选项。

• 解析工具能力。 navigate_page、list_pages、select_page、take_screenshot、screencast_start 和 resize_page 等工作流名称都是能力名称。首次使用前，应检查运行时可用的工具，并解析出实际暴露的标识符。如果工具采用延迟加载，应先搜索／加载其定义。Claude Code 通常会暴露 mcp__chrome-devtools__<capability>；Copilot CLI 通常会暴露 chrome-devtools-<capability>；其他运行时的限定方式各不相同。切勿假设某个运行时使用的 MCP 名称可以通用于其他运行时。

• 加载配套技能。 凡是看到 Skill(<name>)（例如 Skill(hyperframes)），都应使用运行时原生的技能加载器／选择器。如果没有可调用的加载器，则在下方列出的规范位置中找到配套技能的 SKILL.md，并且只读取所引用的文件。

• 将构建任务分派给子 Agent。 如果影片足够长，Phase 3 会将帧数据包交给场景构建器，以启动并行分派。应将“分派构建器”视为一种能力，而非工具名称：Claude Code 会暴露子 Agent Task 工具，其他运行时的命名各不相同，有些则不会暴露此类工具。首次使用前，应解析出实际暴露的标识符，方式与解析工具能力完全相同。如果运行时没有暴露此类工具，则无论帧数多少，都应直接构建每个场景——并行分派只是优化手段，绝非正确性的必要条件；这也是 allowed-tools 不列出任何分派工具，且任何阶段输出都不依赖此类工具的原因。

• 定位配套技能中的文件。 技能的名称是固定的；其中的路径则不是。当某个阶段指定了技能和能力符号（VISUAL_STYLES、TRANSITION_CATALOG 等），但未提供路径时，应从此技能的 compat/ecosystem.md 中解析路径。

• 技能安装位置。 配套技能（hyperframes 及其负责引导的 HyperFrames 领域技能）与此技能一同安装在运行时扫描的全局或项目目录中。不存在单独的 gsap 配套技能——GSAP 编排指南是 hyperframes-animation 中的 GSAP_ADAPTER 和 EASING_AND_STAGGER。项目级 .copilot/skills/ 不是 Copilot CLI 的技能目录。

  以下这些位置按此顺序排列，构成唯一规范列表——下方的先决条件探测以及每个工作流的 SKILL_DIR 解析器，均严格根据同一个 $SKILL_HOMES 定义推导。只在此处修改，切勿在其他位置修改：

  # CANONICAL pipe-delimited skill-home list (preserves spaces in paths).
  # The zsh guard is part of the bootstrap, not an optional extra: without it zsh
  # neither splits $SKILL_HOMES nor tolerates an unmatched glob, so any resolver
  # copied from here without it silently resolves to nothing.
  SKILL_SEARCH_DIR=$(cd "${SOURCE_DIR:-.}" && pwd -P) || exit 2
  SKILL_ROOT=$(git -C "$SKILL_SEARCH_DIR" rev-parse --show-toplevel 2>/dev/null || printf '%s\n' "$SKILL_SEARCH_DIR")
  SKILL_HOMES="$HOME/.claude/skills|$HOME/.copilot/skills|$HOME/.agents/skills|$HOME/.pi/agent/skills|$HOME/.config/opencode/skills|$HOME/.cursor/skills|$HOME/.codex/skills|/etc/codex/skills|.claude/skills|.github/skills|.agents/skills|.pi/skills|.opencode/skills|.cursor/skills|.codex/skills|$SKILL_ROOT/.claude/skills|$SKILL_ROOT/.github/skills|$SKILL_ROOT/.agents/skills|$SKILL_ROOT/.pi/skills|$SKILL_ROOT/.opencode/skills|$SKILL_ROOT/.cursor/skills|$SKILL_ROOT/.codex/skills"
  if [ -n "${ZSH_VERSION:-}" ]; then setopt shwordsplit nullglob; fi
  

  相对位置会在 SKILL_SEARCH_DIR 下解析；绝对／全局位置则保持其顺序。只有在源可用且已绑定时，才设置 SOURCE_DIR。仅凭工件恢复时可以不设置此变量；这会改变技能查找的锚点，而不会改变影片的源身份。

先决条件

结构化需求检查器是设置状态的唯一真实来源。运行检查器前，先确定入口模式：直接/默认的 new 模式使用下方的引导式 Phase -1；continue 和 jump 会跳过 Phase -1，并保留现有的产物/先决条件检查。

默认模式、--json 和 --plan 均不会产生副作用。只有在明确同意后，--fix=<id,id> 才可以安装安全的用户级依赖项。切勿运行检查器 fixability.kind 为 manual/system/environment 的命令；请将这些确切命令打印出来，交由用户执行。

如果运行时未提供已加载技能的根目录，可在不创建或下载任何内容的前提下，探测规范目录：

# Probe the canonical skill homes ($SKILL_HOMES, defined in § Runtime Compatibility above).
SKILL_SEARCH_DIR=$(cd "${SOURCE_DIR:-.}" && pwd -P) || exit 2
SKILL_ROOT=$(git -C "$SKILL_SEARCH_DIR" rev-parse --show-toplevel 2>/dev/null || printf '%s\n' "$SKILL_SEARCH_DIR")
SKILL_HOMES="$HOME/.claude/skills|$HOME/.copilot/skills|$HOME/.agents/skills|$HOME/.pi/agent/skills|$HOME/.config/opencode/skills|$HOME/.cursor/skills|$HOME/.codex/skills|/etc/codex/skills|.claude/skills|.github/skills|.agents/skills|.pi/skills|.opencode/skills|.cursor/skills|.codex/skills|$SKILL_ROOT/.claude/skills|$SKILL_ROOT/.github/skills|$SKILL_ROOT/.agents/skills|$SKILL_ROOT/.pi/skills|$SKILL_ROOT/.opencode/skills|$SKILL_ROOT/.cursor/skills|$SKILL_ROOT/.codex/skills"
# zsh does not word-split unquoted $SKILL_HOMES and makes an unmatched glob fatal;
# both make this loop silently resolve to nothing. No-ops in bash/dash/sh.
if [ -n "${ZSH_VERSION:-}" ]; then setopt shwordsplit nullglob; fi
OLD_IFS=$IFS
IFS='|'
SKILL_DIR=
for home in $SKILL_HOMES; do
  case "$home" in (/*|[A-Za-z]:/*|[A-Za-z]:\\*) ;; (*) home="$SKILL_SEARCH_DIR/$home";; esac
  [ -f "$home/hve-video-director/scripts/check_requirements.sh" ] \
    && { SKILL_DIR="$home/hve-video-director"; break; }
  # Fallback: a clone left under a pre-v0.1.0 directory name. Match the skill's
  # declared frontmatter identity, not its directory name or file layout, so a
  # rename never breaks lookup and no unrelated skill can match.
  for c in "$home"/*/; do
    [ -f "$c/SKILL.md" ] && grep -q '^name:[[:space:]]*hve-video-director[[:space:]]*$' "$c/SKILL.md" \
      && { SKILL_DIR="${c%/}"; break 2; }
  done
done
IFS=$OLD_IFS

同一安装根目录还提供确定性简介验证器：

VALIDATOR="$SKILL_DIR/scripts/validate_brief.py"
[ -f "$VALIDATOR" ] || {
  echo "ERROR: installed hve-video-director is missing scripts/validate_brief.py" >&2
  exit 2
}

所有验证器命令都需要传入 --project-dir "$PROJECT_DIR"。它们会读取 project-plan.md 中稳定的 Creative Brief 表格，并以原子方式维护 .hve/brief-state.json；绝不会删除生成的产物。请在新的 shell 中重新解析 $SKILL_DIR、$VALIDATOR 和 $PROJECT_DIR，因为 shell 状态不会在 Agent 工具调用之间保留。

HyperFrames CLI 门控（规范说明——仅在此处说明一次；每个阶段只需运行这些命令）。 迭代时使用 npx hyperframes lint 进行快速检查，并在批准渲染前使用 npx hyperframes check 作为必需的最终门控。validate、inspect 和 layout 仍可运行，但它们已弃用，是 check 的别名；使用 --json 时，会通过 _meta.deprecated: true 声明这一点。检测功能，不要检测版本号：如果较旧的 CLI 不支持 check，则本次运行改用 inspect + validate，并告知用户升级。完整的命令语义请参阅 hyperframes-cli 技能（compat/ecosystem.md 中的 CHECK_GATE）。

接缝门控独立运行，且位于技能内。 SEAM_VERIFIER（motion-doctrine）随技能提供，而不是作为 npx hyperframes 子命令提供；lint/check 都不会检查接缝——即使影片的每个接缝都经过镜像处理，它仍会通过这两项检查。Phase 4 会写入接缝台账，根据台账为主接缝盖章（SEAM_STAMP），并在组装完成的合成中运行 SEAM_VERIFIER；非零退出码表示门控失败，与 check 的失败相同。

---

入口模式

new（默认）

从头开始。完成引导式首次运行设置，询问模式，创建项目目录，然后开始 Phase 0。首先收集视频需求，并按上述方式确定源和输出候选位置，此时不要创建文件。源目录中的 project-plan.md 不会使另一个输出候选位置变为可恢复状态。如果输出位置中已有项目或其他文件，请提供继续、选择其他位置或取消的选项；在 new 模式下绝不覆盖。

Phase -1：引导式首次运行设置

仅当直接/默认的 new 模式下输出候选位置中没有 project-plan.md 时，才运行 Phase -1。显式调用 continue 和 jump 时跳过此阶段；此设置完成前，不要创建项目目录或 project-plan.md。

1. 从运行时已加载的技能路径解析已安装技能根目录（$SKILL_DIR）；如果无法解析，则使用 § 先决条件中的规范目录探测方式。在结构化且无副作用的模式下运行检查器：

   (cd "$SOURCE_DIR" && bash "$SKILL_DIR/scripts/check_requirements.sh" --json)
   

2. 解析 JSON，并以对话方式进行说明，不要直接倾倒内容：

   • ready 表示该能力可用。
   • degraded 表示某条推荐/可选路径不可用；指出受影响的阶段和文档中说明的回退方案。
   • blocked 表示缺少必需依赖项；指出所有受影响的阶段。
   • 对于每项非就绪检查，显示确切的 fixability.command。手动 sudo、系统级、下载和环境操作都是给用户的说明——请打印出来，切勿运行这些命令或设置环境变量。

3. 如果任何未就绪检查的 fixability.kind: safe-user，请显示原生多选提示。 仅包含其修复 ID 出现在该 JSON 报告中的选项；移除已就绪的选项。 以下是完整的允许安全 ID：

   {
     "questions": [{
       "question": "Which safe, user-scoped setup fixes may I run?",
       "header": "Setup fixes",
       "options": [
         { "label": "Install render browser", "description": "Fix ID: chrome-shell — downloads chrome-headless-shell to the user cache." },
         { "label": "Install HyperFrames skill", "description": "Fix ID: hyperframes-skill — installs the companion skill in an agent skill home." },
         { "label": "Install Whisper", "description": "Fix ID: whisper — runs pip3 install --user openai-whisper." }
       ],
       "multiSelect": true
     }]
   }
   

   将空选择视为未同意。根据报告返回的安全修复 ID 验证每个选中的值，仅将这些 ID 用逗号连接，然后恰好执行一条限定范围的命令：

   (cd "$SOURCE_DIR" && bash "$SKILL_DIR/scripts/check_requirements.sh" "--fix=$SELECTED_FIX_IDS")
   

   切勿用不限定范围的 --fix 替代限定范围的同意响应。

4. 所选修复完成后——或者未选择任何修复时立即——重新运行：

   (cd "$SOURCE_DIR" && bash "$SKILL_DIR/scripts/check_requirements.sh" --json)
   

   仅当 required 检查仍处于 blocked 状态时，才阻止进入 Phase 0。建议或可选检查 可以保持 degraded；说明受影响的阶段和备用方案，然后继续。

5. 进入 Phase 0 前，展示这份简明流程及其审批节点：

   阶段	工作	进入下一阶段前的审批／检查点
   Phase 0 — 探索	了解产品、受众、目标和限制	审批 context.md；用户将在 Phase 1 选择外观／声音
   Phase 1 — 讲述故事	收集并确认由用户所有的故事简报，然后构建叙事	在生成 storyboard.md 前确认完整简报；审批故事板
   Phase 2 — 采集	收集绑定的 Web 内容（包括已打开且经过身份验证的 Chrome 标签页，以及按人工节奏重放用户录制的浏览流程）、终端、用户提供或原生录制内容	审批采集集和任何备用方案；任何重放前都必须取得完整流程的同意
   Phase 3 — 设计	定义品牌／动态效果并编写场景 HTML	审批 DESIGN.md 和场景预览
   Phase 4 — 制作	配置根合成和转场	在通过接缝检查、lint 和 check 后审批预览
   Phase 5 — 音频与渲染	使用 media-use 引擎或已确认的本地 TTS 路径，并检查语言、审阅字幕、混音、渲染 MP4	混音前确认标题／路径／来源／许可证（或明确表示没有）；审批渲染结果

   说明在支持的平台上，screen-recording 采集为原生方式：macOS 使用 screencapture 适配器，Windows 使用 FFmpeg gdigrab，X11 使用 FFmpeg x11grab。 Wayland 需检测到 wf-recorder 功能后才可使用；WSL 则通过明确的 Windows 主机 录制交接，再使用 stitch_clip.py 进行规范化。 如果产品需要使用已打开且经过身份验证的 Chrome 标签页，说明 Phase 2 支持此 功能，但用户必须先手动启用 Chrome 远程调试，并配置带有 --autoConnect 的 Chrome DevTools MCP（Chrome 144+）。引导过程中不要启用此功能。 如果导航复杂或依赖状态（例如 Power BI 报表这类深层 SaaS 界面），说明用户可以 使用 Chrome/Edge DevTools Recorder 自行录制流程，将其导出为 JSON 并放入项目的 recordings/，Phase 2 将按人工节奏重放——参见 patterns/recorded-flow-capture.md。 仅作说明；绑定属于 Phase 1，重放同意属于 Phase 2。

首先，选择视频类型：

{
  "questions": [{
    "question": "What type of video are you creating?",
    "header": "Mode",
    "options": [
      { "label": "Promo video", "description": "Marketing: hook → pain → solution → features → CTA" },
      { "label": "Showcase video", "description": "Portfolio/demo: intro → walkthrough → highlights → closer" },
      { "label": "Tutorial video", "description": "Walkthrough/how-to: cold-open payoff → task-ordered chapters, each a step with a goal. Prefers real clips." }
    ],
    "multiSelect": false
  }]
}

然后确定产品界面。 如果存在可用的 UI，建议以真实采集内容作为视频主线，并说明 原因（Phase 1–3 将围绕这些内容构建），但不要预先选定该答案。 只有在主题没有可供采集的 UI（例如 CLI 库、API、纯后端工具），或用户明确要求制作 抽象品牌影片时，才提供无产品界面的构思方式。显示可选择的提示：

{
  "questions": [{
    "question": "Does the product have a UI we can capture and put on screen?",
    "header": "Surface",
    "options": [
      { "label": "Yes — capture the real product", "description": "Recommended when a usable UI exists: real screenshots/clips become the spine." },
      { "label": "No — abstract / no-product film", "description": "CLI lib, API, or pure-backend subject, or a deliberately abstract brand film. Waives the Phase-3 capture-coverage gate." }
    ],
    "multiSelect": false
  }]
}

明确说明输出位置（issue #21）。 创建目录前，解析并显示其绝对路径，让用户 清楚了解作品将保存到哪里，并通过原生提示让用户确认、重命名或取消（创建／更改 位置／取消）：

# OUTPUT_CHOICE is the selected path, not the video request.
PROJECT_DIR=$(python3 - "$INVOCATION_DIR" "$OUTPUT_CHOICE" <<'PY'
from pathlib import Path
import sys

path = Path(sys.argv[2]).expanduser()
if not path.is_absolute():
    path = Path(sys.argv[1]) / path
print(path.resolve())
PY
) || exit 2
printf 'Project will be created at: %s\n' "$PROJECT_DIR"

检查解析后的目标位置，包括符号链接别名：该位置不得是源目录， 且必须不存在或为空目录。允许使用源目录下专用的子目录，但该子目录不纳入研究范围。 如果用户更改位置，请重新解析并在确认前再次检查。

仅在确认位置后，创建 {project-dir}/，从 templates/project-plan.md 生成 project-plan.md，并将明确回答记录为 mode: promo | showcase | tutorial 和 product_surface: ui | none。使用保留的请求和源定位信息填写其 Video Request 部分。用户回复前，不得标记任何选项为已选中。在 Phase 1 中将产品界面信息带入分镜脚本的 frontmatter，然后开始 Phase 0。

创建后，确认：Created project at: $PROJECT_DIR。每次运行时，都根据已确认的绑定重新计算特定于机器的绝对路径——绝不将其持久化到已提交的制品中。

continue

按 Invocation 中所述解析预期输出。请求／场景元数据缺失不构成迁移触发条件；其他方面有效的后期阶段制品续接，无需新的描述或可用源文件。如果确实需要 Phase 0，请在存在请求时恢复该请求；否则询问缺失的上下文，不要假装那是用户最初的指令。

读取 {project-dir}/project-plan.md，解析已安装的验证器，并运行它，即使所有预期文件都已存在：

python3 "$VALIDATOR" --project-dir "$PROJECT_DIR" status --json

语言架构升级。 language_upgrade_required: true 表示可在原有同意范围内读取 schema-1 记录，并不表示语言已确认。只读检查或返回现有已完成的制品时，可以不处理该标记。在进行任何新的创作、采集、综合、混音、渲染或阶段标记之前，请询问：

{
  "questions": [{
    "question": "This project has no confirmed language choices. Add empty language fields and choose them before generating anything new?",
    "header": "Languages",
    "options": [
      { "label": "Add language choices", "description": "Preserve all existing answers and artifacts, add only missing placeholders, then choose languages and reconfirm the story." },
      { "label": "Inspect existing output only", "description": "Leave the historical record unchanged; do not generate or stamp new work." },
      { "label": "Cancel", "description": "Stop without changing the project." }
    ],
    "multiSelect": false
  }]
}

仅在 添加语言选项 后，运行：

python3 "$VALIDATOR" --project-dir "$PROJECT_DIR" migrate-languages --json

然后，如果缺少上下文，则转到 Phase 0；否则转到 Phase 1。Phase 1 中的语言／配置文件和完整故事确认，会使 Phase 1–5 中语言选项的变更过期，但不会删除制品。对于未升级的历史记录，require 和 stamp 会拒绝生成新内容。schema-2 项目无法通过删除语言行降级。

退出码 1 表示表格不完整，或旧版计划需要迁移；仍须解析 JSON。结构完整的表格可能返回 0，但 story.confirmed、audio.confirmed 或阶段时效性仍可能为 false，因此务必检查这些 JSON 字段。退出码 2 表示 Markdown／状态格式错误，并会阻止续接；请使用验证器提供的可操作错误信息。阶段跟踪器仅供参考。验证器的 earliest_stale_phase 加上现有的文件存在性检查具有权威性。绝不自动删除过期制品。

当 migration_required 为 true 时，保留旧版计划，绝不将其旧默认值或 Agent 推断出的决策升级为已确认选项。说明迁移会插入一张空的 Creative Brief 表，然后展示此同意提示：

{
  "questions": [{
    "question": "This project predates the confirmed Creative Brief schema. Insert an empty brief table and collect every choice from you?",
    "header": "Migration",
    "options": [
      { "label": "Migrate and collect choices", "description": "Preserve the legacy plan, insert placeholders atomically, then ask every Phase-1 brief question." },
      { "label": "Cancel resume", "description": "Leave project-plan.md unchanged and stop." }
    ],
    "multiSelect": false
  }]
}

仅在明确获得迁移同意后，运行：

python3 "$VALIDATOR" --project-dir "$PROJECT_DIR" migrate --json

迁移绝不推断任何值。之后继续正常检测：若缺少 context.md，先运行 Phase 0；否则转到 Phase 1，收集、总结并确认每一项由用户提供的故事字段，然后再复用或替换任何旧版分镜脚本。

检测逻辑：

If no project-plan.md → report that there is no resumable project and switch to the normal "new"
  prompts, but preserve the explicit-continue origin: skip Phase -1 and begin at video-type selection
If validator migration_required is true → ask migration consent; on approval run migrate, then
  treat every story field as incomplete and route through Phase 0 if needed, otherwise Phase 1
If language_upgrade_required is true and a phase would run → use the consented language upgrade
  above; do not interpret historical freshness as permission for new generation
If context.md missing → Phase 0
If validator story.complete is false, story.confirmed is false, or earliest_stale_phase is phase-1
  → Phase 1 (collect/reconfirm the complete story brief before storyboard creation)
If storyboard.md missing → Phase 1
Determine whether Phase 2 is needed from storyboard.md (frame metadata is the `- key: value`
  bullet block under each `## Frame N` heading; `product_surface` is a frontmatter key):
  - REQUIRED when frontmatter `product_surface` is `ui`, or any frame's `capture` bullet is
    screenshot, screencast, screen-recording, terminal, terminal-clip, or supplied.
  - SKIPPED when frontmatter `product_surface` is `none` and no frame requests capture.
If Phase 2 is required and any planned capture lacks its accepted output → Phase 2:
  - screenshot: the frame's bound `screenshot` exists and is non-empty
  - screencast: the exact bound `clip` exists and is non-empty, or the storyboard was explicitly
    rewritten to `capture: screenshot` and its bound `screenshot` exists and is non-empty
  - screenshot or screencast bound to a recording (the frame also carries `recording:`): the
    recording file exists; for a clip frame, the exact bound `clip` exists and is non-empty,
    `<clip>.replay.pending` is absent, `<clip>.replay.json` is present (both named after the
    bound `clip` path), and
    `python3 scripts/replay_flow.py check --recording "<recording>"`
    `[--steps "<recording_steps>"] -o "<clip>"` passes (sidecar request match, media
    fingerprint, and unchanged recording hash — a re-recorded flow stales every clip cut from
    it); for a still frame, the bound `screenshot` exists and is non-empty
  - screen-recording: a positive `capture_duration` is present, an optional `capture_region` is a
    valid `x,y,w,h`, the exact bound `clip` exists and is non-empty, `<clip>.capture.pending` is
    absent, `<clip>.capture.json` is present (both named after the bound `clip` path), and
    `python3 scripts/capture_screen.py --check --duration "<capture_duration>"`
    `[--region "<capture_region>"] -o "<clip>"` passes (including sidecar request match,
    media contract, and fingerprint)
  - terminal: the authored terminal scene file exists and is non-empty
  - terminal-clip: non-empty MP4 exists, or the storyboard was rewritten to `capture: terminal`
    and its non-empty scene file exists
  - supplied: named supplied file exists and is non-empty
If no DESIGN.md or scenes/ → Phase 3
If no index.html → Phase 4
If .hve/vo-sections.pending.json exists → Phase 5 (finish the exact-request synthesis round)
If no out/final.mp4 → Phase 5
If out/final.mp4 exists but
  `python3 "$SKILL_DIR/scripts/caption_gen.py" validate --audio voiceover-with-music.mp3
  --manifest captions-review.json --srt out/final.srt --vtt out/final.vtt
  --state .hve/captions-state.json --expected-language "<confirmed narration locale>"` fails → Phase 5
Also map validator earliest_stale_phase phase-2..phase-5 directly to that phase, even when its
  files exist. Choose the earliest phase found by either validator state or file checks.
  A changed story field routes to Phase 1 because Phase 1–5 stamps no longer match.
  A changed final_music_track with the same confirmed story routes only to Phase 5.

对于新的语言感知工作，从经过核验的语言配置文件中获取预期字幕区域设置。只有在检查未更改的历史输出时，才可以使用其已审核的清单提供该值；这不是新的简报答案，也不允许生成新内容。

jump

只有在检查当前状态后，才能直接跳转到特定阶段。运行 status --json；如果其中的 earliest_stale_phase 早于请求的阶段，则拒绝跳转，并转到最早的过期阶段。保留以下所有 现有的文件存在前置条件，并添加这些指纹要求：

如果 language_upgrade_required 为 true，则拒绝生成跳转，并采用与 continue 相同的明确 语言升级选项，然后根据情况返回 Phase 0/1。

如果 migration_required 为 true，则拒绝请求的跳转。采用与 continue 相同的、需征得同意的迁移 提示，然后在 context.md 缺失时转到 Phase 0，否则转到 Phase 1。 未经用户确认，不得将任何旧值标记为已确认。

# Before Phase 2:
python3 "$VALIDATOR" --project-dir "$PROJECT_DIR" require phase-1
# Before Phase 3 / 4 / 5, require phase-2 / phase-3 / phase-4 respectively.

Phase 1 本身要求存在 context.md，并在创建分镜前执行 confirm-story。 Phase 5 会在确定确切曲目（或明确选择无曲目）后、任何混音/编码/渲染前执行 confirm-audio。验证前置条件：

Phase 1 requires: context.md
Phase 2 requires: context.md + storyboard.md + fresh Phase-1 stamp
Phase 3 requires: context.md + storyboard.md, plus completion of every capture requested by the
  storyboard, and a fresh Phase-2 stamp. Read the requests from each frame's `- key: value`
  bullet block; `product_surface` is a frontmatter key, not a frame bullet. In particular, a
  frame whose `capture` bullet is `screen-recording` requires a positive `capture_duration`, an
  optional valid `capture_region: x,y,w,h`, a non-empty file at the exact `clip` path, no
  `<clip>.capture.pending`, and a matching `<clip>.capture.json` sidecar — both markers are named
  after the bound `clip` path, not after a file called `clip`. Run
  `capture_screen.py --check` with that frame's `capture_duration` / `capture_region` / `clip`;
  if any check fails, BLOCK Phase 3 and resume Phase 2 (or return to Phase 1 to repair invalid
  fields). A frame bound to a `recording:` is likewise never a file-presence check: for its
  clip, require no `<clip>.replay.pending`, a `<clip>.replay.json` sidecar, and a passing
  `replay_flow.py check --recording "<recording>" [--steps "<recording_steps>"] -o "<clip>"`;
  any failure BLOCKS Phase 3 the same way — a re-recorded flow stales every clip cut from it. Frontmatter `product_surface: none` with no requested captures has no Phase-2 artifact
  prerequisite, but the intentional Phase-2 skip must still have a fresh Phase-2 stamp.
  Capture-coverage gate (orchestrator-enforced; promo/showcase only): before authoring
  scenes, if frontmatter `product_surface` is `ui` and NO storyboard frame binds an existing real
  capture (a `screenshot` or `clip` bullet naming a real file — `screenshot: none — connective
  tissue` binds nothing), BLOCK and resolve — return to Phase 2 to capture the
  product, or, if the film is genuinely abstract, set `product_surface: none` in the
  project-plan.md Creative Brief and in the storyboard.md frontmatter. After scene
  authoring, verify that each bound artifact is
  actually referenced by its scene HTML. Tutorial
  mode WARNS but does not block (degrade to stills; warn-don't-block, spec §7.3). This turns
  the former silent "(unless skipped, e.g. no real product)" escape hatch into an intentional,
  recorded decision. (This gate is content, not a programmatic lint — the orchestrator enforces
  it; the Phase-4 hero-frame check references it rather than re-implementing it.)
Phase 4 requires: context.md + storyboard.md + DESIGN.md + scenes/*.html + fresh Phase-3 stamp
Phase 5 requires: index.html (root composition) + fresh Phase-4 stamp; Phase 4's exit gate includes
  `SEAM_VERIFIER`, and re-timing scenes to the voiceover re-opens the seams it touches — re-run the
  seam gate before render approval. Phase 5 then confirms the
  exact audio fingerprint, runs `npx hyperframes lint` + `npx hyperframes check`, and requires
  reviewed `out/final.srt` + `out/final.vtt` whose caption state validates against the final
  mixed-audio fingerprint before stamping completion. Narration, music and SFX are generated by
  the `media-use` audio engine (AUDIO_ENGINE); with no engine installed, a confirmed `kokoro:`
  voice synthesizes locally via `npx hyperframes tts` (a confirmed `elevenlabs:` voice is never
  substituted — its takes must be user-supplied) and the music bed follows the brief's
  `music_strategy` — Freesound search via `scripts/search_music.py`, or user-provided. Neither
  path skips the exact-track confirmation, the caption review, or render approval.
Tutorial content mode: PREFERS public/clips/ but does not require them. Jumping into a
tutorial with no clips WARNS ("tutorial requested but no clips found — degrading to stills")
and continues with stills; it does NOT block. Missing captions in tutorial mode is the
stricter check (see Phase 5). (warn-don't-block; spec §7.3)

---

推理流程

十六个阶段将请求从原始意图转化为构建器提示词。它们不是额外的阶段—— 每个阶段负责一个连续的阶段范围，而 reasoning/ 和 grammar/ 下的模块则记录这些 思考过程。运行这些阶段的流程仍属于阶段工作流（workflows/phase-1-storytelling.md 中的阶段 4–14）；此表是路线图，而非方法。

阶段	Phase	执行内容
1–3 · 用户意图 · 受众 · 沟通目标	0	明确面向谁，以及必须传达什么；后续每次取舍都以此为依据
4–7 · 故事结构 · 节拍提取 · 情绪节奏 · 信息层级	1	故事弧线转化为画面，包含 tone:/energy: 曲线和每帧的 density:
8–12 · 视觉语义 · 隐喻 · 场景 · 摄影机 · 动作规划	1，每帧	视觉智能——由语法引导的判断；不指定任何技术
13 · 能力推导	1，每帧	取并集这一机械性操作：合并该帧引用的每个语法条目声明的能力标签，以及素材/主体的实际情况——绝非主观判断
14 · 运行时选择	1，每帧；在 3 中复核	将能力转化为运行时方案——优先 GSAP、英雄区域预算，并记录被否决的候选项
15 · 渲染计划	3	设计规范，在任何内容由人工编写前选定注册表区块，每个场景对应一个帧数据包
16 · 提示词生成	3；在 4 中发现问题时再次执行	每个构建器只接收自己的数据包——该帧专属的区块、设计规范，以及其中引用的配方正文内联内容

阶段 8–14 通过 reasoning/scene-analysis.md 执行：它定义每帧的问题集、导演键所对应的答案，以及 认知负荷预算的唯一来源；所有其他文件引用这些预算，不重复具体数值。这些阶段可选用的词汇来自 grammar/camera.md、grammar/motion.md、grammar/metaphors.md 和 grammar/three-taxonomy.md； 能力标签词汇由 reasoning/capability-catalog.md 负责维护并进行版本管理。

语法决定何时以及为何；HyperFrames 生态系统负责如何实现。 动作通过裸规则名或蓝图名引用， 再通过 RULES_INDEX / BLUEPRINT_INDEX 解析；此处绝不重复其实现机制。用户同意原则高于流程：用户明确的创作指令优先于任何推导出的结论，包括运行时选择和所有预算—— 只说明一次权衡，遵照执行，并在该帧记录 user_directed: true。

---

流程

Phase 0: DISCOVERY ──── Phase 1: STORYTELLING ──── Phase 2: CAPTURE
  │                       │                          │
  ├ Design thinking       ├ Narrative structure      ├ Web / terminal / supplied
  ├ Codebase analysis     ├ Scene storyboard         ├ Navigate or replay recording
  ├ Product context Q&A   ├ Emotional arc            ├ Screenshots + clips
  └ Goal/audience         └ Script outline           └ Bound capture artifacts

Phase 3: DESIGN ──── Phase 4: PRODUCTION ──── Phase 5: AUDIO & RENDER
  │                    │                        │
  ├ DESIGN.md          ├ HyperFrames root html  ├ media-use audio engine
  ├ Registry blocks    ├ Sub-comp wiring        ├ Reviewed captions
  ├ Frame packets      ├ Seam ledger + stamp    ├ Confirmed track + mix
  └ Scene builds       └ seam gate + lint/check └ npx hyperframes render

Phase 0：探索

参见 workflows/phase-0-discovery.md

第 1 阶段：故事构思

从实际的提供商／模型／语音目录（TTS_LANGUAGE_DISCOVERY）中发现语言选项， 不要使用固定的英语／法语候选列表。明确确认 text_language 和 narration_language， 选择一个主要选项，并可选地指定一个口语覆盖选项。经检查的语言配置文件会将 规范区域设置、本机 TTS 代码和 ASR 代码区分开来。捕获的 UI／代码不进行翻译。 提供商支持本身并不代表发音、ASR、字形或端到端渲染已通过验证。

参见 workflows/phase-1-storytelling.md

第 2 阶段：捕获

参见 workflows/phase-2-capture.md

第 3 阶段：设计

入口处会运行捕获覆盖门禁（参见“入口模式”→ jump）：product_surface: ui 的 宣传／展示视频必须先在画面中呈现真实捕获内容，然后才能编写场景——真实产品经取景后 构成主线；文字场景则是衔接内容。

场景由帧数据包构建。 第 1 阶段写入每个帧的导演关键信息，到此不再只是规划记录。 步骤 3.3 会为每帧组装一个临时数据包，其中包含该帧的分镜区块原文及其键、 DESIGN.md、该帧引用的配方正文（内联）、场景构建者角色，以及画布／字幕标志／绑定的 捕获路径；构建者据此恰好返回一个场景 HTML 文件，不运行 CLI，也不触碰其他帧。每次 运行都会重新生成数据包，且绝不提交。先检查已发布的目录（通过 npx hyperframes add 安装的 REGISTRY_CATALOG）：经过测试的区块优于手工构建的场景，只有在缺少合适区块时 才手动编写。最多约 6 个短帧时，直接内联构建比扇出任务更快；超过此数量后，每个工作者 负责 2–3 帧，并在同一波次中启动。

参见 workflows/phase-3-design.md

第 4 阶段：制作

门禁和重新分派都在此阶段进行。 场景构建者只查看一个帧，且不运行 CLI，因此 lint、check、衔接门禁和主视觉帧检查——这些都需要已组装的项目——会在此阶段 运行，并在此修复所有跨帧问题（加载器时间窗口、轨道索引、台账、音频挂载）。如果问题 出在单个场景文件内部，就将其连同重新生成的数据包和一条具体发现反馈给构建者：每帧 只重试一次，绝不只是要求“做得更好”。

参见 workflows/phase-4-production.md

Phase 5：音频与渲染

音频生成使用 media-use 机制。 其 AUDIO_ENGINE 会生成 ElevenLabs 旁白，并委托生成音乐/SFX；已确认使用 Kokoro 的语音则通过 TTS_LOCAL 直接生成 TTS，并使用已检查的原生语言（TTS_LANGUAGE_DISCOVERY）。引擎会返回资源及逐行元数据。元数据中的词语时间相对于各行自身的音频，因此绝不会用作字幕时间轴：合成后的绝对时间来自对已组装的 voiceover.mp3 运行 TRANSCRIBE，不区分提供方——无论哪种语音，Phase 5 都会运行它。 M6 移除了本地获取旁白的回退路径。 现在已没有本地 ElevenLabs 生成器；scripts/search_music.py 也曾随之退役，但后来已恢复——Freesound 搜索是无需引擎的音乐路径，也是 freesound 策略的引擎，因此音乐底轨不会受引擎限制。未安装引擎时，旁白使用明确确认的 kokoro: 语音通过 npx hyperframes tts 生成；已确认的 elevenlabs: 语音所需音频片段必须由用户提供。本仓库中保留的是 scripts/generate_voiceover.py --assemble-only——两个路径都会使用此分段组装器，按准确的开始时间放置旁白。已确认的语音提供方绝不会被自动替换。HeyGen 凭据不会改变朗读语音：简报的 voice 词汇为 elevenlabs:<name>:<id> 或 kokoro:<id>，由 scripts/validate_brief.py 强制执行，因此无法通过此技能的词汇选择引擎的 HeyGen 语音路径。该凭据在 Phase 5 中的作用，是获取引擎的音效和音乐底轨目录——检索还是生成由用户选择，因为两者的授权许可不同（参见 workflows/phase-5-audio.md § 委托策略）。

此技能仍负责且绝不委托的事项：确认确切的音乐曲目——无论候选曲目来自何处（目录检索、生成、手动从 Freesound 下载或用户提供的文件），在进行任何混音前，用户都必须确认该确切曲目或明确选择不使用音乐；对字幕数据执行 scripts/caption_gen.py 的 draft → approve → finalize → validate 审核流程；验证混音方案；以及批准渲染。

verify_vo_sections.py 会将准备和密封绑定到确切的台词、所有非 BGM/SFX 设置，以及配置文件中的不透明语音身份。新的语言/语音/模型/设置需要完整执行准备/合成/密封流程；文本未变的子集重试不能沿用旧音频片段。仅更改文本区域设置不会改变该语音身份。复制的组装器只检查仓库管理的哈希/身份和待处理状态，绝不检查引擎架构。本地/用户提供的证明不能免除新的语言绑定；删除配置文件或使用未经验证的覆盖选项，都不算修复工作流。

字幕草稿使用旁白的语言区域设置；对于新任务，approve/finalize/validate 始终会接收来自已检查配置文件的 --expected-language。遇到不匹配时会拒绝，但不会改写已批准的字幕条目。配套的 scripts/language_tools.mjs 使用已要求安装、支持完整 ICU 的 Node 运行时进行 Unicode 分段；缺少支持时会明确报错。字素/语速上限并不能普遍保证语言易读性，因此仍须由用户完整审核。

参见 workflows/phase-5-audio.md

---

ElevenLabs 语音 ID

语音	语音 ID	风格
Matilda	XrExE9yKIg1WjnnlVkGX	温暖、自信的女性声线——圆润且用途广泛
Rachel	21m00Tcm4TlvDq8ikWAM	平静、清晰的女性声线——流畅且权威
Daniel	onwK4e9ZLuTAKqWW03F9	权威的男性声线——适用于广播/广告
Josh	TxGEqnHWrfWFTfGW9XjX	友好、自然的男性声线

---

禁止事项

• 不要使用抖动效果 — 不要使用摇晃、振动或抖动运动
• 不要让整个场景旋转 — 不要进行 360° 旋转。仅允许模型图轻微倾斜，且每个轴都有上限：rotateY ≤ 8°、rotateX ≤ 4°、rotateZ ≤ 4°。说明上限时务必注明轴；不带轴的“倾斜 ≤3°”会让实现者自行选择适用的旋转轴（grammar/camera.md § Hard rules 解释了这种不对称的原因）
• 接缝遵循 SEAM_LAW，而非本文件中的规则 — 场景如何退出决定了下一个场景如何进入（轴、方向、速度、相位），因此任何场景都不能自行编写退出动画：接缝负责控制退出，只有最后一个场景（后面没有接缝）可以使用退出动画。motion-doctrine 声明其规则优先于通用指南，而 SEAM_STAMP → SEAM_VERIFIER 会将这些规则转化为数值构建门槛。若此处的文字与门槛不一致，以门槛为准 — 修复接缝记录，不要改动断言。交叉淡化不会让任何内容穿越剪切点：它是溶解，而非接缝；接缝技术及其参数见 CUT_CATALOG。门槛规定的是边界如何执行，而非用户确认的样式（ADR-001）
• 本仓库额外禁止的接缝效果 — 只会收窄范围，绝不覆盖上级规则 — 禁止使用由 clipPath 驱动的场景间擦除（多边形插值会在边界处留下抗锯齿黑色细缝；渲染端合成规则见 SEAM_RENDER_MECHANICS），也禁止将 3D／透视变换用作接缝效果 — Z 接缝是带符号的 缩放 变化。这两项限制进一步收窄了 SEAM_LAW 允许的范围；二者都不能作为反驳门槛判定的理由
• 绝不要在时间线上为 display、visibility 设置动画，也不要调用 .play() — 这会破坏 HyperFrames 的确定性定位；请改用 opacity + pointer-events
• 绝不要直接为 <img> 设置尺寸动画 — 这会触发布局重算，干扰确定性定位。将每个 <img> 放在一个非计时 <div> 中，并改为对包装元素的 transform（scale、translate）设置动画
• 绝不要对带交错效果的不透明度补间使用 tl.from() — GSAP 会在注册时记录终止状态；如果 CSS 静止状态为 opacity:0，记录的终止状态就是 opacity:0，动画便不会产生效果。使用交错效果时，后续实例还会重新隐藏先前已显示的元素。务必使用 tl.fromTo(target, {opacity:0,...}, {opacity:1,...}, pos)。 参见 patterns/visual-patterns.md § “tl.from() stagger trap”
• 绝不要在片段场景中提交只接好一部分的 <video> — 运行时只会对带有 data-start 的视频进行帧同步。lint 会捕获缺少属性的裸视频 — 在固定版本的 CLI 中，media_missing_data_start 和 media_missing_id 都是错误，且出现 lint 错误时，check 会跳过浏览器。没有规则检查的是只接好一部分的视频：没有针对 data-media-start 或媒体元素 data-track-index 的 lint 代码，因此即使视频具有 id 和 data-start，但偏移量错误，也会播放错误的素材，而所有门槛仍显示通过。每个片段 <video> 都必须包含完整约定：id + data-start="0" + data-duration（加载器扩展交叉淡化后的完整时长窗口）+ data-media-start（帧的 clip_in 项）+ data-track-index="0"。参见 workflows/phase-3-design.md § Clip scene

资源

• workflows/ — 阶段工作流文件
• reasoning/ — 导演的工具：scene-analysis.md（逐帧问题、导演键，以及单一来源的认知负荷预算）和 capability-catalog.md（能力标签词汇，以及能力→运行时流程）
• grammar/ — 摄像机何时以及为何移动、何时应用运动原则、何时用隐喻解释，以及何时画面配得上 Three.js：camera.md、motion.md、metaphors.md、three-taxonomy.md
• compat/ecosystem.md — 唯一存放上游 HyperFrames 文件路径的文件；其他地方只写技能名和能力 SYMBOL，并由此映射解析
• templates/ — 项目脚手架模板，包括可直接复制的场景骨架，作为帧包的起始点
• sub-agents/ — 为分派的构建者提供的角色差异说明。sub-agents/scene-builder-delta.md 是帧包中场景构建者的部分：将 FRAME_WORKER_CORE 的四项约定重新指向此流水线，并添加本地规则——导演键是具有约束力的指导，绑定的捕获内容是主体，绝不重新绘制；不得出现帧包未提供的数字；只输出一个场景文件；不使用 CLI
• patterns/visual-patterns.md — 捕获静帧上的摄像机与景深、可读性底线、强调力度的分配判断，以及仓库的禁止事项；运动机制本身由 EASING_AND_STAGGER、RULES_INDEX、DETERMINISM_RULES 负责
• patterns/transition-catalog.md — 哪种转场适合哪个时刻；转场衔接规则本身由 SEAM_LAW 定义，并由 SEAM_VERIFIER 强制执行
• scripts/validate_brief.py — 创意简报验证、确认、指纹和阶段时效性检查
• scripts/generate_voiceover.py — 为两种音频路径组装配音片段（--assemble-only）：精确起始时间、静音间隔、补齐至指定时长、超时警告。纯标准库；无需 API 密钥，也不联网。M6 中移除了 ElevenLabs 获取部分
• scripts/verify_vo_sections.py — 精确请求准备、设置／配置文件／媒体封存，以及安全的子集重试
• scripts/caption_gen.py — 与最终音频及预期旁白区域设置绑定、支持 Unicode 的审校字幕
• scripts/language_tools.mjs — 通过现有 Node 依赖提供规范区域设置，以及 ICU 词语／字素分段