Waku
可在自己电脑上运行、可读可改的本地优先个人助手。
- Star 数
- ★ 1.8k
- 最近更新
- 6 天前
- License
- MIT
- 主语言
- Python
- FA 评分
- 47/100 · 缺口较多
30 秒速览
- 可在哪里用
- 通用 · 跨平台OpenAI API · Claude API
- 开始前需要
- 典型场景
- 希望在自己的笔记本上保留可检查 SQLite 记忆的个人用户，用它记住联系人偏好并在之后安排会议。
- 主要局限
- 首次可用需要选择模型提供商并配置相应密钥；模型调用与可选网页搜索、Telegram 等功能依赖网络。
- 源码审查
- 47/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
Waku 是一个本地优先的个人 AI 助手，核心由 Python 编写的 agent loop、SQLite 记忆、工具调用和评测/追踪组件构成。它通过终端、localhost:7777 仪表盘、Telegram 和可选语音入口接收同一会话中的消息，并在本机进程中执行每轮对话。记忆保存在 `.waku/state.db`，包含语义、情节和程序性记忆，并生成可读的 `.waku/MEMORY.md` 镜像。系统可调用日历、笔记、网页搜索等工具，记录每轮 trace、token 与估算成本，并提供确定性评测和 LLM-as-judge 发布门禁。它适合想拥有并理解个人助手核心机制的开发者或高级个人用户，而非需要托管式成品助手的人。
用户可用 waku 在终端聊天，或运行 waku dashboard 打开本机 127.0.0.1:7777 的浏览器界面；配置 TELEGRAM_BOT_TOKEN 后也可接收 Telegram 消息，waku voice 可通过“waku waku”唤醒词或按键通话。每轮消息先组成包含 SOUL.md、记忆和历史的工作记忆；waku/memory/retrieval_gate.py 决定是否检索 SQLite 中的 facts 与 episodes；随后 waku/loop/agent.py 反复调用模型、执行工具并把结果放回消息上下文，直到模型回复或达到最大迭代数。它可用 create_event 和 list_events 管理本地日历数据、用 save_note 等记忆工具保存信息，并可用 search_web 搜索网页。每轮会写入 .waku/traces/<date>.jsonl，token 用量追加到 .waku/usage.jsonl；make eval、make eval-judge 和 make gate 分别运行确定性评测、裁判评测和发布门禁。
- 希望在自己的笔记本上保留可检查 SQLite 记忆的个人用户，用它记住联系人偏好并在之后安排会议。
- 需要从终端或本地浏览器统一处理个人日程的开发者，用
create_event、list_events查看和创建事件。 - 想观察工具调用、检索决策、迭代次数、token 与成本的 AI 工程学习者，使用 Dashboard 的 Loop、Memory 和 Ops 页面分析每轮运行。
- 希望通过手机消息触发本机助手的用户，配置 Telegram bot token 后以长轮询方式运行
waku telegram。 - 需要把外部 MCP 服务工具接入个人助手的用户，安装
[mcp]extra 并在.waku/mcp.json中声明服务器。 - 想为早晨工作安排生成摘要的 macOS 用户，授权 Calendar.app 和 Apple Mail 后运行
WAKU_APPLE_TOOLS=1 make brief。
如何安装或部署这个 Agent？
快速安装：
pip install waku-agent
waku首次运行会提示需要设置的模型密钥。
如需阅读或修改源码：
git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agent
uv venv && uv pip install -e .
cp .env.example .env在 .env 中选择 WAKU_PROVIDER= 并填入一个已支持提供商的密钥；README 列出 Anthropic（默认）、OpenAI、Gemini、DeepSeek、MiniMax、Kimi、GLM、OpenRouter、OpenCode Zen 和 OpenCode Go。随后运行 uv run waku。
如何使用这个 Agent？
运行 waku 开始终端对话；运行 waku dashboard 启动本机仪表盘并访问 http://localhost:7777。例如，可输入“Remember that Alex prefers morning meetings.”，重启后再询问与 Alex 的会议安排。运行 make eval 执行确定性评测，运行 make gate 执行完整发布门禁。可选功能需额外配置：Telegram 需要 pip install -e '.[telegram]' 和 TELEGRAM_BOT_TOKEN；语音需要 uv pip install -e '.[voice]'；MCP 需要 pip install -e '.[mcp]'。
这个 Agent 有哪些优点和局限？
- 记忆以本地 SQLite
state.db保存，并提供.waku/MEMORY.md可读镜像，用户可直接检查和编辑数据。 - 核心 loop、检索 gate、图工作流和追踪模块均以明确文件路径呈现，适合逐步阅读和定制。
- 同一运行时支持终端、本地 Dashboard、Telegram 与可选语音入口，消息来源会被标记。
- 将确定性测试与 DeepEval 的 LLM-as-judge 评测分开，并提供
make gate发布门禁和评测历史。
- 首次可用需要选择模型提供商并配置相应密钥；模型调用与可选网页搜索、Telegram 等功能依赖网络。
- 本地日历和记忆是默认权威数据；Google Calendar 镜像只写入新建事件，而
list_events仍读取本地数据库。 - Apple Calendar 与 Apple Mail 简报仅面向 macOS，且需要授予系统权限。
- 部分路线图工具仍是 skeleton；例如
run_command、browse_web和schedule_task标为尚未实现的完整功能。
这个 Agent 与同类方案有什么区别？
README 将 Waku 与 ChatGPT、Claude Desktop 等可直接使用的产品区分：Waku 的定位是让用户拥有并修改 loop、记忆 schema、检索 gate 与评测 harness。它也将自己与 OpenClaw、Hermes 等较大型开源助手对比，强调较小、可在短时间阅读的代码规模。作为记忆方案，它以 SQLite FTS5 为默认，并列出 Supabase pgvector、mem0、Letta 与 Zep 作为升级或替代路径。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|
| Waku 当前 | 47 · 缺口较多 | ★ 1.8k | 6 天前 | Python | OpenAI API · Claude API |
| IWE 知识图谱与智能体记忆 | 73 · 存在缺口 | ★ 1.7k | 3 天前 | Rust | Codex · Claude Code · Claude.ai |
| Gini Agent：会记忆、会学习的个人智能体 | 62 · 存在缺口 | ★ 2.3k | 2 个月前 | TypeScript | Codex · OpenAI API · Claude API |
| Mercury | 56 · 缺口较多 | ★ 3.2k | 2 天前 | TypeScript | OpenAI API · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：工具按需启用（如gcal、telegram等extras），有SECURITY.md说明安全边界，数据流透明（本地SQLite、traces、dashboard），敏感数据（API keys）在.env且gitignored。扣分：无用户确认机制（工具调用自动执行），依赖安全仅靠版本下限，外部效果（如Google Calendar写入）无回滚，来源归属仅作者声明。
证据显示：代码结构清晰，README与代码映射一致，有确定性测试。扣分：依赖可用性未锁定（仅下限），失败消息未详细说明（如工具错误处理）。
证据显示：面向开发者，场景多样（CLI、dashboard、voice、telegram），能力边界通过extras和flags控制，环境适配（macOS、Linux）。扣分：触发精度（如wake word）仅简单描述，无详细测试。
证据显示：信息架构清晰（README、docs），安装说明详细，命名稳定（waku命令），示例丰富，MIT许可证明确。扣分：已知限制未明确列出，版本变更日志仅链接releases，维护责任仅作者。
证据显示：输出可用（dashboard、CLI），边际价值高（本地优先、可读代码），成本效益有usage.jsonl记录。扣分：成本效益未量化，无对比数据。
证据显示：README有架构图，代码有测试，但无独立验证。扣分：声明多但无外部佐证，事实与推断未明确分离。
- 工具调用无用户确认，可能自动执行外部操作（如发送消息、写入日历）。
- 依赖版本未锁定，存在供应链风险。
- 外部效果（如Google Calendar写入）无回滚机制。
- 发布者身份未验证，维护责任不明确。
常见问题
数据会离开我的电脑吗？
127.0.0.1 的本机服务器，SQLite 记忆、trace 和用量文件存于本地；但所选托管模型提供商、网页搜索、Telegram 和 Google Calendar 等可选集成会涉及网络请求。支持哪些模型提供商？
WAKU_PROVIDER 选择并配置一个密钥。系统如何避免无限工具循环？
waku/loop/agent.py 在模型不再请求工具时结束；若未自然结束，则由 max_iterations 硬性停止。可以接入自己的工具吗？
[mcp] extra 后，在 .waku/mcp.json 配置 MCP server；其工具会以 <server>_<tool> 名称提供给代理。如何验证修改没有破坏行为？
make eval 做确定性检查，运行 make eval-judge 做 LLM-as-judge 评分，或运行 make gate 同时执行两类检查并依据阈值给出发布门禁结果。