---
name: persona-icon
description: 產生或更新人格的形象圖（icon.svg + icon.png）：先找出該人格「最新一次登場」對應的**高解析度官方圖**（優先官方人設稿／設定圖，它們通常是透明底或白底、解析度遠高於資料庫縮圖），量測解析度與臉的大小後**去背**成透明 PNG，再裁成頭肩構圖、合成到取自角色配色的漸層底上，成為存取庫頭像並同步到 Gitea Wiki（含 icon/ 多解析度）。找不到可用的官方圖時，退回依人格資料重新繪製的向量人物形象。當使用者說要做人格頭像／形象圖／icon、要依角色最新造型更新圖示、說圖示不像或不夠清楚、或剛建立完人格要補圖示時觸發。不適用於：建立人格本身（persona-create／persona-anime）、同步到 Gitea（persona-sync）。
---

# 🎨 persona-icon — 依最新造型產生人格形象圖（有臉）

**CLI**：`node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs"`（帶 `--session <PERSONA_SESSION>`）
**時機**：**人格建立且 IDENTITY／SOUL 補齊之後**——形象綁在最終身分上。
**目標**：圖示要是**人物形象圖，看得到臉**；退而求其次才是抽象徽章。

**流程**：找高解析度官方圖 → 量測 → **去背** → 裁頭肩 → 合成 → 更新頭像與 Wiki。

> 找不到可用的官方圖時（沒有設定稿、只有場景截圖且去背不乾淨），
> 才退回「依人格資料重新繪製」的向量形象（`--style portrait`）。

---

## 為什麼要上網找圖

圖示要像這個人格，就得用他**現在**的樣子：動漫角色會換造型、換作品、換髮色。
所以流程是「查最新登場 → 看那張圖 → 取色 → 畫」，而不是憑印象填色。

## 步驟

### 1. 查出「最新一次登場」

用 WebSearch 確認這個角色最近的官方動向（新作、新章節、新造型）與**對應的形態名稱**
（例：亞絲娜 → 2026《Unanswered//butterfly》重述早期艾恩葛朗特 → 對應 **SAO Avatar**；
結衣 → 現行 Unital Ring 章 → 對應 **ALO Pixie Form**）。

### 2. 找高解析度官方圖

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" icon search --session <PERSONA_SESSION> --wiki <fandom 子網域> --page <角色頁名>
```

結果依「解析度 + 是不是官方設定稿」排序，標 📐 的是設定稿（`Full Body`／`Character Design`／
`Avatar`）。**優先選設定稿**：

- 解析度高（常見 773×1056、1280×880），遠勝角色資料庫的 230px 縮圖
- **多半是透明底或純白底 → 去背幾乎免費、邊緣乾淨**
- 是官方繪製的正式立繪，不是動畫截圖

挑「與第 1 步的形態相符」的那一張——同一個角色會有很多套造型。

### 3. 量測

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" icon measure --session <PERSONA_SESSION> --photo "<圖片網址>"
```

會回報解析度、找到幾張臉、臉佔長邊多少、背景是**透明／單色／有場景**、去背難不難。
`去背難度：偏難` 就回第 2 步換一張設定稿，不要硬做。

### 4. 去背

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" icon cutout --session <PERSONA_SESSION> --photo "<圖片網址>" [--pick <索引>]
```

三條路徑，自動選最好的那條：

| 方式 | 什麼時候 | 品質 |
| --- | --- | --- |
| `source-alpha` | 原圖本來就是透明底（官方設定稿常見） | 完美 |
| `plain-background` | 純白／單色底 | 很好 |
| `grabcut` | 有場景，用臉的位置當前景種子 | 普通，邊緣可能不乾淨 |

輸出到 `icon/portrait-cutout.png`。**用 Read 打開確認**：邊緣有沒有殘留、頭髮有沒有被切掉。
黑髮角色在有場景的圖上特別容易被 GrabCut 誤切——真的不行就換設定稿。

### 5. 合成圖示

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" icon generate --session <PERSONA_SESSION> --force --from-cutout [--zoom 1.85] [--pick <索引>] \
  --palette "hair=#..,eye=#..,accent=#..,secondary=#..,light=#..,skin=#.." \
  --source-url "<那張圖的網址>" --source-note "<作品／形態＋為什麼選這張>"
```

- 自動裁成**頭肩構圖**（官方設定稿常是正反兩面並排，不裁會變成兩個人；`--zoom` 調鬆緊）。
- 底色漸層取自 `--palette`（`light` → `accent`），所以要先看過圖再填顏色。
- 產出 `icon.svg`（內嵌同一張 PNG，自成一體不外連）、`icon.png`，以及
  `icon/portrait.svg`、`icon/portrait-512.png`、`icon/portrait-1024.png`。
- **畫完用 Read 打開看一眼**，構圖不好就調 `--zoom` 或 `--face` 重來。

### 6. 沒有官方圖時：向量重繪（有臉）

裁出大頭照當底稿、親眼看過、讀出特徵，再重繪：

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" icon headshot --session <PERSONA_SESSION> --photo "<圖片網址>" --pick <索引>   # 底稿，不同步
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" icon generate --session <PERSONA_SESSION> --force --palette "..." --features "hairstyle=..,eyes=..,expression=.."
```

特徵可選值：`hairstyle` straight/twintails/ponytail/bob/braid、`length` short/medium/long/very-long、
`fringe` blunt/parted/swept/curtain、`eyes` round/almond/sharp/droopy、
`expression` gentle/bright/calm/neutral、`accessory` none/ribbon/clip/flower/hairband、
`side` left/right、`collar` round/v/high/sailor、`ahoge` yes/no。

### 7. 回報

一句話說明：用了哪部作品哪一年的視覺、取到什麼配色、圖示放哪裡。
把來源網址附上，讓使用者可以自己核對。

## 三種樣式

| 樣式 | 什麼時候用 | 長什麼樣 |
| --- | --- | --- |
| `portrait` | 有底稿（有調色盤）→ **預設** | 依特徵重繪的人物頭像：髮型、瀏海、眼型、表情、髮飾、領口全部照特徵畫 |
| `badge` | 完全沒有參考圖（原創人格） | 雙色漸層徽章 + 編號前兩個字母 |

- 兩種樣式都由 Node 自己柵格化，SVG 與 PNG **共用同一份圖形清單**（橢圓／矩形／多邊形），
  兩邊必然一致；PNG 是自寫的柵格器 + zlib 編碼，不依賴任何影像函式庫。
- 每次產生會輸出：`icon.svg`／`icon.png`（512，頭像用）＋ `icon/portrait.svg`、
  `icon/portrait-512.png`、`icon/portrait-1024.png`（高解析度），全部同步到 Wiki。
- SVG **不會內嵌任何影像**——沒有 `<image>`、沒有 base64、沒有外連。
- `badge` 樣式下若兩個顏色一深一淺（藍黑髮 + 淡粉洋裝），程式會把較亮的一端往較暗的壓，
  確保字讀得到。

## 界線

- **找到的圖片只能當底稿**：裁出來的大頭照留在 `.sync/`，不進圖示、不同步、不發佈。
  圖示的每個像素都是本工具依特徵畫出來的。
- 底稿的來源網址會記在 `config.json`，方便日後核對，但不重製原圖。

## Wiki 必須同步

`icon generate` 推完 Wiki 會**自動回頭驗證**，確認 `icon.svg` 與 `icon.png` 真的在 Wiki 上
而且與本機一致；不一致會直接報錯。也可以手動查：

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" sync verify --session <PERSONA_SESSION> --area wiki
```

## 邊界

- 只能對「本 session 已載入的人格」產生圖示。
- 已有圖示時要重畫必須加 `--force`。
- 不帶 `--palette` 重畫會**沿用 config 裡已存的配色**（不會突然變回雜湊色）。
- `.sync/reference.*` 與 `.sync/headshot.png` 是底稿快取，可以安全刪除（不會同步出去）。
- 所有面向使用者的輸出使用**繁體中文（台灣用語）**、UTF-8 無亂碼。