# 童绘造梦工厂 / picturebook-story-maker

> **一句话**：面向1-6岁宝宝家长的个性化绘本生成 Skill，支持交互式信息收集、故事/科普/混合模式、角色一致性锚定、分镜自检、关键帧、HTML/PDF/配音视频脚本产出。

---

## 🎯 Skill 定位

| 维度 | 说明 |
|------|------|
| 目标用户 | 1-6岁宝宝家长（非专业设计人员） |
| 核心场景 | 家长输入宝宝信息→Skill 生成专属绘本→宝宝翻阅/聆听 |
| 模式 | 故事模式 / 科普模式 / 混合模式（用户可选） |
| 角色一致性 | 每个故事锁定1-2个"角色圣经"锚点，确保视觉风格一致 |
| 分镜自检 | 每页自动评分，≥90 分才进入下一阶段 |
| 输出格式 | HTML（可交互翻页）、PDF（打印级）、配音视频脚本（可选） |

---

## 📐 7阶段工作流

### 阶段1：信息收集（Info Collection）

**目标**：收集宝宝档案的22个字段，为个性化故事提供数据基础。

| # | 字段 | 说明 | 示例 |
|---|------|------|------|
| 1 | `child_name` | 宝宝姓名 | "小明" |
| 2 | `child_age` | 宝宝年龄（岁） | 4 |
| 3 | `child_gender` | 宝宝性别 | "男" |
| 4 | `child_photo` | 宝宝照片（文件路径或URL） | `~/photos/ming.jpg` |
| 5 | `favorite_animal` | 最喜欢的动物 | "恐龙" |
| 6 | `favorite_color` | 最喜欢的颜色 | "蓝色" |
| 7 | `favorite_food` | 最喜欢的食物 | "草莓" |
| 8 | `hobby` | 爱好 | "画画" |
| 9 | `birth_month` | 出生月份 | "5月" |
| 10 | `birth_season` | 出生季节 | "初夏" |
| 11 | `parent_name` | 家长姓名 | "李华" |
| 12 | `parent_role` | 家长角色描述 | "温柔引导的爸爸" |
| 13 | `story_theme` | 故事主题（如"友谊"/"勇气"/"成长"） | "友谊" |
| 14 | `story_mode` | 故事模式（`story`/`science`/`hybrid`） | `story` |
| 15 | `style` | 绘本画风 | "水彩" |
| 16 | `pages` | 页数 | 12 |
| 17 | `character_consistency` | 角色一致性锚定 | true |
| 18 | `story_length` | 故事长度（短/中/长） | "中" |
| 19 | `interaction` | 互动元素（翻翻页/触摸区/音频按钮） | "翻翻页" |
| 20 | `output_format` | 输出格式（`html`/`pdf`/`video`） | `html` |
| 21 | `voiceover` | 是否配音 | false |
| 22 | `video_script` | 是否生成视频脚本 | false |

**交互逻辑**：

```
[开始] → [阶段1: 信息收集]
         ↓
   收集22个字段
         ↓
   [阶段2: 故事创作]
```

---

### 阶段2：故事创作（Story Creation）

根据 `story_mode` 选择创作路径：

| `story_mode` | 创作路径 |
|---|---|
| `story` | 纯故事创作，每页≤50字 |
| `science` | 科普故事，每页≤50字 + 1个科普知识点 |
| `hybrid` | 故事 + 科普混合 |

**角色锚定**：
- 锁定1-2个"角色圣经"锚点（如：主角外貌、标志性服装、口头禅）
- 所有后续故事均沿用这些锚点，确保视觉一致性

---

### 阶段3：分镜规划（Storyboard）

**规则**：
- 每页分镜评分 **≥ 90** 方可进入下一阶段
- 评分 < 90，需重新规划分镜

**分镜评分维度**：

| 维度 | 权重 | 评分标准 |
|------|------|----------|
| 构图 | 40% | 0-100 |
| 角色表现力 | 30% | 0-100 |
| 文图匹配度 | 20% | 0-100 |
| 互动元素 | 10% | 0-100 |

---

### 阶段4：关键帧生成（Keyframe Generation）

为每页生成1-2个关键帧，用于：

1. 视觉节奏控制
2. 翻页时的动态效果（如：淡入淡出、滑动）
3. 互动热点定位

**关键帧格式**：

```json
{
  "page": 1,
  "keyframes": [
    {
      "frame_id": "kf_1_1",
      "description": "主角初登场，特写镜头",
      "camera": "close-up",
      "animation": "fade-in",
      "interaction": "tap-glow"
    }
  ]
}
```

---

### 阶段5：HTML 生成（HTML Generation）

生成可交互翻页的 HTML 绘本页面：

```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>童绘造梦工厂</title>
  <!-- 翻页动画 CSS -->
  <style>
    .page { display: none; }
    .page.active { display: block; }
    /* 翻页动画 */
    @keyframes page-turn {
      from { transform: perspective(800px) rotateY(0deg); }
      to { transform: perspective(800px) rotateY(-180deg); }
    }
    .page-turn { animation: page-turn 0.8s ease-in-out; }
  </style>
</head>
<body>
  <div class="page active">第1页内容</div>
  <div class="page">第2页内容</div>
</body>
</body>
</html>
```

---

### 阶段6：PDF 生成（PDF Generation）

可选，生成打印级 PDF：

```python
# scripts/pdf_book.py
from weasyprint import HTML

class PDFBook:
    def __init__(self, html_file, output_pdf):
        self.html_file = html_file
        self.output_pdf = output_pdf

    def generate(self):
        html = HTML(filename=self.html_file)
        html.write_pdf(self.output_pdf)
```

---

### 阶段7：配音视频脚本（Voiceover Script）

可选，生成配音脚本：

```json
{
  "page": 1,
  "voiceover": "在一片绿色的草地上，小{child_name}发现了一只小{favorite_animal}。",
  "pause_points": ["草地上", "小{favorite_animal}"],
  "emphasis": ["发现", "小{favorite_animal}"],
  " pacing": "slow"
}
```

---

## 🚀 快速开始

### 安装

```bash
# 克隆仓库
git clone https://github.com/your-org/picturebook-story-maker.git
cd picturebook-story-maker
```

### 运行 Demo

```bash
# 安装依赖
pip install -r requirements.txt

# 生成绘本（故事模式）
python -m picturebook_story_maker --mode story --child_name "小明" --favorite_animal "恐龙" --favorite_color "蓝色" --favorite_food "草莓" --hobby "画画" --birth_month "5月" --birth_season "初夏" --parent_name "李华" --parent_role "温柔引导的爸爸" --story_theme "友谊" --style "水彩" --pages 12 --character_consistency --story_length "中" --interaction "翻翻页" --output_format "html"
```

---

### Docker

```bash
docker build -t picturebook-story-maker .
docker run -it picturebook-story-maker python -m picturebook_story_maker --mode story
```

---

## 📂 项目结构

```text
picturebook-story-maker/
├── SKILL.md                  # 本文件
├── references/               # 参考文档
│   ├── workflow.md            # 工作流详解
│   ├── input_design.md        # 输入设计
│   ├── science_story.md       # 科普故事模板
│   ├── visual_prompting.md    # 视觉提示词模板
│   └── demo_script.md         # 演示脚本
├── templates/                # HTML 模板
│   ├── input_form.html        # 交互表单
│   └── story_html.py          # 故事 HTML 生成器
├── scripts/                  # 辅助脚本
│   ├── pdf_book.py            # PDF 生成
│   ├── voiceover.py           # 配音生成
│   └── video_compose.py       # 视频合成
└── samples/                  # 示例
    └── pullback-car-demo/     # 回力车 demo
        ├── profile/            # 宝宝档案
        ├── story/              # 故事
        ├── character_bible/    # 角色圣经
        ├── storyboard/         # 分镜
        ├── race_track/         # 竞赛轨迹
        ├── keyframes/          # 关键帧 (JPG)
        ├── keyframes_original/ # 原始关键帧 (PNG)
        └── output/             # 输出目录
            ├── story.html      # 故事 HTML
            └── refs/           # 空目录（存放参考资料）
```

---

## 🔧 扩展与定制

### 添加新故事模式

```python
# story_mode.py
from enum import Enum

class StoryMode(Enum):
    STORY = "story"           # 纯故事
    SCIENCE = "science"       # 科普
    HYBRID = "hybrid"         # 故事 + 科普

    @property
    def description(self):
        if self == StoryMode.STORY:
            return "纯故事创作"
        elif self == StoryMode.SCIENCE:
            return "科普故事，每页≤50字 + 1个科普知识点"
        else:
            return "故事 + 科普混合"

    def get_story_template(self):
        if self == StoryMode.STORY:
            return "每页≤50字"
        elif self == StoryMode.SCIENCE:
            return "每页≤50字 + 1个科普知识点"
        else:
            return "故事 + 科普混合"
```

---

### 添加新输出格式

```python
# output_format.py
from enum import Enum

class OutputFormat(Enum):
    HTML = "html"
    PDF = "pdf"
    VIDEO = "video"

    def get_output_command(self):
        if self == OutputFormat.HTML:
            return "生成可交互翻页的 HTML 绘本页面"
        elif self == OutputFormat.PDF:
            return "生成打印级 PDF"
        elif self == OutputFormat.VIDEO:
            return "生成配音视频脚本"
```

---

## 📝 配置

在 `config.yaml` 中配置：

```yaml
story_mode: story  # story / science / hybrid
style: watercolor  # 水彩画风
pages: 12
character_consistency: true  # 角色一致性锚定
interaction: flip-flap  # 翻翻页 / touch-area 触摸区 / audio-button 音频按钮
output_format: html  # html / pdf / video
```

---

## 🤝 参与贡献

1. Fork 本仓库
2. 创建你的 Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit 你的更改 (`git commit -m 'Add some AmazingFeature'`)
4. Push 到 Branch (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
6. 待 CI 通过后 Merge

---

## 📄 License

本项目采用 MIT 开源协议 - 详见 [LICENSE](LICENSE) 文件
