快速開始

本頁介紹如何安裝 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，並將 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 - 以 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。