Skill: nicky1108/kart-io-picture-book-wizard (version 1.0.0)

--- name: picture-book-wizard description: A specialized skill for generating high-quality, consistent children's bilingual picture books using 'banana nano'. Supports 18 visual styles across 4 categories (7 core children's book styles, 5 atmospheric styles, 5 Chinese cultural styles, 1 specialized), 12 scenes (5 nature + 7 cultural), age-driven dynamic content system (ages 3-12), and expanded learning domains (science, math, history, psychology, etc.). Use when the user wants to create picture book stories, prompts, or learning materials. argument-hint: "[style] [scene] [age] [pages-optional] [character-optional]" --- # Picture Book Wizard / 绘本魔法师 A professional picture book creation skill that generates bilingual (Chinese/English) educational content with optimized image prompts for the 'banana nano' generator. 专业的绘本创作技能，生成中英双语教育内容，并为 'banana nano' 生成器优化图像提示词。 --- ## Language Versions / 语言版本 | Language | File | Description | |----------|------|-------------| | **English** | [`SKILL-en.md`](./SKILL-en.md) | Full documentation in English | | **中文** | [`SKILL-zh.md`](./SKILL-zh.md) | 完整中文文档 | --- ## Quick Start / 快速开始 **Usage / 用法**: `/picture-book-wizard [style] [scene] [age] [pages-optional] [character-optional] [soul-optional]` ### Examples / 示例 ```bash # Age-Based Generation / 基于年龄生成 /picture-book-wizard watercolor meadow 4 /picture-book-wizard clay forest 8 5 /picture-book-wizard nianhua kitchen 10 7 xiaoming # With Soul Elements / 带灵魂元素 /picture-book-wizard watercolor forest 8 yueyue emotion:curious /picture-book-wizard storybook meadow 5 theme:friendship # With Multi-Character / 带多角色 /picture-book-wizard watercolor kitchen 6 yueyue with:grandma theme:family ``` --- ## Available Styles / 可用风格 (18 total) | Category | Styles | |----------|--------| | **Core / 核心** | `storybook`, `watercolor`, `gouache`, `crayon`, `colored-pencil`, `clay`, `paper-cut` | | **Atmospheric / 氛围** | `dreamy`, `fairytale`, `collage`, `fabric`, `felt` | | **Chinese Cultural / 中国文化** | `ink`, `ink-line`, `nianhua`, `porcelain`, `shadow-puppet` | | **Specialized / 专业** | `tech` | --- ## Available Characters / 可用角色 | Character | Age | Personality | |-----------|-----|-------------| | `yueyue` 悦悦 | 5yo | Curious and gentle / 好奇温柔 (Default) | | `xiaoming` 小明 | 6yo | Adventurous and energetic / 爱冒险有活力 | | `lele` 乐乐 | 3yo | Cheerful and innocent / 开朗天真 | | `meimei` 美美 | 4yo | Creative and imaginative / 有创意爱想象 | --- ## For Complete Documentation / 完整文档 Please refer to the language-specific files: - **English**: [`SKILL-en.md`](./SKILL-en.md) - **中文**: [`SKILL-zh.md`](./SKILL-zh.md)

path: README.md
content: # Picture Book Wizard

[English](#english) | [中文](#中文)

---

## English

A Claude Code skill for generating high-quality, consistent children's bilingual picture books with AI image prompts.

### Features

- **18 Visual Styles** across 4 categories:
  - Core Children's Book: storybook, watercolor, gouache, crayon, colored-pencil, clay, paper-cut
  - Atmospheric: dreamy, fairytale, collage, fabric, felt
  - Chinese Cultural: ink, ink-line, nianhua, porcelain, shadow-puppet
  - Specialized: tech

- **12 Core Scenes**: meadow, pond, rice-paddy, stars, forest, kitchen, courtyard, market, temple, festival, grandma-room, kindergarten

- **Age-Driven Content System** (ages 3-12): Auto-adjusts page count, vocabulary, and learning objectives

- **Character Consistency Lock Protocol (CCLP 4.0)**: Ensures consistent character appearance across multi-page stories

- **Bilingual Output**: Chinese/English with accurate pinyin and tone marks

- **Optimized for 'banana nano'**: Image prompts designed for AI image generation

### Installation

1. Clone the repository:
```bash
git clone https://github.com/kart-io/picture-skills.git
```

2. Copy the skill to your Claude Code skills directory:
```bash
cp -r picture-skills/.claude/skills/picture-book-wizard ~/.claude/skills/
```

3. The skill is now available in Claude Code.

### Usage

Basic syntax:
```bash
/picture-book-wizard [style] [scene] [age] [pages-optional] [character-optional]
```

#### Examples

```bash
# Age-based generation (recommended)
/picture-book-wizard watercolor meadow 4
/picture-book-wizard clay forest 8 5
/picture-book-wizard nianhua kitchen 10 7 xiaoming

# With soul elements (emotion, theme)
/picture-book-wizard watercolor forest 8 yueyue emotion:curious
/picture-book-wizard storybook meadow 5 theme:friendship

# With multi-character
/picture-book-wizard watercolor kitchen 6 yueyue with:grandma theme:family

# Helper commands
/picture-book-wizard help:style warm cozy
/picture-book-wizard help:character age:4 theme:creative
```

### Available Characters

| Character | Age | Personality |
|-----------|-----|-------------|
| Yueyue (悦悦) | 5 | Curious and gentle (Default) |
| Xiaoming (小明) | 6 | Adventurous and energetic |
| Lele (乐乐) | 3 | Cheerful and innocent |
| Meimei (美美) | 4 | Creative and imaginative |

Supporting characters: grandma, dad, mom, grandpa, sibling
Animal companions: cat, dog, rabbit, chick, duckling, etc.

### Project Structure

```
picture-skills/
├── .claude/skills/picture-book-wizard/
│   ├── SKILL.md              # Skill definition (required)
│   ├── engine/               # Python rule engine
│   ├── scripts/              # Automation scripts
│   ├── references/           # Reference materials
│   │   ├── config/           # Configuration files
│   │   ├── examples/         # Working examples
│   │   └── guides/           # Documentation
│   └── assets/               # Static resources
│       └── templates/        # Output templates
├── output/                   # Generated content
│   └── picture-books/
└── scripts/                  # Project utilities
```

### Output

Generated stories are saved to:
```
./output/picture-books/[YYYY-MM]/[style]-[scene]-[character]-[pages]-[timestamp].md
```

Each output includes:
- Bilingual story text (Chinese/English)
- Learning focus with Chinese characters
- Optimized image prompts for AI generation
- Character consistency markers

### Configuration

Detailed configuration files are located in `.claude/skills/picture-book-wizard/references/config/`:

| Category | Files |
|----------|-------|
| Core | characters.md, styles.md, scenes.md, age-system.md |
| CCLP | character-consistency-lock.md, CCLP-FLEXIBILITY.md |
| Advanced | story-soul.md, scene-matching.md, reality-validation.md |

### Specification Compliance

This project follows the [Anthropic Agent Skills Specification](https://agentskills.io/specification) with:
- Progressive disclosure architecture
- Standard directory structure
- Clear separation of concerns

### License

MIT License

---

## 中文

一个 Claude Code 技能，用于生成高质量、角色一致的儿童双语绘本及 AI 图像提示词。

### 特性

- **18 种视觉风格**，分为 4 大类：
  - 核心绘本风格：故事书、水彩、水粉、蜡笔、彩铅、黏土、剪纸
  - 氛围增强风格：梦幻、童话、拼贴、布艺、毛毡
  - 中国文化风格：水墨、白描、年画、青花瓷、皮影
  - 特殊风格：科技

- **12 个核心场景**：草地、池塘、稻田、星空、森林、厨房、庭院、市场、寺庙、节日、奶奶房间、幼儿园

- **年龄驱动内容系统**（3-12岁）：自动调整页数、词汇和学习目标

- **角色一致性锁定协议 (CCLP 4.0)**：确保多页故事中角色外观一致

- **双语输出**：中文/英文，带准确拼音和声调

- **针对 'banana nano' 优化**：专为 AI 图像生成设计的提示词

### 安装

1. 克隆仓库：
```bash
git clone https://github.com/kart-io/picture-skills.git
```

2. 将技能复制到 Claude Code 技能目录：
```bash
cp -r picture-skills/.claude/skills/picture-book-wizard ~/.claude/skills/
```

3. 技能现已在 Claude Code 中可用。

### 使用方法

基本语法：
```bash
/picture-book-wizard [风格] [场景] [年龄] [页数-可选] [角色-可选]
```

#### 示例

```bash
# 基于年龄生成（推荐）
/picture-book-wizard watercolor meadow 4
/picture-book-wizard clay forest 8 5
/picture-book-wizard nianhua kitchen 10 7 xiaoming

# 带灵魂元素（情感、主题）
/picture-book-wizard watercolor forest 8 yueyue emotion:curious
/picture-book-wizard storybook meadow 5 theme:friendship

# 多角色
/picture-book-wizard watercolor kitchen 6 yueyue with:grandma theme:family

# 帮助命令
/picture-book-wizard help:style warm cozy
/picture-book-wizard help:character age:4 theme:creative
```

### 可用角色

| 角色 | 年龄 | 性格 |
|------|-----|------|
| 悦悦 (Yueyue) | 5岁 | 好奇温柔（默认） |
| 小明 (Xiaoming) | 6岁 | 爱冒险、精力充沛 |
| 乐乐 (Lele) | 3岁 | 开朗天真 |
| 美美 (Meimei) | 4岁 | 富有创意和想象力 |

配角：奶奶、爸爸、妈妈、爷爷、兄弟姐妹
动物伙伴：猫、狗、兔子、小鸡、小鸭等

### 项目结构

```
picture-skills/
├── .claude/skills/picture-book-wizard/
│   ├── SKILL.md              # 技能定义（必需）
│   ├── engine/               # Python 规则引擎
│   ├── scripts/              # 自动化脚本
│   ├── references/           # 参考资料
│   │   ├── config/           # 配置文件
│   │   ├── examples/         # 示例
│   │   └── guides/           # 文档
│   └── assets/               # 静态资源
│       └── templates/        # 输出模板
├── output/                   # 生成内容
│   └── picture-books/
└── scripts/                  # 项目工具
```

### 输出

生成的故事保存至：
```
./output/picture-books/[YYYY-MM]/[风格]-[场景]-[角色]-[页数]-[时间戳].md
```

每个输出包含：
- 双语故事文本（中文/英文）
- 学习重点及汉字
- 优化的 AI 图像生成提示词
- 角色一致性标记

### 配置

详细配置文件位于 `.claude/skills/picture-book-wizard/references/config/`：

| 类别 | 文件 |
|------|------|
| 核心 | characters.md, styles.md, scenes.md, age-system.md |
| CCLP | character-consistency-lock.md, CCLP-FLEXIBILITY.md |
| 高级 | story-soul.md, scene-matching.md, reality-validation.md |

### 规范合规

本项目遵循 [Anthropic Agent Skills 规范](https://agentskills.io/specification)：
- 渐进式披露架构
- 标准目录结构
- 清晰的关注点分离

### 许可证

MIT License

---

## Contributing

Contributions are welcome! Please read the documentation in `references/guides/` before submitting PRs.

## Links

- **Repository**: https://github.com/kart-io/picture-skills
- **Specification**: https://agentskills.io/specification


path: SKILL-en.md
content: ---
name: picture-book-wizard
description: A specialized skill for generating high-quality, consistent children's bilingual picture books using 'banana nano'. Supports 18 visual styles across 4 categories (7 core children's book styles, 5 atmospheric styles, 5 Chinese cultural styles, 1 specialized), 12 scenes (5 nature + 7 cultural), age-driven dynamic content system (ages 3-12), and expanded learning domains (science, math, history, psychology, etc.). Use when the user wants to create picture book stories, prompts, or learning materials.
argument-hint: "[style] [scene] [age] [pages-optional] [character-optional]"
---

# Picture Book Wizard

A professional picture book creation skill that generates bilingual (Chinese/English) educational content with optimized image prompts for the 'banana nano' generator.

## Quick Start

**Usage**: `/picture-book-wizard [style] [scene] [age] [pages-optional] [character-optional] [soul-optional]`

**Complete Story System**:
- **Skeleton**: Style, Scene, Age, Pages, Character (required)
- **Soul**: Emotion, Theme, Narrative, Pacing, Color (optional, auto-selected if not specified)

**Age-Driven System** (Recommended):
- **Age**: Target reader age (3-12 years)
- **Pages**: Auto-calculated based on age (can be overridden)
- **Character**: Auto-adapted or dynamically generated based on age

### Available Styles (18 total)

**I. Core Children's Book Styles** (Highly Recommended):
- `storybook`, `watercolor`, `gouache`, `crayon`, `colored-pencil`, `clay`, `paper-cut`

**II. Atmospheric Enhancement Styles** (Use for 10-20% of pages):
- `dreamy`, `fairytale`, `collage`, `fabric`, `felt`

**III. Chinese Cultural Styles**:
- `ink`, `ink-line`, `nianhua`, `porcelain`, `shadow-puppet`

**IV. Specialized**: `tech` (use sparingly)

> **Full details**: `references/config/core/styles.md`

### Available Scenes (12 Core + Extended)

**Core 12 Scenes** (HIGH validation - >90% accuracy):
- **Nature**: `meadow`, `pond`, `rice-paddy`, `stars`, `forest`
- **Cultural & Daily Life**: `kitchen`, `courtyard`, `market`, `temple`, `festival`, `grandma-room`, `kindergarten`

**Extended Scenes**: System supports unlimited scenes through intelligent matching to core scenes.

> **Full details**: `references/config/core/scenes.md`, `references/config/advanced/scene-matching.md`

### Available Characters

**Main Protagonists**:
- `yueyue` - 5yo girl, curious and gentle (Default)
- `xiaoming` - 6yo boy, adventurous and energetic
- `lele` - 3yo boy, cheerful and innocent
- `meimei` - 4yo girl, creative and imaginative

**Supporting Characters**: `grandma`, `dad`, `mom`, `grandpa`, `sibling`
**Animal Companions**: `cat`, `dog`, `rabbit`, `chick`, `duckling`, etc.

> **Full details**: `references/config/core/characters.md`, `references/config/advanced/supporting-characters.md`

### Multi-Character Usage
- **Family**: `with:grandma`, `with:dad`, `with:mom`
- **Animals**: `with:cat`, `with:dog`, `with:rabbit`
- **Multiple**: `with:grandma,cat`

### Soul Elements (Optional)
- **Emotion**: `joyful`, `calm`, `curious`, `brave`, `warm`, `wonder`, `reflective`
- **Theme**: `growth`, `friendship`, `nature`, `family`, `courage`, `creativity`, `discovery`
- **Narrative**: `journey`, `problem`, `cycle`, `transform`, `quest`
- **Pacing**: `gentle`, `lively`, `building`, `varied`
- **Color**: `warm-bright`, `fresh`, `dreamy`, `vibrant`, `serene`

> **Full details**: `references/config/advanced/story-soul.md`

### Examples
```bash
# Age-Based Generation (Recommended)
/picture-book-wizard watercolor meadow 4
/picture-book-wizard clay forest 8 5
/picture-book-wizard nianhua kitchen 10 7 xiaoming

# With Soul Elements
/picture-book-wizard watercolor forest 8 yueyue emotion:curious
/picture-book-wizard storybook meadow 5 theme:friendship

# With Multi-Character
/picture-book-wizard watercolor kitchen 6 yueyue with:grandma theme:family

# Helper Commands
/picture-book-wizard help:style warm cozy
/picture-book-wizard help:character age:4 theme:creative
```

---

## Process Workflow

### Step 0: Content Safety Validation (MANDATORY)

**CRITICAL**: This check runs BEFORE any content generation.

1. **Input Validation**: Verify style, character, age are in allowed lists
2. **Forbidden Content**: Reject violence, horror, adult, political, commercial content
3. **Age-Theme Check**: Ensure theme appropriate for age group

> **Full rules**: `references/config/core/content-safety-validation.md`

### Step 0.5: Pre-Generation Helpers (Optional)

**Style Assistant** (`help:style [mood]`): Get style recommendations based on desired feeling
**Character Advisor** (`help:character [context]`): Get character recommendations based on story context
**Character Type Detection**: Auto-detects animal vs human character requests

> **Full details**: `references/config/core/style-assistant.md`, `references/config/core/character-advisor.md`

### Step 1: Parameter Validation

Validate style, scene, and age/pages parameters. If missing, ask user to specify.

**Age-Driven Auto-Calculation**:
- Ages 3-4: 1-3 pages, basic cognition
- Ages 5-6: 3-5 pages, basic science + social skills
- Ages 7-8: 5-7 pages, science + math + history
- Ages 9-10: 7-10 pages, advanced science + psychology
- Ages 11-12: 10-15 pages, interdisciplinary learning

> **Full specifications**: `references/config/core/age-system.md`

### Step 2: Character Consistency (CCLP 4.0)

Apply **Character Consistency Lock Protocol v4.0** for multi-page stories.

**Three Flexibility Levels**:
1. **STRICT** (Default): 100% identical appearance across all pages
2. **MODERATE**: Fixed face/hair/body, scene-adaptive clothing with narrative justification
3. **FLEXIBLE**: Signature features only, time/theme-adaptive changes

**Core Requirements**:
- **MANDATORY SIGNATURE markers** on key features
- **LOCK ESTABLISHED** statement on Page 1
- **CONSISTENCY REFERENCE** statement on subsequent pages
- **Watermark Prevention Level 2 (35 words)** at prompt end
- **Prompt compression**: 280-300 words total

> **Full protocol**: `references/config/cclp/character-consistency-lock.md`, `references/config/cclp/CCLP-FLEXIBILITY.md`

### Step 3: Content Generation

#### For Single Page
Generate four components:
1. **Story Text**: Bilingual (Chinese first, English), age-appropriate
2. **Learning Focus**: Chinese character + learning domain for age
3. **Image Prompt**: Character anchor + scene + style + rendering + watermark prevention
4. **Formatted Output**: Standard template

#### For Multi-Page Stories
1. **Cover Page**: Character showcase, title space, inviting atmosphere
2. **Story Arc**: 3-page (B-M-E), 5-page (full arc), 7-page (extended journey)
3. **Narrative Continuity**: Character consistency, story flow, learning progression
4. **Story Summary**: Characters learned, theme, extension activities

> **Story patterns**: `references/config/core/story-flow.md`
> **Output format**: `assets/templates/output-format.md`

### Step 4: Pre-Output Validation

**Reality Validation** (for discovery/science themes):
- Cross-check scene Observable Elements
- Verify biological/physical accuracy
- Scan for common error patterns

> **Validation rules**: `references/config/advanced/reality-validation.md`

### Step 5: File Output

Save to: `./output/picture-books/[YYYY-MM]/[style]-[scene]-[character]-[pages]-[timestamp].md`

---

## Image Prompt Assembly

### Solo Character Format
```
[Style] children's picture book illustration,
[Character Anchor with expression],
[Action/Pose],
[Scene Elements],
[Style Keywords],
[Rendering Parameters],
[Watermark Prevention Level 2]
```

### Multi-Character Format
```
[Primary Character Anchor - 150 words],
[Primary Action + Interaction],
[Secondary Character - 40-50 words],
[Relationship Description],
[Scene + Style + Rendering],
[Watermark Prevention Level 2]
```

**CRITICAL Multi-Character Rule**: NEVER use generic descriptions ("family members", "Dad's silhouette"). Each visible character MUST have detailed visual anchor.

> **Supporting character anchors**: `references/config/advanced/supporting-characters.md`
> **Multi-character fix guide**: `references/guides/MULTI-CHARACTER-PROMPT-FIX.md`

### Watermark Prevention (MANDATORY)

**Level 2 (35 words - Default for multi-page)**:
```
clean professional children's book illustration, publication-ready quality, pristine unmarked image, full bleed composition, no watermark, no text overlays, no signatures, no artist marks, no logos, no branding, no copyright symbols, no website URLs, clean professional image
```

**Placement**: MUST be LAST in prompt.

> **Troubleshooting**: `references/guides/WATERMARK-TROUBLESHOOTING.md`

---

## Character Anchors (Quick Reference)

**Yueyue** (5yo):
- Signature: **bright red satin ribbon pigtails**, **sunshine yellow knit sweater**, **denim overalls**
- Build: chubby preschooler, 105-110cm

**Xiaoming** (6yo):
- Signature: **short black hair with left side part**, **royal blue cotton t-shirt**, **tan khaki shorts**
- Build: average 6yo boy, 115-118cm

**Meimei** (4yo):
- Signature: **rainbow pattern hairclip ponytail**, **pastel pink daisy dress**, **white strappy sandals**
- Build: slender 4yo, 100-102cm

**Lele** (3yo):
- Signature: **short fluffy black hair**, **red-white striped t-shirt**, **royal blue elastic pants**
- Build: very chubby toddler, 90-95cm

> **Full anchors**: `references/config/core/characters.md`

---

## Quality Checklist

**Content Quality**:
- [ ] Age-appropriate language
- [ ] Accurate pinyin with tone marks
- [ ] Learning objectives match age
- [ ] Natural bilingual translations

**Technical Quality**:
- [ ] Character anchor included
- [ ] Style keywords present
- [ ] Rendering parameters complete
- [ ] **Watermark directive included** (CRITICAL)

**CCLP Quality (Multi-Page)**:
- [ ] MANDATORY SIGNATURE markers on key features
- [ ] LOCK ESTABLISHED / CONSISTENCY REFERENCE statements
- [ ] CRITICAL CONSISTENCY ENFORCEMENT command
- [ ] Character appearance IDENTICAL across pages
- [ ] Only expression and pose change (STRICT mode)
- [ ] Watermark Level 2 (35w) at end
- [ ] Total prompt 280-300 words

---

## Configuration Reference

### Core Configuration
| File | Description |
|------|-------------|
| `references/config/core/characters.md` | 4 main protagonists + selection guidelines |
| `references/config/core/styles.md` | 18 visual styles across 4 categories |
| `references/config/core/scenes.md` | 12 scenes with Observable Elements |
| `references/config/core/age-system.md` | Age-driven content specifications |
| `references/config/core/rendering.md` | Technical rendering + watermark system |

### Character Consistency
| File | Description |
|------|-------------|
| `references/config/cclp/character-consistency-lock.md` | CCLP 4.0 protocol |
| `references/config/cclp/CCLP-FLEXIBILITY.md` | Three-tier flexibility system |
| `references/config/advanced/supporting-characters.md` | Family/animal character anchors |
| `references/config/advanced/relationship-dynamics.md` | Multi-character patterns |

### Story Creation
| File | Description |
|------|-------------|
| `references/config/advanced/story-soul.md` | Emotion, Theme, Narrative, Pacing, Color |
| `references/config/core/story-flow.md` | Multi-page story patterns + cover design |
| `references/config/advanced/scene-matching.md` | Extended scene intelligent matching |
| `references/config/advanced/reality-validation.md` | Scientific accuracy validation |

### Safety & Helpers
| File | Description |
|------|-------------|
| `references/config/core/content-safety-validation.md` | Forbidden content rules |
| `references/config/core/style-assistant.md` | Style recommendation system |
| `references/config/core/character-advisor.md` | Character recommendation system |

### Animals
| File | Description |
|------|-------------|
| `references/config/animals/animal-characters.md` | Animal character system |
| `references/config/animals/animal-cclp.md` | Animal CCLP rules |

### Templates & Examples
| File | Description |
|------|-------------|
| `assets/templates/output-format.md` | Output structure + file specifications |
| `references/examples/` | Working demonstrations by style/scene |

### Guides
| File | Description |
|------|-------------|
| `references/guides/design.md` | Architecture documentation |
| `references/guides/extending.md` | Extension guide |
| `references/guides/WATERMARK-TROUBLESHOOTING.md` | Watermark fix strategies |
| `references/guides/MULTI-CHARACTER-PROMPT-FIX.md` | Multi-character fix guide |

---

## Key Principles

1. **Educational Focus**: Every page serves a clear learning objective
2. **Character Consistency**: Signature features are non-negotiable
3. **Prompt Optimization**: 150-250 words, all VCP anchors included
4. **Cultural Authenticity**: Accurate Chinese characters and context
5. **No Watermarks**: ALWAYS include watermark prevention directive

---

*For detailed specifications, consult the referenced configuration files.*


path: SKILL-zh.md
content: ---
name: picture-book-wizard
description: 专业的儿童双语绘本创作技能，使用 'banana nano' 生成高质量、风格一致的绘本。支持18种视觉风格（7种核心儿童绘本风格、5种氛围风格、5种中国文化风格、1种专业风格），12种场景（5种自然场景 + 7种文化场景），年龄驱动的动态内容系统（3-12岁），以及扩展学习领域（科学、数学、历史、心理学等）。适用于创建绘本故事、提示词或学习材料。
argument-hint: "[风格] [场景] [年龄] [页数-可选] [角色-可选]"
---

# 绘本魔法师

专业的绘本创作技能，生成中英双语教育内容，并为 'banana nano' 生成器优化图像提示词。

## 快速开始

**用法**: `/picture-book-wizard [风格] [场景] [年龄] [页数-可选] [角色-可选] [灵魂-可选]`

**完整故事系统**:
- 🦴 **骨架**: 风格、场景、年龄、页数、角色（必需）
- ❤️ **灵魂**: 情感、主题、叙事、节奏、色彩（可选，未指定时自动选择）

**年龄驱动系统**（推荐）:
- **年龄**: 目标读者年龄（3-12岁）
- **页数**: 根据年龄自动计算（可覆盖）
- **角色**: 根据年龄自动适配或动态生成

### 可用风格（共18种）

**一、核心儿童绘本风格**（⭐⭐⭐ 强烈推荐）：
- `storybook`（故事书）、`watercolor`（水彩）、`gouache`（水粉）、`crayon`（蜡笔）、`colored-pencil`（彩铅）、`clay`（粘土）、`paper-cut`（剪纸）

**二、氛围增强风格**（建议用于10-20%的页面）：
- `dreamy`（梦幻）、`fairytale`（童话）、`collage`（拼贴）、`fabric`（布艺）、`felt`（毛毡）

**三、中国文化风格**：
- `ink`（水墨）、`ink-line`（白描）、`nianhua`（年画）、`porcelain`（青花）、`shadow-puppet`（皮影）

**四、专业风格**: `tech`（科技）（⚠️ 谨慎使用）

> **完整详情**: `references/config/core/styles.md`

### 可用场景（12个核心 + 扩展）

**核心12场景**（高验证率 - >90% 准确度）：
- **自然场景**: `meadow`（草地）、`pond`（池塘）、`rice-paddy`（稻田）、`stars`（星空）、`forest`（森林）
- **文化与日常生活**: `kitchen`（厨房）、`courtyard`（庭院）、`market`（集市）、`temple`（寺庙）、`festival`（节日）、`grandma-room`（奶奶房间）、`kindergarten`（幼儿园）

**扩展场景**: 系统通过智能匹配支持无限场景扩展至核心场景。

> **完整详情**: `references/config/core/scenes.md`, `references/config/advanced/scene-matching.md`

### 可用角色

**主角**:
- `yueyue`（悦悦）- 5岁女孩，好奇温柔（默认）
- `xiaoming`（小明）- 6岁男孩，爱冒险有活力
- `lele`（乐乐）- 3岁男孩，开朗天真
- `meimei`（美美）- 4岁女孩，有创意爱想象

**配角**: `grandma`（奶奶）、`dad`（爸爸）、`mom`（妈妈）、`grandpa`（爷爷）、`sibling`（兄弟姐妹）
**动物伙伴**: `cat`（猫）、`dog`（狗）、`rabbit`（兔子）、`chick`（小鸡）、`duckling`（小鸭）等

> **完整详情**: `references/config/core/characters.md`, `references/config/advanced/supporting-characters.md`

### 多角色用法
- **家人**: `with:grandma`, `with:dad`, `with:mom`
- **动物**: `with:cat`, `with:dog`, `with:rabbit`
- **多个**: `with:grandma,cat`

### 灵魂元素（可选）
- **情感**: `joyful`（欢乐）、`calm`（平静）、`curious`（好奇）、`brave`（勇敢）、`warm`（温暖）、`wonder`（惊奇）、`reflective`（沉思）
- **主题**: `growth`（成长）、`friendship`（友谊）、`nature`（自然）、`family`（家庭）、`courage`（勇气）、`creativity`（创造力）、`discovery`（发现）
- **叙事**: `journey`（旅程）、`problem`（问题解决）、`cycle`（循环）、`transform`（转变）、`quest`（探索）
- **节奏**: `gentle`（轻柔）、`lively`（活泼）、`building`（渐进）、`varied`（变化）
- **色彩**: `warm-bright`（暖亮）、`fresh`（清新）、`dreamy`（梦幻）、`vibrant`（鲜艳）、`serene`（宁静）

> **完整详情**: `references/config/advanced/story-soul.md`

### 示例
```bash
# 基于年龄生成（推荐）
/picture-book-wizard watercolor meadow 4
/picture-book-wizard clay forest 8 5
/picture-book-wizard nianhua kitchen 10 7 xiaoming

# 带灵魂元素
/picture-book-wizard watercolor forest 8 yueyue emotion:curious
/picture-book-wizard storybook meadow 5 theme:friendship

# 带多角色
/picture-book-wizard watercolor kitchen 6 yueyue with:grandma theme:family

# 辅助命令
/picture-book-wizard help:style warm cozy
/picture-book-wizard help:character age:4 theme:creative
```

---

## 处理流程

### 步骤0: 内容安全验证（必须）

**关键**: 此检查在任何内容生成之前运行。

1. **输入验证**: 验证风格、角色、年龄是否在允许列表中
2. **禁止内容**: 拒绝暴力、恐怖、成人、政治、商业内容
3. **年龄-主题检查**: 确保主题适合年龄组

> **完整规则**: `references/config/core/content-safety-validation.md`

### 步骤0.5: 生成前辅助（可选）

**风格助手** (`help:style [氛围]`): 根据期望的感觉获取风格推荐
**角色顾问** (`help:character [上下文]`): 根据故事上下文获取角色推荐
**角色类型检测**: 自动检测动物vs人类角色请求

> **完整详情**: `references/config/core/style-assistant.md`, `references/config/core/character-advisor.md`

### 步骤1: 参数验证

验证风格、场景和年龄/页数参数。如果缺失，请求用户指定。

**年龄驱动自动计算**:
- 3-4岁: 1-3页，基础认知
- 5-6岁: 3-5页，基础科学 + 社交技能
- 7-8岁: 5-7页，科学 + 数学 + 历史
- 9-10岁: 7-10页，高级科学 + 心理学
- 11-12岁: 10-15页，跨学科学习

> **完整规格**: `references/config/core/age-system.md`

### 步骤2: 角色一致性（CCLP 4.0）

为多页故事应用**角色一致性锁定协议 v4.0**。

**三级灵活度**:
1. **严格模式**（默认）: 所有页面外观100%一致
2. **适度模式**: 固定脸部/头发/体型，场景自适应服装需叙事理由
3. **灵活模式**: 仅标志性特征，时间/主题自适应变化

**核心要求**:
- 关键特征上的**必须标志**标记
- 第1页的**锁定建立**声明
- 后续页面的**一致性参考**声明
- 提示词末尾的**水印预防等级2（35词）**
- **提示词压缩**: 总计280-300词

> **完整协议**: `references/config/cclp/character-consistency-lock.md`, `references/config/cclp/CCLP-FLEXIBILITY.md`

### 步骤3: 内容生成

#### 单页
生成四个组件:
1. **故事文本**: 双语（中文优先，英文），适龄
2. **学习重点**: 汉字 + 适龄学习领域
3. **图像提示词**: 角色锚点 + 场景 + 风格 + 渲染 + 水印预防
4. **格式化输出**: 标准模板

#### 多页故事
1. **封面页**: 角色展示，标题空间，吸引人的氛围
2. **故事弧**: 3页（开始-中间-结尾），5页（完整弧），7页（扩展旅程）
3. **叙事连贯性**: 角色一致性，故事流畅，学习进阶
4. **故事总结**: 学习的汉字，主题，延伸活动

> **故事模式**: `references/config/core/story-flow.md`
> **输出格式**: `assets/templates/output-format.md`

### 步骤4: 输出前验证

**现实验证**（用于发现/科学主题）:
- 交叉检查场景可观察元素
- 验证生物/物理准确性
- 扫描常见错误模式

> **验证规则**: `references/config/advanced/reality-validation.md`

### 步骤5: 文件输出

保存至: `./output/picture-books/[YYYY-MM]/[风格]-[场景]-[角色]-[页数]-[时间戳].md`

---

## 图像提示词组装

### 单角色格式
```
[风格] 儿童绘本插画,
[角色锚点带表情],
[动作/姿势],
[场景元素],
[风格关键词],
[渲染参数],
[水印预防等级2]
```

### 多角色格式
```
[主角色锚点 - 150词],
[主角色动作 + 互动],
[次要角色 - 40-50词],
[关系描述],
[场景 + 风格 + 渲染],
[水印预防等级2]
```

**关键多角色规则**: 永远不要使用通用描述（"家人"、"爸爸的剪影"）。每个可见角色必须有详细的视觉锚点。

> **配角锚点**: `references/config/advanced/supporting-characters.md`
> **多角色修复指南**: `references/guides/MULTI-CHARACTER-PROMPT-FIX.md`

### 水印预防（必须）

**等级2（35词 - 多页默认）**:
```
clean professional children's book illustration, publication-ready quality, pristine unmarked image, full bleed composition, no watermark, no text overlays, no signatures, no artist marks, no logos, no branding, no copyright symbols, no website URLs, clean professional image
```

**位置**: 必须放在提示词最后。

> **故障排除**: `references/guides/WATERMARK-TROUBLESHOOTING.md`

---

## 角色锚点（快速参考）

**悦悦**（5岁）:
- 标志: **鲜红缎带双马尾**、**阳光黄针织毛衣**、**牛仔背带裤**
- 体型: 胖嘟嘟的学龄前儿童，105-110cm

**小明**（6岁）:
- 标志: **左偏分短黑发**、**宝蓝色棉质T恤**、**卡其色短裤**
- 体型: 普通6岁男孩，115-118cm

**美美**（4岁）:
- 标志: **彩虹图案发卡马尾**、**粉色雏菊连衣裙**、**白色凉鞋**
- 体型: 纤细的4岁女孩，100-102cm

**乐乐**（3岁）:
- 标志: **蓬松短黑发**、**红白条纹T恤**、**宝蓝色松紧裤**
- 体型: 非常胖的幼儿，90-95cm

> **完整锚点**: `references/config/core/characters.md`

---

## 质量检查清单

**内容质量**:
- [ ] 适龄语言
- [ ] 准确的拼音带声调标记
- [ ] 学习目标匹配年龄
- [ ] 自然的双语翻译

**技术质量**:
- [ ] 包含角色锚点
- [ ] 包含风格关键词
- [ ] 渲染参数完整
- [ ] **包含水印指令**（关键）

**CCLP质量（多页）**:
- [ ] 关键特征上的必须标志标记
- [ ] 锁定建立 / 一致性参考声明
- [ ] 关键一致性强制命令
- [ ] 角色外观跨页面一致
- [ ] 仅表情和姿势变化（严格模式）
- [ ] 水印等级2（35词）在末尾
- [ ] 总提示词280-300词

---

## 配置参考

### 核心配置
| 文件 | 描述 |
|------|------|
| `references/config/core/characters.md` | 4个主角 + 选择指南 |
| `references/config/core/styles.md` | 18种视觉风格，4个类别 |
| `references/config/core/scenes.md` | 12个场景及可观察元素 |
| `references/config/core/age-system.md` | 年龄驱动内容规格 |
| `references/config/core/rendering.md` | 技术渲染 + 水印系统 |

### 角色一致性
| 文件 | 描述 |
|------|------|
| `references/config/cclp/character-consistency-lock.md` | CCLP 4.0 协议 |
| `references/config/cclp/CCLP-FLEXIBILITY.md` | 三级灵活度系统 |
| `references/config/advanced/supporting-characters.md` | 家人/动物角色锚点 |
| `references/config/advanced/relationship-dynamics.md` | 多角色模式 |

### 故事创作
| 文件 | 描述 |
|------|------|
| `references/config/advanced/story-soul.md` | 情感、主题、叙事、节奏、色彩 |
| `references/config/core/story-flow.md` | 多页故事模式 + 封面设计 |
| `references/config/advanced/scene-matching.md` | 扩展场景智能匹配 |
| `references/config/advanced/reality-validation.md` | 科学准确性验证 |

### 安全与辅助
| 文件 | 描述 |
|------|------|
| `references/config/core/content-safety-validation.md` | 禁止内容规则 |
| `references/config/core/style-assistant.md` | 风格推荐系统 |
| `references/config/core/character-advisor.md` | 角色推荐系统 |

### 动物
| 文件 | 描述 |
|------|------|
| `references/config/animals/animal-characters.md` | 动物角色系统 |
| `references/config/animals/animal-cclp.md` | 动物CCLP规则 |

### 模板与示例
| 文件 | 描述 |
|------|------|
| `assets/templates/output-format.md` | 输出结构 + 文件规格 |
| `references/examples/` | 按风格/场景的工作示范 |

### 指南
| 文件 | 描述 |
|------|------|
| `references/guides/design.md` | 架构文档 |
| `references/guides/extending.md` | 扩展指南 |
| `references/guides/WATERMARK-TROUBLESHOOTING.md` | 水印修复策略 |
| `references/guides/MULTI-CHARACTER-PROMPT-FIX.md` | 多角色修复指南 |

---

## 核心原则

1. **教育为本**: 每页都服务于明确的学习目标
2. **角色一致**: 标志性特征不可妥协
3. **提示优化**: 150-250词，包含所有VCP锚点
4. **文化真实**: 准确的汉字和文化语境
5. **无水印**: 始终包含水印预防指令

---

*详细规格请参阅引用的配置文件。*


path: SKILLSTORE.md
content: # picture-book-wizard

A specialized skill for generating high-quality, consistent children's bilingual picture books using 'banana nano'. Supports 18 visual styles across 4 categories (7 core children's book styles, 5 atmospheric styles, 5 Chinese cultural styles, 1 specialized), 12 scenes (5 nature + 7 cultural), age-driven dynamic content system (ages 3-12), and expanded learning domains (science, math, history, psychology, etc.). Use when the user wants to create picture book stories, prompts, or learning materials.

---

## 📦 Downloaded from [Skillstore.io](https://skillstore.io)

This skill was downloaded from **AI Skillstore** — the official marketplace for Claude Code, Codex, and Claude skills.

🔗 **Skill Page**: [skillstore.io/skills/kart-io-picture-book-wizard](https://skillstore.io/skills/kart-io-picture-book-wizard)

## 🚀 Installation

Copy the contents of this folder to your project's `.claude/skills/` directory.

## 📋 Skill Info

| Property | Value |
|----------|-------|
| **Name** | picture-book-wizard |
| **Version** | 1.0.0 |
| **Author** | kart-io |

### Supported Tools

- claude
- codex
- claude-code

## 🌐 Discover More Skills

Browse thousands of AI skills at **[skillstore.io](https://skillstore.io)**:

- 🔍 Search by category, tool, or keyword
- ⭐ Find verified, security-audited skills
- 📤 Submit your own skills to share with the community

---

*From [skillstore.io](https://skillstore.io) — AI Skills Marketplace*


path: assets/templates/output-format.md
content: # Output Format Template

## Standard Output Structure

Every picture book page must follow this consistent format:

```markdown
📖 **故事 / Story:**
[Chinese text here]
[English translation here]

---

🔤 **拼音 / Pinyin:**
[Pinyin annotation of Chinese text]

---

✨ **学习要点 / Learning Point:**
[Character] ([pinyin]) - [English meaning]

---

🎨 **Banana Nano Prompt:**
[Complete VCP-locked image generation prompt]

---
```

## Section Details

### 1. 📖 Story Section (故事 / Story)

**Purpose**: Present the bilingual narrative content

**Requirements**:
- Chinese text comes first (on its own line)
- English translation follows (on its own line)
- Keep sentences simple and child-appropriate
- Use repetitive language patterns
- Age target: 3-6 years old

**Guidelines**:
- Sentence length: 5-12 words per language
- Vocabulary: Basic, everyday words
- Structure: Subject-Verb-Object preferred
- Tone: Warm, engaging, wonder-filled

**Example**:
```
悦悦在草地上发现了一颗小种子。
Yueyue found a tiny seed on the meadow.
```

---

### 2. 🔤 Pinyin Section (拼音)

**Purpose**: Provide pronunciation guide for Chinese learners

**Requirements**:
- Include tone marks (ā, á, ǎ, à)
- Match exactly with the Chinese text above
- Use proper spacing between words/phrases
- Follow standard pinyin romanization rules

**Guidelines**:
- Proper names: Capitalize (Yuèyuè)
- Standard words: Lowercase
- Word grouping: Follow meaning clusters
- Punctuation: Match Chinese text

**Example**:
```
Yuèyuè zài cǎodì shàng fāxiànle yī kē xiǎo zhǒngzi.
```

---

### 3. ✨ Learning Point Section (学习要点)

**Purpose**: Highlight a key Chinese character for educational focus

**Requirements**:
- Select ONE character most relevant to the scene/story
- Provide the character, pinyin, and English meaning
- Choose characters appropriate for early learners
- Optionally include additional learning objectives (logic, objects, social)

**Standard Format**:
```
[字] ([pinyin]) - [English meaning]
```

**Extended Format** (with additional objectives):
```
汉字 (Character): [字] ([pinyin]) - [English meaning]
逻辑 (Logic): [logical concept or reasoning]
```

Or:
```
汉字 (Character): [字] ([pinyin]) - [English meaning]
物品 (Object): [object name and usage description]
```

**Character Selection Priority**:
1. Nouns related to scene (grass, water, star, tree)
2. Verbs related to action (find, see, walk)
3. Adjectives describing environment (big, small, green)
4. Basic characters suitable for young learners (HSK 1-2 level)

**Additional Learning Objectives** (Optional - see `config/learning-objectives.md`):
- Logic (逻辑): Cause-effect, sequence, problem-solving
- Objects (物品): Tools, utensils, traditional items and their usage
- Social (社交): Sharing, helping, cooperation
- Emotional (情感): Feelings, empathy
- Safety (安全): Rules, hygiene, health
- Science (科学): Nature, growth, observation

**Example (Standard)**:
```
草 (cǎo) - grass
```

**Example (Extended with Logic)**:
```
汉字 (Character): 长 (zhǎng) - grow
逻辑 (Logic): 种子 + 水 + 阳光 → 生长 (seed + water + sun → growth)
```

**Example (Extended with Object)**:
```
汉字 (Character): 筷 (kuài) - chopsticks
物品 (Object): 筷子是中国传统餐具，用来夹食物 (Chopsticks are traditional Chinese utensils used to pick up food)
```

---

### 4. 🎨 Banana Nano Prompt Section

**Purpose**: Provide complete, VCP-locked image generation prompt

**Requirements**:
- Must include Character Anchor
- Must include Scene-specific details
- Must include Style keywords
- Must include Rendering parameters
- Length: 150-250 words optimal

**Structure**:
```
[Character Anchor], [action/pose], [scene environment elements], [scene-specific details], [style keywords], [rendering parameters], [atmospheric effects].
```

**Components Checklist**:
- [ ] Character description (Yueyue's appearance)
- [ ] Character pose/action
- [ ] Scene environment (meadow, pond, etc.)
- [ ] Scene-specific visual details
- [ ] Style keywords (clay/tech/ink)
- [ ] Rendering anchor (octane render, 8k, etc.)
- [ ] Atmospheric description

**Example**:
```
A 5-year-old Chinese girl named Yueyue, round face, rosy cheeks, two pigtails with red ribbons, wearing yellow sweater and denim overalls, kneeling on lush green grass meadow, discovering a tiny seed, hand-sculpted claymation style, physical clay textures, tiny hand-pressed wildflowers scattered around, soft studio lighting, octane render, macro texture details, 8k resolution, warm and inviting atmosphere.
```

---

## Complete Example Output

### Clay Style Meadow Scene

```markdown
📖 **故事 / Story:**
悦悦在草地上发现了一颗小种子。
Yueyue found a tiny seed on the meadow.

---

🔤 **拼音 / Pinyin:**
Yuèyuè zài cǎodì shàng fāxiànle yī kē xiǎo zhǒngzi.

---

✨ **学习要点 / Learning Point:**
草 (cǎo) - grass

---

🎨 **Banana Nano Prompt:**
A 5-year-old Chinese girl named Yueyue, round face, rosy cheeks, two pigtails with red ribbons, wearing yellow sweater and denim overalls, kneeling on lush green grass meadow, discovering a tiny seed, hand-sculpted claymation style, physical clay textures, tiny hand-pressed wildflowers scattered around, soft studio lighting, octane render, macro texture details, 8k resolution, warm and inviting atmosphere.

---
```

---

## Optional Sections

### Story Summary (故事总结) - For Multi-Page Stories

**When to Include**: REQUIRED for all multi-page stories (3, 5, or 7 pages)

**Purpose**: Provide a comprehensive summary of the complete story arc, learning outcomes, and thematic takeaway

**Format**:
```markdown
## 📚 故事总结 / Story Summary

### 完整故事 / Complete Story
[2-3 sentence summary of the full narrative arc in Chinese]
[2-3 sentence summary in English]

### 学习成果 / Learning Outcomes
**汉字学习 (Characters Learned)**:
- Page 1: [字] ([pinyin]) - [meaning]
- Page 2: [字] ([pinyin]) - [meaning]
- Page 3: [字] ([pinyin]) - [meaning]
[Continue for all pages]

**主题 (Theme)**: [Main theme of the story, e.g., "Growth and patience" / "成长与耐心"]

**核心价值 (Core Value)**: [Key lesson or value, e.g., "Taking care of nature" / "爱护自然"]

### 延伸活动建议 / Extension Activities
1. [Activity suggestion 1 - hands-on or discussion]
2. [Activity suggestion 2 - creative or observational]
3. [Activity suggestion 3 - family or group activity]

### 适合年龄 / Age Suitability
**推荐年龄 (Recommended Age)**: [e.g., 4-6岁 / 4-6 years old]
**角色 (Character)**: [Character name and why suitable]
**学习重点 (Learning Focus)**: [Primary learning objective achieved]
```

**Example Summary (3-Page Seed Growth Story)**:
```markdown
## 📚 故事总结 / Story Summary

### 完整故事 / Complete Story
悦悦在草地上发现了一颗小种子，她小心地把种子种在土里，每天浇水照顾。经过耐心等待，种子发芽长大，开出了美丽的小花。
Yueyue found a tiny seed on the meadow, carefully planted it in the soil, and watered it every day. After patient waiting, the seed sprouted and grew into a beautiful little flower.

### 学习成果 / Learning Outcomes
**汉字学习 (Characters Learned)**:
- Page 1: 草 (cǎo) - grass
- Page 2: 种 (zhòng) - plant/grow
- Page 3: 花 (huā) - flower

**主题 (Theme)**: Growth and patience / 成长与耐心

**核心价值 (Core Value)**: Taking care of living things requires patience and consistent care / 照顾生命需要耐心和持续关爱

### 延伸活动建议 / Extension Activities
1. **种植活动**: 和孩子一起种一颗豆子或花种，每天观察记录 (Planting Activity: Plant a bean or flower seed together, observe and record daily)
2. **成长日记**: 画出种子到花朵的成长过程 (Growth Journal: Draw the growth process from seed to flower)
3. **户外探索**: 去公园寻找不同的种子和花朵 (Outdoor Exploration: Go to a park to find different seeds and flowers)

### 适合年龄 / Age Suitability
**推荐年龄 (Recommended Age)**: 4-6岁 / 4-6 years old
**角色 (Character)**: 悦悦 (Yueyue) - 温柔耐心的性格适合照顾植物的故事
**学习重点 (Learning Focus)**: 植物生长过程、耐心品质、自然观察 (Plant growth process, patience, nature observation)
```

---

### Additional Learning Points (Optional)

When appropriate, you may add:

**Related Vocabulary** (相关词汇):
```
- [Character 1] ([pinyin]) - [meaning]
- [Character 2] ([pinyin]) - [meaning]
```

**Cultural Note** (文化注释):
```
[Brief cultural context or interesting fact]
```

**Extension Activity** (延伸活动) - Single Page:
```
[Simple activity suggestion for parents/teachers]
```

---

## Quality Standards

### Story Quality Checklist
- [ ] Age-appropriate language (3-6 years)
- [ ] Culturally authentic
- [ ] Grammatically correct in both languages
- [ ] Natural-sounding translations (not word-for-word)
- [ ] Engaging and wonder-filled tone

### Technical Quality Checklist
- [ ] Pinyin includes all tone marks
- [ ] Learning point character appears in the story
- [ ] Prompt includes all VCP components
- [ ] Formatting follows template exactly
- [ ] Emojis used for section headers

### Educational Quality Checklist
- [ ] Clear learning objective
- [ ] Character appropriate for learner level
- [ ] Repetition supports learning
- [ ] Visual-text alignment strong
- [ ] Cultural authenticity maintained

### Educational Content Reality Validation (🆕 Critical for Quality Control)

**Purpose**: Ensure educational content is scientifically accurate and doesn't teach incorrect information to children.

**Validation Required When**:
- Age 7+ with discovery/science themes
- Any age with science learning domains
- Nature scenes (meadow, pond, forest, stars, rice-paddy)
- Multi-page stories with educational continuity

#### Reality Validation Checklist by Age Group

**Ages 3-4 (Early Childhood)**:
- [ ] Observable elements match toddler height/reach (~90-100cm)
- [ ] Objects described are visible at child's eye level
- [ ] No microscopic details without magnification context
- [ ] Cause-effect relationships are simple and direct
- [ ] Fantasy elements clearly in imaginative play context (not taught as fact)

**Ages 5-6 (Preschool)**:
- [ ] Observable elements match preschool height/reach (~105-115cm)
- [ ] Seasonal elements consistent (spring flowers, autumn leaves, etc.)
- [ ] Simple scientific observations are factually accurate
- [ ] Basic cause-effect follows natural laws (water flows down, objects fall)
- [ ] No teaching of misconceptions as facts (even if simplified)

**Ages 7-8 (Early Elementary) - HIGH PRIORITY**:
- [ ] **MANDATORY** scientific accuracy for discovery/science themes
- [ ] All plant/animal anatomy descriptions are correct
- [ ] Observable vs. non-observable distinction clear (e.g., bark texture ✅, growth rings on living trees ❌)
- [ ] Physics follows real-world rules (gravity, light, motion)
- [ ] Educational objectives teach correct facts, no oversimplifications that mislead

**Ages 9-12 (Late Elementary/Pre-teen) - HIGHEST PRIORITY**:
- [ ] **CRITICAL** scientific rigor required
- [ ] Advanced concepts are factually accurate (cells, ecosystems, physics principles)
- [ ] Terminology is scientifically correct
- [ ] Complex cause-effect relationships follow natural laws
- [ ] No magical thinking presented as science

#### Scene-Specific Reality Validation

**Nature Scenes** (Meadow, Pond, Forest, Stars, Rice Paddy):
- [ ] Cross-referenced scene's Observable Elements section in `references/config/scenes.md`
- [ ] All visual descriptions in ✅ "Visible & Accurate" list
- [ ] NO elements from ❌ "NOT Visible (Common Errors)" list
- [ ] Seasonal consistency maintained
- [ ] Plant/animal behavior realistic

**Cultural Scenes** (Kitchen, Courtyard, Market, Temple, Festival, Grandma-Room, Kindergarten):
- [ ] Cultural practices accurately represented
- [ ] Observable items correctly described (furniture, tools, decorations)
- [ ] Traditional practices shown with respect
- [ ] Modern vs. traditional elements consistent with scene
- [ ] No cultural stereotypes or misconceptions

#### Common Error Patterns to Avoid (Red Flags 🚩)

**Biological Errors**:
- 🚩 ❌ "growth rings visible on living tree bark" → ✅ CORRECT: "rough bark texture with moss"
- 🚩 ❌ "looking at plant roots underground" → ✅ CORRECT: "carefully digs to see roots"
- 🚩 ❌ "seeing inside the flower" → ✅ CORRECT: "counting petals on the flower"
- 🚩 ❌ "flowers blooming in snow" → ✅ CHECK: only winter-blooming species (plum)

**Physical Errors**:
- 🚩 ❌ "objects floating without support" → ✅ CORRECT: "balloon floats up (helium lighter than air)"
- 🚩 ❌ "water flowing uphill" → ✅ CORRECT: "water flows downhill into pond"
- 🚩 ❌ "stars visible in bright daylight" → ✅ CORRECT: "stars appear after sunset"
- 🚩 ❌ "clear reflection in rippling water" → ✅ CORRECT: "reflection distorts in ripples"

**Observational Errors**:
- 🚩 ❌ "seeing microscopic bacteria" → ✅ CORRECT: "washing hands removes germs (invisible)"
- 🚩 ❌ "looking inside solid objects" → ✅ CORRECT: use cut/open context
- 🚩 ❌ "3-year-old reaching high tree branch" → ✅ CORRECT: match height to age (~90cm reach)
- 🚩 ❌ "seeing through thick walls" → ✅ CORRECT: "hearing sounds from inside"

**Common Sense Errors**:
- 🚩 ❌ "wild bear in kitchen" → ✅ CORRECT: "bear in forest"
- 🚩 ❌ "bright sunshine at midnight" → ✅ CORRECT: "moonlight at night"
- 🚩 ❌ "rain falling indoors" → ✅ CORRECT: rain through open window/hole (context)

#### Error Reporting Process

**If Scientific Error Discovered**:
1. **Immediate**: Flag the error and do NOT generate incorrect content
2. **Document**: Note specific error and why it's incorrect
3. **Correct**: Use Observable Elements guidance to find accurate alternative
4. **Regenerate**: Create new prompt with scientifically accurate description
5. **Report** (for continuous improvement): See `reality-validation.md` Section IX for error reporting template

**Example Error Correction Process**:

**Original Error**:
```
Story: "悦悦看见树的年轮在树皮上。"
Prompt: "examining tree trunk with visible circular growth rings on bark"
❌ ERROR: Growth rings NOT visible on bark-covered living trees
```

**Correction Process**:
1. **Identify**: Growth rings only visible on cut wood, not living bark
2. **Reference**: Check `scenes.md` Forest → Observable Elements → "rough bark texture" ✅
3. **Alternative**: Use "bark texture, moss, knots" OR "fallen log with cut end"
4. **Regenerate**:
   - Story: "悦悦触摸树皮，感觉粗糙的纹理。" (Yueyue touches bark, feels rough texture)
   - Prompt: "examining tree trunk with rough ridged bark, green moss patches"
   OR
   - Story: "悦悦看见倒下的树桩上的年轮。" (Yueyue sees growth rings on fallen stump)
   - Prompt: "kneeling beside fallen log, examining circular growth rings on cut end"

**Reference Files**:
- **Validation Rules**: `references/config/reality-validation.md`
- **Scene Observable Elements**: `references/config/scenes.md` (all 12 scenes)
- **Age-Appropriate Guidelines**: `references/config/age-system.md`

---

## Formatting Notes

### Markdown Styling
- Use `---` horizontal rules between sections
- Bold the section headers with `**text**`
- Emojis at start of each section header
- One blank line between sections

### Text Styling
- Chinese and English on separate lines in Story section
- Maintain consistent spacing
- Use proper punctuation for each language
- Keep prompt as single paragraph

### Consistency
- Always use the same emoji for each section
- Keep section order consistent
- Maintain the same header format
- Use identical spacing patterns

---

## Variations by Purpose

### For Digital Display
- Standard format as shown above
- Full color emoji support
- Regular line spacing

### For Print Publication
- Consider replacing emojis with text labels
- Adjust line spacing for print
- May need larger font considerations
- Include page number if part of series

### For Audio Companion
- Story section remains primary
- May abbreviate prompt section
- Emphasize pinyin for pronunciation guide

---

## File Output Specification

### Markdown File Creation

**When to Create**: ALWAYS create a markdown file for generated content

**File Naming Convention**:
```
[style]-[scene]-[character]-[timestamp].md

Examples:
- clay-meadow-yueyue-20260110.md
- nianhua-kitchen-xiaoming-20260110-143522.md
- paper-cut-festival-meimei-3pages-20260110.md
```

**Naming Components**:
- **style**: Style code (clay, tech, ink, paper-cut, nianhua, porcelain, shadow-puppet)
- **scene**: Scene code (meadow, pond, rice-paddy, stars, forest, kitchen, courtyard, market, temple, festival, grandma-room, kindergarten)
- **character**: Character code (yueyue, xiaoming, lele, meimei)
- **pages** (optional): Add "-3pages", "-5pages", or "-7pages" for multi-page stories
- **timestamp**: YYYYMMDD or YYYYMMDD-HHMMSS format

**File Location**:
```
./output/picture-books/[YYYY-MM]/
```

Create monthly subdirectories for organization:
```
./output/picture-books/
  ├── 2026-01/
  │   ├── clay-meadow-yueyue-20260110.md
  │   ├── nianhua-kitchen-xiaoming-20260115.md
  │   └── paper-cut-festival-meimei-3pages-20260120.md
  ├── 2026-02/
  └── ...
```

**File Content Structure**:

```markdown
# [Story Title] / [故事标题]

**Generated**: [Date and Time]
**Style**: [Style name]
**Scene**: [Scene name]
**Character**: [Character name]
**Pages**: [Number]

---

[If single page]
[Full page content with all sections]

[If multi-page]
## Page 1 / 第一页

[Page 1 content]

---

## Page 2 / 第二页

[Page 2 content]

---

[Continue for all pages...]

---

[Story Summary section for multi-page stories]

---

## Generation Info / 生成信息

- **Generator**: Picture Book Wizard (Claude Code Skill)
- **Model**: [Model used]
- **Timestamp**: [ISO timestamp]
- **Configuration**: [style]/[scene]/[character]/[pages]
```

**Example File Header**:
```markdown
# Seed Discovery / 种子的发现

**Generated**: 2026-01-10 14:35:22
**Style**: Clay (粘土风格)
**Scene**: Meadow (草地)
**Character**: Yueyue (悦悦)
**Pages**: 1

---
```

**Example Multi-Page File Header**:
```markdown
# The Seed's Journey / 种子的旅程

**Generated**: 2026-01-10 15:20:00
**Style**: Clay (粘土风格)
**Scene**: Meadow (草地)
**Character**: Yueyue (悦悦)
**Pages**: 3
**Theme**: Growth and Patience / 成长与耐心

---
```

### File Creation Process

1. **Generate Content**: Create all pages and summary first
2. **Assemble File**: Compile content with headers and metadata
3. **Ensure Directory**: Create monthly directory if doesn't exist
4. **Write File**: Save with proper naming convention
5. **Confirm to User**: Show file path and brief summary

**User Notification Format**:
```
✅ Picture book created successfully!

📁 **File**: ./output/picture-books/2026-01/clay-meadow-yueyue-20260110.md
📖 **Title**: Seed Discovery / 种子的发现
🎨 **Style**: Clay
🌿 **Scene**: Meadow
👧 **Character**: Yueyue
📄 **Pages**: 1

Content includes:
- Bilingual story (Chinese/English)
- Pinyin pronunciation guide
- Learning point: 草 (cǎo) - grass
- Banana Nano image prompt
```

**Multi-Page Notification**:
```
✅ Picture book story created successfully!

📁 **File**: ./output/picture-books/2026-01/clay-meadow-yueyue-3pages-20260110.md
📖 **Title**: The Seed's Journey / 种子的旅程
🎨 **Style**: Clay
🌿 **Scene**: Meadow
👧 **Character**: Yueyue
📄 **Pages**: 3
🎯 **Theme**: Growth and Patience

Content includes:
- 3 complete story pages
- Characters learned: 草 (grass), 种 (plant), 花 (flower)
- Story summary with learning outcomes
- Extension activities for parents/teachers
```

---

## Summary

This template provides the complete structure for generating Picture Book Wizard content with:
- Standard bilingual format (Chinese/English/Pinyin)
- Chinese character learning points
- Optional learning objectives (logic, objects, social, etc.)
- Banana Nano optimized prompts
- Story summaries for multi-page content
- Markdown file output with organized storage

All content should follow this template for consistency and quality assurance.


path: engine/__init__.py
content: """
Picture Book Wizard Engine
规则引擎模块
"""

from .config import (
    STYLES,
    SCENES,
    CHARACTERS,
    AGE_SYSTEM,
    WATERMARK_PREVENTION,
    SOUL_ELEMENTS,
    SUPPORTING_CHARACTERS,
    ANIMAL_COMPANIONS,
    STORY_STRUCTURES,
    CCLP_CONFIG,
)

from .rules import (
    # 数据类
    ValidationResult,
    StoryParams,
    CharacterAnchor,
    PageContent,
    PictureBook,
    # 类
    Validator,
    AgeSystem,
    CharacterAnchorGenerator,
    PromptAssembler,
    OutputFormatter,
    PictureBookEngine,
    # 便捷函数
    create_engine,
    quick_validate,
)

__version__ = "1.0.0"
__all__ = [
    # 配置
    "STYLES",
    "SCENES",
    "CHARACTERS",
    "AGE_SYSTEM",
    "WATERMARK_PREVENTION",
    "SOUL_ELEMENTS",
    "SUPPORTING_CHARACTERS",
    "ANIMAL_COMPANIONS",
    "STORY_STRUCTURES",
    "CCLP_CONFIG",
    # 数据类
    "ValidationResult",
    "StoryParams",
    "CharacterAnchor",
    "PageContent",
    "PictureBook",
    # 类
    "Validator",
    "AgeSystem",
    "CharacterAnchorGenerator",
    "PromptAssembler",
    "OutputFormatter",
    "PictureBookEngine",
    # 便捷函数
    "create_engine",
    "quick_validate",
]


path: engine/config.py
content: """
Picture Book Wizard 完整配置数据
将 markdown 规则转换为结构化数据
"""

# ============================================================
# 风格配置 (18 种)
# ============================================================
STYLES = {
    # === I. 核心儿童绘本风格 (7种) ===
    "storybook": {
        "name_cn": "经典绘本",
        "category": "core",
        "keywords": "classic children's storybook illustration, soft rounded shapes, friendly character design, warm inviting colors, clear composition, professional picture book style, gentle lighting, age-appropriate aesthetics",
        "best_for": ["传统故事", "教育内容", "角色叙事"],
        "age_rating": 3,
    },
    "watercolor": {
        "name_cn": "水彩",
        "category": "core",
        "keywords": "soft watercolor illustration, gentle color blending, organic paper texture, delicate brushwork, light and airy, natural color flow, transparent layers, watercolor wash effects",
        "best_for": ["自然场景", "温柔叙事", "情感时刻"],
        "age_rating": 3,
    },
    "gouache": {
        "name_cn": "水粉",
        "category": "core",
        "keywords": "opaque gouache illustration, flat color areas, bold soft colors, clear shapes, matte finish, vibrant controlled palette, painterly texture, clean silhouettes",
        "best_for": ["欢快故事", "文化庆典", "活泼场景"],
        "age_rating": 3,
    },
    "crayon": {
        "name_cn": "蜡笔",
        "category": "core",
        "keywords": "naive crayon illustration, childlike hand-drawn strokes, warm waxy texture, playful imperfect lines, authentic children's drawing style, soft crayon marks, friendly accessible aesthetic",
        "best_for": ["童趣表达", "简单故事", "第一人称叙述"],
        "age_rating": 3,
    },
    "colored-pencil": {
        "name_cn": "彩铅",
        "category": "core",
        "keywords": "gentle colored pencil drawing, soft pencil strokes, delicate color layering, subtle cross-hatching, warm intimate texture, hand-drawn organic quality, fine soft details",
        "best_for": ["安静时刻", "细腻自然", "睡前故事"],
        "age_rating": 4,
    },
    "clay": {
        "name_cn": "黏土",
        "category": "core",
        "keywords": "hand-sculpted claymation style, physical clay textures, fingerprint details visible, matte surface, soft edges, warm color grading, tactile touchable quality, 3D sculpted appearance, soft studio lighting",
        "best_for": ["自然场景", "近距离互动", "温馨故事"],
        "age_rating": 3,
    },
    "paper-cut": {
        "name_cn": "剪纸",
        "category": "core",
        "keywords": "Chinese paper-cut art style, layered paper silhouettes, intricate cut-out patterns, bold red and gold colors, symmetrical design, flat graphic style with depth layers, sharp clean edges, traditional Chinese decorative patterns, shadow layers, folk art aesthetic",
        "best_for": ["节日庆典", "文化教育", "图案学习"],
        "age_rating": 3,
    },

    # === II. 氛围增强风格 (5种) ===
    "dreamy": {
        "name_cn": "梦幻",
        "category": "atmospheric",
        "keywords": "soft dreamy illustration, ethereal lighting, gentle blur effects, pastel color washes, floating weightless elements, magical glow, sparkles and light particles, calm peaceful atmosphere",
        "best_for": ["梦境", "睡前故事", "想象场景"],
        "age_rating": 4,
        "usage_percent": "10-15%",
    },
    "fairytale": {
        "name_cn": "童话",
        "category": "atmospheric",
        "keywords": "whimsical fairytale illustration, magical enchanted elements, soft romantic lighting, decorative storybook borders, traditional fairytale aesthetics, gentle fantasy details, storybook charm",
        "best_for": ["经典童话", "魔法时刻", "特殊场景"],
        "age_rating": 4,
        "usage_percent": "15-20%",
    },
    "collage": {
        "name_cn": "拼贴",
        "category": "atmospheric",
        "keywords": "paper collage illustration, layered textures, mixed media elements, visible paper edges, tactile handmade appearance, crafted overlapping layers, playful composition, artistic cut-outs",
        "best_for": ["创意过程", "艺术主题", "记忆场景"],
        "age_rating": 4,
        "usage_percent": "10-15%",
    },
    "fabric": {
        "name_cn": "布艺",
        "category": "atmospheric",
        "keywords": "textile fabric collage, soft material textures, felt and cotton layers, embroidery stitching details, cozy tactile quality, warm handmade aesthetic, fabric pattern overlays",
        "best_for": ["温馨家庭", "祖孙故事", "舒适环境"],
        "age_rating": 3,
        "usage_percent": "10-20%",
    },
    "felt": {
        "name_cn": "毛毡",
        "category": "atmospheric",
        "keywords": "felt handmade illustration, thick soft felt textures, fuzzy material surface, hand-cut felt shapes, layered dimensional craft, warm cozy aesthetic, playful handmade quality",
        "best_for": ["室内场景", "冬季主题", "安全感叙事"],
        "age_rating": 3,
        "usage_percent": "10-15%",
    },

    # === III. 中国文化风格 (5种) ===
    "ink": {
        "name_cn": "水墨",
        "category": "chinese",
        "keywords": "Chinese ink wash painting for children, gentle flowing brush strokes, soft ink gradients, warm ethereal mist, traditional technique with color accents, watercolor blends, artistic poetic composition",
        "best_for": ["自然意境", "诗意故事", "艺术欣赏"],
        "age_rating": 5,
    },
    "ink-line": {
        "name_cn": "白描",
        "category": "chinese",
        "keywords": "traditional Chinese line art, clean black ink outlines, elegant minimal strokes, white background, simple expressive linework, traditional drawing technique, optional light color fills",
        "best_for": ["书法教育", "简洁构图", "传统艺术"],
        "age_rating": 5,
    },
    "nianhua": {
        "name_cn": "年画",
        "category": "chinese",
        "keywords": "Chinese New Year painting for children, vibrant festive colors, bold outlines, flat color fills, symmetrical joyful composition, auspicious symbols, folk art aesthetic, decorative patterns, celebration atmosphere",
        "best_for": ["春节", "传统节日", "吉祥主题", "文化传承"],
        "age_rating": 3,
    },
    "porcelain": {
        "name_cn": "青花瓷",
        "category": "chinese",
        "keywords": "Chinese blue and white porcelain for children, delicate cobalt blue on white, ceramic glaze texture, soft flowing patterns, traditional motifs simplified, elegant refined aesthetic, child-friendly designs",
        "best_for": ["宁静故事", "文化遗产", "艺术欣赏"],
        "age_rating": 5,
    },
    "shadow-puppet": {
        "name_cn": "皮影",
        "category": "chinese",
        "keywords": "Chinese shadow puppet theater for children, translucent friendly silhouettes, warm gentle backlighting, intricate cut-outs, layered depth, amber orange glow, child-friendly traditional designs, theatrical storytelling",
        "best_for": ["戏剧故事", "光影学习", "表演艺术"],
        "age_rating": 4,
    },

    # === IV. 专业风格 (1种) ===
    "tech": {
        "name_cn": "科技",
        "category": "specialized",
        "keywords": "futuristic children's illustration, soft glowing interfaces, friendly robot designs, colorful holographic elements, clean digital aesthetic with warm touches, child-friendly technology",
        "best_for": ["科技主题", "未来探索", "编程教育"],
        "age_rating": 6,
        "warning": "谨慎使用，可能过于抽象",
    },
}

# ============================================================
# 场景配置 (12 种核心场景)
# ============================================================
SCENES = {
    # === 自然场景 (5种) ===
    "meadow": {
        "name_cn": "草地",
        "category": "nature",
        "elements": "lush green grass meadow, tiny wildflowers scattered, gentle breeze effect, ground-level view, natural daylight, soft grass texture",
        "observable": ["草叶", "野花", "蝴蝶", "露珠", "小石子", "蜜蜂", "蒲公英"],
        "not_observable": ["地下根系", "土壤成分", "地下种子"],
        "characters_cn": ["草", "花", "绿", "地"],
        "mood": "open, fresh, peaceful",
    },
    "pond": {
        "name_cn": "池塘",
        "category": "nature",
        "elements": "crystal clear pond water, mirror-like still water surface, lotus leaves floating, smooth pebbles visible, perfect reflection capability, serene atmosphere",
        "observable": ["水面", "荷叶", "倒影", "小鱼", "蜻蜓", "青蛙", "涟漪"],
        "not_observable": ["深水底部", "水下根系", "鱼卵", "微生物"],
        "characters_cn": ["水", "鱼", "荷", "蛙", "清"],
        "mood": "calm, reflective, serene",
        "special_feature": "reflection",
    },
    "rice-paddy": {
        "name_cn": "稻田",
        "category": "nature",
        "elements": "organized rice paddy rows, green seedlings in shallow water, sky reflections in water, geometric planting pattern, golden hour lighting, agricultural landscape",
        "observable": ["水稻", "田埂", "水面倒影", "白鹭", "农具"],
        "not_observable": ["地下根系", "土壤养分", "种子发芽"],
        "characters_cn": ["田", "稻", "种", "水"],
        "mood": "organized, productive, peaceful",
    },
    "stars": {
        "name_cn": "星空",
        "category": "nature",
        "elements": "deep navy night sky, glowing stars scattered throughout, crescent moon visible, stars at varying depths, magical atmosphere, sense of vastness",
        "observable": ["星星", "月亮", "银河", "流星", "星座轮廓"],
        "not_observable": ["星球表面", "土星环", "星云细节", "遥远星系"],
        "characters_cn": ["星", "月", "天", "夜"],
        "mood": "vast, magical, contemplative",
    },
    "forest": {
        "name_cn": "森林",
        "category": "nature",
        "elements": "giant textured tree trunks, rough bark texture, dappled sunlight filtering through leaves, forest floor details, vertical forest composition, natural woodland atmosphere",
        "observable": ["树皮纹理", "落叶", "蘑菇", "苔藓", "松果", "小鸟", "松鼠"],
        "not_observable": ["年轮(活树)", "内部木纹", "地下根系"],
        "characters_cn": ["树", "林", "叶", "鸟"],
        "mood": "enclosed, natural, mysterious yet safe",
    },

    # === 文化生活场景 (7种) ===
    "kitchen": {
        "name_cn": "厨房",
        "category": "cultural",
        "elements": "warm home kitchen, steaming wok with aromatic food, fresh vegetables on wooden cutting board, traditional Chinese kitchen tools, cozy family cooking atmosphere, warm lighting from above",
        "observable": ["锅碗", "筷子", "蒸汽", "食材", "灶台", "蒸笼", "菜刀"],
        "not_observable": ["食物内部温度", "细菌", "营养成分"],
        "characters_cn": ["锅", "碗", "筷", "饭", "菜", "香"],
        "mood": "warm, familial, aromatic",
    },
    "courtyard": {
        "name_cn": "庭院",
        "category": "cultural",
        "elements": "traditional Chinese courtyard, stone pathways, potted plants, wooden doors, red lanterns, peaceful atmosphere, sky opening above",
        "observable": ["石板路", "花盆", "红灯笼", "木门", "屋檐", "天井"],
        "not_observable": [],
        "characters_cn": ["院", "门", "灯", "家"],
        "mood": "peaceful, culturally rich, intimate",
    },
    "market": {
        "name_cn": "集市",
        "category": "cultural",
        "elements": "bustling Chinese market street, colorful fruit and vegetable stalls, traditional shopfronts, friendly vendors, hanging goods, warm busy atmosphere",
        "observable": ["摊位", "蔬果", "招牌", "人群", "称重器"],
        "not_observable": [],
        "characters_cn": ["买", "卖", "菜", "果"],
        "mood": "bustling, colorful, lively",
    },
    "temple": {
        "name_cn": "寺庙",
        "category": "cultural",
        "elements": "peaceful temple grounds, traditional Chinese architecture, incense smoke, prayer bells, ancient trees, serene spiritual atmosphere",
        "observable": ["香炉", "屋檐", "古树", "石狮", "钟"],
        "not_observable": [],
        "characters_cn": ["庙", "香", "钟", "佛"],
        "mood": "serene, spiritual, ancient",
    },
    "festival": {
        "name_cn": "节庆",
        "category": "cultural",
        "elements": "festive celebration scene, red lanterns everywhere, dragon or lion dance elements, fireworks in sky, happy crowds, traditional decorations, joyful atmosphere",
        "observable": ["灯笼", "烟花", "舞龙舞狮", "对联", "红包"],
        "not_observable": [],
        "characters_cn": ["节", "乐", "红", "福"],
        "mood": "joyful, festive, celebratory",
    },
    "grandma-room": {
        "name_cn": "奶奶房间",
        "category": "cultural",
        "elements": "cozy grandmother's room, wooden furniture, warm lighting, traditional Chinese decor, comfortable bed or chair, family photos, nostalgic warm atmosphere",
        "observable": ["老式家具", "全家福", "针线篮", "茶杯", "老花镜"],
        "not_observable": [],
        "characters_cn": ["奶", "家", "爱", "暖"],
        "mood": "warm, nostalgic, loving",
    },
    "kindergarten": {
        "name_cn": "幼儿园",
        "category": "cultural",
        "elements": "colorful kindergarten classroom, small chairs and tables, children's artwork on walls, toy corners, friendly learning environment, bright cheerful atmosphere",
        "observable": ["小桌椅", "玩具", "画作", "图书角", "滑梯"],
        "not_observable": [],
        "characters_cn": ["学", "玩", "友", "乐"],
        "mood": "cheerful, playful, social",
    },
    "soccer-field": {
        "name_cn": "足球场",
        "category": "cultural",
        "elements": "green grass soccer field, white boundary lines and center circle, goal posts with nets, soccer ball, children in colorful sports uniforms, open sky above, energetic sports atmosphere, dynamic action poses",
        "observable": ["草地", "球门", "足球", "队服", "白线", "球网", "阴影"],
        "not_observable": ["地下灌溉", "草根系统", "球内气压", "肌肉运动"],
        "characters_cn": ["球", "跑", "队", "赢"],
        "mood": "energetic, dynamic, team-oriented",
    },
    "playground": {
        "name_cn": "操场",
        "category": "cultural",
        "elements": "colorful school playground, play equipment with slides and swings, rubber safety ground, children playing together, basketball court lines, school building background, energetic playful atmosphere, bright daylight",
        "observable": ["滑梯", "秋千", "攀爬架", "橡胶地面", "篮球场", "跳绳"],
        "not_observable": ["设备地下固定", "橡胶层结构", "内部安全等级"],
        "characters_cn": ["玩", "友", "乐", "动"],
        "mood": "lively, energetic, social",
    },
}

# ============================================================
# 角色配置 (4 主角 + 支持角色)
# ============================================================
CHARACTERS = {
    # === 主角 ===
    "yueyue": {
        "name_cn": "悦悦",
        "name_meaning": "悦 (yuè) = 喜悦",
        "age": 5,
        "gender": "girl",
        "personality": ["curious", "gentle", "wonder-filled"],
        "anchor": "a 5-year-old Chinese girl named Yueyue with round face, rosy cheeks, bright expressive eyes",
        "signature": {
            "hair": "two pigtails with bright red satin ribbon bows",
            "top": "sunshine yellow knit sweater with ribbed collar",
            "bottom": "medium-wash denim overalls with metal clip straps",
            "shoes": "white canvas slip-on sneakers",
        },
        "build": "chubby preschooler build 105-110cm",
        "best_for": ["自然探索", "温柔学习", "文化传统", "家庭故事"],
    },
    "xiaoming": {
        "name_cn": "小明",
        "name_meaning": "小明 (xiǎomíng) = 小小的光明",
        "age": 6,
        "gender": "boy",
        "personality": ["adventurous", "energetic", "confident"],
        "anchor": "a 6-year-old Chinese boy named Xiaoming with round face, bright smile, curious eyes",
        "signature": {
            "hair": "short neat black hair (2-3cm) with clean side part on left",
            "top": "bright royal blue cotton t-shirt",
            "bottom": "light tan khaki cotton shorts",
            "shoes": "blue and white canvas sneakers with white laces",
        },
        "build": "active athletic build 115-120cm",
        "best_for": ["冒险探索", "运动活动", "问题解决", "户外活动"],
    },
    "meimei": {
        "name_cn": "美美",
        "name_meaning": "美 (měi) = 美丽",
        "age": 4,
        "gender": "girl",
        "personality": ["creative", "imaginative", "artistic"],
        "anchor": "a 4-year-old Chinese girl named Meimei with heart-shaped face, bright expressive eyes, sweet smile",
        "signature": {
            "hair": "long black hair in high ponytail with rainbow pattern plastic hairclip, straight bangs across forehead",
            "top": "pastel pink cotton dress with short puff sleeves and white Peter Pan collar, daisy flower print",
            "bottom": "",  # dress
            "shoes": "white strappy sandals with pink buckles, white ankle socks with lace trim",
        },
        "build": "delicate graceful 100-105cm",
        "best_for": ["艺术创作", "想象游戏", "音乐舞蹈", "色彩学习"],
    },
    "lele": {
        "name_cn": "乐乐",
        "name_meaning": "乐 (lè) = 快乐",
        "age": 3,
        "gender": "boy",
        "personality": ["cheerful", "innocent", "playful"],
        "anchor": "a 3-year-old Chinese boy named Lele with chubby round face, big sparkling eyes, button nose",
        "signature": {
            "hair": "short fluffy black hair (2cm), natural messy-cute style",
            "top": "red and white horizontal striped cotton t-shirt",
            "bottom": "soft royal blue elastic-waist cotton pants",
            "shoes": "tiny red velcro-strap toddler shoes with white rubber soles",
        },
        "build": "chubby toddler 90-95cm",
        "best_for": ["第一次体验", "简单学习", "家庭关爱", "基础认知"],
    },
}

# === 支持角色 ===
SUPPORTING_CHARACTERS = {
    "grandma": {
        "name_cn": "奶奶",
        "anchor": "a kind elderly Chinese grandmother, silver-gray hair in a bun, warm smile, wearing traditional Chinese jacket",
        "signature": {
            "hair": "silver-gray hair neatly tied in low bun",
            "top": "dark blue traditional Chinese jacket with frog buttons",
            "bottom": "loose black cotton pants",
            "shoes": "black cloth shoes with soft soles",
        },
        "relationship": "慈爱、智慧、传统",
    },
    "grandpa": {
        "name_cn": "爷爷",
        "anchor": "a gentle elderly Chinese grandfather, short gray hair, kind eyes, wearing traditional vest",
        "signature": {
            "hair": "short gray hair, slightly balding",
            "top": "beige traditional Chinese vest over white shirt",
            "bottom": "dark gray cotton pants",
            "shoes": "brown leather shoes",
        },
        "relationship": "慈祥、耐心、故事讲述者",
    },
    "mom": {
        "name_cn": "妈妈",
        "anchor": "a young Chinese mother, shoulder-length black hair, gentle smile, wearing casual comfortable clothes",
        "signature": {
            "hair": "shoulder-length black hair, often tied back",
            "top": "soft pink or cream colored blouse",
            "bottom": "comfortable jeans or skirt",
            "shoes": "simple flats",
        },
        "relationship": "温柔、关爱、照顾",
    },
    "dad": {
        "name_cn": "爸爸",
        "anchor": "a young Chinese father, short black hair, warm smile, wearing casual shirt",
        "signature": {
            "hair": "short neat black hair",
            "top": "light blue or white casual button shirt",
            "bottom": "khaki pants",
            "shoes": "casual brown shoes",
        },
        "relationship": "可靠、有趣、保护",
    },
}

# === 动物伙伴 ===
ANIMAL_COMPANIONS = {
    "cat": {
        "name_cn": "小猫",
        "anchor": "a small fluffy orange tabby cat, bright green eyes, pink nose, white paws",
        "signature": {
            "fur": "soft orange tabby fur with darker stripes",
            "eyes": "bright curious green eyes",
            "features": "pink nose, white chest and paws, fluffy tail",
        },
    },
    "dog": {
        "name_cn": "小狗",
        "anchor": "a friendly golden retriever puppy, fluffy golden fur, happy expression, wagging tail",
        "signature": {
            "fur": "soft fluffy golden fur",
            "eyes": "warm brown eyes",
            "features": "floppy ears, black nose, constantly wagging tail",
        },
    },
    "rabbit": {
        "name_cn": "小兔",
        "anchor": "a cute white rabbit with long ears, pink eyes, fluffy cotton tail",
        "signature": {
            "fur": "soft white fluffy fur",
            "eyes": "pink or red gentle eyes",
            "features": "long upright ears, twitching nose, cotton ball tail",
        },
    },
    "chick": {
        "name_cn": "小鸡",
        "anchor": "a tiny yellow chick, fluffy down feathers, small orange beak",
        "signature": {
            "fur": "soft fluffy yellow down",
            "eyes": "small black bead eyes",
            "features": "tiny orange beak and feet",
        },
    },
}

# ============================================================
# 年龄系统
# ============================================================
AGE_SYSTEM = {
    (3, 4): {
        "label": "低龄段",
        "label_en": "Early Childhood",
        "pages": (1, 3),
        "default_pages": 3,
        "sentence_cn": (5, 8),
        "sentence_en": (5, 10),
        "complexity": "simple",
        "learning": ["基础认知", "颜色形状", "感官体验", "安全卫生"],
        "emotions": ["happy", "sad", "surprised"],
        "default_character": "lele",
        "hsk_level": 1,
    },
    (5, 6): {
        "label": "学龄前",
        "label_en": "Preschool",
        "pages": (3, 5),
        "default_pages": 4,
        "sentence_cn": (8, 12),
        "sentence_en": (10, 15),
        "complexity": "simple_narrative",
        "learning": ["基础科学", "基础数学", "社交技能", "情感认知"],
        "emotions": ["happy", "sad", "surprised", "proud", "shy", "curious"],
        "default_character": "yueyue",
        "hsk_level": 2,
    },
    (7, 8): {
        "label": "小学低年级",
        "label_en": "Early Elementary",
        "pages": (5, 7),
        "default_pages": 5,
        "sentence_cn": (12, 15),
        "sentence_en": (15, 20),
        "complexity": "narrative_arc",
        "learning": ["科学方法", "数学逻辑", "历史文化", "品德教育"],
        "emotions": ["complex", "mixed", "empathy"],
        "default_character": "xiaoming",
        "hsk_level": 3,
    },
    (9, 10): {
        "label": "小学高年级",
        "label_en": "Late Elementary",
        "pages": (7, 10),
        "default_pages": 7,
        "sentence_cn": (15, 20),
        "sentence_en": (20, 25),
        "complexity": "complex",
        "learning": ["高级科学", "心理学", "哲学思考", "跨学科"],
        "emotions": ["nuanced", "reflective"],
        "default_character": "xiaoming",
        "hsk_level": 4,
    },
    (11, 12): {
        "label": "初中低年级",
        "label_en": "Early Middle School",
        "pages": (10, 15),
        "default_pages": 10,
        "sentence_cn": (20, 25),
        "sentence_en": (25, 30),
        "complexity": "advanced",
        "learning": ["深度科学", "社会学", "批判思维", "自我认知"],
        "emotions": ["sophisticated"],
        "default_character": "xiaoming",
        "hsk_level": 5,
    },
}

# ============================================================
# 水印防护
# ============================================================
WATERMARK_PREVENTION = {
    "level1": "no watermark, no text, clean image",
    "level2": "clean professional children's book illustration, publication-ready quality, pristine unmarked image, full bleed composition, no watermark, no text overlays, no signatures, no artist marks, no logos, no branding, no copyright symbols, no website URLs, clean professional image",
}

# ============================================================
# 灵魂元素 (Soul)
# ============================================================
SOUL_ELEMENTS = {
    "emotions": {
        "joyful": {"cn": "欢乐", "colors": ["warm-bright", "vibrant"]},
        "calm": {"cn": "平静", "colors": ["serene", "fresh"]},
        "curious": {"cn": "好奇", "colors": ["fresh", "vibrant"]},
        "brave": {"cn": "勇敢", "colors": ["warm-bright", "vibrant"]},
        "warm": {"cn": "温馨", "colors": ["warm-bright", "dreamy"]},
        "wonder": {"cn": "惊奇", "colors": ["dreamy", "vibrant"]},
        "reflective": {"cn": "沉思", "colors": ["serene", "dreamy"]},
    },
    "themes": {
        "growth": {"cn": "成长", "narratives": ["journey", "transform"]},
        "friendship": {"cn": "友谊", "narratives": ["journey", "problem"]},
        "nature": {"cn": "自然", "narratives": ["cycle", "journey"]},
        "family": {"cn": "家庭", "narratives": ["cycle", "problem"]},
        "courage": {"cn": "勇气", "narratives": ["quest", "problem"]},
        "creativity": {"cn": "创意", "narratives": ["transform", "journey"]},
        "discovery": {"cn": "发现", "narratives": ["journey", "quest"]},
    },
    "narratives": {
        "journey": {"cn": "旅程", "pages_min": 3},
        "problem": {"cn": "问题解决", "pages_min": 3},
        "cycle": {"cn": "循环", "pages_min": 3},
        "transform": {"cn": "蜕变", "pages_min": 5},
        "quest": {"cn": "探索", "pages_min": 5},
    },
    "pacing": ["gentle", "lively", "building", "varied"],
    "colors": {
        "warm-bright": {"cn": "温暖明亮", "hex": "#FFD700, #FF6B6B, #FFA500"},
        "fresh": {"cn": "清新", "hex": "#90EE90, #87CEEB, #98FB98"},
        "dreamy": {"cn": "梦幻", "hex": "#DDA0DD, #E6E6FA, #FFB6C1"},
        "vibrant": {"cn": "活力", "hex": "#FF4500, #00CED1, #FFD700"},
        "serene": {"cn": "宁静", "hex": "#B0C4DE, #E0FFFF, #F0FFF0"},
    },
}

# ============================================================
# 故事结构
# ============================================================
STORY_STRUCTURES = {
    3: {
        "name": "Beginning-Middle-End",
        "name_cn": "开始-发展-结束",
        "pages": ["开篇/Setup", "发展/Development", "结局/Resolution"],
    },
    5: {
        "name": "Full Arc",
        "name_cn": "完整弧线",
        "pages": ["引入/Hook", "发现/Discovery", "挑战/Challenge", "成长/Growth", "结局/Resolution"],
    },
    7: {
        "name": "Extended Journey",
        "name_cn": "扩展旅程",
        "pages": ["引入", "探索", "发现", "困难", "尝试", "成功", "总结"],
    },
}

# ============================================================
# CCLP 配置
# ============================================================
CCLP_CONFIG = {
    "version": "4.0",
    "levels": {
        "strict": {
            "name": "严格模式",
            "description": "100% 外观一致，仅表情姿势变化",
            "default": True,
        },
        "moderate": {
            "name": "适度模式",
            "description": "固定面部/发型，服装可根据场景调整",
        },
        "flexible": {
            "name": "灵活模式",
            "description": "仅保留签名特征，允许时间/主题变化",
        },
    },
    "markers": {
        "lock": "[LOCK ESTABLISHED - Page 1]\n[CCLP 4.0 STRICT MODE ACTIVE]",
        "reference": "[CONSISTENCY REFERENCE - Matches Page 1 Lock]\n[CCLP 4.0 STRICT MODE]",
    },
}


path: engine/rules.py
content: """
Picture Book Wizard 规则引擎
将声明式规则转换为可执行代码
"""

from dataclasses import dataclass, field
from typing import List, Dict, Optional, Tuple
from datetime import datetime
import re

from .config import (
    STYLES, SCENES, CHARACTERS, AGE_SYSTEM,
    WATERMARK_PREVENTION, SOUL_ELEMENTS,
    SUPPORTING_CHARACTERS, ANIMAL_COMPANIONS,
    STORY_STRUCTURES, CCLP_CONFIG
)


# ============================================================
# 数据类定义
# ============================================================

@dataclass
class ValidationResult:
    """验证结果"""
    valid: bool
    errors: List[str] = field(default_factory=list)
    warnings: List[str] = field(default_factory=list)


@dataclass
class StoryParams:
    """故事参数"""
    style: str
    scene: str
    age: int
    pages: Optional[int] = None
    character: Optional[str] = None
    emotion: Optional[str] = None
    theme: Optional[str] = None
    with_characters: List[str] = field(default_factory=list)


@dataclass
class CharacterAnchor:
    """角色锚点"""
    name: str
    name_cn: str
    full_anchor: str
    signature_markers: Dict[str, str]
    build: str
    cclp_version: str = "4.0"


@dataclass
class PageContent:
    """单页内容"""
    page_num: int
    story_cn: str
    story_en: str
    pinyin: str
    learning_char: str
    learning_pinyin: str
    learning_meaning: str
    learning_extra: Optional[str] = None
    prompt: str = ""


@dataclass
class PictureBook:
    """完整绘本"""
    title_cn: str
    title_en: str
    style: str
    scene: str
    age: int
    character: str
    pages: List[PageContent]
    created_at: str = ""


# ============================================================
# 验证器
# ============================================================

class Validator:
    """参数验证器"""

    @staticmethod
    def validate_style(style: str) -> ValidationResult:
        """验证风格"""
        if style in STYLES:
            return ValidationResult(valid=True)

        # 模糊匹配建议
        suggestions = [s for s in STYLES.keys() if style.lower() in s.lower()]
        return ValidationResult(
            valid=False,
            errors=[f"未知风格 '{style}'"],
            warnings=[f"您是否想要: {', '.join(suggestions)}"] if suggestions else []
        )

    @staticmethod
    def validate_scene(scene: str) -> ValidationResult:
        """验证场景"""
        if scene in SCENES:
            return ValidationResult(valid=True)

        suggestions = [s for s in SCENES.keys() if scene.lower() in s.lower()]
        return ValidationResult(
            valid=False,
            errors=[f"未知场景 '{scene}'"],
            warnings=[f"您是否想要: {', '.join(suggestions)}"] if suggestions else []
        )

    @staticmethod
    def validate_age(age: int) -> ValidationResult:
        """验证年龄"""
        if 3 <= age <= 12:
            return ValidationResult(valid=True)
        return ValidationResult(
            valid=False,
            errors=[f"年龄 {age} 超出范围 (3-12岁)"]
        )

    @staticmethod
    def validate_character(character: str) -> ValidationResult:
        """验证角色"""
        if character in CHARACTERS:
            return ValidationResult(valid=True)
        return ValidationResult(
            valid=False,
            errors=[f"未知角色 '{character}'"],
            warnings=[f"可用角色: {', '.join(CHARACTERS.keys())}"]
        )

    @staticmethod
    def validate_content_safety(params: StoryParams) -> ValidationResult:
        """内容安全验证"""
        errors = []

        # 禁止内容关键词
        forbidden = ["暴力", "恐怖", "成人", "政治", "violence", "horror", "adult"]

        theme = params.theme or ""
        if any(word in theme.lower() for word in forbidden):
            errors.append(f"主题包含禁止内容: {params.theme}")

        return ValidationResult(valid=len(errors) == 0, errors=errors)

    @classmethod
    def validate_all(cls, params: StoryParams) -> ValidationResult:
        """完整验证"""
        all_errors = []
        all_warnings = []

        checks = [
            cls.validate_style(params.style),
            cls.validate_scene(params.scene),
            cls.validate_age(params.age),
            cls.validate_content_safety(params),
        ]

        if params.character:
            checks.append(cls.validate_character(params.character))

        for result in checks:
            all_errors.extend(result.errors)
            all_warnings.extend(result.warnings)

        return ValidationResult(
            valid=len(all_errors) == 0,
            errors=all_errors,
            warnings=all_warnings
        )


# ============================================================
# 年龄系统
# ============================================================

class AgeSystem:
    """年龄驱动系统"""

    @staticmethod
    def get_age_config(age: int) -> Dict:
        """获取年龄配置"""
        for (min_age, max_age), config in AGE_SYSTEM.items():
            if min_age <= age <= max_age:
                return config
        # 默认返回最高年龄段
        return AGE_SYSTEM[(9, 10)]

    @classmethod
    def calculate_pages(cls, age: int, override: Optional[int] = None) -> int:
        """计算页数"""
        if override:
            return override
        config = cls.get_age_config(age)
        return config["default_pages"]

    @classmethod
    def get_default_character(cls, age: int) -> str:
        """获取默认角色"""
        config = cls.get_age_config(age)
        return config["default_character"]

    @classmethod
    def get_sentence_limits(cls, age: int) -> Tuple[Tuple[int, int], Tuple[int, int]]:
        """获取句子长度限制 (中文, 英文)"""
        config = cls.get_age_config(age)
        return config["sentence_cn"], config["sentence_en"]

    @classmethod
    def get_learning_domains(cls, age: int) -> List[str]:
        """获取学习领域"""
        config = cls.get_age_config(age)
        return config["learning"]


# ============================================================
# 角色锚点生成器
# ============================================================

class CharacterAnchorGenerator:
    """CCLP 4.0 角色锚点生成器"""

    @staticmethod
    def generate(character_id: str, is_first_page: bool = False) -> CharacterAnchor:
        """生成完整角色锚点"""
        char = CHARACTERS.get(character_id)
        if not char:
            raise ValueError(f"未知角色: {character_id}")

        sig = char["signature"]

        # 构建完整锚点
        parts = [
            char["anchor"],
            f"**MANDATORY SIGNATURE: {sig['hair']}**",
            f"**MANDATORY SIGNATURE: {sig['top']}**",
        ]

        if sig.get("bottom"):
            parts.append(f"**MANDATORY SIGNATURE: {sig['bottom']}**")

        parts.append(f"**MANDATORY SIGNATURE: {sig['shoes']}**")
        parts.append(char["build"])

        full_anchor = ", ".join(parts)

        # 添加 CCLP 标记
        if is_first_page:
            full_anchor += "\n[LOCK ESTABLISHED - Page 1]\n[CCLP 4.0 STRICT MODE ACTIVE]"
        else:
            full_anchor += "\n[CONSISTENCY REFERENCE - Matches Page 1 Lock]\n[CCLP 4.0 STRICT MODE]"

        return CharacterAnchor(
            name=character_id,
            name_cn=char["name_cn"],
            full_anchor=full_anchor,
            signature_markers=sig,
            build=char["build"]
        )


# ============================================================
# 提示词组装器
# ============================================================

class PromptAssembler:
    """提示词组装器"""

    @staticmethod
    def assemble(
        style: str,
        scene: str,
        character_anchor: CharacterAnchor,
        action: str,
        expression: str,
        is_first_page: bool = False
    ) -> str:
        """组装完整提示词"""

        style_config = STYLES.get(style, {})
        scene_config = SCENES.get(scene, {})

        parts = [
            # 风格
            style_config.get("keywords", "children's book illustration"),
            # 角色锚点
            character_anchor.full_anchor.split("\n")[0],  # 不含 CCLP 标记
            # 表情和动作
            f"{expression}, {action}",
            # 场景元素
            scene_config.get("elements", ""),
            # 水印防护
            WATERMARK_PREVENTION["level2"],
        ]

        prompt = ", ".join(filter(None, parts))

        # 添加 CCLP 标记
        if is_first_page:
            prompt += "\n\n[LOCK ESTABLISHED - Page 1]\n[CCLP 4.0 STRICT MODE ACTIVE]"
        else:
            prompt += "\n\n[CONSISTENCY REFERENCE - Matches Page 1 Lock]\n[CCLP 4.0 STRICT MODE]"

        return prompt

    @staticmethod
    def get_word_count(prompt: str) -> int:
        """计算提示词词数"""
        # 移除 CCLP 标记后计算
        clean = re.sub(r'\[.*?\]', '', prompt)
        return len(clean.split())


# ============================================================
# 输出格式化器
# ============================================================

class OutputFormatter:
    """输出格式化器"""

    @staticmethod
    def format_page(page: PageContent) -> str:
        """格式化单页输出"""
        output = f"""## 第{page.page_num}页 / Page {page.page_num}

📖 **故事 / Story:**
{page.story_cn}
{page.story_en}

---

🔤 **拼音 / Pinyin:**
{page.pinyin}

---

✨ **学习要点 / Learning Point:**
{page.learning_char} ({page.learning_pinyin}) - {page.learning_meaning}"""

        if page.learning_extra:
            output += f"\n{page.learning_extra}"

        output += f"""

---

🎨 **Banana Nano Prompt:**
```
{page.prompt}
```

---
"""
        return output

    @staticmethod
    def format_book(book: PictureBook) -> str:
        """格式化完整绘本"""
        char = CHARACTERS.get(book.character, {})

        output = f"""# 🌸 {book.title_cn} / {book.title_en}

**Pages**: {len(book.pages)} | **Age**: {book.age} | **Style**: {book.style.title()} | **Character**: {char.get('name_cn', book.character)}

---

"""
        for page in book.pages:
            output += OutputFormatter.format_page(page)

        output += f"""
## 📚 故事总结 / Story Summary

**Created**: {book.created_at}
**Style**: {STYLES.get(book.style, {}).get('name_cn', book.style)}
**Scene**: {SCENES.get(book.scene, {}).get('name_cn', book.scene)}
"""
        return output

    @staticmethod
    def get_output_path(book: PictureBook) -> str:
        """生成输出文件路径"""
        now = datetime.now()
        filename = f"{book.style}-{book.scene}-{book.character}-{len(book.pages)}pages-{now.strftime('%Y%m%d')}.md"
        return f"./output/picture-books/{now.strftime('%Y-%m')}/{filename}"


# ============================================================
# 主引擎
# ============================================================

class PictureBookEngine:
    """绘本生成引擎"""

    def __init__(self):
        self.validator = Validator()
        self.age_system = AgeSystem()
        self.anchor_gen = CharacterAnchorGenerator()
        self.prompt_asm = PromptAssembler()
        self.formatter = OutputFormatter()

    def parse_args(self, args: str) -> StoryParams:
        """解析参数"""
        parts = args.split()

        params = StoryParams(
            style=parts[0] if len(parts) > 0 else "storybook",
            scene=parts[1] if len(parts) > 1 else "meadow",
            age=int(parts[2]) if len(parts) > 2 else 5,
        )

        # 解析可选参数
        for i, part in enumerate(parts[3:], start=3):
            if part.isdigit():
                params.pages = int(part)
            elif part.startswith("with:"):
                params.with_characters = part[5:].split(",")
            elif part.startswith("emotion:"):
                params.emotion = part[8:]
            elif part.startswith("theme:"):
                params.theme = part[6:]
            elif part in CHARACTERS:
                params.character = part

        # 自动填充
        if not params.pages:
            params.pages = self.age_system.calculate_pages(params.age)
        if not params.character:
            params.character = self.age_system.get_default_character(params.age)

        return params

    def validate(self, params: StoryParams) -> ValidationResult:
        """验证参数"""
        return self.validator.validate_all(params)

    def generate_anchor(self, character: str, page: int) -> CharacterAnchor:
        """生成角色锚点"""
        return self.anchor_gen.generate(character, is_first_page=(page == 1))

    def assemble_prompt(
        self,
        params: StoryParams,
        action: str,
        expression: str,
        page: int
    ) -> str:
        """组装提示词"""
        anchor = self.generate_anchor(params.character, page)
        return self.prompt_asm.assemble(
            style=params.style,
            scene=params.scene,
            character_anchor=anchor,
            action=action,
            expression=expression,
            is_first_page=(page == 1)
        )

    def get_scene_characters(self, scene: str) -> List[str]:
        """获取场景推荐汉字"""
        return SCENES.get(scene, {}).get("characters_cn", [])

    def get_style_keywords(self, style: str) -> str:
        """获取风格关键词"""
        return STYLES.get(style, {}).get("keywords", "")

    def format_output(self, book: PictureBook) -> str:
        """格式化输出"""
        return self.formatter.format_book(book)


# ============================================================
# 便捷函数
# ============================================================

def create_engine() -> PictureBookEngine:
    """创建引擎实例"""
    return PictureBookEngine()


def quick_validate(style: str, scene: str, age: int) -> bool:
    """快速验证"""
    params = StoryParams(style=style, scene=scene, age=age)
    result = Validator.validate_all(params)
    return result.valid


path: references/FORMS.md
content: # Forms and Structured Data Guide / 表单与结构化数据指南

This document provides structured input formats and templates for the Picture Book Wizard skill.

---

## Table of Contents

- [Story Generation Request Form](#story-generation-request-form)
- [Character Configuration Template](#character-configuration-template)
- [Scene Description Format](#scene-description-format)
- [Batch Generation Configuration](#batch-generation-configuration)
- [Custom Story Template](#custom-story-template)

---

## Story Generation Request Form

### Basic Story Request

```yaml
---
# Picture Book Story Request
style: clay                    # Required: clay, tech, ink, paper-cut, nianhua, porcelain, shadow-puppet
scene: pond                    # Required: See references/config/scenes.md for all options
character: yueyue              # Optional: yueyue (default), xiaoming, lele, meimei
pages: 1                       # Optional: 1 (default), 3, 5, 7
---

# Optional: Custom Story Requirements
theme: "reflection and self-discovery"
learning_focus: "water, nature, science"
tone: "gentle and contemplative"
```

### Multi-Page Story Request

```yaml
---
# Multi-Page Story Request
style: nianhua
scene: kitchen
character: xiaoming
pages: 3
---

# Story Arc
narrative_type: "learning journey"      # learning journey, discovery, growth, challenge
theme: "family cooperation"
learning_objectives:
  - type: character                     # Always included
  - type: objects                       # Optional: traditional tools/items
  - type: logic                         # Optional: cause-effect, sequences
  - type: emotional                     # Optional: feelings, empathy

# Educational Goals
target_age: "5-6 years"
primary_skill: "using chopsticks"
cultural_element: "Chinese food culture"
```

---

## Character Configuration Template

### Character Selection Criteria

```json
{
  "character_selection": {
    "story_type": "nature_exploration",
    "target_audience": {
      "age_range": "3-6 years",
      "gender_preference": "any",
      "personality_match": "curious"
    },
    "recommended_character": "yueyue",
    "alternatives": ["xiaoming", "meimei"],
    "reasoning": "Yueyue's gentle curiosity suits nature discovery stories"
  }
}
```

### Character Override

```yaml
# Override default character for specific scene
scene: forest
character: xiaoming              # Use adventurous Xiaoming for forest exploration
rationale: "Adventure-focused story requires energetic character"
```

---

## Scene Description Format

### Standard Scene

```yaml
scene:
  name: pond
  type: nature
  primary_elements:
    - clear water surface
    - lotus leaves
    - reflection effects
  optional_elements:
    - dragonflies
    - small fish
    - water ripples
  lighting: soft natural daylight
  atmosphere: peaceful and contemplative
```

### Custom Scene (Not in Predefined List)

```yaml
custom_scene:
  name: "snowy field"
  base_template: meadow           # Use existing scene as base
  modifications:
    - replace: grass → snow
    - add: snowflakes
    - adjust: lighting → winter diffused
  environmental_conditions:
    - season: winter
    - weather: snowing
    - temperature: cold
  required_props:
    - winter clothing for character
    - snow-covered ground
    - bare trees
```

---

## Batch Generation Configuration

### Series Generation

```json
{
  "batch_generation": {
    "series_name": "Nature Discovery Series",
    "character": "yueyue",
    "style": "clay",
    "stories": [
      {
        "scene": "meadow",
        "pages": 1,
        "theme": "seed discovery"
      },
      {
        "scene": "pond",
        "pages": 1,
        "theme": "water reflection"
      },
      {
        "scene": "forest",
        "pages": 1,
        "theme": "tree observation"
      }
    ],
    "consistency_requirements": {
      "character_appearance": "strict",
      "style_rendering": "strict",
      "educational_level": "HSK 1-2"
    }
  }
}
```

### Theme-Based Generation

```yaml
theme_series:
  theme: "seasonal changes"
  stories:
    - scene: meadow
      season_variant: spring
      learning_focus: "flowers blooming"
    - scene: meadow
      season_variant: summer
      learning_focus: "grass growing"
    - scene: meadow
      season_variant: autumn
      learning_focus: "leaves changing"
    - scene: meadow
      season_variant: winter
      learning_focus: "snow covering"
```

---

## Custom Story Template

### Story Outline Form

```markdown
# Story Title: ______________________

## Story Metadata
- **Character**: ___________
- **Scene**: ___________
- **Style**: ___________
- **Pages**: ___

## Story Content (Per Page)

### Page 1
**Chinese Text** (5-12 words):
悦悦_______________________。

**English Translation**:
Yueyue _____________________.

**Learning Point**:
- Character: ___ (pinyin: ___) - meaning: ___
- Optional Objective Type: ___
- Optional Objective Content: ___

**Key Visual Elements**:
- Character pose: ___________
- Main action: ___________
- Background elements: ___________
- Special effects: ___________

### Page 2 (if multi-page)
[Repeat structure]

---

## Story Summary (Multi-Page Only)

**Complete Story** (2-3 sentences):
Chinese: ___________________
English: ___________________

**Characters Learned**:
- Page 1: ___
- Page 2: ___
- Page 3: ___

**Theme**: ___________________
**Core Value**: ___________________

**Extension Activities**:
1. ___________________
2. ___________________
3. ___________________

**Age Suitability**: ___-___ years old
**Reasoning**: ___________________
```

---

## Validation Checklist

Before submitting a story request, verify:

```yaml
validation:
  content_requirements:
    - [ ] Style is valid (clay/tech/ink/paper-cut/nianhua/porcelain/shadow-puppet)
    - [ ] Scene is valid (see references/config/scenes.md)
    - [ ] Character is valid (yueyue/xiaoming/lele/meimei)
    - [ ] Pages is valid (1/3/5/7)
    - [ ] Age-appropriate language (3-6 years)
    - [ ] Learning character is HSK 1-2 level

  technical_requirements:
    - [ ] Character signature features specified
    - [ ] Style keywords included
    - [ ] Scene elements defined
    - [ ] Rendering parameters considered

  educational_requirements:
    - [ ] Learning objective is clear
    - [ ] Character appears in story
    - [ ] Visual reinforcement planned
    - [ ] Cultural authenticity maintained
```

---

## Advanced Configuration

### Learning Objectives Matrix

```json
{
  "learning_matrix": {
    "primary": "character_learning",
    "secondary": [
      {
        "type": "logic",
        "concept": "cause_and_effect",
        "example": "seed + water + sun → growth"
      },
      {
        "type": "objects",
        "item": "chopsticks",
        "usage": "traditional Chinese utensil for picking up food"
      },
      {
        "type": "emotional",
        "emotion": "joy",
        "context": "playing in snow brings pure happiness"
      }
    ],
    "integration": "natural_within_narrative"
  }
}
```

### Output Customization

```yaml
output_preferences:
  file_naming:
    include_timestamp: true
    timestamp_format: YYYYMMDD
    location: ./output/picture-books/YYYY-MM/

  content_format:
    include_pinyin: true
    include_learning_summary: true  # for multi-page
    include_extension_activities: true  # for multi-page

  notification:
    verbose: true
    show_file_path: true
    show_summary: true
```

---

## Examples

### Example 1: Simple Single-Page Request

```yaml
style: clay
scene: pond
character: yueyue
pages: 1
```

### Example 2: Advanced Multi-Page Request

```yaml
style: nianhua
scene: kitchen
character: xiaoming
pages: 3
theme: "learning traditional skills"
learning_objectives:
  - character
  - objects: "chopsticks, dumplings"
  - logic: "sequential learning process"
  - emotional: "family encouragement"
```

### Example 3: Custom Scene Request

```yaml
style: clay
scene: custom
custom_scene:
  base: meadow
  modification: "winter snow field"
  elements:
    - snow-covered ground
    - falling snowflakes
    - winter clothing
character: lele
pages: 3
theme: "first snow experience"
```

---

## Notes

- All forms support both English and Chinese input
- Custom scenes should reference existing scenes as base templates
- Batch generation requires consistent character and style choices
- Learning objectives are optional but enhance educational value
- Output files are automatically organized by month

---

**Related Documents**:
- See `references/REFERENCE.md` for complete parameter reference
- See `references/config/scenes.md` for all available scenes
- See `references/config/characters.md` for character specifications
- See `references/guides/usage-guide.md` for detailed usage instructions

**Last Updated**: 2026-01-10


path: references/README.md
content: # References Directory

This directory contains all reference materials, configuration files, templates, examples, and documentation for the Picture Book Wizard skill.

## Directory Structure

```
references/
├── config/                    # Configuration files (organized by category)
│   ├── core/                  # Core configuration (11 files)
│   │   ├── characters.md      # 4 main protagonist profiles
│   │   ├── styles.md          # 18 visual styles across 4 categories
│   │   ├── scenes.md          # 12 scene environments with Observable Elements
│   │   ├── age-system.md      # Age-driven content specifications (3-12 years)
│   │   ├── rendering.md       # Technical rendering + watermark system
│   │   ├── story-flow.md      # Multi-page story patterns + cover design
│   │   ├── content-safety-validation.md  # Forbidden content rules
│   │   ├── style-assistant.md           # Style recommendation system
│   │   ├── character-advisor.md         # Character recommendation system
│   │   ├── character-extension.md       # Adding new characters guide
│   │   └── learning-objectives.md       # Learning objectives (legacy)
│   │
│   ├── cclp/                  # Character Consistency Lock Protocol (2 files)
│   │   ├── character-consistency-lock.md  # CCLP 4.0 protocol
│   │   └── CCLP-FLEXIBILITY.md           # Three-tier flexibility system
│   │
│   ├── animals/               # Animal character system (5 files)
│   │   ├── animal-characters.md  # Animal character overview
│   │   ├── animal-cclp.md       # Animal CCLP rules
│   │   ├── animal-cat.md        # Cat character template
│   │   ├── animal-dog.md        # Dog character template
│   │   └── animal-bear.md       # Bear character template
│   │
│   └── advanced/              # Advanced configuration (7 files)
│       ├── story-soul.md              # Emotion, Theme, Narrative, Pacing, Color
│       ├── supporting-characters.md   # Family/animal character anchors
│       ├── relationship-dynamics.md   # Multi-character interaction patterns
│       ├── scene-matching.md          # Extended scene intelligent matching
│       ├── reality-validation.md      # Scientific accuracy validation
│       ├── visual-effects.md          # Special visual effects
│       └── scenes-chinese-culture.md  # Chinese cultural scene research
│
├── guides/                    # Documentation and guides
│   ├── usage-guide.md         # Complete usage guide (English)
│   ├── usage-guide-zh.md      # Complete usage guide (Chinese)
│   ├── design.md              # Architecture documentation (English)
│   ├── design-zh.md           # Architecture documentation (Chinese)
│   ├── extending.md           # Extension guide (English)
│   ├── extending-zh.md        # Extension guide (Chinese)
│   ├── WATERMARK-TROUBLESHOOTING.md     # Watermark fix strategies
│   ├── MULTI-CHARACTER-PROMPT-FIX.md    # Multi-character fix guide
│   ├── CCLP-ENFORCEMENT-ENHANCED.md     # CCLP 4.0 implementation details
│   └── ARCHITECTURE-DESIGN-ANALYSIS.md  # Architecture analysis
│
├── examples/                  # Reference examples
│   ├── clay-meadow.md                           # Single-page: clay + meadow
│   ├── clay-meadow-3pages.md                    # Multi-page: 3-page story arc
│   ├── clay-forest-xiaoming.md                  # Single-page: Xiaoming character
│   ├── clay-pond-reflection-optimized.md        # Water reflection techniques
│   ├── ink-forest.md                            # Chinese ink style
│   ├── paper-cut-festival.md                    # Paper-cutting style
│   ├── nianhua-kitchen.md                       # Nianhua style + Grandma
│   ├── nianhua-kitchen-xiaoming-3pages-complete.md  # Complete multi-page demo
│   ├── tech-stars.md                            # Tech style (specialized)
│   └── multi-character-usage-examples.md        # Multi-character examples
│
├── REFERENCE.md               # Quick reference guide
└── FORMS.md                   # Form templates
```

## Quick Navigation

### For New Users
1. Start with `SKILL.md` (main file) for quick start guide
2. Read `guides/usage-guide.md` for complete documentation

### For Content Generation
- **Styles**: `config/core/styles.md` - All 18 visual styles
- **Scenes**: `config/core/scenes.md` - 12 scene environments
- **Characters**: `config/core/characters.md` - 4 protagonists
- **Age System**: `config/core/age-system.md` - Age-driven content

### For Multi-Page Stories
- **CCLP Protocol**: `config/cclp/character-consistency-lock.md`
- **Flexibility Levels**: `config/cclp/CCLP-FLEXIBILITY.md`
- **Story Patterns**: `config/core/story-flow.md`

### For Multi-Character Stories
- **Supporting Characters**: `config/advanced/supporting-characters.md`
- **Relationship Dynamics**: `config/advanced/relationship-dynamics.md`
- **Fix Guide**: `guides/MULTI-CHARACTER-PROMPT-FIX.md`

### For Extension
- **Adding Styles**: `guides/extending.md`
- **Adding Characters**: `config/core/character-extension.md`
- **Adding Scenes**: `config/core/scenes.md`

## File Count Summary

| Directory | Files | Purpose |
|-----------|-------|---------|
| `config/core/` | 11 | Essential configuration |
| `config/cclp/` | 2 | Character consistency |
| `config/animals/` | 5 | Animal characters |
| `config/advanced/` | 7 | Advanced features |
| `guides/` | 10 | Documentation |
| `examples/` | 10 | Reference examples |
| **Total** | **45** | - |

---

*Last updated: 2026-01-18*


path: references/REFERENCE.md
content: # Picture Book Wizard - Complete API Reference

This document provides comprehensive technical reference for all parameters, options, and advanced features of the Picture Book Wizard skill.

---

## Table of Contents

- [Command Syntax](#command-syntax)
- [Parameters Reference](#parameters-reference)
- [Visual Styles Reference](#visual-styles-reference)
- [Scenes Reference](#scenes-reference)
- [Characters Reference](#characters-reference)
- [Learning Objectives Reference](#learning-objectives-reference)
- [Output Format Reference](#output-format-reference)
- [Advanced Features](#advanced-features)
- [Error Handling](#error-handling)

---

## Command Syntax

### Basic Syntax

```
/picture-book-wizard [style] [scene] [pages] [character]
```

### Parameter Order

| Position | Parameter | Required | Default | Valid Values |
|----------|-----------|----------|---------|--------------|
| 1 | style | No* | interactive | See [Styles](#visual-styles-reference) |
| 2 | scene | No* | interactive | See [Scenes](#scenes-reference) |
| 3 | pages | No | 1 | 1, 3, 5, 7 |
| 4 | character | No | yueyue | yueyue, xiaoming, lele, meimei |

*If omitted, interactive selection will be triggered

### Examples

```bash
# Minimal - triggers interactive mode
/picture-book-wizard

# Single page with defaults
/picture-book-wizard clay pond

# Single page with specific character
/picture-book-wizard clay pond 1 xiaoming

# Multi-page story
/picture-book-wizard nianhua kitchen 3 xiaoming

# Full specification
/picture-book-wizard ink forest 5 meimei
```

---

## Parameters Reference

### Style Parameter

**Type**: String (enum)
**Required**: No (triggers interactive mode if omitted)
**Default**: None (interactive selection)

**Valid Values**:

| Code | Name | Description | Best For |
|------|------|-------------|----------|
| `clay` | Clay/Claymation | Hand-sculpted tactile textures | Nature scenes, cozy stories |
| `tech` | Tech/Futuristic | Glowing holographic elements | Space, stars, innovation |
| `ink` | Ink Wash | Traditional Chinese painting | Landscapes, cultural content |
| `paper-cut` | Paper-Cut | Chinese paper-cutting art | Festivals, celebrations |
| `nianhua` | New Year Painting | Chinese folk art style | Domestic scenes, family stories |
| `porcelain` | Blue-White Porcelain | Ceramic glaze aesthetic | Elegant, contemplative scenes |
| `shadow-puppet` | Shadow Puppet | Theatrical silhouettes | Storytelling, dramatic scenes |

**Reference**: `references/config/styles.md` for complete specifications

---

### Scene Parameter

**Type**: String (enum)
**Required**: No (triggers interactive mode if omitted)
**Default**: None (interactive selection)

**Categories**:

#### Nature Scenes

| Code | Name | Primary Elements | Learning Focus |
|------|------|------------------|----------------|
| `meadow` | Grassy Meadow | Grass, wildflowers, open field | Plants, nature discovery |
| `pond` | Pond | Water, lotus leaves, reflections | Water, aquatic life |
| `rice-paddy` | Rice Paddy | Agricultural field, seedlings | Growth, farming, food |
| `stars` | Starry Sky | Night sky, celestial elements | Dreams, cosmos, wonder |
| `forest` | Forest | Trees, woodland, foliage | Trees, ecosystems, exploration |

#### Cultural & Daily Life Scenes

| Code | Name | Primary Elements | Learning Focus |
|------|------|------------------|----------------|
| `kitchen` | Kitchen | Cooking area, family setting | Food, family bonds, cooking |
| `courtyard` | Courtyard | Traditional Chinese architecture | Culture, tradition, heritage |
| `market` | Market | Street stalls, bustling activity | Social interaction, numbers |
| `temple` | Temple | Pagoda, peaceful setting | Culture, respect, spirituality |
| `festival` | Festival | Celebration, decorations | Traditions, customs, joy |
| `grandma-room` | Grandma's Room | Traditional elder's room | Family, respect for elders |
| `kindergarten` | Kindergarten | Classroom, learning environment | Friendship, sharing, learning |

**Reference**: `references/config/scenes.md` for complete specifications

---

### Pages Parameter

**Type**: Integer
**Required**: No
**Default**: 1
**Valid Values**: 1, 3, 5, 7

**Story Structures**:

| Pages | Structure | Best For |
|-------|-----------|----------|
| 1 | Single moment | Simple concepts, quick learning |
| 3 | Beginning → Middle → End | Short stories, basic narrative arcs |
| 5 | Full story arc (Setup → Rising → Climax → Falling → Resolution) | Complete stories, character development |
| 7 | Extended journey | Complex narratives, multiple discoveries |

**Reference**: `references/config/story-flow.md` for detailed story patterns

---

### Character Parameter

**Type**: String (enum)
**Required**: No
**Default**: yueyue
**Valid Values**: yueyue, xiaoming, lele, meimei

**Character Specifications**:

| Code | Name | Age | Gender | Personality | Signature Features |
|------|------|-----|--------|-------------|-------------------|
| `yueyue` | 悦悦 | 5 | Girl | Curious, gentle, wonder-filled | Two pigtails with red ribbons, yellow sweater |
| `xiaoming` | 小明 | 6 | Boy | Adventurous, energetic, confident | Side-part hair, blue t-shirt |
| `lele` | 乐乐 | 3 | Boy | Cheerful, innocent, playful | Chubby toddler face, red striped shirt |
| `meimei` | 美美 | 4 | Girl | Creative, imaginative, artistic | Long ponytail with colorful clip, pink flower dress |

**Character Selection Matrix**:

| Story Type | Recommended Characters |
|------------|------------------------|
| Nature Exploration | Yueyue ⭐⭐⭐, Xiaoming ⭐⭐⭐ |
| Cultural Learning | Yueyue ⭐⭐⭐, Meimei ⭐⭐⭐ |
| Adventure/Action | Xiaoming ⭐⭐⭐ |
| Creative/Artistic | Meimei ⭐⭐⭐ |
| Family Bonding | Yueyue ⭐⭐⭐, Lele ⭐⭐⭐ |
| First Experiences | Lele ⭐⭐⭐, Meimei ⭐⭐ |

**Reference**: `references/config/characters.md` for complete specifications

---

## Visual Styles Reference

### Style Properties

Each style has defined:
- **Color Palette**: Dominant and accent colors
- **Texture**: Material and surface qualities
- **Lighting**: Light direction and quality
- **Technical Keywords**: Rendering parameters for Banana Nano

### Clay Style

```yaml
style: clay
properties:
  technique: "hand-sculpted claymation"
  textures: "physical clay, fingerprint marks, tactile surfaces"
  colors: "warm earth tones, natural palette"
  lighting: "soft studio lighting, warm diffused"
  rendering: "octane render, macro texture details, 8k resolution"
  atmosphere: "warm, inviting, cozy"
  best_for:
    - nature scenes (meadow, pond, forest)
    - intimate family stories (kitchen)
    - close-up interactions
```

### Tech Style

```yaml
style: tech
properties:
  technique: "futuristic technological"
  textures: "smooth surfaces, metallic, holographic"
  colors: "blue, purple, cyan, cool tones"
  lighting: "glowing elements, cool lighting, neon accents"
  rendering: "digital rendering, sharp details, bloom effects"
  atmosphere: "futuristic, innovative, wonder"
  best_for:
    - space scenes (stars)
    - modern concepts
    - innovation themes
```

### Ink Style

```yaml
style: ink
properties:
  technique: "Chinese ink wash painting (水墨画)"
  textures: "fluid brushstrokes, paper texture, wet-on-wet"
  colors: "black, grey, muted colors, minimal palette"
  lighting: "natural ambient, ethereal mist"
  rendering: "traditional art simulation, soft edges"
  atmosphere: "contemplative, artistic, serene"
  best_for:
    - landscapes (meadow, pond, forest)
    - cultural content (courtyard, temple)
    - artistic expression
```

**See `references/config/styles.md` for all 7 styles**

---

## Scenes Reference

### Scene Properties

Each scene defines:
- **Primary Elements**: Essential visual components
- **Optional Elements**: Additional details
- **Environmental Conditions**: Lighting, weather, atmosphere
- **Learning Vocabulary**: Related Chinese characters

### Pond Scene (Example)

```yaml
scene: pond
category: nature
primary_elements:
  - clear water surface
  - lotus leaves (green, floating)
  - water reflections
optional_elements:
  - lily pads
  - dragonflies
  - small fish
  - ripples
environmental_conditions:
  lighting: soft natural daylight
  time_of_day: morning or afternoon
  weather: clear, calm
  atmosphere: peaceful, contemplative
learning_vocabulary:
  primary: 水 (shuǐ) - water
  related: 莲 (lián) - lotus, 叶 (yè) - leaf, 鱼 (yú) - fish
visual_effects:
  - mirror-like reflection on water surface
  - subtle ripple distortions
  - light refraction through water
```

**See `references/config/scenes.md` for all 12 scenes**
**See `references/config/visual-effects.md` for special effects**

---

## Characters Reference

### Character Visual Specifications

Each character has strict visual consistency requirements:

#### Yueyue (悦悦) - Complete Specification

```yaml
character: yueyue
demographics:
  age: 5 years old
  gender: female
  ethnicity: Chinese

appearance:
  face:
    shape: round
    features: rosy cheeks, gentle smile
  hair:
    style: two pigtails
    accessories: red ribbons tied in bows (SIGNATURE - MANDATORY)
  clothing:
    top: yellow sweater (SIGNATURE)
    bottom: denim overalls
    footwear: small shoes

personality:
  primary: curious
  secondary: gentle, wonder-filled
  interaction_style: observant, thoughtful

character_anchor_prompt: |
  A 5-year-old Chinese girl named Yueyue, round face, rosy cheeks,
  two pigtails with red ribbons, wearing yellow sweater and denim overalls

best_suited_for:
  story_types:
    - nature exploration ⭐⭐⭐
    - cultural learning ⭐⭐⭐
    - family bonding ⭐⭐⭐
  age_appropriateness: 4-6 years
  educational_level: beginner to intermediate
```

**See `references/config/characters.md` for all 4 characters**

---

## Learning Objectives Reference

### Primary Objective: Character Learning

**Always Included**: Every page teaches one Chinese character

```yaml
learning_point:
  type: character
  character: 水
  pinyin: shuǐ
  tone: 3rd tone (falling-rising)
  english: water
  hsk_level: 1
  stroke_count: 4
  usage_context: "appears in story text and visible in image"
```

### Secondary Objectives (Optional)

#### 1. Logic (逻辑思维)

```yaml
logic_learning:
  type: logic
  category: cause_and_effect
  concept: "seed + water + sun → growth"
  chinese: "种子 + 水 + 阳光 → 生长"
  teaching_method: "sequential observation in story"
```

#### 2. Objects (物品认知)

```yaml
object_learning:
  type: objects
  item: chopsticks
  chinese: 筷子 (kuàizi)
  category: traditional_utensil
  description: "Chinese traditional eating utensil, used in pairs"
  cultural_context: "requires practice to master, part of Chinese culture"
  usage: "picking up food"
```

#### 3. Emotional (情感发展)

```yaml
emotional_learning:
  type: emotional
  emotion: joy
  chinese: 快乐 (kuàilè)
  context: "playing in snow brings pure happiness"
  development: "recognizing and expressing positive emotions"
```

**See `references/config/learning-objectives.md` for all 6 categories**

---

## Output Format Reference

### Single Page Output

```markdown
# [Title] / [Chinese Title]

**Generated**: YYYY-MM-DD HH:MM:SS
**Style**: [Style name]
**Scene**: [Scene name]
**Character**: [Character name]
**Pages**: 1

---

📖 **故事 / Story:**
[Chinese text]
[English translation]

---

🔤 **拼音 / Pinyin:**
[Pinyin with tone marks]

---

✨ **学习要点 / Learning Point:**
**汉字 (Character)**: [字] ([pinyin]) - [meaning]
[Optional: Secondary learning objectives]

---

🎨 **Banana Nano Prompt:**
[Complete image generation prompt, 150-250 words]

---

## Generation Info / 生成信息
...
```

### Multi-Page Output Structure

```markdown
# [Story Title] / [Chinese Title]

[Metadata block]

---

## Page 1 / 第一页
[Page 1 content: Story + Pinyin + Learning + Prompt]

---

## Page 2 / 第二页
[Page 2 content]

---

## Page 3 / 第三页
[Page 3 content]

---

## 📚 故事总结 / Story Summary

### 完整故事 / Complete Story
[2-3 sentences in Chinese and English]

### 学习成果 / Learning Outcomes
**汉字学习**: [All characters from all pages]
**主题**: [Theme]
**核心价值**: [Core value]

### 延伸活动建议 / Extension Activities
1. [Activity 1]
2. [Activity 2]
3. [Activity 3]

### 适合年龄 / Age Suitability
...
```

**See `assets/templates/output-format.md` for complete template**

---

## Advanced Features

### Custom Scenes

When a scene is not in the predefined list:

1. **Base Template Selection**: Choose similar existing scene
2. **Modification Specification**: Define differences
3. **Element Addition**: Add custom elements
4. **Environmental Adjustment**: Modify lighting, weather

Example:
```yaml
custom_scene:
  base: meadow
  name: "snowy field"
  modifications:
    - replace: grass → snow
    - add: falling snowflakes
    - adjust: lighting → winter diffused
```

### Style-Scene Compatibility

**Excellent Combinations (⭐⭐⭐)**:
- Clay + Nature scenes (meadow, pond, rice-paddy, forest)
- Ink + Nature + Cultural (meadow, pond, forest, courtyard, temple)
- Nianhua + Cultural/Family (kitchen, courtyard, market, festival)
- Paper-Cut + Celebrations (festival, market, courtyard)

**Good Combinations (⭐⭐)**:
- Tech + Cosmic (stars)
- All styles + Any scene (with appropriate adjustments)

**See `references/config/scenes.md` for complete compatibility matrix**

### Batch Generation

Generate multiple related stories:

```yaml
batch_request:
  series: "Four Seasons"
  base_config:
    style: clay
    scene: meadow
    character: yueyue
  variations:
    - pages: 1, theme: "spring flowers"
    - pages: 1, theme: "summer grass"
    - pages: 1, theme: "autumn leaves"
    - pages: 1, theme: "winter snow"
```

---

## Error Handling

### Common Errors

| Error | Cause | Resolution |
|-------|-------|------------|
| Invalid style | Style not in valid list | Use one of: clay, tech, ink, paper-cut, nianhua, porcelain, shadow-puppet |
| Invalid scene | Scene not in valid list | See `references/config/scenes.md` for all options |
| Invalid character | Character not in valid list | Use: yueyue, xiaoming, lele, meimei |
| Invalid pages | Pages not 1/3/5/7 | Use only: 1, 3, 5, or 7 |

### Validation

Before generation, the system validates:
- Parameter types and values
- Style-scene compatibility
- Character-story fit
- Educational appropriateness

---

## File Output

### Automatic File Creation

All generated content is automatically saved to markdown files.

**Location**: `./output/picture-books/[YYYY-MM]/`

**Naming Convention**:
```
[style]-[scene]-[character]-[timestamp].md                # Single page
[style]-[scene]-[character]-[pages]pages-[timestamp].md  # Multi-page
```

**Examples**:
```
clay-pond-yueyue-20260110.md
nianhua-kitchen-xiaoming-3pages-20260110.md
```

### File Organization

```
output/picture-books/
├── README.md
├── 2026-01/
│   ├── clay-pond-yueyue-20260110.md
│   ├── nianhua-kitchen-xiaoming-3pages-20260110.md
│   └── ...
├── 2026-02/
└── ...
```

---

## API Version

**Current Version**: 1.0
**Last Updated**: 2026-01-10
**Compatibility**: Claude Code (Skill System)

---

## Related Documentation

- **Usage Guide**: `references/guides/usage-guide.md`
- **Forms**: `references/FORMS.md`
- **Design Document**: `references/guides/design.md`
- **Extension Guide**: `references/guides/extending.md`

---

**End of Reference Document**


path: references/config/advanced/reality-validation.md
content: # Reality Validation Rules / 现实验证规则

**Version**: 1.0
**Purpose**: Ensure educational content is scientifically accurate, logically consistent, and grounded in reality.

## Overview

This validation system prevents violations of:
- **逻辑** (Logic): Cause-effect relationships, sequential reasoning
- **现实** (Reality): Physical world constraints, observable phenomena
- **常识** (Common Sense): Everyday knowledge, practical understanding
- **规律** (Natural Laws): Biology, physics, chemistry, earth science

---

## I. Biological Rules (生物规律)

### 1. Plant Anatomy & Physiology

#### Tree Structure
**✅ Observable on Living Trees**:
- **Bark**: Texture (rough, smooth, peeling, ridged, scaly)
- **Color variations**: Gray, brown, reddish, white (birch)
- **Moss & Lichen**: Green/gray growth on trunk, especially north-facing
- **Tree knots**: Bumps where branches grew
- **Burls**: Rounded woody growth
- **Insect holes**: Small round holes from beetles, woodpeckers
- **Sap/Resin marks**: Sticky amber-colored drips
- **Branch scars**: Marks where branches fell off
- **Cracks & fissures**: Natural aging cracks in bark
- **Fungi/Mushrooms**: Growing on trunk surface
- **Vines**: Climbing plants wrapped around trunk

**❌ NOT Observable on Living Trees**:
- **Growth rings**: ONLY visible on cut/cross-sectioned wood (stumps, logs, lumber)
- **Inner wood grain**: Hidden beneath bark
- **Heartwood vs. Sapwood**: Internal structure not visible externally
- **Cambium layer**: Thin growing layer under bark, not visible
- **Xylem/Phloem**: Internal transport tissues, not visible

**CORRECT Educational Approach**:
- To teach growth rings: Use fallen log, stump, or woodworking context
- Example: "Yueyue examines a fallen log, counting the circular growth rings on the cut end"

#### Flowers & Plants
**Seasonal Accuracy Required**:
- **Spring**: Blossoms, new leaves, bulbs emerging
- **Summer**: Full foliage, mature flowers, fruits forming
- **Autumn**: Changing leaf colors (yellow, orange, red), falling leaves, ripe fruits
- **Winter**: Bare deciduous trees, evergreens retain needles, dormant perennials

**Growth Patterns**:
- **Roots**: Underground (unless exposed by erosion, flood, or coastal areas)
- **Leaves**: Must have stem/branch connection, don't float in air
- **Flowers**: Grow from buds, don't appear instantly

#### Plant Lifecycle
- **Seeds**: Must be planted or fall to ground before sprouting
- **Germination**: Requires water, appropriate temperature, time
- **Growth direction**: Up toward light (positive phototropism), roots down (positive gravitropism)
- **Water needs**: Plants wilt without water, don't instantly revive

### 2. Animal Behavior & Biology

#### Diurnal/Nocturnal Patterns
- **Nocturnal animals**: Owls, bats, fireflies - rarely seen in bright daylight
- **Diurnal animals**: Most birds, butterflies, squirrels - active during day
- **Crepuscular**: Deer, rabbits - active dawn/dusk

#### Seasonal Behaviors
- **Hibernation**: Bears, some squirrels - not active in winter
- **Migration**: Many birds fly south in autumn, return in spring
- **Breeding seasons**: Specific times for nesting, birthing

#### Size & Proportions
- **Insects**: Small - butterflies ≠ bird-sized, ants ≠ pebble-sized
- **Birds**: Vary greatly - sparrows small, eagles large, but maintain realistic proportions
- **Mammals**: Age-appropriate - baby animals smaller than adults

#### Animal Anatomy
- **Birds**: Have feathers, wings, beaks (not teeth)
- **Fish**: Have scales, gills, fins; live in water
- **Insects**: 6 legs, usually have antennae
- **Mammals**: Have fur/hair, warm-blooded

---

## II. Physical Rules (物理规律)

### 1. Gravity & Motion

**Universal Laws**:
- **Objects fall DOWN**: Not up or sideways (unless in water, blown by wind)
- **Water flows downhill**: Not uphill naturally (unless pumped)
- **Dropped items**: Hit ground unless caught or supported
- **Floating**: Requires water, air, or buoyant force

**Exceptions** (Must be Explained):
- **Balloons**: Float up due to helium/hot air (lighter than air)
- **Kites**: Fly due to wind force (must show wind indicators)
- **Bubbles**: Float briefly in air due to air inside
- **Swimming/Flying**: Animals use energy to counteract gravity

### 2. Light, Shadows & Reflections

**Shadow Rules**:
- **Light source required**: Sun, lamp, fire, etc.
- **Shadow direction**: Opposite to light source
- **Shadow size**: Varies with light source distance and angle
- **No light = No shadows**: Pitch black has no visible shadows
- **Multiple shadows**: Possible with multiple light sources

**Reflection Rules**:
- **Mirror surface needed**: Calm water, glass, polished metal
- **Reflection angle**: Equal to incident angle
- **Ripples disrupt reflections**: Wavy water = distorted reflection
- **Transparency vs. Reflection**: Glass can do both; water surface reflects, depths visible

### 3. Weather & Atmospheric Phenomena

**Weather Consistency**:
- **Rain + Sun**: Possible → creates rainbows (if conditions right)
- **Rain + Wind**: Often together; wind affects rain direction
- **Snow**: Cold temperature required (< 0°C / 32°F)
- **Fog**: Moisture + temperature differential; reduces visibility

**Seasonal Weather**:
- **Summer**: Generally warmer, longer days, thunderstorms common
- **Winter**: Colder, shorter days, snow in cold regions, bare trees
- **Spring**: Warming, rain common, flowers bloom, new leaves
- **Autumn**: Cooling, leaves change color and fall, harvest time

**Sky & Celestial**:
- **Day sky**: Blue (Rayleigh scattering), sun visible
- **Night sky**: Dark, stars/moon visible if clear
- **Twilight**: Gradual transition, orange/pink/purple hues
- **Stars in daytime**: Not visible (sun too bright)
- **Moon phases**: Gradual change over ~29.5 days

### 4. Water Properties

**Water Behavior**:
- **Flows downward**: Due to gravity (streams, waterfalls, rain)
- **Surface tension**: Small insects can walk on water, water forms droplets
- **Freezes at 0°C/32°F**: Ice forms in cold, melts in warmth
- **Evaporation**: Water becomes vapor in heat, forms clouds

**Water in Nature**:
- **Ponds/Lakes**: Still or slow-moving, can have reflections
- **Rivers/Streams**: Flow continuously, create ripples, move objects
- **Rain**: Falls in drops, wets surfaces, forms puddles
- **Ocean waves**: Created by wind, crash on shore, rhythmic

---

## III. Observational Reality (观察现实)

### 1. What Children Can Actually See

**Distance & Scale Limitations**:
- **Microscopic**: Cannot see bacteria, cells, tiny insect details without microscope
- **Too far**: Cannot see individual leaves on distant trees clearly
- **Too high**: Cannot see bird nest details from ground
- **Too deep**: Cannot see bottom of deep pond/ocean from surface
- **Too dark**: Cannot see colors clearly in dim light/darkness

**Age-Appropriate Observation Capabilities**:

#### Ages 3-4:
- **Can observe**: Large shapes, bright colors, movement, textures (touch)
- **Cannot observe**: Fine details, complex patterns, distant objects clearly
- **Height reach**: ~90-100cm, cannot reach table edges, low branches
- **Vision**: Developing depth perception, better at close-up observation

#### Ages 5-6:
- **Can observe**: Patterns, comparisons, counting visible items
- **Cannot observe**: Microscopic life, far distances, complex mechanisms
- **Height reach**: ~105-115cm, can reach low counters, chair seats
- **Vision**: Good color recognition, improving depth perception

#### Ages 7-8:
- **Can observe**: Details, cause-effect, sequences, subtle differences
- **Cannot observe**: Atomic structure, very far space objects detail, internal organs
- **Height reach**: ~120-130cm, can reach higher shelves, lower tree branches
- **Vision**: Mature color vision, good pattern recognition

#### Ages 9-10:
- **Can observe**: Complex patterns, systematic observation, classification
- **Cannot observe**: Still microscopic, molecular, geological time scales
- **Height reach**: ~135-145cm, can reach adult counters, medium tree branches
- **Vision**: Fully developed, can focus on both near and far

#### Ages 11-12:
- **Can observe**: Abstract patterns, scientific relationships, long-term changes
- **Cannot observe**: Quantum phenomena, cellular processes, infrared/ultraviolet
- **Height reach**: ~145-160cm, approaching adult height, higher reach
- **Vision**: Adult-level, can sustain focused observation

### 2. Transparency & Opacity

**Can See Through**:
- **Clear glass**: Windows, drinking glasses
- **Clean water**: Shallow depth, can see fish/plants beneath
- **Thin paper**: Backlight visible, vague shapes
- **Sheer fabric**: Light and shadows, vague shapes

**Cannot See Through**:
- **Solid wood**: Doors, tree trunks, furniture
- **Metal**: Pots, tools, vehicles (except mesh/grating)
- **Thick walls**: Buildings, containers
- **Opaque fabric**: Heavy curtains, clothing
- **Dense foliage**: Thick bushes, layered leaves
- **Muddy/Deep water**: Sediment blocks vision

---

## IV. Common Sense Checks (常识检验)

### 1. Indoor/Outdoor Consistency

**Indoor Environments** (Kitchen, Grandma-room, Kindergarten):
- **Appropriate**: Furniture, appliances, utensils, indoor plants, pet animals
- **Inappropriate**: Wild animals (bears, deer), rain/snow, large trees growing
- **Borderline**: Birds near window (OK), insects (common), small plants (OK)

**Outdoor Environments** (Meadow, Forest, Pond, Stars, Rice-paddy):
- **Appropriate**: Plants, wild animals, weather effects, natural landforms
- **Inappropriate**: Sofas, refrigerators, TV sets, indoor-only items
- **Borderline**: Small items brought outside (blanket for picnic, book to read)

**Semi-Outdoor** (Courtyard, Market, Temple, Festival):
- **Appropriate**: Transitional elements, covered areas, both natural and human-made items
- **Context-dependent**: Furniture OK if outdoor-style; plants common; weather visible

### 2. Temporal Consistency

**Day vs. Night**:
- **Daytime**: Bright, sun visible (or cloudy), blue sky, shadows present, vibrant colors
- **Nighttime**: Dark, moon/stars visible (if clear), muted colors, artificial lights if present
- **Cannot mix**: Bright sun + visible stars, pitch black + vibrant colors

**Seasonal Consistency**:
- **Spring**: Light clothing, blossoms, mild weather, baby animals
- **Summer**: T-shirts, shorts, full foliage, hot weather, sun hats
- **Autumn**: Light jackets, changing leaves, harvest, cooling weather
- **Winter**: Heavy coats, hats, scarves, bare trees (deciduous), snow possible, cold

**Age Progression** (Multi-page stories):
- **Cannot**: Child age backward, instant growth
- **Can**: Very subtle aging (longer story timespan), seasonal time passage
- **Typically**: Same age throughout 3-7 page story (short timeframe)

### 3. Cultural & Social Context

**Kitchen Activities** (Chinese cultural context):
- **Appropriate**: Cooking with wok, chopsticks, steamer baskets, dumplings, rice cooker
- **May include**: Grandmother teaching, family cooking together, traditional dishes
- **Setting**: Clean, organized, warm family atmosphere

**Temple Settings**:
- **Appropriate**: Incense, Buddhist/Taoist imagery, peaceful atmosphere, respectful behavior
- **Behavior**: Quiet, reverent, removing shoes (some temples), gentle movements
- **Inappropriate**: Loud playing, disrespectful actions, athletic activities

**Market Scenes**:
- **Appropriate**: Vendors, fresh produce, busy atmosphere, haggling (polite), carrying baskets
- **Cultural elements**: Chinese vegetables, traditional tools, local community interaction
- **Inappropriate**: Empty market (should be bustling), no vendors, western-only items

---

## V. Educational Content Standards (教育内容标准)

### 1. Scientific Accuracy by Theme

#### "Discovery" Theme
**Requirements**:
- **Observations must be factually accurate**: What child observes is scientifically real
- **Cause-effect relationships must follow natural laws**: A causes B realistically
- **Learning objectives teach correct information**: No misconceptions introduced
- **Scientific method modeled**: Observe → Question → Explore → Understand

**Example - Correct**:
- "Yueyue observes moss growing on the north side of the tree" ✅
- "She notices the bark is rough with deep ridges, perfect for insects to hide" ✅

**Example - Incorrect**:
- "Yueyue sees the tree's growth rings through the bark" ❌ (Impossible)
- "She watches the tree grow taller before her eyes" ❌ (Too fast/unrealistic)

#### "Nature" Theme
**Requirements**:
- **Ecosystems accurately depicted**: Plants, animals, environment interact realistically
- **Seasonal accuracy**: Plants/animals/weather match stated or implied season
- **Habitats correct**: Animals in their natural environment, plants in suitable climate
- **Scale maintained**: Realistic size relationships (flower < bush < tree)

#### "Science" Learning Domain (Ages 7-12)
**Strict Validation Required**:
- **Biology**: Anatomy, physiology, lifecycle, ecology must be factually correct
- **Physics**: Gravity, motion, light, sound follow physical laws
- **Earth Science**: Weather, seasons, water cycle, geological features accurate
- **Chemistry** (if applicable): States of matter, simple reactions accurate

**Validation Priority**: ⚠️ **HIGHEST** - Educational integrity critical

### 2. Age-Appropriate Scientific Complexity

#### Ages 3-4:
- **Acceptable**: Simple cause-effect, fantasy elements in imaginative play
- **Not acceptable**: Teaching incorrect facts as truth (even if simplified)
- **Example**: "The moon follows me" (child perception, OK in imaginative story) vs. "The moon is made of cheese" (incorrect fact, not OK)

#### Ages 5-6:
- **Acceptable**: Simple scientific observations, basic explanations
- **Not acceptable**: Contradicting observable reality, teaching misconceptions
- **Example**: "Seeds need water to grow" ✅ vs. "Seeds grow instantly when planted" ❌

#### Ages 7-8:
- **Required**: Factual accuracy in science-themed content, logical cause-effect
- **Not acceptable**: Magical thinking presented as science, violations of natural laws
- **Example**: "Trees make oxygen from sunlight and water" ✅ vs. "Trees breathe just like people" ⚠️ (Oversimplified, somewhat misleading)

#### Ages 9-10:
- **Required**: Scientific accuracy, intermediate complexity, accurate terminology
- **Not acceptable**: Oversimplification that creates misconceptions
- **Example**: "Photosynthesis converts light energy to chemical energy" ✅

#### Ages 11-12:
- **Required**: Scientific rigor, accurate complex concepts, proper scientific vocabulary
- **Not acceptable**: Any factual errors in scientific content
- **Example**: "Cellular respiration in mitochondria produces ATP" ✅

---

## VI. Validation Triggers (验证触发器)

### High-Priority Validation (MUST Validate)

✅ **Mandatory Validation When**:
1. **Age 7+** AND **theme = "discovery"** OR **theme = "science"**
2. **Any age** AND **learning_domain = "science"**
3. **Nature scenes** (meadow, pond, forest, stars, rice-paddy) AND **theme = "discovery"**
4. **Multi-page stories** (3+ pages) with educational continuity
5. **"Curious" emotion** + **nature theme** + **ages 5+**

**Validation Actions**:
- Cross-reference `references/config/scenes.md` Observable Elements
- Apply reality-validation.md rules
- Check for red flag patterns (see Section VIII)
- Validate cause-effect relationships
- Ensure scientific terminology accuracy

### Moderate-Priority Validation (Should Validate)

⚠️ **Recommended Validation When**:
1. **Cultural scenes** with traditional practices (ensure cultural accuracy)
2. **Ages 5-6** with observation activities
3. **"Reflective" emotion** + **learning objectives**
4. **Any scene** + **"growth" theme** (lifecycle accuracy)
5. **Weather/seasonal elements** present

**Validation Actions**:
- Check cultural authenticity (not just scientific accuracy)
- Verify seasonal consistency
- Ensure age-appropriate observations

### Low-Priority Validation (Optional)

📝 **Light Validation Acceptable**:
1. **Ages 3-4** (fantasy/imagination acceptable in play context)
2. **Atmospheric styles** (dreamy, fairytale - some fantasy elements OK)
3. **Single-page simple stories** without explicit learning objectives
4. **"Joyful" emotion** + **"creativity" theme** (imaginative play)

**Note**: Even low-priority content should NOT teach incorrect facts as truth.

---

## VII. Validation Process Workflow

### Pre-Generation Validation Checklist

**Step 1: Identify Validation Level**
```
IF (age >= 7 AND theme IN ["discovery", "science"]) OR learning_domain == "science":
    validation_level = "HIGH_PRIORITY"
ELIF age >= 5 AND (scene IN nature_scenes OR has_observation_activity):
    validation_level = "MODERATE"
ELSE:
    validation_level = "LOW"
```

**Step 2: Scene Observable Elements Check**
```
scene_elements = get_scene_observable_elements(scene_name)
proposed_description = generate_description_draft()

FOR EACH visual_element IN proposed_description:
    IF visual_element NOT IN scene_elements.visible:
        IF visual_element IN scene_elements.not_visible:
            FLAG as "REALITY_VIOLATION"
            SUGGEST alternative from scene_elements.visible
```

**Step 3: Reality Rules Validation**
```
CHECK biological_rules():
    - Plant anatomy accurate?
    - Animal behavior realistic?
    - Lifecycle/seasonal consistency?

CHECK physical_rules():
    - Gravity observed?
    - Light/shadow logical?
    - Weather consistent?

CHECK observational_reality():
    - Age-appropriate observations?
    - Distance/scale realistic?
    - Transparency/opacity correct?

CHECK common_sense():
    - Indoor/outdoor consistency?
    - Temporal consistency?
    - Cultural appropriateness?
```

**Step 4: Educational Content Validation**
```
IF theme IN ["discovery", "science", "nature", "growth"]:
    ENSURE scientific_accuracy == TRUE
    VERIFY cause_effect_relationships_follow_natural_laws()
    CHECK learning_objectives_teach_correct_facts()
```

**Step 5: Red Flag Scan**
```
red_flags = [
    "growth rings visible on living tree bark",
    "looking inside solid objects",
    "seeing microscopic details without tools",
    "animals behaving contrary to nature",
    "plants in wrong seasons",
    "objects floating without support",
    "instant growth/change",
    "physics violations"
]

FOR EACH flag IN red_flags:
    IF flag DETECTED IN prompt:
        ALERT and REQUIRE_CORRECTION
```

### Example Validation & Correction

**Original Prompt** (Violates Reality):
```
"An 8-year-old Chinese girl named Yueyue, kneeling beside a large tree trunk,
examining closely, giant textured tree trunk with visible swirly wood grain
and circular growth rings, forest background..."
```

**Validation Process**:
```
✅ Age: 8 → High validation priority
✅ Theme: Discovery → Strict scientific accuracy required
✅ Scene: Forest → Check Observable Elements
❌ VIOLATION DETECTED: "circular growth rings" on living tree
✅ Scene Observable Elements: Growth rings NOT visible on living bark
✅ Suggested alternatives: bark texture, moss, lichen, insect holes
```

**Corrected Prompt**:
```
"An 8-year-old Chinese girl named Yueyue, kneeling beside a large tree trunk,
examining closely with focused investigative expression, giant textured tree
trunk with rough ridged bark, patches of green moss growing in the crevices,
small beetle holes and woodpecker marks, forest background..."
```

**Alternative** (If teaching growth rings is objective):
```
"An 8-year-old Chinese girl named Yueyue, kneeling beside a fallen log with
a cut end, examining closely, the cross-section revealing circular growth rings,
counting the rings to estimate the tree's age, forest background..."
```

---

## VIII. Red Flag Patterns (危险信号模式)

### Biological Red Flags
- 🚩 "growth rings visible on living tree bark"
- 🚩 "roots growing above ground" (unless erosion/coastal context)
- 🚩 "flowers blooming in snow" (unless winter-blooming species like plum)
- 🚩 "leaves changing color in spring/summer" (unless diseased)
- 🚩 "baby animals larger than parents"
- 🚩 "nocturnal animals active in bright sunlight"
- 🚩 "fish swimming in air"
- 🚩 "instant plant growth"

### Physical Red Flags
- 🚩 "objects floating without support/water"
- 🚩 "water flowing uphill naturally"
- 🚩 "shadows in wrong direction from light source"
- 🚩 "clear reflections in rippling water"
- 🚩 "bright colors in pitch darkness"
- 🚩 "stars visible in bright daytime"
- 🚩 "snow in hot summer weather"
- 🚩 "frozen water in warm temperature"

### Observational Red Flags
- 🚩 "seeing microscopic details without tools"
- 🚩 "looking inside solid/opaque objects"
- 🚩 "seeing through thick walls"
- 🚩 "observing underground roots without excavation"
- 🚩 "seeing far distant details clearly"
- 🚩 "3-year-old reaching high tree branches"
- 🚩 "seeing in complete darkness"

### Common Sense Red Flags
- 🚩 "wild bears in kitchen"
- 🚩 "sofas in forest"
- 🚩 "rain falling indoors" (unless through hole/window)
- 🚩 "bright sunshine at midnight"
- 🚩 "child wearing winter coat in summer"
- 🚩 "elderly grandma climbing tall trees"
- 🚩 "instant time travel" (in realistic story)

---

## IX. Long-Term Feedback Mechanism (长期反馈机制) 🆕

### Purpose
Continuous improvement of validation system through systematic error tracking, analysis, and rule refinement.

### Error Reporting System

#### When Error is Discovered
**Immediate Documentation Required**:

1. **Error Record Template**:
```markdown
### Error Report #[Number]
**Date Discovered**: YYYY-MM-DD
**Discovered By**: [Educator/Parent/Internal Review]
**File**: [path/to/file.md]
**Page Number**: [X/Y] or [Single]

**Prompt Text with Error**:
```
[Exact prompt text containing the error]
```

**Error Type**: [Biological / Physical / Observational / Common Sense]

**Specific Violation**:
- **What was stated**: [Incorrect description]
- **Why it's wrong**: [Scientific/logical explanation]
- **Correct information**: [Accurate description]

**Impact**: [Low / Medium / High]
- Low: Minor inaccuracy, unlikely to mislead
- Medium: Noticeable error, could cause confusion
- High: Serious misconception, teaches incorrect fact

**Age Group Affected**: [3-4 / 5-6 / 7-8 / 9-10 / 11-12]

**Theme/Scene Combination**: [theme] + [scene] + [style]
```

2. **Example Filled Report**:
```markdown
### Error Report #001
**Date Discovered**: 2026-01-10
**Discovered By**: User (Costa Long)
**File**: output/picture-books/2026-01/storybook-forest-yueyue-5pages-20260110.md
**Page Number**: 3/5

**Prompt Text with Error**:
```
"giant textured tree trunk with visible swirly wood grain and circular growth rings"
```

**Error Type**: Biological

**Specific Violation**:
- **What was stated**: "circular growth rings" visible on living tree trunk
- **Why it's wrong**: Growth rings are internal structure only visible on cut/cross-sectioned wood (stumps, logs). Living tree bark is opaque and covers internal structure.
- **Correct information**: "rough ridged bark texture with patches of green moss and small beetle holes" OR use fallen log/stump context

**Impact**: High
- Teaches 8-year-old children incorrect plant anatomy
- Contradicts basic biology observable in nature
- Undermines scientific discovery theme

**Age Group Affected**: 7-8 (early elementary, science learning)

**Theme/Scene Combination**: discovery + forest + storybook
```

### Root Cause Analysis Process

#### For Each Reported Error, Investigate:

**1. Validation Gap Analysis**:
```
Questions to Answer:
- Was there a validation rule that should have caught this?
  → YES: Why didn't it trigger? (Logic error, rule too narrow)
  → NO: What new rule is needed?

- Was the scene Observable Elements list incomplete?
  → Check scenes.md for missing guidance
  → Add specific "NOT visible" items

- Was the red flag pattern list missing this pattern?
  → Add to Section VIII red flags

- Was validation bypassed or not triggered?
  → Review validation triggers (Section VI)
  → Check if conditions should be expanded
```

**2. Pattern Identification**:
```
Look for:
- Same error in multiple files? → Systematic issue
- Same scene causing errors? → Scene documentation issue
- Same age group? → Age-appropriate validation gap
- Same theme? → Theme-specific validation needed
```

**3. Documentation Review**:
```
Check if error would have been prevented by:
- Better scene Observable Elements documentation
- More specific reality validation rules
- Clearer red flag patterns
- Expanded validation triggers
```

### Rule Update Workflow

#### Process for Adding/Modifying Validation Rules:

**Step 1: Draft New Rule**
```markdown
**Proposed Rule Addition**:

Location: [Section I / II / III / IV / V]
Sub-section: [Specific category]

**New Rule**:
[Clear, specific rule statement]

**Rationale**:
[Why this rule is needed, based on error report #X]

**Examples**:
✅ Correct: [Example following rule]
❌ Incorrect: [Example violating rule]

**Validation Trigger**:
[When should this rule be checked?]
```

**Step 2: Review & Approve**
- Verify rule is scientifically accurate
- Ensure rule doesn't create false positives
- Check rule clarity and actionability
- Confirm validation trigger appropriateness

**Step 3: Update Files**
```
Files to Update:
1. reality-validation.md → Add rule to appropriate section
2. scenes.md → Update Observable Elements if scene-specific
3. SKILL.md → Update validation workflow if needed
4. output-format.md → Add to red flags if applicable
```

**Step 4: Document in Changelog**
```markdown
### Changelog - Reality Validation Rules

#### Version 1.1 (YYYY-MM-DD)
**Changes**:
- **Added**: [Brief description of new rule]
- **Reason**: Addresses Error Report #[X]
- **Impact**: Prevents [specific type of error]

**Updated Sections**:
- Section [X]: [What was added/changed]
- File: scenes.md → [Specific scene updated]

**Testing**:
- Regenerated [number] stories with similar combinations
- Verified error no longer occurs
- Checked for over-correction: [Results]
```

### Regression Testing Procedures

#### After Each Rule Update:

**1. Targeted Regression Tests**:
```
Test Cases:
1. Regenerate original error scenario
   → Verify error is now prevented
   → Verify alternative is scientifically accurate

2. Generate similar scene/theme combinations
   → Ensure new rule catches similar errors
   → Check for false positives (valid content blocked)

3. Test edge cases
   → Verify rule doesn't over-restrict creative freedom
   → Ensure fantasy/imaginative contexts still work appropriately
```

**2. Validation Results Documentation**:
```markdown
### Regression Test Results - Rule Update 1.1

**Test Date**: YYYY-MM-DD
**Rule Tested**: [Rule description]

**Test Case 1**: Original Error Scenario
- Command: /picture-book-wizard storybook forest 8 theme:discovery
- Result: ✅ Error prevented
- Prompt now includes: "rough bark texture with moss" instead of "growth rings"

**Test Case 2**: Similar Scenario (pond scene)
- Command: /picture-book-wizard watercolor pond 7 theme:nature
- Result: ✅ No false positives, appropriate aquatic plant descriptions

**Test Case 3**: Edge Case (stump/log context)
- Command: /picture-book-wizard clay forest 8 [modified for fallen log]
- Result: ✅ Growth rings appropriately mentioned in cut log context

**Test Case 4**: Fantasy Context (ages 3-4)
- Command: /picture-book-wizard fairytale meadow 4
- Result: ✅ Imaginative elements preserved, no over-restriction

**Conclusion**: Rule working as intended, no over-correction detected
```

### Quarterly Review Process

#### Every 3 Months (Scheduled):

**1. Aggregate Error Analysis**:
```
Review Period: [Start Date] to [End Date]

**Metrics**:
- Total errors reported: [Number]
- By category:
  - Biological: [Number]
  - Physical: [Number]
  - Observational: [Number]
  - Common Sense: [Number]

- By severity:
  - High: [Number]
  - Medium: [Number]
  - Low: [Number]

- By age group most affected:
  - Ages 3-4: [Number]
  - Ages 5-6: [Number]
  - Ages 7-8: [Number]
  - Ages 9-10: [Number]
  - Ages 11-12: [Number]

- By theme:
  - Discovery: [Number]
  - Science: [Number]
  - Nature: [Number]
  - [Other themes]: [Number]
```

**2. Pattern Identification**:
```
**Identified Patterns**:

Pattern #1: [Description]
- Frequency: [X errors in Y stories]
- Common elements: [Scene/theme/age combination]
- Root cause: [Analysis]
- Recommended action: [New rule / updated documentation / workflow change]

Pattern #2: [Description]
...
```

**3. Validation System Performance Review**:
```
**Effectiveness Metrics**:

Prevention Rate:
- Pre-validation catches: [X%]
- Errors reaching generation: [Y%]
- Post-generation discoveries: [Z%]

**Goal**: >90% caught pre-generation

False Positive Rate:
- Valid content incorrectly flagged: [Number]
- User overrides of warnings: [Number]

**Goal**: <5% false positive rate

Response Time:
- Average time from error report to rule update: [X days]

**Goal**: <7 days for high-impact errors
```

**4. Documentation Quality Audit**:
```
Review all validation documentation:

✅ Clarity: Are rules clear and actionable?
✅ Completeness: Are all common errors covered?
✅ Accuracy: Are scientific facts current and correct?
✅ Usability: Can implementers easily apply rules?
✅ Examples: Are examples helpful and representative?

**Update Priority List**:
1. [Section needing improvement]
2. [Documentation gap identified]
3. [Examples to add]
```

**5. Recommendations Report**:
```markdown
### Quarterly Validation Review - Q[X] YYYY

**Summary**:
- [Brief overview of quarter's error patterns and improvements]

**Key Achievements**:
- [Number] validation rules added
- [Number] errors prevented by new rules
- [X%] reduction in error rate from previous quarter

**Identified Issues**:
1. [Issue description and priority]
2. [Issue description and priority]

**Recommendations**:
1. **High Priority**: [Action item with timeline]
2. **Medium Priority**: [Action item with timeline]
3. **Low Priority**: [Action item with timeline]

**Next Quarter Goals**:
- [Specific measurable goal 1]
- [Specific measurable goal 2]
- [Specific measurable goal 3]
```

### Community Feedback Integration

#### For Educators/Parents Using Content:

**1. Feedback Channels**:
```
Methods for Submitting Feedback:
- Email: [[REDACTED_SECRET]]
- Online form: [URL to feedback form]
- GitHub Issues: [Repository URL]
- Direct communication: [Contact method]

What to Report:
- Scientific inaccuracies discovered
- Educational effectiveness feedback
- Age-appropriateness concerns
- Cultural accuracy issues
- Suggestions for improvement
```

**2. Feedback Processing Workflow**:
```
Reception → Triage → Investigation → Action → Follow-up

**Triage Criteria**:
- Severity: High (incorrect facts) / Medium (unclear) / Low (stylistic)
- Urgency: Immediate (widespread content) / Normal / Low priority
- Category: Scientific / Educational / Cultural / Technical

**Investigation**:
- Verify reported issue
- Assess impact (how many stories affected)
- Determine root cause
- Classify error type

**Action**:
- Create error report (follow template)
- Root cause analysis
- Update validation rules
- Regenerate/correct affected content

**Follow-up**:
- Notify reporter of resolution
- Document in quarterly review
- Share learnings with community
```

**3. Expert Review Panel** (Phase 3 - Long-term):
```
**Panel Composition**:
- Elementary education specialist
- Child development psychologist
- Biology/natural science educator
- Chinese language/culture expert
- Parent representatives

**Review Schedule**:
- Monthly: High-priority content review
- Quarterly: General content audit
- Annually: Comprehensive curriculum review

**Review Scope**:
- Validate new content before public release
- Audit existing content for accuracy
- Assess age-appropriateness
- Evaluate educational effectiveness
- Recommend improvements
```

### Continuous Improvement Metrics

#### Track Over Time:

**Quality Metrics**:
```
- Error Rate: [Errors per 100 stories generated]
  Goal: <1 error per 100 stories

- Time to Detection: [Days from generation to discovery]
  Goal: Reduce through proactive validation

- Time to Resolution: [Days from discovery to fix]
  Goal: <7 days for high-severity

- Prevention Rate: [% caught by validation before generation]
  Goal: >90%

- User Satisfaction: [Feedback rating from educators]
  Goal: >4.5/5.0
```

**System Health Indicators**:
```
Green (Healthy):
✅ Error rate <1%
✅ Prevention rate >90%
✅ No high-severity errors in last month
✅ Positive community feedback

Yellow (Needs Attention):
⚠️ Error rate 1-3%
⚠️ Prevention rate 80-90%
⚠️ 1-2 high-severity errors in last month
⚠️ Mixed community feedback

Red (Requires Immediate Action):
🚨 Error rate >3%
🚨 Prevention rate <80%
🚨 Multiple high-severity errors
🚨 Negative community feedback trend
```

---

## X. Changelog & Version History

### Version 1.0 (2026-01-10)
**Initial Release**:
- Complete reality validation rule system
- Observable elements framework
- Validation trigger logic
- Red flag pattern library
- Long-term feedback mechanism
- Quarterly review process
- Community integration guidelines

**Catalyst**: Error Report #001 (growth rings on living tree)

**Sections Established**:
- I. Biological Rules
- II. Physical Rules
- III. Observational Reality
- IV. Common Sense Checks
- V. Educational Content Standards
- VI. Validation Triggers
- VII. Validation Process Workflow
- VIII. Red Flag Patterns
- IX. Long-Term Feedback Mechanism
- X. Changelog

---

## XI. Quick Reference Card

### Most Common Validation Checks

**Before generating any content, ask**:

1. ✅ **Can this really be observed?**
   - Check scene Observable Elements list
   - Verify age-appropriate observation capability

2. ✅ **Does this follow natural laws?**
   - Biology: Anatomy, behavior, lifecycle correct?
   - Physics: Gravity, light, motion logical?

3. ✅ **Does this make common sense?**
   - Indoor/outdoor consistency?
   - Temporal consistency (day/night, season)?
   - Cultural appropriateness?

4. ✅ **Is this educationally sound?**
   - Teaching correct facts (not misconceptions)?
   - Age-appropriate complexity?
   - Scientific accuracy for discovery/science themes?

5. ✅ **Any red flags present?**
   - Scan Section VIII red flag list
   - Growth rings on living trees?
   - Impossible observations?
   - Physics violations?

### High-Risk Combinations (Extra Validation)
- Age 7+ + Discovery/Science theme + Nature scene
- Any age + Science learning domain
- Multi-page stories with educational objectives
- Curious emotion + Nature theme + Ages 5+

---

**End of Reality Validation Rules v1.0**


path: references/config/advanced/relationship-dynamics.md
content: # Relationship Dynamics Configuration

**Version**: 3.0 (Multi-Character System)
**Purpose**: Define relationship patterns and interaction dynamics for multi-character stories

---

## Overview

Relationship Dynamics is a new **Soul Layer** dimension that defines how characters interact and relate to each other in stories. This extends the Soul System from 5 to 6 dimensions:

**Soul Layer Dimensions**:
1. Emotion/Mood (7 types)
2. Theme (8 types)
3. Narrative Structure (6 types)
4. Pacing (5 types)
5. Color Mood (7 palettes)
6. **Relationship Dynamics** (4 types) 🆕

---

## Why Relationship Dynamics?

**Problem**: Previous system could only tell single-protagonist stories. Social interaction themes (friendship, family, kindness) lacked authentic multi-character representation.

**Solution**: Relationship Dynamics provides structure for multi-character interactions:
- Enables social learning
- Supports emotional relationship stories
- Allows authentic friendship and family narratives
- Enriches thematic depth

---

## The 4 Relationship Types

### 1. Solo (独自) - `solo`

**Chinese**: 独自、一个人、自我探索

**Pattern**: Single character internal exploration or independent activity

**Character Count**: 1

**Focus**:
- Personal growth
- Self-discovery
- Individual challenges
- Internal reflection

**Best For**:
- **Themes**: Growth, Courage, Discovery, Nature, Creativity
- **Narratives**: Journey, Problem-Solving, Transformation, Quest
- **Emotions**: Curious, Reflective, Brave, Wonder
- **Ages**: All ages (3-12)

**Example Scenarios**:
- Exploring forest alone
- Solving puzzle independently
- Discovering nature
- Personal courage challenge
- Solo artistic creation

**Prompt Structure**:
```
[Single Character Anchor] +
[Solo Action/Pose] +
[Scene Elements] +
[Internal emotional state] +
...
```

---

### 2. Pair (双人) - `pair`

**Chinese**: 双人、两个人、伙伴互动

**Pattern**: Two characters interacting, cooperating, or learning from each other

**Character Count**: 2

**Focus**:
- Friendship development
- Sibling interaction
- Intergenerational learning (grandparent-grandchild)
- Cooperation and teamwork
- Mutual support

**Best For**:
- **Themes**: Friendship, Family, Kindness, Growth, Cooperation
- **Narratives**: Helping, Cooperation, Problem-Solving (dual), Journey (together)
- **Emotions**: Warm, Joyful, Brave (supporting), Calm (together)
- **Ages**: All ages (3-12), especially 5+

**Interaction Patterns**:

**A. Peer Interaction** (同龄伙伴):
- Two protagonists as friends (e.g., Yueyue + Xiaoming)
- Equal roles, mutual learning
- Friendship themes
- Ages 5-12

**B. Intergenerational** (代际互动):
- Child + elderly (e.g., Yueyue + Grandma)
- Teaching-learning relationship
- Family warmth themes
- Ages 3-12

**C. Sibling-like** (类兄弟姐妹):
- Older + younger protagonist (e.g., Xiaoming + Lele)
- Protective/caring dynamic
- Responsibility themes
- Ages 5+

**Example Scenarios**:
- Two friends solving puzzle together
- Grandma teaching grandchild to cook
- Older child helping younger child
- Friends exploring forest together
- Siblings sharing toys

**Prompt Structure**:
```
[Primary Character Anchor - 150 words] +
[Interaction Action] +
[Secondary Character Anchor - 50 words] +
[Relationship Description] +
[Scene Elements] +
...
```

---

### 3. Family (家庭) - `family`

**Chinese**: 家庭、家人聚会、亲情

**Pattern**: Family unit interaction (3-4 characters), focus on family bonds

**Character Count**: 3-4

**Focus**:
- Family warmth and unity
- Intergenerational relationships
- Family activities and traditions
- Collective family experiences
- Cultural heritage transmission

**Best For**:
- **Themes**: Family, Warm, Kindness, Tradition
- **Narratives**: Cycle (family routines), Cumulative (family project), Cooperation
- **Emotions**: Warm, Joyful, Calm
- **Ages**: 5-12 (requires understanding of family roles)

**Family Configurations**:

**A. Three-Generation** (三代同堂):
- Child + Parent + Grandparent
- Example: Yueyue + Mom + Grandma
- Cultural transmission theme

**B. Nuclear Family** (核心家庭):
- Child + Both Parents
- Example: Xiaoming + Mom + Dad
- Family unity theme

**C. Sibling Family** (兄弟姐妹家庭):
- Multiple children + Parent/Grandparent
- Example: Yueyue + Lele + Grandma
- Sibling relationships theme

**Example Scenarios**:
- Family preparing festival dinner together
- Three generations making dumplings
- Family outing to market
- Grandma telling story while parents listen
- Family working in garden together

**Prompt Structure**:
```
[Primary Character Anchor - 150 words] +
[Primary Action] +
[Secondary Character Anchor - 50 words] +
[Secondary Action] +
[Tertiary Character Anchor - 30 words] +
[Family Interaction Description] +
[Scene Elements] +
...
```

**Note**: Family dynamics require longer prompts (250-300 words) to accommodate multiple characters.

---

### 4. Group (群体) - `group`

**Chinese**: 群体、小团队、朋友圈

**Pattern**: Small peer group (3-5 children), focus on group dynamics

**Character Count**: 3-5

**Focus**:
- Peer cooperation
- Group problem-solving
- Social skills development
- Community participation
- Collective creativity

**Best For**:
- **Themes**: Friendship, Cooperation, Creativity, Discovery
- **Narratives**: Cumulative (group contribution), Cooperation, Problem-Solving (group)
- **Emotions**: Joyful, Curious, Brave (collective courage)
- **Ages**: 7-12 (requires understanding of group dynamics)

**Group Configurations**:

**A. Peer Group** (同龄群体):
- 3-5 protagonists as friends
- Example: Yueyue + Xiaoming + Meimei
- Friendship and cooperation

**B. Classroom/Kindergarten** (课堂/幼儿园):
- Multiple children + Teacher
- Example: 4 children + Teacher in kindergarten scene
- Learning and social skills

**C. Play Group** (玩伴):
- Neighborhood children playing together
- Example: 3-4 children at playground/meadow
- Social play and sharing

**Example Scenarios**:
- Group of friends building something together
- Classroom working on group project
- Children playing cooperative game
- Neighborhood kids exploring together
- Group preparing surprise for someone

**Prompt Structure**:
```
[Primary Character Anchor - 100 words] +
[Primary Action] +
[Secondary Character Anchor - 40 words] +
[Tertiary Character Anchor - 40 words] +
[Additional Characters - 20 words each] +
[Group Interaction Description] +
[Scene Elements] +
...
```

**Note**: Group dynamics require careful prompt management. Consider using "group of children" description instead of individual anchors when 4+ characters.

---

## Compatibility Matrix

### Relationship × Theme Compatibility

| Relationship | Highly Compatible Themes | Avoid |
|--------------|-------------------------|-------|
| **Solo** | Growth, Courage, Discovery, Nature | Family, Friendship, Kindness (needs others) |
| **Pair** | Friendship, Family, Kindness, Growth, Cooperation | (None - very versatile) |
| **Family** | Family, Warm, Kindness, Tradition | Courage (unless family supports), Friendship (peer focus) |
| **Group** | Friendship, Cooperation, Creativity, Discovery | Family (different dynamic), intimate themes |

---

### Relationship × Narrative Compatibility

| Relationship | Highly Compatible Narratives | Need Adaptation |
|--------------|----------------------------|-----------------|
| **Solo** | Journey, Problem-Solving, Transformation, Quest | Cycle (can be solo routine), Cumulative (solo building) |
| **Pair** | Helping, Cooperation, Problem-Solving (dual), Journey (together) | All narratives adaptable |
| **Family** | Cycle (family routine), Cumulative (family project), Cooperation | Quest (individual focus), Transformation (needs individual arc) |
| **Group** | Cumulative (group contribution), Cooperation, Problem-Solving (group) | Transformation (individual focus) |

---

### Relationship × Age Suitability

| Relationship | Age 3-4 | Age 5-6 | Age 7-8 | Age 9-10 | Age 11-12 |
|--------------|---------|---------|---------|----------|-----------|
| **Solo** | ✅ Simple | ✅ Good | ✅ Good | ✅ Good | ✅ Good |
| **Pair** | ⚠️ Limited | ✅ Good | ✅✅ Excellent | ✅✅ Excellent | ✅✅ Excellent |
| **Family** | ⚠️ Confusing | ✅ Simple | ✅✅ Excellent | ✅✅ Excellent | ✅ Good |
| **Group** | ❌ Too complex | ⚠️ Limited | ✅ Simple | ✅✅ Excellent | ✅✅ Excellent |

**Age Guidelines**:
- **Ages 3-4**: Solo preferred, pair only with family member (simple interaction)
- **Ages 5-6**: Solo and pair excellent, family simple configurations
- **Ages 7-8**: All types appropriate, pair and family excel
- **Ages 9-12**: All types excellent, can handle complex group dynamics

---

## Auto-Selection Logic

### When to Auto-Select Relationship Type

```python
# Pseudo-code for auto-selection

IF theme = "friendship" THEN
    relationship = "pair" (peer interaction)
    suggest_peer_character()

IF theme = "family" OR theme = "warm" THEN
    relationship = "pair" (intergenerational) OR "family"
    suggest_grandma()

IF theme = "kindness" AND age >= 5 THEN
    relationship = "pair" (helping someone)
    suggest_supporting_character()

IF theme = "cooperation" OR theme = "creativity" (group activity) THEN
    IF age >= 7 THEN
        relationship = "group"
    ELSE
        relationship = "pair"

IF scene = "grandma-room" OR scene = "kitchen" + theme = "family" THEN
    relationship = "pair" (with grandma)
    auto_add_grandma()

IF scene = "kindergarten" AND age <= 6 THEN
    relationship = "pair" OR "group" (classroom context)

IF theme NOT IN ["friendship", "family", "kindness", "cooperation"] THEN
    relationship = "solo" (default)
```

---

## Integration with Existing Soul Elements

### Emotion × Relationship

Different relationships naturally pair with different emotions:

| Emotion | Solo | Pair | Family | Group |
|---------|------|------|--------|-------|
| **Joyful** | ✅ Personal joy | ✅✅ Shared celebration | ✅✅ Family happiness | ✅✅ Group fun |
| **Calm** | ✅✅ Personal peace | ✅✅ Quiet companionship | ✅ Family tranquility | ⚠️ Hard with group |
| **Curious** | ✅✅ Solo exploration | ✅✅ Discovering together | ✅ Family learning | ✅ Group investigation |
| **Brave** | ✅✅ Personal courage | ✅ Supporting friend | ✅ Family encouragement | ✅ Collective courage |
| **Warm** | ⚠️ Limited alone | ✅✅ Caring for each other | ✅✅✅ Family warmth | ✅ Group care |
| **Wonder** | ✅ Personal awe | ✅✅ Shared amazement | ✅ Family wonder | ✅ Group discovery |
| **Reflective** | ✅✅ Personal thought | ✅ Sharing insights | ✅ Wisdom sharing | ⚠️ Harder in group |

---

### Pacing × Relationship

Relationship dynamics affect story rhythm:

| Pacing | Solo | Pair | Family | Group |
|--------|------|------|--------|-------|
| **Gentle** | ✅✅ Easy | ✅✅ Quiet companionship | ✅✅ Family calm | ⚠️ Hard with many |
| **Lively** | ✅ Active solo | ✅✅ Energetic duo | ✅ Family activity | ✅✅✅ Group energy |
| **Building** | ✅✅ Personal journey | ✅✅ Joint challenge | ✅ Family challenge | ✅ Group escalation |
| **Varied** | ✅ Mood changes | ✅✅ Turn-taking | ✅✅ Family rhythm | ✅ Group dynamics |
| **Circular** | ✅✅ Personal routine | ✅ Shared routine | ✅✅✅ Family tradition | ✅ Group ritual |

---

## Prompt Assembly for Each Relationship Type

### Solo (Current Default)

**No changes needed** - existing prompt structure:
```
[Character Anchor] +
[Action/Pose] +
[Scene Elements] +
[Style] +
[Soul Elements] +
...
```

---

### Pair (New Structure)

**Primary-Secondary Model**:
```
[Primary Character Anchor - 150 words with emotion] +
[Primary Action/Pose - narrative appropriate] +
[Interaction Element - what they're doing together] +
[Secondary Character Anchor - 50 words with emotion] +
[Secondary Action/Pose] +
[Relationship Description - how they relate] +
[Scene Elements - theme influenced] +
[Style Keywords] +
[Color Mood palette] +
[Pacing visual cues] +
[Rendering Parameters] +
[Atmosphere - emotion driven, shared space] +
[No Watermark Directive]
```

**Example - Yueyue + Grandma (Kitchen, Family Theme)**:
```
A 5-year-old Chinese girl named Yueyue, round face and rosy cheeks, two pigtails with red ribbons, wearing yellow sweater and denim overalls, standing on small step stool at kitchen counter with focused concentrated expression learning to fold dumplings, small hands carefully pinching dumpling edges with determined effort showing growth and learning, beside her stands 65-year-old grandmother with silver hair in traditional bun, round old-fashioned glasses, burgundy Tang suit, gently guiding with patient teaching expression, grandmother's hands showing proper folding technique, warm intergenerational teaching moment showing family bond and skill transmission, traditional Chinese kitchen setting with bamboo steamer, flour-dusted counter, ingredients in small bowls, watercolor painting style with soft color blending, warm cozy color palette (golden yellows, warm browns, soft reds), gentle pacing with calm peaceful rhythm, soft natural lighting from window creating warm atmosphere, tender loving family mood showing warmth and patience, octane render, macro texture details on dumpling folds, 8k resolution, professional children's book quality, age-appropriate for 5-6 years, no watermark, clean image.
```

---

### Family (Extended Structure)

**Multi-Character Hierarchy**:
```
[Primary Character Anchor - 150 words] +
[Primary Action] +
[Secondary Character Anchor - 50 words] +
[Secondary Action] +
[Tertiary Character Anchor - 30 words] +
[Tertiary Action] +
[Family Interaction Description - collective activity] +
[Scene Elements] +
[Style] +
[Soul Elements] +
[Family Atmosphere - collective mood] +
...
```

**Length**: 250-300 words (longer than standard)

---

### Group (Simplified Multi-Character)

**Group Description Approach** (Recommended for 4+):
```
[Primary Character Anchor - 100 words] +
[Primary Action] +
[Group Description - "accompanied by 3 friends"] +
[Friends Brief Anchor - 40-60 words for 2-3 others] +
[Collective Action] +
[Group Dynamic Description] +
[Scene Elements] +
...
```

**Example Fragment**:
```
5-year-old Yueyue with two pigtails and red ribbons, wearing yellow sweater, leading group activity with excited expression, accompanied by three friends: 6-year-old Xiaoming in blue t-shirt with bright smile, 4-year-old Meimei in pink dress with ponytail, and another child in green shirt, all working together on building block tower in kindergarten, collaborative group dynamic showing teamwork and friendship, children reaching and handing blocks to each other...
```

---

## User Syntax

### Specifying Relationship

**Explicit Specification**:
```
/picture-book-wizard watercolor kitchen 6 3 yueyue with:grandma theme:family
```

**Implied by Theme** (Auto-Selection):
```
/picture-book-wizard watercolor meadow 7 theme:friendship
# System auto-selects: relationship=pair, suggests peer character
```

**Natural Language**:
```
"Create a story about Yueyue and her grandmother cooking together"
# System parses: pair relationship, Yueyue + Grandma, kitchen scene suggested
```

---

## Auto-Suggestion Workflow

### Step 1: Analyze Input
- Check theme, scene, age
- Determine if multi-character appropriate

### Step 2: Determine Relationship Type
- Based on theme and compatibility matrix
- Check age suitability

### Step 3: Suggest Supporting Character
- If pair: Suggest grandma/peer based on theme
- If family: Suggest grandma + parent
- If group: Offer peer group option

### Step 4: Notify User
```
💡 Suggestion: Based on your "family" theme selection, I recommend adding Grandma (奶奶) as a supporting character for a warm intergenerational story.

This will create a pair relationship dynamic with:
- Yueyue learning traditional skills from Grandma
- Warm family bond and cultural transmission
- Perfect for kitchen scene you selected

Would you like to proceed with Yueyue + Grandma pair? (Will be added automatically if you don't specify otherwise)
```

### Step 5: Apply or Allow Override
- User can accept, reject, or specify different character
- System proceeds with selected relationship configuration

---

## Special Considerations

### Age Appropriateness

**Ages 3-4**:
- **Solo**: ✅ Preferred for simplicity
- **Pair**: ⚠️ Only with familiar family member (Grandma), simple interaction
- **Family**: ❌ Too many characters to track
- **Group**: ❌ Cognitively overwhelming

**Ages 5-6**:
- **Solo**: ✅ Good for personal growth stories
- **Pair**: ✅✅ Excellent, can understand friendship and family bonds
- **Family**: ✅ Simple configurations (3 characters)
- **Group**: ⚠️ Limited, simple playground scenarios only

**Ages 7-8**:
- **Solo**: ✅ Good for independent challenges
- **Pair**: ✅✅ Excellent for friendship and cooperation
- **Family**: ✅✅ Excel at understanding family dynamics
- **Group**: ✅ Can handle 3-4 peer interactions

**Ages 9-12**:
- **All types**: ✅✅ Excellent across all relationship dynamics
- Can handle complex social interactions
- Understand nuanced relationships
- Can follow multiple character arcs

---

### Cognitive Load

**Token/Word Budget**:
- Solo: 150-250 words (standard)
- Pair: 200-300 words (extended)
- Family: 250-350 words (long)
- Group: 250-350 words (long, but simplified descriptions)

**Character Tracking Complexity**:
- Solo: 1 character (simple)
- Pair: 2 characters (moderate)
- Family: 3-4 characters (complex)
- Group: 3-5 characters (complex, needs simplification)

---

## Implementation Guidelines

### Phase 1 (MVP) - Current
- ✅ Solo (already implemented)
- ✅ Pair (implement with Grandma)

### Phase 2
- Family (3 character configurations)
- Add Mom and Dad

### Phase 3
- Peer pairs (protagonist + protagonist)

### Phase 4-5
- Group dynamics
- Community characters

---

## Testing Checklist

When using relationship dynamics, verify:

**Relationship Type Quality**:
- [ ] Relationship type appropriate for theme
- [ ] Character count matches age appropriateness
- [ ] Interaction dynamic clear and natural

**Character Quality**:
- [ ] All characters maintain signature features
- [ ] Primary/secondary role balance appropriate
- [ ] Interaction between characters visible

**Soul Integration**:
- [ ] Emotion expressed by all characters
- [ ] Theme supported by relationship dynamic
- [ ] Narrative structure suits relationship type
- [ ] Pacing appropriate for interaction level

**Technical Quality**:
- [ ] Prompt length appropriate (not too long)
- [ ] Character anchors properly sized
- [ ] Relationship description clear
- [ ] All VCP anchors maintained

---

## Version History

- **Version 3.0** (2026-01-10): Initial relationship dynamics system with 4 types (solo, pair, family, group)
- **Planned 3.1**: Expand pair configurations with peer interactions
- **Planned 3.2**: Full family dynamics (4 character configurations)
- **Planned 3.3**: Group dynamics optimization

---

**Status**: ✅ Phase 1 (MVP) - Solo and Pair relationship types ready for implementation


path: references/config/advanced/scene-matching.md
content: # Scene Matching System / 场景匹配系统

**版本**: 1.0
**目的**: 支持用户请求的自定义场景，同时保持核心场景配置精简和现实验证系统的完整性

---

## I. 系统概述 / System Overview

### 核心理念

**保持核心场景精简**：
- 12 个核心场景 = 完整的可观察元素数据库（HIGH validation）
- 扩展场景 = 智能匹配 + 动态推理（MEDIUM validation）
- 避免无限膨胀配置文件

**三层验证策略**：
1. **通用规则**（所有场景）：物理、生物、观察能力、常识
2. **类别规则**（场景类别）：该类别共同的验证规则
3. **特定规则**（核心12场景）：详细的可观察元素列表

---

## II. 场景分类系统 / Scene Category System

### Category 1: 开阔地形类 (Open Terrain)

**核心场景**：`meadow` (草地)

**可匹配场景**：
- **高原** (plateau) - 匹配度 75%
- **草原** (grassland) - 匹配度 90%
- **平原** (plain) - 匹配度 85%
- **牧场** (pasture) - 匹配度 80%
- **田野** (field) - 匹配度 85%

**共同特征**：
- ✅ 开阔视野
- ✅ 地面观察视角
- ✅ 草本植被为主
- ✅ 自然光线充足
- ✅ 天空可见

**通用验证规则**：
```markdown
✅ 可观察元素（所有开阔地形）：
- 草地/植被表面
- 天空和云
- 地平线/远景
- 地面小动物（昆虫、鸟类）
- 风吹动植物
- 阳光和阴影

❌ 不可观察（所有开阔地形）：
- 地下根系（除非挖掘）
- 土壤内部结构
- 微生物
- 地下水位
```

**场景特定调整**：

**高原 (Plateau)**：
- **添加元素**：
  - 远处雪山/山峦
  - 稀疏矮小植被
  - 高原特有动物（牦牛、旱獭）
  - 强烈日光效果
- **调整规则**：
  - 植被密度：低于标准草地
  - 物种多样性：减少
  - 海拔效应：提及但不夸大（儿童友好）
- **避免错误**：
  - ❌ "茂密热带植物"（高海拔不适合）
  - ❌ "蝴蝶和蜜蜂很多"（高原昆虫稀少）
  - ❌ "空气稀薄导致呼吸困难"（儿童内容不适合负面体验）

**草原 (Grassland)**：
- **添加元素**：
  - 广阔无边的视野
  - 野生动物（鹿、兔）
  - 草浪随风起伏
- **调整规则**：
  - 强调广阔感
  - 野生属性更强

**牧场 (Pasture)**：
- **添加元素**：
  - 围栏
  - 家畜（牛、羊、马）
  - 农场建筑（远处）
- **调整规则**：
  - 人工管理痕迹
  - 家畜与野生动物的区别

---

### Category 2: 密集植被类 (Dense Vegetation)

**核心场景**：`forest` (森林)

**可匹配场景**：
- **竹林** (bamboo forest) - 匹配度 70%
- **树林** (woods) - 匹配度 95%
- **丛林** (jungle) - 匹配度 60%
- **山坡树林** (hillside forest) - 匹配度 85%
- **果园** (orchard) - 匹配度 65%

**共同特征**：
- ✅ 植被密集
- ✅ 有遮蔽/树冠
- ✅ 光影斑驳
- ✅ 垂直空间结构
- ✅ 地面到树冠的分层

**通用验证规则**：
```markdown
✅ 可观察元素（所有密集植被）：
- 树干/茎干表面
- 树皮纹理（或茎秆）
- 叶子形状和颜色
- 树冠/植被顶部
- 地面落叶/碎屑
- 藤蔓、苔藓、地衣
- 林间光线和阴影

❌ 不可观察（所有密集植被）：
- 年轮（活树上）
- 内部木纹
- 地下根系
- 树内管道系统
```

**场景特定调整**：

**竹林 (Bamboo Forest)**：
- **关键差异**：
  - 竹子 ≠ 树木（是草本植物）
  - 竹节、竹叶完全不同
  - 生长速度快
- **添加元素**：
  - 竹节（节状结构）
  - 竹叶（细长、成簇）
  - 竹笋（地面）
  - 特有声音（风吹竹叶沙沙声）
- **调整规则**：
  - 不能使用"树木"术语，应该是"竹子"
  - 竹子是空心的（但不能说"看到内部"）
  - 竹笋可见（春季）
- **避免错误**：
  - ❌ "竹子的年轮"（草本植物没有年轮）
  - ❌ "粗糙的树皮"（竹子表面光滑）
  - ❌ "树枝上的鸟巢"（竹子很少有大型鸟巢）

**丛林 (Jungle)**：
- **添加元素**：
  - 极度茂密的植被
  - 热带植物（大叶子、藤蔓）
  - 高温高湿（可见效果：水汽）
  - 热带动物
- **调整规则**：
  - 植被密度极高
  - 多层次结构（地面、灌木、树冠、藤蔓）
- **避免错误**：
  - ❌ "在温带气候的丛林"（地理矛盾）
  - ❌ "清晰的地平线"（丛林遮蔽视野）

**果园 (Orchard)**：
- **添加元素**：
  - 果树（苹果、梨、桃等）
  - 果实（当季）
  - 整齐排列
  - 人工管理痕迹
- **调整规则**：
  - 果树种类一致性
  - 季节与果实匹配
- **避免错误**：
  - ❌ "冬天树上挂满苹果"（季节矛盾）

---

### Category 3: 水域类 (Water Bodies)

**核心场景**：`pond` (水潭)

**可匹配场景**：
- **湖泊** (lake) - 匹配度 85%
- **小溪** (stream) - 匹配度 70%
- **河边** (riverside) - 匹配度 75%
- **瀑布** (waterfall) - 匹配度 60%
- **喷泉** (fountain) - 匹配度 50%

**共同特征**：
- ✅ 水面可见
- ✅ 水的特性（流动/静止、透明/浑浊）
- ✅ 水边环境
- ✅ 可能有倒影
- ✅ 水生植物或动物

**通用验证规则**：
```markdown
✅ 可观察元素（所有水域）：
- 水面（静止或流动）
- 水的颜色和透明度
- 水面倒影（静止水面）
- 水边植被
- 浅水区底部（如果清澈）
- 水生动物（鱼、青蛙等，如可见）
- 波纹、水花
- 水声（流动水）

❌ 不可观察（所有水域）：
- 深水区底部（光线无法穿透）
- 水下根系（深处）
- 水分子结构
- 溶解物质（除非改变水色）
- 地下水源
```

**场景特定调整**：

**湖泊 (Lake)**：
- **添加元素**：
  - 更大规模
  - 远处对岸（或看不到）
  - 可能有船只
  - 湖中心水深（不透明）
- **调整规则**：
  - 视野更广
  - 深度感

**小溪 (Stream)**：
- **添加元素**：
  - 流动的水
  - 溪流声
  - 小石头、鹅卵石
  - 水流冲刷痕迹
- **调整规则**：
  - 强调流动性
  - 浅水可见底部
- **避免错误**：
  - ❌ "静止的湖面倒影"（溪水流动，倒影扭曲）

**瀑布 (Waterfall)**：
- **添加元素**：
  - 下落的水流
  - 水雾
  - 瀑布声（轰鸣）
  - 彩虹（阳光+水雾）
- **调整规则**：
  - 水的运动感
  - 声音和视觉结合
- **避免错误**：
  - ❌ "清晰的水面倒影"（瀑布水流湍急）

---

### Category 4: 天空类 (Sky & Celestial)

**核心场景**：`stars` (星空)

**可匹配场景**：
- **夜空** (night sky) - 匹配度 95%
- **日出** (sunrise) - 匹配度 60%
- **日落** (sunset) - 匹配度 60%
- **云层** (clouds) - 匹配度 50%
- **极光** (aurora) - 匹配度 40%

**共同特征**：
- ✅ 仰视视角
- ✅ 天空现象
- ✅ 光线效果
- ✅ 广阔感、距离感
- ✅ 时间特征明显

**通用验证规则**：
```markdown
✅ 可观察元素（天空类）：
- 星星（点状光源）
- 月亮（相位变化）
- 太阳（不直视）
- 云朵（形状、颜色）
- 天空颜色渐变
- 地平线剪影
- 大气光学现象（彩虹、霞光）

❌ 不可观察（天空类）：
- 星球表面细节（太远）
- 星座实际距离（三维）
- 大气层结构
- 宇宙空间物体细节
```

**场景特定调整**：

**日出/日落 (Sunrise/Sunset)**：
- **添加元素**：
  - 地平线
  - 天空颜色渐变（橙、粉、紫）
  - 太阳（不直视）
  - 逆光剪影
- **调整规则**：
  - 时间感（清晨/傍晚）
  - 光线方向
- **避免错误**：
  - ❌ "直视太阳看到表面"（危险且不可能）
  - ❌ "午夜日出"（时间矛盾）

**极光 (Aurora)**：
- **添加元素**：
  - 绿色/粉色光带
  - 夜空背景
  - 极地环境（寒冷）
- **限制**：
  - 仅在高纬度地区
  - 需要特定地理背景
- **避免错误**：
  - ❌ "在热带看到极光"（地理不可能）

---

### Category 5: 建筑类 (Architecture)

**核心场景**：`courtyard` (四合院), `temple` (寺庙)

**可匹配场景**：
- **园林** (garden) - 匹配度 80% → courtyard
- **亭台** (pavilion) - 匹配度 75% → courtyard
- **古建筑** (ancient architecture) - 匹配度 70% → temple
- **城墙** (city wall) - 匹配度 60% → courtyard
- **桥** (bridge) - 匹配度 50% → courtyard

**共同特征**：
- ✅ 人工结构
- ✅ 建筑材料（木、石、砖）
- ✅ 中国传统元素
- ✅ 文化和历史感

**通用验证规则**：
```markdown
✅ 可观察元素（建筑类）：
- 外部结构（柱、梁、墙、瓦）
- 装饰元素（雕刻、彩绘）
- 材料纹理
- 建筑轮廓
- 周围环境

❌ 不可观察（建筑类）：
- 墙内部结构
- 地基深度
- 隐藏的连接件
- 管道系统
```

---

### Category 6: 室内类 (Indoor)

**核心场景**：`kitchen` (厨房), `grandma-room` (奶奶房间), `kindergarten` (幼儿园)

**可匹配场景**：
- **客厅** (living room) - 匹配度 75% → grandma-room
- **卧室** (bedroom) - 匹配度 80% → grandma-room
- **书房** (study) - 匹配度 70% → grandma-room
- **教室** (classroom) - 匹配度 90% → kindergarten
- **图书馆** (library) - 匹配度 60% → grandma-room

**共同特征**：
- ✅ 封闭空间
- ✅ 人工照明或窗户光
- ✅ 家具和物品
- ✅ 室内温度（舒适）
- ✅ 人类活动痕迹

**通用验证规则**：
```markdown
✅ 可观察元素（室内类）：
- 家具外观
- 物品摆放
- 装饰品
- 窗户和光线
- 墙面、地面
- 室内植物

❌ 不可观察（室内类）：
- 家具内部结构
- 墙体内部
- 电线布局
- 管道系统
```

---

### Category 7: 特殊环境 (Special Environments)

**这些场景需要特别注意，可能不适合直接匹配**

**沙漠 (Desert)**：
- **匹配度**: 低（与所有核心场景差异大）
- **推荐**: 创建专用验证规则或警告用户
- **关键差异**：
  - 极度干燥
  - 沙子（不是土壤）
  - 极端温差
  - 稀少生物
- **如果使用**：基于 `meadow` 但大量调整

**海滩 (Beach)**：
- **匹配度**: 低
- **推荐**: 创建专用规则
- **关键差异**：
  - 沙 + 海水组合
  - 潮汐
  - 海洋生物
  - 盐分

**雪地 (Snow Field)**：
- **匹配度**: 中等 → `meadow`（开阔地形）
- **关键调整**：
  - 冬季环境
  - 雪覆盖
  - 寒冷生物适应

**洞穴 (Cave)**：
- **匹配度**: 极低
- **推荐**: 警告用户
- **关键问题**：
  - 黑暗（需要光源）
  - 封闭空间
  - 特殊地质结构
  - 可能不适合幼儿内容（恐惧感）

**极端环境（不推荐）**：
- ❌ **海底** (Underwater) - 完全不同的物理规则
- ❌ **太空** (Space) - 无重力、无空气
- ❌ **火山** (Volcano) - 危险、极端高温
- ❌ **地下** (Underground) - 黑暗、恐惧

---

## III. 匹配流程 / Matching Process

### Step 1: 场景识别

```
INPUT: 用户场景名称（中文或英文）

PROCESS:
1. 标准化场景名称
2. 检查是否在核心12场景中
3. 如果不在 → 进入匹配流程
```

### Step 2: 场景分类

```
ANALYZE:
- 场景描述中的关键词
- 环境特征（开阔/封闭、自然/人工、室内/室外）
- 植被类型
- 水的存在
- 建筑元素

CLASSIFY:
→ Category 1: 开阔地形
→ Category 2: 密集植被
→ Category 3: 水域
→ Category 4: 天空
→ Category 5: 建筑
→ Category 6: 室内
→ Category 7: 特殊环境（警告）
```

### Step 3: 相似度计算

```
FOR EACH core_scene IN category:
    similarity = calculate_similarity(
        user_scene,
        core_scene,
        features=[
            'terrain_type',      # 地形类型 30%
            'vegetation_density', # 植被密度 20%
            'water_presence',    # 水体存在 15%
            'openness',          # 开阔度 15%
            'lighting',          # 光线条件 10%
            'human_elements'     # 人工元素 10%
        ]
    )

SELECT: highest_similarity_scene
```

### Step 4: 生成调整建议

```
GENERATE:
- 需要添加的特定元素
- 需要调整的验证规则
- 需要避免的常见错误
- 验证等级（HIGH/MEDIUM/LOW）
```

### Step 5: 用户确认

```
PRESENT:
┌─────────────────────────────────────────────────┐
│ 💡 场景匹配建议                                 │
├─────────────────────────────────────────────────┤
│ 请求场景：高原 (Plateau)                        │
│ 场景类别：开阔地形类                            │
│                                                 │
│ 🎯 最佳匹配：草地 (Meadow) - 相似度 75%         │
│                                                 │
│ 📊 共同特征：                                   │
│ ✅ 开阔视野                                     │
│ ✅ 草本植被                                     │
│ ✅ 地面观察视角                                 │
│ ✅ 自然光线充足                                 │
│                                                 │
│ 🔧 需要调整的元素：                             │
│ • 植被：稀疏矮小（高海拔特征）                  │
│ • 远景：添加雪山/远山                           │
│ • 动物：高原特有（牦牛、旱獭）                  │
│ • 光线：强烈日光效果                            │
│                                                 │
│ ⚠️ 需要避免的错误：                             │
│ ❌ "茂密热带植物"（高海拔不适合）               │
│ ❌ "大量蝴蝶和蜜蜂"（高原昆虫稀少）             │
│                                                 │
│ 📋 验证等级：MEDIUM                             │
│ （使用通用规则 + 类别规则 + 场景推理）          │
│                                                 │
│ 选项：                                          │
│ [✓ 使用此匹配生成] [查看其他匹配] [自定义]      │
└─────────────────────────────────────────────────┘
```

---

## IV. 测试案例 / Test Cases

### 测试案例 1：高原 (Plateau)

**输入**：
```
/picture-book-wizard watercolor 高原 8 theme:discovery
```

**预期处理**：
```
1. 识别："高原"不在核心12场景
2. 分类：开阔地形类
3. 匹配：meadow (75%)
4. 验证等级：MEDIUM
5. 调整建议：
   - 添加：远山、稀疏植被、高原动物
   - 避免：茂密植被、低海拔物种
6. 用户确认
7. 生成内容（使用调整后的规则）
```

**预期输出特征**：
```
故事：悦悦在高原上发现了一株矮小的高山花...
提示词：...sparse highland vegetation, distant snow-capped mountains,
         strong sunlight, thin air atmosphere, yak in distance...
学习要点：科学（高原植物适应高海拔环境）
验证报告：✅ MEDIUM validation passed
```

---

### 测试案例 2：竹林 (Bamboo Forest)

**输入**：
```
/picture-book-wizard ink 竹林 7 emotion:calm
```

**预期处理**：
```
1. 识别："竹林"不在核心场景
2. 分类：密集植被类
3. 匹配：forest (70%)
4. 验证等级：MEDIUM
5. 关键差异警告：
   ⚠️ 竹子 ≠ 树木（草本植物 vs. 木本植物）
   ⚠️ 不能使用"树"相关术语
6. 调整建议：
   - 特有元素：竹节、竹叶、竹笋
   - 术语替换："竹子"而非"树"
   - 避免：年轮、树皮、树枝
7. 用户确认
```

**预期输出特征**：
```
故事：悦悦走在竹林中，听到风吹竹叶的沙沙声...
提示词：...bamboo forest, bamboo stalks with visible nodes,
         narrow bamboo leaves rustling, bamboo shoots on ground...
学习要点：竹 (zhú) - bamboo
科学：竹子是草本植物，生长快，有节状结构
验证报告：✅ MEDIUM validation, 特别注意：避免树木术语
```

---

### 测试案例 3：小溪 (Stream)

**输入**：
```
/picture-book-wizard watercolor 小溪 6 theme:nature
```

**预期处理**：
```
1. 识别："小溪"不在核心场景
2. 分类：水域类
3. 匹配：pond (70%)
4. 验证等级：MEDIUM
5. 关键差异：
   - 小溪：流动水
   - 水潭：静止水
6. 调整建议：
   - 添加：流动效果、溪流声、鹅卵石
   - 移除：静止倒影（改为扭曲倒影）
7. 用户确认
```

**预期输出特征**：
```
故事：悦悦在小溪边发现清澈的溪水缓缓流淌...
提示词：...flowing stream, clear water over pebbles,
         gentle water movement, distorted reflections in ripples...
学习要点：水 (shuǐ) - water
科学：流动的水不能形成清晰倒影
验证报告：✅ MEDIUM validation, 已调整：流动 vs. 静止水特性
```

---

### 测试案例 4：沙漠 (Desert) - 低匹配度警告

**输入**：
```
/picture-book-wizard clay 沙漠 9 theme:exploration
```

**预期处理**：
```
1. 识别："沙漠"不在核心场景
2. 分类：特殊环境
3. 匹配：meadow (35%) - 相似度低
4. 警告：
   ⚠️ 沙漠环境与所有核心场景差异较大
   ⚠️ 可观察元素完全不同
   ⚠️ 验证等级：LOW
5. 建议选项：
   [a] 使用 meadow 作为基础（大量调整）
   [b] 使用自定义场景（低验证）
   [c] 改用核心场景（高验证）
```

**用户确认后**：
```
如果选择 [b] 自定义场景：

⚠️ 自定义场景警告：
- 验证等级：LOW（仅通用物理和生物规则）
- 无详细可观察元素数据库
- 需要您自行判断科学准确性
- 建议：请在使用前向领域专家确认内容

是否继续？ [确认] [取消]
```

---

### 测试案例 5：海底 (Underwater) - 不推荐场景

**输入**：
```
/picture-book-wizard tech 海底 8
```

**预期处理**：
```
1. 识别："海底"不在核心场景
2. 分类：极端环境
3. 匹配：无合适匹配
4. 警告：
   ⚠️ 极端环境警告

   海底环境不适合儿童绘本的原因：
   - 物理规则完全不同（水压、浮力、光线）
   - 儿童无法亲身体验（安全隔绝）
   - 观察限制极大（设备依赖）
   - 可能引起恐惧（黑暗、未知）

   建议替代：
   • pond (水潭) - 浅水观察，安全友好
   • 水族馆场景（自定义）- 室内安全环境

   如果仍要生成海底场景：
   - 验证等级：VERY LOW
   - 仅适用于想象/幻想主题
   - 不作为科学教育内容

是否继续？ [取消] [了解风险后继续]
```

---

### 测试案例 6：教室 (Classroom)

**输入**：
```
/picture-book-wizard storybook 教室 5 theme:friendship
```

**预期处理**：
```
1. 识别："教室"不在核心场景
2. 分类：室内类
3. 匹配：kindergarten (90%) - 高度相似
4. 验证等级：MEDIUM-HIGH
5. 调整建议：
   - 年龄调整：幼儿园 → 小学教室
   - 家具尺寸：更大的桌椅
   - 教学内容：更复杂的海报和教材
6. 用户确认
```

**预期输出**：
```
故事：悦悦在教室里和同学分享她的图画书...
提示词：...elementary school classroom, rows of desks,
         educational posters on walls, children aged 5-6...
验证报告：✅ MEDIUM-HIGH validation（与核心场景极相似）
```

---

## V. 验证等级定义 / Validation Levels

### HIGH Validation（核心12场景）

**特征**：
- ✅ 完整的可观察元素数据库
- ✅ 详细的常见错误列表
- ✅ 场景特定的40+红旗模式
- ✅ 年龄分组的观察能力
- ✅ 所有四层验证规则

**适用**：
- meadow, pond, rice-paddy, stars, forest
- kitchen, courtyard, market, temple, festival, grandma-room, kindergarten

**质量保证**：错误预防率 >90%

---

### MEDIUM Validation（匹配场景）

**特征**：
- ✅ 通用物理和生物规则（层级1）
- ✅ 场景类别规则（层级2）
- ✅ AI推理的可观察元素
- ⚠️ 场景特定规则由AI生成
- ⚠️ 用户需要确认调整建议

**适用**：
- 相似度 >60% 的匹配场景
- 例如：高原→meadow, 竹林→forest, 小溪→pond

**质量保证**：错误预防率 ~70%，依赖AI推理准确性

---

### LOW Validation（自定义场景）

**特征**：
- ✅ 通用物理和生物规则（层级1）
- ❌ 无场景类别规则
- ❌ 无详细可观察元素数据库
- ⚠️ 用户自行负责科学准确性

**适用**：
- 相似度 <60% 的场景
- 例如：沙漠、海滩（与核心场景差异大）

**质量保证**：错误预防率 ~40%，主要依赖用户判断

**警告提示**：
```
⚠️ LOW VALIDATION WARNING

此场景使用低等级验证，仅检查基本物理和生物规则。
建议在发布前请领域专家审核科学准确性。

[我理解风险] [返回选择核心场景]
```

---

### VERY LOW / NOT RECOMMENDED（极端环境）

**特征**：
- ⚠️ 仅基础规则
- ⚠️ 可能不适合儿童内容
- ⚠️ 强烈建议改用其他场景

**适用**：
- 海底、太空、火山内部、洞穴（黑暗）
- 危险或恐惧场景

**警告提示**：
```
🚫 NOT RECOMMENDED FOR CHILDREN'S CONTENT

此场景可能不适合儿童绘本：
- 物理环境极端或危险
- 儿童无法亲身体验
- 可能引起恐惧或焦虑

强烈建议使用核心场景或适合儿童的替代场景。

[了解风险后继续] [取消]
```

---

## VI. 实现优先级 / Implementation Priority

### Phase 1: 核心功能（立即实现）
- ✅ 场景分类系统（7大类别）
- ✅ 相似度匹配算法
- ✅ 验证等级定义
- ✅ 用户确认流程
- ✅ 6个测试案例

### Phase 2: 优化体验（后续）
- 多语言场景名称识别
- 自动学习用户偏好
- 匹配建议优化

### Phase 3: 高级功能（长期）
- 常用自定义场景记录
- 社区贡献场景库
- 动态验证规则生成

---

## VII. 总结 / Summary

**核心优势**：
✅ 保持12个核心场景配置精简
✅ 支持无限扩展场景需求
✅ 维持现实验证系统完整性
✅ 分层验证策略（HIGH/MEDIUM/LOW）
✅ 透明的质量保证等级
✅ 用户知情选择权

**质量保证**：
- 核心场景：>90% 错误预防
- 匹配场景：~70% 错误预防（AI推理）
- 自定义场景：~40% 错误预防（用户自负责）
- 极端环境：建议不使用

**用户体验**：
- 清晰的匹配建议
- 透明的调整说明
- 明确的验证等级
- 风险警告（低匹配度场景）

---

**文件版本**: 1.0
**创建日期**: 2026-01-10
**状态**: 准备测试和验证


path: references/config/advanced/scenes-chinese-culture.md
content: # Child-Centered Scenes Expansion

## New Scenes Based on Child Psychology and Chinese Culture

This document adds scenes that resonate with Chinese children's daily experiences and psychological development needs (3-6 years).

---

### 6. Home Kitchen (厨房) - `kitchen`

**Environment**: Warm家庭厨房 with cooking activities

**Visual Elements**:
- Warm wooden or tiled kitchen space
- Steaming woks and cooking utensils
- Fresh vegetables and ingredients
- Family cooking together atmosphere
- Traditional Chinese kitchen items (竹蒸笼, 菜刀, 砧板)

**Atmosphere**:
- Warm and familial
- Busy but organized
- Aromatic and inviting
- Eye-level child perspective

**Educational Focus**:
- Family bonds and cooperation
- Food preparation and nutrition
- Cultural cuisine appreciation
- Responsibility and helping

**Suggested Chinese Characters**:
- 饭 (fàn) - rice/meal
- 菜 (cài) - vegetable/dish
- 锅 (guō) - pot/wok
- 香 (xiāng) - fragrant
- 热 (rè) - hot

**Scene-Specific Details**:
```
warm home kitchen, steaming wok with aromatic food, fresh vegetables on wooden cutting board, traditional Chinese kitchen tools, cozy family cooking atmosphere, warm lighting from above
```

**Child Psychology**:
- **Security (安全感)**: Home environment, family presence
- **Participation (参与感)**: Helping adults, learning life skills
- **Sensory Learning**: Smell, sight, sound of cooking
- **Cultural Connection**: Traditional Chinese food culture

---

### 7. Courtyard/Siheyuan (四合院) - `courtyard`

**Environment**: Traditional Chinese courtyard with cultural elements

**Visual Elements**:
- Square courtyard with sky opening above
- Traditional Chinese architecture elements
- Potted plants and small garden
- Stone pathways and wooden structures
- Lanterns and traditional decorations
- Goldfish pond (optional)

**Atmosphere**:
- Peaceful and enclosed
- Culturally rich
- Safe and intimate
- Multi-generational warmth

**Educational Focus**:
- Traditional Chinese architecture
- Family living together (三代同堂)
- Outdoor-indoor connection
- Cultural heritage

**Suggested Chinese Characters**:
- 院 (yuàn) - courtyard
- 家 (jiā) - home/family
- 门 (mén) - door/gate
- 灯 (dēng) - lantern/light
- 花 (huā) - flower

**Scene-Specific Details**:
```
traditional Chinese courtyard, enclosed square space with sky above, red lanterns hanging, potted plants, stone pathways, wooden pillared structures, peaceful family atmosphere
```

**Child Psychology**:
- **Belonging (归属感)**: Extended family environment
- **Cultural Roots**: Connection to Chinese tradition
- **Safe Exploration**: Enclosed but spacious
- **Multi-sensory**: Architecture, nature, family life

---

### 8. Street Market (市场) - `market`

**Environment**: Bustling traditional Chinese street market

**Visual Elements**:
- Colorful vendor stalls with fresh produce
- Hanging lanterns and signs with characters
- People shopping and vendors calling
- Fresh fruits, vegetables, fish in baskets
- Traditional market architecture
- Red and gold decorative elements

**Atmosphere**:
- Lively and energetic
- Colorful and abundant
- Social and interactive
- Ground-level bustling activity

**Educational Focus**:
- Social interaction and community
- Numbers and counting (buying/selling)
- Food names and varieties
- Daily life observation

**Suggested Chinese Characters**:
- 买 (mǎi) - buy
- 卖 (mài) - sell
- 钱 (qián) - money
- 多 (duō) - many/much
- 少 (shǎo) - few/little

**Scene-Specific Details**:
```
bustling Chinese street market, colorful vendor stalls with fresh produce, hanging red lanterns, Chinese character signs, baskets of fruits and vegetables, lively crowd atmosphere, warm daylight
```

**Child Psychology**:
- **Social Learning**: Observing interactions
- **Sensory Richness**: Colors, sounds, smells
- **Real-world Math**: Counting, comparing
- **Cultural Daily Life**: Authentic Chinese experience

---

### 9. Temple/Pagoda (寺庙) - `temple`

**Environment**: Peaceful Chinese Buddhist temple or pagoda

**Visual Elements**:
- Traditional curved rooftops with upturned eaves
- Red pillars and golden accents
- Incense smoke rising gently
- Stone lion statues or guardians
- Peaceful courtyard with trees
- Prayer bells and decorative elements

**Atmosphere**:
- Serene and reverent
- Spiritually peaceful
- Architecturally magnificent
- Quiet and contemplative

**Educational Focus**:
- Cultural and spiritual heritage
- Respect and reverence (尊重)
- Traditional architecture appreciation
- Quietness and contemplation

**Suggested Chinese Characters**:
- 庙 (miào) - temple
- 塔 (tǎ) - pagoda/tower
- 香 (xiāng) - incense
- 钟 (zhōng) - bell
- 静 (jìng) - quiet/peaceful

**Scene-Specific Details**:
```
traditional Chinese temple, curved upturned roof eaves, red pillars with golden details, gentle incense smoke rising, stone lion guardians, peaceful courtyard with ancient trees, serene atmosphere
```

**Child Psychology**:
- **Quiet Time**: Learning to be calm and peaceful
- **Awe and Wonder**: Impressive architecture
- **Respect**: Cultural and spiritual respect
- **Cultural Heritage**: Connection to traditions

---

### 10. Festival Celebration (节日庆典) - `festival`

**Environment**: Joyful Chinese festival celebration scene

**Visual Elements**:
- Red lanterns hanging everywhere
- Decorative couplets (春联) on doors
- Firecrackers and festive decorations
- Special festival foods displayed
- People in festive clothing
- Vibrant red and gold colors

**Atmosphere**:
- Joyful and celebratory
- Crowded but happy
- Colorful and decorated
- Festive energy and excitement

**Educational Focus**:
- Chinese festivals and traditions
- Celebration and joy
- Family gathering importance
- Cultural customs and meanings

**Suggested Chinese Characters**:
- 节 (jié) - festival/holiday
- 庆 (qìng) - celebrate
- 红 (hóng) - red
- 福 (fú) - fortune/blessing
- 灯 (dēng) - lantern

**Scene-Specific Details**:
```
Chinese festival celebration, countless red lanterns hanging, spring couplets on doors, festive decorations, joyful crowd, traditional festival foods, vibrant red and gold colors, celebratory atmosphere
```

**Child Psychology**:
- **Joy and Excitement**: High positive emotion
- **Family Bonding**: Gathering and celebration
- **Cultural Pride**: Participating in traditions
- **Anticipation**: Festival excitement and rituals

---

### 11. Grandmother's Room (奶奶的房间) - `grandma-room`

**Environment**: Warm, traditional elderly Chinese woman's bedroom

**Visual Elements**:
- Comfortable traditional Chinese furniture
- Embroidered pillows and quilts
- Family photos on walls
- Traditional tea set
- Warm wooden tones
- Soft ambient lighting

**Atmosphere**:
- Cozy and nostalgic
- Safe and loving
- Quiet and gentle
- Inter-generational warmth

**Educational Focus**:
- Family relationships (祖孙情)
- Respect for elders
- Traditional crafts (embroidery)
- Stories and wisdom sharing

**Suggested Chinese Characters**:
- 奶 (nǎi) - grandmother (paternal)
- 爱 (ài) - love
- 老 (lǎo) - old/elderly
- 讲 (jiǎng) - tell/speak
- 听 (tīng) - listen

**Scene-Specific Details**:
```
warm traditional Chinese elder's room, comfortable wooden furniture, embroidered quilts and pillows, family photos on wall, traditional tea set, soft warm lighting, cozy nostalgic atmosphere
```

**Child Psychology**:
- **Emotional Security**: Grandparent love
- **Storytelling**: Oral tradition and listening
- **Patience**: Slower pace, quiet time
- **Generational Bonding**: Learning from elders

---

### 12. Kindergarten Classroom (幼儿园) - `kindergarten`

**Environment**: Bright, colorful Chinese kindergarten classroom

**Visual Elements**:
- Small desks and chairs
- Colorful educational posters with characters
- Toy shelves and learning materials
- Children's artwork displayed
- Alphabet and number charts
- Bright primary colors

**Atmosphere**:
- Bright and cheerful
- Organized but playful
- Social and interactive
- Learning-focused

**Educational Focus**:
- Social skills and friendship
- Learning environment familiarization
- Sharing and cooperation
- Early education concepts

**Suggested Chinese Characters**:
- 学 (xué) - learn/study
- 友 (yǒu) - friend
- 玩 (wán) - play
- 画 (huà) - draw/paint
- 唱 (chàng) - sing

**Scene-Specific Details**:
```
bright Chinese kindergarten classroom, small child-sized furniture, colorful educational posters with Chinese characters, toy shelves, children's artwork on walls, alphabet charts, cheerful learning atmosphere
```

**Child Psychology**:
- **Peer Interaction**: Social skill development
- **Learning Readiness**: Positive school associations
- **Autonomy**: Independent in classroom setting
- **Structured Play**: Balancing rules and creativity

---

## Scene Compatibility with Styles

| Scene | Clay | Tech | Ink | Paper-Cut | Nianhua | Porcelain | Shadow |
|-------|------|------|-----|-----------|---------|-----------|--------|
| Kitchen | ⭐⭐⭐ | ⭐ | ⭐⭐ | ⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
| Courtyard | ⭐⭐⭐ | ⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| Market | ⭐⭐⭐ | ⭐ | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
| Temple | ⭐⭐ | ⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| Festival | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
| Grandma Room | ⭐⭐⭐ | ⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
| Kindergarten | ⭐⭐⭐ | ⭐⭐ | ⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐ | ⭐ |

---

## Child Development Alignment

### Emotional Development (情感发展)

**Security and Attachment** (安全感与依恋):
- Kitchen, Grandma Room, Courtyard, Kindergarten

**Social Skills** (社交能力):
- Market, Festival, Kindergarten

**Cultural Identity** (文化认同):
- Temple, Courtyard, Festival, Market

### Cognitive Development (认知发展)

**Observation Skills** (观察力):
- Market (variety), Temple (details), Kindergarten (organization)

**Categorization** (分类能力):
- Kitchen (food types), Market (vendor categories)

**Spatial Awareness** (空间意识):
- Courtyard (enclosed space), Temple (architecture)

### Moral Development (道德发展)

**Respect** (尊重):
- Temple (reverence), Grandma Room (filial piety)

**Sharing and Cooperation** (分享与合作):
- Kitchen (helping), Kindergarten (playing together)

---

## Integration with Existing Scenes

### Complete Scene Library (12 Scenes)

**Nature Scenes** (自然场景):
1. Meadow (草地)
2. Pond (水潭)
3. Rice Paddy (水稻田)
4. Forest (森林)
5. Stars (星空)

**Cultural & Daily Life Scenes** (文化与生活场景):
6. Kitchen (厨房)
7. Courtyard (四合院)
8. Market (市场)
9. Temple (寺庙)
10. Festival (节日)
11. Grandma Room (奶奶房间)
12. Kindergarten (幼儿园)

This creates a balanced mix of:
- Nature (5 scenes) - for wonder and exploration
- Culture (7 scenes) - for identity and daily life

---

## Usage Recommendations

### Age 3-4 (最适合3-4岁):
- Kitchen, Grandma Room, Kindergarten (familiar, safe)
- Meadow, Pond (simple, clear nature)

### Age 4-5 (最适合4-5岁):
- Market, Festival (more stimulation, social)
- Forest, Rice Paddy (more complex nature)
- Courtyard (cultural understanding emerging)

### Age 5-6 (最适合5-6岁):
- Temple (contemplative capacity developing)
- All scenes (full range accessible)
- Multi-page stories across multiple scenes

---

## Cultural Education Goals

By including these scenes, children learn:
1. **Daily Life** (日常生活): Kitchen, Market
2. **Architecture** (建筑): Courtyard, Temple
3. **Traditions** (传统): Festival, Temple, Grandma Room
4. **Social Environments** (社交环境): Market, Kindergarten
5. **Family Bonds** (家庭纽带): Kitchen, Courtyard, Grandma Room

This comprehensive scene library supports both **nature exploration** and **cultural immersion** for holistic child development.


path: references/config/merged/examples-index.yaml
content: version: '1.0'
description: 示例文件索引 - 按需加载
total_files: 10
examples:
- name: clay-meadow
  file: clay-meadow.md
  size_kb: 1.9248046875
  headers:
  - 'Example: Clay Style Meadow Scene'
  - Notes on This Example
  description: ''
- name: clay-forest-xiaoming
  file: clay-forest-xiaoming.md
  size_kb: 9.14453125
  headers:
  - 'Example: Clay Forest Scene with Xiaoming Character'
  - Example Analysis
  - Why This Combination Works
  - Character-Specific Elements
  - Comparison with Yueyue in Same Scene
  description: ''
- name: clay-pond-reflection-optimized
  file: clay-pond-reflection-optimized.md
  size_kb: 8.5068359375
  headers:
  - 'Example: Clay Pond Scene with Optimized Reflection'
  - Optimization Analysis
  - Key Reflection Keywords Added
  - Keyword Placement Strategy
  - 'Comparison: Before vs After'
  description: ''
- name: nianhua-kitchen
  file: nianhua-kitchen.md
  size_kb: 12.236328125
  headers:
  - 'Example: Nianhua Kitchen Scene'
  - Example Analysis
  - Why This Combination Works
  - 'Style-Scene Compatibility: ⭐⭐⭐ Excellent'
  - Key Prompt Elements
  description: ''
- name: tech-stars
  file: tech-stars.md
  size_kb: 2.3515625
  headers:
  - 'Example: Tech Style Stars Scene'
  - Notes on This Example
  description: ''
- name: paper-cut-festival
  file: paper-cut-festival.md
  size_kb: 10.0693359375
  headers:
  - 'Example: Paper-Cut Festival Scene'
  - Example Analysis
  - Why This Combination Works
  - 'Style-Scene Compatibility: ⭐⭐⭐ Excellent'
  - Key Prompt Elements
  description: ''
- name: nianhua-kitchen-xiaoming-3pages-complete
  file: nianhua-kitchen-xiaoming-3pages-complete.md
  size_kb: 11.3515625
  headers:
  - Making Dumplings Together / 一起包饺子
  - Page 1 / 第一页
  - Page 2 / 第二页
  - Page 3 / 第三页
  - 📚 故事总结 / Story Summary
  description: ''
- name: clay-meadow-3pages
  file: clay-meadow-3pages.md
  size_kb: 6.9384765625
  headers:
  - 'Example: 3-Page Clay Meadow Story - Seed Growth'
  - === Page 1/3 ===
  - === Page 2/3 ===
  - === Page 3/3 ===
  - '📚 故事总结 / Story Summary:'
  description: ''
- name: multi-character-usage-examples
  file: multi-character-usage-examples.md
  size_kb: 26.6064453125
  headers:
  - Multi-Character Usage Examples
  - Table of Contents
  - Family Character Examples
  - 'Example 1: Grandma + Child (Kitchen Scene)'
  - 'Example 2: Dad + Child (Outdoor Adventure)'
  description: ''
- name: ink-forest
  file: ink-forest.md
  size_kb: 2.8134765625
  headers:
  - 'Example: Ink Style Forest Scene'
  - Notes on This Example
  description: ''


path: references/examples/clay-meadow.md
content: # Example: Clay Style Meadow Scene

**Configuration**: `clay` + `meadow`

---

📖 **故事 / Story:**
悦悦在草地上发现了一颗小种子。
Yueyue found a tiny seed on the meadow.

---

🔤 **拼音 / Pinyin:**
Yuèyuè zài cǎodì shàng fāxiànle yī kē xiǎo zhǒngzi.

---

✨ **学习要点 / Learning Point:**
草 (cǎo) - grass

---

🎨 **Banana Nano Prompt:**
A 5-year-old Chinese girl named Yueyue, round face, rosy cheeks, two pigtails with red ribbons, wearing yellow sweater and denim overalls, kneeling on lush green grass meadow, discovering a tiny seed in her palm, hand-sculpted claymation style, physical clay textures with visible fingerprints, tiny hand-pressed wildflowers scattered around in pink, yellow, and white, soft warm studio lighting, octane render, macro texture details showing clay grain, 8k resolution, warm color grading, ground-level perspective, warm and inviting atmosphere.

---

## Notes on This Example

**Why This Combination Works**:
- Clay style provides warm, tactile quality perfect for nature scenes
- Meadow setting is grounded and relatable for young children
- Discovery action encourages curiosity and exploration
- Grass character (草) is fundamental and visually present in scene

**Character Learning**:
- 草 is a basic HSK 1 level character
- The radical 艹 (grass radical) is visible and learnable
- Pronunciation is simple (cǎo - third tone)
- Concept directly matches visual scene

**Technical Highlights**:
- "Kneeling" pose makes Yueyue interactive with environment
- "In her palm" creates intimate discovery moment
- Specific flower colors add visual interest
- Ground-level perspective enhances immersion

**Variations You Could Make**:
- Change time of day: "morning dew on grass" or "golden afternoon light"
- Change action: "running through" instead of "kneeling on"
- Add elements: "butterfly landing nearby" or "ladybug on leaf"
- Adjust mood: "excited expression" vs "gentle smile"


path: scripts/README.md
content: # Scripts Directory

Utility scripts for managing the Picture Book Wizard skill documentation.

## Available Scripts

### doc-stats.sh
文档统计脚本 - 显示文档数量、行数分布、最大文件等信息。

```bash
./doc-stats.sh
```

**输出**:
- 总文件数和行数
- 按目录统计
- 最大的 10 个文件
- 中英文重复文件检测

### cleanup-duplicates.sh
清理重复文档脚本 - 删除中英文重复版本和冗余文件。

```bash
# 预览模式 (不实际删除)
./cleanup-duplicates.sh --dry-run

# 执行删除
./cleanup-duplicates.sh
```

**删除内容**:
- 中文版本文档 (保留英文版)
- 冗余的 usage-guide (SKILL.md 已包含核心内容)

## Usage

```bash
cd .claude/skills/picture-book-wizard/scripts
./doc-stats.sh
```

## Notes

- 所有脚本需要在 scripts 目录下运行
- 使用 `--dry-run` 参数可以预览操作而不实际执行


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)