dsh-short-video-studio
完全本地 · 免费 · 零云端依赖的短剧 / 动画画布工作室，作为 DeepSeek Harness 双面插件运行。所有生成都跑在本地 ComfyUI 上——不需要任何付费云 API、不消耗额度，装好即用，一次生成、无限出片。
画质已可达 2K / 4K 交付：生成侧有两阶段潜空间放大（hires：首遍 896×512 → latent ×1.5 → 二遍重建，交付 1344×768）与学习式 3D latent 放大（…-2k 族：×2 → 交付 2688×1536）；后处理侧有独立的视频超分能力 video.upscale（逐帧 CNN ×2 / ×4，音轨原样带回）——原生片段一趟 ×4 即到 4032×2304（124 帧实测 241.3s），或 2K 再 ×2 到同样尺寸（261.6s）。三条路线怎么选见分辨率与画质（2K / 4K）。
一句话：Agent 按你定义的 skill 编排流程，把生成请求派发到本地 ComfyUI 执行，产物落进可视化画布，还能通过飞书远程操控创作。
🌟 模型无关：FLUX 2 / MiniMax H3 只是插件随附的内置默认工作流，不是产品边界。本插件是通用的 ComfyUI 工作流执行器 + 能力注册表——任何 ComfyUI 能跑的模型（SDXL / SD3.5 / Qwen-Image / Wan / CogVideoX / LTX / 本地 Kling 等，图片或视频、带不带声音都可以）都能通过导入一份工作流清单接入，skill 与工具契约无需任何改动。换模型 = 加一份 JSON。
功能亮点
🖥️ 本地化、0 成本的视频工作流
- 零云端依赖：默认图片用 FLUX 2、视频用 MiniMax H3 音视频 AV 模型（带声音、支持参考图绑定与画面内原生字幕，对白直接写进 prompt，无需后期叠加）——两者都只是内置默认，可整体替换为你自己的任何 ComfyUI 模型/工作流。
- 画质/速度三档（tier）：图片与视频同一套
fast / balanced / quality——图片长边 1024 / 1344 / 2048（文生图），视频长边 832 / 1344 / 1344；图生图按档给参考图重采样预算 768 / 1056 / 2048（quality 档可出 2K 改绘）。工具面不接受 workflow=：实现由配置决定（设置页的家族偏好 / 档位选择 / 钉实现）。加速不暴露到产品层——设置页每个能力只有一条内置默认策略，其余策略由你自己命名与组合（见下）。分辨率按画布比例 × 该档长边自动推导，支持 16:9 / 9:16 / 1:1 等任意画幅，snap32；显式传 width/height 可覆盖（只传一边时另一边按比例补出来）。
- 图片双模（文生图 / 图生图）：t2i 用 FLUX 2 直接出卡（角色卡 / 场景卡 / 分镜图），i2i 用 FLUX 2 ReferenceLatent 改绘——保持主体不变、换背景 / 场景 / 画风 / 去水印；单张参考图、尺寸跟随参考图（≤1MP），
quality（20 步无 LoRA，保真）/ fast（8 步 Turbo LoRA，调试快），可一次出 1–4 张。
- 同场景续接镜「续得上」：
continuity_from=上一镜节点 id ⇒ 链式续接——把上一镜的服务端 latent 直接钉进本镜（画面逐帧接住它的结尾、音频从接缝继续，实测接缝画面差 2.6–7.0，无续接对照 32–68），不需要上传图片、也不吃画质。r2v 与 i2v 两侧都支持（i2v 链式实现另见下），跨形状续接（上一镜 r2v → 本镜 i2v）同样可用。链的硬约束见档位与加速策略与 docs/shot-chain-continuity.md。
- 画质可上 2K / 4K：三条路线都在本地跑通——生成内两阶段放大（hires，交付 1344×768）、生成内学习式 latent ×2（
…-2k 族，交付 2688×1536，可与链式续接叠用，见下）、以及独立视频超分 video.upscale（画布片段 → 逐帧 CNN ×2/×4，音轨原样带回，原生一趟到 4032×2304 只需 241.3s/124 帧）。超分建议按分镜做（失败只毁一镜、可断点重跑）。详见分辨率与画质（2K / 4K）。
- 完整后处理：同场景续接（链式 latent 或末帧串联）、生成式转场镜、抽帧、拼接合成（本机有 ffmpeg 走零重编码，否则 ComfyUI 纯节点链路）、超分提分辨率——一条龙出片。
- 声线一致性与 BGM：视频参考生成支持参考音频
audio_ref_nodes（H3 Ref2VA 的 <Audio N>，≤3 段 / 每段 2–15s / 总 ≤15s / 单文件 ≤15MB）——同一角色跨镜用同一段声线样本锁音色；extract_audio 可从已渲片段抽音轨存为画布音频节点；音频可入库为 voice: 资产跨会话复用；comfy_generate_music 用本地 MiniMax Music 3 生成 44.1kHz 立体声 BGM（duration 秒 / lyrics 分段）。画布上传支持音频，纯音频默认归 voice refs 组。
- 画面内字幕可开关（开场选择）：
burned-in 要字幕（默认——台词由 AV 模型原生烧进画面，无需后期叠加）/ none 不要字幕（对白照常发声、<d> 说话人绑定照写，但不写字幕声明，成片无字幕；本流程没有后期字幕轨）。开关记在项目简报（没有 state 字段），开场与中途都可改；中途改要改简报 + 重写受影响镜的提示词并重渲。字幕写法仍由 h3-prompt-writing 统一裁定，本项只管「要不要」。
- 片段审查节奏可选（开场选择）：
per-shot 逐镜审查（每渲完一镜人工确认一次，默认推荐——坏镜头当场发现、不会连锁返工）/ batch 批量审查（全部正片 + 转场镜渲完、AI 自检全过后出一张审查卡一次批准——人力往返最少，代价是坏镜头晚发现、续接链上的重渲会成串）。两种模式下 AI 自检都逐镜执行（关键帧抽样 / 角色一致性 / 口型字幕 / 污染 / 风格），差别只在人工确认的时机；口型与字幕字准类问题两种模式都当场弹单镜处置卡。选择持久化在画布 settings.reviewMode，画布头部显示「审查 逐镜 / 批量」，中途可改（改 state 即生效，已渲片段不重做）。
🎨 可视化画布
- 每个会话多一个「画布」tab，按生产顺序预览 / 编辑 / 重做每一步产物：简报、大纲、角色卡、场景卡、镜头表、分镜、逐镜片段、成片。
- 文本节点实时渲染 markdown（标题/表格/列表/代码块），媒体节点直接内嵌预览；分组、排序、删除、入库（一键登记为跨会话资产）都在画布上完成。
- 自己添加资产：画布顶栏「＋ 上传素材」支持本地图片（png/jpg/webp/gif）与音频（wav/mp3/m4a/aac/flac/ogg/opus，单文件 ≤24MB）——图片直接成角色卡/场景卡等资产节点，音频成声线参考节点（纯音频默认归
voice refs 组）；「📚 资产库」带缩略图把已入库的跨会话资产取到当前画布，图片类作 ref 参考、音频类作 audio_ref_nodes 声线参考。
- 入库覆盖四类载体：画布上的图片（角色卡 / 场景卡 / 风格锚点）、视频（镜头片段 / 成片）、音频（声线样本 / BGM，
voice: 资产）、文本与表格（镜头表 / 分镜文档 / 提示词）节点都能点「入库」登记进跨会话资产库；资产 id 与显示名解耦——id 入库时随机生成（形如 character:<16 位 hex>）、永久不变，显示名可随时改（同类型内唯一）；资产库对话框里可重命名（只改显示名，任何画布、文本与历史对话里的引用都不会断）或删除（连同库文件清理，画布上的副本不受影响）。载体与语义类别是两个正交维度：type 决定分组（character / scene / style / clip / voice / text），kind（image / video / audio / text）决定怎么存、怎么取回、以及能不能当 ref 参考图或声线参考。
- 生成的卡也能编辑替换：已生成/已入库的角色卡、场景卡上点「编辑」→ 选本地图即可替换该卡图片（节点/标题/分组保留；若已入库会解除绑定，替换后按需重新「入库」登记新版本）。
- 输入框视频生成（
video-generate skill 的可视化入口）：会话输入框工具行左端保留「🎨 图片 / 🎬 视频」开关。点「🎬 视频」即把 /video-generate 斜杠命令（内联 type/tier/ratio/size/length/refs/first/last 参数）写入官方输入框，用 dsh 原生 skill 加载机制加载内置 video-generate skill；同时在输入卡上方弹出紧凑工具条——类型 r2v（参考图生成）/ i2v（首/末帧生成）、档位下拉（选项来自档位矩阵，带实测耗时）、比例、时长（原生下拉菜单）与「参考图 / 首帧 / 末帧」自定义选择器（来源：画布已有图片节点 / 资产库图片资产 / 本地上传；本地上传经 /canvas/upload 落为画布节点，资产经 /assets/to-canvas 物化到画布，画布节点只引用不复制）。prompt 接着写在官方输入框空行后，改参数时工具条自动重写命令行、保留 prompt；发送直接点 dsh 默认发送键（提交整条草稿，不额外做发送按钮、不劫持 Enter），Agent 按对应 skill 解析命令行参数并调用生成工具出片，产物回进对话并落画布。图片生成（🎨 image-generate）同机制：工具条切换 文生图（t2i）/ 图生图（i2i）——t2i 选比例与张数（默认 1344×768，可 1–4 张）；i2i 从画布 / 资产库 / 本地选单张参考图（图 chip + ➕ 新增格，与 dsh 原生上传同款 64px 样式）、选 quality / fast 档与张数，命令头自动写 /image-generate type=… tier=… refs=<画布节点id>。档位按模式独立记忆：视频默认 fast（调试快）、图生图默认 quality（保真优先），手动选过后各自记住；上传的参考图即画布节点（删除/切型/清空草稿都会同步清理，画布不残留）。
- 跟随 DSH 的浅色 / 深色：画布页自带两套调色板，跟着宿主的主题服务走（含「跟随系统」与自定义主题的
colorScheme）。首屏由 ?theme= 定，避免先闪一下另一种底色；运行中你在设置里一切换，画布立刻跟着换。原生控件（下拉、滚动条、复选框）也跟着 变。
🧩 自由扩展：skill 与 workflow
- skill 可扩展 + 随插件升级自动更新：生产流程完全由 skill 定义（安装时复制到
~/.dsh/skills/，带版本戳：内容没被你改过就随插件升级自动刷新，你改过就只提示、不覆盖）。写一个 SKILL.md 就能定义你自己的片型流程——插件本体不认识任何流程、任何片型词汇。
- workflow 可扩展：插件退化为「通用 ComfyUI 工作流执行器 + 能力注册表」。换模型、换工作流 = 增删一份 JSON，不动 JS、不动工具、不动系统提示。FLUX 2 / MiniMax H3 只是内置默认，你的任何 ComfyUI 工作流（SDXL / Qwen-Image / Wan / CogVideoX / LTX…）都可以直接导入并设为默认（见导入你的 workflow）。
🎬 多场景创作：一套引擎，任意场景
- 默认内置 3D 动画短片、品牌宣传短片与短剧系列制片场景（分集剧本 → 集制作包 → 单集成片），但场景不是插件边界。
- 电商宣传视频（商品/卖点 → 展示分镜 + 口播）、教育课件讲解（知识点 → 图解 + 讲解）、品牌故事、纪念短片、Vlog 解说……任何「输入 X → 产出视频」的创作场景，都通过扩展一个 skill 覆盖——复用同一套画布、生成工具、资产库与飞书交付，只换编排规则（见开发你自己的场景 skill）。
- 场景与模型双解耦：场景由 skill 定义、模型由注册表定义，两者互不绑定——电商场景也可以随时切换到你想用的任何 ComfyUI 模型。
🎨 七套内置视觉风格：一套流程，七种画风
同一个片型 skill（story-short-generator）内置 7 套视觉风格，开场（STEP 0）选定一套，全流程统一使用——角色卡、场景卡、道具卡、逐镜片段与成片都是同一套画风：
| id | 风格 | 适用题材 |
|---|
pixar-3d | 皮克斯感 3D 卡通（默认） | 合家欢、童话、成长、纪念短片 |
cinematic-live-action | 电影真人写实 | 现代剧情、悬疑、犯罪、纪实 |
ghibli-2d | 吉卜力 2D 手绘 | 治愈、自然、成长、奇幻冒险 |
anime-cel | 日式二次元赛璐璐 | 校园、青春、恋爱、日常 |
ink-wash-oriental | 水墨东方古风 | 古装、仙侠、武侠、历史 |
comic-halftone | 欧美漫画半调 | 超英、暗黑奇幻、西部、动作 |
guofeng-xianxia | 国风仙侠 3D | 仙侠、修真、玄幻、古风奇幻 |
七套内置视觉风格示例
上排 guofeng-xianxia · ghibli-2d · anime-cel 下排 ink-wash-oriental · comic-halftone · cinematic-live-action
上图为 6 套风格的 5s 验证帧（fast 档；pixar-3d 未列入本图）。这些帧只用于确认"风格可区分 + 链路跑得通"——实测 fast 档 4 步采样的人脸与细节保真不足（4 套风格的脸都出现年轻化 / 中性化漂移），不能用来验收风格；风格验收与成片请走 balanced / quality。
风格是一份文档，不是一个开关。 每套风格 = 一个 references/styles/<id>.md（8 段固定模板：适用 / 视觉 DNA / 负向 / 风格锁后缀 / 分层适配 / 与参考图契约的关系 / 已知风险 / 实测状态），内含可直接复制的英文风格锁后缀。选型指引与换风格纪律在 references/style-selection.md。
风格锁后缀按产物取用（三段，实测得出）：锁 A · 渲染基调（通用）/ 锁 B · 角色与表演（角色卡 + 视频）/ 锁 C · 环境与氛围（场景卡 + 视频）——因为实测污染是双向的：角色词会把人物拉进空场景，环境词会让纯底角色卡长出松树、石台与光束。风格后缀与负向由片型 skill 拼接，追加在 H3 结构化 prompt 之后。
换风格是破坏性操作：已批准的卡片与全部片段都会失效，须显式确认后重出。
📱 飞书集成：远程操控工作台创作
- 会话可以跑在飞书聊天里（配合 dsh-lark 飞书渠道）——你在飞书里说一句话，Agent 就在本地工作台上按 skill 走完整条流水线。
- 每次提问前，插件自动把画布产物送达飞书：图片/视频直接发原文件，简报/大纲/镜头表/分镜等文本自动导出为 PDF（飞书可直接预览）——无需登录任何后台，聊天里就能收片、审片、下指令重做。
安装说明：dsh-lark 飞书渠道是 web profile 的插件，安装时必须带 --profile web；若希望飞书与 dsh web 共用同一个 profile（同一份插件、会话与工作区，Web 画布与飞书聊天看到同一块画布）：
dsh plugin --profile web add dsh-lark-channel@latest
装好后在飞书里把 bot 拉进群即可开始远程创作；群聊会先弹审批卡、再出选项卡。
快速开始
前置条件：本机或者远程主机已运行 ComfyUI，并已下载你计划使用的模型——内置默认（FLUX 2 / MiniMax H3）或你自己导入的模型（见配置与导入 workflow）。
# 安装插件（三种来源任选其一；npm 为正式发布渠道，推荐）
# ① npm（正式发布，随版本自动更新安装源）
dsh plugin --profile web add dsh-short-video-studio
# ② GitHub（最新源码）
# dsh plugin --profile web add github:fengyungithub/dsh-short-video-studio
# ③ 本地源码（开发用）
# dsh plugin --profile web add file:/path/to/dsh-short-video-studio
dsh web # 重启后会话出现「画布」tab；自带 skill 已自动装到 ~/.dsh/skills/
安装后自动完成三件事：skills/ 下 skill 复制到 ~/.dsh/skills/（版本戳刷新：每个副本的 .dsh-studio-manifest 记下插件版本 + 内容哈希，内容被你改过就只提示、绝不覆盖，没改过才随插件升级刷新；DSH_SVS_SKILL_REFRESH=off 关掉刷新、=force 连改过的也覆盖）；Web 设置页新增 ComfyUI 配置菜单；会话多出「画布」视图 tab。
开始创作：在会话里说
把「一只想当宇航员的小狐狸」做成 30 秒 3D 动画短片
Agent 会按 skill 定义的流程推进：项目简报 → 故事大纲 → 角色卡 → 场景卡 → 镜头表 → 分镜 → 逐镜生成 → 拼接合成，关键节点用选项卡确认。产品界面（真实会话截图）：
输入框生成条（真实 UI 截图）
会话输入框工具行左端「🎨 图片 / 🎬 视频」开关，点开后即在官方输入卡内弹出紧凑参数条，命令头自动写入草稿首行、prompt 写在空行后，直接走 dsh 原生发送键提交（截图均为真实会话）：
视频条：类型 r2v（参考图）/ i2v（首/末帧） · 档位 来自档位矩阵（能力有几个档、每档长边与耗时全部读注册表 —— UI 不预设档位数量与名称，默认取该能力首个可用档）——矩阵未加载时不猜档位，命令行也不拼 tier=（交给服务端按清单解析），并显示解析到的实现 id、加速标记与缺节点告警 · 比例 · 时长，参考图/首帧/末帧可上传画布节点。图片条：类型 文生图 / 图生图——t2i 选比例（1344 长边）+ 张数；i2i 传单张参考图（尺寸跟随参考图）、档位默认 quality、可出 1–4 张。
架构概览
完整设计文档见 docs/ARCHITECTURE.md 与 docs/workflow-contract.md。核心分层：
┌──────────────────────────────────────────────────────────────┐
│ 展示层（浏览器半） lib/client.js + studio/ │
│ 「画布」会话 tab + 「ComfyUI」设置页（配置 / 注册表 / 导入） │
├──────────────────────────────────────────────────────────────┤
│ 契约层（纯数据 + 校验） workflows/*.json + lib/manifest.js │
│ 能力词汇表 · 注入原语 · $assets 占位 · $model 哨兵 · 强校验 │
├──────────────────────────────────────────────────────────────┤
│ 执行层（宿主半） lib/index.js │
│ ComfyUI 客户端 · 渲染编排 · 分辨率策略 · 注册表解析 · 画布存储 │
├──────────────────────────────────────────────────────────────┤
│ 集成层 │
│ Agent 工具注册 · GUIDANCE · HTTP 路由 · skill 安装 · 渠道送达 │
└──────────────────────────────────────────────────────────────┘
设计主张：插件不认识「FLUX」「H3」这些名字，只认识能力（capability）与工作流清单（manifest，数据而非代码）——FLUX 2 / MiniMax H3 只是注册表里「恰好是默认」的两条记录，任何模型接入后享有同等地位。三层正交契约：
| 层 | 内容 | 载体 |
|---|
| ① 任务契约 | Agent 只描述「要什么」：capability + 类型化输入 | Agent 工具参数 |
| ② 能力契约 | 抽象作业词汇表：image.text2image / video.reference2video / video.upscale / audio.tts…（开放集合） | CAPABILITIES |
| ③ 工作流绑定契约 | 一份清单 = 一个 capability → 一个 ComfyUI 图 + 注入点 + 资产 + 质量档（JSON 数据） | workflows/*.json |
清单里的 $assets.<key> 占位让「换模型文件只改配置」；["$model", 0] 哨兵让「按质量档插 LoRA 链」由编译期自动完成。注册表来源优先级：内置 workflows/ < 用户 ~/.dsh/dsh-short-video-studio/workflows/（同名遮蔽）< assetOverrides / 环境变量（换模型文件名，不动图结构）。
分辨率与画质（2K / 4K）
现在的方案可以做到 2K 与 4K 交付。 但要分清一件事：开源版 H3 的原生采样上限就是 768p（1344×768），往更高分辨率直接采样会出复制伪影——所以 1344×768 以上的每一个像素都是放大路线合成出来的。下面三条都是本机实测跑通的路径：
| 路线 | 能力 / 档位 | 机制 | 交付尺寸 | 代价（124 帧，本机 A800 实测） |
|---|
| 生成内两阶段（hires） | image2video / reference2video 的该档实现 | 首遍 896×512 解运动/构图/声音 → 视频 latent 插值 ×1.5 → 二遍重建 | 1344×768（把放大后的画面拉回原生 768p） | 分钟级 |
| 生成内学习式放大（>2K） | …-2k 族的档位实现 | 原生 1344×768 → 学习式 3D latent ×2 → 低 σ 精修 | 2688×1536（fast 档 1664×960） | 二遍精修在 ≈500k token 上超线性：620–2700s（分档） |
| 独立视频超分（U3） | video.upscale 能力 + video_upscale 工具 | 画布上已有视频 → 逐帧 CNN ×2 / ×4 → 收敛到交付尺寸 | 2K：2688×1536（原生 ×2）
4K 级：4032×2304（原生 ×4，或 2K 再 ×2） | 逐帧线性、最便宜：2K 155.7s（比生成内两阶段便宜 10.7×）；4K 241.3s（原生 ×4）/ 261.6s（2K ×2） |
怎么选（产品口径）：要让已生成的片段提分辨率，默认用 video_upscale（U3）——同交付尺寸下它比生成内两阶段便宜 6–10×，且在唯一「干净可比」的格子（2K、同网格、无二次缩放）里有效细节更高（有效宽 ×1.65 vs ×1.425）。生成内两阶段放大（U1）的价值在别处：能与链式续接叠用（链上流动的是首遍 latent，交付尺寸不参与续接），且放大后的 latent 还能被第二次采样消费——但不要再把它当成「上 2K 的手段」，那条路由已被 U3 取代。超分建议按分镜做、不要对成片做：分镜 ≤124 帧落在已验证的显存包线内，失败只毁一镜、可断点重跑。
诚实边界（必读）：2K/4K 的像素尺寸是真的、容器元数据可验（MP4 vide 轨实测 2688×1536），但**「交付 2K」≠「细节等于 2K 渲染」。U3 是逐帧 CNN、没有跨帧先验，它造出来的高频不等于真实细节：实测 2K 交付的有效细节约 1.9K**，即比原生 1344 多约 1.4× 线性（面积 ≈2×）的真细节，但没到 2048、更远没到 2688。所以：倍数放大适合交付规格与观感，不适合「找回本来没有的细节」；两条 4K 路线哪个更好必须眼判（本机提供了 1:1 裁切对照图，见文档）。另外，极高分辨率下 h264 默认档会出现可见块效应，要更干净可先收敛到 4032 或分两步 ×2。
怎么用：超分不写提示词，输入是画布上的一个视频节点——
// 最便宜的真 2K：原生片段 ×2 → 2688×1536
video_upscale({ video_node: '<S01 画布视频节点 id>' }) // 倍率取该实现的自然尺寸
// 4K 级：显式选 ×4 实现并收敛到 4032 宽（高度按比例、32 对齐）
video_upscale({ video_node: '<S01 节点 id>', workflow: 'video-upscale-x4', target_width: 4032 })
// 长素材：手动指定每块帧数（缺省按像素-帧预算自动分块）
video_upscale({ video_node: '<长片节点 id>', target_width: 4032, chunk_frames: 120 })
产物写回画布（kind: video），记 width/height/length/fps（拼接与续接的兼容性判据要用）、upscaleFrom（溯源）、factor/naturalWidth（倍率）与 assets（用了哪个权重）；输出的音轨是原样带回的。生成内两阶段那条路则在配置页把某一档指向带放大的实现即可——不用改 prompt、不用改调用。
选型取舍的完整实测见 docs/video-upscale.md（U1 × U3 取舍、诚实边界、复现命令）、docs/learned-latent-upscale-2k.md（2K 有效性测量）与 docs/hires-two-pass-upscale.md（两阶段放大图结构）。
目录结构
├── lib/
│ ├── index.js # 宿主半：ComfyUI 客户端、渲染编排、画布存储、路由、Agent 工具、GUIDANCE
│ ├── manifest.js # 契约引擎：能力词汇、manifest 校验、图编译、注册表加载
│ ├── concat.js # 视频拼接（ffmpeg 优先 / ComfyUI 纯节点退化）
│ ├── upscale.js # 视频超分的纯逻辑（MP4 自解析探尺寸、两种尺寸来源的规划、分块决策与切片）
│ ├── convert.js # ComfyUI「导出 API」JSON → workflow manifest 转换器
│ ├── assets.js # 跨会话资产库（type=角色/场景/风格锚点/片段/文本 × kind=image/video/text）
│ ├── pdf.js # 文本节点 → PDF（puppeteer-core 优先，CLI 兜底）
│ └── client.js # 浏览器半：画布 tab + ComfyUI 设置页
├── studio/ # 画布页（自包含 HTML/CSS/JS，无构建）
├── workflows/ # 内置工作流清单（数据，非代码）
├── schemas/ # workflow-manifest 权威 JSON Schema
├── skills/ # 自带 skill（安装时复制到 ~/.dsh/skills/）
├── docs/ # 架构 / 契约 / 实验报告
└── scripts/ # 冒烟 / e2e / 导入转换 / 模板生成（h3-templates → workflows）与实测（bench-h3）脚本
内置工作流清单（默认，可替换）
下表是插件随附的内置默认。导入你自己的清单后即可通过 preferred 把它设为某能力的默认工作流——内置清单可以不用、可以遮蔽、可以删除。
| 清单 | 能力 | 说明 |
|---|
flux-text2image-{fast,balanced,quality} | image.text2image | FLUX 2 文生图（角色卡 / 场景卡 / 分镜图）。已分档（一档一清单，group=flux-text2image）：长边 1024 / 1344 / 2048，步数 20 / 20 / 25 |
flux2-img2img-{fast,balanced,quality} | image.image2image | FLUX 2 参考图改绘（ReferenceLatent，尺寸跟随参考图）。已分档：参考图预算 0.5 / 1 / 2 MP，步数 8（+Turbo LoRA）/ 20 / 30 |
qwen-image-21-t2i-{fast,balanced,quality} | image.text2image | Qwen-Image 2.1 文生图（7B MMDiT：原生 2K、可出 RGBA 透明背景、中文提示词强）。图结构 = ComfyUI 官方模板 image_qwen_image_2_1_t2i：UNETLoader → TextEncodeQwenImage21 → KSampler(euler/simple, cfg=1) → VAEDecode，latent 由 EmptyLatentImage 给 ⇒ 任意画幅（含 9:16）。已分档（一档一清单，group=qwen-image-21-t2i）：长边 1024 / 1344 / 2048，步数 20 / 30 / 40（官方 pipeline 40–50 步，官方模板从 25 步起）。前置：ComfyUI ≥ v0.37.0（TextEncodeQwenImage21 是 0.37 起的新节点）+ 三个权重（assets：qwen_image_2.1_int8_convrot / qwen3vl_8b_int8_convrot / qwen_image_2.1_vae_bf16，共 ≈16.1 GiB）。requiresNodes 预检会让旧版 ComfyUI 显式显示「缺节点」而不是跑失败 |
qwen-image-21-i2i-{fast,balanced,quality} | image.image2image | Qwen-Image 2.1 参考图改绘（换装 / 改背景 / 风格迁移 / 构图微调）。参考图同时进文本编码器的视觉塔与 VAE 潜空间（reference_latents），输出尺寸跟随第一张参考图（与 flux2-img2img 同口径，显式 width/height 不参与）。ref_nodes 最多 10 张（prompt 里用 <image1>…<image10> 指代，image_1 是编辑目标）——槽位名是 images.image_1…image_16（1 起），故清单里用内嵌算术 "images.image_${i+1}" 映射 0 起的 refs 下标。参考图重采样预算按档注入（reference_pixels：fast 768 / balanced 1056 / quality 2048 ⇒ quality 档可出 2K 改绘）；1056 一档是规避官方起步值 0 与 1024/1536 网格上锐化噪点/指令失效的已知 issue（ComfyUI #16435，未修复），512 与 1056 干净。QwenImage21Cache(dtype=int8) 把「文本+参考图前缀」的 KV cache 减半。同样已分档（长边由参考图决定，步数 20 / 30 / 40）；前置同上一行 + QwenImage21Cache。权重现在只有 int8_convrot 一份 ⇒ 服务端 comfy-kitchen 版本必须与 ComfyUI 对齐（旧 kernel 会在首个采样步报 ） |
档位（tier）与加速策略
- 视频形状
type 必填：comfy_generate_video(type='r2v', …)（参考绑定，配 ref_nodes）或 type='i2v'（首末帧串联，配 first_frame_node）。r2v 另可传 audio_ref_nodes（≤3 段 2–15s 人声）作 H3 的参考音色（<Audio N>），必须同时有 ref_nodes。形状与参数冲突直接报错并给修法（此前是静默丢弃参数）；形状与续接（continuity_from）正交，详见 docs/video-shape-contract.md。
- 产品层档位是受控三档
fast / balanced / quality，图片与视频同一套（长边按能力不同：图片 1024 / 1344 / 2048，视频 832 / 1344 / 1344）。呼叫 comfy_generate_image(tier=…) / comfy_generate_video(tier=…) / comfy_render(tier=…)。缺省是 quality —— 成本最高（图片 2048 档单张约 45s 量级），抽卡迭代建议显式传 tier=fast（~4s）或 balanced。
- 工具面不接受
workflow=：实现由配置决定（preferred 家族序 / tiers 档位选择 / pins 钉实现，设置页可改）；传 workflow= 会报错并指路。comfy_list_workflows 主输出只给「能力 → 档位（可用性 / 交付尺寸 / 耗时）」，实现 id 收在诊断字段里。
- 请求了不存在的档位不会静默换档：如 i2v 请求
tier=balanced → 工具显式报错并列出可用档位，改请求可用档位即可（不要原样重试）。
- 分辨率读清单（长边）+ 画布比例推导：
fast 长边 832、balanced/quality 长边 1344；工具条会显式传 size=WxH（显式优先）。长边由清单声明，UI 不按档位名硬编码。
resolutionLock：有些实现的尺寸不能被调用方改写。两阶段放大类清单（…-hires / …-2k）的首遍尺寸是图结构的一部分（放大倍率写死在节点上），所以它们声明 resolutionLock: { graph, scale }：显式 width/height 与画布 aspectRatio 都不生效，交付尺寸 = graph × scale，并且一定带一条 warnings 如实说明尺寸被改写。这不是"忽略参数"，是清单在保护自己的底片——从错的尺寸起放大，交付尺寸会与调用方以为的静默不一致。校验 node scripts/smoke-hires-lock.mjs；契约见 docs/tier-strategy-design.md §2、docs/hires-two-pass-upscale.md。- 是另一条尺寸语义：超分不进采样器、不占 H3 的 token，，所以它声明（ + / ）且声明 （两者互斥，校验器会拒）。尺寸来源两种形态：（交付 = 源 × 倍率，像素空间 CNN； 只是事后收敛）与 （交付由实现的推导，扩散/恢复类模型用；此时再声明 ，且声明 让 runner 把短边回注实现—— 因此变成「让模型按目标渲染」而不是先渲染再降采样）。另有一个维度 ：（缺省，逐帧独立 ⇒ runner 可按像素-帧预算自动分块）或 （自带跨帧时间先验 ⇒ 外层切，显存交给实现自己管）。想要固定比例/尺寸的生成用生成类能力，想给已有片段提分辨率用 。
实测耗时（16:9 · 124 帧 ≈ 5.17s）
| 能力 | fast | balanced | balanced 带加速 | quality | quality 带加速 |
|---|
| ref2v（832×480 / 1344×768） | 24.6s | 166.3s | 136.3s | 396.6s | 311.2s |
| i2v（832×480 / 1344×768） | 26.1s | 177.3s | 130.5s | 394.8s | 314.7s |
耗时随硬件、驱动、模型文件版本而变，上表只作量级参考（决定选哪一档、加速值不值得开）。
续接镜（…-ctx-*）：同一档位下比标准实现慢约 1.3–1.5×（多采 22 帧 + 一组 Motion Context 条件）。i2v fast 实测：起链 36.4s / 续接 40.4s（同档标准 i2v fast 对照 30.5s）。
PDD 清单（长边 1344，需自己在设置页组进策略）：ref2v 184.7s / 叠加 Sol 137.3s；i2v 178.8s / 叠加 Sol 134.1s。同条件下的 20 步成片档为 394.4s / 392.4s（PDD 的锐度还高 +10.3% / +7.9%）→ PDD 相当于用 8 步的钱买 20 步的画质。
画质：balanced（8 步）帧锐度比 quality（20 步）高约 13%；fast 档细节最弱、适合调构图 / 走位；PDD 8 步则高于成片档。
⚠️ 版本兼容（v0.1.x → 现在）：组 minimax-h3-i2v（拆分后是多份单档清单，见上表）的 base 已从 minimax_h3_ref2va_pruned_int8_convrot 换成 minimax_h3_fl2va_pruned_int8_convrot（+21GB 下载），LoRA 换成 minimax_h3_fl2v_lightx2v_turbo_4step_v0.1_comfy（+2GB）。原因是原先 i2v 用 Ref2VA base 跑 MiniMaxH3ImageToVideo 属跨变体错配（拿不到 fl2v 系迭代红利）。这两个资产现在由独立配置键驱动（models.h3FlUnet / models.h3FlFastLora，或 env DSH_SVS_H3_MODEL_FL / DSH_SVS_H3_LORA_FL_FAST）——旧键 h3RefUnet / h3FastLora 只作用于 ref2v 档，不再被 i2v 复用。若不想多下 21GB，用配置把它按旧组合钉回去即可（i2v 会退回旧行为）：
"assetOverrides": {
"minimax-h3-i2v-quality": {
"unet": "minimax_h3_ref2va_pruned_int8_convrot.safetensors",
"fast_lora": "minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors"
}
}
旧 id 的配置无需改写（P2 迁移已内置）：assetOverrides 按族继承——新 id 会同时读旧 id 的覆盖（minimax-h3-ref2v-* 继承 minimax-h3-ref2v，*-balanced* 额外继承 minimax-h3-ref2v-8step，minimax-h3-i2v-* 继承 minimax-h3-i2v），且精确匹配新 id 的覆盖优先级更高；旧 models.* 键也按族映射到各档清单。所以你不必逐档重写配置。
⚠️ LoRA 与 shift 必须配对（硬约束）：544p 系 LoRA（ref2v/fl2v 4step v0.1）= shift 12/3；768p 系 LoRA（*_8step_v1.0_768p、fl2v v1.1/v1.2 768p）= shift 6/3，且分辨率必须进 768p 训练域（本插件用 1344×768）。错配不是"略糊"而是结构性崩坏。shift 写在清单 graph 里（modes 不支持按档改标量），所以换档位 pairing 的正确做法是加一份新清单。
Agent 工具契约
| 组 | 工具 |
|---|
| 生成 | comfy_generate_image · comfy_generate_video · comfy_generate_music（BGM）· comfy_render（通用入口，模型无关）· comfy_list_workflows（查能力/工作流） |
| 后处理 | extract_frame（抽帧）· extract_audio（抽音轨，作声线参考）· video_concat（拼接成片）· video_upscale（超分：画布视频节点 → 像素空间 ×2/×4，可换模型与工作流） |
| 画布 | canvas_list_nodes · canvas_write_node · canvas_get_node · canvas_write_prompt_bank（每镜分档提示词） · canvas_get_prompt · canvas_group_nodes · canvas_reorder · canvas_get_state · canvas_set_state |
| 资产 | asset_list（列出跨会话资产，含 kind）· asset_to_canvas（物化回画布：图片/视频/音频→媒体节点，文本→text/table 节点） |
全部工具模型无关：capability 由注册表 preferred 解析到具体工作流，prompt 与流程里不硬编码模型名。
扩展：开发你自己的场景 skill
适配场景：插件默认内置三种场景 skill——3D 动画短片（故事创意 → 角色/场景/镜头/分镜/逐镜/合成）、品牌宣传短片（品牌素材 → 事实核验/创意方向/镜头表/逐镜/合成）与短剧系列制片（分集剧本 → 集制作包 → 单集成片，整部量产）。但场景不是插件边界——任何「输入 X → 产出视频内容」的创作场景，都能通过扩展 skill 覆盖，复用同一套执行层工具（生成 / 画布 / 资产 / 拼接 / 飞书交付），只换编排规则：
| 场景 | 输入 | skill 定义的编排重点 |
|---|
| 3D 动画短片（内置） | 一句话故事创意 | 角色一致、场景连续（七列镜头表含「续接」列 + 链式续接）、镜头表十项自检门、H3 原生字幕 |
| 品牌宣传短片（内置） | 品牌素材 / 推广目标 | 身份核验、来源清单、LOGO 首帧锁定、H3 原生画面文案 |
| 短剧系列制片（内置） | 分集剧本 / 一句话题材 | 系列圣经、集制作包（8 列镜头意图）、资产台账、逐集生产与成本闸门（组合 short-drama-series-writer + story-short-generator） |
| 电商宣传视频 | 商品 / 卖点文案 | 产品展示分镜、口播逐字稿、卖点高光镜、BGM 与节奏 |
| 教育课件讲解 | 知识点 / 讲义 | 图解卡片、讲解分镜、字幕与口型绑定、节奏控制 |
| 品牌故事 / 纪念短片 / Vlog 解说… | 素材与主题 | 按你的业务规范自定义 |
另有剧本层 short-drama-series-writer（自 0xsline/short-drama 收编，MIT）：负责选题、分集大纲与单集剧本，供 short-drama-series-production 调用；只写文本、不出视频。
每个场景 skill 就是一个 SKILL.md（纯文本编排规则），插件对它零认知——触发哪个 skill 就完全按它执行。三步即可定义一种新场景：
- 在
~/.dsh/skills/ 下新建目录（或本仓库 skills/ 下），写 SKILL.md，frontmatter 声明触发条件：
---
name: my-niche-skill
description: 把 X 素材做成 Y 风格短片的完整流程。当用户提到「X 转 Y 短片」时使用。
whenToUse: 适用于……不适用于……
---
## 生产流程
1. 开场：用 canvas_set_state 声明画幅/时长/音频模式/角色卡引用版本（`characterCardVariant` = `single` / `three`；fast 只能 single）/片段审查节奏（`reviewMode` = `per-shot` 逐镜确认 / `batch` 全部渲完一次确认）与分组展示顺序
2. 用 comfy_generate_image 建卡片（**每个角色出单视图 + 三视图两版**；视频引用版本由 STEP 0 用户选择，`fast` 只能单视图；场景卡与道具卡单视图；全部零文字）
3. 用 canvas_write_prompt_bank 落每镜提示词库（三档同文，共用 quality 提示词），再 comfy_generate_video(type=…, tier=…, ref_variant=…, prompt_node=…) 逐镜生成（fast 调试 → quality 成片，换档只变采样、不换 prompt）
4. 用 video_concat 拼接，交付前把文本要点写进回复（飞书自动送达产物）
-
用能力词汇而非模型名：skill 里只写 comfy_render(capability=video.reference2video) 这类调用；具体工作流由注册表 preferred 决定，用户换模型时你的 skill 不用改。
-
关键节点用选项卡确认（ask_user_question），把耐用产物全部落画布。
扩展：导入你自己的 ComfyUI workflow
三种途径，任选其一：
方式 A · 设置页粘贴（推荐）：Web 设置页 → ComfyUI → 工作流导入。粘贴你的工作流清单 JSON，或直接粘贴 ComfyUI「Export (API)」导出的原始 JSON（{nodeId:{class_type,inputs}} 格式）——插件会自动转换：抽取模型资产、识别可注入的标量字段，并输出「待人工确认的语义绑定」清单（哪些字段对应 prompt / 宽高 / 参考图）。
方式 B · CLI 转换：
node scripts/import-comfy.mjs exported.json \
--id sdxl-text2image --capability image.text2image --name "SDXL 文生图"
方式 C · 手写 manifest：参照 schemas/workflow-manifest.schema.json 与内置 workflows/ 示例，写一份清单放到 ~/.dsh/dsh-short-video-studio/workflows/<id>.json（入注册表的触发条件：重启插件进程，或在设置页导入/删除任意一份清单——注册表只在写入后重载，纯刷新不会重读磁盘）。强校验保证错误清单被拒绝而不是静默降级：
{
"id": "my-video",
"version": 1,
"capability": "video.reference2video",
"runner": "comfyui",
"displayName": "我的视频工作流",
"output": { "mediaType": "video", "hasAudio": true },
"assets": { "unet": { "kind": "checkpoint", "default": "my_model.safetensors" } },
"graph": {
"1": { "class_type": "UNETLoader", "inputs": { "unet_name": "$assets.unet" } }
},
"params": [
{ "name": "prompt", "inject": { "type": "scalar", "to": [["5", "prompt"]] } },
{ "name": "width", "inject": { "type": "scalar", "to": [["5", "width"]] } }
]
}
导入后即可用 comfy_render / comfy_list_workflows 按能力调用；同名清单遮蔽内置版本；preferred 决定默认工作流。
配置（个性化）
优先级：环境变量 > 配置文件 > 默认值。Web 设置页的 ComfyUI 菜单提供可视化编辑，保存即生效：
配置文件：~/.dsh/dsh-short-video-studio.json（或 DSH_SVS_CONFIG 指定路径）：
{
"canvasHome": "tab",
"baseUrl": "http://localhost:8188",
"apiKey": "",
"pollMs": 2000,
"timeoutMs": 900000,
"models": { "fluxUnet": "flux2_dev_fp8mixed.safetensors", "h3Fps": 24, "…": "…" },
"tiers": {
"video.reference2video": { "fast": "minimax-h3-ref2v-fast", "balanced": "minimax-h3-ref2v-balanced-sol", "quality": "minimax-h3-ref2v-quality-sol" }
},
"preferred": { "image.image2image": ["flux2-img2img"] } // 写家族名：该家族在各档的实现都会被优先选中,
"assetOverrides": { "minimax-h3-ref2v-quality": { "unet": "my_custom.safetensors" } }
}
canvasHome：画布挂在哪儿。"tab"（默认）＝会话区视图标签页（与「对话」并列，整屏工作态）；"sidebar"＝右侧栏标签页（边看对话边生成，还能浮动成可拖拽缩放的面板）。设置页 ComfyUI → 界面 里改。两种取值下只有一个画布实例——插件启动时只注册选中的那个家，互斥由结构保证，不存在两个 iframe 抢同一份工程的状态问题。入口与「工作区文件」「新建终端」同一套原生做法：右栏折叠时从会话标题栏右上角的展开按钮进入，在引导页点「短视频画布」胶囊。改选即保存，刷新页面后生效（设置页有「立即刷新」按钮）。换家只换挂载点：工程数据、生成能力、Agent 工具全都不受影响；models.* / 环境变量（DSH_SVS_COMFY_URL / DSH_SVS_FLUX_MODEL / DSH_SVS_H3_MODEL_REF / DSH_SVS_H3_MODEL_FL / DSH_SVS_H3_LORA_FL_FAST / DSH_SVS_H3_LORA_8STEP 等）：换模型文件不改图结构；preferred：未分档能力默认用哪个工作流（设置页「设为默认」写回这里）——把你导入的工作流设为某能力的默认，即完成「换模型」，内置清单可保留可遮蔽可删除。H3 视频能力已分档，默认由 tiers / 设置页策略决定，不走 preferred；tiers：已分档能力的档位选择（capability → tier → 实现 id，见 docs/tier-strategy-design.md §4.1）；设置页点选策略/逐档下拉就是写这里。选「内置默认」= 清空该能力的条目（回到跟随注册表首选）；strategies：你自己命名并组合的策略（capability → [{ id, name, tiers }]）。设置页「＋ 新增策略（命名 + 逐档组合）」写这里，可重命名 / 编辑档位 / 删除，上限 24 条/能力；tiers 只需 ≥1 个档位，而策略定义了它提供哪些档位（没写的档位不属于它，请求会显式报错而不是回退）；指向不存在实现的选择在投影时被丢弃（不留死引用）；strategyOf：最近一次点过的策略 id（capability → 策略 id），只用于 UI 点亮与消歧（某条用户策略的组合恰好等于默认时，避免两个单选同时点亮）；真正生效的仍然是 tiers；assetOverrides：覆盖资产文件（同 $assets 机制，优先级最高）。精确匹配该档 id 的覆盖 > 旧 id 继承的覆盖（minimax-h3-ref2v-* 继承 minimax-h3-ref2v、*-balanced* 额外继承 minimax-h3-ref2v-8step、minimax-h3-i2v-* 继承 minimax-h3-i2v）；apiKey 非空时请求带 Authorization: Bearer（适配需鉴权的 ComfyUI 网关）。
关于"某能力的默认工作流是哪一个"：已分档能力（H3 视频）不用 preferred 解析档位——档位由 tiers 配置或各实现里该档的首选（priority 降序 → 非加速优先 → id 升序）决定（见 docs/tier-strategy-design.md）。preferred 对未分档清单（图片能力、你导入的自定义清单）仍是固定选择；没有 preferred 时取候选列表第一个，顺序是确定性的：priority 降序（缺省 0），相同则按 id 升序。想让某份清单永不被选为隐式默认（实验性、依赖自定义节点），在它的 JSON 里写负数 priority（内置的 PDD 清单用 -30；显式在设置页选进策略仍可用，缺节点时如实置灰而不是静默换实现）。internal: true 的诊断清单（如 minimax-h3-ref2v-sol-stats）则完全不参与解析。要显式钉住未分档能力的默认：
"preferred": { "image.image2image": ["flux2-img2img"] } // 写家族名：该家族在各档的实现都会被优先选中
可选的加速件（非内置默认，按需开启）
| 项 | 开启方式 | 实测收益（ComfyUI 0.33.3 / 124 帧 / 同 seed 关开对照） |
|---|
fl2v 8 步 768p LoRA（minimax_h3_fl2v_turbo_8step_v1.0_768p_comfyui_bf16.safetensors，i2v balanced 档） | models.h3FlBalancedLora 或各清单的 assetOverrides.<id>.lora_8step | lightx2v/Minimax-h3-Turbo（Apache-2.0，1.82GB）。必须与 shift 6/3 配对：768p 系 LoRA 配 544p 系的 shift 12/3 会结构性崩坏，而不是「略糊」——这就是该档单列一份模板（scripts/h3-templates/minimax-h3-i2v-8step.json）而非改现有 i2v 清单的原因 |
int8_convrot 视频 VAE（需自行下载 minimax_h3_video_vae_int8_convrot.safetensors，Kijai/MiniMax-H3-experimental） | models.h3VideoVae 或各清单的 assetOverrides.<id>.vae（不设则用内置 fp16） | 解码 ~1.2–1.5×、常驻显存 2.7GB vs 5.0GB；同 seed 抽帧像素均值差 1.88/255（视觉等价）。端到端仅省 ~2s/镜（480p）～~5s/镜（768p） |
日常档 balanced（组「MiniMax H3 参考生成视频」，清单 minimax-h3-ref2v-balanced / -balanced-sol） | 显式传 tier="balanced"（或在设置页把该档选成带加速实现） | 166.3s/镜（带加速 136.3s）vs 成片档 396.6s/镜（省 58%），画质明显优于 4 步 fast 档，帧锐度比 quality 还高约 13% |
| PDD 8 步蒸馏（需自装第三方节点包 ComfyUI-MiniMax-H3-PDD-Acc + 权重 aptech0081/MiniMax-H3-Acc-LoRAs-ComfyUI，Apache-2.0，Ref2VA/FL2VA 各 1.54GB） | 权重必须放 ComfyUI/models/pdd_acc/；配置键 models.h3PddRef2v / models.h3PddFl2v（env DSH_SVS_H3_PDD_REF2V / DSH_SVS_H3_PDD_FL2VA）或 assetOverrides.<id>.pdd；在设置页「＋ 新增策略」里把该档选成 …-balanced-pdd[-sol]（不做隐式默认，priority<0） | 184.7s / i2v 178.8s 即达 20 步成片档以上细节（锐度 +10.3% / +7.9%；噪声地板比 20 步更低）；叠加 Sol 后 137.3s / 134.1s。⚠️ 不能与 lightx2v 叠加、不能超 8 步、shift 固定 12/3、采样器必须 euler。详见 docs/minimax-h3-acceleration-lora.md §9.9 |
档位契约全文：见 docs/tier-strategy-design.md（三层模型、受控三档、清单字段契约、策略＝内置默认 + 用户命名组合、解析与错误语义、实施阶段与验收脚本）。
内置清单不默认使用第三方 int8 VAE：它是社区实验件，通过配置或 assetOverrides 开启，符合"换模型=改配置/加清单"的设计。balanced（8 步）与加速实现（-sol）已改为内置：前者是正式档位之一；后者需自装第三方节点，缺节点时该实现置灰不可用（不静默回退），并在设置页「＋ 新增策略」里自行组合、命名、选用。
H3 加速选型与实测数据：见 docs/minimax-h3-acceleration-lora.md（LoRA 全家福、shift/steps/分辨率/base 四条硬约束、三档成本阶梯、PDD 复测与落地（§9.9）、Sol-Attn 细则、剩余杠杆排序）。
全工作流 Benchmark（分辨率 × 档位 × LoRA × Sol 加速）：见 docs/minimax-h3-video-benchmark.md —— 速查结论表、token/成本模型（分辨率超线性 tokens^1.5、步数线性 t≈19s+18.9s×步数）、Sol 交叉点（768p 才值得，1.25–1.38×）、一条 60 镜短片的时间换算、陷阱与未测清单。取数脚本：node e2e-out/bench.mjs、node e2e-out/inventory.mjs。
I2V 与 Ref2V 的概念差别 · 跨模型选型参考（LTX-2.5 vs MiniMax H3）：见 docs/i2v-vs-ref2v-and-model-comparison.md —— 两种"图生视频"的机制差别、角色一致性 / 分辨率 / 时长 / 速度 / 音频与字幕 / 部署成本逐维对照、按镜头类型的选型建议与未验证清单。本文是技术选型参考，不属于插件契约（插件侧只说能力、保持模型无关）。
渠道交付（飞书 / TUI）
前置：飞书渠道 dsh-lark 是 web profile 插件，需 dsh plugin --profile web add dsh-lark-channel@latest（与 dsh web 共用同一 profile，见飞书集成）。
「画布」tab 只在 Web 可见；跑在 TUI / 飞书时，插件在每次提问（ask_user_question）前自动把画布未送达产物发到飞书：媒体文件直接发，文本/表格节点自动导出 PDF（文件名取节点标题，如 主角卡.png / 简报.pdf）。群聊会先弹审批卡、再出选项卡。Web / TUI 无此通道，产物在画布/工作区，按工具返回的绝对路径自取。详见 docs/channel-delivery.md。
实战要点（沉淀自真实生产）
-
角色卡固定出两版（单视图 + 三视图），视频引用版本由 STEP 0 用户选择：每个角色都建 single 单视图正面全身与 three 三视图横排（正 / 侧 / 背 1×3，纯底零文字），两版用 character / cardVariant / pairedNodeId 配对。参考图风险与档位强相关：fast 档下参考图里有几个身体，画面就倾向出现几个角色，且泄漏样式不固定——多出人、内容被投影成背景墙纸、环境被换掉材质都出现过；balanced / quality 档实测干净（角色卡 / 一图两身体 / 三视图均只出 1 个角色）。⇒ 引用规则：fast 只能单视图；balanced / quality 由用户在 STEP 0 选单视图或三视图；每镜显式传 ref_variant（工具不再按 tier 自动选版），非 fast 档若出现参考图形态类污染，传 ref_variant=single 重渲。prompt 声明「只出现一只」无效。⇒ fast 档对进 ref_nodes 的参考图设形态门禁 G-ref（单主体 / 单视图 / 零文字 / 无拼图），判定键是每次调用实际传入的 tier。场景卡与道具卡不随档位改形态（仍单视图）。证据与强度见 skills/story-short-generator/references/reference-image-contract.md 与旧实验报告。
-
参考图内不得有任何文字：角色名、FRONT VIEW 之类标注会被视频模型渲进成片，fast 档尤甚（文档类参考图会以墙面投影形式把文字烙进画面）。名字只写画布标题与资产元数据。
-
多角度由卡片形态承担，不要临时拼图：单张正面卡足以支撑转身/走远，非 fast 档直接用三视图横排卡；确需更多角度时把多张图分别放进不同 ref_nodes 槽位（实测仍只出 1 个角色），绝不临时拼成一张图。
-
原生字幕：使用带原生字幕能力的视频模型（如内置默认 H3）时，对白字幕写进 prompt 末尾即可端到端渲染（含中文）；换成不带该能力的模型后，此条不适用，字幕需走其它方式。
-
同场景续接优先用链式续接（continuity_from），不是末帧串联：前者把上一镜的 latent 逐帧钉进本镜、音频也接着走，接缝几乎看不出来；后者只是拿一张静帧当首帧，模型仍要重新猜运动与声音。跨场景不续接，只放「角色 + 场景」参考。
-
转场镜与锚点式重渲是 i2v 的两处专用场景：转场镜要精确落回下一镜首帧（末帧锚定），锚点式重渲要在改中段时保住下游首帧。两者都能再叠链式续接（用 …-i2v-ctx-*）：链式 i2v 里首帧锚点会被丢弃（开头由上一镜尾部决定）、末帧锚点保留 ⇒ 尾部连续 + 精确落点同时拿到。
-
角色分状态建卡：同一角色不同着装分别建一对状态卡，每对仍是单视图 + 三视图两版。
-
每镜提示词库落画布（prompt bank）：canvas_write_prompt_bank 写 fast / balanced / quality 三段；当前 story/brand 策略是三段同文、共用 quality 提示词，换档只变采样。生成传 ，工具按 tier 取段、缺档自动回退并告警，生成后回写本档。，不重写 prompt；只传 prompt 时工具也会自动建库并返回 。
参考音频（声线一致性）
- 能一次生成就别切次：H3 官方只保证单次 4–15s 内的多镜头声画同源；跨调用没有官方机制。
- 跨镜音色靠参考音频：
comfy_generate_video(type='r2v', ref_nodes=[角色卡, 场景卡], audio_ref_nodes=[声线样本], …)，并在 prompt 写 <Audio 1> is the voice-timbre reference for <Subject 1> (S1). + <Audio 1>: reference - …（只借音色时不要把参考音频里的原台词搬进成片）。
- 参考音频来源：画布音频节点（上传 wav/mp3/m4a）、画布视频节点（自动取音轨，
extract_audio 也能抽成独立音频节点）、或入库后的 voice: 资产。
- 限制：只有
r2v 支持；≤3 段、每段 2–15s、总 ≤15s、单文件 ≤15MB；2K / hires 实现暂不支持（显式报 audio-ref-unsupported）。
- 档位：
fast 是 4 步 turbo，官方说明会削弱参考/音频强度——要稳住声线用 balanced / quality。
- 续接与参考音频正交：参考音频管“是谁的声音”，
continuity_from 管“接缝不断”；两者可以同镜使用。
背景音乐（audio.music）
- 工具：
comfy_generate_music(prompt, duration=30, lyrics='', seed=…)，产物直接是画布音频节点。
- 模型：内置
minimax-music3（本地权重已装）；纯器乐：prompt 里写 instrumental / no vocals，lyrics 留空。
- 时长：
duration 单位是秒（1–360），与视频的 length（帧数）不是一回事。
- 带人声：
lyrics 用 [Verse] / [Chorus] 分段；BGM 建议纯器乐。
- 混音尚未自动化：目前只产独立音轨；
loudnorm / 对白 ducking / loop crossfade 属于后续交付层工作。
H3 结构化 prompt（本地版 H3-Context-IR 替代）
本地 H3 工作流（minimax-h3-*）的逐镜 prompt 默认走 H3 结构化格式，用「本地 agent + skill」复刻官方云端 H3-Context-IR 的核心产物，提升成片质量（官方明言 Context-IR 直接决定输出质量）：
h3-prompt-writing skill（插件适配版）：官方 MiniMax 规范（references/base-en.txt / ref-en.txt 只读引用）+ 插件映射表 references/studio-mapping.md。参考绑定镜输出 Ref2VA 六段式（subject_definitions / summary / retention_analysis / detailed_description / overall_soundscape / non_diegetic_music）；首末帧串联镜 / 转场镜输出 I2VA / FL2VA 三段式（对齐指令 + integrated_multimodal_description + overall_soundscape + non_diegetic_music）。仅当解析工作流 id 前缀为 minimax-h3- 时启用，其他模型自动回退自由格式（模型无关）。- 片型 skill 委托：故事短片、品牌宣传等片型 skill 的逐镜生成步骤只写「加载 h3-prompt-writing 重写」，不内置任何 H3 字段细节（职能单一）。
- hook 门兜底：
tools/pre-execute 校验 H3 系工作流的 prompt 是否携带结构化字段，缺失时 deny 并引导 agent 加载 skill 重写（同一 agent 连续 2 次后降级放行，不会死循环）。
- 关闭方式：覆盖 / 删除
~/.dsh/skills/h3-prompt-writing 的「插件对接」适配节（或整体删目录）即回到自由格式组装；lib/index.js 的 H3_PROMPT_GATE 常量可单独关掉 hook 门。
✅ 字幕兼容已实测定稿（A/B 六变体，见画布「A/B 实验结论」，配方唯一权威版在 skills/h3-prompt-writing/SKILL.md 的 §字幕）：六段式下字幕以英文双引号 on-screen text 声明内嵌 detailed_description 对白处（中文措辞指令任何位置不生效），四条限定词缺一不可——声明紧贴对白句 + reading exactly "原文" + 强调描边对比 + 只给结束点（不给起止时间窗）；失败写法：给时间窗、台词 1.0s 才起。每档都能出字幕、没有档位硬规则（由用户/脚本需求决定）；实测 quality 20 步逐字一致、balanced 8 步整段未烧、fast 4 步有错字，故成片字幕建议 quality，其余档走自检门逐镜核对后再按需升档。口型安全 / 一致性 / 音频与旧格式同级，动作执行略优。
示例：《一只想当宇航员的小狐狸》
一个完整走完流水线的 30 秒风格化短片（6 镜、quality 档、H3 原生字幕；示例用皮克斯感 3D 风格），展示画布各步骤的真实产物。
角色卡与场景卡
⚠️ 以下角色卡为历史示例（仍属反面）：多视图拼图 + 图内文字标注，且用的是「左侧 1 全身 + 右侧 3 个头部特写」的卡面布局。按现行规则，每个角色应出两版——单视图正面全身 + 三视图横排（正 / 侧 / 背全身，1×3），两版都要求零文字、无分隔线；这三张的标注文字与头特写混排都不符合（fast 档下该布局实测出 5 个副本）。正确做法见上文实战要点。
逐镜成片截图
成片 1344×768 · 24fps · 29.6s · H.264 + AAC（H3 声音）· H3 原生中文字幕。对白（含字幕）：S01「总有一天，我要飞到星星上去！」→ S02「我要做一件宇航服！」→ S03 小兔子「狐狸怎么能当宇航员呀？」→ S04「梦想又不需要翅膀，只需要勇气！」→ S05「看，我就要起飞啦！」→ S06「星星……我来啦……」。
复现：在会话里说「把『一只想当宇航员的小狐狸』做成 30 秒 3D 动画短片」，Agent 会按 skill 的 Step 0→8 逐步落画布并逐镜生成。
更新日志
更早版本的完整变更见 GitHub Releases（每次打 v* tag 自动生成）。
v1.14.0 — 声线参考 + BGM + 短剧系列化（2026-10-23）
✨ 声线一致性：参考音频（H3 Ref2VA <Audio N>）
- 视频参考生成新增
audio_ref_nodes（comfy_generate_video / comfy_render）：≤3 段、每段 2–15s、总 ≤15s、单文件 ≤15MB；支持画布音频节点 / 画布视频节点（自动取音轨）/ voice: 资产 / clip: 资产。
- 只在
type='r2v' 生效且必须同时传 ref_nodes；i2v、2K、hires 实现显式拒跑（audio-ref-shape / audio-ref-unsupported），不做静默降级。
- prompt 守卫：传了音频却没写
<Audio N>（会被当环境音）、或写了 <Audio N> 却没传音频（空绑定），都会给出明确 warning。
- 新增
extract_audio：从画布视频节点抽音轨（有 ffmpeg 走 ffmpeg，否则 ComfyUI LoadVideo → GetVideoComponents → SaveAudio），产物可直接作声线参考。
- 资产库新增
voice 类型 / audio 载体：音频节点可入库、可 asset_to_canvas 物化回画布、可跨会话复用；asset_list(type='voice') 可查。
- 时长校验优先读 WAV 头（本机没有 ffprobe 也能校验 2–15s），其余格式降级 ffprobe / 警告。
✨ 背景音乐：audio.music + MiniMax Music 3
- 新工具
comfy_generate_music(prompt, duration, lyrics?, seed?, steps?, cfg?)，产物直接是画布音频节点（44.1kHz 立体声）。
- 新增内置清单
minimax-music3（audio.music，未分档）：prompt → caption、duration → max_duration（秒，1–360）、lyrics / seed / steps / cfg 注入；纯器乐把 lyrics 留空并在 prompt 写 instrumental。
- 能力面新增
audio.music，comfy_render 可直接按能力调用；音频能力跳过分辨率推导（没有画面尺寸）。
✨ 画布与资产：音频上传 / 声线分组
- 画布顶栏「＋ 上传素材」支持图片与音频（wav/mp3/m4a/aac/flac/ogg/opus，单文件 ≤24MB）；纯音频上传默认归
voice refs 组，卡片仍可改分组。
- 资产库对话框新增「音频」类型；入库覆盖四类载体：图片 / 视频 / 音频 / 文本（kind = image / video / audio / text）。
- 媒体上传路由同时接受图片与音频；
asset_to_canvas 音频资产 → 画布 audio 节点。
✨ 短剧系列化（组合式）
- 新增
short-drama-series-production（v0.1.1）：系列圣经 → 集制作包（8 列镜头意图 + 本集资产清单 + 预填参数）→ 委托 story-short-generator 的 STEP 3–8 → 每集交付 / 资产台账 / 成本闸门；默认 90s / 9:16 / 中文 / 无字幕 / balanced / 单视图 / batch。
- 剧本层
short-drama-series-writer 收编进仓库（自 0xsline/short-drama，MIT，v0.2.0）：选题、分集目录、单集剧本与导出，只出文本。
story-short-generator v3.6.1：STEP 0 新增片型门（短视频故事 / 连续短剧）——选连续短剧时按「画布 → 资产库 → 工作区」三级查剧本，有集制作包直接从 STEP 3 生产，缺包则转 series skill 补齐；并新增声线试镜（STEP 3.5：试镜片段 → extract_audio → voice: 资产，对白镜带 audio_ref_nodes）。
📝 文档 / 测试
- 新增调研与设计文档：
docs/research/h3-audio-consistency.md · h3-audio-local.md · h3-audio-web.md · voice-generation-models.md · music-generation-models.md · audio-capability-roadmap.md · audition-voice-pipeline.md · docs/h3-voice-consistency-plan.md · docs/short-drama-series-integration-research.md。
- 新增冒烟
scripts/smoke-music.mjs / scripts/smoke-voice-ref.mjs 并接入 npm run smoke；新增真机端到端 scripts/e2e-voice-ref.mjs（npm run e2e:voice）。
- README / ARCHITECTURE / H3 映射表同步参考音频、试镜规则与 BGM 能力。
已知限制：参考音频只支持 r2v 的非 2K / 非 hires 实现；BGM 目前只产独立音轨，loudnorm / 对白 ducking / loop 尚未自动化。
v1.13.0 — 资产库重命名与不透明 id + 画面内字幕开关（2026-10-23）
✨ 资产库：重命名 / 不透明 id / 同类型显示名唯一
- 入库 id 改为不透明随机 id：新入库资产 id 形如
character:<16 位 hex>，入库时生成、永久不变；显示名与 id 彻底解耦（老库的可读 id character:luna 保留不动，不做迁移，历史引用继续有效）。
- 重命名只改显示名：资产库对话框新增「重命名」；id、库文件、各会话画布上的
params.assetId / params.model、文本节点与历史对话里的引用全部不受影响，不需要迁移。
- 同类型内显示名唯一：同类型同名再次入库 = 更新同一资产（沿用原 id、保留
createdAt）；重命名撞名返回 409（不同状态也算重名）；不同类型可以同名。
- state 退到历史字段：入库 / 重命名界面不再提供「状态」输入；老资产带的值只在分组标题里只读展示，不参与重名判定、不影响任何行为。
- 落点：
lib/assets.js（newAssetId / renameAsset / findAssetByLabel / 显示名解析）、lib/index.js（POST /api/assets/rename、入库按名更新、asset_list 输出可读字段）、studio/app.js（重命名弹窗、卡片 id / 名字行）、docs/ARCHITECTURE.md、USER-MANUAL.md 第 11 章。
✨ 故事短片 skill：STEP 0 新增「画面内字幕」开关（v3.5.0）
- 开场新增字幕选择：
burned-in 要字幕（默认）/ none 不要字幕（对白照常发声、<d> 说话人绑定照写，但不写字幕声明，成片无字幕）。
- 选择贯通镜头表
字幕 列、逐镜 prompt 组装、门 3 自检与终检；audioMode=silent 时自动 none、免问。本流程没有后期字幕轨，改开关要重写受影响镜的提示词并重渲。
- 落点：
story-short-generator 的 SKILL.md / meta.yaml（v3.5.0）、插件 systemPrompt 口径。
📝 文档 / 测试
- README / USER-MANUAL / ARCHITECTURE 同步资产 id 模型、重命名语义、字幕开关。
- 冒烟：
smoke-assets 145 项（不透明 id / 同名更新 / 老库兼容 / 重命名 / 唯一性）、preview-canvas 91 项（重命名弹窗只有显示名、请求体不含 state、id 不变）。
v1.12.0 — 角色卡双版本 + 提示词库 + 资产名 + 参考图选择器（2026-10-22）
✨ 角色卡：每个角色固定出「单视图 + 三视图」两版
- 出卡规则：每个角色都出
single 单视图正面全身（2:3、纯底、零文字）与 three 三视图横排（16:9、正 / 侧 / 背 1×3、纯底、零文字）；两版共享同一份角色设定与风格锁，用 character / cardVariant / pairedNodeId 配对（comfy_generate_image 新增 character / card_variant / paired_node_id 参数，两节点互记配对 id）。
- 视频引用版本由 STEP 0 用户选择：
canvas_set_state(characterCardVariant='single'|'three')；fast 只能 single，balanced·quality 可选 single 或 three。comfy_generate_video 的 ref_variant 只接受显式 single / three（不再有 auto），每镜按 state + 当次 tier 传入。非 fast 档若自检发现参考图形态类污染（多角色副本 / 参考图版面或文字被投影 / 环境材质被替换）→ 传 ref_variant=single 重渲本镜（同 prompt / 同 seed 优先），再走 prompt 失败阶梯。
- 自检：两版都查（单视图单主体、三视图恰好三格同一角色），并新增跨版本一致性核对（脸 / 发型 / 身材 / 服饰主色 / 签名道具）。
- 落点：
story-short-generator v3.4.0（STEP 0/3/5/5.5/7/门 3/重渲纪律）、reference-image-contract.md、image-generate / video-generate / h3-prompt-writing 的口径与插件 systemPrompt。
✨ 视频提示词分档持久化（prompt bank）
- 每镜一份画布文本节点（group
shot prompts，标题如「S01 提示词（分档）」），用 canvas_write_prompt_bank 写入 fast / balanced / quality 三段；三档写同一份完整 quality 提示词（逐字一致），换档只变采样。工具本身仍支持三段不同内容。
- 生成时传
prompt_node：comfy_generate_video / comfy_render 按本次 tier 读对应段；缺该档自动回退最近较低档（没有则较高档）并在 warnings 说明。生成后工具把本次实际 prompt 回写该档段，所以每次生成的提示词都落在画布上。
- 升档重渲：复用同一个
prompt_node + 新 tier（或同一视频 nodeId 重渲且不传 prompt，工具会读回该镜提示词库）——不重写、不手抄旧 prompt。
- 只传
prompt 也兼容：视频工具会自动创建 / 更新提示词库节点并返回 promptNodeId（persist_prompt:false 可关闭），后续升档用该 id。
- 新增工具：
canvas_write_prompt_bank / canvas_get_prompt；comfy_generate_video / comfy_render 新增 prompt_node / persist_prompt / prompt_group，视频工具另加 ref_variant（显式 single / three，由 STEP 0 用户选择驱动；fast 只能 single）。H3 结构化质检门同步支持从 prompt_node 取段校验。
- 落点：
lib/index.js（prompt bank 解析 / 回退 / 自动持久化 / 工具 / 质检门）、story-short-generator v3.4.0、brand-promo-video-generator v1.3.0、video-generate v1.2.0、docs/prompt-bank.md、scripts/smoke-prompt-bank.mjs。
✨ 提示词库策略更新（全档位共用 quality，同日追加）
- 策略变更：每个镜头的
fast / balanced / quality 三段都写同一份完整 quality 提示词（逐字一致）；换档只改变采样预算，不再更换 prompt。
- 写入方式：先写一份 quality prompt，再用
canvas_write_prompt_bank 原样复制到三段；不再为 fast / balanced 另写精简版。
- 工具不变：
prompt_node 仍按 tier 取段，三段同文时读到的都是同一份 quality 文本；缺档回退机制保留，正常流程不会触发。
- 旧库迁移：已有三档不同文案的
SXX 提示词（分档），先读 quality 段，再用 canvas_write_prompt_bank(nodeId=…, prompts={fast:q, balanced:q, quality:q}) 统一；Skill 已把这一步写进流程。
- 依据与边界：1 seed pilot 显示“全档同文”不会崩，但 fast 档会出现构图拉宽、人物变小，quality 档的表演落点也可能偏移；因此这是流程策略选择，不是“全档更优”的保证。生产仍以门 3 自检的动作/走位/景别为准。
✨ 资产库命名支持中文
slugifyName / normalizeAssetId 从「只允许小写英文/数字」改为允许 Unicode 字母/数字（含中文） + . _ -：中文标题不再被吃掉，POST /assets 可直接登记 character:小狐狸 这类资产 id；文件名为 character-小狐狸.png，跨会话 asset_to_canvas / ref_nodes / /media 均按 URL 编码正常工作。- 画布入库表单的默认名与提示同步改成「中文 / 英文 / 拼音都可以」；非法名（如含冒号）仍返回 400 并说明规则。
✨ 输入框图片 / 视频参考图支持从画布与资产库选取
- 「🎨 图片 · 图生图参考图」与「🎬 视频 · r2v 参考图 / i2v 首末帧」的「＋」现在打开统一选择器：从画布已有图片节点、资产库图片资产、本地文件三处取图。
- 画布节点是引用：移除时不删除原画布卡；资产库图片会先物化到画布，移除时只删这份物化副本；本地文件仍按原逻辑上传落画布。
- 资产库选择器只列图片类资产（角色 / 场景 / 风格锚点），视频 / 文本资产不会出现在参考图列表里。
v1.11.0 — 片段审查节奏可选：逐镜审查 / 批量审查（2026-10-12）
✨ story-short-generator v3.2.0 · 新增开场选项：门 3 的人工确认时机可配
- STEP 0 新增「片段审查节奏」选项卡（第 8 项）：
per-shot 逐镜审查（默认推荐——每渲完一镜 AI 自检 + 人工确认，确认通过才渲下一镜；坏镜头当场发现、返工不连锁）/ batch 批量审查（全部正片 + 转场镜渲完、自检全过后出一张批量审查卡一次批准；人力往返最少，代价是坏镜头晚发现，且续接链上的重渲会成串）。
- AI 自检在两种模式下都逐镜执行、不许推迟——批量审查省的只是「人工确认次数」，不是「自检次数」。门 3 自检第 3 项（口型 / 字幕字准）不过关时，两种模式都当场弹单镜处置卡，不压到批量卡里；「同一镜连续 3 次失败」的求助门同样保留。
- 持久化：
canvas_set_state 新增 reviewMode（per-shot | batch，缺省 per-shot），画布头部显示「审查 逐镜 / 批量」；STEP 7 渲染前 canvas_get_state 读回，中途可改（改 state 即生效，已渲片段不重做）。
- 批量模式的纪律：批准以整卡为单位（不接受部分批准——要改就重渲选定镜，然后只列受影响片段重出批量卡）；片段收集、转场镜、拼接、重渲连锁纪律都按
reviewMode 分支描述。
- 未改动
brand-promo-video-generator：品牌片当前没有逐镜人工门（片段后一次确认），本次不动，两侧口径保持各自现状。
- 落点：
story-short-generator 的 SKILL.md（STEP 0 / 1 / 7 渲染前的门 / 门 3 / 转场镜 / 片段收集 / STEP 8 拼接 / 选项卡纪律 / 重渲连锁纪律）与 meta.yaml；插件 canvas_set_state 工具 schema、画布头部元信息。
v1.10.0 — 角色卡形态分档：单视图 / 三视图横排随视频档位（2026-10-10）
✨ story-short-generator v3.1.0 · 规则变更：角色卡默认形态跟着项目视频档位走
fast → 单视图正面全身（一图一人）；balanced / quality → 三视图横排（正 / 侧 / 背全身，1×3，纯底、零文字）。判定键是 STEP 0 选定、canvas_set_state(mode=…) 持久化的视频档位（不是图片档位——图片档位只决定采样尺寸）。fast 档的形态门禁 G-ref 不变，仍按每次调用实际传入的 tier 判定；混合档位下最常见的踩线点是非 fast 项目里把某镜临时降到 fast——该镜要么升档、要么临时补一张单视图。- 只改角色卡：场景卡、道具卡不随档位改形态（仍单视图）——多视图对这两类资产在非
fast 档没有实测依据。
- 卡片画幅：单视图 2:3 竖版（
fast 672×1024 · balanced 896×1344 · quality 1344×2016）；三视图 16:9 横版（fast 1024×576 · balanced 1344×768 · quality 2048×1152）。尺寸按图片档位长边推导，32 对齐。
- 依据：
fast 档多主体参考图必漏（角色卡 4 身体 → 成片 5 个实例）；balanced 档角色卡、quality 档三视图实测均只出 1 个角色，且「档位 vs 实现」混淆已由钉实现实验拆开（差异跟档位 / 采样配置，不跟实现家族）。完整矩阵见 reference-image-contract.md。
- 待补证（已登记在契约 §4）：
balanced 档的三视图横排、quality 档的角色卡布局尚未单独实测——按多主体 + 纯底 + 零文字的共性外推。
- 落点：
story-short-generator 的 SKILL.md（STEP 0 / 3 / 4 / 4.5 / 5.5 / 7、参考图形态与档位节）、references/{asset-catalog,reference-image-contract,style-selection}.md、7 份 references/styles/*.md、meta.yaml；image-generate / video-generate / h3-prompt-writing 的口径同步；插件 systemPrompt 的「参考图硬规则」同步。
v1.9.0 — skill 改名 story-short-generator · 七套视觉风格 · 道具卡 · 参考图形态门禁（2026-10-08）
⚠️ 破坏性变更：自带 skill 改名
3d-animation-short-generator → story-short-generator（目录名与 frontmatter name: 同步改）。原因：新增电影真人写实 / 吉卜力 2D 手绘等风格后，「3D」已名不符实。- 升级后一般无需手动清理：
syncBundledSkills 新增孤儿回收——目标端带本插件安装戳、但源 bundle 里已无同名目录的 skill 会被自动删除。安全底线：无安装戳的目录（非本插件安装）永不删；你改过的副本默认也不删，只提示（DSH_SVS_SKILL_REFRESH=force 才强删）。
- 如果你改过旧 skill 副本（或在别处装过同名 skill）：确认不需要后手动
rm -rf ~/.dsh/skills/3d-animation-short-generator。
✨ story-short-generator v3.0.0
- 七套内置视觉风格（STEP 0 可选，默认
pixar-3d = 旧行为）：皮克斯感 3D / 电影真人写实 / 吉卜力 2D 手绘 / 日式二次元赛璐璐 / 水墨东方古风 / 欧美漫画半调 / 国风仙侠 3D（guofeng-xianxia，仙侠 / 修真 / 玄幻）。一风格一文件（references/styles/<id>.md，8 段固定模板，含可直接复制的英文风格锁后缀），选型指引与换风格纪律在 references/style-selection.md。原全局写死的风格锁（含「不要写实真人摄影」——与真人风格直接冲突）已按风格拆分。
- 风格锁后缀按产物取用（抽卡实测换来的规则）：后缀拆成 锁 A 渲染基调（无角色词也无场景物件词，通用）/ 锁 B 角色与表演（角色卡 + 视频）/ 锁 C 环境与氛围（场景卡 + 视频）。污染是双向的——角色词会让空场景冒出人物（
anime-cel / ink-wash-oriental / comic-halftone 的场景卡均复现），环境词会让纯底角色卡长出松树石台与光束（guofeng-xianxia 复现）。⇒ 场景卡/道具卡不带 B，角色卡不带环境段。
- 新增道具卡（STEP 4.5 + 画布分组
prop cards）：签名道具单独建卡并可进 ref_nodes，避免形状 / 材质逐镜漂移。收编为单视图单件（film-assets 的多视图道具卡不适合本流程的参考绑定）。资产库无 prop 类型，入库推荐归到 scene（id 形如 scene:prop-<name>）。
- 参考图形态门禁 G-ref（仅
fast 档）：实测确认「多主体参考图出副本」是 fast 档特有现象——fast 档下角色卡出 5 个、一图两身体出 3 个、三视图让环境被换材质、设定图被投影成墙纸；balanced / quality 档全部只出 1 个角色（同一 prompt、同一 seed）。故 fast 档强制「单主体 / 单视图 / 零文字 / 无拼图」，不通过则不出图、给四个出路。完整矩阵与结论强度见 skills/story-short-generator/references/reference-image-contract.md（「档位 vs 实现」混淆已在随后一轮钉实现实验中拆开——差异跟档位/采样配置，不跟实现家族；每格 N 仍小，属方向性证据）。
- 新增资产目录
references/asset-catalog.md（角色卡 / 场景卡 / 道具卡 / 风格锚点 / 片段 / 文本：形态规范、生成要求、自检项、入库限制）。
- 图片档位独立于视频档位，默认
quality：STEP 0 新增「图片档位」选项卡（与「生成档位（视频）」分开）。图片默认走 quality（长边 2048）——卡片是全程复用的身份 / 环境锚点，细节不够会连带重做镜头表、分镜与已渲片段。balanced / fast 只用于抽卡试构图，其产物不得直接锁定（锁定前须用选定档位重出定稿）。原「生成档位」一项现在明确为视频档位。
- 镜头表自检门从十项扩到十一项（第 11 项：按当前档位的参考图形态合规）；门 3 自检新增第 6 项（风格一致）；终检新增道具一致性与风格一致性。
📝 文档 / 其它
- 插件 systemPrompt 的「参考图硬规则」改为档位限定表述（原文把
fast 档的结论当成了普适规则）。
docs/three-view-experiment.md 追加「补记：档位维度」——原实验全程只跑 fast（mode=fast、4 步 Lightning LoRA、832×480），结论未被推翻，只是缺档位维度。- README 实战要点 1–3 同步档位限定；
scripts/smoke-skill-install.mjs 新增 4 组孤儿回收用例（含「无戳目录永不删」安全底线）。
v1.8.1 — 仓库不再跟踪 pnpm 本地缓存（2026-09-29）
包内容零变化：本版只动仓库卫生（.gitignore + 取消跟踪），lib / studio / skills / workflows / schemas 与 v1.8.0 完全一致，升级无行为影响。
📝 文档/其它
- 仓库不再跟踪
.pnpm-store/：pnpm 在本机默认把 store 建在项目根（.pnpm-store/v10），这个 31 MB / 2315 个内容寻址文件的纯下载缓存因 .gitignore 漏配规则被一次 git add -A 误入库、并随 v1.8.0 推到远端。本版补上忽略规则并 git rm -r --cached，磁盘缓存与 node_modules 原样保留。
- 顺带说明为什么此前没被发现：
package.json 的 files 白名单本就不含它，npm tarball 一直是干净的——污染只在仓库体积（.git 里 25.6 MB）。历史清理需重写历史 + force push，本版未做。
v1.8.0 — 统一档位与工具面（图片并入 tier · 不再接受 workflow=）· Qwen-Image 2.1 接入 · 超分尺寸契约（2026-09-24）
⚠️ 破坏性变更：① comfy_render(workflow=…) / video_upscale(workflow=…) 会报错并指路——实现改由配置决定（preferred 家族序 / tiers 档位选择 / pins 钉实现）；② 图片清单 id 由 flux-text2image 变为 flux-text2image-{fast,balanced,quality}（一档一清单）；③ 旧参数 mode= 已移除，档位一律用 tier=。
✨ 新增
- Qwen-Image 2.1 接入（文生图 + 图生图，各三档共 6 份清单）：官方模板图结构（
UNETLoader → TextEncodeQwenImage21 → KSampler，i2i 多一层 QwenImage21Cache），需要 ComfyUI ≥ v0.37.0；原生 2K（1:1 2048² / 16:9 2752×1536 / 9:16 1536×2752 实测 63–65s，int8 三件套 ≈16.1 GiB）。i2i 参考图可传 10 张，ref_nodes 按 1 起的槽位 images.image_N 映射。
- 图片与视频统一到同一套档位体系：图片能力从「未分档 +
mode 轴」并入 tier（fast / balanced / quality，一档一清单、group = 家族）。图片长边 1024 / 1344 / 2048（t2i），i2i 按档注入参考图重采样预算 768 / 1056 / 2048 ⇒ i2i 首次能出 2K 改绘。
- 清单由模板生成：
scripts/image-templates/*.json（4 个家族）→ scripts/make-image-variants.mjs → 12 份 workflows/<家族>-<档位>.json；--check 已进冒烟链（产物与模板漂移即失败）。
- 配置面「钉实现」
pins + preferred 升级为家族序：pins["image.text2image"]="qwen-image-21-t2i"（家族名或实现 id，跨档冲突会报错）；原有 preferred: ["qwen-image-21-t2i"] 这类家族名写法零改动继续生效。
- 视频超分尺寸契约：
upscale.sizing（factor = 交付 = 源 × 倍率；short-side = 交付由实现的目标短边推导，target_width 变成让模型按目标渲染）与 upscale.chunking（caller 可被外层分块 / internal 自带跨帧时间窗、外层不切）；SeedVR2 实现 video-upscale-seedvr2-3b 随包发布（v1.7.0 文档提到过、当时未随包）。
- 设置页：默认只列策略与名称，档位表单点该策略的「编辑档位」才展开（内置默认那条＝一次配齐逐档实现，保存为逐档显式选择；另有「恢复跟随首选」）；后端新增
effective 矩阵，设置页标题/摘要/表单预填与实际执行同源。
🐛 修复
- 删除「按 mode 名隐式挑实现」路径——它是「同一请求被悄悄换成另一个模型」的根因（实测踩过：漏传
workflow 时落到了别的模型）；未分档能力现在只按 preferred / 候选序取一个，并明确告警忽略请求档位。
- 交付尺寸如实记账：产物落盘后读真实像素回填节点
width/height（i2i 不再把名义 1344×768 记成交付尺寸），与首遍尺寸不同时另记 graphWidth/graphHeight。
- 未支持参数显式告警：调用方传了、实现没有注入点的参数进
warnings（工具返回 + 节点 params.warnings），不再静默丢弃（如 Qwen 清单的 guidance、i2i 的 width/height）。
- 只传一边宽高不再被静默忽略：另一边按画布比例推导（此前只有
width && height 同时给才生效）。
- 图片分辨率跟随画布比例：图片清单改用
policy: "aspect-ratio"（此前 explicit 下画布 9:16 对图片无效，竖版必须每次显式传宽高）。
📝 文档/其它
- 新增
docs/unified-tier-tool-design.md（统一档位与工具面的设计定稿 + 决策记录 + 滚动状态）与 docs/open-issues.md（登记已查证但暂不实施的问题，首个条目＝ 3d skill 的角色卡/场景卡未定义档位与尺寸）。
- README 全面同步：去掉
workflow= / mode= 旧口径，补图片档位表与「工具面只认 capability + tier」契约。
- 冒烟链加入
variants:check；新增 npm run e2e:tier（真机跑 t2i/i2i/video 三能力并核对记账）；设置页走查支持 --edit-builtin / --block=<capability> 局部截图。
v1.7.0 — 两阶段放大（hires / >2K）· 视频超分（U3）· resolutionLock（2026-09-23）
✨ 新增
- 视频超分
video.upscale（U3）：新能力 + 新工具 video_upscale(video_node, …)。输入是画布上已有的视频节点（不是提示词），逐帧 CNN ×2 / ×4，音轨原样带回（全程不经过模型，也不占 H3 的 token）。内置像素链路 video-upscale-x2（RealESRGAN_x2.pth）/ video-upscale-x4（RealESRGAN_x4.pth），模型走资产槽 upscale_x2 / upscale_x4（换权重必须换同倍率的，倍率写死在权重里）；另有扩散式的 video-upscale-seedvr2-3b（SeedVR2，ComfyUI 原生支持、无需自定义节点；交付尺寸直接喂模型所以 target_width 真驱动；priority=-20 不做隐式默认；实测 124 帧 2K 483.4s vs U3 的 69.0s，细节更多但平坦区会注入细颗粒）。交付尺寸 = 源尺寸 × factor，可用 target_width 收敛（按 32 对齐）；比例永远跟源片——H3 族是 1.75:1，所以 4032 宽对应 4032×2304，不是 16:9 的 3840×2160。逐帧独立 ⇒ 代价线性、天然可分块，长片按 ImageFromBatch + TrimAudioDuration 切块再拼回（不需要 ffmpeg）。实测 124 帧：原生→×4→4032 241.3s；U1 的 2K→×2→4032 261.6s；248 帧 5376 一次过 551.4s（无 OOM）。详见 docs/video-upscale.md。
- 两阶段潜空间放大（hires）：
minimax-h3-ref2v-hires / minimax-h3-i2v-hires（仅 quality，priority: -50）。开源版 H3 原生上限就是 768p，往更高直接采样会出复制伪影 ⇒ 首遍 896×512 解运动/构图/声音 → 视频 latent ×1.5 → 二遍 denoise 0.35 重建细节，交付 1344×768 带声音（音频 latent 全程未被放大、二遍不进音频分支）。模板由 scripts/make-hires-template.mjs 从 ref2v/i2v 两个 base 各自派生，两阶段尾段逐字节一致。详见 docs/hires-two-pass-upscale.md。
- >2K：学习式潜空间放大 + 链式续接：
minimax-h3-{ref2v,i2v}-ctx-{quality,quality-pdd2,balanced,fast}-2k（8 份在役；-balanced-pdd-2k 一对已弃用）。hires 的插值放大器只能把首遍拉回原生 768p，要超过原生上限，放大器必须在 latent 空间真造细节 —— 用 MinimaxH3LatentUpscaler3DRefineHandoff（custom_nodes.Comfyui_Minimax_h3_latent_Upscaler，权重 minimax_h3_latent_upscaler_3d_conv_v1_bf16.safetensors，本机已装）做 ×2 放大 + 低 σ（denoise 0.3）精修。首遍尺寸不锁（）：图内目标尺寸是算术模板 ，跟着画布比例 × 档位长边走 ⇒ ——16:9 交付 （ ）、9:16 交付 （ ）、1:1 交付 （ 1664×1664，像素量为 16:9 的 ，最重）。、各档一份清单、（精修在 ≈500k token 上超线性）。跨比例链式续接（判据是首遍尺寸一致）。⚠️ ： 档 124 帧实测峰值 72.6/79.2 GiB（余量 6.6 GiB）且另有一次被中断 ⇒ 1:1 尽量压帧数；高分辨率档的 1:1（2688×2688）未实测。详见 。
🔧 修正
- 「两阶段放大不能与链式续接叠用」是错的：正确判据是「同一条链内首遍尺寸一致」。放大发生在链式存档之后（
MiniMaxH3MotionContextSaveLatent 读的是首遍采样器输出）⇒ 链上流动的永远是首遍 latent，交付尺寸不参与续接——一条链里可以有「首遍相同、交付不同」的镜（-ctx-quality 1344×768 接 -ctx-quality-2k 2688×1536），首遍不同则显式拒跑。runner 按此实现（chainGraphMismatch，纯函数）。
- PDD 清单补
MiniMaxH3PDDAccApply 依赖声明：minimax-h3-i2v-ctx-balanced-pdd 及其模板此前漏声明该第三方节点，缺节点时可用性预检会假装可用。现已在 requiresNodes 补上（缺节点如实置灰，不静默回退）。
✅ 验证
- 新增
scripts/smoke-hires-lock.mjs（resolutionLock 语义 + 插值/学习式两阶段图结构 + 通用契约块：枚举所有带锁的实现）、scripts/e2e-hires.mjs、scripts/e2e-upscale.mjs、scripts/smoke-upscale.mjs、scripts/probe-2k.mjs、scripts/probe-2k-aspect.mjs（画幅比例出片探针，独立进程直连 ComfyUI 以绕开插件的模块缓存）、scripts/probe-pdd-sigmas.mjs、scripts/analyze-2k-detail.mjs、scripts/compare-crops.py。
scripts/smoke-tier-resolution.mjs 109 断言、scripts/verify-h3-variants.mjs 154 断言（各份单档清单的 id/档位/尺寸/可编译性），全部通过。- 新增实测报告：
docs/2k-pdd-ab-verdict.md（2K + PDD 的 56/124 帧 A/B：全长 2.02×、画质持平且判据略优、音轨逐样本相同）。
- 画幅比例实机出片（
fast 档，产物尺寸从 mp4 box 直读，不信工具自报）：9:16 → 960×1664 带音轨，638.5s（首遍 480×832；像素量与 16:9 相同 ⇒ 解比例零代价，耗时落在 estSeconds 口径上）；1:1 → 1664×1664 带音轨，992.8s（22 / 56 / 124 帧都出片）。⚠️ 1:1 峰值显存 72.6/79.2 GiB（余量仅 6.6 GiB，另有一次运行被中断），且耗时是 estSeconds 的 1.6×——estSeconds 是 16:9 · 124 帧口径，UI 原样显示、不按帧数或画幅修正；高分辨率档的 1:1（2688×2688）与 9:16 未实测。
v1.6.0 — 资产库支持三种载体 · 可删除（2026-09-18）
✨ 新增 / 改进
- 入库不再只管图片：此前只有
kind === 'image' 的节点才有「入库」按钮，视频片段、镜头表、分镜文档、提示词这些同样值得跨会话复用的产物只能干看着。现在 图片 / 视频 / 文本 / 表格 节点都有「入库」按钮（生成失败、已作废的节点也照有——入库只看节点类型，不看生成状态）。
- 载体（kind）与语义类别（type）拆成两个正交维度：
type 决定资产库里的分组与用途（角色 / 场景 / 风格锚点 / 视频片段 / 文本），kind 由 type 推导（character|scene|style → image、clip → video、text → text）并决定怎么存、怎么取回、能不能当 ref 参考图。两个直接收益：
- 入库表单的类型下拉按节点载体收窄——视频节点只给「视频片段」，文本节点只给「文本」，图片节点仍是「角色 / 场景 / 风格锚点」。服务端还会再校验一遍（比如「视频节点 + 角色卡」直接 400 并说明允许的类型），避免库里出现语义错位的记录——agent 拿到一条
character:xxx 会当成参考图去驱动生成，必然失败。
resolveAssetImagePath 现在硬性只认 image，视频/文本资产永远不会被当成 ref_nodes 图片传给 ComfyUI；视频/文本要走 /media?asset= 时改走 resolveAssetPath（此前该路由只认图片，视频资产会 404）。
- 文本资产不落文件，存正文：入库
text/table 节点时保存 text + title + nodeKind，取回画布时按 nodeKind 还原成 text 还是 table——表格类资产取回来仍是表格，不会退化成纯文本。
- 资产库可删除（对话框每张卡片新增「删除」，二次确认）：删除索引的同时清理库文件，但有两个安全边界——① 仅当库里没有别的记录引用同一文件时才删（同图多状态/多名字的情况不会误删）；② 画布上已取用的副本不受影响（它们是各自独立的文件），确认文案里写明了这一点。删除接口是
DELETE /api/assets?id=…，返回 fileDeleted 说明是否连带删了文件。
- 对话框按载体渲染缩略图：图片用
<img>，视频用 <video>（右上角挂「🎬 视频」角标，取不到时回落成「🎬 视频缺失」），文本资产不请求图片、直接把正文摘要显示在缩略图位（6 行截断）。
- 顺带修掉一个 500：入库名不合法（如含冒号的名字）时
normalizeAssetId 抛的是普通 Error，路由没转成 HttpError，前端拿到的是 500 而不是带原因的 400。（中文名已从「非法」改为合法，见 v1.12.0。）
🎨 走查中量出来并修掉的两处
- 「＋ 加入画布」被挤成两行：加上「删除」按钮后卡片里两个按钮共 144px，实测卡片宽 172.5px 时主按钮只剩 92.5px，文案折成 2 行（截图走查发现，随后改为量
Range.getClientRects() 的行数断言）。把资产网格最小列宽 168px → 190px（主按钮 154px）并加 white-space: nowrap，两套主题下按钮都是单行。
- 缩略图占位文字在浅色主题不达 AA：
.thumb .missing 借用 --muted，而缩略图底色两套主题都是纯黑——浅色主题的 --muted（#5c6470）压黑底实测只有 3.51:1。新增与主题无关的 --media-fg（#aab2bf，黑底上 ~9:1）。这是存量问题，只是此前没有测到资产库对话框。
✅ 验证
- 新增
scripts/smoke-assets.mjs（77 项）：隔离 HOME/配置/skill 目录后 apply() 起真路由，对 handleApi/handleMedia 发真请求——覆盖三种载体的入库、非法组合（视频+角色卡、audio 节点、空文本节点、非法名）分别落到 4xx、GET /assets 给老记录补 kind、视频资产 /media 的 content-type 与字节、to-canvas 三种产物化（视频→video 节点、文本→text、表格→table）、删除（含共享文件不误删、最后一条引用才删文件、文件本就不存在时不报假的 fileDeleted）、以及 v1.4 旧库（只有 {type, image}）的兼容与覆盖登记不残留旧字段。
scripts/preview-canvas.mjs 46 → 82 项：新增真浏览器交互段——打开资产库对话框核对三种载体的缩略图分支、分组、按钮与危险色，开着对话框切浅/深主题并复测对比度，点删除走确认→确认后列表与分组同步消失（并断言真的发出了 DELETE）；再逐个节点核对「入库」按钮的有无与三个下拉的选项集合；正文可滚动、滚到底最后一张卡完整可见；按钮行数与截断用 Range 行盒实测。- 两个新截图：
e2e-out/ui/canvas-asset-library{,-light}.png、canvas-asset-register.png。
v1.5.0 — 画布跟随 DSH 浅色/深色 · 顶栏文案与布局（2026-09-18）
✨ 新增 / 改进
- 画布页现在跟随 DSH 的浅色/深色（自动，无开关）：读
ui-theme 的 active.colorScheme，所以「跟随系统」和自定义主题的浅/深都能正确识别。此前画布页只有一套深色调色板，浅色应用里会是一整块深色。
- 首屏不闪：宿主把当前浅/深写进 iframe 的
?theme=（进 src，只读一次，不会因主题变化触发 iframe 重载而丢滚动位置）；随后主题变化走 postMessage 实时下发，iframe onLoad 时再补发一次兜底。宿主没装主题服务时不猜，让画布页按 prefers-color-scheme 自己兜底。
- 两套调色板写全：
studio/app.css 的 :root（浅，默认）/ :root[data-theme="dark"] 变量名完全对等，低透明度底色一律用 color-mix() 从语义色派生（DSH 自身也是这个写法）。color-scheme 两套都声明，原生下拉/滚动条/复选框跟着变。
- 顶栏改为响应式三块布局：A 品牌 / B 工程参数（画幅·时长·音频·档位·节点数）/ C 按钮。宽栏一行 A B C（B 吃掉中间剩余空间，C 靠右）；窄栏竖直 A B C（各占一行）。断点 960px。此前参数那串不定长文本（节点多的工程能到 60+ 字）与按钮挤在同一行，窄栏（右侧面板 ~360px）会把按钮推到不可预期的位置。
- 画布品牌文案：
🎬 短剧画布 → 🎬 短视频画布（本页文档标题、iframe 无障碍名、右栏引导页胶囊、设置页提示一并同步）。标签页仍叫「画布」。
- 顺带修掉两处「只有浅色」的角落：iframe 内自绘的确认/入库模态框原先是写死的白色内联样式（深色主题下会跳出一块白板），改走调色板并收敛为
.svs-modal* 类；深色主题的 --border 由 #2e3342 微调到 #363c4d（原值压在 --panel-2 上只有 1.18:1，chip 的 1px 边框几乎看不见）。
- 验证：新增
scripts/smoke-canvas-theme.mjs（28 项，纯 Node：调色板对等 / 调色板之外零颜色字面量 / 每个 var() 都有定义 / 首屏时序 / WCAG 对比度 + 边框可分）与 scripts/preview-canvas.mjs（46 项，真浏览器：起 stub 服务喂一份覆盖每种节点类型/状态/分区的样例工程，两套主题各量一遍实际合成像素的对比度，宽栏 1100 + 窄栏 360 两档断言 A B C 的横/竖两种排法、按钮不越界、无横向滚动，并断言 postMessage 切换、非法取值不误改、无 ?theme= 时跟随系统偏好）。两者均已进 npm run smoke。
- 顺带修掉走查工具的一个洞：
scripts/lib/ui-probe.mjs 的 parseColor 不认识 color-mix() 在计算样式里的形态 color(srgb 0.05 0.42 0.28 / 0.12)（通道是 0–1 而非 0–255），会把半透明底静默算错——正是它让「chip 底色」这类元素此前的对比度检查形同空跑。
📝 待办
v1.4.0 — 画布可挂右侧栏（canvasHome）· 边看对话边生成（2026-09-18）
✨ 新增 / 改进
- 画布的家变成插件级配置项
canvasHome（设置页 ComfyUI → 界面）："tab"（默认，与「对话」并列的视图标签页）或 "sidebar"（右侧栏标签页）。挂右栏后对话与画布同屏，「跟随最新」自动滚动第一次真正可用（此前切到对话会卸载画布 iframe），并且能浮动成可拖拽缩放的面板——这是视图标签页给不了的能力。
- 互斥由结构保证：插件启动时只注册选中的那一个家，所以任何时刻只可能有一个 studio iframe 实例，不存在两个实例抢同一份工程的状态问题（原先设想的「挂载期互斥守卫」不需要了）。代价是改完需刷新页面（启动时读一次），设置页写明并给了「立即刷新」按钮。
- 入口照抄宿主原生做法（
ui-sidebar-files）：右栏折叠时从会话标题栏右上角的展开按钮进入，在引导页点「短视频画布」胶囊（guide[].order=5，排在「工作区文件」「新建终端」之前）。不自造输入框按钮等非原生控件。
- 一份实现、两个家：两个挂载点复用同一个
CanvasView，iframe 的 postMessage 桥（ask-ai → inputActions.setDraft）、工程数据、生成能力、Agent 工具全都与「家」无关。右侧栏服务走 ctx.inject 软注入，宿主禁用右侧栏插件时浏览器半照常加载。
- 新增离线冒烟
scripts/smoke-canvas-home.mjs（65 项，v1.5.0 起扩到 90 项）：断言两种配置下的席位注册互斥、胶囊定义、配置不可用时回落默认家、右侧栏缺席不抛异常，以及设置页下拉/提示/保存。它在实现期抓到一个真 bug：正文席位必须以实现 id 为 key（shell 用 entryKey: definition.id ?? tab.kind 派发），写成 kind 会静默派发不到、正文退化成「此标签页不可用」。
📝 文档 / 其它
v1.3.0 — 形状契约 · 链式续接落地（含 i2v）· skill 版本戳（2026-09-15）
✨ 新增 / 改进
- 视频形状
type 必填（r2v 参考绑定 / i2v 首末帧串联）：形状与参数冲突直接报错并给修法，此前是静默丢弃参数；comfy_generate_video / comfy_render / POST /generate/video 共用同一张真值表，校验在上传参考图之前完成（非法请求零副作用）。视频节点现在记 params.type，画布可辨识转场镜 / 锚点式重渲。
- 链式续接（
continuity_from）全面落地：同场景续接镜把上一镜的服务端 latent 逐帧钉进本镜、音频从接缝继续（实测接缝画面差 2.6–7.0，无续接对照 32–68；响度台阶稳定变好）。四档覆盖矩阵全绿，附录含测量口径与已知坑。
- i2v 也有链式实现（组「MiniMax H3 首末帧·链式续接」，4 份清单）：模板由
scripts/make-h3-ctx-templates.mjs 从普通 i2v 模板派生（可复现）。实测行为契约：链式 i2v 里 first_frame_node 会被丢弃（钉住的 head 已决定开头约 22 帧）、last_frame_node 保留 ⇒ 转场镜「续接上一场景尾镜 + 末帧锚定下一场景首镜」成为当前最优解，锚点式重渲也不再脱离续接链。fast 档已端到端实测（链路索引、22 帧 + 1.000s 音频上下文、裁剪与尾对齐补零、非链式反例拒跑全部通过）。
- 续接变成规划期的一等公民：
story-short-generator v2.3.0 的镜头表从六列扩到七列（新增「续接」列：起链 / 接 S0x / 锚定 S0x↔S0y），自检门扩到十项（续接链闭合性、续接可行性）；正片镜走 r2v + 续接，i2v 收敛为「转场镜 / 锚点式重渲」两处专用能力。
- 自带 skill 版本戳刷新：安装时复制到
~/.dsh/skills/ 的每个副本带 .dsh-studio-manifest（插件版本 + 内容 sha256）；内容没被你改过就随插件升级自动刷新，改过就只提示、不覆盖（DSH_SVS_SKILL_REFRESH=off|force 可关/强制）。
📝 文档 / 其它
v1.2.2 — 字幕写法单源 · I2V/Ref2V 选型文档（2026-09-14）
✨ 新增 / 改进
- 字幕与画面内文案的写法收归单一权威：
h3-prompt-writing 该节升级为「字幕与画面内文案（唯一权威版）」，四条定稿写法 + 失败写法 + 容量阈值 + 档位口径集中一处；story-short-generator / brand-promo-video-generator 只引用、不复述（原先各自带一份简化版，漏限定词会导致字幕整段不烧，属已实测缺陷）。画面内文案与字幕同源同法（标牌 / UI / 品牌文案同理）。
- 适用面扩到「声明支持字幕的实现」：H3 走结构化内嵌路径（Ref2VA 的
detailed_description、I2VA·FL2VA 的 integrated_multimodal_description），非 H3 走自由格式路径（英文引号逐字声明紧随对白 / 文案句，不用末尾中文指令）；两条路径的四条写法一致。
- 档位口径写清：字幕能力是实现级属性，判定权在逐镜自检门；没有「某档必须出字幕」的硬规则（默认
quality，同档换实现前先按取证入口验证）。
- 新增选型参考文档
docs/i2v-vs-ref2v-and-model-comparison.md：I2V 与 Ref2V 的机制差别、角色一致性 / 分辨率 / 时长 / 速度 / 音频与字幕 / 部署成本逐维对照（LTX-2.5 vs MiniMax H3）、按镜头类型的选型建议与未验证清单。该文不属于插件契约（插件侧只说能力、保持模型无关）。
📝 文档 / 其它
- 修正
docs/tier-strategy-design.md 中指向旧节名的两处失效引用（节名已改）。
- 公开文档不再出现测试机器的型号与显存数字（延续 v1.2.1 的口径）；技术前提（架构、无 FP8 路径、无 nvcc）全部保留。
- 本版为技能 + 文档版本：接口、档位契约与工作流清单零变化。
v1.2.1 — 文档（2026-09-14）
- 公开文档不再点名测试机器（README / skill / docs 一致），耗时数字保留但注明只作量级参考、随硬件与版本浮动；docs 里的实验报告改按架构描述（sm_80 单卡），技术前提（架构、无 FP8 路径、无 nvcc）全部保留。
- 这一版是纯文档版本：为了让 npm 页面渲染到清理后的 README 而发布。
v1.2.0 — 档位契约 · 策略模型 · PDD 8 步（2026-09-14）
✨ 新增 / 改进
- 受控三档
tier（fast / balanced / quality）：一个工作流 json = 一个档位实现（group = 家族），comfy_generate_image(tier=…) / comfy_generate_video(tier=…) / comfy_render(tier=…)。工具面不接受 workflow=（实现由配置解析）。请求不存在的档位显式报错并列出可用档位（不静默换档）；分辨率＝清单声明的长边 × 画布比例推导（只传一边宽高时另一边按比例补出来）。
- 视频清单从 2 份扩到 18 份：参考生成（ref2v）与首末帧生成（i2v）各有
fast / balanced / balanced-sol / quality / quality-sol，外加每条能力的抽帧与内部诊断清单——档位与加速实现可以按能力自由组合。
- 策略＝每能力一条内置默认 + 你自己命名并组合的策略：设置页「＋ 新增策略」起名 + 逐档挑实现（挑 ≥1 档即可，可跨清单组合），支持重命名 / 编辑档位 / 删除。策略声明它提供哪些档位：没挑的档位在设置页逐档区与工具条都不出现，显式请求会报错（不回退到别的实现），不指定档位时按该策略自身最靠前的档解析。
- PDD 8 步蒸馏（可选，需自装第三方节点包与权重）：
nfe=8 就拿到成片档以上的细节量——ref2v 184.7s、i2v 178.8s（同条件 20 步成片档 394.4s / 392.4s，帧锐度还高 +10.3% / +7.9%），叠加 Sol-Attn 后 137.3s / 134.1s。落地为四个普通清单，不做隐式默认（priority<0，缺节点时如实置灰）。
- 设置页能力×档位矩阵：逐档下拉按家族分组、带实测耗时与「缺哪个节点」标记，不可用实现置灰；策略单选 + 策略管理（新增/重命名/编辑档位/删除）。
- i2v 改用 FL2VA base（修正原先"用 Ref2VA base 跑 i2v"的跨变体错配），新增独立配置键
models.h3FlUnet / models.h3FlFastLora（env DSH_SVS_H3_MODEL_FL / DSH_SVS_H3_LORA_FL_FAST），旧键只作用于 ref2v。
⚠️ 升级须知
- 旧视频清单 id
minimax-h3-ref2v / minimax-h3-i2v 已拆成上表里的单档清单；配置中指向旧 id 的 preferred 不再决定视频档位（改由 tiers / 策略决定），但旧 asset id 仍按继承规则生效（assetOverrides 不必改）。
- i2v 换 base 需额外下载 FL2VA 权重（+21GB 左右）；不想多下可用配置钉回旧组合，见下方「版本兼容」。
- 视频默认档是
quality（20 步，最慢最贵），技能与手工调用建议显式传 tier=。
- 新的策略模型要重启插件（或导入/删除任意清单触发注册表重载）后才会出现在设置页。
📝 文档
发布新版本（维护者）
npm 包由 GitHub Actions 自动发布（推送 v* tag 触发，见 .github/workflows/npm-publish.yml；发布前自动跑冒烟自检并带 provenance 供应链签名），并在 npm 发版成功后自动为同一 tag 生成 GitHub Release——变更摘要取「上一个 tag → 本 tag」的提交，按 ✨ 新增/改进 · 🐛 修复 · 📝 文档/其它 自动归类，打开 Releases 页即可看到每版新增的功能。前提：仓库已配置 NPM_TOKEN secret（npmjs.com → Access Tokens → Automation 类型）与 GITHUB_TOKEN（Actions 内置，无需配置）。
npm version patch # bump 版本并打 vX.Y.Z tag（minor / major 同理）
git push origin main --follow-tags # 推送即触发自动发布（npm + GitHub Release）
发布后安装方式：dsh plugin --profile web add dsh-short-video-studio。
更多设计细节：架构 docs/ARCHITECTURE.md · 工作流契约 docs/workflow-contract.md · 链式续接（机制验证矩阵 / 档位覆盖矩阵 / i2v 实测 / 测量口径）docs/shot-chain-continuity.md · 形状与续接契约（type 必填、r2v↔i2v 参数表）docs/video-shape-contract.md · 声音一致性（参考音频机制 / 试镜流水线 / 路线图）docs/h3-voice-consistency-plan.md · docs/research/audition-voice-pipeline.md · docs/research/audio-capability-roadmap.md · 短剧系列化 docs/short-drama-series-integration-research.md · 渠道交付 docs/channel-delivery.md。
