42 KiB
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; storedmemory_type=calendar_event,memory_layer=calendar_history, source and time metadata; derived a stable memory id fromevent_id; SQLite conflict updates now excludecreated_atand update status plusupdated_atonly. - 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 verifiescreated_atpreservation,updated_atchange, layer isolation and no persistedage_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 andpy_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 discoverran 137 test entries, with 136 passing andtest_security_cachefailing during collection because it imports the ordinary companion branch and the environment has noastrbotpackage. - Root cause: the existing test module resolves
page_apifromastrbot_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 testsandgit diff --checkpassed.
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.2loaded;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;Archivistavailable=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复验.mdP1-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_enableddefault 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 分桶用 naivedatetime.now(),UTC 容器上相对全局Asia/Shanghai偏 8 小时,by_day/by_hour键和「深夜查岗」判定都会错档。
- B12
- 根因:同文件已有
_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}%;② 成功类计数器只能在被计数的操作真正返回之后自增;③ 记忆侧禁止 naivedatetime.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无 naivedatetime.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.py14 条正例(全部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.py45 项通过(含 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.py28 项;联合 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.py5 项(含端到端召回、按域分桶、非用户域仍正常清理且隔离不放宽、摘要不可召回则跳过归档并告警、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_eventhad a production producer, but the separatecalendar_historydomain 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_eventas a Bot-private event with reality levelcalendar_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.pypassed 325 tests plus 8 subtests; commite884138is deployed, VM hashes match, D5 is true, no D6 core references remain, service is active, andNRestarts=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_factsexplicitly replaced a missing flag withFalse; same-user facts could cross chat sessions. - Root cause: two bridge entrypoints used contradictory defaults for the same
strict_session_onlypolicy. - Fix or workaround:
bridge_query_user_factsnow defaults the omitted flag toTrue; callers can only relax it by explicitly supplyingfalse. - 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
e884138is deployed with matching VM hashes, active service, andNRestarts=0.