ShenSeanChen/waku-agent

解決的問題

Waku-agent 是一個旨在實現透明度與可讀性的本地優先個人 AI 助手。它透過提供一個核心迴圈、記憶系統與評估框架均清晰明確、簡單，且完全由使用者在自有機器上掌控的程式碼庫，解決了 AI Agent「黑箱」的問題。

工作原理

該系統圍繞四個主要支柱構建：

• The Loop: 一個簡單的 Python 實作（約 95 行），處理「推理-行動-觀察」迴圈，允許 Agent 呼叫工具並迭代直到得出最終回答。
• Memory: 使用本地 SQLite 資料庫 (state.db) 進行語義、情境與程序記憶的多層系統。它包含一個「檢索門」，決定當前輪次是否真正需要存取記憶，以避免偏差與延遲。
• Harness/Gateway: 一個統一的介面，允許透過 CLI、本地 Web 控制面板、Telegram 或語音指令（帶喚醒詞檢測）存取 Agent。
• LLM-Ops: 內建的評估套件，將確定性單元測試（工具是否觸發？）與 LLM-as-judge 評分（回答是否有幫助？）分離，並結合了追蹤與成本統計功能。

適用對象

它專為那些想要了解嚴肅 Agent 底層工作原理的可讀藍圖，而非精美產品的開發者與 AI 愛好者，以及偏好本地優先數據所有權的使用者而設計。

亮點

• 本地優先記憶: 所有記憶都儲存在單一的 SQLite 檔案中，並鏡像到一個人類可讀的 MEMORY.md 檔案中。
• 視覺化控制面板: 一個本地駕駛艙，即時展示 Agent 的思考過程，包括工具呼叫、記憶檢索與成本。
• 多工具鏈式呼叫: 能夠執行複雜任務，例如在單次對話中搜尋多個網路事件並將其全部加入日曆中。
• 透明評估: 集成的發佈閘門，確保在部署前確定性測試 100% 通過。
• 靈活整合: 支援多種 LLM 提供商（Anthropic, OpenAI, Gemini 等），並與 Apple Calendar、Mail 和 Google Calendar 整合。