Was macht syokan?
syokan (召喚, „herbeirufen“) ist ein Verb – LLMs rufen reiche UI auf. Wenn der Benutzer „syokan X“ sagt (JP: 「Xを syokan」), ist das eine Aufforderung, diese Daten in einer Ansicht darzustellen. Unter der Haube handelt es sich um eine schema-getriebene View-Schicht: Statt JSX zu schreiben, sprichst du eine JSON-Beschwörung – einen Baum aus Katalogkomponenten – und syokan rendert sie mit vordefinierten Komponenten. Deine Aufgabe ist es, die Daten in einen Umschlag zu packen und per POST an syokan zu senden. In Prosa verwende syokan als reines transitives Verb (niemals „syokan tun“ / niemals 「syokan する」 – syokan steht für sich allein).
Wenn syokan noch nicht installiert ist (syokan --help schlägt fehl) oder der Benutzer „Onboarding“, „einrichten“ oder „erste Nutzung“ sagt, führe sie durch references/onboarding.md bis zu ihrem ersten Snapshot. Führe keine umgebungsverändernden Operationen wie Installationen stillschweigend aus: melde, dass es nicht installiert ist, und hole die Zustimmung des Benutzers ein, bevor du es ausführst (installiere nie eigenständig).
Unverhandelbar
- Snapshots sind flüchtig: Ein geposteter Snapshot hat keine Bestandsgarantie. Lege dort nur rekonstruierbare, vorübergehende Daten ab (heutiges RSS, eine laufende Überprüfung usw.). Für Layouts, die du wiederverwendest, speichere eine Vorlage zur Reproduktion (Vorlagen bleiben bestehen – siehe „Vorlagen für Reproduzierbarkeit“ unten).
- Nur JSON: Der Server akzeptiert nichts außer einem JSON-Umschlag. Rohes Markdown oder Klartext wird abgelehnt. Um Prosa anzuzeigen, verpacke sie in einen
MarkdownDoc- oderPlainText-Knoten. - Strenges Schema: Props werden streng validiert. Schlüssel, die nicht im Schema sind, werden abgelehnt – erfinde keine zusätzlichen Schlüssel.
- Blätter können keine Kinder haben: Nur
StackundCardakzeptieren Kinder. Das Anhängen von Kindern an einen Blattknoten wird bei der Aufnahme abgelehnt.
Vom Erstellen zum Anzeigen
- Überprüfe die verfügbaren Typen und Props mit
syokan catalog(siehe „Katalog“ unten). - Ordne die anzuzeigenden Daten auf diese Komponenten ab. Die oberste Ebene ist normalerweise ein Container (
Stackusw.), der Elemente vertikal stapelt. - Erstelle daraus einen JSON-Umschlag (siehe „Umschlagform“ unten). Nur
rootist erforderlich. - Sende ihn mit der CLI ab (siehe „Absenden“ unten). Bei Erfolg wird die Ansichts-URL ausgegeben.
Wenn du zuvor bereits eine ähnliche Ansicht erstellt hast, beginne nicht von Null – basiere sie auf einer gespeicherten Vorlage (siehe „Vorlagen für Reproduzierbarkeit“ unten).
Umschlagform
Nur das Folgende darf im POST-Body enthalten sein.
Füge niemals id, createdAt oder url ein – der Server weist sie zu.
{
"root": { "type": "Stack", "props": {}, "children": [ /* Katalogknoten; vollständige Beispiele in references/examples.md */ ] }, // erforderlich. der Ansichtsbaum
"title": "Heutiges RSS", // optional. wird in der Liste und im Ansichtskopf angezeigt
"metadata": { "source": { "label": "daily-rss" } }, // optional. Herkunftsbezeichnung
"schemaVersion": 1, // optional. Der Server füllt es aus
"idempotencyKey": "rss-2026-06-28" // optional. benennt diese Ansicht, sodass sie später aktualisiert werden kann, statt dupliziert zu werden
}
metadata.source behält zusätzliche Schlüssel über label hinaus; du kannst url oder fetchedAt hinzufügen (z. B. { "label": "gh-review", "url": "https://example.com/..." }).
Für tägliche oder wiederkehrende Ansichten füge etwas wie das Datum in den idempotencyKey ein. Die syokan-CLI kümmert sich um den Rest: Sie zielt zuerst auf diesen Schlüssel ab und erstellt nur dann eine neue Ansicht, wenn noch keine existiert – der erste Post erstellt also die Ansicht, und jeder spätere Post mit demselben Schlüssel aktualisiert dieselbe Ansicht an Ort und Stelle, anstatt sie zu duplizieren. Du musst nicht selbst verfolgen, ob es der erste Post ist. (Wenn du stattdessen die HTTP-API direkt anstelle der CLI verwendest: POST /api/snapshots erstellt immer und taggt den Schlüssel; PUT /api/snapshots zielt auf einen vorhandenen Schlüssel ab und gibt 404 zurück, wenn er noch nicht vorhanden ist – es gibt keinen Create-on-Miss-Endpunkt, weshalb die CLI zuerst PUT ausprobiert und bei einem 404 auf POST zurückfällt.)
Katalog
Rufe die verfügbaren types und ihre Props-Definitionen von syokan catalog ab (niemals in md übertragen – ziehe sie jedes Mal von hier).
Die Ausgabe ist { "items": [{ "type", "props", "childrenTypes" }] }.
props: die Props des Typs als JSON-Schema. Erfüllerequired/enum/format(httpUrl isturi,Time.datetimeistdate-time) /additionalProperties:false(unbekannte Schlüssel werden abgelehnt) genau wie angegeben.childrenTypes:nullbedeutet ein Container, der Kinder akzeptiert,[]bedeutet ein Blatt, das keine akzeptiert,[..]bedeutet, dass nur die aufgeführten Typen Kinder sein dürfen.
Vollständige Beispiele, die die Komponenten kombinieren, findest du in references/examples.md.
Absenden
Übergib den zusammengestellten Umschlag als Datei oder über stdin; bei Erfolg wird die Ansichts-URL nach stdout ausgegeben (syokan snapshot.json / cat snapshot.json | syokan / claude -p '…JSON…' | syokan).
Für alles andere – Befehle, Unterbefehle, Umgebungsvariablen, Exit-Codes – konsultiere syokan --help --json; für Typen und Props syokan catalog.
Vorschau lokaler Dateien
Für eine lokale Datei ist syokan <pfad> der kürzeste Weg – du syokanst die Datei selbst. Umschlag-JSON wird unverändert übermittelt; alles andere (Markdown / Log / txt / json, ...) wird automatisch in ein Live-FileDoc verpackt. Die CLI löst es in einen absoluten Pfad auf und übergibt ihn an den Server, der den Inhalt liest und das Format aus der Erweiterung ableitet (.md/.markdown → Markdown, .json → Code, alles andere → Text). Während die Ansicht geöffnet ist, folgt sie Änderungen an der Datei (kein erneutes Absenden nötig).
syokan notes.md # rendert Markdown; die Ansicht aktualisiert sich bei jedem Speichern
syokan app.log # zeigt ein wachsendes Log in nichtproportionaler Schrift an
Um mehrere Dateien in einer Ansicht zu kombinieren oder sie mit Heading und anderen Knoten zu mischen, platziere selbst FileDoc-Knoten (Props: path, nur absolute Pfade; FileDoc übernimmt das Lesen und die Änderungsverfolgung).
Umgekehrt, um den Inhalt einer Datei statisch eingefroren anzuzeigen (keine Nachverfolgung nötig, oder du transformierst den Inhalt), setze den Body in einen MarkdownDoc- / PlainText- / Code-Knoten. jq --rawfile streamt ihn ein, ohne sich um JSON-Escaping kümmern zu müssen.
jq -n --rawfile body README.md \
'{title:"README.md", root:{type:"Stack",props:{},children:[{type:"MarkdownDoc",props:{body:$body}}]}}' \
| syokan
Vorlagen für Reproduzierbarkeit
Baue eine Lieblingsansicht nicht jedes Mal von Grund auf neu – speichere sie als Vorlage in syokan und verwende sie wieder.
Eine Vorlage ist „der gespeicherte Umschlag selbst“. Du kannst Marker wie {{...}} im Gerüst platzieren und sie selbst ausfüllen.
Wenn eine passende Vorlage existiert, beginne nicht von Null: finde die ID in der Liste → rufe sie ab → tausche die Daten ein → sende ab. Wenn du eine neue, erhaltenswerte Ansicht erstellst, speichere sie und reproduziere sie beim nächsten Mal. Die Unterbefehlssyntax (templates list|add|get|rm) findest du unter syokan --help --json.