tangchunwu Document Illustrator Skill
基于 AI 智能分析的文档配图生成工具。无需依赖特定格式，自动理解内容并生成专业配图。
🎯 核心特点
- ✨ AI 智能归纳：自动理解文档内容，智能提取核心主题
- 🎨 格式无关：支持任何格式的文档（Markdown、纯文本、PDF 等）
- 📐 灵活比例：支持 16:9（横屏）和 3:4（竖屏）
- 🖼️ 封面图可选：可生成概括全文的封面图
- 🎭 三种风格：渐变玻璃卡片、票据风格、矢量插画
🚀 使用方法
直接告诉 Codex
帮我为这个文档生成配图：/path/to/document.md
或者：
我想为这篇文章生成一些配图
📝 完整工作流程
第 1 步：Codex 读取和理解文档
当你请求生成配图时，Codex 会：
- 使用 Read 工具读取完整文档
- AI 分析理解文档内容和结构
- 识别核心主题和要点
无需担心文档格式：
- ✅ 标准 Markdown（##、###）
- ✅ 分隔线格式（======、------）
- ✅ 纯文本段落
- ✅ 任何其他格式
第 2 步：配置选项（3 个问题）
Codex 会询问你的偏好：
问题 1：图片比例
请选择图片比例：
1. 16:9 (横屏) - 适合演示文稿、幻灯片、横屏展示
2. 3:4 (竖屏) - 适合社交媒体、手机查看、海报
请选择 (1/2):
问题 2：封面图
是否生成封面图？
封面图将概括文档的所有核心信息，作为系列配图的引导。
1. 是 - 生成封面图 + 内容配图
2. 否 - 仅生成内容配图
请选择 (1/2):
问题 3：内容配图数量
期望生成多少张内容配图？
建议范围：3-10 张
根据文档内容，推荐生成 6 张
请输入数字：
第 3 步：Codex 归纳内容并展示
根据你指定的数量，Codex 会智能归纳文档，然后展示给你确认：
📋 内容归纳完成
📄 封面图内容：（如果选择生成）
"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 步：生成配图
确认后，Codex 调用 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 生成配图，用票据风格
Codex: 好的，让我先读取这个文档...
[读取文档，分析内容]
检测到文档长度约 3000 字，内容涉及 AI 工具演化。
请选择图片比例：
1. 16:9 (横屏)
2. 3:4 (竖屏)
用户: 1
Codex: 是否生成封面图？
1. 是
2. 否
用户: 是
Codex: 期望生成多少张内容配图？
建议范围：3-10 张
根据文档内容，推荐生成 5 张
用户: 5
Codex: [展示归纳的 5 个主题]
确认开始生成配图吗？
用户: Y
Codex: [调用 Python 脚本生成 6 张图片]
✨ 完成！配图已保存到 ~/blog/images/
示例 2：纯文本文档
用户: 为这个纯文本笔记生成配图
Codex: [读取笔记，即使没有任何标题也能理解内容]
[智能识别 3 个核心主题]
[询问配置、展示归纳、生成配图]
示例 3：自定义数量
用户: 我想要 8 张图，竖屏的，不要封面
Codex: 好的，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 密钥：
- 在
~/.Codex/skills/document-illustrator/.env中配置 - 或设置环境变量
GEMINI_API_KEY
📊 内容归纳原则
Codex 归纳内容时遵循以下原则：
1. 完整性优先
- ✅ 所有重要信息都会被包含
- ✅ 不会遗漏关键概念
- ✅ 保留原文的核心观点
2. 逻辑清晰
- 按照内容的自然逻辑分段
- 相关内容归为一组
- 保持叙事的连贯性
3. 平衡分配
- 每张图片包含相似的信息量
- 避免某张过于拥挤或空洞
- 根据内容重要性调整
4. 用户可控
- 展示归纳结果给用户确认
- 用户可以要求调整
- 确认后才开始生成
🐛 故障排除
问题 1：API 密钥错误
错误信息：
Error: Invalid API key
解决方案：
- 检查
.env文件中的GEMINI_API_KEY - 确保 API 密钥有效且未过期
- 获取新密钥：https://makersuite.google.com/app/apikey
问题 2：内容归纳不理想
问题：归纳的主题不符合预期
解决方案：
- 在归纳展示阶段，告诉 Codex 你的期望
- Codex 会重新归纳并调整
- 确认满意后再开始生成
问题 3：图片生成失败
可能原因：
- 网络连接问题
- API 配额用尽
- 内容过长超过限制
解决方案：
- 检查网络连接
- 检查 API 配额
- 尝试增加图片数量（分散内容）
💰 成本估算
| 图片数量 | 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. 风格选择建议
技术文档 → 渐变玻璃卡片风格 数据报告 → 票据风格 教程故事 → 矢量插画风格 产品介绍 → 渐变玻璃卡片风格
🔄 工作原理
传统方式（已废弃）
[代码] 读取文档 → 识别 ## ### 标题 → 机械切分
↓
依赖特定格式
容易遗漏内容
不够智能
新方式（当前实现）
[Codex] 读取文档 → AI 理解内容 → 智能归纳主题
↓
格式无关
内容完整
用户可控
核心区别：
- ❌ 旧方式：依赖代码解析，只能处理标准格式
- ✅ 新方式：AI 理解内容，任何格式都能处理
🎯 与其他工具的对比
| 功能 | Document Illustrator | 传统 PPT 工具 | AI 图片生成器 |
|---|---|---|---|
| 理解文档内容 | ✅ AI 智能理解 | ❌ 需要手动 | ❌ 需要手动输入 |
| 格式依赖 | ✅ 格式无关 | ❌ 依赖特定格式 | ✅ 无依赖 |
| 内容完整性 | ✅ 自动验证 | ⚠️ 手动确保 | ❌ 无法保证 |
| 批量生成 | ✅ 一次生成多张 | ❌ 逐张制作 | ⚠️ 需要多次输入 |
| 风格一致性 | ✅ 自动保持 | ⚠️ 手动调整 | ⚠️ 需要重复提示词 |
📞 获取帮助
如有问题或建议：
- 直接在 Codex 中询问 Codex
- 查看计划文件：
~/.Codex/plans/shimmering-tickling-seahorse.md - 检查 Skill 目录：
~/.Codex/skills/document-illustrator/
让 AI 帮你理解和归纳内容，生成专业配图！ ✨