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

OpenHanako 是一个带着记忆、有着性格、能主动行动的私人 AI 助手。它不仅以“工具性”的方式帮助你完成日常工作，更像一个有灵魂的同伴，能理解你的偏好、记住你说过的事、并在你的电脑上协作完成任务。为了更直观地呈现项目的定位，右上方还有一个可识别的标识图：

OpenHanako 的目标很明确：打破 AI 助手通常局限于命令行或极简界面的窠臼，让强大的 Agent 能力回到日常办公场景中来。它不仅面向程序员，更面向每一个坐在电脑前工作的人。你不需要花费大量的时间来理解复杂的配置，也不需要掌握晦涩的术语，Hanako 会以更自然的方式与你沟通、协作，帮助你更高效地完成任务。

此外，Hanako 的设计强调“可用性”和“可扩展性”。它内建了丰富的图形界面，提供直观的交互；同时也保持了对社区技能、插件、以及跨平台接入的开放性。若你曾经使用过 Claude Code、Codex、Manus 等 CLI 或图形化 Agent，你在 OpenHanako 里会找到熟悉的感觉，也会遇到新颖的体验。

下面，我们将从核心特性、快速上手、架构与技术栈、开发与扩展、以及实际使用的视角，系统地介绍 OpenHanako 的全貌。

---

一、功能特性：从记忆到协作的全方位能力

OpenHanako 将“记忆、人格、工具、协作”这几大维度整合为一个完整的生态，让 Agent 能在你的桌面实现真正的落地能力。

• 记忆

• 将你的对话、任务、偏好等信息纳入记忆体系，近期事件记得特别牢固，方便后续继续工作或回顾。记忆与个人化的数据管理在后续版本中会进一步优化与加强。

• 人格

• 不是千篇一律的“AI 助手”格式，而是通过人格模板和自定义人格文件来塑造独特的说话方式和行为逻辑。不同的 Agent 之间是相对独立的，便于备份与恢复，后续还能通过“代理人文件夹”的形式进行管理。

• 工具

• 全面覆盖日常办公场景：读写文件、执行终端命令、浏览网页、通过浏览器后端或 API 搜索信息、截图、媒体预览、网页检查等。能力覆盖广泛，能够帮助你完成从文书工作到数据检索、再到简单的自动化任务的链路。

• SKILLS 支持

• 内置对庞大 SKILLS 生态的向前兼容与优化：Agent 可以从 GitHub 自动安装社区技能，或自己编写并学习新技能。默认会有严格的 SKILLS 审核，确保稳定性；若遇到无法安装的技能，你也可以选择关闭。

• 多 Agent

• 可以创建多个 Agent，各自拥有独立的记忆、人格和定时任务。Agent 之间可以通过频道群聊协作，也可以互相委派任务，实现分工协作。

• 书桌

• 为每个 Agent 配置“书桌”，放置文件、写笺（便签），Agent 会主动读取并执行书桌上的内容。支持拖拽操作与文件预览，成为你与 Agent 的异步协作空间。

• 全屏媒体查看器

• 在聊天、书桌里出现的图片、SVG、视频等媒体，点开后进入暗色遮罩的全屏预览。支持滚轮缩放、拖拽平移，键盘快捷键带来更流畅的浏览体验；不同媒体的切换也变得自然。

• 定时任务与心跳

• Agent 可以设置 Cron 风格的定时任务，并定期巡检书桌上的文件变化。即使你不在现场，Ta 也会按照预设计划自主工作，保证持续性与稳定性。

• 安全沙盒

• 双层隔离：应用层的 PathGuard（四级访问控制）+ 操作系统级沙盒（macOS 的 Seatbelt、Linux 的 Bubblewrap）。Agent 的权限受你掌控，默认只访问工作目录和一些用户文件；需要调整权限时，可以在设置 → 安全中修改沙盒等级。

• 插件系统

• 约定优先的可扩展插件架构。通过拖拽安装社区插件，插件可以贡献工具、技能、命令、Agent 模板、HTTP 路由、事件钩子、LLM Provider、页面、侧栏 Widget、配置 schema 和后台任务。路由可直接访问核心服务，通过 Session Bus 与 Agent 对话、获取历史、管理 session。两级权限模型（restricted / full-access）保障安全。

• 多平台接入

• 同一个 Agent 可以同时接入 Telegram、飞书、QQ、微信机器人等平台，在任意对话场景下都能远程操作本地电脑。

• 国际化

• 界面支持中文、英文、日文、韩文、繁体中文等多语言版本，方便不同地区的用户使用。

---

二、快速开始：从下载到首次运行

要体验 OpenHanako，最直接的路径是下载安装并进行首次运行配置。以下要点帮助你快速进入实操阶段。

• 下载安装

• macOS（Apple Silicon / Intel）：从 Releases 下载最新的 .dmg 包，应用已通过 Apple Developer ID 签名和公证，可以直接打开使用。

• Windows：从 Releases 下载最新的 .exe 安装包。首次运行时，Windows Defender SmartScreen 可能会提示未签名；点击“更多信息”并选择“仍要运行”，即可继续使用。未来版本也可能提供签名更新。

• Linux：当前尚在计划中，未来会提供相应版本与打包方式。

• 首次运行

• 第一次启动时会引导配置向导：选择语言、输入你的名字、连接模型提供商（API key + 基础 URL），并选择三个模型：

  • 对话模型（主对话）
  • 小工具模型（轻量任务）
  • 大工具模型（记忆编译和深度分析）

• 设置页还可单独选择视觉模型，让文本模型通过 Vision Bridge 处理图片附件。

• Hanako 支持多类接入：OpenAI 兼容、Anthropic 风格、OAuth Provider 和 Ollama 本地模型等。当前开放了 OpenAI 的 OAuth 登录；鉴于 Anthropic 的账号封禁风险，Related 登录功能会按策略调整，暂时不提供 Anthropic OAuth。

---

三、架构与技术栈概览

OpenHanako 的设计以模块化为核心，核心“引擎编排层”与“管理层”协同工作，确保 Agent 的创建、运行、协作、以及跨平台扩展的可维护性。

• 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 间通信、Direct Message 路由），在任何对话会话之外独立运行。Session 内的用户可见文件通过 SessionFile sidecar 统一登记，桌面端、Bridge 与未来移动端按各自能力消费同一份文件身份。

Bridge 平台的媒体发送规则和插件贡献规范也清晰呈现：媒体路由、权限、和插件生态都被设计成可明确掌控的扩展点。Server 以独立 Node.js 进程运行，通过 Electron 的 spawn 或独立启动；前后端通过 WebSocket 保持高效通信。用户数据的根目录由 HANA_HOME 决定，生产环境默认 "~/.hanako"，开发环境 "~/.hanako-dev"。Pi SDK 的数据隔离也在特定目录内独立管理。

技术栈要点：

• 桌面端：Electron 38
• 前端：React 19 + Zustand 5 + CSS Modules
• 构建：Vite 7
• 服务端：Hono + @hono/node-server
• Agent 运行时：Pi SDK
• 数据库：better-sqlite3（WAL 模式）
• 测试：Vitest
• 国际化：5 种语言（zh / en / ja / ko / zh-TW）

平台支持方面，OpenHanako 已覆盖 macOS（Apple Silicon 与 Intel）、Windows，Linux 与移动端计划中。开发与测试环境的命令与流程也有明确指引，便于开发者二次入门。

---

四、架构细节：为什么这样设计

• 多代理（Agent）模型

• 通过将不同任务拆解为不同 Agent，每个 Agent 拥有独立记忆、人格与任务日程。这样的设计实现了高并发、低耦合的协作模式，降低了模块之间的牵绊，让复杂任务也可以分步完成。

• 书桌与文件系统整合

• 书桌作为 Agent 的工作区域，拥有文件、笔记、待办、草稿等元素的集中管理。Agent 可以主动读取并执行书桌中的指令，形成自然的工作流。

• 安全沙盒：两层保护

• PathGuard 的应用层访问控制 + 操作系统级沙盒，确保即使在需要外部资源的场景中也能保持高度的权限控制。用户可通过设定调整安全级别，最大化地在便利性与安全之间保持平衡。

• 插件与技能的开放生态

• 插件系统允许社区贡献工具、技能、命令、路由、事件钩子等。通过两级权限模型，既能让社区力量快速扩展功能，又能保护用户环境不被未授权操作侵扰。

• 跨平台接入

• 将同一 Agent 通过 Telegram、飞书、QQ、微信等渠道接入，使得远程协作成为可能。你在任意对话平台上的指令都能落回到本地电脑执行，提升使用场景的灵活性。

---

五、视觉与体验：界面、截图与互动

OpenHanako 重视“可用性与可观性”，提供了直观的图形界面与交互设计。你可以在桌面应用中直接看到“书桌”的排列、任务的进度、以及媒体的全屏预览效果。为帮助读者直观理解，项目中包含以下图片示例：

• 主界面与概览

• [Hanako 主界面截图] 包含核心工作区、书桌、对话区域等组件的展示，帮助你感受日常使用的场景。

• 品牌与标识

• 侧重品牌视觉的图片，帮助理解 OpenHanako 的风格定位与情感表达。

• Banner 设计

• 顶部横幅图像，作为项目呈现的一种视觉入口，强调“有记忆、有灵魂的私人 AI 助手”的理念。

这些图像放置在文中不同位置，帮助读者在阅读文字的同时形成直观印象，理解产品的定位与风格。

---

六、快速体验的注意事项与常见问题

• 安装与签名

• macOS 用户不必过分担心签名问题，OpenHanako 的安装包已签名并公证。Windows 用户在首次运行时可能遇到 SmartScreen 提示，请按指引继续执行。

• 授权与模型

• 为确保用户的数据安全，OpenHanako 支持多类接入方式（OpenAI、Anthropic、Ollama、OAuth Provider 等）。在实际使用中，请根据需求选择合适的提供商并妥善管理 API Key 与 base URL。

• 安全与隐私

• 沙盒机制是保护隐私与系统安全的关键。你可以在设置中调整沙盒等级，控制 Agent 对本地资源的访问范围，以实现更高的定制化安全策略。

• 社区与扩展

• 插件生态是 OpenHanako 的核心竞争力之一。若你对某个工作流有特别需求，可以查看插件开发指南，尝试编写或使用现有插件来扩展功能。

---

七、面向开发者与贡献者：如何参与

• 插件系统

• 插件可以贡献工具、技能、命令、Agent 模板、HTTP 路由、事件钩子、LLM Provider、页面、侧栏 Widget、配置 schema 和后台任务。你可以通过拖拽方式安装社区插件，快速扩展 OpenHanako 的能力。

• 安全性与权限

• 两级权限模型（restricted / full-access）确保插件在可控的范围内运行，避免对用户系统造成不可控的影响。

• 跨平台扩展

• 代理 Agent 的跨平台接入能力设计，确保在桌面端、桥接端、以及未来的移动端有一致的体验。

• 本地化与国际化

• 界面已经支持多语言，未来也会持续完善本地化文本和区域适配，方便更多用户使用。

---

八、结语：加入 OpenHanako 的旅程

OpenHanako 是一个以“人性化、易用、可扩展”为核心目标的私人 AI 助手项目。它把强大的模型能力带入日常办公的实际场景，让 AI 不再是冷冰冰的工具，而是一个贴心的工作伙伴。你可以通过安装、配置、并结合自己的工作流，逐步让 Hanako 学会记住你的偏好、理解你的需求、主动协作完成任务。

如果你对 OpenHanako 感兴趣，欢迎查看官方页面与相关文档，参与插件开发、贡献技能、或提交问题与建议。让我们一起把 AI 助手的潜力落地到每一个工作的日常，让人机协作变得更自然、更高效。

---

参考与链接

• 官网与主要页面：OpenHanako 官网
• 提交 Issue：官方 Issue 页面
• 安全页与安全政策：安全页面、SECURITY.md
• 插件开发指南：PLUGINS.md
• 贡献指南：CONTRIBUTING.md
• 版本发行与下载：Releases 页面

为了方便直观理解，文中嵌入了以下图片以支持文字描述：

• 顶部横幅：OpenHanako Banner
• 品牌标识：Hanako 标识图
• 主界面截图：Hanako 主界面

如果你愿意，随时可以动手尝试将自己的工作流对接到 OpenHanako 的书桌和 Agent 体系中。我们期待看到你创造出更多实用的、贴近日常工作场景的用例，让“私人 AI 助手”成为每个人工作的一部分，而不再只是少数开发者的专属工具。