ARTICLE · 1122093
AI 编程工具越做越复杂,Pi 1.0 为什么偏要做小?
AI 编程工具越做越复杂，Pi 1.0 为什么偏要做小？
从安装到第一次完成任务，再看懂 Codemode、MCP 和 Virtual Model
2026 年 10 月 1 日，Earendil 发布了 Pi 1.0。官方把它称为一个 minimal、extensible agent harness。这个说法容易让新手卡住，因为 harness 翻成“智能体框架”以后，听起来仍然像一件离日常开发很远的东西。
换成具体动作就好懂了。你在一个项目目录里启动 Pi，把任务交给它。Pi 会读文件、搜索代码、运行命令、修改内容，再根据测试结果继续处理。它有终端交互界面，也能以 print、JSON、RPC 或 SDK 方式嵌进脚本和应用。
我把 Pi 1.0 的发布说明、当前文档和更新记录对了一遍。它最鲜明的特点仍然是核心很小。默认能力围绕读、写、编辑和执行命令展开。团队没有把 sub-agent、plan mode、待办事项、权限弹窗和后台 Bash 全塞进核心。需要这些能力的人，可以装现成的 Pi Package，也可以写 Extension。
这种设计有一个很现实的好处。初次使用时，你面对的是一套很短的基本动作。工作方式稳定以后，再加自己的规则、模板和工具。代价也很明确。Pi 不会替你预设完整工作流，安全隔离也要由使用者自己处理。
下面从零开始。
安装 Pi 1.0
macOS 和 Linux 可以直接运行官方安装脚本。
curl -fsSL https://pi.dev/install.sh | sh
Windows PowerShell 使用下面这条命令。
powershell -c"irm https://pi.dev/install.ps1 | iex"
已经装好 Node.js 的人也可以走 npm。当前版本要求 Node.js 22.19 或更新版本。
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
装完先确认版本。
pi --version
老用户升级可以运行。
pi update
pi update --self、pi update self 和 pi update pi 都是同一个操作的别名。要连同已经安装的 Package 一起更新，可以用 pi update --all。
这里有一个容易踩的坑。网上不少旧教程仍然使用 @mariozechner/pi-coding-agent，当前官方包名已经迁到 @earendil-works/pi-coding-agent。新装时直接使用新包名。
登录模型并启动第一个会话
Pi 本身不附带模型额度。你需要连接一个受支持的订阅、API key、本地模型或兼容接口。
先进入准备处理的项目目录，再启动 Pi。
cd /path/to/your-project
pi
工作目录很重要。Pi 会从这里找项目文件、配置和指令，也会按目录归类保存会话。
进入界面后运行 /login，选择提供商并按提示登录。当前 Pi 支持 Anthropic、OpenAI、Google、Azure、Bedrock、Mistral、Groq、Cerebras、xAI、OpenRouter、Ollama 等多种连接。1.0 还把 Radius 登录放进了 /login 的顶层入口，近期版本也加入了通过 OpenAI 提供商使用 ChatGPT 订阅的登录方式。
登录以后运行 /model 选择模型。Ctrl+L 可以打开同一个选择器，Ctrl+P 在收藏模型之间切换。模型支持推理强度时，可以用 /thinking 调整，或者按 Shift+Tab 循环切换。
第一次使用不用急着装任何扩展。先让默认 Pi 跑完一个小任务，理解它怎样读文件、改文件和执行测试。
用一个小项目走完整条流程
下面准备一个空的 Node.js 项目。
mkdir pi-hello
cd pi-hello
git init
npm init -y
printf'console.log("Hello")\n' > app.js
git add .
git commit -m "init"
pi
进入 Pi 后，把下面这段话交给它。
请先阅读 package.json 和 app.js。
把 app.js 改成一个支持 --name 参数的命令行程序。
没有传参数时输出 Hello，传入 --name Ada 时输出 Hello, Ada。
使用 Node.js 内置的 node:test 补测试，不要安装第三方依赖。
运行测试。测试失败就继续修，最后告诉我改了哪些文件。
这段任务有几个刻意写进去的限制。它先指定要读的文件，再说明输入和可见结果，还规定测试框架和依赖边界。Pi 因此少猜几次。你也能从终端记录里看到它读了什么、执行了什么、测试是否通过。
图 1 读文件、改代码和跑测试都发生在工具执行阶段。测试失败后，结果会回到模型，它可以继续修改并再跑一次。你最终验收的是文件和测试结果，不能只看最后那句“完成了”。
任务进行到一半，如果你想到新的限制，直接输入消息并按 Enter，把它作为当前工作的调整发出去。希望 Pi 完成手头工作后再处理另一件事，可以按 Alt+Enter 加入 follow-up 队列。想立即停止，按 Escape。
完成后可以在 Pi 里运行一条 Shell 命令。
!git diff
单个 ! 会把命令输出放进对话，让模型也能看到。双写成 !! 时，命令仍然执行，输出不会交给模型。
审完改动以后提交代码。Pi 不是版本控制工具，Git 仍然是最便宜的撤销办法。
把文件准确交给 Pi
在输入框里键入 @，Pi 会搜索当前目录中的文件。比如可以这样问。
比较 @src/old-parser.ts 和 @src/new-parser.ts，找出行为差异，并为缺少的边界条件补测试。
路径比较长时按 Tab 补全。终端支持图片粘贴时，也可以直接粘贴或拖入图片。
长提示词可以按 Ctrl+G 交给外部编辑器编写。查看工具完整输出用 Ctrl+O，显示或隐藏 thinking block 用 Ctrl+T。这些快捷键可以通过 /hotkeys 查看当前配置。
会话不会因为退出而消失
Pi 会自动保存会话。退出以后，在同一个项目目录运行下面的命令，可以继续最近一次会话。
pi --continue
交互界面里的 /resume 用来选择其他会话，/name 给当前会话命名，/session 查看会话文件、消息数、token 用量和费用。
Pi 的历史记录是一棵树。/tree 可以回到之前的节点，从那里换一条路继续，仍然使用原来的会话文件。/fork 会从选中的较早用户消息创建新会话，/clone 则把当前活跃分支复制为新会话。
图 2 切换对话历史不会自动还原工作目录里的代码。如果你想试另一种实现，先提交或妥善保存当前改动，再分出会话。回到旧消息以后，也要确认磁盘上的文件是不是你以为的版本。
上下文快满时，Pi 会自动压缩较早的内容。你也可以主动运行 /compact。压缩适合已经很长的会话，不能替代清楚的任务边界。一个功能完成并提交以后，换新会话往往更省心。
不打开交互界面也能用
终端界面适合人盯着处理复杂任务。简单、重复的工作可以直接使用 print mode。
pi --print"阅读这个仓库的 package.json，告诉我开发服务器和测试分别怎样启动"
管道里的内容也能交给 Pi。下面这条命令会把当前差异送去审查。
git diff | pi --print"检查这次改动中的正确性、兼容性和遗漏的测试"
程序需要消费过程事件时，可以选择 JSON mode。
pi --mode json "检查这个仓库" > events.jsonl
RPC mode 通过标准输入输出控制独立的 Pi 进程，TypeScript SDK 则把 Agent 直接嵌进应用。新手先从 print mode 开始。等任务需要持续交互、结构化事件或自定义界面时，再考虑 RPC 和 SDK。
先写 AGENTS.md，再研究复杂扩展
很多人第一次用 Agent 就开始找插件。对项目开发来说，最先值得写的通常是仓库根目录下的 AGENTS.md。
# Project rules
- 修改源码后运行 npm test
- 不新增第三方依赖，除非任务明确要求
- TypeScript 禁止使用 any
- 改动接口时同步更新 README
- 最终回答用中文，列出修改文件和验证结果
Pi 启动时会读取项目和上级目录中的指令文件。个人级配置默认放在 ~/.pi/agent/，项目级配置放在工作目录的 .pi/。项目里的配置只有在你授予 project trust 后才会加载。手动改完设置、指令或资源，可以运行 /reload。
全局规则和项目规则应当分开。回答语言、常用工具偏好适合放在个人配置中。测试命令、目录边界和代码规范属于项目，跟着仓库走更合理。
Prompt Template、Skill、Extension 怎么选
Pi 给出的选择顺序很实用。能用简单机制解决，就别先写复杂代码。
AGENTS.md | |
图 3 以 API 审查为例，一句“不要破坏兼容性”可以写进 AGENTS.md。一套审查步骤和参考资料适合做成 Skill。要增加一个真正调用接口的工具，就需要 Extension。它们可以在同一个项目里一起使用。
做一个代码审查模板
新建 ~/.pi/agent/prompts/review.md。
---
description: Review staged git changes
argument-hint: "[focus]"
---
Review the staged changes. Focus on ${1:-correctness, security, and error handling}.
运行 /reload 后，输入 /review concurrency，Pi 会把参数展开进模板。这个机制适合代码审查、生成提交说明、整理会议记录等重复任务。它只展开文字，不执行额外代码。
做一个自己的 Skill
Skill 适合需要更多背景资料的工作。目录里至少有一个 SKILL.md，也可以带脚本、参考资料和素材。
这个示例可以放进项目的 .pi/skills/api-review/。只想自己使用时，也可以放到 ~/.pi/agent/skills/api-review/。保存以后运行 /reload。
api-review/
├── SKILL.md
├── scripts/
│ └── check-openapi.sh
└── references/
└── review-rules.md
SKILL.md 可以这样写。
---
name: api-review
description: 审查 OpenAPI 变更。用户要求检查接口兼容性、字段变化或接口升级风险时使用。
---
# API review
先读取 references/review-rules.md。
运行 scripts/check-openapi.sh 比较当前版本和基线版本。
按破坏性变更、兼容变更和文档缺失整理结果。
Pi 平时只把 Skill 的名称和描述告诉模型。任务匹配时才加载完整指令。这种 progressive disclosure 能减少无关内容占用上下文，也不容易破坏 prompt cache。
写一个最小 Extension
Extension 是在 Pi 进程中运行的 TypeScript 模块。下面这个例子增加 /hello 命令。
importtype { ExtensionAPI } from"@earendil-works/pi-coding-agent";
exportdefaultfunction (pi: ExtensionAPI) {
pi.registerCommand("hello", {
description: "Show a greeting",
handler: async (name, ctx) => {
ctx.ui.notify(`Hello, ${name || "world"}!`, "info");
},
});
}
把文件保存到 ~/.pi/agent/extensions/hello.ts，重载后输入 /hello Levix。开发阶段也可以临时加载。
pi --extension ./hello.ts
Pi 用 jiti 加载本地 TypeScript Extension，小扩展不用单独编译。Extension 能读取提示词、工具调用、文件、凭据和会话历史，并拥有 Pi 进程的系统权限。来源不明的扩展别直接装。
安装和分享 Pi Package
Pi Package 可以把 Extension、Skill、Prompt Template 和 Theme 放在一起。
下面的 example 是占位名称，实际安装时需要换成你确认过来源的包或仓库。
pi install npm:@example/pi-tools@1.0.0
pi install git:github.com/example/pi-tools@v1
pi install ./local-package
用 pi list 查看已配置的 Package，pi remove <source> 删除，pi update --extensions 更新全部 Package。加 --local 或 -l 会把配置写进当前项目的 .pi/settings.json。
Pi 1.0 新增了什么
Pi 1.0 的七项主线能力分布在 1.0 发布前的连续版本中，最终作为稳定版本一起交付。只看 1.0.0 当天的变更列表，会漏掉 Codemode、Virtual Model 和缓存预热等核心内容。
Codemode 和原生 MCP
这是 1.0 最需要理解的一项变化。
普通 Agent 调用工具时，模型发起一次工具调用，拿回结果，再决定下一次调用。工具很多时，每个工具的定义会占上下文。结果很大时，大量原始数据也会进入模型窗口。
Codemode 给模型一个 QuickJS 沙箱。模型可以临时写一小段 JavaScript，在脚本中搜索工具、并行调用多个工具、筛选结果，只把最后输出交回主模型。沙箱本身没有 Node API、文件系统和网络访问，外部能力只能通过已注册的工具和 models 接口获得。
图 4 假如工具返回了一百条提交，脚本可以先排除锁文件和纯格式化改动，主模型只收到剩下的变化摘要。返回多少内容由脚本决定，Pi 不会自动保证每次调用都只返回短摘要。沙箱里的限制也不会改变外部工具自身的权限。
只用默认工具启动时，Codemode 没有自动启用。想先试一下，可以在全局 ~/.pi/agent/settings.json 或项目的 .pi/settings.json 中加入下面的设置。已有配置时合并这个字段，不要覆盖整份文件。
{
"defaultTools":["+codemode"]
}
+codemode 表示在默认工具上追加 Codemode，保留 read、bash、edit 和 write。运行 /reload 后再使用。配置了 MCP Server 时，Pi 会自动启用 Codemode。
新手不需要亲自写 Codemode 脚本。你描述目标，模型会在合适时生成脚本。一个典型任务可以这样写。
使用 codemode 获取项目最近一周的提交，并行读取每个提交的变更摘要。
过滤掉依赖锁文件和格式化提交，只输出功能变化、修复内容和仍然存在的风险。
1.0 对 Codemode 的提示开销又做了一轮压缩。官方给出的例子中，默认工具和 Codemode 同时启用时，一次 GPT-5.6 请求的相关 prompt token 从约 5300 降到约 3300，减少约四成。错误信息也会给出接近的工具名和恢复办法。
MCP 现在是内置能力，支持 stdio 和 streamable HTTP，也支持 OAuth。添加一个本地 filesystem MCP Server 可以运行。
pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
pi mcp list
pi
交互界面中的 /mcp 可以查看连接、登录、重连和启停 Server。全局配置位于 ~/.pi/agent/mcp.json，项目配置位于 .pi/mcp.json。
Pi 没有把所有 MCP 工具说明一次塞给模型。默认的 codemode exposure 会让脚本通过 searchTools()、describeTool() 和 describeNamespace() 找到需要的工具。大量 MCP 工具因此可以接进来，同时少占上下文。
延迟工具加载
延迟加载和 Codemode 解决的是同一个老问题。一个企业 MCP Server 可能暴露几十个甚至几百个工具。模型每次只用其中一两个，却要先为全部 schema 付 token，既贵又容易选错。
Pi 现在支持几种 exposure。direct 工具始终直接展示给模型，适合少量高频能力。deferred 工具先隐藏，tool_search 找到匹配项后，再把它加载到下一次模型调用。默认的 codemode 工具留给脚本调用，适合组合查询和先过滤再返回。
图 5 deferred 找到工具后，主模型仍然直接调用它。codemode 则把工具留在脚本里使用。工具已经注册，并不代表它的完整定义每次都会出现在主模型的上下文中。
这项变化对新手没有新的操作负担。它主要让工具很多的 Pi 仍然保持轻量。
Codemode 可以调用 Jev 和图像模型
Codemode 的 models 接口不只认识聊天模型。它可以运行 classifier 和 image model。
Jev 属于分类器。它不会像聊天模型那样写长回答，适合给大量结构化项目打标签、算概率或做选择。比如从两百条 issue 中找出情绪最强烈的反馈，可以先并发获取评论，再让 Jev 分别判断情绪等级，最后只把排序后的少量结果交回主模型。官方发布演示就用了类似流程。
1.0.0 又加入了 models.generateImages()。Codemode 脚本可以使用当前会话的凭据调用图像模型，并把 base64 图像块显示到结果中。分类和图像调用都会计入 /session 的用量与费用。
Extension 可以注册 Virtual Model
Virtual Model 是一个能在 /model 中被选中的路由入口。用户始终选中 router/auto，Extension 可以按任务、成本、推理强度或当前对话状态，把每一次请求交给不同的实体模型。
一种常见做法是让大模型负责规划，让更快、更便宜的模型负责实现。发布演示中，Claude Opus 负责规划，Jev 判断任务何时进入实现阶段，随后切给 GPT-6 Luna。工具调用后的追问和重试还能保持在处理当前回合的模型上，避免同一回合来回切换。
路由发生后，终端底部会同时显示虚拟选择和实际模型。/session 按实体模型拆分费用。会话恢复时，Pi 会恢复原来的 Virtual Model 选择。
图 6 router/auto 只是示例入口名。你需要安装或编写提供这一入口的 Extension，才会在模型选择器里看到它。图中的规划和实现分工是一种路由策略，具体条件由扩展决定。
这项能力面向会写 Extension 的进阶用户。刚开始用 Pi 时手动 /model 已经够用，不必为了“自动”先造一套路由系统。
Anthropic Prompt Cache 预热
长任务经常花几分钟跑测试、等外部工具或处理文件。模型提供商的 prompt cache 可能在这段时间过期。下一次请求就要重新写入大段上下文，延迟和费用都会上升。
Pi 1.0 纳入了成本感知的 cache warming。默认的 streaming 模式会在活跃任务的长工具调用期间判断是否值得刷新缓存。模型必须声明缓存有效期，Pi 还要估算这次刷新至少能避免 0.05 美元的 cache miss 成本，才会执行。刷新本身会计费，并计入当前会话。
全局 settings.json 可以调整。
{
"cacheWarming":"off"
}
可选值包括 off、streaming 和 idle。idle 还会在两次任务之间维持缓存。/session 能查看下一次预热判断和相关用量。对短会话来说，这项功能通常不会触发。
对话中途可以更新系统指令和工具
以前的很多 Agent 扩展在会话中改系统提示词或工具列表时，要么只对当前请求生效，要么破坏前面的缓存前缀。Pi 现在会把初始提示词和工具集记录进 transcript，后续变化以新的 system message 追加。
这样做带来两个结果。Extension 在任务进行到某个阶段后，可以增减指令和工具。会话恢复、树形跳转和分支仍然知道当时生效的配置。支持这种转变的模型还能保住前面的 prompt cache。
普通用户不会频繁直接操作这套 API。它给动态工作流、阶段化工具和长期会话提供了可靠基础，也是 Virtual Model 和复杂 Extension 更容易落地的原因之一。
新主题和全屏终端界面
Pi 最近加入 system Theme，它会根据终端前景色、背景色和 ANSI 调色板生成界面颜色，也能随终端的明暗模式变化。这是当前默认主题。
1.0.0 又把 fullscreen 设成默认 TUI 模式。编辑区和状态区会固定在窗口内，记录在内部滚动。偏爱终端原生 scrollback 的人，可以运行下面的命令。
pi --tui-mode regular
也可以在 /settings 中把 tuiMode 改成 regular。1.0 新增的 quietStartup: "header" 只保留版本和快捷键提示，隐藏模型范围和已加载资源列表，适合已经熟悉配置的人。
1.0 里的其他改进
MCP OAuth 在 1.0 得到进一步加固。凭据按 Server 名称和 URL 保存，同一个地址可以用不同账号登录，还增加了授权服务器元数据覆盖、issuer 检查和追加 scope 的重新登录流程。
Anthropic 登录增加了 copy code 方式，浏览器和 Pi 不在同一台机器时也能完成登录。Radius 登录可以顺手写好 MCP 配置。Codemode 的错误提示也更具体，脚本写错工具名、模型名或参数结构时，会告诉模型怎样恢复。
这些变化没有给首页增加一排按钮，大多减少了长会话和复杂工具环境里的摩擦。这很符合 Pi 的取舍。
Pi Durable 是另一件东西
Earendil 在发布 Pi 1.0 的同一天还推出了实验性的 Pi Durable。它面向长时间运行的 Agent 应用，让对话、任务和文档可以持续存在，也方便把 Pi 的能力放到终端以外的产品界面中。
npm install @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord
普通开发者把 Pi 当终端编程 Agent 使用时，不需要安装 Pi Durable。它目前更适合正在搭建 Agent 产品、需要长期任务和持久状态的开发者。官方也明确把它标为 experimental package。
Pi 仍然没有替你做什么
Pi 1.0 仍然没有内置 sub-agent、plan mode、权限弹窗、待办系统和后台 Bash。官方给出的路径很直接。计划可以写进文件，后台任务交给 tmux，需要的能力由 Extension 或 Package 提供。
对新手更重要的一条是，Pi 没有内置文件、进程、网络和凭据沙箱。它默认继承启动它的系统账号权限，也不会在每次工具调用前弹窗询问。Project trust 只决定要不要加载项目里的配置、指令和 Extension，不能约束后续命令能访问什么。
日常使用至少做好下面几件事。
1. 在 Git 仓库和独立分支中运行，开始前确认 git status。2. 不要从含有私人文件和凭据的宽泛目录启动 Pi。 3. 第三方 Package、Skill 和 Extension 先看源码。Skill 里的指令也可能要求模型执行脚本。 4. 处理陌生仓库、外部文件或无人值守任务时，把整个 Pi 放进容器、虚拟机或其他沙箱。 5. 分享 /export、/share或pi-debug.log前检查内容。会话里可能带有提示词、文件内容、工具输出和意外暴露的凭据。
装一个 permission gate Extension 可以减少误操作，却不能替代系统级隔离。Extension 自己也运行在 Pi 进程里。
一条适合新手的学习路线
第一天只做三件事。完成登录，用默认 Pi 改一个小功能，再用 Git 审查改动。记住 @文件、!命令、/model、/session 和 pi --continue。
第二步给常用项目写 AGENTS.md。把测试命令、依赖规则和目录限制写清楚。接着做一两个 Prompt Template，把每天重复输入的提示词收起来。
真的遇到一类任务需要很多说明和配套脚本，再做 Skill。需要新工具、生命周期事件或终端界面时才写 Extension。多个资源准备给团队复用，再包装成 Pi Package。
MCP 适合连接已有系统。Codemode 适合在工具多、返回量大的情况下编排调用。Virtual Model 适合已经能度量任务成本和质量的人。顺序别倒过来。自动路由做得再漂亮，也救不了含糊的项目规则和无法验证的任务。
Pi 1.0 的上手门槛并不在命令数量。最难的一步，是接受它没有替你规定完整工作方式。它先给出一个能读、能改、能运行的 Agent，再把改变 Agent 本身的接口交给你。对只想开箱即用的人，这会显得朴素。对愿意慢慢整理自己工作流的人，Pi 的小核心反而更耐用。