devs/docs/sora.md

Sora - Asistente de Desarrollo Colaborativo

Introducción

Sora es un potente asistente de desarrollo basado en IA que te permite colaborar con modelos de lenguaje de última generación directamente desde tu terminal. Está diseñado para trabajar con repositorios Git y modificar código en respuesta a tus instrucciones en lenguaje natural, proporcionando una experiencia de pair programming con un asistente de IA.

Implementada como parte del ecosistema MRDevs Tools, Sora facilita la codificación asistida por IA, permitiéndote iniciar, desarrollar y mejorar proyectos de software mediante conversaciones naturales con la IA.

Instalación y Configuración

Requisitos Previos

• MRDevs Tools instalado (ejecutar bin/bootstrap.sh previamente)
• Git instalado y configurado
• Python 3.8+ instalado
• Token de API válido de un proveedor compatible (OpenAI, Anthropic, etc.)
• Repositorio Git inicializado para tu proyecto

Instalación Básica

# Instalar Sora
bin/sora_install.sh

El proceso de instalación configura automáticamente todo lo necesario. Si necesitas configurar manualmente un token de API para algún proveedor compatible:

# Configurar token de API (selecciona el proveedor deseado)
bin/ai_token.sh

Actualización y Desinstalación

# Actualizar Sora a la última versión
bin/sora_install.sh --update

# Desinstalar Sora completamente
bin/sora_install.sh -u

Uso Básico

Iniciar una Sesión con tu Repositorio

Para comenzar a trabajar con Sora en un repositorio existente:

# Navegar al directorio del repositorio
cd /ruta/a/tu/proyecto

# Iniciar Sora
bin/sora.sh

También puedes especificar archivos específicos para trabajar:

# Iniciar Sora con archivos específicos
bin/sora.sh archivo1.py archivo2.js

# Iniciar Sora con un patrón glob
bin/sora.sh "src/*.py"

Interacción Básica

Una vez iniciada la sesión, puedes dar instrucciones en lenguaje natural:

> Crea una función que calcule el factorial de un número recursivamente

Sora analizará tu solicitud, generará el código correspondiente y realizará los cambios directamente en tus archivos, mostrándote los cambios realizados en la terminal.

Comandos Dentro de la Sesión

Dentro de una sesión de Sora, puedes usar comandos especiales precedidos por /:

> /help                    # Muestra la ayuda con todos los comandos disponibles
> /add archivo.py          # Añade un archivo al contexto de la sesión
> /drop archivo.py         # Quita un archivo del contexto
> /ls                      # Lista los archivos en el contexto actual
> /diff                    # Muestra los cambios realizados por Sora
> /run script.py           # Ejecuta un script
> /commit "mensaje"        # Crea un commit con los cambios actuales
> /exit                    # Finaliza la sesión

Funcionalidades Avanzadas

Modo de Edición de Archivos

Sora puede trabajar con archivos de diferentes formas:

# Editar archivos existentes
bin/sora.sh --edit archivo.py

# Crear nuevos archivos
bin/sora.sh --new "Crea un archivo HTML con un formulario básico"

# Modo sólo lectura (no modifica archivos automáticamente)
bin/sora.sh --no-auto-commits archivo.py

Selección de Entorno y Modelos

Sora permite escoger entre distintos entornos de ejecución:

# Al iniciar sora.sh, se te presentará un selector:
bin/sora.sh

# Opciones disponibles:
# 1. Remoto (OpenRouter) - Usa modelos en la nube
# 2. Local (Ollama) - Usa modelos instalados localmente

En modo local, Sora evaluará el rendimiento de tu hardware y te mostrará qué tan bien podrá ejecutar los modelos locales.

Comunicación con LLM por Voz

# Activar entrada por voz (experimental)
bin/sora.sh --voice

# Especificar idioma para reconocimiento de voz
bin/sora.sh --voice --language es-ES

Personalización del Comportamiento

# Controlar verbose del LLM
bin/sora.sh --verbose            # Muestra proceso de pensamiento detallado
bin/sora.sh --concise            # Respuestas breves y directas

# Modificar la creatividad de las respuestas
bin/sora.sh --temperature 0.7    # Más creativo (0.0-1.0)
bin/sora.sh --temperature 0.2    # Más determinista

Flujos de Trabajo Comunes

Desarrollo de Nuevas Características

# Iniciar Sora con los archivos relevantes
cd mi-proyecto
sora src/componente.js src/utils.js

# En la sesión de Sora
> Implementa una función de paginación para la tabla de usuarios que muestre 10 elementos por página

Refactorización de Código

# Iniciar con archivos que necesitan refactorización
sora código_legacy.py

# En la sesión
> Refactoriza este código para usar clases en lugar de funciones. Mantén la misma funcionalidad pero mejora la estructura.

Depuración y Corrección de Errores

# Iniciar con el archivo que tiene errores
sora archivo_con_bug.js

# En la sesión
> Este código arroja un TypeError cuando intento acceder a user.settings. Identifica y corrige el problema.

Generación de Tests

# Iniciar con el archivo a testear
sora src/utils.js

# En la sesión
> Genera tests unitarios completos para estas funciones usando Jest.

Técnicas Avanzadas

Proyectos Multiarchivo

Para trabajar con proyectos complejos que involucran múltiples archivos:

# Iniciar con múltiples archivos relevantes
sora src/api.js src/models.js src/controllers.js

# En la sesión
> Implementa un endpoint REST para gestionar usuarios que use los modelos y controladores existentes

Integración con Git

Sora se integra perfectamente con Git para gestionar cambios:

# Dentro de la sesión de Sora
> /diff               # Ver cambios actuales
> /commit "Mensaje"   # Hacer commit de los cambios
> /git status         # Ver estado de Git
> /git checkout -b feature-branch   # Crear y cambiar a nueva rama

Manejo de Dependencias y Bibliotecas

# En la sesión
> Añade la biblioteca axios al proyecto y crea una función para obtener datos de una API REST

Sora puede sugerir modificaciones al package.json y crear el código que utiliza la nueva dependencia.

Generación de Documentación

# En la sesión
> Genera documentación completa en formato JSDoc para todas las funciones en este archivo

Recomendaciones y Buenas Prácticas

Optimización de Prompts

Para obtener los mejores resultados con Sora:

1. Sé específico en tus instrucciones

   # Poco específico
   > Mejora este código
   
   # Muy específico
   > Refactoriza este método para usar async/await en lugar de callbacks y añade manejo de errores
   

2. Proporciona contexto suficiente

   > Este componente es parte de un dashboard que muestra estadísticas en tiempo real. Necesito añadir una funcionalidad de filtrado por fecha.
   

3. Divide problemas complejos

   > Primero, creemos la estructura de datos para almacenar los usuarios.
   > Ahora, implementemos las funciones de validación.
   > Por último, añadamos la lógica para guardar en la base de datos.
   

Reducción de Consumo de Tokens

Para optimizar el uso de tokens y reducir costos:

1. Limita el número de archivos en contexto

   # Preferible
   sora archivo-específico.js
   
   # Evitar si no es necesario
   sora *.js
   

2. Excluye archivos innecesarios

   sora --exclude node_modules,dist,build
   

3. Usa el modelo adecuado según la complejidad

   # Para tareas simples
   sora --model gpt-3.5-turbo archivo.js
   
   # Para tareas complejas
   sora --model gpt-4 archivo.js
   

4. Aprovecha el historial de contexto Continúa la misma sesión para tareas relacionadas en lugar de iniciar nuevas sesiones.

Seguridad y Mejores Prácticas

1. Revisa siempre los cambios propuestos Usa /diff antes de aceptar cambios para verificar que Sora no haya introducido problemas.

2. No incluyas secretos o credenciales Evita incluir archivos con tokens, claves API o contraseñas en las sesiones.

3. Usa ramas de Git separadas

   git checkout -b sora-experiment
   sora archivo.js
   # Después de revisar los cambios
   git checkout main
   git merge sora-experiment
   

4. Mantén respaldos Asegúrate de tener commits recientes antes de iniciar sesiones extensas.

Casos de Uso Prácticos

Caso 1: Implementación de un Sistema de Autenticación

# Iniciar Sora con los archivos relevantes
sora server.js auth.js user-model.js

# En la sesión
> Implementa un sistema completo de autenticación con JWT que incluya:
> 1. Registro de usuarios
> 2. Login con validación de credenciales
> 3. Middleware para rutas protegidas
> 4. Gestión de tokens (creación, verificación y renovación)

Caso 2: Migración de Tecnología

# Iniciar con archivos a migrar
sora componente-clase.jsx

# En la sesión
> Convierte este componente basado en clases de React a un componente funcional con hooks. Mantén exactamente la misma funcionalidad.

Caso 3: Optimización de Rendimiento

# Iniciar con código a optimizar
sora algoritmo-lento.py

# En la sesión
> Este algoritmo de ordenamiento tiene complejidad O(n²). Optimízalo para mejorar su rendimiento manteniendo la misma funcionalidad.

Caso 4: Desarrollo Guiado por Tests (TDD)

# Iniciar con archivo de pruebas
sora test-funcionalidad.js

# En la sesión
> Estos son tests para una API de gestión de tareas. Implementa el código que haga pasar estos tests.

Solución de Problemas Comunes

Problemas de Conexión con la API

Problema: Error de autenticación o conexión

Solución:

# Verificar token configurado
bin/ai_token.sh

# Comprobar conexión a internet
ping api.openai.com

Sora No Reconoce Correctamente la Intención

Problema: Sora genera código que no corresponde con lo solicitado

Solución:

1. Reinicia la instrucción con más detalles
2. Divide la tarea en pasos más pequeños
3. Prueba con otro modelo:

   sora --model gpt-4-turbo archivo.js
   

Errores al Modificar Archivos

Problema: Sora no puede modificar archivos correctamente

Solución:

# Verificar permisos
ls -la archivo.js

# Usar modo sin auto-commits
sora --no-auto-commits archivo.js

# Después, aplicar cambios manualmente
> /diff
# Copiar los cambios y aplicarlos manualmente

Conflictos de Merge en Git

Problema: Conflictos al integrar cambios de Sora

Solución:

# En la sesión de Sora
> /git stash
> /git pull
> /git stash pop
# Resolver conflictos manualmente
> /git add .
> /git commit -m "Resueltos conflictos con cambios de Sora"

Personalización Avanzada

Archivo de Configuración

Puedes crear un archivo .aiderrc o .sorarc en tu directorio home o proyecto para personalizar el comportamiento:

# ~/.sorarc
model = gpt-4
auto_commits = False
editor = vim
map_tokens = 4096
temperature = 0.2

Variables de Entorno

Configura el comportamiento mediante variables de entorno:

# Añadir a tu .bashrc o .zshrc
export SORA_MODEL="gpt-4"
export SORA_VERBOSE=1
export SORA_EDITOR="code -w"

Atajos de Teclado Personalizados

Configura atajos para operaciones comunes:

# Añadir a tu .bashrc o .zshrc
alias sora-web="sora --model gpt-4 --include '*.html,*.css,*.js'"
alias sora-py="sora --model gpt-4 --include '*.py'"
alias sora-debug="sora --no-auto-commits --verbose"

Integración con el Ecosistema de Desarrollo

Integración con Editores

VSCode:

# Usar VSCode para editar diff
export SORA_EDITOR="code --wait"

NeoVim/Vim:

# Usar Vim para editar diff
export SORA_EDITOR="nvim"

Integración con Herramientas de CI/CD

# Archivo .github/workflows/sora-lint.yml
name: Sora Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install Sora
        run: pip install aider-chat
      - name: Code Review
        run: sora --no-auto-commits --model gpt-4 --prompt "Revisa este PR y proporciona feedback sobre posibles bugs y mejoras" $(git diff --name-only origin/main)
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Flujos de Trabajo con Otras Herramientas

Combinación con Cortana:

# Generar esquema con Cortana
cortana "Diseña una arquitectura de microservicios para un sistema de reservas" > arquitectura.md

# Implementar con Sora
sora arquitectura.md
> Implementa el servicio de autenticación descrito en este documento

Modos de Ejecución

Sora ofrece dos modos principales de ejecución, cada uno con sus propias ventajas:

Modo Remoto (OpenRouter)

El modo remoto utiliza OpenRouter para acceder a diversos modelos de IA en la nube:

• Ventajas: Acceso a modelos de alta capacidad, no requiere hardware potente local.
• Desventajas: Requiere conexión a internet, envía datos a servicios externos.
• Uso recomendado: Desarrollo general, tareas complejas, proyectos grandes.

Modo Local (Ollama)

El modo local ejecuta modelos en tu propia máquina utilizando Ollama:

• Ventajas: Privacidad total, funciona sin internet, control completo.
• Desventajas: Requiere hardware potente, modelos más limitados.
• Uso recomendado: Código sensible, entornos restringidos, trabajo offline.

Comparación de Modelos de IA

Sora es compatible con diversos modelos de IA, cada uno con sus fortalezas particulares:

Modelo	Fortalezas	Casos de Uso
GPT-3.5	Rápido, económico	Tareas simples, pruebas rápidas
GPT-4	Comprensión profunda, mejor con código	Desarrollo complejo, debugging
Claude 3	Excelente razonamiento, contexto largo	Proyectos grandes, documentación
Llama 2 / 3	Ejecución local, privacidad	Código sensible, entornos offline

Extensiones y Plugins

Sora puede extenderse con plugins personalizados:

# Plugin para análisis estático
bin/sora.sh --plugin static-analysis

# Plugin para benchmarking
bin/sora.sh --plugin benchmark

Características Adicionales

Evaluación de Hardware

En modo local, Sora realiza un diagnóstico completo del hardware disponible:

• Análisis de CPU: Verifica el número de núcleos disponibles
• Evaluación de RAM: Comprueba la memoria total y disponible
• Detección de GPU: Identifica tarjetas gráficas NVIDIA compatibles
• Clasificación de Rendimiento: Desde "Muy Malo" hasta "Excelente"

Interacción con Ollama

Sora gestiona automáticamente Ollama:

• Arranque Automático: Inicia Ollama cuando es necesario
• Monitoreo de Estado: Verifica que Ollama esté respondiendo correctamente
• Selección Interactiva: Permite elegir entre los modelos disponibles
• Apagado Automático: Detiene Ollama al finalizar si lo inició Sora

Créditos y Reconocimientos

Sora está basado en Aider, una potente herramienta de pair programming con IA. Todas las capacidades de análisis y generación de código son proporcionadas por Aider, mientras que la integración en el ecosistema MRDevs Tools ha sido implementada por el equipo de MRDevs Tools para proporcionar una experiencia fluida y personalizada.

Recursos Adicionales

• Documentación Oficial de Aider
• Comunidad y Soporte
• Guía de Prompt Engineering para Codificación
• Ejemplos Avanzados de Uso

---

Creado por Sora Rosero One para MRDevs Tools. Última actualización: 2025/04/07