@playcraft/cli 0.0.57 → 0.0.59

package/project-template-v2/.claude/skills/brainstorming/visual-companion.md

@@ -0,0 +1,309 @@
+# Visual Companion Guide
+
+Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
+
+## When to Use
+
+Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
+
+**Use the browser** when the content itself is visual:
+
+- **UI mockups** — wireframes, layouts, navigation structures, component designs
+- **Architecture diagrams** — system components, data flow, relationship maps
+- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
+- **Design polish** — when the question is about look and feel, spacing, visual hierarchy
+- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
+
+**Use the terminal** when the content is text or tabular:
+
+- **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
+- **Conceptual A/B/C choices** — picking between approaches described in words
+- **Tradeoff lists** — pros/cons, comparison tables
+- **Technical decisions** — API design, data modeling, architectural approach selection
+- **Clarifying questions** — anything where the answer is words, not a visual preference
+
+A question _about_ a UI topic is not automatically a visual question. "What kind of wizard do you want?" is conceptual — use the terminal. "Which of these wizard layouts feels right?" is visual — use the browser.
+
+## How It Works
+
+The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content to `screen_dir`, the user sees it in their browser and can click to select options. Selections are recorded to `state_dir/events` that you read on your next turn.
+
+**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, selection indicator, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
+
+## Starting a Session
+
+```bash
+# Start server with persistence (mockups saved to project)
+scripts/start-server.sh --project-dir /path/to/project
+
+# Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
+#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
+#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
+```
+
+Save `screen_dir` and `state_dir` from the response. Tell user to open the URL.
+
+**Finding connection info:** The server writes its startup JSON to `$STATE_DIR/server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.superpowers/brainstorm/` for the session directory.
+
+**Note:** Pass the project root as `--project-dir` so mockups persist in `.superpowers/brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.superpowers/` to `.gitignore` if it's not already there.
+
+**Launching the server by platform:**
+
+**Claude Code (macOS / Linux):**
+
+```bash
+# Default mode works — the script backgrounds the server itself
+scripts/start-server.sh --project-dir /path/to/project
+```
+
+**Claude Code (Windows):**
+
+```bash
+# Windows auto-detects and uses foreground mode, which blocks the tool call.
+# Use run_in_background: true on the Bash tool call so the server survives
+# across conversation turns.
+scripts/start-server.sh --project-dir /path/to/project
+```
+
+When calling this via the Bash tool, set `run_in_background: true`. Then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
+
+**Codex:**
+
+```bash
+# Codex reaps background processes. The script auto-detects CODEX_CI and
+# switches to foreground mode. Run it normally — no extra flags needed.
+scripts/start-server.sh --project-dir /path/to/project
+```
+
+**Gemini CLI:**
+
+```bash
+# Use --foreground and set is_background: true on your shell tool call
+# so the process survives across turns
+scripts/start-server.sh --project-dir /path/to/project --foreground
+```
+
+**Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
+
+If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
+
+```bash
+scripts/start-server.sh \
+  --project-dir /path/to/project \
+  --host 0.0.0.0 \
+  --url-host localhost
+```
+
+Use `--url-host` to control what hostname is printed in the returned URL JSON.
+
+## The Loop
+
+1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
+   - Before each write, check that `$STATE_DIR/server-info` exists. If it doesn't (or `$STATE_DIR/server-stopped` exists), the server has shut down — restart it with `start-server.sh` before continuing. The server auto-exits after 30 minutes of inactivity.
+   - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
+   - **Never reuse filenames** — each screen gets a fresh file
+   - Use Write tool — **never use cat/heredoc** (dumps noise into terminal)
+   - Server automatically serves the newest file
+
+2. **Tell user what to expect, then block on `wait-for-selection.sh`:**
+   - Tell the user the URL and briefly describe what's on screen (e.g., "Showing 3 layout options")
+   - Immediately run `scripts/wait-for-selection.sh "$STATE_DIR"` — this blocks until the user acts in the browser
+   - **Do not end your turn asking the user to return to the terminal.** The script unblocks automatically.
+
+   ```bash
+   scripts/wait-for-selection.sh "$STATE_DIR"
+   # returns JSON like:
+   # {"type":"confirm","choices":[{"choice":"a","text":"Single Column"}],"other":"","timestamp":...}
+   # {"type":"reject","timestamp":...}
+   ```
+
+3. **Parse the result and continue:**
+   - `type === "confirm"` — `choices` has selected options (may be empty if user only typed), `other` has free-text input (may be empty)
+   - `type === "reject"` — user declined; treat as "none of these, let's reconsider"
+   - Either way, **continue immediately** without asking the user to type anything in the terminal
+
+4. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
+
+5. **Unload when returning to terminal** — when the next step doesn't need the browser (e.g., a clarifying question, a tradeoff discussion), push a waiting screen to clear the stale content:
+
+   ```html
+   <!-- filename: waiting.html (or waiting-2.html, etc.) -->
+   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
+     <p class="subtitle">Continuing in terminal...</p>
+   </div>
+   ```
+
+   This prevents the user from staring at a resolved choice while the conversation has moved on. When the next visual question comes up, push a new content file as usual.
+
+6. Repeat until done.
+
+## Writing Content Fragments
+
+Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, selection indicator, and all interactive infrastructure).
+
+**Minimal example:**
+
+```html
+<h2>Which layout works better?</h2>
+<p class="subtitle">Consider readability and visual hierarchy</p>
+
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Single Column</h3>
+      <p>Clean, focused reading experience</p>
+    </div>
+  </div>
+  <div class="option" data-choice="b" onclick="toggleSelect(this)">
+    <div class="letter">B</div>
+    <div class="content">
+      <h3>Two Column</h3>
+      <p>Sidebar navigation with main content</p>
+    </div>
+  </div>
+</div>
+```
+
+That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
+
+## CSS Classes Available
+
+The frame template provides these CSS classes for your content:
+
+### Options (A/B/C choices)
+
+```html
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Title</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+**Multi-select:** Add `data-multiselect` to the container to let users select multiple options. Each click toggles the item. The indicator bar shows the count.
+
+```html
+<div class="options" data-multiselect>
+  <!-- same option markup — users can select/deselect multiple -->
+</div>
+```
+
+### Cards (visual designs)
+
+```html
+<div class="cards">
+  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
+    <div class="card-image"><!-- mockup content --></div>
+    <div class="card-body">
+      <h3>Name</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+### Mockup container
+
+```html
+<div class="mockup">
+  <div class="mockup-header">Preview: Dashboard Layout</div>
+  <div class="mockup-body"><!-- your mockup HTML --></div>
+</div>
+```
+
+### Split view (side-by-side)
+
+```html
+<div class="split">
+  <div class="mockup"><!-- left --></div>
+  <div class="mockup"><!-- right --></div>
+</div>
+```
+
+### Pros/Cons
+
+```html
+<div class="pros-cons">
+  <div class="pros">
+    <h4>Pros</h4>
+    <ul>
+      <li>Benefit</li>
+    </ul>
+  </div>
+  <div class="cons">
+    <h4>Cons</h4>
+    <ul>
+      <li>Drawback</li>
+    </ul>
+  </div>
+</div>
+```
+
+### Mock elements (wireframe building blocks)
+
+```html
+<div class="mock-nav">Logo | Home | About | Contact</div>
+<div style="display: flex;">
+  <div class="mock-sidebar">Navigation</div>
+  <div class="mock-content">Main content area</div>
+</div>
+<button class="mock-button">Action Button</button>
+<input class="mock-input" placeholder="Input field" />
+<div class="placeholder">Placeholder area</div>
+```
+
+### Typography and sections
+
+- `h2` — page title
+- `h3` — section heading
+- `.subtitle` — secondary text below title
+- `.section` — content block with bottom margin
+- `.label` — small uppercase label text
+
+## Browser Events Format
+
+When the user clicks options in the browser, their interactions are recorded to `$STATE_DIR/events` (one JSON object per line). The file is cleared automatically when you push a new screen.
+
+```jsonl
+{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
+{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
+{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
+```
+
+The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
+
+If `$STATE_DIR/events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
+
+## Design Tips
+
+- **Scale fidelity to the question** — wireframes for layout, polish for polish questions
+- **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
+- **Iterate before advancing** — if feedback changes current screen, write a new version
+- **2-4 options max** per screen
+- **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
+- **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
+
+## File Naming
+
+- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
+- Never reuse filenames — each screen must be a new file
+- For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
+- Server serves newest file by modification time
+
+## Cleaning Up
+
+```bash
+scripts/stop-server.sh $SESSION_DIR
+```
+
+If the session used `--project-dir`, mockup files persist in `.superpowers/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
+
+## Reference
+
+- Frame template (CSS reference): `scripts/frame-template.html`
+- Helper script (client-side): `scripts/helper.js`

package/project-template-v2/.claude/skills/playcraft-ad-psychology/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: playcraft-ad-psychology
+description: 可玩广告心理设计指南。涵盖四大心理钩子（好奇心缺口/FOMO/即时满足/进度错觉）、60-30-10 色彩法则、CTA 设计规范、各阶段情感设计目标与常见错误。按游戏类型配色方案和音频情绪弧参数见 refs/artist-color-audio-recipes.md。
+triggers: 广告心理,ad psychology,钩子,hook设计,FOMO,近胜,near-win,CTA设计,色彩法则,60-30-10,颜色策略,配色方案,情感弧,emotional arc,安装率,CTR,转化率,EndCard设计,进度条设计,游戏广告设计
+---
+
+# 可玩广告心理设计完整指南
+
+## 0. 核心认知：优化目标是 CTR，不是游戏时长
+
+**最重要的一句话**：可玩广告的成功指标是**安装点击率（CTR > 3%）**，不是玩家在广告内的游戏时长或互动率。
+
+这意味着：
+
+- EndCard 不应该是"胜利满足感"，而应该是"还没玩够"
+- Tutorial 的目标不是让玩家学会玩，而是让玩家感到"我可以玩"
+- Gameplay 不需要公平，需要的是让玩家觉得"再给我一次机会"
+- 每一帧设计都要服务于最终的 CTA 点击
+
+---
+
+## 1. 四大心理钩子
+
+### 钩子 1：好奇心缺口（Curiosity Gap）
+
+**心理原理**：人脑对"未完成"状态有强烈的认知驱动——看到一个悬而未决的问题，大脑会持续寻求解答。
+
+**视觉设计指令**：
+
+- Near-Win 状态：关键元素差一步就能达成（最后一块砖、差 1 颗星、进度条 95%）
+- 不展示解法：只给出问题和"差一点"的状态，**不给解答**
+- 制造张力：用视觉聚焦（模糊背景、高亮关键元素）引导注意力到未解决点
+
+**Prompt 关键词**：`near win moment`, `almost there`, `one step away`, `progress bar at 95%`, `last piece missing`, `unresolved puzzle state`
+
+**错误做法**：在 Gameplay 帧展示"已解决"的完美状态（会消除好奇心，减少安装动机）
+
+---
+
+### 钩子 2：FOMO + 损失厌恶（Fear of Missing Out）
+
+**心理原理**：人对"失去"的感受比对"获得"的感受强 2 倍（Kahneman 损失厌恶理论）。
+
+**视觉设计指令**：
+
+- EndCard 展示"未拿到的奖励"：宝箱半开、金币散落地面、奖励图标模糊显示
+- 不展示胜利：不要"恭喜通关"、不要奖励动画播放完毕的满足状态
+- 制造"差一步就错过"感：宝箱即将关闭、计时器快到零、稀有道具即将消失
+
+**Prompt 关键词**：`treasure chest half open`, `rewards about to expire`, `coins scattered uncollected`, `rare item visible but unreachable`, `countdown almost zero`, `last chance visual`
+
+**EndCard 设计原则**：
+
+1. 主视觉 = 最有价值的游戏内奖励（大宝箱/稀有角色/大金币堆）
+2. 这些奖励处于"触手可及但尚未到手"的状态
+3. CTA 按钮 = 唯一能拿到这些奖励的路径
+
+---
+
+### 钩子 3：即时满足（Instant Gratification）
+
+**心理原理**：人类偏好立即的小奖励胜过未来的大奖励。Tutorial 阶段的核心任务是让玩家在 3-5 秒内体验到"做对了"的反馈。
+
+**视觉设计指令**：
+
+- Tutorial 帧必须"一眼看懂"：画面信息密度最低（只显示 1-2 个可交互元素）
+- 手势引导要大而清晰：手指点击图标 / 虚线箭头 / 高亮光圈，尺寸不小于元素的 1.5 倍
+- 交互结果要夸张：正确操作的视觉反馈（爆炸、星星、得分）要比实际游戏中更夸张
+- 色温略暖：相比 Hook 帧，Tutorial 帧整体色温偏暖，降低压迫感
+
+**Prompt 关键词**：`large finger tap indicator`, `glowing highlight around target`, `bright tutorial arrow`, `warm color temperature`, `simplified single element focus`, `satisfying immediate feedback animation`
+
+**Tutorial 禁忌**：
+
+- 不要出现文字说明（玩家不读广告里的文字）
+- 不要出现超过 3 个可交互元素（信息过载）
+- 不要让 Tutorial 让玩家失败（第一次操作必须成功）
+
+---
+
+### 钩子 4：进度错觉（Progress Illusion）
+
+**心理原理**：看到已完成的进度会激励继续完成，人们对"快完成了"比对"刚开始"更有动力。
+
+**视觉设计指令**：
+
+- 进度条设计在 75-90% 满格状态（而不是 0% 或 50%）
+- 血条/能量条接近满格但不满（如 85%）
+- 积分显示接近整数关卡（如 "980/1000" 而不是 "100/1000"）
+- 成就/收集类：显示"5/6 已收集"而不是"收集了 5 个"
+
+**Prompt 关键词**：`progress bar 80% full`, `health bar nearly complete`, `score counter almost at milestone`, `collection 5 of 6 complete`, `achievement nearly unlocked`
+
+---
+
+## 2. 各阶段情感设计目标
+
+| 阶段         | 时段   | 情感目标    | 关键视觉指标                       |
+| ------------ | ------ | ----------- | ---------------------------------- |
+| **Hook**     | 0–3s   | 震撼 + 好奇 | 最高对比度，最大动感，主视觉冲击   |
+| **Tutorial** | 3–10s  | 安全 + 自信 | 最低信息密度，暖色调，大手势图标   |
+| **Gameplay** | 10–25s | 沉浸 + 紧张 | 进度错觉，Near-Win，最高信息密度   |
+| **EndCard**  | 25–30s | 遗憾 + 渴望 | 奖励可见但未得，CTA 高对比，未竟感 |
+
+---
+
+## 3. 60-30-10 色彩法则（可玩广告版）
+
+### 三色分配
+
+```
+总画面配色 = 60% 主色（背景/场景） + 30% 辅色（游戏主元素） + 10% 强调色（CTA专用）
+```
+
+**"对比稀缺性"原则**：强调色（10%）只出现在 CTA 按钮上时，玩家视线会被自动吸引到 CTA——强调色越少出现在其他地方，CTA 的吸引力越强。
+
+**违规示例**：在游戏元素上大量使用橙色，然后 CTA 按钮也用橙色 → CTA 消失在视觉噪音中。
+
+**正确示例**：游戏用蓝绿主色调，只有 CTA 按钮使用金橙色 → CTA 一眼突出。
+
+## 4. CTA 设计规范
+
+### 尺寸与位置
+
+| 规范项       | 要求                       | 原因                             |
+| ------------ | -------------------------- | -------------------------------- |
+| 最小点击区域 | 48×48 px（设备物理像素）   | 手指触控目标尺寸，防止误触       |
+| 距屏幕边缘   | ≥ 48 px                    | 防止被平台 UI 遮挡，避免误触边框 |
+| 视觉建议尺寸 | 200–400 px 宽（9:16 屏幕） | 足够显眼但不干扰游戏区域         |
+| 位置         | 底部 1/4 区域，水平居中    | 符合拇指操作习惯                 |
+
+### 对比度规范
+
+CTA 按钮与其背景的对比度必须 **≥ 4.5:1**（WCAG AA 标准）。
+
+```
+常见合规组合（按钮色/背景色）：
+- 金橙 #F5A623 / 深蓝 #0D1B2A → 对比度 ~8.5:1 ✅
+- 纯白 #FFFFFF / 主色按钮 → 白色文字在深色按钮上 ✅
+- 鲜绿 #00C851 / 深灰 #222222 → 对比度 ~6.2:1 ✅
+- 浅黄 #FFFF99 / 白色背景 → 对比度 ~1.2:1 ❌（不合规）
+```
+
+快速验证工具：告诉 Artist 用 `playcraft tools research --query "color contrast checker [color1] vs [color2]"` 快速查询。
+
+### 文案优先级
+
+| 优先级    | 文案           | 适用场景                  |
+| --------- | -------------- | ------------------------- |
+| 1（最优） | `Play Now`     | 休闲/消除游戏（情感驱动） |
+| 2         | `Install Free` | 强调免费降低决策成本      |
+| 3         | `Download`     | 通用，略弱于上两者        |
+| 4（避免） | `Click Here`   | 无情感引导，降低 CTR      |
+
+**Google Ads 限制**：不可将 "Download" 或 "Install" 文字**直接叠加在图片上**（会被审核拒绝）。应将文案放在按钮内的独立颜色区域。
+
+### CTA 动画建议
+
+- 使用 `pulse` 动画（参考 `playcraft-vfx-animation` Skill）引导注意力
+- 脉冲频率：1.5-2 秒一次（过快令人烦躁，过慢不引人注意）
+- 第一次脉冲时机：EndCard 出现后 0.5 秒开始
+
+---
+
+## 5. 常见设计错误
+
+| 错误                       | 原因                                      | 正确做法                         |
+| -------------------------- | ----------------------------------------- | -------------------------------- |
+| EndCard 展示胜利/满足状态  | 消除了 FOMO，玩家觉得"看完了，不用下载了" | 展示"差一步"的遗憾状态           |
+| Tutorial 有文字说明        | 玩家不读广告文字                          | 用图形化引导（手势图标/箭头）    |
+| CTA 颜色与游戏主色相同     | 对比稀缺性失效，CTA 不显眼                | CTA 用画面中唯一一种高对比强调色 |
+| Gameplay 展示玩家失败      | 让玩家觉得游戏太难，不想下载              | 展示"即将成功"的 Near-Win 状态   |
+| Hook 超过 3 秒才出现主视觉 | 用户已划走                                | 0 帧就要高对比主视觉，无过渡铺垫 |
+| 信息密度全帧均等           | 视觉无重点，注意力分散                    | 每帧只有一个视觉焦点             |
+
+---
+
+## 6. 按游戏类型配色方案与音频情绪弧
+
+按游戏类型的配色方案（休闲消除、策略战争、益智解谜、RPG 奇幻，含 hex 值与情感定位）和完整音频情绪弧设计参数（BGM 各阶段 BPM、垂直重编排、SFX 时长标准、音频-视觉对齐检查清单）：
+
+详见 `refs/artist-color-audio-recipes.md`。

package/project-template-v2/.claude/skills/playcraft-art-style-guide/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: playcraft-art-style-guide
+description: 可玩广告美术风格选择与应用指南。涵盖 9 种主流风格的视觉特征、选型决策树（按游戏类型/受众/品牌调性）、风格对生产流水线的影响、以及各风格的 prompt 核心策略。Artist 在 Phase 1 确定美术方向前必读。
+triggers: 美术风格,art style,像素风,pixel art,写实,realistic,卡通,cartoon,扁平,flat,科技风,tech,科幻,sci-fi,赛博朋克,cyberpunk,奇幻,fantasy,中国风,chinese,水彩,watercolor,手绘,Q版,chibi,风格选择,style direction,视觉风格
+---
+
+# PlayCraft 美术风格选择与应用指南
+
+## 0. 风格选择的设计思考
+
+美术风格不是"好看就行"——它直接影响：
+
+- **CTR 表现**：风格与目标受众的审美期待是否匹配
+- **生产成本**：不同风格对 AI 生图质量要求和后处理复杂度差异极大
+- **文件体积**：像素风天然小，写实风天然大——直接影响 5MB 预算分配
+- **TA 管线**：像素风需要整数倍缩放 + 限色板；写实风需要高分辨率 + 精细抠图
+
+**风格决策时机**：Game Designer 在 `design-brief.md` 的 StyleDirection 中定义方向，Artist 在 Phase 1 具体化并生成样本验证。
+
+---
+
+## 1. 风格选型决策树
+
+```
+游戏类型 + 目标受众？
+│
+├─ 休闲消除/益智 + 全年龄
+│   ├─ 追求高辨识度/IP感 → Q版/Chibi
+│   ├─ 追求简洁现代 → 扁平卡通
+│   └─ 追求怀旧/独特 → 像素风
+│
+├─ 卡牌/棋牌/麻将 + 成年用户
+│   ├─ 中国市场 → 中国传统风
+│   ├─ 全球市场/高端感 → 写实/半写实
+│   └─ 年轻用户/轻量感 → 扁平卡通
+│
+├─ 动作/射击/跑酷 + 年轻男性
+│   ├─ 现代/都市 → 赛博朋克/科技风
+│   ├─ 太空/未来 → 科幻风
+│   └─ 魔法/剑与盾 → 奇幻风
+│
+├─ 模拟经营/养成 + 女性/全年龄
+│   ├─ 追求温暖治愈 → 水彩/手绘
+│   ├─ 追求可爱萌系 → Q版/Chibi
+│   └─ 追求清新文艺 → 扁平卡通
+│
+└─ RPG/冒险 + 核心玩家
+    ├─ 西方奇幻 → 奇幻风
+    ├─ 东方仙侠 → 中国传统风
+    └─ 暗黑/硬核 → 写实/半写实
+```
+
+---
+
+## 2. 九种风格速览
+
+| #   | 风格                | 视觉特征                             | 体积倾向 | AI 生图难度      | 最佳模型             |
+| --- | ------------------- | ------------------------------------ | -------- | ---------------- | -------------------- |
+| 1   | **像素风**          | 方块化、限色板(8-32色)、无抗锯齿     | 极小     | 中（需严格限色） | gpt-image-2          |
+| 2   | **扁平卡通**        | 粗描边、纯色填充、几何化、无渐变阴影 | 小       | 低               | 任意模型             |
+| 3   | **Q版/Chibi**       | 大头身比(2-3头)、圆润形状、夸张表情  | 小-中    | 低               | 任意模型             |
+| 4   | **写实/半写实**     | 真实光影、材质细节、自然比例         | 大       | 高（细节要求高） | gpt-image-2          |
+| 5   | **中国传统风**      | 水墨笔触、留白、金色装饰、书法元素   | 中       | 中（需文化细节） | gpt-image-2          |
+| 6   | **赛博朋克/科技风** | 霓虹光、暗底、几何线条、HUD 叠加     | 中       | 中               | gpt-image-2 / gemini |
+| 7   | **科幻风**          | 金属质感、星空、全息UI、冷色调       | 中       | 中               | gpt-image-2          |
+| 8   | **奇幻/魔法**       | 发光粒子、魔法阵、饱和色彩、神秘光   | 中-大    | 中               | gpt-image-2          |
+| 9   | **水彩/手绘**       | 纸质纹理、渗透感、不规则边缘、柔和   | 中       | 中（边缘控制难） | gpt-image-2          |
+
+---
+
+## 3. 风格对 TA 管线的影响
+
+| 风格        | 缩放策略                              | 抠图难度          | VFX 适配                 | 特殊注意                        |
+| ----------- | ------------------------------------- | ----------------- | ------------------------ | ------------------------------- |
+| 像素风      | 整数倍(`--scale 2/4/8`)，禁止分数缩放 | 低（硬边）        | `pixelate` 后 VFX        | 缩放后禁用抗锯齿                |
+| 扁平卡通    | 任意缩放                              | 低（粗描边清晰）  | 所有 VFX 兼容            | 描边粗细要统一                  |
+| Q版/Chibi   | 任意缩放                              | 低-中             | 所有 VFX 兼容            | 头身比一致性                    |
+| 写实/半写实 | 只降不升(原图需高分辨率)              | 高（毛发/半透明） | 写实 VFX 慎用卡通预设    | 需 AI 去背(--method ai)         |
+| 中国传统风  | 任意缩放                              | 中（水墨渐变边）  | glow/sparkle 适合        | 文字必须楷体/行书               |
+| 赛博朋克    | 任意缩放                              | 中（发光溢出）    | glow/starburst 适合      | 发光边缘保留，不要过度 trim     |
+| 科幻风      | 任意缩放                              | 中                | glow/impact_ring 适合    | 金属质感需 reference-image 锁定 |
+| 奇幻/魔法   | 任意缩放                              | 中（魔法粒子）    | sparkle/glow/starburst   | 粒子效果保留半透明              |
+| 水彩/手绘   | 任意缩放                              | 高（不规则边缘）  | 慎用——VFX 可能破坏手绘感 | trim threshold 要高(30+)        |
+
+---
+
+## 4. Prompt 核心策略（按风格）
+
+每种风格的 prompt 都遵循公式：`[主体] + [风格关键词] + [技术约束] + [负面约束]`
+
+| 风格      | 核心关键词                                                                     | 必加约束                | 必加负面                                              |
+| --------- | ------------------------------------------------------------------------------ | ----------------------- | ----------------------------------------------------- |
+| 像素风    | `pixel art, 8-bit, limited N-color palette, sharp pixels, no anti-aliasing`    | 指定色板数量            | `no smooth gradients, no anti-aliasing, no blur`      |
+| 扁平卡通  | `flat 2D vector, bold outlines, solid color fills, minimal shading`            | 描边粗细(如 3px)        | `no gradient, no 3D effect, no realistic shading`     |
+| Q版/Chibi | `chibi style, cute, 2.5-head proportion, round shapes, big eyes`               | 头身比                  | `no realistic proportion, no thin limbs`              |
+| 写实      | `photorealistic, detailed textures, natural lighting, high resolution`         | 光源方向                | `no cartoon, no flat color, no cel-shading`           |
+| 中国传统  | `Chinese traditional ink painting, brush strokes, elegant, gold accents`       | 留白比例                | `no western fantasy, no neon, no modern UI`           |
+| 赛博朋克  | `cyberpunk, neon glow, dark background, holographic, circuit patterns`         | 发光色(如 cyan/magenta) | `no nature, no warm colors, no daylight`              |
+| 科幻      | `sci-fi, metallic surfaces, space, holographic UI, cold blue lighting`         | 材质(金属/玻璃)         | `no organic textures, no warm wood, no fantasy magic` |
+| 奇幻      | `fantasy art, magical glow, ethereal, mystical atmosphere, rich colors`        | 光源类型(魔法光)        | `no modern technology, no sci-fi, no urban`           |
+| 水彩      | `watercolor painting, soft edges, paper texture, transparent washes, artistic` | 纸张纹理                | `no hard edges, no digital look, no sharp outlines`   |
+
+---
+
+## 5. 风格一致性检查点
+
+生成样本后，对照以下维度确认风格执行是否到位：
+
+| 维度     | 检查方法                     | 不通过时调整             |
+| -------- | ---------------------------- | ------------------------ |
+| **色板** | 肉眼对比概念图主色           | prompt 加具体 hex 值     |
+| **描边** | 放大看边缘处理               | 加/减 `bold outline Npx` |
+| **光影** | 对比光源方向和阴影风格       | 明确光照描述             |
+| **材质** | 对比表面纹理(哑光/光泽/粗糙) | 加材质修饰词             |
+| **比例** | 对比元素间大小关系           | 加尺寸约束描述           |
+
+---
+
+## 6. 详细参考
+
+每种风格的完整 prompt 示例、模型推荐、TA 管线详细配置、常见错误与修正：
+
+> **Read `refs/artist-art-style-catalog.md`**