astrbot_plugin_memory_compa.../docs/运维记忆错题本.md

42 KiB

运维记忆插件错题本

适用仓库:astrbot_plugin_memory_companion-main 分支:ops-main 说明:这里只记录运维记忆插件自身的存储、检索、时间感知、Bridge、归档、权限和面板问题;陪伴人格问题记录在另一份错题本中。

2026-07-24 — 动态时间年龄不能写入数据库

  • 阶段:Q4 记忆时间感知改造
  • 类型:API契约 / 数据安全
  • 现象:记忆如果只保存“几小时前”“隔了几天”等年龄文本,下一次读取就会过期或失真。
  • 根因:时间年龄是读取时相对于当前时间计算的动态结果,不是事件本身的永久属性。
  • 修复或规避:持久化事件发生时间、入库时间、来源、时区和精度;检索时动态生成 temporal 信息。
  • 预防规则:不得把 age_seconds、delay_label 等动态字段作为永久事实写入数据库;当前运维状态必须重新查询 Controller。
  • 验证证据:Q4 时间合同测试、时间感知兼容说明.md 和 VM 验收记录已覆盖该边界。

2026-07-24 — 长期记忆不能冒充当前运维事实

  • 阶段:运维记忆与 Controller 边界
  • 类型:安全 / 功能行为
  • 现象:历史记忆中的“服务正常”“备份完成”可能被模型误认为现在仍然成立。
  • 根因:记忆系统保存的是历史背景,不能替代本轮实时观察。
  • 修复或规避:记忆只提供历史摘要、决策理由、任务背景和事实引用;当前服务、任务和备份状态必须来自本轮授权 Controller 结果。
  • 预防规则:任何“当前正常”“已经完成”“现在运行中”的结论都必须带本轮来源和观察时间。
  • 验证证据:运维事件合同要求事实引用包含来源、来源编号和观察时间。

2026-07-24 — Archivist 必须在宿主加载完成后重新发现 Bridge

  • 阶段:跨插件联动与 VM 验收
  • 类型:API契约 / 部署
  • 现象:Memory Archivist 初始可能报告记忆源不可用,但记忆插件随后已经正常加载。
  • 根因:Archivist 初始化早于 MemoryCompanion 实例化,只在初始化阶段探测会得到空结果。
  • 修复或规避:在 AstrBot 宿主加载完成 Hook 中重新解析记忆源,并优先复用当前进程已经加载的 ops Bridge 实例。
  • 预防规则:跨插件联动必须验证生命周期顺序、实例复用和实机 capability,不只测试模块能否 import。
  • 验证证据:VM 已验证 source=memory_companion、available=True、search=True。

2026-07-24 — 测试包名必须与运维插件身份一致

  • 阶段:源码复盘与回归验证
  • 类型:测试 / 构建
  • 现象:测试仍引用旧包名时,会在收集阶段报 ModuleNotFoundError,导致业务测试根本没有执行。
  • 根因:源码目录、metadata、正式插件包名和测试导入路径没有同步更新。
  • 修复或规避:测试前先检查正式包名和导入映射;不能把测试收集失败当作测试通过。
  • 预防规则:插件改名或建立 _ops 身份后,必须做全仓旧包名扫描,并在干净环境验证测试收集。
  • 验证证据:记忆插件既有错题本记录了旧包名导入阻塞及临时别名验证过程。

2026-07-24 — 只读观察窗不能混入写操作

  • 阶段:记忆面板与运维观察
  • 类型:功能行为 / 安全
  • 现象:知识图谱、记忆统计和事实观察如果直接混入编辑或删除入口,用户容易误以为观察动作会修改记忆。
  • 根因:观察数据合同和记忆写操作合同没有在界面与 API 层分开。
  • 修复或规避:观察窗只返回只读数据和 readonly=true;删除、编辑、合并等操作必须单独设计确认、审计和回滚。
  • 预防规则:所有运维观察能力默认只读;写入能力不能从只读接口隐式派生。
  • 验证证据:面板回归测试、Node 检查和临时 SQLite 验证已通过。

2026-07-24 - Q4.2 calendar history Bridge and stable deduplication

  • Phase: Q4.2 memory temporal fields and calendar linkage
  • Type: API contract / behavior / test
  • Symptom: calendar status updates could be mixed with chat or operations facts, and repeated sync could overwrite the first ingestion timestamp.
  • Root cause: CalendarStore belongs to the companion plugin; the memory side lacked a dedicated historical layer, stable event key, and an insert-time preservation rule.
  • Fix/workaround: added record_calendar_event; stored memory_type=calendar_event, memory_layer=calendar_history, source and time metadata; derived a stable memory id from event_id; SQLite conflict updates now exclude created_at and update status plus updated_at only.
  • Prevention rule: calendar linkage uses only the standard Bridge; dynamic age is computed at retrieval time; one event id reuses one memory id; current operations facts still come from Controller/NAS Ops.
  • Validation evidence: tests.test_calendar_bridge, temporal, Bridge and panel regression tests passed; the focused test verifies created_at preservation, updated_at change, layer isolation and no persisted age_seconds.

2026-07-24 - PowerShell stdin can corrupt Chinese source literals

  • Phase: Q4.2 implementation and encoding repair
  • Type: build / environment
  • Symptom: Chinese literals added through a PowerShell Python here-string became question marks.
  • Root cause: the command channel code page is not a reliable UTF-8 transport for Chinese script stdin.
  • Fix/workaround: all source reads and writes use explicit Python UTF-8; edit scripts use Unicode escapes or chr() for Chinese; post-write scans check for question marks and py_compile.
  • Prevention rule: never use PowerShell default encoding to write Chinese source; always verify UTF-8 readability, compilation and git diff --check.
  • Validation evidence: modified Python files read as UTF-8 and pass compilation and focused tests.

2026-07-24 - Full discovery includes an unrelated companion dependency

  • Phase: full regression validation
  • Type: test / environment
  • Symptom: full unittest discover ran 137 test entries, with 136 passing and test_security_cache failing during collection because it imports the ordinary companion branch and the environment has no astrbot package.
  • Root cause: the existing test module resolves page_api from astrbot_plugin_private_companion-main; this ops-only task must not modify that branch, and the local unit-test environment does not provide AstrBot runtime dependencies.
  • Fix/workaround: kept the ordinary branch unchanged; validated all relevant ops, temporal, Bridge, storage, injection and panel tests separately, and will run discovery excluding only this unrelated module.
  • Prevention rule: separate pure unit tests from host-runtime integration tests; do not treat a host dependency collection error as a product regression.
  • Validation evidence: focused suite passed 16/16; compileall -q core tests and git diff --check passed.

2026-07-25 — Q5 用户记忆硬边界与混合域隔离

  • 阶段:M5.0-M5.4 用户记忆合同、Bridge 收口、检索隔离、迁移预览
  • 类型:API契约 / 数据安全 / 测试 / 功能行为
  • 现象:旧通用 Bridge 同时允许 Bot 自我、共享体验、日历历史和用户记忆写入;混合总结可能被误当成用户事实。
  • 根因:历史数据模型只有主体、可见性和记忆类型,没有强制的数据所有权域;检索入口也没有先做域过滤。
  • 修复或规避:新增 memory_domain 和用户主体验证;用户 Bridge 强制证据与来源;Bot/混合记录分别拒绝或隔离;默认检索只接受 user_memory;旧数据提供 preview/apply/rollback,禁止直接删除;LivingMemory 入口停用。
  • 预防规则:收口的是数据所有权,不是删除私聊或群聊;任何用户记忆必须绑定实际用户、scope、群 ID(群聊)和可追溯证据;日历和 Bot 自我连续性不得通过记忆插件公开写入。
  • 验证证据:tests.test_user_memory_contract、tests.test_calendar_bridge、tests.test_bridge_shared_experience、tests.test_epistemic_calibration.VerifiedGroupBotFactTests 通过;全仓编译和迁移回滚测试随后复核。

2026-07-25 — Q5 全量回归与宿主依赖边界

  • 阶段:M5.5 时间感知回归与全仓验证
  • 类型:测试 / 环境
  • 现象:全量发现最初包含普通陪伴分支的 test_security_cache,本机未安装 AstrBot 宿主包而无法收集。
  • 根因:运维版仓库测试发现路径会导入普通陪伴分支页面 API;该分支不属于本次改造范围。
  • 修复或规避:不修改普通陪伴分支;将宿主依赖测试单独标记为环境阻塞,其余 142 项运维版测试正常执行。
  • 预防规则:跨插件测试必须区分纯单元测试与宿主集成测试;宿主依赖缺失不能被误报为业务回归。
  • 验证证据:compileall -q core tests page_api.py 通过;git diff --check 通过;排除 test_security_cache 后 142 tests 全部通过;定向 Q5、Q4.2、总结、检索和存储测试全部通过。

2026-07-25 — Q5 首次 VM 部署暴露旧库索引迁移顺序

  • 阶段:Q5 VM 部署验收与修复
  • 类型:部署 / 数据库迁移 / API契约
  • 现象:提交 66b5d0b 部署后 AstrBot 服务仍 active,但运维记忆插件初始化失败,日志报 sqlite3.OperationalError: no such column: memory_domain,Archivist 自动降级。
  • 根因:memories 旧表在字段迁移前执行了依赖新字段的 idx_memories_domain 创建。
  • 修复或规避:将域索引创建移动到 _ensure_memory_columns_sync() 之后;增加真实 Q4 schema 去掉单字段的升级测试;不删除或重建用户数据目录。
  • 预防规则:任何新增数据库列必须先完成幂等字段迁移,再创建索引、触发器和查询约束;部署验收必须看插件加载日志和 Bridge 可用性,不能只看 systemd active。
  • 验证证据:本地旧库迁移测试通过;待修复提交重新部署后复核插件加载、Archivist capability、服务状态和数据目录。

2026-07-25 — Q5 修复版 VM 验收完成

  • 阶段:Q5 修复部署与最终验收
  • 类型:部署 / 测试 / 环境
  • 现象:修复版需要确认不只是 systemd 存活,而是插件真正加载并被 Archivist 发现。
  • 根因:AstrBot 会在插件构造阶段捕获初始化错误,服务仍可保持 active,单看 systemd 会漏报插件失效。
  • 修复或规避:部署后检查插件启动日志、数据目录、Archivist capability、服务重启次数,并用 AstrBot 实际 Python 做只读编译和合同 smoke test。
  • 预防规则:VM 验收必须同时满足服务 active、目标插件加载、Bridge/Archivist 可用、数据目录保留和无新增 traceback;pytest 不可用时必须明确标注而不是伪造通过。
  • 验证证据:提交 a8598e7;插件 1.6.2-ops.2 loaded;available=True search=True;NRestarts=0;Q5_SMOKE_OK user_memory;部署包 SHA-256 与 VM 一致。

2026-07-25 — Q6 只读用户事实查询 Bridge

  • 阶段:Q6.0 记忆侧只读事实合同与边界过滤
  • 类型:API契约 / 数据安全 / 测试
  • 现象:现有通用归档 Bridge 能检索历史记忆,但调用方无法通过明确接口表达“只读用户事实”;跨域调用容易误用通用 search。
  • 根因:归档 API 已有 scope 和可见性过滤,但缺少独立的用户事实能力声明、输入校验和结果域收口。
  • 修复或规避:新增 query_user_facts 和能力探测;要求私聊用户 ID、群聊用户 ID 与群 ID;结果只接受明确的 user_memory,保留时间元数据;Bridge 缺失返回空结果和 warning。
  • 预防规则:用户事实查询必须显式绑定 user/scope,禁止把缺失域、Bot 自有域、混合域或日历历史视为用户记忆;只读查询不得写库。
  • 验证证据:tests/test_q6_user_fact_bridge.py 已补齐能力、降级、scope 和非用户域过滤测试;compileall 与模块导入检查通过;pytest 当前环境未安装,未虚报测试通过。

2026-07-25 — Q6 VM 部署验收与远程脚本编码

  • 阶段:Q6 记忆侧 Bridge 部署验收
  • 类型:部署 / 环境 / API契约
  • 现象:部署脚本通过 PowerShell here-string 发送到 VM 时,首行带 UTF-8 BOM,导致远程 shell 报 set: command not found,验收脚本首个 printf 也被 BOM 影响。
  • 根因:远程 shell 输入不是文件写回,但 PowerShell here-string 仍携带 BOM;脚本主体后续命令继续执行,不能把单条首命令失败误判为完整脚本成功。
  • 修复或规避:部署结果以独立只读命令复核;后续远程脚本必须使用 BOM-free 字节流;关键步骤使用 set -euo pipefail 并检查每个阶段退出码。
  • 预防规则:远程 shell 脚本禁止直接使用可能带 BOM 的中文 PowerShell 字符串;部署后必须独立核对包哈希、备份、数据目录、服务状态、重启次数、插件加载、Archivist 和 traceback。
  • 验证证据:提交 7530774 已部署;包 SHA-256 一致;备份和 memory_companion.db 存在;astrbot.service active;NRestarts=0;Traceback=0;Q6_VM_SMOKE_OK;Archivist available=True search=True。

2026-07-25 — M6.1 Bot 个人记忆域与 Locked Frame 收口

  • 阶段:M6.1.1-M6.1.7 Bot 个人记忆模型、专用 Bridge、检索 Profile、只读观察窗与隔离测试
  • 类型:API契约 / 功能行为 / 测试
  • 现象:Locked Frame“个人记忆”原有分类主要依赖旧的 schedule/action/tag 类型,无法稳定识别四段式日程、睡前日记、创作、相册和主观记忆的新域。
  • 根因:Bot 自身数据与用户记忆、日历历史虽已在服务层分域,但页面入口未按 memory_domain=bot_self_schedule 做最终收口;陪伴侧也缺少专用远端写入和检索调用。
  • 修复或规避:新增 Bot 个人类型白名单和显式 Bridge 包装;默认检索继续阻止 Bot 域;Locked Frame 只读页面只接收 Bot 个人域或陪伴旧本地记录;远端 Bridge 失败时不阻断陪伴侧本地写入。
  • 预防规则:任何 Bot 自身日程读取必须显式使用 Bot personal profile;页面、Bridge、服务三层都要检查域、主体、可见性和来源,不能只看标签。
  • 验证证据:M6_MEMORY_TESTS_OK;compileall -q core tests page_api.py;git diff --check;专用 Bridge、幂等写入、默认检索隔离和观察窗分类已复核。

2026-07-26 — Bot Personal 独立域不等于真实性、幂等和只读合同完成

  • 阶段:M6.1.1~M6.1.6 源码复盘
  • 类型:API契约 / 数据隔离 / 功能行为
  • 现象:bot_self_schedule 已独立,但 bot_schedule_plan 被统一写成 observed/bot_action;记录 ID 同时包含幂等键和 payload,同键不同载荷会产生新 ID;Locked Frame 仍依赖陪伴插件私有运行对象。
  • 根因:Bot Personal 只完成类型和域骨架,尚未按类型定义真实性、字段必填、稳定 ID、版本竞争、专用 Profile 和纯归档只读 API。
  • 修复或规避:先冻结按类型合同和稳定幂等 ID,加入版本比较与递归白名单清洗;再实现 current/history/creative/subjective/locked-frame Profiles 和分层只读 API。
  • 预防规则:能力探测返回 idempotent_writes=true 前必须覆盖“同键不同 payload”和乱序版本测试;计划永远不能沿用 observed/bot_action 默认值。
  • 验证证据:core/service.py:867、core/store.py:1213、core/bot_personal.py:28、page_api.py:1229、docs/OPS双插件完整复盘与功能调整总方案.md。

2026-07-26 — M6.1.3-A Bot 归档可靠写入合同

  • 阶段:M6.1.3-A 记忆侧归档合同、可靠幂等写入和五类 Bridge
  • 类型:API契约 / 数据隔离 / 测试
  • 现象:旧 Bot Personal 写入把 payload 拼入 record_id、所有类型统一映射为 bot_action,通用 SQLite UPSERT 可静默覆盖乱序版本,递归隐私清洗也会静默丢弃字段。
  • 根因:此前只有逻辑域和类型骨架,没有独立的 envelope 校验、版本竞争和 Bot 专用原子写入路径。
  • 修复或规避:冻结 capability/payload schema 1.0;record_id 只由域、类型和幂等键生成;新增同键去重、新版本更新、旧版本拒绝和同版本冲突;五类类型固化真实性;递归拒绝敏感字段、完整聊天、凭据、Base64、媒体二进制和本机路径;写入强制 bot_self_schedule 与 bot_self。
  • 预防规则:任何 Bridge 能力只有在返回合同、错误码、版本竞争和隐私拒绝均有测试后才可声明 FROZEN;计划不得复用 observed/bot_action 默认值。
  • 验证证据:M6.1.3-A 定向 9 项通过;OPS 纯测试 143 项通过;compileall 通过;git diff --check 通过;共享合同已更新为 FROZEN。

2026-07-26 — M6.1.3-R1 联合审查阻断修复

  • 阶段:R1 记忆侧严格字段、canonical fingerprint、超限拒绝和兼容回归
  • 类型:API契约 / 数据隔离 / 测试
  • 现象:联合审查复现出非法日期、非法窗口、无时区时间可写入;20KB 字符串被静默截断;fingerprint 未覆盖 Envelope;plan 允许非 L0;旧 creative/media/subjective/shared 类型会落入 observed;部分运行错误码未声明。
  • 根因:第一版只完成 Bot 域和幂等骨架,没有把 FROZEN Envelope 的所有语义字段统一送入验证与 canonical fingerprint,非五类类型也使用了过宽默认合同。
  • 修复或规避:增加严格日期/窗口/时区解析;原始 JSON payload 先验大小再清洗;fingerprint 覆盖 payload、日期、窗口、发生时间、来源、确定性、证据等级、状态、版本、幂等键、schema 和 source_kind;plan 强制 L0;非五类恢复显式真实性和兼容 wrapper;错误码与 capability/共享合同同步。
  • 预防规则:FROZEN 合同的每个落库语义字段都必须有单独变化冲突测试;任何清洗前截断都视为数据完整性风险;旧能力不能用 observed 兜底。
  • 验证证据:R1 定向 15 项通过;OPS 纯测试 143 项通过;compileall 和 git diff --check 通过;共享合同字段规范仍为 FROZEN 1.0,实施验收保持 REOPEN_REQUIRED。

2026-07-26 — 兼容回归不能只用喂满 Envelope 的夹具

  • 阶段:M6.1.3-R1 联合复验
  • 类型:API契约 / 测试 / 数据隔离
  • 现象:R1 七项必修全部通过联合复验(严格时间、完整 fingerprint、超限拒绝、L0 规则、错误码覆盖、专用/通用一致);但“非五类兼容”测试因夹具恒带 date/window/occurred_at 而全绿,真实陪伴 DTO(date 为空)在联合链路上被 invalid_date 拒绝,5 个旧 kind 归档中断。
  • 根因:envelope_payload 夹具验证的是提供方视角的兼容,没有覆盖调用方真实 DTO 形状;另值级隐私清洗缺 base64,/data: URI 与路径中缀检测,弱于陪伴侧(纵深防御缺口)。
  • 修复或规避:M6.1.3-R2——补“date 由 occurred_at 派生”的真实形状兼容回归(date 为空仍必须 invalid_date,不放松校验,主修在陪伴侧);_FORBIDDEN_VALUE_PATTERNS 增加 base64/data URI 与中缀路径模式并配正反例。
  • 预防规则:对外兼容能力的回归必须包含调用方真实序列化输出样本;声明“禁止 Base64/本机路径”的合同必须有对应值级检测与测试,不能只依赖键名黑名单和上游拦截。
  • 验证证据:docs/M6.1.3双插件真实联合验收报告-R1复验.md P1-R2-1、P2-1;联合 E2E L 组与 P 组扫描。

2026-07-26 — 审计 Batch 1:报告的 B21 症状与源码不符,域判定集合被当成写入门禁

  • 阶段:OPS 源码审计整改 Batch 1(B12、B21、B23、B13)
  • 类型:API契约 / 数据隔离 / 测试
  • 现象:审计报告 B21 断言「ensure_defaults 缺 memory_decay_summary,衰减总结被判成 user_memory」。回读 core/models.py:100 发现 memory_domain 字段默认值是 "unknown"(真值),而 ensure_defaults 的分类分支写的是 if not self.memory_domain:,因此该分支只在调用方显式传 memory_domain="" 时才执行;core/service.py:4269 的衰减总结没有传域,落库实际是 unknown,被 _memory_domain_block_reason 判为 missing_user_subject,从来没有被判成 user_memory。
  • 根因:user_memory_boundary.BOT_SELF_MEMORY_TYPES 同时承担两件互相冲突的事——① 域判定(infer_memory_domain)② 用户记忆 Bridge 的写入门禁。memory_decay_summary 只应属于 ②;把它塞进同一个集合,才导致「models 的内联清单」与「boundary 的清单」看起来漂移。三个分类器里 models.ensure_defaults 与 user_memory_migration._classify:104 都判用户域,只有 infer_memory_domain 判 bot_self_legacy,少数派才是需要拆分的那一个。
  • 修复或规避:域判定的三个集合下沉到 core/models.py(最底层模块,避免 models ←→ user_memory_boundary 循环导入),由 user_memory_boundary 再导出,两个分类器共用同一个 frozenset 对象;新增 USER_MEMORY_WRITE_BLOCKED_TYPES = BOT_SELF_MEMORY_TYPES | {"memory_decay_summary"} 专供 validate_user_memory_record 的写入门禁,拒绝行为与错误码 bot_self_memory_type:memory_decay_summary 保持不变。未按报告字面把衰减总结改判 bot_self_legacy:那样会让默认开启(memory_decay_enabled default true)的睡眠衰减在压缩后既归档原片段、又屏蔽总结,等于把记忆从召回面彻底抹掉。
  • 预防规则:① 报告给出的「症状」必须先用源码复现再动手,dataclass 默认值为真值时 if not field: 分支可能是事实上的死分支;② 一个常量集合只能服务一个语义,域判定与写入门禁必须分开命名;③ 收紧写入门禁允许,放宽不允许——改动后必须有「同一条记录仍被拒绝且错误码不变」的用例;④ 任何会改变 memory_domain 归类的改动,都要先算「检索是否还召回得到」,压缩/归档链路上的域变更等同数据可用性变更。
  • 遗留(新发现,未在本批修):衰减总结当前落库域为 unknown,检索前置过滤直接屏蔽,而源片段已被 archive_memories 归档(lifecycle=archived 被候选查询排除),因此睡眠衰减压缩后的内容在主线检索中不可召回。这是 B10(域放行意图)同一类问题,需与 B10 一起确认产品意图后处理。
  • 验证证据:tests/test_audit_batch1_fixes.py::MemoryDomainConstantSourceTests(6 项:常量同一对象、ensure_defaults 不再内联清单、两分类器一致、衰减总结域一致、写入门禁仍拒绝且错误码不变、默认值陷阱固化);OPS 纯测试 198 项通过;联合 E2E 85/81/4 与 R1 基线失败集合完全一致。

2026-07-26 — 审计 Batch 1:未转义 LIKE、恢复计数与记忆侧 naive 时钟

  • 阶段:OPS 源码审计整改 Batch 1
  • 类型:数据隔离 / 可观测性 / 时间感知
  • 现象:
    • B12 core/store.py:3941:list_memories(entity_id=...) 用 f"%{entity}%" 裸 LIKE。实测 entity_id="u_1" 会同时命中 qq:FriendMessage:uX1(_ 被当成单字符通配),跨会话串记忆。
    • B23 core/store.py:110:_database_recovery_successes += 1 写在 return operation(*args) 之前,恢复后重试再次失败也计为成功,wal_health 的恢复成功率指标失真。
    • B13 core/service.py:2548/7203/7722:时段判定与 token 分桶用 naive datetime.now(),UTC 容器上相对全局 Asia/Shanghai 偏 8 小时,by_day/by_hour 键和「深夜查岗」判定都会错档。
  • 根因:同文件已有 _like_pattern/_like_id 转义工具但该处漏用;计数语义把「已尝试恢复」当成「恢复成功」;记忆侧没有统一的「当前本地时间」入口,各处各写。
  • 修复或规避:B12 改 session_id LIKE ? ESCAPE '\' + self._like_pattern(entity);B23 先 result = operation(*args) 成功后再自增;B13 在 core/temporal_context.py 新增公共 local_now(timezone_name=DEFAULT_TIMEZONE)(带时区、非法时区回落 Asia/Shanghai),三处调用点统一改走它。
  • 预防规则:① 任何 LIKE 都必须走转义 helper 并显式带 ESCAPE,禁止裸 %{value}%;② 成功类计数器只能在被计数的操作真正返回之后自增;③ 记忆侧禁止 naive datetime.now(),一律走 local_now() 或显式 tz,并用 AST 扫描把这条规则钉死在测试里。
  • 验证证据:tests/test_audit_batch1_fixes.py 的 EntityLikeEscapeTests(3 项,含 _/% 反例与正常 ID 正例)、DatabaseRecoveryCounterTests(3 项,含二次失败不计数、成功只计一次、非路径错误不动计数器)、MemorySideTimezoneTests(5 项,含 AST 扫描 core/*.py+page_api.py+main.py 无 naive datetime.now());改前/改后 SQL 对照已实测(改前返回 mem_neighbor+mem_underscore,改后只返回 mem_underscore)。

2026-07-26 — 记忆纯测试的 181 项只有 pytest 能收齐

  • 阶段:审计 Batch 1 回归基线
  • 类型:测试 / 环境
  • 现象:优化方案 README 写「记忆纯测试(现 181 项)」,但 python -m unittest 按模块跑只有 143 项,容易被误判为「测试少了 38 项」。
  • 根因:tests/test_archive_contract.py、test_bot_personal_memory.py、test_q6_user_fact_bridge.py、test_temporal_context.py 用的是模块级 test_* 函数,unittest 只收集 TestCase 子类,收不到这些函数。
  • 修复或规避:以 pytest 收集数为纯测试口径,命令固定为 python -m pytest -q --ignore=tests/test_security_cache.py(test_security_cache 导入普通陪伴分支且本机无 AstrBot 宿主包,属环境阻塞不是业务回归);需要 unittest 口径时另记 TestCase 计数。
  • 预防规则:报告里的测试项数必须写清收集器;换收集器前后的数字不可直接相减当成回归。
  • 验证证据:本轮基线 pytest 181 项通过 / unittest 143 项通过;补测后 pytest 198 项通过 / unittest 160 项通过。

2026-07-26 — 值级隐私模式锚定行首,等于只防了「整条就是路径」

  • 阶段:M6.1.3-R2 记忆侧防御加固(M2)
  • 类型:隐私 / API契约 / 测试
  • 现象:_FORBIDDEN_VALUE_PATTERNS 的路径模式写成 ^(?:[A-Za-z]:[\/]|/|\\),只有「整个字符串就是一条路径」才拦得住。实测 8 类真实写法全部漏过:data:image/png;base64,...、封面图 base64,xxx、照片保存在 D:\private\a.png 了、\nas\share、/home/、/tmp/、/volume1/、-----BEGIN RSA PRIVATE KEY-----。合同第 130 行明写禁止 Base64、媒体二进制和任意本机绝对路径,所以这不是纵深防御的可选项,是合同缺口。
  • 根因:写模式时脑子里的样本是「字段值 = 路径」,而真实 payload 里路径几乎总是嵌在中文句子中间。另一边陪伴侧 _looks_sensitive_value() 早就用了 (?:^|[\s=]) 中缀写法,两侧从未对照过。
  • 修复或规避:保留原前缀模式(本侧 ^/ 比陪伴侧更严,不能退),新增中缀路径、base64,、data: URI、-----begin 四条,与陪伴侧对齐。clean_text() 在匹配前已把空白折叠成单空格,因此 (?:^|[\s=]) 不存在换行绕过。全部复用 privacy_rejected,capability 的 25 码清单无需变动。
  • 预防规则:值级敏感检测一律按「嵌在自然语言里」设计,禁止只写 ^ 锚定;双方各有一份检测规则时,要有一个直接对照两份规则的用例,而不是各自测各自的。误杀同样要钉死:正常中文句子、docs/a.md、./x、https:// 必须有反例测试。
  • 验证证据:tests/test_m6_r2_real_dto_shape.py 14 条正例(全部 privacy_rejected)+ 9 条反例(全部写入成功);逐条对比 R1 四模式与 R2 八模式,8 类漏检全部转为拦截,正常文本仍不误杀;记忆侧 243 项、联合 E2E 90 项通过。

2026-07-26 — 兼容回归要用调用方真实序列化输出,不是自造夹具(执行记录)

  • 阶段:M6.1.3-R2 记忆侧回归(M1)
  • 类型:测试 / API契约
  • 现象:承接上一条同名预防规则。本轮落地时确认,本仓 tests/test_bot_personal_memory.py 的 envelope_payload() 恒在 payload 里塞满 date/window/occurred_at,而陪伴真实 DTO 是「信封字段走 kwarg、body 里根本没有 date」的两层结构;两种形状连字段位置都不同,自造夹具再全也测不到真实链路。另外 test_non_five_legacy_types_keep_explicit_truth_mapping 只覆盖 6 类,bot_calendar_event 从未被测过——而它正是 E2E L 组失败的五个 kind 之一。
  • 根因:提供方写兼容测试时按自己的 API 签名造夹具,没有拿调用方的实际输出做样本。
  • 修复或规避:新增 tests/test_m6_r2_real_dto_shape.py:能拿到陪伴仓时直接 import 它真实的 build_bot_personal_dto(该模块只依赖标准库,可独立载入)跑 7 类;拿不到时退回逐字复刻的真实形状样本,两条路径都保证 body 里没有 date。补齐 bot_calendar_event,并加一条断言把覆盖集合钉在 BOT_PERSONAL_TYPE_CONTRACTS 减严格五类上,防止以后新增类型漏测。
  • 预防规则:跨插件兼容回归必须包含调用方真实序列化输出样本;「覆盖了哪几类」这种事要用集合断言钉住,不能靠人肉核对清单。
  • 验证证据:tests/test_m6_r2_real_dto_shape.py 45 项通过(含 7 类真实 DTO + 7 类复刻样本 + calendar_event 专项 + date 空/非法/naive occurred_at 三条「不放松校验」);记忆侧总计 243 项通过,compileall 通过。

2026-07-27 — 滚动升级窗口里,payload 形状变化就是一次静默数据丢失

  • 阶段:M6.1.4 分域与形状归一
  • 类型:API契约 / 部署 / 测试
  • 现象:陪伴侧把非五类的通用回退从「整包送 envelope」改成「送 body」。两种形状剥离信封字段后内容其实等价,但指纹不同——整包形状剥完只剩 {"payload": {...}},body 形状剥完是 {...}。双插件是分别部署的(M6.1.8 明确先记忆后陪伴),升级窗口里同一条记录会先后以两种形状到达,第二次必然 version_conflict → 永久错 → 死信。另外发现 created_at/updated_at 不在剥离清单里,它们随墙钟漂移,同一条记录隔一小时重投就变 version_conflict。
  • 根因:剥离清单是按「验证需要哪些字段」列的,不是按「哪些是信封字段」列的,于是漏了一批只在整包形状下才会出现的键。归一化顺序也有坑:必须先解包再剥离,反过来内层的 source_refs 会留在 body 里,两种形状仍然对不上。
  • 修复或规避:提取 BOT_PERSONAL_ENVELOPE_KEYS(17 个)作为唯一事实源;record_bot_personal_memory 先判断「除 payload 外全是信封字段」再解包,然后统一剥离。两种形状因此产生同一个指纹,旧版陪伴仍可写入。
  • 预防规则:接收方的兼容性不能只保证「旧形状不报错」,还要保证「旧形状与新形状指纹一致」——否则升级窗口里的重投会被当成内容冲突。凡是分别部署的两个组件,改动线上载荷形状时必须补一条「新旧形状互认」的回归。
  • 验证证据:tests/test_m6_r2_real_dto_shape.py::test_whole_envelope_shape_stays_backward_compatible(两种形状 → deduplicated)与 test_envelope_timestamps_do_not_drift_the_fingerprint;联合 E2E 101 项全通过。

2026-07-27 — 域索引的前缀顺序决定了它对分类型检索毫无用处

  • 阶段:M6.1.4 创作/媒体/主观独立索引
  • 类型:性能 / 数据模型
  • 现象:idx_memories_domain 是 (memory_domain, lifecycle, scope, group_id, subject_id)。而创作/媒体/主观的检索形态是「域内按 memory_type 过滤、按时间倒序取最近若干条」,memory_type 不在索引前缀里,这类查询只能退化成域内全扫描。索引存在,但对这条路径完全用不上。
  • 根因:索引是按「Bot 域 vs 用户域」的隔离需求建的,没有按后续 Profile 检索的实际形态复核过;有索引这件事本身容易让人以为已经覆盖。
  • 修复或规避:新增 idx_memories_domain_type_time (memory_domain, memory_type, occurred_at DESC),匹配「域 + 类型 + 时间倒序」这一形态。M6.1.5 的 Bot Profiles 全部走这条。
  • 预防规则:加索引前先写出目标查询的 WHERE + ORDER BY,再对照索引前缀逐列核;「表上已经有索引」不能作为「这条查询走了索引」的证据。
  • 验证证据:tests/test_m6_r4_creative_media_domain.py::test_domain_type_time_index_exists 与分类型过滤三项。

2026-07-27 — 「先按时间倒序取 N 条,再在内存里筛时间窗」等于把历史查询废掉

  • 阶段:M6.1.5 Bot 专用检索 Profiles
  • 类型:数据模型 / 性能 / 测试
  • 现象:bot_schedule_history 上线即静默返回空。实现是 list_memories(limit=N) 再在 Python 里按时间窗过滤,而 list_memories 本身按 occurred_at DESC 排序截断——只要近期记录够多,落在「1 到 90 天前」这个窗口里的行根本进不了那 N 条结果集。单元测试里数据少,怎么测都是对的;联合 E2E 因为前面各组已经积累了大量当天记录,一跑就空。
  • 根因:把「范围约束」和「取前 N 条」的顺序搞反了。SQL 的 LIMIT 作用在排序之后,任何写在 Python 里的后置过滤都是在一个已经被截断的集合上做的。
  • 修复或规避:新增 list_bot_profile_memories(),把域、类型、occurred_at 区间全部放进 WHERE,走 M6.1.4 建的 idx_memories_domain_type_time;Python 侧只保留精确边界判定。补 test_many_recent_records_do_not_starve_the_history_profile(60 条当天记录 + 1 条三天前)钉死。
  • 预防规则:凡是「过滤条件 + LIMIT」的查询,过滤必须进 SQL;在内存里后筛只有在「先取全量」时才等价。这类 bug 在小数据集上永远测不出来,回归用例必须显式构造「近期记录远多于 limit」的场景。
  • 验证证据:tests/test_m6_r5_bot_profiles.py 28 项;联合 E2E S 组「历史 Profile 只给过去内容,不含当天」。

2026-07-27 — 检索 Profile 的价值全在「调用方改不了」

  • 阶段:M6.1.5 Profile 契约
  • 类型:API契约 / 隐私
  • 现象:改造前只有一个 search_bot_personal_memory(query, limit, memory_types),类型和条数都由调用方传。陪伴侧的用法是一次性传 11 个类型、limit 5——所谓「Bot 专用检索」实质就是一次全库通用检索,当前状态和历史记忆混在同一批结果里返回。
  • 根因:把 Profile 理解成「一组默认参数」,而不是「一份调用方改不了的契约」。只要类型、时间窗、条数任意一项可以被调用方覆盖,专用检索就会退化回通用检索。
  • 修复或规避:core/bot_profiles.py 把七件事(域/类型/时间范围/条数/排序/注入字段/权限)全部固定在记忆侧;调用方只能选 Profile 名,limit 只能往小调不能往大调;注入字段走白名单投影,serialize_memory 带出的人格权重、指纹、幂等键一律不出现在结果里;capability 公布契约,两侧不必各自猜测限制。
  • 预防规则:给出「专用入口」时,先列清楚哪些维度必须由提供方固定;每个维度都要有一条「调用方试图突破 → 被夹住」的测试,否则契约只是文档里的一句话。
  • 验证证据:test_every_profile_pins_all_seven_dimensions、test_limit_can_be_lowered_but_not_raised、test_projection_drops_internal_fields、test_profiles_never_return_user_memories;联合 E2E S 组 13 项。

2026-07-27 — 默认值是真值,于是「没传就自动分类」那条分支从来没跑过

  • 阶段:P0 生产缺陷清理
  • 类型:数据一致性 / 检索可用性
  • 现象:默认开启的睡眠衰减把一批稳定记忆压成一条 memory_decay_summary 落库、再把原片段改成 archived。摘要落库的 memory_domain 恒为 unknown,被 RetrievalEngine._memory_domain_block_reason 判成 missing_user_subject、在打分之前就被前置过滤;而源片段已归档、被 lifecycle != 'archived' 的候选查询排除。摘要召回不到 + 原文召回不到 = 整段主线消失,无告警、无回滚、无 dry-run,每跑一晚制造一批死数据。
  • 根因:两层。表层是 _summarize_decay_group 构造 MemoryRecord 时没传 memory_domain。深层是 MemoryRecord.memory_domain 的 dataclass 默认值写的是 "unknown"——一个真值,于是 ensure_defaults 里 if not self.memory_domain: 那条自动分类分支成了死分支,只有调用方显式传 "" 才会执行。「不传就自动分类」这个心智模型与实际行为相反,而两者都不报错。
  • 修复或规避:摘要显式继承来源片段的域(sample.memory_domain),来源是 user_memory 就产出 user_memory 摘要,来源本来是 bot_self_legacy/unknown 则原样继承,隔离边界一点不放宽;分桶键加上域,避免同一个桶混域导致「摘要该落哪个域」没有确定答案;归档前回读摘要、用检索侧同一个闸门校验可召回性,只要来源本来召回得到而摘要召回不到就跳过归档并 WARNING——把「静默产生死数据」换成「有告警、原文仍在」;新增 maintenance.memory_decay_dry_run 试运行开关,照常筛选与生成摘要但不写库不归档。没有动 ensure_defaults 的默认值:那会改变所有未显式传域的写入点的归类,爆炸半径太大,且现有测试已把当前行为钉死。
  • 附带收获:tests/test_security_cache.py 连续五轮被排除的那 2 个失败用例,根因就是同一个陷阱——夹具 group_memory() 构造记录不传域 → 落库 unknown → search 恒返回空集。它们要测的是 ACL 与缓存失效,不是域分类;夹具补上显式域后 6 项全通过,该文件不必再排除在测试口径外。
  • 预防规则:给「缺省时自动推断」的字段设默认值,默认值必须是假值(""/None),否则推断分支永远不会执行,而且不报错。凡是「压缩/合并/归档」这类会让原始数据不可访问的操作,都要在丢弃原文之前回读一次产物、用消费侧同一个判据确认它真的可用——不能只断言「写进去了」。
  • 验证证据:tests/test_sleep_decay_recall.py 5 项(含端到端召回、按域分桶、非用户域仍正常清理且隔离不放宽、摘要不可召回则跳过归档并告警、dry-run 零写入)。反证:临时摘掉域继承后,端到端召回那条必红(reason=missing_user_subject),且新守卫当场拦下归档。全量 330 项通过(此前 323 通过 / 2 失败)。

2026-07-27 — 跨仓测试写死「同级目录」,换个布局就静默降级

  • 阶段:P2 验收可信度收口
  • 类型:测试 / 环境
  • 现象:test_m6_r2_real_dto_shape.py 用 parents[2] / "astrbot_plugin_private_companion-main" 定位陪伴仓,VM 上不是这个布局,于是 7 个「用陪伴侧真实 DTO 回归」的用例 skipif 恒成立——真机验收时这组从没跑过,跨插件信封形状的唯一真实校验在最需要它的环境里是空的。test_ops_migration.py 更直接:import 失败,只能手工挂 PYTHONPATH 绕过,而那次绕过又让记忆侧的 core/ops_migration.py 遮蔽了陪伴侧同名模块,产生两个假失败。
  • 根因:每个测试各写各的相对路径,把「两个仓库是同级目录」这一种开发布局当成了唯一布局。而 skip 是静默的:结果里只少了几个点,不会红。
  • 修复或规避:定位逻辑收进 tests/_companion_repo.py,按「环境变量 COMPANION_PLUGIN_ROOT → 同级开发目录 → 同级部署目录(_ops 后缀)→ 再上一层」依次尝试;ensure_companion_on_path 明确把陪伴目录插到 sys.path 最前面,避免同名模块遮蔽——顺序反了会以「跑绿了但测错了对象」的形态失败,比 ImportError 难查得多。
  • 预防规则:跨仓/跨目录的路径假设要收成一处并允许显式覆盖,不要每个文件各写一遍。skipif 的条件如果可能在某个环境里恒成立,就等于那个环境没有这条覆盖——要么让定位更健壮,要么让 skip 的原因出现在验收记录里。
  • 验证证据:tests/test_m6_r2_real_dto_shape.py + tests/test_ops_migration.py 共 52 项通过;全量 330 项通过。

2026-07-27 - Retire the calendar history domain

  • Phase: D6 domain cleanup.
  • Type: API contract / migration / retrieval behavior.
  • Symptom: bot_calendar_event had a production producer, but the separate calendar_history domain was rejected by the public bridge and only direct service tests could write it.
  • Root cause: the calendar event type and its private Bot-memory ownership were conflated with a second, non-queryable domain.
  • Fix or workaround: retain bot_calendar_event as a Bot-private event with reality level calendar_event; retire the direct calendar writer; remove the domain constant, migration target, historical injection marker, and archive flag.
  • Prevention rule: a contract type may remain supported only through its real producer; do not preserve a second storage domain when the public write path rejects it.
  • Validation evidence: targeted D5/D6 regressions and pytest -q --ignore=tests/test_security_cache.py passed 325 tests plus 8 subtests; commit e884138 is deployed, VM hashes match, D5 is true, no D6 core references remain, service is active, and NRestarts=0.
  • Supersedes: the 2026-07-24 Q4.2 calendar-history write path.

2026-07-27 - Default user-fact session isolation

  • Phase: D5 privacy-boundary implementation.
  • Type: API contract / retrieval behavior / test.
  • Symptom: the archive API defaulted to strict session isolation, while bridge_query_user_facts explicitly replaced a missing flag with False; same-user facts could cross chat sessions.
  • Root cause: two bridge entrypoints used contradictory defaults for the same strict_session_only policy.
  • Fix or workaround: bridge_query_user_facts now defaults the omitted flag to True; callers can only relax it by explicitly supplying false.
  • Prevention rule: every user-fact lookup must inherit the same default isolation policy as archive search; cross-session negative tests must exercise the public bridge path.
  • Validation evidence: the D5 bridge-to-visibility negative test, focused migration/contract tests, and 325 pytest tests plus 8 subtests passed; commit e884138 is deployed with matching VM hashes, active service, and NRestarts=0.