Pi Coding Agent 2026 完全指南：从入门到精通

什么是 Pi Coding Agent？

Pi Coding Agent 是一款开源（MIT 协议）的终端 AI 编程助手，由 Mario Zechner（GitHub: badlogic）创立的 Earendil Inc. 开发维护。截至 2026 年 8 月，Pi 在 GitHub 上已积累超过 91,600 颗星，最新版本为 v0.84.2，是目前增长最快的 AI 编程工具之一。

与 Cursor、Windsurf 等 IDE 类工具不同，Pi 完全运行在终端中。它不绑定任何编辑器，而是通过 4 个核心工具（read、write、edit、bash）直接操作你的文件系统和命令行。你可以把它理解为一个”住在终端里的 AI 程序员”——你用自然语言描述需求，它读取代码、修改文件、运行命令，全程透明可审计。

Pi 的核心设计理念是极简核心 + 用户可扩展。它只提供最基本的 4 个工具，但通过 TypeScript 编写的扩展（extensions）、技能（skills）和包（packages），你可以为它添加几乎任何能力。这种架构让 Pi 既能满足新手”开箱即用”的需求，也为高级用户提供了深度定制的空间。

Pi Agent 的核心优势

• 完全开源：MIT 协议，代码透明，社区驱动
• 终端原生：不依赖任何 IDE，SSH 远程开发、Docker 容器内均可使用
• 模型自由：支持 15+ 模型提供商（Anthropic、OpenAI、Google、Mistral、本地 Ollama 等）
• 零成本入门：工具本身免费，只需自带 API Key 或复用现有 Claude/ChatGPT/Copilot 订阅
• 高度可扩展：TypeScript 扩展系统，社区生态丰富

安装和配置

系统要求

• 操作系统：macOS 12+、Ubuntu 22.04+、Windows 11（需 WSL2）
• Node.js：22.0 或更高版本
• 网络：需要访问所选 AI 模型的 API

安装方式

方式一：一键安装脚本（推荐）

curl -fsSL https://pi.dev/install.sh | bash

这个脚本会自动检测你的系统架构，下载对应的二进制文件，并添加到 PATH 中。安装完成后，运行以下命令验证：

pi --version
# 输出示例：pi 0.84.2

方式二：通过 npm 安装

npm install -g @earendil-works/pi-coding-agent

方式三：从源码构建

git clone https://github.com/earendil-works/pi.git
cd pi
npm install
npm run build
npm link

首次配置

安装完成后，运行 pi 启动交互式配置向导：

pi

向导会引导你完成以下设置：

1. 选择模型提供商：首次运行推荐选择 Anthropic Claude 或 OpenAI
2. 输入 API Key：直接粘贴你的密钥（存储在 ~/.pi/config.json，权限 600）
3. 选择默认模型：如 claude-sonnet-4-20250514、gpt-4o、gemini-2.5-pro 等
4. 配置工作目录：Pi 会在你当前所在目录启动

你也可以手动编辑配置文件 ~/.pi/config.json：

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "apiKey": "sk-ant-xxx",
  "theme": "dark",
  "autoApprove": false,
  "maxTokens": 8192
}

多模型配置

Pi 支持同时配置多个模型提供商，运行时可随时切换：

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-xxx",
      "defaultModel": "claude-sonnet-4-20250514"
    },
    "openai": {
      "apiKey": "sk-xxx",
      "defaultModel": "gpt-4o"
    },
    "ollama": {
      "baseUrl": "http://localhost:11434",
      "defaultModel": "qwen3-coder:30b"
    }
  }
}

在交互界面中，输入 /model 命令即可切换当前使用的模型。

核心功能详解

1. 代码生成和补全

Pi 不仅能补全单行代码，更能理解整个项目上下文后生成完整的功能模块。

示例：生成一个 Express.js REST API

> 帮我创建一个 Express.js 项目，包含用户注册、登录和 JWT 认证功能

Pi 会自动：

• 初始化 package.json 并安装依赖（express、jsonwebtoken、bcryptjs）
• 创建项目结构（src/routes/、src/middleware/、src/models/）
• 编写完整的路由、中间件和数据验证代码
• 生成 .env.example 和 README.md

整个过程你会看到 Pi 依次调用 write 工具创建每个文件，所有操作实时显示在终端中。

2. 文件操作

Pi 的 4 个核心工具中，read 和 write 负责文件读写，edit 负责精确修改：

• read：读取文件内容，支持按行范围读取大文件
• write：创建新文件或完全覆盖现有文件
• edit：基于差异（diff）的精确编辑，只修改需要变更的部分

> 把 src/utils/date.ts 里的 formatDate 函数改成支持多语言格式

Pi 会先 read 文件了解当前实现，然后用 edit 工具精确修改目标函数，保留文件其余部分不变。

3. 终端命令执行

通过 bash 工具，Pi 可以直接在你的终端执行命令：

> 运行测试，如果有失败的测试就修复它们

Pi 会执行 npm test，解析输出中的失败信息，定位问题代码，修改后重新运行测试，循环直到全部通过。

安全机制：默认情况下，Pi 执行每条命令前都会请求你的确认。你可以设置 autoApprove: true 自动批准，但建议仅在受控环境（如 Docker 容器）中开启。

4. 上下文管理

Pi 的上下文管理是其核心竞争力之一：

• 自动索引：启动时自动扫描项目结构，构建文件关系图
• 智能引用：当你提到某个函数或模块时，Pi 自动定位并加载相关代码
• 长会话支持：通过上下文窗口管理和摘要机制，支持数小时的连续对话
• @ 语法引用：用 @src/auth/jwt.ts 显式将文件加入上下文

> 看看 @src/services/payment.ts 和 @src/routes/checkout.ts，
> 帮我找出为什么支付成功后订单状态没有更新

实战案例

案例 1：创建 REST API

从零开始搭建一个完整的 Todo API：

> 用 Fastify + Prisma + PostgreSQL 创建一个 Todo API，
> 包含 CRUD 操作、分页和过滤功能

Pi 的执行过程：

1. 初始化项目，安装 fastify、prisma、@prisma/client 等依赖
2. 编写 prisma/schema.prisma，定义 Todo 模型
3. 运行 npx prisma generate 和数据库迁移
4. 创建路由文件 src/routes/todos.ts，实现列表（含分页/过滤）、创建、详情、更新、删除 5 个端点
5. 编写 src/server.ts 主入口
6. 生成 docker-compose.yml 用于启动 PostgreSQL
7. 创建 README.md 包含 API 文档和使用说明

全部代码约 200 行，Pi 在 3 分钟内完成。

案例 2：调试代码问题

> 这个函数在处理超过 1000 条数据时特别慢，帮我分析原因并优化

@src/services/report.ts

Pi 读取文件后发现：

// 问题代码：O(n²) 复杂度
for (const item of items) {
  const related = items.filter(i => i.category === item.category);
  // ...
}

Pi 解释问题并给出优化方案：用 Map 分组替代嵌套循环，将 O(n²) 降为 O(n)。修改后实测 10,000 条数据的处理时间从 12 秒降至 0.3 秒。

案例 3：重构项目代码

> 把项目里所有的 CommonJS require/module.exports 迁移到 ES Modules

Pi 会：

1. 扫描所有 .js 和 .ts 文件
2. 逐个转换 require() 为 import，module.exports 为 export
3. 更新 package.json 添加 "type": "module"
4. 修复因 ESM 异步加载导致的相对路径问题（__dirname → import.meta.url）
5. 运行测试验证迁移正确性

案例 4：编写测试

> 给 @src/services/auth.ts 写单元测试，覆盖注册、登录、token 刷新和过期场景

Pi 使用 Jest + TypeScript 编写测试，包含：

• 正常注册流程
• 重复邮箱注册报错
• 密码哈希验证
• 登录成功返回 JWT
• 错误密码登录失败
• Token 刷新机制
• 过期 Token 拒绝

共生成 12 个测试用例，全部通过。

高级技巧

自定义扩展

Pi 的扩展系统基于 TypeScript，让你可以为 Agent 添加新工具：

// extensions/docker.ts
import { defineExtension } from '@earendil-works/pi-coding-agent';

export default defineExtension({
  name: 'docker',
  tools: [
    {
      name: 'docker_exec',
      description: '在指定容器中执行命令',
      parameters: {
        container: { type: 'string', description: '容器名或ID' },
        command: { type: 'string', description: '要执行的命令' },
      },
      async execute({ container, command }) {
        const result = await exec(`docker exec ${container} ${command}`);
        return result.stdout;
      },
    },
  ],
});

将文件放入 ~/.pi/extensions/ 目录，Pi 启动时自动加载。

多 Agent 并行

Pi 支持同时运行多个 Agent 实例处理不同任务：

# 终端 1：前端重构
pi --task "重构 src/components/ 下所有 class 组件为函数组件"

# 终端 2：后端 API
pi --task "给 /api/v2/users 添加分页和排序功能"

# 终端 3：测试覆盖
pi --task "为 src/services/ 下所有模块补充单元测试"

每个 Agent 独立运行，互不干扰。对于大型项目，这种方式可以显著提升开发效率。

与 IDE 集成

虽然 Pi 是终端工具，但可以与任何 IDE 配合使用：

• VS Code：在 VS Code 内置终端中直接运行 Pi
• JetBrains：同样支持内置终端
• Neovim：通过 toggleterm 或 floaterm 插件集成
• SSH 远程开发：Pi 天然支持 SSH 环境，无需额外配置

技能（Skills）系统

技能是预定义的提示词模板，用于常见任务类型：

# 使用内置技能
pi --skill code-review "检查 src/auth/ 目录的安全性"
pi --skill refactor "将 src/utils/ 中的回调风格代码改为 async/await"

你也可以创建自定义技能，保存在 ~/.pi/skills/ 目录下。

Pi Agent vs Claude Code vs Cursor 对比

特性	Pi Coding Agent	Claude Code	Cursor
类型	终端 Agent	终端 Agent	AI IDE（VS Code Fork）
开源	✅ MIT 协议	❌ 闭源	❌ 闭源
价格	免费（自带 API Key）	$20/月（Max 计划含额度）	$20/月（Pro 计划）
模型支持	15+ 提供商	仅 Anthropic Claude	多模型（Claude/GPT/自定义）
本地模型	✅ Ollama/LM Studio	❌	❌
运行环境	任意终端	任意终端	仅 Cursor IDE
SSH 远程	✅ 原生支持	✅ 原生支持	⚠️ 需 Remote SSH 插件
扩展系统	✅ TypeScript 扩展	⚠️ 有限	✅ VS Code 插件生态
上下文窗口	200K tokens	200K tokens	取决于模型
GitHub Stars	91.6K+	N/A（闭源）	N/A（闭源）
适合场景	全栈开发、DevOps、远程服务器	纯编码任务	前端/全栈、可视化开发

选择建议：

• 选 Pi Agent：如果你需要开源、模型自由、终端原生、或想在 SSH/Docker 环境中使用
• 选 Claude Code：如果你已经是 Claude 重度用户，追求最简配置
• 选 Cursor：如果你更喜欢图形化 IDE 体验，不想离开编辑器

常见问题和解决方案

Q1：Pi Agent 是免费的吗？

Pi 工具本身完全免费开源（MIT 协议）。但使用 AI 模型需要付费——你可以自带 API Key（按用量付费给模型提供商），也可以使用 Ollama 等本地模型实现完全免费使用。

Q2：Pi 支持哪些 AI 模型？

目前支持 15+ 提供商，包括：Anthropic（Claude 系列）、OpenAI（GPT-4o/o3 系列）、Google（Gemini 系列）、Mistral、AWS Bedrock、Azure OpenAI、Groq、本地 Ollama/LM Studio 等。完整列表可通过 pi --list-providers 查看。

Q3：Pi 和 Claude Code 有什么区别？

核心区别：Pi 是开源的，支持多模型提供商，有 TypeScript 扩展系统；Claude Code 是 Anthropic 官方产品，仅支持 Claude 模型，但集成度更高。Pi 更适合需要模型灵活性和深度定制的用户。

Q4：Pi 能在 Windows 上使用吗？

可以，但需要通过 WSL2（Windows Subsystem for Linux）。原生 Windows 支持不在当前路线图中，建议 Windows 用户安装 WSL2 后使用。

Q5：如何保证代码安全？Pi 会把我的代码发送到云端吗？

Pi 本身不收集任何数据。你的代码会发送到你选择的模型提供商的 API（如 Anthropic、OpenAI），这取决于该提供商的隐私政策。使用本地模型（Ollama）可以实现完全离线，代码不离开本机。

Q6：Pi 的上下文窗口有多大？

取决于你使用的模型。Claude Sonnet/Opus 支持 200K tokens，GPT-4o 支持 128K tokens。Pi 还实现了自动上下文压缩，在长会话中保留关键信息。

Q7：如何在团队中共享 Pi 配置？

将 .pi/config.json 中的非敏感配置（如主题、自动批准设置）提交到项目仓库的 .pi/ 目录中。API Key 等敏感信息应使用环境变量 PI_API_KEY 或 .env 文件（加入 .gitignore）。

---

Pi Coding Agent 代表了 AI 编程工具的一个重要方向：开源、终端原生、模型无关。对于习惯命令行工作流的开发者，尤其是 IoT 和嵌入式领域经常需要 SSH 远程开发的工程师来说，Pi 是目前最灵活的选择之一。如果你正在寻找一个不受厂商锁定、可以深度定制的 AI 编程助手，Pi 值得一试。