visiomaster

# Visiomaster ## Overview `visiomaster` is a standalone skill for rebuilding diagram images into editable Visio deliverables. It is optimized for: - flowcharts - product or system architecture diagrams - paper-style module/framework figures - box-arrow process diagrams that should remain editable It is not the right tool for: - posters - UI screenshots - decorative layouts - image-heavy slides where the main value is visual styling rather than structured diagram semantics ## Core Positioning Use `ppt-master` ideas on the front half: - source collection - style extraction - layout discipline - image understanding - visual polishing standards Do **not** reuse `ppt-master`'s raw `SVG -> PPTX` output path for Visio. For Visio, the stable path is: `image -> scene.json -> validate -> Visio COM render -> .vsdx/.svg/.png` The key rule is simple: - main structure should be redrawn as editable nodes, labels, and connectors - small thumbnails or texture snippets may remain raster only when redrawing them is not worth the loss in speed - never solve a reconstruction request by pasting the whole original image unless the user explicitly asks for贴图 ## Environment This skill is Windows-first and expects: - local Microsoft Visio desktop installed - Python with `pywin32` Use the active thread default Python interpreter. If the user or project provides a specific Python path, use that; otherwise use: ```powershell python ``` ## Workflow ### 1. Confirm scope First classify the source request: - editable flowchart recreation - architecture/module diagram recreation - paper figure cleanup/redraw - image-assisted redraw with a few raster sub-assets allowed If the diagram is mostly boxes, arrows, labels, and containers, stay in `visiomaster`. For image-based exact replicas, always secure a local source image file before claiming strict review readiness: - If the user provides a filesystem path, use that path as `metadata.source_image` and all review `--original` inputs. - If the user uploads or attaches an image without a local path, save/stage that image into the reconstruction workspace as `source/original.<ext>` before rendering the final deliverable. Do not treat a chat attachment alone as an acceptable strict-review source. - If the current client does not expose an attached image as readable bytes and the image cannot be staged locally, clearly mark the work as a draft/manual preview and ask for a source file path before strict review or final exact delivery. - Every exact replica must keep the staged/local source path stable across review rounds. Do not use screenshots of the replica, pair images, OCR output, or memory of the attachment as a substitute for the original source image. When you have a source file path, stage it with the helper script so review manifests can use one stable canonical image: ```powershell python ${SKILL_DIR}\scripts\stage_source_image.py ` --input <source.png> ` --workspace <reconstruction_workspace> ` --id <figure_id> ``` This writes `source/original.<ext>` and `source/source_manifest.json` with SHA-256 hashes. Use the staged image path as `metadata.source_image` and as `make_review_assets.py --original`. For wide or dense figures, do not start by authoring the whole page in one pass. If the source has many modules, many arrows, tiny labels, or a very wide canvas, first create a region plan: - visible regions become `group_container` - invisible logical work areas become `audit_region` - every meaningful node gets `container_id` - each region should usually stay under 12-18 visible nodes before whole-page assembly - shared typography and arrow styles must be fixed before region scenes are merged For exact replicas, do not write `scene.json` until you have a source-faithful visual inventory for that specific image. This inventory is produced by visual LLM inspection of the source image, not by OCR, filename clues, warning logs, prior scenes, or a batch scene generator. It must preserve visible source language and notation exactly; do not translate Chinese labels to English, normalize formulas, invent unreadable text, or replace source modules with generic neural-network blocks unless the source visibly shows them. Record the inventory in `metadata.source_visual_inventory` before the first render. At minimum it should include: - `analysis_basis`: a short note such as `visual_llm_source_image`. - `language_profile` and `do_not_translate`. - `unknown_text_policy`: use `mark_unreadable_do_not_invent` for unclear tiny text. - per-region `source_bbox_px`, required visible labels/formulas, component motifs, edge motifs, port/boundary/dashed-frame notes, uncertainty notes, and text layout facts. Before authoring the first `edges` array for an exact replica, run a separate arrow-inventory pass from the source image. The goal is to lock topology before any Visio PNG exists. For arrow-dense local structures, this pass is not optional bookkeeping; it is the scene driver: - record every source-visible arrow in `metadata.arrow_plan` - each visible arrow or visible line segment gets its own independent `arrow_plan_id`; do not describe a whole local subgraph or multi-hop chain with one plan entry - each entry needs `id`, `from_visual_object`, `from_anchor_description`, `to_visual_object`, `to_anchor_description`, `route_shape`, `line_style`, `arrowhead`, `semantic_intent`, `source_bbox_px`, `must_not_cross`, `relative_position_facts`, direction, endpoint/boundary facts, and certainty - use `semantic_intent: "data_flow"` for normal flow, `"feedback"`/`"loss_backprop"` for dashed return paths, `"boundary_handoff"`/`"frame_output"` for frame-edge arrows, `"merge"`/`"fan_in"` for many-to-one joins, `"fork"`/`"fan_out"` for one-to-many branches, and `"loop_update"` for outer cycles - use route shapes such as `straight_horizontal`, `straight_vertical`, `orthogonal`, `rounded_orthogonal`, `smooth_curve`, or `loop`; do not leave major arrows as vague `auto` - after authoring edges, bind every source-visible edge with `arrow_plan_id` - one `arrow_plan_id` may bind to only one scene edge by default. If one source arrow truly needs multiple scene segments, every segment edge must declare `same_source_arrow: true`, `segment_index`, and `segment_count` - when a source arrow is unreadable, mark `certainty: "uncertain"` and do not invent its destination Treat `metadata.arrow_plan` as the source-truth checklist for later visual review: the reviewer should be able to say whether `A001`, `A002`, etc. match the original, rather than writing broad comments like "arrows are wrong". For attention-like motifs, decompose the visual grammar before drawing scene edges. A source crop that looks like `K/Q -> multiply -> score matrix -> value multiply -> value matrix -> Concat` is not one edge. Record the local motif, then inventory each visible connector separately, for example: - `A101`: `K_w` right edge -> `qk_mul` left edge, horizontal, no arrowhead - `A102`: `Q_a` right/top edge -> `qk_mul` lower-left edge, short diagonal/curved, no arrowhead - `A103`: `qk_mul` right edge -> score matrix left edge, horizontal, arrowhead end - `A104`: `V_w` right edge -> value multiply left edge, horizontal, no arrowhead - `A105`: score matrix upper-right corner -> value multiply lower-left edge, diagonal, no arrowhead - `A106`: value multiply right edge -> value matrix left edge, horizontal, arrowhead end - `A107`: value matrix top edge -> Concat bottom edge, vertical, arrowhead end When a local diagram matches a known motif such as `attention_score_motif`, `value_weighting_motif`, `residual_add_norm_motif`, or `concat_merge_motif`, generate the local scene from that motif grammar first. For `attention_score_motif`, Q/K feed the left-side multiply, Softmax is a floating label rather than an edge endpoint, the multiply output enters the score matrix, the score matrix connects diagonally to value multiplication, value multiplication enters the value matrix, and the value matrix outputs vertically to Concat. For paper-style exact replicas, `source_visual_inventory` should record precise layout facts, not only module names: - text alignment: left / center / right and baseline relation - intended line breaks and no-wrap expectations - whether a label is plain text, math-like, caption, annotation, or mixed CJK+math - whether subscripts/superscripts are visible and must be preserved - serif / sans / CJK / math font intent and visible source font if known - whether visible shadow / glow / emphasis exists on the source text or bars - caption prefix/body split such as bold `Fig. 6.` plus regular body - crop obligations for that region, such as `caption`, `small_text`, or `arrow_dense` - box/line/shadow/density facts for that region: padding, corner radius, dash rhythm, line weight, soft-shadow character, and whether the crop is visually tight or loose For strict replica work, also mark: - `metadata.replica_review_mode: "strict_replica"` - `metadata.replica_stage: "layout_topology"` before the first render - `metadata.replica_stage: "detail_polish"` only after layout/topology is already visually correct Fresh capability evaluation means a fresh scene from the source inventory. Do not validate a skill change by patching an old scene and checking whether that old scene looks better. Old scenes and old reviews may explain failure modes, but after changing skill workflow, schema, renderer, or components, rebuild each test scene from the source image inventory. Batch exporting finished scenes is fine; batch-generating several scenes from one Python script is not valid proof that the skill works for normal users. ### 2. Build or refine `scene.json` `scene.json` is the contract between the visual analysis step and Visio rendering. When authoring or editing it: - read `references/scene-schema.md` - use `templates/visio_components.json` as the supported component vocabulary - use `templates/style_profiles.json` to select `paper_white` or `clean_white` - read `references/visio-component-map.md` if you need mapping guidance - for exact replicas, author coordinates in source pixels when possible and let the renderer scale them to inches Starter generation: ```powershell python ${SKILL_DIR}\scripts\image_to_scene.py --image <source.png> --output <scene.json> ``` This script does not infer the real diagram structure from pixels. It only writes a blank or template starter scene. The actual first-pass `scene.json` for exact work must still be authored by the LLM from the source image. For exact large-figure reconstruction, start in source pixels and record the region strategy: ```powershell python ${SKILL_DIR}\scripts\image_to_scene.py --image <source.png> --pixel-page --region-strategy region_first --output <scene.json> ``` If the layout is close to a standard process flow, you can seed from the built-in example: ```powershell python ${SKILL_DIR}\scripts\image_to_scene.py --image <source.png> --template basic-flow --output <scene.json> ``` Treat this as draft/bootstrap authoring only. It is not valid strict-replica proof. For GAN/TFR training-cycle figures, AI-generated paper diagrams, or images with Real/Generated TFR panels, you may seed a draft/bootstrap pass from the canonical module template: ```powershell python ${SKILL_DIR}\scripts\image_to_scene.py --image <source.png> --template gan-tfr --output <scene.json> ``` Do not use template-seeded scenes as final evidence for strict capability evaluation. For strict replica work, rebuild the scene from a blank source-driven authoring pass before judging the skill. Before the first Visio render of a draft/bootstrap or legacy GAN/TFR scene, you may run the deterministic recipe pass explicitly: ```powershell python ${SKILL_DIR}\scripts\scene_autofix.py <scene.json> --recipe gan-tfr --output <fixed.scene.json> ``` This recipe upgrades fragile local grammar before visual tuning: split Real/Generated boxes become `tfr_panel`, empty dashed loss frames become `loss_region`, raw `L_adv`/`L_rec` text becomes `math_text`, detached/broken outer loops become smooth `loop_arrow`, reversed GAN arrows are corrected, and crowded backprop arrows are bundled. `scene_to_visio.py` no longer runs this autofix implicitly for strict/exact scenes. Use `--autofix-gan-tfr` only when you intentionally want an explicit bootstrap/render helper path, and treat the written `<basename>.autofixed.scene.json` as a non-final rewritten scene until you re-author a fresh strict-replica scene from source inventory. ### 3. Validate scene data Before touching Visio, validate structure and references: ```powershell python ${SKILL_DIR}\scripts\scene_validate.py <scene.json> ``` If validation fails, fix the scene first. Do not guess around broken ids or unsupported types inside the renderer. For large or complex figures, run a complexity preflight before full rendering: ```powershell python ${SKILL_DIR}\scripts\scene_complexity.py <scene.json> ``` Use the complexity report to catch the large-image failure modes before Visio render: too few regions, uncovered nodes, over-dense modules, inconsistent font scale, text-fit risks, and likely overlaps. For exact replicas, run a typography preflight when the source uses more than one visible font style: ```powershell python ${SKILL_DIR}\scripts\font_inventory.py --check "Times New Roman" --check "Cambria Math" --check "Calibri" --check "Microsoft YaHei UI" ``` Do not treat all labels as one font. Classify visible text by role before rendering: - paper serif labels: `font_role: "paper_serif"` with Times/Cambria-like candidates - UI/product labels: `font_role: "ui_sans"` with Calibri/Arial/Segoe-like candidates - formulas/operators: `font_role: "math"` or `symbol_font_role: "math"` - Chinese labels: `font_role: "cjk_sans"` or `cjk_serif` When the source font is known or strongly inferred, store `source_font_family` in the node style. If that font is installed but the effective render font differs, `scene_audit.py` reports it as a rebuild issue. For complex paper figures with many modules, also generate a module-level audit report: ```powershell python ${SKILL_DIR}\scripts\scene_audit.py <scene.json> ``` Use the audit report to review every `group_container` as a separate region: child count, labels, colors, internal arrows, incoming arrows, outgoing arrows, and whether cross-module arrows start from a boundary or from an internal component. Treat unchecked audit items as real defects before final export. For exact replicas, run the rebuild gate after each rendered iteration: ```powershell python ${SKILL_DIR}\scripts\scene_validate.py <scene.json> --strict python ${SKILL_DIR}\scripts\scene_audit.py <scene.json> --fail-on-rebuild ``` In strict mode, missing `source_visual_inventory`, missing `region_plan`, template-seeded starts, and recipe-rewritten exact scenes are treated as gate failures, not informal warnings. If validate/audit prints a blocking contract failure or `[REBUILD]` item, stop coordinate nudging. Rebuild that local subsystem with the correct semantic component (`loop_arrow`, `dashed_region`, `dashed_feedback_path`, `boundary_port`, etc.) before doing any more visual polishing. In strict mode, missing `metadata.arrow_plan`, missing `arrow_plan_id` bindings, or route-shape violations are also gate failures. Do not render a strict replica whose long arrows still rely on center-to-center `auto` routing when the source shows fixed horizontal, vertical, boundary, merge, fork, feedback, or loop grammar. For exact replica work, validation passing is necessary but not sufficient. Render a PNG and compare it with the source for: - page aspect ratio - container bounds - local topology - distinctive shapes - connector grammar - feature-map coloring - source-language preservation, formulas, tiny labels, ports, and arrow endpoints Exact mode should run as a two-stage production loop, not one rushed render: 1. first render/review stage: lock layout, region bboxes, container bounds, and topology grammar 2. second render/review stage: fix text layout, caption behavior, shadows, local spacing, and visual polish If a higher-level component stays visually wrong after two strict reviews, rebuild that local subsystem with smaller components or primitives. Do not keep nudging the whole page around one stubborn panel or text cluster. For arrow-dense local structures, review the local crop before merging it into the full scene: 1. author a local scene such as `attention_core.scene.json` from the local source crop and motif/arrow plan 2. validate it with strict arrow-plan checks 3. render only that local scene 4. compare the local source crop and local replica crop as a pair 5. merge into the full scene only after every arrow-plan checklist item passes Do not ship after a first-pass exact render unless the second review round is already represented and visually clean. ### 4. Render into Visio Render the scene into a Visio drawing and export deliverables: ```powershell python ${SKILL_DIR}\scripts\scene_to_visio.py <scene.json> --output-dir <exports> ``` Default outputs: - `.vsdx` - `.svg` - `.png` Use `--style-profile clean_white` when the user wants a polished white product/process style. Use the default `paper_white` for paper figures and academic module diagrams. Read `references/visio-export-flow.md` when debugging Visio automation or export behavior. After rendering complex replicas, compare the exported PNG module-by-module against the source. Do not rely on whole-image visual similarity; small topology errors often hide inside large figures. For exact replicas, the first render is allowed to be a fast editable reconstruction pass, but the first render must be followed by at least one local-source review round before final delivery: - Use the local/staged original image file and the exported replica PNG with `make_review_assets.py --write-review-bundle`. - The reviewer input is the original source image plus the current replica image. Do not send a generated global pair when those two full images are already available; a global pair is only a human navigation/audit artifact and usually shrinks fine details. - Generate local crop assets only for the regions under active doubt, such as `attention_core`, `arrow_dense`, `right_output`, `small_text`, or `caption`. Do not generate or review every crop by habit. If you generate a crop but neither a human nor the reviewer inspects it, it is only a stored debug artifact, not review evidence. - Overlay assets are off by default. Generate overlays only when checking global alignment drift, frame offsets, or region bbox registration. Do not use overlays for arrow topology, text wrapping, operator endpoints, or formula fidelity; they tend to obscure those defects. - During review, convert source-vs-replica visual comparison into two explicit checklists inside or alongside `review_findings.json`: a topology checklist and a visual-layout checklist. - The topology checklist records source facts such as branches, merges, boundary crossings, operator order, arrow endpoints, and required routes. Examples: `S3 -> vertical trunk -> S1/common path`, `S2/S3 -> hollow circle -> minus`, `Linear -> f̂ -> [] -> fused feature`. - The visual-layout checklist records overlap, label wrapping, bracket/tensor spacing, line-through-text defects, feature-stack thickness, font-role drift, and color/rounding/shadow mismatches. - A finding should reference the failed checklist item when possible. Do not write only broad notes such as "right output is wrong" when a specific missing branch, wrong landing point, or bracket overlap is visible. - Repair rounds must re-check the same crop and checklist items, not only rerun validation or no-op gates. For high-fidelity work, the reviewer should compare only two images: - the original source image - the current replica PNG Do not give the reviewer pair/overlay images as the prompt when the original and replica are already available. A pair image is redundant with the two full images and often hides small connector or text defects through downscaling. Targeted crops are allowed as secondary reviewer inputs only when the current task is explicitly local and the full images are too small to judge the detail. In that case, send the original full image, the replica full image, and the smallest useful number of local source-vs-replica crop pairs. Record which crop(s) were actually inspected. The review contract is still anchored by the two full images. For exact/strict review packaging, call `make_review_assets.py --write-review-bundle` to write the manifest/templates. By default it does not generate global pairs, local crops, or overlays. Use: - `--include-global-pair` only for human navigation/audit records. - `--crops core arrow_dense caption` for hand-picked named crops. - `--region-crops all` only when you intentionally want every `metadata.region_plan` crop pair. - `--include-overlays` only for alignment-drift debugging. The reviewer should receive the two images and a concrete issue format. It should report specific visual differences, source appearance, replica appearance, impact on fidelity, focus regions, and the expected visible change after regeneration. Use script output only to package round evidence and to validate/export; the quality decision remains visual. If using a separate reviewer agent, give it only the source image, the replica image, and the issue format. Do not give it intended fixes, prior conclusions, pair/crop packs, script warnings, similarity scores, or old scene JSON. The reviewer validates visual fidelity; the main agent turns that into a fresh scene rebuild. Use the fixed reviewer prompt in `references/reviewer-two-image-prompt.md`. Do not stop at natural-language review notes. In strict work, the review loop must produce: