@mindscraft/branch-video-agent-cli 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Branch Video Agent CLI
 
-`@mindscraft/branch-video-agent-cli` 是一个可脱离当前代码仓库使用的发布版 CLI，用于通过 Bearer agent token 调用 branch-video 与 AIHub agent API。
+`@mindscraft/branch-video-agent-cli` 是一个可脱离当前代码仓库使用的发布版 CLI，用于通过 Bearer agent token 调用 branch-video、AIHub workflow 与 AI Gateway agent API。
 
 ## 安装与执行
 
@@ -34,6 +34,8 @@ branch-video-agent --help
 - `AIHUB_AGENT_TOKEN`
 - `BRANCH_VIDEO_AGENT_BASE_URL`
 
+AI Gateway 调用同样只传 `AIHUB_AGENT_TOKEN`；服务端使用该 token 记录上的独立 `AiGatewayKey`，不能复用 AIHub `projectKey`。
+
 最小调用示例：
 
 ```powershell
@@ -46,6 +48,21 @@ branch-video-agent --help
 '@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- project list
 ```
 
+AIHub 导入公共库示例：
+
+```powershell
+@'
+{
+  "global_context_str": "{\"project_title\":\"AIHub 导入项目\"}",
+  "script_body_str": "{\"project_title\":\"AIHub 导入项目\"}",
+  "result_script_str": "[]",
+  "workflow_run_id": "00000000-0000-4000-8000-000000000000"
+}
+'@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- project import-aihub
+```
+
+该命令与其他 `project` / `version` / `production` 命令一样，统一使用 `AIHUB_AGENT_TOKEN` Bearer 鉴权；服务端会兼容旧的 `X-AIHub-Import-Token` 头，但 CLI 不再单独管理第二套 token。
+
 托管互动方案提交示例：
 
 ```powershell
@@ -64,6 +81,65 @@ branch-video-agent --help
 '@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- preset upsert
 ```
 
+角色资产库查询示例：
+
+```powershell
+@'
+{
+  "query": "喵星人 科学老师 实验服",
+  "tags": ["喵星人IP", "科学"],
+  "limit": 10
+}
+'@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- character search
+```
+
+角色资产入库示例：
+
+```powershell
+@'
+{
+  "externalId": "workflow-run-123:meow_teacher",
+  "name": "喵星科学老师",
+  "description": "穿白色实验服的喵星人科学老师，适合科学实验讲解。",
+  "tags": ["喵星人IP", "科学", "老师"],
+  "referenceImages": [{ "url": "https://example.com/meow-teacher.png" }],
+  "actions": [
+    {
+      "actionKey": "speaking",
+      "mediaType": "video",
+      "url": "https://example.com/meow-teacher-speaking.mp4"
+    }
+  ]
+}
+'@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- character create
+```
+
+`character search` 只返回已经人工添加 `accepted_for_reuse` 标签的角色资产；新入库资产默认未验收，需要在角色资产库页面验收后才会被 Agent 二次复用。
+
+AI Gateway 图片生成示例：
+
+```powershell
+@'
+{
+  "model": "doubao-seedream-5-0-260128",
+  "prompt": "3D 卡通风格，穿白大褂的喵星人科学老师在实验室讲解电路"
+}
+'@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- ai-gateway image-generate -- --raw
+```
+
+AI Gateway 视频生成并等待示例：
+
+```powershell
+@'
+{
+  "model": "doubao-seedance-2-0-260128",
+  "input": {
+    "prompt": "镜头推进到实验台，卡通猫老师点亮一个小灯泡"
+  }
+}
+'@ | npm exec --yes --package=@mindscraft/branch-video-agent-cli branch-video-agent -- ai-gateway video-create -- --wait --raw
+```
+
 ## 在仓库内构建发布包
 
 从仓库根目录执行：
@@ -97,4 +173,4 @@ npm publish
 发布前请先确认两件事：
 
 1. 你在 npmjs 上拥有当前包名对应的 scope 权限；如果没有 `@nd` scope，需要先改包名，例如改成你实际拥有的 scope，或改成非 scope 包名。
-2. 如果要让中国大陆用户安装体验更稳定，建议仍以 npmjs 作为唯一发布源，再让用户通过 `npmmirror` 安装；不要把 GitHub Packages 当作主发布仓库，因为安装门槛和网络可达性都更差。
+2. 如果要让中国大陆用户安装体验更稳定，建议仍以 npmjs 作为唯一发布源，再让用户通过 `npmmirror` 安装；不要把 GitHub Packages 当作主发布仓库，因为安装门槛和网络可达性都更差。

package/dist/commands/aiGateway.d.ts

@@ -0,0 +1,2 @@
+import type { CommandHandler } from '../lib/types.js';
+export declare const aiGatewayCommands: Record<string, CommandHandler>;

package/dist/commands/aiGateway.js

@@ -0,0 +1,181 @@
+import { CliCommandError } from '../lib/errors.js';
+import { getOptionalString, getRequiredString, omitKeys, pickDefined } from '../lib/payload.js';
+const gatewaySuccessStatuses = new Set(['succeeded', 'success', 'done']);
+const gatewayPendingStatuses = new Set(['queued', 'running', 'pending', 'text_success', 'first_success']);
+function ensureObject(value, fieldName) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new CliCommandError(`${fieldName} must be a JSON object`, 'VALIDATION_ERROR');
+    }
+    return value;
+}
+function normalizeOperation(value) {
+    return value.trim().replace(/^\/+/, '');
+}
+function extractTaskId(value) {
+    const record = value && typeof value === 'object' ? value : {};
+    const candidates = [
+        record.id,
+        record.taskId,
+        record.task_id,
+        record.data?.id,
+        record.data?.taskId,
+        record.data?.task_id,
+        record.data?.response?.id,
+        record.data?.response?.taskId,
+        record.data?.response?.task_id,
+    ];
+    const taskId = candidates.find((candidate) => typeof candidate === 'string' && candidate.trim());
+    if (!taskId) {
+        throw new CliCommandError('AI Gateway response did not include a task id', 'VALIDATION_ERROR', value);
+    }
+    return String(taskId).trim();
+}
+function extractStatus(value) {
+    const record = value && typeof value === 'object' ? value : {};
+    const status = record.data?.status ?? record.data?.successFlag ?? record.status;
+    return typeof status === 'string' ? status.trim().toLowerCase() : '';
+}
+function extractFailureMessage(value) {
+    const record = value && typeof value === 'object' ? value : {};
+    return String(record.error?.message
+        || record.data?.errorMessage
+        || record.data?.error?.message
+        || record.error
+        || 'AI Gateway task failed');
+}
+async function waitForGatewayTask(context, submit, poll) {
+    const startedAt = context.runtime.now();
+    while (context.runtime.now() - startedAt <= context.flags.timeoutMs) {
+        const statusResult = await poll();
+        const status = extractStatus(statusResult.data);
+        if (gatewaySuccessStatuses.has(status)) {
+            return {
+                data: {
+                    submit,
+                    status: statusResult.data,
+                },
+                requestId: statusResult.requestId,
+            };
+        }
+        if (status && !gatewayPendingStatuses.has(status)) {
+            throw new CliCommandError(extractFailureMessage(statusResult.data), 'RUN_FAILED', { submit, status: statusResult.data }, statusResult.requestId || null);
+        }
+        await context.runtime.sleep(context.flags.pollIntervalMs);
+    }
+    throw new CliCommandError('AI Gateway wait timed out', 'TIMEOUT', { submit });
+}
+function normalizeImageEditPayload(payload) {
+    if (payload.fields || payload.files)
+        return payload;
+    const files = {};
+    if (payload.image !== undefined)
+        files.image = payload.image;
+    if (payload.mask !== undefined)
+        files.mask = payload.mask;
+    return {
+        fields: omitKeys(payload, ['image', 'mask']),
+        files,
+    };
+}
+function inferMusicQueryOperation(operation) {
+    switch (operation) {
+        case 'vocal-removal':
+            return 'vocal-removal';
+        case 'wav':
+            return 'wav';
+        case 'lyrics':
+            return 'lyrics';
+        case 'mp4':
+            return 'mp4';
+        default:
+            return 'query';
+    }
+}
+async function getMusicStatus(context, operation, id) {
+    return context.client.request(`/api/agent/ai-gateway/music/${encodeURIComponent(operation)}`, {
+        method: 'GET',
+        query: { id },
+    });
+}
+export const aiGatewayCommands = {
+    capabilities: async ({ client }) => {
+        const result = await client.request('/api/agent/ai-gateway/capabilities', {
+            method: 'GET',
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    request: async ({ client, payload }) => {
+        const path = getRequiredString(payload, 'path');
+        const method = getOptionalString(payload, 'method') || 'POST';
+        const result = await client.request('/api/agent/ai-gateway/request', {
+            method: 'POST',
+            body: {
+                method,
+                path,
+                query: payload.query === undefined ? undefined : ensureObject(payload.query, 'query'),
+                headers: payload.headers === undefined ? undefined : ensureObject(payload.headers, 'headers'),
+                body: payload.body,
+            },
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'image-generate': async ({ client, payload }) => {
+        const result = await client.request('/api/agent/ai-gateway/images/generations', {
+            method: 'POST',
+            body: payload,
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'image-edit': async ({ client, payload }) => {
+        const result = await client.request('/api/agent/ai-gateway/images/edits', {
+            method: 'POST',
+            body: normalizeImageEditPayload(payload),
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'video-create': async (context) => {
+        const result = await context.client.request('/api/agent/ai-gateway/predictions', {
+            method: 'POST',
+            body: context.payload,
+        });
+        if (!context.flags.wait) {
+            return { data: result.data, requestId: result.requestId };
+        }
+        const taskId = extractTaskId(result.data);
+        const query = pickDefined(context.payload, ['model']);
+        return waitForGatewayTask(context, result.data, () => context.client.request(`/api/agent/ai-gateway/predictions/${encodeURIComponent(taskId)}`, { method: 'GET', query }));
+    },
+    'video-get': async ({ client, payload }) => {
+        const taskId = getRequiredString(payload, 'taskId');
+        const result = await client.request(`/api/agent/ai-gateway/predictions/${encodeURIComponent(taskId)}`, {
+            method: 'GET',
+            query: pickDefined(payload, ['model']),
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    'music-submit': async (context) => {
+        const operation = normalizeOperation(getRequiredString(context.payload, 'operation'));
+        const body = context.payload.body === undefined
+            ? omitKeys(context.payload, ['operation', 'queryOperation'])
+            : ensureObject(context.payload.body, 'body');
+        const result = await context.client.request(`/api/agent/ai-gateway/music/${encodeURIComponent(operation)}`, {
+            method: 'POST',
+            body,
+        });
+        if (!context.flags.wait) {
+            return { data: result.data, requestId: result.requestId };
+        }
+        const taskId = extractTaskId(result.data);
+        const queryOperation = normalizeOperation(getOptionalString(context.payload, 'queryOperation') || inferMusicQueryOperation(operation));
+        return waitForGatewayTask(context, result.data, () => getMusicStatus(context, queryOperation, taskId));
+    },
+    'music-get': async ({ client, payload }) => {
+        const id = getRequiredString(payload, 'id');
+        const operation = normalizeOperation(getOptionalString(payload, 'operation') || 'query');
+        const result = await client.request(`/api/agent/ai-gateway/music/${encodeURIComponent(operation)}`, {
+            method: 'GET',
+            query: { id },
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+};

package/dist/commands/character.d.ts

@@ -0,0 +1,2 @@
+import type { CommandHandler } from '../lib/types.js';
+export declare const characterCommands: Record<string, CommandHandler>;

package/dist/commands/character.js

@@ -0,0 +1,48 @@
+import { getRequiredString, pickDefined } from '../lib/payload.js';
+const ACCEPTED_FOR_REUSE_TAG = 'accepted_for_reuse';
+function normalizeTags(value) {
+    const raw = Array.isArray(value)
+        ? value
+        : typeof value === 'string'
+            ? value.split(',')
+            : [];
+    return raw
+        .map((item) => String(item || '').trim())
+        .filter(Boolean)
+        .filter((item, index, list) => list.indexOf(item) === index);
+}
+function tagsForReuseSearch(value) {
+    return [...normalizeTags(value), ACCEPTED_FOR_REUSE_TAG]
+        .filter((item, index, list) => list.indexOf(item) === index);
+}
+export const characterCommands = {
+    search: async ({ client, payload }) => {
+        const tags = tagsForReuseSearch(payload.tags);
+        const result = await client.request('/api/branch-video/character-assets', {
+            method: 'GET',
+            query: {
+                ...pickDefined(payload, ['query', 'page', 'limit']),
+                tags: tags.join(','),
+            },
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    create: async ({ client, payload }) => {
+        const externalId = getRequiredString(payload, 'externalId');
+        const result = await client.request('/api/branch-video/character-assets', {
+            method: 'POST',
+            body: {
+                ...payload,
+                externalId,
+            },
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    get: async ({ client, payload }) => {
+        const id = getRequiredString(payload, 'id');
+        const result = await client.request(`/api/branch-video/character-assets/${encodeURIComponent(id)}`, {
+            method: 'GET',
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+};

package/dist/commands/project.js

@@ -21,6 +21,13 @@ export const projectCommands = {
         });
         return { data: result.data, requestId: result.requestId };
     },
+    'import-aihub': async ({ client, payload }) => {
+        const result = await client.request('/api/branch-video/import/aihub', {
+            method: 'POST',
+            body: payload,
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
     update: async ({ client, payload }) => {
         const projectId = getRequiredString(payload, 'projectId');
         const result = await client.request(`/api/branch-video/${encodeURIComponent(projectId)}`, {

package/dist/index.js

@@ -3,6 +3,8 @@ import { productionCommands } from './commands/production.js';
 import { projectCommands } from './commands/project.js';
 import { versionCommands } from './commands/version.js';
 import { workflowCommands } from './commands/workflow.js';
+import { characterCommands } from './commands/character.js';
+import { aiGatewayCommands } from './commands/aiGateway.js';
 import { CliCommandError } from './lib/errors.js';
 import { getCliHelpText, parseCliArgs, resolveCliConfig } from './lib/flags.js';
 import { CliHttpClient } from './lib/http.js';
@@ -14,6 +16,8 @@ const commandRegistry = {
     project: projectCommands,
     version: versionCommands,
     production: productionCommands,
+    character: characterCommands,
+    'ai-gateway': aiGatewayCommands,
 };
 function normalizeError(error) {
     if (error instanceof CliCommandError) {

package/dist/lib/flags.js

@@ -41,6 +41,8 @@ export function parseCliArgs(argv) {
     };
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
+        if (arg === '--')
+            continue;
         if (!arg.startsWith('--')) {
             positionals.push(arg);
             continue;
@@ -93,9 +95,11 @@ export function getCliHelpText() {
         'Groups:',
         '  preset     list | upsert',
         '  workflow   run | status | outputs',
-        '  project    list | get | create | update | delete',
+        '  project    list | get | create | import-aihub | update | delete',
         '  version    list | get | publish',
         '  production schema | start | status | retry',
+        '  character  search | create | get',
+        '  ai-gateway capabilities | request | image-generate | image-edit | video-create | video-get | music-submit | music-get',
         '',
         'Config precedence:',
         '  AIHUB_AGENT_TOKEN / BRANCH_VIDEO_AGENT_BASE_URL > stdin JSON or --token-file > command flags',

package/dist/lib/http.js

@@ -14,6 +14,7 @@ function buildUrl(baseUrl, path, query) {
 function extractRequestId(response, parsed) {
     return response.headers.get('x-request-id')
         || response.headers.get('x-correlation-id')
+        || response.headers.get('x-ai-gateway-request-id')
         || (typeof parsed?.requestId === 'string' ? parsed.requestId : null);
 }
 export class CliHttpClient {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindscraft/branch-video-agent-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Published CLI for branch-video and AIHub agent APIs.",
   "type": "module",
   "bin": {
@@ -33,4 +33,4 @@
     "prepack": "npm run build",
     "smoke:help": "npm run build && node dist/bin.js --help"
   }
-}
+}