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

118 行
10 KiB
Markdown

# 运维记忆插件错题本
> 适用仓库:`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、服务状态和数据目录。