鸿爪派·Agnes叙事短片工作流

概述

Agnes AI 叙事短片/长片工作流 Skill

把一部叙事小说/故事，工业化地做成一支 音画分离、带运镜与特效分镜 的 AI 视频。基于 Agnes Video v2.0 实战验证（原生音画同轨 + 后期 TTS 对白），已修复 cnbuu 早期 drama 仓库失效的 API 调用。

v2.0.0 两种模式

何时使用

• 用户说「做一支 AI 短剧 / 把《XXX》做成视频 / 来个 200 秒叙事短片 / 古风动画 / 竖屏连续剧」。
• 需要的是 前期准备（Pre-production）+ 可运行流水线，而不是单纯写脚本。
• 复用时追求「一步到位」：加载本 Skill → 跑工作流 → 自动沉淀 trace，下次改故事名即可重跑。

核心原则（必须遵守 · 9 条）

① 音画分离铁律（v2.0.0 新增 · 最高优先级）

⚠️ says「中文台词」 结构会强制烧入画面字幕（中文渲染为乱码），且任何否定约束（No subtitles / NO_TEXT / no captions）完全无效。 聂小倩 60 镜实战验证，根因是 Agnes 把「」内的文字既读出声（想要的）又画到画面上（不想要的），二者无法通过 prompt 分离。

正确做法：

• prompt 只描述动作和情绪，不引用任何可渲染文本：

  # ❌ 错误：会触发字幕渲染
  f"{character} says「{台词}」once in Chinese with a {voice} voice, mouth moving naturally."
  # ✅ 正确：只描述动作情绪
  f"{character} speaks gently to the scholar, mouth moving naturally, emotional expression."

• 台词与对白音频走后期 edge-tts 独立生成（见 scripts/gen_dialogue_tts.py），叠加到视频音轨上。
• 若历史项目已有烧字幕镜头，用 scripts/remove_subs.py 事后补救（zoomcrop > boxblur > delogo）。

② 图生锚定（跨镜人物一致性最强方案）

先 python3 scripts/generate_refs.py 文生每张角色「定妆参考图」→ assets/keyframes/refs.json → 每镜经 image_url 图生视频锚定，跨镜人物外观全程稳定。比单纯锁 seed 更强（seed 锁场景基调，image 锁人物外观）。图像端点 /v1/images/generations 与视频端点独立队列，视频饱和时仍可备图。

③ 提示词公式（v2.0.0 精简版）

Agnes_Prompt = STYLE_PREFIX + 角色 + 动作 + 光影 + 机位 + SUFFIX

• STYLE_PREFIX = 统一画风前缀（每镜必带），如 Ancient Chinese, Tang dress; （古风）或 2D cartoon, warm tones; （动画）
• SUFFIX = 画质后缀，如 , cinematic, 8k
• 单镜 prompt ≤200 字符，无破折号、无音频指令、无 says「」
• 角色片段逐字一致（不可换词），见 templates/characters.md
• 范例（聂小倩 S01）：

  Ancient Chinese, Tang dress; young Chinese scholar in blue robe walks a misty mountain path at dusk, blue hour, cinematic, 8k

④ 审核红线

拒绝「揭示/显化隐藏神话物」概念镜头（如龙王现身、化身真身）；改为「角色+动作在画面中」陈述式短句即可过审。长华丽提示词（破折号+音频指令+形容词堆砌）也会被拒。

⑤ 防漂移与帧数规则

• 单镜：短片 ≤8s / 长片 ≤10s（必要时可到 18s 上限）
• Agnes 帧数必须满足 8n+1（81/121/169/241/441），frames_for_duration() 自动换算
• num_frames 上限 441（≈18s @ 24fps）

⑥ 限流饱和现实（⚠️ 关键）

视频端点 /v1/videos 会全局饱和（双 key 同时饱和、图像端点正常），不是「1 次/分钟」那么简单。遇 fail_to_fetch_task/429/5xx 长退避 min(240+i*30,900)s 并耐心等待，切勿高频猛撞触发反滥用锁定。

⑦ submit/collect 解耦生产（v2.0.0 新增）

沙箱后台进程会被回收 + shell 可能超时 → 提交与收集必须解耦：

• tasks.json 持久化 video_id，可跨会话/分时段续跑
• 命令：python3 run_pipeline.py submit --count 3 → python3 run_pipeline.py collect --minutes 20 → python3 run_pipeline.py status
• 切勿依赖 setsid/nohup 后台进程（沙箱会回收且日志不落地）

⑧ 两阶段法合成（v2.0.0 新增 · OOM 安全）

阶段 1：每镜统一规格（scale+pad+setsar=1+fps=24+format=yuv420p+AAC 48kHz+CRF 20）→ output/prep/Sxx.mp4 阶段 2：concat demuxer 直拼（硬切比 xfade 自然，Agnes 首尾帧不衔接）→ output/final/<project>.mp4

长片（60 镜+）推荐此法；短片（24 镜以内）仍可用 compose.py 的 xfade 分批（≤8 镜/批）。

⑨ trace 沉淀（skillhub trace-evaluation 规范）

每完成一个阶段，立即把「用到的提示词 / 命令 / 关键参数 / 结果」追加写入项目 docs/trace.md 或 output/trace.jsonl。TRACE 五维自检（详见 references/trace_template.md）：

• Trigger 触发率：换故事后能否直接跑通？
• Resource 资源代价：API 调用次数/时长/成本
• Accuracy 准确度：分镜/角色/音画是否符合设计
• Consistency 一致性：跨镜人物/画风是否稳定
• Evidence 证据包：trace.md/jsonl 是否完整可溯源

完整工作流（9 阶段）

每阶段末尾都标注了「本阶段用到的提示词/命令」，请原样记入 docs/trace.md。

详细 SOP 见 references/workflow_sop.md；提示词公式与范例见 references/prompt_playbook.md；API 修复要点见 references/api_reference.md；踩坑清单见 references/lessons_learned.md。

阶段 0 · 初始化与脚手架

• bash scripts/scaffold.sh <project_slug> "<中文项目名>" [--mode short|long] [--ratio 16:9|9:16] 一键生成项目骨架。
• 全局参数：分辨率（短片 1280×720 / 长片 704×1280 或 1080×1920）、24fps、统一 seed。
• 命令：bash scripts/scaffold.sh nie-xiaoqian "聂小倩" --mode long --ratio 9:16

阶段 1 · 短剧调研（经验+数据）

• 派 research 子代理全网搜索短剧教程，总结「钩子/情绪闭环/节奏/运镜/AI 工作流/行业数据」并落地 docs/research/short_drama_research.md。
• 提示词（给子代理）：「搜索 2024–2026 短剧制作教程与行业报告，提取：①爆款叙事结构（3 秒钩子、15–20s 小反转、结尾强钩不平收）②视听节奏（单集时长、转场频率、竖屏构图）③AI 视频工作流（图生视频占比、角色一致性四件套、音画同步方案）④行业规模/用户/出海数据。输出结构化 Markdown，每条给出来源链接。」
• 结果文件：docs/research/short_drama_research.md

阶段 2 · 选题（叙事小说）

• 从公版叙事中选 1 部，给出选型理由（公版无版权风险 / 动作密集适合镜头 / 契合审核红线 / 可八段式闭环）。
• 选型提示词（给自己）：「评估候选故事：是否公版？动作戏密度？能否拆成 8 段情绪曲线（压→爆）？主要人物是否 ≤5？有无血腥/性暗示风险？」输出 docs/story_selection.md（故事+理由+八段情绪弧）。

阶段 3 · 八段式分镜设计（核心资产）

• 设计分镜（短片 24 镜 / 长片 60 镜），每段含 shot_id / duration / scene / description / camera / lighting / prompt / audio / transition / mood / seed。
• 每镜 prompt 公式（写入 storyboard/<project>_storyboard.json 的 prompt 字段）：

  STYLE_PREFIX + 角色 + 动作 + 光影 + 机位 + SUFFIX

• 范例（聂小倩 S10 月下登场）：Ancient Chinese, Tang dress; young Chinese ghost woman drifts in from the moonlight, ethereal, cinematic, 8k
• ⚠️ 对白镜不写 says「台词」，只写动作情绪（如 speaks gently, mouth moving naturally）。台词放 audio/dialogue.json。
• 结果文件：storyboard/<project>_storyboard.json
• ⭐ 阶段 3.5 角色参考图锚定（跨镜一致性关键）：分镜 characters 写好角色外貌 → 跑 python3 scripts/generate_refs.py 文生定妆图 → URL 写入 assets/keyframes/refs.json → 每镜经 image_url 图生视频锚定。

阶段 4 · 电影术语手册

• 从 assets/pipeline/cinematography_guide.md 复制到 prompts/，按本片时代背景微调（运镜/光影/特效三张表 + 导演参考 + 时代美学）。
• 结果文件：prompts/cinematography_guide.md

阶段 5 · 修复版流水线就位

• scaffold 已复制脚本到 scripts/：
  • agnes_video.py — 正确端点 + 下载去鉴权 + 支持 image_url 图生锚定 + 横竖屏双模式
  • generate_shots.py — 自动发现分镜 + 图生锚定 + 长退避 + 审核跳过 + 断点续传
  • generate_refs.py — 角色参考图生成器（图生锚定前置）
  • run_pipeline.py（v2.0 新增） — submit/collect 解耦生产驱动（tasks.json 持久化）
  • gen_dialogue_tts.py（v2.0 新增） — 后期 TTS 对白生成（edge-tts，按角色映射音色）
  • concat_final.py（v2.0 新增） — 两阶段法拼接（prep统一规格 + concat 直拼）
  • remove_subs.py（v2.0 新增） — 字幕事后补救（zoomcrop / boxblur / delogo）
  • compose.py — 分批合成（短片用，≤8 镜 xfade 防 OOM）
  • concat_segments.py — xfade/acrossfade 同轨拼接
  • audio_mix.py — 多轨混音（原生音 60% + BGM 闪避 + 配音 + 音效）
  • auto_finish.py — 自动收尾守护
  • extract_last_frame.py、setup_env.sh
• 校验：python3 -m py_compile scripts/*.py

阶段 6 · 前期筹备报告

• 生成 docs/preproduction_report/preproduction_report.html（独立可浏览页：调研结论→选型→八段表→技术标准→流水线修复对照→目录结构→生产命令）。可基于 examples/ballad-of-mulan/ 或 examples/nie-xiaoqian/ 改造。

阶段 7 · 生产阶段（用户确认后执行，消耗配额）

⚠️ 限流饱和现实：视频端点会全局饱和，长退避 min(240+i*30,900)s，耐心等待。

短片模式（≤24 镜）：

source scripts/setup_env.sh && export AGNES_API_KEY=...
python3 scripts/generate_refs.py                 # 图生锚定前置
python3 generate_shots.py --shot S01             # 单镜验证
python3 generate_shots.py                        # 批量生成（断点续传）
python3 scripts/compose.py --batch 8 --fade 0.3  # 分批 xfade 合成
python3 scripts/audio_mix.py --bgm audio/bgm/theme.mp3

长片模式（60 镜+） — v2.0 推荐 submit/collect 解耦：

source scripts/setup_env.sh && export AGNES_API_KEY=...
python3 scripts/generate_refs.py                 # 图生锚定前置
python3 run_pipeline.py submit --count 3         # 提交 3 镜（65s/个），存 tasks.json
python3 run_pipeline.py collect --minutes 20     # 轮询 20 分钟，完成即下载
python3 run_pipeline.py status                   # 打印进度（跨会话可续）
# 齐镜后：
python3 scripts/gen_dialogue_tts.py              # 后期 TTS 对白
python3 scripts/concat_final.py                  # 两阶段法拼接
python3 scripts/audio_mix.py --bgm audio/bgm/theme.mp3 --vo audio/vo/
# 若有烧字幕镜头：
python3 scripts/remove_subs.py --method zoomcrop --shots S09,S11,...

阶段 8 · 同步仓库 + 沉淀 trace

• 推送到目标 CNB 组织仓库（如 cnbll/self-dev/<project>）。
• 必做：确认 docs/trace.md 已记录阶段 0–8 每一步的提示词、命令、关键参数与结果摘要（skillhub trace-evaluation 要求）。
• 同时写入 output/trace.jsonl（机器可读版），格式见 references/trace_template.md。

生成的项目目录

<project>/
├── README.md
├── run_pipeline.py               # ★ v2.0 submit/collect 解耦生产入口（长片）
├── generate_shots.py             # 批量生成入口（自动发现分镜+图生锚定+长退避）
├── generate_refs.py              # 角色参考图生成器（图生锚定前置）
├── concat_final.py               # ★ v2.0 两阶段法拼接（长片用）
├── remove_subs.py                # ★ v2.0 字幕事后补救
├── gen_dialogue_tts.py           # ★ v2.0 后期 TTS 对白生成
├── compose.py                    # 分批合成（短片用，≤8镜xfade防OOM）
├── .gitignore
├── storyboard/<project>_storyboard.json
├── scripts/                      # 修复版 Agnes 流水线（scaffold 自动复制全部 13 个脚本）
│   ├── agnes_video.py  generate_shots.py  generate_refs.py  compose.py
│   ├── run_pipeline.py  gen_dialogue_tts.py  concat_final.py  remove_subs.py
│   ├── concat_segments.py  audio_mix.py  auto_finish.py  extract_last_frame.py  setup_env.sh
├── prompts/cinematography_guide.md
├── characters.md                 # ★ 角色卡（prompt 片段 + TTS 音色映射）
├── audio/
│   ├── dialogue.json             # ★ 对白数据（shot_id → 角色 + 台词）
│   └── vo/                       # TTS 生成的对白音频（vo_0030_*.mp3 = 30s 处）
├── assets/keyframes/refs.json    # ★ 角色参考图 URL（图生锚定映射）
├── docs/
│   ├── research/short_drama_research.md
│   ├── story_selection.md
│   ├── preproduction_report/preproduction_report.html
│   ├── lessons_learned.md        # ★ 踩坑复盘（音画分离铁律等）
│   └── trace.md                  # ★ 每步提示词/命令沉淀（复用关键）
├── output/
│   ├── tasks.json                # ★ submit/collect 持久化状态（跨会话续跑）
│   ├── prep/                     # 阶段 1 统一规格中间产物
│   ├── prep_clean/               # 字幕擦除后版本（若用 remove_subs）
│   ├── final/<project>.mp4       # 成片
│   ├── segments/                 # 单镜原始下载
│   └── trace.jsonl               # ★ 机器可读 trace（skillhub 评估用）
└── audio/ assets/                # 生成物（gitignore）

关键参数与坑（速查）

完整修复对照见 references/api_reference.md。

示例（已验证成品）

复用方式（一步到位）

1. 把本 Skill 目录整体复制到新项目，或 bash scripts/scaffold.sh <slug> "<名>" --mode long --ratio 9:16 起骨架。
2. 改 docs/story_selection.md 的故事 + 八段情绪弧。
3. 改 storyboard/<project>_storyboard.json（参照 templates/storyboard_example.json 结构）。
4. 改 characters.md（角色 prompt 片段 + TTS 音色）和 audio/dialogue.json（对白）。
5. 跑阶段 7 生产。全程复用 docs/trace.md 里的提示词，做到「换故事名即一步到位」。

版本历史

• v2.0.0 (2026-07-20)：聂小倩 60 镜 600s 竖屏长片实战复盘升级。5 项核心增量（音画分离铁律/竖屏模式/submit-collect 解耦/两阶段合成/字幕补救）。新增 examples/nie-xiaoqian/。新增 4 个脚本（run_pipeline / gen_dialogue_tts / concat_final / remove_subs）。新增 2 个 references（lessons_learned / trace_template）。新增 templates 目录。
• v1.1.0 (2026-06-25)：《木兰辞》24 镜 185s 横屏短片首版。8 阶段 SOP + 图生锚定 + trace 沉淀。

X402 支付接入（Pay Skill 协议）

本 Skill 已接入 SkillHub X402 Agent Pay 协议（基于 wechatpay v3 Native 支付），调用前由服务端完成预下单与支付触发，用户授权支付后 Agent 继续获取付费能力。计费模式：按调用量计费（per_call），单次调用 2.9 元（= 290 分）。

商户与密钥（已配置）

计费边界

• 计费单位：每次成功调用计 1 次（一次成功的生成/处理调用（叙事短片全流程生成））。
• 不计费场景：付费前置检查失败、参数校验未通过、签名错误导致的预下单失败、用户主动取消支付、上游 AI 服务生成失败（失败调用不计费）。
• 订单标识：out_trade_no 形如 agnes-drama-skill_<YYYYMMDDHHMMSS>_<6位随机>，幂等去重。

X402 4 步调用流程

Step 1 · 付费前置检查（precheck）

Agent 调用本 Skill 前，必须先做付费前置检查：

1. 检查 weixinpay 插件是否安装：Agent 侧调用 weixinpay_check_plugin()（或检查 weixinpay_pay 工具是否在可用工具列表）。若未安装，引导用户启用 weixinpay 插件后再调用本 Skill，否则无法完成支付触发。
2. 读取请求中的 skill_id、skill_version、调用参数；
3. 校验 pub_key_id 是否在本商户有效密钥列表内（最多 3 对，本 Skill 使用 PUB_KEY_7695C2E0CDCCE5E919DAD0E730C1B24A）；
4. 生成幂等 out_trade_no，落库待支付订单；
5. 进入 Step 2。

若 weixinpay 插件缺失，本次调用直接返回错误 "需先安装 weixinpay 插件才能完成付费调用"，不进入 Step 2。

Step 2 · 微信支付下单（WeixinPay Native）

服务端调用微信支付下单接口创建预付订单：

POST https://api.mch.weixin.qq.com/v3/pay/transactions/native
Content-Type: application/json

{
  "appid": "wx1234567890abcdef",
  "mchid": "1116760867",
  "description": "agnes-drama-skill - 单次调用",
  "out_trade_no": "agnes-drama-skill_20260925120000_834721",
  "notify_url": "https://api.hongzhaoai.com/pay/notify/agnes-drama-skill",
  "amount": { "total": 290, "currency": "CNY" }
}

返回 code_url（weixin://wxpay/bizpayurl?pr=...），用于 Step 3 的 pay_items[].pay_data.value。

Step 3 · X402 AI 预下单（payment_required 签名）

业务服务构造 payment_required 业务 JSON 并 Base64 编码：

{
  "skill_info": { "skill_id": "agnes-drama-skill", "skill_version": "1.0.0" },
  "pay_type": "SKILL_PAY",
  "pay_mode": "AUTH_AND_PAY",
  "pay_items": [
    {
      "product_id": "AGNESDRAMASK20260925001",
      "pay_data": { "type": "code_url", "value": "weixin://wxpay/bizpayurl?pr=example" }
    }
  ],
  "expires_at": 1784649665
}

用 Step 1 的 RSA 2048 私钥对以下 5 行签名串（每行以 n 结尾，最后一行也保留换行）做 SHA256withRSA：

SKILLHUB-SHA256-RSA2048
sh-GvUzjdxZ
<32位随机 nonce_str>
<Unix秒 timestamp>
<base64(payment_required)>

组装请求体：

{
  "signature_type": "SKILLHUB-SHA256-RSA2048",
  "developer_platform": "SKILLHUB",
  "developer_id": "sh-GvUzjdxZ",
  "pub_key_id": "PUB_KEY_7695C2E0CDCCE5E919DAD0E730C1B24A",
  "nonce_str": "<32位随机>",
  "timestamp": 1784648765,
  "signature": "<base64-signature>",
  "payment_required": "<base64-payment-required>"
}

调用 X402 预下单接口换取 payment_code（有效期 15 分钟）。

Step 4 · 支付触发（返回 402 + payment_code）

服务端把 payment_code 同时写入 HTTP Header 和响应体，返回给 Agent：

HTTP/1.1 402 Payment Required
WeixinPay-Required: <payment_code>
Content-Type: application/json

{
  "message": "本次调用需要支付后继续",
  "WeixinPay": {
    "WeixinPay-Required": "<payment_code>",
    "prompt": "本次使用微信支付，请将 WeixinPay-Required 的值作为 paymentCode 交给 weixinpay_pay，以向用户申请支付授权。"
  }
}

Agent 拿到 payment_code 后交给微信支付 Skill 发起用户授权；用户授权完成后，按本 Skill 业务协议继续调用获取结果。

支付后重试机制与异常处理

支付后重试机制（核心）：用户完成微信支付后，Agent 必须用相同的请求 body 重新调用本 Skill 接口（body 完全不变），并在 HTTP Header 中携带 WeixinPay-Required: <payment_code> 和 X-Pay-Token: <支付凭证>。服务端识别到支付已完成（通过 out_trade_no 查询微信支付结果），跳过 Step 1-4 的支付触发流程，直接返回业务结果。重试时 body 不能改、参数不能变，否则视为新调用需重新付费。

订单号传递与异常对账

订单号传递（核心）：每次付费调用生成的 out_trade_no 必须在支付完成后随重试请求一起传递——Agent 在重试时需在请求中携带 X-Out-Trade-No: <out_trade_no> 头部（或 body 中加 pay_trade_no 字段）。服务端按 out_trade_no 查询微信支付结果验证支付成功，然后返回业务结果。若重试时未携带订单号或支付凭证，服务端无法关联支付记录，将再次返回 402 触发新一轮付费。

• 传递链：服务端生成 out_trade_no → 微信下单 → payment_required.skill_info 关联 → payment_code 返回 Agent → 支付完成后 notify_url 回调 → 服务端按 out_trade_no 更新订单为已支付 → T+1 结算到绑定商户号。
• 对账依据：以微信支付回调或 out_trade_no 查询结果为准；SkillHub 商户中心提供调用与结算明细。

本 Skill 的 X402 接入遵循 SkillHub 官方《升级为 Pay Skill》规范（https://www.skillhub.cn/tutorials#agent-pay-upgrade）。

由 鸿爪派 出品。