reelforge 1.24.3 → 1.25.0

package/dist/commands/subtitles.js

@@ -1,246 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { getApiKey, getServer, post } from "../client.js";
-import { info, print, success } from "../utils/output.js";
-export function registerSubtitles(program) {
-    const sub = program
-        .command("subtitles")
-        .alias("subtitle")
-        .description("字幕原子能力: split (确定性 token-atomic 分段, 单条/批量) + translate (双语第二行) + ledger (历史切分质量数据)")
-        .helpOption("-h, --help", "show help");
-    sub
-        .command("split")
-        .description("把文本切成字幕分段 (分段). 单条 (--text) 或批量分镜列表 (--scenes). 与线上视频 pipeline 同一个切分器。")
-        .helpOption("-h, --help", "show help")
-        .option("-t, --text <text>", "单条: 要切分的文本. 用 @file 从磁盘读。")
-        .option("-S, --scenes <input>", "批量: 分镜列表. JSON 字符串数组 / [{text}] / storyboard.json ({scenes:[{text}]}). 用 @file。")
-        .option("--bilingual", "双语模式: min/max 缺省时用 6/14 (而非单语 10/28), 与线上双语视频一致")
-        .option("--min <N>", "最小分段字数 (缺省: 单语 10 / 双语 6)", (v) => parseInt(v, 10))
-        .option("--max <N>", "最大分段字数 (缺省: 单语 28 / 双语 14 ≈ 2/1 视觉行)", (v) => parseInt(v, 10))
-        .addHelpText("after", [
-        "",
-        "Segment vs line:",
-        "  一个 segment 是一条上屏字幕单元 (一张 PNG / 一个时间窗), 不是视觉行。",
-        "  视觉换行是模板的事 (默认 clamp 2 行)。",
-        "",
-        "Examples:",
-        "  # 单条",
-        "  rf subtitles split -t '雨水缓缓滑落在玻璃窗上，像是无声的泪珠。'",
-        "",
-        "  # 批量: 一个分镜列表 → 二级 list (每个分镜一组字幕分段)",
-        "  rf subtitles split --scenes '[\"第一镜旁白\",\"第二镜旁白\"]' --json",
-        "",
-        "  # 直接喂真实 storyboard.json (取 scenes[].text), 双语参数验证线上切分",
-        "  rf subtitles split --scenes @storyboard.json --bilingual --json",
-    ].join("\n"))
-        .action(async (opts) => {
-        const body = {};
-        if (opts.min !== undefined)
-            body.min_chars = opts.min;
-        if (opts.max !== undefined)
-            body.max_chars = opts.max;
-        if (opts.bilingual)
-            body.bilingual = true;
-        if (opts.scenes) {
-            body.scenes = await parseScenesInput(await readInput(opts.scenes));
-            const r = await post("/api/v1/subtitles/split", body);
-            print({
-                scene_count: r.scene_count,
-                scenes: r.scenes.map((s, i) => ({
-                    scene: i,
-                    count: s.count,
-                    segments: s.segments.map((g) => g.text),
-                })),
-            });
-            return;
-        }
-        if (!opts.text)
-            throw new Error("提供 --text (单条) 或 --scenes (批量) 其一");
-        let text = opts.text;
-        if (text.startsWith("@"))
-            text = (await fs.readFile(text.slice(1), "utf-8")).trim();
-        body.text = text;
-        const r = await post("/api/v1/subtitles/split", body);
-        print({ count: r.count, segments: r.segments });
-    });
-    sub
-        .command("translate")
-        .description("字幕分段翻译 (双语字幕第二行). 接受一个分段数组 + 目标语言, 返回一一对应的译文。")
-        .helpOption("-h, --help", "show help")
-        .option("-s, --segments <input>", "字幕分段数组. 支持: @file (JSON 数组 或每行一段) / JSON 字符串 / 多段用 \\n 分隔")
-        .option("--from-split <input>", "直接接 rf subtitles split 的 JSON 输出 (file 或 stdin) — 自动提取 segments 字段")
-        .option("-l, --lang <code>", "目标语言, 如 en / ja / English / 日本語 (必填)")
-        .option("--master <text>", "完整旁白脚本 (上下文, 帮助术语一致). @file 读文件。可选, 缺省用 segments 拼接")
-        .option("--llm-model <id>", "覆盖默认 LLM 模型")
-        .addHelpText("after", [
-        "",
-        "Input 三种形式:",
-        "  --segments @file.json        分段 JSON 数组",
-        "  --segments @lines.txt        每行一段",
-        "  --from-split @split.json     rf subtitles split 的输出直接喂进来",
-        "",
-        "Examples:",
-        "  # 直接给分段数组",
-        "  rf subtitles translate -s '[\"第一段\",\"第二段\"]' -l en",
-        "",
-        "  # 链式: split → translate (agent 工作流)",
-        "  rf subtitles split -t @./script.txt --json > /tmp/segs.json",
-        "  rf subtitles translate --from-split @/tmp/segs.json -l en",
-        "",
-        "  # 加完整 master 让术语一致",
-        "  rf subtitles translate --from-split @/tmp/segs.json -l ja --master @/tmp/script.txt",
-        "",
-        "成本估算: 单次 LLM 调用 (~$0.001-0.003 取决于段数 + 模型)",
-    ].join("\n"))
-        .action(async (opts) => {
-        if (!opts.lang)
-            throw new Error("--lang is required (e.g. en, ja, English)");
-        let segments;
-        if (opts.fromSplit) {
-            const raw = await readInput(opts.fromSplit);
-            const parsed = JSON.parse(raw);
-            const arr = Array.isArray(parsed?.segments) ? parsed.segments : parsed;
-            if (!Array.isArray(arr)) {
-                throw new Error("--from-split: expected an object with `segments` array or a bare array");
-            }
-            segments = arr.map((s) => typeof s === "string" ? s : (s?.text ?? "")).filter((s) => s.length > 0);
-        }
-        else if (opts.segments) {
-            const raw = await readInput(opts.segments);
-            segments = parseSegmentsInput(raw);
-        }
-        else {
-            throw new Error("--segments or --from-split is required");
-        }
-        if (segments.length === 0)
-            throw new Error("no segments to translate");
-        let master;
-        if (opts.master) {
-            master = await readInput(opts.master);
-        }
-        const body = {
-            segments,
-            target_lang: opts.lang,
-        };
-        if (master)
-            body.master_script = master;
-        if (opts.llmModel)
-            body.llm_model = opts.llmModel;
-        const r = await post("/api/v1/subtitles/translate", body);
-        print({
-            count: r.translations.length,
-            translations: r.translations.map((t, i) => ({
-                id: i + 1,
-                src: segments[i],
-                translated: t,
-            })),
-            cost_usd: r.cost_usd,
-            duration_ms: r.duration_ms,
-        });
-    });
-    const ledger = sub
-        .command("ledger")
-        .description("Production subtitle ledger (每段字幕一行 JSONL,跨任务汇总)")
-        .helpOption("-h, --help", "show help");
-    ledger
-        .command("dump")
-        .description("从服务器下载字幕 ledger 到本地 JSONL 用于离线分析(每段一行,含切分质量评分)")
-        .helpOption("-h, --help", "show help")
-        .option("--since <iso>", "只拉 ts >= 这个时间的记录(ISO 8601,如 2026-06-01 或 2026-06-01T00:00:00Z)")
-        .option("--until <iso>", "只拉 ts <= 这个时间的记录")
-        .option("--task-id <id>", "只拉某一个 task 的记录")
-        .option("--limit <n>", "最多拉多少条(默认 10000, 上限 100000)", (v) => parseInt(v, 10))
-        .option("-o, --output <file>", "输出文件路径(默认 ./subtitle-ledger.jsonl)", "./subtitle-ledger.jsonl")
-        .addHelpText("after", [
-        "",
-        "字段:",
-        "  ts / task_id / scene_idx / seg_idx       数据点定位",
-        "  input_text                                该 scene 切分前完整文本",
-        "  display_text / text_secondary             实际上字幕的文字 + 译文",
-        "  length / start_sec / end_sec              出现时长",
-        "  cut_reason                                llm | tail | fallback-*",
-        "  split_score (0-100)                       该 scene LLM 切分评分",
-        "  split_attempts / split_source             重试次数 / llm or fallback",
-        "  splitter_version / llm_model              生成这条记录的版本组合",
-        "  subtitle_translate_to                     en / null / 等",
-        "",
-        "Examples:",
-        "  # 全量(上限 10000)",
-        "  rf subtitles ledger dump -o ./ledger.jsonl",
-        "",
-        "  # 只看最近一周",
-        "  rf subtitles ledger dump --since 2026-06-01 -o ./recent.jsonl",
-        "",
-        "  # 单个 task 复盘",
-        "  rf subtitles ledger dump --task-id 0eebc40f -o ./one-task.jsonl",
-        "",
-        "拉完后用 jq / awk / 自己写脚本分析。常见查询:",
-        "  jq 'select(.split_score < 80)' ledger.jsonl     # 低质量 case",
-        "  jq 'select(.length > 25)' ledger.jsonl          # 偏长 segment",
-        "  jq -s 'group_by(.task_id) | length' ledger.jsonl  # task 数",
-    ].join("\n"))
-        .action(async (opts) => {
-        const server = getServer().replace(/\/+$/, "");
-        const apiKey = getApiKey();
-        const qs = new URLSearchParams({ format: "jsonl" });
-        if (opts.since)
-            qs.set("since", opts.since);
-        if (opts.until)
-            qs.set("until", opts.until);
-        if (opts.taskId)
-            qs.set("task_id", opts.taskId);
-        if (opts.limit)
-            qs.set("limit", String(opts.limit));
-        const headers = {};
-        if (apiKey)
-            headers["authorization"] = `Bearer ${apiKey}`;
-        info(`Fetching ledger from ${server}/api/v1/subtitles/ledger?${qs.toString()}`);
-        const resp = await fetch(`${server}/api/v1/subtitles/ledger?${qs.toString()}`, { headers });
-        if (!resp.ok) {
-            const text = await resp.text().catch(() => "");
-            throw new Error(`Ledger fetch failed: HTTP ${resp.status}\n${text.slice(0, 500)}`);
-        }
-        const text = await resp.text();
-        const count = parseInt(resp.headers.get("x-ledger-count") || "0", 10);
-        const totalBytes = parseInt(resp.headers.get("x-ledger-bytes") || "0", 10);
-        const outAbs = path.resolve(opts.output);
-        await fs.mkdir(path.dirname(outAbs), { recursive: true });
-        await fs.writeFile(outAbs, text);
-        success(`Saved ${count} entries → ${outAbs}  ` +
-            `(${(text.length / 1024).toFixed(1)} KB; server ledger size: ${(totalBytes / 1024).toFixed(1)} KB)`);
-    });
-}
-async function readInput(input) {
-    if (input.startsWith("@")) {
-        return (await fs.readFile(input.slice(1), "utf-8")).trim();
-    }
-    return input;
-}
-async function parseScenesInput(raw) {
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new Error("--scenes 必须是 JSON (数组 或 含 scenes 数组的对象, 如 storyboard.json)");
-    }
-    const arr = Array.isArray(parsed)
-        ? parsed
-        : Array.isArray(parsed?.scenes)
-            ? parsed.scenes
-            : null;
-    if (!arr)
-        throw new Error("--scenes: 期望 JSON 数组, 或含 `scenes` 数组的对象 (storyboard.json)");
-    return arr.map((s) => ({ text: typeof s === "string" ? s : (s?.text ?? "") }));
-}
-function parseSegmentsInput(raw) {
-    const trimmed = raw.trim();
-    if (trimmed.startsWith("[")) {
-        const parsed = JSON.parse(trimmed);
-        if (!Array.isArray(parsed))
-            throw new Error("--segments JSON must be an array");
-        return parsed.filter((s) => typeof s === "string" && s.length > 0);
-    }
-    const unescaped = trimmed.replace(/\\n/g, "\n");
-    return unescaped.split("\n").map((s) => s.trim()).filter(Boolean);
-}

package/dist/commands/tasks.js

@@ -1,59 +0,0 @@
-import { del, get } from "../client.js";
-import { waitForTask } from "../utils/task-waiter.js";
-import { print, table } from "../utils/output.js";
-export function registerTasks(program) {
-    const tasks = program
-        .command("tasks")
-        .alias("task")
-        .description("任务队列管理: 查看 / 等待 / 取消")
-        .helpOption("-h, --help", "show help");
-    tasks
-        .command("list")
-        .description("List recent tasks")
-        .helpOption("-h, --help", "show help")
-        .option("--status <s>", "filter by status: pending | running | completed | failed | cancelled")
-        .option("--limit <n>", "max number of tasks", parseInt)
-        .action(async (opts) => {
-        const qs = new URLSearchParams();
-        if (opts.status)
-            qs.set("status", opts.status);
-        if (opts.limit)
-            qs.set("limit", String(opts.limit));
-        const r = await get(`/api/v1/tasks${qs.toString() ? `?${qs}` : ""}`);
-        table(r.tasks.map((t) => ({
-            id: t.id.slice(0, 8),
-            kind: t.kind,
-            status: t.status,
-            progress: `${(t.progress * 100).toFixed(0)}%`,
-            created_at: t.created_at,
-        })));
-    });
-    tasks
-        .command("get <id>")
-        .description("Show full task detail (status, progress, events, result)")
-        .helpOption("-h, --help", "show help")
-        .action(async (id) => {
-        const r = await get(`/api/v1/tasks/${id}`);
-        print(r);
-    });
-    tasks
-        .command("wait <id>")
-        .description("Poll a task until it reaches a terminal state (live progress on stderr)")
-        .helpOption("-h, --help", "show help")
-        .option("--poll-ms <ms>", "poll interval", parseInt, 1500)
-        .option("--timeout-ms <ms>", "max wait time", parseInt)
-        .action(async (id, opts) => {
-        const t = await waitForTask(id, { pollMs: opts.pollMs, timeoutMs: opts.timeoutMs });
-        print({ id: t.id, status: t.status, error: t.error, result: t.result });
-        if (t.status !== "completed")
-            process.exit(1);
-    });
-    tasks
-        .command("cancel <id>")
-        .description("Cancel a running task")
-        .helpOption("-h, --help", "show help")
-        .action(async (id) => {
-        const r = await del(`/api/v1/tasks/${id}`);
-        print(r);
-    });
-}

package/dist/commands/tts.js

@@ -1,134 +0,0 @@
-import { get, post } from "../client.js";
-import { downloadTo } from "../utils/download.js";
-import { print, table, success } from "../utils/output.js";
-const DEFAULT_RELAYX_TTS_MODEL = "vox/index-tts-2";
-export function registerTts(program) {
-    const tts = program
-        .command("tts")
-        .description("语音合成 (TTS): 本地 (免费) / 云端")
-        .helpOption("-h, --help", "显示帮助");
-    tts
-        .command("edge")
-        .description("用本地引擎合成语音 (免费, 不联外网)")
-        .helpOption("-h, --help", "显示帮助")
-        .requiredOption("-t, --text <text>", "要合成的文本")
-        .option("--voice <id>", "音色 id (例: zh-CN-YunjianNeural / en-US-AriaNeural)", "zh-CN-YunjianNeural")
-        .option("--speed <n>", "语速倍率 (0.5..2)", parseFloat, 1.2)
-        .option("--rate <rate>", "原生 rate 字符串, 如 '+30%' (覆盖 --speed)")
-        .option("-o, --output <file>", "保存音频到指定路径")
-        .addHelpText("after", [
-        "",
-        "示例:",
-        "  rf tts edge -t '你好' --voice zh-CN-XiaoxiaoNeural -o hello.mp3",
-        "  rf tts edge -t 'hello' --voice en-US-AriaNeural --speed 1.4 -o out.mp3",
-        "",
-        "查看可用 voices: `rf tts voices` (按 locale 过滤: `--locale zh`)",
-    ].join("\n"))
-        .action(async (opts) => {
-        const body = { text: opts.text };
-        if (opts.voice)
-            body.voice = opts.voice;
-        if (opts.speed !== undefined)
-            body.speed = opts.speed;
-        if (opts.rate)
-            body.rate = opts.rate;
-        const r = await post("/api/v1/tts/edge", body);
-        if (opts.output) {
-            await downloadTo(r.url, opts.output);
-            success(`Saved → ${opts.output} (${r.size_bytes} bytes, voice=${r.voice}, rate=${r.rate})`);
-        }
-        print({ ok: r.ok, voice: r.voice, rate: r.rate, size_bytes: r.size_bytes, file_path: r.file_path, url: r.url, downloaded_to: opts.output || null });
-    });
-    tts
-        .command("relayx")
-        .description("用云端 TTS 合成语音 (149 个内置音色)")
-        .helpOption("-h, --help", "显示帮助")
-        .requiredOption("-t, --text <text>", "要合成的文本")
-        .option("-m, --model <id>", "TTS 模型 id (默认云端模型)")
-        .option("--voice <id>", "音色 id (默认: 专业解说)")
-        .option("--speed <n>", "语速倍率 (0.5..2)", parseFloat)
-        .option("-o, --output <file>", "保存音频到指定路径")
-        .addHelpText("after", [
-        "",
-        "示例:",
-        "  rf tts relayx -t '你好世界' --voice '专业解说' -o hello.mp3",
-        "  rf tts relayx -t '...' --voice '熊小二' --speed 1.1 -o out.mp3",
-        "",
-        "查看可用 voices: `rf tts voices` (默认这 149 个) /",
-        "                 `rf tts voices --model <其他 SKU>`",
-    ].join("\n"))
-        .action(async (opts) => {
-        const body = { text: opts.text };
-        if (opts.model)
-            body.model = opts.model;
-        if (opts.voice)
-            body.voice = opts.voice;
-        if (opts.speed !== undefined)
-            body.speed = opts.speed;
-        const r = await post("/api/v1/tts/relayx", body);
-        if (opts.output) {
-            await downloadTo(r.url, opts.output);
-            success(`Saved → ${opts.output} (${r.size_bytes} bytes, model=${r.model}, voice=${r.voice})`);
-        }
-        print(r);
-    });
-    tts
-        .command("voices")
-        .description("列出可用音色 (本地 + 云端, 共 ~170+)")
-        .helpOption("-h, --help", "显示帮助")
-        .option("--provider <p>", "edge | relayx | all (默认: all,即两者都列)", "all")
-        .option("--model <id>", "云端模型 id (默认云端模型; 例: <SKU>)")
-        .option("--locale <prefix>", "本地引擎才有: 按 locale 前缀过滤, 如 zh / en-US")
-        .option("--refresh", "云端才有: 跳过 5 分钟服务端缓存")
-        .addHelpText("after", [
-        "",
-        "示例:",
-        "  rf tts voices                                  # 本地 + 云端,合计 ~174",
-        "  rf tts voices --provider edge                   # 只看本地",
-        "  rf tts voices --provider edge --locale zh       # 本地中文音色",
-        "  rf tts voices --provider relayx                 # 只看云端 (149)",
-        "  rf tts voices --model <SKU>                      # 换个云端 SKU",
-        "",
-        "默认 --provider=all 同时列两边,本地用 locale 区分语种,云端用 voice id 选择。",
-    ].join("\n"))
-        .action(async (opts) => {
-        const provider = (opts.provider || "all").toLowerCase();
-        const model = opts.model || DEFAULT_RELAYX_TTS_MODEL;
-        async function fetchEdge() {
-            const r = await get("/api/v1/tts/voices?provider=edge");
-            let voices = r.voices;
-            if (opts.locale)
-                voices = voices.filter((v) => v.locale.startsWith(opts.locale));
-            return voices.map((v) => ({ provider: "edge", model: "edge", id: v.id, label: v.label, locale: v.locale, gender: v.gender, featured: "" }));
-        }
-        async function fetchRelayx() {
-            const qs = new URLSearchParams({ provider: "relayx", model });
-            if (opts.refresh)
-                qs.set("refresh", "1");
-            const r = await get(`/api/v1/tts/voices?${qs.toString()}`);
-            return r.voices.map((v) => ({
-                provider: "relayx",
-                model,
-                id: v.id,
-                label: v.label,
-                locale: "",
-                gender: "",
-                featured: v.featured ? "★" : "",
-            }));
-        }
-        if (provider === "edge") {
-            table(await fetchEdge());
-            return;
-        }
-        if (provider === "relayx") {
-            table(await fetchRelayx());
-            return;
-        }
-        if (provider === "all") {
-            const [edgeVoices, relayxVoices] = await Promise.all([fetchEdge(), fetchRelayx()]);
-            table([...edgeVoices, ...relayxVoices]);
-            return;
-        }
-        throw new Error(`未知的 --provider: ${provider} (应为 edge / relayx / all)`);
-    });
-}

package/dist/commands/vlog.js

@@ -1,91 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const VERTICALS = [
-    {
-        id: "pet",
-        label: "宠物第一视角搞笑 vlog",
-        blurb: "用户拍的猫狗图 / 视频 + 一句话 → 宠物第一人称搞笑竖屏短视频",
-    },
-    {
-        id: "general",
-        label: "通用素材→视频(兜底)",
-        blurb: "没有更专门赛道时的通用 SOP:做饭 / 旅行 / 日常 vlog / 开箱等临时场景都走这里",
-    },
-];
-function loadPlaybook(id) {
-    const candidates = [
-        path.resolve(__dirname, "../data/vlog", `${id}.md`),
-        path.resolve(__dirname, "../../../docs/vlog", `${id}.md`),
-    ];
-    for (const p of candidates) {
-        try {
-            return fs.readFileSync(p, "utf8");
-        }
-        catch {
-        }
-    }
-    return null;
-}
-function indexText() {
-    const lines = [
-        "rf vlog — 用素材做视频的「赛道剧本」(给 agent 读的 use-case SOP)",
-        "",
-        "底层能力是 `rf assets describe`(看素材) + `rf compose`(渲染);本命名空间只给",
-        "「怎么把一条赛道落地」的引导。写旁白是 agent 的活,引擎不替写。",
-        "",
-        "可用赛道:",
-    ];
-    for (const v of VERTICALS) {
-        lines.push(`  ${v.id.padEnd(8)} ${v.label}`);
-        lines.push(`  ${" ".repeat(8)} ${v.blurb}`);
-    }
-    lines.push("");
-    lines.push("挑选规则:有贴合的垂类就用垂类;没有 → 用 general 兜底。");
-    lines.push("");
-    lines.push("用法:");
-    lines.push("  rf vlog <id>           打印某赛道完整剧本(SOP),如 `rf vlog pet`");
-    lines.push("  rf vlog general        通用 SOP(临时 / 没专门赛道的场景)");
-    lines.push("  rf vlog <id> | less    分页浏览");
-    return lines.join("\n");
-}
-export function registerVlog(program) {
-    const cmd = program
-        .command("vlog")
-        .description("素材→视频 垂类剧本 (给 agent 读的 use-case SOP;底层用 rf assets describe + rf compose)")
-        .helpOption("-h, --help", "show help")
-        .action(() => {
-        process.stdout.write(indexText() + "\n");
-    });
-    for (const v of VERTICALS) {
-        cmd
-            .command(v.id)
-            .description(`打印「${v.label}」完整剧本 (SOP) 到 stdout`)
-            .helpOption("-h, --help", "show help")
-            .addHelpText("after", ["", `不带 -h 直接运行 \`rf vlog ${v.id}\` 打印完整剧本。`, "适合 agent 启动时一次性读入。"].join("\n"))
-            .action(() => {
-            const text = loadPlaybook(v.id);
-            if (text) {
-                process.stdout.write(text);
-                if (!text.endsWith("\n"))
-                    process.stdout.write("\n");
-                return;
-            }
-            process.stdout.write([
-                `# rf vlog · ${v.label}`,
-                "",
-                "(本机未找到完整剧本文件;可能是旧版安装。)",
-                "核心流程:",
-                "  1. rf assets describe ./素材目录/ -o assets.json   # 让 agent 看懂素材",
-                "  2. agent 基于真实画面写第一人称旁白(不要虚构画面没发生的动作)",
-                "  3. 写 compose.v3 spec,音色查 `rf tts voices --provider relayx --model vox/index-tts-2`",
-                "  4. rf compose spec.json -o ./final.mp4",
-                "",
-                "spec 字段见 `rf compose -h`,封面模板见 `rf cover templates`。",
-                "",
-            ].join("\n"));
-        });
-    }
-}

package/dist/data/vlog/general.md

@@ -1,129 +0,0 @@
-# rf vlog · 通用素材→视频剧本（general）
-
-> 给**上层 agent**（你，正在帮用户做视频的 Claude Code / Cursor 等）读的工作指南。
-> 这是**兜底剧本**:用户拿一批自己的图/视频想做条短视频,但没有更专门的赛道时,走这里。
-> 有更贴合的垂类(如 `rf vlog pet`)就优先用垂类;没有 → 用本剧本。临时场景(做饭、
-> 旅行、日常 vlog、开箱…)都适用。
->
-> **角色边界（先记死）**
-> - 引擎只给你两样**你做不到**的能力:`rf assets describe`(给视频「眼睛」,你看不到视频帧)、`rf compose`(渲染 + 配音 + 字幕对齐)。
-> - **写旁白 / 脚本是你的活,不是引擎的。** 本剧本只给你「怎么写」的最佳实践,绝不替你写一个字。
-> - 字段 / 参数的精确用法一律以 `rf compose -h`、`rf cover -h` 为准。
-
----
-
-## Step 0 · 动手前先确认输入（别让用户从 0 摸索）
-
-| 输入 | 默认 | 要问吗 |
-|---|---|---|
-| 素材目录 | — | 必给(让用户指一个文件夹) |
-| **故事方向 / 想表达啥** | — | **灵魂问 1** |
-| **调性 + 旁白视角** | — | **灵魂问 1 的一部分**:恶搞/温馨/科普/沉浸?旁观叙述 / 第一人称 / 主人 vlog? |
-| **音色** | 不固定 | **灵魂问 2**:按调性挑 2-3 个候选给用户选(查法见下) |
-| 封面 | 自动取一张高光素材 | 用户想要精致封面时,把模板预览图发他挑 |
-| 字幕风格 | stroke(短视频爆款描边) | 默认,不问 |
-| BGM / 分辨率 | 默认 BGM / 1080×1920 | 默认,不问 |
-
----
-
-## Step 1 · 看素材（必做,这是你「看到」素材的唯一方式）
-
-```bash
-rf assets describe ./素材目录/ -o assets.json
-```
-
-返回每个素材的客观描述(图片 ~30 字 / 视频 ~80 字含动作与氛围)+ 视频时长。
-**这是事实地基。后面写旁白,只能基于这里描述出来的真实动作。**
-
-> ⚠️ 视频 describe 有 body 体积上限(~10MB 就会 400)。源视频偏大时,先用 ffmpeg 压个低清短代理
-> (如 `-vf scale=480:-2,fps=12 -crf 30`,几百 KB)再 describe;代理只用来"看懂内容",不进成片。
-
-## Step 2 · 你来写旁白 + 给用户过故事板
-
-引擎不替你写。按《写作最佳实践》自己写,然后用**人话故事板**(不是 JSON)给用户确认。
-
-## Step 3 · 渲染
-
-```bash
-rf compose spec.json -o ./final.mp4
-```
-
----
-
-## ★ 写作最佳实践
-
-### 🚫 反虚构铁律（最重要,违反 = 废片）
-**旁白只能解说画面里 `describe` 出来的真实动作。**
-- ✅ 可以编:情绪、内心戏、动机、夸张比喻。
-- ❌ 不准编:画面没发生的物理事件(画面"够不着"就不能写"够到了")。
-- 不确定画面里发生没发生 → 当作没发生,别写。
-
-### 句子写法
-- 写**完整句子、句末带标点**(。！？)。每句 10~30 字。
-- **别为字幕节奏手动拆短**——字幕切分是引擎的活(compose 内部按真实配音时间对齐)。
-- 每条旁白是一个独立句子,放进对应 scene 的 `narration` 数组里。
-
----
-
-## ★ 素材 & 画幅最佳实践（决定"短视频观感"）
-
-短视频节奏踩过的坑,默认这么做:
-
-- **优先用视频片段,尽量少用静图。** 静图即便加了 Ken Burns,整体节奏也会显得拖沓,不合现代短视频快节奏。能用视频就别用图。
-- **竖拍照片用 full-bleed 铺满**(`fit:"cover"` + `focal` 保主体),别让它缩在中间——铺满才有跟视频齐平的沉浸感。
-- **横屏视频**:要么用 `layout:"blur-bg"`(不裁画面,但竖图会被装在中间显小);要么先用 ffmpeg 把横屏烤成自带模糊垫底的 9:16 片,再整片走 `layout:"full"`——想让图和视频**统一全屏**就用后者。
-- **照片朝向**:手机竖拍照片常带旋转标记,直接喂可能横躺。喂前先摆正、抽帧确认:`ffmpeg -noautorotate -i in.jpg -vf "transpose=1" up.jpg`。
-- 不设 `theme` → 引擎**不会压暗**你的素材(保持原始亮度);只有显式选 theme 才会按主题调色压暗。
-
----
-
-## 音色怎么选
-
-按调性挑,不固定某一个。查全部音色:
-
-```bash
-rf tts voices --provider relayx --model vox/index-tts-2
-```
-
-按风格筛,例如 `... | grep 解说`。**别让用户从一长串里盲选**——你挑 2-3 个候选报给他,他点一个。
-选定后填进 spec 的 `audio.tts_voice`。
-
-## 封面怎么选
-
-compose 的 `cover.image` 只收**一张图**。两种做法:
-
-- **省事**:挑一张高光素材当封面 → `"cover": { "image": "高光帧.jpg" }`。
-- **套模板**:`rf cover templates`(每个模板带 preview_url)→ **把预览裸链接发给用户看图挑** → 渲染:
-  `rf cover -i 高光帧.jpg -t "标题" --template <模板id> -o cover.png` → 填 `"cover": { "image": "cover.png" }`。
-  (`--subtitle` / `--badge` / `--param` 见 `rf cover -h`。)
-
----
-
-## compose.v3 spec 模板
-
-```json
-{
-  "experimental": "compose.v3",
-  "output": { "width": 1080, "height": 1920, "fps": 30, "layout": "full" },
-  "audio": { "tts_model": "vox/index-tts-2", "tts_voice": "<选定音色>", "bgm_volume": 0.12 },
-  "subtitle_style": "stroke",
-  "cover": { "image": "封面.jpg" },
-  "scenes": [
-    { "video": "clip1.mp4", "muted": true, "narration": ["句1。", "句2。"] },
-    { "image": "photo1.jpg", "fit": "cover", "focal": "center", "motion": "zoom-in", "narration": ["句1。"] }
-  ]
-}
-```
-
-- spec 里**没有任何秒数**;时间由引擎量真实配音派生。
-- 旁白尽量 ≤ 视频时长,省掉片头黑卡;真比视频长时引擎会自动前置标题卡。
-- `layout` 选择见上面《素材 & 画幅最佳实践》。
-
----
-
-## 提交前自查
-- [ ] 跑过 `rf assets describe`?
-- [ ] 旁白每一句都对得上画面真实动作?(过一遍反虚构铁律)
-- [ ] 给用户看的是**人话故事板**,不是裸 JSON?
-- [ ] 照片朝向已摆正、竖图 full-bleed?横屏视频处理好画幅?
-- [ ] 没设 theme(素材保持原始亮度)?