zhy-article-illustrator

zhy-article-illustrator Purpose 为任意 Markdown 文章自动规划并生成配图。技能默认采用“高完成度编辑视觉”作为 全局质量基线：不是简单插画，不是装饰图标拼贴，也不是低信息密度草图。系统会先 为文章生成统一的 visual bible，再为每张图生成结构化提示词，使同一篇文章的配图 共享统一风格语言，同时根据章节内容调整构图、信息重点和版式。 默认优先兼容 Gemini Nano Banana 工作流，并默认走 Xiaomi Gemini 兼容接口；同时支持 Gemini 原生代理 / 中转站模式与官方 Gemini 接口。 When to Use 用户请求“为文章配图”、“illustrate article”、“add images to article” zhy-wechat-writing 技能的 Step 6 调用（ with_illustrations=true ） 用户希望生成更适合公众号场景的高完成度专题视觉 用户希望将本地图片上传到七牛云获取 CDN URL Prerequisites 文章 Markdown 文件已存在 已配置至少一种可用生图通道： Gemini 官方直连： GEMINI_API_KEY 或 GOOGLE_API_KEY Gemini 原生代理 / 中转站： IMAGE_PROVIDER=gemini 、 IMAGE_API_KEY 、可选 IMAGE_BASE_URL Xiaomi Gemini 兼容接口： IMAGE_PROVIDER=xiaomi 或 XIAOMI_API_KEY ，可选 XIAOMI_BASE_URL 若启用上传：七牛云配置已就绪（技能根目录 .env 中的 QINIU_ACCESS_KEY / QINIU_SECRET_KEY / QINIU_BUCKET / QINIU_DOMAIN ） Workflow Step 1: 分析文章 目标 ：理解文章结构，确定配图数量、位置与表达方式 操作 ： 读取 article_path 的完整内容 解析文章结构：标题、各章节标题（

/

）、段落数、代码块位置 识别核心信息点： 关键概念 / 术语解释 -> 适合信息图 对比 / 差异描述 -> 适合对比图 步骤 / 流程描述 -> 适合流程图 架构 / 框架描述 -> 适合架构图 数据 / 统计 -> 适合数据可视化 场景 / 叙事描述 -> 适合专题插画或编辑场景图 根据 density 确定配图策略： minimal ：仅为最核心的 1-2 个信息点配图 balanced ：每个

级主要章节配一张图 rich ：每 300 字左右或每个重要段落配一张图 确定 slug ： 若用户提供 slug ：直接使用 否则从文章 H1 标题推导 kebab-case 创建输出目录： {article_dir}/illustrations/{slug}/ 输出 ：文章结构分析结果、配图位置列表 Step 2: 生成 visual bible 与配图规划 目标 ：为整篇文章建立统一视觉基线，并生成每张图的规划信息 操作 ： 先生成文章级 visual_bible ，保存到 {article_dir}/illustrations/{slug}/visual-bible.md visual_bible 必须覆盖： quality_baseline ：统一采用高完成度编辑视觉 / 专题配图标准 visual_theme ：本篇文章的整体风格方向 color_system ：主色、辅色、强调色、背景倾向 graphic_language ：图形语言、线条/材质/光感、信息层级方式 layout_discipline ：页面留白、模块密度、标题区与内容区节奏 text_policy ：默认简体中文；仅 english_terms_whitelist 中的术语保留英文 negative_rules ：禁止简单画图、低幼卡通、无意义装饰、英文乱码、随意混搭风格 再对每个配图位置生成 outline 条目，至少包含： position ：插入位置（在哪个章节/段落之后） purpose ：这张图要传达什么信息 image_type ：对比图 / 流程图 / 架构图 / 数据图 / 场景图 / 编辑专题视觉 core_message ：本图唯一核心表达 content_blocks ：画面中必须出现的内容块 text_blocks ：图中需要出现的标题、标签、注释（默认中文） english_terms_used ：本图允许出现的英文术语子集 layout_hint ：布局方向与信息分区 filename ：输出文件名（格式： NN-简短描述.png ） alt_text ：Markdown 图片的 alt 文本 保存到 {article_dir}/illustrations/{slug}/outline.md 同时为每张图生成独立提示词文件，保存到 {article_dir}/illustrations/{slug}/prompts/ outline.md 格式 ：

article : <article_path

slug : <slug

density : <density

aspect_ratio : <ratio

prompt_profile : <profile

text_language : <language

image_provider : <provider

image_model : <model

image_count : <N

generated_at : <ISO timestamp

输出 ： visual_bible_path 、 outline_path Step 3: 生成图片 目标 ：根据 visual_bible + outline 生成高质量图片文件 操作 ： 为每张图构建结构化提示词，提示词必须同时继承： 全局质量基线：高完成度编辑视觉，而非简单画图 文章级 visual_bible 单图内容规划 提示词必须包含以下层次： 任务定位 ：这是可直接用于公众号文章的成品级专题视觉 风格锚点 ：复用本篇文章统一视觉语言 画面主体 ：核心对象、信息模块、前中后景关系 版式结构 ：标题区、内容区、对比区、流程区、数据区的组织方式 信息层级 ：主标题、次要标签、补充说明的优先级 文字规则 ：默认所有可见文字使用简体中文；仅白名单术语保留英文 质量要求 ：丰富细节、清晰层级、强版式感、避免模板感 禁止项 ：低幼、空泛、装饰性过强、无意义图标堆砌、英文乱码 对 Nano Banana / Gemini 类模型，优先优化以下特性： 画面信息完整、指令明确、元素具体 文本展示尽量短而准，避免大段说明文字 同一篇文章的每张图共享统一色系、统一图形语言、统一完成度 图片更像编辑专题视觉，而不是普通插图 将所有提示词保存到 {article_dir}/illustrations/{slug}/prompts/ 目录 调用本技能内置脚本生成图片： 脚本路径： scripts/image-gen.ts 参数： --prompt "<提示词内容>" --output "<输出路径>" --ar <宽高比> 可选： --provider gemini|google|xiaomi|openai 可选： --model <模型名> 可选： --base-url 可选： --api-key <临时 key> 可选： --image-size <清晰度/尺寸标识> （如 Xiaomi 的 1K ） 可选： --ref <参考图路径> （Gemini 多模态场景） 并行生成 ：建议最多 4 个并发 若需要一键完成规划 + 生图 + 插回文章，可直接调用： node scripts/illustrate-article.ts --article < article.md

若使用 Xiaomi Gemini 兼容接口，可补充： --image-provider xiaomi --image-model gemini-3-pro-image-preview --image-size 1K 失败处理： 单张失败 -> 重试一次，可微调提示词中的布局、文字密度或禁止项 仍失败 -> 记录到失败列表，继续下一张 不中断整体流程 输出 ：图片文件列表、失败列表 Step 4: 上传图床（可选） 触发条件 ： upload=true 目标 ：将生成的图片上传到七牛云，获取 CDN URL 操作 ： 检查七牛云配置：读取技能根目录 .env 调用上传脚本： bun run scripts/qiniu-upload.ts --file < 本地路径

--key < 远程路径

远程 key 格式： illustrations/{slug}/{filename} 逐张上传，记录每张的 CDN URL 上传失败时保留本地路径，不中断流程 输出 ： uploaded_urls 列表（CDN URL 或 null ） Step 5: 插入文章副本 目标 ：创建带有图片引用的文章副本 操作 ： 复制 article_path 为 article.illustrated.md （同目录） 在 outline 指定的每个位置插入图片引用： 若已上传（有 CDN URL）： 若未上传： 对生成失败的图片，插入占位注释：

输出完成摘要： illustrated_article_path 成功 / 失败 / 上传统计 失败图片列表及原因 输出 ： illustrated_article_path Data Flow article.md | v Step 1: 分析文章结构 -> 配图位置列表 | v Step 2: 生成 visual-bible.md + outline.md | v Step 3: 生成结构化 prompts -> illustrations/{slug}/*.png | v Step 4: (--upload) 上传七牛云 -> CDN URLs | v Step 5: 插入副本 -> article.illustrated.md Error Handling 失败场景 处理方式 文章文件不存在 立即报错退出 Gemini / 代理配置缺失 提示用户配置 IMAGE_PROVIDER 、 IMAGE_API_KEY 、可选 IMAGE_BASE_URL ，或回退到官方 GEMINI_API_KEY Xiaomi 接口配置缺失 提示用户配置 IMAGE_PROVIDER=xiaomi 或 XIAOMI_API_KEY ，并按需设置 XIAOMI_BASE_URL / XIAOMI_IMAGE_SIZE 单张图片生成失败 重试一次；仍失败记录跳过，继续下一张 文字过多导致效果差 精简标题/标签/注释长度后重试 七牛云配置缺失 提示用户配置技能根目录 .env ，跳过上传步骤 七牛云上传失败 保留本地路径，记录错误，继续下一张 slug 目录已存在 直接使用（覆盖同名文件） Example Usage 默认 Nano Banana 风格配图 ： article_path : articles/playwright - introduction/article.md density : balanced prompt_profile : nano - banana text_language : zh - CN image_provider : xiaomi image_model : gemini - 3.1 - flash - image - preview image_base_url : https : //your - compatible - endpoint.example/v1beta image_size : 1K upload : false 通过 Gemini 原生代理生图 ： article_path : articles/playwright - introduction/article.md density : balanced image_provider : gemini image_model : gemini - 3.1 - flash - image - preview image_base_url : https : //your - relay.example.com/v1beta upload : false 通过 Xiaomi Gemini 兼容接口生图 ： article_path : articles/playwright - introduction/article.md density : balanced image_provider : xiaomi image_model : gemini - 3.1 - flash - image - preview image_base_url : https : //your - compatible - endpoint.example/v1beta image_size : 1K upload : false 指定英文白名单术语 ： article_path : articles/playwright - introduction/article.md english_terms_whitelist : - Playwright - Chromium - Firefox - WebKit Notes 全局质量基线固定为高完成度编辑视觉，不生成简单装饰图 不同文章可以有不同视觉风格，但同一篇文章内必须共享统一风格体系 默认所有可见文字使用简体中文；仅白名单术语保留英文 始终创建副本（ article.illustrated.md ），不修改原文 图片引用强制使用相对路径和 / 分隔符（本地模式） 提示词保存到 prompts/ 目录，便于追溯和手动调整后重新生成 可使用 bun run scripts/plan-illustrations.ts --article 自动生成 visual-bible.md 、 outline.md 和 prompts/ 可使用 node scripts/illustrate-article.ts --article 一键完成规划、出图和 article.illustrated.md 生成 Xiaomi/Gemini 兼容接口可通过 image_provider=xiaomi 与自定义 image_base_url 配置；开源仓库不预设任何私有中转地址