diagram-skills (DiagramSkills)

DiagramSkills

Wandle eine Diagrammanfrage in ein fertiges visuelles Ergebnis um – mit dem gebündelten DiagramSpec-Renderer. Das primäre Produkt ist Agent-generierte Diagrammqualität: Verfasse wartbares JSON, rendere SVG/HTML und optional PNG, inspiziere das Visuelle, korrigiere die Quelle und gib das Ergebnis zurück. Zwinge den Benutzer nicht, einen Editor zu öffnen, um normale Arbeit zu beenden. Die öffentliche Skill-ID lautet $diagram-skills; die benutzerseitige Marke ist DiagramSkills.

Standard-Lieferworkflow

1. Für Prosa-zu-Diagramm-Arbeiten oder eine wesentliche Überarbeitung erstelle ein prägnantes .brief.json aus templates/briefs/diagram-brief.json. Es hält Ziel, Erzählung, Umfang, Priorisierung, Unsicherheit, Inhaltsrisiken und Überprüfungsfragen fest – nicht die private Gedankenkette.
2. Lies das ausgewählte Profil in references/diagram-thinking-profiles.json, passe mindestens drei Qualitätsfragen an und führe diagram_brief.py ... --strict aus, bevor du zeichnest.
3. Für eine geschichtete Übersicht mit mehr als 14 sichtbaren Konzepten lies references/enterprise-board.md und verwende layout: board. Für kleinere Beziehungsgraphen verwende Knoten/Kanten.
4. Beginne mit der passenden Vorlage, ersetze deren Beispielinhalte und halte das Brief sowie das Quell-JSON neben den Ausgaben.
5. Führe png-backend aus, bevor du PNG anforderst, dann führe render ... --strict mit --png nur aus, wenn ein unterstützter lokaler Rasterizer verfügbar ist. Eine Quelldatei allein ist keine abgeschlossene visuelle Anfrage.
6. Inspiziere das generierte SVG oder 1920-Pixel-PNG in voller Größe. Überprüfe Hierarchie, chinesischen Text, Konsistenz der Symbole, Beschneidungen, überfüllte Karten, Linienkreuzungen und ob die Erzählung des Briefs visuell dominant ist.
7. Beantworte jede Qualitätsfrage des Briefs mit konkreten, eindeutigen Belegen und führe diagram_brief.py ... --spec ... --strict --reviewed aus. Binde dann das überprüfte Brief, die Quelle und das untersuchte SVG oder PNG mit diagram_skills.py review ... in die Qualitätsquittung ein. Wenn eine Prüfung fehlschlägt, korrigiere Brief, Quelle oder Renderer und rendere erneut. Brich nach drei evidenzbasierten Korrekturrunden ab; vereinfache oder teile dann auf.
8. Liefere zuerst das Bild aus, verlinke dann das Brief, SVG/HTML/Quelle/Qualitätsnachweise. Erwähne den Browser-Editor nur, wenn der Benutzer nach manueller Bearbeitung, Importen oder Drill-Down fragt.

Anfrage leiten

1. Lies references/diagram-thinking.md für Prosa-zu-Diagramm-Aufgaben und wesentliche Überarbeitungen. Erfinde keine Tatsachen, um ein Layout symmetrisch zu machen.
2. Lies references/prompt-system.md, wenn die Eingabe Prosa ist, unvollständig ist oder zu einem wiederverwendbaren Prompt werden soll.
3. Wähle genau einen primären Typ aus und lies dessen Anleitung:
   • Systemarchitektur
   • Agent-Workflow
   • Datenfluss
   • Capability Map
   • Benutzerfluss
   • Systemtopologie
   • Entscheidungsbaum
   • Fahrplan
   • Strategiekarte
   • Prozessablauf
4. Lies nur das Profil des ausgewählten Typs in references/diagram-thinking-profiles.json.
5. Lies references/spec.md während der Erstellung eines einzelnen Diagramms. Verwende scripts/diagram_skills.py new für einen produktionsreifen Start.
6. Lies references/enterprise-board.md für hochdichte mehrschichtige Architektur-Infografiken, Abschnittsraster, Seitenlisten, Prozessstreifen und Prinzipienkarten.
7. Der installierte Skill ist der vollständige Generierungspfad. Wenn auch ein vollständiges DiagramSkills-Repository-Checkout vorhanden ist, beschreiben references/workspaces.md, references/imports.md und references/editor.md optionale Studio-Workflows. Überprüfe, ob das editor/-Verzeichnis des Repositorys existiert, bevor du sie anbietest; mache sie niemals zu einer Voraussetzung für die Generierung.
8. Lies references/visual-language.md nur bei der Auswahl von Themen, Marken-Token, Knoten-/Kantensemantik oder der Behandlung chinesischer/englischer Bezeichnungen.
9. Wende references/quality-contract.md an. Eine generierte Datei ist nur ein Kandidat, bis die Inhaltsprüfung, strenge Validierung und visuelle Prüfung bestanden sind.

Eingabevertrag

Akzeptiere natürliche Sprache oder strukturierte Felder. Bewahre benutzerdefinierte Werte; schließe nur risikoarme Auslassungen.

• goal: die Frage oder Entscheidung, die das Diagramm unterstützen soll
• diagram_type: einer der unterstützten Slugs; leite aus der Absicht ab, wenn nicht angegeben
• audience: z.B. Führungskraft, Produkt, Entwicklung, Kunde
• narrative / scope: die Fünf-Sekunden-Geschichte und explizite In-/Out-Grenze
• must_show / emphasize / deemphasize: Inhaltspriorität vor dem Layout
• uncertainties / assumptions: nicht gelieferte Fakten und risikoarme Interpretationen
• content_risks / quality_questions: Wege, wie das Diagramm irreführen könnte, und Prüfungen nach dem Rendern
• content: Akteure, Systeme, Schritte, Fähigkeiten, Meilensteine oder Entscheidungen
• relationships: Daten-, Steuerungs-, Erfolgs-, Fehler-, asynchrone und Feedback-Links
• boundaries: Eigentümerschaft, Lebenszyklusphase, Ebene, Domäne oder Vertrauenszone
• composition: board für hochdichte Unternehmensübersichten; graph für kleinere Beziehungsdiagramme
• lanes: geordnete Eigentümer oder Rollen für ein Swimlane-Diagramm
• rank: explizite nicht-negative Hierarchieebene, wenn die automatische Reihenfolge nicht akzeptabel ist
• language: standardmäßig chinesisch zuerst; etablierte englische Fachbegiffe beibehalten
• theme: paper, notion, spectrum, blueprint oder terminal
• brand: zugelassene Hex-Farb-Token, die einer Voreinstellung überlagert werden
• views: optionale Repository-Studio-Übersichts- und Detailansichten; verbinde mit child_view
• imports: optionale Repository-Studio-Mermaid-Quelle oder CSV-Tabelle
• outputs: standardmäßig fertiges SVG/HTML plus Quell-JSON und Diagnose; PNG, wenn der lokale Rasterizer verfügbar ist

Frage nur, wenn eine ungelöste Wahl die Bedeutung, die Veröffentlichungssicherheit oder die erforderliche Ausgabe wesentlich ändert. Andernfalls wähle das konventionelle Layout aus der Typanleitung und nenne die Annahme.

Befehle

Aus dem Skill-Ordner:

python3 scripts/diagram_brief.py work/architecture.brief.json --strict
python3 scripts/diagram_skills.py types
python3 scripts/diagram_skills.py png-backend
python3 scripts/diagram_skills.py new system-architecture --output work/architecture.json
python3 scripts/diagram_skills.py validate work/architecture.json --strict
python3 scripts/diagram_skills.py render work/architecture.json --output-dir output --strict
python3 scripts/diagram_brief.py work/architecture.brief.json --spec work/architecture.json --strict --reviewed
python3 scripts/diagram_skills.py review work/architecture.json --quality output/architecture.quality.json --brief work/architecture.brief.json --artifact output/architecture.svg

render schreibt immer .svg, .html und eine hash-gebundene .quality.json-Quittung; es schreibt auch .png, wenn --png übergeben wird und png-backend einen unterstützten Rasterizer meldet. Ein strukturell gültiger Render bleibt pending-review, bis review die Quelle, das untersuchte Artefakt, das überprüfte Brief und deren Hashes verifiziert. Eine fehlgeschlagene PNG-Anfrage hinterlässt nie eine bestandene Quittung.

Der installierte Skill ist in sich geschlossen für die Generierung. Der Browser-Arbeitsbereich, Mermaid/CSV-Import und Multi-View-Editing sind Repository-Begleiter und nur über ein vollständiges Checkout mit editor/ verfügbar.

Nicht verhandelbares Verhalten

• Erstelle und validiere das prägnante Diagramm-Brief, bevor du ein nichttriviales Diagramm erstellst. Teile Designentscheidungen und Belege mit, niemals private Gedankenketten.
• Bevorzuge eine primäre Botschaft und eine Leserichtung. Teile Graphen-Diagramme mit mehr als 14 Knoten auf; ein strukturiertes Enterprise-board kann absichtlich 20–45 prägnante Karten in 3–6 Scanbändern enthalten.
• Verwende geordnete lanes für die Eigentümerschaft und Knoten-rank für die manuelle Hierarchie. Verwende groups für semantische Umhüllungen; lasse nicht ein Feld beides bedeuten.
• Verlinke dichte Übersichten mit fokussierten child_view-Details, anstatt Beschriftungen zu verkleinern.
• Markiere beabsichtigte Rückwege als feedback; unmarkierte Zyklen bestehen die Validierung nicht.
• Verwende semantische Kantentypen, keine dekorativen Farben. Zeige eine Legende, wenn zwei oder mehr Kantenbedeutungen interpretiert werden müssen.
• Erlaube Knoten-Links nur für https, http, mailto oder Seitenfragmente. Ausführbare URL-Schemata werden abgelehnt.
• Halte chinesische Bezeichnungen prägnant und setze stabile englische Fachbegriffe in Untertitel. Teile überladene Knoten auf, anstatt Text zu verkleinern.
• Bevorzuge LR für Pipelines, Roadmaps, Topologien und Feedback-Schleifen; bevorzuge TB für Ebenen, Entscheidungen, Strategien und User Journeys.
• Führe strenge Validierungen von Brief und Diagramm durch. Inspiziere das SVG oder das PNG in voller Größe, beantworte jede Typ-Profil-Frage mit eindeutigen Belegen und schließe die hash-gebundene Qualitätsquittung mit review ab.
• Beende den Vorgang nicht mit dem Schreiben von Mermaid/JSON allein, wenn der Benutzer nach einem Diagramm gefragt hat. Rendere und gib das tatsächliche Visuelle zurück.
• Halte das .brief.json und das Quell-JSON neben den Ergebnissen, damit Bedeutung und Pixel reproduzierbar und überprüfbar bleiben.
• Wenn ein vollständiges Repository-Checkout Studio-Importe bereitstellt, behandele importierte Inhalte als nicht vertrauenswürdig. Mermaid rendert im strikten Modus, CSV wird zu typisierten Feldern, und beliebiges CSS oder ausführbare Links werden abgelehnt.

Ausgabewahl

• PNG: bevorzugte Vorschau, wenn png-backend einen unterstützten lokalen Rasterizer meldet; andernfalls zeige zuerst das SVG.
• Diagramm-Brief-JSON: Inhaltsabsicht, Umfang, Unsicherheit, Priorisierung, Risiken und Überprüfungsbelege.
• SVG: skalierbare Dokumentation und Versionskontrolle.
• HTML: reaktionsschnelle Ansicht, Schwenken/Zoomen, Themenwechsel, Downloads und anklickbare Knoten.
• Qualitäts-JSON: maschinenlesbare Validierungsbelege.
• Arbeitsbereichs-JSON: optionales Repository-Studio-Format für Browser-Bearbeitung, gemischte Mermaid/Native-Ansichten, Offline-Persistenz und Drill-Down.

Erweiterung

Füge einen neuen Diagrammtyp nur hinzu, wenn er ein eigenständiges Informationsmodell oder Layout-Vertrag hat. Füge seinen Slug zu DIAGRAM_TYPES, Schema-Enum, templates/<slug>.json, references/diagram-types/<slug>.md und references/diagram-thinking-profiles.json hinzu; füge dann strenge Render- und Denkprofil-Tests hinzu. Erweitere CSV-Zuordnungen in einem Adapter und Arbeitsbereichsfelder sowohl in Zod als auch im JSON-Schema. Neue Themen müssen die Knoten- und Kantensemantik über helle und dunkle Darstellung hinweg bewahren.