zerocut-cli 0.3.0 → 0.3.1

package/dist/commands/image.js

@@ -21,6 +21,7 @@ function register(program) {
         "banana2",
         "banana-pro",
         "wan",
+        "wan-pro",
     ];
     const allowedAspectRatios = [
         "1:1",
@@ -46,6 +47,7 @@ function register(program) {
             aspect_ratio: aspectRatio,
             resolution,
             reference_images: referenceImages,
+            sequential_image_generation: "disabled",
             onProgress,
         };
         const res = await session.ai.generateImage(payload);

package/dist/commands/skill.js

@@ -9,16 +9,29 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 exports.name = "skill";
 exports.description = "Print built-in SKILL.md content";
+function printSkill(relativePath) {
+    const filePath = node_path_1.default.resolve(__dirname, relativePath);
+    const content = node_fs_1.default.readFileSync(filePath, "utf8");
+    process.stdout.write(content);
+    if (!content.endsWith("\n")) {
+        process.stdout.write("\n");
+    }
+}
 function register(program) {
-    program
-        .command("skill")
-        .description("Print built-in skill markdown")
+    const parent = program.command("skill").description("Print built-in skill markdown");
+    parent
+        .command("one-click-video")
+        .description("Print one-click-video skill markdown")
+        .action(() => {
+        printSkill("../skill/one-click-video/SKILL.md");
+    });
+    parent
+        .command("edit-video")
+        .description("Print edit-video skill markdown")
         .action(() => {
-        const filePath = node_path_1.default.resolve(__dirname, "../skill/SKILL.md");
-        const content = node_fs_1.default.readFileSync(filePath, "utf8");
-        process.stdout.write(content);
-        if (!content.endsWith("\n")) {
-            process.stdout.write("\n");
-        }
+        printSkill("../skill/edit-video/SKILL.md");
+    });
+    parent.action(() => {
+        printSkill("../skill/SKILL.md");
     });
 }

package/dist/commands/video.js

@@ -11,11 +11,35 @@ const node_path_1 = __importDefault(require("node:path"));
 const progress_1 = require("../utils/progress");
 exports.name = "video";
 exports.description = "Video command: create video";
+function resolveResultUrl(result) {
+    if (!result || typeof result !== "object") {
+        return undefined;
+    }
+    const record = result;
+    if (typeof record.url === "string" && record.url.length > 0) {
+        return record.url;
+    }
+    const data = record.data;
+    if (data && typeof data === "object") {
+        const dataRecord = data;
+        if (typeof dataRecord.url === "string" && dataRecord.url.length > 0) {
+            return dataRecord.url;
+        }
+    }
+    return undefined;
+}
 function register(program) {
+    const avatarModels = ["zerocut-avatar-1.0", "zerocut-avatar-1.5"];
+    const mvModels = ["zerocut-mv-1.0"];
     const parent = program.command("video").description("Create a new video; requires --prompt");
     const allowedTypes = [
         "zerocut3.0",
+        "zerocut3.0-pro",
+        "zerocut3.0-pro-fast",
+        "zerocut3.0-turbo",
         "seedance-1.5-pro",
+        "seedance-2.0",
+        "seedance-2.0-fast",
         "vidu",
         "vidu-pro",
         "viduq3",
@@ -28,6 +52,8 @@ function register(program) {
         "sora2-pro",
         "veo3.1",
         "veo3.1-pro",
+        ...avatarModels,
+        ...mvModels,
     ];
     async function videoCreateAction(opts) {
         const session = (0, cerevox_1.getSessionFromCommand)(this);
@@ -41,20 +67,30 @@ function register(program) {
             process.exitCode = 1;
             return;
         }
-        let model = typeof opts.video === "string" ? opts.video.trim() : undefined;
+        let model = typeof opts.model === "string" ? opts.model.trim() : undefined;
         if (model && !allowedTypes.includes(model)) {
-            process.stderr.write(`Invalid value for --video: ${model}. Allowed: ${allowedTypes.join("|")}\n`);
+            process.stderr.write(`Invalid value for --model: ${model}. Allowed: ${allowedTypes.join("|")}\n`);
             process.exitCode = 1;
             return;
         }
         if (!model)
             model = "vidu";
         const durationStr = typeof opts.duration === "string" ? opts.duration.trim() : undefined;
+        const sourceVideo = typeof opts.sourceVideo === "string" ? opts.sourceVideo.trim() : undefined;
         let duration = 0;
+        const durationRange = (() => {
+            if (avatarModels.includes(model)) {
+                return { min: 5, max: 240 };
+            }
+            if (mvModels.includes(model)) {
+                return { min: 1, max: 240 };
+            }
+            return { min: 1, max: 16 };
+        })();
         if (durationStr) {
             const n = Number.parseInt(durationStr, 10);
-            if (!Number.isFinite(n) || n < 1 || n > 16) {
-                process.stderr.write("Invalid value for --duration: must be integer 1-16\n");
+            if (!Number.isFinite(n) || n < durationRange.min || n > durationRange.max) {
+                process.stderr.write(`Invalid value for --duration: model ${model} supports integer ${durationRange.min}-${durationRange.max}\n`);
                 process.exitCode = 1;
                 return;
             }
@@ -68,6 +104,21 @@ function register(program) {
             return;
         }
         const aspectRatio = ar;
+        let withBGM = true;
+        if (typeof opts.withBGM === "string") {
+            const withBGMRaw = opts.withBGM.trim().toLowerCase();
+            if (withBGMRaw === "true") {
+                withBGM = true;
+            }
+            else if (withBGMRaw === "false") {
+                withBGM = false;
+            }
+            else {
+                process.stderr.write("Invalid value for --withBGM: expected true|false\n");
+                process.exitCode = 1;
+                return;
+            }
+        }
         const images = [];
         if (opts.firstFrame) {
             images.push({
@@ -81,6 +132,24 @@ function register(program) {
                 url: await (0, cerevox_1.getMaterialUri)(session, opts.lastFrame),
             });
         }
+        if (opts.storyboard) {
+            images.push({
+                type: "storyboard",
+                url: await (0, cerevox_1.getMaterialUri)(session, opts.storyboard),
+            });
+        }
+        const personList = typeof opts.persons === "string" && opts.persons.length > 0
+            ? opts.persons
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0)
+            : [];
+        for (const person of personList) {
+            images.push({
+                type: "person",
+                url: await (0, cerevox_1.getMaterialUri)(session, person),
+            });
+        }
         const refsList = typeof opts.refs === "string" && opts.refs.length > 0
             ? opts.refs
                 .split(",")
@@ -93,21 +162,33 @@ function register(program) {
                 url: await (0, cerevox_1.getMaterialUri)(session, ref),
             });
         }
-        const res = await session.ai.generateVideo({
+        const request = {
             prompt,
             model: model,
             duration: duration || undefined,
             resolution: opts.resolution,
             aspect_ratio: aspectRatio,
-            mute: !opts.withAudio,
+            mute: !(opts.withAudio ?? true),
+            bgm: withBGM,
             optimize_camera: opts.optimizeCameraMotion,
             seed: opts.seed ? Number.parseInt(opts.seed, 10) : undefined,
             images: images.length > 0 ? images : undefined,
+            videos: sourceVideo
+                ? [
+                    {
+                        type: "base",
+                        url: await (0, cerevox_1.getMaterialUri)(session, sourceVideo),
+                    },
+                ]
+                : undefined,
             onProgress: (0, progress_1.createProgressSpinner)("inferencing"),
-        });
+            timeout: 7200000,
+        };
+        const res = await session.ai.generateVideo(request);
+        const initialUrl = resolveResultUrl(res);
         try {
-            if (res?.url) {
-                const tosUrl = await (0, cerevox_1.syncToTOS)(res.url);
+            if (initialUrl) {
+                const tosUrl = await (0, cerevox_1.syncToTOS)(initialUrl);
                 if (tosUrl) {
                     res.url = tosUrl;
                 }
@@ -118,7 +199,13 @@ function register(program) {
         const output = typeof opts.output === "string" ? opts.output : undefined;
         if (output) {
             const dir = process.cwd();
-            const url = res.url;
+            const url = resolveResultUrl(res);
+            if (!url) {
+                process.stderr.write("Cannot save --output because no video URL was returned. Please retry later or run without --output to inspect raw response.\n");
+                process.exitCode = 1;
+                console.log(res);
+                return;
+            }
             const response = await fetch(url);
             const buffer = Buffer.from(await response.arrayBuffer());
             const filePath = node_path_1.default.resolve(dir, output);
@@ -133,15 +220,19 @@ function register(program) {
     // default action on `zerocut video`
     parent
         .option("--prompt <prompt>", "Text prompt for video generation (required)")
-        .option("--duration <duration>", "Video duration in seconds")
-        .option("--video <video>", `Video model: ${allowedTypes.join("|")} (default: vidu)`)
+        .option("--duration <duration>", "Video duration in seconds (default models: 1-16, avatar: 5-240, mv: 1-240)")
+        .option("--model <model>", `Video model: ${allowedTypes.join("|")} (default: vidu)`)
+        .option("--sourceVideo <video>", "Base video path/url for edit mode (requires --duration 3-10)")
         .option("--seed <seed>", "Random seed")
         .option("--firstFrame <image>", "First frame image path/url")
         .option("--lastFrame <image>", "Last frame image path/url")
+        .option("--storyboard <image>", "Storyboard image path/url")
+        .option("--persons <persons>", "Comma-separated person image paths/urls")
         .option("--refs <refs>", "Comma-separated reference image/video paths/urls")
         .option("--resolution <resolution>", "Resolution, e.g., 720p")
         .option("--aspectRatio <ratio>", "Aspect ratio: 9:16|16:9|1:1")
         .option("--withAudio", "Include audio track")
+        .option("--withBGM <withBGM>", "Include background music: true|false (default: true)")
         .option("--optimizeCameraMotion", "Optimize camera motion")
         .option("--output <file>", "Output file path")
         .action(videoCreateAction);
@@ -150,15 +241,19 @@ function register(program) {
         .command("create")
         .description("Create a new video; requires --prompt")
         .option("--prompt <prompt>", "Text prompt for video generation (required)")
-        .option("--duration <duration>", "Video duration in seconds")
-        .option("--video <video>", `Video model: ${allowedTypes.join("|")} (default: vidu)`)
+        .option("--duration <duration>", "Video duration in seconds (default models: 1-16, avatar: 5-240, mv: 1-240)")
+        .option("--model <model>", `Video model: ${allowedTypes.join("|")} (default: vidu)`)
+        .option("--sourceVideo <video>", "Base video path/url for edit mode (requires --duration 3-10)")
         .option("--seed <seed>", "Random seed")
         .option("--firstFrame <image>", "First frame image path/url")
         .option("--lastFrame <image>", "Last frame image path/url")
+        .option("--storyboard <image>", "Storyboard image path/url")
+        .option("--persons <persons>", "Comma-separated person image paths/urls")
         .option("--refs <refs>", "Comma-separated reference image/video paths/urls")
         .option("--resolution <resolution>", "Resolution, e.g., 720p")
         .option("--aspectRatio <ratio>", "Aspect ratio: 9:16|16:9|1:1")
         .option("--withAudio", "Include audio track")
+        .option("--withBGM <withBGM>", "Include background music: true|false (default: true)")
         .option("--optimizeCameraMotion", "Optimize camera motion")
         .option("--output <file>", "Output file path")
         .action(videoCreateAction);

package/dist/services/config.js

@@ -207,7 +207,11 @@ function applyConfigInterceptor(program) {
         const current = (actionCommand ?? thisCommand);
         const name = current?.name?.();
         const parentName = current?.parent?.name?.();
-        if (name === "help" || name === "skill" || name === "config" || parentName === "config")
+        if (name === "help" ||
+            name === "skill" ||
+            name === "config" ||
+            parentName === "config" ||
+            parentName === "skill")
             return;
         const ok = await ensureConfig();
         if (!ok) {
@@ -221,7 +225,8 @@ function applyConfigInterceptor(program) {
     });
     program.hook("postAction", async (thisCommand, actionCommand) => {
         const name = actionCommand?.name?.() ?? thisCommand?.name?.();
-        if (name === "help" || name === "skill")
+        const parentName = actionCommand?.parent?.name?.() ?? thisCommand?.parent?.name?.();
+        if (name === "help" || name === "skill" || parentName === "skill")
             return;
         try {
             const cmd = (actionCommand ?? thisCommand);

package/dist/skill/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: "zerocut-cli-tools"
 description: "Use ZeroCut CLI media and document tools. Invoke when user needs generate media, run ffmpeg/pandoc, sync resources, or save outputs."
+homepage: "https://github.com/liubei-ai/zerocut-cli"
+source: "https://github.com/liubei-ai/zerocut-cli"
+requires_binaries:
+  - "zerocut-cli"
+  - "npx"
 ---
 
 # ZeroCut CLI Tools
@@ -8,6 +13,7 @@ description: "Use ZeroCut CLI media and document tools. Invoke when user needs g
 ## Purpose
 
 This skill provides a single reference for using ZeroCut CLI commands:
+
 - image generation
 - video generation
 - music generation
@@ -18,24 +24,89 @@ This skill provides a single reference for using ZeroCut CLI commands:
 ## When To Invoke
 
 Invoke this skill when the user asks to:
+
 - generate image, video, music, or speech audio
 - run ffmpeg or ffprobe command in sandbox
 - run pandoc conversion in sandbox
 - sync local/remote resources into sandbox
 - save generated results to local output files
 
+## Runtime Requirements
+
+- Runtime expects `zerocut-cli` to be available in current environment.
+- If `zerocut-cli` is unavailable, use one of:
+  - `pnpm dlx zerocut-cli help`
+  - `pnpm add -g zerocut-cli && zerocut-cli help`
+  - `npx zerocut-cli help`
+- This skill is instruction-only and relies on the installed CLI binary for actual enforcement.
+
+## Safety Boundaries
+
+- Only sync files or URLs that user explicitly requests for the current task.
+- Never auto-discover, crawl, or fetch unrelated remote URLs.
+- Treat remote resources as untrusted input and pass through CLI validation.
+- Never sync secrets, key files, token files, or unrelated private directories.
+- Keep all output writes in user-requested path or current working directory naming rules.
+- Do not bypass CLI command guards; ffmpeg/pandoc restrictions are enforced by the CLI implementation.
+
+## Credentials And Data Transfer
+
+- Required credential is `apiKey` in local ZeroCut config.
+- If `apiKey` is missing, stop immediately and request OTT token exchange.
+- `TOS` in this document means object storage used by ZeroCut backend for media URLs.
+- No extra credential beyond ZeroCut config is required for normal media sync/download flows.
+- Do not send data to any external service other than endpoints used by configured ZeroCut session.
+
+## Required Pre-Check
+
+Before every task, the agent must check configuration first:
+
+```bash
+npx zerocut-cli config list
+```
+
+If `apiKey` is missing or empty, the agent must immediately stop task execution and request an OTT token from the user. Do not continue any generation, conversion, or sandbox command until configuration is completed.
+
+Required user action:
+
+```bash
+npx zerocut-cli config --ott <token> --region <cn|us>
+```
+
+Notes:
+
+- `region` must be `cn` or `us`
+- OTT exchange writes `apiKey` and `region` into config
+- when running `config key` without direct key, region must be `cn|us` and OTT is required
+
 ## Command Reference
 
+### skill
+
+Use `skill` command to fetch built-in skill markdown:
+
+```bash
+npx zerocut-cli skill
+npx zerocut-cli skill one-click-video
+npx zerocut-cli skill edit-video
+```
+
+Routing rules:
+
+- When user requests one-click video creation, run `npx zerocut-cli skill one-click-video` to get the sub-skill and execute.
+- When user requests video editing, run `npx zerocut-cli skill edit-video` to get the sub-skill and execute.
+
 ### image
 
 Default action: `create`
 
 ```bash
-zerocut image --prompt "a cat on a bike" --output out.png
-zerocut image create --prompt "a cat on a bike" --model seedream-5l --aspectRatio 1:1 --resolution 1K --refs ref1.png,ref2.jpg --output out.png
+npx zerocut-cli image --prompt "a cat on a bike" --output out.png
+npx zerocut-cli image create --prompt "a cat on a bike" --model seedream-5l --aspectRatio 1:1 --resolution 1K --refs ref1.png,ref2.jpg --output out.png
 ```
 
 Options:
+
 - `--prompt <prompt>` required
 - `--model <model>`
 - `--aspectRatio <ratio>`
@@ -43,91 +114,155 @@ Options:
 - `--refs <refs>` comma-separated local paths or URLs
 - `--output <file>` save generated file
 
+Validation rules:
+
+- `--prompt` must be non-empty
+- `--model` allowed: `seedream|seedream-pro|seedream-5l|banana|banana2|banana-pro|wan|wan-pro`
+- `--aspectRatio` allowed: `1:1|3:4|4:3|16:9|9:16|2:3|3:2|21:9|1:4|4:1|1:8|8:1`
+- unless user specifies aspect ratio, default to `16:9`
+- `--resolution` allowed: `1K|2K|4K`
+- unless user specifies resolution, default to `1K`
+
 ### video
 
 Default action: `create`
 
 ```bash
-zerocut video --prompt "city night drive" --video vidu --duration 8 --output out.mp4
-zerocut video create --prompt "city night drive" --video vidu --aspectRatio 1:1 --refs ref1.png,ref2.png --output out.mp4
+npx zerocut-cli video --prompt "city night drive" --model vidu --duration 8 --output out.mp4
+npx zerocut-cli video create --prompt "city night drive" --model vidu --aspectRatio 1:1 --refs ref1.png,ref2.png --output out.mp4
+npx zerocut-cli video --prompt "remix this clip" --model vidu --sourceVideo input.mp4 --duration 6 --output edited.mp4
 ```
 
 Options:
+
 - `--prompt <prompt>` required
-- `--video <model>`
-- `--duration <seconds>`
+- `--model <model>`
+- `--duration <seconds>` model-dependent integer
+- `--sourceVideo <video>` base video for edit mode
 - `--seed <seed>`
 - `--firstFrame <image>`
 - `--lastFrame <image>`
+- `--storyboard <image>`
+- `--persons <persons>`
 - `--refs <assets>`
 - `--resolution <resolution>`
 - `--aspectRatio <ratio>`
 - `--withAudio`
+- `--withBGM <withBGM>`
 - `--optimizeCameraMotion`
 - `--output <file>`
 
+Validation rules:
+
+- `--prompt` must be non-empty
+- `--model` allowed: `zerocut3.0|zerocut3.0-pro|zerocut3.0-pro-fast|zerocut3.0-turbo|seedance-1.5-pro|seedance-2.0|seedance-2.0-fast|vidu|vidu-pro|viduq3|viduq3-turbo|kling|kling-v3|wan|wan-flash|sora2|sora2-pro|veo3.1|veo3.1-pro|zerocut-avatar-1.0|zerocut-avatar-1.5|zerocut-mv-1.0`
+- `--duration` must follow model range:
+  - default models: `1-16`
+  - `zerocut-avatar-1.0` / `zerocut-avatar-1.5`: `5-240`
+  - `zerocut-mv-1.0`: `1-240`
+- `--aspectRatio` allowed: `9:16|16:9|1:1`
+- unless user specifies aspect ratio, default to `16:9`
+- unless user specifies resolution, default to `720p`
+- `--withBGM` allowed: `true|false`, default to `true`
+
+Long video guidance:
+
+- for default models, if required duration is over 16s, split into multiple generations (each 1-16s)
+- then concatenate clips with ffmpeg
+- example:
+
+```bash
+printf "file 'part1.mp4'\nfile 'part2.mp4'\nfile 'part3.mp4'\n" > concat.txt
+npx zerocut-cli ffmpeg --args -f concat -safe 0 -i concat.txt -c copy final.mp4 --resources concat.txt part1.mp4 part2.mp4 part3.mp4
+```
+
 ### music
 
 Default action: `create`
 
 ```bash
-zerocut music --prompt "lofi beat" --output music.mp3
-zerocut music create --prompt "lofi beat" --output music.mp3
+npx zerocut-cli music --prompt "lofi beat" --output music.mp3
+npx zerocut-cli music create --prompt "lofi beat" --output music.mp3
 ```
 
 Options:
+
 - `--prompt <prompt>` required
 - `--output <file>`
 
+Validation rules:
+
+- `--prompt` must be non-empty
+
 ### tts
 
 Default action: `create`
 
 ```bash
-zerocut tts --text "你好，欢迎使用 ZeroCut" --voiceId voice_xxx --output speech.mp3
-zerocut tts create --prompt "calm tone" --text "Hello world" --voiceId voice_xxx --output speech.mp3
+npx zerocut-cli tts --text "你好，欢迎使用 ZeroCut" --voiceId voice_xxx --output speech.mp3
+npx zerocut-cli tts create --prompt "calm tone" --text "Hello world" --voiceId voice_xxx --output speech.mp3
 ```
 
 Options:
+
 - `--prompt <prompt>`
 - `--text <text>` required
 - `--voiceId <voiceId>`
 - `--output <file>`
 
+Validation rules:
+
+- `--text` must be non-empty
+
 ### ffmpeg
 
 ```bash
-zerocut ffmpeg --args -i input.mp4 -vn output.mp3 --resources input.mp4
-zerocut ffmpeg --args -i input.mp4 -vf scale=1280:720 output.mp4 --resources input.mp4
+npx zerocut-cli ffmpeg --args -i input.mp4 -vn output.mp3 --resources input.mp4
+npx zerocut-cli ffmpeg --args -i input.mp4 -vf scale=1280:720 output.mp4 --resources input.mp4
 ```
 
 Options:
+
 - `--args <args...>` required, arguments appended after `ffmpeg`
 - `--resources <resources...>` optional, files/URLs to sync into sandbox materials
 
 Behavior:
-- command is validated to only allow `ffmpeg` or `ffprobe`
+
+- `--args` must be provided
+- command prefix is fixed as `ffmpeg`
 - for `ffmpeg`, `-y` is auto-injected when absent
 - output file is auto-downloaded from sandbox to local current directory
 
 ### pandoc
 
 ```bash
-zerocut pandoc --args input.md -o output.pdf --resources input.md
-zerocut pandoc --args input.md --output=output.docx --resources input.md template.docx
+npx zerocut-cli pandoc --args input.md -o output.pdf --resources input.md
+npx zerocut-cli pandoc --args input.md --output=output.docx --resources input.md template.docx
 ```
 
 Options:
+
 - `--args <args...>` required, arguments appended after `pandoc`
 - `--resources <resources...>` optional, files/URLs to sync into sandbox materials
 
 Behavior:
-- command is validated to only allow `pandoc`
-- output file must be specified in args with `-o`, `--output`, or `--output=...`
-- output file is auto-downloaded from sandbox to local current directory
+
+- `--args` must be provided
+- command prefix is fixed as `pandoc`
+- output file is auto-downloaded only when args include `-o`, `--output`, or `--output=...`
 
 ## Output And Sync Rules
 
 - Media URLs from generation are synced to TOS when available.
 - `--output` saves files to an absolute path resolved from current working directory.
 - Missing parent directories for `--output` are created automatically.
+- File type constraints:
+  - image output uses `.png`
+  - video output uses `.mp4`
+  - audio output (`music`/`tts`) uses `.mp3`
+- If user does not explicitly provide output file name, agent must generate one in current directory:
+  - use 3-digit incremental prefix to avoid collisions, like `001_...`, `002_...`
+  - keep file name meaningful by task content, e.g. `001_city-night-drive.mp4`, `002_lofi-beat.mp3`
+- ffmpeg and pandoc outputs follow the same naming rule:
+  - if output path is not explicitly specified by user, agent should generate a meaningful file name with `NNN_` prefix and correct extension
+  - for pandoc, keep extension aligned with conversion target format

package/dist/skill/edit-video/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: edit-video
+description: Use this skill when the user wants to edit existing videos, replace visual elements, preserve camera language, or stitch multiple clips. Execute with zerocut-cli commands only.
+homepage: "https://github.com/liubei-ai/zerocut-cli"
+source: "https://github.com/liubei-ai/zerocut-cli"
+requires_binaries:
+  - "zerocut-cli"
+  - "npx"
+---
+
+# Edit Video
+
+## Runtime Requirements
+
+- Use CLI commands only.
+- Do not use MCP tool names in instructions.
+- Ensure CLI is available:
+  - `pnpm dlx zerocut-cli help`
+  - `pnpm add -g zerocut-cli && zerocut-cli help`
+  - `npx zerocut-cli help`
+
+## Required Pre-Check
+
+```bash
+npx zerocut-cli config list
+```
+
+If `apiKey` is missing, stop and request OTT token:
+
+```bash
+npx zerocut-cli config --ott <token> --region <cn|us>
+```
+
+## Video Edit Defaults
+
+- Default model is `seedance-2.0` unless user explicitly specifies another legal video model.
+- Unless user explicitly specifies, keep original visual specs by not forcing `--aspectRatio` and `--resolution`.
+- Keep user-requested camera language and motion intent.
+
+## Legal Video Parameters
+
+Only use legal `video` command options:
+
+- `--prompt <prompt>` required
+- `--duration <seconds>`
+- `--model <model>`
+- `--sourceVideo <video>`
+- `--seed <seed>`
+- `--firstFrame <image>`
+- `--lastFrame <image>`
+- `--storyboard <image>`
+- `--persons <persons>`
+- `--refs <assets>`
+- `--resolution <resolution>`
+- `--aspectRatio <ratio>`
+- `--withAudio`
+- `--withBGM <withBGM>`
+- `--optimizeCameraMotion`
+- `--output <file>`
+
+## Replace Elements In Existing Video
+
+When user asks to replace objects/subjects in an existing clip, pass source video and references to `video` command:
+
+```bash
+npx zerocut-cli video \
+  --prompt "Replace the perfume gift-box product with the cream from reference image, keep original camera movement." \
+  --model seedance-2.0 \
+  --sourceVideo input.mp4 \
+  --refs product_ref.png \
+  --withAudio \
+  --withBGM true \
+  --output edited.mp4
+```
+
+## Character-Aware Editing
+
+If user provides character photos, pass them with `--persons` so they map to `type=person`:
+
+```bash
+npx zerocut-cli video \
+  --prompt "Keep scene pacing, replace actor with provided character while preserving performance rhythm." \
+  --model seedance-2.0 \
+  --sourceVideo input.mp4 \
+  --persons actor_front.png,actor_side.png \
+  --withAudio \
+  --output edited_person.mp4
+```
+
+## Stitch Multiple Videos
+
+Use ffmpeg command path for deterministic stitching.
+
+Create concat list:
+
+```bash
+printf "file 'clip1.mp4'\nfile 'clip2.mp4'\nfile 'clip3.mp4'\n" > concat.txt
+```
+
+Concatenate:
+
+```bash
+npx zerocut-cli ffmpeg --args -f concat -safe 0 -i concat.txt -c copy merged.mp4 --resources concat.txt clip1.mp4 clip2.mp4 clip3.mp4
+```
+
+## Hard Rules
+
+- Never use non-CLI tool calls in this skill.
+- Do not use unsupported video parameters.
+- Keep edits faithful to user instructions and preserve continuity.
+- If a command returns `Not enough credits`, stop immediately and ask user to recharge before continuing.

package/dist/skill/one-click-video/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: one-click-video
+description: Use this skill when the user wants to produce a complete short video from a topic with fast CLI-driven workflow: scene planning, storyboard creation, scene video generation, optional background music, and final ffmpeg composition.
+homepage: "https://github.com/liubei-ai/zerocut-cli"
+source: "https://github.com/liubei-ai/zerocut-cli"
+requires_binaries:
+  - "zerocut-cli"
+  - "npx"
+---
+
+# One-Click Video
+
+## Purpose
+
+Create a deliverable final video by orchestrating `zerocut-cli` commands only.
+
+## Runtime Requirements
+
+- Use CLI commands only, never MCP tool names.
+- Ensure `zerocut-cli` is available:
+  - `pnpm dlx zerocut-cli help`
+  - `pnpm add -g zerocut-cli && zerocut-cli help`
+  - `npx zerocut-cli help`
+
+## Required Pre-Check
+
+Run config check first:
+
+```bash
+npx zerocut-cli config list
+```
+
+If `apiKey` is missing, stop and request user OTT token:
+
+```bash
+npx zerocut-cli config --ott <token> --region <cn|us>
+```
+
+## Video Parameter Contract
+
+When generating scene videos, only use legal `video` command parameters:
+
+- `--prompt <prompt>` required
+- `--duration <seconds>`
+- `--model <model>`
+- `--sourceVideo <video>`
+- `--seed <seed>`
+- `--firstFrame <image>`
+- `--lastFrame <image>`
+- `--storyboard <image>`
+- `--persons <persons>` comma-separated image paths/URLs, mapped to `type=person`
+- `--refs <assets>`
+- `--resolution <resolution>`
+- `--aspectRatio <ratio>`
+- `--withAudio`
+- `--withBGM <withBGM>` `true|false`, default `true`
+- `--optimizeCameraMotion`
+- `--output <file>`
+
+## Output Naming Rules
+
+- If user does not provide output path, generate meaningful names with 3-digit prefix:
+  - `001_storyboard_scene1.png`
+  - `002_scene1.mp4`
+  - `003_scene2.mp4`
+  - `004_bgm.mp3`
+  - `005_final.mp4`
+
+## Workflow
+
+1. Understand topic, goal, duration, platform orientation, and style.
+2. Split into 1-5 scenes with clear narrative progression.
+3. Create one storyboard image for each scene.
+4. Generate one video clip for each scene using only legal video parameters.
+5. Optionally generate one background music track with `music` command.
+6. Compose final video with `ffmpeg` command.
+
+## Scene Storyboard Step
+
+Generate storyboard for each scene:
+
+```bash
+npx zerocut-cli image --prompt "<scene storyboard prompt>" --model banana2 --aspectRatio 16:9 --resolution 1K --output 001_storyboard_scene1.png
+```
+
+## Scene Video Step
+
+Use storyboard as `--storyboard`, optional character images via `--persons`, and optional extra references via `--refs`.
+
+```bash
+npx zerocut-cli video \
+  --prompt "<scene video prompt>" \
+  --model seedance-2.0 \
+  --duration 12 \
+  --resolution 720p \
+  --aspectRatio 16:9 \
+  --storyboard 001_storyboard_scene1.png \
+  --persons actor_front.png,actor_side.png \
+  --refs prop_ref.png,env_ref.png \
+  --withAudio \
+  --withBGM true \
+  --output 002_scene1.mp4
+```
+
+## Background Music Step
+
+Generate one BGM track when needed:
+
+```bash
+npx zerocut-cli music --prompt "<bgm prompt>" --output 004_bgm.mp3
+```
+
+## Final Composition Step (ffmpeg only)
+
+Create concat list:
+
+```bash
+printf "file '002_scene1.mp4'\nfile '003_scene2.mp4'\n" > concat.txt
+```
+
+Concatenate scene clips:
+
+```bash
+npx zerocut-cli ffmpeg --args -f concat -safe 0 -i concat.txt -c copy 005_concat.mp4 --resources concat.txt 002_scene1.mp4 003_scene2.mp4
+```
+
+Mix BGM with original video audio:
+
+```bash
+npx zerocut-cli ffmpeg --args -i 005_concat.mp4 -i 004_bgm.mp3 -filter_complex "[1:a]volume=0.2[bgm];[0:a][bgm]amix=inputs=2:duration=first:dropout_transition=2[aout]" -map 0:v -map "[aout]" -c:v copy -c:a aac 005_final.mp4 --resources 005_concat.mp4 004_bgm.mp3
+```
+
+## Hard Rules
+
+- Do not introduce non-CLI tool calls.
+- Do not use parameters outside the legal `video` parameter contract.
+- Keep single scene duration within model limits.
+- Keep visual style consistent across all scenes.
+- Keep role identity consistent when using `--persons`.
+- Do not generate subtitles in this workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zerocut-cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "ZeroCut CLI: AI assistant CLI for creating and editing images/audio/video",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/copy-skill-md.cjs

@@ -1,8 +1,8 @@
 const fs = require("node:fs");
 const path = require("node:path");
 
-const src = path.resolve(__dirname, "../src/skill/SKILL.md");
-const dest = path.resolve(__dirname, "../dist/skill/SKILL.md");
+const srcDir = path.resolve(__dirname, "../src/skill");
+const distDir = path.resolve(__dirname, "../dist/skill");
 
-fs.mkdirSync(path.dirname(dest), { recursive: true });
-fs.copyFileSync(src, dest);
+fs.mkdirSync(distDir, { recursive: true });
+fs.cpSync(srcDir, distDir, { recursive: true });