pi-from-scratch：用 600 行 TypeScript 拆開 coding agent 的資料流
600 行 TypeScript 写成的超级迷你版 pi，让你轻松从 0 写出属于你的 pi-agent
秒懂
- 它是什麼？
- 這個專案把 pi 的工程細節剝掉，只留一條可追蹤的 agent loop，讓你在本機跑起一個能讀檔、改碼、執行命令的 nano-pi。它的價值在教學路徑，不在生產部署。
- 適合誰用？
- 想弄懂 agent loop 怎麼把 LLM 的 tool call 串成可執行的動作，這個專案值得花一個下午跑一遍：npm install、export NANOPI_API_KEY、npm run dev 三步就能看到 nano-pi 動起來，網站上的 Trace 還能逐行對照執行流。要拿它當production agent 的人請止步，README 只支援 OpenAI 相容介面，沒有權限沙箱、沒有重試策略、沒有持久化，600 行的規模本來就裝不下這些。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 29 天前。
- 用什麼語言寫的？
- 主要是 TypeScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它解決的不是 agent 功能，而是 agent 的不可見
市面上的 coding agent 大多以成品形式出現：安裝、設定金鑰、開始對話，中間那層「模型輸出如何變成檔案修改」被完整封裝。對要除錯或要自建的人來說，這層封裝就是黑箱。pi-from-scratch 針對的正是這個黑箱。README 的定位寫得很直白：沿著 pi 的資料流拆解，需要什麼就造什麼，刪掉工程細節，留下核心思想。
目標讀者有兩類。一類是寫過 LLM API 呼叫、但沒親手接過 tool calling 迴圈的工程師；另一類是已經在用 pi 或同類工具，想弄清楚一次檔案編輯在內部經過幾個階段的人。專案本身不是給終端使用者安裝的產品，README 也把它稱作一篇文章而不是一本書，這個自我定位決定了後面所有取捨。
資料流：從一則訊息到一次檔案改動
README 沒有貼出完整架構圖，但從「沿著 pi 的資料流拆解」與「需要什麼、我們造什麼」這兩句，可以確認它的組織方式是按執行順序切分元件，而不是按模組類型分層。網站把文章與原始碼並排，閱讀推進時右側編輯器逐步補全程式碼，讀完時 nano-pi 的完整實作也剛好呈現。這個漸進補全的安排本身就是一份規格說明：每個段落對應一個可獨立理解的環節，前一段的產出是後一段的輸入。
另一條理解路徑是 Trace。專案設計了可打斷點、逐行過去的追蹤介面，用來觀察程式執行流。README 明確指出線上 trace 是預先生成的靜態資料，瀏覽網站不會發起任何模型請求。這一點對閱讀體驗影響很大：你看到的是固定輸入下的固定路徑，不會因為模型抽樣而每次不同，適合用來建立心智模型，但不適合用來評估模型在真實任務上的表現。
啟動 nano-pi 的三個指令與三個環境變數
README 給出的執行前提是 Node.js 22 或更高版本，以及一個 OpenAI 相容 API。取得與啟動的步驟是：
npm install export NANOPI_API_KEY=your-api-key npm run dev
可選的環境變數有三個。NANOPI_MODEL 指定模型名稱；NANOPI_BASE_URL 指定 OpenAI 相容介面位址，預設值為 https://api.openai.com/v1。也就是說，只要你的服務說 OpenAI 的協議，換掉 base URL 就能接上，不需要改程式碼。
教學網站是獨立的第二個專案，位於 web 目錄：
cd web npm install npm run dev
這裡要留意一件事：兩個 npm install 是分開的，根目錄的安裝不會順帶裝好網站的依賴。如果你只想讀文章與看 Trace，其實只需要跑 web 這一側，因為線上 trace 是靜態資料，不會消耗 API 額度。
600 行意味著哪些東西一定不在裡面
README 的標題把規模寫成 600 行 TypeScript，這個數字同時是賣點與邊界。要在這個預算內完成讀檔、改碼、執行命令三件事，必然要放棄一些在生產環境被視為基本的要求。
第一，只有 OpenAI 相容協議這一條路徑。Anthropic 的原生協議、或是各家廠商自帶的工具呼叫格式，都不在支援範圍內，除非它們包了一層相容介面。第二，README 只交代了金鑰與端點，沒有提到任何權限限制、目錄白名單或命令過濾。一個能執行命令的 agent 若沒有這層約束，執行的範圍就等於你當下的使用者權限。第三，沒有提到重試、逾時或錯誤恢復策略，而 tool calling 迴圈恰恰是最容易在中途失敗的地方。這些不是實作缺陷的指控，而是規模的算術結果：600 行扣掉教學用的註解與型別宣告，能承載的邏輯本來就有限。判斷這個專案是否適合你，本質上是在判斷你要的是理解還是部署。
與 pi 本體的差異，以及什麼時候該直接用 pi
pi-from-scratch 的參照對象是 earendil-works/pi，README 的措辭是刪除工程細節、留下核心思想。兩者的差別因此不在功能清單，而在取捨方向：pi 是一個可以每天使用的工具，pi-from-scratch 是一份可以讀完的實作。前者要處理真實環境的邊界情況，後者要讓每一行都能被解釋。
如果你的目標是完成工作，直接用 pi 或任何成熟 agent 都比改造 nano-pi 划算，因為你很快就會撞上它刻意省略的那些部分。如果你的目標是理解，那麼從零寫一遍的收益無法由閱讀成品取代，尤其當你打算之後自己維護一套內部 agent 時，知道哪些環節會出錯比知道 API 怎麼呼叫更重要。README 另外推薦了 pi-book 作為延伸讀物，並註明它為本專案提供了不少思路，想在完成 nano-pi 後繼續深入 pi 的人可以接著讀。
值得一提的是專案首頁的贊助說明中提到了 API 中轉服務，這類服務通常相容 OpenAI 與 Anthropic 協議。對照 NANOPI_BASE_URL 的設計，這解釋了為什麼專案選擇以 base URL 而非寫死端點的方式接入模型。
授權與後續維護成本
專案採用 MIT 授權，檔案位於 repo 根目錄的 LICENSE。這個授權允許修改、再散布與商業使用，條件是保留著作權與授權聲明。實務上，多數人會把 nano-pi 當成自己 agent 的起點，MIT 對這種用法沒有阻礙。這一段不構成法律意見，實際情況仍應以 LICENSE 全文與你的使用情境為準。
維護面上，這個 repo 沒有檢索到任何 release，最新推送時間為 2026-08-18，預設分支為 main，且未被封存。沒有 release 意味著沒有版本化標籤可鎖定，如果你打算在自己的專案中引用其中片段，得自行複製或固定 commit。另一個要考慮的成本是模型端：nano-pi 每次執行都會打到你設定的 OpenAI 相容端點，模型名稱與端點一旦變動，環境變數就要跟著調整，這部分沒有抽象層幫你吸收。
教學網站是另一個部署單位，位於 web 目錄，線上版本託管於 Vercel，首頁為 https://pi-from-scratch.vercel.app。網站與 agent 兩邊的依賴是分開安裝的，升級時記得兩邊都要處理。
編輯結論
想弄懂 agent loop 怎麼把 LLM 的 tool call 串成可執行的動作，這個專案值得花一個下午跑一遍：npm install、export NANOPI_API_KEY、npm run dev 三步就能看到 nano-pi 動起來，網站上的 Trace 還能逐行對照執行流。要拿它當production agent 的人請止步，README 只支援 OpenAI 相容介面，沒有權限沙箱、沒有重試策略、沒有持久化，600 行的規模本來就裝不下這些。動手前先確認兩件事：本機 Node.js 是否為 22 或以上，以及你的 API 端點是否走 OpenAI 相容協議，因為 NANOPI_BASE_URL 預設指向 https://api.openai.com/v1，換成自架服務時要自己填對路徑。
社群筆記