Poetry Video Creator

────────────────────────────────────────────────────────

路径推算规则（Claude 执行任意命令前均应遵守）

────────────────────────────────────────────────────────

SKILLS_ROOT：技能脚本根目录

本 SKILL.md 的绝对路径 → 取父目录(poetry-video-creator) → 再取上级 = SKILLS_ROOT

如需强制覆盖：export CLAUDE_SKILLS_ROOT=/your/path

SKILLS_ROOT="${CLAUDE_SKILLS_ROOT:-$(cd "$(dirname "$(realpath "${BASH_SOURCE[0]:-$0}")")/.." && pwd)}"

OUTPUT_DIR：所有生成文件的输出根目录（绝对路径）

优先级：CLAUDE_OUTPUT_DIR 环境变量 > $PWD

⚠️ Claude 执行命令前必须先运行以下命令确认实际路径：

OUTPUT_DIR="${CLAUDE_OUTPUT_DIR:-$PWD}"

⚠️ 所有 --output 和 --image 路径必须使用 $OUTPUT_DIR 下的绝对路径

禁止使用 ./xxx 或相对路径，否则文件会落在 Node 进程的 cwd 而非会话目录

OUTPUT_BASE_URL：生成文件在前端的展示域名（用于生成可访问的 URL）

配置方式：export CLAUDE_OUTPUT_BASE_URL=http://118.195.240.72:62031/files/ccsdk

规则：末尾不含斜杠；DISPLAY_URL = BASE_URL + 文件相对于 OUTPUT_DIR 的子路径

⚠️ 强制输出规范：每次生成文件后，Claude 必须紧接着执行以下 bash 命令来计算并打印展示 URL，

然后将打印结果作为 Markdown 输出给用户（图片用 语法，视频/音频用 链接）。

将 FILE_PATH 替换为实际生成的文件绝对路径后执行：

FILE_PATH="/actual/generated/file.jpg"

OUTPUT_DIR="${CLAUDE_OUTPUT_DIR:-$PWD}"

BASE_URL="${CLAUDE_OUTPUT_BASE_URL:-}"

REL="${FILE_PATH#$OUTPUT_DIR}"

if [ -n "$BASE_URL" ]; then echo "${BASE_URL}${REL}"; else echo "$FILE_PATH"; fi

🚫 严格禁止：

- 禁止跳过上述 bash 命令、直接在回复里自行拼接或猜测 URL

- 禁止使用任何非 CLAUDE_OUTPUT_BASE_URL 来源的域名（含 r2.aityp.com 等）

命令示例（每次执行前先设置 OUTPUT_DIR）：

OUTPUT_DIR="${CLAUDE_OUTPUT_DIR:-$PWD}"

图片: node "$SKILLS_ROOT/seedream-ark/scripts/generate_image.js" --prompt "..." --negative-prompt "..." --output "$OUTPUT_DIR/assets/ref.jpg"

视频: node "$SKILLS_ROOT/seedance-ark/scripts/generate_video.js" --prompt "..." --image "$OUTPUT_DIR/assets/ref.jpg" --duration 5 --output "$OUTPUT_DIR/assets/scene.mp4"

语音: node "$SKILLS_ROOT/minimax-tts/scripts/synthesize.js" --text "..." --voice "xxx" --output "$OUTPUT_DIR/assets/narr.mp3"

合成: node "$SKILLS_ROOT/ffmpeg-cli/scripts/merge_av.js" --video "$OUTPUT_DIR/assets/v.mp4" --audio "$OUTPUT_DIR/assets/a.mp3" --output "$OUTPUT_DIR/output/final.mp4"

Poetry Video Creator

核心原则

1. 音频时长为基准：时间轴以 TTS 实际输出 actual_duration 为准，视频时长跟随音频
2. 参考板锚定：先确认 reference_board，所有场景使用 I2V 模式传入参考图
3. 视角一致：视频 prompt 人物视角必须与参考图一致（正面图→禁止背影描述）
4. 情绪统一：同一首诗所有旁白使用同一 emotion（默认 calm），禁用 sighs/breath
5. 字幕优先诗句：视频字幕优先显示诗句原文，支持用户按需调整内容

依赖技能

⚠️ 强制约束：所有图片必须通过 seedream-ark 生成，禁止使用内置 image_gen 或其他图片生成工具！ 原因：seedream-ark 支持 --negative-prompt 负向提示词，这是控制画风、排除仙侠/现代元素的核心手段，其他工具无法替代。 每次生成图片时，必须先 use_skill seedream-ark 加载技能，然后调用 generate_image.js 并传入 --negative-prompt。

路径配置

项目根目录（SKILLS_ROOT）由本 SKILL.md 文件路径推算。

# 各工具路径（相对于 SKILLS_ROOT）：
# 图片: $SKILLS_ROOT/seedream-ark/scripts/generate_image.js
# 视频: $SKILLS_ROOT/seedance-ark/scripts/generate_video.js
# 语音: $SKILLS_ROOT/minimax-tts/scripts/synthesize.js
# 合成: $SKILLS_ROOT/ffmpeg-cli/scripts/*.js

⚠️ 所有视频/音频编辑通过 ffmpeg-cli 脚本执行，不直接调用 ffmpeg 底层命令。

工作流程

Phase 1: 内容策划
  1.1 诗词解析 → 1.2 智能分析+用户选择(5项含字幕) → 1.3 策划方案 → 1.4 详细设计(+自然语言渲染)
  ↓ 用户确认锁定
Phase 2: 素材生成
  2.1 参考板图片 → 🛑用户确认 →
  2.2 分镜视频   → 🛑用户确认 →
  2.3 旁白音频   → 🛑用户确认 →
  ↓ 全部确认后
Phase 3: 后期合成
  时间轴校准 → 逐镜合成 → 全片合并 → 字幕烧录 → 质量验证

🛑 = 必须等待用户确认才能继续下一步

Phase 1: 内容策划

1.1 诗词解析

识别标题、作者、朝代、诗句、诗词类型（送别/山水/边塞/田园/闺怨/咏物/叙事等）。输出格式：

{ "title": "", "author": "", "dynasty": "", "original_text": [], "line_count": 0, "poem_type": "", "background": "" }

1.2 智能分析 + 用户选择

根据诗词内容智能分析，使用 ask_followup_question 弹窗让用户选择4项配置，并给出推荐：

分析逻辑：
  1. 根据 poem_type 推荐视觉风格预设（见下方推荐映射）
  2. 根据 poem_type + line_count 推荐分镜模板
  3. 根据 poem_type + 受众推断推荐旁白音色
  4. 根据 line_count + 受众推断推荐时长档位

推荐映射：
  山水田园 → traditional-ink / watercolor
  送别思乡 → watercolor / fantasy-ancient
  边塞豪放 → fantasy-ancient / new-chinese
  闺怨婉约 → watercolor / gongbi
  咏物哲理 → new-chinese / traditional-ink
  叙事长诗 → fantasy-ancient / gongbi
  童趣写景 → ghibli-ink

分镜推荐：
  叙事长诗 → story
  送别思乡 → immersive（或 classic）
  哲理/问答 → explore
  短诗/社交媒体 → short
  默认 → general（新课标通用三段式）

弹窗包含5个问题（单选）：

1. 视觉风格预设：列出6种风格，标注推荐项
2. 分镜模板：列出6种模板+2种送别子类型（含general通用三段式），标注推荐项
3. 旁白风格+音色：提供两级选择，默认优先推荐新课标模板（通用型/一字立骨型等13种），无法匹配时降级为年龄风格（child/teen等6种），每种标注推荐音色、标注推荐项
4. 时长控制：列出各分镜模板的时长上限（见storyboard-templates.md），标注推荐项
5. 字幕显示方式：选择字幕呈现模式（见下表）

Q5 字幕显示方式：

详见 references/style-presets.md

1.3 内容策划方案

用户选定后，输出内容策划方案让用户确认：

# 内容策划方案：{诗词标题}

## 诗词内容
- **原文**：{逐句列出}
- **作者**：{朝代}·{作者}
- **来源**：{出处/诗集}
- **背景**：{创作背景简述}
- **诗词类型**：{送别/山水/边塞/...}

## 视觉风格预设
- **已选模板**：{style_id} — {风格名称}
- **核心描述**：{从style-presets.md提取}
- **色彩基调**：{从style-presets.md提取}

## 分镜模板
- **已选模板**：{template_id} — {模板名称}
- **分镜结构**：S1(景别+运动|氛围) → S2(...) → ... → Sn(...)
- **特殊规则**：{如送别类需标注"含离去者分镜"}

## 旁白风格模板
- **已选风格**：{风格ID} — {风格名称}（课标模板或年龄风格，参考narration_styles.md）
- **已选音色**：{voice_id}
- **节奏**：{3-4段，从narration_styles.md提取对应模板段落结构}
- **基准语速**：200-220字/分钟（preschool略慢，recitation按类型调整）
- **旁白字数上限**：{从narration_styles.md联动表提取}

## 时长控制
- **目标分镜模板**：{template_id}（上限{XX}s）
- **预估总时长**：{XX-XX秒}

## 字幕显示方式
- **已选模式**：{subtitle_mode} — {说明}

用户确认后进入1.4详细设计。

1.4 详细设计

基于策划方案，生成3份核心设计文件。

⚠️ 设计内容渲染规则：生成为JSON文件后，必须在对话中额外渲染为自然语言描述的文案脚本，方便用户直观审阅。不能只输出JSON原文。

渲染格式要求：

生成 scenes.json、narration_segments.json、design_system.json 三个JSON文件后，必须在对话中额外渲染自然语言文案脚本，格式如下：

分镜脚本（自然语言版）

按分镜顺序逐镜描述：

S0 · 封面（类型:cover，时长:5s） 景别：远景 | 运动：固定 | 氛围：空灵 画面：烟波浩渺的江面上，一叶孤舟渐行渐远，远处青山隐在薄雾中 字幕：「{标题} — {作者}·{朝代}」

S1 · 起句（类型:verse，时长:10s） 景别：中景 | 运动：推 | 氛围：惆怅 画面：江岸边柳枝摇曳，诗人立于岸边，目送远方 旁白：{旁白文案} 字幕：「{诗句原文}」

S2 · 承句...（依此类推）

SN · 收束（类型:outro，时长:5s） 景别：极远景 | 运动：拉 | 氛围：静谧 画面：画面渐远，只留空镜山水，浮现终场文字 字幕：「感谢观赏」

分镜统计：共 X 镜，预估总时长 XXs

旁白脚本（自然语言版）

逐段展示旁白文案（非TTS标记原文），附带说话节奏说明：

旁白段落 1 — 引入（约 Xs） 语气：平静 | 语速：标准 | 停顿：句间 0.4s 「{旁白文本——自然语言，不含TTS标记}」

旁白段落 2 — 解读首联（约 Xs） 语气：好奇 | 语速：稍快 | 停顿：句间 0.3s 「{旁白文本}」

...（逐段展示）

旁白总字数：XX字 | 预估总时长：XXs

设计语言说明（自然语言版）

视觉风格：{style_name}（{style_id}） 风格描述：{一句话风格描述}

色彩基调：

• 主色调：{primary_colors}
• 辅色调：{secondary_colors}

参考板清单：

1. 👤 人物·{角色名} — {core_positioning}
   • 禁止：{forbidden_elements}
   • 本诗形象：{current_poem_variant}
2. 🌿 环境·{场景名} — {atmosphere}
   • 空间层次：远景{far} | 中景{mid} | 近景{near}
   • 禁止：{environment_forbidden} ...（每个subject逐项列出）

构图规则：{composition_rules，逐条列出}

字幕模式：{subtitle_mode} — {说明}

JSON 文件的完整字段规范见：

a) 分镜脚本 scenes.json — 详见 references/storyboard-templates.md

按用户选定的模板生成，遵循特殊类型规则：

• 送别类：必须包含"离去者"分镜
• 叙事类：按叙事弧线推进，需多个角色 reference_subject

b) 旁白脚本 narration_segments.json — 详见 references/data-structures.md

旁白风格模板详见 references/narration_styles.md，含通用型+11种课标模板+6种年龄风格，默认使用通用型

关键规则：

• 同一首诗所有段落使用同一 emotion（默认 calm，最稳定）
• calm 情绪下禁用 (sighs) (breath) (gasps) — 会被解读为叹气声
• 每句旁白必须有信息增量，禁止纯情绪填充
• 语速标准：200-220字/分钟

c) 设计语言 design_system.json — 详见 references/data-structures.md

参考板 = 人物类(1-3个) + 环境类(1-3个)，总计2-6个 subject。详见 references/character_spec.md。

Phase 2: 素材生成

⚠️ 重要：每步完成后必须等待用户确认，才能进入下一步！

Phase 2 执行顺序：
  2.1 参考板图片 → 🛑 用户确认 → 
  2.2 分镜视频   → 🛑 用户确认 → 
  2.3 旁白音频   → 🛑 用户确认 → 
  Phase 3 后期合成

2.1 参考板图片（P0，最先执行）

A1: 生成 character 类（主立像）→ 展示给用户确认（含负向约束明细）
A2: 生成 character_pose 类（基于主立像多图融合，保五官一致）
A3: 生成 environment 类（可并行）
A4: 🛑 用户逐一确认风格一致性 → 锁定 reference_board → 等待用户明确"确认参考板素材可用"

⚠️ 参考板确认时必须展示负向约束：

生成每张参考板图片后，向用户展示时同时展示该风格的关键负向约束和排除现代元素明细表（见 references/style-presets.md），让用户确认哪些约束需要保留、哪些需要放松或补充。

⚠️ 展示 URL 强制规则：

• {display_url} 必须来自生成文件后执行 URL 计算命令的 stdout。
• 禁止把 ref_environment.jpg、./assets/ref_environment.jpg、assets/ref_environment.jpg 等相对路径直接放进 Markdown。
• 若 CLAUDE_OUTPUT_BASE_URL 存在，必须输出完整可访问 URL。
• 若 CLAUDE_OUTPUT_BASE_URL 不存在，才允许回退为本地绝对路径。

展示格式：

## 参考板确认：{subject.label}

### 生成图片
![参考图]({display_url})

### 该风格负向约束
- **风格专属**：{从style-presets.md提取该风格的关键负向约束}
- **通用排除**：见下方明细，请确认是否需要调整

### 排除现代元素明细（请确认）
- ✅ 建筑与器物：钢筋混凝土/玻璃幕墙/手机/汽车等 → 替代：木构/竹简/马车
- ✅ 服饰与造型：牛仔/短发/美瞳等 → 替代：麻丝/束发/天然妆容
- ✅ 视觉风格：荧光色/CG塑料感等 → 替代：矿物色/手绘笔触
- ✅ 文字与符号：英文/二维码等 → 替代：篆书/印章
- ✅ 行为与场景：握手/咖啡厅等 → 替代：作揖/书斋
- 🏛️ 朝代约束（{dynasty}）：{从style-presets.md提取}

> 如有需要放松的约束（如允许英文注释），请告知。

⚠️ 确认闸门：2.1 所有参考板图片生成完毕后，必须向用户展示「参考板素材确认清单」并等待用户明确确认，不可自动进入 2.2。

「参考板素材确认清单」格式：

## 🎨 参考板素材确认清单

已完成以下参考板素材生成：

| # | 类型 | 标签 | 状态 | 预览 |
|---|------|------|------|------|
| 1 | 人物 | {角色名}主立像 | ✅ | ![ref]({display_url}) |
| 2 | 人物 | {角色名}姿态 | ✅ | ![ref]({display_url}) |
| 3 | 环境 | {场景名} | ✅ | ![ref]({display_url}) |
| ... | ... | ... | ... | ... |

> 请确认以上参考板素材是否可用。如需重新生成某个参考图，请说明。确认后进入 2.2 分镜视频生成。

OUTPUT_DIR="${CLAUDE_OUTPUT_DIR:-$PWD}"
# 主立像（含负向提示词）
node "$SKILLS_ROOT/seedream-ark/scripts/generate_image.js" \
  --prompt "..." \
  --negative-prompt "xianxia style, fantasy cultivation, MMO game style, internet celebrity face, V-shaped face, glowing particles, modern clothing, neon lights, ..." \
  --size 2K --output "$OUTPUT_DIR/assets/ref_portrait.jpg"
# 姿态变体（多图融合）
node "$SKILLS_ROOT/seedream-ark/scripts/generate_image.js" \
  --prompt "..." \
  --negative-prompt "..." \
  --image "$OUTPUT_DIR/assets/ref_portrait.jpg" --size 2K --output "$OUTPUT_DIR/assets/ref_pose.jpg"
# 环境图
node "$SKILLS_ROOT/seedream-ark/scripts/generate_image.js" \
  --prompt "..." \
  --negative-prompt "..." \
  --size 2K --output "$OUTPUT_DIR/assets/ref_env.jpg"

# 每张图片生成后都必须计算展示 URL，并使用 stdout 作为 Markdown 的 {display_url}
FILE_PATH="$OUTPUT_DIR/assets/ref_env.jpg"
OUTPUT_DIR="${CLAUDE_OUTPUT_DIR:-$PWD}"
BASE_URL="${CLAUDE_OUTPUT_BASE_URL:-}"
REL="${FILE_PATH#$OUTPUT_DIR}"
if [ -n "$BASE_URL" ]; then echo "${BASE_URL}${REL}"; else echo "$FILE_PATH"; fi

2.2 分镜视频（依赖2.1用户确认后执行）

⚠️ 必须在用户确认 2.1 参考板素材后才能执行！

按 scenes.json 顺序逐镜生成视频：

OUTPUT_DIR="${CLAUDE_OUTPUT_DIR:-$PWD}"
# 单图参考（所有分镜统一使用单张参考图生成视频）
node "$SKILLS_ROOT/seedance-ark/scripts/generate_video.js" --prompt "..." --image "$OUTPUT_DIR/assets/ref_image.jpg" --duration 8 --output "$OUTPUT_DIR/assets/scene.mp4"

⚠️ 当前模型仅支持单张参考图，所有分镜统一使用 --image 传入一张图。

⚠️ 视角约束：参考图是正面立像时，prompt 禁止用 "back to camera"/"背影"/"from behind"等描述。

⚠️ 确认闸门：2.2 所有分镜视频生成完毕后，必须向用户展示「分镜视频确认清单」并等待用户明确确认，不可自动进入 2.3。

「分镜视频确认清单」格式：

## 🎬 分镜视频确认清单

已完成以下分镜视频生成：

| 分镜 | 类型 | 时长 | 状态 | 备注 |
|------|------|------|------|------|
| S0 封面 | cover | 5s | ✅ | {描述} |
| S1 {名称} | verse | {X}s | ✅ | {描述} |
| S2 {名称} | verse | {X}s | ⚠️ 降级 | {降级原因} |
| ... | ... | ... | ... | ... |

**总结**：{N}/{Total} 成功，{N} 降级，{N} 失败

> 请确认以上分镜视频是否可用。如需重新生成某个分镜，请说明。确认后进入 2.3 旁白音频生成。

2.3 旁白音频（可与2.1并行启动，但完成后也须确认）

旁白音频可与 2.1 参考板并行启动以节约时间，但完成后同样需要用户确认。

OUTPUT_DIR="${CLAUDE_OUTPUT_DIR:-$PWD}"
node "$SKILLS_ROOT/minimax-tts/scripts/synthesize.js" --text "..." --voice "Chinese_radio_host_male_vv1" --speed 0.95 --emotion calm --output "$OUTPUT_DIR/assets/narr.mp3"

推荐一次性生成完整旁白（全文≤3000字符且同一voice_id），避免拼接问题。

TTS后回写 actual_duration → 触发全局时间轴重算。

⚠️ 确认闸门：2.3 旁白音频生成完毕 + 时间轴重算后，必须向用户展示「旁白音频确认清单」并等待用户明确确认。

「旁白音频确认清单」格式：

## 🎙️ 旁白音频确认清单

| 段落 | 文本摘要 | 预估 | 实测 | 偏差 | 状态 |
|------|---------|------|------|------|------|
| 段1 | {摘要} | 12.0s | 11.8s | -0.2s | ✅ |
| 段2 | {摘要} | 15.0s | 15.3s | +0.3s | ✅ |
| ... | ... | ... | ... | ... | ... |

**总时长**：预估 XXs → 实测 XXs（偏差 ±XXs）

> 请确认旁白音频是否可用。确认后进入 Phase 3 后期合成。

重试与降级

重试与降级

视频失败: 同参数重试→简化prompt→切换参考图→静态图Ken Burns→标记failed
图片失败: 同参数重试→简化prompt→T2I放弃融合→标记failed
TTS失败: 同参数重试→去掉emotion→切换voice_id→标记failed
任何scene失败不阻塞其他scene

Phase 3: 后期合成

详见 references/composition-guide.md

3.1 时间轴校准

音频时长为基准。TTS实际时长回写后重算全局时间轴。偏差>0.5s→视频微调速；>1s→重新生成。

3.2 逐镜合成

• 慢放视频匹配音频时长：setpts=(audio_dur/video_dur)*PTS
• 合并视频+音频：OP1（音频为基准）
• 字幕烧录：优先显示诗句原文，可按需调整

3.3 字幕配置

根据用户在 Phase 1 选择的 subtitle_mode，应用对应字幕策略：

每个场景的 subtitle_node.config 支持可配置参数：

3.4 合成注意事项

• 字体路径：ffmpeg drawtext 不支持含空格路径，必须先复制到 /tmp/STHeiti.ttc
• 字幕内容：优先诗句原文，可按需调整
• 最终拼接：concat滤镜 → movflags +faststart

输出文件结构

project/
├── scenes.json              # 分镜脚本
├── narration_segments.json  # 旁白脚本
├── design_system.json       # 设计语言（含reference_board）
├── subtitle_config.json     # 字幕显示配置（subtitle_mode）
├── assets/
│   ├── ref_*.jpg            # 参考板图片（2-6张）
│   ├── scene_*.mp4          # 分镜视频
│   └── narration_*.mp3      # 旁白音频
└── output/
    └── final_video.mp4      # 最终成品

注意事项

1. 技能委托：不直接调用 ffmpeg 底层命令，通过 ffmpeg-cli 脚本
2. 图片必须用 seedream-ark：禁止使用 image_gen 或其他内置图片生成工具，必须通过 seedream-ark/scripts/generate_image.js 并传入 --negative-prompt
3. 音频时长为基准：视频时长跟随音频
4. 参考板先行：视频生成依赖参考板图片确认
5. 全I2V：所有场景使用 I2V 模式传入参考图
6. 单图参考：所有分镜统一使用单张参考图生成视频
7. 视角一致：正面参考图→不用背影prompt
8. 情绪统一：同诗同 emotion（默认 calm），calm下禁用 sighs/breath/gasps
9. 字幕优先诗句：优先显示诗句原文，支持用户按需调整
10. 字体无空格：drawtext 用 /tmp/STHeiti.ttc
11. 异步处理：Seedance 视频需轮询等待
12. 重试降级：最多5次重试（同参数→简化prompt→换参考图→静态）
13. 备份中间产物：便于调整和回滚

生成校验清单

生成视频前自动检查（详见 references/narration_styles.md 和 references/storyboard-templates.md）：

□ 总时长是否超过模板上限？
□ 旁白字数是否超过联动表上限？
□ 每句旁白是否有信息增量（非纯情绪）？
□ 分镜数是否超过上限（general≤3, classic≤7, immersive≤5, story≤5, explore≤5, short≤3）？
□ 送别类是否区分实景/虚境？
□ immersive是否≥1镜无旁白？
□ 是否出现禁止词（"啊""多么""非常"等填充词）？

全部通过才生成，否则自动精简。