oracle

O que oracle faz?

O Oracle agrupa um prompt + arquivos selecionados para uma segunda passagem com modelo de IA. Trate a saída como consultiva; verifique contra o código e os testes.

Caminho principal

Modelo padrão atual da CLI: gpt-5.5-pro. O motor navegador é útil para longas execuções no ChatGPT Pro; o motor API é útil quando OPENAI_API_KEY ou a configuração do Azure estiver pronta.

Recomendações padrão:

• Visualize primeiro: --dry-run summary --files-report
• Execução longa no navegador: --engine browser --model gpt-5.5-pro
• API explícita: --engine api --model gpt-5.5

Caminho dourado

1. Escolha um conjunto enxuto de arquivos (o menor número de arquivos que ainda contenha a verdade).
2. Visualize o payload e o gasto de tokens (--dry-run + --files-report).
3. Use o modo navegador para pensamento prolongado (Pro); modo API para chamadas de API explícitas.
4. Se a execução desanexar ou expirar: reconecte-se à sessão armazenada. Não execute novamente cegamente.

Comandos (preferidos)

• Ajuda:

  • oracle --help
  • Se o binário não estiver instalado: npx -y @steipete/oracle --help (evite pnpx aqui; dependências do sqlite).

• Visualização (sem tokens):

  • oracle --dry-run summary -p "<tarefa>" --file "src/**" --file "!**/*.test.*"
  • oracle --dry-run full -p "<tarefa>" --file "src/**"

• Sanidade de tokens:

  • oracle --dry-run summary --files-report -p "<tarefa>" --file "src/**"

• Execução no navegador (caminho principal; execução longa é normal):

  • oracle --engine browser --model gpt-5.5-pro -p "<tarefa>" --file "src/**"

• Alternativa de colagem manual:

  • oracle --render --copy -p "<tarefa>" --file "src/**"
  • Nota: --copy é um alias oculto para --copy-markdown.

Anexando arquivos (--file)

--file aceita arquivos, diretórios e globs. Você pode passá-lo várias vezes; as entradas podem ser separadas por vírgulas.

• Incluir:

  • --file "src/**"
  • --file src/index.ts
  • --file docs --file README.md

• Excluir:

  • --file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"

• Padrões (comportamento da implementação):

  • Diretórios ignorados por padrão: node_modules, dist, coverage, .git, .turbo, .next, build, tmp (ignorados a menos que sejam passados explicitamente como diretórios/arquivos literais).
  • Respeita .gitignore ao expandir globs.
  • Não segue links simbólicos.
  • Arquivos com ponto no início (dotfiles) são filtrados a menos que optados via padrão (ex.: --file ".github/**").
  • Arquivos > 1 MB são rejeitados.

Motores (API vs navegador)

• Escolha automática: api quando OPENAI_API_KEY estiver definida; caso contrário, browser.
• Navegador suporta apenas GPT + Gemini; use --engine api para Claude/Grok/Codex ou execuções com vários modelos.
• Anexos no navegador:
  • --browser-attachments auto|never|always (auto cola inline até ~60k caracteres e depois faz upload).
• Host remoto do navegador:
  • Servidor: oracle serve --host 0.0.0.0 --port 9473 --token <segredo>
  • Cliente: oracle --engine browser --remote-host <host:port> --remote-token <segredo> -p "<tarefa>" --file "src/**"

Sessões e slugs

• Armazenadas em ~/.oracle/sessions (sobrescreva com ORACLE_HOME_DIR).
• Execuções podem desanexar ou levar muito tempo (navegador + Pro frequentemente leva). Se a CLI expirar: não execute novamente; reconecte-se.
  • Listar: oracle status --hours 72
  • Anexar: oracle session <id> --render
• Use --slug "<3-5 palavras>" para manter os IDs das sessões legíveis.
• Existe proteção contra prompts duplicados; use --force apenas quando você realmente quiser uma execução nova.

Template de prompt (alto sinal)

O Oracle começa com zero conhecimento do projeto. Presuma que o modelo não pode inferir sua stack, ferramentas de build, convenções ou caminhos "óbvios". Inclua:

• Briefing do projeto (stack + comandos de build/teste + restrições de plataforma).
• "Onde as coisas vivem" (diretórios-chave, entrypoints, arquivos de configuração, limites).
• Pergunta exata + o que você tentou + o texto do erro (literal).
• Restrições ("não mude X", "deve manter a API pública", etc.).
• Saída desejada ("retorne plano de correção + testes", "dê 3 opções com trade-offs").

Anexos

• Deixe arquivos .env, arquivos de chave e tokens de autenticação fora dos anexos, a menos que o usuário peça para incluí-los.

Padrão de restauração de "prompt exaustivo"

Para investigações longas, escreva um prompt independente + conjunto de arquivos para que você possa reexecutar dias depois:

• Briefing do projeto (6 a 30 frases) + o objetivo.
• Passos para reproduzir + erros exatos + o que você tentou.
• Anexe todos os arquivos de contexto necessários (entrypoints, configurações, módulos-chave, docs).

As execuções do Oracle são únicas; o modelo não se lembra de execuções anteriores. "Restaurar contexto" significa reexecutar com o mesmo prompt + conjunto --file … (ou reconectar a uma sessão armazenada ainda em execução).