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

适用场景：内网环境、无外网 Ubuntu 服务器、需要离线部署 Node.js CLI 工具

目标工具：

OpenSpec CLI：@fission-ai/openspec@latest

Superpowers：npx skills add obra/superpowers

CodeGraph CLI：@colbymchenry/codegraph

一、问题背景
[二、先判断工具类型：是 npm 包，还是远程资源](#二、先判断工具类型：是 npm 包，还是远程资源)
[三、离线环境先准备 Node.js](#三、离线环境先准备 Node.js)
[四、如何持久化 PATH](#四、如何持久化 PATH)
[五、离线安装 OpenSpec CLI](#五、离线安装 OpenSpec CLI)
[六、离线安装 CodeGraph CLI](#六、离线安装 CodeGraph CLI)
[七、为什么推荐"整目录打包"而不是只用 npm pack](#七、为什么推荐“整目录打包”而不是只用 npm pack)
[八、如何理解 npx skills add obra/superpowers](#八、如何理解 npx skills add obra/superpowers)
九、统一离线打包方案
十、常用命令汇总
十一、关键结论
十二、后续建议

一、问题背景

在 Ubuntu 离线环境中，需要安装以下工具：

OpenSpec CLI
bash 复制代码
```
@fission-ai/openspec@latest
```
Superpowers
bash 复制代码
```
npx skills add obra/superpowers
```
CodeGraph CLI
bash 复制代码
```
@colbymchenry/codegraph
```

一开始尝试通过下面的命令查询：

bash 复制代码

npm view openspec-cli

结果返回：

bash 复制代码

npm error code E404
npm error 404 Not Found - GET https://registry.npmjs.org/openspec-cli - Not found

这说明：

openspec-cli 不是 npm 官方仓库中的真实包名
离线安装前，必须先确认：
- 真实包名
- 安装来源
- 是否是标准 npm 包

后来确认实际要安装的是：

@fission-ai/openspec
@colbymchenry/codegraph
以及通过 skills 添加的 obra/superpowers

二、先判断工具类型：是 npm 包，还是远程资源

离线安装之前，先判断工具属于哪一类，非常关键。

1）标准 npm 包

典型形式：

bash 复制代码

npm install -g @scope/package

例如：

@fission-ai/openspec
@colbymchenry/codegraph

这种工具通常可以使用以下离线方法：

npm pack
在线安装后整体打包 node_modules
迁移 npm 缓存
使用内网 npm 代理

2）非标准 npm 包，而是某个工具加载的资源

例如：

bash 复制代码

npx skills add obra/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）检查是否已安装

bash 复制代码

node -v
npm -v

如果没有安装，需要先离线部署 Node.js。

2）推荐的离线安装 Node.js 方式

在联网机器上下载适合目标架构的压缩包，例如：

node-v20.x.x-linux-x64.tar.xz
node-v20.x.x-linux-arm64.tar.xz

将文件拷贝到离线 Ubuntu 机器后执行：

bash 复制代码

mkdir -p ~/local/node
tar -xJf node-v20.x.x-linux-x64.tar.xz -C ~/local/node --strip-components=1
export PATH="$HOME/local/node/bin:$PATH"

验证：

bash 复制代码

node -v
npm -v

四、如何持久化 PATH

临时执行下面命令：

bash 复制代码

export PATH="$HOME/local/node/bin:$PATH"

只在当前 shell 会话中生效，关闭终端后就失效了。

如果想永久生效，需要写入 shell 配置文件。

1）bash 用户的持久化方法

bash 复制代码

echo 'export PATH="$HOME/local/node/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

2）验证是否生效

bash 复制代码

echo $PATH
which node
node -v

3）zsh 用户的写法

bash 复制代码

echo 'export PATH="$HOME/local/node/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

4）避免重复追加的更稳写法

bash 复制代码

grep -qxF 'export PATH="$HOME/local/node/bin:$PATH"' ~/.bashrc || echo 'export PATH="$HOME/local/node/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

五、离线安装 OpenSpec CLI

目标包名：

bash 复制代码

@fission-ai/openspec

1）先在联网机器上确认包信息

bash 复制代码

npm view @fission-ai/openspec name version dependencies bin dist.tarball

重点关注：

dependencies
bin
dist.tarball

如果有 bin 字段，说明它是 CLI 工具。

2）方法一：直接 `npm pack`

这是最简单的尝试方式。

联网机器

bash 复制代码

npm pack @fission-ai/openspec

会生成类似：

text 复制代码

fission-ai-openspec-<version>.tgz

离线机器

bash 复制代码

npm install -g ./fission-ai-openspec-<version>.tgz

缺点

如果依赖较多，离线安装时 npm 仍可能尝试联网下载依赖，因此成功率不一定高。

3）方法二：推荐方式------在线安装后整目录打包

这是最稳妥的离线安装方式。

联网机器

bash 复制代码

mkdir -p ~/offline-openspec
cd ~/offline-openspec
npm init -y
npm install @fission-ai/openspec
tar -czf openspec-offline-bundle.tar.gz .

这一步会把以下内容全部打包：

package.json
package-lock.json
node_modules/
CLI 入口

离线机器

bash 复制代码

mkdir -p ~/offline-openspec
tar -xzf openspec-offline-bundle.tar.gz -C ~/offline-openspec
cd ~/offline-openspec

测试运行：

bash 复制代码

npx @fission-ai/openspec --help

或者直接运行本地 CLI：

bash 复制代码

./node_modules/.bin/openspec --help

4）加入 PATH，方便全局调用

bash 复制代码

mkdir -p ~/.local/bin
ln -sf ~/offline-openspec/node_modules/.bin/openspec ~/.local/bin/openspec
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

之后就可以直接使用：

bash 复制代码

openspec --help

六、离线安装 CodeGraph CLI

目标包名：

bash 复制代码

@colbymchenry/codegraph

它的处理方式与 OpenSpec CLI 基本相同。

1）联网机查询包信息

bash 复制代码

npm view @colbymchenry/codegraph name version dependencies bin dist.tarball

2）联网机打离线包

bash 复制代码

mkdir -p ~/offline-codegraph
cd ~/offline-codegraph
npm init -y
npm install @colbymchenry/codegraph
tar -czf codegraph-offline-bundle.tar.gz .

3）离线机部署

bash 复制代码

mkdir -p ~/offline-codegraph
tar -xzf codegraph-offline-bundle.tar.gz -C ~/offline-codegraph
cd ~/offline-codegraph

测试：

bash 复制代码

npx @colbymchenry/codegraph --help

或者：

bash 复制代码

./node_modules/.bin/codegraph --help

4）建立软链接

bash 复制代码

mkdir -p ~/.local/bin
ln -sf ~/offline-codegraph/node_modules/.bin/codegraph ~/.local/bin/codegraph
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

验证：

bash 复制代码

codegraph --help

七、为什么推荐"整目录打包"而不是只用 npm pack

会话中讨论了两类常见离线方式。

方式一：`npm pack`

优点：

操作简单
能快速拿到包的 .tgz

缺点：

只打主包，不一定包含依赖
离线安装时可能继续联网拉依赖
对复杂 CLI 工具成功率不高

方式二：联网 `npm install` 后整体打包目录

优点：

node_modules 中已包含依赖
离线环境成功率更高
实操上更稳

缺点：

包体积更大
要求在线机和离线机：
- 系统架构尽量一致
- Node.js 版本尽量一致

实战建议

对于复杂 Node.js CLI，推荐优先使用：

联网完整安装 + 整个目录打包带走

这是最稳的离线方案。

八、如何理解 `npx skills add obra/superpowers`

这个命令和普通 npm 包安装完全不同。

bash 复制代码

npx skills add obra/superpowers

它并不是执行：

bash 复制代码

npm install superpowers

而是：

先运行 skills
再由 skills 去拉取或添加 obra/superpowers

从命名上看，obra/superpowers 很像：

GitHub 的 owner/repo
或者某种远程模板 / 资源标识

因此，离线处理需要分两步。

第一步：先确认 `skills` 本体是什么

在联网机器上执行：

bash 复制代码

npm view skills
npm search skills
npx skills --help
npx skills add --help

目标是确认：

skills 的真实 npm 包名
skills add 是否支持本地路径
obra/superpowers 的真实来源

第二步：确认 `obra/superpowers` 是什么资源

高概率情况是它对应一个 GitHub 仓库，例如：

text 复制代码

https://github.com/obra/superpowers

如果是这种情况，离线处理通常为：

联网机器

bash 复制代码

git clone https://github.com/obra/superpowers.git
tar -czf superpowers-repo.tar.gz superpowers

离线机器

bash 复制代码

tar -xzf superpowers-repo.tar.gz

然后查看 skills 是否支持从本地路径导入，例如：

bash 复制代码

skills add ./superpowers

或：

bash 复制代码

skills import ./superpowers

具体命令以 skills --help 的实际输出为准。

九、统一离线打包方案

如果目标是"在离线 Ubuntu 环境中尽快可用"，最推荐的统一做法是：

在线机完整安装
将整个项目目录打包
离线机解压
通过软链接暴露命令

1）在线机准备 OpenSpec

bash 复制代码

mkdir -p ~/bundles/openspec
cd ~/bundles/openspec
npm init -y
npm install @fission-ai/openspec

2）在线机准备 CodeGraph

bash 复制代码

mkdir -p ~/bundles/codegraph
cd ~/bundles/codegraph
npm init -y
npm install @colbymchenry/codegraph

3）如果确认了 `skills` 本体，也同样处理

假设它的包名就是 skills：

bash 复制代码

mkdir -p ~/bundles/skills
cd ~/bundles/skills
npm init -y
npm install skills

4）统一打包

bash 复制代码

cd ~/bundles
tar -czf all-cli-bundles.tar.gz openspec codegraph skills

如果暂时没有确认 skills，也可以先只打包前两个：

bash 复制代码

tar -czf all-cli-bundles.tar.gz openspec codegraph

5）离线机部署

bash 复制代码

mkdir -p ~/bundles
tar -xzf all-cli-bundles.tar.gz -C ~/bundles

6）测试运行

bash 复制代码

~/bundles/openspec/node_modules/.bin/openspec --help
~/bundles/codegraph/node_modules/.bin/codegraph --help

如果已安装 skills：

bash 复制代码

~/bundles/skills/node_modules/.bin/skills --help

7）创建软链接

bash 复制代码

mkdir -p ~/.local/bin
ln -sf ~/bundles/openspec/node_modules/.bin/openspec ~/.local/bin/openspec
ln -sf ~/bundles/codegraph/node_modules/.bin/codegraph ~/.local/bin/codegraph

如果有 skills：

bash 复制代码

ln -sf ~/bundles/skills/node_modules/.bin/skills ~/.local/bin/skills

8）配置 PATH

bash 复制代码

grep -qxF 'export PATH="$HOME/.local/bin:$PATH"' ~/.bashrc || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

十、常用命令汇总

1）查询 npm 包信息

bash 复制代码

npm view @fission-ai/openspec name version dependencies bin dist.tarball
npm view @colbymchenry/codegraph name version dependencies bin dist.tarball

2）搜索相关包

bash 复制代码

npm search openspec
npm search skills

3）查看当前 npm registry

bash 复制代码

npm config get registry

4）打包 npm 主包

bash 复制代码

npm pack @fission-ai/openspec
npm pack @colbymchenry/codegraph

5）在线安装并准备离线 bundle

bash 复制代码

npm init -y
npm install @fission-ai/openspec
npm install @colbymchenry/codegraph

6）打包目录

bash 复制代码

tar -czf openspec-offline-bundle.tar.gz .
tar -czf codegraph-offline-bundle.tar.gz .

7）离线解压

bash 复制代码

tar -xzf openspec-offline-bundle.tar.gz -C ~/offline-openspec
tar -xzf codegraph-offline-bundle.tar.gz -C ~/offline-codegraph

8）直接运行本地 CLI

bash 复制代码

./node_modules/.bin/openspec --help
./node_modules/.bin/codegraph --help

9）创建软链接

bash 复制代码

ln -sf ~/offline-openspec/node_modules/.bin/openspec ~/.local/bin/openspec
ln -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。

十二、后续建议

如果后续要把这套方案做成一键脚本，建议进一步确认以下信息：

离线机架构
- x64
- arm64
skills 的真实 npm 包名
obra/superpowers 的真实来源
- GitHub 仓库
- skills 自带 registry
- 其他远程源
联网机执行以下命令后的输出：

bash 复制代码

npx skills --help
npx skills add --help

附：一句话总结

对于 Ubuntu 离线环境中的 Node.js CLI 工具部署，最实用的原则就是：

先确认真实安装源，再在联网机完整安装并打包整个目录，最后在离线机通过软链接暴露命令。

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

目录

一、问题背景

二、先判断工具类型：是 npm 包，还是远程资源

1）标准 npm 包

2）非标准 npm 包，而是某个工具加载的资源

三、离线环境先准备 Node.js

1）检查是否已安装

2）推荐的离线安装 Node.js 方式

四、如何持久化 PATH

1）bash 用户的持久化方法

2）验证是否生效

3）zsh 用户的写法

4）避免重复追加的更稳写法

五、离线安装 OpenSpec CLI

1）先在联网机器上确认包信息

2）方法一：直接 npm pack

联网机器

离线机器

缺点

3）方法二：推荐方式------在线安装后整目录打包

联网机器

离线机器

4）加入 PATH，方便全局调用

六、离线安装 CodeGraph CLI

1）联网机查询包信息

2）联网机打离线包

3）离线机部署

4）建立软链接

七、为什么推荐"整目录打包"而不是只用 npm pack

方式一：npm pack

方式二：联网 npm install 后整体打包目录

实战建议

八、如何理解 npx skills add obra/superpowers

第一步：先确认 skills 本体是什么

第二步：确认 obra/superpowers 是什么资源

联网机器

离线机器

九、统一离线打包方案

1）在线机准备 OpenSpec

2）在线机准备 CodeGraph

3）如果确认了 skills 本体，也同样处理

4）统一打包

5）离线机部署

6）测试运行

7）创建软链接

8）配置 PATH

十、常用命令汇总

1）查询 npm 包信息

2）搜索相关包

3）查看当前 npm registry

4）打包 npm 主包

5）在线安装并准备离线 bundle

6）打包目录

7）离线解压

8）直接运行本地 CLI

9）创建软链接

十一、关键结论

十二、后续建议

附：一句话总结

2）方法一：直接 `npm pack`

方式一：`npm pack`

方式二：联网 `npm install` 后整体打包目录

八、如何理解 `npx skills add obra/superpowers`

第一步：先确认 `skills` 本体是什么

第二步：确认 `obra/superpowers` 是什么资源

3）如果确认了 `skills` 本体，也同样处理