Communitygithub.com

wwwyo/syokan

syokan — LLMs invocam UI rica. Recite uma invocação JSON e uma interface viva aparece. Efêmera por design.

O que é syokan?

syokan (召喚, "invocar") é um verbo que permite que LLMs (modelos de linguagem de grande escala) criem interfaces de usuário ricas e efêmeras. Em vez de escrever JSX, você descreve a interface como uma árvore de componentes em JSON, e o syokan a renderiza com componentes predefinidos. O fluxo de trabalho é simples: o agente de IA monta os dados em um envelope JSON e o envia via CLI para o servidor syokan, que devolve uma URL para visualização. A ferramenta é ideal para visualizações transitórias e reconstruíveis, como um feed RSS diário, uma revisão em andamento ou logs de aplicação. Ela suporta visualização de arquivos locais com atualização em tempo real, e permite salvar templates para reproduzir layouts favoritos sem recomeçar do zero. O catálogo de componentes é dinâmico e deve ser consultado via comando `syokan catalog`, que retorna os tipos, props (em JSON Schema) e tipos de filhos permitidos. O envelope JSON aceita apenas os campos `root` (obrigatório), `title`, `metadata`, `schemaVersion` e `idempotencyKey`. O sistema é estrito: props desconhecidas são rejeitadas, folhas não podem ter filhos, e snapshots não têm garantia de persistência.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add wwwyo/syokan

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que syokan faz?

syokan (召喚, "invocar") é um verbo — LLMs invocam UI rica. Quando o usuário diz "syokan X" (JA: 「Xを syokan」), isso é um pedido para invocar esses dados em uma visualização. Por baixo dos panos, é uma camada de visualização orientada por esquema: em vez de escrever JSX, você profere uma invocação JSON — uma árvore de componentes do catálogo — e o syokan a renderiza com componentes predefinidos. Seu trabalho é montar os dados em um envelope e fazer POST para o syokan. Em prosa, use syokan como um verbo transitivo nu (nunca "faça syokan" / nunca 「syokan する」 — syokan se sustenta sozinho).

Se o syokan ainda não estiver instalado (syokan --help falhar), ou o usuário disser "onboarding", "configurar" ou "primeira vez usando", guie-o por references/onboarding.md até o primeiro snapshot. Não execute operações que alterem o ambiente silenciosamente, como instalações: relate que não está instalado e obtenha a aprovação do usuário antes de executar (nunca instale por conta própria).

Inegociáveis

  • Snapshots são efêmeros: um snapshot enviado não tem garantia de persistência. Coloque apenas dados reconstruíveis e transitórios lá (RSS de hoje, uma revisão em andamento, etc.). Para layouts que você reutiliza, salve um template para reproduzi-los (templates persistem — veja "Templates para reprodutibilidade" abaixo).
  • Apenas JSON: o servidor aceita nada além de um envelope JSON. Markdown bruto ou texto simples é rejeitado. Para mostrar prosa, envolva-a em um nó MarkdownDoc ou PlainText.
  • Esquema estrito: as props são validadas rigorosamente. Chaves que não estão no esquema são rejeitadas — não invente chaves extras.
  • Folhas não podem ter filhos: apenas Stack e Card aceitam filhos. Anexar filhos a um nó folha é rejeitado na ingestão.

Da composição à visualização

  1. Verifique os tipos e props disponíveis com syokan catalog (veja "Catálogo" abaixo).
  2. Mapeie os dados que você quer mostrar para esses componentes. O nível superior geralmente é um contêiner (Stack etc.) empilhando itens verticalmente.
  3. Transforme-o em um envelope JSON (veja "Forma do envelope" abaixo). Apenas root é obrigatório.
  4. Envie-o com a CLI (veja "Envio" abaixo). Em caso de sucesso, a URL da visualização é impressa.

Se você já construiu uma visualização semelhante antes, não comece do zero — baseie-se em um template salvo (veja "Templates para reprodutibilidade" abaixo).

Forma do envelope

Apenas o seguinte pode ir no corpo do POST. Nunca inclua id, createdAt ou url — o servidor os atribui.

{
  "root": { "type": "Stack", "props": {}, "children": [ /* nós do catálogo; exemplos completos em references/examples.md */ ] }, // obrigatório. a árvore de visualização
  "title": "RSS de hoje",                                // opcional. mostrado na lista e no cabeçalho da visualização
  "metadata": { "source": { "label": "daily-rss" } },   // opcional. rótulo de proveniência
  "schemaVersion": 1,                                    // opcional. o servidor o preenche
  "idempotencyKey": "rss-2026-06-28"                     // opcional. nomeia esta visualização para que possa ser atualizada depois em vez de duplicada
}

metadata.source aceita chaves extras além de label; você pode adicionar url ou fetchedAt (ex.: { "label": "gh-review", "url": "https://exemplo.com/..." }).

Para visualizações diárias ou recorrentes, inclua algo como a data no idempotencyKey. A CLI do syokan cuida do resto: ela primeiro tenta essa chave, e só cria uma nova visualização se nenhuma existir ainda — então a primeira postagem cria a visualização e toda postagem posterior com a mesma chave atualiza essa mesma visualização no lugar, em vez de duplicá-la. Você não precisa rastrear se é a primeira postagem. (Se você chamar a API HTTP diretamente em vez da CLI: POST /api/snapshots sempre cria e marca a chave; PUT /api/snapshots atinge uma chave existente e retorna 404 se ela ainda não estiver lá — não há endpoint create-on-miss, e por isso a CLI tenta PUT primeiro e recai para POST em caso de 404.)

Catálogo

Obtenha os types disponíveis e suas definições de props a partir de syokan catalog (nunca os transcreva para md — extraia-os daqui toda vez).

A saída é { "items": [{ "type", "props", "childrenTypes" }] }.

  • props: as props do tipo como JSON Schema. Satisfaça required / enum / format (httpUrl é uri, Time.datetime é date-time) / additionalProperties:false (chaves desconhecidas são rejeitadas) exatamente como fornecido.
  • childrenTypes: null significa um contêiner que aceita filhos, [] significa uma folha que não aceita nenhum, [..] significa que apenas os tipos listados podem ser filhos.

Para exemplos completos combinando os componentes, veja references/examples.md.

Envio

Passe o envelope montado como um arquivo ou via stdin; em caso de sucesso, a URL da visualização é impressa no stdout (syokan snapshot.json / cat snapshot.json | syokan / claude -p '…JSON…' | syokan).

Para todo o resto — comandos, subcomandos, variáveis de ambiente, códigos de saída — consulte syokan --help --json; para tipos e props, syokan catalog.

Visualizando arquivos locais

Para um arquivo local, syokan <caminho> é o caminho mais curto — você invoca o próprio arquivo. O envelope JSON é enviado como está; qualquer outra coisa (markdown / log / txt / json, ...) é automaticamente encapsulada em um FileDoc ao vivo. A CLI o resolve para um caminho absoluto e o entrega ao servidor, que lê o conteúdo e infere o formato a partir da extensão (.md/.markdown → markdown, .json → código, todo o resto → texto). Enquanto a visualização estiver aberta, ela segue as edições no arquivo (sem necessidade de reenvio).

syokan notas.md   # renderiza markdown; a visualização é atualizada a cada salvamento
syokan app.log    # mostra um log crescente em monoespaçada

Para combinar vários arquivos em uma única visualização, ou misturá-los com Heading e outros nós, coloque nós FileDoc você mesmo (props: path, apenas caminhos absolutos; FileDoc lida com leitura e rastreamento de alterações).

Por outro lado, para mostrar o conteúdo de um arquivo congelado estaticamente (sem necessidade de acompanhamento, ou você está transformando o conteúdo), coloque o corpo em um nó MarkdownDoc / PlainText / Code. O jq --rawfile o insere sem se preocupar com escaping JSON.

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

Templates para reprodutibilidade

Não reconstrua uma visualização favorita do zero toda vez — salve-a como um template no syokan e reutilize-a. Um template é "o próprio envelope salvo". Você pode colocar marcadores como {{...}} no esqueleto e preenchê-los você mesmo.

Se um template correspondente existir, não construa do zero: encontre o id na lista → busque-o → substitua os dados → envie. Quando você produzir uma nova visualização que vale a pena manter, salve-a e reproduza-a na próxima vez. Para a sintaxe dos subcomandos (templates list|add|get|rm), consulte syokan --help --json.

Habilidades Relacionadas