Instalar OpenSpec

Instalar OpenSpec

OpenSpec gestiona propuestas, especificaciones y registros de cambios. Esta página tiene un objetivo: explicar claramente la ruta de instalación para que pueda adjuntarla a su flujo de trabajo existente.

¿Qué es OpenSpec?

OpenSpec es una herramienta de línea de comandos para gestionar propuestas y especificaciones en el trabajo de software. El flujo de trabajo principal incluye:

• Gestión de propuestas: cree, revise y realice un seguimiento de propuestas de funciones
• Validación de especificaciones: asegúrese de que los cambios de código se ajusten a las especificaciones predefinidas
• Seguimiento de cambios: registre todo el historial de cambios revisado
• Colaboración en equipo: admite el desarrollo colaborativo de varias personas

Aplicación en Proyectos HagiCode

En proyectos HagiCode, OpenSpec se utiliza para:

1. Gestión de desarrollo de funciones: todas las funciones nuevas deben pasar por el proceso de propuesta de OpenSpec
2. Revisión de código: asegúrese de que los cambios cumplan con las especificaciones del proyecto
3. Sincronización de documentación: mantenga la coherencia entre la documentación y la implementación del código
4. Integración de control de versiones: integración perfecta con flujos de trabajo de control de versiones

Requisitos previos

Antes de instalar OpenSpec, asegúrese de que su sistema cumpla con los siguientes requisitos:

Node.js y npm

OpenSpec se distribuye a través de npm y requiere un entorno Node.js. OpenSpec requiere Node.js 18.0 o superior.

Verifique la instalación de Node.js:

node --version

Verifique la instalación de npm:

npm --version

Si no está instalada o la versión es demasiado antigua, consulte las instrucciones de instalación del software relacionado en el Guía de instalación.

Instalación de OpenSpec

Requisitos de versión

Este proyecto requiere el uso de la gama de versiones OpenSpec 1.0.0 o superior. Todas las versiones 1.x son compatibles para garantizar la compatibilidad con el flujo de trabajo del proyecto.

OpenSpec se instala globalmente a través de npm, lo que lo hace disponible desde cualquier lugar de su sistema.

Instalar globalmente usando npm

Windows

Ejecute en PowerShell o símbolo del sistema:

npm install -g @fission-ai/openspec@1

Problemas de permisos de Windows

Si encuentra errores de permisos durante la instalación, ejecute PowerShell o el símbolo del sistema como administrador.

macOS

Ejecutar en la Terminal:

npm install -g @fission-ai/openspec@1

Problemas de permisos de macOS

si te encuentras EACCES errores de permiso, intente:

sudo npm install -g @fission-ai/openspec@1

O usar nvm para administrar las versiones de Node.js y evitar problemas de permisos.

Linux

Ejecutar en la Terminal:

npm install -g @fission-ai/openspec@1

Problemas de permisos de Linux

si te encuentras EACCES errores de permiso, puede:

1. uso sudo: sudo npm install -g @fission-ai/openspec@1
2. Configure npm para usar el directorio de usuarios:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Verificar la instalación

Después de la instalación, verifique que OpenSpec esté instalado correctamente y que la versión cumpla con los requisitos:

openspec --version

Si se instaló correctamente, verá un resultado con el número de versión, por ejemplo:

openspec/1.1.1 linux-x64 node-v18.17.0

Rango de versiones

Asegúrese de que la versión de OpenSpec instalada sea 1.0.0 o superior. El proyecto ha verificado la compatibilidad con la versión 1.1.1. Se recomienda utilizar la última versión compatible para obtener nuevas funciones.

Problemas comunes y solución de problemas

Errores de permiso

Problema: EACCES Permiso denegado

Encontrar errores de permiso al instalar o ejecutar OpenSpec.

Soluciones:

Windows

Ejecute PowerShell o el símbolo del sistema como administrador:

1. Haga clic con el botón derecho en PowerShell o Símbolo del sistema
2. Seleccione “Ejecutar como administrador”
3. Vuelva a ejecutar el comando de instalación

macOS

Instalar usando sudo:

sudo npm install -g @fission-ai/openspec@1

O usar nvm para administrar Node.js y evitar problemas de permisos de instalación global.

Linux

Solución 1: use sudo

sudo npm install -g @fission-ai/openspec@1

Solución 2: configurar npm para usar el directorio de usuarios

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @fission-ai/openspec@1

Problemas de red

Problema: la instalación de npm falla o es muy lenta

No se puede descargar OpenSpec del registro npm por motivos de red.

Soluciones:

1. Usar espejo npm doméstico:

# Use Taobao mirror
npm config set registry https://registry.npmmirror.com

# Then reinstall
npm install -g @fission-ai/openspec@1

2. Restaurar fuente oficial (si es necesario):

npm config set registry https://registry.npmjs.org

3. Utilice cnpm (opcional):

npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install -g @fission-ai/openspec@1

Se recomienda a los usuarios de China continental que utilicen el espejo Taobao, que puede mejorar significativamente la velocidad de descarga.

Problemas de compatibilidad de versiones

Problema: los comandos OpenSpec se ejecutan de forma anormal o informan errores

La versión de OpenSpec instalada es incompatible con el entorno actual.

Soluciones:

1. Verifique la versión de Node.js:

node --version

Asegúrese de que la versión sea 18.0 o superior. Si la versión es demasiado baja, actualice Node.js.

2. Verifique la versión de OpenSpec:

openspec --version

3. Reinstalar la versión específica:

npm install -g @fission-ai/openspec@1

4. Borrar caché npm (si el problema persiste):

npm cache clean --force
npm install -g @fission-ai/openspec@1

Comando no encontrado

Problema: escribir openspec El comando muestra “Comando no encontrado”

OpenSpec está instalado pero el sistema no puede encontrar el comando.

Soluciones:

Windows

1. Confirme la ruta de instalación global de npm:

npm config get prefix

2. Agregar ruta a la RUTA del sistema:
   • Abra “Propiedades del sistema” → “Avanzado” → “Variables de entorno”
   • encontrar Path en “Variables del sistema”
   • Agregue la ruta global de npm (generalmente C:\Users\<username>\AppData\Roaming\npm)
   • Reiniciar la ventana de línea de comando

macOS

1. Confirme la ruta de instalación global de npm:

npm config get prefix

2. Agregar ruta a PATH (en ~/.zshrc o ~/.bash_profile):

export PATH="$(npm config get prefix)/bin:$PATH"

3. Recargar configuración:

source ~/.zshrc

Linux

1. Confirme la ruta de instalación global de npm:

npm config get prefix

2. Agregar ruta a PATH (en ~/.bashrc):

export PATH="$(npm config get prefix)/bin:$PATH"

3. Recargar configuración:

source ~/.bashrc

Actualización de OpenSpec

Rango de versiones

Este proyecto requiere el uso de OpenSpec 1.0.0 o una versión superior. Si tiene requisitos de actualización de versión, consulte la documentación del proyecto.

Si necesita reinstalar una versión específica:

npm install -g @fission-ai/openspec@1

Desinstalar OpenSpec

Si necesita desinstalar OpenSpec:

Windows

npm uninstall -g @fission-ai/openspec

macOS

npm uninstall -g @fission-ai/openspec

O use sudo:

sudo npm uninstall -g @fission-ai/openspec

Linux

npm uninstall -g @fission-ai/openspec

O use sudo:

sudo npm uninstall -g @fission-ai/openspec

Próximos pasos

Una vez completada la instalación de OpenSpec, puede continuar con los siguientes pasos:

Wizard Setup See how first launch checks OpenSpec and related dependencies, then completes project creation inside the wizard.

Create Proposal Session Learn about the proposal-driven development workflow and transform abstract ideas into structured implementation plans.

Para obtener guías de uso de OpenSpec más detalladas, consulte la Documentación oficial de OpenSpec.

¿Necesita más ayuda?

Si encuentra problemas que no se tratan aquí:

1. comprobar Problemas de OpenSpec GitHub para problemas similares
2. Visita Documentación oficial de OpenSpec para más información
3. Consulte las guías relacionadas en el Sitio de documentación de HagiCode para ayuda adicional