@aswless_854771076/ai_short_studio_cli 0.1.33 → 0.1.35

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

@@ -32,14 +32,20 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
 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**
+
+用户需要从选题、创作方案、人物、分集目录开始创作或续写微短剧剧本时，先使用 `short-drama` 完成对应阶段并取得用户确认，再把已确认的单集剧本交给本 Skill 创建 VVICAT 项目、素材和分镜。已有专业剧本时直接创建 `screenplay-resource` 并进入素材与分镜流程，不得重复执行 `novel-to-script`；只有输入仍是小说、故事梗概或需要改编的原文时才使用 `novel-to-script`。
+
 ## 标准创作流程
 
 1. 明确原始故事或剧本、目标受众与平台、语言、成片画幅、总时长与镜头目标时长、风格参考、人物/场景/道具约束，以及交付是否包含剧本、设定、分镜图、视频和音频；除本文明确的素材画幅与视频生成时长默认值外，缺项先问。
 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` 的节点必须显式写入最终值，不得误继承项目中的其他画幅；不支持时不得伪造字段，应说明实际继承来源并在付费生成前确认最终有效画幅。人物视觉方案的每个 `appearance.descriptions` 候选必须拆成独立输入，并采用“一候选描述 → 一个三视图节点 → 一个独立图片资产”的方式生成；道具存在多个候选方案（真/假、原版/复制品、干净/破损等成对或多版本）时，**必须按“关联资产参考图门禁”先生成基础版并用户确认 selected version，再把该基础版的 image-resource 作为参考图连入派生版 turnaround/design 节点，prompt 逐条枚举允许的差异**，不得两版并行独立生成。每个三视图/设计节点只能接收一个人物形象或一个道具候选，提示词必须明确“只生成当前候选的一张三视图，不得拼接其他候选”；单张三视图内部可以包含同一对象的正面、侧面和背面，但禁止把多个候选方案纵向、横向或宫格拼成一张图。`count` 只表示同一候选的独立生成版本数，每个结果必须作为独立图片版本展示和选择，不得合并为一张长图。互不依赖的素材节点应同批执行并收集真实任务 ID，再并发 `task wait`，不得等待一个完成后才提交下一个；存在上游依赖（例如假道具依赖真道具参考图、童年形象依赖成年形象参考图）时必须按依赖顺序分批执行，参考图未选定 selected version 前不得提交下游派生节点。每个任务都必须到成功终态，并让用户确认后为每项素材设置 selected version。任一素材未生成成功、未确认或没有 selected version 时，禁止执行 `storyboard-breakdown`，先询问用户并补齐。
+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`，不得重复手工创建，并通过“分镜素材连线门禁”。
 5. 生成分镜图前，必须先通过“分镜素材连线门禁”。再用 `canvas asset get/list` 取得人物、场景、道具等已选版本，必要时下载，并把实际图片或可访问预览展示给用户；只提供资产 ID、文件路径或文字说明不算展示。用户明确确认素材与选版后，读取 `storyboard-image` 的实时 `configSchema`，用户未指定画幅且 schema 支持时将 `aspectRatio: 16:9` 显式写入节点，再分析每个镜头的动作阶段、运镜变化、多人调度和连续性难度，选择 schema 允许的最小够用格数：简单镜头建议 4 格，常规镜头使用默认 6 格，复杂镜头建议 9 格，16/25 格只用于用户明确需要的长动作或高密度关键帧。向用户展示逐镜建议并确认后，将各自 `gridSize` 写入对应节点；旧服务 schema 未暴露字段时不得虚假写入，应说明限制并回退到项目有效值，`gridSize` 未另行确认时为 6 格。连续叙事优先建议 `imageLayout: storyboard`，同时说明 `grid` 与 `single` 可选，最终由用户确认布局、镜头范围、参考资产、模型与费用范围。未展示、未确认或连线门禁未通过时禁止生成分镜图。
-6. 执行分镜图后按“生成后自我审计”检查任务、配置和真实产物，并把实际分镜图或可访问预览展示给用户。用户明确确认分镜图以及需要制作的视频镜头后，先运行 `canvas continuity analyze --project <projectId> --json`，在任何视频任务提交前取得相邻镜头依赖、等待关系和当前可修复项；不得先生成全部视频再分析。依赖前一镜尾帧的镜头必须等待前一镜视频成功，随后运行 `canvas continuity analyze --project <projectId> --apply-ready --json` 创建提帧节点与连线，再提交下一镜。之后才能复用服务端自动创建的 `storyboard-video-prompt`；宫格和故事版均先按实际布局重写完整视频提示词，再经用户确认后执行自动创建的 `video-generate`。默认把完整宫格或故事版作为视频参考，不预先拆格；先审计首轮视频，只有动作顺序、构图、关键帧遵循或画面质量明显不佳，或实时模型能力不支持完整分镜参考时，才向用户展示问题与拆格方案。用户确认后再创建、连接并执行拆分节点，只用拆分结果重跑受影响镜头；不得自动拆格或自动付费重跑。为给后续剪辑留余量，设镜头目标时长为 `d`：`0 < d <= 5` 时生成 5 秒，`5 < d <= 10` 时生成 10 秒，`10 < d <= 15` 时生成 15 秒；保留原目标时长供剪辑裁切，不得为了凑生成档位改写叙事时长。`d` 缺失或非法时默认生成 5 秒；`d > 15` 时先拆镜或取得用户确认。最终值必须由实时 `video-generate.configSchema` 支持；模型不支持目标档位时，展示可用选项并在付费生成前确认，不得静默缩短。音频按交付范围执行。未展示或未确认分镜图时禁止生成视频。
+6. 执行分镜图后按“生成后自我审计”检查真实产物，并展示给用户确认。新分镜直接读取 `independent` / `previous-tail`，服务端自动协调“前镜视频 → 尾帧提取 → 后镜 start-frame”；先生成前镜和当前尾帧，再提交后镜。依赖未完成、尾帧来自旧视频版本，或模型仅支持 reference 时，服务端返回 `CANVAS_VIDEO_CONTINUITY_REQUIRED`，不得改接普通参考图绕过。之后复用自动创建的 `storyboard-video-prompt`，按实际布局重写视频提示词并确认后执行 `video-generate`。镜头建议时长按正常剧情节拍、口播和动作确定，首尾保留约 1–2 秒剪辑余量；不为命中全片总时长机械扩镜。执行时按当前模型合法时长档位换算，保留原建议时长供剪辑裁切。未展示或未确认分镜图时禁止生成视频。
 7. 配置门禁固定用一次 `canvas settings set` 写入确认字段；通过门禁后的同阶段节点与连线变更优先合并为一次 `canvas apply`，批量不可用或按“核心原则”处理后仍失败时才回退专用 node/edge 单条命令。每次执行都读取真实任务 ID 并 `task wait`，不用固定 sleep。
 8. 每批图片、视频或音频生成完成后必须先通过“生成后自我审计”，才能报告成功、请求选版或进入下一付费阶段。在进入视频生成前，必须额外依次执行：(a)“镜头级素材审计”全量清单，核对 reference 集合覆盖镜中人物/场景/道具、无跨类型错边、成对资源引用正确版本、stale 清零、道具词扫 description 兜底、资源文字设定贯穿到 shot/image；(b)“上下镜连续性审计”，按时序逐对相邻镜核对人物位置、道具状态、光影色调、动势视线、景别节奏、叙事桥接，并给有动作连续关系的镜组互加 reference、给极端特写/物证镜补入必要的人物 reference；(c)“分镜逻辑审计”，对照叙事期望逐项扫掉关键词误命中、真假道具互串、跨段同名实体误连、黑场/空镜多余连线、多版本角色（成年/童年）误连、龙套角色引用主角资源等问题，输出逐镜审计表并精确删/加边直到 wired=plan；(d) 把图像模型的已知先验 bias（数字、具象动物、实体面具、中文字样等）列入视频阶段 prompt 的 negative 约束。交付前再次确认 selected version 与下载目录，记录项目、节点、任务和资产 ID、审计结论、失败项与未决项。临时项目在所有结束路径删除；既有项目绝不擅自删除。
 
@@ -167,7 +173,7 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
 - 开始或恢复操作时先读取最新画布、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 链路重跑，历史版本继续保留。
-- 视频输入按模型实时能力选择严格首尾帧、普通首帧图生视频或多图参考；`video-frame-extract` 与连续性关系先展示建议，用户确认后才写入，另行确认后才执行任务。
+- 视频输入按模型实时能力选择严格首尾帧、普通首帧图生视频或多图参考。新分镜以规划产物的 `continuity` 为准：`previous-tail` 会自动物化“前镜视频 → 尾帧提取 → 后镜 start-frame”，CLI 不再自行猜测或手工补规划边；执行视频仍需用户确认。
 - 原始视频交付只下载每镜已选中的 MP4，按镜号命名 `S001.mp4`、`S002.mp4`……；字幕在编排/交付层单独生成，不烧录进原始视频。`manifest` 每行至少记录 `shotNumber`、`nodeId`、`assetId`、`versionId`、`fileName`，不得混入分镜图、音频中间件或烧录字幕版本。
 
 ## 安全边界
@@ -181,9 +187,9 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
 - `project provider get` 只返回配置状态。`project provider set` 的 JSON 必须来自安全 stdin 或不入库的临时秘密文件，禁止把 Key 写进命令参数、仓库文件或会回显的 shell 历史。
 - 删除用户既有项目、覆盖完整画布或修改模型配置前，先明确目标和影响；没有授权就停在读取或生成变更计划。
 - `canvas apply` 只用于节点、连线、删除、视口等低层图补丁，不能代替 `canvas settings set`。同阶段有多个图变更时优先一次批量提交；批量失败按“核心原则”分类处理，不能通过逐条重试绕过权限、schema、业务门禁或付费确认。CLI 保存显式请求完整画布响应；正常保存不额外预读全图，遇到 409 才重新读取、合并并确认后重试。项目配置遇到 409 时也必须重新读取和确认。
-- 编辑 `storyboard-shot` 必须使用 `canvas node edit-shot`。该命令追加人工资产版本并固定选版，不允许修改 `shotKey`、`shotIndex` 或来源身份；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"}`。新节点按实时能力选择严格首尾帧、普通首帧图生视频或多图参考；未声明新版语义的历史节点保持旧参考图行为。连续性和拆格关系必须先展示建议，只有用户确认后才能写入；创建节点或连线不等于执行或付费，运行前仍须确认。
+- 手工提取视频首帧或尾帧时先从实时目录确认 `video-frame-extract`，配置 `{"position":"first"}` 或 `{"position":"last"}`。新规划镜头的连续拓扑由服务端自动协调；没有 `continuity` 的历史镜头仍可使用只读启发式分析。创建连续拓扑不执行模型、不付费，运行视频前仍须确认。
 
 ## 示例
 

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

@@ -21,7 +21,7 @@ ai-short-studio skill status --target codex --json
 ai-short-studio skill update --target codex --json
 ```
 
-`--target agents` 安装到 `~/.agents/skills`，`--directory` 可指定其他目录。更新不会覆盖用户修改，除非显式传入 `--force`。
+`--target agents` 安装到 `~/.agents/skills`。`--root` 指定全部内置 Skills 的父目录；兼容参数 `--directory` 只管理主 CLI Skill，并把参数值作为精确安装目录。更新不会覆盖用户修改，除非显式传入 `--force`。
 
 ## 认证
 
@@ -120,11 +120,11 @@ ai-short-studio canvas edge delete <edgeId> --project <projectId> --yes --json
 
 网页增量保存使用 `Prefer: return=minimal` 获取固定大小回执；CLI 的后续命令依赖完整画布，因此显式使用 `Prefer: return=representation`。正常保存前不额外读取全图；发生 409 时重新读取最新画布、合并本地补丁并确认后重试。
 
-`canvas node edit-shot` 的文件或 stdin 内容是镜头字段对象。命令读取当前画布版本和当前资产选版后追加一个人工 DOCUMENT 版本；`shotKey`、`shotIndex` 和来源身份不可修改，旧版本不会被覆盖或删除。
+`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 资产版本并记录来源视频版本。新视频节点按实时 capability 选择严格首尾帧、普通首帧图生视频或多图参考；历史节点保留旧语义。连续性与拆格建议需用户确认才写入，节点与连线创建后仍需另行确认执行，不会自动付费。
+首尾帧提取使用实时目录中的 `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；字幕单独交付，不混入分镜图、音频中间件或烧录字幕版本。
 
@@ -137,7 +137,7 @@ ai-short-studio canvas continuity analyze --project <projectId> --json
 ai-short-studio canvas continuity analyze --project <projectId> --apply-ready --json
 ```
 
-默认命令在视频生成前只读分析相邻镜头、故事板 lineage、视频模型能力和现有连线，不创建节点或任务。`dependencies` 中的 `waiting-for-source-video` 表示必须先生成上一镜；上一镜成功后再次分析，使用 `--apply-ready` 原子创建当前可用的尾帧提取节点和目标连线。它不会运行视频节点，也不能替代生成后的真实画面审计。
+该命令主要用于没有 `continuity` 的历史镜头和人工审计。新规划镜头直接读取 `independent` 或 `previous-tail`；当前后视频节点出现后，服务端自动创建稳定尾帧提取节点与 `start-frame` 连线。前镜视频或当前尾帧未完成时，运行后镜会返回 `CANVAS_VIDEO_CONTINUITY_REQUIRED`；reference-only 模型不能满足严格连续性。`--apply-ready` 仅保留给旧启发式建议，不用于新规划关系。
 
 ### Meme 专属节点流程