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

206 行
无行尾
16 KiB
Markdown

此文件含有模棱两可的 Unicode 字符

此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的,可以安全地忽略该警告。 使用 Escape 按钮显示他们。

# 运维陪伴插件错题本
> 适用仓库:`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-*` 导入错误。