svmc-cli 1.0.0 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # svmc-cli
 
-将 `media-center-frontend` 的图生图能力封装为可供 Agent 调用的命令行工具。
+将 `media-center-frontend` 的图像/视频生成能力封装为可供 Agent 调用的命令行工具。
 
 ## 安装与构建
 
@@ -34,25 +34,25 @@ svmc auth status
 ## 获取参数规格
 
 ```bash
-svmc image specs --provider nano-banana
+svmc img2img specs --provider nano-banana
 ```
 
 需要显式传 Cookie 时：
 
 ```bash
-svmc image specs --provider nano-banana --cookie "session=...; sl-session=..."
+svmc img2img specs --provider nano-banana --cookie "session=...; sl-session=..."
 ```
 
 仅列出 provider 列表：
 
 ```bash
-svmc image specs
+svmc img2img specs
 ```
 
 ## 发起图生图任务
 
 ```bash
-svmc image generate \
+svmc img2img generate \
   --provider nano-banana \
   --input "img1.jpg" \
   --input "img2.png" \
@@ -63,7 +63,7 @@ svmc image generate \
 支持传递动态参数（会原样透传给后端）：
 
 ```bash
-svmc image generate ... --steps 20 --guidance_scale 7 --cookie "session=...; sl-session=..."
+svmc img2img generate ... --steps 20 --guidance_scale 7 --cookie "session=...; sl-session=..."
 ```
 
 任务轮询间隔固定 5 秒，完成后输出：
@@ -73,11 +73,38 @@ IMAGE_SAVED: /abs/path/to/file.jpg
 MEDIA:/abs/path/to/file.jpg
 ```
 
+## 其他任务命令
+
+以下模块都遵循相同流程：动态获取 `params`、按 provider 规格校验参数、提交任务并轮询 `get_task`、下载结果。
+
+- 修图：`svmc editImage specs` / `svmc editImage generate`
+- 文生图：`svmc text2img specs` / `svmc text2img generate`
+- 图生视频：`svmc img2video specs` / `svmc img2video generate`
+- 文生视频：`svmc text2video specs` / `svmc text2video generate`
+
+示例（修图）：
+
+```bash
+svmc editImage generate \
+  --provider nano-banana \
+  --input "origin.jpg" \
+  --prompt "remove watermark"
+```
+
+示例（文生视频）：
+
+```bash
+svmc text2video generate \
+  --provider kling \
+  --prompt "a panda dancing in snowfall" \
+  --ratio "16:9"
+```
+
 ## 端到端验收脚本
 
 1. `svmc auth`，写入 token。
-2. `svmc image specs --provider <provider>`，确认返回规格。
-3. `svmc image generate --provider <provider> --input <img> --prompt "..."`。
+2. `svmc img2img specs --provider <provider>`，确认返回规格。
+3. `svmc img2img generate --provider <provider> --input <img> --prompt "..."`。
 4. 观察输出包含 `IMAGE_SAVED` 和 `MEDIA`，并确认本地文件存在。
 
 ## 质量命令
@@ -87,3 +114,57 @@ npm run lint:eslint
 npm run type-check
 npm test
 ```
+
+## npm 发布流程
+
+发布前建议先确认当前 npm 登录账号：
+
+```bash
+npm whoami
+```
+
+### 1) 发布前检查
+
+```bash
+npm install
+npm run lint:eslint
+npm run type-check
+npm test
+npm run build
+```
+
+### 2) 更新版本号
+
+按语义化版本选择其一：
+
+```bash
+npm version patch
+# 或 npm version minor
+# 或 npm version major
+```
+
+### 3) 执行发布
+
+```bash
+npm publish
+```
+
+如果是首次发布非 scoped 包，使用：
+
+```bash
+npm publish --access public
+```
+
+### 4) 发布后验证
+
+```bash
+npm view svmc-cli version
+npm view svmc-cli dist-tags
+```
+
+如需快速验证安装：
+
+```bash
+npm i -g svmc-cli@latest
+svmc --version
+```

package/dist/src/commands/generation.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runModuleSpecsCommand = runModuleSpecsCommand;
+exports.runModuleGenerateCommand = runModuleGenerateCommand;
+const node_path_1 = require("node:path");
+const apiClient_1 = require("../core/apiClient");
+const config_1 = require("../core/config");
+const downloader_1 = require("../core/downloader");
+const errors_1 = require("../core/errors");
+const parser_1 = require("../core/parser");
+const poller_1 = require("../core/poller");
+async function runModuleSpecsCommand(meta, options) {
+    const token = await (0, config_1.getAccessToken)(options.configPath);
+    const baseUrl = await (0, config_1.getBaseUrl)(options.baseUrl, options.configPath);
+    const cookie = await (0, config_1.getSessionCookie)(options.cookie, options.configPath);
+    const client = new apiClient_1.ApiClient(baseUrl, token, cookie);
+    const params = await client.get(`/${meta.moduleRoot}/params`);
+    const moduleConfig = readModuleConfig(params, meta);
+    const suppliers = moduleConfig.for_supplier ?? {};
+    if (!options.provider) {
+        process.stdout.write(`${JSON.stringify({ providers: Object.keys(suppliers) }, null, 2)}\n`);
+        return;
+    }
+    const providerSpec = suppliers[options.provider];
+    if (!providerSpec) {
+        throw new errors_1.CliError(`${meta.displayName} 未找到 provider: ${options.provider}`, errors_1.EXIT_CODES.USAGE);
+    }
+    process.stdout.write(`${JSON.stringify({ module: meta.commandName, provider: options.provider, spec: providerSpec }, null, 2)}\n`);
+}
+async function runModuleGenerateCommand(meta, options) {
+    const parsed = (0, parser_1.parseGenerateCliArgs)(options.rawArgs, {
+        requireInput: meta.requireInput,
+    });
+    await (0, parser_1.ensureInputsReadable)(parsed.input);
+    const token = await (0, config_1.getAccessToken)(options.configPath);
+    const baseUrl = await (0, config_1.getBaseUrl)(parsed.baseUrl, options.configPath);
+    const cookie = await (0, config_1.getSessionCookie)(parsed.cookie, options.configPath);
+    const client = new apiClient_1.ApiClient(baseUrl, token, cookie);
+    const params = await client.get(`/${meta.moduleRoot}/params`);
+    const moduleConfig = readModuleConfig(params, meta);
+    const providerSpec = readProviderSpec(moduleConfig, parsed.provider, meta.displayName);
+    const submitPayload = {
+        supplier: parsed.provider,
+        ...parsed.dynamicParams,
+    };
+    if (parsed.input.length > 0) {
+        const imageData = await (0, parser_1.readImagesAsDataUrls)(parsed.input);
+        submitPayload.image = imageData;
+    }
+    if (parsed.prompt) {
+        submitPayload.prompt = parsed.prompt;
+    }
+    if (parsed.ratio) {
+        submitPayload.ratio = parsed.ratio;
+    }
+    validatePayloadBySpec(providerSpec, submitPayload);
+    if (parsed.verbose) {
+        process.stdout.write(`[generate] module=${meta.commandName} provider=${parsed.provider} inputs=${parsed.input.length}\n`);
+    }
+    const submittedTask = await client.post(meta.submitPath, submitPayload);
+    const taskUuid = submittedTask.task_uuid;
+    if (!taskUuid) {
+        throw new errors_1.CliError("提交成功但未返回 task_uuid。", errors_1.EXIT_CODES.API);
+    }
+    process.stdout.write(`TASK_UUID: ${taskUuid}\n`);
+    const completedTask = await (0, poller_1.pollTaskUntilDone)(() => client.get(`/${meta.moduleRoot}/get_task?task_uuid=${taskUuid}`), {
+        intervalMs: 5000,
+        timeoutMs: parsed.timeoutSec * 1000,
+        verbose: parsed.verbose,
+    });
+    const results = completedTask.results ?? [];
+    if (results.length === 0) {
+        throw new errors_1.CliError(`任务已完成，但未返回任何${meta.outputKind === "IMAGE" ? "图片" : "视频"}结果。`, errors_1.EXIT_CODES.TASK_FAILED);
+    }
+    const outputDir = parsed.outputDir ? (0, node_path_1.join)(process.cwd(), parsed.outputDir) : process.cwd();
+    for (let index = 0; index < results.length; index += 1) {
+        const item = results[index];
+        if (!item.result_url) {
+            continue;
+        }
+        const name = `${meta.outputPrefix}_${taskUuid}_${Date.now()}_${index + 1}.${item.format || (meta.outputKind === "VIDEO" ? "mp4" : "jpg")}`;
+        const localPath = await (0, downloader_1.downloadToLocal)(item.result_url, outputDir, name);
+        process.stdout.write(`${meta.outputKind}_SAVED: ${localPath}\n`);
+        process.stdout.write(`MEDIA:${localPath}\n`);
+    }
+}
+function readModuleConfig(params, meta) {
+    const moduleConfig = params[meta.paramsKey];
+    if (!moduleConfig || typeof moduleConfig !== "object") {
+        throw new errors_1.CliError(`${meta.displayName} 参数配置不存在，请检查接口 /${meta.moduleRoot}/params`, errors_1.EXIT_CODES.API);
+    }
+    return moduleConfig;
+}
+function readProviderSpec(moduleConfig, provider, displayName) {
+    const providerSpec = moduleConfig.for_supplier?.[provider];
+    if (!providerSpec) {
+        throw new errors_1.CliError(`${displayName} 未找到 provider: ${provider}`, errors_1.EXIT_CODES.USAGE);
+    }
+    if (!providerSpec.properties || !Array.isArray(providerSpec.required)) {
+        throw new errors_1.CliError(`${displayName} provider=${provider} 规格格式不合法，缺少 properties/required`, errors_1.EXIT_CODES.API);
+    }
+    return providerSpec;
+}
+function validatePayloadBySpec(spec, payload) {
+    const properties = spec.properties ?? {};
+    for (const requiredKey of spec.required) {
+        const value = payload[requiredKey];
+        if (isMissingValue(value)) {
+            throw new errors_1.CliError(`缺少必填参数: --${requiredKey}`, errors_1.EXIT_CODES.USAGE);
+        }
+    }
+    for (const [key, value] of Object.entries(payload)) {
+        if (key === "supplier" || value === undefined) {
+            continue;
+        }
+        const schema = properties[key];
+        if (!schema) {
+            throw new errors_1.CliError(`参数 --${key} 不在 provider 规格中，请先执行 specs 查看可用参数。`, errors_1.EXIT_CODES.USAGE);
+        }
+        if (!isValueConformingSchema(value, schema)) {
+            const expectedType = readExpectedTypeText(schema);
+            throw new errors_1.CliError(`参数 --${key} 类型不匹配，期望 ${expectedType}`, errors_1.EXIT_CODES.USAGE);
+        }
+    }
+}
+function isMissingValue(value) {
+    if (value === undefined || value === null) {
+        return true;
+    }
+    if (typeof value === "string") {
+        return value.trim().length === 0;
+    }
+    if (Array.isArray(value)) {
+        return value.length === 0;
+    }
+    return false;
+}
+function isValueConformingSchema(value, schema) {
+    if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) {
+        return schema.anyOf.some((item) => isValueMatchingType(value, item.type));
+    }
+    if (typeof schema.type === "string") {
+        return isValueMatchingType(value, schema.type);
+    }
+    return true;
+}
+function isValueMatchingType(value, schemaType) {
+    switch (schemaType) {
+        case "string":
+            return typeof value === "string";
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "number":
+            return typeof value === "number";
+        case "boolean":
+            return typeof value === "boolean";
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return typeof value === "object" && value !== null && !Array.isArray(value);
+        default:
+            return true;
+    }
+}
+function readExpectedTypeText(schema) {
+    if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) {
+        return schema.anyOf.map((item) => item.type).join(" | ");
+    }
+    return typeof schema.type === "string" ? schema.type : "任意类型";
+}

package/dist/src/core/parser.js

@@ -9,7 +9,7 @@ exports.readImagesAsDataUrls = readImagesAsDataUrls;
 const promises_1 = require("node:fs/promises");
 const yargs_parser_1 = __importDefault(require("yargs-parser"));
 const errors_1 = require("./errors");
-function parseGenerateCliArgs(rawArgs) {
+function parseGenerateCliArgs(rawArgs, options) {
     const parsed = (0, yargs_parser_1.default)(rawArgs, {
         array: ["input"],
         string: ["provider", "prompt", "ratio", "output-dir", "base-url", "cookie", "config-path"],
@@ -28,7 +28,7 @@ function parseGenerateCliArgs(rawArgs) {
         throw new errors_1.CliError("缺少 `--provider` 参数。", errors_1.EXIT_CODES.USAGE);
     }
     const input = toStringArray(parsed.input);
-    if (input.length === 0) {
+    if (options.requireInput && input.length === 0) {
         throw new errors_1.CliError("至少传入一个 `--input` 图片路径。", errors_1.EXIT_CODES.USAGE);
     }
     const timeoutSec = typeof parsed["timeout-sec"] === "number" ? parsed["timeout-sec"] : 600;

package/dist/src/index.js

@@ -5,7 +5,7 @@ const commander_1 = require("commander");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const auth_1 = require("./commands/auth");
-const image_1 = require("./commands/image");
+const generation_1 = require("./commands/generation");
 const errors_1 = require("./core/errors");
 async function run(argv = process.argv) {
     const program = new commander_1.Command();
@@ -32,27 +32,81 @@ async function run(argv = process.argv) {
         .action(async (options) => {
         await (0, auth_1.runAuthStatusCommand)(options);
     });
-    const image = program.command("image").description("图像相关命令");
-    image
-        .command("specs")
-        .description("获取 img2img 参数规格")
-        .option("--provider <provider>", "指定供应商，仅输出该供应商规格")
-        .option("--base-url <url>", "服务地址")
-        .option("--cookie <cookie>", "会话 Cookie，可覆盖配置")
-        .option("--config-path <path>", "指定配置文件路径")
-        .action(async (options) => (0, image_1.runImageSpecsCommand)(options));
-    image
-        .command("generate")
-        .description("提交 img2img 任务并轮询下载结果")
-        .allowUnknownOption(true)
-        .option("--config-path <path>", "指定配置文件路径")
-        .action(async (options) => {
-        const rawArgs = getRawArgsAfterToken(argv, "generate");
-        await (0, image_1.runImageGenerateCommand)({
-            rawArgs,
-            configPath: options.configPath,
+    const taskModules = [
+        {
+            commandName: "img2img",
+            displayName: "图生图",
+            moduleRoot: "image_generation",
+            paramsKey: "img2img",
+            submitPath: "/image_generation/img2img",
+            requireInput: true,
+            outputPrefix: "img2img",
+            outputKind: "IMAGE",
+        },
+        {
+            commandName: "editImage",
+            displayName: "修图",
+            moduleRoot: "image_generation",
+            paramsKey: "edit_image",
+            submitPath: "/image_generation/edit_image",
+            requireInput: true,
+            outputPrefix: "edit_image",
+            outputKind: "IMAGE",
+        },
+        {
+            commandName: "text2img",
+            displayName: "文生图",
+            moduleRoot: "image_generation",
+            paramsKey: "text2img",
+            submitPath: "/image_generation/text2img",
+            requireInput: false,
+            outputPrefix: "text2img",
+            outputKind: "IMAGE",
+        },
+        {
+            commandName: "img2video",
+            displayName: "图生视频",
+            moduleRoot: "video_generation",
+            paramsKey: "img2video",
+            submitPath: "/video_generation/img2video",
+            requireInput: true,
+            outputPrefix: "img2video",
+            outputKind: "VIDEO",
+        },
+        {
+            commandName: "text2video",
+            displayName: "文生视频",
+            moduleRoot: "video_generation",
+            paramsKey: "text2video",
+            submitPath: "/video_generation/text2video",
+            requireInput: false,
+            outputPrefix: "text2video",
+            outputKind: "VIDEO",
+        },
+    ];
+    for (const meta of taskModules) {
+        const task = program.command(meta.commandName).description(`${meta.displayName}命令`);
+        task
+            .command("specs")
+            .description(`获取 ${meta.commandName} 参数规格`)
+            .option("--provider <provider>", "指定供应商，仅输出该供应商规格")
+            .option("--base-url <url>", "服务地址")
+            .option("--cookie <cookie>", "会话 Cookie，可覆盖配置")
+            .option("--config-path <path>", "指定配置文件路径")
+            .action(async (options) => (0, generation_1.runModuleSpecsCommand)(meta, options));
+        task
+            .command("generate")
+            .description(`提交 ${meta.commandName} 任务并轮询下载结果`)
+            .allowUnknownOption(true)
+            .option("--config-path <path>", "指定配置文件路径")
+            .action(async (options) => {
+            const rawArgs = getRawArgsAfterToken(argv, "generate");
+            await (0, generation_1.runModuleGenerateCommand)(meta, {
+                rawArgs,
+                configPath: options.configPath,
+            });
         });
-    });
+    }
     try {
         await program.parseAsync(argv);
     }

package/dist/tests/parser.test.js

@@ -19,7 +19,7 @@ const parser_1 = require("../src/core/parser");
             "20",
             "--negative_prompt",
             "low quality",
-        ]);
+        ], { requireInput: true });
         (0, vitest_1.expect)(args.provider).toBe("nano-banana");
         (0, vitest_1.expect)(args.input).toEqual(["a.jpg", "b.png"]);
         (0, vitest_1.expect)(args.prompt).toBe("cyberpunk");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svmc-cli",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "SVMC CLI for media-center image workflows",
   "main": "dist/src/index.js",
   "bin": {

package/src/commands/generation.ts

@@ -0,0 +1,245 @@
+import { join } from "node:path";
+import { ApiClient } from "../core/apiClient";
+import { getAccessToken, getBaseUrl, getSessionCookie } from "../core/config";
+import { downloadToLocal } from "../core/downloader";
+import { CliError, EXIT_CODES } from "../core/errors";
+import { ensureInputsReadable, parseGenerateCliArgs, readImagesAsDataUrls } from "../core/parser";
+import { pollTaskUntilDone } from "../core/poller";
+import type {
+  CommonGenerationTask,
+  ModuleParamsConfig,
+  MultiModuleParamsResponse,
+  PropertySchema,
+  SupplierSchema,
+  TaskModuleId,
+} from "../types";
+
+export interface SpecsCommandOptions {
+  provider?: string;
+  configPath?: string;
+  baseUrl?: string;
+  cookie?: string;
+}
+
+export interface GenerateCommandOptions {
+  rawArgs: string[];
+  configPath?: string;
+}
+
+export interface TaskModuleMeta {
+  commandName: TaskModuleId;
+  displayName: string;
+  moduleRoot: "image_generation" | "video_generation";
+  paramsKey: string;
+  submitPath: string;
+  requireInput: boolean;
+  outputPrefix: string;
+  outputKind: "IMAGE" | "VIDEO";
+}
+
+export async function runModuleSpecsCommand(
+  meta: TaskModuleMeta,
+  options: SpecsCommandOptions,
+): Promise<void> {
+  const token = await getAccessToken(options.configPath);
+  const baseUrl = await getBaseUrl(options.baseUrl, options.configPath);
+  const cookie = await getSessionCookie(options.cookie, options.configPath);
+  const client = new ApiClient(baseUrl, token, cookie);
+
+  const params = await client.get<MultiModuleParamsResponse>(`/${meta.moduleRoot}/params`);
+  const moduleConfig = readModuleConfig(params, meta);
+  const suppliers = moduleConfig.for_supplier ?? {};
+  if (!options.provider) {
+    process.stdout.write(`${JSON.stringify({ providers: Object.keys(suppliers) }, null, 2)}\n`);
+    return;
+  }
+
+  const providerSpec = suppliers[options.provider];
+  if (!providerSpec) {
+    throw new CliError(
+      `${meta.displayName} 未找到 provider: ${options.provider}`,
+      EXIT_CODES.USAGE,
+    );
+  }
+  process.stdout.write(
+    `${JSON.stringify({ module: meta.commandName, provider: options.provider, spec: providerSpec }, null, 2)}\n`,
+  );
+}
+
+export async function runModuleGenerateCommand(
+  meta: TaskModuleMeta,
+  options: GenerateCommandOptions,
+): Promise<void> {
+  const parsed = parseGenerateCliArgs(options.rawArgs, {
+    requireInput: meta.requireInput,
+  });
+  await ensureInputsReadable(parsed.input);
+  const token = await getAccessToken(options.configPath);
+  const baseUrl = await getBaseUrl(parsed.baseUrl, options.configPath);
+  const cookie = await getSessionCookie(parsed.cookie, options.configPath);
+  const client = new ApiClient(baseUrl, token, cookie);
+  const params = await client.get<MultiModuleParamsResponse>(`/${meta.moduleRoot}/params`);
+  const moduleConfig = readModuleConfig(params, meta);
+  const providerSpec = readProviderSpec(moduleConfig, parsed.provider, meta.displayName);
+
+  const submitPayload: Record<string, unknown> = {
+    supplier: parsed.provider,
+    ...parsed.dynamicParams,
+  };
+  if (parsed.input.length > 0) {
+    const imageData = await readImagesAsDataUrls(parsed.input);
+    submitPayload.image = imageData;
+  }
+  if (parsed.prompt) {
+    submitPayload.prompt = parsed.prompt;
+  }
+  if (parsed.ratio) {
+    submitPayload.ratio = parsed.ratio;
+  }
+
+  validatePayloadBySpec(providerSpec, submitPayload);
+
+  if (parsed.verbose) {
+    process.stdout.write(
+      `[generate] module=${meta.commandName} provider=${parsed.provider} inputs=${parsed.input.length}\n`,
+    );
+  }
+
+  const submittedTask = await client.post<CommonGenerationTask>(meta.submitPath, submitPayload);
+  const taskUuid = submittedTask.task_uuid;
+  if (!taskUuid) {
+    throw new CliError("提交成功但未返回 task_uuid。", EXIT_CODES.API);
+  }
+  process.stdout.write(`TASK_UUID: ${taskUuid}\n`);
+
+  const completedTask = await pollTaskUntilDone(
+    () => client.get<CommonGenerationTask>(`/${meta.moduleRoot}/get_task?task_uuid=${taskUuid}`),
+    {
+      intervalMs: 5000,
+      timeoutMs: parsed.timeoutSec * 1000,
+      verbose: parsed.verbose,
+    },
+  );
+
+  const results = completedTask.results ?? [];
+  if (results.length === 0) {
+    throw new CliError(`任务已完成，但未返回任何${meta.outputKind === "IMAGE" ? "图片" : "视频"}结果。`, EXIT_CODES.TASK_FAILED);
+  }
+
+  const outputDir = parsed.outputDir ? join(process.cwd(), parsed.outputDir) : process.cwd();
+  for (let index = 0; index < results.length; index += 1) {
+    const item = results[index];
+    if (!item.result_url) {
+      continue;
+    }
+    const name = `${meta.outputPrefix}_${taskUuid}_${Date.now()}_${index + 1}.${item.format || (meta.outputKind === "VIDEO" ? "mp4" : "jpg")}`;
+    const localPath = await downloadToLocal(item.result_url, outputDir, name);
+    process.stdout.write(`${meta.outputKind}_SAVED: ${localPath}\n`);
+    process.stdout.write(`MEDIA:${localPath}\n`);
+  }
+}
+
+function readModuleConfig(
+  params: MultiModuleParamsResponse,
+  meta: TaskModuleMeta,
+): ModuleParamsConfig {
+  const moduleConfig = params[meta.paramsKey];
+  if (!moduleConfig || typeof moduleConfig !== "object") {
+    throw new CliError(
+      `${meta.displayName} 参数配置不存在，请检查接口 /${meta.moduleRoot}/params`,
+      EXIT_CODES.API,
+    );
+  }
+  return moduleConfig;
+}
+
+function readProviderSpec(
+  moduleConfig: ModuleParamsConfig,
+  provider: string,
+  displayName: string,
+): SupplierSchema {
+  const providerSpec = moduleConfig.for_supplier?.[provider];
+  if (!providerSpec) {
+    throw new CliError(`${displayName} 未找到 provider: ${provider}`, EXIT_CODES.USAGE);
+  }
+  if (!providerSpec.properties || !Array.isArray(providerSpec.required)) {
+    throw new CliError(
+      `${displayName} provider=${provider} 规格格式不合法，缺少 properties/required`,
+      EXIT_CODES.API,
+    );
+  }
+  return providerSpec;
+}
+
+function validatePayloadBySpec(spec: SupplierSchema, payload: Record<string, unknown>): void {
+  const properties = spec.properties ?? {};
+  for (const requiredKey of spec.required) {
+    const value = payload[requiredKey];
+    if (isMissingValue(value)) {
+      throw new CliError(`缺少必填参数: --${requiredKey}`, EXIT_CODES.USAGE);
+    }
+  }
+
+  for (const [key, value] of Object.entries(payload)) {
+    if (key === "supplier" || value === undefined) {
+      continue;
+    }
+    const schema = properties[key];
+    if (!schema) {
+      throw new CliError(`参数 --${key} 不在 provider 规格中，请先执行 specs 查看可用参数。`, EXIT_CODES.USAGE);
+    }
+    if (!isValueConformingSchema(value, schema)) {
+      const expectedType = readExpectedTypeText(schema);
+      throw new CliError(`参数 --${key} 类型不匹配，期望 ${expectedType}`, EXIT_CODES.USAGE);
+    }
+  }
+}
+
+function isMissingValue(value: unknown): boolean {
+  if (value === undefined || value === null) {
+    return true;
+  }
+  if (typeof value === "string") {
+    return value.trim().length === 0;
+  }
+  if (Array.isArray(value)) {
+    return value.length === 0;
+  }
+  return false;
+}
+
+function isValueConformingSchema(value: unknown, schema: PropertySchema): boolean {
+  if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) {
+    return schema.anyOf.some((item) => isValueMatchingType(value, item.type));
+  }
+  if (typeof schema.type === "string") {
+    return isValueMatchingType(value, schema.type);
+  }
+  return true;
+}
+
+function isValueMatchingType(value: unknown, schemaType: string): boolean {
+  switch (schemaType) {
+    case "string":
+      return typeof value === "string";
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "number":
+      return typeof value === "number";
+    case "boolean":
+      return typeof value === "boolean";
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+    default:
+      return true;
+  }
+}
+
+function readExpectedTypeText(schema: PropertySchema): string {
+  if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) {
+    return schema.anyOf.map((item) => item.type).join(" | ");
+  }
+  return typeof schema.type === "string" ? schema.type : "任意类型";
+}

package/src/core/parser.ts

@@ -15,7 +15,14 @@ export interface GenerateCliArgs {
   dynamicParams: Record<string, string | number | boolean | string[]>;
 }
 
-export function parseGenerateCliArgs(rawArgs: string[]): GenerateCliArgs {
+export interface ParseGenerateCliArgsOptions {
+  requireInput: boolean;
+}
+
+export function parseGenerateCliArgs(
+  rawArgs: string[],
+  options: ParseGenerateCliArgsOptions,
+): GenerateCliArgs {
   const parsed = yargsParser(rawArgs, {
     array: ["input"],
     string: ["provider", "prompt", "ratio", "output-dir", "base-url", "cookie", "config-path"],
@@ -36,7 +43,7 @@ export function parseGenerateCliArgs(rawArgs: string[]): GenerateCliArgs {
   }
 
   const input = toStringArray(parsed.input);
-  if (input.length === 0) {
+  if (options.requireInput && input.length === 0) {
     throw new CliError("至少传入一个 `--input` 图片路径。", EXIT_CODES.USAGE);
   }
 

package/src/index.ts

@@ -2,7 +2,11 @@ import { Command } from "commander";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { runAuthCommand, runAuthStatusCommand } from "./commands/auth";
-import { runImageGenerateCommand, runImageSpecsCommand } from "./commands/image";
+import {
+  runModuleGenerateCommand,
+  runModuleSpecsCommand,
+  type TaskModuleMeta,
+} from "./commands/generation";
 import { CliError } from "./core/errors";
 
 export async function run(argv: string[] = process.argv): Promise<void> {
@@ -36,32 +40,87 @@ export async function run(argv: string[] = process.argv): Promise<void> {
       await runAuthStatusCommand(options);
     });
 
-  const image = program.command("image").description("图像相关命令");
+  const taskModules: TaskModuleMeta[] = [
+    {
+      commandName: "img2img",
+      displayName: "图生图",
+      moduleRoot: "image_generation",
+      paramsKey: "img2img",
+      submitPath: "/image_generation/img2img",
+      requireInput: true,
+      outputPrefix: "img2img",
+      outputKind: "IMAGE",
+    },
+    {
+      commandName: "editImage",
+      displayName: "修图",
+      moduleRoot: "image_generation",
+      paramsKey: "edit_image",
+      submitPath: "/image_generation/edit_image",
+      requireInput: true,
+      outputPrefix: "edit_image",
+      outputKind: "IMAGE",
+    },
+    {
+      commandName: "text2img",
+      displayName: "文生图",
+      moduleRoot: "image_generation",
+      paramsKey: "text2img",
+      submitPath: "/image_generation/text2img",
+      requireInput: false,
+      outputPrefix: "text2img",
+      outputKind: "IMAGE",
+    },
+    {
+      commandName: "img2video",
+      displayName: "图生视频",
+      moduleRoot: "video_generation",
+      paramsKey: "img2video",
+      submitPath: "/video_generation/img2video",
+      requireInput: true,
+      outputPrefix: "img2video",
+      outputKind: "VIDEO",
+    },
+    {
+      commandName: "text2video",
+      displayName: "文生视频",
+      moduleRoot: "video_generation",
+      paramsKey: "text2video",
+      submitPath: "/video_generation/text2video",
+      requireInput: false,
+      outputPrefix: "text2video",
+      outputKind: "VIDEO",
+    },
+  ];
 
-  image
-    .command("specs")
-    .description("获取 img2img 参数规格")
-    .option("--provider <provider>", "指定供应商，仅输出该供应商规格")
-    .option("--base-url <url>", "服务地址")
-    .option("--cookie <cookie>", "会话 Cookie，可覆盖配置")
-    .option("--config-path <path>", "指定配置文件路径")
-    .action(
-      async (options: { provider?: string; baseUrl?: string; cookie?: string; configPath?: string }) =>
-        runImageSpecsCommand(options),
-    );
+  for (const meta of taskModules) {
+    const task = program.command(meta.commandName).description(`${meta.displayName}命令`);
 
-  image
-    .command("generate")
-    .description("提交 img2img 任务并轮询下载结果")
-    .allowUnknownOption(true)
-    .option("--config-path <path>", "指定配置文件路径")
-    .action(async (options: { configPath?: string }) => {
-      const rawArgs = getRawArgsAfterToken(argv, "generate");
-      await runImageGenerateCommand({
-        rawArgs,
-        configPath: options.configPath,
+    task
+      .command("specs")
+      .description(`获取 ${meta.commandName} 参数规格`)
+      .option("--provider <provider>", "指定供应商，仅输出该供应商规格")
+      .option("--base-url <url>", "服务地址")
+      .option("--cookie <cookie>", "会话 Cookie，可覆盖配置")
+      .option("--config-path <path>", "指定配置文件路径")
+      .action(
+        async (options: { provider?: string; baseUrl?: string; cookie?: string; configPath?: string }) =>
+          runModuleSpecsCommand(meta, options),
+      );
+
+    task
+      .command("generate")
+      .description(`提交 ${meta.commandName} 任务并轮询下载结果`)
+      .allowUnknownOption(true)
+      .option("--config-path <path>", "指定配置文件路径")
+      .action(async (options: { configPath?: string }) => {
+        const rawArgs = getRawArgsAfterToken(argv, "generate");
+        await runModuleGenerateCommand(meta, {
+          rawArgs,
+          configPath: options.configPath,
+        });
       });
-    });
+  }
 
   try {
     await program.parseAsync(argv);

package/src/types/index.ts

@@ -9,7 +9,7 @@ export interface ResultItem {
   size?: number;
 }
 
-export interface ImageGenerationTask {
+export interface CommonGenerationTask {
   id?: number;
   task_uuid: string;
   status: TaskStatus;
@@ -19,16 +19,40 @@ export interface ImageGenerationTask {
   request_payload?: Record<string, unknown>;
 }
 
+export type ImageGenerationTask = CommonGenerationTask;
+
 export interface ModuleParamsConfig {
   supplier?: Record<string, unknown>;
-  for_supplier?: Record<string, Record<string, unknown>>;
+  for_supplier?: Record<string, SupplierSchema>;
+}
+
+export interface PropertySchema {
+  type?: string;
+  anyOf?: Array<{
+    type: string;
+    [key: string]: unknown;
+  }>;
+  [key: string]: unknown;
 }
 
-export interface ImageParamsResponse {
+export interface SupplierSchema {
+  type?: string;
+  properties: Record<string, PropertySchema>;
+  required: string[];
+  [key: string]: unknown;
+}
+
+export interface MultiModuleParamsResponse {
+  text2img?: ModuleParamsConfig;
   img2img?: ModuleParamsConfig;
+  edit_image?: ModuleParamsConfig;
+  text2video?: ModuleParamsConfig;
+  img2video?: ModuleParamsConfig;
   [key: string]: unknown;
 }
 
+export type TaskModuleId = "img2img" | "editImage" | "text2img" | "img2video" | "text2video";
+
 export interface RuntimeConfig {
   auth: {
     access_token: string;

package/tests/parser.test.ts

@@ -3,22 +3,25 @@ import { parseGenerateCliArgs } from "../src/core/parser";
 
 describe("parseGenerateCliArgs", () => {
   it("parses standard and dynamic options", () => {
-    const args = parseGenerateCliArgs([
-      "--provider",
-      "nano-banana",
-      "--input",
-      "a.jpg",
-      "--input",
-      "b.png",
-      "--prompt",
-      "cyberpunk",
-      "--ratio",
-      "16:9",
-      "--steps",
-      "20",
-      "--negative_prompt",
-      "low quality",
-    ]);
+    const args = parseGenerateCliArgs(
+      [
+        "--provider",
+        "nano-banana",
+        "--input",
+        "a.jpg",
+        "--input",
+        "b.png",
+        "--prompt",
+        "cyberpunk",
+        "--ratio",
+        "16:9",
+        "--steps",
+        "20",
+        "--negative_prompt",
+        "low quality",
+      ],
+      { requireInput: true },
+    );
 
     expect(args.provider).toBe("nano-banana");
     expect(args.input).toEqual(["a.jpg", "b.png"]);

package/src/commands/image.ts

@@ -1,104 +0,0 @@
-import { join } from "node:path";
-import { ApiClient } from "../core/apiClient";
-import { getAccessToken, getBaseUrl, getSessionCookie } from "../core/config";
-import { downloadToLocal } from "../core/downloader";
-import { CliError, EXIT_CODES } from "../core/errors";
-import { ensureInputsReadable, parseGenerateCliArgs, readImagesAsDataUrls } from "../core/parser";
-import { pollTaskUntilDone } from "../core/poller";
-import type { ImageGenerationTask, ImageParamsResponse } from "../types";
-
-export interface SpecsCommandOptions {
-  provider?: string;
-  configPath?: string;
-  baseUrl?: string;
-  cookie?: string;
-}
-
-export interface GenerateCommandOptions {
-  rawArgs: string[];
-  configPath?: string;
-}
-
-export async function runImageSpecsCommand(options: SpecsCommandOptions): Promise<void> {
-  const token = await getAccessToken(options.configPath);
-  const baseUrl = await getBaseUrl(options.baseUrl, options.configPath);
-  const cookie = await getSessionCookie(options.cookie, options.configPath);
-  const client = new ApiClient(baseUrl, token, cookie);
-
-  const params = await client.get<ImageParamsResponse>("/image_generation/params");
-  const suppliers = params.img2img?.for_supplier ?? {};
-  if (!options.provider) {
-    process.stdout.write(`${JSON.stringify({ providers: Object.keys(suppliers) }, null, 2)}\n`);
-    return;
-  }
-
-  const providerSpec = suppliers[options.provider];
-  if (!providerSpec) {
-    throw new CliError(`未找到 provider: ${options.provider}`, EXIT_CODES.USAGE);
-  }
-  process.stdout.write(
-    `${JSON.stringify({ provider: options.provider, spec: providerSpec }, null, 2)}\n`,
-  );
-}
-
-export async function runImageGenerateCommand(options: GenerateCommandOptions): Promise<void> {
-  const parsed = parseGenerateCliArgs(options.rawArgs);
-  await ensureInputsReadable(parsed.input);
-  const token = await getAccessToken(options.configPath);
-  const baseUrl = await getBaseUrl(parsed.baseUrl, options.configPath);
-  const cookie = await getSessionCookie(parsed.cookie, options.configPath);
-  const client = new ApiClient(baseUrl, token, cookie);
-  const imageData = await readImagesAsDataUrls(parsed.input);
-
-  const submitPayload: Record<string, unknown> = {
-    supplier: parsed.provider,
-    image: imageData,
-    ...parsed.dynamicParams,
-  };
-  if (parsed.prompt) {
-    submitPayload.prompt = parsed.prompt;
-  }
-  if (parsed.ratio) {
-    submitPayload.ratio = parsed.ratio;
-  }
-
-  if (parsed.verbose) {
-    process.stdout.write(`[generate] provider=${parsed.provider} images=${imageData.length}\n`);
-  }
-
-  const submittedTask = await client.post<ImageGenerationTask>(
-    "/image_generation/img2img",
-    submitPayload,
-  );
-  const taskUuid = submittedTask.task_uuid;
-  if (!taskUuid) {
-    throw new CliError("提交成功但未返回 task_uuid。", EXIT_CODES.API);
-  }
-  process.stdout.write(`TASK_UUID: ${taskUuid}\n`);
-
-  const completedTask = await pollTaskUntilDone(
-    () => client.get<ImageGenerationTask>(`/image_generation/get_task?task_uuid=${taskUuid}`),
-    {
-      intervalMs: 5000,
-      timeoutMs: parsed.timeoutSec * 1000,
-      verbose: parsed.verbose,
-    },
-  );
-
-  const results = completedTask.results ?? [];
-  if (results.length === 0) {
-    throw new CliError("任务已完成，但未返回任何图片结果。", EXIT_CODES.TASK_FAILED);
-  }
-
-  const outputDir = parsed.outputDir ? join(process.cwd(), parsed.outputDir) : process.cwd();
-  for (let index = 0; index < results.length; index += 1) {
-    const item = results[index];
-    if (!item.result_url) {
-      continue;
-    }
-    const name = `img2img_${taskUuid}_${Date.now()}_${index + 1}.${item.format || "jpg"}`;
-    const localPath = await downloadToLocal(item.result_url, outputDir, name);
-    process.stdout.write(`IMAGE_SAVED: ${localPath}\n`);
-    process.stdout.write(`MEDIA:${localPath}\n`);
-  }
-}