reelforge 1.18.2

package/README.md

@@ -0,0 +1,295 @@
+# reelforge
+
+> Turn a topic or script into a finished vertical video — narration, visuals, and subtitles, assembled for you. Every capability is a command, with `--help` at every level.
+
+## Install
+
+```bash
+npm install -g reelforge
+```
+
+Or use directly without install:
+
+```bash
+npx reelforge <command>
+```
+
+After install, two binaries are on your `PATH` — `reelforge` and the short alias `rf`. Both behave identically; the docs use `rf` from here on.
+
+```bash
+rf --version            # same as `reelforge --version`
+```
+
+## Quick start
+
+The CLI ships pointing at the hosted service. Log in once, then call:
+
+```bash
+npm install -g reelforge
+rf login                                       # opens browser; headless? rf login <api_key>
+rf whoami                                      # balance + api_keys
+rf create "为什么我们还没找到外星文明？"          # auto-saves to ./<title>-<id>.mp4 in cwd
+```
+
+That's the whole story — no server to run.
+
+### Output behavior
+
+| invocation | result |
+|---|---|
+| `rf create "..."` | Saves to `./<sanitized-title>-<task_id_short>.mp4`, prints the path |
+| `rf create "..." -o ./videos/space.mp4` | Saves to that exact path (must include filename, not just a directory) |
+| `rf create "..." --no-download` | Skips local save, prints JSON result with `video_url` |
+| `rf create "..." \| jq .video_url` | When stdout is piped, download is skipped automatically |
+
+## Global options
+
+| flag | description |
+|---|---|
+| `-s, --server <url>` | Server URL (overrides `$REELFORGE_SERVER`; defaults to the hosted service) |
+| `-k, --api-key <key>` | API key (overrides `$REELFORGE_API_KEY` and `reelforge login` saved key) |
+| `--json` | Output raw JSON instead of pretty text — pipe-friendly |
+| `--quiet` | Suppress informational messages on stderr |
+| `-v, --version` | Show CLI version |
+| `-h, --help` | Show help (works on every sub-command) |
+
+## Command map
+
+Run `rf <command> --help` for full details on any of these.
+
+### Core capabilities
+
+| command | what it does |
+|---|---|
+| `llm chat -p <text>` | Send one prompt to the configured model |
+| `llm presets` | List built-in model presets |
+| `tts ... -t <text> -o out.mp3` | Text-to-speech (free local + cloud voice options) |
+| `tts voices [--locale zh]` | List supported voices |
+| `images generate -p <prompt>` | Image generation |
+
+### Content / audio / subtitle atomics
+
+| command | what it does |
+|---|---|
+| `content scene-plan -t <topic>` | Single LLM call: title + master script + per-scene image prompts (replaces the old narration / split / image-prompts / title trio) |
+| `content scene-plan --script <text-or-@file>` | Same, but the user supplies the script verbatim — LLM only segments and writes image prompts |
+| `audio transcribe -f <file>` / `--url <url>` | Speech-to-text with word + segment timestamps |
+| `subtitles split -t <text-or-@file>` | Deterministic tiered-punctuation subtitle line splitter (pure function, zero billing) |
+
+### Composition
+
+| command | what it does |
+|---|---|
+| `templates list [--size 1080x1920] [--type image]` | List HTML frame templates |
+| `templates preview <keyOrPath> [-o out.png]` | Render a preview from a preset key **or your own local .html file** |
+| `templates show <key> [-o file.html]` | Print or save the source HTML of any preset — copy it as a starting point for a custom template |
+| `frames render -t <keyOrPath> --title ... --text ...` | Render a single composed frame to PNG. `-t` accepts a preset key **or a local .html path** |
+| `compositions concat <v1> <v2> -o out.mp4` | FFmpeg concat (+ optional BGM) |
+| `compositions bgm -i video.mp4 --bgm bgm.mp3 -o out.mp4` | Add background music |
+| `compositions image-to-video -i img.png -a aud.mp3 -o out.mp4` | Build video from image + audio |
+| `compositions overlay -v video.mp4 --overlay overlay.png -o out.mp4` | Overlay PNG on video |
+
+### End-to-end pipelines
+
+All `pipelines *` commands submit an **async task** and (by default) poll until it finishes with a live progress indicator on stderr. Use `--no-wait` to return immediately with a `task_id`, then `rf tasks wait <id>` later.
+
+The standard pipeline turns a topic or script into a finished vertical video — narration, visuals, and subtitles are generated and assembled for you. One continuous narration track; visuals cut at scene boundaries; subtitles cut at line boundaries.
+
+| command | what it does |
+|---|---|
+| `pipelines standard -t <topic>` (or `--script <text>`) | Audio-first pipeline; `-d/--duration` and `-p/--pace` are the two main knobs |
+
+#### Composition knobs
+
+Three independent axes — mix and match as you like:
+
+| flag | values | default | what changes |
+|---|---|---|---|
+| `--motion` | `off` / `lite` / `max` | `lite` | per-scene zoompan + crossfade intensity |
+| `--layout` | `full` / `blur-bg` / `letterbox` | `full` | how the image sits in the canvas |
+| `--subtitle-style` | `plate` / `stroke` / `cinema` | `plate` | subtitle look |
+
+**Layout presets**:
+- `full` — image fills the whole 1080×1920 canvas. Generates a 1080×1920 image. High-impact; 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** moving in sync with the foreground. Generates a 1080×1080 image (cheaper + no wasted pixels). Best for charts, screenshots, non-9:16 source content (小红书 / 抖音 style).
+- `letterbox` — image at 1080×1080 centered, top/bottom is a solid matte (CSS color). Generates a 1080×1080 image. Cinematic / calm. Customize the matte with `--layout-matte-color "#1a1a1a"` (default `black`).
+
+Examples:
+```bash
+rf create "财经日报" --layout blur-bg                              # 小红书 / 抖音
+rf create "纪录片片段" --layout letterbox --motion max             # 电影感
+rf create "..." --layout letterbox --layout-matte-color "#1a1a1a" # 柔和黑
+```
+
+### Resources
+
+| command | what it does |
+|---|---|
+| `bgm list / upload <file> / delete <name>` | Manage background music |
+| `files list / upload <file> / download <path> / delete <path>` | Manage user assets |
+
+### System
+
+| command | what it does |
+|---|---|
+| `config get` | Read server config (keys masked) |
+| `config set <key> <value>` | Update a dotted-path setting (e.g. `llm.api_key sk-xxx`) |
+| `config patch <file>` | Apply a JSON-merge patch |
+| `tasks list [--status running]` | List recent tasks |
+| `tasks get <id>` / `tasks wait <id>` / `tasks cancel <id>` | Task lifecycle |
+| `history list / get <id> / delete <id>` | Browse / delete completed runs |
+| `health` | Server health + capability check |
+
+### Heavy brand customization (custom overlay templates)
+
+`--motion` / `--layout` / `--subtitle-*` / `--brand-*` cover the common cases. For full visual identity ownership (custom path bar, accent decorations, light theme, footer block, etc.) pass a custom overlay HTML via `--frame-template <local.html | preset_key>`:
+
+```bash
+rf templates show 1080x1920/default.html -o ./my-brand.html
+# ...edit my-brand.html (change colors, add structure, etc.)...
+rf create "我的视频" --frame-template ./my-brand.html
+```
+
+**Contract for custom HTML**:
+
+- Canvas is **1080×1920** (pipeline-fixed; don't declare a different size in `<meta>`).
+- Background must be **transparent** — the scene image is composited by the renderer outside the HTML layer.
+- **`{{image}}` no longer exists.** Using `<img src="{{image}}">` is a hard error at submit time. The image is composited by the renderer.
+- The pipeline injects these placeholders for you:
+
+| Placeholder | What it is |
+|---|---|
+| `{{title}}` `{{text}}` | per-frame content |
+| `{{index}}` `{{total}}` | "scene N of M" — `{{total}}` is the LLM-decided scene count, don't hardcode |
+| `{{layout}}` | `"full"` / `"blur-bg"` / `"letterbox"` — react via `body[data-layout="..."]` CSS to put title/subtitle in the matte zones when layout ≠ full |
+| `{{subtitle_style}}` `{{subtitle_color}}` `{{subtitle_background}}` | subtitle preset + overrides |
+| `{{brand_position}}` `{{brand_handle}}` `{{brand_slogan}}` `{{brand_logo}}` `{{brand_color}}` | brand-chrome inputs (use or ignore as you like) |
+
+Inline HTML is hard-capped at 2 MB. The audio + motion + character-ref + scene-plan stages all keep working identically — only the overlay layer is yours.
+
+**Publishing to short-video platforms (Douyin / TikTok / WeChat Channels)** — the default composition renders to the full 1080×1920 canvas, but those apps overlay UI on top/bottom/right and cover-crop ~96-180px on each side on taller phones. ReelForge does NOT bake platform-specific padding into the renderer. Look up reference safe-zone numbers + recommended `--media-anchor-y` values per platform:
+
+```bash
+rf platform                  # overview table for all platforms
+rf platform 抖音              # detail + anchor variants (alias of douyin)
+rf platform tiktok
+rf platform wechat           # 视频号
+```
+
+## Examples
+
+```bash
+# 1. One-click out a video (45s default, AI writes the script)
+rf create "为什么我们还没找到外星文明？"
+
+# 2. Longer video with a slower visual rhythm
+rf create "深夜便利店的灯光" -d 90 -p slow
+
+# 3. Your own script — no narration-splitting on your side, the pipeline handles it
+rf create --script @./my-script.txt
+rf create --script "雨水缓缓滑落在玻璃窗上，像是无声的泪珠。"
+
+# 4. Preview-first workflow: scrub the storyboard in the browser
+#    before paying for the MP4 render. Finalize with `rf render` when satisfied.
+rf create "..." --preview-only          # opens browser studio
+rf render <task-id>                     # produce the MP4
+
+# 5. Push the image square up to grow the bottom matte (抖音 long-description
+#    case); subtitle position follows the image automatically.
+rf create "..." --layout blur-bg --media-anchor-y 0.40
+#  See `rf platform 抖音` for the safe range and per-scenario recommendations.
+
+# 6. Encoder budget — pick a quality preset or set an exact bitrate.
+rf create "..." --quality draft         # ~1 Mbps, ~3-4× smaller than default
+rf create "..." --video-bitrate 750k    # exact bitrate
+rf create "..." --crf 28                # fine-grained control
+
+# 7. Pick a built-in visual style preset
+rf create "美食教程" --style photorealistic
+
+# 5. Pipeline form with explicit output path
+rf pipelines standard \
+  --script @./script.txt \
+  --frame-template 1080x1920/image_default.html \
+  -p normal -o smoke.mp4
+
+# 6. Inspect existing tasks & redownload a finished video
+rf tasks list --limit 5
+rf history get <task-id> --download recovered.mp4
+
+# 7. Atomics for stand-alone use
+rf content scene-plan -t "雨天的玻璃窗" -d 45 --json | jq .scenes
+rf audio transcribe -f narration.mp3 --json | jq '.words[:5]'
+rf subtitles split -t @./narration.txt --min 10 --hard-max 24
+
+# 8. JSON pipe for automation
+rf llm presets --json | jq '.[].defaultModel'
+
+# 9. Use your own HTML template (no PR/release needed)
+#     Any --frame-template that points to a local .html file is read and sent
+#     inline. Declare size inside the file via
+#       <meta name="template:width"  content="1080">
+#       <meta name="template:height" content="1920">
+#     or pass --frame-template-size 1080x1920.
+rf templates show 1080x1920/image_default.html -o my-brand.html   # copy a preset
+# ...edit my-brand.html to suit your style...
+rf templates preview ./my-brand.html --title "Hello" -o preview.png
+rf frames render -t ./my-brand.html --values '{"author":"Alice"}' -o frame.png
+rf pipelines standard -t "宠物" --frame-template ./my-brand.html -o final.mp4
+```
+
+### Custom HTML templates
+
+Easiest way to start: grab a preset as a reference.
+
+```bash
+rf templates list                                                  # see all keys
+rf templates show 1080x1920/static_default.html                    # print to stdout
+rf templates show 1080x1920/image_default.html -o my-brand.html    # save and edit
+```
+
+`{{title}}`, `{{text}}`, `{{image}}`, `{{index}}`, `{{total}}` are reserved built-ins auto-injected by the pipeline; everything else uses the `{{name:type=default}}` DSL (`type` ∈ `text|number|color|bool`). Pass extras through `--values '{"author":"Alice"}'` (or `template_params` on the pipeline API).
+
+- `{{index}}` — current scene number, 1-based
+- `{{total}}` — scene count the LLM actually produced (use this for "scene N of M" badges; don't hardcode in `template_params`, the scene count is decided at runtime)
+
+#### Template type — does the pipeline generate an AI image per scene?
+
+When you ship an inline template through `rf create` / `rf pipelines standard`, ReelForge needs to know whether each scene should kick off image generation. Resolution priority (high → low):
+
+1. Explicit flag — `--frame-template-type image|static|asset` (or `frame_template_type` in the API body).
+2. Inside the HTML — `<meta name="template:type" content="image">` (or `static` / `asset`).
+3. **Default: `image`** — best practice for zero-config users. If your template doesn't reference scene imagery (pure-text card, etc.), declare `static` explicitly to skip image generation and its cost.
+
+The placeholder `{{image}}` no longer doubles as a type signal — declare type explicitly.
+
+Limits and safety:
+
+- Max 2 MB per inline HTML.
+- The render sandbox blocks `file://`, loopback / private / link-local IPs, CGNAT range, cloud-metadata, and `*.local` / `*.internal` hostnames. So your template can only reference public `https`/`http` resources or `data:` URIs.
+- If the CLI is talking to a hosted server, local-path `--image` won't reach the server; either upload to `rf files upload` first or use an HTTPS URL / data: URI.
+
+#### API field reference
+
+| endpoint | inline HTML field | size field | type field |
+|---|---|---|---|
+| `POST /api/v1/frames/render` | `template_html` | `size` | — (n/a, no image generation) |
+| `POST /api/v1/templates/preview` | `template_html` | `size` | — |
+| `POST /api/v1/pipelines/standard` | `frame_template_inline` | `frame_template_size` | `frame_template_type` |
+
+The pipeline endpoint uses the `frame_template_*` prefix because it already has a `frame_template` field (preset key). The single-frame endpoints use the shorter `template_html` because they don't.
+
+## Tip — getting unstuck
+
+Every level has `--help`:
+
+```bash
+rf --help                     # top-level overview
+rf pipelines --help           # list of pipelines
+rf pipelines standard --help  # full option reference
+rf tts edge --help            # one specific command
+```
+
+## License
+
+Apache-2.0

package/bin/reelforge.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Thin shim so `reelforge` (alias `rf`) is invokable globally. The actual
+// implementation is bundled to dist/ by `npm run build`.
+import("../dist/index.js").catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error(err?.stack || err);
+  process.exit(1);
+});

package/dist/client.js

@@ -0,0 +1,120 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+const DEFAULT_SERVER = "https://reelforge.timor419.com";
+function loadConfigSync() {
+    try {
+        const p = path.join(os.homedir(), ".reelforge", "config.json");
+        const raw = readFileSync(p, "utf-8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed === "object" && parsed ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+const fileConfig = loadConfigSync();
+let overrideServer = null;
+let overrideApiKey = null;
+export function setServer(url) {
+    overrideServer = url.replace(/\/$/, "");
+}
+export function getServer() {
+    if (overrideServer)
+        return overrideServer;
+    const env = process.env.REELFORGE_SERVER;
+    if (env)
+        return env.replace(/\/$/, "");
+    if (fileConfig.server)
+        return fileConfig.server.replace(/\/$/, "");
+    return DEFAULT_SERVER;
+}
+export function setApiKey(key) {
+    overrideApiKey = key;
+}
+export function getApiKey() {
+    if (overrideApiKey)
+        return overrideApiKey;
+    if (process.env.REELFORGE_API_KEY)
+        return process.env.REELFORGE_API_KEY;
+    if (fileConfig.api_key)
+        return fileConfig.api_key;
+    return null;
+}
+export class ApiCallError extends Error {
+    status;
+    code;
+    details;
+    constructor(err) {
+        super(err.message);
+        this.status = err.status;
+        this.code = err.code;
+        this.details = err.details;
+    }
+}
+async function request(path, init = {}) {
+    const url = `${getServer()}${path.startsWith("/") ? path : `/${path}`}`;
+    const headers = new Headers(init.headers);
+    const key = getApiKey();
+    if (key && !headers.has("Authorization") && !headers.has("authorization")) {
+        headers.set("Authorization", `Bearer ${key}`);
+    }
+    let res;
+    try {
+        res = await fetch(url, { ...init, headers });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new ApiCallError({
+            status: 0,
+            message: `Network error contacting ${url}: ${msg}`,
+        });
+    }
+    const text = await res.text();
+    let json = null;
+    try {
+        json = text ? JSON.parse(text) : null;
+    }
+    catch {
+        if (!res.ok) {
+            throw new ApiCallError({ status: res.status, message: text.slice(0, 500) });
+        }
+        return text;
+    }
+    if (!res.ok) {
+        const err = json?.error;
+        throw new ApiCallError({
+            status: res.status,
+            code: err?.code,
+            message: err?.message || `HTTP ${res.status}`,
+            details: err?.details,
+        });
+    }
+    return json;
+}
+export function get(path) {
+    return request(path);
+}
+export function post(path, body) {
+    return request(path, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+}
+export function patch(path, body) {
+    return request(path, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+}
+export function del(path) {
+    return request(path, { method: "DELETE" });
+}
+export async function uploadMultipart(path, fields) {
+    const form = new FormData();
+    for (const [k, v] of Object.entries(fields))
+        form.append(k, v);
+    return request(path, { method: "POST", body: form });
+}

package/dist/commands/assets-workflow-text.js

@@ -0,0 +1,22 @@
+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);
+function loadWorkflowText() {
+    const candidates = [
+        path.resolve(__dirname, "../data/assets-to-video-workflow.md"),
+        path.resolve(__dirname, "../../../docs/assets-to-video-workflow.md"),
+    ];
+    for (const p of candidates) {
+        try {
+            return fs.readFileSync(p, "utf8");
+        }
+        catch {
+        }
+    }
+    return ("# 素材 → 视频 工作流\n\n" +
+        "用 `rf compose <spec.json>` 把图片/视频素材 + 旁白拼成竖屏视频。\n" +
+        "spec 的结构、字段与完整示例见 `rf compose --help`。\n");
+}
+export const ASSETS_WORKFLOW_TEXT = loadWorkflowText();

package/dist/commands/assets.js

@@ -0,0 +1,231 @@
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import { post } from "../client.js";
+import { info, isJson, print, success, warn } from "../utils/output.js";
+import { ASSETS_WORKFLOW_TEXT } from "./assets-workflow-text.js";
+const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".webp"]);
+const VIDEO_EXT = new Set([".mp4", ".mov", ".webm", ".mkv", ".m4v"]);
+const SUPPORTED_EXT = new Set([...IMAGE_EXT, ...VIDEO_EXT]);
+const BATCH_CONCURRENCY = 4;
+function mimeForExt(ext) {
+    switch (ext) {
+        case ".png": return "image/png";
+        case ".jpg":
+        case ".jpeg": return "image/jpeg";
+        case ".webp": return "image/webp";
+        case ".mp4":
+        case ".m4v": return "video/mp4";
+        case ".mov": return "video/quicktime";
+        case ".webm": return "video/webm";
+        case ".mkv": return "video/x-matroska";
+        default: return null;
+    }
+}
+function typeForExt(ext) {
+    if (IMAGE_EXT.has(ext))
+        return "image";
+    if (VIDEO_EXT.has(ext))
+        return "video";
+    return null;
+}
+async function resolveAsset(input) {
+    const t = input.trim();
+    if (t.startsWith("data:image/"))
+        return { url: t, type: "image" };
+    if (t.startsWith("data:video/"))
+        return { url: t, type: "video" };
+    if (t.startsWith("data:")) {
+        throw new Error(`unsupported data: URI MIME (need data:image/... or data:video/...)`);
+    }
+    if (/^https?:\/\//i.test(t)) {
+        let ext = "";
+        try {
+            ext = path.extname(new URL(t).pathname).toLowerCase();
+        }
+        catch {
+        }
+        const guessed = typeForExt(ext);
+        if (!guessed) {
+            throw new Error(`cannot infer asset type from URL (extension "${ext || "<none>"}"). ` +
+                `Use a URL ending in a supported extension, or download the file and pass the local path.`);
+        }
+        return { url: t, type: guessed };
+    }
+    const abs = path.resolve(t);
+    if (!fsSync.existsSync(abs)) {
+        throw new Error(`asset not found: ${abs}`);
+    }
+    const ext = path.extname(abs).toLowerCase();
+    const type = typeForExt(ext);
+    const mime = mimeForExt(ext);
+    if (!type || !mime) {
+        const supported = [...IMAGE_EXT, ...VIDEO_EXT].join(" / ");
+        throw new Error(`unsupported extension ${ext} (supported: ${supported})`);
+    }
+    const buf = await fs.readFile(abs);
+    return { url: `data:${mime};base64,${buf.toString("base64")}`, type };
+}
+async function describeOne(input, opts) {
+    const { url, type } = await resolveAsset(input);
+    const body = {};
+    body[`${type}_url`] = url;
+    if (opts.model)
+        body.model = opts.model;
+    if (opts.prompt)
+        body.prompt = opts.prompt;
+    return post("/api/v1/assets/describe", body);
+}
+function listAssetFiles(dir) {
+    return fsSync
+        .readdirSync(dir)
+        .filter((name) => SUPPORTED_EXT.has(path.extname(name).toLowerCase()))
+        .filter((name) => !name.startsWith("."))
+        .sort();
+}
+async function pMap(items, fn, limit) {
+    const out = new Array(items.length);
+    let idx = 0;
+    async function worker() {
+        while (true) {
+            const i = idx++;
+            if (i >= items.length)
+                return;
+            out[i] = await fn(items[i], i);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return out;
+}
+export function registerAssets(program) {
+    const cmd = program
+        .command("assets")
+        .description("素材相关能力: describe(图片/视频 → 一句话描述) / workflow(agent 用户素材→视频 SOP)")
+        .helpOption("-h, --help", "show help");
+    cmd
+        .command("workflow")
+        .description("打印 agent 用户素材→视频 完整 SOP（给 Claude / Cursor 等 agent 看；底层使用 rf compose 渲染）")
+        .helpOption("-h, --help", "show help")
+        .addHelpText("after", [
+        "",
+        "打印素材→视频工作流指南到 stdout。",
+        "适合 agent 启动时一次性读入；普通用户也可以 `rf assets workflow | less` 浏览。",
+        "spec 的结构与示例见 `rf compose --help`。",
+    ].join("\n"))
+        .action(() => {
+        process.stdout.write(ASSETS_WORKFLOW_TEXT);
+        if (!ASSETS_WORKFLOW_TEXT.endsWith("\n"))
+            process.stdout.write("\n");
+    });
+    cmd
+        .command("describe <pathOrDir>")
+        .description("用多模态 LLM 给图片或视频生成中文描述。" +
+        "单文件打印一句话;目录批量,扫描所有 jpg/png/mp4/mov 等并输出 recipe 风格 JSON。")
+        .helpOption("-h, --help", "show help")
+        .option("-o, --output <file>", "写到文件而不是 stdout(单文件写描述文本,目录写 JSON)")
+        .option("--model <id>", "指定 RelayX 上的 vision-capable 模型(默认 qwen/qwen3-vl-flash;其他可选: qwen/qwen3-vl-plus / openai/gpt-4.1-mini / google/gemini-3-flash / anthropic/claude-4-7-sonnet)")
+        .option("--prompt <text>", "覆盖默认提示词(图片默认 30 字简描,视频默认 80 字动作+氛围描述)")
+        .addHelpText("after", [
+        "",
+        "支持的扩展名:",
+        "  图片: .jpg .jpeg .png .webp",
+        "  视频: .mp4 .mov .webm .mkv .m4v",
+        "",
+        "Examples:",
+        "  # 图片,直接打到终端",
+        "  rf assets describe ./cat.jpg",
+        "",
+        "  # 视频(自动检测扩展名),输出 ~80 字含动作和氛围的描述",
+        "  rf assets describe ./clip.mp4",
+        "",
+        "  # 整个相册目录批量(图片视频混着扫),输出 recipe JSON",
+        "  rf assets describe ./trip/ -o trip.recipe.json",
+        "",
+        "  # 自定义提示词",
+        "  rf assets describe ./clip.mp4 --prompt 'List 3 key visual moments in this video, comma-separated.'",
+        "",
+        "Output:",
+        "  单文件: 直接打印 description 到 stdout(--json 时打印完整 JSON)",
+        "  目录:   { assets: [{image|video, description}, ...] }",
+        "",
+        "成本参考(默认 qwen3-vl-flash):",
+        "  图片 ~$0.00007 (¥0.0005)",
+        "  视频 ~$0.00007/秒 (60s 视频 ¥0.03)",
+    ].join("\n"))
+        .action(async (pathOrDir, opts) => {
+        const isLocal = !/^https?:\/\//i.test(pathOrDir) && !pathOrDir.startsWith("data:");
+        const isDir = isLocal && fsSync.existsSync(pathOrDir) && fsSync.statSync(pathOrDir).isDirectory();
+        if (isDir) {
+            const abs = path.resolve(pathOrDir);
+            const names = listAssetFiles(abs);
+            if (names.length === 0) {
+                throw new Error(`no supported asset files in ${abs} ` +
+                    `(looked for ${[...SUPPORTED_EXT].join(" / ")})`);
+            }
+            info(`Captioning ${names.length} assets from ${abs} (concurrency=${BATCH_CONCURRENCY})...`);
+            const results = await pMap(names, async (name) => {
+                const filePath = path.join(abs, name);
+                const ext = path.extname(name).toLowerCase();
+                const type = typeForExt(ext);
+                try {
+                    const r = await describeOne(filePath, opts);
+                    return {
+                        type,
+                        path: filePath,
+                        description: r.description,
+                        cost_usd: r.cost_usd ?? 0,
+                        intrinsic_duration_ms: r.intrinsic_duration_ms,
+                    };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    warn(`  ${name}: failed — ${msg}`);
+                    return { type, path: filePath, description: "", error: msg, cost_usd: 0 };
+                }
+            }, BATCH_CONCURRENCY);
+            const totalCost = results.reduce((s, r) => s + (r.cost_usd ?? 0), 0);
+            const okCount = results.filter((r) => r.description).length;
+            const stub = {
+                assets: results.map((r) => {
+                    if (r.type === "video") {
+                        const entry = {
+                            video: r.path,
+                            description: r.description,
+                        };
+                        if (typeof r.intrinsic_duration_ms === "number" && r.intrinsic_duration_ms > 0) {
+                            entry.intrinsic_duration_ms = r.intrinsic_duration_ms;
+                        }
+                        return entry;
+                    }
+                    return { image: r.path, description: r.description };
+                }),
+            };
+            const json = JSON.stringify(stub, null, 2);
+            if (opts.output) {
+                const outAbs = path.resolve(opts.output);
+                await fs.mkdir(path.dirname(outAbs), { recursive: true });
+                await fs.writeFile(outAbs, json);
+                success(`Wrote ${okCount}/${names.length} captions → ${outAbs}  (total cost $${totalCost.toFixed(4)})`);
+            }
+            else {
+                print(stub);
+                info(`(${okCount}/${names.length} ok, total cost $${totalCost.toFixed(4)})`);
+            }
+            return;
+        }
+        const r = await describeOne(pathOrDir, opts);
+        if (opts.output) {
+            const outAbs = path.resolve(opts.output);
+            await fs.mkdir(path.dirname(outAbs), { recursive: true });
+            await fs.writeFile(outAbs, r.description);
+            success(`Wrote description (${r.type}) → ${outAbs}  (${r.model} · ${(r.duration_ms / 1000).toFixed(2)}s · $${(r.cost_usd ?? 0).toFixed(6)})`);
+        }
+        else if (isJson()) {
+            print(r);
+        }
+        else {
+            print(r.description);
+            info(`${r.type} · ${r.model} · ${(r.duration_ms / 1000).toFixed(2)}s · cost $${(r.cost_usd ?? 0).toFixed(6)}`);
+        }
+    });
+}