AI Short Studio CLI

@aswless_854771076/ai_short_studio_cli 是当前发布的新链路无限画布项目命令行客户端，面向开发者、自动化程序和 Agent Skill。它不接入旧项目类型；获得组织权限后可切换为 @vvicat/ai_short_studio_cli。

安装后使用体现完整产品名的 ai-short-studio 命令，同时避免与其他 CLI 冲突。

安装与认证

需要 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 --google

npm 包内置 using-vvicat-ai-short-studio-cli、short-drama 和 humanizer 三个 Agent Skill。安装或升级 CLI 时，postinstall 会自动把它们安装或更新到 Codex；用户修改过或不由 CLI 管理的副本不会被覆盖。设置 VVICAT_SKIP_SKILL_INSTALL=1 可关闭自动安装。

skill install/status/update 默认管理全部内置 Skill，也可用 --skill short-drama 或 --skill humanizer 单独管理。用户修改过的 Skill 独立跳过，不影响其他 Skill。剧本先用 short-drama 创作和复核，再用 humanizer 审计、去除 AI 味，最后回到 short-drama 检查剧情连贯性；操作 VVICAT 使用主 CLI Skill。

CLI 未传服务地址且当前 profile 未保存地址时，默认连接测试环境 https://ai-short-studio.vvicat.dev。--base-url、VVICAT_BASE_URL 和当前 profile 可依次覆盖默认值。本地缺少 Supabase 公共配置时，CLI 会从服务端 bootstrap 接口读取并保存到 profile；也可用 VVICAT_SUPABASE_URL 和 VVICAT_SUPABASE_PUBLISHABLE_KEY 显式覆盖。Google 登录采用浏览器 PKCE 和本机环回回调；Windows 直接调用系统 URL Handler，确保包含 & 的完整授权参数传给浏览器。

邮箱注册和登录均通过隐藏输入或 stdin 接收密码，不能把密码放入命令参数：


ai-short-studio auth signup --email user@example.com --password-stdin
ai-short-studio auth login --email user@example.com --password-stdin

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

注册输出 registrationAccepted、authenticated 和 confirmationRequired。confirmationRequired: true 表示需要先完成邮件验证，CLI 不会写入空凭据；为 false 时注册已返回有效会话，refresh token 会立即保存到系统钥匙串。

CLI 使用当前 profile 的 baseUrl 和 --locale 生成同域的 /{locale}/auth/callback，并显式写入注册确认邮件。API 与网页需保持同域；Supabase Redirect URLs 应允许本地、测试和生产环境各自的 /**，Site URL 仅作为未显式传入回调时的生产兜底，无需为单次注册临时修改。

refresh token 保存在操作系统钥匙串。短期 access token 保存在权限为 0600 的本机 session 缓存；同一 profile 的并发进程用跨进程锁共享刷新结果，缓存有效时不会重复访问 macOS Keychain。auth logout 会清除缓存；CI 可通过 VVICAT_ACCESS_TOKEN 注入临时令牌。profile 只保存服务地址、Supabase 公共配置和默认项目等非敏感信息，默认位于 XDG 配置目录，可通过 VVICAT_CONFIG_DIR 改写。

创作前预检


ai-short-studio preflight --json

预检请求公开的 GET /api/v1/bootstrap：HTTP 成功同时证明 API base URL 可达，响应包含 npm 对应包 latest 标签指向的 CLI 稳定版本和 Supabase URL/publishable key，不包含 service role 或其他 secret。服务端通过 VVICAT_CLI_PACKAGE_NAME 声明包名；npm registry 暂时不可用时，版本回退到 VVICAT_CLI_LATEST_VERSION 或服务端内置版本。

CLI 默认在发现新版本时更新当前全局 npm 包；更新成功后输出 restartRequired 和 nextAction，必须重跑，旧进程不会继续创作。用户明确禁止全局写入时可传 --no-update。版本就绪后，预检检查登录态以及标准创作链路所需的文本、人物图、场景图、故事版图和视频默认模型。读取配置时，服务端会把已失效的默认模型替换为同类型的首个已启用模型，并用实时选项的第一项补齐该模型缺失的能力默认值；修复后仍为 ready: false 时，再根据 missing 处理。供应商、密钥和模型目录由管理员统一维护，预检不检查用户供应商密钥；Comfly 与 RunningHub 从全局目录选择。服务不可达时，先检查 --base-url、VVICAT_BASE_URL、当前 profile 或默认测试环境。

项目与画布


ai-short-studio project list --json
ai-short-studio project create --name "CLI Draft" --json
ai-short-studio canvas get --project <projectId> --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

项目创建和列表固定限定 INFINITE_CANVAS。删除项目、节点、连线或任务必须显式传入 --yes。

新建或继续无限画布项目时，项目配置是创建、执行创作节点之前的硬门禁。两种流程都先执行 preflight → config get → canvas node types → project list。新项目创建前必须确认账户已配置默认分析模型；缺失时 project create 会直接停止，不发送创建请求。审查通过后再按“确认名称/用途 → project create → project get + canvas settings get”继续，不要求创建前读取不存在的项目或画布；既有项目按“project get → canvas settings get”继续。

每个配置字段都返回项目覆盖值 currentValue、最终生效值 effectiveValue 和来源 source。Agent 必须逐项展示并确认这些值；模型可以覆盖到项目，也可以由用户明确确认继承账户默认，但必须明确最终生效且当前可用的具体模型。画风、画幅、分镜类型、格数和模型的可选值来自实时 options，visualBible 则返回 schema；CLI 不内置这些服务端枚举。示例中的 $ART_STYLE_ID 必须从本次响应的 artStyle.options 中选择并解析真实 option.value，不能复用文档值。

canvas settings set 只更新 values 中的字段。传入 null 或空字符串可清除项目覆盖并恢复账户级或系统默认继承。标准创作门禁必须使用 --file 或 stdin 批量写入，并把最近一次 settings get 返回的 version 填入请求的 expectedVersion；--field/--value 只适合已确认没有并发写入的交互式单字段便利操作。批量文件一次原子写入，例如：


{
  "expectedVersion": 3,
  "values": {
    "aspectRatio": "9:16",
    "storyboardGridSize": 6,
    "imageResolution": "2K",
    "imageQuality": "high",
    "videoResolution": "1080p",
    "videoModel": "runninghub::minimax-h3-reference-to-video",
    "videoPromptType": "h3"
  }
}

最终生效的模型为 comfly::minimax-h3、runninghub::minimax-h3-reference-to-video 或 comfyui::minimax-h3-reference-to-video 时，Agent 会在同一次批量设置中显式写入 videoPromptType: "h3"；非 H3 模型仍保留用户手动选择提示词类型的能力。既有 storyboard-video-prompt 节点中仅有效的 h3 / seedance 会覆盖项目设置，因此运行前会清除与 H3 不一致的 seedance，并清理无效旧值后回读确认。节点未设置或值无效时先继承项目类型，项目也无有效值时才使用 seedance；任一有效值不一致时不会执行付费任务。

设置 artStyle 时，服务端会把该画风当前关联的 visualBible 保存为项目快照；画风库后续修改不会反向改变既有项目。同一请求显式提供 visualBible 时，以显式值为准。所有者和管理员可写，协作者只能读取；遇到 409 版本冲突时重新运行 canvas settings get、核对变化并携带新的 expectedVersion 重试，不能盲目覆盖。

canvas apply 保留为节点、连线、删除、视口等完整画布图补丁的低层入口，不再是常规项目配置入口。同一阶段存在多个可合并的画布写操作时，Agent 默认先用一次 canvas apply 批量提交并统一回读；已有画布快照时同时传 --canvas-id 和 --expected-version，保存前不会额外读取全图。只有批量入口不可用、服务不支持，或合法请求仍因批量粒度失败时，才回退到 node/edge 单条命令。409 版本冲突会先读取最新状态、合并本地补丁并确认后继续批量重试；权限、参数、schema、业务门禁和付费确认错误不能通过单条命令绕过。节点执行使用一次 canvas node run --node … --node …，任务等待使用一次 task wait --task … --task …；两者默认并发 4、上限 16，也可用 run --wait 在同一进程提交并等待。账户级 config set、项目 description 或节点 prompt/config 不能代替项目 settings。Pexels 仍使用 project provider get|set|test 管理，不受 settings 命令影响。

常见审计查询用 canvas inspect 聚合完成。它只读取一次画布，并可通过重复的 --include 返回 summary、nodes、edges、assets、settings 和 node-types；--kind、--status、--search、--operation、--resource-type、--producer-node 可直接过滤。Agent 不应为这些查询临时编写 TypeScript、Python 或 jq 脚本。

节点配置支持字段级更新：canvas node update <nodeId> --set 'gridSize=9' --unset legacyField --title '镜头一' 只修改指定字段，--config 保持向后兼容；canvas node update-many --file updates.json 在同一画布版本基线上原子更新多个节点。结构化生成资源仍使用 edit-resource 或 edit-shot，不得用字段更新改写 artifact。

使用 canvas node edit-shot <nodeId> --project <projectId> --file shot.json 编辑镜头。命令会追加并选中不可变的人工 DOCUMENT 版本，可修改经校验的 continuity，但不允许修改 shotKey、shotIndex 或来源身份，旧版本继续可选。

使用 canvas node edit-resource <nodeId> --project <projectId> --file resource.json 编辑剧本、人物、人物视觉、场景、子场景或道具结构化资源。命令基于该节点当前 selectedOutputVersionId 在完整父文档中只替换目标实体，追加并选中人工版本；名称、资源键、ID 和所属关系等身份字段不可修改，兄弟资源节点保持原选版。资源版本写入具有独立并发基线，不属于 canvas apply 图补丁；409 后必须重新读取画布和当前选版再确认。

项目级默认生成参数使用 imageResolution、imageQuality 和 videoResolution。候选值从 canvas settings get 对应字段的实时 options 读取；没有单独覆盖的图片、图片编辑和视频节点会继承项目值，只有需要偏离项目默认时才写节点级 resolution、quality。

节点类型目录由现有服务接口 GET /api/canvas/node-types 返回，格式为：


{
  "data": {
    "schemaVersion": 1,
    "nodeTypes": [
      {
        "kind": "text",
        "title": "文本",
        "defaultConfig": {},
        "inputSchema": { "type": "object" },
        "outputSchema": { "type": "object" },
        "configSchema": { "type": "object" }
      }
    ]
  }
}

实际字段以接口实时响应为准。CLI 与 Skill 必须先读取该目录，再按 input、output 和 config JSON Schema 操作节点，不能写死枚举或端口。

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


ai-short-studio canvas node types --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 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 run --project <projectId> --node <node1> --node <node2> --concurrency 4 --wait --json
ai-short-studio task wait --task <task1> --task <task2> --concurrency 4 --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

video-frame-extract 可从已选中的视频资产版本提取首帧或尾帧，配置分别为 {"position":"first"} 和 {"position":"last"}。输出是独立的 IMAGE 资产版本并记录来源视频版本；镜头连续性和拆格连接只生成建议，用户确认后才写入，创建节点或连线不会自动执行任务或付费。

输出语言先读取 settings，再用 ai-short-studio canvas settings set --project <PROJECT_ID> --field outputLanguage --value pt-BR 设置任意规范 BCP 47 标签；null 恢复自动跟随输入。CLI --locale 只控制命令界面，不代替内容语言。变化只标记相关下游节点 stale，不删除历史版本或自动重跑。原始视频按镜号下载 selected MP4 并命名为 S001.mp4、S002.mp4，manifest 记录 shotNumber、nodeId、assetId、versionId、fileName；字幕单独交付，不烧录进原始视频。

RunningHub MiniMax H3 的实时 aspectRatio 只有 16:9、9:16，resolution 只有 480p、720p、1K、2K，默认为 1K。该模型支持原生音频，实时能力会把 generateAudioOptions 明确限制为 true；H3 有声任务仍需在每个视频节点显式写入 generateAudio: true，不能仅依赖默认值。

画布资产目录管理（Canvas Folders）

每个无限画布项目固定预置五个根目录——道具 / 人物 / 场景 / 配音 / 分镜（props、characters、locations、voices、storyboards），全部为系统预设，不可改名、不可删除、不可移动。用户在根目录下可创建子目录，深度上限为 32 层。删除采用软删模式，软删节点在 30 天回收窗口内可恢复。跨项目复制命令只复制资产及版本，目录结构不会随复制迁移。


# 列出目录树
ai-short-studio canvas folder list --project <projectId> --json
# 含软删节点
ai-short-studio canvas folder list --project <projectId> --include-soft-deleted --json
 
# 创建子目录
ai-short-studio canvas folder create --project <projectId> --name "武器" --json
ai-short-studio canvas folder create --project <projectId> --name "未来战甲" --parent-id <folderId> --json
 
# 重命名（预设目录禁止，返回 FOLDER_PRESET_IMMUTABLE）
ai-short-studio canvas folder rename --project <projectId> --folder <folderId> --name "新名称" --json
 
# 移动（同项目内，环检测返回 FOLDER_CYCLE_DETECTED）
ai-short-studio canvas folder move --project <projectId> --folder <folderId> --parent-id <newParentId> --json
 
# 删除（被引用时返回 FOLDER_IN_USE 含引用方列表）
ai-short-studio canvas folder delete --project <projectId> --folder <folderId> --json
# 恢复软删目录（30 天窗口外返回 FOLDER_GONE）
ai-short-studio canvas folder restore --project <projectId> --folder <folderId> --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
ai-short-studio canvas folder copy-cross-project --project <sourceProjectId> --asset-id <assetId> --target-project <targetProjectId> --json

错误码	HTTP	含义
`FOLDER_NOT_FOUND`	404	目录不存在或已彻底删除
`FOLDER_CONFLICT`	409	同 parent 下重名
`FOLDER_PRESET_IMMUTABLE`	409	预设目录不可改/不可删
`FOLDER_IN_USE`	409	目录被引用，必须先解除引用
`FOLDER_CYCLE_DETECTED`	409	移动形成环
`FOLDER_INVALID_PARAMS`	422	depth 超过 32 / name 非法字符
`FOLDER_FORBIDDEN`	403	跨项目越权
`FOLDER_GONE`	410	目标已回收或超出恢复窗口

canvas folder * 操作目录容器，canvas asset * 操作资产条目。跨项目复制前先对目标项目运行 canvas folder list 取得 folderId；当前 canvas asset list 只支持 --kind 和 --search，目录内浏览及批量复制、移动、删除、恢复、下载请使用网页资产目录。目录被引用时必须先解除引用，CLI 不提供强制绕过。完整字段和示例详见 using-vvicat-ai-short-studio-cli Skill。

CLI 支持分集查询与创建，以及任务读取、等待和取消；分集删除、选择一致性测试结果和视频人工复核仍需在网页端确认后完成。

资产、下载与配置


ai-short-studio canvas asset list --project <projectId> --json
ai-short-studio canvas asset select-version <assetId> --project <projectId> --version <versionId> --json
ai-short-studio canvas asset download <assetId> --project <projectId> --output ./downloads
ai-short-studio config get --json
ai-short-studio config set --file ./config.json --json

下载默认使用资产的 selected version，也可用 --version 指定版本。文件先写入 .part，成功后原子改名。config get 返回个人默认值和管理员已发布的全局模型，不返回 Provider 密钥；目录中的模型可直接用于预检。config set 仅管理个人默认模型和能力默认值，CLI 与服务端都会拒绝 providers、models 或工作流并发；工作流并发由管理员在用户管理中配置，项目设置必须通过 canvas settings set 写入。

管理员 AI Provider 命令

仅管理员账号可用。把管理员侧的 AI Provider 管理从网页端下沉到 CLI，便于部署/CI 与 Agent 复核。Agent 在排查”我能不能用这个 provider / 还缺什么”时先跑 capabilities。


ai-short-studio config ai-provider list --json
ai-short-studio config ai-provider get --id <providerId> --json
ai-short-studio config ai-provider set --id <providerId> [--base-url <url>] [--api-key-stdin] [--enabled true|false] [--preset <name>] --json
ai-short-studio config ai-provider test --id <providerId> --json
ai-short-studio config ai-provider models --id <providerId> --json
ai-short-studio config ai-provider capabilities --json

--api-key-stdin 从隐藏 stdin 读取密钥，禁止写入 shell 历史或日志；CI 用 VVICAT_AI_PROVIDER_<ID>_API_KEY 注入。
--preset <name> 触发服务端内置 Preset（如 openai-compatible、runninghub、comfly）一键种子。
test 不消耗 token，只报告 HTTP 状态与延迟；models 仅在 enabled 且最近 test 成功时返回。
capabilities 报告当前生效的私有/LAN baseUrl 白名单（环境变量 VVICAT_ALLOW_PRIVATE_PROVIDER_BASE_URLS，CSV host:port）、已注册 Provider、缺失项与诊断。
私有/LAN baseUrl（如本地 ComfyUI http://127.0.0.1:8188、http://192.168.3.30:8188）必须在 Next.js 运行环境里把 VVICAT_ALLOW_PRIVATE_PROVIDER_BASE_URLS=127.0.0.1:8188,192.168.3.30:8188 显式打开；公网 URL 仍强制 HTTPS 与公网 IP 校验。

CLI 包身份 drift 防护（2026-09 闭环）

CLI 与服务端 /api/v1/bootstrap 必须就包身份（name + latestVersion）达成一致，否则 preflight 会抛”服务端返回的 CLI 包名与当前安装包不一致”并阻塞所有 CLI 命令（含 auth login）。

完整协议与排查决策树见配套 Skill vvicat-cli-adapter（.agents/skills/vvicat-cli-adapter/SKILL.md）。以下是简版：

CLI 端：
- 仓库内 packages/ai_short_studio_cli/package.json 的 name 必须恒等于 @aswless_854771076/ai_short_studio_cli（pre-commit guard npm run check:cli-package-identity 强制）。
- 改 CLI 代码后：npm run build && npm test && npm run typecheck，再 push 到 main。GitHub Actions .github/workflows/cli-publish.yml 会自动 npm run release -- --verify 推到 npm。
- 手动流程 fallback：参考 Skill references/cli-release-sop.md。
服务端：
- /api/v1/bootstrap 已升级：响应新增 data.cliDrift 字段，drift 时返回 reason（PACKAGE_NAME_DRIFT 或 VERSION_DRIFT）+ manifest + npm 三组对照信息，方便 Agent 立即看到。
- resolvePackageName 优先级：VVICAT_CLI_PACKAGE_NAME > NPM_PUBLISH_PACKAGE_NAME > packages/ai_short_studio_cli/package.json。强烈建议显式设置 env，避免仓库 rename 后静默漂移。
Agent 进入新环境第一件事：ai-short-studio config ai-provider capabilities --json（如果未登录就先 auth login --password-stdin），失败时查看响应里是否含 cliDrift 字段，按 reason 走对应修复流程。

本地真实验收

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

Agent Skill 与一致性 Hook

storyboard-breakdown 的实时 configSchema 现在提供 targetDurationSeconds、pacingPreset 和 maxShotCount。CLI 通过通用节点更新写入，例如 --set 'targetDurationSeconds=90' --set 'pacingPreset="balanced"' --set 'maxShotCount=18'。这些是拆镜规划预算：超出时给出软提示并保留完整源文覆盖，不因镜头数或估算时长偏差阻塞整个拆镜任务。不设置时不限制镜头数，也不启用时长硬门禁。

资产、分镜图、视频提示词和视频生成使用滚动异步调度：节点完成后立即审计并提交已就绪的下游，不等整批同阶段任务完成。单镜可恢复失败只暂停和重试该镜，其他无依赖镜头继续向前。剪辑交付包含对白/旁白字幕、首次人物与场景介绍角标、有叙事动机的切换/短淡化、镜间响度匹配以及可复现 manifest；不给所有镜头机械套淡入淡出。

npm 包包含 skills/using-vvicat-ai-short-studio-cli，用于指导 Agent 在写操作前先拉取账户配置、节点目录、项目和画布，检查默认模型与项目配置，并在配置不完整或信息不确定时先询问用户。项目配置写入后必须回读一致，门禁通过前不得创建或执行任何创作节点。供应商与模型目录由管理员维护，Agent 只协助用户选择默认模型。Skill 同时覆盖画布操作、异步任务等待和临时项目清理。

标准创作流程把分镜拆解设为硬门禁：必须先完成本次故事涉及的人物、场景、道具等素材生成。互不依赖的素材会同批提交并并发等待；存在上游依赖时才按依赖顺序分批执行。全部任务成功并由用户确认每项素材的 selected version 后，Agent 才会按实时 schema 将剧本节点和每个相关素材节点逐项连接到 storyboard-breakdown 对应输入。只要素材未完成、未选版或连线缺失，Agent 就不能执行分镜拆解，而应先询问并补齐。即使服务端 schema 将部分素材输入标为可选，也不能跳过故事实际涉及且已确认使用的素材。

制作短剧时，Agent 必须先用随 CLI 安装的 short-drama 生成和复核专业剧本，再以嵌入模式调用 humanizer 审计模板化台词、虚浮修辞与机械节奏，然后回到 short-drama 检查剧情连贯性（已有专业剧本则直接复用）。Humanizer 只润色表达，不改剧情事实、人物关系、专有名词、数字、时间线、世界观规则、场次结构或拍摄标记。剧本确认后再由用户选择目标集数并创建或复用项目。资产只覆盖目标集出现的人物及形象版本、场景、道具，以及有效配音模型需要的音色设定；音色设定不等于授权执行声音设计或 TTS。拆镜前必须输出资产—剧情匹配审计，清零缺失、多余、同名、真假、年龄、状态、选版和连线冲突。拆镜后逐镜全量审计覆盖、重复、无效、缺失、穿帮、轴线、视线、动作、道具交互朝向、语言和来源身份，不抽样；P0/P1 未清零时不得进入图片、声音或视频生产。

需要测试专业 Markdown 剧本拆镜时，在 storyboard-breakdown 节点配置中显式写入 {"storyboardPipelineVersion":2,"sourceFormat":"screenplay-markdown.v1","targetLanguage":"pt-BR","platform":"TikTok","aspectRatio":"9:16"}。targetLanguage 可为任意规范 BCP 47 标签，且剧本的场景标题、对白、旁白和屏显必须提供同标签的本地化块。只连接一条剧本输入，并连接该集实际使用的全部人物、场景和道具文本资产。该模式只产生分镜文本与镜头资产：不得因为声音设定而运行 voice-design，也不得运行 tts、图片、音频或视频节点。任务完成后重新读取画布和资产，确认来源覆盖与逐字校验已通过、镜头节点存在，且没有新增 IMAGE、AUDIO 或 VIDEO 版本；失败任务必须确认没有新增分镜版本或镜头。

视觉生成也有两次人工确认门禁：生成分镜图前，Agent 必须实际展示人物、场景、道具等已选素材预览并取得用户确认；生成视频前，必须实际展示分镜图，并确认分镜内容与视频镜头范围。随后可运行 canvas continuity analyze，用零模型费用分析相邻镜头依赖；waiting-for-source-video 只表示尾帧建议尚不可用，不阻止后镜独立生成。用户选择严格连续时，再等待前镜成功并显式执行 --apply-ready。默认直接使用完整宫格或故事版作为视频参考，不预先拆格；只有首轮视频的动作顺序、构图、关键帧遵循或画面质量明显不佳，或模型不支持完整分镜参考时，Agent 才会展示问题与拆格方案，并在用户确认后只用拆分结果重跑受影响镜头。该命令不会运行视频任务，生成后仍需审计真实画面。仅报告资产 ID、URL、文件路径或生成成功不算展示，未确认时不得进入下一步。

用户未另行指定时，Skill 会把角色、道具、场景/背景、分镜图等视觉参考素材统一生成为 16:9，并在实时节点 schema 支持时显式写入节点，避免误继承项目中的其他画幅。视频生成时长必须以当前模型实时 durationOptions 为准。只有实时模型仅提供 5、10、15 秒时，标准流程才为剪辑预留余量，按镜头目标时长向上取这三档，并保留原目标时长供后续裁切。其他模型使用经用户确认的实时合法值，不得硬编码为三档。

每批图片、视频或音频生成结束后，Agent 必须先做自我审计，再报告成功或进入下一付费阶段。审计会重新读取任务、画布、节点、连线和资产，核对任务终态、selected version、输入引用、最终有效配置，并确认视频时长仍属于当前模型实时 durationOptions 的合法值。Agent 还会实际查看预览中的人物身份、场景、道具、动作、连续性及黑帧、拉伸、裁切、破音或空结果，并列出通过项、缺陷、失败项和未决项；再次付费生成、改选版本或覆盖用户内容前仍需用户确认。

storyboard-image 的实时 configSchema 现在提供节点级 gridSize。Agent 会分析每个镜头的动作阶段、运镜变化、多人调度和连续性难度，选择实时 schema 允许的最小够用格数，展示建议并经用户确认后逐镜写入。简单镜头建议 4 格，常规镜头使用默认 6 格，复杂镜头建议 9 格；16/25 格只用于明确需要的长动作或高密度关键帧。未单独设置或连接旧服务时回退到项目格数，系统默认为 6 格。

character-visual-design 的实时 configSchema 提供 candidateCount，范围为 1～3，默认值为 1。CLI 继续按实时 schema 通用校验和写入；需要多个视觉描述时显式设置该字段，每个描述仍应分别进入独立的三视图和图片资产链。

通用图片生成和图片编辑节点的实时 configSchema 支持字符串 resolution、quality，视频生成节点支持字符串 resolution。具体取值必须来自 canvas settings get 中当前模型的 capabilities；模型未声明对应选项时不写入，节点未显式配置时由服务端采用第一个可用选项。

tts 的实时 configSchema 会在百炼 CosyVoice 场景声明 voice、languageHints、format、sampleRate、volume、cosyRate、pitch 和 instruction，并把 voice 标为必需字段。其字段说明明确 cosyvoice-v3.5-plus 与 cosyvoice-v3.5-flash 只接受声音设计或声音克隆生成的同型号 ID；不要使用 longxiaochun_v3 等系统预置音色。rate 仅保留给非 CosyVoice 模型。CLI 在新增或更新节点前会校验字符串/数字类型、整数、枚举以及 minimum/maximum，因此音量、语速和音调等越界配置会在发送画布写请求前停止。Agent 必须先确认最终 audioModel 和兼容音色，再从实时 schema 选择其余参数。

声音设计使用实时目录中的 voice-design：通过 prompt 输入或配置提供声音描述，按 schema 配置试听文本、目标模型、前缀和语言提示，任务成功后把 voice-design.voice 连接到 tts.voice。声音克隆使用 voice-clone：连接参考音频到 audio，按 schema 配置目标模型与克隆参数，成功后同样把 voice 输出连接到 tts.voice。音色 ID 由服务端任务结果生成，不应预先猜测。

任务涉及剪辑设计或实现、Remotion composition、时间线、裁切、字幕、转场、音频编排或渲染时，Agent 必须加载并遵循已安装的 remotion-best-practices Skill，再使用 VVICAT 已确认的素材完成剪辑；纯素材生成不触发该 Skill。

安装或更新 npm CLI 时，安装脚本会同步安装或更新 Codex 的 using-vvicat-ai-short-studio-cli、short-drama 与 humanizer。每个 Skill 独立检查；已被用户修改或非 CLI 托管的副本会保留并跳过，不会阻止其他 Skill 更新，也不会导致 CLI 安装失败。如需关闭自动安装，设置 VVICAT_SKIP_SKILL_INSTALL=1。


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

默认自动目标是 ~/.codex/skills。使用 --target agents 可手动安装到 ~/.agents/skills。CLI 记录安装版本与 SHA-256；检测到用户修改时不会自动覆盖，必须由用户显式使用 --force。

CLI 直接复用产品现有接口：预检与 Supabase 公共配置使用 /api/v1/bootstrap，项目和画布使用 /api/projects，节点目录使用 /api/canvas/node-types，资产版本选择使用 /api/projects/<projectId>/canvas/assets/<assetId>。显式登录参数和环境变量优先于 bootstrap 与本地 profile。

2026-09-05：资产管理 SSOT Phase 1.1 — 删除 5 个已迁移的 /api/asset-hub/* 路由（generate-image / modify-image / select-image / undo-image / update-asset-label），并移除 5 个多方法路由的 GET handler。CLI 不直接调用这些端点，因此不影响 CLI 行为。详见 docs/asset-management-api-matrix.md（Phase 1.1 段）。

canvas node types [kind] --json 接受节点目录 schema v1/v2，并显示动态节点的定义与发布版本字段。后台发布后重新读取目录即可创建新节点；归档会从新增目录隐藏节点，但既有实例仍按画布返回的固定版本 schema 更新和执行。CLI 创建动态节点不会提交 definitionVersionId，该字段始终由服务端固定。

节点执行若返回 MODEL_PRICING_NOT_CONFIGURED，表示当前模型能力参数没有匹配的已发布价格档位。请调整节点参数或由管理员发布对应价格；重复提交不会自行恢复。

项目的 Agent PostToolUse Hook 会在相关代码变化后运行影响分析；提交门禁还会运行 npm run check:ai-short-studio-cli-sync -- --staged。当无限画布、项目、任务、模型配置或 CLI 使用的现有 API 契约变化时，CLI 实现、配套 Skill、中英文 CLI 文档和包 README 必须同步审查。

npm 发布

发布脚本只从 NODE_AUTH_TOKEN 环境变量读取 npm Granular Access Token，不把 token 写入仓库、包清单或命令参数。Docker 发布可通过 NPM_PUBLISH_PACKAGE_NAME 选择个人或组织 scope；当前默认发布到个人包 @aswless_854771076/ai_short_studio_cli，获得组织权限后再切换为 @vvicat/ai_short_studio_cli。


cd packages/ai_short_studio_cli
export NODE_AUTH_TOKEN="<token>"
npm run release:dry-run
npm run release:test -- --version 0.1.0-beta.0
npm run release

Token 应限制到目标包，并在 CI 中保存为加密 Secret。发布脚本会在测试发布时临时替换包名和版本，并在成功或失败后恢复正式清单。

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

云效 Flow 使用托管构建集群和 Node.js 22 即可，不需要自有 Runner。把 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

个人账号 beta 测试执行 npm run release:ci:test -- --version 0.1.1-beta.0。两个 CI 命令都会先运行测试和类型检查，发布后等待 npm registry 可见，再从 npm 安装精确版本并验证 CLI 与配套 Skill。只有流水线需要访问内网资源或固定出口 IP 时才配置自有构建集群。

latest 只表示 npm 默认安装的 dist-tag，不会自动升级已经全局安装的 CLI。个人包手动更新命令为 npm install --global @aswless_854771076/ai_short_studio_cli@latest；切换组织包后替换为对应包名即可。

机器可读约定

结构化结果使用 JSON。接口错误包含 error.code、message、status、retryable 和 details。退出码为：0 成功、3 未认证、4 不存在、5 禁止或冲突、6 参数错误、7 其他错误。