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

19 KiB

错题本

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 — 运行时能力与平台能力不能混成一层

  • 阶段: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 事实,旧记忆只作历史背景。
  • 验证证据:时间合同测试 13 项通过;非宿主依赖的 unittest 130 项通过;compileall 通过;数据库无需迁移,版本升至 1.6.2-ops.2。VM 定向测试 20 passed,完整回归在双插件 PYTHONPATH 下为 155 passed;服务 active 且 NRestarts=0,Archivist 已发现 1.6.2-ops.2。

2026-07-24 — 运维版记忆插件源码全量审计

  • 阶段:源码审计与优化规划
  • 类型:其他 / API契约 / 功能行为 / 运维
  • 现象:插件已具备重要性、检索、时间感知、权限、迁移、衰减和运维合同,但这些能力的质量与生产边界分散在多个模块,容易把“已实现”误认为“已闭环”。
  • 根因:重要性、置信度、新鲜度、提及策略和冲突版本尚未拆成统一质量合同;缓存、迁移、维护和危险面板操作也缺少统一的预演、审计和恢复模型。
  • 修复或规避:完成源码、测试、Q3/Q4 文档和提交记录的交叉审计,形成 docs/记忆插件源码审计与优化档案.md;将缓存 stale、冲突版本、导入源选择、衰减 dry-run、结构化评分解释和质量基准列为后续优先队列。
  • 预防规则:以后新增记忆能力必须同时回答“来源、时效、置信度、冲突、可解释性、可回滚性、测试证据”七项;仅有 README 或单元测试通过不能视为生产闭环。
  • 验证证据:审计覆盖 core/、page_api.py、pages/记忆面板、tests/;既有 Q4 回归记录为 VM 定向 20 passed、完整回归 155 passed, 1 warning,未对本阶段报告新增业务代码。

2026-07-24 — 只读记忆观察窗必须与写操作隔离

  • 阶段:记忆观察窗实现
  • 类型:功能行为 / API契约 / 测试
  • 现象:原有知识图谱接口可展示关系边,但如果直接把图形观察和记忆管理混在一起,容易让用户误以为可以在图上修改事实。
  • 根因:观察数据、节点详情和记忆写操作没有在产品语义上明确分层。
  • 修复或规避:新增只读 knowledge_graph_observation() 数据合同和观察窗;复用 GET /graph,返回统计、节点、关系和 readonly=true,前端只渲染 SVG、统计卡片和详情查看,不增加删除、编辑、合并或写入按钮。
  • 预防规则:所有可视化观察功能默认只读;任何修改能力必须单独设计 POST 合同、二次确认、审计和回滚,不能从观察图直接派生。
  • 验证证据:面板回归 9 项通过;Node --check、Python py_compile 通过;临时 SQLite 验证返回 2 个节点、1 条关系和 readonly=True。