astrbot_plugin_private_comp.../docs/运维陪伴错题本.md
YokiiroBW 2518f7b6bf fix: make the daily plan chain survive startup timing and same-day rewrites
Two defects that only showed up on the real machine, both of which left the
schedule frozen on a fallback plan with nothing in the logs to say so.

The plugin asked for a chat provider 0.8s before AstrBot finished loading
them, wrote a template fallback, and stamped it with today's date -- so the
next 24 hours never retried. Resolution now falls back through get_config()
(4.26.6's Context exposes nothing else) and validates the configured id with
get_provider_by_id, because a configured default is not a loaded instance.
When nothing is ready yet the round is skipped instead of downgraded, up to
DAILY_PLAN_PROVIDER_MAX_WAITS rounds.

Once the model recovered, the real plan still could not reach the archive:
the idempotency key is always daily_plan:<date> but the plan dict never
carried a version, so every rewrite re-sent v1 and the memory side rejected
it as version_conflict. The companion swallowed that -- outbox state is only
touched when enqueue accepts, and a same key/version enqueue does not. Plans
now carry a version watermark drawn from both daily_plan and its history, and
any ok=False archive response logs a warning regardless of outbox state.

Verified on the VM: provider wait counted once and no fallback written, plan
generated at v2 with 10 segments from the model, and the stored record
upserted from the 8-segment fallback to the same v2 content.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 04:16:06 +08:00

59 KiB

运维陪伴插件错题本

适用仓库:astrbot_plugin_private_companion-main 分支:ops-main 说明:这里只记录运维人格插件自身的编码、消息流、权限、日程、部署和性能问题;记忆插件问题记录在另一份错题本中。

2026-07-24 — 回复延迟不能复用当前用户时间

  • 阶段:Q4.1 陪伴消息时间感知
  • 类型:功能行为 / API契约
  • 现象:用户隔夜回复时,模型容易把昨晚的话题当成当前实时状态。
  • 根因:入站处理已经把 last_user_message_at 更新为当前消息,不能再用它计算用户等待时间;真正的锚点是上一条 Bot 消息。
  • 修复或规避:新增 temporal_context.py,优先读取平台消息时间,使用 last_companion_message_at 计算延迟,并把跨日、话题年龄和短期状态过期提示注入人格提示词。
  • 预防规则:计算回复间隔前先明确时间区间两端;不要复用本轮刚更新的时间字段代替历史锚点。
  • 验证证据:tests.test_temporal_context 5 项 unittest 通过;人格插件 compileall 通过。

2026-07-24 — 群聊不能泄露私聊等待情绪

  • 阶段:Q4.1 陪伴消息时间感知
  • 类型:安全 / 功能行为
  • 现象:如果把私聊时间上下文直接复用到群聊,可能出现“你怎么这么久才回复我”等不适合公开场景的表达。
  • 根因:现实时间信息和私聊关系情绪没有分层。
  • 修复或规避:时间上下文格式化函数增加群聊模式;群聊不输出私聊等待情绪和私密承接规则。
  • 预防规则:群聊只注入必要的公共时间背景;涉及等待、关系和私密历史的内容必须按会话类型隔离。
  • 验证证据:群聊边界测试通过,提示词不包含“昨晚”式私聊等待表达。

2026-07-24 — 运维人格不能直接拥有运维写权限

  • 阶段:运维人格融合设计
  • 类型:安全 / API契约
  • 现象:自然语言入口容易被误做成 Shell、SSH、Docker 或 NAS 的直接控制器。
  • 根因:人格连续性和执行权限被混为一层。
  • 修复或规避:人格插件只负责理解意图、表达、日程、委派和结果解释;具体操作交给受限 Controller,并保留审批和审计边界。
  • 预防规则:新增运维能力时先确认工具所有者、事实来源、审批条件和失败回滚;禁止把高权限工具直接挂给主人格。
  • 验证证据:当前运维设计文档明确人格与执行分离,未新增 Shell、SSH Key、Docker Socket 或 NAS 写能力。

2026-07-24 — VM 加载状态不能用本地提交代替

  • 阶段:VM 部署验收
  • 类型:部署 / 环境
  • 现象:本地 ops-main 编译通过,不代表 VM 已加载运维版插件。
  • 根因:源码、Forgejo、发布包和 VM 运行实例是四个独立状态。
  • 修复或规避:部署验收必须同时检查目标目录、启动日志、插件版本、Bridge 发现结果和 NRestarts。
  • 预防规则:没有实机加载证据只能标记为部署前置完成,不能宣称生产验收通过。
  • 验证证据:既有 Q2/Q3 VM 验收记录已采用该标准。

2026-07-24 — 日历重复事件不能只保存原始模板

  • 阶段:Q4.2 真实日历
  • 类型:功能行为
  • 现象:每日/工作日重复事件能被判断“存在”,但投影和附近日程仍使用第一次发生时间。
  • 根因:重复规则与当天发生实例没有分离。
  • 修复或规避:新增 event_occurrence_on_date,按目标日期生成实例,保留原始 event_id。
  • 预防规则:任何重复事件展示或计算前,先生成目标日期实例,不直接使用模板起止时间。
  • 验证证据:每日重复和工作日跳过周末测试通过。

2026-07-24 — 日历写入必须经过确认和历史快照

  • 阶段:Q4.2 真实日历
  • 类型:安全 / API契约
  • 现象:自然语言“帮我安排一下”如果直接落库,可能把猜测当成用户确认。
  • 根因:解析、冲突检测和持久化没有明确分层。
  • 修复或规避:新增 pc_manage_calendar;写操作第一次只返回预览,confirm=true 才写入,并记录 before/after 历史。
  • 预防规则:新增、修改、完成和取消都必须有明确事件 ID/时间合同、冲突检测和确认步骤。
  • 验证证据:工具入口限制主要用户私聊;外部日程写权限拒绝;核心文件编译通过。

2026-07-24 — PowerShell 写回源码必须显式指定 UTF-8

  • 阶段:Q4.2 实现与验证
  • 类型:环境 / 构建
  • 现象:使用默认 Get-Content/Set-Content 读写含中文源码后,出现大范围乱码和未闭合字符串。
  • 根因:Windows PowerShell 默认编码与仓库 UTF-8 不一致。
  • 修复或规避:从 HEAD 恢复源码,并使用 UTF-8 显式读写;新增文件也统一 UTF-8。
  • 预防规则:修改中文源码时禁止默认编码读写;写回后立即运行 py_compile 和最小测试。
  • 验证证据:核心文件恢复为可编译状态,14 项单元测试通过。

2026-07-24 — 运维陪伴插件已完成 VM 部署验收

  • 阶段:Q4.2 运维陪伴部署
  • 类型:部署 / 环境 / API契约
  • 现象:本地提交和 Forgejo 推送完成后,需要确认 VM 只替换运维陪伴插件,不影响普通陪伴插件和运维记忆数据。
  • 根因:插件代码目录、插件数据目录、普通陪伴插件目录和运行中的 AstrBot 服务是不同边界;只看本地 Git 状态不足以证明实机已生效。
  • 修复或规避:按提交 0e2848d 生成归档,核对本地/VM SHA-256;停服前备份活动插件与运维数据;仅移动替换 astrbot_plugin_private_companion_ops,保留普通插件和数据;启动后核对加载日志、关键文件、服务状态和重启次数。
  • 预防规则:运维版部署必须使用精确提交归档;先备份再替换;禁止覆盖普通陪伴插件或直接读取/改写记忆数据库;必须保留可回滚目录。
  • 验证证据:VM 备份 /var/lib/astrbot/ops-replace-backups/private-companion-ops-20260725-014151;日志确认 5.10.4-ops.1 加载、主动消息循环启动、WAL 优化应用;astrbot.service=active、NRestarts=0;VM AstrBot Python 编译检查通过。

2026-07-24 — VM 没有系统级 python 命令

  • 阶段:Q4.2 运维陪伴部署
  • 类型:环境
  • 现象:直接执行 python -m py_compile 返回 python: command not found。
  • 根因:VM 只通过 AstrBot 的 uv 工具环境提供运行时,不保证系统 PATH 暴露 python。
  • 修复或规避:使用 /var/lib/astrbot/.local/share/uv/tools/astrbot/bin/python 完成同一检查。
  • 预防规则:VM Python 验证优先读取 systemd 实际启动命令,使用 AstrBot 运行时,不假设系统 PATH。
  • 验证证据:关键文件 VM 编译检查输出 VM_PYCOMPILE=passed。

2026-07-24 — 日记主动任务依赖默认模型 Provider

  • 阶段:Q4.2 运维陪伴部署
  • 类型:环境 / 功能行为
  • 现象:旧进程日志出现 task=diary provider=default 未找到可用默认模型 Provider 的警告。
  • 根因:VM 的 AstrBot Provider 配置未提供名为 default 的可用模型;不是本次代码归档或目录替换造成的异常。
  • 修复或规避:本次不修改 VM Provider 配置;记录为独立部署后配置项,避免把环境问题混入插件替换。
  • 预防规则:验收主动日记、主动消息等 LLM 任务时,同时检查 Provider 可用性;区分旧日志、当前进程日志和代码回归。
  • 验证证据:部署后新进程加载日志无该错误;服务保持 active 且 NRestarts=0。

2026-07-25 — 旧 daily_plan 不能直接交给统一对账器

  • 阶段:Q5.0–Q5.3 本地统一真实日程
  • 类型:API契约 / 功能行为
  • 现象:旧计划项使用 time/end/activity,统一对账器需要 start_at/end_at/title;直接读取会导致计划无法和实际活动匹配。
  • 根因:Q4 日历已能把计划投影为 calendar_events,但新统一视图初始仍读取原始 daily_plan.items。
  • 修复或规避:统一视图优先读取 calendar_events 中的计划投影;没有投影时再通过 plan_item_to_event 转换旧计划。
  • 预防规则:任何新日程模块不得直接假设旧 daily_plan 已经是完整事件合同;入口必须经过规范化层。
  • 验证证据:tests.test_agenda_system 的 legacy daily plan 转换测试通过。

2026-07-25 — World 接入阶段必须默认离线

  • 阶段:Q5.7 World 离线接口预留
  • 类型:安全 / API契约 / 环境
  • 现象:World Server 尚未实现时,如果陪伴插件直接请求外部服务,会把本地日程稳定性绑定到未完成的跨 Bot 服务。
  • 根因:World 文档是未来合同,不是当前运行时能力;生产接入还需要授权、撤销、过期和双端幂等验证。
  • 修复或规避:新增 WorldGatewayContract 和 NullWorldGateway,默认不联网;只允许读取带 fresh_until 的缓存,外部失败静默降级。
  • 预防规则:本地统一日程稳定运行和观察期结束前,不启用 World 生产投影;共同活动必须等待双端确认。
  • 验证证据:tests.test_agenda_system 的离线网关和过期缓存测试通过;world_gateway.py 编译通过。

2026-07-25 — Bot 自有记忆不能继续走外部记忆桥

  • 阶段:C6.0–C6.5 Bot 自有存储与用户记忆边界
  • 类型:安全 / API契约 / 功能行为
  • 现象:Bot 日程、窗口快照、主动行为、创作和梦境原先可以通过 record_schedule_fragment、record_calendar_event 或其他 Bridge 写入记忆插件,容易和用户记忆混合。
  • 根因:陪伴插件的 Bot 自我连续性和记忆插件的用户事实没有硬隔离,调用方只依赖方法名和降级路径判断归属。
  • 修复或规避:新增 bot_self_store.py 和 bot_self_store 命名空间;Bot 自有记录使用本地幂等存储;主 MemoryCompanion 与旧 RememberYou 适配器停止写入 Bot 日程和自我记录;用户图片摘要和用户习惯仍保留用户记忆入口。
  • 预防规则:任何跨插件写入前必须确认主体是用户;没有明确用户证据的共同活动不得进入用户记忆;禁止用 record_schedule_fragment 作为 Bot 数据降级通道。
  • 验证证据:tests.test_bot_self_store、全量 unittest discover -s tests 共 29 项通过;核心 Python 编译通过;git diff --check 通过。

2026-07-25 — 混合活动必须显式拆出用户侧

  • 阶段:C6.2 共同对话拆分
  • 类型:功能行为 / API契约
  • 现象:一条“Bot 与用户共同完成某事”的活动,不能直接整段当作用户记忆。
  • 根因:参与者列表只能说明谁在场,不能证明用户具体做了什么。
  • 修复或规避:新增 split_shared_activity() 和 ActivityCapture.split_for_storage();只有输入明确提供 user_side 时才允许生成用户侧记录,Bot 侧统一进入本地 Bot 存储。
  • 预防规则:参与者不等于用户事实;必须保留来源引用、证据等级和拆分结果。
  • 验证证据:共享活动缺少 user_side 时 eligible=false;显式用户侧测试通过。

2026-07-25 — VM 旧 pycache 权限导致编译检查误报

  • 阶段:Q7.5 VM 部署验收
  • 类型:环境 / 部署
  • 现象:在 VM 插件目录直接执行 python3 -m compileall -q . 时,大量文件报告无法写入既有 __pycache__;服务本身仍能正常启动。
  • 根因:插件目录中的旧 __pycache__ 由不同权限主体创建,当前验收用户没有写权限;编译命令默认尝试回写原目录。
  • 修复或规避:使用 PYTHONPYCACHEPREFIX=/tmp/private-companion-q7-pycache python3 -m compileall -q . 将字节码写入临时目录,不修改活动插件目录。
  • 预防规则:VM 部署后的编译检查必须使用临时字节码目录,不能把活动插件目录的旧缓存权限当成源码编译失败。
  • 验证证据:Q7.5 VM 验收中临时字节码目录编译通过;astrbot.service=active、NRestarts=0。 docs\运维陪伴错题本.md

2026-07-25 — OPS 功能删减必须按依赖链处理

  • 阶段:OPS 全功能盘点与娱乐模块删减评估
  • 类型:功能行为 / API 契约 / 其他
  • 现象:单看配置开关容易把 QQ 空间、新闻、图片、主动消息和群聊逻辑误认为可以独立删除,实际它们还连接了页面、Provider、后台任务、命令、缓存和主动候选。
  • 根因:陪伴插件采用多个 Mixin 组合,外部娱乐能力与主动系统、图片系统和页面 API 存在交叉依赖。
  • 修复或规避:先形成“保留、建议删除、可选删除”清单,删除前按源码、配置、命令、页面、任务、缓存和迁移数据逐项清理;本轮只写评估,不直接删除。
  • 预防规则:任何 OPS 功能删减都必须先关闭观察,再做依赖扫描和 VM 回滚方案,不能只删除一个 enable_* 配置项。
  • 验证证据:已盘点 main.py Mixin 组合、_conf_schema.json 开关、command_handlers.py、page_api.py、页面目录和当前 Q6/Q7 边界文档;评估落盘于 docs/OPS陪伴插件全功能盘点与删减评估.md。

2026-07-25 — 源码批量编辑时的中文编码陷阱

  • 阶段:功能删减
  • 类型:编码 / 环境
  • 现象:Windows PowerShell 默认读取源码后再写回,中文源码被按系统编码误读,造成大范围乱码和语法错误。
  • 根因:未显式使用无 BOM UTF-8 读写。
  • 修复或规避:回滚受影响文件;后续统一使用 Python Path.read_text/write_text(encoding="utf-8") 或 .NET UTF-8 无 BOM。
  • 预防规则:涉及中文源码的批量替换必须先做编码探测,并在写回后立即运行 py_compile。
  • 验证证据:python -m py_compile main.py page_api.py llm_tool_actions.py 和 python -m compileall -q . 均通过。

2026-07-25 — 独立娱乐模块删除后的兼容边界

  • 阶段:功能删减
  • 类型:功能行为 / API契约
  • 现象:QQ 空间和新闻实现被多个主类、页面、命令和配置入口引用,直接删文件会导致插件启动或页面注册失败。
  • 根因:功能实现、配置 schema、页面路由和主动调度没有统一边界。
  • 修复或规避:先移除 Mixin/导入/路由,再删除独立文件;保留旧数据命名空间但不再执行外部调用;主动动作开关强制关闭。
  • 预防规则:删除插件能力必须同时检查导入、Mixin、路由、schema、命令、后台任务和页面脚本。
  • 验证证据:独立模块文件已删除;已删除模块导入和 qzone 页面脚本残留扫描无结果;源码编译通过。

2026-07-25 — VM 发布归档继承了不可读目录权限

  • 阶段:部署
  • 类型:部署 / 权限
  • 现象:插件归档部署后,AstrBot 日志提示运维陪伴插件没有可加载的 main.py。
  • 根因:归档保留了本地插件根目录的 0700 权限,运行服务的 astrbot 用户无法读取插件目录。
  • 修复或规避:部署后统一将插件目录设为 0755、文件设为 0644,并保持 root:root 所有权。
  • 预防规则:发布归档不能只检查文件存在,必须检查运行用户对根目录、main.py 和配置文件的读取权限。
  • 验证证据:AstrBot 重启后加载 astrbot_plugin_private_companion_ops (5.10.4-ops.1);服务 active,NRestarts=0。

2026-07-25 — 回滚副本不能放入插件扫描目录

  • 阶段:部署
  • 类型:部署 / AstrBot 插件发现
  • 现象:AstrBot 将 astrbot_plugin_private_companion_ops.previous-* 当作插件加载,产生 ModuleNotFoundError。
  • 根因:回滚副本被放在活动插件目录的同级扫描范围内,且目录名不是合法的 Python 模块名。
  • 修复或规避:删除本次误生成的同级副本;正式备份放在 /var/backups/astrbot-plugin-private-companion/。
  • 预防规则:任何备份、临时解压目录都必须放在 AstrBot 插件扫描根目录之外。
  • 验证证据:清理后重启日志只保留正式运维陪伴插件加载记录,没有新的 previous-* 导入错误。

2026-07-25 — 前端只读契约必须与后端返回结构对齐

  • 阶段:Q8 前端改造
  • 类型:API契约 / 编码
  • 现象:前端首次接入日程对账接口时,不能假设接口同时返回摘要字段;详情接口主要返回计划、实际和历史列表。
  • 根因:Q7 将摘要和详情拆成不同职责,前端把两者误当成同一 payload。
  • 修复或规避:前端对状态数量、实际数量和对账数量增加列表回退计算,并对每个只读接口单独降级。
  • 预防规则:接入页面前先读取后端构造函数和真实字段,摘要缺失时必须有可解释的派生值或明确的“暂无”。
  • 验证证据:Q8 页面接入 build_agenda_detail 后通过 node --check 和 git diff --check。

2026-07-25 — PowerShell 换行标记不能做全局替换

  • 阶段:Q8 前端改造
  • 类型:环境 / 编码
  • 现象:使用 PowerShell 文本替换插入事件处理时,模板字符串中的反引号加 n 被误当作换行标记,造成 JavaScript 语法损坏。
  • 根因:脚本编辑器和目标 JavaScript 都使用反引号,批量替换没有隔离作用域。
  • 修复或规避:回退未提交前端文件,改用 Node 直接读取、按真实换行处理并立即运行 node --check。
  • 预防规则:复杂 JavaScript 模板注入不要使用 PowerShell 全局替换;优先使用 Node/补丁工具,并在每次写入后做语法检查。
  • 验证证据:恢复后的 app.js 语法检查通过,Q8 补丁已重新写入。

2026-07-25 — Q8 前端归档部署与 VM 时钟差异

  • 阶段:Q8 VM 部署
  • 类型:部署 / 环境
  • 现象:部署验收日志使用 VM 时间 2026-07-26 02:59,而工作站当前日期为 2026-07-25。
  • 根因:VM 与工作站系统时钟或时区存在差异。
  • 修复或规避:验收记录同时保留本地日期和 VM 日志时间,不用相对日期描述部署结果。
  • 预防规则:VM 部署记录必须写入绝对日期、服务状态、提交号和备份路径。
  • 验证证据:Q8 VM 部署验收记录;服务 active、NRestarts=0,插件和前端资源检查通过。

2026-07-25 — M6.1 陪伴侧 Bot 个人记忆联动降级

  • 阶段:M6.1.3-M6.1.7 四段式写入、Bot 专用检索、Bridge 缺失与异常降级测试
  • 类型:API契约 / 功能行为 / 测试
  • 现象:陪伴插件原先只写本地 bot_self_store,若直接改成记忆插件远端写入,会在插件缺失或初始化失败时阻断日程运行。
  • 根因:Bot 自有记录入口没有把本地事实存储与跨插件长期归档拆成两个可选步骤。
  • 修复或规避:保留本地写入作为主路径;通过 record_bot_personal_memory 按 kind 映射到 Bot 专用 memory_type;检索优先调用 search_bot_personal_memory,无结果或 Bridge 不可用时回退旧上下文;远端异常只记录日志。
  • 预防规则:跨插件联动必须是可选增强,陪伴主流程不能依赖记忆插件;日计划、窗口快照、创作、相册和日记必须使用稳定幂等键。
  • 验证证据:tests.test_m6_bot_personal_bridge 4 项通过;陪伴插件全仓 compileall -q . 通过;git diff --check 通过。

2026-07-25 — M6 日程拆分不能删除运行态

  • 阶段:M6 日程拆分与 Bot 个人记忆联动评估
  • 类型:功能行为 / API契约 / 性能
  • 现象:如果把 Bot 日程全部搬到记忆插件,当前活动、下一项日程、休息闸门和主动消息都会依赖长期记忆查询。
  • 根因:日程运行态和长期归档是两种不同职责;记忆插件适合历史检索,不适合替代陪伴插件的实时状态机。
  • 修复或规避:确定陪伴插件继续维护当前运行态和本地 bot_self_store,记忆插件只接收 Bot 专属长期归档并提供只读 Profile。
  • 预防规则:M6 先做双写、字段统一和失败补偿;观察期结束前不删除 daily_plan、calendar_events、observed_activities、window_snapshots 等旧运行字段。
  • 验证证据:已核对 agenda_runtime.py、busy_reply_gate.py、state_views.py、planning.py 和 memory_companion_adapter.py;评估文档已写入 docs/M6日程拆分与陪伴插件调整评估.md。

2026-07-25 — M6 远端归档字段不能依赖通用清洗猜测

  • 阶段:M6 日程拆分与 Bridge 字段复盘
  • 类型:API契约 / 功能行为
  • 现象:陪伴侧多个 Bot 事件通过同一个通用清洗函数写入记忆插件,嵌套计划、创作和对账内容可能被压扁或丢失,导致长期归档结构不稳定。
  • 根因:业务事件没有统一的 M6 payload 合同;通用清洗只能保证安全,不能保证事件语义完整。
  • 修复或规避:本轮不直接改代码;将统一归档适配器、source_refs、occurred_at、certainty、evidence_level、version 和幂等键列为 M6.1.3 首要改造项。
  • 预防规则:业务代码优先调用类型化 Bot Bridge;底层通用入口只做兼容,不让记忆插件反推调用方语义。
  • 验证证据:已核对 memory_companion_adapter.py 的 _memory_companion_record_bot_self_local() 及记忆侧 record_bot_personal_memory() 实现;差距已记录在 M6 评估文档。

2026-07-26 — 四段式快照与远端归档存在“看似接通、实际不闭环”

  • 阶段:M6.1.3 前置源码复盘
  • 类型:编码 / API契约 / 功能行为
  • 现象:窗口快照未按时间窗口过滤,深夜跨午夜语义不完整;活动、对账和完整日记没有正式写入对应 Bot Personal 类型,Bridge 失败也没有补偿队列。
  • 根因:日程运行、窗口结算、本地 Bot 存储和远端归档分别演进,缺少统一窗口合同、正式 reconciliation 和可靠 outbox;通用 payload 清洗还会把列表中的结构化对象转成字符串。
  • 修复或规避:先修窗口过滤和跨午夜,再建立类型化归档 schema、专用 Bridge 调用和 outbox;本地运行态字段继续保留,禁止直接迁走日程引擎。
  • 预防规则:窗口功能必须覆盖完整 24 小时、重启补算和逐窗口数据隔离;远端写入必须验证结构、幂等、失败状态和恢复补写。
  • 验证证据:agenda_runtime.py:142、agenda_runtime.py:168、memory_companion_adapter.py:722、docs/OPS双插件完整复盘与功能调整总方案.md。

2026-07-26 — M6.1.3-B 深夜窗口必须使用窗口日期

  • 阶段:M6.1.3-B 四段窗口、跨午夜和重启补算
  • 类型:功能行为 / API契约
  • 现象:如果只用当前自然日和分钟判断“深夜”,00:00~06:00 会被错误归到当天深夜,导致上一晚 22:00~06:00 的快照、对账和日记边界错位。
  • 根因:深夜是跨午夜窗口,窗口名称和窗口所属日期不是同一个概念。
  • 修复或规避:新增 window_for_datetime() 和 window_bounds();00:00~06:00 映射到前一日的“深夜”,保存 window_date/start_at/end_at/timezone。
  • 预防规则:所有窗口结算、过滤和幂等键必须使用 window_date + window,不能只使用当前 date()。
  • 验证证据:tests.test_m6_local_loop.M6LocalLoopTests.test_deep_night_uses_start_date_across_midnight 和跨午夜快照测试通过。

2026-07-26 — M6.1.3-C Bridge 失败不能只写日志

  • 阶段:M6.1.3-C 本地 outbox 和可靠联动准备
  • 类型:API契约 / 功能行为 / 部署
  • 现象:远端记忆 Bridge 超时或插件未加载时,如果只记录日志,短暂故障会造成长期 Bot 归档永久缺口。
  • 根因:本地日程成功与远端归档成功没有独立状态,缺少重试和重启恢复记录。
  • 修复或规避:新增 bot_personal_outbox,记录精简 envelope、幂等键、版本、尝试次数、下次重试和错误码;Bridge 使用短超时,维护 tick 负责补投,消息主链不等待远端成功。
  • 预防规则:跨插件写入必须先本地落盘,再异步发送;pending/retry/dead_letter 需要可观察,不能把 Bridge 返回值当成本地日程成功条件。
  • 验证证据:tests.test_m6_local_loop 的 outbox 去重/重试恢复测试通过;共享合同仍为 DRAFT,未锁定版本冲突逻辑。

2026-07-26 — M6.1.3-B 活动聚合必须稳定 ID 加来源去重

  • 阶段:M6.1.3-B 活动捕获聚合
  • 类型:功能行为 / 性能
  • 现象:连续消息的起始时间会变化,若把起始时间直接放入活动 ID,同一协作过程会被拆成多条活动;重复 Hook 还可能重复计数。
  • 根因:活动 ID 没有固定时间桶,写入层也没有检查 source_ref。
  • 修复或规避:活动 ID 使用会话、主题和时间桶;本地写入前按 source_ref 去重,并合并来源引用和活动起止时间。
  • 预防规则:活动聚合要先定义会话/时间桶/主题边界,再用来源引用做幂等保护。
  • 验证证据:活动聚合和重复 Hook 测试通过;普通问候仍不会生成活动。

2026-07-26 — FROZEN 合同的能力检测与 DRAFT 兼容层发送

重写说明(M6.1.3-R2 补):本条原文因 PowerShell 默认编码读写,被替换成 334 个 U+FFFD, 已确认不可逆——文件本身是合法 UTF-8,GBK 解不回,且 0e0db82 提交版里还没有这一条, Git 也取不回。以下按残存的 ASCII 片段(阶段/类型行、record_bot_personal_memory、 certainty、ok、payload schema、五个测试模块名与「31 项」)结合共享合同上下文重建, 语义忠实,但不是逐字原文。

  • 阶段:M6.1.3-C FROZEN Bridge 对接
  • 类型:API契约 / 功能行为 / 测试
  • 现象:共享合同已经冻结,但陪伴侧仍只调用通用 record_bot_personal_memory,中文枚举值和字符串形式的 certainty 直接发送;记忆侧返回的结构化失败也会被当成写入成功。
  • 根因:任务执行记录与后来冻结的合同状态没有同步——DTO、五类专用方法、outbox 本地错误态三者各自演进,谁也没有回头以合同为准对齐一次。
  • 修复或规避:五类专用方法优先,通用方法只作兼容降级;枚举统一映射到合同的英文值;certainty 数值化;补齐时间字段与 payload_schema_version;幂等键改为稳定值,不随内容变化。
  • 预防规则:每次开发都要以共享合同和真实 Bridge 源码为准,不能照抄旧任务单;结构化返回必须解析 ok,不能只判断有没有抛异常;版本冲突类错误不得无限重试。
  • 验证证据:tests.test_m6_bot_personal_bridge、tests.test_m6_local_loop、tests.test_q7_backend_contracts、tests.test_agenda_system、tests.test_bot_self_store 共 31 项通过;目标模块 py_compile 通过。

2026-07-26 — R1 联合审查阻断项必须覆盖真实生产路径

  • 阶段:M6.1.3-R1 联合审查阻断修复
  • 类型:功能行为 / API契约 / 性能 / 测试
  • 现象:M6.1.3-B/C 的定向测试通过,但实际活动归档没有生产调用;维护任务被主动消息总开关提前短路;outbox 仍会覆盖版本、丢弃未完成任务或在 Bridge 缺失时立即热重试。
  • 根因:本地运行态、异步归档、主动生成和 outbox 版本生命周期没有在真实调用点闭环;测试只覆盖了假 Bridge 的单次写入。
  • 修复或规避:活动落地后异步归档最终对象;核心日程维护独立于主动生成;outbox 按类型和幂等键版本化 upsert;容量只清理 sent;方法缺失产生带退避 retry;严格五类与非五类旧兼容路径分流。
  • 预防规则:联合审查必须从生产调用点反查,而不是只看定义和单元测试;每个跨插件事件同时验证新增、合并、升级、断桥、恢复和满容量行为。
  • 验证证据:41 项定向测试通过;覆盖真实活动归档调用、max_daily_messages=0 核心维护、501 条 pending、隐私拒绝、专用/通用 body 一致、稳定幂等键和 Bridge 缺失退避。

2026-07-26 — 旧 kind DTO 缺 date 会在真实链路被静默拒绝

  • 阶段:M6.1.3-R1 联合复验
  • 类型:API契约 / 功能行为 / 测试
  • 现象:R1 十项必修全部通过联合复验;但 creative_progress、dream_fragment、proactive_message、qzone_publish、calendar_event 五个旧 kind 的远端归档在真实双插件链路上全部返回 invalid_date,且只有 debug 日志;daily_outfit、detail_enhancement 因 payload 自带 date 正常。
  • 根因:build_bot_personal_dto 的 date 只取 payload.date/window_date,不从 occurred_at 派生;旧 wrapper payload 天然无 date;本侧测试从未断言旧 kind 的 envelope 能过记忆侧 FROZEN 校验。
  • 修复或规避:M6.1.3-R2 本侧主修——date 缺失时从 occurred_at(本地时区)派生;calendar_event 的 occurred_at 改用 start_at;未知 kind 不再默认 bot_observed_activity;capture_hard_fact 的 L4 修为 L3。
  • 预防规则:每个 kind 的 DTO 输出必须有“date 非空 + 四窗口 + 带时区”的形状回归;远端拒绝不能只落 debug 日志,至少要能在 outbox/告警里观察到(严格五类已做到,旧 kind 兼容层同样要可观察)。
  • 验证证据:docs/M6.1.3双插件真实联合验收报告-R1复验.md P1-R2-1;联合 E2E 探针 5 kind dto_date=''→invalid_date。

2026-07-26 — 列表状态 helper 不能返回过滤后的新列表

  • 阶段:源码审计整改 Batch 1(B1)
  • 类型:编码 / 功能行为
  • 现象:_atrelay_send_log() / _atrelay_receipt_tasks() 只在「确实剪掉了过期项」时才把新列表写回 self.data;稳态(没有过期项)下返回的是脱离持久化的副本,调用方 append 全部丢失。结果是 10 分钟去重拦截失效(同一条转述可反复发送),私聊回执任务永远查不到、对方回复不会回传。
  • 根因:过滤写成 kept = [...] + 条件赋值 + return kept,把「读取」和「重建」混在一个函数里,返回对象的身份不稳定。
  • 修复或规避:改成 log[:] = kept; return log(原地更新),与同文件 _recent_atrelay_contexts 已有写法对齐,保证返回对象恒等于持久化对象。
  • 预防规则:任何返回 self.data 内列表/字典的 helper,必须保证返回的就是持久化对象本身;剪枝一律用切片赋值 obj[:] = kept,禁止条件性重新绑定。定向测试要断言 helper() is self.data[key]。
  • 验证证据:tests.test_audit_batch1.B1AtrelayListHelperTests 3 项通过(写入落库、过期仍原地剪枝、回执任务可见)。

2026-07-26 — 衰减为 0 时不能推进时间戳

  • 阶段:源码审计整改 Batch 1(B2)
  • 类型:功能行为
  • 现象:_decay_izard_emotion_dimensions / _decay_plutchik_emotions 在 steps==0(间隔 < 150s,recovery=24/h)时不做衰减,却无条件把 updated_ts 推到 now。提示词构建每轮会多次调用这两个函数,于是已流逝时间被反复丢弃,Izard 四维 / Plutchik 八维在高频对话里永远卡在峰值。
  • 根因:把「本次没有衰减」当成了「已经结算到 now」;时间戳语义应该是「这组数值准确到哪个时刻」。
  • 修复或规避:steps/decay <= 0 且 last_ts > 0 时保留旧 updated_ts;last_ts 为 0(首次初始化)仍写 now,避免衰减被永久冻结。
  • 预防规则:任何按「累计时间 → 离散步数」推进的状态机,只有真正推进了步数才可以推进时间锚点;不足一步必须保留旧锚点让时间可累计。回归用例要覆盖「高频轮询 N 次后仍能在阈值处触发一次衰减」。
  • 遗留待确认:_update_izard_emotion_dimensions:455 / _update_plutchik_emotions:566 在情绪事件分支未命中时仍无条件写 updated_ts = now,因此消息主链上的衰减仍会被重置。审计报告把 B2 的影响写成「活跃对话中情绪永不衰减」,仅改两个 decay 函数不足以完全消除该现象——是否让「没有命中任何情绪事件分支」也保留旧时间戳属于产品行为变更,待确认后再改。
  • 验证证据:tests.test_audit_batch1.B2EmotionDecayTimestampTests 5 项通过(含 145s 内高频轮询后仍在 150s 触发衰减)。

2026-07-26 — 别名子串匹配必须按长度降序

  • 阶段:源码审计整改 Batch 1(B6)
  • 类型:功能行为 / API契约
  • 现象:_normalize_platform_kind 精确键未命中后按 dict 插入顺序做子串匹配,泛化别名 "qq" 排在 "qq_official" 之前,qq_official_webhook 被判成 onebot,官方机器人平台拿到 poke/撤回/合并转发/QQ空间能力位,官方边界提示也不再注入,LLM 会承诺并调用平台不支持的动作。
  • 根因:别名表既有泛化前缀又有精确键,却用「插入顺序 + 子串包含」做匹配。
  • 修复或规避:新增模块级 _PLATFORM_KIND_ALIAS_MATCH_ORDER,按 token 长度降序预排序后再做子串匹配(精确键命中路径不变)。
  • 预防规则:任何「子串/前缀别名表」都必须显式定义匹配优先级(最长匹配优先),不能依赖 dict 顺序;新增泛化别名时必须补一条「更长的精确别名仍能命中」的用例。
  • 验证证据:tests.test_audit_batch1.B6PlatformAliasTests 3 项通过(qq_official_webhook/QQOfficial-Adapter/qqbot_webhook → qq_official;qq/onebot/aiocqhttp/napcat_v2 → onebot)。

2026-07-26 — 会向外发消息的 LLM 工具必须先鉴权

  • 阶段:源码审计整改 Batch 1(A1)
  • 类型:安全 / API契约
  • 现象:pc_relay_message / pc_send_to_group / pc_send_to_private_user / pc_schedule_group_relay 只校验 enable_atrelay_tools 开关、群号格式、内容边界、去重和敏感确认,不校验调用者身份,也不校验目标群。群内任何不可信消息都能经提示注入让 Bot 以自己的身份向任意群/私聊发任意内容。同文件 _memo_tool_authorization / _relation_lookup_authorized 都做了 owner 校验,此处属遗漏。
  • 根因:把「工具总开关」当成了权限模型;工具面写在人格提示词里,默认调用者可信。
  • 修复或规避:新增 _atrelay_tool_authorization()(owner 校验,_permission_identity_id + _is_private_companion_owner_user_id)与 _atrelay_target_group_allowed()(黑名单硬拒 → 群白名单/已观察群/当前群放行 → 都没有时放行并告警)。四个入口全部前置校验;统一入口 pc_relay_message 也要拦,否则非主人调用会先跑一次改写 LLM 才在底层被拒。
  • 预防规则:与源码实际用法对齐——转述被明确设计为群聊里也能用(群转私/群转群),所以不能照搬 _memo_tool_authorization 的「必须私聊」条件,只校验发起人身份。任何能产生对外副作用(发消息、发布、写外部系统)的 LLM 工具,新增时必须同时定义:谁能调用、目标范围、失败文案、以及一条「越权被拒」测试。
  • 验证证据:tests.test_audit_batch1.A1RelayAuthorizationTests 9 项通过(非 owner 四入口全拒;owner 越白名单/黑名单群被拒;owner 白名单群通过白名单闸门)。

2026-07-26 — 越权限制要加在不可信入口,不能加在共享底层

  • 阶段:源码审计整改 Batch 1(A2)
  • 类型:安全 / 功能行为
  • 现象:pc_generate_photo 的 reference_image_path 由模型自由填写,经 _photo_reference_copy_local_file 复制宿主机任意 .png/.jpg/.jpeg/.webp 并上传外部生图 API(任意图片外泄),经 _photo_reference_source_to_stable_path 下载任意 http(s) URL(SSRF 内网探测)。
  • 根因:模型可控来源与管理员配置来源共用同一套底层 helper,底层没有信任级别概念。
  • 修复或规避:给 _photo_reference_copy_local_file / _photo_reference_source_to_stable_path 增加 trusted 关键字;只有 LLM 入口传 trusted=False——本地路径必须 is_relative_to(data_dir),远程地址必须通过 _url_host_is_public()(新增于 helpers.py,拒绝 private/loopback/link-local/reserved/multicast/unspecified 及 IPv4-mapped)。_persist_private_remote_image_source 增加 public_hosts_only,并用 _PublicOnlyRedirectHandler 对每一跳重定向重新校验,避免公网 URL 302 到内网。解析失败时必须清掉原始字符串并直接返回 invalid_reference,否则原始路径会继续传给下游生图后端被 os.path.exists 直接读取。
  • 预防规则:方案里写「在底层 helper 上加 data_dir 限制」时先回读调用方——该 helper 同时服务管理员配置的 photo_persona_reference_image_path(面板文案明确支持任意本地路径/URL),无条件收紧会造成功能回归。信任级别要显式传递,不可信入口负责收敛;拒绝路径必须同时切断「原始值继续下传」这条旁路。
  • 验证证据:tests.test_audit_batch1.A2PhotoReferenceGuardTests 8 项通过(越权路径被拒且无复制、管理员路径仍可用、内网/环回/link-local/非 http URL 全判非公网、LLM 工具返回 invalid_reference 且从未调用生图)。

2026-07-26 — 负缓存要用哨兵,默认值不能用魔数

  • 阶段:源码审计整改 Batch 1(L1/PF7、L2)
  • 类型:性能 / API契约
  • 现象:_memory_companion_bridge() 用 if self._bridge_cache is not None 判断缓存是否有效,未装记忆插件时 bridge 恒为 None,30s 负缓存形同虚设,每条消息的提示词构建都要 list(sys.modules.values()) 全表遍历;_memory_companion_compose_feature_context 用 if top_k == 5 / if max_chars == 900 判断「调用方是否显式传参」,显式传这两个值的调用方会被配置静默覆盖。
  • 根因:用业务值兼任「未设置」语义。
  • 修复或规避:新增模块级 _BRIDGE_UNPROBED = object() 哨兵区分「未探测」与「探测过且为 None」;top_k/max_chars 默认值改 None 哨兵。改签名的同时按行为等价原则清理调用点:原本靠魔数回落到配置的 top_k=5 / max_chars=900 一律删掉(改由 None 走配置),非魔数的显式值(760/850/800/1000/950/700/4/6)原样保留。
  • 预防规则:缓存「查不到」和默认参数「未指定」必须用哨兵对象或 None,禁止复用合法业务值;把魔数默认改成哨兵时,必须同步审查全部调用点——只改签名不改调用点会把原本跟随配置的调用方硬编码住。
  • 验证证据:tests.test_audit_batch1.L1BridgeNegativeCacheTests 3 项 + L2ExplicitArgumentTests 3 项通过;memory_companion_adapter.py 属归档链路,已复跑 docs/验收工件/M6.1.3-R1/joint_e2e.py,结果与 R1 基线一致(85 项 81 通过,4 项失败仍为 M6.1.3-R2 的非五类 invalid_date)。

2026-07-26 — 错题本自身存在一段不可恢复的乱码

  • 阶段:源码审计整改 Batch 1(记录)
  • 类型:编码 / 其他
  • 现象:本文件「2026-07-26 FROZEN 合同」那一条(原第 308–316 行)整段是 U+FFFD 替换字符,用 GBK/UTF-8 任何方式都解不回原文。
  • 根因:早期窗口用 PowerShell 默认编码读写中文源码/文档造成,与本文件既有的两条「PowerShell 编码」错题同源;替换字符是有损转换,原文已不在文件里。
  • 修复或规避:Batch 1 只登记未处理;M6.1.3-R2(C6)确认 Git 也救不回——该条是在 0e0db82 之后新增的,提交版里根本没有它——遂按残存 ASCII 片段加合同上下文重写,并在条目开头标注「非逐字原文」。
  • 预防规则:文档同样适用「中文文件必须显式 UTF-8 读写」;发现替换字符要立刻从版本历史恢复,不要在上面继续追加内容,否则损坏范围会随提交固化。重写不可恢复的记录时必须显式标注重建来源,不能让后人把重建文本当原始证据。
  • 验证证据:python 逐行检查确认全部为合法 UTF-8 但含 334 个 U+FFFD、gbk 解码失败;git show 0e0db82:docs/运维陪伴错题本.md 无该条目;R2 重写后全文件 U+FFFD 计数为 0。

2026-07-26 — 未知 kind 的兜底默认值就是误标真实性的入口

  • 阶段:M6.1.3-R2 非五类兼容修复
  • 类型:API契约 / 功能行为 / 隐私
  • 现象:修 date 派生时顺手体检了归档链路,发现两处兜底把「不知道是什么」写成了「观察到的真事」:_memory_companion_archive_type() 对未登记 kind 返回 bot_observed_activity,还会被 _memory_companion_is_strict_archive_type() 判成严格类型进 outbox 和专用 Bridge 方法;build_bot_personal_dto() 只给严格五类做了 source_kind 归一,其余七类落到 source_kind or "observed",于是创作、梦境、日历这些记录在陪伴本地 bot_self_records 里全被标成 observed。
  • 根因:两处兜底都选了一个「看起来最常见」的业务值当默认,而不是「未知」。记忆库那侧因为 BOT_PERSONAL_TYPE_CONTRACTS 强制覆盖 source_kind 才没被污染,所以联合 E2E 的 mislabeled=0 一直是绿的——真实性错标只发生在本地存储,恰好在断言盲区里。
  • 修复或规避:未登记 kind 返回空串并直接跳过归档 + 一条 warning,宁可不写也不误标;DTO 新增 TYPE_CONTRACTS 表覆盖全部 12 个合同类型,与记忆侧 BOT_PERSONAL_TYPE_CONTRACTS 一一对齐,最终兜底从 observed 改为 unspecified。
  • 预防规则:枚举兜底不许挑一个合法业务值,要么显式「未知」,要么拒绝处理;跨插件双方对同一字段各有一张映射表时,必须写一条断言把两张表钉在一起,否则接收方的强制覆盖会长期掩盖发送方的错标。
  • 验证证据:tests/test_m6_r2_legacy_compat.py::R2LegacyKindCompatTests::test_legacy_kinds_are_never_mislabelled_observed 是发现该问题的用例;R2RegisteredKindShapeTests 三项覆盖未知 kind 跳过 + 12 kind 映射;陪伴 115 项、联合 E2E 90 项全通过。

2026-07-26 — 主动消息带图时整条记录会被自己的隐私校验丢掉

  • 阶段:M6.1.3-R2 非五类兼容修复(C7,R1 任务单未覆盖)
  • 类型:隐私 / 功能行为 / 测试
  • 现象:_memory_companion_record_proactive_message() 把 image_path 原样塞进 payload。生产里这是本机绝对路径,bot_personal_dto._looks_sensitive_value() 判 absolute_path 抛 PrivacyRejected,调用点只记一行 warning 就 return——带图的主动消息整条不落库,本地和远端都没有。即使 R2 修好了 date,这条路径依然是断的。
  • 根因:wrapper 写的时候只想着「把上下文都带上」,没有对照合同的「媒体只存标识,不存原始媒体与本机绝对路径」;而隐私校验的拒绝是整条丢弃、不是字段脱敏,于是一个可预见的合法输入变成了静默数据丢失。
  • 修复或规避:payload 改存 has_image 布尔 + image_name 文件名(replace("\\", "/").rsplit("/", 1)[-1],Windows/POSIX 都只留文件名),不再出现任何目录成分。
  • 预防规则:凡是把路径/URL/文件名类字段送进跨插件 payload 的地方,写之前先过一遍合同的禁止清单;隐私校验只要是「整条拒绝」语义,就必须为每个会喂它的真实调用点准备正例测试,否则拒绝路径等于静默丢数据。
  • 验证证据:tests/test_m6_r2_legacy_compat.py::R2PrivacyAndVersionTests 三项(Windows 路径、POSIX 路径、无图);联合 E2E L 组新增「带图 proactive_message 可归档且不外泄本机绝对路径」,P 组敏感扫描新增 D:\media 标记。

2026-07-26 — 兼容工件依赖临时联接目录,跑完就不可复跑

  • 阶段:M6.1.3-R2 复验
  • 类型:测试 / 部署
  • 现象:要复跑 R1 留下的 docs/验收工件/M6.1.3-R1/joint_e2e.py 时直接 ModuleNotFoundError——它按 WORK/proj/<插件目录> 解析源码,而 proj 是当时临时建的联接,跑完被清掉了。留在仓库里的只有一个跑不起来的脚本和一份没法再验证的结果 JSON。
  • 根因:验收工件把「运行环境」写进了路径常量,没有从工件位置反推仓库根。
  • 修复或规避:R2 工件改为 PROJECT_ROOT = WORK/proj if exists else WORK.parents[2],保留 proj 覆盖以便在隔离副本上跑,默认直接解析仓库根。
  • 预防规则:验收工件必须能在干净检出上原地复跑,路径一律从 __file__ 反推;结果 JSON 单独存在而脚本跑不起来,等于没有证据。
  • 验证证据:docs/验收工件/M6.1.3-R2/joint_e2e.py 在无 proj 的情况下直接复跑,先复现 R1 基线 85 项 81 通过,修复后 90 项全通过。

2026-07-27 — 维护循环的 per-task try/except 会把签名不匹配当成「这步今天不太顺」

  • 阶段:M6.1.4 创作/媒体/主观分域
  • 类型:功能行为 / 测试
  • 现象:creative.py:_maybe_advance_creative_projects 调 _memory_companion_record_creative_progress(project=, chunk=, extract=),而 wrapper 根本没有 chunk 形参,每次创作推进都 TypeError。主动循环给每个维护步骤包了 try/except,异常只留一行 warning 并计入维护失败;失败累计后「创作推进」整步被 _maintenance_task_blocked_by_failure 阻断,排在它后面的封面生成也一并不再执行。创作功能就这样停摆,页面和日志都看不出是「代码不匹配」。
  • 根因:调用点和 wrapper 分属两个模块、由两轮开发分别改动,中间没有任何测试真正调用过这条链路;而维护循环的容错设计把「偶发运行时错误」和「必然的编程错误」一视同仁地降级成了 warning。
  • 修复或规避:wrapper 补 chunk 形参并只取其长度做里程碑计数;新增测试用 inspect.signature 钉住生产调用点会传的三个参数名,再真实调用一次。
  • 预防规则:凡是被 catch-all 包住的调用点,必须有一个测试用生产调用方的真实参数组合调一次——try/except 会把 TypeError 伪装成运行时波动,靠读日志永远发现不了。跨模块回调建议同时用 inspect.signature 断言参数名,重命名形参时才会立刻炸出来。
  • 验证证据:tests/test_m6_r4_creative_media.py::R4CreativeMilestoneTests 6 项;联合 E2E R 组「creative_progress 接受生产真实调用形状」。

2026-07-27 — 禁用键名写得太宽,会把合同要求的能力一起禁掉

  • 阶段:M6.1.4 媒体索引
  • 类型:隐私 / API契约
  • 现象:_memory_companion_record_photo_generation 100% 静默丢弃——payload 里 prompt 是禁用键名,image_path/reference_image_path 是禁用值。改成媒体索引后仍然写不进去:FORBIDDEN_KEY_PARTS 里有一条裸 "media",把 media_id/media_kind/media_name 全封了。合同要求「媒体只存 ID、摘要、尺寸和类型」,而本侧的禁用清单让这条要求在实现上根本不可能满足。
  • 根因:禁用清单按「关键词像不像敏感词」写,而不是按「这个字段承载的是内容还是标识」写。裸 "media" 同时命中内容键与标识键,且它的存在让清单里的 media_bytes/raw_media 变成冗余,掩盖了范围过宽这件事。
  • 修复或规避:收窄为媒体内容键(media_bytes/raw_media/media_binary/media_data/media_content/media_blob/image_bytes/audio_bytes/video_bytes),标识键放行。prompt 键名禁令保持不动——需要留摘要时改用不含该词的键名(summary + generation_digest),而不是去放宽禁令。
  • 预防规则:禁用清单只禁「内容」不禁「标识」,新增词条前先问一遍「合同有没有要求我存这个字段的标识」;每条禁令都要配一条正例测试证明合规字段仍可通过,否则过宽的禁令会长期伪装成隐私保护。
  • 验证证据:R4PrivacyBoundaryTests 的 test_media_identity_keys_are_allowed 与 test_media_content_keys_are_still_rejected 成对;联合 E2E R 组媒体三项。

2026-07-27 — 幂等键是个没人校验的旁路

  • 阶段:M6.1.4 隐私边界
  • 类型:隐私 / API契约
  • 现象:photo_generation 的幂等键是 photo:{image_path}:{prompt[:120]}。隐私校验只作用于 payload,幂等键完全不过校验,却会原样进 envelope 的 idempotency_key、落进记忆库、还参与 record_id 计算。也就是说只要把 payload 修干净,本机绝对路径和 Prompt 就会换条道进库。补上校验后仍然漏检——_looks_sensitive_value 的路径中缀边界类只有 ^|\s|=,而幂等键里的路径跟在 : 后面。
  • 根因:「payload 要校验」被当成了「敏感数据只可能出现在 payload 里」。而中缀正则的边界类是照着自然语言句子(空格分隔)设计的,没考虑结构化字符串里路径紧跟分隔符的写法。
  • 修复或规避:build_bot_personal_dto 增 validate_bot_personal_key,幂等键与 payload 同一条底线;边界类扩为 ^|[\s=:;,](https:// 不受影响,s:/ 前面是 p);同时把幂等键本身改成 photo:{media_id} 这种不含原始信息的形式。
  • 预防规则:盘点「会落库的字段」而不是「会被校验的字段」——凡是进 envelope 的都要过同一套校验,键、来源引用、ID 一个都不能少。中缀检测的边界类要同时覆盖自然语言分隔(空白)与结构化分隔(: ; , =)。
  • 验证证据:R4PrivacyBoundaryTests 5 项(含 test_path_after_colon_is_now_detected 与 URL 反例);联合 E2E R 组「媒体记录整行无本机绝对路径」。

2026-07-27 — 通用回退整包送信封,会让时间戳漂移变成永久错

  • 阶段:M6.1.4 归档形状
  • 类型:API契约 / 功能行为
  • 现象:非五类走通用回退时,_send_bot_archive 送的是整个 envelope 而不是 body。记忆侧剥离信封字段时没有剥 created_at/updated_at,这两个字段随墙钟走,于是同一条记录隔一小时重投一次,指纹就变了 → 同键同版本不同内容 → version_conflict,而它被判为永久错,直接死信。实测第二次归档 action=error error=version_conflict。顺带还有个形状问题:非五类的 body 被多包一层,落库后 metadata 形状与五类不一致,检索侧要区分两种嵌套。
  • 根因:R1 为了兼容旧调用方让非五类整包送信封,但没有同步检查「信封里哪些字段会进指纹」。指纹覆盖 body 是对的,问题在于 body 里混进了会漂移的信封字段。
  • 修复或规避:两条路径一律送同一个 body_payload(这本来就是「专用与通用发送相同 body」那条门禁的原意);记忆侧同时把 created_at/updated_at/record_id 等提取为 BOT_PERSONAL_ENVELOPE_KEYS 并补进剥离清单,作为纵深防御。
  • 预防规则:进指纹的字段必须全部是「内容」,任何随时间/环境变化的字段都不能留在里面;判断方式是——同一条记录隔一天重投一次,必须 deduplicated,这条应当作为每个归档类型的标准回归。
  • 验证证据:联合 E2E R 组「同一创作里程碑隔时重投 deduplicated」;记忆侧 test_envelope_timestamps_do_not_drift_the_fingerprint。

2026-07-27 — 拿关键词包当检索词,等于每次都查了个寂寞

  • 阶段:M6.1.5 按 Profile 分槽注入
  • 类型:功能行为 / API契约
  • 现象:_memory_companion_compose_schedule_context 会把十几条提示语拼成一个 1400 字的 query,然后原样交给记忆侧检索。而记忆侧的 query 是 SQL 子串匹配(content LIKE '%...%'),一个上千字的关键词包永远匹配不到任何内容——每个 Profile 槽都返回空,注入直接变成空串。联合 E2E 里注入长度为 0 才发现。回头看,改造前的 search_bot_personal_memory 走的是同一个子串匹配、喂的是同一个关键词包,也就是说旧路径在生产上大概率一直返回空,一直靠再往下的 compose_context 兜底,从来没人察觉。
  • 根因:默认「对面的 query 是语义检索」,实际是子串匹配。拼关键词包这种写法只对向量检索有意义,对 LIKE 是纯粹的反效果——越详细越匹配不到。
  • 修复或规避:Profile 已经按类型 + 时间窗定好范围,槽内要的就是「这一类最近的 N 条」,因此不传检索词。补 test_slot_query_is_not_the_giant_keyword_bag 钉死。
  • 预防规则:跨插件传检索词之前,先确认对面是子串匹配还是语义检索——两者对「query 越长越好」的判断完全相反。凡是「检索结果为空」不会报错的路径,必须有一条断言证明它在正常情况下确实返回了东西,否则空结果和没调用长得一模一样。
  • 验证证据:tests/test_m6_r5_profile_injection.py 13 项;联合 E2E S 组「陪伴侧注入按槽位标注且声明当前以本地运行态为准」。

2026-07-27 — 验收工件里的 reset 方法比生产实现旧了一个版本

  • 阶段:M6.1.5 联合复验
  • 类型:测试 / 环境
  • 现象:E2E Harness 自己实现了 reset_bridge_cache(),写的是 self._bridge_cache = None。而审计 Batch 1 之后,生产实现改用 _BRIDGE_UNPROBED 哨兵区分「没探测过」与「探测过、没有记忆插件」——None 现在表示后者,是负缓存。于是 E2E 里重置完缓存,Bridge 再也发现不回来,compose 恒返回空。
  • 根因:验收工件复制了一份宿主行为的实现,源码改了它不会跟着改;而它「看起来还能跑」,因为大部分断言并不经过这条路径。
  • 修复或规避:Harness 改用 adapter_mod._BRIDGE_UNPROBED,与生产同源。
  • 预防规则:验收工件里凡是复刻宿主行为的代码,都要直接引用生产模块的常量/函数,不要抄一份值。抄下来的那一刻它就开始过期,而且过期得无声无息。
  • 验证证据:docs/验收工件/M6.1.5/joint_e2e.py 的 Harness.reset_bridge_cache;改后 S 组陪伴侧注入两项转通过,全量 115 项全通过。

2026-07-27 — 回滚副本放在插件目录里,就会被当成插件加载

  • 阶段:M6.1.8 VM 部署
  • 类型:部署 / 环境
  • 现象:替换记忆插件时把原件留成同目录下的 astrbot_plugin_memory_companion_ops.old,AstrBot 扫描插件目录时把它当成一个插件去导入,报 ModuleNotFoundError: No module named 'data.plugins.astrbot_plugin_memory_companion_ops.old',日志里多出一条 ERRO。功能没受影响,但启动日志从此不干净——而部署验收恰恰要靠「启动日志无错误」来判断。
  • 根因:把「就近留个回滚副本」和「插件扫描目录」放在了同一个地方。本仓错题本里早有「回滚副本不入扫描目录」这条,部署时没有对照执行。
  • 修复或规避:两个回滚副本一律移进 ops-replace-backups/<时间戳>/,扫描目录里只留活动插件;替换后立即 ls 确认无 .old/.new/.stage 残留。
  • 预防规则:任何「原地改名保留旧版」的操作,先确认这个目录会不会被某个扫描器遍历——插件目录、任务目录、配置目录都算。部署脚本里把「回滚副本落到备份区」写成固定步骤,而不是临时决定。
  • 验证证据:移出后重启,最新启动窗口内无 ERRO / Traceback / 导入失败;服务 active、NRestarts=0。

2026-07-27 — 配置里写了默认 Provider,不等于 Provider 已经装载

  • 阶段:M6.1.8 真机日程链路验证
  • 类型:功能行为 / 环境
  • 现象:VM 上日程恒为 source=fallback。时间戳把竞态钉死了:03:38:53.755 插件加载 → 03:38:55.558 主动循环启动 → 03:38:55.798 解析默认 Provider 失败 → 03:38:56.619 AstrBot 才打出 "Selected ... as default chat model provider"。插件比宿主早 0.8 秒问 Provider。直连 API 探针确认模型本身可用(HTTP 200、315 tokens),问题不在模型。
  • 根因:两层。一是 _default_chat_provider_id 只认 get_using_provider(),4.26.6 的 Context 只暴露 get_config(),没有 astrbot_config/config 属性,兜底链断在这里;二是补了配置兜底之后仍然错——从 provider_settings.default_provider_id 读到的只是「配置里指定了谁」,实例还没注册,照样拿到 Provider BOT 1X/gpt-5.6-terra not found。竞态只是从「拿不到 id」挪到了「拿到了一个没人认的 id」。
  • 修复或规避:兜底链读到 id 后必须用 context.get_provider_by_id(id) 确认实例真的在;新增 _chat_provider_ready() 区分「还没就绪」与「模型不可用」;_ensure_daily_plan 在未就绪时跳过本轮而不是写兜底计划,DAILY_PLAN_PROVIDER_MAX_WAITS = 5 对应「每 5 分钟重试、共 5 次」,超限才退化。
  • 预防规则:启动期取宿主资源,一律区分「配置声明」与「实例可用」,只有后者算就绪。写兜底之前先问一句「现在是真失败,还是只是早了几秒」——把早到当失败,会把降级结果固化成当天的正式数据。
  • 验证证据:tests/test_provider_readiness.py 8 项;VM 复跑 30s 记 等待轮次=1 且不写兜底,第 5 轮 source=llm 10 段、8111 tokens、33.4s。

2026-07-27 — 幂等键不变、版本号不动,同日改计划会被静默丢弃

  • 阶段:M6.1.8 真机归档链路验证
  • 类型:数据一致性 / 跨插件契约
  • 现象:兜底计划先落库(8 段、v1),同一天模型恢复后生成的真实计划(10 段)在库里完全看不到——bot_schedule_plan 最新一条仍是兜底那份,updated_at 纹丝不动。outbox 里也没有新条目。既不是失败也不是报错,是彻底无声。
  • 根因:daily_plan 的幂等键恒为 daily_plan:<date>,而 planning.py 构造的计划字典从来不带 version,适配器 _safe_int(plan.get("version"), 1) 于是每次都发 v1。记忆侧 store.py 判 version == stored_version 且指纹不同 → version_conflict 拒绝;陪伴侧 enqueue_outbox 同键同版本返回 accepted=False,而状态更新整段都在 if ... accepted 里,于是拒绝结果既不落 outbox 状态也不留日志。M6.1.3 给 agenda_snapshot 修过同类问题,但那次只补了「透传 version」,没人问过生产者到底有没有 version。
  • 修复或规避:新增 _next_daily_plan_version(plugin, plan_date),同时看 daily_plan 与 daily_plan_history 取最大版本 +1(历史条目同步补 version 字段,运维清空 daily_plan 后版本才不会退回 1 撞上库里已有记录);另外把「远端拒绝」的告警移到 accepted 判断之外,任何 ok=False 都留一条可检索的 warning。
  • 预防规则:透传字段之前先确认上游真的在产生它——「把 version 传下去」和「version 有值」是两件事。凡是同一幂等键会被重复写入的链路,必须有一条测试证明第二次写入改变了库内容,而不是只证明第一次能写进去。
  • 验证证据:tests/test_daily_plan_version.py 7 项;VM 复跑本地 v=2 source=llm 10 段 与库内 v=2 source=llm 10 段 一致,updated_at 推进到 2026-07-26T20:13:31Z。