企业官网建设流程全解析

上周我把终端里的默认编程代理从 0.x 切换到了 Pi 1.0，起因很简单：我同时开着三个 MCP Server 跑一个跨文件重构任务，旧版本经常把工具调用的上下文搞乱，更糟的是任务跑到一半电脑自动重启，整个进度全部白费。Pi 1.0 正式发布，主打原生 MCP 和 Pi Durable，刚好都打在我这两个痛点上。

这篇文章不是为了复读官方发布说明，而是从我从旧版迁移过来、实际跑了几天之后的体验出发，把三件事说透：原生 MCP 支持到底改变了什么、Pi Durable 是怎么做到“断了还能续上”的，以及接入 MCP 生态时哪些坑是真坑。如果你正在用终端编程代理，或者在几个主流工具之间犹豫，这篇应该能帮你少走几天弯路。

1. Pi 1.0 这次发布，先把三个老大难摆上台面

1.1 终端编程代理这几年卡在了哪里

终端编程代理是个很有意思的品类：它不依赖 IDE，直接在命令行里运行，让 AI 自己读项目代码、跑测试、执行命令、改文件。相比 IDE 插件，它更轻、更容易脚本化，也天然适合放进 CI、容器、远程服务器这些没有图形界面的环境里。

但这个品类从“能跑通 Demo”到“能真正接活”，中间隔了三个老大难问题。

第一是上下文太脆。终端会话一旦关闭、终端窗口被误关、或者电脑重启，整个对话上下午就没了。下次启动要么重新描述一遍任务，要么把之前的结论粘贴回来。对于超过一小时的复杂任务，这种丢失几乎是致命的。

第二是工具接入太碎。你想让 AI 操作浏览器，得装一套浏览器自动化插件；想查数据库，又得配另一套连接器；想读设计稿、操作逆向工具、调用项目管理接口，每个都是单独适配。各家工具的自定义插件格式还不统一，换一个代理就要重新配一遍。

第三是长任务没有状态。跨 40 个文件的符号重命名、一次多阶段的数据迁移、跑一遍要半小时的回归测试加修复循环，这类任务一旦中途被打断，第二天你再问它“刚才进行到哪了”，它往往一脸茫然。你说你没保存，它也不知道该从哪里继续。

这三个问题单看都不算致命，但凑在一起，终端编程代理就只能停留在“改改小文件”的水平。Pi 1.0 这次把 MCP 和 Durable 做进核心层，本质上就是分别从“工具接入”和“任务状态”两个方向正面回应这些痛点。

1.2 Pi 1.0 给出的两个正面回应

先说原生 MCP。MCP（Model Context Protocol，模型上下文协议）这两年已经成了 AI 工具接入的事实标准，Playwright MCP、各类数据库 MCP、设计工具 MCP、逆向工具 MCP 都在往这个协议上靠。但“支持 MCP”和“原生支持 MCP”是两码事。Pi 1.0 是把 MCP 直接做进了代理主循环里，项目里放一份pi.jsonc，里面写好mcpServers，启动时自动发现、按需加载、错误原样透传，不需要再套一层自定义插件适配器。

再说 Pi Durable。这是一套面向长任务的持久化机制，它不只是把聊天记录存下来，而是把整个任务的事件流、工具调用结果、已改文件的追踪、当前计划进度都落盘。会话过程中断后，可以用pi resume找回，代理会基于保存的状态继续干活，而不是从头再来。

我拿到的 1.0 正式版里，这两个能力是默认开启并深度耦合的，项目级配置也支持得很好。接下来我把原理和实操分开讲。

2. 原生 MCP：从“每个工具一套接口”到统一协议

2.1 一句话讲清楚 MCP 是什么

如果你没接触过 MCP，可以把它理解成 AI 领域的“USB 接口”。USB 出现之前，鼠标、键盘、U 盘各有各的接口，你得为每个外设配不同的线。MCP 做的事就是统一：它定义了 AI 应用（host）和外部工具/数据源（server）之间如何描述能力、如何发起调用、如何返回结果。

一个 MCP Server 对外暴露三类能力：tools（可调用的函数，比如“打开网页”“执行 SQL”）、resources（可读取的数据，比如文件内容、表格）、prompts（可复用的提示词模板）。数据传输走 JSON-RPC，底层传输可以是标准输入输出（stdio），也可以是 HTTP/SSE。

所以你在热词里看到的 Playwright MCP、Figma MCP、IDA MCP、PostgreSQL MCP，本质都是同一个协议下的不同 Server。以前每接一个工具都是一套新集成，现在只要按 MCP 协议写好配置，理论上任何支持 MCP 的客户端都能复用。

2.2 原生支持与外挂适配器的本质区别

“支持 MCP”和“原生 MCP”的差别，我建议看四个维度：

我在旧版本里尝试过给 Pi 接第三方 MCP 适配器，最典型的问题是：MCP Server 里明明定义了一个新工具，适配器却没把它暴露给模型，因为工具列表是写死的。原生支持后，Pi 启动时会去询问每个 Server 的tools/list，工具增删立刻生效，这对工具生态快速演进的当下很重要。

2.3 在 Pi 里配置并跑通第一个 MCP Server

以 1.0 版本实测为例，全局配置放在~/.pi/config.json，项目级配置放在项目根目录的pi.jsonc。一个最基础的 stdio 传输的 MCP Server 配置长这样：

{ "mcpServers": { "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"], "env": { "PLAYWRIGHT_BROWSER_PATH": "/usr/bin/chromium" } }, "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"] } } }

配置好之后，用命令行管理：

pi mcp list pi mcp test playwright pi --mcp-server filesystem "把 /workspace/src/README.md 读给我，并总结结构"

pi mcp test是个值得养成的习惯。它会向 Server 发一个初始化握手，验证协议版本和工具列表是否正常。很多“工具没生效”的问题，在这一步就能暴露出来。

如果你的 MCP Server 走的是 HTTP 传输，配置里要特别注意baseUrl这个字段，而不是url：

{ "mcpServers": { "custom-http": { "transport": "http", "baseUrl": "http://127.0.0.1:3001/mcp", "headers": { "Authorization": "Bearer <token>" } } } }

提示：baseUrl必须包含完整的路径前缀，比如/mcp。只写http://127.0.0.1:3001经常会导致 404。这个字段也是社区里搜索“pi configure base url”的高频问题，后面第 5 节我会专门展开讲。

2.4 一个真实任务：让 Pi 开着浏览器干活

配好 Playwright MCP 之后，我做了个最简单的验证。给 Pi 下达指令：

用 playwright 打开一个本地页面，读取页面上所有 h2 标题，写入 /tmp/headings.md，然后用 filesystem 确认文件内容。

Pi 的处理过程大致是：先发现playwrightServer 下有browser_navigate、page_get_content这类工具，依次调用；把页面内容写入文件时，它又切换到filesystemServer 的写文件工具；最后读取确认。两个不同 MCP Server 的工具，在同一个任务里被统一调度，切换几乎是无感的。

这里我特意提一个热词场景：MCP 工具流式输出内容到文件。当工具输出特别长，比如 Playwright 抓回来的完整页面结构、数据库查询的几千行结果，直接塞进对话上下文很容易把模型的注意力稀释掉。我在 Pi 里会引导它把长输出重定向到文件：

pi --mcp-server playwright "抓取页面 console 日志，流式输出到 /tmp/console.log，然后只汇报摘要"

这样既保留了完整过程记录，又不会把上下文撑爆。原生 MCP 对这类场景的友好度，是插件时代比不了的。

3. Pi Durable：状态不丢，任务不白跑

3.1 Durable 到底在持久化什么

我一开始以为 Pi Durable 就是把聊天记录存下来，用了一天才发现它远比这个复杂。它持久化的是“任务的状态”，而不是“聊天的文字”。

具体来说包括四类：对话轮次和关键决策、工具调用的事件记录和结果摘要、工作区文件变更追踪（哪些文件被哪个工具改过、改成什么样）、以及代理内部的计划清单和待办进度。它类似一个事件日志：每完成一次工具调用，就形成一个可恢复的进度点，而不是定时做全量快照。

这个设计的好处是恢复粒度细。比如一个任务里改了 20 个文件，你在第 18 个文件处中断，恢复后代理知道自己推进到了哪里，而不是把前 18 个文件再改一遍。更聪明的部分在于它会对编辑操作做幂等处理，恢复时比对已应用变更的指纹，避免重复替换导致的内容错乱。

3.2 一次“干到一半崩溃”的恢复实测

我专门做了一次压力测试：让 Pi 对一个 C++ 项目做跨文件符号重命名，涉及 40 个文件，中间还穿插了几次编译和测试。任务跑到大约一半的时候，我直接杀掉了终端进程，模拟断电崩溃。

重新打开终端，执行：

pi durable sessions pi resume <session-id>

恢复后的表现让我印象深刻。它没有从头开始，而是先朗读了一段进度摘要：“已完成 23/40 个文件的替换；第 24 个文件尚未处理；上一次测试在第 19 个文件处报错，错误信息如下……”然后直接接着第 24 个文件继续。已完成的修改没有被重复应用，失败断点也定位准确。

这个体验和旧版本完全不同。以前遇到同样的情况，我连“做到哪了”都要靠 git diff 猜，更别说让代理记住失败原因。Durable 等于把“代理的短期记忆”升级成了“可持续的工程状态”。

3.3 什么任务适合开 Durable，什么任务别开

不是所有任务都需要 Durable，开之前先判断：

配置开关在项目级pi.jsonc里：

{ "durable": { "enabled": true, "storageDir": "~/.pi/durable" } }

存储目录建议单独指定，方便定期清理和备份。我个人的习惯是：只有要跑超过 20 分钟的任务才显式开启，短任务保持关闭，减少无谓的文件写入。

4. 和 Claude Code、Codex CLI 放一起比，Pi 1.0 的价值在哪

4.1 横向对比

用终端编程代理的人，基本都绕不开 Claude Code、Codex CLI、opencode 这几个名字。我把自己这几天的实测感受整理成一张表，供你参考：

再说一遍，这只是我的体感，不代表绝对优劣。Claude Code 在复杂架构理解上依旧很强，Codex CLI 和 GitHub 的联动是它独特的优势，opencode 在交互界面上更现代。Pi 1.0 的差异化在于：你用标准 MCP 配置就能把其他工具里攒下的 Server 生态直接搬过来，再加上 Durable 对长任务的支撑，这是它和其他工具拉开差距的地方。

4.2 我切换主力工具的三点理由

第一，MCP 配置不用重写。我之前在别的工具里调的 Playwright MCP、文件系统 MCP、PostgreSQL MCP，迁移到 Pi 1.0 就是把同一份mcpServers配置复制过来，字段名、参数结构完全一致，这个迁移成本几乎为零。

第二，Durable 正好匹配我的工作流。我日常有大量半小时以上的重构和迁移任务，过去最怕中途被打断，现在可以放心让任务挂着跑，断了也能续上。这种安全感以前只有 CI 系统能给，现在终端代理也给了。

第三，它在资源占用上很克制。不应答时基本不占内存，没有 Electron 壳，在服务器和容器里跑很干净。对于我这种常常 SSH 到远程机器上干活的人来说，这个优点很实在。

当然，如果你主要做的是几十分钟内的深度对话式编程，不一定需要换；但如果你和我一样被长任务折腾过，Pi 1.0 值得在你机器上跑两周试试。

5. 接入 MCP 生态时最容易踩的坑（附排查思路）

5.1 Server 拉起失败：先查命令和 PATH

MCP 接入最常见的失败，不是协议问题，而是进程根本没拉起来。现象是配置完pi mcp test直接报spawn npx ENOENT，或者 Server 启动后秒退。

根因通常是 PATH 不对。Pi 如果是从图形界面启动的，继承到的环境变量和你在终端里看到的可能完全不一样，npx、node的路径找不到。解决办法是在 Server 配置里显式指定 PATH：

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

另外，npx -y第一次运行要下载包，慢的话容易触发超时。排查时先手动在终端跑一遍 Server 启动命令，确认退出码和报错信息，再回来看配置。Windows 上还要注意用npx.cmd而不是npx。

5.2 base URL 配错导致的连接失败

就是热词里那个“pi configure base url”的高频问题。HTTP 传输的 MCP Server，最常见的三个错误是：字段名写错、路径没带全、本地地址的 IP 版本不对。

字段名我再说一次，是baseUrl，不是url。很多从旧项目拷来的配置写的是url，Pi 解析不到，直接用默认的 stdio 去连，结果自然是连接失败。

路径问题也很常见。Server 实际监听/mcp，你只写了http://127.0.0.1:3001，请求全 404。排查时可以先用 curl 直接验证：

curl -X POST http://127.0.0.1:3001/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

有正常 JSON-RPC 返回，说明 Server 没问题，问题在 Pi 的配置；没返回，先去查 Server 本身的监听地址和端口。最后提醒一下：localhost在部分机器上会解析到 IPv6 的::1，而 Server 只监听了 IPv4，这时换成127.0.0.1往往立刻见效。

5.3 工具一多，上下文就爆了

这是 MCP 重度用户最容易忽略的隐性成本。每个 Server 启动后，Pi 都要把它的工具定义读进上下文：工具名、描述、参数 Schema，一个复杂的 Server 动辄几千 token。挂 10 个 Server，光工具介绍就能吃掉一大截上下文，模型实际用来思考的窗口被严重压缩。

我的处理原则是“少量按需”。全局配置只保留两三个核心 Server，其余放进项目级pi.jsonc，按项目加载。临时需要某个 Server 时，用命令行参数单独挂载：

pi --mcp-server pg "列出 users 表结构"

如果某个 Server 工具特别多，还可以尝试在配置里做工具过滤，只暴露必要的几个，大幅降低上下文占用。长输出继续沿用第 2 节说的“流式输出到文件”策略，别让大段内容长期停留在对话窗口里。

5.4 Durable 的存储占用与隐私边界

Durable 便利的背后是磁盘代价。长任务的工具调用结果、文件变更摘要会持续追加写入事件日志，跑一整天的大任务，存储目录可能膨胀到几百兆。建议养成清理习惯：

pi durable prune --days 7

隐私方面要拎清楚：Durable 会把工具调用结果摘要落盘，如果任务涉及敏感的生产数据、客户信息，要么别开 Durable，要么把storageDir指向一个加密盘。另外，不建议把 Durable 存储目录提交进 git，也不要在里面放任何凭据。

5.5 权限控制与安全底线

最后说安全。MCP Server 跑起来之后，它的权限和当前用户是一样的：能读你的文件、能执行命令、能访问网络。一个被投毒的 MCP Server，完全可以借着“给 AI 提供能力”的名义干坏事。

我的底线规则有三条：第一，只装来源清晰、更新频率正常的 Server，优先用固定版本而不是@latest，避免供应链漂移；第二，配置里涉及 token 的地方，尽量用环境变量引用，不把明文写进pi.jsonc；第三，对要开放的目录和数据库权限做最小化设置，给文件系统 Server 指定工作目录范围，而不是放一个根目录权限。

提示：任何声称“免配置、全自动接入所有工具”的 MCP Server，都值得多留个心眼。协议的便利性是把双刃剑，权限该收紧还是要收紧。

我在实际使用中还有个习惯是“先小后大”：新接入一个 MCP Server，先在临时目录里跑一个最小任务验证它只调用了预期的工具，再放进正式项目。这套流程看起来费事，但比事后排查供应链问题便宜得多。