| name | document-illustrator |
| description | 为 Markdown、纯文本、PDF、DOCX、PPTX 或 XLSX 文档规划并生成可交付配图。适用于文章配图、报告插图、封面图、章节图、概念解释图和演示文稿素材；当用户说“给文档配图”“生成插图”“做封面图”或需要按文档结构批量生成一致风格图片时使用。 |
文档配图助手
把文档内容转化为一组有用途、有一致性、可定位来源的真实图片文件。不要只给提示词或口头建议冒充交付。
工作边界
- 默认使用 WorkWise 已配置的图片生成能力，不读取技能目录、用户目录或
.env 中的第三方密钥。
- 不自动上传完整文档到未经用户授权的第三方服务。
- 图片必须写入当前工作区或用户明确选择的输出目录。
- 生成失败、图片提供商未配置或输出未通过检查时，明确说明原因，不声称图片已经完成。
- 不虚构文档中不存在的人物、数据、品牌标识、工程现场或事实证据。
工作流
0. 图片能力门禁（任何读取、建目录或写计划之前）
- 先检查当前 Turn 的可用工具和运行时能力清单，确认存在已配置、可调用的 WorkWise 图片生成工具。
- 如果工具不存在、能力清单明确显示未配置，或缺少提供商/模型/凭据，立即停止；不要读取文档全文，不要创建
illustrations/，不要写配图计划，也不要给出一个看似真实但尚未生成的目标文件路径。
- 失败回复只需说明缺少哪项配置，并引导用户到“设置 → 图片生成”选择提供商、模型并完成连接测试。不得建议把文档或密钥复制到未授权的第三方服务。
- 只有能力门禁通过后，才进入以下内容分析和文件写入步骤。
1. 读取并建立内容地图
- 读取当前文档。PDF 或 Office 文件优先使用 WorkWise 文档解析结果；保留页码、标题和来源锚点。
- 提取文档目标、受众、语气、章节结构、关键概念和需要视觉解释的位置。
- 区分三类内容：
- 必须忠实表达的数据、流程、结构或事实。
- 可以抽象表现的概念、情绪和主题。
- 不应生成的敏感、未经证实或缺少授权的内容。
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. 生成图片
- 为每张图编写完整提示，至少包含：
- 主体、动作、环境和构图。
- 精确比例和安全边距。
- 统一配色、材质、光线和镜头语言。
- 必须忠实的事实约束。
- 需要避开的错误、文字乱码、品牌误用和多余元素。
- 使用 WorkWise 图片生成工具逐张生成，并把
output_path 指向 illustrations/assets/<计划文件名>；工具会按图片真实格式规范化扩展名。
- 输出到
illustrations/assets/，把工具返回的实际相对路径回写计划，不得把默认缓存路径冒充交付路径。
- 需要中文长句时，优先把正文留给文档排版，只在图片中保留极短标签，避免模型生成乱码。
5. 逐张检查并修正
每张图片都要检查：
- 文件真实存在、可打开且尺寸非零。
- 对具备视觉输入能力的模型：读取生成图片，核对主体、数量、方向、顺序、数据、关系、畸形、乱码、裁切、遮挡、水印和第三方商标误用。
- 对不具备视觉输入能力的模型：只能完成文件、格式、尺寸和计划映射检查，必须把视觉复核明确列为人工确认项，不得声称已经看过像素内容。
- 与计划中的插入位置和视觉目标一致。
- 同一套图片的色彩、材质和构图语言一致。
不合格图片最多重做两次。仍不合格时保留可用结果并报告具体缺陷，不自动无限重试。
6. 交付
最终回复必须包含：
- 已生成图片数量及相对路径。
- 每张图对应的文档位置。
- 未完成、降级或需要人工确认的项目。
- 可操作的成果文件卡片；至少支持打开、另存为和显示位置。
如果用户还要求把图片插入 Write 文档、报告或 PPT，应继续完成嵌入并验证目标文档，而不是只交付散图。
与其他能力协作
- 需要社交卡片排版时，将配图作为素材交给已获授权并可用的社交卡片 Skill。
- 需要正式演示文稿时，将配图和来源锚点交给 PPT Master；最终必须交付可验证的
.pptx。
- 需要编辑现有 Design 画板时，把生成图片插入当前设计文档，并确认切换文档后状态不串用。
来源
本技能基于 op7418/Document-illustrator-skill 的 MIT 版本进行 WorkWise 适配。具体提交、许可证和改动边界见 references/upstream.md。
