🌐 主站: 可可萝.我爱你 | 📖 开发博客: 给 AstrBot 写了个群聊感知插件
让 bot 拥有跨群/跨会话的记忆能力，像真人一样记住各个群和私聊中发生的事情。
- 记录每个用户在不同群/私聊中的发言摘要
- 在另一个群聊/私聊中与该用户对话时，bot 能自然地引用之前的内容
- 支持私聊↔群聊、群聊↔群聊的双向感知
示例：
用户在 A 群说：「今天考试考砸了，好烦」
用户在 B 群和 bot 聊天时，bot 可能会说：「考试的事还好吗？别太在意了」
- 记录各个群的完整对话流（包括所有群友的发言）
- 定期生成群聊对话摘要
- 在其他群被问到时，bot 能引用其他群发生的事情
示例：
A 群对话：
- 群友1：我被欺负了，好烦
- 群友2：怎么了？
- 群友3：别提了，他考试考的一团糟
B 群有人问 bot：「群友1 怎么了？」
bot 回复：「说是考试考砸了」
- 当群友发送合并转发的聊天记录时，bot 会读取其中的内容
- 采用抖动合并策略：等待后续群友对聊天记录的讨论结束后，将「聊天记录内容 + 群友讨论」作为一个整体生成摘要
- 若群友发完聊天记录后各聊各的，则超时后丢弃，不产生垃圾摘要
示例：
群友 A 发了一段从其他群截取的聊天记录
群友 B、C 围绕聊天记录内容展开讨论
抖动结束后，bot 把「A 分享的聊天记录 + B、C 的讨论」合并为一条群聊摘要，供跨群感知使用
在 AstrBot Dashboard 中安装插件，填入仓库地址：
https://github.com/TaiLaaa/astrbot_plugin_cross_session_awareness
⚠️ 安装后请重启一次 AstrBot，插件会在启动时自动读取你已配置的模型供应商列表，填充到摘要模型和视觉模型的下拉选项中。
⚠️ 如果配置页里出现了不属于你当前环境的模型，或者模型下拉没有正确加载出来，请重载插件一次刷新模型列表。
安装后在 Dashboard 的插件配置页面中设置：
| 配置项 | 说明 | 默认值 |
|---|---|---|
| 摘要模型 | 用于生成摘要的 LLM 模型 ID，留空则使用原文截断 | 空 |
| 视觉模型 | 用于识别图片的模型 ID，留空则标记为 [含图片] | 空 |
| 启用群聊上下文感知 | 是否记录群聊对话并生成摘要 | ✅ 开启 |
| 群聊摘要抖动时间 | 群聊静默多久后生成摘要（秒） | 60 |
| 触发摘要最少消息数 | 至少积累多少条消息才生成摘要 | 3 |
| 注入时最多引用群数 | LLM 请求时注入多少个其他群的上下文 | 3 |
| 每群最大消息缓存数 | 每个群缓存的原始消息数量 | 50 |
| 每用户最大记忆数 | 每个用户保留的跨会话记忆数 | 20 |
| 记忆过期时间 | 记忆自动过期的小时数 | 48 |
| 每次注入最大记忆数 | 每次 LLM 请求注入的最大记忆条数 | 5 |
| 最小消息长度 | 少于此字数的短消息不记忆 | 4 |
| 用户消息抖动时间 | 用户停止发言后多久生成摘要（秒） | 15 |
| 转发暂存超时时间 | 合并转发暂存等待讨论的最长时间（秒） | 300 |
| 私聊→群聊感知 | 允许在群聊中引用用户私聊内容 | ✅ |
| 群聊→私聊感知 | 允许在私聊中引用用户群聊内容 | ✅ |
| 群聊→群聊感知 | 允许跨群引用 | ✅ |
| 会话黑名单 | 不参与记忆的会话 SID 列表 | 空 |
💡 模型选项会在插件启动时自动从 AstrBot 已配置的模型列表中读取，无需手动输入。
黑名单填入的是会话的完整 ID（unified_msg_origin），格式为：
平台前缀:消息类型:QQ号或群号
常见格式举例：
| 场景 | 填入内容示例 |
|---|---|
| 屏蔽某个群 | default:GroupMessage:582235104 |
| 屏蔽某个用户的私聊 | default:FriendMessage:2624836044 |
如何获取正确的会话 ID？
在 AstrBot 日志中搜索关键词 UMO，可以看到类似：
UMO: 「default:GroupMessage:582235104」
复制引号内的完整字符串，粘贴到黑名单列表中即可。
⚠️ 直接填 QQ 号或群号不会生效，必须填完整格式。
| 命令 | 权限 | 说明 |
|---|---|---|
/跨群感知 状态 |
管理员 | 查看插件运行状态、记忆统计 |
/跨群感知 群聊动态 |
管理员 | 查看各群的对话摘要 |
/跨群感知 查看 |
所有人 | 查看自己的跨会话记忆 |
/跨群感知 可用模型 |
管理员 | 列出可配置的 LLM 模型 ID |
群聊消息 ──→ 消息捕获（priority=99990）
│
├── 普通文本/图片
│ ├── 用户个人缓冲区 ──→ 抖动合并(15s) ──→ LLM 摘要 ──→ 用户记忆库
│ └── 群聊上下文缓冲区 ──→ 抖动合并(60s) ──→ LLM 群聊摘要 ──→ 群聊摘要库
│
└── 合并转发聊天记录
├── 解析转发内容（调用 OneBot get_forward_msg API）
├── 暂存到 forward_pending（等待后续讨论）
└── 群聊抖动到期时：转发内容 + 后续讨论 ──→ 合并摘要 ──→ 群聊摘要库
LLM 请求 ──→ inject_memories()
│
├── 注入用户跨会话记忆（该用户在其他群的发言摘要）
│
└── 注入群聊上下文（其他群的对话摘要）──→ bot 回复时可引用
- 消息捕获：以最低优先级(99990)捕获所有消息，不影响其他插件
- 抖动合并：用户连续发言合并为一条再调用 LLM，减少 API 消耗
- 群聊摘要：群聊静默 60 秒后批量生成对话摘要，避免频繁调用
- 转发感知：合并转发内容暂存，与后续讨论合并后一起摘要，超时自动丢弃
- 无模型降级：未配置模型时使用原文截断，功能仍可用（精度降低）
- 数据持久化：JSON 文件存储，自动过期清理
插件数据存储在 cross_session_data/ 目录下：
memories.json— 用户个人跨会话记忆group_context.json— 群聊对话日志和摘要
- 建议配置一个轻量模型（如 DeepSeek-V3）作为摘要模型，避免消耗大量 token
- 群聊上下文会增加 LLM 请求的 system prompt 长度，注意 token 消耗
- 隐私：插件会记录群聊对话内容，请确保群成员知情
- 记忆默认 48 小时过期，可按需调整
- 🆕 合并转发聊天记录感知：自动读取合并转发内容，与后续群友讨论合并摘要
- ✨ 转发暂存超时配置项（
forward_pending_ttl，默认 300 秒）
- 🆕 新增群聊上下文感知：记录各群对话流，生成群聊摘要
- 🆕 跨群引用：在 B 群问 A 群的事，bot 能回答
- 🆕
/跨群感知 群聊动态命令 - 🆕 群聊摘要独立抖动时间配置
- ✨ 模型选项启动时自动从 AstrBot 读取，无需手动配置
- 消息抖动合并，减少 LLM 调用
- 图片消息支持（视觉模型识别）
- 初始版本：用户跨会话记忆