Crear un plugin con IA¶
Un asistente de programación con IA (Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot, Aider…) puede escribirte un plugin de Kino si primero lee las reglas, aunque tú no sepas programar: tú dices qué fuente quieres y pruebas el resultado en Kino; el asistente escribe el código, lo prueba con el kit y te dice qué hacer en cada paso. Este sitio publica las reglas en los formatos que mejor leen esas herramientas:
| Archivo | Qué es |
|---|---|
AGENTS.md |
Las instrucciones para el asistente: su rol, qué leer, el flujo de trabajo paso a paso, las reglas duras con sus números exactos, una lista de chequeo y los errores de siempre. También está en el repositorio. |
llms-full.txt |
Toda esta guía en un solo archivo de texto (en inglés), más AGENTS.md, contract.json y kino.d.ts. Se genera con el sitio, así que siempre es la misma versión de estas páginas. |
llms.txt |
El índice corto, en el formato llms.txt. |
¿Quieres usar un scraper de Nuvio?
Para agregar scrapers a Kino no necesitas este prompt: Kino instala directamente los scrapers de un repositorio de Nuvio, convirtiéndolos en el dispositivo. Mira Scrapers de Nuvio.
¿Quieres un plugin que busque sus enlaces en los scrapers de Nuvio?
Eso sí es un plugin tuyo, y el asistente lo escribe bien si lee la página Plugins que usan scrapers de Nuvio
(kino.nuvio, Kino 0.9.71). Usa el prompt corto de Nuvio o, en el prompt de abajo, rellena la línea «Scrapers de Nuvio».
¿Quieres usar un addon de Stremio?
Tampoco necesitas este prompt. En Ajustes ▸ Plugins, «Agregar plugin», elige Stremio y pega la dirección del
manifest.json del addon: Kino lo lee y genera, en el dispositivo, un plugin que habla con el servidor del addon.
Mira Addons de Stremio.
¿Quieres usar un plugin de CloudStream?
No necesitas este prompt (Kino 0.9.54). En «Agregar plugin», pega la dirección de un repositorio de CloudStream, o su código corto, y Kino convierte los plugins que la persona elija. Algo importante: necesita una app auxiliar. El código de CloudStream nunca corre dentro de Kino; corre en una pequeña app aparte, el complemento de CloudStream (un APK adicional). La primera vez, Kino ofrece instalarlo («Instalar complemento»): lo descarga de los mismos servidores que sus propias actualizaciones, comprueba que es la copia de Kino (paquete, versión, sha256 y firma) y Android pide permiso para instalarlo. El complemento no tiene permiso de internet: toda petición pasa por Kino. Mientras no esté instalado, esos plugins dicen «Necesitas el complemento de CloudStream» con un botón para instalarlo. Mira Plugins de CloudStream y el complemento.
¿Quieres un plugin que use los datos de otro plugin, o que ofrezca los suyos a otros plugins?
Desde Kino 0.9.81 los plugins pueden usarse entre sí a través de Kino: uno abre puertas y otro les pregunta (una trivia de cine que saca sus películas del plugin TMDB, por ejemplo). Un asistente lo hace bien si lee Protocolo entre plugins. Usa el prompt corto del protocolo.
Antes de empezar¶
Necesitas cinco cosas. Todas son gratis salvo, a veces, el asistente.
- Una cuenta de GitHub (github.com/signup). Tu plugin vive en un repositorio público de GitHub; de ahí lo instala Kino.
- Node.js 18 o más nuevo (nodejs.org, la versión "LTS"). Es lo que corre
el kit de pruebas. Para comprobarlo, en una terminal:
node --versiontiene que responderv18o un número mayor. - Git (git-scm.com), para bajar y subir el repositorio. Opcional
pero útil: GitHub CLI (
gh), con el que el asistente puede crear el repositorio y ponerle el topic por ti (la primera vez,gh auth login). -
Un asistente que pueda usar la terminal, es decir, que ejecute comandos y lea lo que responden:
- en la terminal: Claude Code, Codex CLI, Gemini CLI, Aider;
- en un editor: Cursor, o VS Code con GitHub Copilot en modo agente.
Cómo abrir una terminal: en Windows, menú Inicio → escribe "Terminal" (o "PowerShell"); en Mac, Cmd + Espacio → escribe "Terminal"; en Linux, Ctrl + Alt + T. Crea una carpeta vacía, entra en ella y abre ahí el asistente.
Un chat en el navegador, sin terminal, también sirve, pero ahí te toca a ti copiar cada comando, ejecutarlo y pegarle al chat lo que responda. 5. Kino en un celular o un televisor, para probar el plugin de verdad antes de compartirlo.
Y una cosa más: el derecho a usar la fuente. Un plugin solo puede llegar a lo que la persona igual podría ver; no le pidas a un asistente que se salte un muro de pago, un login ajeno o un DRM.
El prompt¶
Cópialo (el botón de copiar está arriba a la derecha del bloque), cambia lo que está entre <<< y
>>> y pégalo en tu asistente. Si no sabes qué poner en una línea, déjala como está: el asistente te
lo va a preguntar.
Vas a escribir un plugin de Kino: un repositorio público de GitHub con kino-plugin.json y un
módulo ES de JavaScript (plugin.js) que la app Kino (video, TV en vivo, música y podcasts) ejecuta
en un sandbox de QuickJS.
Puede que yo no sepa programar. Explícame cada paso en español sencillo, ejecuta tú los comandos
(antes dime cuál y para qué), pregúntame antes de cualquier cosa que no se pueda deshacer (borrar,
publicar, subir a GitHub) y, cuando algo lo tenga que hacer yo en GitHub o en Kino, dame los clics
exactos.
La interfaz del plugin (esta regla va primero): para cualquier plugin que necesite su propia pantalla,
configuración, bienvenida, tablero o panel, constrúyela con las pantallas de Kino: apiVersion 14, la capacidad
"screen" con los exports screen() y screenEvent(), componentes al estilo Flutter (Scaffold, AppBar, TabBar,
ListTile, Card, Form, TextField, el nodo "settings"...), valores por tamaño, el celular y el TV dibujados desde el
mismo árbol. Deja el formulario de ajustes viejo y el formato de panel anterior solo por compatibilidad. apiVersion
14 llega con Kino 0.9.74: para seguir instalándose en un Kino anterior,
conserva tu apiVersion y ofrece la pantalla con "enhancements". Pon el código en src/ y empaquétalo en plugin.js
con esbuild (generado, guardado en git, revisado con check:built). Valida con node sdk/validate.mjs . y
node sdk/run.mjs . screen (también con --device tv). Sigue el catálogo de componentes (https://kinotvapp.github.io/kino-plugins/en/screen-components/,
https://kinotvapp.github.io/kino-plugins/en/screen-forms/, https://kinotvapp.github.io/kino-plugins/en/screen-reference/) y las reglas de foco del TV (https://kinotvapp.github.io/kino-plugins/en/screens/#tv-focus): Kino dibuja su anillo
de foco solo en los nodos que la persona puede presionar; un nodo donde el control remoto debe detenerse solo para
leerlo lleva "canRequestFocus": true.
Cada pantalla del plugin usa una sola barra compacta: su AppBar lleva mergeWithKinoBar: true y dense: true, con un
leading que es una salida real ({ close: true } en la portada, un regreso en las demás). La ruta sin nombre es "main",
la portada. Un elemento de una fila del Home que abre una pantalla usa open: { screen: { args } } y el detalle se apila
desde la respuesta de open, así Atrás vuelve a la portada. Un lector usa Image fit: "width", un desplazamiento con zoom
y onScroll, y pages con reverse y progress. Si las imágenes del sitio solo responden a su propia página, cada Image lleva
headers { Referer, User-Agent }, que se envían solo a hosts que están en los hosts del manifiesto y solo con una imagen https.
Desde Kino 0.9.88 las imágenes de una pantalla también pueden ser http en un host público (logos de canales de IPTV): manda
una imagen http solo cuando kino.screen.httpImages === true; si no, una https o ninguna (se ven las iniciales). En la TV el
botón de un plugin mide 40 dp de alto con 14 dp a cada lado (Kino 0.9.88): ponle padding, height o minHeight solo cuando
deba ser más grande. La NavigationBar de un Scaffold conserva el desplazamiento de cada destino cuando su nodo que se
desplaza lleva su propia key. { ui: [{ fullscreen: true }] } (Kino 0.9.84) esconde la barra de Kino para un lienzo inmersivo:
dibuja tu propia salida. Para recordar dónde se
quedó la persona, usa kino.progress (apiVersion 22, Kino 0.9.83): el lugar exacto va en resume (opaco para
Kino, máximo 1024 bytes), get(id) responde null cuando no hay nada, y Kino no dibuja ninguna fila: el plugin arma su propia
fila "Seguir leyendo" con list() (https://kinotvapp.github.io/kino-plugins/progress/). Para algo pequeño que se queda
en el reproductor de la TV (un reloj, un marcador, un botón que abre mi panel), usa el hueco del reproductor (apiVersion 23,
Kino 0.9.83): la capacidad "playerSlot", un bloque "slot" de 1 a 3 elementos (text, icon, image, button;
"overlay" con los controles o "fixed", que me pregunta en rojo) y los dos exports playerSlot(context) y
playerSlotAction({ id, context }); el context puede venir sin kind, y refreshMs va de 2000 a 60000. Un text acepta size, weight,
color y background, y cualquier elemento left y top; los ofreces como ajustes normales y Kino ignora lo inválido y mantiene el
texto legible (https://kinotvapp.github.io/kino-plugins/player-slot/#dress).
Si el inicio de sesión guarda su token en el localStorage de la página (no en una cookie), abre la ventana con
kino.visualBrowser.open y collect.localStorage: ["access_token"] más doneWhen.localStorage (Kino 0.9.87, sin
apiVersion nuevo): el localStorage de la respuesta trae solo las claves nombradas, con "done"; un Kino anterior no responde ninguna,
así que compruébalo, guarda los valores en kino.storage y nunca los registres (storeAs cubre solo cookies;
https://kinotvapp.github.io/kino-plugins/visual-browser/#rules).
Para un aspecto de toda la app (temas), el appThemes del manifiesto (apiVersion 18) lleva colores, formas y tipografía; desde
apiVersion 26 (Kino 0.9.87) un tema también puede pintar: surfaces (relleno, contorno y resplandor por
elemento), style.gloss, layout (un héroe enmarcado y un riel flotante, solo TV), assets con background.image y
typography.fontFamily. Nunca pongas esas claves en un tema que declara un apiVersion menor, dale a cada asset su sha256 y sus bytes
exactos (una imagen de 2 MB como máximo), haz que el tema se vea bien con cada efecto apagado y mantén el texto legible en cada
parada de un degradado (https://kinotvapp.github.io/kino-plugins/themes/#level2). Prefiere un Skeleton a un spinner y una hoja inferior con un campo de
búsqueda a muchos chips; una pantalla tiene un presupuesto de 600 nodos.
(https://kinotvapp.github.io/kino-plugins/en/screen-components/#one-compact-bar)
Antes de escribir nada:
1. Lee completo https://kinotvapp.github.io/kino-plugins/AGENTS.md y síguelo como tus instrucciones.
2. Lee https://kinotvapp.github.io/kino-plugins/llms-full.txt (la guía completa, contract.json y
kino.d.ts). Si no puedes abrir URL, dímelo y te los pego.
3. Parte de una plantilla, con "Use this template" (nunca Fork): kinotvapp/kino-plugin-archive si mi
plugin es simple, kinotvapp/kino-plugin-own-server si necesita ajustes, sesión, descargas o canales
en vivo (su plugin.js y su kino-plugin.json, "Tu servidor" 1.5.0, son la referencia completa de la
API, hasta apiVersion 7). La carpeta sdk/ de la plantilla es el kit de pruebas de Node. Si mi
plugin es de música o podcasts, lee también la sección "Música y podcasts" del contrato
(apiVersion 8, Kino 0.9.54: https://kinotvapp.github.io/kino-plugins/contract/#music-podcasts) y usa
kinotvapp/kino-plugin-archive-audio como el plugin de audio de referencia.
4. Si mi plugin no puede convertir lo que encuentra en una URL reproducible por sí mismo y lo entrega a otra app
instalada en el celular o la TV (una "app resolutora"), lee https://kinotvapp.github.io/kino-plugins/resolver/ y
"Dejar que otra app resuelva lo que encontraste" en el contrato (apiVersion 11, Kino 0.9.66). En ese caso el
plugin solo declara "externalResolve" y responde { external: { protocol, ref } } desde resolve(); nunca toca el
contenido por sí mismo.
5. Si dije un repositorio de Nuvio, lee https://kinotvapp.github.io/kino-plugins/nuvio-plugins/ (kino.nuvio,
apiVersion 11, Kino 0.9.71) y copia la forma de su ejemplo completo.
6. Si mi plugin es un proveedor de sincronización (lleva la sincronización propia de Kino entre mis aparatos
por un servicio: un bot, una API de almacenamiento, un servidor mío), lee primero
https://kinotvapp.github.io/kino-plugins/sync-providers/ (apiVersion 12, Kino 0.9.74). Sus referencias son
tres repositorios públicos: Sync-Gram (https://github.com/kinotvapp/kino-plugin-sync-gram, un bot de Telegram
de la propia persona) para un servicio de terceros, Sync Servidor
(https://github.com/kinotvapp/kino-plugin-sync-server, un servidor de Node de un solo archivo) para un
servidor mío, y Sync-Gram Cuenta (https://github.com/kinotvapp/kino-plugin-sync-gram-account, la propia
cuenta de Telegram de la persona por un WebSocket, apiVersion 13: sync.generateKey, una contraseña 2FA de un
solo uso en provision, hide en settingsStatus) para una cuenta mía.
7. Si mi plugin es una tienda (una fuente de plugins para la tienda de Kino), o usa identidad, la bóveda o avisos, lee primero
https://kinotvapp.github.io/kino-plugins/plugin-stores/, /store-examples/, /identity/, /vault/ y /notifications/
(identity, notifications y pluginStore: apiVersion 15, Kino 0.9.77). La bóveda (vault) es apiVersion 28, Kino 0.9.90 y
requiere identity: una sola llamada, const secret = await kino.vault.get(), y Kino lee el secreto propio del plugin
(una API base, llaves) que registraste en la bóveda — el plugin nunca ve la URL de la bóveda y solo puede leer SU propio
secreto. Ejemplo de la vida real: https://github.com/kinotvapp/kino-plugin-vault-demo. Para una tienda, parte de un ejemplo
con node sdk/init.mjs mi-tienda --host <host> --store local|live.
8. Si mi plugin usa los datos de otro plugin, o abre una puerta para otros plugins, lee primero
https://kinotvapp.github.io/kino-plugins/protocol/ (el protocolo entre plugins: apiVersion 20, Kino 0.9.81)
y copia los patrones de Cine Trivia (https://github.com/kinotvapp/kino-plugin-cine-trivia,
un consumidor con la puerta de instalación) y TMDB (https://github.com/kinotvapp/kino-plugin-tmdb, un proveedor).
Parte de la plantilla del kit: node sdk/init.mjs mi-plugin --kind provider, o --kind consumer --repo dueño/nombre
--door <la puerta real> --call <una llamada real> (escribe "hosts": []); su test/provider
es un reemplazo que hay que cambiar por una copia del proveedor real. Resumen en una página:
https://kinotvapp.github.io/kino-plugins/protocol-quick/.
9. Para el botón Compartir (va en todo plugin, mira las reglas), lee https://kinotvapp.github.io/kino-plugins/share/ y
copia la forma de Megaplay (su repositorio kino-plugin-megaplay, src/browse/share.js y
test/share.test.mjs).
Lo que quiero:
- Fuente: <<< el sitio o la API, p. ej. https://example.com >>>
- Contenido: <<< películas / series / anime / TV en vivo / música / podcasts o audiolibros / un catálogo que no reproduce nada (listas o calificaciones); idioma y país >>>
- Acceso: <<< ninguno / mi usuario y contraseña del sitio / una clave de API mía (del desarrollador) que no quiero publicar / la dirección de un servidor que escribe cada persona >>>
- Qué le pregunta Kino a la persona al configurarlo: <<< nada / su usuario y contraseña / su región / la dirección de su servidor >>>
- Descargas para ver sin conexión: <<< sí / no >>>
- Otra app resuelve el stream reproducible (una app resolutora aparte en el aparato): <<< no / sí: el nombre del paquete de la app, el protocolo que responde, qué "ref" espera y cómo la consigue la gente: un APK de un release de GitHub (con su sha256), F-Droid, un código de Downloader para la TV >>>
- Scrapers de Nuvio: <<< ninguno / el repositorio de Nuvio (owner/repo) de donde el plugin saca los enlaces >>>
- Proveedor de sincronización (el plugin lleva la sincronización de Kino entre mis aparatos en vez de la red local): <<< no / sí: el servicio, si le da a cada persona un token largo y aleatorio, y si el servicio puede leer los datos sincronizados >>>
- Nombre en Kino y una descripción corta: <<< p. ej. "Mi fuente": "Películas de …, en español" >>>
- Su propia pantalla (un tablero, una configuración paso a paso, una pestaña del panel...): <<< no / sí: qué muestra y qué hace ahí la persona >>>
- Una tienda (una fuente de plugins para la tienda de Kino, apiVersion 15): <<< no / sí: local (una lista que entrega en segundo plano, desde GitHub, mi servidor o un archivo JSON estático) o en vivo (también responde mientras la persona navega: storeList y storeSearch, así que lo que busque llega a mi servidor), los hosts que usa y los plugins que lista >>>
- Identidad o avisos (apiVersion 15): <<< no / sí: quién necesita el seudónimo de Telegram de la persona (solo las llaves de autor en las que Kino confía reciben el token firmado; desde Kino 0.9.88 cualquier otro plugin recibe el seudónimo y, con un desafío, la atestación, y un Kino anterior lo rechaza) y qué avisos dejar en la campanita de Inicio >>>
- Otros plugins (el protocolo entre plugins, apiVersion 20, Kino 0.9.81): <<< no / usa la puerta de otro plugin: su repositorio y su puerta (p. ej. kinotvapp/kino-plugin-tmdb, "movies") / abre una puerta: qué podrían pedirle otros plugins >>>
- Archivos del aparato de la persona (apiVersion 21, Kino 0.9.82): <<< no / sí: de qué tipo (libros, música, videos, imágenes, subtítulos), un archivo o una carpeta entera, y si solo los lee o los reproduce >>>
- Recordar dónde se quedó la persona (apiVersion 22, Kino 0.9.83): <<< no / sí: qué recorre la persona página a página o capítulo a capítulo (un manga, un libro, un podcast que reproduce el plugin), la unidad que hay que recordar (capítulo y página, una posición en el libro) y qué guardar en resume para volver al lugar exacto (p. ej. { cap: 87, pag: 12 }), y si mi plugin muestra su propia fila "Seguir leyendo" (Kino no dibuja ninguna) >>>
- Imágenes de un sitio que solo responde a su propia página (los headers de una Image, Kino 0.9.83): <<< no / sí: el sitio, el Referer que pide (p. ej. https://mangasite.example/) y si necesita un User-Agent de navegador; sus hosts de imágenes van en hosts >>>
- Algo siempre a la vista en el reproductor de la TV (el hueco del reproductor, apiVersion 23, Kino 0.9.83): <<< no / sí: qué muestra (un reloj, un marcador, un logo, un botón que abre mi panel), si se queda todo el tiempo (fixed: Kino me pregunta en rojo) o solo con los controles (overlay), y cada cuánto cambia >>>
- Inicio de sesión que guarda su token en el localStorage de la página (kino.visualBrowser, Kino 0.9.87): <<< no / sí: el sitio, las claves de localStorage que guardan el token (p. ej. access_token) y dónde guardarlas (kino.storage) >>>
- Un aspecto para toda la app (temas; superficies pintadas desde apiVersion 26, Kino 0.9.87): <<< no / sí: el ambiente (colores, oscuro o claro), si necesita superficies (botones degradados o brillantes, resplandores), una imagen de fondo (mi propio archivo, de 2 MB como máximo, en el repositorio del plugin), su propia fuente (TTF u OTF), un héroe enmarcado y un riel flotante (solo TV) >>>
- Lo que cuesta cada reproducción en la fuente (decide entre resolveAhead y prepare, Kino 0.9.88): <<< nada / cuenta una reproducción / gasta un cupo (cuántas llamadas por hora y por cuenta) / gasta una prueba o una reproducción gratis / abre una página oculta >>>
- Canales en vivo de un CDN cuyas direcciones de segmento terminan en un número de reloj que crece (en vivo por reloj, apiVersion 27, Kino 0.9.88): <<< no / sí: una dirección de segmento real, las duraciones de las líneas #EXTINF de la lista y cómo conseguir un instante con el segmento que empezó entonces >>>
- Compartir en Kino Social (recomendado en todo plugin): <<< sí, desde la página de cada título y desde la barra / solo desde la barra (solo texto) / no >>>
- Firmar el plugin con mi propia clave, para que la gente sepa que cada actualización es mía: <<< sí / no >>>
- Mi usuario de GitHub: <<< p. ej. mi-usuario >>>
Reglas que no puedes romper (el detalle y los números exactos están en AGENTS.md):
- Declara en "hosts" cada host que conozcas: los de la API y los del video, subtítulos, audio,
segmentos y redirecciones (*.x no cubre x). Si falta uno, al abrir o reproducir un título Kino le
pregunta a la persona una sola vez; no cuentes con eso. Si el video sale de CDN que cambian, usa
"streamHosts": "any" (apiVersion 4; la persona lo aprueba al instalar); para canales en vivo,
"liveStreamHosts": "any" (apiVersion 3, necesita la capacidad "channels"). Si el sitio o sus
extractores cambian de dominio y no puedes listarlos, usa "fetchHosts": "any" (apiVersion 9, Kino
0.9.55; la persona lo aprueba en rojo; solo por https en el puerto 443, con un cupo de peticiones, nunca la red de la casa) y revisa kino.fetchAnyHost.
Desde Kino 0.9.45 no hay un máximo de hosts; Kino 0.9.44 y anteriores rechazan más de 20, así que si
declaras más de 20, avísame.
- En kino-plugin.json escribe "entry": "plugin.js" e "icon": "icon.png", NUNCA "./plugin.js": Kino
0.9.45 y anteriores rechazan un "./" al principio y el plugin no se instala.
- No es Node ni un navegador: no hay fetch, setTimeout, Buffer, process, require, crypto ni Intl;
usa kino.fetch, kino.sleep, kino.crypto, kino.storage. Sí hay URL, URLSearchParams, atob, btoa,
TextEncoder, TextDecoder y console. Un solo archivo, sin import.
- Nunca lances un error antes del primer await de una función async (primero await, luego valida):
Kino 0.9.50 lo ataja, pero 0.9.49 y anteriores abortan toda la llamada, y la gente actualiza tarde.
- Usa kino.fetch siempre que encuentre el video. Solo si el embed de un servidor arma la dirección
ejecutando sus propios scripts, usa el navegador oculto ("browser": true, apiVersion 6; me lo pregunta
en rojo) y llama kino.browser.capture solo dentro de resolve. Nunca intentes resolver ni saltarte un
captcha o una revisión de "confirma que eres humano": con blocked, pasa al siguiente servidor. Si un
título tiene varios servidores o idiomas, resuelve uno y lista los demás como alternatives
{ label, ref }.
- Límites: search 15 s, prepare 15 s y las demás llamadas 20 s; 60 peticiones por llamada (cada salto de
redirección cuenta, también los rechazados) y máximo 6 al mismo tiempo; cuerpos de 5 MB;
256 KB de kino.storage; 100 resultados de búsqueda; Inicio con 20 filas de 60.
- Errores para la persona: kino.error("auth_required" | "not_found" | "geo_blocked" |
"rate_limited" | "unavailable"). Con apiVersion 6 puedes agregar una frase propia,
kino.error(code, detalle, { userMessage: "…" }): en español (o en el idioma de kino.lang, mira la
regla del idioma), máximo 160 caracteres, sin URL ni
dominios, sin números largos, nunca pidiendo plata, contraseñas, códigos ni contacto por fuera de
Kino, y nunca repitiendo lo que escribió la persona (Kino la muestra como "Mensaje de <plugin>: …"
solo si pasa todas sus reglas; un plugin que la usa para pedir plata o datos incumple las reglas y sale del índice de la comunidad).
- Home por categorías: agrupa el contenido de preferencia en las categorías de Kino
(https://kinotvapp.github.io/kino-plugins/categories/): declara "genre" en cada fila de home() y "genres"
en cada ítem con ids de esa lista (peliculas, series, anime, accion, comedia, drama…), manda también "year"
e ids.tmdb, e inventa una categoría nueva solo cuando ninguna encaje.
- Contenido +18: márcalo con adult: true (apiVersion 6; Kino lo muestra solo con el código +18
desbloqueado). Nunca intentes saltarte ese candado.
- Todo lo que lee la persona, en español de Bogotá con tuteo, nunca voseo, y los textos que arma el
código (títulos de filas, userMessage) en el idioma de kino.lang: desde Kino 0.9.54 kino.lang puede
ser "en-US", y entonces van en inglés (antes de 0.9.54 siempre es "es-CO").
- Música y podcasts (apiVersion 8, Kino 0.9.54): el kind "music" es un álbum, una lista o una pista;
el kind "podcast" es un programa (también de radio) o un audiolibro; "artist" es opcional (el
artista, o quien conduce o escribe). Si el plugin declara "episodes", episodes() tiene que responder
por cada ref de music y podcast, aunque sea una sola pista; sin "episodes", el ref del ítem va a
resolve. Por debajo de apiVersion 8 esos ítems se descartan.
- Playlists de la persona en el plugin (apiVersion 10, Kino 0.9.65): si el servicio tiene las listas
PROPIAS de la persona (su cuenta, no tu catálogo), puedes declarar la capacidad "playlists"; sus
seis funciones son cada una opcional, incluida playlists() misma. Es un contrato todavía sin
conectar a ninguna pantalla de Kino, así que no la presentes como algo que ya se ve en la app.
Léela en https://kinotvapp.github.io/kino-plugins/contract/#playlists antes de usarla; la mayoría
de los plugins no la necesita.
- Otra app que resuelve lo que encontraste (apiVersion 11, Kino 0.9.66): cuando una fuente no se puede
convertir en una URL desde el propio plugin y una app resolutora aparte, instalada por separado, lo hace,
declara la capacidad "externalResolve" (y, para nombrar la app, el "externalResolver" del manifiesto) y
responde { external: { protocol, ref } } desde resolve() en vez de una url. Kino nunca interpreta el
protocolo ni el ref; le pide permiso a la persona, muestra el progreso de la app y reproduce lo que devuelve.
Úsalo solo cuando el plugin de verdad no pueda producir una url, dale una alternativa cuando se pueda y no
prometas que existe una app resolutora. Lee https://kinotvapp.github.io/kino-plugins/resolver/ antes de usarlo.
- Proveedores de sincronización (apiVersion 12, Kino 0.9.74), solo si te pedí uno: declara la capacidad
"syncProvider" (puede ser la única) y exporta syncPull({ maxBlobBytes }) -> { blob, version } o null,
syncPush({ maxBlobBytes, blob, expectedVersion }) -> { version } y, si quieres, syncStatus(null) ->
{ ready, message? }. El blob es texto cifrado en base64 que hace Kino: guárdalo y devuélvelo byte por
byte, nunca lo decodifiques. Lanza kino.error("conflict", …) cuando la copia remota cambió desde
expectedVersion, y kino.error("auth_required", …) cuando faltan ajustes o el servicio los rechaza.
El manifiesto TIENE que llevar un bloque "sync" con "keySecret" (un proveedor sin él se rechaza):
"keySecret" = la clave de un ajuste "password" con un token largo y aleatorio (nunca una contraseña que
escoge una persona, sin "default"); Kino deriva de él la llave de sincronización en cada aparato, así
que un segundo aparato solo necesita los mismos ajustes y ninguna llave viaja, PERO el plugin y su
servicio pueden leer los datos y la única línea de consentimiento lo dice en rojo: dímelo. "provision"
(obligatorio) = los ajustes que necesita un segundo aparato, incluido "keySecret". "maxBlobBytes" como
mucho 4194304 (4 MiB; solo dentro de syncPull y syncPush puede kino.fetch mover tanto). Si el token
cambia, todos los demás aparatos necesitan el nuevo. Nunca pongas el token en un error, una línea de
estado o un registro.
- Ayudas para configurar (apiVersion 12): un ajuste "help" corto (qué necesita la persona y dónde lo
consigue) y un ajuste "link" (un botón https, p. ej. https://t.me/BotFather). Desde Kino 0.9.74 una
acción puede responder link: { candidate, confirm } (Kino pregunta "¿Eres tú, <candidate>?" antes de
correr la acción confirm) y setSettings: { clave: valor } para llenar ajustes "text" o "select" del
propio plugin (nunca un "url"; un "password" solo desde apiVersion 13). La acción confirm lleva "linkOnly": true, así la
persona ve un solo botón. La preparación que un TV no puede hacer (un token que se pega en el celular)
lleva "devices": ["phone"]: el TV la recibe con "Recibir configuración", enviada desde el celular con "Enviar configuración".
- Detecta lo que a un Kino viejo le falta: kino.meta y kino.tmdb (Kino 0.9.53) solo detrás de
`typeof kino.meta === "function"` / `typeof kino.tmdb === "function"`, y las opciones captureAll del
navegador oculto (Kino 0.9.54) solo cuando `kino.browser.captureAll === true`. kino.device (Kino 0.9.55)
es "tv" o "phone" y es undefined en un Kino anterior: úsalo solo para lo que de verdad cambia en una caja
de TV y trata todo lo que no sea "tv" como celular. Agrega kino.seed(session) (Kino 0.9.55, detrás de
`typeof kino.seed === "function"`) SOLO a un plugin cuya fuente reparta sesiones de invitado anónimas y
bloquee regiones para iniciar sesión: una sesión nueva que acabas de comprobar que funciona, nunca la de la
persona, como mucho cada pocas horas y detrás de un ajuste que la persona pueda apagar. TMDB va por
kino.tmdb, nunca con una llave en el código. Nunca exportes una función auxiliar llamada "details":
desde apiVersion 8 es un export reservado.
- Nada secreto en el código ni en el repositorio. El usuario y la contraseña de cada persona van en
un ajuste de tipo "password". Una clave de API mía va sellada: "secrets" en el manifiesto, sellada
con `node sdk/seal.mjs --repo USUARIO/REPO --name nombre`, y en el código kino.secret("nombre")
(apiVersion 4).
- Las descargas son declarativas: si la fuente lo permite, agrega "download" a "capabilities"
(apiVersion 2) y no exportes nada extra; Kino llama a resolve él mismo cuando corre la descarga.
Se guardan películas y capítulos en archivo normal (mp4, mkv…) o en HLS que no es en vivo; lo en
vivo, DASH y lo que tiene DRM, nunca.
- Firmar (solo si dije que sí): "apiVersion": 5 (necesita Kino 0.9.45+). Explícame con palabras
sencillas para qué sirve y guíame: `node sdk/seal.mjs --keygen` UNA sola vez (escribe
kino-author-key.pem), agrega `*.pem` al .gitignore ANTES de cualquier commit, y dime que guarde una
copia de la clave y que nunca la comparta (si se pierde, todos los que instalaron el plugin tienen
que desinstalarlo y reinstalarlo). Luego `node sdk/seal.mjs --sign --repo USUARIO/REPO` DESPUÉS del
último cambio en plugin.js o en "version" y otra vez después de cada cambio posterior; nunca subas
el .pem. Nunca imprimas el contenido de la clave en el chat.
- apiVersion 13 (Kino 0.9.74; los Kino anteriores lo rechazan), solo si mi fuente lo necesita: un servicio que habla por WebSocket ("socket",
kino.ws, wss:// a mis hosts declarados, frames como textos hex/base64), video que sirve el propio plugin
("byteSource": resolve responde { source: "plugin", handle, size, mime } y read({ handle, offset, length })
responde { bytes: base64 } de exactamente ese rango, armado con kino.crypto.convert, nunca con un ciclo de
JavaScript sobre los bytes), miles de registros para buscar ("catalog", kino.catalog), un almacenamiento
más grande solo en el aparato ("storageLarge"), un QR en el formulario de ajustes (ajuste "qr") o el lector
del teléfono desde una acción ("qrScan", kino.qr.scan), una contraseña que debe quedarse en un aparato como una de
verificación en dos pasos que se manda una vez ("sync": false en ese ajuste password; sync.provision puede llevarla una vez a un aparato nuevo, nunca como
keySecret), un proveedor de sincronización junto a "socket"/"storageLarge"/"catalog"/"qrScan" sin resolve ni
search, una llave que crea Kino (sync.generateKey), un formulario que esconde lo que un paso no necesita
(settingsStatus respondiendo hide: [claves]), imágenes que solo el plugin puede traer
("imageSource" y un export image). Lee primero https://kinotvapp.github.io/kino-plugins/bytes/,
/catalog/, /images/ y /qr/; prueba read con node sdk/run.mjs --size <bytes> . read <handle> <offset> <length> y
una prueba de Node (askRead o un WebSocket de mentira); revisa con typeof cada operación de bytes de kino.crypto que
uses (dependen de la versión de Kino).
- apiVersion: el más bajo que funcione (3 para canales, 4 solo para secrets, "streamHosts": "any" o un
ajuste de tipo "list", 5 solo para un plugin firmado, 6 solo si usas algo de apiVersion 6: estados y
botones en los ajustes, una sección propia, colores, telemetry, migrate, firma por petición,
userMessage, adult, canales en filas de Inicio; 6 necesita Kino 0.9.50 o más nuevo; 7 solo para
"tracking" o "segments", y necesita Kino 0.9.51 o más nuevo; 8 solo para elementos "music" o
"podcast" o el export details, y necesita Kino 0.9.54 o más nuevo; 9 para el panel del reproductor o
un "fetchHosts": "any" escrito a mano (Kino 0.9.55); 10 solo para "playlists" (Kino 0.9.65); 11 solo
para "externalResolve" (Kino 0.9.66); 12 solo para "syncProvider", el bloque "sync" o un ajuste
"link"/"help" (Kino 0.9.74; Kino 0.9.73 y anteriores lo rechazan); 13 solo para "socket", "byteSource",
"storageLarge", "catalog", "qrScan", "imageSource" o un ajuste "qr" (Kino 0.9.74); 14 para las pantallas y sus capacidades (Kino 0.9.74); 15 para
"identity", "notifications" o "pluginStore" (Kino 0.9.77); 16 para "coins" (Kino 0.9.78); 17 a 20 solo para lo que
la sección 2 de AGENTS.md lista para ellos (Kino 0.9.81); 21 para "files" (Kino 0.9.82); 22 para "progress" y 23 para
"playerSlot" (Kino 0.9.83; para seguir en Kinos anteriores, la función va en "enhancements"); 24 para una lista de drm o
ClearKey (Kino 0.9.85), 25 para el texto propio de un subtítulo (Kino 0.9.86), 26 para un tema pintado (Kino 0.9.87); 27
solo para clockLive (Kino 0.9.88), y aun así deja la base más baja y agrega "enhancements": { "27": {} }). Un catálogo que no reproduce
nada declara "catalogOnly": true (Kino 0.9.54) y aun así exporta un resolve que falla con not_found,
para los Kino anteriores. Un id nuevo y
mío (nunca "archive-org").
- Compartir (recomendado en TODO plugin, salvo que yo diga que no): un botón "Compartir" en la pantalla del plugin (en la
página de un título, con el título, y/o en la barra, solo texto) que abre una hoja con un texto que puedo cambiar y un
interruptor "Adjuntar el título", y manda el texto, más el título cuando lo hay ({ kind: "movie" | "series", tmdb }), a la
puerta "wall" de Kino Social con kino.plugins.call("social", "share", { text, title, from }). En el manifiesto:
"consumes": { "social": { "repo": "kinotvapp/kino-social", "door": "wall", "calls": ["share"] } } y
"recommends": ["kinotvapp/kino-social"] (apiVersion 20, o dentro de enhancements["20"] y detrás de
typeof kino.plugins === "object"; Kino 0.9.81 y Kino Social 0.9.7). Si responde provider_missing y Kino Social no está
instalado, responde go: { installPlugin: { repo: "kinotvapp/kino-social" } }; sin kino.plugins, un aviso "Actualiza Kino".
Nunca publiques por mí: Kino Social solo guarda un borrador que yo reviso y publico allá, y así me lo dices. Desde Kino
0.9.84 el plugin puede declarar además "openFrom": { "routes": [...] } con las rutas de su pantalla
que pueden abrir las tarjetas de otros plugins (lee route.args en el evento open y revísalos)
(https://kinotvapp.github.io/kino-plugins/share/).
- Dejar listo un título por adelantado (Kino 0.9.88, cualquier apiVersion), según lo que dije que cuesta una reproducción:
si un resolve cuenta una reproducción o gasta un cupo, una prueba o una reproducción gratis, nunca declares
"resolveAhead": true; exporta en cambio prepare(ref), que prepara una sesión o un token mientras leo la página del título
(Kino ignora su respuesta; 15 s en segundo plano, una vez por ref cada 5 minutos; no debe gastar nada ni empezar ninguna
reproducción). "resolveAhead": true solo cuando resolve no gasta nada y el plugin tiene un "fetchHosts": "any" y un
"streamHosts": "any" que yo apruebo (si no, Kino no resuelve nada por adelantado). Pruébalo con
node sdk/run.mjs . prepare <ref> (https://kinotvapp.github.io/kino-plugins/contract/#resolve-ahead).
- En vivo por reloj (apiVersion 27, Kino 0.9.88), solo para un CDN abierto (sin DRM ni firma por petición) cuyas direcciones
de segmento nombra un reloj de medios: un stream en vivo devuelve una url (una real para un Kino anterior), mime
"application/vnd.apple.mpegurl" y clockLive { template con {seg} (y {mc} con mediaCode), grid en ms, anchor { t, s } };
nunca con drm, signing ni external; cada host de segmento pasa la regla de hosts del canal. Conserva el apiVersion de base,
agrega "enhancements": { "27": {} } y manda clockLive solo cuando kino.pluginApiVersion >= 27 (nunca revises kino.apiVersion
para esto); resolve devuelve el Stream mismo; el kit no lo modela
(https://kinotvapp.github.io/kino-plugins/live-channels/#clock-live).
- Nada de "debug": true en un plugin publicado salvo que yo lo pida: todo plugin ya tiene un
interruptor "Modo debug" en Ajustes de Kino, y "debug": true solo lo deja encendido de entrada para todos. "telemetry" solo si yo acepto que
los errores del plugin lleguen a Kino; registra pasos y conteos, nunca lo que escribe la persona.
Trabaja paso a paso: primero explora la fuente con peticiones reales, luego el manifiesto, luego
cada función. Después de cada paso corre `node sdk/validate.mjs .` y `node sdk/run.mjs . <función> …`
y arregla todo lo que Kino descartaría. Graba fixtures con --record y haz que
`node --test test/plugin.test.mjs` pase sin conexión. Termina con la lista de chequeo de AGENTS.md y,
antes de entregarme el plugin, corre esta autocomprobación y dime el resultado de cada línea:
- `node sdk/validate.mjs .` sale con 0 y sin problemas;
- kino-plugin.json: "entry" e "icon" sin "./" al principio; "version" subida; el apiVersion es el más
bajo que funciona; no hay "debug": true salvo que yo lo haya pedido;
- si se firma: "signature" está en kino-plugin.json, `validate.mjs` la verificó DESPUÉS de la última
edición, y ningún .pem está rastreado (el `.gitignore` tiene *.pem);
- cada host (video, subtítulos, segmentos, redirecciones) está en "hosts" o cubierto por un campo "any";
- para que lo encuentren: el repositorio es público y no es un fork, el topic kino-plugin está puesto,
y el manifiesto tiene un "name" y una "description" en español;
- si no reproduce nada: "catalogOnly": true, y un resolve que falla con not_found para los Kino viejos;
- si usa scrapers de Nuvio: "apiVersion": 11, la capacidad "nuvio" y "nuvioRepos" (de 1 a 4), "streamHosts": "any",
kino.nuvio solo dentro de las funciones y detrás de `typeof kino.nuvio === "object"`; el kit de Node lo
responde desde una fixture (KINO_NUVIO_FIXTURE; si dice `Unknown capability`, mi kit es viejo: actualízalo, no quites la
capacidad), y los scrapers de verdad solo se prueban en Kino 0.9.71 o más nuevo;
- si tiene música o podcasts: "apiVersion": 8, cada ítem de audio tiene kind "music" o "podcast", y
(con "episodes") episodes() responde por cada ref de audio, aunque sea una sola pista;
- si es un proveedor de sincronización: "apiVersion": 12, "syncProvider" declarada, syncPull y syncPush
exportadas, "sync.maxBlobBytes" de máximo 4194304, pruebas que envían y traen un blob de 4 MiB y lanzan
"conflict", con "sync.keySecret" y "sync.provision" declarados, y me dijiste con palabras sencillas que el
plugin y su servicio pueden leer los datos;
- si usa apiVersion 13: read tiene una prueba de
Node que revisa cada rango byte por byte, ningún handle lleva un secreto y cada socket se cierra;
- el botón Compartir: consumes "social" (kinotvapp/kino-social, puerta "wall", llamada "share") y el mismo repositorio en
recommends, provider_missing responde go.installPlugin, el texto se puede cambiar antes de enviar, el título se puede quitar,
y el mensaje final dice que el borrador espera en Kino Social (nada se publica solo);
- si declara "resolveAhead": un resolve no gasta nada y el plugin tiene "fetchHosts" y "streamHosts" "any"; si exporta
prepare: node sdk/run.mjs . prepare <ref> no imprime ningún aviso y prepare no empieza ni cuenta ninguna reproducción;
- si usa clockLive: el apiVersion de base se conserva con "enhancements": { "27": {} }, una url real a su lado para un Kino
anterior, sin drm, signing ni external a su lado;
- si tiene un hueco del reproductor: "playerSlot" y el bloque "slot" juntos, los dos exports presentes, node sdk/run.mjs .
playerSlot imprime el cuadro sin nada descartado (también con --bare), y node sdk/validate.mjs . pasa;
- si tiene una pantalla: el AppBar de cada pantalla lleva mergeWithKinoBar: true y dense: true con un leading que es una
salida real, node sdk/run.mjs . screen y --device tv . screen imprimen el árbol sin nada descartado,
cada nombre de evento que usas tiene respuesta en screenEvent y, si su apiVersion es menor que 14, la pantalla
llega por "enhancements" y node sdk/validate.mjs . no reporta ningún bloque descartado;
- apiVersion 15 (Kino 0.9.77 o posterior). Una tienda: "capabilities": ["pluginStore"] (puede ir sola) y, si quieres, "pluginStore": { "mode": "local" |
"live", "name" }. storeSync({ reason, since, state }) responde { full, entries, removed?, state? } y since/state pueden
faltar en cualquier momento: cuando Kino pierde las filas de una tienda la sincroniza de nuevo desde cero, así que la
tienda debe responder entonces su lista completa (full: true) y nunca depender de un cursor guardado. Una tienda en
vivo (mode "live") exporta además storeList({ category, sort, cursor }) y storeSearch({ q, category, cursor }), 5 s y
20 llamadas por minuto. Cada entrada lleva address (owner/repo, owner/repo/ruta, owner/repo@ref o url:https://...), id,
name (de 1 a 60 caracteres) y, opcionales, description, categories, icon, popularity, updatedAt, signed/authorKey
(solo pistas); "recommended" se ignora fuera de Kino Plugins. Máximo 5.000 entradas y 4 MB. Un plugin por id en todas
las tiendas: si dos repositorios reclaman un id gana el de la lista de Kino Plugins y, si no, se conserva uno de forma
determinista, y ninguna tienda puede listar el id kino-plugins. La tienda solo entrega direcciones: nunca instala nada
ni dice que aprueba un plugin; Kino aplica su lista de bloqueo y el código +18, y muestra las líneas de consentimiento
(una en rojo para una tienda en vivo). Quien publica un plugin responde por él; Kino solo lo lista. La vista de la
tienda tiene las pestañas «De Kino» (la lista por defecto de Kino Plugins), «De la comunidad» (todo lo demás, de todas
las tiendas) e «Instalados». Comprueba con node sdk/validate.mjs . y node sdk/run.mjs . storeSync (y storeList /
storeSearch si es en vivo) sin nada reportado como [dropped by Kino]. identity: kino.identity.telegram({ challenge? })
responde { id, token? } solo dentro de una llamada que la persona inició: el token solo para las llaves de autor de
kinoIdentity.tokenAuthors (cualquier otro autor recibe el id y, con un desafío, la atestación desde Kino 0.9.88;
permission_denied antes); nunca registres ni muestres el token; el plugin funciona si se rechaza (permission_denied). notifications:
kino.notifications.post({ id, title, text?, go? }) y clear(id?), títulos de 80 caracteres, textos de 160, 20 avisos por
hora, desde una pantalla o el trabajo. library: kino.library.watched() trae season y episode en las series. Todo
declarativo y probado con node sdk/run.mjs . notifications y las variables KINO_IDENTITY_*.
Al final, llévame de la mano:
1. Publicarlo: repositorio público (nunca fork) con los archivos en la raíz; el topic kino-plugin y
una descripción en GitHub (About → ⚙ → Description y Topics → Save changes, o
`gh repo edit USUARIO/REPO --add-topic kino-plugin --description "…"`); y un "name" y una
"description" buenos, en español, en kino-plugin.json, porque eso es lo que la gente ve en Kino.
2. Instalarlo en Kino: en el celular, menú ☰ → Plugins → botón +; en el televisor, Ajustes →
Plugins → Agregar. Escribir USUARIO/REPO → Agregar → leer la hoja → Instalar (y Configurar si
pide datos).
3. Qué probar a mano en Kino y qué hacer si algo falla.
Un ejemplo lleno¶
Así queda la parte "Lo que quiero" para una fuente pública y sencilla. Cópiala en lugar de la del prompt si quieres ensayar el camino completo antes de hacer el tuyo:
Lo que quiero:
- Fuente: https://archive.org, solo la colección de cine negro (https://archive.org/details/Film_Noir)
- Contenido: películas; en inglés
- Acceso: ninguno
- Qué le pregunta Kino a la persona al configurarlo: nada
- Descargas para ver sin conexión: sí
- Nombre en Kino y una descripción corta: "Cine negro": "Películas clásicas de cine negro de archive.org, de dominio público. No pide cuenta."
- Mi usuario de GitHub: mi-usuario
Prompt corto: un plugin con scrapers de Nuvio¶
Si lo único que quieres es un plugin cuyo catálogo es tuyo y cuyos enlaces los buscan los scrapers de un
repositorio de Nuvio, este prompt es más corto (el asistente igual lee AGENTS.md):
Vas a escribir un plugin de Kino que busca sus enlaces con los scrapers de un repositorio de Nuvio.
Puede que yo no sepa programar: explícame cada paso en español sencillo, ejecuta tú los comandos
(antes dime cuál y para qué) y pregúntame antes de cualquier cosa que no se pueda deshacer.
Lee, en este orden:
1. https://kinotvapp.github.io/kino-plugins/AGENTS.md (tus instrucciones).
2. https://kinotvapp.github.io/kino-plugins/nuvio-plugins/ (kino.nuvio: el manifiesto, las cuatro
llamadas, los límites y un ejemplo completo que debes seguir).
3. https://kinotvapp.github.io/kino-plugins/llms-full.txt (la guía completa, contract.json y kino.d.ts).
Lo que quiero:
- Repositorio de Nuvio: <<< owner/repo, o la dirección https de su manifest.json >>>
- Catálogo: <<< películas / series / anime; de dónde sale (p. ej. TMDB con kino.tmdb) >>>
- Qué scrapers preguntar primero: <<< p. ej. los que hablan español / los de anime solo para animación / lo decide el plugin >>>
- Nombre en Kino y una descripción corta: <<< p. ej. "Mi todo en uno": "Películas y series, enlaces de Nuvio" >>>
- Mi usuario de GitHub: <<< p. ej. mi-usuario >>>
Reglas: "apiVersion": 11, "nuvio" en "capabilities", "nuvioRepos" con ese repositorio, y
"streamHosts": "any". Llama a kino.nuvio solo dentro de tus funciones y detrás de
`typeof kino.nuvio === "object"`. Pregunta pocos scrapers a la vez (empieza con 4 a 6), baja
timeoutMs para que uno colgado no gaste los 75 s del resolve, y recuerda en kino.storage cuáles
funcionaron. Un scraper que falla es una entrada con ok: false, no un error. Devuelve un solo Stream
con la mejor copia y el resto en alternatives. Todo texto para la persona en español de Bogotá, con tuteo.
El kit de Node (el actual) conoce "nuvio": `node sdk/validate.mjs .` revisa nuvioRepos y `node sdk/run.mjs`
responde kino.nuvio desde una fixture que escribes tú (KINO_NUVIO_FIXTURE; ejemplo en
https://github.com/kinotvapp/kino-plugin-sdk/blob/main/fixtures/nuvio.json), así que pruébalo así. Si
validate dice `Unknown capability: "nuvio"`, mi copia del kit es vieja: dime que copie otra vez sdk/,
contract.json y kino.d.ts desde kinotvapp/kino-plugin-sdk (no quites la capacidad). Al terminar, dime cómo
probar los scrapers de verdad instalando el plugin en Kino 0.9.71 o más nuevo, con los clics exactos.
Prompt corto: plugins que se usan entre sí¶
Para un plugin que usa la puerta de otro plugin (un consumidor) o que abre una para otros plugins (un proveedor). El protocolo entre plugins llega con Kino 0.9.81: el plugin solo se instalará, o solo abrirá su puerta, en Kino 0.9.81 o más nuevo. Llena la parte que te toca y borra la otra:
Vas a escribir un plugin de Kino que usa el protocolo entre plugins (apiVersion 20, Kino 0.9.81):
plugins que se usan entre sí a través de Kino.
Puede que yo no sepa programar: explícame cada paso en español sencillo, ejecuta tú los comandos
(antes dime cuál y para qué) y pregúntame antes de cualquier cosa que no se pueda deshacer.
Lee, en este orden:
1. https://kinotvapp.github.io/kino-plugins/protocol-quick/ (el protocolo en una página: formas, una pantalla
mínima, los comandos de prueba, las cinco trampas), y después https://kinotvapp.github.io/kino-plugins/AGENTS.md
(tus instrucciones; su tabla de contenido al principio dice en qué línea empieza cada parte; la sección 4,
"apiVersion 20: the plugin protocol", es la que más importa aquí).
2. https://kinotvapp.github.io/kino-plugins/protocol/ (provides, consumes, kino.plugins.call, los tipos,
los siete códigos de error, los límites, los flujos, la puerta de instalación y el ejemplo de TMDB + Cine Trivia).
3. https://kinotvapp.github.io/kino-plugins/llms-full.txt (la guía completa, contract.json y kino.d.ts:
la sección "protocol" de contract.json tiene cada número).
Estudia los dos plugins de referencia antes de escribir nada: https://github.com/kinotvapp/kino-plugin-cine-trivia
(un consumidor) y https://github.com/kinotvapp/kino-plugin-tmdb (un proveedor, TMDB 1.3.0 y posteriores).
Lo que quiero:
- Papel: <<< consumidor (usa la puerta de otro plugin) / proveedor (abre una puerta para otros) / los dos >>>
- Si es consumidor: el repositorio del proveedor y su puerta: <<< p. ej. kinotvapp/kino-plugin-tmdb, puerta "movies" >>>
y qué hace mi plugin con esos datos: <<< p. ej. un quiz de cine / una pantalla de "película al azar para hoy" >>>
- Si es proveedor: qué podrían pedirle otros plugins: <<< p. ej. "la letra de una canción por título y artista", "los partidos de hoy" >>>
y de dónde salen esos datos: <<< p. ej. kino.tmdb / mi sitio https://example.org/api >>>
- ¿Mi plugin se debe seguir instalando en Kino anteriores? <<< sí (usa enhancements["20"]) / no (apiVersion 20) >>>
- Nombre en Kino y una descripción corta: <<< p. ej. "Cine Trivia": "Preguntas de cine con películas de TMDB" >>>
- Mi usuario de GitHub: <<< p. ej. mi-usuario >>>
Reglas:
- Kino es el único intermediario: nunca importes, consultes ni copies el otro plugin; un consumidor solo usa
`await kino.plugins.call(alias, llamada, arg)` con una entrada de "consumes"; un proveedor solo responde con
exportaciones que se llaman exactamente proto_<puerta>_<llamada>(arg) y proto_<puerta>_<flujo>(cursor) -> { items, cursor }.
- Nombres de puertas, llamadas, flujos y alias: letras y dígitos, empiezan con letra, máximo 32. Tipos solo del
lenguaje cerrado (string, number, boolean, T?, T[], un tipo de la puerta, un objeto en línea).
- Consumidor: declara en "consumes" solo las llamadas y los flujos que usa, pon el mismo repositorio en "recommends",
y mientras installed["owner/name"] no sea true dibuja SOLO una pantalla de instalación con un botón
{ go: { installPlugin: { repo: "owner/name" } } }; nunca instales nada tú. Cada kino.plugins.call va en
try/catch y muestra un mensaje corto por código (provider_missing, not_declared, bad_input, bad_output,
rate_limited, timeout, provider_failed); nada de reintentos en bucle ni de llamadas desde un trabajo en segundo
plano. Los argumentos nunca llevan tokens, contraseñas ni nada privado: le llegan al proveedor.
- Proveedor: responde solo lo que la puerta declara, nada privado en las respuestas ni en los errores, nunca un
secreto sellado; un "summary" corto que la persona entienda; una vez publicada, una puerta solo crece (llamadas
nuevas, campos opcionales).
- Límites: 64 KB por petición y por respuesta, 10 s por llamada, 30 llamadas en cualquier ventana de 10 s por puerta,
4 puertas por plugin, 16 llamadas y 8 flujos por puerta, 8 entradas en consumes, flujos consultados cada 30 s como mínimo.
- Todo texto para la persona en español (neutro, con tuteo, nunca voseo) y en inglés (text + textEn).
- Un consumidor solo de pantalla (apiVersion 20, un "consumes" no vacío, "capabilities" exactamente ["screen"])
declara "hosts": [] (una Image no necesita declarar su host; sin host su propio kino.fetch se rechaza salvo que
declare fetchHosts "any" o un ajuste url). Cualquier otra capacidad trae de vuelta "al menos un host": entonces pon
solo los hosts reales a los que llega su kino.fetch. Nunca example.com ni uno inventado (validate avisa si es de
relleno). Mira https://kinotvapp.github.io/kino-plugins/protocol/#consumer-hosts. Un plugin que solo provee
(apiVersion 20, provides, sin capacidades ni ajustes) también puede tener "hosts": []; no existe un campo
"providesOnly".
- Árboles de pantalla: un Scaffold cuyo appBar es { "type": "AppBar", ... }; SingleChildScrollView lleva
"children" (una lista), nunca "child"; los botones son ElevatedButton/TextButton con labelText + labelTextEn y
onPressed (FilledButton no existe). Copia la pantalla mínima de consumidor de la sección 4 de AGENTS.md.
Parte de la plantilla del kit, no de un archivo en blanco: `node sdk/init.mjs mi-plugin --kind provider` o
`node sdk/init.mjs mi-plugin --kind consumer --repo dueño/nombre --door <puerta> --call <llamada>` (`"hosts": []`)
(`node sdk/init.mjs --help`), cambia su `test/provider` de reemplazo por una copia del proveedor real, y después copia
junto a él `sdk/` sin `sdk/test/` y `contract.json` (`kino.d.ts` es opcional, solo para los tipos del editor). Pruébalo sin conexión antes que nada:
`node sdk/validate.mjs .` (ningún ✗, y lee cada línea !); para un proveedor
`node sdk/run.mjs . proto <puerta>.<llamada> '<json>'` y `node sdk/run.mjs . proto <puerta>.<flujo> ['<cursor>']`;
para un consumidor `node sdk/run.mjs --context '{"installed":{"dueño/nombre":true}}' --provider <carpeta del proveedor> . screen`
(también con false, con --lang en y con --device tv: ninguna línea "dropped" en stderr), el mismo --context y
--provider con `screenEvent <evento>`, y `screenEvent protocol <alias>.<flujo>` (con --cursor '<json>' para probar
ítems repetidos). El kit ignora "repo" (usa el primer proveedor que tenga la puerta): revísalo a mano. Si run.mjs
no conoce --provider ni proto, o init.mjs no conoce --kind, dime cómo conseguir un kit más nuevo en vez de darle
la vuelta. El kit no revisa la regla 18+, los secretos sellados en las respuestas ni las llamadas a sí mismo: al
terminar, dime cómo probarlo en Kino 0.9.81 o más nuevo con los dos plugins instalados, y después con el
proveedor apagado y quitado, con los clics exactos.
Que Kino encuentre tu plugin¶
Instalarlo escribiendo la dirección funciona desde el primer momento. Para que además salga solo en Kino, en la pestaña "De la comunidad" de la pantalla de Plugins, el repositorio tiene que:
- ser público y no un fork (créalo con "Use this template");
- tener
kino-plugin.jsonen la raíz, válido paranode sdk/validate.mjs ., con unnamey unadescriptionen español (es lo que muestra la tarjeta); - tener el topic
kino-plugin(About → ⚙ → Topics) y, mejor, una descripción en GitHub; - en Kino 0.9.53 y anteriores, estar entre los 30 con más estrellas del topic.
Desde Kino 0.9.54 la app lee los resultados de a 100, en el orden que elige la persona ("Populares" o "Recientes"), "Cargar más" lee los 100 siguientes y "Buscar en GitHub" encuentra un plugin por el nombre y la descripción de su repositorio, así que también se encuentra un plugin sin estrellas. Cada dispositivo busca de nuevo cada 12 horas, o al tocar "Actualizar". Los clics exactos y cómo comprobarlo: Aparecer en Kino.
Con Kino 0.9.77 (apiVersion 15) la app ya no busca en GitHub por su cuenta: la pestaña
«De la comunidad» de la vista de la tienda (junto a «De Kino» e «Instalados») la llena Kino Plugins, cuyo índice diario se
construye con los repositorios que tienen el topic kino-plugin; las reglas de arriba siguen valiendo. Hay un plugin por id
en todas las tiendas y un ícono de recargar termina con un aviso («Se actualizaron N plugins» o «Tus plugins están al día»).
Plugins firmados¶
Si quieres que la gente sepa que cada actualización viene de ti, pide un plugin firmado
("apiVersion": 5, Kino 0.9.45+): creas una clave una vez, el asistente firma plugin.js con ella
después de cada cambio, y Kino comprueba la firma al instalar y en cada actualización. La clave
privada se queda en tu computador: nunca debe llegar a GitHub (*.pem en el .gitignore), y
conviene que hagas una copia de seguridad, porque si se pierde, todos los que instalaron el plugin
tienen que desinstalarlo y reinstalarlo. Es opcional: un plugin sin firma funciona igual.
Lee la página completa.
Si algo falla¶
Pégale al asistente el texto completo que salió en la terminal (no un resumen) y dile qué esperabas. Algunos casos comunes:
| Lo que ves | Qué hacer |
|---|---|
node: command not found, "node no se reconoce…" |
Node no está instalado, o abriste la terminal antes de instalarlo: instálalo y abre una terminal nueva. |
✗ kino-plugin.json: … |
El manifiesto rompe una regla; el mensaje es el mismo que da Kino. Pídele al asistente que lo arregle según AGENTS.md. |
[dropped by Kino] … |
Kino descartaría esos resultados. Pregúntale qué regla de el contrato rompen, en vez de aceptar un parche a ciegas. |
[host_not_allowed] … |
Un host que falta en hosts: que lo declare. |
El campo "entry" debe ser una ruta relativa a un archivo .js (Kino) o Quita el "./" del campo "entry" (kit) |
"entry" (o "icon") empieza con ./. Escribe "plugin.js": Kino 0.9.45 y anteriores rechazan el ./ (por qué). |
La firma del autor no es válida… |
El plugin está firmado y plugin.js o version cambiaron después de firmar: corre otra vez node sdk/seal.mjs --sign --repo owner/repo. |
[timeout] … |
La fuente es lenta o hay demasiadas peticiones: que haga menos peticiones por llamada. |
| Funciona en el kit pero falla en Kino | El kit de Node es más permisivo que la app (lo que no reproduce): globales que faltan, un throw antes del primer await (en Kino 0.9.49 y anteriores), kino.html.select. Dale al asistente el mensaje exacto que muestra Kino (o una foto de la pantalla). |
| Kino dice "Configura … en Ajustes ▸ Plugins" | El plugin necesita datos: toca el botón Configurar del mensaje, o ve a Plugins → Instalados → tu plugin → Configurar. |
| No sale en "De la comunidad" | Revisa Aparecer en Kino. |
Registros de Kino (para quien tenga un computador conectado al celular con adb):
adb logcat -s KinoPlugin muestra lo que escribe el plugin con kino.log. Nunca pegues contraseñas
ni claves en el chat.
Consejos¶
- Dale una terminal al asistente. El kit solo ayuda si el asistente puede ejecutar
node sdk/validate.mjs .ynode sdk/run.mjs …y leer lo que imprimen. - Pruébalo en la app. El kit de Node es más permisivo que Kino (lo que no reproduce): instala el plugin y revisa que busque, liste capítulos, reproduzca (y descargue, si lo declaraste) antes de compartirlo.
- Pide las razones. Cuando el kit reporte un ítem descartado, pregúntale al asistente qué regla de el contrato rompió, en vez de aceptar un parche.
- Sube la versión en cada cambio. Kino solo instala una actualización si
versiones mayor (Publicar). - Ojo con los derechos. Un plugin solo puede llegar a lo que la persona igual podría ver; no le pidas a un asistente que se salte un muro de pago, un login o un DRM.