reelforge 1.20.1 → 1.21.0

package/dist/commands/assets.js

@@ -113,6 +113,7 @@ export function registerAssets(program) {
         "spec 的结构与示例见 `rf compose --help`。",
     ].join("\n"))
         .action(() => {
+        warn("`rf assets workflow` 已更名 → 用 `rf vlog`(列赛道)/ `rf vlog pet`(宠物 SOP)。下方为旧版通用 SOP。");
         process.stdout.write(ASSETS_WORKFLOW_TEXT);
         if (!ASSETS_WORKFLOW_TEXT.endsWith("\n"))
             process.stdout.write("\n");

package/dist/commands/create.js

@@ -154,8 +154,6 @@ function optsToBody(opts) {
         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)
@@ -168,8 +166,6 @@ function optsToBody(opts) {
         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)
@@ -188,10 +184,6 @@ function optsToBody(opts) {
         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.profile !== undefined && opts.profile.trim())
@@ -230,10 +222,6 @@ function optsToBody(opts) {
         cover.base = opts.coverBase;
     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;
@@ -283,7 +271,6 @@ export function registerCreate(program) {
         .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.")
@@ -294,8 +281,6 @@ export function registerCreate(program) {
         .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("--profile <id>", "视频的「场景」(垂类):plain(默认,纯 AI 图,无组件)| finance(财经/金融,数据组件 + 鎏金深蓝)| mindset(财商认知,认知组件 + 暖纸黏土)| general(通用组件,中性皮)。选了 profile 即带出它的组件、配色、配图风、封面与字幕默认,可被其他 flag 覆盖。")
         .option("--subtitle-translate <lang>", "双语字幕:把每条字幕翻译成指定语言,以小一号文字显示在主字幕下方,如 'en'(英文)/ 'ja'(日文)。开启后字幕分段自动变短(主字幕保持单行)。默认:开(en);传 'off' 关闭(也可覆盖 recipe 设置)")
@@ -317,12 +302,9 @@ export function registerCreate(program) {
         .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("--quality <preset>", "encoder quality preset: draft | standard (default) | high. draft shrinks output ~3-4× vs standard (~3 Mbps); high is the opposite. Mutually exclusive with --video-bitrate.")
+        .option("--video-bitrate <rate>", "目标视频码率,如 '750k' / '1M' / '2M'。用于命中文件大小预算。")
         .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")
@@ -385,8 +367,6 @@ export function registerCreate(program) {
         "  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.",
@@ -402,8 +382,7 @@ export function registerCreate(program) {
         "",
         "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.",
+        "  · Omit --style to let the LLM pick a per-video style automatically.",
         "  · Run `rf styles list` to query the server's live catalog.",
         "",
         "Output behavior:",

package/dist/commands/vlog.js

@@ -0,0 +1,83 @@
+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: "用户拍的猫狗图 / 视频 + 一句话 → 宠物第一人称搞笑竖屏短视频",
+    },
+];
+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("用法:");
+    lines.push("  rf vlog pet            打印「宠物赛道」完整剧本(SOP)");
+    lines.push("  rf vlog pet | 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/pet.md

@@ -0,0 +1,155 @@
+# rf vlog · 宠物赛道剧本（pet）
+
+> 给**上层 agent**（你，正在帮用户做视频的 Claude Code / Cursor 等）读的工作指南。
+> 教你怎么把用户的宠物素材 + 一句话，做成一条第一视角搞笑竖屏 vlog。
+>
+> **角色边界（先记死）**
+> - 引擎只给你两样**你做不到**的能力：`rf assets describe`（给视频「眼睛」，你看不到视频帧）、`rf compose`（渲染 + 配音 + 字幕对齐）。
+> - **写旁白 / 脚本是你的活，不是引擎的。** 本剧本只给你「怎么写」的最佳实践，绝不替你写一个字。
+> - 字段 / 参数的精确用法一律以 `rf compose -h`、`rf cover -h` 为准。
+
+---
+
+## Step 0 · 动手前先确认输入（别让用户从 0 摸索）
+
+宠物赛道的输入清单 + 默认值。**只问灵魂 2 问，其余用默认，别拿用户看不懂的选项去烦他**：
+
+| 输入 | 默认 | 要问吗 |
+|---|---|---|
+| 素材目录 | — | 必给（让用户指一个文件夹） |
+| **故事方向 / 今天发生了啥** | — | **灵魂问 1** |
+| **音色** | 熊小二（推荐，非强制） | **灵魂问 2**：挑 2-3 个候选给用户选，别让他盲选 |
+| 封面 | 自动取一张高光素材 | 用户想要精致封面时，把模板预览图发他挑 |
+| 字幕风格 | stroke（描边，短视频爆款风） | 默认，不问 |
+| BGM / 分辨率 / 画幅 | 默认 BGM / 1080×1920 / blur-bg | 默认，不问 |
+
+---
+
+## Step 1 · 看素材（必做，这是你「看到」素材的唯一方式）
+
+```bash
+rf assets describe ./素材目录/ -o assets.json
+```
+
+返回每个素材的客观描述（图片 ~30 字 / 视频 ~80 字含动作与氛围）+ 视频时长。
+**这是事实地基。后面写旁白，只能基于这里描述出来的真实动作。**
+
+## Step 2 · 你来写旁白 + 给用户过故事板
+
+引擎不替你写。按下面《写作最佳实践》自己写，然后用**人话故事板**（不是 JSON）给用户确认。
+
+## Step 3 · 渲染
+
+```bash
+rf compose pet.compose.json -o ./final.mp4
+```
+
+---
+
+## ★ 写作最佳实践（宠物第一视角搞笑）
+
+### 人设 brief
+- 第一人称，宠物自己开口。称主人「铲屎的」，自称「本喵 / 本汪」。
+- 调性：**痞帅自信 → 怂的反差**。先吹牛，翻车了立刻甩锅装无辜。
+- 多内心戏、多吐槽；句子口语、短、有梗。
+
+### 🚫 反虚构铁律（最重要，违反 = 废片）
+**旁白只能解说画面里 `describe` 出来的真实动作。**
+- ✅ 可以编：情绪、内心戏、动机、夸张比喻（画面在踱步 → 写「围着鱼缸转了八圈」可以）。
+- ❌ 不准编：画面没发生的物理事件。
+  - 画面是「伸爪够、够不着」→ 不能写「一爪把鱼捞上来」「鱼归我了」。
+  - 画面是「趴着不动」→ 不能写「它一跃而起」。
+- 不确定画面里到底发生没发生 → 当作没发生，别写。
+
+### 句子写法
+- 写**完整句子、句末带标点**（。！？）。每句 10~30 字都行。
+- **别为字幕节奏手动拆短**——字幕切分是引擎的活（compose 内部按真实配音时间对齐）。
+- 每条旁白是一个独立句子，放进对应 scene 的 `narration` 数组里。
+
+### 范例（同一段「够鱼」画面）
+- ✅ 「想吃，真想吃，可这缸里装的居然是水？本喵金贵爪子凭啥沾水。」
+- ❌ 「本喵一爪下去，鱼就归我了。」（画面根本没捞到——虚构）
+
+---
+
+## 音色怎么选（不强制熊小二）
+
+熊小二只是**推荐默认**（痞帅搞笑，贴宠物号），用户想用别的随时换。
+
+查全部音色：
+
+```bash
+rf tts voices --provider relayx --model vox/index-tts-2
+```
+
+按风格筛，例如想要解说腔：
+
+```bash
+rf tts voices --provider relayx --model vox/index-tts-2 | grep 解说
+```
+
+**别让用户从一长串里盲选**：你按他要的调性挑 2-3 个候选报给他，他点一个。
+选定后填进 spec 的 `audio.tts_voice`（就是音色名，如 `"熊小二"`）。
+
+---
+
+## 封面怎么选
+
+compose 的 `cover.image` 只收**一张图**。两种做法：
+
+**A. 省事**：直接挑一张高光素材当封面 → `"cover": { "image": "高光帧.jpg" }`。
+
+**B. 套模板（精致）**：引擎内置多个封面模板。先看长啥样——每个模板都带一条预览图链接：
+
+```bash
+rf cover templates           # 人读表格 + 预览链接
+rf cover templates --json    # agent 消费，含每个模板的 preview_url
+```
+
+**把这些预览裸链接发给用户，让他看图挑**（别凭模板名猜）。用户选定后渲封面：
+
+```bash
+rf cover -i 高光帧.jpg -t "橘子大战鱼缸" --template <模板id> -o cover.png
+```
+
+（`--subtitle` / `--badge` / `--param` 等精确用法见 `rf cover -h`。）
+然后填进 spec：`"cover": { "image": "cover.png" }`。
+
+---
+
+## compose.v3 spec 模板（pet 默认值已填好）
+
+```json
+{
+  "experimental": "compose.v3",
+  "output": { "width": 1080, "height": 1920, "fps": 30, "layout": "blur-bg" },
+  "audio": { "tts_model": "vox/index-tts-2", "tts_voice": "熊小二", "bgm_volume": 0.12 },
+  "subtitle_style": "stroke",
+  "title": "可选，片头标题",
+  "cover": { "image": "封面.jpg" },
+  "scenes": [
+    { "video": "clip1.mp4", "muted": true, "narration": ["句1。", "句2。"] },
+    { "image": "photo1.jpg", "motion": "zoom-in", "narration": ["句1。"] }
+  ]
+}
+```
+
+- **横屏视频用 `layout: "blur-bg"`**：视频缩放居中 + 模糊垫底，绝不裁掉主角。
+- spec 里**没有任何秒数**；时间由引擎量真实配音派生。
+- 旁白尽量 ≤ 视频时长，省掉片头黑卡；真比视频长时引擎会自动前置一张标题卡。
+
+### ⚠️ 照片朝向
+手机竖拍照片常带旋转标记，直接喂可能是横躺的。喂前先摆正、抽帧确认方向：
+
+```bash
+ffmpeg -noautorotate -i in.jpg -vf "transpose=1" up.jpg
+```
+
+---
+
+## 提交前自查
+- [ ] 跑过 `rf assets describe`？
+- [ ] 旁白每一句都对得上画面真实动作？（过一遍反虚构铁律）
+- [ ] 给用户看的是**人话故事板**，不是裸 JSON？
+- [ ] 照片朝向已摆正？
+- [ ] output 1080×1920、横屏视频 blur-bg？

package/dist/index.js

@@ -34,6 +34,7 @@ import { registerExtract } from "./commands/extract.js";
 import { registerMedia } from "./commands/media.js";
 import { registerScript } from "./commands/script.js";
 import { registerCompose } from "./commands/compose.js";
+import { registerVlog } from "./commands/vlog.js";
 import { error as logError } from "./utils/output.js";
 import { ApiCallError } from "./client.js";
 const program = new Command();
@@ -111,8 +112,10 @@ program.addHelpText("after", [
     "  rf history list                                 看之前生成的视频",
     "  rf tasks list --status running                  看进行中的任务",
     "",
-    "Agent 工作流(use-case SOP,挂在用例命名空间下)",
-    "  rf assets workflow                              用户素材→视频 SOP（给 agent 看的）",
+    "做 vlog?(用户拍的素材 → 视频,如宠物号)先看赛道剧本:",
+    "  rf vlog                                         列出可用赛道(宠物等)",
+    "  rf vlog pet                                     打印「宠物第一视角搞笑」完整 SOP",
+    "  → 拿到 SOP 后照着走:rf assets describe(看素材) → 写旁白 → rf compose(渲染)",
 ].join("\n"));
 registerAuth(program);
 registerCreate(program);
@@ -142,6 +145,7 @@ registerExtract(program);
 registerMedia(program);
 registerScript(program);
 registerCompose(program);
+registerVlog(program);
 async function main() {
     if (process.argv.length <= 2) {
         program.outputHelp();

package/package.json

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