Ubuntu 离线安装 OpenSpec CLI、CodeGraph CLI 与相关工具实战笔记

适用场景内网环境、无外网 Ubuntu 服务器、需要离线部署 Node.js CLI 工具目标工具OpenSpec CLIfission-ai/openspeclatestSuperpowersnpx skills add obra/superpowersCodeGraph CLIcolbymchenry/codegraph目录一、问题背景二、先判断工具类型是 npm 包还是远程资源三、离线环境先准备 Node.js四、如何持久化 PATH五、离线安装 OpenSpec CLI六、离线安装 CodeGraph CLI七、为什么推荐“整目录打包”而不是只用 npm pack八、如何理解npx skills add obra/superpowers九、统一离线打包方案十、常用命令汇总十一、关键结论十二、后续建议一、问题背景在 Ubuntu 离线环境中需要安装以下工具OpenSpec CLIfission-ai/openspeclatestSuperpowersnpx skillsaddobra/superpowersCodeGraph CLIcolbymchenry/codegraph一开始尝试通过下面的命令查询npmview openspec-cli结果返回npmerror code E404npmerror404Not Found - GET https://registry.npmjs.org/openspec-cli - Not found这说明openspec-cli不是 npm 官方仓库中的真实包名离线安装前必须先确认真实包名安装来源是否是标准 npm 包后来确认实际要安装的是fission-ai/openspeccolbymchenry/codegraph以及通过skills添加的obra/superpowers二、先判断工具类型是 npm 包还是远程资源离线安装之前先判断工具属于哪一类非常关键。1标准 npm 包典型形式npminstall-gscope/package例如fission-ai/openspeccolbymchenry/codegraph这种工具通常可以使用以下离线方法npm pack在线安装后整体打包node_modules迁移 npm 缓存使用内网 npm 代理2非标准 npm 包而是某个工具加载的资源例如npx skillsaddobra/superpowers这类命令往往不是在安装一个叫superpowers的 npm 包而是用npx运行skills再通过skills去添加obra/superpowers也就是说skills是工具本体obra/superpowers更像是插件 / 模板 / 仓库资源因此superpowers的离线安装方式与普通 npm 包不同。三、离线环境先准备 Node.js因为 OpenSpec CLI 和 CodeGraph CLI 都属于 Node.js 生态所以离线机需要先准备 Node.js 和 npm。1检查是否已安装node-vnpm-v如果没有安装需要先离线部署 Node.js。2推荐的离线安装 Node.js 方式在联网机器上下载适合目标架构的压缩包例如node-v20.x.x-linux-x64.tar.xznode-v20.x.x-linux-arm64.tar.xz将文件拷贝到离线 Ubuntu 机器后执行mkdir-p~/local/nodetar-xJfnode-v20.x.x-linux-x64.tar.xz-C~/local/node --strip-components1exportPATH$HOME/local/node/bin:$PATH验证node-vnpm-v四、如何持久化 PATH临时执行下面命令exportPATH$HOME/local/node/bin:$PATH只在当前 shell 会话中生效关闭终端后就失效了。如果想永久生效需要写入 shell 配置文件。1bash 用户的持久化方法echoexport PATH$HOME/local/node/bin:$PATH~/.bashrcsource~/.bashrc2验证是否生效echo$PATHwhichnodenode-v3zsh 用户的写法echoexport PATH$HOME/local/node/bin:$PATH~/.zshrcsource~/.zshrc4避免重复追加的更稳写法grep-qxFexport PATH$HOME/local/node/bin:$PATH~/.bashrc||echoexport PATH$HOME/local/node/bin:$PATH~/.bashrcsource~/.bashrc五、离线安装 OpenSpec CLI目标包名fission-ai/openspec1先在联网机器上确认包信息npmview fission-ai/openspec name version dependencies bin dist.tarball重点关注dependenciesbindist.tarball如果有bin字段说明它是 CLI 工具。2方法一直接npm pack这是最简单的尝试方式。联网机器npmpack fission-ai/openspec会生成类似fission-ai-openspec-version.tgz离线机器npminstall-g./fission-ai-openspec-version.tgz缺点如果依赖较多离线安装时 npm 仍可能尝试联网下载依赖因此成功率不一定高。3方法二推荐方式——在线安装后整目录打包这是最稳妥的离线安装方式。联网机器mkdir-p~/offline-openspeccd~/offline-openspecnpminit-ynpminstallfission-ai/openspectar-czfopenspec-offline-bundle.tar.gz.这一步会把以下内容全部打包package.jsonpackage-lock.jsonnode_modules/CLI 入口离线机器mkdir-p~/offline-openspectar-xzfopenspec-offline-bundle.tar.gz-C~/offline-openspeccd~/offline-openspec测试运行npx fission-ai/openspec--help或者直接运行本地 CLI./node_modules/.bin/openspec--help4加入 PATH方便全局调用mkdir-p~/.local/binln-sf~/offline-openspec/node_modules/.bin/openspec ~/.local/bin/openspecechoexport PATH$HOME/.local/bin:$PATH~/.bashrcsource~/.bashrc之后就可以直接使用openspec--help六、离线安装 CodeGraph CLI目标包名colbymchenry/codegraph它的处理方式与 OpenSpec CLI 基本相同。1联网机查询包信息npmview colbymchenry/codegraph name version dependencies bin dist.tarball2联网机打离线包mkdir-p~/offline-codegraphcd~/offline-codegraphnpminit-ynpminstallcolbymchenry/codegraphtar-czfcodegraph-offline-bundle.tar.gz.3离线机部署mkdir-p~/offline-codegraphtar-xzfcodegraph-offline-bundle.tar.gz-C~/offline-codegraphcd~/offline-codegraph测试npx colbymchenry/codegraph--help或者./node_modules/.bin/codegraph--help4建立软链接mkdir-p~/.local/binln-sf~/offline-codegraph/node_modules/.bin/codegraph ~/.local/bin/codegraphechoexport PATH$HOME/.local/bin:$PATH~/.bashrcsource~/.bashrc验证codegraph--help七、为什么推荐“整目录打包”而不是只用 npm pack会话中讨论了两类常见离线方式。方式一npm pack优点操作简单能快速拿到包的.tgz缺点只打主包不一定包含依赖离线安装时可能继续联网拉依赖对复杂 CLI 工具成功率不高方式二联网npm install后整体打包目录优点node_modules中已包含依赖离线环境成功率更高实操上更稳缺点包体积更大要求在线机和离线机系统架构尽量一致Node.js 版本尽量一致实战建议对于复杂 Node.js CLI推荐优先使用联网完整安装 整个目录打包带走这是最稳的离线方案。八、如何理解npx skills add obra/superpowers这个命令和普通 npm 包安装完全不同。npx skillsaddobra/superpowers它并不是执行npminstallsuperpowers而是先运行skills再由skills去拉取或添加obra/superpowers从命名上看obra/superpowers很像GitHub 的owner/repo或者某种远程模板 / 资源标识因此离线处理需要分两步。第一步先确认skills本体是什么在联网机器上执行npmview skillsnpmsearch skills npx skills--helpnpx skillsadd--help目标是确认skills的真实 npm 包名skills add是否支持本地路径obra/superpowers的真实来源第二步确认obra/superpowers是什么资源高概率情况是它对应一个 GitHub 仓库例如https://github.com/obra/superpowers如果是这种情况离线处理通常为联网机器gitclone https://github.com/obra/superpowers.gittar-czfsuperpowers-repo.tar.gz superpowers离线机器tar-xzfsuperpowers-repo.tar.gz然后查看skills是否支持从本地路径导入例如skillsadd./superpowers或skillsimport./superpowers具体命令以skills --help的实际输出为准。九、统一离线打包方案如果目标是“在离线 Ubuntu 环境中尽快可用”最推荐的统一做法是在线机完整安装将整个项目目录打包离线机解压通过软链接暴露命令1在线机准备 OpenSpecmkdir-p~/bundles/openspeccd~/bundles/openspecnpminit-ynpminstallfission-ai/openspec2在线机准备 CodeGraphmkdir-p~/bundles/codegraphcd~/bundles/codegraphnpminit-ynpminstallcolbymchenry/codegraph3如果确认了skills本体也同样处理假设它的包名就是skillsmkdir-p~/bundles/skillscd~/bundles/skillsnpminit-ynpminstallskills4统一打包cd~/bundlestar-czfall-cli-bundles.tar.gz openspec codegraph skills如果暂时没有确认skills也可以先只打包前两个tar-czfall-cli-bundles.tar.gz openspec codegraph5离线机部署mkdir-p~/bundlestar-xzfall-cli-bundles.tar.gz-C~/bundles6测试运行~/bundles/openspec/node_modules/.bin/openspec--help~/bundles/codegraph/node_modules/.bin/codegraph--help如果已安装skills~/bundles/skills/node_modules/.bin/skills--help7创建软链接mkdir-p~/.local/binln-sf~/bundles/openspec/node_modules/.bin/openspec ~/.local/bin/openspecln-sf~/bundles/codegraph/node_modules/.bin/codegraph ~/.local/bin/codegraph如果有skillsln-sf~/bundles/skills/node_modules/.bin/skills ~/.local/bin/skills8配置 PATHgrep-qxFexport PATH$HOME/.local/bin:$PATH~/.bashrc||echoexport PATH$HOME/.local/bin:$PATH~/.bashrcsource~/.bashrc十、常用命令汇总1查询 npm 包信息npmview fission-ai/openspec name version dependencies bin dist.tarballnpmview colbymchenry/codegraph name version dependencies bin dist.tarball2搜索相关包npmsearch openspecnpmsearch skills3查看当前 npm registrynpmconfig get registry4打包 npm 主包npmpack fission-ai/openspecnpmpack colbymchenry/codegraph5在线安装并准备离线 bundlenpminit-ynpminstallfission-ai/openspecnpminstallcolbymchenry/codegraph6打包目录tar-czfopenspec-offline-bundle.tar.gz.tar-czfcodegraph-offline-bundle.tar.gz.7离线解压tar-xzfopenspec-offline-bundle.tar.gz-C~/offline-openspectar-xzfcodegraph-offline-bundle.tar.gz-C~/offline-codegraph8直接运行本地 CLI./node_modules/.bin/openspec--help./node_modules/.bin/codegraph--help9创建软链接ln-sf~/offline-openspec/node_modules/.bin/openspec ~/.local/bin/openspecln-sf~/offline-codegraph/node_modules/.bin/codegraph ~/.local/bin/codegraph十一、关键结论这次实践中最重要的几个结论如下先确认真实包名不要凭工具名称猜 npm 包名。对于 Node.js CLI离线安装最稳的方式是联网完整安装 整目录打包。npx skills add obra/superpowers这类命令通常不是普通 npm 包安装问题而是“CLI 本体 远程资源”的组合问题。PATH 持久化最简单的方法就是写入~/.bashrc后再source ~/.bashrc。十二、后续建议如果后续要把这套方案做成一键脚本建议进一步确认以下信息离线机架构x64arm64skills的真实 npm 包名obra/superpowers的真实来源GitHub 仓库skills 自带 registry其他远程源联网机执行以下命令后的输出npx skills--helpnpx skillsadd--help附一句话总结对于 Ubuntu 离线环境中的 Node.js CLI 工具部署最实用的原则就是先确认真实安装源再在联网机完整安装并打包整个目录最后在离线机通过软链接暴露命令。