Pi 1.0 正式发布：原生MCP支持与Durable持久化，终端代理迎来升级

Pi 1.0 正式发布，这次升级最核心的两件事：原生支持 MCP，以及加入了 Pi Durable 持久化层。如果你一直在终端里用 AI 编程代理干活，应该能立刻感受到这两项的分量——以前的代理是“开一个会话长一个脑子”，只能在当前终端进程里帮你改文件、跑命令，换个窗口、隔一天再回来，它什么都不记得，你还得把项目背景、约束条件、已经改到哪一步重新讲一遍。现在不一样了，Pi 能通过标准协议直接接入各种外部工具和数据源，并且把任务进度、关键决策、工作区状态完整保存下来，下次启动还能接着干。

这篇文章不打算写成发布会通稿，我从使用者角度拆一下：Pi 1.0 的 MCP 原生支持到底解决了什么问题，Durable 是怎么做到跨会话恢复的，以及实际跑起来有哪些坑。内容主要面向两类读者：一类是重度使用终端 AI 工具的开发者，另一类是对 MCP 协议和持久化设计感兴趣、想自己做类似工具的人。我会尽量把原理讲清楚，也会给出可以直接照着配的步骤。

1. 为什么要做这次“结构性升级”

1.1 终端代理的老毛病：能力孤岛和失忆式协作

我接触终端编程代理也算比较早了。这类工具最初的形态很简单：一个 CLI 程序，把大模型的对话能力封装起来，让它能帮你执行 shell 命令、读写文件、生成代码。听起来很美好，但用一阵子就会发现两个特别恼火的点。

第一个是能力孤岛。代理默认只能做开发环境里已经具备的操作，要接别的系统就得写一堆胶水脚本。每次想让它查询某个外部服务的状态、操作数据库、读监控面板，或者调用内部文档，都得手动写集成代码，而且不同工具的接入方式五花八门。有的走 HTTP API，有的走命令行封装，有的只能通过文件导入导出。到头来，代理的能力被限制在“能跑命令、能读写本地文件”这个封闭圈子里，价值大打折扣。

第二个是失忆式协作。终端代理默认是无状态的，每次启动都是全新会话。可真实开发任务是跨天的，我昨天可能刚让代理排查完一个接口异常，今天想继续深挖，它完全不记得昨天查到哪一步了。更麻烦的是，如果一个任务涉及修改多个文件，中间切换了几次窗口或会话，代理对不同文件改动的记忆是支离破碎的，需要反复把上下文重新喂给它。这种体验就像每次跟同事讨论到一半就要重新自我介绍，时间全浪费在同步背景上。

1.2 双引擎路线：MCP 和 Durable 要解决的是两类根本问题

Pi 1.0 选择同时推原生 MCP 和 Pi Durable，不是功能堆叠，而是顺着上面两个痛点对症下药。

MCP 解决的是“代理的能力边界”问题。MCP 的全称是 Model Context Protocol，即模型上下文协议，它定义了 AI 应用与外部工具、数据源之间的统一交互标准。你可以把 MCP 理解成连接外部能力的一整套接口规范。Pi 1.0 原生实现了 MCP 客户端角色，能通过标准协议发现、连接、调用各种 MCP 服务器提供的工具。这意味着代理不再局限于本地命令，而是可以像插 USB 设备一样，即插即用地接入文件系统、数据库、浏览器调试接口、内部文档库等外部资源。

Pi Durable 解决的则是“状态连续性”问题。它把代理的工作现场持久化到一个专门设计的状态存储层里，包括会话事件、中间产物、工作区变化快照。这样即使终端关掉、电脑重启、不同目录下再打开 Pi，它都能把之前的状态重新加载回来，接着上次的进度继续执行。

用一个表格看升级前后的差异比较直观：

这两条线各管一摊，但叠加以后效果是互乘的：MCP 让代理“手变长了”，Durable 让代理“记性变好了”。一个能调用广泛工具并且记得住上下文的终端代理，才真正接近“开发者身边的可靠搭档”。

2. 原生 MCP 支持：让代理真正长出手脚

2.1 MCP 到底是个什么协议

先把这个概念讲透。MCP 可以类比成设备接口界的 USB 标准。在 USB 出现之前，打印机、键盘、鼠标各有各的接口，每次接新设备都要准备对应的转接头、驱动、协议文档。USB 出现以后，外设厂商按统一标准生产，电脑端一个接口就能接所有设备。MCP 干的就是类似的事，只不过面向的不是物理设备，而是 AI 应用需要调用的各种“能力”。

在 MCP 体系里有几个关键角色：MCP 主机是 AI 应用本身，MCP 客户端负责建立连接和通信，MCP 服务器对外暴露具体能力。每个 MCP 服务器可以提供三类原语：tools 是可供模型调用的具体动作，比如“查询文件”“执行 SQL”“搜索网页”；resources 是可以被读取的数据资源，比如“某个表格”“某份日志”“某个配置”；prompts 是可复用的提示模板，比如“帮我审查这段代码的格式”。

Pi 1.0 在终端代理层面原生实现了 MCP 客户端。也就是说，Pi 本身就是一台“智能主机”，它能够连接外部 MCP 服务器，发现服务器上有哪些 tools、resources、prompts，然后在对话中根据用户需求自主决定调用哪个工具、读取哪份资源。用户侧的感知就是：你能让 Pi 直接查询本地数据库、操作某个外部系统，而不用再手动帮它写调用代码。

很多人第一次听到 MCP 会误以为它是一个高深复杂的框架，其实底层逻辑非常简单：就是一套基于 JSON 的消息交换规范。MCP 规定了消息该怎么发、该包含什么字段、错误该怎么返回，所有实现方都遵守这套规则，互操作性就建立起来了。Pi 1.0 把这套规范内建在调度层，而不是当作外部插件临时挂载，所以稳定性明显好过那些靠运行时打补丁、拼提示词的做法。

2.2 原生实现和“事后补救”式接入，区别在哪里

市面上有些类终端代理工具也声称“支持 MCP”，但实现深度差别很大。一类是在提示词层面做文章，通过把 MCP 工具说明拼进 system prompt，让大模型“假装”能调用外部工具，实际执行时还是靠正则匹配和子进程模拟，结构化程度很低。另一类是在规则层面做文章，用一系列 if-else 匹配工具调用意图，工具多了规则很难维护。这两种都不算真正的原生支持。

Pi 1.0 的做法是把 MCP 协议栈嵌进代理的核心调度流程。用户发来请求后，代理内部会经历：意图识别、任务拆解、工具检索、调用决策、执行与返回解析。其中工具检索和调用决策直接面向 MCP 的 discovery 和 invoke 接口，工具返回的是结构化数据，不是自然语言文本流。举一个直观的差别：如果工具返回一个 JSON 格式的查询结果，原生适配的代理能直接把这个 JSON 当作结构化数据参与下一步决策，而提示词拼出来的“伪适配”只能把 JSON 文本塞给模型让它自己理解，前者准确率高得多。

还有一个容易忽略的细节：MCP 的传输方式。Pi 1.0 同时支持 stdio 和 HTTP 两类传输通道。本地工具用 stdio 最合适，因为代理可以直接派生子进程并与之交互；远程服务用 HTTP，可以跨机器连接。原生支持意味着这些传输细节被统一在协议层处理，用户只需要在配置里声明用哪种方式，不需要关心底层的进程管理或网络握手逻辑。

2.3 实操：接入一个 MCP 服务器最快需要几步

讲一个最基础但非常实用的场景：接入一个本地文件系统 MCP 服务器，让 Pi 能通过标准协议做文件搜索和内容读取操作。以配置文件为例，在 Pi 的 MCP 配置段里添加一条服务器声明：

[mcp.servers.local-fs] command = "pi-mcp-filesystem" args = ["--root", "/workspace/project-a"] transport = "stdio"

保存后执行以下命令验证连接：

pi mcp list

命令输出里应该能看到local-fs这个服务器，并且能列出它提供的工具清单。接下来直接在对话里对 Pi 说“帮我在项目 A 里找所有超过 500 行且最近三天修改过的源文件”，Pi 会自主调用 filesystem 工具完成搜索，然后把结果整理给你。

这里补充一个我在实操中的经验：一开始不要同时配置一堆 MCP 服务器，先接入一个，把连接、调用、返回解析整条链路跑通，再逐步加。因为 MCP 生态虽然统一了协议，但每个服务器返回的数据结构和工具命名风格仍有差异，如果一次配置太多，遇到问题很难定位是哪个环节出的错。

3. Pi Durable：把短期记忆升级成长期工作台

3.1 Durable 到底在持久化什么

Pi Durable 不是简单把对话记录存到一个文件里，而是围绕“代理工作现场”做了分层设计。根据我拆解和实际使用观察，它持久化的核心内容可以分三类。

第一类是会话事件流。每一次用户输入、代理的工具调用、模型回复、工具返回结果、关键决策依据，都会以追加式事件日志的形式记录。这类数据解决了“代理记得住”的问题，等于把一次会话的完整推演过程固化下来。

第二类是中间产物。代理在执行任务过程中生成的补丁、搜索结果、错误日志快照、临时分析报告，这些内容不算最终成果，但它们是理解任务进度的关键。没有 Durable 的话，这些中间产物随会话销毁而丢失；有了持久化，代理重启后可以直接引用之前的搜索结果，不用重新查一遍。

第三类是工作区状态快照。Pi 1.0 采用内容寻址的方式记录文件版本变化，不会所有文件盲目全量保存，而是按内容哈希去重。文件没变就不重复存储，只记录变化增量。这样既保证了可以恢复到任意历史节点，又控制了存储量增长。

用事件源的方式做持久化有一个明显优势：完整可回溯。任何时刻 Pi 都能回答“这个决策是在哪个会话里基于什么数据做出的”，这在实际协作中非常有用。同时事件流可以压缩、可以合并，老的日志沉淀到快照之后，日常恢复就不需要重放所有历史事件。

3.2 存储结构和恢复流程

Pi Durable 的持久化数据默认存放在用户目录下的专用文件夹里，典型结构大致如下：

~/.pi/durable/ sessions/ <session-id>/ session.toml events.log artifacts/ workspace-snapshot/ indexes/ event-index.db content-hash.db

sessions/<session-id>是单个会话的完整工作区。session.toml记录会话的元数据，包括创建时间、最后活跃时间、用户命名的会话名、关联的工作目录。events.log按时间顺序记录事件流中的每一条记录，每条事件带有序号、时间戳和事件类型。artifacts目录存放中间产物文件，workspace-snapshot目录存放内容寻址后的文件快照。indexes目录里是全局索引，用来加速跨会话的搜索和定位。

启动恢复流程是：Pi 启动时先读取全局索引，定位需要恢复的会话；然后校验events.log的完整性，确认事件流没有缺口；接着加载最近的workspace-snapshot作为基线；最后按事件日志重放基线上的增量事件。三层组合完之后，代理才把“记忆”加载到工作内存中。

这个恢复流程最让我满意的是它对异常中断的容忍度。正常情况下你杀掉 Pi 进程，事件流最后一条还没来得及写入，下一次启动时 Pi 能通过索引检测到这种截断，自动从最后一条完整事件恢复，不会把不完整的事件当作有效状态。这点在长任务稳定运行的时候特别重要。我实际跑过一次连续 6 小时的任务，中途手动 kill 进程，重启后 Pi 能准确说出自己处理到第几步，没有出现半个事件被当成有效状态的脏数据。

3.3 跨会话任务恢复：真实工作流演示

用一个我实际跑通的场景说明跨会话恢复的体验。

周一下午，我让 Pi 排查一个批量任务偶发超时的问题。Pi 通过 MCP 工具读取了任务调度日志，定位到某台缓存服务的响应延迟异常，写了一段分析日志存到artifacts，最后它告诉我“问题可能出在缓存连接池配置上”，并把一个待验证的命令放在会话里。

当天我关掉终端下班了。周二早上我在另一个目录下打开 Pi，执行如下命令：

pi session resume --last

Pi 进入恢复模式，几秒钟后加载了昨天的会话状态，自动恢复工作目录、工具连接和上下文。我直接问它：“昨天那个超时问题，你后面想验证什么来着？”Pi 的回答是：“昨天我定位到缓存连接池配置可能有问题，我准备用redis-cli info clients观察 connected_clients 的波动情况。另外我还在 artifacts 里留了一段日志分析的输出。”

这就是一个完整的工作连续性体验：不需要我重新粘贴一遍项目背景、日志路径、分析方法，Pi 自己记得所有细节。尤其对那种“任务周期跨越几天”的活，这种能力价值极高。你不需要把代理当作无状态工具反复喂上下文，它可以像一位真正参与项目的成员一样，把前一天的工作延续下来。

4. 升级前后的实操对比：同一个小需求，两种体验

4.1 场景 A：排查端口占用问题

先说升级前的老流程。如果我想让传统终端代理帮忙排查端口占用，通常只能发自然语言让它“分析一下”，代理缺乏标准化的工具调用能力时，只能给我指个方向。高情商的做法是它建议你去执行lsof -i :8080，然后你手动把输出贴回去；低情商的甚至只会给你一段自己看代码的提示。

Pi 1.0 的流程是：用户说“8080 端口被什么占了，帮我看一下”，Pi 通过 MCP 工具直接执行端口查询、读取进程列表、遍历相关服务的配置文件，全程不需要用户手动跑任何命令。老流程需要你来回复制粘贴，新流程是代理自己做完整个信息获取过程，最后只把结论和后续建议交给你。

用列表对比一下：

传统流程：

1. 用户手动执行lsof -i :8080
2. 把输出复制回会话，让模型分析
3. 手动查询进程 PID 对应的服务名
4. 模型再给建议，很可能还得手动验证

Pi 1.0 流程：

1. 直接描述需求
2. Pi 自动调用系统查询 MCP 工具，获取端口占用信息
3. 自动关联进程信息与服务配置
4. 返回结论、影响范围和处理建议

新流程减少的不是一点半点操作，而是把整个信息链路变成自动化。这背后靠的就是原生 MCP：Pi 能调用统一的端口查询工具、进程管理工具、配置读取工具，让模型不是在“看命令输出猜结论”，而是在“调用可靠工具得到结构化数据，再做判断”。

4.2 场景 B：跨三天的需求迭代

再举一个更贴近日常工作节奏的场景：一个功能需求分三天做完。

升级前，如果你第二天、第三天还想让代理继续帮写代码，你得反复重申需求背景、已经写好的文件位置、上一轮做过的设计取舍、接下来打算做什么。碰上复杂的重构，光是把这些说清楚就可能花掉十几分钟。更麻烦的是，如果你中间换了一台设备或换了一个终端用户，那些历史上下文就彻底断了。

升级后，Pi Durable 把这些内容统统持久化解了。我实际跑过一个模拟项目 X 的功能迭代：第一天让 Pi 搭建项目骨架并实现基础模块；第二天直接执行pi session resume --name feature-x，Pi 自己回到项目根目录、加载第一天的代码和设计记录；我只需要说“把昨天那个模块的数据校验补上”，它就知道指的是哪个文件、哪种校验规则。到了第三天，我甚至可以分派一个全新的小任务，然后让它基于前两天的工作上下文去完成，不需要我再把项目全貌讲一遍。这种连续的协作体验，对长周期任务的效率提升是肉眼可见的。

用一个表格总结两个维度的提升：

5. 常见问题与排查技巧实录

5.1 MCP 工具连接失败怎么办

先说连接失败的一类典型情况。配置好 MCP 服务器后，执行pi mcp list发现工具列表为空，或者调用时报“connection refused”“process exited with non-zero code”之类的错误。这种问题的原因往往集中在三处：命令路径不对、传输协议配置错误、参数没传对。

我的排查顺序是这样的：先用pi mcp ping local-fs这种诊断命令单独验证链路，如果 ping 不通，就检查配置里的command是否在系统 PATH 中。排除了路径问题，再看transport字段是stdio还是http，选错传输方式会导致代理用错连接通道。最后检查服务器进程是否正常启动，有些 MCP 服务器依赖特定的环境变量，而 Pi 派生子进程时默认不会继承全套环境变量，遇到奇奇怪怪的启动失败，可以试试给服务器显式配置环境变量。

另一个容易踩的坑是同时配置多个 MCP 服务器后出现同名工具冲突。比如两个服务器都提供了search工具，Pi 调度层可能不知道该调哪个。我倾向于在配置阶段就给每个工具加命名空间前缀，或者只保留当前任务真正用得到的服务器，减少冲突面。

5.2 Durable 状态冲突和恢复问题

Durable 的一个常见问题是多会话并发操作同一个工作区。我有一次开了两个 Pi 会话，同时让它们改同一个模块，结果其中一个会话的快照状态和另一个会话的操作出现冲突。Pi 1.0 的做法是检测到工作区文件内容哈希发生变化后，会提示状态冲突，让用户选择以哪个会话为准，或者创建一个分支会话。这个机制不会强制你二选一，而是把选择权交给你，但实际使用中最好还是避免这种并发操作，我的建议是不同会话处理不同目录或不同模块。

恢复失败的问题也遇到过，比如某个会话的events.log因为异常中断出现损坏。我尝试过pi durable repair这类修复命令，它能自动扫描缺失的事件序号，尝试从最近的完整快照重建状态。如果修复不起作用，还有一个笨办法：手动删除坏的会话目录重新开始，但这样会丢失没有同步到快照的增量数据。所以我会在执行大改动前用pi durable snapshot手动触发一次快照，给关键节点打上保险。

5.3 性能、存储和隐私边界

随着使用时间增加，Durable 的存储目录会膨胀。尤其是大仓库，频繁的文件变更会产生很多内容寻址快照。我见过有用户跑了几个月后，~/.pi/durable占了好几个 GB。解决思路是配置忽略规则，把node_modules、build、dist这些生成目录排除在快照范围外。Pi 1.0 提供了持久化排除列表配置，这点非常重要，千万不要把所有目录都纳入追踪。

隐私层面，默认持久化是本地明文存储，数据保存在本机。如果要在共享环境或开发机上使用，可以考虑开启存储加密选项。我自己的习惯是把会话里可能涉及密钥、令牌的内容尽量不让代理记录，要么在任务开始前就明确要求不把某些内容写入持久化。不要把敏感信息交给一个会记住一切的工具，这个边界要靠使用习惯去把握。

常见问题速查表整理如下：

6. 一些实操心得与后续可以研究的方向

Pi 1.0 的 MCP 原生支持与 Pi Durable 组合在一起，带来的不是单点功能增强，而是把终端编程代理从“一次性对话工具”变成了“有记忆、有工具生态的持续工作伙伴”。我实际跑了一周多，最大的感受是很多以前不愿意交给代理做的事，现在愿意了。因为它接工具不需要我再写胶水脚本，它会记住我项目里的各种约束和进度，我不用反复为它铺垫上下文。这种信任感的建立，比单纯的“它能写代码”重要得多。

如果让我给刚接触 Pi 1.0 的人一个最实在的建议：先从一个核心任务开始——比如把某个固定的数据查询或日志分析场景通过 MCP 服务器接进来，同时给会话起一个有意义的名字。把这两个基础打牢，再逐步丰富工具配置。不要一开始追求“接满所有工具、所有会话都持久化”，那样只会把排查问题的复杂度翻倍。越聚焦的使用方式，越能发挥这套设计的价值。

另外我个人很期待后续在跨设备状态同步方向上的演进。现在 Durable 是在单机本地，如果能做到多设备间安全同步，就意味着你在台式机上开了一个长期任务，回到笔记本上还能接着推进，那终端代理的实用性还会再上一个台阶。不过在同步机制成熟之前，本地 Durable 加上合理的快照习惯，已经足以覆盖大多数长周期开发任务。核心思路就是：让代理具备工具与记忆两种基础能力，然后大胆地把真实任务交给它跑，踩过几次坑，你自然知道哪些场景最依赖这两个特性。