最近这几个月的绝大多数业余时间我都花在了这个名叫 ChatBuddy 的开源项目上。它的定位不复杂把一个有长期记忆、能调用工具、能区分上下文的 AI 助理直接“塞”进常用的聊天软件里。2.0 版本我已经发布了重点补上了两个高频需求一个是历史会话搜索另一个是跨设备、跨成员的云端协作。这篇文章不打算做发布公告式的罗列而是直接把架构思路、检索方案、协作边界和踩坑记录拆开讲清楚。如果你正在做类似“IM AI Agent”的结合或者单纯想给自己的群聊加一个能记住事的私人助理这版设计应该能给你省不少弯路。先交代一下背景ChatBuddy 不是那种重新做个网页聊天框的助理而是一个适配层项目。它在别人写好的即时通讯软件里伪装成一个普通联系人/机器人你用聊天的姿势跟它交互它帮你完成问答、纪要、任务跟进、信息检索这些事。2.0 之前大家反馈最多的问题是“助理确实能聊天但它聊过就忘想搜回之前某句话特别费劲”以及“我在公司电脑上的对话回家想接着聊就得重新讲一遍背景”。于是 2.0 我干脆把搜索和协作做成了底层能力而不是后期追加的小插件。下面按模块说。1. 为什么非要把 AI 助理“住进”聊天软件而不是做成独立应用1.1 交互习惯和触达成本是第一道坎你回想一下自己手机里的应用分布就知道聊天软件是每天打开次数最多、停留时间最长的应用类型。相比之下一个独立 AI 助手 App 的处境是用户可能新鲜两天之后就放在角落里吃灰。让助理住在聊天软件里本质上是把 AI 的触达成本降到了“给好友发消息”的水平。用户不需要学习新的界面逻辑不需要记住第二个入口它就在会话列表里。从产品角度说IM 自带的消息通知链路是最适合 AI 助理的场景。私人助理经常会碰到“需要你稍后确认”的情况比如提醒你三点开会、帮你盯着某个网页价格变化、定时汇总群里的未读消息。这些能力如果做在独立应用里要么依赖系统推送授权要么用户根本看不到。而聊天软件里的机器人天然就有一条畅通的消息触达通道你不需要额外解决“如何唤起用户注意力”这个问题。1.2 聊天软件本身就是一个超强的上下文数据库第二个原因更关键用户的大量真实工作上下文本来就在聊天软件里。项目群里的讨论、同事发来的文件、领导布置任务的语音转文字、客户反馈的截图……这些信息天然以对话形式沉淀在 IM 里。如果 AI 助理住在同一个聊天软件里它就能在授权范围内把这些上下文变成自己的记忆来源而不是像独立 App 那样“被迫失忆”。这个点也是 2.0 会话搜索功能最核心的设计依据不是让助理脱离 IM 单独存一套对话记录而是让助理直接索引用户在聊天软件里产生的会话。用户说“把我上周跟设计讨论的结论整理一下”助理能真正去会话库里检索而不是只能翻自己说过的话。这种“助理视角”和“用户视角”的统一只有住在聊天软件里才做得到。1.3 适合谁来参考这套方案如果你符合下面任一场景这篇内容对你会比较有用第一你维护着一个团队群或社群想让机器人具备跨会话的记忆能力而不是每次都被 后答非所问第二你正在做 IM 机器人的二次开发想给机器人增加“搜历史”和“多人共享状态”的能力第三你纯粹想给自己搭一个私人助理希望所有聊天数据在自己可控的服务器上流转而不是全部丢给某个大平台。我见过不少团队走另一个方向自研一个带聊天界面的 AI 工作台。实话说那工程量至少翻三倍还得处理消息推送、客户端兼容、多端同步一堆破事。ChatBuddy 的思路是把 IM 本身作为前端项目只做后端的大脑和记忆这样能用最小的成本撬动最大的交互红利。2. ChatBuddy 2.0 的整体架构与模块拆分2.1 分层架构不让“接入方式”绑架“对话逻辑”1.0 时期我犯过一个典型的架构错误把所有消息处理逻辑直接写在微信机器人的回调函数里导致后续想再加一个飞书渠道时差不多要把对话引擎整个复制一遍。2.0 做重构时首先定下的原则就是分层参考了一个比较通用的 Agent 服务端设计适配层负责对接不同 IM 平台把平台原始的 webhook/长连接消息统一成内部 Message 对象会话管理层负责维护多轮对话、会话 ID、参与者权限、超时策略Agent 核心层负责调用大模型、编排工具、决定下一步动作不关心消息来自于哪个软件记忆与搜索层负责消息入库、向量化、全文索引和混合检索云协作层负责把会话状态同步到用户的其他设备或者共享空间里。分层的价值在重构时体现得特别明显。我加新平台时只需要写一个 adapter把平台的 webhook 数据结构转换成 ChatBuddy 内部的统一结构剩下所有能力开箱即得。反过来说如果某天大模型供应商想换一家我也只需要替换 Agent 核心层里对模型 API 的调用完全不会碰到底层消息适配和会话索引逻辑。2.2 内部通信的事件总线设计ChatBuddy 2.0 在各层之间没有用一堆互相调用的函数而是引入了一个轻量事件总线。核心事件包括 message.received、message.before_send、session.created、session.archived、search.requested 等等。每一层只向总线声明自己关心的事件然后异步响应。这样做最大的收益是异步 IO 不会阻塞 IM 回调。拿主流 IM 平台来说很多平台要求 webhook 在几秒内返回响应否则会认定投递失败并重试。如果我在回调里直接做“调大模型 → 查向量库 → 生成回复”大概率因为模型推理太慢导致请求超时。事件总线模式下webhook 只负责把消息转成事件发布出去然后立即返回后台 worker 慢慢处理处理完再通过 IM 接口把结果发回会话里。这样用户体验上只是从“回调触发”变成了“多等两秒看到机器人正在输入”但稳定性提高了一个量级。2.3 每个模块的边界与典型配置以适配层为例我给内部消息定义了一个极简的 pydantic 模型from pydantic import BaseModel class ChatMessage(BaseModel): platform: str # im_type例如 wechat / feishu / telegram session_id: str # 当前聊天会话的唯一 ID sender_id: str # 发送者 ID sender_name: str # 可显示名称 content_type: str text content: str extra: dict {} # 平台特有字段如图片 URL、引用消息 ID 等任何平台过来的消息都会先过一转换层统一变成这个结构。会话管理层只认 session_id 和 sender_id不关心它们来自哪个平台。这种做法的实际好处在云端协作功能上线时真正体现出来了我可以在飞书一个群里跟助理聊几句然后回到微信继续同一个会话由于两边通过业务层映射到了同一个会话 ID助理完全不知道“换了聊天软件”这回事。3. 会话搜索功能详解关键词与语义双路混合检索3.1 为什么不做单一大模型“硬搜”2.0 最早做搜索时我有过偷懒的念头把所有历史消息一股脑拼进上下文让大模型自己挑。实验之后就放弃了——模型单次上下文窗口有限塞五千条历史记录既不现实也容易产生严重的注意力漂移。后来换了一种更工程化的思路先通过传统文本检索做一次“粗筛”把候选数量压缩到几十条再用 AI 做重排和摘要。这种“传统检索召回 模型精排”的模式在信息检索领域已经很成熟放到聊天记录这场景同样适用。聊天记录有一个天然区别于网页检索的特征时序性和强上下文。搜“上个月谈的价格”光做关键词匹配很难把“价格”同义改写为“报价”“单价”等变体而纯向量检索又容易忽略人名、编号这类精确词造成同音字误判。所以 ChatBuddy 的检索层一开始就朝“混合检索”方向设计词法索引负责精确命中向量索引负责语义拓展两者结果用 RRFReciprocal Rank Fusion方式做融合最后再交给重排模型统一排序。这套组合非常像搜索引擎里常见的“BM25 召回 Dense Retrieval 召回 Rerank”三段式只是底层库选得更轻量。3.2 落库与索引流程在落库前ChatBuddy 会把长消息按长度切分成了固定大小的块块与块之间保留 30% 重叠避免关键信息刚好被截断。每条消息入库时会附上一份元数据包括 session_id、sender_id、timestamp、消息类型等。这些字段后面都会作为过滤条件参与检索比如你可以只搜“某个人在某天之后说的话”这个精度是直接塞 prompt 给模型做不到的。检索流程我简化成下面的步骤用户发起搜索请求带上查询词和可选的过滤条件词法检索引擎对查询词做分词在 FTS5 索引中执行 MATCH 查询并返回 Top K向量检索引擎把查询词编码成 embedding在向量库中做相似度检索并返回 Top KRRF 把两路结果的排名分数合并重排模型对融合后的前 30 条做精细打分最终结果以“会话块 上下文摘要 定位跳转链接”的形式返回给用户。这里简单展示一下词法索引的建表和查询片段-- 建虚拟表使用 SQLite FTS5 CREATE VIRTUAL TABLE IF NOT EXISTS chat_messages_fts USING fts5( session_id UNINDEXED, sender_name, content, msg_type UNINDEXED, ts UNINDEXED ); -- 插入时同步写 FTS INSERT INTO chat_messages_fts(rowid, session_id, sender_name, content, msg_type, ts) VALUES (?, ?, ?, ?, ?, ?); -- 查询时用 bm25 排序并把过滤条件放在外面 SELECT rowid, session_id, snippet(chat_messages_fts, 2, [, ], …, 12) AS highlighted FROM chat_messages_fts WHERE chat_messages_fts MATCH ? AND ts ? ORDER BY bm25(chat_messages_fts) LIMIT 20;实际测试下来四万条消息的会话库词法检索通常在百毫秒内就能完成。向量检索会稍慢一些但加了 ANN 索引之后也能控制在几百毫秒完全满足聊天气息内的体验。3.3 在什么场景下应该用向量、什么场景用词法这里分享一点实操经验如果用户搜索的内容包含明确的专有名词例如产品代号、订单号、人名、邮箱词法检索的命中率远高于向量检索。原因很好理解向量检索本质上是查找“语义相近”的文本它对近义词很友好但对精确匹配并不擅长。反过来如果用户搜索“上次说那个方案不行的理由”这一整句里根本没有稳定关键词词法检索几乎只能靠“方案”“不行”这种泛词瞎蒙这时向量检索的效果会显著更好。所以 ChatBuddy 默认对两种结果做了 50/50 的召回配额再靠重排层去纠正前两级的偏差。这种设计比硬编码阈值要稳得多也省去了在不同场景反复调参的痛苦。下面这张表是我在一台普通 4 核 8G 服务器上做的检索效果对照语料是某团队近三个月的聊天记录共约 6 万条中文消息检索方式精确专名查询命中率语义模糊查询命中率平均时延仅词法检索高低60ms仅向量检索中高380ms词法向量RRF高高420ms再加上重排模型最高最高750ms重排会带来额外延迟但成功率提升相对明显。如果对速度敏感可以把重排层做成可开关的“高级选项”默认不开启。4. 云端协作多设备与多人共享会话的安全边界4.1 先想清楚哪个“云”才是用户需要的“云端协作”这四个字在 2.0 立项时被讨论了很多次。可能有人觉得云端协作就是把聊天记录同步到服务器上让用户换设备能同步。但我把需求拆开后发现真实用户其实有完全不同的两个诉求一是“我在自己手机聊的内容晚上回家能在电脑上继续”这是个人多端同步二是“我在和助理单独沟通时希望项目组同事也能看到执行进展”这是共享/协作。这两个场景对权限模型和数据可见性的要求差异极大不能混在一个功能里。最终 ChatBuddy 2.0 把它们拆成了两个空间个人空间和团队空间。个人空间里的会话默认只有用户本人可见同步范围和共享范围都局限在用户自己的账号体系内。团队空间则有一个显式的“空间 Owner”由 Owner 决定谁能加入、谁能看历史、谁能只有发言权。助理在两个空间里的记忆彼此隔离不会出现团队会话内容泄露到个人空间的情况。4.2 同步的是“状态机”而不是单纯的消息流聊天同步如果只同步消息内容一定会出现多端状态错乱。比如你在手机上和助理约定明早九点提醒然后关了手机电脑端根本不知道有这条提醒又比如你在团队空间里把一个任务标记为“已完成”但另一个成员的客户端还显示“进行中”。问题的本质在于同步的不仅是消息更是助理对当前会话的认知状态。所以 ChatBuddy 云协作层同步的是一棵状态树包含会话元信息、挂起任务、记忆标签、助手内部缓存的工作区变量。所有的变更都会生成带版本号的操作记录多端通过 WebSocket 长连接接收增量更新离线时则将操作写入本地队列恢复联网后再重放到远端。这套机制跟多人协同文档的底层理念一致只是把“文档的增删改”换成了“聊天对话与任务状态”。我画过一张简单的状态流转逻辑客户端发起动作 → 服务端生成带递增版本号的 state update → 服务端把 update 广播给在线的协作成员 → 各端用本地状态机 apply update → 冲突时按服务端版本号为准并覆盖本地旧版本。这个流程保证了一个最底线的一致性不管有几台设备同时在线助理看到的任务状态一定和最新提交的一致。4.3 端到端加密是否值得做关于聊天记录的私密性2.0 很早就把端到端加密列为可选模块。说得直白点很多人看到“云”就会担心数据被平台运营商看到。但如果把所有数据都做端到端加密分词索引和向量检索的难度会直线上升服务端没法对密文做全文检索。行业里做这类系统的惯用妥协方案是“元数据明文 内容封箱”但这样一来搜索功能就只能搜到标题和时间根本搜不到对话正文这显然不符合 ChatBuddy 的产品目标。我的最终方案是做了二级密钥体系。默认模式下服务器能看到完整数据并负责建立索引适合部署在企业内网、可信任自托管环境的用户强隐私模式下用户本地持有主密钥发给服务器的先加密正文再进行索引搜索时服务端采用“加密关键词 同态过滤”的简化变体只把满足条件的密文消息块交还客户端做本地解密。当然强隐私模式的搜索速度和精度都有下降也无法使用云端的向量重排能力。这个取舍我在文档里写得很明确追求极速搜索就选默认模式追求绝对私密就必须接受搜索功能“缩水”。4.4 协作权限的经典坑权限模型这块我最初吃了不少亏。第一版直接参考了“群成员都可以看群聊历史”的思路结果发现不行。因为很多用户跟助理的互动是私人的比如“帮我分析下我跟某同事的合作问题”这类话根本不适合给群里所有人看。后来我把权限逻辑细分成了消息级和会话级两层会话 Owner 可以授权成员查看整个会话历史成员只能引用自己被 到的回复作为任务执行依据搜索时严格按照“发起搜索的人是否有该会话的读取权限”过滤结果。实现权限过滤其实就是所有检索请求先加一个 where 条件session_id in (有权限的子查询)。听起来简单但有一个性能坑如果用户所在会话特别多子查询的结果集可能上千进而拖慢总体检索。后来我把权限列表单独缓存了一份用户变更权限时只更新缓存不让查询阶段反复查库。这个优化让带权限过滤的检索耗时从 2 秒左右降到了 300 毫秒以下。5. 实操十分钟跑起 ChatBuddy 2.05.1 部署形态与硬件要求ChatBuddy 支持三种部署方式纯本地方案、服务器托管方案和 Docker Compose 全自动方案。一般个人用户我推荐直接使用 Docker Compose因为项目依赖了至少四个组件消息适配网关、Agent 服务、SQLite/Postgres 数据库、向量引擎。手动安装虽然也不过是几条命令的事但用容器可以省去处理 Python 版本和系统依赖的麻烦。硬件方面如果只是个人使用且调用的远端大模型 API2 核 CPU 2G 内存就足够了。如果你想用本地开源模型例如部署一个 7B 量级的对话模型那至少需要 16G 内存或者一块 6G 显存以上的 GPU并且推理时延会明显变高。我的建议是先把服务跑起来模型后端选性能够用的云 API后续再通过项目里的“模型网关”把推理切到本地。5.2 快速启动命令下面是个人快速试用版的流程。假设你已经装好了 Docker 和 Docker Compose 插件git clone https://github.com/your-org/chatbuddy.git cd chatbuddy # 复制环境变量模板填入你的 IM 机器人密钥和大模型 API Key cp .env.example .env # 启动服务网关、检索、向量引擎、后台 Worker 都在编排里 docker compose --profile full up -d # 查看启动日志 docker compose logs -f chatbuddy-core在.env里需要配置的核心项大致如下我没有列出具体的 Key你可以按自己使用的平台去申请# 大模型 API 配置 LLM_PROVIDERopenai-compatible LLM_API_KEY你的密钥 LLM_MODEL你的模型名 LLM_BASE_URL模型服务商地址 # 消息平台适配配置 IM_PLATFORMfeishu IM_APP_ID... IM_APP_SECRET... # 数据持久化目录 CHATBUDDY_DATA_DIR./data CHATBUDDY_SYNC_ENABLEDtrue我把服务做成多进程模型Webhook 网关是一个常驻服务Agent Worker 是另一组进程。这样当大模型推理出现超时时网关仍然能及时响应 IM 平台的回调不会因为 Worker 阻塞而整个服务不可用。这一点在线上跑了一段时间之后确实明显减少了 IM 平台侧的“机器人无响应”报错。5.3 接入开发时的最小可运行思路如果你的 IM 平台没有现成适配器也可以参照下面的最小 FastAPI 回调实现快速开发一个接入层。下面这个例子只处理最核心的消息收发from fastapi import FastAPI, Request from chatbuddy.events import event_bus from chatbuddy.models.message import ChatMessage app FastAPI() app.post(/im/webhook) async def im_webhook(request: Request): payload await request.json() # 不同 IM 平台的字段名不一样这里需要按实际格式解析 msg ChatMessage( platformpayload.get(platform, generic), session_idpayload.get(chat_id), sender_idpayload.get(user_id), sender_namepayload.get(username, ), contentpayload.get(text, ), ) # 可以直接在适配层拦截指令比如普通消息不用触发助理 if not msg.content.startswith(chatbuddy) and msg.content ! /ask: return {ok: True, skip: True} # 发布内部事件所有后续处理交给 worker await event_bus.publish(message.received, msg) # 先立刻响应平台避免 webhook 超时重试 return {ok: True, status: accepted}实际的 adapter 还要处理图片消息、引用消息、消息撤回等一些边缘情况。但核心路径就这么简单收到消息、转成标准对象、发布事件、立刻返回。所有的“聪明活”都在 worker 侧慢慢做逻辑上完全不阻塞接入层。5.4 会话搜索与协作的配置开关2.0 版上线后是不是所有人打开就能搜索历史我特意没有默认开启索引功能。原因很直白把用户聊天记录全部建立索引涉及隐私预期和存储成本最好由用户明确决定。所以在管理的后台页面里有两个开关“启用历史会话索引”和“启用云端协作同步”。开启索引时系统会对已有历史消息做一次离线重建后续新消息则实时增量索引。协作同步还有一个“审计日志”开关。团队空间建议打开它会记录谁在什么时候把某段会话同步给了哪个新成员出问题时有据可查。个人空间则不需要开减少无谓的写入量。6. 实战中踩过的坑与排查实录6.1 高频问题速查表在项目问题反馈里出现频率最高的问题差不多就是下面这几个我把典型症状、排查思路和解决方案整理成了速查表症状可能原因排查与解决新消息搜索不到增量索引队列积压登录服务器看 worker 日志确认是否还在重建历史索引必要时手动触发 flush中文搜索分词奇怪默认分词器不支持中文换用 jieba / IK 分词器或在写入前手动对 content 做分词并录入词法索引同一个问题不同设备答得不一样本地区状态未同步检查 WebSocket 通道是否掉线查看服务端 last_sync_version 是否已推进搜索结果排序不对找不到重点没有开重排层打开 Rerank 开关模型用小尺寸的 cross-encoder 即可把非本组织成员的会话搜出来了权限缓存未刷新清空协作权限缓存确认所有检索都带上了当前用户可见的 session_id 子查询这些坑里最让我意外的就是中文分词。SQLite FTS5 默认 unicode61 分词器对中文基本是“整句切一个词”导致我搜“价格”永远匹配不到“报价”。后来我写了一个分词回调在数据入库前先把中文句子用 jieba 切成词数组再拼接成空格分隔的文本写入 FTS5。效果立竿见影中文检索的命中率提升非常明显。如果你是做类似功能务必把“入库前分词”这一步放在前面设计不要等数据量大了再迁移。6.2 一个被我忽略的权限级联问题云端协作上线测试时我发现一个特别隐蔽的 bug当用户 A 把一个会话分享给用户 B随后 B 又把会话分享给了用户 C。表面上看 B 有权限所以 B 能把会话同步给 C但逻辑上 C 是否应该拿到完整历史需要依据会话 Owner A 的授权策略来决定。最初实现我没做这个级联校验导致 C 能看到 A 从未授权过的聊天内容这算一起严重的数据越权漏洞。修复方案是引入“授权链”概念分享权限不能超越当前用户的权限范围。用代码表达就是每次 grant 操作都要检查“被分享的会话范围是否为我当前拥有权限范围的子集”。另外对已分享出去的成员做权限回收时也要递归清理所有下游的派生授权。这个坑强烈建议正在做多人会话协作的朋友提前规避不要只是在 UI 层加一个按钮底层一定要有权限传播的判断逻辑。6.3 检索召回质量不上不下的调试方法如果你做完搜索功能后觉得自己检索“凑合能用但总不够好”建议先用一组“验收查询集”来量化问题。我从用户反馈里提炼了大概三十条典型查询比如“找出上个月产品评审里的风险点”“我们上次说的服务器迁移什么时候执行”“小明上周发的客户反馈原文”。每次改动检索参数后我会把这三十条查询跑一遍人工标记 Top5 结果是否满足预期统计一个“满意率”。这个方法非常笨但对于迭代搜索系统的帮助极大。它可以让你量化判断一次优化到底有没有进步也方便发布时向用户说明“你关心的那类检索已经有 X% 的提升”。而且当模型和向量库升级时这组查询集还相当于回归测试能挡住很多莫名的效果回退。6.4 长期运行的存储膨胀与性能下降聊天记录是日志型数据如果只增不减任何存储系统最终都会发生膨胀。ChatBuddy 默认按时间窗口管理消息保留策略普通群聊存 180 天私聊存 365 天被用户手工标记为“重要”的消息永久保存。索引库则配合做定期清理超过保留窗口的消息先从生产库迁出再从 FTS 和向量索引中删除。不设保留策略的话运行半年后你就能明显感受到搜索变慢因为要扫描的无意义数据太多了。向量索引也在膨胀后会显著降低 ANN 查询速度。最初我用的是 HNSW 索引它插入性能好但是对删除不友好频繁删除会产生很多残留向量。后来我换成分段式索引把向量库按时间段切分成多个 segment保留窗口外的 segment 直接整体丢弃用空间换维护成本。这种方案牺牲了一点磁盘占用但省掉了逐条删除向量带来的巨大开销。7. 后续规划与开源社区共建方向2.0 的功能重心主要在“搜索”和“协作”两个看得见的能力上但我心里清楚一个 AI 助理项目的天花板其实是“记忆的组织方式”。目前 ChatBuddy 的记忆还是偏“对话记录式”的搜聊天记录本质上是在还原当时的对话上下文而不是把散落的信息提炼成结构化的知识。所以下一阶段我打算在记忆层之上增加一个“知识沉淀”模块让助理能从历史对话里自动抽取行动项、决策理由和项目进度并形成一张可以随时被查询的事实表。做成开源项目之后的另一个明显变化是提 issue 的人开始帮我补齐真实业务场景。很多使用者并不是开发者而是一个社群运营者在问“机器人能否在 500 人的大群里记住每个人都提过什么需求”。这其实要求会话层做更大粒度的成员分层记忆并非简单扩大上下文窗口能解决的。我也在组织文档里规划了“成员画像”方案不过那会是 3.0 阶段的事了。最后分享一个很实际的建议如果你只是想给自己做一个安静好用的 AI 助理不需要把“云端协作”里的所有功能都打开。个人最舒服的开法其实是开历史会话搜索、关掉多端实时同步、关掉团队共享然后找一个文件目录专门放数据。你会发现整个服务安静得像一个本地记事本没有多余的同步流量也没有复杂的权限管理但它能记住你在聊天里聊过的所有值得记住的事。这种“足够私有、足够安静”的使用体验反而最接近一个助理该有的样子。