NSFC 技术路线图生成器

重要声明（非官方）

本技能生成的技术路线图仅用于写作与展示优化，不代表任何官方评审口径或资助结论。

安全与隐私（硬规则）

默认将标书内容视为敏感信息：仅处理用户明确提供的文件/目录；不擅自扩展扫描范围。
输出中避免复述不必要的个人信息/单位信息；图中节点仅保留科研相关内容。
默认不联网获取外部数据；若用户明确要求联网补充素材，先提醒风险再执行。

输入

用户至少提供其一：

proposal_path：标书目录（包含 .tex / .md 等；推荐，AI 将自动读取立项依据与研究内容）
proposal_file：单个输入文件（仅在无法提供目录时使用；推荐优先提供 proposal_path）
spec_file：结构化图规格文件（推荐，便于可控迭代）

可选：

rounds：评估-优化轮次（默认 5，单一真相来源见 config.yaml:evaluation.max_rounds）
output_dir：输出目录（默认在当前工作目录下创建 roadmap_output/）
renderer：渲染后端（默认 drawio；仅当用户主动提及 Nano Banana/Gemini 图片模型时才允许使用 nano_banana，该模式仅输出 PNG）
dotenv：可选：显式指定 .env 路径（仅 renderer=nano_banana 使用；默认从当前工作目录向上搜索）
style_ref_images：可选：风格参考图片（可多张；仅 renderer=nano_banana 生效；脚本参数为 --style-ref 可多次提供；支持 png/jpg/jpeg/webp；最多使用前 4 张；用于让生成图的配色/线条/质感尽量贴近参考图，但不照抄其内容结构）
layout：布局模板名（默认 auto，见 config.yaml:layout；支持 classic/three-column/packed-three-column/layered-pipeline）
template_ref：具体模板 id（如 model-02；高级选项；默认“纯 AI 规划”不需要也不建议设置）

输出

在 output_dir 下生成（默认启用隐藏中间产物）：

交付根目录（可直接交付）：
- roadmap.drawio：draw.io 可编辑源文件（用于人工微调）
- roadmap.svg：矢量输出（优先用于 LaTeX/Word 嵌入）
- roadmap.png：高分辨率位图（用于预览与兜底）
- roadmap.pdf：默认生成（无 draw.io CLI 时为 PNG→PDF 栅格降级）
- roadmap-plan.md：规划阶段产出（可审阅/修改）
Nano Banana / Gemini PNG-only 模式：交付 4K roadmap.png + 体积显著更小的 roadmap_compacted.png（默认将 4K 图下采样并压缩，适合嵌入标书 PDF；不生成 .drawio/.svg/.pdf）
隐藏中间产物：output_dir/.nsfc-roadmap/
- runs/run_YYYYMMDDHHMMSS/：本次运行隔离目录（包含各轮 round_XX/）
  - round_XX/measurements.json：纯度量采集（密度/溢出/阶段平衡/连线/字体等；不含 P0/P1/P2 判定）
  - round_XX/dimension_measurements.json：structure/visual/readability 三维度度量（供宿主 AI 语义解读）
  - round_XX/layout_debug.json：布局诊断（节点尺寸/压缩等）
  - round_XX/edge_debug.json：连线诊断（显式/自动 edges 的解析结果）
  - round_XX/critique_structure.json：结构完整性评估（术语一致性/重复节点/阶段合理性等）
  - round_XX/critique_visual.json：视觉美学评估（对比度/配色区分度等）
  - round_XX/critique_readability.json：人类可读性评估（字号门槛/密度分布/边缘拥挤等）
- spec_latest.yaml：最新 spec 快照（可复现）
- optimization_report.md：迭代记录（每轮缺陷与修改点）
- config_used_best.yaml / evaluation_best.json：best round 复现证据
- config_local.yaml：实例级局部配置覆盖（白名单字段；用于“只覆盖本次图参数/停止策略”，不改全局 config.yaml；其中 color_scheme.name 仅允许 {academic-blue, tint-layered}；当设置 renderer.canvas.width_px/height_px 时，该宽高比会被锁定并在多轮优化中持续保持）
- ai/：AI 证据包与 request/response 协议（仅在 stop_strategy=ai_critic 工作流中使用）
  - ai/ACTIVE_RUN.txt：当前 ai_critic 活跃 run（用于 resume）
  - ai/{run_dir}/ai_pack_round_XX/：本轮 AI 证据包（供宿主 AI 读图批判）
  - ai/{run_dir}/ai_critic_request.md：宿主 AI 请求（固定格式）
  - ai/{run_dir}/ai_critic_response.yaml：宿主 AI 响应（结构化：spec/config_local patch + stop/continue）

工作流（执行规范）

读取配置（强制）

开始前先读取本技能目录下 config.yaml，以下字段作为执行时单一真相来源：

renderer：输出尺寸与格式、字体与配色
evaluation：最大轮次与提前终止规则
layout：布局与字号门槛
color_scheme：配色方案

阶段一：规划（推荐）

若你已准备好 spec_file，可跳过规划阶段。

纯 AI 规划（默认）

本技能默认启用 config.yaml:planning.planning_mode=ai：规划阶段不要求/不建议选择单一 template_ref。

工作流：

运行 plan_roadmap.py 生成规划请求协议（plan_request.json/plan_request.md + 模型画廊）。
宿主 AI 按 plan_request.md 写出 roadmap-plan.md + spec_draft.yaml。
再次运行 plan_roadmap.py，脚本将校验 spec_draft.yaml 是否满足 scripts/spec.py:load_spec() 约束。

（兼容旧流程）如需让脚本按确定性规则直接生成草案（模板规划），使用 --mode template 或设置 planning_mode=template。

步骤 1：调查标书

读取标书目录下的关键 tex 文件，彻底了解整个标书的情况。至少读取：

extraTex/1.立项依据.tex（或等效文件）：研究背景、科学问题、研究假说
extraTex/2.1.研究内容.tex（或等效文件）：具体研究内容、技术路线

仅看研究内容是不够的；立项依据提供了科学逻辑的全貌，有助于更准确地把握路线图的叙事结构与路线叙事设计。

步骤 2：视觉参考（学习优秀结构），生成 roadmap-plan.md

优先基于“视觉参考”来学习优秀结构（不要求也不建议固定到某个 template_ref）：

运行规划脚本后，查看 output_dir/.nsfc-roadmap/planning/models_contact_sheet.png（模型画廊 contact sheet）
或直接查看 references/models/ 下的单张参考图

然后在 roadmap-plan.md 中明确写出：

视觉/结构学习点（例如：分区方式、主链走向、信息密度控制、配色层级）
路线图整体结构设计（分区/列/主线、节点密度上限、配色层级等）

步骤 3：生成 spec.yaml

基于 roadmap-plan.md 生成 spec.yaml（结构化图规格），必须满足：

3–5 个阶段（phases），每个阶段 2–6 个节点（boxes）
术语与正文一致（同一概念不出现多种叫法）
输入输出闭合（每个模块/关键节点有明确产出）
风险与备选方案可见（至少 1 个风险/对照节点）

阶段二：从 roadmap-plan.md 落到 spec（结构化图规格）

优先路径（按优先级）：

用户提供 spec_file：直接使用（可控、可复现）
阶段一已完成：使用阶段一生成的 spec.yaml（或脚本规划产物 spec_draft.yaml）
跳过阶段一：从输入文件中自动抽取"研究内容/技术路线"相关段落生成初版 spec

模板字段（可选，推荐在 spec 中记录以便可复现与复盘）：

layout_template: auto|classic|three-column|packed-three-column|layered-pipeline（可选；不写也可以）
template_ref: model-01..model-10（可选；默认不建议使用，以避免把复杂场景“框死”在单一模板上）

spec v2（可选；用于逼近 draw.io 手工连线上限）：

box.id：为关键节点显式指定稳定 id（用于可复现连线与手工微调不丢失）
edges：显式关键连线（当提供 spec.edges 时，渲染器必须优先复现；未提供时才按 config.yaml:layout.auto_edges 自动连线）

阶段三：渲染（确定性脚本）

目标：以 spec.yaml 为单一真相来源，确定性生成交付文件（drawio + svg/png/pdf）。

运行（示例）：

python3 nsfc-roadmap/scripts/generate_roadmap.py \
  --spec-file ./roadmap_output/spec.yaml \
  --output-dir ./roadmap_output \
  --rounds 5

脚本职责：

将最新 spec 固化到 output_dir/.nsfc-roadmap/spec_latest.yaml
输出 roadmap.drawio（可编辑源文件）
输出 roadmap.svg / roadmap.png / roadmap.pdf（交付结果）

生成流程（Nano Banana / Gemini PNG-only，仅当用户主动要求）

硬规则：只有当用户明确提出要用 Nano Banana/Gemini 图片模型（例如用户说“用 Nano Banana”“用 Gemini 出图”“不用 draw.io”）时，才允许启用该模式；否则必须保持默认 draw.io 流程。

提示：图片模型生成图内中文文字可能出现扭曲/乱码/模糊。本 skill 的确定性 Nano Banana prompt 已加入“印刷体字体 + 水平排版 + 禁变形”的强约束来降低该风险；但仍建议控制节点文案长度（1-2 行为宜）。如需 100% 可控字体与排版，优先使用默认 draw.io 流程。

环境变量（写入项目根目录 .env 或系统环境变量）：

GEMINI_BASE_URL（例如 https://generativelanguage.googleapis.com/v1beta）
GEMINI_API（Gemini API Key；也兼容 GEMINI_API_KEY/GOOGLE_API_KEY）
GEMINI_MODEL（例如 gemini-3.1-flash-image-preview）

连通性检查：

python3 nsfc-roadmap/scripts/nano_banana_check.py

生成（PNG-only）：

python3 nsfc-roadmap/scripts/generate_roadmap.py \
  --spec-file ./roadmap_output/spec.yaml \
  --output-dir ./roadmap_output \
  --rounds 1 \
  --renderer nano_banana \
  --style-ref ./path/to/style_ref_1.png \
  --style-ref ./path/to/style_ref_2.jpg

阶段四：评估-优化循环（默认 5 轮）

目标：围绕阶段一在 roadmap-plan.md 中声明的叙事与版式约束，迭代改进可读性与专业感；必要时回写 spec 并复跑。

每轮必须产出结构化缺陷清单（建议 JSON）：

P0：会被评审直接扣分（缺研究内容、逻辑断裂、孤立节点、不可读）
P1：显著影响专业印象（布局混乱、重叠、刺眼配色、字号过小）
P2：一般优化（间距不均、边距偏小、箭头不清晰、信息拥挤）

纠偏原则（避免“越优化越不可读”）：

density（拥挤）通常是内容问题：优先改 spec（缩短节点文案/合并相近节点/减少节点数）；不要用缩字号来“通过阈值”。
overflow 才是缩字号的正确触发条件：出现文字溢出/接近溢出时，才考虑减字号或增大 box 高度。
字号偏小应增大字体：当评估为“字号偏小/过小”且没有 overflow 风险时，应增大字号，优先保证 A4 打印可读。
配色干扰是 spec 层面的 kind 分配问题：优先减少 kind 种类、修正 kind 语义；不要用切换到黑白方案替代结构修正。

停止策略以 config.yaml:evaluation 为准：

early_stop：legacy 提前终止规则（可选开启）
stop_strategy: plateau：默认启用的“平台期停止”（基于 PNG 哈希与分数提升阈值）
stop_strategy: ai_critic：AI 自主闭环（脚本不调用外部模型；每轮生成 request 并暂停等待宿主 AI 的 response）

评估模式以 config.yaml:evaluation.evaluation_mode 为准：

heuristic（默认）：脚本启发式评估 + 多维度自检（可复现、可离线）
ai：额外导出纯度量证据 measurements.json/dimension_measurements.json 供宿主 AI 解读（常与 stop_strategy=ai_critic 搭配）

补充：多维度自检（默认启用，配置见 config.yaml:evaluation.multi_round_self_check）：

在每轮渲染后并行运行 structure/visual/readability 三个维度评估
每个维度产出独立的 critique_*.json，并汇总进 evaluation.json
评分采用“基础评估分数 - 维度缺陷惩罚”的保守策略，避免遗漏人类感知问题

AI 自主闭环（可选：stop_strategy=ai_critic）

当你希望把“怎么画图/是否继续/改哪儿”交给宿主 AI 决策时，启用 ai_critic 模式：

在本次输出目录的隐藏中间产物里创建/编辑：output_dir/.nsfc-roadmap/config_local.yaml
在其中设置：evaluation.stop_strategy: ai_critic（这是实例级开关，不改全局 config.yaml）
运行 generate_roadmap.py 后脚本会：
- 只渲染 1 轮（或在已有 run 上继续渲染下一轮）
- 生成证据包：output_dir/.nsfc-roadmap/ai/{run_dir}/ai_pack_round_XX/（含 roadmap.png/spec_latest.yaml/config_used.yaml/evaluation.json/measurements.json/dimension_measurements.json/critique_*.json；若 renderer=nano_banana 还会包含 nano_banana_prompt.md）
- 写出固定请求：ai_critic_request.md
- 暂停等待你（宿主 AI）写入：ai_critic_response.yaml
你把宿主 AI 的结构化响应写入 ai_critic_response.yaml 后，再次运行脚本即可自动应用 patch 并进入下一轮。

Nano Banana + ai_critic（可选组合）

当你使用 --renderer nano_banana（Gemini 图片模型）并同时启用 evaluation.stop_strategy: ai_critic 时：

宿主 AI 应以 直接读图（roadmap.png）的视觉判断 为主；evaluation.json/critique_*.json 仅作参考。
证据包会携带 nano_banana_prompt.md（本轮传给 Gemini 的完整 prompt），便于你对照当前绘图指令。
你可以在响应中提供 nano_banana_prompt 字段，用于控制下一轮传给 Gemini 的 prompt（见下方协议）。
无论 nano_banana_prompt.mode 使用 full 还是 patch，脚本都会在真正发给 Gemini 的 prompt 中自动补齐“字体与文字排版”硬约束，避免多轮优化时把防扭曲规则丢掉。
Nano Banana 模式严禁在图内生成总标题/图题；若标书需要图题，应由正文图注承担，而不是画进 PNG。
宿主 AI 需要判断当前“整体风格”（构图/线条/配色/质感）是否已经足够好：
- 若足够好：在响应里写 style_continuity: true；下一轮会把上一轮 roadmap.png 作为参考图一并传给 Gemini，以保证风格延续，避免“开盲盒式换风格”。
- 若仍需大改：写 style_continuity: false；下一轮不传参考图（让模型有空间重做风格）。
若认为配色仍需优化，可在响应中提供 nano_banana_color_advice，脚本会自动拼到下一轮 prompt 里（建议写成可执行规则）。

ai_critic_response.yaml 最小协议（version=1）

version: 1
based_on_round: 1
action: both  # spec_only|config_only|both|nano_banana_prompt_only|stop
reason: "一句话说明本轮行动与停止/继续依据"
# 说明：nano_banana_prompt_only = 只更新 prompt，不修改 spec/config_local

# 仅 nano_banana：是否从本轮开始锁定风格（下一轮会把上一轮图片作为参考图传入）
style_continuity: false

# 推荐：直接给完整 spec（避免 patch 合并歧义）
# spec:
#   title: ...
#   phases: ...

# 可选：给 config_local patch（仅允许 renderer/layout/color_scheme/evaluation.stop_strategy 的安全子集）
# config_local:
#   color_scheme:
#     name: tint-layered

# 可选（仅 nano_banana）：配色建议（会自动拼到下一轮 prompt）
# nano_banana_color_advice: |
#   - 主色不超过 2-3 个；风险/对照用点缀色
#   - 保证文本对比度（深色字 + 浅色填充）

# 可选（仅 nano_banana 模式）：提供下一轮传给 Gemini 的 prompt
# nano_banana_prompt:
#   mode: full    # patch=更稳（推荐）| full=全量替换（脚本仍会自动补齐字体硬约束）
#   content: |
#     你是一名科研申请书插图设计师...

阶段五：交付与自检

交付前自检清单：

A4 可读（不依赖放大）
主流向清晰（上→下、左→右）
配色 ≤ 3 种主色调（允许辅助灰）
节点命名与正文一致
输出包含 roadmap.drawio 与至少一种可嵌入格式（svg 或 png）