使用 Pi

本頁介紹 Pi 的日常使用方式，以及 Quickstart 中未展開說明的功能。

該介面有四個主要區域：

• 啟動標頭 - 快速鍵、已載入的 context files、Prompt Templates、Skills 和擴充
• 訊息 - 使用者訊息、助理回應、工具呼叫、工具結果、通知、錯誤和擴充 UI
• 編輯器 - 輸入內容的位置；邊框顏色表示目前 thinking level
• 頁尾 - 工作目錄、工作階段名稱、token/快取使用情況、成本、上下文使用情況和目前模型。總計包括助理回應、工具報告的使用情況以及摘要產生。

編輯器可以暫時替換為內建 UI（例如 /settings）或自訂擴充 UI。

功能	用法
檔案引用	輸入 @ 模糊搜尋專案檔案
路徑補完	按 Tab 補全路徑
多行輸入	Shift+Enter，或 Windows 終端機上的 Ctrl+Enter
複製回復	Ctrl+X 複製最後一條助理訊息；在 /tree 中複製選中的訊息
圖片	使用 Ctrl+V 貼上，Windows 上使用 Alt+V，或拖入終端機
Shell 指令	!command 執行指令並將輸出傳送給模型
隱藏 Shell 指令	!!command 執行指令，但不將輸出傳送給模型
外部編輯器	Ctrl+G 開啟 externalEditor、$VISUAL、$EDITOR、Windows 上的 Notepad，或其他平台上的 nano

有關所有快速鍵和自訂，請參閱 Keybindings。

在編輯器中輸入 / 可開啟指令補全。擴充可以註冊自訂指令，Skills 可透過 /skill:name 使用，Prompt Templates 會透過 /templatename 展開。

指令	描述
/login, /logout	管理 OAuth 或 API Key 憑證
/llama	下載、載入和解除安裝 llama.cpp 路由器模型
/model	切換模型
/scoped-models	啟用/停用 Ctrl+P 循環模型
/settings	thinking level、主題、訊息投遞和傳輸設定
/resume	從之前的工作階段中選擇
/new	開始新工作階段
/name <name>	設定工作階段顯示名稱
/session	顯示工作階段檔案、ID、訊息、token 和成本
/tree	跳轉到工作階段中的任意一點並從那裡繼續
/trust	儲存專案信任決策，供後續工作階段使用
/fork	根據先前的使用者訊息建立新工作階段
/clone	將目前分支複製到新工作階段中
/compact [prompt]	手動壓縮上下文，選用擇使用自訂指令
/copy	將最後一條助理訊息複製到剪貼簿
/export [file]	將工作階段匯出為 HTML 或 JSONL
/import <file>	從 JSONL 檔案匯入並恢復工作階段
/share	上傳為私有 GitHub Gist，並產生可分享的 HTML 連結
/reload	重新載入按鍵綁定、擴充、技能、提示、主題和 context files
/hotkeys	顯示所有鍵盤快速鍵
/changelog	顯示版本歷史記錄
/quit	退出 pi

Agent 仍在工作時也可以commit訊息：

• Enter 將 steering message 加入佇列，在目前助理輪次次完成工具呼叫後投遞。
• Alt+Enter 將 follow-up message 加入佇列，在 Agent 完成全部工作後投遞。
• Escape 中止並將排隊訊息恢復到編輯器。
• Alt+Up 將排隊的訊息檢索回編輯器。

在 Windows Terminal 中，Alt+Enter 預設是全螢幕快捷鍵。若希望 pi 接收該快速鍵，請按 Terminal setup 中的說明重新映射。

可在 Settings 中透過 steeringMode 和 followUpMode 設定投遞方式。

工作階段自動儲存到 ~/.pi/agent/sessions/，按工作目錄組織。

pi -c                  # Continue most recent session
pi -r                  # Browse and select a session
pi --no-session        # Ephemeral mode; do not save
pi --name "my task"    # Set session display name at startup
pi --session <path|id> # Use a specific session file or session ID
pi --fork <path|id>    # Fork a session into a new session file

有用的工作階段指令：

• /session 顯示目前工作階段檔案和 ID。
• /tree 導航檔案內的 session tree，並可以總結已放棄的分支。
• /fork 根據較早的使用者訊息建立新工作階段。
• /clone 將目前分支複製到新的工作階段檔案中。
• /compact 總結較早訊息以釋放上下文。

詳細資訊請參閱Sessions和Compaction。

Pi 在啟動時載入 AGENTS.md 或 CLAUDE.md：

• ~/.pi/agent/AGENTS.md 用於全域指令
• 父目錄，從目前工作目錄向上走
• 目前目錄

如果目錄包含 AGENTS.override.md，Pi 會從該目錄載入它，而不是 AGENTS.md 或 CLAUDE.md。其他目錄中的context files仍然正常分層。

使用 context files 記錄專案約定、指令、安全規則和偏好。使用 --no-context-files 或 -nc 可停用載入。

將預設的系統提示替換為：

• .pi/SYSTEM.md 用於專案
• ~/.pi/agent/SYSTEM.md 用於全域

附加到預設提示，而不在任一位置將其替換為 APPEND_SYSTEM.md。

在互動式啟動時，pi 在信任包含專案本機設定、資源或專案 .agents/skills 的專案資料夾之前會詢問，並且在 ~/.pi/agent/trust.json 中沒有儲存該資料夾或父資料夾的決定。信任專案允許 pi 載入 .pi/settings.json 和 .pi 資源、安裝缺少的專案套件以及執行專案擴充。

在做出信任決定之前，pi 只載入 context files、使用者/全域擴充和 CLI -e 擴充，以便它們可以處理 project_trust 事件。專案本機擴充、由專案套件管理的擴充以及專案設定只會在專案受信任後載入。當切換到來自另一個 cwd 的工作階段，且該 cwd 在目前程序中尚未完成信任解析時，也會採用同樣的分離載入方式。

非互動模式（-p、--mode json 和 --mode rpc）不會顯示信任提示。如果沒有適用的已儲存信任決策，它們會使用全域設定中的 defaultProjectTrust：ask（預設）和 never 會忽略這些專案資源，always 會信任它們。傳入 --approve/-a 或 --no-approve/-na 可以覆寫單次執行的專案信任行為。

如果沒有適用的擴充或已儲存決策，則由 defaultProjectTrust 控制後備行為。可在 ~/.pi/agent/settings.json 中將其設定為 "ask"、"always" 或 "never"，也可以透過 /settings 修改。

pi config 和 package 指令使用相同的專案信任流程，但 pi update 從不提示。傳遞 --approve 以信任某個指令的專案本機設定，或傳遞 --no-approve 以忽略它們。

在互動模式下使用 /trust 可以儲存專案信任決策，供後續工作階段使用，並包含對直接父目錄的信任。該指令只會寫入 ~/.pi/agent/trust.json；目前工作階段不會重新載入，因此需要重新啟動 pi 才能讓變更生效。

使用 /export [file] 將工作階段寫入 HTML。

使用 /share 可以上傳私有 GitHub Gist，並產生可分享的 HTML 連結。

如果你使用 pi 進行開源工作，並希望發佈模型、提示、工具和評估研究的工作階段，請參閱badlogic/pi-share-hf。它將工作階段發佈到 Hugging Face 資料集。

pi [options] [@files...] [messages...]

pi install <source> [-l]     # Install package, -l for project-local
pi remove <source> [-l]      # Remove package
pi uninstall <source> [-l]   # Alias for remove
pi update [source|self|pi]   # Update pi only, or one package source
pi update --all              # Update pi and packages; reconcile pinned git refs
pi update --extensions       # Update packages only; reconcile pinned git refs
pi update --models           # Refresh model catalogs only
pi update --self             # Update pi only
pi update --extension <src>  # Update one package
pi list                      # List installed packages
pi config                    # Enable/disable package resources

這些指令管理 pi 包，pi update 可以更新 pi CLI 安裝。要解除安裝 pi 本身，請參閱 Quickstart。 pi config 和專案套件指令接受 --approve/--no-approve 以信任或忽略一個指令的專案本機設定。 pi update 從不提示專案信任。

有關套件來源和安全說明，請參閱Pi Packages。

標誌	描述
預設	互動模式
-p, --print	列印回應並退出
--mode json	將所有事件輸出為 JSON 行；見 JSON mode
--mode rpc	透過 stdin/stdout 使用 RPC 模式；見 RPC mode
--export <in> [out]	將工作階段匯出為 HTML

在列印模式下，pi 還會讀取管道 stdin 並將其合併到初始提示中：

cat README.md | pi -p "Summarize this text"

選項	描述
--provider <name>	Provider，例如 anthropic、openai 或 google
--model <pattern>	模型比對模式或 ID；支援 provider/id 和選用的 :<thinking>
--api-key <key>	API Key，覆蓋環境變數
--thinking <level>	off, minimal, low, medium, high, xhigh, max
--models <patterns>	用於 Ctrl+P 循環的逗號分隔模式
--list-models [search]	列出可用模型

選項	描述
-c, --continue	繼續最近的工作階段
-r, --resume	瀏覽並選擇一個工作階段
--session <path|id>	使用特定的工作階段檔案或部分 UUID
--fork <path|id>	將工作階段檔案或部分 UUID 分叉到新工作階段中
--session-dir <dir>	自訂工作階段儲存目錄
--no-session	臨時模式；不儲存
--name <name>, -n <name>	設定啟動時的工作階段顯示名稱

選項	描述
--tools <list>, -t <list>	將特定內建、擴充和自訂工具列入允許清單
--exclude-tools <list>, -xt <list>	停用特定的內建、擴充和自訂工具
--no-builtin-tools, -nbt	停用內建工具但保持擴充/自訂工具啟用
--no-tools, -nt	停用所有工具

內建工具：read、bash、edit、write、grep、find、ls。

選項	描述
-e, --extension <source>	從路徑、npm 或 git 載入擴充；可重複
--no-extensions	停用擴充探索
--skill <path>	載入 Skill；可重複
--no-skills	停用技能探索
--prompt-template <path>	載入 Prompt Template；可重複
--no-prompt-templates	停用提示模板探索
--theme <path>	載入主題；可重複
--no-themes	停用主題探索
--no-context-files, -nc	停用 AGENTS.md 和 CLAUDE.md 探索

將 --no-* 與顯式標誌結合，可以只載入需要的資源並忽略設定。例如：

pi --no-extensions -e ./my-extension.ts

選項	描述
--system-prompt <text>	替換預設 Prompt；context files 和 Skills 仍會追加
--append-system-prompt <text>	追加到系統 Prompt
--tui-mode <mode>	TUI 模式：regular（預設）或實驗性 fullscreen
--verbose	強制詳細啟動
-a, --approve	信任本次執行的專案本機檔案
-na, --no-approve	忽略本次執行的專案本機檔案
-h, --help	顯示說明
-v, --version	顯示版本

在 fullscreen 模式下，transcript會在終端機viewport內滾動，而排隊訊息、工作狀態、擴充widget、編輯器和頁尾會固定在底部。滑鼠/觸控板輸入會滾動游標下方的區域；鍵盤viewport操作始終可用。inline 圖片可在支援 Kitty 圖形協議的終端機中工作，包括 Kitty 和 Ghostty。在 iTerm2 中，圖片會渲染為文字佔位符，因為它的inline 圖片協議無法在應用擁有滾動區域時刪除或裁剪圖片位置。在 regular 模式下，pi 使用主螢幕和終端機自帶的 scrollback，iTerm2 inline 圖片會繼續正常渲染。

在 /settings 中設定 TUI mode，可以立即在 regular 和 fullscreen 之間切換，並為後續工作階段選擇預設值。Fullscreen exit output 控制退出全螢幕時是列印最終transcript，還是恢復上一屏並只列印工作階段resume 提示。

使用 @ 為檔案新增前綴以將其包含在訊息中：

pi @prompt.md "Answer this"
pi -p @screenshot.png "What's in this image?"
pi @code.ts @test.ts "Review these files"

# Interactive with initial prompt
pi "List all .ts files in src/"

# Non-interactive
pi -p "Summarize this codebase"

# Non-interactive with piped stdin
cat README.md | pi -p "Summarize this text"

# Named one-shot session
pi --name "release audit" -p "Audit this repository"

# Different model
pi --provider openai --model gpt-4o "Help me refactor"

# Model with provider prefix
pi --model openai/gpt-4o "Help me refactor"

# Model with thinking level shorthand
pi --model sonnet:high "Solve this complex problem"

# Limit model cycling
pi --models "claude-*,gpt-4o"

# Read-only mode
pi --tools read,grep,find,ls -p "Review the code"

# Disable one extension or built-in tool while keeping the rest available
pi --exclude-tools ask_question

Pi 保持核心精簡，並將工作流程相關行為放到擴充、Skills、Prompt Templates 和 packages 中。

它有意不內建 MCP、子 Agent、權限彈窗、plan mode、to-do 或背景 Bash。可以將這些工作流程建置或安裝為擴充/包，也可以使用容器、tmux 等外部工具。

完整設計動機見 blog post。