oráculo

¿Qué hace oráculo?

Oracle empaqueta un prompt + archivos seleccionados para una única pasada de un segundo modelo. Trata la salida como orientativa; verifícala contra el código y las pruebas.

Ruta principal

Modelo predeterminado actual de CLI: gpt-5.5-pro. El motor de navegador es útil para ejecuciones largas en ChatGPT Pro; el motor API es útil cuando OPENAI_API_KEY o la configuración de Azure está lista.

Valores predeterminados recomendados:

• Vista previa primero: --dry-run summary --files-report
• Ejecución larga en navegador: --engine browser --model gpt-5.5-pro
• API explícita: --engine api --model gpt-5.5

Ruta dorada

1. Elige un conjunto de archivos ajustado (la menor cantidad de archivos que aún contengan la verdad).
2. Previsualiza el payload y el gasto de tokens (--dry-run + --files-report).
3. Usa el modo navegador para pensamiento Pro largo; modo API para llamadas API explícitas.
4. Si la ejecución se desconecta/agota el tiempo: reconéctate a la sesión almacenada. No vuelvas a ejecutar ciegamente.

Comandos (preferidos)

• Ayuda:

  • oracle --help
  • Si el binario no está instalado: npx -y @steipete/oracle --help (evita pnpx aquí; bindings sqlite).

• Vista previa (sin tokens):

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

• Verificación de tokens:

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

• Ejecución en navegador (ruta principal; normal que sea larga):

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

• Alternativa de pegado manual:

  • oracle --render --copy -p "<tarea>" --file "src/**"
  • Nota: --copy es un alias oculto para --copy-markdown.

Adjuntar archivos (--file)

--file acepta archivos, directorios y globs. Puedes pasarlo varias veces; las entradas pueden estar separadas por comas.

• Incluir:

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

• Excluir:

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

• Valores predeterminados (comportamiento de implementación):

  • Directorios ignorados por defecto: node_modules, dist, coverage, .git, .turbo, .next, build, tmp (omitidos a menos que se pasen explícitamente como directorios/archivos literales).
  • Respeta .gitignore al expandir globs.
  • No sigue enlaces simbólicos.
  • Los archivos de puntos se filtran a menos que se opte mediante un patrón (ej. --file ".github/**").
  • Archivos > 1 MB rechazados.

Motores (API vs navegador)

• Selección automática: api cuando OPENAI_API_KEY está configurada; de lo contrario browser.
• El navegador solo soporta GPT + Gemini; usa --engine api para Claude/Grok/Codex o ejecuciones multi-modelo.
• Adjuntos del navegador:
  • --browser-attachments auto|never|always (auto pega en línea hasta ~60k caracteres y luego sube).
• Host de navegador remoto:
  • Servidor: oracle serve --host 0.0.0.0 --port 9473 --token <secreto>
  • Cliente: oracle --engine browser --remote-host <host:puerto> --remote-token <secreto> -p "<tarea>" --file "src/**"

Sesiones + slugs

• Almacenadas en ~/.oracle/sessions (sobrescribe con ORACLE_HOME_DIR).
• Las ejecuciones pueden desconectarse o tardar mucho tiempo (el navegador + Pro a menudo lo hace). Si la CLI agota el tiempo: no vuelvas a ejecutar; reconéctate.
  • Listar: oracle status --hours 72
  • Adjuntar: oracle session <id> --render
• Usa --slug "<3-5 palabras>" para que los IDs de sesión sean legibles.
• Existe protección contra prompts duplicados; usa --force solo cuando realmente quieras una ejecución fresca.

Plantilla de prompt (alta señal)

Oracle comienza con cero conocimiento del proyecto. Asume que el modelo no puede inferir tu stack, herramientas de construcción, convenciones o rutas "obvias". Incluye:

• Briefing del proyecto (stack + comandos de construcción/prueba + restricciones de plataforma).
• "Dónde viven las cosas" (directorios clave, puntos de entrada, archivos de configuración, límites).
• Pregunta exacta + lo que probaste + el texto del error (textual).
• Restricciones ("no cambies X", "debes mantener la API pública", etc).
• Salida deseada ("devuelve plan de parche + pruebas", "da 3 opciones con compensaciones").

Adjuntos

• Deja fuera de los adjuntos los archivos .env, archivos clave y tokens de autenticación a menos que el usuario pida incluirlos.

Patrón de restauración de "prompt exhaustivo"

Para investigaciones largas, escribe un prompt independiente + conjunto de archivos para poder volver a ejecutar días después:

• Briefing del proyecto de 6 a 30 oraciones + el objetivo.
• Pasos de reproducción + errores exactos + lo que probaste.
• Adjunta todos los archivos de contexto necesarios (puntos de entrada, configuraciones, módulos clave, documentos).

Las ejecuciones de Oracle son de una sola vez; el modelo no recuerda ejecuciones anteriores. "Restaurar contexto" significa volver a ejecutar con el mismo prompt + conjunto --file … (o reconectarse a una sesión almacenada que aún esté en ejecución).