docs: 新增说人话与图示优先两条规则,登记跨仓库笔记
This commit is contained in:
+70
@@ -0,0 +1,70 @@
|
||||
# Agent Note: 下线内容暴露记录,复习参考资料只取知识碎片
|
||||
|
||||
Status: implemented
|
||||
|
||||
## Problem
|
||||
|
||||
回忆侧曾有三套记录同时存在:回忆请求(`requests`)、回忆记录(`RecallRecord`)、以及「内容暴露记录」——用户看到过哪条提示、哪段原文,都通过 `POST /review/recalls/{recallNum}/exposures` 写回文档(`detail.exposures`),再作为 `exposures` 传给 AI。
|
||||
|
||||
这条链路实际没有消费方:不做评分、不做统计、页面也不读它。它带来的成本却很实在——前端要维护离线重放队列与冲突判定,后端要在隐私清理时多判一次「是否已显示」,AI 请求体多一个字段并多一套校验。同时它把「看过」这件事固化成事实,与「不按提示次数扣分、不推断记忆来源」的设计意图天然拉扯。
|
||||
|
||||
同一次排查还发现资料的组成过宽:复习参考资料同时装入知识碎片、同源学习报告与任务范围内的应用场景。界面把每条资料的 80 字预览常驻,预览已含结论;学习报告摘要更接近标准答案。三者都在用户主动索取之前把内容铺开。
|
||||
|
||||
## Decision
|
||||
|
||||
### 一、删除内容暴露记录(三仓库同批)
|
||||
|
||||
- 删除端点 `POST /review/recalls/{recallNum}/exposures`、DTO `ExposureRequest` / `Exposure` / `AiExposure`、`RecallDetail.exposures`、AI 请求体的 `exposures`。
|
||||
- 删除写入点:`revealHint` / `applyHints` / `exposeCheck` / `openSource`;前端不再有 `useRecallDraft` 的 `pendingExposures` 队列(离线重放、冲突判定、`beforeunload` 条件随之简化)。
|
||||
- 删除读取点:隐私清理 `sourceDeleted` 的 `exposed` 分支、`ReviewRecallStore` 的脱敏映射、`RecallAiService` 的 `AiExposure` 组装、`lpt-ai` 的字段校验与 prompt 规则。
|
||||
- 迁移 `V20261118_2__strip_recall_exposures`:按 id 流式清理 `document_json.detail.exposures`,其它字段原样保留;解析失败或结构不可识别的文档原样跳过并计数(日志只带 id),不阻断升级、不新增删除路径。幂等。
|
||||
- 读兼容依赖 `RecallJson.readStored` 的 `FAIL_ON_UNKNOWN_PROPERTIES=false`:历史文档里的 `exposures`、`REPORT`、`APPLICATION` 来源都不再导致反序列化失败,首次写入时自然落掉旧字段。
|
||||
- 保留:提示默认模糊、点「显示内容」在本地展开(`revealed` 内存集合);回忆查漏结果直接展开。行为不变,只是不再回写。
|
||||
|
||||
### 二、复习参考资料 = 本次复习范围选中的知识碎片
|
||||
|
||||
- `RecallReferenceLoader.snapshot` 只产 `FRAGMENT` 来源;学习报告(`REPORT`)与应用场景(`APPLICATION`)不再进入参考资料,limitations 只留「资料可能有遗漏或相互冲突,不作为标准答案。」
|
||||
- 概念文档同口径:`review-reference.md` 的来源表只剩知识碎片,并明确排除学习报告、保存的思维导图与应用场景;`recall-hint.md` 删掉「内容暴露记录」整节,「尽量避开已经表达或提示的内容」收窄为「已经表达的内容」。
|
||||
- 从来源直接开回忆(`entry`)仍支持 `FRAGMENT` / `REPORT` 入口,这与参考资料组成是两件事,不改。
|
||||
|
||||
### 三、界面:本次资料 → 相关碎片
|
||||
|
||||
- 标题「相关碎片(N 条)」,旁挂一个信息图标,说明这些碎片按本次所选复习范围取出(碎片实际用户标签的并集或交集),不含学习报告;后端给的限制说明并进同一个图标,不再并排两个问号。
|
||||
- 只渲染 `role === 'PRIMARY'`(知识碎片);学习报告条目不显示。
|
||||
- 条目默认收起,只给标题与角色;点「展开」才显示原文开头 80 字,「查看全文」读全文。原文弹窗标题改为「原文」。预览不再常驻。
|
||||
|
||||
### 四、布局:导图铺满整屏 + 全部内容浮层
|
||||
|
||||
评审第一版是「导图 | 辅助栏」两栏,导图仍只占半屏;第二版改成导图铺满工作区、辅助区浮在右上,但页头、范围行、计时条仍按文档流占据顶部一整块(截图红框)。最终版把整页变成画布:
|
||||
|
||||
- `.recall-workspace.workspace-canvas` 用 `position: fixed; inset: 0` 铺满视口,导图卡片 `position: absolute; inset: 0`,页面本身不产生滚动条。
|
||||
- 页头(`MyHead`)在 App.vue 里按 `route.meta.recallWorkspace && route.params.recallNum` 切到 `canvas-shell`:`position: fixed` + 半透明底 + 毛玻璃 + 阴影,`pointer-events: none` 让空白处透传点击,只有卡片本身可交互。标签入口页(`/review/by-tag`)没有 `recallNum`,仍是普通文档流。
|
||||
- 左下 `.hud`:范围名 + 状态 chip + 同步状态 + 计时三组 + 操作(更多 / 切换范围 / 完成回忆);可收成一行摘要(状态 + 倒计时 + 有效时间 + 展开)。提醒、离线提示、草稿恢复面板同在这个左下栈里。
|
||||
- 右上 `.help-drawer`:提示与查漏(请求 → 结果 → 相关碎片),可收成一条标题条;抽屉内部一条滚动轴,不引出页面滚动。2026-11-19 起抽屉只留最近一次结果,另加「放大」三栏视图,见 [自由回忆辅助区放大成三栏阅读](../../../../lpt-fe/.agents/notes/implemented/feature/2026-11-19-recall-help-expanded-reading.md)。
|
||||
- 导图自带的左上工具条、空图提示、节点配色面板统一让开页头:`top: calc(var(--shell-header-height) + …)`。
|
||||
- 窄屏:辅助区改成 `position: fixed` 的贴底抽屉(默认收起),状态条同样可收起;导图仍然铺满。
|
||||
- 窄屏页头压成一行(约 48px):返回、`AI 用量统计`、`退出登录` 在画布页窄屏换成图标(`MyHead` 按 `route.meta.recallWorkspace` 挂 `compact-head`,桌面仍保留文字)。原来 ≤768px 的「竖排 + 按钮满宽」在画布页会把整块导航堆三行。
|
||||
- 计时问号并进「有效时间」的值行(`timing-value-row`),不再作为 `recall-metrics` 的独立子项吃 `border-left`,避免看起来像空白第三列。
|
||||
- 浮层卡片在窄屏会被内容撑宽:`.hud-stack` / `.hud` 都改用 `grid-template-columns: minmax(0, 1fr)` 并给子项 `min-width: 0`;`.hud .workspace-header` 在 ≤768px 允许换行(范围名独占一行,状态与收起同行)。
|
||||
- 节点配色入口补上触屏路径:mind-elixir 只监听 `contextmenu`(右键/安卓长按),iOS 长按不触发,只读草稿也根本没有菜单。现在选中节点后会在节点上方浮出「配色」小按钮(`MindMapViewer` 内 `.palette-chip`),点它打开同一个面板;面板改成贴着选中节点出现(原来是固定右上,正好被浮动的提示抽屉压住),窄屏(≤768px)进一步改成贴底横条,避免和 HUD、提示文案互相挤压。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **保留「内容暴露记录」,只在界面弱化展示**:能力还在,未来想做「提示依赖度」分析时不用重做契约。但用户判断这个设计本身无用,弱化后的数据没人读,却要继续维护三仓库字段、隐私分支、离线队列与 AI prompt 规则,维护成本不降反升,因此整条删除。
|
||||
- **参考资料同时保留学习报告与应用场景**:上下文更全,查漏时能引用报告结论。但它们不是「应回忆的知识」,混进引用会让 AI 把总结当标准答案,也让「本次资料」的来源说不清;用户明确要求只取知识碎片。
|
||||
- **后端照旧返回、前端只过滤不显示报告**:改动最小,不用动 AI 与迁移。但报告仍会进 `units` 与 AI prompt,支付 token 且扩大隐私面,属于「界面上看不见、系统里还在」,否决。
|
||||
- **保留 `POST /exposures` 端点一段时间做兼容**:可以避免三仓库同批发布。但暴露记录已无消费方,留着就会有人接,最终还是要删;三仓库同一分支一起发(`dev` 配 `dev`、`master` 配 `master`)已经能覆盖升级窗口,因此不留兼容层。
|
||||
- **迁移脚本遇到坏 `documentJson` 直接删整条回忆**:数据一致但会误删用户内容。改为跳过并计数、只记 id,保留「唯一删除路径仍是 `ReviewRecallStore.deleteUnreadable`」的边界。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 三个仓库必须同批发布:BE 停发字段、AI 停收、FE 停调;单独上线会出现 400/404。旧客户端访问旧端点会 404。
|
||||
- AI 不再知道「已经给过哪些提示」,用户可能收到重复线索。这是删除暴露记录的已知代价,评审时接受。
|
||||
- 旧草稿的 `documentJson` 仍可能带 `detail.exposures`:读取靠 `RecallJson.readStored` 的 `FAIL_ON_UNKNOWN_PROPERTIES=false` 兼容,写入前由迁移 `V20261118_2` 清掉;迁移坏 JSON 跳过并计数、幂等、不阻断升级。
|
||||
- 「相关碎片」只列知识碎片,条数等于实际行数(`RecallReferenceLoader.knowledgeSources()`)。
|
||||
- 布局改成整页画布后,页面自身不再滚动,滚动只发生在辅助区抽屉内部;窄屏页头压成一行图标,桌面仍保留文字按钮。
|
||||
- 少了一条链路(提交暴露、离线补发、隐私分支、AI prompt 规则)与一个字段,AI 输入变小、成本下降;代价是将来要做「提示依赖度」类分析需要重新设计。
|
||||
|
||||
## 未决
|
||||
|
||||
- 保存的思维导图是否仍保留「参考关系」:代码侧参考资料从未包含保存图,但 `mind-map.md`、`principles.md` 等 8 处文档仍写「保存图默认在对应范围启用参考、参与以后核对」。本轮未改,需单独定口径。
|
||||
Reference in New Issue
Block a user