Visio Mechanism Diagram Zh

Visio Mechanism Diagram ZH

Core Goal

Create Visio mechanism diagrams that look like a finished academic figure, not a stack of text boxes. Prefer visible local Visio COM automation when the user wants to watch the drawing process. Do not install Visio MCP unless the user explicitly wants a long-lived MCP interface; direct COM is shorter and more controllable for visible local editing.

The accepted baseline from prior work is a compact, vertical, three-column, orthogonal Visio mechanism diagram:

• Left column: stage/task labels.
• Middle column: core content/mechanism nodes.
• Right column: methods, outputs, or policy implications.
• Flow: top-to-bottom stages, with horizontal arrows only inside a row and vertical arrows only on the main center axis.

Default Workflow

0. Run environment discovery before assuming paths. Use scripts/discover_visio.py to locate VISIO.EXE, check likely Office install records, and optionally verify COM. Different users may install Office/Visio in different folders; do not hardcode one user's C:\Program Files\Microsoft Office\root\Office16\VISIO.EXE path unless discovery confirms it.

1. Read the source material and compress it into a diagram contract before drawing. Define stages, research questions, core mechanisms, methods, outputs, and arrow semantics. Do not paste long paragraphs into boxes.

2. Choose direct visible Visio COM unless there is a strong reason not to. Start with Visio.Application, set Visible = True, create/open a .vsdx, draw shapes, save, export PNG/PDF if needed, and leave Visio open if the user wants to inspect or copy the figure.

3. Build the diagram with parameterized geometry. Define page size, margins, column widths, stage heights, row centers, node widths/heights, and gaps as constants. All shape coordinates must be derived from those constants.

4. Draw all nodes first, then draw connectors. This avoids anchor drift and accidental diagonal lines.

5. Export and inspect a rendered PNG. A saved .vsdx is not enough. Check the rendered image for overlap, cut text, slanted arrows, uneven fills, excessive whitespace, and page-break guide lines.

6. Update local experience notes when a user rejects a version or accepts a new default. Record root cause, corrected rule, accepted file, and QA evidence.

Environment Discovery Preflight

Before visible drawing on a new computer, locate Visio and verify automation:

python scripts/discover_visio.py --out visio_discovery.json
python scripts/discover_visio.py --check-com --out visio_discovery_com.json

Use the JSON fields as follows:

• preferred_executable: path to use when a script needs to launch Visio explicitly.
• found_executables: fallback candidate paths.
• uninstall_records: version and install-location clues for diagnostics.
• com.available: whether direct COM automation worked when --check-com was used.

If no executable is found but COM works, direct Visio.Application automation may still be enough. If neither executable nor COM is available, stop and tell the user Visio is not discoverable on this machine instead of silently switching to another drawing engine.

Visible editing is mandatory when requested:

• Start with Visio.Application, not Visio.InvisibleApp.
• Set Visible = True.
• Move/size or activate the Visio window when possible so the user can watch drawing progress.
• Only use invisible/background mode for explicit batch export or non-user-facing validation.

Semantic Compression

Convert source text into short labels:

• Stage label: 4-8 Chinese characters, for example 问题识别, 机制解析, 效应测度, 路径优化.
• Stage question: one compact phrase, not a full sentence.
• Middle nodes: 2-4 short nodes per stage.
• Chain/transition node: one concise mechanism chain or method chain.
• Right column: method tag, compact detail, and output/result.

For a four-task research framework, this pattern works well:

Accepted Layout Grammar

Use a three-column orthogonal layout by default.

Suggested parameters in inches:

page_w = 10.6 to 11.2
page_h = 7.4 to 8.2
outer_margin_x = 0.22 to 0.35
outer_margin_y = 0.22 to 0.35
left_w = 1.15 to 1.35
content_w = 5.2 to 5.8
right_w = 2.6 to 3.0
column_gap >= 0.30
stage_gap = 0.14 to 0.22
stage_h = derived from stage content, usually 1.55 to 1.85

Within each stage:

• Use one light background container with a thin border and a small stage color strip or title band.
• Reuse the same row centers in the middle and right columns.
• Keep right-column detail boxes aligned to middle content boxes: same y, same height where possible.
• Align right-column output boxes to the middle chain/output row, not to arbitrary visual centers.
• Keep stage-to-stage arrows on the same vertical center axis.

Do not use huge text-bearing boxes just to force equal heights. Background containers may be tall, but text-bearing child boxes should match their text density.

Orthogonal Arrow Rules

These are hard rules:

• Horizontal arrows must have identical start and end y coordinates.
• Vertical arrows must use one shared center x coordinate.
• Do not use diagonal fan-in arrows from multiple nodes into one box.
• Do not let connectors cross text or pass through boxes.
• Draw connectors after all connected shapes exist.
• Use different styles for main stage arrows and internal mechanism arrows.

If several factors feed a mechanism, express them as a horizontal sequence or grouped row, then connect from the row center downward. Do not draw three diagonal arrows into a center box.

Style Rules

Use restrained academic styling:

• Background: white or very light gray.
• Stage containers: light neutral fill, thin gray-blue border.
• Stage identity: small color strip, title band, or label accent.
• Text: dark blue/charcoal; avoid pure black-heavy blocks.
• Same row/same group: identical fill, border, line width, font size, corner radius, and text alignment.
• Visual emphasis belongs on stage labels, title bands, chain boxes, or output boxes, not random individual peer nodes.
• Avoid gradients, heavy shadows, decorative blobs, and web-hero aesthetics unless the user explicitly asks for a poster-like figure.

Useful semantic colors:

• Blue: problem/identification.
• Teal: mechanism/data.
• Gold: structure/cost/effect.
• Green: policy/path.
• Red: risk/constraint, used sparingly.

Density And Whitespace

When the user says the diagram is ugly or empty, diagnose the whitespace source before changing font size.

Preferred repair order:

1. Tighten outer margins and page width/height.
2. Expand useful column widths, especially the middle content column.
3. Reduce stage gaps and row heights while preserving safe spacing.
4. Split sparse right-column content into method tag, detail box, and output box.
5. Shorten text labels.
6. Only then increase font size slightly.

Box height heuristic:

• 1 line: about 0.28-0.34 in.
• 2-3 lines: about 0.45-0.58 in.
• More than 3 lines: split into multiple boxes.

Do not make a 1-line method label sit alone inside a large high box. If a box looks much larger than its text, either shrink it or turn it into a background container with smaller child boxes.

Visio COM Guardrails

Use visible Visio for user-facing drawing:

$visio = New-Object -ComObject Visio.Application
$visio.Visible = $true

Use Visio.InvisibleApp only for batch export or non-interactive background work.

Avoid these known mistakes:

• Do not set ActiveWindow.Zoom = 88 or 92; Visio COM expects a multiplier such as 0.88 or 0.92.
• Disable visual guide artifacts when possible:
  • ActiveWindow.ShowPageBreaks = False
  • ActiveWindow.ShowGuides = False
  • ActiveWindow.ShowConnectionPoints = False
• Set page size and print page size consistently if page-break guide lines appear.
• If the .vsdx is open in Visio, zip/XML inspection may fail due to a file lock. That is not file corruption.
• On Windows with Chinese paths, prefer resolving paths through PowerShell or Path.cwd() rather than hardcoding possibly mojibaked paths inside here-strings.

QA Gate

Do not call a Visio diagram finished until all checks pass:

• .vsdx saved successfully.
• Visio is visibly open when the user requested visible editing.
• Exported PNG/PDF is non-empty.
• No overlapping boxes.
• No text clipped by borders.
• No connector crosses text.
• No horizontal arrow is slanted.
• No diagonal fan-in arrows.
• Same-row peer boxes share style.
• Right detail boxes align with middle content boxes.
• Output boxes align with chain/output rows.
• No visible page-break dashed line or unwanted guide artifact.
• No excessive unused side whitespace.

If any issue appears, fix the geometry parameters, not ad hoc one-off coordinates.

Common Failure Repairs

• Ugly stack of long rectangles: compress text, use three columns, add chain/output roles.
• Random fill colors: normalize peer node styles; move emphasis to stage strip/output.
• Arrows point oddly: redraw with only horizontal same-y and vertical same-x connectors.
• Boxes overlap: increase stage height, row step, or column gap; do not patch by dragging one shape.
• Right column not aligned: reuse middle row node_y and node_h.
• Too much whitespace: adjust page size, margins, column widths, row height, and text density together.
• Visio appears zoomed too much: set zoom as 0.88, not 88.
• Dotted page line appears: hide page breaks and match page/print dimensions.

Deliverables

For a polished mechanism diagram task, provide:

• .vsdx source file.
• PNG/PDF export when useful for Word/PPT insertion.
• Brief note with output paths, visible Visio state, and QA result.
• Local experience update if a new accepted baseline or failure rule was discovered.

Sharing This Skill

When publishing or sharing, copy the entire visio-mechanism-diagram-zh folder, not only SKILL.md. The folder may contain agents/openai.yaml and scripts/discover_visio.py; both are part of the reusable skill package.