excalidraw-local

name	excalidraw-local
description	Create, inspect, update, and export editable Excalidraw diagrams using local scripts and a local browser UI. Use for flowcharts, architecture diagrams, system diagrams, structure diagrams, data-flow diagrams, and editable whiteboard-style diagrams when MCP is unavailable.

1. When to use this Skill (使用场景)

Use this Skill whenever the user asks for an editable whiteboard-style diagram and an MCP-backed solution is not available. Typical triggers:

• "Draw an architecture diagram for ..." / "画一张架构图..."
• "Show me the login flow as a flowchart" / "把登录流程画成流程图"
• "I edited the diagram in the browser; please add a rate limiter" / "我手动改了图，再帮我加一个限流"
• "Clear the canvas and start over with a CI/CD pipeline" / "清空画布，画一张 CI/CD 流水线"

Do NOT use this Skill for: bitmap art, photo manipulation, slide decks, anything that requires uploading data to a remote service.

2. Working directory convention (工作目录约定)

The skill stores everything under the project root in .excalidraw-workbench/:

.excalidraw-workbench/
├── current.excalidraw      # the live scene the UI loads / writes
├── specs/                  # AI-generated DiagramSpec files (source of truth for AI work)
├── exports/                # user-driven exports (UI's built-in export goes here by convention)
├── backups/                # auto-backups taken before every overwrite (D18)
├── server.pid              # bash-managed server PID
└── server.log              # server stdout/stderr

The user is expected to run all commands from the repo root. Do not write outside .excalidraw-workbench/ unless the user explicitly asks.

3. Starting the UI (启动 UI 的命令)

bash scripts/start.sh
# server: http://127.0.0.1:3131  (override with EXCALIDRAW_PORT / EXCALIDRAW_HOST)

The script auto-builds dist/ and workbench/dist/ on first run. It is idempotent: running start.sh while the server is already up is a no-op.

To stop / inspect:

bash scripts/status.sh   # exit 0 + "running pid=..." if up; exit 1 if down
bash scripts/stop.sh

4. DiagramSpec format (生成 spec 的格式要求)

The AI's job is to output a DiagramSpec JSON file under .excalidraw-workbench/specs/. Minimal example:

{
  "title": "Login Flow",
  "direction": "LR",
  "nodes": [
    { "id": "user",     "label": "User",       "type": "rectangle" },
    { "id": "frontend", "label": "Frontend",   "type": "rectangle" },
    { "id": "api",      "label": "API",        "type": "rectangle" }
  ],
  "edges": [
    { "from": "user",     "to": "frontend", "label": "submit credentials" },
    { "from": "frontend", "to": "api",      "label": "POST /login" }
  ]
}

Field rules:

• direction is "LR" (left-to-right) or "TB" (top-to-bottom). Drives dagre auto-layout.
• nodes[].id MUST be unique within the spec and stable across iterations. The same node id will round-trip through the UI.
• nodes[].type: rectangle | ellipse | diamond | text (defaults to rectangle).
• nodes[].x / y (or row / column) are HARD constraints — dagre will only place the unanchored nodes.
• edges[].from / to must reference an existing node id — either in the spec or already on the current scene.
• Optional mode: "replace" to wipe the scene before render. Default is upsert (additive — existing elements not in the spec are preserved). Use "deletions": ["id1", ...] to remove specific elements without --replace.

See examples/architecture.spec.json, examples/flowchart.spec.json, examples/sequence.spec.json for full samples.

5. Rendering a spec (渲染 spec 的命令)

node dist/cli/render-spec.mjs .excalidraw-workbench/specs/my-diagram.spec.json \
  --out .excalidraw-workbench/current.excalidraw

Flags:

• --out <path> (default .excalidraw-workbench/current.excalidraw)
• --replace force-overwrite, ignoring spec mode
• --no-backup skip the auto-backup (intended for tests/CI; users normally should NOT pass this)

Exit codes (PRD §14.2):

• 0 success · 1 generic · 2 bad argument · 3 file not found · 4 invalid JSON · 5 schema validation failed

When the UI server is alive, render-spec writes through the API (PUT /api/scene) so concurrent UI edits arbitrate via ETag (D15). When the server is down, it writes the file directly — both paths run the auto-backup first.

6. Reading the current scene (读取当前 scene 的命令)

node dist/cli/summarize-scene.mjs .excalidraw-workbench/current.excalidraw
# add --json for machine-readable output
# add --max-elements 50 to truncate large scenes

The text summary lists totals, per-type breakdown, every node with id/label/coords/size, every edge as from -[label]-> to, and any text-only elements. Use this BEFORE any incremental edit so the AI knows what already exists.

7. Principles for modifying a scene (修改 scene 的原则)

1. Always summarize first. Run summarize-scene and read the output. Treat the existing scene as ground truth.
2. Reuse existing IDs. Stable IDs are the contract: <node-id> for shapes, text:<node-id> for bound labels, edge:<from>:<to> for connectors. If the user asks to "add a Rate Limiter between Frontend and API", introduce a new node rate-limiter and update the affected edges; do NOT re-render existing nodes with new ids.
3. Default to upsert mode. Never use --replace unless the user explicitly says "clear and redraw" or similar.
4. Honor user positions. If a node already has x/y from the user manually moving it, leave them alone — the spec node should NOT include x/y/row/column for that id, so dagre keeps it pinned.
5. Use deletions[] for surgical removals. Don't reach into the scene file by hand.
6. Re-summarize after rendering to confirm the change is what you intended.

8. Safety boundaries (安全边界)

• Server binds only to 127.0.0.1. Setting EXCALIDRAW_HOST to anything else is rejected unless EXCALIDRAW_ALLOW_REMOTE=1 is set explicitly.
• All scene data lives under the project's .excalidraw-workbench/ directory — never ~, never /tmp, never the network.
• No PNG/SVG export script. The Excalidraw UI itself has built-in Menu → Export image (D13).
• No MCP server. No Puppeteer. No telemetry.
• clear.sh requires --force (or interactive y) to skip the confirmation prompt.
• Auto-backup runs on every overwrite; recovery is manual (copy the desired file from .excalidraw-workbench/backups/ back to current.excalidraw).

9. Error handling guidance (错误处理建议)

Symptom	Cause	What to suggest
error: file not found (exit 3)	spec path wrong	Check the path. Default search dir is .excalidraw-workbench/specs/.
error: invalid JSON (exit 4)	malformed spec	Re-emit the spec; the file path is included in the error.
error: Duplicate node id (exit 5)	spec has two nodes with the same id	Rename one of them.
error: edges[i] references unknown ... node (exit 5)	edge endpoint missing	Either add the missing node to nodes[] or use an id already present in the current scene (upsert mode looks across both).
409 Conflict from render-spec	UI saved between read and write	The CLI auto-retries once; if it fails again, refresh the UI then re-run.
error: port 3131 already in use	another instance already running	bash scripts/status.sh then bash scripts/stop.sh, or set EXCALIDRAW_PORT.
Bad UI-side save (Save conflict — please reload toast)	concurrent disk write	Click Reload from disk in the header; the merge already preserved your work.

10. Example prompts (示例 prompt)

10.1 Create an architecture diagram

Use /excalidraw-local to create an editable architecture diagram for:
- React frontend
- API Gateway
- Auth Service
- User Service
- PostgreSQL
- Redis
- Async Worker

Use left-to-right layout and save it to the local Excalidraw workbench.

10.2 Draw a login flow

Use /excalidraw-local to draw a login flow:
User submits credentials, frontend validates form, API checks password,
Auth Service issues token, frontend redirects to dashboard.

10.3 Incremental edit on top of user changes

Use /excalidraw-local. I manually edited the current diagram. Inspect the
current scene, then add a Rate Limiter between Frontend and API Gateway
without redrawing the whole diagram.

10.4 Clear and start fresh

Use /excalidraw-local. Clear the current scene and create a new top-to-bottom
CI/CD pipeline diagram.