HanaAgent

一个有记忆、有灵魂的私人 AI 助理

English

---

HanaAgent 是什么

HanaAgent 是一个更加易用的 AI agent，拥有记忆与性格，能够主动行动，并支持在你的电脑上实现多 Agent 协同工作。

作为助手，Ta 是温柔的：无需复杂的配置，无需理解晦涩的术语。HanaAgent 不仅仅面向开发者，它是为每一位坐在电脑前工作的人所设计的助手。 作为工具，Ta 是强大的：能够记住你提到的每一件事，操作你的电脑、浏览网页、搜索信息、读写文件、执行代码、管理日程，甚至能自主学习新技能。

我开发这个项目的初衷是：弥合绝大多数人与 AI Agent 之间的鸿沟，让强大的 Agent 能力不再仅局限于命令行。因此，我针对传统 Coding Agent 进行了多项优化：一方面强化了 Agent 的「人格」属性，使交互更加自然；另一方面，作为一名文员，我也针对日常办公场景进行了大量流程化和工具性的优化，欢迎探索。 此外，HanaAgent 配备了完善的图形化界面。

如果你使用过 claude code、codex、Manus 等 CLI 或图形化 Agent，你会在 HanaAgent 这里找到既熟悉又新奇的体验。

功能特性

记忆 — 结合了主流记忆方案并进行了创新，建立了一套专属的记忆系统，能够牢固记忆近期事项（目前仍在持续优化中）。

人格 — 不再是千篇一律的「AI 助手」。通过人格模板和自定义文件塑造独特的性格，每个 Agent 都有其专属的说话方式和行为逻辑。Agent 之间实现了良好的物理隔离，便于备份。Agent 本身即为一个文件夹，后续将增加备份功能。

工具 — 支持读写文件、执行一次性命令或持续终端会话、浏览网页、通过浏览器后端或 API 搜索互联网、截图、分段长截图、媒体预览、网页检查等。能力覆盖日常办公的绝大多数场景。你也可以通过 server-first CLI 连接同一个 HanaAgent Server，在终端里查看状态、列出所有会话并继续对话。

SKILLS 支持 — 内置兼容庞大的 SKILLS 社区生态。此外，我进行了一些主动性优化：Agent 在执行任务前会尝试从 GitHub 安装社区技能，也能自主编写并学习新技能。默认情况下，Agent 拥有严格的 SKILLS 审核机制，若发现技能安装受阻，可手动关闭审核。

角色卡与技能包 — Agent 支持导入/导出为本地优先的角色卡 zip 文件，按白名单携带人格、头像、记忆和 Skills。Skill Bundle 是独立的技能包基础设施，支持在技能管理页进行分组、拖拽、成组启用，并可单独导出为 zip，方便迁移与分享。

多 Agent 协作 — 支持创建多个 Agent，每个 Agent 拥有独立的记忆、人格和定时任务。Agent 之间可以通过频道进行群聊协作，也可以互相委派任务。

书桌 — 每个 Agent 都有专属的「书桌」，可存放文件、编写便签（Agent 会主动读取并执行）。支持拖拽操作、文件预览以及工作区文件树变更监听，是你与 Agent 之间的异步协作空间。

全屏媒体查看器 — 聊天记录或书桌上的图片、SVG、视频点开即进入暗色遮罩全屏预览模式：支持滚轮缩放、拖拽平移、+ / − / 0 快捷键，并可通过方向键在同会话或同目录下的相邻媒体间切换。

会话管理 — 侧栏支持聊天记录搜索，标题命中优先，必要时可继续检索正文；旧会话归档后可从设置入口恢复或永久删除。聊天正文中的选中文本会自动进入输入框引用卡片，追问时保留原文语境。

定时任务与心跳 — Agent 可设置定时任务（Cron），并定期巡检书桌上的文件变化。当前的自动化执行器已将“触发时机”与“动作内容”解耦：复杂任务由 Agent 后台执行，轻量提醒可直接发送通知，插件动作也可被计划调用。

安全沙盒 — 双层隔离：应用层 PathGuard 四级访问控制 + 操作系统级沙盒（macOS Seatbelt / Linux Bubblewrap / Windows restricted token）。Agent 权限完全由你掌控。平时仅支持对系统普通文件进行只读访问，写入和删除操作限制在工作目录与受控数据目录内。Windows 命令沙盒采用写隔离模型，读取遵循当前用户权限，网络连接也受限于当前用户网络权限；macOS / Linux 的网络隔离由对应平台沙盒能力决定。你可以在“设置 → 安全”页面调整沙盒级别；外部网络支持配置系统代理、手动代理或直连。

插件系统 — 采用约定优先的可扩展插件架构。支持拖拽安装社区插件，插件可贡献工具、技能、命令、Agent 模板、HTTP 路由、Pi SDK 扩展、LLM Provider、页面、侧栏 Widget、配置 schema 以及后台任务。路由可直接访问核心服务（注入 PluginContext），通过 Session Bus 与 Agent 对话、获取历史、管理 session；插件卡片将进入统一的消息块和历史回放。提供两级权限模型（restricted / full-access）以保障安全，extensions/、routes、providers、页面及生命周期能力仅在 full-access 插件中生效。

多平台接入 — 同一个 Agent 可同时接入 Telegram、飞书、QQ、微信机器人，在任何平台与 Ta 对话，支持远程操控电脑；Bridge 消息附带平台上下文，通知亦可回发至当前外部平台。

移动端与局域网前端 — HanaAgent Server 可托管 /mobile/ PWA，手机可通过设备访问密钥或本地账号登录，查看会话、继续聊天和管理工作台文件。另一台桌面端亦可通过 LAN URL + access key 连接至已有 HanaAgent Server，实现多端共享同一套会话和资源。

国际化 — 界面支持中文、英文、日文、韩文、繁体中文 5 种语言。

截图

(此处放置图片)

快速开始

下载安装

macOS（Apple Silicon / Intel）：从 Releases 下载最新 .dmg 安装包。

应用已通过 Apple Developer ID 签名和公证，macOS 可直接打开。

Windows：从 Releases 下载最新 .exe 安装包。

Windows SmartScreen 提示： 由于安装包暂未经过代码签名，首次运行时 Windows Defender SmartScreen 可能会拦截，点击更多信息 → 仍要运行即可，此为未签名版本的正常现象。

Linux：从 Releases 下载最新 .AppImage 或 .deb 包。

首次运行

首次启动时，引导向导将带你完成配置：选择语言、输入名称、连接模型提供商（API key + base URL），并选择三个模型：对话模型（主对话）、小工具模型（轻量任务）、大工具模型（记忆编译和深度分析）。设置页还可单独配置视觉模型，让文本模型通过 Vision Bridge 处理图片附件。HanaAgent 支持 OpenAI 兼容、Anthropic 风格、OAuth Provider 和 Ollama 本地模型等多种接入方式。 目前已添加 OpenAI 的 OAuth 登录支持。

架构

core/           引擎编排层 + Manager（含 PluginManager）
lib/            核心库（记忆、工具、沙盒、Bridge 适配器）
server/         Hono HTTP + WebSocket 服务（独立 Node.js 进程）
hub/            调度器、频道路由、事件总线
desktop/        Electron 应用 + React 前端
shared/         跨层共享工具（config schema、error bus、模型引用等）
plugins/        内置系统插件（随应用打包）
skills2set/     内置技能定义
scripts/        构建工具（server 打包、启动器、签名）
tests/          Vitest 测试

引擎层协调多个 Manager（Agent、Session、Model、Preferences、Skill、Channel、BridgeSession、Plugin 等），并通过统一的 facade 暴露。Hub 负责后台任务（心跳巡检、自动化 / 定时任务、频道路由、Agent 间通信、DM 路由），独立于当前聊天会话运行。