Screenshot Tutorial Generator

截图教程图生成器 (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 个功能卡片，彼此区分又和谐）
• 中性色（pagebg / cardbg / text）

把这份配色方案作为整套图的视觉基准。风格必须跟随截图：

• 截图偏白/奶白 → 浅色主题、暖白底、大圆角、柔和
• 截图偏深/科技感 → 深色主题、深色底、小圆角、冷调强调色
• 强调色取自截图里最鲜明的品牌色

步骤 2 · 定位功能区域（关键，分层降级）

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

1. OCR 优先：运行 scripts/ocr_locate.py "" 定位文字坐标。

• 能识别到按钮文字时，以 OCR 返回的 box 为基准，再往外扩 2%~4% 的 padding 作为功能区域。
• 如果功能是多个相邻按钮的集合（如"导出图片/导出PDF/导出XMind"），用 OCR 找到其中一个按钮后，

根据界面布局把 surrounding 同类按钮一起框进来，宁可裁宽一点也不要漏按钮。

1. 多模态目测辅助：如果当前 agent 能看到图片内容且 OCR 失败，再用目测给出归一化矩形 [x, y, w, h]。

目测后建议先裁剪出来看一眼，确认内容正确再继续。

1. 用户指认兜底：若以上都拿不准，用九宫格让用户指认——

问"『导入文件』大概在截图的哪个位置？(左上/上中/右上/左中/中/右中/左下/下中/右下)"。

步骤 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
• Source: Wanqiu12345/screenshot-infographic-skill
• License: MIT

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