docs: add frontend migration contract

这个提交存在于:
YokiiroBW 2026-07-26 00:14:38 +08:00
父节点 0113666e5c
当前提交 6afa64bb51

查看文件

@ -0,0 +1,241 @@
# 前端改造要求: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 存储边界和运行时改造:已完成并部署验收。
- 前端页面统一改造:待后端接口最终冻结后开始。
- 本文档:作为后续前端实现和验收依据。