Tech Manga Explainer

用漫画对话形式将复杂技术概念变得通俗易懂。

核心特点

• 目标读者：成年技术学习者、编程新手、想了解技术的非技术人员
• 表达形式：漫画对话，老手带新手，边问边答
• 画风选择：日式漫画、简约线条、赛博朋克、手绘涂鸦
• 角色组合：支持多套角色，默认火影师徒（卡卡西 & 鸣人）
• 适用主题：编程、架构、AI、自动化、云原生、数据库等技术概念

⚠️ 角色一致性规则（重要）

全套漫画必须保持角色外观完全一致。每一页 prompt 都会自动包含完整角色卡。

可选角色组

默认角色卡：火影师徒

卡卡西（Kakashi）- 技术导师

FACE & HEAD:
- Japanese male ninja, around 30 years old, tall and lean
- HAIR: Spiky SILVER/WHITE hair, gravity-defying, pointing up and left
- LEFT EYE: Covered by TILTED forehead protector (hitai-ate)
- RIGHT EYE: Relaxed, half-lidded, slightly bored
- MASK: ALWAYS wearing dark navy blue FACE MASK covering nose and mouth

CLOTHING (NEVER CHANGES):
- HEAD: Konoha forehead protector worn TILTED to cover left eye
- TOP: Green/olive JONIN VEST (flak jacket) with scroll pouches
- UNDER: Dark navy blue long-sleeve shirt with built-in mask
- PANTS: Dark navy blue ninja pants
- SHOES: Standard blue ninja sandals

⚠️ 必须出现的特征：银白刺猬头、遮左眼的护额、深蓝色面罩、绿色马甲、慵懒眼神

鸣人（Naruto）- 热血学习者

FACE & HEAD:
- Japanese male ninja, around 16 years old (Shippuden era)
- HAIR: Bright SPIKY BLONDE/YELLOW hair, messy, sticking out everywhere
- EYES: Big bright BLUE eyes, very expressive
- FACE: THREE WHISKER MARKS on each cheek (6 total)

CLOTHING (NEVER CHANGES - Shippuden outfit):
- HEAD: Konoha forehead protector worn on FOREHEAD (black cloth)
- TOP: Orange and BLACK TRACKSUIT jacket with zipper
- INSIDE: Black t-shirt visible at collar
- PANTS: Orange tracksuit pants
- SHOES: Black ninja sandals
- ACCESSORIES: Small green crystal necklace

⚠️ 必须出现的特征：金色刺猬头、蓝色眼睛、每边脸3道胡须印记、橙黑运动服、正戴护额

备选角色卡：程序员搭档

码叔（Ma Shu）- 技术导师

⚠️ 必须出现的特征：秃顶+两侧有发、银框眼镜、红黑格子衬衫、灰色帽衫堆在脖子后、络腮胡

小新（Xiao Xin）- 技术新手

⚠️ 必须出现的特征：蘑菇头黑发、黑色拉链卫衣敞开、白T恤、灰背包+像素机器人挂件

工作流程

第一步：技术概念分析与页数判断

1. 理解用户想要解释的技术概念
2. 🚨 必须：分析内容复杂度，根据下方标准确定合适的页数（禁止默认6页）
3. 拆解知识点，为每个知识点设计「问-答」对话
4. 确定合适的比喻和类比（可用忍术类比技术概念）

⚠️ 页数判断标准（强制执行）

核心原则：

• ❌ 禁止：不分析内容就默认生成 6 页
• ✅ 必须：先数核心概念数量，再用公式计算页数
• ✅ 必须：在规划中写明「复杂度判断理由」

计算公式：

总页数 = 开头引入(1页) + 核心概念数 × 1.5页 + 结尾总结(1页)

示例：3个核心概念 → 1 + 3×1.5 + 1 = 6.5 → 取整为 6-7 页
示例：7个核心概念 → 1 + 7×1.5 + 1 = 12.5 → 取整为 12-13 页

判断流程（必须执行）：

1. 列出需要解释的核心概念/知识点
2. 数一数有几个核心概念
3. 根据上表确定复杂度和页数范围
4. 在规划中明确写出判断理由

判断示例：

示例1：用户要求「用漫画解释什么是 Pod」

• 核心概念：Pod的定义(1个)
• 判断：简单概念 → 3-4页
• 结构：引入 → Pod概念 → 与Container关系 → 总结

示例2：用户要求「用漫画讲解 Kubernetes 的 Pod、Node、Cluster」

• 核心概念：Pod + Node + Cluster + 三者关系 = 4个概念
• 判断：中等复杂度 → 6-7页
• 结构：引入 → Pod → Node → Cluster → 三者关系 → 实际应用 → 总结

示例3：用户要求「把这篇 Transformer 论文变成漫画」

• 核心概念：注意力机制 + Self-Attention + Multi-Head + Encoder + Decoder + 位置编码 + 训练过程 = 7+个概念
• 判断：复杂内容 → 12-15页
• 结构：引入 → 逐个概念讲解(每个1-2页) → 整体架构 → 应用场景 → 总结

第二步：漫画结构规划

必须先输出规划，等用户确认后再生成图片。

⚠️ 规划硬性要求

1. 禁止合并页数：不能写”第2-3页”，必须每页单独规划
2. 必须包含试错环节：至少有1页是「鸣人犯错→卡卡西纠正」
3. 技术图示必须漫画化：不能写抽象描述，要转化为具体画面

输出规划格式：

## 漫画规划

主题：[技术概念名称]
复杂度判断：[简单/中等/复杂/系统性] - [判断理由]
总页数：[X页]
画风：[manga/minimal/cyberpunk/sketch]
角色组：[naruto/coder] - 默认火影师徒

### 核心比喻
[主比喻] = [忍术/火影世界事物]
理由：[为什么这个比喻合适]
例：Docker = 封印卷轴，把整个环境封印进去，随时随地都能召唤

### 知识点拆解（每个概念单独一行）
1. [知识点1] - 第X页
2. [知识点2] - 第X页
3. 【试错环节】鸣人的理解错误 - 第X页 ← 必须有这一行
4. ...

### 第1页 - 引入问题
- 场景：[具体场景，如：木叶村情报分析室，鸣人对着一堆卷轴抓狂]
- 鸣人：「[用口癖开头，如：可恶！/卡卡西老师！]...」
- 卡卡西：「[用口癖开头，如：嘛嘛...]...」
- 画面要点：[具体视觉元素]

### 第2页 - [知识点1标题]
- 场景：[具体场景]
- 鸣人：「...」
- 卡卡西：「...」
- 技术图示：[漫画化描述，如：卡卡西手持三个卷轴，分别写着Q/K/V，箭头汇聚成发光球]
- 画面要点：[具体视觉元素]

### 第X页 - 鸣人的理解错误【必须有】
- 场景：[鸣人自信尝试的场景]
- 鸣人：「哦！我懂了！就是XXX对吧！（开始乱搞）」
- 卡卡西：「等等...你还没...」
- 画面要点：[失败/爆炸/报错特效]

### 第X+1页 - 卡卡西纠正
- 场景：[卡卡西认真讲解的场景]
- 卡卡西：「不对不对。关键点是...」
- 鸣人：「原来是这样...」
- 技术图示：[正确理解的可视化]
- 画面要点：[对比错误和正确的做法]

### 第N页 - 总结应用
- 场景：[成功场景，如：夕阳下的训练场]
- 鸣人：「哦哦！我懂了！[用自己的话总结，带上忍术类比]」
- 卡卡西：「嘛，差不多是这个意思（翻开小橙书）」
- 画面要点：[成就感、成长氛围]

规划完成后询问用户：

以上是漫画结构规划，共X页（包含1个试错学习环节）。确认无误后我将开始生成图片，或者你可以告诉我需要调整的地方。

第三步：生成漫画图片

使用脚本逐页生成：

# 默认使用卡卡西 & 鸣人
python3 /mnt/skills/user/tech-manga-explainer/scripts/generate_tech_manga.py \
  --style manga \
  --prompt "木叶村训练场，卡卡西在白板前讲解" \
  --dialogue "鸣人:这个 Docker 到底是什么啊！|卡卡西:嘛嘛，你想想忍者出任务时为什么要带卷轴？" \
  --tech-diagram "Docker 容器结构示意图" \
  --output page_01.png

# 使用程序员角色组
python3 /mnt/skills/user/tech-manga-explainer/scripts/generate_tech_manga.py \
  --preset coder \
  --style manga \
  --prompt "办公室场景，码叔在白板前" \
  --dialogue "小新:Pod是什么？|码叔:就像一个集装箱..." \
  --output page_01.png

画风参数

角色组参数

脚本参数

python3 generate_tech_manga.py [选项]

必需参数：
  --prompt       场景描述

核心参数：
  --dialogue     对话内容，格式：角色:内容|角色:内容
  --preset       角色组 [naruto|coder]，默认 naruto（卡卡西&鸣人）
  --style        画风 [manga|minimal|cyberpunk|sketch]，默认 manga
  
可选参数：
  --tech-diagram 需要在画面中展示的技术图示描述
  --output       输出文件名，默认 tech_manga_page.png
  --size         图片尺寸，默认 1024x1024（推荐竖版 768x1024）
  --show-prompt  仅显示提示词，不生成图片
  --list-styles  列出所有可用画风
  --list-presets 列出所有可用角色组

使用示例

示例1：卡卡西 & 鸣人讲解 Docker（默认角色）

# 第1页 - 引入
python3 generate_tech_manga.py \
  --style manga \
  --prompt "木叶村训练场，鸣人在电脑前抓狂，卡卡西慵懒地走过来" \
  --dialogue "鸣人:卡卡西老师！这个 Docker 到底是什么啊！跑了一天都报错！|卡卡西:嘛嘛，别着急。你想想，忍者出任务时为什么要带卷轴？" \
  --output docker_01.png

# 第2页 - 核心比喻
python3 generate_tech_manga.py \
  --style manga \
  --prompt "卡卡西拿出一个卷轴展示，上面画着封印术式" \
  --dialogue "鸣人:因为...可以随时召唤需要的武器？|卡卡西:没错。Docker 就是你的封印卷轴，把整个运行环境封印进去，到哪里都能完美还原" \
  --tech-diagram "卷轴里封印着：代码 + 依赖 + 配置 = 容器" \
  --output docker_02.png

# 第3页 - 理解确认
python3 generate_tech_manga.py \
  --style manga \
  --prompt "鸣人眼睛发光，双手握拳，卡卡西眼神带笑" \
  --dialogue "鸣人:哦！我懂了！这就像我把影分身术封印在卷轴里，走到哪都能用！|卡卡西:差不多是这个意思（翻开小橙书）" \
  --output docker_03.png

示例2：程序员搭档讲解 Kubernetes Pod

python3 generate_tech_manga.py \
  --preset coder \
  --style manga \
  --prompt "办公室场景，小新对着电脑挠头，码叔端着咖啡杯走过来" \
  --dialogue "小新:码叔，这个 Pod 到底是啥？文档看得我头大|码叔:来，我给你打个比方" \
  --output k8s_pod_01.png

示例3：赛博朋克风格讲 AI Agent

python3 generate_tech_manga.py \
  --style cyberpunk \
  --prompt "霓虹灯闪烁的未来城市背景，卡卡西和鸣人站在一个全息投影前" \
  --dialogue "鸣人:AI Agent 和普通聊天机器人有什么区别？|卡卡西:Agent 能自己思考、规划、还能动手干活，就像上忍和下忍的区别" \
  --tech-diagram "Agent 循环图：感知→思考→规划→执行" \
  --output agent_01.png

对话设计技巧

好的技术漫画对话应该：

火影师徒风格（默认）

🎭 角色语言特点（必须遵守）

卡卡西的说话习惯：

• 口癖：「嘛嘛…」「嘛，差不多是这个意思」
• 语气：慵懒、不紧不慢，但关键时刻一针见血
• 特点：喜欢用反问引导思考，偶尔翻小橙书
• 常用句式：
  • 「嘛嘛，别着急。你想想…」
  • 「这就是为什么…（叹气）」
  • 「不对不对，你理解错了。关键是…」
  • 「差不多是这个意思（眼神带笑）」

鸣人的说话习惯：

• 口癖：「我说啊！」「可恶！」「哦哦！我懂了！」
• 语气：热血、冲动、容易激动
• 特点：经常先犯错再理解，喜欢用自己的话总结
• 常用句式：
  • 「卡卡西老师！这个XXX到底是什么啊！」
  • 「可恶！又报错了！」
  • 「等等…我好像有点懂了…就是说…」
  • 「哦！我懂了！这就像XXX！」

📝 对话示例对比

🥷 忍术类比技术概念（推荐映射表）

基础设施类：

架构类：

AI/ML类：

⚠️ 必须包含「试错学习」环节

火影的核心是成长，每个教程都应该有鸣人犯错→被纠正的桥段：

【试错学习模板】

第X页 - 鸣人的理解错误（必须有这一页）
- 场景：鸣人自信地尝试，结果失败
- 鸣人："我懂了！就是XXX对吧！（开始乱搞）"
- 卡卡西："等等...你还没学会基础就..."
- 画面要点：鸣人自信满满 → 爆炸/报错特效

第X+1页 - 卡卡西纠正
- 场景：卡卡西解释正确做法
- 卡卡西："不对不对。你理解错了关键点。XXX不是YYY，而是ZZZ。"
- 鸣人："原来是这样...那应该怎么做？"
- 画面要点：卡卡西认真讲解，鸣人虚心听讲

常见的「犯错点」设计：

1. 把相似概念搞混（Container vs Image）
2. 跳过基础直接上手（不看文档就开干）
3. 字面理解而非本质理解（”注意力”就是”看一遍”）
4. 过度简化（”就是XXX嘛，很简单”）

程序员搭档风格

码叔的说话习惯：

• 语气：耐心、幽默、偶尔自嘲
• 特点：喜欢用生活化比喻，喝咖啡
• 常用句式：「来，我给你打个比方…」「我当年也是这么踩坑的…」

小新的说话习惯：

• 语气：好奇、虚心、偶尔冒傻气
• 特点：认真记笔记，喜欢确认理解
• 常用句式：「所以说…」「等等，让我理一下…」

通用原则

• 每页对话不超过3轮：漫画是视觉媒介，文字太多会挤压画面
• 禁止合并页数：必须每页单独规划，不能写”第2-3页”
• 每个概念至少1页：宁可多拆不要压缩

技术图示设计（漫画化）

技术图示不能太抽象，必须转化为漫画场景：

❌ 错误写法（太抽象）

技术图示：注意力权重计算图（Query, Key, Value）

✅ 正确写法（漫画化）

技术图示：三个鸣人分身分别拿着写有"Q/K/V"的卷轴，
箭头汇聚到中间一个发光的结果球，
旁边标注"注意力分数"

图示漫画化转换表

📦 第四步：生成交互式 HTML 漫画（必须执行）

所有图片生成完成后，必须生成一个交互式 HTML 文件，将所有页面整合成可浏览的漫画教程。

HTML 模板文件

模板文件位于 assets/ 目录：

assets/
├── manga_template.html      # 主模板（完整页面结构，深色技术风格）
├── page_template.html       # 单页模板（循环生成每页）
└── dialogue_template.html   # 对话模板（角色对话块）

模板占位符说明

主模板 manga_template.html：

单页模板 page_template.html：

对话模板 dialogue_template.html：

生成流程

1. 读取 assets/manga_template.html 主模板
2. 对每一页，读取 assets/page_template.html 并填充内容
3. 对每段对话，读取 assets/dialogue_template.html 并填充
4. 将所有页面内容插入主模板的 {{PAGES}} 位置
5. 保存为 [主题]_manga.html

生成要求

1. 文件命名：[主题]_manga.html
2. 图片引用：使用相对路径引用生成的图片
3. 代码高亮：技术术语用 <code> 标签包裹
4. 技术要点：每页的核心知识点单独展示
5. 响应式：确保手机端也能正常浏览

完成提示

生成 HTML 后，告知用户：

✅ 技术漫画已完成！共生成 [N] 张图片和 1 个交互式 HTML 文件。

📁 文件列表：

• page_01.png ~ page_0N.png（漫画图片）
• [主题]_manga.html（交互式漫画，可在浏览器中打开）

💡 提示：将 HTML 文件和所有图片放在同一文件夹，用浏览器打开 HTML 即可阅读完整漫画教程。

依赖

• nanobanana skill（提供 Gemini 图像生成能力）
• Python 3
• 环境变量：通过 nanobanana 配置 GEMINI_API_KEY