reelforge 1.23.0 → 1.24.1

package/dist/commands/assets.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import fsSync from "node:fs";
 import path from "node:path";
 import { post } from "../client.js";
+import { uploadToOss } from "../utils/oss-upload.js";
 import { info, isJson, print, success, warn } from "../utils/output.js";
 import { ASSETS_WORKFLOW_TEXT } from "./assets-workflow-text.js";
 const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".webp"]);
@@ -63,13 +64,23 @@ async function resolveAsset(input) {
         const supported = [...IMAGE_EXT, ...VIDEO_EXT].join(" / ");
         throw new Error(`unsupported extension ${ext} (supported: ${supported})`);
     }
-    const buf = await fs.readFile(abs);
-    return { url: `data:${mime};base64,${buf.toString("base64")}`, type };
+    try {
+        const key = await uploadToOss(abs);
+        return { key, type };
+    }
+    catch (e) {
+        warn(`${path.basename(abs)}: OSS 直传不可用,回退内联上传 (${e instanceof Error ? e.message : e})`);
+        const buf = await fs.readFile(abs);
+        return { url: `data:${mime};base64,${buf.toString("base64")}`, type };
+    }
 }
 async function describeOne(input, opts) {
-    const { url, type } = await resolveAsset(input);
+    const { url, key, type } = await resolveAsset(input);
     const body = {};
-    body[`${type}_url`] = url;
+    if (key)
+        body[`${type}_key`] = key;
+    else
+        body[`${type}_url`] = url;
     if (opts.model)
         body.model = opts.model;
     if (opts.prompt)

package/dist/commands/clip.js

@@ -0,0 +1,139 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { post } from "../client.js";
+import { waitForTask } from "../utils/task-waiter.js";
+import { downloadTo } from "../utils/download.js";
+import { formatUsd, humanDuration, info, isJson, print, success } from "../utils/output.js";
+async function loadSpec(raw) {
+    let text = raw;
+    if (raw.startsWith("@")) {
+        text = await fs.readFile(path.resolve(raw.slice(1)), "utf8");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`--spec is not valid JSON: ${e instanceof Error ? e.message : e}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("--spec must be a JSON object (the component's render spec)");
+    }
+    return parsed;
+}
+export function registerClip(program) {
+    program
+        .command("clip")
+        .description("一个 scene 组件 → 独立竖屏 MP4 (可选配音; 给 `rf dub --append` 拼片尾用)")
+        .helpOption("-h, --help", "show help")
+        .requiredOption("--component <id>", "组件 kind id (如 kinetic-text / quote-card / index-board)")
+        .requiredOption("--spec <json>", "组件 spec,内联 JSON 或 @文件路径")
+        .option("--theme <id>", "主题皮肤 id (缺省 = 组件所属 profile;general 组件用 general)")
+        .option("--narration <text>", "配音文案 (传了才有声音;不传 = 无声片段)")
+        .option("--voice <id>", "配音音色 (index-tts-2 音色名, 默认 熊小二)", "熊小二")
+        .option("--tts-model <id>", "TTS 模型 (默认 vox/index-tts-2)", "vox/index-tts-2")
+        .option("--duration <sec>", "片段时长 (秒);缺省 = 组件自然时长(无声)或配音时长(有声)", (v) => parseFloat(v))
+        .option("--subtitles", "烧录字幕 (默认不烧;组件通常自带文字)")
+        .option("--subtitle-style <style>", "字幕样式: plate | stroke | cinema (默认 plate)", "plate")
+        .option("-o, --output <file>", "输出 MP4 路径 (默认: clip-<组件>.mp4, 放在当前目录)")
+        .option("--preview-only", "只生成 preview, 不渲染最终 MP4")
+        .option("--poll-ms <ms>", "轮询间隔", (v) => parseInt(v, 10), 1500)
+        .option("--timeout-ms <ms>", "最长等待时间", (v) => parseInt(v, 10))
+        .addHelpText("after", [
+        "",
+        "它是什么:",
+        "  把单个 scene 组件渲染成一段独立的 1080×1920 竖屏 MP4。通用命令 —— 任何",
+        "  想单独跑的组件都走这里;最常见用途是给 `rf dub --append` 做固定片尾(关注卡 /",
+        "  赞助板 / 口播尾板),生成一次反复拼,省去每条视频重复 TTS。",
+        "",
+        "配音 (可选):",
+        "  · 不传 --narration → 无声片段,时长 = 组件自然时长 (或 --duration)。",
+        "  · 传 --narration   → 熊小二配音 (可 --voice 换),时长 = max(配音, 组件自然时长),",
+        "                       即配音短也不会截断动画;--subtitles 可另烧字幕。",
+        "",
+        "组件 (--component) + spec (--spec):",
+        "  · --component 传组件的 kind id。常用通用组件: kinetic-text(一句大字) /",
+        "    quote-card(金句) / comparison-vs(对比) / stat-counter(数字) /",
+        "    bullet-list(要点) / timeline(时间线)。finance / mindset 垂直组件也可,",
+        "    会自动套对应主题皮肤 (也可 --theme 指定)。",
+        "  · --spec 是该组件的渲染字段 (JSON 对象),内联或 @文件。字段随组件而定,",
+        "    例: kinetic-text = {text, emphasis};quote-card = {quote, author, context}。",
+        "",
+        "认证: 需要 API key — `rf login <key>` / $REELFORGE_API_KEY / --api-key。",
+        "可用音色: `rf tts voices`。",
+        "",
+        "示例:",
+        "  # 无声金句卡 (用组件自然时长)",
+        '  rf clip --component quote-card --spec \'{"quote":"慢即是快","author":"老张"}\'',
+        "",
+        "  # 带配音的关注片尾,再拼到 dub 后面 (典型用法)",
+        '  rf clip --component kinetic-text --spec \'{"text":"关注 机械制造师","emphasis":"机械制造师"}\' \\',
+        '    --narration "关注机械制造师官方账号,每天一个离谱发明" -o outro.mp4',
+        "  rf dub gameplay.mp4 --append outro.mp4",
+        "",
+        "  # 指定时长 + 字幕",
+        '  rf clip --component kinetic-text --spec \'{"text":"上车!"}\' --narration "都给我上车" --subtitles --duration 4',
+        "",
+        "  # 财经组件 (spec 从文件读, 自动用 finance 皮肤)",
+        "  rf clip --component index-board --spec @board.json",
+    ].join("\n"))
+        .action(async (opts) => {
+        const spec = await loadSpec(opts.spec);
+        const subtitleStyle = (opts.subtitleStyle || "plate").toLowerCase();
+        if (!["plate", "stroke", "cinema"].includes(subtitleStyle)) {
+            throw new Error(`--subtitle-style must be plate | stroke | cinema (got ${opts.subtitleStyle})`);
+        }
+        if (opts.duration !== undefined && (!Number.isFinite(opts.duration) || opts.duration <= 0)) {
+            throw new Error(`--duration must be a positive number (got ${opts.duration})`);
+        }
+        const body = {
+            component: opts.component,
+            spec,
+            voice: opts.voice || "熊小二",
+            tts_model: opts.ttsModel || "vox/index-tts-2",
+            subtitles: opts.subtitles === true,
+            subtitle_style: subtitleStyle,
+        };
+        if (opts.theme)
+            body.theme = opts.theme;
+        if (opts.narration)
+            body.narration = opts.narration;
+        if (opts.duration !== undefined)
+            body.duration_sec = opts.duration;
+        if (opts.previewOnly)
+            body.preview_only = true;
+        info(`Rendering component "${opts.component}"${opts.narration ? " (voiced)" : " (silent)"}...`);
+        const submitted = await post("/api/v1/clip", body);
+        info(`Submitted task: ${submitted.task_id} — 渲染中, 请稍候...`);
+        const t = await waitForTask(submitted.task_id, { pollMs: opts.pollMs, timeoutMs: opts.timeoutMs });
+        if (t.status !== "completed") {
+            throw new Error(t.error || `Task ended with status ${t.status}`);
+        }
+        const result = t.result;
+        if (result?.render_pending) {
+            info(`MP4 render skipped (--preview-only). Run \`rf render ${t.id}\` to finalize.`);
+        }
+        else if (result?.video_url) {
+            const stdoutIsPipe = !process.stdout.isTTY;
+            const skipDownload = stdoutIsPipe && !opts.output;
+            let savedPath;
+            if (opts.output)
+                savedPath = path.resolve(opts.output);
+            else if (!skipDownload)
+                savedPath = path.resolve(`clip-${opts.component}.mp4`);
+            if (savedPath) {
+                await downloadTo(result.video_url, savedPath);
+                success(`Saved → ${savedPath}`);
+            }
+        }
+        if (result?.generation_ms != null) {
+            const playback = result.duration != null ? `, ${result.duration.toFixed(1)}s` : "";
+            const skin = result.theme ? `, theme ${result.theme}` : "";
+            info(`generated in ${humanDuration(result.generation_ms)}${playback}${skin}`);
+        }
+        if (result?.price_usd != null)
+            info(`charge: ${formatUsd(result.price_usd)}`);
+        if (isJson())
+            print({ task_id: t.id, status: t.status, ...result });
+    });
+}

package/dist/commands/compose.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import fsSync from "node:fs";
 import path from "node:path";
 import { post, getServer } from "../client.js";
+import { uploadToOss } from "../utils/oss-upload.js";
 import { waitForTask } from "../utils/task-waiter.js";
 import { downloadTo } from "../utils/download.js";
 import { formatUsd, humanDuration, info, print, success, warn } from "../utils/output.js";
@@ -18,15 +19,6 @@ const EXT_TO_MIME = {
     ".mov": "video/quicktime",
     ".webm": "video/webm",
 };
-function fmtSize(bytes) {
-    if (!bytes)
-        return "0";
-    if (bytes < 1024)
-        return `${bytes} B`;
-    if (bytes < 1024 * 1024)
-        return `${(bytes / 1024).toFixed(1)} KB`;
-    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
-}
 function listSpecPaths(spec) {
     const paths = new Set();
     if (spec.audio.narration)
@@ -188,14 +180,27 @@ async function renderComposeOnce(specPath, opts) {
     info(`Reading spec from ${specPath}...`);
     const specPaths = listSpecPaths(spec);
     const files = {};
-    let totalBytes = 0;
+    const fileKeys = {};
     for (const p of specPaths) {
-        const r = await readAsDataUri(p, baseDir);
-        files[p] = r.dataUri;
-        totalBytes += r.bytes;
+        const abs = path.isAbsolute(p) ? p : path.resolve(baseDir, p);
+        if (!fsSync.existsSync(abs)) {
+            throw new Error(`compose: spec references "${p}" but file not found at ${abs}`);
+        }
+        try {
+            fileKeys[p] = await uploadToOss(abs);
+        }
+        catch (e) {
+            warn(`${p}: OSS 直传不可用,回退内联上传 (${e instanceof Error ? e.message : e})`);
+            const r = await readAsDataUri(p, baseDir);
+            files[p] = r.dataUri;
+        }
     }
-    info(`Bundling ${specPaths.length} files (${fmtSize(totalBytes)} total)...`);
-    const body = { spec, files };
+    info(`Bundling ${specPaths.length} files (${Object.keys(fileKeys).length} 直传 OSS, ${Object.keys(files).length} 内联)...`);
+    const body = { spec };
+    if (Object.keys(fileKeys).length)
+        body.file_keys = fileKeys;
+    if (Object.keys(files).length)
+        body.files = files;
     if (opts.previewOnly)
         body.preview_only = true;
     const submitted = await post("/api/v1/compose", body);

package/dist/commands/compositions.js

@@ -1,7 +1,8 @@
 import { post } from "../client.js";
 import { downloadTo } from "../utils/download.js";
-import { print, success, info } from "../utils/output.js";
-import { fmtSize, resolveFileInput, resolveFileInputs } from "../utils/file-upload.js";
+import { print, success, info, warn } from "../utils/output.js";
+import { fmtSize, resolveUploadInput, resolveUploadInputs } from "../utils/file-upload.js";
+const onOssFallback = (flagName, reason) => warn(`${flagName}: OSS 直传不可用,回退内联上传 (${reason})`);
 const WHEN_TO_USE = [
     "",
     "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
@@ -52,18 +53,22 @@ export function registerCompositions(program) {
         .action(async (videos, opts) => {
         if (!opts.output)
             throw new Error("--output is required");
-        const { resolved, totalBytes } = await resolveFileInputs(videos, {
+        const { resolved, totalBytes } = await resolveUploadInputs(videos, {
             flagName: "<videos...>",
+            onFallback: onOssFallback,
         });
         const bgm = opts.bgm
-            ? await resolveFileInput(opts.bgm, { flagName: "--bgm" })
+            ? await resolveUploadInput(opts.bgm, { flagName: "--bgm", onFallback: onOssFallback })
             : null;
         if (totalBytes)
             info(`Uploading ${resolved.length} videos (${fmtSize(totalBytes + (bgm?.bytes ?? 0))})...`);
+        const videoKeys = resolved.filter((r) => r.key).map((r) => r.key);
+        const videoUris = resolved.filter((r) => r.url).map((r) => r.url);
         const r = await post("/api/v1/compositions/concat", {
-            videos: resolved.map((r) => r.url),
+            videos: videoUris,
+            video_keys: videoKeys,
             method: opts.method,
-            bgm_path: bgm?.url,
+            ...(bgm?.key ? { bgm_key: bgm.key } : bgm?.url ? { bgm_path: bgm.url } : {}),
             bgm_volume: opts.bgmVolume,
             bgm_mode: opts.bgmMode,
         });
@@ -83,12 +88,12 @@ export function registerCompositions(program) {
         .action(async (opts) => {
         if (!opts.output)
             throw new Error("--output is required");
-        const v = await resolveFileInput(opts.input, { flagName: "-i / --input" });
-        const b = await resolveFileInput(opts.bgm, { flagName: "--bgm" });
+        const v = await resolveUploadInput(opts.input, { flagName: "-i / --input", onFallback: onOssFallback });
+        const b = await resolveUploadInput(opts.bgm, { flagName: "--bgm", onFallback: onOssFallback });
         info(`Uploading video (${fmtSize(v.bytes ?? 0)}) + bgm (${fmtSize(b.bytes ?? 0)})...`);
         const r = await post("/api/v1/compositions/bgm", {
-            video: v.url,
-            bgm: b.url,
+            ...(v.key ? { video_key: v.key } : { video: v.url }),
+            ...(b.key ? { bgm_key: b.key } : { bgm: b.url }),
             volume: opts.volume,
             mode: opts.mode,
         });
@@ -107,12 +112,12 @@ export function registerCompositions(program) {
         .action(async (opts) => {
         if (!opts.output)
             throw new Error("--output is required");
-        const img = await resolveFileInput(opts.image, { flagName: "-i / --image" });
-        const aud = await resolveFileInput(opts.audio, { flagName: "-a / --audio" });
+        const img = await resolveUploadInput(opts.image, { flagName: "-i / --image", onFallback: onOssFallback });
+        const aud = await resolveUploadInput(opts.audio, { flagName: "-a / --audio", onFallback: onOssFallback });
         info(`Uploading image (${fmtSize(img.bytes ?? 0)}) + audio (${fmtSize(aud.bytes ?? 0)})...`);
         const r = await post("/api/v1/compositions/image-to-video", {
-            image: img.url,
-            audio: aud.url,
+            ...(img.key ? { image_key: img.key } : { image: img.url }),
+            ...(aud.key ? { audio_key: aud.key } : { audio: aud.url }),
             fps: opts.fps,
         });
         await downloadTo(r.url, opts.output);
@@ -129,12 +134,12 @@ export function registerCompositions(program) {
         .action(async (opts) => {
         if (!opts.output)
             throw new Error("--output is required");
-        const v = await resolveFileInput(opts.video, { flagName: "-v / --video" });
-        const o = await resolveFileInput(opts.overlay, { flagName: "--overlay" });
+        const v = await resolveUploadInput(opts.video, { flagName: "-v / --video", onFallback: onOssFallback });
+        const o = await resolveUploadInput(opts.overlay, { flagName: "--overlay", onFallback: onOssFallback });
         info(`Uploading video (${fmtSize(v.bytes ?? 0)}) + overlay (${fmtSize(o.bytes ?? 0)})...`);
         const r = await post("/api/v1/compositions/overlay", {
-            video: v.url,
-            overlay_image: o.url,
+            ...(v.key ? { video_key: v.key } : { video: v.url }),
+            ...(o.key ? { overlay_key: o.key } : { overlay_image: o.url }),
         });
         await downloadTo(r.url, opts.output);
         success(`Saved → ${opts.output}`);

package/dist/commands/cover.js

@@ -2,7 +2,9 @@ import fs from "node:fs/promises";
 import fsSync from "node:fs";
 import path from "node:path";
 import { getServer, getApiKey } from "../client.js";
+import { uploadToOss } from "../utils/oss-upload.js";
 import { info, success, warn } from "../utils/output.js";
+const MAX_BYTES = 50 * 1024 * 1024;
 const TEMPLATES = [
     { id: "paper-band", label: "牛皮纸条 横卡", supports: "title, subtitle, badge", useFor: "财经 / 干货 / 商业分析" },
     { id: "carbon-copy", label: "复写纸 暗调", supports: "title, subtitle", useFor: "情感 / 哲思 / 治愈(默认)" },
@@ -17,6 +19,21 @@ const TEMPLATES = [
 const TEMPLATE_IDS = new Set(TEMPLATES.map((t) => t.id));
 const DEFAULT_TEMPLATE = "carbon-copy";
 const SMALL_IMAGE_WARN_BYTES = 100 * 1024;
+async function uploadOrInline(fileAbs, fileMime, label) {
+    const bytes = (await fs.stat(fileAbs)).size;
+    try {
+        const key = await uploadToOss(fileAbs);
+        return { key, bytes };
+    }
+    catch (e) {
+        if (bytes > MAX_BYTES) {
+            throw new Error(`${label} 直传 OSS 失败 (${e instanceof Error ? e.message : e}),且文件 ${fmtSize(bytes)} 超过内联回退上限 ${fmtSize(MAX_BYTES)}。`);
+        }
+        warn(`${label}: OSS 直传不可用,回退内联上传 (${e instanceof Error ? e.message : e})`);
+        const buf = await fs.readFile(fileAbs);
+        return { uri: `data:${fileMime};base64,${buf.toString("base64")}`, bytes };
+    }
+}
 async function resolveImage(input) {
     const t = input.trim();
     if (!t)
@@ -37,9 +54,8 @@ async function resolveImage(input) {
     if (!mime) {
         throw new Error(`--image: unsupported extension ${ext} (use png/jpg/jpeg/webp)`);
     }
-    const buf = await fs.readFile(abs);
-    const url = `data:${mime};base64,${buf.toString("base64")}`;
-    return { url, bytes: buf.byteLength };
+    const up = await uploadOrInline(abs, mime, "--image");
+    return { key: up.key, url: up.uri, bytes: up.bytes };
 }
 function fmtSize(b) {
     if (b < 1024)
@@ -177,7 +193,7 @@ export function registerCover(program) {
         if (missing.length > 0) {
             throw new Error(`required: ${missing.join(", ")}`);
         }
-        const { url: imageUrl, bytes } = await resolveImage(opts.image);
+        const { key: imageKey, url: imageUrl, bytes } = await resolveImage(opts.image);
         if (typeof bytes === "number" && bytes < SMALL_IMAGE_WARN_BYTES) {
             warn(`--image is ${fmtSize(bytes)} — that's quite small, the cover may look blurry. ` +
                 `For best results use a source image of at least 1080×1920.`);
@@ -188,10 +204,13 @@ export function registerCover(program) {
         }
         const params = buildParamsPayload(opts.param, opts.params);
         const body = {
-            image_url: imageUrl,
             template,
             title: opts.title,
         };
+        if (imageKey)
+            body.image_key = imageKey;
+        else
+            body.image_url = imageUrl;
         if (opts.subtitle)
             body.subtitle = opts.subtitle;
         if (opts.badge)
@@ -251,17 +270,22 @@ export function registerCover(program) {
         if (!fsSync.existsSync(coverAbs)) {
             throw new Error(`cover not found: ${coverAbs}`);
         }
-        const coverBuf = await fs.readFile(coverAbs);
-        const videoBuf = await fs.readFile(videoAbs);
         const coverExt = path.extname(coverAbs).toLowerCase();
         const coverMime = coverExt === ".jpg" || coverExt === ".jpeg" ? "image/jpeg" : "image/png";
-        const body = {
-            cover_data_uri: `data:${coverMime};base64,${coverBuf.toString("base64")}`,
-            video_data_uri: `data:video/mp4;base64,${videoBuf.toString("base64")}`,
-        };
+        const coverUp = await uploadOrInline(coverAbs, coverMime, "cover");
+        const videoUp = await uploadOrInline(videoAbs, "video/mp4", "video");
+        const body = {};
+        if (coverUp.key)
+            body.cover_key = coverUp.key;
+        else
+            body.cover_data_uri = coverUp.uri;
+        if (videoUp.key)
+            body.video_key = videoUp.key;
+        else
+            body.video_data_uri = videoUp.uri;
         if (typeof opts.fps === "number")
             body.fps = opts.fps;
-        info(`Prepending cover (${fmtSize(coverBuf.byteLength)}) → video (${fmtSize(videoBuf.byteLength)})...`);
+        info(`Prepending cover (${fmtSize(coverUp.bytes)}) → video (${fmtSize(videoUp.bytes)})...`);
         const server = getServer().replace(/\/+$/, "");
         const apiKey = getApiKey();
         const headers = { "content-type": "application/json" };

package/dist/commands/create.js

@@ -3,6 +3,7 @@ import fsSync from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { post, getServer } from "../client.js";
+import { uploadToOss } from "../utils/oss-upload.js";
 import { waitForTask } from "../utils/task-waiter.js";
 import { downloadTo } from "../utils/download.js";
 import { formatUsd, humanDuration, info, print, success, warn } from "../utils/output.js";
@@ -38,14 +39,15 @@ async function resolveTextOrFile(input) {
     }
     return input;
 }
-async function resolveRefImage(input, flagName) {
+const REF_IMAGE_MAX_BYTES = 15 * 1024 * 1024;
+async function resolveRefImageUpload(input, flagName) {
     if (input === undefined)
         return undefined;
     const t = input.trim();
     if (!t)
         return undefined;
     if (/^https?:\/\//i.test(t) || t.startsWith("data:"))
-        return t;
+        return { passthrough: t };
     const abs = path.resolve(t);
     if (!fsSync.existsSync(abs)) {
         throw new Error(`${flagName}: local file not found: ${abs}`);
@@ -58,8 +60,19 @@ async function resolveRefImage(input, flagName) {
     if (!mime) {
         throw new Error(`${flagName}: unsupported extension ${ext} (use png/jpg/jpeg/webp)`);
     }
-    const buf = await fs.readFile(abs);
-    return `data:${mime};base64,${buf.toString("base64")}`;
+    try {
+        const key = await uploadToOss(abs);
+        return { key };
+    }
+    catch (e) {
+        const sz = (await fs.stat(abs)).size;
+        if (sz > REF_IMAGE_MAX_BYTES) {
+            throw new Error(`${flagName} 直传 OSS 失败 (${e instanceof Error ? e.message : e}),且文件超过内联回退上限 ${REF_IMAGE_MAX_BYTES} 字节。`);
+        }
+        warn(`${flagName}: OSS 直传不可用,回退内联上传 (${e instanceof Error ? e.message : e})`);
+        const buf = await fs.readFile(abs);
+        return { passthrough: `data:${mime};base64,${buf.toString("base64")}` };
+    }
 }
 async function loadRecipe(recipePath) {
     const raw = await fs.readFile(recipePath, "utf-8");
@@ -512,17 +525,30 @@ export function registerCreate(program) {
                 "  # (compose your script using /tmp/ref.txt as raw material in your agent)\n" +
                 "  rf create --script @final.txt -d 60        # render it");
         }
-        const resolvedChar = await resolveRefImage(body.character_ref, "--character-ref");
-        if (resolvedChar !== undefined)
-            body.character_ref = resolvedChar;
-        else
-            delete body.character_ref;
+        const resolvedChar = await resolveRefImageUpload(body.character_ref, "--character-ref");
+        delete body.character_ref;
+        delete body.character_ref_key;
+        if (resolvedChar?.key)
+            body.character_ref_key = resolvedChar.key;
+        else if (resolvedChar?.passthrough)
+            body.character_ref = resolvedChar.passthrough;
         if (body.brand?.logo_url) {
-            const resolvedLogo = await resolveRefImage(body.brand.logo_url, "--brand-logo");
-            if (resolvedLogo !== undefined)
-                body.brand.logo_url = resolvedLogo;
-            else
-                delete body.brand.logo_url;
+            const resolvedLogo = await resolveRefImageUpload(body.brand.logo_url, "--brand-logo");
+            delete body.brand.logo_url;
+            delete body.brand_logo_key;
+            if (resolvedLogo?.key)
+                body.brand_logo_key = resolvedLogo.key;
+            else if (resolvedLogo?.passthrough)
+                body.brand.logo_url = resolvedLogo.passthrough;
+        }
+        if (body.cover?.base) {
+            const resolvedBase = await resolveRefImageUpload(body.cover.base, "--cover-base");
+            delete body.cover.base;
+            delete body.cover_base_key;
+            if (resolvedBase?.key)
+                body.cover_base_key = resolvedBase.key;
+            else if (resolvedBase?.passthrough)
+                body.cover.base = resolvedBase.passthrough;
         }
         const hasTopic = typeof body.topic === "string" && body.topic.trim().length > 0;
         const hasScript = typeof body.script === "string" && body.script.trim().length > 0;
@@ -545,7 +571,11 @@ export function registerCreate(program) {
         }
         info(`Submitting create task (≈ ${formatUsd(estimate)})...`);
         const submitted = await post("/api/v1/pipelines/standard", finalBody);
-        await saveLastCreate(finalBody).catch((e) => {
+        const toSave = { ...finalBody };
+        delete toSave.character_ref_key;
+        delete toSave.brand_logo_key;
+        delete toSave.cover_base_key;
+        await saveLastCreate(toSave).catch((e) => {
             warn(`Could not save last-create.json: ${e.message}`);
         });
         if (opts.wait === false) {

package/dist/commands/dub.js

@@ -2,9 +2,10 @@ import fs from "node:fs/promises";
 import fsSync from "node:fs";
 import path from "node:path";
 import { post } from "../client.js";
+import { uploadToOss } from "../utils/oss-upload.js";
 import { waitForTask } from "../utils/task-waiter.js";
 import { downloadTo } from "../utils/download.js";
-import { formatUsd, humanDuration, info, isJson, print, success } from "../utils/output.js";
+import { formatUsd, humanDuration, info, isJson, print, success, warn } from "../utils/output.js";
 const VIDEO_EXT_TO_MIME = {
     ".mp4": "video/mp4",
     ".mov": "video/quicktime",
@@ -33,6 +34,15 @@ export function registerDub(program) {
         .option("--game-volume <n>", "原视频自带声音的音量 0..1 (默认 0.6; 设 0 = 完全静音原声, 只留配音)", (v) => parseFloat(v), 0.6)
         .option("--no-subtitles", "不烧录字幕 (默认烧录)")
         .option("--subtitle-style <style>", "字幕样式: plate | stroke | cinema (默认 plate)", "plate")
+        .option("--no-cover", "不加封面 (默认自动生成封面)")
+        .option("--cover-template <id>", "封面模板 (默认 paper-band; 见 `rf cover templates`)", "paper-band")
+        .option("--cover-title <text>", "封面标题 (默认自动生成 ≤10 字钩子)")
+        .option("--cover-subtitle <text>", "封面副标题 (默认无)")
+        .option("--cover-badge <text>", "封面角标 (默认无)")
+        .option("--append <file>", "在成片末尾拼接一段视频 (如 `rf clip` 出的关注片尾; 可多次传, 按顺序拼)", (val, acc) => {
+        acc.push(val);
+        return acc;
+    }, [])
         .option("--theme <id>", "可选主题 id (影响字幕底板 / 配色风格)")
         .option("--vision-model <id>", "反推用的视觉模型 (默认 qwen/qwen3-vl-flash)")
         .option("--script-model <id>", "写解说脚本用的 LLM (默认服务端配置模型)")
@@ -47,6 +57,10 @@ export function registerDub(program) {
         "  3. 用熊小二音色合成配音 (可 --voice 指定其它音色)",
         "  4. 把配音叠到原视频上, 原视频自带声音压到 60% 垫底 (可 --game-volume 调)",
         "  5. 烧录字幕 (复用 compose 的字幕样式 + 切分逻辑; --no-subtitles 关闭)",
+        "  6. 自动生成封面 — 选画面最炸的一帧当底图 + LLM 钩子标题, 套 paper-band 模板",
+        "     (--no-cover 关; --cover-template / --cover-title 自定; 见 `rf cover templates`)",
+        "  7. (可选) 在末尾拼接片尾 — --append <clip.mp4>, 可多次, 按顺序拼",
+        "     (片尾用 `rf clip` 先生成, 比如固定的「关注」引导卡, 生成一次反复用)",
         "",
         "认证:",
         "  需要 API key — `rf login <key>` 或 $REELFORGE_API_KEY 或 --api-key <key>。",
@@ -71,6 +85,11 @@ export function registerDub(program) {
         "",
         "  # 先看效果再决定 (preview, 不渲染 MP4)",
         "  rf dub ./clip.mp4 --preview-only",
+        "",
+        "  # 配上固定片尾「关注卡」(先用 rf clip 生成一次, 之后反复拼)",
+        "  rf clip --component kinetic-text --spec '{\"text\":\"关注 机械制造师\"}' \\",
+        "    --narration \"关注机械制造师官方账号,每天一个离谱发明\" -o outro.mp4",
+        "  rf dub ./clip.mp4 --append outro.mp4",
     ].join("\n"))
         .action(async (videoArg, opts) => {
         const abs = path.resolve(videoArg);
@@ -89,22 +108,69 @@ export function registerDub(program) {
         if (!["plate", "stroke", "cinema"].includes(subtitleStyle)) {
             throw new Error(`--subtitle-style must be plate | stroke | cinema (got ${opts.subtitleStyle})`);
         }
-        const buf = await fs.readFile(abs);
-        if (buf.byteLength > MAX_BYTES) {
-            throw new Error(`video is ${fmtSize(buf.byteLength)} — exceeds the ${fmtSize(MAX_BYTES)} upload cap. ` +
-                `Compress / trim it first (e.g. ffmpeg -crf 28).`);
-        }
-        info(`Uploading ${path.basename(abs)} (${fmtSize(buf.byteLength)})...`);
         const body = {
-            video: `data:${mime};base64,${buf.toString("base64")}`,
             voice: opts.voice || "熊小二",
             tts_model: opts.ttsModel || "vox/index-tts-2",
             game_audio_volume: gameVolume,
             subtitles: opts.subtitles !== false,
             subtitle_style: subtitleStyle,
+            cover: opts.cover !== false,
         };
+        if (opts.coverTemplate)
+            body.cover_template = opts.coverTemplate;
+        if (opts.coverTitle)
+            body.cover_title = opts.coverTitle;
+        if (opts.coverSubtitle)
+            body.cover_subtitle = opts.coverSubtitle;
+        if (opts.coverBadge)
+            body.cover_badge = opts.coverBadge;
         if (opts.theme)
             body.theme = opts.theme;
+        const uploadOrInline = async (fileAbs, fileMime, label) => {
+            try {
+                const key = await uploadToOss(fileAbs);
+                return { key };
+            }
+            catch (e) {
+                const sz = (await fs.stat(fileAbs)).size;
+                if (sz > MAX_BYTES) {
+                    throw new Error(`${label} 直传 OSS 失败 (${e instanceof Error ? e.message : e}),且文件 ${fmtSize(sz)} 超过内联回退上限 ${fmtSize(MAX_BYTES)}。`);
+                }
+                warn(`${label}: OSS 直传不可用,回退内联上传 (${e instanceof Error ? e.message : e})`);
+                const buf = await fs.readFile(fileAbs);
+                return { uri: `data:${fileMime};base64,${buf.toString("base64")}` };
+            }
+        };
+        info(`Uploading ${path.basename(abs)} (${fmtSize((await fs.stat(abs)).size)}) → 直传对象存储...`);
+        const mainUp = await uploadOrInline(abs, mime, "video");
+        if (mainUp.key)
+            body.video_key = mainUp.key;
+        else
+            body.video = mainUp.uri;
+        const appendFiles = opts.append ?? [];
+        if (appendFiles.length) {
+            const appendKeys = [];
+            const appendUris = [];
+            for (const f of appendFiles) {
+                const aAbs = path.resolve(f);
+                if (!fsSync.existsSync(aAbs))
+                    throw new Error(`--append file not found: ${aAbs}`);
+                const aExt = path.extname(aAbs).toLowerCase();
+                const aMime = VIDEO_EXT_TO_MIME[aExt];
+                if (!aMime)
+                    throw new Error(`--append: unsupported extension "${aExt}" (${path.basename(aAbs)})`);
+                info(`  + append ${path.basename(aAbs)} (${fmtSize((await fs.stat(aAbs)).size)})`);
+                const up = await uploadOrInline(aAbs, aMime, `--append ${path.basename(aAbs)}`);
+                if (up.key)
+                    appendKeys.push(up.key);
+                else if (up.uri)
+                    appendUris.push(up.uri);
+            }
+            if (appendKeys.length)
+                body.append_keys = appendKeys;
+            if (appendUris.length)
+                body.append = appendUris;
+        }
         if (opts.visionModel)
             body.vision_model = opts.visionModel;
         if (opts.scriptModel)

package/dist/commands/extract.js

@@ -2,7 +2,9 @@ import fs from "node:fs/promises";
 import fsSync from "node:fs";
 import path from "node:path";
 import { post } from "../client.js";
-import { info, isJson, print, success } from "../utils/output.js";
+import { uploadToOss } from "../utils/oss-upload.js";
+import { info, isJson, print, success, warn } from "../utils/output.js";
+const MAX_BYTES = 25 * 1024 * 1024;
 const FILE_EXT_TO_MIME = {
     ".pdf": "application/pdf",
     ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
@@ -13,13 +15,13 @@ async function resolveSource(input) {
     if (!t)
         throw new Error("--reference / source is empty");
     if (t.startsWith("data:"))
-        return t;
+        return { source: t };
     if (/^https?:\/\//i.test(t))
-        return t;
+        return { source: t };
     if (/v\.douyin\.com\//i.test(t) || /复制此链接/.test(t) || /打开抖音/.test(t))
-        return t;
+        return { source: t };
     if (/^[a-z0-9][a-z0-9-._]*\/[a-z0-9][a-z0-9-._]*$/i.test(t) && !t.split("/")[0].includes(".")) {
-        return t;
+        return { source: t };
     }
     const abs = path.resolve(t);
     if (!fsSync.existsSync(abs)) {
@@ -32,8 +34,19 @@ async function resolveSource(input) {
         throw new Error(`unsupported file extension "${ext}". ` +
             `Supported: ${Object.keys(FILE_EXT_TO_MIME).join(" / ")}, or pass a URL / github owner/repo / 抖音 link.`);
     }
-    const buf = await fs.readFile(abs);
-    return `data:${mime};base64,${buf.toString("base64")}`;
+    try {
+        const key = await uploadToOss(abs);
+        return { source_key: key };
+    }
+    catch (e) {
+        const sz = (await fs.stat(abs)).size;
+        if (sz > MAX_BYTES) {
+            throw new Error(`${path.basename(abs)} 直传 OSS 失败 (${e instanceof Error ? e.message : e}),且文件超过内联回退上限 ${MAX_BYTES} 字节。`);
+        }
+        warn(`source: OSS 直传不可用,回退内联上传 (${e instanceof Error ? e.message : e})`);
+        const buf = await fs.readFile(abs);
+        return { source: `data:${mime};base64,${buf.toString("base64")}` };
+    }
 }
 export function registerExtract(program) {
     program
@@ -81,7 +94,7 @@ export function registerExtract(program) {
     ].join("\n"))
         .action(async (source, opts) => {
         const resolved = await resolveSource(source);
-        const r = await post("/api/v1/reference/extract", { source: resolved });
+        const r = await post("/api/v1/reference/extract", { ...resolved });
         if (opts.output) {
             const outAbs = path.resolve(opts.output);
             await fs.mkdir(path.dirname(outAbs), { recursive: true });

package/dist/commands/images.js

@@ -2,14 +2,16 @@ import fs from "node:fs/promises";
 import fsSync from "node:fs";
 import path from "node:path";
 import { post } from "../client.js";
+import { uploadToOss } from "../utils/oss-upload.js";
 import { downloadTo } from "../utils/download.js";
-import { print, success } from "../utils/output.js";
+import { print, success, warn } from "../utils/output.js";
+const MAX_REF_BYTES = 15 * 1024 * 1024;
 async function resolveImageRef(input) {
     const t = input.trim();
     if (!t)
         throw new Error("--image: empty value");
     if (/^https?:\/\//i.test(t) || t.startsWith("data:"))
-        return t;
+        return { url: t };
     const abs = path.resolve(t);
     if (!fsSync.existsSync(abs)) {
         throw new Error(`--image: local file not found: ${abs}`);
@@ -22,8 +24,19 @@ async function resolveImageRef(input) {
     if (!mime) {
         throw new Error(`--image: unsupported extension ${ext} (use png/jpg/jpeg/webp)`);
     }
-    const buf = await fs.readFile(abs);
-    return `data:${mime};base64,${buf.toString("base64")}`;
+    try {
+        const key = await uploadToOss(abs);
+        return { key };
+    }
+    catch (e) {
+        const sz = (await fs.stat(abs)).size;
+        if (sz > MAX_REF_BYTES) {
+            throw new Error(`--image ${path.basename(abs)} 直传 OSS 失败 (${e instanceof Error ? e.message : e}),且文件超过内联回退上限 ${MAX_REF_BYTES} 字节。`);
+        }
+        warn(`--image ${path.basename(abs)}: OSS 直传不可用,回退内联上传 (${e instanceof Error ? e.message : e})`);
+        const buf = await fs.readFile(abs);
+        return { url: `data:${mime};base64,${buf.toString("base64")}` };
+    }
 }
 export function registerImages(program) {
     const images = program
@@ -69,7 +82,13 @@ export function registerImages(program) {
             if (opts.image.length > 3) {
                 throw new Error(`--image accepts at most 3 refs (got ${opts.image.length})`);
             }
-            body.image_urls = await Promise.all(opts.image.map(resolveImageRef));
+            const resolved = await Promise.all(opts.image.map(resolveImageRef));
+            const urls = resolved.filter((r) => r.url).map((r) => r.url);
+            const keys = resolved.filter((r) => r.key).map((r) => r.key);
+            if (urls.length)
+                body.image_urls = urls;
+            if (keys.length)
+                body.image_keys = keys;
         }
         const r = await post("/api/v1/images/generate", body);
         if (opts.output && r.images?.[0]) {

package/dist/commands/media.js

@@ -2,7 +2,8 @@ import fs from "node:fs/promises";
 import fsSync from "node:fs";
 import path from "node:path";
 import { post } from "../client.js";
-import { info, isJson, print } from "../utils/output.js";
+import { uploadToOss } from "../utils/oss-upload.js";
+import { info, isJson, print, warn } from "../utils/output.js";
 const MEDIA_EXT_TO_MIME = {
     ".mp4": "video/mp4",
     ".mov": "video/quicktime",
@@ -112,8 +113,15 @@ export function registerMedia(program) {
                 throw new Error(`unsupported extension "${ext}". Supported: ${Object.keys(MEDIA_EXT_TO_MIME).join(" / ")}, ` +
                     `or pass a URL.`);
             }
-            const buf = await fs.readFile(abs);
-            body = { data_uri: `data:${mime};base64,${buf.toString("base64")}` };
+            try {
+                const key = await uploadToOss(abs);
+                body = { key };
+            }
+            catch (e) {
+                warn(`${path.basename(abs)}: OSS 直传不可用,回退内联上传 (${e instanceof Error ? e.message : e})`);
+                const buf = await fs.readFile(abs);
+                body = { data_uri: `data:${mime};base64,${buf.toString("base64")}` };
+            }
             label = path.basename(abs);
         }
         const r = await post("/api/v1/media/probe", body);

package/dist/index.js

@@ -35,6 +35,7 @@ import { registerMedia } from "./commands/media.js";
 import { registerScript } from "./commands/script.js";
 import { registerCompose } from "./commands/compose.js";
 import { registerDub } from "./commands/dub.js";
+import { registerClip } from "./commands/clip.js";
 import { registerVlog } from "./commands/vlog.js";
 import { error as logError } from "./utils/output.js";
 import { ApiCallError } from "./client.js";
@@ -149,6 +150,7 @@ registerMedia(program);
 registerScript(program);
 registerCompose(program);
 registerDub(program);
+registerClip(program);
 registerVlog(program);
 async function main() {
     if (process.argv.length <= 2) {

package/dist/utils/file-upload.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import fsSync from "node:fs";
 import path from "node:path";
+import { uploadToOss } from "./oss-upload.js";
 export const EXT_TO_MIME = {
     ".png": "image/png",
     ".jpg": "image/jpeg",
@@ -57,3 +58,45 @@ export function fmtSize(bytes) {
         return `${(bytes / 1024).toFixed(1)} KB`;
     return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 }
+export async function resolveUploadInput(input, opts) {
+    const t = input.trim();
+    if (!t)
+        throw new Error(`${opts.flagName}: empty value`);
+    if (/^https?:\/\//i.test(t))
+        return { url: t, kind: "http-url" };
+    if (t.startsWith("data:"))
+        return { url: t, kind: "data-uri" };
+    const abs = path.resolve(t);
+    if (!fsSync.existsSync(abs)) {
+        throw new Error(`${opts.flagName}: local file not found: ${abs}\n` +
+            `  (Acceptable forms: local path / https:// URL / data: URI. ` +
+            `Server-side paths like 'data/uploads/...' do NOT work — CLI commands ` +
+            `auto-upload local files, so just pass the local path directly.)`);
+    }
+    const ext = path.extname(abs).toLowerCase();
+    const map = opts.extToMime ?? EXT_TO_MIME;
+    const mime = map[ext];
+    if (!mime) {
+        throw new Error(`${opts.flagName}: unsupported file extension "${ext}" (path: ${abs}). ` +
+            `Supported: ${Object.keys(map).join(" / ")}`);
+    }
+    const bytes = (await fs.stat(abs)).size;
+    try {
+        const key = await uploadToOss(abs);
+        return { key, bytes, kind: "oss-key" };
+    }
+    catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        opts.onFallback?.(opts.flagName, reason);
+        const buf = await fs.readFile(abs);
+        return { url: `data:${mime};base64,${buf.toString("base64")}`, bytes, kind: "local-file-inline" };
+    }
+}
+export async function resolveUploadInputs(inputs, opts) {
+    const resolved = [];
+    for (const input of inputs) {
+        resolved.push(await resolveUploadInput(input, opts));
+    }
+    const totalBytes = resolved.reduce((n, r) => n + (r.bytes ?? 0), 0);
+    return { resolved, totalBytes };
+}

package/dist/utils/oss-upload.js

@@ -0,0 +1,43 @@
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import { post } from "../client.js";
+const EXT_TO_MIME = {
+    ".mp4": "video/mp4",
+    ".mov": "video/quicktime",
+    ".webm": "video/webm",
+    ".mkv": "video/x-matroska",
+    ".m4v": "video/mp4",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".m4a": "audio/mp4",
+    ".ogg": "audio/ogg",
+    ".pdf": "application/pdf",
+};
+export function mimeForFile(filePath) {
+    return EXT_TO_MIME[path.extname(filePath).toLowerCase()] || "application/octet-stream";
+}
+export async function uploadToOss(filePath) {
+    if (!fsSync.existsSync(filePath))
+        throw new Error(`file not found: ${filePath}`);
+    const ext = path.extname(filePath).toLowerCase();
+    const contentType = mimeForFile(filePath);
+    const signed = await post("/api/v1/uploads/sign", { ext, content_type: contentType });
+    if (!signed?.put_url || !signed?.key)
+        throw new Error("uploads/sign returned no put_url/key");
+    const bytes = await fs.readFile(filePath);
+    const res = await fetch(signed.put_url, {
+        method: "PUT",
+        headers: { "Content-Type": contentType },
+        body: bytes,
+    });
+    if (!res.ok) {
+        const detail = await res.text().catch(() => "");
+        throw new Error(`OSS PUT failed: ${res.status} ${res.statusText} ${detail.slice(0, 200)}`);
+    }
+    return signed.key;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reelforge",
-  "version": "1.23.0",
+  "version": "1.24.1",
   "description": "AI 视频生成 CLI。一句话主题或自己的脚本 → 自动出抖音/TikTok/视频号竖屏 MP4。安装即用：`reelforge` 或短别名 `rf`。",
   "license": "Apache-2.0",
   "type": "module",