Waku Agent Vibe 项目

项目简介

Waku Agent 是一个本地优先的 AI Agent 框架，全部代码用纯 Python 写成，核心逻辑不到 100 行，任何人花一个下午就能读完理解。与市面上的重型 Agent 框架不同，Waku 不做任何黑盒封装——循环（Loop）、记忆（Memory）、评估（Eval/LLM-Ops）全部摆在明面上，代码即文档。适合想真正搞懂 Agent 内部运作原理的开发者，也适合需要一个完全自主可控的个人 AI 助手。

核心功能

• 本地优先架构：记忆全部存在本地 SQLite 文件（.waku/state.db），不依赖任何云端服务，数据完全归用户自己所有。

• 四层记忆系统：语义记忆（Semantic）+ 情景记忆（Episodic）+ 程序记忆（Procedural），由 Gate 组件决定何时记忆、记忆什么，由 Pass 组件决定保留哪些内容。

• 透明 Agent 循环：核心循环约 95 行纯 Python 代码，从接收消息、Gate 判断、工具调用到回复生成，每一步都完全可见可调试。

• 内置评估体系：同时支持确定性测试（Deterministic Tests）和 LLM-as-Judge 评估，带发布门控（Release Gate），每一次改动都有量化指标支撑。

• 多渠道接入：终端对话、浏览器 Dashboard（localhost:7777）、Telegram Bot、语音输入，全部通过同一个本地进程处理消息。

• 多模型适配器：约 60 行适配器代码对接 Anthropic（默认）、OpenAI、Gemini、DeepSeek、MiniMax、Kimi、GLM、OpenRouter 等多平台，切换Provider只需改一个环境变量。

技术实现

Waku Agent 的架构设计以「可读性优先」为核心理念。整个系统围绕四大支柱展开：Harness（控制流）、Loop（执行循环）、Memory（记忆管理）和 Eval（质量评估）。

Harness 负责任务调度和状态管理，是整个系统的入口。Loop 是最核心的部分，约 95 行代码，完整实现了 Agent 的感知→决策→执行→回复流程。开发者可以直接单步调试，理解 Agent 在每一个节点上如何做判断。

Memory 模块采用分层设计：Semantic Memory 存储向量化的长期知识；Episodic Memory 记录每一次对话的轨迹；Procedural Memory 保存习得的技能和流程。Gate 组件像守门人一样决定哪些信息值得进入记忆，Pass 组件则像编辑一样决定哪些内容值得长期保留。

Eval 模块内置了两套评估机制：一是确定性测试，验证 Agent 对特定输入的输出是否始终一致；二是 LLM-as-Judge，由另一个模型评估主模型输出的质量。两套机制并行运行，共同构成发布前的质量门禁。

技术栈方面，Waku Agent 使用 Python 标准库加少量外部依赖（SQLite 为内置），Dashboard 使用纯静态文件无需构建步骤，部署不需要 Docker 或复杂的环境配置。

快速上手

第一步，安装 Waku Agent：

pip install waku-agent

第二步，运行 Agent（终端模式）：

waku

首次运行会提示设置 Provider Key（支持 Anthropic/OpenAI/Gemini/DeepSeek 等）。

第三步，打开浏览器 Dashboard（可选）：

waku dashboard

访问 http://localhost:7777，可以图形化观察 Agent 内部的消息流向、Gate 判断、Token 消耗等信息。

第四步，配置 Telegram Bot（可选）：

设置 TELEGRAM_BOT_TOKEN 环境变量，Waku 会自动启动 Telegram Bot 接入，实现手机端随时唤醒个人助手。

高级用法：克隆源码研究学习

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

适用人群

• 想深入理解 AI Agent 内部机制的学习者（代码量小、可读性极高）
• 需要完全自主可控的个人 AI 助手（数据存在本地、无云依赖）
• 关注隐私保护、不希望对话数据上云的开发者
• 想要一个轻量级 Agent 框架作为二次开发基础的工程师
• AI 爱好者/创作者（肖恩君的双语 YouTube 频道配套教程丰富）