@optima-chat/optima-agent 0.9.7 → 0.9.9

package/.claude/settings.local.json

@@ -0,0 +1,166 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh api:*)",
+      "WebFetch(domain:platform.claude.com)",
+      "Bash(git init:*)",
+      "Bash(mkdir:*)",
+      "Bash(npm run typecheck:*)",
+      "Bash(npm view:*)",
+      "WebSearch",
+      "Bash(commerce --help)",
+      "Bash(done)",
+      "Bash(commerce product:*)",
+      "Bash(commerce order:*)",
+      "Bash(commerce i18n:*)",
+      "Bash(google-ads:*)",
+      "Bash(scout --help:*)",
+      "Bash(tree:*)",
+      "Bash(cloc:*)",
+      "Bash(npm run build:*)",
+      "Bash(git restore:*)",
+      "Bash(gh repo view:*)",
+      "Bash(mv:*)",
+      "Bash(rmdir:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push)",
+      "Bash(timeout 5 npm run optima:*)",
+      "Bash(npm install:*)",
+      "Bash(cat:*)",
+      "Bash(gh issue create:*)",
+      "Bash(npx tsx:*)",
+      "Bash(timeout 30 npx tsx:*)",
+      "Bash(git push origin feature/ask-user-question)",
+      "Bash(node:*)",
+      "Bash(npm version:*)",
+      "Bash(git push:*)",
+      "Bash(npm publish:*)",
+      "Bash(pkill:*)",
+      "Bash(git -C /Users/verypro/optima-agent log --oneline --all -- \".claude/\")",
+      "Bash(wc:*)",
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(commerce collection --help:*)",
+      "Bash(commerce collection update --help:*)",
+      "Bash(commerce collection set-cover:*)",
+      "Bash(commerce collection get --help:*)",
+      "Bash(commerce collection list --help:*)",
+      "Bash(commerce collection create --help:*)",
+      "Bash(commerce collection remove-products:*)",
+      "Bash(commerce collection list-products:*)",
+      "Bash(commerce --version:*)",
+      "Bash(bi-cli --version:*)",
+      "Bash(commerce homepage create --help:*)",
+      "Bash(commerce homepage reorder --help:*)",
+      "Bash(commerce homepage delete --help:*)",
+      "Bash(commerce homepage update-images:*)",
+      "Bash(commerce homepage update-collections:*)",
+      "Bash(commerce homepage update-target:*)",
+      "Bash(commerce homepage switch-template:*)",
+      "Bash(commerce inventory:*)",
+      "Bash(commerce merchant:*)",
+      "Bash(commerce review:*)",
+      "Bash(commerce product-page:*)",
+      "Bash(bi-cli:*)",
+      "Bash(comfy:*)",
+      "Bash(scout search:*)",
+      "Bash(scout product:*)",
+      "Bash(commerce homepage create-collections:*)",
+      "Bash(commerce homepage create-featured:*)",
+      "Bash(commerce homepage create-collection-products:*)",
+      "Bash(commerce homepage create-banner:*)",
+      "Bash(xargs -I {} sh -c 'echo \"\"\"\"=== {} ===\"\"\"\"; head -3 /Users/verypro/optima-agent/.claude/skills/{}/SKILL.md | grep \"\"\"\"name:\"\"\"\"')",
+      "Bash(ls:*)",
+      "Bash(gh issue view:*)",
+      "Bash(npx markdownlint-cli:*)",
+      "Bash(chmod:*)",
+      "Bash(npm whoami:*)",
+      "Bash(tsx test-scripts/test-headless-progress.ts:*)",
+      "Bash(DEBUG_STREAM=1 node dist/bin/optima.js:*)",
+      "Bash(git describe:*)",
+      "WebFetch(domain:github.com)",
+      "Bash(./scripts/test-headless.sh:*)",
+      "Bash(./scripts/test-headless-simple.sh:*)",
+      "Bash(env)",
+      "Bash(gh pr list:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh pr diff:*)",
+      "Bash(optima --version:*)",
+      "Bash(optima agent headless:*)",
+      "Bash(optima headless:*)",
+      "Bash(/Users/verypro/optima-agent/scripts/test-headless.sh:*)",
+      "Bash(/Users/verypro/optima-agent/scripts/test-headless-simple.sh:*)",
+      "Bash(tee:*)",
+      "Bash(CONV_ID=\"conv-1\":*)",
+      "Bash(echo:*)",
+      "Bash(scout tiktok trending --help:*)",
+      "Bash(scout tiktok trending:*)",
+      "Bash(git checkout:*)",
+      "Bash(npm test:*)",
+      "Bash(git tag:*)",
+      "Bash(/private/tmp/claude/-Users-verypro-optima-agent/68a9ac2c-def2-44e1-b42b-e53bd9022ab6/scratchpad/test-canUseTool.sh)",
+      "Bash(optima --help:*)",
+      "Bash(npx @optima-chat/ads-cli:*)",
+      "Bash(head:*)",
+      "Bash(git pull:*)",
+      "Bash(pnpm build:*)",
+      "Skill(read-code)",
+      "Bash(npm run cli:*)",
+      "Bash(scout:*)",
+      "WebFetch(domain:docs.scrapecreators.com)",
+      "WebFetch(domain:scrapecreators.com)",
+      "Bash(gh auth status:*)",
+      "Bash(optima-agent:*)",
+      "Bash(python3:*)",
+      "Bash(python3 -c \" import sys content = sys.stdin.read\\(\\) # Find flushMessageQueueSync idx = content.find\\(''flushMessageQueueSync''\\) # Get context around it lines = content.split\\(''\\\\n''\\) for i, line in enumerate\\(lines\\): if ''flushMessageQueueSync'' in line and ''private'' in line: for j in range\\(i, min\\(i+20, len\\(lines\\)\\)\\): print\\(f''{j+1}: {lines[j]}''\\) break \")",
+      "Bash(optima:*)",
+      "WebFetch(domain:www.npmjs.com)",
+      "WebFetch(domain:registry.npmjs.org)",
+      "WebFetch(domain:zod.dev)",
+      "Bash(npm ls:*)",
+      "Bash(NODE_DEBUG=child_process npx tsx:*)",
+      "Bash(DEBUG_CLAUDE_AGENT_SDK=1 npx tsx:*)",
+      "Bash(CLAUDECODE= npx tsx:*)",
+      "Bash(env:*)",
+      "Bash(gh release:*)",
+      "Bash(npm info:*)",
+      "Bash(gh run:*)",
+      "Bash(gtimeout 90:*)",
+      "Bash(sentinel:*)",
+      "Bash(gh pr:*)",
+      "Bash(git fetch:*)",
+      "Bash(git log:*)",
+      "Bash(npm bin:*)",
+      "Bash(git status:*)",
+      "Bash(browser-cli --version && browser-cli --help)",
+      "Bash(browser-cli status:*)",
+      "Bash(browser-cli launch:*)",
+      "Bash(browser-cli screenshot:*)",
+      "Bash(browser-cli --version)",
+      "Bash(browser-cli close:*)",
+      "Bash(npm update:*)",
+      "Bash(node -e \"console.log\\(require\\('./node_modules/@optima-chat/browser-cli/package.json'\\).version\\)\")",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(aws ecs:*)",
+      "Bash(aws ecr:*)",
+      "Bash(gh search:*)",
+      "Bash(npx tsc:*)",
+      "Bash(find /Users/verypro/optima-agent -path */node_modules -prune -o -type f \\\\\\(-name *comfy* -o -name *gen* \\\\\\) -print)",
+      "Bash(export PATH=\"/usr/local/bin:$PATH\")",
+      "Bash(pnpm add:*)",
+      "Bash(cp -r ~/optima-agent/test/skills/kol-outreach/fixtures/one-active-campaign ~/optima-agent/test/skills/kol-outreach/fixtures/max-rounds-hit)",
+      "Bash(cp -r ~/optima-agent/test/skills/kol-outreach/fixtures/one-active-campaign ~/optima-agent/test/skills/kol-outreach/fixtures/budget-almost-spent)",
+      "Bash(cp -r ~/optima-agent/test/skills/kol-outreach/fixtures/one-active-campaign ~/optima-agent/test/skills/kol-outreach/fixtures/two-active-campaigns)",
+      "Bash(cp -r ~/optima-agent/test/skills/kol-outreach/fixtures/one-active-campaign ~/optima-agent/test/skills/kol-outreach/fixtures/brand-only)",
+      "Bash(pnpm vitest:*)",
+      "Bash(pnpm test:*)",
+      "Bash(pnpm --filter @optima-scout/backend test --reporter=verbose backend/src/routes/outreach/__tests__/lock.test.ts backend/src/routes/outreach/__tests__/inbound.test.ts)",
+      "Bash(npx vitest:*)",
+      "Bash(DATABASE_URL=postgres://optima_scout:optima_scout_dev@localhost:7293/optima_scout pnpm --filter @optima-scout/backend test)",
+      "Bash(pnpm --filter @optima-scout/backend exec vitest run src/routes/outreach/__tests__/inbound.test.ts)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/.claude/skills/gen/SKILL.md

@@ -38,6 +38,10 @@ gen image <prompt> [options]
 | `-o, --output <path>` | 输出目录或完整路径 |
 | `-s, --seed <number>` | 随机种子（可复现结果） |
 | `-f, --format <fmt>` | 输出格式：jpeg \| png |
+| `--provider <name>` | 供应商：grsai（默认） \| bfl |
+| `-m, --model <model>` | 模型：gpt-image-2（默认） \| nano-banana-fast \| nano-banana-pro \| flux-kontext-pro \| flux-kontext-max 等 |
+| `--aspect-ratio <ratio>` | 宽高比：1:1 \| 16:9 \| 9:16 \| 4:3 等 |
+| `--image-size <size>` | nano-banana-pro 输出尺寸：1K \| 2K \| 4K |
 
 ### 工作流示例
 
@@ -86,7 +90,7 @@ gen image "a modern logo with brand color #02eb3c as the primary accent" -o /hom
 gen image "Disney Pixar style 3D poster, [产品描述], cute character, vibrant gradient background, professional studio lighting" -W 1024 -H 1024 -o /home/aiuser/project/poster.png
 ```
 
-### 提示词指南（FLUX.2）
+### 提示词指南
 
 #### 结构
 

package/.claude/skills/multigrid-poster/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: multigrid-poster
+description: "为商家生成小红书 2×2 四宫格 / 3×3 九宫格封面图。触发场景:做小红书封面 / 小红书首图 / 种草帖封面 / 爆款封面 / 四宫格 / 九宫格。一句话指令产出 1242×1660 成片,支持自然语言迭代(换版式 / 重抽某格 / 改文案)。本 skill 只生成封面图,搜索小红书笔记 / 分析博主请用 'xhs' skill。"
+---
+
+# 小红书多宫格封面生成
+
+帮电商商家用 AI 图 + 通用网格布局合成小红书封面。**一句话从意图到 1242×1660 成片**,支持 4 宫格 / 9 宫格两种版式。
+
+## Global Rules
+
+优先级高于任何 pipeline 步骤。
+
+1. **User-facing 不出现模型名 / 服务名**
+   status / 成本 / 进度统一用"封面生成中 / 素材生成中 / 合成封面中"。`gen image` 作为 CLI 字面值可以,但不要把整条命令原文回显给用户。
+
+2. **花钱前必走 COST-GATE**
+   任何 `gen image` 批量调用之前必走一次成本确认。**Fast-path、迭代、重试均无例外**。2×2 = 4 张,3×3 = 9 张,SKU 拉图 = 0 张。rate 按 `gen image` 每次 1 积分估。
+
+3. **Per-post init 是任何 pipeline 第一步**
+   出图 / 合成执行前先建目录 + cd。否则 write 写错位置。迭代场景用 `{旧id}-vN`。
+
+4. **Anti-fabrication**
+   未在本 skill 显式列出的命令 / flag / 参数,不允许凭印象拼。`gen image` / `commerce` / `compose.py` 子命令同样适用。
+
+5. **不自动发帖**
+   只产 PNG,**绝对不调用**任何自动登录 / 发帖 / 上传命令。完成后给路径,用户自己下载手动发。
+
+## 工作目录
+
+```
+~/multigrid-poster/
+├── preferences.md
+├── history.md
+└── posters/{post-id}/
+    ├── intent.md             # 用户意图 + layout + 文案
+    ├── cells/cell_0..N.png   # 4 或 9 张素材
+    ├── cover.png             # 成片
+    └── cost.md
+```
+
+整个 `~/multigrid-poster/` 是一个 git repo。每步完成后 `git add -A && git commit`。
+
+## 启动流程
+
+1. **首次** (`ls ~/multigrid-poster/preferences.md` 不存在) → `mkdir -p ~/multigrid-poster/posters && cd ~/multigrid-poster && git init -b main`,创建空的 `preferences.md` (字段:merchant_id / brand_name / category / xhs_account_id / default_layout) 和 `history.md` (表头:date | post-id | layout | title | parent | status)。`.gitignore` 加 `posters/**/cells/*.png` 和 `posters/**/cover.png`。
+2. **扫未完成**:`posters/` 下有 `intent.md` 但无 `cover.png` 且 < 7 天 → 提一次"你有 N 个封面没完成"。
+3. **读 preferences.md / history.md**,继续主流程。
+
+## 主流程
+
+### Step 1: 选 layout
+
+| 用户原话 | layout | cells |
+|---|---|---|
+| 含"九宫格 / 9 格 / 9 张 / 清单 / N 款 / 礼物推荐 / 榜单" | **3×3** | 9 |
+| 其他(包含"四宫格 / 4 格 / 4 张" 或没指定) | **2×2** | 4 |
+
+### Step 2: Per-post init
+
+```bash
+# slug = 用户意图前 20 字内的 kebab-case
+POST_ID="$(date +%Y%m%d-%H%M)-<slug>"
+mkdir -p ~/multigrid-poster/posters/$POST_ID/cells
+cd ~/multigrid-poster/posters/$POST_ID
+```
+
+迭代("换版式 / 重抽 / 改文案")时:轻迭代沿用旧目录,重迭代新建 `{旧id}-vN`。
+
+### Step 3: 写文案
+
+agent 自己写,不调外部生成器。约束:
+- **title**:2 行 × 8-12 字 / 行(2×2 适合)或 2 行 × 6-10 字 / 行(3×3 标题挤)
+- **caption**:2 行 × 15-20 字 / 行
+- 硬禁:医疗 / 保健 / 绝对化用语(最 / 第一 / 唯一 / 100%)
+
+写到 `intent.md`:
+
+```markdown
+# Intent
+| 项目 | 值 |
+|---|---|
+| 用户原话 | <原话> |
+| layout | 2x2 / 3x3 |
+| title 行 1 | <8-12 字> |
+| title 行 2 | <8-12 字> |
+| caption 行 1 | <15-20 字> |
+| caption 行 2 | <15-20 字> |
+```
+
+展示给用户:"标题'XXX / YYY',副标题'AAA / BBB'。OK 吗?"
+- Fast-path(意图明确):告知,用户喊停才停
+- 意图模糊:必须等确认
+
+### Step 4: COST-GATE
+
+**生成前必做**(包括 Fast-path / 迭代 / 重试):
+
+> 即将生成封面(布局: 2x2 / 3x3),预计:
+> - 素材调用: N 次(2×2=4 / 3×3=9 / SKU 拉图=0)
+> - 预估耗时: ~X 分钟
+> - 预估成本: ~Y 积分
+>
+> 继续?
+
+用户说"继续 / 好" → 执行。"太贵 / 换便宜的" → 提议降级 (3×3 → 2×2,或 SKU 拉图)。不回应 → 等。
+
+### Step 5: 出图
+
+**默认走 AI 生图**。每个 cell 并行调一次:
+
+```bash
+# 2×2: cell 尺寸 621×830;3×3: cell 尺寸 414×420
+gen image "<subprompt>" -W <W> -H <H> -o ./cells/cell_<i>.png -s <seed> -f png
+```
+
+`<subprompt>` 由 agent 根据用户意图为每格独立设计(不同视角 / 不同 step / 不同场景 / 不同 SKU 等)。`<seed>` 用确定性 hash(POST_ID + cell_index),迭代复用同格 seed。
+
+**SKU 拉图模式**(用户明确说"用我店里商品图"做 listicle):
+
+```bash
+commerce product list --limit 9
+```
+
+下载到 `./cells/cell_0..8.png`。商品 < 9 → 降级 2×2 取前 4。商品 < 4 → 报错。
+
+**失败容忍**:单格生图失败 → 重试 1 次(换 seed)。两次失败 → 用 `${CLAUDE_SKILL_DIR}/scripts/placeholder.png` 占位,告知用户"第 N 格失败,先占位,要重抽直接说"。
+
+### Step 6: 合成
+
+```bash
+python3 $CLAUDE_SKILL_DIR/scripts/compose.py \
+  --layout $CLAUDE_SKILL_DIR/layouts/2x2.json \
+  --cells ./cells/cell_0.png ./cells/cell_1.png ... \
+  --title-line "<title 行 1>" \
+  --title-line "<title 行 2>" \
+  --caption-line "<caption 行 1>" \
+  --caption-line "<caption 行 2>" \
+  --output ./cover.png
+```
+
+依赖:Pillow(容器自带)。失败常见原因:
+
+| 错误 | 处理 |
+|---|---|
+| `cell 数量不对` | layout 要求 4 / 9,检查 `--cells` 参数 |
+| `font not found` | 检查 `$CLAUDE_SKILL_DIR/shared/fonts/` 完整 |
+| 中文显示方块 | 同上,字体没加载 |
+
+### Step 7: 交付
+
+写 `cost.md`,追加 `~/multigrid-poster/history.md` 一行,告知用户:
+
+> 封面在 `~/multigrid-poster/posters/<POST_ID>/cover.png`,可以下载发帖了。
+> 换版式 / 改文案 / 重抽某格直接告诉我。
+
+用户说"好 / 完美" → preferences.md `Learned` 追加一条 → commit。
+
+## 迭代
+
+| 类型 | 重跑步骤 | 新目录 | 成本 |
+|---|---|---|---|
+| 换 layout(2×2 ↔ 3×3) | 文案 → 出图 → 合成 | 是(`-vN`) | 全成本 |
+| 重抽全部 | 出图 → 合成 | 是 | 全素材 |
+| 重抽单格 N | 出图(单格) → 合成 | 否 | 1 素材 |
+| 改文案 | 合成 | 否 | 0 |
+
+**每次迭代也走 COST-GATE**,即使 0 积分。
+
+## 错误处理
+
+| 故障 | 处理 |
+|---|---|
+| `gen image` 返回 failed | 重试 1 次换 seed → 仍失败用占位图 |
+| 超配额 / 余额不足 | 告知用户,不自动降级 |
+| `commerce product list` < 9 | 降级 2×2 取前 4 |
+| 会话关闭 | 状态在文件系统 + git,下次接续 |
+
+## 相关工具
+
+- `gen image` — 文生图(详见 `gen` skill)
+- `commerce merchant get` / `commerce product list` — 商家档案 / 商品(详见 `merchant` skill 和 `product` skill)
+- `compose.py` — 本 skill 自带的 Pillow 渲染器
+
+## 流程偏好
+
+- **信息够就直接做(Fast-path)**
+- **`intent.md` 是可追溯产物**
+- **每步完成立刻 git commit**
+- **生成过程零打扰**
+- **迭代用 `-vN` 不覆盖**
+- **新会话有未完成先告知一次**

package/.claude/skills/multigrid-poster/layouts/2x2.json

@@ -0,0 +1,34 @@
+{
+  "_comment": "通用 2×2 网格布局 — 适合 4 张 cell 的所有 intent (创业故事/对比测评/教程/场景)",
+  "canvas_size": [1242, 1660],
+  "cells": {
+    "positions": [[0, 0], [621, 0], [0, 830], [621, 830]],
+    "sizes": [[621, 830], [621, 830], [621, 830], [621, 830]]
+  },
+  "text_zones": {
+    "title": {
+      "_comment": "中央偏上 2 行标题 - 8-12 字 / 行最佳",
+      "font": "shared/fonts/MaShanZheng-Regular.ttf",
+      "size": 110,
+      "color": "#FFB940",
+      "stroke_w": 8,
+      "stroke_color": "#D63D3D",
+      "lines": [
+        {"position": [621, 480], "anchor": "mm"},
+        {"position": [621, 620], "anchor": "mm"}
+      ]
+    },
+    "caption": {
+      "_comment": "底部 2 行 caption - 15-20 字 / 行最佳",
+      "font": "shared/fonts/MaShanZheng-Regular.ttf",
+      "size": 78,
+      "color": "#FFB940",
+      "stroke_w": 6,
+      "stroke_color": "#D63D3D",
+      "lines": [
+        {"position": [621, 1340], "anchor": "mm"},
+        {"position": [621, 1450], "anchor": "mm"}
+      ]
+    }
+  }
+}

package/.claude/skills/multigrid-poster/layouts/3x3.json

@@ -0,0 +1,43 @@
+{
+  "_comment": "通用 3×3 网格布局 - 适合 9 张 cell (商品清单 / 多角度展示)",
+  "canvas_size": [1242, 1660],
+  "cells": {
+    "_comment": "9 格 414×420。顶部 200px 标题区,cells y=200..1460,底部 200px caption 区。3×420 + 200×2 = 1660 = canvas_h ✓",
+    "positions": [
+      [0, 200],   [414, 200],   [828, 200],
+      [0, 620],   [414, 620],   [828, 620],
+      [0, 1040],  [414, 1040],  [828, 1040]
+    ],
+    "sizes": [
+      [414, 420], [414, 420], [414, 420],
+      [414, 420], [414, 420], [414, 420],
+      [414, 420], [414, 420], [414, 420]
+    ]
+  },
+  "text_zones": {
+    "title": {
+      "_comment": "顶部白边 2 行标题(y < 200 区间)",
+      "font": "shared/fonts/MaShanZheng-Regular.ttf",
+      "size": 78,
+      "color": "#FFB940",
+      "stroke_w": 6,
+      "stroke_color": "#D63D3D",
+      "lines": [
+        {"position": [621, 60], "anchor": "mm"},
+        {"position": [621, 150], "anchor": "mm"}
+      ]
+    },
+    "caption": {
+      "_comment": "底部白边 2 行 caption(cells 结束于 y=1460,留 200px)",
+      "font": "shared/fonts/MaShanZheng-Regular.ttf",
+      "size": 60,
+      "color": "#FFB940",
+      "stroke_w": 5,
+      "stroke_color": "#D63D3D",
+      "lines": [
+        {"position": [621, 1530], "anchor": "mm"},
+        {"position": [621, 1610], "anchor": "mm"}
+      ]
+    }
+  }
+}

package/.claude/skills/multigrid-poster/scripts/compose.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""multigrid-poster compose — Pillow 版渲染器
+
+输入：layout.json + N 张 cell 图片 + 标题文字 + caption 文字
+输出：1242×1660 PNG（小红书封面标准）
+
+用法：
+  python compose.py \
+    --layout <SKILL_DIR>/layouts/2x2.json \
+    --cells cell_0.png cell_1.png cell_2.png cell_3.png \
+    --title-line "26岁一个人创业" \
+    --title-line "跨境电商月入10w+" \
+    --caption-line "只需要一部手机就可以完成！" \
+    --caption-line "跨境人的必备app推荐" \
+    --output cover.png
+
+依赖：Pillow (容器自带，无需额外安装)
+字体：从 SKILL_DIR/shared/fonts/ 加载（layout.json 里指定）
+"""
+import argparse
+import json
+import sys
+from pathlib import Path
+from PIL import Image, ImageDraw, ImageFont
+
+
+def compose(layout_path: Path, cell_paths: list[Path],
+            title_lines: list[str], caption_lines: list[str],
+            output_path: Path) -> Path:
+    """根据 layout.json 渲染海报。
+
+    layout.json 字段：
+      canvas_size       [w, h]
+      cells.positions   [[x,y], ...] cell 左上角
+      cells.sizes       [[w,h], ...] cell 尺寸
+      text_zones.title  {lines: [...], size, color, stroke_w, stroke_color, font}
+      text_zones.caption {同上}
+    """
+    layout = json.loads(layout_path.read_text(encoding="utf-8"))
+    # 约定:layout 必须放在 <skill>/layouts/ 下,字体路径相对 <skill>/ 解析
+    skill_dir = layout_path.parent.parent
+
+    # 文本行数 vs layout 配置行数:行多了 zip 会静默截断,显式 fail-fast
+    # 错误信息用英文 — sys.exit 走 stderr,Windows GBK locale 下中文会乱码
+    for zone_key, lines in [("title", title_lines), ("caption", caption_lines)]:
+        zone = layout.get("text_zones", {}).get(zone_key)
+        if not zone:
+            continue
+        max_lines = len(zone["lines"])
+        if len(lines) > max_lines:
+            sys.exit(f"too many {zone_key} lines: got {len(lines)}, layout supports {max_lines}")
+
+    # Canvas
+    canvas = Image.new("RGB", tuple(layout["canvas_size"]), "white")
+
+    # Cells
+    cell_count = len(layout["cells"]["positions"])
+    if len(cell_paths) != cell_count:
+        sys.exit(f"cell count mismatch: layout expects {cell_count}, got {len(cell_paths)}")
+    for cp, pos, size in zip(cell_paths,
+                              layout["cells"]["positions"],
+                              layout["cells"]["sizes"]):
+        img = Image.open(cp).convert("RGB").resize(tuple(size), Image.LANCZOS)
+        canvas.paste(img, tuple(pos))
+
+    draw = ImageDraw.Draw(canvas)
+
+    # Text zones (title + caption 通用绘制)
+    for zone_key, lines in [("title", title_lines), ("caption", caption_lines)]:
+        if zone_key not in layout["text_zones"]:
+            continue
+        zone = layout["text_zones"][zone_key]
+        font_path = skill_dir / zone["font"]
+        font = ImageFont.truetype(str(font_path), zone["size"])
+        for text, line_cfg in zip(lines, zone["lines"]):
+            if not text:
+                continue
+            draw.text(
+                tuple(line_cfg["position"]), text,
+                fill=zone["color"], font=font,
+                stroke_width=zone.get("stroke_w", 0),
+                stroke_fill=zone.get("stroke_color", zone["color"]),
+                anchor=line_cfg.get("anchor", "la"),
+            )
+
+    canvas.save(output_path, optimize=True)
+    return output_path
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                  formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--layout", required=True, type=Path,
+                    help="layout.json 路径（如 SKILL_DIR/layouts/2x2.json）")
+    ap.add_argument("--cells", required=True, nargs="+", type=Path,
+                    help="N 张 cell 图片路径，顺序对应 layout.cells.positions")
+    ap.add_argument("--title-line", action="append", default=[],
+                    help="标题行（可重复）")
+    ap.add_argument("--caption-line", action="append", default=[],
+                    help="底部 caption 行（可重复）")
+    ap.add_argument("--output", required=True, type=Path,
+                    help="输出 PNG 路径")
+    args = ap.parse_args()
+
+    out = compose(
+        layout_path=args.layout,
+        cell_paths=args.cells,
+        title_lines=args.title_line,
+        caption_lines=args.caption_line,
+        output_path=args.output,
+    )
+    print(f"saved {out} ({out.stat().st_size // 1024} KB)")
+
+
+if __name__ == "__main__":
+    main()