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

6.9 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.