快速开始

本页将带你从安装到完成第一次可用的 pi 会话。

安装

Pi 以 npm Package 的形式分发：

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

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

卸载

使用安装 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/agent/ 中的设置、凭据、会话和已安装的 pi Package。

然后在你希望 pi 处理的项目目录中启动它：

cd /path/to/project
pi

认证

Pi 可以通过 /login 使用订阅 Provider（模型提供方），也可以通过环境变量或 auth 文件使用 API-key Provider。

选项 1：订阅登录

启动 pi 并运行：

/login

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

选项 2：API 密钥

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

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 - 打补丁修改文件
• 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

修改上下文文件后，请重启 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 循环切换思考级别。使用 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 来管理会话。

非交互模式

用于一次性提示：

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 - 安装共享扩展、Skill、提示词和主题。

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