Waku Agent Skill：95行代码本地AI助手，四支柱架构完全透明

Waku Agent 是一个本地优先的个人 AI 助手框架，核心围绕四大支柱构建：Harness（调度层）、Loop（推理循环）、Memory（记忆系统）和 Eval/LLM-Ops（评估与运营）。最吸引人的特性是代码完全透明——整个 agent loop 只有约 95 行纯 Python，不依赖任何重量级框架，任何人花一个下午就能读完并理解整个系统的工作原理。

功能与原则

Waku Agent 遵循”可读性优先”的设计哲学：不隐藏细节，不用框架遮盖核心逻辑，让用户真正掌握 agent 的每个决策环节。系统内置四大核心模块：

• Harness：连接各种网关（CLI、Telegram、语音、Web）的统一调度层
• Loop：约 95 行纯 Python 的推理循环，工具调用与回复交替执行，有自然退出和硬上限两层 guardrail
• Memory：三层记忆架构——语义记忆（长期事实）、情景记忆（历史对话）、程序记忆（Skill/SOUL.md 规范），配检索门控决定何时读取记忆
• Eval/LLM-Ops：内置确定性测试 + LLM-as-Judge 双轨评估，每次运行都有 trace 和成本追踪

设计原则是”本地优先、隐私第一”——记忆存在本地 SQLite 文件（.waku/state.db），数据不出本机。

认可度

• GitHub Star 数：约 1,300 星（截至 2026-08-22；8 月 12 日约 1,245 星，周增长约 272 星，增长稳定）
• 周增长趋势：持续在 LinkedIn AI Agent Trending 周榜出现（2026-08-11 周排名第 4，约 272 星/周）
• 定位：更偏”教学代码库”而非生产级框架，但代码质量和设计透明度受到开发者社区高度认可
• 生态：活跃开发中（2026-07-15 最新 commit），MIT 许可证，Discord 社区活跃

链接

GitHub：https://github.com/ShenSeanChen/waku-agent

原作者

ShenSeanChen（@ShenSeanChen），独立开发者，运营 YouTube 频道”Sean’s AI Stories”，专注 AI Agent 架构与教学。

介绍

Waku Agent 起源于”Sean’s AI Stories”系列视频，作者希望通过一个真实可跑的代码库，拆解现代 AI Agent 的四大支柱：Harness（如何接入）、Loop（如何推理）、Memory（如何记忆）和 Eval（如何评估）。整个项目最独特的地方在于”代码即文档”——README 里每个架构图中的方框，都对应代码库中一个具体文件，行数极少、可直接阅读。

记忆系统是 Waku 的核心创新点。三层记忆架构各有分工：语义记忆存储长期事实（如”Alex 喜欢上午开会”）；情景记忆记录历史对话事件；程序记忆则以 Skill/SOUL.md 形式保存行为规范。每次对话结束，系统会通过 consolidation 机制将对话提炼为可查询的事实写入 SQLite 数据库。检索门控（retrieval gate）决定当前 turn 是否需要读取记忆，避免每次都做全量检索，保持低延迟。

内置的本地 Dashboard（localhost:7777）是另一个亮点。启动后可以通过浏览器实时观察 agent 的运行状态：Gateway（消息来源）、Loop（每次 turn 的推理步骤与 token 消耗）、Graph（结构化工作流拓扑）、Memory（记忆分栏）、Ops（评估结果与 trace）。所有数据都在本地，没有任何内容上传到云端。

特点

• 零门槛快速启动：pip install waku-agent 后 waku 或 waku dashboard 即可运行，无需复杂配置
• Loop 仅 ~95 行 Python：无 LangGraph、无隐藏控制流，工具调用逻辑完全透明可读
• 三层记忆架构：语义 + 情景 + 程序记忆，SQLite 本地持久化，配检索门控节省 token
• 内置 Eval 双轨：确定性测试 + LLM-as-Judge，release gate 控制在生产环境前拦住不合格输出
• 多模型支持：Anthropic（默认）、OpenAI、Gemini、DeepSeek、MiniMax、Kimi、GLM、OpenRouter，一个 .env 配置切换
• 多网关接入：CLI、浏览器 Dashboard、Telegram Bot、语音输入，同一 brain 多端共享
• Graph 工作流：可选的图引擎，在 Loop 之上增加结构化任务编排能力

使用方法

安装：

pip install waku-agent
git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agent
uv venv && uv pip install -e .
cp .env.example .env
# 编辑 .env，填入 WAKU_PROVIDER 和对应的 API key

运行（终端对话）：

uv run waku

运行（浏览器 Dashboard）：

uv run waku dashboard
# 打开 http://localhost:7777

添加 MCP 工具：
在 .env 中配置 WAKU_MCP_SERVERS=...，Dashboard 的 Tools 标签页会自动显示可用 MCP 工具列表。

体验记忆能力：

# 第一次对话
> "记得 Raj 喜欢傍晚打网球"
> quit

# 第二次对话（重启后）
> "帮我约 Raj 这周五打一场球"
→ Waku 检索到 Raj 的偏好，自动推荐傍晚时间段

使用场景与人群

• AI Agent 学习者：想理解 agent 四大支柱（Harness/Loop/Memory/Eval）如何协同工作的开发者
• 个人效率用户：需要本地、私密记忆的 AI 助手（日程、笔记、邮件）
• 技术博主/讲师：用 Waku 的白板图 + 可读代码做 AI Agent 教学素材
• 想要自主可控 agent 的工程师：不满闭源 AI 产品的黑盒行为，希望自己掌控 agent 的每一步决策

不适用：需要大规模多 Agent 编排、生产级 SLA 的场景（这类需求应选 CrewAI、LangGraph 等）。

输入与输出案例

案例 1：带记忆的日程管理

输入：

"帮我把世界杯剩下所有比赛都加入日历"

输出：
Waku 自动触发 Loop，在 8 次迭代中完成：搜索剩余赛程 → 逐场创建日历事件 → 回复完成报告。Dashboard Loop 标签页显示每次工具调用的推理过程和 token 消耗。

案例 2：检索门控演示

输入：

"我什么时候和 Sergey 游过泳？"

输出：
Waku 激活检索门控（Gate bar 显示 skip→retrieve），从 SQLite 记忆库查询历史情景记录，回复："你在 7 月 18 日和 Sergey 游过泳"。随后问 "12 × 8 是多少？" 时，门控判定不需要记忆，直接推理回答。

Waku Agent 的核心价值不在于替代哪个商业产品，而在于它是一本”可运行的 Agent 架构教科书”。通过阅读 ~95 行的 Loop 代码，你能真正理解 tool call → observe → reason 的闭环是如何工作的；通过查看 Memory 三层架构，能直观感受记忆系统设计的权衡取舍。对想从”会用 AI 工具”升级到”能构建 AI 系统”的工程师来说，这是一个难得的从源码理解 agent 的起点。

GitHub: https://github.com/ShenSeanChen/waku-agent