Pi Agent 入门：轻量、可扩展的终端编码助手

现在的编码 Agent 越来越多，差异不只在模型能力，也在“它到底把多少工程工作流暴露给你控制”。有的产品像完整 IDE，有的更像托管平台；Pi Agent 选择了一条偏工程师的路线：把核心保持得很小，主要运行在终端里，再通过扩展、技能、提示模板、主题和包去补齐团队需要的能力。

Pi 官方文档对它的定位很直接：Pi 是一个 minimal terminal coding harness。这句话里的关键词不是“AI”，而是“harness”。它更像一个把模型、工具、上下文、会话和扩展系统串起来的终端执行框架，而不是一个只负责聊天的助手。

Pi Agent 是什么

Pi Agent，也就是 Pi Coding Agent，是一个基于终端的编码 Agent。它在当前工作目录中运行，默认给模型提供四类基础工具：读取文件、写入文件、补丁式编辑文件，以及执行 shell 命令。除此之外，grep、find、ls 等只读工具也可以通过工具选项启用。

这意味着 Pi 的使用姿势非常接近日常开发：进入项目目录，启动 pi，让它阅读仓库、修改代码、运行检查、解释错误，再把会话保存下来供之后继续。它不是把开发者从终端里拉走，而是把 Agent 放进终端。

flowchart LR
    A[项目目录] --> B[启动 pi]
    B --> C[加载 AGENTS.md / CLAUDE.md]
    C --> D[选择模型和认证 Provider]
    D --> E[读取、编辑、执行命令]
    E --> F[保存会话 / 继续会话]
    E --> G[扩展、技能、包增强能力]

Pi 的核心设计可以概括成三点：

终端优先：从项目目录启动，围绕文件、命令和会话工作。
小核心、强扩展：把自定义命令、工具、生命周期事件、模型提供商等能力交给 TypeScript 扩展和 Pi packages。
多 Provider 接入：既支持订阅型 Provider 登录，也支持 API key、云厂商和自定义 Provider。

安装与认证

Pi 通过 npm 包分发，官方推荐的安装命令是：

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

这里的 --ignore-scripts 用来禁用依赖安装阶段的生命周期脚本。Pi 的普通 npm 安装不依赖 install scripts，这个参数能降低安装第三方依赖时不必要的执行风险。

安装完成后，在希望它工作的项目目录里启动：

1
2
cd /path/to/project
pi

认证有两条主线。

第一种是订阅登录。在交互模式里执行：

1
/login

然后选择 Provider。官方文档列出的内置订阅登录包括 Claude Pro/Max、ChatGPT Plus/Pro（Codex）和 GitHub Copilot。

第二种是 API key。比如使用 Anthropic 时，可以在启动前设置环境变量：

1
2
export ANTHROPIC_API_KEY=sk-ant-...
pi

也可以在交互模式里通过 /login 选择 API-key Provider，把 key 存到 ~/.pi/agent/auth.json。当 Pi 解析 Provider 凭据时，文档列出的优先级是：CLI 的 --api-key 参数、auth.json 中的 API key 或 OAuth token、环境变量、models.json 中的自定义 Provider key。

第一次会话怎么用

Pi 启动后，直接输入自然语言任务即可。例如：

1
Summarize this repository and tell me how to run its checks.

默认情况下，模型可以读取文件、写文件、编辑文件和执行 shell 命令。因为 Pi 在当前工作目录里运行，并且可以修改文件，建议把它放在已有 Git 管理的项目里使用：需要回滚时，git diff 和分支就是最简单的安全网。

如果你希望 Pi 遵守项目规则，可以在仓库里放一个 AGENTS.md：

1
2
3
4
5
# Project Instructions

- Run `npm run check` after code changes.
- Do not run production migrations locally.
- Keep responses concise.

Pi 启动时会加载全局的 ~/.pi/agent/AGENTS.md，也会加载父目录和当前目录里的 AGENTS.md 或 CLAUDE.md。修改这些上下文文件后，可以重启 Pi，或者在会话中执行 /reload 重新加载。

文件、命令和模型切换

在交互编辑器里输入 @ 可以模糊搜索文件，也可以在命令行里直接把文件作为上下文传进去：

1
2
pi @README.md "Summarize this"
pi @src/app.ts @src/app.test.ts "Review these together"

运行 shell 命令也很自然。在交互模式中使用 ! 前缀：

1
!npm run lint

这类命令的输出会进入模型上下文。如果只是想执行命令但不把输出加入上下文，可以使用 !!command。

模型切换也放在交互体验里：使用 /model 或 Ctrl+L 选择模型；使用 Shift+Tab 切换 thinking level；使用 Ctrl+P 或 Shift+Ctrl+P 在 scoped models 之间切换。对经常在不同模型之间权衡速度、成本和推理能力的人来说，这比每次改配置文件更顺手。

会话管理与非交互模式

Pi 会自动保存会话。常用恢复命令如下：

1
2
3
pi -c                 # 继续最近一次会话
pi -r                 # 浏览历史会话
pi --session <path|id> # 打开指定会话

在 Pi 内部，也可以通过 /resume、/new、/tree、/fork、/clone 管理会话。这个能力很适合处理长期任务：例如先让 Agent 读仓库和定位问题，再 fork 一个会话尝试不同修复路径。

对于一次性任务，Pi 提供非交互模式：

1
2
3
pi -p "Summarize this codebase"
cat README.md | pi -p "Summarize this text"
pi -p @screenshot.png "What's in this image?"

如果要做自动化集成，可以使用 --mode json 输出 JSON 事件，或者用 --mode rpc 做进程级集成。这样 Pi 不只是一个人工交互工具，也能进入脚本、CI 辅助流程或上层工作台。

Provider：不把选择绑死在单一模型上

Pi 的 Provider 设计覆盖面比较广。官方文档把它分成几类：

订阅型 Provider：通过 /login 使用 OAuth 登录，例如 Claude Pro/Max、ChatGPT Plus/Pro（Codex）、GitHub Copilot。
API key Provider：通过环境变量或 ~/.pi/agent/auth.json 提供凭据。
云 Provider：包括 Azure OpenAI、Amazon Bedrock、Cloudflare AI Gateway、Cloudflare Workers AI、Google Vertex AI 等。
自定义 Provider：可以通过 models.json 接入 Ollama、LM Studio、vLLM，或者任何兼容 OpenAI Completions、OpenAI Responses、Anthropic Messages、Google Generative AI 等 API 形态的服务；更复杂的 OAuth 或自定义 API 则可以通过扩展实现。

这带来的好处是：Pi 的工作流不用和某一个模型或厂商强绑定。团队可以把“怎么改代码、怎么跑检查、怎么保存会话”沉淀在 Pi 的上下文和扩展里，同时根据任务切换不同模型。

需要注意，订阅登录不等于所有调用都自动计入订阅套餐。不同 Provider 的额度和计费规则不同，例如 Pi 文档特别说明 Claude Pro/Max 的第三方 harness 用量走 extra usage，并按 token 计费，而不是消耗 Claude 订阅套餐内的额度。

扩展、技能和包

Pi 的核心小，但扩展面很大。

Extensions 是 TypeScript 模块，可以订阅生命周期事件、注册自定义工具、增加 slash command、改 UI、注册 Provider，甚至覆盖内置工具。开发调试时可以用 pi -e ./path.ts 快速加载；长期使用时放到 ~/.pi/agent/extensions/ 或 .pi/extensions/，然后用 /reload 热重载。

Skills 是按需加载的能力包。一个技能可以包含专门工作流、配置说明、辅助脚本和参考文档。Pi 实现了 Agent Skills 标准，并会在任务匹配时加载对应的 SKILL.md。技能也可以注册成 /skill:name 命令，适合把“写发布说明”“审查 Dockerfile”“处理某类云资源”这类重复工作固化下来。

Pi packages 用来打包和分发扩展、技能、提示模板和主题。可以从 npm、Git 或本地路径安装：

1
2
3
pi install npm:@foo/bar@1.0.0
pi install git:github.com/user/repo@v1
pi install ./relative/path/to/package

包也可以用 pi update 更新，用 pi config 启用或禁用其中的扩展、技能、提示模板和主题。项目级配置写在 .pi/settings.json，全局配置写在 ~/.pi/agent/settings.json；如果团队想共享一套 Agent 能力，可以把项目级 Pi 配置提交到仓库里。

不过，这里也有明确的安全边界。官方文档提醒：Pi packages 以完整系统权限运行；扩展可以执行任意代码；技能可以指示模型执行动作，甚至调用可执行文件。因此第三方包、扩展和技能都应该像 shell 脚本、npm 包或 CI 插件一样审查来源和内容。

Pi 的优势在哪里

Pi 最突出的优势不是“多一个聊天入口”，而是它把编码 Agent 做成了一个可组合的终端运行时。

第一，上手成本低。安装后进入项目目录运行 pi，用 /login 或 API key 完成认证，就能开始让它读仓库、改代码、跑命令。上下文文件用 AGENTS.md 或 CLAUDE.md 表达，和当前主流 Agent 工作流保持一致。

第二，对工程工作流友好。文件引用、shell 命令、会话恢复、非交互模式、JSON/RPC 输出，都是开发者能直接接进现有流程的接口。它不要求你把项目迁移到某个新平台，也不强迫你离开终端。

第三，模型和 Provider 选择灵活。订阅登录、API key、云厂商、自定义 Provider 都在一个工具里统一调度。对个人开发者来说，可以按手头订阅选择模型；对团队来说，可以通过 Provider 和 models.json 把内部模型、代理网关或本地模型接进来。

第四，扩展体系有想象力。很多 Agent 工具只开放配置项，Pi 则把生命周期事件、命令、工具、UI、Provider、技能和包都放进扩展面。它更适合喜欢把规则沉淀成工具的人：例如代码审查命令、项目初始化向导、内部工单补全、受控的远程命令执行、模型切换策略，都可以变成团队共享能力。

第五，边界足够透明。Pi 明确告诉你它能修改当前目录、扩展有系统权限、包和技能需要审查。对工程工具来说，这种透明比“假装无风险”更重要。只要配合 Git、最小化安装第三方包、把敏感操作写进 AGENTS.md 约束，Pi 可以成为一个可控的本地 Agent 执行入口。

适合谁使用

如果你主要想要一个“开箱即用、不关心配置”的图形化 AI 编辑器，Pi 可能不是最省心的选择。它更适合这些人：

长期在终端和 Git 工作流里开发，希望 Agent 不打断原有节奏；
经常在多个模型、订阅账号、API key 或云 Provider 之间切换；
想把团队规则写进 AGENTS.md、扩展、技能和项目级 .pi/settings.json；
需要把 Agent 接入脚本、自动化流程或上层工作台；
愿意审查第三方扩展和包，而不是盲装插件。

我的判断是：Pi Agent 的价值在“轻量”和“可编排”之间取得了不错的平衡。它不像完整 IDE 那样替你规定工作空间，也不像单一 CLI 聊天工具那样止步于对话。对于已经习惯终端开发、又希望把 AI Agent 逐步纳入工程规范的人，Pi 值得认真试用。