Habilidad de Publicación
Publica proyectos HTML frontend en la plataforma de publicación y, opcionalmente, empaquétalos como APKs de Android.
URL de la plataforma:
https://pushwebly.com
Usa "proyecto" en los mensajes al usuario. Las rutas canónicas de la API son /api/projects y los nombres de las herramientas canónicas son project_*. Pueden aparecer alias game_* obsoletos y campos de respuesta gameId; trata gameId como el id del proyecto.
Reglas de Ejecución para Codex
- Prefiere las herramientas MCP
project_*montadas si existen en el entorno actual. - Si las herramientas MCP remotas no están montadas, usa las API HTTP con
curl. - No requieras Python. Los scripts opcionales, si existen, son solo para usuarios de CLI/CI.
- Pregunta solo por la información genuinamente faltante: credenciales, ruta del zip, nombre del proyecto, visibilidad pública/privada o preferencia de contraseña de acceso privada.
- Nunca escribas credenciales dentro del zip del proyecto o en un archivo del repositorio. Guárdalas solo en el archivo
~/.publisher/config.jsondel usuario después de obtener su consentimiento. - En Windows/PowerShell, usa un archivo JSON temporal para los cuerpos de las solicitudes en lugar de escapar JSON en línea en el shell.
Mapeo de Intenciones
| Intención del usuario | Acción | Información faltante a preguntar |
|---|---|---|
| Publicar, enviar, subir, poner en línea | Publicar proyecto | ruta del zip, nombre del proyecto |
| Hacer una app instalable para teléfono, APK, paquete Android | Publicar y construir APK | ruta del zip, nombre del proyecto |
| Construir APK para un proyecto ya publicado | Construir APK | id del proyecto; usa la lista de proyectos si es necesario |
| Hacer una app privada/pública, agregar/eliminar contraseña de acceso | Cambiar visibilidad | URL de la app, visibilidad objetivo (contraseña opcional si es privada) |
| Mostrar mis proyectos, listar proyectos publicados | Listar proyectos | ninguno si el token está disponible |
| Iniciar sesión, registrarse, configuración de cuenta | Iniciar sesión/registrarse | nombre de usuario y contraseña |
Si la intención es ambigua, haz una pregunta corta: "¿Solo publicarlo, o publicarlo y también construir un APK de Android?"
Proceso de Conversación para Publicación
Cuando los usuarios expresen intenciones como publicar, desplegar, lanzar, compartir aplicaciones, generar enlaces de acceso, etc., deben entrar en este proceso.
Principios Generales de la Máquina de Estados Finitos
- Al entrar en el flujo, ejecuta primero
S-1(verificación de versión, no bloqueante), luego procede en el ordenS0 -> S1 -> S2 -> S3 -> S4. - No está permitido saltarse pasos (excepto
S-1). - No se pueden consultar múltiples campos en una sola solicitud.
- La información que el usuario haya proporcionado claramente se puede registrar y no es necesario preguntarla repetidamente.
- Cuando la respuesta del usuario sea ambigua, solo se hace un seguimiento una vez para el campo actual.
- Solo después de completar el paso actual se puede pasar al siguiente.
- Si se requiere esperar la entrada del usuario, no agregues explicaciones, sugerencias o vistas previas del siguiente paso al final de la respuesta.
S-1: Verificación de Versión (primer nodo del flujo de publicación, no bloqueante)
Al entrar en el flujo de publicación, ejecuta una autoverificación de versión antes de S0. Este paso NO es parte de las reglas de bloqueo <HARD-GATE>: sea cual sea el resultado, incluso si el endpoint es inalcanzable, siempre continúa. Nunca interrumpas la publicación por un problema de versión.
Pasos:
-
Lee la versión local de la habilidad: el campo
versionen el frontmatter de este archivo. -
Consulta la última versión de la plataforma (no requiere inicio de sesión):
curl -s https://ai-pub.pushwebly.com/api/skill/latest-versionLa respuesta
datacontiene:version(última),downloadUrl(paquete de documentación multiplataforma, descomprimir y usar),downloadUrlWindows(instalador .exe para Windows) ydownloadUrlMac(instalador .zip para macOS). -
Compara la
versionlocal con laversiondevuelta.Regla de comparación: una versión es
major.minor.patch. Compara segmento por segmento como enteros, de izquierda a derecha — primero major, luego minor, luego patch; rellena los segmentos faltantes con 0 (1.1significa1.1.0). Compara como enteros, NO como cadenas:1.10.0es mayor que1.9.0(segundo segmento10 > 9); una comparación de cadenas daría un resultado incorrecto. Ejemplo ascendente:1.0.0 < 1.0.9 < 1.1.0 < 1.2.0 < 1.10.0 < 2.0.0.-
La versión local es más antigua (la secuencia de segmentos enteros local es menor que la devuelta): DEBES mostrar un aviso de actualización al usuario antes de continuar, y el aviso DEBE incluir la URL de descarga real (esto no bloquea la publicación, pero el aviso no debe omitirse). Elige la URL de descarga según el sistema operativo del usuario:
- Windows → usa
downloadUrlWindows - macOS → usa
downloadUrlMac - Sistema operativo desconocido, o el campo correspondiente está vacío → recurre a la
downloadUrlgenérica
Texto del aviso (escríbelo en el MISMO idioma en el que el usuario está conversando — chino si escribe en chino, inglés si escribe en inglés; no uses un solo idioma fijo; el siguiente ejemplo es solo una plantilla en inglés; reemplaza la URL con la seleccionada real; escribe la URL de descarga como un enlace Markdown clicable
[URL](URL)— NO la envuelvas en comillas invertidas como código en línea, o el usuario no podrá hacer clic; nunca dejes un marcador de posición, nunca digas "existe una nueva versión" sin proporcionar el enlace):Nota: hay disponible una nueva versión
<version>de la habilidad Publisher (tú estás en<local version>). Descargar: https://ai-pub.pushwebly.com/downloads/AI_Publisher_skill.exe (la actualización no afecta la publicación actual). - Windows → usa
-
La versión local es igual o más reciente: permanece en silencio y continúa.
-
La solicitud falla/expirado/no se puede analizar: salta en silencio, ve directamente a
S0, no muestres un error.
-
-
En todos los casos, continua con
S0a continuación. Debido a que este paso solo notifica (sin entrada, sin bloqueo), la regla de "como máximo una pregunta dirigida al usuario por respuesta" no se aplica a él: la nota de versión puede compartir la misma respuesta que la primera pregunta deS0.
S0: Verificar Estado de la Cuenta
Primero, verifica si ya hay un token/credencial local disponible.
- Si ya tienes credenciales de cuenta: ve a
S2. - Si no hay credenciales de cuenta: entra en
S1_USERNAME. - Si no se puede verificar el estado de la cuenta: pregunta al usuario si ya tiene una cuenta de publicación.
Haz una pregunta al usuario:
Primero necesito confirmar la cuenta de publicación: ¿Ya tienes una cuenta o token disponible?
Respuesta del usuario:
- Sí: Solicita al usuario que proporcione o confirme el token/las credenciales de inicio de sesión, luego ve a
S2. - No: Entra en
S1_USERNAME.
S1: Proceso de Registro e Inicio de Sesión
S1_USERNAME: Recopilar nombre de usuario registrado
Si no hay nombre de usuario, solo pregunta:
Por favor, proporciona el nombre de usuario a registrar.
Después de recibir el nombre de usuario, regístralo como username y entra en S1_PASSWORD.
S1_PASSWORD: Recopilar contraseña de registro
Si no hay contraseña, solo pregunta:
Por favor, proporciona la contraseña de registro.
Después de recibir la contraseña, regístrala como password y entra en S1_VALIDATE.
S1_VALIDATE: Validación conjunta
Solo después de tener tanto username como password se puede llamar a la interfaz del backend para la validación conjunta.
Validación exitosa:
- Crear cuenta
- Completar inicio de sesión
- Mensaje:
Registro e inicio de sesión exitosos - Entrar en
S2
Validación fallida:
- Mostrar la razón de error específica devuelta por el backend
- Solo preguntar sobre el elemento que necesita ser corregido
- No terminar el proceso de registro
S2: Preguntar sobre la Visibilidad de la Aplicación
Si el estado público o privado no se ha definido claramente, solo pregunta:
¿Esta aplicación es pública? Pública significa que cualquiera puede acceder a ella mediante un enlace; privada requiere una contraseña de acceso de 6 dígitos.
Respuesta del usuario:
- Pública / Sí / pública: Registra
visibility=public, entra enS4 - Privada / No / privada: Registra
visibility=private, entra enS3 - No claro: Continúa preguntando solo sobre este elemento
S3: Contraseña de Acceso Privada
Si visibility=private, es necesario preguntar si se desea personalizar la contraseña, preguntando solo:
¿Quieres personalizar una contraseña de acceso de 6 dígitos? También puedes responder "generada por el sistema".
Respuesta del usuario:
- Proporcionar contraseña: la verificación debe ser de 6 dígitos o letras; después de pasar, registra
accessPassword=<contraseña del usuario>y entra enS4 - Responder generada por el sistema / No es necesaria / Aleatoria: No pases
accessPassword, deja que el backend la genere, y entra enS4 - Error de formato de contraseña: Solo indica los requisitos de formato y vuelve a preguntar por la contraseña
S4: Ejecutar Publicación
Solo se permite llamar a la interfaz de publicación si se cumple una de las siguientes condiciones:
visibility=publicvisibility=privatey el usuario ha seleccionado una contraseña personalizada o una contraseña generada por el sistema
Parámetros de publicación:
Aplicación pública:
{
"visibility": "public"
}
Aplicación privada, contraseña personalizada:
{
"visibility": "private",
"accessPassword": "a1b2c3"
}
Por defecto es public si el usuario no especifica la visibilidad. Una contraseña de acceso privada debe coincidir con ^[A-Za-z0-9]{6}$; de lo contrario, pide una contraseña válida o deja que el backend la genere.
Manejo de Tokens
Se requiere un token Bearer para todas las API de publicación.
Usa este orden:
- Si el usuario proporcionó un token en la conversación, úsalo directamente.
- Si
~/.publisher/config.jsonexiste, lee el nombre de usuario/contraseña almacenados e inicia sesión nuevamente para refrescar el token. - De lo contrario, pide nombre de usuario y contraseña. El endpoint de inicio de sesión registra automáticamente nuevas cuentas.
Endpoint de inicio de sesión/registro:
curl -s -X POST https://ai-pub.pushwebly.com/api/auth/login-or-register \
-H "Content-Type: application/json" \
-d @login.json
Escribe login.json como:
{"username":"alice","password":"contraseña-en-texto-plano"}
Usa data.token de la respuesta como:
Authorization: Bearer <TOKEN>
Elimina el archivo de inicio de sesión temporal después de usarlo.
Archivo de credenciales local opcional:
{
"baseUrl": "https://ai-pub.pushwebly.com",
"username": "alice",
"password": "contraseña-en-texto-plano",
"authorization": "Bearer <TOKEN>",
"userId": 1
}
En Linux/macOS, establece el modo 600 después de escribir. En caso de 401, refresca el token una vez iniciando sesión nuevamente, luego reintenta la operación fallida una vez.
Verificar token:
curl -s https://ai-pub.pushwebly.com/api/auth/verify-token \
-H "Authorization: Bearer <TOKEN>"
Comprobaciones Previas a la Publicación
Antes de publicar:
- Confirma que el archivo existe y tiene extensión
.zip. - Confirma que el zip contiene
index.htmloindex.htm. - Si el zip tiene directorios anidados, confirma que se puede localizar el archivo de entrada.
- Confirma que el nombre del proyecto no está vacío.
- Confirma que hay un token válido disponible.
Operaciones HTTP
Publicar Proyecto
Público:
curl -s -X POST https://ai-pub.pushwebly.com/api/projects/publish \
-H "Authorization: Bearer <TOKEN>" \
-F "project_name=demo" \
-F "[email protected]"
Privado con contraseña personalizada opcional:
curl -s -X POST https://ai-pub.pushwebly.com/api/projects/publish \
-H "Authorization: Bearer <TOKEN>" \
-F "project_name=demo" \
-F "[email protected]" \
-F "visibility=private" \
-F "access_password=a1b2c3"
Para aplicaciones privadas, omite access_password para que el backend genere una contraseña.
Siempre comunica al usuario el accessPassword final de la respuesta.
Listar Proyectos
curl -s https://ai-pub.pushwebly.com/api/projects/my \
-H "Authorization: Bearer <TOKEN>"
Cambiar Visibilidad (pública <-> privada)
Alterna una aplicación ya publicada entre pública y privada. La entrada es la URL de la aplicación; el backend analiza el identificador de la aplicación a partir de ella y verifica que la aplicación pertenezca al usuario actual — solo puedes cambiar tus propias aplicaciones, no las de otros.
curl -s -X PATCH https://ai-pub.pushwebly.com/api/projects/visibility \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d @visibility.json
Escribe visibility.json (a privado):
{"url":"https://ai-pub.pushwebly.com/play/aB3xYz/","visibility":"private","accessPassword":"a1b2c3"}
O a público (no se necesita contraseña; la contraseña antigua se elimina):
{"url":"https://ai-pub.pushwebly.com/play/aB3xYz/","visibility":"public"}
accessPassword es opcional y solo se usa al cambiar a privado (6 dígitos o letras; se genera automáticamente si se omite). La respuesta data incluye el visibility final, url y, cuando es privado, el accessPassword. Comunica la URL y la contraseña de una aplicación privada por separado, nunca con ?pwd=. Si la aplicación no se encuentra, ya ha sido eliminada o pertenece a otro usuario, indica la razón concreta y que solo tus propias aplicaciones pueden ser modificadas.
Construir APK para un Proyecto Existente
curl -s -X POST https://ai-pub.pushwebly.com/api/apk/build \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d @build-apk.json
Escribe build-apk.json como:
{"projectId":12}
Usa data.apkUrl de la respuesta como la URL de descarga del APK.
Publicar y Construir APK
Esta es la operación recomendada cuando el usuario desea una aplicación Android instalable.
curl -s -X POST https://ai-pub.pushwebly.com/api/apk/publish-and-build \
-H "Authorization: Bearer <TOKEN>" \
-F "project_name=airplane-war" \
-F "[email protected]"
Para una aplicación privada, agrega:
-F "visibility=private" -F "access_password=a1b2c3"
Omite access_password para que se genere automáticamente.
Los campos de respuesta esperados pueden incluir:
{
"gameId": 12,
"projectName": "airplane-war",
"playUrl": "https://ai-pub.pushwebly.com/play/aB3xYz/",
"status": "enabled",
"apkUrl": "https://ai-pub.pushwebly.com/api/apk/download/airplane-war_aB3xYz.apk",
"apkFileNa
...
[truncado para traducción]