跳到主要内容

安装 nrgrd

nrgrd 是 NeuroGrid 的终端客户端：一个在 shell 里对你的代码仓库进行操作的 编程智能体。它可以连接任何兼容 OpenAI 的 endpoint，包括一个 NeuroGrid deployment，并以 nrgrd 的名字发布在 PyPI 上。

它运行在 macOS、Linux 和 Windows 上，需要 Python 3.11 或更新版 本。

这不是代理

这是用来使用推理服务的工具。如果你想出租一张 GPU，你需要的是 代理，它以 Docker 镜像的形式发布。

安装​

使用 uv（推荐）​

uv 会把 nrgrd 安装在它自己的环境里，把 nrgrd 命令加进你的 PATH，并且 如果你还没有合适的 Python，会自动帮你下载一个。

uv tool install nrgrd

还没有 uv？先安装它，然后在一个新终端里运行上面的命令。

# macOS 和 Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

使用 pipx​

需要已经安装了 Python 3.11 或更新版本。

pipx install nrgrd

使用 pip​

安装进一个虚拟环境，而不是系统自带的 Python。这样 nrgrd 会在那个环境被激 活时随时可用。

python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install nrgrd

检查是否安装成功​

nrgrd --version

它会打印出已安装的版本号，比如 nrgrd 0.1.0。

第一次运行​

在你想要处理的项目目录下打开一个终端，启动 nrgrd：

cd my-project
nrgrd                             # 交互模式
nrgrd "解释一下这个仓库"           # 一次性提问，然后退出

第一次运行时，它会要求输入你 deployment 的 endpoint URL 和 API key，两者都能在你的 NeuroGrid 控制台里 找到。接着它会询问该 endpoint 提供哪些模型，如果只有一个，就会自动为你选 中它。

API key 会保存在你操作系统的凭据存储中——macOS 的 Keychain、Windows 的 Credential Manager，或者 Linux 的 Secret Service——而不是配置文件里。

之后可以用 /config edit 修改连接。输入 /help 查看所有命令。

更新与卸载​

uvpipxpip
更新uv tool upgrade nrgrdpipx upgrade nrgrdpip install -U nrgrd
卸载uv tool uninstall nrgrdpipx uninstall nrgrdpip uninstall nrgrd

故障排查​

Windows："incompatible hardlinks"（os error 396）​

症状。 uv tool install nrgrd 失败，提示 The cloud operation cannot be performed on a file with incompatible hardlinks. (os error 396)。

原因。 uv 通过从缓存创建硬链接来完成安装。工作笔记本上常见的 OneDrive，不允许在它管理的文件夹里创建硬链接。

解决办法。 让 uv 改为复制文件：

uv tool uninstall nrgrd
uv tool install nrgrd --link-mode=copy

要让复制成为 uv 每次安装的默认方式，运行一次下面的命令，然后打开一个新终 端：

[Environment]::SetEnvironmentVariable("UV_LINK_MODE", "copy", "User")

系统无法识别 nrgrd 命令​

原因。 uv 或 pipx 放置命令的那个文件夹还不在你的 PATH 里。

解决办法。 运行 uv tool update-shell（或者 pipx ensurepath），然 后打开一个新终端。

error: externally-managed-environment​

原因。 在较新的 macOS 和 Linux 上，pip 拒绝安装到系统自带的 Python 里，以保护操作系统自身的包。

解决办法。 使用 uv 或 pipx，或者像上面那样在虚拟环境里使用 pip。

软件包 'nrgrd' 需要不同的 Python 版本​

原因。 pip 或 pipx 运行在 Python 3.10 或更旧的版本上。

解决办法。 用 uv 安装，它会自己下载合适的 Python；或者安装 Python 3.11 或更新版本。

pipx: "pipx needs uv>=…"​

原因。 较新版本的 pipx 会在发现系统里有 uv 时使用它，而你的 uv 版本 比它要求的更旧。

解决办法。 更新 uv（如果你是用独立安装器装的，运行 uv self update），或者用 pipx install --backend pip nrgrd 跳过这个问题。

链接​