---
name: happyhorse-longvideo
description: 通过编排阿里云百炼 HappyHorse 1.1（t2v/i2v/r2v）批量生成 30秒–5分钟长视频。当用户请求"生成长视频/多镜头视频/广告TVC/短剧/电商穿搭/品牌故事/延时摄影"，或提到 HappyHorse、快乐马、Wan、百炼视频生成、分镜生产、批量出片、Prompt Cookbook 时使用。自动完成创意拆解 → 分镜规划 → 角色卡生成 → 单镜生成 → 一致性校验 → 拼接出片 → Credit 保护全流程。
version: 1.0.0
---

# HappyHorse 长视频生产 Skill

把用户的一句创意 brief，编排成一部可交付的多镜头长视频。**核心价值：把资深创意的隐性经验（Prompt 6 段式、角色一致性、镜头调度、Credit 保护）固化成 Agent 可调用的编排流程。**

---

## 触发场景

调用此 Skill 当用户请求：

- 生成超过 15 秒的视频（HappyHorse 单次上限 15s，需分镜拼接）
- 广告 TVC / 短剧 / 电商穿搭 / 品牌故事 / 延时摄影 / MV
- 明确提到 HappyHorse、快乐马、Wan 2.6/2.7、百炼视频生成
- 需要跨镜头角色/产品一致性（例：同一模特多场景、同一 SKU 多角度）
- 要求批量出片、A/B 测试、Prompt Cookbook 类交付

## 不适用场景

- 单个 ≤15s 的短镜头 → 直接用 API 单次调用即可
- 纯图像生成 → 用 Qwen-Image / 通义万相
- 视频后期精修（配音/剪辑特效）→ 用剪映/Adobe，本 Skill 只负责生成与拼接

---

## 前置条件

**环境变量**（禁止硬编码 API Key）：

```bash
export DASHSCOPE_API_KEY="sk-xxxx"          # 阿里云百炼 API Key
export DASHSCOPE_WORKSPACE_ID="ws-xxxx"     # 可选：Workspace 隔离
export HAPPYHORSE_DEFAULT_RESOLUTION="720P" # 试稿默认 720P，成片切 1080P
```

**依赖检查**：

```bash
python -c "import dashscope; import ffmpeg" 2>/dev/null || pip install dashscope ffmpeg-python openpyxl
which ffmpeg || brew install ffmpeg
```

**账户预算保护**：调用前必须先算 Credit 预估，超出用户预算需二次确认。

---

## 生产流水线（7 步）

### Step 1 · 需求澄清（AskUser）

必须问清 4 件事，缺一不可：

1. **视频总时长**（决定分镜数：`ceil(总时长 / 12s)` 段，留 3s 转场余量）
2. **风格锚点**（导演/品牌/胶片型号，例：新海诚 / Wes Anderson / 柯达 Vision3）
3. **是否需要主体一致性**（是 → 走 r2v 路径；否 → t2v 路径）
4. **交付分辨率**（720P 试稿 ¥0.9/s / 1080P 成片 ¥1.2/s）

同时明确 **Credit 预算上限**（例：¥200），全流程用它做 budget guard。

### Step 2 · 分镜规划（`templates/storyboard-schema.md`）

按 WonderClip 7 列标准输出分镜表：

```
分镜号 | 景别 | 摄像机角度 | 运镜 | 分镜描述(画面内容) | 对白 | 分镜时长(3s/6s/9s/12s)
```

写盘为 `outputs/storyboard.xlsx`，供用户预审 + 后续批量调用。

**镜头调度铁律**：
- 广告 TVC：开场空镜 3s → 主体中景 6s → 特写 3s → 收尾拉远 3s
- 短剧叙事：铺垫 → 冲突 → 高潮 → 回落，每段 ≤12s
- 电商穿搭：整体展示 → 细节特写 → 场景应用 → 三宫格收尾

### Step 3 · 角色/产品卡生成（一致性锚点）

如果分镜涉及跨镜头主体一致：

- **角色**：用 Qwen-Image 生成 3-5 张角色定妆照（不同角度/表情），存 `assets/character/`
- **产品**：用户上传原始 SKU 图，去底后存 `assets/product/`
- **场景**：可选，用 Qwen-Image 生成环境参考图存 `assets/scene/`

所有参考图上限 9 张，按 `[Image N]` 索引在 Prompt 中调用。

### Step 4 · Prompt 组装（`templates/prompt-6part.md`）

**6 段式 Prompt 骨架**（每段镜头独立一份）：

```
【风格】<风格锚点，含参考导演/作品/胶片>
【主体】<角色卡 or 产品卡 引用，如 [Image 1] 少女、[Image 2] 产品>
【场景】<时间+地点+光线+氛围元素>
【镜头】[0-Xs] <景别+运镜+动作+情绪>
【音频】<环境音+BGM 情绪+对白/无对白>
【负向约束】不出现字幕/水印/畸形手/塑料感/竞品 logo
```

每段镜头一个独立 Prompt 文件写入 `prompts/shot_01.md` ... `shot_NN.md`。

### Step 5 · 单镜生成（`scripts/call-bailian.py`）

自动路由模型变体：

| 分镜特征 | 模型 | 说明 |
|---|---|---|
| 有首帧图，动画化 | `happyhorse-1.1-i2v` | 静图转视频 |
| 无参考图，纯创意 | `happyhorse-1.1-t2v` | 试稿最省 credit |
| 需角色/产品一致性 | `happyhorse-1.1-r2v` | 广告/电商必用 |

**每段跑 2 条备选**，credit 允许时跑 3 条，走 consistency-checker 挑选最佳。

调用流程：

```python
# 从环境变量读 Key，绝不硬编码
import dashscope, os
dashscope.api_key = os.environ["DASHSCOPE_API_KEY"]

response = dashscope.VideoSynthesis.async_call(
    model="happyhorse-1.1-r2v",
    prompt=open(f"prompts/shot_{i:02d}.md").read(),
    ref_images=[...],       # 参考图 URL 或 base64
    resolution="720P",       # or "1080P"
    duration=6               # 3-15s
)
task_id = response.output.task_id
# 轮询 GetTaskStatus 拿视频 URL
```

### Step 6 · 一致性校验（consistency-checker）

每段生成后抽 3 帧（首/中/尾），用视觉模型或用户目视检查：

- 角色脸型/发色是否漂移
- 产品 logo/色号是否一致
- 光线色温是否连续
- 有无字幕/水印/畸形手

不合格 → 微调 Prompt 或增强负向约束 → 重跑（消耗额外 credit，需 budget guard 放行）。

### Step 7 · 拼接与转场（ffmpeg）

```bash
# 生成 concat 列表
for f in output/shot_*.mp4; do echo "file '$f'"; done > concat.txt

# 无损拼接（同分辨率同编码）
ffmpeg -f concat -safe 0 -i concat.txt -c copy final.mp4

# 加淡入淡出转场（推荐 0.5s crossfade）
ffmpeg -i shot_01.mp4 -i shot_02.mp4 \
  -filter_complex "[0:v][1:v]xfade=transition=fade:duration=0.5:offset=<t>" \
  transition.mp4
```

输出 `outputs/final_<resolution>.mp4` + `outputs/production_report.md`（含 credit 消耗明细、失败率、重跑次数）。

---

## Credit 保护（必须实施）

**这是太兴案例已经验证的 P0 痛点**：F&B 客户对"credit 为何被扣"极度敏感。

三层保护：

1. **生产前预估**：`credit = 分镜数 × 备选条数 × 单价（720P ¥0.9/s / 1080P ¥1.2/s）`，超预算终止
2. **单条失败退款**：API 返回 FAILED 状态时不计费（百炼原生支持）
3. **Budget Alert**：每完成 25% / 50% / 75% 主动向用户报告已消耗 credit + 剩余预算

---

## 关键 Pitfalls

| 坑 | 规避 |
|---|---|
| API Key 硬编码 | 一律 `os.environ["DASHSCOPE_API_KEY"]`，`.gitignore` 加 `.env` |
| 长视频一次生成 | HappyHorse 单次 ≤15s，>15s 必须拆镜拼接 |
| 参考图 >9 张 | R2V 上限 9 张，超出必须精简或拆多次调用 |
| 单条 Prompt 塞 20 个场景 | 一条 Prompt 最多 6-8 场景，超出走多次调用 |
| 前后镜头分辨率不一致 | ffmpeg concat 会失败，全流程锁定同一分辨率 |
| 手部特写畸形 | 减少手部特写 + 负向约束"不畸形手指" |
| 画面出乱码字幕 | 负向约束"不出现任何文字/字幕/水印" |
| 竞品/情色/暴力/未成年内容 | 百炼合规审核直接拦截，返回 InappropriateContent |

---

## 输出规范

生产结束后交付到 `outputs/` 的文件清单：

```
outputs/
├── final_720P.mp4                    # 试稿成片
├── final_1080P.mp4                   # 精修成片（可选）
├── storyboard.xlsx                   # 7 列分镜表
├── prompts/                          # 每段 Prompt 归档
│   ├── shot_01.md
│   └── shot_NN.md
├── shots/                            # 单镜原始文件
│   ├── shot_01_v1.mp4
│   └── shot_NN_vX.mp4
├── assets/                           # 参考图（角色/产品/场景）
└── production_report.md              # Credit 消耗 + 失败率 + 重跑记录
```

`production_report.md` 必须包含：

- 总 credit 消耗（预算 vs 实际）
- 每段镜头的生成次数与最终选用版本
- 失败原因分类（内容审核 / 一致性不达标 / 用户主观拒绝）
- 交付时长与实际生产耗时

---

## 客户分层默认参数

| 客户类型 | 推荐路径 | 默认参数 |
|---|---|---|
| **F&B 品牌方** | t2v 试稿 → r2v 精修 | 720P 试稿 + 1080P 精修，Credit 预算 ¥200/条 |
| **电商 SKU 批量** | r2v 模板化 | 全 1080P，一次 5-10 SKU 批跑，Credit 预算 ¥800/批 |
| **广告代理/MCN** | Storyboard 全流程 | 全 1080P + 音视频协同，Credit 预算 ¥1500/项目 |
| **短剧团队** | t2v 试稿定风格 → r2v 定角色 → 全 r2v 出片 | 分镜 6-8 段，Credit 预算 ¥500/集 |
| **专业创作者试玩** | t2v 单镜 720P | Credit 预算 ¥50，出品即交付 |

---

## Verification（交付前必检）

- [ ] 所有分镜生成成功，无 FAILED 未处理
- [ ] 拼接后总时长 = 预期 ± 1s
- [ ] 主体一致性目视/工具检查通过
- [ ] 无字幕/水印/竞品 logo 出现
- [ ] Credit 消耗 ≤ 预算上限
- [ ] `production_report.md` 已生成
- [ ] 交付文件已复制到 `outputs/`（用户可见目录）

---

## 相关技能

- `qoderwork-ppt` / `pptx-advanced`：把 production_report 做成客户交付 deck
- `xlsx`：读写 storyboard.xlsx
- `docx`：生成 Prompt Cookbook 交付文档
- `create-skill`：把本 Skill 派生成客户行业专属版本（F&B / 电商 / 短剧）