快速开始

本页介绍如何安装 Pi、完成身份验证，并开始第一次有用的 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 使用订阅 Provider，也可以通过环境变量或 auth 文件使用 API Key Provider。

启动 pi 并运行：

/login

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

在启动 pi 之前设置 API Key：

export ANTHROPIC_API_KEY=sk-ant-...
pi

也可以运行 /login，选择 API Key Provider，并将密钥存储到 ~/.pi/agent/auth.json。

所有受支持的 Provider、环境变量和云 Provider 设置见 Providers。

pi 启动后，输入请求并按 Enter：

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

默认情况下，pi 会向模型提供四个工具：

• read - 读取文件
• write - 创建或覆盖文件
• edit - 以 patch 方式修改文件
• bash - 运行 shell 命令

其他内置只读工具（grep、find、ls）可通过工具选项启用。Pi 在当前工作目录中运行，并可以修改其中的文件。若需要方便回滚，请使用 git 或其他检查点工作流。

Pi 会在启动时加载 context files。添加 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。

更改 context files 后，重启 pi 或运行 /reload。

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

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

可以使用 Ctrl+V（Windows 上为 Alt+V）粘贴图像或文本；图像也可以拖到支持的终端中。

在交互模式下：

!npm run lint

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

使用 /model 或 Ctrl+L 选择模型。使用 Shift+Tab 循环切换 thinking level。使用 Ctrl+P / Shift+Ctrl+P 在作用域模型之间循环切换。

会话会自动保存：

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 来管理会话。

对于一次性 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 进行进程集成。

• Using Pi - 交互模式、slash commands、会话、context files 和 CLI 参考。
• Providers - 身份验证和模型设置。
• Settings - 全局和项目配置。
• Keybindings - 快捷方式和自定义。
• Pi Packages - 安装共享扩展、技能、提示和主题。

平台备注：Windows、Termux、tmux、Terminal setup、Shell aliases。