企业官网建设流程全解析

终端编程代理这个赛道的更新速度，这两年真的快。从早先只能在预设命令里打转，到现在能自己规划任务、调用工具、改代码跑测试，变化完全是另一个物种。最近 Pi 1.0 正式发布，核心就两个关键词：原生 MCP 和 Pi Durable。前者解决的是"代理怎么接外部工具"的问题，后者解决的是"代理记不住事"的问题。这篇文章，我想从实际使用的角度把这两个功能拆开讲清楚，也会把升级过程中遇到的坑和排查思路一并分享。适合正在用终端编程代理、或者正打算把手上的 AI 编码工具从"聊天对话"升级成"真正干活的助手"的开发者。

1. Pi 1.0 为什么值得关注：终端编程代理的三个老毛病

1.1 工具链割裂：代理接不到工具，AI 就只是个高级聊天框

很多人第一次用终端编程代理的时候都会有个疑问：它跟网页版 AI 聊天有什么区别？区别当然有，但如果你只把它当聊天框用，你会发现很多任务它做不了。原因不是模型能力不行，而是它没有工具。

在终端里写代码，真正高效的流程一定是：代理能帮你查目录、读文件、搜代码、跑测试、看报错、改完再跑。这些能力，过去都是靠代理内置的一堆固定命令实现的。你让它做什么，它就用那十几个内置函数去应付。一旦你手头用到的工具不在这十几个函数里——比如你想让它操作一个网页、查一下线上数据库、或者调用一个内部服务的接口——就很尴尬了。你可以把命令贴给它让它生成命令，但它没法"直接"看到结果，更没法自动根据结果决定下一步。

这就是工具链割裂的问题。AI 是 AI，工具是工具，中间隔着一道需要人肉搬运信息的墙。我见过不少团队把这种半残状态的代理硬当生产力工具用，结果大部分时间都在把代理生成的命令复制到另一个终端里手动跑，再把输出贴回去告诉它结果。这么一来一回，效率反而比直接自己干还低。Pi 1.0 选择把 MCP 做成原生的，本质上就是在拆这道墙。

1.2 上下文不持久：改到一半，代理失忆了

第二个老毛病是上下文丢失。终端编程代理跑起来以后，它的上下文都存在内存里。你让它分析一个项目的代码结构、找到问题、写出修改方案，它做了一半，你在另一个窗口开了个服务，切回来的时候不小心把它重启了——好，之前所有分析全部作废。你得从头开始再描述一遍项目背景、再贴一遍报错日志。

如果只是聊天重新开始也就算了，问题是它还经常是"断点续传"式的丢失。比如你明明已经让它改了三个文件，重启之后它只记得前两个，第三个忘了，然后自作主张从某个中间状态开始继续改。这种"改到一半的代理"比完全不改还危险，因为它会让你相信代码已经按预期改完了，实际上并没有。

长任务的场景更严重。一个跨天的代码重构、一个多步骤的数据迁移，只要是超过单次会话边界的，用普通终端代理基本都做不了。不是模型能力不够，而是它压根记不住昨天你们聊到什么程度了。这也是为什么我特别看重 Pi Durable 这个功能，后面会细说。

1.3 决策过程不透明：出了问题你都不知道它干过什么

第三个问题比较隐性，但用久了你会发现它特别要命：代理的决策过程没有记录。普通聊天式对话里，你至少还能往上翻翻聊天记录，看看之前让它做过什么。但在终端里执行的那些命令、改过的那些文件、调过的那几个接口，很多都没有沉淀下来。出了问题想复盘，只能靠回忆，运气好点能翻到 shell 历史。

这三个问题，其实互相纠缠。工具接不上，你就会手工搬运信息，搬运的过程又切断了上下文的连贯性；上下文不持久，你就没法放长任务去跑；没有记录，就算跑完了你也不敢完全信任结果。所以我说 Pi 1.0 的发布值得关注，不是说它加了两个新功能，而是这两个新功能正好打在以上三个痛点上：原生 MCP 打通工具链，Pi Durable 解决持久化与可追溯，配合起来，终端编程代理才有资格谈"生产力"。

2. 原生 MCP 支持：给代理装上万能插座

2.1 MCP 到底是什么，为什么要用协议去接工具

MCP，Model Context Protocol，模型上下文协议。你要理解它，不需要去啃协议规范文档，只需要记住一句话：MCP 做了一件事——把"AI 应用如何调用外部工具"这个事标准化了。

在 MCP 出现之前，每个 AI 应用接工具都是各搞各的。Agent 自己实现一套工具调用机制，想接一个浏览器自动化工具，就得写一套桥接代码；想再接一个数据库工具，又要写一套。工具方更痛苦，同一个工具要在不同的 AI 应用里用，就要为每个应用分别做适配。这就像每个手机品牌都有自己的充电接口，你得出门带一堆线。

MCP 相当于统一成了 USB-C。它定义了三个角色：MCP Host（宿主，就是我们的 AI 应用）、MCP Server（工具提供方）、MCP Client（Host 内部用来与 Server 通信的组件）。工具方把能力封装成 Server，暴露成一个个"工具"（tool），AI 应用只需要实现同一个协议，就能发现和调用这些工具。这就是为什么你现在看各种工具都在往 MCP 靠：Playwright MCP 把浏览器自动化封装成工具，数据库、地图、项目管理平台都在做各自的 MCP Server。就连 IDA 和 x32dbg 这类调试器，现在也有对应的 MCP 插件。生态一旦形成，接入的成本就急剧降低。

2.2 Pi 的"原生 MCP"和"装个插件接 MCP"有什么不同

标题里特意写"原生 MCP"，说明这里是有讲究的。很多工具说自己支持 MCP，其实是打了个擦边球：你装一个第三方插件，插件里面内置了一个 MCP 客户端，然后 AI 应用跟这个插件通讯。问题是这种间接层会带来接口不稳定、配置分散、错误信息不透明等各种麻烦。

Pi 的原生 MCP 是另一个层面的支持。Pi 自己就是 MCP Host，启动的时候直接读取 MCP 配置文件，拉起配置里的 Server 进程或连接远程地址，自动发现工具清单并合并到代理的可用工具列表里。对用户来说，少了一层中间进程，排错路径变得非常直接：Pi 日志能看到它启动了哪个 Server，哪些工具注册成功了，哪些失败了，原因是什么。对于我这种不喜欢黑盒的人来说，这是天大的加分项。

另外一个很实际的差异是能力边界。第三方插件桥接的方式往往只支持配置一两个固定的 Server，而且不会在系统提示词里动态管理工具能力的增减。原生 MCP 则可以让代理在每一轮决策的时候，根据任务需要动态挑选和加载工具描述，既不会把所有工具描述全塞进上下文浪费 token，又能保证需要的时候工具随叫随到。

2.3 实操：从零给 Pi 接上一个 MCP Server

MCP Server 的运输方式主要有两种，一种是本地进程用 stdio 通信，另一种是远程服务走 HTTP/SSE。配置上并没有多复杂，Pi 会在~/.pi/config.json里找全局的 MCP 配置，也会读取项目根目录下.pi/mcp.json的项目级配置，后者优先级更高。

拿最常见的 Playwright MCP 举例，你要让 Pi 能操作浏览器，只需要在.pi/mcp.json里加上一段：

{ "mcpServers": { "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"], "env": { "PLAYWRIGHT_BROWSERS_PATH": "/usr/bin" } } } }

如果你要接的是一个跑在远端机器上的 MCP 服务，比如团队内部搭的数据库查询服务，那配置更简单：

{ "mcpServers": { "team-db": { "url": "http://192.168.1.100:8000/mcp" } } }

配好之后，跑一下pi mcp list，Pi 就会拉起来并列出所有发现的工具。看到 playwright 下面出现browser_navigate、browser_click、browser_snapshot这些名字，就说明接入成功了。之后你直接用平时说话的方式让 Pi 干活就行，比如"打开 localhost:3000，把首页的标题取出来"，Pi 会自动选择合适的工具去执行，不需要你手动指定调用哪个。这个"自动选工具"的能力很关键，它意味着工具调用不是你在命令里写死的，而是代理根据你的目标和当前上下文动态决定的。

这里有个小技巧：如果你改了配置但工具没出现在清单里，先跑pi mcp list --refresh强制重新拉起 Server。我遇到过几次改完配置不生效的问题，基本都是因为 Pi 复用了旧的 Server 进程，refresh 一下就好。

2.4 三个我实测过的高性价比 MCP 用法

第一个是 Web 自动化调试。前端的同学应该能体会，改页面样式、复现用户报障，全靠手动开浏览器太折磨了。我把 Playwright MCP 接进来之后，直接让 Pi 打开目标页面，截图给我看，再把浏览器 console 的报错抓回来分析。整个闭环都在终端里完成，不用来回切换窗口，效率提升非常明显。

第二个是数据库操作。团队内部如果有一个 Postgres 的 MCP Server（现在网上有很多开源实现），你可以让 Pi 直接查表结构、跑查询、甚至生成迁移脚本。这个场景下 MCP 的价值尤其突出，因为代理不需要你告诉它数据库长什么样，它自己通过工具去"看"，然后基于真实结构做判断，而不是靠训练数据里的过时印象瞎写。

第三个是文档与代码的交叉检索。有一些文档型 MCP Server，能把项目 Wiki 或内部规范变成可检索工具。当代理写到一个跟已有约定相关的逻辑时，它会主动去检索文档确认规范。这一点在规范严格的项目里特别有用，等于把团队的隐性知识显式地喂给了代理。

3. Pi Durable：让代理从"聊天机器人"变成"长期同事"

3.1 Durable 到底做了什么：普通会话 vs 持久化会话

Pi Durable 这个名字，"Durable"本身就把意图说完了：持久的、耐用的。普通终端代理的上下文就是一段会话内存，进程退出即清零。而 Durable 是把整个任务状态——包括目标的定义、当前进展、执行过的步骤、工具调用的输入输出、文件变更记录——以一种可恢复的形态落到磁盘上。

你可以把它理解成一个"带断点续传的日志系统"。Pi 每做一步决策和执行，都会把关键事件追加到本地的事件流里，同时定期生成状态快照。恢复的时候，Pi 会加载最近的快照，再重放在那之后的事件，把状态还原到中断前的样子。这种设计比直接全量保存内存快照更优雅，因为快照不用频繁生成，也不会因为保存带来明显的性能开销。

这个跟传统的聊天记录保存完全是两码事。聊天记录保存的是对话历史，恢复回来顶多是让你把上下文贴回去。Durable 还原的是整个执行状态：代理知道自己打算干什么、已经干到什么程度、下一步要干什么，甚至清楚自己已经调用过哪些工具、拿到过什么结果。它恢复后的行为和中断前是一致的，就像代码调试里的断点恢复，而不是重头跑一遍。

3.2 我为什么觉得 Durable 是 1.0 最被低估的能力

从宣传角度看，原生 MCP 显然更吸引眼球，大家一窝蜂去试各种工具。但真正改变日常使用体验的，我认为是 Durable，因为它把"代理能用"升级成了"代理信得过"。

举一个真实的场景。我接手了一个老项目的重构，涉及十几个模块，跨了大概三天。以前用终端代理，这个事根本没办法交给它从头到尾干，因为第二天上班我发现它已经把上下文丢了。有了 Durable 之后，我可以每天下班让它把进度存下来，第二天回来一句pi resume --session survey-refactor，它就能接着昨天的进度继续。它会告诉我昨天分析到哪个文件、今天的计划是什么，而不是茫然地看着我问"好的，你想让我做什么？"

还有一次，我在让 Pi 跑一个批量数据清洗任务的时候，中午办公室断电了。以前这种情况下整个任务就得从头再来，那天我重新打开终端，pi resume之后它竟然从断掉的那一条记录开始继续处理，已经完成的批次它明确告诉我"已完成，跳过"，然后接着往下走。那个时刻我是真的觉得，这个工具具备生产力属性了。

Durable 还顺带解决了一个信任问题。因为所有决策和执行都有记录，我可以随时查看代理在某一步为什么这么做。团队里用 Pi 的时候，这个记录也能用于审计：谁在什么时候让代理执行过什么命令，结果如何。这对非单人环境非常重要。

3.3 Durable 与 MCP 的组合：持久化 + 工具调用才算完整闭环

如果只把 Durable 当成会话恢复，那还是低估了它。它跟 MCP 组合起来，才能构成完整的终端代理体验。为什么这么说？因为工具调用是最容易出现"状态断点"的地方。

举个例子。我让 Pi 调用 Playwright MCP 跑一整轮核心流程的 E2E 测试，每跑完一步它都会记录下这一步的操作结果。跑到第 27 步的时候网络断了，Server 进程挂掉。等我重连以后，普通情况下代理会怎么办？它会发现浏览器没了、上下文里的中间结果残缺，然后就懵了。但有了 Durable，Pi 恢复时会知道"我执行到第 27 步，这一步的输入是 XX，预期的输出是 YY，但尚未确认"，于是它会重新拉起 MCP Server，从第 27 步重试，而不是从头跑到 27。这在长工具链任务里，省下来的不只是一点点时间。

另外一个组合玩法是"多阶段任务编排"。比如让 Pi 先通过数据库 MCP 拉取一份用户清单，再调用 HTTP 工具访问业务接口，最后写一份分析报告。整个编排过程的输入输出都在 Durable 的事件流里，中间任何一步出错，都能定位到具体环节。排查问题从"猜它干了什么"变成了"看它干了什么"。

4. 从 0.x 升级到 1.0：迁移、配置与踩坑记录

4.1 安装与升级：半小时内的平滑切换

先明确一个前提：如果你是第一次装 Pi，直接装 1.0 就行，不用关心迁移。但如果你跟我一样从 0.x 时代就在用，升级前我建议你先看一眼这节。

安装动作很简单，用 npm 或者 brew 都行：

# npm 方式 npm install -g pi@latest # macOS / Linux 用 brew brew install pi

装完先跑pi --version确认一下，看到pi 1.0.x就说明升级成功了。如果之前是用某种 alias 方式调用的老版本，还需要检查一下 shell 里是不是有旧的 alias 把新命令挡住。

升级后 Pi 一般会自动把旧的配置文件迁移到新格式，但自动迁移不总是完美。我喜欢在升级前手动把~/.pi/整个目录备份一份，这样即使迁移出了问题，也能从容回滚。

4.2 配置变化：MCP 配置从哪来到哪去

0.x 里如果你已经用过 MCP，配置位置可能在~/.pi/mcp.json或者散落在各个项目目录里。1.0 的标准是：全局配置在~/.pi/config.json的mcpServers字段，项目级配置在.pi/mcp.json。自动迁移一般会把旧的拆散文件合并到这个标准位置。

我自己踩过的一个坑是：当时项目目录里有个旧格式的.pi/mcp.json，里面还写着很多历史 Server，但升级后 Pi 会优先读这个项目级配置，而且它不会再去兼容旧字段。结果就是我在全局配好的新 Server 在项目里不可见，排查了半天才发现是项目级配置优先级的问题。解决办法很简单，把项目级配置清理干净，只留真正当前要用的 Server。

4.3 任务状态迁移：旧的 durable 会话怎么办

如果你之前已经用过 Durable 的测试版，1.0 的会话存储格式可能有变化。官方给出的迁移方案一般是在升级时自动执行，但为了保险起见，我在升级前会把~/.pi/durable/目录也备份了。升级后先不要急着删旧文件，跑一次pi session list，看看历史会话是否还在。如果全部消失，不要慌，可以直接从备份目录里恢复；如果部分丢失，通常是新版本在某些事件凭据的兼容上出了问题，把旧目录手动映射进去即可。

这个细节没多少人提，但我觉得值得留意：Durable 的存储文件本质上是文本协议格式（早期版本是纯 JSON 行），所以就算官方的自动迁移失败，你也能手动把里面的关键信息捞出来。

4.4 1.0 稳定性与性能上的体感变化

我用 1.0 正式版跑了一段时间，最直观的变化是长会话的上下文管理明显更好了。0.x 时期到了后期会出现响应变慢、经常要手动清理上下文的情况；1.0 对上下文窗口的分层管理做了一些优化，能让短期的工具结果和长期的会话目标分开放置，不需要频繁触发压缩。

另一个细节是流式输出的稳定性。之前跑长任务，偶尔会遇到输出中断，但任务还在后台执行的情况，很困惑。1.0 里代理的输出和实际执行进度做了更严格的同步，输出中断基本等同于执行中断，这对于我判断"它到底干完了没有"很重要。

性能上没有什么奇迹，毕竟模型推理的时间占了大头，但在工具调度和状态读写这些工程环节，体感上是明显更轻快了一些。

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

5.1 MCP Server 起不来，第一件事查什么

遇到 MCP 工具全部消失或部分消失，我建议按以下顺序排查，别慌：

先确认配置格式正确。配置里最常见的错误是args写成了字符串而不是数组，这是新手最容易犯的问题。再用pi mcp list看 Server 的启动状态，如果显示 failed，查看 Pi 日志。本地进程方式的 Server 启动失败，九成是命令不存在；比如你没有全局安装 npx，或者 Server 包没下载成功，就会看到类似ENOENT的错误。

还有一类问题是环境变量。很多 MCP Server 在不同机器或平台上的路径和 token 不一样，需要你在配置的env字段里正确传递。我见过有人把 API key 写在命令行里，结果还能被 shell 历史记录下来，那就属于安全隐患了。正确做法是把敏感信息放到环境变量里，然后在配置的env里引用。

5.2 Durable 恢复不了，怎么最大程度找回

如果你发现pi resume之后代理的状态跟预期不符，先区分是"没有恢复"还是"恢复了个旧状态"。没有恢复大概率是会话 ID 的问题，用pi session list确认你恢复的会话确实是中断的那一个。恢复了个旧状态则多半是快照和事件流没有写全，比如断电瞬间的状态丢失。

这类问题没有完美的补救方案，但是有个经验可以减少损失：把 Pi 的 Durable 存储目录放到一个独立的、支持崩溃安全的文件系统上，并且在重要的长时间任务执行前，手动做一次pi durable checkpoint。这个命令会立即生成一个快照，让恢复点离中断点更近。

5.3 常见问题速查表

我把我最常碰到的几个问题整理成一张速查表，方便你遇到问题时直接对照。

特别提醒：MCP 配置里涉及密钥、token 的内容一定要走环境变量，不要明文写在.pi/mcp.json里。这个文件很可能会被提交进代码仓库，明文密钥一旦入库，后果就是泄漏。

5.4 关于 MCP 生态的一个建议

最后给想深入用 MCP 的朋友一个建议：不要一次接太多 Server。MCP 工具链的威力在于"按需调用"，但如果你的配置里堆了三十个 Server，代理每一轮决策都要从工具清单里去挑选，不仅慢，而且可能选错工具。我个人的习惯是，长期只留两三个高频 Server 在全局配置，其他按项目挂到项目级配置里，等真正需要的时候再启用。这个做法让 Pi 的响应速度和准确性都保持在一个好的水平。

我自己的体会是，Pi 1.0 里原生 MCP 是那个让你"可以做到很多事"的功能，而 Pi Durable 是那个让你"敢把事交给它"的功能。两者加在一起，终端编程代理才算真正迈过了从玩具到工具的那道坎。很久以前大家讨论终端代理，纠结最多的是模型能力，现在模型能力已经不是瓶颈了，反而是工程能力——工具的连接、状态的持久化、决策的可追溯——决定了这类工具能走多远。如果你还没上手，我建议你从一个小任务开始：给它接一个 Playwright MCP，然后让它跑一遍你项目里最常点的那个用户流程。等你能放心让它跑完一个跨会话的长任务，你会回来感谢 Durable 的。