INTRODUCTION · 從這裡開始
為什麼要讀這本 Pi 藍皮書
你可能已經用過 ChatGPT、Claude 或其他聊天產品：開啟視窗，提出問題，等待回答。第一次開啟 Pi 時，它看起來也像一個輸入文字的終端機視窗，但這不是理解它的最好方式。
Pi 官方把它定義為一個極簡、可擴充的 代理框架（Agent Harness）。模型負責理解和生成，代理框架則把模型、工具、工作階段（Session）、上下文和你的工作目錄連接起來。它可以讀取檔案、修改內容、執行命令，也可以透過技能（Skill）和擴充功能（Extension）適應你的工作方式。因此，Pi 不是“又一個聊天視窗”，而是一個可以由你掌握和改造的 Agent 底座。
它和 Claude Code、Codex 在什麼位置
Claude Code、Codex 和 Pi 都能把模型帶進真實工作，但產品取捨不同。學習 Pi 不是為了證明它是一個“更強的程式設計師角色”，也不是為了把別的工具全部替換掉。
Pi 的特點是核心保持小，把更多工作流決定留給使用者。官方預設提供可工作的基礎能力，但不會把子代理（Subagent）、計劃模式、權限彈窗等全部固化成唯一答案。你可以繼續使用預設方式，也可以在真正遇到需求後，用擴充功能、技能、模板或包（Package）補上一塊能力。
這種自由有兩個方向：你更容易把工具變成自己的，也要更清楚自己裝了什麼、開放了什麼權限、最終結果怎樣驗收。
中文初學者真正會卡在哪裡
多數人並不是先卡在 Agent 的抽象概念，而是卡在幾個很現實的問題上。
- 使用者帳戶與模型存取。 安裝 Pi 不等於已經獲得模型。你仍需使用受支援的訂閱登入或 API Key。
- 費用與額度。 訂閱和 API 是不同的存取方式；API 呼叫可能按量計費，訂閱也可能有額度限制。先確認自己能用什麼，再開始長任務。
- Windows 路徑與終端機。 macOS 命令不能不加判斷地複製到 PowerShell。本站為 Windows 單獨提供 Git Bash 路徑，並在後續課程給出對照。
- 外掛程式帶來的不確定性。 一開始裝很多外掛程式，會讓你無法判斷一項能力來自 Pi、模型還是第三方擴充，失敗時也很難定位原因。
所以，本書不會先給你一張功能大全。第一階段只要求你準備獨立目錄、完成登入，並讓 Pi 做完一件可以由你親自檢查的小事。
本版堅持的五條主張
- 先做一件小事。 學會提交任務、檢視產物和獨立驗收，比背完全部概念更重要。
- 一次只增加一個變數。 先用預設能力；遇到明確需求時，再試一個技能或擴充功能，並檢查它是否真的生效。
- Agent 的總結不是驗收。 檔案能否開啟、資料是否完整、測試是否透過，需要由外部證據確認。
- 文字限制不是沙箱。 “不要存取目錄外”是任務範圍說明，不會取消程序在作業系統中的權限。
- 動態事實必須帶日期。 模型、登入方式、命令和生態都會變化；看到動態內容時，以頁核心驗日期和官方文件為準。
這本書適合怎樣閱讀
想先動手，進入從零開始操作，按平台完成安裝、認證和第一次任務，再回來理解原理。想系統閱讀，可以按導論、十條判斷、凡例、序章和五個模組的順序繼續。作者故事和十條判斷不是安裝前置條件。
已經能穩定使用 Pi 的讀者，可以從藍皮書主線選擇對應模組；遇到具體概念時再查參考手冊；想了解判斷如何形成，可以回看小墨同學札記。官方授權譯文提供原作者的完整論述，但不代替課程中的中文操作路徑。
下一頁會把 98 條推文裡反覆出現、到本版定稿時仍然成立的判斷集中列出。原始推文保留當時的探索和變化，藍皮書只承擔現在的結論。