pi agent安装使用

Pi Agent 安装与使用指南：从终端编码到自定义模型接入

Pi 是一个运行在终端里的 Coding Agent。进入项目目录后，它可以阅读代码、搜索文件、执行命令、修改文件，并围绕同一会话持续推进任务。

本文主要介绍 Pi 的安装、模型接入、常用命令、项目级上下文、CLI 自动化和问题排查，适合第一次使用 Pi 的开发者，也适合需要接入第三方模型 API 的用户。

1. Pi 是什么

Pi（Pi Coding Agent）是一套轻量、可扩展的终端编程代理。

它的核心能力包括：

• 阅读和分析项目代码。
• 搜索文件、执行 Shell 命令。
• 创建文件、修改已有代码。
• 在同一会话中持续完成多步骤开发任务。
• 通过 Skills、Extensions、Prompt Templates 等机制扩展能力。

相比于一开始就安装大量插件，更推荐先使用原生功能，再根据实际工作流逐步扩展。

官网与项目地址：

• 官网：https://pi.dev/
• GitHub：https://github.com/earendil-works/pi
• 官方 Quickstart：https://pi.dev/docs/latest/quickstart

2. Pi 的安装

2.1 检查 Node.js

通过 npm 安装时，官方当前要求 Node.js 22.19 或更高版本。

先检查本机环境：

node-vnpm-v

如果版本不满足要求，需要先升级 Node.js。

2.2 macOS / Linux

可以使用官方安装脚本：

curl-fsSLhttps://pi.dev/install.sh|sh

也可以使用 npm 安装：

npminstall-g--ignore-scripts @earendil-works/pi-coding-agent

2.3 Windows

在 PowerShell 中执行：

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

检查安装结果：

pi--version

原生 Windows 环境建议同时安装 Git for Windows，供 Pi 使用 Bash 执行命令。如果项目和开发工具链主要位于 Linux 环境，也可以在 WSL 中运行 Pi。

Windows 环境说明：https://pi.dev/docs/latest/windows

2.4 验证安装

pi--versionpi--help

如果执行pi提示找不到命令，优先检查 npm 全局安装目录是否加入了PATH，修改后重新打开终端。

3. 第一次启动与模型登录

进入准备交给 Pi 操作的项目目录：

cd/path/to/your/project pi

进入交互界面后，执行：

/login

按照提示选择支持的 Provider，完成订阅授权或 API Key 配置。

登录后选择模型：

/model

如果需要调整模型的思考级别，可以使用：

/thinking

通常情况下，支持的官方 Provider 可以直接通过/login使用，不需要手写模型配置文件。

如果接入的是第三方兼容 API、自建推理服务或者 API 中转端点，则可以继续配置models.json。

官方模型配置文档：https://pi.dev/docs/latest/models

4. 配置自定义模型

4.1 配置文件位置

Pi 默认将用户级配置存放在~/.pi/agent/目录中。

常用文件如下：

Windows 下，~通常对应当前用户目录，例如：

C:\Users\用户名\.pi\agent\

如果目录不存在，可以手动创建。

项目级配置则主要放在项目根目录下的.pi/目录中，例如.pi/settings.json。

配置文件说明：https://pi.dev/docs/latest/configuration

4.2 配置 OpenAI 兼容 API

创建文件：

~/.pi/agent/models.json

示例配置：

{"$schema":"https://pi.dev/schemas/models.schema.json","providers":{"my-api":{"baseUrl":"https://api.example.com/v1","api":"openai-completions","apiKey":"$MY_API_KEY","models":[{"id":"my-model-id","name":"My Model","reasoning":true,"input":["text"],"contextWindow":128000,"maxTokens":8192}]}}}

主要字段说明：

• my-api：自定义 Provider 名称，可以自行命名。
• baseUrl：服务商提供的 API 根地址。
• api：请求协议类型。openai-completions对应 Chat Completions 风格接口；如果服务端使用 Responses API，则应配置对应的openai-responses。
• apiKey：API 密钥。示例使用环境变量，避免将密钥直接写进配置文件。
• id：服务端实际接受的模型 ID。
• name：模型在界面中显示的名称。
• reasoning：模型是否支持相应的推理能力。
• input：模型接受的输入类型，例如文本或图片。
• contextWindow：上下文窗口大小。
• maxTokens：最大输出 Token 数量。

其中模型 ID、上下文长度、最大输出长度和输入能力都应以实际服务商文档为准，不要直接复制其他模型的参数。

在 macOS / Linux 当前终端中设置环境变量：

exportMY_API_KEY='替换成你的真实密钥'

PowerShell 中：

$env:MY_API_KEY ='替换成你的真实密钥'

然后启动 Pi，并打开模型选择器：

/model

如果模型没有出现，需要检查 JSON 格式、API 地址、协议类型、模型 ID，以及启动 Pi 的进程能否读取到对应环境变量。

注意：不要把真实 API Key 提交到 Git 仓库，也不要把含有密钥的配置或请求日志公开分享。

4.3 命令行指定模型

可以在启动时直接指定 Provider 和模型：

pi--providermy-api--modelmy-model-id

也可以执行一个一次性任务：

pi--providermy-api--modelmy-model-id\--print"总结当前项目结构"

这里的my-api和my-model-id必须和配置文件中的名称、模型实际 ID 对应。

5. 用 AGENTS.md 固化项目规则

如果每次启动 Pi 都需要重复说明项目结构、代码风格和测试方式，可以将这些信息写入项目根目录下的AGENTS.md。

例如：

# 项目开发说明 - 修改前先阅读 README 和相关模块代码。 - 优先使用现有架构、命名规范和依赖。 - 不要随意引入新的第三方库。 - 修改后运行相关单元测试或静态检查。 - 不要擅自修改生产环境、签名或密钥配置。 - 完成后总结修改文件、关键变更和测试结果。

这类文件适合记录长期有效的规则。某一次任务的临时需求则直接写在当前提示词中，避免长期上下文越来越臃肿。

对于 Android 项目，还可以进一步写明：

## Android 开发约束 - 修改前检查模块依赖和现有架构。 - 优先遵循项目已有的 Java/Kotlin 风格。 - 不要未经确认修改 Gradle 插件版本或依赖版本。 - 修改 JNI、线程和生命周期相关代码时，说明潜在风险。 - 如果设备或模拟器不可用，明确说明哪些测试未执行。

这样可以减少重复沟通，并让模型更容易遵循项目自身的开发约定。

6. 常用快捷操作与斜杠命令

日常开发最值得先熟悉的命令：

编辑器里还可以使用以下操作：

• 输入@，搜索并引用项目文件。
• 使用!命令执行 Shell 命令，并将输出交给模型。
• 使用!!命令执行 Shell 命令，但不把输出放进模型上下文。

快捷键会受到系统和终端配置影响，具体以当前版本文档为准：

https://pi.dev/docs/latest/keybindings

7. CLI 用法：把 Pi 用进开发工作流

Pi 不仅能交互运行，也可以在脚本中执行一次性任务。

7.1 交互模式

pi

7.2 继续最近一次会话

pi--continue

7.3 一次性分析项目

pi--print"总结当前项目的模块划分和主要依赖"

7.4 引用文件

pi @README.md--print"总结项目的构建和启动流程"

7.5 审查 Git 变更

gitdiff|pi--print\"审查这些代码改动，重点检查潜在 Bug 和遗漏的测试"

7.6 输出 JSON 事件

pi--modejson"检查当前项目并列出风险">pi-events.jsonl

其中，--print适合单次执行并输出最终回答；--mode json则可以让其他程序消费结构化事件。

这意味着 Pi 可以逐步接入代码审查脚本、自动化检查和 CI 工作流。不过，在接入无人值守任务之前，应先验证命令执行范围、退出行为及异常处理。

CLI 完整文档：https://pi.dev/docs/latest/cli

8. 扩展机制：Skills、Prompts、Extensions 和 Packages

Pi 提供了几种不同层次的扩展方式：

• AGENTS.md：提供持续生效的项目背景和约束。
• Skills：把重复任务整理成可复用的步骤和参考资料。
• Prompt Templates：保存常用提示词。
• Extensions：增加工具、事件处理逻辑或交互行为。
• Packages：将扩展、技能、主题和提示模板打包分发。

建议按照需求选择：

如果只是要求模型遵循特定代码风格，优先编写项目规则；如果某类任务经常重复，可以进一步整理成 Skill；只有当确实需要添加工具或改变行为时，再开发或安装 Extension。

官方扩展包文档：https://pi.dev/docs/latest/packages

第三方包可能执行代码，因此安装前应检查项目来源和实现，不要只因为名称熟悉就直接授权。

9. 常见问题排查

9.1pi命令不存在

检查 npm 安装状态和全局可执行目录：

npmlist-g@earendil-works/pi-coding-agent

必要时检查PATH，然后重新打开终端。

9.2 模型无法显示或登录失败

检查以下内容：

1. Provider 名称是否正确。
2. models.json是否为合法 JSON。
3. API Key 是否能被当前终端进程读取。
4. 模型 ID 和 API 地址是否正确。
5. api类型是否与服务端协议匹配。

9.3 API 返回 400 或 404

常见原因包括路径不正确、模型 ID 不匹配、协议类型错误，或服务端不支持请求中某些字段。

先核对服务商的接口文档，再逐项缩小问题范围。不要只凭服务商宣称“兼容 OpenAI”就假设所有接口行为都完全一致。

9.4 Windows 下 Bash 不可用

原生 Windows 环境下，Pi 默认会尝试寻找 Git Bash。

安装 Git for Windows 后，重新打开终端，再进入 Pi 执行：

!printf 'Bash is working\n'

如果项目工具链主要位于 Linux，也可以直接在 WSL 中运行 Pi。

9.5 如何观察模型请求

网络问题可以通过受控的本机调试代理进行排查，并根据代理工具说明配置代理环境变量及受信任的 CA 证书。

不要为了抓包而关闭 TLS 证书验证，也不要将包含授权请求头、Cookie 或 API Key 的日志上传到公开平台。很多问题同样可以通过服务端错误响应和最小化的单次任务进行复现。

10. 安全建议

Pi 可以在当前操作系统用户的权限范围内读取和修改文件，并执行命令。因此，模型生成的代码和命令都应该视为需要检查的内容。

实际使用时建议：

1. 优先在可回滚的 Git 分支中操作，关键步骤后检查git diff。
2. 不要把 API Key、SSH 私钥、生产凭据或敏感环境变量放进提示词和公开日志。
3. 对不熟悉的仓库，先检查AGENTS.md、.pi/配置及第三方扩展。
4. 删除文件、数据库迁移、发布和部署等关键操作应先制定计划，再由人确认。
5. 处理不可信代码或无人值守任务时，优先考虑容器、虚拟机或低权限环境，不要只依赖提示词约束。

官方安全说明：https://pi.dev/docs/latest/security

11. 总结

Pi 的基础使用并不复杂：

安装 CLI，通过/login接入模型，在项目目录中启动 Pi，再用AGENTS.md固化项目开发规则。接下来可以逐步学习模型切换、会话恢复、自定义 API 配置和 CLI 自动化。

建议先掌握原生功能，再按真实需求添加扩展。这样既能保留 Pi 的灵活性，也能避免过度配置，让终端 Agent 更自然地融入日常开发流程。

reference

• Pi 官网：https://pi.dev/
• Quickstart：https://pi.dev/docs/latest/quickstart
• Configuration：https://pi.dev/docs/latest/configuration
• Models：https://pi.dev/docs/latest/models
• CLI：https://pi.dev/docs/latest/cli
• Windows：https://pi.dev/docs/latest/windows
• Security：https://pi.dev/docs/latest/security