云端生图工作流#

仓库已内置 GitHub Actions：Generate AI Images，采用三阶段独立流水线架构，可在云端生成图片并自动提交到 static/images/ai/。

三阶段流水线#

阶段1: 内容总结（所有风格共享）
  → 读取页面/全站内容，生成结构化英文摘要
阶段2: 提示词生成（每种风格各1次）
  → 基于摘要 + 风格指导，生成英文生图提示词
阶段3: 图片生成（每种风格各1次）
  → 调用生图模型，解析并保存图片

每阶段独立重试（默认最多 3 次，指数退避），某个风格失败只跳过该风格，不影响其他风格。阶段1 失败则整体中止。

必需配置#

在仓库设置中添加：

IMAGE_BASE_URL（Variables）— OpenAI 兼容代理地址
IMAGE_MODEL（Variables）— 默认模型名称
IMAGE_API_KEY（Secrets）— API 密钥

触发方式#

打开 GitHub Actions。
选择 Generate AI Images。
点击 Run workflow。
选择 input_mode：
- page — 基于单个页面内容生成（默认）
- site — 遍历全站 content/ 下所有 .md 文件
- custom — 跳过阶段1+2，直接使用自定义 prompt 生图
选择 style（both/minimal/tech）。
可选填写 model、prefix。
若使用 custom，填写 custom_prompt。
可选设置 summarizer_model（阶段1模型，默认同生图模型）。
可选设置 prompt_builder_model（阶段2模型，默认同生图模型）。
可选设置 page_content_path（默认 content/_index.md）。
可选设置 max_retries（每阶段最大重试次数，默认 3）。
如需自动替换首页与目录主视觉引用，将 replace_home_hero 设为 true。
如需生成后自动触发 Pages 部署，将 auto_deploy_after_generate 设为 true。

参数一览#

参数	说明	默认值
`input_mode`	site/page/custom	page
`page_content_path`	page 模式目标文件	content/_index.md
`custom_prompt`	custom 模式直接提供 prompt	—
`style`	both/minimal/tech	both
`model`	覆盖生图模型	—
`summarizer_model`	阶段1模型	—
`prompt_builder_model`	阶段2模型	—
`prefix`	文件名前缀	hero-ai
`max_retries`	每阶段最大重试	3
`replace_home_hero`	替换首页图片引用	false
`auto_deploy_after_generate`	自动触发部署	false

生成产物#

图片目录：static/images/ai/
清单文件：static/images/ai/manifest.json
版本化清单：static/images/ai/manifest-YYYYMMDD-HHMMSS.json

脚本会优先使用 URL 类型图片载荷并下载落盘；若接口返回 base64，也会自动解码后保存为本地图片文件。

manifest.json 结构#

{
  "pipelineVersion": "2.0",
  "inputMode": "page",
  "style": "both",
  "baseUrl": "...",
  "model": "...",
  "models": {
    "summarizer": "...",
    "promptBuilder": "...",
    "imageGenerator": "..."
  },
  "summary": "阶段1生成的摘要文本",
  "generatedAt": "...",
  "images": [
    {
      "name": "minimal",
      "prompt": "最终生图提示词",
      "promptSource": "pipeline",
      "summary": "使用的摘要",
      "model": "...",
      "summarizerModel": "...",
      "promptBuilderModel": "...",
      "file": "static/images/ai/hero-ai-minimal-1.png",
      "generatedAt": "..."
    }
  ]
}

自动替换主视觉（可选）#

当 replace_home_hero=true 时，工作流会自动更新：

content/_index.md
content/docs/_index.md

将主视觉图片引用替换为本次生成的图片路径。

生成后自动部署（可选）#

当 auto_deploy_after_generate=true 时：

若本次生成有文件变化并成功提交到 main，会由 push 自动触发 deploy.yml。
若本次没有文件变化（未产生新提交），工作流会主动调用 workflow_dispatch 触发 deploy.yml。

三种输入模式说明#

page 模式（默认）#

读取指定页面内容（默认 content/_index.md），经阶段1总结后生成贴合页面内容的图片。

site 模式#

遍历 content/ 下所有 .md 文件，拼接内容后经阶段1总结，生成反映全站主题的图片。

custom 模式#

跳过阶段1（内容总结）和阶段2（提示词生成），直接使用用户提供的 custom_prompt 进入阶段3生图。

建议参数：

input_mode: page
style: both
model: gemini-3-pro-image-preview