cubxxw/archify

Was macht archify?

Erstellen Sie ein eigenständiges, interaktives HTML-Diagramm aus einer kleinen, typisierten JSON-Spezifikation. Statische Ausgabe ist der Standard; aktivieren Sie Bewegung nur, wenn der Benutzer eine Demo oder Präsentation wünscht.

Schneller Autorenpfad

Verwenden Sie diesen begrenzten Pfad für die normale Erstellung. Lesen Sie die optionale Viewer-Laufzeit-Referenz erst, wenn der Benutzer nach diesen Funktionen fragt.

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

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

3. Artefakt zuerst: Die nächste Tool-Aktion muss den Kandidaten schreiben. Schreiben Sie den Kandidaten, bevor Sie die Renderer-Interna untersuchen. Planen Sie keine genauen Koordinaten in Prosa. Beginnen Sie mit einem klaren Hauptpfad, kurzen Nebenpfaden, 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 via, channelX, channelY oder labelAt erst hinzu, wenn eine Diagnose dies erfordert; wenden Sie höchstens ein diagnostiziertes Geometriekontrollmittel 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
   

   Eine Quittung mit nur 4 Artefaktprüfungen ist eine Basisvalidierung, niemals eine Showcase-Abnahme. 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. Ein bestandener finaler Validierungslauf friert den Kandidaten ein: Bearbeiten Sie ihn danach nie mehr.

5. Für eine ausgelieferte HTML-Datei ist deliver der letzte Akzeptanzbefehl:

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

   Ein Exit-Code ungleich Null kann 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 es erneut aus. Setzen Sie die fokussierte Korrektur fort, während die objektive Fehleranzahl ein neues Minimum erreicht. Wenn zwei aufeinanderfolgende Runden dieses beste Minimum nicht verbessern, stoppen Sie und melden Sie die ungelösten Diagnosen wahrheitsgemäß.

Lesen Sie renderers/shared/geometry.mjs, Renderer-Quellcode, Validator-Quellcode, Tests oder Benchmarks nicht vor dem ersten Kandidaten. Untersuchen Sie die Implementierung nur für eine nicht unterstützte interne Diagnose oder nachdem zwei fokussierte Reparaturen fehlgeschlagen sind.

Hinweis zum Lebenszyklus: Phasenspalten 0..4 belegen die Hauptschiene; Ereignis-/Ergebnisspalten 0..2 werden unter späteren 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, Genehmigungsstufen, Tool-Aufrufe, Runbooks, CI/CD
sequence	API-Aufrufketten, Anfrage-Lebenszyklen, asynchrone Abläufe, Rückgaben
dataflow	Pipelines, ETL/ELT, Datenherkunft, Governance, Verbraucher
lifecycle	Zustands-/Statusübergänge, Wiederholungen, wartende und terminale Zustände

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

Mermaid-Eingabe

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

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

Autoren-Invarianten

• Ein offensichtlicher Hauptpfad; Nebenpfade verlassen den nächstgelegenen Hauptpfad-Knoten. Entfernen Sie Kanten mit geringem Wert, bevor Sie Routing-Steuerungen hinzufügen.
• Lassen Sie meta.legend für den wahrheitsgemäßen auto-Standard weg. Wenn nötig, verwenden Sie nur mode: auto|all|hidden und 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 Mittelpunktabstand. Bei einem Beziehungs-Label muss der klare Zwischenraum seine gemessene Maskenbreite überschreiten; andernfalls lassen Sie das Label weg oder platzieren Sie es bewusst.
• Automatische Routen besitzen ihre Endpunktseiten. Eine Seite ist ein Richtungsvertrag: Das erste und letzte Segment müssen senkrecht zu dieser Seite verlassen/eintreten.
• 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. Nahezu parallele Ports verwenden eine externe Brücke, damit automatisches Routing kein Segment unter 8px oder Innenkurve unter 16px erzeugt.
• Akzeptieren Sie niemals eine Kante, die einen nicht verwandten opaken Knoten kreuzt, einen mehrdeutigen gemeinsamen Korridor oder ein Beziehungs-Label, das eine andere Route maskiert.

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

Auslieferung

Verwenden Sie validate während der Reparatur und deliver einmal für die finale Abnahme. Die Auslieferung friert die exakten Spezifikationsbytes in einem privaten, gleichnamigen Verzeichnis-Snapshot ein, rendert und prüft diesen Snapshot, committet das HTML atomar und meldet SHA-256 sowie Byte-Anzahl für Spezifikation und Artefakt.

Fügen Sie --open nur hinzu, wenn der Benutzer eine sofortige lokale Vorschau wünscht. Für einen aktiven Desktop-Autoren-Workflow 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, Exportquittungen, visuelle Überprüfung oder Öffnen nach dem Commit verwenden.

Optionale Viewer-Funktionen

Generiertes HTML enthält bereits Themenwechsel, Pan/Zoom, Suche, Fokus, Beziehungsverfolgung, semantische Ansichten, Präsentation und wahrheitsgemäße Exporte. Dies sind Leser-Funktionen, keine zusätzliche Autorenarbeit. meta.animation: "trace" ist Opt-in; 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 Share Cards, Route/Reach Cards, Bewegung, geführten Geschichten, Deep Links, Präsentation, Suche/Fokus oder einer anderen Viewer-Laufzeit-Funktion fragt.

Einrichtung und Fallback

Keine Installation innerhalb des Skill-Pakets erforderlich. Überprüfen Sie mit:

node bin/archify.mjs doctor
node bin/archify.mjs demo <ausgabe-verzeichnis>

Wenn Shell-Zugriff nicht verfügbar ist, platzieren Sie Architektur-SVG manuell in assets/template.html, verwenden Sie CSS-semantische 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, die Spezifikations-/Artefaktquittung und den wahrheitsgemäßen Status der visuellen Überprüfung zurück. Beanspruchen Sie keinen Erfolg für einen Befehl mit Exit-Code ungleich Null oder beanspruchen Sie eine visuelle Inspektion, die Sie nicht durchgeführt haben.