Pi Coding Agent 实战配置：从安装到日常使用的完整指南

Pi 是一个开源的终端编码代理，由 libGDX 作者 Mario Zechner 开发。它的核心只有 418 行 TypeScript，默认提供 read、write、edit、bash 四个工具，所有高级功能通过扩展和包来补充。此前我们已经从架构层面深入分析过 Pi 的设计哲学，本文则聚焦于实际使用场景：如何安装、配置、选择扩展包，以及如何将 Pi 融入日常开发工作流。

定位：Pi 在工具链中的角色

Pi 并非要替代所有编码工具。以 DeepakNess 的实际使用为例，三款工具各有分工：

• OpenAI Codex：处理主项目的复杂任务
• Cursor：主项目的日常编码
• Pi：副项目、实验性任务、一次性脚本，通常搭配更便宜的开源模型

这种分层策略的核心逻辑是：复杂度高的任务用强模型 + 重型工具，简单或探索性的任务用轻量代理 + 低成本模型，控制整体开支。

安装与首次配置

Pi 的安装只需一行命令：

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

安装完成后在终端输入 pi 启动，通过 /login 命令完成认证。Pi 支持两种认证方式：

1. 订阅登录：支持 Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot、Google Gemini CLI 等
2. API Key：选择 "Use an API key"，输入对应提供商的密钥（如 DeepSeek）

模型选择使用 /model 或 Ctrl+L 打开选择器。作者默认使用 deepseek-v4-pro 配合 xhigh 思考级别用于深度分析，切换到 deepseek-v4-flash 处理快速任务。

三个核心扩展包

Pi 通过 pi install 安装扩展包。以下三个包覆盖了大部分实用场景：

pi-web-access

赋予 Pi 网页搜索、内容抓取、YouTube 转录和 GitHub 仓库探索能力。

pi install npm:pi-web-access

配置文件位于 ~/.pi/web-search.json：

{
  "provider": "exa",
  "summaryModel": "deepseek/deepseek-v4-flash",
  "workflow": "none"
}

pi-codex-goal

为长时间运行的任务添加目标追踪机制，适合需要多步骤完成的复杂任务。

pi install npm:pi-codex-goal

pi-vision-proxy

当主模型不具备视觉能力时，将图片分析请求代理到支持视觉的模型（如 Kimi K2.6）。

pi install npm:pi-vision-proxy

配置文件体系

Pi 的配置分两层：

AGENTS.md（项目上下文）：放在项目根目录或 ~/.pi/agent/AGENTS.md，内容会注入 system prompt。适合定义项目技术栈、编码规范等。

APPEND_SYSTEM.md（全局行为规则）：位于 ~/.pi/agent/APPEND_SYSTEM.md，追加到系统提示末尾，优先级高于 AGENTS.md。适合定义跨项目的通用行为准则，例如：

• 主模型不具备视觉能力时自动使用 vision proxy
• 优先使用本地文件，只在必要时联网搜索
• 解释高风险的编辑和命令
• 简洁写作，避免 AI 腔

快捷键与常用命令

Pi 的交互设计围绕终端效率展开：

常用命令包括 /model、/settings、/resume、/new、/tree（会话分支管理）、/compact（手动压缩上下文）、/session。

实际成本案例

一个典型的使用场景：用 DeepSeek v4 Flash 抓取 28.5 万个 URL，耗时约 1.5 小时，总费用 $1。这体现了 Pi 搭配开源模型的成本优势。

为什么选择 Pi

Pi 的核心优势在于：

• 终端原生：无 UI 卡顿，响应迅速
• 模型无关：通过 /model 随时切换 provider，上下文无缝迁移
• 高度可定制：扩展和包机制让用户按需组装功能
• 会话树管理：/tree 命令支持分支和导航对话历史
• 自动上下文压缩：接近上下文限制时自动摘要

对于终端用户而言，Pi 的价值不在于"功能最全"，而在于"可控性最高"。它的每一个行为都是透明的，每一个功能都是显式安装的。这种设计哲学让它成为副项目和实验性任务的理想选择。

参考来源：

• DeepakNess: Setting Up and Using the Pi Coding Agent
• Pi 官方文档