前言

为何选择 Pi？

Pi 是一款极简的智能体框架。让 Pi 适应您的工作流程，而非本末倒置。通过扩展、技能、提示词模板和主题来自定义 Pi。将它们打包为Pi 包，并通过 npm 或 git 分享。

Pi 自带强大的默认配置，但省略了子智能体和计划模式等功能。您可以要求 Pi 构建您想要的功能，或安装一个符合您需求的包。

我选择 Pi，主要是因为它启动快、配置简单，而且可以通过扩展和技能自由调整。相比功能复杂的智能体工具，Pi 更适合喜欢自己折腾配置的人

官方网站:https://pi.dev
开源地址:https://github.com/earendil-works/pi

安装

开始安装Pi Coding Agent

Windows

使用Win + R打开运行对话框，输入powershell
在powershell中输入，来运行Pi Agent交互式安装

powershell -c "irm https://pi.dev/install.ps1 | iex"

首先会询问是否需要安装Node.js与npm，输入y后回车(必须)
将会下载并安装Node.js与npm
图片.png
然后将会询问你是否要安装Pi并给出安装路径
选择y
图片.png
之后会弹出如下选项，均询问想要如何安装git bash
图片.png
y:安装由Pi托管的git bash(便携版)，不影响系统环境变量，无需关心管理员权限，适合小白用户
w:使用winget来全局安装git bash(完整安装)，可以在cmd、powershell、vscode中使用git命令，适合开发者或者本来就想安装git的用户
n:不安装gitbash(不推荐，需要指定终端工具)

选择任意一个选项后按回车开始下载安装流程

最后会询问是否要将Pi添加到环境变量PathAdd C:\Users\123\.pi\agent\bin to your user PATH now? [Y/n]:选择y后完成安装
使用 pi --version验证安装

Linux

打开终端

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

过程基本同Windows

使用Pi

来看看Pi支持的功能吧！

添加模型

终端内输入pi来打开pi，首次进入需要下载依赖工具(rg,fd)
在输入框输入/login，将显示三个选项
图片.png
Sign in with an account：使用OAuth验证来添加模型（如ChatGPT订阅）
Sign in with an API key: 使用ApiKey来添加模型
Sign in with Radius：使用Pi官方提供的Radius服务
OAuth将会在浏览器进行并回调
以DeepSeek为例:
选择Sign in with an API key
输入deepseek并选择
图片.png
图片.png
登录DeepSeek开放平台————Apikeys————创建Apikeys————命名————复制

不要泄露你的Apikey


将复制的Apikey粘贴到输入框内，然后按回车，添加成功

选择模型

在输入框输入/model按下回车，选择你已经配置(添加)好的模型
图片.png

在选择的模型上按下 Ctrl+S 可将其保存为新会话的默认模型


此时就可以进行开发了
快捷键见常用快捷键

插件/扩展

Pi Agent有着很高的可自定义度得益于它的扩展
前往Pi软件包市场选择你喜欢的插件/扩展
以pi-mcp-adapter为例：在 Pi 中使用 MCP 服务器
图片.png
点击右下角的[Copy]
然后启动终端并粘贴即可使用npm安装插件/扩展

配置

  • Windows:%USERPROFILE%\.pi\agent
  • Linux:~/.pi/agent/

项目配置 > 全局配置

全局配置

bin:二进制文件夹
extensions:扩展
npm:安装的npm软件包
sessions:会话记录
skills:技能

auth.json:存储各个模型提供商的OAuth凭证与Apikey
settings.json:存储PiAgnet的设置
trust.json:信任的目录
models.json:自定义模型与模型设置

项目配置

路径职责
.pi/settings.json项目级 设置、资源路径及 Pi 包声明
.pi/mcp.json项目MCP 服务器
.pi/SYSTEM.md替换项目的系统提示词
.pi/APPEND_SYSTEM.md向系统提示词添加项目专属指令
.pi/extensions/项目扩展
.pi/skills/项目技能及支持文件
.pi/prompts/以斜杠命令形式公开的项目提示词模板
.pi/themes/项目主题文件

如需全局生效只需将前面的.pi换为.pi/agent即可(注意是在%USERPROFILE%下)

上下文文件

包括
AGENTS.md
CLAUDE.md

  • 上下文文件与项目.pi配置相互独立
  • 会自动查找父目录、代理目录、工作目录的上下文文件并自动加载
  • AGENTS.override.md优先于 AGENTS.md 或 CLAUDE.md

常用外置命令

pi -r ：继续上一次的会话，在选择会话界面按Tab可以从当前文件夹和全局来回切换
pi update ：使用npm更新Pi Agent
pi update --extensions：使用npm更新扩展/插件
pi prompt ：新建会话并发送提示词(prompt)

常用内置命令

/login ：登录模型服务或添加 API Key
/logout ：退出并移除已登录的模型服务
/model ：选择当前使用的模型
/thinking ：调整模型思考强度
/settings ：打开 Pi 设置
/new ：新建一个空会话
/resume ：恢复或切换已保存的会话
/name ：给当前会话命名
/session ：查看当前会话的信息、Token 与费用
/compact ：压缩较早的对话上下文，减少占用
/tree ：查看并切换当前会话的分支
/fork ：从之前的消息另开一个分支会话
/clone ：复制当前会话为一个新会话
/reload ：重新加载配置、扩展、技能等
/hotkeys ：查看快捷键
/changelog ：查看 Pi 更新日志
/copy ：复制上一条 AI 回复
/export ：导出当前会话为 HTML 或 JSONL
/share ：分享当前会话
/quit ：退出 Pi

常用快捷键

Enter ：发送当前消息
Shift + Enter ：换行
Ctrl + J ：换行（Shift + Enter 不生效时用）
Esc ：停止当前 AI 任务
Ctrl + Q ：将消息排队，等当前任务完成后再处理
Alt + Q ：把已排队的消息放回输入框
Ctrl + L ：打开模型选择
Shift + Tab ：切换思考强度
Ctrl + O ：展开 / 折叠工具执行输出
Ctrl + T ：显示 / 隐藏思考过程
Ctrl + F ：搜索当前会话内容（全屏模式）
Ctrl + ↑ / ↓ ：跳到上一条 / 下一条标记消息
Ctrl + Home ：跳到会话最上方
Ctrl + End ：跳到会话最下方
Ctrl + X ：复制上一条 AI 回复
Alt + V ：粘贴剪贴板中的图片或文件
Ctrl + C ：先清空输入框；连续再按一次可退出
Ctrl + D ：输入框为空时退出 Pi

常见问题

Q:LLM模型不会调用Shell，为什么？
A:尝试在聊天框输入!ls，如出现
图片.png
则代表GitBash未安装成功，此时需要前往https://git-scm.com/download/手动下载安装对应版本，建议使用默认安装路径，对于Windows，Pi Agent会在以下目录内查找gitbash:
C:\Program Files\Git\bin\
C:\Program Files (x86)\Git\bin\
安装完成后，在聊天框输入/reload 或 重启Pi Agent即可解决