tech-manga-explainer

Tech Manga Explainer

Use comic dialogue format to make complex technical concepts easy to understand.

Core Features

• Target Audience: Adult technical learners, programming beginners, non-technical people who want to understand technology
• Expression Format: Comic dialogue, veteran guiding novice, asking and answering along the way
• Art Style Options: Japanese manga, minimalist line art, cyberpunk, hand-drawn doodle
• Character Combinations: Supports multiple character sets, default is Naruto master-apprentice (Kakashi & Naruto)
• Applicable Topics: Technical concepts such as programming, architecture, AI, automation, cloud native, databases, etc.

⚠️ Character Consistency Rules (Important)

The entire comic must maintain completely consistent character appearance. Each page prompt will automatically include the complete character card.

Optional Character Sets

Character Set	Parameter	Mentor	Student	Style Features
Naruto Master-Apprentice	--preset naruto	😷 Kakashi	🍥 Naruto	Passionate training, master-apprentice inheritance, step by step (default)
Programmer Duo	--preset coder	👨‍💻 Ma Shu	🧑 Xiao Xin	Workplace daily life, relaxed and humorous

Default Character Card: Naruto Master-Apprentice

Kakashi - Technical Mentor

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 - Passionate Learner

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道胡须印记、橙黑运动服、正戴护额

Alternative Character Card: Programmer Duo

Ma Shu - Technical Mentor

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

Xiao Xin - Technical Novice

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

Workflow

Step 1: Technical Concept Analysis and Page Count Determination

1. Understand the technical concept the user wants to explain
2. 🚨 Required: Analyze content complexity and determine the appropriate page count according to the criteria below (defaulting to 6 pages is prohibited)
3. Break down knowledge points and design a "question-answer" dialogue for each knowledge point
4. Determine appropriate metaphors and analogies (ninjutsu can be used to analogize technical concepts)

⚠️ Page Count Determination Criteria (Mandatory)

Core Principles：

• ❌ Prohibited: Defaulting to generating 6 pages without analyzing the content
• ✅ Required: First count the number of core concepts, then use the formula to calculate the page count
• ✅ Required: State the "reason for complexity judgment" in the plan

Calculation Formula：

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

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

Complexity	Page Count Range	Number of Core Concepts	Judgment Criteria	Example
Simple	3-4 pages	1-2	Single concept, no need to go deep into principles	"What is an API", "Environment Variables"
Medium	5-8 pages	3-5	Need to explain principles + applications	"Docker Introduction", "What is RAG"
Complex	9-15 pages	6-10	Multiple sub-concepts interrelated	"K8s Architecture Full Explanation", "Transformer Principles"
Systematic	15-25 pages	10+	Complete tutorial or paper interpretation	"Understanding LLM from Scratch", "Complete Paper Interpretation"

Judgment Process (Must Be Executed)：

1. List the core concepts/knowledge points that need to be explained
2. Count how many core concepts there are
3. Determine the complexity and page range based on the table above
4. Clearly write out the reasoning for the judgment in the plan

Judgment Examples：

Example 1: The user requests "Explain what a Pod is with comics"

• Core concept: Definition of Pod (1)
• Judgment: Simple concept → 3-4 pages
• Structure: Introduction → Pod concept → Relationship with Container → Summary

Example 2: The user requests "Explain Kubernetes' Pod, Node, and Cluster with comics"

• Core concepts: Pod + Node + Cluster + relationships among the three = 4 concepts
• Judgment: Medium complexity → 6-7 pages
• Structure: Introduction → Pod → Node → Cluster → relationships among the three → practical application → summary

Example 3: The user requests "Turn this Transformer paper into comics"

• Core concepts: Attention mechanism + Self-Attention + Multi-Head + Encoder + Decoder + positional encoding + training process = 7+ concepts
• Judgment: Complex content → 12-15 pages
• Structure: Introduction → explain each concept one by one (1-2 pages each) → overall architecture → application scenarios → summary

Step 2: Comic Structure Planning

The plan must be output first, and images can only be generated after the user confirms.

⚠️ Hard Requirements for Planning

1. Merging pages is prohibited: You cannot write "pages 2-3"; each page must be planned separately
2. A trial-and-error segment must be included: At least 1 page must be "Naruto makes a mistake → Kakashi corrects him"
3. Technical diagrams must be turned into comics: You cannot write abstract descriptions; they must be transformed into concrete visuals

Output plan format:

## 漫画规划

主题：[技术概念名称]
复杂度判断：[简单/中等/复杂/系统性] - [判断理由]
总页数：[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页 - 总结应用
- 场景：[成功场景，如：夕阳下的训练场]
- 鸣人：「哦哦！我懂了！[用自己的话总结，带上忍术类比]」
- 卡卡西：「嘛，差不多是这个意思（翻开小橙书）」
- 画面要点：[成就感、成长氛围]

After the plan is complete, ask the user：

The above is the comic structure plan, totaling X pages (including 1 trial-and-error learning segment). If confirmed correct, I will begin generating images, or you can tell me what needs to be adjusted.

Step 3: Generate Comic Images

Generate page by page using the script:

# 默认使用卡卡西 & 鸣人
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

Art Style Parameters

Style Code	Style Name	Features	Suitable Themes
manga	Japanese manga	Clear lines, halftone backgrounds, dynamic expressions	General, most recommended
minimal	Minimalist lines	Mainly black and white, minimalist, professional feel	Architecture, process explanation
cyberpunk	Cyberpunk	Neon colors, tech feel, dark tones	AI, cloud native, future technology
sketch	Hand-drawn doodles	Relaxed and casual, like whiteboard drawings	Rapid prototyping, brainstorming

Character Group Parameters

Character Group	Parameters	Features	Dialogue Style
naruto	--preset naruto	Passionate training, master-apprentice inheritance	Naruto asks impulsively, Kakashi answers lazily
coder	--preset coder	Workplace daily life, light and humorous	Shin-chan humbly asks for advice, Uncle Ma patiently explains

Script parameters

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 列出所有可用角色组

Usage examples

Example 1: Kakashi & Naruto explain Docker (default characters)

# 第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

Example 2: Programmer partners explain Kubernetes Pod

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

Example 3: Explaining AI Agent in cyberpunk style

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

Dialogue design tips

Good technical comic dialogue should:

Naruto master-apprentice style (default)

🎭 Character speech traits (must follow)

Kakashi's speech habits:

• Catchphrase: "Well well..." "Well, that's roughly what it means"
• Tone: lazy, unhurried, but hits the nail on the head at critical moments
• Traits: likes to guide thinking with rhetorical questions, occasionally reads Little Orange Book
• Common sentence patterns:
  • "Well well, don't rush. Think about it..."
  • "This is why... (sighs)"
  • "No no, you misunderstood. The key is..."
  • "That's roughly what it means (smiling eyes)"

Naruto's speech habits:

• Catchphrase: "I'm telling you!" "Damn it!" "Oh oh! I get it!"
• Tone: passionate, impulsive, easily excited
• Traits: often makes mistakes before understanding, likes to summarize in his own words
• Common sentence patterns:
  • "Kakashi-sensei! What on earth is this XXX!"
  • "Damn it! Another error!"
  • "Wait... I think I kind of get it... so it's like..."
  • "Oh! I get it! This is like XXX!"

📝 Dialogue example comparison

Scenario	❌ Wrong writing (too formal)	✅ Correct writing (Naruto style)
Question	"May I ask what the definition of Docker is?"	"Kakashi-sensei! What on earth is this Docker! I've been trying all day and still can't get it running!"
Answer	"Docker is a containerization technology"	"Well well, don't rush. Think about it, why do ninjas carry scrolls when going on missions?"
Mistake	"I misunderstood"	"Damn it! I thought I could just copy it directly!"
Correction	"No, it should be like this"	"No no. You're using a genin's method. Watch closely... (forms hand seals with one hand)"
Understanding	"I understand"	"Oh oh! I get it! This is like sealing the Shadow Clone Technique in a scroll!"
Confirmation	"Yes, you understand correctly"	"Well, that's roughly what it means (opens Little Orange Book)"

🥷 Ninjutsu analogies for technical concepts (recommended mapping table)

Infrastructure category:

Technical concept	Ninjutsu analogy	Reason for analogy
Docker	Sealing scroll	Seal the entire environment inside, summon it anytime
Kubernetes	Hokage	Scheduling manages all ninjas (containers) and assigns tasks
Container	Shadow Clone	Multiple copies can be made, each able to work independently
Virtual Machine	Transformation Jutsu	The whole person turns into something else, with high overhead
Image	Original Scroll	Can be copied, but the original stays unchanged

Architecture category:

Technical Concept	Ninjutsu Analogy	Reason for Analogy
API	Summoning Jutsu	Summon other services to help
Microservices	Konoha Twelve	Each has their own specialty, fighting together as a team
Load Balancing	Clone Coordination	Distribute tasks among multiple clones
Cache	Sharingan Memory	Remember it after seeing it once, use it directly next time
Message Queue	Flying Thunder God Mark	Mark it first, teleport later

AI/ML category:

Technical Concept	Ninjutsu Analogy	Reason for Analogy
Attention Mechanism	Byakugan	Observe the relationships among all information simultaneously in 360 degrees
Self-Attention	Byakugan Observing Teammates	Everyone simultaneously observes the status of all teammates
Multi-Head	Shadow Clone Analysis	Multiple clones analyze simultaneously from different angles
Encoder	Yamanaka Clan Mind Reading	Understand the meaning of the input information
Decoder	Sharingan Copying	Generate output based on understanding
Neural Network	Chakra Pathway System	Information flows through the network like chakra
Training	Training	Practice repeatedly until mastered
Overfitting	Only able to deal with one enemy	Training is too narrow, and it fails against a different opponent

⚠️ Must include a "trial-and-error learning" segment

The core of Naruto is growth, and every tutorial should have a scene where Naruto makes a mistake → gets corrected:

【试错学习模板】

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

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

Common "mistake point" designs:

1. Confusing similar concepts (Container vs Image)
2. Skipping the basics and jumping straight in (starting without reading the docs)
3. Literal understanding rather than essential understanding ("attention" is just "taking a look")
4. Oversimplification ("It's just XXX, it's simple")

Programmer partner style

Uncle Ma's speaking habits:

• Tone: patient, humorous, occasionally self-deprecating
• Traits: likes to use everyday analogies, drinks coffee
• Common sentence patterns: "Come, let me give you an analogy..." "I also stepped into this pit back in the day..."

Xiaoxin's speaking habits:

• Tone: curious, humble, occasionally silly
• Traits: takes notes seriously, likes to confirm understanding
• Common sentence patterns: "So that's why..." "Wait, let me sort this out..."

General principles

• Each page has no more than 3 rounds of dialogue: Manga is a visual medium; too much text will squeeze the artwork.
• Do not merge pages: Each page must be planned separately; you cannot write "pages 2-3".
• At least 1 page per concept: Better to split more than to compress.

Technical Diagram Design (Manga-fication)

Technical diagrams cannot be too abstract; they must be transformed into manga scenes:

❌ Incorrect writing (too abstract)

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

✅ Correct writing (manga-fied)

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

Diagram Manga-fication Conversion Table

Abstract Diagram	Manga-fied Description
Architecture diagram (boxes + arrows)	Ninja village map, buildings = components, roads = data flow
Flowchart	Mission scroll, steps represented by ninjutsu hand seals
Neural network diagram	Meridian system diagram, nodes = acupoints, connections = chakra flow
Data flow diagram	Intelligence transmission route, intelligence = data, ninja = processing nodes
Comparison diagram	Genin approach on the left (wrong), jonin approach on the right (correct)

📦 Step 4: Generate interactive HTML manga (must be executed)

After all images are generated, an interactive HTML file must be generated, integrating all pages into a browsable manga tutorial.

HTML template file

The template file is located in the assets/ directory:

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

Template placeholder description

Main template manga_template.html：

Placeholder	Description	Example
{{TITLE}}	Tutorial title	Docker Getting Started: The Secret of the Sealing Scroll
{{COMPLEXITY}}	Complexity	Simple/Medium/Complex
{{PAGE_COUNT}}	Total pages	6
{{STYLE}}	Art style name	Japanese manga
{{ANALOGY_TITLE}}	Core metaphor title	The core metaphor of this tutorial
{{ANALOGY_DESC}}	Core metaphor description	Docker = sealing scroll
{{PAGES}}	Page content (generated in a loop)	-

Single page template page_template.html：

Placeholder	Description
{{PAGE_NUM}}	Page number
{{PAGE_TITLE}}	Page title
{{IMAGE_FILE}}	Image filename
{{DIALOGUES}}	Dialogue content (generated in a loop)
{{TECH_POINT}}	Technical points

Dialogue template dialogue_template.html：

Placeholder	Description
{{CLASS}}	CSS class name: mashu / xiaoxin
{{EMOJI}}	Character emoji: 👨‍🏫 / 🧑
{{NAME}}	Character name: Mashu / Xiaoxin
{{CONTENT}}	Dialogue content

Generation process

1. Read assets/manga_template.html main template
2. For each page, read assets/page_template.html and fill in the content
3. For each dialogue, read assets/dialogue_template.html and fill in
4. Insert all page content into the main template's {{PAGES}} position
5. Save as [主题]_manga.html

Generation requirements

1. File naming：[主题]_manga.html
2. Image reference: Use relative paths to reference generated images
3. Code highlighting: Technical terms should be wrapped in <code> tags
4. Key technical points: Display each page's core knowledge points separately
5. Responsive: Ensure it can also be browsed normally on mobile

Completion notice

After generating the HTML, inform the user:

✅ The technical comic is complete! A total of [N] images and 1 interactive HTML file were generated.

📁 File list:

• page_01.png ~ page_0N.png (comic images)
• [topic]_manga.html (interactive comic, can be opened in a browser)

💡 Tip: Put the HTML file and all images in the same folder, then open the HTML in a browser to read the complete comic tutorial.

Dependencies

• nanobanana skill (provides Gemini image generation capability)
• Python 3
• Environment variable: configure GEMINI_API_KEY through nanobanana