HanaAgent — 有记忆、有灵魂的私人 AI 助理

图注：HanaAgent 桌面端主界面，支持多 Agent 协作、记忆系统和插件扩展。

---

一、它是谁：一位"会成长"的 AI 搭档

想象一下这样的场景：你周一早上打开电脑，AI 助手主动提醒你："上周你让我整理的会议纪要草稿还在桌面，记得抽空看一下。"这不是预设的定时提醒——是它真的记住了你们对话中提到的事项，并主动跟进。这，就是 HanaAgent 想要实现的体验。

HanaAgent（项目名 liliMozi/openhanako，目前 5,700+ ★）是一款主打"像人一样成长"的个人 AI 助理。与传统的命令行 AI 工具（如 Claude Code、Codex）不同，它不只是执行单次任务的工具，而是一个能够跨会话积累记忆、保持独特人格、在多个平台上持续陪伴你的"数字同事"。

项目的核心设计理念非常明确：弥合大多数人和 AI Agent 之间的使用门槛。作者在 README 中坦言，自己本职是文员，开发 HanaAgent 的初衷是让身边不写代码的朋友也能用上 AI 能力。因此，它选择了图形界面优先的路线，从安装到配置全程可视化，不需要掌握命令行。

---

二、技术架构：Electron + Hono 的桌面 Agent 方案

分层结构

core/           引擎编排层 + 各 Manager（Agent/Session/Model/Plugin等）
lib/            核心库（记忆、工具、沙盒、Bridge适配器）
server/         Hono HTTP + WebSocket 服务（独立 Node.js 进程）
hub/            调度器：心跳巡检、定时任务、频道路由、Agent间通信
desktop/        Electron 应用 + React 前端
plugins/        内置系统插件（随应用打包）
skills2set/     内置技能定义
shared/         跨层共享工具

关键设计点：Server 独立进程

Server 以独立 Node.js 进程运行（由 Electron spawn 或独立启动），通过 Vite 打包，通过 WebSocket 与渲染进程通信。这意味着用户可以：

• 在桌面端 GUI 使用
• 通过 npm run cli 在终端连接同一个 Server
• 同一 Server 还能同时给 PWA 移动端提供服务

技术栈一览

层级	技术选型	说明
桌面端	Electron 42	跨平台桌面框架
前端	React 19 + Zustand 5	状态管理用 Zustand，CSS Modules
构建	Vite 7	现代化前端构建工具
服务端	Hono + @hono/node-server	轻量高性能 Node.js Web 框架
Agent 运行时	Pi SDK (@earendil-works/pi-agent-core)	项目依赖的第三方 Agent 运行时
数据库	better-sqlite3 (WAL 模式)	本地 SQLite 持久化
测试	Vitest	Vite 原生测试框架

值得注意的是，项目使用了 Pi SDK 作为 Agent 核心运行时，而非从零自研。Pi SDK（badlogic/pi-mono）是一个开源的 Agent 框架，HanaAgent 在其基础上构建了记忆、人格、工具等上层能力。这种"站在巨人肩膀上"的策略让项目能够专注于差异化能力建设。

---

三、核心能力：记忆 · 人格 · 工具 · 多 Agent

记忆系统

HanaAgent 的记忆系统结合了主流方案，并在 README 中坦诚表示"目前确实有待优化"。记忆通过 better-sqlite3 数据库持久化，支持跨会话保持。每个 Agent 有独立的记忆空间，互不干扰。用户也可以手动导出/导入记忆。

人格系统

每个 Agent 都可以加载人格模板或自定义人格文件，塑造独特的说话风格和行为逻辑。人格以独立文件夹管理，备份和迁移非常方便——备份一个 Agent 就是备份一个文件夹。

工具集

HanaAgent 提供的能力覆盖日常办公场景：

工具类别	具体能力
文件操作	读写文件、管理目录
命令执行	一次性命令或持续终端会话
网页浏览	通过浏览器后端浏览、截图、分段长截图
搜索	浏览器后端或 API 搜索互联网
媒体处理	图片预览、视频预览（内置全屏媒体查看器）
文档	Excel、Word 等办公文档读取（通过插件）
代码执行	集成代码运行和执行环境

多 Agent 协作

可以同时创建多个 Agent，各自独立维护记忆、人格和定时任务。Agent 之间可以通过频道群聊协作，也可以互相委派任务。例如：主 Agent 收到用户请求后，可以将子任务委派给专业 Agent 处理。

Skill 生态兼容

HanaAgent 内置兼容 SKILLS 社区生态，并做了主动优化——Agent 在需要时可以从 GitHub 自动安装社区技能，也可以自己编写并学会新技能。默认启用了技能审核机制，发现安装异常时可以手动关闭审核。

---

四、插件系统：约定优先的可扩展架构

HanaAgent 的插件系统设计相当完善，采用"约定优先"的哲学：

插件可以贡献的内容：

• 工具（Tools）
• 技能（Skills）
• 命令（Commands）
• Agent 模板
• HTTP 路由
• Pi SDK Extension
• LLM Provider
• 页面（Pages）
• 侧栏 Widget
• 配置 Schema
• 后台任务

两级权限模型：

• restricted：仅能贡献工具
• full-access：可以贡献所有能力，包括路由、页面、生命周期等

安装方式：拖拽文件夹或 zip 包到安装区，无需重启即可热加载。开发调试支持 plugin.dev.reload 热重载。内置 beautify（美化）、office（办公）、media（媒体）、jimeng-cli（图像生成）等插件。

---

五、安全机制：双层隔离的沙盒设计

HanaAgent 对安全下了相当功夫，采用双层隔离：

1. 应用层 PathGuard：四级访问控制

   • 只读访问系统普通文件
   • 写入和删除限制在工作目录与受控数据目录
   • 可在设置 → 安全页面调整沙盒级别

2. 操作系统级沙盒：

   • macOS：Seatbelt
   • Linux：Bubblewrap
   • Windows：Restricted Token（写隔离模型，读按当前用户权限自然发生）

外部网络支持配置系统代理、手动代理或直连。

---

六、部署体验：图形引导 + 多平台覆盖

安装包

平台	状态	格式
macOS (Apple Silicon)	✅ 已签名公证	.dmg
macOS (Intel)	✅	.dmg
Windows	Beta	.exe
Linux	✅	.AppImage / .deb

首次运行引导

首次启动会进入引导向导，完成：

1. 选择语言（支持中/英/日/韩/繁 5 种）
2. 输入用户名字
3. 选择模型提供商（API Key + Base URL）
4. 配置三个核心模型：
   • 对话模型（主对话）
   • 小工具模型（轻量任务）
   • 大工具模型（记忆编译和深度分析）
5. 可选配置视觉模型（处理图片附件）

支持接入的模型类型：OpenAI 兼容 API、Anthropic 风格、OAuth Provider、Ollama 本地模型。

部署局限

• ❌ 无 Docker 容器化，不支持一键部署
• ⚠️ 依赖用户自行准备 LLM API（不支持纯本地离线运行，除非接 Ollama）
• ⚠️ Windows 版本仍处于 Beta

---

七、亮点与局限

✅ 亮点

1. 零门槛 GUI：完全可视化的配置和操作，不需要命令行经验
2. 记忆 + 人格双系统：让 AI 不只是工具，更像有性格的搭档
3. 多平台统一接入：Telegram、飞书、QQ、微信同时在线，一个 AI 在所有地方陪伴你
4. 插件生态：约定优先的架构降低了插件开发门槛
5. 多语言界面：中日韩英繁全覆盖

⚠️ 局限与风险

1. API Key 必须：完全依赖外部 LLM API，无法完全离线使用
2. Windows Beta：稳定性不如 macOS/Linux
3. 记忆系统待优化：作者明确表示仍有改进空间
4. 非 Docker 部署：无法在服务器端一键部署为后台服务
5. Electron 开销：相比纯命令行工具，桌面应用资源占用更高

---

八、适用人群

场景	推荐度	说明
非技术用户寻找 AI 助理	⭐⭐⭐⭐⭐	图形界面、引导配置，门槛最低
技术用户寻找 Claude Code 替代	⭐⭐⭐	功能接近，但 GUI 路线不同
需要多 Agent 协作	⭐⭐⭐⭐	支持 Agent 间消息传递和任务委派
需要 IM 平台接入	⭐⭐⭐⭐	Telegram/飞书/QQ/微信全覆盖
追求纯本地部署	⭐⭐	需要 Ollama，不支持纯离线

---

项目地址：liliMozi/openhanako | 官网：openhanako.com 许可：Apache-2.0 | 语言：TypeScript | 最新版本：v0.441.32