Document Illustrator

---
name: document-illustrator
description: 为 Markdown、纯文本、PDF、DOCX、PPTX 或 XLSX 文档规划并生成可交付配图。适用于文章配图、报告插图、封面图、章节图、概念解释图和演示文稿素材；当用户说“给文档配图”“生成插图”“做封面图”或需要按文档结构批量生成一致风格图片时使用。
---

# 文档配图助手

把文档内容转化为一组有用途、有一致性、可定位来源的真实图片文件。不要只给提示词或口头建议冒充交付。

## 工作边界

- 默认使用 WorkWise 已配置的图片生成能力，不读取技能目录、用户目录或 `.env` 中的第三方密钥。
- 不自动上传完整文档到未经用户授权的第三方服务。
- 图片必须写入当前工作区或用户明确选择的输出目录。
- 生成失败、图片提供商未配置或输出未通过检查时，明确说明原因，不声称图片已经完成。
- 不虚构文档中不存在的人物、数据、品牌标识、工程现场或事实证据。

## 工作流

### 0. 图片能力门禁（任何读取、建目录或写计划之前）

1. 先检查当前 Turn 的可用工具和运行时能力清单，确认存在已配置、可调用的 WorkWise 图片生成工具。
2. 如果工具不存在、能力清单明确显示未配置，或缺少提供商/模型/凭据，立即停止；不要读取文档全文，不要创建 `illustrations/`，不要写配图计划，也不要给出一个看似真实但尚未生成的目标文件路径。
3. 失败回复只需说明缺少哪项配置，并引导用户到“设置 → 图片生成”选择提供商、模型并完成连接测试。不得建议把文档或密钥复制到未授权的第三方服务。
4. 只有能力门禁通过后，才进入以下内容分析和文件写入步骤。

### 1. 读取并建立内容地图

1. 读取当前文档。PDF 或 Office 文件优先使用 WorkWise 文档解析结果；保留页码、标题和来源锚点。
2. 提取文档目标、受众、语气、章节结构、关键概念和需要视觉解释的位置。
3. 区分三类内容：
   - 必须忠实表达的数据、流程、结构或事实。
   - 可以抽象表现的概念、情绪和主题。
   - 不应生成的敏感、未经证实或缺少授权的内容。

### 2. 制定配图计划

默认自行采用以下设置，只有缺失信息会实质改变结果时才询问：

- 横向文档或演示文稿：`16:9`。
- 文章、报告和知识库正文：`4:3` 或与版心接近的横向比例。
- 移动端长文和社交内容：`3:4`。
- 默认生成一张封面和每个主要章节一张配图；短文控制在 3–5 张，长文先给出上限并分批执行。

为每张图建立计划项：

| 字段 | 要求 |
| --- | --- |
| 文件名 | 稳定、可读、无绝对路径 |
| 插入位置 | 对应标题、段落或页码 |
| 视觉目标 | 一句话说明读者应立即理解什么 |
| 事实约束 | 必须保持准确的名称、数据、顺序和关系 |
| 风格 | 全套共享的配色、材质、光线和构图规则 |
| 比例 | 明确宽高比 |

将计划保存为 `illustrations/illustration-plan.md`，便于复核和重做。

### 3. 选择视觉语言

按内容选择一种主风格并保持全套一致：

- 渐变玻璃卡片：科技、产品、AI、现代商业主题。读取 `references/gradient-glass.md`。
- 票据编辑风：流程、清单、方法、运营和知识卡片。读取 `references/ticket.md`。
- 矢量解释图：教育、工程、科学、概念拆解和结构关系。读取 `references/vector-illustration.md`。

品牌已有色、字体或视觉规范时优先遵循品牌。不要默认使用紫色渐变、发光球体、无意义机器人或廉价图库式握手图。

### 4. 生成图片

1. 为每张图编写完整提示，至少包含：
   - 主体、动作、环境和构图。
   - 精确比例和安全边距。
   - 统一配色、材质、光线和镜头语言。
   - 必须忠实的事实约束。
   - 需要避开的错误、文字乱码、品牌误用和多余元素。
2. 使用 WorkWise 图片生成工具逐张生成，并把 `output_path` 指向 `illustrations/assets/<计划文件名>`；工具会按图片真实格式规范化扩展名。
3. 输出到 `illustrations/assets/`，把工具返回的实际相对路径回写计划，不得把默认缓存路径冒充交付路径。
4. 需要中文长句时，优先把正文留给文档排版，只在图片中保留极短标签，避免模型生成乱码。

### 5. 逐张检查并修正

每张图片都要检查：

- 文件真实存在、可打开且尺寸非零。
- 对具备视觉输入能力的模型：读取生成图片，核对主体、数量、方向、顺序、数据、关系、畸形、乱码、裁切、遮挡、水印和第三方商标误用。
- 对不具备视觉输入能力的模型：只能完成文件、格式、尺寸和计划映射检查，必须把视觉复核明确列为人工确认项，不得声称已经看过像素内容。
- 与计划中的插入位置和视觉目标一致。
- 同一套图片的色彩、材质和构图语言一致。

不合格图片最多重做两次。仍不合格时保留可用结果并报告具体缺陷，不自动无限重试。

### 6. 交付

最终回复必须包含：

- 已生成图片数量及相对路径。
- 每张图对应的文档位置。
- 未完成、降级或需要人工确认的项目。
- 可操作的成果文件卡片；至少支持打开、另存为和显示位置。

如果用户还要求把图片插入 Write 文档、报告或 PPT，应继续完成嵌入并验证目标文档，而不是只交付散图。

## 与其他能力协作

- 需要社交卡片排版时，将配图作为素材交给已获授权并可用的社交卡片 Skill。
- 需要正式演示文稿时，将配图和来源锚点交给 PPT Master；最终必须交付可验证的 `.pptx`。
- 需要编辑现有 Design 画板时，把生成图片插入当前设计文档，并确认切换文档后状态不串用。

## 来源

本技能基于 `op7418/Document-illustrator-skill` 的 MIT 版本进行 WorkWise 适配。具体提交、许可证和改动边界见 `references/upstream.md`。