@aswless_854771076/ai_short_studio_cli 0.1.5 → 0.1.7

package/README.md

@@ -18,10 +18,13 @@ ai-short-studio canvas node types --json
 ai-short-studio auth login --email user@example.com --password-stdin
 ```
 
-CLI 只把 refresh token 保存到系统钥匙串，access token 仅驻留内存并在到期前自动刷新。首次登录通过参数或 `VVICAT_SUPABASE_URL`、`VVICAT_SUPABASE_PUBLISHABLE_KEY` 提供 Supabase 公共配置。服务地址和非敏感 profile 写入系统配置目录；可使用 `--profile`、`--base-url` 或 `VVICAT_BASE_URL` 切换环境。
+CLI 只把 refresh token 保存到系统钥匙串，access token 仅驻留内存并在到期前自动刷新。首次登录会从服务端 bootstrap 取得 Supabase 公共配置，也可用 `VVICAT_SUPABASE_URL`、`VVICAT_SUPABASE_PUBLISHABLE_KEY` 显式覆盖。服务地址和非敏感 profile 写入系统配置目录；切换环境时必须使用独立的 `--profile`，避免复用旧认证。
+
+创作前运行 `ai-short-studio preflight --json`。CLI 会通过公开的 `/api/v1/bootstrap` 检查服务连通性、取得 Supabase 公共配置、比较稳定版本并默认更新当前全局包，再检查登录态和文本、人物、场景、故事版、视频模型配置。更新后必须按输出重跑；明确不允许全局写入时使用 `--no-update`。
 
 ## 命令范围
 
+- `ai-short-studio preflight`：创作前版本、连通性、认证和模型配置检查。
 - `ai-short-studio project`：无限画布项目增删改查。
 - `ai-short-studio canvas get|apply`：读取或批量更新画布。
 - `ai-short-studio canvas node`：节点类型/schema 查询、节点读写、执行。
@@ -36,13 +39,13 @@ ai-short-studio canvas edge delete <edgeId> --project <projectId> --yes --json
 ai-short-studio canvas asset select-version <assetId> --project <projectId> --version <versionId> --json
 ```
 
-CLI 直接使用现有 `/api/projects`、`/api/canvas/node-types`、项目画布与资产路由，不要求服务端额外提供版本化包装接口。
+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`。
 
 退出码：`0` 成功，`3` 未认证，`4` 不存在，`5` 禁止或冲突，`6` 参数错误，`7` 其他错误。
 
-配套 Agent Skill 位于 `skills/using-vvicat-cli`，随 npm 包发布。安装或更新 CLI 时会自动安装到 Codex Skill 目录；已被用户修改或非 CLI 托管的目录不会被覆盖。
+配套 Agent Skill 位于 `skills/using-vvicat-ai-short-studio-cli`，随 npm 包发布。安装或更新 CLI 时会自动安装到 Codex Skill 目录；已被用户修改或非 CLI 托管的目录不会被覆盖。
 
 ```bash
 ai-short-studio skill install --target codex

package/dist/commands/preflight.d.ts

@@ -0,0 +1,12 @@
+import { BaseCommand } from '../base-command.js';
+export default class Preflight extends BaseCommand {
+    static description: string;
+    static flags: {
+        update: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        '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/preflight.js

@@ -0,0 +1,40 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../base-command.js';
+import { ProfileStore } from '../config/profiles.js';
+import { VvicatApi } from '../domain/vvicat-api.js';
+import { createRuntime } from '../runtime.js';
+import { compareStableVersions, fetchBootstrap, inspectCreationConfig, readCurrentPackageIdentity, updateCliPackage, } from '../preflight.js';
+export default class Preflight extends BaseCommand {
+    static description = '创作前检查 CLI、服务连接、认证和模型配置';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        update: Flags.boolean({ description: '发现新版本时更新全局 CLI', default: true, allowNo: true }),
+    };
+    async run() {
+        const { flags } = await this.parse(Preflight);
+        const profiles = new ProfileStore();
+        const selected = flags.profile ? await profiles.get(flags.profile) : await profiles.current();
+        const baseUrl = (flags['base-url'] || process.env.VVICAT_BASE_URL || selected?.baseUrl || '').replace(/\/+$/, '');
+        if (!baseUrl)
+            this.error('缺少服务地址，请传入 --base-url 或设置 VVICAT_BASE_URL');
+        const bootstrap = await fetchBootstrap(baseUrl);
+        const current = await readCurrentPackageIdentity();
+        const hasUpdate = compareStableVersions(current.version, bootstrap.cli.latestVersion) < 0;
+        const version = flags.update
+            ? updateCliPackage({ current, latest: bootstrap.cli })
+            : {
+                updated: false,
+                restartRequired: false,
+                currentVersion: current.version,
+                latestVersion: bootstrap.cli.latestVersion,
+            };
+        if (version.restartRequired) {
+            this.print({ connected: true, version, ready: false, nextAction: '重新运行 ai-short-studio preflight --json' });
+            return;
+        }
+        const runtime = await createRuntime(flags);
+        await runtime.client.request('/api/auth/session');
+        const readiness = inspectCreationConfig(await new VvicatApi(runtime.client).config());
+        this.print({ connected: true, authenticated: true, updateAvailable: hasUpdate, version, ...readiness });
+    }
+}

package/dist/preflight.d.ts

@@ -0,0 +1,46 @@
+export interface BootstrapConfig {
+    cli: {
+        packageName: string;
+        latestVersion: string;
+    };
+    supabase: {
+        url: string;
+        publishableKey: string;
+    };
+}
+type Fetcher = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+type PackageRunner = (command: string, args: string[], options: {
+    shell: false;
+    timeout: number;
+    encoding: 'utf8';
+}) => {
+    status: number | null;
+    error?: Error;
+};
+export declare function fetchBootstrap(baseUrl: string, fetcher?: Fetcher): Promise<BootstrapConfig>;
+export declare function compareStableVersions(left: string, right: string): number;
+export declare function readCurrentPackageIdentity(): Promise<{
+    name: string;
+    version: string;
+}>;
+export declare function updateCliPackage(input: {
+    current: {
+        name: string;
+        version: string;
+    };
+    latest: {
+        packageName: string;
+        latestVersion: string;
+    };
+    run?: PackageRunner;
+}): {
+    updated: boolean;
+    restartRequired: boolean;
+    currentVersion: string;
+    latestVersion: string;
+};
+export declare function inspectCreationConfig(config: unknown): {
+    ready: boolean;
+    missing: string[];
+};
+export {};

package/dist/preflight.js

@@ -0,0 +1,140 @@
+import { spawnSync } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+const STABLE_SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const REQUIRED_CREATION_MODELS = {
+    analysisModel: 'llm',
+    characterModel: 'image',
+    locationModel: 'image',
+    storyboardModel: 'image',
+    videoModel: 'video',
+};
+export async function fetchBootstrap(baseUrl, fetcher = fetch) {
+    const normalizedBaseUrl = baseUrl.replace(/\/+$/, '');
+    let response;
+    try {
+        response = await fetcher(`${normalizedBaseUrl}/api/v1/bootstrap`, {
+            headers: { accept: 'application/json' },
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch {
+        throw new Error(`无法连接 VVICAT 服务，请检查 API base URL：${normalizedBaseUrl}`);
+    }
+    if (!response.ok) {
+        throw new Error(`VVICAT 服务预检失败：HTTP ${response.status}；请检查 API base URL：${normalizedBaseUrl}`);
+    }
+    const payload = await response.json().catch(() => null);
+    const data = payload?.data;
+    const cli = data?.cli;
+    const supabase = data?.supabase;
+    if (payload?.ok !== true
+        || typeof cli?.packageName !== 'string'
+        || typeof cli.latestVersion !== 'string'
+        || typeof supabase?.url !== 'string'
+        || typeof supabase.publishableKey !== 'string')
+        throw new Error('VVICAT 服务返回的 bootstrap 配置无效');
+    compareStableVersions(cli.latestVersion, cli.latestVersion);
+    return {
+        cli: { packageName: cli.packageName, latestVersion: cli.latestVersion },
+        supabase: { url: supabase.url, publishableKey: supabase.publishableKey },
+    };
+}
+export function compareStableVersions(left, right) {
+    if (!STABLE_SEMVER.test(left) || !STABLE_SEMVER.test(right))
+        throw new Error('CLI 版本必须是稳定 SemVer');
+    const a = left.split('.').map(Number);
+    const b = right.split('.').map(Number);
+    for (let index = 0; index < 3; index += 1) {
+        if (a[index] !== b[index])
+            return a[index] - b[index];
+    }
+    return 0;
+}
+export async function readCurrentPackageIdentity() {
+    const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    if (typeof manifest.name !== 'string' || typeof manifest.version !== 'string')
+        throw new Error('当前 CLI 包清单无效');
+    return { name: manifest.name, version: manifest.version };
+}
+export function updateCliPackage(input) {
+    if (input.current.name !== input.latest.packageName)
+        throw new Error('服务端返回的 CLI 包名与当前安装包不一致');
+    const comparison = compareStableVersions(input.current.version, input.latest.latestVersion);
+    const result = {
+        updated: false,
+        restartRequired: false,
+        currentVersion: input.current.version,
+        latestVersion: input.latest.latestVersion,
+    };
+    if (comparison >= 0)
+        return result;
+    const run = input.run || ((command, args, options) => {
+        const child = spawnSync(command, args, options);
+        return { status: child.status, error: child.error };
+    });
+    const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const child = run(npm, [
+        'install',
+        '--global',
+        `${input.current.name}@${input.latest.latestVersion}`,
+        '--prefer-online',
+        '--no-audit',
+        '--no-fund',
+    ], { shell: false, timeout: 120_000, encoding: 'utf8' });
+    if (child.error || child.status !== 0)
+        throw new Error('CLI 自动更新失败，请检查 npm 全局安装权限后重试');
+    return { ...result, updated: true, restartRequired: true };
+}
+export function inspectCreationConfig(config) {
+    const value = isRecord(config) ? config : {};
+    const providers = Array.isArray(value.providers) ? value.providers.filter(isRecord) : [];
+    const models = Array.isArray(value.models) ? value.models.filter(isRecord) : [];
+    const defaults = isRecord(value.defaultModels) ? value.defaultModels : {};
+    const capabilityDefaults = isRecord(value.capabilityDefaults) ? value.capabilityDefaults : {};
+    const missing = [];
+    const addMissing = (field) => { if (!missing.includes(field))
+        missing.push(field); };
+    for (const [field, expectedType] of Object.entries(REQUIRED_CREATION_MODELS)) {
+        const modelKey = defaults[field];
+        if (typeof modelKey !== 'string' || !modelKey.trim()) {
+            addMissing(`defaultModels.${field}`);
+            continue;
+        }
+        const model = models.find((item) => item.modelKey === modelKey && item.enabled !== false);
+        if (!model || model.type !== expectedType) {
+            addMissing(`models.${modelKey}`);
+            continue;
+        }
+        const provider = providers.find((item) => item.id === model.provider);
+        if (!provider || provider.hasApiKey !== true)
+            addMissing(`providers.${String(model.provider)}.apiKey`);
+        inspectModelCapabilities(model, modelKey, expectedType, capabilityDefaults, addMissing);
+    }
+    if (!isRecord(value.capabilityDefaults))
+        addMissing('capabilityDefaults');
+    return { ready: missing.length === 0, missing };
+}
+function inspectModelCapabilities(model, modelKey, modelType, defaults, addMissing) {
+    const capabilities = isRecord(model.capabilities) ? model.capabilities : {};
+    const namespace = isRecord(capabilities[modelType]) ? capabilities[modelType] : {};
+    const selection = isRecord(defaults[modelKey]) ? defaults[modelKey] : {};
+    for (const [optionName, rawOptions] of Object.entries(namespace)) {
+        if (!optionName.endsWith('Options') || !Array.isArray(rawOptions) || rawOptions.length === 0)
+            continue;
+        const field = optionName.slice(0, -'Options'.length);
+        const selected = selection[field];
+        if (selected === undefined) {
+            if (modelType === 'image' && field === 'resolution')
+                continue;
+            if (modelType === 'video' && field === 'generateAudio' && rawOptions.includes(false))
+                continue;
+            addMissing(`capabilityDefaults.${modelKey}.${field}`);
+        }
+        else if (!rawOptions.includes(selected)) {
+            addMissing(`capabilityDefaults.${modelKey}.${field}`);
+        }
+    }
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/runtime.js

@@ -2,17 +2,29 @@ import { ApiClient } from './client/api-client.js';
 import { KeyringCredentialStore } from './auth/credential-store.js';
 import { SessionManager, SupabaseAuthProvider } from './auth/session-manager.js';
 import { ProfileStore } from './config/profiles.js';
+import { fetchBootstrap } from './preflight.js';
 export async function createRuntime(flags) {
     const profiles = new ProfileStore();
     const selected = flags.profile ? await profiles.get(flags.profile) : await profiles.current();
     const baseUrl = (flags['base-url'] || process.env.VVICAT_BASE_URL || selected?.baseUrl || '').replace(/\/+$/, '');
     if (!baseUrl)
         throw new Error('缺少服务地址，请传入 --base-url 或设置 VVICAT_BASE_URL');
-    const profile = ensureAuthConfig({
+    if (selected?.baseUrl && selected.baseUrl.replace(/\/+$/, '') !== baseUrl) {
+        throw new Error('API base URL 与当前 profile 不一致；请为新服务使用独立的 --profile，避免复用旧环境认证');
+    }
+    let profile = resolveAuthConfig({
         ...selected,
         name: flags.profile || selected?.name || 'default',
         baseUrl,
     }, flags);
+    if (!profile.supabaseUrl || !profile.supabasePublishableKey) {
+        const bootstrap = await fetchBootstrap(baseUrl);
+        profile = {
+            ...profile,
+            supabaseUrl: profile.supabaseUrl || bootstrap.supabase.url,
+            supabasePublishableKey: profile.supabasePublishableKey || bootstrap.supabase.publishableKey,
+        };
+    }
     await profiles.save(profile);
     const session = new SessionManager({
         profile: profile.name,
@@ -25,7 +37,7 @@ export async function createRuntime(flags) {
         client: new ApiClient({ baseUrl, session, locale: flags.locale }),
     };
 }
-function ensureAuthConfig(profile, flags) {
+function resolveAuthConfig(profile, flags) {
     const supabaseUrl = flags['supabase-url']
         || process.env.VVICAT_SUPABASE_URL
         || process.env.NEXT_PUBLIC_SUPABASE_URL
@@ -35,9 +47,6 @@ function ensureAuthConfig(profile, flags) {
         || process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
         || process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY
         || profile.supabasePublishableKey;
-    if (!supabaseUrl || !supabasePublishableKey) {
-        throw new Error('缺少 Supabase 公共配置；登录时传入 --supabase-url 和 --supabase-publishable-key，或设置对应的 VVICAT_ 环境变量');
-    }
     return {
         ...profile,
         supabaseUrl,

package/dist/skill/skill-manager.js

@@ -3,14 +3,14 @@ import { cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:
 import { homedir } from 'node:os';
 import { dirname, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
-const BUNDLED_SKILL = fileURLToPath(new URL('../../skills/using-vvicat-cli', import.meta.url));
+const BUNDLED_SKILL = fileURLToPath(new URL('../../skills/using-vvicat-ai-short-studio-cli', import.meta.url));
 const PACKAGE_JSON = fileURLToPath(new URL('../../package.json', import.meta.url));
 const MANIFEST = '.vvicat-skill.json';
 export function bundledSkillPath() {
     return BUNDLED_SKILL;
 }
 export function defaultSkillTarget(target) {
-    return join(homedir(), target === 'codex' ? '.codex' : '.agents', 'skills', 'using-vvicat-cli');
+    return join(homedir(), target === 'codex' ? '.codex' : '.agents', 'skills', 'using-vvicat-ai-short-studio-cli');
 }
 export async function skillStatus(target) {
     const packageVersion = await readPackageVersion();

package/package.json

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

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

@@ -0,0 +1,64 @@
+---
+name: using-vvicat-ai-short-studio-cli
+description: Use when an agent needs to inspect or operate VVICAT infinite-canvas projects, nodes, edges, assets, tasks, or model configuration through the ai-short-studio CLI.
+---
+
+# 使用 VVICAT AI Short Studio CLI
+
+## 核心原则
+
+把 `ai-short-studio` 当作机器可读的远程控制接口。创作全程只要目标、素材含义、平台、语言、画幅、时长、风格、人物、场景、道具、模型、节点 schema、候选版本、付费范围或覆盖影响存在未知、缺失或矛盾，就合并列出最少必要问题并询问用户；得到答复前只做只读检查，不用示例值、默认值或自行推断替用户做创作决定。
+
+## 初始化检查
+
+创建项目或修改任何资源前，按顺序执行：
+
+1. 运行 `ai-short-studio preflight --json`。它通过 API base URL 检查连通性和 CLI 最新稳定版，默认发现更新就更新当前全局包；`restartRequired` 为真时必须重跑。连不上时提醒用户检查 `--base-url`、`VVICAT_BASE_URL` 或 profile，不猜地址。
+2. 未登录时执行 `ai-short-studio auth login --google`；CLI 会从服务端取得 Supabase 公共配置。登录后重跑 preflight。`ready` 为 false 时，把 `missing` 一次性告知用户并询问如何补齐；新配置模型首选公司的 [StarRouter](https://starrouter.io/)，账号开通联系邱茂。
+3. 运行 `ai-short-studio skill status --target codex --json`；非 current 时询问后更新，用户修改或非托管目录不得擅自 `--force` 覆盖。
+4. 运行 `ai-short-studio canvas node types --json`，按实时 `inputSchema`、`outputSchema`、`configSchema` 和 `defaultConfig` 确定能力与必填项。
+5. 运行 `project list/get` 与 `canvas get`，确认 `INFINITE_CANVAS`、目标项目、现有节点、资产 selected version 和本次创作参数。任何缺口仍按核心原则询问。
+
+## 标准创作流程
+
+1. 明确原始故事或剧本、目标受众与平台、语言、画幅、总时长与镜头时长、风格参考、人物/场景/道具约束，以及交付是否包含剧本、设定、分镜图、视频和音频；缺项先问。
+2. 完成 preflight、节点目录、模型配置与项目检查。新建项目先确认名称和用途；既有项目优先复用已确认的节点与 selected version。
+3. 原文需要改编时执行 `novel-to-script`。分镜拆解前必须先完成人物、场景、道具等本次故事涉及的素材生成；每个生成任务都 `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、文件路径或文字说明不算展示。用户明确确认素材与选版后，优先建议选择 `imageLayout: storyboard`：它适合连续叙事审阅并保留格序、镜号、景别、机位和运镜。也要说明 `grid` 与 `single` 可选；最终由用户确认布局、镜头范围、参考资产、模型与费用范围。未展示或未确认时禁止生成分镜图。
+6. 执行分镜图后检查任务终态、候选资产与 selected version，并把实际分镜图或可访问预览展示给用户。用户明确确认分镜图以及需要制作的视频镜头后，才能刷新画布并复用服务端自动创建的 `storyboard-video-prompt`；提示词再经用户确认后执行自动创建的 `video-generate`，音频按交付范围执行。未展示或未确认分镜图时禁止生成视频。
+7. 每次写入前重新读取画布版本；优先用专用 node/edge 命令，批量变更才用 `canvas apply`。每次执行都读取真实任务 ID 并 `task wait`，不用固定 sleep。
+8. 交付前确认 selected version 与下载目录，记录项目、节点、任务和资产 ID、失败项与未决项。临时项目在所有结束路径删除；既有项目绝不擅自删除。
+
+详细命令按需读取 [references/commands.md](references/commands.md)，或运行 `ai-short-studio <topic> --help`。
+
+## 安全边界
+
+- 不把密码、access token、refresh token 或 API Key 放入参数、日志、Skill 或仓库。
+- 密码登录使用 `printf`/管道以外的安全 stdin 来源；自动化环境使用秘密管理器注入 stdin。
+- `config get` 只应返回 `hasApiKey`，不得依赖或要求服务端回显密钥。
+- 删除用户既有项目、覆盖完整画布或修改模型配置前，先明确目标和影响；没有授权就停在读取或生成变更计划。
+- 对版本冲突重新读取画布后重算变更，不盲目重试旧的 `expectedVersion`。
+
+## 示例
+
+```bash
+ai-short-studio canvas node types --json
+ai-short-studio project create --name "agent-draft-20260722" --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
+```
+
+从 JSON 输出中取得真实 ID；示例中的环境变量仅表示调用方已安全解析并保存结果。
+
+## 常见错误
+
+- 节点类型写死：先读 `canvas node types`，服务端目录才是事实来源。
+- 配置不全仍继续：先做初始化检查；模型、项目或用户意图有缺口时先询问。
+- CLI 有更新仍用旧进程继续：更新后必须重跑 preflight。
+- 自动创建的下游节点重复添加：任务完成后先刷新画布并复用真实节点 ID。
+- 素材未完成或未连线就拆分镜：人物、场景、道具等相关素材必须任务成功、已确认 selected version，并逐项连接到 `storyboard-breakdown` 对应输入后才能执行。
+- 未展示产物就继续：生成分镜图前展示并确认素材，生成视频前展示并确认分镜图；只报告 ID 或路径不能代替预览与用户确认。
+- 只检查任务创建响应：必须 `task wait` 并检查终态和错误字段。
+- 下载列表中的任意 URL：先确认资产的 selected version，再下载。
+- 测试创建资源但未清理：用调用方的 `finally`/trap 删除唯一前缀项目。

package/skills/using-vvicat-ai-short-studio-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "使用 VVICAT AI Short Studio CLI"
+  short_description: "通过命令行安全操作 VVICAT 无限画布项目与产物"
+  default_prompt: "使用 $using-vvicat-ai-short-studio-cli 安全地完成 VVICAT 无限画布项目、节点、任务、产物或模型配置操作。"

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

@@ -2,6 +2,16 @@
 
 所有命令支持 `--base-url`、`--profile`、`--locale zh|en` 和 `--json`。默认档案保存服务地址与默认项目；refresh token 仅保存在系统钥匙串。
 
+## 创作前预检
+
+```bash
+ai-short-studio --version
+ai-short-studio preflight --json
+ai-short-studio preflight --no-update --json
+```
+
+`preflight` 通过 `/api/v1/bootstrap` 检查 API base URL 连通性、取得 Supabase 公共配置、比较服务端推荐的稳定 CLI 版本，并检查认证和标准创作所需模型。默认发现新版本会更新当前全局 npm 包；更新后按 `nextAction` 重跑。`--no-update` 仅用于用户明确禁止全局写入时。
+
 ## Skill 管理
 
 ```bash
@@ -88,3 +98,13 @@ ai-short-studio config set --file <config.json> --json
 ```
 
 `config set` 接受 `models`、`providers`、`defaultModels`、`capabilityDefaults`、`workflowConcurrency` 的部分对象。provider 的 `apiKey` 缺省时保留现有密钥，空字符串表示清除；敏感配置文件不要提交到版本库。
+
+## 标准创作命令顺序
+
+先只读执行 `preflight` → `canvas node types` → `project list/get` → `canvas get` → `canvas node list` → `canvas asset list`。确认用户意图和配置后，才执行 node add/edge add/node run，并对每个返回任务使用 `task wait`。
+
+执行 `storyboard-breakdown` 前，必须先完成本次故事涉及的全部人物、场景、道具等素材节点：逐个等待生成任务成功，用 `canvas asset get/list` 核对并在用户确认后设置 selected version。随后依据实时 schema，用 `canvas edge add` 将剧本节点和每个相关素材节点分别连接到 `storyboard-breakdown` 对应输入 handle，再用 `canvas get` 与 `canvas edge list` 核对无遗漏。任一素材任务未成功、selected version 为空或对应连线缺失时，都不得执行分镜拆解；素材范围不清楚时先询问用户。即使服务端 schema 把人物、场景或道具输入标为可选，标准创作流程也不能跳过本次故事实际涉及且已确认使用的素材。
+
+生成 `storyboard-image` 前，用 `canvas asset get/list` 取得素材 selected version，必要时通过 `canvas asset download` 下载，并向用户实际展示人物、场景、道具等预览；用户确认后才可执行。生成视频前，同样取得并展示实际分镜图或可访问预览，确认分镜图和视频镜头范围后才可执行 `storyboard-video-prompt` / `video-generate`。仅输出资产 ID、URL、文件路径或成功状态不能代替展示；任一确认缺失时停止并询问。
+
+`storyboard-breakdown`、`storyboard-image` 和 `storyboard-video-prompt` 成功后会由服务端物化下游节点。每步完成后先重新 `canvas get` 或 `canvas node list` 获取真实 ID，禁止照示例伪造 ID 或重复建节点。

package/skills/using-vvicat-cli/SKILL.md

@@ -1,59 +0,0 @@
----
-name: using-vvicat-cli
-description: Use when an agent needs to inspect or operate VVICAT infinite-canvas projects, nodes, edges, assets, tasks, or model configuration through the ai-short-studio CLI.
----
-
-# 使用 VVICAT CLI
-
-## 核心原则
-
-把 `ai-short-studio` 当作机器可读的远程控制接口。认证后首先拉取服务端节点目录，先了解当前有哪些功能节点，再检查模型和项目配置。任何必要配置不完整或信息不确定时，先询问用户，不猜测、不执行写操作。
-
-## 初始化检查
-
-认证成功后、创建项目或修改任何资源前，按顺序执行：
-
-1. 运行 `ai-short-studio canvas node types --json`，检查节点列表及各节点的 `inputSchema`、`outputSchema`、`configSchema` 和 `defaultConfig`，据此确定可用功能与必填项。
-2. 运行 `ai-short-studio config get --json`，检查本次会用到的 `providers`、`models`、`defaultModels` 和 `capabilityDefaults`，包括 provider 的 `hasApiKey` 是否为真。需要新配置模型时，首选公司的 [StarRouter](https://starrouter.io/)；需开通账号时联系邱茂。
-3. 运行 `ai-short-studio project list --json`。已有项目再运行 `ai-short-studio project get <projectId> --json` 和 `ai-short-studio canvas get --project <projectId> --json`，检查项目类型、目标项目、画布现状及节点必需输入；新项目则确认名称、用途和节点所需业务参数。
-4. 上述配置缺失、相互矛盾、无法判定是否适用，或用户意图存在任何不确定时，合并列出缺口并询问用户；得到答复前停在只读检查。
-
-## 工作流
-
-1. 运行 `ai-short-studio auth status --json`。首次登录通过参数或 `VVICAT_BASE_URL`、`VVICAT_SUPABASE_URL`、`VVICAT_SUPABASE_PUBLISHABLE_KEY` 提供服务和 Supabase 公共配置，再运行 `ai-short-studio auth login --google`；非交互环境才通过 stdin 传密码。
-   npm 安装或更新 CLI 时会自动同步 Codex Skill。先运行 `ai-short-studio skill status --json`；`current` 为 false 时，说明自动同步可能因用户修改或非托管目录被跳过，再询问是否执行 `ai-short-studio skill update`。
-2. 完成上述初始化检查。确认目标项目是 `INFINITE_CANVAS`；创建测试项目时使用唯一前缀，并记录项目 ID。
-3. 严格按节点目录返回的 schema 和默认配置构造数据。
-4. 写入前运行 `ai-short-studio canvas get --project <id> --json` 获取当前结构；优先使用专用 node/edge 命令，批量变更才用 `canvas apply`。
-5. 执行节点后读取返回的任务 ID，并用 `ai-short-studio task wait <taskId> --json` 等待终态。不要使用固定时长 sleep。
-6. 下载前读取资产及所选版本，再使用 `canvas asset download` 写入明确目录。
-7. 对临时项目始终在结束路径中执行 `ai-short-studio project delete <id> --yes`，包括命令失败时。
-
-详细命令按需读取 [references/commands.md](references/commands.md)，或运行 `ai-short-studio <topic> --help`。
-
-## 安全边界
-
-- 不把密码、access token、refresh token 或 API Key 放入参数、日志、Skill 或仓库。
-- 密码登录使用 `printf`/管道以外的安全 stdin 来源；自动化环境使用秘密管理器注入 stdin。
-- `config get` 只应返回 `hasApiKey`，不得依赖或要求服务端回显密钥。
-- 删除用户既有项目、覆盖完整画布或修改模型配置前，先明确目标和影响；没有授权就停在读取或生成变更计划。
-- 对版本冲突重新读取画布后重算变更，不盲目重试旧的 `expectedVersion`。
-
-## 示例
-
-```bash
-ai-short-studio canvas node types --json
-ai-short-studio project create --name "agent-draft-20260722" --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
-```
-
-从 JSON 输出中取得真实 ID；示例中的环境变量仅表示调用方已安全解析并保存结果。
-
-## 常见错误
-
-- 节点类型写死：先读 `canvas node types`，服务端目录才是事实来源。
-- 配置不全仍继续：先做初始化检查；模型、项目或用户意图有缺口时先询问。
-- 只检查任务创建响应：必须 `task wait` 并检查终态和错误字段。
-- 下载列表中的任意 URL：先确认资产的 selected version，再下载。
-- 测试创建资源但未清理：用调用方的 `finally`/trap 删除唯一前缀项目。

package/skills/using-vvicat-cli/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "使用 VVICAT CLI"
-  short_description: "通过命令行安全操作 VVICAT 无限画布项目与产物"
-  default_prompt: "使用 $using-vvicat-cli 安全地完成 VVICAT 无限画布项目、节点、任务、产物或模型配置操作。"