Pi 完全上手指南：从安装到真实项目实战

2026 年 11 月 7 日校订：更新安装版本要求、DeepSeek 调用名称、升级方法与内置 MCP。文中速度记录属于原作者当时的体验，本轮未重测性能；旧概念配图不代表当前模型目录。

如果你已经用过 Claude Code、Codex CLI，或者在编辑器里用过各种 AI 编程插件，第一次看到 Pi，可能会问：又一个命令行 AI 工具，有什么不同？

我的答案很直接：Pi 最吸引我的，不是它替你塞进了多少功能，而是它把核心保持得足够小，把模型、工具、工作流和界面的选择权交还给使用者。

Pi 官方把自己定义为一个“极简的终端编程代理框架”。它不是大模型，也不是某家模型公司的专属客户端。它更像一套运行在终端里的工作台：上面可以接不同模型，下面可以调用读取文件、修改代码和执行命令等工具，外面还可以继续增加扩展、技能、提示词模板、主题和软件包。

我尤其推荐大家试试 Pi + DeepSeek Flash。以我目前的实际使用感受，这个组合在速度、性能和价格之间达到了很好的平衡。我实测流式输出的瞬时最高速度接近 100 token/s。这不是对所有网络、供应商和任务都成立的保证，但它足以说明，这套组合已经可以提供相当流畅的交互体验。

这篇文章不只讲“安装后输入 pi”。我会从选择思路、安装、模型接入、第一次任务、日常工作流、会话管理、项目规则、扩展方式一直讲到安全边界。你可以边看边操作。

一、先弄明白：Pi 到底是什么

一次完整的 AI 编程任务，大致包含四层：

• 你提出目标，并提供必要上下文；
• 模型理解问题，决定下一步动作；
• 代理调用工具，读取文件、编辑代码或运行命令；
• 结果回到模型，继续判断，直到任务结束。

Pi 主要负责后三层之间的协调。它把你的对话、模型响应、工具调用和任务历史组织成一个可持续工作的终端会话。

Pi 默认提供 read、write、edit 和 bash 四个工具，分别对应读取文件、写入文件、精确编辑和执行 Shell 命令。还可以按需启用 grep、find、ls。看起来很少，但写代码最基本的闭环已经完整：理解现状，修改文件，运行检查，观察结果，再修正。

这也是它和普通聊天机器人的根本区别。聊天机器人可以告诉你“应该怎么改”，Pi 则可以在你授权的本机环境里真正打开项目、修改代码和运行测试。

它与其他终端编程代理也不是简单的高低关系。Pi 的取向是“小核心、强扩展、可切换模型”。如果你想要开箱即用、由厂商安排好的完整体验，其他产品可能更省心；如果你希望自己决定模型、上下文规则、工具和工作流，Pi 会更有吸引力。

二、安装前要准备什么

你需要一台 macOS、Linux 或可正常使用终端环境的电脑。使用 npm 安装时，还需要 Node.js 和 npm。

先检查环境：

node --version
npm --version

npm 安装要求 Node.js 22.19 或更新版本；不只要能输出版本号，还要核对版本满足要求。若提示命令不存在，先从 Node.js 官方网站安装当前的 LTS 版本，再重新打开终端。

Pi 官方给出的 npm 安装命令是：

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

其中 -g 表示全局安装，安装后可以在任意目录输入 pi；--ignore-scripts 会在安装期间关闭依赖包的生命周期脚本。Pi 的正常 npm 安装不依赖这些脚本，这是一个更克制的安装方式。

macOS 和 Linux 也可以使用官方安装脚本：

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

如果你对管道执行远程脚本比较谨慎，就优先使用 npm 方案。安装完成后验证：

pi --version
pi --help

下面的卸载命令仅适用于 npm 安装；官方脚本、Nix 安装应按原渠道管理。npm 安装需要卸载时运行：

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

这里有一个很容易被忽略的细节：不要在主目录、桌面根目录或包含大量私人文件的宽泛目录里直接启动代理。 应该先进入一个边界明确的项目目录：

cd /你的项目路径
git status
pi

如果项目还没有使用 Git，可以先初始化并做一次基线提交。这样出现不符合预期的修改时，你能清楚看到差异，也更容易恢复。

官方安装脚本会固定依赖，并通过 pi update 更新；npm 安装不固定传递依赖，应沿用 npm 管理。升级前记录 pi --version、保留配置，升级后先验证读文件、写文件和一次模型调用。当前安装要求

三、接入模型：订阅登录与 API Key

Pi 自己不提供模型算力。安装 Pi 相当于装好工作台，接下来还要告诉它去哪里调用模型。

最省事的方法是在 Pi 中输入：

/login

然后根据界面选择供应商。官方目前支持通过订阅登录使用 ChatGPT Plus/Pro（Codex）、Claude Pro/Max、GitHub Copilot 等服务，也支持 OpenAI、Anthropic、DeepSeek、Gemini、Kimi、MiniMax 等 API Key 供应商。具体可用项会随着版本和地区变化，以 /login 页面和官方 Providers 文档为准。

如果使用 DeepSeek 官方接口，可以在启动 Pi 前设置环境变量：

export DEEPSEEK_API_KEY="你的_API_Key"
pi

也可以通过 /login 选择相应供应商并保存密钥。Pi 的认证信息默认保存在 ~/.pi/agent/auth.json。不要把 API Key 写进项目源码、提交到 Git，或复制到公开截图中。

进入 Pi 后输入：

/model

即可搜索和切换模型，也可以按 Ctrl+L 打开模型选择。DeepSeek 官方当前推荐 deepseek-flash，由 DeepSeek-V4.1-Flash-1017 提供服务；旧 deepseek-v4-flash 是兼容别名，不代表还在运行旧模型。在 /model 中核对提供商与实际请求名；本地目录没有正式名称时，先更新 Pi，再按提供商文档处理。DeepSeek 调用说明

为什么我推荐这套组合？

速度首先决定了代理是否好用。编程代理会频繁读取文件、调用工具和继续生成。如果每一步都要等很久，思路很容易被打断。DeepSeek Flash 的快速响应让连续修改更接近人与工具协作，而不是提交工单后等待。

性能决定了速度有没有价值。真正的项目任务不是补全一行代码，还包括理解目录结构、追踪调用关系、遵循现有风格、处理错误并验证结果。以我目前的体验，它足以承担大量日常开发、排错、重构和文档任务。

价格则决定了你敢不敢高频使用。代理任务通常会消耗大量上下文和输出 token。成本足够低时，你才会愿意让它先调查、再计划、再修改、再测试，而不是为了省 token 省略必要步骤。价格与计费仍应以你选择的实际供应商页面为准。

四、第一次使用，不要急着让它改代码

启动后，我建议第一个任务只读不写：

请先阅读当前项目，不要修改任何文件。告诉我：
1. 这个项目解决什么问题；
2. 主要入口和关键模块在哪里；
3. 如何本地运行与测试；
4. 目前最明显的风险或缺失信息是什么。

这一步有三个作用：确认 Pi 进入了正确目录；观察模型能否理解项目；检查它会不会遵守“不要修改”的约束。

你可以用 @ 明确引用文件：

请阅读 @README.md 和 @package.json，核对文档里的启动命令是否与脚本一致。

也可以直接执行命令：

!npm test

如果不希望命令输出进入对话上下文，可以使用两个感叹号：

!!git status

这些小功能很重要。代理不是知道得越多越好，而是要得到与当前决策有关、又尽量干净的上下文。

五、一套更可靠的日常工作流

我日常使用的闭环是：调查、计划、修改、验证、复核。

调查阶段，让 Pi 先找到相关文件和现有逻辑，不要一上来重写：

先定位登录状态丢失的原因。只做读取和诊断，列出证据、涉及文件和你认为最可能的根因，不要修改代码。

计划阶段，让它把修改范围说清楚：

基于刚才的诊断，给出最小修改方案。说明准备改哪些文件、为什么改、可能影响什么，以及如何验证。

确认方向后再实施：

按最小方案实施。保留现有接口，不新增依赖。完成后运行相关测试，并汇总实际修改。

最后要求复核：

检查 git diff 和测试结果。寻找遗漏、回归风险、临时代码、敏感信息和没有验证的假设。若发现问题，先说明再修复。

这套写法比“帮我修一下”多几行，却能显著减少代理误判。一个好任务至少要包含五类信息：目标、范围、约束、验收标准和禁止事项。

例如：

目标：修复移动端菜单打开后页面仍可滚动的问题。
范围：只处理导航组件及相关样式。
约束：不引入新依赖，不改变桌面端布局。
验收：iPhone 宽度下打开菜单后背景不可滚动，关闭后恢复；现有构建通过。
禁止：不要部署，不要修改环境变量。

六、用 AGENTS.md 给项目立规矩

重复解释项目规则很浪费时间。Pi 会读取用户级的 ~/.pi/agent/AGENTS.md，也会读取项目当前目录及父目录中的 AGENTS.md 或 CLAUDE.md。你可以在项目根目录建立 AGENTS.md：

# Project instructions

- 修改前先阅读 README.md 和 package.json。
- 搜索文件优先使用 rg。
- 不要读取、输出或修改 .env 文件。
- 不新增依赖，除非任务明确要求。
- 完成代码修改后运行 npm test 和 npm run build。
- 未经明确要求，不部署、不推送、不创建外部资源。
- 最终说明修改文件、验证结果和剩余风险。

规则应该具体、可执行、可验证。不要写“请保持代码优雅”这种每个人理解不同的句子。更好的表达是“沿用现有组件结构”“单个函数不承担网络请求与 UI 渲染两类职责”“新增行为必须有对应测试”。

如果进入一个不受信任的新项目，Pi 会询问是否信任。这个机制控制项目资源和指令文件是否加载，但它不是安全沙箱。选择不信任，并不意味着模型执行的所有命令都会被隔离。

七、会话、分支与上下文管理

Pi 会把会话保存在 ~/.pi/agent/sessions/。退出终端不等于工作消失。

常用方式包括：

pi -c            # 继续最近一次会话
pi -r            # 选择并恢复会话
pi --name auth-fix

交互界面里常用的命令有：

当一个任务出现两种可行方案时，不必把主线对话搅乱。可以在关键节点使用 /fork，分别探索方案 A 和方案 B。上下文太长时使用 /compact，但压缩属于摘要，不可能无损保留每个细节。关键约束最好放进项目文件、任务说明或测试，而不是只存在于很久以前的一轮对话中。

八、Pi 真正强大的地方：可以继续搭建

当前 Pi 还内置 MCP：用户配置位于 ~/.pi/agent/mcp.json，项目配置位于 .pi/mcp.json，项目配置受信任状态控制。用 pi mcp list 核对服务；旧的 MCP 扩展可能覆盖内置 /mcp，升级后要检查实际生效的是哪一套。接通服务不等于已获所有数据权限。MCP 配置

Pi 的核心很小，但可以通过 TypeScript Extensions、Skills、Prompt Templates、Themes 和 Pi Packages 扩展。

你可以把它们理解成五类能力：

• Extension：增加工具、命令、事件处理和界面行为；
• Skill：给代理一套针对特定任务的操作说明；
• Prompt Template：保存经常复用的任务提示词；
• Theme：调整终端界面外观；
• Pi Package：把扩展、技能和模板打包分发。

刚开始不要急着装一大堆扩展。先用默认工具跑通几个真实任务，记录重复动作，再决定哪些值得固化。例如每次发布前都要检查链接、构建和 Git 状态，就适合写成模板或 Skill；只有某个项目会用到的命令，放进项目级规则往往更清楚。

Pi 也支持非交互模式：

pi -p "总结当前项目结构"

还提供 JSON 和 RPC 模式，便于接入脚本或其他应用。自动化时应收紧工具范围，例如使用 --tools、--exclude-tools 或 --no-tools，并让程序根据退出码和结构化结果判断成功，不能只检查“模型有没有输出一段看起来像完成的话”。

九、安全边界：Pi 能做事，也真的能做错事

直接在本机启动 Pi 时，命令使用当前操作系统用户的权限。当前官方区分整套 Pi 放进隔离环境，以及只隔离内置工具两种做法；后者不能隔离主进程和其他扩展。工作目录和项目信任都不是文件访问边界。运行安全说明这意味着它可能读取你有权读取的文件、修改当前用户可写的内容，也可能执行网络、包管理和 Git 命令。

我的基本规则是：

• 只在边界清楚的项目目录启动；
• 修改前确认 Git 工作区状态，并保留可恢复节点；
• 密钥放在安全的认证存储或环境变量，不写入提示词和仓库；
• 陌生仓库先不信任，先人工阅读项目指令和脚本；
• 生产数据库、服务器、发布、付款和外部消息必须单独确认；
• 自动化任务只开放必需工具；
• 高风险或无人值守场景使用容器、虚拟机或操作系统级隔离。

还有一个常见误区：模型说“测试通过”不等于测试真的通过。你应该查看实际命令、退出状态和输出。模型说“已经部署”也不等于公网版本已经更新，仍要访问正式地址做验收。

十、我会怎样开始使用 Pi

如果你今天第一次尝试，我建议按这个顺序：

1. 在一个有 Git、风险较低的小项目中安装并启动 Pi；
2. 用 /login 接入已有订阅，或配置 DeepSeek API Key；
3. 在 /model 中搜索并选择 DeepSeek Flash；
4. 先执行一次“只读项目体检”，观察它如何使用工具；
5. 交给它一个能在半小时内人工完成的小问题；
6. 使用“调查、计划、修改、验证、复核”的完整闭环；
7. 把重复出现的约束写入 AGENTS.md；
8. 熟练以后，再研究扩展、技能和自动化。

Pi 的价值并不是让人停止思考。恰恰相反，它把机械操作交给模型，让人把精力放到目标、边界、判断和验收上。

工具让人走得更快，思考决定往哪里走。

如果你也在使用 Pi，欢迎告诉我你接入了哪个模型、速度和成本如何，以及它在哪类任务上真正帮到了你。我也会继续记录 Pi + DeepSeek Flash 在真实项目中的表现。

说明：本文依据 Pi 当前官方文档与个人实测整理。工具版本、供应商、模型目录、上下文窗口、价格和速度都可能变化，请以 Pi 最新文档、模型目录及实际服务商页面为准。文中的接近 100 token/s 是特定时间、网络、供应商和任务条件下的瞬时实测结果，不代表稳定速度或性能承诺。