Instale o OpenSpec

Instale o OpenSpec

OpenSpec gerencia propostas, especificações e registros de alterações. Esta página tem um objetivo: explicar claramente o caminho de instalação para que você possa anexá-lo ao seu fluxo de trabalho existente.

O que é OpenSpec?

OpenSpec é uma ferramenta de linha de comando para gerenciar propostas e especificações em trabalho de software. O fluxo de trabalho principal inclui:

• Gerenciamento de propostas: crie, revise e acompanhe propostas de recursos
• Validação de especificação: garanta que as alterações no código estejam em conformidade com as especificações predefinidas
• Acompanhamento de alterações: registre todo o histórico de alterações revisado
• Colaboração em equipe: Apoie o desenvolvimento colaborativo de várias pessoas

Aplicação em Projetos HagiCode

Em projetos HagiCode, OpenSpec é usado para:

1. Gerenciamento de desenvolvimento de recursos: todos os novos recursos devem passar pelo processo de proposta OpenSpec
2. Revisão do código: garanta que as alterações estejam em conformidade com as especificações do projeto
3. Sincronização de documentação: mantenha a consistência entre a documentação e a implementação do código
4. Integração de controle de versão: integração perfeita com fluxos de trabalho de controle de versão

Pré-requisitos

Antes de instalar o OpenSpec, certifique-se de que seu sistema atenda aos seguintes requisitos:

Node.js e npm

OpenSpec é distribuído via npm e requer um ambiente Node.js. OpenSpec requer Node.js 18.0 ou superior.

Verifique a instalação do Node.js:

node --version

Verifique a instalação do npm:

npm --version

Se não estiver instalado ou a versão for muito antiga, consulte as instruções de instalação do software relacionado no Guia de instalação.

Instalando o OpenSpec

Requisitos de versão

Este projeto requer o uso do intervalo de versões OpenSpec 1.0.0 ou superior. Todas as versões 1.x são suportadas para garantir compatibilidade com o fluxo de trabalho do projeto.

O OpenSpec é instalado globalmente via npm, disponibilizando-o em qualquer lugar do seu sistema.

Instale globalmente usando npm

Windows

Execute no PowerShell ou prompt de comando:

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

Problemas de permissão do Windows

Se você encontrar erros de permissão durante a instalação, execute o PowerShell ou o prompt de comando como administrador.

macOS

Execute no Terminal:

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

Problemas de permissão do macOS

Se você encontrar EACCES erros de permissão, tente:

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

Ou use nvm para gerenciar versões do Node.js e evitar problemas de permissão.

Linux

Execute no Terminal:

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

Problemas de permissão do Linux

Se você encontrar EACCES erros de permissão, você pode:

1. Usar sudo: sudo npm install -g @fission-ai/openspec@1
2. Configure o npm para usar o diretório de usuários:

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

Verifique a instalação

Após a instalação, verifique se o OpenSpec está instalado corretamente e se a versão atende aos requisitos:

openspec --version

Se instalado com sucesso, você verá uma saída de número de versão, por exemplo:

openspec/1.1.1 linux-x64 node-v18.17.0

Intervalo de versões

Certifique-se de que a versão instalada do OpenSpec seja 1.0.0 ou superior. O projeto verificou compatibilidade com a versão 1.1.1. Recomenda-se usar a versão compatível mais recente para obter novos recursos.

Problemas comuns e solução de problemas

Erros de permissão

Problema: EACCES Permissão negada

Encontrando erros de permissão ao instalar ou executar o OpenSpec.

Soluções:

Windows

Execute o PowerShell ou prompt de comando como administrador:

1. Clique com o botão direito em PowerShell ou Prompt de Comando
2. Selecione “Executar como administrador”
3. Execute novamente o comando de instalação

macOS

Instalar usando sudo:

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

Ou use nvm para gerenciar o Node.js e evitar problemas de permissão de instalação global.

Linux

Solução 1: use sudo

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

Solução 2: configure o npm para usar o diretório de usuários

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 rede

Problema: a instalação do npm falha ou é muito lenta

Não foi possível baixar o OpenSpec do registro npm devido a motivos de rede.

Soluções:

1. Usar espelho 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 fonte oficial (se necessário):

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

3. Usar cnpm (opcional):

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

Recomenda-se que os usuários na China continental usem o espelho Taobao, que pode melhorar significativamente a velocidade de download.

Problemas de compatibilidade de versão

Problema: comandos OpenSpec são executados de maneira anormal ou relatam erros

A versão instalada do OpenSpec é incompatível com o ambiente atual.

Soluções:

1. Verifique a versão do Node.js:

node --version

Certifique-se de que a versão seja 18.0 ou superior. Se a versão for muito baixa, atualize o Node.js.

2. Verifique a versão do OpenSpec:

openspec --version

3. Reinstalar versão específica:

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

4. Limpar cache npm (se o problema persistir):

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

Comando não encontrado

Problema: Digitação openspec Comando mostra “Comando não encontrado”

O OpenSpec está instalado, mas o sistema não consegue encontrar o comando.

Soluções:

Windows

1. Confirme o caminho de instalação global do npm:

npm config get prefix

2. Adicione o caminho ao PATH do sistema:
   • Abra “Propriedades do Sistema” → “Avançado” → “Variáveis de Ambiente”
   • Encontrar Path em “Variáveis do sistema”
   • Adicione o caminho global npm (geralmente C:\Users\<username>\AppData\Roaming\npm)
   • Reinicie a janela da linha de comando

macOS

1. Confirme o caminho de instalação global do npm:

npm config get prefix

2. Adicione o caminho ao PATH (em ~/.zshrc ou ~/.bash_profile):

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

3. Configuração de recarga:

source ~/.zshrc

Linux

1. Confirme o caminho de instalação global do npm:

npm config get prefix

2. Adicione o caminho ao PATH (em ~/.bashrc):

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

3. Configuração de recarga:

source ~/.bashrc

Atualizando o OpenSpec

Intervalo de versões

Este projeto requer o uso do OpenSpec 1.0.0 ou versão superior. Se você tiver requisitos de atualização de versão, consulte a documentação do projeto.

Se você precisar reinstalar uma versão específica:

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

Desinstalando o OpenSpec

Se você precisar desinstalar o OpenSpec:

Windows

npm uninstall -g @fission-ai/openspec

macOS

npm uninstall -g @fission-ai/openspec

Ou use sudo:

sudo npm uninstall -g @fission-ai/openspec

Linux

npm uninstall -g @fission-ai/openspec

Ou use sudo:

sudo npm uninstall -g @fission-ai/openspec

Próximas etapas

Após a conclusão da instalação do OpenSpec, você poderá continuar com as seguintes etapas:

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 guias de uso mais detalhados do OpenSpec, consulte o Documentação oficial do OpenSpec.

Precisa de mais ajuda?

Se você encontrar problemas não abordados aqui:

1. Verifique Problemas do OpenSpec GitHub para problemas semelhantes
2. Visite Documentação oficial do OpenSpec para mais informações
3. Consulte os guias relacionados no Site de documentação do HagiCode para ajuda adicional