minimal-agent 0.1.9 → 0.3.0

package/plugins/workflow-runner/src/types.js

@@ -0,0 +1,59 @@
+/**
+ * ============================================================
+ *  src/workflows/types.ts —— workflow runner 核心类型
+ * ------------------------------------------------------------
+ *  ralph-loop 让 LLM 自规划；workflow 反过来 —— 外层确定性 step 列表
+ *  驱动执行，LLM 只在 llm: / skill: 节点出场。本文件定义 YAML 解析
+ *  后的内存形态（WorkflowDef / StepDef），以及运行时上下文（VarStack /
+ *  RunContext）和 UI 事件（WorkflowEvent）。
+ *
+ *  与 src/types.ts 关系：WorkflowEvent 是插件**私有**事件，结构上满足
+ *  framework 的 PluginEvent 开放契约（type: string + 任意 payload），
+ *  经 plugin.ts -> pluginRunner 原样透传给 UI；UI 不识别即静默忽略。
+ *  src/types.ts 的 LoopEvent union **不**包含 workflow_*，框架零插件耦合。
+ * ============================================================
+ */
+// ---------------- 2. 变量栈（loop scope 用） ----------------
+/**
+ * 简单的多帧变量栈：
+ *   - 最外层（frame 0）放 inputs + 全局变量
+ *   - 进入 loop 时 push() 新帧，存当前迭代的 as / as_idx
+ *   - 退出 loop 时 pop()
+ *
+ * get(key) 从栈顶往下找第一个匹配的 frame，类似 JS 的 lexical scope。
+ */
+export class VarStack {
+    frames = [{}];
+    set(key, val) {
+        this.frames[this.frames.length - 1][key] = val;
+    }
+    /** 写到栈底（root frame），用于 inputs / 全局常量 */
+    setGlobal(key, val) {
+        this.frames[0][key] = val;
+    }
+    get(key) {
+        for (let i = this.frames.length - 1; i >= 0; i--) {
+            if (key in this.frames[i])
+                return this.frames[i][key];
+        }
+        return undefined;
+    }
+    has(key) {
+        for (let i = this.frames.length - 1; i >= 0; i--) {
+            if (key in this.frames[i])
+                return true;
+        }
+        return false;
+    }
+    push() {
+        this.frames.push({});
+    }
+    pop() {
+        if (this.frames.length > 1)
+            this.frames.pop();
+    }
+    /** 合并所有帧为一个普通对象（外层覆盖内层），用于 vars 持久化与事件 */
+    snapshot() {
+        return Object.assign({}, ...this.frames);
+    }
+}

package/plugins/workflow-runner/src/workflowState.js

@@ -0,0 +1,46 @@
+/**
+ * ============================================================
+ *  src/workflows/workflowState.ts —— workflow 运行状态持久化
+ * ------------------------------------------------------------
+ *  与 GoalState 类似的轻量目录模型，但只用于 debug / 中断恢复（P0 不实现
+ *  恢复，只写出现场）。目录结构：
+ *
+ *    <cwd>/.minimal-agent-workflow/
+ *      ├── current.json    # { name, startedAt }
+ *      ├── inputs.json     # 用户传入的 inputs 快照
+ *      ├── vars.json       # 最后一次成功 step 后的 VarStack.snapshot()
+ *      └── progress.md     # 时间戳追加的 step 完成日志
+ *
+ *  init() 进 workflow 前 reset 一次；cleanup() 在 finally 把文件删掉
+ *  + rmdir（保持 /new 扫描 .minimal-agent-* 子目录的语义一致）。
+ *
+ *  与 GoalState 的核心区别：workflow 不需要 PHASE / completion / learnings 文件，
+ *  因为执行流程是确定性的，没有 LLM 自规划过程。
+ * ============================================================
+ */
+import { mkdir, writeFile, appendFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+const STATE_DIR = '.minimal-agent-workflow';
+export class WorkflowState {
+    dir;
+    constructor(workingDir) {
+        this.dir = join(workingDir, STATE_DIR);
+    }
+    async init(name, inputs) {
+        await rm(this.dir, { recursive: true, force: true });
+        await mkdir(this.dir, { recursive: true });
+        await writeFile(join(this.dir, 'current.json'), JSON.stringify({ name, startedAt: new Date().toISOString() }, null, 2), 'utf8');
+        await writeFile(join(this.dir, 'inputs.json'), JSON.stringify(inputs, null, 2), 'utf8');
+        await writeFile(join(this.dir, 'progress.md'), `# ${name}\n\n`, 'utf8');
+    }
+    async appendProgress(line) {
+        const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+        await appendFile(join(this.dir, 'progress.md'), `- ${ts} ${line}\n`, 'utf8').catch(() => { });
+    }
+    async writeVars(snapshot) {
+        await writeFile(join(this.dir, 'vars.json'), JSON.stringify(snapshot, null, 2), 'utf8').catch(() => { });
+    }
+    async cleanup() {
+        await rm(this.dir, { recursive: true, force: true }).catch(() => { });
+    }
+}

package/skills/image-gen-openrouter/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: image-gen-openrouter
+description: 当用户说"生成图片"、"画一张图"、"配图"、"OpenRouter 生图"、"nano banana"、"image-gen-openrouter"，或在 workflow 里要按提示词生成图片时使用。调用 OpenRouter 的 Chat Completions 接口（OpenAI 兼容 + image modalities），按提示词生成任意比例图片并落盘。
+---
+
+# image-gen-openrouter —— OpenRouter 文生图
+
+> 这是一个**通用 skill**，不绑定特定场景。任何需要文生图的 workflow / 用户对话都能调它。
+
+## 输入约定
+
+调用方传一行 `key=value` 字段串，**字段顺序无要求**，例：
+
+```
+prompt=A cat reading a book in cyberpunk neon city output=./assets/img_0.png aspect=9:16 size=4K model=google/gemini-3-pro-image-preview key=sk-or-...
+```
+
+字段定义：
+- **prompt**（必填）：图片提示词（建议英文，效果更好）。可包含空格 —— 用"剩余串"策略解析（先把其它已知字段抠出去，剩下的就是 prompt）
+- **output**（必填）：目标图片路径（相对 cwd 或绝对）
+- **aspect**（可选，默认 `1:1`）：宽高比；OpenRouter 支持 `1:1` / `2:3` / `3:2` / `3:4` / `4:3` / `4:5` / `5:4` / `9:16` / `16:9` / `21:9` 等
+- **size**（可选，默认 `1K`）：分辨率；可选 `0.5K` / `1K` / `2K` / `4K`（部分模型不支持 4K，限流时自动降级）
+- **model**（可选，默认 `google/gemini-3-pro-image-preview`）—— Nano Banana Pro，质量最好；备选 `google/gemini-3.1-flash-image-preview`（便宜）、`google/gemini-2.5-flash-image`（兜底）
+- **key**（可选）：API key；不传则用环境变量 `OPENROUTER_API_KEY`
+
+## 标准执行流程
+
+### 1. 解析输入
+
+仔细从 step.input 里提取 4 个字段。注意 prompt 可能包含空格，所以按"先取 output= / model= / key= 之外的部分作为 prompt"的策略最稳妥。
+
+如果你拿不到 prompt 或 output，立刻报错并返回。
+
+### 2. 取 API key
+
+按优先级：
+1. step.input 里的 `key=` 字段
+2. 用 Bash 跑 `echo "$OPENROUTER_API_KEY"` 看环境变量
+
+两者都空 → 报错 "OpenRouter API key 未配置（既不在 step.input 也不在 OPENROUTER_API_KEY 环境变量）" 并退出。
+
+### 3. 调 OpenRouter API
+
+用 Bash 跑 curl（**注意把变量替换成实际值**）：
+
+```bash
+curl -sS https://openrouter.ai/api/v1/chat/completions \
+  -H "Authorization: Bearer <YOUR_KEY>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "<MODEL>",
+    "messages": [{"role": "user", "content": "<PROMPT>"}],
+    "modalities": ["image", "text"],
+    "image_config": {"aspect_ratio": "<ASPECT>", "image_size": "<SIZE>"}
+  }' \
+  -o /tmp/openrouter_resp.json
+```
+
+> 💡 prompt 里若含双引号/特殊字符，用 jq 拼 JSON（**推荐**）：
+> ```bash
+> jq -n --arg p "$PROMPT" --arg m "$MODEL" --arg a "$ASPECT" --arg s "$SIZE" \
+>   '{model:$m, messages:[{role:"user", content:$p}], modalities:["image","text"], image_config:{aspect_ratio:$a, image_size:$s}}' \
+>   | curl -sS https://openrouter.ai/api/v1/chat/completions \
+>       -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
+>       --data-binary @- -o /tmp/openrouter_resp.json
+> ```
+
+### 4. 提取 base64 并解码到 PNG
+
+OpenRouter 返回结构（关键字段）：
+```
+.choices[0].message.images[0].image_url.url  →  "data:image/png;base64,iVBORw0KG..."
+```
+
+**Linux/macOS/git-bash on Windows：**
+```bash
+mkdir -p "$(dirname <OUTPUT>)"
+jq -r '.choices[0].message.images[0].image_url.url' /tmp/openrouter_resp.json \
+  | sed 's|^data:image/[a-z]*;base64,||' \
+  | base64 -d > <OUTPUT>
+```
+
+**Windows PowerShell（base64 -d 不存在时）：**
+```powershell
+powershell -NoProfile -Command "$resp = Get-Content /tmp/openrouter_resp.json -Raw | ConvertFrom-Json; $url = $resp.choices[0].message.images[0].image_url.url; $b64 = $url -replace '^data:image/[a-z]+;base64,',''; [IO.File]::WriteAllBytes('<OUTPUT>', [Convert]::FromBase64String($b64))"
+```
+
+### 5. 校验产物
+
+用 Read 工具读 `<OUTPUT>`（offset=0 limit=1）— 触发文件类型嗅探；如果工具报"二进制"或文件 size > 1KB 就视为成功，否则失败。
+
+或者更直接：用 Bash 跑 `ls -la <OUTPUT> | awk '{print $5}'`，size > 10000 字节算成功。
+
+### 6. 处理错误
+
+如果 curl 失败 / OpenRouter 返回 error / base64 解码失败 / 产物太小：
+- 打印 `/tmp/openrouter_resp.json` 头 500 字节（用 Bash `head -c 500`）帮助 debug
+- 如果是 429 限流，sleep 5s 重试一次
+- 仍然失败 → 输出 "image-gen-openrouter 失败：<原因>" 并返回（不要继续往下走）
+
+### 7. 收尾输出
+
+成功后输出**一行** summary（机器友好，方便上游 capture / regex 提取）：
+```
+saved: <OUTPUT> (model=<MODEL>, aspect=<ASPECT>, size=<BYTES>)
+```
+
+## 模型选型快速参考
+
+| 模型 ID | 代号 | 单图成本 | 备注 |
+|---|---|---|---|
+| `google/gemini-3-pro-image-preview` | Nano Banana Pro | 高 | 4K，质量最好，默认 |
+| `google/gemini-3.1-flash-image-preview` | Nano Banana 2 | 中 | 平衡，限流时降级 |
+| `google/gemini-2.5-flash-image` | Nano Banana | 低 | 兜底 |
+
+## 注意事项
+
+- **不要把 API key 打到日志或最终输出里**，curl 错误信息也要小心 grep 掉
+- **不要重试超过 1 次** — 429 / 5xx 各最多 1 次重试，避免烧钱
+- 中文提示词模型可以理解，但效果不如英文 —— 如果调用方给的是中文 prompt，可以保留，但**不要主动翻译**（让上游负责）
+- 调用方决定 `aspect` 和 `size`；本 skill 不做任何场景假设（不绑定竖屏/横屏）

package/skills/subtitle-srt/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: subtitle-srt
+description: 当用户说"生成字幕"、"做 SRT"、"字幕文件"、"subtitle-srt"，或在 workflow 里要把分段文本 + 时长信息转成标准 SRT 字幕文件时使用。给定 cue 列表（每条带文本和起止时间或时长），生成符合 SRT 规范的字幕文件。
+---
+
+# subtitle-srt —— SRT 字幕生成
+
+> 通用 skill，不绑定语种 / 不绑定视频比例 / 不绑定字体（字体是视频合成阶段的事）。
+
+## 输入约定
+
+支持两种输入形态：
+
+### 形态 A：cues_json（一次性给所有 cue）
+
+```
+cues_json=<JSON 数组> output=./subs.srt [encoding=utf-8]
+```
+
+`cues_json` 是合法 JSON 数组，每个元素至少有 `text`，时间可以两种方式给：
+
+```json
+[
+  {"text": "开场白", "start": 0.0, "end": 3.5},
+  {"text": "第二幕", "start": 3.5, "end": 7.7}
+]
+```
+
+或者只给时长，由本 skill 自动累加：
+
+```json
+[
+  {"text": "开场白", "duration": 3.5},
+  {"text": "第二幕", "duration": 4.2}
+]
+```
+
+### 形态 B：texts + durations（两个并列数组）
+
+```
+texts=<JSON 字符串数组> durations=<逗号分隔秒数> output=./subs.srt
+```
+
+例：
+```
+texts=["开场白","第二幕","第三幕"] durations=3.5,4.2,3.0 output=./subs.srt
+```
+
+> 形态 B 比形态 A 易写，适合 workflow 里用 capture 拼出的简单场景。
+
+## 标准执行流程
+
+### 1. 解析输入
+
+判断是哪种形态：含 `cues_json=` 字段走 A，含 `texts=` + `durations=` 走 B。两者都不满足 → 报错。
+
+### 2. 计算每条 cue 的起止时间戳
+
+如果给了 `start` + `end`（形态 A 第一种），直接用。
+
+否则按 `duration` 累加：
+- cue 1: start=0.0, end=duration[0]
+- cue 2: start=end[0], end=start[1]+duration[1]
+- ...
+
+### 3. 时间戳格式转换
+
+SRT 时间戳格式：`HH:MM:SS,mmm`（毫秒前**用逗号不用点**）。
+
+公式：
+```
+total_ms = round(seconds * 1000)
+hh = total_ms // 3600000
+mm = (total_ms % 3600000) // 60000
+ss = (total_ms % 60000) // 1000
+ms = total_ms % 1000
+formatted = f"{hh:02d}:{mm:02d}:{ss:02d},{ms:03d}"
+```
+
+### 4. 拼 SRT 内容
+
+每条 cue 4 行（序号 / 时间戳 / 文本 / 空行）：
+
+```
+1
+00:00:00,000 --> 00:00:03,500
+开场白
+
+2
+00:00:03,500 --> 00:00:07,700
+第二幕
+
+```
+
+> ⚠️ 最后一条 cue 末尾**也要有空行**，否则部分播放器会吞掉最后一句。
+
+### 5. 写入文件
+
+用 Write 工具：
+- `file_path = OUTPUT`
+- `content = <上面拼好的 SRT 字符串>`
+
+或者用 Bash + heredoc（注意编码，Windows 上要保证 UTF-8 无 BOM）：
+```bash
+mkdir -p "$(dirname "$OUTPUT")"
+cat > "$OUTPUT" <<'EOF'
+1
+00:00:00,000 --> 00:00:03,500
+开场白
+
+EOF
+```
+
+### 6. 自检（可选）
+
+如果机器有 ffprobe，跑一下确认字幕可读：
+```bash
+ffprobe -v error -loglevel error -i "$OUTPUT" 2>&1 || echo "ffprobe 验证未通过：$?"
+```
+
+ffprobe 失败不算硬错（部分版本对 SRT 解析比较宽松），但要打印 warning。
+
+### 7. 收尾输出
+
+```
+saved: <OUTPUT> (cues=<N>, duration=<TOTAL_SEC>s)
+```
+
+## 注意事项
+
+- 长文本自动换行：单 cue 文本超过 ~30 字时，在自然标点处插入换行（`，` / `。` / `？` / `！`）。SRT 单条多行用真实换行符即可
+- **不打印用户文本内容到日志**（隐私）
+- 字符编码强制 UTF-8 无 BOM；Windows PowerShell 写文件时显式 `-Encoding utf8`
+- 不假设语种 —— 中英日韩都按字符长度判断换行（中文 1 字符 ≈ 英文 2 字符的视觉宽度，可按 30 字符切）

package/skills/tts-zh/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: tts-zh
+description: 当用户说"中文配音"、"中文 TTS"、"语音合成"、"文字转语音"、"tts-zh"，或在 workflow 里要把中文文本转成 mp3 时使用。优先用 MiniMax T2A API，失败时 fallback 到 edge-tts 离线方案，输出 mp3 到指定路径。
+---
+
+# tts-zh —— 中文 TTS（minimax 主 + edge-tts 兜底）
+
+## 输入约定
+
+调用方传一行 `key=value` 字段串：
+
+```
+text=今天天气真好 output=./assets/audio_0.mp3 voice=female-shaonv speed=1.0
+```
+
+字段：
+- **text**（必填）：要合成的中文文本（短句，≤200 字）
+- **output**（必填）：目标 mp3 路径
+- **voice**（可选，默认 `female-shaonv`）：minimax 嗓音 id；edge-tts 走 `zh-CN-XiaoxiaoNeural` 不受 voice 字段影响
+- **speed**（可选，默认 `1.0`）：语速 0.5–2.0
+
+## 标准执行流程
+
+### 1. 解析输入
+
+仔细取 text / output / voice / speed。text 可能包含空格甚至标点，按"剩余串"策略提取。
+
+### 2. 优先尝试 MiniMax T2A
+
+#### 2.1 取 key + group id
+
+```bash
+KEY="$MINIMAX_API_KEY"
+GROUP="$MINIMAX_GROUP_ID"
+```
+
+如果两个都不空，进入 2.2；任一为空，**直接跳到第 3 步（edge-tts fallback）**，不算错误。
+
+#### 2.2 调 API
+
+minimax T2A v2 接口：
+
+```bash
+jq -n --arg t "$TEXT" --arg v "$VOICE" --argjson s "$SPEED" \
+  '{model:"speech-01", text:$t, voice_setting:{voice_id:$v, speed:$s}, audio_setting:{format:"mp3"}}' \
+  | curl -sS "https://api.minimax.chat/v1/t2a_v2?GroupId=$GROUP" \
+      -H "Authorization: Bearer $KEY" \
+      -H "Content-Type: application/json" \
+      --data-binary @- \
+      -o /tmp/minimax_resp.json
+```
+
+> ⚠️ MINIMAX_BASE_URL 可能不是 `api.minimax.chat`（用户也许配了自定义网关）。如果 env 里有 `MINIMAX_BASE_URL`，用它替换 `https://api.minimax.chat`，否则用默认。
+
+#### 2.3 解析响应
+
+minimax 返回里音频是 hex 字符串：
+```
+.data.audio  →  "ff f3 e4 ..."（hex 编码的 mp3 字节流）
+```
+
+解码到文件：
+```bash
+mkdir -p "$(dirname "$OUTPUT")"
+jq -r '.data.audio' /tmp/minimax_resp.json | xxd -r -p > "$OUTPUT"
+```
+
+> 如果 `xxd` 不可用（部分 Windows），用 PowerShell：
+> ```powershell
+> $resp = Get-Content /tmp/minimax_resp.json -Raw | ConvertFrom-Json
+> $hex = $resp.data.audio
+> $bytes = New-Object byte[] ($hex.Length / 2)
+> for ($i = 0; $i -lt $bytes.Length; $i++) { $bytes[$i] = [Convert]::ToByte($hex.Substring($i*2, 2), 16) }
+> [IO.File]::WriteAllBytes('<OUTPUT>', $bytes)
+> ```
+
+#### 2.4 校验
+
+```bash
+SIZE=$(stat -c%s "$OUTPUT" 2>/dev/null || stat -f%z "$OUTPUT")
+```
+
+- `SIZE > 1000` → 成功，输出 `saved: <OUTPUT> (provider=minimax, size=<SIZE>)`，结束
+- `SIZE < 1000` 或文件不存在 → 视为失败，**进入第 3 步 edge-tts fallback**
+
+### 3. Fallback 到 edge-tts
+
+#### 3.1 确认 edge-tts 可用
+
+```bash
+pip show edge-tts >/dev/null 2>&1 || pip install --user edge-tts
+which edge-tts || python -m edge_tts --help >/dev/null 2>&1 || true
+```
+
+如果 pip / python 都没有，**报错退出**："tts-zh 失败：minimax 不可用且本机无 Python，无法 fallback 到 edge-tts。请配置 MINIMAX_API_KEY + MINIMAX_GROUP_ID 或安装 Python + edge-tts"
+
+#### 3.2 跑 edge-tts
+
+```bash
+edge-tts --voice zh-CN-XiaoxiaoNeural --rate "+0%" --text "$TEXT" --write-media "$OUTPUT"
+# 或：
+python -m edge_tts --voice zh-CN-XiaoxiaoNeural --text "$TEXT" --write-media "$OUTPUT"
+```
+
+> 语速换算：minimax 的 speed=1.0 ↔ edge-tts 的 `--rate "+0%"`；speed=1.2 ↔ `--rate "+20%"`；speed=0.8 ↔ `--rate "-20%"`。
+> 公式：`rate = ((speed - 1.0) * 100)` 取整，前面加 `+` 或 `-`。
+
+#### 3.3 校验
+
+同 2.4 步骤；size > 1000 → 成功，输出 `saved: <OUTPUT> (provider=edge-tts, size=<SIZE>)`。
+
+仍然失败 → 报错 "tts-zh 失败：minimax 和 edge-tts 都不工作"
+
+## 嗓音速查
+
+### MiniMax 常用 voice_id
+
+| voice_id | 描述 |
+|---|---|
+| `female-shaonv` | 少女音（默认，自然清亮） |
+| `male-qn-jingying` | 精英男声（沉稳） |
+| `female-tianmei` | 甜美女声 |
+| `audiobook_male_1` | 有声书男声 |
+
+### edge-tts（兜底，固定）
+
+| voice | 描述 |
+|---|---|
+| `zh-CN-XiaoxiaoNeural` | 默认女声（自然） |
+| `zh-CN-YunxiNeural` | 男声 |
+
+## 注意事项
+
+- **不打印 API key / GroupId 到任何日志**
+- text 含特殊 shell 字符（`$ "  '` 等）时务必走 jq 拼 JSON，**不要直接拼字符串到 curl 命令里**
+- 输出 mp3 时长会因为文本长度而变 —— 不要硬假设时长，下游 ffprobe 实际测量
+- 一次只合成一句；若调用方传超过 200 字，让它分多次调用

package/skills/video-compose/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: video-compose
+description: 当用户说"合成视频"、"做 mp4"、"图片转视频"、"ffmpeg 拼视频"、"video-compose"，或在 workflow 里要把图片序列 + 可选音轨 + 可选字幕合成成 mp4 时使用。本 skill 是 ffmpeg 的 declarative 封装，所有参数（分辨率、字体、码率、转场）都可配置，不绑定特定视频格式。
+---
+
+# video-compose —— 通用 ffmpeg 视频合成
+
+> 通用 skill，可被任何 workflow 调用。无场景假设（不绑定竖屏/横屏，不绑定语言）。
+
+## 输入约定
+
+调用方传一行 `key=value` 字段串，必填项 + 可选项混合：
+
+```
+images_glob=./assets/img_*.png audio=./assets/audio.mp3 srt=./assets/subs.srt output=./out/video.mp4 width=1080 height=1920 per_image_duration=3 fps=30 font=Microsoft YaHei font_size=42
+```
+
+### 必填
+
+- **images_glob**：图片 glob 表达式（用 Glob 工具枚举，按文件名排序）
+- **output**：目标 mp4 路径
+
+### 可选
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| **audio** | （无） | 音轨 mp3/wav；不传则纯视频无声 |
+| **srt** | （无） | 字幕文件；不传则不烧入字幕 |
+| **width** × **height** | `1080` × `1920` | 输出分辨率（默认竖屏；横屏传 `1920` × `1080`） |
+| **per_image_duration** | `3` | 每张图片显示秒数（如果给 audio，可能会被覆盖 —— 见下方"对齐音轨"） |
+| **fps** | `30` | 帧率 |
+| **font** | `Microsoft YaHei`（Win）/ `PingFang SC`（Mac）/ `Noto Sans CJK SC`（Linux） | 字幕字体 |
+| **font_size** | `42` | 字幕字号 |
+| **font_color** | `FFFFFF` | 字幕颜色（RGB hex） |
+| **align_audio** | `auto` | `auto`=按音轨长度等分图片时长 / `fixed`=固定 `per_image_duration` / `cut`=超出部分截断 |
+| **crf** | `23` | x264 质量（18–28，越低越清） |
+
+## 标准执行流程
+
+### 1. 前置检查
+
+```bash
+which ffmpeg >/dev/null || { echo "缺少 ffmpeg，请安装：winget install Gyan.FFmpeg / brew install ffmpeg / apt install ffmpeg"; exit 1; }
+which ffprobe >/dev/null || { echo "缺少 ffprobe（通常和 ffmpeg 一起装）"; exit 1; }
+```
+
+### 2. 收集图片列表
+
+用 Glob 工具按 `images_glob` 找文件 → 按文件名 ASCII 排序。如果只有 0 或 1 张图，**报错退出**（视频至少要 2 帧才有意义）。
+
+### 3. 决定每张图时长
+
+- 如果**有 audio** 且 `align_audio=auto`（默认）：
+  - 用 `ffprobe -v error -show_entries format=duration -of csv=p=0 <audio>` 拿音轨时长 `T`
+  - 单图时长 = `T / 图片数`
+- 否则：每张图固定 `per_image_duration` 秒
+
+### 4. 生成 concat 列表
+
+ffmpeg concat demuxer 用法：
+
+```bash
+mkdir -p "$(dirname "$OUTPUT")"
+LIST=/tmp/video_compose_list.txt
+> "$LIST"
+for f in $(ls $IMAGES_GLOB | sort); do
+  echo "file '$f'" >> "$LIST"
+  echo "duration $PER_IMG" >> "$LIST"
+done
+# ffmpeg quirk：最后一张图片要再列一次（不带 duration）才会被显示完整时长
+LAST=$(ls $IMAGES_GLOB | sort | tail -n1)
+echo "file '$LAST'" >> "$LIST"
+```
+
+### 5. 合成视频流（可选烧字幕）
+
+无字幕版本：
+```bash
+ffmpeg -y -f concat -safe 0 -i "$LIST" \
+  -vf "scale=${WIDTH}:${HEIGHT}:force_original_aspect_ratio=increase,crop=${WIDTH}:${HEIGHT},fps=${FPS}" \
+  -c:v libx264 -crf ${CRF} -pix_fmt yuv420p /tmp/video_only.mp4
+```
+
+带字幕版本（filter 链尾加 subtitles 滤镜）：
+```bash
+ffmpeg -y -f concat -safe 0 -i "$LIST" \
+  -vf "scale=${WIDTH}:${HEIGHT}:force_original_aspect_ratio=increase,crop=${WIDTH}:${HEIGHT},fps=${FPS},subtitles=${SRT}:force_style='Fontname=${FONT},Fontsize=${FONT_SIZE},PrimaryColour=&H00${FONT_COLOR}&,Outline=2,BorderStyle=1'" \
+  -c:v libx264 -crf ${CRF} -pix_fmt yuv420p /tmp/video_only.mp4
+```
+
+> ⚠️ Windows 路径里反斜杠 `\` 会被 ffmpeg subtitles 滤镜当转义字符吃掉。**字幕路径强制用正斜杠 `/`**，或者 `\\:` 转义盘符冒号。
+
+### 6. 合入音轨（如果有）
+
+```bash
+if [ -n "$AUDIO" ]; then
+  ffmpeg -y -i /tmp/video_only.mp4 -i "$AUDIO" \
+    -c:v copy -c:a aac -b:a 192k \
+    -shortest "$OUTPUT"
+else
+  cp /tmp/video_only.mp4 "$OUTPUT"
+fi
+```
+
+### 7. 校验产物
+
+```bash
+ffprobe -v error -show_entries stream=codec_type,duration -of default=noprint_wrappers=1 "$OUTPUT"
+SIZE=$(stat -c%s "$OUTPUT" 2>/dev/null || stat -f%z "$OUTPUT")
+```
+
+- 文件存在且 size > 100KB
+- 至少有 1 个 video 流；如果传了 audio 还应该有 1 个 audio 流
+- 总时长 > 1 秒
+
+任一项不满足 → 报错并打印 ffprobe 输出供 debug。
+
+### 8. 收尾输出
+
+```
+saved: <OUTPUT> (resolution=<WIDTH>x<HEIGHT>, duration=<DUR>s, size=<MB>MB)
+```
+
+## 字体路径速查
+
+| OS | 字体名（filter 用） | 实际文件 |
+|---|---|---|
+| Windows | `Microsoft YaHei` 或 `SimHei` | `C:\Windows\Fonts\msyh.ttc` |
+| macOS | `PingFang SC` | `/System/Library/Fonts/PingFang.ttc` |
+| Linux | `Noto Sans CJK SC` | `/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc` |
+
+如果 force_style 找不到字体，会 fallback 到 Arial（中文会变方块），用 `fc-list :lang=zh-cn` 看本机有哪些中文字体。
+
+## 注意事项
+
+- **ffmpeg 滤镜里的引号嵌套很难写**：双引号包围整个 `-vf` 值，里面用单引号；force_style 的 key=value 用 `=` 不要用空格
+- subtitles 滤镜路径必须**用正斜杠**，盘符冒号转义成 `\\:`（Win 上 `C:/path/x.srt` → `C\\:/path/x.srt`）
+- 不接受**纯静态图片**作输入 —— 至少 2 张才合理；如果调用方只有 1 张图，让它用 ffmpeg `-loop 1` 单独处理（不走本 skill）
+- 不假设视频用途（短视频 / 长视频 / 横屏 / 竖屏 / 方形）—— 全部走参数

package/src/bootstrap/cwdArg.js

@@ -0,0 +1,22 @@
+/**
+ * ============================================================
+ *  src/bootstrap/cwdArg.ts —— `-d` / `--cwd` 参数解析
+ * ------------------------------------------------------------
+ *  抽出来是为了让 main.tsx 之外能 import 这个纯函数做单测，
+ *  而不会触发 main.tsx 顶层的 main().catch(...) 副作用。
+ *
+ *  使用约定：在 initWorkingDir() 之前调一次。匹配到则建目录 + chdir。
+ * ============================================================
+ */
+/**
+ * 扫 argv 找 `-d <dir>` / `--cwd <dir>`；只取第一个匹配。
+ * 找不到返回 null。
+ */
+export function extractCwdArg(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '-d' || argv[i] === '--cwd') {
+            return argv[i + 1] ?? null;
+        }
+    }
+    return null;
+}