OpenSpec

安装 ​

前置条件 ​

  • Node.js 20.19.0 或更高版本 — 检查你的版本：node --version

使用 AI 助手安装 ​

不想手动操作？将以下提示词粘贴到任何支持运行 Shell 命令的编码助手中——Claude Code、Codex、Cursor、Gemini CLI、Copilot 以及其余受支持的工具。它将安装 CLI，初始化此项目，并报告实际发生的情况。

下面的手动步骤是权威来源——提示词只是为你执行这些步骤。如果你的助手停止并返回某些内容，这是设计使然：它在涉及特权操作前会询问，并且绝不会编辑你的 Shell 启动文件。请通过包管理器和故障排除自行完成剩余部分。

text
在此项目中安装 OpenSpec 并为我设置好。按顺序执行以下步骤，并在某一步骤指示你停止时停止。

1. 运行时环境 (RUNTIME)。运行 `node --version`。OpenSpec 需要 Node.js 20.19.0 或更高版本。如果
   缺少 Node 或版本过低，请说明情况并停止——不要安装 Node，不要切换版本，也不要为我重新配置
   我的版本管理器。

2. 安装 (INSTALL)。使用我 PATH 中已有的任何包管理器，优先选择 npm：
     npm install -g @fission-ai/openspec@latest
     pnpm add -g @fission-ai/openspec@latest
     bun add -g @fission-ai/openspec@latest
     yarn global add @fission-ai/openspec@latest   (仅限 Yarn 1.x)
   不要根据此项目的 lockfile 进行选择——全局安装与此仓库自身依赖的安装方式无关。如果这四个都不可用，
   请停止并告诉我——不要即兴发挥进行安装。（如果我使用的是 Nix，请指引我查看 OpenSpec 安装文档中的
   Nix 部分。）向我展示确切的命令，并在运行前让我确认；这是在项目外部安装软件，我可能希望由不同的
   包管理器来管理它。
   如果安装需要 sudo 或管理员权限、因权限错误失败，或报告其全局 bin 目录缺失或未配置，请停止并再次
   询问我。绝不编辑我的 shell 启动文件 (.bashrc, .zshrc, .profile, fish, PowerShell profile)，也绝不
   运行任何为我编辑这些文件的设置命令——向我展示更改，让我自己执行。

3. PATH。运行 `openspec --version`。如果找不到该命令，可能只是当前 shell 中缺失：告诉我包管理器将其
   安装在哪里，以及如何将该目录添加到我的 shell 和 OS 的 PATH 中，然后停止直到我确认。如果它打印出的
   版本低于安装刚报告的版本，说明 PATH 上有一个较早的副本遮蔽了它——请告诉我这两个版本，而不是继续。
   如果我使用版本管理器，请说明情况，而不是围绕它修改 PATH：对于 nvm 或 fnm，CLI 与安装时活跃的 Node
   版本绑定；对于 asdf 或 volta，可能需要重新生成 shim。

4. 初始化 (INITIALIZE)。询问我使用哪些 AI 编码工具，并将每个工具映射到 `openspec init --help` 中的 id
   （Copilot 是 `github-copilot`，Zoo Code 是 `roocode`）。`--tools` 接受逗号分隔的列表，因此列出所有
   它们。`openspec init --tools <ids>` 会自动删除旧版 OpenSpec 版本的残留物，无需询问——包括我主目录中的
   `opsx-*.md` 提示文件（Codex 将它们保存在 ~/.codex/prompts 中）。在运行之前，查找这些文件：`.../commands/openspec/`
   文件夹、CLAUDE.md 或 AGENTS.md 等文件中的 OpenSpec 标记块，以及主目录中的 `opsx-*.md` 提示。列出你找到的
   所有内容并等待我的许可；如果没找到任何东西，请说明情况并继续，无需询问。现有的 `openspec/` 文件夹不是问题——
   init 会刷新它并保留我的 specs 和 changes 不变。
   同时确认我在正确的文件夹中：init 会在其运行的任何位置创建 `openspec/`，包括 monorepo 包内部。
   然后运行：openspec init --tools <ids>

5. 报告 (REPORT)。不要假设应该存在什么——告诉我 init 实际打印了什么：创建了多少个 skills 和/或 commands，
   它们的位置，配置文件行，任何“需要设置”的说明，以及需要重启或重载的内容。有些工具仅包含 skills，正确创建了
   零个 command 文件，因此缺少 commands 本身并不是失败。如果 init 说没有生成任何内容，请传达它建议的修复方法，
   而不是重试。最后告诉我如何在工具中调用 OpenSpec，并从 init 创建的文件中获取确切的拼写，而不是从它的摘要行中：
   标点符号因工具而异（某些工具中使用 /opsx:propose，其他工具中使用 /opsx-propose，Amazon Q 中使用 @opsx-propose），
   获得 skills 而非 commands 的工具通过 skill 名称调用（/openspec-propose，或在 Codex 中为 $openspec-propose，
   或在 Kimi Code 中为 /skill:openspec-propose）。

提示词中没有供应商特定的内容：它是普通指令加上本页记录的相同命令。它在 macOS、Linux 和 Windows 上都能工作，并且在某一步骤需要你的许可时会故意停止而不是即兴发挥。你的助手需要能够运行 Shell 命令——一些 IDE 集成无法做到这一点。

包管理器 ​

npm ​

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

pnpm ​

bash
pnpm add -g @fission-ai/openspec@latest

yarn ​

bash
yarn global add @fission-ai/openspec@latest

Yarn 2 及更高版本（Berry）移除了 global 命令。在这些版本上，请使用 npm、pnpm 或 bun 安装 OpenSpec——全局 CLI 不需要共享你项目的包管理器。

deno ​

Deno 有时在解析 @latest 标签时会有问题，但我们可以在初始安装时指定一个版本。 如果出现这种情况，你可以尝试将 @latest 标签替换为版本号，例如 @^1.3.1

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

注意：如果你的子命令启动外部工具，如配置编辑、反馈或工作区打开，你可能需要作用域的 --allow-run=<program>。

bun ​

Bun 可以全局安装 OpenSpec，但 OpenSpec 目前运行在 Node.js 上。 你仍然需要在 PATH 上可用 Node.js 20.19.0 或更高版本。

bash
bun add -g @fission-ai/openspec@latest

Nix ​

直接运行 OpenSpec 而无需安装：

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

或者安装到你的 profile 中：

bash
nix profile install github:Fission-AI/OpenSpec

或者将其添加到 flake.nix 中的开发环境中：

nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    openspec.url = "github:Fission-AI/OpenSpec";
  };

  outputs = { nixpkgs, openspec, ... }: {
    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
      buildInputs = [ openspec.packages.x86_64-linux.default ];
    };
  };
}

验证安装 ​

bash
openspec --version

更新 ​

升级包，然后刷新每个项目生成的文件：

bash
npm install -g @fission-ai/openspec@latest   # 或 pnpm/yarn/bun 等效命令
openspec update                              # 在每个项目中运行

openspec update 会为你配置的工具重新生成 skill 和 command 文件，以便你的斜杠命令与已安装的版本保持同步。它还会检查是否发布了更新的 CLI 并提供升级选项，因为升级是新工作流程可用的前提——参见 CLI 参考。

卸载 ​

没有 openspec uninstall 命令，因为 OpenSpec 只是一个全局包加上你项目中的一些文件。移除它只需要几个手动步骤，且这里不会触及你的源代码。

1. 移除全局包：

bash
npm uninstall -g @fission-ai/openspec   # 或：pnpm rm -g / yarn global remove / bun rm -g

2. 从项目中移除 OpenSpec（可选）。 如果你不再需要它的 specs 和 changes，请删除 openspec/ 目录：

bash
rm -rf openspec/

三思而后行：openspec/specs/ 和 openspec/changes/archive/ 是你记录系统行为及其变更原因的地方。如果你可能想要这些历史记录，即使在卸载后也要保留文件夹（或将其保留在 git 中）。

3. 移除生成的 AI 工具文件（可选）。 OpenSpec 将 skill 和 command 文件写入每个工具的目录中，如 .claude/skills/openspec-*/、.cursor/commands/opsx-* 等。删除你配置的工具对应的 openspec-* skills 和 opsx-* commands。每个工具的确切路径列在 受支持的工具 中。

如果你还在 CLAUDE.md 或 AGENTS.md 等文件中拥有 OpenSpec 标记块，请手动移除这些块；这些文件中的你自己的内容归你所有。

下一步 ​

安装后，在你的项目中初始化 OpenSpec：

bash
cd your-project
openspec init

请参阅 入门指南 以获取完整教程。