AI Short Studio CLI

VVICAT 新链路无限画布的官方命令行客户端。要求 Node.js 22 或更高版本。截至 2026 年 7 月 28 日，个人包的 npm latest 为 0.1.15；后续以 npm dist-tag 为准。

npm view @aswless_854771076/ai_short_studio_cli dist-tags.latest
npm install --global @aswless_854771076/ai_short_studio_cli@latest
ai-short-studio --version
ai-short-studio auth login
ai-short-studio auth login --provider supabase
ai-short-studio project list --json
ai-short-studio canvas node types --json

npm 包只内置一个 using-vvicat-ai-short-studio-cli Agent Skill。短剧和 humanizer 等参考资料统一放在该 Skill 的 references/ 下。安装或升级 CLI 时，postinstall 会自动安装或更新这个 Skill；用户修改过或不由 CLI 管理的副本不会被覆盖。设置 VVICAT_SKIP_SKILL_INSTALL=1 可关闭自动安装。

短剧默认采用专业拆镜，逐镜保留时间宫格与镜头故事版；count: 1 不表示单格，用户要求只完成分镜图时不执行视频提示词或视频。canvas node edit-shot 会同步镜头字段别名并拒绝改写来源原文；修改时长后检查响应的 durationOverrides，保留的下游手工时长需要逐项确认。普通单帧不能提交为专业双板审核。

skill install/status/update 管理这个唯一 Skill。短剧创作、humanizer 审计和自由画布视频制作资料通过主 Skill 的 references 按需读取。

references/canvas-production-principles.md、references/canvas-inspection.md 与 references/canvas-media-gates.md 是 CLI 与内置 Agent 共用的业务经验正文；CLI 继续按原命令合同执行。内置接入仍在开发验证，不代表侧栏已可用。

生产环境登录使用 MemHub 浏览器授权；兼容 Supabase 的邮箱注册和登录从 stdin 读取密码：

ai-short-studio auth signup --provider supabase --email [email protected] --password-stdin
ai-short-studio auth login --provider supabase --email [email protected] --password-stdin

Agent 代操作时，用户已在当前会话明确提供的密码只能直接写入正在等待的隐藏密码提示，不得复述、拼入 shell 命令、落盘或跨会话保存。

注册响应中的 confirmationRequired 表示是否需要先完成邮件验证。Supabase 直接返回会话时，CLI 会立即登录并把 refresh token 保存到系统钥匙串；需要邮件验证时不会写入空凭据，验证后再执行登录。MemHub 登录成功后使用短期 API Key 访问服务。

注册确认链接使用当前 profile 的 baseUrl 和 --locale，指向同域的 /{locale}/auth/callback。API 与网页需保持同域，并在 Supabase Redirect URLs 中允许各环境的 /**；Site URL 只作为未显式传入回调时的生产兜底。

CLI 只把 refresh token 保存到系统钥匙串。短期 access token 会写入权限为 0600 的本机 session 缓存；同一 profile 的并发进程通过跨进程锁共享刷新结果，只有缓存缺失或确实需要刷新时才访问钥匙串，从而避免 Agent 批量操作反复触发 macOS Keychain。退出登录会清除该缓存，CI 可用 VVICAT_ACCESS_TOKEN 直接注入临时令牌。未配置服务地址时默认连接 https://pixelshort.vvicat.dev，--base-url、VVICAT_BASE_URL 和当前 profile 可依次覆盖。首次登录会从服务端 bootstrap 取得 Supabase 公共配置，也可用 VVICAT_SUPABASE_URL、VVICAT_SUPABASE_PUBLISHABLE_KEY 显式覆盖。Google 登录在 Windows 上直接调用系统 URL Handler，确保带 & 的 PKCE 授权参数完整传给浏览器。服务地址和非敏感 profile 写入系统配置目录；切换环境时必须使用独立的 --profile，避免复用旧认证。

创作前运行 ai-short-studio preflight --json。CLI 会通过公开的 /api/v1/bootstrap 检查服务连通性、取得 Supabase 公共配置、读取 npm latest 稳定版本并自动更新全局 CLI；更新成功后按输出重新运行。临时不更新时传 --no-update。随后预检检查登录态和文本、人物、场景、故事版、视频模型配置。npm registry 暂时不可用时服务端使用配置版本降级。

命令范围

• ai-short-studio preflight：创作前版本、连通性、认证和模型配置检查。
• ai-short-studio project：无限画布项目增删改查。
• ai-short-studio canvas settings get|set：读取或原子更新项目配置。
• ai-short-studio canvas get|inspect|apply：读取画布、一次聚合查询常用状态，或执行低层图补丁。
• ai-short-studio canvas node：节点类型/schema 查询、字段级或批量节点更新、批量执行。
• ai-short-studio canvas edge：连线读写。
• ai-short-studio canvas continuity analyze：视频生成前分析镜头依赖，可修复已具备源视频的首尾帧连线。
• ai-short-studio canvas asset：资产列表、上传、版本选择和下载。
• ai-short-studio canvas documents：一次读取当前分集的 自由画布文档、选版和阻塞原因；canvas document get|save|status 读取、保存或检查单个文档。
• ai-short-studio canvas previs read <nodeId> --project <projectId>：读取预演场景与 base；canvas previs apply <nodeId> --project <projectId> --file edit.json 提交 { "base": <读取结果的 base>, "actions": [...] }，或用 restoreVersionId 代替 actions 恢复历史。所有写入都追加版本；409 后重新读取并审阅，不自动换基线重试。执行帧图和视频仍使用 canvas node execute。canvas previs upload <nodeId> <imageFile> --base base.json 上传并绑定最多 16 MiB 的 PNG/JPEG/WebP 参考图；当前仅存档，绑定素材的场景暂不能渲染。
• ai-short-studio canvas workflow status：读取当前阶段、基础模块门禁和下一步缺失项。
• ai-short-studio canvas asset review-context|review：读取当前媒体摘要和必需维度，提交实际逐项审核并追加独立审核文档；不自动生成通过结论。
• ai-short-studio canvas folder：画布资产目录管理（5 预设 + 用户子目录 + 软删 + 跨项目复制）。
• ai-short-studio canvas episode：列出或创建无限画布分集。其他画布命令用 --episode <ID|集数> 选择分集。
• ai-short-studio task：项目任务列表、读取、受限批量等待和取消。
• ai-short-studio config：读取管理员发布的全局模型，管理个人默认模型、能力默认值和并发配置；CLI 会拒绝写入 Provider 或模型目录。

CLI 不提供分集删除或任务人工复核提交；这两类需要确认生产资产或保留范围的操作继续在网页端完成。

config get 返回管理员发布的全局模型与个人默认值，不返回供应商密钥。已保存的默认模型失效时，服务端会改用同类型的首个已启用模型，并用实时选项的第一项补齐该模型缺失的能力默认值。Comfly 和 RunningHub 的凭据、服务地址与工作流均由服务端维护；CLI 预检只检查默认模型及能力选项。config set 会拒绝写入任何供应商或模型目录。

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
ai-short-studio canvas asset select-version <assetId> --project <projectId> --version <versionId> --json
ai-short-studio canvas folder list --project <projectId> --json
ai-short-studio canvas episode list --project <projectId> --json
ai-short-studio canvas episode create --project <projectId> --number 2 --json
ai-short-studio canvas get --project <projectId> --episode 2 --json
ai-short-studio canvas folder copy-cross-project --project <sourceProjectId> --asset-id <assetId> --target-project <targetProjectId> --target-episode-id <episodeId> --target-folder-id <folderId> --json

canvas folder copy-cross-project 可用 --target-episode-id 指定复制品所属分集；省略 --target-folder-id 时，复制品进入该分集的未分类资产。目标目录必须属于目标项目和目标分集。两个参数都会去除首尾空白并拒绝空白值。该命令只复制资产及版本，不复制源目录结构。

项目配置

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 只适合已确认无并发写入的交互式便利操作。批量文件一次原子更新：

{
  "expectedVersion": 3,
  "values": {
    "aspectRatio": "9:16",
    "storyboardGridSize": 6,
    "imageResolution": "2K",
    "imageQuality": "high",
    "videoResolution": "1080p",
    "videoModel": null
  }
}

null 或空字符串会清除项目覆盖并恢复继承。设置 artStyle 会把当前关联的 visualBible 保存为项目快照，画风库后续变化不会反向更新项目；同一请求显式传入 visualBible 时以显式值为准。所有者和管理员可写，协作者只读；409 冲突后重新 settings get 并携带新 expectedVersion 重试。canvas apply 仍用于节点、连线、删除和视口等低层画布图补丁；同阶段有多个可合并图变更时默认一次批量提交并统一回读。已经读取画布时传入 --canvas-id 与 --expected-version，可避免保存前再请求一次全图。批量入口不可用或合法批量请求仍因粒度失败时才回退单条命令。

常用审计优先使用一次聚合查询，不必临时编写脚本或逐条请求：

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 --operation image-resource --json
ai-short-studio canvas node update <nodeId> --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 asset upload ./reference.wav --project "$PROJECT_ID" --json
ai-short-studio canvas node add audio --project "$PROJECT_ID" --asset-id <assetId> --json
# --asset-id 只允许 image、video、audio 节点，其他节点会在写入前拒绝
ai-short-studio canvas node add recreation-shot-extract --project "$PROJECT_ID" --config ./shot.json --json
ai-short-studio canvas node run --project "$PROJECT_ID" --node <node1> --node <node2> --concurrency 4 --json
ai-short-studio task list --project "$PROJECT_ID" --status running --json
ai-short-studio task wait --task <task1> --task <task2> --concurrency 4 --timeout 600 --max-interval 15000 --json

canvas node update 的 --set key=<JSON>、--unset key、--title、--x 和 --y 只修改指定字段；旧 --config 仍兼容。update-many 在一次画布版本校验中原子更新多个节点。结构化生成资源仍必须使用 edit-resource 或 edit-shot，不能通过字段更新改写 artifact。批量执行与等待默认并发为 4、上限为 16；多节点 --wait 优先按项目批量轮询任务快照，任务不在快照范围时自动回退逐任务等待。task list 默认返回精简状态，--full 才返回完整 payload/result；精简状态包含 attempt、maxAttempts 和时间戳，task wait 默认 600 秒超时，并对无变化状态使用 1 秒到 15 秒指数退避；传 --allow-timeout 可在超时时返回当前任务快照，供调度器继续判断。Agent 应优先单进程批处理，避免为每个节点启动一个 CLI 进程。

使用 canvas node edit-shot <nodeId> --project <projectId> --file shot.json 编辑镜头。命令会追加并选中不可变的人工 DOCUMENT 版本，不允许修改 shotKey、shotIndex 或来源身份，旧版本继续可选。重复提交同一节点、同一基线与同一载荷，或当前选版内容已等于目标结果时，返回已有版本并标记 idempotent: true。画布版本冲突会刷新画布和当前选版后重试一次；资产版本竞争因事务已回滚，会刷新画布并保留原基线重试一次。身份错误不会重试。

使用 canvas node edit-resource <nodeId> --project <projectId> --file resource.json 编辑剧本、人物、人物视觉、场景、子场景或道具结构化资源。命令只替换完整父文档中的目标实体，追加并选中人工版本；名称、资源键、ID 和所属关系不可修改，兄弟资源节点保持原选版。资源版本写入不属于 canvas apply 图补丁；它与 edit-shot 使用相同的幂等、当前结果无操作和一次冲突恢复规则。

CLI 通过 /api/v1/bootstrap 完成版本、连通性与 Supabase 公共配置预检，并直接使用现有 /api/projects、/api/canvas/node-types、项目画布与资产路由。

canvas node types [kind] --json 同时兼容节点目录 schema v1/v2，并原样返回动态节点的 source、definitionId 和 definitionVersionId。短剧结构化节点还会返回 structuredOutputSchema，描述生成文本解码后的顶层字段和关键嵌套结构；Agent 必须按该合同组织输出，不能从 TEXT/SCRIPT 字符串端口猜 JSON。节点 prompt 只补充创作意图，服务端会把语言与最终结构合同追加在它之后。后台发布后重新执行该命令即可读取新目录；归档节点不能新建，但已有实例仍按画布中的固定版本 schema 更新和执行。CLI 创建节点只提交 kind 与配置，版本由服务端固定，不能由客户端伪造。

新建视频生成节点按实时模型能力执行：首尾帧模型使用 start-frame + end-frame，普通图生视频使用 start-frame，图片参考使用 references。Ark 两个 Seedance 2.0 和 StarRouter 两个内置 Dreamina Seedance 2.0 可使用 reference-videos 和 reference-audios，上限为 9 张参考图、3 个参考视频和 3 个参考音频；部署方启用的内部 RunningHub MiniMax H3 模型支持纯文本零媒体输入，参考图、参考视频和独立参考音频范围分别为 0–9、0–2 和 0–2。RunningHub 参考视频只传画面，需要声音时须单独连接参考音频。它的实时 durationOptions 为 5–15 秒的每个整数，服务端把 1–4 秒兼容输入归一为 5 秒。其他 StarRouter 和自定义模型不会按名称猜能力。参考音频不能作为唯一媒体输入；纯文本指不连接任何媒体，不是只连参考音频。多模态参考不能与首尾帧混用。历史节点未声明新版输入语义时继续按原多图参考逻辑执行，不会被读取或保存自动迁移。

storyboard-image schema 现在暴露节点级 gridSize。CLI 继续按实时 schema 通用写入，配套 Skill 会分析每个镜头的动作、运镜、多人调度和连续性难度，向用户确认后逐镜设置；未单独设置或连接旧服务时回退到项目格数，系统默认为 6 格。

专业拆镜使用 storyboardPipelineVersion: 2、sourceFormat: screenplay-markdown.v1 或 screenplay-json.v1 及非空 platform。JSON 接受 scenes[].content[] 的动作、逐句对白和旁白；Markdown 提供项目语言对应的本地化块。项目 outputLanguage 决定内容语言，画布设置优先决定画幅，CLI 不再要求节点重复配置这两项。新建可用 canvas node add storyboard-breakdown --source-format screenplay-json.v1 --platform short-drama 显式启用专业模式；Markdown 使用 screenplay-markdown.v1。历史节点不自动升级，通过 node update 切换前需连接可解析的选定剧本，失败整笔回滚；成功保留旧选版并将本节点和下游标为过期，运行中不可切换；拆镜测试只生成分镜文本和镜头资产，不自动运行声音、TTS、图片、音频或视频。

实时 structuredOutputSchema 公开专业导演字段及双时长：duration 是 5～15 秒素材，edit_plan.intended_duration 是正数保留秒数，可小于 5 秒，但不得超过素材或截断语音。edit-shot 可修改保留时间并保留其余导演字段。专业预算按保留时长计算，超过显式镜头上限或目标时长 120% 时有限纠错，最多三次调用。多分集项目的回读和 edit-shot / edit-resource 应使用相同 --episode；错误分集返回 404。

storyboard-breakdown 还可按实时 schema 写入 targetDurationSeconds、pacingPreset 和 maxShotCount。结构化剧本会先生成固定镜号、顺序和来源的确定性骨架；其中 maxShotCount 是硬预算，无法完整覆盖来源时会在模型调用前明确失败。纯文本旧链路仍按软提醒处理镜头数，targetDurationSeconds 始终是柔性时长目标。留空时不限制镜头数，也不启用时长硬门禁。生成链采用滚动异步调度：单镜分镜图完成后立即进入视频提示词，提示词通过审计后立即提交该镜视频，可恢复失败不阻塞其他镜头。内置 Skill 同时补全字幕、人物/场景首次介绍角标、有动机的镜头衔接、声音平衡和成片验收流程。

标准短剧制作读取主 Skill references/short-drama/ 与 references/humanizer/：先生成和复核专业剧本，再审计模板化台词、虚浮修辞与机械节奏，最后检查剧情连贯性。自由画布视频制作流程读取随包参考目录。Humanizer 只润色表达，不改剧情事实、人物关系、专有名词、数字、时间线、世界观规则、场次结构或拍摄标记。剧本确认后再选择目标集数、创建或复用项目，并只建立目标集实际出现的人物、场景、道具和可选音色设定。拆镜前必须完成资产—剧情匹配审计；拆镜后逐镜全量检查重复、无效、缺失、冲突、穿帮、连续性、道具交互朝向、语言和来源身份。P0/P1 未清零时不得进入图片、声音或视频生产。

character-visual-design schema 暴露 candidateCount，范围为 1～3，默认值为 1。CLI 按实时 schema 校验和写入；多个视觉描述仍分别进入独立三视图和图片资产链。

canvas settings set 支持项目级 imageResolution、imageQuality、videoResolution，未覆盖的图片、图片编辑和视频节点会继承这些默认值。候选值来自 settings get 对应字段的实时 options；节点仅在需要偏离项目默认时，按当前模型 capabilities 写入 resolution、quality 覆盖。

项目交付语言在创建时用 ai-short-studio project create --language pt-BR 固定，接受任意规范 BCP 47 标签；剧本、拆镜、台词、配音、画面文字和字幕都沿用该值。canvas settings get 只回读项目语言，画布设置接口不能清空或修改它。CLI --locale 只影响界面消息；文本与短剧节点按项目 outputLanguage 选择模板并追加强制语言合同。节点 prompt 作为附加指令执行，但不得覆盖主 schema、必填字段或语言合同。短剧结构化节点会校验核心 JSON 结构合同，散文、空键、空内容数组、缺少 scenes/content、关键顶层或嵌套核心字段不会落库；结构化短剧文本调用关闭 reasoning，使用模型允许的最大输出预算、120 秒超时和最多 3 次任务尝试。运行中的画布节点会显示阶段、进度和任务重试次数。数据库旧模板缺少 JSON 或关键 schema 字段时会告警并回退仓库模板。空白模型结果按 EMPTY_RESPONSE 失败重试，不生成空资产。交付时只下载每镜 selected 原始 MP4，按 S001.mp4 顺序命名，并用 manifest 记录镜号、节点、资产、版本和文件名；字幕单独交付，不烧录进原始视频。

百炼 CosyVoice 的 tts 节点通过实时 schema 提供音色、语言、格式、采样率、音量、语速、音调和声音指令。先用 canvas settings get 确认最终 audioModel，再从 canvas node types 返回的 tts.configSchema 选择字段和值；CLI 会在写入前校验必填字段、类型、整数、枚举和数值上下限。

声音设计使用实时目录中的 voice-design 节点：提供声音描述并按 schema 配置试听文本、目标模型等参数，成功后将 voice 输出连接到 tts.voice。声音克隆使用 voice-clone：参考音频连接 audio，成功后同样连接 voice 输出，无需手工复制音色 ID。

视频首尾帧使用实时目录中的 video-frame-extract 节点，配置为 {"position":"first"} 或 {"position":"last"}。其 IMAGE 输出保留来源视频版本；连续性和拆格连接只是建议，只有用户勾选确认后才写入，创建节点和连线不会自动执行或付费。

运行 ai-short-studio <topic> --help 查看精确参数。可执行命令使用完整产品名 ai-short-studio，同时避免与其他 CLI 冲突。所有结构化响应保持 JSON；API 错误也返回稳定的 error.code、status、retryable 和 details。

退出码：0 成功，3 未认证，4 不存在，5 禁止或冲突，6 参数错误，7 其他错误。

配套 Agent Skill 位于 skills/using-vvicat-ai-short-studio-cli，随 npm 包发布。安装或更新 CLI 时会自动安装到 Codex Skill 目录；已被用户修改或非 CLI 托管的目录不会被覆盖。

RunningHub MiniMax H3 通过实时能力暴露 16:9、9:16 与 480p、720p、1K、2K，默认为 1K；Agent 不得臆造其他值。

本地真实验收

CLI 开发完成后运行以下命令：

cd packages/ai_short_studio_cli
npm run test:local-e2e

该命令先构建真实 CLI，再启动隔离的本地 mock API，通过多个 bin/run.js 子进程验证聚合查询、字段级与多节点更新、canvas apply 免预读、批量执行/等待和旧位置参数兼容；同时启动 8 个独立认证进程，确认共享 session 缓存只触发一次模拟 Keychain 读取和一次刷新。测试不连接生产服务、不调用模型，所有配置、令牌、画布和任务数据均在系统临时目录中创建并在结束时清理。

标准创作中，用户未指定时角色、道具、场景/背景和分镜图统一使用 16:9。视频时长以当前模型实时 durationOptions 为准；只有实时模型仅提供 5、10、15 秒时，才按镜头目标时长向上取这三档为剪辑保留余量，其他模型不硬编码三档。每批生成后 Agent 必须重新读取任务与资产、核对最终时长在实时合法选项中，并实际检查预览，完成自我审计后才能继续或交付。

ai-short-studio skill install --target codex
ai-short-studio skill status --target codex
ai-short-studio skill update --target codex
ai-short-studio skill update --target codex --json

手动恢复或安装到其他 Agent 时，可使用 --target agents；自定义全部内置 Skills 的父目录使用 --root <path>。旧版 --directory <path> 保留为兼容入口，只把主 CLI Skill 精确安装到该目录。自动安装对应使用 VVICAT_SKILLS_ROOT；旧变量 VVICAT_SKILL_DIRECTORY 仍保持主 Skill 精确目录语义。CLI 会记录版本和 SHA-256；已安装 Skill 被用户修改后，更新默认停止，只有显式 --force 才覆盖。自动安装可通过 VVICAT_SKIP_SKILL_INSTALL=1 跳过。

自动安装被跳过时，skill status、skill update、skill diff 和 postinstall 输出都会带上 state 与跳过原因，避免 CLI 升级后 Skill 悄悄停在旧版本：current 表示版本与校验和都与随包一致；outdated 表示托管目录的清单版本低于当前 CLI；modified 表示目录内容与安装时记录的校验和不一致（用户改动或混入其他文件）；unmanaged 表示目录没有 CLI 清单；missing 表示未安装。

ai-short-studio skill diff --target codex --json

skill diff 对照随包版本列出 changed（内容不同）、extra（本地新增）和 missing（随包有而本地没有）的文件，供用户决定手工合并还是 skill install --force 覆盖。preflight --json 会返回 skill 块，其中 skillReady 只有在 state === "current" 时为真；未就绪时 nextAction 给出下一步命令，Agent 应在处理完 Skill 版本前停止创作。

发布

使用具有发布权限并允许 bypass 2FA 的 npm Granular Access Token：

export NODE_AUTH_TOKEN="<token>"
npm run release:dry-run
# 加入 @vvicat organization 后发布正式包
npm run release

Token 只从环境变量读取，不要放入参数、Git 或日志。

未显式传入 --version 时，发布脚本会从包清单版本开始查询 npm，并自动选择第一个未占用的 patch 版本；例如 0.1.1 已存在时发布 0.1.2。显式传入 --version 时严格使用指定版本，版本已存在则幂等跳过。

Docker 自动发布使用 .env 中的 NPM_PUBLISH_PACKAGE_NAME 选择目标；当前默认个人包为 @aswless_854771076/ai_short_studio_cli，获得组织权限后可改为 @vvicat/ai_short_studio_cli。preflight 会自动检查并升级已安装的全局 CLI；手动更新仍可使用：

npm install --global @aswless_854771076/ai_short_studio_cli@latest

云效 Flow

选择云效托管构建集群和 Node.js 22，将 npm Granular Access Token 保存为加密变量 NPM_ACCESS_TOKEN。正式发布流水线建议仅由 cli-v* Tag 触发：

export NODE_AUTH_TOKEN="$NPM_ACCESS_TOKEN"
cd packages/ai_short_studio_cli
npm run release:ci

staging 不再发布 CLI，原 release:test 和 release:ci:test 入口已移除。Docker 自动发布要求 NPM_PUBLISH_ENABLED=true 且 NEXT_PUBLIC_SITE_URL=https://pixelshort.vvicat.dev（允许末尾 /）；地址缺失或为测试站时跳过发布。测试环境应持续设置 NPM_PUBLISH_ENABLED=false。生产正式包沿用已配置的包名和 latest tag。

release:ci 会依次运行测试和类型检查、发布 npm、等待 registry 可见，再从 npm 安装该精确版本并验证 CLI 与配套 Skill。无需配置自有 Runner；只有访问内网或需要固定出口 IP 时才使用自有构建集群。

专业拆镜增量修订：canvas node revise-storyboard <parentNodeId> --project <projectId> --json 读取当前版本、来源合同、资产白名单及软提示；--file patch.json --dry-run 预览差异、硬错误和下游影响，移除 --dry-run 原子保存指定镜头。请求必须携带画布、父版本及镜头基础版本；409 不自动重试。来源、原文、镜号与顺序只读，跨镜合同需同时修改两侧。未改镜头和历史媒体保留，受影响下游标记待更新。专业模式中的节奏、突出比例及建议预算只提示，硬错误最多纠错三轮；细化失败保留合法规划与完成批次。

Agent 恢复 / Agent recovery

新项目先运行 canvas documents 和 canvas workflow status，由 Agent 在无限画布创建 自由画布 JSON 文档；用 canvas document save 追加版本，用 canvas document status 检查上游选版。canvas node diagnose <nodeId> 仅用于历史媒体节点的恢复，不是新流程入口。完整操作见随包 Skill 的 自由画布文档流程。

canvas document save 在发出任何远程请求前按随包 module-map.json 的 documents 合同核对正文：登记的文档键缺少必需顶层字段，或 non_empty 字段为空时直接失败，并指出应先读取的模板路径。阶段状态只看文档键、版本和来源快照，不校验正文，因此只写摘要一类的占位文档会让阶段显示 ready 却向下游传递空分析。只有用户明确要求保存半成品草稿时才加 --allow-partial，该版本会被警告为不得作为阶段依据。

canvas asset audit --project <projectId> --json 补齐资产生成前的机器门禁：读取已就绪的资产计划文档和画布节点、连线，按人物、场景、道具逐类核对是否使用了对应的设定板节点（character-turnaround、location-image、prop-turnaround），而不是透明边界的 image-generate；同时检查设定板的 prompt 端口是否来自结构化设定节点、是否接线、是否手写了 config.prompt。存在失败项时退出码为 7，errors[].nodeIds 直接指出要重建的节点；计划文档未就绪时返回 blocked: "asset-plan-not-ready"。同一项目有多份资产计划时用 --document-key 指定。该命令只做跨节点事实核对——缺少必需端口由服务端在提交时拒绝，不在本命令范围内。

Use canvas node diagnose to inspect inputs, selected versions, task status and recovery actions without running a model. canvas node storyboard-draft reads an unapproved planning draft; --file submits explicit edit/promote requests and --dry-run previews them. Content errors do not prevent draft saves. Promotion validates the complete plan; draft saves neither change the formal selection nor generate media. See the bundled Skill's references/agent-recovery.md. Image quality is inspected by a person or Agent; the platform checks review records and provenance, rather than detecting visual defects automatically.

Agent 可直接在 text-resource 节点保存剧本、导演本和制作计划等自由画布文档（文档结构由平台画布统一校验）；每次保存都通过 --input 固化上游版本，审核使用独立 canvas.review.v1 文档。历史 screenplay-resource 和 storyboard-draft 只用于迁移旧项目，不得用于新项目。

Agents author freeform JSON documents directly in text-resource nodes and preserve every source version through --input; legacy screenplay resources and storyboard drafts are migration-only compatibility paths.

canvas asset select-version（或 asset select）修改资产全局选版，不覆盖节点的固定输出版本。网页节点“查看版本”和内置助手的 canvas_select_version 只切换当前节点，保留兄弟节点与全局选版，并使下游过期；运行中节点不能切版。读取或编辑节点时优先使用 selectedOutputVersionId。本次没有新增 CLI 节点切版命令，不能用普通配置补丁代替。

画布 settings 管理制作配置，不修改内置助手 agentModel；项目 outputLanguage 创建后不可改。null 只对可覆盖字段恢复默认。内置助手使用专用工具复用同一保存服务，CLI 继续使用 canvas settings get/set。

连续性 --apply-ready 只配置尾帧提取节点和连线，不运行媒体任务。网页、CLI与内置助手复用同一分析规则；读取图和设置版本不一致时重新分析，不覆盖新图。内置助手的专用工具额外核对分析指纹和指定建议。

失效视频复用 / Reuse an existing stale video

先用 canvas asset reuse-context <assetId> --project <projectId> --node <producerNodeId> --version <versionId> --json 检查原媒体及当前合同。修复返回的来源阻塞并实际完整播放后，通过 canvas asset reuse <assetId> --project <projectId> --file reuse.json --json 提交上下文指纹与逐项审核。服务端追加同媒体复用版本，不触发视频生成；旧版本保留，字幕和剪辑须重新核对。完整合同见随包 references/agent-recovery.md。

Read canvas asset reuse-context before submitting canvas asset reuse. The context includes the original and current contracts, source differences, media digest, canvas version, and context hash. Resolve blocked sources and fully watch and listen to the existing video before submitting observations and playback evidence. Reuse appends a new version referencing the same media; it preserves generation history and never calls the video provider. Rebuild caption and edit bindings against the returned version. Frame samples, ASR, and technical checks do not prove full playback.

人工完整审看后，可加 --approve-only 单独保存验收声明，把返回的 approvalAssetId / approvalVersionId 交给内置助手继续。内置工具仅接受该引用，不能自行填写人审结论；声明不改变视频选版。

After a human completes playback and review, use --approve-only to save a separate declaration without selecting a video version. Pass the returned approval references to the built-in assistant; its reuse tool accepts references rather than model-authored review or playback claims. A changed source or deleted declaration requires a fresh review.

动作编译 / Motion compilation: previs-motion 接收正式场景版本，使用现有节点配置、连线与 execute 命令提交；canvas previs read <nodeId> --project <projectId> --motion --json 读取完整 QA 和版本有效性。QA 失败会保留，available 不等于审核通过。Motion playback and rendering remain unavailable.

预演导出 / Previs export: 创建 previs-export，连接 scene 和可选 motion，在 config.previs 配置 sceneId、formats（project/otio/usd-camera/media/frame-pack）及可选 shotIds，然后显式 execute。canvas previs read <nodeId> --project <projectId> --export --json 返回正式 ZIP／JSON 文件版本和短期链接。包保留素材版本引用，不内嵌模型，恢复需要原平台素材权限。The export node emits a ZIP archive and JSON manifest with exact version references; assets are not embedded and restoring requires access to the original platform assets.

雕刻轮廓比较 / Sculpt silhouette comparison: canvas previs compare <nodeId> --project <projectId> --file compare.json --json 显式提交 {base,sceneId,objectId,references,options?}，只接受已绑定的精确参考版本，支持自动角度、多视图加权和候选排名；不应用候选。输出只读报告及 PNG 对照图数据。The native approximation scores silhouettes, not boolean holes, material accuracy, identity or approval. See the bundled canvas-previs reference for parameter limits and assistant support.

OBJ/GLB/FBX props can be uploaded with canvas previs upload <nodeId> <file.obj> --project <projectId> --base base.json --scene <sceneId> --object <objectId> (32 MiB maximum). Use a .glb or .fbx file with the same command for GLB or untextured binary/ASCII FBX props (ASCII versions 7000–7700). Prop FBX uses --object; character FBX keeps its separate model/character flags. The command creates a new mesh or replaces an existing mesh source, preserving scene transforms and source history. Read the latest full base and save drafts first. Character flags cannot be combined with --object. OBJ/GLB/FBX preview and frame/video rendering use exact source versions; GLB supports bounded embedded PNG/JPEG/WebP textures and rejects external URIs, unsupported compression and unknown required extensions. Separate glTF resources, AVIF/data URIs, external MTL/textures and textured FBX are not integrated. Native character FBX still requires binary encoding.

逐帧物理读取 / Physics frame inspection: canvas previs physics <motionNodeId> --project <projectId> --motion-version <receipt.versionId> --frame <zeroBasedFrame> --json reads frozen compiled COM, support, the current ballistic-fit point and up to 24 spring-tip frames. It does not create versions, render or approve media. Read the current motion receipt first; stale versions and concurrent edits return 409. Coordinates stay in compiled world metres, and display placement does not recompute dynamics. Attached-solid collision QA remains in qa.attachments; path support is outside this diagnostic scope.

预演环境贴图：ai-short-studio canvas previs upload <nodeId> sky.hdr --project <projectId> --base base.json --hdr --scene <sceneId> --json；支持 HDR／EXR／PNG／JPEG，最大32 MiB及16,777,216像素。上传保存正式素材与场景版本并选中环境，仍须显式执行节点渲染。内置助手可读取并选择已有绑定，暂不能上传本地文件。

显式预演抠图 / Previs matte: canvas previs apply <nodeId> --project <projectId> --file matte.json --json accepts {base,matte:{sceneId,objectId,selection:"auto"|"saved",options:{...}}}. Keep the read base, save drafts first, and use existing cutout sources. This appends immutable image/mask/scene versions; it does not render or approve media.