Instalar la extensión Naquada para VS Code

Antes de empezar

La extensión controla la CLI local escrita en Rust. Ambos componentes son necesarios.

VS Code 1.96 o posterior.
Una cuenta Naquada en el servicio de producción.
La CLI disponible mediante el comando naquada.
Codex en VS Code para lanzar pipelines desde el chat.

Verificación

Resultado visible: naquada --version responde en el terminal integrado.

Instalar ambos componentes

Instalar la CLI

Sigue primero la guía para macOS, Windows o Linux. La sesión se guarda en el almacén seguro del sistema.

Guía de la CLI de Naquada →

Instalar la extensión

Instala “Naquada for Codex” desde Marketplace y recarga VS Code.

Enlace de distribución no configurado

El operador debe definir NEXT_PUBLIC_NAQUADA_VSCODE_MARKETPLACE_URL con la ficha oficial antes de publicar. No instales paquetes de otro editor.

code --install-extension naquada.naquada-vscode

Comprobar la instalación

Aparece el icono Naquada en la barra de actividad y el comando “Naquada: iniciar sesión” en la paleta.

Conectar el proyecto y Codex

Iniciar sesión

Abre la paleta (⇧⌘P o Ctrl+Shift+P), ejecuta “Naquada: iniciar sesión” y aprueba el código en el navegador.

naquada login

Vincular la carpeta actual

Ejecuta “Naquada: vincular este proyecto”. Elige un nombre y una etiqueta estables. Solo se crea .naquada y un contexto remoto de tu cuenta.

naquada project link --name "Mi proyecto" --tag mi-proyecto

Registrar Naquada en Codex

Ejecuta “Naquada: conectar Codex por MCP”, confirma y recarga la ventana. El comando CLI siguiente hace lo mismo.

naquada setup codex --apply

Comprobación concreta

En la lista MCP de Codex, naquada aparece activo y sus herramientas de planificación son visibles.

Crear un primer asset sin salir de VS Code

Pide un resultado preciso y proporciona siempre una ruta relativa. La ejecución de pago empieza solo tras la aprobación exigida por tu configuración.

Usa Naquada para crear un icono pixel art de un cofre mágico, fondo transparente, 512 × 512. Guarda el original en assets/generated/chest.png. Muéstrame el plan y el coste estimado antes de ejecutar.

Comprueba el modelo, la configuración, las entradas, el coste y assets/generated/chest.png; después aprueba.

Resultado esperado y comprobable

La ejecución aparece en “Naquada — Ejecuciones y assets”.
El recibo local indica la herramienta usada, el plan y la ruta final.
assets/generated/chest.png existe y se abre en VS Code.
El hash figura en .naquada/runs/<run-id>.json.

Dónde se guardan los archivos

Las rutas de Naquada son relativas a la raíz del proyecto abierto.

.naquada/runs/ guarda los recibos de seguimiento y reanudación.
.naquada/assets/ es un búfer temporal, no una biblioteca sincronizada.
El archivo verificado se mueve a la ruta final solicitada.
Solo se envían referencias locales indicadas explícitamente.

Colisión de nombres

Solo se sobrescribe si la IA lo exige explícitamente. En caso contrario, image.png se convierte, por ejemplo, en image-02.png.

Lo que Naquada nunca hace implícitamente

La confianza de VS Code y el consentimiento explícito siguen siendo obligatorios.

No escanea ni envía el repositorio completo.
No sincroniza automáticamente la biblioteca en línea.
No ejecuta comandos Git.
No descarga assets sin ejecución aprobada y recibo local.
La sesión se guarda en el almacén seguro del sistema operativo.

Cerrar VS Code sin perder una generación

La generación continúa en Naquada y la extensión no bloquea el chat.

Al reiniciar, solo lee recibos aprobados de .naquada/runs/.
Reanuda descargas y verifica SHA-256.
Una notificación confirma la entrega o señala el problema.
También puedes reanudar manualmente desde la vista Naquada.

Diagnóstico en menos de un minuto

Ejecuta “Naquada: diagnosticar integración” o este comando.

naquada --json doctor

authenticated debe ser true.
projectLinked debe ser true.
apiReachable debe ser true.
gitTouched siempre debe ser false.

Resultado

Con ok: true, la cuenta, el proyecto, la API y los directorios de reanudación están listos.