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 --google
ai-short-studio auth login --memhub
ai-short-studio project list --json
ai-short-studio canvas node types --json

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

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

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

ai-short-studio auth signup --email [email protected] --password-stdin
ai-short-studio auth login --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://ai-short-studio.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 稳定版本并默认更新当前全局包，再检查登录态和文本、人物、场景、故事版、视频模型配置。npm registry 暂时不可用时服务端使用配置版本降级。更新后必须按输出重跑；明确不允许全局写入时使用 --no-update。

命令范围

• 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 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 --wait --json
ai-short-studio task wait --task <task1> --task <task2> --concurrency 4 --json

canvas node update 的 --set key=<JSON>、--unset key、--title、--x 和 --y 只修改指定字段；旧 --config 仍兼容。update-many 在一次画布版本校验中原子更新多个节点。结构化生成资源仍必须使用 edit-resource 或 edit-shot，不能通过字段更新改写 artifact。批量执行与等待默认并发为 4、上限为 16；Agent 应优先单进程批处理，避免为每个节点启动一个 CLI 进程。

使用 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 与配置，版本由服务端固定，不能由客户端伪造。

新建视频生成节点按实时模型能力执行：首尾帧模型使用 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 格。

专业 Markdown 剧本可在 storyboard-breakdown 配置中显式使用 storyboardPipelineVersion: 2、sourceFormat: screenplay-markdown.v1、任意规范 BCP 47 targetLanguage（如 en、ar、fr、pt-BR 或 zh-Hant）、platform: TikTok 和 aspectRatio: 9:16。CLI 通过现有通用节点配置写入这些字段。该模式只生成分镜文本和镜头资产，不自动运行声音、TTS、图片、音频或视频节点。

storyboard-breakdown 还可按实时 schema 写入 targetDurationSeconds、pacingPreset 和 maxShotCount。它们是镜头规划预算，超出只提示而不阻塞源文完整覆盖；留空时不限制镜头数，也不启用时长硬门禁。生成链采用滚动异步调度：单镜分镜图完成后立即进入视频提示词，提示词通过审计后立即提交该镜视频，可恢复失败不阻塞其他镜头。内置 Skill 同时补全字幕、人物/场景首次介绍角标、有动机的镜头衔接、声音平衡和成片验收流程。

标准短剧制作读取主 Skill references/short-drama/ 与 references/humanizer/：先生成和复核专业剧本，再审计模板化台词、虚浮修辞与机械节奏，最后检查剧情连贯性。hypit 视频制作流程读取 references/hypit/。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 canvas settings set --project <PROJECT_ID> --field outputLanguage --value pt-BR 设置，接受任意规范 BCP 47 标签；用 null 恢复自动跟随输入。语言变化只把相关下游节点标为 stale，不删除历史资产或自动生成。交付时只下载每镜 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 跳过。

发布

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

export NODE_AUTH_TOKEN="<token>"
npm run release:dry-run
npm run release:test -- --version 0.1.0-beta.0
# 加入 @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。latest 不会自动升级已安装的全局 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

个人账号 beta 测试使用：

npm run release:ci:test -- --version 0.1.1-beta.0

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