@ninkch/dsh-infinite-canvas 0.18.6 → 0.19.0

package/README.md

@@ -25,28 +25,44 @@ The canvas and the agent share one brain. Every node is an AI workbench, and the
 
 The heavy lifting — bibles, episode scripts, storyboard breakdowns, batches of reference images — is exactly what the agent is fast at. You then fine-tune the 20% you care about directly on the nodes: tweak a prompt, reorder references, re-roll one shot, pull an older result from history.
 
-## Case study: Time-Postman (时空邮递员)
+## Case study: 门缝里的字条
 
-A full episode produced end to end with the flow above. The canvas at 32% — the script node, the expanded per-scene text + storyboard groups, the scene-1 video node with its bound references and preview, and the Assets panel:
+A full episode produced end to end with the flow above. The canvas with the whole episode laid out — the icon rail on the left adds nodes, the **Projects** panel on the right manages the canvases of the current project (第1集 / 第2集), while assets and the bible stay shared across the project:
 
-![Canvas overview — episode 1 pipeline (EN UI)](./docs/images/overview-en.png)
+![Canvas overview (EN UI)](./docs/images/overview-en.png)
 
-Scene 1 up close — text → storyboard → video wiring, with the storyboard's shot list and the video node's bound references:
+Shot 1 up close — storyboard → character/scene turnaround images → video, with the reference relationships drawn as edges:
 
-![Scene 1 pipeline (ZH UI)](./docs/images/scene1-zh.png)
+![Scene 1 storyboard and references (ZH UI)](./docs/images/scene1-zh.png)
 
-A scene video node: model picked from the provider's model list, duration/ratio/resolution on the node, four reference images bound in order:
+A node with its generation panel: click the content area to open it — references live in a draggable strip at the top, and model / ratio / quality / count sit on one row:
 
-![Video node with references](./docs/images/video-node-refs.png)
+![Node with generation panel](./docs/images/video-node-refs.png)
 
-Providers are configured once (URL + key + vendor-specific extra params) and can hold many models — one is starred as the default route:
+The bible modal — world view, style, character/scene/prop entries, each able to bind reference assets:
 
-![Provider detail](./docs/images/provider-detail.png)
+![Bible modal (ZH UI)](./docs/images/panel-bible-zh.png)
 
-The Settings panel — data root, Craft status (12/12 ready), skills, text model, and the image/video/TTS provider lists (EN / 中文 versions of the same UI):
+The assets modal — a card grid with search, category and project filters; videos use their first frame as the thumbnail (EN UI):
+
+![Assets modal (EN UI)](./docs/images/panel-assets-en.png)
+
+The project dropdown on the top-left project name: every row shows `project · canvas`, renames happen in place, and more than five projects paginate with a page-jump box (ZH UI):
+
+![Project dropdown (ZH UI)](./docs/images/panel-projects-zh.png)
+
+The Settings panel — data root, Craft status, Skill boost (General expert), text model and the image/video/TTS providers (EN UI):
 
 ![Settings (EN UI)](./docs/images/panel-settings-en.png)
 
+Shortcuts and gestures:
+
+![Shortcuts and gestures (EN UI)](./docs/images/shortcuts-en.png)
+
+Help & feedback:
+
+![Help & feedback (EN UI)](./docs/images/help-en.png)
+
 ## Work beside the chat
 
 The canvas is not a separate window you have to switch to. It opens as a **tab in the Harness right pane**, so you can talk to the agent on the left and storyboard on the right **at the same time** — ask for a change in chat and watch the nodes update in place.
@@ -59,6 +75,27 @@ The canvas is not a separate window you have to switch to. It opens as a **tab i
 
 > One live canvas at a time (shared node graph and generation state): opening it in the pane while the full-page panel is also open **moves** the canvas rather than duplicating it — the other side shows a "move the canvas here" button.
 
+## 3D Director Stage (previz)
+
+A blocking & previz workspace that lives inside the same project: place real glTF characters and set dressing, frame them with real cameras, and send the result back to the canvas as an image or video node.
+
+- **Three modes** — **Static previz** (studio look, paused), **Dynamic previz** (studio look + timeline playback), **Live render** (final look: daylight, shadows, materials, no guides).
+- **Asset library** — characters, trees, furniture, buildings, primitives, and ancient-street set pieces (pitched roofs, stalls, stone steps) in one searchable rail.
+- **Direct manipulation** — local-axis move/rotate/scale gizmo, box select, **Alt-drag a scale handle = uniform scale**, **W/A/S/D + Q/E fly navigation** (hold Shift for 4x speed).
+- **Shots & timeline** — shot rail with per-shot start/end, camera keyframes, ease curves, markers and loop playback.
+- **Camera & optics** — FOV, focal length, sensor size and roll stay consistent; shot-size presets show the live framing percentage.
+- **Export** — PNG still or MP4/WebM clip, dropped straight back onto the canvas as an image or video node.
+
+![Static previz — studio viewport, object properties and the shortcut list](./docs/images/director-static-en.png)
+
+![Dynamic previz — timeline, shot rail and camera keyframes](./docs/images/director-dynamic-en.png)
+
+![Live render — daylight, real shadows and sun controls](./docs/images/director-daylight-en.png)
+
+Assets are shared with the canvas: the characters, trees, furniture and buildings you already generated are directly usable as previz set dressing.
+
+Full walkthrough — asset tabs, gizmo, keyboard map, shots and export: **[User guide → 3D Director Stage](./docs/guide.en.md#8-3d-director-stage)**.
+
 ## How it works
 
 ```mermaid

package/README.zh-CN.md

@@ -25,28 +25,44 @@
 
 设定集、整集剧本、分镜拆解、成批参考图——这些批量工作正是 Agent 最快的部分。跑完后你只需要在画布上精修真正在意的那 20%：改提示词、调参考图顺序、重掷某一个镜头、从历史里回退旧结果。
 
-## 案例：时空邮递员
+## 案例：门缝里的字条
 
-用上面的流程完整制作的一集。整集铺开后的画布全览（32%）——左侧：剧本 → 各场文本 → 各场分镜表 → 场1视频（带预览与参考图）；右侧：资产面板：
+用上面的流程完整制作的一集。整集铺开后的画布全览——左侧一列图标添加节点，右侧「项目」面板管理当前项目的画布（第1集 / 第2集），资产与设定集在项目内共享：
 
 ![画布全览（中文界面）](./docs/images/overview-zh.png)
 
-场1 连线细节——场1文本 → 场1分镜表 → 场1视频，分镜表带镜头清单与逐镜台词标注：
+场1 的镜头组——场1分镜表 → 角色/场景多视图 → 场1视频，节点之间用连线表达参考关系：
 
-![场1 连线细节](./docs/images/pipeline-zh.png)
+![场1 分镜与参考图](./docs/images/scene1-zh.png)
 
-场景视频节点：模型来自供应商模型列表，时长/比例/分辨率在节点上可调，四张参考图按顺序绑定：
+节点 + 生成面板：点击节点内容区弹出面板，参考图在顶部缩略图条里可拖拽排序，模型/比例/清晰度/张数一行排开：
 
-![视频节点与参考图](./docs/images/video-node-refs.png)
+![节点与生成面板](./docs/images/video-node-refs.png)
 
-供应商配置一次（地址 + Key + 厂商专属扩展参数），下面可挂多个模型——点 ★ 星标作为默认路由：
+设定集弹窗——世界观、风格基调、角色/场景/道具条目，每条都可以绑定参考资产：
 
-![供应商详情](./docs/images/provider-detail.png)
+![设定集弹窗](./docs/images/panel-bible-zh.png)
 
-设置页签——数据根目录、Craft 状态（12/12 就绪）、技能增强、文本模型与图片/视频/TTS 供应商列表：
+资产弹窗——卡片网格，搜索/分类/项目筛选，视频以首帧作为缩略图：
+
+![资产弹窗](./docs/images/panel-assets-zh.png)
+
+左上角项目名点开是项目下拉：每行显示「项目名 · 画布名」，可直接就地改名，超过 5 个项目自动分页并可跳页：
+
+![项目下拉](./docs/images/panel-projects-zh.png)
+
+设置页签——数据根目录、Craft 状态、技能增强（通用专家）、文本模型与图片/视频/TTS 供应商：
 
 ![设置页签](./docs/images/panel-settings-zh.png)
 
+快捷键与操作：
+
+![快捷键与操作](./docs/images/shortcuts-zh.png)
+
+帮助与反馈：
+
+![帮助与反馈](./docs/images/help-zh.png)
+
 ## 在对话旁边工作
 
 画布不是必须切过去的另一个窗口——它可以作为 **Harness 右侧面板里的一个页签**打开，左边对话、右边分镜，**同时进行**：在对话里提要求，右边节点实时跟着变。
@@ -59,6 +75,27 @@
 
 > 同一时刻只有一个画布实例（共享节点图与生成状态）：在右栏打开时若全屏面板也开着，画布会**被移动到右栏**而不是复制一份——另一侧显示「把画布切换到这里」按钮。
 
+## 3D 导演台（预演）
+
+同一项目里内置的摆位与预演工作台：把真实 glTF 角色与场景陈设摆进场景，用真实机位取景，再把结果作为图片或视频节点导回画布。
+
+- **三种模式**：**静态预演**（影棚外观、暂停摆位）、**动态预演**（影棚外观 + 时间轴播放）、**实时渲染**（成片外观：日光、阴影、材质，无辅助线）。
+- **资产库**：人物、树木、家具、建筑、几何体，以及古街陈设（坡屋顶、摊位、石阶），一个搜索栏全覆盖。
+- **直接操作**：局部轴移动/旋转/缩放操作轴、框选、**Alt + 拖轴端方块 = 等比缩放**、**W/A/S/D + Q/E 键盘漫游**（按住 Shift 加速 4 倍）。
+- **分镜与时间轴**：分镜轨、单镜起止、机位关键帧、缓动曲线、标记、循环播放。
+- **机位与光学**：FOV、焦段、传感器尺寸、滚筒角联动一致；景别预设直接显示当前构图占比。
+- **导出**：PNG 截图或 MP4/WebM 预演视频，直接落成画布上的图片/视频节点。
+
+![静态预演——影棚视口、对象属性与快捷键列表](./docs/images/director-static-zh.png)
+
+![动态预演——时间轴、分镜轨与机位关键帧](./docs/images/director-dynamic-zh.png)
+
+![实时渲染——日光、真实阴影与太阳参数](./docs/images/director-live-render-zh.png)
+
+资产与画布共享：你已经生成的角色、树木、家具、建筑，可以直接拿来当预演场景的摆件。
+
+完整操作（资产页签、操作轴、快捷键表、分镜、导出）：**[操作手册 → 3D 导演台](./docs/guide.zh-CN.md#8-3d-导演台)**。
+
 ## 工作方式
 
 ```mermaid

package/assets/canvas-craft/SKILL.md

@@ -7,6 +7,7 @@ description: 短剧与短视频的创作方法论：剧本结构、分场格式
 
 本技能是**创作手法**规范；画布的操作流程（建项目、写节点、触发生成）见 `canvas-studio`。
 两者配合使用：先按本技能写出合格内容，再按操作规范落到画布上。
+本技能里的「硬规则 / 判定口径」**优先于任何专家人设的一句话概括**（人设只给方向，本技能给可核对的判据）。
 
 ## 一、短剧剧本方法论
 
@@ -17,6 +18,21 @@ description: 短剧与短视频的创作方法论：剧本结构、分场格式
 - **每场一个小目标**：人物想要什么 → 遇到什么阻碍 → 结果如何转折。写不出这条，这场就该删。
 - **结尾留钩子**：最后 3–5 秒抛出新信息或未解之谜（下集驱动力）。
 
+### 场景间因果钩子（连贯性硬规则，缺这条剧本就是流水账）
+
+**每场结尾必须留一个"推动下一场的具体东西"**：一个动作、一件物件、一句没说完的话、一个刚被揭开的动作结果。
+它是下一场的**起因**，不是本场的**总结**。
+
+- ✅ 正例：`【场2】他撕开信封，里面只有半张车票。他抓起外套冲出门。` → 场3 由「车票」和「冲出门」引发。
+- ❌ 反例：`【场2】他感到事情越来越复杂，心里很不安。` → 情绪总结，下一场无从接起。
+
+判定口径：
+
+- **该做**：结尾句必须是**可拍摄的动作或可见的物件状态**（手、门、屏幕、脸、道具）；下一场第 1 个动作/画面**直接由它引发**。
+- **不该做**：不写"他决定了""事情还没结束""危机正在靠近"这类总结；不用"第二天""与此同时"硬切到毫无因果的新场景。
+- **禁止并列场景清单**：每场必须**改变人物的处境或认知**（有变化才成立）；只是"又发生一件事"的场，删掉或合并。
+- **四要素每场各至少一处**：**目标**（这场要拿到/守住什么）→ **阻碍**（谁/什么挡住）→ **转折**（计划失效的瞬间）→ **代价**（他为此失去或付出什么）。四者缺一即视为该场不合格。
+
 ### 分场格式（固定八要素）
 ```
 【第 N 场】内/外景 · 地点 · 时间
@@ -102,8 +118,11 @@ B：……
 - **单镜头按时长谱系取值**（见下）；各镜时长之和 = 目标视频总时长，**按内容写足、不设硬上限**
   （如 15 秒 ≈ 4–7 镜，30 秒 ≈ 8–14 镜）。整个分镜表会组合成**一条多镜头提示词，由视频模型一次性生成整段视频**
   （镜头间由模型硬切，不需要逐镜生成再拼接）。
-- 一场通常拆 4–8 镜：建置镜（环境/全景）→ 主体镜（中近景）→ 情绪镜（特写）→ 动作镜（跟移/推拉）；
+- 一场通常拆 4–8 镜：建置镜（环境/全景）→ 主体镜（中近景）→ 情绪镜（特写）→ 动作镜（跟拍/推拉）；
   镜越短节奏越快，每镜的提示词要越聚焦。
+- **每场至少 1 个大特写（短场也不例外）**：用在关键信息或情绪爆点——眼睛、手、纸条上的字、钟表指针、
+  扣扳机的手指、屏幕上的名字。`visual` 里写清「大特写 + 拍的是哪个局部」，`duration` 给 0.8–2s；
+  一场没有大特写的分镜表 = 没有信息焦点，退回重拆。
 
 ### 节奏谱系（时长为情绪与节拍服务，**拒绝均匀分布**）
 | 镜头类型 | 时长 | 用途 |
@@ -139,23 +158,223 @@ B：……
 
 ### 术语表
 - **景别**：大远景 / 远景 / 全景 / 中景 / 中近景 / 近景 / 特写 / 大特写（极致特写：只拍眼睛、嘴、道具细节）。
-- **运镜**：固定 / 推 / 拉 / 摇 / 移 / 跟 / 升降 / 环绕；**一镜只用一种运镜**。
+- **运镜**：固定 / 推 / 拉 / 摇 / 移 / 跟 / 甩 / 升降 / 环绕 / 变焦；**一镜只用一种运镜**。
+- **调度**：人物走位 + 机位运动 + 镜头切换的**组合设计**（不是单个动词）；一场戏的调度要回答
+  "人往哪走、镜头在哪跟、下一刀切到哪"。
 - **高级运镜（按需选用）**：希区柯克变焦（推拉+变焦的眩晕感）、低角度仰拍（英雄感）、
-  快速摇镜（运动模糊）、FPV 第一人称主观（需要连续运动的环境才成立）、
+  快速摇镜/甩镜（运动模糊）、手持晃动（纪实不安感）、FPV 第一人称主观（需要连续运动的环境才成立）、
   航拍俯冲（要有明确落点，否则画面漂浮）、机械臂跟随（多角度贴视线）。
 
-### visual（首帧画面）公式
-> 景别 + 主体姿态 + 环境 + 光线 + 构图重心（+ 风格）
+### 术语勘误（生成与改写时一律按右列，不要沿用左列口语）
 
-示例：`中近景，陈拾右手举着信封站在雨里，老旧邮局门口，暖黄门灯打在信封上，主体位于画面右侧三分之一，写实电影感`
+| 常见误写 | 正确写法 | 说明 |
+|---|---|---|
+| 大豆、大特、特镜 | **大特写** | 只拍局部细节（眼睛、手、字迹、指针），不是"很大的特写" |
+| 调职、调道 | **调度** | 人物走位 + 机位运动 + 切换设计的组合 |
+| 推近 / 拉远 / 平移（单独使用） | **推镜 / 拉镜 / 移镜**，并写清起点与终点 | 单个动词是空模板，见「motion 公式」 |
+| 镜头、画面（当景别用） | **具体景别**（大特写/特写/近景/中景/全景/远景） | "镜头"不是景别 |
+| 跟移 / 移动镜头 / 跟拍（混用） | 统一为 **跟拍** | 与「移镜」区分：跟拍是镜头跟着主体走 |
+| 特写（当大特写用） | 信息/情绪爆点写 **大特写**，人物情绪写 **特写** | 两者能混用就等于没有景别设计 |
 
-### motion（运动/情绪）公式
-> 动作节拍 + 运镜方式 + 节奏
+### visual（首帧画面）六要素（缺一即不合格）
 
-示例：`他缓慢把信封贴上胸口，镜头缓慢推近，节奏由慢到停顿`
+> **景别 + 机位/角度 + 主体位置与朝向 + 前景/背景层次 + 光线方向与质感 + 关键道具位置**（+ 风格）
 
+| 要素 | 必须写到 | 判定口径 |
+|---|---|---|
+| 景别 | 大特写 / 特写 / 近景 / 中景 / 中近景 / 全景 / 远景 / 大远景 | **必须写具体景别**；只写"镜头""画面"＝不合格 |
+| 机位/角度 | 平视 / 俯拍 / 仰拍 / 过肩 / 越轴侧 / 贴地视角 | 说清摄影机在哪、朝哪 |
+| 主体位置与朝向 | 画面左/中/右三分区 + 脸部或身体朝向 | 写"画面右侧三分之一、3/4 侧脸朝左"这类可执行坐标 |
+| 前景/背景层次 | 前景挡什么 + 背景是什么 | 至少一层前景（肩膀/栏杆/雨丝）或明确的背景信息，禁止主体贴死空背景 |
+| 光线方向与质感 | 光源方向 + 硬/软 + 冷暖 | "暖黄门灯从右后方打来、硬光"；"阴天无方向冷光" |
+| 关键道具位置 | 道具在谁手里、画面哪个位置 | "信封在画面中心偏下、被指节压出折痕" |
+
+- **长度与要素的取舍**：常规镜约 60 字，关键镜（大特写/冲撞点）可到 90 字；**要素写不下就拆成两镜，
+  绝不删要素凑字数**。六要素是清单，不是句式——按"景别→主体→层次→光线→道具"顺序写最省字。
+- ✅ 正例：`大特写，俯拍，手指压在信封封口上，画面中心偏下；前景袖口边缘，背景虚化的雨夜门灯；暖黄硬光从右后方勾出手指轮廓；火漆印正在指纹下方。`
+- ❌ 反例：`镜头对着他，气氛很紧张。`——没有景别、没有机位、没有可拍的东西。
+- 示例（叙事镜）：`中近景，平视，陈拾右手举着信封站在雨里，画面右侧三分之一、身体朝左；前景是虚化的雨帘，背景老旧邮局门口；暖黄门灯从右后方打亮信封；主体穿着旧邮差制服。`
+
+### motion（动作/运镜）公式：起点 → 运动方式 → 终点
+
+> **起点 → 运动方式 → 终点**（+ 速度/节奏）
+
+示例：`起点：他站在雨里举着信封 → 缓慢把信封贴上胸口、低头 → 停在信封贴住心口、雨声变大`
+
+- **禁止只用"平移 / 推近 / 拉远"这类空模板**：它们没写清"从哪到哪、镜头为什么动、什么时候停"，
+  三镜连写"缓慢推近"全片就只剩一种运动。
+- **每镜至少一种非平移运动**（按情绪选，一镜只用一种）：
+  **跟拍**（跟着人物走）、**甩镜**（快速摇到新主体，带运动模糊）、**手持晃动**（不安/纪实感）、
+  **升降**（机位高度变化，俯仰关系跟着变）、**环绕**（绕主体走弧线）、**变焦**（焦距变化，机位不动）、
+  **镜头内主体运动带动**（人物逼近镜头/撞向镜头/从画外闯入）。
+- **同一场连续三镜不得使用同一种运动方式**：写成 跟拍 → 手持逼近 → 环绕 这样交替；
+  连续三镜同一运动 = 调度单调，退回改 `motion`。
+- **至少一种非平移运动**与「相邻镜禁止反向运镜」（见第四节 `cam` 字段）不冲突：
+  反向是方向问题，类型多样是选择问题——同向的甩镜/跟拍不算反向。
+- ✅ 正例：`起点：他坐在桌前 → 手持跟拍他起身冲出门、轻微晃动并加速 → 停在门框挡住画面的半秒。`
+- ❌ 反例：`镜头缓慢推近。`（全片每镜都这样写 = 单调平移，观众看不出情绪变化）
 - **一镜一个连续动作段落**；不要在一个镜头里写多个动作串联，也不要写跨镜切换（切镜由分镜表组织）。
 - **首帧与运动不重复**：visual 描述静止状态，motion 描述之后发生的变化。
+- **`motion` 由两部分组成**：**主体动作节拍**（`timeBeats` 三拍，见下节）+ **运镜**（起点 → 方式 → 终点，
+  见 `camera` 十二式）——只写运镜就是"只会平移"的根源。
+
+### timeBeats（每镜三个时间节拍，强制动作有层次）
+
+**硬规则：每镜必须把主体动作拆成 3 个时间节拍——`[0s] 起势 → [中段] 发力 → [结尾] 落点`。**
+
+两条写法都合法，**优先用结构化字段**（画布会把字段单独注入视频提示词，段落更清晰）：
+
+1. **结构化（首选）**：分镜 JSON 里给独立的 `timeBeats` 数组，每拍一条：
+   `"timeBeats":["0s 背对镜头、肩线绷住","1.2s 肩先转、眼后转、右手撑住桌面","2.4s 停在 3/4 侧脸、指节压白"]`
+2. **写进 `motion`（兼容旧格式）**：`[0s] … → [中段] … → [结尾] …；<运镜，起点 → 终点>`
+
+模型只演写出来的节拍；只写"缓缓转头"= 一个节拍 = 模型只会做最省力的平移。
+
+| 镜头类型 | [0s] 起势 | [中段] 发力 | [结尾] 落点 |
+|---|---|---|---|
+| 对话镜 | 低头看信、嘴半张 | 抬眼看向对方、把信按在桌上 | 指尖顶住桌面、话说完、视线不移 |
+| 冲撞镜 | 站在门口、肩线绷紧 | 一步跨进来、手掌推向桌面（椅子被撞开） | 手停在桌面、对方后退半步、纸散开 |
+| 情绪镜 | 背对镜头、肩膀起伏 | 肩先转、眼睛后转、右手撑住桌面 | 停在 3/4 侧脸、眼泪停在睫毛上、不眨眼 |
+
+- **该做**：三段都写**可见动作**（身体部位 + 方向 + 落点），三段之间姿势/位置**必须真的变化**，每段都能被拍到一帧。
+- **不该做**：三段写同一个动作的不同情绪（"他犹豫 → 更犹豫 → 非常犹豫"）= 0 个节拍；也不要写心理（"他下定决心"）。
+- **动作量下限**：`duration ≥ 2s` 的镜头，timeBeats **不得少于 3 条**；`≤1s` 的快切镜允许 1 条（多写演不完）。
+- ✅ 正例：`"timeBeats":["0s 背对镜头、肩线绷住","1.2s 肩先转、眼后转、右手撑住桌面","2.4s 停在 3/4 侧脸、指节压白"]` + `motion: "手持微晃左移跟拍，起于他右后方、止于他正面偏左"`
+- ❌ 反例：`他缓缓转头`——一个节拍，模型只会给一个平移/微动。
+- **判定**：能数出 3 个带时间锚点（`[0s]` / `[中段]` / `[结尾]`，或"起初/随即/最后"）的可见动作阶段，
+  且结尾状态与 `tail` 写的接点一致。
+
+### camera（机位 / 镜头 / 运动三件套，禁止只写"推拉摇移"）
+
+三件套分工：**机位与镜头写进 `visual`，运动写进 `motion`**。只写"推近"等于没说清用什么镜头、从哪推到哪。
+
+**① 景别 × 焦段**（`visual` 里写"近景，85mm"）
+
+| 景别 | 常用焦段 | 典型用法 | 情绪效果 |
+|---|---|---|---|
+| 大远景 / 远景 | 超广角 14–24mm | 环境交代、人物渺小 | 孤独、压迫、史诗感 |
+| 全景 | 广角 24–35mm | 关系建立、动作调度 | 客观、疏离、空间清楚 |
+| 中景 | 标准 50mm | 对话、信息交换 | 自然、旁观、贴近人眼 |
+| 中近景 / 近景 | 中长焦 85mm | 情绪、反应镜头 | 亲近、聚焦、背景柔化 |
+| 特写 / 大特写 | 长焦 135–200mm | 细节揭示、情绪爆点 | 压缩、紧张、窒息 |
+
+**② 光圈 × 景深**（`visual` 里写"f/2.8 浅景深"）
+
+| 光圈 | 景深观感 | 适用 |
+|---|---|---|
+| f/1.4 | 极浅，背景糊成色块 | 梦幻人像、夜戏孤光、情绪特写 |
+| f/2.8 | 浅，主体与背景分离 | 叙事主力、对话镜 |
+| f/4 | 中等，人与背景都可辨 | 群像、双人对峙 |
+| f/8 | 深，环境全清晰 | 建立镜头、动作全景、纪实 |
+
+判定：**情绪镜 / 冲撞镜必须写焦段与光圈**（大特写 135–200mm + f/1.4–2.8；远景 14–24mm + f/8）；
+其余镜头可省略。全场统一 f/1.4 = 背景全糊、看不出在哪，不合格。
+
+**③ 运镜十二式**（写进 `motion` 的"运动方式"段，必须带起点 → 终点）
+
+| 运镜 | 一句触发条件 |
+|---|---|
+| 推近 | 要压向情绪或让人看清细节时（从中景推到近景，不是一直推） |
+| 后拉 | 要揭示处境、让观众从人物身上抽离时 |
+| 左摇 | 要顺着视线往左带出新信息时 |
+| 右摇 | 要带出主体右侧的人或空间关系时 |
+| 仰摇 | 要从低往高拍、制造压迫或崇高感时 |
+| 俯摇 | 要从高往低拍、揭示布局或让主体显弱时 |
+| 左移跟拍 | 人物横向走位大（超过画面 1/4）时，镜头同速横跟 |
+| 前移穿入 | 要穿过前景进入场景、形成沉浸感时 |
+| 升起俯视 | 要收尾揭示环境规模、或人物被环境吞没时 |
+| 左环绕 | 对峙/宣言要转出轮廓与空间层次时 |
+| 甩镜 | 冲撞/转场要硬切到新主体时（带运动模糊，切完必须稳住） |
+| 焦点转移 | 注意力要从人转到道具、或从道具转回人时（机位不动，只变焦平面） |
+
+其余可用：右移跟拍 / 右环绕 / 下降贴近 / 后退撤离 / 变焦推进 / 定镜凝视——同法写"起点→终点"，不要只写名字。
+
+- **归并大类（「连续三镜不同运动」自检时按大类比）**：推（推近 / 前移穿入）、拉（后拉）、
+  摇（左摇 / 右摇 / 仰摇 / 俯摇）、跟（左移 / 右移跟拍）、升降（升起 / 下降）、环绕、甩、变焦（变焦推进 / 焦点转移）、手持。
+
+**④ 单镜容量上限（超了就拆镜，这是稳定性的来源）**
+
+| 项目 | 上限 | 怎么判（可机械核对） |
+|---|---|---|
+| 主运镜 | **1 个** | `motion` 里能数出两个不同运动动词（推+摇 / 移+环绕）= 超限 |
+| 主动作链 | **1 条**（起势→发力→落点） | 出现两个互不相干的目标动作（"转身" + "端起杯子"）= 超限 |
+| 主要角色 | **2 名** | `characters` 数组 > 2，且都要在画面里演戏 = 超限 |
+| timeBeats | **3 条** | `duration ≥ 2s` 的镜头不足 3 条 = 不合格（见上节） |
+
+超限一律**拆镜**（换景别 / 换机位接），不要在一镜里堆——堆了模型只执行前半段，下一镜必然对不上。
+
+### vfx（特效与物理细节，不写就没有）
+
+视频模型**不会自己加特效**：不写就是空白。`vfx` 没有独立字段——粒子/光效/物理/环境写进 `visual`，
+镜头类（晃动 / 呼吸 / 拖影）写进 `motion`。
+
+| 类别 | 写法示例 | 适用 |
+|---|---|---|
+| 粒子 | 雨丝斜打（细密、有方向）、尘粒在光柱里浮动、雪片近大远小、火星随呼吸明灭 | 氛围 / 苦情 / 古装 |
+| 光效 | 逆光镜头光斑、路灯钠黄溢光、闪电瞬时照亮半张脸、手电光柱切过烟雾 | 夜戏 / 悬疑 |
+| 物理 | 衣角被风掀起、水面涟漪一圈圈扩散、纸张翻飞、湿发贴在颊边 | 写实 / 生活 |
+| 镜头 | 轻微手持晃动、镜头呼吸感（缓慢起伏）、运动模糊拖影 | 纪实 / 动作 |
+| 环境 | 烟雾贴地弥漫、蒸汽升腾、水汽在玻璃上凝结 | 冷峻 / 工业 |
+
+- **硬规则：每场至少 3 镜写 vfx**；纯对话文戏可降到 1 镜，**但不得为 0**。
+- **判定**：每镜 `visual`（或 `motion`）里能找到一个**具名物理/光效细节**（名词 + 方向或强度），
+  例如"雨丝从右后斜打""钠黄溢光反在指纹上"；数得出"每场 ≥3 镜"即合格。
+- vfx 必须**带方向或强度**；不写方向的粒子在成片里就是噪点。
+- ✅ 正例：`…；前景雨丝从右后斜打过画面，路灯钠黄溢光在指纹上反出一道亮边。`
+- ❌ 反例：`画面很唯美`——空话，模型不知道画什么。
+
+### negative（负向要求清单：在分镜阶段规避，不是生成后再后悔）
+
+画布自动组装的视频提示词**没有负向槽位**——所以 negative 的主用法是**写分镜时逐条转成"正向确定写法"**；
+只有在手写提示词覆盖（含 `subject_definitions` 的完整结构）或厂商原生支持负向参数时，
+才把清单作为"负向：…"追加到末尾。
+
+**通用必备（每场逐条检）**
+
+| 负向项 | 正向规避写法（写进 `visual` / `motion`） | 怎么判 |
+|---|---|---|
+| 换脸 | 写死"与 @角色@ 一致，脸型/眼型不变" | 能搜到"一致/不变" |
+| 五官漂移 | 逐镜复述不变的眉形、鼻梁、下颌线 | 相邻镜外观词逐字相同 |
+| 服装变化 | 逐镜复述服装关键件（"旧邮差制服、左胸口袋"） | 服装词全场同一套 |
+| 手部畸形 | 写清手部姿态与遮挡（"右手五指并拢按在桌面"） | 有动作的镜都写了手 |
+| 多指 | 明确手指数与动作（"双手十指交握"） | 手部特写必写 |
+| 穿模 | 写清前后遮挡关系（"手在桌面之上、不入桌面"） | 有接触动作就写 |
+| 闪烁 | 固定光源方向与强度（"门灯始终从右后方打来"） | 光线描述跨镜一致 |
+| 风格突变 | 每镜沿用同一句风格词 | 风格词全片统一 |
+| 动作僵硬 | timeBeats 三段姿势真有变化 | `duration ≥ 2s` 的镜头 ≥3 拍 |
+| 人物凭空出现/消失 | 首镜写站位、末镜用 `tail` 写清位置与退场方向 | 每镜有位置关系 |
+| 口型与台词不同步 | 有台词必写"开口说话、口型清晰可见"（近景/中近景、脸可见） | 有 `dialogue` 的镜必查 |
+
+**按题材追加（勾选后同样要找到对应规避写法）**
+
+| 题材 | 追加负向项 |
+|---|---|
+| 古装 | 现代物件（手表 / 拉链 / 塑料 / 电线 / 汽车） |
+| 室内 | 窗外光线突变（白天拍成夜晚、阴晴乱跳） |
+| 多人 | 身份互换（服装、配饰串到别人身上） |
+
+- **判定**：每场通用 11 项逐条能在分镜里找到规避写法；题材项按标签勾选，勾了就必须有对应写法。
+
+### 冲撞感：怎么用镜头写出"撞"（每场至少一个冲撞点）
+
+**每场至少一个冲撞点**：人物之间（对峙、逼问、撕扯、抢夺），或人物与环境/物件之间
+（撞门、摔碎、被雨砸、被车灯扫过、被推上墙）。写不出冲撞点的场 = 这场没戏，回去加冲突，
+**不要靠运镜硬撑**。
+
+四种手段，同一个冲撞点至少叠两种：
+
+| 手段 | 怎么写进分镜 | 判定标准 |
+|---|---|---|
+| 短镜头堆叠 | 冲撞点前后连用 1–1.5s 短镜（爆发瞬间可到 0.3–0.8s），每镜只留一个动作 | 冲撞段落里出现 ≥2 个 ≤1.5s 的镜头 |
+| 反向构图 | 不越轴的前提下让相邻两镜构图重心相反（正反打、俯仰互换、主体左右占位互换） | 相邻两镜构图重心方向相反，且轴线关系仍成立 |
+| 突然的机位跳切 | 用 `seg: closeup` 插一个大特写或俯拍，刻意打断轴线一瞬——**切完立刻切回原轴线** | 冲撞点处出现一次景别或角度的突变 |
+| 声音突入 | `sfx` 写一个**盖过环境声的短促声音**：撞门、玻璃碎裂、掌掴、急刹、椅腿刮地、呼吸骤停 | 冲撞点那镜的 `sfx` 是"突入型"声音，不是环境底噪 |
+
+- **visual 写"接触瞬间"**：不写"两人起冲突"，写"他的肩撞上她的肩，她的包被撞飞，画面右倾、前景手臂横挡"。
+- **motion 写"速度突变"**：`起点：静止对峙 → 突然加速逼近（手持晃动）→ 在相距半臂处急停`。
+- **sfx 写"声音证据"**：`椅腿刮地、闷响、急促呼吸`；非冲撞镜只给环境声（雨声/空调声/远处车流）。
+- ✅ 正例：冲撞点 = 0.6s 大特写（攥紧的拳头）+ 1.2s 反向过肩（她被推上墙）+ `sfx: 后脑撞墙的闷响`。
+- ❌ 反例：全场 motion 都是"缓慢推近"、sfx 全是"雨声"——观众感受不到任何冲击。
 
 ### 连续性（最容易被忽略，必须检查）
 - **180° 轴线**：对话双方在相邻镜头保持同一侧。
@@ -163,6 +382,21 @@ B：……
 - **相邻镜头的方向与姿态要衔接**（180° 轴线、出入画方向一致）；多镜头一次性生成时
   把衔接关系写进相邻镜头的提示词，模型会在同一条视频里保持连贯。
 
+### 分镜自检（生成分镜后逐条判定，任一不过 → 重拆/重写，不带病生成视频）
+
+| # | 检查项 | 判定标准（可机械核对） | 不过怎么办 |
+|---|---|---|---|
+| 1 | 每场有冲突点？ | 每场能指出"谁 vs 谁/物"的具体冲撞点，且该处叠了 ≥2 种冲击手段（短镜/反向构图/跳切/声音突入） | 回剧本加冲突，不是靠运镜补救 |
+| 2 | 每场有 1 个大特写？ | 每场 `shots` 里至少一镜 `visual` 以「大特写」开头且写明拍的是哪个局部 | 在关键信息/情绪爆点处补一镜（0.8–2s） |
+| 3 | 有三镜同运动？ | 任意连续 3 镜的 `motion` 运动类型（跟/甩/手持/升降/环绕/变焦/主体带动）不全相同 | 改中间那镜的运动类型，或拆镜 |
+| 4 | 景别是否具体？ | 每镜 `visual` 首句含具体景别；全文搜不到"镜头对着""画面里"这类无景别开头 | 逐镜补景别，缺机位/光线的按六要素补齐 |
+| 5 | 场间有因果钩子？ | 每场结尾句是动作/物件（不是总结），且下一场第 1 镜由它引发 | 重写该场结尾，或调整下一场开场 |
+| 6 | 六要素齐全？ | 每镜 `visual` 六要素逐项能找到（景别/机位角度/主体位置朝向/前景背景/光线方向质感/道具位置） | 缺项补写；字数超了就拆镜 |
+
+> 前 5 条来自用户实测反馈（剧本不连贯、镜头太粗、运镜单调、缺冲击），是**硬闸门**；
+> 第 6 条是质量线。自检结果不需要输出给用户，但**不合格就不许触发视频生成**（视频花钱，分镜重生成不花钱）。
+
+
 ## 三、图片提示词规范
 
 公式：**主体 + 景别/构图 + 环境 + 光线 + 风格质感 (+ 画幅)**
@@ -171,6 +405,9 @@ B：……
   （年龄、发型、服装、配饰），只在景别与动作上变化。
 - **参考图绑定**：把角色/场景/道具资产连到图片节点的 ref 端口，顺序即 `[图N]`，
   提示词里用 `[图1] 角色：陈拾（旧邮差制服，帆布邮包）` 这样的绑定说明。
+- **图片/视频是合并节点（有图就是资产，空节点点开面板生成）**：画布不再区分「生成节点」与
+  「资产节点」——同一个 `image` / `video` 节点，有结果（`assetId`）就是资产，没有结果时点开节点
+  的生成面板填写提示词后生成；参考图仍靠连线（资产 → ref）与 `@实体@` 引用挂载。
 - **要避免**：一个画面里多个主体动作、文字/水印、风格混搭（写实 + 卡通）、
   极端广角导致人物变形。
 - 风格统一：整部片用**同一套风格词**（如"写实电影感，暖色调，浅景深"）。
@@ -179,7 +416,7 @@ B：……
 
 ### 多镜头视频：系统自动用「参考生成」结构化格式（不要手写机械拼装）
 
-分镜表驱动的视频生成（视频节点连了分镜表）**由画布自动组装结构化提示词**，格式对齐 MiniMax H3 /
+分镜表驱动的视频节点（`video` 节点连了分镜表）**由画布自动组装结构化提示词**，格式对齐 MiniMax H3 /
 优云智算优化后的协议——**机械拼装（风格 + [图N] 绑定 + 镜头列表 + 设定集全文）会让模型把台词、
 场景、人物判错**（实测：台词被当画外音、场景串镜）。自动生成的六段结构：
 
@@ -207,6 +444,29 @@ non_diegetic_music:    仅当显式给出（节点扩展参数 {"music":"…"}
   3. 参考图已连到视频节点（无参考图时自动回退普通提示词）。
 - **手写覆盖**：节点提示词里若含 `subject_definitions`，画布原样发送，不做二次加工（高级用法）。
 
+### 字段落点：写了没用，是因为没落到对的字段上
+
+分镜镜头落库时保留这些键：`title` / `visual` / `motion` / `timeBeats` / `camera` / `vfx` / `negative` /
+`tail` / `cam` / `start` / `seg` / `characters` / `scene` / `props` / `duration` / `dialogue` / `sfx`。
+**结构化字段（`timeBeats` / `camera` / `vfx` / `negative`）会被画布单独提取**，逐镜拼进视频提示词的
+「动作节拍 / 机位·焦段·运镜 / 物理特效」三段；没写就是空，模型不会自己补。落点对照：
+
+| 内容块 | 落在哪个字段 | 组装后变成 |
+|---|---|---|
+| timeBeats（3 拍：起势→发力→落点） | `timeBeats` 数组（首选）或 `motion` 前半段 | `动作节拍（按时间推进，不可省略任何一拍）：… → … → …` |
+| camera 三件套 | `camera`（首选），或拆进 `visual`（景别+焦段+光圈）+ `motion`（运镜） | `机位/焦段/运镜：…` |
+| vfx | `vfx`（首选），或写进 `visual` / `motion` | `物理特效（必须可见）：…` |
+| negative | `negative`（逗号分隔短语） | 合并进逐镜末尾的「禁止：…」清单 |
+| 台词与音色 | `dialogue` + 设定集「声音：…」 | `台词：<Subject N>（S1）用…说：<d>…</d>` |
+| 音效 / 环境声 | `sfx` | `音效：…`（并合并进 `overall_soundscape`） |
+
+> 结论：**只写 `visual` 不写 `motion` = 没有运动；`timeBeats` 不写 3 拍 = 只有平移；`vfx` 不写 = 没有特效。**
+>
+> 补充一条**切段**口径：铺开时画布会按真实镜头边界把这张分镜表切成若干段生成（默认单段上限 15s，
+> 面板上可调；MiniMax 这类弱衔接模型建议 6–10s）。切点只落在 `scene_change` / `closeup` /
+> `new_character` 三种镜头上，所以**同一个人同一段连续动作不要拆成多个 continuation 镜**——
+> 宁可给这一镜更长的 `duration`；真要换机位，就让下一镜成为三种切点之一（哪怕插一镜大特写）。
+
 ### 分镜衔接：分段生成能不能接上，全看这四件事
 
 短剧一集必然切成多段生成（模型单次有时长上限），而**每段是独立采样的——模型看不到上一段最后发生了什么**。
@@ -279,9 +539,20 @@ non_diegetic_music:    仅当显式给出（节点扩展参数 {"music":"…"}
 
 ## 六、交付前自检清单
 
-- [ ] 剧本：开场 10 秒有钩子；结尾有悬念；对白口语化；每场有目标/阻碍/转折
+- [ ] 剧本：开场 10 秒有钩子；结尾有悬念；对白口语化；**每场目标/阻碍/转折/代价四要素各至少一处**；
+      **每场结尾是动作或物件的因果钩子（不是总结句），且下一场由它引发**
 - [ ] 一致性：人名/地名/道具与设定集逐字一致；角色外观描述未漂移
-- [ ] 分镜：镜头数 × 时长 ≈ 目标时长；每镜一个动作；相邻镜头轴线与光线连续
+- [ ] 分镜：镜头数 × 时长 ≈ 目标时长；每镜一个动作；相邻镜头轴线与光线连续；
+      **每镜 `visual` 六要素齐全且景别具体**；**每场至少 1 个大特写**
+- [ ] **冲撞**：每场至少一个冲撞点，且叠了 ≥2 种冲击手段（短镜头堆叠 / 反向构图 / 机位跳切 / 声音突入）
+- [ ] **调度**：`motion` 写成"起点→运动方式→终点"，含非平移运动；**同一场连续三镜不含同一种运动方式**
+- [ ] **timeBeats**：每镜有 3 拍（`[0s]` 起势 → `[中段]` 发力 → `[结尾]` 落点），写进 `timeBeats` 数组或 `motion`；
+      `duration ≥ 2s` 的镜头**一律不少于 3 条**，`≤1s` 的快切镜允许 1 条
+- [ ] **camera 容量**：每镜只有 **1 个主运镜 + 1 条主动作链**（多一个就拆镜），运镜写全「起点 → 方式 → 终点」
+- [ ] **vfx / negative**：每场 **≥3 镜**写了具名特效或物理细节（纯对话文戏可 1 镜、不得为 0）；
+      negative 通用项 + 题材项写进 `negative` 字段（或转成正向规避写法）
+- [ ] **切段友好**：同一角色的同一段连续动作没有被拆成多个 continuation 镜；
+      换机位时下一镜是 `scene_change` / `closeup` / `new_character` 之一（切点干净，剪辑时是硬切不是硬接）
 - [ ] **节奏**：同一场里至少一次明显的时长对比（快切/长镜）；景别随情绪推进而不是随机
 - [ ] 提示词：图片含景别/光线/构图；视频单动作单运镜；风格词全片统一；**每条视频提示词都有音频指令**
 - [ ] 资产：命名含项目 + 集数 + 场次（便于检索与后期对轨）

package/assets/canvas-layout/SKILL.md

@@ -13,8 +13,11 @@ description: 画布节点布局纪律：一类型一列、竖向排列、绝不
 
 1. **一类型一列**：同类型节点永远排在**同一竖列**里、从上往下顺次排列。
    列的固定顺序（从左到右）：
-   **剧本 → 场景文本 → 分镜表 → 资产图（角色/场景/道具）→ 视频 → 成片**。
+   **剧本 → 场景文本 → 分镜表 → 图片节点（角色/场景/道具参考图）→ 视频节点 → 成片**。
    绝不把同类型节点横向散开，也绝不与其他类型混列。
+   > **图片/视频是合并节点**：不再区分「生成」与「资产」两种节点——**有图/有视频就是资产，
+   > 空节点在画布上点开生成面板填写提示词后生成**。所以「图片节点」这一列同时承载
+   > 已生成的参考图与待生成的空节点；新建节点一律用 `image` / `video` 类型（旧名自动映射）。
 2. **连线不改列**：连线只表达数据流（剧本→分镜、分镜→视频、资产→参考图）。
    分镜表不会因为连了"某场文本"就移动到那一列旁边——它永远待在「分镜表」列里。
 3. **绝不重叠**：任意两个节点框不得相交，最小间距 24px。
@@ -39,8 +42,8 @@ description: 画布节点布局纪律：一类型一列、竖向排列、绝不
 1) 剧本节点          （1 个，列 1）
 2) 场景文本 × N      按场次顺序建（列 2，竖向 = 场1…场N）
 3) 分镜表 × N        按场次顺序建（列 3；用 connectFrom 连到对应场景文本，但列归属不变）
-4) 资产图 × M        角色 → 场景 → 道具 顺序建（列 4）
-5) 视频节点 × N      按场次顺序建（列 5）
+4) 图片节点 × M       角色 → 场景 → 道具 顺序建（列 4；有图=资产，空节点点开面板生成）
+5) 视频节点 × N      按场次顺序建（列 5；生成与结果同一个节点）
 6) 成片节点          （列 6，通常 1 个）
 ```