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

Users need to provide at least one of the following:

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

Optional:

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

Generated under

output_dir

(each run will create an isolated

run_*/round_*

directory to avoid mixing historical residues):

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

By default, the root directory of

output_dir

only retains delivery files (drawio/svg/png/pdf) and the hidden directory

.nsfc-schematic/

to avoid intermediate files polluting the user's working directory.

Compatibility mode:

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

Each

round_*/

generates the following "traceable evidence" by default (can be turned off via

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

)

When

config.yaml:evaluation.evaluation_mode=ai

(optional enhancement), the script will output offline protocol files (the script does not call external models locally):

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)

Planning mode delivery:

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

yaml

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)

Read

config.yaml

before starting, and use it as the single source of truth for execution:

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

When users generate schematics for the proposal for the first time, it is recommended to "plan → review → regenerate" first:

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

bash

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

(Compatible with old processes) If you want the script to directly generate a draft according to deterministic rules (template planning), use:

bash

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

Or use natural language description:

bash

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

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

(Optional visual learning) The planning script will (try its best) generate a "model gallery" in the

--output

directory (used to learn excellent structures/styles):

./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)

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

bash

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

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
```
Use
```
generate_schematic.py
```
to enter multi-round generation and optimization:

bash

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

Generation Process (Default Entry)

bash

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

Process breakdown:

Parse the spec (
```
spec_parser.py
```
) and automatically complete the layout.
Generate draw.io XML (
```
schematic_writer.py
```
).
Pre-check (P0): Perform XML well-formed verification on
```
.drawio
```
; if it fails, stop immediately and give a readable error.
Render SVG/PNG/PDF (
```
render_schematic.py
```
).
Evaluate diagram quality (
```
evaluate_schematic.py
```
), and enhance the identification and classification of "near-blank rendering/content loss".
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.
Record the results of each round and export the best round.

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

Hard rule: Only when users explicitly propose to use the Nano Banana/Gemini image model (for example, users say "use Nano Banana", "use Gemini to generate images", "do not use draw.io"), this mode is allowed to be enabled; otherwise, the default draw.io process must be maintained.

Prerequisites: Configure and connectable in the project root directory

.env

(or system environment variables):

GEMINI_BASE_URL

(example:

https://generativelanguage.googleapis.com/v1beta

)

```
GEMINI_API
```
(Gemini API Key)

GEMINI_MODEL

(example:

gemini-3.1-flash-image-preview

)

It is recommended to do a connectivity check first (no images will be output):

bash

python3 nsfc-schematic/scripts/nano_banana_check.py

If you are not executing in the project root directory, you can explicitly specify

.env

bash

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

Generate PNG (default

--rounds 5

; only output

schematic.png

bash

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

Description:

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

Applicable: When you need to try different optimization strategies (canvas/font size/spacing/routing/exploration seed, etc.) at the same time, avoid repeatedly modifying

config_local.yaml

in the same

output_dir

leading to run confusion.

Core strategy: Use

parallel-vibe

to create multiple isolated workspaces, each thread maintains a separate

output_dir/.nsfc-schematic/config_local.yaml

(only whitelist fields), and uses

--run-tag

to mark the source of this run.

Default recommended to open 5 threads (aligned with the "default rounds" of

evaluation.max_rounds=5

; it is also more convenient to filter out obviously inferior solutions in 1 round).

Recommended threads (example, split according to common pain points):

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)

It is recommended to run a small number of rounds for quick screening for each thread (such as

--rounds 3

), and then return to the main workspace for fine-tuning with higher rounds after selecting the best (such as

--rounds 7

AI Autonomous Closed Loop (ai_critic, Offline Protocol)

Default mode. Each run only advances 1 round, the host AI evaluates the evidence package and decides the next step. If you need to fall back to unattended automatic convergence, you can override

stop_strategy: plateau

config_local.yaml

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

bash

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

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

)

Host AI writes back the response:

Write according to the protocol of

ai_critic_request.md

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

Additional agreement for Nano Banana (Gemini PNG-only) + ai_critic:

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.

Minimum example (general):

yaml

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

Minimum example (only for Nano Banana, optional fields):

yaml

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 个；风险/对照用点缀色
  - 保证文本对比度（深色字 + 浅色填充）

Resume:

Run

generate_schematic.py

again to automatically consume the response and advance to the next round; after writing

action: stop

, the script will clear

ACTIVE_RUN.txt

and export the final delivery file.

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

Focus on checking 6 dimensions:

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)

Hard threshold (must be met, otherwise regarded as P0):

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

Additional enhanced dimensions (closer to "reduced print readability/reviewer perception"):

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)

AI autonomous evaluation mode (offline protocol)

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)

nsfc-schematic

NPX Install

Tags

SKILL.md Content (Chinese)

NSFC Schematic Generator

Important Disclaimer (Unofficial)

Security and Privacy (Hard Rules)

Input

Output

Spec v2 (backward compatible with old versions)

Correction Principles

Workflow

Read Configuration (Mandatory)

Planning Mode (Recommended for First Use)

Generation Process (Default Entry)

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

Evaluation-Optimization Loop (Default: AI Closed Loop)

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

AI Autonomous Closed Loop (ai_critic, Offline Protocol)

Script Responsibilities

Evaluation Criteria

Failure Handling

Maintainer Self-check

Delivery and Self-check (must pass before delivery)