Pi 是一个极简的 agent harness，原生只有四个工具，其余能力全靠插件拼装。这篇文章记录我把它从零装起来、配好模型、挑插件。刚开始token消耗量极低，等插件配置完毕，token量飙升，一个你好，直接增加1万6上下文。
前言：Pi 的优势是什么
先把结论放前面。Pi 和 Claude Code、Codex 这类工具最大的差别，不在功能多少，而在取舍方向。
核心足够小。 官方对自己的定位是 minimal agent harness，装完之后内置工具只有四个：read 读文件（文本和图片都行）、bash 执行 shell 命令、edit 做精确的多段编辑（一次调用完成多处不连续替换）、write 创建或覆盖文件。sub-agent、plan mode、权限弹窗、内置 todo、后台 bash 这些，官网专门列了一节叫「What we didn't build」，理由是它们都能用扩展实现，不该写死在核心里。
扩展是一等公民。 扩展就是 TypeScript 模块，可以拿到工具、命令、快捷键、事件，甚至整个 TUI。官方在 examples 目录里放了五十多个扩展示例，从权限门到 sandbox 到 SSH 执行都有。你也可以直接让 Pi 自己写一个扩展，写完 /reload 接着用。
上下文可控。 这是我最看重的一点。系统提示足够小，AGENTS.md 和 SYSTEM.md 可以按项目定制，上下文压缩策略也能通过扩展替换。装什么不装什么，直接决定每一轮要烧多少 token，后面有实测数据。官网把这件事叫 context engineering。
模型自由。 官网列了 15 家以上 provider，Anthropic、OpenAI、Google、Azure、Bedrock、Mistral、Groq、Cerebras、xAI、Hugging Face、Kimi、MiniMax、NVIDIA、OpenRouter、Ollama 都在里面，认证支持 API key 和 OAuth，也能用 models.json 加自定义厂商。会话中按 /model 或 Ctrl+L 直接换模型，Ctrl+P 收藏轮换。本文用的是小米 MiMo。
还有两个用起来很舒服的细节。会话按树状存储，/tree 能跳回任意历史节点继续分支，整棵树只存一个文件；/export 导出 HTML，/share 传到 GitHub gist 直接给链接。
安装
官网在 pi.dev/，首页直接给了各包管理器的安装命令。Windows 下我用 PowerShell 装：
powershell
powershell -c "irm https://pi.dev/install.ps1 | iex"配模型
装完启动，第一步是登录。输入 /login。
接着选认证方式。Pi 支持账号登录，也支持直接填 API key，我用的API，这里选第二条。
然后输入厂商名，我填的是 Xiaomi，按回车进入密钥输入。
密钥填完，Pi 会把该厂商下可用的模型列出来。这里能看到 mimo-v2.6-flash、mimo-v2.6-pro 等几档，回车选中，按 Ctrl+S 可以设成默认。
最后发一条消息验证：
到这里基础环境就通了。不过这个时候的 Pi 还只有四个内置工具，真正的能力要装插件才有。
插件安装
Pi 的包生态叫 Pi packages，官网目录页收录的插件里绝大多数类型是 extension。安装命令统一是 pi install npm:<包名>，也可以 pi install git:<仓库> 从源码装。
我按自己的使用场景挑了两组。
通用能力三件套
pi-subagents 把工作委派给专注的子代理。
bash
pi install npm:pi-subagents包自带几个开箱可用的角色：scout 做本地代码侦察，researcher 做带来源的联网调研，evidence-auditor 独立核对调研结论是否被来源支持，worker 负责实现改动，reviewer 做代码审查，oracle 在你动手前给第二意见。装完不用写配置，直接说「用 reviewer 审一下这个 diff」就行，Pi 自己决定调不调、调哪个。前台的子代理直接在会话里流式输出，后台的会挂在一个独立进程里继续跑，之后可以回来查。
pi-hermes-memory 负责跨会话记忆。
bash
pi install npm:pi-hermes-memory它把知识分成三层：MEMORY.md 存环境和项目约定，USER.md 存用户偏好和沟通风格，SKILL.md 存「这件事怎么做」的流程。历史会话用 SQLite FTS5 建索引，可以直接问「我们之前讨论过 auth 的什么」。记忆分 failure、correction、insight、preference、convention、tool-quirk 几类，用户纠正过一次「用 pnpm 不用 npm」这类事会被单独记下来。所有写入都会过一遍密钥扫描，避免把 API key 存进去。
pi-web-access 提供联网能力。
bash
pi install npm:pi-web-access三个工具：web_search 支持 40 多家搜索源，零配置就能用（默认走 Exa MCP），不填任何 key 也行；fetch_content 抓内容，网页转 Markdown、GitHub 仓库直接克隆到本地、PR 和 Issue 渲染成结构化文档、YouTube 视频能出画面描述加转录加章节、PDF 也能转 Markdown；source_check 针对某个结论收集证据并给原文引用，返回 supported、contradicted、unclear 三种状态。它同时还能当本地 MCP server，给 Claude Code、Cursor 这些客户端复用。
编程质量与安全
pi-lens 负责写代码时的实时反馈。
bash
pi install npm:pi-lens挂上 LSP 之后，改动一落盘就补诊断，还会做联动检查：改了这个文件，把依赖它的相关文件也一起扫一遍。语言级的 linter、类型检查、格式化、ast-grep 结构规则都在里面，另外提供 symbol_search 这类给 agent 用的导航工具。它带的 read-guard 会拦住「没读就先改」的编辑，git-guard 会压住「还有未解决诊断就 commit 或 push」。
pi-simplify 审查刚改动的代码。
bash
pi install npm:pi-simplify/simplify 会用 git diff 找出改动范围，只审改动过的行。四条原则：不改功能、遵循项目里的 CLAUDE.md 和 AGENTS.md 约定、去冗余提清晰度、不要过度简化。逐文件改，每改完跑一次测试确认没弄坏，最后给一份汇总。
cc-safety-net 在执行前拦截危险操作。
bash
pi install npm:cc-safety-net它在工具调用真正跑起来之前解析命令语义，git reset --hard、git push --force、指向危险目标的 rm -rf 会被挡下，藏在 bash -c 或 python -c 里的也一样。同时对密钥文件做保护，SSH key、.env、~/.aws，以及各家 coding CLI 自己的凭据，从 shell 和 agent 的文件工具两条路都拦。规则可以用 npx cc-safety-net gui 在图形界面里调，官方还给了 Terraform、AWS、gcloud、Azure 的规则包。需要说明的是它不是沙箱，不隔离进程、不设文件权限、不看网络出口。
@juicesharp/rpiv-todo 给你一份能看见的任务清单。
bash
pi install npm:@juicesharp/rpiv-todo装完 Pi 就有了 todo 工具和 /todos 命令，编辑器上方会出现一个面板，显示哪些做完、哪个在做、哪些排队。任务状态是从对话本身重建的，所以 /reload 和上下文压缩之后依然在。任务依赖会在写入前校验，悬空 id、自依赖、循环都会被拒。
@narumitw/pi-plan-mode 提供只读的 /plan 模式。
bash
pi install npm:@narumitw/pi-plan-mode理念是「改代码之前先把计划定下来」。进入 plan 模式后，修改类工具被禁掉，shell 命令走的是一份失败即关闭的白名单，只放常见检查类命令，MCP 工具和自定义工具默认拒绝。规划过程中它可以用结构化问题澄清歧义，计划最多五万字符。计划定了之后，可以选择在当前会话直接实施、开新会话只带计划过去、保存或者导出成 Markdown。
主题
界面也能换皮肤，最喜欢pi-style这个。
bash
pi install npm:@quandev104/pi-stylepi-style 是一套统一视觉样式包，覆盖状态栏、编辑器、启动界面、消息渲染几个区域。状态栏是响应式分段布局，能显示模型、思考状态、路径、Git、上下文用量、费用、时间和扩展状态；编辑器有 compact、boxed、dock 几种样式。它自带 titanium 主题，装完在 TUI 里会自动应用。
bash
pi install npm:better-claude-code-uibetter-claude-code-ui 是把 Claude Code 的视觉识别整套搬进 Pi，包括六套 CC 主题（真彩的暗色和亮色、给不支持真彩终端的 ANSI-16 版本、以及色盲友好版本）、欢迎横幅、状态栏、spinner、每轮的耗时费用页脚，还有 CC 风格的工具渲染。装它之后建议在 ~/.pi/agent/settings.json 里加上 "quietStartup": true，把 Pi 自带的启动头关掉，免得两块横幅叠在一起。
装完之后
插件装齐，让 Pi 把能力清单列了一遍，翻成中文大概是这些：
核心工具
read读文件，文本和图片都行bash执行 shell 命令edit精确的多段编辑，一次调用完成多处不连续替换write创建或覆盖文件
导航与分析
project_report快速理解一个项目，找枢纽文件和入口module_report读之前先看模块轮廓read_symbol和read_enclosing只读某个函数或类的主体symbol_search按标识符定位文件lens_diagnostics对改动过的文件跑 LSP 诊断ast_grep_search和ast_grep_replace做语义级搜索与替换，可能要先用pi_lens_activate_tools激活
联网
web_search多查询并行搜索source_check为某个结论收集来源与原文引用fetch_content抓取网页、视频、仓库内容
记忆与技能
memory_add、memory_replace、memory_remove、memory_search组成跨会话持久记忆session_search搜索历史对话skill_manage创建和更新可复用流程
工作管理
todo任务清单，增删改查都有subagent把活派给子代理，或跑并行流程bg_wait等后台任务
Pi 专属
plan_mode_question和plan_mode_complete只有显式开了/plan模式才出现pi_lens_activate_tools按需启用工具effective_config解释 LSP 和工具的解析结果
从四个工具涨到几十个，代价马上就来。
这里做一个无聊的测试，仅供参考
每个插件大概要吃掉多少上下文？
工具定义是要进上下文的。装得越多，第一轮还没开始干活，token 就已经花出去了。
测法很简单：同一个目录，每次新建会话，发同样的一句「你好」，看状态栏右下角 X/1.0M 的数字。截图都是卸载插件之后重新截的。
插件全装，首轮上下文 15.8K：
然后一个一个卸，每卸一批就重开一个会话再发一次「你好」。每一步都截了图，数字汇总如下。
| 阶段 | 动作 | 剩余扩展 | 首轮上下文 |
|---|---|---|---|
| 1 | 插件全装 | 7 个 | 15.8K |
| 2 | 卸载 cc-safety-net | 6 个 | 15.6K |
| 3 | 卸载 pi-subagents | 5 个 | 14.0K |
| 4 | 卸载 pi-hermes-memory | 4 个 | 9.0K |
| 5 | 卸载 pi-web-access | 3 个 | 6.9K |
| 6 | 卸载 pi-lens 和 pi-simplify | 只剩 pi-style | 2.8K |
| 7 | 卸载主题 pi-style | 无 | 2.0K |
每一步的截图和对应的状态栏数字：
卸载 cc-safety-net 之后，首轮上下文降到 15.6K：
卸载 pi-subagents 之后，首轮上下文 14.0K：
卸载 pi-hermes-memory 之后，首轮上下文 9.0K：
卸载 pi-web-access 之后，首轮上下文 6.9K：
卸载 pi-lens 和 pi-simplify 之后，只剩 pi-style 一个扩展，首轮上下文 2.8K：
卸载主题 pi-style 之后，回到裸机，首轮上下文 2.0K：
把上面的差值翻过来，就是每个插件的上下文成本。
| 插件 | 增量上下文 |
|---|---|
| pi-hermes-memory | 约 5.0K |
| pi-lens 加 pi-simplify | 约 4.1K |
| pi-web-access | 约 2.1K |
| pi-subagents | 约 1.6K |
| @quandev104/pi-style 主题 | 约 0.8K |
| cc-safety-net | 约 0.2K |
| Pi 大概基线 | 2.0K |
几个结论。
大头是记忆和 lens。 pi-hermes-memory 一个插件占 5K（实际情况有波动），因为它要带一整套记忆工具的 schema 和策略说明；pi-lens 加上 pi-simplify 合计 4.1K，lens 那边工具最多，symbol_search、lens_diagnostics、ast-grep 那一串都算钱。
Pi 的大概基线只有1-2K多。四个内置工具的系统提示压到 2.0K，这是它能做到上下文可控的前提。同一个 harness 装与不装，差将近八倍。
其中 cc-safety-net 只花 0.2K，挡的却是 rm -rf 这种危险操作，性价比最高。反过来，memory 这类插件是不是必须，取决于你要不要跨会话记忆。如果每个会话都是独立任务，卸掉它省下的 5K 很实在。
怎么选：按需装，别一次装满
按我的取舍顺序排一遍。
- 一定要装：
cc-safety-net。成本较低，收益是「不会手滑删库」。 - 干开发活：
pi-lens加pi-simplify。4.1K 不便宜，但换来的是落盘即诊断和只审改动行的精简建议。如果只是偶尔改改脚本，可以先不装。 - 需要查资料：
pi-web-access。2.1K 换一整套联网能力，而且零配置。 - 长线项目：
pi-hermes-memory。单价最贵，但跨会话记忆和失败记录对长期维护的项目确实有用，项目一多、会话一长，这 5K 就摊薄了。 - 复杂重构：
pi-plan-mode。改之前先看计划，比改错了再回滚便宜。 - 多步骤任务：
pi-subagents加rpiv-todo。前者并行干活，后者让你看得见进度。 - 主题：纯看心情。
以上数据都是「首轮上下文」，也就是还没开始干活时已经付掉的固定成本。技能、历史记忆、项目里的 AGENTS.md 都会在此基础上继续往上加。
所以先装最小集，用一段时间，发现哪一步卡住了再补对应的插件。Pi 的安装和卸载都是一行命令，没必要一次装满。
验证环境
- Pi：
@earendil-works/pi-coding-agent，Windows 11、PowerShell 安装 - 模型：小米 MiMo（mimo-v2.6-flash）
- 文中截图来自本机实测，token 数字取自状态栏的首轮上下文计数