astrbot_plugin_private_comp.../docs/运维陪伴错题本.md
YokiiroBW 1bd4821538 chore: script the deployment discipline
There was no shell script anywhere in either repo, so every deployment was
typed by hand and every deployment re-exposed the same pitfalls: rollback
copies left in the plugin scan directory, wrong ownership, stale pycache,
deploying the companion before memory, and a rollback pointer left aimed at an
older backup.

ops/deploy-plugin.sh fixes the order: local test gate, remote backup with the
LATEST_M6 pointer updated, stop, memory before companion (the companion probes
the memory bridge at startup and caches a negative result if the peer is
absent), ownership and modes, a scan-directory residue check that exits
non-zero on any .old/.new/.bak, remote compileall with PYTHONPYCACHEPREFIX,
start, then verification of service state and plugin-level error count.

The ownership rule was documented two ways -- root:root in the errata,
astrbot:astrbot in the M6.1.8 record. The service runs as User=astrbot, so
astrbot:astrbot is correct and the script now says so in a comment.

Also noted, in the script and the errata: QQ's official platform rate-limits
bot session starts, and restarting eight times within an hour made the
qq_official adapter fail to log in. Batch deployments should batch restarts.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 05:42:03 +08:00

74 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。

2026-07-27 — 删功能时删了实现没删调用点,故障藏在「结果看起来是好的」后面

  • 阶段:P0 生产缺陷清理
  • 类型:清理未完成 / 可观测性
  • 现象:daily_state.py 调用 _ensure_daily_news_reading,该方法在新闻/日报功能退役时已被删除,全仓只剩这一个调用点。生产 VM 三小时内抛 14 次 AttributeError,主动循环把「今日日程」标为失败并进冷却;「查看日程/重置细化」等命令与页面 refine_schedule 入口同样报错。而这一切在验收里完全不可见——崩溃点在计划保存之后,所以查 companions.json 永远看到一份完整正确的计划。
  • 根因:删功能只删了实现与配置入口,没有反查调用方。更关键的是调用点位于「保存之后、返回之前」,异常被上层 catch 成一条 warning,主链数据正确,于是没有任何一个断言会失败。
  • 修复或规避:删掉调用点;补 test_no_production_code_calls_the_removed_news_reader,用全仓扫描而不是单点断言——这类残余按定义就不知道会藏在哪。同时补一条反面断言证明该方法确实不存在,否则测试本身可能因为改名而失效。
  • 预防规则:删除一个方法之前先全仓搜它的名字,把调用点一起处理;退役功能的收口要有一条「全仓无引用」的扫描型断言。凡是 try/except 包住的调用,都要问一句「如果它一直失败,我从哪看得出来」——看不出来就得升级日志级别或加断言。
  • 验证证据:tests/test_p0_runtime_fixes.py 12 项;VM 重启后 3 分钟窗口内 _ensure_daily_news_reading 与「主动循环维护步骤失败」命中数均为 0,ERRO/Traceback 为 0。

2026-07-27 — 新开关没写进 _conf_schema.json,等于没有开关

  • 阶段:P0 生产缺陷清理
  • 类型:配置一致性
  • 现象:归档总闸 enable_memory_companion_bridge(main.py 用 _cfg_bool 读)在 _conf_schema.json 里 grep 命中 0 处。后果是设置页看不到它、改了也不落盘,运维想确认或临时切断双插件联动时无从下手。
  • 根因:上一轮把桥的开关从 enable_livingmemory_integration 拆出来时,只改了 Python 侧的读取,没同步 schema。而 _cfg_bool 读不到就取默认值 True,功能表现完全正常——缺失的是可操作性,不是功能,所以任何功能测试都不会失败。
  • 修复或规避:加进 external_memory_config.items(可见分组,不是 invisible 的 legacy flat 区),并补两条断言:一条钉死它在可见分组里且未被标 invisible,一条证明 _flat_get 能穿过分组按扁平键读到——schema 挂在分组下而代码按扁平键读,这两件事必须同时成立。
  • 预防规则:新增配置项的定义是「Python 读取 + schema 条目」两半,缺一半时功能仍然正常,只有可操作性消失。凡是新增 _cfg_* 读取,同一个提交里必须有对应的 schema 条目。
  • 验证证据:tests/test_p0_runtime_fixes.py::BridgeSwitchSchemaTests;VM 重启后配置文件里 external_memory_config.enable_memory_companion_bridge = True 已落盘。

2026-07-27 — 兜底结果带上日期,就等于把降级固化成一整天

  • 阶段:P0 生产缺陷清理
  • 类型:功能行为
  • 现象:Provider 连续 5 轮未就绪后写入模板兜底日程,而 _ensure_daily_plan 有三处复用分支都以「daily_plan.date == today」为条件直接返回,于是当天不再生成。一次启动时序抖动就把模板兜底固化成正式的一天,并顺着归档链路进入长期记忆;下游的细化增强、日记、每日穿搭全部基于这份假计划。
  • 根因:source="fallback" 这个标记产出了却无人消费。复用分支只看日期,不看这份计划是真实生成还是降级产物。
  • 修复或规避:新增 _daily_plan_can_upgrade_from_fallback,当天的兜底计划在 Provider 恢复后允许再取一次真实计划;DAILY_PLAN_FALLBACK_RETRY_LIMIT = 3 防住「Provider 就绪但生成始终失败」时每个 tick 重跑模型;重试计数按日期分桶,昨天用掉的额度不占今天的;真实计划到手即清空计数。归档侧靠已有的版本水位做 upsert,不会撞版本冲突。
  • 预防规则:凡是写入了「降级/兜底」标记的数据,都要有一条链路消费这个标记——否则标记只是自我安慰。带日期的缓存键要问一句「如果这份数据是坏的,什么时候会被替换」,答不上来就是固化。
  • 验证证据:tests/test_p0_runtime_fixes.py::FallbackUpgradeTests 8 项(含额度耗尽、跨日分桶、坏状态容错);VM 上当天计划保持 source=llm v=2 10 段,重试计数为空。

2026-07-27 — 固定天数的补算窗口,等于给「静默丢数据」定了个期限

  • 阶段:P1 遗留缺陷清理(上轮 #14,连续四轮被推迟)
  • 类型:数据一致性
  • 现象:_agenda_closed_windows 固定扫 -3..+1 天。停机超过 3 天,中间那些窗口既不会被补算,也不留任何痕迹——数据里就是一段空洞。而「快照数为 0」和「本来就没到时间」在结果上长得一模一样,所以这个缺陷挂了四轮都没人能从现象上发现它。
  • 根因:用「最近几天」近似「还没结算的部分」。这个近似在服务不间断时成立,恰好在最需要补算的场景(长时间停机)下失效。
  • 修复或规避:持久化 agenda_last_settled 游标,从游标往前扫;游标缺失时退回原来的 3 天,兼容旧数据。补算跨度上限 AGENDA_SETTLE_MAX_CATCHUP_DAYS = 30,超出部分明确告警后放弃——不是不允许有上限,是不允许静默截断。游标只在快照与结算都写完之后推进,且只前进不后退。
  • 预防规则:凡是「扫最近 N 天/条」的补偿逻辑,都要问一句「N 不够时会发生什么」。答案是「静默少算」就必须换成游标。任何截断都要留日志,否则「跑完了」和「跑了一部分」无法区分。
  • 验证证据:tests/test_agenda_settle_cursor.py 8 项(含停机 10 天补算、超上限告警、游标不回退、坏游标容错、旧字符串游标兼容)。

2026-07-27 — 幂等键格式与合同不符:一处双前缀,一处拿内部 id 当业务键

  • 阶段:P3 遗留缺陷清理(P2-6)
  • 类型:跨插件契约
  • 现象:reconciliation_id 本身已是 reconciliation:{date}:{window},归档时又套一层前缀,落库键成了 reconciliation:reconciliation:2026-07-24:早晨;窗口快照则用内部 snapshot_id 拼成 agenda_snapshot:snapshot-2026-07-24-下午。合同 FROZEN 1.0 第 90 行推荐的是 reconciliation:{date}:{window} 与 window_snapshot:{date}:{window}。
  • 根因:拼键时顺手用了手边的 id,没有回看那个 id 自己是什么格式。键唯一且稳定,所以功能一直正常,只有格式不对——这类问题不会自己暴露。
  • 修复或规避:抽出 _bot_personal_window_key(date, window, prefix=..., fallback=...) 统一按合同格式拼;date/window 缺失时退回旧键,宁可格式不好看也不产出没有业务含义的键。已落库的旧键保持不变:结算与快照都是按窗口一次性写入的终态记录,不存在后续更新,键格式切换不会产生孤儿。
  • 预防规则:拼幂等键时先确认参与拼接的每个部分自己是什么格式,尤其是名字里已经带冒号的 id。跨插件的键格式以合同为准,合同里给了推荐格式就照抄,不要就地发明。
  • 验证证据:tests/test_p3_key_and_clock.py::WindowKeyFormatTests 3 项。

2026-07-27 — outbox 用系统时钟,与窗口归属不是同一套时间源

  • 阶段:P3 遗留缺陷清理(P2-7)
  • 类型:时间与时区
  • 现象:bot_personal_outbox._now() 直接取 datetime.now().astimezone(),而窗口归属、DTO 的 occurred_at 走的是插件的 _environment_now(带时区、可被测试与运维覆盖)。两套时钟意味着 outbox 的创建时间、重试时间可能与它描述的那个窗口不在同一天。
  • 根因:_now() 早就留了 now 参数,但所有调用点都没传——留了扩展点却没接上,比没留还隐蔽,因为签名看起来是对的。
  • 修复或规避:新增 _memory_companion_clock() 取插件时钟(取不到就退回 None,由 outbox 自己兜底),8 个 outbox 调用点全部带上 now=。测试用 2031 年的插件时钟与真实系统时钟拉开距离,时间戳落在 2031 才算通过。
  • 预防规则:函数留了 now/clock 这类可注入参数,就要有一条测试证明调用方真的传了——用一个不可能与系统时钟重合的值来断言,而不是断言「格式是 ISO」。
  • 验证证据:tests/test_p3_key_and_clock.py::OutboxClockTests 2 项;全量 231 项通过、联合 E2E 135/135。

2026-07-27 — 「最后写入时间」和「结算到哪个时刻」是两个字段,混用一个就没有衰减

  • 阶段:P0 生产缺陷清理
  • 类型:功能行为
  • 现象:只要用户在持续对话,Izard 四维与 Plutchik 八维就永不回落,情绪提示词长期停在被最后一次事件推高的状态。实跑对照(recovery=24/h,每 30 秒一条 × 120 次 = 1 小时):修复前四维恒为 -80/90/80/20、sadness 恒 80、anger 恒 70,一格未动。
  • 根因:updated_ts 在两个函数之间被当成两种语义。_decay_* 里它是「这组数值结算到哪个时刻」的衰减锚点,上一轮已经改成「真消耗了一格才推进,不足一格保留让时间可累计」;而 _update_* 把它当成「最后一次被写入的时间」,写在所有事件分支之外无条件执行。主链每条私聊消息都会调 _update_*,于是锚点被逐条消息冲成 now,hours 永远涨不到一格(默认 150 秒),steps 恒为 0,衰减分支永不执行——上一轮的修复被完全抵消。更进一步:四维/八维共用同一个锚点,任一维被 nudge 就重置整组时钟,所以「亲密对话推高 joy/trust」会连带冻结 anger/sadness/fear。
  • 修复或规避:删掉两个 _update_* 里的无条件写入,把锚点所有权交还给 _decay_*。不是加「命中分支才推进」的条件——apology/comfort 这些分支本身在降情绪,更没有理由重置衰减时钟。核对过消费面:全仓只有两个 _decay_* 读这个字段,页面摘要与前端都不读它,受伤余波的硬闸门走的是另外三个独立时间戳,不受影响。
  • 预防规则:一个时间戳字段只能有一种语义。「最后修改时间」和「结算锚点」看起来都叫 updated_ts,但前者可以随便推进,后者推进一次就丢掉一段没被消耗的时间。共享锚点的多维状态尤其危险:任一维的写入都会连累其余维度,而症状只在「某几维不衰减」上体现,很难联想到锚点。
  • 验证证据:tests/test_audit_batch1.py::B2EmotionUpdateTimestampTests 4 项(高频对话仍衰减、分步与静默一小时严格等价、正向事件不冻结负向维度、单次事件不吞掉不足一格的时间)。反证:临时还原成缺陷版,这 4 项全红。全量 235 项通过。

2026-07-27 — 清理写在 return 旁边,就一定漏掉异常和取消

  • 阶段:P0 生产缺陷清理(B7)
  • 类型:资源泄漏
  • 现象:识图会把 http(s) 图片源下载落盘到 private_inbound_images/<namespace>/,唯一的删除入口是 _cleanup_prepared_image_sources。私聊侧六处清理调用全部包在 if group_mode: 里(group_mode = clean_cache_scope == "group_image"),只有群聊识图会清;forward 侧复用了准备函数却没复制配套的清理调用,四条 return 全泄漏。单文件上限 12 MB,随消息量无界增长。
  • 根因:清理责任被绑在「各条 return 语句旁边」,而不是绑在临时文件的生命周期上。于是出现三重漏洞:被业务开关误当作条件、复用者只抄了申请没抄释放、逐 return 点手工清理天生覆盖不到异常与取消路径——识图协程被 asyncio.wait_for 超时取消时抛的是 CancelledError,except Exception 捕不到,六处清理全部落空(群聊也一样漏)。
  • 修复或规避:三条防线各管一段。①去掉六处的 group_mode 门控——清理是临时文件的生命周期,不是群聊功能的一部分;②forward 侧拆出内层函数、外层 try/finally 收口,正常与异常路径都清;③准备新图之前先按存活时长清扫该 namespace(PREPARED_IMAGE_MAX_AGE_SECONDS = 30 分钟),这一条不依赖任何一条 return 走到,覆盖异常与取消。没有采用「把 260 行函数整体包进 try/finally」的方案:那需要整体改缩进,风险大于收益,而按时长清扫对取消路径的覆盖反而更彻底。
  • 预防规则:临时资源的释放要绑在申请点的同一个作用域(try/finally),不能散落在下游各个 return 分支。只要清理逻辑出现在 if <业务条件>: 里面,就该警觉——释放不该有业务条件。此外,凡是可能被 wait_for 取消的协程,except Exception 都不算兜底,必须另有一条不依赖控制流的回收路径。
  • 验证证据:tests/test_b7_image_temp_files.py 8 项(按时长清扫、准备时先清扫、清理点不再被门控、forward 侧正常/异常/取消三条路径都清理)。全量 243 项通过;联合 E2E 146/146。

2026-07-27 — 部署纪律固化成脚本,顺带定死属主规则的冲突

  • 阶段:P5 部署可重复性
  • 类型:部署 / 环境
  • 现象:仓库里没有任何 .sh/.ps1,每次部署都是手打命令,于是每次都在重新暴露同一批历史问题(回滚副本落在扫描目录、属主权限、旧 pycache、部署顺序、备份指针没更新)。更麻烦的是属主规则本身两处冲突:本错题本早期写 root:root,M6.1.8 记录写 astrbot:astrbot,脚本化之前必须先定一个。
  • 根因:纪律只写在文档里,执行靠人记。文档条目一多,执行时就会漏掉其中一两条,而漏掉哪一条每次都不一样。
  • 修复或规避:新增 ops/deploy-plugin.sh,把顺序写死:本地测试门禁 → 远端备份并更新 LATEST_M6 指针 → 停服 → 记忆先于陪伴(陪伴启动时会探测记忆插件的桥,对端不在会落进负缓存)→ 属主 astrbot:astrbot、目录 0755、文件 0644 → 扫描目录残留检查(.old/.new/.bak 一律报错退出)→ 远端 compileall(带 PYTHONPYCACHEPREFIX)→ 启动 → 验证服务与插件级错误数。属主之争按实机与 systemd 配置定案:服务以 User=astrbot 运行,因此是 astrbot:astrbot,错题本早期那条 root:root 是错的。
  • 附带记录:QQ 官方平台对 bot 会话启动次数有限流,一小时内反复重启会让 qq_official 适配器登录失败(self._ws_ap["session_start_limit"] 为 None → TypeError)。这次连续 8 次重启后触发了一次。批量部署要合并重启次数,脚本末尾也写了这条提醒。
  • 预防规则:写进错题本的部署纪律,如果三次以上部署都要手动重复,就该固化成脚本。两份文档对同一条规则给出不同值时,以实机与服务配置为准,并在固化时把结论写进代码注释——否则下一次还会再争一遍。
  • 验证证据:ops/deploy-plugin.sh(bash -n 通过、参数校验与 both+文件列表的互斥校验实测生效)。