起步建议：
安装 → 配置模型 → 创建 AGENTS.md → 简单任务练手 → 按需加 2-3 个 extensions
为什么 Pi Agent 值得你关注
过去一年，AI 的使用方式正在从“问聊天机器人”转向“让 Agent 在本地文件、命令行和工具之间连续完成任务”。这就是本地 Agent 值得关注的地方：它离真实工作更近，可以直接处理项目目录、资料、表格、脚本和最终输出，而不是停留在一问一答。
Pi Agent 是这个方向里很适合入门的一款工具。它在国内讨论不多，但在海外开发者和重度 AI 用户中已经形成了稳定使用群体。一个数据可以说明问题：在 OpenRouter 的排行榜上，Pi 每天的 token 消耗量排在第五名，紧紧跟在 Cloud Code 后面。
OpenAI Codex 的负责人甚至公开表示，他们大约有 5% 的生产流量已经跑在了 Pi Agent 上面。考虑到 Codex 这个量级的工具，5% 已经相当可观。
更关键的是，Pi 靠的是"低消耗高频率"。同样规模的任务，Pi 的 token 消耗大概只有 Cloud Code 的三分之一甚至更少。但每次对话消耗的 token 仅为其他 Agent 的几分之一，总消耗量却能排进前六。这说明有大量用户正在高频次地使用它来完成日常工作。
1. Pi 与其他 Agent 的区别
目前的 AI Agent 领域，T0 级别的工具大致有四款：Cloud Code、Codex、Open Code 和 Pi Agent。前三个从名字里的 "Code" 就能看出，核心定位是帮你写代码。它们预装了代码索引、测试运行、Git 操作、编码规范等一整套围绕代码交付设计的工具，开箱即用，对开发者非常友好。
但问题是，不是每个人每天都在写代码。更多人日常需要搜资料、读 PDF、整理表格、写汇报、做 PPT。预装一套通用编程工具，其实照顾不到这些日常办公需求。Pi Agent 走了一条截然不同的路。它不是专门帮你写代码的，而是帮你完成日常任务的。
| 类型 | 代表 | 产出 | 特点 |
|---|---|---|---|
| Coding Agent | Cloud Code、Codex、Open Code | 代码 | 内置完整写代码流程、工具和提示词，像预制菜一样开箱即用 |
| 日常任务 Agent | Pi Agent | 结果 | 底座极简，能力靠 Skill 一个一个加，每个人最后用到的 Pi 长得都不一样 |
更详细的对比：
| 对比维度 | Pi Agent | OpenCode |
|---|---|---|
| 设计哲学 | 原语（Primitives）而非功能（Features）——给你积木，你自己搭 | 终端里的全功能 IDE——开箱即用，功能完整 |
| 核心工具数 | 仅 4 个：read、write、edit、bash | 20+ 内置工具，包含 LSP 集成、多文件编辑、规划 Agent、记忆系统等 |
| 系统提示词 | ~200-1000 Tokens（极致精简） | 10K+ Tokens（功能越多，提示越重） |
| 安装复杂度 | 中（需要理解设计哲学，自己写扩展） | 低（一条命令安装，几分钟配好） |
| GitHub Stars | ~15K-32K | 140K+（社区人气王） |
| 开发者 | Mario Zechner（libGDX 作者） | AnomalyCo（SST 团队） |
| 编程语言 | TypeScript | Go |
注意：上表中的 "Pi Agent" 数据为官方 Pi 的规格。若使用 OMP（oh-my-pi，Pi 的官方 Fork），系统提示词可进一步精简至 ~200 Tokens，并额外获得 Hashline 锚定编辑、原生调试器挂载等增强功能。
Coding Agent 解决的是开发效率，Pi 解决的是工作流效率。当你把单一的 Skill 串起来的时候，Pi 能完成一个真正像工作一样的任务——从一句话开始，交付一份完整的行业调研演讲报告。
装搜索它就会联网，装 Office 相关它就会读资料，装 TTS 它就会开口说话，装 GPT Image 2 它就会生成图片素材，装 Hyper Frames 它就会做带动画的演讲和视频。你的 Pi，由你定义。
2. 极简底座与 Skill 扩展：Pi 的设计哲学
Pi Agent 的核心设计思路可以用一句话概括：把底座做得极简，把扩展交给用户按需安装。其他 Agent 的方向是功能越来越多、越来越重，Pi 则是反过来的。
它的底座只保留四个最基础的能力：读文件、写文件、改文件和跑命令。除此之外，什么都不预装。为什么这样设计？因为 Pi 想让你去搭一个属于自己的 Agent。如果你是搞研究的，可以装上 PDF 阅读和搜索 Skill；如果你是办公党，可以装表格处理 Skill；如果你想让它开口说话，就装 Edge TTS；如果你想做视频，就装 Hyper Frames。你装一个 Skill，Agent 就多一项能力。每个人最后手里的 Pi，长得都不太一样。
Pi 官网上的口号精准地表达了这一理念：
"世界上有很多很多其他不同类型的 Agent，但是这个 Pi Agent 就是你自己的 Agent。"
核心理念是：
"Adapt Pi to your workflows, not the other way around"（让 Pi 适应你的工作流，而不是反过来）。
Skill 是什么？简单来说，就是一份给 Agent 的说明书或操作手册。Agent 读完之后，就知道该怎么具体干活了。底座保持极简，能力按需安装，这就是 Pi 的设计思路。
3. Pi Agent 快速上手
Pi 默认运行在命令行里，也可以通过网页界面使用。安装首先需要 Node.js（20+ 推荐）。
3.1 安装
curl -fsSL https://pi.dev/install.sh | sh
# 或者 npm 安装
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 卸载
npm uninstall -g @earendil-works/pi-coding-agent
安装后，所有配置、sessions、packages 都在 ~/.pi/agent/ 目录下。推荐在项目目录下启动 Pi，它会自动读取本地文件。
3.2 配置 Provider 和 Model
启动 Pi：
cd /path/to/your/project
pi
-
方式 1：订阅登录（Claude Pro、ChatGPT Plus 等）：输入
/login，选择 provider 按提示操作。 -
方式 2：API Key（推荐生产场景，便于 Secrets 管理）：
export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY 等 pi启动后用
/model或Ctrl+P切换模型，Shift+Tab切换思考强度（thinking level）。
如果是团队部署，可以用环境变量或 ~/.pi/agent/auth.json，结合公司 Secrets Manager（如 HashiCorp Vault、AWS Secrets）注入。避免硬编码。
模型调通后测试一下，发个"你好"确认连通，再让它看看桌面上有什么——它已经能读取电脑上的文件了。哪怕什么 Skill 都没装，Pi 已经能完成不少事情了，比如整理文件夹、批量改文件名、执行命令跑脚本。只要是本地电脑上能通过文件和命令完成的事，它基本都能帮你做。
3.3 常用快捷键
| 功能 | 操作方式 |
|---|---|
| 文件引用 | 输入 @ 以模糊搜索项目文件 |
| 路径补全 | 按 Tab 键补全路径 |
| 多行输入 | Shift + Enter，或在 Windows Terminal 中使用 Ctrl + Enter |
| 图片 | 使用 Ctrl + V、Windows 上使用 Alt + V，或将图片拖入终端 |
| Shell 命令 | !command 执行并将输出发送给模型 |
| 隐藏 Shell 命令 | !!command 执行但不将输出发送给模型 |
| 外部编辑器 | Ctrl + G 打开 $VISUAL 或 $EDITOR |
查看快捷键了解所有快捷方式和自定义选项。
3.4 常用斜杠命令
在编辑器中输入 / 打开命令补全。
| 命令 | 说明 |
|---|---|
/model | 切换模型 |
/settings | 思考层级、主题、消息传递方式、传输协议 |
/resume | 从之前的会话中选择并继续 |
/new | 开启新会话 |
/name <name> | 设置会话显示名称 |
/session | 显示会话文件、ID、消息数、令牌数和成本 |
/tree | 跳转到会话树中的任意节点并继续 |
/fork | 从之前的某条用户消息创建新会话 |
/clone | 将当前活动分支复制到新会话 |
/compact [prompt] | 手动压缩上下文，可附带自定义指令 |
/copy | 将上一条助手消息复制到剪贴板 |
/export [file] | 将会话导出为 HTML |
/reload | 重新加载快捷键、扩展、技能、提示和上下文文件 |
/hotkeys | 显示所有键盘快捷键 |
/changelog | 显示版本历史 |
/quit | 退出 pi |
3.5 会话管理
会话自动保存至 ~/.pi/agent/sessions/，按工作目录组织。
pi -c # 继续最近的会话
pi -r # 浏览并选择会话
pi --no-session # 临时模式；不保存
pi --name "my task" # 启动时设置会话显示名称
pi --fork <path|id> # 将会话分叉到新会话文件
会话自动保存为 JSONL 树结构，极适合长周期任务。详情请参阅会话和压缩。
导出与分享：
/export [file]将会话写入 HTML/share上传为私有 GitHub Gist 并生成可分享的 HTML 链接
非交互模式：
pi -p "Generate a Dockerfile for this app" # 打印回复后退出
cat input.txt | pi -p "Summarize this" # 管道输入
4. OMP 快速上手
OMP（oh-my-pi）是 Pi 的官方 Fork，由原作者维护，在 Pi 基础上做了开箱即用的全功能增强。如果你希望一步到位，可以直接安装 OMP。
4.1 安装
| 方式 | 命令 | 适用场景 |
|---|---|---|
| Bun | bun install -g @oh-my-pi/pi-coding-agent | 已安装 Bun >= 1.3.14 |
| 安装脚本 | curl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh | 其他情况；优先用 Bun，否则回退预编译二进制 |
| mise | mise use -g github:can1357/oh-my-pi | 按项目锁定版本 |
验证：
omp --version # PATH 中二进制文件的版本
omp config path # 当前激活的 agent 目录
omp -p 'hello' # 发送一次性提示词并接收响应
4.2 配置 Provider 和 Model
接入提供商有两种方式：启动前设置环境变量，或在 TUI 内使用 /login 进行 OAuth 认证。
方式一 — 环境变量：
export ANTHROPIC_API_KEY=sk-ant-...
omp
其他常用密钥：OPENAI_API_KEY、GEMINI_API_KEY、XAI_API_KEY、GROQ_API_KEY、MISTRAL_API_KEY、OPENROUTER_API_KEY、ZAI_API_KEY。
方式二 — /login：
omp
/login
你将看到一个按字母排序的选择器。/login 追加凭据，不会覆盖已有记录；/logout 清除已选提供商。同一提供商下，已保存的 API 密钥优先于 OAuth。所有凭据存储在 ~/.omp/agent/agent.db 中——迁移设备时请备份该文件。
4.3 常用快捷键
OMP 的编辑器与 Pi 类似，但增加了一些功能：
| 功能 | 操作 | 说明 |
|---|---|---|
| 文件引用 | @ | 对项目文件进行模糊搜索（遵守 .gitignore） |
| 路径补全 | Tab | 补全相对路径、../、~/ 等前缀 |
| 多行输入 | Shift + Enter / Alt + Enter | 插入换行。Windows Terminal 改用 Ctrl + Enter |
| 图片附加 | Ctrl + V、拖放或 @image.png | 从剪贴板粘贴或拖入 |
| Shell 转义（可见） | ! | 在提示词前加 ! 作为 shell 命令执行，并将输出纳入上下文 |
| Shell 转义（隐藏） | !! | 与 ! 相同，但输出不进入 LLM 上下文 |
| Python 转义 | $ / $$ | 在共享的 Python 内核中运行。$$ 对上下文隐藏输出 |
| 外部编辑器 | Ctrl + G | 在 $VISUAL / $EDITOR 中打开当前草稿 |
| 提示词操作 | # | 在当前草稿上打开提示词操作菜单 |
| 展开工具输出 | Ctrl + O | 展开/折叠工具调用卡片 |
完整的快捷键列表见 Keybindings。
4.4 常用斜杠命令
OMP 保留了 Pi 的所有斜杠命令，并新增了大量功能。以下是 OMP 特有的常用命令：
| 命令 | 说明 |
|---|---|
/plan | 切换计划模式；先草拟计划再执行 |
/branch | 从历史消息分支（同一文件，新叶子节点） |
/handoff [focus] | 撰写结构化总结并结束当前轮次 |
/login / /logout | OAuth 登录 / 撤销授权 |
/share | 上传会话为私密 GitHub Gist（或自定义处理器） |
/goal <subcommand> | 持久化的自主目标（set、show、pause、resume、drop、budget） |
/loop [count|duration] | 切换循环模式 |
/background (/bg) | 分离 UI，在后台继续运行 |
/compact [focus] | 手动压缩会话上下文 |
/btw <question> | 基于当前上下文的临时旁问 |
4.5 会话管理
会话自动保存至 ~/.omp/agent/sessions/，按工作目录分组。
omp -c # 继续当前目录下最近的一次会话
omp -r # 打开限定在当前项目的选择器
omp -r 1f9d2a # 按 ID 前缀恢复
omp --no-session # 临时会话；不写入磁盘
omp --fork <path|id> # 将会话派生到新文件
导出与分享：
/export [path]将当前会话渲染为自包含的 HTML/share上传到私密 GitHub Gist，或调用自定义处理器/handoff [focus]生成交接文档并开启新会话
非交互模式：
omp -p "list .ts files in src/" # 一次性模式
5. 上下文文件
Pi 在启动时自动加载 AGENTS.md，搜索路径如下（按优先级）：
~/.pi/agent/AGENTS.md（全局指令）- 从当前工作目录向上遍历的所有父目录
- 当前目录
通过上下文文件配置项目约定、命令、安全规则和偏好。使用 --no-context-files 或 -nc 禁用加载。
强烈推荐在项目根目录或 ~/.pi/agent/ 创建 AGENTS.md：
# Project Instructions
- Always run `npm run check` after changes.
- Use TypeScript strict mode.
- Keep commits atomic.
修改后输入 /reload 生效。
系统提示文件（进阶）：
- 替换默认系统提示：
.pi/SYSTEM.md（项目级）或~/.pi/agent/SYSTEM.md（全局） - 追加到默认提示（不替换）：在上述任一位置使用
APPEND_SYSTEM.md
6. 用 Skill 逐步解锁能力
核心思路只有一个公式：Agent + Skill。这是现在最基本的框架、最本质的逻辑。
下面的演示不单纯是装一个 Skill，而是装一个 Skill 马上跑一个小任务。你会看到 Pi 如何从一个只能读写文件的本地 Agent，一步步变成能搜索、能读资料、能说话、能生图、甚至能做视频的工作流 Agent。
Skill 安装时有 Global 和 Project 两个选项。Global 意味着所有项目都能使用这个 Skill；Project 则只有当前项目能用。一般默认选 Global。
6.1 读文件 Skill：处理 PDF 与 Office 文档
PDF 相关推荐 OpenAI 发布的文字版 PDF Skill，它会提取文字来读。如果是扫描版 PDF，需要在 Pi 模型设置里打开图像识别能力，让模型能看到 PDF 里面的图。
安装好后用 DeepSeek v4 的技术报告来测试。把 PDF 拖进工作目录，艾特这份报告，直接跟 Pi 说"读取这个 PDF，总结里面的核心信息"。Pi 会自己调用 PDF Skill，把十几页的报告都读完，最后整理成结构化的总结。你不用去复制 PDF 的内容，也不用自己提取文字，直接把文件丢给它，剩下的叫它自己处理。
6.2 视频 Skill：制作动画演讲
最后一步，让 Pi 增加做视频的功能。直接搜索 Hyper Frames 并安装。这是非常适合做讲解类视频、产品介绍、科普动画和过程演示的 Skill。
它的思路很巧妙：不是直接让 AI 生成视频，而是先让 Agent 写一个带动画的 HTML 网页。HTML 因为是代码组成的，生成的时候非常稳定，又可编辑、可预览，然后再逐帧渲染成一个完整的视频。对你来说完全不需要懂 HTML 代码是什么意思，只要告诉他你想要什么结果就行。
安装后先跑一个小 demo，让 Pi 用 Hyper Frames 做一个 20 秒的动画解释什么是 Agent，只生成 HTML，不需要渲染视频。它能做标题、转场、图形动画、字幕的节奏。继续加上语音、加上图片，就能变成一条完整的视频。
6.3 更多扩展推荐
Pi 的插件 / 扩展生态非常活跃，可通过 pi install npm:<包名> 或 git 来源安装。推荐查看官方包目录：pi.dev/packages。
pi install npm:pi-subagents # 子代理
pi install npm:pi-mcp-adapter # MCP 支持
pi install npm:pi-web-access # 网页搜索
pi install npm:context-mode # 极致上下文节省
pi install npm:pi-hermes-memory # 记忆扩展
pi list
Skills：可复用能力包（放 ~/.pi/agent/skills/），Prompt Templates（/name 展开）。
自定义：问 Pi "帮我写一个 XXX extension"，它能自我修改，改完 /reload 即可用。
安装建议：先少量安装（避免上下文膨胀），优先安全类（permission-gate、guardrails）。
7. 消息队列与中途干预
Pi 和 OMP 都支持在代理工作时提交消息，无需等待当前任务完成：
- Enter — 将一条引导消息（steering message）加入队列，在当前助手回合完成其工具调用后送达
- Alt + Enter — 将一条后续消息（follow-up message）加入队列，在代理完成所有工作后送达
- Escape — 中止操作并将队列中的消息恢复到编辑器
- Alt + Up — 将队列中的消息取回编辑器
8. 长任务怎么不跑偏：上下文、压缩与注意力管理
当你开始用 Pi 或 OMP 做几十轮以上的任务，真正的难点就不再是安装和配置，而是怎么让 Agent 一直记得自己在干什么。
长对话里最常见的问题不是 token 用完，而是注意力被污染：前面读过的文件、执行过的命令、失败过的尝试、用户临时补充的要求、工具返回的大段日志，都会挤在同一个上下文里。模型看得越多，不一定越清楚。真正关键的是：哪些内容必须继续给它看，哪些内容可以摘要，哪些内容应该离开上下文但保留路径。
所以 /compact 不应该只被理解成“压缩历史”。它更像一次任务整理：把用户目标、硬约束、当前进度、关键证据和下一步重新摆清楚。如果只是短任务，普通摘要就够了；如果是长周期任务，最好主动告诉 Agent 压缩时保留什么，例如：
/compact 保留用户原始要求、禁止项、已完成步骤、失败命令、关键文件路径和下一步计划。
最需要保护的是用户原文和硬约束。比如你说“不要改数据库迁移，只改展示层”，这句话不能被压成“用户希望做前端修改”。后者听起来差不多，但已经丢掉了禁止项，后续 Agent 就可能误碰迁移文件。长任务里，AGENTS.md、项目规则、用户最新纠偏，都应该被当成高优先级上下文。
工具输出也要分层处理。短命令输出、小 diff、关键报错可以直接留在上下文里；长网页、完整构建日志、大文件内容更适合落盘，只在上下文里保留摘要、路径和关键命中行。这样 Agent 不需要每一轮都重读完整日志，但需要追溯时还能找回原始材料。
一个简单的实践顺序是：
- 先让 Agent 记清楚目标和禁止项。
- 遇到长工具输出时，让它提炼关键行并保留文件路径。
- 多轮任务中定期使用
/compact或/handoff，要求保留当前状态和下一步。 - 对大任务优先分阶段做，每阶段结束后让 Agent 写一份短交接。
- 不要一开始就装太多扩展，Skill 越多，上下文越容易膨胀。
短流程助手不需要复杂压缩；真正需要上下文管理的是那些会持续几十轮、工具调用很多、用户约束很多、需要保留审计路径的任务。Pi 和 OMP 的价值也在这里：它们不只是能聊天，而是能把一个本地工作流持续推进下去。
