安装 OpenSpec
安装 OpenSpec
Section titled “安装 OpenSpec”OpenSpec 是一个规范驱动开发工具，用于管理提案、规范和变更。它帮助团队通过结构化的方式管理工作流程，确保所有变更都经过审查和验证。本指南将指导您完成 OpenSpec 的安装过程。
什么是 OpenSpec？
Section titled “什么是 OpenSpec？”OpenSpec 是一个命令行工具，专门用于管理软件开发过程中的提案（Proposals）和规范（Specifications）。它提供了一套完整的工作流程，包括：
- 提案管理：创建、审查和跟踪功能提案
- 规范验证：确保代码变更符合预定义的规范
- 变更追踪：记录所有经过审查的变更历史
- 团队协作：支持多人协作开发
在 PCode 项目中的应用
Section titled “在 PCode 项目中的应用”在 PCode 项目中，OpenSpec 用于：
- 管理功能开发：所有新功能都需要通过 OpenSpec 提案流程
- 代码审查：确保变更符合项目规范
- 文档同步：保持文档与代码实现的一致性
- 版本控制集成：与版本控制工作流无缝集成
在安装 OpenSpec 之前，请确保您的系统已满足以下要求：
Node.js 和 npm
Section titled “Node.js 和 npm”OpenSpec 通过 npm 分发，需要 Node.js 环境。OpenSpec 要求 Node.js 18.0 或更高版本。
验证 Node.js 安装：
node --version验证 npm 安装：
npm --version如果未安装或版本过低，请参考安装指南中的相关软件安装说明。
安装 OpenSpec
Section titled “安装 OpenSpec”OpenSpec 通过 npm 全局安装，使其在系统的任何位置都可用。
使用 npm 全局安装
Section titled “使用 npm 全局安装”在 PowerShell 或命令提示符中运行：
npm install -g @fission-ai/openspec@0.23.0在终端中运行：
npm install -g @fission-ai/openspec@0.23.0在终端中运行：
npm install -g @fission-ai/openspec@0.23.0安装完成后，验证 OpenSpec 是否正确安装且版本符合要求：
openspec --version如果安装成功，您将看到版本号输出，例如：
openspec/0.23.0 linux-x64 node-v18.17.0:::warning 版本兼容性 请确保安装的是 0.23.0 版本。不要升级到 1.0 或更高版本，因为这些版本包含破坏性变更，与当前项目工作流不兼容。 :::
常见问题和故障排除
Section titled “常见问题和故障排除”问题：EACCES 权限被拒绝
Section titled “问题：EACCES 权限被拒绝”在安装或运行 OpenSpec 时遇到权限错误。
解决方案：
以管理员身份运行 PowerShell 或命令提示符：
- 右键点击 PowerShell 或命令提示符
- 选择”以管理员身份运行”
- 重新运行安装命令
使用 sudo 安装：
sudo npm install -g @fission-ai/openspec@0.23.0或使用 nvm 管理 Node.js，避免全局安装权限问题。
方案 1：使用 sudo
sudo npm install -g @fission-ai/openspec@0.23.0方案 2：配置 npm 使用用户目录
mkdir -p ~/.npm-globalnpm config set prefix '~/.npm-global'echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrcsource ~/.bashrcnpm install -g @fission-ai/openspec@0.23.0问题：npm 安装失败或速度很慢
Section titled “问题：npm 安装失败或速度很慢”由于网络原因，无法从 npm registry 下载 OpenSpec。
解决方案：
- 使用国内 npm 镜像：
# 使用淘宝镜像npm config set registry https://registry.npmmirror.com
# 然后重新安装npm install -g @fission-ai/openspec@0.23.0- 恢复官方源（如果需要）：
npm config set registry https://registry.npmjs.org- 使用 cnpm（可选）：
npm install -g cnpm --registry=https://registry.npmmirror.comcnpm install -g @fission-ai/openspec@0.23.0版本兼容性问题
Section titled “版本兼容性问题”问题：OpenSpec 命令运行异常或报错
Section titled “问题：OpenSpec 命令运行异常或报错”安装的 OpenSpec 版本与当前环境不兼容。
解决方案：
- 检查 Node.js 版本：
node --version确保版本为 18.0 或更高。如果版本过低，请升级 Node.js。
- 检查 OpenSpec 版本：
openspec --version- 重新安装特定版本：
npm install -g @fission-ai/openspec@0.23.0- 清理 npm 缓存（如果问题持续）：
npm cache clean --forcenpm install -g @fission-ai/openspec@0.23.0问题：输入 openspec 命令提示”命令未找到”
Section titled “问题：输入 openspec 命令提示”命令未找到””OpenSpec 已安装但系统无法找到该命令。
解决方案：
- 确认 npm 全局安装路径：
npm config get prefix- 将路径添加到系统 PATH：
- 打开”系统属性” → “高级” → “环境变量”
- 在”系统变量”中找到
Path - 添加 npm 全局路径（通常是
C:\Users\<用户名>\AppData\Roaming\npm） - 重启命令行窗口
- 确认 npm 全局安装路径：
npm config get prefix- 将路径添加到 PATH（在
~/.zshrc或~/.bash_profile中）：
export PATH="$(npm config get prefix)/bin:$PATH"- 重新加载配置：
source ~/.zshrc- 确认 npm 全局安装路径：
npm config get prefix- 将路径添加到 PATH（在
~/.bashrc中）：
export PATH="$(npm config get prefix)/bin:$PATH"- 重新加载配置：
source ~/.bashrc升级 OpenSpec
Section titled “升级 OpenSpec”:::warning 版本锁定 本项目要求使用 OpenSpec 0.23.0 版本。不要升级到其他版本，除非项目明确要求。 :::
如果需要重新安装特定版本：
npm install -g @fission-ai/openspec@0.23.0卸载 OpenSpec
Section titled “卸载 OpenSpec”如果需要卸载 OpenSpec：
npm uninstall -g @fission-ai/openspecnpm uninstall -g @fission-ai/openspec或使用 sudo：
sudo npm uninstall -g @fission-ai/openspecnpm uninstall -g @fission-ai/openspec或使用 sudo：
sudo npm uninstall -g @fission-ai/openspecOpenSpec 安装完成后，您可以：
- 学习 OpenSpec 基础：了解提案和规范的基本概念
- 在项目中使用：在 PCode 项目中使用 OpenSpec 管理变更
- 配置团队工作流：为团队设置 OpenSpec 工作流程
需要更多帮助？
Section titled “需要更多帮助？”如果您遇到此处未涵盖的问题：
- 查看 OpenSpec GitHub Issues 寻找类似问题
- 访问 OpenSpec 官方文档 获取更多信息
- 参考 PCode 文档站点 寻求帮助