对比项	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 用这行：

Windows 用 PowerShell：

第二条，npm。

第三条，Nix。

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

装完验证：

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

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

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

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

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

三、界面认一遍

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

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

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

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

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

四、上手：一节一件事

先登录，再选模型

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

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

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

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

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

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

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

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

会话是一棵树

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

常用的几条：

聊到一半想换方案，在界面里敲 /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 config。装了一堆包，不是每个都想常开。这个面板能按项目开关，Tab 键切换范围。

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

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

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

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

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

让它改自己

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

你可以直接让它改自己：

改完敲 /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 的命令行默认 provider 是 google。机器上没有 Google 的 key，第一次启动就会卡在登录。

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

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

六、它在生态里的位置

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

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