astrbot_plugin_memory_compa.../docs/错题本.md

183 行
17 KiB
Markdown

# 错题本
## 2026-07-22 — 测试仍引用插件旧包名
- 阶段:源码复盘与回归验证
- 类型:测试 / 构建
- 现象:在仓库目录直接运行 `python -m pytest -q` 时,12 个测试模块全部在收集阶段报 `ModuleNotFoundError: No module named 'astrbot_plugin_remember_you'`。
- 根因:插件正式包名已经变更为 `astrbot_plugin_memory_companion`,但测试文件仍从旧包名 `astrbot_plugin_remember_you` 导入。
- 修复或规避:本次未修改业务源码;通过把仓库临时复制为旧包名验证测试本体,122 个测试全部通过。后续应统一测试 import 到正式包名,或在测试夹具中建立显式兼容别名。
- 预防规则:插件改名、仓库改名或 metadata 名称调整时,必须全仓搜索旧包名,并在干净目录执行一次测试收集。
- 验证证据:临时别名目录执行测试得到 `122 passed in 17.75s`;两个仓库 `compileall` 均通过。
## 2026-07-22 — 本阶段复盘
- 阶段:消息流与架构复盘
- 类型:API契约 / 功能行为
- 现象:无新增业务逻辑错误被测试触发。
- 根因:不适用。
- 修复或规避:确认主链注入失败时会放行 LLM,请求命令和内部生成会跳过记忆捕获;Bridge 在终止时会清理活动实例。
- 预防规则:后续改动必须保持“记忆失败不阻断聊天”“可见性先于召回”“陪伴插件只通过 Bridge 写长期事件”三条边界。
- 验证证据:源码追踪 `main.py`、`core/service.py`、`core/store.py`、`core/bridge.py`,并完成 122 个测试的别名验证。
## 2026-07-22 — 白话复盘文档阶段检查
- 阶段:文档交付
- 类型:其他
- 现象:本阶段未修改插件源码,也未发现新的运行问题。
- 根因:不适用。
- 修复或规避:新增独立白话注释版复盘文件,保留原专业版不变。
- 预防规则:后续功能方案同时保留技术定义和面向产品讨论的白话说明,避免术语理解差异造成需求偏差。
- 验证证据:白话版覆盖插件职责、消息流、已知问题和 Q0 至功能开发的实施顺序。
## 2026-07-22 — 生产平台与记忆事实边界
- 阶段:VM 运维人格融合评估
- 类型:API契约 / 功能行为 / 安全
- 现象:生产 AstrBot 使用 QQ Official,但插件 metadata 当前只声明 aiocqhttp;同时运维历史记忆容易被模型误当成当前机器状态。
- 根因:插件最初围绕通用陪伴记忆设计,尚未按生产的 QQ Official 身份维度和机器事实源要求完成验收。
- 修复或规避:改造前增加 QQ Official 支持、`platform + bot_instance + user_id + chat_id` 隔离测试和运维事件类型;运维记忆只保存安全摘要与 Controller 引用,实时状态必须重新调用工具确认。
- 预防规则:任何“当前服务正常、任务完成、操作已执行”的回答都必须来自本轮工具或控制器结果,不能只来自长期记忆。
- 验证证据:VM 公开接口确认 AstrBot 4.26.6;Ops Suite 明确以 Forgejo Commit 和中央 Controller 分别作为代码与任务事实源。
## 2026-07-23 — 归档 API 改造评估的测试导入阻塞
- 阶段:归档公开 API 改造评估
- 类型:测试 / 环境
- 现象:在 `astrbot_plugin_memory_companion-main` 根目录执行 `pytest -q` 时,12 个测试模块在收集阶段报 `ModuleNotFoundError: astrbot_plugin_remember_you`,未进入测试用例。
- 根因:源码目录名与测试使用的可导入包名不一致,当前工作树没有安装包或测试别名映射。
- 修复或规避:本阶段先完成静态源码核对;恢复测试时统一确定正式包名,并通过可编辑安装、测试配置或明确的导入映射解决,不修改生产逻辑绕过导入问题。
- 预防规则:跨插件 API 改造开始前先执行一次“包名/导入路径/测试入口”冒烟检查;测试收集失败时不得把未执行测试当作通过。
- 验证证据:`pytest -q` 于 2026-07-23 收集阶段失败;失败信息已记录在本阶段评估文档。
## 2026-07-23 — 归档出口不能复用主链默认序列化
- 阶段:归档公开 API 改造评估
- 类型:API契约 / 安全
- 现象:现有归档接口已经存在,但 `_archive_payload` 直接复用通用 `serialize_memory`,而归档需求要求敏感信息清洗、最小字段和 `redacted` 标记。
- 根因:主链注入和外部归档对字段宽度、原始证据和 `bot_self` 默认行为的安全要求不同。
- 修复或规避:规划中增加独立 `ArchiveContract`、`ArchiveVisibilityPolicy` 和 `ArchiveRedactor`,归档出口不再把主链序列化结果视为稳定合同。
- 预防规则:任何跨插件公开 API 必须先建立最小字段白名单和独立安全 profile,再复用内部模型。
- 验证证据:已核对 `core/bridge.py`、`core/service.py`、`core/visibility.py` 与需求文件;现状缺口已写入 `docs/MEMORY_ARCHIVIST_ARCHIVE_API_REFACTOR_PLAN.md`。
## 2026-07-23 — 归档 API 本地实现阶段复盘
- 阶段:A0-A6 归档公开 API 实施
- 类型:编码 / 测试 / API契约
- 现象:归档接口原有骨架可用,但字段合同、清洗、bot_self 默认策略、空查询保护和 Page API 均不完整;测试入口还存在旧包名和根目录包收集问题。
- 根因:早期实现优先复用了主链序列化和可见性策略,未把外部归档当作独立安全边界。
- 修复或规避:新增 core/archive_contract.py,引入归档专用 payload、redactor 和 capability;增加 archive visibility profile、空查询拒绝、Page API、默认关闭的确认写入,并用 pytest.ini 固化根目录测试入口。
- 预防规则:跨插件输出必须使用最小字段合同和独立安全策略;本地测试通过后仍需在 AstrBot VM 做鉴权和真实生命周期验收。
- 验证证据:python -m compileall 通过;pytest -q 通过(2026-07-23:128 passed);VM 验收尚未执行。
## 2026-07-23 — VM 部署与 A7 验收
- 阶段:A7 VM staging 部署
- 类型:部署 / 测试 / 环境
- 现象:VM 原先没有 `astrbot_plugin_memory_companion` 插件目录;远端 staging 使用 `astrbot` 用户运行 compile/test 时遇到上传缓存目录归属问题,且 VM Python 没有 pytest。
- 根因:本地递归上传包含由 Windows 用户生成的 `.pytest_cache` 和 `__pycache__`,服务用户不能删除或覆盖;生产运行环境只提供 AstrBot runtime,不包含 pytest。
- 修复或规避:部署前执行统一加密备份;清理临时目录时限定到本次创建的 staging 路径;以 root 复制后恢复 `astrbot:astrbot` 归属;使用 AstrBot 实际 Python 做归档模块烟测,测试回归以本地 `pytest -q` 的 128 passed 为依据。
- 预防规则:发布包必须排除测试缓存和字节码;VM 只做运行时 smoke test,完整 pytest 保留在构建机;部署前后必须记录备份归档、服务 PID/NRestarts、插件启动日志和 API 鉴权结果。
- 验证证据:备份 `astrbot-system-20260723T143423Z.tar.gz.enc` 成功;`astrbot.service active`、`NRestarts=0`;日志确认插件 1.6.2 启动;五个归档 Page API 未认证返回 401;本地 `pytest -q` 为 128 passed。
## 2026-07-23 — VM 安装 pytest 并完成远端回归
- 阶段:A7 VM 测试环境补齐
- 类型:测试 / 环境
- 现象:VM 原先没有 pytest,无法在已部署插件目录执行完整回归。
- 根因:AstrBot runtime 自带 pip,但 pytest 未包含在生产运行依赖中。
- 修复或规避:使用 `/var/lib/astrbot/.local/share/uv/tools/astrbot/bin/python -m pip install pytest` 安装到 AstrBot runtime,不修改系统 Python,不重启服务。
- 预防规则:部署前先检查 runtime 的测试工具;生产环境补充测试工具后要记录安装位置和版本,避免误装到系统 Python。
- 验证证据:VM `pytest 9.1.1`;在 `/var/lib/astrbot/data/plugins/astrbot_plugin_memory_companion` 执行 `pytest -q`,结果 `128 passed, 1 warning`。警告为 `main.py:38` 的 AstrBot `register_star` 弃用提示。
## 2026-07-23 — 认证态归档 API 与隔离测试复盘
- 阶段:A7 认证态与真实运行时验收
- 类型:测试 / 安全 / API契约
- 现象:Dashboard 登录态可加载 MemoryCompanion 页面并完成普通召回,但浏览器客户端不允许直接导航认证 API JSON,VM 也没有 Dashboard 凭据可供 shell 使用。
- 根因:浏览器控制面限制直接 API 导航,且认证 Cookie 属于敏感凭据,不能读取或复制到命令行。
- 修复或规避:通过已登录页面执行只读 UI 召回测试;通过 VM AstrBot 实际 Python 在隔离临时数据库中直接调用部署后的 archive Service,验证合同、scope、证据、清洗和写入关闭,不绕过认证。
- 预防规则:认证测试优先复用现有 UI 或正式 API 客户端;不得提取 Cookie 伪造命令行会话;真实数据测试必须使用隔离临时库。
- 验证证据:Dashboard UI 召回 `0 Hits / 0 Blocked`;VM capability、empty query、evidence、session context、write disabled 和五类隔离/清洗断言均通过。
## 2026-07-23 — 产品分支不能只隔离代码
- 阶段:普通陪伴版与专用运维版分线评估
- 类型:部署 / API契约 / 功能行为
- 现象:只创建 `companion-main` 和 `ops-main` 分支,但继续使用相同插件名和数据目录,会让安装、数据、扩展页和更新流程仍然互相覆盖。
- 根因:当前 `PLUGIN_NAME` 同时决定 AstrBot 注册身份、`StarTools.get_data_dir()` 数据目录和页面路由,分支名本身不会参与运行时隔离。
- 修复或规避:运维版采用 `astrbot_plugin_memory_companion_ops` 独立身份,并同步修改注册、数据目录、页面路由、Bridge 发现、备份合同和更新源;普通数据只做一次性复制迁移。
- 预防规则:任何长期产品分线都必须同时检查代码分支、插件身份、数据目录、发布包和更新源五层隔离,不能把 Git 分支误当成运行时隔离。
- 验证证据:已核对 `main.py` 与 `page_api.py` 中的 `PLUGIN_NAME`、数据目录和路由用法,并形成 `双分支运维版可行性评估.md`。
## 2026-07-23 — 运维记忆分支建立并完成身份隔离
- 阶段:运维分支初始化与第一批代码改造
- 类型:环境 / 测试 / API契约
- 现象:源码快照没有 Git 历史;Git 初始化后触发 dubious ownership;系统命令中没有 python;旧 benchmark 仍引用 astrbot_plugin_remember_you。
- 根因:目录所有者与沙箱执行用户不同;Windows 环境未把 Python 放入 PATH;benchmark 未跟随插件改名。
- 修复或规避:建立 companion-main 基线、upstream-sync 和 ops-main;Git 使用仓库级 safe.directory;测试使用 Codex bundled Python;benchmark 改用 astrbot_plugin_memory_companion_ops。此前关于“全部测试因旧包名无法收集”的记录在当前基线已被本条取代,当前测试直接引用 core 包。
- 预防规则:后续版本改名必须同步检查 main、metadata、页面路由、Bridge、历史导入、运维诊断、benchmark 和测试;测试结果必须来自当前分支实际执行。
- 验证证据:companion-main 基线提交为 2f24824,当前分支为 ops-main;compileall 通过;pytest 结果 128 passed in 13.51s。
## 2026-07-24 — Q1 迁移必须与插件启动解耦
- 阶段:Q1 数据迁移与启动安全
- 类型:功能行为 / 数据安全
- 现象:运维版数据目录已与普通版分离,但没有迁移器时,旧记忆不会自动出现;启动时直接搬迁又可能覆盖生产数据。
- 根因:目录隔离和历史数据迁移是两个不同问题,不能用插件初始化顺手解决。
- 修复或规避:增加 `core/ops_migration.py`,只允许管理员显式执行 preview/run;SQLite 使用只读校验与 backup,成功后写迁移标记。
- 预防规则:先预览和备份,再执行迁移;目标非空、格式损坏或已有标记时必须拒绝。
- 验证证据:`tests/test_ops_migration.py` 5 项 unittest 通过,`compileall` 通过。
2026-07-24 21:34:04 +08:00
## 2026-07-24 — 运行时能力与平台能力不能混成一层
- 阶段:Q2 运行时兼容层
- 类型:API契约 / 兼容性
- 现象:已有 `platform_compat.py` 能判断 OneBot、QQ 官方等平台动作,但无法说明当前 AstrBot 是否提供对应 Hook、ProviderRequest 或消息组件。
- 根因:平台能力和宿主运行时 API 是两种不同维度;只判断平台会把版本/API 缺失误判成平台不支持。
- 修复或规避:新增 `runtime_compat.py`,启动时只做导入和对象形状探测,返回 full/degraded/unsupported;平台能力继续由 `platform_compat.py` 负责。
- 预防规则:新增 AstrBot API 调用前先进入运行时兼容层;不得用未认证管理 API 作为能力探测依据。
- 验证证据:运行时兼容单元测试 2 项通过,插件 compileall 通过。
## 2026-07-24 — 运维版模块名必须进入跨插件发现列表
- 阶段:Q2 插件联动适配
- 类型:API契约 / 集成
- 现象:Memory Archivist 只寻找普通版 MemoryCompanion 模块名,运维版插件虽然已安装,仍会被判定为记忆源不可用。
- 根因:普通版和运维版按设计使用不同插件身份,跨插件发现不能只保留旧包名。
- 修复或规避:Memory Archivist 的公开适配器加入 `astrbot_plugin_memory_companion_ops.main` 和 `data.plugins.astrbot_plugin_memory_companion_ops.main`,并读取 Bridge 的运行时能力快照。
- 预防规则:插件分支改名时必须同步检查模块发现、Bridge、页面、备份和适配器候选列表。
- 验证证据:适配器和测试 `py_compile` 通过;最小能力探测返回 archive 与 runtime 两组状态。
## 2026-07-24 — VM 生产仍是普通版,不能提前宣称运维版验收
- 阶段:Q2 VM 只读验收
- 类型:部署 / API契约 / 环境
- 现象:本地运维版已完成 Q1/Q2,但 VM 上未发现 `_ops` 插件目录,因此无法执行 `/mcomp runtime` 或验证 Archivist 的运维 Bridge 发现。
- 根因:源码完成、Forgejo 推送和生产部署是三个独立状态;不能用本地提交或普通版插件在线来代表运维版已加载。
- 修复或规避:只读确认 AstrBot `4.26.6`、systemd active、`NRestarts=0`、普通版插件和 Archivist 状态;不覆盖普通版目录,不重启生产,不绕过管理认证;记录缺口并等待单独部署验收。
- 预防规则:任何“实机验收通过”必须同时具备目标插件目录、启动导入证据、命令或 Bridge 返回结果;缺一项只能标记为“部署前置未完成”。
- 验证证据:`Q2_VM只读验收记录.md`;SSH 只读检查于 2026-07-24 21:49 CST 完成。
## 2026-07-24 — Q3 事件合同必须在启动后重新发现 Bridge
- 阶段:Q3 运维事件与数据模型、VM 部署验收
- 类型:API契约 / 部署 / 功能行为
- 现象:两个 ops 插件已成功加载,但 Memory Archivist 初始仍报告 `source=unavailable`。
- 根因:Archivist 在 `__init__` 阶段解析记忆源,早于 MemoryCompanion 完成插件实例化;`on_astrbot_loaded` 只探测旧适配器,没有重新解析。
- 修复或规避:在宿主加载完成 Hook 中重新调用 `resolve_memory_source`;同时优先复用当前进程已加载的 ops 模块,避免重复导入造成空 Bridge。
- 预防规则:跨插件发现不能只测试“模块能否 import”;必须验证插件生命周期顺序、Bridge 实例是否已初始化和实机 capability 返回。
- 验证证据:VM 日志 `source=memory_companion version=1.6.2-ops.1 available=True search=True`;AstrBot `4.26.6`、`NRestarts=0`。
## 2026-07-24 — Q4 动态时间元数据不能落库
- 阶段:Q4 时间感知改造
- 类型:编码 / 测试 / API契约 / 部署
- 现象:已有 `occurred_at`、`created_at` 等字段,但注入和 Bridge 只能给出裸时间,模型容易把历史天气、备份或服务状态误当作当前事实。
- 根因:时间跨度、跨日、事实有效期和时间来源没有统一合同;如果把“距今多久”持久化,下一次读取就会过期。
- 修复或规避:新增 `core/temporal_context.py`,在检索/注入/Bridge/Archivist 出口动态生成 `temporal`;metadata 只补来源、时区、精度和估算标记;增加 `bridge_get_reply_delay()`,群聊默认不产生私密等待情绪。
- 预防规则:不得用 `last_accessed_at` 代替事件时间;不得把 `age_seconds` 写入数据库;运维当前状态必须重新取 Controller 事实,旧记忆只作历史背景。
2026-07-24 23:12:02 +08:00
- 验证证据:时间合同测试 13 项通过;非宿主依赖的 unittest 130 项通过;`compileall` 通过;数据库无需迁移,版本升至 `1.6.2-ops.2`。VM 定向测试 `20 passed`,服务 `active` 且 `NRestarts=0`,Archivist 已发现 `1.6.2-ops.2`。