ShenSeanChen/waku-agent

解决的问题

Waku-agent 是一个旨在实现透明度和可读性的本地优先个人 AI 助手。它通过提供一个核心循环、记忆系统和评估框架均清晰明确、简单，且完全由用户在自有机器上掌控的代码库，解决了 AI 智能体“黑箱”问题。

工作原理

该系统围绕四个主要支柱构建：

• The Loop: 一个简单的 Python 实现（约 95 行），处理“推理-行动-观察”循环，允许智能体调用工具并迭代直到得出最终回答。
• Memory: 使用本地 SQLite 数据库 (state.db) 进行语义、情境和程序记忆的多层系统。它包含一个“检索门”，决定当前轮次是否真正需要访问记忆，以避免偏差和延迟。
• Harness/Gateway: 一个统一的接口，允许通过 CLI、本地 Web 控制面板、Telegram 或语音命令（带唤醒词检测）访问智能体。
• LLM-Ops: 内置的评估套件，将确定性单元测试（工具是否触发？）与 LLM-as-judge 评分（回答是否有帮助？）分离，并结合了追踪和成本统计功能。

适用对象

它专为那些想要了解严肃智能体底层工作原理的可读蓝图，而非精美产品的开发者和 AI 爱好者，以及偏好本地优先数据所有权的用户而设计。

亮点

• 本地优先记忆: 所有记忆都存储在一个单一的 SQLite 文件中，并镜像到一个人类可读的 MEMORY.md 文件中。
• 可视化控制面板: 一个本地驾驶舱，实时展示智能体的思考过程，包括工具调用、记忆检索和成本。
• 多工具链式调用: 能够执行复杂任务，例如在单次对话中搜索多个网络事件并将其全部添加到日历中。
• 透明评估: 集成的发布闸门，确保在部署前确定性测试 100% 通过。
• 灵活集成: 支持多种 LLM 提供商（Anthropic, OpenAI, Gemini 等），并与 Apple Calendar、Mail 和 Google Calendar 集成。