# ⚠️ 由 scripts/build-skills.mjs 从 shared/examples/brand.yaml 同步生成，不要直接改这里。
# 店铺品牌视觉规范 —— 所有生图技能读这一份，保证几百个 SKU 看起来像同一家店。
#   node scripts/brand.mjs --brand brand.yaml --for flat-lay
#   node scripts/gen.mjs --task flat-lay --brand brand.yaml --prompt '...'

brand:
  name: 示例品牌
  # 一句话概括调性，会原样进 prompt
  tone: quiet minimalist, warm and lived-in, never glossy or commercial

model:
  # 锁模特：给一张脸的参考图，所有技能都会把它作为最后一张参考图传入
  reference: assets/model/face-a.jpg
  description: East Asian woman, late twenties, natural makeup, shoulder-length black hair
  body: slim, height around 168cm

photography:
  background: seamless off-white studio backdrop, RGB 248 248 246
  lighting: soft large softbox from camera left, gentle fill, no hard shadows
  camera: 85mm equivalent, eye level, shallow depth of field
  grade: neutral white balance around 5200K, low contrast, slightly lifted blacks
  crop: full body with headroom, product centered

layout:
  # 给带排版的技能（主图 / 详情页）用
  margin: at least 8% empty margin on all sides
  typeface: clean sans-serif, no decorative fonts
  text_color: near-black on light background

forbid:
  - no visible brand logos other than the product's own
  - no text or watermark
  - no exaggerated poses or dramatic wind effects
  - no oversaturated colors

# 可选：把这些直接写进合规目标，生成时就按平台要求出图
compliance:
  platform: amazon

<!-- 由 scripts/build-skills.mjs 从 shared/references/provider-cli.md 同步生成，不要直接改这里。 -->
# 后端调用参考

技能正文只写「要生成什么」。认证、计费、错误码、输出结构这些每个技能都一样的东西放在这里，
**用到时再读**，不占技能的常驻上下文。

---

## 一、认证

### 默认后端 dLazy

```bash
dlazy login            # 设备码流程，远程 shell 也能用，自动写入本地配置
dlazy auth set <KEY>   # 已有 key 时直接写入
```

key 存在用户配置目录（macOS/Linux `~/.dlazy/config.json`，Windows `%USERPROFILE%\.dlazy\config.json`），
权限限本机用户。也可以每次调用用环境变量 `DLAZY_API_KEY` 传入。

手动获取：登录 [dlazy.com](https://dlazy.com) → [API Key 页面](https://dlazy.com/dashboard/organization/api-key)。
key 按组织隔离，可随时轮换或吊销。

### 其他后端

本技能库不锁定单一厂商。配好任意一家的 key 即可跑：

| 后端 | 环境变量 | 说明 |
| --- | --- | --- |
| `dlazy` | `dlazy login` 或 `DLAZY_API_KEY` | 默认，最省事 |
| `openai` | `OPENAI_API_KEY` | 走 `/v1/images/edits` 与 `/v1/images/generations` |
| `gemini` | `GEMINI_API_KEY` | Nano Banana 系列 |
| `fal` | `FAL_KEY` | |
| `replicate` | `REPLICATE_API_TOKEN` | |
| `ark` | `ARK_API_KEY` + `ARK_MODEL` | 火山方舟，模型 ID 需按开通情况填 |

选路优先级：`--provider` 参数 > `PROVIDER` 环境变量 > 第一个配了 key 的 > `dlazy`。

```bash
node scripts/gen.mjs --doctor     # 看当前哪个后端可用
```

各后端的模型 ID 可用 `GEN_MODEL_OPENAI` / `GEN_MODEL_GEMINI` / `GEN_MODEL_FAL` /
`GEN_MODEL_REPLICATE` / `GEN_MODEL_ARK` 覆盖。**厂商目录会变，以各家最新文档为准。**

---

## 二、两种调用方式

### 方式 A：统一入口（推荐）

```bash
node scripts/gen.mjs --task <技能名> --prompt '...' --images a.jpg b.jpg --save out.jpg
```

它负责：后端选路、默认尺寸档位、失败重试（429/5xx 指数退避）、落盘建目录、成本估算。

```bash
node scripts/gen.mjs --task flat-lay --prompt '...' --dry-run   # 不调用不计费，只看要发什么
node scripts/gen.mjs --help
```

### 方式 B：直接用 dLazy CLI

不想引入 Node 依赖时，技能正文里的 `dlazy ...` 命令可以原样执行，效果等价。

```bash
npx @dlazy/cli@1.2.3 <command>     # 不装全局二进制
```

- CLI 源码：[github.com/dlazy-ai/cli](https://github.com/dlazy-ai/cli) · npm 包 `@dlazy/cli`

---

## 三、数据流向

调用 dLazy 时：提示词与参数发往 `api.dlazy.com`；传入的本地图片会上传到 `files.dlazy.com`
供模型读取；产出 URL 同样托管在 `files.dlazy.com`。这是云端生成 API 的通用形态。
换成其他后端时，数据流向对应厂商，不经过 dLazy。

---

## 四、输出结构

`gen.mjs`（加 `--json`）：

```json
{
  "ok": true,
  "task": "flat-lay",
  "provider": "dlazy",
  "model": "gpt-image-2",
  "files": ["docs/flat-lay/output-sku001.jpg"],
  "texts": [],
  "estimatedCredits": 60,
  "elapsedMs": 58213
}
```

dLazy CLI 原生：

```json
{
  "ok": true,
  "result": {
    "tool": "gpt-image-2",
    "data": { "urls": ["https://files.dlazy.com/data/ai/....jpg"] },
    "savedPath": "docs/flat-lay/example-output.jpg"
  }
}
```

加 `--no-wait` 的异步任务不返回 `data`，返回 `task: { generateId, status }`，
用 `dlazy status <generateId> --wait` 轮询。

文本类模型（如质检）产出在 `result.data.texts[0]`：

```bash
dlazy claude-sonnet-5 --prompt '...' --images x.jpg \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["result"]["data"]["texts"][0])'
```

---

## 五、错误处理

| Code | 类型 | 示例 |
| --- | --- | --- |
| 401 | 未授权 / 无 key | `ok: false, code: "unauthorized"` |
| 501 | 缺必填参数 | `error: required option '--prompt <prompt>' not specified` |
| 502 | 本地文件读不到 | `Error: Image file not found: ...` |
| 503 | 余额不足 | `ok: false, code: "insufficient_balance"` |
| 503 | 服务端错误 | `HTTP status code error (500)` |
| 504 | 异步任务失败 | `=== Generation Failed ===` / `Prompt violates safety policy` |

**给 Agent 的硬性要求**

1. 命中 `insufficient_balance` → 明确告诉用户算力不足，并给出充值入口
   <https://dlazy.com/dashboard/organization/settings?tab=credits>
2. 命中 `unauthorized` / 缺 key → 告诉用户去 <https://dlazy.com/dashboard/organization/api-key>
   取 key，用 `dlazy auth set <key>` 存好再继续。
3. 用 `gen.mjs` 时，429 与 5xx 已自动重试；仍失败才向用户报错。
4. **不要**为了「跑通」而偷偷降级参数（尺寸、档位、批量），先问用户。

<!-- 由 scripts/build-skills.mjs 从 shared/references/video-backends.md 同步生成，不要直接改这里。 -->
# 视频后端配置

图像模型的默认值写死在 `lib/tasks.json` 里，视频模型没有——**因为各家的视频模型
ID 差异大、更新快，写死只会误导**。所以视频技能要求你显式指定。

## 指定模型

```bash
export DLAZY_VIDEO_MODEL=<你账号里可用的视频模型 ID>
# 或每次调用时
node scripts/video.mjs --mode clip --task main-image-video --model <id> ...
```

没设会直接报错，不会拿一个猜的模型名去跑。

## 各后端

| 后端 | 怎么配 | 说明 |
| --- | --- | --- |
| `dlazy` | `DLAZY_VIDEO_MODEL` | 用 `dlazy --help` 看当前账号可用的视频工具 |
| `fal` | `FAL_KEY` + `GEN_MODEL_FAL=<视频模型路径>` | 产出在 `videos[]` 或 `video.url` |
| `replicate` | `REPLICATE_API_TOKEN` + `GEN_MODEL_REPLICATE=<owner/model>` | 产出为 URL |

图生视频时参考图走 `--images`，与图像技能一致。

## 合成依赖

拼接与字幕需要 ffmpeg：

```bash
brew install ffmpeg        # macOS
apt install ffmpeg         # Debian/Ubuntu
```

没装也能跑——片段照常生成，脚本会输出 `concat.txt`，装好后一条命令补拼。

## 字幕的三级降级

1. **烧录进画面**：需要 ffmpeg 带 libass。很多发行版的预编译包没有。
2. **软字幕轨**：`-c:s mov_text` 封进 MP4，播放器可开关。几乎总能成。
3. **都不行**：`.srt` 留在产物目录旁边，可导入剪辑软件。

脚本自动逐级尝试，不用你判断。查本机是否支持烧录：

```bash
ffmpeg -hide_banner -filters | grep ' subtitles '
```

## 分镜文件

```json
{
  "shots": [
    { "id": "s1", "seconds": 3, "image": "main.jpg",
      "prompt": "Slow push-in on the product, soft light sweeps across the surface.",
      "caption": "三层加厚，零下也不怕" }
  ]
}
```

`caption` 会按 `seconds` 累加时间轴自动生成 SRT，不用手对时间码。