使用Pi

此頁面收集不適合快速入門頁面的日常使用詳細資訊。

此介面有四個主要區域：

• 啟動標題 - 快捷方式、加載的context files、prompt templates、技能和擴展
• 訊息 - 使用者訊息、助手回應、工具呼叫、工具結果、通知、錯誤和擴展 UI
• 編輯器 - 您輸入的位置；邊框顏色表示當前思維水平
• 頁腳 - 工作目錄、會話名稱、令牌/快取使用情況、成本、上下文使用情況和當前模型。總計包括助理回應、工具報告的使用情況以及摘要產生。

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

特徵	如何
文件參考	輸入 @ 模糊搜尋項目文件
路徑補全	按 T​​ab 鍵完成路徑
多行輸入	Shift+Enter，或 Windows 終端機上的 Ctrl+Enter
複製回覆	Ctrl+X 複製最後一則助手訊息；在/tree中，它複製所選訊息
圖片	在 Windows 上使用 Ctrl+V、Alt+V 貼上，或拖曳到終端機中
外殼命令	!command 運行並將輸出傳送到模型
隱藏的 shell 指令	!!command 運行而不將輸出送到模型
外部編輯	Ctrl+G 在 Windows 上開啟 externalEditor、$VISUAL、$EDITOR、記事本，或在其他地方開啟 nano

有關所有快捷方式和自訂，請參閱 Keybindings。

在編輯器中輸入 / 開啟指令補全。 Extensions可以註冊自訂指令，技能與/skill:name相同，prompt templates透過/templatename擴充。

命令	描述
/login, /logout	管理 OAuth 或 API 金鑰憑證
/llama	下載、載入和卸載 llama.cpp 路由器模型
/model	切換型號
/scoped-models	啟用/停用 Ctrl+P 循環模型
/settings	思維層次、主題、訊息傳遞、傳輸
/resume	Pick 之前的會議
/new	開始新會話
/name <name>	設定會話顯示名稱
/session	顯示會話檔案、ID、訊息、令牌和成本
/tree	跳到會話中的任何一點並從那裡繼續
/trust	保存專案信任決策以供未來會議使用
/fork	根據先前的用戶訊息建立新會話
/clone	將目前活動分支複製到新會話中
/compact [prompt]	手動壓縮上下文，可選擇使用自訂指令
/copy	將最後一則助理訊息複製到剪貼簿
/export [file]	將會話匯出為 HTML 或 JSONL
/import <file>	從 JSONL 檔案匯入並恢復會話
/share	上傳為私人 GitHub 要點，並帶有可共享的 HTML 鏈接
/reload	重新載入按鍵綁定、擴充、技能、提示、主題和 context files
/hotkeys	顯示所有鍵盤快速鍵
/changelog	顯示版本歷史記錄
/quit	退出圓周率

您可以在代理仍在工作時提交訊息：

• Enter 將轉向訊息排隊，在目前助手輪完成執行其工具呼叫後傳遞。
• Alt+Enter 將後續訊息排隊，在代理完成所有工作後發送。
• Escape 中止排隊訊息並將其還原為編輯器。
• Alt+Up 將排隊的訊息檢索回編輯器。

在 Windows 終端機上，Alt+Enter 預設為全螢幕。如果您希望 pi 接收快捷方式，請按照 Terminal setup 中的說明重新映射它。

使用steeringMode和followUpMode配置Settings中的交付。

會話自動儲存到~/.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 表示專案約定、指令、安全規則和首選項。使用 --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 切換到會話時，此分割也適用。

非互動模式（-p、--mode json 和 --mode rpc）不顯示信任提示。如果沒有適用的已儲存信任決策，他們將使用全域設定中的defaultProjectTrust：ask（預設）和never忽略這些項目資源，而always則信任它們。透過 --approve/-a 或 --no-approve/-na 涵蓋一次運行的專案信任。

如果沒有適用擴展或保存的決策，則defaultProjectTrust控制後備行為。將~/.pi/agent/settings.json中的"ask"、"always"或"never"設定為"ask"、"always"或"never"，或將其改為/settings。

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

在互動模式下使用 /trust 可以為未來的會話保存專案信任決策，包括對直接父資料夾的信任。只寫~/.pi/agent/trust.json；當前會話不會重新加載，因此請重新啟動 pi 以使更改生效。

使用 /export [file] 將會話寫入 HTML。

使用 /share 上傳帶有可共享 HTML 連結的私人 GitHub 要點。

如果您使用 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	RPC模式超過stdin/stdout；見RPC mode
--export <in> [out]	將會話匯出為 HTML

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

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

選項	描述
--provider <name>	提供者，例如 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	瀏覽並選擇一個會話
`--會話<路徑\	id>`
`--fork <路徑\	id>`
--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>	加載技能；可重複的
--no-skills	禁用技能發現
--prompt-template <path>	載入提示模板；可重複的
--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>	替換預設提示； context files 技能仍附加
--append-system-prompt <text>	附加到系統提示符
--tui-mode <mode>	TUI模式：regular（預設）或實驗性fullscreen
--verbose	強制詳細啟動
-a, --approve	信任本次運行的專案本地文件
-na, --no-approve	忽略本次運行的專案本地文件
-h, --help	顯示幫助
-v, --version	顯示版本

在 fullscreen 模式下，記錄在終端視窗內滾動，而排隊訊息、工作狀態、擴充小工具、編輯器和頁腳保持固定在底部。滑鼠/觸控板輸入滾動指標下方的區域；鍵盤視窗操作始終保持可用。內嵌影像可在支援 Kitty 圖形協定（包括 Kitty 和 Ghostty）的終端中運作。在 iTerm2 中，它們呈現為文字佔位符，因為其內聯圖像協定無法在應用程式擁有的捲動期間刪除或裁剪位置。在regular模式下，pi使用主螢幕和終端機擁有的回滾，iTerm2內嵌影像繼續正常渲染。

在/settings中設定TUI模式可立即在regular和fullscreen之間切換，並為未來的會話選擇預設值。 全螢幕退出輸出 控制退出全螢幕是否列印最終記錄或恢復前一畫面並僅列印會話恢復提示。

使用 @ 為文件添加前綴以將其包含在訊息中：

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 保持核心較小，並將特定於工作流程的行為推送到擴充、技能、prompt templates 和套件中。

它故意不包含內建MCP、子代理、權限彈出視窗、計劃模式、待辦事項或背景bash。您可以將這些工作流程建置或安裝為擴充功能或套件，或使用容器和tmux等外部工具。

要了解完整的原理，請閱讀blog post。