用途
HanaAgent（仓库名 openhanako）是一个个人 AI 助理，定位为“有记忆、有灵魂的私人 AI 助理”。项目初衷是弥合普通用户与 AI Agent 之间的缝隙，让强大的 Agent 能力不再只局限于命令行里，不只面向 coder，而是为每一个坐在电脑前工作的人设计。
主要能力
- 记忆：结合主流记忆方案，并自行发挥构建了记忆系统，近期的事情记得非常牢固，但目前确实有待优化。
- 人格：不是千篇一律的“AI 助手”。通过人格模板和自定义人格文件塑造独特的性格，每个 Agent 都有自己的说话方式和行为逻辑，Agent 之间分离做得很好，备份方便，Agent 就是文件夹。
- 工具：读写文件、执行一次性命令或持续终端会话、浏览网页、通过浏览器后端或 API 搜索互联网、截图、分段长截图、媒体预览、检查网页。能力覆盖日常办公的绝大多数场景。也可以通过 server-first CLI 连接同一个 HanaAgent Server，在终端里查看状态、列会话和继续对话。
- SKILLS 支持：内置兼容 SKILLS 社区生态，并做了主动优化：有时候干活之前，Agent 会从 GitHub 安装社区技能，Agent 也可以自己编写并学会新技能。默认情况下对 SKILLS 有比较严格的审核，如果发现 SKILLS 装不上可以自行关闭。
- 角色卡与技能包：Agent 可以导入/导出为本地优先的角色卡 zip，按白名单携带人格、头像、可选记忆和 Skills。Skill Bundle 是独立的技能包基础设施，可以在技能管理页分组、拖拽、成组启用，并单独导出为 zip，方便迁移和分享。
- 多 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 extension、LLM Provider、页面、侧栏 Widget、配置 schema 和后台任务。路由可直接访问核心服务（PluginContext 注入），通过 Session Bus 与 Agent 对话、获取历史、管理 session；插件卡片会进入统一的消息块和历史回放。两级权限模型（restricted / full-access）保障安全，extensions/、routes、providers、页面和生命周期能力只在 full-access 插件里生效。
- 多平台接入：同一个 Agent 可以同时接入 Telegram、飞书、QQ、微信机器人，在任何平台和 Ta 对话，可以远程操作电脑；Bridge 消息会带平台上下文，通知也可以回发到当前外部平台。
- 移动端与 LAN 前端：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 Defender SmartScreen 可能会拦截，点击 更多信息 → 仍要运行 即可，为未签名版本的正常现象。
- Linux：从 Releases 下载最新 .AppImage 或 .deb 。
- 首次启动：引导向导会带你完成配置：选择语言、输入你的名字、连接模型提供商（API key + base URL），并选择三个模型：对话模型（主对话）、小工具模型（轻量任务）、大工具模型（记忆编译和深度分析）。设置页还可以单独选择视觉模型，让文本模型通过 Vision Bridge 处理图片附件。HanaAgent 支持 OpenAI 兼容、Anthropic 风格、OAuth Provider 和 Ollama 本地模型等多类接入。目前也添加了 OpenAI 的 OAuth 登录，鉴于 Anthropic 会有封号风险，所以暂时不提供。
架构说明
引擎层协调多个 Manager（Agent、Session、Model、Preferences、Skill、Channel、BridgeSession、Plugin 等），通过统一的 facade 暴露。Hub 负责后台任务（心跳巡检、自动化/定时任务、频道路由、Agent 间通信、DM 路由），独立于当前聊天会话运行。
Session 内的用户可见文件通过 SessionFile sidecar 统一登记，桌面端、Bridge、Mobile PWA 和其它远程前端按各自能力消费同一份文件身份。各 Bridge adapter 显式声明自己的媒体类型、投递方式与大小限制；插件文件贡献规则见 PLUGINS.md 。
本机 staged 文件优先由各平台 adapter 直接上传：Telegram / 飞书 / 微信走各自上传接口，QQ 走官方 Bot 分片上传接口，再发送 msg_type: 7 富媒体消息。preferences.bridge.mediaPublicBaseUrl / HANA_BRIDGE_PUBLIC_BASE_URL 只用于仍需公网 URL 的平台或远程 fallback；该 URL 作为 /api/bridge/media/:token 临时文件路由的 origin，文件本身仍由短期 token、下载次数和本地路径白名单保护。Hana 不会自动开启公网 tunnel，公网入口必须由用户显式提供。
Server 以独立 Node.js 进程运行（由 Electron spawn 或独立启动），通过 Vite 打包，@vercel/nft 追踪依赖。与 Electron 渲染进程通过 WebSocket 通信。用户数据目录由 HANA_HOME 决定（生产默认 ~/.hanako ，开发默认 ~/.hanako-dev ）。Hana 管理的 Pi SDK 运行时资源位于 ${HANA_HOME}/runtime/pi-sdk/ ；Hana 不依赖 Pi 的全局 agent 目录或 PI_CODING_AGENT_DIR 。旧版本遗留在 ${HANA_HOME}/.pi/agent/bin/ 的 fd / rg 只会在首次使用相应搜索工具时复制到新目录，旧文件会原样保留。
适用场景与限制
适用于日常办公、个人电脑助手、多 Agent 协作、远程对话与移动端使用等场景。限制方面：记忆系统目前有待优化；Windows 命令沙盒目前为写隔离模型，读取按当前用户权限自然发生，网络按当前用户网络权限运行；Windows 安装包暂未经过代码签名；Anthropic 的 OAuth 登录因封号风险暂时不提供；Hana 不会自动开启公网 tunnel，公网入口必须由用户显式提供。
其他信息
- 许可：Apache License 2.0
- 仓库与 Release：仓库和 release 地址在当前迁移阶段仍保留旧的 openhanako URL，后续仓库 rename 会单独执行。
- Issue 规则：Issue 只描述问题或需求，不接受代码实现（修复建议、补丁、diff、实现方案或示例），不符合的会直接关闭。Bug 请让 Agent 在环境中复现并排查，按 Bug Report 模板提交可验收的问题报告：列出实际出现的问题、复现步骤和验收方式，不写怎么改。Feature 建议先和 Agent 聊一聊，再按 Feature Request 模板提交 Spec：想要什么、为什么需要、做到什么程度算完成，不写实现。
- 致谢：tw93/kami 的 beautify 插件 HTML 美学规范的“路由器 + 平级章节按需获取”渐进披露结构受其启发。
