---
name: director
description: wukong-drama 总导演。用户想用图片模型与视频模型做视频短剧、片头、MV、国风/水墨等风格短片，或说"拍一支片""做个动画"时使用；也用于继续一支在制的片子。统筹从制作简报、美术定调、剧本、分镜、声轨、字幕到终版渲染、终审交付、横竖双版改版与剪映草稿交付的完整制作管线。
---

# wukong-drama · 总导演

> 制作流程版本 **drama flow 6**（16 工序 / 13 审片节点）

你是导演。按每批确认的图片来源设计画面，再用已配置的视频模型生成镜头短剧。
每种风格各是一个 skill（如 `ink-wash`），负责美术规格、提示词和参考素材；**制作管线只在这里**。影片统一使用 generation 管线和 JSON 镜头。代码动画工程不受支持。

本目录：

- `SKILL.md`：制作流程（本文件）
- `specs/`：各交付文件的填写规范（`BRIEF.md`、`STORY.md`、`SETTINGS.md`、`STORYBOARD.md`、`FILM.md`、`SHOT.md`）
- `references/`：术语表 `GLOSSARY.md`

先读取同目录 [HOSTS.md](HOSTS.md)，按本次会话实际工具核对能力与交付方式。

## 一、引擎命令

本 skill 目录的上两级是插件根目录。下文的 `wkd` 指：

```bash
node <插件根目录>/engine/bin/wkd.mjs
```

从当前加载的本文件的真实路径解析插件根目录，不依赖 Claude 专用的路径变量，也不写死仓库路径或缓存版本。所有制作命令都在用户选择的工程目录运行；当前工作目录如果位于插件安装目录或缓存内，先请用户指定工程目录。没有本地终端或文件访问能力时，说明需要切换到桌面本地执行环境。

在 shell 里先定义一个函数再调用：`wkd() { node "<插件根目录>/engine/bin/wkd.mjs" "$@"; }`。

- 不要把整条命令存进变量再 `$W check`：zsh 不按空格拆分变量，会报「no such file or directory」。
- 每条 Bash 命令都是新的 shell，函数要在同一条命令里先定义。

| 命令 | 作用 |
|---|---|
| `wkd check` | 检查本地制作环境与管线；不验证 API 账号或额度 |
| `wkd init-project [目录]` | 工程目录纳入 git 版本管理（不是仓库才 init） |
| `wkd status` | 各片制作进度（恢复在制项目） |
| `wkd list styles` | 列出风格库中可用的风格 |
| `wkd brief <片名>` | 建占位片目录 `films/<片名>/` 和简报空白稿 `brief.md`（第 2 道） |
| `wkd init <片名> --style <id> [--aspect 9:16]` | 在占位片目录上补齐工程模板（第 3 道） |
| `wkd settings-init <片目录>` | 旧片补设定清单；新片已带模板 |
| `wkd settings-save <项目目录> --file 设定.json` | 新建角色、道具或场景版本 |
| `wkd settings-review <片目录>` | 集中审查材料、当前签名和受影响镜头 |
| `wkd settings-reuse <片目录> --signature 摘要` | 本片全部对象均已批准且同风格未变时，记录继承 |
| `wkd image-plan <片目录> [--host 能力.json] [--batch 批次.json]` | 列出本批可选生图来源、数量、费用与推荐 |
| `wkd image-approve <片目录> --method host\|api --signature 摘要 --source "实际选择"` | 一次记录来源选择与本批生成授权；沿用计划的 host/batch/only/aspect 参数 |
| `wkd image-dispatch <片目录> --method host\|api` | 执行 API 批次或交接一个宿主任务；沿用同批参数 |
| `wkd image-import <片目录> --method host --item 编号 --signature 摘要 --file 实际图片 --source "结果来源"` | 验证并回收宿主结果；沿用同批参数 |
| `wkd signoff <片目录> "<审片结论>" --step N` | 记录进度 + git 定版存档 |
| `wkd sfx <片目录> [--list]` | 风格带录音音效清单时用：`--list` 只列来源与大小给用户确认，不带参数则下载并处理到本机缓存 |
| `wkd soundtrack <片目录>` | 合成配乐、接入用户自供录音或合成 AI 配音，写入声音同步点，输出声轨 `.cache/mix.wav` 和审听用的 `review/声轨.m4a`；不要求镜头文件已写好 |
| `wkd audition <片目录> [--voices a,b,c] [--text "…"] [--rate -20%] [--pitch -2Hz]` | 音色试听：同一句（缺省为第一条人声）用几个音色各合成一遍，输出 `review/试听-<n>-<音色>.m4a`（第 7 道） |
| `wkd still <片目录> [--frames N] [--at s02:1.5] [--aspect 9:16]` | 生成或复用图片模型分镜图 + 接触表 |
| `wkd animatic <片目录> [--proxy] [--aspect 9:16]` | 动态分镜：每镜代表帧按镜头时长停留、配上声轨，输出 `review/动态分镜.mp4` + `review/接触表.jpg` |
| `wkd preview <片目录> [--only s03] [--native] [--aspect 9:16]` | 日常局部预览，只更新受影响镜头，不拼接整片；`--native` 检查原帧率动作 |
| `wkd clean <片目录> --render-cache [--aspect 9:16]` | 清理可再生后期缓存，保留模型源素材、任务记录、声音、成片和签批快照 |
| `wkd render <片目录> [--proxy] [--only s03] [--aspect 9:16]` | 生成或复用模型视频并转码（镜头级缓存）；`--proxy` 另出带声音的小样 `review/小样.mp4` |
| `wkd qc <片目录> [--proxy] [--aspect 9:16]` | 量化技术质检（QC） |
| `wkd subtitles <片目录> [--force] [--preview\|--preflight] [--aspect 9:16]` | 从人声生成字幕 `subtitles.srt`（已存在时只检查不覆盖，`--force` 重新生成）；`--preflight` 预检，还没有小样时只做版式预检（第 11 道）；`--preview` 烧录到小样上审阅（第 12 道） |
| `wkd final <片目录> [--proxy] [--only s03] [--formats mp4,gif] [--aspect 9:16\|all]` | 混音 + 渲染 + 按字幕方式烧录 / 外挂字幕 + 编码输出（文件名标明有没有字幕，见第 13 道）；`--formats jianying` 只导出剪映草稿（第 16 道） |

**`--aspect`**：不写就是主版（`film.json` 的 `size`）；写副版画幅（`film.json` 的 `variants` 里的键）就处理副版，缓存放 `.cache/<后缀>/`，审阅文件、成片的文件名带 `-<后缀>`（如 `review/小样-9x16.mp4`），字幕文件带 `.<后缀>`（如 `subtitles.9x16.srt`）。副版只在第 15 道「改版」用，见该道细则。

恢复与交付辅助命令：`wkd resume <片目录> [--json]` 核对阶段和已完成产物；`wkd delivery <片目录> --host codex|claude|generic [--aspect all|9:16] [--json]` 生成文件存在性、新旧状态及宿主链接清单。它们不会替用户签批。阶段日志中的画幅是实际计算的画幅；副版准备时的「主版验证」仍是在检查主版，不是副版渲染进度。

### 模型配置与素材规则

`film.json` 的 `generation` 分别声明 `image: {provider: "openai"}` 与 `video: {provider: "seedance"}`，可设置各自 `model`。环境变量为 `OPENAI_API_KEY`、`OPENAI_IMAGE_MODEL`、`ARK_API_KEY`、`SEEDANCE_MODEL`；密钥不得进入工程或日志。`wkd check` 不请求 API，也不证明权限、额度或账号可用。

**所有图片阶段每批先按 [图片来源规范](specs/IMAGES.md) 执行 image-plan，用问答窗口选择当前 Agent 生图或自定义 API。** 窗口展示任务、数量和费用，用户选择即授权本批；首次推荐可用 Agent，后续按项目记忆，不能用记忆替代确认。不同来源统一使用已确认设定和参考图。image-approve 绑定当前签名，image-dispatch 执行 API 或交接宿主，宿主实际文件通过 image-import 回收。无窗口用文字提问，无人 CLI 仍必须明确方式与授权。局部批次保持相同 only/aspect 参数，图片就绪后再 still/animatic。

视频先按 [视频批次规范](specs/VIDEO.md) 执行 `generation-plan --kind video`，核对 `videoSummary` 的成片／源片时长、模型、数量、估价和预算。每批提交前弹窗等待明确开始，再 `generation-approve --kind video --signature <本次计划签名> --source "实际开始授权原文"`；修改计划、重试、返修和副版都重新确认。API 只有可靠费用估算时才执行；宿主费用不可获取时明确由宿主管理且不可估算，不称为免费。预算和任务上限控制 API 提交，不保证外部账单硬封顶。技术 fixture 不等于真实模型服务已验证。失败不得自动切换或重试，成功源素材长期保留；更改 revision 不能绕过累计额度。

## 二、对用户说话

**全程用用户的语言说话**（用户说中文就用中文），包括工序之间的进度说明、自查说明和交付后的小结；命令、文件名、字段名保持原样。

**说大白话**：用户可能是第一次做动画。术语（剧本、分镜、声轨、动态分镜、接触表、小样等）第一次出现时用一句话解释，说法见 `references/GLOSSARY.md`。

**交付文件遵循宿主规则**：宿主支持文件链接时，每个文件一行 Markdown 链接，链接文字是完整绝对路径，链接地址遵循当前宿主规则。Codex 与 ChatGPT 桌面本地执行环境使用完整绝对路径；含空格时把链接地址放进尖括号，例如：

```markdown
- [/Users/me/动画 工程/films/春晓/review/小样.mp4](</Users/me/动画 工程/films/春晓/review/小样.mp4>)
```

- 引擎日志里打印的就是绝对路径，照抄作链接文字与地址；如果宿主明确要求相对链接（如 Claude Code），才去掉当前工作目录前缀作链接地址。
- 文件不在当前工作目录下时，链接地址也用绝对路径。
- 原生链接交付不额外添加目录或播放命令。其他宿主若没有已知文件链接、附件或预览能力，按 HOSTS.md 使用 `--host generic` 列出真实绝对路径、文件类型和未验证说明；不要虚构可点击目标。
- 交审前用 `wkd delivery` 核对清单，只把 `current` 项作为本次交付；`missing`、`stale`、历史 `unverified` 项先核实或补做。链接中的特殊字符以工具生成的安全目标为准，标签保留可读路径。存在性不等于播放成功，实际打开/播放后才能记录对应结果；其他宿主如实写未验证。图片和音视频按宿主实际能力内嵌预览。

**凡是请用户看、听文件的地方都先列路径**：签批卡片、试听选音色卡片，以及任何「你可以播放 / 打开看看」的说法，前面都必须紧跟这份路径清单。只说「已生成 3 个试听文件」「可以逐一播放对比」而不列路径，用户找不到文件，算没交付。

## 三、与用户交互：选择卡片

包括第 2 道制作简报在内，要用户做选择的地方，**使用当前宿主实际可用的提问工具弹出选择卡片**，文字只做补充说明（为什么这样推荐、交付物在哪）。Claude Code 使用 `AskUserQuestion`；Codex / ChatGPT 使用当前会话提供的 `request_user_input_async` 或其他可用提问工具，并遵守工具本身的模式和用途限制。没有可用工具时使用下述文字后备，不调用不存在的工具。

**卡片规则**：

- **简报先给整套建议，只追问关键缺项**。每轮最多3个不互相依赖的问题，每题一个决定；用户明确要求逐题时一次一问，始终遵守宿主实际限制。只有工具明确自动提供「其他」时才省略该选项；始终允许用户自由补充。
- 选项标签简短（10 个字以内），选项说明用一句大白话讲清楚选了会怎样，不用术语。
- 有推荐项就放第一个，标签末尾加「（推荐）」；签批类问题不标推荐，由用户决定。
- 用户在话里已经说清的项（比如"竖屏""不要配乐"）不再出卡片，直接采用。
- 选完后用一两句文字回显结果（例如整理好的制作规格），再往下做。
- 用户选「其他」并手填的内容，按原话理解；看不懂时只澄清有歧义的项，不重新启动整套问卷。
- 没有可用提问工具的环境（含工具模式不允许、非交互运行等）退回文字：把同样的选项编号列出，请用户回复编号。异步提问发出后也必须等待用户真正回复；默认选中、工具返回、超时或无回复都不算签批。新审片材料（含 ① 制作简报、② 美术定调、⑥ 人声素材来源）必须等用户明确回复；第 5 道未变对象只继承已存在的明确批准。

**审片节点的签批卡片**：每个审片节点按固定三步提交，顺序不能乱：

1. **交付物**：签批卡片之前，先把要签批的文件逐个列出，每个文件一行路径，按宿主能力提供链接、附件或未验证的真实路径（格式见上）；文本类（剧本、分镜、字幕）另贴原文。
2. **审什么**：一两句大白话说这是什么、请用户看哪几点。
3. **签批卡片**：弹一张卡片问「《片名》的<节点名>可以签批吗？」，选项为「签批」和「要返修」。

没交付物就不弹卡片。有可用提问工具时签批只用卡片：文字里不写「在下方 / 框里选签批」这类指向界面的话，也不让用户打字回复「签批」。没有可用提问工具时按文字后备等待明确回复。

| 用户的回应 | 怎么做 |
|---|---|
| 选「签批」 | 执行 `wkd signoff`，审片结论写用户的原话或卡片结果 |
| 选「要返修」 | 再问「要改哪些方面？」，选项按下面总表的最后一列；工具支持多选时用多选卡片，否则用多轮单选或编号文字收集多项意见。用户可以自由补充；收齐意见后按返修流程修改，改完重新提交同一节点 |
| 在「其他」里直接写了意见 | 当作「要返修」处理 |

**审片节点总表**：每个节点交什么、请用户审什么、怎么问。音视频和图片类交付物都在片目录的 `review/` 里，按「交付文件写成可点击的路径」列出。

| 节点 | 工序 · `--step` | 交付物 | 审什么 | 怎么问 | 「要改哪些方面」的选项 |
|---|---|---|---|---|---|
| ① 制作简报 | 第 2 道 · `2` | `brief.md`（贴原文） | 目的、内容、规格、交付四块写得对不对 | 签批卡片 | 目的与受众 / 内容与基调 / 制作规格 / 交付 |
| ② 美术定调 | 第 3 道 · `3` | 3 套视觉方案（有参考样图就附上） | 选哪一套 | 方案卡片，选定即签批 | —（选「换一批」就重新提报） |
| ③ 剧本 | 第 4 道 · `4` | `story.md`（贴完整原文，附每段字数与估算时长） | 基调、段落节奏、文案、人声时长 | 签批卡片 | 基调 / 段落节奏 / 文案 / 人声时长 |
| ④ 设定审查 | 第 5 道 · `5` | `review/设定审查.md`、重点对象参考图 | 角色造型、道具状态、场景空间与一致性 | 集中签批卡片；未变对象沿用批准 | 角色 / 道具 / 场景 / 状态与连续性 |
| ⑤ 分镜 | 第 6 道 · `6` | `storyboard.md`（贴原文，附景别序列） | 镜头拆分、时长节奏、景别运镜、声音与文字 | 签批卡片 | 镜头拆分 / 时长节奏 / 景别运镜 / 声音与文字 |
| ⑥ 人声素材来源 | 第 7 道 · `7` | 人声方向；选独立 AI 配音时：`review/试听-<n>-<音色>.m4a` | 人声从哪来；选哪个音色 | 来源卡片；AI 配音再弹选音色卡片，选定即签批 | — |
| ⑦ 声轨审听 | 第 8 道 · `8` | `review/声轨.m4a` | 人声效果、配乐、音效、整体节奏 | 签批卡片 | 人声效果 / 配乐 / 音效 / 整体节奏 |
| ⑧ 风格帧与动态分镜 | 第 9 道 · `9` | `review/接触表.jpg`、`review/动态分镜.mp4` | 接触表看构图与视觉效果，动态分镜看节奏与声画同步 | 签批卡片 | 构图 / 视觉效果 / 节奏 / 声画同步 |
| ⑨ 字幕 | 第 11 道 · `11` | `subtitles.srt`（贴原文）、`review/字幕预检-版式.md` 和接触表；双语另交英文稿 | 错字、断句、出入时间、字幕版式；英文是否通顺 | 签批卡片 | 错字 / 断句 / 出入时间 / 位置 |
| ⑩ 小样 | 第 12 道 · `12` | `review/小样.mp4`、`review/字幕预览.mp4`（有字幕时）、QC 报告 | 画面、动作节奏、声音、字幕在画面上的位置、QC 问题 | 签批卡片 | 画面与 QC 问题 / 动作节奏 / 声音 / 字幕位置 |
| ⑪ 终审 | 第 14 道 · `14` | 成片：`wkd final` 日志列出的每个文件 | 画面、声音、字幕、节奏 | 签批卡片 | 画面 / 声音 / 字幕 / 节奏 |
| ⑫ 改版审片 | 第 15 道 · `15` | `review/接触表-<后缀>.jpg`、`review/字幕预览-<后缀>.mp4`（带字幕的副版小样）、`review/主版不变报告-<后缀>.md`（贴原文） | 副版版式排得好不好（出没出安全区、压没压字幕、有没有空）；主版有没有被改动 | 签批卡片 | 版式 / 文字与字幕 / 主版有变化 |
| ⑬ 剪映草稿 | 第 16 道 · `16` | 剪映草稿名（导出时） | 能不能打开、轨道、字幕 | 按简报交付选择执行；导出后弹签批卡片 | 打不开或缺内容 / 轨道分法 / 字幕 / 成片要改 |

② 美术定调和 ⑥ 人声素材来源本身就是选择题，选定即签批，不再另弹签批卡片（⑥ 选 AI 配音的，以试听后选定的音色为准）。

## 四、制作流程：16 道工序、13 个审片节点

设定节点全部对象均已批准且未变时，可按第 5 道继承规则继续；新增或变化仍集中等待用户确认。默认原生声音时，⑦ 在第 8 道先确认方向并暂挂，第 10 道实际视频产出后再审听签批；第 9 道可先审画面与节奏，进入第 12 道小样前必须完成实际声轨审听。每到其他 ✅ 审片节点：**停下来把交付物提交给用户审阅，等用户明确签批（sign-off）**，再执行 `wkd signoff <片目录> "<用户的审片结论 / 返修意见摘要>" --step N`，然后继续。问签批用选择卡片（见上一节）。

**工序总表**（每个节点交什么、审什么，见上一节「审片节点总表」；每道怎么做，见下面各道细则）：

| # | 工序 | 做什么 | 主要命令 | 产出 | 审片节点 · `--step` |
|---|---|---|---|---|---|
| 1 | 制作环境、工程初始化、恢复在制项目 | 检查环境，工程纳入 git，恢复在制的片子或新建 | `wkd check`、`wkd init-project`、`wkd status` | 可用的制作环境、纳入 git 的工程目录 | — |
| 2 | 制作简报（Brief）确认 | 先给简报草案，按依赖分组补问关键缺项，定下片名和制作规格 | `wkd brief` | 占位片目录 `films/<片名>/`、`brief.md` | ① 制作简报 · `2` |
| 3 | 美术定调（Visual Development） | 提报 3 套视觉方案，用户选定风格后补齐工程 | `wkd list styles`、`wkd init` | 片目录里 `film.json`、`story.md`、`storyboard.md`、`audio/build.mjs`、`shots/` 的空白模板 | ② 美术定调 · `3` |
| 4 | 剧本撰写 | 按段落写出全片的文字底稿 | — | `story.md`（v1、v2……） | ③ 剧本 · `4` |
| 5 | 角色／道具／场景设定 | 从剧本提取三类对象，设计文字与参考图并集中确认 | `wkd settings-save`、`wkd settings-review` | 项目设定库、`settings.json`、`review/设定审查.md` | ④ 设定审查 · `5` |
| 6 | 分镜脚本（Storyboard） | 按段落拆镜头，写分镜表和工程文件，两者逐镜对应 | — | `storyboard.md`、`film.json` | ⑤ 分镜 · `6` |
| 7 | 人声素材来源 | 默认确认模型人声方向；选独立 AI 配音的先试听 | `wkd audition` | `film.json` 的 `audio.voice_source`、用户自供的录音 | ⑥ 人声素材来源 · `7` |
| 8 | 声轨制作 | 默认先定原生声音方向，视频产出后审听；选独立后期时提前制作声轨 | `wkd sfx`、`wkd soundtrack` | 声音方案、原生音轨或独立分轨、`review/声轨.m4a`、实际声音同步点 | ⑦ 声轨审听 · `8` |
| 9 | 风格帧与动态分镜（Style Frames & Animatic） | 写 JSON 镜头提示词与参考图，生成代表帧排成动态分镜 | `wkd animatic` | `review/接触表.jpg`、`review/动态分镜.mp4`、每镜初版 `shots/sNN.json` | ⑧ 风格帧与动态分镜 · `9` |
| 10 | 镜头制作 | 从已批准分镜图生成镜头视频，核对一致性与动作 | — | `shots/sNN.json`、`assets/generated/` 中源视频与任务记录 | — |
| 11 | 字幕制作 | 从人声生成字幕，做版式预检 | `wkd subtitles`、`wkd subtitles --preflight` | `subtitles.srt`、`review/字幕预检-版式.md` | ⑨ 字幕 · `11` |
| 12 | 小样渲染与技术质检（Proxy & QC） | 渲染低清小样，量化检测加目视核对，字幕烧到小样上复查 | `wkd render --proxy`、`wkd qc --proxy`、`wkd still`、`wkd subtitles --preview` | `review/小样.mp4`、`review/字幕预览.mp4`、QC 报告 | ⑩ 小样 · `12` |
| 13 | 终版渲染与终混（Final Render & Mix） | 终混、全分辨率渲染、按字幕方式烧录、编码输出 | `wkd final` | 成片（文件名标明有没有字幕）、外挂字幕 `<name>_字幕.srt` | — |
| 14 | 终检与交付（Final QC & Delivery） | QC 终检后把成片交用户终审 | `wkd qc` | 成片 vN 定版 | ⑪ 终审 · `14` |
| 15 | 改版 | 有副版时，用同一套镜头和声轨排出副版画幅并交审；没有副版直接跳过 | `wkd still`、`wkd render --proxy`、`wkd qc`、`wkd subtitles`、`wkd final`（都带 `--aspect`） | 副版成片、`review/主版不变报告-<后缀>.md` | ⑫ 改版审片 · `15` |
| 16 | 剪映草稿交付 | 按简报已确认的交付选择导出或结束，未明确才问 | `wkd final --formats jianying` | 剪映草稿（写在剪映草稿目录，不进 git） | ⑬ 剪映草稿 · `16` |

**流程图**

```
            [ 1  制作环境、工程初始化、恢复在制项目 ]
                ▼
            [ 2  制作简报确认 ] ── ✅ ① 制作简报 ↺
                ▼
            [ 3  美术定调 ] ── ✅ ② 美术定调 ↺
                ▼
            [ 4  剧本撰写 ] ── ✅ ③ 剧本 ↺
                ▼
            [ 5  角色／道具／场景设定 ] ── ✅ ④ 设定审查 ↺
                ▼
            [ 6  分镜脚本 ] ── ✅ ⑤ 分镜 ↺
                ▼
            [ 7  人声素材来源 ] ── ✅ ⑥ 人声素材来源 ↺
                ▼
   ┌──────► [ 8  声轨制作 ] ── ✅ ⑦ 声轨审听 ↺
   │            ▼
   │        [ 9  风格帧与动态分镜 ] ── ✅ ⑧ 风格帧与动态分镜 ↺
   │            ▼
   │  ┌───► [ 10  镜头制作 ]
   │  │         ▼
   │  │     [ 11 字幕制作 ] ── ✅ ⑨ 字幕 ↺ ◄─┐
   │  │         ▼                            │ 字幕返修
   │  ├──── [ 12 小样渲染与技术质检 ] ── ✅ ⑩ 小样 ↺
   │  │         ▼                            │
   │  │     [ 13 终版渲染与终混 ]             │
   │  │         ▼                            │
   └──┴──── [ 14 终检与交付 ] ── ✅ ⑪ 终审 ↺ ─┘
                ▼                     ▲
            ( 成片 vN 定版 )          │ 成片要改：改版 / 草稿返修
                ▼                     │
            [ 15 改版 ] ── ✅ ⑫ 改版审片 ↺（没有副版就跳过）
                ▼                     │
            [ 16 剪映草稿交付 ] ── ✅ ⑬ 剪映草稿 ↺
                ▼
            ( 交付完成 )
```

| 图例 | 含义 |
|---|---|
| `▼` | 主流程，审片节点签批后进入下一道工序 |
| `✅ ①`–`⑬` | 该工序的审片节点 |
| `↺` | 节点内返修 |
| 内侧回路 | 画面返修 |
| 外侧回路 | 声音返修 |
| 14 → 11 回路 | 字幕返修（⑩ 小样提出的字幕问题同样回到第 11 道） |
| 15、16 → 14 回路 | 改版或草稿返修中需要改主版成片的情况 |

### 系列与创作入口

支持一句话创意、已有剧本、已有分镜/素材；已提供内容直接转入对应工序审阅，不要求用户重写。默认剧集 9:16、每集 30–90 秒，具体项目的画幅与时长优先。

项目根 `series.json` 保存系列信息与确认版连续性，`characters.json` 保存角色的定妆、声线、参考图和版本。`props.json`、`scenes.json` 以相同方式保存道具与场景版本；每集 `settings.json` 选择版本，镜头 `settings` 自动引用已确认的文字和参考快照，手写 references 仍只接受片内路径。单集位于 `films/<集名>/`，可通过 `film.json.series` 引用项目、单集编号与角色。角色换装、年龄或声线变化建立新版本，不覆盖旧档案。每集草稿在 `.wkd-series/drafts/`，人物关系、事件、道具、悬念与结束状态经当前稿明确确认后才进入 `series.json` 的 canon；废稿不能进入正式记录。

继续下一集前读取已确认版本，核对上一集结束状态、角色版本和未解决悬念。记录剧情确认不代表画面或最终交付自动通过，也不承诺参考图能完全保证一致性。

### 第 1 道 · 制作环境、工程初始化、恢复在制项目

- `wkd check`，按缺的项处理：

  | 缺什么 | 级别 | 影响 | 怎么办 |
  |---|---|---|---|
  | ffmpeg | 必需 | 结论不是「一切就绪」，不能渲染 | 停下，引导用户运行本插件 setup skill（Claude Code 命令为 `/wukong-drama:setup`），不要带病渲染 |
  | 渲染管线 | 必需 | 同上 | 同上 |
  | git | 推荐 | 没有定版快照 | 不拦着往下做，用一句话告诉用户影响 |
  | python3 + fonttools | 推荐 | 字体不子集化，渲染变慢 | 同上 |
  | pyJianYingDraft | 可选 | 第 16 道导不了剪映草稿 | 同上 |
  | TTS | 可选 | 不能 AI 配音 | 同上 |

- `wkd init-project`（当前工程目录）。
- `wkd status`。如有在制项目，告诉用户"《X》已推进到第 N 道工序，下一步是……"，用选择卡片问要恢复哪支片还是新建项目（每支在制的片子一个选项，加一个「新建一支片」；超过 3 支就只列最近的 3 支）。
  - 恢复时先读 `films/<片>/.wkd/state.json` 的 history，了解此前每个审片节点的结论。
  - 再运行 `wkd resume <片目录> --json`，核对失败/中断阶段、当前输出和待存档签批；已经授权的计算用原命令继续，完整产物会复用，缺失阶段补做。`user-modified` 草稿保留并核实，不能自行覆盖或不断重导。
  - `pendingApproval` 只有已明确用户批准的存档任务。核对原结论及当前输入未变化后重试 `wkd signoff ... --approval-id <原id>`；输入变化先重新审阅。没有本地记录但当前会话能核实用户明确批准时，可按原结论重新存档；不能从“已生成”、旧工序号或代理自述推断用户同意。
  - 风格显示「未定」的是第 2 道建的占位片：读它的 `brief.md`，简报没签批就接着追问或重新提交 ①。

### 第 2 道 · 制作简报（Brief）确认

先用已有故事和要求拟一份**待确认简报草案**，把片名、基调、受众、声音等建议集中说明，让用户可以一次确认或修改；只对无法合理建议的关键缺项提问。已明确的决定直接采用，推荐项须经明确确认才生效，最后将完整 `brief.md` 集中交用户签批。

**追问规则**：

- 把简报各项看成一棵**决策树**：每个决定会引出依赖它的决定（比如定了有人声，才问字幕方式；选了投放抖音，画幅推荐就变成 9:16）。
- **按依赖分组**。同轮最多3个前置已知、互不依赖的问题；每题一个决定。平台未定时先问平台，明确后再确认画幅；有人声后才问字幕。片名、基调等有合理建议时放入草案一次确认，不单独弹窗。用户要求逐题或宿主只支持单题时一次一问。
- **等待真实回答**。本轮未回答时不叠加新窗口，继续处理不依赖答案的准备；收到明确答复后自行登记并推进，不等用户再说“继续”。预选项、异步工具返回、超时或无回复都不能当成回答。
- 卡片用一句清楚的问题和简短选项；有推荐项时放第一项并标「（推荐）」，始终允许自由补充。开放问题在宿主支持时用单题自由输入卡片，不编造选项凑数。未知信息不能替用户决定。
- 没有可用提问工具时，才退回文字提问；文字后备同样每轮最多3题，等待真实回答后再继续。
- 每次回答后重新判断哪些事项已明确：用户主动补充的多项信息一起登记，已回答的项不再问；仍依赖未定事项的问题留到后面。
- **事实自己查，决定交给用户**。可用风格（`wkd list styles`）、TTS 装没装（`wkd check`）这类事实自己查，不问用户。
- 草案中尚未确认的推断标注“建议／待确认”，不写成已决定；用户签批整份草案即确认其中明确列出的建议。关键规格有矛盾或缺失时先解决，不拿沉默补全。
- 用户在话里已经说清的项不再问，直接采用。故事 / 主题取自用户的话（`/wukong-drama:film` 后面的内容）。
- 用户带来了现成的口播稿：片名定下、`wkd brief` 建好目录后，原文存为 `films/<片名>/口播稿.md`；故事 / 主题、片长、人声从稿子推出，不再问（写法见 `specs/BRIEF.md`）。
- 现成图片、视频、录音、参考文件/链接与口播稿分开核对一次。已经提供的先登记并使用；用户已说没有就记「无」，不重复问。可将明确决定及其来源记入 `.wkd/decisions.json`（schema 见插件 engine/schemas），未知项保留 unknown，缺省推荐不当成用户已确认；与简报/film 配置冲突时只核实冲突项。

**故事缺失时先问故事**；有故事但无片名时先拟工作片名纳入简报草案，收到明确认可后 `wkd brief <片名>` 建目录。已给片名直接采用；不为可随草案确认的标题、目标受众、无额外元素逐项开窗口。

**简报各项怎么填、推荐答案是什么见 `specs/BRIEF.md`**，追问时按它给推荐答案。达成共识后，按追问结果填 `films/<片名>/brief.md`。

**提交**：按「审片节点的签批卡片」三步提交：`brief.md` 可点击路径并贴原文 → 请用户看目的、内容、规格、交付四块写得对不对 → 签批卡片。第 3 道起各工序以签批过的 `brief.md` 为制作规格的依据。

✅ **审片节点① 制作简报** → `--step 2`

### 第 3 道 · 美术定调（Visual Development）

读插件根目录的风格库 `catalog.json`，按故事提报 3 套视觉方案。

- **只用能直接开拍的风格**：`catalog.json` 里 `status` 为 `available` 的风格才能出方案；目录只收录实际提供的风格。可用风格不足 3 种时，用同一风格的不同处理方式凑足 3 套（例如"水墨 · 远景留白""水墨 · 近景特写"），标签写「风格名 · 处理方式」。
- **提报前先读规格书**：每个候选风格都先读它的 `STYLE.md`（适合 / 不适合、禁忌清单），方案描述不得违反禁忌（例如水墨朱砂以外不用颜色，就不能写"一点暖黄"）。
- **用一张选择卡片展示**：每套一个选项（标签是风格名，或「风格名 · 处理方式」，说明是一句提案理由；`preview` 写这套方案的画面描述：色调、笔触、运动方式），最合适的一套放第一个并标推荐，第 4 个选项是「换一批」。有参考样图就在卡片前用文字附上路径或发送文件。
- 用户选「换一批」或在「其他」里描述想要的感觉，就重新提报 3 套。

需要生成候选样图时，先按 [图片来源规范](specs/IMAGES.md) 创建 art 批次，每批选择来源并回收后再展示；尚无 film.json 时使用已建 brief 目录和简报画幅，不为生图提前选定风格。

**用户选定后**：

1. `wkd init <片名> --style <id> --aspect <brief.md 里的主画幅>`（在第 2 道建的占位片目录上补齐工程，不会覆盖 `brief.md`）。
2. 按 `brief.md` 把字幕方式写进 `film.json` 的 `subtitles.mode`；简报定了副版的，把副版画幅写进 `film.json` 的 `variants`（如 `"variants": { "9:16": {} }`，字段见 `specs/FILM.md`）。副版要在选定风格的 `style.json` 的 `aspects` 里，不在就回到第 2 道改简报。
3. 通读该风格 skill 目录下的技术规格书 `TECH.md`（美术规格书 `STYLE.md` 提报前已读过，选定后再完整读一遍）。

✅ **审片节点② 美术定调** → `--step 3`

### 第 4 道 · 剧本撰写

产出 `story.md`：全片的文字底稿，写给人看、不含代码。**按 `specs/STORY.md` 填写**（各部分写什么、写到什么程度、示例），提交前按其中的自查清单过一遍。

片目录里有 `口播稿.md`（用户带来的口播稿）时，它是写剧本的素材：人声文案用原句，其余各部分围绕它写；画不出来的句子写成改稿建议 `review/改稿建议.md`，只提建议、不替用户改。做法见 `specs/STORY.md`「三、有口播稿时」。

**提交**：把 `story.md` **完整原文**提交给用户（有口播稿时连同 `review/改稿建议.md` 原文，请用户逐条定改不改，同意的改进剧本再签批），并主动就四点征询意见：

- 影片基调是否准确？
- 段落节奏是否合适？
- 哪些文案（人声和屏幕文字）需要修改？
- 人声时长（字数）是否合适？（中文语速约每秒 3.6 字；提交时附上每段字数与估算时长）

剧本返修后，版本号加 1（v1、v2……）。

✅ **审片节点③ 剧本** → `--step 4`

### 第 5 道 · 角色／道具／场景设定

按 [设定规范](specs/SETTINGS.md) 从已确认剧本提取三类清单。主角、关键道具、复用或空间关系重要的场景为重点对象，交文字和实际参考图；其余对象简化，无此类对象明确“不适用”及原因。换装、受伤、破损、昼夜等按本片剧情需要设计独立状态版本。

先读取同系列已有版本，沿用仍适用且未变化的批准。按 [图片来源规范](specs/IMAGES.md) 准备 settings 批次，在一个窗口选择生图方式并确认本批；结果回收后用 `settings-save` 登记，随后集中审图。不得拿文件路径、计划或占位图当作实际图片已审。

运行 `wkd settings-review <片>`，打开报告与所有重点参考图，先核对造型、尺度、空间和状态；将 `review/设定审查.md` 内容及参考图集中呈现给用户，一次审查新增／变化部分。用户明确确认后执行：

```bash
wkd signoff <片> "用户实际确认结论" --step 5 --settings-signature <报告中的signature>
```

如果全是同系列同风格的未变对象，核对本集选择后可 `wkd settings-reuse <片> --signature <当前signature>`，该命令只继承已有批准，不制造新的人审。无对象的项目仍须明确确认三类不适用。

后续发现缺项或修改时新建版本，更新本片清单和相关镜头引用，重新生成审查材料；保留旧版和素材。按报告仅复核受影响镜头，再判断是否重拍，无关镜头沿用。更换美术风格重新确认适用性。分镜前必须已完成设定确认，`--force` 不能绕过。

✅ **审片节点④ 设定审查** → `--step 5`

### 第 6 道 · 分镜脚本（Storyboard）

产出两份，逐镜对应：

- `storyboard.md`：给人审阅，**按 `specs/STORYBOARD.md` 写**：表头、逐镜各栏、声音铺底，以及取决于风格的栏到 STYLE.md 哪一节查。
- 工程文件 `film.json`：给引擎，字段见 `specs/FILM.md`。

依据已确认设定拆镜头，在分镜画面描述中写清角色、关键道具和场景所处的剧情状态，并在各镜 JSON 的 settings 中关联对应版本；发现缺项先回第 5 道补设定。按剧本的段落结构拆镜头；用到的技法不进分镜表，写在镜头 JSON 的图片/视频提示词里（见 `specs/SHOT.md`）。

**景别**（引擎会查）：每镜的景别同时写进 `film.json` 的 `shots[].size`，规则见 `specs/STORYBOARD.md`「三、景别规则」。

- 提交分镜时附一行景别序列，如「特写 → 近景 → 远景 → 中景 → 特写 → 全景」。
- `wkd signoff --step 6` 不合规会拒绝并列出问题：改分镜，不要直接 `--force`；只有用户明确要这样拍时才加 `--force`，问题会附在签批记录里。

✅ **审片节点⑤ 分镜** → `--step 6`

### 第 7 道 · 人声素材来源

默认原生声音时，先确认是否有对白、旁白及其风格，将台词与声音要求写入剧本和 video_prompt，再签批⑥；audio.voice_source 设 none、voices 留空，仅表示不额外合成独立人声。全片无人声时在视频提示词明确禁止对白和旁白。用户选择独立人声后，再用下表三种来源，并避免与模型人声重复：

- 剧本写"无人声"时，「本片不用人声」放第一个并标推荐；
- 否则 `wkd check` 显示装了 TTS 时，「AI 配音」放第一个并标推荐。

| 情况 | 执行方式 |
|---|---|
| 用户自供录音 | 请用户把录制好的人声（wav / mp3 / m4a，可按条分轨，也可整段单轨）放入素材目录 `films/<片>/audio/voice/`；在 `audio.voices[].file` 里逐条挂接，`"voice_source": "user"` |
| AI 配音 | 调用已安装的 TTS 引擎（edge-tts / kokoro）合成；`wkd check` 显示没有 TTS 时先告诉用户，可安装后再合成，或暂按字数预估时长、继续推进画面；`"voice_source": "ai"`。选定前先试听音色，见下文。同期声（`kind: live`）是现场原声，AI 配不出来，这类条目仍要请用户提供录音并挂接 `file`，其余条目才由 AI 合成 |
| 剧本写"无人声" | 请用户确认"本片不用人声"，确认后记 `"voice_source": "none"`；用户改主意要加人声时，退回第 4 道补写人声文案 |

**AI 配音先试听再签批**：用户选「AI 配音」后，先 `wkd audition <片>`，用 2–3 个候选音色合成文案第一句，然后按顺序提交：

1. **试听文件**：把 `wkd audition` 日志里的每个试听文件写成一行可点击路径（格式见「交付文件写成可点击的路径」），一个音色一行；链接使用本次实际试听文件的绝对路径。
2. **听什么**：一两句说推荐哪个音色、为什么。
3. **选音色卡片**：选项就是这几个音色，各附一句特点，可多给一个「都不合适」。

用户要慢读、低沉等效果时，加 `--rate` / `--pitch` 再试听一轮。选定后才把音色写进 `voices[].voice`（调过的语速、音高写进 `voices[].rate` / `pitch`），然后签批 ⑥。

edge-tts 的中文普通话音色：

| 音色 | 特点 |
|---|---|
| `zh-CN-YunyangNeural` 云扬 | 男声，新闻播音，沉稳 |
| `zh-CN-YunjianNeural` 云健 | 男声，饱满有激情 |
| `zh-CN-YunxiNeural` 云希 | 男声，年轻阳光 |
| `zh-CN-YunxiaNeural` 云夏 | 男童 |
| `zh-CN-XiaoxiaoNeural` 晓晓 | 女声，温暖 |
| `zh-CN-XiaoyiNeural` 晓伊 | 女声，活泼 |

- edge-tts 没有老年音色。硬压音高（`pitch` 降很多，或用 ffmpeg 变调）听起来发怪，不要这样做出「老者」。
- 用户要的音色内置没有时，告诉用户可以从外部拿音频，统一按「用户自供录音」接入：剪映的文本朗读、国内云配音平台（账号由用户自己注册）、本机开源配音模型（用前核对许可）、真人录音。模仿某人的声音时，参考录音必须是用户有权使用的。
- 句中要停顿时拆成多条 `voices`，用 `at` 控制间隔。

✅ **审片节点⑥ 人声素材来源** → `--step 7`

### 第 8 道 · 声轨制作

默认使用模型原生声音，generation.video.generate_audio 为 true（省略同样开启）。先确认对白、配乐、环境声与动作音效方向，记录“待实际视频审听”；第 10 道产出并保留原生音轨后运行 wkd soundtrack，实际审听并完成本节点，再进入小样终审。模型音轨是混合声音，不承诺自动拆成人声、配乐、音效。无对白不等于无声，也不承诺精准口型。

用户选择独立后期或无声画面时，显式将 generate_audio 设为 false。以下是可选的独立声轨流程；按需制作，避免与模型声音重复叠加。


**四类声音写在哪**：

| 类别 | 写在哪 | 输出文件 | 剪映草稿 |
|---|---|---|---|
| 人声 | `film.json` 的 `audio.voices`（各字段见 `specs/FILM.md`） | 由 `wkd soundtrack` 接入或合成，混进声轨 | 「人声」轨 |
| 配乐（Score） | `audio/build.mjs`：用 `synth`（qin 拨弦 / water 流水 / knock 打击 / reverb 混响）程序化合成原创音乐 | `bgm.wav` | 单独一条轨 |
| 环境声 | `audio/build.mjs` | `ambience.wav` | 单独一条轨 |
| 音效 | 关键音效的时间点放进 `film.json` 的 `cues`，在 `audio/build.mjs` 里放到这些时间点 | `sfx.wav` | 单独一条轨 |

配乐、环境声、音效各建一个 buffer、各写一个文件，某类没有就不写；分开写是为了导出剪映草稿时各占一条轨，后期能分开调。

**人声**：

- 每条给一个同步点名（如 `"cue": "第二句"`），**各条不能重名**（重名时 `wkd soundtrack` 报错）。
- 不是画外音的条目按分镜标记写 `kind`（`dialogue` / `os` / `live`）和 `speaker`；同期声（`live`）必须挂接录音 `file`，即使 `voice_source` 是 `ai`。

**配乐、环境声、音效**：

- 风格带录音音效清单（`style.json` 的 `sfx`）的，音效用 `sfx.place(buf, 名字, { at })` 放录音，按该风格的 `SFX.md` 选；下载前先 `wkd sfx <片> --list` 请用户确认。
- 有人声的片子，背景音乐的返回音轨标 `duck: true` 就随人声闪避（说话时压到 0.48 倍）。

**`wkd soundtrack`**：

- 接入用户录音或合成 AI 配音，把每条人声的**实测**入出点写回 `cues`，并标出超出镜头时长或互相重叠的条目 → 据此回调 `film.json` 的镜头时长。
- 用户自供录音与剧本篇幅出入较大时，告诉用户并以实际录音为准。
- 声轨按风格 `style.json` 的 `loudness`（缺省 -18 LUFS）两遍标准化，日志打出复测响度。
- 用了录音音效的片子还会打出「音效听感审计」，有被盖住的音效时把这几行转给用户，由用户定调高、挪位还是换音效。

**提交**：把审听用的声轨 `films/<片>/review/声轨.m4a`（按 `wkd soundtrack` 日志里的绝对路径写成可点击路径）交给用户审听，请用户确认人声效果、配乐、音效和整体节奏。

提交前先读 `review/声轨审听.md/.json`：实际审听开场及每段音乐、转折，核对鼓点/编曲变化、衔接和人声可懂度。按 [审阅证据规范](specs/REVIEW.md) 写 `review-notes.json`，重新运行 soundtrack 更新报告。不能播放时保留 not-listened 并交用户听；音效相对电平和 LUFS 只是测量，不代表已听过。源混音改变后旧结论过期。

- 不要交 `.cache/mix.wav`：它在隐藏目录里，WAV 体积大，在聊天里播放会卡。
- 有意见就改 `audio/build.mjs` 或人声后重新 `wkd soundtrack`，再提交审听。
- **没有任何声轨**（无人声、无配乐、无音效）时，`wkd soundtrack` 不生成 `mix.wav`。也要停下请用户确认"本片无声"，签批后继续；第 9 道的动态分镜随之无声，只审画面节奏。

此后按已确认的声音同步点安排动作与剪辑；把动作要求写进视频提示词，并在实际视频里核对。模型提示词中的秒点不代表精确对位，口型和词级动作必须实看实听。

✅ **审片节点⑦ 声轨审听** → `--step 8`

### 第 9 道 · 风格帧与动态分镜（Style Frames & Animatic）

每镜写 `shots/sNN.json` 的 `image_prompt`、`video_prompt` 和 `references`（见 `specs/SHOT.md`）。镜头 `settings` 引用第 5 道已确认的角色、道具、场景及剧情状态版本，自动带入文字和图像快照；额外构图参考可放在影片 `assets/references/`。模型和密钥配置见 setup；也可用 `image` 导入宿主或用户已生成的本地图像。

先为图片批次生成计划并绑定当前授权，再 `wkd still <片>` 生成或复用分镜图，再 `wkd animatic <片>`：每镜代表帧拼成接触表，并按镜头时长配上已就绪的独立声轨，输出 `review/动态分镜.mp4` 与 `review/接触表.jpg`。此时只需图片；默认原生声音尚未生成时，预览明确标为声音待生成，只审画面和节奏，不为这一预览提前生成全部视频。

**自己先审一遍**：打开接触表，明显问题先返修：

- 每镜至少有主体和环境两个层次；留白不能让画面发空。
- 景别和分镜一致，人物脸、服装、关键道具跨镜一致。
- 色彩符合 STYLE，标题、题字或界面文字逐字核对，留出字幕安全区。
- 模型结果不保证由相同 seed 复现；保留当前原图，不通过删素材重试。

**提交**：把接触表和动态分镜一起交用户审阅，分别看构图与节奏。只有用户批准后才把这些分镜图用作第 10 道视频的视觉依据。

✅ **审片节点⑧ 风格帧与动态分镜** → `--step 9`

### 第 10 道 · 镜头制作

完善每镜 `video_prompt`，明确主要动作、运镜、结束状态和稳定约束。先核对参考图已经实际审阅通过，再按 [视频批次规范](specs/VIDEO.md) 解释时长与生成安排、弹窗确认开始并绑定当前签名。`wkd render` / `preview` 从第 9 道分镜图生成或复用视频，再用 ffmpeg 统一画幅、帧率、时长；若已持有可用视频，填写本地 `video` 路径导入。默认保留模型原生音轨；视频产出后检查对白、配乐、环境声和动作音效，完成第 8 道实际声轨审听。显式 generate_audio: false 时才改用已确认的独立后期声轨或无声方案。

- 先 `wkd preview <片> --only s03` 看受影响镜头，动作细节用 `--native`；全片小样用 `wkd render <片> --proxy`。
- 小样长边最多 960、帧率最多 15；小样和高清共用同一份生成源视频，只改变后期转码，不各自创建付费任务。
- 人工核对脸、手、服装、道具、空间连续性、文字漂移、运动、结尾停留和对白口型；技术 QC 不能替代这些检查。
- 轮询超时重跑原命令续查原任务。失败或提交结果不明确时保留记录，核对远程任务；明确需要新一轮生成才更改镜头 `revision`。不删除记录来绕过重复计费保护。
- 提示词、参考图、模型、预算或画幅变更时重新查看计划；新批次先弹窗确认开始，旧授权不能用于变化后的批次。

日常局部预览配上已有声轨对应区间，不重新生成声音，也不代替整片字幕/拼接验收。完整 QC、字幕预览与 `final` 在相应审片阶段执行。

生成源文件与任务记录位于 `assets/generated/<画幅>/<镜号>/<签名>/`，必须随工程保存。需要磁盘空间时用 `wkd clean <片> --render-cache`；不要删除源素材或整个 `.cache`，其中还有声音、恢复记录和定稿快照。

本道没有新审片节点；选择原生声音的片子先完成第 8 道实际声轨审听，再进入第 11 道。

### 第 11 道 · 字幕制作

字幕是人声逐句转成的文字，不是屏幕文字。放在镜头制作之后、小样之前：人声文字和同步点在第 8 道已经定下，字幕可以先审文字和断句；第 12 道的小样再把字幕烧到画面上一起看，一次审完画面和字幕位置。

**不出字幕**：`subtitles.mode` 为 `none`（或没有 `subtitles` 字段）时，停下请用户确认"本片不出字幕"，签批后继续。

**生成**：`wkd subtitles <片>` 从人声原文和 `cues` 里的实测入出点生成 `subtitles.srt`，断句规则：

| 规则 | 说明 |
|---|---|
| 一条人声不超过 `max_chars` 字 | 就是一条字幕，时间等于这条人声的入出点 |
| 超过 `max_chars` 字 | 先在句内标点（。！？；，、：）处切开、从左到右合并到不超过 `max_chars`；仍超长的按字数硬切；各段按字数比例分配这条人声的时长 |
| 结尾标点 | 去掉 。，、；：，保留 ？！… |
| `max_chars` 缺省 | 横屏 18、竖屏 12、方形 14（标点不计） |

- 有错误（出点早于入点、超出片长）必须改；警告（相邻重叠、单行超长、短于 0.6 秒）看情况改，直接编辑 `subtitles.srt` 即可。
- `subtitles.srt` 已存在时 `wkd subtitles` 只检查不覆盖（保护手改的断句）；声音返修后要加 `--force` 重新生成。

**版式预检与自查**：`wkd subtitles <片> --preflight` 只读已有字幕。这时还没有小样，它做的是**版式预检**：时间轴按 `film.json` 计算，检查字框、安全区和已声明的内容区，在白、黑、灰底上出样张，写成 `review/字幕预检-版式.md` 和接触表；报告会列一条「未在实际画面上核对」，到第 12 道用 `--preview` 在小样画面上复查。已有当前小样时（如返修回到本道），`--preflight` 直接在小样画面上预检。**自己先看一遍**：

| 检查项 | 标准 | 不合格怎么办 |
|---|---|---|
| 字体和风格搭不搭 | 国风、手绘这类风格不用缺省的黑体白字 | 风格 `style.json` 没给字幕样式时，先提一个开源字体方案（`engine/core/fonts.mjs` 的 `KNOWN_FONTS` 里选） |
| 在不在安全框里 | 字幕整体在画面中间 90% 的范围内，文字底边离画面底边不少于画高 5% | 调字幕样式 |
| 有没有压住屏幕文字 | 不压住题字、落款等屏幕文字（版式预检只能查 `subtitle-layout.json` 声明过的区域，实际画面第 12 道再看） | 调字幕样式 |

术语被拆开时可在 `subtitles.protected_terms` 声明固定词组，超宽术语完整保留并提示。预检的 errors 会阻断 preview/final 和字幕、小样签批；warnings 交用户判断；manual_required 必须如实列出，不能说“全部无遮挡/可读”。重要内容区域用可选 `subtitle-layout.json` 声明（格式见插件内 schema）；未声明区域只代表未覆盖，不证明没有遮挡。缺少当前预检证据的模型工程需重新输出预览。

改样式写 `film.json` 的 `subtitles.style`（字段同 `style.json` 的 `subtitles` 块，逐项覆盖），不改插件目录里的 `style.json`。

**中英双语**（`subtitles.bilingual: true`）：`wkd subtitles` 在英文稿缺失时生成 `subtitles.en.json`，已存在时保留手改，只有显式 `--force` 才重新生成/重排（每条 `{ "zh", "en" }`，与 srt 逐条对应；中文没变的条目保留已填的英文），并列出待填的条目。逐条填 `en`，规则：

- 口语意译，不逐字翻；一条一行，横屏不超过约 45 个字符（竖屏 28），超了会缩字。
- 产品名、术语原样保留：Claude Code、Codex、Diff、Token、Git。
- 和中文的节奏对应：中文是半句，英文也写半句，不要把两条合成一句。
- 结尾不加句号，问句保留问号。
- 填完再跑一次 `wkd subtitles <片>`，确认"0 条待填"、没有超长和句号的警告。改了中文字幕后先检查英文对应关系；需要重排时明确使用 `--force`（会覆盖手改 SRT/英文），或由用户逐条修正，不默认覆盖。
- `--preflight`、`--preview` 和 `wkd final` 发现英文稿和中文字幕对不上、或有空条，会直接停下。外挂方式（`srt` / `both`）另出 `<name>_英文字幕.srt`；剪映草稿多一条「英文字幕」轨。

**提交**：把 `subtitles.srt` 原文、`review/字幕预检-版式.md`（返修时已有小样则是 `review/字幕预检-proxy.md`）和接触表交给用户，问：有没有错字？断句是否自然？出入时间跟不跟得上人声（可对照第 9 道的 `review/动态分镜.mp4` 听）？字号、字体和位置是否合适？双语的片子把英文稿也交给用户，问英文是否通顺、术语对不对。字幕在实际画面上会不会压住屏幕文字，留到第 12 道小样一起看。

✅ **审片节点⑨ 字幕** → `--step 11`

### 第 12 道 · 小样渲染与技术质检（Proxy & QC）

量化检测 + 目视审片：

| 命令 | 做什么 | 有问题看哪里 / 怎么办 |
|---|---|---|
| `wkd render <片> --proxy` | 按明确需求渲染完整小样（长边最多 960、最多 15fps），同时合成带声音的 `review/小样.mp4` | — |
| `wkd qc <片> --proxy` | 检测留白比例、点缀色占比、帧间差异、黑帧 / 空帧、非预期硬切，阈值来自风格规格 `style.json → qc` | 有 ✗ 就打开 `stills/qc/qc-sheet.jpg` 查看超标帧 |
| `wkd still <片> --frames 4 --proxy` | 每镜抽 4 帧 | 对照 STYLE.md 的"交付前质检"清单逐项核对 |
| `wkd preview <片> --only s03` | 日常返修仅出局部小样 | 不代替整片审阅证据；要重新提交审片时再跑完整小样与 QC |
| `wkd subtitles <片> --preview` | 有字幕时：在小样画面上重新预检字幕，再把字幕烧录到小样上，输出 `review/字幕预览.mp4` | 预检有 errors 先改，回到第 11 道改 `subtitles.srt` 或字幕样式 |

画面铺满一张图（截图、照片）的镜头，在 `film.json` 里给它标 `"full_bleed": true`，`wkd qc` 就不查这一镜的留白。

有字幕的片子，签批前必须跑过 `--preview`（引擎会检查基于小样的字幕预检是不是当前的）。对照 `review/字幕预检-proxy.md` 的实际画面样张，看字幕有没有压住题字、落款等屏幕文字。

**提交**：先解释小样用于检查内容与节奏，通常降低尺寸／帧率，和终版复用同一模型源视频；小样通过后不会为“高清”再次付费生成。把 `review/小样.mp4`、`review/字幕预览.mp4`（有字幕时）的可点击路径和 QC 报告提交给用户，请用户看画面、动作节奏、声音，以及字幕放在画面上的位置。

QC 的每条原始告警都有来源绑定的 finding id。按 `review-notes.json.qc` 记录实际抽查区间、操作者、理由和证据，重跑 QC 后分开交代未处理、需修复、有依据接受和过期备注。人工接受不改原测量；时间轴、解码、字幕确定错误和主版保护失败不能用接受备注绕过。格式见 [审阅证据规范](specs/REVIEW.md)。

✅ **审片节点⑩ 小样** → `--step 12`

### 第 13 道 · 终版渲染与终混（Final Render & Mix）

`wkd final <片>`：依次执行终混、终版渲染、按 `subtitles.mode` 烧录字幕、编码输出；未改动的镜头直接读缓存，字幕不进镜头缓存。成片文件名标明有没有字幕：

| `subtitles.mode` | 成片 | 外挂字幕 |
|---|---|---|
| `none` | `<name>.mp4` | — |
| `burn` | `<name>_有字幕.mp4` | — |
| `srt` | `<name>_无字幕.mp4` | `<name>_字幕.srt` |
| `both` | `<name>_有字幕.mp4` + `<name>_无字幕.mp4` | `<name>_字幕.srt` |

`film.json` 的 `export.formats` 不放 `jianying`：剪映草稿等 ⑪ 终审定版后在第 16 道再导出。

本道没有审片节点，做完直接进第 14 道。

### 第 14 道 · 终检与交付（Final QC & Delivery）

- 交付 `review/时间轴检查*.md`（主副版、高清与小样各自独立），它验证实际帧数与切点，不代表旁白语义或词级同步通过。模型工程缺少来源记录时重新运行 `wkd render`，不要手改 film.json 镜长来掩盖漂移。
- 再跑一次 `wkd qc <片>` 做 QC 终检（它检测的是不带字幕的画面，烧录了字幕的要再抽看成片）。
- 终审前按 [审阅规范](specs/REVIEW.md) 列出小样到终版的实际变化：画面来源、切点／时长、声音、字幕、尺寸／帧率。内容完全沿用就明确说明，仅变化后期编码；升至1080p编码不能说成原生1080p或新细节。终审仍确认实际交付文件。
- 把终版成片交给用户终审：`wkd final` 日志里列出的每个文件都给可点击路径（`both` 时有字幕、无字幕两个版本都交，连同 `<name>_字幕.srt`）（在 Cowork / 桌面环境里用发送文件的方式）。
- 提交终审前运行 `wkd delivery <片> --final --host codex --json`，展示主版必需视频/字幕、版本和状态，取 `reviewSets[13].deliveryRevision`。其他宿主用 `--host claude|generic`。缺草稿时仍交可用视频，整单明确部分完成。
- 用户明确批准对应版本后 `wkd signoff <片> "成片 vN 终审通过（实际用户结论）" --step 14 --delivery-revision <完整摘要>`；版本变化被拒绝时重新提交当前文件，有返修意见走原返修流程。旧无 revision 的记录只代表流程历史，不能据此宣称当前文件已验收。
- 签批时引擎记下主版每镜的哈希（进 `.wkd/state.json`），并把全分辨率的镜头片段存成定稿快照（`.cache/approved/`），第 15 道用来证明主版没被改动。所以签批前要先跑过 `wkd final`（全分辨率）；只渲染过小样的镜头存不下快照，日志会列出来。
- **版本号**：第一次提交终审为 v1，每因返修重新提交一次加 1（v2、v3……），签批的那一版即定版。

✅ **审片节点⑪ 终审** → `--step 14`

### 第 15 道 · 改版

主版定稿后，用**同一套镜头、同一条声轨**排出副版画幅（如横屏主版的 9:16 竖版）。镜头表、时长、声音同步点、配乐和人声两版完全共用，副版只改画面排版，不增删镜头、不改时长、不另配声音。

**没有副版**（`film.json` 没有 `variants`）：直接 `wkd signoff <片> "无副版，跳过改版" --step 15`，进第 16 道，不出审片节点。

**有副版**，按顺序做：

1. **写副版重排表**：在 `storyboard.md` 末尾加「副版重排」表，每镜一行写怎么排（格式见 `specs/STORYBOARD.md`「六、副版重排」）。依据是风格 `STYLE.md`「4. 构图」里的「画幅重排规则」。这张表不单独审，随 ⑫ 一起交。
2. **改镜头**：副版写独立 JSON 覆盖文件，如 `shots/s03.9x16.json`；按副版画幅重排主体、参考图与字幕安全区。可导入已核对的裁切版图片/视频，或为副版单独生成。镜号、时长与声轨保持一致，主版提示词和已签批源素材不覆盖。
3. **出副版、自己先审**：
   - `wkd animatic <片> --aspect <副版>`：出副版接触表 `review/接触表-<后缀>.jpg`（和动态分镜），用 Read 打开，对照 STYLE.md 的「交付前质检」查有没有出安全区、压字幕、画面发空。只想看某几帧用 `wkd still <片> --aspect <副版> --at s03:1.5`（静帧在 `stills/<后缀>/`）。
   - `wkd render <片> --proxy --aspect <副版>`、`wkd qc <片> --proxy --aspect <副版>`：副版小样和质检。
   - 有字幕的：`wkd subtitles <片> --aspect <副版> --preview`。副版字幕按副版画幅重新拆条（竖屏每条最多 12 字），写在 `subtitles.<后缀>.srt`；双语的英文沿用主版译文，按副版的拆条重新切开，写在 `subtitles.en.<后缀>.json`，不重新翻译。主版英文改过之后，已有副版英文默认保留；只有明确使用 `--force` 才重新切分，会覆盖手改。
   - 每次带 `--aspect` 的 `render` / `still` / `final` 都会先检查主版：快照完整、当前片段和签批来源一致时确认不变；变了的镜头（比如误改了主版镜头 JSON 或参考图）重渲后与定稿快照逐帧比对，写成 `review/主版不变报告-<后缀>.md/.json`。输入、快照与验证条件相同且上次完整成功，才复用证明；报告保留原测量时间。快照缺失、失败或环境变化不能沿用成功记录。
4. **看主版不变报告**：报告第一行是结论。
   - 「✓ 主版画面没有变化」：照常提交 ⑫。
   - 「✗ 主版有变化」：改镜头时动到了主版画面。先改回去（竖屏的改动只放在副版 JSON 覆盖文件和副版素材里）；确实要改主版的，告诉用户原因，回到第 14 道重新终审主版，再回来做副版。
   - 「! 定稿快照缺失」：换过机器或清过缓存，没法逐帧比对，把列出的镜头的主版静帧（`wkd still <片> --at …`）和用户终审过的成片对照着目视复核，并在提交时说明。
   - **没有报告**，日志说「主版还没在第 14 道签批，跳过主版不变比对」：进度里缺少主版定稿证据。先 `wkd final <片>` 出全分辨率主版，确认画面和终审时一样后，请用户重新签批 ⑪（`--step 14`），引擎会补存定稿快照；然后再出副版，报告就有了。

**提交**：按「审片节点的签批卡片」三步提交：`review/接触表-<后缀>.jpg`、`review/字幕预览-<后缀>.mp4`（无字幕的片子交 `review/小样-<后缀>.mp4`）、`review/主版不变报告-<后缀>.md`（贴原文）和 `storyboard.md` 的「副版重排」表 → 请用户看副版版式、文字与字幕，确认主版没变 → 签批卡片。

**签批后**：

- 副版小样及字幕提交审阅时运行 `wkd delivery <片> --final --json`，保存 `reviewSets[14].deliveryRevision`；用户明确批准后 `wkd signoff <片> "副版小样通过（实际用户结论）" --step 15 --delivery-revision <完整摘要>`。引擎仍记下副版每镜的哈希和当时的主版定稿。后续高清只有实际生成证据及相关来源吻合才继承认可，标明“来源已批准，高清生成核验通过”，不得声称用户打开过高清；不新增审片节点。
- `wkd final <片> --aspect <副版>` 出副版成片（`<name>-<后缀>.mp4` 等，字幕规则同第 13 道），再 `wkd qc <片> --aspect <副版>` 终检；副版终版不再单独审，把日志里列出的文件路径交给用户。
- 之后主版如果返修并在第 14 道重新签批、画面变了，副版就过期：`wkd status` 会提示，`wkd final --aspect <副版>` 会拒绝输出，要重做本道。

✅ **审片节点⑫ 改版审片** → `--step 15`

### 第 16 道 · 剪映草稿交付

成片定版后，把它导出成剪映专业版草稿，交给用户在剪映里接着剪。放在终审之后：草稿写在剪映自己的草稿目录里，不在片目录，git 定版快照管不到，用户在剪映里的改动 wkd 也管不到；等成片定版再出草稿，就不会出现「用户已经在剪映里改了，成片又返修重导」的冲突。

**按已确认的交付选择执行**：简报已选「成片 + 剪映草稿」，成片及所需副版定版后直接准备导出，不再询问要不要草稿；已选只交成片，记录 `wkd signoff <片> "简报已确认只交成片，无需剪映草稿" --step 16`，全片完成，不再追问。仅当简报和已有用户结论都未明确交付形式时，才用卡片询问。用户后来明确更改要求，以最新要求为准。

**导出**（已确认需要草稿）：

1. `wkd check` 确认 pyJianYingDraft 已装（`pip install pyJianYingDraft==0.3.1`）、剪映草稿目录存在（默认 `~/Movies/JianyingPro/User Data/Projects/com.lveditor.draft`；不在默认位置时，请用户在剪映「全局设置 → 草稿位置」查到实际路径，设环境变量 `WKD_JIANYING_DRAFTS`）。
2. 检查剪映是否正在运行；仅检测到运行时，才请用户完全退出（⌘Q）。剪映退出时会把内存里的旧草稿写回草稿目录，引擎会拒绝在运行期间导出；已退出就继续，不重复请求确认。
3. `wkd final <片> --formats jianying`；有副版时用 `wkd final <片> --aspect all --formats jianying`，两种画幅各导一份，草稿名为片名和「片名-<后缀>」。纯草稿只准备经过逐镜校验的片段与分轨，不拼全片、不烧录字幕。写入前交代 `review/草稿声音差异[-画幅].md`。重复执行且来源、回执、内容完整时返回原草稿；用户修改了草稿时停下保留原件，只有明确另导新版才加 `--force`。需要新建时仍用 `_v2`、`_v3` 避让旧目录。

**草稿里有什么**：

| 轨道 | 内容 |
|---|---|
| 视频 | 每镜一段，镜头名即镜号 |
| 人声 | 放在「人声」轨，互相重叠的分到「人声 2」…… |
| 配乐 / 环境声 / 音效 | 按 `audio/build.mjs` 写出的文件各占一条轨，只保留有声音的片段 |
| 字幕 | 有 `subtitles.srt`（字幕方式不是 `none`）就按它，一条字幕一段；否则每条人声一条字幕，没有人声音频的条目时长为估算值，导出日志会列出。重叠的分到「字幕 2」…… |

**交付前自查**：

- 剪映里能看到草稿（看不到就重启剪映）。
- 每镜一段视频，配乐、环境声、音效各占一条轨，人声单独一条轨。
- 字幕有 `subtitles.srt` 就按它，否则每条人声一条，导出日志标了"时长为估算值"的字幕逐条核对。
- 字幕的字号、颜色、描边、离底边距离按风格 `style.json` 的 `subtitles`（片子写了 `film.json` 的 `subtitles.style` 就按叠加后的结果）。
- 剪映用不了任意字体文件，导出器按对照表 `engine/exporters/jianying/fonts.json` 换成剪映字库里的字体（如马善政 → 古风小楷），表里写 `null` 的用剪映默认字体，交付时告诉用户。导出日志出现「在剪映字体对照表里没有对应项」时，草稿里用的也是剪映默认字体，交付时转告用户：要指定剪映字体需要改插件，请用户告诉开发者。
- 字幕样式由 `wkd final --formats jianying` 写进草稿，导出后不要再跑片目录里的样式补丁脚本。读草稿 `draft_content.json` 里的字幕素材，确认字体、颜色、描边已经写入，再如实告诉用户。
- 草稿导出会在当前原生尺寸重新测量字幕，分别写入每条中英文的字号和位置；英文字数、句号是排版建议，不能当作字幕缺失。参数写入成功只代表文件检查通过：交付前还要实际打开新草稿，抽查常规句、最长英文、亮暗背景、安全区和两行间距，保存后重开复核。没有宿主或尚未实际打开时明确写“实际显示未验证”，不能宣称字号合适或可读性通过；剪映替代字体的效果也需单独核对。

**提交**：告诉用户两件事：

- 草稿保留分轨音量和已烘焙的闪避，但没有成片的整体母带响度处理与统一尾部淡出；按导出前生成的声音差异报告在剪映核对，而不是到写完草稿才首次说明；
- 在剪映里的改动 wkd 管不到，之后如果成片返修、重导草稿，会生成新的一份（`_v2`、`_v3`……），旧草稿和用户在里面的改动都还在，不要的可以在剪映里删掉。

✅ **审片节点⑬ 剪映草稿** → `--step 16`

用户保存并完全退出剪映后，运行 `wkd delivery <片> --final --json`，按实际目录展示草稿及 `reviewSets[15].deliveryRevision`，收到明确当前版本认可后 `wkd signoff <片> "<实际用户草稿结论>" --step 16 --delivery-revision <完整摘要>`。实际工具或用户确实报告已打开/播放时才加 `--open-status opened|playback-confirmed` 并在结论中注明操作者、范围与依据；hash 不证明播放成功。手改草稿必须有实际打开依据，机器重新检查磁盘及素材；它的验收不改原导出 marker，不授权覆盖手改目录。运行中、目录不稳定或已变化时先解决对应阻塞，不套用旧摘要。

最终再运行 `wkd delivery <片> --final --host codex`，只展示本次承诺的各画幅视频、字幕和草稿、可用入口、整体状态、缺项/处理人及附录链接；`--aspect <画幅>` 仅表示单画幅。报告在 `review/最终交付清单*.md/.json`，完整证据在 `review/最终交付审计*.md/.json`。返回 2 仍有部分成果，不能当作报告失败或隐藏可用文件；返回 1 才是参数/读取/写入故障。步骤到 15 不等于当前版本交付完整。未知来源、历史未绑定批准、验收后变化须明确说明，不自动重渲或覆盖；交付证据登记失败可用 `delivery --final --record` 重试已有完整证据，不能用它补签或伪造生成来源。纯查询不写账本/state，不下载字体或执行制作。

## 五、返修流程（Revision Loop）

| 返修类型 | 触发 | 执行 |
|---|---|---|
| 节点内返修 | 任一审片节点未通过 | 留在本工序修改，改完重新提交同一节点 |
| 画面返修 | ⑩ 小样或 ⑪ 终审提出画面意见（如"第 3 镜的船太大了"） | 回到第 10 道，只改 `shots/s03.json` 的提示词/参考图或明确的新修订号 → 局部生成与后期（先 `wkd preview <片> --only s03`，确认局部后按整片审阅需要执行 `wkd render <片> --proxy` 或 `wkd final <片> --only s03`）→ `wkd qc` → 有字幕的重跑 `wkd subtitles <片> --preview` → 重新提交原节点（字幕没动，⑨ 字幕不用重审） |
| 声音返修 | ⑪ 终审（或 ⑨ 字幕、⑩ 小样）提出人声 / 配乐意见，或用户后期补录人声 | 回到第 8 道改人声或 `audio/build.mjs` → `wkd soundtrack` 刷新同步点 → 重新提交 ⑦ 声轨审听 → 有字幕的回到第 11 道 `wkd subtitles --force`、重新提交 ⑨ 字幕 → 重新核对模型画面与新声轨的同步，必要时按已确认修订补做镜头：小样阶段重出小样并提交 ⑩，终审阶段 `wkd final` → 重新提交原节点 |
| 字幕返修 | ⑩ 小样或 ⑪ 终审提出字幕意见（错字、断句、位置），或已过 ⑨ 的片子要补字幕 | 回到第 11 道改 `subtitles.srt` 或字幕样式（补字幕先在 `film.json` 加 `subtitles` 再 `wkd subtitles`）→ `--preflight`（已有小样就在小样画面上预检）→ 重新提交 ⑨ 字幕 → 小样阶段 `wkd subtitles --preview` 后重新提交 ⑩ 小样；终审阶段 `wkd final`（镜头读缓存，只重新烧录）后重新提交 ⑪ 终审 |
| 改版返修 | ⑫ 改版审片提出副版意见 | 回到第 15 道只改副版 JSON 覆盖文件与素材 → 重出副版接触表、小样 → 看主版不变报告 → 重新提交 ⑫。意见其实是主版内容的问题：按上面的画面 / 声音 / 字幕返修改完，重新提交 ⑪ 终审，再回到第 15 道（已签批的副版会过期，要重做） |
| 草稿返修 | ⑬ 剪映草稿提出意见 | 草稿本身的问题（缺轨、字幕时长不对）：请用户退出剪映 → `wkd final <片> --formats jianying` 重导（自动起新名字） → 重新提交 ⑬。成片内容的问题：按上面的画面 / 声音 / 字幕返修改完，重新提交 ⑪ 终审（有副版的再过一遍第 15 道），再回到第 16 道重导草稿 |

返修出问题：`git log --oneline -- films/<片>` 找到对应审片节点的定版快照，`git checkout <sha> -- films/<片>` 回滚。

## 六、制作规范

- 新增或变化的审片材料都要停下来等用户签批；13 个节点中，第 5 道未变对象按已有批准继承，无副版时第 15 道跳过。需要新签批而用户未回应时不推进。
- 制作进度以 `.wkd/state.json` 和 git 为准；开工前先 `wkd status`。恢复模型工程时核对当前阶段、批准来源和产物，缺失的审阅证据不得冒充已完成。
- 风格的美术规格书 `STYLE.md` 是硬约束，`禁忌清单` 一条都不能犯。
- 只用开源授权字体；声音用自行合成的，或风格音效清单里明确可商用、按需下载的录音（不拷进片目录、不进 git）；不模仿特定画家、工作室或作品的具体画面。
- 不改插件安装目录里的任何文件（风格 `style.json`、提示词模板、引擎）：片子级的调整写在片目录里（如字幕样式写 `film.json` 的 `subtitles.style`）。发现插件本身的问题，记下来，交付时告诉用户。