# ⚠️ 由 scripts/build-skills.mjs 从 shared/assets/brand.example.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/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/brand-schema.md 同步生成，不要直接改这里。 -->
# brand.yaml 字段说明

一份文件定义店铺的视觉规范，所有生图技能读它。改一处，全店跟着变。

```yaml
brand:
  name: 品牌名                    # 仅用于记录
  tone: 一句话调性                # 原样进 prompt，写英文效果更稳

model:                           # 只有出人像的技能会读
  reference: assets/model/face-a.jpg   # 锁脸：会作为额外参考图传入
  description: 模特外形描述        # 英文
  body: 身形与身高

photography:                     # 出实拍类图的技能会读
  background: 背景描述
  lighting: 光位
  camera: 镜头与视角
  grade: 色调与白平衡
  crop: 景别与构图

layout:                          # 只有带排版的技能会读（主图 / 详情页）
  margin: 留白要求
  typeface: 字体倾向
  text_color: 文字颜色

forbid:                          # 硬性禁止项，会拼成一句 Hard constraints
  - no text or watermark
  - no oversaturated colors

compliance:
  platform: amazon               # 可选：默认合规目标
```

## 哪个技能读哪几段

| 段落 | 读它的技能 |
| --- | --- |
| `brand.tone` | 全部 |
| `model` | 出人像的：flat-lay、wear-everything、image-fusion、one-shot、fission-pattern、creative-scene、clothing-grass-planting、batch-image、三个视频技能、listing-optimizer |
| `photography` | 出实拍类图的（含上面这些，再加 item-change-background、to-3d、clothing-detail、item-repair） |
| `layout` | 带排版的：item-detail、item-selling-point、listing-optimizer、cross-border-localize |
| `forbid` | 全部 |

不相干的段落不会进 prompt——给详情页技能塞模特脸的描述只会干扰它。

## 用法

```bash
node scripts/brand.mjs --init > brand.yaml           # 生成模板
node scripts/brand.mjs --brand brand.yaml --for flat-lay          # 看会追加什么
node scripts/gen.mjs --task flat-lay --brand brand.yaml --prompt '...'   # 自动追加
```

`--brand` 对 `gen.mjs` / `run_loop.mjs` / `batch.mjs` / `video.mjs` 都有效。

## 注意

- `model.reference` 路径相对于**运行命令的目录**，不是 brand.yaml 所在目录。
- 文件找不到时只警告不报错，生成照常进行（少一张参考图而已）。
- 支持的是 YAML 的常用子集：2 空格缩进、映射、标量、`- ` 列表。
  锚点、多行标量这些没实现——用到了就换成 `brand.json`，同样能读。

<!-- 由 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. **不要**为了「跑通」而偷偷降级参数（尺寸、档位、批量），先问用户。