Back to Details

nsfc-roadmap

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

NSFC 技术路线图生成器

NSFC Technical Roadmap Generator

重要声明（非官方）

Important Disclaimer (Non-Official)

  • 本技能生成的技术路线图仅用于写作与展示优化，不代表任何官方评审口径或资助结论。
  • The technical roadmaps generated by this tool are only used for writing and display optimization, and do not represent any official review standards or funding conclusions.

安全与隐私（硬规则）

Security and Privacy (Hard Rules)

  • 默认将标书内容视为敏感信息：仅处理用户明确提供的文件/目录；不擅自扩展扫描范围。
  • 输出中避免复述不必要的个人信息/单位信息；图中节点仅保留科研相关内容。
  • 默认不联网获取外部数据；若用户明确要求联网补充素材，先提醒风险再执行。
  • Treat grant proposal content as sensitive information by default: Only process files/directories explicitly provided by users; do not expand the scanning scope without permission.
  • Avoid restating unnecessary personal/affiliation information in outputs; only retain research-related content in diagram nodes.
  • Do not access external data via the internet by default; if users explicitly request to supplement materials online, remind them of risks first before execution.

输入

Input

用户至少提供其一：
  • 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 规划”不需要也不建议设置）
Users must provide at least one of the following:
  • proposal_path
    : Grant proposal directory (contains 
    .tex
    /
    .md
    files, etc.; recommended, AI will automatically read project justification and research content)
  • proposal_file
    : Single input file (only use when directory is unavailable; priority is recommended to provide 
    proposal_path
    )
  • spec_file
    : Structured diagram specification file (recommended for controllable iteration)
Optional:
  • rounds
    : Evaluation-optimization rounds (default 5, single source of truth refers to 
    config.yaml:evaluation.max_rounds
    )
  • output_dir
    : Output directory (default creates 
    roadmap_output/
    in the current working directory)
  • layout
    : Layout template name (default 
    auto
    , see 
    config.yaml:layout
    ; supports 
    classic/three-column/layered-pipeline
    )
  • template_ref
    : Specific template ID (e.g., 
    model-02
    ; advanced option; not required or recommended for default "pure AI planning")

输出

Output

在 
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）
Generated under 
output_dir
(intermediate products are hidden by default):
  • Delivery Root Directory (Directly Deliverable): 
    • roadmap.drawio
      : Editable draw.io source file (for manual fine-tuning)
    • roadmap.svg
      : Vector output (preferred for embedding in LaTeX/Word)
    • roadmap.png
      : High-resolution bitmap (for preview and fallback)
    • roadmap.pdf
      : Generated by default (rasterized to PDF from PNG if draw.io CLI is unavailable)
    • roadmap-plan.md
      : Output from planning phase (reviewable/editable)
  • Hidden Intermediate Products: 
    output_dir/.nsfc-roadmap/
    • runs/run_YYYYMMDDHHMMSS/
      : Isolated directory for this run (contains each 
      round_XX/
      ) 
      • round_XX/measurements.json
        : Pure metric collection (density/overflow/phase balance/connections/fonts, etc.; no P0/P1/P2 judgments)
      • round_XX/dimension_measurements.json
        : Three-dimensional metrics for structure/visual/readability (for host AI semantic interpretation)
      • round_XX/critique_structure.json
        : Structural integrity evaluation (terminology consistency/duplicate nodes/phase rationality, etc.)
      • round_XX/critique_visual.json
        : Visual aesthetics evaluation (contrast/color differentiation, etc.)
      • round_XX/critique_readability.json
        : Human readability evaluation (font size threshold/density distribution/edge crowding, etc.)
    • spec_latest.yaml
      : Latest spec snapshot (reproducible)
    • optimization_report.md
      : Iteration records (defects and modifications in each round)
    • config_used_best.yaml
      / 
      evaluation_best.json
      : Reproduction evidence for the best round
    • config_local.yaml
      : Instance-level local configuration override (whitelisted fields; used to "only override current diagram parameters/stop strategy" without modifying the global 
      config.yaml
      ; only 
      {academic-blue, tint-layered}
      are allowed for 
      color_scheme.name
      )
    • ai/
      : AI evidence package and request/response protocol (only used in workflows with 
      stop_strategy=ai_critic
      ) 
      • ai/ACTIVE_RUN.txt
        : Current active ai_critic run (for resume)
      • ai/{run_dir}/ai_pack_round_XX/
        : AI evidence package for this round (for host AI diagram critique)
      • ai/{run_dir}/ai_critic_request.md
        : Host AI request (fixed format)
      • ai/{run_dir}/ai_critic_response.yaml
        : Host AI response (structured: spec/config_local patch + stop/continue)

工作流（执行规范）

Workflow (Execution Specifications)

读取配置（强制）

Read Configuration (Mandatory)

开始前先读取本技能目录下 
config.yaml
，以下字段作为执行时单一真相来源：
  • renderer
    ：输出尺寸与格式、字体与配色
  • evaluation
    ：最大轮次与提前终止规则
  • layout
    ：布局与字号门槛
  • color_scheme
    ：配色方案
Read 
config.yaml
in this tool's directory before starting; the following fields are used as the single source of truth during execution:
  • renderer
    : Output size and format, fonts and color schemes
  • evaluation
    : Maximum rounds and early termination rules
  • layout
    : Layout and font size thresholds
  • color_scheme
    : Color matching scheme

阶段一：规划（推荐）

Phase 1: Planning (Recommended)

若你已准备好 
spec_file
，可跳过规划阶段。
If you have prepared 
spec_file
, you can skip the planning phase.

纯 AI 规划（默认）

Pure AI Planning (Default)

本技能默认启用 
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
。
This tool enables 
config.yaml:planning.planning_mode=ai
by default: No single 
template_ref
is required/recommended in the planning phase.
Workflow:
  1. Run 
    plan_roadmap.py
    to generate planning request protocols (
    plan_request.json/plan_request.md
    + model gallery).
  2. Host AI writes 
    roadmap-plan.md + spec_draft.yaml
    according to 
    plan_request.md
    .
  3. Run 
    plan_roadmap.py
    again; the script will verify whether 
    spec_draft.yaml
    meets the constraints of 
    scripts/spec.py:load_spec()
    .
(Compatible with old workflows) If you want the script to directly generate drafts according to deterministic rules (template planning), use 
--mode template
or set 
planning_mode=template
.

步骤 1：调查标书

Step 1: Investigate the Grant Proposal

读取标书目录下的关键 tex 文件，彻底了解整个标书的情况。至少读取：
  • extraTex/1.立项依据.tex
    （或等效文件）：研究背景、科学问题、研究假说
  • extraTex/2.1.研究内容.tex
    （或等效文件）：具体研究内容、技术路线
仅看研究内容是不够的；立项依据提供了科学逻辑的全貌，有助于更准确地把握路线图的叙事结构与路线叙事设计。
Read key tex files in the grant proposal directory to fully understand the entire proposal. At least read:
  • extraTex/1.立项依据.tex
    (or equivalent): Research background, scientific problems, research hypotheses
  • extraTex/2.1.研究内容.tex
    (or equivalent): Specific research content, technical roadmap
Only reading research content is insufficient; project justification provides the full picture of scientific logic, which helps to accurately grasp the narrative structure and route narrative design of the roadmap.

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

Step 2: Visual References (Learn Excellent Structures), Generate roadmap-plan.md

优先基于“视觉参考”来学习优秀结构（不要求也不建议固定到某个 
template_ref
）：
  • 运行规划脚本后，查看 
    output_dir/.nsfc-roadmap/planning/models_contact_sheet.png
    （模型画廊 contact sheet）
  • 或直接查看 
    references/models/
    下的单张参考图
然后在 
roadmap-plan.md
中明确写出：
  • 视觉/结构学习点（例如：分区方式、主链走向、信息密度控制、配色层级）
  • 路线图整体结构设计（分区/列/主线、节点密度上限、配色层级等）
Prioritize learning excellent structures based on "visual references" (no need to fix to a single 
template_ref
):
  • After running the planning script, view 
    output_dir/.nsfc-roadmap/planning/models_contact_sheet.png
    (model gallery contact sheet)
  • Or directly view single reference images under 
    references/models/
Then clearly write in 
roadmap-plan.md
:
  • Visual/structural learning points (e.g., partitioning method, main chain direction, information density control, color hierarchy)
  • Overall structural design of the roadmap (partitioning/columns/main lines, node density upper limit, color hierarchy, etc.)

步骤 3：生成 spec.yaml

Step 3: Generate spec.yaml

基于 
roadmap-plan.md
生成 
spec.yaml
（结构化图规格），必须满足：
  • 3–5 个阶段（phases），每个阶段 2–6 个节点（boxes）
  • 术语与正文一致（同一概念不出现多种叫法）
  • 输入输出闭合（每个模块/关键节点有明确产出）
  • 风险与备选方案可见（至少 1 个风险/对照节点）
Generate 
spec.yaml
(structured diagram specification) based on 
roadmap-plan.md
, which must meet:
  • 3–5 phases, each with 2–6 nodes (boxes)
  • Consistent terminology with the text (no multiple names for the same concept)
  • Closed input-output loop (clear outputs for each module/key node)
  • Visible risks and alternative solutions (at least 1 risk/control node)

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

Phase 2: Translate roadmap-plan.md to spec (Structured Diagram Specification)

优先路径（按优先级）：
  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
    （可选；默认不建议使用，以避免把复杂场景“框死”在单一模板上）
Priority paths (in order):
  1. User provides 
    spec_file
    : Directly use (controllable, reproducible)
  2. Phase 1 Completed: Use 
    spec.yaml
    generated in Phase 1 (or script-planned 
    spec_draft.yaml
    )
  3. Skip Phase 1: Automatically extract paragraphs related to "research content/technical roadmap" from input files to generate initial spec
Template fields (optional, recommended to record in spec for reproducibility and review):
  • layout_template: auto|classic|three-column|layered-pipeline
    (optional; can be omitted)
  • template_ref: model-01..model-10
    (optional; not recommended by default to avoid "boxing" complex scenarios into a single template)

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

Phase 3: Rendering (Deterministic Script)

目标：以 
spec.yaml
为单一真相来源，确定性生成交付文件（drawio + svg/png/pdf）。
运行（示例）：
bash
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
    （交付结果）
Goal: Use 
spec.yaml
as the single source of truth to deterministically generate deliverable files (drawio + svg/png/pdf).
Run (Example):
bash
python3 nsfc-roadmap/scripts/generate_roadmap.py \
  --spec-file ./roadmap_output/spec.yaml \
  --output-dir ./roadmap_output \
  --rounds 5
Script Responsibilities:
  • Solidify the latest spec to 
    output_dir/.nsfc-roadmap/spec_latest.yaml
  • Output 
    roadmap.drawio
    (editable source file)
  • Output 
    roadmap.svg
    / 
    roadmap.png
    / 
    roadmap.pdf
    (deliverable results)

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

Phase 4: Evaluation-Optimization Cycle (Default 5 Rounds)

目标：围绕阶段一在 
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
  • 评分采用“基础评估分数 - 维度缺陷惩罚”的保守策略，避免遗漏人类感知问题
Goal: Iteratively improve readability and professionalism around the narrative and layout constraints declared in 
roadmap-plan.md
in Phase 1; rewrite spec and re-run if necessary.
Each round must produce a structured defect list (JSON recommended):
  • P0
    : Will directly lead to deduction in review (missing research content, logical breaks, isolated nodes, unreadable)
  • P1
    : Significantly impacts professional impression (disorganized layout, overlapping, harsh color matching, too small font size)
  • P2
    : General optimization (uneven spacing, small margins, unclear arrows, information crowding)
Correction Principles (Avoid "Less Readable After Optimization"):
  • Density (crowding) is usually a content issue: Prioritize modifying 
    spec
    (shorten node text/merge similar nodes/reduce node count); do not reduce font size to "meet thresholds".
  • Overflow is the correct trigger for font size reduction: Consider reducing font size or increasing box height only when text overflow/near overflow occurs.
  • Increase font size if it is too small: When evaluated as "font size too small/very small" and there is no overflow risk, increase font size to ensure readability in A4 printing.
  • Color interference is a problem of kind assignment at the spec level: Prioritize reducing the number of kinds and correcting kind semantics; do not replace structural correction with switching to black-and-white schemes.
Stop strategy follows 
config.yaml:evaluation
:
  • early_stop
    : Legacy early termination rule (optional to enable)
  • stop_strategy: plateau
    : Default "plateau stop" (based on PNG hash and score improvement threshold)
  • stop_strategy: ai_critic
    : AI autonomous closed loop (script does not call external models; generates request and pauses to wait for host AI response in each round)
Evaluation mode follows 
config.yaml:evaluation.evaluation_mode
:
  • heuristic
    (default): Script heuristic evaluation + multi-dimensional self-check (reproducible, offline available)
  • ai
    : Export additional pure metric evidence 
    measurements.json/dimension_measurements.json
    for host AI interpretation (often paired with 
    stop_strategy=ai_critic
    )
Supplement: Multi-dimensional self-check (enabled by default, configuration in 
config.yaml:evaluation.multi_round_self_check
):
  • Run parallel evaluations of three dimensions (structure/visual/readability) after each round of rendering
  • Produce independent 
    critique_*.json
    for each dimension, and summarize into 
    evaluation.json
  • Scoring uses a conservative strategy of "basic evaluation score - dimension defect penalty" to avoid missing human perception issues

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

AI Autonomous Closed Loop (Optional: 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 并进入下一轮。
Enable 
ai_critic
mode when you want to leave "how to draw/whether to continue/what to modify" to the host AI for decision-making:
  • Create/edit in hidden intermediate products of the current output directory: 
    output_dir/.nsfc-roadmap/config_local.yaml
  • Set in it: 
    evaluation.stop_strategy: ai_critic
    (this is an instance-level switch, does not modify global 
    config.yaml
    )
  • After running 
    generate_roadmap.py
    , the script will:
    • Render only 1 round (or continue rendering the next round on an existing run)
    • Generate evidence package: 
      output_dir/.nsfc-roadmap/ai/{run_dir}/ai_pack_round_XX/
      (contains 
      roadmap.png/spec_latest.yaml/config_used.yaml/evaluation.json/measurements.json/dimension_measurements.json/critique_*.json
      )
    • Write fixed request: 
      ai_critic_request.md
    • Pause and wait for you (host AI) to write: 
      ai_critic_response.yaml
  • After you write the structured response of the host AI into 
    ai_critic_response.yaml
    , run the script again to automatically apply the patch and enter the next round.

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

ai_critic_response.yaml Minimum Protocol (version=1)

yaml
version: 1
based_on_round: 1
action: both  # spec_only|config_only|both|stop
reason: "一句话说明本轮行动与停止/继续依据"
yaml
version: 1
based_on_round: 1
action: both  # spec_only|config_only|both|stop
reason: "One-sentence explanation of this round's action and basis for stop/continue"

推荐：直接给完整 spec（避免 patch 合并歧义）

Recommended: Provide complete spec directly (avoid patch merge ambiguity)

spec:

spec:

title: ...

title: ...

phases: ...

phases: ...

可选：给 config_local patch（仅允许 renderer/layout/color_scheme/evaluation.stop_strategy 的安全子集）

Optional: Provide config_local patch (only allows safe subset of renderer/layout/color_scheme/evaluation.stop_strategy)

config_local:

config_local:

color_scheme:

color_scheme:

name: tint-layered

name: tint-layered

undefined
undefined

阶段五：交付与自检

Phase 5: Delivery and Self-Check

交付前自检清单：
  • A4 可读（不依赖放大）
  • 主流向清晰（上→下、左→右）
  • 配色 ≤ 3 种主色调（允许辅助灰）
  • 节点命名与正文一致
  • 输出包含 
    roadmap.drawio
    与至少一种可嵌入格式（
    svg
    或 
    png
    ）
Self-Check List Before Delivery:
  • A4 readable (no need to zoom in)
  • Clear main direction (top→bottom, left→right)
  • ≤3 main color tones (auxiliary gray allowed)
  • Node naming consistent with text
  • Output includes 
    roadmap.drawio
    and at least one embeddable format (
    svg
    or 
    png
    )