Windows 电脑部署 Pi Agent：WSL2 + Node + D 盘工作区全流程

目标环境

Pi Agent 是跑在终端里的 AI 搭档（terminal coding harness）：你给它一句话需求，它能读文件、改代码、跑命令。Windows 上最顺的跑法是 WSL2 + Ubuntu——文件在 Windows 和 Linux 两边都能访问，装完跟 Linux 服务器行为一致，后面迁移到服务器也零成本。

第 1 步：开启 WSL2 并安装 Ubuntu

1. 右键开始菜单，打开 管理员 PowerShell
2. 执行：

   wsl --install

它会自动开启 WSL2 并安装默认的 Ubuntu 发行版，装完提示重启电脑

1. 重启后，Ubuntu 窗口自动打开，按提示设置 Linux 用户名和密码（密码输入时屏幕不显示，正常）

第 2 步：更新系统 + 装基础工具

在 Ubuntu 终端里执行：

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl ca-certificates

第 3 步：装 Node.js 20+

Pi 需要 Node 20 及以上。用 nvm 装最干净（以后换版本一条命令）：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
node -v    # 应输出 v22.x.x，>= 20 即可

第 4 步：安装 Pi Agent

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version   # 验证安装成功

第 5 步：配置模型（API Key）

Pi 本身不带模型，需要接一个 LLM 提供方。首次运行 pi 会引导你选择；也可以直接编辑配置文件：

mkdir -p ~/.pi/agent
# 自定义提供方示例（OpenAI 兼容接口都适用）
cat > ~/.pi/agent/models.json <<'EOF'
{
  "providers": {
    "my-provider": {
      "baseUrl": "https://你的接口地址/v1",
      "apiKey": "$MY_API_KEY",
      "models": { "my-model": {} }
    }
  }
}
EOF

然后把密钥放进环境变量（~/.bashrc 里加一行）：

echo 'export MY_API_KEY=sk-xxxx' >> ~/.bashrc && source ~/.bashrc

第 6 步：把工作区设在 D 盘

WSL 里 Windows 的 D 盘路径是 /mnt/d。建一个专门放项目的工作区：

mkdir -p /mnt/d/pi-projects

之后所有项目都放这里——Windows 资源管理器里直接能看到、能备份，pi 干活也在这个目录里进行：

cd /mnt/d/pi-projects && pi

第 7 步：常用命令速查

验收清单

1. pi --version 输出版本号
2. cd /mnt/d/pi-projects && pi 进入对话
3. 输入 你好，收到回复
4. 让它"在当前目录建一个 hello.txt 写一句话"，它真的动手了

跑通这四步，你的 Windows 就有一台能写代码、能操作文件的 AI 搭档了。

常见问题与排错

• wsl --install 报错或卡住不动：多半是 BIOS 没开虚拟化。重启进 BIOS 开启 VT-x/AMD-V，再到"控制面板 → 程序 → 启用或关闭 Windows 功能"勾选"虚拟机平台"，重装 WSL。
• wsl -l -v 显示 VERSION 1：执行 wsl --set-version Ubuntu 2 升级到 WSL2。
• npm 安装 pi 很慢或超时：换国内镜像后重装：npm config set registry https://registry.npmmirror.com。
• pi 命令找不到：确认全局 bin 在 PATH：npm prefix -g，把输出的 bin 目录加进 ~/.bashrc 的 PATH。
• 启动报 Node 版本太低：nvm install 22 && nvm use 22，然后 node -v 确认。
• D 盘读写明显慢：WSL 跨盘 IO 本来就比 Linux 盘慢，大量小文件操作建议放 ~/projects。
• 中文显示成方块/乱码：sudo apt install -y fonts-noto-cjk，装中文字体后重开终端。

相关网址汇总

• WSL 官方文档：https://learn.microsoft.com/zh-cn/windows/wsl/
• nvm（Node 版本管理）：https://github.com/nvm-sh/nvm
• Pi Agent 官方站：https://pi.dev
• Pi 的 npm 包页：https://www.npmjs.com/package/@earendil-works/pi-coding-agent