pi-agent-bins

修复 pi-agent 安装时缺少 fd 和 rg 二进制文件的问题，支持 Windows、macOS、Linux 多平台。

背景

pi-agent 在安装过程中需要 fd 和 rg 命令。如果你的网络环境无法下载这些二进制文件，可以手动下载后放置到指定目录，然后使用本包将它们复制到正确的位置。

安装

全局安装（推荐用于修复 pi-agent）

npm install -g pi-agent-bins

全局安装后，本包的 postinstall 脚本会自动检测当前平台，并将对应平台的 fd 和 rg 二进制文件复制到全局 npm bin 目录（通常在系统 PATH 中），之后安装 pi-agent 就能找到它们。

本地安装

npm install pi-agent-bins --save-dev

本地安装后，postinstall 脚本会将对应平台的二进制文件复制到当前包目录的 node_modules/.bin。

使用

方式一：依赖自动安装（全局安装）

npm install -g pi-agent-bins
npm install -g pi-agent

全局安装 pi-agent-bins 后，对应平台的 fd 和 rg 会被放置到全局 npm bin 目录（%APPDATA%\npm 或 /usr/local/bin），该目录在系统 PATH 中，因此 pi-agent 可以直接找到它们。

方式二：手动运行（本地项目）

如果你已在本地安装了 pi-agent-bins，或者想要在特定目录安装二进制文件，可以手动运行：

npx pi-agent-bins

这会将文件复制到当前目录的 node_modules/.bin。你也可以指定目标目录：

npx pi-agent-bins C:\my\custom\bin\dir

方式三：指定平台复制

如果你需要为其他平台复制二进制文件（例如在 CI 中构建多平台产物）：

# Windows x64
npx pi-agent-bins --platform windows-x64

# macOS Apple Silicon
npx pi-agent-bins --platform darwin-arm64

# Linux x64
npx pi-agent-bins --platform linux-x64

支持的平台：

• windows-x64, windows-x86, windows-arm64
• darwin-x64, darwin-arm64
• linux-x64, linux-x86, linux-arm64, linux-armhf

方式四：在 package.json 脚本中运行

{
  "scripts": {
    "prepare:pi-agent-bins": "pi-agent-bins",
    "install:pi-agent": "npm run prepare:pi-agent-bins && npm install pi-agent"
  }
}

二进制文件目录结构

将下载好的二进制文件放置到以下目录：

C:\Users\Administrator\.pi\agent\bin\
├── fd.exe                    # Windows x64（兼容旧版本，放在根目录）
├── rg.exe                    # Windows x64（兼容旧版本，放在根目录）
├── windows-x64\
│   ├── fd.exe
│   └── rg.exe
├── windows-x86\
│   ├── fd.exe
│   └── rg.exe
├── windows-arm64\
│   ├── fd.exe
│   └── rg.exe
├── darwin-x64\
│   ├── fd                    # fd v8.7.0（最新版无 x64 版本）
│   └── rg
├── darwin-arm64\
│   ├── fd
│   └── rg
├── linux-x64\
│   ├── fd
│   └── rg
├── linux-x86\
│   ├── fd
│   └── rg                    # ripgrep v11.0.0（最新版无 i686 版本）
├── linux-arm64\
│   ├── fd
│   └── rg
└── linux-armhf\
    ├── fd
    └── rg

注意：

• Windows 平台使用 .exe 后缀
• macOS 和 Linux 平台没有后缀
• 优先查找平台子目录，如果没找到会 fallback 到根目录（兼容旧版本）
• 部分平台使用了较旧版本的二进制文件，因为最新版本未提供该平台构建

已包含的二进制文件版本

| 平台 | fd 版本 | rg 版本 | |------|--------|--------| | Windows x64 | v10.4.2 | v15.2.0 | | Windows x86 | v10.4.2 | v15.2.0 | | Windows ARM64 | v10.4.2 | v15.2.0 | | macOS x64 | v8.7.0 | v15.2.0 | | macOS ARM64 | v10.4.2 | v15.2.0 | | Linux x64 | v10.4.2 | v15.2.0 | | Linux x86 | v10.4.2 | v11.0.0 | | Linux ARM64 | v10.4.2 | v15.2.0 | | Linux ARMhf | v10.4.2 | v15.2.0 |

如何获取各平台二进制文件

如果还没有二进制文件，可以从以下渠道获取：

• fd:

  • GitHub Releases: https://github.com/sharkdp/fd/releases
  • 下载对应平台的压缩包，解压后得到可执行文件

• ripgrep (rg):

  • GitHub Releases: https://github.com/BurntSushi/ripgrep/releases
  • 下载对应平台的压缩包，解压后得到可执行文件

各平台下载文件名参考：

| 平台 | fd 文件名 | rg 文件名 | |------|-----------|-----------| | Windows x64 | fd-x86_64-pc-windows-msvc.zip | ripgrep-x86_64-pc-windows-msvc.zip | | Windows x86 | fd-i686-pc-windows-msvc.zip | ripgrep-i686-pc-windows-msvc.zip | | Windows ARM64 | fd-aarch64-pc-windows-msvc.zip | ripgrep-aarch64-pc-windows-msvc.zip | | macOS x64 | fd-x86_64-apple-darwin.tar.gz | ripgrep-x86_64-apple-darwin.tar.gz | | macOS ARM64 | fd-aarch64-apple-darwin.tar.gz | ripgrep-aarch64-apple-darwin.tar.gz | | Linux x64 | fd-x86_64-unknown-linux-gnu.tar.gz | ripgrep-x86_64-unknown-linux-musl.tar.gz | | Linux x86 | fd-i686-unknown-linux-gnu.tar.gz | ripgrep-i686-unknown-linux-musl.tar.gz | | Linux ARM64 | fd-aarch64-unknown-linux-gnu.tar.gz | ripgrep-aarch64-unknown-linux-musl.tar.gz | | Linux ARMhf | fd-arm-unknown-linux-gnueabihf.tar.gz | ripgrep-armv7-unknown-linux-musleabihf.tar.gz |

环境变量

可以通过环境变量自定义二进制文件源目录：

# Windows PowerShell
$env:PI_AGENT_BINS_DIR = "D:\my\custom\bin\dir"
npm install -g pi-agent-bins

# Linux/macOS
export PI_AGENT_BINS_DIR="/path/to/custom/bin"
npm install -g pi-agent-bins

注意事项

• 由于网络限制，部分平台的二进制文件可能使用了较旧版本
• 如果某个平台的二进制文件缺失，postinstall 脚本会跳过该平台并输出警告
• 你可以通过 PI_AGENT_BINS_DIR 环境变量指定自己的二进制文件目录

License

MIT