xiaohei-code-decoder

name

xiaohei-code-decoder

description

Turn a codebase or GitHub repo into a hand-drawn "小黑 (Xiaohei)" illustrated explainer — a bilingual (中文/English) image+text slide deck saved as one HTML file. Use when the user wants to explain, decode, visualize, walk through, or 拆解 / 图解 how a repository or codebase works using illustrations; mentions Xiaohei Code Decoder, 小黑 Code Decoder, 小黑看代码, 小黑图解, doodle / hand-drawn code explainer, illustrated codebase walkthrough; or points at a repo and asks for an illustrated guide to how it works.

Xiaohei Code Decoder · 小黑看代码

把一个代码库变成一套手绘小黑风的双语图文幻灯片：每屏一张小黑插画 + 一段讲机制的双语文案，最后存成单个 index.html。读者是好奇的非工程师。

先读这些

按需读取，不要一次塞满上下文：

• references/xiaohei-style.md — 小黑图像风格 DNA 与生图提示词。
• references/writing-rules.md — 双语文案规则与高亮标记。
• references/assembly.md — 怎么把图文填进模板、命名、输出、打开。
• assets/template.html — 幻灯片模板（含全部 CSS/JS，复制后填充）。
• assets/examples/ — 仅作风格校准，不要照抄其构图与隐喻。

工作流

进度：
- [ ] 1 拿到仓库
- [ ] 2 分析，选 3–6 个点（默认 5）
- [ ] 3 写双语图文 + 为每屏设计小黑场景
- [ ] 4 逐张生成 16:9 配图
- [ ] 5 填进模板组装 index.html
- [ ] 6 浏览器打开并自检

1. 拿到仓库

• 给的是 GitHub URL → git clone --depth 1 到临时目录。
• 给的是本地路径 / 当前 workspace → 直接读。

2. 分析

读 README + 关键源文件（入口、核心模块、配置）。挑出最该懂的 3–6 个点（默认 5），排成合理顺序，通常是：

1. 这是什么、做的一件事；2) 主要部件 / 架构；3) 让它成立的核心机制或巧思；4) 跑起来时的数据 / 控制流；5) 一个值得知道的细节（安全 / 性能 / 边界）。 按仓库实际内容调整。每个判断都要有代码依据。

3. 写内容 + 设计配图

• 文案严格按 references/writing-rules.md：讲机制、不揣测作者、不复述画面、不跑题、短、双语、克制高亮。
• 每屏按 references/xiaohei-style.md 重新发明一个小黑隐喻：一句中文隐喻 + 一段英文场景 + ≤4 个中文标注词。
• 同时写好封面标题/引子和 3–6 条「一句话总结」。

4. 生成配图

用当前 agent 的生图能力，按 xiaohei-style.md 的提示词结构，逐张 16:9 生成，存到输出目录的 images/，命名 NN-<slug>.png。一张图只讲一个概念，不要把多屏拼进一张。

• 免 key：Cursor 生图工具 / Codex 内置 image_gen / Antigravity（Nano Banana）。
• 需 key：Gemini CLI /image（需 Gemini API key）、Claude Code（需带 key 的图像 MCP，如 Gemini/OpenAI 图像服务）。若当前环境没有可用生图能力，先告诉用户怎么补，再继续。

5. 组装

按 references/assembly.md：复制 assets/template.html 到 <repo-slug>-xiaohei/index.html，逐屏填充，转换高亮标记，清空所有 {{…}} 占位符。

6. 打开并自检

open（macOS）/ xdg-open（Linux）打开 index.html。检查：圆点数对、语言开关只显示一种语言、每张图都能加载。

输出口径

交付时简短说明：生成了几屏、各屏讲什么、存在哪、怎么打开。让图自己说话，不要长篇风格理论。