scientific-agent-skills 智能迭代精修指南：信息图生成中的「生成-评审-精修」循环与 CLI 全参数解析

导读

本文聚焦 scientific-agent-skills 仓库中 infographics 技能的核心机制 —— Smart Iterative Refinement（智能迭代精修）：由 Nano Banana Pro 生成信息图，由 Gemini 3.6 Flash 按五维评分标准做质量评审，只有当评分低于文档类型阈值时才触发重生成，从而以最少的 API 调用获得满足质量门槛的成品。读完本文，你将掌握该 generate-review-refine 循环的完整工作流、五维质量评审标准、Review Log 日志结构，以及 generate_infographic.py 的全部命令行参数与配置方式，并能结合源码理解提前停止（early stop）、评分解析等底层实现原理。

---

一、Smart Iterative Refinement：生成-评审-精修循环

infographics 技能的核心并非"一次生成"而是"闭环校验"。其完整流程如下：

┌─────────────────────────────────────────────────────┐
│  1. Generate infographic with Nano Banana Pro       │
│                    ↓                                │
│  2. Review quality with Gemini 3.6 Flash            │
│                    ↓                                │
│  3. Score >= threshold?                             │
│       YES → DONE! (early stop)                      │
│       NO  → Improve prompt, go to step 1            │
│                    ↓                                │
│  4. Repeat until quality met OR max iterations      │
└─────────────────────────────────────────────────────┘

每一步在源码中都有对应实现（见 generate_infographic_ai.py 的 InfographicGenerator.generate_iterative()，第 1102 行起）：

1. 生成：generate_image() 携带完整设计指南调用 Nano Banana Pro（self.image_model = "google/gemini-3.1-flash-image"，第 434 行），请求 modalities=["image", "text"]；
2. 评审：review_image() 将已保存的迭代图片转成 base64 data URL，连同评审提示词交给 Gemini 3.6 Flash（self.review_model，第 436 行）做视觉质量打分；
3. 决策：比较得分与 doc_type 对应的质量阈值，not review.needs_improvement 即提前停止；
4. 精修：若分数低于阈值且未耗尽迭代次数，improve_prompt() 会把评审意见（critique）注入下一轮生成提示词，要求"修复评审中提到的全部问题、保持类型与风格、达到出版级质量"。

每轮迭代产出的图片保存为 {base_name}_v{i}{extension}（如 figures/exercise_v1.png、exercise_v2.png），最终达标版本会被复制到 -o 指定的输出路径，因此版本化图片与最终成品会同时保留。

提前停止（Early Stop）的收益

从 SKILL.md 的 "Smart Iteration Benefits" 一节可以看到该机制的设计动机：

• 首轮生成即达标时节省 API 调用，不再空转；
• 营销材料要求更高门槛，质量有保障；
• 草稿/内部用途门槛更低，周转更快；
• 每种使用场景获得"恰好合适"的质量，而不是一刀切。

代码层面的关键证据：results["early_stop"] = True 只在 not review.needs_improvement 分支触发（generate_infographic_ai.py），且提前停止时输出 Iterations Used: N/M (early stop)。

---

二、五维质量评审标准

Gemini 3.6 Flash 在每一轮迭代中，会以评审提示词（源码第 901-959 行）对信息图从五个维度打分，每个维度 0-2 分，总分 0-10 分：

维度	分值	评审要点
1. Visual Hierarchy & Layout（视觉层级与布局）	0-2	清晰的视觉层级、逻辑阅读流、平衡构图、充足留白
2. Typography & Readability（字体与可读性）	0-2	文本可读且字号合适、标题醒目、无重叠拥挤、字体统一
3. Data Visualization（数据可视化）	0-2	数字与统计醒目、图表/图标清晰准确、数据一眼可懂、标签齐全
4. Color & Accessibility（色彩与无障碍）	0-2	配色和谐专业、对比度足够、色盲友好、色彩支撑内容层级
5. Overall Impact & Professionalism（整体效果）	0-2	专业精致、有吸引力、无视觉瑕疵、达成沟通目标

评审模型被要求以严格格式输出，便于程序解析：

SCORE: [total score 0-10]

STRENGTHS:
- [strength 1]

ISSUES:
- [issue 1]

SPECIFIC_IMPROVEMENTS:
- [specific improvement 1]

VERDICT: [ACCEPTABLE or NEEDS_IMPROVEMENT]

源码中的评分解析细节

从 generate_infographic_ai.py 顶部的解析器可以看到几个工程化细节：

• _normalize_review_text() 用正则 [*_#]剥掉模型常见的 Markdown 装饰（Gemini 常输出SCORE: 8.5而非裸的SCORE: 8.5`），避免因格式不符而误判；
• _parse_score() 同时匹配 SCORE 模式与宽松模式 (score|rating|quality)\s*[:\s]\s*(\d+(?:\.\d+)?)(?:/\s*10)?，且只接受 0.0-10.0 区间内的数字——超出该范围说明匹配到的是百分比、迭代号等干扰项，返回 None 而非猜测一个分数；
• _parse_verdict() 锚定行首匹配 VERDICT: ACCEPTABLE|NEEDS[_ ]?IMPROVEMENT，防止评审模型"复读指令"导致的误判；
• 关键设计：评审失败绝不虚构分数。ReviewResult 中 score=None 表示"未测量"而非"通过"，未产生可用分数的评审不会伪装成达标（源码第 39-51 行的 docstring 明确说明这一点）。

按文档类型的质量阈值

不同使用场景对应不同阈值（定义于 QUALITY_THRESHOLDS，源码第 356-364 行，与 SKILL.md 表格一致）：

文档类型	阈值	适用场景
marketing	8.0/10	营销材料，必须足够有说服力
report	8.0/10	商务报告，专业质量
presentation	7.5/10	幻灯片、演讲，清晰且有吸引力
social	7.0/10	社交媒体内容
internal	7.0/10	内部使用
draft	6.5/10	工作草稿（最低门槛）
default	7.5/10	通用默认

注意：CLI 脚本 --list-options 输出中 marketing 标注为 8.5/10，而源码 QUALITY_THRESHOLDS 字典与 SKILL.md 表格均为 8.0/10；实际生效阈值以 generate_infographic_ai.py 中的字典为准。

---

三、Review Log：每次生成的审计日志

每一轮完整生成都会在输出目录产生一个 JSON 评审日志文件 {base_name}_review_log.json，其结构与文档给出的示例一致：

{
  "user_prompt": "5 benefits of exercise...",
  "infographic_type": "list",
  "style": "healthcare",
  "doc_type": "marketing",
  "quality_threshold": 8.5,
  "iterations": [
    {
      "iteration": 1,
      "image_path": "figures/exercise_v1.png",
      "score": 8.7,
      "needs_improvement": false,
      "critique": "SCORE: 8.7\nSTRENGTHS:..."
    }
  ],
  "final_score": 8.7,
  "early_stop": true,
  "early_stop_reason": "Quality score 8.7 meets threshold 8.5"
}

对照源码 generate_iterative() 中 results 字典的初始化（第 1146-1165 行），日志字段还包括：

• research_enabled、research_data、context_images：记录是否启用研究阶段、研究数据与参考图上下文；
• final_image、final_reviewed、success：最终产物路径、是否经过有效评审、是否成功；
• 每轮 iteration_result 中还包含 prompt_length、reviewed、review_error 等字段（第 1246-1256 行）。

日志的意义在于：分数、评审意见、提前停止原因全部留痕，用户可据此判断"该信多少"以及是否需要手动复核。此外，启用 --research 时还会额外生成 {name}_research.json，保存原始研究数据与来源（SKILL.md "Research Output" 一节）。

---

四、命令行参考（CLI 全参数）

统一入口是仓库根目录下的 generate_infographic.py：

python skills/infographics/scripts/generate_infographic.py [OPTIONS] PROMPT

Arguments:
  PROMPT                    Description of the infographic content

Options:
  -o, --output PATH         Output file path (required)
  -t, --type TYPE           Infographic type preset
  -s, --style STYLE         Industry style preset
  -p, --palette PALETTE     Colorblind-safe palette
  -b, --background COLOR    Background color (default: white)
  --doc-type TYPE           Document type for quality threshold
  --iterations N            Maximum refinement iterations (default: 3)
  --api-key KEY             OpenRouter API key
  -v, --verbose             Verbose output
  --list-options            List all available options

除文档列出的参数外，源码还支持两个扩展参数（generate_infographic.py）：

• -r, --research：先用 Perplexity Sonar 研究主题、收集准确数据再生成；
• --context-image（仅 generate_infographic_ai.py 直接入口）：可重复指定，把品牌图、图表等参考图作为视觉上下文附带给 Nano Banana Pro。

列出全部可选值

python skills/infographics/scripts/generate_infographic.py --list-options

该命令输出带格式化的完整清单，涵盖：

• 10 种信息图类型（--type）：statistical、timeline、process、comparison、list、geographic、hierarchical、anatomical、resume、social（常量定义于源码第 25-28 行，各类型的生成准则见 generate_infographic_ai.py）；
• 8 种行业风格（--style）：corporate、healthcare、technology、nature、education、marketing、finance、nonprofit，每种风格内置具体十六进制配色（如 healthcare 为 #0077B6 / #00B4D8 / #90E0EF，见源码第 287-328 行）；
• 3 种色盲安全调色板（--palette）：wong（7 色，最广泛推荐）、ibm（8 色）、tol（12 色定性调色板），具体色值与 RGB 见 color_palettes.md；
• **7 种文档类型（--doc-type）**及各自阈值。

参数校验与转发逻辑

从 generate_infographic.py 源码可确认：

• prompt 与 --output 为必填项，缺失时报错退出（第 229-232 行）；
• --type、--style、--palette、--doc-type 均为 choices 约束的枚举参数，非法值会被 argparse 直接拒绝；
• 该脚本本身是薄封装：校验通过后，它把参数转发给同目录下的 generate_infographic_ai.py 子进程（第 255-283 行），并通过 build_subprocess_env() 构造最小化环境变量（FORWARDED_ENV_VARS，第 45-53 行）——只传递 PATH、代理、TLS 证书等必要变量，避免把调用 shell 中无关的敏感环境变量泄露给子进程，API Key 则单独注入。

---

五、配置：API Key 的三种注入方式

模型调用统一走 OpenRouter API，因此需要配置 API Key。文档给出的基础方式是环境变量：

export OPENROUTER_API_KEY='your_api_key_here'

源码中的 resolve_api_key() / _resolve_api_key()（两处实现一致，见 generate_infographic.py）实际支持三级解析优先级：

1. --api-key KEY 命令行显式传入；
2. 环境变量 OPENROUTER_API_KEY；
3. .env 文件：从当前工作目录逐级向上查找，最后回落到脚本自身所在目录；解析时跳过 # 注释行、剥离引号（第 72-88 行）。这意味着在项目根目录放一个 .env 文件即可，无需 python-dotenv 依赖。

若三者都未命中，脚本会输出错误提示并退出（第 236-244 行）。SKILL.md 的元数据也声明了该技能的可选环境变量为 OPENROUTER_API_KEY（primaryEnv），无 Key 时仅影响依赖 LLM 的生成步骤。

文档中的提示 "Get an API key at: https://openrouter.ai/keys" 是获取 Key 的官方渠道；实际请求通过 https://openrouter.ai/api/v1/chat/completions 发出（源码第 429 行）。

---

六、快速上手：从零生成一张达标信息图

将以上机制串起来的典型调用如下（示例均来自 SKILL.md 的 Quick Start）：

# 1. 列表型信息图，使用默认阈值 7.5/10
python skills/infographics/scripts/generate_infographic.py \
  "5 benefits of regular exercise" \
  -o figures/exercise_benefits.png --type list

# 2. 营销场景（最高门槛 8.0/10）
python skills/infographics/scripts/generate_infographic.py \
  "Product features comparison" \
  -o figures/product_comparison.png --type comparison --doc-type marketing

# 3. 企业风格时间线
python skills/infographics/scripts/generate_infographic.py \
  "Company milestones 2010-2025" \
  -o figures/timeline.png --type timeline --style corporate

# 4. 色盲安全配色的统计图
python skills/infographics/scripts/generate_infographic.py \
  "Heart disease statistics worldwide" \
  -o figures/health_stats.png --type statistical --palette wong

# 5. 启用研究阶段，确保数据准确、时效
python skills/infographics/scripts/generate_infographic.py \
  "Global AI market size and growth projections" \
  -o figures/ai_market.png --type statistical --research

运行期间控制台会打印每轮的阈值、得分、是否提前停止及最终评分（源码第 1167-1178、1239-1317 行），结束后输出目录中将出现 exercise_benefits_v1.png 与 exercise_benefits_review_log.json 等文件。

结合提示词技巧提高命中率

• 内容具体化："5 benefits of meditation: reduces stress, improves focus, better sleep, lower blood pressure, emotional balance" 远好于 "meditation infographic"；
• 给出数据点："Market growth from $10B (2020) to $45B (2025), CAGR 35%" 而非 "market is growing"；
• 明确视觉元素："Timeline showing 5 milestones with icons for each event"；
• 完整提示词模板与 10 类信息图的示例 Prompt 可参考 infographic_types.md，设计规范（视觉层级、60-40 图文比、留白、字体、对比度等）见 design_principles.md。

---

七、常见问题排查

问题	解决方案
图中文字不可读	精简文本量，并用 --type 明确布局类型
颜色冲突或无障碍不足	使用 --palette wong 色盲安全配色
质量分始终偏低	增大 --iterations 3；给出更具体、带数据的 Prompt
生成类型不符预期	始终显式指定 --type，保证结果一致
出现 "OPENROUTER_API_KEY not found"	依次尝试 --api-key、环境变量、项目根目录 .env 文件
评审未产生分数（Score unavailable）	该轮图片仍会保留并停止迭代（代码刻意不虚构分数），建议人工查看图片与日志确认质量

---

八、小结

Smart Iterative Refinement 的本质，是把"一次生成碰运气"升级为"生成-评审-精修"的闭环：用 Gemini 3.6 Flash 的五维评分客观度量质量，用文档类型阈值控制标准，用 early stop 控制成本。理解 iterative_refinement.md 中描述的循环、评审标准、Review Log 与 CLI 参数，再对照 generate_infographic.py 与 generate_infographic_ai.py 的源码实现，你就可以精确掌控每一次生成的迭代次数、质量门槛与成本开销，稳定地产出专业级信息图。