NSFC Schematic Generator

Important Disclaimer (Unofficial)

• This skill is only used for scientific research writing and visualization expression optimization, and does not represent any official review standards or funding conclusions.

Security and Privacy (Hard Rules)

• By default, proposal content is treated as sensitive information: only process files or directories explicitly provided by users.
• Only retain necessary scientific research terms in the output diagram, avoid writing irrelevant personal information.
• Do not crawl materials online by default; if users require online supplementation, explain the risks first.

Input

• spec_file

  : Structured diagram specification file (recommended, most controllable)

• proposal_file

  : Single proposal file (such as

  main.tex

  or

  extraTex/*.tex

  )

• proposal_path

  : Proposal directory (automatically search for

  .tex

  files)

• rounds

  : Optimization rounds (default refers to

  config.yaml:evaluation.max_rounds

  )

• renderer

  : Rendering backend (default

  drawio

  ; only allowed to use

  nano_banana

  when users actively mention the Nano Banana/Gemini image model, this mode only outputs PNG)

• output_dir

  : Output directory (optional; default uses

  config.yaml:output.dirname

  , relative to the current working directory)

• config

  : Configuration file path (optional; default uses the built-in

  nsfc-schematic/config.yaml

  of the skill; used to individually override parameters such as

  output.hide_intermediate

  for a specific project)

• context

  : Natural language mechanism description (only used for "planning mode"; planning draft and spec draft are generated by

  plan_schematic.py

  )

• template_ref

  : Diagram type template id/family (advanced option; default "pure AI planning" does not require or recommend setting)

Output

output_dir

run_*/round_*

• schematic.drawio

  : Editable source file

• schematic.pdf

  : Recommended for embedding in LaTeX/Word (vector first; downgraded to PNG→PDF raster when draw.io CLI is unavailable)

• schematic.svg

  : Vector diagram (more suitable for web pages/slides; draw.io SVG may contain foreignObject, and some toolchains will lose text)

• schematic.png

  : Preview image
• Nano Banana / Gemini PNG-only mode: Deliver 4K

  schematic.png

  + significantly smaller

  schematic_compacted.png

  (downsample and compress the 4K image by default, suitable for embedding in proposal PDF; no

  .drawio/.svg/.pdf

  generated)

• .nsfc-schematic/

  : Intermediate product directory (hidden by default; directory name is configurable)

  • optimization_report.md

    : Latest optimization record (overwritten and updated each run)

  • spec_latest.yaml

    : Latest spec used (easy to reproduce/trace)

  • config_used_best.yaml

    /

    evaluation_best.json

    : Latest best round reproduction evidence

  • runs/run_YYYYMMDDHHMMSS(__tag)/

    : Current run directory (contains

    round_*

    , each round of evaluation and rendering products;

    __tag

    will be added when using

    --run-tag

    )

  • ai/

    : Closed-loop workspace for

    stop_strategy=ai_critic

    (

    ACTIVE_RUN.txt

    ,

    {run}/ai_pack_round_XX/

    ,

    ai_critic_request.md

    ,

    ai_critic_response.yaml

    )

  • legacy/

    : Automatically migrated/stored historical residues (such as old version output

    run_*

    ,

    spec*.yaml

    ,

    config_*.yaml

    ,

    evaluation_*.json

    , etc.)

output_dir

.nsfc-schematic/

• If you need to restore the old behavior (intermediate files and

  run_*

  are written directly to the root directory of

  output_dir

  ), set

  config.yaml:output.hide_intermediate=false

  .

round_*/

config.yaml:evaluation.*

• evaluation.json

  : Main evaluator result (includes

  score_base/score_penalty/score_total

  )

• layout_debug.json

  : Layout diagnosis (node/group geometric information)

• edge_debug.json

  : Connection diagnosis (edge id, kind, route, waypoints)

• measurements.json

  : Pure metric evidence for main evaluation

• dimension_measurements.json

  : Structural/visual/readability dimension evidence (summarized by critique)

• critique_structure.json / critique_visual.json / critique_readability.json

  : Multi-dimensional critical self-check evidence (

  evaluation.multi_round_self_check

  ; only generated under heuristic evaluation or AI fallback path to avoid duplicate point deduction with AI standards)

• _candidates/

  : Limited candidate comparison per round (

  evaluation.exploration.candidates_per_round

  )

config.yaml:evaluation.evaluation_mode=ai

• round_*/_candidates/cand_*/ai_eval_request.md

  +

  ai_eval_response.json

  : AI evaluation request/response (main evaluation)

• run_*/ai_tex_request.md

  +

  ai_tex_response.json

  : When the input comes from TEX and no spec_file is provided, it is used for the offline request/response of "AI directly reads TEX → generates spec draft" (automatically downgrades to regular extraction if there is no response)

• output_dir/schematic-plan.md

  : Planning draft (written by the host AI; the script is responsible for generating the request protocol and performing legitimacy verification when re-running)
• (Optional)

  schematic-plan.md

  : If you need to copy an extra copy to the current working directory for easy review, use

  plan_schematic.py --also-write-workspace-plan

Spec v2 (backward compatible with old versions)

• node.id

  is now optional: if missing, the script generates a stable id according to

  group + label + index

  (reproducible).

• schematic.edges

  supports explicit edge protocol:

edges:
  - id: e_input_core
    from: input_layer.data_input   # 支持 group.node 路径引用
    to: process_layer.core_module
    kind: main                     # main|aux|risk|validate
    route: orthogonal              # orthogonal|straight|auto
    label: 输入数据

• Rendering priority:
  • If

    edges

    are provided: output strictly according to explicit edges;
  • If

    edges

    are not provided: fall back to

    layout.auto_edges

    (

    minimal|off

    ).

Correction Principles

• For crowding issues, prioritize modifying the spec (shorten text/merge nodes/reduce nodes), do not force the threshold by reducing the font size.
• Only reduce the font size when there is a risk of overflow; if the font size is small and there is no overflow, increase the font size.
• For color matching interference, prioritize modifying the kind allocation, do not use black and white schemes to cover up structural problems.

Workflow

Read Configuration (Mandatory)

config.yaml

• renderer

  : Canvas size, font, rendering behavior

• renderer.drawio

  : Prompt when draw.io CLI is missing / (optional) automatic installation strategy

• layout

  : Automatic layout parameters

• layout.auto_edges

  : Automatic connection strategy when no explicit edges are provided (

  minimal|off

  )

• layout.template_ref

  : Diagram type template (advanced option; disabled by default; the model gallery is only for learning, see

  references/models/templates.yaml

  )

• layout.title

  : In-diagram title switch and top reservation (in-diagram title is disabled by default, external figure caption is recommended)

• layout.text_fit

  : Node text "automatic expansion" strategy (avoid text overflow/occlusion after export)

• layout.auto_expand_canvas

  : Whether to automatically expand the canvas to avoid out-of-bounds after nodes/groups are automatically expanded

• layout.canvas_fit

  : Canvas fitting strategy (optional shrink according to content boundary; and center the content bbox to reduce unilateral white space)

• layout.routing

  : Routing avoidance parameters (more conservative obstacle padding, avoid group title bar)

• layout.font.edge_label_size

  : Connection label font size (edge label does not automatically follow

  node_label_size

  , need to be configured separately)

• color_scheme

  : Color scheme

• evaluation

  : Scoring threshold, stop strategy (stop_strategy), weight and multi-round exploration parameters

• evaluation.evaluation_mode

  : Evaluation mode (default

  heuristic

  ;

  ai

  is optional enhancement: output offline AI protocol files and consume host AI responses; automatically downgrade if there is no response)

• evaluation.thresholds.min_edge_font_px/warn_edge_font_px

  : Connection label font size access threshold (including reduced print equivalent font size check)

• evaluation.spec_variants

  : Spec security variants (disabled by default; only wrap/truncate/candidates for labels, used to alleviate crowding/overflow caused by long text)

• output.hide_intermediate

  /

  output.intermediate_dir

  : Intermediate file hiding strategy and directory name

• output.max_history_runs

  : Keep up to the latest N

  run_*

  (only effective when hide_intermediate=true)

• output_dir/.nsfc-schematic/config_local.yaml

  : Instance-level override (whitelist:

  renderer.canvas/stroke/drawio.cli_path/internal_routing

  ,

  layout.direction/font/auto_edges/canvas_fit.center_content/auto{margin,gap,max_cols}

  ,

  color_scheme.name

  ,

  evaluation.stop_strategy/max_rounds/spec_variants/exploration{seed,candidates_per_round,enabled}

  )

• planning.models_file

  : Diagram type template library path (default

  references/models/templates.yaml

  )

• planning.planning_mode

  : Planning mode (

  ai|template

  ; default

  ai

  : pure AI planning protocol)

Planning Mode (Recommended for First Use)

1. Investigate the proposal and generate a "planning request protocol" (the script will comprehensively extract "project basis + research content/technical route", and generate a model gallery for learning; no need to select a template):

python3 nsfc-schematic/scripts/plan_schematic.py \
  --proposal /path/to/proposal/ \
  --output ./schematic_plan/

python3 nsfc-schematic/scripts/plan_schematic.py \
  --mode template \
  --proposal /path/to/proposal/ \
  --output ./schematic_plan/

python3 nsfc-schematic/scripts/plan_schematic.py \
  --context "用一句话/一段话描述机制与模块关系..." \
  --output ./schematic_plan/

1. Host AI pure planning: According to the requirements of

   ./schematic_plan/.nsfc-schematic/planning/plan_request.md

   , write:

• ./schematic_plan/schematic-plan.md

• ./schematic_plan/spec_draft.yaml

--output

• ./schematic_plan/.nsfc-schematic/planning/models_simple_contact_sheet.png

  : Skeleton/pattern diagram (recommended to view first)

• ./schematic_plan/.nsfc-schematic/planning/models_contact_sheet.png

  : Complete reference diagram (used for style and detail completion)

1. Run the planning script again for legitimacy verification (the script will verify the spec structure and give P0/WARN prompts):

python3 nsfc-schematic/scripts/plan_schematic.py \
  --proposal /path/to/proposal/ \
  --output ./schematic_plan/

1. Review

   schematic_plan/schematic-plan.md

   and

   schematic_plan/spec_draft.yaml

   : Confirm whether the module division, node list, connection relationship and layout suggestions are reasonable.
   • If you need to manually draft a planning draft, you can refer to:

     nsfc-schematic/references/plan_template.md

2. Use

   generate_schematic.py

   to enter multi-round generation and optimization:

python3 nsfc-schematic/scripts/generate_schematic.py \
  --spec-file ./schematic_plan/spec_draft.yaml \
  --output-dir ./schematic_output/ \
  --rounds 5

Generation Process (Default Entry)

python3 nsfc-schematic/scripts/generate_schematic.py \
  --spec-file nsfc-schematic/references/spec_examples/ccs_framework.yaml \
  --output-dir ./schematic_output \
  --rounds 5

1. Parse the spec (

   spec_parser.py

   ) and automatically complete the layout.
2. Generate draw.io XML (

   schematic_writer.py

   ).
3. Pre-check (P0): Perform XML well-formed verification on

   .drawio

   ; if it fails, stop immediately and give a readable error.
4. Render SVG/PNG/PDF (

   render_schematic.py

   ).
5. Evaluate diagram quality (

   evaluate_schematic.py

   ), and enhance the identification and classification of "near-blank rendering/content loss".
6. Multi-dimensional self-check (

   evaluate_dimension.py

   ): Structural/visual/readability independent evidence is written to disk, and

   score_total

   is obtained by linear deduction of defects.
7. Record the results of each round and export the best round.

Generation Process (Nano Banana / Gemini PNG-only, only when users actively request)

.env

• GEMINI_BASE_URL

  (example:

  https://generativelanguage.googleapis.com/v1beta

  )

• GEMINI_API

  (Gemini API Key)

• GEMINI_MODEL

  (example:

  gemini-3.1-flash-image-preview

  )

python3 nsfc-schematic/scripts/nano_banana_check.py

.env

python3 nsfc-schematic/scripts/nano_banana_check.py --dotenv /path/to/.env

--rounds 5

schematic.png

python3 nsfc-schematic/scripts/generate_schematic.py \
  --renderer nano_banana \
  --dotenv /path/to/.env \
  --spec-file ./schematic_plan/spec_draft.yaml \
  --output-dir ./schematic_output/ \
  --rounds 5

• In Nano Banana mode, the script will automatically disable SVG/PDF export, and only generate 1 candidate per round (to avoid cost multiplication; for multi-scheme comparison, please use

  parallel-vibe

  multi-thread parallelism).
• The prompt of this mode is deterministically constructed from the spec (group/node/edges), and includes hard constraints of "print-level text layout" (prohibiting text distortion/rotation/art fonts, etc.); during optimization, priority is given to modifying the label length, group boundary and edge relationship of the spec to ensure "readable after reduced printing".

Evaluation-Optimization Loop (Default: AI Closed Loop)

• Default configuration:

  evaluation.stop_strategy=ai_critic

• Script behavior:
  • Each run only advances 1 round, pauses after generating the evidence package, waiting for the host AI response
  • Automatically score and write evidence to disk (

    evaluation.json

    +

    *_debug.json

    +

    measurements*.json

    )
  • After the host AI writes back

    ai_critic_response.yaml

    , resume to advance to the next round; write

    action: stop

    to export the final delivery file
• If you need unattended automatic convergence, you can override it to

  stop_strategy: plateau

  in

  config_local.yaml

Multi-scheme Parallel Optimization (parallel-vibe, optional, recommended for "opening many runs and comparing repeatedly")

config_local.yaml

output_dir

parallel-vibe

output_dir/.nsfc-schematic/config_local.yaml

--run-tag

evaluation.max_rounds=5

• thread_1 (structure and white space): Increase

  layout.auto.group_gap_y/node_gap_y

  , increase the canvas if necessary
• thread_2 (readability first): Increase

  layout.font.node_label_size/edge_label_size

  , increase the canvas if necessary
• thread_3 (connection and interpretability): Switch

  renderer.internal_routing=straight

  or disable

  layout.auto_edges

• thread_4 (jump out of local optimum): Keep the structure unchanged, only modify

  evaluation.exploration.seed

  (let the exploration jitter take another trajectory)

--rounds 3

--rounds 7

AI Autonomous Closed Loop (ai_critic, Offline Protocol)

stop_strategy: plateau

config_local.yaml

1. Run the generation script (only advance 1 round each time):

python3 nsfc-schematic/scripts/generate_schematic.py \
  --spec-file ./schematic_plan/spec_draft.yaml \
  --output-dir ./schematic_output/

1. Find the request and evidence package (the script will prompt the path; default in the hidden directory):

• output_dir/.nsfc-schematic/ai/ACTIVE_RUN.txt

  : Current closed-loop run (for resume)

• output_dir/.nsfc-schematic/ai/<run>/ai_critic_request.md

  : Host AI instructions

• output_dir/.nsfc-schematic/ai/<run>/ai_pack_round_XX/

  : Evidence package (includes

  schematic.png

  +

  evaluation.json

  , etc.; if

  renderer=nano_banana

  , it will also include

  nano_banana_prompt.md

  )

1. Host AI writes back the response:

ai_critic_request.md

• output_dir/.nsfc-schematic/ai/<run>/ai_critic_response.yaml

• The host AI should give priority to visual judgment by directly reading the image (

  schematic.png

  );

  evaluation.json/*_debug.json

  are only for reference.
• The host AI needs to judge whether the current "overall style" (composition/line/color matching/texture) is good enough:
  • If good enough: write

    style_continuity: true

    ; the next round will pass the previous round's

    schematic.png

    as a reference image to Gemini to ensure style continuity.
  • If major changes are still needed: write

    style_continuity: false

    ; no reference image is passed in the next round (to avoid solidifying bad styles).
• If you think the color matching still needs optimization, you can write

  nano_banana_color_advice

  ; the script will automatically splice it into the next round's prompt.

version: 1
based_on_round: 1
action: config_only  # spec_only|config_only|both|stop
reason: "一句话说明为什么这样改"
config_local:
  layout:
    font:
      node_label_size: 28

version: 1
based_on_round: 1
action: nano_banana_prompt_only  # spec_only|config_only|both|nano_banana_prompt_only|stop
reason: "风格已满意，锁定风格并微调配色"
style_continuity: true
nano_banana_color_advice: |
  - 主色不超过 2-3 个；风险/对照用点缀色
  - 保证文本对比度（深色字 + 浅色填充）

1. Resume:

generate_schematic.py

action: stop

ACTIVE_RUN.txt

Script Responsibilities

• scripts/spec_parser.py

  : Parse/verify spec, complete automatic layout, verify edges.

• scripts/schematic_writer.py

  : Convert standardized spec to draw.io XML.

• scripts/render_schematic.py

  : Prioritize draw.io CLI rendering; use internal fallback rendering when missing.

• scripts/ai_evaluate.py

  : Generate/consume AI evaluation offline protocols (ai_eval_request.md / ai_eval_response.json), do not call external models in the script.

• scripts/ai_extract_tex.py

  : Generate/consume AI TEX extraction offline protocols (ai_tex_request.md / ai_tex_response.json), do not call external models in the script.

• scripts/measure_schematic.py

  : "Pure metric collection layer" for main evaluation (geometry/routing/pixel proxy), retained for heuristic evaluation and downgrade fallback.

• scripts/measure_dimension.py

  : "Pure metric collection layer" for multi-dimensional self-check (structure/visual/readability), retained for heuristic self-check and downgrade fallback.

• scripts/evaluate_schematic.py

  : Heuristic evaluation (fallback); when

  evaluation_mode=ai

  is enabled, output offline AI protocol and consume the host AI's review response (automatically fall back to heuristic if missing).

• scripts/evaluate_dimension.py

  : Heuristic multi-dimensional self-check (used for penalty deduction; skipped by default when AI main evaluation takes effect to avoid duplicate caliber).

• scripts/routing.py

  : Deterministic orthogonal routing (waypoints), used for rendering fallback, drawio writing and evaluation caliber alignment.

• scripts/extract_from_tex.py

  : Extract terms from TEX for initial spec filling.

• scripts/generate_schematic.py

  : One-click orchestration of multi-round iterations.

• scripts/env_utils.py

  :

  .env

  parsing and upward search (used to read GEMINI_* configuration in Nano Banana/Gemini mode).

• scripts/nano_banana_client.py

  : Gemini REST call encapsulation (connectivity check + PNG generation + current limiting retry).

• scripts/nano_banana_check.py

  : Nano Banana connectivity check CLI (no image generation).

• scripts/nano_banana_generate_png.py

  : Nano Banana PNG generation CLI (convenient for independent prompt debugging).

Evaluation Criteria

• Text readability (font size threshold)
• Node overlap (overlap ratio)
• Arrow integrity (valid endpoints, number of crossings)
• Canvas overflow (out of bounds/close to edge)
• Visual balance (center of gravity offset)
• Overall aesthetics (local proxy evaluation based on rendered products)

• Text must not overflow/be occluded: Node text should not exceed the node boundary, nor should it be covered by connections (reduce risk through draw.io element hierarchy: group bottom layer, connection middle layer, node top layer).

• Long diagonal connection penalty (encourage clearer hierarchy and alignment)
• Connection crossing/close to node penalty (reduce the risk of text crossing/close to text)
• Connection label reduced print readability access control (font size of edge label and equivalent font size after reduced printing)
• Node text crowding proxy (prompt to shorten text or enlarge nodes)

• Trigger: Set

  config.yaml:evaluation.evaluation_mode=ai

• Behavior: The script outputs

  ai_eval_request.md

  +

  ai_eval_response.json

  (and

  ai_tex_request.md

  +

  ai_tex_response.json

  in TEX scenarios) templates; the host AI can make semantic judgments based on spec+config+PNG/TEX and write back the response; if the response is missing or illegal, the script automatically falls back to heuristic evaluation to ensure the process can run.

Failure Handling

• When draw.io CLI is unavailable:
  • You can explicitly specify the draw.io CLI executable file path (or command name that can be parsed by PATH) in

    config.yaml:renderer.drawio.cli_path

    ;
  • Use internal rendering fallback by default and give a strong prompt (internal rendering is available, but the final delivery quality is usually not as good as CLI export);
  • If

    config.yaml:renderer.allow_internal_fallback=false

    , it will fail directly and prompt to install draw.io.
• When spec verification fails: Return an error immediately and indicate the field path.

Maintainer Self-check

• The version number is only recorded in

  config.yaml:skill_info.version

  .
• After modifying the script, run at least 1 set of examples (

  references/spec_examples/*.yaml

  ).
• When adding/adjusting output fields, update the README and CHANGELOG synchronously.

Delivery and Self-check (must pass before delivery)

• A4/screen readable (no zoom required)
• Main flow is clear (top→bottom or left→right)
• Color matching ≤ 3 main tones (auxiliary gray is allowed)
• Node naming is consistent with the main text
• Output includes

  schematic.drawio

  and at least one embeddable format (svg or png)
• Connection labels are readable (equivalent font size after reduced printing ≥ 10px)