pi 架構總覽
源码版本v0.73.1
badlogic/pi-mono 是一個 TypeScript monorepo,用五個 npm 包搭出一整條「統一 LLM API → 通用 Agent → 編碼助手 → 終端/網頁 UI」的棧。本頁給一張全景圖,後續每頁拆一層。
五個包
| 包 | npm 名 | 角色 |
|---|---|---|
ai | @mariozechner/pi-ai | 統一 LLM API,9 個內建 provider,自動模型發現 |
agent | @mariozechner/pi-agent-core | 通用 Agent,雙層 while 迴圈 + 工具執行 |
coding-agent | @mariozechner/pi-coding-agent | 編碼助手 CLI,read/bash/edit/write 工具 + 工作階段管理 |
tui | @mariozechner/pi-tui | 終端 UI 庫,差分渲染 + 同步輸出 |
web-ui | @mariozechner/pi-web-ui | 網頁聊天元件,Lit Web Components |
原始碼目錄:packages/
分層
每層一句話
- pi-ai:把 9 家 LLM(Anthropic、OpenAI、Google、Bedrock...)統一成
stream/streamSimple兩個函式,透過註冊表按model.api分發。詳見 串流門面 stream。 - pi-agent-core:
Agent類別持狀態,runLoop外層處理插話/佇列、內層處理工具呼叫,串流 + 工具迴圈。詳見 雙層 while 主迴圈。 - pi-coding-agent:在
Agent外套AgentSession,加工具、系統提示、工作階段持久化、三種執行模式。詳見 AgentSession 編排層。 - pi-tui:差分渲染 + DECSET 2026 同步輸出,避免終端閃爍。詳見 差分渲染 TUI 類別。
- pi-web-ui:Lit 元件擁有自己的
Agent實例,透過createStreamFn包一層 CORS 代理調streamSimple。詳見 AgentInterface 工作階段宿主。
分層動機
為什麼不做成一個大包?因為各層消費者不同:網頁元件不能依賴 Node 的 fs,終端 UI 不該背網頁的 IndexedDB,通用 Agent 不該知道「編碼」這件事。分層後,網頁可以直接拿 pi-agent-core + pi-ai 自己跑 agent,跳過編碼助手的工具集;編碼助手 CLI 可以換 UI(tui 或 rpc 模式)而不動編排邏輯。pi-ai 單獨成包,是為了讓任何專案都能直接用統一 LLM API,不被 agent 概念綁住。
常見誤讀
- 「pi 是一個 coding agent」:不準確。
pi-coding-agent是上層應用,底層pi-ai和pi-agent-core是通用基礎設施,可獨立使用。 - 「UI 層只是渲染」:網頁和終端 UI 都會參與串流——網頁替換
Agent.streamFn注入 CORS 代理,終端訂閱事件決定何時重繪。
推薦閱讀順序
先 串流門面 stream 懂 LLM 怎麼調,再 雙層 while 主迴圈 看工具迴圈,接著 AgentSession 編排層 看編碼助手怎麼裝配,最後按興趣挑 pi-tui 或 pi-web-ui。