先交代一个背景：我最近手上一个拖了两周的多模块重构任务，恰好是在终端里靠编程代理跑完的。前几天这个工具从预览版正式跨到 1.0，升级说明里最扎眼的两个词是“原生 MCP”和“Pi Durable”。如果你也长期在终端里用 AI 代理干活，这篇就帮你看清楚这次升级到底动了哪块硬骨头，以及要不要立刻跟着升。

简单说下 Pi 是干什么的：它是个跑在终端里的编程代理，你给它一句话描述目标，它会自己规划步骤、读写文件、执行命令、看测试结果，然后根据反馈接着干。在 1.0 之前，这类工具最大的短板其实是两个：跟外部工具/数据源的连接方式太绕，以及任务到一半就“失忆”。这次发布正好冲着这两个短板来的。

1. 先说结论：Pi 1.0 到底升级了什么

1.1 终端编程代理此前的尴尬现状

在没有 MCP 原生支持之前，终端代理要连接外部能力基本是“打补丁”的思路。比如想让代理能查数据库，很多人会在系统提示词里塞一段说明，让代理靠执行psql命令行去摸数据；想让代理看某个内部平台的页面，就得想办法把页面 HTML 抓下来再喂给模型。这种做法的最大问题是：代理对“用什么工具、能获得什么数据”的理解完全靠提示词里的零散描述，模型并不知道某个外部系统到底有哪些操作边界，经常是猜着用，用错了再纠错，来回折腾好几个回合。

另一个更大的痛点是会话状态极其脆弱。终端代理干活往往是一个长任务：先用十来分钟勘察整个工程的目录结构，再找关键文件逐个读，接着拟定修改方案，然后一处处改代码、跑测试、看报错、再改。整个过程里模型依赖的“上下文”都在当前进程的内存里。一旦终端被关掉、电脑休眠后进程被杀、或者网络抖动导致会话断开，之前所有勘察结果和已经做的决策就全没了。下次打开终端，代理又变成一张白纸，逼着你从头描述任务。

1.2 1.0 带来的三个关键变化

这次 1.0 解决的就是上面这两类问题，顺带把工程化程度也拉高了一截。我理解的核心变化有三点：

第一，MCP 从“外部插件式的支持”变成了“内置原生能力”。代理进程启动时就直接拉起 MCP 客户端，配置好连接的服务端，模型在推理过程中可以像调用本地函数一样去请求外部数据或操作外部工具，协议层的事情由内核完成，不再需要一个额外的桥接进程在中间转发。

第二，Pi Durable 把“记忆”真正落了盘。它会在任务执行的多个节点自动保存快照，包括会话历史、文件变更记录、已执行命令、环境状态等。下次开会话时可以直接从某个检查点恢复，代理还记得自己在干什么、干到哪一步了、哪些决策已经定过。

第三，整体的配置和迁移路径变得清晰。1.0 提供了一整套命令来处理 MCP 服务器的声明、连通性检查、Durable 存储的初始化，以及从旧版本的配置迁移，不用再像以前那样手改一堆 JSON 文件还要担心格式对不上。

如果你之前被终端代理的“连接费劲”和“动不动失忆”劝退过，这次升级算是把两条最影响体验的沟壑填上了。

2. 原生 MCP：从“能用”到“好用”的质变

2.1 MCP 对终端代理到底意味着什么

MCP（Model Context Protocol）简单说就是一套约定好的协议，让 AI 模型能通过统一的方式去调用外部工具、读取外部数据。它定义了客户端（比如 Pi 这个代理）、服务端（比如一个文件系统访问器、一个数据库连接器）、以及它们之间传输消息的格式。你可以把它类比成 USB-C 接口：不同的外部设备（U 盘、显示器、扩展坞）只需要都做成 USB-C 口，电脑就能统一接。MCP 解决的是“模型怎么跟 N 种外部系统对话”的标准化问题。

对终端编程代理来说，MCP 的意义在于：代理不再需要用自然语言去“猜”外部系统的用法，而是通过一组结构化的工具定义，明确知道某个服务端提供了哪些能力、每个工具接收什么参数、返回什么结构。比如一个数据库 MCP 服务端会向模型声明query(sql)这个工具，模型就知道可以传一段 SQL 进去，然后拿到结构化的查询结果。这比让模型自己拼psql -c "..."命令再解析输出要可靠得多。

2.2 原生支持与桥接方案的区别

在 1.0 之前，也有人给终端代理加过 MCP 能力，但基本都是桥接方案：外部起一个独立进程做 MCP 客户端，代理通过某种 IPC 跟这个进程沟通，再由这个进程去跟 MCP 服务端通信。链路多一跳，问题也跟着多：

• 多一个进程就多一个故障点，桥接进程挂了自己还不知道，代理只看到工具调用了没返回。
• 流式传输和取消请求在中转时容易丢语义，一段长的工具输出可能被截断或者卡住。
• 配置要靠环境变量和额外脚本拼凑，换个机器就是一场灾难。

原生支持则是在代理核心内部实现了 MCP 客户端逻辑。代理读取配置后，自己直接跟各个 MCP 服务端建立连接、管理生命周期、转发调用请求。好处很实际：工具调用的延迟更可控，模型的推理循环跟外部调用是一个整体，超时、取消、重试这些语义都能正确处理。用下来最直观的感觉是，之前偶尔会出现的“工具调用半天卡住无响应”基本消失了。

2.3 用配置文件跑通一个真实场景

我现在的日常工作流里，Pi 1.0 接了三个 MCP 服务端：文件系统、本地数据库、内部搜索服务。配置文件长这样（不同版本可能字段略有差异，但思路通用）：

{ "mcp": { "servers": [ { "name": "workspace-fs", "transport": "stdio", "command": "pi-mcp-filesystem", "args": ["--root", "~/projects/current"] }, { "name": "local-db", "transport": "http", "url": "http://127.0.0.1:9911/mcp", "headers": { "Authorization": "Bearer local-dev-token" } }, { "name": "internal-search", "transport": "stdio", "command": "pi-mcp-search", "args": ["--index", "~/docs-index"] } ], "defaultEnabled": ["workspace-fs", "local-db"] } }

这里有两个细节值得说。第一，stdio 和 HTTP 两种传输方式都有实际用途：本地工具用 stdio，由 Pi 拉起子进程并通过标准输入输出通信，配置最简单；远端或常驻服务用 HTTP，比如数据库连接器如果已经跑在本地端口，就可以直接复用，避免每次会话都要重新握手认证。第二，defaultEnabled字段控制启动时默认拉起哪些服务端，其它服务端可以按需在会话里临时启用，这样不会因为服务端太多拖慢启动速度。

配好之后，我可以直接对代理说“看一下当前工程里所有超过 500 行的文件，按调用关系列个清单”，它会调用文件系统 MCP 去遍历目录，而不是靠猜。再比如让它分析某个数据变更影响面，它可以直接通过数据库 MCP 查 schema 和索引情况，步骤清晰、输出可控。

2.4 MCP 使用中的几个要点

原生 MCP 有了以后，并不等于随便配一堆服务端就能高效干活。我自己踩出来几条经验：

• 服务端不是越多越好，每个服务端启动都要时间，工具声明还会占用模型的上下文空间，默认只启用真正高频使用的两三个。
• 命名要一目了然。workspace-fs、local-db这种名字，代理和人都能立刻明白用途；起个helper、service这种模糊名字，模型推理时都可能混淆。
• 本地 stdio 服务端要注意路径权限。给文件系统服务端配置--root而不是让它默认访问整个磁盘，既安全又能减少模型在无关目录里的无效探索。
• HTTP 服务端要注意认证信息的存放。配置里明文 token 只是方便开发，别把带 token 的配置文件提交到公共仓库。标准做法是支持从环境变量读取，我自己的配置里就用的${LOCAL_DB_TOKEN}这种占位符。

3. Pi Durable：为长时间任务补上的最后一块拼图

3.1 终端代理最怕什么：任务中断

说完了 MCP，再说这次让我觉得最值回票价的另一个升级——Pi Durable。

用过终端代理的人应该都有过这种体验：代理已经花了几十分钟勘察代码库、分析了多条调用链、开始动手改第三个文件了，这时候电脑突然没电关机，或者终端窗口被误关，或者 SSH 断开。等你重新打开终端，代理一脸茫然地看着你，完全不记得刚才的进度，你只能复制之前的任务描述重新开始。运气好上下文相关文件还能重新定位，运气不好连之前确认过的方案细节都得一点一点重新问出来。

这个问题的根因在于：大部分会话上下文是纯内存态的，进程退出即消失。IDE 插件的场景稍微好一点，因为 IDE 本身会保留文件列表，但终端代理对“当前任务目标、中间结论、已做改动”的记忆一样脆弱。

3.2 Durable 机制是怎么工作的

Pi Durable 做的事情，简单说就是把“工作记忆”持续落盘。它不像普通的日志那样只是记录聊天文本，而是保存了一种可以恢复执行的结构化状态。按我的观察，它主要包含三层：

第一层是会话上下文。包括任务目标、用户和代理的全部对话记录、代理在推理过程中的关键中间结论。这相当于把模型“脑子里想的事情”导出了一份副本。

第二层是执行台账。代理执行过哪些命令、每个命令的退出码和关键输出、改过哪些文件、是否有文件处于“改了一半”的状态。这份台账让恢复后的代理能判断“哪一步已经完成、哪一步还没开始”，不需要盲目重跑。

第三层是环境锚点。会话发生时的工作目录、Key 环境变量、正在使用的 MCP 服务端连接状态等。这个细节很关键，因为终端代理的很多操作都依赖工作目录，恢复会话时如果目录不对，后续脚本、测试命令全都得重来。

可以把它理解成操作系统的休眠而不是关机：休眠会把内存中的状态完整保存到磁盘，下次开机直接回到之前的工作现场。进程没丢上下文，只是中间隔了一会儿。

3.3 配置与恢复流程

Pi Durable 的配置并不复杂，默认是开启的，但建议手动确认一下存储位置和保留策略：

{ "durable": { "enabled": true, "autoSaveEvery": "30s", "storeDir": "~/.pi/state", "maxSnapshots": 50, "retention": { "keepDays": 7, "keepSuccessfulOnly": false } } }

几个字段的用意说一下：

• autoSaveEvery是自动快照间隔。我设成 30 秒，基本可以保证意外中断时最多丢失 30 秒的进度，代价是频繁写入对性能影响很小，毕竟快照是增量保存。
• maxSnapshots限制快照数量，防止跑一个大项目后磁盘被快照占满。
• keepDays是保留天数。太短会导致几天的旧任务无法恢复，太长又容易积累大量无用数据，一周对我来说比较合适。
• keepSuccessfulOnly如果设成 true，只保留成功完成任务的快照，但实际操作中我建议保留失败任务的快照，因为很多时候你需要恢复一个失败任务去分析为什么失败。

恢复会话的操作也简单。比如某个任务跑到一半终端被关了，重新打开后执行：

pi session list pi session restore --id <session-id>

代理会把之前的工作目录切回去、重建 MCP 连接、重新加载会话上下文和执行台账，然后告诉你“上次进行到修改配置文件中的第 N 行，接下来要继续吗”。这种体验非常接近 IDE 里的断点续跑。

3.4 存储管理与安全注意

Durable 把状态落盘之后，有一个安全细节很容易被忽略：快照里包含对话内容、文件内容片段、执行过的命令，这些可能是敏感信息。默认存储目录在用户主目录下，权限是当前用户可读写，这没问题。但如果你是团队协作的机器，注意别把存储目录软链到共享盘里。还有一点，如果任务涉及密钥、Token，建议在任务描述里避免直接粘贴明文，而是让代理去读环境变量，因为快照里可能会留下明文痕迹。

我实际用的时候还发现一个值得注意的点：快照恢复并不是万能的。如果代理当时正在调用一个外部命令，比如正在跑一个耗时很长的测试，测试已经执行了 20 分钟还没结束，这时候中断，恢复后代理虽然知道“测试在跑”，但测试进程本身已经没了，它只能选择重新跑或者根据已有输出做判断。也就是说，Durable 保存的是“代理的认知状态”，不是系统里所有子进程的现场，别把它当成虚拟机快照用。

4. 从预览版迁移到 1.0 的完整实操

4.1 升级前的检查清单

Pi 1.0 不是一个小版本迭代，从预览版直接跨到正式版，配置格式、命令名称都有调整。我建议升级前先做三件事，能省掉后面一堆麻烦。

第一，确认旧版本号。用pi --version看一眼，如果你是特别老的预览版，迁移工具可能不支持直接一步到位，得先升到某个中间版本。

第二，备份旧配置。别看只是几个 JSON 文件，里面可能有你积累良久的 MCP 服务端定义和工作区设置。我习惯直接复制一份配置文件，再顺手把 durable 的存储目录也打个 tar 包。

第三，记录当前常用的 MCP 服务端列表。因为旧配置可能用的是老格式的服务端描述，迁移工具转换时偶尔有漏网之鱼，提前记下“我原来配了哪些服务端”，迁移完逐项核对，比到时候发现问题再翻历史记录快得多。

4.2 迁移步骤详解

官方推荐的迁移路径是直接用内置命令，我实测下来比较顺：

pi doctor pi config migrate pi config validate pi mcp verify

第一步pi doctor会做环境自检，检查运行时版本、配置目录权限、MCP 服务端依赖项等。如果这里报错，先解决环境问题再做后续步骤，别硬着头皮往下跑。

第二步pi config migrate会读取旧配置文件，按 1.0 的格式生成新文件。旧文件会被重命名备份，不会直接覆盖。迁移完后它会列出哪些字段做了变更、哪些值被重置，这个输出建议截图留存。

第三步pi config validate校验新配置的语法和字段合法性。我遇到过一种情况：旧配置里有个自定义字段，迁移工具不认识，直接给丢掉了，但校验工具并不会主动提醒你“有字段被忽略”。所以校验通过不代表完全一致，最好人工扫一遍生成的配置。

第四步pi mcp verify逐条验证配置里声明的 MCP 服务端能否连通。它会对每个 stdio 服务端尝试拉起子进程并握手，对 HTTP 服务端发一个探测请求。这一步能帮你快速发现哪些服务端路径变了、哪些命令在新环境里没装。

4.3 旧配置兼容性处理

迁移过程中最容易踩的坑我总结有三个：

一是老的 MCP 服务端命令路径失效。预览版时期很多人手动装过 MCP 服务端，装的时候用了个临时路径，后来系统 PATH 变了，迁移之后日志里就会报“找不到命令”。处理办法是升级后统一pi mcp install <server>重装一遍，或者把服务端路径改成绝对路径写进配置。

二是 Durable 存量快照的迁移。pi config migrate只处理配置，不处理已有的状态快照。我升级之后执行pi session list发现旧会话没出现，折腾了一会儿才意识到需要手动导入旧存储目录。操作也简单，把旧存储目录下的数据文件拷贝到新storeDir里，重新执行pi durable scan就能识别出来。

三是环境变量占位符。旧配置里 MCP 服务端可能用${VAR}这种写法读取环境变量，迁移后如果变量名变了，服务端启动时会静默失败。最直接的表现是pi mcp verify显示某个服务端连接超时，但看日志又没有报错。排查技巧是手动在终端里执行那个命令路径，看看环境变量是否真的存在。

我自己从预览版升到 1.0 大概花了不到二十分钟，大部分时间花在核对 MCP 服务端列表上。整体迁移路径打磨得比较平滑，没有出现“升完级完全不可用”的情况。

5. 实测一周：场景表现与踩坑记录

5.1 典型任务场景实测

升级完我特意拿三类任务做了实测，覆盖了日常最典型的用法。

第一类是跨文件重构。我让 Pi 把一个模块里散落四处的一批工具函数收敛到统一目录，并同步修改所有调用方。在原生 MCP 的帮助下，它先用文件系统服务端拿到了工程里所有引用这些函数的位置，形成一份清单，然后逐个文件处理。这期间我故意把任务拆成三段做，前两段之间让代理停下来，我用pi session list确认会话还在，又用pi durable restore恢复了一次，代理明确记得“已处理完 23 个调用点，还剩 7 个”，完全没重复劳动。

第二类是数据库影响面分析。我让代理分析某个表结构调整会影响哪些查询和接口。它通过数据库 MCP 直接拉到了表 schema、外键关系、相关索引，再结合代码搜索定位到引用位置。第一次接触这类任务时我还有点担心模型会不会乱猜表结构，实测下来它每一步都引用的是 MCP 返回的元数据，没有靠想象补细节。

第三类是长时测试监控。之前我们的一个集成测试套件经常要跑四十多分钟，以前代理跑测试期间一旦终端断连，测试结果和中间日志全丢。这次用 Durable 特性，代理每隔 30 秒保存一次状态，我可以中途随时关掉终端，过一会儿再恢复，代理能续上“还在等测试结果”的状态，并在测试结束后给出汇总。这个场景应该是最能体现 Durable 价值的。

5.2 遇到的问题与排查思路

实测一周当然也踩了几个坑，记录一下排查思路。

遇到的第一个问题是某个 MCP 服务端连接成功后偶发超时。现象是代理调用工具时偶尔报“connection closed”，但服务端进程看起来还活着。排查了几轮，发现是服务端日志里频繁出现内存相关告警，估计是返回的数据包太大导致内存压力。最后把配置里的输出大小上限调低，问题就不再出现。如果你也遇到类似问题，先看 MCP 服务端的日志，绝大多数不是协议问题，是服务端扛不住大请求。

第二个问题是 Durable 快照恢复后，代理对当前工作目录的判断出现偏差。现象是恢复会话后它想执行cat config/settings.yml，但系统提示文件不存在。排查后发现恢复操作是在另一个目录下启动的，Durable 虽然恢复出了环境锚点，但如果当前 shell 的工作目录跟快照不一致，有些命令还是会基于当前 shell 的 PWD 执行。解决办法是恢复后先用cd回到快照记录的目录，再让代理继续。这个也可以认为是快照恢复时的预期限制，毕竟它不会去强制改你的 shell 目录。

第三个问题比较冷门：配置里开了多个 HTTP 类型 MCP 服务端，其中一个因为服务端协议版本不一致直接拒绝握手。一开始 Pi 启动时没报错，但访问那个服务端的工具时始终返回错误。我查了pi mcp verify结果，显示 connection ok，但实际工具调用失败。最后发现是 HTTP 服务端实现的 MCP 协议版本比客户端低一个次要版本，虽然握手成功但某个工具定义格式不兼容。解决办法是把服务端升级到兼容版本，这类问题排查时最容易蒙圈，建议优先检查两边协议版本号。

5.3 几条避开坑的经验

• 快照别留太多。maxSnapshots设成无限会让存储目录膨胀，尤其是文件变更台账，跑几个大项目就能吃掉几个 GB。够用就好。
• 重要任务开始前手动做一个 checkpoint。虽然 Durable 定时自动保存，但手动pi durable checkpoint可以确保某个关键节点之前的状态万无一失，比如批量改文件之前、跑大规模重构之前。
• MCP 配置里命令路径尽量写绝对路径。PATH 在交互式终端和后台进程之间的差异是很多诡异问题的根源，写成绝对路径，哪怕启动入口脚本换了环境也不容易挂。
• 升级后第一周不要急着删旧存储目录。等你确认新版本稳定、旧会话不再需要了，再清理预览版的 Durable 数据，减少万一迁移遗漏某块历史状态的后悔成本。

6. 与 IDE 插件方案对比：为什么我坚定转向终端代理

6.1 三种方案的对比

用了一段时间 Pi 1.0，我想聊聊为什么它比 IDE 里的 AI 插件方案更适合一部分人。先摆一张对比表：

这个表能看出来，终端代理在“长任务、跨文件、多系统联动”上是明显优势方。源码目录在本地但 IDE 打不开的服务器环境（比如开发机）更是终端代理的主场。IDE 插件强在即时性：改了代码立刻看报错、光标所在处的内联补全体验是终端代理比不了的。两者不完全是替代关系，更多是场景互补。

6.2 我个人的分流策略

我现在的用法是：在 IDE 里处理高频小改动，让补全和即时语法检查辅助我手写；一旦任务变成“调研一个模块然后整体调整”或者“跨服务梳理数据依赖”，就跑到终端里派给 Pi，让它独立执行。中间用 Git 分支做隔离，不满意直接丢掉重来。

这种分流策略的好处是两边都发挥各自强项。IDE 那边不需要为了支持复杂任务去装一堆插件，终端这边也不用强行提供内联编辑体验。回到 Pi 1.0 本身：有了原生 MCP，外部系统的信息获取不再是痛点；有了 Durable，长任务的中断焦虑也基本消失。让我选最值得升级的理由，我会说 Durable 治好了我最大的心病——以前那种“跑半天代理结果一瞬间全忘了”的挫败感真的受够了。

最后再分享一点个人体会

如果你还在用预览版，我建议尽快做一次升级和迁移，特别是经常在服务器上跑长任务的场景，Durable 带来的改变是体验级的。升级后的第一次长时间任务，建议开两个终端，一个跑代理，另一个用来观察 Durable 存储目录的增长情况，亲眼看到状态按预期落盘，你对这个功能的信任感会建立得更快。

操作上别忘了最基础的一条：重要任务开始前，先确认配置里durable.enabled是true。别等到任务跑了一半才想起检查，那时候已经晚了。我个人的习惯是每次新建任务时都会瞄一眼会话列表，确认自动保存正常启动，几秒钟的检查能让后面十几个小时都安心。