超简单 PI Agent ，入门到精通，个人智能体的王者

想风·约 10 分钟阅读

2026年10月22日10月22日

文章目录

大家好，我是想风！

今天来看 Pi（Pi Coding Agent），一个极简、可以自己改自己的智能体框架，本篇写给新手小白，新手也能学会！

标题里写的 PI Agent，就是 Pi。它的 npm 包名是 @earendil-works/pi-coding-agent，命令只有两个字母：pi。

这是什么
下载和安装
界面认一遍
上手：一节一件事
坑集锦
它在生态里的位置
最后

一、这是什么：一盒能自己改自己的积木

Pi 是一个跑在终端里的 AI 编程智能体。你用自然语言下任务，它读文件、跑命令、改代码。和 Claude Code、Codex 干的是同一类活。

路线不一样。

官方把 Pi 叫作 minimal agent harness，最小智能体外壳。内核只保留最基本的工具循环，其他能力全部拆出去，交给扩展。

官网挂着一句原话：Adapt Pi to your workflows, not the other way around. 让 Pi 适应你的工作流，不是让你适应它。

这句不是标语，是产品设计。它默认连 plan mode、sub-agents 都不带，权限系统也不内置。想要，自己装。

对比项	Pi	Claude Code、Codex 这类成品
内核	最小，只留基本循环	大而全
开箱功能	少，计划模式、子智能体都要另外装	多，装完就能干活
扩展	技能、扩展、提示词模板、主题，都能打包分享	有官方扩展点，改不到最里面
权限	没有内置权限系统，靠容器隔离	自带审批流程
适合谁	想养一个自己的智能体	想马上把活干完

为什么值得花时间学它？

大多数智能体是成品家电。功能多，流程固定，你只能按它的方式用。

Pi 是一盒积木。技能、扩展、提示词模板、主题，四样东西都能自己写，打包成 Pi package，发到 npm 或 git，别人一条命令就能装。

它还是 MIT 协议。15 家以上模型商，几百个模型，Anthropic、OpenAI、Google、Bedrock、Ollama 都能接，不绑死一家。

它有四个使用模式：交互、打印/JSON、RPC、SDK。一个内核，终端能用，脚本能用，自己的程序里也能嵌。

会话存成树，不是一条线。聊到一半想试另一个方向，回到任意节点开分支，原路不丢。

标题说它是个人智能体的王者。王者不在功能表最长，在于装完之后，这东西是你的。你往里装什么，它就长成什么样。

二、下载和安装

前置条件只有一条：Node.js 22.19 或更高。

三条安装路，挑一条。

第一条，官方脚本。 macOS 和 Linux 用这行：

curl -fsSL https://pi.dev/install.sh | sh   # 官方安装脚本，会锁定依赖版本

Windows 用 PowerShell：

powershell -c "irm https://pi.dev/install.ps1 | iex"   # Windows 安装脚本

第二条，npm。

npm install -g --ignore-scripts @earendil-works/pi-coding-agent   # 全局安装

第三条，Nix。

nix run github:earendil-works/pi/stable   # 从源码构建，支持 Linux 和 macOS

三条路的区别在依赖：官方脚本会锁定版本，npm 不锁传递依赖，Nix 从源码构建。想省心，用第一条。

装完验证：

pi --version   # 能打印出版本号，就装好了

装完先做三件事(或可选第三方登录)

第一件，连上一个模型。 直接敲 pi 进界面，再输入 /login，按提示选模型商。也可以用环境变量：

export ANTHROPIC_API_KEY="你的 key"    # Claude
export OPENAI_API_KEY="你的 key"       # OpenAI
export GEMINI_API_KEY="你的 key"       # Google

第二件，定默认模型。 配置文件在 ~/.pi/agent/settings.json：

{
  "defaultProvider": "openrouter",
  "defaultModel": "moonshotai/kimi-k2.6"
}

不写也行，启动时用 --provider 和 --model 临时指定。

第三件，想清楚隔离。 Pi 没有内置权限系统，跑起来就是你自己的权限。拿它碰不熟的项目之前，先把容器方案想好。这条放在坑一里细讲。

三、界面认一遍

敲 pi 回车，进的是终端界面，不是网页。

终端界面的布局每个版本会微调，不用背。真正要记的是几个键：

按键	作用
Enter	任务跑着时也能插话，马上生效
Alt + Enter	排队，等当前这轮干完再发
Ctrl + L	切换模型
Ctrl + P	在收藏的几个模型之间轮换
`/`	打开斜杠命令

斜杠命令常用的有这几个：

/login     # 登录模型商  可选Claude\Chatgpt\Deepseek\Gemini、OpenRouter（中转稍贵）
/model     # 换模型
/tree      # 回到会话的任意节点，开一条新分支
/export    # 把这次会话导出成 HTML
/share     # 分享成一个 GitHub gist
/reload    # 改完扩展或主题后，热加载

界面不花哨。它的价值不在好看，在于你能一边看它干活，一边改它的方向。

四、上手：一节一件事

先登录，再选模型

第一次用，先确认模型通不通。

pi --list-models kimi            # 按关键词搜可用模型
pi --model sonnet:high "帮我分析这个报错"   # 指定模型，顺手把思考等级拉高
pi --models claude-sonnet,claude-haiku,gpt-4o   # 只在这三个里 Ctrl + P 轮换

思考等级有七档：off、minimal、low、medium、high、xhigh、max。日常改代码用默认档就够，复杂重构再往上调。

模型没通，后面全是白搭。

第一个任务：先让它读，别让它写

进项目目录，开一个只读任务：

cd 你的项目目录
pi "先读一遍项目结构，告诉我入口文件在哪，先不要改代码"

这一步是摸清它的脾气。它读文件、列目录、跑只读命令，你看它理解得对不对。

想更保险，直接把工具锁死成只读：

pi --tools read,grep,find,ls -p "review 一下 src 目录的代码"   # 一个写操作都不给

这里有个容易踩的点。内置工具里，read、bash、edit、write 默认开着，grep、find、ls 默认是关的。它想自己搜文件，得手动打开：

pi --tools read,bash,edit,write,grep,find,ls   # 全套工具都开

会话是一棵树

每次对话都会存成一个 session。默认放在 ~/.pi/agent/sessions，可以用 --session-dir 改地方。

常用的几条：

pi --name "重构登录模块"      # 给这次会话起个名字
pi -c "接着上次的改"          # 继续上一次会话
pi -r                         # 列出历史会话，挑一个恢复
pi --fork <会话 ID>           # 从某个会话分叉，原会话不动

聊到一半想换方案，在界面里敲 /tree。回到任意一个节点，开新分支。原分支还在，随时能切回去。

这条比「重新开一个对话」省太多事。上下文不用重新喂。

边跑边改：Enter 和 Alt + Enter

Pi 干活的时候，输入框没锁。

发现它方向不对，直接按 Enter 打一句「别动数据库，只改前端接口」。这句话会立刻插进去，它当场调整。

手上还有下一件事，按 Alt + Enter。这句话排队，等当前这轮干完再发。

区别就一个：Enter 是现在说，Alt + Enter 是等会儿说。

教它新本事：技能、扩展、模板、主题

四样东西，分工不同：

技能（skills）：一份 Markdown 说明书，加可选的脚本和资料，告诉它某类任务怎么做。放在 ~/.pi/agent/skills，启动时自动发现。
扩展（extensions）：真正的代码。能加工具、加命令、加启动参数。
提示词模板（prompt templates）：Markdown 写的常用提示词，不用每次重打。
主题（themes）：终端配色。

这四样打包起来，就是 Pi package，可以发到 npm 或 git。

装包、看包、卸包：

pi install npm:@foo/pi-tools                    # 从 npm 装
pi install git:github.com/badlogic/pi-doom      # 从 GitHub 装
pi list                                         # 看装了哪些
pi config                                       # 打开面板，启用或禁用某个资源
pi update                                       # 更新 pi 和已装的包
pi remove npm:@foo/pi-tools                     # 卸载

只想临时用一个技能，不装进全局：

pi --skill ./skills/my-skill "用这个技能处理这批文件"
pi --no-skills "这次一个技能都不要加载"

新手最容易忽略 pi config。装了一堆包，不是每个都想常开。这个面板能按项目开关，Tab 键切换范围。

自动化：脚本、事件流、RPC、SDK

交互界面只是四种用法里的一种。

pi -p "总结这个仓库做了什么" > summary.txt    # 跑完就退出，适合放进脚本
pi --mode json -p "检查依赖有没有过期" | jq    # 输出事件流，适合接程序

-p 是打印模式，一问一答，干完走人。--mode json 把过程拆成一条条 JSON 事件，方便程序读。

再往上一层是 RPC 模式和 TypeScript SDK。RPC 用 --mode rpc，让另一个程序控制一个独立的 Pi 进程。SDK 直接把 Pi 嵌进自己的 TypeScript 应用。

想把 Pi 塞进自己的工作流，这三层够用了。

让它改自己

Pi 的扩展、主题、提示词，都是磁盘上的文件。

你可以直接让它改自己：

把这个扩展的通知文案改成中文，保存后我执行 /reload

改完敲 /reload，不用重启，新代码立刻生效。

这是 Pi 和成品智能体最不一样的地方。成品你只能等厂商更新，Pi 可以当场长出新器官。

MCP 和 Codemode

MCP 是内置的。它是一个让 AI 连外部工具和数据的标准，第一次见可以理解成「给智能体装 USB 接口」。

Codemode 是另一层：让智能体把一串工具调用写成 JavaScript，在沙箱里一次跑完。

工具调用多的时候，省的是来回次数。适合流程固定、步骤多的活。

五、坑集锦（这部分值回票价）

坑一、它没有内置权限系统

这是最需要先知道的一条。

Pi 以启动它的用户权限运行。你能读的文件它能读，你能删的它能删，你能连的网络它能连。官方文档写得很直白：文件、进程、网络、凭据，都没有内置限制。

官方给的方案是上容器。Gondolin 微虚拟机扩展、普通 Docker、OpenShell，三种都可以。

别拿它直接跑在生产机上，也别在放着密钥的目录里裸跑。

坑二、默认没有 plan mode 和子智能体

这是故意的，不是缺功能。

官方文档写得很清楚：给零件，不给成品。计划模式、子智能体、权限检查，都留给扩展。

从 Claude Code 或 Codex 过来的人，第一次用会觉得「怎么什么都要自己装」。先接受这件事，再决定要不要装对应的包。

坑三、npm 安装不锁传递依赖

官方脚本会锁定依赖版本，npm 这条路不会。

供应链安全是 Pi 很在意的一件事。它的做法是锁直接依赖、强制 lockfile、安装时加 --ignore-scripts。

所以能用官方脚本，就别图省事走 npm。

坑四、grep、find、ls 默认是关的

第一次让它找文件，它可能绕一大圈。

内置工具里，read、bash、edit、write 默认开，grep、find、ls 默认关。想让它像别的智能体那样自己搜，启动时用 --tools 打开。

或者干脆让它用 bash 里的 grep。能用，但不如内置工具省 token。

坑五、项目里的资源要批准，批准不等于隔离

项目目录里如果带扩展、技能、配置，Pi 默认不会乱加载。

--approve 信任这个项目的本地文件，--no-approve 忽略它们。

但信任只解决「加载不加载」，不解决「跑起来安不安全」。官方安全文档专门写了这一句：项目信任控制的是加载哪些资源，不是给工具调用加沙箱。

批准之前，先看一眼项目里到底放了什么。

坑六、会话不命名，很快就找不到

Pi 把每次对话都存下来，这是好事。攒到几十上百条，-r 的列表就没法看了。

养成两个习惯：开长任务先 --name，重要节点用 /tree 分叉。

会话目录也能换。工作区和私人项目分开存，找起来快很多：

pi --session-dir ~/pi-sessions/work

坑七、模型没配好，启动就卡住

Pi 的命令行默认 provider 是 google。机器上没有 Google 的 key，第一次启动就会卡在登录。

两条路：进去敲 /login，或者启动时直接指定：

pi --provider openai --model gpt-4o-mini
pi --model anthropic/claude-sonnet   # 带厂商标识，不用再写 --provider

模型名不用背。pi --list-models 会列出来，后面跟关键词还能模糊搜。

六、它在生态里的位置

Pi 不只是一个终端命令，它是一组 npm 包。

包	管什么
`pi-ai`	一个 API 接多家模型
`pi-agent-core`	工具调用和状态管理
`pi-coding-agent`	终端里那个 `pi`
`pi-tui`	终端界面库
`chord`	插件运行环境，支持热重载和 RPC
`pi-durable`	会话、任务、文档的存储
`pi-telemetry`	遥测数据的统一接口