amirtaherkhani/diago

Archify

Erstellen Sie ein eigenständiges, interaktives HTML-Diagramm aus einer kleinen getypten JSON-Spezifikation. Die statische Ausgabe ist die Standardeinstellung; aktivieren Sie Bewegungen nur, wenn der Benutzer nach einer Demo oder Präsentation fragt.

Schneller Autorenpfad

Verwenden Sie diesen begrenzten Pfad für die gewöhnliche Generierung. Lesen Sie die optionale Viewer-Laufzeitumgebungs-Referenz nur, wenn der Benutzer nach diesen Funktionen fragt.

1. Wählen Sie aus der Frage architecture, workflow, sequence, dataflow oder lifecycle.

2. Lesen Sie ein passendes Schema in schemas/, schemas/common.schema.json und ein passendes JSON-Beispiel in examples/. Lesen Sie nur diese Dateien. Neuartigkeit bedeutet neue stabile IDs, domänenspezifische Formulierungen und Layout; verwenden Sie das Beispiel für die Feldstruktur, nicht für Fakten.

3. Zuerst das Artefakt: Die nächste Tool-Aktion muss den Kandidaten schreiben. Schreiben Sie den Kandidaten, bevor Sie die Interna des Renderers inspizieren. Planen Sie keine genauen Koordinaten in Prosa. Beginnen Sie mit einem klaren Hauptpfad, kurzen Nebenverzweigungen, spärlichen Beschriftungen und maximal 12 primären Knoten. Setzen Sie meta.quality_profile auf "showcase", es sei denn, der Benutzer fordert explizit eine dichte standard-Karte. Beginnen Sie mit automatischen Routen und Beschriftungen. Fügen Sie kein via, channelX, channelY oder labelAt hinzu, bevor eine Diagnose eine solche Angabe erfordert; wenden Sie maximal eine diagnostizierte Geometriesteuerung pro Reparatur an.

4. Validieren Sie nach jeder Kandidatenbearbeitung und unmittelbar vor der Übergabe:

   node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json
   

   Ein Beleg mit nur 4 Artefaktprüfungen ist eine grundlegende Validierung, niemals eine Showcase-Akzeptanz. Ein Showcase-Durchlauf muss alle 9 Artefaktprüfungen mit 0 Kompositionsfehlern und 0 Warnungen melden. Wenn der Kandidat das genaue Feld meta.quality_profile auslässt oder falsch schreibt, korrigieren Sie es vor der Geometrie. Eine erfolgreiche finale Validierung friert den Kandidaten ein: Bearbeiten Sie ihn danach nie mehr.

5. Für ein ausgeliefertes HTML ist deliver der endgültige Akzeptanzbefehl:

   node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
   

   Ein Exit-Code ungleich Null darf niemals als Erfolg beschrieben werden. Wenn die Validierung fehlschlägt, ändern Sie nur das diagnostizierte subject, überprüfen Sie evidence, wählen Sie aus supportedFixes und führen Sie erneut aus. Setzen Sie die fokussierte Korrektur fort, während die objektive Fehlerzahl ein neues Minimum erreicht. Wenn sich die beste Zählung in zwei aufeinanderfolgenden Runden nicht verbessert, brechen Sie ab und melden Sie die ungelösten Diagnosen wahrheitsgemäß.

Lesen Sie renderers/shared/geometry.mjs, den Renderer-Quellcode, den Validator-Quellcode, Tests oder Benchmarks nicht vor dem ersten Kandidaten. Inspizieren Sie die Implementierung nur für eine nicht unterstützte interne Diagnose oder nach zwei fehlgeschlagenen fokussierten Reparaturen.

Hinweis zum Lebenszyklus: Phasenspalten 0..4 belegen die Hauptschiene; Ereignis-/Ergebnisspalten 0..2 werden unterhalb späterer Phasen ausgerichtet. Ein wiederherstellbarer Zustand verwendet type: "failure" plus einen echten Übergang zurück zum aktiven Zustand.

Typ-Router

Typ	Verwendung für
architecture	Komponenten, Dienste, Cloud-/Sicherheitsgrenzen, Infrastruktur
workflow	Prozesse, Genehmigungsschleusen, Tool-Aufrufe, Runbooks, CI/CD
sequence	API-Aufrufketten, Anforderungslebenszyklen, asynchrone Ablaufverfolgungen, Rückgaben
dataflow	Pipelines, ETL/ELT, Linien, Governance, Verbraucher
lifecycle	Zustands-/Statusübergänge, Wiederholungen, Warte- und Endzustände

Bei Unklarheit führen Sie node bin/archify.mjs guide "<scenario>" --json aus. Szenariobeispiele sind strukturelle Referenzen, keine zu kopierenden Fakten.

Mermaid-Eingabe

Lesen Sie Mermaid für Topologie und Bedeutung, und schreiben Sie dann frische Archify-JSON; rendern Sie Mermaid-Stile nicht mechanisch.

• flowchart / graph → workflow, oder architecture für eine Komponentenkarte.
• sequenceDiagram → sequence; Teilnehmer werden semantische Teilnehmer und Pfeile werden Nachrichten.
• stateDiagram → lifecycle; Zustände und Übergänge behalten ihre Bedeutung, nicht den Mermaid-Stil.

Autoren-Invarianten

• Ein offensichtlicher Hauptpfad; Nebenverzweigungen verlassen den nächsten Knoten des Hauptpfads. Entfernen Sie Kanten mit geringem Wert, bevor Sie Routing-Steuerungen hinzufügen.
• Lassen Sie meta.legend für die wahrheitsgemäße Standardeinstellung auto weg. Wenn nötig, verwenden Sie nur mode: auto|all|hidden und vom Renderer unterstützte entries.<kind>.label|visible; Labels ändern niemals die Semantik.
• Komponententypen sind frontend, backend, database, cloud, security, messagebus und external; Varianten sind default, emphasis, security und dashed.
• Abstand bedeutet klaren Zwischenraum, nicht Mittenabstand. Bei einem Beziehungs-Label muss der klare Abstand größer sein als seine gemessene Maskenbreite; andernfalls lassen Sie das Label weg oder verschieben Sie es gezielt.
• Automatische Routen besitzen ihre Endpunktseiten. Eine Seite ist ein Richtungsvertrag: Das erste und letzte Segment muss diese Seite senkrecht verlassen/betreten.
• Automatische Port-Verteilung ist ein Standard-Renderer-Verhalten für Architektur, Workflow, Datenfluss und Lebenszyklus. Es überspringt einzelne Beziehungen und explizite via, channelX, channelY, labelAt oder nicht-auto-Routen. Nahe parallele Ports verwenden eine äußere Brücke, sodass automatisches Routing kein Segment unter 8 px oder eine innere Kurve unter 16 px erzeugen kann.
• Akzeptieren Sie niemals eine Kante, die einen nicht zusammenhängenden undurchsichtigen Knoten, einen mehrdeutigen gemeinsamen Korridor oder ein Beziehungs-Label, das eine andere Route maskiert, kreuzt.

Lesen Sie references/authoring-contract.md nur, wenn Sie Feld-Enums, Abstandsmathematik, Geometrie-Reparaturregeln, Repository-Nachweise oder modusspezifische Platzierung benötigen.

Lieferung

Verwenden Sie validate während der Reparatur und deliver einmalig für die finale Akzeptanz. Die Lieferung friert die exakten Spezifikationsbytes in einen privaten Snapshot im selben Verzeichnis ein, rendert und prüft diesen Snapshot, committet das HTML atomar und meldet SHA-256 sowie Byte-Zahlen sowohl für die Spezifikation als auch für das Artefakt.

Fügen Sie --open nur hinzu, wenn der Benutzer eine sofortige lokale Vorschau wünscht. Für eine aktive Desktop-Autorenschleife lautet der optionale Befehl:

node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcase

Starten Sie niemals standardmäßig eine Vorschau. Lesen Sie references/delivery-contract.md, wenn Sie Vorschau, Repository-Nachweise, Exportbelege, visuelle Überprüfung oder das Öffnen nach dem Commit verwenden.

Optionale Betrachterfähigkeiten

Das generierte HTML enthält bereits Themenwechsel, Schwenken/Zoomen, Suche, Fokus, Beziehungsverfolgung, semantische Ansichten, Präsentation und wahrheitsgemäße Exporte. Dies sind Leserfähigkeiten, keine zusätzliche Autorenarbeit. meta.animation: "trace" ist optional; meta.views ist optional und sollte höchstens fünf kuratierte Kapitel enthalten.

Lesen Sie references/viewer-runtime.md nur, wenn der Benutzer explizit nach Teilen-Karten, Route-/Reach-Karten, Bewegung, geführten Geschichten, Deep Links, Präsentation, Suche/Fokus oder einer anderen Viewer-Laufzeitumgebungs-Funktion fragt.

Einrichtung und Fallback

Innerhalb des Skill-Pakets ist keine Installation erforderlich. Überprüfen Sie mit:

node bin/archify.mjs doctor
node bin/archify.mjs demo <output-directory>

Wenn Shell-Zugriff nicht verfügbar ist, platzieren Sie das Architektur-SVG manuell in assets/template.html, verwenden Sie semantische CSS-Klassen anstelle von Inline-Farben und befolgen Sie den visuellen Überprüfungsvertrag in references/delivery-contract.md.

Ausgabe

Geben Sie den geprüften HTML-Pfad, den Diagrammtyp, die Validierungszusammenfassung, den Spezifikations-/Artefaktbeleg und den wahrheitsgemäßen Status der visuellen Überprüfung zurück. Beanspruchen Sie keinen Erfolg für einen Befehl mit einem Exit-Code ungleich Null und beanspruchen Sie keine visuelle Inspektion, die Sie nicht durchgeführt haben.