# Screenshot Tutorial Generator

> >

- **Type:** Skill
- **Install:** `agentstack add skill-wanqiu12345-screenshot-infographic-skill-screenshot-infographic-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Wanqiu12345](https://agentstack.voostack.com/s/wanqiu12345)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Wanqiu12345](https://github.com/Wanqiu12345)
- **Source:** https://github.com/Wanqiu12345/screenshot-infographic-skill

## Install

```sh
agentstack add skill-wanqiu12345-screenshot-infographic-skill-screenshot-infographic-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

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

## 核心产出

- **第 1 张：总体概览** — 截图嵌在顶部窗口，下方用卡片逐个拆解全部功能。
- **第 2~N 张：功能细节** — 每张聚焦一个核心功能，用「局部放大 + 圈选」或「原图 + 箭头指向」讲细节。
- 默认出 **4~5 张**（1 概览 + 3~4 细节），全部 **1080×1440 竖版 (3:4)** 高清 PNG。
- 同时保留可编辑的 HTML 源文件。

---

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

### 步骤 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 个功能，以及**每个功能在截图上的定位依据**
- 品牌页脚放什么（用户给了名字/网址就写上）
- 是否检测到截图中有敏感信息，需不需要提醒打码

回述格式示例：
> 我准备这样出图，请确认：
> - 主题：浅色奶白、蓝色主色（跟随你的截图），配套互补强调色橙/琥珀，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  ` 调系统浏览器无头渲染为 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  ` 提取，再确认提取结果是否清晰可用。不清晰时宁可不用。
3. **回退到单字/单字母**：取品牌名第一个汉字（英文取前 1~2 个字母）作为简洁初始，放 logo 圆圈里。多字必须截断到 1 字。
4. **最次回退**：用相关 SVG 图标（如"思维导图"用 tree/layers 图标）。

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

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

### 细节图选取（默认"自动挑主要功能"）
从全部功能里挑 **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//SKILL.md`
- **OpenAI Codex**：`~/.agents/skills//SKILL.md`（或仓库内 `.agents/skills/`），Codex 2025-12 起原生支持 Agent Skills
- **Hermes**：`~/.hermes/skills//SKILL.md`，还支持 `external_dirs` 扫描共享的 `~/.agents/skills/`
- **WorkBuddy**：`~/.workbuddy/skills//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`。

### 配置
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`。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Wanqiu12345](https://github.com/Wanqiu12345)
- **Source:** [Wanqiu12345/screenshot-infographic-skill](https://github.com/Wanqiu12345/screenshot-infographic-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-wanqiu12345-screenshot-infographic-skill-screenshot-infographic-skill
- Seller: https://agentstack.voostack.com/s/wanqiu12345
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.