Pi 1.0 发布：原生MCP与Durable如何重塑终端编程代理

最近我把手头一个项目的终端编程工作流彻底重做了一遍，核心原因是 Pi 1.0 正式版发布了。这个版本给我的感觉不是小修小补，而是把终端编程代理这个品类往前推了一大步——原生 MCP 支持加上 Pi Durable，前者让 AI 代理能直接接入整个外部工具生态，后者让任务真正摆脱了“终端会话一关就断”的宿命。这篇东西我会把这些天从升级到跑通、再到踩坑的全部过程写下来，包括这两块能力到底解决什么问题、怎么配、怎么用、哪些地方最容易翻车，给同样在用或者准备用终端编程代理的朋友一个参考。

先说下我自己的使用场景，方便你对号入座。我日常大量工作在终端里完成：写代码、跑测试、批量改文件、查日志、整理技术文档。之前我用过好几个 AI 编程助手，要么只能在 IDE 里聊天，要么能跑命令但接不了外部数据源，要么就是会话断了任务就全丢。Pi 1.0 恰好把这几块补上了。如果你平时也依赖命令行工作，或者你在折腾 AI 编程代理的自动化能力，这篇应该能给你一些可落地的思路。

1. 这个 1.0 到底升级了什么：项目背景与设计思路

1.1 终端编程代理解决了什么问题

要理解 Pi 1.0 的升级点，得先搞清楚“终端编程代理”到底在做什么。普通的 AI 编程助手，比如 IDE 里那种对话机器人，它的典型工作方式是：你给它看代码片段，它给你建议，然后你自己动手改。这种模式说白了是“顾问模式”，只动嘴不动手。而一个真正意义上的终端编程代理，它是直接住在你的终端里的——它能自己读文件、跑命令、执行测试、修改代码，然后告诉你它做了什么、结果如何。这相当于从“顾问”升级成了“能上手的操作员”。

我之前的实际感受是：这类工具最值钱的地方在于它能用一条指令完成一长串操作。比如我让它“把项目里所有 Python 文件的 print 调用改成 logging”，它会在整个仓库里做全局修改，然后自己跑一遍静态检查，把结果贴给我。这种“描述意图—代理执行—人工验收”的闭环，确实比手动打开一个个文件去改要高效得多。但以前的版本也有个明显的瓶颈：它能操作终端里的事情，却拿不到终端之外的数据。

1.2 原生 MCP：从“单体工具”到“开放生态”

瓶颈在哪儿？举个例子。以前我想让 AI 代理去查询一下本地数据库里的表结构，然后根据表结构生成一段 ORM 代码，这没法直接干——它不认识数据库，也接不上数据库驱动，只能靠我把表结构复制粘贴给它。再比如我想让它自动化操作一下网页来做端到端测试，它也没有浏览器的能力。简单说，以前的终端编程代理是个“单体工具”，能力边界就画在它能读写的文件和能执行的命令上。

Pi 1.0 选择用 MCP 来打破这个边界。MCP 全称 Model Context Protocol，模型上下文协议。它做的事情用一句话概括就是：给 AI 模型和外部工具之间定了一个标准接口。任何工具只要实现了 MCP 服务端，任何 AI 应用只要实现了 MCP 客户端，两边一对接就能用，不需要为一对具体的产品去写专门的集成代码。这就像 USB-C——以前每个设备一根线，现在统一了接口标准，一台机器能接所有外设。原生 MCP 的意义就在于，Pi 不再是功能封闭的单个工具，而是一个可以接插件的平台。数据库、浏览器自动化、文件系统、HTTP 请求工具，凡是有 MCP 服务的，它都能临时调用。

我升级之后最直观的感受：以前要为一个数据源专门写一个小工具，现在只需要在配置里加一条 MCP 服务器记录。生态里有啥直接用啥，没有那种被锁在某个封闭功能里的憋屈感。

1.3 Pi Durable：把“会话”变成“任务”

另一个我觉得比 MCP 影响更深远的更新是 Pi Durable。这个特性解决的是一个特别实际但又特别容易被忽视的痛点：终端编程代理和终端是绑定的。终端一关、电脑一重启、SSH 一断，之前跑了一半的任务就没了，得从头再来。如果你只是让它改几个文件还好，但如果是一个要跑十分钟以上的全仓代码重构，中途断一下简直要命。

Pi Durable 做的事情，是把“会话”变成“任务”。你可以把一个长耗时操作提交成后台任务，让它在 Pi 自己的运行时里持续执行。任务进度、中间状态、输出结果都会持久化保存，哪怕终端早就关了、SSH 断了、笔记本合盖了，任务也会继续推进。等你下次打开终端，用一条命令就能查状态、看结果，甚至恢复到之前的会话继续交互。

我用一个类比来理解它：以前的终端编程代理是“窗口模式”，窗口在，工作就在；窗口没了，工作就没了。Pi Durable 相当于加了一个“后台运行模式”，你把活派下去，代理想办法把它干完，之后回来验收就行。这个体验改变非常大，尤其是对那种需要夜间跑、无人值守的批量任务来说。

2. 原生 MCP 集成：工具生态怎么接、怎么配

2.1 MCP 到底是什么

如果你之前没接触过 MCP，我尽量用最直白的方式讲清楚。先拆成三个角色：MCP 客户端、MCP 服务端、还有中间的协议。AI 应用本身是 MCP 客户端，比如 Pi 就是。提供能力的工具是 MCP 服务端，比如一个数据库连接器、一个浏览器自动化工具、一个文件搜索工具。客户端和服务端之间通过 MCP 协议通信，协议规定了“工具清单怎么获取”“某个调用怎么发出去”“结果怎么返回”这些标准动作。

我举例来说，Pi 接上一个 SQLite 的 MCP 服务端之后，它就能拿到这个服务端声明的工具列表，比如 query、schema、execute 之类。之后 Pi 在推理过程中发现“我需要查一下这个库的用户表结构”，它就可以调用 query 工具去执行一次查询，把结果拿回来作为后续决策的依据。整个过程对使用者来说往往是透明的——你只看到结论，中间它已经不知不觉调了好几个外部工具。

这个协议在技术上支持不同的传输方式。我理解比较主流的是两种：本地进程方式，也就是 MCP 服务端作为一个子进程跑在你机器上，通过标准输入输出和客户端通信；远程 HTTP 方式，客户端通过网络请求去调用一个部署在远端服务上的 MCP 端点。Pi 1.0 对这两种方式都做了支持。本地方式的好处是隐私好、响应快，适合接数据库这类敏感工具；远程方式适合接那种共享的、部署在服务端的工具，比如团队内部的一个内部 API 网关。

2.2 Pi 的 MCP 接入方式与配置

我在自己的机器上接 MCP 的路径大致是这样的：Pi 的配置文件一般在用户目录下的.pi/config.json。1.0 版新增了一个mcpServers字段，里面可以声明一组 MCP 服务器。每个服务器需要写明命令、参数和可选的运行环境。

以我本机上的配置为例子：

{ "mcpServers": { "sqlite": { "command": "uvx", "args": ["mcp-server-sqlite", "--db-path", "./data/app.db"] }, "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] }, "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"] } } }

配置好之后，Pi 启动时会逐个拉起这些 MCP 服务端进程，然后通过 MCP 协议握手。握手完成后，它会在内部维护一张工具清单，记录下来自不同服务端的能力。实际对话里，它会在合适的时机自动使用这些工具。如果你想确认某个工具到底有没有被 Pi 加载到，可以问一句“你现在能调用哪些外部工具”，它会按来源列出。

配置过程中我发现一个小坑——MCP 服务端的启动方式五花八门，有的是uvx，有的是npx，有的又是直接可执行文件。一开始我习惯把所有东西都塞进npx，后来发现这样会让启动变慢，而且有些包不走 npm 生态反而更干净。我的建议是：优先看工具官方文档推荐的启动方式，不要自己图省事统一改成一种。

2.3 工具选型思路与注意事项

接入 MCP 之后，一个很现实的问题浮出来：该挂哪些工具，不该挂哪些？我的经验是三条原则：最小权限、按场景挂载、优先本地。最小权限的意思是，只挂你当前阶段真正会用到的工具，不要把一个拥有文件系统读写能力的 MCP 服务器在你只需要查数据库的时候也开着。场景挂载的意思是结合你手头的任务——如果你这几天在做网页自动化验证，那就挂 Playwright 的 MCP；如果你在写后端，那数据库类的 MCP 优先级更高。优先本地则是我个人的偏好，凡是能用本地进程方式跑的，我尽量不选远程方式，少一个网络链路就少一个故障点。

结合我看到的行业动态，MCP 生态这一两年扩张得非常快。从数据库连接、HTTP 请求、浏览器自动化，到一些专业软件的 AI 接口，都在往 MCP 上靠。这其实是个信号：以后你在终端里通过 AI 编程代理能调用的工具范围会越来越宽。但工具多也意味着你要有点取舍意识——我见过有人一次性挂二十多个 MCP 服务器，结果 Pi 每次选择工具都犹豫半天，反而拉低了效率。工具是给你干活的，不是给你凑数的。

3. Pi Durable 的工作机制：后台任务到底怎么跑

3.1 Durable 的核心设计：任务与进程解耦

Pi Durable 能在关掉终端后继续跑，这个能力不是变魔术，核心在于它把“任务执行”和“终端进程”拆开了。这一点我理解是它整个机制设计的重点。我们平时在终端里跑一个 AI 编程会话，模型推理、上下文管理、工具调用这些状态都活在某一个进程里，这个进程挂在终端上，终端一退，进程收到信号就终止了，状态随之蒸发。Durable 的解决思路是把任务状态做成可持续保存的数据，由 Pi 的一个独立后台运行时去调度和执行，终端进程只是一个“控制面板”而不是“执行现场”。

具体机制上，我理解它基于一套任务持久化框架来实现：任务描述、上下文、执行状态、工具调用记录，这些东西在任务运行的各个阶段都会被序列化保存到本地存储。任务执行过程中，Pi 会定期写入检查点，这样即使任务本身因为某种异常崩了，重启之后也能从最近一个检查点恢复，而不是从头再来。把话说明白点——它不是让你死等一个前台任务跑完，而是把工作拆成可保存、可恢复、可跟踪的状态机。

我打个比方。以前你让 AI 代理干活，就像你在窗口前等着柜台里的人现做一份复杂的餐，你得一直守着。Pi Durable 则像是下了单之后，后厨自己慢慢做，你拎着号牌先走，过会儿回来取就行。这个“号牌”就是任务 ID，“后厨”就是那个独立的后台调度层。

3.2 任务状态机与会话恢复

Durable 任务的生命周期大体上绕着几个状态转：等待中、运行中、暂停、完成、失败。任务提交后进入等待队列，调度器分配资源后进入运行中，如果执行过程中遇到需要人工介入的情况，可能会进入暂停状态，等人恢复会话处理之后继续跑。最终要么完成，要么失败。

状态查看这一块，我这边常用的命令大致是这样：

# 列出所有后台任务以及它们的状态 pi durable list # 查看某个任务的详细输出 pi durable status <task-id> # 恢复一个已暂停或中断的任务会话 pi --resume <task-id>

恢复会话这件事是我觉得最实用的。打个比方，你早上提交了一个大规模测试任务，跑了一会儿发现有几个用例需要你先修一下代码才能继续。你可以把任务暂停，修完代码，再通过pi --resume把原会话恢复——它会记得自己之前在干什么、已经跑到哪一步，而不是像一个新对话一样问“你好，需要我帮你做什么”。

3.3 什么场景真的需要 Durable

Durable 不是所有场景都适用的，我给自己总结了一套判断标准：凡是预计超过五分钟、且不需要我每一步都盯着看、又不怕它自己跑偏的任务，都适合转成 Durable 任务。典型的比如全仓代码风格迁移、批量替换旧 API 调用、整体跑一遍测试并汇总报告、把一堆 Markdown 文档批量转换格式。反过来，那种需要高频人类决策的任务就不适合——比如“帮我边看边改这个模块的设计”，这种交互密度很高的工作，保留在前台会话里反而更高效。

我自己的体会是：判断 Durable 和前台会话的分界线，就看一件事——你要的是“过程参与”还是“结果交付”。如果过程参与重要，留在前台；如果你只要结果，扔给 Durable。这个判断做清楚了，使用体验会舒服很多。

4. 实操：从安装到跑通一个完整任务

4.1 安装与初始化

Pi 1.0 的安装我这边是用包管理器直接装的，如果你是 macOS 环境，用 Homebrew 的话一条命令就行。Linux 环境不同发行版的安装方式可能不一样，建议直接看官方仓库的 README。装完之后先跑一次初始化，它会在用户目录下建好配置和数据目录，同时做一个环境自检，看看本机有没有配好必要的运行时。

# macOS 示例 brew install pi # 初始化配置 pi init

初始化之后，配置文件的路径一般在~/.pi/config.json。这个文件是全文的枢纽——MCP 服务器、默认模型、代理行为偏好都在里面。我的建议是初始化完先别急着配一堆东西，先跑一个最简单的对话确认基础链路通不通：让它读一个当前目录下的文件，然后执行一句命令。基础链路通了，再逐步加 MCP、加后台任务的复杂度。

4.2 把 MCP 服务器逐个加进去

给 Pi 加 MCP 服务器的完整步骤我总结成四步。第一步，想清楚你需要的工具有哪些、分别以什么方式启动。第二步，把对应的启动命令和参数写进mcpServers字段，有的还需要配环境变量。第三步，重启 Pi 让它重新加载配置。第四步，用一句自然语言验证一下工具是否真正可用。

验证这一步特别重要。别只看 Pi 说“已经加载了 5 个工具”就完事，要实际让它用一次。比如我接完 SQLite 的 MCP 后会直接问它“帮我查一下本地这个数据库里有多少张表”，它如果真能查出来，说明这条链路是通的。很多时候配置看起来没问题，但实际调用时才发现命令路径不对、依赖没有、权限不够，所以实测验证是必须的。

4.3 创建一个 Durable 任务并跟踪状态

创建 Durable 任务的方式，我这边使用的接口是pi durable run加上一段任务描述。Pi 会把这段描述解析成一个后台任务，然后再返回一个任务 ID。下面是我实际跑过的一个例子：

pi durable run "把 src/legacy/ 目录下所有 Python 文件的 % 格式化改成 .format() 写法，并跑一遍 py_compile 检查语法，最后汇总修改过的文件列表"

提交之后它会显示类似Task created: du-2024-xxxx这样的 ID。正常情况下，Pi 已经开始在后台推进了，而你当前的终端界面是直接释放的。你可以干别的去，过几分钟用pi durable list看状态。任务完成后，它会提示你completed，然后用pi durable status du-2024-xxxx就能看到完整输出和结果摘要。

要特别提醒一点：刚开始用 Durable 的时候，我对它的预期不太对，以为它像神灯一样“眨眼间全搞定”。实际它的工作节奏更像一个慢慢干活的人——大任务要一步一步来，遇到要跑很久的步骤也不会伪装快。所以提交任务后别频繁刷状态，让它干活，隔一会儿看一次就行。

5. 真实场景复盘：三件事我确实这么干了

5.1 全仓代码迁移：MCP 提供数据，代理动手改

最近我把一个老项目里所有的数据库访问从裸 SQL 改成 ORM 风格。这个活儿烦就烦在：先得摸清楚所有涉及数据库访问的文件、再分析每一处 SQL 和表结构的关系、然后逐个改、改完还要验证。

升级到 Pi 1.0 之后，我把这个任务拆成两步走。第一步，让 Pi 通过 SQLite 的 MCP 服务端把库里的表结构全部拉出来——它自己调用工具拿到了所有表的字段、索引、外键关系；第二步，把这些结构信息作为背景，让它对全仓的裸 SQL 做改写。MCP 在这里的价值很直接：它不用我手动导出一份表结构文档再贴给它，而是它“亲眼”去看了数据库。整个过程中我只在任务开始的时候描述了目标，后面基本是验收和纠偏。

5.2 下班前扔一个 Durable 任务，早上回来收报告

这个场景我很推荐大家都试试。有一天下午下班前，我临时接到一个需求：要对整个项目的所有接口幂等性做一次静态扫描，输出一份报告。这个任务要遍历几十个文件、分析每个接口的写法、还要对照各处的调用方式判断潜在重复提交风险，短时间内根本搞不完。

以前遇到这种事我大概率是加班盯着终端跑。那天我直接提交了一个 Durable 任务，描述里写清楚扫描范围、要检查什么模式、报告格式要求，然后合上电脑走了。第二天到公司，先pi durable list看到状态是completed，再用 status 命令拉出它生成的报告。它有板有眼地把几十处疑似非幂等的接口列了出来，还按风险等级排了序。这个体验让我意识到，AI 编程代理的价值不止于“帮你改代码”，更在于把那些不需要人在场的规模化任务从你的工作时间里剥离出去。

5.3 把 MCP 工具链和 Durable 组合成一个小流水线

单个工具能干活，组合起来能干的活就更多了。我现在比较喜欢的一个组合方式是：用 Playwright MCP 做页面操作，用文件系统 MCP 做产出归档，用数据库 MCP 做数据校验，然后整条链路跑在 Durable 任务里。比如有一次我需要验证一批前端页面在大改之后的展示是否正常、并把关键页面的标题结构抓取下来更新到文档里。

我提交的任务描述大致是“用浏览器工具打开项目首页，先登录，然后依次访问列出的 15 个页面，每个页面把 h1 标题和关键按钮文案抓出来，最后汇总成一个 Markdown 文件并保存到 docs 目录”。这个任务跑完后，我打开文档一看，格式清晰，内容基本准确。这种“外部工具 + 后台调度”的组合，确实让终端编程代理从一个被动问答工具变成了能主动执行复合任务的执行平台。

6. 踩坑记录与排查技巧速查表

6.1 会话恢复了，但上下文丢了

这个问题我遇到好几次，现象是pi --resume能恢复对话，但它好像忘了我刚才让它干什么了，甚至反过来问我“你想让我做什么”。排查下来发现大多是因为任务在中途发生过暂停，而当前模型上下文长度有限，早期的指令被挤掉了。解决办法是在提交任务时把目标写得足够清晰完整，不要指望它从长对话中记住你的意图。我把任务描述当需求文档写：背景一句、目标一句、约束一句、输出格式一句。这样即使上下文丢了，任务本身还在。

6.2 MCP 工具调用超时，傻傻等

MCP 工具调用有时候会因为服务端卡住而超时，尤其是远程 HTTP 那种。现象是任务卡在一条工具调用上好几分钟没动静。我的排查思路是先分清楚是本地方有问题还是服务端有问题，本地的就用ps看看进程状态，远程的就测一下端点连通性。遇到高频超时的 MCP 服务器，我会干脆先禁掉它，优先确保主流程能跑完，之后再做工具本身的诊断。死磕一个不健康的工具会把整个任务拖垮。

6.3 权限引起的“工具可用但调用失败”

Pi 配置好 MCP 服务器、工具列表也显示加载了，但真正调用时却总报权限错误。这类问题十有八九出在 MCP 服务端进程本身没有对应目录或数据库的访问权限。特别是通过npx启动的服务端，它运行在当前用户的权限下，并不会因为你 Pi 是以管理员跑的，就自动获得所有文件系统的访问权。我的做法是：凡是要访问特定目录的 MCP 服务端，启动参数里显式把路径传进去，比如 filesystem 服务端要传--allowed-directory；涉及数据库的，检查一下连接串里的账号是不是真有表权限。

6.4 常见问题速查表

我把一段时间里遇到的高频问题整理成了一张表，方便日后照方抓药。

6.5 几个长期用了才明白的经验

最后分享几条我在这个版本上长期使用后才会明白的东西。第一，Durable 不是无限期的——有些任务跑太久容易被系统或调度器回收，重要任务隔一段时间看一眼比较稳妥，别等到要结果的时候才发现它早就没了。第二，MCP 工具给出的数据，Pi 在没有特别要求时只会当成参考，不会主动做二次校验；但如果你在描述里加上“用数据库结果和页面抓取结果交叉比对”，它会真的去核对。第三，模型的窗口长度决定了 Durable 任务能做多复杂，任务描述越精简，留给执行过程的空间越大，整体质量越高。

我个人的体会是，终端编程代理从“能对话”到“能干活”再到“能靠谱地独立干活”，中间隔着两样东西：一是能接入外部世界的能力，这就是 MCP 在做的事；二是不依赖人工盯守的执行能力，这就是 Pi Durable 在做的事。1.0 版本把这两块拼齐了，体验确实上了一个台阶。后面我准备再试试把它接入更复杂的 CI 场景，比如提交任务后自动触发构建、收集结果、生成变更说明。这种“AI 代理当执行者、人当验收者”的工作方式，我觉得会是接下来一段时间很值得深入探索的方向。