Waku Agent - 本地優先的個人 AI 助手框架

解決什麼

市面上的 AI 助手要麼是黑盒產品(ChatGPT/Claude Desktop),要麼是重框架隱藏實現細節。Waku Agent 提供一個可讀透明的個人 AI 助手實現,核心迴圈僅 95 行 Python,記憶儲存在本地 SQLite 檔案中完全可控。它展示了構建生產級 Agent 的四大支柱:Harness(工具呼叫)、Loop(推理迴圈)、Memory(三層記憶體系)、Eval(評估與 LLMOps)。開發者可以在一個下午讀完全部程式碼,理解每個決策的實現細節,並根據需求自由修改。

為何火

專案在 GitHub 獲得 922 stars,主要因為三個差異化優勢:1)教學價值高 - 作者提供 20 分鐘程式碼講解影片,架構白板圖與程式碼檔案一一對應,是學習 Agent 架構的優質教材;2)本地優先 - 所有資料存在 .waku/state.db 一個 SQLite 檔案中,使用者完全擁有資料主權;3)多模型支援 - 支援 Anthropic/OpenAI/Gemini/DeepSeek/Kimi/GLM/MiniMax 等 10+ 提供商,國內開發者無需梯子可直接使用 Kimi/GLM 等模型。內建的視覺化 Dashboard 能即時展示每次推理的 Gate 決策、工具呼叫、Token 消耗,讓 Agent 執行過程完全透明。

核心功能

記憶體系:實現語義記憶(事實知識)、情景記憶(對話歷史)、程式記憶(技能庫)三層架構,帶記憶門控(決定是否記憶)和記憶整理(決定保留什麼)。推理迴圈:95 行核心迴圈支援多工具呼叫,如"搜尋世界盃賽程並新增到日曆"會自動執行 8 輪迭代(多次搜尋 + 多次建立事件)。檢索門控:智慧判斷何時需要檢索記憶,避免無效查詢。視覺化 Dashboard:本地 Web 介面(localhost:7777)即時展示架構圖、迴圈迭代、記憶狀態、工具呼叫、成本統計,支援拖拽調整佈局。多閘道器接入:同時支援終端 CLI、Web Dashboard、Telegram Bot,所有渠道共享同一記憶。評估體系:內建確定性測試和 LLM-as-judge 兩種評估方式,帶釋出門控。

安裝

快速體驗:

pip install waku-agent
waku                    # 終端對話
waku dashboard          # 瀏覽器介面 → localhost:7777

開發模式(推薦閱讀程式碼):

git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agent
uv venv && uv pip install -e .
cp .env.example .env    # 配置任一模型 API Key
uv run waku dashboard   # 無需啟用虛擬環境直接執行

首次執行會提示配置 API Key。在 .env 中設定 WAKU_PROVIDER(如 kimi)並填入對應 Key 即可。支援 OpenRouter 一鍵接入數百個託管模型。

適合誰

AI 工程師:想深入理解 Agent 架構而非只調用框架 API 的開發者,程式碼註釋詳盡且有影片講解。LLMOps 實踐者:需要評估體系、成本追蹤、視覺化除錯的團隊,Dashboard 提供完整的 Ops 檢視。隱私敏感使用者:資料存本地 SQLite,可完全離線執行(配合本地模型)。國內開發者:原生支援 Kimi/GLM/DeepSeek/MiniMax,無需梯子。教學場景:作為 AI Agent 課程的參考實現,架構清晰且規模適中(非玩具也非過度工程)。不適合只想開箱即用的普通使用者,這是面向開發者的教學型框架。

社群評價

暫無足量社群公開討論,以下為基於專案本身的中立評估:

專案在 GitHub 獲得近千 stars 和 186 forks,顯示出較高的開發者關注度。作者在 YouTube/B站/小紅書等多平臺釋出教學影片,形成了一定的學習社群。從程式碼質量看,核心迴圈確實保持在 100 行左右,架構設計遵循"透明優於抽象"的理念。17 位貢獻者參與且持續更新(最近提交在今天),說明專案維護狀態良好。MIT 協議和本地優先的設計降低了使用門檻。不足之處在於文件主要面向英文使用者,中文社群討論較少;作為教學專案,生產環境的魯棒性(如錯誤恢復、併發處理)需要使用者自行加固。

選型對比

vs ChatGPT/Claude Desktop:商業產品是黑盒且資料在雲端,Waku 程式碼完全開放且資料本地儲存,適合需要定製或隱私保護的場景。商業產品功能更完善,Waku 需要自己擴充套件工具。

vs LangChain/LlamaIndex:重框架抽象層多,Waku 只有 95 行核心迴圈直接可讀。LangChain 生態更豐富,Waku 更適合學習原理或輕量定製。

vs AutoGPT/BabyAGI:早期 Agent 專案多已停止維護,Waku 持續更新且有完整的評估和視覺化體系,工程成熟度更高。

vs Dify/FastGPT:國產低程式碼平臺面向業務人員,Waku 面向開發者提供程式碼級控制,適合需要深度定製的技術團隊。

已知坑

模型依賴:必須配置至少一個 LLM 提供商的 API Key,完全離線執行需自行對接本地模型(如 Ollama)。工具擴充套件:預設工具較少(日曆、筆記、搜尋),需要自己編寫工具函式擴充套件能力。併發限制:Dashboard 是單程序 Web 伺服器,不支援多使用者併發,僅適合個人使用。記憶整理:長期使用後 SQLite 檔案會膨脹,需手動觸發記憶整理或定期清理。國內網路:使用 Anthropic/OpenAI 需要梯子,建議配置 Kimi/GLM/DeepSeek 等國內模型。Telegram Bot:需額外配置 TELEGRAM_BOT_TOKEN,且 Bot 執行在本地機器,關機即停止服務。README 提到的 MCP(Model Context Protocol)聯結器功能在當前版本尚未完全實現。