1 快速开始

本页带你从安装一路走到完成第一个实用的 pi 会话。

安装

Pi 以 npm 包的形式分发：

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

--ignore-scripts 会在安装过程中禁用依赖的生命周期脚本。在常规 npm 安装下，Pi 不需要安装脚本。

卸载

使用安装 pi 时所用的包管理器来卸载。curl 安装器底层使用全局 npm，因此 curl 和 npm 安装的版本都用 npm 卸载：

# curl installer or 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 使用订阅型提供商，也可以通过环境变量或认证文件使用 API 密钥型提供商。

方式一：订阅登录

启动 pi 并运行：

/login

然后选择一个提供商。内置的订阅登录包括 Claude Pro/Max、ChatGPT Plus/Pro（Codex）以及 GitHub Copilot。

方式二：API 密钥

在启动 pi 之前设置 API 密钥：

export ANTHROPIC_API_KEY=sk-ant-...
pi

也可以运行 /login 并选择一个 API 密钥型提供商，把密钥存入 ~/.pi/agent/auth.json。

所有受支持的提供商、环境变量以及云端提供商的配置，请参阅提供商。

第一个会话

pi 启动后，输入一个请求并按回车：

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 文件，告诉它在这个项目中如何工作：

# 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

如果某个目录中存在 AGENTS.override.md，Pi 会加载它来取代该目录中的 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 为当前会话选择模型。在模型选择器中按 Ctrl+S，可以把高亮的模型保存为启动默认值。使用 /thinking 为当前会话选择思考级别；在该选择器中按 Ctrl+S 可保存启动默认的思考级别。使用 Shift+Tab 可以循环切换思考级别。使用 Ctrl+P / Shift+Ctrl+P 可以在限定范围（scoped）的模型之间循环切换。

稍后继续

会话会自动保存：

pi -c                  # Continue most recent session
pi -r                  # Browse previous sessions
pi --name "my task"    # Set session display name at startup
pi --session <path|id> # Open a specific session

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

非交互模式

一次性提示可以这样运行：

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——交互模式、slash 命令、会话、上下文文件与 CLI 参考。
• 提供商——认证与模型配置。
• 设置——全局与项目配置。
• 快捷键——快捷键与自定义。
• Pi 包——安装共享的扩展、技能、提示词模板和主题。

平台说明：Windows、Termux、tmux、终端配置、Shell 别名。