@aswless_854771076/ai_short_studio_cli 0.1.59 → 0.1.61

package/README.md

@@ -120,7 +120,7 @@ CLI 通过 `/api/v1/bootstrap` 完成版本、连通性与 Supabase 公共配置
 
 `storyboard-image` schema 现在暴露节点级 `gridSize`。CLI 继续按实时 schema 通用写入，配套 Skill 会分析每个镜头的动作、运镜、多人调度和连续性难度，向用户确认后逐镜设置；未单独设置或连接旧服务时回退到项目格数，系统默认为 6 格。
 
-专业 Markdown 剧本可在 `storyboard-breakdown` 配置中显式使用 `storyboardPipelineVersion: 2`、`sourceFormat: screenplay-markdown.v1`、`targetLanguage: en|ar`、`platform: TikTok` 和 `aspectRatio: 9:16`。CLI 通过现有通用节点配置写入这些字段。该模式只生成分镜文本和镜头资产，不自动运行声音、TTS、图片、音频或视频节点。
+专业 Markdown 剧本可在 `storyboard-breakdown` 配置中显式使用 `storyboardPipelineVersion: 2`、`sourceFormat: screenplay-markdown.v1`、任意规范 BCP 47 `targetLanguage`（如 `en`、`ar`、`fr`、`pt-BR` 或 `zh-Hant`）、`platform: TikTok` 和 `aspectRatio: 9:16`。CLI 通过现有通用节点配置写入这些字段。该模式只生成分镜文本和镜头资产，不自动运行声音、TTS、图片、音频或视频节点。
 
 标准短剧制作先用随包安装的 `short-drama` 生成和复核专业剧本，再用 `humanizer` 审计模板化台词、虚浮修辞与机械节奏，随后回到 `short-drama` 检查剧情连贯性（已有专业剧本直接复用）。Humanizer 只润色表达，不改剧情事实、人物关系、专有名词、数字、时间线、世界观规则、场次结构或拍摄标记。剧本确认后再选择目标集数、创建或复用项目，并只建立目标集实际出现的人物、场景、道具和可选音色设定。拆镜前必须完成资产—剧情匹配审计；拆镜后逐镜全量检查重复、无效、缺失、冲突、穿帮、连续性、道具交互朝向、语言和来源身份。P0/P1 未清零时不得进入图片、声音或视频生产。
 
@@ -128,7 +128,7 @@ CLI 通过 `/api/v1/bootstrap` 完成版本、连通性与 Supabase 公共配置
 
 `canvas settings set` 支持项目级 `imageResolution`、`imageQuality`、`videoResolution`，未覆盖的图片、图片编辑和视频节点会继承这些默认值。候选值来自 `settings get` 对应字段的实时 `options`；节点仅在需要偏离项目默认时，按当前模型 `capabilities` 写入 `resolution`、`quality` 覆盖。
 
-项目输出语言通过 `ai-short-studio canvas settings set --project <PROJECT_ID> --field outputLanguage --value en` 设置，也可用 `null` 恢复自动。语言变化只把相关下游节点标为 stale，不删除历史资产或自动生成。交付时只下载每镜 selected 原始 MP4，按 `S001.mp4` 顺序命名，并用 manifest 记录镜号、节点、资产、版本和文件名；字幕单独交付，不烧录进原始视频。
+项目输出语言通过 `ai-short-studio canvas settings set --project <PROJECT_ID> --field outputLanguage --value pt-BR` 设置，接受任意规范 BCP 47 标签；用 `null` 恢复自动跟随输入。语言变化只把相关下游节点标为 stale，不删除历史资产或自动生成。交付时只下载每镜 selected 原始 MP4，按 `S001.mp4` 顺序命名，并用 manifest 记录镜号、节点、资产、版本和文件名；字幕单独交付，不烧录进原始视频。
 
 百炼 CosyVoice 的 `tts` 节点通过实时 schema 提供音色、语言、格式、采样率、音量、语速、音调和声音指令。先用 `canvas settings get` 确认最终 `audioModel`，再从 `canvas node types` 返回的 `tts.configSchema` 选择字段和值；CLI 会在写入前校验必填字段、类型、整数、枚举和数值上下限。
 

package/dist/commands/canvas/settings/set.js

@@ -43,7 +43,7 @@ export default class CanvasSettingsSet extends BaseCommand {
     static flags = {
         ...BaseCommand.baseFlags,
         project: projectFlag,
-        field: Flags.string({ description: '要更新的设置字段，如 outputLanguage、imageResolution、imageQuality、videoResolution', dependsOn: ['value'], exclusive: ['file'] }),
+        field: Flags.string({ description: '要更新的设置字段；outputLanguage 支持 pt-BR 等 BCP 47 标签', dependsOn: ['value'], exclusive: ['file'] }),
         value: Flags.string({ description: '字段值', dependsOn: ['field'], exclusive: ['file'] }),
         file: Flags.string({ description: '设置 JSON 文件；省略时读取 stdin', exclusive: ['field', 'value'] }),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aswless_854771076/ai_short_studio_cli",
-  "version": "0.1.59",
+  "version": "0.1.61",
   "description": "VVICAT 无限画布项目命令行工具",
   "license": "MIT",
   "private": false,

package/skills/using-vvicat-ai-short-studio-cli/SKILL.md

@@ -5,319 +5,44 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
 
 # 使用 VVICAT AI Short Studio CLI
 
-## 核心原则
-
-把 `ai-short-studio` 当作机器可读的远程控制接口。创作全程只要目标、素材含义、平台、语言、画幅、时长、风格、人物、场景、道具、模型、节点 schema、候选版本、付费范围或覆盖影响存在未知、缺失或矛盾，就合并列出最少必要问题并询问用户；得到答复前只做只读检查，不用示例值或自行推断替用户做创作决定。本文明确规定的 `16:9` 素材画幅是标准流程默认值；视频时长必须读取当前模型的实时 `durationOptions`。只有实时模型仅提供 5、10、15 秒时，标准流程才可按目标时长向上取这三档并在执行摘要中说明；其他模型按实时合法值和用户确认选择，不得硬编码三档。新建或继续任何无限画布项目时，项目配置是创作节点之前的硬门禁：配置写入并回读验证通过前，不得创建或执行任何创作节点。
-
-同一阶段存在两个及以上可合并的操作时，默认使用一个 CLI 进程完成批处理：项目配置用一次 `canvas settings set --file` 或 stdin，节点字段更新用 `canvas node update-many`，节点、连线、删除和视口等同一画布补丁用一次 `canvas apply --file` 或 stdin，互不依赖的节点执行用一次 `canvas node run --node … --node …`，多个任务等待用一次 `task wait --task … --task …`。批量执行与等待默认并发 4、上限 16；不要由 Agent 并发启动多个 CLI 进程。这样可复用同一会话、降低请求开销，并避免频繁触发 macOS Keychain。批量提交前读取一次最新画布与实时 schema，构造完整预期差异；`canvas apply` 同时传入已读到的 `--canvas-id` 和 `--expected-version`，避免保存前再次读取全图。成功后统一回读审计。批量命令不存在、当前服务不支持，或合法批量请求在处理批量粒度时失败，才回退到对应的单条命令，并只处理尚未生效的项。409 先重读、合并并确认后继续重试批量；401/403、参数、schema、业务门禁或付费确认错误必须停下修正，不得用单条命令绕过。
-
-常用画布查询优先使用一次 `canvas inspect`，按需重复 `--include summary|nodes|edges|assets|settings|node-types`，并通过 `--kind`、`--status`、`--search`、`--operation`、`--resource-type`、`--producer-node` 过滤。能由这些参数表达的查询不得临时编写 TypeScript、Python、jq 或 shell 数据处理脚本；只有 `inspect` 无法表达且现有专用命令也不满足时才允许临时脚本，并在结束后清理。
-
-## 初始化检查
-
-创建项目或修改任何资源前，按顺序执行：
-
-1. 运行 `ai-short-studio preflight --json`。它通过 API base URL 检查连通性和 CLI 最新稳定版，未配置地址时使用测试环境 `https://ai-short-studio.vvicat.dev`，默认发现更新就更新当前全局包；`restartRequired` 为真时必须重跑。连不上时提醒用户检查 `--base-url`、`VVICAT_BASE_URL`、profile 或默认测试环境，不猜其他地址。
-2. 未登录且已有账号时执行 `ai-short-studio auth login --google` 或邮箱登录；没有账号且用户明确要求注册时，先核对 profile 的 `baseUrl` 确实指向目标环境，再使用 `auth signup --email <email> --password-stdin`。CLI 会从服务端取得 Supabase 公共配置，并把同域的 `/{locale}/auth/callback` 显式设为注册确认回调。注册返回 `confirmationRequired: true` 时，等待用户完成邮件验证后再登录。登录后重跑 preflight。`ready` 为 false 且缺失项仅为 `capabilityDefaults.<modelKey>.<field>` 时，不先反馈用户：立即运行 `config get`，确认模型已启用且该字段存在非空实时 `*Options`，优先复用目标项目对应的有效设置，其次使用服务端返回的模型默认值，否则使用实时 options 第一项；将全部可确定缺项合并为一次 `config set --file` 写入当前账户，随后 `config get` 回读并重跑 preflight。无权写入、回读不一致或仍为 `ready=false` 时才报告。缺少默认模型、模型不可用、没有合法 options 或涉及供应商与模型目录时不得猜测，交由用户或管理员处理。
-3. 运行账户级只读命令 `ai-short-studio config get --json`，取得账户默认模型及管理员已发布的全局模型。创建项目至少要求已配置 `defaultModels.analysisModel`；缺失时 `project create` 会在发送创建请求前停止，需先由用户在设置中心完成配置。供应商、密钥和模型目录只能由管理员维护；`config set` 只维护个人默认模型及其能力默认值和工作流并发，不得写入 `providers` 或 `models`。
-   Comfly 和 RunningHub 同样从全局目录选择；其凭据、服务地址和工作流映射由管理员或服务端维护，CLI 不要求也不接受用户配置供应商连接。
-4. 运行 `ai-short-studio canvas node types --json`，按实时 `inputSchema`、`outputSchema`、`configSchema` 和 `defaultConfig` 确定能力与必填项。
-5. 运行 `project list` 判断目标是新项目还是既有项目。新项目先确认账户默认分析模型已配置，再按“确认名称和用途 → `project create` → `project get` + 一次 `canvas inspect --include summary --include nodes --include edges --include assets --include settings --include node-types`”继续；未通过模型审查时不得尝试创建。既有项目同样用 `project get` 加一次聚合查询取得画布、项目配置、节点目录和资产。只有聚合结果缺少专用命令独有字段时才补充单项读取，不得把这些查询拆成一串 CLI 进程；也不得要求尚未创建的新项目先读取项目或画布。任何缺口仍按核心原则询问。
-6. 运行 `ai-short-studio skill status --target codex --json`；非 current 时询问后更新，用户修改或非托管目录不得擅自 `--force` 覆盖。
-7. Meme 流程需要外部背景时，运行 `project provider get <projectId> --json` 检查 Pexels 状态；只在用户明确提供 Key 并授权写入后，才通过安全 stdin 执行 `project provider set`，随后运行 `project provider test`。
-
-## 项目配置门禁
-
-1. 运行 `canvas settings get --project <projectId> --json`，向用户展示项目名称与用途，并逐项确认以下设置的项目覆盖值 `currentValue`、继承后的 `effectiveValue`、建议值和来源 `source`：`aspectRatio`、`artStyle`、`visualBible`、`storyboardImageType`、`analysisModel`、`imageModel`、`imageResolution`、`imageQuality`、`editModel`、`videoModel`、`videoResolution`、`audioModel`。画风、画幅、分镜、模型及分辨率/质量候选必须读取服务端实时 `options`；用户未指定分镜类型时推荐 `storyboardImageType: grid`（分镜板/宫格分镜），不再默认推荐 `storyboard`（故事版）。`visualBible` 按返回的 `schema` 构造，不得硬编码枚举或结构。模型既可写为项目覆盖，也可由用户明确确认继承账户默认，但必须列明最终生效且当前可用的具体模型。缺失、冲突或继承结果不明确时先一次性询问。
-2. 必须展示并确认 `storyboardGridSize` 的项目覆盖值、继承后的默认分镜格数和来源；系统默认值为 6 格。`storyboard-image` 的实时 schema 已提供节点级 `gridSize`，正常流程应逐镜配置；连接旧版本服务且 schema 未暴露该字段时，禁止虚假写入，并回退到用户确认的项目格数。
-3. 优先在项目配置中确认 `imageResolution`、`imageQuality` 和 `videoResolution`，让未单独设置的图片、图片编辑和视频节点统一继承。候选值只从 `canvas settings get` 对应字段的实时 `options` 选择；节点确需不同参数时，才按节点当前模型 `capabilities` 的 `resolutionOptions`、`qualityOptions` 写入 `resolution`、`quality` 覆盖。模型未声明选项时不得臆造字段值。
-4. 新项目按初始化顺序确认名称和用途、创建项目并取得项目、画布与 settings；既有项目开始创作前也必须完成本门禁，名称或用途需要更新时只用 `project update` 修改用户确认的项目字段。用途可记录在项目描述中，但描述不构成画布 settings。不得用账户级 `config set`、项目 `description` 或节点 `prompt`/`config` 代替 `canvas settings set`。
-5. 用户确认后，用一次 `canvas settings set --file <settings.json>` 或 stdin 原子写入所有变更。标准创作门禁必须把最近一次 `settings get` 返回的 `version` 填入请求的 `expectedVersion`，并统一使用这种批量模式；`--field/--value` 只适合已确认无并发写入的交互式便利操作。画风 ID 必须从 `artStyle.options` 选择并解析实时 `option.value`，示例中的 `$ART_STYLE_ID` 不是固定值。`null` 或空字符串表示清除项目覆盖并恢复账户/系统继承。设置 `artStyle` 会保存其当前关联的 `visualBible` 项目快照；画风库之后的修改不反向更新项目，同一请求显式传入 `visualBible` 时以显式值为准。
-6. 写入后立即再次执行 `canvas settings get`，比较所有目标字段的 `currentValue`、`effectiveValue` 和 `source`。只有结果符合用户确认且所需模型明确可用，才可创建或执行创作节点。409 冲突时重新读取、展示变化并取得确认，携带新 `expectedVersion` 重试；不得盲目覆盖。所有者和管理员可写，协作者只读；写入、回读或权限校验失败时停在配置阶段，不触发任何付费任务。
-
-## 剧本创作与审计联动
-
-**REQUIRED SUB-SKILL: Use short-drama**
-
-**REQUIRED SUB-SKILL: Use humanizer**
-
-用户需要从选题、创作方案、人物、分集目录开始创作或续写微短剧剧本时，先使用 `short-drama` 完成对应阶段与 `/review`，再以嵌入模式使用 `humanizer` 审计并改写剧本中的 AI 腔、模板化台词、虚浮修辞、机械排比和不自然节奏。Humanizer 只能润色表达，不得改动已经确认的剧情事实、人物关系、专有名词、数字、时间线、世界观规则、场次结构和拍摄标记；润色后的剧本仍须回到 `short-drama` 检查连贯性并取得用户确认，再交给本 Skill 创建 VVICAT 项目、素材和分镜。已有专业剧本时直接创建 `screenplay-resource` 并进入素材与分镜流程，不得重复执行 `novel-to-script`；只有输入仍是小说、故事梗概或需要改编的原文时才使用 `novel-to-script`。
-
-## 短剧项目制作门禁（强制顺序）
-
-1. **确认专业剧本**：没有已确认剧本时，必须先调用 `short-drama`，完成创作方案、角色、分集目录、目标单集剧本及 `/review`，再用 `humanizer` 去除 AI 味并回到 `short-drama` 复核连贯性；已有专业剧本直接复用。剧本未确认时不得创建付费生产节点。
-2. **选择目标集数后建项目**：先让用户确认本次目标集数，再创建或复用无限画布项目并完成项目配置门禁。只提取目标集实际出现的人物及形象版本、场景及子场景、关键道具及叙事版本；不得为未选集数提前创建资产。
-3. **按模型决定音色资产**：项目存在有效配音模型且本次需要声音制作时，为出场角色创建音色描述或音色资产。音色设定与 TTS 分离；没有用户授权不得执行声音设计、TTS、图片、音频或视频生成。
-4. **执行资产—剧情匹配审计**：逐项输出“剧本出现项 / 已创建资源 / selected version / 拆镜连线 / 结论”，检查缺失、多余、同名、真假、年龄、服装、状态、所有权、场景版本、音色偏差、stale、重复和跨类型连线。缺失未清零、版本冲突未确认、必要资源没有 selected version，或实际连线集合不等于目标集需求时，拆镜前门禁失败，禁止运行 `storyboard-breakdown`。
-5. **每集独立拆镜**：每个拆镜节点只能连接一条目标集专业剧本，并连接该集全部已确认人物、场景和道具。任务完成后必须按集号、`parentAssetId` 和 `producerNodeId` 回查产物归属，不能按任务提交顺序推断，也不能重复创建服务端自动生成的镜头节点。
-6. **执行镜头质量审计**：拆镜后按镜号全量检查，不抽样。至少检查剧本动作、台词、旁白、反应和转场是否覆盖，重复/无效/缺失镜头，人物与资产误配，真假和年龄版本冲突，服化道穿帮，人物位置、视线、轴线、动作和道具状态连续性，景别与机位异常，以及目标语言、台词归属、集号和来源身份。人物使用手机等道具时还要确认主体朝向交互面，不能默认让屏幕正对观众。
-7. **按严重级别闭环**：报告逐镜列出 P0/P1/P2、证据、问题类型和最小修复。P0/P1 未清零时不得进入分镜图、声音或视频生产；只精确修改受影响镜头或连线，并重跑同一资产审计和镜头审计，禁止用全量重建掩盖局部问题。
-
-本节只规定阶段顺序与通过条件。具体连线覆盖、相邻镜连续性、内容误匹配和生成后验收，继续执行下文“分镜素材连线门禁”“镜头级素材审计”“上下镜连续性审计”“分镜逻辑审计”和“生成后自我审计”。
-
-## 标准创作流程
-
-1. 明确原始故事或剧本、目标受众与平台、语言、成片画幅、总时长与镜头目标时长、风格参考、人物/场景/道具约束，以及交付是否包含剧本、设定、分镜图、视频和音频；除本文明确的素材画幅默认值外，缺项先问。实时 `durationOptions` 只限定合法值，不代替用户确认镜头目标时长。
-2. 完成 preflight、账户配置读取和节点目录检查后，新项目按“project list → 确认名称/用途 → project create → project get + canvas get + canvas settings get”继续，既有项目读取相同的已有资源；再按“项目配置门禁”确认、原子写入并回读 settings。两种项目都必须在任何创作节点之前通过门禁；既有项目只修改用户确认字段，并优先复用已确认的节点与 selected version。
-3. 原文需要改编时执行 `novel-to-script`。分镜拆解前必须先完成人物、场景、道具等本次故事涉及的素材生成。角色、道具、场景/背景、分镜图及其他视觉参考素材，用户未指定画幅时统一采用推荐值 `aspectRatio: 16:9`；用户明确指定其他画幅或平台硬性要求不同时，以用户要求为准。创建或更新节点前读取实时 `configSchema`：支持 `aspectRatio` 的节点必须显式写入最终值，不得误继承项目中的其他画幅；不支持时不得伪造字段，应说明实际继承来源并在付费生成前确认最终有效画幅。`character-visual-design` 的实时 schema 支持 `candidateCount` 时，只能按用户确认值写入 1～3，未指定时保留服务端默认值 1。人物视觉方案的每个 `appearance.descriptions` 候选必须拆成独立输入，并采用“一候选描述 → 一个三视图节点 → 一个独立图片资产”的方式生成；道具存在多个候选方案（真/假、原版/复制品、干净/破损等成对或多版本）时，**必须按“关联资产参考图门禁”先生成基础版并用户确认 selected version，再把该基础版的 image-resource 作为参考图连入派生版 turnaround/design 节点，prompt 逐条枚举允许的差异**，不得两版并行独立生成。每个三视图/设计节点只能接收一个人物形象或一个道具候选，提示词必须明确“只生成当前候选的一张三视图，不得拼接其他候选”；单张三视图内部可以包含同一对象的正面、侧面和背面，但禁止把多个候选方案纵向、横向或宫格拼成一张图。`count` 只表示同一候选的独立生成版本数，每个结果必须作为独立图片版本展示和选择，不得合并为一张长图。互不依赖的素材节点应同批执行并收集真实任务 ID，再并发 `task wait`，不得等待一个完成后才提交下一个；存在上游依赖（例如假道具依赖真道具参考图、童年形象依赖成年形象参考图）时必须按依赖顺序分批执行，参考图未选定 selected version 前不得提交下游派生节点。每个任务都必须到成功终态，并让用户确认后为每项素材设置 selected version。任一素材未生成成功、未确认或没有 selected version 时，禁止执行 `storyboard-breakdown`，先询问用户并补齐。
-4. 按实时节点 schema，把已确认的剧本节点，以及每个人物、场景、道具等相关素材节点，逐项连接到 `storyboard-breakdown` 对应输入 handle（通常为 `script`、`characters`、`locations`、`props`）。执行前重新读取画布和连线，确认本次故事涉及的素材节点无遗漏；即使服务端把素材输入标为可选，标准创作流程也不得省略。任一对应连线缺失时禁止拆解，先补线；素材范围不清楚时先询问用户。全部门禁满足后才执行并等待。成功后刷新画布，读取服务端自动创建的 `storyboard-shot` 和 `storyboard-image`，不得重复手工创建，并通过“分镜素材连线门禁”。
-
-   用户明确要求专业 Markdown 剧本拆镜测试时，给 `storyboard-breakdown` 显式配置 `storyboardPipelineVersion: 2`、`sourceFormat: screenplay-markdown.v1`、目标集的 `targetLanguage: en|ar`、`platform: TikTok` 和 `aspectRatio: 9:16`，且只能连接一条剧本。该模式只验收分镜文本和镜头资产：声音只记录音色设定，不执行 `voice-design`；不执行 TTS、图片、音频或视频节点。任务成功后确认来源与逐字校验通过且没有新增 IMAGE/AUDIO/VIDEO 版本；任务失败时确认没有新增分镜版本或镜头。
-5. 生成分镜图前，必须先通过“分镜素材连线门禁”。再用 `canvas asset get/list` 取得人物、场景、道具等已选版本，必要时下载，并把实际图片或可访问预览展示给用户；只提供资产 ID、文件路径或文字说明不算展示。用户明确确认素材与选版后，读取 `storyboard-image` 的实时 `configSchema`，用户未指定画幅且 schema 支持时将 `aspectRatio: 16:9` 显式写入节点，再分析每个镜头的动作阶段、运镜变化、多人调度和连续性难度，选择 schema 允许的最小够用格数：简单镜头建议 4 格，常规镜头使用默认 6 格，复杂镜头建议 9 格，16/25 格只用于用户明确需要的长动作或高密度关键帧。向用户展示逐镜建议并确认后，将各自 `gridSize` 写入对应节点；旧服务 schema 未暴露字段时不得虚假写入，应说明限制并回退到项目有效值，`gridSize` 未另行确认时为 6 格。用户未指定布局时推荐并使用 `imageLayout: grid`（分镜板/宫格分镜）；`storyboard`（故事版）与 `single` 仅在用户明确选择时使用。最终仍需确认镜头范围、参考资产、模型与费用范围。未展示、未确认或连线门禁未通过时禁止生成分镜图。
-6. 执行分镜图后按“生成后自我审计”检查真实产物，并展示给用户确认。新分镜直接读取 `independent` / `previous-tail`，但该字段只作为建议：服务端不自动创建尾帧节点或连线，也不阻止后镜独立生成。需要严格连续性时，在用户确认后显式执行 `--apply-ready`。之后复用自动创建的 `storyboard-video-prompt`，按实际布局重写视频提示词并确认后执行 `video-generate`。镜头建议时长按正常剧情节拍、口播和动作确定，首尾保留约 1–2 秒剪辑余量；不为命中全片总时长机械扩镜。执行时先读取当前模型的实时 `durationOptions`；只有实时选项仅为 5、10、15 秒时，才按目标时长向上取这三档。其他模型选用用户确认的实时合法时长，并保留原建议时长供剪辑裁切。未展示或未确认分镜图时禁止生成视频。
-7. 配置门禁固定用一次 `canvas settings set` 写入确认字段；通过门禁后的同阶段节点与连线变更优先合并为一次 `canvas apply`。只改节点 config、标题或坐标时，单节点使用 `canvas node update --set/--unset/--title/--x/--y`，多节点使用一次 `canvas node update-many`；不能借此编辑结构化 artifact。互不依赖的节点通过一次 `canvas node run` 重复传 `--node`，需要立即等待时加 `--wait`；已经取得多个任务 ID 时通过一次 `task wait` 重复传 `--task`，不用固定 sleep。批量不可用或按“核心原则”处理后仍失败时才回退专用单条命令。
-8. 每批图片、视频或音频生成完成后必须先通过“生成后自我审计”，才能报告成功、请求选版或进入下一付费阶段。在进入视频生成前，必须额外依次执行：(a)“镜头级素材审计”全量清单，核对 reference 集合覆盖镜中人物/场景/道具、无跨类型错边、成对资源引用正确版本、stale 清零、道具词扫 description 兜底、资源文字设定贯穿到 shot/image；(b)“上下镜连续性审计”，按时序逐对相邻镜核对人物位置、道具状态、光影色调、动势视线、景别节奏、叙事桥接，并给有动作连续关系的镜组互加 reference、给极端特写/物证镜补入必要的人物 reference；(c)“分镜逻辑审计”，对照叙事期望逐项扫掉关键词误命中、真假道具互串、跨段同名实体误连、黑场/空镜多余连线、多版本角色（成年/童年）误连、龙套角色引用主角资源等问题，输出逐镜审计表并精确删/加边直到 wired=plan；(d) 把图像模型的已知先验 bias（数字、具象动物、实体面具、中文字样等）列入视频阶段 prompt 的 negative 约束。交付前再次确认 selected version 与下载目录，记录项目、节点、任务和资产 ID、审计结论、失败项与未决项。临时项目在所有结束路径删除；既有项目绝不擅自删除。
-
-## 分镜素材连线门禁
-
-在首次生成或重跑任何 `storyboard-image` 前，对当前画布的每个 `storyboard-shot → storyboard-image` 配对执行以下检查；任一项失败都禁止付费生成：
-
-1. 读取当前 shot 的 selected asset 完整结构，并以已确认的人物、场景、道具资源名称核对 `characters`、`location(s)`、`props` 与 `description`、`sourceText/source_text`、`imagePrompt/image_prompt`。若叙事字段明确出现某资源而对应结构字段为空、漏项或冲突，判定 breakdown 产物不完整；不能因为文字 prompt 提到了素材就视为已注入参考图。若 `props` 结构字段缺失（某些模型版本只输出 characters/location），必须用关键词扫 description/video_prompt/photographyPlan 来确定每镜道具，不得因为字段缺失就跳过。
-2. 只把资源全名、稳定资源 key 或用户已确认的别名视为确定匹配。简称、同类物、真假版本、多人/多场景同名等无法唯一映射时，列出“镜头 → 候选资源”并询问用户，不得自行猜测。
-3. 为每镜生成期望素材表，逐项核对其 selected version、实际图片产物和目标 `storyboard-image` 的引用边。视觉素材优先从已选版 `image-resource` 的图片输出接入实时 schema 支持的 `reference` 或对应语义 handle；不能用 `prop-turnaround` 等生成节点本身冒充最终参考资产。核对时必须分别统计人物、场景、道具三类素材两种边：(a) 从各自图片资源连入 `storyboard-image.reference` 的图片参考边；(b) 从资源文字设定节点（`character-resource`/`location-resource`/`prop-resource`）连入 `storyboard-shot.<handle>` 和 `storyboard-image.<handle>` 的文字边。两类边都要三类素材对称覆盖，不能只看图片参考边而漏掉文字边——道具类资源尤其容易出现“文字只连到 breakdown、三视图只连到 reference、但 prop-resource 本身没连到 shot/image”的物化 bug，导致编号/印记/negative 约束等文字信息在 shot/image 阶段全部丢失。道具边数显著少于人物/场景时即为物化 bug，按下一条补线。
-4. 按实时输入输出 schema 和业务链路审计全部相关边，拒绝跨类型、反向、互连、重复和串镜边。`prop-turnaround` 的图片只能物化到对应道具图片资源，不得连到 `location-image`、其他 turnaround 或无关镜头。
-5. 发现已物化画布缺线或错线时，先输出精确差异：要删除的 edge ID、要新增的 source/handle → target/handle、受影响镜头和预计重跑范围。不得改写自动生成的 shot asset、伪造 `props` 字段或重复创建自动下游节点。
-6. 仅在映射唯一或用户已确认后修复。写前重读画布版本；优先使用 `canvas edge add/delete`，只删除精确 edge ID，保留无关和用户自建连线。写后重新读取并重复同一审计，确认实际边集合等于期望集合、无重复且再次执行不会产生新差异，才允许只重跑受影响镜头。
-
-结构字段漏项属于上游产物或物化缺陷，不得静默绕过。能用确定映射恢复 reference 时按上述幂等流程修复；不能确定时停止并报告缺口，等待用户选择重新拆解或确认映射。
-
-## 画布资产目录管理（canvas folder）
-
-无限画布项目按分集隔离画布、目录和资产。用 `canvas episode list --project <projectId>` 列出分集，用 `canvas episode create --project <projectId> --number <n>` 创建分集；其他 `canvas *` 命令传 `--episode <episodeId|集数>` 选择作用域。
-
-CLI 不提供分集删除或任务人工复核提交。遇到需要删除分集、选择一致性测试结果或提交视频人工复核的场景，转到网页端完成，不得用低层请求绕过确认。
-
-画布资产目录是项目内"道具 / 人物 / 场景 / 配音 / 分镜"五类的物理容器，命令族 `canvas folder *` 独立于 `canvas asset *`，专管目录结构。
-
-### 概述
-
-- 5 个预设目录（道具、人物、场景、配音、分镜）在项目初始化时自动创建，名称固定，不可重命名、不可移动、不可删除
-- 用户可在 5 个预设目录的任意层下创建子目录，递归层级上限 32 层
-- 删除目录走软删逻辑：节点进入 30 天回收窗口，可恢复；窗口外返回 `FOLDER_GONE`
-- 跨项目复制资产时不复制目录结构，仅复制资产条目与所属版本
-
-### 强制顺序
-
-1. 执行 `canvas folder list --project <projectId> --json` 取得活动目录树（含 5 个预设 + 用户子目录）。只有传 `--include-soft-deleted` 时才同时返回软删节点
-2. 需要修改目录结构前必须先 list，避免对不存在的 `folderId` 操作触发 `404 / FOLDER_NOT_FOUND`
-3. 创建子目录：`canvas folder create --project <projectId> --name "..." --parent-id <folderId>`。省略 `--parent-id` 时创建在项目根层
-4. 重命名：`canvas folder rename --project <projectId> --folder <folderId> --name "..."`。预设目录禁止重命名，返回 `FOLDER_PRESET_IMMUTABLE`
-5. 移动：`canvas folder move --project <projectId> --folder <folderId> --parent-id <parentId>`。预设目录禁止移动；同项目内不允许形成环（目标 `parentId` 不能是 `folderId` 的后代），返回 `FOLDER_CYCLE_DETECTED`
-6. 删除：`canvas folder delete --project <projectId> --folder <folderId>`。预设目录禁止删除；被引用时返回 `FOLDER_IN_USE` 并附引用方列表，必须先解除引用再重试
-7. 恢复软删目录：`canvas folder restore --project <projectId> --folder <folderId>`。超过 30 天回收窗口返回 `FOLDER_GONE`，无法恢复
-8. 跨项目或跨分集复制资产：`canvas folder copy-cross-project --project <sourceProjectId> --asset-id <assetId> --target-project <targetProjectId> --target-episode-id <episodeId> --target-folder-id <folderId>`。`--target-episode-id` 指定目标分集；省略 `--target-folder-id` 时复制到该分集的未分类。目标目录必须属于目标项目和目标分集。该命令只复制资产及版本，不复制目录结构；目标项目无写入权限时返回 `FOLDER_FORBIDDEN`
-
-### 批量操作原则
+## 按需读取
 
-- 单次命令只处理一个目录；批量场景按目录循环执行
-- 删除、移动、重命名互不依赖时可并发执行；存在依赖（先重命名再删除）必须按顺序串行
-- 操作前后用 `canvas folder list --project <projectId>` 回读验证结果是否生效
-- 任何 `404 / FOLDER_NOT_FOUND / FOLDER_PRESET_IMMUTABLE / FOLDER_IN_USE` 错误必须停下修正；被引用时必须先解除引用再重试
+`SKILL.md` 只保留路由和主流程。按实际进度逐阶段读取命中的资料；长任务可以先后读取多份，但不要在开始时一次加载全部：
 
-### 与现有 CLI 命令的关系
+- 项目创建、settings、批处理、目录或安全边界：[references/project-and-canvas.md](references/project-and-canvas.md)
+- 人物/场景/道具、拆镜、分镜图和生成前审计：[references/assets-and-storyboard.md](references/assets-and-storyboard.md)
+- MiniMax H3 视频、原生音频、遮挡转场、单镜与成片验收：[references/h3-video-delivery.md](references/h3-video-delivery.md)
+- 专业剧本、TTS 独立音频、Meme、Remotion 等专项流程：[references/special-workflows.md](references/special-workflows.md)
+- 精确参数和命令示例：[references/commands.md](references/commands.md) 或 `ai-short-studio <topic> --help`
+- 已知错误、恢复边界和历史兼容问题：[references/troubleshooting.md](references/troubleshooting.md)
 
-- `canvas folder *` 命令**独立于** `canvas asset *`。folder 操作对象是目录容器，asset 操作对象是容器内的资产条目
-- `canvas folder list` 是取得目标目录 ID 的唯一目录命令；`canvas asset list` 当前仅支持 `--kind` 与 `--search`，不接受目录筛选参数
-- 复制后用目标项目的 `canvas asset get <assetId>` 或网页资产目录回读；目录结构和回收站状态以 `canvas folder list` 为准
-
-## 关联资产参考图门禁（真假/版本/衍生）
-
-故事里存在“真/假”“原版/复制品”“同款不同状态”的成对道具、不同年龄同一人物、或母题相关的场景时，三视图和分镜图必须保持视觉血缘一致性，禁止各版本互不相干地自由发挥：
-
-1. **先生成基础版，再衍生对照版**。成对资源中先跑“真/原版/成年/主场景”的 turnaround/design 节点，让用户确认 selected version 后，再把它的 `image-resource` 作为参考图连到派生节点（假/复制品/童年/对照场景）的 turnaround/design 输入（若实时 schema 支持 reference 类 handle）或写入 prompt（“必须与已确认的 {基础版名称} 采用完全相同的器型、轮廓、尺寸、材质肌理和工艺细节，唯一允许差异为……”）。禁止两版同时独立生成后再期望图像模型自己保持一致。
-2. **差异显式枚举**。衍生版的 prompt 必须逐条列出“唯一允许差异”（例如：赝品只有两处印记、编号尾号不同、磨损略轻；童年形象必须共享眼型/鼻梁/脸型/发色），其余项一律写“与真品完全一致”。不能只写“与真品近似”。
-3. **禁止具象化母题元素**。当视觉圣经禁止宗教符号或特定图样、但剧本要求抽象呼应（例如“猎隼面向西方”的猎隼母题）时，道具/人物饰钮只能用**抽象剪影/勾形/几何轮廓**，prompt 必须明确“不是鸟类、没有眼睛/喙/羽毛/真实鸟头”，并把母题图样列在 negative 里，避免图像模型画成具象猛禽/人像/宗教纹样。
-4. **关联参考必须作为 reference 边入图**。基础版一旦选定，其 `image-resource` 必须作为 `reference` 连入所有衍生版的 turnaround/design，以及所有出现该道具（不论真假）的 `storyboard-image`。不能只在文字 prompt 里描述而不给参考图；文字描述对图像模型的约束力远低于参考图。
-5. **审查顺序：真→假→镜**。审计时先核对基础版三视图质量（造型、工艺、非宗教、非具象），再核对衍生版差异点是否完全符合 prompt 且与基础版轮廓一致，最后核对每镜的 reference 集里是否同时包含该镜出现版本的三视图。任一环节失败都回滚重跑，不得“视频阶段再修”。
-
-## 镜头级素材审计（必跑清单）
-
-在付费生成视频或交付前，必须对每一个 `storyboard-shot → storyboard-image` 配对执行以下机械审计并输出结构化结果；任何一项缺失都先补线再继续：
-
-1. **reference 来源完整**。枚举该 `storyboard-image` 的全部 `reference` 入边，反向 trace 到 `image-resource → turnaround/design → resource`，分别归类为人物/场景/道具/分镜图本身；与该镜 shot asset 里的 `characters`、`location`、以及从 description/video_prompt 扫出的道具名做集合比较，三类素材都应覆盖，不能有名字在镜中但没有 reference 图。注意同一角色可能存在 character-design 和 character-visual-design 两个 resource 节点，审计必须并集两个来源，不能因后者覆盖前者而误报缺失。
-2. **没有错边/串镜/跨类型边**。扫描画布全局，拒绝以下边：`prop-turnaround → location-image`、`*-turnaround → *-turnaround`（任何类型 turnaround 之间互连）、`image-resource → storyboard-image` 指向的分镜图与该图片资产镜号不符、`A→B` 和 `B→A` 同时存在形成环。
-3. **成对资源一致**。对每组成对资源（真/假道具、成年/童年人物），核对该镜引用的版本正确（赝品出镜镜必须引用赝品三视图，不能用真品的；童年镜必须引用童年资源）；若镜中真假同框，两个版本的 reference 都必须在。
-4. **结构字段兜底**。shot asset 的 `props` 字段缺失时，必须用关键词扫 description/video_prompt/photographyPlan 补出道具集合，不能因为字段空就判为无道具。关键词匹配优先长名/特异名（如“镇族金器拍卖赝品”优先于“金器”），避免把“真品”关键词误命中到赝品镜。
-5. **stale 节点清零**。画布上 `status=stale` 的节点数量必须为 0；不为 0 时列出并删除，保留可能被用户显式收藏的版本（需询问）。
-6. **资源文字设定必须贯穿到 shot/image**。`character-resource`、`location-resource`、`prop-resource` 三类文字设定的输出边必须对称：除连到对应 turnaround/design 节点和 `storyboard-breakdown` 外，还要按镜中实际出现连到 `storyboard-shot.<characters|locations|props>` 和 `storyboard-image.<characters|locations|props>`。不能只把道具连到 breakdown（会导致 shot/image 阶段看不到道具文字设定，只看到三视图参考图，编号/印记/文字提示词全部丢失）。审计时单独统计三类资源 → shot 的边数、三类资源 → image 的边数，三类分布必须一致，明显偏少（例如人物/场景全连而道具边数为 0）即判定为物化 bug，按幂等流程补线。
-7. **输出审计报告**。审计完成后给出：每镜实际 reference 清单、缺失项、错边列表、stale 数、成对资源一致性检查结果、以及待重跑的镜头列表；用户确认后再补边/重跑。
-
-审计脚本应一次性覆盖全部镜头，不要“抽样”或只看几镜；几十镜规模下全量审计成本仍很低，漏检代价高。
-
-## 上下镜连续性审计（镜头间一致性）
-
-在素材连线审计通过后、生成视频前，必须再做一次**按时间线顺序**的跨镜连续性检查。这一步独立于单镜素材审计，关注的是“上一镜结尾到下一镜开头”的视觉连续性：
-
-先执行 `canvas continuity analyze --project <projectId> --json`。该命令只读取镜头、lineage、模型能力与连线，不创建任务、不产生模型费用；`waiting-for-source-video` 只表示建议的尾帧链尚不可建立，不阻止后镜独立生成；`readyFixes` 表示用户确认后可用 `--apply-ready` 免费补建提帧节点与连线。视频完成后仍需按本节清单复检真实画面。
-
-1. **检查清单**。按 shotKey 顺序逐镜对相邻两镜核对：
-   - **人物身份与位置**：上一镜的主要人物下一镜是否还在；越肩/反打镜头的前景人物是否与上个对话方匹配；同一场景多镜之间服装/妆容/干湿/血迹等是否一致。
-   - **道具状态与位置**：上一镜刚出现/移动/封存的道具下一镜位置是否连贯（例：镜 6 手刚打开胸针背板，镜 7 必须是同一胸针压痕；镜 9 金沙飘向档案盒，镜 10 文件叠化要能看出“异能→纸本”的视觉桥接）。
-   - **光影与色调**：同一场景内相邻镜的色温、光源方向必须一致（暖金权力空间保持暖金侧逆光、冷蓝档案空间保持冷蓝顶侧光，跨场景转场要有硬切或黑场）；段尾镜要为下一段开头做光线过渡（例：修复室最后一镜努尔抬眼、右侧带暖金反光，接暖金拍卖厅全景）。
-   - **动势与视线**：上一镜角色的动作方向/视线方向，下一镜是否承接；跳切、匹配切需要视觉重心在屏幕同一位置或动作方向一致；竖屏 9:16 多镜要优先沿竖轴设计运动（向下推、向上拉、垂直叠化），避免横向无动机跳。
-   - **景别呼吸节奏**：不能连续多镜同景别无动机切换；关键钩子前要留一镜短时长（≤2s）做屏息，长举证镜可给 4–6s。
-   - **叙事桥接**：时间/空间跳跃必须有可识别的桥（黑场、声音、视线引导、动作匹配），不能让观众猜“人怎么到那里了”。
-2. **极端特写/空镜/物证镜也必须人物 reference**。`characters` 字段为空但画面里会露出手、肩、眼等身体部分时（例如极端特写胸针压痕但努尔手指入镜、微距金器但白手套入镜），**必须把对应人物的 image-resource 作为 reference 连入**，否则该身体部位可能被画成第三人称或出现手指数量错误。
-3. **关联镜头互相作为参考**。对于成对/多镜动作（匹配切、叠化、连续推轨、正反打），除了各自的人物/场景/道具 reference，还应把前一镜和后一镜的 `storyboard-image` 输出也作为 `reference` 接进来（双向或单向视剪辑方向），让图像模型在镜间保持构图、光线、道具位置的连续。
-4. **已知模型先验 bias 必须在 video 阶段二次约束**。图像模型对面具、号牌数字或动物意象等词有强先验；这些要在 video-generate 的 prompt 里二次写出明确的形状与禁止项，不能依赖分镜图阶段的约束。
-5. **时序问题必须报给用户**。发现剧本/分镜顺序本身的时序错位（例如某段镜组发生时间早于前一段却排在后面）、或人物/道具位置无法通过剪辑弥补的跳变时，不能自行改镜，必须列出来让用户决定调镜序还是补过渡镜。
-
-## 分镜逻辑审计（内容与匹配）
-
-素材连线和连续性审计都通过后、进入视频生成前，必须对每个 shot 的**叙事内容、文字匹配、资源引用正确性**做一次逻辑审计，专门抓“看起来连线都齐但其实引错了/引多了/引少了”的问题：
-
-1. **对照叙事期望，扫掉“关键词误命中”连线**。用关键词匹配 props/characters 时必然有误命中，必须逐镜人工或半人工复核：
-   - **场景特异性优先于通用关键词**。“断环标记”同时出现在复检权限平板（会议室）和普通竞拍牌（电梯），不能因为“断环”二字就把两个道具都连上。要根据 location 和其他关键词（平板 vs 号牌、会议室 vs 电梯）判定。
-   - **真假版本不能互串**。真品关键词（“三处印记/尾号04”）命中时，不能把赝品三视图连上；反之亦然。镜中明确写“方形金质砝码/拍品”时连赝品，写“原册/真品三处印记”时连真品。
-   - **跨段同名/相似实体不能互串**。“金器被调换”描述里的“金器”是回忆里父亲核对的真/假两件，不是展厅展柜里的那一件，不能因为出现“金器”二字就连赝品三视图。
-   - **身体/戒指/人物不等于对应资源**。“她左手猎隼戒指”不是一个独立道具，不要误连其他戒指资源；“档案袋/文件/报告/报纸”等未在 prop-resource 中定义的现场物件，不要强行映射到已定义道具。
-   - **空镜/黑场/片名镜**（纯黑、字幕、全片头等）没有任何道具，也不应有 location 的实际画面，不能连任何 reference 或道具/场景；连了就是误命中，必须删除。
-2. **检查龙套/临时角色**。shot 的 `characters` 字段里出现未在 character-resource 中定义的角色（例如拍卖师、工作人员、路人、独立鉴定人）时：
-   - 不强行创建完整角色资源（三视图/turnaround 成本高），但必须在 storyboard-image 的 prompt/config 里写明“无名龙套、正装、海湾阿拉伯面孔、非主角脸、无特殊标识”，避免图像模型用主角脸凑数。
-   - 龙套镜不应有 `characters` 边指向主角的 character-resource。
-3. **多版本角色（成年/童年、年轻/老年）严格按景别连**。同一角色的不同年龄段（如努尔 vs 年幼努尔）是两个独立 resource：
-   - 成年主角的近景/中景/特写只连成年版，不能因为“努尔”关键词命中就把童年版也连上（会让模型在成年镜画出儿童脸）。
-   - 明确的童年/回忆镜（人物表列“年幼努尔”、action 写明“蹲下身对小努尔说话”）才连童年版。
-   - 过渡镜/混合镜（匹配剪辑、跨时空同框）两个版本都要连。
-4. **“物证/文件/纸页叠化”类镜头不能引错实体**。交接簿、复检许可、旧编号页、现场报告等临时纸张如果不是已定义 prop，不要为它们连上无关的实体道具（例如平板、藏册）。纸页叠化是蒙太奇语言，不是单个道具特写。
-5. **逐镜打印审计表**。对几十镜规模的项目，输出一张“镜号 / 时长 / 角色（plan）/ 道具（plan）/ 场景 / 实际 wired chars / 实际 wired props / 实际 refs 数 / 问题”表，人工扫一遍：plan 和 wired 不一致的、wired 比 plan 多出奇怪条目、黑场镜仍有 props/location 连线的、龙套镜引用了主角资源的，全部列出并修。
-6. **视频阶段 negative 清单**。分镜图阶段修不掉的图像模型先验（面具买家画眼罩、竞拍牌画数字、隼画成具象猛禽、证章上出现中文字等），整理成逐镜 negative prompt 清单，在 video-generate 节点 config.prompt 里逐条显式禁止，不要寄希望于视频模型自己纠正。
-7. **时长/节奏校验**。核对各段总时长与剧本秒数的偏差（例如 39+45+39=123s 对 120s 剧本，偏差在视频剪辑桶内可消化）；单镜过长过短、或单镜承担三段以上动作（匹配剪辑超过 3 段）的，提示用户可能需要拆镜或延长。
-
-逻辑审计发现的连线错误必须精确删除（删 edge ID，不动正确边）；不要图省事把整个节点或全部边清空重连。每次删边/加边后必须重新读画布、重复同一份审计表直到 wired 集合等于期望集合。
-
-## 生成后自我审计
-
-每批生成完成后必须主动审计，不等待用户指出问题，也不能用 `task wait` 成功代替审计：
-
-1. 重新读取任务、画布、节点、连线和资产，确认所有任务处于成功终态，预期产物真实存在，selected version、输入引用和自动创建的下游节点没有错位、遗漏或重复；分镜图片还必须重新执行“分镜素材连线门禁”和“分镜逻辑审计”，确认任务实际使用的上游版本包含全部期望参考、且没有误连的资源。
-2. 对照执行前确认值核对节点最终有效配置：视觉素材默认或显式画幅正确，视频生成时长仍在当前模型实时 `durationOptions` 的合法值中，模型、分辨率、质量、布局和格数没有被继承值意外覆盖。
-3. 实际查看图片/视频/音频预览；核对人物身份、场景、道具、动作顺序、构图、连续性，以及黑帧、拉伸、裁切、破音、空结果等明显缺陷。能从资产元数据取得的画幅和时长必须与配置交叉核对。
-4. 输出简短审计结论，逐项列出通过项、缺陷、失败项和未决项。只读即可确认的问题直接补查；涉及再次付费生成、改选版本或覆盖用户内容时先展示问题并取得确认。自我审计不能替代用户选版和阶段确认。
-
-## TTS、声音设计与声音克隆
-
-语音交付使用 `audio`、`voice-design`、`voice-clone` 和 `tts` 节点，并以服务端实时节点目录为准：
-
-1. 先执行 `canvas settings get` 和 `canvas node types --json`，确认最终生效的 `audioModel`、`tts.configSchema`、`voice-design.configSchema`、`voice-clone.configSchema` 及端口。不要根据百炼网页文档猜测当前服务已支持的字段或音色。
-2. `tts` 的文本通过 `text` 输入端口或 `config.text` 提供；音色通过 `tts.voice` 连线或 `config.voice` 提供。连线音色优先于手填值，并使任务采用该克隆产物记录的精确 CosyVoice 目标模型。执行前必须回读画布，确认文本、音色和最终 `audioModel` 一致。
-3. `cosyvoice-v3.5-plus` 与 `cosyvoice-v3.5-flash` 只接受声音设计或声音克隆生成的同型号音色 ID，不接受 `longxiaochun`、`longxiaochun_v3` 等系统预置音色名，也不能混用其他 CosyVoice 型号的 ID。违反该约束会在供应商请求前返回 `COSYVOICE_TTS_CUSTOM_VOICE_REQUIRED:<model>`；不要通过反复更换预置音色重试。
-4. 需要设计声音时创建 `voice-design`，通过 `prompt` 输入或配置提供声音描述，并按实时 schema 确认 `previewText`、`prefix`、`targetModel` 和 `languageHints`。运行后取得真实任务 ID 并执行 `task wait`；成功后刷新画布，连接 `voice-design.voice → tts.voice`。
-5. 需要克隆时，先创建或绑定含已授权参考音频的 `audio` 节点，再创建 `voice-clone`，连接 `audio.audio → voice-clone.audio`。按实时 schema 确认 `prefix`、`targetModel`、`languageHints`、`maxPromptAudioLength` 和 `enablePreprocess`；`prefix` 只含字母和数字且不超过 10 位，参考音频截取范围为 3～30 秒。声音克隆会创建远端资源，任务不自动重试；失败时先检查输入，不得盲目重复执行。
-6. 运行 `voice-clone` 后取得真实任务 ID 并执行 `task wait`。成功后刷新画布，确认产物包含非空音色 ID 和与 `targetModel` 对应的模型键，再连接 `voice-clone.voice → tts.voice`。不得预先猜测音色 ID，也不要把任务 ID、节点 ID 或预置音色名当作音色 ID。
-7. CosyVoice `tts` 只写实时 schema 声明的 `languageHints`、`format`、`sampleRate`、`volume`、`cosyRate`、`pitch` 和 `instruction`。默认值通常为 WAV、24000 Hz、音量 50、语速 1、音调 1；最终仍以实时 schema 为准。`instruction` 只用于 schema 和有效模型共同允许的型号，最多 100 个计权字符，汉字按 2 个计算。非 CosyVoice 模型使用 `rate`，不得同时套用 CosyVoice 参数。
-8. 运行 `tts` 后必须等待任务终态并刷新资产，实际试听音频，检查空音频、破音、语言、音色、语速、音调和时长。任务失败时先按错误码修正：`*_VOICE_ID_REQUIRED` 表示音色缺失，`COSYVOICE_TTS_CUSTOM_VOICE_REQUIRED:<model>` 表示 v3.5 音色来源或型号错误，`COSYVOICE_TTS_INSTRUCTION_TOO_LONG` 表示声音指令超限，`COSYVOICE_TTS_LANGUAGE_HINT_UNSUPPORTED:<language>` 表示语言提示不兼容；只有供应商临时错误才按任务的 `retryable` 判断是否重试。
-
-## Meme 专属流程门禁
-
-用户要求制作 Meme 视频时，默认且标准的成片链路必须使用 `meme-scene-analysis` → `meme-material-search` → `cat-meme-video` 专属节点。禁止静默使用 `storyboard-breakdown`、`storyboard-image`、`storyboard-video-prompt` 或通用 `video-generate` 代替，也不得因为项目配置中存在 Seedance 等 `videoModel` 就调用视频生成模型。只有用户明确要求生成式视频路线，并在得知画风、费用和流程变化后再次确认，才可改走通用视频生成。
-
-标准连线为 `text.text → meme-scene-analysis.story`；分析成功后刷新画布，复用自动创建的 `meme-material-search` 和计划资源；素材检索成功后再次刷新，复用自动创建的 `cat-meme-video` 和素材包资源。最终应包含素材包资源 `.text → cat-meme-video.materials`、原故事 `.text → cat-meme-video.story`，以及计划资源 `.text → cat-meme-video.plan`。不得手工重复创建自动下游节点或资源。`cat-meme-video` 使用分析模型、内置猫素材/背景/BGM 与 FFmpeg 合成，输出由节点自身 `aspectRatio` 和 `resolution` 决定，不使用项目 `videoModel` 或通用 `videoResolution` 触发 Seedance。
-
-即使用户明确不使用外部素材，也必须运行 `meme-material-search`：Pexels 可保持关闭，节点仍会解析内置背景和内置道具，并对库外必显道具调用图片模型生成。运行后检查素材包的缺失项；每个 `mustShow` 道具必须存在当前可用素材或可复用的同名合格素材，才可运行视频节点。不要为了绕过缺失道具而擅自删改剧情。
-
-遇到 `CAT_MEME_REQUIRED_PROP_MISSING` 时回到素材检索补齐道具；遇到 `CAT_MEME_DISPLAY_CONTENT_REQUIRED` 时修复场景计划中的屏幕内容；遇到 `CAT_MEME_FFMPEG_FAILED` 时报告渲染器错误并在修复或部署后重试。任何失败都不得在未获用户确认时自动切换到通用 `video-generate`。`cat-meme-video` 的 `config` 仍需按实时 schema 确认 `aspectRatio`（`1:1`、`9:16` 或 `16:9`）与 `resolution`（`720p` 或 `1080p`）。
-
-详细命令按需读取 [references/commands.md](references/commands.md)，或运行 `ai-short-studio <topic> --help`。
-
-## AI 剪辑联动
-
-**REQUIRED SUB-SKILL:** Use remotion-best-practices
-
-任务涉及剪辑设计或实现、Remotion composition、时间线、裁切、字幕、转场、音频编排或渲染时，必须先加载并遵循 `remotion-best-practices`，再把 VVICAT 已确认的视频、图片和音频资产用于剪辑。该 Skill 不可用时先请用户安装，不得凭零散的 Remotion 知识自行设计剪辑流程；纯素材生成无需加载。
-
-## 无限画布成片与交付
+## 核心原则
 
-- 开始或恢复操作时先读取最新画布、settings 和节点 schema；用 `canvas node edit-shot` 编辑 `storyboard-shot`，用 `canvas node edit-resource` 编辑具有稳定 `operation/resourceKey/resourceType` 的剧本、人物、人物视觉、场景、子场景或道具资源。两类编辑都基于当前 `selectedOutputVersionId` 追加不可变版本，不得覆盖历史版本；资源编辑只替换完整父文档中的目标实体，兄弟节点保持原选版。
-- 在 `canvas settings get` 后让用户确认 `outputLanguage` 为自动、`zh` 或 `en`；变化只把拆镜、视频提示词、TTS 和视频节点标为 stale，不删除资产、不清除选版、不自动重跑。试听原生配音并核对语言；节点显式 `languageHints` 优先。
-- 戒指等实体必须进入镜头 `props`。肢体仅在剧情需要时出现，并在画面中可见归属于人物；纯道具镜头不得凭空增加手、手套、人物或 UI。上游变化后只按 stale 链路重跑，历史版本继续保留。
-- 视频输入按模型实时能力选择严格首尾帧、普通首帧图生视频或图片参考；模型明确声明多模态参考上限时，可把视频、音频素材分别连接到 `reference-videos`、`reference-audios`。参考音频不能作为唯一媒体输入；纯文本指不连接任何媒体，不是 audio-only。RunningHub MiniMax H3 允许纯文本生成，参考图、视频、独立音频分别为 0–9、0–2、0–2，实时 `durationOptions` 为 5–15 秒的每个整数，1–4 秒由服务端归一为 5 秒。多模态参考不能与首尾帧混用。新分镜以规划产物的 `continuity` 为准；`previous-tail` 只记录需求，需要用户确认后显式执行 `--apply-ready` 或手动连线，执行视频仍需用户确认。
-- 原始视频交付只下载每镜已选中的 MP4，按镜号命名 `S001.mp4`、`S002.mp4`……；字幕在编排/交付层单独生成，不烧录进原始视频。`manifest` 每行至少记录 `shotNumber`、`nodeId`、`assetId`、`versionId`、`fileName`，不得混入分镜图、音频中间件或烧录字幕版本。
+把 `ai-short-studio` 当作机器可读的远程控制接口。目标、素材含义、平台、语言、画幅、时长、风格、人物、场景、道具、模型、实时 schema、候选版本、付费范围或覆盖影响存在未知、缺失或矛盾时，合并询问最少必要问题；得到答复前只做只读检查。不得用示例值替用户作创作决定。
 
-RunningHub MiniMax H3 的实时 `aspectRatio` 只有 16:9、9:16，`resolution` 只有 480p、720p、1K、2K，默认为 1K。
+优先使用一次 `canvas inspect` 聚合查询。同阶段可合并的 settings、节点、连线、执行和等待分别使用 `canvas settings set --file`、`canvas apply`、`canvas node update-many`、一次 `canvas node run` 和一次 `task wait`；默认并发 4、上限 16，不并发启动多个 CLI 进程。409 重读并确认，401/403、schema、业务门禁和付费错误必须停下修正。
 
-## 安全边界
+## 主流程
 
-- 不把密码、access token、refresh token 或 API Key 放入参数、日志、Skill 或仓库。
-- refresh token 只保存在系统钥匙串；CLI 自动维护权限为 `0600` 的短期 access-token session 缓存和跨进程刷新锁。不要手工读取、复制或删除缓存来规避认证；正常退出使用 `auth logout`，CI 使用秘密管理器注入 `VVICAT_ACCESS_TOKEN`。批量操作保持单进程，避免无意义地竞争钥匙串。
-- 密码登录使用 `printf`/管道以外的安全 stdin 来源；自动化环境使用秘密管理器注入 stdin。
-- 邮箱注册同样只通过交互式隐藏输入或安全 stdin 传递密码，不把密码放入命令参数、日志或仓库。
-- 用户已在当前会话明确提供密码时，可将其直接写入正在等待的交互式隐藏密码提示；不得复述密码、拼入 shell 命令、写入临时文件或跨会话保存。
-- 注册环境通过 profile `baseUrl` 区分；Supabase Redirect URLs 应预先允许各环境，禁止为单次本地注册临时修改全局 Site URL。
-- `config get` 不返回全局 Provider 密钥；返回的模型已经过管理员发布和可用性校验，预检不得要求用户持有 Provider 密钥。
-- `project provider get` 只返回配置状态。`project provider set` 的 JSON 必须来自安全 stdin 或不入库的临时秘密文件，禁止把 Key 写进命令参数、仓库文件或会回显的 shell 历史。
-- 删除用户既有项目、覆盖完整画布或修改模型配置前，先明确目标和影响；没有授权就停在读取或生成变更计划。初始化检查中按实时 options 自动补齐缺失的当前账户 `capabilityDefaults` 已获本 Skill 授权，不属于需要再次询问的模型切换。
-- `canvas apply` 只用于节点、连线、删除、视口等低层图补丁，不能代替 `canvas settings set`。同阶段有多个图变更时优先一次批量提交；已有画布快照时必须传 `--canvas-id` 和 `--expected-version`，不让 CLI 再预读全图。批量失败按“核心原则”分类处理，不能通过逐条重试绕过权限、schema、业务门禁或付费确认。遇到 409 才重新读取、合并并确认后重试。项目配置遇到 409 时也必须重新读取和确认。
-- 编辑 `storyboard-shot` 必须使用 `canvas node edit-shot`。完整 JSON 可包含 `photographyPlan` 对象和 `actingNotes` 对象或数组；它们与其他镜头字段一起追加不可变版本、固定选版并把下游标记为 stale。命令不允许修改 `shotKey`、`shotIndex` 或来源身份；409 后重新读取镜头版本再确认，不能覆盖历史版本。
-- 编辑结构化生成资源必须使用 `canvas node edit-resource`，不得用 `canvas node update` 或 `canvas apply` 改写服务端 artifact。名称、资源键、ID 和所属关系等身份字段不可修改；缺少稳定 `operation/resourceKey/resourceType` 的旧节点保持只读。资源版本写入具有独立并发基线，409 后重新读取画布与当前选版并确认；兄弟资源节点不得被同步切版。
-- 手工提取视频首帧或尾帧时先从实时目录确认 `video-frame-extract`，配置 `{"position":"first"}` 或 `{"position":"last"}`。新规划镜头的连续拓扑由服务端自动协调；没有 `continuity` 的历史镜头仍可使用只读启发式分析。创建连续拓扑不执行模型、不付费，运行视频前仍须确认。
+1. **预检**：运行 `preflight --json`；更新后重跑。再读取 `config get`、实时 `canvas node types` 和目标项目。`skill status --target codex` 非 current 时先询问再更新，禁止强制覆盖用户修改。
+2. **项目配置门禁**：读取 `canvas settings get`，展示 `currentValue`、`effectiveValue`、`source`、建议值和实时 options。确认 `aspectRatio`、`artStyle`、`visualBible`、`storyboardImageType`、`outputLanguage`、`analysisModel`、`imageModel`、`imageResolution`、`imageQuality` 和 `videoResolution`，以及 `editModel`、`videoModel`、`videoPromptType`、`audioModel`；`$ART_STYLE_ID` 必须解析实时 `option.value`。标准创作门禁使用 `--file settings.json` 原子写入并携带 `expectedVersion`，回读一致前不得创建或运行付费节点。节点确需不同参数时才按实时能力覆盖。
+3. **剧本和目标集**：已有专业剧本时直接复用，不得重复执行 `novel-to-script`。需要创作微短剧时，**REQUIRED SUB-SKILL: Use short-drama**，随后 **REQUIRED SUB-SKILL: Use humanizer** 去除 AI 味；不得改动已经确认的剧情事实，润色后回到 short-drama 复核。确认目标集数后，只生产该集实际需要的资产。
+4. **资产门禁**：先完成人物、场景、道具及其派生版本，展示真实预览并确认 selected version。执行资产—剧情匹配审计；缺失、多余、错版、stale、错边未清零时拆镜前门禁失败。
+5. **拆镜和分镜图**：拆镜前按 [语言匹配门禁](references/assets-and-storyboard.md#拆镜语言匹配门禁) 核对源剧本语言、交付语言、项目 `outputLanguage` 和节点 `targetLanguage`，不一致时禁止执行。把该集剧本与全部确认资产连接到 `storyboard-breakdown`，复用服务端自动创建的 `storyboard-shot` / `storyboard-image`。完成后逐镜执行语言与镜头质量审计且不抽样；P0/P1 未清零不得继续。分镜图生成前按实时 schema 确认画幅、布局、格数和费用，生成后展示真实结果并选版。
+6. **视频规划**：视频生成前依次完成素材连线、镜头逻辑和上下镜连续性审计。读取实时 `durationOptions`；只有选项恰为 5、10、15 秒时才按这三档向上取整。RunningHub MiniMax H3 支持纯文本和 0–9 张参考图、0–2 个参考视频、0–2 个参考音频，5–15 秒逐秒可选，1–4 秒归一为 5 秒；参考视频只传画面。画幅为 16:9 / 9:16，分辨率为 480p / 720p / 1K / 2K。
+7. **H3 生成门禁**：`videoModel` 为 `comfly::minimax-h3` 或 `runninghub::minimax-h3-reference-to-video` 时，同次设置 `videoPromptType: "h3"`。仅有效的节点 `promptType` 可覆盖项目值；旧 `seedance` 覆盖必须清除并回读，否则不得执行视频提示词或视频生成。编写或改写 H3 提示词时，**REQUIRED SUB-SKILL: Use h3-prompt-writing**；进入生成前必须读取 [H3 成片规则](references/h3-video-delivery.md)。
+8. **逐镜后验**：每个视频镜头完成后实际看画面、听完整音轨，并完成视觉、音频、转场、字幕四项验收。任一 P0/P1 失败只修复并重跑受影响镜头；未通过不得进入成片剪辑。
+9. **成片和交付**：剪辑只使用通过验收的 selected 版本。完成轻微重叠拼接、字幕和必要技术处理后，从头到尾观看成片并执行完整成片验收；未通过不得声称完成。原始视频按 `selectedOutputVersionId` 下载，字幕独立保存，`manifest` 记录镜号、节点、资产、版本和文件名。
 
-## 示例
+## 强制分流
 
-```bash
-ai-short-studio canvas node types --json
-ai-short-studio project create --name "agent-draft-20260722" --json
-ai-short-studio canvas settings get --project "$PROJECT_ID" --json
-ai-short-studio canvas settings set --project "$PROJECT_ID" --field aspectRatio --value 9:16 --json
-ai-short-studio canvas settings set --project "$PROJECT_ID" --field artStyle --value "$ART_STYLE_ID" --json
-ai-short-studio canvas settings set --project "$PROJECT_ID" --field imageResolution --value 2K --json
-ai-short-studio canvas settings set --project "$PROJECT_ID" --file settings.json --json
-ai-short-studio canvas node add text --project "$PROJECT_ID" --config ./node.json --json
-ai-short-studio canvas inspect --project "$PROJECT_ID" --include summary --include nodes --include edges --include assets --include settings --include node-types --json
-ai-short-studio canvas inspect --project "$PROJECT_ID" --kind storyboard-image --status stale --json
-ai-short-studio canvas node update "$NODE_ID" --project "$PROJECT_ID" --set 'gridSize=9' --unset legacyField --json
-ai-short-studio canvas node update-many --project "$PROJECT_ID" --file updates.json --json
-ai-short-studio canvas node run --project "$PROJECT_ID" --node "$NODE_1" --node "$NODE_2" --concurrency 4 --wait --json
-ai-short-studio task wait --task "$TASK_1" --task "$TASK_2" --concurrency 4 --json
-```
+- H3 成片中的人物说话、旁白、环境音和 BGM 全部由 H3 原生生成；不得用 `voice-design`、`voice-clone`、`tts` 或其他外部 TTS 覆盖。独立音频交付才读取专项 TTS 流程。
+- Meme 默认且标准链路是 `meme-scene-analysis → meme-material-search → cat-meme-video`，禁止静默切换通用视频生成；`CAT_MEME_REQUIRED_PROP_MISSING` 必须返回素材检索修复。
+- 涉及剪辑、字幕、转场、音频编排或渲染时，**REQUIRED SUB-SKILL: Use remotion-best-practices**。
+- 编辑镜头用 `canvas node edit-shot`，编辑结构化资源用 `canvas node edit-resource`，均追加不可变版本。`outputLanguage` 变化只标记下游 stale；手工首尾帧使用 `video-frame-extract`。
 
-从 JSON 输出中取得真实 ID；示例中的环境变量仅表示调用方已安全解析并保存结果。
+## 安全与完成条件
 
-## 常见错误
+不把密码、Token 或 API Key 写入参数、日志、Skill 或仓库。删除项目、覆盖画布、切换模型、重新付费生成或覆盖用户选版前，必须明确目标和影响并取得授权。临时项目在所有结束路径清理；既有项目不得擅自删除。
 
-- 节点类型写死：先读 `canvas node types`，服务端目录才是事实来源。
-- 配置不全仍继续：先做初始化检查；仅缺可确定的账户 `capabilityDefaults` 时自动补齐并验证，模型、项目或用户意图仍有缺口时再询问。
-- 把项目配置写到错误位置：画幅、画风、视觉圣经、故事版类型、模型、默认图片分辨率/质量和默认视频分辨率必须通过 `canvas settings set` 写入；`canvas apply`、账户级 `config set`、项目描述或节点 prompt/config 都不能替代。
-- 写完 settings 就创建节点：必须 `canvas settings get` 回读并确认 `currentValue`、`effectiveValue`、`source` 和最终模型；失败或冲突时停在配置阶段，不触发付费任务。
-- CLI 有更新仍用旧进程继续：更新后必须重跑 preflight。
-- 预检只缺账户能力默认值就停止反馈：先按初始化检查自动补齐可确定的 `capabilityDefaults`、回读并重跑 preflight；只有无法安全确定或写入失败时才报告。
-- 未指定分镜布局却推荐故事版：默认推荐 `grid` 分镜板；`storyboard` 只在用户明确选择时使用。
-- 注册成功就假定已登录：`confirmationRequired: true` 表示需要先完成邮件验证，再执行 `auth login`。
-- 自动创建的下游节点重复添加：任务完成后先刷新画布并复用真实节点 ID。
-- 多项画布写操作逐条执行：同一阶段可合并的节点、连线和删除应先用一次 `canvas apply`；只有批量入口不可用或合法批量请求仍因批量粒度失败时才回退单条命令，不能把权限、schema 或业务错误当作回退理由。
-- 为常见查询写临时脚本：节点、边、资产、设置、目录、状态和资源来源审计先用一次 `canvas inspect` 与过滤参数；只有命令无法表达时才写临时脚本，并在结束后清理。
-- 为每个节点启动一个 CLI 进程：互不依赖的执行和等待分别用一个 `canvas node run --node …` 或 `task wait --task …` 批次；不要用 shell 并发制造 Keychain 竞争。
-- 为改一个配置字段发送完整 config：单节点使用 `canvas node update --set/--unset`，多节点使用 `update-many`；结构化资源内容仍走 `edit-resource`/`edit-shot`。
-- 素材未完成或未连线就拆分镜：人物、场景、道具等相关素材必须任务成功、已确认 selected version，并逐项连接到 `storyboard-breakdown` 对应输入后才能执行。
-- 未展示产物就继续：生成分镜图前展示并确认素材，生成视频前展示并确认分镜图；只报告 ID 或路径不能代替预览与用户确认。
-- 所有镜头沿用项目格数却声称已动态配置：实时 schema 提供 `gridSize` 时，必须展示并确认逐镜难度建议，再把数值写入对应节点；只有旧服务未暴露字段时才回退到项目格数，未另行确认时为 6 格。
-- 视觉素材混用不同默认画幅：用户未指定时，角色、道具、场景/背景和分镜图统一使用 `16:9`；实时 schema 支持时显式写入节点，避免继承项目中的其他画幅。
-- 按固定档位套用所有视频模型：先读实时 `durationOptions`；只有当前模型仅提供 5/10/15 秒时，才向上取这三档，并保留原目标时长供剪辑裁切。
-- 多个三视图候选被拼成一张图：每个候选必须使用独立输入和独立三视图节点生成；`count` 产生的多个版本也必须保持为独立图片，不能拼接展示。
-- 涉及剪辑却自行设计：时间线、字幕、转场、音频编排或渲染必须先使用 `remotion-best-practices`。
-- 只检查任务创建响应：必须 `task wait` 并检查终态和错误字段。
-- 任务成功就直接交付：每批生成后必须重新读取状态与资产、核对配置并实际查看产物，输出审计结论后才能继续。
-- 下载列表中的任意 URL：先确认资产的 selected version，再下载。
-- 测试创建资源但未清理：用调用方的 `finally`/trap 删除唯一前缀项目。
-- 道具三视图未连入分镜图：仅把 `prop-resource` 文字连到 `storyboard-breakdown` 不够；必须让每个 `prop-turnaround` 产出的 `image-resource`（三视图 PNG）按镜实际出现连到对应 `storyboard-image.reference`。人物/场景会自动物化连线，道具链路当前（0.1.26）有缺漏：连线门禁必须同时数三类素材（人物/场景/道具）从各自 turnaround/image 节点走到 storyboard-image reference 的边数；道具边数显著少于人物/场景时即物化 bug，按本文“分镜素材连线门禁”补齐。
-- 误以为道具资源 name 写得克制 = 分镜里就会克制：`prop-resource` 文字 description 被直接喂给图像模型，`无装饰/朴素/光面/克制到无特征` 这类词会让道具画成无记忆点的几何体（例如方形金器变砖块/花瓶/随机金色器物）。文字应描述具体但不奢华的工艺语言（手工锤纹、抽象几何线刻、小型器耳/饰钮等），明确“不是光面金属块”；视觉圣经的“克制奢华”不等于“无装饰”。在 prop-turnaround 提示词里必须写清器型、可识别的工艺细节和家族特征（如呼应母题的小型饰钮），否则关键道具的连续性和辨认度会崩溃。
-- 把 breakdown output 的 props 字段当作一定存在：shot JSON 可能只有 `characters`/`location` 而缺 `props` 字段。不能因为结构字段缺失就判定道具没出现；必须同时扫 `description`、`video_prompt` 和 `photographyPlan` 中出现的道具关键词（金器/胸针/平板/藏册/证章/牌/记录/报道等）来建立镜头→道具映射，再据此补 reference 边。匹配唯一后再写边；简称、同名、真假版本无法唯一映射时询问用户。
-- 道具 turnaround 串错链路：检查 `prop-turnaround` 不得有到 `location-image`、其他 `prop-turnaround` 或非图片资源的出边；发现跨类型/互连边立即删除。修复只删精确 edge ID，不影响其他连线。
-- CosyVoice v3.5-plus 用 v2 预置音色名：`cosyvoice-v3.5-plus` 不接受 `longxiaochun/longshu/longshuo` 等 v2 预置名，传入会返回 `COSYVOICE_TTS_FAILED(400): InvalidParameter`；空 voice 会返回 `BAILIAN_VOICE_ID_REQUIRED`。v3.5-plus 只接受通过 `voice-design` 或 `voice-clone` 生成的同型号音色 ID（形如 `cosyvoice-v3.5-plus-<prefix>-...`）；不要反复换预置名重试。`instruction` 长度按计权字符计（CJK 算 2、ASCII 算 1），v3.5-plus 上限 100，超长返回 `COSYVOICE_TTS_INSTRUCTION_TOO_LONG`。
-- 并发跑多个 storyboard-breakdown 后误以为资产互换：任务终态成功后，必须按 shot 节点的 `parentAssetId` 和 `producerNodeId` 重新核对产出归属，不能按提交顺序假设；如果某段镜头内容与接入的 screenplay 时段不符，检查是否有历史旧版本/旧资产仍被引用，先清理 stale 节点再重跑。
-- 真假/衍生道具同时独立生成：成对资源必须先生成并确认基础版（真/原版/成年/主场景），再以它的 image-resource 为 reference 跑派生版（假/复制/童年/对照场景），prompt 显式枚举“唯一允许差异”；禁止两版并行独立生成后靠文字 prompt 保持一致。
-- 母题元素被画成具象物：剧本里的隐喻（如猎隼、家族纹章）在视觉圣经里通常要求“抽象几何、非宗教、非具象”，但图像模型会把“隼/鹰/鸟”强先验画成具象猛禽头/羽毛/眼睛。prompt 里必须避免动物名词，改用形状描述（“向上勾起的逗号形/弯勾饰片”）并在 negative 中列“眼睛/喙/羽毛/真实鸟头”。
-- 同名/多版本资源漏审：同一角色可能存在 character-design 与 character-visual-design 两个 resource，审计 reference 覆盖时必须并集所有同名资源的图片产物，不能只看一个就报“缺失”。
-- 镜头级素材审计靠抽样：几十镜量级下也必须全量审计每个 shot 的 reference 集与镜中素材对比，不能抽样或只抽查前几镜；脚本化比对三类素材（人物/场景/道具）reference 边数应不低于镜中素材出现次数。
-- 关键词匹配没做场景/真假消歧：道具“断环标记”同时出现在平板和竞拍牌上、“金器”同时指真品和赝品、“努尔”同时指成年和童年版本，不能靠单个关键词命中就连线；必须结合 location（会议室vs电梯）、真假关键词（三印/04 vs 两印/07）、景别和叙事上下文判定，否则会出现“平板镜连竞拍牌”“成年镜连童年资源”等跨串。
-- 黑场/字幕/空镜连了道具或场景：纯黑开场、静默黑场、片名落版、全声音无画面等镜，不能连任何 image-resource/prop/location，否则模型会强行画东西破坏空镜。
-- 龙套镜引用了主角资源：拍卖师、工作人员、路人、独立鉴定人等无名角色如果没有独立 character-resource，要在 storyboard-image 的 prompt 里写明“非主角脸”，不能让角色边指向努尔/拉希德/奥马尔的三视图，否则会把龙套画成主角的脸。
-- 纸本叠化/交接簿/报告等临时物件强绑到实体道具：蒙太奇里的纸页、文件、报告、现场封袋如果不是预定义道具，不要误连平板/藏册等实体；这些是程序戏不是具体道具。
-- 删错边用“全清重连”代替精确删 edge ID：发现误连边时要精确删具体 edge ID，不要批量清空相关节点连线或重建节点；重连会丢失用户手工调整过的连线，且增加二次错误风险。
-- 改了道具/人物/场景 turnaround 后忘了旧 description 会打架：如果在分镜图生成后更新了道具设定（例如把“方形金质砝码”改成“带盖礼器+勾形饰钮”），`storyboard-shot` 的 description 仍是 breakdown 阶段的旧文字（asset 不可直接编辑），图像模型会在旧文字（砝码）和新参考图（方盒）之间冲突，表现为反复重跑都画回旧造型。必须在受影响镜的 `storyboard-image.prompt` 里写显式覆盖（“忽略 description 里的 X，按参考图绘制 Y，四个特征逐条列出”），不要只靠参考图。重跑节点产生新 id 后，之前加的参考边也会丢，要重新连。
-- 极端远景/微距交替镜的小物体先验太强：当镜次构成为“远景展柜里小物体 + 微距局部”时，GPT-Image-2 容易把物体画成光面几何块（即使 prompt 强调饰钮/纹饰）；这是分镜草图阶段的已知极限，不要无限迭代。中近景/中景（物体占画面 ≥1/4）的构图能稳定拿到正确造型；远景镜可以接受，到 `video-generate` 阶段通过 motion prompt（推近到顶部饰钮、运镜覆盖关键特征）保证最终视频帧里造型正确。
-- 极端特写/物证镜忘记补人物 reference：`characters` 字段为空但画面里会露出手、眼、肩等身体部位（胸针压痕镜有努尔手指、金器微距带白手套、证章特写带手部）时，必须把对应人物的三视图 image-resource 作为 reference 连入，否则手指/手部会画成第三人称或数量错误。
-- 关联镜头没互加 reference：匹配切、叠化、连续推轨、正反打、同一动作多镜等强关联镜组，应该把前后镜的 storyboard-image 互作为 reference，保证构图/光线/道具位置连续；不能只单独看每镜自己的人物/场景/道具 reference。
-- 只做单镜审计不做时序审计：镜头间的人物位置跳跃、道具状态不连贯、色温跳变、视线失配、无桥硬切，必须按 shotKey 顺序逐对相邻镜核对；几十镜量级全量成本仍低，漏检代价高。
-- 把图像模型先验问题留到视频阶段不做记录：“面具买家”会被画眼罩、“竞拍牌”会被加数字、“隼”会被画成具象猛禽，这些必须在视频生成前列成 negative 清单写入 video-generate prompt，不能只依赖分镜图阶段的 negative。
-- 道具文字设定只连到 breakdown 就以为够了：`prop-resource` 必须像 `character-resource`/`location-resource` 一样，除连到 `prop-turnaround` 和 `storyboard-breakdown` 外，按镜中出现把文字节点连到对应 `storyboard-shot.props` 和 `storyboard-image.props`；否则 shot/image 阶段只能看到三视图 PNG，拿不到编号、印记或 negative 约束等文字设定，分镜图会出现牌面画数字、印记形状错误等连续性 bug。审计时必须单独统计三类资源到 shot 和到 image 的文字边数，要求三类分布对称；道具边数为零而人物/场景大量存在时即为异常。
+任务成功只代表服务端完成，不代表创作合格。每批产物都要回读任务、画布、连线、资产和最终配置并查看真实预览；只有阶段门禁、逐镜四项验收和最终成片验收全部通过，才可交付。

package/skills/using-vvicat-ai-short-studio-cli/references/assets-and-storyboard.md

@@ -0,0 +1,57 @@
+# 资产、拆镜与生成前审计
+
+仅在生产人物/场景/道具、拆镜、分镜图或视频前审计时读取本文件。
+
+## 资产生产门禁
+
+1. 只生产目标集实际出现的人物及形象版本、场景/子场景、关键道具及叙事版本。每项任务成功后展示真实预览，让用户确认并设置 selected version。
+2. 每个形象候选使用独立输入、独立三视图节点和独立图片资产；`count` 的多个结果也不能拼图。视觉素材未另行指定时使用 16:9，并按实时 schema 显式写入。
+3. 真/假、原版/复制、成年/童年等成对资源必须先生成基础版并确认，再把基础版 `image-resource` 作为 reference 生成派生版；prompt 只枚举允许差异，其余保持一致。
+4. 每个分镜拆解节点只连接一条目标集剧本，以及该集全部确认人物、场景和道具。素材缺失、未选版、映射歧义或连线不足时禁止执行。
+5. 拆镜成功后刷新画布并复用自动创建的 shot/image/prompt 节点；按 `parentAssetId`、`producerNodeId` 和集号核对归属，不按任务提交顺序猜测。
+
+## 拆镜语言匹配门禁
+
+拆镜前先输出并核对一行语言契约：`源剧本语言 / 用户交付语言 / 项目 outputLanguage / 节点 targetLanguage / H3 人声语言 / 字幕语言`。专有名词、品牌、咒语或剧情要求保留的外语另列白名单；除此之外任一项不明确或冲突都禁止执行。
+
+- **普通拆镜**：项目 `outputLanguage` 留空时自动跟随输入的主要语言；显式交付语言使用规范 BCP 47 标签，如 `en`、`ar`、`fr`、`pt-BR`、`zh-Hant`。写入后必须回读服务端规范值。节点若残留 `targetLanguage`，先按实时 schema 清除，避免把专业模式字段误当普通模式覆盖。
+- **专业 Markdown 拆镜**：`targetLanguage` 使用任意规范 BCP 47 标签，源文件必须为每段对白、旁白、屏显和场景标题提供同标签的本地化块。例如巴西葡萄牙语使用 `- **PT-BR:** ...`，场景标题使用 `**PT-BR:** ...`。专业 `targetLanguage` 是内容语言事实来源；项目 `outputLanguage` 和 CLI `--locale` 都不能代替它。
+- **写前回读**：执行前重新读取 settings、拆镜节点原始 config 和 selected 剧本，确认语言契约仍一致；`outputLanguage` 或 `targetLanguage` 改变后，从 stale 链起点重新拆镜，不复用旧语言镜头。
+
+拆镜完成后不抽样，逐镜检查所有语言字段：场景标题、description/action、对白、旁白、表演说明、摄影计划、图像提示词和视频提示词。专业流程还必须确认没有 `STORYBOARD_LANGUAGE_MISMATCH`；普通流程没有同等级服务端校验时，由本审计补齐。白名单外出现其他语言、台词被翻译成错误目标语言、角色名被错误翻译或同一镜混入两种输出语言，均记为 P1。
+
+全局错配先修正 settings/config 后重跑 `storyboard-breakdown`；仅单镜偶发错词且其他镜头语言正确时，使用 `canvas node edit-shot` 精确追加修正版并重新执行该镜后续链路。不得通过只改字幕掩盖错误台词或错误旁白。
+
+## 分镜素材连线门禁
+
+逐镜读取 selected shot 完整结构，把 `characters`、`locations`、`props` 与 description、sourceText、imagePrompt、videoPrompt、photographyPlan 交叉核对。结构化 `props` 缺失时用长名和上下文扫描文字字段；简称、同名或真假版本不能唯一匹配时询问用户。
+
+每镜同时核对两类边：
+
+- 已选 `image-resource → storyboard-image.reference` 的图片参考边。
+- `character/location/prop-resource → storyboard-shot/storyboard-image` 的文字设定边。
+
+人物、场景、道具必须对称覆盖。拒绝跨类型、反向、互连、重复、串镜和 stale；只精确删除错误 edge ID，不清空整组边。修复前输出差异，修复后重复同一审计，直到实际集合等于计划集合。
+
+## 镜头质量与逻辑审计
+
+逐镜输出“镜号 / 时长 / 角色计划与实际 / 道具计划与实际 / 场景 / reference / 问题 / 严重级别”。全量检查：
+
+- 剧本动作、台词、旁白、反应和转场是否覆盖，有无重复、缺失或无效镜头。
+- 人物身份、年龄版本、龙套、服化妆；道具真假、状态、编号；场景与子场景是否匹配。
+- 关键词是否因通用词误连；黑场、字幕、空镜不得连接可见人物、场景或道具。
+- 极端特写里出现手、眼、肩等身体部分时，补入对应人物 reference。
+- 临时纸页、报告等不是预定义道具时，不强绑无关实体资源。
+- 图像模型已知先验偏差写入逐镜 video negative，不能假设视频模型自动修正。
+
+P0/P1 必须清零；只修复受影响镜头或边，禁止全量重建掩盖局部问题。
+
+## 上下镜连续性
+
+先运行 `canvas continuity analyze`，再按时间线逐对核对人物位置和身份、服装状态、道具位置、光源与色温、动势和视线、轴线、景别节奏、叙事桥接。强关联动作、匹配切、正反打或连续推轨可让相邻分镜图互作 reference。时序本身错误或无法剪辑弥补的跳变必须报告用户决定调序或补镜。
+
+视频生成前，为每对镜头定义衔接方案：前镜结束遮挡物、后镜开头同源遮挡物、运动方向、色彩/亮度和可用重叠时长。具体执行见 [h3-video-delivery.md](h3-video-delivery.md)。
+
+## 分镜图后验
+
+每批完成后回读任务、节点、连线、资产、最终配置和 selected version，并实际查看所有图片。检查身份、肢体、道具、构图、画幅、裁切、文字、连续性和空结果。缺陷需再次付费生成或改选版本时，先展示问题并取得确认。

package/skills/using-vvicat-ai-short-studio-cli/references/commands/assets-and-tasks.md

@@ -0,0 +1,24 @@
+# 资产与任务命令
+
+## 资产
+
+```bash
+ai-short-studio canvas asset list --project <projectId> --json
+ai-short-studio canvas asset get <assetId> --project <projectId> --json
+ai-short-studio canvas asset upload <file> --project <projectId> --json
+ai-short-studio canvas asset select-version <assetId> --version <versionId> --project <projectId> --json
+ai-short-studio canvas asset download <assetId> --project <projectId> --output <directory>
+```
+
+下载前确认 `selectedOutputVersionId`。原始视频按镜号保存为 `S001.mp4`、`S002.mp4`，manifest 至少记录 `shotNumber`、`nodeId`、`assetId`、`versionId`、`fileName`。
+
+## 执行和等待
+
+```bash
+ai-short-studio canvas node run --project <projectId> --node <node1> --node <node2> --concurrency 4 --wait --json
+ai-short-studio task get <taskId> --json
+ai-short-studio task wait --task <task1> --task <task2> --concurrency 4 --json
+ai-short-studio task cancel <taskId> --yes --json
+```
+
+互不依赖的节点在一个 CLI 进程内批量运行；有依赖时分批。任务成功后仍需回读资产并查看真实产物，不能把成功状态当作质量验收。

package/skills/using-vvicat-ai-short-studio-cli/references/commands/canvas.md

@@ -0,0 +1,50 @@
+# 画布、节点与连线命令
+
+## 聚合读取与补丁
+
+```bash
+ai-short-studio canvas inspect --project <projectId> --include summary --include nodes --include edges --include assets --include settings --include node-types --json
+ai-short-studio canvas apply --project <projectId> --canvas-id <canvasId> --expected-version <version> --file patch.json --json
+ai-short-studio canvas node types --json
+```
+
+常见审计优先通过 `inspect` 的 `--kind`、`--status`、`--search`、`--operation`、`--resource-type`、`--producer-node` 过滤。同阶段多个图变更用一次 `apply`；409 后重读并合并。
+
+## 节点
+
+```bash
+ai-short-studio canvas node list --project <projectId> --json
+ai-short-studio canvas node get <nodeId> --project <projectId> --json
+ai-short-studio canvas node add <kind> --project <projectId> --config node.json --json
+ai-short-studio canvas node update <nodeId> --project <projectId> --set 'gridSize=9' --json
+ai-short-studio canvas node update-many --project <projectId> --file updates.json --json
+ai-short-studio canvas node edit-shot <nodeId> --project <projectId> --file shot.json --json
+ai-short-studio canvas node edit-resource <nodeId> --project <projectId> --file resource.json --json
+ai-short-studio canvas node delete <nodeId> --project <projectId> --yes --json
+```
+
+`update` 只改普通 config、标题和坐标；结构化 artifact 必须用 `edit-shot` / `edit-resource` 追加版本。身份字段不可修改，409 后重新读取当前选版。
+
+H3 批量启用原生音频的 `updates.json`：
+
+```json
+{
+  "updates": [
+    { "nodeId": "<videoNodeId>", "set": { "generateAudio": true } }
+  ]
+}
+```
+
+提交前以实时命令 schema 为准，提交后逐节点 `get` 回读。
+
+## 连线与连续性
+
+```bash
+ai-short-studio canvas edge list --project <projectId> --json
+ai-short-studio canvas edge add --project <projectId> --from <sourceNodeId>:<sourceHandle> --to <targetNodeId>:<targetHandle> --json
+ai-short-studio canvas edge delete <edgeId> --project <projectId> --yes --json
+ai-short-studio canvas continuity analyze --project <projectId> --json
+ai-short-studio canvas continuity analyze --project <projectId> --apply-ready --json
+```
+
+handle 来自实时节点目录。只删除精确 edge ID；`--apply-ready` 只在用户确认连续性建议后执行。

package/skills/using-vvicat-ai-short-studio-cli/references/commands/project.md

@@ -0,0 +1,65 @@
+# 项目与配置命令
+
+## 预检、Skill 与认证
+
+```bash
+ai-short-studio preflight --json
+ai-short-studio skill status --target codex --json
+ai-short-studio auth signup --email user@example.com --password-stdin
+ai-short-studio auth login --google
+ai-short-studio auth login --email user@example.com --password-stdin
+ai-short-studio auth status --json
+ai-short-studio auth logout
+```
+
+更新 CLI 后重跑 preflight。邮箱密码只从隐藏输入或安全 stdin 读取；`confirmationRequired: true` 时先完成邮件确认。
+
+## 项目与供应商
+
+```bash
+ai-short-studio project list --json
+ai-short-studio project get <projectId> --json
+ai-short-studio project create --name <name> [--description <text>] --json
+ai-short-studio project update <projectId> [--name <name>] [--description <text>] --json
+ai-short-studio project delete <projectId> --yes --json
+ai-short-studio project provider get <projectId> --json
+ai-short-studio project provider set <projectId> --json
+ai-short-studio project provider test <projectId> --json
+```
+
+`provider set` 的 Key 只从安全 stdin 或秘密管理器提供。删除既有项目必须取得明确授权。
+
+## Settings
+
+```bash
+ai-short-studio canvas settings get --project "$PROJECT_ID" --json
+ai-short-studio canvas settings set --project "$PROJECT_ID" --file settings.json --json
+```
+
+标准文件包含最近读取的版本和全部已确认变更：
+
+```json
+{
+  "expectedVersion": 3,
+  "values": {
+    "outputLanguage": "zh",
+    "aspectRatio": "9:16",
+    "imageResolution": "2K",
+    "imageQuality": "high",
+    "videoModel": "runninghub::minimax-h3-reference-to-video",
+    "videoPromptType": "h3",
+    "videoResolution": "1K"
+  }
+}
+```
+
+`null` 或空字符串清除项目覆盖。409 后重新读取、展示变化并确认，不盲目覆盖。
+
+## 账户配置
+
+```bash
+ai-short-studio config get --json
+ai-short-studio config set --file config.json --json
+```
+
+`config set` 只接受个人默认模型、能力默认值和并发；供应商、密钥与全局模型目录只能由管理员维护。

package/skills/using-vvicat-ai-short-studio-cli/references/commands.md

@@ -1,216 +1,19 @@
-# 命令参考
+# 命令路由
 
-所有命令支持 `--base-url`、`--profile`、`--locale zh|en` 和 `--json`。未配置地址时默认连接 `https://ai-short-studio.vvicat.dev`；`--base-url`、`VVICAT_BASE_URL` 和当前 profile 可依次覆盖。默认档案保存服务地址与默认项目；refresh token 仅保存在系统钥匙串，短期 access token 使用权限为 `0600` 的本机 session 缓存。同一 profile 的并发刷新由跨进程锁合并；Agent 应优先单进程批处理，不要并发启动多个 CLI 进程。
+只读取当前操作对应的命令文件：
 
-CLI 源码开发完成后，在包目录运行 `npm run test:local-e2e`。该命令使用本地 mock API 和真实 CLI 子进程覆盖聚合查询、字段更新、批量执行/等待、兼容入口及 8 进程 session 锁，不连接生产服务或调用模型，结束时自动清理临时数据。
+- 预检、认证、项目、供应商、settings、账户配置：[commands/project.md](commands/project.md)
+- 画布聚合、节点、连线、结构化编辑和连续性：[commands/canvas.md](commands/canvas.md)
+- 资产、选版、下载、异步任务和批量执行：[commands/assets-and-tasks.md](commands/assets-and-tasks.md)
 
-## 创作前预检
+所有命令支持 `--base-url`、`--profile`、`--locale zh|en` 和 `--json`。`--locale` 只控制 CLI 消息，不控制剧本、拆镜、H3 人声或字幕语言。
 
-```bash
-ai-short-studio --version
-ai-short-studio preflight --json
-ai-short-studio preflight --no-update --json
-```
+## 跨流程硬规则
 
-`preflight` 通过 `/api/v1/bootstrap` 检查 API base URL 连通性、取得 Supabase 公共配置、比较服务端推荐的稳定 CLI 版本，并检查认证和标准创作所需模型。默认发现新版本会更新当前全局 npm 包；更新后按 `nextAction` 重跑。`--no-update` 仅用于用户明确禁止全局写入时。
+项目配置先运行 `canvas settings get`，核对 `currentValue`、`effectiveValue`、`source` 和实时 options。`$ART_STYLE_ID` 必须解析 `option.value`。标准创作门禁必须用 `canvas settings set --file settings.json` 并携带 `expectedVersion`，写后回读；不得用账户 config、项目描述或节点 prompt 代替。
 
-## Skill 管理
+最终 `videoModel.effectiveValue` 为 `comfly::minimax-h3` 或 `runninghub::minimax-h3-reference-to-video` 时，必须写入 `videoPromptType: "h3"`；仅有效的节点 `promptType` 可覆盖项目值，旧 `seedance` 必须清除并回读，否则不得执行视频提示词或视频生成。实时能力 `generateAudioOptions` 必须包含 `true`，H3 节点显式设置并回读 `generateAudio: true`。
 
-```bash
-ai-short-studio skill path --json
-ai-short-studio skill install --target codex --json
-ai-short-studio skill status --target codex --json
-ai-short-studio skill update --target codex --json
-```
+视频时长读取实时 `durationOptions`。只有实时选项恰为 5、10、15 秒时才按这三档向上取整。RunningHub MiniMax H3 支持纯文本，5–15 秒逐秒可选，1–4 秒归一为 5 秒；画幅为 16:9 / 9:16，分辨率为 480p / 720p / 1K / 2K。
 
-`--target agents` 安装到 `~/.agents/skills`。`--root` 指定全部内置 Skills 的父目录；兼容参数 `--directory` 只管理主 CLI Skill，并把参数值作为精确安装目录。更新不会覆盖用户修改，除非显式传入 `--force`。
-
-## 认证
-
-```bash
-ai-short-studio auth signup --email user@example.com --password-stdin
-ai-short-studio auth login --google
-ai-short-studio auth login --email user@example.com --password-stdin
-ai-short-studio auth status --json
-ai-short-studio auth logout
-```
-
-Google 登录会打开浏览器并通过本机环回地址完成 PKCE 回调。Windows 直接调用系统 URL Handler，避免授权 URL 中 `&` 后的 `redirect_to` 和 PKCE 参数被命令解释器截断；若授权后仍跳到站点默认地址，先更新 CLI 并重试。
-邮箱注册的密码只从隐藏输入或 stdin 读取。`confirmationRequired: true` 时需先完成邮件验证再登录；为 `false` 时 CLI 已保存会话。
-邮箱注册确认链接由当前 profile 的 `baseUrl` 和 `--locale` 生成，格式为同域的 `/{locale}/auth/callback`。Supabase Redirect URLs 必须允许对应环境的 `/**`，无需为本地或测试注册修改全局 Site URL。
-
-## 项目
-
-```bash
-ai-short-studio project list --json
-ai-short-studio project get <projectId> --json
-ai-short-studio project create --name <name> [--description <text>] --json
-ai-short-studio project update <projectId> [--name <name>] [--description <text>] --json
-ai-short-studio project delete <projectId> --yes --json
-```
-
-创建操作固定写入 `INFINITE_CANVAS`；列表也只返回该类型。
-
-### 项目素材供应商
-
-```bash
-ai-short-studio project provider get <projectId> --json
-ai-short-studio project provider set <projectId> --json
-ai-short-studio project provider test <projectId> --json
-```
-
-`provider set` 从 stdin 读取 `{ "enabled": true, "apiKey": "..." }`，也可用 `--file`。真实 Key 只能来自安全 stdin 或秘密管理器；不得把它写入命令参数、仓库文件或文档。省略 `apiKey` 会保留已保存的 Key，只更新启用状态。读取命令只返回遮罩状态。
-
-### 项目配置
-
-```bash
-ai-short-studio canvas settings get --project "$PROJECT_ID" --json
-ai-short-studio canvas settings set --project "$PROJECT_ID" --field aspectRatio --value 9:16 --json
-ai-short-studio canvas settings set --project "$PROJECT_ID" --field artStyle --value "$ART_STYLE_ID" --json
-ai-short-studio canvas settings set --project "$PROJECT_ID" --field imageResolution --value 2K --json
-ai-short-studio canvas settings set --project "$PROJECT_ID" --field outputLanguage --value en --json
-ai-short-studio canvas settings set --project "$PROJECT_ID" --file settings.json --json
-```
-
-`settings get` 返回 `canvasId`、`version` 和各配置字段。每个字段包含项目覆盖值 `currentValue`、继承后的最终值 `effectiveValue` 与来源 `source`。画风、画幅、分镜类型、格数和模型候选从实时 `options` 读取；`visualBible` 返回 `schema`，不返回 `options`。CLI 和 Agent 都不得硬编码服务端枚举。示例中的 `$ART_STYLE_ID` 必须从 `artStyle.options` 选择并解析实时 `option.value`。
-
-`settings set` 只修改 `values` 中出现的字段。标准创作门禁必须用 `--file` 或 stdin 一次原子写入，并把最近一次 `settings get` 返回的 `version` 填入请求的 `expectedVersion`；`--field/--value` 只适合已确认无并发写入的交互式便利操作：
-
-```json
-{
-  "expectedVersion": 3,
-  "values": {
-    "aspectRatio": "9:16",
-    "storyboardGridSize": 6,
-    "imageResolution": "2K",
-    "imageQuality": "high",
-    "videoResolution": "1080p",
-    "videoModel": null
-  }
-}
-```
-
-`null` 或空字符串会清除项目覆盖并恢复账户默认或系统默认继承。设置 `artStyle` 时，服务端会把画风当前关联的 `visualBible` 保存为项目快照；画风库后续修改不会反向更新既有项目。同一请求显式提供 `visualBible` 时，显式值覆盖画风快照。
-
-所有者和管理员可执行 `settings set`，协作者只能执行 `settings get`。批量写入是原子的；建议携带最近一次读取的 `expectedVersion`，遇到 409 后重新运行 `settings get`、核对变化并取得确认，再携带新版本重试，不得盲目覆盖。Pexels 配置仍由 `project provider get|set|test` 管理，不属于 canvas settings。
-
-## 画布和节点
-
-```bash
-ai-short-studio canvas get --project <projectId> --json
-ai-short-studio canvas inspect --project <projectId> --include summary --include nodes --include edges --include assets --include settings --include node-types --json
-ai-short-studio canvas inspect --project <projectId> --kind storyboard-image --status stale --operation image-resource --json
-ai-short-studio canvas apply --project <projectId> --canvas-id <canvasId> --expected-version <version> --file <patch.json> --json
-ai-short-studio canvas node types --json
-ai-short-studio canvas node list --project <projectId> --json
-ai-short-studio canvas node get <nodeId> --project <projectId> --json
-ai-short-studio canvas node add <kind> --project <projectId> [--x N] [--y N] [--title <text>] [--config <config.json>] --json
-ai-short-studio canvas node update <nodeId> --project <projectId> --config <config.json> --json
-ai-short-studio canvas node update <nodeId> --project <projectId> --set 'gridSize=9' --unset legacyField --title <text> --json
-ai-short-studio canvas node update-many --project <projectId> --file <updates.json> --json
-ai-short-studio canvas node edit-shot <nodeId> --project <projectId> [--file <shot.json>] --json
-ai-short-studio canvas node edit-resource <nodeId> --project <projectId> [--file <resource.json>] --json
-ai-short-studio canvas node delete <nodeId> --project <projectId> --yes --json
-ai-short-studio canvas node run --project <projectId> --node <node1> --node <node2> --concurrency 4 --wait --json
-```
-
-`canvas inspect` 一次读取画布并聚合常见审计结果。`--include` 可重复指定 summary、nodes、edges、assets、settings、node-types；`--kind`、`--status`、`--search`、`--operation`、`--resource-type`、`--producer-node` 用于筛选。覆盖这些条件的查询不再编写临时脚本。
-
-`canvas apply` 的 JSON 可以通过 `--file` 读取；省略文件时从 stdin 读取。若已有画布快照，传入 `--canvas-id` 和 `--expected-version` 后不会额外预读全图；缺少任一参数时保持兼容，CLI 自动读取版本。该命令保留给节点、连线、删除、视口等低层画布图补丁；常规项目配置使用 `canvas settings get|set`。同一阶段存在两个及以上可合并的图变更时，默认用一次 `canvas apply` 提交 `upsertNodes`、`upsertEdges`、`deleteNodeIds` 和 `deleteEdgeIds` 等完整差异，成功后统一回读；批量入口不存在、服务不支持，或合法请求仍因批量粒度失败时，才回退对应的 node/edge 单条命令并只处理尚未生效项。409 应重读、合并并确认后继续重试批量；401/403、参数、schema、业务门禁或付费确认错误必须先修正，不能通过单条命令绕过。
-
-`canvas node update --set key=<JSON> --unset key` 只修改指定 config 字段，也可同时更新标题与坐标；`--config` 保持兼容。`update-many` 输入 `{ "updates": [...] }`，一次读取画布和 schema 后原子更新多个节点。结构化生成资源仍必须走 `edit-resource` 或 `edit-shot`。批量节点执行和任务等待默认并发 4、上限 16，优先在一个进程内运行。`storyboardGridSize` 仅在节点级 `gridSize` 无法使用的异常回退中经用户确认后写入；正常流程继续按镜头复杂度设置各节点的 `gridSize`。
-
-## 连线
-
-```bash
-ai-short-studio canvas edge list --project <projectId> --json
-ai-short-studio canvas edge add --project <projectId> --from <sourceNodeId>:<sourceHandle> --to <targetNodeId>:<targetHandle> --json
-ai-short-studio canvas edge delete <edgeId> --project <projectId> --yes --json
-```
-
-网页增量保存使用 `Prefer: return=minimal` 获取固定大小回执；CLI 的后续命令依赖完整画布，因此显式使用 `Prefer: return=representation`。正常保存前不额外读取全图；发生 409 时重新读取最新画布、合并本地补丁并确认后重试。
-
-`canvas node edit-shot` 的文件或 stdin 内容是镜头字段对象，可编辑 `photographyPlan` 对象和 `actingNotes` 对象或数组。命令读取当前画布版本和当前资产选版后追加一个人工 DOCUMENT 版本；`shotKey`、`shotIndex` 和来源身份不可修改，旧版本不会被覆盖或删除。
-
-`canvas node edit-resource` 的文件或 stdin 内容是剧本、人物、人物视觉、场景、子场景或道具资源的 JSON 对象。命令读取最新画布版本与目标节点的 `selectedOutputVersionId`，在该版本的完整父文档中只替换 `resourceKey` 对应实体，再追加并固定当前节点的新选版；名称、资源键、ID、所属人物或场景等身份字段不可修改，兄弟资源节点保持原选版，下游递归标记 stale。缺少稳定 `operation/resourceKey/resourceType` 的旧节点只读，不能按标题猜测。该写入不属于 `canvas apply`；409 后重新读取画布与选版并确认，不得盲目覆盖。
-
-首尾帧提取使用实时目录中的 `video-frame-extract`，配置为 `{"position":"first"}` 或 `{"position":"last"}`。输入连接 `video`，输出 `image` 是独立 IMAGE 资产版本并记录来源视频版本。`previous-tail` 只记录连续性需求，不自动物化尾帧拓扑；用户可确认预检建议或手动建立节点与连线。创建这些节点与连线不会自动执行或付费。
-
-原始视频交付先按镜号读取视频节点的 `selectedOutputVersionId`，再逐个执行 `canvas asset download`，保存为 `S001.mp4`、`S002.mp4`……。同时生成逐行 `manifest`，每行包含 `shotNumber`、`nodeId`、`assetId`、`versionId`、`fileName`。只下载 selected 原始 MP4；字幕单独交付，不混入分镜图、音频中间件或烧录字幕版本。
-
-handle 名称来自节点类型目录中的输入输出 schema，不要自行推断。
-
-## 镜头连续性
-
-```bash
-ai-short-studio canvas continuity analyze --project <projectId> --json
-ai-short-studio canvas continuity analyze --project <projectId> --apply-ready --json
-```
-
-该命令用于新旧镜头的连续性分析和人工审计。新规划镜头直接读取 `independent` 或 `previous-tail`，但服务端不会自动创建尾帧节点或 `start-frame` 连线，也不会因依赖未完成阻止后镜独立生成。前镜视频完成后，用户可确认建议再显式执行 `--apply-ready`。
-
-### Meme 专属节点流程
-
-Meme 视频默认使用 `meme-scene-analysis` → `meme-material-search` → `cat-meme-video`，禁止静默改用 `storyboard-*` 或通用 `video-generate`。项目中的 Seedance 等 `videoModel` 不参与 `cat-meme-video` 合成；只有用户明确要求生成式视频并确认额外费用与画风变化后，才可使用通用视频节点。
-
-1. 连接 `text.text → meme-scene-analysis.story`，运行并等待任务终态。
-2. 刷新画布，复用自动创建的计划资源和 `meme-material-search`；不要手工添加重复节点。
-3. 运行素材检索。即使不使用外部素材也不能跳过：Pexels 可关闭，内置背景、内置道具和库外道具图片生成仍在该节点完成。
-4. 刷新画布，复用自动创建的 `cat-meme-video`，核对原故事、计划和素材包三条输入边，并确认素材包没有无法复用的必显道具缺失项。
-5. 按实时 schema 设置节点的 `aspectRatio: "1:1" | "9:16" | "16:9"` 和 `resolution: "720p" | "1080p"`，运行并等待终态，再下载和审计真实视频。
-
-错误恢复固定为：`CAT_MEME_REQUIRED_PROP_MISSING` 回到素材检索；`CAT_MEME_DISPLAY_CONTENT_REQUIRED` 修复计划；`CAT_MEME_FFMPEG_FAILED` 修复或部署渲染器后重试。不得把失败当作切换通用视频生成的授权。
-
-项目级默认参数使用 `canvas settings set` 写入 `imageResolution`、`imageQuality`、`videoResolution`；候选值读取 `settings get` 对应字段的实时 `options`。通用 `image-generate`、`image-edit` 节点只在需要偏离项目默认时，才在 `config` 写入字符串 `resolution`、`quality`；`video-generate` 同理可覆盖 `resolution`。节点覆盖值必须来自当前节点模型 `capabilities`，没有对应能力声明时不写入。
-
-RunningHub MiniMax H3 的实时 `aspectRatio` 只有 16:9、9:16，`resolution` 只有 480p、720p、1K、2K，默认为 1K。
-
-## 资产与下载
-
-```bash
-ai-short-studio canvas asset list --project <projectId> --json
-ai-short-studio canvas asset get <assetId> --project <projectId> --json
-ai-short-studio canvas asset upload <file> --project <projectId> --json
-ai-short-studio canvas asset select-version <assetId> --version <versionId> --project <projectId> --json
-ai-short-studio canvas asset download <assetId> --project <projectId> --output <directory>
-```
-
-`canvas asset upload` 会按文件扩展名为常见图片、视频和音频设置 MIME 类型；未知扩展名使用 `application/octet-stream`。
-
-## 异步任务
-
-```bash
-ai-short-studio task get <taskId> --json
-ai-short-studio task wait <taskId> [--interval 1000] --json
-ai-short-studio task wait --task <task1> --task <task2> --concurrency 4 [--interval 1000] --json
-ai-short-studio task cancel <taskId> --yes --json
-```
-
-## 模型配置
-
-```bash
-ai-short-studio config get --json
-ai-short-studio config set --file <config.json> --json
-```
-
-`config set` 只接受 `defaultModels`、`capabilityDefaults`、`workflowConcurrency` 的部分对象；CLI 与服务端都会拒绝 `providers` 或 `models`。Provider 密钥和全局模型目录只能由管理员后台维护。预检仅缺 `capabilityDefaults.<modelKey>.<field>` 时，先用 `config get` 核对实时 options，优先复用目标项目有效设置，其次使用服务端模型默认值，否则使用 options 第一项；合并写入后回读并重跑 preflight，不先把可自动修复项反馈给用户。账户级 `config set` 不得代替项目的 canvas settings。
-
-## 标准创作命令顺序
-
-先执行 `preflight`；若只缺可确定的账户能力默认值，立即用一次 `config set` 自动补齐、回读并重跑。通过后继续 `config get` → `canvas node types` → `project list`。新项目随后按“确认名称/用途 → `project create` → `project get` + 一次 `canvas inspect` 聚合查询”继续，不要求创建前读取不存在的项目或画布；既有项目读取同样的已有资源。只有聚合结果缺少专用命令独有字段时才补充单项查询。
-
-取得配置后，向用户展示项目名称/用途，并逐项确认 `aspectRatio`、`artStyle`、`visualBible`、`storyboardImageType`、`analysisModel`、`imageModel`、`imageResolution`、`imageQuality`、`editModel`、`videoModel`、`videoResolution`、`audioModel` 的 `currentValue`、`effectiveValue`、建议值与 `source`；候选值和视觉圣经结构分别以实时 `options` 与 `schema` 为准。用户未指定分镜类型时推荐 `storyboardImageType: grid`（分镜板/宫格分镜），不推荐 `storyboard`（故事版）。模型可项目覆盖，也可由用户明确确认继承账户默认，但必须明确最终生效且可用的具体模型。`storyboardGridSize` 仅在异常回退时确认。同一阶段的多个画布写操作默认合并到一次 `canvas apply`，批量不可用或合法批量请求仍因批量粒度失败时才回退单条 node/edge 命令。
-
-项目名称和用途先由用户确认；新项目用 `project create` 保存，既有项目需要变更时仅用 `project update` 修改用户确认的项目字段。把确认的配置用一次 `canvas settings set` 原子写入并携带 `expectedVersion`，随后再次 `settings get` 回读。只有结果与确认一致且所需模型可用，才执行 node add/edge add/node run。写入、权限、冲突、回读或模型校验失败时停在配置阶段，不触发付费任务。账户级 `config set` 自动修复只补预检缺失的能力默认值，不能替代项目 settings；项目 `description`、节点 `prompt`/`config` 和低层 `canvas apply` 同样不能替代。
-
-执行 `storyboard-breakdown` 前，必须先完成本次故事涉及的全部人物、场景、道具等素材节点：互不依赖的节点用一次 `canvas node run` 重复传 `--node`，需要同步等待时加 `--wait`；已有多个任务 ID 时用一次 `task wait` 重复传 `--task`。有上游依赖的节点按依赖顺序分批执行，不得为了等待单个任务而串行提交其他独立素材。全部任务成功后，用聚合查询或 `canvas asset get/list` 核对并在用户确认后设置 selected version。随后依据实时 schema 连接素材，并用一次 `canvas inspect` 核对无遗漏。任一素材任务未成功、selected version 为空或对应连线缺失时，都不得执行分镜拆解；素材范围不清楚时先询问用户。即使服务端 schema 把人物、场景或道具输入标为可选，标准创作流程也不能跳过本次故事实际涉及且已确认使用的素材。
-
-专业 Markdown 纯文本拆镜使用 `{"storyboardPipelineVersion":2,"sourceFormat":"screenplay-markdown.v1","targetLanguage":"en","platform":"TikTok","aspectRatio":"9:16"}`，阿语集把语言改为 `ar`。只连接一条剧本与该集实际涉及的文字资产。该模式不执行声音、TTS、图片、音频或视频生成；完成后用任务、画布和资产回读确认只新增分镜文本/镜头，失败时零分镜持久化。
-
-生成 `storyboard-image` 前，用 `canvas asset get/list` 取得素材 selected version，必要时通过 `canvas asset download` 下载，并向用户实际展示人物、场景、道具等预览；用户确认后才可执行。用户未指定布局时推荐并使用 `imageLayout: grid`（分镜板/宫格分镜），`storyboard`（故事版）与 `single` 仅在用户明确选择时使用。逐镜头根据需要独立呈现的动作、表情、主体关系、视角和空间调度状态选择最小够用的 `gridSize`，不得沿用统一格数或仅按时长推算；先用实时节点 schema 核对允许值，再向用户列出“镜号、复杂度依据、建议格数”，确认后逐个更新对应 `storyboard-image` 节点。生成视频前，同样取得并展示实际分镜图或可访问预览，确认分镜图和视频镜头范围后才可执行 `storyboard-video-prompt` / `video-generate`。仅输出资产 ID、URL、文件路径或成功状态不能代替展示；任一确认缺失时停止并询问。
-
-用户未指定画幅时，角色、道具、场景/背景、分镜图及其他视觉参考素材统一使用 `16:9`；实时 schema 支持 `aspectRatio` 时显式写入节点，避免继承项目中的其他画幅。视频时长以当前模型实时 `durationOptions` 为准。只有实时模型仅提供 5、10、15 秒时，才按镜头目标时长向上取这三档，并保留原目标时长供剪辑裁切；其他模型使用经用户确认的实时合法值。RunningHub MiniMax H3 暴露 5–15 秒的每个整数，支持不连任何媒体的纯文本生成，服务端会把 1–4 秒归一为 5 秒。参考音频仍不能作为唯一媒体输入；纯文本是零媒体，不是 audio-only。
-
-每批生成完成后都必须自我审计：重新读取任务、画布、节点、连线和资产，核对终态、selected version、输入引用、最终有效画幅、视频时长仍属于实时 `durationOptions` 的合法值、模型与布局，并实际查看预览中的身份、场景、道具、动作、连续性及黑帧、拉伸、裁切、破音或空结果。输出通过项、缺陷、失败项和未决项；再次付费生成、改选版本或覆盖用户内容前先取得确认。
-
-`storyboard-breakdown`、`storyboard-image` 和 `storyboard-video-prompt` 成功后会由服务端物化下游节点。每步完成后先重新 `canvas get` 或 `canvas node list` 获取真实 ID，禁止照示例伪造 ID 或重复建节点。
+结构化资源使用 `canvas node edit-resource`，镜头使用 `canvas node edit-shot`。Meme 使用 `meme-scene-analysis → meme-material-search → cat-meme-video`，禁止静默切换通用视频；`CAT_MEME_REQUIRED_PROP_MISSING` 返回素材检索修复。

package/skills/using-vvicat-ai-short-studio-cli/references/h3-video-delivery.md

@@ -0,0 +1,73 @@
+# MiniMax H3 原生音频、转场与成片验收
+
+凡是 MiniMax H3 视频任务或包含 H3 镜头的成片，必须完整读取并执行本文件。
+
+## 1. 原生音频唯一来源
+
+生成前读取实时模型能力和 `video-generate.configSchema`。目标 H3 模型的 `generateAudioOptions` 必须包含 `true`，节点 schema 必须允许 `generateAudio`；否则停止并报告模型能力缺口，不得回退外部 TTS。用一次 `canvas node update-many` 给本批全部 H3 `video-generate` 显式设置 `generateAudio: true`，随后逐节点回读；任一节点不是显式 `true` 都禁止运行，不能依赖默认值。
+
+每个 `video-generate` 在同一提示词中完整设计四层声音：
+
+1. **人物对白**：写明说话者、语言、逐字台词、表演情绪、声线锚点和口型要求。画面内说话者必须可见且口型同步。
+2. **旁白/画外音**：写明说话者或叙述者、逐字内容、声线锚点及“画外音期间画面人物闭口”，避免模型把旁白错误赋给画面人物。
+3. **环境音与动作音**：写明空间底噪、关键动作拟音、远近关系和需要静音的区域；不要只写“有环境音”。
+4. **BGM**：写明配器、节奏、情绪曲线、起止和跨镜延续母题；对白出现时降低存在感，不盖住人声。
+
+同一角色跨镜复用稳定的声线描述；相邻镜明确上一镜声音如何延续、衰减或被新声音接管。参考视频只提供画面，不能假设其中音轨会自动进入 H3。
+
+## 2. 人声时长与跨镜声音计划
+
+运行前逐镜输出声音时间表：`镜头时长 / 人物对白起止 / 旁白起止 / 无人声反应段 / 环境音 / BGM 状态 / 转场声音桥`。对白和旁白必须按目标语言自然试读或使用已有时长估算能力，全部落在合法镜头时长内，并为开场建立、表演反应和尾部遮挡保留实际余量。文本放不下时优先拆镜或删减经用户确认的非关键信息，不通过加速语速、吞掉停顿或剪断句尾硬塞。
+
+同一场景建立一份共享音乐锚点：配器、速度、调性/音区、节奏型、情绪曲线和禁止元素。每个转场指定 `outgoing|incoming` 中哪一侧拥有重叠区的主导音乐；另一侧在提示词中要求保持稀疏、尾奏或延后进入，避免两段独立 BGM 同时争抢。相邻生成结果仍不连续时重跑音频不合格的一镜，不得铺外部音乐遮盖。
+
+禁止为 H3 成片运行 `voice-design`、`voice-clone`、`tts`、Edge TTS 或其他外部 TTS 后覆盖人物说话或旁白，也禁止用外部 BGM/环境音替换 H3 原生设计。后期只允许对原生整轨做轻微音量、均衡、降噪、响度和首尾淡化；原生语音失败必须重写提示词并重跑受影响镜头，不能用外部配音遮盖。
+
+## 3. 遮挡/遮罩转场设计
+
+转场必须在生成前成对设计，而不是生成后用特效补救：
+
+- 前镜最后约 0.3–0.8 秒安排有动机的前景物完整或近完整遮挡画面，例如人物衣摆、门框、车辆、墙柱、暗部、强光或快速贴近镜头的物体。
+- 后镜从形状、运动方向、速度、亮度或色彩相近的遮挡状态开始，再揭示新场景；遮挡物要服务剧情和空间，不添加无关物体。
+- 分镜和 H3 提示词都明确“结束遮挡 / 开始遮挡 / 揭示方向 / 声音桥 / 可裁切余量”。若前后遮挡无法匹配，生成前改镜头设计，不把问题留给剪辑。
+- 硬切可用于明确节奏点；需要顺滑衔接时默认使用遮挡匹配，不依赖长叠化、花哨插件或全局统一转场。
+
+后期只做轻微重叠拼接：默认重叠 0.2–0.5 秒，在遮挡最充分处对齐；仅做短透明度/音量交叉淡化或直接切换。不得用长叠化把两个不匹配画面糊在一起，也不得因重叠截掉台词首尾。
+
+生成前逐对记录转场表：`前镜 / 后镜 / 前镜遮挡 / 后镜同源遮挡 / 方向 / 亮度与色彩 / 声音桥 / 预计重叠 / 主导音轨`。该表是审核记录，不是虚构的节点 config；实际写入字段仍以实时 schema 为准。
+
+## 4. 每镜四项后验验收
+
+每个镜头任务成功后，先下载或打开真实视频，从头到尾观看并听完，再输出以下四项结果。任务成功、元数据正确或首帧截图都不能替代验收。
+
+### 视觉
+
+核对人物身份、年龄、服装、脸、手、道具版本和状态、场景、动作顺序、机位、轴线、画幅、黑帧、冻结、闪烁、拉伸、裁切、模型幻觉和非预期文字。关键叙事动作必须真实可见。
+
+### 音频
+
+核对人物对白和旁白的逐字内容、说话者、语言、声线连续性、口型/闭口状态；检查环境音、动作音、BGM 是否存在且层级合理，有无漏字、重复、异常停顿、断裂、破音、削波、静音、杂音、陌生人声或 BGM 盖人声。任何人声缺失或来源错误为 P0/P1，必须重跑该镜，禁止外部 TTS 补洞。
+
+### 转场
+
+同时查看前镜尾部和本镜头部，确认遮挡真实覆盖、形状/方向/亮度/速度可匹配，并保留足够重叠余量；检查声音桥是否自然。转场条件不成立时重跑受影响的一侧，不直接进入剪辑。
+
+### 字幕
+
+字幕以验收通过的实际原生人声为准。先从实时节点目录寻找可用的转写/字幕能力；存在时转写 selected 视频音轨并人工复核，不存在时必须完整听写，不能假装已自动转写。将结果与语言契约和剧本逐句比较，核对逐字内容、说话者、分句、时间码、可读时长、安全区和语言。提示词文本不能直接当作已验收转写；若实际语义或语言错误，重跑视频，不用错误字幕伪装正确对白。原始视频不烧录字幕，成片层再排版。
+
+逐镜记录 shot/node/task/asset/version、四项结论、问题级别和处理动作。P0/P1 未清零不得选入剪辑；P2 可在不改变内容的轻量后期范围内修复并复验。
+
+## 5. 完整成片验收
+
+只使用逐镜四项验收通过的 selected 版本。涉及 Remotion 时先加载 `remotion-best-practices`，保留每镜 H3 原生音轨，以遮挡点轻微重叠拼接；不要另铺外部旁白、对白、环境音或 BGM 覆盖原生轨。
+
+渲染后必须从头到尾完整观看并听完，再检查：
+
+- **叙事与画面**：镜序、总时长、节奏、人物/服化道/空间连续性，无黑帧、冻结、坏帧、意外裁切或视觉跳变。
+- **声音**：对白、旁白、环境音和 BGM 跨镜连续，无重复、吞字、断裂、突跳、削波或被转场截断；平台无特殊要求时可把整片响度控制在约 -14 至 -16 LUFS，true peak 不高于 -1 dBTP。
+- **转场**：逐个慢看遮挡交界帧，确认重叠发生在遮挡最充分处，无双影、闪白、方向反转或长叠化拖影。
+- **字幕**：全片逐句核对实际人声、时间码、说话者、断句、错字、遮挡和安全区；标题、介绍和字幕风格统一。
+- **技术**：用媒体探针核对分辨率、画幅、帧率、时长、视频/音频编码、采样率和声道；文件可从头播放到尾且交付目录只含批准版本。
+
+任一 P0/P1 失败都回到对应镜头或剪辑点修复并重新渲染、重新完整观看。最终报告列出成片路径、技术参数、镜头版本、四类全片验收结论和仍获用户接受的 P2；未完成完整观看不得声称“成片完成”。

package/skills/using-vvicat-ai-short-studio-cli/references/project-and-canvas.md

@@ -0,0 +1,34 @@
+# 项目与画布规则
+
+仅在创建/恢复项目、修改 settings、目录、节点或连线时读取本文件。
+
+## 初始化和配置
+
+1. `preflight --json` 检查地址、CLI 版本、认证和标准能力；`restartRequired` 为真时重跑。仅缺可确定的账户 `capabilityDefaults` 时，从实时 options、目标项目有效值或模型默认值补齐并回读；模型不可用或候选缺失时停下询问。
+2. `config get` 只管理个人默认模型、能力默认值和工作流并发。供应商、密钥和全局模型目录由管理员维护。
+3. 新项目按“确认名称/用途 → `project create` → `project get` + 一次 `canvas inspect`”执行；既有项目先聚合读取。项目配置回读通过前不得创建创作节点。
+4. `canvas settings get` 必须确认项目覆盖值、继承后的有效值、来源和实时候选。默认推荐 `storyboardImageType: grid`；`visualBible` 按实时 schema 构造。`outputLanguage` 必须与用户确认的交付语言一致；“自动”只适合用户明确要求跟随输入且源剧本语言单一的普通拆镜。CLI `--locale` 只影响命令界面和输出消息，不代表内容语言。
+5. `imageResolution`、`imageQuality`、`videoResolution` 优先由项目统一设置；节点只有确需不同且实时能力允许时才覆盖。H3 模型必须与 `videoPromptType: "h3"` 同次写入。
+6. 用一次 `canvas settings set --file` 原子写入全部确认项并携带最近的 `expectedVersion`。409 后重新读取、展示变化并确认；写后立即回读。
+
+## 查询与批处理
+
+- 常规查询先用一次 `canvas inspect`，通过 `--include`、`--kind`、`--status`、`--search`、`--operation`、`--resource-type`、`--producer-node` 表达；现有命令不能表达时才写临时脚本。
+- 同阶段两个及以上图变更用一次 `canvas apply --canvas-id ... --expected-version ...`。只改 config/title/位置时，单节点用 `node update`，多节点用 `node update-many`。
+- 独立任务在一次 `node run` 中执行，多个任务在一次 `task wait` 中等待；不要 shell 并发多个 CLI 进程。
+- 批量命令缺失或合法批量请求因粒度失败时，只回退尚未生效的单项。不得用单项调用绕过权限、schema、业务或付费门禁。
+
+## 资产目录
+
+先用 `canvas episode list/create` 确认分集，再用 `canvas folder list` 取得真实目录 ID。预设的道具、人物、场景、配音、分镜目录不可重命名、移动或删除；用户子目录最多 32 层，删除后有 30 天恢复窗口。移动不得形成环，删除被引用目录前先解除引用。跨项目复制只复制资产及版本，不复制目录结构，写后用目标项目回读。
+
+## 不可变编辑和并发
+
+- `canvas node edit-shot` 只编辑镜头内容，不能改 `shotKey`、`shotIndex` 或来源身份。
+- `canvas node edit-resource` 只替换完整父文档中的目标实体，不能改名称、资源键、ID 或所属关系；兄弟资源保持原选版。
+- 两类编辑都基于当前 `selectedOutputVersionId` 追加版本并使下游 stale。409 后重读画布和选版，不覆盖历史。
+- `canvas apply` 只处理节点、边、删除和视口，不代替 settings 或结构化 artifact 编辑。
+
+## 安全边界
+
+refresh token 只保存在系统钥匙串；密码和 API Key 只从交互式隐藏输入、stdin 或秘密管理器提供。不得读取、复制或删除本地认证缓存规避认证。项目供应商读取只返回遮罩状态，写入 Key 必须使用安全 stdin。删除既有项目、覆盖完整画布或改模型前先确认影响。

package/skills/using-vvicat-ai-short-studio-cli/references/special-workflows.md

@@ -0,0 +1,25 @@
+# 专项流程
+
+只读取当前任务命中的小节。
+
+## 专业剧本和纯文本拆镜
+
+微短剧从选题或方案开始时，先用 `short-drama` 完成方案、角色、分集、目标单集剧本和 review，再用 `humanizer` 只润色表达，最后回到 short-drama 复核。已有专业剧本直接创建 screenplay resource。
+
+用户明确要求专业 Markdown 纯文本拆镜测试时，给 `storyboard-breakdown` 配置 `storyboardPipelineVersion: 2`、`sourceFormat: screenplay-markdown.v1`、任意规范 BCP 47 `targetLanguage`、平台和画幅，且只连接一条剧本。执行前按 [拆镜语言匹配门禁](assets-and-storyboard.md#拆镜语言匹配门禁) 验证每个本地化块；`targetLanguage` 不能被项目 `outputLanguage` 或 CLI `--locale` 替代。该模式只验收分镜文本和镜头资产，不执行声音设计、TTS、图片、音频或视频生成；失败时确认没有持久化半成品。
+
+## 独立 TTS 音频
+
+本节只适用于用户明确要求独立音频文件、无 H3 视频的声音资产或非 H3 工作流。H3 成片的人物对白、旁白、环境音和 BGM 必须遵守 [h3-video-delivery.md](h3-video-delivery.md)，不得用本节覆盖。
+
+先读取实时 `audioModel` 和 `tts` / `voice-design` / `voice-clone` schema。声音设计和克隆必须先生成真实音色 ID，再连接到 TTS；不得把任务 ID、节点 ID 或预置音色名当音色 ID。CosyVoice v3.5 plus/flash 只接受同型号设计或克隆音色。运行后等待终态并试听完整音频，检查语言、文本、音色、语速、音调、时长、空音频和破音；按错误码修正，不盲目换音色重试。
+
+## Meme
+
+标准链路固定为 `meme-scene-analysis → meme-material-search → cat-meme-video`。即使禁用外部素材，也要运行 material search 解析内置素材和必显道具。刷新画布后复用自动创建的计划、搜索和视频节点，不手工重复创建。
+
+`CAT_MEME_REQUIRED_PROP_MISSING` 返回素材检索补道具；`CAT_MEME_DISPLAY_CONTENT_REQUIRED` 修复场景计划；`CAT_MEME_FFMPEG_FAILED` 修复或部署渲染器后重试。不得把失败当作切换通用 `video-generate` 的授权。
+
+## AI 剪辑
+
+涉及时间线、裁切、字幕、转场、音频编排或渲染时，必须先加载 `remotion-best-practices`。只使用已确认的 selected 资产；原始镜头和 manifest 单独保留。H3 成片只对原生整轨做轻量处理，禁止另铺外部 TTS、旁白、对白、环境音或 BGM 覆盖。

package/skills/using-vvicat-ai-short-studio-cli/references/troubleshooting.md

@@ -0,0 +1,30 @@
+# 故障排查与恢复边界
+
+仅在任务失败、产物异常、语言错配或连线审计失败时读取。
+
+## 配置、语言和版本
+
+- **settings 写错位置**：画幅、画风、`outputLanguage`、模型和默认分辨率必须写项目 settings。账户 config、项目描述和节点 prompt 不能替代。
+- **拆镜语言错配**：先打印语言契约。普通模式修正 `outputLanguage`；专业 Markdown 修正 `targetLanguage` 和源文件本地化块。全局错配重跑 breakdown，单镜偶发错误才精确 `edit-shot`；不能只改字幕。
+- **任务成功但仍是旧内容**：按 `selectedOutputVersionId`、`parentAssetId`、`producerNodeId` 和 stale 链核对，不能按提交顺序猜版本。
+- **自动下游重复**：breakdown、storyboard image 或 prompt 完成后先刷新画布，复用服务端物化节点。
+
+## H3 音频与成片
+
+- **没有人声或旁白**：检查模型 `generateAudioOptions` 包含 `true`，节点 config 显式为 `generateAudio: true`，提示词含逐字文本、说话者和语言。任一不符先修正并重跑该镜，禁止外部 TTS 补洞。
+- **语言正确但吞字/断句**：检查声音时间表是否放得下全部文本；拆镜或经确认删减，不加速硬塞。
+- **BGM 切换突兀**：核对共享音乐锚点和转场主导侧；只重跑不合格的一镜，不铺外部 BGM。
+- **遮挡转场仍生硬**：先检查两侧真实画面是否都达到遮挡条件；生成素材不成立时重跑对应镜头，长叠化不能修复根因。
+
+## 资产与连线
+
+- **道具存在但没有 reference**：不能只看结构化 `props`；同时扫描 description、video prompt 和 photography plan，并核对图片 reference 边与资源文字边。
+- **真假、年龄或同名资源串线**：结合场景、完整资源名、状态和叙事上下文消歧；不唯一时询问用户。
+- **旧 description 与新参考图冲突**：在受影响分镜提示词中明确覆盖旧描述，并重新连接新节点丢失的 reference；不要无限重跑冲突输入。
+- **错边修复**：只删除精确 edge ID；禁止清空全部边或重建节点掩盖问题。
+
+## 专项错误
+
+- `STORYBOARD_LANGUAGE_MISMATCH`：专业拆镜输出含目标语言之外的文字；修正本地化块或 `targetLanguage` 后重跑。
+- `COSYVOICE_TTS_CUSTOM_VOICE_REQUIRED`：仅独立 TTS 流程使用同型号声音设计/克隆 ID，不反复尝试预置音色。
+- `CAT_MEME_REQUIRED_PROP_MISSING`：返回 material search；`CAT_MEME_DISPLAY_CONTENT_REQUIRED` 修复计划；`CAT_MEME_FFMPEG_FAILED` 修复渲染器后重试，均不得静默切换通用视频生成。