OpenSpec

安装 ​

在您的机器上安装 openspec CLI、更新和卸载它。

安装 ​

在 macOS 或 Linux 上，在终端中执行：

bash
curl -fsSL https://openspec.dev/cli/install.sh | sh

在 Windows 上，在 PowerShell 中执行：

powershell
irm https://openspec.dev/cli/install.ps1 | iex

如果安装程序打印了 export PATH=... 行，请运行它。然后检查是否成功。

使用您的 AI 助手安装 ​

将以下内容粘贴到您的 AI 聊天中：

text
Fetch https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md and follow it.

或者，在终端中，将其通过管道传输到 CLI 代理（以 Claude Code 为例）：

bash
curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md | claude

这将获取 仓库根目录下的 install.md，这是一个为任何可以运行 shell 命令的代理编写的提示词（某些 IDE 集成无法做到）。预期您的助手会：

  1. 如果 CLI 已在您的机器上，则跳过安装，并提供按其安装方式进行更新。如果那是 npm 或 Homebrew，提一次 openspec install 会切换到独立安装，但不要强行推销。否则，向您展示上面的安装命令，并在运行前等待您的确认。
  2. 仅在您要求或安装程序失败时使用 npm，如果您的 Node 版本低于 22.12.0，则停止。
  3. 验证 openspec 是否在您的 PATH 上。
  4. 说出它认为您指的是哪个文件夹，建议使用您已经在交谈的 AI 工具，并询问您还使用哪些其他工具，然后在其中运行 openspec init（项目设置步骤）。
  5. 报告 init 创建的内容以及在您的工具中调用 OpenSpec 的确切拼写。

它在任何需要权限的操作之前停止，绝不编辑您的 shell 启动文件。上面的安装命令和下面的包管理器是真实来源，提示词会为您运行它们。

这种安装方法是新推出的，根据使用的模型不同，结果可能有所差异。仅当您能够接受纠正 AI 错误时才使用。否则，我们建议按照下面的标准方法操作。

包管理器 ​

这些方法将 OpenSpec 安装为 Node.js 包，因此需要 Node.js 22.12.0 或更新版本（Homebrew 和 Nix 自带）。在终端中执行：

bash
node --version

如果打印 v22.12.0 或更高版本，使用 npm 安装：

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

如果没有，从 nodejs.org 或通过您的版本管理器（nvm、fnm、asdf、volta）安装更新的 Node，或者使用独立安装。

Homebrew ​

Homebrew 在 macOS 或 Linux 上安装 OpenSpec 及其 Node.js 依赖。在终端中执行：

bash
brew install openspec

该 formula 发布在 homebrew-core 中，因此您不需要添加 tap。

Yarn ​

yarn global add 仅适用于 Yarn Classic (1.x)。现代 Yarn 已移除全局安装功能，因此请改用 npm、pnpm 或 bun。全局 CLI 不必与您的项目共享包管理器。

Bun ​

Bun 可以安装 OpenSpec 但无法运行它，因此您仍然需要在机器上安装 Node（参见包管理器）。没有 Node，每个命令都会失败并报错 env: node: No such file or directory。Bun 对每个 Node CLI都是这样处理的。

Deno ​

Deno 从 npm 安装 CLI，需要显式的权限标志。在终端中执行：

bash
deno install --global \
  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
  npm:@fission-ai/openspec@latest

某些命令会启动另一个程序：openspec config edit 会打开您的编辑器。Deno 会在每次运行时以权限提示中断这些操作。要停止提示，请在安装命令中添加作用域限定的 --allow-run=<program>。

NOTE

如果 Deno 无法解析 @latest，请固定版本范围：npm:@fission-ai/openspec@^1.7.0。

Nix ​

OpenSpec 仓库附带一个 Nix flake。将其安装到您的 profile 中。在终端中执行：

bash
nix profile install github:Fission-AI/OpenSpec

或者先运行一次性命令，不安装：

bash
nix run github:Fission-AI/OpenSpec -- --version

这不会在您的 PATH 上留下任何东西，因此之后无需检查安装。

如果要将 OpenSpec 放入项目开发环境（dev shell），请将 flake 添加为输入并使用其默认包；flake.nix 列出了输出。

Nix 包在标准位置提供了 Bash、Fish 和 Zsh 补全脚本 （share/bash-completion/completions、share/fish/vendor_completions.d、 share/zsh/site-functions），因此它们随包一起加载，无需运行 openspec completion install。

检查是否成功 ​

无论您使用哪种方法，在终端中执行：

bash
openspec --version

如果打印版本号，说明 CLI 已在您的 PATH 上。它每台机器只需安装一次。

接下来，设置您的项目。如果您的助手已经运行了 init，该页面会显示它写入的内容以及如何调整。

安装选项 ​

要选择版本或文件夹，在 sh 之前设置变量：

bash
curl -fsSL https://openspec.dev/cli/install.sh | OPENSPEC_VERSION=v1.15.0 sh
  • OPENSPEC_VERSION：要安装的发行版，例如 v1.15.0。默认是最新发行版。
  • OPENSPEC_INSTALL_DIR：要安装到的文件夹。默认是 ~/.local/bin（Windows：%LOCALAPPDATA%\Programs\openspec）。

在 Windows 上，先设置变量：

powershell
$env:OPENSPEC_VERSION = 'v1.15.0'
irm https://openspec.dev/cli/install.ps1 | iex

在 Alpine Linux 上，安装前先运行 apk add libstdc++ libgcc。

手动下载 ​

每个发行版为每台计算机提供一个文件：

计算机文件
Mac，Apple 芯片openspec-darwin-arm64.tar.gz
Mac，Intelopenspec-darwin-x64.tar.gz
Linux，arm64openspec-linux-arm64.tar.gz
Linux，x64openspec-linux-x64.tar.gz
Alpine，arm64openspec-linux-arm64-musl.tar.gz
Alpine，x64openspec-linux-x64-musl.tar.gz
Windows，arm64openspec-windows-arm64.zip
Windows，x64openspec-windows-x64.zip
  1. 下载您的文件，从最新发行版获取。文件会在发行版发布几分钟后附加。如果您的不在列表中，请等待并重新加载，或从上一个发行版中获取。
  2. 解包。在终端中：tar -xzf openspec-darwin-arm64.tar.gz。在 Windows 上，右键单击 .zip 并选择"全部解压缩"。
  3. 在 macOS 上，在您解包的文件夹中运行 xattr -d com.apple.quarantine openspec。macOS 会阻止在浏览器中下载的文件，直到您执行此操作。
  4. 移动 openspec 到 PATH 上的文件夹，例如 ~/.local/bin。在 Windows 上，将 openspec.exe 移动到用户 PATH 上的文件夹，例如 %LOCALAPPDATA%\Programs\openspec。

验证下载 ​

要检查文件是否由 OpenSpec 发行工作流构建，使用 GitHub CLI 运行以下命令：

bash
gh attestation verify openspec-darwin-arm64.tar.gz --repo Fission-AI/OpenSpec

如果工作流没有构建该文件，则会失败。安装命令已经根据发行版的 SHA256SUMS 检查每个下载，因此此步骤是可选的。

从 npm 切换到独立安装 ​

切换是可选的；npm 仍然可以工作。您的设置和项目会保留；只是程序变了。

1. 安装独立副本。 在终端中执行：

bash
openspec install

它会安装独立的 openspec 并打印移除 npm 或 Homebrew 副本的命令。

2. 移除旧副本。 它通常在 PATH 上排在前面，因此在删除之前它会一直运行。运行步骤 1 打印的命令，例如：

npm
npm uninstall -g @fission-ai/openspec

3. 检查运行的是哪个副本。 打开一个新终端：

bash
openspec version

它应该打印 OpenSpec <version> (standalone)。如果它显示的是包管理器，说明 PATH 上还有另一个副本：which -a openspec（Windows：where.exe openspec）会列出每个副本，请删除其他副本。

不需要重新初始化任何项目。要切换回去，删除文件并重新运行 npm 安装。

更新 ​

在终端中，在每个运行过 init 的项目中执行：

bash
openspec update

当有更新的 CLI 时，openspec update 会告知并可以为您安装；该升级每台机器只需一次。每次运行都会刷新项目生成的技能和命令，这些不会自行更新。当前项目会打印 ✓ All 2 tool(s) up to date (v1.7.0)。

WARNING

使用独立安装时，运行 openspec install 来就地替换您的副本；openspec update 会告知何时有新版本。在 Homebrew 上，运行 brew upgrade openspec。在 Deno 上，使用 -f 重新运行 Deno 安装；没有 -f 它不会覆盖已安装的命令。在 Nix 上，使用 nix profile upgrade openspec。

NOTE

全局 npm 安装属于一个 Node 安装。使用 nvm 切换 Node 版本时，openspec 命令不会跟过来，因此请在新版本下重新安装。

卸载 ​

要卸载 OpenSpec，请按照以下步骤操作；它们都不会触及您的源代码。您也可以将您的代理指向此部分，让它处理移除。

1. 移除 shell 补全（如果您设置了），趁 CLI 还能执行此操作时。在终端中执行：

bash
openspec completion uninstall

2. 移除 CLI。 对于独立安装，删除 ~/.local/bin/openspec（Windows：%LOCALAPPDATA%\Programs\openspec，并从用户 PATH 中移除该文件夹）。对于 npm，在终端中执行：

npm
npm uninstall -g @fission-ai/openspec

在 Homebrew 上：brew uninstall openspec。在 Deno 上：deno uninstall --global openspec。在 Nix 上：nix profile remove openspec。您的 shell 应该不再找到 openspec。

3. 删除剩余内容，或保留它。

  • 生成的代理文件：openspec-* 技能和 opsx 命令，位于 .claude/ 或 .agents/ 等目录下，按项目分。支持的工具列出了每个工具的路径；MiniMax Code 将技能保存在 ~/.minimax/skills 中。
  • 旧版本的残留物：CLAUDE.md 或 AGENTS.md 中的标记块（删除块，保留文件）以及 ~/.codex/prompts 中的 opsx-*.md 提示词。
  • openspec/ 文件夹：先暂停。specs/ 和 changes/archive/ 是您对系统的记录，是纯 Markdown，没有 OpenSpec 也能正常阅读。
  • 每台机器的状态：~/.config/openspec/ 中的设置和遥测 ID；~/.local/share/openspec/（Windows：%APPDATA%\openspec、%LOCALAPPDATA%\openspec）中的 schema 覆盖、存储注册表和独立安装的内置 schema（binary-schemas/）。注册是指针；它们指向的存储库不受影响。