跳转到内容
Hagicode Docs
網誌

安裝 OpenSpec

编辑此页

安裝 OpenSpec

Section titled “安裝 OpenSpec”

OpenSpec 管理提案、規格和變更記錄。此页面致力于实现一个目标：清楚地解释安装路径，以便您可以将其附加到现有的工作流程中。

什么是 OpenSpec？

Section titled “什么是 OpenSpec？”

OpenSpec 是一個命令列工具，用於管理軟體工作中的提案和規格。核心工作流程包括：

  • 提案管理：创建、审查和跟踪功能提案
  • 規範驗證：確保程式碼變更符合預先定義的規範
  • 變更追蹤：記錄所有已審核的變更歷史記錄
  • 團隊協作：支援多人協作開發

在HagiCode專案中的應用

Section titled “在HagiCode專案中的應用”

在 HagiCode 專案中，OpenSpec 用於：

  1. 功能开发管理：所有新功能都必须经过 OpenSpec 提案流程
  2. 代码审查：确保更改符合项目规范
  3. 文檔同步：保持文檔和程式碼實現的一致性
  4. 版本控制集成：與版本控制工作流程無縫集成

先決條件

Section titled “先決條件”

在安裝 OpenSpec 之前，請確保您的系統符合以下要求：

Node.js 和 npm

Section titled “Node.js 和 npm”

OpenSpec 透過 npm 分發，需要 Node.js 環境。 OpenSpec 需要 Node.js 18.0 或更高版本。

驗證 Node.js 安裝：

Terminal window
node --version

驗證 npm 安裝：

Terminal window
npm --version

若未安裝或版本過舊，請參考相關軟體安裝說明 安裝指南.

安裝 OpenSpec

Section titled “安裝 OpenSpec”

:::提示[版本要求] 此專案需要使用OpenSpec 1.0.0 或更高版本範圍。支援所有 1.x 版本，以確保與專案工作流程的兼容性。 :::

OpenSpec 透過 npm 在全球範圍內安裝，使其可以從系統上的任何位置使用。

使用 npm 全域安裝

Section titled “使用 npm 全域安裝”

在 PowerShell 或命令提示字元中執行：

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

:::注意[Windows 權限問題] 如果在安裝過程中遇到權限錯誤，請以管理員身分執行 PowerShell 或命令提示字元。 :::

驗證安裝

Section titled “驗證安裝”

安裝完成後，驗證OpenSpec是否安裝正確且版本符合要求：

Terminal window
openspec --version

如果安裝成功，您將看到版本號輸出，例如：

openspec/1.1.1 linux-x64 node-v18.17.0

:::注意[版本範圍] 請確保安裝的 OpenSpec 版本為 1.0.0 或更高版本。該專案已驗證與1.1.1版本的兼容性。建議使用最新的兼容版本以獲得新功能。 :::

常見問題和故障排除

Section titled “常見問題和故障排除”

權限錯誤

Section titled “權限錯誤”

問題： EACCES 權限被拒絕

Section titled “問題： EACCES 權限被拒絕”

安裝或執行 OpenSpec 時遇到權限錯誤。

解決方案：

以管理員身分執行 PowerShell 或命令提示字元：

  1. 右鍵點選 PowerShell 或命令提示符
  2. 選擇“以管理員身份執行”
  3. 重新運行安裝命令

網路問題

Section titled “網路問題”

問題：npm 安裝失敗或非常慢

Section titled “問題：npm 安裝失敗或非常慢”

由於網路原因，無法從 npm 註冊表下載 OpenSpec。

解決方案：

  1. 使用國內npm鏡像：
Terminal window
# Use Taobao mirror
npm config set registry https://registry.npmmirror.com


# Then reinstall
npm install -g @fission-ai/openspec@1
  1. 恢復官方來源（如果需要）：
Terminal window
npm config set registry https://registry.npmjs.org
  1. 使用 cnpm （可選）：
Terminal window
npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install -g @fission-ai/openspec@1

:::提示 推薦中國大陸用戶使用淘寶鏡像，可顯著提高下載速度。 :::

版本相容性問題

Section titled “版本相容性問題”

問題：OpenSpec 指令運行異常或報告錯誤

Section titled “問題：OpenSpec 指令運行異常或報告錯誤”

安裝的 OpenSpec 版本與目前環境不相容。

解決方案：

  1. 檢查 Node.js 版本：
Terminal window
node --version

確保版本為 18.0 或更高版本。如果版本過低，請升級Node.js。

  1. 檢查 OpenSpec 版本：
Terminal window
openspec --version
  1. 重新安裝特定版本：
Terminal window
npm install -g @fission-ai/openspec@1
  1. 清除 npm 快取（如果問題仍然存在）：
Terminal window
npm cache clean --force
npm install -g @fission-ai/openspec@1

未找到指令

Section titled “未找到指令”

問題：打字 openspec 命令顯示“未找到命令”

Section titled “問題：打字 openspec 命令顯示“未找到命令””

OpenSpec 已安裝，但係統找不到該指令。

解決方案：

  1. 確認npm全域安裝路徑：
Terminal window
npm config get prefix
  1. 新增路徑到系統PATH：
    • 開啟“系統屬性”→“進階”→“環境變數”
    • 尋找 Path 在「系統變數」中
    • 新增npm全域路徑（通常 C:\Users\<username>\AppData\Roaming\npm)
    • 重新啟動命令列視窗

升級 OpenSpec

Section titled “升級 OpenSpec”

:::注意[版本範圍] 此專案需要使用 OpenSpec 1.0.0 或更高版本範圍。如果您有版本更新需求，請參考專案文件。 :::

如果您需要重新安裝特定版本：

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

卸載 OpenSpec

Section titled “卸載 OpenSpec”

如果需要解除安裝 OpenSpec：

Terminal window
npm uninstall -g @fission-ai/openspec

下一步

Section titled “下一步”

OpenSpec 安裝完成後，您可以繼續執行下列步驟：

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.

:::提示 更詳細的OpenSpec使用指南，請參考 OpenSpec 官方文檔. :::

需要更多幫助嗎？

Section titled “需要更多幫助嗎？”

如果您遇到此處未涵蓋的問題：

  1. 檢查 OpenSpec GitHub 問題 對於類似的問題
  2. 參觀 OpenSpec 官方文檔 欲了解更多信息
  3. 請參閱相關指南 HagiCode文件網站 如需更多協助