reelforge 1.18.2

package/dist/commands/cover.js

@@ -0,0 +1,397 @@
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import { getServer, getApiKey } from "../client.js";
+import { info, success, warn } from "../utils/output.js";
+const TEMPLATES = [
+    { id: "paper-band", label: "牛皮纸条 横卡", supports: "title, subtitle, badge", useFor: "财经 / 干货 / 商业分析" },
+    { id: "carbon-copy", label: "复写纸 暗调", supports: "title, subtitle", useFor: "情感 / 哲思 / 治愈(默认)" },
+    { id: "chalkboard", label: "黑板 粉笔", supports: "title, subtitle, badge", useFor: "教育 / 科普 / 课程" },
+    { id: "book-spine", label: "书脊 + 卡片", supports: "title, subtitle, badge", useFor: "书单 / 读书笔记" },
+    { id: "polaroid", label: "拍立得 相纸", supports: "title, subtitle", useFor: "生活 / vlog / 日常" },
+    { id: "recipe-card", label: "食谱 米色卡", supports: "title, subtitle, badge", useFor: "美食 / 菜谱" },
+    { id: "spec-sheet", label: "工业 规格表", supports: "title, subtitle, badge", useFor: "数码 / 汽车 / 评测" },
+    { id: "vintage-stamp", label: "牛皮纸 + 红印章", supports: "title, subtitle, badge", useFor: "历史 / 经典 / 怀旧" },
+    { id: "magazine", label: "杂志 italic 衬线", supports: "title, subtitle, badge", useFor: "时尚 / 娱乐 / 人物特写" },
+];
+const TEMPLATE_IDS = new Set(TEMPLATES.map((t) => t.id));
+const DEFAULT_TEMPLATE = "carbon-copy";
+const SMALL_IMAGE_WARN_BYTES = 100 * 1024;
+async function resolveImage(input) {
+    const t = input.trim();
+    if (!t)
+        throw new Error("--image: empty value");
+    if (/^https?:\/\//i.test(t))
+        return { url: t };
+    if (t.startsWith("data:"))
+        return { url: t };
+    const abs = path.resolve(t);
+    if (!fsSync.existsSync(abs)) {
+        throw new Error(`--image: local file not found: ${abs}`);
+    }
+    const ext = path.extname(abs).toLowerCase();
+    const mime = ext === ".png" ? "image/png" :
+        ext === ".jpg" || ext === ".jpeg" ? "image/jpeg" :
+            ext === ".webp" ? "image/webp" :
+                null;
+    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 };
+}
+function fmtSize(b) {
+    if (b < 1024)
+        return `${b} B`;
+    if (b < 1024 * 1024)
+        return `${(b / 1024).toFixed(1)} KB`;
+    return `${(b / 1024 / 1024).toFixed(1)} MB`;
+}
+function buildParamsPayload(pairs, bulkJson) {
+    if ((!pairs || pairs.length === 0) && !bulkJson)
+        return undefined;
+    const out = {};
+    if (bulkJson) {
+        let parsed;
+        try {
+            parsed = JSON.parse(bulkJson);
+        }
+        catch (e) {
+            throw new Error(`--params: not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("--params: must be a JSON object (not array or scalar)");
+        }
+        Object.assign(out, parsed);
+    }
+    for (const pair of pairs ?? []) {
+        const eq = pair.indexOf("=");
+        if (eq <= 0) {
+            throw new Error(`--param: expected "key=value" form, got "${pair}"`);
+        }
+        const key = pair.slice(0, eq).trim();
+        const rawVal = pair.slice(eq + 1);
+        if (!key)
+            throw new Error(`--param: empty key in "${pair}"`);
+        out[key] = coerceParamValue(rawVal);
+    }
+    return out;
+}
+function coerceParamValue(raw) {
+    const t = raw.trim();
+    if (t === "true")
+        return true;
+    if (t === "false")
+        return false;
+    if (t === "null")
+        return null;
+    if (/^-?\d+(\.\d+)?$/.test(t))
+        return Number(t);
+    if ((t.startsWith("{") && t.endsWith("}")) || (t.startsWith("[") && t.endsWith("]"))) {
+        try {
+            return JSON.parse(t);
+        }
+        catch {
+        }
+    }
+    return raw;
+}
+export function registerCover(program) {
+    const templateList = TEMPLATES
+        .map((t) => `  ${t.id.padEnd(13)} ${t.label.padEnd(26)} 适合: ${t.useFor}\n  ${"".padEnd(13)} 支持字段: ${t.supports}`)
+        .join("\n\n");
+    const coverCmd = program
+        .command("cover")
+        .description("渲染 1080×1920 竖屏封面 PNG (9 个模板可选, 每个模板有自己的字号/配色/装饰参数)")
+        .helpOption("-h, --help", "show help")
+        .option("-i, --image <pathOrUrl>", "封面背景图 — 本地文件路径 / http(s) URL / data: URI")
+        .option("-t, --title <text>", "封面大标题(必填,短句更佳,12 字内最稳;长标题模板会自动选小一档字号,不会断行错乱)")
+        .option("--subtitle <text>", "副标题 / 一句话标语。不是所有模板都显示 — 具体看 `rf cover templates --id <id>` 列出的 supports.subtitle 字段(=true 才会渲染,否则静默忽略)")
+        .option("--badge <text>", "角标 / 期号 / 紧急标,如 'EP.042' / '突发' / 'FLASH'。不是所有模板都显示 — 同样看 `rf cover templates --id <id>` 的 supports.badge 字段")
+        .option("--template <id>", `封面风格,共 9 个(default: ${DEFAULT_TEMPLATE})。用户不确定选哪个时,agent 先跑 \`rf cover templates --json\` 把 9 张 preview_url 给用户看,看完图再传 id。详见下面"封面模板"段的清单`)
+        .option("--param <key=value>", "模板特有参数,如 --param titleSize=M。可多次传; --param 优先级高于 --params 的同名键。运行 `rf cover templates --id <id>` 查看某模板支持哪些 params", (val, prev = []) => [...prev, val], [])
+        .option("--params <json>", "模板特有参数,一次性传一个 JSON 对象,如 --params '{\"titleSize\":\"M\",\"dividerChar\":\"···\"}'。会与 --param 合并,后者优先")
+        .option("-o, --output <file>", "输出 PNG 文件路径(如 cover.png)")
+        .addHelpText("after", [
+        "",
+        "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+        "AGENT 三步上手 (LLM / 脚本调用必读)",
+        "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+        "  Step 1. 看清单选模板:",
+        "    rf cover templates --json     # 9 个模板的 id/label/supports/params 全在 JSON 里",
+        "",
+        "  Step 2. 看选中模板的特有 params (字号档 / 颜色 / 装饰元素 等):",
+        "    rf cover templates --id carbon-copy --json",
+        "",
+        "  Step 3. 按 params 描述里的 options / default 调用渲染:",
+        "    rf cover -i ./scene.png -t '今天的咖啡冷得很慢' --subtitle '清晨手记' \\",
+        "             --template carbon-copy --param titleSize=M --param 'dividerChar=···' \\",
+        "             -o cover.png",
+        "",
+        "  字号档兜底: --param titleSize=auto (默认) 会按标题字数自动选档,大概率不必显式传。",
+        "  传错 param 时 server 返回 400 + 具体 issues + 提示再跑 `rf cover templates --id <id>`,",
+        "  按提示纠正即可,不要盲猜。",
+        "",
+        "封面模板清单 (--template):",
+        templateList,
+        "",
+        "  上面 \"支持字段\" 仅说 subtitle/badge 是否生效;每个模板的额外 params 见 step 2。",
+        "",
+        "模板特有参数 (--param / --params):",
+        "  每个模板可以额外接受自己专属的参数 (字号档 / 颜色 / 装饰元素 等),",
+        "  这些参数因模板而异。运行 `rf cover templates --id <id>` 可以列出某个模板",
+        "  支持的全部 params 及其默认值。",
+        "",
+        "  例: --param titleSize=M --param dividerChar='···'",
+        "      --params '{\"titleSize\":\"M\",\"accentColor\":\"#C9D9E8\"}'",
+        "",
+        "Examples:",
+        "  rf cover -i ./scene.png -t '巴菲特又出手了' --badge 'EP.042' \\",
+        "           --subtitle 'MAGE · 美股科普' -o ./out/cover.png",
+        "",
+        "  rf cover -i https://example.com/bg.jpg -t '美联储再降息' \\",
+        "           --template magazine --badge '突发' -o cover.png",
+        "",
+        "  # 用模板特有参数压字号档 + 换分隔符:",
+        "  rf cover -i ./scene.png -t '今天的咖啡冷得很慢' \\",
+        "           --template carbon-copy --param titleSize=S --param dividerChar='···' \\",
+        "           --subtitle '清晨手记' -o cover.png",
+        "",
+        "  # Use \\n in the title to force a line break:",
+        "  rf cover -i scene.png -t '美股科技股\\n急跌' --template magazine \\",
+        "           --badge 'FLASH' -o cover.png",
+        "",
+        "Output is a 1080×1920 PNG. Background image is auto-scaled with cover-fit;",
+        "any aspect ratio works. Very small inputs (under 100 KB) will look blurry —",
+        "recommended source size is 1080×1920 or larger.",
+    ].join("\n"))
+        .action(async (opts) => {
+        const missing = [];
+        if (!opts.image)
+            missing.push("--image / -i");
+        if (!opts.title)
+            missing.push("--title / -t");
+        if (!opts.output)
+            missing.push("--output / -o");
+        if (missing.length > 0) {
+            throw new Error(`required: ${missing.join(", ")}`);
+        }
+        const { 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.`);
+        }
+        const template = (opts.template ?? DEFAULT_TEMPLATE);
+        if (!TEMPLATE_IDS.has(template)) {
+            throw new Error(`--template must be one of ${TEMPLATES.map((t) => t.id).join(" | ")} (got: ${opts.template})`);
+        }
+        const params = buildParamsPayload(opts.param, opts.params);
+        const body = {
+            image_url: imageUrl,
+            template,
+            title: opts.title,
+        };
+        if (opts.subtitle)
+            body.subtitle = opts.subtitle;
+        if (opts.badge)
+            body.badge = opts.badge;
+        if (params)
+            body.params = params;
+        info(`Rendering cover (template=${template})...`);
+        const server = getServer().replace(/\/+$/, "");
+        const apiKey = getApiKey();
+        const headers = { "content-type": "application/json" };
+        if (apiKey)
+            headers["authorization"] = `Bearer ${apiKey}`;
+        const resp = await fetch(`${server}/api/v1/cover`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => "");
+            throw new Error(`Cover render failed: HTTP ${resp.status}\n${text.slice(0, 500)}`);
+        }
+        const outAbs = path.resolve(opts.output);
+        await fs.mkdir(path.dirname(outAbs), { recursive: true });
+        const buf = Buffer.from(await resp.arrayBuffer());
+        await fs.writeFile(outAbs, buf);
+        success(`Saved → ${outAbs}  (${fmtSize(buf.byteLength)})`);
+    });
+    coverCmd
+        .command("prepend <video> <cover>")
+        .description("把一张封面 PNG 作为首帧贴到已有 MP4 上。无重编码 (~1s 完成), 适合 A/B 测封面或后期换封面。")
+        .helpOption("-h, --help", "show help")
+        .option("--out <file>", "输出 MP4 路径 (默认覆盖 <video> 输入文件). 注意: 父命令 `rf cover` 占用了 -o, 这里只用长 flag 避免冲突")
+        .option("--fps <n>", "目标 fps (默认 24 — 跟主线 pipeline 默认一致, 与原视频 fps 不一致时会按目标 fps 改写时间戳)", (v) => parseInt(v, 10))
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  # 默认: 覆盖原文件",
+        "  rf cover prepend ./video.mp4 ./cover.png",
+        "",
+        "  # 写到新文件 (注意: --out 不是 -o, 因为父命令 rf cover 占用了 -o)",
+        "  rf cover prepend ./video.mp4 ./cover.png --out ./video-with-cover.mp4",
+        "",
+        "  # 自定义 fps",
+        "  rf cover prepend ./video.mp4 ./cover.png --fps 30",
+        "",
+        "性能:",
+        "  典型 40s 视频处理 ~1s (TS-remux, 无重编码)。",
+        "  抖音 / TikTok / 视频号在 9 宫格 feed 抓首帧或近首帧作为封面缩略图,",
+        "  贴一张设计封面可以控制 feed 里出现什么画面。",
+    ].join("\n"))
+        .action(async (videoArg, coverArg, opts) => {
+        const videoAbs = path.resolve(videoArg);
+        const coverAbs = path.resolve(coverArg);
+        if (!fsSync.existsSync(videoAbs)) {
+            throw new Error(`video not found: ${videoAbs}`);
+        }
+        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")}`,
+        };
+        if (typeof opts.fps === "number")
+            body.fps = opts.fps;
+        info(`Prepending cover (${fmtSize(coverBuf.byteLength)}) → video (${fmtSize(videoBuf.byteLength)})...`);
+        const server = getServer().replace(/\/+$/, "");
+        const apiKey = getApiKey();
+        const headers = { "content-type": "application/json" };
+        if (apiKey)
+            headers["authorization"] = `Bearer ${apiKey}`;
+        const resp = await fetch(`${server}/api/v1/cover/prepend`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => "");
+            throw new Error(`Cover prepend failed: HTTP ${resp.status}\n${text.slice(0, 500)}`);
+        }
+        const outAbs = path.resolve(opts.out ?? videoArg);
+        await fs.mkdir(path.dirname(outAbs), { recursive: true });
+        const out = Buffer.from(await resp.arrayBuffer());
+        await fs.writeFile(outAbs, out);
+        success(`Saved → ${outAbs}  (${fmtSize(out.byteLength)})`);
+    });
+    coverCmd
+        .command("templates")
+        .description("【 discovery / 发现命令 】列出所有封面模板 + 各自的特有 params (字号档 / 颜色 / 装饰元素 等)。" +
+        "Agent/LLM 在生成 rf cover 命令前必须先跑这个,否则只能盲猜参数。--json 模式直接拿结构化 catalog 喂给上游模型。")
+        .helpOption("-h, --help", "show help")
+        .option("--id <templateId>", "只看某个模板的详细信息 (e.g. carbon-copy)")
+        .option("--json", "输出原始 JSON,适合 agent / 脚本消费 (默认人读表格)")
+        .addHelpText("after", [
+        "",
+        "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+        "AGENT 帮用户选封面的标准流程 (LLM 必读)",
+        "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+        "  当用户没明确指定 --cover-template,或说『我不知道选哪个』时,不要替用户",
+        "  拍板,也不要按 label 文字给用户脑补描述 — 直接走这条路径:",
+        "",
+        "  Step 1. 拉 catalog (含 preview_url):",
+        "    rf cover templates --json",
+        "",
+        "  Step 2. 把 9 张 preview_url 用 markdown 图片格式丢给用户 (聊天界面会",
+        "         直接渲染成缩略图):",
+        "    ![carbon-copy](https://rf-cdn.oss-cn-hangzhou.aliyuncs.com/cover-samples/carbon-copy.png)",
+        "    ![magazine](https://rf-cdn.oss-cn-hangzhou.aliyuncs.com/cover-samples/magazine.png)",
+        "    ... (其余 7 个同样格式)",
+        "",
+        "  Step 3. 用户照图选,把 id 喂给 `rf create --cover-template <id>` 或",
+        "         `rf cover --template <id>`.",
+        "",
+        "  9 张 preview 都是同一个 title=今天的咖啡冷得很慢 / subtitle=清晨手记 /",
+        "  badge=EP.042 渲染,只有模板变量在动,横向对比一目了然.",
+        "",
+        "Examples:",
+        "  # 列出所有模板的简要清单",
+        "  rf cover templates",
+        "",
+        "  # 看 carbon-copy 模板支持哪些特有 params",
+        "  rf cover templates --id carbon-copy",
+        "",
+        "  # JSON 输出 (agent 必跑这条)",
+        "  rf cover templates --json",
+        "  rf cover templates --id magazine --json",
+    ].join("\n"))
+        .action(async (opts) => {
+        const server = getServer().replace(/\/+$/, "");
+        const apiKey = getApiKey();
+        const headers = {};
+        if (apiKey)
+            headers["authorization"] = `Bearer ${apiKey}`;
+        const resp = await fetch(`${server}/api/v1/cover/templates`, { headers });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => "");
+            throw new Error(`Cover templates fetch failed: HTTP ${resp.status}\n${text.slice(0, 500)}`);
+        }
+        const catalog = (await resp.json());
+        const filtered = opts.id
+            ? catalog.templates.filter((t) => t.id === opts.id)
+            : catalog.templates;
+        if (opts.id && filtered.length === 0) {
+            throw new Error(`unknown template "${opts.id}". Known: ${catalog.templates.map((t) => t.id).join(", ")}`);
+        }
+        if (opts.json) {
+            const payload = opts.id ? filtered[0] : { default: catalog.default, templates: filtered };
+            console.log(JSON.stringify(payload, null, 2));
+            return;
+        }
+        if (catalog.preview && !opts.id) {
+            console.log(`\n样图基线 (preview_url 都是按这组输入渲的):` +
+                `\n  title="${catalog.preview.title}" · subtitle="${catalog.preview.subtitle}" · badge="${catalog.preview.badge}"`);
+        }
+        for (const t of filtered) {
+            console.log(`\n● ${t.id}  ${t.label}${t.id === catalog.default ? "  (默认)" : ""}`);
+            if (t.preview_url) {
+                console.log(`  预览 (直接浏览器打开): ${t.preview_url}`);
+            }
+            console.log(`  支持槽位: title (必填) · subtitle (${t.supports.subtitle ? "✓" : "—"}) · badge (${t.supports.badge ? "✓" : "—"})`);
+            if (t.params.length === 0) {
+                console.log(`  模板特有 params: 无 (只用 title/subtitle/badge 即可)`);
+            }
+            else {
+                console.log(`  模板特有 params:`);
+                for (const p of t.params) {
+                    const opts = p.options ? `  [${p.options.join(" | ")}]` : "";
+                    const def = p.default !== undefined ? `  default=${JSON.stringify(p.default)}` : "";
+                    console.log(`    - ${p.name}  <${p.type}>${opts}${def}`);
+                    console.log(`        ${p.desc}`);
+                }
+            }
+        }
+        if (!opts.id) {
+            console.log([
+                "",
+                "下一步:",
+                "  1. 挑一个模板 (上面的 ● <id> 行) — 按内容场景选,如教育→chalkboard / 财经→paper-band。",
+                "  2. 运行 `rf cover templates --id <id>` 看那个模板的特有 params 详细描述 + default。",
+                "  3. 运行 `rf cover -i <bg> -t <title> --template <id> [--param k=v ...] -o out.png` 出图。",
+                "",
+                "Agent / 脚本: 加 --json 拿结构化 catalog 直接喂给上游模型。",
+                "",
+            ].join("\n"));
+        }
+        else {
+            console.log([
+                "",
+                "示例调用:",
+                `  rf cover -i ./bg.png -t '示例标题' --template ${opts.id} \\`,
+                "           --param titleSize=M  # 其余 params 同样 --param k=v 形式",
+                "           -o out.png",
+                "",
+                "传错 param 时 server 返回 400 + Zod issues,按提示纠正即可。",
+                "",
+            ].join("\n"));
+        }
+    });
+}