Pi 1.0 正式发布这六个字对长期蹲在终端里的开发者来说分量不轻。我过去一年在命令行里试了不少 AI 编程代理最头疼的永远是两件事工具链和它是两套话语体系会话一断上下文全部归零。这次 1.0 把原生 MCP 支持和 Pi Durable 会话持久化做成了内置能力等于同时解决了工具接入碎片化和任务状态不可恢复两个老毛病。这篇东西是我从 0.6 一路用到 1.0 的实际体验整理不光聊新功能还涉及配置迁移、权限边界和各种坑适合重度使用终端 AI 助手的人也适合第一次接触 MCP 的新手照着做。1. 为什么终端编程代理必须来一次重大升级1.1 0.x 时代那些绕不开的痛先说前面几个版本的体验。Pi 在 0.x 阶段并不是不能用写写脚本、改改正则、补个单元测试效果都不错。但问题恰恰出在好用和能用之间的落差上。首先它和外部工具的连接是碎片化的。那时候要接一个代码搜索服务得先写一个自定义插件再在配置文件里声明一堆路由规则换一个项目这些插件经常要重配。这个体验特别像你家里买了十个智能插座每个都得用独立 App 控制谁受得了。其次会话状态跟纸糊的一样。终端一关、网络一跳、电脑休眠超过某个时间之前跑了大半个小时的上下文分析就没了。重新启动 Pi 之后它一脸茫然地看着你你得把项目的架构、依赖、目标文件重新口述一遍。一个十万人规模代码库的项目光重新解释上下文就要花掉十几分钟这个成本在实际开发里是非常具体的。还有个隐蔽问题0.x 时代的上下文管理是单次任务视角。它记住的是当前对话里聊了什么而不是当前仓库里发生了什么。也就是说它既没有可靠机制去感知文件系统变化也没有能力把某个长任务的中间结果持久保存下来。这种设计放在玩具 demo 上没问题放到真实项目里就显得特别单薄。所以 1.0 把 MCP 和 Durable 一起端上来不是锦上添花而是填坑。1.2 MCP 到底是什么为什么原生比外挂香MCPModel Context Protocol模型上下文协议。这个概念前两年就已经在圈内传开了简单说就是给大模型和外部世界之间定了一个标准接线口。以前大模型要读文件、查数据库、调 Git 命令每个工具都要单独适配一套私有协议有了 MCP工具方只需要暴露统一的服务器接口模型侧只需要按标准去发现和使用这些工具。类比一下这就像是 USB-C 接口标准。之前每个手机厂商都有自己的充电线出门要带一把现在一个接口能通吃协议层把设备的差异性和使用者的操作方式隔离开了。Pi 1.0 这次是原生支持 MCP这个词值得划重点。原生意味着它不是通过一个中间适配层去迁就的而是从核心调度逻辑里就把 MCP 服务器当作一等公民。外挂式支持常见的毛病是工具调用要先经过一个翻译层性能有损耗权限模型也经常对不上原生支持则可以在进程内部直接管理工具的生命周期、超时、错误传递和权限校验。另一个实际好处是配置体验统一了。在 0.x 里接入不同工具是各写各的模板在 1.0 里全部收敛成MCP 服务器这一个概念写在同一个 registry 里统一启动、统一检查、统一日志。这里还要把 Pi Durable 的角色讲清楚。Durable 解决的是任务状态的标准化。MCP 管的是怎么连接工具Durable 管的是连接之后做了一半的事情怎么不丢。它会在关键节点给会话打检查点记录上下文快照、工具调用结果和文件状态支持事后恢复。所以说 1.0 的核心思路是两条腿走路一条腿是向外扩展能力边界另一条腿是向内保证状态可靠。很多同类工具只做了前者后者才是真正拉开差距的地方。2. 原生 MCP 接入实操从能连到好用2.1 五分钟接上第一个本地 MCP 服务器实操先来。1.0 里配一个 MCP 服务器路径非常短。以最常见的文件系统访问场景为例你需要做三件事在配置里注册服务器、重启 Pi 让 registry 生效、在会话里让 Pi 去直接读写文件。配置文件长这样{ mcp: { servers: { my-fs: { transport: stdio, command: pi-fs-server, args: [--root, /workspace/my-project], env: { PI_FS_MODE: read-write } } } } }这里 transport 用了 stdio意思是 Pi 和 MCP 服务器通过标准输入输出管道通信最简单、最快也最适合本地进程。如果服务器跑在远程机器上可以换成 http/sse 类型的 transport把 url 填到配置里就行。安装好之后跑pi mcp list能看到服务器状态为 connected就说明通了。我自己的习惯是接完先做一次冒烟测试让 Pi 读取某个已知内容的文件确认路径权限没有问题。这个步骤很多人会跳过但一旦配置里 root 路径写错了后面所有工具调用都会返回路径不存在排查起来更浪费时间。另外要注意stdio 类型的服务器生命周期是跟着 Pi 进程走的Pi 退出时服务器也会关闭这是预期行为不是 bug。2.2 工具接入的安全边界怎么设都不为过工具接入的范围越广越要管住权限。Pi 1.0 给每个 MCP 服务器提供了三层控制注册时的白名单、调用时的交互确认、运行时的资源限制。第一层是配置层面决定这个服务器能不能被加载第二层是会话层面决定某个具体工具调用要不要人工点头第三层是系统层面限制它占用的内存、CPU 和可访问目录。有个实际教训。我给某个测试项目接了一个数据库查询服务器当时为了省事把权限设成了 allow-all结果 Pi 在执行一个清空测试表的请求时真的直接把整张表 drop 了。虽然测试库可以重建但那个瞬间的冷汗到现在还记得。后来我养成了一个习惯所有 MCP 服务器默认跑在 read-only 模式需要写入的场景再单独开一个高权限实例并且开启高危险操作需要确认的开关。这个开关在pi config set mcp.confirm_destructive true这一行命令里就能打开强烈建议所有人在生产环境开启。还有一个很多人容易忽略的点密钥管理。MCP 服务器配置里不要明文写 Token、数据库密码。Pi 1.0 支持从系统密钥环读取变量配置里填env: {DB_PASSWORD: ${KEYRING:DB_PASSWORD}}这样的引用方式比把密码直接扔进配置文件里安全一个数量级。哪怕只是内部工具也建议遵守这个习惯因为你不知道哪天这个配置文件就被别人分享出去了。2.3 Resources 与 PromptsMCP 里容易被低估的两个能力很多人提到 MCP 只想到工具调用其实协议里还有另外两块Resources 和 Prompts而且这两块在编程代理场景里特别有用。Resources 是把某些上下文内容暴露给模型比如项目 README、接口文档、目录结构树。Pi 可以把这些资源自动注入到会话上下文中省去反复读文件的消耗。举个例子我让 Pi 在每次开始任务前自动加载AGENTS.md和docs/architecture.md它就能持续记住项目约定不需要我每次都强调编码规范。Prompts 则是预定义的操作模板可以理解成给 Pi 的话术脚本。审查代码、生成 commit message、写发布说明这些高频重复任务都可以固化成 prompt。平时干活时直接对 Pi 说按团队规范审查当前 diff它会从 Prompt 模板里找到一整套行动清单先读哪些文件、检查哪些点、按什么格式输出。这比每次临时口述要求稳定得多也让团队里新来的同事能享受到同等的执行标准。从实现层面看Resources 和 Prompts 同样来自 MCP 服务器所以它们和 Tools 共享同一套权限模型和安全边界。理解到这一层你就明白为什么我说原生 MCP不是多了一个功能而是把整个上下文管理方式重新设计了一遍。对长期使用者来说这个改动的价值远大于界面上的任何变化。3. Pi Durable 使用手册把终端会话变成可以续传的任务3.1 Durable 的工作机制检查点、快照与恢复Pi Durable 最核心的机制是给会话打检查点。每当任务执行到一个关键节点比如一轮工具调用完成、一个文件修改落地、或者上下文长度超过某个阈值时Pi 会把当前会话的完整状态写入本地存储。这个状态包含对话历史、上下文摘要、已调用工具的结果、当前工作目录、环境变量快照等。从存储格式上说1.0 默认使用.pi/durable/目录每个会话一个子目录内部是带索引的 JSON Lines 文件方便增量写入和快速恢复。恢复的入口很直接。终端里执行pi du status看当前有哪些可恢复的会话然后用pi du resume session-id回到指定会话。恢复之后我实测下来 Pi 能记住之前解析过的代码结构、正在进行的修改列表、甚至是对话里提到但还没落地的计划事项。这种感觉非常接近电脑合上盖子第二天打开还在原处而过去终端代理是完全做不到这一点的。从设计和实现角度想Durable 之所以叫 Durable 而不是简单的历史记录关键在于它保存的是可执行状态而不是一堆日志。普通 shell history 只是记录了你敲过什么命令重放不等于恢复Durable 保存的是已经加载到工作内存里的语义状态恢复后 Pi 可以直接基于之前的知识继续推理而不是从零开始重新读代码。这个差别我在大型重构任务里感受特别明显。3.2 哪些场景真正需要 Durable哪些不需要不是所有场景都需要持久化。如果你只是临时问一个正则表达式怎么写用完就关终端那 Durable 对你来说没有意义反而会在磁盘上留下没用的会话文件。真正值得用 Durable 的场景我总结下来有这么几类长时任务比如全仓库重构、依赖升级和冲突排查、大型测试结果分析这类任务的上下文很长很难一次会话内完成中间断掉代价极大。后台运行Pi 在无交互模式下跑任务时你可能会切去做别的事。这时候一旦连接断开没有 Durable 就等于白跑。跨机器工作把.pi/durable/目录放进同步盘你可以在办公室的机器上恢复家里机器创建的会话。这个用法适合经常切换工作环境的人。多人协作团队共享一个会话检查点比如明天评审会用这个 session其他成员可以恢复同一状态来对齐上下文。反过来简单的问答、临时代码片段生成甚至短时间内的调试都不需要特意创建 durable 会话。Pi 1.0 默认是普通会话模式只有你调用了pi du checkpoint或者开启了某个任务的持久化选项才会生成检查点。这个设计是对的毕竟检查点不是零成本的快照写入和上下文重建都需要时间。3.3 一次断电恢复的现场实录说一次我自己真实的经历。某天我让 Pi 在一个大体量项目里做跨模块的依赖梳理任务已经执行到一半上下文里加载了十多个关键文件的分析结论。正当我准备让它继续写迁移方案时笔记本断电了。重新开机以后老实说第一反应是想骂人因为按以前的经验这种状态下 Pi 基本就是一片空白。这次不一样。我打开终端输入pi du status屏幕上列出了两个可恢复会话其中一个的标记就是刚才那个任务。我执行pi du resume session-idPi 首先打印出恢复摘要包括之前分析过的文件列表、最近一次检查点的位置、以及任务计划中尚未完成的部分。然后我让它继续它直接接上了按之前的方案继续分析某某模块这个上下文没有重新问项目结构也不需要我重新贴代码。那次之后我正式把 Pi 1.0 放进日常工具箱。不过在恢复过程中也确实有一个注意点如果中途手动修改过仓库里的文件恢复的上下文可能与当前磁盘状态不一致。比如 Pi 记忆里某个文件还是旧版本但磁盘上已经被你改了。这种情况建议先让 Pi 重新读取相关文件用pi resync刷新索引再继续执行任务避免基于过期状态做决策。4. 从 0.x 升级到 1.0迁移实操与避坑清单4.1 配置文件有哪些变化怎么迁升级最怕的是老配置失效。Pi 1.0 在配置格式上做了一次收敛把原来散落在tools、plugins、hooks三个区块的能力统一整合进mcp和durable两个核心区。0.x 的旧配置文件1.0 提供了一个自动迁移工具执行pi migrate config它会扫描旧文件把插件式工具定义转换成 MCP 服务器配置把持久化相关设置归入 durable 区块。值得提醒的是自动迁移不代表万事大吉。工具定义从插件形式变成 MCP 服务器形式时参数名和默认值有些地方对不上。我迁移的时候遇到过几个小问题比如旧的timeout_seconds字段在新配置里变成了tool_timeout单位没变但字段名变了又比如旧版里某个插件自带的权限控制选项在新版里转移到了 MCP server 的capabilities区块下。所以迁完必须逐项核对尤其是权限类配置千万别只看进程能启动就以为没问题。如果迁移工具不敢直接改生产配置可以先复制一份旧配置做 dry-runpi migrate config --dry-run --out ./pi-config-new.json生成一个预览文件人工检查 diff 之后再真正应用。我的习惯是每次大版本升级都留一个旧配置的备份并且把新配置放到独立的 profile 里跑几天确认稳定后再切默认。4.2 升级之后先做这三件事完成迁移之后别急着压上真实任务。我建议按下面的顺序把环境验证一遍。第一步初始化新的配置仓库。Pi 1.0 引入了 profile 机制可以把不同项目的配置彻底隔离。我在~/.pi/profiles/project-a.json里为新项目建了独立 profile避免不同项目的 MCP 服务器互相干扰。这一步在 0.x 时代很难做因为全局配置只有一个大家只能在一个文件里堆条件判断。第二步验证 MCP 连接清单。执行pi mcp ping --all这个命令会逐个检测所有已注册服务器的可达性给出延迟和错误信息。实测中我发现有些旧插件转化为 MCP 服务器后因为启动命令发生了变化会报transport error。这种问题通常是在配置里把启动方式从entrypoint改成command args即可解决但必须逐个服务器过一遍。第三步创建一个测试用 Durable 会话。让 Pi 完成一个小的多步骤任务比如分析当前目录结构找出所有未使用的导入输出问题清单然后执行pi du checkpoint马上再pi du resume session-id看能不能完整恢复。这一步验证的是持久化链路是否正常工作早发现早处理别等真出大事才去测试。4.3 舍不得旧版本的用户怎么办每次大版本发布总有一批人想留在旧版本上观望。这完全可以理解我自己也在 0.9 上多待了两周。如果确实要暂时留在旧版建议用环境隔离而不是在同一台机器上直接替换。Pi 1.0 支持通过环境变量指定数据目录比如PI_HOME~/.pi10 pi --version这样新旧版本可以共享 shell 环境但各自使用独立的配置和数据目录。这比直接覆盖要稳妥得多。长期保留旧版本有个实际风险MCP 生态是在快速迭代的很多工具服务器的新版本已经开始要求更多协议能力旧版 Pi 可能无法完整支持。所以我的建议是留旧版做应急回退可以但别把它当主力给自己设一个明确的切换日期。落到具体操作上升级过程的每个步骤都做记录真出了问题能快速定位是配置迁移引入的还是新版本本身的行为变化。5. 常见问题与排查技巧实录5.1 MCP 连接失败先按这个顺序查MCP 服务器连接不上是最常见的问题也是升级后最容易被惊吓到的问题。我自己踩过各种各样的坑整理了一个固定排查顺序照着走基本能定位大多数故障。症状优先检查点修复思路transport error启动命令和参数是否正确打开服务器手动执行一遍确认能独立启动服务器状态反复超时网络或进程环境变量检查代理设置确认本地端口未被占用工具存在但调用返回空权限模式和 env 配置先切换 read-only 验证基本链路再放开写入配置文件改了不生效是否有缓存重启 Pi 后重新执行pi mcp list多项目配置冲突profile 是否正确加载检查pi config current指向的 profile确认没有串项目顺序上先看进程能否独立启动再看网络和端口再看权限和缓存。有一个细节stdio 类型的服务器如果启动时打印了一堆 debug 日志到 stdout会污染协议通道导致 Pi 完全无法解析。这种问题不在列表里但如果你遇到命令明明能跑但 MCP 就是连不上请优先检查服务器是否把调试输出写到了 stdout把它改成写 stderr 或日志文件即可。5.2 Durable 会话恢复异常怎么办恢复会话失败的场景不外乎几种磁盘空间不足导致检查点写入不完整、.pi/durable/目录被同步工具冲突覆盖、进程在前一次快照时被强制 kill 导致文件锁残留。针对这些Pi 1.0 提供了一个健康检查命令pi du doctor它会扫描所有会话目录检查索引完整性、文件锁状态和磁盘余量输出诊断报告。我遇到过的一个典型问题是用同步盘同步 durable 目录两台机器同时跑 Pi结果检查点文件出现冲突副本。恢复会话时 Pi 检测到多个候选版本会询问选择哪个时间点恢复。这种功能是好的但前提是你对版本之间的差异有数。所以如果多设备同步 durable 目录建议只开一台机器的 Pi 写检查点另一台只做只读恢复避免写写冲突。这个教训是实际成本换来的。5.3 性能变慢可能不是 Pi 的问题升级到 1.0 之后有朋友反馈说感觉 Pi 变慢了。逐个排查下来真正的原因往往不在 Pi 本身而是 MCP 服务器数量泛滥。每接入一个服务器Pi 在会话启动时都要做初始化握手、资源加载、工具能力注册接入七八个服务器之后启动耗时和内存占用明显上升。这不是 bug是设计的必然代价。解决办法也很直接在 profile 里按项目需求开启最小服务器集合。Pi 1.0 支持按需加载设置了lazy: true的服务器只在第一次被调用时才启动而不是 Pi 启动时就全部拉起。我自己的项目里文件系统和 Git 服务器设为常驻数据库、日志分析这类低频工具全部 lazy 加载。实测下来启动时间从原来的四五秒降到一秒左右体感差距很明显。还有一个容易被当成 Pi 问题、其实是 MCP 服务器本身慢的情况。某些服务器是远程 HTTP 服务每次工具调用都要走网络往返慢是正常的。排查时可以用pi mcp ping server-id测延迟如果延迟很高优先优化服务器侧的响应不要盲目给 Pi 加超时时间。把超时调得很大只是掩盖问题不是解决问题。这篇文章写到这主体内容就差不多了。最后说说我个人实际用下来的体会。Pi 1.0 最大的价值不在某个单独功能上而在于它把工具接入标准化和任务状态可恢复这两件事真正落到了日常使用里。我用它连续处理了两周的重构任务最深的感受是敢让它跑长时间任务的底气变足了不用盯着终端怕它意外断开。最后再分享一个小技巧如果你刚升级完先别急着接任何外部服务器用默认的文件系统 MCP 和 Durable 把一套完整的任务-检查点-恢复流程跑通再逐步加服务器。基础链路稳定了后面的一切都会顺很多。
