Pi 介绍与基本使用

Pi 是什么？

Pi 是一个面向开发者的命令行 AI 编程代理（coding agent）。它能在项目目录中读取、创建和修改文件，也可以运行终端命令，帮助开发者理解代码、实现功能、排查问题和执行常规开发流程。

但 Pi 不只是一个“在终端里聊天写代码”的工具。官方将它定义为一个轻量的 agent harness，也就是 AI 编程代理的运行底座：它提供基础能力，但不强行规定你应该怎样使用 AI，而是允许你把它改造成符合自己习惯的工作环境。

Pi 官方网站https://pi.dev/

它解决什么问题？

大多数 AI 编程工具提供的是一套预设好的体验：固定的界面、固定的权限弹窗、固定的任务规划方式，以及相对固定的模型接入方式。这样的产品对新手很友好，但当用户有自己的项目规范、脚本工具、模型偏好或团队流程时，工具本身也可能成为限制。

Pi 的思路是保留一个足够轻的核心，再让用户决定要增加哪些能力。它支持多模型、项目级规则、会话分支、提示词模板、技能、扩展和自动化接口。换句话说，Pi 的重点不是替你决定工作流，而是让你拥有并调整自己的工作流。

和 Cursor、Claude Code、Codex 这类产品有什么不同？

最核心的区别是：Pi 更像“可改造的底座”，而不是开箱即用的完整产品。

维度	Pi	常见一体化 AI 编程工具
产品思路	轻量核心，按需组合能力	功能预置，开箱即用
可定制性	很高，可写扩展、技能、模板、主题	通常受产品边界限制
模型选择	可接入多家服务商和多种模型	往往围绕少量模型或固定接入方式
上手门槛	较高，需要接受终端与配置	较低，图形界面和引导更多
默认功能	有意保持克制	常内置计划、多代理、权限管理、任务管理等
适合场景	个性化工作流、自动化、技术用户	快速完成日常开发任务

Pi 的优势不在于“默认功能最多”，恰恰在于它不强加工作流。子代理、计划模式、权限弹窗、MCP 等能力并非全部内置，而是让用户按需自行实现或安装扩展。

那怎样把 Pi 这个“底座”越用越丰富？

Pi 的核心保持轻量，但预留了多层扩展方式。可以理解为：先有一个能读写代码、执行终端命令的 AI 助手，再按需求把自己的开发流程逐步装进去。

Extensions（扩展）：用 TypeScript 为 Pi 增加工具、斜杠命令、快捷键、事件处理和终端 UI。例如自定义审批流程、子代理、MCP 接入或状态栏。
Skills（技能）：将可重复使用的流程包装为按需加载的能力，例如代码审查规范、部署流程或数据库排查指南。
Prompt Templates（提示词模板）：把常用提示保存为 Markdown 文件，之后通过 /review、/release 之类的命令快速调用。
Themes（主题）：调整终端中的显示风格。
自定义模型与供应商：可配置私有模型接口、模型网关或自定义 OAuth 流程。
Pi Packages（Pi 包）：将扩展、技能、提示词和主题打包并分享，是复用他人成果最方便的方式。

如果想找现成内容，优先推荐官方的 Pi Packages Gallery。它适合发现专门为 Pi 制作的扩展、技能包、提示词和主题。

Pi 包主要可从两类平台获取：

npm：适合搜索和安装已发布的包；
GitHub：适合寻找开源项目、查看源码、Issue 与维护状态。

例如：

1 2	pi install npm:@作者/包名 pi install git:github.com/作者/仓库

如果只是临时试用某个包，不希望改动本地配置，可以使用：

1	pi -e npm:@作者/包名

需要注意的是，Pi 默认没有内置 MCP。若需要 MCP，可以通过 Pi 扩展包或自行编写扩展接入。安装第三方包前最好先看源码和维护情况：Pi 的扩展可以执行代码，技能也可能引导模型运行本机命令，因此应像安装其他开发工具一样审慎。

Pi 的优势

自由度高：能让 AI 适配个人或团队的工作方式，而不是让人适应工具。
模型选择广：可接入 OpenAI、Anthropic、Google、Azure、Bedrock、Ollama、OpenRouter 等服务，并可在会话中切换模型。
上下文管理可控：可利用项目说明、系统提示、技能和上下文压缩策略，控制 AI 了解哪些项目规则。
适合自动化：除交互式终端外，还支持 Print/JSON、RPC 与 SDK，可嵌入脚本、CI 或内部平台。
会话可回溯：树状会话历史允许从此前任意节点继续、分支尝试或导出分享。

它的代价是什么？

Pi 并不一定适合所有人。它的“极简”意味着很多能力需要用户自己选择、安装或搭建，例如权限确认、子代理、计划管理和后台执行。

因此，如果你希望“安装完就点几下按钮直接使用”，Pi 的学习成本会高于带完整图形界面的产品；如果你重视模型选择权、项目规则和工作流控制权，Pi 的吸引力会更强。

极简上手介绍

1. 安装 Pi

推荐使用 npm 安装：

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

然后进入项目目录并启动：

1 2	cd 你的项目目录 pi

Pi 以当前目录作为工作范围，默认可读取、创建、修改文件和执行命令。

2. 登录或配置模型

Pi 本身不提供模型，它负责把已有订阅或 API 接入你的终端开发流程。

方式 A：使用已有订阅登录

启动 Pi 后输入：/login

然后按提示选择服务商并在浏览器中完成授权。可使用的订阅登录包括：

ChatGPT Plus / Pro（Codex）
Claude Pro / Max
GitHub Copilot
xAI 的 Grok/X 订阅
OpenRouter 等

如果需要清除登录状态，可输入：/logout

方式 B：使用 API Key

若使用 OpenAI、Anthropic、Gemini、DeepSeek、OpenRouter 等 API，可通过环境变量配置。以 Windows PowerShell 和 OpenAI 为例：

1 2	$env:OPENAI_API_KEY="你的_API_Key" pi

也可以先进入 Pi，输入 /login，选择 API Key 对应的服务商并粘贴密钥。Pi 会将凭据保存到本机配置中，之后无需重复输入。

如果已经拥有 ChatGPT Plus/Pro、Claude Pro/Max 或 GitHub Copilot，优先使用 /login 会更方便；没有订阅时，再选择熟悉的 API 平台并配置 Key。

3. 选择模型

在 Pi 中输入：/model，或按 Ctrl + L，即可选择模型。

一个实用的用法是：用更快、成本更低的模型阅读项目和处理简单任务，再切换到更强的模型完成复杂设计、重构或代码审查。

5. 给 Pi 一份项目说明书

在项目根目录创建 AGENTS.md，说明项目规则，例如：

# Project Instructions

- 修改代码后必须运行 npm run check。
- 不要执行生产环境迁移。
- 优先复用现有组件，不随意引入依赖。
- 回复时先说明计划，再开始修改。

Pi 启动时会读取当前目录及父目录中的 AGENTS.md 或 CLAUDE.md。修改这些文件后，可重启 Pi，或输入 /reload 重新加载，这样就能让它从泛用助手变成了解项目规范的协作者。

6. 第一次任务：先理解，再修改

第一次不建议直接让 Pi “优化整个项目”，而应从范围明确、可验证的小任务开始。

先输入：

1
2
3

阅读 README、package.json 和主要目录结构。
告诉我：这个项目做什么、如何启动、如何运行测试，
以及最适合新手先理解的三个文件。

确认回答合理后，再提出一个具体改动：

1 2	为首页的提交按钮添加加载状态。先说明会修改哪些文件和验证方法；在我确认后再修改。

这种“先理解—再计划—再执行—再验证”的方式，通常比一句“帮我优化项目”更可靠。

7. 几个立刻有用的操作

目标	操作
引用文件让 Pi 重点阅读	输入 `@` 搜索文件，或 `pi @README.md "总结这个文件"`
在会话中运行命令并让模型读取结果	`!npm run lint`
只运行命令，不将结果发给模型	`!!npm run lint`
切换模型	`/model` 或 `Ctrl + L`
新开会话	`/new`
查看或回到历史分支	`/tree`
继续最近会话	`pi -c`
浏览旧会话	`pi -r`
一次性脚本调用	`pi -p "总结这个代码库"`