UltraGXSolução de problemas e perguntas frequentes
Instalação e inicialização
O Windows mostra "O Windows protegeu o computador". É o SmartScreen com um instalador que ainda tem pouca reputação. Clique em Mais informações → Executar assim mesmo. Se a sua organização bloquear essa opção, peça ao suporte técnico que libere o instalador.
A janela do UltraGX abre em branco ou não abre (Windows). O runtime Microsoft Edge WebView2 está faltando ou danificado. Instale-o a partir da página da Microsoft ("WebView2 Runtime", instalador Evergreen) e abra o UltraGX de novo. O instalador do UltraGX o adiciona automaticamente.
O aplicativo não abre no Linux. Execute-o em um terminal (ultragx ou a AppImage) para ver o erro. Se ele mencionar libwebkit2gtk, instale libwebkit2gtk-4.1-0 (Debian/Ubuntu) ou webkit2gtk4.1 (Fedora).
O macOS diz que o UltraGX "não pode ser aberto". A versão para macOS não é assinada com um Developer ID da Apple. Dê dois cliques em Allow UltraGX.command na imagem de disco depois de arrastar o UltraGX para Aplicativos (ou execute xattr -cr /Applications/UltraGX.app no Terminal), ou autorize-o em Ajustes do Sistema → Privacidade e Segurança → Abrir Mesmo Assim.
Licença
Aparece "Não foi possível contatar o serviço de licenças". O computador não alcança https://licenses.ultra-gx.com. Verifique a conexão com a internet; em redes corporativas, peça que liberem HTTPS para esse domínio (também pelo proxy). As demais mensagens do registro estão explicadas em Primeiro início e licença.
A execução termina com "A valid license file (ultragx.lic) is required…" ou código 3. A licença está ausente, venceu ou foi revogada. Confira Configurações → Licença. Se a demo terminou, escreva para nós para passar à edição completa.
Na demo, nenhum objeto saiu detalhado. A execução não conseguiu consultar o serviço de licenças e continuou sem amostra. O motivo está no aviso do README.md e do visualizador. Resolva a conexão e execute o pipeline de novo.
Troquei de computador. A licença fica vinculada à máquina onde foi ativada. Escreva para nós com o novo Id desta máquina para transferi-la.
Documentar uma KB
A fonte "live" aparece desabilitada. Configurações → Ambiente mostra o motivo: Conector GeneXus: não encontrado (Linux, macOS ou uma cópia sem conector) ou GeneXus instalado: nenhum detectado. Nesses casos, exporte a KB para XPZ na máquina onde está o GeneXus.
A exportação ao vivo não avança ou falha ao abrir a KB. A KB está aberta na IDE do GeneXus ou em outra ferramenta: feche-a e execute de novo. Se o log repetir o mesmo objeto por vários minutos, o conector continua extraindo um objeto grande; em KBs de milhares de objetos a exportação pode levar mais de uma hora.
Escolhi a versão errada do GeneXus. Deixe auto (a partir da KB). Force uma instalação só se a KB abrir com uma versão diferente da que é detectada.
Alguns SDTs ou transações aparecem sem estrutura. Se a KB foi documentada com uma versão anterior à 0.2.5, execute-a de novo com a versão atual (com a fonte live, também a exportação).
A aceitação terminou em warning. A documentação foi gerada completa; o controle de qualidade encontrou algo a revisar. O detalhe está em Aceitação, no visualizador. failed indica um problema que convém relatar.
O resumo avisa library_flag_suspect. Quase todos os objetos foram marcados como biblioteca, o que indica um export que não separou bem os objetos próprios dos referenciados. Exporte a KB de novo (com o conector atual, se for ao vivo).
Os caminhos ou os nomes de pasta são muito longos (Windows). A saída replica os módulos e pastas da KB. Use uma pasta de saída curta, como D:\ultragx.
A pasta de saída está no OneDrive / Dropbox e tudo fica lento. A sincronização processa milhares de arquivos ao mesmo tempo. Use uma pasta fora das pastas sincronizadas.
Narrativa
| Mensagem no log | Causa | Solução |
|---|---|---|
401, 403, invalid API key | a chave da conexão não é válida ou não tem permissão para esse modelo | confira a API key da conexão |
404, model not found | o nome do modelo não existe nesse provedor | corrija Modelo com um nome do catálogo do provedor |
429, quota, rate limit | limite de uso do provedor | o motor tenta de novo sozinho; se persistir, reduza Concorrência ou confira a cota da sua conta |
| connection refused com um modelo local | o servidor local não está rodando ou a URL não é a correta | inicie o Ollama / LM Studio e verifique a URL base |
muitos degraded | o modelo cita nomes que não existem | teste um modelo mais capaz; com modelos locais, aumente o tamanho do contexto |
A prosa não aparece no visualizador. Clique em Recarregar. Só os objetos em ok são publicados.
Onde olhar
| O quê | Onde |
|---|---|
| Log de uma execução | Tarefas → Log enquanto o aplicativo está aberto |
| Resultado da execução | run_summary.json e acceptance_report.md na pasta do projeto |
| Status da narrativa | narrative/checkpoint.json e um JSON por objeto em narrative/ |
| Configurações e licença | %APPDATA%\UltraGX (Windows) ou ~/.config/UltraGX (Linux e macOS) |
Suporte
Escreva para contact@ultra-gx.com com:
- a versão do UltraGX (Configurações → Ambiente → Aplicativo) e o sistema operacional;
- a mensagem de erro ou o final do log da tarefa;
run_summary.jsoneacceptance_report.mddo projeto, se o problema for de uma execução.
Não envie o XPZ, o código da KB nem a pasta de saída completa, a menos que pedirmos e a sua organização autorize.
Perguntas frequentes
O UltraGX modifica a minha KB? Não. Ele só lê: o conector não tem nenhum caminho de escrita e, com um XPZ, nem sequer toca na KB.
Preciso ter o GeneXus instalado? Só para a fonte live. Com um XPZ ou um export de texto, não.
Quais versões do GeneXus são suportadas? Da 7.5 à 18 por XPZ/XML; do X Evolution 1 ao 18 ao vivo.
Posso documentar a mesma KB muitas vezes? Sim. Com o mesmo nome de projeto, ela é regenerada na mesma pasta e as notas e a narrativa são preservadas. Na demo, a amostra de 25 objetos é sempre a mesma.
Posso compartilhar a documentação? Sim: a pasta do projeto é autocontida e o visualizador funciona sem conexão. Lembre-se de que ela contém o código da KB.
O código-fonte é enviado para algum lugar? Só se você usar a narrativa com um provedor na nuvem, e para esse provedor. Veja Narrativa com IA.