museav-cli 2.7.0 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 2.9.0 (2026-08-28)
+
+### 新增：`slideshow` —— 一组图 + 文案 + 配乐 → 竖版短视频（免登录）
+
+```bash
+museav slideshow ./表情图 --title "莓啾日常" --caption "催外卖 / 催开饭" --music bgm.mp3
+```
+
+默认 1080×1920 / 30fps / H.264+AAC。排版走 sharp + SVG（中文用系统字体，不引入需要编译的
+canvas），合成走 ffmpeg（**要求本机装了 ffmpeg**，这是唯一的外部依赖）。
+
+这个能力原本长在微信表情包的 skill 里（一个 Python 脚本），做推广视频用。但「图集 + 文案 +
+配乐 → 竖版视频」跟表情包没关系，产品图、作品集、日报一样要用，所以下沉到 CLI，
+skill 那边退化成读配置拼参数的薄封装。
+
+移植时保留了三个已经踩过的坑的修法，它们的共同点还是**不报错、只是结果不对**：
+
+1. **小图不会被自动放大。** PIL 的 `thumbnail` 和 sharp 的 `withoutEnlargement` 都只缩不放，
+   240×240 的贴纸贴到 1080 宽的画布上会原样贴，在竖屏里只占两成宽。要显式 `resize` 到目标尺寸。
+   贴纸类图片还得先 `trim` 掉四周透明留白再放大——否则放大的是留白，主体照样小。
+2. **配乐直接 `-shortest` 会中途硬切断。** 配乐通常比视频长几倍，切在句子中间很难听。
+   要 `atrim` 裁到视频时长 + 首尾 `afade`。
+3. **ffmpeg 的 concat demuxer 会忽略最后一项的 `duration`。** 末页一闪而过，
+   只能把末页在列表里多写一次。
+
+## 2.8.0 (2026-08-27)
+
+### 新增：贴图素材 + 版式模板命令（租户级资产，给封面/海报工具用）
+
+两个新命令，底层调中台 `/api/stickers` 和 `/api/poster-templates`，账户 Key / 租户 Key 均可（落到本租户）。
+
+- `museav stickers`：列出本租户贴图素材（PNG 透明装饰图）
+- `museav stickers add <file> --name <名称>`：上传贴图（不压缩，保留透明通道）
+- `museav poster-templates`：列出版式模板（封面底图 + 固定描述）
+- `museav poster-templates add <file> --name <名称> --prompt <描述>`：保存版式（`{城市}` `{明星}` 占位符会被替换）
+
+背景：好易美（hym）的闲鱼封面工具此前版式存学员本机桌面、贴图只在后台本地，无法共享。
+现在贴图素材 + 版式模板收归中台，CLI 一条命令加载/保存，学员间共享。
+
 ## 2.7.0 (2026-08-27)
 
 ### 修复：`remove-bg` 抠不出主体（三个静默 bug）

package/README.md

@@ -102,11 +102,12 @@
 | | 抠图去背景（输出透明 PNG） | `remove-bg` |
 | | **放大清晰度**（2M → 10M+ 级） | `upscale` |
 | | 去水印 | `remove-watermark` |
+| | **一组图 → 竖版短视频**（带标题/文案/配乐） | `slideshow` |
 | **语音**（直连小米 MiMo，需 `MIMO_API_KEY`） | 文字转语音 / 音色设计 / 音色克隆 | `speak` |
 | | 语音转文字 | `transcribe` |
 | **素材与统计** | 上传素材 / 查任务 / 查余额 / 查模型 / 查身份 | `upload` / `jobs` / `balance` / `models` / `whoami` |
 
-> 本地工具（`compress` / `remove-bg` / `upscale` / `remove-watermark`）**不用登录、不花一分钱**，装了就能用；其余命令需要一个凭证（个人 `login` 或租户 apiKey）。
+> 本地工具（`compress` / `remove-bg` / `upscale` / `remove-watermark` / `slideshow`）**不用登录、不花一分钱**，装了就能用；其余命令需要一个凭证（个人 `login` 或租户 apiKey）。
 >
 > 语音（`speak` / `transcribe`）是第三种情况：**不走中台身份**，直连小米 MiMo，只认 `MIMO_API_KEY` 环境变量。
 > 中台的出音链路还没接完，这批能力目前内部用，没有那把 key 的人（包括租户）用不了。
@@ -440,6 +441,36 @@ museav remove-watermark photo.jpg --mask mask.png      # 复杂画面手工掩
 - 依赖红线：本地**绝不自动拉起开源大模型**——这些工具是轻量 CNN/传统算法，用完即释放内存。reverse 的本地路已翻回显式 `--local`（需自备 Ollama），默认走中台 API。
 - 二进制与模型缓存：`~/.museav-bin/upscayl`（引擎）、`~/.museav-models/`（模型），Windows 对应 `%USERPROFILE%` 下同名目录；删除即彻底清理。
 
+### 图集转竖版短视频 `slideshow`（免登录）
+
+一组图 + 每张的文案 + 一段配乐 → 一条能直接发朋友圈 / 视频号 / 小红书的竖版视频。
+排版走 sharp + SVG（中文用系统字体），合成走 ffmpeg，**需要本机装了 ffmpeg**（`brew install ffmpeg`）。
+
+```bash
+# 最简：一个目录里的图，按文件名排序串成视频
+museav slideshow ./图片目录 --out 成片.mp4
+
+# 完整：标题 + 逐张文案 + 配乐
+museav slideshow ./表情图 \
+  --title "莓啾日常" --subtitle "莓啾 · 微信表情包" \
+  --caption "需要被安慰的时候" --caption "催外卖 / 催开饭" \
+  --footer "微信搜「莓啾日常」添加整套" \
+  --music bgm.mp3 --sec 2.2 --out 推广视频.mp4
+
+# 文案多的时候写文件里，每行一条
+museav slideshow ./图片目录 --captions 文案.txt --title "作品集"
+```
+
+默认 1080×1920 / 30fps / H.264+AAC，每张停 2.5 秒；`--size` 换尺寸、`--theme dark` 换深色底。
+
+三个不写出来就会踩的点，已经在实现里处理掉了：
+
+- **小图会被显式放大**。240×240 的贴纸直接贴到 1080 宽的画布上只占两成宽，画面空得离谱。
+  贴纸类图片还会先裁掉四周透明留白再放大（`--no-trim` 关掉），否则放大的是留白不是主体。
+- **配乐不会中途硬切断**。配乐通常比视频长几倍，直接 `-shortest` 会在句子中间断掉；
+  这里裁到视频时长并做首尾淡入淡出。
+- **末页不会一闪而过**。ffmpeg 的 concat demuxer 会忽略最后一项的 duration，实现里把末页多列了一次。
+
 ### 项目（工作区）与项目素材库 `projects`
 
 层级：**平台 → 账户 → 工作区**。一个账户最多 5 个项目，每个项目挂自己的素材库——「人像库的项目出模特图、产品库的项目出电商图」，业务隔离互不污染：
@@ -564,6 +595,7 @@ console.log(r.sculpt.light)  // 光影分析
 | `remove-bg <file>` | 本地抠图去背景（免登录，输出带 alpha 的 PNG） | 产物路径 |
 | `upscale <file>` | 本地超分放大，2M 图变 10M+（免登录，Real-ESRGAN GPU，`--scale 2/3/4`） | 产物路径 |
 | `remove-watermark <file>` | 本地去水印（免登录，自动定位 + LaMa 修复，`--mask` 手工兜底） | 产物路径 |
+| `slideshow <图片或目录...>` | 图集转竖版短视频（免登录，带标题/逐张文案/配乐，需 ffmpeg） | 产物路径 |
 | `projects` | 工作区（项目）列表：一账户多项目，各带自己的素材库 | 项目 id 列表 |
 | `projects assets --project` | 项目素材库：ls / add / rm（垫图母版，人像库/产品库各管各的） | `id<TAB>url` 行 |
 | `models` | 可用模型 | 模型名列表 |

package/dist/client.d.ts

@@ -337,6 +337,18 @@ export declare class StudioClient {
     createTemplate(input: CreateTemplateInput): Promise<TemplateOption>;
     /** 新建视频模板。归属同图片模板：租户 apiKey 自动归租户，平台管理员归平台共享 */
     createVideoTemplate(input: CreateVideoTemplateInput): Promise<TemplateOption>;
+    /** 贴图素材清单（租户级资产，服务端已按调用者权限过滤）。PNG 装饰图，叠加在海报/封面上 */
+    stickers(): Promise<any[]>;
+    /** 上传贴图素材（不压缩——透明 PNG 压缩会破坏透明通道） */
+    createSticker(filePath: string, name: string): Promise<any>;
+    /** 删除贴图素材 */
+    deleteSticker(id: string): Promise<void>;
+    /** 版式模板清单（租户级资产）：封面底图 + 固定描述（{城市}{明星} 占位符） */
+    posterTemplates(): Promise<any[]>;
+    /** 上传版式模板（不压缩，保留封面底图原样） */
+    createPosterTemplate(filePath: string, name: string, prompt: string): Promise<any>;
+    /** 删除版式模板 */
+    deletePosterTemplate(id: string): Promise<void>;
     /** 提交出图任务，立即返回 jobId */
     generate(opts: GenerateOptions): Promise<{
         jobId: string;

package/dist/client.js

@@ -125,6 +125,41 @@ export class StudioClient {
         });
         return r.row;
     }
+    /** 贴图素材清单（租户级资产，服务端已按调用者权限过滤）。PNG 装饰图，叠加在海报/封面上 */
+    async stickers() {
+        const r = await this.request('stickers');
+        return Array.isArray(r) ? r : [];
+    }
+    /** 上传贴图素材（不压缩——透明 PNG 压缩会破坏透明通道） */
+    async createSticker(filePath, name) {
+        const blob = new Blob([new Uint8Array(readFileSync(filePath))]);
+        const fd = new FormData();
+        fd.append('file', blob, basename(filePath));
+        fd.append('name', name);
+        return this.request('stickers', { method: 'POST', body: fd });
+    }
+    /** 删除贴图素材 */
+    async deleteSticker(id) {
+        await this.request(`stickers?id=${encodeURIComponent(id)}`, { method: 'DELETE' });
+    }
+    /** 版式模板清单（租户级资产）：封面底图 + 固定描述（{城市}{明星} 占位符） */
+    async posterTemplates() {
+        const r = await this.request('poster-templates');
+        return Array.isArray(r) ? r : [];
+    }
+    /** 上传版式模板（不压缩，保留封面底图原样） */
+    async createPosterTemplate(filePath, name, prompt) {
+        const blob = new Blob([new Uint8Array(readFileSync(filePath))]);
+        const fd = new FormData();
+        fd.append('file', blob, basename(filePath));
+        fd.append('name', name);
+        fd.append('prompt', prompt);
+        return this.request('poster-templates', { method: 'POST', body: fd });
+    }
+    /** 删除版式模板 */
+    async deletePosterTemplate(id) {
+        await this.request(`poster-templates?id=${encodeURIComponent(id)}`, { method: 'DELETE' });
+    }
     /** 提交出图任务，立即返回 jobId */
     async generate(opts) {
         // prompt / skill_slug / template_id 三选一：都传时服务端按 prompt > template_id > skill_slug

package/dist/commands/poster-templates.d.ts

@@ -0,0 +1,11 @@
+/**
+ * museav poster-templates —— 版式模板库（租户级资产）。
+ *  封面底图 + 固定描述（{城市} {明星} 占位符），选版式时把城市/明星名填进底图。
+ *  学员做的封面版式保存后全租户共享。
+ */
+import type { StudioClient } from '../client.js';
+export declare function posterTemplates(client: StudioClient): Promise<void>;
+export declare function createPosterTemplate(client: StudioClient, filePath: string, opts: {
+    name: string;
+    prompt: string;
+}): Promise<void>;

package/dist/commands/poster-templates.js

@@ -0,0 +1,23 @@
+export async function posterTemplates(client) {
+    const list = await client.posterTemplates();
+    if (!list.length) {
+        process.stderr.write('没有版式模板（可用 museav poster-templates add <底图> --name <名称> --prompt <描述> 保存）\n');
+        return;
+    }
+    process.stderr.write(`版式模板（${list.length} 个）:\n`);
+    for (const t of list) {
+        process.stderr.write(`  ${t.id.padEnd(38)} ${String(t.name || '').padEnd(18)} ${String(t.prompt || '').slice(0, 40)}\n`);
+    }
+    process.stderr.write(`\n保存: museav poster-templates add <底图路径> --name <名称> --prompt <描述>\n`);
+    console.log(list.map((t) => t.id).join('\n'));
+}
+export async function createPosterTemplate(client, filePath, opts) {
+    if (!opts.name?.trim())
+        throw new Error('--name 必填');
+    if (!opts.prompt?.trim())
+        throw new Error('--prompt 必填，{城市} {明星} 占位符会被替换');
+    const row = await client.createPosterTemplate(filePath, opts.name, opts.prompt);
+    const id = row?.template?.id || row?.id || '';
+    process.stderr.write(`✅ 版式模板已保存：${id}\n`);
+    console.log(id);
+}

package/dist/commands/slideshow.d.ts

@@ -0,0 +1,15 @@
+export interface SlideshowCmdOpts {
+    out?: string;
+    title?: string;
+    subtitle?: string;
+    footer?: string;
+    caption?: string[];
+    captions?: string;
+    music?: string;
+    sec?: string;
+    size?: string;
+    art?: string;
+    theme?: string;
+    trim?: boolean;
+}
+export declare function slideshowCmd(paths: string[], opts: SlideshowCmdOpts): Promise<void>;

package/dist/commands/slideshow.js

@@ -0,0 +1,82 @@
+/** museav slideshow —— 一组图 + 文案 + 配乐 → 竖版短视频。
+ *  纯本地、免登录、不碰中台；stdout 只出产物路径，进度与统计打 stderr。
+ *  排版走 sharp + SVG（中文用系统字体），合成走 ffmpeg，不引入需要编译的重依赖。 */
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { extname, isAbsolute, join, resolve } from 'node:path';
+import { makeSlideshow, fileSize } from '../local-slideshow.js';
+const IMG_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp']);
+function fmtBytes(n) {
+    return n >= 1048576 ? `${(n / 1048576).toFixed(2)}MB` : `${(n / 1024).toFixed(1)}KB`;
+}
+/** 入参可以是若干张图，也可以是一个目录（目录内按文件名排序，所以图片建议带序号前缀） */
+async function collectImages(paths) {
+    const out = [];
+    for (const p of paths) {
+        const abs = isAbsolute(p) ? p : resolve(p);
+        let st;
+        try {
+            st = await stat(abs);
+        }
+        catch {
+            throw new Error(`路径不存在: ${p}`);
+        }
+        if (st.isDirectory()) {
+            const names = (await readdir(abs))
+                .filter((n) => !n.startsWith('.') && IMG_EXT.has(extname(n).toLowerCase()))
+                .sort((a, b) => a.localeCompare(b, 'zh-Hans-CN', { numeric: true }));
+            if (!names.length)
+                throw new Error(`目录里没有图片: ${p}`);
+            out.push(...names.map((n) => join(abs, n)));
+        }
+        else {
+            out.push(abs);
+        }
+    }
+    return out;
+}
+export async function slideshowCmd(paths, opts) {
+    const images = await collectImages(paths);
+    let captions = opts.caption?.length ? [...opts.caption] : [];
+    if (opts.captions) {
+        const text = await readFile(opts.captions, 'utf8').catch(() => {
+            throw new Error(`文案文件读不到: ${opts.captions}`);
+        });
+        captions = text.split('\n').map((l) => l.trim()).filter(Boolean);
+    }
+    if (captions.length && captions.length < images.length) {
+        process.stderr.write(`⚠️  文案 ${captions.length} 条少于图片 ${images.length} 张，后面几张不带文字\n`);
+    }
+    const sec = opts.sec ? Number(opts.sec) : 2.5;
+    if (!Number.isFinite(sec) || sec <= 0)
+        throw new Error('--sec 必须是正数');
+    let width = 1080;
+    let height = 1920;
+    if (opts.size) {
+        const m = /^(\d+)[x×](\d+)$/i.exec(opts.size.trim());
+        if (!m)
+            throw new Error('--size 格式是 宽x高，如 1080x1920');
+        width = Number(m[1]);
+        height = Number(m[2]);
+    }
+    const artSize = opts.art ? Number(opts.art) : Math.round(width * 0.48);
+    if (!Number.isFinite(artSize) || artSize < 16)
+        throw new Error('--art 至少 16px');
+    const theme = (opts.theme || 'light');
+    if (!['light', 'dark'].includes(theme))
+        throw new Error('--theme 只支持 light / dark');
+    const out = opts.out ? resolve(opts.out) : resolve('slideshow.mp4');
+    const total = images.length * sec;
+    process.stderr.write(`${images.length} 张 × ${sec}s ≈ ${total.toFixed(0)}s · ${width}×${height}` +
+        (opts.title ? ` · 「${opts.title}」` : '') +
+        (opts.music ? ' · 带配乐' : ' · 无配乐') + '\n');
+    const start = Date.now();
+    const r = await makeSlideshow({
+        images, out, width, height, artSize, seconds: sec, theme, trim: opts.trim,
+        title: opts.title, subtitle: opts.subtitle, footer: opts.footer,
+        captions: captions.length ? captions : undefined,
+        music: opts.music ? resolve(opts.music) : undefined,
+    });
+    process.stderr.write(`✅ 视频生成完成（${r.pages} 页，${r.seconds.toFixed(1)}s，` +
+        `${fmtBytes(await fileSize(out))}，用时 ${((Date.now() - start) / 1000).toFixed(1)}s）\n`);
+    console.log(out);
+}

package/dist/commands/stickers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * museav stickers —— 贴图素材库（租户级资产）。
+ *  PNG 透明装饰图（logo/花纹/边框），叠加在海报/封面上。
+ *  列出的都是自己租户的贴图；上传用账户 Key 或租户 Key 均可（落到本租户）。
+ */
+import type { StudioClient } from '../client.js';
+export declare function stickers(client: StudioClient): Promise<void>;
+export declare function createSticker(client: StudioClient, filePath: string, opts: {
+    name: string;
+}): Promise<void>;

package/dist/commands/stickers.js

@@ -0,0 +1,22 @@
+export async function stickers(client) {
+    const list = await client.stickers();
+    if (!list.length) {
+        process.stderr.write('没有贴图素材（可用 museav stickers add <图片> --name <名称> 上传）\n');
+        return;
+    }
+    process.stderr.write(`贴图素材（${list.length} 个）:\n`);
+    for (const s of list) {
+        process.stderr.write(`  ${s.id.padEnd(38)} ${String(s.name || '').padEnd(20)} ${s.url || ''}\n`);
+    }
+    process.stderr.write(`\n上传: museav stickers add <图片路径> --name <名称>\n`);
+    // stdout 只出 id，便于脚本与 agent 解析
+    console.log(list.map((s) => s.id).join('\n'));
+}
+export async function createSticker(client, filePath, opts) {
+    if (!opts.name?.trim())
+        throw new Error('--name 必填');
+    const row = await client.createSticker(filePath, opts.name);
+    const id = row?.sticker?.id || row?.id || '';
+    process.stderr.write(`✅ 贴图素材已上传：${id}\n`);
+    console.log(id);
+}

package/dist/index.js

@@ -16,6 +16,7 @@ import { printWelcome } from './commands/welcome.js';
 import { gen } from './commands/gen.js';
 import { reverse } from './commands/reverse.js';
 import { compressCmd, removeBgCmd, upscaleCmd, removeWatermarkCmd } from './commands/img-tools.js';
+import { slideshowCmd } from './commands/slideshow.js';
 import { projects, createProject, listAssets, addAsset, removeAsset } from './commands/projects.js';
 import { imageToTemplate } from './commands/image-to-template.js';
 import { upload } from './commands/upload.js';
@@ -28,6 +29,8 @@ import { jobs } from './commands/jobs.js';
 import { whoami } from './commands/whoami.js';
 import { products } from './commands/products.js';
 import { assets } from './commands/assets.js';
+import { stickers, createSticker } from './commands/stickers.js';
+import { posterTemplates, createPosterTemplate } from './commands/poster-templates.js';
 import { speak, transcribeCmd } from './commands/speak.js';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
 // 每 12 小时最多查一次 npm registry，过期才提示，不拖慢日常调用
@@ -200,6 +203,22 @@ program
     .option('--mask <file>', '手工掩码图（白色=要去除的区域），跳过自动定位')
     .option('--overwrite', '允许覆盖已存在的输出文件')
     .action(asyncRun((input, opts) => removeWatermarkCmd(input, opts)));
+program
+    .command('slideshow <图片或目录...>')
+    .description('本地图集转竖版短视频（sharp + ffmpeg，免登录）：默认 1080×1920 / 30fps / H.264，可加标题、逐张文案与配乐。需要本机有 ffmpeg')
+    .option('--out <path>', '输出 mp4（默认当前目录 slideshow.mp4）')
+    .option('--title <text>', '顶部主标题（大字）')
+    .option('--subtitle <text>', '顶部副标题（小字）')
+    .option('--caption <text>', '单页文案，可重复传，按顺序对应每张图', (v, acc) => [...acc, v], [])
+    .option('--captions <file>', '文案文件（每行一条，按顺序对应每张图），与 --caption 二选一')
+    .option('--footer <text>', '底部引导语')
+    .option('--music <file>', '配乐音频。自动裁到视频长度并加首尾淡入淡出（不会中途硬切断）')
+    .option('--sec <n>', '每张停留秒数，默认 2.5')
+    .option('--size <WxH>', '画面尺寸，默认 1080x1920')
+    .option('--art <px>', '主图渲染边长，默认画面宽的 48%')
+    .option('--theme <name>', 'light（默认）/ dark')
+    .option('--no-trim', '不裁主图四周的透明留白（默认会裁，贴纸类图片不裁会显得很小）')
+    .action(asyncRun((paths, opts) => slideshowCmd(paths, opts)));
 // 工作区（项目）与项目素材库：平台 → 账户 → 工作区三层归属，素材挂工作区
 const projectsCmd = program
     .command('projects')
@@ -315,6 +334,25 @@ templatesCmd
     .option('--fields <json>', '占位符字段说明，JSON 数组，如 \'[{"key":"artist","label":"艺人名"}]\'；不传则自动从 --prompt 里的 {key} 提取')
     .option('--type <type>', '模板类型：image（图片，默认） / article（文字）')
     .action(withClient((client, opts) => createTemplate(client, opts)));
+const stickersCmd = program
+    .command('stickers')
+    .description('查贴图素材库（租户级资产：PNG 装饰图，叠加在海报/封面上）')
+    .action(withClient((client) => stickers(client)));
+stickersCmd
+    .command('add <file>')
+    .description('上传贴图素材（PNG 透明装饰图，不压缩保留透明通道）')
+    .requiredOption('--name <名称>', '贴图名称')
+    .action(withClient((client, file, opts) => createSticker(client, file, opts)));
+const posterTemplatesCmd = program
+    .command('poster-templates')
+    .description('查版式模板库（租户级资产：封面底图 + 固定描述，选版式把城市/明星名填进底图）')
+    .action(withClient((client) => posterTemplates(client)));
+posterTemplatesCmd
+    .command('add <file>')
+    .description('保存版式模板（封面底图 + 描述，描述里用 {城市} {明星} 占位）')
+    .requiredOption('--name <名称>', '版式名称')
+    .requiredOption('--prompt <描述>', '版式固定描述，{城市} {明星} 会自动替换')
+    .action(withClient((client, file, opts) => createPosterTemplate(client, file, opts)));
 program
     .command('products')
     .description('查所属租户自己的产品目录（数据在租户自己的后台，不在 Studio 中台；只支持已开通该接口的租户，仅租户 apiKey 身份可用）')

package/dist/local-slideshow.d.ts

@@ -0,0 +1,23 @@
+export interface SlideshowOpts {
+    images: string[];
+    out: string;
+    title?: string;
+    subtitle?: string;
+    captions?: string[];
+    footer?: string;
+    music?: string;
+    seconds?: number;
+    width?: number;
+    height?: number;
+    /** 主图渲染尺寸（正方形边长）。默认 520，约占 1080 宽的 48% */
+    artSize?: number;
+    theme?: 'light' | 'dark';
+    /** 放大前先裁掉主图四周的透明留白，默认开（仅对带 alpha 的图生效） */
+    trim?: boolean;
+}
+export declare function makeSlideshow(opts: SlideshowOpts): Promise<{
+    out: string;
+    pages: number;
+    seconds: number;
+}>;
+export declare function fileSize(p: string): Promise<number>;

package/dist/local-slideshow.js

@@ -0,0 +1,157 @@
+/**
+ * 本地图集转竖版短视频 —— slideshow 的核心实现。
+ * 一组图 + 每张的文字说明 + 配乐 → 1080×1920 的 mp4，适合发朋友圈 / 视频号 / 小红书。
+ *
+ * 排版走 sharp 渲染 SVG（中文靠系统字体，macOS/Win/主流 Linux 都有中文字体），
+ * 合成走 ffmpeg 的 concat demuxer —— 不引入 canvas 那种要编译的重依赖。
+ *
+ * 三个实测踩出来的点，写在这里免得下次重踩：
+ *
+ * 1. 图片必须显式放大。小图（如 240×240 的表情）直接贴到 1080 宽的画布上只占两成宽，
+ *    画面空得离谱。要按目标尺寸等比 resize，而不是「不超过某上限」那种只缩不放的逻辑。
+ * 2. 配乐不能直接 -shortest。配乐通常比视频长几倍，硬切会在中途断掉。
+ *    要 atrim 裁到视频时长 + 首尾 afade。
+ * 3. concat demuxer 的最后一张要再列一次，否则它的 duration 被忽略，末页一闪而过。
+ */
+import { mkdtemp, writeFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+const FONT = 'Hiragino Sans GB, PingFang SC, Microsoft YaHei, Noto Sans CJK SC, sans-serif';
+function esc(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+}
+/** 中文按全宽算、ASCII 按半宽算，估出一行文字的像素宽，用来收敛字号 */
+function textWidth(s, size) {
+    let w = 0;
+    for (const ch of s)
+        w += /[一-鿿　-〿＀-￯]/.test(ch) ? size : size * 0.55;
+    return w;
+}
+function fitSize(text, max, start, min = 24) {
+    let size = start;
+    while (size > min && textWidth(text, size) > max)
+        size -= 2;
+    return size;
+}
+function pageSvg(o) {
+    const { width: W, height: H, theme } = o;
+    const dark = theme === 'dark';
+    const bg = dark ? '#16181c' : '#ffffff';
+    const ink = dark ? '#e9ebef' : '#2b2d31';
+    const muted = dark ? '#8b929c' : '#8c929b';
+    const pink = dark ? '#3a2b33' : '#ffd6e2';
+    const mint = dark ? '#22383a' : '#baebe2';
+    const parts = [
+        `<rect width="${W}" height="${H}" fill="${bg}"/>`,
+        // 左上 / 右下两块装饰弧，位置固定，整套看起来是同一个模板
+        `<ellipse cx="${W * 0.176}" cy="${-H * 0.068}" rx="${W * 0.472}" ry="${H * 0.224}" fill="${pink}"/>`,
+        `<ellipse cx="${W * 1.028}" cy="${H * 0.99}" rx="${W * 0.269}" ry="${H * 0.146}" fill="${mint}"/>`,
+    ];
+    if (o.title) {
+        const s = fitSize(o.title, W * 0.86, Math.round(W * 0.078), 36);
+        parts.push(`<text x="${W / 2}" y="${H * 0.205}" font-family="${FONT}" font-size="${s}" font-weight="600" fill="${ink}" text-anchor="middle">${esc(o.title)}</text>`);
+    }
+    if (o.subtitle) {
+        const s = Math.round(W * 0.041);
+        parts.push(`<text x="${W / 2}" y="${H * 0.258}" font-family="${FONT}" font-size="${s}" fill="${muted}" text-anchor="middle">${esc(o.subtitle)}</text>`);
+    }
+    if (o.caption) {
+        const s = fitSize(o.caption, W * 0.86, Math.round(W * 0.067), 28);
+        parts.push(`<text x="${W / 2}" y="${H * 0.822}" font-family="${FONT}" font-size="${s}" font-weight="600" fill="${ink}" text-anchor="middle">${esc(o.caption)}</text>`);
+    }
+    if (o.footer) {
+        const s = Math.round(W * 0.031);
+        parts.push(`<text x="${W / 2}" y="${H * 0.925}" font-family="${FONT}" font-size="${s}" fill="${muted}" text-anchor="middle">${esc(o.footer)}</text>`);
+    }
+    return `<svg width="${W}" height="${H}" xmlns="http://www.w3.org/2000/svg">${parts.join('')}</svg>`;
+}
+function run(cmd, args) {
+    return new Promise((resolve) => {
+        const p = spawn(cmd, args);
+        let err = '';
+        p.stderr.on('data', (d) => { err += d.toString(); });
+        p.on('error', (e) => resolve({ code: 1, err: String(e) }));
+        p.on('close', (code) => resolve({ code: code ?? 1, err }));
+    });
+}
+async function hasFfmpeg() {
+    const { code } = await run('ffmpeg', ['-version']);
+    return code === 0;
+}
+export async function makeSlideshow(opts) {
+    if (!opts.images.length)
+        throw new Error('没有输入图片');
+    if (!(await hasFfmpeg()))
+        throw new Error('需要 ffmpeg（brew install ffmpeg）');
+    const sharpMod = await import('sharp').catch(() => null);
+    if (!sharpMod)
+        throw new Error('sharp 不可用。重装 CLI 即可补上：npm install -g museav-cli');
+    const sharp = sharpMod.default ?? sharpMod;
+    const W = opts.width ?? 1080;
+    const H = opts.height ?? 1920;
+    const ART = opts.artSize ?? 520;
+    const sec = opts.seconds ?? 2.5;
+    const theme = opts.theme ?? 'light';
+    const work = await mkdtemp(join(tmpdir(), 'museav-slideshow-'));
+    try {
+        const pages = [];
+        for (let i = 0; i < opts.images.length; i++) {
+            const bg = Buffer.from(pageSvg({
+                width: W, height: H, theme,
+                title: opts.title, subtitle: opts.subtitle,
+                caption: opts.captions?.[i], footer: opts.footer,
+            }));
+            // 贴纸类图片四周常有大片透明留白，直接放大等于把留白也放大、主体显小。
+            // 先裁到主体外接框再放大，画面才撑得住。只对带 alpha 的图做——
+            // 对不透明照片 trim 会去裁纯色边框，那不是这里想要的。
+            let pipe = sharp(opts.images[i]);
+            if (opts.trim !== false && (await pipe.metadata()).hasAlpha) {
+                pipe = sharp(opts.images[i]).trim({ background: { r: 0, g: 0, b: 0, alpha: 0 }, threshold: 8 });
+            }
+            // 显式等比 resize 到 ART：小图必须放大，否则在竖屏里小得可怜
+            const art = await pipe
+                .resize(ART, ART, { fit: 'inside', withoutEnlargement: false, background: { r: 0, g: 0, b: 0, alpha: 0 } })
+                .png()
+                .toBuffer({ resolveWithObject: true });
+            const top = Math.round(H * 0.344 + (H * 0.365 - art.info.height) / 2);
+            const left = Math.round((W - art.info.width) / 2);
+            const page = join(work, `p${String(i).padStart(3, '0')}.png`);
+            await sharp(bg).composite([{ input: art.data, top: Math.max(0, top), left: Math.max(0, left) }]).png().toFile(page);
+            pages.push(page);
+        }
+        // concat demuxer：末页要重复列一次，否则它的 duration 会被忽略
+        const listLines = [];
+        for (const p of pages)
+            listLines.push(`file '${p}'`, `duration ${sec}`);
+        listLines.push(`file '${pages[pages.length - 1]}'`);
+        const listFile = join(work, 'list.txt');
+        await writeFile(listFile, listLines.join('\n') + '\n', 'utf8');
+        const total = pages.length * sec;
+        const args = ['-y', '-v', 'error', '-f', 'concat', '-safe', '0', '-i', listFile];
+        if (opts.music)
+            args.push('-i', opts.music);
+        args.push('-c:v', 'libx264', '-r', '30', '-pix_fmt', 'yuv420p', '-preset', 'medium', '-crf', '22');
+        if (opts.music) {
+            const fadeOut = Math.max(0, total - 1.5);
+            args.push('-af', `atrim=0:${total},afade=t=in:st=0:d=1,afade=t=out:st=${fadeOut}:d=1.5`, '-c:a', 'aac', '-b:a', '128k', '-shortest');
+        }
+        args.push(opts.out);
+        const { code, err } = await run('ffmpeg', args);
+        if (code !== 0)
+            throw new Error(`ffmpeg 失败：${err.trim().slice(0, 400)}`);
+        return { out: opts.out, pages: pages.length, seconds: total };
+    }
+    finally {
+        await rm(work, { recursive: true, force: true }).catch(() => { });
+    }
+}
+export async function fileSize(p) {
+    try {
+        return (await stat(p)).size;
+    }
+    catch {
+        return 0;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "museav-cli",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "MUSE AV 出图中台官方 CLI —— 命令行调中台 API 出图、出视频、读图逆向、图生模板",
   "type": "module",
   "bin": {

package/src/client.ts

@@ -432,6 +432,47 @@ export class StudioClient {
     return r.row
   }
 
+  /** 贴图素材清单（租户级资产，服务端已按调用者权限过滤）。PNG 装饰图，叠加在海报/封面上 */
+  async stickers(): Promise<any[]> {
+    const r = await this.request('stickers')
+    return Array.isArray(r) ? r : []
+  }
+
+  /** 上传贴图素材（不压缩——透明 PNG 压缩会破坏透明通道） */
+  async createSticker(filePath: string, name: string): Promise<any> {
+    const blob = new Blob([new Uint8Array(readFileSync(filePath))])
+    const fd = new FormData()
+    fd.append('file', blob, basename(filePath))
+    fd.append('name', name)
+    return this.request('stickers', { method: 'POST', body: fd })
+  }
+
+  /** 删除贴图素材 */
+  async deleteSticker(id: string): Promise<void> {
+    await this.request(`stickers?id=${encodeURIComponent(id)}`, { method: 'DELETE' })
+  }
+
+  /** 版式模板清单（租户级资产）：封面底图 + 固定描述（{城市}{明星} 占位符） */
+  async posterTemplates(): Promise<any[]> {
+    const r = await this.request('poster-templates')
+    return Array.isArray(r) ? r : []
+  }
+
+  /** 上传版式模板（不压缩，保留封面底图原样） */
+  async createPosterTemplate(filePath: string, name: string, prompt: string): Promise<any> {
+    const blob = new Blob([new Uint8Array(readFileSync(filePath))])
+    const fd = new FormData()
+    fd.append('file', blob, basename(filePath))
+    fd.append('name', name)
+    fd.append('prompt', prompt)
+    return this.request('poster-templates', { method: 'POST', body: fd })
+  }
+
+  /** 删除版式模板 */
+  async deletePosterTemplate(id: string): Promise<void> {
+    await this.request(`poster-templates?id=${encodeURIComponent(id)}`, { method: 'DELETE' })
+  }
+
   /** 提交出图任务，立即返回 jobId */
   async generate(opts: GenerateOptions): Promise<{ jobId: string; trace_id?: string }> {
     // prompt / skill_slug / template_id 三选一：都传时服务端按 prompt > template_id > skill_slug

package/src/commands/poster-templates.ts

@@ -0,0 +1,33 @@
+/**
+ * museav poster-templates —— 版式模板库（租户级资产）。
+ *  封面底图 + 固定描述（{城市} {明星} 占位符），选版式时把城市/明星名填进底图。
+ *  学员做的封面版式保存后全租户共享。
+ */
+import type { StudioClient } from '../client.js'
+
+export async function posterTemplates(client: StudioClient): Promise<void> {
+  const list = await client.posterTemplates()
+  if (!list.length) {
+    process.stderr.write('没有版式模板（可用 museav poster-templates add <底图> --name <名称> --prompt <描述> 保存）\n')
+    return
+  }
+  process.stderr.write(`版式模板（${list.length} 个）:\n`)
+  for (const t of list) {
+    process.stderr.write(`  ${t.id.padEnd(38)} ${String(t.name || '').padEnd(18)} ${String(t.prompt || '').slice(0, 40)}\n`)
+  }
+  process.stderr.write(`\n保存: museav poster-templates add <底图路径> --name <名称> --prompt <描述>\n`)
+  console.log(list.map((t) => t.id).join('\n'))
+}
+
+export async function createPosterTemplate(
+  client: StudioClient,
+  filePath: string,
+  opts: { name: string; prompt: string },
+): Promise<void> {
+  if (!opts.name?.trim()) throw new Error('--name 必填')
+  if (!opts.prompt?.trim()) throw new Error('--prompt 必填，{城市} {明星} 占位符会被替换')
+  const row = await client.createPosterTemplate(filePath, opts.name, opts.prompt)
+  const id = row?.template?.id || row?.id || ''
+  process.stderr.write(`✅ 版式模板已保存：${id}\n`)
+  console.log(id)
+}

package/src/commands/slideshow.ts

@@ -0,0 +1,103 @@
+/** museav slideshow —— 一组图 + 文案 + 配乐 → 竖版短视频。
+ *  纯本地、免登录、不碰中台；stdout 只出产物路径，进度与统计打 stderr。
+ *  排版走 sharp + SVG（中文用系统字体），合成走 ffmpeg，不引入需要编译的重依赖。 */
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { extname, isAbsolute, join, resolve } from 'node:path'
+import { makeSlideshow, fileSize } from '../local-slideshow.js'
+
+const IMG_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp'])
+
+function fmtBytes(n: number): string {
+  return n >= 1048576 ? `${(n / 1048576).toFixed(2)}MB` : `${(n / 1024).toFixed(1)}KB`
+}
+
+/** 入参可以是若干张图，也可以是一个目录（目录内按文件名排序，所以图片建议带序号前缀） */
+async function collectImages(paths: string[]): Promise<string[]> {
+  const out: string[] = []
+  for (const p of paths) {
+    const abs = isAbsolute(p) ? p : resolve(p)
+    let st
+    try {
+      st = await stat(abs)
+    } catch {
+      throw new Error(`路径不存在: ${p}`)
+    }
+    if (st.isDirectory()) {
+      const names = (await readdir(abs))
+        .filter((n) => !n.startsWith('.') && IMG_EXT.has(extname(n).toLowerCase()))
+        .sort((a, b) => a.localeCompare(b, 'zh-Hans-CN', { numeric: true }))
+      if (!names.length) throw new Error(`目录里没有图片: ${p}`)
+      out.push(...names.map((n) => join(abs, n)))
+    } else {
+      out.push(abs)
+    }
+  }
+  return out
+}
+
+export interface SlideshowCmdOpts {
+  out?: string
+  title?: string
+  subtitle?: string
+  footer?: string
+  caption?: string[]
+  captions?: string
+  music?: string
+  sec?: string
+  size?: string
+  art?: string
+  theme?: string
+  trim?: boolean
+}
+
+export async function slideshowCmd(paths: string[], opts: SlideshowCmdOpts): Promise<void> {
+  const images = await collectImages(paths)
+
+  let captions = opts.caption?.length ? [...opts.caption] : []
+  if (opts.captions) {
+    const text = await readFile(opts.captions, 'utf8').catch(() => {
+      throw new Error(`文案文件读不到: ${opts.captions}`)
+    })
+    captions = text.split('\n').map((l) => l.trim()).filter(Boolean)
+  }
+  if (captions.length && captions.length < images.length) {
+    process.stderr.write(`⚠️  文案 ${captions.length} 条少于图片 ${images.length} 张，后面几张不带文字\n`)
+  }
+
+  const sec = opts.sec ? Number(opts.sec) : 2.5
+  if (!Number.isFinite(sec) || sec <= 0) throw new Error('--sec 必须是正数')
+
+  let width = 1080
+  let height = 1920
+  if (opts.size) {
+    const m = /^(\d+)[x×](\d+)$/i.exec(opts.size.trim())
+    if (!m) throw new Error('--size 格式是 宽x高，如 1080x1920')
+    width = Number(m[1])
+    height = Number(m[2])
+  }
+  const artSize = opts.art ? Number(opts.art) : Math.round(width * 0.48)
+  if (!Number.isFinite(artSize) || artSize < 16) throw new Error('--art 至少 16px')
+  const theme = (opts.theme || 'light') as 'light' | 'dark'
+  if (!['light', 'dark'].includes(theme)) throw new Error('--theme 只支持 light / dark')
+
+  const out = opts.out ? resolve(opts.out) : resolve('slideshow.mp4')
+  const total = images.length * sec
+  process.stderr.write(
+    `${images.length} 张 × ${sec}s ≈ ${total.toFixed(0)}s · ${width}×${height}` +
+    (opts.title ? ` · 「${opts.title}」` : '') +
+    (opts.music ? ' · 带配乐' : ' · 无配乐') + '\n',
+  )
+
+  const start = Date.now()
+  const r = await makeSlideshow({
+    images, out, width, height, artSize, seconds: sec, theme, trim: opts.trim,
+    title: opts.title, subtitle: opts.subtitle, footer: opts.footer,
+    captions: captions.length ? captions : undefined,
+    music: opts.music ? resolve(opts.music) : undefined,
+  })
+  process.stderr.write(
+    `✅ 视频生成完成（${r.pages} 页，${r.seconds.toFixed(1)}s，` +
+    `${fmtBytes(await fileSize(out))}，用时 ${((Date.now() - start) / 1000).toFixed(1)}s）\n`,
+  )
+  console.log(out)
+}

package/src/commands/stickers.ts

@@ -0,0 +1,29 @@
+/**
+ * museav stickers —— 贴图素材库（租户级资产）。
+ *  PNG 透明装饰图（logo/花纹/边框），叠加在海报/封面上。
+ *  列出的都是自己租户的贴图；上传用账户 Key 或租户 Key 均可（落到本租户）。
+ */
+import type { StudioClient } from '../client.js'
+
+export async function stickers(client: StudioClient): Promise<void> {
+  const list = await client.stickers()
+  if (!list.length) {
+    process.stderr.write('没有贴图素材（可用 museav stickers add <图片> --name <名称> 上传）\n')
+    return
+  }
+  process.stderr.write(`贴图素材（${list.length} 个）:\n`)
+  for (const s of list) {
+    process.stderr.write(`  ${s.id.padEnd(38)} ${String(s.name || '').padEnd(20)} ${s.url || ''}\n`)
+  }
+  process.stderr.write(`\n上传: museav stickers add <图片路径> --name <名称>\n`)
+  // stdout 只出 id，便于脚本与 agent 解析
+  console.log(list.map((s) => s.id).join('\n'))
+}
+
+export async function createSticker(client: StudioClient, filePath: string, opts: { name: string }): Promise<void> {
+  if (!opts.name?.trim()) throw new Error('--name 必填')
+  const row = await client.createSticker(filePath, opts.name)
+  const id = row?.sticker?.id || row?.id || ''
+  process.stderr.write(`✅ 贴图素材已上传：${id}\n`)
+  console.log(id)
+}

package/src/index.ts

@@ -16,6 +16,7 @@ import { printWelcome } from './commands/welcome.js'
 import { gen } from './commands/gen.js'
 import { reverse } from './commands/reverse.js'
 import { compressCmd, removeBgCmd, upscaleCmd, removeWatermarkCmd } from './commands/img-tools.js'
+import { slideshowCmd } from './commands/slideshow.js'
 import { projects, createProject, listAssets, addAsset, removeAsset, resolveWorkspace } from './commands/projects.js'
 import { imageToTemplate } from './commands/image-to-template.js'
 import { upload } from './commands/upload.js'
@@ -28,6 +29,8 @@ import { jobs } from './commands/jobs.js'
 import { whoami } from './commands/whoami.js'
 import { products } from './commands/products.js'
 import { assets } from './commands/assets.js'
+import { stickers, createSticker } from './commands/stickers.js'
+import { posterTemplates, createPosterTemplate } from './commands/poster-templates.js'
 import { speak, transcribeCmd } from './commands/speak.js'
 
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8')) as { name: string; version: string }
@@ -208,6 +211,23 @@ program
   .option('--overwrite', '允许覆盖已存在的输出文件')
   .action(asyncRun((input: string, opts: any) => removeWatermarkCmd(input, opts)))
 
+program
+  .command('slideshow <图片或目录...>')
+  .description('本地图集转竖版短视频（sharp + ffmpeg，免登录）：默认 1080×1920 / 30fps / H.264，可加标题、逐张文案与配乐。需要本机有 ffmpeg')
+  .option('--out <path>', '输出 mp4（默认当前目录 slideshow.mp4）')
+  .option('--title <text>', '顶部主标题（大字）')
+  .option('--subtitle <text>', '顶部副标题（小字）')
+  .option('--caption <text>', '单页文案，可重复传，按顺序对应每张图', (v: string, acc: string[]) => [...acc, v], [] as string[])
+  .option('--captions <file>', '文案文件（每行一条，按顺序对应每张图），与 --caption 二选一')
+  .option('--footer <text>', '底部引导语')
+  .option('--music <file>', '配乐音频。自动裁到视频长度并加首尾淡入淡出（不会中途硬切断）')
+  .option('--sec <n>', '每张停留秒数，默认 2.5')
+  .option('--size <WxH>', '画面尺寸，默认 1080x1920')
+  .option('--art <px>', '主图渲染边长，默认画面宽的 48%')
+  .option('--theme <name>', 'light（默认）/ dark')
+  .option('--no-trim', '不裁主图四周的透明留白（默认会裁，贴纸类图片不裁会显得很小）')
+  .action(asyncRun((paths: string[], opts: any) => slideshowCmd(paths, opts)))
+
 // 工作区（项目）与项目素材库：平台 → 账户 → 工作区三层归属，素材挂工作区
 const projectsCmd = program
   .command('projects')
@@ -345,6 +365,29 @@ templatesCmd
   .option('--type <type>', '模板类型：image（图片，默认） / article（文字）')
   .action(withClient((client: StudioClient, opts: any) => createTemplate(client, opts)))
 
+const stickersCmd = program
+  .command('stickers')
+  .description('查贴图素材库（租户级资产：PNG 装饰图，叠加在海报/封面上）')
+  .action(withClient((client: StudioClient) => stickers(client)))
+
+stickersCmd
+  .command('add <file>')
+  .description('上传贴图素材（PNG 透明装饰图，不压缩保留透明通道）')
+  .requiredOption('--name <名称>', '贴图名称')
+  .action(withClient((client: StudioClient, file: string, opts: any) => createSticker(client, file, opts)))
+
+const posterTemplatesCmd = program
+  .command('poster-templates')
+  .description('查版式模板库（租户级资产：封面底图 + 固定描述，选版式把城市/明星名填进底图）')
+  .action(withClient((client: StudioClient) => posterTemplates(client)))
+
+posterTemplatesCmd
+  .command('add <file>')
+  .description('保存版式模板（封面底图 + 描述，描述里用 {城市} {明星} 占位）')
+  .requiredOption('--name <名称>', '版式名称')
+  .requiredOption('--prompt <描述>', '版式固定描述，{城市} {明星} 会自动替换')
+  .action(withClient((client: StudioClient, file: string, opts: any) => createPosterTemplate(client, file, opts)))
+
 program
   .command('products')
   .description('查所属租户自己的产品目录（数据在租户自己的后台，不在 Studio 中台；只支持已开通该接口的租户，仅租户 apiKey 身份可用）')

package/src/local-slideshow.ts

@@ -0,0 +1,184 @@
+/**
+ * 本地图集转竖版短视频 —— slideshow 的核心实现。
+ * 一组图 + 每张的文字说明 + 配乐 → 1080×1920 的 mp4，适合发朋友圈 / 视频号 / 小红书。
+ *
+ * 排版走 sharp 渲染 SVG（中文靠系统字体，macOS/Win/主流 Linux 都有中文字体），
+ * 合成走 ffmpeg 的 concat demuxer —— 不引入 canvas 那种要编译的重依赖。
+ *
+ * 三个实测踩出来的点，写在这里免得下次重踩：
+ *
+ * 1. 图片必须显式放大。小图（如 240×240 的表情）直接贴到 1080 宽的画布上只占两成宽，
+ *    画面空得离谱。要按目标尺寸等比 resize，而不是「不超过某上限」那种只缩不放的逻辑。
+ * 2. 配乐不能直接 -shortest。配乐通常比视频长几倍，硬切会在中途断掉。
+ *    要 atrim 裁到视频时长 + 首尾 afade。
+ * 3. concat demuxer 的最后一张要再列一次，否则它的 duration 被忽略，末页一闪而过。
+ */
+import { mkdtemp, writeFile, rm, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { spawn } from 'node:child_process'
+
+export interface SlideshowOpts {
+  images: string[]
+  out: string
+  title?: string
+  subtitle?: string
+  captions?: string[]
+  footer?: string
+  music?: string
+  seconds?: number
+  width?: number
+  height?: number
+  /** 主图渲染尺寸（正方形边长）。默认 520，约占 1080 宽的 48% */
+  artSize?: number
+  theme?: 'light' | 'dark'
+  /** 放大前先裁掉主图四周的透明留白，默认开（仅对带 alpha 的图生效） */
+  trim?: boolean
+}
+
+const FONT = 'Hiragino Sans GB, PingFang SC, Microsoft YaHei, Noto Sans CJK SC, sans-serif'
+
+function esc(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;').replace(/'/g, '&apos;')
+}
+
+/** 中文按全宽算、ASCII 按半宽算，估出一行文字的像素宽，用来收敛字号 */
+function textWidth(s: string, size: number): number {
+  let w = 0
+  for (const ch of s) w += /[一-鿿　-〿＀-￯]/.test(ch) ? size : size * 0.55
+  return w
+}
+
+function fitSize(text: string, max: number, start: number, min = 24): number {
+  let size = start
+  while (size > min && textWidth(text, size) > max) size -= 2
+  return size
+}
+
+function pageSvg(o: Required<Pick<SlideshowOpts, 'width' | 'height'>> & {
+  title?: string; subtitle?: string; caption?: string; footer?: string; theme: 'light' | 'dark'
+}): string {
+  const { width: W, height: H, theme } = o
+  const dark = theme === 'dark'
+  const bg = dark ? '#16181c' : '#ffffff'
+  const ink = dark ? '#e9ebef' : '#2b2d31'
+  const muted = dark ? '#8b929c' : '#8c929b'
+  const pink = dark ? '#3a2b33' : '#ffd6e2'
+  const mint = dark ? '#22383a' : '#baebe2'
+
+  const parts = [
+    `<rect width="${W}" height="${H}" fill="${bg}"/>`,
+    // 左上 / 右下两块装饰弧，位置固定，整套看起来是同一个模板
+    `<ellipse cx="${W * 0.176}" cy="${-H * 0.068}" rx="${W * 0.472}" ry="${H * 0.224}" fill="${pink}"/>`,
+    `<ellipse cx="${W * 1.028}" cy="${H * 0.99}" rx="${W * 0.269}" ry="${H * 0.146}" fill="${mint}"/>`,
+  ]
+  if (o.title) {
+    const s = fitSize(o.title, W * 0.86, Math.round(W * 0.078), 36)
+    parts.push(`<text x="${W / 2}" y="${H * 0.205}" font-family="${FONT}" font-size="${s}" font-weight="600" fill="${ink}" text-anchor="middle">${esc(o.title)}</text>`)
+  }
+  if (o.subtitle) {
+    const s = Math.round(W * 0.041)
+    parts.push(`<text x="${W / 2}" y="${H * 0.258}" font-family="${FONT}" font-size="${s}" fill="${muted}" text-anchor="middle">${esc(o.subtitle)}</text>`)
+  }
+  if (o.caption) {
+    const s = fitSize(o.caption, W * 0.86, Math.round(W * 0.067), 28)
+    parts.push(`<text x="${W / 2}" y="${H * 0.822}" font-family="${FONT}" font-size="${s}" font-weight="600" fill="${ink}" text-anchor="middle">${esc(o.caption)}</text>`)
+  }
+  if (o.footer) {
+    const s = Math.round(W * 0.031)
+    parts.push(`<text x="${W / 2}" y="${H * 0.925}" font-family="${FONT}" font-size="${s}" fill="${muted}" text-anchor="middle">${esc(o.footer)}</text>`)
+  }
+  return `<svg width="${W}" height="${H}" xmlns="http://www.w3.org/2000/svg">${parts.join('')}</svg>`
+}
+
+function run(cmd: string, args: string[]): Promise<{ code: number; err: string }> {
+  return new Promise((resolve) => {
+    const p = spawn(cmd, args)
+    let err = ''
+    p.stderr.on('data', (d) => { err += d.toString() })
+    p.on('error', (e) => resolve({ code: 1, err: String(e) }))
+    p.on('close', (code) => resolve({ code: code ?? 1, err }))
+  })
+}
+
+async function hasFfmpeg(): Promise<boolean> {
+  const { code } = await run('ffmpeg', ['-version'])
+  return code === 0
+}
+
+export async function makeSlideshow(opts: SlideshowOpts): Promise<{ out: string; pages: number; seconds: number }> {
+  if (!opts.images.length) throw new Error('没有输入图片')
+  if (!(await hasFfmpeg())) throw new Error('需要 ffmpeg（brew install ffmpeg）')
+
+  const sharpMod = await import('sharp').catch(() => null)
+  if (!sharpMod) throw new Error('sharp 不可用。重装 CLI 即可补上：npm install -g museav-cli')
+  const sharp = (sharpMod as any).default ?? sharpMod
+
+  const W = opts.width ?? 1080
+  const H = opts.height ?? 1920
+  const ART = opts.artSize ?? 520
+  const sec = opts.seconds ?? 2.5
+  const theme = opts.theme ?? 'light'
+  const work = await mkdtemp(join(tmpdir(), 'museav-slideshow-'))
+
+  try {
+    const pages: string[] = []
+    for (let i = 0; i < opts.images.length; i++) {
+      const bg = Buffer.from(pageSvg({
+        width: W, height: H, theme,
+        title: opts.title, subtitle: opts.subtitle,
+        caption: opts.captions?.[i], footer: opts.footer,
+      }))
+      // 贴纸类图片四周常有大片透明留白，直接放大等于把留白也放大、主体显小。
+      // 先裁到主体外接框再放大，画面才撑得住。只对带 alpha 的图做——
+      // 对不透明照片 trim 会去裁纯色边框，那不是这里想要的。
+      let pipe = sharp(opts.images[i])
+      if (opts.trim !== false && (await pipe.metadata()).hasAlpha) {
+        pipe = sharp(opts.images[i]).trim({ background: { r: 0, g: 0, b: 0, alpha: 0 }, threshold: 8 })
+      }
+      // 显式等比 resize 到 ART：小图必须放大，否则在竖屏里小得可怜
+      const art = await pipe
+        .resize(ART, ART, { fit: 'inside', withoutEnlargement: false, background: { r: 0, g: 0, b: 0, alpha: 0 } })
+        .png()
+        .toBuffer({ resolveWithObject: true })
+      const top = Math.round(H * 0.344 + (H * 0.365 - art.info.height) / 2)
+      const left = Math.round((W - art.info.width) / 2)
+      const page = join(work, `p${String(i).padStart(3, '0')}.png`)
+      await sharp(bg).composite([{ input: art.data, top: Math.max(0, top), left: Math.max(0, left) }]).png().toFile(page)
+      pages.push(page)
+    }
+
+    // concat demuxer：末页要重复列一次，否则它的 duration 会被忽略
+    const listLines: string[] = []
+    for (const p of pages) listLines.push(`file '${p}'`, `duration ${sec}`)
+    listLines.push(`file '${pages[pages.length - 1]}'`)
+    const listFile = join(work, 'list.txt')
+    await writeFile(listFile, listLines.join('\n') + '\n', 'utf8')
+
+    const total = pages.length * sec
+    const args = ['-y', '-v', 'error', '-f', 'concat', '-safe', '0', '-i', listFile]
+    if (opts.music) args.push('-i', opts.music)
+    args.push('-c:v', 'libx264', '-r', '30', '-pix_fmt', 'yuv420p', '-preset', 'medium', '-crf', '22')
+    if (opts.music) {
+      const fadeOut = Math.max(0, total - 1.5)
+      args.push('-af', `atrim=0:${total},afade=t=in:st=0:d=1,afade=t=out:st=${fadeOut}:d=1.5`,
+        '-c:a', 'aac', '-b:a', '128k', '-shortest')
+    }
+    args.push(opts.out)
+
+    const { code, err } = await run('ffmpeg', args)
+    if (code !== 0) throw new Error(`ffmpeg 失败：${err.trim().slice(0, 400)}`)
+    return { out: opts.out, pages: pages.length, seconds: total }
+  } finally {
+    await rm(work, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+export async function fileSize(p: string): Promise<number> {
+  try {
+    return (await stat(p)).size
+  } catch {
+    return 0
+  }
+}