From 6afa64bb5161c1fff300c4d4118c73042e3c41cf Mon Sep 17 00:00:00 2001 From: YokiiroBW Date: Sun, 26 Jul 2026 00:14:38 +0800 Subject: [PATCH] docs: add frontend migration contract --- ...�端改造要求-Q6-Bot自有存储与用户记忆边界.md | 241 ++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 docs/前端改造要求-Q6-Bot自有存储与用户记忆边界.md diff --git a/docs/前端改造要求-Q6-Bot自有存储与用户记忆边界.md b/docs/前端改造要求-Q6-Bot自有存储与用户记忆边界.md new file mode 100644 index 0000000..6331243 --- /dev/null +++ b/docs/前端改造要求-Q6-Bot自有存储与用户记忆边界.md @@ -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 存储边界和运行时改造:已完成并部署验收。 +- 前端页面统一改造:待后端接口最终冻结后开始。 +- 本文档:作为后续前端实现和验收依据。