快速开始

本文介绍如何安装到首次有意义的 pi 会话。

安装 Install

Pi 以 npm 包形式分发：

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

--ignore-scripts 在安装过程中禁用依赖生命周期脚本。Pi 不需要安装脚本来进行正常的 npm 安装。

卸载 Uninstall

使用当初安装 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

身份验证 Authenticate

Pi 可通过 /login 使用订阅提供商，或通过环境变量及 auth 文件使用 API 密钥提供商。

选项 1：订阅登录

启动 pi 并执行：

/login

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

选项 2：API 密钥

在启动 pi 前设置 API 密钥：

export ANTHROPIC_API_KEY=sk-ant-...
pi

你也可以运行 /login 并选择 API 密钥提供商，将密钥存储到 ~/.pi/agent/auth.json 中。

查看提供商 Providers 了解所有支持的提供商、环境变量及云提供商配置。

首次会话 First session

启动 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。

常见操作 Common things to try

引用文件

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

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

在 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 进行进程集成。

后续步骤 Next steps

• 使用 Pi usage — 交互模式、斜杠命令、会话、上下文文件及 CLI 参考。
• 提供商 providers — 身份验证和模型设置。
• 设置 settings — 全局和项目配置。
• 快捷键 keybindings — 快捷键及自定义。
• Pi 包 packages — 安装共享扩展、技能、提示和主题。

平台说明：Windows、Termux、tmux、终端设置 terminal-setup、Shell 别名 shell-aliases。