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。