🦆 Duckduki - Documentação Completa

Assistente Desktop Inteligente com IA Generativa Multiplataforma

O que é o Duckduki?

O Duckduki é um assistente desktop multiplataforma (Windows, macOS, Linux) que utiliza inteligência artificial generativa para maximizar sua produtividade. Integra-se com múltiplos provedores de IA (Groq, OpenAI, Google Gemini) oferecendo análise de código, automação de tarefas, monitoramento inteligente e muito mais.

🌟 Características Principais

📦 Instalação Completa

🔧 Requisitos do Sistema

# Ubuntu/Debian
sudo apt update
sudo apt install libsecret-1-dev libxss1 libgconf-2-4

# Fedora/RHEL
sudo dnf install libsecret-devel libXScrnSaver GConf2

# Arch Linux
sudo pacman -S libsecret libxss gconf

🚀 Instalação Rápida

# 1. Clonar repositório
git clone https://github.com/seu-usuario/duckduki.git
cd duckduki

# 2. Setup automático (instala deps + configura ambiente)
npm run setup

# 3. Desenvolvimento
npm run dev

# 4. Build para produção
npm run build

# 5. Distribuição
npm run dist

🔑 Configuração de API Keys

Após a instalação, você precisará configurar pelo menos um provedor de IA:

1. Groq (Recomendado): console.groq.com - Acesso gratuito, velocidade ultra-rápida
2. OpenAI: platform.openai.com - Modelos GPT-4
3. Google AI: aistudio.google.com - Gemini models

📦 Scripts Disponíveis

⚙️ Configuração Avançada

🤖 Provedores de IA Suportados

🚀 Groq (Recomendado)

# Configuração
1. Acesse: https://console.groq.com
2. Criar conta gratuita
3. Gerar API Key
4. Colar no Duckduki > Configurações > IA > Groq

🧠 OpenAI

🌟 Google Gemini

📧 Configuração de Email (IMAP)

Gmail

1. Ative a verificação em 2 etapas na conta Google
2. Gere uma "Senha de app" específica para Duckduki
3. Use essa senha no campo "Senha" do Duckduki
4. Servidor: imap.gmail.com:993 (SSL)

Outlook/Hotmail

1. Use suas credenciais normais
2. Certifique-se que IMAP está habilitado
3. Servidor: outlook.office365.com:993 (SSL)

🔗 Integração Google Services

Para usar Calendar e Tasks do Google:

1. Acesse Google Cloud Console
2. Crie um projeto ou use existente
3. Ative APIs: Calendar API, Tasks API
4. Crie credenciais OAuth 2.0
5. Configure no Duckduki > Configurações > Google

🎯 Guia Completo de Uso

🚀 Atalhos Globais

💬 Comandos de IA e Automação

📧 Gestão de Email

👨‍💻 Desenvolvimento

📅 Produtividade

💡 Criatividade e Pesquisa

🎙️ Comandos por Voz

O Duckduki suporta entrada por voz em português brasileiro:

1. Clique no ícone do microfone 🎤
2. Fale seu comando naturalmente
3. Clique novamente para parar a gravação
4. O comando será processado automaticamente

🔧 Ferramentas Integradas (AI Tools)

📋 Gestão de Tarefas

• Análise Inteligente: IA detecta urgência e prioridade
• Sistema de Prioridades: 🔴 Crítica, 🟠 Alta, 🟡 Média, 🟢 Baixa
• Filtros Avançados: Por status, prioridade, categoria
• Sincronização: Google Tasks integration

📅 Calendar Management

• Criação de Eventos: Linguagem natural → Calendar
• Análise de Conflitos: Detecção automática de sobreposições
• Sugestões de Horários: Based em padrões de uso
• Resumos Inteligentes: Overview diário/semanal

💻 System Monitoring

• Status de Sistema: CPU, RAM, processos
• Detecção de Apps: Monitora aplicação ativa
• Sugestões Contextuais: Based no app em uso
• Performance Alerts: Avisos de alta utilização

🔧 API Reference & Arquitetura

🏗️ Arquitetura do Sistema

🤖 AI Tools Framework

Email Tools

getEmailSummary()
  ↳ Conecta via IMAP
  ↳ Analisa emails recentes  
  ↳ Gera resumo inteligente com IA
  ↳ Retorna: { summary, priority_emails, stats }

Task Management Tools

addTask(description)
  ↳ Análise de linguagem natural
  ↳ Extrai: urgência, facilidade, categoria
  ↳ Define prioridade automática
  ↳ Salva no banco local + Google Tasks
  
getTasks(status?, priority?)
  ↳ Filtros opcionais
  ↳ Retorna tarefas formatadas
  ↳ Incluí estatísticas e insights

Google Integration Tools

createCalendarEvent(title, start, end, description?)
  ↳ OAuth2 authentication
  ↳ Conflict detection
  ↳ Calendar integration
  
getGoogleDayOverview()
  ↳ Combina Calendar + Tasks
  ↳ Análise de carga de trabalho
  ↳ Sugestões de otimização

System Monitoring Tools

getSystemStatus()
  ↳ CPU, RAM, active processes
  ↳ Active window detection
  ↳ Performance insights
  
analyzeCurrentCode()
  ↳ Detecta projeto ativo
  ↳ Analisa código no editor
  ↳ Sugestões de melhorias

🔌 Extensibilidade

Criando Novas Ferramentas

// Exemplo: Nova ferramenta customizada
class CustomTool {
  async execute(parameters) {
    // Lógica da ferramenta
    return { success: true, data: result };
  }
  
  getDefinition() {
    return {
      name: 'custom_tool',
      description: 'Descrição da ferramenta',
      parameters: {
        // Schema Zod para validação
      }
    };
  }
}

Registrando Ferramentas

// Em AIToolsService
this.tools.set('custom_tool', new CustomTool());

// Schema para IA
tools: {
  custom_tool: {
    description: 'Executa função customizada',
    parameters: z.object({
      input: z.string()
    })
  }
}

📊 Storage & Data

Electron Store (Configurações)

• Configurações de UI e preferências
• Estado da aplicação
• Cache de dados não sensíveis

Keychain/Keytar (Chaves Seguras)

• API keys dos provedores de IA
• Credenciais de email
• Tokens OAuth

Knowledge Base (SQLite)

• Histórico de conversas
• Notas e documentação
• Cache de contexto

🔧 Troubleshooting Avançado

🚨 Problemas Críticos

❌ Aplicativo não Inicia

# 1. Limpar cache e dependências
rm -rf node_modules package-lock.json
npm install

# 2. Rebuild nativo modules
npm run rebuild

# 3. Verificar compatibilidade Electron
npm ls electron

🔑 API Keys não Salvam

# Instalar libsecret
sudo apt install libsecret-1-dev  # Ubuntu/Debian
sudo dnf install libsecret-devel  # Fedora
sudo pacman -S libsecret          # Arch

# Verificar keyring
gnome-keyring-daemon --version

# Verificar Keychain Access
security find-generic-password -a "duckduki"

# Reset keychain se necessário
security delete-generic-password -a "duckduki"

# Verificar Windows Credential Manager
cmdkey /list | findstr "duckduki"

# Executar como administrador se necessário

⚠️ Problemas de Conectividade

🌐 Erro de API Groq/OpenAI

# Testar chave Groq
curl -H "Authorization: Bearer SEU_KEY" \
     https://api.groq.com/openai/v1/models

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

📧 Problemas de Email IMAP

🐛 Problemas de Performance

💻 Alto Uso de CPU/RAM

# Monitorar processos Electron
ps aux | grep -i electron
top -p $(pgrep -f duckduki)

# Windows
tasklist | findstr electron

🔄 Interface Travando

🔧 Ferramentas de Debug

📊 Logs do Sistema

# Localização dos logs
# Linux: ~/.config/duckduki/logs/
# macOS: ~/Library/Logs/duckduki/
# Windows: %APPDATA%/duckduki/logs/

# Executar com debug verbose
DEBUG=* npm run dev

# Logs específicos
DEBUG=duckduki:* npm run dev

🔍 Modo Debug Avançado

# Habilitar DevTools por padrão
export ELECTRON_ENABLE_DEVTOOLS=1

# Desabilitar segurança para debug
export ELECTRON_DISABLE_SECURITY_WARNINGS=1

# Debug específico de módulos
export DEBUG=ai-tools,email-service,groq-client

📞 Suporte

👨‍💻 Guia de Desenvolvimento

🏗️ Estrutura do Projeto

duckduki/
├── src/
│   ├── main/                     # Processo principal (Electron)
│   │   ├── index.ts              # Entry point e configuração IPC
│   │   ├── aiManager.ts          # Orquestrador de IA
│   │   ├── aiProviders/          # Clientes de IA (Groq, OpenAI, Google)
│   │   ├── aiTools/              # Ferramentas integradas
│   │   ├── aiToolsService.ts     # Coordenador de ferramentas
│   │   ├── securityManager.ts    # Gestão segura de chaves
│   │   ├── knowledgeService.ts   # Base de conhecimento
│   │   ├── emailService.ts       # Integração IMAP
│   │   ├── processMonitor.ts     # Monitoramento de sistema
│   │   └── deployService.ts      # Automação de builds
│   ├── renderer/                 # Interface React
│   │   ├── App.tsx               # Componente principal
│   │   ├── components/           # Componentes UI
│   │   ├── contexts/             # Context providers
│   │   ├── settings/             # Painel de configurações
│   │   └── widgets/              # Widgets especializados
│   └── preload.ts                # Bridge segura IPC
├── assets/                       # Recursos estáticos
├── docs/                         # Documentação
└── release/                      # Builds de distribuição

🔧 Setup de Desenvolvimento

# 1. Fork e clone
git clone https://github.com/seu-usuario/duckduki.git
cd duckduki

# 2. Instalar dependências
npm install

# 3. Setup ambiente de desenvolvimento
npm run setup

# 4. Executar em modo dev (hot reload)
npm run dev

# 5. Build para teste
npm run build

# 6. Rodar testes
npm test

🎯 Contribuindo

🐛 Reportando Bugs

1. Verificar issues existentes
2. Usar template de bug report
3. Incluir logs e informações do sistema
4. Passos claros para reproduzir

✨ Novos Recursos

1. Abrir discussion para feedback
2. Implementar com testes
3. Documentar na docs/
4. Seguir padrões de código existentes

🔧 Adicionando Novas AI Tools

// 1. Criar nova tool em src/main/aiTools/
export class NovaFerramenta {
  async execute(params: any) {
    // Lógica da ferramenta
    return { success: true, data: resultado };
  }
  
  getDefinition() {
    return {
      name: 'nova_ferramenta',
      description: 'Descrição da ferramenta',
      parameters: {
        type: 'object',
        properties: {
          input: { type: 'string' }
        }
      }
    };
  }
}

// 2. Registrar em AIToolsService
import { NovaFerramenta } from './aiTools/novaFerramenta';

// Em constructor:
this.novaFerramenta = new NovaFerramenta();

// Em processWithToolsStream:
nova_ferramenta: {
  description: 'Executa nova funcionalidade',
  parameters: z.object({
    input: z.string()
  }),
  execute: async ({ input }) => {
    const result = await this.novaFerramenta.execute({ input });
    return result.success ? `✅ ${result.data}` : `❌ Erro`;
  }
}

🧪 Testing

# Testes unitários
npm run test:unit

# Testes de integração
npm run test:integration

# Test coverage
npm run test:coverage

# Testar build em todas as plataformas
npm run test:build

📋 Changelog

v2.1.0 (Current)

v2.0.0

v1.5.0

v1.0.0