document-illustrator

by @op7418 in Productivity

200

# Install this skill:

npx skills add op7418/Document-illustrator-skill

Or install specific skill: npx add-skill https://github.com/op7418/Document-illustrator-skill

# Description

# SKILL.md

name: document-illustrator
description: >
基于文档内容自动生成配图。AI 智能分析文档结构，归纳核心要点，
为每个主题生成符合特定风格的配图。支持封面图生成和自定义图片比例。
使用场景：当用户需要为文档、文章、笔记生成配图时。
关键词：配图、插图、illustration、generate images、document images
allowed-tools:
- Read
- Write
- Bash(python:*)
- Glob
- AskUserQuestion
model: claude-sonnet-4-5-20250514

Document Illustrator Skill

基于 AI 智能分析的文档配图生成工具。无需依赖特定格式，自动理解内容并生成专业配图。

🎯 核心特点

✨ AI 智能归纳：自动理解文档内容，智能提取核心主题
🎨 格式无关：支持任何格式的文档（Markdown、纯文本、PDF 等）
📐 灵活比例：支持 16:9（横屏）和 3:4（竖屏）
🖼️ 封面图可选：可生成概括全文的封面图
🎭 三种风格：渐变玻璃卡片、票据风格、矢量插画

🚀 使用方法

直接告诉 Claude

帮我为这个文档生成配图：/path/to/document.md

或者：

我想为这篇文章生成一些配图

📝 完整工作流程

第 1 步：Claude 读取和理解文档

当你请求生成配图时，Claude 会：
1. 使用 Read 工具读取完整文档
2. AI 分析理解文档内容和结构
3. 识别核心主题和要点

无需担心文档格式：
- ✅ 标准 Markdown（##、###）
- ✅ 分隔线格式（======、------）
- ✅ 纯文本段落
- ✅ 任何其他格式

第 2 步：配置选项（3 个问题）

Claude 会询问你的偏好：

问题 1：图片比例

请选择图片比例：
1. 16:9 (横屏) - 适合演示文稿、幻灯片、横屏展示
2. 3:4 (竖屏) - 适合社交媒体、手机查看、海报

请选择 (1/2):

问题 2：封面图

是否生成封面图？
封面图将概括文档的所有核心信息，作为系列配图的引导。

1. 是 - 生成封面图 + 内容配图
2. 否 - 仅生成内容配图

请选择 (1/2):

问题 3：内容配图数量

期望生成多少张内容配图？
建议范围：3-10 张
根据文档内容，推荐生成 6 张

请输入数字：

第 3 步：Claude 归纳内容并展示

根据你指定的数量，Claude 会智能归纳文档，然后展示给你确认：

📋 内容归纳完成

📄 封面图内容：（如果选择生成）
"AI 编程工具概念演化：从 Rules 到 Skills"
- 核心概念：静态上下文 vs 动态上下文
- 演化路径：Rules → Commands → MCP → Modes → Skills
- 最佳实践：简化为两个核心工具

📚 内容配图（共 6 张）：

1. Rules 的诞生与演化
   包含：早期模型幻觉问题、rules 文件的作用、静态上下文概念

2. Commands 和工作流打包
   包含：固定工作流的出现、slash command、团队分享

3. MCP Servers 带来动态能力
   包含：第三方工具集成、OAuth 认证、上下文膨胀问题

4. Modes 和 Subagents 的登场
   包含：人设提示词、系统提示词修改、可靠性设计、Hooks 确定性

5. Skills 统一动态上下文
   包含：Skills 概念、动态加载、编程工具优化

6. 最佳实践与未来展望
   包含：Rules 使用建议、Skills 探索、核心理念总结

✓ 所有内容已覆盖，无遗漏

确认开始生成配图吗？(Y/N)

关键保证：
- ✅ 内容完整：所有重要信息都会被归入某张图片
- ✅ 逻辑清晰：按照内容的自然逻辑分段
- ✅ 用户可控：展示归纳结果，等待用户确认

第 4 步：生成配图

确认后，Claude 调用 Python 脚本生成图片：

🖼️  开始生成配图...

正在生成封面图...
  ✓ 已保存: /path/to/document/images/cover.png

正在生成第 1/6 张...
  标题: Rules 的诞生与演化
  ✓ 已保存: /path/to/document/images/illustration-01.png

正在生成第 2/6 张...
  标题: Commands 和工作流打包
  ✓ 已保存: /path/to/document/images/illustration-02.png

...

✨ 完成！共生成 7 张配图（1 张封面 + 6 张内容）

第 5 步：输出结果

输出位置：文档所在目录下的 images/ 文件夹

/path/to/your/document/
└── images/
    ├── cover.png              # 封面图（如果选择生成）
    ├── illustration-01.png    # 第 1 张内容配图
    ├── illustration-02.png    # 第 2 张内容配图
    ├── illustration-03.png
    ├── illustration-04.png
    ├── illustration-05.png
    └── illustration-06.png

🎨 三种风格说明

1. 渐变玻璃卡片风格 (gradient-glass)

特点：
- Apple Keynote 风格的极简主义
- 玻璃拟态（Glassmorphism）设计
- 深邃虚空黑或纯净陶瓷白基底
- 流动的极光渐变色
- 3D 玻璃物体和发光效果

适用场景：
- 科技产品介绍
- 数据分析报告
- 未来趋势展望
- 产品功能演示

2. 票据风格 (ticket)

特点：
- 数字极简票券设计
- 高度对比的黑白配色
- 类似登机牌、门票的结构
- 精确的几何分区
- 中英混排，多向文字布局

适用场景：
- 信息图表
- 统计数据展示
- 时间线和流程图
- 要点总结

3. 矢量插画风格 (vector-illustration)

特点：
- 扁平化矢量插画
- 统一粗细的黑色轮廓线
- 复古柔和的配色
- 几何化处理
- 横向全景式构图

适用场景：
- 故事叙述
- 概念解释
- 教育内容
- 品牌宣传

💡 使用示例

示例 1：完整流程

用户: 帮我为 ~/blog/ai-tools.md 生成配图，用票据风格

Claude: 好的，让我先读取这个文档...
        [读取文档，分析内容]

        检测到文档长度约 3000 字，内容涉及 AI 工具演化。

        请选择图片比例：
        1. 16:9 (横屏)
        2. 3:4 (竖屏)

用户: 1

Claude: 是否生成封面图？
        1. 是
        2. 否

用户: 是

Claude: 期望生成多少张内容配图？
        建议范围：3-10 张
        根据文档内容，推荐生成 5 张

用户: 5

Claude: [展示归纳的 5 个主题]
        确认开始生成配图吗？

用户: Y

Claude: [调用 Python 脚本生成 6 张图片]
        ✨ 完成！配图已保存到 ~/blog/images/

示例 2：纯文本文档

用户: 为这个纯文本笔记生成配图

Claude: [读取笔记，即使没有任何标题也能理解内容]
        [智能识别 3 个核心主题]
        [询问配置、展示归纳、生成配图]

示例 3：自定义数量

用户: 我想要 8 张图，竖屏的，不要封面

Claude: 好的，16:9 竖屏，不生成封面，8 张内容配图。
        [将文档归纳为 8 个主题]
        [展示归纳结果，用户确认后生成]

🔧 技术细节

图片规格

比例	分辨率	适用场景
16:9	2560x1440 (2K)	演示文稿、横屏展示
3:4	1920x2560	社交媒体、竖屏查看

可选 4K 分辨率：
- 16:9 → 3840x2160
- 3:4 → 2880x3840

API 调用

模型：Gemini 2.0 Flash Image Preview (Nano Banana Pro)
成本：每张图片 = 1 次 API 调用
速度：平均 10-20 秒/张

环境要求

必需：

pip install google-genai pillow python-dotenv

API 密钥：
- 在 ~/.claude/skills/document-illustrator/.env 中配置
- 或设置环境变量 GEMINI_API_KEY

📊 内容归纳原则

Claude 归纳内容时遵循以下原则：

1. 完整性优先

✅ 所有重要信息都会被包含
✅ 不会遗漏关键概念
✅ 保留原文的核心观点

2. 逻辑清晰

按照内容的自然逻辑分段
相关内容归为一组
保持叙事的连贯性

3. 平衡分配

每张图片包含相似的信息量
避免某张过于拥挤或空洞
根据内容重要性调整

4. 用户可控

展示归纳结果给用户确认
用户可以要求调整
确认后才开始生成

🐛 故障排除

问题 1：API 密钥错误

错误信息：

Error: Invalid API key

解决方案：
1. 检查 .env 文件中的 GEMINI_API_KEY
2. 确保 API 密钥有效且未过期
3. 获取新密钥：https://makersuite.google.com/app/apikey

问题 2：内容归纳不理想

问题：归纳的主题不符合预期

解决方案：
1. 在归纳展示阶段，告诉 Claude 你的期望
2. Claude 会重新归纳并调整
3. 确认满意后再开始生成

问题 3：图片生成失败

可能原因：
- 网络连接问题
- API 配额用尽
- 内容过长超过限制

解决方案：
1. 检查网络连接
2. 检查 API 配额
3. 尝试增加图片数量（分散内容）

💰 成本估算

图片数量	API 调用次数	预估成本
无封面 + 3 张	3 次	低
有封面 + 5 张	6 次	中
有封面 + 10 张	11 次	较高

建议：
- 短文档（<1000字）：3-5 张
- 中等文档（1000-3000字）：5-7 张
- 长文档（>3000字）：8-10 张

📚 最佳实践

1. 合理选择图片数量

太少：
- 每张图片信息量过大
- 不容易理解和记忆

太多：
- 内容分散
- 增加成本和生成时间

推荐：
- 根据文档长度选择
- 每张图片涵盖 1-2 个核心观点

2. 根据用途选择比例

16:9 适合：
- PPT 演示
- 网站横幅
- 视频封面
- 博客配图（桌面端）

3:4 适合：
- 社交媒体（Instagram、小红书）
- 移动端文章
- 海报设计
- 竖屏视频

3. 封面图的使用

建议生成封面图的场景：
- 系列文章（作为统一引导）
- 社交分享（作为预览图）
- 文档首页（概括全文）

可以不生成的场景：
- 仅内部使用
- 图片数量已足够
- 希望降低成本

4. 风格选择建议

技术文档 → 渐变玻璃卡片风格
数据报告 → 票据风格
教程故事 → 矢量插画风格
产品介绍 → 渐变玻璃卡片风格

🔄 工作原理

传统方式（已废弃）

[代码] 读取文档 → 识别 ## ### 标题 → 机械切分
       ↓
    依赖特定格式
    容易遗漏内容
    不够智能

新方式（当前实现）

[Claude] 读取文档 → AI 理解内容 → 智能归纳主题
         ↓
      格式无关
      内容完整
      用户可控

核心区别：
- ❌ 旧方式：依赖代码解析，只能处理标准格式
- ✅ 新方式：AI 理解内容，任何格式都能处理

🎯 与其他工具的对比

功能	Document Illustrator	传统 PPT 工具	AI 图片生成器
理解文档内容	✅ AI 智能理解	❌ 需要手动	❌ 需要手动输入
格式依赖	✅ 格式无关	❌ 依赖特定格式	✅ 无依赖
内容完整性	✅ 自动验证	⚠️ 手动确保	❌ 无法保证
批量生成	✅ 一次生成多张	❌ 逐张制作	⚠️ 需要多次输入
风格一致性	✅ 自动保持	⚠️ 手动调整	⚠️ 需要重复提示词

📞 获取帮助

如有问题或建议：
1. 直接在 Claude Code 中询问 Claude
2. 查看计划文件：~/.claude/plans/shimmering-tickling-seahorse.md
3. 检查 Skill 目录：~/.claude/skills/document-illustrator/

让 AI 帮你理解和归纳内容，生成专业配图！ ✨

# README.md

Document Illustrator

Document Illustrator Cover

基于 AI 智能分析的文档配图生成工具

Document Illustrator 是一个 Claude Code Skill，它能智能理解文档内容，自动归纳核心要点，并为每个主题生成专业配图。无需依赖特定文档格式，AI 会理解内容并生成符合你选择风格的高质量图片。

✨ 核心特性

🤖 AI 智能归纳：自动理解文档内容，智能提取核心主题，无需依赖标题格式
📝 格式无关：支持任何格式的文档（Markdown、纯文本、PDF 等）
🎨 三种风格：渐变玻璃卡片、票据风格、矢量插画，满足不同场景需求
📐 灵活比例：支持 16:9（横屏）和 3:4（竖屏）两种图片比例
🖼️ 封面图可选：可生成概括全文的封面图作为系列配图的引导
✅ 内容完整：展示归纳结果供你确认，确保所有重要信息都被包含

🚀 快速开始

使用 npx 安装（推荐）

npx skills add https://github.com/op7418/Document-illustrator-skill

手动安装

克隆或下载本仓库到 Claude Skills 目录：

cd ~/.claude/skills/
git clone https://github.com/op7418/Document-illustrator-skill.git

配置 API 密钥（见下方"配置说明"部分）
安装 Python 依赖（见下方"环境要求"部分）

基本使用

在 Claude Code 中直接告诉 Claude：

帮我为这个文档生成配图：/path/to/document.md

或者：

我想为这篇文章生成一些配图

Claude 会引导你完成整个配图生成流程。

🎨 三种风格说明

1. 渐变玻璃卡片风格 (gradient-glass)

视觉特点：
- Apple Keynote 风格的极简主义设计
- 玻璃拟态（Glassmorphism）效果
- 深邃虚空黑或纯净陶瓷白基底
- 流动的极光渐变色
- 3D 玻璃物体和发光效果

适用场景：
- 科技产品介绍
- 数据分析报告
- 未来趋势展望
- 产品功能演示

2. 票据风格 (ticket)

视觉特点：
- 数字极简票券设计
- 高度对比的黑白配色
- 类似登机牌、门票的结构化布局
- 精确的几何分区
- 中英混排，多向文字布局

适用场景：
- 信息图表
- 统计数据展示
- 时间线和流程图
- 要点总结

3. 矢量插画风格 (vector-illustration)

视觉特点：
- 扁平化矢量插画
- 统一粗细的黑色轮廓线
- 复古柔和的配色方案
- 几何化处理
- 横向全景式构图

适用场景：
- 故事叙述
- 概念解释
- 教育内容
- 品牌宣传

📦 安装和配置

步骤 1: 安装 Skill

使用 npx（推荐）：

npx skills add https://github.com/op7418/Document-illustrator-skill

手动安装：

cd ~/.claude/skills/
git clone https://github.com/op7418/Document-illustrator-skill.git
cd document-illustrator

步骤 2: 配置 API 密钥

获取 Gemini API 密钥：Google AI Studio
在 Skill 根目录创建 .env 文件：

cd ~/.claude/skills/document-illustrator
echo "GEMINI_API_KEY=your-api-key-here" > .env

或直接编辑 .env 文件：

GEMINI_API_KEY=your-api-key-here

安全提示：.env 文件包含敏感信息，请勿提交到版本控制系统

步骤 3: 安装 Python 依赖

cd ~/.claude/skills/document-illustrator
pip install google-genai pillow python-dotenv

或使用 pip3：

pip3 install google-genai pillow python-dotenv

步骤 4: 验证安装

运行测试命令：

python3 scripts/generate_single_image.py --help

预期输出应显示脚本的帮助信息，表示安装成功。

📖 使用方法

方式 1: 通过 Claude Code 使用（推荐）

这是主要的使用方式，让 Claude 智能处理整个流程。

基本命令：

帮我为这个文档生成配图：~/blog/my-article.md

交互式流程：

选择图片比例
16:9（横屏）- 适合演示文稿、网站横幅
3:4（竖屏）- 适合社交媒体、手机查看
是否生成封面图
是 - 生成封面图 + 内容配图
否 - 仅生成内容配图
指定配图数量
根据文档长度，Claude 会推荐合适的数量
你可以自定义需要的图片数量（建议 3-10 张）
确认内容归纳
Claude 会展示归纳的主题列表
确认所有重要内容都被包含
可以要求调整归纳结果
生成配图
确认后，自动调用 Gemini API 生成图片
图片保存到文档所在目录的 images/ 文件夹

完整示例：

用户: 帮我为 ~/documents/ai-evolution.md 生成配图，用渐变玻璃风格

Claude: 好的，让我先读取这个文档...
        [读取并分析文档内容]

        检测到文档长度约 3000 字。

        请选择图片比例：
        1. 16:9 (横屏)
        2. 3:4 (竖屏)

用户: 1

Claude: 是否生成封面图？
        1. 是
        2. 否

用户: 是

Claude: 期望生成多少张内容配图？
        建议范围：3-10 张
        根据文档内容，推荐生成 5 张

用户: 5

Claude: 📋 内容归纳完成

        📄 封面图内容：
        "AI 技术演化：从规则到智能"
        - 核心概念、演化路径、最佳实践

        📚 内容配图（共 5 张）：
        1. AI 技术的起源
        2. 机器学习的突破
        3. 深度学习革命
        4. 大语言模型时代
        5. 未来发展趋势

        ✓ 所有内容已覆盖，无遗漏

        确认开始生成配图吗？(Y/N)

用户: Y

Claude: 🖼️  开始生成配图...

        正在生成封面图...
        ✓ 已保存: ~/documents/images/cover.png

        正在生成第 1/5 张...
        ✓ 已保存: ~/documents/images/illustration-01.png

        ...

        ✨ 完成！共生成 6 张配图

方式 2: 直接使用 Python 脚本（高级用户）

如果你想要更多控制或进行批量处理，可以直接调用 Python 脚本。

单图生成：

python3 scripts/generate_single_image.py \
  --title "人工智能的未来" \
  --content "AI 技术正在快速发展..." \
  --style gradient-glass \
  --aspect-ratio 16:9 \
  --resolution 2K \
  --output ~/output/image.png

参数说明：

--title: 图片标题
--content: 图片内容描述
--style: 风格（gradient-glass / ticket / vector-illustration）
--aspect-ratio: 比例（16:9 / 3:4）
--resolution: 分辨率（2K / 4K）
--output: 输出文件路径

🔍 示例展示

示例 1: 技术文章配图

技术文章示例

使用渐变玻璃卡片风格，16:9 比例，适合科技博客和演示文稿。

示例 2: 数据报告配图

数据报告示例

使用票据风格，3:4 比例，适合信息图表和社交媒体分享。

示例 3: 教程配图

教程示例

使用矢量插画风格，16:9 比例，适合教育内容和故事叙述。

注意：以上为示例占位符。实际生成的图片效果取决于文档内容和选择的风格。

⚙️ 工作原理

整体架构

📄 文档输入
    ↓
🤖 Claude 读取和理解
    ↓
💡 AI 智能归纳核心主题
    ↓
✅ 用户确认内容分配
    ↓
🎨 调用 Gemini API 生成图片
    ↓
💾 保存到本地目录

与传统方式的对比

传统方式：

代码解析标题 → 机械切分章节 → 生成配图
    ↓
❌ 依赖特定格式（## ###）
❌ 容易遗漏非标准内容
❌ 无法理解语义

Document Illustrator：

AI 理解内容 → 智能归纳主题 → 用户确认 → 生成配图
    ↓
✅ 格式无关，任何文档都能处理
✅ 保证内容完整性
✅ 用户可控，结果透明

核心优势：
- AI 理解文档语义，而非简单的格式解析
- 智能归纳保证内容完整，不会遗漏重要信息
- 用户确认机制，生成前可以调整归纳结果

👨‍💻 开发者指南

目录结构

document-illustrator/
├── README.md                 # 项目说明文档（本文件）
├── LICENSE                   # MIT 许可证
├── SKILL.md                  # Skill 定义文件（供 Claude Code 使用）
├── .env                      # API 密钥配置（需自行创建）
├── .gitignore                # Git 忽略规则
├── scripts/                  # Python 脚本目录
│   ├── generate_illustrations.py    # 批量生成脚本（已废弃）
│   └── generate_single_image.py     # 单图生成脚本
├── styles/                   # 风格提示词目录
│   ├── gradient-glass.md            # 渐变玻璃卡片风格
│   ├── ticket.md                     # 票据风格
│   └── vector-illustration.md        # 矢量插画风格
└── examples/                 # 示例图片目录（可选）
    └── README.md                     # 示例说明

自定义风格

你可以创建自己的图片风格：

在 styles/ 目录创建新的 .md 文件，例如 my-style.md
编写 Gemini 提示词：

### 提示词

帮我生成一张[描述你的风格]的图片...

[详细的风格要求]
- 配色方案
- 构图规则
- 设计元素
- 视觉效果

修改 scripts/generate_single_image.py 以支持新风格（在 --style 参数中添加新选项）

贡献指南

我们欢迎贡献！如果你想为本项目做出贡献：

Fork 本仓库
创建功能分支：
bash git checkout -b feature/my-new-feature
提交你的更改：
bash git commit -m "Add: 新功能描述"
推送到分支：
bash git push origin feature/my-new-feature
创建 Pull Request

贡献类型：
- 新的图片风格
- 功能改进
- Bug 修复
- 文档完善
- 测试用例

代码规范：
- 遵循 PEP 8 Python 代码风格
- 添加必要的注释和文档字符串
- 确保代码可读性和可维护性

❓ 常见问题

Q: API 密钥无效怎么办？

A: 请检查以下几点：
1. 确认 .env 文件中的 GEMINI_API_KEY 拼写正确
2. 确保 API 密钥有效且未过期
3. 检查 API 密钥是否有足够的配额
4. 重新获取密钥：Google AI Studio

Q: 生成的图片不符合预期怎么办？

A: 可以尝试：
1. 在归纳展示阶段，告诉 Claude 你的期望，它会重新归纳
2. 尝试不同的风格
3. 调整配图数量（增加或减少）
4. 提供更详细的文档内容

Q: 如何调整图片质量？

A: 使用 --resolution 参数：
- 2K（默认）：16:9 为 2560x1440，3:4 为 1920x2560
- 4K：16:9 为 3840x2160，3:4 为 2880x3840

注意：4K 图片生成时间更长，API 成本可能更高。

Q: 支持批量处理多个文档吗？

A: 目前推荐通过 Claude Code 逐个处理文档。如果需要批量处理，可以编写自定义脚本循环调用 generate_single_image.py。

Q: 成本估算？

A: 每张图片需要调用一次 Gemini API：
- 无封面 + 3 张：3 次调用
- 有封面 + 5 张：6 次调用
- 有封面 + 10 张：11 次调用

具体成本取决于 Google AI 的定价策略，请查看 Gemini API 定价。

Q: 为什么有时图片生成失败？

A: 可能的原因：
1. 网络连接问题 - 检查网络连接
2. API 配额用尽 - 检查 API 使用量
3. 内容过长 - 脚本会自动截取前 1000 字符
4. API 服务临时不可用 - 稍后重试

📊 技术规格

项目	说明
AI 模型	gemini-3-pro-image-preview (Nano Banana Pro)
图片格式	PNG
16:9 分辨率	2K (2560x1440) / 4K (3840x2160)
3:4 分辨率	2K (1920x2560) / 4K (2880x3840)
支持文档格式	Markdown, 纯文本, PDF 等（任何 Claude 可读的格式）
平均生成时间	10-20 秒/张
Python 版本	3.8+
主要依赖	google-genai, pillow, python-dotenv

💡 最佳实践

1. 合理选择图片数量

太少（1-2 张）：
- 每张图片信息量过大
- 不容易理解和记忆
- 视觉负担重

太多（15+ 张）：
- 内容分散，缺乏重点
- 增加生成时间和成本
- 可能过于碎片化

推荐：
- 短文档（<1000 字）：3-5 张
- 中等文档（1000-3000 字）：5-7 张
- 长文档（>3000 字）：8-10 张
- 每张图片涵盖 1-2 个核心观点

2. 根据用途选择比例

16:9 适合：
- PPT 演示和幻灯片
- 网站横幅和博客配图
- 视频封面和缩略图
- 桌面端展示

3:4 适合：
- 社交媒体（Instagram、小红书、微信朋友圈）
- 移动端文章和 H5 页面
- 海报设计
- 竖屏视频和 Story

3. 封面图的使用场景

建议生成封面图：
- 系列文章（作为统一的视觉引导）
- 社交分享（作为预览图吸引点击）
- 文档首页（概括全文主旨）
- 演示文稿开场

可以不生成封面图：
- 仅内部使用的文档
- 图片数量已经足够
- 希望降低 API 调用成本
- 不需要总览性的图片

4. 风格选择建议

内容类型	推荐风格	理由
技术文档	渐变玻璃卡片	现代、科技感强
数据报告	票据风格	简洁、信息密度高
教程故事	矢量插画	温馨、易于理解
产品介绍	渐变玻璃卡片	高端、未来感
学术论文	票据风格	专业、严谨
儿童内容	矢量插画	可爱、友好