企业官网建设流程全解析

1. 这次升级到底改了什么：从"能跑"到"敢用"的分水岭

终端编程代理这个概念，前两年还停留在"玩具"阶段——你让它改个函数，它能把整个文件重写一遍；你让它跑个测试，它把依赖装到系统 Python 里去了。Pi 1.0 这次发布，我盯了几天实测下来，最大的感受是：它终于从"演示品"跨到了"生产工具"的门槛上。核心就两件事——原生 MCP和Pi Durable。前者解决的是"代理能不能接上你现有的工具链"，后者解决的是"代理干到一半崩了怎么办"。这两个问题不解决，终端代理永远只能做 demo。

先说清楚这篇文章适合谁看。如果你是把 AI 代理当聊天玩具的，这篇可能有点硬；如果你是那种每天在终端里泡着、想让代理真正帮你跑构建、改配置、查日志、写脚本的人，那这篇就是给你写的。我会把 MCP 的接入逻辑、Durable 的状态持久化机制、以及我在实际项目里踩过的坑，全部摊开讲。不堆概念，只讲怎么落地。

MCP全称 Model Context Protocol，你可以把它理解成"代理和外部世界之间的 USB-C 接口"。在 Pi 1.0 之前，你想让代理读个数据库、调个内部 API、操作一下浏览器，得自己写胶水代码，每个工具一套适配，改一次接口全崩。原生 MCP 的意思是，Pi 现在把这套协议做进了内核，任何符合 MCP 规范的服务端，插上就能用。这不是"支持了一个新特性"，而是把代理的能力边界从"文件系统 + shell"扩展到了"任何你能封装成 MCP 服务的东西"。

Pi Durable则是另一个维度的东西。终端代理最怕什么？跑到第 17 步，网络抖了一下，或者你自己手贱 Ctrl+C 了，前面 16 步的上下文全丢，重来一遍还得重新理解你的意图。Durable 做的是把代理的执行状态——包括任务分解、中间产物、工具调用记录——持久化下来，中断后能从断点续上。听起来简单，但实现起来涉及状态快照、幂等重放、副作用隔离一堆问题。Pi 1.0 敢把它作为正式特性放出来，说明这套机制已经过了内部足够多的验证。

我个人的判断是，这两个特性叠加起来，Pi 1.0 的定位就从"终端里的 AI 助手"变成了"可编排的终端自动化引擎"。区别在于：助手是你问一句它答一句，引擎是你给它一个目标，它自己拆解、执行、遇错重试、断点续传。这个定位的转变，才是这次发布真正值得聊的地方。

2. 原生 MCP 到底怎么接：从协议到实操的完整链路

2.1 MCP 的核心抽象：为什么是这三个概念

MCP 协议本身不复杂，核心就三个抽象：Resources（资源）、Tools（工具）、Prompts（提示模板）。很多人第一次看会懵，觉得这不就是 API 吗，为什么要重新发明一套。我一开始也这么想，直到自己写了一个 MCP 服务端之后才明白，这套抽象是专门为"代理消费"设计的，和给人用的 API 有本质区别。

Resources 是只读的上下文来源，比如一个数据库的 schema、一个项目的目录结构、一份配置文件的当前内容。代理在执行任务前，会先拉取相关 Resources 来建立"世界认知"。Tools 是可调用的动作，比如"执行 SQL 查询"、"发送 HTTP 请求"、"写入文件"。Prompts 则是预定义的提示模板，让代理在特定场景下按最佳实践来组织语言。

为什么这个区分重要？因为代理的决策逻辑是：先看有哪些 Resources 可以了解现状，再决定调用哪些 Tools 来改变现状。如果你把所有东西都塞进 Tools，代理会分不清"读取信息"和"执行动作"，容易做出危险操作。我见过一个反例，某开发者把"读取生产数据库"也做成了 Tool，结果代理在排查问题时顺手调了一下，虽然只是读，但触发了全表扫描，把线上库拖慢了。Resources 和 Tools 分离，本质上是在协议层面给代理划了一条"观察"和"干预"的界线。

2.2 在 Pi 1.0 里配置一个 MCP 服务端

Pi 1.0 的 MCP 配置走的是声明式路线，配置文件放在~/.pi/mcp.json（不同平台路径略有差异，Windows 下在%APPDATA%\pi\mcp.json）。结构大致是这样：

{ "servers": { "project-db": { "command": "node", "args": ["/path/to/mcp-db-server/index.js"], "env": { "DB_CONNECTION": "postgres://localhost:5432/devdb" }, "resources": ["schema", "migrations"], "tools": ["query", "explain"] }, "internal-api": { "command": "python", "args": ["-m", "mcp_api_server"], "env": { "API_BASE": "http://localhost:8080" } } } }

这里有几个关键点，我逐个拆。command和args是启动 MCP 服务端的进程命令，Pi 会在启动时把这些服务拉起来，通过 stdio 通信。这意味着你的 MCP 服务端不需要暴露网络端口，安全性上省心不少。env是传给服务端的环境变量，敏感信息比如数据库连接串放这里，不要硬编码在服务端代码里。

resources和tools字段是可选的过滤配置。如果你只想让代理用某个服务端的部分能力，可以在这里白名单。我强烈建议在生产环境里用这个过滤，尤其是那些既有读又有写能力的服务端。比如一个数据库 MCP 服务，开发环境可以放开query和write，生产环境只放query和explain，写操作直接不给代理。

注意：MCP 服务端的启动是懒加载的，Pi 不会在启动时把所有服务都拉起来，而是在第一次需要用到某个服务时才启动。这个设计对资源占用友好，但意味着第一次调用会有几百毫秒的冷启动延迟。如果你对延迟敏感，可以在配置里加"preload": true强制预加载。

2.3 自己写一个 MCP 服务端：最小可用示例

官方 SDK 覆盖了 TypeScript、Python、Go 几个主流语言。我用 Python 写一个最小的"文件搜索"服务端，让你看清整个结构：

from mcp.server import Server from mcp.types import Resource, Tool, TextContent import os import fnmatch app = Server("file-search") @app.list_resources() async def list_resources(): return [ Resource( uri="file://workspace", name="workspace", description="当前工作目录的文件列表", mimeType="text/plain" ) ] @app.read_resource() async def read_resource(uri: str): if uri == "file://workspace": files = [] for root, dirs, filenames in os.walk("."): dirs[:] = [d for d in dirs if not d.startswith('.')] for f in filenames: files.append(os.path.join(root, f)) return TextContent(type="text", text="\n".join(files[:500])) @app.list_tools() async def list_tools(): return [ Tool( name="search_files", description="按 glob 模式搜索文件", inputSchema={ "type": "object", "properties": { "pattern": {"type": "string", "description": "glob 模式，如 *.py"} }, "required": ["pattern"] } ) ] @app.call_tool() async def call_tool(name: str, arguments: dict): if name == "search_files": pattern = arguments["pattern"] matches = [] for root, dirs, filenames in os.walk("."): dirs[:] = [d for d in dirs if not d.startswith('.')] for f in filenames: if fnmatch.fnmatch(f, pattern): matches.append(os.path.join(root, f)) return [TextContent(type="text", text="\n".join(matches[:100]))] if __name__ == "__main__": app.run()

这个服务端暴露了一个 Resource（工作目录文件列表）和一个 Tool（按模式搜索文件）。代理在需要了解项目结构时会读 Resource，在需要找特定文件时会调 Tool。注意read_resource里我限制了返回 500 个文件，call_tool里限制了 100 个匹配——这是血的教训。代理拿到超长列表后，会把它塞进上下文，token 消耗爆炸，而且它自己也抓不住重点。给代理的数据，永远要截断和摘要，不要原样丢过去。

2.4 MCP 接入后的能力边界变化

接上 MCP 之后，Pi 能做的事情范围变化有多大？我列个对比表，你感受一下：

这个表里最关键的一行是最后一行。没有 MCP 的时候，代理获取上下文是被动的——它得先猜哪个文件相关，然后去读。有了 MCP，服务端可以主动告诉代理"这里有一份 schema 你可能需要"。这个从"拉"到"推"的转变，对代理的任务规划质量影响巨大。我实测下来，同一个任务，有 MCP 上下文推送的情况下，代理的首次尝试成功率大概能提升三成左右。

3. Pi Durable 的持久化机制：断点续传是怎么做到的

3.1 状态快照的粒度设计

Pi Durable 的核心是执行状态快照。但"快照"这个词很模糊，快照什么？多久快照一次？快照存在哪？这些设计决策直接决定了 Durable 好不好用。

Pi 1.0 的快照粒度是步骤级，不是 token 级也不是会话级。所谓步骤，是代理执行计划里的一个原子动作——比如"读取 config.yaml"、"运行 pytest"、"修改 main.py 第 42 行"。每完成一个步骤，Pi 就把当前状态写一次盘。状态内容包括：任务目标、已完成步骤列表、每步的输入输出、当前上下文摘要、以及一个指向工作区文件状态的引用。

为什么是步骤级？token 级太频繁，写盘开销扛不住；会话级太粗，中断后等于重来。步骤级是个平衡点，既能在中断时保留足够的进度，又不会因为频繁写盘拖慢执行。我实测一个中等复杂度的任务（大概 20 到 30 个步骤），快照带来的额外开销在总执行时间的 5% 以内，可以接受。

快照存储默认在~/.pi/durable/<session-id>/下，每个步骤一个 JSON 文件，外加一个manifest.json记录步骤顺序和依赖关系。这个设计的好处是，你可以手动去看某个步骤的快照，排查代理当时到底看到了什么、做了什么决策。我排查过几次代理"莫名其妙"的行为，最后都是靠翻快照找到原因的——它当时读到的文件内容和我以为的不一样。

3.2 断点续传的触发与恢复流程

Durable 的恢复有两种触发方式：自动和手动。自动是 Pi 检测到上次会话异常退出（比如进程被 kill、机器重启），下次启动时提示你是否恢复。手动是你自己执行pi resume <session-id>。

恢复流程分三步。第一步是状态重建：Pi 读取 manifest，按顺序加载各步骤快照，重建出中断时的上下文。第二步是工作区校验：检查工作区文件是否和快照记录的一致。这一步很关键，因为如果你在中断期间手动改了文件，直接恢复会导致代理的认知和实际不符。Pi 的做法是对比文件哈希，不一致的会标记出来，让你决定是"以工作区为准"还是"以快照为准"。第三步是幂等重放：从最后一个未完成步骤继续执行。

这里有个设计细节值得说：Pi 对每个步骤都标记了幂等性。读操作、查询操作默认幂等，重放安全；写操作、外部调用默认非幂等，恢复时会先检查该步骤是否已经产生副作用。比如"发送邮件"这个步骤，如果快照显示它已经执行过，恢复时会跳过，不会重复发。这个机制依赖 MCP 服务端在 Tool 定义里声明幂等性，所以你自己写 MCP 服务端时，一定要如实标注。

提示：如果你写的 Tool 有副作用但没标非幂等，Durable 恢复时可能会重复执行。我踩过这个坑——一个"创建工单"的 Tool 没标非幂等，恢复后创建了两张重复工单。后来在 Tool 的 inputSchema 里加了"idempotent": false才解决。

3.3 快照的清理与存储管理

Durable 的快照不会自动删除，这是把双刃剑。好处是你随时可以回溯历史会话；坏处是磁盘会被慢慢吃满。一个 30 步的任务，快照大概占 2 到 5 MB，取决于每步的上下文大小。如果你每天跑几十个任务，一个月下来就是几个 GB。

Pi 提供了pi durable prune命令来清理，支持按时间、按大小、按会话状态过滤。我的习惯是保留最近 7 天的所有快照，7 天以上的只保留失败会话的快照（用于排查），成功的直接删。配置可以写在~/.pi/config.json里：

{ "durable": { "retention": { "successful": "7d", "failed": "30d", "maxTotalSize": "5GB" } } }

maxTotalSize是硬上限，超过后会从最旧的开始删，不管保留策略。这个兜底很重要，防止某个异常任务产生超大快照把盘撑爆。我遇到过代理陷入循环，一个步骤反复重试，快照文件涨到几百 MB 的情况，有了这个上限就不怕了。

4. 把 MCP 和 Durable 组合起来用：真实任务拆解

4.1 场景设定：一个跨服务的配置同步任务

光讲特性没意思，我拿一个实际做过的任务来串。需求是：把某个服务的配置从开发环境同步到测试环境，涉及读取开发环境的配置中心、对比测试环境现有配置、生成差异报告、执行同步、验证同步结果。这个任务跨了三个系统（配置中心、测试环境、验证脚本），步骤多，中间任何一步失败都需要能续上。

先配 MCP。配置中心我封装了一个 MCP 服务端，暴露 Resources（当前配置树）和 Tools（读取配置、写入配置）。测试环境通过另一个 MCP 服务端接入，暴露 Tools（读取当前配置、应用配置）。验证脚本就是本地 shell，不需要 MCP。

任务启动后，Pi 的执行流程大致是：先读配置中心的 Resource 建立认知，然后调 Tool 拉取开发环境配置，再调测试环境的 Tool 拉取现有配置，本地做 diff，生成报告，调测试环境 Tool 应用变更，最后跑验证脚本。整个过程大概 15 个步骤。

4.2 中断发生时的实际表现

我故意在"应用变更"这一步之后、验证之前，把 Pi 进程 kill 掉，模拟中断。然后执行pi resume。Pi 的表现是：加载快照，重建上下文，发现"应用变更"已完成，跳过，直接从验证步骤继续。验证脚本跑完，任务标记完成。整个过程没有重复应用变更，也没有丢失进度。

这里有个细节：验证脚本本身是非幂等的（它会往测试环境写验证数据），但因为它还没执行过，所以恢复时正常执行。如果中断发生在验证脚本执行到一半，恢复时 Pi 会检测到脚本进程已死，重新执行整个脚本。这就是为什么我建议把有副作用的验证逻辑尽量做成幂等的，或者在脚本开头加清理逻辑。

4.3 组合使用的性能与可靠性数据

我跑了 20 次同样的任务，统计了一下数据：

执行时间多了 6%，换来的是中断后 40 秒恢复而不是 4 分钟重跑。对于长任务，这个 trade-off 非常划算。而且注意，这 6% 是包含 MCP 冷启动的，如果服务端预加载了，开销能降到 3% 左右。

5. 踩坑记录与排查手册

5.1 MCP 服务端连不上的排查顺序

MCP 服务端启动失败是最常见的问题。排查顺序我总结成一张表：

我遇到最多的是第一和第二种。第一种通常是路径写错了，或者依赖没装。第二种多半是 SDK 版本和 Pi 内置的协议版本不匹配。Pi 1.0 用的是 MCP 协议 2024-11 版本，如果你的 SDK 太老，返回结构会对不上。建议锁定 SDK 版本，别用 latest。

5.2 Durable 恢复失败的几种典型情况

恢复失败比启动失败更让人抓狂，因为你好不容易跑了一半的进度可能就废了。我遇到过的几种：

工作区文件被外部修改。这是最常见的。恢复时 Pi 发现文件哈希对不上，会暂停并询问。如果你选"以工作区为准"，代理的上下文会和实际文件不一致，后续步骤可能出错。我的建议是，中断期间尽量不要手动改工作区文件，如果必须改，改完后选"以快照为准"让 Pi 回滚，或者干脆放弃恢复重跑。

MCP 服务端状态丢失。Durable 只持久化 Pi 自己的状态，不持久化 MCP 服务端的状态。如果服务端是有状态的（比如维护了一个会话），Pi 恢复后服务端可能已经重启，状态没了。解决办法是让 MCP 服务端尽量无状态，或者服务端自己也做持久化。

快照文件损坏。极少见，但发生过一次，原因是磁盘写满导致快照写了一半。Pi 会检测到损坏并提示从上一个完好快照恢复。所以前面说的maxTotalSize兜底很重要。

5.3 几个提升稳定性的实操技巧

第一个技巧：给 MCP 服务端加健康检查。在配置里加"healthCheck": {"command": "ping", "interval": 30}，Pi 会定期 ping 服务端，挂了会自动重启。这个对长时间运行的任务很有用。

第二个技巧：Durable 快照加密。快照里可能包含敏感数据（比如数据库查询结果），默认是明文存储。可以在配置里开"encrypt": true，Pi 会用系统密钥链里的密钥加密快照。多用户机器上强烈建议开。

第三个技巧：限制单步上下文大小。在~/.pi/config.json里设"maxStepContextSize": "256KB"，超过的会被截断。这能防止某个步骤读了个大文件把快照撑爆，也能控制 token 消耗。

第四个技巧：用pi durable inspect做事后分析。这个命令能列出某个会话的所有步骤、每步的耗时、工具调用次数。我经常用它来找性能瓶颈——哪个步骤耗时异常，一看就知道。

6. 这套组合适合什么场景，不适合什么场景

MCP 加 Durable 的组合，不是万能的。我用了这段时间，摸清了它的甜区。

适合的场景：步骤多、跨系统、单步耗时长的任务。比如跨环境的配置同步、多步骤的数据迁移、需要反复试错的调试任务。这些任务的特点是，重跑成本高，中断损失大，Durable 的价值能充分发挥。

不太适合的场景：单步就能完成的简单任务，或者对延迟极度敏感的任务。比如"帮我改个变量名"这种，Durable 的快照开销反而是负担。这种任务直接跑就行，不用开 Durable。

MCP 的适用边界：当你需要代理和外部系统做结构化交互时，MCP 是正解。但如果只是读读本地文件、跑跑 shell 命令，原生能力就够了，没必要为了用 MCP 而用 MCP。我见过有人把ls都封装成 MCP Tool，纯属脱裤子放屁。

最后分享一个我自己的配置习惯：我把常用的 MCP 服务端分成"核心"和"按需"两类。核心的（比如项目数据库、内部 API）在配置里preload: true，启动就加载；按需的（比如浏览器操作、特定工具）不预加载，用到才起。这样既保证了常用能力的响应速度，又不会让启动时拉一堆用不上的服务。

这套东西还在快速迭代，Pi 1.0 只是起点。我接下来打算试试把 CI 流水线也封装成 MCP 服务端，让代理能直接触发和查询构建。等跑通了再回来补一篇。