reelforge 1.18.2

package/dist/commands/create.js

@@ -0,0 +1,629 @@
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { post, getServer } from "../client.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";
+const LAST_CREATE_PATH = path.join(os.homedir(), ".reelforge", "last-create.json");
+const EST_SCENE_PLAN_USD = 0.0015;
+const EST_TTS_USD_PER_CHAR = 1.575 / 1e6;
+const EST_ASR_USD_PER_SEC = 0.0319 / 60;
+const EST_IMAGE_USD = 0.003;
+const CHARS_PER_SEC_ZH = 5;
+const TARGET_SEC_PER_SCENE = 8;
+function estimateCostUsd(body) {
+    let durSec;
+    let chars;
+    if (body.script) {
+        durSec = body.script.length / CHARS_PER_SEC_ZH;
+        chars = body.script.length;
+    }
+    else {
+        durSec = body.duration ?? 45;
+        chars = Math.round(durSec * CHARS_PER_SEC_ZH);
+    }
+    const scenes = Math.max(2, Math.round(durSec / TARGET_SEC_PER_SCENE));
+    const cost = EST_SCENE_PLAN_USD +
+        chars * EST_TTS_USD_PER_CHAR +
+        durSec * EST_ASR_USD_PER_SEC +
+        scenes * EST_IMAGE_USD;
+    return cost;
+}
+async function resolveTextOrFile(input) {
+    if (input.startsWith("@")) {
+        const file = input.slice(1);
+        return (await fs.readFile(file, "utf-8")).trim();
+    }
+    return input;
+}
+async function resolveRefImage(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;
+    const abs = path.resolve(t);
+    if (!fsSync.existsSync(abs)) {
+        throw new Error(`${flagName}: local file not found: ${abs}`);
+    }
+    const ext = path.extname(abs).toLowerCase();
+    const mime = ext === ".jpg" || ext === ".jpeg" ? "image/jpeg" :
+        ext === ".webp" ? "image/webp" :
+            ext === ".png" ? "image/png" :
+                null;
+    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")}`;
+}
+async function loadRecipe(recipePath) {
+    const raw = await fs.readFile(recipePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Recipe ${recipePath}: must be a JSON object`);
+    }
+    return parsed;
+}
+async function loadLastCreate() {
+    try {
+        const raw = await fs.readFile(LAST_CREATE_PATH, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function saveLastCreate(body) {
+    await fs.mkdir(path.dirname(LAST_CREATE_PATH), { recursive: true });
+    await fs.writeFile(LAST_CREATE_PATH, JSON.stringify(body, null, 2) + "\n", "utf-8");
+}
+const FILENAME_MAX_CHARS = 40;
+function sanitizeFilename(name) {
+    const cleaned = name
+        .replace(/[\/\\:*?"<>|\r\n\t]+/g, "-")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/^[-.\s]+|[-.\s]+$/g, "");
+    const chars = Array.from(cleaned);
+    if (chars.length <= FILENAME_MAX_CHARS)
+        return cleaned;
+    return chars.slice(0, FILENAME_MAX_CHARS).join("").replace(/[-.\s]+$/g, "");
+}
+function computeDefaultFilename(args) {
+    const ext = args.ext || "mp4";
+    const shortId = args.taskId.slice(0, 8);
+    let base;
+    if (args.resultTitle && args.resultTitle.trim()) {
+        base = sanitizeFilename(args.resultTitle);
+    }
+    else if (args.topic && Array.from(args.topic).length <= 60) {
+        base = sanitizeFilename(args.topic);
+    }
+    else if (args.fileStemFromAt) {
+        base = sanitizeFilename(args.fileStemFromAt);
+    }
+    return `${base || "reelforge"}-${shortId}.${ext}`;
+}
+async function validateOutputPath(out) {
+    if (out.endsWith("/") || out.endsWith("\\")) {
+        throw new Error(`-o must include a filename (got directory-only path: ${out}). Example: -o ./videos/space.mp4`);
+    }
+    try {
+        const stat = await fs.stat(out);
+        if (stat.isDirectory()) {
+            throw new Error(`-o must include a filename (path exists as a directory: ${out}). Example: -o ${out.replace(/[\\/]+$/, "")}/space.mp4`);
+        }
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+}
+function mergeWithNested(base, overlay) {
+    const merged = { ...base, ...overlay };
+    if (base.cover || overlay.cover) {
+        merged.cover = { ...base.cover, ...overlay.cover };
+    }
+    if (base.brand || overlay.brand) {
+        merged.brand = { ...base.brand, ...overlay.brand };
+    }
+    return merged;
+}
+function optsToBody(opts) {
+    const out = {};
+    if (opts.topic !== undefined)
+        out.topic = opts.topic;
+    if (opts.script !== undefined)
+        out.script = opts.script;
+    if (opts.title !== undefined)
+        out.title = opts.title;
+    if (opts.duration !== undefined)
+        out.duration = opts.duration;
+    if (opts.pace !== undefined)
+        out.pace = opts.pace;
+    if (opts.llmModel !== undefined)
+        out.llm_model = opts.llmModel;
+    if (opts.ttsModel !== undefined)
+        out.tts_model = opts.ttsModel;
+    if (opts.asrModel !== undefined)
+        out.asr_model = opts.asrModel;
+    if (opts.imageModel !== undefined)
+        out.image_model = opts.imageModel;
+    if (opts.promptPrefix !== undefined)
+        out.prompt_prefix = opts.promptPrefix;
+    if (opts.style !== undefined)
+        out.style = opts.style;
+    if (opts.characterRef !== undefined)
+        out.character_ref = opts.characterRef;
+    if (opts.voiceId !== undefined)
+        out.voice_id = opts.voiceId;
+    if (opts.ttsSpeed !== undefined)
+        out.tts_speed = opts.ttsSpeed;
+    if (opts.videoFps !== undefined)
+        out.video_fps = opts.videoFps;
+    if (opts.quality !== undefined)
+        out.quality = opts.quality;
+    if (opts.crf !== undefined && Number.isFinite(opts.crf))
+        out.crf = opts.crf;
+    if (opts.videoBitrate !== undefined)
+        out.video_bitrate = opts.videoBitrate;
+    if (opts.motion !== undefined)
+        out.motion = opts.motion;
+    if (opts.layout !== undefined)
+        out.layout = opts.layout;
+    if (opts.layoutMatteColor !== undefined)
+        out.layout_matte_color = opts.layoutMatteColor;
+    if (opts.mediaAnchorY !== undefined && Number.isFinite(opts.mediaAnchorY))
+        out.media_anchor_y = opts.mediaAnchorY;
+    if (opts.noBgm)
+        out.bgm_path = "";
+    else if (opts.bgm !== undefined)
+        out.bgm_path = opts.bgm;
+    if (opts.bgmVolume !== undefined && Number.isFinite(opts.bgmVolume))
+        out.bgm_volume = opts.bgmVolume;
+    if (opts.subtitleStyle !== undefined)
+        out.subtitle_style = opts.subtitleStyle;
+    if (opts.subtitleColor !== undefined)
+        out.subtitle_color = opts.subtitleColor;
+    if (opts.subtitleBackground !== undefined)
+        out.subtitle_background = opts.subtitleBackground;
+    if (opts.subtitleBottom !== undefined && Number.isFinite(opts.subtitleBottom))
+        out.subtitle_bottom_px = opts.subtitleBottom;
+    if (opts.components !== undefined)
+        out.image_only = !opts.components;
+    if (opts.theme !== undefined && opts.theme.trim())
+        out.theme = opts.theme.trim();
+    if (opts.subtitleTranslate !== undefined) {
+        const v = opts.subtitleTranslate.trim();
+        out.subtitle_translate_to = /^(off|none|no)$/i.test(v) ? "" : v;
+    }
+    const brand = {};
+    if (opts.brandHandle !== undefined)
+        brand.handle = opts.brandHandle;
+    if (opts.brandSlogan !== undefined)
+        brand.slogan = opts.brandSlogan;
+    if (opts.brandLogo !== undefined)
+        brand.logo_url = opts.brandLogo;
+    if (opts.brandPosition !== undefined)
+        brand.position = opts.brandPosition;
+    if (opts.brandColor !== undefined)
+        brand.color = opts.brandColor;
+    if (Object.keys(brand).length > 0)
+        out.brand = brand;
+    const cover = {};
+    if (opts.cover === false)
+        cover.enabled = false;
+    else if (opts.cover === true)
+        cover.enabled = true;
+    if (opts.coverTemplate !== undefined)
+        cover.template = opts.coverTemplate;
+    if (opts.coverTitle !== undefined)
+        cover.title = opts.coverTitle;
+    if (opts.coverSubtitle !== undefined)
+        cover.subtitle = opts.coverSubtitle;
+    if (opts.coverBadge !== undefined)
+        cover.badge = opts.coverBadge;
+    if (Object.keys(cover).length > 0)
+        out.cover = cover;
+    if (opts.segmentMinChars !== undefined)
+        out.segment_min_chars = opts.segmentMinChars;
+    if (opts.segmentMaxChars !== undefined)
+        out.segment_max_chars = opts.segmentMaxChars;
+    if (opts.previewOnly)
+        out.preview_only = true;
+    return out;
+}
+const STYLE_PRESET_META = [
+    { id: "cinematic", label: "电影感", scene: "故事 / 旅行 / 通用百搭" },
+    { id: "photorealistic", label: "写实棚拍", scene: "产品 / 人像 / 美食" },
+    { id: "documentary", label: "纪实新闻", scene: "历史 / 人物 / 纪录" },
+    { id: "flat", label: "扁平商业插画", scene: "财经 / 商业 / 数据科普" },
+    { id: "anime", label: "日漫", scene: "故事 / 二次元 / 年轻向" },
+    { id: "comic", label: "美漫", scene: "动作 / 英雄向 / 段子" },
+    { id: "watercolor", label: "水彩", scene: "治愈 / 情感 / 小红书风" },
+    { id: "oil-painting", label: "油画", scene: "文艺 / 古典 / 艺术史" },
+    { id: "ink", label: "中国水墨", scene: "中式叙事 / 古诗词 / 国风" },
+    { id: "3d-render", label: "三维渲染", scene: "科技 / 产品 / 未来 / 概念图" },
+    { id: "claymation", label: "黏土定格", scene: "儿童 / 萌系 / 治愈段子" },
+    { id: "low-poly", label: "低多边形", scene: "科技 / 概念 / 设计感" },
+    { id: "pixel", label: "像素", scene: "游戏 / 怀旧 / 段子" },
+    { id: "cyberpunk", label: "赛博朋克", scene: "科技未来 / 都市夜景" },
+    { id: "vaporwave", label: "蒸汽波", scene: "网络梗 / 怀旧 / 抽象审美" },
+    { id: "art-deco", label: "装饰艺术", scene: "奢华品牌 / 复古优雅" },
+    { id: "matchstick", label: "极简黑白火柴人", scene: "知识科普 / 哲思 / 段子" },
+];
+function displayWidth(s) {
+    let w = 0;
+    for (const c of s)
+        w += c.charCodeAt(0) > 0x7f ? 2 : 1;
+    return w;
+}
+function padDisplay(s, width) {
+    const pad = Math.max(0, width - displayWidth(s));
+    return s + " ".repeat(pad);
+}
+function formatStylePresetsList() {
+    const keyW = Math.max(...STYLE_PRESET_META.map((p) => p.id.length));
+    const labelW = Math.max(...STYLE_PRESET_META.map((p) => displayWidth(p.label)));
+    return STYLE_PRESET_META.map((p) => `  ${padDisplay(p.id, keyW)}  ${padDisplay(p.label, labelW)}  ${p.scene}`).join("\n");
+}
+export function registerCreate(program) {
+    program
+        .command("create [topic]")
+        .description("一键生成视频: 主题或自己的脚本 → 完整 MP4")
+        .helpOption("-h, --help", "show help")
+        .option("-t, --topic <text>", "video topic; AI writes the script (mode=generate). Prefix with @file to read from disk.")
+        .option("--script <text>", "your own master script text; AI just plans scenes + visuals (mode=fixed). Prefix with @file to read from disk.")
+        .option("--title <text>", "hard-override video title; LLM will NOT auto-summarize. Useful for compliance-sensitive content (e.g. financial). Prefix with @file to read from disk. Pass --title '' (empty string) to explicitly suppress title rendering. Omit to keep LLM auto-title.")
+        .option("-d, --duration <sec>", "target video duration in seconds (generate mode only; default 45). LLM aims for ~duration × 5 chars of narration.", (v) => parseInt(v, 10))
+        .option("-p, --pace <pace>", "visual rhythm hint passed to the LLM: slow | normal | fast (default normal). LLM still decides the actual scene count from semantic structure.")
+        .option("--image-model <id>", "image model (rx-image-z | rx-image-flux | rx-image-qwen | rx-image-qwen-edit). Auto-switches to the edit-capable model when --character-ref is set.")
+        .option("--prompt-prefix <text>", "raw style prefix prepended to every image prompt (overrides --style)")
+        .option("--style <preset>", "image style preset id — server-expanded. 用户不知道选哪个时,agent 应该先跑 `rf styles list --json` 把每个风格的 preview_url(同一灯塔在 17 种风格下的对比图)给用户看,让用户照图选。仅看 id 列表用户和你都猜不准实际出图长啥样")
+        .option("--character-ref <urlOrPath>", "reference image of the main character — locks identity across scenes. URL, data: URI, or local png/jpg/webp path (auto-encoded). Auto-enables the edit-capable image model.")
+        .option("--motion <preset>", "per-scene image animation intensity. See 'Motion presets' below. Default: lite.")
+        .option("--layout <preset>", "image layout within canvas: full (default) | blur-bg | letterbox. See 'Layout presets' below.")
+        .option("--layout-matte-color <css>", "letterbox matte color (CSS string, e.g. 'black', '#1a1a1a', '#2d3748'). Ignored unless --layout letterbox. Default: black.")
+        .option("--media-anchor-y <fraction>", "vertical anchor of the inner image square (blur-bg/letterbox only), 0..1. 0.5=centered (default); lower values push the square up to grow the bottom matte. Subtitle position follows the image automatically. See `rf platform <name>` for safe ranges per platform (抖音 / TikTok / 视频号). Ignored for --layout full.", (v) => Number(v))
+        .option("--bgm <path>", "background music file (relative or absolute). Omit to use the server's default (config.bgm.default_path → bgm/default.mp3).")
+        .option("--bgm-volume <0..1>", "BGM mix volume (0=silent, 1=full). Default 0.15 keeps narration intelligible.", (v) => Number(v))
+        .option("--no-bgm", "disable background music for this render")
+        .option("--subtitle-style <preset>", "subtitle visual style. See 'Subtitle styles' below. Default: plate.")
+        .option("--subtitle-color <css>", "override subtitle text color, e.g. '#ffeb3b'. Omit for preset default.")
+        .option("--subtitle-background <css>", "override plate-preset background, e.g. 'rgba(20,30,80,0.75)'. Other presets ignore.")
+        .option("--subtitle-bottom <px>", "override the subtitle bottom offset in px (default 400, the lower-third position). blur-bg/letterbox images move up to clear it.", (v) => parseInt(v, 10))
+        .option("--components", "render data COMPONENTS (charts / cards / terminals / kinetic numbers) for suitable scenes instead of only AI images (default: image-only). Pair with --theme to pick the look.")
+        .option("--theme <id>", "single visual theme for the whole video: neo-brutal | bloomberg | editorial | terminal | swiss | liquid-glass | y2k | neon | bauhaus | ios. Only used with --components. Omit → inferred from the script.")
+        .option("--subtitle-translate <lang>", "双语字幕:把每条字幕翻译成指定语言,以小一号文字显示在主字幕下方,如 'en'(英文)/ 'ja'(日文)。开启后字幕分段自动变短(主字幕保持单行)。默认:开(en);传 'off' 关闭(也可覆盖 recipe 设置)")
+        .option("--cover", "给视频加一张设计封面图作为首帧。抖音/TikTok/视频号默认抓取首帧当 9 宫格缩略图——加了 cover 在 feed 里更出挑;不加则首帧是 scene-01 + 字幕。也可由 recipe 自动启用(cover.enabled=true)。")
+        .option("--no-cover", "强制关闭封面,无视 recipe 设置")
+        .option("--cover-template <id>", "封面风格,共 9 个: paper-band(财经) | carbon-copy(哲思,默认) | chalkboard(教育) | book-spine(书单) | polaroid(生活/vlog) | recipe-card(美食) | spec-sheet(数码/汽车) | vintage-stamp(历史) | magazine(时尚/娱乐)。" +
+        "用户不确定选哪个时,agent 应该先跑 `rf cover templates --json` 把每个模板的 preview_url 给用户看,看完图再选")
+        .option("--cover-title <text>", "封面大标题(短句更佳,12 字内最稳)。不指定则用 --title 或 AI 自动生成的视频标题")
+        .option("--cover-subtitle <text>", "副标题/一句话标语。不是所有模板都显示 — 看 `rf cover templates --id <id>` 的 supports.subtitle 字段确认 (= true 才会渲染,否则静默忽略)")
+        .option("--cover-badge <text>", "角标/期号/紧急标,如 'EP.012' / '突发' / 'FLASH'。同样看 `rf cover templates --id <id>` 的 supports.badge 字段确认")
+        .option("--brand-handle <text>", "creator handle shown in corner, e.g. '@大灰狼'")
+        .option("--brand-slogan <text>", "creator slogan/tagline shown under handle")
+        .option("--brand-logo <urlOrPath>", "logo/avatar URL or local file path (PNG/JPG/WebP)")
+        .option("--brand-position <pos>", "where to render brand chrome: top-left | top-right | bottom-left | bottom-right")
+        .option("--brand-color <css>", "brand text color, e.g. '#ffffff' (default)")
+        .option("--voice-id <id>", "RelayX TTS voice id (default 专业解说); see `rf tts voices`")
+        .option("--tts-speed <n>", "speech speed 0.5..2 (default 1.0). Only honored by some TTS backends; the default cloud model ignores it.", parseFloat)
+        .option("--llm-model <id>", "override the LLM model used for scene-plan")
+        .option("--tts-model <id>", "override the TTS model (defaults to the server's)")
+        .option("--asr-model <id>", "override the ASR model (defaults to the server's)")
+        .option("--segment-min-chars <N>", "subtitle SEGMENT (分段) min chars (default 10). A segment is one on-screen subtitle unit, not a visual line — visual wrapping is automatic.", (v) => parseInt(v, 10))
+        .option("--segment-max-chars <N>", "subtitle SEGMENT (分段) max chars (default 28 ≈ 2 visual lines at 820px safe width). HTML clamps display to 2 lines + ellipsis.", (v) => parseInt(v, 10))
+        .option("--video-fps <n>", "output video fps (default 24 — cinema-standard, ~20% faster render vs 30; pass 30 if you want smoother motion)", (v) => parseInt(v, 10))
+        .option("--quality <preset>", "encoder quality preset: draft | standard (default) | high. draft shrinks output ~3-4× vs standard (~3 Mbps) at slight visible quality cost; high is the opposite. Mutually exclusive with --crf and --video-bitrate.")
+        .option("--crf <N>", "constant rate factor 0-51 (lower = higher quality). Bypasses --quality preset's bitrate choice. Mutually exclusive with --video-bitrate.", (v) => parseInt(v, 10))
+        .option("--video-bitrate <rate>", "目标视频码率,如 '750k' / '1M' / '2M'。用于命中文件大小预算。和 --crf 二选一。")
+        .option("--recipe <file>", "load defaults from a JSON recipe file (CLI flags still override)")
+        .option("--redo", "replay last successful create from ~/.reelforge/last-create.json")
+        .option("--dry-run", "print the final request body + estimated units; do NOT submit")
+        .option("--no-wait", "submit and return task_id immediately (do not poll)")
+        .option("-o, --output <file>", "save the final video to this exact path (must include filename, e.g. ./out/space.mp4).")
+        .option("--no-download", "do not save the video locally — just print JSON with video_url")
+        .option("--poll-ms <ms>", "poll interval while waiting", (v) => parseInt(v, 10), 1500)
+        .option("--timeout-ms <ms>", "max wait time before aborting (default unlimited)", (v) => parseInt(v, 10))
+        .option("--preview-only", "跳过 MP4 渲染,只出可预览的网页版并打印 URL — 最快的迭代回路。后续可用 `rf render <task-id>` 出 MP4。")
+        .addHelpText("after", [
+        "",
+        "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+        "何时用 rf create (AGENT 必读 — 选错命令是这个 CLI 最常见的失败模式)",
+        "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+        "✓ 用户给的是『主题 / 想法 / 一句话需求』 → -t \"<topic>\" (AI 全权出片)",
+        "✓ 用户给的是『自己写好的文案脚本』 → --script @file.txt",
+        "✓ 用户参考别人的视频/链接 → 先 `rf extract <url>` 拿到原文,agent 帮用户",
+        "  写好脚本,再 --script 喂给 create",
+        "",
+        "✗ 用户给的是『一堆现成视频/图片要拼接』 → 不要走这条!",
+        "    → `rf compositions concat ...` (低层 ffmpeg)",
+        "✗ Agent 想自定义每个 scene 的素材 → `rf compose <spec.json>` (EXPERIMENTAL)",
+        "",
+        "Two content modes (one is required):",
+        "  generate    AI writes the script.        --topic / -t <text>  + optional --duration -d",
+        "  fixed       You supply the script.       --script <text-or-@file>",
+        "",
+        "  Need to base a script on external material (PDF / 抖音 / web URL / GitHub / etc.)?",
+        "  Use `rf extract <source>` to parse it into text, compose your script in your agent /",
+        "  external LLM, then pass the result via --script. ReelForge does not compose scripts",
+        "  from references — that's an agent's job.",
+        "",
+        "Pace (visual rhythm hint to the LLM):",
+        "  slow    fewer scenes, glued to semantic boundaries",
+        "  normal  balance semantic edges with visual variety (default)",
+        "  fast    split long semantic chunks into multiple shots for variety",
+        "",
+        "Defaults:",
+        "  duration=45s · pace=normal · motion=lite · layout=blur-bg · subtitle-style=plate · tts-speed=1.0",
+        "",
+        "Motion presets (--motion <preset>) — per-scene image animation intensity:",
+        "  off     no motion, hard cuts between scenes — PPT / slideshow mode",
+        "  lite    6% zoom + 0.3s crossfade, 4 sub-anims (default; safe + tasteful)",
+        "  max     20% zoom/pan + 0.5s crossfade, 10 sub-anims (cinematic, more dramatic)",
+        "  · sub-animations are Fisher-Yates shuffled per task_id, so every video",
+        "    cycles a different order — no two videos feel identical.",
+        "",
+        "Layout presets (--layout <preset>) — how the AI image sits in the 1080×1920 canvas:",
+        "  full        image fills the whole canvas (default; high-impact, attention-grabbing).",
+        "              best for human portraits, landscapes, 9:16-native content.",
+        "  blur-bg     image at 1080×1080 centered, top/bottom is a gaussian-blurred copy",
+        "              of the same image — moves in sync with the foreground (小红书/抖音 style).",
+        "              best for charts, screenshots, infographics, non-9:16 source content.",
+        "  letterbox   image at 1080×1080 centered, top/bottom is a solid matte (cinematic).",
+        "              use --layout-matte-color to change (default 'black'; try '#1a1a1a' for less harsh).",
+        "  · The image generator is asked for the actual on-screen size (1080×1920 for full,",
+        "    1080×1080 for blur-bg/letterbox), so you don't pay for pixels that get cropped.",
+        "",
+        "Subtitle styles (--subtitle-style <preset>):",
+        "  plate    semi-transparent black plate + white text (CapCut default; safest readability)",
+        "  stroke   bold white text with black stroke + shadow, no plate (抖音网红风)",
+        "  cinema   bottom black gradient backdrop + lighter text (film / documentary look)",
+        "  · use --subtitle-color / --subtitle-background to override the preset's colors",
+        "    e.g. --subtitle-color '#ffeb3b' --subtitle-background 'rgba(20,30,80,0.75)'",
+        "",
+        "Brand chrome (--brand-* flags or config.video.default_brand):",
+        "  Adds a constant @handle / slogan / logo block in a frame corner.",
+        "  --brand-position bottom-right --brand-handle '@大灰狼' --brand-slogan '财经科普'",
+        "  --brand-logo accepts URL / data: URI / local png/jpg/webp path.",
+        "  All fields optional; missing handle/slogan/logo are individually hidden.",
+        "  Per-request flags merge over config defaults field by field.",
+        "",
+        "Preview-only 模式 (--preview-only):",
+        "  跳过 MP4 渲染,只出网页可预览版。CLI 会打印 preview URL(studio 页 + 纯",
+        "  播放器页),自己在浏览器里打开看效果迭代,定型再用",
+        "  `rf render <task-id>` 出 MP4 — 比每次都等 MP4 出来快得多。",
+        "",
+        "Image style presets (--style <preset>) — server expands id → prompt prefix:",
+        formatStylePresetsList(),
+        "  · Pass --prompt-prefix to override with a custom string (always wins).",
+        "  · Omit both to let the LLM pick a per-video style automatically.",
+        "  · Run `rf styles list` to query the server's live catalog.",
+        "",
+        "Output behavior:",
+        "  No flag       → saves to ./<title>-<task_id>.mp4 in current directory, prints the path",
+        "  -o <path>     → saves to that exact path (must include filename)",
+        "  --no-download → skips local save, just prints JSON result with video_url",
+        "  (when stdout is piped, --no-download is implied automatically)",
+        "",
+        "Examples (`rf` is the short alias):",
+        "  # Minimum — AI writes a 45s script",
+        ' rf create "为什么我们还没找到外星文明？"',
+        "",
+        "  # 60-second video with slow visual pace",
+        ' rf create "..." -d 60 -p slow',
+        "",
+        "  # Your own script, you decide the wording",
+        " rf create --script @./script.txt",
+        ' rf create --script "整段文案文本..."',
+        "",
+        "  # Reference-based scripts — extract first, then create:",
+        " rf extract https://v.douyin.com/XXXX/ -o /tmp/ref.txt   # parse anything → text",
+        " #   (agent / your LLM composes the script using /tmp/ref.txt as raw material)",
+        " rf create --script @final.txt -d 60                     # render the result",
+        "",
+        "  # Pick a built-in image style preset",
+        ' rf create "..." --style cinematic',
+        "",
+        "  # Cross-scene character consistency (auto-switches image model)",
+        ' rf create "主角小女孩的一天" --character-ref ./hero.png',
+        ' rf create "..." --character-ref https://example.com/hero.png',
+        "",
+        "  # Motion + subtitle style combos",
+        ' rf create "..." --motion max --subtitle-style stroke    # 抖音网红风',
+        ' rf create "..." --motion lite --subtitle-style cinema   # 文艺纪录片',
+        ' rf create "..." --motion off                            # PPT 模式（旧行为）',
+        "",
+        "  # Layout combos",
+        ' rf create "财经日报" --layout blur-bg                       # 小红书 / 抖音 风（图表内容首选）',
+        ' rf create "纪录片片段" --layout letterbox --motion max       # 电影感',
+        ' rf create "..." --layout letterbox --layout-matte-color "#1a1a1a"  # 柔和黑',
+        "",
+        "  # Preview ladder",
+        ' rf create "..." --preview-only        # ~2min, ~$0.05 — prints preview URL, no MP4',
+        ' rf create "..."                       # ~5min, ~$0.20 — full MP4',
+        " rf render <task-id>                   # finalize MP4 from a preview-only task",
+        "",
+        "  # Recipe + replay last",
+        " rf create --recipe ./space.recipe.json",
+        " rf create --redo                       # replay last successful create",
+        " rf create --redo -p fast               # replay with one knob tweaked",
+        "",
+        "  # See exactly what would be sent (no submission)",
+        ' rf create "..." -d 60 --dry-run',
+        "",
+        "  # Pipe-friendly",
+        ' rf create "..." --no-download --json | jq -r .video_url',
+    ].join("\n"))
+        .action(async (topicArg, opts) => {
+        if (opts.output) {
+            await validateOutputPath(opts.output);
+        }
+        if (opts.style && !STYLE_PRESET_META.some((p) => p.id === opts.style)) {
+            throw new Error(`Unknown --style: ${opts.style}\n` +
+                `Available presets (this CLI):\n${formatStylePresetsList()}\n` +
+                `For the server's live catalog: rf styles list`);
+        }
+        if (opts.pace && !["slow", "normal", "fast"].includes(opts.pace)) {
+            throw new Error(`--pace must be one of slow|normal|fast (got: ${opts.pace})`);
+        }
+        if (opts.motion && !["off", "lite", "max"].includes(opts.motion)) {
+            throw new Error(`--motion must be one of off|lite|max (got: ${opts.motion})`);
+        }
+        if (opts.layout && !["full", "blur-bg", "letterbox"].includes(opts.layout)) {
+            throw new Error(`--layout must be one of full|blur-bg|letterbox (got: ${opts.layout})`);
+        }
+        if (opts.subtitleStyle && !["plate", "stroke", "cinema"].includes(opts.subtitleStyle)) {
+            throw new Error(`--subtitle-style must be one of plate|stroke|cinema (got: ${opts.subtitleStyle})`);
+        }
+        if (opts.brandPosition && !["top-left", "top-right", "bottom-left", "bottom-right"].includes(opts.brandPosition)) {
+            throw new Error(`--brand-position must be one of top-left|top-right|bottom-left|bottom-right (got: ${opts.brandPosition})`);
+        }
+        if (opts.ttsSpeed !== undefined &&
+            (!opts.ttsModel || opts.ttsModel.startsWith("vox/"))) {
+            const m = opts.ttsModel || "default";
+            warn(`--tts-speed=${opts.ttsSpeed} will be ignored by TTS model "${m}". Speed control is only honored by Edge-TTS-backed models.`);
+        }
+        let body = {};
+        if (opts.redo) {
+            const last = await loadLastCreate();
+            if (!last) {
+                throw new Error(`--redo: no previous create found at ${LAST_CREATE_PATH}. Run at least one successful create first.`);
+            }
+            body = { ...last };
+            info(`Loaded last create from ${LAST_CREATE_PATH}`);
+        }
+        if (opts.recipe) {
+            const recipe = await loadRecipe(opts.recipe);
+            body = mergeWithNested(body, recipe);
+            info(`Loaded recipe from ${opts.recipe}`);
+        }
+        const fromOpts = optsToBody(opts);
+        body = mergeWithNested(body, fromOpts);
+        const rawTopicInput = topicArg ?? (typeof body.topic === "string" ? body.topic : undefined);
+        const fileStemFromAt = rawTopicInput?.startsWith("@") ? path.parse(rawTopicInput.slice(1)).name :
+            body.script?.startsWith("@") ? path.parse(body.script.slice(1)).name :
+                undefined;
+        if (topicArg) {
+            body.topic = await resolveTextOrFile(topicArg);
+        }
+        else if (typeof body.topic === "string") {
+            body.topic = await resolveTextOrFile(body.topic);
+        }
+        if (typeof body.script === "string") {
+            body.script = await resolveTextOrFile(body.script);
+        }
+        if (typeof body.title === "string" && body.title.startsWith("@")) {
+            body.title = await resolveTextOrFile(body.title);
+        }
+        const legacy = body;
+        const legacyKeys = ["reference", "reference_url", "instruct", "script_only"]
+            .filter((k) => legacy[k] !== undefined);
+        if (legacyKeys.length > 0) {
+            throw new Error(`Removed in 1.6.0: ${legacyKeys.join(", ")}. ` +
+                "Script composition from external material now lives in your agent / LLM.\n" +
+                "Migration:\n" +
+                "  rf extract <source> -o /tmp/ref.txt        # parse PDF / URL / 抖音 / GitHub / ...\n" +
+                "  # (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;
+        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 hasTopic = typeof body.topic === "string" && body.topic.trim().length > 0;
+        const hasScript = typeof body.script === "string" && body.script.trim().length > 0;
+        const contentCount = (hasTopic ? 1 : 0) + (hasScript ? 1 : 0);
+        if (contentCount === 0) {
+            throw new Error("one of --topic (or positional arg) or --script is required.");
+        }
+        if (contentCount > 1) {
+            throw new Error("--topic and --script are mutually exclusive (pick one).");
+        }
+        const finalBody = { ...body };
+        const estimate = estimateCostUsd(finalBody);
+        if (opts.dryRun) {
+            info("--- DRY RUN ---");
+            info("Final request body:");
+            print(finalBody);
+            info(`Estimated cost: ≈ ${formatUsd(estimate)}`);
+            info("(use without --dry-run to actually submit)");
+            return;
+        }
+        info(`Submitting create task (≈ ${formatUsd(estimate)})...`);
+        const submitted = await post("/api/v1/pipelines/standard", finalBody);
+        await saveLastCreate(finalBody).catch((e) => {
+            warn(`Could not save last-create.json: ${e.message}`);
+        });
+        if (opts.wait === false) {
+            print({ task_id: submitted.task_id, status: submitted.status });
+            return;
+        }
+        info(`Task submitted: ${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;
+        const serverBase = getServer().replace(/\/+$/, "");
+        const previewPageAbs = result?.preview_urls?.page ? serverBase + result.preview_urls.page : undefined;
+        const previewPlayerAbs = result?.preview_urls?.player ? serverBase + result.preview_urls.player : undefined;
+        if (previewPageAbs) {
+            info(`预览页 (全功能): ${previewPageAbs}`);
+        }
+        if (previewPlayerAbs) {
+            info(`纯播放器:    ${previewPlayerAbs}`);
+        }
+        if (result?.render_pending) {
+            info(`MP4 渲染未触发 (preview-only)。完成后用 \`rf render ${t.id}\` 生成。`);
+        }
+        else if (result?.video_url) {
+            const stdoutIsPipe = !process.stdout.isTTY;
+            const skipDownload = !!opts.noDownload || (stdoutIsPipe && !opts.output);
+            let savedPath;
+            if (opts.output) {
+                savedPath = opts.output;
+            }
+            else if (!skipDownload) {
+                const topicForFilename = hasTopic && finalBody.topic ? finalBody.topic : undefined;
+                savedPath = computeDefaultFilename({
+                    resultTitle: result.title,
+                    topic: topicForFilename,
+                    fileStemFromAt,
+                    taskId: t.id,
+                    ext: "mp4",
+                });
+            }
+            if (savedPath) {
+                await downloadTo(result.video_url, savedPath);
+                success(`Saved → ${savedPath}`);
+            }
+        }
+        if (result?.generation_ms != null) {
+            const gen = humanDuration(result.generation_ms);
+            const playback = result.duration != null ? `，视频时长 ${result.duration.toFixed(1)}s` : "";
+            info(`本次生成耗时 ${gen}${playback}`);
+        }
+        if (result?.price_usd != null) {
+            info(`本次扣费 ${formatUsd(result.price_usd)}`);
+        }
+        print({ task_id: t.id, status: t.status, ...result });
+    });
+}