# Visio Mechanism Diagram Zh

> Use when Codex needs to create, revise, or QA a polished Chinese academic mechanism diagram, research framework, technical roadmap, or policy path diagram in Microsoft Visio, especially when the user wants Visio opened visibly and the diagram edited on the local desktop. Applies to Visio COM automation, .vsdx output, visible editing, orthogonal flow diagrams, compact three-column mechanism layouts, and avoiding ugly layouts with overlap, slanted arrows, inconsistent fills, excessive whitespace, or page-break guide artifacts.

- Skill: `hoangxuanthu54755-lang/visio-mechanism-diagram-zh` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add hoangxuanthu54755-lang/visio-mechanism-diagram-zh`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hoangxuanthu54755-lang/visio-mechanism-diagram-zh/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: hoangxuanthu54755-lang (https://skillmd.com/u/hoangxuanthu54755-lang)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/hoangxuanthu54755-lang/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:

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

| Stage | Middle content role | Right column role |
|---|---|---|
| Task 1 | factors or constraints | formation mechanism/output |
| Task 2 | mechanism chain | mechanism model/output |
| Task 3 | empirical blocks | methods and heterogeneity map |
| Task 4 | policy paths | scenario tools and policy toolbox |

## Accepted Layout Grammar

Use a three-column orthogonal layout by default.

Suggested parameters in inches:

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

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