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 本仓库
创建功能分支：
```
git checkout -b feature/my-new-feature
```
提交你的更改：
```
git commit -m "Add: 新功能描述"
```
推送到分支：
```
git push origin feature/my-new-feature
```
创建 Pull Request

贡献类型：

新的图片风格
功能改进
Bug 修复
文档完善
测试用例

代码规范：

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

❓ 常见问题

Q: API 密钥无效怎么办？

A: 请检查以下几点：

确认 .env 文件中的 GEMINI_API_KEY 拼写正确
确保 API 密钥有效且未过期
检查 API 密钥是否有足够的配额
重新获取密钥：Google AI Studio

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

A: 可以尝试：

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

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: 可能的原因：

网络连接问题 - 检查网络连接
API 配额用尽 - 检查 API 使用量
内容过长 - 脚本会自动截取前 1000 字符
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+ 张）：

内容分散，缺乏重点
增加生成时间和成本
可能过于碎片化

2. 根据用途选择比例

16:9 适合：

PPT 演示和幻灯片
网站横幅和博客配图
视频封面和缩略图
桌面端展示

3:4 适合：

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

3. 封面图的使用场景

建议生成封面图：

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

可以不生成封面图：

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

4. 风格选择建议

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

📄 许可证

本项目采用 MIT 许可证。

你可以自由地：

✅ 使用本软件用于商业或非商业目的
✅ 修改本软件
✅ 分发本软件
✅ 将本软件用于私人用途

前提是：

📝 在所有副本中包含原始许可证和版权声明

🙏 致谢

本项目由以下技术驱动：

Claude Sonnet 4.5 - AI 智能内容分析和归纳
Gemini 3 Pro Image Preview - 高质量图片生成
Claude Code - Skill 执行环境

特别感谢所有为本项目做出贡献的开发者和用户。

📞 联系方式

Issues: GitHub Issues
Discussions: GitHub Discussions

如有问题或建议，欢迎通过以上方式联系！

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