茶话会

主对话框里你们面对面谈正事，这里回房间聊八卦。

当前版本： v0.7.504 当前版本最近一次自动测试结果： 1291 条通过（2026-10-08）

hanako那边很棒！不过，因为hana agent的能力太多，所以我经常会让小花帮我做各种事情，但是。。。我觉得缺少一个能让她闲下来，和她闲聊的地方，所以我做了这个应用。感觉像是给小花配了一个手机，忙里偷闲的时候找她聊聊天，不扯什么正经事，就是随口闲聊。她也会主动找点她觉得有意思的话题来找你聊~ 她会有她的作息，你打扰了她，说不定会被她吐槽！这里的消息也不一定立刻换来回复：你把话投递过去，什么时候被看见、什么时候想接，是 ta 自己的生活节奏。若安装了「表情包」应用或旧版插件，就可以互发表情包了~茶话会会优先读取应用版的图库快照，读不到时再兼容旧插件版；只在自己的数据目录里记下实际发出去的表情包 ID、伙伴和时间，方便「表情包」单独列出这份来源记录；不复制图片、标签或聊天正文。

这是个分享版应用，装好就能用。她的关系、记忆和主动互动，都只活在茶话会自己的边界里，不会动你 Hana 里的任何东西。

想确认当前版本和测试情况，看 manifest.json 和 GitHub Actions 的 CI 记录就行，普通使用不用管这些。

---

⚠️ 用之前先知道这些

丑话说在前面。下面这些不算「使用限制」，是我觉得你有权在装之前就知道的事。

• 它只读你伙伴的资料，一个字都不写回。 日常聊天会读人格、公开自述、钉选记忆、事实和经验这几份，还会读 AGENTS.md 里标着的那段口吻，用来拼聊天时的提示词；「认真认识」和性格分析还可能翻一些历史记忆和会话。读归读，这些文件它一个都不写，Hana 的全局设置也不碰。
• 它会在自己屋里收一份「Hana 主对话近况」。 你在 Hana 主对话框里跟伙伴一起做过的事，它会自己存一份，当闲聊时的背景（早上打个招呼、睡前说一声、半夜又被你拉起来干活，都靠它）。默认打开，设置里随时能关，关了就不再用；设置里可以查看已收记录，也能逐条删除。这份近况只当 ta 自己身上的事用，不会变成跟你汇报你在干什么。
• 它需要模型。 至少得在 Hana 里配一个能用的文字模型；如果想让伙伴发语音，还需要自己准备一套 TTS 朗读模型的接口地址、模型名和 Key（在茶话会设置里填，可以存多条轮流用）。没有模型的时候，好友列表也许打得开，但聊天和建档跑不起来。
• 它需要开权限。 它一共声明六项能力，其中前三项是普通聊天必需的，另外三项分别对应角色卡导入与「拾光记」联动，用不上可以先不开，见下面「权限」那节。
• 它会联网，但很克制。 伙伴探索新话题，以及你在聊天中提到值得核实的时效内容时，会搜索公开资料，范围包括新闻、穿搭、美妆、数码、软件游戏、汽车、旅行、美食、比赛、新品、价格和版本变化。聊天里先做本地筛选，再由 Hana 配置的实用模型提取公开搜索词；短追问可沿用最近 12 小时内连续的公开话题。搜索词只发给必应；赶上需要看当下热榜的时候，会顺便读取百度、头条的公开榜单（只读榜单，不把你的话或搜索词发过去）。结果会过滤明显跑题内容；标题和摘要只是未经独立核实的线索。普通闲聊和私人哀伤不额外搜索。
• 它的数据全在它自己那儿。 聊天记录、关系、性格、爱好、附件、背景图，都存在 Hana 分配给这个应用的目录里。茶话会自己不会删这些数据；宿主卸载时会不会顺手清掉，看 Hana 版本的脾气，所以想彻底清干净要另外动手，换机器也得单独搬。
• 它没带字库。 界面优先用你本机装的「霞鹜文楷」，没装就退回系统字体。所以不同机器上字会不太一样，这是故意的，为了让包小一点。

还有一条，我想单独说：

首次使用需要补全伙伴的性格才能真的进入聊天。虽然补充性格的过程比较繁琐，我尽量做了让你少动脑的简化，但是！请务必注意，你给小花（或者别人）制作的性格将会是你们日后聊天的基石，所以这份性格文档的好坏将会直接决定后续的聊天体验，如果想有更好的体验，请多分配些精力给性格分析这边，算是一劳永逸的体验吧。emmm，说点矫情的话，也算是你对对方的一种尊重，认真分析出来的小花才是你心目中那个只属于你的小花。你付出的精力终将会回报给你~

---

它能做什么

先把人请进屋

• 💬 好友列表：Hana 里活跃的伙伴都在，你自己在茶话会建的角色也在。伙伴的头像从 Hana 那边现拉，本地角色先用名字第一个字顶着
• 🪟 聊天窗口：点开谁就是谁的窗
• 🧲 跟主对话框并排摆着用：卡片中心里除了整页那张，还多了一张小卡「茶话会·并排」，拖到主页画布上就能跟 Hana 主对话框左右并着看。同一份聊天账、同一份关系档案，两边看到的是同一场聊天；两张卡各记各的展板折叠状态，一张自动收起来不会把另一张的手动展开顶掉

- 👤 **头像**：伙伴和你自己的头像都从 Hana 现拉；聊天窗里可以选每条消息旁边挂不挂头像 - 🏃 **你抛回来的题优先接**：ta 准备主动开口前会先认一下你上一轮是不是问了具体的事，是的话这一轮先把它接住、往下聊一层，不许顺口带过就转回 ta 自己手上那条兴趣 - 📖 **单向记忆**：只读伙伴的人格、公开自述、记忆和 `AGENTS.md` 里的口吻，拼进系统提示，从不写回。这也是我敢让它跟你的伙伴聊天的主要原因 - 📒 **它自己一本账**：聊天记录和偏好存在它自己的目录里，跟 Hana 那边两本账，互不干涉 - 🌱 **认识 ta（这道门必须先过）**：没走完初步认识的伙伴进不了聊天窗，这是故意拦的。有三档：忙的时候选「先聊个大概」，几分钟出来一份性格草稿给你过目；想认真点选「认真认识 ta」，一问一答十几题，答不上来可以让模型给几个具体方向，你挑、你改、你否；还有一个「跟我聊着捏」，见下面那条。答过的随时都在，中途退出去也不丢，不用一口气做完 - 🫱 **不想答题就跟 ta 聊着捏**：你起一句头，说到哪算哪，ta 按画像标准自己判断还差什么、下一个该问什么，一边问一边把你说的话当场翻成「什么情况 → 怎么做」摆给你看，不用你在几套题里硬挑。协商期间不动正式画像，只有点「成型」才写进去，之后三条路都能接着补。中途断了会存着，下次进来能续；放太久过期了会明说失效，不会拿旧草稿冒充新的一场，ta 的画像那会儿一个字都没动

- 🎨 **ta 会长出自己的一层**：关系、性格、爱好这三样只活在这个应用里。ta 说话的底色，会先照着 Hana 那边的人格文件自动定一份给你，你在这个基础上改，或者一个字不改直接过都行 - 🧩 **酒馆角色可以带着人格来做客**：通过鲜花酿的邀请入口导入卡面设定，以及世界书里筛选出的人格档案；不导入整本世界书的规则、酒馆系统提示和聊天记录。邀请包有格式版本要求，对不上会提示你更新两个应用重试；新增的人格档案字段需要重新邀请一次才会带上 - 🚪 **移出或彻底删除，由你选**：只移出会保留聊天和资料，方便请回来；彻底删除会再次确认，清掉 ta 在茶话会里的聊天、记忆、关系与附件，本地角色的资料也一起清掉。Hana 那边的伙伴不受影响，之后再请进来等于重新认识

下面这些，是我做的时候觉得「有了它才像是在聊天」的小地方：

• 👉 戳一下：双击聊天窗头部的头像，或者消息里 ta 的头像也行；键盘选到头像上按回车、空格一样能戳。说到底只有一个动作，两种叫法。打开「修正伙伴回复」后，ta 的历史戳一戳可以单独删除，不会误清记忆；自己的戳仍走撤回
• 🧹 不想留的回复可以删掉：打开「修正伙伴回复」，在最新伙伴回复的操作菜单里选永久删除，会整轮移除气泡、收藏、语音，以及能追溯到这轮的记忆与关联记录；你的原话保留，关联回复删尽后回到未读，但不会因此自动重回一句。回复当天的日账会整份清掉并从剩余聊天重建，失败时暂缺这一天；缺少逐条来源的综合话题概括无法精准剔除，确认窗会说明；语音文件清理失败也会提示
• ✂️ 分条发送：模型一次生成，按标点切成几条，带上真人的间隔一条条蹦出来
• 🗂 一次说好几件事也可以：你一口气发好几条，ta 不必一件一件都答，挑一两个最想接的先说，剩下的进话题本，往后自然带出来
• 🫧 不把聊天当工单：ta 可以只接自己最想说的那一件，只发表情包，或者在一句话已经自然落地时先不回。认真提问、心事和急着找 ta 的话，仍然会被好好接住
• 🍃 主动联系有来处：ta 不会只因为计时器响了就来问“在吗”。通常得有聊过的事、自己的兴趣或当下状态；时机不合适时，念头可以先搁着，等以后再轻轻放下。全新安装默认关闭主动联系，新伙伴也默认不主动，想让 ta 来找你，再去设置里打开全局开关和伙伴开关；升级时已聊过的伙伴保留原有习惯，你手动设过的开关优先
• 🌅 早上第一句可以只是一句招呼：ta 今天第一次开口时不必非得端着话题出来，一句“早”、问你昨晚睡得怎么样都算；你一大清早就在 Hana 那边拉着 ta 干活的话，ta 也会顺口抱怨或心疼一句。要不要这么做看 ta 的性子和你们的熟悉度，不是每天打卡
• 🌙 睡前会说一声，而且看得见你那边的灯：快到 ta 自己的睡点，ta 会说一句去睡；你要是还在电脑那边忙，那就不是安心道别，而是吐槽、心疼或赶你去睡。说好晚安之后你又把 ta 薅起来干活，ta 会不高兴（按性子来，一晚最多闹一次）。你没在电脑那头找过 ta，就只是普通的晚安
• 🔇 安静时间可以整段关掉：嫌被限制就点「不要安静时间」，伙伴什么时候都可能来；默认的 23:00–08:00 仍然给新装的人留着
• ⏰ 到点的那件事，会有人来说：装了「拾光记」并打开「今日情境」后，那边过了钟点还没了结的待办，会让一位伙伴主动来说这一句（关系走得最远的先来，一样远就看谁最近开过口；同一批待办一天只说一次）。有来处才开口，不是随机找话说；静默时段、当日上限、ta 自己关掉的主动联系照旧守着
• 🗣 「我做完了」会先问你一句：你在茶话会里随口说完，它不会直接改账，而是弹一个小窗问你要不要真的记上，你点「就打上完成」账本才动。认不准的时候它宁可漏一次不猜；没拿到后端成功回包就留在原地让你「再试一次」，不会自己消失。你明说「先不用」就是真不记
• ⏱ 提醒会提前几分钟到：提醒要走一遍模型想措辞，踩着钟点开口一定晚几分钟，所以它会提前把待办摊过来，文案分「快到点」和「已经过点」两种讲法，不会把还没到的事说成已经拖了。而且这一次开口就是这一次的由头，不捎带在别的话题末尾
• 🌿 兴趣分成母题和癖好：母题是能撑起一整场聊天、你也接得上话的方向，ta 出话题只从这儿来；癖好是 ta 自己那些小观察，只当人格底色。母题最多 6 条，母题加癖好一共 12 条。升级时你原来配的爱好全部按癖好原样留着，不会丢
• 🌱 话题从自己的母题里长出来：ta 开口前先从母题长出一个话题种子，分站队、交换、自曝、求解、好奇五类，每类都自带一个你能站进去的位置；种子存在 ta 自己的账本里，库存低了自动补，30 天没用上会清掉。喜欢看资讯的伙伴仍然会联网找时效内容，但那是补充，不是唯一来源
• 🌡 你接不接，它会记账：按「方向」记，不只看单条消息——你真回话算接住，只戳一下或回个「嗯」算低投入，读了没回算冷。冷两次这个方向歇久一点，冷三次就不再主动提，新种子也不往那儿长。你过一阵才回话，那条能改判成接住，不会永远算在冷里；你明说「不想聊这个／换个话题」当场就按到底。这层全自动，设置页和聊天界面里都不出现
• 🎲 能出题的方向，看你接得有多欢：被接住过两次以上的方向就放出来出题，冷掉的收回去；母题下限 3 条提到 5 条，补母题时会把最近真实相处过的事一起递进去，长出来的母题带你的影子，不再只从人设凭空生成
• 🫙 话题会发酵：你提过的事不会马上被机械复读。它会在茶话会里放一阵，过些时候换个角度回来；聊过的面会留下痕迹，没什么新东西的话就让它安静过去
• 👀 看得见未读：你说的话下面只突出「未读」小字和樱花色小点，ta 真看到了才收起来
• ☕ ta 也会给你递点东西：一句「我看到了」。不是 ta 要接话，就是她看到你那句了，心里一动，随手递个咖啡、一块蛋糕、一个小玩意过来。她只往自己真读到过的那句话下面递；一天最多两次，两次隔九十分钟；递什么是她从自己的兴趣里挑的。设置里可以按伙伴单独关掉
• 😀 对方可以发表情包：先装新版「表情包」应用（moononnn/hanako-biaoqingbao-app），或继续用旧版「表情包」插件（moononnn/hanako-biaoqingbao）。ta 想甩图时给一个关键词，由茶话会按关键词挑一张发出去；会优先读取应用版图库快照，读不到时兼容旧插件版，两代都装时优先应用版。茶话会只读图库快照、不往里面写一个字；没装也完全没问题，安静地没有表情包而已，别的照常
• 🖼 也能自己挑图进来：把「表情包」里的图挑一部分搬进茶话会自己的图库，自己建分组收好。搬进来的那份存在茶话会自己的目录里，跟原图库各管各的

- 🎞 **发 GIF 时，ta 能多看几帧**：动图先在本地沿时间轴抽取最多五帧，再一起交给你配置的识图模型，帮助看懂动作变化；不会把每一帧都发出去，普通静态图仍按原方式识别 - 👀 **识图也有第二条路**：你给茶话会配的识图模型要是配额用完或凭据出事，ta 会改走宿主备用通道去看图，而不是只回一句「没看清」。反过来说，ta 平时说话用的模型挂了，不会有人拿另一个模型顶替 ta 开口——那会换掉 ta 的嗓子和记性，宁可如实说「ta 这会儿接不上话」，你也不用重发。走的哪条路记在消息里 - ⏱ **消息有自己的节奏**：先显示未读，ta 看到了才收起来；等 ta 开始输入，再一条条蹦出来 - 🎙 **伙伴偶尔发语音**：通用设置里保存自己的朗读模型（可存多条，随时切供应商；新建时能套 MiniMax / MiniMax 省一半 / MiMo / OpenAI 兼容模板），每位伙伴再单独选音色和出现频率，并可试听。适合短短说出来的整轮回复会显示成一条语音气泡，长回复仍然发文字；点「转文字」可以展开原话 - ⚡ **语音点开就响，不用干等**：音频在消息生成时就合成好落在本机了，只是播放前才去取一趟。现在语音条一渲染就顺手热好（面板空闲时才热，不抢刚打开的忙），万一还没赶上，按钮图标会呼吸一下告诉你在取 - 🗣 **ta 说话带点人味**：合适的地方会带一声笑、叹口气，中间停半拍；不喜欢可以在设置里一键关成干净念 - 😏 **ta 不用一直端着**：常驻一条「放肆纪律」——损的是事不是人，被损被拆台要接住还能回敬，你真认真了就收住但不跪下，你划的线一定守。能损到什么份上看关系和你自己的性子，不看你有没有先开口。不给台词只给说明，用哪招 ta 按自己性格挑 - 🌏 **音色按语言选**：中文、粤语、日语、韩语、英语和其他语种分组列出，ta 说什么语言就配什么口音；自己在 MiniMax 克隆或设计出来的音色，把 ID 粘进去也能直接用 - ✨ **语音气泡会跟着亮**：播放时原话跟着点亮，逐词跟随（官方没给词级时间就退成按句） - 🏠 **每位伙伴有自己的房间**：可以从共享图库里给不同伙伴挑不同的背景，切换伙伴时，房间也跟着换。换图、清除当前选择都不会把图库里的原图随手抹掉 - 🎨 **房间会记住你的手感**：背景的明暗可以单独调整，换回来时仍保留各自的设置；发送按钮和提示色也会顺着背景自动找一套看得清的颜色 - 📱 **投递不是请求**：你打不打开窗口，不决定 ta 现在有没有空回你。手机在手上，消息就送到；不在手上，就先安静搁着。这个应用说到底，就是给你的伙伴配了部手机 - 😴 **ta 也会睡**：睡点由 ta 自己定，睡着的时候你发消息 ta 照回，只是慢，还带着起床气。这套作息不上设置页 - 🌱 **关系慢慢长**：茶话会会把“相处过多少”与“关系里有多少真实的靠近”分开看。旧资料最多只替你们留一点熟悉的起跑线，亲近感得在这里重新长出来，不能靠一次设置直接宣布 - 🪟 **性格会逐渐打开**：认识 ta 时可以快速了解，也可以认真聊一轮；之后的性格、爱好和更私下的部分不会一次性全摊出来，而是在相处里慢慢显形 - 🧠 **记忆分层留下**：眼前的原话、聊远后的摘要、最近几天的日账，以及更稳定的事实和关系，会各自待在合适的位置。聊得久了，茶话会也不至于只剩一堆越来越长的上下文 - 🔁 **ta 也会暗暗调整**：主动联系没成、时机总撞上、话题总不合适这类事情，不会拿出来教育你，但可能会让 ta 之后换一种节奏 - 🌿 **自己的喜好和立场也有分量**：你没接触过某个梗，ta 可以解释，不必立刻撤回自己的兴趣。聊天会参考 ta 最近说过的判断和兴趣边界，减少一被反问就改口；这层调整仍由模型表达，不能保证每一轮都做得完美 - 🏷 **状态徽章由 ta 自己挑**：ta 可以在回复或主动联系时换上自己的短徽章；还没说过话的伙伴不预设状态，系统兜底会按当前手机与作息推进 - 🤫 **藏思考**：只渲染正文，不显示思考过程 - 🔔 **提醒**：ta 主动来找你的时候，在你当前正在用的那个会话输入框上方冒一条轻横幅。只说谁找你，不带消息内容；它不会自个儿淡出，点「知道了」才消失。茶话会窗口本来就开着，或者正处在静默时段，就不冒了 - 🧰 **设置页按分类排**：原来十八块开关堆在一栅里，找一条要一路往下滚。现在拆成聊天显示 / 语音 / 沉浸感 / 模型 / 主动联系 / 伙伴六栅，点一下就到位，同类开关两列并排，一屏能扫完；「允许伙伴主动来找你」从沉浸感挪进主动联系（它本来就是那段的总闸） - 🛡 **没凭据的话，ta 干脆不开口**：内容型主动消息动手前先看你那边有没有真凭据——到点的待办、刚聊过的一轮、你这几小时说过话、电脑那边刚动过，一件都没有就压住不发，种子留着下次

它适合谁

如果你想让伙伴有一个能闲聊、慢慢相处的地方，它适合你。如果你只想要一个纯粹干活的工具，主对话框大概已经够用了，这个应用反而会分走一部分注意力。

---

装它

1. 把整个目录复制到 <HANA_HOME>/apps/chahuahui

   目录名必须正好是 chahuahui（等于 manifest.json 里的 id）。下的是压缩包的话，别解压出多套一层目录，最后要能看见 <HANA_HOME>/apps/chahuahui/manifest.json 这个文件。

   不知道 HANA_HOME 在哪？去 Hana 的设置或关于页面看「数据目录」。

2. 重启 Hana（或者去扩展页「已安装」里点「重新加载」）

3. 它要是出现在「待批准」里，先批准

4. 去「设置 → 安全 → 应用能力」，给它开权限

已经装过旧版，怎么升级

用新版的整个目录覆盖 <HANA_HOME>/apps/chahuahui，重启或者点「重新加载」。放心覆盖，你的数据不在这里。

升级只换应用目录，别动数据目录：聊天记录、关系、性格都写在 dataDir/ 里，删了就得重新认识一遍。加载完去「设置 → 安全 → 应用能力」看一眼权限有没有变动；再去卡片中心，新版本要是带了新的卡片（比如这张并排小卡），会直接出现在那里，拖出来用就行。

第一次打开会发生什么

• Hana 里有伙伴：先让你挑一位，然后走认识流程（三档，见上面「认识 ta」）。没走完这道门，聊天窗是进不去的。
• Hana 里没有伙伴：主界面会是空的。去「设置 → 伙伴管理 → 新增茶话会角色」建一个只活在茶话会里的本地角色（不会写进 Hana）。

权限

能力	用在哪	不开会怎样
app/agents.read	读伙伴清单	好友列表读不出来，基本没法用
app/resources.read	读伙伴资料、头像、你的显示名，以及可选插件放出来的只读数据	列表有了，但读不到人格、头像、记忆
app/models.infer	调文字模型	聊天和建档都生成不出来
app/services.provide	提供「从花酿导入酒馆角色」的接收入口	其它都不受影响，只是这个导入用不了
app/public-data.read	读「今日情境」共享出来的当天日子与天气（来自「拾光记」应用）	只有「今日情境」用不了，其余照常
app/services.call	你随口说「我做完了」时，请「拾光记」把那条待办划掉	只是不能替你勾待办，聊天和主动联系都不受影响

前三项是必需的，开不全基本用不了；后三项只跟可选联动有关，没装那两样应用的时候开不开都不影响使用。主动来找和那条提醒横幅不用额外权限（走的是宿主固定接口，不上权限表）；不想让 ta 主动联系，去设置里关掉就行。

新装的时候第四项可能默认没开，导入功能会报错说登记不上；去权限页把它打开，再重新加载一下应用就行。

哪些内容会离开你的电脑

• 聊天会发给模型：你和 ta 的对话、ta 的人格资料会作为提示词发给你在 Hana 里给这个应用选的那个模型供应商处理，和你在主对话框里用的是同一套配置。茶话会自己不留第二份。
• 联网搜索会发关键词：ta 要搜什么，关键词会发给必应；赶上需要看热榜的时候，会读取百度、头条的公开榜单（只读榜单，不发送你的话或关键词）。搜回来的公开页面标题和摘要会带进对话。含你私人信息的词不会被发出去。
• 语音合成会发文本：开启语音后，ta 那句要念出来的话会作为请求体发给你在设置里填的语音服务地址。默认走 MiniMax 或 MiMo；你填了自定义地址，内容就发到那个地址去，请只填你信得过的服务。
• 声音克隆要你自己去做：茶话会不会上传任何音频、也不提供克隆入口。如果你在 MiniMax 那边用自己的声音做了克隆或用文字设计了一个音色，把生成出来的 ID 填进设置就行；那个 ID 属于你的账号，茶话会只是照着它合成。请只克隆自己的声音，克隆他人需要对方明确的授权。
• 朗读 Key 存在哪：朗读模型的 Key 保存在茶话会自己的数据文件（Hana 用户目录/app-data/chahuahui/）里。这台机器上如果系统加密接口在应用沙箱里用不上，Key 会以明文形式写进这个文件，文件本身只有你的 Windows 账户能读写；设置页会明确告诉你当前是不是这种情况。同一台机器上的其他程序仍有可能读到它，介意的话就把这条朗读配置删掉，Key 随时能重新填。
• 表情包只读不写：只读图库快照并记下发出去的图片 id，不复制图片、不上传聊天内容。

你的数据在哪

都在 Hana 分配给这个应用的数据目录下（dataDir/）。注意背景图和表情库不在 v2/ 里面：

dataDir/v2/state.json                            设置、本地角色、运行状态、伙伴设置快照（含每位的聊天背景用哪张、多暗）
dataDir/v2/threads/<id>.json                     聊天记录
dataDir/v2/partners/<id>/memory.json             分层记忆
dataDir/v2/partners/<id>/topics.json             主动话题本（聊到哪儿了、冷却到什么时候）
dataDir/v2/partners/<id>/knowing.json            关系 + 性格 + 爱好
dataDir/v2/partners/<id>/selfwatch.json          主动互动的内部状态，平常不用管
dataDir/v2/partners/<id>/review-session.json     性格协商会话（聊到一半的）
dataDir/v2/partners/<id>/palette-draft.json      性格草稿（没捏完的）
dataDir/v2/attachments/                          聊天附件
dataDir/v2/workfeed.json                         Hana 主对话近况的副本
dataDir/v2/diagnostics.jsonl                     诊断日志（不含聊天原文，只记事件和长度）
dataDir/backgrounds/                             聊天背景图库（全局共用）
dataDir/sticker-library.json                     表情图库索引
dataDir/stickers/                                表情图库图片

这些文件不属于 Hana 的伙伴资料目录。 茶话会不往 <HANA_HOME>/agents/ 里写任何东西，这条我盯得最紧。

账本文件万一读坏了，它会把原文件改名留档（.corrupt-时间戳）再用空数据继续跑，不会一声不响把整本账清掉。所以你的目录里偶尔会多出这种文件，那是留的证据，不是垃圾。

可选增强

• 「表情包」应用或旧版插件（新版应用：moononnn/hanako-biaoqingbao-app；旧版插件：moononnn/hanako-biaoqingbao）：装任意一代都能用；新版应用优先，旧插件兼容兜底。没装或两边都读不到时安静地跳过
• 「拾光记」应用（跟茶话会一样是 Hana v2 应用）：装了才能在设置里打开「今日情境」（让伙伴知道今天什么日子、窗外什么天气）；另外它那边过了钟点还没了结的待办，会让一位伙伴主动来说这一句，你在茶话会里随口说「我做完了」也能请它划掉。默认关
• 「鲜花酿」（Hana v2 酒馆角色卡工具）：茶话会里的酒馆角色邀请入口由鲜花酿触发；需要对方版本支持邀请服务，并批准茶话会的服务能力。导入只接卡面设定与世界书里筛选出的人格档案，不拿酒馆系统提示、整本世界书规则或聊天记录；同一张卡重导只更新设定，不会动你在茶话会里的聊天和记忆。

这几个都是可选的，缺了不影响普通聊天。

卸载与换机器

• 在 Hana 扩展页「已安装」里卸载，或者直接删掉 <HANA_HOME>/apps/chahuahui，应用就没了
• 数据不会跟着走：应用自己不会去删 dataDir/，它还在原处（宿主卸载时会不会顺手清掉，看 Hana 版本的脾气）。想彻底清干净，自己把整个 dataDir/ 删掉
• 换机器：应用目录和数据目录都要搬。现在还没有内置的导出/导入，手动搬整个 dataDir/ 就行（是整层 dataDir/，不只 v2/，背景图和表情库在 v2/ 外面，只搬 v2/ 会漏）。到了新机器，应用能力要重新批准一次

兼容性

• 这是个 Hana v2 应用（manifestVersion: 2），最低版本见 manifest.json 的 minAppVersion（站点导航里的茶杯小图标从 0.1020.0 起才认 pageIcon，低了整个应用会装载失败）
• 图标一共三处，各归各位：卡片面上用的是新画的那张（ui/assets/icon.png），整页和并排两张卡共用；扩展列表和 App 管理里用的是另一张 App 图标（包根 assets/icon.png，走顶层 manifest.icon）；站点导航条上另有一只简约绿杯子（ui/assets/nav-icon.png，宿主按 ui/ 目录解析 pageIcon）。三张都跟着安装包走，不用另外下载
• 零额外运行时依赖（纯 Node，用 Hana 自带的运行时）
• 支持独立窗口，卡片可以拖出来单独放；另有一张画布卡可以拖到主页面，跟 Hana 主对话框左右并排
• 联网搜索和语音合成走的是应用在 manifest.network.allowedHosts 里声明的域名。如果你在设置里填了自定义的语音服务地址，它不在这个名单里时可能发不出去，换成默认的 MiniMax 或 MiMo 最稳
• 字体不内嵌，原因上面说过了

开发

node --check index.js
node <HANA_ROOT>/scripts/validate-app.mjs --dir . --json   # 得在应用目录里执行
# 测试（零依赖，用 Node 内置 node:test；完整命令见项目仓库的 TESTING.md：
# https://github.com/moononnn/Hanako-chahuahui/blob/main/TESTING.md；发布 zip 为了轻量不带测试文件）

目录结构（这里是主干，其余模块从略）：

index.js          路由与编排
lib/persona.js    读伙伴人格与记忆（只读）
lib/prompt.js     系统提示与消息转换
lib/model.js      调模型（stream 优先，utility 兜底）
lib/store.js      自有账本 + 诊断日志
lib/rhythm.js     节奏器
lib/reply.js      消息什么时候被接住
lib/workfeed.js   Hana 主对话近况（只读来源，存在自己这儿）
ui/panel.html     好友列表 + 聊天窗口
ui/settings.html  设置页

⚠️ 改这个应用的人注意一条：apply() 里绝不能调用受权限保护的接口（ctx.bus.request / ctx.resources.* / ctx.models.*）。宿主会判定装载失败，连安装记录一起回滚，应用会直接从列表里消失。受保护调用一律放到路由或定时回调里，tests/load.test.js 守着这条。

排查

• 诊断日志：GET /api/apps/chahuahui/routes/diagnostics（只记事件名和长度，不落聊天原文）

致谢

ai4rpg/tavern-cards

「认真认识 ta」和性格分析那一套，方法论出自这套写卡流程。我借的是它「AI 当记者、用户当作者」的骨架：问题只是抓手，答案得你自己给；提炼的是你身上真实存在的东西，不是替你编一个人设。茶话会只留下跟闲聊有关的那部分，打包、角色卡工具一概没用。那套流程自己还有一层致谢（sanmingyue 的写卡预设），一并谢过。

MomoiCore/HDS-Interlude（GitHub 镜像）

伙伴主动联系那一套的早期思路参考过这个项目。借的是两条机制：主动开口要有来处，是因为某件真的事才想起你，不凭空丢一句；时机不合适的时候不硬塞，等合适的时候再轻轻放下。借的是机制，没有使用它的代码。

「表情包」和「拾光记」

这两个插件的作者也是我。茶话会跟它们是各管各的联动：表情包只借图，情境只借一天的日子和天气，都能单独关掉。

deanm/omggif

GIF 解帧使用 Dean McNamee 的 omggif 编解码器（MIT），原版权与许可声明保留在 lib/vendor/omggif.cjs；本应用的许可不替代该第三方模块的 MIT 许可。

反馈

遇到 bug、有想吐槽的体验，或者想要什么新功能，欢迎来 GitHub 提 issue：

Hanako-chahuahui/issues

提的时候带上：版本号、你做了什么操作、出现了什么现象（最好带截图）。信息越全，我修得越快～

项目关系

本应用是 HanaAgent 的社区应用，与 HanaAgent 官方没有隶属或担保关系。

HanaAgent 项目：github.com/liliMozi/openhanako

署名

moononnn & 小花

许可

源码使用 PolyForm Noncommercial License 1.0.0（仅限非商业用途），详见 LICENSE。

第三方素材与平台名称归各自所有者所有。