19 KiB
运维版记忆插件源码审计与优化档案
审计日期:2026-07-24
审计对象:astrbot_plugin_memory_companion_ops(工作目录:astrbot_plugin_memory_companion-main)
当前分支:ops-main
当前版本:1.6.2-ops.2
审计性质:源码、数据模型、运行链路、面板 API、测试与部署文档的全量结构化复盘;本档案不替代生产验收记录。
1. 结论摘要
这个插件已经具备“可投入运维场景”的完整骨架:长期记忆、时间线、分层检索、Embedding/Rerank、权限隔离、自然衰减、导入导出、LivingMemory 迁移、Archivist Bridge、Q3 运维事实合同和 Q4 时间感知均已落地,并有较完整的回归测试与 VM 验收证据。
当前最值得优化的不是再堆一个“记忆类型”,而是把已有能力从“能运行”提升为“可解释、可纠错、可治理”:
- 重要性、置信度、新鲜度和人格价值仍然共同影响一个排序分数,缺少独立的事实可信度与召回解释层。
- 记忆可以被
supersedes_id标记,但没有形成完整的冲突检测、版本链、当前有效版本查询和用户可见纠错流程。 - 动态时间元数据已实现,但检索缓存命中后只做权限复验,不重新计算年龄、过期状态或排序分数。
- 维护、导入、导出、迁移能力很丰富,但缺少统一的 dry-run、校验和、分页/流式处理、失败恢复与审计结果模型。
- 观测面板能展示不少运行指标,但还没有“召回质量、误召回、过期事实命中、冲突记忆、注入收益”的闭环指标。
总体评级:架构能力强,生产边界清晰;数据治理和质量度量处于下一阶段建设期。
2. 审计范围与证据
2.1 主要源码范围
- 数据模型与规范化:
core/models.py、core/config.py - 记忆价值评估:
core/importance.py - 检索与重排:
core/retrieval.py - Prompt 注入:
core/injection.py - 服务编排与维护:
core/service.py - SQLite 持久化:
core/store.py - Bridge/Archivist:
core/bridge.py、core/archive_contract.py - 运维合同:
core/ops_domain.py、core/operations.py - 历史导入与 LivingMemory 迁移:
core/chat_import.py、core/migration_livingmemory.py - 面板 HTTP API:
page_api.py、pages/记忆面板/app.js - 测试:
tests/全部测试模块
2.2 版本和验收证据
- Q4 时间感知实现:提交
8d21776 - Q4 VM 验收文档:提交
b227a7e - Q4 完整回归证据:提交
efd6fab - 现有验收记录显示:VM 服务 active、
NRestarts=0、定向测试20 passed、完整回归155 passed, 1 warning,Archivist 发现运维版1.6.2-ops.2。 - 本次审计以源码为准;README 或验收文档中未能由源码、测试或实机证据互相印证的内容,均标记为“需补证”。
3. 整体架构与数据流
AstrBot 事件
-> identity/session 解析
-> classifier / time_intent / reply_chain
-> timeline 原始事件
-> summarizer / importance evaluator
-> memories + relationship_edges + knowledge graph
-> retrieval: 当前窗口 / 时间窗口 / FTS / 关键词 / 向量 / 图扩展
-> visibility + ACL + mutable-fact collapse + source dedupe
-> slot orchestration
-> injection composer + temporal metadata
-> LLM 请求
外部路径:
Controller 事实 -> Q3 OpsFactRef/OpsEvent -> Bridge/人格层
LivingMemory/QQ 历史 -> preview -> import batch -> 记忆/时间线/关系
面板 -> page_api -> service/store -> 维护、导出、审查、修复
3.1 数据模型优点
MemoryRecord 已明确区分 occurred_at、created_at、updated_at、last_accessed_at,并保存 confidence、importance、visibility、lifecycle、review_status、supersedes_id 和 metadata(core/models.py:97-167)。这为时间感知、事实等级和后续版本链提供了正确基础。
SQLite 层启用 WAL、外键和 busy timeout,并有事务、连接恢复、删除级联和 revision 机制(core/store.py:35-45、core/store.py:184-236)。这是生产稳定性的良好基础。
4. 能力矩阵
| 能力 | 状态 | 证据/说明 |
|---|---|---|
| 长期记忆与时间线 | 已实现 | MemoryRecord、timeline 表、阶段总结链路 |
| 重要性评估 | 已实现但需治理 | core/importance.py:15-78,多维人格价值评分 |
| 置信度与审查队列 | 部分实现 | 字段和 review queue 存在,但缺少统一人工校准流程 |
| 分层检索 | 已实现 | core/retrieval.py:878-1025,当前窗口/时间窗口/FTS/关键词/向量 |
| Rerank/Embedding | 已实现 | 配置、候选缓存、超时与降级路径存在 |
| 权限与 ACL | 已实现 | 可见性、scope、session、group、ACL 复验和缓存失效测试 |
| 记忆去重 | 部分实现 | fingerprint、mutable fact collapse、LivingMemory source dedupe;通用语义去重不足 |
| 冲突/替代 | 部分实现 | supersedes_id、归档原因存在,但没有完整冲突图和当前版本查询 |
| 时间感知 | 已实现 | core/temporal_context.py,动态 age/stale/relative label |
| Prompt 注入预算 | 已实现 | slot 编排、compact 模式、字符上限;缺少 token 级质量度量 |
| 自然衰减 | 已实现但有误伤风险 | core/service.py:3760-3880,按保护类型/标签/权重筛选 |
| LivingMemory 迁移 | 已实现 | preview、批次、修复路径和回滚能力存在 |
| JSONL 迁移 | 已实现但规模有限 | core/operations.py:303-631,64 MiB 上限、整批载入 |
| 运维事实合同 | 已实现 | core/ops_domain.py:37-325,只校验不执行外部操作 |
| 运行时兼容 | 已实现 | capability probe 与降级状态 |
| 面板管理 | 已实现 | page_api.py:68-113,记忆、维护、导入、ACL、Bridge 路由 |
| 可观测性 | 部分实现 | 有耗时、Token、缓存、WAL、路径诊断;缺少质量指标 |
5. 已实现且建议保留的设计
5.1 时间与事实边界
Q4 的动态时间合同是正确方向:年龄、相对标签、跨日、过期原因在输出时计算,不写死到数据库;MemoryRecord.ensure_defaults() 只写入来源、时区、精度和估算标记(core/models.py:129-146)。build_temporal_memory_meta() 输出 age_seconds、age_label、relative_label、stale、time_source 等字段(core/temporal_context.py:166-197)。
Q3 规定 Controller 事实优先于记忆,且合同层不执行 Shell/SSH/Docker,是运维插件必须坚持的安全边界。
5.2 权限与跨窗口隔离
检索前做 visibility/ACL 过滤,缓存命中后还会重新读取当前记录并复验权限(core/retrieval.py:94-142)。跨窗口、群聊/私聊和 Bot 自我时间线已有专门测试,明显优于“把所有历史拼成一个 prompt”的实现。
5.3 存储一致性与可恢复性
删除记忆有级联和事务回滚测试;WAL、busy timeout、连接恢复、revision 和 embedding 表设计较完整。tests/test_store_consistency.py 与 tests/test_security_cache.py 已覆盖多项高风险边界。
5.4 迁移可逆性
LivingMemory 和历史聊天导入都带批次概念;JSONL 导入前备份,历史聊天有 rollback 路由。这使插件具备从旧生态迁移而不直接破坏主库的能力。
6. 重点欠缺与优化清单
优先级定义:P0=会造成严重数据/权限/生产风险;P1=会造成明显事实错误或维护成本;P2=质量、效率和产品体验提升。
P1-01:重要性分数承担了过多语义
- 现象:一个
importance同时承载长期价值、人格意义、内容类型、生命周期和部分新鲜度;检索又直接把importance乘以0.55,同时叠加confidence*0.25、recency、persona、dynamics(core/importance.py:49-78、core/retrieval.py:2191-2254)。 - 根因:没有把“是否值得记住”“是否可信”“是否适合当前提及”“是否仍是当前事实”拆成独立可解释信号。
- 影响:高重要但过期的服务状态可能仍有较强召回;低重要但与当前问题高度匹配的事实可能被压下去;分数变化难以向用户解释。
- 建议:新增
memory_value、fact_confidence、mentionability、freshness_state四个逻辑维度;保留旧importance作为兼容字段,检索改用可解释的分桶/门控。 - 可实施性:可以立即做合同和评分单元测试,下一阶段再替换排序公式。
P1-02:人工重要性修改没有形成“覆盖层”
- 证据:面板更新接口直接接受
importance、confidence、lifecycle等字段(page_api.py:454-470);评估器在calibrate()中用metadata.setdefault("base_importance", ...)保存基线(core/importance.py:15-47)。 - 风险:人工调整与自动重算的关系不清楚;重跑校准时可能继续使用旧基线,用户无法知道“手动 0.9”是否被模型覆盖或只影响一次。
- 建议:增加
manual_importance_override、override_reason、override_by、override_at、calibration_version;UI 显示“自动分/人工分/最终分”。 - 可实施性:中等,属于数据契约扩展,可先只写 metadata,无需立即迁移表结构。
P1-03:缓存命中后不重新计算时间状态和排序
- 证据:服务把结果按 revision/config/query/time intent 缓存(
core/service.py:1450-1516),命中后调用revalidate_cached_results(),该函数只刷新记录并复验权限,不重新跑_score()、过期门控或temporal(core/retrieval.py:94-116;core/service.py:1618-1628)。 - 影响:短 TTL 内跨过天气/服务状态 TTL 时,旧结果仍可能保留;缓存中的
score和reason反映命中时刻而不是当前时刻。 - 建议:缓存命中后至少执行:动态 stale 门控、age bucket 变化检查、可变事实 collapse;若 age bucket 或 stale 状态变化则重新排序或放弃缓存。
- 可实施性:高,优先级高,风险低。
P1-04:冲突与版本链不完整
- 现状:模型有
supersedes_id,维护归档会写入decay_archived(core/models.py:127、core/store.py:4853-4888),检索对 mutable fact 有特定 collapse,但这不是通用事实冲突治理。 - 欠缺:没有统一的
conflict_set_id、superseded_by、生效时间区间、冲突原因和当前版本查询;无法可靠回答“哪个是最新事实、旧事实为什么失效”。 - 建议:为偏好、账号、地址、服务状态、计划等可变事实建立 conflict family;写入时检测同 owner/subject/key 的候选,旧版本标记
superseded,保留证据和替代关系;检索默认只返回当前有效版本,历史查询显式展开。 - 可实施性:中高;先覆盖运维服务状态、计划和联系方式,避免一次性推广到所有文本记忆。
P1-05:衰减策略保护规则偏硬,缺少 dry-run 与人工复核
- 证据:
_decay_candidate()通过类型、标签、权重、phase、visibility 直接跳过或纳入衰减(core/service.py:3760-3804);分组后达到最小条数才调用摘要(core/service.py:3718-3758)。 - 风险:保护类型列表与 metadata 可能漂移;低频但重要的关系/创作片段可能因分类错误进入压缩;摘要失败时只能记录错误,缺少逐组重试和人工预览。
- 建议:维护接口增加
dry_run=true,返回候选、排除原因、预计摘要内容和影响范围;实际执行使用确认 token;每个摘要保留source_memory_ids、摘要版本和可逆恢复入口。 - 可实施性:高,先做 dry-run 和报告即可明显降低运维风险。
P1-06:导入/导出路径适合中小库,不适合大库
- 证据:JSONL 导出一次性读取最多
1_000_000条记忆、时间线、关系和 ACL(core/operations.py:309-315);单文件上限为 64 MiB,导入读取后把全部记录放进内存(core/operations.py:15-17、602-631)。 - 影响:库变大后内存峰值、导出耗时和失败重试成本明显上升;导入没有逐段 checkpoint,长任务中断后只能整体重来。
- 建议:改为分页/游标式导出;JSONL 按块写入并带 SHA-256、记录数和 schema 版本;导入按 record_type 分批提交,保存 checkpoint,支持断点续传和单类回滚。
- 可实施性:中等,适合下一阶段数据治理版本。
P1-07:迁移/导入的“选择哪一个源库”仍较隐式
- 证据:LivingMemory
preview()枚举候选路径,import_data()使用preview["candidates"][0]作为导入源(core/migration_livingmemory.py:72-95)。 - 风险:同一环境存在多个旧库、备份库或测试库时,可能导入错误候选;用户只能在事后从批次记录发现来源。
- 建议:预览返回候选排序依据、文件大小、mtime、表计数和健康检查;导入必须携带明确
source_path或候选 ID,默认拒绝隐式第一项。 - 可实施性:高。
P1-08:外部事实的 TTL 已有合同,但通用记忆检索没有统一 stale gate
- 证据:Q3
OpsFactRef有expires_at/stale_after_seconds;Q4temporal_context能判断天气、服务状态等主题过期;但核心_score()主要使用 recency bonus,未把stale作为通用硬门控(core/retrieval.py:2237-2247)。 - 影响:Bridge 出口能告诉调用方“过期”,主检索路径仍可能先选出再注入,取决于上层是否额外处理。
- 建议:把
stale_policy写入检索结果:exclude、background_only、allow_with_warning;运维状态、天气、人体状态默认为 exclude/background-only。 - 可实施性:高,先在运维记忆类型和 topic_expiry 上启用。
P2-01:检索解释还不够面向运维排查
- 现状:reason 字符串包含 hits、bm25、vector、importance、persona、recency(
core/retrieval.py:2250-2254),但没有显示“为何被过滤、为何比另一个候选高、是否因 stale/冲突被降级”。 - 建议:输出结构化
score_breakdown、filter_decisions、source_path、freshness_decision,字符串只作为兼容展示。
P2-02:注入预算以字符为主,缺少真实 token 预算与收益统计
- 证据:注入器使用
max_chars、section 限额和 compact 模式控制包大小(core/injection.py:15-100)。 - 欠缺:中文、代码、表格、不同模型 tokenizer 的实际 token 成本不同;没有记录每个 slot 的 token 占用、命中后是否被模型使用或造成重复。
- 建议:增加 tokenizer 可选适配;至少记录估算 token、slot、被截断原因和最终响应任务类型,建立“每 1k token 带来的有效命中”指标。
P2-03:通用语义去重弱于特定场景去重
- 现状:有 content fingerprint、mutable fact collapse 和 LivingMemory source dedupe,但不是通用语义级 merge;同一事实来自消息、导入摘要、人工笔记和外部插件时,可能保留多份。
- 建议:建立 canonical fact key、来源优先级和合并策略;保留证据列表,不直接覆盖原文。
P2-04:关系阶段状态是文件级 JSON,缺少数据库治理
- 证据:关系阶段状态从文件加载并原子替换保存(
core/service.py:7465-7484)。 - 风险:多进程/多实例同时写入时没有锁、版本号或合并策略;备份、迁移和按用户清理也不随 SQLite 事务统一完成。
- 建议:迁移到 SQLite 独立表或至少增加 file lock、revision、冲突恢复和备份纳入范围。
P2-05:面板危险操作需要更强的二次确认与审计
- 证据:页面直接暴露
/maintenance/clear_all、/maintenance/clear_scope、/memory/delete等路由(page_api.py:68-113)。 - 建议:所有清空/批量归档/导入/恢复操作使用 preview -> confirm token -> execute;记录 actor、scope、数量、备份路径、结果和失败原因;默认禁止跨 scope 的管理请求。
P2-06:测试偏合同和单元,缺少规模、故障和质量回归
- 已有:时间合同、权限缓存、存储一致性、历史导入、运维合同、运行时兼容、面板回归等测试。
- 欠缺:没有稳定的真实数据集评测召回 precision/recall;没有 10 万级 SQLite 压测、长时间衰减、导入中断恢复、多进程写入、WAL 膨胀、Embedding provider 慢/挂的故障矩阵。
- 建议:建立脱敏 fixture 和基准集;每次评分/过滤规则修改自动输出 top-k 命中、过期命中、跨 scope 泄露、注入 token 和 p95 延迟。
7. 按阶段的优化队列
阶段 A:低风险、立即可做
- 缓存命中时重新检查 stale、age bucket 和 mutable fact。
- LivingMemory 导入必须显式选择候选源库。
- 维护增加 dry-run、候选排除原因和确认 token。
- 检索结果增加结构化
score_breakdown与freshness_decision。 - 面板危险操作增加 preview/confirm/audit。
- 为上述行为补齐单元测试和一条 VM 回归脚本。
阶段 B:事实治理增强
- 引入人工重要性覆盖层和版本化校准元数据。
- 建立 conflict family、superseded 状态、有效期和当前版本查询。
- 为服务状态、天气、身体状态、临时计划启用 stale gate。
- 将摘要压缩结果与源记忆建立可恢复的证据链。
阶段 C:规模化与质量度量
- JSONL 导入导出分页化、校验和、断点续传。
- SQLite 大库基准、WAL/备份/恢复演练和多进程写入测试。
- 脱敏召回基准集,追踪 precision@k、stale hit rate、conflict hit rate、cross-scope block rate、injection token p95。
- 评估将关系阶段状态迁移到数据库。
8. 不能在本次源码审计中确认的事项
- 生产环境真实记忆规模、每日增长量和 WAL 膨胀曲线未在本地源码中确认。
- 当前配置是否启用 Embedding/Rerank、各 Provider 实际 p95 和失败率,需要从 VM 运行指标或日志取证。
- 真实用户数据下的召回准确率、过期事实命中率和注入收益没有基准集,不能由单元测试推断。
- 面板路由是否由宿主统一鉴权、是否存在反向代理层 CSRF 防护,需结合 AstrBot/部署配置审计。
9. 最终判断
运维版记忆插件的核心方向是正确的:它已经不是简单的“聊天记录检索器”,而是一个带权限、时间、事实边界、迁移和跨插件合同的记忆中枢。
下一阶段的关键不是继续增加更多记忆类型,而是完成三件事:
- 让每次召回都能解释:为什么选中、为什么过滤、为什么过期、为什么当前不能当事实。
- 让每条事实都能纠错:谁写入、来自哪里、何时生效、被谁替代、如何恢复。
- 让维护操作可预演可回滚:先看影响,再确认执行,结果有审计,失败可恢复。
完成阶段 A 后,插件的生产可运维性会有明显提升;完成阶段 B/C 后,才适合把它作为长期的个人运维知识与陪伴记忆底座。
10. 参考文件
README.mdcore/models.pycore/importance.pycore/retrieval.pycore/injection.pycore/temporal_context.pycore/store.pycore/service.pycore/operations.pycore/migration_livingmemory.pycore/ops_domain.pycore/archive_contract.pycore/bridge.pypage_api.pytests/- 项目根目录:
Q3_运维事件与数据模型说明.md、Q4_记忆插件时间感知改造要求.md、Q4_VM部署验收记录.md
本档案只记录源码审计发现,不自动修改业务代码;实施优化前应以阶段 A 的合同测试和 dry-run 结果为准。