@ninkch/dsh-infinite-canvas 0.17.10 → 0.17.12

package/README.md

@@ -2,7 +2,7 @@
 
 **A node-based short-drama studio inside DeepSeek Harness.** Start from a one-line idea, walk out with a storyboarded, voiced, subtitled video cut — right on an infinite canvas.
 
-English | [简体中文](./README.zh-CN.md)
+English | [简体中文](./README.zh-CN.md) · **User guide: [English](./docs/guide.en.md)** · [操作手册（中文）](./docs/guide.zh-CN.md)
 
 <!-- Badges: add CI / npm / license badges here after publishing -->
 
@@ -12,23 +12,57 @@ Infinite Canvas is a [DeepSeek Harness](https://github.com/deepseek-ai) plugin t
 
 Everything runs locally in your Harness. Bring your own generation APIs, or use the built-in demo mode to learn the whole flow with zero configuration.
 
+## Drive it from the chat
+
+The canvas and the agent share one brain. Every node is an AI workbench, and the **chat side is the director**: ask in plain language and the agent operates the canvas tools for you — batch work especially.
+
+> *"Create a project called Time-Postman, write the world view and series bible first."*
+> *"Write episode 1 based on the bible."* → the script node generates one episode (60–120s), every scene marked with a `【场N】` header.
+> *"Expand episode 1 into scenes."* → per-scene text nodes + storyboard nodes appear, wired automatically.
+> *"Generate reference images for every character, scene and prop."* → ten image nodes created and generated in one go.
+> *"Generate scene 1's video."* → storyboard shots + reference images compose one multi-shot video call.
+> *"Send episode 1 to FilmCraft for an MP4 render."* → FCP7 XML + SRT land in your data root for the Craft suite.
+
+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 (时空邮递员)
+
+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:
+
+![Canvas overview — episode 1 pipeline (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:
+
+![Scene 1 pipeline (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:
+
+![Video node with references](./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:
+
+![Provider detail](./docs/images/provider-detail.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):
+
+![Settings (EN UI)](./docs/images/panel-settings-en.png)
+
 ## How it works
 
 ```mermaid
 flowchart LR
-    A[Script node<br>AI screenplay] --> B[Storyboard node<br>AI shot list]
-    B --> C[Expand to canvas]
-    C --> D[Multi-shot video gen<br>all shots in ONE prompt]
-    D --> E[Final cut<br>transitions · subtitles · voices]
-    E --> F[Export<br>WebM preview / FilmCraft MP4]
-    A --> G[Reference image gen<br>characters · scenes · props]
-    G --> D
+    A[Script node<br>ONE episode · scene headers] --> B[Expand to scenes<br>text + storyboard per scene]
+    B --> C[Multi-shot video per scene<br>shots + refs in ONE call]
+    C --> D[Tail-frame chaining<br>scene N last frame → N+1 first frame]
+    A --> E[Reference image gen<br>characters · scenes · props]
+    E --> C
+    D --> F[Final cut / FilmCraft<br>transitions · subtitles · voices]
 ```
 
 ## Highlights
 
 ### Consistent characters, scene after scene
-A per-project **series bible** (style baseline + character/scene/prop cards) is injected into every AI call, so wardrobes, locations and props stay coherent across shots and episodes. After each storyboard run, a local consistency check flags any name that isn't registered yet.
+A per-project **series bible** (style baseline + character/scene/prop cards) is injected into every AI call, so wardrobes, locations and props stay coherent across shots and episodes. Entities referenced with `@name` in a prompt automatically carry their bible description and reference assets. After each storyboard run, a consistency check flags any name that isn't registered yet, and the agent fills the gaps.
 
 ### References that actually bind
 Reference images connect as an ordered, visible list — `[图1] 角色：Lin Ning`, `[图2] 场景：The Old House` — and that exact order is what reaches the model. Multi-character frames stay unambiguous, and Volcano Engine **Seedance**'s native `[图N]` convention is supported end to end (first frame, up to 4 reference images, official task API).
@@ -40,28 +74,32 @@ Reference images connect as an ordered, visible list — `[图1] 角色：Lin Ni
 Pan, zoom, marquee select, alignment guides, groups that fold, a minimap, 60-step undo/redo, per-node media history (last 8 results), mask-based inpainting, and middle-click everything — the canvas part should feel like an editor, not a chat sidebar.
 
 ### Bring your own models
-Text models come from Harness itself (no extra keys, no per-plugin parameters). Image, video and TTS backends are **multi-config** — define as many endpoints as you want, mark a default, and pick per node. Every gateway call is relayed through the local Harness host process, so **any vendor works** (no CORS headaches). No backend configured? Demo mode synthesizes placeholder images and animated videos locally so the entire pipeline is testable offline.
+Text models come from Harness itself (no extra keys, no per-plugin parameters). Image and video backends use a **provider + model** structure: configure a provider once (URL, key, optional vendor-specific **extra params** as JSON) and list as many model IDs under it as you like; star one as the **default route** for nodes that don't pick one. Video endpoints are auto-adapted — OpenAI-style task APIs, Seedance-native `content[]` gateways and Sora-style `/v1/videos` are covered by an automatic fallback chain, resolutions/ratios/first-frames/references are mapped to each vendor's conventions, and oversized references are downscaled before sending. Every gateway call is relayed through the local Harness host process, so **any vendor works** (no CORS headaches). No backend configured? Demo mode synthesizes placeholder images and animated videos locally so the entire pipeline is testable offline.
 
 ### A portable data root
-Set a **data root folder** once and everything lands there, organized by **project name**: nodes and the series bible in `project.json`, the asset index in `assets.json`, media under `image/ video/ audio/ text/`, and Craft post-production under `craft/`. Move to a new machine by copying the folder and clicking **Import from data root**.
+Set a **data root folder** once and everything lands there, organized by **project name**: nodes and the series bible in `project.json`, the asset index in `assets.json`, media under `image/ video/ audio/ text/`, and Craft post-production under `craft/`. **Moving to a new machine = copying the folder**: point the new install's data root at it and every project (assets, bible, media) is recognized — plus a one-click **Import from data root** for anything not yet on disk. Put the folder inside a cloud-sync directory and multiple machines stay in sync automatically.
 
 ## Quick start
 
 1. Install the plugin (bundle folder) and restart Harness once.
-2. Click the **Infinite Canvas** button in the left sidebar.
-3. Add a **Script** node, type a logline, hit *AI write script*.
-4. Connect it to a **Storyboard** node → *AI break into shots* → *Expand to canvas*.
-5. Drop character images onto the placeholder asset nodes, hit *Run workflow*, then open a **Final Cut** node and export.
+2. Click the **Infinite Canvas** button in the left sidebar, and set a **data root** in Settings.
+3. In the chat: *"Create a project called <your idea>, write the world view and series bible first."*
+4. *"Write episode 1."* → script node generates one episode with `【场N】` scene headers → click **Expand to scenes** (or ask the agent) to get text + storyboard nodes per scene.
+5. *"Generate reference images for all characters, scenes and props."* → named, bible-consistent asset images in one batch.
+6. *"Generate scene 1's video."* → storyboard shots + references compose one multi-shot video call; chain scenes via tail-frame → first-frame.
+7. Open a **Final Cut** node for the preview cut, or export to FilmCraft for a true MP4.
 
 > Without any generation API configured, every step runs in demo mode — the full pipeline works offline.
 
+The full walkthrough (with screenshots, model configuration and data-root migration) lives in the [Chinese user guide](./docs/guide.zh-CN.md).
+
 ## Generation backends
 
 | Kind | Protocol | Notes |
 |---|---|---|
-| Text | Harness LLM service | Script & storyboard writers; pick any configured model, or override per node |
-| Image | OpenAI-compatible `/images/generations`, multi-reference via `/images/edits` | Size (1K/2K/4K) × ratio; mask inpainting via `edits` + PNG mask |
-| Video | Generic submit+poll, or **Volcano Seedance official tasks** | duration up to 15 s, 480P/720P/1080P, ratio, first frame, up to 4 reference images |
+| Text | Harness LLM service | Episode scripts & storyboard writers; pick any configured model, or override per node |
+| Image | OpenAI-compatible `/images/generations`, multi-reference via `/images/edits` | Provider + model list with starred default; size (1K/2K/4K) × ratio; extra params as JSON; mask inpainting via `edits` + PNG mask |
+| Video | OpenAI-style task APIs, Seedance-native `content[]`, Sora-style `/v1/videos` — automatic fallback chain | Episodes per scene (≤15s), 480P/720P/1080P, ratio, first frame, multi-reference (auto-downscaled), voice references via `audios[]` |
 | TTS | OpenAI-compatible `/audio/speech` | Per-shot voices mixed into the final cut |
 
 All gateway calls are relayed by the local Harness host process (no browser CORS limits) — any vendor endpoint with an OpenAI-style shape works.

package/README.zh-CN.md

@@ -2,92 +2,135 @@
 
 **DeepSeek Harness 内的节点式短剧工作室。** 从一句话创意出发，在无限画布上完成剧本、分镜、角色资产、画面生成、视频生成，直到带转场、字幕、配音的成片。
 
-[English](./README.md) | 简体中文
+[English](./README.md) | 简体中文 · **操作手册：[中文版](./docs/guide.zh-CN.md)** · [English guide](./docs/guide.en.md)
 
 <!-- 徽标位：发布后在顶部添加 CI / npm / license 徽标 -->
 
 ## 这是什么？
 
-无限画布是一个 [DeepSeek Harness](https://github.com/deepseek-ai) 插件：它在 Web 界面左侧栏加入一个完整的创作工作室。你不需要在对话里反复描述需求，而是像导演一样工作——无限画布上的节点连成流水线：剧本、分镜、角色与场景资产、图片生成、视频生成，最终在成片节点完成转场、字幕与配音。
+无限画布是一个 [DeepSeek Harness](https://github.com/deepseek-ai) 插件：它在 Web 界面侧边栏加入一个完整的创作工作室。你像导演一样工作——无限画布上的节点连成流水线：剧本、分镜、角色与场景资产、图片生成、视频生成，最终在成片节点完成转场、字幕与配音。
 
 全部本地运行于你的 Harness。生成后端自带或自配均可；未配置任何 API 时有内置演示模式，整条流水线离线可学可测。
 
+## 用对话驱动画布
+
+画布与对话共享同一个"大脑"。每个节点都是一个 AI 工位，而**对话侧就是导演**：用自然语言下指令，Agent 替你操作画布工具——批量工作尤其如此。
+
+> 「创建一个叫《时空邮递员》的项目，先写世界观和设定集。」
+> 「根据设定集写第一集。」→ 剧本节点生成一整集（60–120 秒），每个场景带【场N】分场标记。
+> 「把第一集铺开到场景。」→ 每场一个文本节点 + 分镜表节点自动出现并连线。
+> 「把所有角色、场景、道具的参考图都生成了。」→ 十个图片节点一次建好、逐个生成。
+> 「生成场1的视频。」→ 分镜镜头 + 参考图合成一次多镜头视频调用。
+> 「把第一集交给 FilmCraft 渲染 MP4。」→ FCP7 XML + SRT 落盘，Craft 套件接手。
+
+设定集、整集剧本、分镜拆解、成批参考图——这些批量工作正是 Agent 最快的部分。跑完后你只需要在画布上精修真正在意的那 20%：改提示词、调参考图顺序、重掷某一个镜头、从历史里回退旧结果。
+
+## 案例：时空邮递员
+
+用上面的流程完整制作的一集。整集铺开后的画布全览（32%）——左侧：剧本 → 各场文本 → 各场分镜表 → 场1视频（带预览与参考图）；右侧：资产面板：
+
+![画布全览（中文界面）](./docs/images/overview-zh.png)
+
+场1 连线细节——场1文本 → 场1分镜表 → 场1视频，分镜表带镜头清单与逐镜台词标注：
+
+![场1 连线细节](./docs/images/pipeline-zh.png)
+
+场景视频节点：模型来自供应商模型列表，时长/比例/分辨率在节点上可调，四张参考图按顺序绑定：
+
+![视频节点与参考图](./docs/images/video-node-refs.png)
+
+供应商配置一次（地址 + Key + 厂商专属扩展参数），下面可挂多个模型——点 ★ 星标作为默认路由：
+
+![供应商详情](./docs/images/provider-detail.png)
+
+设置页签——数据根目录、Craft 状态（12/12 就绪）、技能增强、文本模型与图片/视频/TTS 供应商列表：
+
+![设置页签](./docs/images/panel-settings-zh.png)
+
 ## 工作方式
 
 ```mermaid
 flowchart LR
-    A[剧本节点<br>AI 编剧] --> B[分镜表节点<br>AI 拆分镜]
-    B --> C[铺开到画布<br>1 镜 = 1 组节点]
-    C --> D[图片生成<br>多参考图]
-    D --> E[视频生成<br>首帧 + 参考图]
-    E --> F[成片<br>转场 · 字幕 · 配音]
-    F --> G[导出<br>WebM 预览 / FilmCraft MP4]
+    A[剧本节点<br>一集 · 场景标记] --> B[铺开到场景<br>每场 文本+分镜表]
+    B --> C[每场多镜头视频<br>镜头+参考图一次生成]
+    C --> D[尾帧串联<br>场N尾帧 → 场N+1首帧]
+    A --> E[参考图生成<br>角色 · 场景 · 道具]
+    E --> C
+    D --> F[成片 / FilmCraft<br>转场 · 字幕 · 配音]
 ```
 
 ## 核心亮点
 
 ### 角色一致，跨镜跨集
-项目级**设定集**（风格基调 + 角色/场景/道具卡）会注入每一次 AI 调用，服装、场景、道具在镜头之间、剧集之间保持一致。每次生成分镜后，本地一致性检查会标出尚未登记的名称。
+项目级**设定集**（风格基调 + 角色/场景/道具卡）注入每一次 AI 调用，服装、场景、道具跨镜跨集保持一致。提示词里的 `@名称` 自动携带该实体的设定描述与参考资产。每次分镜生成后一致性检查会标出未登记实体，Agent 自动补全。
+
+### 参考图真正绑定
+参考图以有序、可见的列表连线（`[图1] 角色：陈拾`、`[图2] 场景：褶皱巷`），这个顺序就是到达模型的顺序。多角色画面不再含糊；Volcano **Seedance** 的原生 `[图N]` 约定端到端支持（首帧、最多 4 张参考图、官方任务 API）。
 
-### 参考图真正"绑定"
-参考图以**有序、可见**的列表接入——`[图1] 角色：林宁`、`[图2] 场景：老屋`——这个顺序就是发给模型的顺序。多角色画面不再混淆；火山引擎 **Seedance** 的原生 `[图N]` 约定全链路支持（首帧、最多 4 张参考图、官方任务 API）。
+### 从分镜到可看成片
+**一个分镜表 = 一次多镜头视频生成。** 全部镜头（顺序 + 每镜时长）合成一条提示词，视频模型一次调用渲染整段——硬切由模型完成，没有逐镜拼接的接缝。每场 ≤ 15 秒，多场之间用**尾帧 → 首帧**串联。**成片节点**按顺序拼接片段——交叉溶解或黑场转场、烧录字幕、原声与 TTS 配音混音——即时导出预览版；接 [ArtCraft](#artcraft-桥接)（FilmCraft）则写出 **FCP7 XML 时间线 + SRT** 渲染真正的 MP4。
 
-### 从分镜到能看的成片
-**成片节点**按顺序拼接分镜视频——叠化/黑场转场、字幕烧录、原声与 TTS 配音混音——即时导出预览版。要做真正的后期，一键把 **FCP7 XML 时间线 + SRT** 写到磁盘，交给 [ArtCraft](#artcraft-桥接)（FilmCraft）渲染成 MP4。
+### 编辑器级画布
+平移缩放、框选、对齐参考线、可折叠分组、小地图、60 步撤销重做、节点媒体历史（最近 8 次）、蒙版局部重绘、全要素中键——画布应该像剪辑软件，不像聊天侧栏。
 
-### 剪辑器级画布
-平移缩放、框选、对齐参考线、可折叠分组、小地图、60 步撤销重做、节点媒体历史（最近 8 次）、蒙版局部重绘——画布的手感应该是剪辑软件，而不是聊天侧栏。
+### 模型自带或自配
+文本模型直接来自 Harness（无额外 Key）。图片/视频后端采用**供应商 + 模型**两级结构：供应商配一次（地址、Key、可选的厂商专属**扩展参数 JSON**），下面挂任意多个模型 ID，点 ★ 星标作为默认路由。视频端点自动适配——OpenAI 风格任务接口、Seedance 原生 `content[]`、Sora 风格 `/v1/videos` 由自动降级链覆盖，分辨率/比例/首帧/参考图按厂商惯例映射，超大参考图发送前自动压缩。所有网关调用经本地 Harness 宿主进程转发（无浏览器 CORS 限制）。什么都没配？演示模式本地合成占位图与动画视频，整条流水线离线可测。
 
-### 模型自带
-文本模型直接用 Harness 配置（无需额外 Key）。图片、视频、TTS 后端支持**多配置**——配任意多个接口、设默认、节点上按需选择。什么都没配？演示模式在本地合成占位图与动画视频，整条流水线离线可跑。
+### 便携数据根目录
+设置一次**数据根目录**，所有数据按**项目名**落盘：节点与设定集在 `project.json`，资产索引在 `assets.json`，媒体在 `image/ video/ audio/ text/`，Craft 后期产物在 `craft/`。**换电脑 = 复制文件夹**：新机器把数据根目录指过去，所有项目（资产、设定集、媒体）自动识别——另有**「从数据根导入」**一键合并。把目录放进网盘同步文件夹，多台机器自动保持一致。
 
 ## 快速开始
 
-1. 安装插件（bundle 目录），重启一次 Harness。
-2. 点左侧栏的 **无限画布** 按钮。
-3. 加一个 **剧本** 节点，输入一句话创意，点 *AI 生成剧本*。
-4. 连到 **分镜表** 节点 → *AI 生成分镜* → *铺开到画布*。
-5. 给占位资产节点上传角色图，点 *运行工作流*，再打开 **成片** 节点导出。
+1. 安装插件（bundle 目录）并重启一次 Harness。
+2. 点侧边栏 **Infinite Canvas**，在设置里配好**数据根目录**。
+3. 对话：*「创建一个项目叫〈你的创意〉，先写世界观和设定集。」*
+4. *「写第一集。」* → 剧本节点生成带【场N】标记的一集 → 点**铺开到场景**（或让 Agent 做），得到每场的文本+分镜表组合。
+5. *「把所有角色、场景、道具的参考图生成了。」* → 一批命名规范、与设定集一致的资产图。
+6. *「生成场1的视频。」* → 分镜镜头 + 参考图合成一次多镜头调用；场与场之间尾帧串联。
+7. 打开**成片节点**导出预览版，或交给 FilmCraft 渲染正式 MP4。
 
-> 未配置任何生成 API 时，每一步都走演示模式——整条流水线离线可用。
+> 未配置任何生成 API 时，全部步骤以演示模式运行——整条流水线离线可用。
+
+完整的图文教程（含截图、模型配置与数据目录迁移）见[中文操作手册](./docs/guide.zh-CN.md)。
 
 ## 生成后端
 
 | 类型 | 协议 | 说明 |
 |---|---|---|
-| 文本 | Harness LLM 服务 | 剧本与分镜写手；可选任意已配置模型，节点上可覆盖 |
-| 图片 | OpenAI 兼容 `/images/generations`，多参考走 `/images/edits` | 清晰度（1K/2K/4K）× 比例；蒙版重绘走 `edits` + PNG 蒙版 |
-| 视频 | 通用提交+轮询，或 **火山 Seedance 官方任务** | 时长 4–10s、480P/720P/1080P、比例、首帧、最多 4 张参考图 |
-| TTS | OpenAI 兼容 `/audio/speech` | 逐段配音，混入成片 |
+| 文本 | Harness LLM 服务 | 整集剧本与分镜拆解；可选任意已配置模型，或按节点覆盖 |
+| 图片 | OpenAI 兼容 `/images/generations`，多参考走 `/images/edits` | 供应商+模型列表（星标默认）；尺寸（1K/2K/4K）× 比例；扩展参数 JSON；`edits`+PNG 蒙版局部重绘 |
+| 视频 | OpenAI 风格任务接口、Seedance 原生 `content[]`、Sora 风格 `/v1/videos`——自动降级链 | 每场一集（≤15s）、480P/720P/1080P、比例、首帧、多参考图（自动压缩）、`audios[]` 声音参考 |
+| TTS | OpenAI 兼容 `/audio/speech` | 每镜配音混入成片 |
+
+所有网关调用由本地 Harness 宿主进程转发（无浏览器 CORS 限制）——任何 OpenAI 风格的厂商端点都可用。
 
 ## ArtCraft 桥接
 
-安装配套的 [`dsh-artcraft`](../dsh-artcraft/README.md) 插件后，画布通过同源 HTTP 调用本地 **PhotoCraft / FilmCraft / EffectCraft** 工具链：资产同步到按项目隔离的数据目录，图片走 PhotoCraft 无头调色（单张或批量），成片导出 FCP7 XML + SRT 交给 FilmCraft 渲染 MP4。状态灯、优雅降级与完整契约见 [`docs/artcraft-handoff.md`](./docs/artcraft-handoff.md)。
+安装姊妹插件 [`dsh-artcraft`](../dsh-artcraft/README.md) 后，画布可与本地 **Craft 家族**（PhotoCraft、FilmCraft、EffectCraft、LightCraft、VectorCraft、DesignCraft 等 12 个）经同源 HTTP 协作。把 ArtCraft 的数据根目录指向与画布相同的位置，全部后期产物落在 `projects/<项目>/craft/`：资产按项目同步、图片支持 PhotoCraft 无头调色（单个/批量）、成片导出 FCP7 XML + SRT 交 FilmCraft 渲染 MP4。设置面板的状态卡为每个 Craft 显示一盏状态灯与 n/n 就绪摘要。
 
 ## 发布（维护者）
 
-测试三层漏斗、beta 标签、打包校验与完整发布手册见 [`docs/release.md`](docs/release.md)。
+维护者手册（红线、分支模型、版本规则）见 [`RELEASING.md`](RELEASING.md)；操作细节见 [`docs/release.md`](docs/release.md)；已发布变更见 [`CHANGELOG.md`](CHANGELOG.md)——**GitHub Release 正文一律英文**，从 changelog 复制。
 
-发布走 **npm Trusted Publishing**（OIDC）——不依赖任何 npm 令牌：
+发布走 **npm Trusted Publishing**（OIDC）——任何地方都不存在 npm 令牌：
 
-- **Release 流程**：GitHub 仓库创建 Release（tag `v0.17.0`…）→ Actions 自动发布该版本。
-- **手动流程**：仓库 → Actions → *publish* → Run workflow → 输入版本号。
-- `publish.yml` 从 release tag（或手动输入）解析版本号，发布时带 `provenance` 徽标。
+- **发布流程**：dev 测试通过并获批准 → 合并进 `main` → 创建 GitHub Release（tag `v0.17.11`，…）→ Actions 自动发布该版本。
+- `publish.yml` 工作流内置守卫：release 提交必须在 `main` 上、tag 必须与 `package.json` 一致，然后带 `provenance` 徽章发布。
 
 ## 数据与隐私
 
-- 画布文档、项目、设置与设定集存于浏览器 `localStorage`（`dsh-ic:*`）；资产存于 IndexedDB（`dsh-infinite-canvas`）——**或在设置中配置数据根目录后落盘**（按项目分目录存放，由插件后台以 HTTP Range 方式服务，支持视频拖动进度条）。
-- AI 文本经 Harness 宿主进程调用（使用你已配置的模型，无需额外 Key）。
-- 图片/视频/TTS 请求由浏览器直连你配置的地址——请注意 CORS 与密钥保管。
+- 画布文档、项目与设置存于浏览器 `localStorage`（`dsh-ic:*`）；资产元数据存于 IndexedDB（`dsh-infinite-canvas`）；设置数据根目录后媒体文件**落盘**（按项目名分目录，插件后端带 HTTP Range 支持视频拖动）。
+- AI 文本生成经 Harness 宿主进程（用你已配置的模型，无额外 Key）。
+- 图片/视频/TTS 网关调用由本地 Harness 宿主进程转发（规避浏览器 CORS）；你的端点与 Key 都留在本地。
 - 插件自身不向任何第三方上传数据。
 
 ## 环境与限制
 
-- DeepSeek Harness 0.2.0-rc.2+；演示视频导出依赖 MediaRecorder（Chromium）。
-- 预览成片为实时录制的 WebM；要多轨精修的 MP4 母版，请配合 ArtCraft FilmCraft 或任意非线性编辑软件。
+- DeepSeek Harness 0.2.0-rc.2+；演示模式成片导出需要 MediaRecorder（Chromium）。
+- 预览成片为实时录制 WebM；多轨剪辑的 MP4 母版请配合 ArtCraft FilmCraft 或任意 NLE。
 - 图片 `edits`/蒙版重绘需要模型支持该端点（如 gpt-image-1）。
-- 插件 Host 半侧更新需重启一次 Harness；网页半侧热更新。
+- 宿主侧插件更新需重启一次 Harness；Web 半区热加载。
 
-## 许可
+## 许可证
 
 Apache-2.0

package/assets/canvas-studio/SKILL.md

@@ -40,32 +40,98 @@ description: 用无限画布（Infinite Canvas）做短剧/视频创作时使用
    只要 `warnings` 非空：**逐条** `canvas_update_bible` 补全（名称与告警**逐字一致**、描述写实可生成），
    再生成参考图；**绝不忽略、绝不跳过、绝不只补一部分**。设定集更新后告警会自动重算
    （几秒内随文档同步刷新），以最新一次 `canvas_node_status` 为准。
-9. **汇报固定要素**：项目名 + 项目 id + 节点名/id + 成稿摘要（若已生成）；有错误如实说明。
+9. **分镜容量铁律：一个分镜节点 = 一个 10–15s 的完整场景视频，是剧本的一小部分。**
+   - 一个分镜节点只吃**一个场景**的剧本：各镜 2–5s、时长之和 **≤ 15s（上限）**；
+   - **长剧本必须按场景拆分**为多个场景剧本节点（命名「第X节-场Y剧本」…），
+     每个场景剧本作为**各自分镜表**的源端——**绝不把长剧本整根连线给一个分镜表**；
+   - 全集剧本（若有）只作总纲存档，**不作为分镜源端**；
+   - 体量感：一个 10–15s 场景 ≈ 剧本 60–150 字（含该场全部对白）；分镜表 `shots` 上限 24 镜，
+     超长剧本会被截断且触发生成告警（warnings 会出现"剧本较长…请按场景拆分"）；
+   - **镜头数量不固定**：分镜表镜头数默认「自动（按内容节拍）」——一个连续动作段落 = 一镜，
+     3–10 镜都正常，绝不凑数、绝不用固定数量；全部镜头时长之和 ≤ 15s（超限客户端会自动压缩最长镜）；
+   - 拆分操作：全集剧本已生成后，按场景把对应片段 `canvas_write_node(target:'output')`
+     写入各场景剧本节点（这是**分配已有内容**，不是代写）。
+10. **汇报固定要素**：项目名 + 项目 id + 节点名/id + 成稿摘要（若已生成）；有错误如实说明。
+11. **生成节点前置检查单（创建任何 image-gen / video-gen 前逐条确认，任一不过 = 停止创建）**：
+    ① **镜头清单来源**：这一段的镜头序列已经从分镜表节点的 `shots` 读到了吗？（`canvas_node_status`）
+       没读到 → 停止创建，先读分镜表节点；仍读不到 → **问用户要分镜内容**。绝不自己按剧本推导/编造镜头表。
+    ② **视频节点数量 = 1**：一个分镜表对应一个完整视频（多镜头一次生成）。
+       准备为不同镜头建第 2 个视频节点 → 立即停止，走错路了。
+    ③ **先建 1 个、验证、再继续**：批量预建生成节点会放大错误——先建第 1 个，
+       用 `canvas_node_status` 验证连线与产物正确，再继续下一个。
+12. **读不到就问**：必需的项目状态（分镜内容/镜头清单/设定集条目）读不到时，那是**应当向用户确认的缺口**，
+    不是可以自行绕过的障碍——绝不把"编一份"当作替代方案。
+13. **分镜连贯靠连线，绝不靠名字/序号推断。** 分镜表节点**顶部**有「衔接上一镜」输入口（`prev`）、
+    **底部**有「尾镜」输出口（`tail`）。需要与上一场连贯时：
+    `canvas_connect({ projectId, fromNode: 上一分镜表id, toNode: 本分镜表id, fromPort: 'tail', toPort: 'prev' })`。
+    连上后，本场分镜**生成时**会自动把上一场尾镜的「画面 / 最后一个动作 / 台词 / 音效」作为**硬性承接约束**
+    写进提示词：第 1 镜必须从上一镜的**最后一个动作**继续、画面重叠 **≤ 0.2 秒**、**背景声连续**、
+    不得重新建立场景或跳回远景交代。**禁止**用节点名（"场1/场2"）、节点位置或剧本序号去猜衔接关系——
+    名字会改，只有连线是可靠依据。修复已有项目时：先补连 `tail → prev`，再重新生成对应分镜表。
+14. **音话同步（口型）是硬要求。** 分镜里带 `dialogue` 的镜头，必须让说话角色**在画面内开口说话**：
+    近景/中近景、脸部朝向可见（正面或 3/4 侧脸），**禁止**背对镜头、脸部被遮挡、人物出画；
+    `visual` 或 `motion` 里要写明「开口说话、口型清晰可见」。
+    台词**绝不能**处理成画外音/旁白——成片里人嘴闭着、声音飘在背景，就是这个错误。
+    视频提示词会自动带上该约束（画面内开口、口型与台词同步）；发现分镜把有台词的镜头写成背影/空镜，
+    必须重新生成该分镜。
 
 ## 二、标准工作流（对话填提示词+连线+触发，生成由节点完成）
 
 0. **读/补设定集**：`canvas_get_bible` → 缺什么用 `canvas_update_bible` 补。
    创作意图、世界观、风格 → 写进设定集的 worldview/style 字段。
 1. `canvas_list_projects` —— 查重 + 拿到 projectId 与节点 id
-2. **剧本节点**：只写提示词，让节点自己生成剧本——
-   - 新项目：`canvas_create_project({ name, scriptText: 本节创作提示词, nodeName: '第X节剧本' })`
+2. **剧本节点（一集 = 成片 60–120 秒，按【场N】分场）**：只写提示词，让节点自己生成剧本——
+   - 新项目：`canvas_create_project({ name, scriptText: 本集创作提示词, nodeName: '第X节剧本' })`
    - 已有项目：`canvas_write_node({ projectId, text: 提示词, target: 'idea', name: '第X节剧本' })`
    - 触发生成：`canvas_run_node({ projectId, nodeId })` → `canvas_node_status` 轮询直到 done/error
+   - 生成契约（自动注入，无需复述）：整集 **4–10 场、每场 10–15 秒成片**；**每场以「【场N】场景名（地点·时间）」单独一行开头**
+     ——这是"铺开到场景"自动拆分的解析标记，格式不可变；对白逐行「角色：台词」；结尾附人物/场景/道具清单；
    - **【铁律】不要把成稿直接填进 output**——生成是节点的工作（用户在画布上看得到过程与结果）。
      仅当用户明确说"你直接把剧本写出来、不用节点生成"时，才允许 `target:'output'` 直接写成稿。
-3. **分镜表节点**：**用连线从剧本节点取内容，绝不复制剧本全文**——
-   - `canvas_create_node({ projectId, type: 'storyboard', name: '第X节分镜表', connectFrom: 剧本节点id })`
-     （connectFrom 创建即连线；不要传 prompt——内容来自连线的上游剧本节点）
-   - 触发：`canvas_run_node({ projectId, nodeId })` → 轮询（画布基于连线的剧本拆解镜头）
-   - **【多镜头铁律】一个分镜表 = 一次视频生成**：分镜是"一次多镜头生成"的镜头脚本
-     （每镜 2-5 秒、各镜时长之和 = 目标视频总时长），不是"一镜一视频"。
-     现代视频模型支持多镜头模式：全部镜头按顺序+时长写进一条提示词，一次性生成整段视频，
-     镜头间由模型硬切。**绝不要为一个镜头单独建视频生成节点再拼接**。
-4. **视频生成节点**：多镜头提示词来自上游分镜表（连线取，不要复制）——
-   - `canvas_create_node({ projectId, type: 'video-gen', name: '第X节多镜头视频', connectFrom: 分镜表节点id, duration: 各镜时长之和 })`
-     （不传 connectFrom 且项目里已有分镜表时会自动连线；prompt 留空）
+3. **铺开到场景（每场 = 场景文本节点 + 分镜表节点，连线一次生成场景分镜）**：
+   - 画布：剧本节点的**「铺开到场景」按钮**一键完成（按【场N】自动分段）；
+   - Agent 等价操作：`canvas_node_status` 读成稿 → 按【场N】分段 → **逐场**：
+     `canvas_create_node({ type: 'text', name: '第X节-场Y文本' })` +
+     `canvas_write_node({ projectId, nodeId: 文本节点id, target: 'output', text: 该场原文 })` +
+     `canvas_create_node({ projectId, type: 'storyboard', name: '第X节-场Y分镜表', connectFrom: 该场文本节点id })`；
+   - **【铁律】每个分镜表的源端 = 对应场景文本（连线取）**；整集剧本节点**绝不**直接连分镜表（体量超限，见硬约束 9）。
+   - **连贯连线（要连贯就必须连，见硬约束 13）**：把**上一场分镜表的 `tail` 输出口**连到**本场分镜表的 `prev` 输入口**：
+     `canvas_connect({ projectId, fromNode: 上一场分镜表id, toNode: 本场分镜表id, fromPort: 'tail', toPort: 'prev' })`。
+     逐场依次串联（场1→场2→场3…），**连好之后再生成该场分镜**——连上后生成的分镜第 1 镜会承接上一场尾镜
+     （从上一镜最后一个动作续、重叠 ≤0.2s、背景声连续）。已有分镜是"旧约束"产物时，补连后
+     **重新 `canvas_run_node` 该分镜表**即可修正（重生成分镜不花钱，只有视频花钱）。
+4. **逐场生成视频（多镜头一次生成）**：
+   - `canvas_run_node({ 分镜表 })` → `canvas_node_status` 读 `shots`（镜头清单以此为准，绝不编造镜头表）；
+   - `canvas_create_node({ projectId, type: 'video-gen', name: '第X节-场Y视频', connectFrom: 分镜表节点id, duration: 各镜时长之和 })`
+     （不传 connectFrom 且项目里有已拆解镜头的分镜表时会自动连线；prompt 留空）；
+   - **【禁止逐镜建节点】**一段 10–15 秒的视频**不需要逐镜的图片节点或"镜头图→镜头视频"链路**：
+     多镜头一致性靠角色/场景/道具**参考图资产**（@引用自动挂载）保证，视频模型在一次调用里完成全部镜头。
+     最多为**开场首帧或 1–2 个关键镜头**补定帧图（接同一视频节点的 frame/ref 端口）。
+     一旦发现自己在批量创建"第X节-场Y-镜Z"这类镜头图片/视频节点 = 走错路，**立即停止**并回到本条。
    - 参考图：把角色/场景/道具参考图资产连到视频生成节点的 `ref` 端口（`canvas_connect`）；
      提示词里的 `@引用` 命中的资产也会自动挂上
+    - **【跨段连贯：分镜承接 + 尾帧 → 首帧】**连贯分两层，先文本后画面：
+      **①分镜承接（文本层，先做）**：上一分镜表 `tail` → 本分镜表 `prev`（见硬约束 13 / 工作流第 3 步），
+      让分镜第 1 镜从上一场尾镜的最后一个动作继续、重叠 ≤0.2s、背景声连续；
+      **②画面承接（视频层，后做）**：每个视频节点生成完成后会**自动提取尾帧**并挂到 `last` 输出端口。
+      多场视频按顺序串联：上一视频节点的 `last` 端口 → 下一视频节点的 `frame` 端口
+      （`canvas_connect({ projectId, fromNode: 上一段, toNode: 下一段, fromPort: 'last', toPort: 'frame' })`）。
+      第一段的 `frame` 用开场定帧图（若生成了首帧关键图）或留空。
+      **【衔接模式】**下一段视频节点若有 frame 连线，节点上有「衔接」下拉三选一：
+      **参考图融合**（默认：尾帧降级为第 1 张参考图，保留实体参考图，衔接为软约束）、
+      **硬首帧（弃参考图）**（用真首帧参数，画面绝对承接——网关禁止首帧与参考图混用）、
+      **忽略首帧**。需要画面严格承接选「硬首帧」，新实体参考图占主导选「参考图融合」。
+      **按顺序触发**：上一段 `canvas_node_status` 为 done 后再连线、再触发下一段
+      （连线可以提前建好——frame 在下一段真正运行时才解析）。
+   - **【声音一致（可选）】**视频接口配置里的「生成同步音频」勾选后才发送 `generate_audio:true`——
+     模型生成**自带音轨**的视频（对白/环境声与画面同步）；不勾 = 无声视频（声音另行 TTS 配音）。
+     要让同一角色**跨视频保持音色**：用视频/成片节点的「提取声音参考」按钮——
+     **输入角色名即可**：系统自动按分镜 `dialogue` 台词标注定位该角色的全部时间窗，
+     逐窗取音轨**拼接为一个声音参考文件**（`角色-<名> 声音`，自动绑定实体），
+     之后该角色的视频提示词里 `@<名称>` 会自动把这条声音参考放进 `audios[]`，
+     模型生成的对白将向参考音色对齐（携带声音参考时会自动强制开启同步音频）。
+     时间窗归属靠分镜的 `dialogue` 标注（对白逐字来自剧本、按镜头分配，一镜尽量单说话人）；
+     分镜缺少台词标注时按钮会降级为手动模式并提示重新生成分镜。
    - 触发：`canvas_run_node` → 轮询；整段视频一次生成完成
 5. **生成角色/场景/道具参考图**：为设定集里的每个条目
    `canvas_create_node({ projectId, type: 'image-gen', name: '角色-张山 多视图', prompt: '按设定集写外观关键词' })`