ascii-excalidraw（ascii excalidraw 开发）

<details> <summary>简体中文</summary>

将 ASCII 字符画转换为精美的手绘风格 Excalidraw JSON 文件。该技能专门用于解析 ASCII 图并生成结构化的 .excalidraw 文件，可在 excalidraw.com 打开。核心工作流：先分析结构 → 逐模块生成 JSON → 合并输出。

</details>

Examples / 示例

Example 1: System Architecture / 系统架构

Input:

┌────────────┐      ┌──────────────┐      ┌──────────┐
│   Web App  │─────▶│  API Server  │─────▶│ Database │
└────────────┘      └──────────────┘      ──────────┘
                           │
                     ┌─────▼─────┐
                     │   Cache   │
                     └───────────┘

View in Excalidraw: Open in Excalidraw

Example 2: PPO Training Loop / PPO 训练循环

Input:

────────────┐    ┌────────────┐    ┌────────────┐
│  Collect   │───▶│  Compute   │───▶│   Update   │
│  Traject.  │    │ Advantage  │    │  Policy    │
└────────────┘    ────────────┘    └─────┬──────┘
         ▲                                │
         │         ┌────────────         │
         ─────────│  Evaluate  │◀────────
                   │  & Check   │
                   └────────────┘

View in Excalidraw: Open in Excalidraw

ASCII to Excalidraw Converter

Convert ASCII art diagrams into polished, hand-drawn style Excalidraw JSON files. This skill specializes in parsing ASCII diagrams and producing structured .excalidraw files that can be opened at excalidraw.com.

When to Use

The user provides an ASCII diagram (boxes, arrows, text) and wants a visual Excalidraw file. Typical inputs:

┌────────────┐      ┌──────────────┐
│   Web App  │─────▶│  API Server  │
└────────────┘      └──────────────┘
                           │
                     ┌─────▼─────┐
                     │ Database  │
                     └───────────┘

Conversion Workflow

CRITICAL: Do NOT generate the entire JSON in one shot. Follow this multi-step process to reduce errors.

Step 1: Analyze + Quantitative Layout Planning

Parse the full ASCII diagram and produce a structured analysis plus a quantitative layout plan before generating any JSON.

1a. Qualitative Analysis

1. Detect all boxes: Find +------+, ┌──┐ corner patterns. Record positions, sizes, and text content.
2. Detect all arrows: Find --->, -->, ▼, ▲, ◄, ►, │ patterns. Record source, target, direction, label text.
3. Detect containers: Identify groups of elements enclosed by larger boxes or indentation patterns.
4. Detect text labels: Titles, standalone text, annotations.
5. Infer layers: Determine if the diagram has horizontal layers (top-to-bottom) or vertical columns.
6. Assign colors: Use keyword matching on box labels (see Color Assignment below).

1b. Text Width Estimation (CRITICAL for proportion)

Before computing any coordinates, estimate the rendered width of every text element:

For monospace/code text, add a 10% buffer. For CJK text, use ~12-14px per char.

1c. Compute Layout Dimensions

Using the text widths from 1b, compute:

1. Shape widths: max(text_width + 30px padding, min_width). Min widths: 140x70 (single-line), 180x90 (multi-line).
2. Row height: max(shape_height, line1_text_height, line2_text_height) + 40px buffer.
3. Total canvas width: left_margin + shape_column_width + gap + description_column_width + right_margin.
4. Total canvas height: top_margin + num_rows * row_height + bottom_margin.
5. Background zone: extends 80px beyond the bounding box of all content.

1d. Proportion Check

Before proceeding to Step 2, verify:

• Width/Height ratio: if ratio > 3 or < 0.5, consider reflowing (e.g., swap horizontal layout for vertical, or split wide rows).
• No overflow: ensure description text does not exceed its allocated width — if it does, either increase canvas width or split into multiple lines.
• No overlap: verify that shape_width + gap < column_width for all columns.

If proportion issues are detected, recompute the layout (adjust canvas width, reduce font sizes, or increase spacing) before generating JSON.

1e. Produce Module Plan

Output a structured plan:

Diagram Analysis:
- Title: "compute_advantages_and_returns() dispatch"
- Layout: left-to-right (method column + description column), 7 rows
- Canvas: ~830px wide × ~750px tall (estimated)
- Proportion: width/height = 1.1 ✓

Module 1 (background): Outer zone [gray]
Module 2 (header): Title box [bold]
Module 3 (connector): Vertical dispatch line
Module 4 (branches): 7 horizontal arrows
Module 5 (methods): 7 method boxes [varied colors]
Module 6 (descriptions): 7 description lines + 7 annotation badges

Method list (name → color, estimated shape width):
  GRPO → blue (#1971c2), ~120px
  GSPO → teal (#087f93), ~120px
  PPO → violet (#7048e8), ~110px
  step_wise → green (#2f9e44), ~160px
  reinforce_plus_plus → orange (#f08c00), ~220px
  reinforce_plus_plus_baseline → pink (#e64980), ~260px
  on_policy_distillation → teal (#087f5b), ~220px

Step 2: Generate JSON Module by Module

Generate Excalidraw JSON for each identified module separately. Each module output is a JSON array of element objects.

Module ordering: Follow drawing order — background zones first, then layers top-to-bottom, then connections.

For each module:

1. Emit background zone rectangles (if any) with opacity: 35 and fillStyle: "solid"
2. Emit shapes with their bound text elements
3. Emit arrows and their label text
4. Use semantic colors (see Color Assignment below)
5. Apply sketch style (roughness: 1-2, fillStyle: "hachure", fontFamily: 5)

Between modules, maintain consistent coordinate space. Track cursor positions so subsequent modules align properly.

Write each module to a temporary JSON file:

/tmp/excalidraw_modules/module_1.json
/tmp/excalidraw_modules/module_2.json
...

Step 3: Merge All Modules

Use the helper script to assemble all module arrays into the final .excalidraw envelope:

python ~/.skills/ascii-excalidraw/scripts/merge_modules.py \
  -o diagram.excalidraw \
  /tmp/excalidraw_modules/module_1.json \
  /tmp/excalidraw_modules/module_2.json \
  ...

The script handles ID deduplication, binding reference updates, and produces the standard .excalidraw format.

ASCII Pattern Mapping

Color Assignment

Automatically assign colors based on keyword detection in box label text:

Rules:

• Background zones: same color family with opacity: 35, fillStyle: "solid"
• Arrow strokeColor: match source shape's stroke color, or #1e1e1e for neutral
• Arrow labels: same color as the arrow stroke

Sketch Style Rules

Apply these properties to ALL elements:

• roughness: 1 (default sketch) or 2 (more sketchy)
• fillStyle: "hachure" for filled shapes; "solid" for background zones
• fontFamily: 5 (Excalifont) for all text — this is the key to the sketch look
• strokeWidth: 2 (default), 3 for emphasized elements
• strokeStyle: "solid" (default), "dashed" for optional/async connections

Sizing and Layout

Font Sizes

• Titles: 24-28px
• Shape labels: 16-20px
• Arrow labels: 14-16px
• Annotations: 14px minimum — NEVER below 14px

Text Width Estimation

Estimate rendered widths before computing coordinates (see Step 1b):

Element Sizes

• Shape width: max(text_width + 30px padding, min_width). Min widths: 140x70 (single-line), 180x90 (multi-line).
• Ellipses: minimum 120x120
• Diamonds: minimum 140x100
• Gap between sibling shapes: 50px horizontal, 60px vertical minimum
• Layer gap (top-to-bottom flow): 120px minimum
• Column gap (left-to-right flow): 150px minimum
• Background zones: extend 80px beyond contained elements on all sides

Multi-line Text Handling

When a single text element would be too wide:

• Split into multiple text elements (each on its own line, same y + fontSize * 1.25 offset)
• Or reduce font size (but never below 14px)
• Annotation text: prefer short phrases; split long annotations into separate badges

Proportion Rules

• Target width/height ratio: 0.8 to 1.5 for best display. If outside this range, consider reflowing the layout.
• Column alignment: when layout has distinct columns (e.g., shape column + description column), align all rows to the same baseline.
• No element should extend beyond its column: if description text overflows, either widen canvas or increase row height.

Drawing Order (z-order)

1. Title text (standalone)
2. Background zone rectangles
3. Zone label text
4. Shapes in reading order (top-left → bottom-right)
5. Each shape's bound text immediately after the shape
6. Arrows and their bound labels
7. Decorative/annotation elements last

Container Binding Pattern (CRITICAL)

For labeled shapes, use bidirectional binding:

{
  "type": "rectangle",
  "id": "box_api",
  "x": 200, "y": 150, "width": 180, "height": 80,
  "backgroundColor": "#d0bfff", "fillStyle": "hachure",
  "strokeColor": "#7048e8", "roughness": 1,
  "roundness": { "type": 3 },
  "boundElements": [
    { "id": "t_box_api", "type": "text" },
    { "id": "arrow_1", "type": "arrow" }
  ]
},
{
  "type": "text",
  "id": "t_box_api",
  "x": 210, "y": 170, "width": 160, "height": 30,
  "text": "API Server",
  "fontSize": 18, "fontFamily": 5,
  "strokeColor": "#1e1e1e",
  "textAlign": "center", "verticalAlign": "middle",
  "containerId": "box_api",
  "originalText": "API Server",
  "autoResize": true
}

The shape's boundElements MUST list the text element ID, and the text MUST have containerId pointing back.

Arrow Binding Pattern

{
  "type": "arrow",
  "id": "arrow_1",
  "x": 380, "y": 190, "width": 150, "height": 0,
  "points": [[0, 0], [150, 0]],
  "endArrowhead": "arrow",
  "strokeColor": "#7048e8", "strokeWidth": 2, "roughness": 1,
  "startBinding": { "elementId": "box_api", "fixedPoint": [1, 0.5] },
  "endBinding": { "elementId": "box_db", "fixedPoint": [0, 0.5] }
}

fixedPoint: [horizontal_ratio, vertical_ratio] where 0=top/left, 1=bottom/right, 0.5=center.

Common Pitfalls

1. Never use "label" property on shapes — use container binding (containerId + boundElements)
2. Both sides of binding must exist — shape needs boundElements AND text needs containerId
3. Always include fontFamily: 5 on text for Excalifont sketch style
4. Always include originalText and autoResize: true on text elements
5. Don't generate all at once — break into modules, generate incrementally
6. ID uniqueness — every element needs a globally unique id across all modules
7. Coordinate continuity — track positions between modules
8. No emoji in text — Excalidraw fonts don't render emoji reliably
9. Text contrast — minimum #757575 on white backgrounds; use dark variants on colored fills
10. Drawing order matters — emit shape → its text → its arrows in sequence, NOT all rectangles then all texts then all arrows