#快速开始

本页面是 Pi 官方文档 的中文翻译。仅供学习参考。

本页将带你从安装到完成第一个有用的 Pi 会话。

#安装

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

yarn add -g @earendil-works/pi-coding-agent

pnpm add -g @earendil-works/pi-coding-agent

bun add -g @earendil-works/pi-coding-agent

deno add -g npm:@earendil-works/pi-coding-agent

--ignore-scripts 在安装期间禁用依赖生命周期脚本。Pi 的正常 npm 安装不需要安装脚本。

#卸载

使用安装 Pi 时所用的包管理器进行卸载。curl 安装器使用全局 npm，因此 curl 和 npm 安装都可以通过 npm 移除：

# curl 安装器或 npm install -g
npm uninstall -g @earendil-works/pi-coding-agent

# pnpm
pnpm remove -g @earendil-works/pi-coding-agent

# Yarn
yarn global remove @earendil-works/pi-coding-agent

# Bun
bun uninstall -g @earendil-works/pi-coding-agent

卸载 Pi 后，设置、凭证、会话和已安装的 Pi 包仍保留在 ~/.pi/agent/ 目录中。

然后在你希望运行的项目目录中启动 Pi：

cd /path/to/project
pi

#认证

Pi 可以通过 /login 使用订阅 Provider，或通过环境变量或认证文件使用 API Key Provider。

#方式一：订阅登录

启动 Pi 后执行：

/login

然后选择一个 Provider。内置的订阅登录包括 Claude Pro/Max、ChatGPT Plus/Pro (Codex) 和 GitHub Copilot。

#方式二：API Key

在启动前设置环境变量：

export ANTHROPIC_API_KEY=sk-ant-...
pi

或者运行 /login 选择一个 API Key Provider，Key 会被存储在 ~/.pi/agent/auth.json 中。

所有支持的 Provider、环境变量和云 Provider 设置请参考 Providers。

#第一个会话

Pi 启动后，输入一个请求并按 Enter：

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

默认情况下，Pi 为模型提供了四个工具：

• read —— 读取文件
• write —— 创建或覆盖文件
• edit —— 修补文件
• bash —— 运行 Shell 命令

额外的只读工具（grep、find、ls）可通过工具选项获得。Pi 在你的当前工作目录中运行，可以修改文件。如果需要轻松回滚，建议使用 git 或其他检查点工作流。

#给 Pi 项目指令

Pi 在启动时加载上下文文件。添加 AGENTS.md 文件可以配置 Pi 在项目中的行为：

# 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。

#常用操作

#引用文件

在编辑器中输入 @ 可以模糊搜索文件，或在命令行上传入文件：

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

在支持的终端中可以使用 Ctrl+V（Windows 为 Alt+V）粘贴图像，或拖入终端。

#运行 Shell 命令

在交互模式下：

!npm run lint

命令输出会发送给模型。使用 !!command 运行命令但不将输出添加到模型上下文。

#切换模型

使用 /model 或 Ctrl+L 选择模型。Shift+Tab 循环切换思维级别（thinking level）。Ctrl+P / Shift+Ctrl+P 在限定模型之间循环。

#稍后继续

会话自动保存：

pi -c                  # 继续最近的会话
pi -r                  # 浏览历史会话
pi --name "my task"    # 启动时设置会话显示名称
pi --session <path|id> # 打开特定会话

在 Pi 内部，使用 /resume、/new、/tree、/fork、/clone 管理会话。

#非交互模式

用于一次性 Prompt：

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 —— 交互模式、斜杠命令、会话、上下文文件和 CLI 参考。
• Providers —— 认证和模型设置。
• Settings —— 全局和项目配置。
• Keybindings —— 快捷键和自定义。
• Pi Packages —— 安装共享的扩展、Skills、Prompt 模板和主题。

平台相关说明：Windows、Termux、tmux、Terminal setup、Shell aliases。

法律声明：本页面是 pi.dev 官方文档的中文翻译版本，仅供学习参考。本网站与 pi.dev 及 Earendil Inc. 无任何法律关系。