jpmanson/pele-skill

Pele

Rendere Mermaid-Quellcode mit Pele in SVG. Pele ist eine synchrone Bibliothek: kein Puppeteer, kein mermaid-cli, kein MCP-Server. Das Interface dieser Fähigkeit ist scripts/render.mjs.

Das Wurzelverzeichnis der Fähigkeit ist das Verzeichnis, das diese Datei enthält. Alle nachfolgenden Pfade sind relativ zu diesem Verzeichnis angegeben. Das gilt auch, nachdem die Fähigkeit in Claude Code, Hermes oder OpenCode installiert wurde.

Wann verwenden

• Der Benutzer wünscht ein Mermaid-Diagramm als SVG-, HTML- oder Bilddatei.
• Eine .mmd-Datei oder ein Mermaid-Fenced-Code-Block (````mermaid`) soll gerendert und überprüft werden.
• Der Benutzer fragt nach einem Diagramm, das einer der 32 unterstützten Typen zeichnen kann, und möchte eine Datei, keinen Chat-Fence. Dazu gehören auch weniger geläufige: Wardley-Karte, Fischgräte, Venn, Swimlane, Radar, Treemap, Sankey, Eisenbahngrammatik, Dateibaum, Cynefin, Ereignismodell. Siehe Diagrammtypen unten.

Nicht verwenden, wenn:

• Der Mermaid-Fence soll im Markdown bleiben, das GitHub, Obsidian oder ein anderer Viewer bereits rendert.
• Das gewünschte Artefakt ist kein Mermaid (handgezeichnetes Excalidraw-JSON, eine maßgeschneiderte Architekturseite, eine Screenshot-Annotation).
• Der Benutzer pixelidentische mermaid.js-Ausgabe benötigt. Pele hat sein eigenes Layout.

Diese Fähigkeit nicht in einen MCP-Server einwickeln. Ein einziger Skriptaufruf ist die gesamte Funktionalität.

Voraussetzungen

• Node.js 20 oder neuer und npm im PATH.
• Die Abhängigkeitsinstallation erfolgt im Wurzelverzeichnis der Fähigkeit (package.json neben dieser Datei), niemals im Projekt des Benutzers.

Fehlt node_modules/pele, führt das Skript dort npm install aus. Sie können es auch selbst erledigen:

npm install --no-fund --no-audit

Abschluss: node scripts/render.mjs --check beendet sich mit Exit-Code 0 und stderr-JSON enthält "ok": true und eine pele-Version.

Diagrammtypen

Kennen Sie die vollständige Liste, bevor Sie sich entscheiden. Pele rendert 32 Typen, und ein Drittel von ihnen benötigt einen -beta-Header, der sich vom Namen unterscheidet, den ein Benutzer nennen würde.

node scripts/render.mjs --types

Das gibt JSON aus: type, exakter erster header, wofür er steht, und ein funktionierendes example-Pfad. references/diagram-types.md enthält dieselbe Tabelle, die Header, die fehlschlagen, und wie man einen Typ auswählt.

• Wählen Sie den Typ, der zeigt, was der Leser braucht, nicht den ersten, der einem einfällt. Besitzer pro Schritt → swimlane. Ursachen eines Problems → ishikawa. Terminierte Aufgaben → gantt. Ordnerlayout → treeView. Proportionale Flüsse → sankey.
• Passt die Anforderung zu keinem Typ (freiform Layout, ein Bild, ein nicht aufgeführter Diagrammtyp), sagen Sie das und zwingen Sie es nicht in ein Flussdiagramm.
• Wenn der Benutzer einen bestimmten Diagrammtyp nennt, der nicht in der Liste ist, sagen Sie das, bevor Sie den nächstgelegenen unterstützten Typ anbieten. Nähern Sie es nicht stillschweigend an.

Vorgehen

1. Wählen Sie den Typ und seinen genauen Header aus --types. Bei -beta-Typen oder Typen, deren Syntax Sie nicht sicher sind, lesen Sie zuerst deren example-Datei und kopieren Sie die Struktur.
2. Schreiben Sie die Mermaid-Quelle in eine .mmd-Datei. Übergeben Sie kein mehrzeiliges Diagramm als Shell-Argument.
3. Rendern Sie es:

node scripts/render.mjs EINGABE.mmd AUSGABE.svg

4. Lesen Sie die JSON-Quittung auf stderr. Abschluss ist alles: Exit-Code 0, "ok": true, der Quittungs-type ist der von Ihnen gewählte Typ, und die Ausgabedatei beginnt mit <svg.
5. Wenn "ok": false:
   • unsupported-diagram: Die erste Zeile ist kein bekannter Header. Verwenden Sie suggest[0].header, falls vorhanden, sonst wählen Sie einen aus --types.
   • syntax oder semantic: Korrigieren Sie die Quelle bei line/column mit snippet, vergleichen Sie sie mit dem Beispiel des Typs und rendern Sie erneut.
   • Wechseln Sie nicht zu mermaid-cli, einem Headless-Browser oder einem handgeschriebenen SVG.
6. Geben Sie den absoluten Ausgabepfad an. Fügen Sie das SVG nicht in den Chat ein, es sei denn, der Benutzer hat nach dem Markup gefragt. Beanspruchen Sie keinen Erfolg bei einem Exit ungleich Null.

Verwenden Sie --html oder einen Ausgabepfad, der auf .html endet, wenn der Benutzer eine Datei benötigt, die er im Browser öffnen kann. Das HTML bettet das SVG ein und setzt Peles CSS-Farbvariablen.

node scripts/render.mjs --html EINGABE.mmd AUSGABE.html

Quittung

Erfolg auf stderr:

{"ok":true,"type":"flowchart","width":180,"height":80,"bytes":1200,"output":"/abs/AUSGABE.svg","html":false,"pele":"1.6.0"}

Fehler auf stderr, Exit 1 (Exit 2, wenn Pele nicht installiert werden konnte):

{"ok":false,"code":"syntax","message":"...","type":"flowchart","line":2,"column":5,"snippet":"..."}

code ist syntax, semantic, unsupported-diagram, limit, usage, install-failed oder render-failed. Zeigen Sie message als Text an. Es kann die Diagrammquelle enthalten.

Eine unsupported-diagram-Quittung hat auch hint und suggest:

{"ok":false,"code":"unsupported-diagram","hint":"Ersetzen Sie die erste Zeile durch den untenstehenden Header. Viele Typen benötigen das -beta-Suffix.","suggest":[{"type":"radar","header":"radar-beta","example":"/abs/examples/types/radar.mmd"}]}

Flags

Flag	Verwendung
--check	Pele laden, Version ausgeben, nicht rendern
--types	Unterstützte Typen, Header und Beispielpfade als JSON auf stdout ausgeben
--html	Eigenständiges HTML statt rohes SVG
--fixed	Feste Pixelgröße. Standard für eine .svg-Datei
--responsive	SVG kann an seinen Container schrumpfen. Standard für stdout und HTML
--max-width <px>	Pele bitten, das Layout anzupassen. Kann ein breites LR-Flussdiagramm unter 640px vertikal umschalten
--font-size <px>	Basis-Schriftgröße
--font <Schriftfamilie>	Beschriftungsschrift
--id-prefix <str>	Eindeutiges Präfix, wenn mehr als ein SVG eine Seite teilt

Stdout bleibt das SVG (oder HTML). Die Quittung ist immer die letzte JSON-Zeile auf stderr.

Ein umgebender Mermaid-Fence (````mermaid`) wird entfernt. Mermaids eigenes Frontmatter wird nicht entfernt.

Fallstricke

• Datei-SVG standardisiert auf responsive: false. Übergeben Sie --responsive nur, wenn das SVG eingebettet wird und schrumpfen soll.
• Node hat keine Canvas-Messung. Beschriftungsbreiten können von einer Browserdarstellung abweichen. Das ist zu erwarten.
• Übergeben Sie --max-width nur, wenn der Benutzer nach einem schmalen Layout gefragt hat. Es kann die Richtung ändern.
• Header sind exakt. radar, venn, wardley, swimlane, treeView, usecase, cynefin, railroad, agentflow benötigen alle -beta; architecture benötigt ebenfalls -beta. Es gibt keinen fishbone-Header; verwenden Sie ishikawa-beta.
• Symbolnamen (fa:fa-user, Architektursymbole außer cloud, database, disk, internet, server) werden als leerer Slot ohne Fehler gerendert. Dieses Skript stellt keinen Symbol-Callback bereit. Entfernen Sie das Symbol oder ersetzen Sie es durch Text.
• Quell-Limit ist 50.000 Zeichen. Ausgabe-Limit ist 4.000.000. Flussdiagramm-Kanten-Limit ist 5.000.
• npm install im Repository des Benutzers wird dieses Skript nicht zufriedenstellen. Das Paket befindet sich im Wurzelverzeichnis der Fähigkeit.
• Wenn node_modules existiert, Pele aber nicht geladen werden kann, löschen Sie dieses node_modules und führen Sie npm install im Wurzelverzeichnis der Fähigkeit aus.
• Eine bereits geöffnete Agent-Sitzung sieht eine während der Sitzung installierte Fähigkeit nicht. Das ist ein Loader-Cache, keine fehlerhafte Installation.

Verifikation

Vom Wurzelverzeichnis der Fähigkeit:

npm run smoke

Abschluss: Exit-Code 0, und stdout-JSON hat "ok": true, eine pele-Version, "types": 32, eine rendered-Liste mit jedem Katalogtyp und einen syntaxError mit "code": "syntax" und einem line ungleich Null. Der Smoke schlägt auch fehl, wenn scripts/catalog.mjs von Peles eigener Typliste abweicht oder wenn ein Header nicht mehr als sein Typ erkannt wird. examples/broken.mmd muss weiterhin fehlschlagen. Ein bestandener Smoke bedeutet nicht, dass ein neues Diagramm korrekt ist; jedes neue Diagramm benötigt weiterhin seine eigene Quittung.