pi-mono 深度導讀系列：從零認識這個極簡 Coding Agent 的完整架構
本系列 17 篇帶你從 CLI 使用者角度切入，逐層深入 pi-mono 的 Agent Loop、Session Tree、Tool System、Extension System、TUI 架構、Remote Session、Telemetry、Compaction、Release 流程等核心機制。適合想自架 Agent、研究 Agent 架構、或想貢獻 pi 的開發者。
17 篇文章
pi-mono 深度導讀
逐段讀 pi-mono 原始碼：agent loop、工具呼叫、審批與 session 管理的實作方式，作為跟成熟 coding agent 學設計的對照案例之一。
pi-mono 深度導讀 1：從 CLI 使用者角度認識 pi——安裝、模式、Session、模型切換與訊息插隊
把 pi 當黑盒用：4 種運行模式怎麼切、Session 樹狀結構怎麼存、怎麼在對話中途換模型、Enter vs Alt+Enter 訊息插隊差異、/tree 怎麼跳回歷史分支。為後續架構篇建立直覺。
pi-mono 深度導讀 2：Monorepo 架構與核心抽象層——7 套件怎麼分工、依賴為什麼單向流動
從使用者可見功能切入架構：7 個 npm 套件各司其職、依賴圖單向流向、為什麼 pi-tui/pi-telemetry 零依賴、pi-ai 如何隔離 provider 細節、lockstep versioning 怎麼避免 diamond dependency。建立「從外往內」的架構心智模型。
pi-mono 深度導讀 3：pi-ai——統一 15+ 供應商的 LLM API，從 Lazy Loading 到 Model Catalog 自動生成
pi-ai 是 pi-mono 的反腐層：上層只見 Message/Tool/Context/streamFunction，下層 15+ providers 各自實作細節。本文拆解：統一介面設計、Provider Factory Registry、Lazy Loading 實現 Tree-shaking、Model Catalog 自動生成流程、OAuth/API Key 統一管理、Credential Sync 機制、Thinking/Reasoning 參數標準化。
pi-mono 深度導讀 4：Agent Loop——雙層循環與事件流，從 Steering 到 Follow-up 的完整時序
pi-agent-core 的心臟：agentLoop() → runLoop() 雙層 while(true)。Inner loop 處理 tool calls + steering messages，Outer loop 處理 follow-up + prepareNextTurn（compaction、model switch）。Enter = steering（當前工具跑完插入）、Alt+Enter = follow-up（agent 判定結束插入）。streamAssistantResponse() 如何處理 partial message 更新、tool call 解析、parallel/sequential 執行、before/after hooks。
pi-mono 深度導讀 5：Session Tree——Append-only JSONL、Branching 不改歷史、Compaction 邏輯完整解析
SessionManager 核心：JSONL append-only 儲存、id/parentId 形成樹、branch() 移動 leaf pointer 不改歷史、buildSessionContext() 處理 compaction entry、createBranchedSession() fork 新檔案。完整 Entry 類型：message、thinking_level_change、model_change、compaction、branch_summary、custom、custom_message、label、session_info。Migration v1→v2→v3 細節。
pi-mono 深度導讀 6：Tool System——8 核心工具定義、Factory 模式、Parallel/Sequential 執行、Before/After Hooks 攔截
pi-coding-agent 8 核心工具完整解析：ToolDefinition（給 LLM 看）vs AgentTool（執行邏輯）、createToolDefinition/createTool Factory、executionMode 決定 parallel/sequential、beforeToolCall/afterToolCall 攔截鏈、withFileMutationQueue 序列化檔案寫入、truncateHead/Line/Tail 輸出截斷、read/write/edit/bash/grep/find/ls/powershell 各工具實作細節。
pi-mono 深度導讀 7：Extension System——Hooks、Custom Tools、UI Components、Lifecycle 完整機制
Extension 系統完整解析：Extension 介面定義、onLoad/onUnload 生命週期、四大 Hook（onAgentStart/onBeforeToolCall/onAfterToolCall/onTurnEnd）、五大擴充點（tools/commands/keybindings/ui/settings）、ExtensionRunner 載入順序與依賴解析、ExtensionAPI 提供的能力、Dynamic Border、Widget、Dialog、Selector 等 UI 元件、Extension 間通訊、熱重載機制、官方範例 Extensions。
pi-mono 深度導讀 8：TUI 架構——Differential Rendering、Component Tree、Layout Engine、CSI 2026 同步輸出
pi-tui 核心完整解析：Virtual DOM Diff 算法實現無閃爍渲染、Component 生命週期、Layout Engine（Flex-like VStack/HStack/Box）、CSI 2026 同步輸出避免 partial frame tearing、Keybindings Manager、Alt Screen 管理、括號貼上模式、Kitty/iTerm2 圖片協定、Markdown/Editor/Selector/Diff 等內建元件。
pi-mono 深度導讀 9：Model Catalog、Provider Factory、OAuth 與 Credential Sync——從自動生成到跨裝置同步
pi-ai Model Catalog 自動生成流程、Provider Factory 註冊與 Lazy Loading、OAuth 2.0 + PKCE 流程實作、Credential Store（Keychain/Libsecret/Credential Manager/加密檔案）、Credential Sync 跨裝置同步機制、Model Scope Diagnostics、ModelResolver 解析邏輯、CredentialSynchronizationOperation 狀態機。
pi-mono 深度導讀 10：Remote Session——Client/Server、JSON-RPC 2.0、WebSocket、斷線重連
pi-protocol JSON-RPC 2.0 定義、pi-client 連線管理與重連指數退避、pi-server Session Registry、WebSocket Transport、心跳機制、Session Snapshot、Remote Session Handle、RPC 模式架構、流式事件傳輸、Steering/Follow-up 遠端插隊。
pi-mono 深度導讀 11：Telemetry——Vendor-neutral Contracts、Schema 定義、Conformance Tests
pi-telemetry 核心：TelemetrySchema 定義 Span/Event/Attribute、defineTelemetrySchema 建立 TypedSpanStarter、InMemoryTelemetryContext/NOOP_TELEMETRY_CONTEXT 零開銷實作、Conformance Tests 驗證 Adapter 正確性、AI/Harness Telemetry Schema 完整定義、屬性類型系統、為什麼不直接用 OpenTelemetry。
pi-mono 深度導讀 12：Compaction 深度——策略、Token Estimation、Branch Summary、Structured Compaction
Compaction 完整機制：shouldCompact 觸發條件（token 佔比、訊息數）、estimateTokens 計算（字符/單字近似）、findCutPoint 尋找切點（保留最近 N 輪）、generateSummary 生成摘要（LLM 呼叫）、prepareCompaction 整理上下文、Branch Summary 生成、Structured Compaction（Extension 自訂 via fromHook）、CompactionEntry 細節、fromHook 機制、Compaction Settings。
pi-mono 深度導讀 13：Agent Harness、Skills、System Prompt 組裝——從零構建 Agent 行為
AgentHarness 核心類別、System Prompt 動態組裝流程、Skills 載入與格式化、Prompt Templates 系統、Harness 如何決定 Tool 可用性、Result Handling、Telemetry Schema 註冊、預設 Harness 建構、Extension 如何擴充 Harness。
pi-mono 深度導讀 14：Testing、Quality Gates、Supply-chain Hardening——Faux Provider、Browser Smoke、Biome、tsgo、Shrinkwrap、Trusted Publishing
測試策略：Faux Provider（無 API Key 跑 e2e）、Vitest 單元測試、Browser Smoke Test（真實瀏覽器驗證）、Biome Lint/Format、tsgo Type Check、Pinned Dependencies、Shrinkwrap 生成、Install Lock、npm Trusted Publishing、CI Pipeline 完整流程。
pi-mono 深度導讀 15：Containerization、Sandbox、Permission Model——Gondolin、Docker、OpenShell、安全邊界
Pi 為什麼不內建 Permission System、Gondolin Extension（微 VM 隔離）、Docker 整合模式、OpenShell 沙盒、Permission Model 設計哲學、三種容器化部署模式、安全邊界對比、micro-VM vs Container vs Process Isolation、Extension 如何實作沙盒。
pi-mono 深度導讀 16：Release 流程、Lockstep Versioning、Binary Build、Trusted Publishing——從代碼到 npm 發佈的完自動化管線
Release 完整流程：Lockstep Versioning（所有套件同版本）、CHANGELOG 更新、Local Smoke Test 驗證、Release Script 自動化、Binary Build (Bun + Node)、npm-shrinkwrap.json 鎖死傳遞依賴、GitHub Actions OIDC Trusted Publishing、R2 Release Marker 驗證、pi.dev/api/latest-version 公告、Announcement Verification 確保發佈成功。