Communitygithub.com

wwwyo/syokan

syokan — les LLMs invoquent une UI riche. Prononcez une incantation JSON, et une interface vivante apparaît. Éphémère par conception.

Qu'est-ce que syokan ?

syokan (召喚, « invoquer ») est un verbe qui permet aux LLMs de créer dynamiquement une interface utilisateur éphémère à partir d'une description JSON. Au lieu d'écrire du JSX, vous définissez une structure de composants sous forme d'arbre JSON, et syokan la rend avec des composants prédéfinis. Cette compétence est particulièrement utile pour visualiser rapidement des données temporaires (flux RSS, revues de code, logs) sans infrastructure persistante. Elle fonctionne avec son propre CLI, et peut être intégrée à des outils comme Claude Code, Cursor ou Codex via une simple commande POST. Les snapshots sont éphémères par conception, mais il est possible de sauvegarder des templates pour reproduire des mises en page récurrentes.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add wwwyo/syokan

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait syokan ?

syokan (召喚, « invoquer ») est un verbe — les LLMs invoquent une UI riche. Lorsque l'utilisateur dit « syokan X » (JA: 「Xを syokan」), cela signifie qu'il souhaite matérialiser ces données dans une vue. Sous le capot, c'est une couche de rendu pilotée par un schéma : au lieu d'écrire du JSX, vous prononcez une incantation JSON — un arbre de composants du catalogue — et syokan le rend avec des composants prédéfinis. Votre travail consiste à assembler les données dans une enveloppe et à la POSTer vers syokan. En prose, utilisez syokan comme un verbe transitif nu (jamais « faire syokan », ni 「syokan する」 — syokan se suffit à lui-même).

Si syokan n'est pas encore installé (syokan --help échoue), ou si l'utilisateur dit « onboarding », « configure-le », ou « première utilisation », guidez-le à travers references/onboarding.md jusqu'à son premier snapshot. N'exécutez pas silencieusement des opérations qui modifient l'environnement, comme des installations : signalez qu'il n'est pas installé et obtenez l'approbation de l'utilisateur avant d'exécuter (n'installez jamais de votre propre initiative).

Non-négociables

  • Les snapshots sont éphémères : un snapshot posté n'a aucune garantie de persistance. N'y mettez que des données reconstructibles et transitoires (le RSS du jour, une revue en cours, etc.). Pour les mises en page que vous réutilisez, sauvegardez un template pour les reproduire (les templates persistent — voir « Templates pour la reproductibilité » ci-dessous).
  • JSON uniquement : le serveur n'accepte rien d'autre qu'une enveloppe JSON. Le markdown brut ou le texte brut est rejeté. Pour afficher de la prose, enveloppez-la dans un nœud MarkdownDoc ou PlainText.
  • Schéma strict : les props sont validées strictement. Les clés qui ne figurent pas dans le schéma sont rejetées — n'inventez pas de clés supplémentaires.
  • Les feuilles ne peuvent pas avoir d'enfants : seuls Stack et Card acceptent des enfants. Attacher des enfants à un nœud feuille est rejeté à l'ingestion.

De la composition à la visualisation

  1. Vérifiez les types et props disponibles avec syokan catalog (voir « Catalogue » ci-dessous).
  2. Mappez les données que vous souhaitez afficher sur ces composants. Le niveau supérieur est généralement un conteneur (Stack, etc.) qui empile les éléments verticalement.
  3. Transformez-le en une enveloppe JSON (voir « Forme de l'enveloppe » ci-dessous). Seul root est obligatoire.
  4. Postez-le avec le CLI (voir « Publication » ci-dessous). En cas de succès, l'URL de la vue est affichée.

Si vous avez déjà construit une vue similaire auparavant, ne repartez pas de zéro — basez-vous sur un template sauvegardé (voir « Templates pour la reproductibilité » ci-dessous).

Forme de l'enveloppe

Seuls les éléments suivants peuvent figurer dans le corps du POST. N'incluez jamais id, createdAt ou url — le serveur les attribue.

{
  "root": { "type": "Stack", "props": {}, "children": [ /* nœuds du catalogue ; des exemples complets dans references/examples.md */ ] }, // obligatoire. l'arbre de la vue
  "title": "RSS d'aujourd'hui",                                // optionnel. affiché dans la liste et l'en-tête de la vue
  "metadata": { "source": { "label": "daily-rss" } },   // optionnel. étiquette de provenance
  "schemaVersion": 1,                                    // optionnel. le serveur le complète
  "idempotencyKey": "rss-2026-06-28"                     // optionnel. nomme cette vue pour pouvoir la rafraîchir plus tard sans la dupliquer
}

metadata.source accepte d'autres clés que label ; vous pouvez ajouter url ou fetchedAt (ex. { "label": "gh-review", "url": "https://example.com/..." }).

Pour les vues quotidiennes ou récurrentes, incluez quelque chose comme la date dans l'idempotencyKey. Le CLI syokan gère le reste : il cible d'abord cette clé, et ne crée une nouvelle vue que si aucune n'existe encore — ainsi la première publication crée la vue et chaque publication ultérieure avec la même clé rafraîchit cette même vue sur place au lieu de la dupliquer. Vous n'avez pas besoin de savoir s'il s'agit de la première publication. (Si vous appelez l'API HTTP directement au lieu du CLI : POST /api/snapshots crée toujours et étiquette la clé ; PUT /api/snapshots cible une clé existante et renvoie 404 si elle n'existe pas encore — il n'y a pas de point de terminaison create-if-not-exists, c'est pourquoi le CLI essaie PUT d'abord et se rabat sur POST en cas de 404.)

Catalogue

Obtenez les types disponibles et leurs définitions de props à partir de syokan catalog (ne les retranscrivez jamais en md — tirez-les d'ici à chaque fois).

La sortie est { "items": [{ "type", "props", "childrenTypes" }] }.

  • props: les props du type sous forme de schéma JSON. Satisfaites required / enum / format (httpUrl est uri, Time.datetime est date-time) / additionalProperties:false (les clés inconnues sont rejetées) exactement comme indiqué.
  • childrenTypes: null signifie un conteneur qui accepte des enfants, [] signifie une feuille qui n'en accepte aucun, [..] signifie que seuls les types listés peuvent être des enfants.

Pour des exemples complets combinant les composants, voir references/examples.md.

Publication

Passez l'enveloppe assemblée sous forme de fichier ou via stdin ; en cas de succès, l'URL de la vue est affichée sur stdout (syokan snapshot.json / cat snapshot.json | syokan / claude -p '…JSON…' | syokan).

Pour tout le reste — commandes, sous-commandes, variables d'environnement, codes de sortie — consultez syokan --help --json ; pour les types et props, syokan catalog.

Aperçu des fichiers locaux

Pour un fichier local, syokan <chemin> est le chemin le plus court — vous syokan le fichier lui-même. L'enveloppe JSON est postée telle quelle ; tout autre format (markdown / log / txt / json, ...) est automatiquement enveloppé dans un FileDoc en direct. Le CLI le résout en chemin absolu et le transmet au serveur, qui lit le contenu et déduit le format de l'extension (.md/.markdown → markdown, .json → code, tout le reste → texte). Tant que la vue est ouverte, elle suit les modifications du fichier (pas besoin de reposter).

syokan notes.md   # rend le markdown ; la vue se rafraîchit à chaque sauvegarde
syokan app.log    # affiche un journal en croissance en police monospace

Pour combiner plusieurs fichiers dans une seule vue, ou les mélanger avec des Heading et d'autres nœuds, placez vous-même des nœuds FileDoc (props : path, chemins absolus uniquement ; FileDoc gère la lecture et le suivi des modifications).

Inversement, pour afficher le contenu d'un fichier figé statiquement (sans suivi nécessaire, ou vous transformez le contenu), mettez le corps dans un nœud MarkdownDoc / PlainText / Code. jq --rawfile le stream sans se soucier de l'échappement JSON.

jq -n --rawfile body README.md \
  '{title:"README.md", root:{type:"Stack",props:{},children:[{type:"MarkdownDoc",props:{body:$body}}]}}' \
  | syokan

Templates pour la reproductibilité

Ne reconstruisez pas une vue favorite à partir de zéro chaque fois — sauvegardez-la comme template dans syokan et réutilisez-la. Un template est « l'enveloppe elle-même sauvegardée ». Vous pouvez placer des marqueurs comme {{...}} dans le squelette et les remplir vous-même.

Si un template correspondant existe, ne partez pas de zéro : trouvez son id dans la liste → récupérez-le → échangez les données → postez. Lorsque vous produisez une nouvelle vue qui mérite d'être conservée, sauvegardez-la et reproduisez-la la prochaine fois. Pour la syntaxe des sous-commandes (templates list|add|get|rm), consultez syokan --help --json.

Skills associés