图解文档 · Document Visuals

为 Markdown 文档智能分析插图位置，并行生成/检索图片，输出带插图的增强版文档。

Triggers

Activate when

• 用户要求“给文章配图”“补插图”“生成文章插画”或“illustrate this document”。
• 用户希望为长文规划真实素材、对照图、过程图、数据图表或程序化合成图。

Do not activate when

• 用户只要求生成一张独立图片，不需要文章级选图、插入与视觉节奏；使用对应图像 Skill。
• 用户只要求给现有图片加 Caption、边框或 Logo；使用 lov-image-decorator。
• 用户要求发布公众号文章或修改远端草稿；使用 lov-publish-wechat-article。
• 用户只要求审阅正文内容，不需要插图规划或图片文件。

参数格式

<file_path> [--auto] [--style <style>] [--max <n>]

• file_path: 必填，md文件路径
• --auto: 跳过确认，直接生成
• --style: 图片风格（默认：从 design-guide.md 读取，回退 warm-academic）
• --max: 最大插图数量（默认：不限，由AI决定）

工作流

Step 1: 读取文档 + 加载品牌风格

1. 读取目标文档
2. 尝试读取 ${SKILL_WORKSPACE_ROOT}/design/design-guide.md，提取 AI 生图 prompt 模板和色彩体系
3. 如果存在品牌风格，后续所有 AI 生图 prompt 必须注入品牌色彩和质感关键词
4. 如果计划制作包含可编辑文字的 HTML、SVG、Canvas、Pillow 或其他程序化合成图， 必须完整读取 references/text-rendering-safety.md，并在方案中登记文本语言与字体来源

Step 2: 分析文档结构 + 实体提取

分析：

• 文章结构（标题层级、段落分布）
• 内容主题（每个章节的核心概念）
• 情绪节奏（叙事高潮、转折点）
• 已有图片位置
• 数据密集区域（表格、多产品/多概念并列对比）
• 可量化信息（ARR、用户数、增长率等需要图表的数据）

关键步骤：实体与证据候选提取（必做）

在规划插图前，先逐段扫描文档，列出所有可联网检索的真实实体：

| 实体 | 类型 | 出现位置 | 可检索素材 |
|------|------|---------|-----------|
| Cursor IDE | 产品 | L12 | 产品界面截图、博文封面 |
| Sam Altman | 人物 | L45 | 新闻照片 |
| GPT-4发布会 | 事件 | L78 | 发布会现场照片 |
| arXiv:2602.11988 | 论文 | L199 | 论文图表 |
| github.com/openai/symphony | 开源项目 | L121 | GitHub页面截图、终端UI |

实体类型覆盖：产品/工具、人物、公司、事件、地点、论文/研究、博客文章、开源项目、终端/CLI 界面

这张表是后续插图方案的候选输入，不是图片配额。只有素材能帮助读者理解论点、验证 现场、看见变化或获得必要视觉休息时才进入方案；正文已经清楚、图片只会机械重复时 可以不配。真实人物与活动素材还要记录授权状态、来源场景和能否公开组合。

Step 3: 规划插图方案

为每个建议插图位置生成方案（必须标注关联实体和搜索策略）：

| # | 位置 | 插图主题 | 类型 | 关联实体 | 搜索策略/prompt |
|---|------|---------|------|---------|----------------|
| 1 | L12 | ELIZA对话界面 | 联网检索 | ELIZA | "ELIZA chatbot original screenshot" |
| 2 | L47 | Web演进时间线 | AI生图 | 无（纯抽象） | editorial timeline illustration... |
| 3 | L136 | ARR增长对比 | 数据图表 | Notion/Airtable/Linear | 先调研数据再绘制 |
| ...

类型决策树（按优先级）

该插图是否涉及真实产品/人物/事件/地点？
├─ 是 → 联网检索（产品截图、历史照片、官方图表、新闻图片）
│       └─ 搜不到合适素材？→ AI生图（概念化表达）
└─ 否 → 该插图是否涉及可量化数据？
         ├─ 是 → 数据图表（先调研获取可溯源数据，再绘制）
         └─ 否 → 是否需要精确、可编辑的文字或结构？
                  ├─ 是 → 程序化合成图（HTML/SVG/Canvas 等）
                  └─ 否 → AI生图（概念插画）

硬性规则（违反则方案不合格）：

1. 价值驱动而非实体配额：每张图必须至少承担证据、解释、对比、过程或节奏中的 一项任务；无法说明读者收益时删除，不因文章提到某个实体就强制配图。
2. 真实实体优先真实素材：产品、事件、论文、项目和公共人物优先使用可溯源截图、 照片或原图。只有用户提供了合法输入并明确要求风格化、编辑或概念化表达时，才用 生成式模型处理真实实体，并如实标注 provenance。
3. 来源场景一致：同一组对照或合成图中的人物、活动与原图必须来自文章所述场景。 获得授权只解决权利问题，不代表其他场合的素材适合混入当前公共叙事。
4. 原图真源：比较“原图 / 结果”时，原图必须回到活动相册、相机文件或经核验的 原始附件，不能把裁切图、风格化结果或聊天缩略图误当原图。
5. AI 占比自检：AI 图较多时逐张复核是否真的需要，以及是否会把可验证事实变成 虚构视觉；不设置机械百分比门槛。
6. 生成方式如实标注：联网素材合成、程序化排版、数据图表、生成式编辑与纯生成 是不同 provenance；不得互相冒充。

特殊类型：Hero Image（可选）

Hero 只在它能提供封面之外的新信息、建立强现场或显著提升首屏吸引力时使用。不要 为了模板完整生成“全文摘要图”，也不要让一张高大的概念图把真正的开头和证据推到 首屏之外。已有高质量人物照、结果对照或正文首图能够完成任务时，省略额外 Hero。

Step 4: 用户确认（除非 --auto）

使用 宿主的聚焦提问工具 展示插图方案表格，让用户：

• 确认/删除/调整每个插图位置和类型
• 选项：「全部确认」「我来调整后继续」

Step 5: 数据调研（如有数据图表类型）

如果方案中包含「数据图表」类型的插图：

1. 逐项调研每个数据主题，获取带来源的精确数据点
2. 汇总数据表格，展示给用户确认数据准确性
3. 确认后再生成图表

数据图表的prompt必须包含：

• 每个数据点的精确数值
• 图表底部标注数据来源（Sources: ...）
• 使用品牌色彩体系

Step 6: 并行生成图片

确认后，使用 Task 工具并行处理每张图片：

AI生图流程：

• 优先调用当前宿主已经提供的图像生成工具或 Plugin 能力
• 若宿主只提供本地脚本，由使用者显式传入脚本路径；不得依赖某个客户端专属环境变量
• 输出到 <doc_dir>/attachments/ill-<n>-<slug>.png，并保留 prompt 与生成方式收据

Prompt 构建规则：

• 基于文章上下文生成详细英文 prompt
• 注入品牌风格（从 Step 1 加载的 design-guide 提取关键词）
• 默认风格关键词：warm off-white background (#F9F9F7), terracotta (#CC785C) accents, charcoal (#181818) text, matte paper texture, editorial illustration style
• 避免文字/人脸（AI生图弱点）——数据图表除外
• 宽幅构图（适合文章内嵌）

联网检索流程：

• 使用 Task 工具并行搜索
• 优先官方素材、公开图表
• curl 下载到 attachments/ 目录
• 验证下载文件是有效图片（file 命令检查）

数据图表流程：

• 使用 Step 5 调研获得的精确数据构建 prompt
• prompt 中列出每个数据点的精确数值
• 图表底部必须标注来源
• 使用 -q high 生成更高精度

程序化合成图流程：

• 使用 HTML/CSS、SVG、Canvas 或等价确定性工具排版精确文字、图表和资料卡片
• 每个文本 run 必须声明正确 lang，并使用与该语言匹配且覆盖全部字符的显式字体栈
• 中日文并列或混排时拆成独立语言 run；禁止把日文字体放在简中 run 的首位，反之亦然
• 在截图或栅格化前执行 references/text-rendering-safety.md 的字体覆盖与实际字体门禁
• Chromium 页面可使用 scripts/audit_html_fonts.py 生成机器可读字体收据；ok=false 时不得交付图片
• 记录合成源、素材来源、请求字体、实际字体、语言和输出图片的对应关系

Step 6.4: 文字渲染门禁（含文字图片必做）

1. 按语言 run 检查字符覆盖，任何正文字符缺字都必须先修复字体栈，不能依赖未知系统 fallback
2. 对最终截图所用的真实浏览器回读实际 PostScript 字体与 glyph count，不能只检查 CSS 声明
3. 纯简中或纯日文 run 默认只允许一套 CJK 字体；有意混植必须在方案和收据中逐项声明
4. lang 只负责语言语义和本地化字形选择，不会自动跳过字体栈首位的错误区域字体
5. 图片栅格化后 fallback 已固化，公众号、Markdown 或下游 CSS 无法修复；门禁必须发生在导出前

Step 6.5: 图片质量校验

对每张下载/生成的图片，使用 Read 工具查看验证：

• 联网检索图：确认内容匹配目标产品（非同名但不同的产品、非无关图片）
• AI生图：确认视觉主题与 alt 描述一致
• 程序化合成图：确认字体收据 ok=true，并人工查看 CJK 字形、基线、标点和换行
• 所有图片：记录像素尺寸、宽高比和按文章正文宽度渲染后的预计高度；单张图过高、 上下留白显著或连续多张占据多个手机屏幕时，必须裁切、重排或删除。
• 过程 / 对照图：只保留视觉上不同且推动理解的阶段，删除重复帧和过早出现的最终 状态；统一子图视觉尺寸与间距，把真正变化的区域放大，背景保持中性，不额外套用会 干扰比较的目标风格。
• 生成式人物图：检查脸、身体、手指、服装、饰品与物件是否符合源图和真实世界； 过程只展示真实发生过的调试状态，不为叙事补造畸形或失败帧。
• 不合格的图片重新搜索/生成

Step 7: 组装输出

在原文档的指定位置插入图片引用：

Markdown 中写入一条标准图片引用，alt 描述读者需要的内容，路径使用实际生成文件； 例如 !\[描述性 alt\]\(attachments/ill-N-slug.png\)。

Caption 与图内文字

1. Caption 是面向读者的编辑文案，不是图片内容的机械复述。读者一眼可见的信息无需 再写；没有证据、归属或理解任务时宁可不写 Caption。
2. 图内烧录文字、Decorator Caption 与 Markdown 图注只能保留一种。图片已经自带 标题或说明时，删除外部重复图注；需要可访问性的信息留在 alt，不再作为第二份文案。
3. 过程图的文字只点出本质变化，例如“基于真实世界修复模型常识性错误”；不要为每 张子图写长句解释肉眼可见的动作、数量和位置。
4. 来源与引申资料在对应位置低调呈现；多项资料逐项分行或分点，不堆到文章底部。

精确插入定位规则（必须逐条检查）

Step 3 规划的是章节级粗略位置，Step 7 组装时必须精确到段落级。逐张图执行以下检查：

1. 先提后图：图片必须插在其所配内容首次被提及之后，不得出现在内容之前。例：报告截图必须在报告被引用/讨论之后，不能在报告被提及的上一个章节末尾。
2. 不割裂语义单元：以下结构视为不可分割的语义单元，图片不得插入其内部：
   • 连续引用块（多个 > blockquote 属于同一论述）
   • 递进/收束段落对（"A是什么...→ 所以A意味着..."）
   • 论点+论据（"观点。 具体展开..."）
   • 排比/并列结构（"第一...第二...第三..."）
3. 收束优先：如果一个概念有明确的收束句（"会说，即会做。""数据不会说谎。"等金句/总结），图片应插在收束句之后而非之前。
4. 自检方法：插入后，朗读图片前后各1-2段。如果读起来感觉"话说到一半被打断"，则位置错误，需下移到语义完整处。

文件命名规则：

• 图片：ill-<序号>-<语义slug>.png（如 ill-5-arr-comparison.png）
• 输出文档：原文件名加 -illustrated 后缀（如 v5-illustrated.md）

Step 8: 完成报告

输出简要报告：

• 生成了 N 张插图（X 联网检索 + Y AI生图 + Z 数据图表 + W 程序化合成图）
• 输出文件路径
• 对含文字图片提供字体审计收据路径与实际字体摘要
• 用 Read 工具展示一张代表性图片预览

插图位置选择原则

1. 证据优先：真实现场、聊天、结果和变化过程优先于装饰性概念图。
2. Hero 可省略：正文首图或第一组证据已经有吸引力时，不再叠加摘要型 Hero。
3. 移动端视觉预算：同时看图片数量、宽高比、预计屏高、相邻空白与连续图片长度； 没有固定“每多少字一张”或“每节至少几张”的配额。
4. 概念转换处：只有图片能真正帮助换挡时才作为分隔，不用空泛配图切断论证。
5. 数据横比：多个并列产品或概念优先一张清楚的对比图，而不是逐个配图。
6. 演变过程：用最少的不同阶段说明变化；子图数量、尺寸和间距服从信息差异， 不为凑齐网格复制帧。
7. 情绪高潮：优先真实照片、对话或结果；生成式插图不能替代真实关系与现场。

Execution boundary

自然语言请求即可触发；无需旧 slash 路径、参数插值或指定助手。明确解析当前请求中的 项目、目标文件、选项与输出位置；用当前宿主实际提供的文件、搜索、CLI 和浏览器能力。 项目依赖版本与外部 API 在执行时核实，不能假设示例是现行配置。随包脚本从 Skill 根解析， 业务文件从目标项目根解析。先读当前状态，保护已有未提交内容与其他任务的暂存区。 分析、预览请求保持只读；修改、提交、推送、部署和发布各依当前请求的明确范围执行。 不绕过保护、自动发送消息、强制结束用户进程或抢前台。失败保留可诊断原始错误。

Composition

执行前读取 能力组合，按明确制品交接相邻能力。

Runtime context (shared)

运行前读取本包 skill.yaml 与 Profile 合同。优先级为当前请求、 项目上下文、本 Skill records、共享 preferences、brand/user Profile、安全默认值。 只读取声明字段；没有专用运行时的宿主可使用 scripts/profile_store.py 读取共享 Profile。 配置缺失只问影响结果的一个问题。用户明确要求长期保存的值通过该脚本原子写入， 报告实际路径；不保存推断、凭据或其他任务的资料。