# adr

Adopt this skill: https://proskills.md/skills/other/sirius-777-llm-adr

Page: https://proskills.md/skills/other/sirius-777-llm-adr
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: README.md
upstream: https://github.com/sirius-777-llm/adr/blob/HEAD/README.md

````text
# ADR — Automated Documentary Rendering

ADR 是一套自动纪录片生成管线。输入一个主题或带时间戳的台词，输出带画面、配音、字幕、BGM 的横屏或竖屏视频，并把过程状态和成片推送到 Telegram。

本 README 是 ADR 的产品契约：模式名、默认行为、质量兜底和禁止误触发规则必须和代码保持一致。每次改动 `run_adr_v8.py` 或 Telegram 启动器时，都要同步更新这里。

## 当前模式

| 模式 | 画幅 | 触发 | 含义 |
|---|---:|---|---|
| `HADS` | 16:9 | `h` | 横屏动态纪录片（默认），WeryDance 逐分镜动态化 |
| `VADS` | 9:16 | `v` | 竖屏动态纪录片（默认），WeryDance 逐分镜动态化 |
| `HADR` | 16:9 | `h --no-motion` | 横屏静态分镜叙述（罕用） |
| `VADR` | 9:16 | `v --no-motion` | 竖屏静态分镜叙述（罕用） |
| `HADSD` | 16:9 | `h --ads-dialogue` | 横屏多角色对话纪录片 |
| `VADSD` | 9:16 | `v --ads-dialogue` | 竖屏多角色对话纪录片 |
| `HMTV` | 16:9 | `hmtv` 或 `h --mtv` | 横屏原创音乐 MTV，WeryAI VOCAL_SONG + WeryDance |
| `VMTV` | 9:16 | `vmtv` 或 `v --mtv` | 竖屏原创音乐 MTV，WeryAI VOCAL_SONG + WeryDance |

重要边界：

- `HADS/VADS` 只表示"动态纪录片"，不等于现场记者。
- 只有显式传 `--ads-reporter`，或用户明确说"拟现场记者 / 战地记者 / dispatch / 第一人称记者 / POV 记者"，才进入记者 POV。
- `--ads-dialogue` 和 `--ads-reporter` 互斥；多角色对话优先。
- ADSD 走 step66 lip_sync，不参与 step65 motion；`--no-motion` 对 ADSD 无效。
- MTV 是独立音乐视频管线，不走普通旁白 TTS / Whisper 字幕时间轴；主音轨来自 WeryAI `VOCAL_SONG`。
- MTV 主唱通过 `--singer <名字>` 指定；如果主唱已存在于 `voice_assets/speaker_ips/`，直接复用人物卡和绑定音色；如果不存在，自动孵化人物卡并写入人物库。
- MTV 默认烧录歌词字幕；先用歌曲 ASR 建立“声音/字幕/视频”共享时间轴，再按该时间轴生成前奏、歌词和尾奏镜头；人声段默认尝试歌曲音频驱动 lip-sync（`ADR_MTV_LIP_SYNC=0` 可关闭），失败时降级普通动效；可用 `ADR_MTV_SUBTITLES=0` 关闭字幕。

## 默认策略

| 能力 | 默认 | 说明 |
|---|---:|---|
| GPT Image 2 故事板 | 开 | 主线分镜优先生成故事板和网格故事板 |
| Storyboard reference motion | 开 | WeryDance 动态化优先吃 clean keyframe / storyboard 参考 |
| Motion action storyboard | 开 | 每个分镜生成动作起点、过程、终点，避免人物发呆 |
| Motion bridge refs | 开 | 为关键镜头补终点参考图，提升动作幅度 |
| WeryDance 字幕 | 开 | 默认交给 WeryDance 生成字幕，ASS 硬字幕作为兜底 |
| LLM 跨模型容错 | 开 | 主模型遇到 5xx 或模型下线时自动切备用模型，429 仍按原模型退避 |
| 音色资产库 | 开 | 男声默认罗翔，女声默认 BY2，可用环境变量覆盖 |
| 严格音色锁定 | 开 | Motion prompt 会显式锁定声音资产和人物性别 |
| Telegram 进度 | dashboard | TG 只保留一条可编辑进度面板，显示进度条、当前阶段和最近日志 |
| BGM-only | 关 | `--bgm-only` 跳过 TTS，只保留画面、字幕、BGM |

## 架构

```text
主题 / 台词输入
  |
  |-- Step 1: 剧本、考证、分镜
  |   |-- 题材分析：文化、地域、年代、服饰、负面禁令
  |   |-- 台词生成或外部台词解析：支持带时间戳文本
  |   |-- 历史顾问：校准时代视觉，避免文化和年代穿帮
  |   |-- 分镜提示词：画面、角色、镜头、情绪、动作
  |
  |-- Step 2: 配音 / 音色
  |   |-- 普通 ADR：Podcast/TTS 生成整段音轨
  |   |-- ADSD：逐 turn 配音，支持口型同步
  |   |-- WeryDance audio-dub：可用音色资产参考音频完成视频内配音
  |
  |-- Step 3: 时间轴
  |   |-- Whisper 字级时间戳
  |   |-- 外部带时间戳台词优先
  |   |-- 字幕、画面、音频按分镜对齐
  |
  |-- Step 4: 故事板
  |   |-- GPT Image 2 单镜故事板
  |   |-- 4K storyboard grid / 多 storyboard fallback
  |   |-- crop QA，避免切到相邻格
  |
  |-- Step 5: 静态画面和封面
  |   |-- 分镜图并发生成
  |   |-- 失败重试，必要时重写 prompt
  |   |-- Telegram 图片审批可选
  |
  |-- Step 6.5: WeryDance 动态化
  |   |-- clean keyframe 优先，其次 annotated storyboard 实验模式
  |   |-- 每镜头 motion prompt + 动作计划 + 可选终点参考
  |   |-- 失败镜头保留静态兜底，不中断整片
  |
  |-- Step 7: 合成
  |   |-- ffmpeg 拼接视频
  |   |-- WeryDance 字幕优先，ASS 字幕兜底
  |   |-- 配音、BGM 混音
  |
  `-- Step 8: QA 和交付
      |-- motion_qa.json
      |-- storyboard / crop / caption / voice QA
      |-- Telegram 推送成片和文案
```

## 快速开始

```bash
export WERYAI_API_KEY="your-key"
export TG_BOT_TOKEN="your-bot-token"
export TG_CHAT_ID="your-chat-id"

python3 run_adr_v8.py "1924年泰戈尔访华" h
python3 run_adr_v8.py "黄仁勋CMU毕业演讲核心内容" h
python3 run_adr_v8.py "1915年二十一条最后通牒" v --ads-reporter
python3 run_adr_v8.py "AI时代就业市场访谈" h --ads-dialogue
python3 run_adr_v8.py "江南春日风物" v --bgm-only
python3 run_adr_v8.py "曹操的短歌行" hmtv --singer 曹操
python3 tools/mtv_sync_audit.py /tmp/adr_v8_xxx
python3 run_adr_v8.py "唐宋八大家" h --no-motion          # 罕用：HADR 静态分镜
```

## 常用参数

| 参数 | 用途 |
|---|---|
| `h` / `v` | 横屏 16:9 / 竖屏 9:16，默认 HADS/VADS 动态化 |
| `--no-motion` | 退化为 HADR/VADR 静态分镜叙述（罕用） |
| `--ads-reporter` | 开启第一人称现场记者 POV |
| `--no-ads-reporter` | 强制禁止 reporter |
| `--ads-dialogue` | 开启多角色对话纪录片 |
| `--adsd-lip-sync` | ADSD 口型同步实验 |
| `hmtv` / `vmtv` | 横屏 / 竖屏原创音乐 MTV |
| `--mtv` | 在 `h` / `v` 画幅下开启 MTV 模式 |
| `--singer <name>` | MTV 主唱；命中人物库则复用，否则自动创建人物卡 |
| `--bgm-only` | 无旁白，仅画面、字幕、BGM |
| `--skip-approval` | 跳过 Telegram 图片审批 |
| `--with-approval` | 强制开启 Telegram 图片审批（默认关闭） |
| `--speaker <id:name>` | 指定 Podcast 音色 |

## 关键环境变量

| 变量 | 默认 | 用途 |
|---|---:|---|
| `ADR_GPT_IMAGE2_STORYBOARD` | `1` | 开关故事板 |
| `ADR_DEFAULT_STORYBOARD_GRID` | `1` | 开关默认 storyboard grid |
| `ADR_GPT_IMAGE2_STORYBOARD_GRID_BATCH` | `12` | storyboard grid 默认 12 宫格；横屏 4x3、竖屏 3x4，超出自动拆批 |
| `ADR_STORYBOARD_REFERENCE_MOTION` | `1` | 动态化使用故事板参考 |
| `ADR_STORYBOARD_ANNOTATED_MOTION` | `0` | 使用 annotated storyboard 喂 WeryDance |
| `ADR_MOTION_ACTION_STORYBOARD` | `1` | 动作计划故事板 |
| `ADR_MOTION_BRIDGE_REFS` | `1` | 终点关键帧参考 |
| `ADR_WERYDANCE_CAPTIONS` | `1` | WeryDance 字幕优先 |
| `ADR_DEFAULT_MALE_VOICE_ASSET` | `external_luo_xiang_xyma_001` | 默认男声音色资产 |
| `ADR_DEFAULT_FEMALE_VOICE_ASSET` | `external_by2_e7gn_001` | 默认女声音色资产 |
| `ADR_DEFAULT_VOICE_ASSET` | 空 | 全局强制默认音色资产 |
| `ADR_MOTION_VOICE_STRICT_LOCK` | `1` | 严格锁定音色和人物性别 |
| `ADR_CREATIVE_MODEL` | `GPT_5_6_SOL` | 旁白、对话、Producer Brief 与视觉导演主模型 |
| `ADR_CREATIVE_FALLBACK_MODELS` | `CLAUDE_4_8_OPUS,GEMINI_3_7_FLASH,GEMINI_25_FLASH` | 主创节点的有序多级降级链 |
| `ADR_JUDGMENT_MODEL` | `GEMINI_3_7_FLASH` | 题材、基调、规划、审稿及严格 JSON 任务 |
| `ADR_JUDGMENT_FALLBACK_MODELS` | `GEMINI_25_FLASH` | 判断/JSON 节点的降级链 |
| `ADR_VISION_MODEL` | `GEMINI_3_7_FLASH` | 分镜异常检测与封面质检 Vision 模型 |
| `ADR_VISION_FALLBACK_MODELS` | `GEMINI_25_FLASH` | Vision 遇 5xx/模型下线时的有序降级链 |
| `ADR_CHAT_FALLBACK_MODELS` | 空 | 任意直接 `chat()` 调用的逗号分隔多级备用；优先于旧单值 |
| `ADR_CHAT_FALLBACK_MODEL` | `GEMINI_25_FLASH` | 旧单备用配置，仅在未设多级链时使用 |
| `ADR_ADS_REPORTER_ALLOW_ENV` | 空 | 允许环境变量触发 reporter，默认不允许 |
| `ADR_ADS_REPORTER` | 空 | reporter 环境开关，需配合上一项 |
| `ADR_TG_PROGRESS_MODE` | `dashboard` | TG 推送模式：`dashboard` / `compact` / `verbose` / `silent` |
| `ADR_TG_DIGEST_INTERVAL_SEC` | `120` | compact 模式下过程摘要最小间隔 |
| `ADR_TG_DASHBOARD_EDIT_INTERVAL_SEC` | `8` | dashboard 模式下进度面板最小编辑间隔 |
| `ADR_GPT_IMAGE2_STORYBOARD_GRID_SUBMIT_STAGGER` | `12` | storyboard grid 任务错峰提交间隔，避免同时请求 |
| `ADR_GPT_IMAGE2_STORYBOARD_GRID_POLL_WORKERS` | `20` | storyboard grid 提交后并发轮询/下载/裁剪 worker 数 |
| `ADR_GPT_IMAGE2_STORYBOARD_SUBMIT_STAGGER` | `12` | 单图 storyboard fallback 错峰提交间隔 |
| `ADR_GPT_IMAGE2_STORYBOARD_POLL_WORKERS` | `20` | 单图 storyboard fallback 并发轮询/下载 worker 数 |
| `ADR_MOTION_BRIDGE_REFS_SUBMIT_STAGGER` | `12` | motion bridge end keyframe 错峰提交间隔 |
| `ADR_MOTION_BRIDGE_REFS_POLL_WORKERS` | `20` | motion bridge end keyframe 并发轮询/下载 worker 数 |

2026-09-06 同 prompt 主创 A/B：`GPT_5_6_SOL` 在 22 镜视觉 JSON 中实现 22/22 对象、8/8 字段及所有 enum/字数/首尾约束通过；`CLAUDE_FABLE_5` 有超长与截断，`CLAUDE_4_8_OPUS` 出现间歇 5xx，因此未设为首选。判断档另以 180/200/300/600/800 token 的五类生产近似任务对照：`GEMINI_3_7_FLASH` 5/5 正常停止且格式通过，`GEMINI_25_FLASH` 4/5（严格 JSON 出现 Markdown fence）。

文本降级配置优先级为：调用点显式 `fallback_models` > 全局多值 `ADR_CHAT_FALLBACK_MODELS` > 旧单值 `ADR_CHAT_FALLBACK_MODEL` > 主创/判断分档默认链。5xx 与模型下线错误会推进到下一模型；429 只在当前模型退避，不跨模型。Vision 同样遵循 429 原模型退避策略。

## Telegram 进度策略

默认 `dashboard` 模式下，ADR 只发一条可编辑进度面板，后续用 Telegram `editMessageText` 原地更新，类似软件安装进度：

- 面板内容：主题、阶段、百分比、进度条、当前状态、最近日志、更新时间。
- 强制刷新：启动、剧本、主音轨、故事板、动态化、合成、发布门禁、成片、耗时统计、告警和错误。
- 限频刷新：普通过程日志最多每 8 秒编辑一次，避免 Telegram API 限流。
- 最终视频、封面、社媒文案、复制按钮仍单独发送，因为这些是交付物，不应该被进度面板覆盖。

`compact` 模式保留为备用，会把过程信息分为三层：

- 立即发送：启动、剧本完成、主音轨完成、故事板完成、动态化启动/完成、视频拼接、发布门禁、最终成片、耗时统计、所有告警和错误。
- 合并摘要：单张图完成、单个分镜动态化成功、Podcast task_id、轮询类信息、重复审批进度。
- 本地日志：所有细节仍写入 stdout/log，调试时可设 `ADR_TG_PROGRESS_MODE=verbose` 恢复全量推送。

目标是让 TG 对话框里能直接看到“现在跑到哪、有没有风险、最终文件在哪里”，不需要在几十条过程消息里捞结果。

## 音色资产库

音色资产配置位于 `voice_assets/voice_assets.json`。当前库中包含候选资产：

- `external_luo_xiang_xyma_001`：罗翔，默认男声。
- `external_by2_e7gn_001`：BY2，默认女声。
- `external_xu_zhiyuan_xyma_001`：许知远，访谈/文化类备选。
- `external_huang_renxun_fzh_001`：黄仁勋，英文科技领袖演讲备选。

外部人物声音默认只允许内部测试和分析；公开发布、商业用途、拟真冒充必须另行做权利审查。

## QA 检查点

每次改管线后至少验证：

- `python3 -m py_compile run_adr_v8.py`
- HADS/VADS 不带 `--ads-reporter` 时，日志必须显示 `HADS/VADS`（或 `--no-motion` 下 `HADR/VADR`），不能出现"拟现场记者"。
- `motion_qa.json` 里应记录参考图数量、字幕策略、音色策略。
- storyboard crop QA 不能把两个分镜切在同一张输出里。
- WeryDance 字幕失败时，ASS 兜底必须仍能合成。
- 自定义音色任务要检查声音性别、画面人物性别、台词内容三者一致。

## README 更新规则

README 只写已经落地并通过基础 QA 的能力，不写愿景。每次新增默认开关或改变模式含义时，要同步
````
