npm - sinapse-ai - Versions diffs - 5.0.8 → 6.0.1 - Mend

sinapse-ai 5.0.8 → 6.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (660) hide show

package/docs/es/guides/llm-routing.md DELETED Viewed

@@ -1,312 +0,0 @@
-<!--
-  Traduccion: ES
-  Original: /docs/en/guides/llm-routing.md
-  Ultima sincronizacion: 2026-01-26
--->
-# Guia de Enrutamiento de LLM
-> 🌐 [EN](../../guides/llm-routing.md) | [PT](../../pt/guides/llm-routing.md) | **ES**
----
-**Version:** 1.0.0
-**Actualizado:** 2025-12-14
-Enrutamiento de LLM rentable para Claude Code. Ahorra hasta un 99% en costos de API mientras mantienes la funcionalidad completa.
----
-## Descripcion General
-El Enrutamiento de LLM proporciona dos comandos para diferentes casos de uso:
-| Comando | Proveedor | Costo | Caso de Uso |
-|---------|----------|------|----------|
-| `claude-max` | Claude Max (OAuth) | Suscripcion | Experiencia premium, tareas complejas |
-| `claude-free` | DeepSeek | ~$0.14/M tokens | Desarrollo, pruebas, tareas simples |
----
-## Inicio Rapido
-### Instalacion
-**Opcion 1: Si tienes sinapse-ai clonado**
-```bash
-# Desde el directorio sinapse-ai
-node .sinapse-ai/infrastructure/scripts/llm-routing/install-llm-routing.js
-```
-**Opcion 2: Instalacion nueva**
-```bash
-# Clonar el repositorio
-git clone https://github.com/SinapseAI/sinapse-ai.git
-cd sinapse-ai
-# Ejecutar el instalador
-node .sinapse-ai/infrastructure/scripts/llm-routing/install-llm-routing.js
-```
-### Configurar Clave API de DeepSeek
-1. Obtener tu clave API en: <https://platform.deepseek.com/api_keys>
-2. Agregar al archivo `.env` de tu proyecto:
-```bash
-DEEPSEEK_API_KEY=sk-your-key-here
-```
-### Uso
-```bash
-# Experiencia premium de Claude (usa tu suscripcion Claude Max)
-claude-max
-# Desarrollo rentable (usa DeepSeek ~$0.14/M tokens)
-claude-free
-```
----
-## Comandos
-### claude-max
-Usa tu suscripcion Claude Max via OAuth (inicio de sesion en claude.ai).
-**Caracteristicas:**
-- Capacidades completas de Claude
-- No requiere clave API
-- Usa el inicio de sesion existente de Claude
-- Ideal para tareas de razonamiento complejo
-**Uso:**
-```bash
-claude-max
-```
-**Cuando usar:**
-- Analisis de codigo complejo
-- Decisiones arquitectonicas
-- Tareas que requieren alta precision
-- Trabajo critico de produccion
----
-### claude-free
-Usa la API de DeepSeek con endpoint compatible con Anthropic.
-**Caracteristicas:**
-- Llamadas a herramientas soportadas
-- Streaming soportado
-- ~99% de reduccion de costos
-- Soporte para archivo `.env` del proyecto
-**Uso:**
-```bash
-claude-free
-```
-**Cuando usar:**
-- Desarrollo y pruebas
-- Tareas de codigo simples
-- Aprendizaje y experimentacion
-- Operaciones de alto volumen
----
-## Comparacion de Costos
-| Proveedor | Tokens de Entrada | Tokens de Salida | Mensual (1M tokens) |
-|----------|-------------|---------------|---------------------|
-| API de Claude | $15.00/M | $75.00/M | $90.00 |
-| Claude Max | Incluido | Incluido | $20/mes |
-| **DeepSeek** | **$0.07/M** | **$0.14/M** | **$0.21** |
-**Ahorro con DeepSeek:** Hasta 99.7% comparado con la API de Claude
----
-## Configuracion
-### Fuentes de Clave API
-`claude-free` busca la clave API de DeepSeek en este orden:
-1. **Archivo `.env` del proyecto** (recomendado)
-   ```bash
-   # .env en la raiz de tu proyecto
-   DEEPSEEK_API_KEY=sk-your-key-here
-   ```
-2. **Variable de entorno**
-   ```bash
-   # Windows
-   setx DEEPSEEK_API_KEY "sk-your-key-here"
-   # Unix (agregar a ~/.bashrc o ~/.zshrc)
-   export DEEPSEEK_API_KEY="sk-your-key-here"
-   ```
-### Ubicaciones de Instalacion
-| SO | Directorio de Instalacion |
-|----|-------------------|
-| Windows | `%APPDATA%\npm\` |
-| macOS/Linux | `/usr/local/bin/` o `~/bin/` |
----
-## Como Funciona
-### claude-max
-1. Limpia todas las configuraciones de proveedores alternativos
-2. Usa la autenticacion OAuth predeterminada de Claude
-3. Inicia Claude Code con tu suscripcion Max
-### claude-free
-1. Busca el archivo `.env` (directorio actual -> directorios padre)
-2. Carga `DEEPSEEK_API_KEY` desde `.env` o variables de entorno
-3. Configura el endpoint compatible con Anthropic de DeepSeek
-4. Inicia Claude Code con backend de DeepSeek
-**Endpoint de DeepSeek:**
-```text
-https://api.deepseek.com/anthropic
-```
-Este endpoint proporciona:
-- Compatibilidad con API de Anthropic
-- Soporte para llamadas a herramientas/funciones
-- Respuestas en streaming
-### Nota de Seguridad: Omision de Permisos
-Tanto `claude-max` como `claude-free` usan la bandera `--dangerously-skip-permissions` por defecto. Esto:
-- **Omite los prompts de confirmacion** para operaciones de archivos, ejecucion de comandos, etc.
-- **Solo debe usarse en repositorios/entornos de confianza**
-- **No se recomienda para bases de codigo no confiables**
-Se muestra una advertencia cada vez que ejecutas estos comandos. Si prefieres confirmaciones interactivas, ejecuta `claude` directamente en lugar de usar los comandos de enrutamiento.
----
-## Solucion de Problemas
-### Comando no encontrado
-**Windows:**
-```powershell
-# Verificar si npm global esta en PATH
-echo $env:PATH | Select-String "npm"
-# Si no, agregarlo:
-$env:PATH += ";$env:APPDATA\npm"
-```
-**Unix:**
-```bash
-# Verificar PATH
-echo $PATH | grep -E "(local/bin|~/bin)"
-# Si ~/bin no esta en PATH, agregar a ~/.bashrc:
-export PATH="$HOME/bin:$PATH"
-```
-### DEEPSEEK_API_KEY no encontrada
-1. Verificar que el archivo `.env` existe en la raiz del proyecto
-2. Verificar formato de la clave: `DEEPSEEK_API_KEY=sk-...`
-3. Sin espacios alrededor de `=`
-4. No se necesitan comillas alrededor del valor
-### Errores de API
-| Error | Causa | Solucion |
-|-------|-------|----------|
-| 401 Unauthorized | Clave API invalida | Verificar clave en el panel de DeepSeek |
-| 429 Rate Limited | Demasiadas solicitudes | Esperar y reintentar |
-| Connection refused | Problema de red | Verificar conexion a internet |
-### Llamadas a herramientas no funcionan
-El endpoint `/anthropic` de DeepSeek soporta llamadas a herramientas. Si las herramientas no funcionan:
-1. Verificar que el endpoint es `https://api.deepseek.com/anthropic`
-2. Verificar que la clave API tiene creditos suficientes
-3. Intentar una prueba simple sin herramientas primero
----
-## Configuracion Avanzada
-### Modelos Personalizados
-Editar los archivos de plantilla si necesitas modelos diferentes:
-**Windows:** `.sinapse-ai/infrastructure/scripts/llm-routing/templates/claude-free.cmd`
-**Unix:** `.sinapse-ai/infrastructure/scripts/llm-routing/templates/claude-free.sh`
-Cambiar:
-```bash
-export ANTHROPIC_MODEL="deepseek-chat"
-```
-### Variables de Entorno
-| Variable | Descripcion | Predeterminado |
-|----------|-------------|---------|
-| `ANTHROPIC_BASE_URL` | Endpoint de API | `https://api.deepseek.com/anthropic` |
-| `ANTHROPIC_API_KEY` | Clave API | Desde DEEPSEEK_API_KEY |
-| `ANTHROPIC_MODEL` | Nombre del modelo | `deepseek-chat` |
-| `API_TIMEOUT_MS` | Tiempo de espera de solicitud | `600000` (10 min) |
----
-## Desinstalacion
-### Windows
-```powershell
-Remove-Item "$env:APPDATA\npm\claude-free.cmd"
-Remove-Item "$env:APPDATA\npm\claude-max.cmd"
-```
-### Unix
-```bash
-rm /usr/local/bin/claude-free
-rm /usr/local/bin/claude-max
-# O si se instalo en ~/bin:
-rm ~/bin/claude-free
-rm ~/bin/claude-max
-```
----
-## Recursos Relacionados
-- **Definicion de Herramienta:** `.sinapse-ai/infrastructure/tools/cli/llm-routing.yaml`
-- **Script de Instalacion:** `.sinapse-ai/infrastructure/scripts/llm-routing/install-llm-routing.js`
-- **Definicion de Tarea:** `.sinapse-ai/development/tasks/setup-llm-routing.md`
-- **API de DeepSeek:** <https://platform.deepseek.com/api_keys>
----
-## Preguntas Frecuentes
-**P: Es DeepSeek tan bueno como Claude?**
-R: DeepSeek es excelente para la mayoria de tareas de programacion pero puede no igualar el razonamiento de Claude en problemas complejos. Usa `claude-max` para trabajo critico.
-**P: Puedo usar ambos comandos en la misma sesion?**
-R: Si! Cada comando configura su propio entorno. Puedes alternar entre ellos.
-**P: Funciona claude-free sin conexion?**
-R: No, requiere acceso a internet para conectarse a la API de DeepSeek.
-**P: Estan seguras mis claves API?**
-R: Las claves se cargan desde archivos `.env` (no los subas al repositorio!) o variables de entorno. Nunca codifiques las claves directamente.
----
-*Generado por SINAPSE Framework - Story 6.7*

package/docs/es/guides/mcp/desktop-commander.md DELETED Viewed

@@ -1,368 +0,0 @@
-# Desktop Commander MCP
-> **ES**
----
-Guía para usar el servidor MCP Desktop Commander con Claude Code para capacidades avanzadas de gestión de terminal y procesos.
-**Versión:** 1.0.0
-**Última Actualización:** 2026-01-28
----
-## Descripción General
-Desktop Commander es un servidor MCP que extiende Claude Code con capacidades avanzadas para la gestión del entorno local. Proporciona funcionalidades que las herramientas nativas de Claude Code no pueden hacer, haciéndolo esencial para ciertos flujos de trabajo.
-### Cuándo Usar Desktop Commander
-| Caso de Uso                              | Claude Code Nativo | Desktop Commander |
-| ---------------------------------------- | ------------------ | ----------------- |
-| Sesiones persistentes (SSH, REPL)        | No soportado       | **Recomendado**   |
-| Procesos interactivos                    | Limitado           | **Recomendado**   |
-| Edición difusa de archivos               | No soportado       | **Recomendado**   |
-| Lectura de cola de archivo (offset negativo) | No soportado  | **Recomendado**   |
-| Ejecución de código en memoria           | No soportado       | **Recomendado**   |
-| Operaciones simples de archivos          | **Preferido**      | Más lento         |
-| Operaciones Git                          | **Preferido**      | Innecesario       |
-| Búsqueda de archivos (Glob, Grep)        | **Preferido**      | Innecesario       |
----
-## Comparación de Capacidades
-### Lo Que Desktop Commander Hace Que Claude Code No Puede
-| Capacidad                         | Claude Code Nativo                                                  | Desktop Commander                                      |
-| --------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------ |
-| **Sesiones Persistentes**         | El estado del shell no persiste entre llamadas (solo working dir)   | Mantiene sesiones activas (SSH, bases de datos, REPL)  |
-| **Ejecución de Código en Memoria**| Requiere Write → Bash                                               | Ejecución directa en REPL (Python, Node.js, R)         |
-| **Edición Difusa**                | Edit requiere coincidencia EXACTA de old_string                     | Respaldo inteligente con búsqueda difusa               |
-| **Offset Negativo (tail)**        | Read solo tiene offset positivo                                     | Lectura desde el final del archivo (como Unix tail)    |
-| **Procesos Interactivos**         | Limitado (background sin stdin)                                     | Stdin/stdout bidireccional                             |
-| **Configuración Dinámica**        | Requiere reinicio                                                   | Cambiar shell, directorios, comandos bloqueados al vuelo |
-| **Registro de Auditoría**         | Básico en .claude.json                                              | Historial completo de herramientas y estadísticas de uso |
-### Donde Claude Code Nativo es Suficiente
-| Capacidad                         | Claude Code Nativo                 | Notas                                      |
-| --------------------------------- | ---------------------------------- | ------------------------------------------ |
-| **Búsqueda Paginada**             | Grep tiene `head_limit` y `offset` | Ya tiene capacidad de streaming            |
-| **Gestión Multi-Sesión**          | Task tool + TaskOutput + /tasks    | Enfoque diferente pero funcional           |
-| **Análisis CSV/JSON**             | Read + Bash con jq/python          | Funciona bien para la mayoría de los casos |
----
-## Instalación
-### Prerequisitos
-- Node.js 18+
-- Claude Code CLI instalado
-- Soporte MCP habilitado
-### Configuración
-```bash
-# Instalar desktop-commander globalmente
-npm install -g @anthropic/desktop-commander
-# O agregar a la configuración MCP de Claude Code
-claude mcp add desktop-commander
-```
-### Configuración
-Agregar a `~/.claude.json`:
-```json
-{
-  "mcpServers": {
-    "desktop-commander": {
-      "command": "npx",
-      "args": ["-y", "@anthropic/desktop-commander"]
-    }
-  }
-}
-```
----
-## Herramientas Disponibles
-### Gestión de Terminal
-| Herramienta       | Descripción                                  |
-| ----------------- | -------------------------------------------- |
-| `execute_command` | Ejecutar comando shell con sesión persistente |
-| `read_output`     | Leer salida del proceso en ejecución         |
-| `send_input`      | Enviar entrada al proceso interactivo        |
-| `force_terminate` | Terminar un proceso en ejecución             |
-| `list_sessions`   | Listar todas las sesiones activas            |
-| `list_processes`  | Listar procesos en ejecución                 |
-### Operaciones de Archivos
-| Herramienta      | Descripción                                          |
-| ---------------- | ---------------------------------------------------- |
-| `read_file`      | Leer archivo con soporte de offset negativo (tail)  |
-| `write_file`     | Escribir contenido de archivo                        |
-| `edit_block`     | Editar con respaldo de coincidencia difusa           |
-| `search_files`   | Buscar con streaming/paginación                      |
-| `get_file_info`  | Obtener metadatos del archivo                        |
-| `list_directory` | Listar contenido del directorio                      |
-### Ejecución de Código
-| Herramienta    | Descripción                                       |
-| -------------- | ------------------------------------------------- |
-| `execute_code` | Ejecutar código en memoria (Python, Node.js, R)  |
-| `create_repl`  | Crear sesión REPL persistente                     |
-| `repl_execute` | Ejecutar en REPL existente                        |
-### Configuración
-| Herramienta        | Descripción                                   |
-| ------------------ | --------------------------------------------- |
-| `get_config`       | Obtener configuración actual                  |
-| `set_config_value` | Actualizar configuración dinámicamente        |
----
-## Ejemplos de Uso
-### Sesión SSH Persistente
-```
-# Crear sesión SSH
-execute_command: ssh user@server.com
-# Enviar comandos a la sesión
-send_input: ls -la
-read_output: [session_id]
-# Mantener la sesión activa para múltiples interacciones
-send_input: cd /var/log
-send_input: tail -f syslog
-```
-### Análisis Python en Memoria
-```
-# Ejecutar Python sin crear archivos
-execute_code:
-  language: python
-  code: |
-    import pandas as pd
-    df = pd.read_csv('/path/to/data.csv')
-    print(df.describe())
-    print(df.head(10))
-```
-### Edición Difusa de Archivos
-```
-# Editar con coincidencia aproximada (cuando falla la coincidencia exacta)
-edit_block:
-  file_path: /path/to/file.py
-  old_text: "def process_data(data)"  # Coincidencia aproximada
-  new_text: "def process_data(data: dict) -> dict"
-  fuzzy: true
-```
-### Lectura de Cola de Archivo
-```
-# Leer las últimas 100 líneas de un archivo de log grande
-read_file:
-  path: /var/log/application.log
-  offset: -100  # Negativo = desde el final
-  lines: 100
-```
-### REPL Interactivo
-```
-# Crear REPL de Node.js
-create_repl:
-  language: nodejs
-# Ejecutar en REPL (mantiene el estado)
-repl_execute: const data = require('./config.json')
-repl_execute: Object.keys(data).length
-repl_execute: data.settings.enabled
-```
----
-## Mejores Prácticas
-### 1. Usar Herramientas Nativas Cuando Sea Posible
-Desktop Commander agrega latencia. Preferir herramientas nativas para:
-```
-# Bueno - Usar Read nativo
-Read tool para lectura simple de archivos
-# Bueno - Usar Bash nativo
-Bash tool para comandos rápidos
-# Bueno - Usar Grep nativo
-Grep tool para búsqueda de archivos
-```
-### 2. Usar Desktop Commander Para
-```
-# Sesiones persistentes
-- Conexiones SSH
-- Conexiones a bases de datos (psql, mysql, mongo shell)
-- Sesiones REPL (python, node, irb)
-# Procesos interactivos
-- Comandos de larga duración con monitoreo de salida
-- Procesos que requieren entrada stdin
-# Operaciones avanzadas de archivos
-- Archivos grandes que necesitan tail (offset negativo)
-- Ediciones con coincidencias inexactas (fuzzy)
-```
-### 3. Gestión de Sesiones
-```
-# Siempre listar sesiones antes de crear nuevas
-list_sessions
-# Limpiar sesiones no utilizadas
-force_terminate: [old_session_id]
-# Nombrar sesiones para claridad
-execute_command:
-  command: ssh prod-server
-  session_name: prod-ssh
-```
-### 4. Manejo de Errores
-```
-# Verificar estado del proceso antes de enviar entrada
-list_processes
-# Usar timeouts para operaciones largas
-execute_command:
-  command: long-running-task
-  timeout: 300000  # 5 minutos
-```
----
-## Integración con SINAPSE
-### Prioridad de Selección de Herramientas
-Según `.claude/rules/mcp-usage.md`:
-| Tarea                 | USAR ESTO              | NO desktop-commander                |
-| --------------------- | ---------------------- | ----------------------------------- |
-| Leer archivos locales | `Read` tool            | Más lento                           |
-| Escribir archivos locales | `Write` / `Edit` tools | Más lento                       |
-| Ejecutar comandos shell | `Bash` tool          | A menos que se necesite sesión persistente |
-| Buscar archivos       | `Glob` tool            | Más lento                           |
-| Buscar contenido      | `Grep` tool            | Más lento                           |
-### Cuándo se Requiere Desktop Commander
-1. El usuario solicita explícitamente sesión persistente
-2. La tarea requiere ejecución REPL
-3. Necesidad de leer cola de archivos grandes
-4. La edición requiere coincidencia difusa
-5. Proceso interactivo con stdin/stdout
-### Responsabilidades de Agentes
-| Agente             | Caso de Uso de Desktop Commander              |
-| ------------------ | --------------------------------------------- |
-| **@dev**           | Sesiones REPL, depuración, codificación en vivo |
-| **@devops**        | Sesiones SSH, gestión de servidores, análisis de logs |
-| **@data-engineer** | REPL de análisis de datos, conexiones a bases de datos |
-| **@qa**            | Pruebas interactivas, monitoreo de procesos   |
----
-## Solución de Problemas
-### La Sesión No Persiste
-```bash
-# Verificar si desktop-commander está ejecutándose
-claude mcp status
-# Reiniciar servidor MCP
-claude mcp restart desktop-commander
-```
-### Edición Difusa No Funciona
-```
-# Asegurar que el flag fuzzy esté configurado
-edit_block:
-  fuzzy: true
-  threshold: 0.8  # Ajustar umbral de similitud
-```
-### Timeout del Proceso
-```
-# Aumentar timeout para operaciones largas
-execute_command:
-  timeout: 600000  # 10 minutos
-# O usar modo background
-execute_command:
-  background: true
-```
-### No se Puede Conectar al Servidor
-```bash
-# Verificar configuración MCP
-cat ~/.claude.json | grep -A 10 desktop-commander
-# Verificar paquete npm
-npm list -g @anthropic/desktop-commander
-# Reinstalar si es necesario
-npm install -g @anthropic/desktop-commander@latest
-```
----
-## Documentación Relacionada
-- [Docker Gateway Tutorial](./docker-gateway-tutorial.md)
-- [MCP Global Setup Guide](../mcp-global-setup.md)
-- [Docker MCP Setup](../../docker-mcp-setup.md)
-- [MCP Usage Rules](../../../.claude/rules/mcp-usage.md)
-- [Agent Tool Integration](../../architecture/agent-tool-integration-guide.md)
----
-## Resumen
-| Funcionalidad         | Claude Code Nativo | Desktop Commander          |
-| --------------------- | ------------------ | -------------------------- |
-| Velocidad             | Rápido             | Más lento (overhead MCP)   |
-| Sesiones Persistentes | No                 | Sí                         |
-| Ejecución en Memoria  | No                 | Sí                         |
-| Edición Difusa        | No                 | Sí                         |
-| Offset Negativo       | No                 | Sí                         |
-| Procesos Interactivos | Limitado           | Completo                   |
-**Regla General:** Usar herramientas nativas por defecto. Cambiar a Desktop Commander solo cuando necesites sus capacidades únicas.
----
-_Desktop Commander MCP Guide v1.0.0 - SINAPSE Framework_