astrbot_plugin_memory_compa.../docs/时间感知兼容说明.md

2.8 KiB

时间感知兼容说明

Q4:记忆插件时间感知改造;数据库结构不变。

统一合同

记忆记录继续保留 occurred_at、created_at、updated_at 和 last_accessed_at 四个独立字段。core/temporal_context.py 在检索、注入、Bridge 和 Archivist 序列化时动态生成 temporal,不会把 age_seconds 或 age_minutes 写回数据库。

记录 metadata 会补齐以下来源信息:

  • time_source:事件时间来源;未知时为 unknown,无可靠事件时间时为 ingestion_time。
  • time_precision:second、minute、hour、date 或 unknown。
  • timezone:默认 Asia/Shanghai,调用方可覆盖。
  • ingested_at:进入记忆库的时间。
  • occurred_at_estimated:无法确认事件时间时为 true。

平台来源矩阵

平台/入口 首选时间值 time_source 估算规则
QQ Official AstrBot 事件或消息对象携带的消息时间 event_timestamp 或 message_timestamp 没有事件时间时回退 ingestion_time,并标记估算
OneBot/QQ OneBot/AstrBot 消息事件时间 event_timestamp 或 message_timestamp 不使用 last_accessed_at;缺失时估算
Telegram 适配器传入的消息时间 message_timestamp 外部转发只有观察时间时使用 controller_observed_at
历史导入 导入记录原始时间 imported_record 原始记录无时间时使用 ingestion_time
外部 Controller Controller 返回的观察/发生时间 controller_observed_at 只有观察时间时不得伪装成事件实际发生时间

调用方应把上述字段放入 MemoryRecord.metadata 或 record_external_event() 的 metadata;时间值本身仍放入 occurred_at,入库时间由 created_at/ingested_at 表示。

注入与 Bridge

  • 普通注入带紧凑的“发生、距今、跨日、状态”信息。
  • 时间敏感查询带发生时间、入库时间、当前提取时间、年龄、跨日、有效性、来源和精度。
  • serialize_memory()、archive_payload() 和 Archivist 检索结果都包含 temporal。
  • bridge_get_reply_delay() 返回隔夜等延迟标签;私聊可建议提及,群聊默认关闭私密等待情绪。
  • 运维状态仍以 NAS Ops/Controller 当前事实为准,旧记忆只能作为历史背景。

数据库结论

无需迁移。现有 metadata 已是 JSON 字段,新增来源字段使用向后兼容的默认值;动态年龄只在读取出口计算,不新增表列,也不改变历史记录主键或索引。

降级行为

时间值为空、格式错误或时区不可用时,计算层返回 age_label=unknown、time_source=unknown 或 ingestion_time,Bridge/注入继续返回正常结果,不阻断聊天。