video-style-analysis

name	video-style-analysis
description	完美复刻原视频的完整内容（画面+声音），通过智能体分析原视频的视觉风格和音频特征，生成风格提示词，使用TTS复刻配音，基于原画面重新生成相似视频并合成；当用户需要完美复刻视频内容、语音克隆、视频风格迁移时使用
dependency	{"python":["opencv-python","numpy","moviepy","Pillow","openai-whisper","edge-tts","aiohttp","pyyaml","insightface","onnxruntime"]}

视频完美复刻（智能体分析+TTS配音+音视频合成）

任务目标

• 本 Skill 用于：完美复刻原视频的完整内容，包括重新生成画面（保持高相似度）和克隆原视频的配音风格（音色、语调、节奏），并合成最终视频
• 能力包含：智能体视频分析（视觉+音频）、风格提示词生成、TTS配音生成、音视频合成
• 触发条件：用户需要完美复刻视频内容、克隆原视频配音风格、保持原故事情节和画面风格时使用

前置准备

• 依赖说明：确保已安装以下Python包

  opencv-python
  numpy
  moviepy
  Pillow
  openai-whisper
  

---

核心理念

⭐ 多层视频语义分析：先粗判，再抽丝剥茧

这套 Skill 不应该一上来就把视频压缩成一句 prompt。

无论有没有 ASR，都必须先完成一个逐层收敛的分析过程：先判断视频属于什么内容机制，再判断画面里发生了什么，再抽取能帮助进一步判定的证据，最后才生成复刻约束。

强制顺序：

1. 媒体基线：分辨率、横竖屏、时长、帧率、是否有音轨、是否有 OCR/字幕
2. 内容粗分类：剧情 / 口播 / 纪录 / 教程 / 表演 / 训练 / 商品展示 / 氛围片
3. 场景语义骨架：地点类型、空间结构、人数规模、主体组织方式、光线与环境
4. 主体与行为分析：谁在画面里、在做什么、动作是同步还是对抗、是训练还是表演
5. 判别性证据提取：服装、鞋子、道具、器材、文字、标识、屏幕内容
6. 子类收敛与复刻约束：把“像运动”继续收敛到“训练 / 表演 / 比赛 / 排练”等，再写 prompt 和负约束

原则：

• 不允许从“多人 + 室内”直接跳成“多人活动现场”
• 不允许从“像跳舞”直接停住，必须继续检查动作、队形、服装、鞋子、文字、道具
• 先写事实层，再写解释层，最后才写生成层
• 每一层都要回答：我看到了什么、这说明什么、还缺什么证据

语义分析 6 层 16 维（通用）

Layer 0：媒体基线

• 媒体规格：分辨率、比例、横竖屏、时长、帧率、清晰度
• 音频角色：无人声 / 解说 / 对话 / 环境音 / 音乐主导 / 混合

Layer 1：内容机制判断

• 内容类型：剧情、纪实、教程、舞台、训练、广告、旅行、产品、纯氛围
• 叙事驱动力：ASR 驱动、视觉驱动、字幕驱动、音乐驱动，或混合驱动

Layer 2：场景语义骨架

• 地点与空间：室内/室外、建筑类型、空间用途、景深与站位关系
• 时间与光线：白天/夜晚、自然光/人工光、冷暖、硬光/漫射
• 主体规模：单人、双人、小群体、大型群像
• 主体组织关系：对话、协作、对抗、列队、围观、表演、教学

Layer 3：主体与行为

• 核心行为：走、跑、跳、练、演、讲、做、展示、互动、操作
• 动作结构：静态、重复动作、连续动作链、强爆发动作、同步动作
• 外观线索：年龄段、性别倾向、服装类别、制服程度、发型、妆造

Layer 4：判别性证据

• 道具/器材/鞋服细节：最能帮助子类判断的具体物件或穿着细节
• 文字与符号线索：字幕、招牌、屏幕 UI、墙面文字、衣物印字、徽标

Layer 5：生成约束

• 构图与摄影：景别、机位、构图、运镜、节奏
• 风格与氛围：色调、质感、真实度、年代感、文化风格、情绪气候
• 复刻硬约束：哪些必须保留，哪些不能错，哪些允许近似

示例（抽象方法，不是写死舞蹈模板）：

• 粗分类：室内多人同步活动
• 行为判断：重复抬步、队列训练、节奏一致
• 证据提取：统一服装、分趾舞鞋、木地板、墙面文字
• 子类收敛：群体基础舞步训练 / 民俗舞排练，而不是泛化成“多人运动”

⭐ ASR优先 + 分级容错机制

关键洞察：ASR语音识别不仅仅是"语音转文字"，更是理解视频叙事的关键步骤。

对比：

方法	只看图像	图像+ASR
角色数量	可能误判（如数出7个）	准确（如实际2个）
主角识别	不确定	立刻知道
叙事线	需要猜测	文本直接说明
角色关系	不清楚	明确

因此：当 ASR 有效时，ASR结果指导角色识别和叙事理解；但它不替代视觉语义分析，更不能跳过“粗分类 → 证据提取 → 子类收敛”。

执行方式：ASR步骤如主session环境无法安装Whisper，会自动启动sub-agent session执行。

---

⚠️ 分级容错机制

问题：不是所有视频都有音频，也不是所有音频都能提取到有效的叙事线。

解决方案：三级容错机制，自动降级处理。

Level 1：ASR成功 + 叙事线清晰（最佳）✅

触发条件：

• 视频有音频轨道
• ASR成功提取文本
• 文本包含明确的角色信息和叙事线

处理方式：

• 按标准流程：ASR → 叙事线分析 → 角色识别 → 视觉验证
• 输出高质量叙事分析

示例：完整剧情类短视频（含明确角色关系与叙事线）

---

Level 2：ASR成功但叙事线不清晰（次佳）⚠️

触发条件：

• 视频有音频轨道
• ASR成功提取文本
• 文本缺少明确角色信息或叙事线（如：环境音、音乐、片段式对话）

处理方式：

• ASR辅助模式：使用ASR时间戳作为场景边界
• 文本辅助：提取关键词作为风格提示
• 降级到视觉分析：主要依靠关键帧视觉分析
• 角色识别：纯视觉推断 + ASR关键词辅助

示例场景：

• 旅游纪录片：ASR可能只有环境音，但时间戳可用于场景分割
• 美食视频：ASR可能只有烹饪声音，但可以提取场景节奏

---

Level 3：无ASR或ASR失败（兜底）🛡️

触发条件：

• 视频无音频轨道
• ASR完全失败（音频损坏、格式不支持等）
• 纯视觉视频

处理方式：

• 纯视觉分析模式
• 场景分割：完全依赖关键帧视觉差异
• 角色识别：使用步骤1.5的 character_detection.json（InsightFace人脸嵌入聚类，即使换装也能匹配同一角色）
• 逐层视觉语义分析：按“内容粗分类 → 主体行为 → 证据提取 → 子类判定 → 生成约束”执行
• 叙事线推断：基于场景变化和动作序列推断，而不是直接猜主题

风险提示：

• 角色数量可能误判（如之前的7个 vs 实际2个）
• 叙事线可能不准确
• 需要用户确认角色识别结果

示例场景：

• 无声视频、动画视频、纯画面展示视频

---

自动降级流程

def analyze_with_fallback(video_path):
    """
    带容错的视频分析流程
    """
    # 尝试提取音频
    audio = extract_audio(video_path)
    
    if audio is None:
        # Level 3: 无音频
        return pure_visual_analysis(video_path)
    
    # 尝试ASR
    asr_result = perform_asr(audio)
    
    if asr_result is None or not asr_result["full_text"]:
        # Level 3: ASR失败
        return pure_visual_analysis(video_path)
    
    # 尝试叙事线分析
    narrative = analyze_narrative(asr_result["full_text"])
    
    if narrative["clarity_score"] < 0.5:
        # Level 2: 叙事线不清晰
        return hybrid_analysis(video_path, asr_result, narrative)
    
    # Level 1: 完整流程
    return full_analysis_with_narrative(video_path, asr_result, narrative)

输出标识：

• 每个分析结果需包含 analysis_level 字段（"level_1" / "level_2" / "level_3"）
• Level 2/3 需增加 confidence_warning 字段，提示用户验证

---

操作步骤

阶段1：叙事理解（ASR优先）

步骤1：智能关键帧提取

执行方式：调用Python脚本

python scripts/smart_keyframe_extractor.py \
  --video_path <原视频路径> \
  --output_dir output/keyframes/ \
  --min_fps 2.0

核心功能：

• 场景切换检测：识别场景边界（帧间像素差异阈值15%）
• 动作密度分析：动作密集区域多提取，静态区域适度提取
• 均匀提取兜底：每秒至少2帧，确保不遗漏重要镜头

输出：

• output/keyframes/*.jpg - 关键帧图像
• output/keyframes/extraction_result.json - 提取结果（场景列表、关键帧列表、视频信息）

---

步骤1.5：角色检测与跨帧聚类

执行方式：调用Python脚本（InsightFace）

python scripts/character_detector.py \
  --keyframes_dir output/keyframes/ \
  --output_path output/analysis/character_detection.json \
  --extraction_result output/keyframes/extraction_result.json \
  --similarity_threshold 0.4

核心功能：

• 人脸检测：使用InsightFace (buffalo_l) 检测每帧中的人脸及位置
• 特征提取：提取512维人脸嵌入向量（ArcFace）
• 跨帧聚类：余弦相似度贪心聚类（默认阈值0.4），即使换装也能通过人脸特征匹配同一角色
• 角色档案：生成每个角色的出现帧列表、人脸/身体区域bbox、代表性面部裁切图
• ASR整合（可选）：步骤3.5完成后，可带 --narrative_path 重新运行以将视觉角色与文本角色名关联

为什么需要这一步：

• 纯图像分析中，同一角色换装后会被误判为不同人
• ASR失败时，没有角色检测就只能靠Claude看图猜测
• 人脸嵌入在换装、换场景时仍然稳定，是最可靠的跨帧角色匹配方式

输出：

• output/analysis/character_detection.json - 角色检测与聚类结果
• output/analysis/characters/char_N_face.jpg - 每个角色的代表性面部裁切

人数字段的正确理解：

• unique_characters = 跨帧人脸聚类数，它表示底层检测里聚成了多少张“可能是不同人”的脸，不能直接当成现场人数
• frame_visible_people = 对步骤1提取出的每张关键帧做一次 单帧可见人数估计
• visible_people_stats.stable_visible_people_estimate = 复刻链路默认使用的 稳定可见人数估计
• scene_visible_people_stats = 每个场景的人数统计，后续判断主体规模、群像策略、prompt 人数关系时优先用它

输出示例：

{
  "total_keyframes_analyzed": 10,
  "total_faces_detected": 15,
  "unique_characters": 2,
  "visible_people_stats": {
    "stable_visible_people_estimate": 2,
    "min_visible_people": 1,
    "max_visible_people": 2
  },
  "scene_visible_people_stats": [
    {
      "scene_id": 0,
      "time_range": "0.0-5.0s",
      "stable_visible_people_estimate": 2
    }
  ],
  "characters": [
    {
      "character_id": 0,
      "label": "char_0",
      "matched_name": null,
      "appearance_count": 7,
      "keyframe_indices": [0, 2, 3, 5, 6, 8, 9],
      "scene_ids": [0, 1, 2, 3],
      "face_bboxes": {"frame_0000.jpg": [120, 50, 220, 180]},
      "body_bboxes": {"frame_0000.jpg": [80, 50, 260, 440]},
      "representative_face_path": "output/analysis/characters/char_0_face.jpg",
      "avg_det_score": 0.92
    }
  ]
}

---

步骤2：色彩与运动分析

执行方式：调用Python脚本

python scripts/video_analyzer.py \
  --video_path <原视频路径> \
  --output_path output/analysis/color_analysis.json

分析内容：

• 技术规格：分辨率、帧率、时长、编码格式
• 色彩分布：RGB均值、HSV特征、亮度、对比度
• 色调识别：warm_red_orange, warm_yellow, green, cyan, blue, purple等
• 运动特征：static, slow_movement, normal_movement, dynamic_fast等

输出：

• output/analysis/color_analysis.json - 色彩分析结果

---

步骤3：ASR语音识别 ⭐ 核心步骤

执行方式：调用Python脚本（自动提取音频+语音识别）

python scripts/asr_transcriber.py \
  --video_path <原视频路径> \
  --output_path output/analysis/asr_result.json \
  --model_size base \
  --language zh \
  --word_level

自动执行流程：

1. 音频提取：使用ffmpeg从视频中提取音频轨道（16kHz, mono, WAV格式）
2. 语音识别：使用Whisper模型将音频转为文本
3. 时间戳提取：生成段落级和词级时间戳

⚠️ 重要说明：

• 如果主session环境无法安装Whisper库，会自动启动sub-agent session执行
• sub-agent session有独立环境，可以安装依赖并执行完整流程
• ASR结果返回后，主session继续后续步骤

分析内容：

• 语音转文本：提取完整解说文本
• 时间戳提取：段落级和词级时间戳（用于音画对齐）
• 叙事内容：文本中包含的角色、身份、关系、叙事主题

输出：

• output/audio/extracted_audio.wav - 提取的音频文件
• output/analysis/asr_result.json - ASR识别结果

输出示例：

{
  "video_path": "原视频.mp4",
  "language": "zh",
  "full_text": "大家好，今天要分享的是...",
  "duration": 45.2,
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 3.5,
      "text": "大家好，今天要分享的是",
      "words": [
        {"word": "大家好", "start": 0.0, "end": 0.8, "confidence": 0.95}
      ]
    }
  ],
  "voice_style": {
    "speed": {"chars_per_second": 3.2, "level": "中等"},
    "pause": {"count": 5, "frequency": 1.1},
    "estimated_tone": "温柔",
    "estimated_emotion": "温暖"
  }
}

---

步骤3.5：叙事线分析 + 内容粗分类 ⭐ 关键步骤

执行方式：审核初稿 + 智能体补充

初稿已自动生成：output/analysis/narrative_analysis.json 由 draft_generator.py 在阶段1结束时自动生成，包含从ASR文本提取的人名和按时间三等分的叙事弧线骨架。Claude 只需阅读 ASR 文本后，补充所有 [TODO] 占位符。

核心理念：先判断这条视频是“什么类型的内容”，再用 ASR 文本识别角色和叙事线，指导后续图像验证。

分析内容：

3.5.1 内容粗分类（必须先做）

• 判断视频属于：剧情 / 口播 / 纪录 / 教程 / 表演 / 训练 / 商品展示 / 纯氛围
• 判断当前视频的主导理解方式：ASR 驱动 / 视觉驱动 / 字幕驱动 / 音乐驱动
• 如果 ASR 文本很弱，只把它当辅助信号，不允许强行编造完整剧情

3.5.2 叙事主题识别

• 从文本识别故事类型（爱情/励志/纪录片/广告等）
• 识别叙事视角（第一人称"我"/第三人称）
• 识别情感基调（温暖/紧张/幽默/治愈等）

3.5.3 角色识别（从文本）

• 主角识别：文本中明确提到的主角是谁？
• 角色关系：角色之间是什么关系？（情侣/朋友/家人等）
• 角色身份：角色的真实身份是什么？（富豪/普通人/企业家等）

3.5.4 叙事弧线

• 起：故事的开端（0-?秒）
• 承：故事的发展（?-?秒）
• 转：故事的转折（?-?秒）
• 合：故事的结局（?-?秒）

输出：

• output/analysis/narrative_analysis.json - 叙事线分析结果

示例输出（中性占位示例，仅演示结构）：

{
  "narrative_theme": "都市人物关系变化故事",
  "narrator": "第一人称主角（女性）",
  "characters_from_text": [
    {
      "name": "角色甲",
      "role": "主要对手戏角色，表面身份普通",
      "identity": "隐藏真实背景"
    },
    {
      "name": "叙述者（我）",
      "role": "第一人称主角",
      "identity": "故事推动者"
    }
  ],
  "narrative_arc": {
    "act_1": {"name": "建立关系", "time_range": "0-15s"},
    "act_2": {"name": "冲突发展", "time_range": "15-35s"},
    "act_3": {"name": "结果揭示", "time_range": "35-49.5s"}
  }
}

重要：此步骤完成后，应先完善步骤3.6的 semantic_analysis.json，再进行步骤4的角色视觉验证。

---

步骤3.6：6棱镜语义分析骨架（逐层收敛）

执行方式：审核初稿 + 智能体补全行为、证据、子类判断

初稿已自动生成：output/analysis/semantic_analysis.json 已自动写入媒体基线，并为每个场景生成 6 棱镜骨架。Claude 应优先完善这个文件，再进入步骤4-6。

核心理念：这一步不是单纯写分析报告，而是要产出复刻主脑。先用固定提问框架把视频看清楚，再把分析结论直接写成后续步骤必须继承的统一生成约束。

6棱镜固定提问框架：

• narrative_prism：这段在讲什么？这镜只完成什么？当前属于什么内容类型？允许 unknown
• subject_prism：谁是主体？人数规模如何？主体之间是什么关系？谁必须出现？
• action_prism：主体在做什么？动作是静态、重复、同步还是连续动作链？
• scene_prism：空间是什么？灯光如何？有哪些服装、鞋子、道具、文字、环境证据？
• camera_prism：这镜怎么拍？景别、角度、运镜、镜头关注点是什么？
• constraint_prism：哪些事实必须保留？哪些可以近似？哪些绝不能生成错？

这一步还必须把 4 类高价值判断单独结构化：

• 本体 / 子类判断：不能只写“训练 / 表演 / 活动”这种大类，必须继续收敛到更细层；写进 narrative_prism.subtype_judgment
• 行为判断：不能只写“在运动 / 在跳舞”，必须说明主体到底在做什么、凭什么这么判断；写进 action_prism.behavior_judgment
• 证据链：不能只把鞋子、文字、道具零散记下来，必须组织成“直接证据 / 辅助证据 / 反例假设 / 未决点”；写进 scene_prism.evidence_chain
• 负约束：不能只散落在描述里，必须把最容易生成错的高风险事实单列；写进 constraint_prism.negative_constraints

必须完成的内容：

• 媒体基线：确认分辨率、比例、时长、音频模式、主导理解方式
• 6棱镜补全：每个 scene 都必须补全 narrative_prism / subject_prism / action_prism / scene_prism / camera_prism / constraint_prism
• 统一生成契约 / generation_contract：在步骤3.6就先锁定整项目最终视频形态与参考图策略。后面步骤8和步骤9只能继承，不能再各自决定
• 统一风格模板 / style_consistency：它不是独立脑子，而是对 generation_contract 的展开描述。后面步骤8和步骤9必须直接继承，不允许各自发挥
• 开放世界判断：如果不确定具体类别，允许 label_status = unknown，但不允许跳过行为、证据、约束
• 证据驱动复刻：即使无法精确命名，也必须把服装、鞋子、道具、文字、环境、动作组织方式写清楚
• 负约束整理：把“不能生成错”的点写进 constraint_prism
• 禁止只看见不穿透：看到鞋子、文字、队形、动作还不够，必须把它们变成后续 prompt 会消费的结构化字段

generation_contract + style_consistency 至少必须回答这些点：

• 原视频本体是什么形态：live_action / stylized_live_action / anime
• 这个项目最终统一生成成什么形态：只能选一种
• 如果模型能力不足，是否允许整项目统一降级；如果允许，只能整项目一起降，不能局部乱降
• 角色参考图必须是什么形态：直接同形态，还是在 source_visual_mode 明确为真人时统一走 pseudo_realistic_human_illustration 这类写实人物插画桥接方案
• 场景视频必须是什么形态：它必须与 target_visual_mode 一致，不能被参考图介质带偏
• 角色参考图的背景规则和构图规则是什么
• 多人场景要给哪些 visible_characters 提供身份锚点，哪些核心角色还要补 full_body_outfit
• 服装材质和颜色语言如何统一
• 哪些一致性必须保持，哪些偏离明确禁止
• 哪些关键词必须出现，哪些关键词绝对不能混用

原则：

• 生成形态不是步骤8或步骤9临时决定，而是步骤3.6先锁定的项目级结论
• generation_contract 和 style_consistency 一起构成复刻主脑
• 后面每次生角色图、每次生场景，都必须携带同一份 generation_contract + style_consistency
• 角色之间只允许改“发型 / 脸型 / 灰裤黑裤 / 站位气质”这类差异点，不能改整体形态和项目统一画法
• 多人队列如果不补 visible_characters 和全身服装锚点，步骤9很容易出现整队同脸和主角换衣，这必须在步骤6先避免

输出：

• output/analysis/semantic_analysis.json - 6棱镜语义分析骨架

重要：

• 如果 semantic_analysis.json 还没补完整，不要急着写 scene_prompts.json
• 固定的是问题结构，不是分类答案
• final_label 可以是 unknown
• crowd mode 只影响参考图策略，不等于“活动现场”语义结论

---

步骤4：深度视觉分析（主体行为 + 证据提取）

执行方式：审核初稿 + 智能体用 read_image 验证

初稿已自动生成：output/analysis/coherence_analysis.json 包含从 character_detection.json 映射的角色骨架。Claude 需要用 read_image 查看关键帧和角色代表面部，填写外貌描述，并补充“主体在做什么、为什么这样判断、还有哪些证据支撑”。

⚠️ 核心要求：

1. 必须先完成步骤3.5叙事线分析
2. 必须先完成步骤3.6语义骨架
3. 必须使用read_image工具检查关键帧内容
4. 角色识别必须基于叙事线，而非从头猜测
5. 优先使用步骤1.5的 character_detection.json：该文件包含跨帧角色聚类、单帧可见人数、场景人数统计。人数判断先看 visible_people_stats / scene_visible_people_stats，不要直接拿 unique_characters 当现场人数

步骤4.1：基于叙事线与场景分配关键帧

# 读取叙事线分析
with open("output/analysis/narrative_analysis.json") as f:
    narrative = json.load(f)

# 读取ASR时间戳
with open("output/analysis/asr_result.json") as f:
    asr_data = json.load(f)
    segments = asr_data["segments"]

# 根据ASR时间戳和叙事弧线，分配关键帧到对应角色
for segment in segments:
    start_time = segment["start"]
    end_time = segment["end"]
    text = segment["text"]
    
    # 根据文本内容判断这段属于哪个角色
    # 例如："我第一次见到角色甲" → 角色甲
    #       "那时我才明白真相" → 叙述者（我）
    
    # 找到对应时间的关键帧
    keyframes_in_range = [kf for kf in keyframes 
                          if start_time <= kf["time"] <= end_time]

步骤4.2：用 read_image 做主体行为判断

除了看“是谁”，还必须回答：

• 画面主体是单人、双人、小群体还是大型群像
• 主体组织方式是什么：对话 / 围观 / 列队 / 协作 / 对抗 / 表演 / 教学
• 当前主行为是什么：走、讲、练、演、展示、操作、互动
• 动作结构是什么：静态、重复动作、同步动作、连续动作链、爆发动作

步骤4.3：用 read_image 提取判别性证据

必须主动检查以下证据，而不是只写“看起来像”：

• 服装：是否统一、是否有制服特征、颜色层次、功能性
• 鞋子：运动鞋、皮鞋、舞鞋、工鞋、裸足等
• 道具/器材：球拍、乐器、厨具、工具、训练器材、交通工具等
• 文字与标识：墙面文字、屏幕 UI、标牌、衣服印字、字幕
• 环境细节：地板材质、舞台/教室/车间/球场/厨房等空间特征

步骤4.4：用read_image验证角色外貌

# 选择要检查的帧（每个角色的代表性帧）
frames_to_check = []

# 对于每个角色，选择其出现的关键帧
for char in narrative["characters_from_text"]:
    char_frames = get_keyframes_for_character(char, segments, keyframes)
    frames_to_check.extend(char_frames[:5])  # 每个角色最多5帧

# 用read_image检查
result = read_image(frames_to_check)

# 从read_image结果提取角色外貌特征
# 注意：要和叙事线中的角色对应

步骤4.5：角色定义表（基于叙事线+视觉验证）

必须基于叙事线 + read_image结果

示例角色定义表（中性占位示例）：

角色	文本识别（叙事线）	关键帧验证	年龄	外貌	服装	出现场景
角色甲	"我第一次见到角色甲"	frame_005,010,015	25-35岁	东亚男性，黑色短发，五官立体	浅色衬衫→深色外套	1-5
叙述者	"那时我才明白真相"	frame_050,070,080	25-30岁	东亚女性，黑色短发	白色上衣→正式礼服	5-7

对比：错误做法 vs 正确做法

错误做法	正确做法
从图像识别出7个角色	从ASR文本识别出2个主角
每个场景独立分析	用ASR时间戳分配场景到角色
猜测叙事线	文本直接说明叙事线
不知道主角是谁	文本明确说明主角

输出：

• output/analysis/coherence_analysis.json - 场景分析 + 角色定义

---

步骤5：音画关联分析 + 子类判定（智能体）

执行方式：审核初稿 + 智能体补充语义评分

初稿已自动生成：output/analysis/audio_visual_correlation.json 包含 ASR 文本与场景时间的自动映射。Claude 需要补充语义匹配、情感一致性评分，并完成“从粗分类到子类”的最终收敛判断。

分析内容：

• 时间轴映射：建立音频文本与视频分镜的时间对应关系
• 语义匹配度：分析解说文本与画面内容的关联性
• 情感一致性：评估语音情感与画面氛围的一致性
• 子类判定：例如把“运动”继续收敛到“训练 / 比赛 / 表演”，把“多人活动”继续收敛到“列队训练 / 课堂练习 / 舞台演出 / 现场活动”
• 负约束整理：明确哪些内容不能被生成错，例如人数关系、队形、服装类型、关键道具、鞋型、文字信息

输出：

• output/analysis/audio_visual_correlation.json - 音画关联分析结果

---

阶段2：智能多维提示词生成

步骤6：生成视觉风格提示词

执行方式：审核初稿 + 智能体补充场景描述和角色外貌

初稿已自动生成：output/prompts/scene_prompts.json 包含从 character_detection 映射的角色列表、从场景数据推导的场景骨架（scene_id/duration/main_character 已填充）、从色彩分析推导的 visual_style_prompt、以及 realistic photo style 提示词前缀。Claude 需要把步骤3.5-5得到的“内容类型、行为、证据、子类判定、负约束”真正落实到 prompt，而不是只补几个形容词。

数据来源：

• 色彩数据：output/analysis/color_analysis.json
• 角色定义：output/analysis/coherence_analysis.json
• 内容粗分类 / 子类判定：步骤3.5、步骤3.6与步骤5的结论

写 prompt 前必须先写清 4 件事：

1. 这是什么类型的视频内容
2. 当前场景里主体在做什么
3. 哪些证据决定了这个判断
4. 哪些视觉事实绝不能生成错

还必须继承步骤3.6的复刻主脑：

• scene_prompts.json 必须同时携带 generation_contract 和 style_consistency
• 步骤8生成角色参考图时，先读 generation_contract.character_reference_mode，再套用 style_consistency
• 步骤9生成场景视频时，也必须先读同一份 generation_contract.scene_generation_mode，再套用 style_consistency
• 多人场景必须在 scenes[] 里补 visible_characters，不能只写 main_character
• 每个 scene 必须带 semantic_anchor，把步骤3.6的内容类型 / 子类判断 / 行为摘要 / 关键证据 / 负约束直接挂到生成层
• 核心角色的 character_ref_prompts 不能只有胸像身份图；至少主角色和关键服装角色要补 full_body_outfit
• 如果出现风格不一致，优先回头修步骤3.6，不要只在某一张图或某一段视频上临时打补丁

Prompt 组成顺序建议：

1. 与 target_visual_mode 一致的统一前缀 + 原视频尺寸比例
2. 场景与空间骨架
3. 主体规模与组织关系
4. 语义锚点（内容类型 + 子类判断 + 行为摘要）
5. 判别性证据（服装 / 鞋子 / 道具 / 文字 / 环境）
6. 光线与色调
7. 负约束（避免把训练生成成演出、避免把制服生成错、避免把群像生成成散乱路人）

示例输出（中性占位示例，仅演示结构）：

视觉风格提示词：
电影感，warm_yellow色调，缓慢推拉镜头，流畅转场

场景1提示词：
[按 target_visual_mode 填写统一前缀], 9:16 vertical, 540x960, 校园入口外景，日间自然光，角色甲（东亚男性，25岁，黑色短发，浅色衬衫）

场景4提示词：
[按 target_visual_mode 填写统一前缀], 9:16 vertical, 540x960, 室内餐桌场景，暖色灯光，角色乙（东亚男性，35岁，短发，米白衬衫）

输出：

• output/prompts/visual_style_prompt.txt - 视觉风格提示词
• output/prompts/scene_prompts.json - 每个场景的提示词

⚠️ scene_prompts.json 必须严格遵守以下 JSON schema，步骤8-9的脚本依赖这些字段：

{
  "global_style": "电影感，warm_yellow色调，缓慢推拉镜头",
  "generation_contract": {
    "source_visual_mode": "live_action",
    "target_visual_mode": "live_action",
    "mode_lock_reason": "原视频是真人，最终视频仍统一保持真人出镜；但平台对真人参考图有限制，因此步骤8统一使用写实人物插画参考图桥接",
    "fallback_policy": "如果模型能力不足，只允许整项目统一降级，不允许局部混用",
    "character_reference_mode": "pseudo_realistic_human_illustration",
    "scene_generation_mode": "live_action",
    "required_keywords": ["live action", "realistic photo style", "真人出镜"],
    "forbidden_keywords": ["anime", "illustration", "角色设定图", "live action 与动漫词混用"],
    "consistency_rules": [
      "步骤8和步骤9都必须服从同一份 generation_contract",
      "scene_generation_mode 必须与 target_visual_mode 一致",
      "如果 character_reference_mode 与 target_visual_mode 不同，只允许整项目统一采用写实人物插画桥接方案，且 source_visual_mode 必须是真人"
    ]
  },
  "style_consistency": {
    "style_family": "统一项目风格名称",
    "character_render_mode": "角色参考图必须完全服从 character_reference_mode；真人项目走桥接时，也必须是写实人物插画参考图，并保持真人比例、真实皮肤明暗和布料褶皱",
    "scene_render_mode": "场景视频必须完全服从 scene_generation_mode，不能被参考图介质带偏",
    "lighting_rule": "统一光线逻辑",
    "palette_rule": "统一主色倾向和服装配色",
    "background_rule": "角色参考图必须单人、纯净浅色背景、不带第二个人",
    "framing_rule": "角色参考图默认平视胸像；核心角色还要补全身服装锚点图",
    "costume_rule": "服装材质、颜色、版型沿用原视频",
    "character_prompt_block": "步骤8每次生角色图都必须先读取 character_reference_mode；只有 source_visual_mode 为真人时，才能走写实人物插画桥接；多人场景至少给核心角色补 identity_portrait + full_body_outfit",
    "scene_prompt_block": "步骤9每次生场景都必须先读取 scene_generation_mode；输入参考图只锁定身份、发型、服装和鞋子，最终画面仍必须服从 scene_generation_mode；多人场景必须用 main_character + visible_characters 的多张参考图防止同脸",
    "must_keep": ["scene_generation_mode 与 target_visual_mode 一致", "多人场景的人脸和发型必须分开", "核心角色的裤型和鞋型必须稳定"],
    "negative_constraints": ["角色参考图不要画成漫画脸、二次元大眼或赛璐璐阴影", "不要只喂一张参考图去生成多人场景", "不要局部换风格"]
  },
  "video_generation": {
    "source_resolution": "540x960",
    "source_aspect_ratio": "9:16",
    "target_resolution": "540x960",
    "provider_ratio": "9:16",
    "provider_resolution": "720p",
    "prompt_prefix": "[按 target_visual_mode 填写统一前缀], 9:16 vertical, 540x960"
  },
  "characters": [
    {
      "id": "char_0",
      "name": "角色甲",
      "gender": "男性",
      "age": "25-35岁",
      "appearance": "东亚男性，黑色短发，五官立体",
      "clothing": "浅色衬衫→深色外套"
    }
  ],
  "character_ref_prompts": [
    {
      "character_id": "char_0",
      "reference_type": "identity_portrait",
      "prompt": "先读取 character_reference_mode，再按唯一目标形态写身份参考图提示词，锁定脸型和发型"
    },
    {
      "character_id": "char_0",
      "reference_type": "full_body_outfit",
      "prompt": "先读取 character_reference_mode，再按唯一目标形态写全身服装锚点提示词，锁定长裤和鞋子"
    }
  ],
  "scenes": [
    {
      "scene_id": 1,
      "prompt": "[按 target_visual_mode 填写统一前缀], 9:16 vertical, 540x960, 校园入口外景，日间自然光，char_0（东亚男性，25岁，黑色短发，浅色衬衫），自然站立",
      "duration": 5.2,
      "main_character": "char_0",
      "visible_characters": ["char_0", "char_1", "char_2"],
      "semantic_anchor": {
        "content_type": "训练 / 表演 / 仪式 / 课堂 / 比赛 / 商品展示 / 剧情 / unknown",
        "subtype_judgment": "更细的子类判断，如：女子舞踊基础练习 / 课堂示范 / 队列排练",
        "behavior_summary": "一句话说明主体到底在做什么，不能只写抽象词",
        "evidence_to_preserve": ["必须在生成中保留的证据，如鞋型 / 字样 / 道具 / 队形"],
        "negative_constraints": ["最容易生成错的点，如不要把训练生成成演出 / 不要把分趾鞋生成成运动鞋"]
      },
      "time_range": "0-5.2s"
    }
  ]
}

字段说明：

• video_generation：从原视频自动继承的尺寸与比例信息，步骤9必须优先遵循此配置
• generation_contract：步骤3.6锁定的统一生成形态，步骤8和步骤9都必须先消费它，不能绕过
• style_consistency：项目级统一风格模板，是 generation_contract 的展开描述，步骤8和步骤9必须强制消费
• characters：角色定义列表（id, gender, age, appearance, clothing），用于步骤8自动生成角色参考图
• character_ref_prompts：角色参考图的提示词；支持 reference_type=identity_portrait/full_body_outfit
• scenes：场景列表（scene_id, prompt, duration, main_character, visible_characters），用于步骤9生成视频
• semantic_anchor：场景级语义锚点，强制把步骤3.6的本体 / 子类 / 行为 / 证据 / 负约束穿透到生成层
• main_character：值必须对应 characters[].id，用于查找角色参考图
• visible_characters：多人场景里真正要喂给步骤9的人物锚点；如果缺失，极容易出现同脸

大型现场模式（crowd mode）：

• 当 character_detection.json 中的 visible_people_stats.stable_visible_people_estimate > 10 时，默认判定为大型群像场景
• 注意：crowd mode 只是参考图生成策略，不是最终语义结论；不能因为人数多，就把内容草率写成“活动现场”
• 即使进入 crowd mode，也仍需继续判断它到底是训练、表演、比赛、课堂、仪式、集会还是其他多人组织活动
• unique_characters 仍然保留在分析结果里，作为底层聚类参考；但角色数量、队形关系、场景规模，必须优先使用 单帧可见人数 与 稳定可见人数估计
• crowd mode 下默认不为所有路人逐个建模，但仍要给前排主体和关键服装角色保留少量身份锚点
• 步骤9主要通过场景提示词 + visible_characters 复刻多人现场关系：前景主体、背景人群、站位层次、活动氛围，而不是给每个路人单独生成参考图
• 如用户明确要求逐角色建模，才从 crowd mode 切回逐角色参考图模式

---

步骤7：生成TTS复刻指导

执行方式：仅在 ASR 有有效文本时执行

执行前检查：如果 output/analysis/asr_result.json 的 full_text 为空，或 segments 为空，说明该视频没有可复刻的有效解说文本。此时跳过步骤7和步骤10，进入纯视觉复刻模式，不再生成或消费 tts_guide.json。

初稿已自动生成：output/prompts/tts_guide.json 已从 ASR 结果自动填充 reference_text（完整解说文本）、duration_target、以及从 voice_style 映射的 TTS 参数。只有在 ASR 文本非空时，Claude 才需要审核这些字段。

数据来源：

• ASR结果：output/analysis/asr_result.json

TTS复刻参数：

{
  "tts_parameters": {
    "gender": "女性",
    "tone": "温柔亲切",
    "speed": "中等",
    "emotion": "温暖鼓励",
    "rhythm": "平稳节奏"
  },
  "reference_text": "大家好，今天要分享的是...",
  "duration_target": 45.2
}

输出：

• output/prompts/tts_guide.json - TTS复刻指导（仅在 ASR 有有效文本时生成并消费）

⚠️ tts_guide.json 必须严格遵守以下 JSON schema，步骤10的脚本依赖这些字段：

{
  "tts_parameters": {
    "gender": "女性",
    "tone": "温柔亲切",
    "speed": "中等",
    "emotion": "温暖鼓励",
    "rhythm": "平稳节奏"
  },
  "reference_text": "大家好，今天要分享的是...",
  "duration_target": 45.2
}

字段说明：

• tts_parameters.gender：性别（男/女），用于 voice 映射
• tts_parameters.tone：语调（温柔/激昂/平静），用于 voice 映射
• tts_parameters.speed：语速（慢/较慢/中等/较快/快速），用于 rate 调整
• tts_parameters.emotion：情感（温暖/严肃/轻松），用于 voice 映射
• reference_text：完整解说文本，用于 TTS 输入

---

阶段3：风格精准复刻与音画一体化生成

步骤8：生成统一形态角色参考图

执行方式：调用Python脚本（ApiMart Gemini 图片生成）

python scripts/image_generator.py \
  --prompts_json output/prompts/scene_prompts.json \
  --output_dir output/角色参考图/ \
  --config config/api_config.yaml

脚本读取 scene_prompts.json 中的 generation_contract、style_consistency 与 character_ref_prompts / characters 列表。先确认 scene_generation_mode == target_visual_mode，再按 character_reference_mode 生成角色参考图。只有当 source_visual_mode 明确为真人时，步骤8才允许统一改用 pseudo_realistic_human_illustration 作为写实人物插画桥接参考图。动漫源视频必须继续走动漫角色参考图模板。

强制规则：

• 如果 generation_contract 还没锁定，步骤8必须直接报错停止
• 如果角色参考图的目标形态和步骤9的场景目标形态不一致，步骤8输出不能继续用于步骤9
• 当前项目生成完的 refs_manifest.json 必须记录本次 generation_contract，供步骤9核对
• 真人项目如果不能直接喂真人参考图，桥接图必须是写实人物插画参考图：非照片、真人比例、真实皮肤明暗、真实布料褶皱
• 动漫源视频不能走写实人物插画桥接，必须继续使用动漫角色参考图模板
• 只要桥接图出现漫画脸 / 二次元大眼 / 赛璐璐阴影 / 卡通线稿，就必须打回重生，不能流入步骤9

角色参考图策略：

• 常规模式（stable_visible_people_estimate <= 10）：按稳定可见人数估计选择主要主体生成参考图
• 每个进入生成链路的关键角色，至少应有 identity_portrait
• 主角色和关键服装角色，还应补 full_body_outfit，专门锁定长裤、鞋子和服装版型
• 大型现场模式 / crowd mode（stable_visible_people_estimate > 10）：默认不做“全员逐个建模”，但仍要保留少量前排主体锚点，不能只剩 1 张主角图去硬带全场
• crowd mode 的目的不是减少复刻对象，而是避免把大型群像视频错误降维成“29 个独立角色逐个建模”，从而破坏真实现场感
• crowd mode 下的多人信息应保留在 scene_prompts.json 的场景描述中，而不是依赖大量单角色参考图

配置要求：

• config/api_config.yaml 中配置 models.image（默认 provider: apimart）
• API 密钥通过 config/api_keys.yaml 或环境变量 APIMART_API_KEY / VOLCENGINE_API_KEY 设置

输出：

• output/角色参考图/*.jpg - 每个角色的统一形态参考图
• output/角色参考图/refs_manifest.json - 参考图清单

---

步骤9：生成视频片段

执行方式：调用Python脚本（Seedance 2.0 API）

python scripts/video_generator.py \
  --prompts_json output/prompts/scene_prompts.json \
  --refs_dir output/角色参考图/ \
  --output_dir output/videos/ \
  --config config/api_config.yaml \
  --parallel 1

脚本为每个场景：

1. 查找该场景主角 + visible_characters 的参考图（从 refs_manifest.json）
2. 先核对 refs_manifest.json 与当前 generation_contract 是否一致；不一致则直接停止
3. 构建带 @图片N 调用语句的提示词
4. 调用 Seedance 2.0 API 提交任务 → 轮询 → 下载视频
5. 每个 scene prompt 在提交前，都必须自动叠加同一份 generation_contract 和 style_consistency
6. 支持最多 9 张参考图（角色+构图+风格等）

多人场景强制要求：

• main_character 只能解决“主角是谁”，解决不了“整队不要同脸”
• visible_characters 必须列出真正需要喂给步骤9的人物锚点
• 如果多人场景只喂一张主角参考图，极容易出现“所有人长成同一张脸”
• 如果主角色没有 full_body_outfit，极容易出现“裤子、鞋子、下装版型漂移”

强制参数（优先由 scene_prompts.json.video_generation 决定，config 为兜底）：

• ratio: 继承原视频比例（如 9:16 / 16:9 / 1:1）
• resolution: API 生成档位（当前通常为 720p 或 1080p），生成后再归一到原视频精确尺寸
• duration: 4-15秒（与原视频场景时长一致，自动 clamp）
• max_reference_images: 9

尺寸规则：

• 最终输出尺寸必须与原视频一致（例如原视频为 540x960，则生成后的场景视频也必须落盘为 540x960）
• 如果视频生成 API 只能按档位分辨率工作，允许先按最近档位生成，再在本地统一缩放/补边到原视频尺寸

断点续传：已存在的 scene_*.mp4 自动跳过。

输出：

• output/videos/scene_*.mp4 - 每个场景的视频片段
• output/videos/videos_manifest.json - 视频清单

---

步骤10：生成TTS配音

执行方式：仅在步骤7已确认存在有效解说文本时执行

跳过条件：如果 asr_result.json 没有可用文本（full_text == ""），则该视频视为无 TTS 复刻需求。直接跳过步骤10，进入纯视觉复刻模式。

python scripts/tts_generator.py \
  --text "<解说文本>" \
  --output_path output/audio/tts_narration.wav \
  --tone "温柔" \
  --speed "中等" \
  --emotion "温暖" \
  --service edge_tts

支持的服务：

• edge_tts（默认，免费）：微软 Edge TTS，支持中文多音色
• custom：自定义 TTS API（通过 --custom_api_url 指定）
• sine：正弦波兜底（仅调试用）

Voice 映射（tone + emotion → voice）：

语调+情感	edge_tts voice
温暖/女性	zh-CN-XiaoxiaoNeural
平静/中性	zh-CN-XiaoyiNeural
激昂/男性	zh-CN-YunxiNeural

可通过 --voice 直接指定 voice 名称覆盖自动映射。

输出：

• output/audio/tts_narration.wav - TTS配音音频
• output/audio/tts_narration_tts_result.json - TTS参数记录

---

步骤11：音视频合成

执行方式：根据是否存在 TTS 分为两种模式

模式A：有 TTS 文本 → 执行 11a + 11b

# 11a 拼接场景视频
python scripts/scene_concat.py \
  --video_dir output/videos/ \
  --output_path output/videos/merged_video.mp4 \
  --order_json output/prompts/scene_prompts.json

# 11b 合成音视频（使用ASR时间戳精确对齐）
python scripts/audio_video_mixer.py \
  --video_path output/videos/merged_video.mp4 \
  --audio_path output/audio/tts_narration.wav \
  --output_path output/复刻视频.mp4 \
  --asr_json output/analysis/asr_result.json

模式B：无 TTS 文本 → 仅执行 11a（纯视觉复刻）

默认规则：当 ASR 为空时，最终交付物定义为无复刻配音版本。即只拼接视频片段，不执行 audio_video_mixer.py。

# 11a 拼接场景视频（此时 merged_video.mp4 即最终交付物）
python scripts/scene_concat.py \
  --video_dir output/videos/ \
  --output_path output/videos/merged_video.mp4 \
  --order_json output/prompts/scene_prompts.json

当前 Skill 的默认定义：纯视觉复刻模式下，最终输出是 merged_video.mp4。
不默认保留原视频音轨；“保留原音轨”属于额外需求，需用户明确提出，并应通过单独的音频策略实现，而不是复用 TTS 替换链路。

# 11a 拼接场景视频
python scripts/scene_concat.py \
  --video_dir output/videos/ \
  --output_path output/videos/merged_video.mp4 \
  --order_json output/prompts/scene_prompts.json

# 11b 合成音视频（使用ASR时间戳精确对齐）
python scripts/audio_video_mixer.py \
  --video_path output/videos/merged_video.mp4 \
  --audio_path output/audio/tts_narration.wav \
  --output_path output/复刻视频.mp4 \
  --asr_json output/analysis/asr_result.json

输出：

• output/复刻视频.mp4 - 最终视频（有 TTS 文本时）
• output/videos/merged_video.mp4 - 纯视觉复刻的最终视频（无 TTS 文本时）

---

📋 完整步骤总结

阶段	步骤	内容	执行方式	输出
阶段1	步骤1	智能关键帧提取	Python脚本	keyframes/
阶段1	步骤1.5	角色检测与跨帧聚类	Python脚本（InsightFace）	character_detection.json
阶段1	步骤2	色彩与运动分析	Python脚本	color_analysis.json
阶段1	步骤3	ASR语音识别 ⭐	Python脚本	asr_result.json
阶段2	步骤3.5	叙事线分析 ⭐	Claude分析	narrative_analysis.json
阶段2	步骤3.6	通用语义分析骨架 ⭐	Claude分析	semantic_analysis.json
阶段2	步骤4	深度视觉分析（基于叙事线）⭐	Claude+Read工具	coherence_analysis.json
阶段2	步骤5	音画关联分析	Claude分析	audio_visual_correlation.json
阶段2	步骤6	生成视觉提示词	Claude生成	scene_prompts.json
阶段2	步骤7	生成TTS指导（可选）	Claude生成	tts_guide.json
阶段3	步骤8	生成角色参考图	Python脚本（ApiMart Gemini 图片生成）	角色参考图/
阶段3	步骤9	生成视频片段	Python脚本（Seedance 2.0 API）	videos/scene_*.mp4
阶段3	步骤10	生成TTS配音（可选）	Python脚本（edge_tts）	tts_narration.wav
阶段3	步骤11	音视频合成 / 纯视觉交付	Python脚本	复刻视频.mp4 / merged_video.mp4

---

数据流完整链路

原视频.mp4
    │
    ├─→ [步骤1] smart_keyframe_extractor.py → keyframes/*.jpg
    ├─→ [步骤1.5] character_detector.py → character_detection.json + characters/*.jpg
    ├─→ [步骤2] video_analyzer.py → color_analysis.json
    └─→ [步骤3] asr_transcriber.py
            ├─→ extracted_audio.wav
            └─→ asr_result.json
                    │
                    ↓
            [步骤3.5] Claude分析 → narrative_analysis.json
                    │
                    ↓
            [步骤3.6] Claude分析 → semantic_analysis.json
                    │
                    ↓
    [步骤4] Claude Read(keyframes) + 叙事线 → coherence_analysis.json

    ↓

[步骤5] Claude分析 → audio_visual_correlation.json

    ↓

[步骤6-7] Claude生成提示词
    ├─→ scene_prompts.json（视觉风格+场景提示词+角色参考图提示词）
    └─→ tts_guide.json（TTS参数+文本）

    ↓

[步骤8] image_generator.py（ApiMart Gemini 图片生成）→ 角色参考图/*.jpg

    ↓

[步骤9] video_generator.py（Seedance 2.0 API + 角色参考图）→ videos/scene_*.mp4

    ↓

[步骤10] tts_generator.py（edge_tts，可选）→ tts_narration.wav

    ↓

[步骤11a] scene_concat.py → merged_video.mp4
    ├─→ 若无有效 ASR / 无 TTS 需求：merged_video.mp4 即最终输出
    └─→ 若有有效 ASR / 需要 TTS：进入步骤11b

[步骤11b] audio_video_mixer.py → 复刻视频.mp4

---

注意事项

1. ASR优先，但允许纯视觉降级 ⭐ 最重要

• 优先尝试 ASR，再判断是否进入文本驱动流程
• 有有效 ASR 文本时：文本理解 > 图像理解，ASR结果指导叙事线、角色识别和音画对齐
• 无有效 ASR 文本时：立即切换到纯视觉复刻模式，以关键帧、角色检测、场景叙事为主，不再强行走 TTS 链路
• 禁止跳过 ASR 探测；但 ASR 为空不等于流程失败，而是代表该视频不适合做 TTS 复刻

2. 调度模式

• 本 Skill 是调度核心：Claude 读取 SKILL.md 后按步骤执行全部流程
• 步骤1-3：Claude 调用 Python 脚本（perfect_replication_workflow.py 或单独脚本）
• 步骤3.5-7（含步骤3.6）：Claude 直接执行（分析 ASR 文本、补全语义骨架、查看关键帧、生成提示词）
• 步骤8-9：Claude 调用 Python 脚本（image_generator.py、video_generator.py，通过 API 生成）
• 步骤10-11：Claude 调用 Python 脚本；其中步骤10和步骤11b仅在存在有效 ASR 文本时执行
• API 配置：config/api_config.yaml 定义 provider，config/api_keys.yaml 存放密钥（或用环境变量）

3. 角色识别流程

1. 步骤1.5自动检测人脸并聚类（character_detection.json）
2. 从ASR文本识别角色（名字、身份、关系）
3. 完成 semantic_analysis.json 中的主体规模、行为、证据、子类判断
4. 从ASR时间戳分配关键帧到角色
5. 用read_image验证角色外貌
6. 生成最终角色定义表

4. 角色 ID 命名规范 ⭐ 重要

• 步骤1.5输出的角色 label（如 char_0, char_1）是全管线统一的角色 ID
• 步骤6生成 scene_prompts.json 时，characters[].id、scenes[].main_character、scenes[].visible_characters[] 必须使用相同的 ID
• 步骤8生成参考图时，身份图默认文件名为 {character_id}.jpg，全身服装锚点图为 {character_id}__full_body_outfit.jpg
• 步骤9查找参考图时，会同时读取 main_character 和 visible_characters
• 如果 ID 不一致，步骤9将找不到参考图，生成的视频质量会严重下降
• 若进入 crowd mode，未单独生成参考图的角色 ID 仍应保留在分析结果中，不得因为跳过参考图生成而删除角色记录
• 但 scene_prompts.json 中真正进入生成链路的 characters 列表，应按 稳定可见人数估计 做收敛，不能把 unique_characters 原样当成人数抄下去

5. 步骤依赖关系

• 步骤1-3可并行执行（或调用 perfect_replication_workflow.py 一次性完成，含步骤1.5）
• 步骤3.5必须在步骤3.6之前或同时完成（叙事线提供文本语义）
• 步骤3.6必须在步骤4和步骤6之前完成（行为、证据、子类判断先于角色细化和 prompt 编写）
• 步骤4必须用 Read 工具查看关键帧图片
• 步骤6生成提示词时必须引用步骤2的色彩分析、步骤3.5的叙事线和步骤3.6的语义骨架
• 步骤6生成的 JSON 必须通过 Schema 校验（scripts/schema_validator.py），步骤8-9入口会自动校验
• 若 ASR 文本为空，则步骤7、步骤10、步骤11b默认跳过
• 步骤8-9依赖 scene_prompts.json；步骤10-11b仅在存在有效 tts_guide.json 时依赖 TTS 相关文件
• 步骤8-9需要 API 密钥已配置（config/api_keys.yaml 或环境变量 VOLCENGINE_API_KEY）

6. JSON 模板与 Schema 校验

• 步骤3.5-7（含步骤3.6）的每个 JSON 输出都有标准模板，位于 assets/schema_templates/
• 生成 JSON 时应参考模板中的字段定义，确保不遗漏必需字段
• scripts/schema_validator.py 可独立运行校验任意中间文件：

  python scripts/schema_validator.py --file output/analysis/semantic_analysis.json --type semantic
  

• 步骤8（image_generator.py）和步骤9（video_generator.py）入口已集成自动校验，缺字段时会报明确错误

7. 其他注意事项

• 角色定义必须一致：同一个角色在所有场景使用完全相同的描述
• 视频尺寸必须跟随原视频：不得在 Skill 层面写死为 16:9 / 1280x720
• 当 asr_result.json 中 full_text 为空时，应切换到纯视觉复刻模式，不再强行生成 TTS
• 纯视觉复刻模式下，默认最终输出为 output/videos/merged_video.mp4
• 当 visible_people_stats.stable_visible_people_estimate > 10 时，默认进入 crowd mode：保留全部角色检测结果，但步骤8不做全员逐个建模，只保留少量前排主体与关键服装锚点
• “保留原视频音轨”不是当前默认链路；只有用户明确要求时，才应作为单独音频策略处理
• Whisper依赖：步骤3需要安装openai-whisper包（或使用sub-agent）

8. 统一生成形态提示词 ⭐ 强制要求

所有场景提示词和角色参考图提示词，都必须先服从 generation_contract。

允许的最终视频目标形态只有 3 种：

• live_action
• stylized_live_action
• anime

允许的桥接参考图形态：

• pseudo_realistic_human_illustration

兼容说明：旧项目里的 safe_stylized_human 视为历史命名；新生成的文件统一不要再写这个值。

规则：

• 一个项目只能选 1 种
• scene_generation_mode 必须和 target_visual_mode 完全一致
• character_reference_mode 通常与 target_visual_mode 一致；如真人项目受平台限制不能直接使用真人参考图，可整项目统一改成 pseudo_realistic_human_illustration
• pseudo_realistic_human_illustration 的含义是：写实人物插画参考图，不是漫画，不是二次元，不是卡通脸
• 如果 source_visual_mode = anime，则 character_reference_mode 不得使用 pseudo_realistic_human_illustration
• 如果模型能力不足，只允许整项目统一降级
• 禁止出现“某一段角色参考图是桥接安全图，另一段又突然改成别的桥接方式”这种局部乱切
• 禁止出现“多人场景只喂一张主角图，结果整队同脸”这种结构性错误

示例前缀：

live_action

realistic photo style, live action, 9:16 vertical, 540x960,

stylized_live_action

stylized live action, realistic human proportions, 9:16 vertical, 540x960,

anime

anime style, clean cel shading, 9:16 vertical, 540x960,

步骤6生成提示词时必须检查：

• 当前项目前缀是否和 target_visual_mode 一致
• 角色参考图提示词和场景提示词是否属于同一种形态
• 比例与分辨率是否与原视频一致
• 是否出现跨形态冲突词（如 live action 和 插画角色设定图 混在一起）

---

资源索引

核心脚本

• 智能关键帧提取: scripts/smart_keyframe_extractor.py
• 角色检测与聚类: scripts/character_detector.py（步骤1.5，InsightFace人脸嵌入聚类）
• 视频色彩分析: scripts/video_analyzer.py
• ASR语音识别: scripts/asr_transcriber.py
• API客户端: scripts/api_client.py（凭证加载、图像/视频 API 封装）
• 角色参考图生成: scripts/image_generator.py（步骤8，ApiMart Gemini 图片生成）
• 场景视频生成: scripts/video_generator.py（步骤9，Seedance 2.0 API）
• TTS生成: scripts/tts_generator.py（步骤10，edge_tts优先+可切换）
• 视频拼接: scripts/scene_concat.py（步骤11a，ffmpeg）
• 音视频合成: scripts/audio_video_mixer.py（步骤11b）
• JSON Schema 校验: scripts/schema_validator.py（校验步骤3.5-7含3.6的中间JSON）
• 初稿生成器: scripts/draft_generator.py（自动从步骤1-3的输出生成步骤3.5-7含3.6的JSON初稿）
• 完整工作流: scripts/perfect_replication_workflow.py（步骤1-11完整管线）

JSON 模板（步骤3.5-7含3.6输出标准格式）

• 叙事线分析: assets/schema_templates/narrative_analysis_template.json
• 语义分析骨架: assets/schema_templates/semantic_analysis_template.json
• 深度视觉分析: assets/schema_templates/coherence_analysis_template.json
• 音画关联分析: assets/schema_templates/audio_visual_correlation_template.json
• 场景提示词: assets/schema_templates/scene_prompts_template.json
• TTS复刻指导: assets/schema_templates/tts_guide_template.json

配置文件

• API配置: config/api_config.yaml
• API密钥示例: config/api_keys.yaml.example（复制为 api_keys.yaml 填入密钥）

参考资料

• ASR输出格式: references/asr_output_format.md
• 提示词模板: references/prompt_templates.md
• 风格分类: references/style_categories.md