Waku-Agent：把 AI 助手装进口袋，在代码里读懂它

想象一个画面：凌晨两点，你突然想起上周五跟同事 Alex 说过「下周一开个碰头会」——打开笔记本，对 Waku 说一句「帮我约 Alex 周一上午九点」，它调出记忆、查了日历、创建了日程，然后回你一句「搞定」。你的记忆，它帮你管着；你的时间，它帮你排着。关键是——这一切都运行在你自己的笔记本电脑上，不需要任何云服务，不需要注册任何账号。

这就是 Waku-Agent，一个本地优先的个人 AI 助手项目，由独立开发者 Sean Chen 构建和维护。

waku-agent 系统架构白板

waku-agent 系统架构白板，完整呈现了 Harness → Loop → Memory → Eval/LLM-Ops 四大支柱与各模块的对应关系。

背景故事：一个「授人以渔」的 AI Agent 教学项目

2024-2025 年，AI Agent 概念大热。OpenAI 推出 GPT-4 Agents SDK，Anthropic 发布 Computer Use，OpenClaw、AutoGPT、LangGraph 等框架层出不穷。但这些框架都有一个共同问题：黑箱。你调用一个方法，它返回一个结果——中间发生了什么？为什么选了这个工具而不是另一个？不知道，改不了。

Sean Chen 在他的 Sean s AI Stories YouTube 频道上，用一系列视频回答了这个问题。他的解法是：用最少的代码，完整实现一个 Agent，并让每一行都能被普通人读懂。

waku-agent 就是这个系列视频的核心产物。它从一个教学演示 repo 起步，逐步演化为一个功能完整的个人助手。README 第一句话就亮明了项目哲学：「Your own AI assistant. On your laptop. In code you can read in an afternoon.」（你自己的 AI 助手。在你的笔记本上。代码一下午就能读完。）

项目的另一层野心藏在 CLAUDE.md 里：「it's now growing toward a full open-source assistant (the next Hermes / OpenClaw)」——它正在向一个完整的开源助手框架演进，目标是对标 Hermes-3 和 OpenClaw。

核心设计：四根支柱，读懂 Agent 的本质

waku-agent 的架构极为清晰，用 Mermaid 流程图就能完整表达——README 里直接内嵌了图源码，不需要打开外部链接就能看：

flowchart LR
  GW["Gateway cli · telegram · voice · dashboard"] --> WM["Working memory SOUL.md + memory + history"]
  WM --> LLM
  subgraph LOOP["The Loop — loop/agent.py"]
    LLM -->|"tool call"| TOOLS["Tools create_event · list_events search_web · save_note · …"]
    TOOLS -->|"result"| LLM
  end
  LLM -->|"reply"| REPLY["Reply"] --> GW
  GATE{{"Retrieval gate does this turn need memory?"}} -. only if needed .-> WM
  MEM[("Memory — state.db SQLite + FTS5 semantic · episodic · procedural")] --> GATE
  REPLY -. save chat .-> MEM
  MEM -->|"every N chats"| CONS["Consolidate → facts"] --> MEM
  REPLY --> OPS["LLM Ops trace → eval → gate → release"]
  OPS -. improved prompt/config .-> WM

第一支柱：Harness（驾驭层）

Harness 是整个系统的入口网关，支持六种通信渠道：命令行（默认）、Telegram 机器人、语音输入、Discord、WhatsApp，以及浏览器 Dashboard。所有这些渠道共用同一个 Agent 大脑，消息统一汇入一个对话流。

以 Telegram 为例：设置 TELEGRAM_BOT_TOKEN 环境变量，waku telegram 启动后，手机上发一条消息，立刻触发本地 Agent 运行。这解决了一个很实际的痛点：手机上的 AI 助手永远需要联网、把数据传到云端。Waku 绕过了这个限制——手机只充当终端，显示由本地模型驱动的回复。

第二支柱：The Loop（约 95 行代码的核心循环）

这是整个项目最精华的部分。主循环 waku/loop/agent.py 只有约 95 行，用最直白的 Python 写出 Agent 的本质逻辑：

while not done:
    response = llm(messages, tools)   # reason：模型调用
    if response asks for tools:
        results = run(tool_calls)      # act：执行工具
        messages += results            # observe：观察结果
    else:
        done                            # reply：回复用户

这就是所有 Agent 框架的底层逻辑——waku-agent 没有用任何高级抽象把它藏起来。对于想理解 Agent 内部原理的开发者来说，这 95 行代码是极佳的教科书。

循环内置了两个退出守卫：模型主动停止调用工具（自然结束）或 达到最大迭代次数（防止无限循环）。对于需要并行执行多个步骤的复杂任务（如「把世界杯剩余所有比赛加入日历」），循环可以迭代 8 次甚至更多。

第三支柱：Memory（记忆系统）

waku-agent 的记忆系统是项目的 Hero Feature，设计了三层架构：

语义记忆（Semantic）：基于 SQLite FTS5 的全文搜索，存储关于用户的客观事实。「Alex 喜欢晚上开会」这样的事实，以向量嵌入形式存入数据库，需要时通过语义检索召回。

情景记忆（Episodic）：记录带时间戳的事件序列。用户和 Waku 的每段对话、每次创建日程的操作，都作为独立事件存储，可以按时间线回溯。

程序记忆（Procedural）：以 SKILL.md 文件形式存储的技能定义——类似 Hermes Agent 的 Skill 机制。每个技能文件描述了触发条件和执行步骤，让 Waku 能「学会」新技能。

记忆系统的创新点在于 Retrieval Gate（检索门控）：waku/memory/retrieval_gate.py 是项目的 Hero Moment #1。在每次调用记忆前，先用一个廉价的小模型判断「这条消息是否需要调用记忆」。

打个比方：就像一个秘书，不是用户说每句话都去翻档案柜——而是先判断「这个问题需要查资料吗？」「2+2 等于多少」不需要查，「我约了 Alex 几点？」需要查。小模型这一步判断，既省了延迟（少了不必要的语义搜索），也避免了无关记忆污染回答（过拟合问题）。

记忆还有一个异步 Consolidation 机制：每 N 轮对话后，自动将对话历史蒸馏为简洁的事实存入语义记忆层，防止记忆库无限膨胀，同时保留关键信息。

第四支柱：Eval/LLM-Ops（评估与运维）

waku-agent 内置了两套评估机制并存运行：

确定性评估（Deterministic Evals）：使用 pytest，「工具是否被正确调用」用 0/1 二值判断，结果非此即彼。通过 make eval 运行。

Judge 评估（LLM-as-Judge）：使用 DeepEval，由另一个 LLM 对回复质量打分（百分比），处理开放式判断（语气是否合适？建议是否有用？）。通过 make eval-judge 运行。

两套机制绝不混用——一个是单元测试，一个是评分 opinions。Release Gate 要求 100% 的确定性测试通过，且 Judge 评分达到阈值，才能发布新版本的 Prompt 或模型配置。

运维侧还有一个本地 Dashboard（make dashboard），在 localhost:7777 启动一个小型 Web 服务器，提供实时追踪界面：Overview（总览）、Gateway（多渠道消息流）、Loop（每次迭代详情）、Graph（图工作流）、Memory（记忆层）、Data（SQLite 数据库浏览器）、Ops（评估历史和追踪日志）。浏览器只是 UI，真正的 Agent 进程运行在本地，数据不离开机器。

技术栈与实现

模块	技术选型	说明
核心语言	Python 3.11+	最低要求 3.11，类型注解完善
LLM 接口	Anthropic / OpenAI 双协议	Anthropic 格式覆盖 Claude/Kimi/GLM/MiniMax，OpenAI 格式覆盖 GPT/Gemini/DeepSeek
本地记忆	SQLite + FTS5	`.waku/state.db`，无需额外服务，完全本地
向量搜索	FTS5（默认）/ Supabase pgvector（可选升级）	FTS5 完全免费离线，pgvector 提供更精确的语义匹配
Web 界面	Python 原生 HTTP Server + 原生 JS/CSS	无前端框架依赖，构建步骤为零
日历	SQLite ICS mock（默认）/ Google Calendar（可选）	无需配置直接用，配好凭证后可同步真实日历
追踪	JSONL（默认）/ OpenTelemetry（可选）	JSONL 无依赖，OTel 可接 Phoenix 或 Langfuse
语音	faster-whisper（本地 ASR）+ macOS say（默认 TTS）	神经网络 TTS（Kokoro-82M，Apache-2.0）为可选升级
包管理	uv（推荐）/ pip	pyproject.toml + uv 提供极快的依赖安装

依赖策略极为克制：核心只需 anthropic、openai、python-dotenv、rich 四个包，其余均为可选插件（[telegram]、[voice]、[gcal] 等），按需安装。

上手门槛：零门槛启动

waku-agent 的安装体验在开源 Agent 项目中属于顶级：

最快路径（无需克隆仓库）：

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 .     # 创建虚拟环境 + 安装 waku 命令
cp .env.example .env                # 填入一个 API Key（Anthropic/OpenAI 等）
uv run waku                        # 直接运行，无需激活虚拟环境

配置极为简洁：只需选一个 Provider（Anthropic/OpenAI/Gemini/DeepSeek/MiniMax/Kimi/GLM/OpenRouter 等），填入对应的 API Key，.env 文件搞定。支持 OpenRouter 的 「:free」 模型 ID，可以零成本体验（速率受限）。

局限与争议

不擅长的场景：复杂的多 Agent 协作（多个 Waku 实例间的通信）、实时音视频流处理、需要超长上下文（大于 100K tokens）的任务。在这些方向上，LangGraph 或 CrewAI 可能更合适。

API Key 依赖：虽然本地运行，但模型推理仍需调用外部 API（Anthropic、OpenAI 等），没有完全脱离云端计算。对于追求绝对数据隐私的用户，这是需要权衡的一点。项目正在探索本地推理支持，但目前尚未包含。

尚处于 Beta 阶段：版本号 0.1.1，功能在快速迭代中，API 稳定性不如生产级框架。

记忆质量依赖模型能力：Consolidation 将对话蒸馏为事实的能力，取决于调用模型的上下文窗口和总结能力。在一些长对话中可能丢失细节。

行业意义：让 AI Agent 从黑箱变成白盒

waku-agent 最重要的贡献不是功能本身，而是示范了一个正确的 Agent 架构应该是什么样子。它的代码量和复杂度大约是同类开源项目（OpenClaw、LangGraph、CrewAI 等）的 1/100，却涵盖了所有核心组件。

这种「用最少的代码做最多的事」的理念，在当前的 Agent 框架生态中非常稀缺。大多数框架追求功能丰富，代价是代码难以阅读和修改；waku-agent 追求透明可读，代价是功能覆盖不如商业框架全面。对于学习者来说，waku-agent 是理解 Agent 本质的最佳起点。

项目背后的 Sean Chen 通过 YouTube（Bilibili 同号）、X、Discord 等平台持续更新，架构图以 Excalidraw 源码形式发布在仓库中，任何人都可以下载后在 excalidraw.com 上编辑和分享。这形成了一个活跃的教学社区。

一句话评价：waku-agent 是 AI Agent 领域的一股清流——它不追求最大、最全、最复杂，而是追求最透明、最可读、最可控。在 Agent 框架普遍趋向臃肿的当下，这样一个「一下午读完、立刻能改」的实现，恰恰是最稀缺的东西。