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 编程工具之一。它属于 AI Coding Agent 这一新品类——与传统的”AI 补全”不同，Agent 能够自主规划并执行完整的开发任务，是当下 AI 编程工具生态 中最活跃的一环，也是 Vibe Coding 潮流的核心基础设施。

与 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，
> 帮我找出为什么支付成功后订单状态没有更新

Pi Agent 的工作原理

理解 Pi 的底层工作机制，有助于你更高效地使用它。

核心循环：思考-行动-观察

Pi 的运行遵循一个经典的 Agent 循环：

1. 思考（Think）：接收用户输入，结合项目上下文，规划下一步行动
2. 行动（Act）：调用工具（read/write/edit/bash）执行具体操作
3. 观察（Observe）：读取工具返回结果，判断是否达到目标
4. 迭代（Loop）：如果任务未完成，回到第 1 步继续

这个循环直到 Pi 认为任务完成或遇到无法解决的问题时才会停止。在整个过程中，你可以在终端实时看到每一步的思考和操作记录——这是 Pi 相比 IDE 类工具的透明度优势。

工具调用机制

Pi 的 4 个核心工具通过 JSON Schema 定义参数，模型以结构化方式调用：

用户: "帮我修复这个 bug"
  ↓
模型思考: 需要先读取文件了解代码
  ↓
调用 read 工具 → 返回文件内容
  ↓
模型思考: 发现第 42 行有逻辑错误
  ↓
调用 edit 工具 → 精确修改第 42 行
  ↓
调用 bash 工具 → 运行测试验证修复
  ↓
测试通过 → 返回结果给用户

每个工具调用都会在终端中以彩色文本显示，你可以随时按 Esc 中断正在执行的操作。

上下文窗口管理

当对话变长时，Pi 会智能管理有限的上下文窗口：

• 近期对话：完整保留最近 10-20 轮对话
• 早期对话：自动压缩为摘要，保留关键决策和代码变更
• 文件引用：通过 @ 语法引用的文件始终保持在上下文中
• 项目结构：自动维护项目文件树的精简表示

Pi Agent 在 IoT 和嵌入式开发中的应用

作为 makeronsite.com 的读者，你可能更关心 Pi 在 IoT 和嵌入式领域的实际用途。Pi 的终端原生特性使其特别适合这类场景。

SSH 远程开发

IoT 开发经常需要 SSH 到树莓派或远程服务器。Pi 可以直接在 SSH 会话中运行：

ssh pi@192.168.1.100
pi
> 帮我检查 /home/pi/sensors/ 目录下的 Python 脚本，
> 找出为什么 DHT22 传感器数据偶尔读取失败

Pi 会读取代码，分析超时和重试逻辑，给出修复方案并直接应用。

ESP32/Arduino 项目辅助

虽然 Pi 不能直接烧录固件，但它可以帮你：

• 编写和优化 Arduino/ESP32 C++ 代码
• 配置 PlatformIO 项目（platformio.ini）
• 分析串口日志，定位通信协议问题
• 编写 Python 上位机脚本与嵌入式设备通信

> 帮我写一个 ESP32 的 MQTT 客户端代码，
> 连接 EMQX 公共 broker，每 30 秒发布 DHT22 温湿度数据

Pi 会生成完整的 Arduino 代码，包含 WiFi 连接、DHT22 读取、MQTT 发布、断线重连和 OTA 更新支持。

Docker 容器化部署

IoT 后端服务通常需要容器化部署。Pi 可以帮你：

> 帮我创建一个 docker-compose.yml，包含：
> - EMQX MQTT broker
> - Node-RED 可视化面板
> - InfluxDB 时序数据库
> - Grafana 数据看板
> 确保它们能互相通信

Pi 会生成完整的 docker-compose.yml，配置网络、卷挂载、环境变量，并确保服务间的依赖顺序正确。

实战案例

案例 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 的 10 个技巧

1. 使用 CLAUDE.md / PI.md 定义项目规则

在项目根目录创建 PI.md 文件，Pi 启动时会自动读取：

# PI.md

## 项目规则
- 使用 TypeScript strict 模式
- 所有 API 返回统一格式 { code, data, message }
- 测试覆盖率不低于 80%
- 提交信息使用 Conventional Commits 格式

## 技术栈
- 后端：Fastify + Prisma + PostgreSQL
- 前端：React + Vite + Tailwind CSS
- 部署：Docker + Kubernetes

这样 Pi 在每次对话中都会遵循这些规则，无需重复说明。

2. 善用 /compact 命令

长时间对话后，输入 /compact 可以压缩当前上下文，释放窗口空间。Pi 会保留关键信息，丢弃冗余细节。

3. 使用 —print 模式实现自动化

Pi 的 --print 模式让它可以在 CI/CD 管道中运行：

# 在 GitHub Actions 中自动生成 changelog
pi --print "根据最近的 git commits 生成 CHANGELOG.md" >> CHANGELOG.md

# 自动代码审查
pi --print "审查 src/api/ 目录下最近的改动，指出潜在的安全问题"

4. 利用 —allowedTools 限制工具范围

如果你只想让 Pi 读取文件而不修改，可以限制可用工具：

pi --allowedTools "read,bash(git *)"

这样 Pi 只能读取文件和执行 git 命令，无法修改任何代码——适合代码审查场景。

5. 使用 MCP 扩展能力

Pi 支持 Model Context Protocol（MCP），可以连接外部服务：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxx" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "postgresql://..." }
    }
  }
}

配置后，Pi 可以直接查询数据库、管理 GitHub Issues，无需离开终端。

6. 分步拆解复杂任务

与其一次性描述整个需求，不如分步引导：

第 1 步: "先帮我设计数据库模型，不要写代码"
第 2 步: "模型看起来不错，现在写 Prisma schema"
第 3 步: "生成 seed 脚本填充测试数据"
第 4 步: "写 API 路由，遵循 RESTful 规范"

分步执行让每一步都可控，避免 Pi 一次性生成大量代码后难以调试。

7. 使用 —resume 恢复会话

Pi 会自动保存对话历史。用 --resume 可以恢复上次会话：

pi --resume          # 恢复最近一次会话
pi --resume --id abc # 恢复指定会话

8. 配置 .piignore 排除无关文件

类似 .gitignore，创建 .piignore 排除不需要 Pi 索引的文件：

node_modules/
dist/
*.min.js
coverage/
*.log

这能显著提升 Pi 的上下文利用效率。

9. 利用 /cost 监控 API 消耗

输入 /cost 查看当前会话的 token 消耗和费用。对于按量付费的 API，这个功能帮你控制成本。

10. 组合使用 bash 和 Pi

Pi 最强大的用法之一是将 bash 命令的输出作为输入：

# 让 Pi 分析 git diff
git diff HEAD~5 | pi --print "审查这些代码变更，指出潜在问题"

# 让 Pi 分析错误日志
docker logs myapp --tail 100 | pi --print "分析这些错误日志，找出根本原因"

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 体验，不想离开编辑器

生态与社区

GitHub 项目概览

Pi 的 GitHub 仓库（earendil-works/pi）是目前增长最快的开源 AI 编程项目之一：

• Stars：91,600+，2026 年内增长超过 5 倍
• 贡献者：200+ 活跃贡献者
• Release 频率：每周 2-3 个版本
• License：MIT，无任何商业限制

社区生态

围绕 Pi 已经形成了丰富的生态：

• 官方文档：docs.pi.dev 提供完整的中英文文档
• Discord 社区：10,000+ 成员，官方开发者在线答疑
• 扩展市场：社区贡献了 500+ 扩展，涵盖数据库、云服务、物联网等领域
• 模板库：官方提供 20+ 项目模板（React、Vue、FastAPI、ESP-IDF 等）

版本演进时间线

2025 Q3  v0.1.x  项目发布，核心 4 工具 + Claude/OpenAI 支持
2025 Q4  v0.4.x  引入 TypeScript 扩展系统，支持 Ollama 本地模型
2026 Q1  v0.6.x  推出 RPC/SDK 模式，支持多 Agent 并行
2026 Q2  v0.7.x  集成 MCP 协议，上下文压缩机制上线
2026 Q3  v0.84    稳定版，GitHub Stars 突破 9 万

高级配置与优化

性能调优

对于大型项目，Pi 的上下文管理至关重要。可以通过以下配置优化性能：

1. 设置上下文窗口大小

在 ~/.pi/config.json 中配置：

{
  "contextWindow": 128000,
  "maxTokens": 8192,
  "temperature": 0.7
}

较大的上下文窗口允许 Pi 同时查看更多代码，但会增加 API 成本。建议根据项目规模调整：

• 小型项目（< 100 文件）：128K tokens
• 中型项目（100-500 文件）：200K tokens
• 大型项目（> 500 文件）：使用 --compact 频繁压缩

2. 配置智能忽略规则

创建 .piignore 文件排除不需要索引的内容：

node_modules/
dist/
build/
*.min.js
*.map
coverage/
.nyc_output/
*.log
.DS_Store

这能显著提升 Pi 的响应速度，避免浪费 tokens 在无关文件上。

3. 启用缓存机制

Pi 支持本地缓存减少重复请求：

{
  "cache": {
    "enabled": true,
    "ttl": 3600,
    "maxSize": "500MB"
  }
}

缓存会在 ~/.pi/cache/ 目录存储最近的对话和文件索引，相同问题的响应速度提升 3-5 倍。

多模型策略

不同任务适合不同模型，Pi 支持动态切换：

# 简单任务用快速模型
pi --model gpt-4o-mini "格式化这段代码"

# 复杂重构用强模型
pi --model claude-opus-4 "重构整个认证模块"

# 本地模型处理敏感代码
pi --model ollama/qwen2.5-coder "分析这段加密算法"

在交互模式中，使用 /model 命令实时切换，无需重启会话。

自定义工作流

Pi 支持通过 Hook 系统自动化工作流：

{
  "hooks": {
    "beforeWrite": ["npm run lint --fix"],
    "afterWrite": ["npm run format"],
    "beforeBash": ["echo 'Executing command...'"]
  }
}

这样每次 Pi 写入文件后自动格式化，执行命令前显示提示，确保代码风格统一。

实战案例：构建完整的 IoT 项目

让我们用 Pi 从零构建一个智能家居监控系统：

需求：ESP32 采集温湿度数据，通过 MQTT 发送到后端，前端实时显示。

第一步：后端服务

> 用 Fastify + MQTT.js 创建后端服务，接收 ESP32 的传感器数据，
> 存储到时序数据库，提供 REST API 查询历史数据

Pi 会生成：

• server.js：Fastify 服务器 + MQTT 客户端
• database.js：InfluxDB 连接和数据写入
• routes.js：REST API（GET /api/sensors, GET /api/history）
• docker-compose.yml：InfluxDB + EMQX 容器配置

第二步：ESP32 固件

> 写 ESP32 Arduino 代码，读取 DHT22 温湿度，
> 通过 WiFi 连接 MQTT broker，每 10 秒发布一次数据

Pi 生成完整的 Arduino 代码，包含：

• WiFi 连接管理（自动重连）
• DHT22 读取（错误处理）
• MQTT 发布（JSON 格式）
• 低功耗模式（深度睡眠）
• OTA 更新支持

第三步：前端界面

> 用 React + Chart.js 创建监控面板，
> 实时显示温湿度曲线，支持时间范围筛选

Pi 生成：

• App.jsx：主界面布局
• SensorChart.jsx：Chart.js 实时图表
• api.js：后端 API 调用
• WebSocket.js：实时数据推送

整个项目约 800 行代码，Pi 在 15 分钟内完成，包含完整的错误处理和文档。

常见问题与解决方案

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）。

Q8：Pi 和 Cursor 可以一起用吗？

完全可以。很多开发者把 Cursor 当作编辑器，把 Pi 当作终端中的”高级助手”。工作流通常是：在 Cursor 中浏览和编辑代码，遇到复杂任务（重构、批量修改、调试）时切换到终端让 Pi 处理。两者互补，并不冲突。

Q9：Pi 的 bash 工具安全吗？

Pi 默认在执行每条 bash 命令前都会显示命令内容并等待你的确认（Y/n）。只有当你设置 autoApprove: true 后才会自动执行。建议：日常开发保持默认确认模式，仅在 Docker 容器或一次性环境中开启自动批准。你还可以用 --allowedTools "bash(git *),read,write,edit" 精细控制 Pi 能执行哪些命令。

Q10：如何卸载 Pi？

# 如果是 npm 安装
npm uninstall -g @earendil-works/pi-coding-agent

# 如果是一键脚本安装
rm -f ~/.local/bin/pi

# 删除配置和缓存（可选）
rm -rf ~/.pi

常见错误与排查

错误 1：command not found: pi

安装后找不到命令，通常是 PATH 未包含安装目录。重新打开终端，或手动将安装目录加入 PATH：

export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

错误 2：API Key 认证失败

检查环境变量是否被旧配置覆盖：

pi doctor   # 运行诊断命令

常见原因：~/.pi/config.json 中的 apiKey 为空、环境变量名拼写错误（应为 ANTHROPIC_API_KEY 而非 ANTHROPIC_KEY）、或 Key 已过期。

错误 3：上下文窗口耗尽

长对话后出现”context length exceeded”错误。解决：

1. 输入 /compact 压缩上下文
2. 或重启会话，用 --resume 恢复并继续
3. 或将任务拆分为多个小会话

错误 4：模型请求超时

网络不稳定时常见。解决方法：

• 检查网络连接和代理设置
• 在配置中增加 timeout 字段（默认 60 秒）
• 切换到响应更快的模型（如 Haiku 替代 Sonnet 处理简单任务）

---

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