@aswless_854771076/ai_short_studio_cli 0.1.16 → 0.1.18

package/README.md

@@ -34,7 +34,8 @@ CLI 只把 refresh token 保存到系统钥匙串，access token 仅驻留内存
 
 - `ai-short-studio preflight`：创作前版本、连通性、认证和模型配置检查。
 - `ai-short-studio project`：无限画布项目增删改查。
-- `ai-short-studio canvas get|apply`：读取或批量更新画布。
+- `ai-short-studio canvas settings get|set`：读取或原子更新项目配置。
+- `ai-short-studio canvas get|apply`：读取画布或执行低层图补丁。
 - `ai-short-studio canvas node`：节点类型/schema 查询、节点读写、执行。
 - `ai-short-studio canvas edge`：连线读写。
 - `ai-short-studio canvas asset`：资产列表、上传、版本选择和下载。
@@ -47,6 +48,32 @@ ai-short-studio canvas edge delete <edgeId> --project <projectId> --yes --json
 ai-short-studio canvas asset select-version <assetId> --project <projectId> --version <versionId> --json
 ```
 
+## 项目配置
+
+```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" --file settings.json --json
+```
+
+`settings get` 为每个字段返回项目覆盖值 `currentValue`、继承后的 `effectiveValue` 和来源 `source`。画风、画幅、分镜与模型候选使用服务端实时 `options`，`visualBible` 使用 `schema`；CLI 不硬编码枚举。示例中的 `$ART_STYLE_ID` 必须从 `artStyle.options` 选择并解析真实 `option.value`。
+
+标准创作门禁必须用 `--file` 或 stdin 批量写入，并把最近一次 `settings get` 返回的 `version` 填入请求的 `expectedVersion`；`--field/--value` 只适合已确认无并发写入的交互式便利操作。批量文件一次原子更新：
+
+```json
+{
+  "expectedVersion": 3,
+  "values": {
+    "aspectRatio": "9:16",
+    "storyboardGridSize": 4,
+    "videoModel": null
+  }
+}
+```
+
+`null` 或空字符串会清除项目覆盖并恢复继承。设置 `artStyle` 会把当前关联的 `visualBible` 保存为项目快照，画风库后续变化不会反向更新项目；同一请求显式传入 `visualBible` 时以显式值为准。所有者和管理员可写，协作者只读；409 冲突后重新 `settings get` 并携带新 `expectedVersion` 重试。`canvas apply` 仍用于节点、连线和视口等低层画布图补丁；Pexels 继续使用 `project provider get|set|test`。
+
 CLI 通过 `/api/v1/bootstrap` 完成版本、连通性与 Supabase 公共配置预检，并直接使用现有 `/api/projects`、`/api/canvas/node-types`、项目画布与资产路由。
 
 运行 `ai-short-studio <topic> --help` 查看精确参数。可执行命令使用完整产品名 `ai-short-studio`，同时避免与其他 CLI 冲突。所有结构化响应保持 JSON；API 错误也返回稳定的 `error.code`、`status`、`retryable` 和 `details`。

package/dist/commands/canvas/settings/get.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../../../base-command.js';
+export default class CanvasSettingsGet extends BaseCommand {
+    static flags: {
+        project: import("@oclif/core/interfaces").OptionFlag<string, 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/settings/get.js

@@ -0,0 +1,10 @@
+import { BaseCommand } from '../../../base-command.js';
+import { commandApi, projectFlag } from '../../../command-helpers.js';
+export default class CanvasSettingsGet extends BaseCommand {
+    static flags = { ...BaseCommand.baseFlags, project: projectFlag };
+    async run() {
+        const { flags } = await this.parse(CanvasSettingsGet);
+        const { api } = await commandApi(flags);
+        this.print(await api.canvasSettings(flags.project));
+    }
+}

package/dist/commands/canvas/settings/set.d.ts

@@ -0,0 +1,23 @@
+import { BaseCommand } from '../../../base-command.js';
+type CanvasSettingsFlags = {
+    field?: string;
+    file?: string;
+    value?: string;
+};
+type ReadInput = (file?: string) => Promise<Record<string, unknown>>;
+export declare function parseSettingFlagValue(value: string): unknown;
+export declare function buildCanvasSettingsInput(flags: CanvasSettingsFlags, readInput?: ReadInput): Promise<Record<string, unknown>>;
+export default class CanvasSettingsSet extends BaseCommand {
+    static flags: {
+        project: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        field: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        value: import("@oclif/core/interfaces").OptionFlag<string | undefined, 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>;
+}
+export {};

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

@@ -0,0 +1,55 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../../base-command.js';
+import { commandApi, projectFlag, readJsonInput } from '../../../command-helpers.js';
+export function parseSettingFlagValue(value) {
+    const input = value.trim();
+    const structured = input.startsWith('{') || input.startsWith('[');
+    if (input === 'null' || input === 'true' || input === 'false')
+        return parseFiniteJson(input);
+    try {
+        const parsed = parseFiniteJson(input);
+        if (structured)
+            return parsed;
+        return typeof parsed === 'number' ? parsed : value;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'JSON 数字必须是有限值')
+            throw error;
+        if (structured)
+            throw new Error('--value 以 { 或 [ 开头时必须是合法 JSON');
+        return value;
+    }
+}
+function parseFiniteJson(value) {
+    return JSON.parse(value, (_key, parsed) => {
+        if (typeof parsed === 'number' && !Number.isFinite(parsed))
+            throw new Error('JSON 数字必须是有限值');
+        return parsed;
+    });
+}
+export async function buildCanvasSettingsInput(flags, readInput = readJsonInput) {
+    const hasField = flags.field !== undefined;
+    const hasValue = flags.value !== undefined;
+    const hasFile = flags.file !== undefined;
+    if (hasFile && (hasField || hasValue))
+        throw new Error('--file 不能与 --field 或 --value 同时使用');
+    if (hasField !== hasValue)
+        throw new Error('必须同时提供 --field 和 --value');
+    if (hasField && hasValue)
+        return { values: { [flags.field]: parseSettingFlagValue(flags.value) } };
+    return readInput(flags.file);
+}
+export default class CanvasSettingsSet extends BaseCommand {
+    static flags = {
+        ...BaseCommand.baseFlags,
+        project: projectFlag,
+        field: Flags.string({ description: '要更新的设置字段', dependsOn: ['value'], exclusive: ['file'] }),
+        value: Flags.string({ description: '字段值', dependsOn: ['field'], exclusive: ['file'] }),
+        file: Flags.string({ description: '设置 JSON 文件；省略时读取 stdin', exclusive: ['field', 'value'] }),
+    };
+    async run() {
+        const { flags } = await this.parse(CanvasSettingsSet);
+        const { api } = await commandApi(flags);
+        this.print(await api.updateCanvasSettings(flags.project, await buildCanvasSettingsInput(flags)));
+    }
+}

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

@@ -45,6 +45,8 @@ export declare class VvicatApi {
     testProjectMaterialProvider(projectId: string): Promise<JsonObject>;
     deleteProject(projectId: string): Promise<JsonObject>;
     canvas(projectId: string): Promise<CanvasDto>;
+    canvasSettings(projectId: string): Promise<JsonObject>;
+    updateCanvasSettings(projectId: string, input: JsonObject): Promise<JsonObject>;
     listNodes(projectId: string): Promise<CanvasNode[]>;
     node(projectId: string, nodeId: string): Promise<CanvasNode>;
     listEdges(projectId: string): Promise<JsonObject[]>;

package/dist/domain/vvicat-api.js

@@ -11,6 +11,14 @@ export class VvicatApi {
         return payload.projects.filter((project) => project.type === 'INFINITE_CANVAS');
     }
     async createProject(input) {
+        const config = await this.config();
+        const defaultModels = config.defaultModels;
+        const analysisModel = defaultModels && typeof defaultModels === 'object' && !Array.isArray(defaultModels)
+            ? defaultModels.analysisModel
+            : null;
+        if (typeof analysisModel !== 'string' || !analysisModel.trim()) {
+            throw new Error('创建项目前请先配置默认分析模型');
+        }
         return this.client.request('/api/projects', { method: 'POST', body: { ...input, type: 'INFINITE_CANVAS' } });
     }
     project(projectId) {
@@ -35,6 +43,12 @@ export class VvicatApi {
         const payload = await this.client.request(`/api/projects/${projectId}/canvas`);
         return payload.data.canvas;
     }
+    canvasSettings(projectId) {
+        return this.client.request(`/api/projects/${projectId}/canvas/settings`);
+    }
+    updateCanvasSettings(projectId, input) {
+        return this.client.request(`/api/projects/${projectId}/canvas/settings`, { method: 'PATCH', body: input });
+    }
     async listNodes(projectId) {
         return (await this.canvas(projectId)).nodes;
     }

package/package.json

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

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

@@ -15,29 +15,29 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
 
 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 时，把 `missing` 一次性告知用户并询问如何补齐；新配置模型首选公司的 [StarRouter](https://starrouter.io/)，账号开通联系邱茂。
-3. 运行账户级只读命令 `ai-short-studio config get --json`，取得账户默认模型及可用 provider；此步骤只用于计算继承后的有效模型，不得用 `config set` 改账户配置来完成项目配置。
+3. 运行账户级只读命令 `ai-short-studio config get --json`，取得账户默认模型及可用 provider。创建项目至少要求已配置 `defaultModels.analysisModel`；缺失时 `project create` 会在发送创建请求前停止，需先由用户在设置中心完成配置。此步骤只用于计算继承后的有效模型，不得用 `config set` 改账户配置来完成项目配置。
 4. 运行 `ai-short-studio canvas node types --json`，按实时 `inputSchema`、`outputSchema`、`configSchema` 和 `defaultConfig` 确定能力与必填项。
-5. 运行 `project list` 判断目标是新项目还是既有项目。新项目按“确认名称和用途 → `project create` → `project get` + `canvas get`”继续；既有项目直接运行 `project get` + `canvas get`。这些项目与画布读取只用于确认 `INFINITE_CANVAS`、当前 `settings`、现有节点、资产 selected version 和本次创作参数；不得要求尚未创建的新项目先执行 `project get` 或 `canvas get`。任何缺口仍按核心原则询问。
+5. 运行 `project list` 判断目标是新项目还是既有项目。新项目先确认账户默认分析模型已配置，再按“确认名称和用途 → `project create` → `project get` + `canvas get` + `canvas settings get`”继续；未通过模型审查时不得尝试创建。既有项目直接运行这三个读取命令。它们只用于确认 `INFINITE_CANVAS`、项目配置、现有节点、资产 selected version 和本次创作参数；不得要求尚未创建的新项目先读取项目或画布。任何缺口仍按核心原则询问。
 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. 向用户展示项目名称与用途，并逐项确认以下画布设置的“当前值、继承后的有效值、建议值、来源/继承关系”：`aspectRatio`、`artStyle`、`visualBible`、`storyboardImageType`、`analysisModel`、`imageModel`、`editModel`、`videoModel`、`audioModel`。模型既可写为项目覆盖，也可由用户明确确认继承账户默认；无论哪种方式，都必须列明每个所需模型最终生效的具体模型，并确认该模型当前可用。缺失、冲突或继承结果不明确时先一次性询问。
+1. 运行 `canvas settings get --project <projectId> --json`，向用户展示项目名称与用途，并逐项确认以下设置的项目覆盖值 `currentValue`、继承后的 `effectiveValue`、建议值和来源 `source`：`aspectRatio`、`artStyle`、`visualBible`、`storyboardImageType`、`analysisModel`、`imageModel`、`editModel`、`videoModel`、`audioModel`。画风、画幅、分镜和模型候选必须读取服务端实时 `options`；`visualBible` 按返回的 `schema` 构造，不得硬编码枚举或结构。模型既可写为项目覆盖，也可由用户明确确认继承账户默认，但必须列明最终生效且当前可用的具体模型。缺失、冲突或继承结果不明确时先一次性询问。
 2. `storyboardGridSize` 不是统一创作默认值，只在无法按节点设置 `gridSize` 的异常回退场景中展示并取得用户确认。正常流程仍按镜头复杂度逐个设置节点 `gridSize`，不得因项目 settings 已有该字段而套用统一格数。
-3. 新项目按初始化顺序确认名称和用途、创建项目并取得项目与画布；既有项目开始创作前也必须完成本门禁，名称或用途需要更新时只用 `project update` 修改用户确认的项目字段。用途可记录在项目描述中，但描述不构成画布 settings。不得用账户级 `config set`、项目 `description` 或节点 `prompt`/`config` 代替画布 `settings`。
-4. 配置写入窗口内必须避免其他客户端或用户并发修改项目 settings；无法确保时停在配置阶段，请用户协调后再继续。执行 `canvas apply` 前立即再运行一次 `canvas get`，以这次读取的完整 settings 为基线重新合并，仅改变用户确认字段并原样保留其余字段；如果相对用户刚确认的快照有任何字段变化，先展示变化字段并重新确认，再用一次 `canvas apply` 写入完整目标 settings。
-5. 写入后立即再次执行 `canvas get`，把回读的完整 settings（包括应原样保留的字段）与本次写入的完整目标 settings 做整体比较。只有两者完全一致、继承后的所需模型明确且可用时，才可创建或执行创作节点。写入或回读失败、字段被权限规则忽略、结果不一致时，停在配置阶段，不触发任何付费任务。
+3. 新项目按初始化顺序确认名称和用途、创建项目并取得项目、画布与 settings；既有项目开始创作前也必须完成本门禁，名称或用途需要更新时只用 `project update` 修改用户确认的项目字段。用途可记录在项目描述中，但描述不构成画布 settings。不得用账户级 `config set`、项目 `description` 或节点 `prompt`/`config` 代替 `canvas settings set`。
+4. 用户确认后，用一次 `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` 时以显式值为准。
+5. 写入后立即再次执行 `canvas settings get`，比较所有目标字段的 `currentValue`、`effectiveValue` 和 `source`。只有结果符合用户确认且所需模型明确可用，才可创建或执行创作节点。409 冲突时重新读取、展示变化并取得确认，携带新 `expectedVersion` 重试；不得盲目覆盖。所有者和管理员可写，协作者只读；写入、回读或权限校验失败时停在配置阶段，不触发任何付费任务。
 
 ## 标准创作流程
 
 1. 明确原始故事或剧本、目标受众与平台、语言、画幅、总时长与镜头时长、风格参考、人物/场景/道具约束，以及交付是否包含剧本、设定、分镜图、视频和音频；缺项先问。
-2. 完成 preflight、账户配置读取和节点目录检查后，新项目按“project list → 确认名称/用途 → project create → project get + canvas get”继续，既有项目按“project list/get → canvas get”继续；再按“项目配置门禁”逐项确认、写入并回读完整画布 settings。两种项目都必须在任何创作节点之前通过门禁；既有项目只修改用户确认字段，并优先复用已确认的节点与 selected version。
+2. 完成 preflight、账户配置读取和节点目录检查后，新项目按“project list → 确认名称/用途 → project create → project get + canvas get + canvas settings get”继续，既有项目读取相同的已有资源；再按“项目配置门禁”确认、原子写入并回读 settings。两种项目都必须在任何创作节点之前通过门禁；既有项目只修改用户确认字段，并优先复用已确认的节点与 selected version。
 3. 原文需要改编时执行 `novel-to-script`。分镜拆解前必须先完成人物、场景、道具等本次故事涉及的素材生成；互不依赖的素材节点应同批执行并收集真实任务 ID，再并发 `task wait`，不得等待一个完成后才提交下一个；存在上游依赖时按依赖顺序分批执行。每个任务都必须到成功终态，并让用户确认后为每项素材设置 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、文件路径或文字说明不算展示。用户明确确认素材与选版后，逐镜头评估需要独立呈现的关键状态（起势、动作或表情变化、人物与道具关系变化、机位或视角变化、空间调度和结果），把 `gridSize` 设为实时 schema 允许值中能够完整表达这些状态的最小值：单一静态状态用 1 格，一般连续变化优先 4 格，多阶段动作或复杂调度再用 6/9 格，只有确实存在更多不可合并状态时才用 12 格以上；不得全项目固定同一格数，也不得只按镜头时长决定。向用户列出“镜号、复杂度依据、建议格数”并确认；连续叙事优先建议 `imageLayout: storyboard`，同时说明 `grid` 与 `single` 可选，最终由用户确认布局、镜头范围、参考资产、模型与费用范围。未展示或未确认时禁止生成分镜图。
 6. 执行分镜图后检查任务终态、候选资产与 selected version，并把实际分镜图或可访问预览展示给用户。用户明确确认分镜图以及需要制作的视频镜头后，才能刷新画布并复用服务端自动创建的 `storyboard-video-prompt`；提示词再经用户确认后执行自动创建的 `video-generate`，音频按交付范围执行。未展示或未确认分镜图时禁止生成视频。
-7. 配置门禁固定用一次 `canvas apply` 写入合并后的 settings；通过门禁后的节点与连线写入，仍需在每次写入前重新读取画布版本，优先用专用 node/edge 命令，批量变更才用 `canvas apply`。每次执行都读取真实任务 ID 并 `task wait`，不用固定 sleep。
+7. 配置门禁固定用一次 `canvas settings set` 写入确认字段；通过门禁后的节点与连线写入，仍需在每次写入前重新读取画布版本，优先用专用 node/edge 命令，批量图变更才用低层 `canvas apply`。每次执行都读取真实任务 ID 并 `task wait`，不用固定 sleep。
 8. 交付前确认 selected version 与下载目录，记录项目、节点、任务和资产 ID、失败项与未决项。临时项目在所有结束路径删除；既有项目绝不擅自删除。
 
 Meme 推荐链路为 `text.text → meme-scene-analysis.story`，运行后把自动生成的计划资源连接到 `meme-material-search.plan`，再把素材包资源连接到 `cat-meme-video.materials`；原故事仍连接 `cat-meme-video.story`，计划资源可同时连接 `cat-meme-video.plan`。每一步完成后刷新画布，使用服务端自动创建的资源节点，不能伪造或重复创建资源。`cat-meme-video` 的 `config` 需按实时 schema 确认 `aspectRatio`（`1:1`、`9:16` 或 `16:9`）与 `resolution`（`720p` 或 `1080p`）；它们是节点输出参数，不替代项目配置门禁。
@@ -60,13 +60,17 @@ Meme 推荐链路为 `text.text → meme-scene-analysis.story`，运行后把自
 - `config get` 只应返回 `hasApiKey`，不得依赖或要求服务端回显密钥。
 - `project provider get` 只返回配置状态。`project provider set` 的 JSON 必须来自安全 stdin 或不入库的临时秘密文件，禁止把 Key 写进命令参数、仓库文件或会回显的 shell 历史。
 - 删除用户既有项目、覆盖完整画布或修改模型配置前，先明确目标和影响；没有授权就停在读取或生成变更计划。
-- `canvas apply` 提交的版本字段不能替代项目 settings 的排他写入窗口；无法协调其他客户端或用户暂停修改时，停在配置阶段。
+- `canvas apply` 只用于节点、连线、视口等低层图补丁，不能代替 `canvas settings set`。项目配置遇到 409 时必须重新读取和确认。
 
 ## 示例
 
 ```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" --file settings.json --json
 ai-short-studio canvas node add text --project "$PROJECT_ID" --config ./node.json --json
 ai-short-studio canvas node list --project "$PROJECT_ID" --json
 ```
@@ -77,8 +81,8 @@ ai-short-studio canvas node list --project "$PROJECT_ID" --json
 
 - 节点类型写死：先读 `canvas node types`，服务端目录才是事实来源。
 - 配置不全仍继续：先做初始化检查；模型、项目或用户意图有缺口时先询问。
-- 把项目配置写到错误位置：画幅、画风、视觉圣经、故事版类型和模型必须通过 `canvas apply` 写入项目 settings；账户级 `config set`、项目描述或节点 prompt/config 都不能替代。
-- 写完 settings 就创建节点：必须 `canvas get` 回读完全一致，并确认继承后的最终有效模型可用；失败或冲突时停在配置阶段，不触发付费任务。
+- 把项目配置写到错误位置：画幅、画风、视觉圣经、故事版类型和模型必须通过 `canvas settings set` 写入；`canvas apply`、账户级 `config set`、项目描述或节点 prompt/config 都不能替代。
+- 写完 settings 就创建节点：必须 `canvas settings get` 回读并确认 `currentValue`、`effectiveValue`、`source` 和最终模型；失败或冲突时停在配置阶段，不触发付费任务。
 - CLI 有更新仍用旧进程继续：更新后必须重跑 preflight。
 - 注册成功就假定已登录：`confirmationRequired: true` 表示需要先完成邮件验证，再执行 `auth login`。
 - 自动创建的下游节点重复添加：任务完成后先刷新画布并复用真实节点 ID。

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

@@ -59,6 +59,34 @@ 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" --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": 4,
+    "videoModel": null
+  }
+}
+```
+
+`null` 或空字符串会清除项目覆盖并恢复账户默认或系统默认继承。设置 `artStyle` 时，服务端会把画风当前关联的 `visualBible` 保存为项目快照；画风库后续修改不会反向更新既有项目。同一请求显式提供 `visualBible` 时，显式值覆盖画风快照。
+
+所有者和管理员可执行 `settings set`，协作者只能执行 `settings get`。批量写入是原子的；建议携带最近一次读取的 `expectedVersion`，遇到 409 后重新运行 `settings get`、核对变化并取得确认，再携带新版本重试，不得盲目覆盖。Pexels 配置仍由 `project provider get|set|test` 管理，不属于 canvas settings。
+
 ## 画布和节点
 
 ```bash
@@ -73,9 +101,7 @@ 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`，但这不为 settings 提供可靠的条件写保护。项目配置补丁使用顶层 `settings`，其值是从 `canvas get` 当前 settings 合并用户确认字段后得到的完整对象，不是只含变更字段的局部对象；写入期间仍需避免其他客户端或用户并发修改项目 settings。
-
-现有 `visualBible` 必须从 `canvas get` 原样保留；需要修改时，必须使用项目或服务端返回的完整 `VisualBibleV1`。禁止写入空对象或占位对象，也不要自行编造视觉圣经结构。`storyboardGridSize` 仅在节点级 `gridSize` 无法使用的异常回退中经用户确认后写入；正常流程继续按镜头复杂度设置各节点的 `gridSize`。
+`canvas apply` 的 JSON 可以通过 `--file` 读取；省略文件时从 stdin 读取。CLI 会在提交前读取当前画布版本并携带 `canvasId` 与 `expectedVersion`。该命令保留给节点、连线、视口等低层画布图补丁；常规项目配置使用 `canvas settings get|set`。`storyboardGridSize` 仅在节点级 `gridSize` 无法使用的异常回退中经用户确认后写入；正常流程继续按镜头复杂度设置各节点的 `gridSize`。
 
 ## 连线
 
@@ -120,11 +146,11 @@ ai-short-studio config set --file <config.json> --json
 
 ## 标准创作命令顺序
 
-先只读执行 `preflight` → `config get` → `canvas node types` → `project list`。新项目随后按“确认名称/用途 → `project create` → `project get` + `canvas get`”继续，不要求创建前读取不存在的项目或画布；既有项目按“`project get` → `canvas get`”继续。现有节点和资产也只读检查。
+先只读执行 `preflight` → `config get` → `canvas node types` → `project list`。新项目随后按“确认名称/用途 → `project create` → `project get` + `canvas get` + `canvas settings get`”继续，不要求创建前读取不存在的项目或画布；既有项目读取同样的已有资源。现有节点和资产也只读检查。
 
-取得画布后，向用户展示项目名称/用途，并逐项确认 `aspectRatio`、`artStyle`、`visualBible`、`storyboardImageType`、`analysisModel`、`imageModel`、`editModel`、`videoModel`、`audioModel` 的当前值、继承后的有效值、建议值与来源；模型可项目覆盖，也可由用户明确确认继承账户默认，但必须明确最终生效且可用的具体模型。`storyboardGridSize` 仅在异常回退时确认。
+取得配置后，向用户展示项目名称/用途，并逐项确认 `aspectRatio`、`artStyle`、`visualBible`、`storyboardImageType`、`analysisModel`、`imageModel`、`editModel`、`videoModel`、`audioModel` 的 `currentValue`、`effectiveValue`、建议值与 `source`；候选值和视觉圣经结构分别以实时 `options` 与 `schema` 为准。模型可项目覆盖，也可由用户明确确认继承账户默认，但必须明确最终生效且可用的具体模型。`storyboardGridSize` 仅在异常回退时确认。
 
-项目名称和用途先由用户确认；新项目用 `project create` 保存，既有项目需要变更时仅用 `project update` 修改用户确认的项目字段，用途可记录在 description 中。配置写入窗口内必须避免其他客户端或用户并发修改项目 settings；无法确保时停下并请用户协调。`canvas apply` 前立即执行一次 `canvas get`，以最新完整 settings 为基线重新合并；相对用户刚确认的快照有字段变化时，先展示变化字段并重新确认，再写入一次。随后用 `canvas get` 回读，必须把完整 settings（包括原样保留字段）与写入目标整体比较；只有完全一致且所需模型可用，才执行 node add/edge add/node run。写入、回读或模型校验失败时停在配置阶段，不触发付费任务。账户级 `config set`、项目 `description` 和节点 `prompt`/`config` 都不能替代项目 settings。
+项目名称和用途先由用户确认；新项目用 `project create` 保存，既有项目需要变更时仅用 `project update` 修改用户确认的项目字段。把确认的配置用一次 `canvas settings set` 原子写入并携带 `expectedVersion`，随后再次 `settings get` 回读。只有结果与确认一致且所需模型可用，才执行 node add/edge add/node run。写入、权限、冲突、回读或模型校验失败时停在配置阶段，不触发付费任务。账户级 `config set`、项目 `description`、节点 `prompt`/`config` 和低层 `canvas apply` 都不能替代项目 settings 命令。
 
 执行 `storyboard-breakdown` 前，必须先完成本次故事涉及的全部人物、场景、道具等素材节点：互不依赖的节点先同批执行并收集真实任务 ID，再并发调用 `task wait`；有上游依赖的节点按依赖顺序分批执行，不得为了等待单个任务而串行提交其他独立素材。全部任务成功后，用 `canvas asset get/list` 核对并在用户确认后设置 selected version。随后依据实时 schema，用 `canvas edge add` 将剧本节点和每个相关素材节点分别连接到 `storyboard-breakdown` 对应输入 handle，再用 `canvas get` 与 `canvas edge list` 核对无遗漏。任一素材任务未成功、selected version 为空或对应连线缺失时，都不得执行分镜拆解；素材范围不清楚时先询问用户。即使服务端 schema 把人物、场景或道具输入标为可选，标准创作流程也不能跳过本次故事实际涉及且已确认使用的素材。