@ninkch/dsh-infinite-canvas 0.17.4 → 0.17.6

package/assets/canvas-craft/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: canvas-craft
+description: 短剧与短视频的创作方法论：剧本结构、分场格式、分镜拆解、图片与视频提示词规范、角色一致性、设定集维护与交付自检。在无限画布里生成剧本、拆解分镜、写图片/视频提示词之前加载本技能。Load before writing scripts, storyboards or generation prompts.
+---
+
+# 创作方法论（剧本 / 分镜 / 提示词）
+
+本技能是**创作手法**规范；画布的操作流程（建项目、写节点、触发生成）见 `canvas-studio`。
+两者配合使用：先按本技能写出合格内容，再按操作规范落到画布上。
+
+## 一、短剧剧本方法论
+
+### 结构与节奏
+- **单集时长**：竖屏短剧常见 60–120 秒；对应 **4–8 场**，每场 15–30 秒。
+- **开场 10 秒必须有钩子**：悬念、冲突、反常画面或一句扎心的台词；不要铺垫世界观。
+- **三段压缩**：建置（1–2 场）→ 对抗（主体，冲突升级）→ 解决/反转（1 场，留悬念）。
+- **每场一个小目标**：人物想要什么 → 遇到什么阻碍 → 结果如何转折。写不出这条，这场就该删。
+- **结尾留钩子**：最后 3–5 秒抛出新信息或未解之谜（下集驱动力）。
+
+### 分场格式（固定八要素）
+```
+【第 N 场】内/外景 · 地点 · 时间
+人物：A、B
+画面：可拍摄的动作与环境（不写心理活动）
+对白：
+A：口语化短句。
+B：……
+```
+- **只写能拍出来的东西**：摄影机拍不到的心理描写一律改成动作、表情或对白。
+- **对白**：短句、口语；单场不超过 6 个来回；避免解释性台词（"你知道的，当年……"）。
+- **一致性**：人名、地名、道具名与设定集**逐字一致**，禁止擅自改名或新增设定。
+- **输出格式**：直接给可用剧本正文，不要解释、不要提纲、不要"待生成"占位。
+
+### 画面感要点
+- 用一个**具体的可视细节**替代形容词：不写"他很悲伤"，写"他把没送出的信折了三次，塞回口袋"。
+- 每场至少一个"能被记住的画面"（记忆点）。
+
+## 二、分镜拆解方法论
+
+### 粒度
+- **一段连续的动作节拍 = 一个镜头**；不要把两个不相关的动作塞进一个镜头。
+- **单镜头 2–5 秒**（一个镜头拍一个连续动作段落）；各镜时长之和 = 目标视频总时长
+  （如 15 秒 ≈ 4–7 镜）。整个分镜表会组合成**一条多镜头提示词，由视频模型一次性生成整段视频**
+  （镜头间由模型硬切，不需要逐镜生成再拼接）。
+- 一场通常拆 4–8 镜：建置镜（环境/全景）→ 主体镜（中近景）→ 情绪镜（特写）→ 动作镜（跟移/推拉）；
+  镜越短节奏越快，每镜的提示词要越聚焦。
+
+### 术语表
+- **景别**：大远景 / 远景 / 全景 / 中景 / 中近景 / 近景 / 特写 / 大特写。
+- **运镜**：固定 / 推 / 拉 / 摇 / 移 / 跟 / 升降 / 环绕；**一镜只用一种运镜**。
+
+### visual（首帧画面）公式
+> 景别 + 主体姿态 + 环境 + 光线 + 构图重心（+ 风格）
+
+示例：`中近景，陈拾右手举着信封站在雨里，老旧邮局门口，暖黄门灯打在信封上，主体位于画面右侧三分之一，写实电影感`
+
+### motion（运动/情绪）公式
+> 动作节拍 + 运镜方式 + 节奏
+
+示例：`他缓慢把信封贴上胸口，镜头缓慢推近，节奏由慢到停顿`
+
+- **一镜一个连续动作段落**；不要在一个镜头里写多个动作串联，也不要写跨镜切换（切镜由分镜表组织）。
+- **首帧与运动不重复**：visual 描述静止状态，motion 描述之后发生的变化。
+
+### 连续性（最容易被忽略，必须检查）
+- **180° 轴线**：对话双方在相邻镜头保持同一侧。
+- **服装 / 发型 / 光线 / 天气**在相邻镜头一致；换场要交代时间流逝。
+- **相邻镜头的方向与姿态要衔接**（180° 轴线、出入画方向一致）；多镜头一次性生成时
+  把衔接关系写进相邻镜头的提示词，模型会在同一条视频里保持连贯。
+
+## 三、图片提示词规范
+
+公式：**主体 + 景别/构图 + 环境 + 光线 + 风格质感 (+ 画幅)**
+
+- **角色一致性**（关键）：同一角色跨镜头，描述**逐字复用**设定集里的外观关键词
+  （年龄、发型、服装、配饰），只在景别与动作上变化。
+- **参考图绑定**：把角色/场景/道具资产连到图片节点的 ref 端口，顺序即 `[图N]`，
+  提示词里用 `[图1] 角色：陈拾（旧邮差制服，帆布邮包）` 这样的绑定说明。
+- **要避免**：一个画面里多个主体动作、文字/水印、风格混搭（写实 + 卡通）、
+  极端广角导致人物变形。
+- 风格统一：整部片用**同一套风格词**（如"写实电影感，暖色调，浅景深"）。
+
+## 四、视频提示词规范
+
+公式：**主体动作 + 运镜方式 + 环境变化 + 节奏/时长**
+
+- 单动作、单运镜；**不要写场景切换**（切换交给镜头之间的衔接）。
+- 与上一镜衔接：从上一镜的**末帧**继续动作（画布支持 last 帧作为视频节点输入）。
+- 时长与动作量匹配：3 秒只够一个动作，别写"转身、拔枪、开枪"三连。
+- 对白/音效单独交给配音（TTS）节点，不要写进视频提示词。
+
+## 五、设定集（Series Bible）维护
+
+- **风格**：一句话定调（题材 + 年代 + 色调 + 质感）。
+- **角色 / 场景 / 道具卡**：`名称 + 一句话设定 + 外观关键词`。
+- 首次出现某元素时补卡；此后**引用而非重写**，保证跨集跨镜一致。
+- 名字要唯一且可检索（不要"路人甲1""路人甲2"混用）。
+
+## 六、交付前自检清单
+
+- [ ] 剧本：开场 10 秒有钩子；结尾有悬念；对白口语化；每场有目标/阻碍/转折
+- [ ] 一致性：人名/地名/道具与设定集逐字一致；角色外观描述未漂移
+- [ ] 分镜：镜头数 × 时长 ≈ 目标时长；每镜一个动作；相邻镜头轴线与光线连续
+- [ ] 提示词：图片含景别/光线/构图；视频单动作单运镜；风格词全片统一
+- [ ] 资产：命名含项目 + 集数 + 场次（便于检索与后期对轨）
+- [ ] 成片：字幕覆盖全部对白；配音与画面同长；转场时长 ≤ 1 秒

package/assets/canvas-studio/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: canvas-studio
+description: 用无限画布（Infinite Canvas）做短剧/视频创作时使用：创建或复用项目、写剧本与分镜、触发生成、查看结果、命名与清理。用户提到画布、无限画布、短剧项目、剧本节点、分镜、生成视频，或要求"建个画布项目/把内容写进画布"时，先加载本技能再动手。Load this skill before operating the infinite canvas.
+---
+
+# 无限画布操作规程（硬约束）
+
+画布是一个按项目组织的节点工作台：剧本 → 分镜 → 图片 → 视频 → 成片。你（对话模型）是操作者，
+**所有画布操作只能通过 canvas_* 工具完成**，不要臆造节点或项目状态。
+
+## 一、硬约束（违反即视为操作失败）
+
+0. **设定集先行。** 写剧本、写分镜、生成任何画面之前，**必须先 `canvas_get_bible` 读设定集**：
+   - 世界观/核心设定、风格基调、角色/场景/道具为空或不完整时，**先补全设定集**
+     （`canvas_update_bible`），再开始生成；用户已给出创意时按其创意补全，不要凭空另起一套。
+   - **创作意图、世界观、核心设定、风格基调 → 全部写进设定集；
+     【禁止】为"创作意图/世界观/设定"单独建任何节点**——那是设定集的职责，不是节点。
+   - 角色/场景/道具的参考图也应**先从设定集条目生成**（为每个条目建 `image-gen` 节点 → `canvas_run_node`），
+     再进入分镜与镜头生成，这样才能跨镜跨集一致。
+   - 唯一例外：用户明确说"先随便写个剧本/不用管设定"。
+1. **同一个请求最多创建一个项目。** 调用 `canvas_create_project` 之前**必须先** `canvas_list_projects` 查重：
+   已存在同名或同主题项目 → **直接复用它的 projectId**，绝不重复创建。重复建项目会留下空壳项目，用户非常反感。
+2. **绝不为单个节点新建项目。** 往已有项目加内容一律用 `canvas_write_node(projectId=…)`；
+   只有用户**明确要求"另开一个项目"**时才调用 `canvas_create_project`。
+3. **失败重试不要重建资源。** 工具报错时先 `canvas_list_projects` 看是否已经创建成功（可能只是返回值校验问题），
+   已存在就复用，绝不靠"再建一个"来重试。
+4. **每个节点都要有可识别的名字。** 新建节点时传 `name`（如「第一节剧本」「第一节分镜表」「第2集剧本」）；
+   同名节点必须加区分后缀。**不存在"创作意图/设定"类节点**——那些内容在设定集里。
+5. **一个剧本节点必须同时有 `idea` 与 `output`——绝不把一个剧本拆成两个节点。**
+   - `idea`＝本节创作提示词（**对话侧负责填写**）；`output`＝完整剧本正文
+   - **正常情况：output 由节点自己生成**（写好 idea → `canvas_run_node`），对话侧不要代替节点写成稿；
+     仅当用户明确要求"直接写稿"时才用 `target:'output'` / `scriptOutput` 由对话填写
+   - **禁止**：一个只有 `idea` 的剧本节点 + 另一个只有 `output` 的剧本节点；**禁止**只写提纲、计划或"待生成"占位
+   - **分镜内容只能放分镜表节点（storyboard）**，绝不要写进剧本节点
+6. **删除是破坏性操作。** 先 `canvas_list_projects` 确认 id，且仅在用户明确要求时执行
+   （`canvas_delete_node` / `canvas_delete_project`）。
+7. **完成后让用户看到结果**：调用 `canvas_open({ projectId })`，画布会在数秒内自动跳转。
+8. **汇报固定要素**：项目名 + 项目 id + 节点名/id + 成稿摘要（若已生成）；有错误如实说明。
+
+## 二、标准工作流（对话填提示词+连线+触发，生成由节点完成）
+
+0. **读/补设定集**：`canvas_get_bible` → 缺什么用 `canvas_update_bible` 补。
+   创作意图、世界观、风格 → 写进设定集的 worldview/style 字段。
+1. `canvas_list_projects` —— 查重 + 拿到 projectId 与节点 id
+2. **剧本节点**：只写提示词，让节点自己生成剧本——
+   - 新项目：`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
+   - **【铁律】不要把成稿直接填进 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 留空）
+   - 参考图：把角色/场景/道具参考图资产连到视频生成节点的 `ref` 端口（`canvas_connect`）；
+     提示词里的 `@引用` 命中的资产也会自动挂上
+   - 触发：`canvas_run_node` → 轮询；整段视频一次生成完成
+5. **生成角色/场景/道具参考图**：为设定集里的每个条目
+   `canvas_create_node({ projectId, type: 'image-gen', name: '角色-张山 多视图', prompt: '按设定集写外观关键词' })`
+   → `canvas_run_node({ projectId, nodeId })` 触发（画布用它配置的图片接口）
+   - 需要补连任意两节点时用 `canvas_connect({ projectId, fromNode, toNode })`（端口类型必须匹配）
+6. `canvas_open({ projectId })` —— 让用户看到画布结果
+
+## 三、@引用与资产命名（跨集一致性的核心手法）
+
+**写图片/视频提示词时必须用 `@名称` 引用设定集条目**，不要只写名字：
+
+```
+中近景，@张山 站在 @褶皱巷 的雨里，手里攥着 @火漆信，暖黄门灯，写实电影感
+```
+
+插件会自动完成（用户也能在节点里看到"@引用命中"）：
+
+- `@张山` → 取设定集里「张山」的外观描述，并把它名下**所有参考图资产**按顺序追加为 `[图N]`
+- 连线参考图排在最前（`[图1..n]`，顺序可在节点里上下调整），`@` 命中的资产按**实体出现顺序**接在后面
+- `@名称` 在输入框里会**蓝色加粗显示**（人类可读），送给模型前会自动转成带 `[图N]` 与设定描述的标准提示词
+- 未命中设定集的名字不会报错，但会失去一致性保障——所以先补设定集再加 `@`
+
+**资产命名规范（必须遵守，否则跨集引用会断）**：
+
+| 用途 | 命名 | 例子 |
+| --- | --- | --- |
+| 角色参考图/多视图 | `角色-<名称> <说明>` | `角色-张山 多视图`、`角色-张山 参考图` |
+| 场景参考图 | `场景-<名称>` | `场景-褶皱巷` |
+| 道具参考图 | `道具-<名称>` | `道具-火漆信` |
+| 分镜表整段视频 | `<集数>-<场次> 多镜头视频` | `第1集-场3 多镜头视频` |
+
+生成角色/场景/道具参考图时，**用 `canvas_create_node` 的 `name` 直接写这个规范名**；
+插件会把资产记录绑定到对应实体（`entity` 字段），之后任何 `@名称` 都能精确取到它。
+
+**每集/后续工作的一致性纪律**：
+
+1. 每集开工前先 `canvas_get_bible`，**只沿用已有名称**；新元素先 `canvas_update_bible` 补卡再使用。
+2. **绝不改名**：一个角色的名字一旦写进设定集，后续所有集数、所有提示词都用同一个名字。
+3. 已生成的参考图资产**持续复用**：`@名称` 会自动带上它们，不需要重复生成。
+4. 若某实体还没有参考图，先为它建一个 `image-gen` 节点生成（用规范命名），再进入镜头生成。
+
+## 四、节点类型与字段
+
+| 类型 | 用途 | 主要字段 |
+| --- | --- | --- |
+| `script` | 剧本 | `idea`＝创作意图/提示词，`output`＝剧本成稿 |
+| `storyboard` | 分镜表（多镜头脚本） | 由剧本拆镜头（画布内生成）；一个分镜表对应一次视频生成 |
+| `image-gen` | 图片生成 | `prompt`＝画面提示词 |
+| `video-gen` | 视频生成（多镜头一次性生成） | 多镜头提示词来自上游分镜表连线；`duration`＝各镜时长之和 |
+| `text` | 自由文本 | `text` |
+
+## 四、生成能力（必须真的产出内容）
+
+1. **文本类（剧本 / 分镜）**：可由你直接生成完整正文，用
+   `canvas_write_node({ projectId, nodeId, text: 完整正文, target: 'output' })` 写入；
+   也可让画布用它自己配置的模型生成：`canvas_run_node({ projectId, nodeId })`。
+2. **图片 / 视频**：只能由画布生成（使用用户在画布设置里配置的图片/视频接口）：
+   `canvas_run_node({ projectId, nodeId })` 触发 → `canvas_node_status` 轮询直到 `status` 变为
+   `done`（成功）或 `error`（失败，读 `error` 字段并向用户说明）。
+3. **模型为空/报错时**：`canvas_node_status` 会给出错误文本（例如"模型未返回文本"）——
+   如实转达，并建议用户在画布设置里更换文本模型；**不要谎报已生成**。
+4. **生成需要时间**：图片/视频可能几十秒到数分钟。触发后用 `canvas_node_status` 间隔轮询
+   （建议 ≥10 秒一次），不要反复触发同一个节点。
+
+## 五、生成参数来源（不要臆造参数）
+
+- **文本模型**：走 Harness 里已配置的 provider/model 与其默认参数。画布设置里可填「输出上限」「温度」，
+  **留空即不下发该字段**（用 Harness/模型的默认值）。
+- **图片 / 视频 / 配音**：走用户在画布设置里配置的 API 与其参数；仅当用户填写了覆盖项
+  （如图片 `size`、`response_format`、Seedance 的音频/水印）才发送，否则用 API 默认。
+- **不要**向用户断言某个模型的上下文/输出上限数值——以 Harness 配置与厂商文档为准
+  （例：GLM-5.3 / GLM-5.3-Flash 为 1M 上下文、最大输出 128K）。
+- 生成失败时，插件会回传真实原因（含 chunk 类型统计）；如实转达，不要猜测。
+
+## 六、ArtCraft 后期全流程（PhotoCraft / FilmCraft / EffectCraft）
+
+前置：用户需安装 `dsh-artcraft` 插件并配置三个 CLI 路径（画布设置 → Craft 后期 卡片会显示
+就绪/缺失状态与数据目录）。资产会同步到 Craft 工作区按项目分目录存放。
+
+流程顺序（每一步的输出是下一步的输入）：
+
+1. **素材就绪**：剧本 → 分镜 → 图片/视频生成完成（节点 `status=done`，有 `assetId`）。
+2. **资产落盘**：把节点产物同步到 Craft 工作区（画布 UI 的"同步"按钮；对话侧通过
+   `canvas_node_status` 确认产物已生成）。
+3. **PhotoCraft（调色/修图）**：对单张或批量图片做无头调色，产物为调色后的图片资产。
+4. **EffectCraft（片头/特效）**：生成片头动画（Lottie/序列），作为成片开场。
+5. **FilmCraft（成片渲染）**：把分镜视频片段 + 配音 + 字幕合成成片。
+   画布上的「成片（finalcut）」节点会把片段合成 MP4，并可导出 **FCP7 XML + SRT** 交给
+   FilmCraft 渲染正式成片。
+6. **交付**：成片资产可在「资产」页下载；数据根目录下 `projects/<项目>/…` 有对应文件。
+
+**当前边界（务必如实告知用户）**：PhotoCraft / FilmCraft / EffectCraft 的**执行按钮在画布 UI 上**
+（节点内的 Craft 按钮、成片节点的导出按钮），对话工具目前不能代替点击这些按钮。
+你能做的是：准备节点与提示词、写入成稿、触发生成、检查状态、并在完成后引导用户到画布执行后期步骤。
+如果用户希望"对话直接驱动后期"，请明确提出——这需要为 ArtCraft 增加对应工具。
+
+**排查建议**：Craft 卡片显示"未找到可执行文件"时，先让用户在画布设置里配置 CLI 路径，
+再重试；`effectcraft` 若未配置只影响片头，不阻塞成片。
+
+## 四、必须避免的错误
+
+- ❌ 一次请求里创建多个项目（含"重试式重建"）→ 先查重、复用
+- ❌ 每个节点都新建项目 → 用 `canvas_write_node` 往同一 projectId 追加
+- ❌ 只写提示词、不写剧本正文 → 成稿必须进 `output`
+- ❌ 节点不留名字 → 一律用 `name` 命名
+- ❌ 未经确认就删除项目/节点 → 先列表确认、再按用户明确要求删除