Kuti: la tarea del navegador que repites cada semana, escrita en un archivo que puedes leer

¿Para quién es Kuti?

Quien repite a mano la misma tarea web cada semana —entrar a un panel, sacar el mismo reporte, cargar el mismo formulario— y el equipo donde ese «cómo se hace acá» vive en una sola cabeza.

¿Qué hace Kuti?

¿Qué puedes usar hoy y qué te falta?

Kuti tiene dos mitades. La mitad del archivo funciona solo con el CLI. La mitad del navegador —mirar la página mientras grabas, capturar tus clics y reproducir el guion— pasa entera por la extensión de navegador de Theus, que viaja dentro del programa desde la versión 1.2.2. Si tienes una anterior, theus update te la trae.

Lo que ya funciona con solo tener Theus CLI:

• El guion como archivo. Es un YAML versionado que describe cada paso por su intención y por cómo encontrar el elemento, no por coordenadas. Lo abres con cualquier editor, lo lees, lo corriges a mano y lo guardas en tu repositorio como un archivo más.
• Todo lo que hace /guiones: listar, ver el YAML anotado, exportar a un archivo .kuti, importar el de un compañero viendo primero un resumen, y borrar.
• Publicarlo como skill del arsenal, para que el modelo lo invoque solo cuando la conversación encaje con lo que ese guion resuelve.
• /grabar destilar, que convierte la sesión de terminal que acabas de tener en una skill: extrae la ruta que funcionó y descarta los callejones sin salida. Es la única parte de Kuti que no toca el navegador.

Lo que necesita la extensión de navegador:

• Grabar en modo copiloto. Theus mira la página mientras tú narras la tarea, para anotar cada elemento por su rol, su nombre y su texto.
• Grabar en automático tus clics, tus teclas y los cambios de campo.
• Reproducir. El reproductor trabaja únicamente con las herramientas de navegador de Theus; si el navegador no está conectado, se detiene y te lo dice en vez de intentarlo por otro lado.

Y la extensión, sin rodeos: viaja con el programa desde la versión 1.2.2, en los cuatro canales. Lo que todavía no está es publicada en una tienda de extensiones, así que se carga descomprimida activando el modo de desarrollador del navegador: dos clicks que el comando /chrome te deja preparados — instala el conector, te abre la pantalla exacta y te copia la ruta al portapapeles. Preferimos que lo leas aquí, antes de instalar, y no después de perder una tarde.

¿Cómo se graba una tarea con Kuti?

Con tres comandos dentro de Theus: /grabar para capturar la tarea, /reproducir para repetirla y /guiones para ver, exportar y borrar lo que tienes guardado. Lo grabado queda como archivo en .theus/guiones/ dentro de tu proyecto, o en ~/.theus/guiones/ si lo quieres en todas partes.

• /grabar reporte abre la grabación en modo copiloto: haces la tarea contando lo que haces y Theus escribe el guion contigo, paso a paso, enseñándotelo para que lo confirmes o lo corrijas. Para mirar la página y anotar los elementos necesita el navegador conectado por la extensión.
• /grabar auto reporte captura de verdad tus clics, tus teclas y los cambios de campo, también con la extensión. Los campos sensibles —contraseña, tarjeta, clave de acceso, código de un solo uso— se registran sin su valor, ya convertidos en parámetro secreto.
• /grabar fin cierra: anota la intención de cada paso, propone los parámetros y guarda el archivo.
• /reproducir reporte imprime el plan numerado y espera tu aprobación antes de tocar el navegador. Si el guion pide datos, se los pasas ahí mismo: /reproducir reporte --usuario ana@miempresa.pe. También necesita la extensión: sin ella se detiene ahí.
• /guiones lista lo que tienes; /guiones ver reporte te imprime el YAML anotado y /guiones borrar reporte lo elimina. Estos tres trabajan sobre tu disco y no necesitan navegador.

¿Qué hay dentro de un guion?

Un archivo YAML que empieza por kuti: 1 y una lista de pasos, cada uno con su intención escrita en castellano. Cabe en pantalla, lo abres con cualquier editor y lo corriges a mano antes de ponerlo a correr: no hay nada que desempaquetar ni ninguna grabación binaria que mirar de lejos. Este es un guion de ejemplo, con el formato real:

$ cat .theus/guiones/reporte.guion.yaml
kuti: 1
nombre: reporte
descripcion: Entra al panel y saca el total del día.
parametros:
  usuario:
    descripcion: correo con el que entras al panel
  clave:
    descripcion: contraseña del panel
    secreto: true
pasos:
  - tipo: navegar
    url: https://panel.miempresa.pe/entrar
    intencion: abrir la pantalla de acceso
  - tipo: escribir
    objetivo: { rol: textbox, nombre: Correo, css: "#email" }
    valor: "{{usuario}}"
  - tipo: escribir
    objetivo: { rol: textbox, nombre: Contraseña }
    valor: "{{clave}}"
  - tipo: clic
    objetivo: { rol: button, nombre: Entrar, texto: Entrar }
    intencion: entrar al panel
  - tipo: esperar
    condicion: la tabla de pedidos termina de cargar
  - tipo: verificar
    espera: la página contiene "Pedidos del día"
  - tipo: extraer
    objetivo: { rol: cell, nombre: Total, css: td.total }
    guardar_en: total_del_dia

# La contraseña no está aquí. Su valor se lee al reproducir, de
# la variable THEUS_GUION_REPORTE_CLAVE.

Cada paso se describe por lo que pretende, no por dónde estaba el ratón. Un grabador de coordenadas se rompe en cuanto la página mueve un botón catorce píxeles; aquí lo que se guarda es qué elemento buscar y para qué, y eso se vuelve a resolver sobre la página de hoy. La escalera va de lo más estable a lo menos:

• Rol y nombre accesible primero —«el botón que se llama Entrar»—, que es lo que menos cambia cuando se rediseña una pantalla.
• El texto visible, si el rol y el nombre no dan un único candidato claro.
• El selector CSS, como último recurso, porque es justo la llave que un cambio de plantilla invalida primero.

Un paso esperar tampoco lleva un temporizador: lleva una condición escrita en castellano —«hasta que aparezca este elemento», «hasta que la URL sea esta», «hasta que el texto esté en la página», «hasta que no queden peticiones en vuelo»— y Theus la traduce a cómo comprobarla. Un temporizador de tres segundos falla el día que la red va lenta y actúa sobre una pantalla que aún no está; una condición, no. Dicho como es: eso es la instrucción que sigue el reproductor, no un cronómetro que se lo impida.

Y un paso extraer guarda lo que leyó bajo un nombre —total_del_dia— que los pasos siguientes pueden usar; si no logra extraerlo, la instrucción es parar y decirlo, no seguir con lo que dependía de él.

¿Cuándo se detiene a preguntarte?

Siempre antes de empezar, y otra vez ante cualquier paso sin vuelta atrás. Lo primero que hace /reproducir es imprimirte el plan completo numerado y esperar tu aprobación; a partir de ahí se para en tres casos, decididos por un módulo de lógica pura que comparten el plan y el reproductor:

• El guion marca ese paso como de confirmación explícita.
• El paso lo tiene que hacer una persona: un captcha, un segundo factor. Ahí pausa y te espera; no lo intenta.
• El texto del paso habla de pagar, enviar, borrar, transferir, publicar, emitir, contratar o firmar —aunque el guion no lo hubiera marcado—. La lista de raíces está escrita de más a propósito: un falso positivo solo añade una pregunta, un falso negativo hace algo irreversible sin permiso.

Ese freno solo puede dispararlo un paso que actúe sobre la página —un clic, una tecla, algo que se escribe—; leer, esperar o verificar no mueve nada. Y si un objetivo no casa después de agotar la escalera, la instrucción es abortar limpio y decirte en qué paso se quedó, en lugar de improvisar el siguiente.

Las contraseñas no se escriben nunca dentro del guion. Un parámetro marcado secreto: true viaja sin valor —ni al guardar en tu disco ni al exportar—, y al reproducir el valor se lee de una variable de entorno, THEUS_GUION_<GUION>_<PARAMETRO>, que el plan enmascara al imprimirlo. El matiz completo, porque a medias no sirve: ese valor ya resuelto sí transita la conversación de esa sesión, porque el agente tiene que teclearlo en la página.

¿Cómo comparto un guion con mi equipo?

Con /guiones exportar reporte, que deja un archivo .kuti autocontenido y legible. Quien lo recibe lo abre y lo lee antes de ejecutar nada, y al importarlo Theus le enseña primero un resumen y no guarda hasta que confirma. Esta parte va sobre disco: funciona tengas o no la extensión de navegador.

• El archivo es auditable a ojo. Un guion ajeno es código de automatización de un tercero que va a navegar, hacer clic y escribir en tu navegador: por eso el formato es YAML y no un binario.
• Nunca sobrescribe en silencio. Si ya tienes un guion con ese nombre, te lo dice; la importación no pisa tu versión sin que lo apruebes.
• Los secretos no viajan. Los parámetros marcados como secretos se exportan sin valor, así que compartir el proceso no es compartir la contraseña: cada uno pone la suya en su máquina.
• Y si tu equipo comparte cuenta, /guiones equipo lista los del equipo, /guiones subir y /guiones traer mueven uno, y /guiones sync, que sincroniza, baja los que aún no tienes sin tocar los que ya tienes con ese nombre. Con su salvedad: esta sincronización contra el servidor es reciente y todavía no está probada de punta a punta, así que trátala como lo nuevo que es.

Esto es lo que resuelve la mitad aburrida del problema: que el «cómo se hace esto acá» deje de vivir en una sola cabeza y de salir distinto según quién lo haga.

¿Qué no hace Kuti todavía?

Preguntas frecuentes sobre Kuti