ai-agents-from-scratch：用 node-llama-cpp 把 agent 拆成十一個可以單獨跑的例子
Demystify AI agents by building them yourself. Local LLMs, no black boxes, real understanding of function calling, memory, and ReAct patterns.
秒懂
- 它是什麼？
- 這個 MIT 授權的 JavaScript 教學專案，把 LLM 推論、function calling、記憶、ReAct 與 AoT 規劃拆成十一個獨立可執行的目錄。它的價值在於把框架藏起來的東西攤開，代價是你得自己下載模型、自己管記憶體，而且它不打算讓你拿去上線。
- 適合誰用？
- 如果你已經會寫 JavaScript，卻說不清楚框架裡的 tool call 到底是誰在決定、記憶是存在哪裡，這個專案值得照著順序跑一遍，尤其是 simple-agent、simple-agent-with-memory、react-agent 三個目錄。如果你要的是能進 production 的 agent runtime，它不對，因為 README 沒有給出任何部署、併發控管或持久化的方案。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 53 天前。
- 用什麼語言寫的？
- 主要是 JavaScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它要解決的是「框架會用但講不清楚」的那一段
多數人第一次接觸 agent 是透過框架，寫幾個 tool 定義、掛上 memory、指定一個 planner，然後東西就跑起來了。問題是當它跑不起來的時候，你很難判斷是哪一層壞掉：是模型沒有產生合法的 JSON、是工具的參數 schema 寫錯、還是迴圈根本沒有終止條件。這個專案針對的就是這種斷層。README 把定位寫得很直接：先理解底層，再決定要不要用框架。
目標讀者是有基本 JavaScript 能力、想搞清楚 function calling 與 ReAct 實際資料流的工程師。它不假設你懂 LLM 推論，所以 intro 從載入模型與 prompt/response 迴圈開始。反過來說，如果你的需求是「這週要交一個會查資料的客服機器人」，這個專案幫不上忙，它沒有任何現成的產品介面。
十一個目錄，其實是一條從推論到規劃的依賴鏈
README 把學習路徑編號成 1 到 11，每一站都附三份東西：可執行的 .js、解釋程式碼的 CODE.md、講概念的 CONCEPT.md。這個結構不是裝飾，因為程式碼本身刻意寫得短，真正的內容在後兩份文件。
前六站是鋪路。intro 處理模型載入與 context；openai-intro 是選修的對照組，讓你看 hosted 模型與本地模型的差別落在網路延遲、成本與資料隱私上；translation 示範用 system prompt 把模型特化成特定角色；think 處理推理任務並指出純推理的極限；batch 用 context sequences 做平行處理；coding 處理串流輸出與 token 預算。
真正的轉折在第七站 simple-agent。README 在這裡寫了一句話，說這是文字生成變成 agency 的地方。它教的是 function calling：用 JSON Schema 定義工具參數，觀察模型什麼時候決定呼叫工具。第八站加上跨 session 的記憶，第九站是 ReAct 的 Reason、Act、Observe 迴圈，第十站是 AoT，把多步計算拆成帶相依關係的原子操作，先產出結構化 JSON 計畫再確定性執行。第十一站處理錯誤分類，把驗證、LLM、工具、工作流四類錯誤給上穩定的錯誤碼。
把 AoT 放在 ReAct 之後是有道理的順序：ReAct 讓模型邊想邊做，AoT 則要求它先把計畫寫完再執行，兩者對模型輸出穩定度的要求不同。至於哪一種在本地小模型上比較可行，README 沒有給出比較數據，這需要你自己在機器上跑過才知道。
跑起來只需要三個指令，剩下的成本在模型檔案
安裝與執行在 README 裡寫得很精簡。先確認 Node.js 18 以上，然後：
npm install node intro/intro.js node simple-agent/simple-agent.js node react-agent/react-agent.js
硬體門檻是至少 8GB 記憶體，README 建議 16GB。這個數字合理，因為 node-llama-cpp 是在本機載入模型權重，模型本身會佔掉相當比例的記憶體，跑 batch 那類平行處理的例子時壓力更明顯。
README 沒有把模型檔放進版本庫，而是要求你自己下載後放進 ./models/ 目錄，細節在 DOWNLOAD.md。這是一個刻意的設計：模型檔動輒數 GB，放進 Git 不現實。代價是第一次設定的摩擦比 npm install 高，而且模型的選擇會直接影響後面幾站的成敗，尤其是需要產生合法 JSON 的 simple-agent 與 aot-agent。
設定層面，README 沒有列出集中的 config 檔或環境變數清單，參數是在各範例程式裡直接寫的。openai-intro 那一站會涉及 API key，README 只提到它是選修，沒有說明金鑰管理的做法，這部分要自己判斷。
本地模型是教學選擇，也是這個專案最大的變數
把推論放在本機有明確好處：沒有網路延遲、沒有 token 帳單、資料不離開機器，而且你能直接看到 context 裡到底塞了什麼。對學習而言，最後一點最重要，因為記憶體系的實作在 hosted 模型上往往被 API 封裝掉了。
但這也是它最脆弱的地方。function calling 與 AoT 都要求模型穩定輸出符合 schema 的 JSON，而本地可取得的模型在這一點上落差很大。README 把 openai-intro 列為選修，等於承認 hosted 模型在某些任務上更省事，卻沒有進一步說明：如果本地模型在 simple-agent 一站反覆產生不合法的工具呼叫，該換模型、該改 prompt，還是該降低任務難度。文件在這方面留了空白。
另一個現實限制是併發。batch 那一站教的是 context sequences 與 GPU 批次處理，但這是在單一 process 內把請求排進同一批。它不等於服務化。README 沒有提到任何多使用者、佇列或資源隔離的機制，把它當成推論伺服器來用會出問題。
與 LangChain.js 的差別不在功能多寡，在誰決定控制流
拿 LangChain.js 來對照最清楚，因為兩者都是 JavaScript、都處理工具呼叫與記憶。差別在控制流的位置。
LangChain.js 提供的是抽象層：chain、tool、retriever、memory 都是可組合的物件，你宣告結構，框架負責串接與呼叫。好處是換模型或換向量庫時改動小，代價是當行為不如預期，你得先弄清楚框架在哪一層做了決定。
這個專案走反方向。simple-agent 與 react-agent 裡的控制流是你自己寫的：什麼時候把工具結果塞回 context、迴圈跑幾輪要停、記憶要用什麼形式保存，全部是明寫的程式碼。所以它更容易除錯，也更容易被你看懂。缺點同樣明顯：這些程式碼沒有經過生產環境的打磨，沒有重試策略的統一封裝（第十一站才開始處理），沒有可觀測性，也沒有測試。
如果你的專案需要快速接上多個資料來源、又要頻繁更換模型供應商，LangChain.js 那類抽象層的價值會蓋過理解成本。如果你需要的是知道每一輪對話到底發生什麼事，這個專案的路線更直接。
維護成本低，因為它幾乎不維護
這個專案沒有發布過 release，最後一次推送是 2026 年 7 月。對教學材料來說，這未必是缺點：範例的價值在於概念，不在版本跟進。但依賴是活的，node-llama-cpp 這類綁定原生函式庫的套件，會隨 Node 版本與底層 llama.cpp 的變動而需要調整，README 沒有承諾任何相容性政策。
授權是 MIT，這是寬鬆授權，你可以修改、商用、再散布，只要保留著作權聲明。要注意的是授權只涵蓋這個 repo 的程式碼，不涵蓋你自行下載的模型權重，每個模型的授權條款不同，商用前要分別確認。這不是法律意見，只是提醒你兩件事被混在一起了。
還有一個容易忽略的成本：README 提到有 Python 版本與一個 companion website，網站負責概念與心智模型，repo 負責程式碼。這代表完整的學習需要跨兩個來源，如果你只想離線讀文件，會少掉一部分說明。
編輯結論
如果你已經會寫 JavaScript，卻說不清楚框架裡的 tool call 到底是誰在決定、記憶是存在哪裡，這個專案值得照著順序跑一遍，尤其是 simple-agent、simple-agent-with-memory、react-agent 三個目錄。如果你要的是能進 production 的 agent runtime，它不對，因為 README 沒有給出任何部署、併發控管或持久化的方案。動手之前先確認三件事：機器是否有 16GB 記憶體、能不能接受在 models/ 目錄放進數 GB 的模型檔、以及你有沒有耐心讀完每個目錄下 CODE.md 與 CONCEPT.md 兩份文件，因為程式碼本身相當短，真正的內容在說明裡。
社群筆記