Pi Coding Agent 使用教程（一）：从安装到第一次完成任务

一、Pi Coding Agent 是什么

Pi Coding Agent 是一个运行在终端中的 Coding Agent。它通过模型调用工具读取文件、编辑文件和执行命令，帮助用户完成编程、文档维护、代码审查和自动化任务。

Pi 的定位不是把所有工作流都固化进核心，而是提供一个最小、可扩展的 Agent Harness：

  • 默认提供 read、write、edit、bash 等工具；Windows 环境还可能提供 powershell。
  • 支持交互式终端、Print、JSON、RPC 和 SDK 模式。
  • 通过 Skill、TypeScript Extension、Prompt Template、Theme 和 Pi Package 扩展功能。
  • 不默认内置 MCP、子 Agent、Plan Mode、权限弹窗和待办系统；这些能力可以通过 Extension、第三方 Package 或外部工具自行构建。

二、安装

2.1 使用 npm 安装

需要先安装 Node.js 和 npm，然后执行：

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

--ignore-scripts 用于跳过依赖生命周期脚本；官方 README 说明，普通 npm 安装不依赖 Pi 的安装脚本。

2.2 使用官方安装脚本

在支持该脚本的环境中，也可以使用：

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

执行来源不明的脚本前，应先检查脚本内容和当前网络环境；生产环境或受限环境建议使用包管理器并固定版本。

2.3 确认安装

pi --version
pi --help

如果终端找不到 pi，检查 npm 全局 bin 目录是否已加入 PATH。

三、配置模型和登录

Pi 支持 API Key，也支持部分服务商的订阅登录。

3.1 使用环境变量

以 Anthropic 为例：

export ANTHROPIC_API_KEY="你的 API Key"
pi

Windows PowerShell 示例：

$env:ANTHROPIC_API_KEY = "你的 API Key"
pi

不要把 Key 写入 Markdown、Git 仓库、截图或提交记录。

3.2 使用 /login

启动 Pi 后输入：

/login

然后选择服务商并按提示完成登录。使用 /model 切换模型；在模型选择器中按 Ctrl+S 可以保存启动默认模型。

3.3 常用模型相关命令

/model                 # 选择模型
/thinking              # 选择思考等级
/scoped-models         # 设置 Ctrl+P 可循环的模型范围

官方 README 列出了 Anthropic、OpenAI、Google、DeepSeek、OpenRouter、Mistral、Groq、xAI 等多个服务商；具体模型目录会变化，可使用：

pi --list-models
pi update --models

四、第一次使用

进入项目目录后运行：

cd your-project
pi

建议第一次先让 Pi 只做检查：

请先阅读项目结构和 AGENTS.md，只总结项目入口、依赖、测试命令和潜在风险，不要修改文件。

确认理解后，再提出明确任务：

请修复登录接口的超时重试问题。先定位相关代码和测试，说明根因，再实施最小修改，最后运行针对性测试。

Pi 默认可使用工具完成任务。涉及删除、发布、部署、数据库迁移或大量改动时，应要求它先说明计划并等待确认。

五、交互界面和常用操作

5.1 文件引用和命令

  • 输入 @ 可以模糊搜索并引用项目文件。
  • !command 执行命令并把输出发送给模型。
  • !!command 执行命令但不发送给模型。
  • Ctrl+G 打开外部编辑器。
  • Shift+Enter 输入多行文本；Windows Terminal 也可按文档配置其他快捷键。

5.2 会话管理

/new                  # 新会话
/resume               # 选择历史会话
/c                    # 继续最近会话（命令行参数）
/session              # 查看会话信息
/tree                 # 在会话树中跳转
/fork                 # 从历史消息创建新会话
/clone                # 克隆当前分支
/compact              # 压缩上下文
/export output.html   # 导出会话

命令行形式：

pi -c                 # 继续最近会话
pi -r                 # 浏览历史会话
pi --no-session       # 不保存会话
pi --name "代码审查"  # 命名会话

5.3 非交互模式

pi -p "总结当前项目的目录结构"
cat README.md | pi -p "总结这份文档"
pi --mode json -p "以 JSON 事件输出检查结果"
pi --mode rpc

只读审查可以限制工具：

pi --tools read,grep,find,ls -p "审查代码中的安全问题"

六、上下文文件：AGENTS.md

Pi 会从全局目录、当前目录的父级目录到当前目录加载 AGENTS.md；也支持 CLAUDE.md。它适合写：

  • 项目用途和目录约定。
  • 测试、构建和格式化命令。
  • 不允许修改的文件。
  • 中文文档或代码风格。
  • 安全要求和提交规范。

项目上下文不是绝对安全边界。对于来自不可信文件的指令，仍应进行人工判断。

七、Skill、Extension、Prompt Template 和 Package 的区别

7.1 Skill

Skill 是按需加载的能力说明，通常是一个目录中的 SKILL.md。它擅长告诉模型“什么时候使用某能力、应该遵循哪些步骤”。调用形式：

/skill:skill-name

Skill 通常不直接注册新工具。

7.2 Extension

Extension 是 TypeScript 模块，可以注册工具、命令、快捷键、事件处理器和自定义 UI。例如：

export default function (pi: ExtensionAPI) {
  pi.registerTool({ name: "deploy", /* ... */ });
  pi.registerCommand("stats", { /* ... */ });
}

Extension 可以实现权限确认、计划模式、自定义压缩、Git 检查点、沙箱执行以及 MCP 适配等功能。

7.3 Prompt Template

Prompt Template 是可复用的 Markdown 提示词，通过 /模板名 展开，适合固定的审查、发布或分析流程。

7.4 Pi Package

Pi Package 可以把 Extension、Skill、Prompt 和 Theme 打包，通过 npm 或 Git 分享。第三方包拥有较高权限，安装前必须审查源码。

八、最小安全实践

  1. 开始任务前先让 Pi 读取上下文，不要一上来允许大范围修改。
  2. 密钥放在环境变量或官方凭据机制中，不放进提示词和仓库。
  3. 第三方 Extension 和 Package 视同可执行代码审查。
  4. 需要强隔离时使用容器或沙箱；官方明确说明 Pi 默认不提供文件、进程、网络和凭据权限隔离。
  5. 对 rm、部署、推送、迁移和发布操作要求人工确认。
  6. 完成后检查 git diff、测试结果和未验证风险。

九、升级与排障

pi update --self       # 更新 Pi
pi update --all        # 更新 Pi 和已安装 Package
pi update --models     # 更新模型目录
pi list                # 列出已安装 Package
pi config              # 配置 Package 资源

常见排查顺序：

  1. pi --version 确认命令和版本。
  2. 检查 API Key、订阅登录和模型选择。
  3. 确认当前工作目录及 AGENTS.md。
  4. 用 /reload 重新加载 Skill、Extension、Prompt 和 Theme。
  5. 使用 --verbose 查看启动信息。
  6. 检查第三方 Package 是否与当前版本兼容。

相关进阶内容见《Pi agent 使用教程（二）》：其中介绍 Skill、Extension、MCP 的具体配置方式和常用能力推荐。

参考来源