# character-lora — playbook（方法論深度）

> SKILL.md 是操作骨架；本檔是「**為什麼 + 怎麼判斷 + per-base 配方知識**」。跑流程看 SKILL.md，卡住 / 要決策時翻這裡。

## 心智模型（3 條，橫貫全程）

1. **LoRA = 資料集的鏡子。** 烤進去的特徵（招牌特徵 / 體型 / 髮型 / 配件）來自**圖**、不是 caption。要改它們 → 回去改**資料集**，不是改 prompt（prompt override 已烤進的特徵只能部分、不可靠）。
2. **LoRA 綁架構。** train base family = infer base family。不同架構（如 SDXL-family vs 新世代 NL 模型）的 LoRA 互不相容。**資料集(照片)兩邊通用、是可重用資產**；只有 caption 格式不同、要分別標。
3. **標可變、留 identity。** caption 標的 = 模型認為「可以變」的；留白的 = 烤進 trigger 成為「這角色是誰」。所以場景 / 角度 / 服裝標，臉 / 體型不標。

## 為什麼要先做 base 功課（red line 1 的理由）

不同 base 的訓練「方言」差很多，憑印象套通用 config 會踩：
- **caption 風格**（booru tag vs 自然語言）不同 → 用錯模型不認。
- **蒸餾 / Turbo 變體**常需特殊 training adapter + 不同 sample 設定，不知道 → 「訓壞了」的假象。
- **trigger 命名 / 要不要 class word / 要不要 quality tag**，各 base 規範不同。
- **環境 / 依賴**（哪個訓練器支援、量化、VRAM 配方）不同。

**功課清單**：① 官方 model card / 訓練文件 ② 社群實戰文（dim/alpha/optimizer/步數的實測值）③ 該 base 的「變體差異」（base vs distilled/Turbo）④ 訓練器支援度 + VRAM 配方。**查完再動手。**

## Stage 深度

### 1-2 角色定義 / 定版
- 「不變 vs 可變」這刀切錯，後面全歪。招牌特徵（永遠這臉/這體型）→ 不變、烤進去；可換的（服裝/配件/髮色）→ 可變、當維度。
- **toggle 維度**（如眼鏡）要可控 → dataset 必須**同時有「有」和「沒有」兩種圖**，caption 只在「有」的標。只收一種 = 烤死、toggle 不了。
- 招牌特徵想**鎖死** → 完全不標（全圖都有、留白 → 焊進 identity）；想當**可變維度** → 每張標真實狀態（前提：dataset 真有變化）。
- ⚠️ **跟 base prior 衝突的特徵**（如人類底模上的精靈耳、非寫實比例）：留白可能訓不穩 → 該特徵的圖要**夠多 / 夠一致**，必要時輕標一個 token 拉它。
- **服裝 / costume**：想換裝 → 當可變維度、每張標；屬角色「制服」想固定 → 不標。介於兩者（如「ranger 皮甲」）→ 看你要不要換，由你決定哪邊。
- reg / class images：單一具名角色多半**不用**；風格污染嚴重才考慮。

### 3 資料集
- 多角度是**訓練型 LoRA** 的需求（不是 embedding/IPAdapter，那種偏好乾淨正面）。
- 角度 × 取景都要分佈：全正 → 生不出別角度；全特寫 → 拒生全身。
- **品質 >> 數量**：~40-50 精圖即可，>100-150 = overfit、不是更像；垃圾/重複圖**有害**。AI 生成的一致性 dataset 比多來源混搭穩（避免風格污染）。
- **pilot 重用**：pilot 圖花算力/usage，生 full 時只補沒生過的角度、合併、不重生。

### 4 captioning（per-base）
- **booru-native（Pony/SDXL）**：comma tags、trigger 第一 token、30-60 tags、`keep_tokens=1`（trigger 固定、其餘 shuffle）。訓練**不放 quality/score tag**（style bleed）、推理才加。
- **自然語言（新世代 NL 模型）**：句子、`<trigger> <class word>` 開頭。**禁止會觸發既有語義的字**（如把某類別名寫進去 → 模型照字面渲染）。class word（man/woman…）防 baseline 偏某性別。
- trigger 一律**非字典 token**（發明的、可加前綴）避免污染既有概念。

### 5 base 選型 + 配方知識（generic 起點，仍要查當下版本）
**SDXL-family（如 Pony）配方共識**：
- dim/alpha：角色 16/8 起；**複雜角色（多細節）32/16**；`alpha = dim 一半`（切壞訓練），alpha 絕不 > dim。
- optimizer：低圖數 → 8bit-Adam + 純 cosine；高圖數 → adafactor + cosine_with_restarts；Prodigy 自適應穩（**配純 cosine — cosine_with_restarts 只配 adafactor**）。
- steps：低圖數 ~1000-1500、**高 epoch(15-20) + 低 repeat** → 每 epoch 存、挑最佳（14+ 常 overbake）。
- 其餘：1024 + bucket、min_snr_gamma 5、noise_offset 0.0357（XL 訓練值）、bf16、flip_aug 通常 off（臉不對稱）。

**蒸餾 / Turbo 變體配方**：
- Turbo 訓 LoRA **必疊 training adapter**（否則 de-distill drift，推理要 20-30 步而非快速步數）；完整版訓法不同（通常無 adapter）。
- sample / 推理用 Turbo 設定：少步數 / 低或零 CFG / 對應 scheduler / 無 negative。
- 對應訓練器（如 ai-toolkit）；小 VRAM → fp8 量化 + 低 VRAM 模式。
- lr 不要超（一超就 drift）。

> ⚠️ 以上是**社群共識起點**，跑前仍要查當下版本 + 你的 base 確切文件（red line 1）。

### 6-8 訓練 / 驗收
- **OOM 試跑先**（別整批跑才發現爆 VRAM）。
- **checkpoint 常非最後一個最好** → 存多個、肉眼挑（過甜蜜點 overbake：背景掉質、訓練資料 artifact 跑出來）。
- **寬景掉臉**是 SDXL-LoRA 通病（臉太小、base prior 接管）→ face-detail pass（crop 臉用 LoRA 重畫）。
- diagnose：identity 不穩先分「dim/alpha 容量不足」vs「dataset 問題」，別亂改 prompt。

## 完整 失敗 → 根因 → 對策

| 症狀 | 根因 | 對策 |
|---|---|---|
| 角色每次「抽籤」/ 超飄 | dim/alpha 雙重弱化 + optimizer 沒調 | 照 base 官方配方（dim 足、Prodigy/adafactor、alpha=半dim） |
| 寬景 / 全身掉臉變別人 | 臉太小、base prior 接管 | face-detail pass（用 LoRA 重畫臉） |
| 出來變性別 | NL caption 沒 class word | caption 加 man/woman |
| 出現非預期動物 / 卡通特徵 | caption 有觸發該語義的字 | 拿掉那字、trigger 用非字典 token |
| 烤進的特徵 prompt 改不掉 | 特徵來自圖、非 caption | 改 dataset，不是改 prompt |
| 「訓壞了」但其實是 sample 設定錯 | 蒸餾變體用了 base 的 sample 設定 | 用該變體正確的 sample 設定再看 |
| 表情 / 細節被 face-detail 中和 | detailer denoise 太低 | 拉高 detailer denoise + prompt 補表情 token |
| 多角色互動空間崩（飄浮 / 接錯） | 文字無法指定空間、雙人資料稀疏 | ControlNet（pose/depth）/ 從參考 img2img / 分區 inpaint |

## 自檢 / contact sheet（品質把關）

- **你是第二雙眼睛。** 生成圖傳 user 前自己先 view、主動 flag：沒臉 / 崩臉 / 變性別 / 非預期動物或卡通 / 框景裁頭 / 體型不符。「看起來很好」（你的或 subagent 的）是 input、不是事實 — 最終 user 判，但別盲轉。
- **批量出 contact sheet。** 數十張 dataset 或多 checkpoint → `ffmpeg`（`tile` filter）或 `imagemagick montage` 拼 grid 一張看，效率 + 一眼抓異常。某些 ffmpeg build 缺 `drawtext`（加不了文字標籤）→ 標籤靠檔名 / caption 或用 imagemagick。

## skill 映射（哪裡自動、哪裡人工 gate）
- 自動：codex 出圖（delegate gpt-image-gen）、訓練啟動、進度 checker、montage 合成。
- **人工 gate（不自動跳）**：base 選型、pilot 驗收、訓練設定確認、production 拍板。
- 紅線（功課 / 驗證 / 拍板）= 人工把關。

---
name: character-lora
description: "Use when the user wants to build a consistent-identity LoRA for an original character — defining the character, generating a face/body-consistent multi-angle dataset (via the gpt-image-gen skill for codex image generation), captioning it, doing base-specific homework, training on a chosen base (Pony / Z-Image / others) on a local GPU, and producing a usable LoRA. This skill ORCHESTRATES the end-to-end pipeline and gates every expensive/irreversible step; it delegates actual image generation to gpt-image-gen and never improvises training settings from memory."
version: 0.2.1
status: mvp
triggers:
  - "/character-lora"
  - "做角色 lora"
  - "訓練角色 lora"
  - "角色 lora 流程"
  - "做一個角色的 lora"
  - "train a character lora"
  - "character lora pipeline"
---

# character-lora

You are a **character-LoRA pipeline orchestrator**. You take an original character from "an idea + a reference look" to a trained, usable LoRA that reproduces its identity across angles, framings and scenes. You drive a multi-stage pipeline, **delegate image generation to the `gpt-image-gen` skill**, **gate every expensive / irreversible step on explicit user approval**, and **never improvise training settings from memory** — you do the base-specific homework first.

> 完整方法論（每 stage 的 why、決策樹、per-base 配方知識、完整失敗對策）在同目錄 **`playbook.md`**。本檔是操作骨架。

## 🔴 Red lines（即使讀過下面 step 也別忘）

1. **MANDATORY：跑任何新 base 的訓練前，先讀該 base 的官方訓練文件 + 社群討論** — caption 規範 / trigger 命名 / 蒸餾(Turbo)變體 vs 完整版的訓練差異 / 環境依賴。憑印象配參數 = 角色「抽籤」/ 飄。
2. **沒驗證的不寫進 playbook/recipe** — 設定要實跑驗過才當「配方」；沒測的標 `proposed / 待驗`。
3. **生圖 / 訓練 = 花 user 的錢與算力 → 先拿明確 go 才跑**（pilot 給看 → OK 才整批；訓練前報設定）。**不要自己上 API key**。
4. **LoRA 綁架構** — train base family = infer base family，絕不跨（Pony LoRA ≠ Z-Image LoRA，互不相容）。
5. **標「會變」、留「identity」** — caption 只標可變（場景/角度/服裝/toggle 配件）；臉/體型/招牌特徵留白 → 烤進 trigger word。

## 圖生成（單張 delegate / 批量自跑 / 本機自生）

- **單張（定版 Stage 1b、sheet Stage 2）→ 走 `gpt-image-gen` skill**（互動擬 prompt + 單張拍板 + codex text2img/img2img）。⚠️ **明確要它保留無損 PNG** — gpt-image-gen 預設交 jpg q85 且刪 png，但訓練/canonical 要 PNG，delegate 時講「留無損 png」。
- **批量（dataset Stage 3）→ 本 skill 自己跑 codex 批次**：gpt-image-gen 是單張互動式、不適合批 40-50 張。改自跑 `codex exec "<prompt> $imagegen" -i <ref> < /dev/null`（prompt 第一 positional、`-i` 在後、迴圈必 `< /dev/null`、並行各自獨立 `CODEX_HOME`；坑見 gpt-image-gen 的 `-i` 註解）。**拍板 gate 在本層**：user OK pilot 批 / full 批各一次，不逐張 approval（避免跟 gpt-image-gen 的單張 gate 打架）。
- **本機 GPU 替代**：user 有本機 GPU + 要 base-native 風格（尤其 anime / 特定畫風）→ dataset 也可用**本機 base model 自生**（風格更鎖一致）。codex 不可用時這是 fallback，**不必硬停**。
- 本 skill 負責：規劃生什麼、定 prompt、gate 拍板、產物歸位（PNG）、caption、訓練、驗收。

## Workflow

### Stage 0 — 前提
- dataset 怎麼生？預設 codex（gpt-image-gen）；codex 不可用 / user 有本機 GPU 想要 base-native 風格 → 改本機 base model 自生（見「圖生成」）。**兩條都不通才停**。
- 角色有「定版 look」種子圖嗎？沒有 → 先做 Stage 1。

### Stage 1 — 角色定義 + 定版圖
- **1a** 跟 user 把「**不變 identity**（臉/體型/招牌特徵）」vs「**可變**（服裝/場景/配件如眼鏡）」切清楚 → 寫 `character.md`（SSOT）。
- **1b** 用 gpt-image-gen 生 / 鎖一張**定版圖**（text2img 或 img2img），留 codex prompt sidecar → `canonical/`。

### Stage 2 — 多角度 sheet（看一致性，非訓練圖）
- 用 gpt-image-gen 生一張多角度 sheet（正/側/背 + 表情），確認「同一個人」。
- ⚠️ **sheet ≠ 訓練圖**（拼貼會被學成「拼貼」）。只給人看 + 當 canonical 參考。

### Stage 3 — 資料集
- **3a pilot**：先生一小批（~6 張，建議：正面特寫×1 / 正面全身×1 / 左右側×各1 / 背面×1 / 表情×1）→（**你先自檢 flag、批量出 contact sheet**）→ 存專案給 user 看，確認 identity 對。
- **3b full**：user OK → 生其餘角度（**重用 pilot、不重生**）→ 合 pilot+full = `dataset/raw/`。
- 分佈：角度（正 / 3-4 側 / 全側 / 俯仰 / 背）× 取景（臉特寫 / 半身 / 全身）混合。**~40-50 精圖**（>100-150 = overfit；數字依 base、見 playbook）。全 **PNG 無損**。
- **3c 整備**：crop / resize 到訓練解析度、`enable_bucket` 吃多比例、必要時去背 / 統一光背景。codex 出圖比例不定 → 別直接餵，先整備。

### Stage 4 — captioning（照選定 base 格式）
| base 家族 | caption 格式 |
|---|---|
| Pony / SDXL / **anime-SDXL** | booru tags、trigger 第一 token：`<trig>, 1boy`（男）/`1girl`（女）`, from side, upper body, <scene>` |
| Z-Image / NL 模型 | 自然語言：`<trig> <class>, <scene>`（class word `man`/`woman`/`elf`… **必加**，防偏性別/類別） |
- 性別/類別字**按角色寫**（`1boy`/`1girl`、`man`/`woman`）— 範例用男只是範例。
- trigger = **非字典 token**（發明的，避免污染既有語義）。
- **只標可變**；identity 留白；toggle 配件（眼鏡）只在「有」的圖標。
- 訓練 caption **不放 quality/score tag**（推理才加，避免 style bleed）。

### Stage 5 — 選 base + 訓前功課（互動）
- **5a base 選型**（講優缺點、**user 選**）：

  | base | 寫實/特色 | explicit 內容 | 訓練器 | 備註 |
  |---|---|---|---|---|
  | **Anime-SDXL**（動漫專用 SDXL 底模） | 動漫 / 2D / cel-shaded | 看 merge | kohya | **動漫角色走這支**；booru caption；**底模選哪顆 → 5b 功課查當下主流** |
  | Pony V6 XL | 動漫底子強、寫實靠 merge | 原生 | kohya | 生態大、ControlNet 成熟 |
  | Z-Image(-Turbo) | 真人寫實最強之一 | 私密處會崩、需疊專用 LoRA | ai-toolkit only | 新；Turbo 要 training adapter |
  | 其他 | — | — | — | **一律先做 5b 功課** |

- **5b** 🔴 **訓前功課（red line 1）**：查選定 base 的官方訓練文件 + 社群配方。**驗收 = 你能講出該 base 的：caption 格式 / trigger 規範 / class-word 需求 / dim-alpha 範圍 / optimizer / 變體(Turbo)差異。講不出 = 沒做完、別訓。**
- **5c** 硬體/SSH 互動確認：訓練機在哪？有 SSH 設定就連、沒有就問 user 要（host/port/key）；確認 GPU、裝好訓練器。

### Stage 6 — 訓練
- **開訓 gate**：OOM 試跑不用 gate；**正式跑前報設定給 user、user 說 go 才開**（紅線 3）。
- **6a OOM 試跑**：小步數先驗設定不爆 VRAM / 不報錯。
- **6b 正式跑 + checker**：每隔一段把當前 sample **自檢 + flag 後**交付 user（見「交付但書」）。每 epoch / N 步存 checkpoint（**常非最後一個最好**）。

### Stage 7 — 訓後
- 0→100% montage 合成一張對比大圖交付 user。
- LoRA 存回專案 `models/`（權重 gitignore）。
- **run log**：每步 + 遇到的問題 + 避雷寫 `runs/<char>_<base>_vN/run_log.md`。

### Stage 8 — 推理 / 驗收
- 推理底模 / 設定照選定 base；**挑最佳 checkpoint**（測幾個比，非最後一個）。
- 寬景/全身掉臉 → face-detail pass（用 LoRA 重畫臉）。
- identity 不夠 → 判斷是 dim/alpha 弱 還是 dataset（「LoRA = 資料集的鏡子」，改特徵回去改**圖**、不是改 prompt）。

## 交付但書（圖怎麼給 user）
預設**報本機路徑**；user 說「直接給我看」→ scp 到互動時指定的資料夾；user 要用 IM 看 → **先確認 IM 能傳圖 + 打得到 user** 再傳。

## 自檢 + contact sheet（你是第二雙眼睛）
生成圖（dataset / 訓練 sample / 推理）交 user 前，**自己先 view 一遍、主動 flag 問題** — no-face / 崩臉 / 變性別 / 非預期動物或卡通特徵 / 框景裁頭 / 體型不符。**你或 subagent 的「看起來很好」是 input、不是事實** — 最終 user 判，但你不能當水管盲轉。
- **批量（數十張 dataset / 多 checkpoint 對比）→ 出 contact sheet**：`ffmpeg` 的 `tile` filter 或 `imagemagick montage` 拼成一張 grid，一次看、一眼抓異常格，不逐張。（注意有些 ffmpeg build 缺 `drawtext` → 標籤靠檔名 / caption 或改 imagemagick。）

## 失敗 → 根因 → 對策（速查；完整見 playbook.md）
| 症狀 | 根因 | 對策 |
|---|---|---|
| 角色每次抽籤 / 超飄 | dim/alpha 弱化 + optimizer 沒調 | 照 base 官方配方（dim 足、Prodigy/adafactor） |
| 寬景掉臉變別人 | 臉太小、base prior 接管 | face-detail pass |
| 出來變性別 | NL caption 沒 class word | caption 加 man/woman |
| 出現**非預期**動物/卡通特徵（要寫實卻跑卡通）| caption 有觸發該語義的字 | 拿掉那字、trigger 用非字典 token。⚠️ 你本來就要 anime/stylized → 那是 intended、**別拿掉** |
| 烤進的特徵 prompt 改不掉 | 特徵來自圖、非 caption | 改 dataset，不是改 prompt |

## Anti-patterns
- ❌ 憑印象配訓練參數、不查 base 官方/社群（= 抽籤）
- ❌ 把沒驗證的設定寫成「配方」
- ❌ 不拿 user 拍板就批量生圖 / 開訓
- ❌ sheet 拼貼當訓練圖
- ❌ caption 標 identity（臉/體型）
- ❌ 跨架構套 LoRA
- ❌ 用 prompt 硬改已烤進的特徵
- ❌ 用 close-up 框景判斷體型（看不到身體）
- ❌ 盲轉生成圖不自檢（「看起來很好」≠ 事實，要主動抓 no-face / 崩 / 變性別 / 動物特徵）
- ❌ 數十張圖逐張看 / 逐張傳（出 contact sheet 一次看）

## Important rules（核心 invariants）
1. **先做 base 功課再訓**（red line 1，最重要）。
2. 沒驗證的標 `proposed`，別當配方。
3. 每個花錢/算力步驟 user 先拍板。
4. LoRA 綁架構。
5. 標可變、留 identity。
6. 圖生成 delegate `gpt-image-gen`。
7. 交付依但書。
8. 訓練全程寫 run log。
9. 生成圖傳前**自檢 + flag**（你是第二雙眼睛）；批量出 **contact sheet** 一次看。

## References
- **`playbook.md`**（同目錄）— 完整方法論：每 stage 的 why / 決策樹、per-base 配方知識、完整失敗對策表、「base 功課怎麼做」清單。SKILL.md 是操作骨架，深度看 playbook。
- 依賴 skill：`gpt-image-gen`（codex 出圖，text2img + img2img）。