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)连接器功能在当前版本尚未完全实现。