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

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

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)

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)

If you have prepared

spec_file

, you can skip the planning phase.

Pure AI Planning (Default)

This tool enables

config.yaml:planning.planning_mode=ai

by default: No single

template_ref

is required/recommended in the planning phase.

Workflow:

Run
```
plan_roadmap.py
```
to generate planning request protocols (
```
plan_request.json/plan_request.md
```
+ model gallery).

Host AI writes

roadmap-plan.md + spec_draft.yaml

according to

plan_request.md

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

Step 1: Investigate the Grant Proposal

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.

Step 2: Visual References (Learn Excellent Structures), Generate 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.)

Step 3: Generate spec.yaml

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)

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

Priority paths (in order):

User provides
spec_file
: Directly use (controllable, reproducible)
Phase 1 Completed: Use
```
spec.yaml
```
generated in Phase 1 (or script-planned
```
spec_draft.yaml
```
)
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)

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)

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

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 Autonomous Closed Loop (Optional: stop_strategy=ai_critic)

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 Minimum Protocol (version=1)

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"

# Recommended: Provide complete spec directly (avoid patch merge ambiguity)
# spec:
#   title: ...
#   phases: ...

# Optional: Provide config_local patch (only allows safe subset of renderer/layout/color_scheme/evaluation.stop_strategy)
# config_local:
#   color_scheme:
#     name: tint-layered

Phase 5: Delivery and Self-Check

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
```
)

nsfc-roadmap

NPX Install

Tags

SKILL.md Content (Chinese)