NSFC 技术路线图生成器

重要声明（非官方）

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

安全与隐私（硬规则）

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

输入

用户至少提供其一：

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

可选：

• rounds：评估-优化轮次（默认 5，单一真相来源见 config.yaml:evaluation.max_rounds）
• output_dir：输出目录（默认在当前工作目录下创建 roadmap_output/）
• layout：布局模板名（默认 auto，见 config.yaml:layout；支持 classic/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：规划阶段产出（可审阅/修改）
• 隐藏中间产物：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/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}）
  • 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。

工作流：

1. 运行 plan_roadmap.py 生成规划请求协议（plan_request.json/plan_request.md + 模型画廊）。
2. 宿主 AI 按 plan_request.md 写出 roadmap-plan.md + spec_draft.yaml。
3. 再次运行 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（结构化图规格）

优先路径（按优先级）：

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

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

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

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

目标：以 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（交付结果）

阶段四：评估-优化循环（默认 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）
  • 写出固定请求：ai_critic_request.md
  • 暂停等待你（宿主 AI）写入：ai_critic_response.yaml
• 你把宿主 AI 的结构化响应写入 ai_critic_response.yaml 后，再次运行脚本即可自动应用 patch 并进入下一轮。

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

version: 1
based_on_round: 1
action: both  # spec_only|config_only|both|stop
reason: "一句话说明本轮行动与停止/继续依据"

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

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

阶段五：交付与自检

交付前自检清单：

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