用 Pi 1.0 搭一个极简可定制的编码智能体：安装、扩展包与 Codemode MCP 实操

Pi 的核心哲学写在仓库首页：模型是引擎，harness 是整车其余的部分——提示词、控制流、工具与记忆管理。Pi 默认只给模型 read、write、edit、bash 四个工具，其余一切（子智能体、计划模式、权限弹窗）都通过扩展体系外挂。这个设计换来的是可审计：模型收到的上下文清清楚楚，出了问题容易定位，也方便跨模型复现。

它支持交互式使用、以 print 或 JSON 模式做自动化、通过 RPC 远程控制，也可以用 TypeScript SDK 嵌进你自己的应用——官方举的真实集成案例就是 OpenClaw。扩展、技能、提示词模板与主题可以打包成 Pi 包，通过 npm 或 git 分享。

官方安装脚本会锁定全部依赖版本，并支持用 pi update 升级，是推荐路线。Windows 用 PowerShell 版脚本，npm 全局安装作为备选（官方明确提示：npm 路线不锁定传递依赖）：

# macOS / Linux
curl -fsSL https://pi.dev/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://pi.dev/install.ps1 | iex"

# 备选：npm 全局安装（不锁定传递依赖）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Pi 要求 Node.js 22.19 或更新版本——macOS、Linux 与 Windows 安装器在缺失时会自动安装，npm 路线则需要你自己保证。装完在项目目录启动，刚装好时在界面内输入 /login 绑定模型：

cd /path/to/project
pi
# 界面内执行：
# /login

交互模式下直接用自然语言派活即可，四个内置工具足以覆盖"读代码—改文件—跑命令"的闭环。Pi 更有价值的用法在自动化：官方 README 列出了 print 模式与 JSON 模式（机器可读输出）、RPC 模式（远程控制）与 TypeScript SDK（嵌入应用）四种非交互形态。具体参数以你安装版本的 --help 输出为准：

cd /path/to/project
pi --help   # 查看 print / JSON / RPC 等非交互模式参数
pi update   # 后续升级

把 Pi 塞进 CI 或脚本时，JSON 模式输出的结构化结果便于下游程序解析；RPC 模式适合常驻进程里复用同一个会话。建议先在低风险仓库试跑完整任务链，再接入自动化流程。

Pi 的可定制面有四层：extensions（行为扩展）、skills（技能）、prompt templates（提示词模板）与 themes（主题），它们都能打包成 Pi 包，通过 npm 或 git 分发。官方在 @earendil-works scope 下发布了七个包，包括 pi-ai（统一模型 API）、pi-agent-core（Agent 循环）、pi-coding-agent（CLI 本体）、pi-tui（终端界面）与 pi-telemetry（遥测），可作为写扩展时的参考实现：

# 查看官方包元数据，确认版本与依赖
npm view @earendil-works/pi-coding-agent
npm view @earendil-works/pi-ai

没有现成扩展时，官方的建议很直接：让 Pi 自己给你写一个——这正是极简 harness 的用法，你描述工作流，它生成扩展代码，你审阅后装回。这种"把定制本身交给智能体"的循环，是大而全商业智能体难以提供的。

1.0 最重要的新特性是 Codemode：Pi 不再把每个工具的完整 schema 塞进上下文逐个调用，而是把工具暴露给一个运行在 harness 侧的 JavaScript 沙箱，模型写一段短脚本一次完成"调用多个工具、循环、过滤、返回结果"。官方 v1.0.0 发布说明给出的数据是：默认工具加 Codemode 生效后，一次 GPT-5.6 请求的 prompt tokens 从约 5300 降到约 3300。1.0 同时把原生 MCP 支持收进核心——曾经公开表示不需要 MCP 的项目，在 MCP 成熟并带来工具元数据延迟加载、调用编排等能力后完成了转身。

伴随 Codemode 还有一批上下文工程改进：deferred tool loading 让大型工具目录按需加载而非每次全量注入；Anthropic 模型支持 cache warming；系统消息可以在会话中途插入，提示词与工具变更会落在它们实际发生的位置。这些都直接改善长会话的成本与一致性。

与 1.0 同期发布的 Pi Durable 是一个独立的实验性包，把 Pi 的极简哲学延伸到"跑很久"的应用：对话管理与存储走 SQLite 加 JSONL 文件，每个任务步骤都落检查点，进程崩溃后可从断点恢复，还支持多人共同驾驶同一段会话。官方用"Pi 之于 Flask，而非 Django"来定位它——给你地基，不给你全家桶：

npm install @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord

上手路径：用 pi-ai 定义模型调用，用 pi-durable 包装会话与检查点逻辑，跑一个定时清理仓库、生成周报之类的长任务，中途手动 kill 进程再重启，验证它从 JSONL 检查点恢复。如果恢复点符合预期，再考虑更严肃的场景。