PRINCIPLE MAP · 完整執行鏈路
Pi 工作原理：從一條 Prompt 到一次完整 Agent Loop
前面的課程分別講過工作階段（Session）、上下文（Context）、System Prompt、Tool、技能（Skill）、壓縮（Compaction）和 Cache。單獨看，每個詞都不難；真正容易卡住的是：當你提交一條任務以後，它們究竟怎樣連在一起？
這一篇只做一件事：把一次請求從輸入到完成完整跑通。讀完以後，你應該能看著 Pi 介面裡的模型回覆、工具呼叫和工具結果，說清它現在位於哪一步，以及下一步為什麼還會再次呼叫模型。
先記住一句話
Pi 是組織執行過程的代理框架（Agent Harness）。模型負責判斷下一步，工具負責接觸真實環境，工作階段儲存過程，上下文是某一次模型呼叫真正收到的輸入。
先看完整執行鏈
圖裡最重要的不是箭頭數量，而是中間那一圈：
模型 → Tool Call → 工具執行 → Tool Result → 模型再次推理只要模型仍然需要外部資訊或動作，這個迴圈就可以繼續。模型可能先讀取檔案，再搜尋內容，再修改檔案，最後執行檢查；每次工具返回的結果都會成為下一次模型判斷的依據。模型不再請求工具、而是給出普通回覆時，這一輪 Agent Loop 才結束。
圖中的壓縮使用虛線，因為它不是每條 Prompt 都會經過的固定步驟。只有上下文接近限額、手動執行 /compact，或相應機制被觸發時，Pi 才會把較早內容整理成摘要，再帶著保留的近期訊息繼續。
不要把所有術語排成一條流水線
下面這條寫法適合記憶大方向：
輸入任務 → 讀取 Session → 構建 Context → 調模型 → 調工具 → 返回結果
→ 再次推理 → 回覆使用者 → 寫入 Session → 必要時 Compaction → 繼續但真實結構裡有三個需要修正的地方。
1. System Prompt、Tool 和技能共同參與上下文組裝
它們不是三個依次執行的站點。
- System Prompt 規定 Pi 以什麼身份工作、有哪些基礎規則，並列出當前能力。
- Tool 定義 告訴模型有哪些工具、每個工具能做什麼、需要哪些引數；工具本身要等模型發出 Tool Call 才會執行。
- 技能 通常先以名稱和描述出現在系統提示中。任務匹配時，模型再透過讀取工具載入完整
SKILL.md，其內容從那一刻開始參與後續判斷。 - 上下文檔案和專案規則、當前工作目錄、活動工作階段分支中的訊息與壓縮摘要，也會一起構成這一輪模型可見的輸入。
所以更準確的說法是：Pi 先組裝上下文，再把 System Prompt、訊息和可用工具等資訊一起交給模型。
2. 工作階段不等於上下文
工作階段是儲存在磁碟上的工作歷史，包含使用者訊息、模型回覆、Tool Call、Tool Result、分支與壓縮記錄。上下文則是 Pi 從當前活動分支重建出來、準備交給模型的本輪輸入。
你可以把工作階段想成完整工作檔案，把上下文想成這一次擺到模型桌面上的材料。檔案還在，不代表所有舊內容每一輪都完整放在桌面上。
3. Cache 不負責決定下一步
提示快取不是 Agent Loop 中一個新的執行節點。它是模型服務商（Provider）對重複字首的一種複用機制，可能影響延遲和費用，但不會替 Pi 儲存工作階段，也不會替模型執行 Tool Call。
因此圖裡沒有單獨畫 Cache。需要理解快取命中與上下文變化時，再回到提示快取入門。
一次 Agent Loop，逐步發生了什麼
第 0 步：Pi 先準備本次執行環境
啟動 Pi 時，它會確定工作目錄、模型、可用工具，並載入允許使用的專案資源。可用技能的名稱與描述會進入系統提示；擴充功能（Extension）還可以註冊新工具，或在 Agent Loop 開始前調整系統提示和上下文。
這一步決定的是“模型稍後能看到什麼、能呼叫什麼”，還沒有替使用者完成任務。
第 1 步：使用者提交 Prompt
你在編輯區提交任務。Pi 把這條使用者訊息加入當前工作階段的活動分支，然後準備第一次模型呼叫。
Prompt 不需要把所有背景重複一遍。當前工作階段、專案規則和你明確引用的檔案，會由 Pi 按當前執行狀態參與上下文組裝。但沒有實際讀入上下文的材料，不能假設模型已經知道。
第 2 步：Pi 構建本輪上下文
Pi 從當前工作階段分支重建訊息歷史，並組合系統提示、專案上下文檔案、可用工具說明、技能索引和當前工作目錄等資訊。若之前發生過壓縮，較早訊息可能以摘要形式進入當前上下文，較近訊息繼續保留。
上下文是一次模型呼叫的輸入快照。下一次呼叫時，因為新 Tool Result 或新訊息已經加入，它會隨之變化。
第 3 步：模型做第一次判斷
模型讀取當前上下文後，通常會返回兩類結果之一：
- 已經可以回答，直接生成普通回覆。
- 還需要讀取資訊或執行動作，返回一個或多個 Tool Call。
模型只是在提出工具呼叫請求。真正讀取檔案、執行命令或寫入內容的是 Pi 提供的工具。
第 4 步：Pi 執行 Tool Call
Pi 按工具名稱和引數呼叫對應能力。例如 read 讀取檔案，write 寫入檔案，bash 執行命令。介面會顯示 Tool Call 與隨後的 Tool Result，讓你知道它碰了什麼物件、返回了什麼。
Tool Result 可能是檔案內容、命令輸出、變更差異，也可能是明確的錯誤。無論成功還是失敗，它都不是最終回答，而是下一次推理的新證據。
第 5 步：Tool Result 回到模型
Pi 把 Tool Result 加入訊息歷史，再次呼叫模型。模型此時可以根據真實結果決定：
- 繼續呼叫另一個工具；
- 修正上一次失敗的引數；
- 檢查剛寫入的結果；
- 或停止呼叫工具，給出最終回覆。
這就是 Agent Loop 的核心。一次使用者 Prompt 可以觸發多次模型呼叫，也可以包含多輪 Tool Call 與 Tool Result。
第 6 步：Pi 儲存過程並結束本輪
當模型不再請求工具而是給出普通回覆，Pi 會把回覆繼續寫入工作階段。使用者訊息、模型訊息、Tool Call 和 Tool Result 共同構成可恢復的工作階段歷史。
這裡的“結束”只表示 Agent 已經回到等待輸入狀態，不等於業務結果必然正確。檔案是否存在、內容是否完整、網頁是否上線，仍要回到真實環境獨立驗收。
第 7 步：上下文變長，必要時進行壓縮
隨著訊息和工具結果增加，當前上下文會逐漸佔用更多空間。接近模型上下文限額時，Pi 可以總結較早內容、保留較近訊息，並在同一個任務中繼續執行；你也可以用 /compact 手動觸發。
壓縮以後，新的摘要會參與後續上下文重建。它能幫助任務繼續，但不是無損記憶，也不會替你恢復磁碟檔案。關鍵目標、決定和驗收結果仍應寫進專案檔案。
用真實任務走一遍：把會議記錄整理成行動清單
沿用第一次任務和 CASE 01 的練習：讀取 input/專案會議記錄.md，生成 output/行動清單.md，保留事項、負責人、日期和風險提醒。
下面描述的是這項可復現任務的典型可觀察路徑。不同模型可能合併呼叫、增加檢查步驟或採用不同順序；看不見的模型內部思考不會被當成已驗證事實。
| 環節 | 這項任務裡發生什麼 | 你能觀察什麼 |
|---|---|---|
| Prompt | 使用者指定輸入、輸出、四個欄位和不可越過的範圍 | 工作階段中出現完整使用者訊息 |
| 上下文 | Pi 組合系統提示、工作目錄、活動工具、當前工作階段歷史與使用者任務 | 啟動區能看到已載入資源；底部能看到當前目錄與模型 |
| 第一次模型呼叫 | 模型判斷必須先取得會議記錄內容 | 出現讀取 input/專案會議記錄.md 的 Tool Call |
| Tool Result | 讀取工具把三條事項返回給模型 | 介面顯示被讀取路徑與返回內容 |
| 再次模型呼叫 | 模型根據原文組織四類欄位，並決定寫入目標檔案 | 出現寫入 output/行動清單.md 的 Tool Call |
| 再次 Tool Result | 寫入工具報告成功或返回錯誤 | 介面顯示實際寫入路徑；報錯時模型可以繼續修正 |
| 結束本輪 | 模型不再呼叫工具，報告產物和建議的驗收方法 | Pi 回到可輸入狀態，最終回覆寫入工作階段 |
| 獨立驗收 | 使用者離開模型總結，核對輸入指紋、輸出路徑和三條內容 | input 未變，輸出檔案存在，四類欄位逐項對應 |
這個例子裡不需要為了展示概念而強行加入技能。若後來把“每次都按四個欄位檢查行動清單”固化成技能，變化發生在上下文組裝階段：系統提示會先列出該技能；模型按需讀取完整說明後，再沿用同一個工具迴圈完成任務。
遇到問題時，從鏈路上定位
| 現象 | 先檢查哪一段 |
|---|---|
| 模型像是不知道專案規則 | 上下文檔案是否被載入，工作目錄是否正確 |
| 模型說讀過檔案，但介面沒有讀取記錄 | 是否真的產生並執行了 Tool Call |
| 工具報錯後任務停止 | Tool Result 的錯誤內容，以及模型是否獲得下一次推理機會 |
| 回覆看起來正確，但檔案沒有變化 | 實際寫入 Tool Call、目標路徑和磁碟檔案 |
| 長任務開始遺漏早期要求 | 上下文佔用、壓縮摘要和專案交接檔案 |
| Cache 命中下降 | 系統提示、工具定義或歷史字首是否發生變化；不要把它當成記憶丟失 |
本篇驗收
讀完後，不看前文，嘗試說清下面四件事：
- 為什麼 Tool Call 之後還要再次呼叫模型？
- 為什麼工作階段中儲存了舊訊息，模型仍可能遺漏舊細節？
- System Prompt、Tool 和技能為什麼不是三個順序執行的步驟？
- 為什麼 Pi 回覆“完成”以後，仍要獨立檢查真實檔案或線上結果？
如果能回答，你已經把前面分散的術語接成了一套工作模型。下一步不是記更多詞，而是在 CASE 01 中盯著一次真實工具迴圈，再去上下文與壓縮觀察長任務如何改變上下文。
本篇依據
- Pi SDK：System Prompt、Tools、技能與上下文 Files
- Pi Agent Core：帶 Tool Call 的事件序列
- Pi 擴充功能：Agent Loop 前後的事件與上下文調整
- Pi 技能：按需載入與漸進披露
- Pi 工作階段
- Pi 壓縮
以上動態行為核驗於 2026-09-11。Pi 的資源載入、事件和壓縮機制可能繼續更新，以官方 Latest 文件和對應原始碼為準。