zhy-article-illustrator

zhy-article-illustrator

目的

任意の Markdown 文章について、挿絵を自動で計画し生成します。このスキルでは、デフォルトで 「高い完成度の編集ビジュアル」を全体的な品質基準として採用します。単純なイラストでも、 装飾アイコンの寄せ集めでも、情報密度の低いラフスケッチでもありません。まず文章全体の visual bible を作成し、次に各画像の構造化プロンプトを生成します。これにより、同じ文章内の 挿絵で一貫したスタイルを共有しつつ、章の内容に応じて構図、情報の重点、レイアウトを調整します。

デフォルトでは Gemini Nano Banana ワークフローとの互換性を優先し、Xiaomi Gemini 互換インターフェースを使用します。また、Gemini ネイティブのプロキシ／中継サーバーモードと公式 Gemini インターフェースにも対応しています。

使用する場面

• ユーザーが「文章に挿絵を付けて」「記事をイラスト化して」「記事に画像を追加して」と依頼した場合
• zhy-wechat-writing スキルの Step 6 から呼び出す場合（with_illustrations=true）
• ユーザーが WeChat 公式アカウント向けの、高い完成度の特集ビジュアルを生成したい場合
• ユーザーがローカル画像を Qiniu Cloud にアップロードして CDN URL を取得したい場合

前提条件

• 文章の Markdown ファイルが存在すること
• 利用可能な画像生成経路が少なくとも 1 つ設定されていること：
  • 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
  • アップロードを有効にする場合：Qiniu Cloud の設定が完了していること（スキルのルートディレクトリにある .env の QINIU_ACCESS_KEY / QINIU_SECRET_KEY / QINIU_BUCKET / QINIU_DOMAIN）

ワークフロー

Step 1: 文章を分析する

目標：文章の構成を把握し、挿絵の枚数、位置、表現方法を決定します。

操作：

1. article_path の全文を読み取る
2. 文章の構成を解析する：タイトル、各章の見出し（## / ###）、段落数、コードブロックの位置
3. 重要な情報を特定する：
   • 重要な概念／用語の説明 -> インフォグラフィックに適しています
   • 比較／相違点の説明 -> 比較図に適しています
   • 手順／プロセスの説明 -> フローチャートに適しています
   • アーキテクチャ／フレームワークの説明 -> アーキテクチャ図に適しています
   • データ／統計 -> データビジュアライゼーションに適しています
   • シーン／ストーリーの説明 -> 特集イラストまたは編集用シーン画像に適しています
4. density に応じて挿絵の方針を決定する：
   • minimal：最も重要な 1～2 個の情報だけに挿絵を付けます
   • balanced：各 ## レベルの主要な章に 1 枚ずつ画像を付けます
   • rich：およそ 300 字ごと、または重要な段落ごとに 1 枚画像を付けます
5. slug を決定する：
   • ユーザーが slug を指定している場合：その値をそのまま使用します
   • それ以外の場合：文章の H1 タイトルから kebab-case を導出します
6. 出力ディレクトリを作成する：{article_dir}/illustrations/{slug}/

出力：文章の構成分析結果、挿絵の配置リスト

Step 2: visual bible と挿絵の計画を作成する

目標：文章全体の統一されたビジュアル基準を確立し、各画像の計画情報を作成します。

操作：

1. まず文章全体の visual_bible を作成し、{article_dir}/illustrations/{slug}/visual-bible.md に保存します
2. visual_bible には以下を必ず含めます：
   • quality_baseline：一貫して高い完成度の編集ビジュアル／特集挿絵の基準を採用する
   • visual_theme：この記事全体のスタイルの方向性
   • color_system：メインカラー、サブカラー、アクセントカラー、背景の傾向
   • graphic_language：グラフィック表現、線／素材／光の表現、情報階層の表現方法
   • layout_discipline：ページの余白、モジュールの密度、タイトル領域とコンテンツ領域のリズム
   • text_policy：デフォルトは簡体字中国語とし、english_terms_whitelist に含まれる用語のみ英語のままにする
   • negative_rules：単純な描画、幼児向けのカートゥーン、意味のない装飾、英語の文字化け、無秩序なスタイルの混在を禁止する
3. 次に、各挿絵の配置箇所について outline の項目を作成します。最低限、以下を含めます：
   • position：挿入位置（どの章／段落の後か）
   • purpose：この画像で伝える情報
   • image_type：比較図／フローチャート／アーキテクチャ図／データ図／シーン図／編集用特集ビジュアル
   • core_message：この画像で伝える唯一の核心的なメッセージ
   • content_blocks：画面に必ず含めるコンテンツブロック
   • text_blocks：画像内に含めるタイトル、ラベル、注釈（デフォルトは中国語）
   • english_terms_used：この画像に含めてよい英語用語のサブセット
   • layout_hint：レイアウトの方向性と情報の区分
   • filename：出力ファイル名（形式：NN-短い説明.png）
   • alt_text：Markdown 画像の alt テキスト
4. {article_dir}/illustrations/{slug}/outline.md に保存します
5. 各画像について個別のプロンプトファイルも作成し、{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 に基づいて、高品質な画像ファイルを生成します。

操作：

1. 各画像の構造化プロンプトを作成します。プロンプトには以下をすべて反映させます：
   • 全体的な品質基準：単純な描画ではなく、高い完成度の編集ビジュアル
   • 文章全体の visual_bible
   • 画像ごとのコンテンツ計画
2. プロンプトには以下の階層を必ず含めます：
   • タスクの位置付け：WeChat 公式アカウントの記事にそのまま使える、完成品レベルの特集ビジュアルであること
   • スタイルの基準点：この記事に統一されたビジュアル表現を再利用すること
   • 画面の主体：中心となるオブジェクト、情報モジュール、前景／中景／背景の関係
   • レイアウト構成：タイトル領域、コンテンツ領域、比較領域、フロー領域、データ領域の構成方法
   • 情報階層：メインタイトル、補助ラベル、補足説明の優先順位
   • 文字のルール：デフォルトでは、表示される文字をすべて簡体字中国語にすること。ホワイトリストに含まれる用語のみ英語のままにすること
   • 品質要件：豊かなディテール、明確な階層、強いレイアウト感、テンプレートのような印象を避けること
   • 禁止事項：幼児向け、内容が漠然としているもの、装飾過多、意味のないアイコンの羅列、英語の文字化け
3. Nano Banana／Gemini 系モデルでは、以下の特性を優先して最適化します：
   • 画面内の情報を網羅し、指示を明確にし、要素を具体的にする
   • 表示するテキストは短く正確にし、長い説明文を避ける
   • 同じ文章の画像すべてで、色調、グラフィック表現、完成度を統一する
   • 一般的な挿絵ではなく、編集用の特集ビジュアルに仕上げる
4. すべてのプロンプトを {article_dir}/illustrations/{slug}/prompts/ ディレクトリに保存します
5. このスキルに組み込まれたスクリプトを呼び出して画像を生成します：
   • スクリプトのパス：scripts/image-gen.ts
   • パラメーター：--prompt "<プロンプトの内容>" --output "<出力先>" --ar <アスペクト比>
   • 任意：--provider gemini|google|xiaomi|openai
   • 任意：--model <モデル名>
   • 任意：--base-url <Gemini ネイティブプロキシのベース URL>
   • 任意：--api-key <一時的な key>
   • 任意：--image-size <解像度／サイズの識別子>（Xiaomi の 1K など）
   • 任意：--ref <参照画像のパス>（Gemini のマルチモーダルシナリオ）
   • 並列生成：同時実行は最大 4 件を推奨します
6. 計画、画像生成、文章への挿入を一括で完了する場合は、次を直接呼び出します：

   node scripts/illustrate-article.ts --article <article.md>
   

   • Xiaomi Gemini 互換インターフェースを使用する場合は、--image-provider xiaomi --image-model gemini-3-pro-image-preview --image-size 1K を追加できます
7. 失敗時の処理：
   • 1 枚だけ失敗した場合 -> 1 回再試行します。プロンプトのレイアウト、文字量、禁止事項を微調整できます
   • それでも失敗した場合 -> 失敗リストに記録し、次の画像に進みます
   • ワークフロー全体は中断しません

出力：画像ファイルのリスト、失敗リスト

Step 4: 上传图床（可选）

触发条件：upload=true

目标：将生成的图片上传到七牛云，获取 CDN URL

操作：

1. 检查七牛云配置：读取技能根目录 .env
2. 调用上传脚本：

   bun run scripts/qiniu-upload.ts --file <本地路径> --key <远程路径>
   

3. 远程 key 格式：illustrations/{slug}/{filename}
4. 逐张上传，记录每张的 CDN URL
5. 上传失败时保留本地路径，不中断流程

输出：uploaded_urls 列表（CDN URL 或 null）

Step 5: 插入文章副本

目标：创建带有图片引用的文章副本

操作：

1. 复制 article_path 为 article.illustrated.md（同目录）
2. 在 outline 指定的每个位置插入图片引用：
   • 若已上传（有 CDN URL）：![alt_text](CDN_URL)
   • 若未上传：![alt_text](illustrations/{slug}/{filename})
3. 对生成失败的图片，插入占位注释：

4. 输出完成摘要：
   • 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 <article.md> 自动生成 visual-bible.md、outline.md 和 prompts/
• 可使用 node scripts/illustrate-article.ts --article <article.md> 一键完成规划、出图和 article.illustrated.md 生成
• Xiaomi/Gemini 兼容接口可通过 image_provider=xiaomi 与自定义 image_base_url 配置；开源仓库不预设任何私有中转地址