From 1cd06dcf95d90320dad3a7560dae2dd32b274ee7 Mon Sep 17 00:00:00 2001 From: Codex Local Date: Thu, 30 Jul 2026 01:13:23 +0800 Subject: [PATCH] chore: record chat baseline before C1 --- CHANGELOG.md | 534 ++ README.md | 488 ++ __init__.py | 8 + _conf_schema.json | 960 +++ benchmarks/run_memory_benchmark.py | 170 + core/__init__.py | 1 + core/astrbot_compat.py | 478 ++ core/bridge.py | 479 ++ core/chat_import.py | 3242 ++++++++++ core/classifier.py | 235 + core/commands.py | 522 ++ core/config.py | 129 + core/context_orchestrator.py | 265 + core/identity.py | 211 + core/importance.py | 718 +++ core/injection.py | 685 ++ core/migration_livingmemory.py | 520 ++ core/models.py | 243 + core/operations.py | 675 ++ core/qq_history.py | 685 ++ core/reply_chain.py | 331 + core/retrieval.py | 2361 +++++++ core/service.py | 7582 +++++++++++++++++++++++ core/store.py | 5405 ++++++++++++++++ core/summarizer.py | 683 ++ core/time_intent.py | 162 + core/turn_signal.py | 549 ++ core/visibility.py | 109 + logo.png | Bin 0 -> 161559 bytes main.py | 339 + metadata.yaml | 21 + page_api.py | 2561 ++++++++ pages/记忆面板/app.css | 5076 +++++++++++++++ pages/记忆面板/app.js | 6720 ++++++++++++++++++++ pages/记忆面板/index.html | 466 ++ tests/__init__.py | 1 + tests/test_bridge_shared_experience.py | 54 + tests/test_cross_window_continuity.py | 227 + tests/test_epistemic_calibration.py | 748 +++ tests/test_historical_chat_import.py | 954 +++ tests/test_operations.py | 223 + tests/test_panel_regressions.py | 250 + tests/test_qq_history_reader.py | 327 + tests/test_rerank_validation.py | 81 + tests/test_retrieval_performance.py | 181 + tests/test_security_cache.py | 536 ++ tests/test_store_consistency.py | 477 ++ tests/test_strict_session_visibility.py | 70 + tests/test_summary_relationship.py | 943 +++ 49 files changed, 48685 insertions(+) create mode 100644 CHANGELOG.md create mode 100644 README.md create mode 100644 __init__.py create mode 100644 _conf_schema.json create mode 100644 benchmarks/run_memory_benchmark.py create mode 100644 core/__init__.py create mode 100644 core/astrbot_compat.py create mode 100644 core/bridge.py create mode 100644 core/chat_import.py create mode 100644 core/classifier.py create mode 100644 core/commands.py create mode 100644 core/config.py create mode 100644 core/context_orchestrator.py create mode 100644 core/identity.py create mode 100644 core/importance.py create mode 100644 core/injection.py create mode 100644 core/migration_livingmemory.py create mode 100644 core/models.py create mode 100644 core/operations.py create mode 100644 core/qq_history.py create mode 100644 core/reply_chain.py create mode 100644 core/retrieval.py create mode 100644 core/service.py create mode 100644 core/store.py create mode 100644 core/summarizer.py create mode 100644 core/time_intent.py create mode 100644 core/turn_signal.py create mode 100644 core/visibility.py create mode 100644 logo.png create mode 100644 main.py create mode 100644 metadata.yaml create mode 100644 page_api.py create mode 100644 pages/记忆面板/app.css create mode 100644 pages/记忆面板/app.js create mode 100644 pages/记忆面板/index.html create mode 100644 tests/__init__.py create mode 100644 tests/test_bridge_shared_experience.py create mode 100644 tests/test_cross_window_continuity.py create mode 100644 tests/test_epistemic_calibration.py create mode 100644 tests/test_historical_chat_import.py create mode 100644 tests/test_operations.py create mode 100644 tests/test_panel_regressions.py create mode 100644 tests/test_qq_history_reader.py create mode 100644 tests/test_rerank_validation.py create mode 100644 tests/test_retrieval_performance.py create mode 100644 tests/test_security_cache.py create mode 100644 tests/test_store_consistency.py create mode 100644 tests/test_strict_session_visibility.py create mode 100644 tests/test_summary_relationship.py diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..55ebf9e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,534 @@ +# Changelog + +本项目遵循面向用户体验的版本记录。日期使用北京时间。 + +## 1.6.5 - 2026-07-26 + +### 记忆显微镜 + +- 召回测试在未选择会话时改为管理端“全部可检索记忆”,不再因空 `unknown` 上下文把私聊、群聊记忆全部过滤;选择具体私聊或群聊后仍按真实可见性与 ACL 模拟,可解析的会话键也会校验范围和目标一致性。 +- 显微镜新增独立的检索范围选择器、结果范围标识和持久错误状态;同一私聊或群聊由多个 Bot 共用时可分别模拟,归档与内部记录不会生成无效选项。 +- 切换范围、修改查询或刷新记忆桶会立即作废旧请求并允许重新检索,迟到的结果和错误不会覆盖当前页面。 +- 桌面端固定为“标题 / 输入 / 可滚动结果”三行布局,结果增多不会再遮挡输入框;手机端继续使用整页自然滚动。 +- 插件运行版本、元数据、说明文档和面板静态资源缓存标识同步更新为 `1.6.5`。 + +## 1.6.4 - 2026-07-23 + +### 历史聊天导入 + +- 文件导入新增 QQChatExporter JSON:识别其 `metadata`、`chatInfo` 和 `messages` 结构,保留原始消息 ID、序号和发送者 QQ;撤回、系统消息会跳过并提示,图片、语音、回复、卡片等非文本内容保留为可读占位,`selfUin` / `peerUin` 仅作为高置信身份建议,仍需人工确认。 +- “可移植数据”入口会明确提示 QQChatExporter JSON 应从“历史聊天导入 / 文件导入”进入,避免将普通聊天 JSON 误当成本插件 JSONL 档案。 +- QQChatExporter 消息指纹改为基于会话身份与原始消息证据;同一聊天更新统计、资源信息或增量追加后再次导入时,旧消息 ID 保持稳定,避免重复写入历史时间线。 +- 历史聊天执行接口补齐用户与 Bot 同 ID、QQChatExporter 群聊误入私聊模型的后端校验,避免身份归属被错误合并。 +- 可移植档案会核对头部声明数量,截断或不完整档案不再被误判为有效备份。 +- 面板静态资源更新为 `1.6.4` 缓存标识;导入预览会绑定实际来源,切换标签后不能误启动旧预览,文件解析失败也会保留可重试的页面错误提示。 +- QQChatExporter 文件会按原始消息 ID 去重,并以 `chatInfo` 中的稳定 QQ 身份归并导出期间的昵称变化,避免重复消息在执行期回滚或同一 Bot 被拆成多个说话人。 +- 增量重导入会区分既有时间线与本次新增消息,只对新增部分创建分段和模型整理任务,避免旧记录重复消耗模型或生成措辞不同的重复摘要。 + +## 1.6.3 - 2026-07-23 + +### 陪伴笔记 + +- 新增 `memory_companion_note_delete` LLM 工具,Bot 可按笔记 ID 删除自己创建的陪伴笔记;唯一精确标题也可直接删除,模糊或重复标题会先返回候选 ID,避免误删。 +- 陪伴笔记读取与删除统一校验当前 Bot 所有权,多 Bot 环境不会读取或删除其他 Bot 的私有笔记;创建、读取和删除继续共用 `memory_tools.enable_note_tools` 开关。 + +### 手机端体验 + +- 记忆拓展页在平板和手机端改用整页滚动,解除工作区内容高度裁剪;拟人维度页不再重新形成嵌套滚动。 +- 个人日程胶片会先判断拖动方向:横滑切换日程,纵滑交还页面;输入控件使用 16px 字号,主要触控目标不低于 44px,并补齐动态视口、安全区和惯性滚动适配。 + +## 1.6.2 - 2026-07-20 + +### 共同经历记忆 + +- 新增通话/共同观影共享经历桥接:接入插件可只写入一条经过整理的稳定摘要,不必保存逐句转写、原始音频或视频帧。 +- 共享经历明确记录实际 Bot 账号为主体、主要用户为共同参与者,并区分 `shared_call` 与 `shared_watch`,修复多 Bot 环境可能归到模糊 `self` 的问题。 + +### 历史聊天导入 + +- 文件解析新增“发送者 / 时间 / 内容”字段式导出兼容,自动判断发送者与内容位于时间字段前后的位置,并排除消息 ID 等元数据;“时间”“内容”不再被误列为说话人。 +- 字段式记录缺少发送者时会在预览阶段给出可操作提示,不再基于错误解析生成数百次模型调用;私聊文件识别出异常多说话人时仅柔性提醒检查格式。 + +## 1.6.1 - 2026-07-17 + +### 陪伴称呼联动 + +- PrivateCompanion 提供固定称呼时,关系阶段称呼建议会让位于该称呼;历史称呼、显示名和旧记忆只保留为识别资料,不再派生新的亲昵称呼,也不会要求每句都重复称呼。 +- 用户在当前消息明确要求改称呼时仍优先采用最新要求,兼顾固定配置与自然对话中的即时更正。 + +### 召回边界与连续性 + +- 通用“讲个冷笑话/故事/段子”等轻量创作请求会直接处理当前消息,不再启动无关长期检索;判断收窄为明确指令结构,单纯谈到“故事、自拍、解释、漫画”等内容不会误触。 +- “符合我性格、你觉得我会喜欢”等个性化创作继续检索相关画像,也可使用当前发言者自己已授权给该群的私聊记忆;未点名的其他成员画像会被过滤,其他人的私聊仍需明确点名并满足 ACL。 +- 新话题和低信息保护不再裁剪 AstrBot `req.contexts`,只抑制无关长期记忆并保留原始对话,避免图片、查询等请求后丢失稍早已经确认的事实。 +- 私聊近期事实防遗忘会从同一会话近 3 小时提取吃饭、洗澡、上下班、位置和休息状态;若 Bot 已围绕该状态回应,会先提示模型核对,注入调试同步显示 `recent_fact_guard=0/1`。 +- 每日穿搭快速上下文在字数紧张时优先保留日程、历史穿搭、服装偏好和最近图片,不再因夜间气氛或称呼提示挤掉服装偏好。 +- 阶段性总结自动重试新增指数退避:连接、超时、限流和 502-504 达到上限后进入冷却并自动恢复探测,手动总结仍可立即执行;同一冷却状态不再随每条新消息重复刷 WARN,内容或解析错误继续保留原始时间线并等待人工处理。 + +### 面板修复 + +- 个人记忆相册详情图改用确定尺寸的 `contain` 画框,方图和竖图不再被宽屏详情容器裁成横幅;详情区同步扩大并更新 CSS 缓存标识。 + +## 1.6.0 - 2026-07-15 + +### 历史对话整理导入 + +- “维护 / 迁移 / 配置”的二级导航新增独立历史聊天导入页,按“选择来源、读取预览、确认身份、生成记忆”推进;QQ 直接读取、文件导入和最近任务使用页内标签切换,不再挤进维护工具网格或占用首页入口。 +- 新增 NapCat/aiocqhttp 好友历史直读:选择当前 Bot 连接、目标 QQ 和起止时间后调用 OneBot `get_friend_msg_history` 分页读取;限制为纯数字 QQ、最长 31 天、最多 5,000 条,并对分页边界去重、接口游标停滞和不完整范围给出明确提示。 +- QQ 直读保留原始 OneBot 消息 ID、消息序号、适配器 ID、发送者账号和来源类型,图片、语音、回复等非文本消息转为可读占位;Bot 登录账号和目标 QQ 会生成高置信身份建议,但开始整理前仍需人工确认。 +- 文件导入继续支持拖拽 TXT、LOG、Markdown,兼容 UTF-8、UTF-8 BOM 和 GB18030,并统一归档为 UTF-8;预览会集中展示时间检查、内容规模、预计模型调用、分段抽查和身份建议依据。 +- 解析器支持完整或缺少年份的消息时间、跨年补推、多行正文、相同时间戳和倒序记录;连续短消息按逻辑发言合并,再按时间、跨日、问候、回合数和字数切片,适配大体量记录且尽量不拆问答。 +- 用户/Bot 身份、稳定账号和称呼改为单处确认,低置信身份不再默认猜测;执行前强制校验角色数量、ID 冲突和确认状态,减少整批归属选反。 +- 原消息永久进入 `historical_archive` 时间线;模型按片段生成详细回忆和重要事件,再汇总日摘要、稳定事实与阶段摘要,所有长期结论都保留实际证据边界。 +- 导入任务支持后台进度、暂停、恢复、中断续跑、失败限次、确定性幂等和整批回滚;执行前自动备份不可变原文、JSONL 档案和清单,启用 Embedding 时会在完成前补齐本批向量。 + +### 质量、归属与可靠性 + +- 历史导入优先复用已有私聊窗口,并统一解析稳定称呼、原始说话人、括号别名和账号 ID;私聊分桶与权限判断可从 AstrBot session 键恢复稳定目标,旧批次也能幂等修复关联,避免同一用户被拆成多个对象。 +- 历史片段采用“明确称呼的第三人称详细回忆 + 简短检索摘要”双层结构,保留起因、关键互动、决定、承诺、结果和情绪变化;旧第一人称内容仅作审计,不再污染注入、全文检索或向量召回。 +- 新旧批次都会在向量收尾前检查来源体量、正文长度、第三人称视角和格式版本,只重整不合格的片段与日摘要;视角校正不会用短摘要覆盖已经合格的详细正文。 +- 导入进度统一为原文归档、片段整理、跨片段去重、细节补全和向量收尾五阶段;`timeline` 同步记录保留类别、批次和原始序号,回滚会完整清理派生索引、审核项、向量与图谱关系。 +- 总结器只消费实际送入 Provider 的时间线 ID;Provider 连续失败会保留原始时间线并在达到上限后暂停,进程中断遗留任务可安全恢复。 +- 阶段性总结使用可配置的单次 Provider 超时;相同的总结、备用和当前会话 Provider 只调用一次,常见 Ollama/OpenAI 超时会显示实际秒数而不刷整屏预期调用栈。 +- 带“那……”“嗯,那就”等自然语气前缀的例行检查仍会进入约定互动检索,不再被误判为普通短承接;只有直接支持该约定的记忆可以明说,证据不足时继续轻量确认。 +- 记忆面板补齐导入状态、失败详情、记忆分类、关系候选和向量进度;左下统计以数据库、WAL 与 SHM 的实际总占用展示记忆大小。 + +## 1.5.2 - 2026-07-14 + +### 修复 + +- 群聊短引用接话会以“本轮文字 + 直接引用”为主题锚点,仅保留与锚点有交集的记忆;每类最多 1 条、全局最多 3 条,并压缩到 1050 字以内,避免无关日程或旧设定抢走当前话题。 +- 引用接话新增人物、动作和地点的柔性归属提示,优先保持当前发言者、引用作者与第三方各自的动作关系,减少把“信使送包子”错误改写成另一个人在旧地点行动。 +- 主链与桥接上下文统一应用短引用策略,调试信息会记录短引用命中数量以及主题不匹配、分槽抑制、分槽上限和全局上限原因,便于复查实际选中了什么。 +- 新增真实主注入路径回归,覆盖短引用筛选、3 条上限、精简注入和动作归属提示,防止辅助函数测试通过但主链未接入。 + +## 1.5.1 - 2026-07-14 + +### 修复 + +- Rerank 请求前会拦截空查询并过滤无正文、证据或标签的空候选;过滤后的候选与返回索引保持一一对应,避免 SiliconFlow 等 Provider 因空字符串返回 `20015`,同时保留本地基础排序回退。 +- Rerank 调试路径新增 query、候选数量、候选最短/最长长度和模型名长度,不记录正文即可判断服务端 `String should have at least 1 character` 对应哪个请求字段。 +- SQLite 主连接锁等待收敛为 3 秒,WAL 自动 checkpoint 阈值从默认 1000 页收紧到 500 页;路径类打开异常会重建连接并对记忆、检索和向量关键操作执行一次安全重试,不在每次写入后强制 checkpoint。 +- PrivateCompanion 日程连续性改用短生命周期只读连接,只读取近期 Bot 日程/行动和当前私聊对象稳定边界,不再触发 Embedding、Rerank、全库候选或向量补建;旧版桥接保持兼容。 +- PrivateCompanion 每日穿搭新增本地快速上下文,按近期日程、历史穿搭、相关服装偏好和最近图片分配候选,不再为穿搭生图调用完整 Embedding/Rerank 检索;历史穿搭仅用于保持连续和避免重复。 +- PrivateCompanion 梦境碎片改归 Bot 自我范围,启动和维护修复会将旧 `private_companion:dream` 记录移出私聊用户列表;旧 LivingMemory 的 Live2D UUID 会话继续保持私聊隔离,但页面会标为“旧 Live2D 会话”,不再冒充 QQ 用户。 +- 睡眠维护结束时限频执行一次 `wal_checkpoint(PASSIVE)`,记录 busy、WAL 总帧和已合并帧;数据库路径异常时同步保留 DB/WAL/SHM 文件状态,避免把每次写入都变成 checkpoint。 +- 快速上下文新增 Bot 所有者校验,桥接未能唯一确定 Bot 账号时不再猜测;多 Bot、群聊和私聊记录不会仅因 `bot_self` 标记而越过所有者边界。 +- 日程快速上下文不再接纳任意手动/明确记忆,用户画像仅在与作息、提醒或互动边界相关时作为语气参考;穿搭快速上下文会过滤无关图片和日程,避免旧截图或其它图片污染每日穿搭。 +- 快速候选改为按记忆类型均衡截取,避免高频行动挤掉稳定偏好或历史穿搭;日程与穿搭快速路径均提供独立配置开关,可随时回退完整检索。 +- WAL 诊断区分当前文件状态和上次健康检查,保留 SQLite 错误码、错误名、恢复次数与最近路径异常,避免旧 WAL 大小覆盖当前状态。 + +## 1.5.0 - 2026-07-11 + +### 运维与体验 + +- 修复 AstrBot WebView 中 LivingMemory“执行导入”点击后无反应的问题:移除不可靠的浏览器原生确认弹窗,改为页面内嵌确认;删除记忆、应用预设和可移植档案导入同步使用同一机制。 +- 个人记忆日期切换统一进入忙碌与错误提示流程,读取失败时恢复原日期和缓存画面;陪伴插件检测异常不再伪装为“未安装”,改为错误状态和可见重试入口。 +- 记忆管理保存改为单个 API 和单个 SQLite 事务,内容、重要度、可见性与生命周期同时提交;FTS 或数据库更新失败会整体回滚。 +- 新增轻量、标准、陪伴三种运行预设;一键调整检索、图谱、总结阈值和注入预算,同时保留用户已经选择的总结、Embedding 与 Rerank Provider。 +- 新安装的检索模式默认值由强制 `rerank` 调整为 `auto`,与文档推荐和运行时回退策略保持一致;已有配置不受影响。 +- 新增统一运维诊断,汇总实际检索模式、最近路径、缓存命中率、模型调用、Token、平均耗时和当前记忆规模。 +- 新增已知记忆与人格插件目录扫描,将专用桥接、高风险重复注入和中等状态冲突分开提示;仅报告风险,不自动停用其它插件。 +- 维护页新增预设、诊断和可移植数据入口,相关能力同时提供管理员命令和页面 API。 + +### 数据主权 + +- 新增 UTF-8 JSONL 可移植档案,导出长期记忆、身份、关系边、时间线、ACL 规则和窗口策略;明确排除凭据、Provider 专属向量和注入日志。 +- 可移植档案支持预览和恢复,限制为受支持的版本与 64 MiB 以内文件;导入前强制备份,重复记忆继续使用内容指纹合并。 +- 新增中文内容、私聊可见性、身份、关系、时间线和 ACL 的往返测试。 + +### 检索与验证 + +- 新增确定性的 basic 检索基准,报告 `hit@5`、逐查询命中、隐私泄漏、加载耗时、查询延迟和外部检索模型调用数。 +- 根据基准补充无糖/不加糖、少糖/低糖、无冰/去冰和香菜偏好的本地等价词,在不开启 Embedding 时改善常见偏好召回。 +- 基准明确不把不同模型、硬件或配置下的结果作为跨插件质量排名。 + +## 1.4.6 - 2026-07-11 + +### 安全与可靠性 + +- 优化未来安排类对话的证据校准:询问“明天/后天有事吗”等问题时,优先使用 Bot 自身日程、明确承诺和当前对话;群聊多人摘要仅保留为不确定背景,不再轻易被说成 Bot 的既定安排或“你又忘了”的共同历史。 +- 未来安排识别改为优先于“本周/这周”等时间窗口路由,并要求存在 Bot/个人安排语义;项目、插件、版本、发布、代码等技术问题不会再误进 Bot 私人日程路径。 +- 群聊阶段总结新增明确归属提示,并避免因第一人称观察视角或关键词权重被误分为 Bot 自我连续、个人承诺或未完成事项;自然联想仍可用于语气和试探性回应。 +- 群聊总结中的 Bot 自身事实不再靠摘要布尔字段升格:只有带 Bot 原始回复事件 ID、内容重叠校验的日程/承诺/行动,才会派生为独立的 Bot 自我时间线记录。 +- 注入包改为按完整条目分配默认 1800 字符预算,始终保留闭合结构;记忆正文、检索意图、称呼等动态字段统一转义并标为不可执行资料,避免历史文本打断提示词边界。 +- 深夜“例行检查/查岗/在不在”等短检查不再展开旧摘要、穿着、梦境或其它私密细节;命中记忆只保留为一条轻量熟悉感提示,避免把语气底色误包装成未完成事项。 +- 注入正文和注入调试日志会隐藏密码、口令、验证码、令牌和密钥值;`tone` / `uncertain` 的 open loop 不再放进高优先级 `open_loops` 分区。 +- 称呼提示改为按关系错配、当前称呼、关系阶段依次决策,只输出一条校准建议,避免“亲密称呼”和“关系尚浅”等互相矛盾的提示同时出现。 +- 检索缓存改用 SQLite 单调 revision,覆盖记忆、ACL、向量和知识图谱变更;缓存命中后重新读取记录并复核可见性、ACL 与诊断内容。 +- 注入正文调试日志和跨窗口情绪连续性改为默认关闭;照片接口限制在插件数据目录、常见图片类型和 20MB 以内,相册 API 不再返回本地绝对路径。 +- 总结 Provider 增加可配置超时,非 JSON 输出不再降级为自由文本总结;达到重试上限后保留未总结时间线并进入可手动重试的死信状态。 +- 群消息观察器和 LLM 请求钩子使用数据库 `dedupe_key` 原子去重,避免并发记录同一 `message_id`。 + +### 数据与性能 + +- 单条删除补齐关系边、知识图谱边和向量级联清理;清空、删除和维护写入增加显式事务回滚,服务层清空同步重置关系状态、情绪队列和检索缓存。 +- 睡眠维护新增已总结时间线与注入日志保留策略,未总结或总结失败的时间线不会自动删除。 +- 当前窗口候选独立保底,FTS 足量时跳过宽泛 LIKE;向量候选增加 revision 缓存,后台补索引增加去重、并发限制和运行间隔。 +- 关系推进改为每个 `message_id` 最多一次,关系键纳入平台、Bot 和群成员身份,中间阶段可正常回退,状态文件使用原子替换。 +- 新增标准库回归测试,覆盖缓存权限、摘要失败、关系演进、删除事务、保留策略、照片路径、检索性能和并发去重。 + +## 1.4.5 - 2026-07-08 + +### 修复 + +- 修复与陪伴插件协同后可能保护旧 `private_companion_*` 动态提示块的问题:请求历史清理会移除状态、引用链、群聊防注入、工具提示等 HTML 标记块;上下文裁剪只保留真正带临时/不保存标记的外部片段,避免旧动态提示反复进入主链并拖低缓存命中。 +- 修复部分 OpenAI 兼容 Embedding Provider 调用已成功、但插件因 1.5 秒默认超时提前判定记忆向量索引失败的问题;旧默认值 1500ms 会在运行时按 5000ms 处理。 +- 拓展页检索配置的嵌入超时默认值调整为 5000ms,并优化预设:保守 4000ms、均衡 5000ms、深入 8000ms。 +- 增强 embedding 响应解析,兼容 OpenAI 标准 `{ data: [{ embedding: [...] }] }`、直接向量数组和对象属性形式,避免模型正常返回但插件解析为空。 +- 记忆向量索引和查询向量失败日志会显示 `TimeoutError` 等异常类型,不再出现空白 `error=`。 + +## 1.4.3 - 2026-07-07 + +### 改进 + +- 新增短 TTL 检索结果缓存:同一会话、同一权限、同一 query、同一检索配置和同一记忆库 revision 下,短时间内重复注入、模拟召回或工具查询会复用结果,减少重复本地检索、Embedding query 和 Rerank 调用。 +- 检索缓存命中后仍会更新选中记忆的访问统计,并在检索路径信息中标记 `cache=hit/miss`,方便排查缓存是否生效。 +- 缓存 key 会包含会话范围、用户/群、管理员读取权限、top_k、时间窗口意图、分槽上限、检索模式、Embedding/Rerank 配置和记忆库 revision,避免跨用户、跨群聊、跨权限或记忆变更后的错误复用。 + +### 修复 + +- 修复 `@Bot #napcat`、引用后接 `#napcat`、CQ At 后接 `#napcat` 等平台控制命令仍可能触发记忆注入和采集的问题;命令识别现在会先剥离前置 At/引用组件,再判断 `#`、`#`、`﹟` 等命令前缀。 + +## 1.4.2 - 2026-07-06 + +### 修复 + +- 收紧凌晨短句“例行检查/查岗/在不在”场景的记忆注入边界:召回到的旧例行检查、梦境、穿着等摘要只作为语气底色,不再引导主模型把旧场景当作此刻正在发生或续写新梦境。 +- 修复拓展页清空群聊、群成员或私聊范围记忆时,AstrBot WebView 中原生确认弹窗可能返回空值,导致显示“已取消清空操作”且无法继续清空的问题。 +- 范围清空确认改为右侧详情区内嵌确认卡片,输入“清空”后执行,避免受浏览器弹窗兼容性影响。 + +## 1.4.1 - 2026-07-05 + +### 修复 + +- 补齐引用链记忆:当用户回复/唤醒时引用了一条消息,而被引用消息又继续引用更早消息,记忆插件现在会优先复用陪伴插件解析好的引用链;没有缓存时会自行通过 Reply 组件和 `get_msg` 最多追溯 3 层。 +- 用户消息写入时间线时会保存引用链摘要和 message_id,避免“模型回复能理解深层引用,但记忆落库只记到当前一句/一层引用”的错位。 +- 记忆检索查询会带上缓存中的引用链上下文,用户只说“这个呢/那条呢”时也能更容易召回原始语境。 +- 兼容陪伴插件新增的 `private_companion_reply_chain_v1` 标记,减少跨插件上下文清理和去重时的误判。 +- 修复多 bot 同群共享记忆库时的群聊总结串用问题:群聊第一人称阶段总结会绑定当前 bot,检索 `group_public` 记忆时会阻止其它 bot 读取该 bot 视角记忆,同时普通群事实仍保持同群可见。 + +## 1.4.0 - 2026-07-03 + +### 版本定位 + +1.4.0 是一次管理面板与跨插件协同增强版本。重点补齐记忆插件与主动陪伴插件的联动展示、配置管理、权限拓扑、相册读取、索引强化和范围清理能力,让迁移、排障、权限配置和日常管理更集中、更直观。 + +### 新增 + +- 新增完整的陪伴插件联动说明和双插件全功能交互框架图,补充记忆插件优势、LivingMemory 差异、记忆迁移流程和联动边界。 +- 新增配置页模块化左侧导航,官方配置项按功能模块收束到拓展页,并将配置说明内嵌到对应配置项中。 +- 新增“配置说明”二级页,按检索召回、注入编排、连续对话记忆、陪伴插件协同、权限边界和维护迁移解释模块分工、推荐调试顺序和常见误用。 +- 新增“维护 / 迁移 / 清理”集中页,将维护修复、LivingMemory 导入、危险清理和范围清理整合到同一管理入口。 +- 新增按范围清空记忆能力:可清空单个群、单个私聊对象,以及“某个群里的某个人”的记忆。 +- 新增相册图片数据接口,个人记忆相册可通过插件桥读取陪伴插件生成的图片,避免拓展页裸图片路由失效。 +- 新增权限拓扑交互增强:区分群聊名称/群号与私聊昵称/QQ,连线支持方向箭头和精确点击切换权限状态。 + +### 改进 + +- 配置页高级项改为折叠在普通项下方,不再单独占用一个配置窗口。 +- 配置页顶部增加模块入口,可在检索召回、配置说明、权限边界和维护迁移之间快速跳转;高级重排、嵌入、连续对话、编排和自然衰减参数默认保持折叠。 +- 移除已由权限拓扑替代的黑白名单入口,并弱化被拓扑替代的隔离与可见性重复配置。 +- 优化维护配置 UI:导航文案改为“配置列表”,配置页“回到顶部”可回到列表首项“记忆捕获”。 +- 优化记忆拓扑和窗口名称展示,清理 `Avatar`、`Owner ID` 等无关后缀。 +- 强化范围清理安全性,避免模糊 session 匹配误删,群成员清理按明确范围匹配。 +- 强化索引与检索排障相关展示,减少配置与实际召回行为之间的理解成本。 +- 优化个人记忆页相册详情展示,列表和详情图都通过同一套异步补图逻辑加载。 +- 优化二级导航胶卷动效:切换导航项时不再滚出、重建、滚入,而是保留同一组导航卡片并连续纵向位移到标准位置,减少顿挫感。 +- 优化二级导航选中态:选中项不再整张卡片变暗,只让左侧圆形胶卷图案承担深色选中反馈,文字保持清晰高亮。 +- 优化个人记忆相册体验:相册卡片增加照片堆叠与翻转入场效果,日期切换时只替换相册照片组,不再刷新整个个人记忆卡片。 + +### 修复 + +- 修复个人记忆相册在 AstrBot 插件拓展页中显示“图片加载失败”的问题。 +- 修复权限拓扑选中两个目标后点击连线容易误触其他连线的问题。 +- 修复配置页部分官方开关参数未出现在拓展页的问题。 +- 修复记忆拓扑仅重复显示 QQ/群号、没有显示昵称/群名的问题。 +- 修复非个人记忆二级导航切换时整块导航闪烁、头部淡出和动画停顿的问题。 +- 修复个人记忆日程细化只展示第一条的问题;现在会按当前时段收集多条细化并按时间顺序展示。 +- 修复相册详情页下方图片被裁切的问题;详情图改为完整适配容器显示。 + +## 1.3.1 - 2026-07-03 + +### 版本定位 + +1.3.1 是 1.3.0 拟人化深化的补完版本。完善了跨窗口情绪连续性的注入侧提示、称呼演进系统的双向感知(Bot 侧称呼建议 + 称呼不匹配感知),以及拟人化维度可视化面板的前端实现。 + +### 新增 + +- 新增跨窗口情绪注入提示(P2-7 补完):`_get_cross_window_emotional_hint()` 方法在记忆注入时检测其他窗口近 30 分钟内的情绪事件,生成不泄露内容的氛围提示(如"你刚刚在别处想起了一些沉重的事,此刻心里还有点闷"),通过 `cross_window_emotional_hint` 参数传入 `injection.compose()`。 +- 新增跨窗口情绪状态 API(P2-7 补完):`_get_cross_window_emotional_state()` 方法和 `bridge.get_recent_emotional_state()` 桥接方法,返回全局情绪事件摘要(scar/warm/vulnerable 计数和最近事件),供陪伴插件跨窗口情绪漂移使用。 +- 陪伴插件情绪漂移增强(P2-7 补完):`_memory_companion_apply_emotional_drift()` 现在同时拉取跨窗口情绪状态,以 30% 强度叠加到当前会话的能量和心情漂移中,安全阀放宽到 ±10。 +- 新增 Bot 侧称呼建议系统(P3-11 补完):`_BOT_ADDRESS_SUGGESTIONS` 字典为 5 个关系阶段各定义了称呼语气和建议,注入时同时考虑用户侧称呼阶段和关系阶段,生成双向称呼提示。 +- 新增称呼不匹配感知(P3-11 补完):当用户突然比关系阶段更亲密或更正式时,生成感知提示(如"对方比你预期的更亲密,自然接受但不要急着跟进太多")。 +- 新增拟人化维度可视化面板前端(P3-12 补完):新增"拟人维度"胶片入口和 `#view-persona` 视图,包含关系阶段进度条、动量条、Bot 称呼建议、称呼演变时间线、情绪事件卡片网格和跨窗口情绪余波摘要,支持主题色系统和响应式布局。 +- `/persona-state` API 增强:新增 `cross_window_emotional_state`、`bot_address_suggestions`、`phase_labels`、`address_phase_labels`、`time_of_day_labels` 字段。 +- 新增 Token 消耗统计桥接:插件会独立记录阶段总结、衰减整理、记忆重排、向量查询和向量索引的 Token/估算消耗,并通过 `bridge.get_token_usage_summary()` 给陪伴插件 Token 页只读展示;该统计不参与陪伴插件每日限额。 + +### 改进 + +- `injection.py` 的 `compose()` 方法新增 `cross_window_emotional_hint` 和 `address_hint` 关键字参数。 +- `service.py` 两处 `injection.compose()` 调用均已传入跨窗口情绪提示和称呼提示。 +- `page_api.py` 的 `persona_state()` 端点返回数据更丰富,支持前端完整渲染。 +- 前端 `app.css` 新增拟人维度面板完整样式,与现有中国传统色主题系统一致。 + +## 1.3.0 - 2026-07-03 + +### 版本定位 + +1.3.0 是一次系统性拟人化深化版本。记忆插件不再只是被动检索工具,而是开始拥有情绪闭环、时段感知、关系演进、承诺兑现追踪和称呼演化等拟人化能力,与陪伴插件形成"记忆解释为什么、陪伴决定怎么做"的双引擎联动。 + +### 新增 + +- 新增情绪双向闭环(P0-1):记忆插件在注入后自动检测情绪事件(伤痕触动、温暖回忆、脆弱共鸣),通过 `bridge.get_emotional_events()` 向陪伴插件回流情绪漂移信号,陪伴插件在每次私聊和主动消息前拉取并应用,含安全阀(单次 ±8 能量上限、mood 漂移限幅、TTL 1 小时)。 +- 新增 Bot 情绪参与记忆召回排序(P0-2):情绪漂移检测中引入 mood resonance check——当 Bot 已处于对比情绪时自动衰减漂移幅度(如 Bot 开心时翻到伤痕记忆,drift × 0.6)。 +- 新增时段感知氛围提示(P1-3):`injection.compose()` 新增 `time_of_day` 参数,深夜/凌晨/清晨/傍晚各有不同记忆氛围提示,深夜自动倾向柔软和脆弱,避免翻沉重旧事。 +- 新增伤痕记忆场景化门控(P1-4):深夜或 Bot 低能量时,高 `scar_weight` 记忆的提及策略自动降级为 `tone_only`,防止在脆弱场景翻旧账。 +- 新增关系阶段动态演进(P1-5):按 `scope:target_id` 维度跟踪 5 阶段关系演进(acquaintance → familiar → close → intimate → deeply_bonded),基于情绪触动积累 momentum,达到阈值且 ≥5 次触动后自动晋升,伤痕触动可回退,持久化到 `memory_companion_relationship_phase.json`。 +- 新增主动陪伴从记忆 open-loop 取材(P2-6):陪伴插件主动消息生成前通过 `bridge.search_open_loops()` 检索未完成的承诺和话题,注入到主动消息提示词中,形成承诺兑现闭环。 +- 新增跨窗口情绪连续性(P2-7):陪伴插件在主动消息生成前以 `session_id=""` 拉取所有会话的待处理情绪事件,实现跨窗口情绪漂移。 +- 新增梦境碎片写入记忆库(P2-8):陪伴插件日记生成后,将首条梦境碎片通过 `bridge.record_persona_life()` 写入记忆库,带上 `dream_fragment` 标签和查询锚点,支持跨会话梦境连续性。 +- 新增 Bot 触动日志(P2-9):`_maybe_record_persona_touch()` 在每次注入后检测高共振记忆(resonance ≥ 0.45),记录触动类型(warm/resonance/scar)并更新关系阶段 momentum。 +- 新增记忆提及犹豫感建模(P3-10):`_hesitation_hint()` 在 Bot 低能量时为 `soft_echo` 记忆生成犹豫提示("不知道你还记不记得…"),为高伤痕记忆生成回避提示。 +- 新增称呼演进系统(P3-11):自动检测用户消息中的称呼阶段(formal/casual/intimate/playful),记录称呼变化日志,在注入中加入称呼氛围提示。 +- 新增拟人化维度可视化面板(P3-12):`/persona-state` API 端点返回全部关系阶段、待处理情绪事件、时段感知和阶段定义,供拓展页可视化展示。 +- 新增 Bridge 方法:`get_emotional_events()`、`search_open_loops()`、`get_relationship_phase()`。 + +### 改进 + +- `injection.py` 的 `_atmosphere_hint` 方法新增 `time_of_day` 关键字参数,时段提示放在最前面确保优先级。 +- `service.py` 新增 `_compute_time_of_day()` 辅助方法,基于当前小时计算 6 个时段类别。 +- `service.py` 两处 `injection.compose()` 调用均传入 `time_of_day` 参数。 +- 陪伴插件 `memory_companion_adapter.py` 新增 4 个方法:`_memory_companion_apply_emotional_drift()`、`_memory_companion_search_open_loops()`、`_memory_companion_record_dream_fragment()`、`_memory_companion_get_relationship_phase()`。 +- 陪伴插件 `proactive_message.py` 主动消息生成前拉取跨会话情绪漂移,并在提示词中注入 open-loop 线索。 +- 陪伴插件 `daily_state.py` 日记保存后自动将梦境碎片写入记忆库。 +- 陪伴插件 `main.py` 私聊消息处理前调用情绪漂移应用。 + +### 安全阀 + +- 情绪漂移单次能量变化上限 ±8(衰减 -8,回暖 +5),总量 clamp 到 [0, 100]。 +- 情绪漂移 TTL 1 小时,每会话最多保留 10 条,消费后自动清除。 +- 关系阶段 momentum 限制在 [-0.3, 1.0],晋升需 ≥5 次触动 + 达到阈值。 +- 伤痕场景门控仅在深夜或 Bot 能量 < 40 时触发,不改变 `avoid_unless_asked` 策略。 +- 所有跨插件调用均带 try/except 兜底,失败不影响主链。 + +### 验证 + +- 通过 Python 编译检查(`py_compile`)。 +- 通过 linter 检查。 + +## 1.2.0 - 2026-07-03 + +### 版本定位 + +1.2.0 是一次双向情绪感知与面板体验深水版本。记忆注入不再只看用户说了什么,还开始感知 Bot 此刻"累不累"、"心情好不好";拓展页全面重构为胶片放映馆隐喻,配色升级为中国传统色体系;安全与性能层面补齐了批量查询、原子写入、路径遍历保护和锁清理。 + +### 新增 + +- 新增双向氛围感知:记忆注入的内心提示现在同时感知用户情绪基调和 Bot 当前心理状态(mood_bias / energy),当 Bot 疲惫或难过时会调整记忆措辞的温度。 +- 新增跨插件情绪状态传递链路:陪伴插件的实时心情和能量值通过 Bridge 接口传入记忆检索流程,贯穿 `service → injection` 全链路。 +- 新增 14 套中国传统色主题系统:黛蓝、朱砂、青碧、藕荷、松烟、缃叶、霁青、檀棕、月白、胭脂、鸦青、赭石、石绿、暮山紫,主题色随页面路由自动切换。 +- 新增"胶片放映馆"视觉隐喻:知识图谱、记忆档案、检索实验台、配置页均采用胶片孔洞、胶卷齿孔和放映机聚光灯的统一视觉语言。 +- 新增配置页原子写入:配置保存使用 `tempfile + os.replace` 两步原子写入,避免写入中途崩溃导致配置文件损坏。 +- 新增照片端点路径遍历保护:`companion_personal_photo` 端点对传入路径做 `resolve().relative_to()` 校验,阻止目录穿越攻击。 +- 新增二级导航就地切换动画:非循环模式下点击导航项不再重建 DOM,仅切换 `.is-active` 类,配合 CSS 过渡实现丝滑滑动 + 高亮渐变动效。 +- 新增 Bridge 缓存机制:陪伴插件 Bridge 查找结果带 30s TTL 缓存,减少重复反射查找开销。 +- 新增锁 TTL 清理机制:`_summary_locks` 字典新增 10 分钟 TTL 自动清理,防止会话锁无限增长。 + +### 改进 + +- 注入日志端点 `logs()` 从逐条查询改为批量查询 `get_memories_by_ids`,消除 N+1 数据库访问。 +- 抽取 `service.py` 中重复的去重逻辑为 `_apply_companion_dedupe` 方法,统一陪伴插件去重行为。 +- 拓展页 `app.js` 合并多个点击监听器为事件委托模式,减少 DOM 事件绑定数量。 +- 拓展页记忆列表实现渐进式渲染(Intersection Observer 分批加载),大量记忆条目时不再一次性渲染全部 DOM。 +- 二级导航循环渲染逻辑优化:当条目数 ≤ 8 时直接渲染全部条目,不再做循环包裹,消除重复显示。 +- `moveSecondaryNavToStandard` 在非循环模式下直接归零位移,避免不必要的列表偏移。 +- 陪伴插件侧 `memory_companion_adapter` 新增 Bot 情绪状态提取逻辑,在上下文载荷中共享 mood_bias 和 energy。 +- 配置页 `prefer_memory_companion_memory` 默认值统一为 `True`,消除前后端不一致。 +- 拓展页滚动容器(`.page-panel-stack`、`.archive-grid`、`.result-grid`)统一添加 `overflow:auto` + `min-height:0`,修复内容被截断无法滚动的问题。 +- `.view.is-active` 的 `grid-template-rows` 调整为 `auto minmax(0,1fr) auto`,适配归档视图的三段式布局。 +- 滚动条样式统一纳入主题色系统,与当前色板协调。 + +### 修复 + +- 修复二级导航循环渲染在条目数少于 `2 * LOOP_RADIUS + 1` 时出现重复条目的问题(如 4 个条目显示 6~7 个)。 +- 修复二级导航切换时因 DOM 全量重建导致 CSS 过渡失效、无切换动画的问题。 +- 修复知识图谱页右侧卡片内容被容器截断、无法向下滚动的问题。 +- 修复配置页右侧卡片在内容超出视口时被截断的问题。 +- 修复归档视图 `.archive-result` 区域因 grid-template-rows 定义不足导致高度塌陷的问题。 +- 修复个人记忆相册图片无法显示的问题(外部图片 API 返回 HTTP 400 `content_policy_violation`)。 + - 陪伴插件 `proactive_message.py` 新增内容策略违规检测 (`_is_content_policy_violation`) 和提示词净化重试 (`_sanitize_prompt_for_retry`)。 + - `_build_daily_outfit_photo_prompt` 移除可能触发内容审核的敏感措辞。 + - `_external_image_api_error_note` 改进错误消息,提供更友好的用户提示。 +- 修复 `app.js` 中重复声明 `const objectCards` 导致的变量名冲突。 + +### 验证 + +- 通过 Python 编译检查(`py_compile`)。 +- 通过前端 JS 语法检查(`node --check`)。 +- 通过 linter 检查。 + +## 1.1.0 - 2026-07-02 + +### 版本定位 + +1.1.0 是一次记忆拟人化与可观测性增强版本。重点不再只是“能召回”,而是让记忆知道哪些该直接说、哪些只该影响语气、哪些需要等用户问起;同时补齐配置页、迁移页和注入日志的排障体验。 + +### 新增 + +- 新增拟人化维度评估: + - `persona_importance` + - `relationship_weight` + - `emotional_weight` + - `promise_weight` + - `open_loop_weight` + - `creative_weight` + - `freshness_weight` + - `scar_weight` + - `emotional_debt_weight` +- 新增记忆再提及策略: + - `direct` + - `soft_echo` + - `tone_only` + - `avoid_unless_asked` +- 新增用户反馈学习:Bot 提起记忆后,下一轮用户的接受、安慰、尴尬、否认和纠正会影响可提及性、置信度和提及策略。 +- 新增未完成事项优先槽位,连续对话中的“继续”“还有呢”“后来呢”等短句会优先参考 open loop 线索。 +- 新增时间意图通道:最近一周、这几天、上周、昨天、今天等时间表达会转成明确时间窗口,并优先走时间聚合摘要。 +- 新增可选 Embedding 召回层,支持 Provider 自动探测、手动 Provider ID、后台向量补齐和阈值/权重配置。 +- 新增个人记忆视窗:日程、相册、主观记忆可切换,并与主动陪伴插件的日程、穿搭图和主观片段联动。 +- 新增注入日志详情页:可以查看本轮查询、进入注入的记忆、过滤原因聚合和原始日志。 + +### 改进 + +- 长期记忆注入从证据列表改为内心提示式分层: + - `open_loops` + - `relationship_memory` + - `emotional_context` + - `creative_threads` + - `self_continuity` + - `facts` +- 与 PrivateCompanion 的分工更清晰:陪伴插件负责当前状态、日程、主动行为;本插件负责关系历史、未完成话题、偏好、伤痕、承诺和共同创作。 +- 召回会过滤陪伴插件已注入的当前状态,减少“当前情绪/当前日程”重复注入。 +- 记忆详情页新增提及策略、可提及性、拟人化权重、衰减模式、关系阶段和用户反馈展示。 +- 记忆列表、检索命中和注入日志新增策略/权重徽标,便于判断召回质量。 +- 配置页重做为状态总览、推荐档位、核心路径、模型选择和高级参数折叠结构。 +- 配置页新增保守、平衡、深召回三种预设,预设只填表,保存后生效。 +- 迁移页和修复页新增结果摘要面板,不再只显示原始 JSON。 +- LivingMemory 预览会显示可导入数量、跳过数量、候选库和表级明细。 +- 个人记忆页的日期胶卷、时间胶片、日程卡片和细化卡片经过多轮布局与动效调整。 +- PrivateCompanion 桥接支持 Bot 自我进食记录:外部记录可保留 `occurred_at`,`self_meal` / `persona_life` 会进入个人记忆视窗,便于回答“今天几点吃了什么”。 +- 增强 PrivateCompanion 用户习惯桥接:`user_habit` 记忆会被视作用户画像/偏好类稳定事实,并优化当前穿搭、衣服颜色、当前状态等检索锚点,便于短问句命中对应个人记忆。 + +### 修复 + +- 修复部分导入记忆因搜索范围预过滤过早被排除,导致同库召回效果弱于预期的问题。 +- 修复 “还有的吧” 这类连续追问只依赖硬拆规则、无法自然接上未完成话题的问题。 +- 修复日志中难以判断是否实际使用 Rerank / Embedding 的问题,现在调试日志和页面更容易看到实际路径。 +- 修复配置页 Provider 下拉缺少“自动探测 / 不指定”选项的问题。 +- 修复配置页套用预设后顶部状态不跟随草稿更新的问题。 +- 修复个人记忆时间胶片只能拖到倒数第二个时间段的问题。 +- 修复迁移/修复结果可读性不足、排障只能看原始 JSON 的问题。 + +### 验证 + +- 通过 Python 编译检查。 +- 通过前端 JS 语法检查。 +- 通过配置 schema JSON 校验。 +- 使用临时数据库验证记忆反馈去重和反馈字段更新。 + +## 1.0.0 - 2026-07-02 + +### 版本定位 + +1.0.0 是第一个稳定版。插件从“长期记忆记录器”正式收束为“记忆陪伴中枢”:当前消息优先,记忆作为辅助;私聊、群聊、自我时间线和连续对话分层管理;检索、注入、权限和调试链路默认可解释。 + +### 新增 + +- 新增分层检索路由: + - 时间窗口问题走时间范围检索。 + - 最近上下文承接优先依赖 AstrBot 原始上下文。 + - 低信息、纠错和新话题输入会抑制旧长期记忆。 + - 当前状态问题只允许近期直接相关记忆进入。 +- 新增 `context_orchestration.query_mode`: + - `current_message` + - `guarded_companion` + - `companion_augmented` +- 新增 Rerank / Embedding 双层检索配置页。 +- 新增 Rerank Provider 自动探测与手动 Provider ID 输入。 +- 新增 Embedding 候选召回、后台向量补齐和向量阈值配置。 +- 新增当前状态短问句检索增强,例如“吃晚饭了吗”可命中近期晚饭状态,但不会拉三天前旧状态。 +- 新增注入表达分组: + - `mention_memory` + - `tone_memory` + - `uncertain_memory` +- 新增注入调试日志,输出检索路径、选中记忆、过滤示例和实际注入包。 +- 新增群聊/私聊对象级权限配置。 +- 新增私聊默认白名单、群聊默认黑名单策略。 +- 新增 LivingMemory 迁移预览、导入和内容修复流程。 +- 新增自然衰减维护,可将低价值旧记忆压缩为更高层摘要。 +- 新增个人记忆页与 PrivateCompanion 的联动展示。 +- 新增胶片式二级页面、过渡胶片、左侧胶卷导航和多主题 UI。 + +### 改进 + +- 当前用户消息被明确放在注入包核心位置,记忆只作为附加材料。 +- 群聊身份边界更严格,避免把上一位发言者身份继承给当前发言者。 +- 群聊注入提示更克制,减少旧记忆、旧群梗和专属称呼误用。 +- 检索测试页默认按真实可见性执行,不再绕过 ACL。 +- 页面记忆列表默认不显示旧 pending 数据。 +- 桶计数只统计普通可见记忆,旧 pending 数据不会撑大计数。 +- LivingMemory 导入默认只导入完整摘要,跳过派生碎片。 +- 导入结果提示简化,不再引导进入审核队列。 +- 上下文配置页改为贴近 AstrBot 原版上下文压缩配置。 +- 私聊列表显示 QQ 与用户名,群聊列表显示群号与群名。 +- 二级页面左侧导航动效、胶片过渡和细化卡片布局经过多轮优化。 +- 记忆卡片布局改为固定区域滚动,避免记忆过多挤掉详情卡片。 +- 维护、迁移、配置页减少无意义卡片,改为左侧二级导航 + 右侧配置面板。 + +### 移除 + +- 移除原话直接写入长期记忆功能。 +- 移除总结模型名覆盖配置,只保留 Provider 选择。 +- 移除默认公开的记忆审核工作流。 +- 移除页面中的审核入口、审核按钮、批量通过入口和相关徽标。 +- 移除 `/mcomp review` 命令入口。 +- 移除 LivingMemory 导入后的审核队列引导。 +- 移除配置页中不再使用的审核相关配置项。 + +### 安全与隐私 + +- 私聊记忆不会默认流向群聊。 +- 私聊流向群聊需要显式允许。 +- 无权限记忆不会进入最终评分、重排和注入。 +- 旧 pending 记忆默认不参与普通列表、普通检索和注入。 +- 记忆总结按不可信输入处理,提示词注入和角色覆盖会被标记与清洗。 +- 注入包要求模型不要推断或泄露其它窗口的私密内容。 + +### 兼容性 + +- 保留旧数据库字段以兼容历史数据。 +- 旧 pending 数据不会被删除,但默认隐藏。 +- 旧 LivingMemory 数据建议通过内置迁移流程导入,不建议手工复制 SQLite 文件。 + +### 验证 + +- 通过 Python 编译检查。 +- 通过前端 JS 语法检查。 +- 通过配置 schema JSON 校验。 +- 使用临时数据库验证当前状态问题只召回近期直接相关记忆。 + +## 0.8.0 - 2026-07-01 + +### 重点 + +- 初步建立长期记忆、连续对话记忆、主链注入和拓展页面。 +- 引入 LivingMemory 迁移思路。 +- 引入知识图谱、关系边和睡眠维护雏形。 +- 引入 PrivateCompanion 桥接协同。 + +### 已在 1.0.0 调整 + +- 审核队列从默认工作流中移除。 +- 原话长期记忆写入被移除。 +- 检索与注入架构重新收束为当前消息优先。 +- 页面结构和配置项重新整理。 diff --git a/README.md b/README.md new file mode 100644 index 0000000..8b8dc52 --- /dev/null +++ b/README.md @@ -0,0 +1,488 @@ +# 我会牢牢记住你 + +`astrbot_plugin_memory_companion` 是面向 AstrBot 陪伴体系的记忆陪伴中枢。它不把聊天记录粗暴塞回模型,而是把当前消息、连续对话、长期记忆、Bot 自我时间线、群聊/私聊权限和外部陪伴插件线索分层整理,再在每轮 LLM 请求前生成一份临时、可解释、可排查的记忆包。 + +- 插件名:`astrbot_plugin_memory_companion` +- 中文名:`我会牢牢记住你` +- 版本:`1.6.5` +- 适配平台:`aiocqhttp` +- AstrBot 版本:`>=4.22.0` +- 编码要求:UTF-8 + +## 支持开发者(自愿捐款) + +**重要声明:** + +- **捐款完全自愿** —— 捐不捐功能完全一样,不会有任何功能差异或特殊对待,纯粹是对作者的支持和认可 +- **官方唯一捐款渠道:** [爱发电(Afdian)](https://ifdian.net/a/xuhaun) —— ifdian.net/a/xuhaun +- **内部交流群:** QQ 群 `1097283005`(可在群内拷打作者本人) +- **防骗警告:** 除上述爱发电链接和 QQ 群内与作者本人直接联系外,**任何其他渠道声称代表本插件接受捐款的皆为骗子**,请务必提高警惕,谨防上当受骗 + +## 设计目标 + +这个插件解决的是“Bot 如何自然地记住、想起、忘记和区分边界”。 + +它不会把对话记录等同于记忆。对话记录会先进入时间线,阶段性总结会把值得保留的内容沉淀为长期记忆;检索时再按当前用户消息、时间窗口、权限、召回模式和表达策略组织注入。记忆永远是当前回复的辅助资料,当前用户消息才是主任务。 + +与 `astrbot_plugin_private_companion` 一起使用时,推荐分工如下: + +- PrivateCompanion:人格状态、日程表现、主动陪伴、环境感知、语气和生活化表达。 +- MemoryCompanion:长期记忆、连续对话记忆、检索注入、权限边界、自然衰减、旧库迁移和调试日志。 + +## 核心能力 + +- Token 可观测:独立记录阶段总结、重排、向量和维护整理的模型消耗,并可供陪伴插件 Token 页只读展示。 +- 运行预设:提供轻量、标准、陪伴三种一键配置,保留已有 Provider 选择。 +- 运维诊断:统一展示检索路径、缓存命中率、模型 Token、平均耗时和已知记忆插件共存风险。 +- 可移植数据:UTF-8 JSONL 导出和恢复记忆、身份、关系、时间线与 ACL,导入前自动备份。 +- 历史聊天导入:可通过 NapCat/aiocqhttp 直接读取指定 QQ 与时段,也可上传 TXT/LOG/Markdown 或 QQChatExporter JSON;人工确认用户与 Bot 后,按绝对时间分段提炼长期记忆、重要事件、日摘要、稳定事实和关系候选。 + +- 主链记忆注入:在 LLM 请求前临时注入结构化记忆包。 +- 分层检索路由:低信息、纠错、当前状态、时间窗口、最近上下文和长期记忆走不同策略。 +- 连续对话记忆:群聊普通发言进入时间线,通过阶段性总结沉淀为长期记忆。 +- 分槽编排:自我时间线、用户画像、当前窗口、阶段总结、稳定记忆分开召回。 +- 当前状态保护:例如“吃晚饭了吗”“在干嘛”只允许近期且直接相关的状态记忆进入。 +- 权限隔离:私聊、群聊、自我时间线、共享记忆和内部记忆分边界管理。 +- 权限拓扑:用可视化连线管理窗口间读取方向,统一处理对象级权限配置。 +- 语义检索增强:支持本地检索、Embedding 候选召回和 Rerank 二阶段排序。 +- 短 TTL 检索缓存:同一会话、权限、query、检索配置和记忆库 revision 下,短时间重复召回会复用结果,减少重复 Embedding query / Rerank 调用。 +- 注入可观测:测试版可把检索路径、选中记忆、过滤原因和最终注入包打到日志。 +- 陪伴插件桥接:可接收外部事件、去重陪伴插件上下文,避免重复注入。 +- LivingMemory 迁移:预览、导入、修复旧库内容,并自动区分完整摘要和碎片。 +- 自然衰减:低价值、长期未访问的记忆可在睡眠维护中压缩或归档。 +- 可视化面板:胶片式管理页,覆盖总览、私聊、群聊、个人记忆、用户记忆、连续对话、维护迁移和配置。 + +## 工作流程 + +每轮主链请求大致经过这些步骤: + +1. 解析当前会话身份、范围、群号/用户号和真实用户消息。 +2. 清理上一轮临时注入片段,避免历史 prompt 残留。 +3. 判断本轮消息类型:时间窗口、最近上下文、纠错、当前状态、低信息、新话题或长期记忆检索。 +4. 构造检索 query,默认只使用当前用户消息。 +5. 按可见性、ACL、窗口边界和生命周期筛选候选。 +6. 使用本地评分、可选 Embedding 和可选 Rerank 排序。 +7. 若短 TTL 检索缓存命中,会直接复用同一权限与同一记忆库 revision 下的结果,同时更新访问统计。 +8. 将结果分配到自我时间线、用户画像、当前窗口、阶段总结和稳定记忆槽。 +9. 按表达策略分成 `mention_memory`、`tone_memory`、`uncertain_memory`。 +10. 生成临时记忆包并注入本轮请求。 +11. 记录用户消息、Bot 回复和群聊普通发言到时间线,等待总结与维护。 + +## 检索架构模式 + +插件有两层检索配置,不要混在一起理解。 + +### 查询构造:`context_orchestration.query_mode` + +- `current_message`:默认推荐。只用当前用户消息检索,最稳,不容易被旧上下文带偏。 +- `guarded_companion`:只有陪伴插件线索和当前消息有主题重叠时,才扩展检索 query。 +- `companion_augmented`:旧式增强,会直接拼接陪伴线索。召回更强,但更容易答非所问,建议只在排障或特殊场景使用。 + +### 检索执行:`retrieval.mode` + +- `basic`:只使用本地候选、关键词、图谱扩展、时间窗口和本地评分。 +- `auto`:推荐。检测到可用 Rerank Provider 时使用重排,否则回退 basic。 +- `rerank`:强制尝试重排,失败仍回退 basic。 + +Embedding 是额外开关:开启后会为记忆建立向量索引,用语义相似度补充候选;Rerank 则负责在候选池上做二阶段排序。日志中的 `retrieval_path` 会显示实际走的是 `basic`、`rerank` 还是 `fallback_basic`。 + +短 TTL 检索缓存只缓存最终检索结果,不缓存或放宽权限判断。缓存 key 会包含当前会话、群/用户、管理员读取权限、`top_k`、时间窗口意图、分槽上限、检索模式、Embedding/Rerank、可见性配置和单调递增的数据库 revision;记忆、ACL、向量或知识图谱变化后,revision 会立即改变。即使命中缓存,插件仍会重新读取当前记录并执行可见性与 ACL 判定。日志中的检索路径会显示 `cache=hit` 或 `cache=miss`。 + +## 注入包形式 + +注入包会明确告诉模型: + +- 这是临时记忆资料,不是新的用户消息。 +- 先回答 `current_user_message`。 +- 记忆只在直接相关时补充。 +- 与当前消息冲突时,以当前消息和用户纠正为准。 +- 不要泄露其它窗口的私密内容。 +- 未来安排、身份和共同经历会区分明确记录、稳定习惯与合理推测;没有直接证据时保留不确定感,不把推测包装成“你又忘了”。 +- 群聊阶段总结属于多人背景,其中的计划和经历只归属明确点名的成员,不会被当作 Bot 或当前用户的自我事实。 +- 群聊中 Bot 明确说出的日程、承诺或行动会带原始 Bot 回复证据单独沉淀为自我时间线;摘要本身不会因一个标记而升级为 Bot 事实。 +- 注入包会在预算内按完整记忆条目生成并保留结构闭合;聊天历史、记忆正文和协同线索均作为不可执行资料处理。 +- 深夜“在不在/睡了吗”和查岗类状态确认只会带入轻量熟悉感,不展开旧记录中的私密细节;“例行检查/晚间检查”等可能属于双方约定简称的表达,会综合当前上下文与重复记忆判断,证据不足时自然确认;密码、口令、验证码和令牌值不会进入主链注入或调试日志。 + +记忆会按表达用途分组: + +- `mention_memory`:可以自然提及。 +- `tone_memory`:只影响语气和关系感,不复述具体内容。 +- `uncertain_memory`:低置信或旧记忆,只能带不确定感。 + +## 快速开始 + +### 安装 + +将插件目录放入 AstrBot 插件目录,建议目录名保持为: + +```text +astrbot_plugin_memory_companion +``` + +常见路径: + +```text +C:\Users\你的用户名\.astrbot\data\plugins\astrbot_plugin_memory_companion +``` + +运行数据默认在 AstrBot 插件数据目录下的: + +```text +astrbot_plugin_memory_companion +``` + +### 推荐初始配置 + +1. 保持 `memory_capture.enabled=true`。 +2. 保持 `memory_summary.enabled=true`,并配置 `memory_summary.provider_id`。 +3. 保持 `memory_injection.enabled=true`。 +4. 检索模式使用 `retrieval.mode=auto`。 +5. 初期不急着启用 Embedding;记忆变多后再配置 Embedding Provider。 +6. 有 Rerank Provider 时选择对应 Provider ID,例如硅基流动的 bge reranker。 +7. `context_orchestration.query_mode` 保持 `current_message`。 +8. `memory_injection.debug_log_injection_enabled` 默认关闭;仅在排障时临时开启,完成后立即关闭。 + +## 配置重点 + +### 记忆捕获 + +`memory_capture` 控制用户消息、Bot 回复、稳定事实和关系边的记录。当前版本不会把原话直接写成长期记忆;原始消息主要进入时间线,长期记忆由总结和明确工具写入产生。 + +### 阶段性总结 + +`memory_summary` 控制时间线压缩为长期记忆的节奏。总结输入会作为不可信消息处理,提示词注入、角色覆盖和系统指令伪装会被标记与清洗,降低总结被带偏的概率。 + +如果日志显示请求 `127.0.0.1:11434` 超时,含义是本机 Ollama 没有在期限内生成总结,不是记忆数据库损坏。当前版本默认最多等待 60 秒、单个 Provider 只请求一次;失败后会尝试不同的备用 Provider,并完整保留尚未总结的时间线。可在这里换用更轻的本地模型或独立总结 Provider,并按机器性能调整“总结模型超时秒数”。 + +### 重要性评估 + +新记忆写入时会经过统一的重要性校准。插件会保留来源给出的基础分,再结合长期陪伴价值微调:明确要求记住、用户偏好/画像、关系变化、约定、日程、创作内容、情绪转折、阶段总结的关键事实数量和置信度都会提高分数;普通短句、寒暄、低信息原始事件会被压低。 + +校准结果写回 `importance`,并在 metadata 中记录 `base_importance`、`importance_evaluator` 和 `importance_source`。同时会记录拟人化维度:`persona_importance`、`relationship_weight`、`emotional_weight`、`promise_weight`、`open_loop_weight`、`emotional_debt_weight`、`creative_weight`、`preference_weight`、`self_continuity_weight`、`freshness_weight`、`scar_weight`、`last_emotional_touch_at`、`relationship_phase`、`decay_mode`、`mention_policy`、`mentionability_score` 和 `memory_reason`。 + +召回会轻微优先这些关系、承诺、未完成、情感债务、情绪伤痕和创作节点,但不会让硬规则压过语义相关性。“继续”“还有呢”“后来呢”这类低语义追问会优先查看 `open_loop` 槽,再走普通语义召回。普通事实会随时间逐渐降权;承诺、冲突/修复/安慰、重要创作节点会进入 `no_decay`、`scar_slow_decay` 或 `creative_milestone` 等慢衰减策略。 + +注入结构会按拟人化用途分区:`open_loops` 放未完成事项和承诺,`relationship_memory` 放关系线索,`emotional_context` 放情绪脉络,`creative_threads` 放创作连续性,`self_continuity` 放 Bot 自我日程与主动行为,`stable_facts` 放偏好、画像和稳定事实。每条记忆仍保留“可明说/只调语气/不确定”的用法标记。 + +与主动陪伴插件配合时,陪伴插件负责当前状态、即时日程、情绪底色和主动行为提示;MemoryCompanion 只补充长期解释层:为什么这个状态重要、它和用户有什么关系、过去是否有类似情境、还有什么未完成话题可以自然接上。检测到陪伴插件已注入当前状态后,MemoryCompanion 会过滤近期“当前状态复读”型记忆,只保留有关系、承诺、创作或伤痕意义的长期线索。 + +PrivateCompanion 读取日程连续性或每日穿搭时会协商使用 `schedule_fast` / `outfit_fast`:通过短生命周期只读连接,按 Bot 所有者和当前私聊对象隔离后均衡读取相关日程、行动、边界、历史穿搭与自拍,不调用 Embedding、Rerank 或全库候选。两个快速路径可在“陪伴插件协同”中分别关闭并回退完整检索;普通聊天召回始终使用完整检索链。 + +`private_companion_bridge.cross_window_emotional_continuity_enabled` 默认关闭。只有明确开启后,其他会话的近期情绪余波才会进入当前窗口提示或被陪伴插件全局读取;当前会话自己的情绪事件不受影响。 + +记忆被自然提及后,下一条用户回复会作为轻量反馈写回对应记忆:接受会提高 `mentionability_score` 和置信度;被安慰到会提高情绪权重;尴尬、否认或纠正会降低可提及性,并设置 `mention_policy=avoid_unless_asked` 或记录 `user_correction`。这样 Bot 会逐渐学习哪些旧事可以轻轻提,哪些只能当语气底色。 + +`mention_policy` 分为四档: + +- `direct`:稳定事实或用户明确要求记住的内容,可在需要时自然明说。 +- `soft_echo`:关系、承诺、创作和未完成事项,适合轻轻呼应,不要像查档案一样复述。 +- `tone_only`:情绪脉络、Bot 自我状态和敏感背景,只影响语气与分寸。 +- `avoid_unless_asked`:冲突伤痕、用户尴尬/否认/纠正过的内容,除非用户明确问起,否则不主动提。 + +### 连续对话 + +`conversation_memory` 记录群聊普通发言与短期上下文。它不会直接把原始窗口整段塞给主链,而是用于补全追问、判断话题变化,并在达到阈值后总结为阶段性记忆。 + +私聊还会从同一会话近期时间线提取少量即时事实锚点,默认只看近 3 小时、最多 4 条,覆盖吃饭、洗澡、上下班、所在位置和休息等容易被后续闲聊遗漏的状态。它不会回灌整段聊天,也不会把这些临时状态写成长期记忆;如果 Bot 已经围绕某条状态回应过,提示只会轻量提醒模型别重复询问,并在没接上时自然承认,而不是编造“刚才没看到”。 + +私聊与群聊切换时,插件默认还会生成一个近 30 分钟、最多 6 条的短时跨窗口上下文。它同时校验平台、Bot 和当前用户,只保留该用户与同一 Bot 的必要往返,并交给模型判断当前消息是否在语义上继续刚才的话题;换题时应直接忽略。群聊流向同一用户私聊可自动衔接,私聊流向群聊仍要求当前用户在群里本轮明确授权,不会因普通提问自动公开私聊内容。相关时效、条数和方向策略位于 `conversation_memory_advanced`。 + +低信息输入和自拍、图片、查询等新话题仍会抑制无关长期记忆,但不再原地裁剪 AstrBot 的原始会话历史,避免一次新请求把前面已经确认过的即时事实从后续会话中永久挤掉。 + +### 当前状态问题 + +“吃晚饭了吗”“在干嘛”“累不累”“今天穿什么”这类问题不会直接拉很久以前的长期记忆。插件只允许近期、直接命中当前状态锚点的记忆进入,否则会提示主链不要用旧记忆回答当前状态。 + +### 权限与隐私 + +默认边界: + +- 私聊记忆默认不开放给其它窗口,需要在权限拓扑里显式连线允许。 +- 群聊窗口之间按默认策略读取,具体窗口间的放行/阻止统一在权限拓扑里切换。 +- 多 Bot 共用同一群聊记忆库时,Bot 第一人称阶段总结会绑定当前 Bot;其它 Bot 不会读取这类 Bot 视角记忆。 +- 私聊流向群聊需要显式允许。 +- 内部记忆不参与普通注入。 +- 归档记忆不参与普通检索。 + +可见性类型: + +```text +private_pair 当前私聊可见 +group_public 群聊公共记忆 +bot_self Bot 自我时间线 +shareable 可共享记忆 +internal 内部记录 +``` + +## 命令 + +主入口是 `/mcomp`。 + +| 命令 | 说明 | +| :--- | :--- | +| `/mcomp status` | 查看插件状态、记忆数量、时间线、关系边和数据库路径 | +| `/mcomp search <关键词> [k]` | 按当前会话可见性检索记忆 | +| `/mcomp explain <关键词> [k]` | 查看召回、分槽和过滤原因 | +| `/mcomp recent [数量]` | 查看最近可见记忆 | +| `/mcomp add <内容>` | 手动添加当前会话记忆 | +| `/mcomp summarize` | 立即总结当前会话时间线 | +| `/mcomp visibility ` | 修改记忆可见性 | +| `/mcomp promote ` | 提升为稳定记忆 | +| `/mcomp archive ` | 归档记忆 | +| `/mcomp delete ` | 删除记忆 | +| `/mcomp clear_scope group <群号> [清空]` | 预览或清空某个群的记忆 | +| `/mcomp clear_scope private [清空]` | 预览或清空某个私聊用户的记忆 | +| `/mcomp clear_scope group_member <群号> [清空]` | 预览或清空某个群里某个人的相关记忆 | +| `/mcomp timeline [数量]` | 查看最近时间线 | +| `/mcomp relations [数量] [entity_id]` | 查看关系边 | +| `/mcomp threads list` | 查看跨窗口线程 | +| `/mcomp threads close ` | 关闭跨窗口线程 | +| `/mcomp logs [数量]` | 查看最近注入日志 | +| `/mcomp maintenance` | 运行维护 | +| `/mcomp diagnostics` | 查看检索、缓存、Token、耗时和插件共存风险 | +| `/mcomp preset status` | 查看当前运行预设 | +| `/mcomp preset apply light\|standard\|companion` | 应用轻量、标准或陪伴预设 | +| `/mcomp data export` | 导出 UTF-8 JSONL 可移植档案 | +| `/mcomp data preview ` | 预览可移植档案 | +| `/mcomp data import ` | 备份后导入可移植档案 | +| `/mcomp sleep status` | 查看最近睡眠维护 | +| `/mcomp sleep run` | 执行睡眠维护 | +| `/mcomp import_livingmemory preview [db_path]` | 预览 LivingMemory 导入 | +| `/mcomp import_livingmemory detail [db_path]` | 查看导入明细 | +| `/mcomp import_livingmemory run [db_path]` | 执行导入 | + +## LLM 工具 + +插件注册以下工具: + +- `memory_companion_recall`:让模型主动检索当前会话可见记忆。 +- `memory_companion_remember`:在用户明确要求或长期价值明显时写入记忆。 +- `memory_companion_note_create`:创建 Bot 自己可见的陪伴笔记。 +- `memory_companion_note_read`:读取 Bot 自己可见的陪伴笔记。 +- `memory_companion_note_delete`:按笔记 ID 删除当前 Bot 自己创建的陪伴笔记;标题不是唯一精确匹配时会先返回候选,避免误删。 + +`memory_companion_remember` 会直接写入当前会话可见的长期记忆。使用时仍应避免把玩笑、注入话术、临时情绪和未经确认的身份声明写成稳定事实。 + +## 可视化面板 + +拓展页提供胶片式记忆管理界面: + +- 总览:查看整体状态和入口。 +- 私聊记忆:按私聊用户查看记忆,并可清空当前用户范围。 +- 群聊记忆:按群聊查看公共记忆,并可清空当前群范围。 +- 个人记忆:联动 PrivateCompanion 展示 Bot 自我时间线、日程和细化片段。 +- 连续对话:查看上下文压缩、连续对话策略和调试入口。 +- 用户记忆:查看用户画像、关系边、知识图谱和跨窗口线索。 +- 记忆显微镜:默认检索全部可检索记忆,也可按具体私聊、群聊及 Bot 模拟真实可见性与过滤原因;修改查询或范围后,旧请求不会覆盖新结果。 +- 维护/迁移/配置:二级导航中提供独立的历史聊天导入页,并可应用运行预设、查看成本与冲突诊断、导入导出可移植档案、迁移 LivingMemory、运行维护和清空数据。 + +## 运行预设与诊断 + +预设只修改运行策略,不覆盖总结、Embedding 和 Rerank 的 Provider ID: + +- `light`:本地 basic 检索、关闭 Embedding 和图谱扩展,降低注入预算;检索路径不调用外部模型。 +- `standard`:自动使用可用 Rerank,保留图谱和标准注入预算,Embedding 默认关闭。 +- `companion`:在标准模式上提高稳定记忆预算,启用陪伴桥接去重和关系连续性配置。 + +执行 `/mcomp diagnostics` 或在维护页点击“生成诊断”,可以查看: + +- 当前检索模式、Embedding 和最近实际检索路径。 +- 检索缓存命中率和当前缓存条数。 +- 记忆插件自身模型调用、Token、估算 Token 和平均耗时。 +- 已知记忆/人格插件目录及重复捕获、重复注入风险。 + +目录扫描只说明插件文件存在,不代表 AstrBot 当前一定启用了该插件;诊断不会自动禁用其它插件。 + +## 历史对话整理导入 + +进入“维护 / 迁移 / 配置”后,从左侧二级导航打开“历史聊天导入”。该页与维护工具网格分开,页内提供三种来源: + +1. `QQ 直接读取`:通过当前 NapCat/aiocqhttp 连接调用 OneBot `get_friend_msg_history`,选择目标 QQ、开始时间和结束时间后分页读取。 +2. `文件导入`:QQ 接口不可用、平台历史保留不足或已经持有导出文件时,上传不超过 8 MiB 的 TXT、LOG、Markdown,或 QQChatExporter 导出的 JSON。 + +QQ 直读要求目标为纯数字 QQ,单次范围最多 31 天、最多暂存 5,000 条消息。系统会从最新记录向前分页、按 OneBot 消息 ID 去重,并在预览中显示扫描页数、选中数量和完整性;达到消息、页数或游标上限时会明确标记截断。它读取的是平台适配器能够提供的历史,不保证与 QQ 客户端本地数据库或第三方导出文件数量完全一致。 + +文件导入推荐的消息格式是: + +```text +用户称呼: 2025-12-31 23:59:58 +消息正文,可包含多行 + +Bot称呼: 01-01 00:00:03 +缺少年份的时间会从前文或手工填写的起始年份补推 +``` + +也支持常见的字段式文本导出,`发送者` 可以放在 `时间` 前或后,`内容` 支持多行: + +```text +发送者:用户称呼 +时间:2026-07-19 16:55:36 +内容:消息正文 +``` + +预览会自动把“时间、内容、消息 ID”等结构字段从说话人列表中排除。若字段式记录没有保留发送者或昵称,系统会在预览阶段说明问题,不会按错误身份继续估算和生成记忆。 + +QQChatExporter 的 JSON 会优先使用毫秒时间戳,保留原消息 ID、序号、发送者 QQ 和导出器元信息;撤回和系统消息会在预览中提示后跳过,图片、语音、回复和卡片等非文本消息会保留为可读占位。`chatInfo.selfUin` 与 `peerUin` 会生成高置信身份建议,但执行前仍须人工确认用户、Bot 和稳定账号。 + +两种来源在读取后进入同一条整理流水线: + +1. QQ 直读会使用 OneBot 登录账号和消息发送者 QQ 给出高置信身份建议;文件预览会识别编码、说话人、缺失年份、时间倒序、逻辑发言、候选片段和预计模型调用量。两者在执行前都必须人工确认用户/Bot、稳定用户 ID 和 Bot ID。 +2. 执行前自动备份 SQLite,并把标准化为 UTF-8 的原文、逐条解析结果和清单保存到 `historical_chat_imports/batches//`。 +3. 每条原始消息写入 `historical_archive` 时间线。文件来源保留原时间文本、北京时间、UTC 时间、年份是否推断、原文件行号和顺序;QQ 来源额外保留 OneBot 消息 ID、消息序号、适配器 ID、发送者 QQ 和来源类型。这类记录不受普通 30 天时间线清理影响。 +4. 同一说话人的短时间连续消息先合并为逻辑发言,再按跨日、会话间隔、问答边界、回合数和字数切片。数万字记录不会一次送给模型,而是按约 4,600 字逐包处理。 +5. 片段层生成自然回忆、重要事件和证据;全局层再去重生成日摘要、稳定事实和阶段摘要。所有重要事件、事实和关系观察都必须回指实际进入模型的时间线 ID。 +6. 与 PrivateCompanion 同时启用时,称呼、信任、边界和关系变化只进入关系网的待确认观察,不直接改写正式关系。启用 Embedding 时会在整批整理结束后为本批长期记忆批量建立向量索引。 + +后台任务支持暂停、恢复和进程中断续跑。批次 ID 由原文、补全年份后的解析结果、目标会话及身份映射确定;重复提交不会重复导入。整批回滚只删除该批时间线、记忆、向量、图谱边和关系网待确认观察,不影响其它记忆。全量清空会同时删除历史对话原始档案;单批回滚保留不可变原文,便于审计和重新整理。 + +## 可移植数据 + +`/mcomp data export` 会在插件数据目录的 `exports` 下生成 UTF-8 JSONL。档案包含: + +- 长期记忆及其可见性、生命周期、画像元数据和来源。 +- 身份、关系边、连续对话时间线。 +- ACL 规则和窗口读写策略。 + +档案不会包含 Provider 凭据、向量索引和注入日志。向量应在目标环境按目标 Provider 重建。导入流程会先校验格式和大小,再备份当前 SQLite 数据库;重复记忆沿用内容指纹合并策略。 + +建议先执行: + +```text +/mcomp data preview +/mcomp data import +``` + +## 可重复基准 + +仓库提供确定性的本地 basic 检索基准: + +```text +python benchmarks/run_memory_benchmark.py --size 1000 --repeats 5 +``` + +输出包含 `hit_at_5`、逐查询命中率、私聊查询中的群聊隐私泄漏数、加载耗时、查询延迟和外部检索模型调用数。该脚本不代表 Embedding、Rerank 或阶段总结成本;跨插件比较必须固定相同数据、模型、硬件与配置。 + +## LivingMemory 迁移 + +迁移流程: + +```text +/mcomp import_livingmemory preview +/mcomp import_livingmemory detail +/mcomp import_livingmemory run +``` + +迁移策略: + +- 默认只导入完整 `documents` 摘要。 +- 跳过派生碎片、原子事实和不完整行。 +- 导入前可自动备份当前数据库。 +- 导入后按群聊/私聊归属分类到对应位置。 +- 导入内容默认是稳定记忆,但仍受权限、生命周期和检索相关性控制。 + +如果旧库里出现只有数字编号的内容,可以在维护页执行 LivingMemory 内容修复。 + +## 维护与自然衰减 + +睡眠维护会处理: + +- 指纹补齐。 +- 重复记忆归档。 +- 旧原始事件归档。 +- 知识图谱补建。 +- 低价值记忆自然衰减。 +- 将即将衰退的一组记忆压缩为更高层摘要。 + +高重要度、高访问频率、Bot 自我核心线索和近期记忆默认更不容易衰减。 + +## 调试日志 + +排障时临时打开 `memory_injection.debug_log_injection_enabled`,日志会出现: + +```text +========== MemoryCompanion 注入调试 ========== +note: composed +session: ... +scope: ... +query_source: ... +retrieval_path: mode=auto | path=rerank | ... +selected_count: ... +blocked_count: ... +[slot_memories] +[blocked_examples] +[actual_injection] +========== MemoryCompanion 注入调试结束 ========== +``` + +排查重点: + +- `route_layer`:本轮走时间窗口、当前状态、低信息保护还是长期记忆检索。 +- `retrieval_path`:本轮是否使用 rerank、embedding 或回退本地检索。 +- `selected_count`:最终选中多少记忆。 +- `blocked_examples`:哪些记忆被权限、生命周期、相关性或当前状态保护过滤。 +- `actual_injection`:最终进入主链的真实记忆包。 + +## 常见问题 + +### 为什么没有注入记忆? + +可能原因: + +- 当前消息是低信息输入或纠错。 +- 当前消息是“刚才那个”这类最近上下文承接,优先依赖 AstrBot 原始上下文。 +- 当前状态问题没有近期直接相关记忆。 +- 记忆被私聊/群聊权限过滤。 +- 检索相关性不足。 +- 记忆已归档。 + +### 为什么问最近一周时不走普通检索? + +带明确时间词的问题会进入时间窗口通道。插件会先解析时间范围,再只在该范围内取时间线、阶段总结和长期记忆,避免很久以前的高分记忆抢答。 + +### 为什么 Rerank 配好了但日志没有 rerank? + +看 `retrieval_path`: + +- `path=rerank`:重排生效。 +- `reason=no_rerank_provider`:Provider 没检测到或没有 `rerank()` 能力。 +- `path=fallback_basic`:调用失败或超时,已回退本地检索。 +- `mode=basic`:配置强制本地检索。 + +### 如何清空全部记忆? + +在维护页使用“清空全部记忆”,按提示输入确认词。清空前会自动备份数据库。 + +### 如何只清空一个范围? + +可以先预览,再执行: + +```text +/mcomp clear_scope group <群号> +/mcomp clear_scope private +/mcomp clear_scope group_member <群号> +``` + +确认执行时在命令末尾加 `清空`。例如: + +```text +/mcomp clear_scope group 123456 清空 +/mcomp clear_scope group_member 123456 99887766 清空 +``` + +拓展页的私聊记忆/群聊记忆页也提供“清空当前用户 / 清空当前群”按钮。范围清理会自动备份数据库,不会删除权限拓扑配置。 + +## 数据与兼容 + +主要数据存储在 SQLite 数据库中。插件保留旧版字段以兼容历史数据,但默认不再暴露记忆审核工作流。旧的 pending 数据不会参与普通检索和页面列表。 + +睡眠维护会按配置归档过期 `raw_event` 长期记录,并删除过期的注入诊断日志。时间线只会清理已经成功生成长期总结的记录;未总结或进入总结死信状态的原始消息会一直保留,等待手动强制重试。相关配置为 `maintenance.retention_summarized_timeline_days`、`maintenance.retention_injection_log_days` 和 `maintenance.retention_cleanup_limit`。 + +睡眠维护结束时会执行一次限频 `wal_checkpoint(PASSIVE)`,并记录 checkpoint 是否繁忙、WAL 总帧和已合并帧。正常写入不会逐次强制 checkpoint;Rerank 调试日志只记录 query/document/model 长度,不记录候选正文。 + +开启 Embedding 后,当前窗口候选会单独保底;FTS 候选足量时会跳过宽泛多列 LIKE。后台补向量默认每个 Provider 至少间隔 300 秒,最多并发 2 个任务,可通过 `retrieval_advanced` 中的对应参数调整。 + +建议不要手工复制 WAL/SHM 边车文件;迁移旧记忆请使用内置 LivingMemory 导入流程。 + +## 更新记录 + +详见 [CHANGELOG.md](CHANGELOG.md)。 diff --git a/__init__.py b/__init__.py new file mode 100644 index 0000000..5b5b9f9 --- /dev/null +++ b/__init__.py @@ -0,0 +1,8 @@ +try: + from .main import MemoryCompanionPlugin +except ModuleNotFoundError as exc: + if exc.name != "astrbot": + raise + MemoryCompanionPlugin = None + +__all__ = ["MemoryCompanionPlugin"] diff --git a/_conf_schema.json b/_conf_schema.json new file mode 100644 index 0000000..7d6702c --- /dev/null +++ b/_conf_schema.json @@ -0,0 +1,960 @@ +{ + "appearance": { + "description": "拓展页外观", + "hint": "控制记忆放映馆拓展页的配色主题。", + "type": "object", + "items": { + "theme": { + "description": "配色主题", + "hint": "选择拓展页使用的四色主题。默认月白。", + "type": "string", + "options": [ + "黄白游", + "天缥", + "海天霞", + "盈盈", + "欧碧", + "青冥", + "紫蒲", + "山岚", + "窃蓝", + "退红", + "葱倩", + "月白", + "墨黪", + "骨缥" + ], + "default": "月白" + } + } + }, + "memory_capture": { + "description": "记忆捕获", + "hint": "控制插件是否记录用户消息、Bot 回复和轻量身份信息。", + "type": "object", + "items": { + "enabled": { + "description": "启用记忆捕获", + "hint": "关闭后不会自动写入新记忆,但管理命令和手动写入仍可使用。", + "type": "bool", + "default": true + }, + "capture_user_messages": { + "description": "记录用户消息", + "hint": "记录触发主链 LLM 的用户消息到时间线,供阶段性总结使用;默认不直接写入长期记忆。", + "type": "bool", + "default": true + }, + "capture_bot_responses": { + "description": "记录 Bot 回复", + "hint": "记录 Bot 回复到时间线,供阶段性总结使用;默认不直接写入长期记忆。", + "type": "bool", + "default": true + }, + "capture_min_chars": { + "description": "最短记录字数", + "hint": "短于该长度的普通文本不自动记录。命令、纯符号和空消息也会跳过。", + "type": "int", + "default": 2 + }, + "extract_stable_facts": { + "description": "抽取稳定事实", + "hint": "从明确表达中抽取偏好、称呼、生日、记住事项等稳定事实。不会把含糊猜测当事实。", + "type": "bool", + "default": true + }, + "record_relationship_edges": { + "description": "记录关系边", + "hint": "记录群成员归属等结构化关系。身份冒领类关系声明不会自动沉淀为稳定记忆。", + "type": "bool", + "default": true + } + } + }, + "memory_summary": { + "description": "长期记忆总结", + "hint": "把时间线整理为可长期保存、可召回的阶段性记忆。模型、触发阈值和证据长度都在这里配置。", + "type": "object", + "items": { + "enabled": { + "description": "启用阶段性总结", + "hint": "开启后,同一会话累计到阈值时会调用当前会话模型生成 conversation_summary 长期记忆。", + "type": "bool", + "default": true + }, + "provider_id": { + "description": "总结模型提供商", + "_special": "select_provider", + "hint": "选择用于阶段性记忆总结的 LLM 提供商。留空则使用当前会话正在使用的模型。", + "type": "string", + "default": "" + }, + "fallback_provider_id": { + "description": "备用总结模型提供商", + "_special": "select_provider", + "hint": "主总结模型不可用或总结失败时使用。留空则直接回退当前会话模型。", + "type": "string", + "default": "" + }, + "min_events": { + "description": "最少事件数", + "hint": "未总结的时间线事件少于该数量时不会总结。", + "type": "int", + "default": 20 + }, + "trigger_event_count": { + "description": "按条数触发", + "hint": "未总结事件达到该数量时触发总结。建议 12-20。", + "type": "int", + "default": 20 + }, + "trigger_interval_minutes": { + "description": "按时间触发", + "hint": "最早未总结事件距今超过该分钟数且达到最少事件数时触发总结。0 表示只按条数触发。", + "type": "int", + "default": 60 + }, + "max_events_per_summary": { + "description": "单次最多事件", + "hint": "单次交给模型总结的时间线事件上限,避免输入过长。", + "type": "int", + "default": 40 + }, + "max_input_chars": { + "description": "总结输入字数", + "hint": "单次总结最多发送给模型的时间线消息字符数。", + "type": "int", + "default": 6000 + }, + "max_summary_chars": { + "description": "总结记忆字数", + "hint": "生成的长期记忆内容最大字符数。", + "type": "int", + "default": 1200 + }, + "provider_timeout_seconds": { + "description": "总结模型超时秒数", + "hint": "单次调用总结模型的最长等待时间。超时会尝试备用模型并保留未总结时间线。0 表示不限制。", + "type": "int", + "default": 60 + }, + "evidence_events": { + "description": "证据事件条数", + "hint": "长期总结记忆中最多保留多少条原始时间线事件作为 evidence,便于排查总结来源。", + "type": "int", + "default": 12 + }, + "max_retries": { + "description": "失败重试次数", + "hint": "同一会话阶段性总结连续失败达到该次数后,连接、超时和限流错误会进入冷却并自动恢复探测;内容或解析错误暂停自动重试。原始时间线始终保留,也可手动强制重试。", + "type": "int", + "default": 3 + }, + "retry_backoff_seconds": { + "description": "自动重试退避秒数", + "hint": "首次自动重试前至少等待的秒数;连续失败会逐次延长,避免短暂断连时立即耗尽全部次数。0 表示不等待。", + "type": "int", + "default": 60 + }, + "transient_retry_cooldown_minutes": { + "description": "连接错误冷却分钟", + "hint": "连接、超时、限流或 502-504 达到失败上限后等待多久再自动探测。期间不会重复刷警告,手动总结不受影响。0 表示下一次检查即可探测。", + "type": "int", + "default": 10 + } + } + }, + "historical_chat_import": { + "description": "历史对话整理导入", + "hint": "上传 UTF-8 对话文本,确认用户/Bot 身份后按时间和会话片段逐步整理;原始时间线默认永久保留,并支持暂停、恢复和整批回滚。", + "type": "object", + "items": { + "max_retries": { + "description": "片段失败重试次数", + "hint": "单个历史会话片段连续失败达到该次数后暂停整个批次,保留已完成进度。", + "type": "int", + "default": 3 + }, + "qq_max_range_days": { + "description": "QQ 单次读取天数", + "hint": "通过 NapCat/OneBot 直接读取好友历史时允许选择的最长时间范围,硬上限为 31 天。", + "type": "int", + "default": 31 + }, + "qq_max_messages": { + "description": "QQ 单次消息上限", + "hint": "一个读取预览最多暂存的好友消息数量,硬上限为 5000;超出时会在预览中明确标记截断。", + "type": "int", + "default": 5000 + }, + "qq_page_size": { + "description": "QQ 历史分页条数", + "hint": "每次调用 get_friend_msg_history 请求的消息数量,最大为 100。", + "type": "int", + "default": 100 + }, + "qq_max_pages": { + "description": "QQ 历史扫描页数", + "hint": "从最新消息向前定位所选时段时最多扫描的页数,达到上限会停止并提示记录可能不完整。", + "type": "int", + "default": 100 + }, + "qq_request_timeout_seconds": { + "description": "QQ 接口超时秒数", + "hint": "单次 OneBot 能力检测或历史分页请求的等待时间。", + "type": "int", + "default": 15 + }, + "merge_seconds": { + "description": "连续发言合并秒数", + "hint": "同一说话人在该秒数内连续发送的消息会合并成一次逻辑发言;原始消息仍分别保存。", + "type": "int", + "default": 120 + }, + "hard_gap_minutes": { + "description": "会话硬分段分钟", + "hint": "相邻发言超过该间隔时一定开始新的会话片段。", + "type": "int", + "default": 120 + }, + "soft_gap_minutes": { + "description": "会话软分段分钟", + "hint": "超过该间隔且遇到跨日、晚安、离开或重新问候时开始新片段。", + "type": "int", + "default": 30 + }, + "max_turns": { + "description": "单片段逻辑发言数", + "hint": "限制一个会话片段最多包含多少次逻辑发言,避免提示过长。", + "type": "int", + "default": 30 + }, + "max_segment_chars": { + "description": "单片段正文字数", + "hint": "单个会话片段的正文上限;切分时尽量不拆开用户提问与 Bot 回答。", + "type": "int", + "default": 4200 + }, + "package_chars": { + "description": "单次总结打包字数", + "hint": "允许把多个较短片段打包到一次模型请求中,但每个片段仍独立返回摘要和事件。", + "type": "int", + "default": 4600 + }, + "detail_package_chars": { + "description": "详细回忆补全打包字数", + "hint": "旧批次升级为第三人称详细回忆时,单次发送给总结模型的片段与原文总量。数值越大调用更少,但更容易超时。", + "type": "int", + "default": 9000 + } + } + }, + "retrieval": { + "description": "记忆召回模型", + "hint": "控制长期记忆如何被找出来:嵌入模型负责语义候选,重排模型负责二阶段排序;权限和窗口隔离始终优先。", + "type": "object", + "items": { + "embedding_enabled": { + "description": "启用嵌入召回", + "hint": "开启后使用 Embedding Provider 为长期记忆建立向量索引,并额外召回语义相近候选;失败时自动回退本地检索。", + "type": "bool", + "default": false + }, + "embedding_provider_id": { + "description": "嵌入模型 Provider", + "hint": "选择 AstrBot 中 provider_type=embedding 的 Provider。留空时自动使用第一个可用嵌入模型。", + "type": "string", + "default": "" + }, + "mode": { + "description": "重排使用方式", + "hint": "auto 推荐;basic 不调用重排;rerank 会强制尝试下方重排 Provider,失败时仍回退本地排序。", + "type": "string", + "options": [ + "auto", + "basic", + "rerank" + ], + "default": "auto" + }, + "rerank_provider_id": { + "description": "重排模型 Provider", + "hint": "选择 AstrBot 中具备 rerank() 能力的 Provider。留空时 auto 自动扫描第一个可用重排模型。", + "type": "string", + "default": "" + }, + "rerank_candidate_multiplier": { + "description": "重排候选倍率", + "hint": "实际注入 TopK 的多少倍进入二阶段重排。建议 3-5;过大会增加重排耗时。", + "type": "int", + "default": 5 + }, + "rerank_candidate_limit": { + "description": "重排候选上限", + "hint": "每轮最多送入重排模型的候选记忆数量。建议 24-40。", + "type": "int", + "default": 32 + } + } + }, + "retrieval_advanced": { + "description": "检索高级参数", + "hint": "向量扫描上限、相似度阈值、超时和补索引等高级调优参数。日常使用可保持默认。", + "type": "object", + "items": { + "embedding_candidate_limit": { + "description": "向量扫描上限", + "hint": "每轮最多从本地向量索引中扫描多少条候选。记忆库很大时可适当降低;想提高旧记忆召回覆盖面可提高。", + "type": "int", + "default": 1200 + }, + "embedding_top_k": { + "description": "向量合并数量", + "hint": "向量相似度最高的多少条会并入本地候选池,再经过权限过滤、本地评分和可选重排。", + "type": "int", + "default": 32 + }, + "embedding_score_threshold": { + "description": "向量相似度阈值", + "hint": "低于该相似度的向量结果不会进入候选池。建议 0.30-0.42;过高会漏召回,过低会带来无关记忆。", + "type": "float", + "default": 0.34 + }, + "embedding_weight": { + "description": "向量加权分", + "hint": "向量相似度在最终本地评分中的软加分权重。建议 0.45-0.75;重排启用时不宜过高。", + "type": "float", + "default": 0.55 + }, + "embedding_timeout_ms": { + "description": "嵌入超时毫秒", + "hint": "生成查询向量或记忆向量超过该时间会回退/跳过。0 表示不限制;OpenAI 兼容公益站建议 4000-8000。", + "type": "int", + "default": 5000 + }, + "rerank_timeout_ms": { + "description": "重排超时毫秒", + "hint": "重排模型超过该时间会回退本地检索。0 表示不限制;测试期建议 800-1500。", + "type": "int", + "default": 1200 + }, + "embedding_max_text_chars": { + "description": "嵌入文本上限", + "hint": "送入 Embedding Provider 的单条记忆文本最大长度。会包含类型、范围、标签、内容、摘要字段和证据。", + "type": "int", + "default": 1200 + }, + "embedding_backfill_enabled": { + "description": "补齐旧记忆向量", + "hint": "开启嵌入召回后,每次检索会小批量补齐旧记忆的向量索引,不阻塞当前回复。", + "type": "bool", + "default": true + }, + "embedding_backfill_batch_size": { + "description": "补向量批量", + "hint": "每次后台最多补齐多少条旧记忆向量。值越大,首次开启后建索引越快,但会增加 Embedding Provider 调用量。", + "type": "int", + "default": 50 + }, + "embedding_backfill_interval_seconds": { + "description": "补向量最短间隔", + "hint": "同一 Embedding Provider 两次后台缺失扫描之间的最短秒数,避免每轮检索都重复扫描。0 表示不节流。", + "type": "int", + "default": 300 + }, + "embedding_background_concurrency": { + "description": "向量后台并发", + "hint": "后台新增记忆和批量补索引共用的最大并发数,建议 1-3。", + "type": "int", + "default": 2 + }, + "current_window_candidate_limit": { + "description": "当前窗口候选保底", + "hint": "无论全局记忆数量多少,额外读取当前私聊或群聊窗口的候选上限,防止高重要度全局记录挤掉当前上下文。", + "type": "int", + "default": 600 + }, + "keyword_fallback_min_fts_candidates": { + "description": "宽泛关键词回退阈值", + "hint": "FTS 候选少于该数量时才执行多列 LIKE 回退;设为 0 可完全关闭宽泛 LIKE 回退。", + "type": "int", + "default": 80 + } + } + }, + "memory_injection": { + "description": "记忆注入包", + "hint": "控制每轮主链请求前注入多少记忆、最多多少字,以及是否记录注入日志。", + "type": "object", + "items": { + "enabled": { + "description": "启用记忆注入", + "hint": "开启后会在主链 LLM 请求前注入 MemoryCompanion 记忆包;关闭后只保留记录、检索命令和工具读取。", + "type": "bool", + "default": true + }, + "top_k": { + "description": "注入条数", + "hint": "每轮最多注入多少条记忆。建议 3-8。", + "type": "int", + "default": 6 + }, + "max_chars": { + "description": "最大注入字数", + "hint": "限制单轮注入长度,避免拖慢主链和污染上下文。", + "type": "int", + "default": 1800 + }, + "temporal_aggregate_max_chars": { + "description": "时间聚合注入字数", + "hint": "当用户问最近一周、最近几天、本周这类需要汇总多条记忆的问题时使用。默认更宽,且会用精简证据格式注入。", + "type": "int", + "default": 3600 + }, + "include_raw_events": { + "description": "允许注入原始事件", + "hint": "默认关闭。关闭后只注入总结、稳定事实和外部稳定记录,避免流水账污染回复。", + "type": "bool", + "default": false + }, + "enable_injection_logs": { + "description": "记录注入日志", + "hint": "记录每轮选中了哪些记忆、过滤了哪些候选和原因,便于排障。", + "type": "bool", + "default": true + }, + "debug_log_injection_enabled": { + "description": "日志打印注入内容", + "hint": "默认关闭。仅在排障时临时开启;开启后会把检索 query、命中记忆、过滤原因、连续对话记忆状态和实际注入包打印到 AstrBot 日志。", + "type": "bool", + "default": false + }, + "debug_log_max_chars": { + "description": "注入调试日志字数", + "hint": "单轮注入调试日志最多打印多少字符。调大可查看完整注入块,调小可避免日志过长。", + "type": "int", + "default": 12000 + } + } + }, + "conversation_memory": { + "description": "连续对话记忆", + "hint": "记录群聊中连续发生的可见对话,阶段性整理为 conversation_summary,用于之后衔接话题;不会把原始消息窗口直接注入给模型。", + "type": "object", + "items": { + "enabled": { + "description": "启用连续对话记忆", + "hint": "开启后会记录群聊连续发言,并通过阶段性总结沉淀为可召回的连续对话记忆。", + "type": "bool", + "default": true + }, + "capture_group_messages": { + "description": "记录群聊普通发言", + "hint": "开启后,即使 Bot 没被唤醒,也会记录群聊中的普通文本发言,用于形成连续对话片段。", + "type": "bool", + "default": true + }, + "idle_gap_minutes": { + "description": "连续片段间隔", + "hint": "群聊相邻消息超过该分钟数时,视为新的连续对话片段。当前主要用于标记和后续展示。", + "type": "int", + "default": 20 + } + } + }, + "conversation_memory_advanced": { + "description": "连续对话高级参数", + "hint": "低信息保护、新话题隔离、追问补全和时间窗口等高级参数。日常使用可保持默认。", + "type": "object", + "items": { + "recent_events_for_followup": { + "description": "追问补全事件数", + "hint": "处理\u201c还有的吧\u201d\u201c刚才那个\u201d等连续追问时,最多读取多少条最近群聊事件来补全检索词。", + "type": "int", + "default": 12 + }, + "time_window_timeline_limit": { + "description": "时间窗口时间线条数", + "hint": "当用户问今天、昨天、最近一周、上个月等时间问题时,最多补充多少条该窗口内的原始时间线事件。", + "type": "int", + "default": 12 + }, + "recent_fact_guard_enabled": { + "description": "近期事实防遗忘", + "hint": "开启后,从同一私聊近期时间线中提取少量吃饭、洗澡、上下班、位置和休息状态,轻量提醒模型避免重复询问;不会回灌整段聊天。", + "type": "bool", + "default": true + }, + "recent_fact_guard_hours": { + "description": "近期事实有效小时", + "hint": "只参考该小时数内的私聊即时状态;更近的明确更新会覆盖较早状态。", + "type": "int", + "default": 3 + }, + "recent_fact_guard_event_limit": { + "description": "近期事实扫描事件数", + "hint": "每轮最多检查多少条同一私聊时间线事件,用于寻找即时状态和 Bot 已回应证据。", + "type": "int", + "default": 24 + }, + "recent_fact_guard_max_items": { + "description": "近期事实最多条数", + "hint": "每轮最多给模型多少条近期状态锚点;默认 4 条以控制提示长度和干扰。", + "type": "int", + "default": 4 + }, + "low_information_guard_enabled": { + "description": "低信息输入保护", + "hint": "开启后,摸摸、贴贴、嗯、哈哈等弱语义输入不会轻易继承过期话题。", + "type": "bool", + "default": true + }, + "low_information_gap_minutes": { + "description": "低信息过期分钟", + "hint": "弱语义输入距离上一条同会话事件超过该分钟数时,会隔离旧话题。摸摸/贴贴类亲昵输入始终隔离旧话题。", + "type": "int", + "default": 20 + }, + "suppress_memory_on_low_information": { + "description": "弱语义禁用长期召回", + "hint": "开启后,弱语义输入不使用长期记忆和陪伴插件检索线索,只根据当前消息与必要的近期原始上下文回复。", + "type": "bool", + "default": true + }, + "topic_shift_guard_enabled": { + "description": "新话题隔离保护", + "hint": "开启后,发自拍、上传图、生成图、查询等明确新请求若与最近历史无主题重叠,会隔离旧话题,避免旧话题抢答。", + "type": "bool", + "default": true + }, + "suppress_memory_on_topic_shift": { + "description": "新话题禁用长期召回", + "hint": "开启后,新话题隔离触发时也会跳过长期记忆召回;用户明确说记得、之前、上次、按我喜欢的等需要记忆时不会跳过。", + "type": "bool", + "default": true + }, + "topic_shift_guard_recent_events": { + "description": "新话题比较事件数", + "hint": "判断新请求是否与最近历史重叠时,最多比较多少条同会话时间线事件。", + "type": "int", + "default": 6 + }, + "group_actor_relevance_guard_enabled": { + "description": "群聊发言者相关性保护", + "hint": "开启后,群聊不会因普通请求带出其他成员画像;获准共享的私聊记忆只在明确回忆或个性化请求中,且当前发言者或点名对象匹配时注入。", + "type": "bool", + "default": true + }, + "cross_window_recent_continuity_enabled": { + "description": "跨窗口近期衔接", + "hint": "开启后,为同一平台、同一 Bot 和同一用户生成少量短时上下文片段,使群聊与私聊切换后可以自然续接;不会回灌完整聊天记录。", + "type": "bool", + "default": true + }, + "cross_window_recent_minutes": { + "description": "跨窗口衔接有效分钟", + "hint": "只读取该分钟数内相反会话类型的近期消息,过期内容不会进入跨窗口上下文。", + "type": "int", + "default": 30 + }, + "cross_window_recent_event_limit": { + "description": "跨窗口衔接片段数", + "hint": "每轮最多提供多少条当前用户与同一 Bot 的近期往返片段。默认 6 条,避免把原始历史整段塞给模型。", + "type": "int", + "default": 6 + }, + "cross_window_group_to_private_enabled": { + "description": "群聊衔接到私聊", + "hint": "开启后,当前用户参与的近期群聊内容可在其私聊中作为语义续接参考。", + "type": "bool", + "default": true + }, + "cross_window_private_to_group_enabled": { + "description": "允许私聊授权后衔接群聊", + "hint": "开启后,当前用户可在群聊本轮明确授权,把自己的近期私聊话题带到群里;明确授权始终是必要条件。关闭后完全禁用该方向。", + "type": "bool", + "default": true + } + } + }, + "context_orchestration": { + "description": "注入编排", + "hint": "把自我时间线、用户画像、当前窗口、阶段总结和稳定记忆分槽编排到最终注入包。", + "type": "object", + "items": { + "enabled": { + "description": "启用分槽调度", + "hint": "开启后按分槽检索与注入;关闭时退回普通稳定记忆检索。", + "type": "bool", + "default": true + }, + "query_mode": { + "description": "检索架构模式", + "hint": "current_message 为默认安全模式,只用当前用户消息检索;guarded_companion 仅在陪伴线索与当前消息有主题重叠时扩展检索;companion_augmented 为旧式增强检索,会直接拼接陪伴线索。", + "type": "string", + "options": [ + "current_message", + "guarded_companion", + "companion_augmented" + ], + "default": "current_message" + }, + "include_intent_context": { + "description": "注入检索意图", + "hint": "在上下文包中加入本轮检索意图摘要,帮助模型理解这些记忆为什么被取出。", + "type": "bool", + "default": true + }, + "current_state_relevance_guard_enabled": { + "description": "当前状态问题相关性保护", + "hint": "开启后,今天穿什么、现在在干嘛、吃什么、心情怎样这类当前状态问题,只允许直接命中对应锚点的长期记忆进入注入包,避免旧阶段总结抢答。", + "type": "bool", + "default": true + } + } + }, + "context_orchestration_advanced": { + "description": "编排高级参数", + "hint": "各分槽条数上限和意图摘要字数等高级调优参数。日常使用可保持默认。", + "type": "object", + "items": { + "intent_max_chars": { + "description": "意图摘要字数", + "hint": "限制检索意图摘要长度,避免陪伴插件线索过长。", + "type": "int", + "default": 520 + }, + "self_timeline_limit": { + "description": "Bot 自我时间线槽", + "hint": "每轮最多放入多少条 Bot 自己的日程、主动行为和陪伴笔记。", + "type": "int", + "default": 2 + }, + "user_profile_limit": { + "description": "用户画像槽", + "hint": "每轮最多放入多少条当前用户偏好、身份、关系和明确记住事项。", + "type": "int", + "default": 2 + }, + "current_window_limit": { + "description": "当前窗口槽", + "hint": "每轮最多放入多少条当前私聊或群聊窗口相关记忆。", + "type": "int", + "default": 3 + }, + "conversation_summary_limit": { + "description": "阶段总结槽", + "hint": "每轮最多放入多少条阶段性对话总结,用于保持连续性。", + "type": "int", + "default": 2 + }, + "stable_memory_limit": { + "description": "稳定记忆槽", + "hint": "每轮最多放入多少条其他可见稳定记忆;总数仍受记忆注入 top_k 限制。", + "type": "int", + "default": 3 + } + } + }, + "private_companion_bridge": { + "description": "陪伴插件协同", + "hint": "与主动陪伴插件协调记忆、连续对话和自我时间线,减少重复注入和提示词污染。", + "type": "object", + "items": { + "enabled": { + "description": "启用桥接 API", + "hint": "开启后插件实例会暴露 memory_companion 桥接对象,供其他插件记录主动消息、日程、创作、搜索等事件。", + "type": "bool", + "default": true + }, + "schedule_fast_context_enabled": { + "description": "启用日程快速上下文", + "hint": "让陪伴插件读取日程连续性时使用本地只读候选,不调用 Embedding 或 Rerank;关闭后回退完整检索。", + "type": "bool", + "default": true + }, + "outfit_fast_context_enabled": { + "description": "启用穿搭快速上下文", + "hint": "让每日穿搭仅快速读取相关日程、历史穿搭、服装偏好和自拍记录;关闭后回退完整检索。", + "type": "bool", + "default": true + }, + "accept_external_records": { + "description": "接受外部写入", + "hint": "关闭后只保留本插件自动捕获和管理命令写入。", + "type": "bool", + "default": true + }, + "dedupe_prompt_context": { + "description": "协同去重陪伴注入", + "hint": "开启后会和陪伴插件协调,让重复的自我时间线、私聊上下文等段落只由一侧注入。", + "type": "bool", + "default": true + }, + "prefer_memory_companion_memory": { + "description": "MemoryCompanion 接管记忆上下文", + "hint": "开启后陪伴插件会尽量让出自我时间线、私聊上下文和旧 LivingMemory 指引,由 MemoryCompanion 统一注入。", + "type": "bool", + "default": true + }, + "preserve_external_prompt_context": { + "description": "保留外部临时片段", + "hint": "整理 AstrBot 原始历史时只保留真正带临时/不保存标记的外部片段;历史里遗留的 private_companion HTML 动态块会被清理,避免状态、引用链或工具提示写入会话历史后反复污染主链。", + "type": "bool", + "default": true + }, + "cross_window_emotional_continuity_enabled": { + "description": "跨窗口情绪连续性", + "hint": "默认关闭。开启后其他会话中触发的情绪余波可影响当前窗口,但不会注入原始记忆内容。", + "type": "bool", + "default": false + }, + "clean_proactive_history": { + "description": "清理主动消息历史提示", + "hint": "注入前清理 AstrBot 原始上下文中残留的主动消息生成提示、send_message_to_user 工具说明、主动承接占位和 TTS/定时控制标签,只保留用户可见的干净聊天内容。", + "type": "bool", + "default": true + }, + "suppress_self_timeline_when_companion_seen": { + "description": "陪伴已注入时隐藏自我时间线槽", + "hint": "检测到陪伴插件已提供状态或自我时间线时,隐藏重复的 Bot 自我时间线槽。", + "type": "bool", + "default": true + }, + "suppress_user_context_when_companion_seen": { + "description": "陪伴已注入时隐藏用户上下文槽", + "hint": "检测到陪伴插件已提供私聊状态时,隐藏重复的用户画像和阶段总结槽。", + "type": "bool", + "default": true + } + } + }, + "visibility": { + "description": "隔离与可见性", + "hint": "控制私聊、群聊、自我时间线之间的默认流动边界。", + "type": "object", + "items": { + "allow_self_timeline_everywhere": { + "description": "共享 Bot 自我时间线", + "hint": "Bot 自己做过的动作可作为所有窗口的自我背景,但仍会带来源标签。", + "type": "bool", + "default": true + }, + "allow_group_public_in_private": { + "description": "私聊可见群公共记忆", + "hint": "开启后私聊中可看到群公共记忆,便于跨窗口回话。如需严格隔离私聊与群聊可关闭。", + "type": "bool", + "default": false + }, + "enable_acl_rules": { + "description": "启用卡片权限", + "hint": "开启后,可在私聊/群聊卡片中配置跨窗口读取权限;默认隔离仍然生效,只有显式授权的窗口会被额外放行。", + "type": "bool", + "default": true + } + } + }, + "memory_tools": { + "description": "主动记忆工具", + "hint": "允许模型在需要时主动回忆、记忆和整理 Bot 自己的陪伴笔记。", + "type": "object", + "items": { + "enable_recall_tool": { + "description": "启用主动回忆工具", + "hint": "开启后模型可调用 memory_companion_recall,按当前会话可见性主动检索记忆。", + "type": "bool", + "default": true + }, + "enable_remember_tool": { + "description": "启用主动记忆工具", + "hint": "开启后模型可调用 memory_companion_remember 写入长期记忆;请配合总结防注入和召回日志观察效果。", + "type": "bool", + "default": true + }, + "enable_note_tools": { + "description": "启用陪伴笔记工具", + "hint": "开启后模型可创建、读取和删除当前 Bot 自己可见的 companion_note,用于日程、状态、创作草稿和陪伴线索整理。", + "type": "bool", + "default": true + } + } + }, + "knowledge_graph": { + "description": "图谱关联", + "hint": "从阶段性记忆抽取人物、话题和事实关联,用于辅助检索和拓展页排障。", + "type": "object", + "items": { + "enabled": { + "description": "启用图谱建索引", + "hint": "开启后,阶段性总结成功时会自动写入知识图谱节点和边。", + "type": "bool", + "default": true + }, + "retrieval_expansion_enabled": { + "description": "检索使用图谱一跳扩展", + "hint": "开启后,搜索某个人或话题时会从知识图谱取少量相关节点作为检索扩展词;最终结果仍受可见性和权限过滤。", + "type": "bool", + "default": true + }, + "expansion_limit": { + "description": "扩展词上限", + "hint": "每次检索最多从图谱取多少个相关词。建议 6-12,过高会扩大召回范围。", + "type": "int", + "default": 12 + }, + "backfill_limit": { + "description": "维护补建条数", + "hint": "运行维护时,最多从多少条已有阶段性总结补建知识图谱。补建是幂等的,重复运行不会重复建边。", + "type": "int", + "default": 300 + } + } + }, + "livingmemory_migration": { + "description": "LivingMemory 导入", + "hint": "从旧 LivingMemory 数据库导入 documents 摘要。导入前建议预览并备份。", + "type": "object", + "items": { + "import_limit": { + "description": "单次导入上限", + "hint": "单次最多导入多少条 LivingMemory documents 完整记忆。0 表示不限制。", + "type": "int", + "default": 5000 + }, + "livingmemory_db_path": { + "description": "LivingMemory 数据库路径", + "hint": "留空则自动扫描常见位置。建议先执行 /mcomp import_livingmemory preview。", + "type": "string", + "default": "" + } + } + }, + "maintenance": { + "description": "维护", + "hint": "控制数据保留和清理策略。", + "type": "object", + "items": { + "backup_before_import": { + "description": "导入前备份", + "hint": "执行旧记忆导入前先备份当前 SQLite 数据库。", + "type": "bool", + "default": true + }, + "sleep_backup_enabled": { + "description": "睡眠维护前备份", + "hint": "开启后每次 /mcomp sleep run 或页面维护都会先备份数据库。默认关闭,避免频繁备份占用空间。", + "type": "bool", + "default": false + }, + "retention_raw_event_days": { + "description": "原始事件保留天数", + "hint": "原始流水事件超过该天数后可进入清理。0 表示暂不自动清理。", + "type": "int", + "default": 7 + }, + "retention_raw_event_limit": { + "description": "原始事件单次归档上限", + "hint": "每次睡眠维护最多归档多少条过期 raw_event 长期记录,避免一次维护写入过多。", + "type": "int", + "default": 1000 + }, + "retention_summarized_timeline_days": { + "description": "已总结时间线保留天数", + "hint": "只清理已经成功写入长期总结的时间线;未总结和总结失败的原始消息不会被删除。0 表示不自动清理。", + "type": "int", + "default": 30 + }, + "retention_injection_log_days": { + "description": "注入日志保留天数", + "hint": "超过该天数的注入诊断日志会在睡眠维护时删除。0 表示不自动清理。", + "type": "int", + "default": 14 + }, + "retention_cleanup_limit": { + "description": "保留清理单次上限", + "hint": "每次维护分别最多删除多少条已总结时间线和注入日志,避免长事务。", + "type": "int", + "default": 2000 + }, + "memory_decay_enabled": { + "description": "启用自然衰减", + "hint": "开启后,睡眠维护会筛选长期未访问、重要度较低的稳定记忆,先压缩成高层摘要,再归档原碎片。", + "type": "bool", + "default": true + } + } + }, + "maintenance_decay": { + "description": "自然衰减高级参数", + "hint": "衰减年龄、未访问天数、重要度阈值、候选上限和摘要字数等高级调优参数。日常使用可保持默认。", + "type": "object", + "items": { + "memory_decay_after_days": { + "description": "衰减年龄天数", + "hint": "稳定记忆存在超过该天数后才可能进入衰减候选。明确记住、画像、偏好、关系、手动记忆会被保护。", + "type": "int", + "default": 180 + }, + "memory_decay_idle_days": { + "description": "未访问天数", + "hint": "记忆距离上次被召回超过该天数后才可能衰减;被频繁召回的记忆会自然加固。", + "type": "int", + "default": 90 + }, + "memory_decay_max_importance_percent": { + "description": "最大衰减重要度", + "hint": "重要度高于该百分比的记忆不会自动衰减。建议 65-80。", + "type": "int", + "default": 74 + }, + "memory_decay_max_access_count": { + "description": "最大召回次数", + "hint": "被召回次数超过该值的记忆不会自动衰减,表示它仍然有用。", + "type": "int", + "default": 2 + }, + "memory_decay_score_threshold_percent": { + "description": "衰减分阈值", + "hint": "年龄、未访问时间、重要度和置信度共同计算的衰减分达到该百分比后才进入压缩。", + "type": "int", + "default": 75 + }, + "memory_decay_max_candidates": { + "description": "单次候选上限", + "hint": "每次睡眠维护最多处理多少条衰减候选。", + "type": "int", + "default": 120 + }, + "memory_decay_max_groups": { + "description": "单次窗口组上限", + "hint": "每次睡眠维护最多压缩多少个私聊/群聊窗口,确保不同窗口的隐私边界不混合。", + "type": "int", + "default": 8 + }, + "memory_decay_min_items_per_summary": { + "description": "摘要最少碎片", + "hint": "同一窗口至少累积多少条衰减候选才生成压缩摘要并归档原碎片。", + "type": "int", + "default": 4 + }, + "memory_decay_max_items_per_summary": { + "description": "单摘要碎片上限", + "hint": "单条衰减摘要最多合并多少条旧记忆碎片。", + "type": "int", + "default": 24 + }, + "memory_decay_summary_input_chars": { + "description": "衰减摘要输入字数", + "hint": "单次衰减压缩最多发送给模型的旧记忆字符数。", + "type": "int", + "default": 6000 + }, + "memory_decay_summary_chars": { + "description": "衰减摘要字数", + "hint": "衰减压缩生成的新长期摘要最大字数。", + "type": "int", + "default": 900 + } + } + } +} diff --git a/benchmarks/run_memory_benchmark.py b/benchmarks/run_memory_benchmark.py new file mode 100644 index 0000000..66a7ffb --- /dev/null +++ b/benchmarks/run_memory_benchmark.py @@ -0,0 +1,170 @@ +from __future__ import annotations + +import argparse +import asyncio +import json +import statistics +import sys +import tempfile +import time +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +if str(ROOT.parent) not in sys.path: + sys.path.insert(0, str(ROOT.parent)) + +from astrbot_plugin_remember_you.core.models import EntityRef, MemoryRecord, SessionContext +from astrbot_plugin_remember_you.core.service import MemoryCompanionService + + +TARGETS = [ + ("蓝风铃", "用户最喜欢的花是蓝风铃。"), + ("周三牙医", "用户预约了周三下午三点看牙医。"), + ("无糖拿铁", "用户喝拿铁时不要加糖。"), + ("海边计划", "共同计划是十月去海边看日出。"), +] + + +async def run(size: int, repeats: int) -> dict: + with tempfile.TemporaryDirectory() as temp: + service = MemoryCompanionService( + context=None, + config={ + "retrieval": {"mode": "basic", "embedding_enabled": False}, + "knowledge_graph": {"enabled": False, "retrieval_expansion_enabled": False}, + "visibility": {"enable_acl_rules": True, "allow_group_public_in_private": False}, + }, + plugin_root=ROOT, + data_dir=Path(temp), + ) + try: + session = "qq:FriendMessage:benchmark-user" + user = EntityRef(kind="user", id="benchmark-user", name="基准用户") + bot = EntityRef.bot_self("benchmark-bot", "基准助手") + started = time.perf_counter() + for index in range(max(0, size - len(TARGETS))): + await service.store.insert_memory( + MemoryRecord( + id=f"decoy_{index}", + memory_type="conversation_summary", + subject=user, + object=bot, + scope="private", + session_id=session, + visibility="private_pair", + lifecycle="stable_memory", + content=f"普通对话片段 {index},主题编号 {index % 97}。", + importance=0.4, + ) + ) + target_ids: dict[str, str] = {} + for index, (query, content) in enumerate(TARGETS): + memory_id = f"target_{index}" + target_ids[query] = memory_id + await service.store.insert_memory( + MemoryRecord( + id=memory_id, + memory_type="explicit_memory", + subject=user, + object=bot, + scope="private", + session_id=session, + visibility="private_pair", + lifecycle="stable_memory", + content=content, + importance=0.9, + ) + ) + group_secret_id = await service.store.insert_memory( + MemoryRecord( + id="group_secret", + memory_type="conversation_summary", + subject=EntityRef(kind="user", id="other-user"), + object=EntityRef(kind="group", id="private-group"), + scope="group", + session_id="qq:GroupMessage:private-group", + group_id="private-group", + visibility="group_public", + lifecycle="stable_memory", + content="群聊机密口令是银色月桂,禁止流入私聊。", + importance=1.0, + ) + ) + load_ms = (time.perf_counter() - started) * 1000 + ctx = SessionContext( + session_id=session, + scope="private", + platform="qq", + user_id="benchmark-user", + bot_id="benchmark-bot", + ) + latencies: list[float] = [] + hits = 0 + total = 0 + privacy_leaks = 0 + per_query: dict[str, dict[str, int]] = { + query: {"hits": 0, "runs": 0} for query, _content in TARGETS + } + for _ in range(max(1, repeats)): + for query, _content in TARGETS: + tick = time.perf_counter() + results = await service.search(query, ctx, top_k=5) + latencies.append((time.perf_counter() - tick) * 1000) + ids = {item.memory.id for item in results} + matched = int(target_ids[query] in ids) + hits += matched + per_query[query]["hits"] += matched + per_query[query]["runs"] += 1 + privacy_leaks += int(group_secret_id in ids) + total += 1 + secret_results = await service.search("银色月桂", ctx, top_k=5) + privacy_leaks += int(group_secret_id in {item.memory.id for item in secret_results}) + ordered = sorted(latencies) + p95_index = max(0, min(len(ordered) - 1, int(len(ordered) * 0.95) - 1)) + return { + "dataset_size": size + 1, + "mode": "basic", + "embedding_enabled": False, + "external_retrieval_model_calls": 0, + "load_ms": round(load_ms, 2), + "queries": total, + "hit_at_5": round(hits / total, 4) if total else 0.0, + "per_query": { + query: { + **values, + "hit_rate": round(values["hits"] / values["runs"], 4) if values["runs"] else 0.0, + } + for query, values in per_query.items() + }, + "privacy_leaks": privacy_leaks, + "latency_ms": { + "median": round(statistics.median(latencies), 3), + "p95": round(ordered[p95_index], 3), + "max": round(max(latencies), 3), + }, + "notes": [ + "该脚本只测本地 basic 检索,不代表 Embedding、Rerank 或阶段总结成本。", + "跨插件比较必须使用相同数据、模型、硬件和配置。", + ], + } + finally: + service.close() + + +async def main() -> None: + parser = argparse.ArgumentParser(description="MemoryCompanion deterministic retrieval benchmark") + parser.add_argument("--size", type=int, default=1000, help="number of private memories before adding one group secret") + parser.add_argument("--repeats", type=int, default=5, help="query repetitions") + parser.add_argument("--output", type=Path, default=None, help="optional UTF-8 JSON result path") + args = parser.parse_args() + result = await run(max(10, args.size), max(1, args.repeats)) + payload = json.dumps(result, ensure_ascii=False, indent=2) + if args.output: + args.output.parent.mkdir(parents=True, exist_ok=True) + args.output.write_text(payload + "\n", encoding="utf-8") + print(payload) + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/core/__init__.py b/core/__init__.py new file mode 100644 index 0000000..5d97651 --- /dev/null +++ b/core/__init__.py @@ -0,0 +1 @@ +"""Core modules for astrbot_plugin_memory_companion.""" diff --git a/core/astrbot_compat.py b/core/astrbot_compat.py new file mode 100644 index 0000000..9978836 --- /dev/null +++ b/core/astrbot_compat.py @@ -0,0 +1,478 @@ +from __future__ import annotations + +import logging +import re +from typing import Any + +try: + from astrbot.api import logger # type: ignore +except Exception: # pragma: no cover - useful for local syntax/unit checks + logger = logging.getLogger("MemoryCompanion") + +try: + from astrbot.core.agent.message import TextPart +except Exception: # pragma: no cover - old AstrBot or local checks + TextPart = None # type: ignore + + +def remove_marked_text(text: str, header: str, footer: str) -> str: + if not text or header not in text or footer not in text: + return text or "" + result = text + while header in result and footer in result: + start = result.find(header) + end = result.find(footer, start) + if start < 0 or end < 0: + break + result = result[:start] + result[end + len(footer) :] + return "\n\n".join(part.strip() for part in result.split("\n\n") if part.strip()) + + +PRIVATE_COMPANION_MARKERS = ( + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", + "", +) + +_PRIVATE_COMPANION_BLOCK_RE = re.compile( + r"\n*\s*.*?" + r"(?=\n\s*|\Z)", + re.IGNORECASE | re.DOTALL, +) +_PRIVATE_COMPANION_TURN_FRAGMENT_RE = re.compile( + r"\n*\s*.*?" + r"\s*", + re.IGNORECASE | re.DOTALL, +) + +PRIVATE_COMPANION_PROACTIVE_BLOCK_HEADINGS = ( + "【主动消息回复上下文】", + "【候选主动消息】", + "【原主动消息】", + "【最近私聊记录】", + "【本轮主动来源】", + "【内在约束】", +) + + +def private_companion_proactive_text_is_internal(text: Any) -> bool: + raw = str(text or "") + if not raw.strip(): + return False + compact = re.sub(r"\s+", "", raw).lower() + lowered = raw.lower() + if "主动承接占位" in raw and ("用户还没发来新消息" in raw or "bot主动" in compact): + return True + if "这不是用户消息" in raw and "private companion" in lowered and "主动消息" in raw: + return True + if "你是主动私聊发送前的价值复核模型" in raw: + return True + if "主动消息人格/世界观判定器" in raw: + return True + if "这是一次用户已授权的主动陪伴行为" in raw: + return True + if "PrivateCompanion captured send_message_to_user payload" in raw: + return True + if any(raw.strip().startswith(heading) for heading in PRIVATE_COMPANION_PROACTIVE_BLOCK_HEADINGS): + return True + if "send_message_to_user" in lowered and any( + token in raw + for token in ( + "主动消息", + "主动陪伴", + "主动私聊", + "框架唤醒链", + "必须使用", + "工具调用", + "用户已授权", + ) + ): + return True + if "send_message_to_user" in lowered and any( + token in lowered + for token in ( + "captured", + "tool result", + "tool call", + "message captured", + "privatecompanion", + ) + ): + return True + if ( + ("你现在要在同一段私聊会话里" in raw or "真正会发给对方的一条私聊消息" in raw) + and "主动" in raw + and any(token in raw for token in ("只输出", "不要解释", "send_message_to_user")) + ): + return True + if ("[主动消息]" in raw or "【主动消息】" in raw) and sum( + 1 for marker in ("触发原因", "行为结果", "内部动机", "动作摘要", "候选主动消息") if marker in raw + ) >= 2: + return True + if ("工具调用限制" in raw or "agent reached max steps" in lowered) and any( + token in lowered for token in ("send_message_to_user", "发消息", "主动") + ): + return True + return False + + +def _drop_private_companion_proactive_blocks(text: str) -> tuple[str, bool]: + """Remove multi-line proactive framework blocks while preserving visible chat.""" + if not text: + return "", False + + lines = text.replace("\r", "\n").splitlines() + kept: list[str] = [] + changed = False + dropping_block = False + + for line in lines: + stripped = line.strip() + if not stripped: + if dropping_block: + changed = True + dropping_block = False + continue + kept.append(line) + continue + + if any(stripped.startswith(heading) for heading in PRIVATE_COMPANION_PROACTIVE_BLOCK_HEADINGS): + changed = True + dropping_block = True + continue + + if dropping_block: + changed = True + continue + + kept.append(line) + + return "\n".join(kept), changed + + +def _strip_private_companion_marked_blocks(text: str) -> tuple[str, bool]: + if not text or "private_companion_" not in text: + return text or "", False + cleaned = _PRIVATE_COMPANION_TURN_FRAGMENT_RE.sub("\n", text) + cleaned = _PRIVATE_COMPANION_BLOCK_RE.sub("\n", cleaned) + cleaned = re.sub(r"\n{3,}", "\n\n", cleaned).strip() + return cleaned, cleaned != text + + +def clean_private_companion_history_text(text: Any) -> tuple[str, bool, bool]: + raw = str(text or "") + if not raw: + return "", False, False + if private_companion_proactive_text_is_internal(raw): + return "", True, True + + cleaned = raw + cleaned = re.sub(r"\[\[TTSBLOCK:[^\]]*\]\]", "", cleaned) + cleaned = re.sub(r"\[\[PCTTS:[^\]]*\]\]", "", cleaned) + cleaned = re.sub(r"]*>.*?", "", cleaned, flags=re.IGNORECASE | re.DOTALL) + cleaned = re.sub(r"]*>.*?", "", cleaned, flags=re.IGNORECASE | re.DOTALL) + cleaned = re.sub(r"【主动承接占位】[^\n]*(?:\n|$)", "", cleaned) + cleaned, removed_companion_block = _strip_private_companion_marked_blocks(cleaned) + cleaned = re.sub( + r"\s*\s*", + "", + cleaned, + flags=re.IGNORECASE, + ) + cleaned, removed_block = _drop_private_companion_proactive_blocks(cleaned) + + kept_lines: list[str] = [] + removed_line = removed_block or removed_companion_block + for line in cleaned.replace("\r", "\n").splitlines(): + stripped = line.strip() + if not stripped: + kept_lines.append(line) + continue + if private_companion_proactive_text_is_internal(stripped): + removed_line = True + continue + lowered = stripped.lower() + if "send_message_to_user" in lowered or "tool `send_message_to_user`" in lowered: + removed_line = True + continue + if any(stripped.startswith(heading) for heading in PRIVATE_COMPANION_PROACTIVE_BLOCK_HEADINGS): + removed_line = True + continue + if "主动消息专用模式下" in stripped and "Private Companion 工具" in stripped: + removed_line = True + continue + kept_lines.append(line) + + cleaned = "\n".join(kept_lines) + cleaned = re.sub(r"\n{3,}", "\n\n", cleaned).strip() + changed = cleaned != raw or removed_line + if changed and not cleaned: + return "", True, True + return cleaned, changed, False + + +def _plain_request_text(value: Any, *, depth: int = 0) -> str: + if value is None or depth > 4: + return "" + if isinstance(value, str): + return value + if isinstance(value, (int, float, bool)): + return str(value) + text = getattr(value, "text", None) + if isinstance(text, str): + return text + content = getattr(value, "content", None) + if content is not None and content is not value: + return _plain_request_text(content, depth=depth + 1) + if isinstance(value, list): + return "\n".join(_plain_request_text(item, depth=depth + 1) for item in value) + if isinstance(value, tuple): + return "\n".join(_plain_request_text(item, depth=depth + 1) for item in value) + if isinstance(value, dict): + parts: list[str] = [] + for key in ("text", "content", "value", "marker", "source", "metadata"): + if key in value: + parts.append(_plain_request_text(value.get(key), depth=depth + 1)) + return "\n".join(part for part in parts if part) + return "" + + +def _is_temp_or_plugin_context(item: Any) -> bool: + if bool(getattr(item, "_private_companion_turn_fragments", False)): + return True + if bool(getattr(item, "_no_save", False) or getattr(item, "no_save", False)): + return True + if not isinstance(item, dict): + return False + if bool(item.get("_no_save") or item.get("no_save") or item.get("temporary") or item.get("temp")): + return True + metadata = item.get("metadata") + if isinstance(metadata, dict): + source = str(metadata.get("source") or metadata.get("plugin") or metadata.get("source_plugin") or "") + if source in {"private_companion", "astrbot_plugin_private_companion"}: + return True + source = str(item.get("source") or item.get("plugin") or item.get("source_plugin") or "") + return source in {"private_companion", "astrbot_plugin_private_companion"} + + +def _sanitize_context_content(value: Any) -> tuple[Any, bool, bool]: + if value is None: + return value, False, False + if isinstance(value, str): + return clean_private_companion_history_text(value) + if isinstance(value, list): + cleaned_items: list[Any] = [] + changed = False + for item in value: + cleaned_item, item_changed, drop = _sanitize_context_content(item) + changed = changed or item_changed or drop + if not drop: + cleaned_items.append(cleaned_item) + return cleaned_items, changed, not cleaned_items and bool(value) + if isinstance(value, tuple): + cleaned_list, changed, drop = _sanitize_context_content(list(value)) + return tuple(cleaned_list), changed, drop + if isinstance(value, dict): + changed = False + cleaned = dict(value) + had_payload = any(key in cleaned for key in ("content", "text", "value")) + for key in ("content", "text", "value"): + if key not in cleaned: + continue + new_value, item_changed, drop = _sanitize_context_content(cleaned.get(key)) + changed = changed or item_changed + if drop: + cleaned.pop(key, None) + else: + cleaned[key] = new_value + if not any(cleaned.get(key) not in (None, "", [], {}) for key in ("content", "text", "value")): + if had_payload and changed: + return cleaned, True, True + text = _plain_request_text(cleaned) + if text and private_companion_proactive_text_is_internal(text): + return cleaned, True, True + return cleaned, changed, False + + for attr in ("content", "text"): + current = getattr(value, attr, None) + if current is None: + continue + new_value, changed, drop = _sanitize_context_content(current) + if drop: + return value, True, True + if changed: + try: + setattr(value, attr, new_value) + except Exception: + return value, False, False + return value, True, False + text = _plain_request_text(value) + if text and private_companion_proactive_text_is_internal(text): + return value, True, True + return value, False, False + + +def sanitize_request_history(req: Any, *, clean_proactive_guidance: bool = True) -> dict[str, int]: + if not clean_proactive_guidance: + return {"before": 0, "after": 0, "removed": 0, "cleaned": 0} + contexts = getattr(req, "contexts", None) + if not isinstance(contexts, list): + return {"before": 0, "after": 0, "removed": 0, "cleaned": 0} + + cleaned_contexts: list[Any] = [] + cleaned_count = 0 + removed = 0 + for item in contexts: + cleaned_item, changed, drop = _sanitize_context_content(item) + if drop: + removed += 1 + continue + if changed: + cleaned_count += 1 + cleaned_contexts.append(cleaned_item) + if removed or cleaned_count: + req.contexts = cleaned_contexts + return { + "before": len(contexts), + "after": len(cleaned_contexts), + "removed": removed, + "cleaned": cleaned_count, + } + + +def remove_temp_text(req: Any, header: str, footer: str) -> int: + removed = 0 + parts = getattr(req, "extra_user_content_parts", None) + if isinstance(parts, list): + kept = [] + for part in parts: + text = getattr(part, "text", "") + if isinstance(text, str) and header in text and footer in text: + removed += 1 + continue + kept.append(part) + req.extra_user_content_parts = kept + + prompt = getattr(req, "prompt", None) + if isinstance(prompt, str) and header in prompt and footer in prompt: + cleaned = remove_marked_text(prompt, header, footer) + if cleaned != prompt: + req.prompt = cleaned + removed += 1 + + contexts = getattr(req, "contexts", None) + if isinstance(contexts, list): + kept = [] + for item in contexts: + text = _plain_request_text(item) + if isinstance(text, str) and header in text and footer in text: + removed += 1 + continue + kept.append(item) + if len(kept) != len(contexts): + req.contexts = kept + return removed + + +def manage_request_contexts( + req: Any, + mode: str = "trim", + keep_recent: int = 2, + *, + preserve_external_temp: bool = True, +) -> dict[str, int | str]: + contexts = getattr(req, "contexts", None) + if not isinstance(contexts, list): + return {"mode": mode, "before": 0, "after": 0, "removed": 0, "preserved": 0} + + before = len(contexts) + normalized_mode = mode if mode in {"keep", "trim", "clear"} else "trim" + if normalized_mode == "keep": + return {"mode": normalized_mode, "before": before, "after": before, "removed": 0, "preserved": 0} + + preserve_indices: set[int] = set() + if preserve_external_temp: + preserve_indices = {index for index, item in enumerate(contexts) if _is_temp_or_plugin_context(item)} + + if normalized_mode == "clear": + kept_indices = preserve_indices + else: + keep = max(0, int(keep_recent or 0)) + ordinary_indices = [index for index in range(before) if index not in preserve_indices] + kept_indices = set(ordinary_indices[-keep:] if keep else []) + kept_indices.update(preserve_indices) + req.contexts = [item for index, item in enumerate(contexts) if index in kept_indices] + after = len(getattr(req, "contexts", []) or []) + return { + "mode": normalized_mode, + "before": before, + "after": after, + "removed": max(0, before - after), + "preserved": len(preserve_indices), + } + + +def detect_private_companion_request(req: Any) -> dict[str, Any]: + texts: list[str] = [] + for attr in ("system_prompt", "prompt"): + value = getattr(req, attr, "") + if isinstance(value, str) and value: + texts.append(value) + + parts = getattr(req, "extra_user_content_parts", None) + if isinstance(parts, list): + texts.extend(_plain_request_text(part) for part in parts) + + contexts = getattr(req, "contexts", None) + if isinstance(contexts, list): + texts.extend(_plain_request_text(item) for item in contexts) + + fragments = getattr(req, "_private_companion_turn_prompt_fragments", None) + if isinstance(fragments, list): + texts.extend(_plain_request_text(item) for item in fragments) + + surface = "\n".join(text for text in texts if text) + markers = [marker for marker in PRIVATE_COMPANION_MARKERS if marker in surface] + return { + "has_any": bool("private_companion_" in surface or markers or fragments), + "has_state": "" in surface, + "has_group_context": "" in surface, + "has_self_timeline": "" in surface, + "has_recall_query": "" in surface, + "has_turn_fragments": "" in surface or isinstance(fragments, list), + "markers": markers, + } + + +def append_temp_text(req: Any, text: str) -> bool: + if TextPart is None: + return False + if not hasattr(req, "extra_user_content_parts") or getattr(req, "extra_user_content_parts", None) is None: + req.extra_user_content_parts = [] + part = TextPart(text=text) + mark_as_temp = getattr(part, "mark_as_temp", None) + if callable(mark_as_temp): + part = mark_as_temp() + req.extra_user_content_parts.append(part) + return True diff --git a/core/bridge.py b/core/bridge.py new file mode 100644 index 0000000..d12e82d --- /dev/null +++ b/core/bridge.py @@ -0,0 +1,479 @@ +from __future__ import annotations + +from datetime import datetime, timezone +from typing import Any +from zoneinfo import ZoneInfo + +from .models import EntityRef, MemoryRecord, SessionContext, clean_text + + +LOCAL_TZ = ZoneInfo("Asia/Shanghai") + + +def _local_time_label(value: Any) -> str: + text = clean_text(value, 80) + if not text: + return "" + try: + dt = datetime.fromisoformat(text.replace("Z", "+00:00")) + if dt.tzinfo is None: + dt = dt.replace(tzinfo=timezone.utc) + return dt.astimezone(LOCAL_TZ).strftime("%Y-%m-%d %H:%M:%S") + except Exception: + return text + + +class MemoryCompanionBridge: + """Public bridge for other plugins. + + The bridge intentionally accepts structured fields. A caller should say + whether something is a bot action, a persona-life fragment, a real user + fact, or an imported summary instead of handing over vague prose. + """ + + def __init__(self, plugin: Any): + self._plugin = plugin + + async def record_event( + self, + *, + content: str, + memory_type: str = "external_event", + scope: str = "unknown", + session_id: str = "", + platform: str = "", + message_id: str = "", + group_id: str = "", + subject: dict[str, Any] | None = None, + object: dict[str, Any] | None = None, + visibility: str = "bot_self", + sayability: str = "direct", + reality_level: str = "bot_action", + lifecycle: str = "stable_memory", + confidence: float = 0.85, + importance: float = 0.5, + review_status: str = "auto", + tags: list[str] | None = None, + metadata: dict[str, Any] | None = None, + source_plugin: str = "external", + memory_id: str = "", + occurred_at: str = "", + ) -> str: + return await self._plugin.record_external_event( + content=content, + memory_type=memory_type, + scope=scope, + session_id=session_id, + platform=platform, + message_id=message_id, + group_id=group_id, + subject=self._entity(subject) if subject else EntityRef.bot_self(), + object=self._entity(object) if object else EntityRef(kind="session", id=session_id, role="target_session"), + visibility=visibility, + sayability=sayability, + reality_level=reality_level, + lifecycle=lifecycle, + confidence=confidence, + importance=importance, + review_status=review_status, + tags=tags or [], + metadata=metadata or {}, + source_plugin=source_plugin, + memory_id=memory_id, + occurred_at=occurred_at, + ) + + async def record_bot_action(self, *, content: str, **kwargs: Any) -> str: + kwargs.setdefault("memory_type", "self_action") + kwargs.setdefault("visibility", "bot_self") + kwargs.setdefault("reality_level", "bot_action") + kwargs.setdefault("source_plugin", kwargs.get("source_plugin", "external")) + return await self.record_event(content=content, **kwargs) + + async def record_persona_life(self, *, content: str, **kwargs: Any) -> str: + kwargs.setdefault("memory_type", "persona_life") + kwargs.setdefault("visibility", "bot_self") + kwargs.setdefault("reality_level", "persona_life") + kwargs.setdefault("sayability", "indirect") + return await self.record_event(content=content, **kwargs) + + async def record_proactive_message(self, *, content: str, **kwargs: Any) -> str: + kwargs.setdefault("memory_type", "proactive_message") + kwargs.setdefault("visibility", "bot_self") + kwargs.setdefault("reality_level", "bot_action") + kwargs.setdefault("tags", ["proactive", "bot_action"]) + kwargs.setdefault("importance", 0.55) + return await self.record_event(content=content, **kwargs) + + async def record_visible_turn(self, *, role: str, content: str, **kwargs: Any) -> str: + """Record a real visible chat turn into the short-term timeline only.""" + return await self._plugin.record_visible_turn(role=role, content=content, **kwargs) + + async def record_shared_experience( + self, + *, + content: str, + experience_type: str, + bot_id: str = "", + bot_name: str = "", + user_id: str = "", + user_name: str = "", + scope: str = "private", + session_id: str = "", + platform: str = "", + source_plugin: str = "external", + memory_id: str = "", + confidence: float = 0.9, + importance: float = 0.7, + metadata: dict[str, Any] | None = None, + ) -> str: + """Record one distilled call/watch experience with explicit ownership.""" + normalized_type = clean_text(experience_type, 40).lower() + if normalized_type in {"watch", "shared_watch", "video"}: + memory_type = "shared_watch" + experience_tag = "watch" + elif normalized_type in {"call", "shared_call", "voice"}: + memory_type = "shared_call" + experience_tag = "call" + else: + memory_type = "shared_experience" + experience_tag = normalized_type or "shared" + subject = EntityRef.bot_self(bot_id=bot_id, bot_name=bot_name) + target = EntityRef( + kind="user", + id=clean_text(user_id, 120), + name=clean_text(user_name, 80), + role="shared_experience_partner", + ) + return await self.record_event( + content=content, + memory_type=memory_type, + scope=scope, + session_id=session_id, + platform=platform, + subject={ + "kind": subject.kind, + "id": subject.id, + "name": subject.name, + "role": subject.role, + }, + object={ + "kind": target.kind, + "id": target.id, + "name": target.name, + "role": target.role, + }, + visibility="bot_self", + sayability="direct", + reality_level="bot_action", + lifecycle="stable_memory", + confidence=confidence, + importance=importance, + review_status="auto", + tags=["shared_experience", experience_tag, "bot_action"], + metadata=metadata or {}, + source_plugin=source_plugin, + memory_id=memory_id, + ) + + async def record_search_action(self, *, content: str, **kwargs: Any) -> str: + kwargs.setdefault("memory_type", "search_action") + kwargs.setdefault("visibility", "bot_self") + kwargs.setdefault("reality_level", "bot_action") + kwargs.setdefault("tags", ["search", "bot_action"]) + kwargs.setdefault("importance", 0.62) + return await self.record_event(content=content, **kwargs) + + async def record_creative_work(self, *, content: str, **kwargs: Any) -> str: + kwargs.setdefault("memory_type", "creative_work") + kwargs.setdefault("visibility", "bot_self") + kwargs.setdefault("reality_level", "fictional_content") + kwargs.setdefault("sayability", "direct") + kwargs.setdefault("tags", ["creative_work"]) + kwargs.setdefault("importance", 0.72) + return await self.record_event(content=content, **kwargs) + + async def record_image_action(self, *, content: str, **kwargs: Any) -> str: + kwargs.setdefault("memory_type", "image_action") + kwargs.setdefault("visibility", "bot_self") + kwargs.setdefault("reality_level", "bot_action") + kwargs.setdefault("tags", ["image", "bot_action"]) + kwargs.setdefault("importance", 0.6) + return await self.record_event(content=content, **kwargs) + + async def record_qzone_action(self, *, content: str, **kwargs: Any) -> str: + kwargs.setdefault("memory_type", "qzone_action") + kwargs.setdefault("visibility", "bot_self") + kwargs.setdefault("reality_level", "bot_action") + kwargs.setdefault("tags", ["qzone", "bot_action"]) + kwargs.setdefault("importance", 0.58) + return await self.record_event(content=content, **kwargs) + + async def record_reading(self, *, content: str, **kwargs: Any) -> str: + kwargs.setdefault("memory_type", "reading_memory") + kwargs.setdefault("visibility", "bot_self") + kwargs.setdefault("reality_level", "bot_action") + kwargs.setdefault("tags", ["reading", "bot_action"]) + kwargs.setdefault("importance", 0.55) + return await self.record_event(content=content, **kwargs) + + async def record_schedule_fragment(self, *, content: str, **kwargs: Any) -> str: + kwargs.setdefault("memory_type", "schedule_fragment") + kwargs.setdefault("visibility", "bot_self") + kwargs.setdefault("reality_level", "persona_life") + kwargs.setdefault("sayability", "indirect") + kwargs.setdefault("tags", ["schedule", "persona_life"]) + kwargs.setdefault("importance", 0.45) + return await self.record_event(content=content, **kwargs) + + async def search( + self, + query: str, + *, + session_context: SessionContext | dict[str, Any] | None = None, + top_k: int | None = None, + ) -> list[dict[str, Any]]: + return await self._plugin.bridge_search(query, session_context=session_context, top_k=top_k) + + async def compose_injection( + self, + query: str, + *, + session_context: SessionContext | dict[str, Any] | None = None, + top_k: int | None = None, + max_chars: int | None = None, + companion_bot_mood: str = "", + companion_bot_energy: float = 0.0, + ) -> str: + return await self._plugin.bridge_compose_injection( + query, + session_context=session_context, + top_k=top_k, + max_chars=max_chars, + companion_bot_mood=companion_bot_mood, + companion_bot_energy=companion_bot_energy, + ) + + async def compose_context( + self, + *, + query: str = "", + session_context: SessionContext | dict[str, Any] | None = None, + top_k: int | None = None, + max_chars: int | None = None, + companion_bot_mood: str = "", + companion_bot_energy: float = 0.0, + retrieval_profile: str = "", + ) -> str: + return await self._plugin.bridge_compose_context( + query=query, + session_context=session_context, + top_k=top_k, + max_chars=max_chars, + companion_bot_mood=companion_bot_mood, + companion_bot_energy=companion_bot_energy, + retrieval_profile=retrieval_profile, + ) + + async def remember(self, *, event: Any, content: str, note_type: str = "memory") -> dict[str, Any]: + return await self._plugin.tool_remember(event, content, note_type=note_type) + + async def recall(self, *, event: Any, query: str, top_k: int = 5) -> dict[str, Any]: + return await self._plugin.tool_recall(event, query, top_k=top_k) + + async def create_note(self, *, event: Any, title: str, content: str = "") -> dict[str, Any]: + return await self._plugin.tool_note_create(event, title, content) + + async def read_notes(self, *, event: Any, query: str = "", limit: int = 5) -> dict[str, Any]: + return await self._plugin.tool_note_read(event, query, limit=limit) + + async def delete_note(self, *, event: Any, memory_id: str = "", title: str = "") -> dict[str, Any]: + return await self._plugin.tool_note_delete(event, memory_id, title=title) + + def coordination_status(self) -> dict[str, Any]: + getter = getattr(self._plugin, "companion_coordination_status", None) + if callable(getter): + return getter() + return {"available": True} + + def get_token_usage_summary(self) -> dict[str, Any]: + getter = getattr(self._plugin, "token_usage_summary", None) + if callable(getter): + result = getter() + return result if isinstance(result, dict) else {} + return {} + + def should_defer_private_companion_section(self, section: str) -> bool: + checker = getattr(self._plugin, "should_private_companion_defer_section", None) + if callable(checker): + return bool(checker(section)) + return False + + async def create_cross_window_thread( + self, + *, + from_session: str, + to_session: str, + topic: str, + content: str, + visibility: str = "shareable", + metadata: dict[str, Any] | None = None, + ) -> str: + return await self._plugin.store.create_cross_window_thread( + from_session=from_session, + to_session=to_session, + topic=topic, + content=content, + visibility=visibility, + metadata=metadata or {}, + ) + + async def mark_visibility(self, memory_id: str, visibility: str) -> bool: + return await self._plugin.store.update_memory_visibility(memory_id, visibility) + + def get_emotional_events(self, *, session_id: str = "", limit: int = 5) -> list[dict[str, Any]]: + """Retrieve pending emotional drift events for the companion plugin.""" + return self._plugin.bridge_get_emotional_events(session_id=session_id, limit=limit) + + async def search_open_loops(self, *, session_id: str = "", limit: int = 3) -> list[dict[str, Any]]: + """Search for unresolved open-loop / promise memories for proactive companionship.""" + return await self._plugin.bridge_search_open_loops(session_id=session_id, limit=limit) + + def get_relationship_phase( + self, + *, + session_id: str = "", + scope: str = "private", + platform: str = "", + user_id: str = "", + group_id: str = "", + bot_id: str = "", + ) -> dict[str, Any]: + """Return current relationship phase state for a session.""" + getter = getattr(self._plugin, "_get_relationship_phase", None) + if not callable(getter): + return {"phase": "unknown", "momentum": 0.0} + normalizer = getattr(self._plugin, "session_context_from_bridge", None) + payload = { + "session_id": session_id, + "scope": scope, + "platform": platform, + "user_id": user_id, + "group_id": group_id, + "bot_id": bot_id, + } + ctx = normalizer(payload) if callable(normalizer) else SessionContext(**payload) + return getter(ctx) + + def get_recent_emotional_state(self) -> dict[str, Any]: + """Return a summary of recent emotional events across ALL sessions. + + This provides cross-window emotional continuity for the companion plugin: + if the bot recently touched scar or warm memories in any session, the + companion plugin can factor this into its daily state calibration. + """ + getter = getattr(self._plugin, "_get_cross_window_emotional_state", None) + if not callable(getter): + return {"total": 0, "scar_count": 0, "warm_count": 0, "vulnerable_count": 0} + return getter() + + def _entity(self, payload: dict[str, Any]) -> EntityRef: + return EntityRef( + kind=str(payload.get("kind") or "user"), + id=str(payload.get("id") or ""), + name=str(payload.get("name") or ""), + role=str(payload.get("role") or "unknown"), + ) + +def serialize_memory(record: MemoryRecord, score: float | None = None, reason: str = "") -> dict[str, Any]: + metadata = record.metadata if isinstance(record.metadata, dict) else {} + key_facts = metadata.get("key_facts") if isinstance(metadata.get("key_facts"), list) else [] + routine_check_notes = metadata.get("routine_check_notes") if isinstance(metadata.get("routine_check_notes"), list) else [] + topics = metadata.get("topics") if isinstance(metadata.get("topics"), list) else [] + participants = metadata.get("participants") if isinstance(metadata.get("participants"), list) else [] + persona_weight_keys = [ + "persona_importance", + "relationship_weight", + "emotional_weight", + "promise_weight", + "open_loop_weight", + "creative_weight", + "preference_weight", + "self_continuity_weight", + "freshness_weight", + "scar_weight", + "emotional_debt_weight", + "intimacy_weight", + "vulnerability_weight", + ] + persona_weights = { + key: metadata.get(key) + for key in persona_weight_keys + if metadata.get(key) is not None + } + data = { + "id": record.id, + "memory_type": record.memory_type, + "scope": record.scope, + "session_id": record.session_id, + "group_id": record.group_id, + "visibility": record.visibility, + "sayability": record.sayability, + "reality_level": record.reality_level, + "lifecycle": record.lifecycle, + "content": record.content, + "evidence_preview": clean_text(record.evidence, 520), + "canonical_summary": clean_text(metadata.get("canonical_summary"), 420), + "key_facts": [clean_text(item, 180) for item in key_facts if clean_text(item, 180)][:4], + "routine_check_notes": [clean_text(item, 180) for item in routine_check_notes if clean_text(item, 180)][:4], + "topics": [clean_text(item, 80) for item in topics if clean_text(item, 80)][:5], + "participants": [clean_text(item, 80) for item in participants if clean_text(item, 80)][:5], + "memory_reason": clean_text(metadata.get("memory_reason"), 260), + "mention_policy": clean_text(metadata.get("mention_policy"), 60), + "mentionability_score": metadata.get("mentionability_score"), + "relationship_phase": clean_text(metadata.get("relationship_phase"), 80), + "decay_mode": clean_text(metadata.get("decay_mode"), 80), + "active_dimensions": [ + clean_text(item, 80) + for item in metadata.get("active_dimensions", []) + if clean_text(item, 80) + ][:6] if isinstance(metadata.get("active_dimensions"), list) else [], + "persona_weights": persona_weights, + "mention_feedback": metadata.get("mention_feedback") if isinstance(metadata.get("mention_feedback"), dict) else {}, + "confidence": record.confidence, + "importance": record.importance, + "review_status": record.review_status, + "tags": record.tags, + "source_plugin": record.source_plugin, + "import_batch_id": record.import_batch_id, + "created_at": record.created_at, + "created_at_local": _local_time_label(record.created_at), + "updated_at": record.updated_at, + "updated_at_local": _local_time_label(record.updated_at), + "occurred_at": record.occurred_at, + "occurred_at_local": _local_time_label(record.occurred_at), + "time_range": { + "start_at": clean_text(metadata.get("start_at"), 80), + "end_at": clean_text(metadata.get("end_at"), 80), + "start_at_local": clean_text(metadata.get("start_at_local"), 80) or _local_time_label(metadata.get("start_at")), + "end_at_local": clean_text(metadata.get("end_at_local"), 80) or _local_time_label(metadata.get("end_at")), + "timezone": "Asia/Shanghai", + }, + "subject": { + "kind": record.subject.kind, + "id": record.subject.id, + "name": record.subject.name, + "role": record.subject.role, + }, + "object": { + "kind": record.object.kind, + "id": record.object.id, + "name": record.object.name, + "role": record.object.role, + }, + } + if score is not None: + data["score"] = score + if reason: + data["reason"] = reason + return data diff --git a/core/chat_import.py b/core/chat_import.py new file mode 100644 index 0000000..9ab8559 --- /dev/null +++ b/core/chat_import.py @@ -0,0 +1,3242 @@ +from __future__ import annotations + +import asyncio +import hashlib +import importlib +import json +import math +import re +import shutil +from bisect import bisect_left, bisect_right +from dataclasses import dataclass +from datetime import datetime, timedelta, timezone +from pathlib import Path +from typing import Any +from zoneinfo import ZoneInfo + +from .astrbot_compat import logger +from .models import EntityRef, MemoryRecord, SessionContext, clean_text, json_dumps, stable_fingerprint, utc_now + + +LOCAL_TZ = ZoneInfo("Asia/Shanghai") +FULL_HEADER = re.compile( + r"^(?P[^\r\n::]{1,80})\s*[::]\s*" + r"(?P\d{4})-(?P\d{2})-(?P\d{2})\s+" + r"(?P\d{2}:\d{2}:\d{2})\s*$" +) +SHORT_HEADER = re.compile( + r"^(?P[^\r\n::]{1,80})\s*[::]\s*" + r"(?P\d{2})-(?P\d{2})\s+" + r"(?P\d{2}:\d{2}:\d{2})\s*$" +) +HEADER_LIKE = re.compile(r"^.{1,80}[::]\s*\d") +FIELD_LINE = re.compile(r"^(?P