OpenSpec 安装后提示 “openspec: command not found“ 怎么排查？

OpenSpec 安装后提示 openspec: command not found 怎么排查【免费下载链接】OpenSpecSpec-driven development (SDD) for AI coding assistants.项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpec在终端输入openspec --version或openspec init时shell 报openspec: command not found。按 Troubleshooting 文档的说法这个报错只有两类原因CLI 没有安装或者装了但 shell 找不到它全局 bin 目录不在PATH里。本文按文档给出的顺序走完这两个分支先装好并验证再修 PATH最后处理版本管理器导致的装到了另一个 Node 版本下的情况。适用前提是 Node.js 20.19.0 或更高macOS、Linux 和 Windows 都覆盖。先确认 Node.js 版本OpenSpec 运行在 Node 20.19.0 上见 Installation 的 Prerequisites 一节。先检查当前版本node --version如果 Node 缺失或低于 20.19.0先解决 Node 本身的问题再继续——文档明确要求这种情况下不要靠安装 OpenSpec 绕过。另外注意一点即使你用 bun 来安装 OpenSpecOpenSpec 依然运行在 Node 上所以无论用什么包管理器安装PATH上都必须有 Node 20.19.0。第二步全局安装并立即验证全局安装会把包写到项目之外的系统全局目录这是它后来找不到命令的根源之一。文档给出的主路径是 npmnpm install -g fission-ai/openspeclatest openspec --version装完立刻跑openspec --version这是 Installation 文档指定的验证方式。如果打印出版本号问题就结束了如果继续报command not found进入下一步。其他包管理器的等价命令来自 Installation 的 Package Managers 一节按你系统里已有的选一个pnpm add -g fission-ai/openspeclatest yarn global add fission-ai/openspeclatest bun add -g fission-ai/openspeclatest两个文档写明的限制yarn global只在 Yarn 1.x 可用Yarn 2 及以后Berry移除了global命令文档建议这种情况改用 npm、pnpm 或 bun 安装——全局 CLI 不需要和项目的包管理器一致。如果安装过程要求 sudo 或管理员权限或报权限错误Installation 的 AI 协助安装流程要求停下来先确认不要带权限问题继续往下走。如果你用 Nix 或 denoInstallation 有对应章节本文主路径不展开。第三步安装成功但仍报 not found检查全局 bin 目录是否在 PATH 上这是 Troubleshooting 给出的核心判断安装成功但 shell 找不到通常是 npm 全局 bin 目录不在PATH里。用下面这条命令看全局包装在哪npm prefix -g然后按平台确认二进制实际位置macOS 和 Linux可执行文件在该目录的bin/子目录里Windows可执行文件直接位于该目录中。确认上述路径在PATH上即可。文档特别提醒npm bin -g这个旧命令在 npm 9 中已移除不要再用它定位。修改PATH由你自己完成按你的 shell.bashrc、.zshrc、.profile、fish、PowerShell profile 等把目录加进去。这一点在 Installation 的 AI 协助安装流程里是明确的设计边界——那个安装 prompt 会停下来把PATH改动告诉你而不是替你编辑 shell 启动文件。如果你就是走的 AI 协助安装停在告诉你怎么改 PATH这一步是预期行为不是流程卡住。版本管理器用户的特殊情况如果你用 Node 版本管理器Installation 的 PATH 一节给出了针对性说明不要盲目把路径写死进PATHnvm / fnm全局安装的 CLI 绑定在安装当时激活的那个 Node 版本下。切到别的 Node 版本后找不到命令是因为你换了 Node 版本CLI 还留在旧版本的全局目录里。asdf / volta升级或切换 Node 后shim 可能需要重新生成。文档的建议是先弄清CLI 装到了哪个 Node 版本下再决定用哪个 Node 版本运行或重装而不是绕着版本管理器改 PATH。命令能找到了但版本号不对PATH 上有一份旧副本Installation 还覆盖了一种相关现象openspec --version打印出的版本比刚才安装时报告的版本旧。这说明PATH上靠前位置的旧安装shim 或早先的全局副本抢答了新装的那份根本没被执行到。判断办法记录两个版本号安装命令报告的版本和openspec --version实际打印的版本。找出实际被加载的是哪一份。CLI Reference 说明openspec update的升级提示会打印当前运行 CLI 的加载目录文档示例中的Running from: /usr/local/lib/node_modules/fission-ai/openspec一行升级后仍被旧 shim 占据 PATH时就要看这一行并且当 PATH 靠前位置的另一份安装仍在应答时openspec update会直接告诉你而不是假称升级成功。处理方式就是修PATH顺序或删除旧副本让新版本目录生效确认方式是openspec --version打印出与新装版本一致的版本号。验证成功并继续初始化排查完成的标准openspec --version正常打印版本号。之后按 Installation 的 Next Steps在目标项目里初始化cd your-project openspec initinit会在当前目录创建openspec/结构文档提示它运行在哪就在哪创建monorepo 里先确认目录并按你选择的 AI 工具生成 skill 和 command 文件。完整走查见 Getting Started。如果以上步骤走完仍然卡住Troubleshooting 提供了一个终端内反馈入口openspec feedback what went wrong它会替你开一个 issue文档建议附上 OpenSpec 版本openspec --version、Node 版本node --version、所用 AI 工具以及精确的命令和输出。【免费下载链接】OpenSpecSpec-driven development (SDD) for AI coding assistants.项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考