@aswless_854771076/ai_short_studio_cli 0.1.43 → 0.1.45

package/README.md

@@ -11,9 +11,9 @@ ai-short-studio project list --json
 ai-short-studio canvas node types --json
 ```
 
-npm 包内置 `using-vvicat-ai-short-studio-cli` Agent Skill。安装或升级 CLI 时，`postinstall` 会自动把该 Skill 安装或更新到 Codex；用户修改过或不由 CLI 管理的副本不会被覆盖。设置 `VVICAT_SKIP_SKILL_INSTALL=1` 可关闭自动安装。
+npm 包内置 `using-vvicat-ai-short-studio-cli`、`short-drama` 和 `humanizer` 三个 Agent Skill。安装或升级 CLI 时，`postinstall` 会自动把它们安装或更新到 Codex；用户修改过或不由 CLI 管理的副本不会被覆盖。设置 `VVICAT_SKIP_SKILL_INSTALL=1` 可关闭自动安装。
 
-npm 安装或升级现在会同时安装 `using-vvicat-ai-short-studio-cli` 和 `short-drama`。`skill install/status/update` 默认管理全部内置 Skill，也可用 `--skill short-drama` 只管理短剧 Skill；某个 Skill 被用户修改时会独立跳过，不影响另一个 Skill。创作剧本使用 `short-drama`，操作 VVICAT 使用主 CLI Skill。
+`skill install/status/update` 默认管理全部内置 Skill，也可用 `--skill short-drama` 或 `--skill humanizer` 单独管理。某个 Skill 被用户修改时会独立跳过，不影响其他 Skill。剧本先用 `short-drama` 创作和复核，再用 `humanizer` 审计、去除 AI 味，最后回到 `short-drama` 检查剧情连贯性；操作 VVICAT 使用主 CLI Skill。
 
 邮箱注册和登录从 stdin 读取密码：
 
@@ -28,7 +28,7 @@ Agent 代操作时，用户已在当前会话明确提供的密码只能直接
 
 注册确认链接使用当前 profile 的 `baseUrl` 和 `--locale`，指向同域的 `/{locale}/auth/callback`。API 与网页需保持同域，并在 Supabase Redirect URLs 中允许各环境的 `/**`；Site URL 只作为未显式传入回调时的生产兜底。
 
-CLI 只把 refresh token 保存到系统钥匙串，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`，避免复用旧认证。
+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`。
 
@@ -37,12 +37,12 @@ CLI 只把 refresh token 保存到系统钥匙串，access token 仅驻留内存
 - `ai-short-studio preflight`：创作前版本、连通性、认证和模型配置检查。
 - `ai-short-studio project`：无限画布项目增删改查。
 - `ai-short-studio canvas settings get|set`：读取或原子更新项目配置。
-- `ai-short-studio canvas get|apply`：读取画布或执行低层图补丁。
-- `ai-short-studio canvas node`：节点类型/schema 查询、节点读写、执行。
+- `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 task`：异步任务读取、等待和取消。
+- `ai-short-studio task`：异步任务读取、批量等待和取消。
 - `ai-short-studio config`：模型、provider、默认模型、能力默认值和并发配置。
 
 ```bash
@@ -80,7 +80,20 @@ ai-short-studio canvas settings set --project "$PROJECT_ID" --file settings.json
 }
 ```
 
-`null` 或空字符串会清除项目覆盖并恢复继承。设置 `artStyle` 会把当前关联的 `visualBible` 保存为项目快照，画风库后续变化不会反向更新项目；同一请求显式传入 `visualBible` 时以显式值为准。所有者和管理员可写，协作者只读；409 冲突后重新 `settings get` 并携带新 `expectedVersion` 重试。`canvas apply` 仍用于节点、连线、删除和视口等低层画布图补丁；同阶段有多个可合并图变更时默认一次批量提交并统一回读，批量入口不可用或合法批量请求仍因粒度失败时才回退单条命令。Pexels 继续使用 `project provider get|set|test`。
+`null` 或空字符串会清除项目覆盖并恢复继承。设置 `artStyle` 会把当前关联的 `visualBible` 保存为项目快照，画风库后续变化不会反向更新项目；同一请求显式传入 `visualBible` 时以显式值为准。所有者和管理员可写，协作者只读；409 冲突后重新 `settings get` 并携带新 `expectedVersion` 重试。`canvas apply` 仍用于节点、连线、删除和视口等低层画布图补丁；同阶段有多个可合并图变更时默认一次批量提交并统一回读。已经读取画布时传入 `--canvas-id` 与 `--expected-version`，可避免保存前再请求一次全图。批量入口不可用或合法批量请求仍因粒度失败时才回退单条命令。Pexels 继续使用 `project provider get|set|test`。
+
+常用审计优先使用一次聚合查询，不必临时编写脚本或逐条请求：
+
+```bash
+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 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` 或来源身份，旧版本继续可选。
 
@@ -96,7 +109,7 @@ CLI 通过 `/api/v1/bootstrap` 完成版本、连通性与 Supabase 公共配置
 
 专业 Markdown 剧本可在 `storyboard-breakdown` 配置中显式使用 `storyboardPipelineVersion: 2`、`sourceFormat: screenplay-markdown.v1`、`targetLanguage: en|ar`、`platform: TikTok` 和 `aspectRatio: 9:16`。CLI 通过现有通用节点配置写入这些字段。该模式只生成分镜文本和镜头资产，不自动运行声音、TTS、图片、音频或视频节点。
 
-标准短剧制作先用随包安装的 `short-drama` 生成并审校专业剧本（已有专业剧本直接复用），再选择目标集数、创建或复用项目，并只建立目标集实际出现的人物、场景、道具和可选音色设定。拆镜前必须完成资产—剧情匹配审计；拆镜后逐镜全量检查重复、无效、缺失、冲突、穿帮、连续性、道具交互朝向、语言和来源身份。P0/P1 未清零时不得进入图片、声音或视频生产。
+标准短剧制作先用随包安装的 `short-drama` 生成和复核专业剧本，再用 `humanizer` 审计模板化台词、虚浮修辞与机械节奏，随后回到 `short-drama` 检查剧情连贯性（已有专业剧本直接复用）。Humanizer 只润色表达，不改剧情事实、人物关系、专有名词、数字、时间线、世界观规则、场次结构或拍摄标记。剧本确认后再选择目标集数、创建或复用项目，并只建立目标集实际出现的人物、场景、道具和可选音色设定。拆镜前必须完成资产—剧情匹配审计；拆镜后逐镜全量检查重复、无效、缺失、冲突、穿帮、连续性、道具交互朝向、语言和来源身份。P0/P1 未清零时不得进入图片、声音或视频生产。
 
 `character-visual-design` schema 暴露 `candidateCount`，范围为 1～3，默认值为 1。CLI 按实时 schema 校验和写入；多个视觉描述仍分别进入独立三视图和图片资产链。
 
@@ -116,6 +129,17 @@ CLI 通过 `/api/v1/bootstrap` 完成版本、连通性与 Supabase 公共配置
 
 配套 Agent Skill 位于 `skills/using-vvicat-ai-short-studio-cli`，随 npm 包发布。安装或更新 CLI 时会自动安装到 Codex Skill 目录；已被用户修改或非 CLI 托管的目录不会被覆盖。
 
+## 本地真实验收
+
+CLI 开发完成后运行以下命令：
+
+```bash
+cd packages/ai_short_studio_cli
+npm run test:local-e2e
+```
+
+该命令先构建真实 CLI，再启动隔离的本地 mock API，通过多个 `bin/run.js` 子进程验证聚合查询、字段级与多节点更新、`canvas apply` 免预读、批量执行/等待和旧位置参数兼容；同时启动 8 个独立认证进程，确认共享 session 缓存只触发一次模拟 Keychain 读取和一次刷新。测试不连接生产服务、不调用模型，所有配置、令牌、画布和任务数据均在系统临时目录中创建并在结束时清理。
+
 标准创作中，用户未指定时角色、道具、场景/背景和分镜图统一使用 `16:9`；视频按镜头目标时长向上取 5、10、15 秒生成档位，为剪辑保留余量。每批生成后 Agent 必须重新读取任务与资产、核对最终配置并实际检查预览，完成自我审计后才能继续或交付。
 
 ```bash
@@ -123,6 +147,7 @@ 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 --skill short-drama --json
+ai-short-studio skill update --target codex --skill humanizer --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` 跳过。

package/dist/auth/session-cache.d.ts

@@ -0,0 +1,20 @@
+export interface CachedAccessToken {
+    accessToken: string;
+    expiresAt: number;
+}
+export interface AccessTokenCache {
+    delete(profile: string): Promise<void>;
+    get(profile: string): Promise<CachedAccessToken | null>;
+    set(profile: string, session: CachedAccessToken): Promise<void>;
+    withRefreshLock<T>(profile: string, action: () => Promise<T>): Promise<T>;
+}
+export declare class FileAccessTokenCache implements AccessTokenCache {
+    private readonly directory;
+    constructor(directory: string);
+    delete(profile: string): Promise<void>;
+    get(profile: string): Promise<CachedAccessToken | null>;
+    set(profile: string, session: CachedAccessToken): Promise<void>;
+    withRefreshLock<T>(profile: string, action: () => Promise<T>): Promise<T>;
+    private tokenPath;
+    private lockPath;
+}

package/dist/auth/session-cache.js

@@ -0,0 +1,76 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const LOCK_STALE_MS = 30_000;
+const LOCK_WAIT_MS = 50;
+export class FileAccessTokenCache {
+    directory;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    async delete(profile) {
+        await rm(this.tokenPath(profile), { force: true });
+    }
+    async get(profile) {
+        try {
+            const value = JSON.parse(await readFile(this.tokenPath(profile), 'utf8'));
+            if (typeof value.accessToken !== 'string' || typeof value.expiresAt !== 'number')
+                return null;
+            return { accessToken: value.accessToken, expiresAt: value.expiresAt };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+    }
+    async set(profile, session) {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        await chmod(this.directory, 0o700);
+        const path = this.tokenPath(profile);
+        const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporaryPath, `${JSON.stringify(session)}\n`, { mode: 0o600 });
+            await rename(temporaryPath, path);
+            await chmod(path, 0o600);
+        }
+        finally {
+            await rm(temporaryPath, { force: true });
+        }
+    }
+    async withRefreshLock(profile, action) {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        await chmod(this.directory, 0o700);
+        const path = this.lockPath(profile);
+        while (true) {
+            try {
+                await mkdir(path, { mode: 0o700 });
+                try {
+                    return await action();
+                }
+                finally {
+                    await rm(path, { recursive: true, force: true });
+                }
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                const lockStat = await stat(path).catch(() => null);
+                if (lockStat && Date.now() - lockStat.mtimeMs > LOCK_STALE_MS) {
+                    await rm(path, { recursive: true, force: true });
+                    continue;
+                }
+                await new Promise((resolve) => setTimeout(resolve, LOCK_WAIT_MS));
+            }
+        }
+    }
+    tokenPath(profile) {
+        return join(this.directory, `${profileKey(profile)}.json`);
+    }
+    lockPath(profile) {
+        return join(this.directory, `${profileKey(profile)}.lock`);
+    }
+}
+function profileKey(profile) {
+    return createHash('sha256').update(profile).digest('hex').slice(0, 24);
+}

package/dist/auth/session-manager.d.ts

@@ -1,3 +1,4 @@
+import type { AccessTokenCache } from './session-cache.js';
 export interface SessionTokens {
     accessToken: string;
     refreshToken: string;
@@ -26,7 +27,9 @@ export declare class SupabaseAuthProvider implements AuthProvider {
 }
 export declare class SessionManager {
     private current;
+    private lastReturnedAccessToken;
     private refreshPromise;
+    private readonly cache?;
     private readonly credentials;
     private readonly environment;
     private readonly profile;
@@ -35,6 +38,7 @@ export declare class SessionManager {
         profile: string;
         credentials: CredentialStore;
         provider: AuthProvider;
+        cache?: AccessTokenCache;
         environment?: NodeJS.ProcessEnv;
     });
     accessToken(): Promise<string>;
@@ -44,4 +48,5 @@ export declare class SessionManager {
     refreshAccessToken(): Promise<string>;
     logout(): Promise<void>;
     private refresh;
+    private remember;
 }

package/dist/auth/session-manager.js

@@ -49,7 +49,9 @@ function sessionTokens(session) {
 }
 export class SessionManager {
     current = null;
+    lastReturnedAccessToken = null;
     refreshPromise = null;
+    cache;
     credentials;
     environment;
     profile;
@@ -58,15 +60,19 @@ export class SessionManager {
         this.profile = input.profile;
         this.credentials = input.credentials;
         this.provider = input.provider;
+        this.cache = input.cache;
         this.environment = input.environment ?? process.env;
     }
     async accessToken() {
         if (this.environment.VVICAT_ACCESS_TOKEN)
-            return this.environment.VVICAT_ACCESS_TOKEN;
-        if (this.current && this.current.expiresAt > Date.now() + 60_000)
-            return this.current.accessToken;
+            return this.remember(this.environment.VVICAT_ACCESS_TOKEN);
+        if (this.current && isFresh(this.current))
+            return this.remember(this.current.accessToken);
+        const cached = await this.cache?.get(this.profile);
+        if (cached && isFresh(cached))
+            return this.remember(cached.accessToken);
         if (!this.refreshPromise) {
-            this.refreshPromise = this.refresh().finally(() => {
+            this.refreshPromise = this.refresh(false).finally(() => {
                 this.refreshPromise = null;
             });
         }
@@ -75,23 +81,26 @@ export class SessionManager {
     async login(email, password) {
         this.current = await this.provider.login(email, password);
         await this.credentials.set(this.profile, this.current.refreshToken);
+        await this.cache?.set(this.profile, this.current);
     }
     async loginWithGoogle() {
         this.current = await this.provider.loginWithGoogle();
         await this.credentials.set(this.profile, this.current.refreshToken);
+        await this.cache?.set(this.profile, this.current);
     }
     async signup(email, password, emailRedirectTo) {
         this.current = await this.provider.signup(email, password, emailRedirectTo);
         if (!this.current)
             return false;
         await this.credentials.set(this.profile, this.current.refreshToken);
+        await this.cache?.set(this.profile, this.current);
         return true;
     }
     async refreshAccessToken() {
         if (this.environment.VVICAT_ACCESS_TOKEN)
-            return this.environment.VVICAT_ACCESS_TOKEN;
+            return this.remember(this.environment.VVICAT_ACCESS_TOKEN);
         if (!this.refreshPromise) {
-            this.refreshPromise = this.refresh().finally(() => {
+            this.refreshPromise = this.refresh(true).finally(() => {
                 this.refreshPromise = null;
             });
         }
@@ -103,15 +112,33 @@ export class SessionManager {
             if (accessToken)
                 await this.provider.logout(accessToken);
             await this.credentials.delete(this.profile);
+            await this.cache?.delete(this.profile);
         }
         this.current = null;
     }
-    async refresh() {
-        const refreshToken = await this.credentials.get(this.profile);
-        if (!refreshToken)
-            throw new Error('尚未登录，请先运行 ai-short-studio auth login');
-        this.current = await this.provider.refresh(refreshToken);
-        await this.credentials.set(this.profile, this.current.refreshToken);
-        return this.current.accessToken;
+    async refresh(force) {
+        const action = async () => {
+            const cached = await this.cache?.get(this.profile);
+            if (cached && isFresh(cached) && (!force || cached.accessToken !== this.lastReturnedAccessToken)) {
+                return this.remember(cached.accessToken);
+            }
+            const refreshToken = await this.credentials.get(this.profile);
+            if (!refreshToken)
+                throw new Error('尚未登录，请先运行 ai-short-studio auth login');
+            this.current = await this.provider.refresh(refreshToken);
+            if (this.current.refreshToken !== refreshToken) {
+                await this.credentials.set(this.profile, this.current.refreshToken);
+            }
+            await this.cache?.set(this.profile, this.current);
+            return this.remember(this.current.accessToken);
+        };
+        return this.cache ? this.cache.withRefreshLock(this.profile, action) : action();
+    }
+    remember(accessToken) {
+        this.lastReturnedAccessToken = accessToken;
+        return accessToken;
     }
 }
+function isFresh(session) {
+    return session.expiresAt > Date.now() + 60_000;
+}

package/dist/command-helpers.d.ts

@@ -8,3 +8,4 @@ export declare function commandApi(flags: Parameters<typeof createRuntime>[0]):
     client: import("./client/api-client.js").ApiClient;
 }>;
 export declare function readJsonInput(file?: string): Promise<Record<string, unknown>>;
+export declare function mapConcurrent<T, R>(values: T[], concurrency: number, transform: (value: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/command-helpers.js

@@ -14,6 +14,18 @@ export async function readJsonInput(file) {
         throw new Error('输入必须是 JSON 对象');
     return value;
 }
+export async function mapConcurrent(values, concurrency, transform) {
+    const results = new Array(values.length);
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(Math.max(1, concurrency), values.length) }, async () => {
+        while (cursor < values.length) {
+            const index = cursor++;
+            results[index] = await transform(values[index], index);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
 async function readStdin() {
     if (process.stdin.isTTY)
         throw new Error('请使用 --file 或通过 stdin 传入 JSON');

package/dist/commands/canvas/apply.d.ts

@@ -3,6 +3,8 @@ export default class CanvasApply extends BaseCommand {
     static flags: {
         project: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'canvas-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'expected-version': import("@oclif/core/interfaces").OptionFlag<number | 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>;

package/dist/commands/canvas/apply.js

@@ -2,6 +2,24 @@ import { Flags } from '@oclif/core';
 import { BaseCommand } from '../../base-command.js';
 import { commandApi, projectFlag, readJsonInput } from '../../command-helpers.js';
 export default class CanvasApply extends BaseCommand {
-    static flags = { ...BaseCommand.baseFlags, project: projectFlag, file: Flags.string({ description: 'patch JSON 文件；省略时读取 stdin' }) };
-    async run() { const { flags } = await this.parse(CanvasApply); const { api } = await commandApi(flags); const canvas = await api.canvas(flags.project); this.print(await api.patchCanvas(flags.project, { ...(await readJsonInput(flags.file)), canvasId: canvas.id, expectedVersion: canvas.version })); }
+    static flags = {
+        ...BaseCommand.baseFlags,
+        project: projectFlag,
+        file: Flags.string({ description: 'patch JSON 文件；省略时读取 stdin' }),
+        'canvas-id': Flags.string({ description: '已知画布 ID；与 expected-version 同时提供时跳过预读' }),
+        'expected-version': Flags.integer({ description: '最近一次读取的画布版本；与 canvas-id 同时提供时跳过预读' }),
+    };
+    async run() {
+        const { flags } = await this.parse(CanvasApply);
+        const { api } = await commandApi(flags);
+        const input = await readJsonInput(flags.file);
+        const canvasId = flags['canvas-id'] ?? (typeof input.canvasId === 'string' ? input.canvasId : undefined);
+        const expectedVersion = flags['expected-version'] ?? (typeof input.expectedVersion === 'number' ? input.expectedVersion : undefined);
+        const canvas = canvasId && expectedVersion !== undefined ? null : await api.canvas(flags.project);
+        this.print(await api.patchCanvas(flags.project, {
+            ...input,
+            canvasId: canvasId ?? canvas.id,
+            expectedVersion: expectedVersion ?? canvas.version,
+        }));
+    }
 }

package/dist/commands/canvas/inspect.d.ts

@@ -0,0 +1,19 @@
+import { BaseCommand } from '../../base-command.js';
+export default class CanvasInspect extends BaseCommand {
+    static description: string;
+    static flags: {
+        project: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        include: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        kind: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        status: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        search: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        operation: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'resource-type': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'producer-node': 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>;
+}

package/dist/commands/canvas/inspect.js

@@ -0,0 +1,36 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base-command.js';
+import { commandApi, projectFlag } from '../../command-helpers.js';
+const includeOptions = ['summary', 'nodes', 'edges', 'assets', 'settings', 'node-types'];
+export default class CanvasInspect extends BaseCommand {
+    static description = '一次读取并筛选画布节点、连线、资产、设置与节点目录';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        project: projectFlag,
+        include: Flags.string({
+            description: '返回内容，可重复指定',
+            multiple: true,
+            options: [...includeOptions],
+            default: ['summary', 'nodes', 'edges'],
+        }),
+        kind: Flags.string({ description: '节点 kind，可重复指定', multiple: true }),
+        status: Flags.string({ description: '节点状态，可重复指定', multiple: true }),
+        search: Flags.string({ description: '按节点 ID、标题、资源名称或 resourceKey 搜索' }),
+        operation: Flags.string({ description: '按 artifact.operation 筛选' }),
+        'resource-type': Flags.string({ description: '按 artifact.resourceType 筛选' }),
+        'producer-node': Flags.string({ description: '按 artifact.producerNodeId 筛选' }),
+    };
+    async run() {
+        const { flags } = await this.parse(CanvasInspect);
+        const { api } = await commandApi(flags);
+        this.print(await api.inspectCanvas(flags.project, {
+            includes: flags.include,
+            kinds: flags.kind,
+            statuses: flags.status,
+            search: flags.search,
+            operation: flags.operation,
+            resourceType: flags['resource-type'],
+            producerNodeId: flags['producer-node'],
+        }));
+    }
+}

package/dist/commands/canvas/node/run.d.ts

@@ -1,10 +1,12 @@
 import { BaseCommand } from '../../../base-command.js';
 export default class CanvasNodeRun extends BaseCommand {
     static args: {
-        nodeId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        nodeId: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static flags: {
         project: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        node: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        concurrency: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         wait: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         interval: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/canvas/node/run.js

@@ -1,11 +1,37 @@
 import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../../../base-command.js';
-import { commandApi, projectFlag } from '../../../command-helpers.js';
+import { commandApi, mapConcurrent, projectFlag } from '../../../command-helpers.js';
 export default class CanvasNodeRun extends BaseCommand {
-    static args = { nodeId: Args.string({ required: true }) };
-    static flags = { ...BaseCommand.baseFlags, project: projectFlag, wait: Flags.boolean({ default: false }), interval: Flags.integer({ default: 1000 }) };
-    async run() { const { args, flags } = await this.parse(CanvasNodeRun); const { api } = await commandApi(flags); const submitted = await api.runNode(flags.project, args.nodeId); if (flags.wait && submitted.task?.id)
-        this.print(await api.waitTask(submitted.task.id, flags.interval));
-    else
-        this.print(submitted); }
+    static args = { nodeId: Args.string({ required: false }) };
+    static flags = {
+        ...BaseCommand.baseFlags,
+        project: projectFlag,
+        node: Flags.string({ description: '节点 ID，可重复指定以批量运行', multiple: true }),
+        concurrency: Flags.integer({ description: '批量提交并发数', default: 4, min: 1, max: 16 }),
+        wait: Flags.boolean({ default: false }),
+        interval: Flags.integer({ default: 1000 }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(CanvasNodeRun);
+        const nodeIds = [...new Set([...(args.nodeId ? [args.nodeId] : []), ...(flags.node ?? [])])];
+        if (!nodeIds.length)
+            throw new Error('请提供 nodeId 或至少一个 --node');
+        const { api } = await commandApi(flags);
+        const submissions = await mapConcurrent(nodeIds, flags.concurrency, async (nodeId) => ({
+            nodeId,
+            result: await api.runNode(flags.project, nodeId),
+        }));
+        if (!flags.wait) {
+            this.print(nodeIds.length === 1 ? submissions[0].result : { submissions });
+            return;
+        }
+        const tasks = submissions.filter((item) => item.result.task?.id);
+        const completed = await mapConcurrent(tasks, flags.concurrency, async (item) => ({
+            nodeId: item.nodeId,
+            task: await api.waitTask(item.result.task.id, flags.interval),
+        }));
+        this.print(nodeIds.length === 1 ? completed[0]?.task ?? submissions[0].result : { submissions, tasks: completed });
+        if (completed.some((item) => item.task.status !== 'completed'))
+            this.error('部分任务未成功完成', { exit: 8 });
+    }
 }

package/dist/commands/canvas/node/update-many.d.ts

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

package/dist/commands/canvas/node/update-many.js

@@ -0,0 +1,48 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../../base-command.js';
+import { commandApi, projectFlag, readJsonInput } from '../../../command-helpers.js';
+export default class CanvasNodeUpdateMany extends BaseCommand {
+    static description = '一次读取 schema 并原子更新多个节点字段';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        project: projectFlag,
+        file: Flags.string({ description: '包含 updates 数组的 JSON 文件；省略时读取 stdin' }),
+    };
+    async run() {
+        const { flags } = await this.parse(CanvasNodeUpdateMany);
+        const input = await readJsonInput(flags.file);
+        if (!Array.isArray(input.updates))
+            throw new Error('输入必须包含 updates 数组');
+        const updates = input.updates.map(readUpdate);
+        const { api } = await commandApi(flags);
+        this.print(await api.updateNodes(flags.project, updates));
+    }
+}
+function readUpdate(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('updates 每一项必须是对象');
+    const update = value;
+    if (typeof update.nodeId !== 'string' || !update.nodeId)
+        throw new Error('updates.nodeId 不能为空');
+    if (update.set !== undefined && (!update.set || typeof update.set !== 'object' || Array.isArray(update.set))) {
+        throw new Error(`节点 ${update.nodeId} 的 set 必须是对象`);
+    }
+    if (update.unset !== undefined && (!Array.isArray(update.unset) || update.unset.some((field) => typeof field !== 'string'))) {
+        throw new Error(`节点 ${update.nodeId} 的 unset 必须是字符串数组`);
+    }
+    for (const coordinate of ['x', 'y']) {
+        if (update[coordinate] !== undefined && (typeof update[coordinate] !== 'number' || !Number.isFinite(update[coordinate]))) {
+            throw new Error(`节点 ${update.nodeId} 的 ${coordinate} 必须是数字`);
+        }
+    }
+    if (update.title !== undefined && typeof update.title !== 'string')
+        throw new Error(`节点 ${update.nodeId} 的 title 必须是字符串`);
+    return {
+        nodeId: update.nodeId,
+        set: update.set,
+        unset: update.unset,
+        title: update.title,
+        x: update.x,
+        y: update.y,
+    };
+}

package/dist/commands/canvas/node/update.d.ts

@@ -6,6 +6,11 @@ export default class CanvasNodeUpdate extends BaseCommand {
     static flags: {
         project: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        set: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        unset: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        title: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        x: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        y: import("@oclif/core/interfaces").OptionFlag<number | 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>;