# Autodsj

> AutoDSJ 电视剧/短剧全自动解说剪辑工作流。用户说“AutoDSJ”“剪辑某剧”“跑第N集”“出成片”，或 asks to automate drama recap video editing, diagnose mismatched visuals, build a scene map, or rerun an episode 时使用。强制使用完整大场景地图、字幕/剧本混合检索、父段全局序列解码和60～240帧选择性云端视觉复核。

- Skill: `dabaoagent/autodsj` (Agent Skill, multi-file: 22 files)
- Install (CLI): `npx skillmds@latest add dabaoagent/autodsj`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dabaoagent/autodsj/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: DaBaoAgent (https://skillmd.com/u/dabaoagent)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/dabaoagent/autodsj

---


# AutoDSJ 工作流

## 唯一技能源与同步

只修改 Git 仓库中的 `skills/autodsj`。它是 Claude Code、Codex、Hermes、OpenCode 和 OpenClaw 共用的唯一源；不得把任一 Agent 的部署目录当作源文件直接迭代。每次修改后先校验并提交 Git，再运行：

```powershell
cd <AutoDSJ 仓库根目录>
python scripts\install_autodsj_skill.py --agent all
python scripts\install_autodsj_skill.py --agent all --check
```

安装器按每个文件 SHA-256 镜像校验目标目录。可传入 `--agent claude|codex|hermes|opencode|openclaw|shared` 只安装一个 Agent；`shared` 写入 `~/.agents/skills`，适合 OpenCode/OpenClaw 的通用发现路径。旧 Hermes 目录仅在必须兼容既有安装时使用 `--agent legacy-hermes`。

项目根目录和 Python 环境必须从当前工作区发现，不得照抄任何机器的绝对路径。换电脑或项目路径变化时，先读 [portable-deployment.md](references/portable-deployment.md)。

本工作流无 WebUI、无端口，只走 `autodsj.py` 这一条 CLI 管线。配音只用百炼 Qwen 克隆音色。**音量硬性规范：`voice.volume=100`、`drama.source_play_volume=100`，配音与原片再分别经 `loudnorm=I=-16:TP=-1.5:LRA=11` 归一化到 -16 LUFS 等响**。不得用 120%/50% 等纯增益组合代替响度归一化。

## 不可跳过的顺序

### 1. 先审校文案

读取目标单集目录及子目录的 `.txt/.md/.docx` 源文案，不得直接开跑。检查：

- `原片：` / `解说：` 结构完整；
- 开头冲突或悬念足够强，信息递进、因果和结尾追更钩子合理；
- 角色名、他/她、人物关系、动作主体和字幕同音字正确；
- 每段主要推进一个事件，只有尾句可承接下一场景。

《玫瑰的故事》必须读 `references/rose-story-knowledge.md`，并查 `references/rose-story-episodes.json` 的对应集。

### 2. 先建文本和物理镜头索引

```powershell
cd D:\@kaifa\AutoDSJ\project
$PY = ".\.venv\Scripts\python.exe"
& $PY autodsj.py preflight --folder "<单集素材夹>"
& $PY autodsj.py script --folder "<单集素材夹>"
& $PY autodsj.py shots --folder "<单集素材夹>"
```

不要恢复旧的每 8～10 秒抽一帧、全片约 280 帧的 VL 扫描。先以 SRT、审校剧本和物理镜头关键图编完整场景地图；昂贵视觉只在文本缩小候选后运行。

新集还没有 `★ 匹配报告.json` 时，允许一次不渲染引导：

```powershell
& $PY autodsj.py run --folder "<单集素材夹>" --skip-visual --no-render
```

### 3. 建完整大场景地图

在正式匹配或渲染前，必须完整查看原片时间轴，写好 `<素材夹>\_scene_map.json`。原片有多少个完整大场景，`scenes` 就必须有多少个；不得只画文案提到的几个。

必须满足：

- `coverage_reviewed: true`；
- `scene_count == scenes.length`；
- `coverage_ranges` 全部被各大场景连续覆盖，无空洞；
- 每个解说镜头只能落在唯一的父段场景计划中；
- 一段解说默认只有一个主场景；
- 最多允许“整段主场景 → 更短的尾句承上启下场景”；
- 禁止三场景跳转、短前导后长跳转、候选扩窗越出指定大场景。

**效率技巧**：建场景地图时用 `execute_code` 批处理——一次性读取视觉索引用 `print` 输出完整时间轴（time+people+caption），据此划分场景边界，然后写 JSON 到磁盘并立即 `from backend.scene_map import validate_scene_map` 验证，避免多轮 terminal/read_file 来回。

具体 JSON 契约见 `references/hierarchical-shot-matching.md`。新集从零编写场景地图的实操
（先跑 `run --skip-visual --no-render` 引导出 `★匹配报告.json`，据它定 `parent_scene_plans`
的键=`tts_parent_id`、`to_shot`=各段真实分镜数；交叉剪辑剧集用「多 range 场景按剧情线分组」
但所有 range 须划分时间轴不重叠），以及渲染后用人脸库核验成片的完整方法，见
`references/scene-map-authoring-and-verification.md`。

### 4. 建分层镜头并影子匹配

```powershell
& $PY autodsj.py events --folder "<单集素材夹>"
& $PY autodsj.py shadow-match --folder "<单集素材夹>"
& $PY autodsj.py visual --folder "<单集素材夹>" --target-frames 90
& $PY autodsj.py shadow-match --folder "<单集素材夹>"
```

固定层级：`大场景 → 连续事件块 → 物理镜头 → 动作瞬间`。

固定证据顺序：SRT/审校剧本 BM25 → 文本向量 → 可选 CAM++ 角色声纹 → 父段 Viterbi → 60～240 帧选择性云端视觉复核 → 高风险候选前/中/后三帧对比。所有证据只能在父场景内排序，不能将镜头拉到场景外。详细契约见 `references/hybrid-evidence-matching.md`。

`narration_intent.py` 必须区分检索扩展词和视觉硬条件。关系“靠近”、心理“后退”等隐喻可以辅助文本召回，但不得写进 `hard_requirements.actions`；只有明确可见动词、人物、地点和道具才能成为 `must_have`。显式“不是/并非/不要/没有/而非”写入 `must_not_have`，不得反向扩展成正向要求。

时间线固定使用两轮分配：第一轮在全部候选中选择全局未用画面；只有第一轮完全无解时，父段计划才允许第二轮复用已引用的原片对白画面。`planning_summary.strict_fresh` 应尽量等于解说镜头数，`source_reuse_fallback` 应为 0 或极小。广告区在两轮中都是绝对硬禁区，父段计划、人工 override 和复用降级均不得绕过。

`shadow-match` 会生成 `_selective_visual_plan.json`。计划按风险在 60/90/120/180/240 帧间自主选择（上限 240）；计划未完成时，候选或场景图变化会使旧视觉索引失效；一旦同一素材、同一场景地图的计划完整识别，后续影子匹配必须锁定该通用计划，禁止因新视觉描述改变候选排序后反复推翻整套计划。人工修改场景地图 SHA 时锁定自动失效；普通候选变化交给 `_candidate_visual_review.json` 的独立多帧复核处理。运行 `visual` 后必须再跑一次 `shadow-match`。视觉 API 运行期间可读 `_source_visual_index.json` 的 `status/message` 监控进度。

高风险候选复核最多处理 `matching.candidate_review_max_segments` 个解说句；基础层每个候选取物理镜头前/中/后三帧，候选数不足时允许单候选硬确认，但绝不越过 `_scene_map.json` 补候选。人物身份只认 InsightFace；云端只能确认动作、地点、道具和可见事实。完整结果可缓存，`partial` 结果续跑时只重试失败组。

基础层仍 unresolved 时，默认只对这些段运行二级复核：把同一场景内候选从3个扩大到5个，每候选取7帧（8%～92%均匀覆盖），写入 `_candidate_visual_escalation.json`，不得重跑已通过段或锁定的120帧通用索引。超大多图请求被远端断开时，保持本地7帧人脸核验，但云端可均匀降为每候选5帧、再降为3帧；基础请求可降为2帧、再降为1帧，候选数量与身份硬门禁不变。候选缓存只有在候选 ID 顺序和帧数完全一致时才可复用。加帧后仍稳定出现错误人物，说明候选镜头错，应扩大同一父场景内候选数量或修正场景地图，禁止继续无上限加帧或跨场景搜索。`candidate_visual_review_ready=false` 或任一复核句 `unresolved` 时，`safe_to_render` 必须为 false。

有干净角色对白参考时启用 CAM++：

```powershell
uv pip install --python $PY -r requirements-audio.txt
uv pip install --python $PY --no-deps speakerlab==0.0.6
# <剧集根>\_voices\<角色名>\*.wav
& $PY autodsj.py voices --folder "<单集素材夹>"
```

缺 `speakerlab` 或参考音频时允许字幕/剧本路径运行，但报告必须显示 `voice_index=false`，不得声称声纹已生效。

必须检查：

- `★ 分层影子匹配报告.json`；
- `★ 新旧匹配并排对比.json`；
- `★ 分层接管预演报告.json`。
- `_subtitle_event_index.json`、`_selective_visual_plan.json`；有声纹时还要 `_source_voice_index.json`。

只有 `safe_to_render=true` 且 `unresolved=0` 才能渲染。地图、文案、分镜或配音变化后必须重跑 `shadow-match`；不得手改报告绕过哈希和时间线校验。

### 5. 先预跑，再成片

```powershell
& $PY autodsj.py run --folder "<单集素材夹>" --skip-visual --no-render --hierarchical-match
& $PY autodsj.py run --folder "<单集素材夹>" --skip-visual --hierarchical-match
```

正式渲染不带 `--hierarchical-match`、缺场景地图、地图不完整或预演哈希失效时，必须停止，不允许降级到旧匹配方法。

## 人脸库

换新剧或人物容易混淆时，在剧集根目录放 `_faces/<角色>/*.jpg`，每个主要角色 3–5 张清晰正脸，再运行：

```powershell
& $PY autodsj.py faces build --folder "<单集素材夹>"
```

## 成片交付

正式渲染完成后，管线必须自动执行发布交付，不得等用户再次提醒。只有以下文件全部生成并通过门禁，才允许报告“成片完成”：

- `★ 成片.mp4`：可读取时长和视频流；
- `★ 字幕.srt`：可解析，末条字幕不得越过片尾；
- `★ 匹配报告.json`；
- `★ 发布信息.txt`：3 个标题、剧情简介、互动问题、严格 5 个标签、封面文案和实际成片参数；
- `★ 剪映字幕导入.txt`：同时包含原片对白和解说，删除分段标签与空行，保持源文案顺序；
- `★ 交付清单.json`：记录上述文件、视频参数、字幕/文案行数及待复核指代词行数，状态必须为 `ready`。

交付门禁通过后，单集根目录必须只保留原片、原片字幕、源文案、`★ 成片.mp4`、`★ 发布信息.txt`、`★ 剪映字幕导入.txt` 和 `_AutoDSJ工作文件`。`★ 字幕.srt`、匹配报告、场景地图、索引、TTS、裁切片及交付清单全部自动移入 `_AutoDSJ工作文件`。下一次执行处理命令时自动恢复这些资产，成片后再次归档；禁止因整理目录而删除可复用的场景图、声纹或缓存。

交付门禁已接入 `autodsj.py run` 的正式渲染末尾。已有成片缺交付文件、或人工修改文案后只需重建发布包时，运行：

```powershell
& $PY autodsj.py deliver --folder "<单集素材夹>"
```

`scripts/audit_pronouns.py` 和 `scripts/make_jianying_srt_txt.py` 仅用于人工诊断/单文件修复，不再是正式流程的必需手工步骤。向用户交付时报告成片、SRT、匹配报告、发布信息、剪映字幕和交付清单路径。

用户要求保留旧成片时，先复制到单集子目录，再渲染；不要在主目录放多个可被误识别的源视频。

## 安全清理

只在成片存在且验收后执行：

```powershell
& $PY autodsj.py clean --folder "<单集素材夹>"
```

该命令不再删除资产，而是把根目录中的工作文件统一归档到 `_AutoDSJ工作文件`。必须保留原片、原片字幕、源文案和三项公开交付文件。

## 快速排错

- 整段乱跳：先查 `_scene_map.json` 和 `parent_scene_plans`，不要扩大时间窗。
- 人物错：检查父场景是否选错，再补人脸参考照。
- 动作错：检查事件块、物理镜头的多关键帧和 SRT，不得跳出父场景找高分帧。
- 动作句的人工 `override` 必须锚定动作起点而非动作后的对白/反应字幕；渲染前抽取该源片范围和对应成片范围的连续帧，确认动作起势、发生、结果都落入计划片段。只看到动作结果（例如人已在水里）不能算命中“推入水里”。
- 独立 `quality` 复查必须按 `_AutoDSJ工作文件`、素材根目录、旧 `_DY工作文件` 的顺序寻找最新报告与索引；`HIGH` 人物缺失是人工复核告警，不能替代候选门禁，也不能仅凭云端未写角色名就判定真实错配。
- 改了文案：重跑脚本表与 `shadow-match`。若新的 `_selective_visual_plan.json` 使视觉索引过期，再跑默认 `visual`（风险自适应60～240帧），不要恢复固定间隔密集全片扫描。
- 匹配慢：先检查 `_event_text_embeddings.json` 和 `_query_text_embeddings.json` 是否存在；内容不变时第六集93镜实测重匹配约7秒。
- 多集任务：串行渲染，不要同时吃满笔记本 CPU/内存/磁盘。
- **场景地图覆盖空洞**：`validate_scene_map` 报 `覆盖存在空洞` 时，常见原因：(a) `coverage_ranges` 包含了没有视觉帧的广告区间——把广告区从 `coverage_ranges` 移除，或拆成多段 `[[150, 978], [1001, 2668]]`；(b) 某场景 `ranges` 结尾与下个场景开头有间隔——逐场景检查 `scenes[].ranges` 的连续性，确保相邻场景首尾相接（允许广告区打断）。`excluded_ranges` 不影响覆盖校验，只影响匹配，广告区必须从 `coverage_ranges` 移出而非只写在 `excluded_ranges`。
- **场景地图写入顺序**：先用 Python 写 `_scene_map.json` 到磁盘，再 `validate_scene_map` 验证。`validate_scene_map` 从磁盘读取场景地图，不是从内存。先写后验，不要反过来。

三个「别慌」信号（都不是故障，详见 `references/scene-map-authoring-and-verification.md`）：

- 渲染日志刷 `[场景锁定] 行N-镜M → 「场景」` 且与 `parent_scene_plans` 不符——那是旧分配器过渡噪声，随后的 `分层匹配正式接管：N 个解说分镜` 会整段覆盖，以接管后置信度全 `H` 的 `★匹配报告.json` 为准。
- 接管后必须分别检查解说复用和原片明确复引。解说画面与任何已用片段重叠都应先消除；只有文案明确重复引用同一句原片对白、且必须保持口型与原声时，才允许记录为必要例外。
- 「独立爆款版」短文案出片仅 2-3 分钟——正确。成片时长 = Σ解说配音 + Σ原片对白，由文案长度决定；引导日志「解说目标约2490s(90%)」只是按原片长度的默认假设，不代表漏渲染。

- **广告禁区误封**：当前 `backend/ad_filter.py` 会把“墙上的小广告、办证刻章、柱子上的广告字迹”等场景陈设排除，只把明确的广告插播、品牌/产品展示或字幕商业话术设为硬禁区；`shadow-match` 也会根据当前字幕和视觉索引重新生成 `_source_ad_intervals.json`，不得复用陈旧广告缓存。若正式预跑仍报广告冲突，检查该文件的 `reasons`：纯视觉信号必须包含明确商业语境，不能只有墙面招贴。详细诊断见 `references/ad-filter-false-positive-fix.md`。

项目的完整命令与数据结构以 `D:\@kaifa\AutoDSJ\project\README.md` 为准。

## 耗时参考

单集全流程端到端耗时约 **40-80 分钟**，主要瓶颈：

| 阶段 | 耗时 | 备注 |
|------|------|------|
| 初始 visual（36帧） | 5-10分钟 | SiliconFlow Qwen VL API |
| 引导 scaffold（TTS+匹配） | 5-10分钟 | 百炼 TTS 偶尔 SSL 重试 |
| 场景地图编写 | 1-2分钟 | execute_code 一次性完成 |
| events + shadow-match | 2-5分钟 | 文本嵌入是主要开销 |
| 选择性 visual（60～240帧） | 5-45分钟 | 取决于帧数、并发与云端长尾；可续跑 |
| shadow-match 再跑 | 2-3分钟 | |
| 预跑 + 正式渲染 | 20-40分钟 | TTS 复用缓存 + FFmpeg 编码 |

**多集批量（4集实测）**：串行交错模式，总耗时约 **4-5小时**。
具体做法：在上一集渲染（FFmpeg 编码约15-30分钟）期间，为下一集做全部准备工作（preflight→visual→script→shots→scaffold→场景地图→events→shadow-match→visual selective），等上一集成片时下一集已就绪可立即开跑。

**常见延时因素**：
- 视觉 API 超时（SiliconFlow 429/500），重试可续跑
- 百炼 TTS SSL EOF 错误，管线内置重试自动恢复
- 广告误封先检查 `_source_ad_intervals.json` 的 `reasons`；当前管线会自动排除墙面小广告/办证招贴等场景陈设，无需改写视觉索引

## 新集并行准备（2026-07）

新集默认先运行：

```powershell
$PY autodsj.py prepare --folder "<单集文件夹>"
```

该命令并行建立脚本表与物理镜头索引，生成事件索引、
`_scene_map.draft.json` 和风险自适应的 60/90/120/180/240 帧云端视觉计划，再以有界并发执行
稀疏抽帧和批量视觉识别。视觉完成后自动把识别证据回填到镜头/事件索引，不重跑镜头边界。

草案始终为 `coverage_reviewed=false`，不得直接用于正式成片。人工核对完整覆盖、场景边界、
广告排除和父段计划后，另存为 `_scene_map.json` 并设置 `coverage_reviewed=true`。
只生成索引和草案时使用 `autodsj.py prepare --skip-visual`；显式固定视觉预算时使用
`--target-frames 60..240`，否则保持风险自适应。