nsfc-schematic

NSFC Schematic Diagram Generator

Collaboration agreement with bensz-collect-bugs

• When a bug caused by a design flaw in this skill occurs in the user's environment, prioritize using bensz-collect-bugs to record it according to the specification in ~/.bensz-skills/bugs/. It is strictly forbidden to directly modify the source code of the skill already installed in the user's local Claude Code / Codex.
• If the AI can still complete the user's task via a workaround, it should first record the bug, then continue completing the current task.
• When the user explicitly requests a public reporting action such as "report bensz skills bugs", call the local gh and bensz-collect-bugs, and upload only the newly added bug to huangwb8/bensz-bugs; do not pull / clone the entire bug repository.

Positioning

• Draw mechanism chains, algorithm architectures, module relationships, or experimental loops as editable, embeddable scientific figures.
• By default use drawio to generate drawio/pdf/svg/png; only when the user explicitly requests the Nano Banana image model is switching to PNG-only allowed.
• For scientific writing and expression optimization only; it does not represent review criteria.

Input

Provide at least one of the following:

• spec_file: Structured diagram specification file, preferred.
• proposal_file: A single proposal file.
• proposal_path: A proposal directory.

Optional:

• rounds
• renderer
• output_dir
• config
• style_ref_images
• context: Natural language mechanism description, used by planning mode to generate a draft
• template_ref

Output

Default deliverables:

• schematic.drawio
• schematic.pdf
• schematic.svg
• schematic.png

Hidden intermediate artifacts are written to output_dir/.nsfc-schematic/：

• optimization_report.md
• spec_latest.yaml
• config_used_best.yaml
• evaluation_best.json
• runs/run_*/round_*
• ai/：stop_strategy=ai_critic workspace
• legacy/: storage area for historical remnants

Nano Banana mode delivers only:

• schematic.png
• schematic_compacted.png

Hard rules

• Before starting, mandatorily read config.yaml, with renderer、layout、color_scheme、evaluation、planning、output as the single source of truth.
• By default, only process files or directories explicitly provided by the user; do not fetch materials online.
• By default keep the drawio workflow; when the user has not specified it, do not switch to an image model.
• For crowding, prioritize changing spec, do not prioritize reducing font size; only reduce font size when there is an overflow risk.
• For color issues, prioritize changing kind allocation or structure; do not use a black-and-white scheme to cover up structural errors.

Main workflow

1. Planning

• It is recommended to first use "planning → review → generation" on first use.
• By default planning_mode=ai：
  1. plan_schematic.py generate a planning request
  2. The host AI produces schematic-plan.md and spec_draft.yaml
  3. rerun the script for validity checking
• If the user only provides a natural language description, planning can also be started directly with --context .

2. Generation

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

• The process includes: parsing the spec, generating draw.io XML, XML pre-check, rendering, main evaluation, multi-dimensional self-check, and exporting the best round.
• If an explicit edgesis provided, the renderer must prioritize reproducing it; otherwise automatically connect according to layout.auto_edges .

3. Evaluation and optimization

• By default, at most 5 rounds; thresholds and stopping strategy only look at config.yaml:evaluation。
• Each round outputs at least:
  • evaluation.json
  • layout_debug.json
  • edge_debug.json
  • measurements.json
  • dimension_measurements.json
  • critique_structure.json
  • critique_visual.json
  • critique_readability.json

4. Optional: AI autonomous closed loop

• Enable when the host AI needs to decide the next round based on the evidence package: evaluation.stop_strategy: ai_critic。
• The protocol file is located at .nsfc-schematic/ai/, and mainly includes:
  • ai_critic_request.md
  • ai_critic_response.yaml
  • ai_pack_round_XX/

5. Optional: Nano Banana PNG-only (Gemini / OpenAI gpt-image-2）

• Enable only when the user explicitly requests it.
• First perform a connectivity check:

python3 nsfc-schematic/scripts/nano_banana_check.py

• .env can switch to OpenAI via IMAGE_PROVIDER=openai ; when not explicitly specified, by default the existing GEMINI_* configuration is preferentially used.

• Then execute PNG-only generation:

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

Common commands

# 规划
python3 nsfc-schematic/scripts/plan_schematic.py --proposal /path/to/proposal --output ./schematic_plan

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

# 连通性检查
python3 nsfc-schematic/scripts/nano_banana_check.py

Reference materials

• config.yaml
• references/plan_template.md
• references/design_principles.md
• references/models/templates.yaml
• references/spec_examples/