Guia de Solução de Problemas do Synkra AIOX

🌐 EN | PT | ES

Este guia abrangente ajuda você a diagnosticar e resolver problemas comuns com o Synkra AIOX.

Índice

Diagnóstico Rápido
Problemas de Instalação
Problemas com o Meta-Agent
Problemas com a Camada de Memória
Problemas de Performance
Problemas de API e Integração
Erros de Segurança e Permissão
Problemas Específicos de Plataforma
Solução de Problemas Avançada
Obtendo Ajuda

Diagnóstico Rápido

Executar o Doctor do Sistema

Sempre comece com o diagnóstico integrado:

# Diagnóstico básico
npx aiox-core doctor

# Corrigir automaticamente problemas comuns
npx aiox-core doctor --fix

# Saída detalhada
npx aiox-core doctor --verbose

# Verificar componente específico
npx aiox-core doctor --component memory-layer

Correções Rápidas Comuns

# Limpar todos os caches
*memory clear-cache

# Reconstruir índice de memória
*memory rebuild

# Resetar configuração
*config --reset

# Atualizar para última versão
npx aiox-core update

Problemas de Instalação

Problema: Comando NPX não encontrado

Sintomas:

bash: npx: command not found

Solução:

# Verificar versão do npm
npm --version

# Se npm < 5.2, instalar npx globalmente
npm install -g npx

# Ou usar npm diretamente
npm exec aiox-core init my-project

Problema: Instalação falha com erros de permissão

Sintomas:

Error: EACCES: permission denied

Soluções:

Opção 1: Corrigir permissões do npm (Recomendado)

# Criar diretório npm
mkdir ~/.npm-global

# Configurar npm
npm config set prefix '~/.npm-global'

# Adicionar ao PATH (adicionar ao ~/.bashrc ou ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH

# Recarregar shell
source ~/.bashrc

Opção 2: Usar diretório diferente

# Instalar no diretório do usuário
cd ~
npx aiox-core init my-project

Problema: Erro de versão do Node.js

Sintomas:

Error: Node.js version 18.0.0 or higher required

Solução:

# Verificar versão atual
node --version

# Atualizar Node.js
# macOS (usando Homebrew)
brew upgrade node

# Windows (usando Chocolatey)
choco upgrade nodejs

# Linux (usando NodeSource)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Ou usar nvm (Node Version Manager)
nvm install 18
nvm use 18

Problema: Instalação trava ou expira

Sintomas:

Instalação travada em "Installing dependencies..."
Erros de timeout de rede

Soluções:

# Usar registro diferente
npm config set registry https://registry.npmjs.org/

# Limpar cache do npm
npm cache clean --force

# Aumentar timeout
npm config set fetch-timeout 60000

# Pular instalação de dependências
npx aiox-core init my-project --skip-install

# Então instalar manualmente
cd my-project
npm install --verbose

Problema: Erro de espaço em disco

Sintomas:

Error: ENOSPC: no space left on device

Solução:

# Verificar espaço disponível
df -h

# Limpar cache do npm
npm cache clean --force

# Remover node_modules antigos
find . -name "node_modules" -type d -prune -exec rm -rf '{}' +

# Limpar arquivos temporários
# macOS/Linux
rm -rf /tmp/npm-*

# Windows
rmdir /s %TEMP%\npm-*

Problemas com o Meta-Agent

Problema: Meta-agent não inicia

Sintomas:

Error: Failed to initialize meta-agent

Soluções:

Verificar configuração:

# Verificar se config existe
ls -la .aiox/config.json

# Validar configuração
npx aiox-core doctor --component config

# Resetar se corrompido
rm .aiox/config.json
npx aiox-core doctor --fix

Verificar dependências:

# Reinstalar dependências principais
npm install

# Verificar arquivos de agentes
ls -la agents/

Verificar ambiente:

# Verificar variáveis de ambiente
cat .env

# Garantir que chaves de API estão definidas
echo "OPENAI_API_KEY=your-key" >> .env

Problema: Comandos não reconhecidos

Sintomas:

Unknown command: *create-agent

Soluções:

Verificar ativação do agente:

# Listar agentes ativos
*list-agents --active

# Ativar meta-agent
*activate meta-agent

# Verificar disponibilidade de comandos
*help

Verificar sintaxe do comando:

# Sintaxe correta usa asterisco
*create-agent my-agent  # ✓ Correto
create-agent my-agent   # ✗ Errado

Recarregar agentes:

# Recarregar todos os agentes
*reload-agents

# Ou reiniciar meta-agent
exit
npx aiox-core

Problema: Criação de agente falha

Sintomas:

Error: Failed to create agent

Soluções:

Verificar permissões:

# Verificar permissões de escrita
ls -la agents/

# Corrigir permissões
chmod 755 agents/

Validar nome do agente:

# Nomes válidos: minúsculas, hífens
*create-agent my-agent      # ✓ Bom
*create-agent MyAgent       # ✗ Ruim (maiúsculas)
*create-agent my_agent      # ✗ Ruim (underscore)
*create-agent my-agent-2    # ✓ Bom

Verificar duplicatas:

# Listar agentes existentes
*list-agents

# Remover duplicata se existir
rm agents/duplicate-agent.yaml

Problemas com a Camada de Memória

Problema: Busca de memória não retorna resultados

Sintomas:

Busca semântica não encontra nada
Reconhecimento de padrões falha

Soluções:

Reconstruir índice de memória:

# Limpar e reconstruir
*memory clear-cache
*memory rebuild --verbose

# Aguardar indexação
# Verificar progresso
*memory status

Verificar configuração de memória:

# Verificar config
cat .aiox/memory-config.json

# Resetar para padrões
*memory reset-config

Verificar integridade do índice:

# Executar diagnóstico de memória
*memory diagnose

# Reparar se necessário
*memory repair

Problema: Camada de memória usando muita RAM

Sintomas:

Alto uso de memória
Lentidão do sistema

Soluções:

Ajustar configurações de memória:

// Editar .aiox/memory-config.json
{
  "maxDocuments": 5000,      // Reduzir de 10000
  "chunkSize": 256,          // Reduzir de 512
  "cacheSize": 100,          // Reduzir de 1000
  "enableCompression": true  // Habilitar compressão
}

Limpar dados antigos:

# Remover entradas antigas
*memory prune --older-than "30 days"

# Otimizar armazenamento
*memory optimize

Usar limites de memória:

# Definir limite de memória
export NODE_OPTIONS="--max-old-space-size=1024"

# Executar com memória limitada
npx aiox-core

Problema: Erros do LlamaIndex

Sintomas:

Error: LlamaIndex initialization failed

Soluções:

Verificar chaves de API:

# Verificar chave OpenAI para embeddings
echo $OPENAI_API_KEY

# Testar acesso à API
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Usar embeddings locais:

// .aiox/memory-config.json
{
  "embedModel": "local",
  "localModelPath": "./models/embeddings"
}

Reinstalar LlamaIndex:

npm uninstall llamaindex
npm install llamaindex@latest

Problemas de Performance

Problema: Execução lenta de comandos

Sintomas:

Comandos levam > 5 segundos
Interface parece lenta

Soluções:

Perfilar performance:

# Habilitar profiling
*debug enable --profile

# Executar comando lento
*analyze-framework

# Ver perfil
*debug show-profile

Otimizar configuração:

// .aiox/config.json
{
  "performance": {
    "enableCache": true,
    "parallelOperations": 4,
    "lazyLoading": true,
    "indexUpdateFrequency": "hourly"
  }
}

Limpar recursos:

# Limpar caches
*cache clear --all

# Remover agentes não utilizados
*cleanup-agents

# Otimizar banco de dados
*optimize-db

Problema: Alto uso de CPU

Sintomas:

Barulho de ventilador
Lentidão do sistema
Alta CPU no gerenciador de tarefas

Soluções:

Limitar operações concorrentes:

# Definir limites de operação
*config --set performance.maxConcurrent 2
*config --set performance.cpuThreshold 80

Desabilitar recursos em tempo real:

# Desabilitar indexação em tempo real
*config --set memory.realTimeIndex false

# Usar processamento em lote
*config --set performance.batchMode true

Verificar processos descontrolados:

# Listar todos os processos
*debug processes

# Matar processo travado
*debug kill-process <pid>

Problemas de API e Integração

Problema: Chave de API não funciona

Sintomas:

Error: Invalid API key
Error: 401 Unauthorized

Soluções:

Verificar formato da chave de API:

# OpenAI
echo $OPENAI_API_KEY
# Deve começar com "sk-"

# Anthropic
echo $ANTHROPIC_API_KEY
# Deve começar com "sk-ant-"

Testar API diretamente:

# Testar OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# Testar Anthropic
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

Verificar limites de taxa:

# Ver uso atual
*api-status

# Mudar para provedor diferente
*config --set ai.provider anthropic

Problema: Erros de conexão de rede

Sintomas:

Error: ECONNREFUSED
Error: getaddrinfo ENOTFOUND

Soluções:

Verificar configurações de proxy:

# Proxy corporativo
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# Testar conexão
curl -I https://api.openai.com

Usar modo offline:

# Habilitar modo offline
*config --set offline true

# Usar modelos locais
*config --set ai.provider local

Configurar timeouts:

# Aumentar timeouts
*config --set network.timeout 30000
*config --set network.retries 3

Erros de Segurança e Permissão

Problema: Erros de permissão negada

Sintomas:

Error: EACCES: permission denied
Error: Cannot write to file

Soluções:

Corrigir permissões de arquivo:

# Corrigir permissões do projeto
chmod -R 755 .
chmod 600 .env

# Corrigir diretórios específicos
chmod 755 agents/ tasks/ workflows/

Verificar propriedade de arquivo:

# Ver propriedade
ls -la

# Corrigir propriedade (Linux/macOS)
sudo chown -R $(whoami) .

Executar com usuário correto:

# Não usar sudo para npm
npm install  # ✓ Bom
sudo npm install  # ✗ Ruim

Problema: Dados sensíveis expostos

Sintomas:

Chaves de API visíveis em logs
Credenciais em mensagens de erro

Soluções:

Proteger variáveis de ambiente:

# Verificar .gitignore
cat .gitignore | grep .env

# Adicionar se ausente
echo ".env" >> .gitignore
echo ".aiox/logs/" >> .gitignore

Habilitar modo seguro:

# Habilitar recursos de segurança
*config --set security.maskSensitive true
*config --set security.secureLogging true

Rotacionar chaves comprometidas:

# Gerar novas chaves dos provedores
# Atualizar arquivo .env
# Limpar logs
rm -rf .aiox/logs/*

Problemas Específicos de Plataforma

Problemas do Windows

Problema: Erros de caminho muito longo

Error: ENAMETOOLONG

Solução:

# Habilitar caminhos longos (Executar como Administrador)
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

# Ou usar caminhos mais curtos
cd C:\
npx aiox-core init myapp

Problema: Scripts desabilitados

Error: Scripts is disabled on this system

Solução:

# Executar como Administrador
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problemas do macOS

Problema: Command Line Tools ausentes

Error: xcrun: error: invalid active developer path

Solução:

# Instalar Xcode Command Line Tools
xcode-select --install

Problema: Gatekeeper bloqueia execução

Error: "aiox-core" cannot be opened

Solução:

# Permitir execução
sudo spctl --master-disable

# Ou remover quarentena
xattr -d com.apple.quarantine /usr/local/bin/aiox-core

Problemas do Linux

Problema: Dependências ausentes

Error: libssl.so.1.1: cannot open shared object file

Solução:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install libssl-dev

# RHEL/CentOS
sudo yum install openssl-devel

# Arch
sudo pacman -S openssl

Solução de Problemas Avançada

Habilitar Modo Debug

# Saída de debug completa
export DEBUG=aiox:*
npx aiox-core

# Componentes específicos
export DEBUG=aiox:memory,aiox:agent

Analisar Logs

# Ver logs recentes
tail -f .aiox/logs/aiox.log

# Buscar por erros
grep -i error .aiox/logs/*.log

# Ver logs estruturados
*logs --format json --level error

Criar Relatório de Diagnóstico

# Gerar diagnóstico completo
npx aiox-core doctor --report diagnostic.json

# Incluir informações do sistema
npx aiox-core info --detailed >> diagnostic.json

# Criar pacote de suporte
tar -czf aiox-support.tar.gz .aiox/logs diagnostic.json

Perfilamento de Performance

// Habilitar profiling na config
{
  "debug": {
    "profiling": true,
    "profileOutput": ".aiox/profiles/"
  }
}

# Analisar perfil
*debug analyze-profile .aiox/profiles/latest.cpuprofile

Análise de Dump de Memória

# Criar snapshot de heap
*debug heap-snapshot

# Analisar uso de memória
*debug memory-report

# Encontrar vazamentos de memória
*debug find-leaks

Obtendo Ajuda

Antes de Pedir Ajuda

Execute diagnósticos:

npx aiox-core doctor --verbose > diagnostic.log

Colete informações:
- Versão do Node.js: node --version
- Versão do NPM: npm --version
- SO e versão: uname -a ou ver
- Versão do AIOX: npx aiox-core version
Verifique issues existentes:
- GitHub Issues
- Discussions

Suporte da Comunidade

Discord: Entre no nosso servidor
- #help - Ajuda geral
- #bugs - Relatos de bugs
- #meta-agent - Específico do meta-agent
GitHub Discussions: Perguntas técnicas e solicitações de funcionalidades
Stack Overflow: Marque perguntas com aiox-core

Reportando Bugs

Crie relatórios de bug detalhados:

## Ambiente
- SO: macOS 13.0
- Node: 18.17.0
- AIOX: 1.0.0

## Passos para Reproduzir
1. Executar `npx aiox-core init test`
2. Selecionar template "enterprise"
3. Erro ocorre durante instalação

## Comportamento Esperado
Instalação completa com sucesso

## Comportamento Real
Error: Cannot find module 'inquirer'

## Logs
[Anexar diagnostic.log]

## Contexto Adicional
Usando proxy corporativo

Recuperação de Emergência

Se tudo mais falhar:

# Fazer backup do estado atual
cp -r .aiox .aiox.backup

# Reset completo
rm -rf .aiox node_modules package-lock.json
npm cache clean --force

# Instalação limpa
npm install
npx aiox-core doctor --fix

# Restaurar dados se necessário
cp .aiox.backup/memory.db .aiox/

Lembre-se: A maioria dos problemas pode ser resolvida com:

npx aiox-core doctor --fix
Limpando caches
Atualizando para a última versão
Verificando permissões

Em caso de dúvida, a comunidade está aqui para ajudar!

FilesExpand file tree

troubleshooting.md

Latest commit

History

troubleshooting.md

File metadata and controls

Guia de Solução de Problemas do Synkra AIOX

Índice

Diagnóstico Rápido

Executar o Doctor do Sistema

Correções Rápidas Comuns

Problemas de Instalação

Problema: Comando NPX não encontrado

Problema: Instalação falha com erros de permissão

Problema: Erro de versão do Node.js

Problema: Instalação trava ou expira

Problema: Erro de espaço em disco

Problemas com o Meta-Agent

Problema: Meta-agent não inicia

Problema: Comandos não reconhecidos

Problema: Criação de agente falha

Problemas com a Camada de Memória

Problema: Busca de memória não retorna resultados

Problema: Camada de memória usando muita RAM

Problema: Erros do LlamaIndex

Problemas de Performance

Problema: Execução lenta de comandos

Problema: Alto uso de CPU

Problemas de API e Integração

Problema: Chave de API não funciona

Problema: Erros de conexão de rede

Erros de Segurança e Permissão

Problema: Erros de permissão negada

Problema: Dados sensíveis expostos

Problemas Específicos de Plataforma

Problemas do Windows

Problema: Erros de caminho muito longo

Problema: Scripts desabilitados

Problemas do macOS

Problema: Command Line Tools ausentes

Problema: Gatekeeper bloqueia execução

Problemas do Linux

Problema: Dependências ausentes

Solução de Problemas Avançada

Habilitar Modo Debug

Analisar Logs

Criar Relatório de Diagnóstico

Perfilamento de Performance

Análise de Dump de Memória

Obtendo Ajuda

Antes de Pedir Ajuda

Suporte da Comunidade

Reportando Bugs

Recuperação de Emergência