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

44 行
2.8 KiB
Markdown

# 时间感知兼容说明
> 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/注入继续返回正常结果,不阻断聊天。