astrbot_plugin_private_comp.../docs/前端改造要求-Q6-Bot自有存储与用户记忆边界.md

11 KiB

前端改造要求:Q6 Bot 自有存储与用户记忆边界

1. 文档目的

本文档规定运维版陪伴插件前端页面的后续改造范围。

当前先完成后端数据模型、接口和运行时行为,前端暂不立即修改。等后端改造稳定、接口字段冻结、VM 验收通过后,再按本文档统一修改页面,避免前端反复跟随未稳定的后端字段调整。

本文件只适用于运维分支 ops-main,不约束普通陪伴分支。

2. 改造原则

  1. 先后端,后前端:先完成存储、接口、权限边界和兼容迁移,再统一调整页面。
  2. 页面展示真实边界:用户必须能看懂哪些内容属于用户记忆,哪些内容属于 Bot 自己的资料。
  3. 不把内部存储直接暴露成复杂数据库管理器:前端以状态、摘要、时间线和安全操作为主,不提供任意修改底层 JSON/SQLite 的入口。
  4. 计划和事实分开显示:计划时间、实际发生时间、延迟、取消和部分完成不能合并成一条模糊记录。
  5. 迁移默认只读预览:旧数据迁移必须先显示影响范围,确认后才能执行隔离或归档。
  6. 不让页面暗示 Bot 数据进入记忆插件:所有相关文案必须明确记忆边界。
  7. 不增加无必要的轮询:总览使用已有快照接口;详情页按需加载,避免每次打开页面都读取完整历史。

3. 当前前端存在的问题

现有页面已经有总览、观察、主动、配置和存储方式等区域,但主要仍按旧模型组织:

  • 总览页能显示部分日程和生活记录,但没有独立的 Bot 自有存储状态。
  • 观察页把日记、梦境、生活记录和长期记忆放在相近的展示语义中,容易误认为它们都会写入记忆插件。
  • 配置页仍保留 livingmemory、memory_companion 等旧概念,未清晰表达“外部记忆插件只保存用户数据”。
  • 页面没有展示 Bot 自有记忆、Bot 自我时间线、Bot 日程历史和 Bot 人格状态。
  • 页面没有展示用户侧活动、Bot 侧活动和共同活动的分拆结果。
  • 现有配置迁移界面是通用配置导入/备份流程,不等于 Q6 旧 Bot 数据隔离迁移。
  • 页面没有提供记忆 Bridge 隔离状态、写入计数或最近一次边界检查结果。

4. 后端完成后必须提供的页面数据

前端开始改造前,后端接口至少需要稳定提供以下信息。字段名称可以在实现阶段调整,但语义必须保持一致。

4.1 总览状态

建议由 /overview 返回:

  • 当前现实日期、时间和时区。
  • 当前日程日期和当前时间窗口。
  • 计划项数量、已完成数量、延期数量、取消数量和未开始数量。
  • 最近一次日程对账时间。
  • Bot 自有存储是否启用、版本、最近写入时间和各命名空间数量。
  • 用户记忆 Bridge 是否可用、当前来源、搜索能力和最近一次检查时间。
  • Bot 数据外写拦截状态。
  • 旧数据迁移是否需要预览。

4.2 Bot 自有存储摘要

建议增加独立的 bot_self 或等价对象,不把原始存储直接塞进旧的 memory 对象:

  • bot_self_memory:Bot 自己形成的记忆或自我认知摘要数量和最近更新时间。
  • bot_self_timeline:Bot 自我时间线数量、最近事件和时间范围。
  • bot_agenda_history:Bot 日程历史数量、最近计划和执行结果。
  • bot_persona_state:当前人格状态摘要、更新时间和来源。
  • legacy_quarantine:待隔离旧数据数量、最近预览时间和迁移状态。

4.3 用户记忆边界摘要

建议增加独立的 memory_boundary 或等价对象:

  • 当前外部记忆插件名称和版本。
  • 当前是否只接收用户数据。
  • 最近一次用户记忆写入时间。
  • 最近一次 Bot 数据拦截/拒绝外写时间。
  • 当前是否发现疑似 Bot 数据混入。
  • 发现问题时提供可读的原因和排查建议。

4.4 日程和时间线数据

页面需要同时拿到:

  • plan:原始计划。
  • observed:实际观察到的活动。
  • world:外部或 World 来源事件(接入前也要保持空状态可显示)。
  • reconciled:最终用于展示的统一日程视图。
  • adjustments:延期、取消、覆盖、部分完成等对账记录。
  • 事件来源、证据等级、可见范围和最后更新时间。

5. 页面改造要求

5.1 总览页

在现有“今日概览”下增加三个清晰的状态卡:

A. Bot 自有空间

显示:

  • Bot 自有存储:正常/需要迁移/异常。
  • Bot 日程、时间线、人格状态和自有记忆的数量摘要。
  • 最近一次 Bot 自己写入的时间。
  • “查看 Bot 时间线”和“查看 Bot 日程”按钮。

B. 用户记忆空间

显示:

  • 用户记忆插件:可用/不可用/未配置。
  • 当前规则:“只保存用户硬性对话数据”。
  • 最近一次用户记忆写入时间。
  • 是否发现 Bot 数据外写。

C. 日程对账

显示:

  • 当前现实日期和时区。
  • 当前时间窗口。
  • 计划、实际、延期、取消和未完成数量。
  • 最近一次对账时间。

总览页只显示摘要,不直接展开完整历史。

5.2 观察页

将现有混合语义拆成至少四个区块:

  1. 用户记忆:只显示用户数据摘要、来源和入库时间。
  2. Bot 自有记忆:显示 Bot 自己形成的资料,不提供“同步到长期记忆”的误导性按钮。
  3. Bot 自我时间线:显示 Bot 自己的经历、计划、创作、梦境和状态变化。
  4. 共同活动:显示双方共同参与的活动,并标注用户侧投影、Bot 侧投影和共同事件。

每条记录至少显示:发生时间、记录时间、来源、主体、可见范围、证据等级和当前状态。

5.3 日程页面

现有完整日程区域需要改为真实日期时间视图:

  • 支持按日期查看,而不是只显示“今天的若干段落”。
  • 清楚区分计划时间和实际时间。
  • 延迟、取消、部分完成和未开始使用不同状态。
  • 显示 Bot 自己的日程与共同活动,但不把用户普通聊天自动变成 Bot 日程。
  • 对没有明确日期的内容标记为“待确认话题”,不能伪装成确定日程。
  • 显示时区,默认使用运行环境配置的现实时间系统。
  • World 尚未接入时显示“当前无 World 来源”,不能显示为系统故障。

5.4 配置页

配置页新增“数据边界”分组,内容包括:

  • Bot 自有存储:启用状态、存储位置、版本和只读摘要。
  • 用户记忆边界:固定显示“仅保存用户数据”。
  • Bot 数据外写保护:启用状态和最近检查结果。
  • 旧数据迁移:只提供预览、隔离和查看结果,不提供直接删除。
  • 共同活动记录策略:显示用户侧、Bot 侧和共同事件的保存范围。

以下内容不得作为普通可编辑项暴露:

  • 任意修改 bot_self_store 原始结构。
  • 任意改变用户记忆与 Bot 自有存储的硬性边界。
  • 任意将 Bot 日程转写为用户长期记忆。
  • 任意绕过外写拦截器。

5.5 排障页

增加“记忆边界与日程一致性”检查:

  • Bot 数据是否被调用外部记忆写入接口。
  • 用户记忆写入是否带有用户主体和入库时间。
  • Bot 自有数据是否仍写在旧字段中。
  • Bot 自有数据是否已经完成隔离迁移。
  • 计划、实际活动和统一日程是否存在无法对账的记录。
  • 当前时间、时区和存储时间是否一致。

每项检查需要显示:状态、检查时间、简短原因和建议动作。

6. 文案要求

页面必须使用白话文,避免只显示内部术语。

推荐文案:

  • “Bot 自有空间”——不要只写 bot_self_store。
  • “用户记忆”——明确说明“只记录你的真实对话和事实”。
  • “不会写入用户记忆插件”——用于 Bot 日程、梦境、人格和自我时间线说明。
  • “计划”和“实际发生”——不要只写 plan、observed。
  • “旧数据待隔离”——不要只写 legacy_quarantine。
  • “证据强度”——同时提供“系统记录”“用户明确说过”“推测”等解释。

7. 后端完成后的实施顺序

前端不要在后端字段尚未稳定时提前开发。后续统一按以下顺序推进:

  1. 冻结 /overview、日程详情、Bot 自有存储摘要和边界检查接口。
  2. 用真实 VM 数据验证接口返回,不使用只有测试数据才能通过的假字段。
  3. 修改总览页状态卡和页面数据映射。
  4. 修改观察页,将用户记忆、Bot 自有数据和共同活动拆开。
  5. 修改日程页,接入真实日期、计划/实际对账和时间窗口。
  6. 修改配置页,增加数据边界和旧数据迁移预览。
  7. 修改排障页,增加外写隔离和时间一致性检查。
  8. 清理旧文案和无效入口,但保留必要的兼容显示。
  9. 完成本地测试、VM 部署和实机验收。

8. 前端验收标准

功能验收

  • 页面能明确区分用户记忆和 Bot 自有数据。
  • Bot 日程、人格、梦境和自我时间线不会被显示成用户长期记忆。
  • 计划时间和实际时间能够同时显示。
  • 延期、取消、部分完成和未开始状态能够区分。
  • 旧数据迁移先预览,执行后能看到隔离结果。
  • 用户记忆 Bridge 状态与 VM 实际运行状态一致。

安全验收

  • 前端没有绕过后端边界直接写入外部记忆插件的接口。
  • 页面不提供任意修改底层 Bot 自有存储的能力。
  • 页面不提供无确认删除旧数据的按钮。
  • 用户数据、Bot 数据和共同活动数据的可见范围明确。

性能验收

  • 打开总览不读取完整历史原文。
  • 详情数据按页面或用户操作按需加载。
  • 重复刷新不会触发重复迁移或重复写入。
  • 接口响应异常时页面显示降级状态,而不是把“无数据”显示成“数据已丢失”。

VM 验收

  • 页面显示的存储目录、插件版本和 Bridge 状态与 VM 实际值一致。
  • 重启 AstrBot 后页面仍能读取 Bot 自有存储摘要。
  • 记忆插件不可用时,Bot 自有存储和日程页面仍可正常工作。
  • 前端改造不会覆盖现有陪伴数据,也不会影响记忆插件自身数据。

9. 明确不在本轮前端范围内的内容

  • 不在页面中实现 World Server。
  • 不把普通聊天全文展示为可编辑记忆库。
  • 不把 Bot 自有数据同步到外部记忆插件。
  • 不重做普通陪伴分支的页面。
  • 不因为前端改造顺便恢复已删除的娱乐模块。

10. 当前状态

  • 后端 Q6 存储边界和运行时改造:已完成并部署验收。
  • 前端页面统一改造:待后端接口最终冻结后开始。
  • 本文档:作为后续前端实现和验收依据。