REFERENCE · 遇到問題時查這裡
參考手冊
這裡不承擔從零教學，也不要求順序閱讀。遇到一個術語、一項能力或一個操作問題時，從對應主題進入；如果你第一次閱讀，先從導論：為什麼要讀這本 Pi 藍皮書開始，再按藍皮書主線繼續。
先讀本版說明
十條仍然成立的判斷區分當前結論與原始學習檔案；凡例與 2026 開放學習版說明記錄平台路徑、核驗截止、維護規則與版權邊界。
三種快速查法
| 你現在遇到的是 | 從這裡進入 | 閱讀路徑 |
|---|---|---|
| 一個具體問題 | Pi 常見問題 FAQ | 先看短答，再進入對應概念或課程 |
| 一個已經發生的故障 | Pi 故障排查手冊 | 按現象建立基線，每次只改變一個條件 |
| 一個看不懂的詞 | AI 與 Agent 熱詞表 | 先讀人話解釋，再理解它在 Pi 中的含義 |
FAQ、故障排查手冊與熱詞表會互相引用，並繼續連接主線課程。FAQ 回答“為什麼”，故障手冊處理“現在壞在哪裡”，熱詞表解釋“這個詞是什麼意思”。
核心機制
| 你正在找什麼 | 主題入口 | 適合解決的問題 |
|---|---|---|
| Pi 能看到哪些材料 | 檔案與工作目錄 | 工作目錄、檔案範圍與上下文邊界 |
| 怎樣儲存並繼續任務 | 工作階段（Session）與續寫 | 工作階段命名、恢復與可攜帶性 |
| 長任務為什麼會忘記 | 上下文與壓縮 | 上下文（Context）、壓縮（Compaction）與交接記錄 |
| Cache 數字代表什麼 | 提示快取 | 快取命中、成本與狀態判斷 |
| 這些概念怎樣連成一次執行 | 從 Prompt 到 Agent Loop | 上下文組裝、模型呼叫、工具閉環與工作階段寫回 |
能力與邊界
| 能力 | 主題入口 | 先記住的一句話 |
|---|---|---|
| 固化方法與新增能力 | 技能（Skill）、擴充功能（Extension）與包（Package） | 技能教它怎麼做，擴充功能給它新的執行能力 |
| 選擇第三方擴充 | 外掛程式推薦 | 先確認需求和來源，只試一個最接近問題的外掛程式 |
| 選擇不同 Agent 路線 | Pi、OMP 與 Selesai Code | 區分原版 Pi 與兩個獨立分支，按任務決定是否換工具 |
| 多工分工 | 子代理（Subagent） | 分工之後仍需統一證據和最終驗收 |
| 安全地執行任務 | 權限、隔離與驗收 | 成功返回不等於業務結果已經完成 |
| 長時間執行 | VPS 與長期任務 | 先設計檢查點、恢復路徑和停止條件 |
操作入口
- 安裝前檢查：確認環境和練習目錄。
- 安裝並啟動 Pi：完成第一次啟動。
- Windows 中文路徑：用 Git Bash 完成 Windows 環境準備、安裝和第一次啟動。
- 登入與模型設定：連接模型服務商（Provider）與模型。
- 從練習目錄開始：把實驗與真實檔案隔離。
- 安裝後生命週期管理：更新 Pi、重新整理模型目錄、退出登入、解除安裝並處理本地資料。
常用命令速查
下面只列主線實際使用的入口。普通終端機命令與 Pi 內部命令不要混輸。
| 在哪裡輸入 | 命令 | 用途 |
|---|---|---|
| 普通終端機 | pi | 在當前目錄啟動互動介面 |
| 普通終端機 | pi --version | 檢視當前安裝版本 |
| 普通終端機 | pi update | 只更新 Pi 本體 |
| 普通終端機 | pi update --models | 只重新整理模型目錄 |
| 普通終端機 | pi list | 檢視設定中登記的包 |
| 普通終端機 | pi -c | 繼續當前專案最近工作階段 |
| 普通終端機 | pi -r | 開啟當前專案工作階段選擇器 |
| 普通終端機 | pi --no-extensions -e ./file.ts | 忽略自動發現的擴充功能，只顯式載入一個檔案 |
| 普通終端機 | pi --no-skills --skill ./SKILL.md | 忽略自動發現的技能，只顯式載入一個檔案 |
| Pi 編輯區 | /login | 管理模型服務認證 |
| Pi 編輯區 | /logout | 清除選定模型服務商的本地憑據 |
| Pi 編輯區 | /model | 選擇當前模型 |
| Pi 編輯區 | /name 名稱 | 設定工作階段顯示名 |
| Pi 編輯區 | /resume | 瀏覽並切換工作階段 |
| Pi 編輯區 | /tree | 在當前工作階段樹中選擇節點 |
| Pi 編輯區 | /fork / /clone | 從舊訊息或當前分支建立新工作階段 |
| Pi 編輯區 | /compact | 把較早上下文整理為摘要 |
| Pi 編輯區 | /reload | 重新載入自動發現位置中的資源 |
| Pi 編輯區 | /quit | 退出 Pi 回到普通終端機 |
包管理命令輸入在普通終端機：pi install <來源> 安裝，pi list 檢視，pi config 啟用或停用資源，pi remove <來源> 移除。包可能包含可執行擴充功能與會引導 Agent 執行操作的技能；看不清來源和完整內容時不要安裝。
命令行為會隨版本變化；本表核驗於 2026-09-09。遇到不一致時先執行 pi --help，再查 Using Pi 和對應專題頁。
檔案與設定位置
| 位置 | 作用 | 邊界 |
|---|---|---|
~/.pi/agent/ | 使用者級認證、設定、工作階段與資源 | 可能包含憑據和私人工作階段，不要上傳 |
.pi/ | 當前專案的設定、擴充功能、技能等 | 專案資源受專案信賴（Project Trust）控制 |
.agents/skills/ | 可被多個 Agent 工具發現的專案技能 | 專案級資源，需要先審查來源 |
AGENTS.md、CLAUDE.md | 專案上下文說明 | 預設載入不受拒絕專案信賴保護，可用 --no-context-files 關閉 |
docs/public/ | 本藍皮書站點的公開下載材料 | 構建後複製到網站根路徑，不放憑據 |
故障排查順序
先停止重複嘗試並保留完整錯誤，再核對輸入位置、工作目錄、當前模型和工作階段。隨後建立不載入附加資源的乾淨基線，每次只恢復一個變數。涉及金鑰、付費、釋出、刪除或對外傳送時，不自行擴大操作。
術語邊界
- 模型服務商：實際提供模型呼叫與計費的服務，不等同於 Pi 本身。
- 工作階段：儲存的對話樹；它不會替代檔案版本管理。
- 上下文：模型這一輪能參考的輸入；不等於永久記憶。
- 技能：按需讀取的工作說明與配套資源；能影響行為，也可能引導執行指令碼。
- 擴充功能：在 Pi 程序內執行的 TypeScript 能力，擁有當前使用者權限。
- 包：分發技能、擴充功能、提示模板與主題的組合，不是安全容器。
- 專案信賴：是否載入專案資源的決定，不是執行時沙箱。
延伸閱讀
官方授權譯文不是主線課程。它們按本版目錄作為獨立專區保留，從對應章節進入，用原作者的完整文章進一步解釋一個機制：
- 學完第 7 課後：無法隨身帶走的工作階段
- 學完第 8 課後：Pi 中的壓縮機制
- 學完第 9 課後：Agent 中的提示快取
怎麼使用參考手冊
先用搜尋或上面的主題索引定位問題；需要建立完整理解時，再沿著頁面頂部的課程歸屬回到對應章節。