2026-07-27 14:55:44 +08:00
# 运维记忆插件错题本
2026-07-25 01:35:22 +08:00
> 适用仓库:`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 23:29:48 +08:00
## 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 23:39:08 +08:00
## 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 23:41:55 +08:00
## 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-26 02:14:15 +08:00
## 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-26 02:21:59 +08:00
## 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-26 03:14:04 +08:00
## 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-27 01:37:20 +08:00
## 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 项。
fix: keep sleep-decay summaries retrievable, and stop excluding two tests
Sleep decay compresses a batch of stable memories into one summary row and
archives the originals. The summary was built without memory_domain, and
MemoryRecord.memory_domain defaults to "unknown" -- a truthy value, so the
`if not self.memory_domain:` classification branch in ensure_defaults has
never once executed. The summary stored as unknown, the retrieval gate only
admits user_memory and drops it before scoring, and the sources were already
archived out of the candidate query. Summary unreachable plus originals
unreachable meant the whole thread disappeared, silently, every night the
job ran.
Summaries now inherit the domain of their source records, and the decay
bucket key includes the domain so a bucket cannot mix domains and leave the
question undecidable. Before archiving anything, the summary is read back and
checked through the same gate the retrieval side uses; if the source was
reachable and the summary is not, the archive is skipped with a warning
rather than turning live memory into dead rows. A maintenance.memory_decay_
dry_run switch runs the whole selection and summarisation without writing.
ensure_defaults itself is left alone -- changing that default would reclassify
every write that omits a domain.
The two test_security_cache tests that have been excluded from the test
command for five rounds turned out to have the same root cause: the fixture
built a record without a domain, so search returned an empty set. Those tests
are about ACL and cache invalidation, not domain classification; with an
explicit domain the file passes 6/6 and no longer needs excluding.
Memory suite 330 passed, was 323 passed / 2 failed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 05:27:07 +08:00
## 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 失败)。
test: locate the companion repo instead of assuming one layout
test_m6_r2_real_dto_shape resolved the companion repo as a sibling directory,
which is only true of the development checkout. On the VM the skipif was
always true, so the seven cases that exercise the companion's real DTO builder
-- the only genuine check of the cross-plugin envelope shape -- never ran in
the environment that most needed them, and a skip shows up as a missing dot
rather than a failure.
test_ops_migration had the harder version of the same bug: the import simply
failed, and working around it with PYTHONPATH let the memory side's own
core/ops_migration shadow the companion module, producing two failures that
looked like product defects and were not.
Resolution now lives in tests/_companion_repo.py and tries, in order, the
COMPANION_PLUGIN_ROOT override, the sibling development directory, the
sibling deployed directory (_ops suffix), and one level up. The path helper
inserts at the front of sys.path deliberately: getting that order wrong fails
as "green but testing the wrong module", which is worse than an ImportError.
Memory suite 330 passed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 05:41:32 +08:00
## 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 14:55:44 +08:00
## 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.
- 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.