waku-agent：主循环只有 95 行的开源 agent harness，专为读懂而写

本文介绍 ShenSeanChen 开源的 waku-agent（1.8 千 stars，MIT）——一个"你真正拥有"的本地优先 AI agent harness：主循环只有约 95 行纯 Python，记忆是主角（语义+情景+程序三柱），还内置确定性测试与 LLM-as-judge 双轨评测。它最大的价值是可读——专为读懂 agent 内部而写。

项目简介

现在流行的 agent 框架大多又黑又厚，waku-agent 反其道而行：这是一个配合视频课程系列（作者 YouTube/B站/小红书都有内容）的教学型 harness，每一行代码都设计给人读。架构白板上每个框都对应一个文件，20 分钟的代码走读视频把循环、记忆三支柱、评测、Telegram 网关和"Waku Waku"唤醒词全部过一遍。

它也是作者 Waku Memory（同套记忆跑在 Claude Code、Codex、Grok Bot 里，waku.one）的参考实现。

核心特性

记忆是主角：语义 + 情景 + 程序性三柱记忆，带一个"要不要记住"的门控和一个"留什么"的整理环节——不是无脑堆 vector
~95 行主循环：plain Python，一步一步能走通
可视化思考：本地 dashboard（localhost:7777）实时点亮每条消息在 harness 里的流动
评测内置：确定性测试与 LLM-as-judge 并排跑，带发布门禁（release gate）

快速开始

只想跑：

bash

pip install waku-agent
waku                  # 终端对话
waku dashboard        # 或浏览器驾驶舱 → localhost:7777

想读代码（这个仓库的意义所在）：

bash

git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agent
uv venv && uv pip install -e .
cp .env.example .env   # 选一个供应商，贴一个 key
uv run waku

先试这句："Remember that Alex prefers morning meetings." 退出重启，再说"Book a catch-up with Alex on Friday"——它记得。

适用场景

想真正理解 agent harness 内部机制的开发者：95 行循环是最好的教材
自建记忆系统的团队：三柱记忆 + 门控设计可直接借鉴
agent 应用开发者：内置评测框架解决"改了 prompt 不知道变好变坏"的老问题

注意事项

教学定位，生产使用需自行补安全、多租户等工程化部分
Telegram 网关等集成需要对应平台凭证
哔哩哔哩/小红书有中文内容，中文用户学习路径友好

项目链接

GitHub 仓库：https://github.com/ShenSeanChen/waku-agent
Waku Memory：https://www.waku.one
代码走读视频：YouTube 播放列表（仓库 README 内链）