Communitygithub.com

wwwyo/syokan

syokan — los LLMs invocan interfaces de usuario enriquecidas. Pronuncia una invocación JSON y aparece una interfaz viva. Efímera por diseño.

¿Qué es syokan?

syokan (召喚, 'invocar') es un verbo: los LLMs invocan interfaces de usuario enriquecidas. En lugar de escribir JSX, el agente compone un árbol de componentes predefinidos en JSON y lo envía (POST) a syokan, que lo renderiza al instante. La interfaz es efímera: no hay garantía de persistencia, por lo que solo se deben colocar datos reconstruibles y transitorios. syokan acepta únicamente JSON con un esquema estricto: las props adicionales son rechazadas y los nodos hoja no pueden tener hijos. Se integra con Claude Code, Cursor y otras herramientas de IA mediante línea de comandos. También permite previsualizar archivos locales (Markdown, logs, texto plano, JSON) que se actualizan en vivo al editarse. Para vistas recurrentes, soporta idempotencia mediante claves y plantillas reutilizables. El agente debe consultar 'syokan catalog' para conocer los tipos y props disponibles, y 'syokan --help --json' para comandos y opciones adicionales.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace syokan?

syokan (召喚, "invocar") es un verbo — los LLMs invocan interfaces de usuario enriquecidas. Cuando el usuario dice "syokan X" (JA: 「Xを syokan»), es una solicitud para invocar esos datos en una vista. Internamente es una capa de vista basada en esquemas: en lugar de escribir JSX, pronuncias una invocación JSON — un árbol de componentes del catálogo — y syokan lo renderiza con componentes predefinidos. Tu trabajo es ensamblar los datos en un sobre y hacer POST a syokan. En prosa, usa syokan como verbo transitivo directo (nunca "hacer syokan" / nunca 「syokan する」 — syokan se sostiene por sí solo).

Si syokan aún no está instalado (syokan --help falla), o el usuario dice "onboarding", "configurarlo" o "primera vez que lo uso", guíalo a través de references/onboarding.md hasta su primera instantánea. No ejecutes operaciones que modifiquen el entorno de forma silenciosa, como instalaciones: informa que no está instalado y obtén la aprobación del usuario antes de ejecutar (nunca instales por tu cuenta).

No negociables

  • Las instantáneas son efímeras: una instantánea publicada no tiene garantía de persistencia. Solo coloca allí datos reconstruibles y transitorios (RSS de hoy, una revisión en curso, etc.). Para diseños que reutilices, guarda una plantilla para reproducirlos (las plantillas persisten — ver "Plantillas para reproducibilidad" más abajo).
  • Solo JSON: el servidor no acepta nada más que un sobre JSON. Markdown sin formato o texto plano son rechazados. Para mostrar prosa, envuélvela en un nodo MarkdownDoc o PlainText.
  • Esquema estricto: las props se validan estrictamente. Las claves que no están en el esquema son rechazadas — no inventes claves adicionales.
  • Las hojas no pueden tener hijos: solo Stack y Card aceptan hijos. Adjuntar hijos a un nodo hoja es rechazado al ingerir.

Desde la composición hasta la visualización

  1. Verifica los tipos y props disponibles con syokan catalog (ver "Catálogo" más abajo).
  2. Mapea los datos que quieres mostrar a esos componentes. El nivel superior suele ser un contenedor (Stack, etc.) apilando elementos verticalmente.
  3. Conviértelo en un sobre JSON (ver "Forma del sobre" más abajo). Solo root es obligatorio.
  4. Publícalo con la CLI (ver "Publicación" más abajo). Si tiene éxito, se imprime la URL de la vista.

Si ya has construido una vista similar antes, no empieces desde cero — baséate en una plantilla guardada (ver "Plantillas para reproducibilidad" más abajo).

Forma del sobre

Solo lo siguiente puede ir en el cuerpo del POST. Nunca incluyas id, createdAt o url — el servidor los asigna.

{
  "root": { "type": "Stack", "props": {}, "children": [ /* nodos del catálogo; ejemplos completos en references/examples.md */ ] }, // obligatorio. el árbol de la vista
  "title": "RSS de hoy",                                // opcional. se muestra en la lista y en el encabezado de la vista
  "metadata": { "source": { "label": "daily-rss" } },   // opcional. etiqueta de procedencia
  "schemaVersion": 1,                                    // opcional. el servidor lo completa
  "idempotencyKey": "rss-2026-06-28"                     // opcional. nombra esta vista para que pueda actualizarse más tarde en lugar de duplicarse
}

metadata.source admite claves adicionales además de label; puedes agregar url o fetchedAt (ej.: { "label": "gh-review", "url": "https://example.com/..." }).

Para vistas diarias o recurrentes, incluye algo como la fecha en el idempotencyKey. La CLI de syokan maneja el resto: primero apunta a esa clave, y solo crea una nueva vista si ninguna existe aún — así la primera publicación crea la vista y cada publicación posterior con la misma clave actualiza esa misma vista en su lugar en lugar de duplicarla. No necesitas rastrear si es la primera publicación tú mismo. (Si llamas a la API HTTP directamente en lugar de a la CLI: POST /api/snapshots siempre crea y etiqueta la clave; PUT /api/snapshots apunta a una clave existente y devuelve 404 si aún no está — no hay un endpoint que cree si no existe, por eso la CLI primero intenta PUT y recurre a POST si recibe un 404.)

Catálogo

Obtén los types disponibles y sus definiciones de props desde syokan catalog (nunca los transcribas a md — obténlos de aquí cada vez).

La salida es { "items": [{ "type", "props", "childrenTypes" }] }.

  • props: las props del tipo como JSON Schema. Cumple con required / enum / format (httpUrl es uri, Time.datetime es date-time) / additionalProperties:false (las claves desconocidas son rechazadas) exactamente como se indica.
  • childrenTypes: null significa que es un contenedor que acepta hijos, [] significa que es una hoja que no acepta ninguno, [..] significa que solo los tipos listados pueden ser hijos.

Para ejemplos completos que combinan los componentes, consulta references/examples.md.

Publicación

Pasa el sobre ensamblado como archivo o mediante stdin; si tiene éxito, la URL de la vista se imprime en stdout (syokan snapshot.json / cat snapshot.json | syokan / claude -p '…JSON…' | syokan).

Para todo lo demás — comandos, subcomandos, variables de entorno, códigos de salida — consulta syokan --help --json; para tipos y props, syokan catalog.

Vista previa de archivos locales

Para un archivo local, syokan <ruta> es la ruta más corta — invocas el archivo mismo. El JSON del sobre se publica tal cual; cualquier otra cosa (markdown / log / txt / json, ...) se envuelve automáticamente en un FileDoc en vivo. La CLI lo resuelve a una ruta absoluta y se la entrega al servidor, que lee el contenido e infiere el formato a partir de la extensión (.md/.markdown → markdown, .json → código, todo lo demás → texto). Mientras la vista está abierta, sigue los cambios del archivo (sin necesidad de volver a publicar).

syokan notas.md   # renderiza markdown; la vista se actualiza en cada guardado
syokan app.log    # muestra un log creciente en monoespaciado

Para combinar varios archivos en una sola vista, o mezclarlos con Heading y otros nodos, coloca tú mismo los nodos FileDoc (props: path, solo rutas absolutas; FileDoc maneja la lectura y el seguimiento de cambios).

Por el contrario, para mostrar el contenido de un archivo congelado estáticamente (sin necesidad de seguimiento, o si estás transformando el contenido), coloca el cuerpo en un nodo MarkdownDoc / PlainText / Code. jq --rawfile lo introduce sin preocuparse por el escape JSON.

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

Plantillas para reproducibilidad

No reconstruyas una vista favorita desde cero cada vez — guárdala como plantilla en syokan y reutilízala. Una plantilla es "el sobre guardado en sí mismo". Puedes colocar marcadores como {{...}} en el esqueleto y completarlos tú mismo.

Si existe una plantilla que coincida, no construyas desde cero: encuentra el id en la lista → obténla → intercambia los datos → publica. Cuando produzcas una nueva vista que valga la pena conservar, guárdala y reprodúcela la próxima vez. Para la sintaxis de subcomandos (templates list|add|get|rm), consulta syokan --help --json.

Skills relacionados