Pi Agent 快速上手指南
Pi Agent 是一个极简底座的通用 AI Agent，通过按需安装 Skill 来扩展能力，专注于日常工作流自动化，而不是写代码。从搜资料、读 PDF、整理表格到做 PPT，你装什么 Skill，它就会什么。
前置准备
开始之前，确保你的环境满足以下条件：
- Node.js 20+（推荐最新 LTS 版本）
- 一个可用的 AI 模型 API Key（如 DeepSeek、Claude、OpenAI），或者订阅账号（Claude Pro、ChatGPT Plus 等）
- 一个项目目录（推荐在项目根目录启动 Pi，它会自动读取本地文件）
什么是 Pi Agent
在 OpenRouter 的排行榜上，Pi 每天的 token 消耗量排在第五名，紧紧跟在 OpenClaw 后面。
更关键的是，Pi 靠的是「低消耗高频率」。同样规模的任务，Pi 的 token 消耗大概只有 Claude Code 的三分之一甚至更少，但总消耗量却能排进前六。这说明有大量用户正在高频次地使用它来完成日常工作。
Pi 和 Claude Code 到底有什么区别？
| 对比维度 | Claude Code | Pi Agent |
|---|---|---|
| 核心定位 | 写代码、交付软件 | 完成日常工作任务 |
| 预装能力 | 代码索引、测试运行、Git 操作、编码规范等一整套开发工具 | 只保留四个基础能力：读文件、写文件、改文件、跑命令 |
| 扩展方式 | 通过 MCP / Hook 扩展 | 通过 Skill 按需安装 |
| 目标用户 | 开发者 | 任何有日常办公需求的人 |
| 典型场景 | 写功能、修 Bug、做 Code Review | 搜资料、读 PDF、整表格、写汇报、做 PPT |
一句话总结：Claude Code 解决的是开发效率，Pi 解决的是工作流效率。 不是每个人都天天写代码，但每个人每天都有一堆杂事要处理。
5 分钟快速体验
第一步：安装
在终端中运行：
curl -fsSL https://pi.dev/install.sh | sh
安装完成后，所有配置、会话记录和 Skill 包都在 ~/.pi/agent/ 目录下。
第二步：启动并登录
在项目目录下启动 Pi：
pi
输入 /login 进行登录。你有两种方式：
方式 1：订阅登录（如果你已有 Claude Pro、ChatGPT Plus 等订阅）
输入 /login，选择 provider，按提示完成授权。
方式 2：API Key（推荐，方便管理 Secrets）
第三步：选择模型
登录后，输入 /model 或按 Ctrl+P 打开模型选择面板。按 Shift+Tab 可以切换思考强度（thinking level）。
以 DeepSeek 为例：选择 DeepSeek，然后输入你的 DeepSeek API 密钥即可开始对话。
第四步：开始对话
配置完成，现在你可以直接和 Pi 对话了。
实战：用 Pi 做一个 PPT
装一个 PPT Skill，然后一句话描述需求，Pi 就能帮你从零生成一份 PPT。
安装 PPT Skill
pi install git:github.com/op7418/guizang-ppt-skill
一句话生成 PPT
直接告诉 Pi 你要什么：
帮我制作一张介绍南京风景的 PPT
Pi 会先分析需求并列出大纲，你需要确认风格和主题色，然后它开始生成。
最终效果
下图是直接生成的纯文字版效果（要想更好的视觉效果，需要进一步调试 Prompt 和参数）。
Pi 的设计哲学：极简底座 + 按需扩展
Pi Agent 的核心思路和其他 Agent 完全相反：别人在做加法，Pi 在做减法。
它的底座只保留四个最基础的能力：读文件、写文件、改文件、跑命令。除此之外，什么都不预装。
为什么这样设计？因为 Pi 想让你搭一个属于自己的 Agent：
- 搞研究的 → 装 PDF 阅读和搜索 Skill
- 办公党 → 装表格处理 Skill
- 想做视频 → 装 Hyper Frames
- 想让它开口说话 → 装 Edge TTS
- 想生成图片素材 → 装 GPT Image 2
你装一个 Skill，Agent 就多一项能力。每个人手里的 Pi，长得都不一样。
Pi 官网上的原话精准概括了这一点：
世界上有很多很多其他不同类型的 Agent，但是这个 Pi Agent 就是你自己的 Agent。
核心理念：
Adapt Pi to your workflows, not the other way around（让 Pi 适应你的工作流，而不是反过来）。
常用快捷键
| 功能 | 操作方式 |
|---|---|
| 文件引用 | 输入 @ 模糊搜索项目文件 |
| 路径补全 | 按 Tab 键补全路径 |
| 多行输入 | Shift + Enter（Windows Terminal 中使用 Ctrl + Enter） |
| 粘贴图片 | Ctrl + V（Windows：Alt + V），或将图片拖入终端 |
| 执行 Shell 命令 | !command（输出会发送给模型） |
| 隐藏 Shell 命令 | !!command（输出不发送给模型） |
| 外部编辑器 | Ctrl + G 打开 $VISUAL 或 $EDITOR |
常用斜杠命令
在对话中输入 / 打开命令补全菜单。
| 命令 | 说明 |
|---|---|
/model | 切换模型 |
/settings | 配置思考层级、主题、消息传递方式、传输协议 |
/resume | 从之前的会话中选择并继续 |
/new | 开启新会话 |
/name <name> | 设置会话显示名称 |
/session | 显示会话文件、ID、消息数、token 数和费用 |
/tree | 跳转到会话树中的任意节点并继续 |
/fork | 从之前的某条用户消息创建新会话 |
/clone | 将当前活动分支复制到新会话 |
/compact [prompt] | 手动压缩上下文（可附带自定义指令） |
/copy | 将上一条助手消息复制到剪贴板 |
/export [file] | 将会话导出为 HTML |
/reload | 重新加载快捷键、扩展、技能、提示和上下文文件 |
/hotkeys | 显示所有键盘快捷键 |
/changelog | 显示版本历史 |
/quit | 退出 Pi |
常见问题
Pi Agent 和 Claude Code 有什么区别？
Claude Code 是给开发者写代码用的，预装了代码索引、测试、Git 等开发工具。Pi Agent 是给所有人做日常任务用的，底座极简，能力靠安装 Skill 扩展。详见上文对比表。
Pi Agent 免费吗？
Pi Agent 本身是开源工具，不收费。但你需要自己提供模型 API Key 或订阅账号，模型调用费用由对应的模型服务商收取。
Pi Agent 支持哪些模型？
Pi 支持多种模型，可以通过 /model 命令查看和切换。常见的如 DeepSeek、Claude 系列、OpenAI 系列等都可以配置使用。
为什么我的 Skill 安装后不生效？
确认安装路径正确，然后运行 /reload 重新加载。如果仍不生效，检查 ~/.pi/agent/ 目录下是否有对应的 Skill 文件。