# 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

```bash
# Instalar Sora
bin/aider_install.sh

# Configurar alias para facilitar su uso
bin/sora_enable.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:

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

### Actualización y Desinstalación

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

# Desinstalar Sora completamente
bin/aider_install.sh -u

# Deshabilitar temporalmente el alias 'sora'
bin/sora_disable.sh
```

## Uso Básico

### Iniciar una Sesión con tu Repositorio

Para comenzar a trabajar con Sora en un repositorio existente:

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

# Iniciar Sora (usando alias)
sora
```

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

```bash
# Iniciar Sora con archivos específicos
sora archivo1.py archivo2.js

# Iniciar Sora con un patrón glob
sora "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:

```bash
# Editar archivos existentes
sora --edit archivo.py

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

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

### Selección de Modelos

Puedes especificar qué modelo de IA usar para la sesión:

```bash
# Usar un modelo específico de OpenAI
sora --model gpt-4

# Usar un modelo de Anthropic
sora --model claude-3-opus-20240229

# Ver modelos disponibles
sora --help models
```

### Comunicación con LLM por Voz

```bash
# Activar entrada por voz (experimental)
sora --voice

# Especificar idioma para reconocimiento de voz
sora --voice --language es-ES
```

### Personalización del Comportamiento

```bash
# Controlar verbose del LLM
sora --verbose            # Muestra proceso de pensamiento detallado
sora --concise            # Respuestas breves y directas

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

## Flujos de Trabajo Comunes

### Desarrollo de Nuevas Características

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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**
   ```bash
   # Preferible
   sora archivo-específico.js
   
   # Evitar si no es necesario
   sora *.js
   ```

2. **Excluye archivos innecesarios**
   ```bash
   sora --exclude node_modules,dist,build
   ```

3. **Usa el modelo adecuado según la complejidad**
   ```bash
   # 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**
   ```bash
   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

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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**:
```bash
# 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:
   ```bash
   sora --model gpt-4-turbo archivo.js
   ```

### Errores al Modificar Archivos

**Problema**: Sora no puede modificar archivos correctamente

**Solución**:
```bash
# 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**:
```bash
# 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:

```ini
# ~/.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:

```bash
# 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:

```bash
# 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**:
```bash
# Usar VSCode para editar diff
export SORA_EDITOR="code --wait"
```

**NeoVim/Vim**:
```bash
# Usar Vim para editar diff
export SORA_EDITOR="nvim"
```

### Integración con Herramientas de CI/CD

```bash
# 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**:
```bash
# 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
```

## 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:

```bash
# Plugin para análisis estático
sora --plugin static-analysis

# Plugin para benchmarking
sora --plugin benchmark
```

## 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](https://aider.chat/docs/)
- [Comunidad y Soporte](https://github.com/paul-gauthier/aider/discussions)
- [Guía de Prompt Engineering para Codificación](https://github.com/paul-gauthier/aider/blob/main/docs/prompting.md)
- [Ejemplos Avanzados de Uso](https://aider.chat/docs/examples.html)

---

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