@aswless_854771076/ai_short_studio_cli 0.1.32 → 0.1.33

package/README.md

@@ -78,10 +78,12 @@ ai-short-studio canvas settings set --project "$PROJECT_ID" --file settings.json
 }
 ```
 
-`null` 或空字符串会清除项目覆盖并恢复继承。设置 `artStyle` 会把当前关联的 `visualBible` 保存为项目快照，画风库后续变化不会反向更新项目；同一请求显式传入 `visualBible` 时以显式值为准。所有者和管理员可写，协作者只读；409 冲突后重新 `settings get` 并携带新 `expectedVersion` 重试。`canvas apply` 仍用于节点、连线和视口等低层画布图补丁；它显式请求完整画布响应，正常保存不预读全图，409 后才读取最新状态并合并重试。Pexels 继续使用 `project provider get|set|test`。
+`null` 或空字符串会清除项目覆盖并恢复继承。设置 `artStyle` 会把当前关联的 `visualBible` 保存为项目快照，画风库后续变化不会反向更新项目；同一请求显式传入 `visualBible` 时以显式值为准。所有者和管理员可写，协作者只读；409 冲突后重新 `settings get` 并携带新 `expectedVersion` 重试。`canvas apply` 仍用于节点、连线、删除和视口等低层画布图补丁；同阶段有多个可合并图变更时默认一次批量提交并统一回读，批量入口不可用或合法批量请求仍因粒度失败时才回退单条命令。Pexels 继续使用 `project provider get|set|test`。
 
 使用 `canvas node edit-shot <nodeId> --project <projectId> --file shot.json` 编辑镜头。命令会追加并选中不可变的人工 DOCUMENT 版本，不允许修改 `shotKey`、`shotIndex` 或来源身份，旧版本继续可选。
 
+使用 `canvas node edit-resource <nodeId> --project <projectId> --file resource.json` 编辑剧本、人物、人物视觉、场景、子场景或道具结构化资源。命令只替换完整父文档中的目标实体，追加并选中人工版本；名称、资源键、ID 和所属关系不可修改，兄弟资源节点保持原选版。资源版本写入不属于 `canvas apply` 图补丁，409 后需重新读取画布与当前选版。
+
 CLI 通过 `/api/v1/bootstrap` 完成版本、连通性与 Supabase 公共配置预检，并直接使用现有 `/api/projects`、`/api/canvas/node-types`、项目画布与资产路由。
 
 `canvas node types [kind] --json` 同时兼容节点目录 schema v1/v2，并原样返回动态节点的 `source`、`definitionId` 和 `definitionVersionId`。后台发布后重新执行该命令即可读取新目录；归档节点不能新建，但已有实例仍按画布中的固定版本 schema 更新和执行。CLI 创建节点只提交 `kind` 与配置，版本由服务端固定，不能由客户端伪造。

package/dist/commands/canvas/node/edit-resource.d.ts

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../../../base-command.js';
+export default class CanvasNodeEditResource extends BaseCommand {
+    static args: {
+        nodeId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        project: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        locale: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/canvas/node/edit-resource.js

@@ -0,0 +1,45 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../../base-command.js';
+import { commandApi, projectFlag, readJsonInput } from '../../../command-helpers.js';
+export default class CanvasNodeEditResource extends BaseCommand {
+    static args = { nodeId: Args.string({ required: true }) };
+    static flags = {
+        ...BaseCommand.baseFlags,
+        project: projectFlag,
+        file: Flags.string({ description: '结构化资源 JSON 文件；省略时读取 stdin' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(CanvasNodeEditResource);
+        const { api } = await commandApi(flags);
+        const canvas = await api.canvas(flags.project);
+        const node = canvas.nodes.find((candidate) => candidate.id === args.nodeId);
+        const rawArtifact = node?.data.artifact;
+        const artifact = rawArtifact && typeof rawArtifact === 'object' && !Array.isArray(rawArtifact)
+            ? rawArtifact
+            : null;
+        if (!node || !artifact
+            || artifact.type !== 'GENERATED_RESOURCE'
+            || typeof artifact.operation !== 'string' || !artifact.operation
+            || typeof artifact.resourceKey !== 'string' || !artifact.resourceKey
+            || typeof artifact.resourceType !== 'string' || !artifact.resourceType) {
+            throw new Error(`结构化资源节点不可编辑：${args.nodeId}`);
+        }
+        let basedOnVersionId = typeof node.data.selectedOutputVersionId === 'string'
+            ? node.data.selectedOutputVersionId
+            : '';
+        if (!basedOnVersionId && typeof node.refId === 'string') {
+            const payload = await api.asset(flags.project, node.refId);
+            const asset = payload.asset && typeof payload.asset === 'object' && !Array.isArray(payload.asset)
+                ? payload.asset
+                : {};
+            basedOnVersionId = typeof asset.selectedVersionId === 'string' ? asset.selectedVersionId : '';
+        }
+        if (!basedOnVersionId)
+            throw new Error('结构化资源当前版本不存在');
+        this.print(await api.updateStructuredResource(flags.project, args.nodeId, {
+            expectedCanvasVersion: canvas.version,
+            basedOnVersionId,
+            resource: await readJsonInput(flags.file),
+        }));
+    }
+}

package/dist/domain/vvicat-api.d.ts

@@ -63,6 +63,7 @@ export declare class VvicatApi {
     }): Promise<JsonObject>;
     patchCanvas(projectId: string, input: JsonObject): Promise<JsonObject>;
     updateStoryboardShot(projectId: string, nodeId: string, input: JsonObject): Promise<JsonObject>;
+    updateStructuredResource(projectId: string, nodeId: string, input: JsonObject): Promise<JsonObject>;
     nodeTypes(): Promise<{
         schemaVersion: 1 | 2;
         catalogRevision?: string;

package/dist/domain/vvicat-api.js

@@ -121,6 +121,11 @@ export class VvicatApi {
             method: 'PATCH', body: input,
         });
     }
+    updateStructuredResource(projectId, nodeId, input) {
+        return this.client.request(`/api/projects/${projectId}/canvas/nodes/${nodeId}/structured-resource`, {
+            method: 'PATCH', body: input,
+        });
+    }
     async nodeTypes() {
         const payload = await this.client.request('/api/canvas/node-types');
         if (payload.data.schemaVersion !== 1 && payload.data.schemaVersion !== 2) {

package/package.json

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

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

@@ -9,6 +9,8 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
 
 把 `ai-short-studio` 当作机器可读的远程控制接口。创作全程只要目标、素材含义、平台、语言、画幅、时长、风格、人物、场景、道具、模型、节点 schema、候选版本、付费范围或覆盖影响存在未知、缺失或矛盾，就合并列出最少必要问题并询问用户；得到答复前只做只读检查，不用示例值或自行推断替用户做创作决定。本文明确规定的 `16:9` 素材画幅和 `5/10/15` 秒视频生成时长是标准流程默认值，用户未另行指定时可直接采用并在执行摘要中说明，不必为这两项单独阻塞。新建或继续任何无限画布项目时，项目配置是创作节点之前的硬门禁：配置写入并回读验证通过前，不得创建或执行任何创作节点。
 
+同一阶段存在两个及以上可合并的写操作时，默认先使用 CLI 已提供的批量入口：项目配置用一次 `canvas settings set --file` 或 stdin，节点、连线、删除和视口等同一画布补丁用一次 `canvas apply --file` 或 stdin。批量提交前读取一次最新画布与实时 schema，构造完整预期差异；成功后统一回读审计。批量命令不存在、当前服务不支持，或合法批量请求在处理批量粒度时失败，才回退到对应的 `canvas node` / `canvas edge` 单条命令，并只处理尚未生效的项。409 先重读、合并并确认后继续重试批量；401/403、参数、schema、业务门禁或付费确认错误必须停下修正，不得用单条命令绕过。`canvas node run`、`task wait`、资产下载等没有批量入口的操作直接使用单条命令，其中互不依赖的任务并发提交或等待。
+
 ## 初始化检查
 
 创建项目或修改任何资源前，按顺序执行：
@@ -37,8 +39,8 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
 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`，先询问用户并补齐。
 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` 支持；模型不支持目标档位时，展示可用选项并在付费生成前确认，不得静默缩短。音频按交付范围执行。未展示或未确认分镜图时禁止生成视频。
-7. 配置门禁固定用一次 `canvas settings set` 写入确认字段；通过门禁后的节点与连线写入，仍需在每次写入前重新读取画布版本，优先用专用 node/edge 命令，批量图变更才用低层 `canvas apply`。每次执行都读取真实任务 ID 并 `task wait`，不用固定 sleep。
+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` 支持；模型不支持目标档位时，展示可用选项并在付费生成前确认，不得静默缩短。音频按交付范围执行。未展示或未确认分镜图时禁止生成视频。
+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、审计结论、失败项与未决项。临时项目在所有结束路径删除；既有项目绝不擅自删除。
 
 ## 分镜素材连线门禁
@@ -162,7 +164,7 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
 
 ## 无限画布成片与交付
 
-- 开始或恢复操作时先读取最新画布、settings 和节点 schema；用 `canvas node edit-shot` 编辑 `storyboard-shot`，每次追加不可变版本，并核对 `selectedOutputVersionId`，不得覆盖历史版本。
+- 开始或恢复操作时先读取最新画布、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` 与连续性关系先展示建议，用户确认后才写入，另行确认后才执行任务。
@@ -178,8 +180,9 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
 - `config get` 只应返回 `hasApiKey`，不得依赖或要求服务端回显密钥。
 - `project provider get` 只返回配置状态。`project provider set` 的 JSON 必须来自安全 stdin 或不入库的临时秘密文件，禁止把 Key 写进命令参数、仓库文件或会回显的 shell 历史。
 - 删除用户既有项目、覆盖完整画布或修改模型配置前，先明确目标和影响；没有授权就停在读取或生成变更计划。
-- `canvas apply` 只用于节点、连线、视口等低层图补丁，不能代替 `canvas settings set`。CLI 保存显式请求完整画布响应；正常保存不额外预读全图，遇到 409 才重新读取、合并并确认后重试。项目配置遇到 409 时也必须重新读取和确认。
+- `canvas apply` 只用于节点、连线、删除、视口等低层图补丁，不能代替 `canvas settings set`。同阶段有多个图变更时优先一次批量提交；批量失败按“核心原则”分类处理，不能通过逐条重试绕过权限、schema、业务门禁或付费确认。CLI 保存显式请求完整画布响应；正常保存不额外预读全图，遇到 409 才重新读取、合并并确认后重试。项目配置遇到 409 时也必须重新读取和确认。
 - 编辑 `storyboard-shot` 必须使用 `canvas node edit-shot`。该命令追加人工资产版本并固定选版，不允许修改 `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"}`。新节点按实时能力选择严格首尾帧、普通首帧图生视频或多图参考；未声明新版语义的历史节点保持旧参考图行为。连续性和拆格关系必须先展示建议，只有用户确认后才能写入；创建节点或连线不等于执行或付费，运行前仍须确认。
 
 ## 示例
@@ -207,6 +210,7 @@ ai-short-studio canvas node list --project "$PROJECT_ID" --json
 - CLI 有更新仍用旧进程继续：更新后必须重跑 preflight。
 - 注册成功就假定已登录：`confirmationRequired: true` 表示需要先完成邮件验证，再执行 `auth login`。
 - 自动创建的下游节点重复添加：任务完成后先刷新画布并复用真实节点 ID。
+- 多项画布写操作逐条执行：同一阶段可合并的节点、连线和删除应先用一次 `canvas apply`；只有批量入口不可用或合法批量请求仍因批量粒度失败时才回退单条命令，不能把权限、schema 或业务错误当作回退理由。
 - 素材未完成或未连线就拆分镜：人物、场景、道具等相关素材必须任务成功、已确认 selected version，并逐项连接到 `storyboard-breakdown` 对应输入后才能执行。
 - 未展示产物就继续：生成分镜图前展示并确认素材，生成视频前展示并确认分镜图；只报告 ID 或路径不能代替预览与用户确认。
 - 所有镜头沿用项目格数却声称已动态配置：实时 schema 提供 `gridSize` 时，必须展示并确认逐镜难度建议，再把数值写入对应节点；只有旧服务未暴露字段时才回退到项目格数，未另行确认时为 6 格。

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

@@ -103,11 +103,12 @@ 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 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 <nodeId> --project <projectId> --json
 ```
 
-`canvas apply` 的 JSON 可以通过 `--file` 读取；省略文件时从 stdin 读取。CLI 会在提交前读取当前画布版本并携带 `canvasId` 与 `expectedVersion`。该命令保留给节点、连线、视口等低层画布图补丁；常规项目配置使用 `canvas settings get|set`。`storyboardGridSize` 仅在节点级 `gridSize` 无法使用的异常回退中经用户确认后写入；正常流程继续按镜头复杂度设置各节点的 `gridSize`。
+`canvas apply` 的 JSON 可以通过 `--file` 读取；省略文件时从 stdin 读取。CLI 会在提交前读取当前画布版本并携带 `canvasId` 与 `expectedVersion`。该命令保留给节点、连线、删除、视口等低层画布图补丁；常规项目配置使用 `canvas settings get|set`。同一阶段存在两个及以上可合并的图变更时，默认用一次 `canvas apply` 提交 `upsertNodes`、`upsertEdges`、`deleteNodeIds` 和 `deleteEdgeIds` 等完整差异，成功后统一回读；批量入口不存在、服务不支持，或合法请求仍因批量粒度失败时，才回退对应的 node/edge 单条命令并只处理尚未生效项。409 应重读、合并并确认后继续重试批量；401/403、参数、schema、业务门禁或付费确认错误必须先修正，不能通过单条命令绕过。节点执行、任务等待和资产下载没有批量入口，互不依赖时使用单条命令并发处理。`storyboardGridSize` 仅在节点级 `gridSize` 无法使用的异常回退中经用户确认后写入；正常流程继续按镜头复杂度设置各节点的 `gridSize`。
 
 ## 连线
 
@@ -121,6 +122,8 @@ ai-short-studio canvas edge delete <edgeId> --project <projectId> --yes --json
 
 `canvas node edit-shot` 的文件或 stdin 内容是镜头字段对象。命令读取当前画布版本和当前资产选版后追加一个人工 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 选择严格首尾帧、普通首帧图生视频或多图参考；历史节点保留旧语义。连续性与拆格建议需用户确认才写入，节点与连线创建后仍需另行确认执行，不会自动付费。
 
 原始视频交付先按镜号读取视频节点的 `selectedOutputVersionId`，再逐个执行 `canvas asset download`，保存为 `S001.mp4`、`S002.mp4`……。同时生成逐行 `manifest`，每行包含 `shotNumber`、`nodeId`、`assetId`、`versionId`、`fileName`。只下载 selected 原始 MP4；字幕单独交付，不混入分镜图、音频中间件或烧录字幕版本。
@@ -183,7 +186,7 @@ ai-short-studio config set --file <config.json> --json
 
 先只读执行 `preflight` → `config get` → `canvas node types` → `project list`。新项目随后按“确认名称/用途 → `project create` → `project get` + `canvas get` + `canvas settings get`”继续，不要求创建前读取不存在的项目或画布；既有项目读取同样的已有资源。现有节点和资产也只读检查。
 
-取得配置后，向用户展示项目名称/用途，并逐项确认 `aspectRatio`、`artStyle`、`visualBible`、`storyboardImageType`、`analysisModel`、`imageModel`、`imageResolution`、`imageQuality`、`editModel`、`videoModel`、`videoResolution`、`audioModel` 的 `currentValue`、`effectiveValue`、建议值与 `source`；候选值和视觉圣经结构分别以实时 `options` 与 `schema` 为准。模型可项目覆盖，也可由用户明确确认继承账户默认，但必须明确最终生效且可用的具体模型。`storyboardGridSize` 仅在异常回退时确认。
+取得配置后，向用户展示项目名称/用途，并逐项确认 `aspectRatio`、`artStyle`、`visualBible`、`storyboardImageType`、`analysisModel`、`imageModel`、`imageResolution`、`imageQuality`、`editModel`、`videoModel`、`videoResolution`、`audioModel` 的 `currentValue`、`effectiveValue`、建议值与 `source`；候选值和视觉圣经结构分别以实时 `options` 与 `schema` 为准。模型可项目覆盖，也可由用户明确确认继承账户默认，但必须明确最终生效且可用的具体模型。`storyboardGridSize` 仅在异常回退时确认。同一阶段的多个画布写操作默认合并到一次 `canvas apply`，批量不可用或合法批量请求仍因批量粒度失败时才回退单条 node/edge 命令。
 
 项目名称和用途先由用户确认；新项目用 `project create` 保存，既有项目需要变更时仅用 `project update` 修改用户确认的项目字段。把确认的配置用一次 `canvas settings set` 原子写入并携带 `expectedVersion`，随后再次 `settings get` 回读。只有结果与确认一致且所需模型可用，才执行 node add/edge add/node run。写入、权限、冲突、回读或模型校验失败时停在配置阶段，不触发付费任务。账户级 `config set`、项目 `description`、节点 `prompt`/`config` 和低层 `canvas apply` 都不能替代项目 settings 命令。