astrbot_plugin_private_comp.../docs/运维陪伴错题本.md

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