screenshot-infographic-skill

---
name: screenshot-infographic-skill
description: >
  把「一张截图 + 一段功能描述」或「一段主题文案」自动变成一整套可在小红书/公众号/社群直接发的
  风格统一、视觉优美的图。两种模式：①截图模式——生成功能教程图/产品导览图（1张概览+单功能细节，
  局部放大或箭头指向，视觉风格自动跟随截图）；②纯文案模式——生成杂志风信息图，每页自带文生图
  3D 概念插画，配色按主题自动推导。基于专业色彩系统生成主色/辅色/互补强调色/6功能色，避免单一。
  适合产品教程、功能安利、新手引导、知识科普、活动预告、资讯解读。
  触发词：截图生成教程、功能讲解图、产品导览图、截图配图、功能安利图、把截图做成教程、
  文案生成信息图、小红书配图、杂志风信息图、infographic generator、screenshot tutorial、
  feature guide image、text to infographic、AI 插图、3D 插画。
agent_created: true
version: 1.3.6
---

# 截图教程图生成器 (Screenshot Tutorial Generator)

把「一张截图 + 一段功能描述」变成「一整套风格统一、色彩有层次的教程图片」。用户不需要懂设计，
只要发来截图和大致说明，就能拿到可直接发布的成套配图。

## 核心产出

- **第 1 张：总体概览** — 截图嵌在顶部窗口，下方用卡片逐个拆解全部功能。
- **第 2~N 张：功能细节** — 每张聚焦一个核心功能，用「局部放大 + 圈选」或「原图 + 箭头指向」讲细节。
- 默认出 **4~5 张**（1 概览 + 3~4 细节），全部 **1080×1440 竖版 (3:4)** 高清 PNG。
- **每种模式额外生成一张「极简传播封面」`00_cover.png`**（独立一张、不编号），专供小红书/公众号直接发：
  顶部小字栏目名 + 居中大图标 + 超大品牌名 + ≤24 字 slogan + 可选一句说明；背景跟随主题色，文字克制、唯一色彩爆点是图标/品牌色。
- 同时保留可编辑的 HTML 源文件。
- **随图附赠一张小红书发布文案 `social_post.md`**：标题（< 20 字，随机主标题 + 2 备选）+ 一段正文（导语 + 要点 + 收尾 + 话题标签），可直接复制去发。内容由本次配置自动提炼，平实干净、不用营销腔。

---

## 执行流程（务必按顺序）

### 步骤 0 · 接收输入
用户会给：① 一张截图路径；② 一段功能描述（自然语言，可能不规范）。
如果只给了截图没给描述，或只给描述没给截图 → **先索要缺失的那一项**。

（**纯文案输入也已支持**：用户只发一段文案、不发截图时，走 `run_text_tutorial.py`：自动识别主题 → 拆页 → 文生图 3D 插画 → 杂志风排版成套出图。字段规范见 `references/text_mode_design.md`；执行入口 `run_text_tutorial.py`。截图模式仍是主流程。）

### 步骤 1 · 自动分析截图（脚本，不靠肉眼）
运行 `scripts/extract_theme.py <截图路径>`，得到 JSON：
- `size` / `ratio`：尺寸与比例
- `theme`：`light` 或 `dark`（由平均亮度判定）
- `bg`：背景主色
- `accent`：强调色（品牌色；界面太素时给优雅兜底色）
- `mood` / `temperature`：色相区与冷暖调性
- `radius_style`：`soft`(大圆角) 或 `sharp`(小圆角/硬朗，科技感界面)

`extract_theme.py` 内部会调用 `scripts/color_system.py`，由主色推导完整 palette：
- `accent`（主色）、`secondary`（类比辅色）、`accent2`（互补强调色）
- `feature`（6 个功能色，用于 6 个功能卡片，彼此区分又和谐）
- 中性色（page_bg / card_bg / text）

把这份配色方案作为整套图的视觉基准。**风格必须跟随截图**：
- 截图偏白/奶白 → 浅色主题、暖白底、大圆角、柔和
- 截图偏深/科技感 → 深色主题、深色底、小圆角、冷调强调色
- 强调色取自截图里最鲜明的品牌色

### 步骤 2 · 定位功能区域（关键，分层降级）
每个要讲的功能，都要在截图上定位一个矩形区域(归一化坐标 0~1)。**坐标不准会直接导致细节图裁错或裁空**，必须认真对待。按以下优先级：

1. **OCR 优先**：运行 `scripts/ocr_locate.py <截图> "<按钮文字>"` 定位文字坐标。
   - 能识别到按钮文字时，以 OCR 返回的 box 为基准，再往外扩 2%~4% 的 padding 作为功能区域。
   - 如果功能是多个相邻按钮的集合（如"导出图片/导出PDF/导出XMind"），用 OCR 找到其中一个按钮后，
     根据界面布局把 surrounding 同类按钮一起框进来，宁可裁宽一点也不要漏按钮。
2. **多模态目测辅助**：如果当前 agent 能看到图片内容且 OCR 失败，再用目测给出归一化矩形 `[x, y, w, h]`。
   目测后建议**先裁剪出来看一眼**，确认内容正确再继续。
3. **用户指认兜底**：若以上都拿不准，用九宫格让用户指认——
   问"『导入文件』大概在截图的哪个位置？(左上/上中/右上/左中/中/右中/左下/下中/右下)"。

### 步骤 3 · 确认门（做图前必须过）⚠️
**在生成任何图片之前，必须先把出图方案回述给用户确认。** 除非用户明确说"直接生成"、"你直接做"、"不用确认"之类的话，否则都要过确认门。

回述时必须包含：
- 识别到的主题/明暗/主色调/色彩调性
- 概览图要拆解的功能清单（个数和名称）
- 细节图要讲的 3~4 个功能，以及**每个功能在截图上的定位依据**
- 品牌页脚放什么（用户给了名字/网址就写上）
- 是否检测到截图中有敏感信息，需不需要提醒打码
- **产品名必须真实**：`run_screenshot_tutorial.py` 默认品牌是内置 demo 产品，**不可直接用于用户自己的截图**。运行前务必用环境变量传入截图对应产品的真实信息：`BRAND_NAME`（产品名）、`BRAND_URL`（网址）、`BRAND_SUBTITLE`（一句话副标题）、`BRAND_CATEGORY`（分类，如「AI/科技」「美食/餐饮」）。封面主/副标题与随图赠品文案都会自动从真实产品名推导。
- **封面栏目名**：先根据用户输入推导一个栏目名候选（如医疗科普→「健康知识小科普」、工具类→「AI 工具实测」），回述时给出候选 + 2~3 个备选（工具分享 / 知识分享 / 其它），**请用户确认或自定义**后再出封面。

回述格式示例：
> 我准备这样出图，请确认：
> - 主题：浅色奶白、蓝色主色（跟随你的截图），配套互补强调色橙/琥珀，6 张功能卡片用绿→青→蓝→紫 的和谐色阶
> - 概览图讲 6 个功能：①聊天输入 ②导入文档 ③图表类型 ④风格选择 ⑤添加节点 ⑥导出
> - 细节图重点讲：聊天输入生成、导入文档、图表类型切换、多格式导出
> - 定位依据：OCR 识别到"导出图片/导出PDF/导出XMind"在截图左上角横向排列；"导入文档"在右上角；"类型"在顶部中间；输入框在底部
> - 隐私检查：截图中暂未发现明显手机号/邮箱/身份证，可直接出图
> - 页脚：世界是一片荒原.AI 思维导图 · https://th3hj2tsh4.coze.site/ · 1/5
> 没问题我就开始生成。

**用户没确认、有异议、或定位依据存疑时，不要出图。** 宁可多问一句，不要裁错图、出空图。

如果用户明确催生成（如"你直接跑"、"不用确认了"），则在开始生成后**第一张概览图出来先给用户看一眼**，确认方向再继续出剩余细节图。

### 步骤 4 · 生成第 1 张概览图
用 `templates/overview.html`，填入：品牌名、副标题、截图、功能卡片(标题+一句话说明+SVG图标+编号)、
可选页脚。配色用步骤 1 的方案。功能卡片文案要**润色统一语气**，不要照抄用户原话。

6 个功能卡片会自动使用 `palette.feature` 6 色，每个卡片有独立颜色（图标底、编号、标题、左侧色条），
引导用户视线从左到右扫完一整套。

### 步骤 5 · 生成第 2~N 张细节图
对选中的每个功能，用 `templates/detail.html`：
- 用 `scripts/crop_region.py` 按步骤 2 的坐标裁出该功能区域
- **小控件**（按钮/图标）→ 局部放大 + 圈选高亮；如果控件颜色太淡导致放大后看不清，
  改用"整图 + 圈选标记"或在原图上做放大插图画中画。
- **大区域**（面板/列表/输入框）→ 裁一个包含上下文的稍大区域，让截图本身有信息量，
  避免只裁到一条细边。
- 配 3~4 段具体、可执行的操作步骤（标题 + 详细说明），以及一个底部**小提示/使用场景** box，
  确保 1080×1440 画面被有效内容填满，不要出现下半截大面积空白。
- 步骤说明要润色，语气统一；不要照抄用户原话，也不要过度废话。
- 用 `feature_color` 让细节图与概览中对应卡片颜色呼应。
- 用 `accent2`（互补强调色）高亮「核心价值」和「小提示」区块，把视线拉到重点。

### 步骤 6 · 渲染与输出
用 `scripts/render.py <html> <输出png>` 调系统浏览器无头渲染为 2x 高清 PNG，自动裁剪留白。
输出命名：`01_overview.png`、`02_<功能>.png` … 放到当前工作目录。
最后展示成图：WorkBuddy 可用 `present_files` 一次性展示；其他客户端（Claude Code / Codex / Hermes）直接打开生成的 `output/*.png` 文件即可。

---

## 关键规则

### 品牌 logo 处理
概览图左上角的品牌标识按以下优先级处理，**禁止把长品牌名硬塞进小圆圈里**（比如“世界是一片荒原.AI 思维导图”十几个字塞 60×60 图标会很难看）：
1. **用户提供 logo 图**：如果用户给了品牌图标/头像路径，直接放进 `logo_image` 字段使用。
2. **截图中有浏览器标签页 favicon**：可尝试运行 `scripts/extract_favicon.py <截图> <输出.png>` 提取，再确认提取结果是否清晰可用。不清晰时宁可不用。
3. **回退到单字/单字母**：取品牌名第一个汉字（英文取前 1~2 个字母）作为简洁初始，放 logo 圆圈里。多字必须截断到 1 字。
4. **最次回退**：用相关 SVG 图标（如"思维导图"用 tree/layers 图标）。

调用 `fill_template.py` 时，通过 `logo_image` / `logo_icon` / `logo_text` 字段显式指定，避免自动猜测导致丑图。

### 极简传播封面（每种模式各一张 `00_cover.png`）
封面是给信息流传播的「门面」，必须极简、一眼看懂，**不要**把概览图的密集信息搬上来。规则：

1. **结构**：顶部小字栏目名 → 居中大图标（圆角方块框）→ 超大品牌名 → ≤24 字 slogan（利益点，不重复品牌）→ 可选 ≤20 字说明。无页脚（或仅极淡品牌水印）。
2. **图标来源**：截图模式用提取的 favicon；纯文案/无图标时用文生图生成的 3D 主视觉当图标（已带「禁止文字」约束）。图标放圆角方块框内，仿 app-icon 质感。
3. **品牌名不缩写**：优先整名展示，按语义断行（如「世界是一片荒原」/「AI 思维导图」两层）。**仅当超过约 16 字**才提取一个短「显示名」作主标题、完整名作副标题。绝不直接把长品牌名硬塞进图标。
4. **背景跟随主题色**（深/浅随截图或文案主题），但文字保持中性、保证对比度；**唯一色彩爆点是图标/品牌色**，不要把 accent 铺满，否则会显乱。
5. **slogan 上限 24 字**：写用户一眼懂的「好处」，不要功能词、不要重复品牌名。
6. **页码**：封面不编号，文件固定 `00_cover.png`；概览图顺延为 `1/N`，细节图为 `2/N…N/N`。

调用：`fill_template.py` 的 `type="cover"`，字段 `series / icon_image(可空) / icon_text(降级) / brand_main / brand_sub(可空) / slogan / desc(可空) / watermark(可空) / palette / radius`。`icon_image` 为空时自动降级为「首字渐变圆角方块」文字 logo。

### 文案质量准则（内容层，两种模式通用）
排版再好看，文案不行也白搭。所有页面文字必须同时满足「说人话」和「专业」——这两者不矛盾：平实的词 + 准确的信息 + 有分寸的语气。

1. **说人话 ≠ 网络腔**。要口语化、易懂，但**禁用**下列几类词，它们看着接地气，实则拉低专业感：
   - 网络流行语/烂梗：`说白了`、`上头`、`能打`、`拿捏`、`绝绝子`、`yyds`、`格局`、`栓Q`、`家人们`、`划重点`、`敲黑板`。
   - 夸大营销词：`神器`、`封神`、`逆天`、`王炸`、`天花板`、`吊打`、`秒杀`、`遥遥领先`、`无敌`（正文里的 `爆款` 也尽量避免，仅栏目名可保留）。
   - 夸张情绪词：`疯狂`、`恐怖`、`炸裂`、`震惊`、`离谱`、`绝了`。
   - 对产品/工具的贬义拟人：`偷懒`、`找借口`、`耍滑头` → 换成中性的「跳过步骤 / 走捷径 / 省事做法」。
2. **标题传递信息，不贩卖情绪**。`page_title` 要让人知道这页讲什么（「四个关键设计」），而不是煽动感受（「四个让人上头的点」）。
3. **每页只讲一个核心点**。`lead` 点题 → 正文展开 → `summary` 收束，三者角度不同、不重复措辞。
4. **数字客观、可溯源、不注水**。`metrics` 用真实数据，`desc` 客观陈述（「GitHub 上的收藏量」而非「被疯狂收藏」）；拿不准的数据宁可不写。
5. **落到读者利益（so what）**。每个卖点都要回答「这对你意味着什么」，而不是罗列功能参数。
6. **术语即用即解**。出现专有名词时随手用一句白话解释，默认读者是小白。
7. **口吻统一**：全套统一第二人称、平和专业；比喻可用但克制（最多一个且贴切），不堆叠。
8. **介绍类页面首选 `spec_list`**：用「名称 / 它是什么 / 适用人群 / 使用场景」让完全不懂的人也能秒懂。

> 自检口诀：写完通读一遍，凡是「换成一个认真的人当面讲不会说出口」的词，一律删掉重写。

### 品牌页脚智能判断
- 用户给了 **网址 + 品牌名** → 页脚放品牌名 + 网址（可预留二维码位）
- 只给了 **品牌名或主题名** → 页脚只放名字
- **什么都没给**（只有截图）→ 不加页脚，保持简洁

### 细节图选取（默认"自动挑主要功能"）
从全部功能里挑 **3~4 个最核心**的出细节图。判断依据：用户描述里强调的、
最能体现产品价值的、操作最高频的。若用户明确指定了重点功能，则以用户指定为准。

### 明暗自适应（默认"自动跟随截图"）
`theme=light` → 浅色主题图；`theme=dark` → 深色主题图。让教程图和截图调性一致。

### 色彩系统
色彩不是随机选的。`scripts/color_system.py` 基于成熟色彩理论，从截图主色自动推导：
- **60-30-10 法则**：60% 中性背景、30% 主色+类比辅色、10% 互补强调色。
- **功能色板**：以主色为锚，在色轮 ±60° 内等距取 6 色，给每个功能卡片独立颜色，引导视线。
- **WCAG 对比度**：彩色块上的白字满足可读性。
- **互补强调色**：只用在「核心价值」和「小提示」等重点区块，避免满图都是高饱和色。

### 一致性
整套图统一：同背景、同卡片样式、同套配色、同字体、同页脚、页码(1/5、2/5…)。

### 隐私
出图前扫一眼截图是否含手机号/邮箱/身份证/二维码/个人昵称等敏感信息，有则提醒用户是否打码。

### ⚠️ 生成任务进行中严禁主动结束对话
只要还有图片/渲染（含 Agnes 文生图、无头浏览器渲染）等耗时任务没出结果，**绝对不能**主动结束这一轮对话。
- 禁止在最后说"等图出来再汇报""转为等后台通知"之类收尾语然后停嘴——这等于主动结束对话，任务成功时不会再主动开口汇报。
- 必须用持续阻塞（工具轮询 `block=true`）把对话保持在等待状态，直到任务真正跑完、拿到成图并向用户汇报之后，这一轮才算结束。
- 即使后台任务用 `run_in_background` 启动，也必须在当轮内持续 `TaskOutput block=true` 等待，不能用"等通知"当结束语。
- 这条优先级高于"减少轮询占用"等任何省事考量；用户明确要求过：skill 不允许在图片全部生成完毕前中断对话。

---

## 跨平台支持（已验证）

本技能遵循 **Agent Skills 开放标准（agentskills.io）**，技能目录结构在主流编码智能体之间通用，无需改写格式：
- **Claude Code**：`~/.claude/skills/<name>/SKILL.md`
- **OpenAI Codex**：`~/.agents/skills/<name>/SKILL.md`（或仓库内 `.agents/skills/`），Codex 2025-12 起原生支持 Agent Skills
- **Hermes**：`~/.hermes/skills/<name>/SKILL.md`，还支持 `external_dirs` 扫描共享的 `~/.agents/skills/`
- **WorkBuddy**：`~/.workbuddy/skills/<name>/SKILL.md`

技能内含的 Python 脚本靠终端执行，上述工具均支持，可直接复用。`agent_created` / `version` 等本工具专属元数据会被其他工具忽略，无害。

**运行前置（任何客户端都一样）**：
- 必须装有 **Edge / Chrome / Chromium** 之一（无头渲染依赖，Linux 服务器/容器需自行 `apt/dnf install chromium`）；`render.py` 已内置 `--no-sandbox` 与 `--disable-dev-shm-usage`。
- 纯文案模式的 3D 插画调用 **Agnes AI**（`apihub.agnes-ai.com`，主要面向中国大陆直连）。海外/受限网络连不上时会**自动跳过插画、降级为占位渲染**，不会卡死；想用插画请自配 `AGNES_API_KEY`。

---

## 依赖

- **Python 3.10+**
- **Pillow**（必需，取色/裁剪）：装在隔离 venv 里。
- **系统浏览器**（必需，渲染）：Windows 用 Edge，macOS 用 Chrome，Linux 用 chromium。
  `render.py` 会自动查找。
- **OCR（强烈推荐）**：`rapidocr-onnxruntime`，用于自动定位按钮文字坐标，避免目测误差。
  若未安装，可临时用目测+裁剪验证，但务必在生成前确认裁剪内容正确。

也可以直接运行仓库根目录的 `install.py` 一键创建隔离 venv 并安装依赖。

详细设计规范见 `references/design_notes.md`；配色理论见 `references/color_guide.md`。

---

## 多截图与输出目录

- 每次生成会覆盖当前工作目录下已有的 `01_overview.png`、`02_xxx.png` 等文件；
- 如需为多个项目/多张截图出图，建议把 `run_screenshot_tutorial.py` 复制到不同工作目录，并修改脚本里的 `BASE`、`SCREENSHOT`、`items`、`details` 等配置；
- 所有中间文件（`config.json`、`*.html`、`crop_*.png`）都保留在 `BASE` 目录，方便追溯和调试。

## 错误处理与兜底

- 如果 `extract_theme.py` 返回错误 JSON 或取色失败，先检查截图路径是否正确、图片是否能被 Pillow 打开。
- 如果 OCR 无法定位，按「目测→裁剪验证→九宫格用户指认」的顺序降级，不要直接猜一个坐标出图。
- 如果 `render.py` 报错找不到浏览器，请安装 Edge / Chrome / Chromium 后重试。
- 如果渲染出的 PNG 有空白或错位，优先检查 HTML 源文件和 CSS 变量是否正确填充。

---

## 图片模型（可选增强 · Agnes AI）

为教程图生成 **3D 概念插画**，提升「精美度」。这是可选增强，未配置 key 时自动降级，不影响基础出图。

### 什么时候用
- **截图模式**：给概览图顶部加 3D 品牌主视觉；给细节图的「核心价值 / 使用场景」配 3D 概念图。
- **纯文案模式**（已支持）：为每页生成对应主题的 3D 插画，见 `run_text_tutorial.py`。配置里 `cover` 与每个 `page` 都必须带 `visual_prompt`（3D 插画英文 prompt）；缺失会在文生图前**显式报错**并指出缺了哪几页（带 page_title/layout 便于定位），可加 `--no-validate` 跳过该校验（仅当你确实要纯文字页时）。

### 配置
1. 到 https://agnes-ai.com 注册，Settings → API Keys 创建密钥。
2. 设置环境变量：`export AGNES_API_KEY=sk-xxx`（Windows: `set AGNES_API_KEY=sk-xxx`）。
3. 在 `run_screenshot_tutorial.py` 或模板调用点指定 `concept_prompt`，由 `scripts/agnes_image.py` 生成并嵌入。

### 调用约定
- 文生图：`agnes-image-2.1-flash`；图生图：`agnes-image-2.0-flash`。
- 竖版尺寸用 `768x1024`(3:4) 或 `720x1280`(9:16)；**不要**用 `1080x1920`（会 500）。
- `scripts/agnes_image.py` 内部已处理 5xx 重试与图片下载，返回本地路径。
- 详细 API、Prompt 结构与降级策略见 `references/agnes_image_guide.md`。