Skip to content

windows.md

Latest commit

 

History

History
342 lines (235 loc) · 8.26 KB

windows.md

File metadata and controls

342 lines (235 loc) · 8.26 KB
Raw

Guía de Instalación Windows para Synkra AIOX

🌐 EN | PT | ES

Versiones Soportadas

Versión de Windows Estado Notas
Windows 11 ✅ Totalmente Soportado Recomendado
Windows 10 (22H2+) ✅ Totalmente Soportado Requiere últimas actualizaciones
Windows 10 (anterior) ⚠️ Soporte Limitado Actualización recomendada
Windows Server 2022 ✅ Totalmente Soportado
Windows Server 2019 ⚠️ Probado por la Comunidad

Requisitos Previos

1. Node.js (v20 o superior)

Opción A: Usando el Instalador Oficial (Recomendado)

  1. Descargue desde nodejs.org
  2. Elija la versión LTS (20.x o superior)
  3. Ejecute el instalador con opciones predeterminadas
  4. Verifique la instalación en PowerShell:
node --version  # Debería mostrar v20.x.x
npm --version

Opción B: Usando winget

# Instalar via Windows Package Manager
winget install OpenJS.NodeJS.LTS

# Reinicie PowerShell, luego verifique
node --version

Opción C: Usando Chocolatey

# Instale Chocolatey primero (si no está instalado)
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Instalar Node.js
choco install nodejs-lts -y

# Reinicie PowerShell
node --version

2. Git para Windows

Usando Instalador Oficial (Recomendado)

  1. Descargue desde git-scm.com
  2. Ejecute el instalador con estas opciones recomendadas:
    • ✅ Git from the command line and also from 3rd-party software
    • ✅ Use bundled OpenSSH
    • ✅ Checkout Windows-style, commit Unix-style line endings
    • ✅ Use Windows' default console window

Usando winget

winget install Git.Git

Verifique la instalación:

git --version

3. GitHub CLI

Usando winget (Recomendado)

winget install GitHub.cli

Usando Chocolatey

choco install gh -y

Autentique:

gh auth login
# Siga las indicaciones, elija "Login with a web browser"

4. Windows Terminal (Recomendado)

Para la mejor experiencia, use Windows Terminal:

winget install Microsoft.WindowsTerminal

Instalación

Instalación Rápida

  1. Abra PowerShell o Windows Terminal

  2. Navegue al directorio de su proyecto:

    cd C:\Users\SuNombre\proyectos\mi-proyecto

  3. Ejecute el instalador:

    npx github:SynkraAI/aiox-core install

Qué Hace el Instalador

El instalador automáticamente:

  • ✅ Detecta Windows y aplica configuraciones específicas de plataforma
  • ✅ Crea directorios necesarios con permisos apropiados
  • ✅ Configura rutas de IDE para ubicaciones Windows:
    • Cursor: %APPDATA%\Cursor\
    • Claude: %USERPROFILE%\.claude\
  • ✅ Maneja separadores de ruta Windows (barras invertidas)
  • ✅ Configura terminaciones de línea correctamente (CRLF para batch, LF para scripts)
  • ✅ Configura scripts npm compatibles con cmd.exe y PowerShell

Configuración Específica por IDE

Cursor

  1. Descargue desde cursor.sh
  2. Ejecute el instalador
  3. Reglas del IDE se instalan en .cursor\rules\
  4. Atajo de teclado: Ctrl+L para abrir chat
  5. Use @nombre-del-agente para activar agentes

Claude Code (CLI)

  1. Instale Claude Code:

    npm install -g @anthropic-ai/claude-code

  2. Comandos se instalan en .claude\commands\AIOX\

  3. Use /nombre-del-agente para activar agentes

  4. Ejecute el instalador

  5. Use @nombre-del-agente para activar agentes

Solución de Problemas

Error de Política de Ejecución

Si ve running scripts is disabled:

# Verificar política actual
Get-ExecutionPolicy

# Configurar para permitir scripts locales (recomendado)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# O bypass temporal para sesión actual
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

Errores de Permiso npm EACCES

# Limpiar caché de npm
npm cache clean --force

# Configurar prefijo npm al directorio del usuario
npm config set prefix "$env:APPDATA\npm"

# Agregar al PATH (permanente)
[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:APPDATA\npm",
    "User"
)

Problemas de Ruta Larga

Windows tiene límite de 260 caracteres por defecto. Para habilitar rutas largas:

  1. Abra Editor de Directivas de Grupo (gpedit.msc)
  2. Navegue a: Configuración del Equipo → Plantillas Administrativas → Sistema → Sistema de Archivos
  3. Habilite "Habilitar rutas largas Win32"

O via PowerShell (requiere admin):

# Ejecutar como Administrador
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Node.js No Encontrado Después de Instalar

# Actualizar variables de entorno
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

# O reinicie PowerShell/Terminal

Antivirus Bloqueando npm

Algunos antivirus bloquean operaciones npm:

  1. Agregue excepciones para:

    • %APPDATA%\npm
    • %APPDATA%\npm-cache
    • %USERPROFILE%\node_modules
    • Su directorio de proyecto

  2. Temporalmente deshabilite escaneo en tiempo real durante instalación (no recomendado para producción)

Problemas de Autenticación GitHub CLI

# Verificar estado
gh auth status

# Re-autenticar
gh auth login --web

# Si está detrás de proxy corporativo
$env:HTTPS_PROXY = "http://proxy.empresa.com:8080"
gh auth login

Integración WSL (Opcional)

Para usuarios que prefieren herramientas Linux dentro de Windows:

Instalar WSL2

# Ejecutar como Administrador
wsl --install

# Instalar Ubuntu (predeterminado)
wsl --install -d Ubuntu

# Reinicie el computador cuando se solicite

Configurar AIOX con WSL

# Dentro de WSL, siga la guía de instalación Linux
# Vea: docs/installation/linux.md

# Acceder archivos Windows desde WSL
cd /mnt/c/Users/SuNombre/proyectos/mi-proyecto

# Para mejor rendimiento, mantenga proyectos en sistema de archivos Linux
# Use: ~/proyectos/ en lugar de /mnt/c/

Actualización

Para actualizar una instalación existente:

# Usando npx (recomendado)
npx github:SynkraAI/aiox-core install

# El actualizador:
# - Detectará instalación existente
# - Hará respaldo de personalizaciones en .aiox-backup\
# - Actualizará solo archivos modificados
# - Preservará configuraciones

Requisitos del Sistema

Requisito Mínimo Recomendado
Windows 10 (22H2) 11
RAM 4GB 8GB
Espacio en Disco 1GB 5GB
Node.js 18.x 20.x LTS
npm 9.x 10.x
PowerShell 5.1 7.x (Core)

Próximos Pasos

  1. Configure su IDE (vea configuración específica por IDE arriba)
  2. Ejecute *help en su agente AI para ver comandos disponibles
  3. Comience con la Guía del Usuario
  4. Únase a nuestra Comunidad en Discord para ayuda

Recursos Adicionales