From 8f4aa0d6b577a425fb87ca528cbb57bbcbfc9d9a Mon Sep 17 00:00:00 2001
From: "xiaohan.yuan" <hhhhyuan@outlook.com>
Date: Wed, 21 Oct 2026 14:01:57 +0800
Subject: [PATCH] docs(B04): trace Base64 flash when expanding conversation
 details

---
 docs/协作/B04-需求.md | 51 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 docs/协作/B04-需求.md

diff --git a/docs/协作/B04-需求.md b/docs/协作/B04-需求.md
new file mode 100644
index 0000000..ab426cc
--- /dev/null
+++ b/docs/协作/B04-需求.md
@@ -0,0 +1,51 @@
+# B04：展开历史详情时图片地址闪现
+
+日期：2026-10-21。状态：待开发。任务：YC-008，优先级 P1。
+
+## 用户现象与定位
+
+用户反馈 `hello`、`使用浏览器打开baidu.com，输入框中输入t…` 的详情似乎打不开，进一步明确为：展开时有大片文字一闪而过。
+
+调查代码：`0fbc1616e5b6f262e75df5c7411562d3a5031096`。两条会话的保存数据可解析，正文可加载；隔离 Electron 使用当前 dev renderer，展开过程中没有捕获 renderer 异常。该结果是定向诊断，不是独立安装构建验收。
+
+已确认根因在 `src/renderer/src/workbuddy/images/MarkdownImage.tsx`：
+
+1. 第 32 行 `resolvedUrl` 首次渲染为 undefined。
+2. 安全图片 URL 也要等第 35 行的 effect 才设置 resolvedUrl。
+3. 第 62–69 行在此期间进入 fallback，空 alt 时显示 `src`。
+4. 对浏览器截图，src 是完整的 data URI/Base64，于是首帧将其显示为大量文本，随后才换成图片。
+5. `CompletedFold.tsx:192` 的展开分支会切换详情树，重新挂载图片，使该现象在展开时再次触发；不能仅检查首次打开会话。
+
+## 已采集的帧证据
+
+百度会话一次实际展开，requestAnimationFrame 采样：
+
+| 时间 | 外层详情高度 | 图片 Markdown 块高度 | 块内文本字符数 | 图片节点 |
+| --- | ---: | ---: | ---: | --- |
+| 点击前 | 0px | 不适用 | 不适用 | 原树图片已就绪 |
+| 点击后约 28ms | 5704px | 5468px | 18076 | 重挂载处尚无图片节点 |
+| 点击后约 43ms | 636px | 400px | 1 | 图片就绪 |
+
+另一轮采样同样出现 5704px → 636px。文字长度与约 18075 字符的截图 data URI 对应；未将真实会话内容、图片、用户配置或完整 URL 写入交接文件。
+
+本机原始诊断产物保留在 dev 工作树 `.tmp/session-detail-review/`，其中 `native-SZ8eKi/report.json` 为上述帧数据，`native-vsZP6s/report.json` 为另一轮采样。表格和代码定位为可移交的脱敏证据；本机临时路径不是开发端唯一复现依据。
+
+## 开发要求
+
+- 安全且不需要宿主解析的图片地址，在第一次渲染即可使用；避免先进入地址文本占位再在 effect 中切换。
+- 异步解析中的图片使用稳定、简短的占位状态。空 alt 的 data/blob 等地址不得将完整 URI 显示为文字。
+- 失败态也不得显示完整 Base64。可以使用 alt 或简短的图片加载失败提示。
+- src 改变时不能继续展示上一个 src 的图片；保留异步请求取消、过期结果隔离和已有 URL 安全校验。
+- 详情展开导致的重挂载必须覆盖回归；是否进一步稳定详情 DOM 由开发端评估，但不能以更换折叠动画掩盖图片首帧问题。
+- 不修改、清理或迁移用户历史消息来绕过问题。
+
+## 验收标准
+
+1. 使用合成的长 Base64 图片、空 alt，冷挂载首帧到稳定态均不显示 URI 文本。
+2. 在已完成回复中放置图片，连续展开/收起、切换会话后再展开均无大片文字闪现。
+3. 采集展开前后连续帧，图片区域不因完整地址占位瞬间增高数千像素；不能只提交动画结束截图。
+4. 图片加载失败、宿主解析失败、无效地址均显示简短且稳定的失败态。
+5. 快速切换 src、展开/收起时无旧图串入、过期请求覆盖或 renderer 异常。
+6. 图片预览、下载、URL 安全策略和正常 Markdown 图片功能保持可用。
+
+验收端本轮只读产品代码，未修改产品源码和正式用户数据，未重启用户窗口。本需求按用户授权提交至 Gitea 协作主线；开发端按 YC-008 实现后提交交付记录，由验收端复测连续帧。