Skill de Publicação
Publique projetos frontend HTML na plataforma de publicação e, opcionalmente, empacote-os como APKs Android.
URL da Plataforma:
https://pushwebly.com
Use "projeto" nas mensagens voltadas ao usuário. Os caminhos canônicos da API são
/api/projects e os nomes canônicos das ferramentas são projeto_*. Apelidos obsoletos game_*
e campos de resposta gameId ainda podem aparecer; trate gameId como o id do projeto.
Regras de Execução do Codex
- Prefira ferramentas MCP
projeto_*montadas, se elas existirem no ambiente atual. - Se ferramentas MCP remotas não estiverem montadas, use as APIs HTTP com
curl. - Não exija Python. Scripts opcionais, se presentes, são para usuários CLI/CI.
- Pergunte apenas por informações genuinamente ausentes: credenciais, caminho do zip, nome do projeto, visibilidade pública/privada ou preferência de senha de acesso privado.
- Nunca escreva credenciais dentro do zip do projeto ou em um arquivo do repositório. Armazene-as apenas
no arquivo local do usuário
~/.publisher/config.jsonapós consentimento. - No Windows/PowerShell, use um arquivo JSON temporário para corpos de requisição, em vez de escapar JSON inline no shell.
Mapeamento de Intenção
| Intenção do usuário | Ação | Informação ausente para perguntar |
|---|---|---|
| Publicar, enviar, fazer upload, colocar online | Publicar projeto | caminho do zip, nome do projeto |
| Criar um aplicativo de telefone instalável, APK, pacote Android | Publicar e criar APK | caminho do zip, nome do projeto |
| Criar APK para um projeto já publicado | Criar APK | id do projeto; use a lista de projetos se necessário |
| Tornar um aplicativo privado/público, adicionar/remover senha de acesso | Alterar visibilidade | URL do aplicativo, visibilidade alvo (senha opcional quando privado) |
| Mostrar meus projetos, listar projetos publicados | Listar projetos | nenhum, se o token estiver disponível |
| Fazer login, registrar, configurar conta | Login/registro | nome de usuário e senha |
Se a intenção for ambígua, faça uma pergunta curta: "Apenas publicar, ou publicar e também criar um APK Android?"
Processo de Conversação de Publicação
Quando os usuários expressam intenções como publicar, implantar, lançar, compartilhar aplicativos, gerar links de acesso, etc., eles devem entrar neste processo.
Princípios Gerais da Máquina de Estados Finita
- Ao entrar no fluxo, primeiro execute
S-1(verificação de versão, não bloqueante), depois prossiga na ordemS0 -> S1 -> S2 -> S3 -> S4. - Não é permitido pular etapas (exceto
S-1). - Vários campos não podem ser consultados em uma única requisição. Informações que o usuário já forneceu claramente podem ser registradas, e não há necessidade de perguntar repetidamente. Quando a resposta do usuário for ambígua, faça apenas um acompanhamento para o campo atual.
- Somente após a conclusão da etapa atual podemos prosseguir para a próxima etapa.
- Se for necessário aguardar a entrada do usuário, não anexe explicações, sugestões ou prévias da próxima etapa no final da resposta.
S-1: Verificação de Versão (primeiro nó do fluxo de publicação, não bloqueante)
Ao entrar no fluxo de publicação, execute uma auto-verificação de versão antes de S0. Esta etapa NÃO faz parte das regras de bloqueio <COMPORTAMENTO-RIGOROSO>: seja qual for o resultado — mesmo que o endpoint esteja inacessível — sempre continue. Nunca interrompa a publicação devido a um problema de versão.
Passos:
-
Leia a versão local da skill: o campo
versionno frontmatter deste arquivo. -
Consulte a versão mais recente da plataforma (sem necessidade de login):
curl -s https://ai-pub.pushwebly.com/api/skill/latest-versionA resposta
datacontém:version(mais recente),downloadUrl(pacote de documentação multiplataforma, descompacte e use),downloadUrlWindows(instalador .exe para Windows) edownloadUrlMac(instalador .zip para macOS). -
Compare a
versionlocal com aversionretornada.Regra de comparação: uma versão é
major.minor.patch. Compare segmento por segmento como inteiros, da esquerda para a direita — major primeiro, depois minor, depois patch; preencha segmentos ausentes com 0 (1.1significa1.1.0). Compare como inteiros, NÃO como strings:1.10.0é maior que1.9.0(segundo segmento10 > 9); uma comparação de strings erraria isso. Exemplo ascendente:1.0.0 < 1.0.9 < 1.1.0 < 1.2.0 < 1.10.0 < 2.0.0.-
Local é mais antiga (a sequência de segmentos inteiros local é menor que a retornada): você DEVE exibir um aviso de atualização ao usuário antes de continuar, E o aviso DEVE incluir a URL de download real (isso não bloqueia a publicação, mas o aviso não pode ser omitido). Escolha a URL de download pelo SO do usuário:
- Windows → use
downloadUrlWindows - macOS → use
downloadUrlMac - SO desconhecido, ou o campo correspondente está vazio → use o
downloadUrlgenérico
Texto do aviso (exiba-o no MESMO idioma em que o usuário está conversando — chinês se escreverem chinês, inglês se inglês; não codifique um idioma; o exemplo abaixo é apenas um modelo em inglês; substitua a URL pela real selecionada; escreva a URL de download como um link Markdown clicável
[URL](URL)— NÃO a envolva em crases como código inline, ou o usuário não poderá clicar; nunca deixe um espaço reservado, nunca diga "uma nova versão existe" sem fornecer o link):Nota: uma versão mais recente da skill Publisher
<version>está disponível (você está em<local version>). Download: https://ai-pub.pushwebly.com/downloads/AI_Publisher_skill.exe (a atualização não afeta a publicação atual). - Windows → use
-
Local é igual ou mais recente: permaneça em silêncio e continue.
-
A requisição falha/timeout/não pode ser analisada: pule silenciosamente, vá direto para
S0, não exiba um erro.
-
-
Em todos os casos, prossiga para
S0em seguida. Como esta etapa apenas notifica (sem entrada, sem bloqueio), a regra "no máximo uma pergunta voltada ao usuário por resposta" não se aplica a ela — a nota de versão pode compartilhar a mesma resposta que a primeira pergunta deS0.
S0: Verificar Status da Conta
Primeiro, verifique se já existe um token/credencial local disponível.
- Se você já tiver credenciais de conta: vá para
S2. - Se não houver credenciais de conta: Entre em
S1_USERNAME. - Se não for possível verificar o status da conta: pergunte ao usuário se ele já tem uma conta de publicação.
Faça uma pergunta ao usuário:
Preciso confirmar a conta de publicação primeiro: Você já tem uma conta ou token disponível?
Resposta do usuário:
- Sim: Solicite que o usuário forneça ou confirme o token/credenciais de login, depois prossiga para
S2. - Não: Entre em
S1_USERNAME.
S1: Processo de Registro e Login
S1_USERNAME: Coletar nome de usuário registrado
Se não houver nome de usuário, pergunte apenas:
Por favor, forneça o nome de usuário a ser registrado.
Após receber o nome de usuário, registre-o como username e entre em S1_PASSWORD.
S1_PASSWORD: Coletar senha de registro
Se não houver senha, pergunte apenas:
Por favor, forneça a senha de registro.
Após receber a senha, registre-a como password e entre em S1_VALIDATE.
S1_VALIDATE: Validação Conjunta
Somente depois de ter ambos username e password é que a interface de backend pode ser chamada para validação conjunta.
Validação aprovada:
- Criar Conta
- Completar Login
- Aviso:
Registro e login bem-sucedidos - Entre em
S2
Validação falhou:
- Exiba o motivo específico do erro retornado pelo backend
- Apenas pergunte sobre o item que precisa ser corrigido
- Não termine o processo de registro
S2: Perguntar sobre a visibilidade do aplicativo
Se o status público ou privado não tiver sido claramente definido, pergunte apenas:
Este aplicativo é público? Público significa que qualquer um pode acessá-lo por meio de um link; privado requer uma senha de acesso de 6 dígitos.
Resposta do usuário:
- Público / Sim / public: Registre
visibility=public, entre emS4 - Privado / Não / private: Registre
visibility=private, entre emS3 - Incerto: Continue perguntando apenas sobre este item
S3: Senha de Acesso Privado
Se visibility=private, é necessário perguntar se deseja personalizar a senha, perguntando apenas:
Deseja personalizar uma senha de acesso de 6 dígitos? Você também pode responder "gerado pelo sistema".
Resposta do usuário:
- Fornecer senha: a verificação deve ter 6 dígitos ou letras; depois de aprovada, registre
accessPassword=<senha do usuário>e entre emS4 - Responder gerado pelo sistema / Não é necessário / Aleatório: Não passe
accessPassword, deixe o backend gerá-la e entre emS4 - Erro de formato da senha: Apenas avise sobre os requisitos de formato e peça a senha novamente
S4: Executar Lançamento
Chamar a interface de publicação só é permitido se uma das seguintes condições for atendida:
visibility=publicvisibility=privatee o usuário selecionou uma senha personalizada ou gerada pelo sistema
Parâmetros de Lançamento:
Aplicativo Público:
{
"visibility": "public"
}
Aplicativo privado, senha personalizada:
{
"visibility": "private",
"access_password": "a1b2c3"
}
Aplicativo privado, senha gerada pelo sistema:
{
"visibility": "private"
}
Padrão é public se o usuário não especificar visibilidade. Uma senha de acesso privada
deve corresponder a ^[A-Za-z0-9]{6}$; caso contrário, peça uma senha válida ou deixe o
backend gerar uma.
Tratamento de Token
Um token Bearer é necessário para todas as APIs de publicação.
Use esta ordem:
- Se o usuário forneceu um token na conversa, use-o diretamente.
- Se
~/.publisher/config.jsonexistir, leia o nome de usuário/senha armazenados e faça login novamente para renovar o token. - Caso contrário, peça nome de usuário e senha. O endpoint de login registra automaticamente novas contas.
Endpoint de login/registro:
curl -s -X POST https://ai-pub.pushwebly.com/api/auth/login-or-register \
-H "Content-Type: application/json" \
-d @login.json
Escreva login.json como:
{"username":"alice","password":"plain-text-password"}
Use data.token da resposta como:
Authorization: Bearer <TOKEN>
Exclua o arquivo de login temporário após o uso.
Arquivo de credencial local opcional:
{
"baseUrl": "https://ai-pub.pushwebly.com",
"username": "alice",
"password": "plain-text-password",
"authorization": "Bearer <TOKEN>",
"userId": 1
}
No Linux/macOS, configure o modo 600 após escrever. Em 401, renove o token uma vez fazendo
login novamente e, em seguida, repita a operação com falha uma vez.
Verificar token:
curl -s https://ai-pub.pushwebly.com/api/auth/verify-token \
-H "Authorization: Bearer <TOKEN>"
Verificações Pré-Publicação
Antes de publicar:
- Confirme que o arquivo existe e tem extensão
.zip. - Confirme que o zip contém
index.htmlouindex.htm. - Se o zip tiver diretórios aninhados, confirme que o arquivo de entrada pode ser localizado.
- Confirme que o nome do projeto não está vazio.
- Confirme que um token válido está disponível.
Operações HTTP
Publicar Projeto
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 com senha 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 aplicativos privados, omita access_password para deixar o backend gerar uma senha.
Sempre repasse ao usuário o accessPassword final da resposta.
Listar Projetos
curl -s https://ai-pub.pushwebly.com/api/projects/my \
-H "Authorization: Bearer <TOKEN>"
Alterar Visibilidade (público <-> privado)
Alternar um aplicativo já publicado entre público e privado. A entrada é a URL do aplicativo; o backend analisa o identificador do aplicativo a partir dela e verifica se o aplicativo pertence ao usuário atual — você só pode alterar seus próprios aplicativos, não os de outros.
curl -s -X PATCH https://ai-pub.pushwebly.com/api/projects/visibility \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d @visibility.json
Escreva visibility.json (para privado):
{"url":"https://ai-pub.pushwebly.com/play/aB3xYz/","visibility":"private","accessPassword":"a1b2c3"}
Ou para público (nenhuma senha necessária; a senha antiga é limpa):
{"url":"https://ai-pub.pushwebly.com/play/aB3xYz/","visibility":"public"}
accessPassword é opcional e só é usado ao alternar para privado (6 dígitos ou letras;
auto-gerado se omitido). A resposta data inclui o visibility final, url e — quando
privado — o accessPassword. Repasse a URL e a senha de um aplicativo privado
separadamente, nunca com ?pwd=. Se o aplicativo não for encontrado, já tiver sido
excluído ou pertencer a outro usuário, indique o motivo concreto e que apenas seus
próprios aplicativos podem ser alterados.
Criar APK para Projeto 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
Escreva build-apk.json como:
{"projectId":12}
Use data.apkUrl da resposta como URL de download do APK.
Publicar e Criar APK
Esta é a operação recomendada quando o usuário deseja um aplicativo Android instalável.
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 um aplicativo privado, adicione:
-F "visibility=private" -F "access_password=a1b2c3"
Omita access_password para auto-geração.
Os campos de resposta esperados podem 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",
"apkFileName": "airplane-war.apk"
}
Erros Comuns e Soluções
ZIP não encontrado / arquivo não existe
"O arquivo
/home/user/project.zipnão existe. Verifique o caminho e tente novamente."
ZIP sem index.html
"O arquivo ZIP deve conter um arquivo
index.htmlouindex.htmpara ser publicado."
Falha de validação da senha
Se o usuário forneceu uma senha que não corresponde ao padrão ^[A-Za-z0-9]{6}$:
"A senha de acesso deve ter exatamente 6 caracteres, podendo ser letras ou números. Exemplo: a1b2c3."
Se o usuário então disser "gerado pelo sistema" ou similar, reverta para a geração automática.
Atualização do aplicativo
O usuário pode publicar o mesmo project_name novamente com um novo ZIP para substituir
o aplicativo existente. O fluxo é idêntico a uma publicação inicial;
a visibilidade atual e a senha (se privado) são preservadas — não pergunte novamente
a menos que o usuário indique explicitamente que deseja alterá-las.
Erros 401 (Não Autorizado)
Na primeira ocorrência, renove o token automaticamente:
curl -s -X POST https://ai-pub.pushwebly.com/api/auth/login-or-register \
-H "Content-Type: application/json" \
-d '{"username":"<username>","password":"<password>"}'
Em caso de falha na renovação, informe ao usuário e peça que faça login novamente.
Timeout de Rede
Se uma requisição falhar por timeout:
"O servidor não respondeu a tempo. Verifique sua conexão de rede e tente novamente."
Erro 500 do Servidor
Se o servidor retornar um erro 500:
"Ocorreu um erro interno no servidor. Tente novamente mais tarde."
Notas Adicionais
- A URL base da API é
https://ai-pub.pushwebly.com. Se a variável de ambientePUBLISHER_API_BASE_URLestiver definida, use-a em vez disso. - A interface de upload aceita arquivos ZIP de até 50 MB.
- Os nomes dos projetos devem conter apenas letras, números, hífens e sublinhados.
- Os projetos públicos são acessíveis sem autenticação. Projetos privados requerem a senha de acesso para visualizar.