上周我第三次装 Pi。

第一次装完，它回了我一句「你好」，然后我就关了。第二次装完，我照着文档接了模型，还是只会聊天。第三次才摸清：这东西的力气全在装完之后那二十个开关上，模型怎么接、扩展怎么装、MCP 和扩展差在哪、会话断了怎么接上，每一个都够单独写一段。

Pi 1.4.0 是 10 月 21 日发的，到现在八天。GitHub 上 11.45 万星，npm 一周下载 454 万次。生态里光是我今天翻到的扩展就有十几个过了五百星，最大的那个 `pi-web-access` 1738 星，昨天还在推新版本。

这篇要讲的东西，先列一遍：

```text

一、装：Windows 两条路，哪条不坑

二、接模型：/login 里没有的选项，要自己写文件

三、界面：三块区域，一句口诀

四、四个概念：provider / 权限 / 会话 / 四类资源

五、哪些设置别动

六、六件事：模型、扩展、MCP、Skills、会话、-p 模式

七、五类活：每一类给一段能直接抄的提示词

八、进阶：让扩展替你联网，再自己写一个

九、扩展、MCP、Skills 到底差在哪

十、我踩过的 10 个坑

十一、收尾

```

全文七千字左右，每一步都有真机截图，命令能直接抄。建议先收藏，装的时候开着对照，中间有几处容易卡住。

一、装：Windows 上别用那个 sh 脚本

Pi 官网给的第一条命令是 `curl -fsSL https://pi.dev/install.sh | sh`。这条在 Windows 的终端里跑不通，那是给 macOS 和 Linux 的。

Windows 有两条正路。

第一条，PowerShell 安装器。 官网有专门的 Windows 脚本，会帮你固定好依赖，装完能用 `pi update` 自更新。适合想一劳永逸的人。缺点是它的下载源在国外，网络不好时容易卡在第一步。

第二条，npm。 前提是 Node 22.19 或更高。我用的这条：

```powershell

node --version

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

pi --version

```

`node --version` 低于 22.19 就别往下走了，先去装 Node。`--ignore-scripts` 是我加的习惯，装包时不跑安装钩子，出问题好排查。整条命令三十多秒，装完 `pi --version` 回一句 `1.4.0` 就算成了。

装不上的两种情况：一是公司电脑限制了 `npm install -g`，改成装到一个固定目录再加 PATH；二是网络卡在下载，换镜像源 `npm config set registry https://registry.npmmirror.com` 通常能救。

装完先看自己装在哪：

```powershell

(Get-Command pi).Source

```

它会回一个具体路径。这个路径后面有用，卸载的时候就是删这个目录对应的包。

什么时候该升级？ 跑 `pi update` 就行。1.x 的小版本更新很快，我装的时候是 1.4.0，三周前还是 1.1.0。升级不会动你的 `models.json` 和扩展列表，放心升。

二、接模型：`/login` 里没有的那一项，得自己写文件

打开 Pi 打 `/login`，列表里是一串官方支持的服务商。国内常用的 SiliconFlow、DeepSeek 直连、各种中转站，一个都不在里面。

新手到这一步就停住了。正路是写一个文件：`~/.pi/agent/models.json`，Windows 上就是 `C:\Users\你的用户名\.pi\agent\models.json`。没有这个目录就自己建。

```json

{

"providers": {

"siliconflow": {

"name": "SiliconFlow",

"baseUrl": "https://api.siliconflow.cn/v1",

"api": "openai-completions",

"apiKey": "$SILICONFLOW_API_KEY",

"models": [

{ "id": "moonshotai/Kimi-K2.7-Code", "name": "Kimi K2.7 Code" },

{ "id": "deepseek-ai/DeepSeek-V3.2", "name": "DeepSeek V3.2" }

]

}

}

}

```

三个地方值得说清。

`apiKey` 写 `$SILICONFLOW_API_KEY` 这种形式，Pi 会去读环境变量。key 不进文件，这个文件以后分享给别人、发到群里都不慌。你要是懒得配环境变量，直接写死也行，但那个文件别往网盘里放。

`api` 那行照抄 `openai-completions` 就行。国内九成服务商都是 OpenAI 兼容协议，写错了会报一堆看不懂的解析错误。

`models` 数组里只写你真正要用的。写多了 `/model` 列表翻半天，没意义。

想接别家怎么办？ 结构一模一样，改三个字段就行。接 DeepSeek 官方：

```json

"deepseek": {

"name": "DeepSeek",

"baseUrl": "https://api.deepseek.com/v1",

"api": "openai-completions",

"apiKey": "$DEEPSEEK_API_KEY",

"models": [{ "id": "deepseek-chat", "name": "DeepSeek Chat" }]

}

```

接中转站也一样，把 `baseUrl` 换成它给的那个地址，`models` 里填它文档上写的模型名。只要它兼容 OpenAI 的接口格式，Pi 就能接，这一条能覆盖国内九成服务。

写完验证一句：

```powershell

pi --list-models | Select-String siliconflow

```

三个模型整整齐齐出现在表里，128K 上下文、16.4K 输出，说明这条路通了。表里最后两列是「支持思考」和「支持图片」，我这几款都是 no，说明它们不吃图，别拿图片去喂。

选哪个模型？ 我的用法是两个：改代码、跑长任务用 Kimi K2.7 Code，它在这个价位里工具调用最稳；只做总结、抽字段这类轻活换 DeepSeek V3.2，便宜。两个都在 `models` 里挂着，`/model` 一键切。

三、界面：三块区域，一句口诀

Pi 跑起来是个全屏终端界面。第一次见会觉得空，其实就三块：

上面是对话流，中间偏下是输入行，最底下一行是状态栏。

对话流里会显示模型说的话、它调用了什么工具、工具返回了什么。状态栏显示当前模型、上下文用了多少、当前目录。

记住一句口诀：斜杠管命令，@ 管文件，感叹号管终端。

输入 `/` 弹命令列表，`/model` 换模型、`/resume` 翻历史会话、`/compact` 压缩上下文、`/tree` 看会话分叉。输入 `@` 弹文件补全，直接把某个文件塞进这句话的上下文里。输入 `!` 开头的命令不走模型，当成普通终端命令直接执行。

几个我天天用的：

| 按键 | 干什么 |

|---|---|

| `/model` | 换模型 |

| `/compact` | 上下文快满了，压一压再继续 |

| `/resume` | 翻出以前的会话接着聊 |

| `/tree` | 看这个会话分过哪些叉 |

| `Ctrl+C` | 打断它，改主意了 |

| `!命令` | 直接跑一条终端命令，不经过模型 |

`/compact` 这个值得单独提。长任务跑久了上下文会满，满了就报错。压一下会把它前面说过的话缩成摘要，腾出空间继续干。压缩的时机和保留多少，1.4.0 改成了按模型的输出上限来算，比之前稳。

第一次启动它会问你三件事：用哪个模型服务、要不要登录、当前目录信不信任。第三项别随手点信任，那意味着允许 Pi 在这个目录里读项目级配置文件（`.pi/` 下的东西），只对你自己可控的目录点。

启动位置也有讲究。Pi 会把当前工作目录当成项目根，会话存在哪、它认定的「项目范围」多大，都跟着这个目录走。所以进项目之前先 `cd` 到项目根，别在用户主目录那种地方直接开。

四、四个概念，一次分清

provider 和 model

provider 是服务商，model 是具体那个模型。同一个 provider 下面挂几个 model。启动时可以用参数指定，也可以在界面里用 `/model` 换。

```powershell

pi --provider siliconflow --model moonshotai/Kimi-K2.7-Code

```

长命令记不住就写进别名，或者干脆用 `/model`。

权限：默认继承你的账户权限

这一条要单独说。Pi 默认用你当前 Windows 账户的权限跑命令，没有沙箱。

意思是它能删你的文件、能改你的注册表、能往任何目录写东西。这不是 bug，是它设计上的取舍，因为它要能像你一样操作这台机器。

新手最稳的做法：第一次跑陌生任务，先开一个新的空目录，在那里试。 确认它听话了再放进真项目。跑重要仓库之前，先 `git commit` 一下，出问题能回滚。

想收紧的话有两个口子：一是用 `--tools` 只给它几个工具，比如 `--tools read,edit` 就只能读和改，不能跑命令；二是把它装进容器里跑，官方文档有 docker 那一节。新手期用不上，先知道有这两条路就行。

会话

每次对话存成一个 session，存在项目目录下。断了不怕，`pi --continue` 接着上一句，`pi --resume` 弹列表挑一个，`pi --fork` 复制一份出来另开分支试。长任务尤其有用，跑到一半电脑休眠了，回来接着跑。

四类资源：扩展、Skills、提示词模板、主题

这是新手最容易糊的地方。四样东西都放在 `~/.pi/agent/` 下面，但管的事完全不同：

• 扩展（extensions）：能写代码的，给 Pi 加新工具、改行为。真正能干活的都是它。
• Skills：一段给模型看的说明书，教它某种任务该怎么做，不执行代码。
• 提示词模板：几个常用问句存起来，输入时一键调出。
• 主题：纯外观。

记法：扩展加能力，Skills 加知识，模板加熟练，主题加好看。

五、哪些设置别动

新手期只有两个文件值得改：`models.json` 和 `settings.json`，都在 `~/.pi/agent/`。

`settings.json` 里主要就一个 `packages` 数组，记着装了哪些扩展。这个文件不要手改，统一用 `pi install` 和 `pi remove` 让它自己维护，手改容易和实际目录对不上。

其余的 `mcp.json`（MCP 服务器）、`auth.json`（登录凭证）、`models-store.json`（模型缓存）都不用碰，都有命令能管。

有个例外：`pi remove` 失败的时候，你得手动去 `settings.json` 里删那一行。这个坑下面第十条会讲。

六、六件事

这节是配置层，讲完你就有了一个能用的 Pi。

第 1 件：装扩展，一行就够，但源格式别写错

`pi install` 支持六种源，`pi install --help` 里写着：

```text

pi install npm:@foo/bar

pi install git:github.com/user/repo

pi install git:git@github.com:user/repo

pi install https://github.com/user/repo

pi install ssh://git@github.com:user/repo

pi install ./local/path

```

我第一次写的是 `pi install github:nicobailon/pi-web-access`，想着跟 npm 的简写差不多。结果直接报错：

```text

Error: Path does not exist: ...\github:nicobailon\pi-web-access

```

它把 `github:` 当成一个本地路径去找了。正确写法是 `git:github.com/user/repo`，注意 `git:` 后面直接跟域名，没有斜杠。

我还试了两种源的耗时：git 源那次 clone 走了三分钟还没完（GitHub 直连的速度），换成 npm 源十秒就结束了。

```powershell

pi install npm:pi-web-access

```

所以 只要作者发了 npm 包，一律优先 npm 源，快一个数量级。没发 npm 的才用 git 源。

装完看一眼：

```powershell

pi list

```

它会把包装到 `~/.pi/agent/npm/node_modules/` 下面，同时往 `settings.json` 的 `packages` 数组里加一条。下次启动自动加载，不用再管。

再装一个状态栏美化：

```powershell

pi install npm:pi-powerline-footer

```

装完重启 Pi，底部那行状态栏就变成带分段配色的样式了，模型名、上下文占用、当前目录分段显示。纯外观，但对天天盯着终端的人挺值。

装之前先想清楚要不要。 扩展多了，每轮对话要带上的工具描述就变长，token 跟着涨。我这次只留了两个。

第 2 件：接 MCP，扩展的另一条路

MCP 是另一套接法。扩展是装在 Pi 里的代码，MCP 是外面另起一个服务，Pi 通过协议去调。

一条命令接文件系统：

```powershell

pi mcp add fs -- npx -y @modelcontextprotocol/server-filesystem .

```

`fs` 是我给这个服务器起的名字，`--` 后面是启动它的命令，最后的 `.` 是它被允许访问的目录，写 `.` 就是当前目录。

```powershell

pi mcp list

```

`connected` 加 `14 tools`，说明连上了，工具清单也拉回来了。这 14 个工具包括读文件、写文件、编辑、建目录、列目录树、移动、搜索，够干大部分活。

注意那个 `.`。MCP 文件服务器只认你给的那个目录，给宽了它就能翻遍你整块盘。接自己项目就写到项目目录，别图省事写盘符根目录。

想接别的 MCP 服务也是同一条命令。文档站、数据库、浏览器自动化，社区里现成的一大堆，`pi mcp add 名字 -- 启动命令` 复制过去改改就行。

第 3 件：让它真干一件活（这段是重点）

前面都是准备。真正验证一个编码 agent 值不值，就看它能不能自己走完「读 → 改 → 跑 → 验」这一圈。

我准备了一个小项目：一个 `expenses.csv`，12 行本月支出，两个字段有坑（一笔退款是负数、一行团建场地重复录了两次）；一个 `summarize.py`，读 CSV 算总额、算分类小计、找最大单笔。

先跑一遍，看它自己报什么数：

```powershell

python summarize.py

```

12 条、4196.50。这个数是错的，因为团建场地那 1200 被算了两遍。

然后我不告诉它错在哪，只给现象和验收标准：

```powershell

pi --provider siliconflow --model moonshotai/Kimi-K2.7-Code -p "这份月度报表的数字不对：团建场地那 1200 被算了两次。给 summarize.py 加去重逻辑，重复行只算一次，改完自己跑 python summarize.py 验证。最后用五行以内说清改了什么，不要贴代码。"

```

一分钟出头，它回了这么一段：

它自己读了 `summarize.py`、自己改了文件、自己跑了验证，然后把结论写出来。中间过程在 `-p` 模式下不打印，但结果骗不了人，因为我紧接着又亲手跑了一遍同一条命令：

```powershell

python summarize.py

```

11 条、2996.50，而且它顺手把输出改成了「总条数（去重后）」，比我原来的写法还清楚。

这就是 `-p` 模式的价值：一句话进去，一个改好的项目出来，中间不看屏幕。适合放进脚本、放进定时任务、放进 CI。

但它不是每次都对。 我在同一个项目上还试了一句话：

```text

帮我把这个月的支出按周分组统计一下。

```

它先问我「周从周几算起」，等我说周一，它自己造了个 `week` 列。可那份 CSV 里根本没有周字段，它把日期字符串截了前七位当成周了。数字全错，输出排版却很漂亮。

这是编码 agent 最需要警惕的地方：它做错事的时候不会停下来问你，会给你一个看起来很像样的结果。所以每一类活都得配一句验收话术，下一节每类都给了。

判断一段活该不该交给它，我自己的标准是三条：结果有没有客观对错（数字、测试过不过、返回码）、++改动能不能回滚++（git 有没有提交）、++我能不能花两分钟验一遍++。三条都满足，放手交；缺一条，就自己盯着屏幕。

反过来，写文案、定方案、判断「这个设计好不好」这类没有客观对错的活，它给的只能当草稿。

第 4 件：Skills，教它你的规矩

Skills 是一段给模型看的说明书，放在 `~/.pi/agent/skills/` 下面，一个目录一个技能，里面是 `SKILL.md`。

和扩展的区别在于：Skills 不执行代码，它只改模型的想法。比如你可以写一个「写周报」的 Skill，规定必须先列三件做成的事、再列两件卡住的事、不许写形容词。

写 Skills 的门槛比扩展低得多，不用会 TypeScript，会写 Markdown 就行。我认为这是普通人定制 Pi 最划算的入口。

一个最小的 Skill 长这样：

```text

---

name: weekly-report

description: 写周报时用这个，按固定三段结构

---

写周报时按这三段，不要加别的：

1. 做成的事：最多三条，每条一句，带数字。

2. 卡住的事：最多两条，写清卡在谁那里。

3. 下周第一件：只写一件。

禁止用"持续推进""赋能""深度参与"这类词。

没写的事不要编，我没说的就是没做。

```

放在 `~/.pi/agent/skills/weekly-report/SKILL.md`，重启就生效。

第 5 件：会话断了怎么接

跑长任务最有用的三条：

```powershell

pi --continue # 接着上次那句说

pi --resume # 弹列表挑一个历史会话

pi --fork <会话id> # 复制一份出来，在副本上试新想法

```

`--fork` 这个我一开始没在意，后来越用越顺手。改代码改到一半想试另一条路，又怕把现在这版弄坏，fork 一份出来在副本上折腾，原会话一个字不动。

第 6 件：`-p` 和交互模式怎么选

交互模式适合探索，你一句我一句，能随时打断。

`-p`（`--print`）适合确定的事：跑一个明确的活，拿结果走人，不进界面。批量处理的时候更好用，写个循环调它几十次都行。

```powershell

pi -p "把这个目录下所有 .md 文件的标题抽出来，写成 index.md"

```

一句话，一个文件，不用开界面。

七、五类活，每类一段提示词

这一节是我实际在用的。五类活覆盖了我八成使用场景，提示词你直接抄，改掉文件名就能跑。

每段最后都有一句防幻觉的边界句，别删。 终端 agent 最烦的毛病就是没找到东西自己编一个，这句能压住大半。

第一类：看懂一个陌生项目

适用场景：接手别人的仓库、翻开源项目、看自己三个月前写的代码。

我的例子：刚从同事手上接过来一个四十多个文件的 Python 项目，两眼一抹黑。

```text

先不要改任何文件。读一遍这个项目的目录结构和主要文件，

用这段话回答我：

1. 这个项目是干什么的，一句话。

2. 分成哪几层，每层负责什么，各举一个文件。

3. 我要加一个新功能，应该从哪个文件开始看。

不确定的写"没找到"，不要猜。

```

验收话术：它给的入口文件，你自己打开看一眼对不对。对不上就回一句「你说的入口是 A，但我看逻辑在 B，重新看」。

++这一类最容易翻车的地方++：它会给你一个听起来很合理的分层，但分层是它编的。真伪判据只有一个，它点名的每个文件都得真实存在。

第二类：修一个已知的毛病

适用场景：报错、数字不对、行为跟预期不符。

我的例子：就是上面那个报表，合计多算了 1200。

```text

<把现象说清楚，不要自己诊断>

这份月度报表的数字不对：团建场地那 1200 被算了两次。

<给验收标准>

给 summarize.py 加去重逻辑，重复行只算一次，

改完自己跑 python summarize.py 验证。

<限制输出形态>

最后用五行以内说清改了什么，不要贴代码。

不许改 expenses.csv，不许改测试文件。

```

验收话术：自己再跑一遍那条验证命令。数字对不上就回「你跑出来的和我跑出来的不一样，把命令原样输出一遍」，让它重跑。

++这一类最容易翻车的地方++：它为了让你看到绿色，会顺手改测试文件。所以那句「不许改测试文件」不能省，跑完还要 `git diff` 看一眼动了哪几个。

第三类：批量整理文件

适用场景：一堆下载文件要改名、一堆截图要归档、一堆 Markdown 要统一格式。

我的例子：`Downloads` 里堆了六十多个文件，名字全是乱码。

```text

先只列计划，不要动文件。

把当前目录下的文件按扩展名分组，每组给我一个改名规则，

规则要能说清"原名 → 新名"的对应关系。

等我确认"开始"两个字，再执行。

执行时把每一条改动都打印出来。

拿不准的文件单独列一栏，不要动它。

```

验收话术：先看计划别放行。跑完之后随机抽三个文件看名字对不对。

++这一类最容易翻车的地方++：批量操作错了不可逆。所以提示词必须切成「先列计划 / 等确认 / 再执行」三段，一口气让它干完的，出事只能靠备份。

第四类：从零造一个小工具

适用场景：想要个顺手的小东西，不值得找人做。

我的例子：需要一个把 CSV 里某一列单独抽出来、去重、排序的小脚本。

```text

写一个 Python 脚本 pick.py，读同目录的 data.csv：

1. 命令行参数 --col 指定要抽哪一列。

2. 去重、去掉首尾空格、按长度排序。

3. 输出到 picked.txt，一行一个。

4. 只用标准库，不要装任何第三方包。

写完自己造三行假数据跑一遍，把输出贴给我看。

```

验收话术：拿你自己的真数据跑。它造的假数据总是太干净，真数据一跑就露馅。

++这一类最容易翻车的地方++：依赖。你说了只用标准库，它还是可能 `import pandas`。跑之前先看一眼文件头的 import。

第五类：查资料并落到文件

适用场景：要写点东西，得先查清事实。

我的例子：写这篇文章前要确认 Pi 现在的版本号和扩展生态的规模。

```text

<先说清要什么形态的答案>

用联网搜索查三件事：pi 的最新版本号、它现在的 GitHub 星数、

生态里星数最高的三个扩展。

<限制输出>

做成一张表存到 research.md，每行带一条来源链接。

查不到的在那一格写"未查到"，不要用你记得的数字替代。

```

验收话术：点开它给的链接看一眼。链接打不开或者内容对不上，就回「你给的某个链接和结论对不上，重新查这一条」。

++这一类最容易翻车的地方++：编来源。链接格式看着特别真，点开是 404。所以「查不到写未查到」这句必须留。

这五类练熟了，日常八成的工作都能塞进去。

八、进阶：让扩展替你联网，再自己写一个

Pi 本身不带联网。要查实时的东西，得装 `pi-web-access`。这个扩展 1738 星，昨天还在推 0.46 版本。

它最大的好处是零配置：装完就能搜，背后走的是 Exa 的公共服务，不填任何 key。想换成 Brave、Tavily、博查这些，就往 `~/.pi/agent/web-search.json` 里填对应 key。

装上之后我试了一句：

```powershell

pi --provider siliconflow --model moonshotai/Kimi-K2.7-Code -p "用你的联网搜索工具查一下 pi coding agent 最新版本号，只回答版本号和一个来源链接"

```

回的是 1.4.0，附了个 npm 包页链接。这个数跟我查到的对得上，说明它真去查了。

除了搜网页，这个扩展还能读具体页面、抓 PDF 文字、把 GitHub 仓库直接克隆到本地让 Pi 翻真代码。后面这个能力在「照着开源项目改东西」时特别省事。

嫌现成的不够用，自己写一个。 扩展最小的形态就是一个文件，导出一个函数：

```typescript

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {

pi.registerCommand("today", {

description: "把今天的日期塞进对话",

handler: async () => `今天是 ${new Date().toISOString().slice(0, 10)}`,

});

}

```

丢进 `~/.pi/agent/extensions/` 下面，重启就能用。会写 JavaScript 的话，加一个自己的小工具不超过半小时。这个门槛比大多数人想得低。

九、扩展、MCP、Skills 到底差在哪

这三个名字天天一起出现，新手几乎必混。一句话各说一遍：

扩展是装在 Pi 里的代码，能加新工具、能改它的行为，能力最大，写起来最麻烦，要会 TypeScript。

MCP 是外面另起的服务，Pi 通过协议去调。好处是同一套服务不光 Pi 能用，Claude Code、Cursor 也能用，换个工具不用重买。坏处是多一层进程，慢一点，配置也多一步。

Skills 是一段说明书，不写代码，只告诉模型「这类活该按什么顺序干、有什么禁忌」。

选择建议：要加能力先看有没有现成扩展，没有再看 MCP，两样都没有才考虑自己写。只想让它按你的规矩干活，写 Skill，别写扩展。

摆成一张表更清楚：

| | 扩展 | MCP | Skills |

|---|---|---|---|

| 是什么 | 装在 Pi 里的代码 | 外面另起的服务 | 一段说明书 |

| 会不会执行代码 | 会 | 会，在它自己的进程里 | 不会 |

| 写起来要会什么 | TypeScript | 看服务本身 | Markdown |

| 跨工具通用 | 只对 Pi | Claude Code、Cursor 都能用 | 只对 Pi |

| 什么时候用 | 加工具、改行为 | 已有现成服务想复用 | 定规矩、定流程 |

十、我踩过的 10 个坑

1. 用 `pi install github:user/repo` 装扩展 → 改成 `git:github.com/user/repo` 或 `npm:包名`

2. 拿 `curl ... | sh` 在 Windows 上装 → 走 PowerShell 安装器或 npm

3. Node 版本低于 22.19 硬装 → 先升 Node，别指望它能跑

4. 在 `/login` 里找 SiliconFlow → 写 `~/.pi/agent/models.json`

5. `api` 那行填 `openai` → 填 `openai-completions`

6. key 直接写进 models.json 然后传群里 → 用 `$环境变量名` 的形式

7. `pi remove` 在 Windows 报 `[safe-delete] spawnSync genie-trash ETIMEDOUT` → 系统回收站超时，记录没删掉；去 `settings.json` 手动删那一行，再删 `~/.pi/agent/npm/node_modules` 下对应目录

8. `pi mcp add` 的目录参数写成盘符根目录 → 只给它该看的那个项目目录

9. 拿它直接跑未提交的重要仓库 → 先 `git commit`，出问题能回滚

10. 装一堆扩展图安心 → 只留真在用的，工具描述占 token

第 7 条是我今天刚踩的。装扩展时先用了 git 源，后来想换 npm 源，`pi remove` 没删干净，`pi list` 里出现两条一样的记录。手动清完才干净。

第 3 条也值得展开一句。Node 版本不够的时候，Pi 不会给你一句「请升级 Node」，它会报一个看起来像权限问题的错。遇到莫名其妙的错，先 `node --version` 看一眼。

第 9 条同理。它默认没有沙箱，删东西不弹确认。想稳妥就先只给读权限，看清楚它想做什么再放开。

第 10 条补个具体数：每装一个扩展，每轮请求都要多带上它的工具描述。1.4.0 做了延迟加载和工具搜索，把这个开销压下去不少，但不是零。装到十个以上，你自己就会发现它开始选错工具。

十一、收尾

如果你一路看到这里，七千字，中间还有十张终端截图，耐心是真的好。

Pi 这类工具的难点从来不在「装」，在装完之后那一堆看不懂的开关。今天这篇把模型、扩展、MCP、Skills、会话五层都拆开讲了，每一层给了一条能照抄的命令，外加五类活的提示词。剩下的就是你自己上手试。

还有三样我这次没深用，你进阶时可以去翻：一是 Pi Durable，专门给长时间跑的 agent 做断点续跑和多人协作；二是 Codemode，让模型写一小段 JavaScript 在沙箱里批量调工具，官方说能把提示词压下去四成；三是容器化，官方文档有 docker 那一节，适合把没把握的活关起来跑。这三样都不该在新手期碰，先把手上的活跑顺。

建议你现在就做一件事：把 `models.json` 写好，接上一个能用的模型，然后拿一个自己手上的小文件，让它读完给你说三句话。

做成了，剩下的都好办。

如果这篇帮你省了时间，点个赞、点个在看，转发给那个也在折腾终端 agent 的朋友。想第一时间看到下一篇，记得关注并设成星标。

有问题回来看，我都写在里面了。