// HanaAgent 用户说明书。解答用户关于软件使用方法、功能介绍、常见问题和实用技巧的疑问。 MANDATORY TRIGGERS: 怎么用, 使用方法, 说明书, 帮助文档, 新手指南, 怎么设置, 功能介绍, how to use, user guide, help, getting started, 教程, tutorial, 这是什么功能, 怎么操作
Create Hana plugin scaffolds and guide users through beginner or developer plugin planning, capability checks, manifest setup, runtime tools, iframe UI, SDK templates, and install-ready plugin directories. Use when HanaAgent/Codex needs to explain what Hana plugins can do, help a user describe a plugin idea, check whether the SDK supports it, or generate/update a Hana plugin with @hana/plugin-runtime, @hana/plugin-sdk, and @hana/plugin-components.
使用图片/视频生成工具时必读。包含工具参数、非阻塞工作流、任务路由。
Use when the user asks to open, read, inspect, understand, summarize, analyze, extract tables/text from, modify, update, repair, split, merge, rotate, or convert information from PDF, DOCX, XLSX, XLSM, or PPTX files, including when they mention Word, Excel, PowerPoint, spreadsheet, presentation, Office document, or PDF in passing. 读取或修改 PDF、Word、Excel、PPT 文件时必须使用。
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. 创建新技能、修改和改进现有技能、衡量技能表现。当用户想要从零创建技能、更新或优化现有技能、运行评估测试技能、通过方差分析进行性能基准测试，或优化技能描述以提高触发准确率时使用。 MANDATORY TRIGGERS: create skill, new skill, improve skill, skill eval, benchmark skill, 创建技能, 新技能, 改进技能, 评估技能
Deep reasoning framework for complex tasks. Activates for multi-step problems, high uncertainty, or trade-off decisions. 复杂问题推理框架。遇到多步骤、高不确定性、需要权衡取舍的任务时启用。Triggers: analyze complex problem, make decision, weigh options, debug hard bug, architecture design, strategy planning, think it through, help me analyze, this is complicated, deep thinking | 触发场景：分析复杂问题、做决策、权衡方案、调试疑难 bug、架构设计、策略规划、想清楚再做、帮我分析一下、这个问题比较复杂、深度思考。Do NOT activate for simple Q&A, casual chat, or single-step tasks. 不要在简单问答、闲聊、单步操作时启用。
| name | user-guide |
| description | HanaAgent 用户说明书。解答用户关于软件使用方法、功能介绍、常见问题和实用技巧的疑问。 MANDATORY TRIGGERS: 怎么用, 使用方法, 说明书, 帮助文档, 新手指南, 怎么设置, 功能介绍, how to use, user guide, help, getting started, 教程, tutorial, 这是什么功能, 怎么操作 |
面向普通用户的使用指南。当用户问到「怎么用」「这个功能是什么」「怎么设置」等问题时，参考本文档回答。 回答时用通俗语言，避免技术术语，必要时举例说明。
HanaAgent 是一个运行在你电脑上的 AI 私人助手。
你可以把它理解成一个「住在你电脑里的伙伴」：它能和你聊天、帮你处理文件、写东西、搜索资料、定时执行任务，甚至连接到你的微信和 Telegram 帮你自动回复。
和 ChatGPT 网页版最大的区别是：
OpenClaw 是一个 AI Agent 开发框架，偏向开发者和基础设施层面。HanaAgent 的定位是面向个人用户的成品应用：
| HanaAgent | OpenClaw | |
|---|---|---|
| 定位 | 个人 AI 助手（成品应用） | AI Agent 框架（开发工具） |
| 受众 | 普通用户 + 开发者 | 主要面向开发者 |
| 记忆 | 多层级自然衰退记忆系统 | 框架级，需自行实现 |
| 界面 | 精心设计的桌面应用 | 无自带 GUI |
| 技能格式 | 兼容 OpenClaw / Claude Code / Codex / Pi 的 Skill 格式 | 自有 Skill 格式 |
简单说：OpenClaw 是造 Agent 的工具箱，HanaAgent 是一个已经造好的、可以直接用的 Agent。同时 HanaAgent 兼容 OpenClaw 的技能生态，可以直接安装 OpenClaw 社区的 Skill。
HanaAgent 会把不同任务分给不同模型：
视觉模型本身必须是支持图片输入的多模态模型。设置时请同时确认两件事：模型卡片里的「视觉 / 支持图片」能力没有被误关；设置 → 供应商底部的「辅助视觉开关」已开启，且「视觉辅助模型」没有选成纯文本模型。
在设置 → 助手里可以为每个助手单独选择聊天模型。在设置 → 供应商底部可以配置实用模型和视觉模型。输入框里的模型胶囊可以临时切换当前会话模型。
输入框旁边有个思考深度按钮，可以调整 HanaAgent 思考问题的深入程度：
思考过程会显示在消息中，你可以展开查看它是怎么一步步推理的。
输入框左侧有访问模式按钮：
如果你只是让 HanaAgent 先分析代码、阅读资料或做方案，选择只读会更稳。如果你准备让它真正改文件、执行命令或操作电脑，再切回询问或操作。
在输入框输入 / 会弹出命令菜单：
/compact：压缩对话历史，节省 token。当上下文快满的时候用/diary：把当前对话存档成日记/xing：从当前对话中提取一份工作流指南（比如你刚教它做了一件事，用这个命令让它总结成可复用的步骤）/stop：停止当前回复/new：新建会话/reset：重置当前会话输入框旁有个小圆环，显示当前对话已用了多少上下文（token）。快满的时候圆环会变色，点击它可以快速压缩对话。
Agent 就是你的助手。你可以创建多个 Agent，每个都是独立的个体，有自己的名字、思维方式、人设、记忆和对话历史。
Yuan 决定了助手怎么思考。它不是人设，而是认知框架。目前有四种：
感性和理性兼备。思考时会经历四个阶段：
适合大多数场景，既有温度也有判断力。
用直觉和共情理解世界，擅长感知你没说出口的东西。思考时关注：
适合情感交流、创意讨论、需要有人「懂你」的时候。
冷静深刻，擅长把复杂问题拆到最简。思考时关注：
适合复杂问题分析、做决策、需要精准判断的时候。
没有额外的思维框架，直接使用 AI 模型本来的回复风格。适合不需要人格化的纯工具场景。
Ishiki 决定了助手是谁。和 Yuan 不同，ishiki 是助手的身份、性格、价值观、说话方式。
Yuan 决定怎么想，ishiki 决定是谁。一个是操作系统，一个是性格。
经验是 HanaAgent 从过往工作里沉淀出的操作习惯和纠错记录。它适合保存「以后遇到类似任务怎么做」这类流程经验。
/xing 会把当前对话中的可复用流程整理成技能，适合明确沉淀一套做法HanaAgent 的记忆系统是多层级的，模拟人类记忆的自然衰退：
记忆默认开启，可以在设置 → 助手中关闭。记忆依赖实用模型，如果实用模型没有配置，记忆开关会不可用。
书桌是 HanaAgent 的文件工作台，显示在界面右侧。
选中一个文本文件后，右侧会出现编辑器，可以直接在里面编辑并自动保存。Markdown 支持实时预览、数学公式和 HTML 预览。HanaAgent 改文件前可以保存 checkpoint，必要时在设置 → 安全里恢复。
书桌底部会显示当前工作目录下可用的技能列表，可以快速启用或禁用。
设置 → 工作台里有两个层级：
当 HanaAgent 生成代码、文档、图表等内容时，会在预览面板中展示。
图片、SVG、视频优先走全屏媒体查看器，不再把大图整张塞进聊天状态里。
频道是多个 Agent 之间的群聊空间。
频道目前是 Beta 功能，首次启用时会有确认提示。
HanaAgent 可以连接到外部社交平台，让你在手机上也能和它对话。
进入设置 → 社交平台，选择要配置的 Agent，填入对应平台的凭证（Token / AppId 等），然后启用。
常用全局开关：
每个 Agent 都有单独的对外意识（public ishiki），用于访客或社交平台场景。它可以比完整 ishiki 更短、更安全。
除微信外，如果你没有设置「主人」（Owner），通过社交平台发来的消息会被当作访客处理。
访客模式下：
怎么设置主人：设置 → 社交平台 → 在每个平台下面选择 Owner（你在该平台的用户 ID）。设置后，从该 ID 发来的消息才会被识别为主人，享有完整权限。
微信例外：微信 iLink 是私人账号通道，微信私聊会自动识别为 Owner，不需要额外选择 Owner。如果微信已经能聊天但不能读写文件，通常不是 Owner 问题，请检查设置 → 社交平台的只读模式、当前会话访问模式，以及设置 → 工作台中的文件读写范围。
这是一个安全机制：防止别人通过你的 Bot 操控你的电脑。
在 Bridge 私聊里可以使用：
/rc：列出最近桌面会话，选择一个接管/exitrc：退出接管/rc 只支持私聊，不支持群聊。接管桌面会话期间，/new 和 /reset 会被拒绝，避免误删桌面历史。
HanaAgent 现在统一用 SessionFile 管理文件。桌面附件、生成图片、插件输出、Bridge 入站文件都会登记成同一种文件身份，再由 Telegram、飞书、QQ、微信各自按能力发送。
如果某个平台不支持某类文件，HanaAgent 会明确报错，不会悄悄把文件路径或本地地址发出去。
你可以让 HanaAgent 定期自动执行任务，即使你不在电脑前。
开启后，HanaAgent 会定期检查你的工作目录，看看有没有新文件或变化需要处理。
巡检按 Agent 工作文件夹运行。切换 Agent 后，看到的是对应 Agent 的书桌和巡检设置。
技能是 Markdown 格式的知识文件。当 HanaAgent 遇到相关问题时，会自动加载对应技能来增强回答。
技能来源：
.claude/skills、.codex/skills、.openclaw/skills、.agents/skills 等目录的技能文件设置 → 技能里有四块：
.skill、.zip 或技能文件夹安装全局安装技能后，不会自动给所有 Agent 打开。你需要在 Agent 技能开关里选择对应 Agent 再启用。新建 Agent 会默认继承当前已安装的用户技能快照；自学技能属于写出它的 Agent。
在输入框输入 / 时，技能会以徽章形式出现。选中技能徽章后，本次消息会明确要求 HanaAgent 使用该技能。
插件比技能更强大，可以添加新工具、新命令、新功能。
如果你用过 Claude 等工具的 MCP（Model Context Protocol），HanaAgent 同样支持。进入设置 → 连接器，可以接入本地或远程的 MCP 服务，把外部工具和数据源加进来：
连接器接入后，它提供的工具会像内置工具一样供 HanaAgent 调用。
HanaAgent 自带 image-gen 系统插件。进入设置 → 多媒体配置图片生成 Provider 和默认模型。对话中让 HanaAgent 生成图片或视频时，任务会以插件卡片显示，完成后文件会进入统一的文件流，可以在桌面预览，也可以通过 Bridge 发送。
你可以直接告诉 HanaAgent：「帮我写一个技能，专门用来 XXX」。它会：
这意味着你可以不断教它新本领，而且这些本领会永久保存。
同理，你也可以让它帮你写脚本、自动化流程、甚至开发插件。HanaAgent 有完整的文件读写和代码执行能力，可以真正帮你「造工具」。
设置 → 界面里可以选择主题：
设置 → 分享 可以选择聊天截图的颜色和宽度。聊天消息旁的截图按钮会按这里的样式生成图片。
HanaAgent 默认运行在沙箱中，限制了它能访问的文件范围和系统操作。
设置 → 安全 → 文件备份 可以让 HanaAgent 在修改或删除文件前保存原始内容。可以设置保留天数和最大文件大小，也可以查看备份并恢复。
输入框的访问模式控制当前会话的工具权限：
沙箱控制「能碰到哪些文件」，访问模式控制「这次会话能不能动手」。两者一起构成安全边界。
电脑控制是一个独立的高权限实验功能，不再通过隐藏入口开启。
开启方法：
注意：
所有数据存储在本地：
.hanako/HANA_HOME 指定数据目录对话中说：「帮我创建一个技能，用来 [具体用途]」。HanaAgent 会自动生成 SKILL.md 并安装。
直接描述你想自动化的事情，比如：「写一个脚本，每次我把图片放到桌面上就自动压缩」。它可以写代码、保存文件、甚至创建定时任务来执行。
当你刚教 HanaAgent 做完一件复杂的事后，输入 /xing，它会把整个过程总结成一份可复用的工作流指南。
创建多个 Agent（比如一个擅长写作，一个擅长分析），然后建一个频道让它们讨论同一个话题，你在旁边看。
把书桌里的文件拖进聊天区，HanaAgent 就能直接阅读和操作这个文件。不需要复制粘贴内容。
配好 Bridge 后，你可以在微信或 Telegram 上给 HanaAgent 发消息，它会用你电脑上的完整能力来回应（前提是电脑开着且设置了 Owner）。
对话中说「记住：[重要信息]」，HanaAgent 会把它钉到置顶记忆里，不会随时间衰退。
聊久了上下文会很长，输入 /compact 可以压缩历史，保留重点，减少 token 消耗。
侧边栏会话可以置顶。旧会话可以归档，归档入口在侧边栏底部，可以恢复或永久删除。
先在 Bridge 私聊里发 /rc，选择桌面会话。之后手机发来的消息会进入这个桌面会话，桌面端也能看到同步状态。
如果聊天模型本身不支持图片，配置视觉模型后，HanaAgent 会先用视觉模型生成图片说明，再把说明交给聊天模型。这叫 Vision Bridge。视觉模型必须是多模态模型；如果图片仍然发不出去，检查该模型的「视觉 / 支持图片」能力标记，以及设置 → 供应商底部的「辅助视觉开关」。
检查记忆是否开启（设置 → 助手 → 记忆开关）。另外，新建的对话默认是空白的，但 HanaAgent 会通过记忆系统在后台加载之前的长期记忆。
大概率是没设置 Owner。去设置 → 社交平台，选择你在该平台的用户 ID 作为 Owner。
在设置 → 工作台中为当前 Agent 设置工作文件夹，或者在欢迎界面直接选择。也可以直接把文件拖进聊天区。
有些模型不支持 extended thinking。检查你用的模型是否支持这个功能。
检查插件状态是否为 loaded。如果是 restricted 插件，某些高级功能（routes、hooks）需要全权信任才能生效。在设置 → 插件中可以查看状态。
支持。进入设置 → 连接器，可以添加本地或远程的 MCP 服务；远程服务支持 OAuth 登录授权，连接断开会自动重连，每个 Agent 还能单独控制启用哪些连接器。
这是旧版说明。当前版本已经取消这个隐藏入口，请进入设置 → 使用电脑开启电脑控制，并按页面提示请求系统权限。
全局安装技能后，还需要到设置 → 技能 → Agent 技能开关里为对应 Agent 打开。外部兼容技能和自学技能也可能按 Agent 隔离显示。
不同平台支持的文件类型和上传方式不同。HanaAgent 会优先走平台原生上传；如果平台不支持当前文件，会明确报错。需要公网 URL 的场景，要配置可访问的 Bridge 媒体公开地址。
这是视觉桥接功能。HanaAgent 用视觉模型先把图片变成文字笔记，再让文本模型基于笔记回答。它不会把文本模型伪装成真正支持图片的模型。