安装前需要准备什么？

你需要准备四样：

  1. 电脑终端
  2. 安装 Node.js 和 npm
  3. 一个可用的模型订阅或 API Key
  4. 一个用来练习的项目，最好已经交给 Git 管理

检查 Node.js 和 npm：

1
2
node --version
npm --version

安装 Pi

1、通用安装方式

1️⃣ 直接在命令行执行

1
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

注：--ignore-scripts 会关闭依赖安装脚本。Pi 的普通 npm 安装不需要这些脚本，这是官方推荐写法。

2️⃣ 安装完成后检查

1
pi --version

能看到版本号，说明 Pi 已进入系统命令路径。如果出现 command not found，通常不是 Pi 本身坏了，而是 npm 的全局命令目录没有加入 PATH。

2、Mac 和 Linux 特有安装方式

macOS 和 Linux 也可以使用官方安装脚本：

1
curl -fsSL https://pi.dev/install.sh | sh

根据提示操作确认就行：

安装成功后检查：

注：完整安装说明见 Pi Quickstart。

启动 Pi

不要随便找个目录运行。先进入你希望 Pi 操作的项目：

1
cd /path/to/your-project

然后执行命令启动 Pi ：

1
pi

Pi 会把当前目录当作工作现场，在这里阅读文件、修改代码和执行命令。

登陆模型

1️⃣ 进入 Pi 后输入登录：

1
/login

2️⃣ 选择模型服务：

3️⃣ 选择如何登录，浏览器 or 设备码：

4️⃣ 选中浏览器登录后会跳到浏览器页面：

输入你的账号密码就可以登录成功啦!

登录成功后你也可以切换使用的模型，输入命令：

1
/model

选择具体模型。以后想换模型，仍然使用 /model，或者按 Ctrl+L。

Shift+Tab 可以切换模型的推理强度。

完全配置好了后，那就测试下是否可用吧：

几个高频操作

这些命令基本够你完成日常使用

  1. /model：选择或切换模型；
  2. /settings：调整推理强度、主题等设置；
  3. /session：查看当前会话、token 和成本；
  4. /resume：打开以前的会话；
  5. /tree：回到历史节点，从那里尝试另一条路线；
  6. /compact：压缩较早内容，为长任务释放上下文；
  7. /new：开始一个新会话；
  8. /hotkeys：查看全部快捷键；
  9. /quit：退出 Pi。

使用小技巧

1️⃣ Pi 会自动保存会话。退出后，在同一项目目录执行：

1
pi -c

可以继续最近一次会话；

2️⃣ 使用 pi -r 可以浏览历史会话。

1
pi -r

3️⃣ 如果只想执行一次任务，不进入交互界面：

1
pi -p "总结这个代码库，并告诉我如何运行测试"

4️⃣ 在交互界面里，!npm test 会执行命令并把输出交给模型：

1
!npm test

5️⃣ !!npm test 也会执行，但不把输出加入模型上下文：

1
!!npm test

给项目写一份使用说明

如果每次都要提醒 Pi“修改后必须跑测试”“不要碰生产数据库”，把规则写进项目根目录的 AGENTS.md：

1
2
3
4
5
6
# Project Instructions
- 修改前先阅读相关代码和测试。
- 修改后运行 npm run check。
- 不要执行生产数据库迁移。
- 不要修改与当前任务无关的文件。
- 完成时列出修改文件和验证结果。

修改后重新启动 Pi，或输入 /reload。

Pi 也会读取父目录和当前目录中的 AGENTS.md、CLAUDE.md，全局规则则可放在 ~/.pi/agent/AGENTS.md。

到这里，你已经跑通了 Pi 最核心的使用闭环。

先把这条路线用熟，再考虑给“毛坯房”安装联网、多 Agent、长期记忆和远程控制。