next-tjwater-frontend/docs/history/agent-chat-ui-implementation-notes.md

# Agent 聊天与报告实现记录

本页归档原设计文档中的阶段记录，仅反映各次验证范围，不作为当前样式或验收结论。现行样式见 [样式设计指南](../style-design-guide.md)，交互与报告规则见 [Agent 交互与报告设计](../agent-chat-ui-design.md)。

2026-10-20 本地验证：前端 lint、类型检查、514 项单测和构建通过；23 项聚焦浏览器用例通过，涵盖聊天、历史、流式稳定、表单、图表、展开阅读、报告版本、320/375px、键盘与强制颜色。最终引用来源调整另通过组件测试，并重新运行 5 项聊天及报告工作区浏览器用例。

Agent 类型检查及 16 项相关测试通过；隔离 OpenCode 工具发现验证通过，未调用模型推理。Server 的报告 schema、发布幂等、证据归属、历史读取和报告 API 共 76 项聚焦测试通过；OpenAPI 检查通过，Agent 类型与副本同步，三端组件参数目录一致。

另有原有 API 测试 `test_approved_task_source_uses_server_delegation` 失败：测试期待 `delegated=True`，当前接口返回 False；使用 HEAD 中的原版测试复现相同结果。该问题未混入本轮 UI 修改。

浏览器截图使用明确标注的演练数据。此次没有重启既有 Agent/Server、部署、调用真实模型生成报告或连接真实数据库验收；正式运行前需要同步三端版本并验证实际报告生成与落库。构建仍有大 chunk 提示。参数重算、附件、导出与版本差异比较属于后续范围。

同日后续细化：合并指标摘要区、收起图表范围筛选、对齐数据点读数，并增加正式报告章节导航。当前结果的状态标签与标题并排；当前最终结论去除重复的“调查结论”标题，历史、阶段性判断和证据不足的说明继续显示。

320px 浏览器实测，聊天展开视图的指标区从 310px 降为 118px；趋势图距阅读区顶部从 596px 降为 396px。测量使用同一演练数据，图表仍保留 220px 高度，文本内容与数值未裁剪。检查并更新聊天内嵌、聊天展开、报告内嵌、报告展开共 4 类视图（checked 4 / changed 4 / left 0）。

本次增量验证：lint、类型检查、515 项单测、18 项聚焦浏览器用例及 `git diff --check` 通过。浏览器覆盖 320/375px 与桌面、范围筛选和重置、章节键盘跳转与吸顶、滚动章节提示、草稿保留、版本引用、原有审批内容和强制颜色。改动限于前端展示与导航，没有新增依赖或更改接口；本次未重跑构建和 Agent/Server 测试。

2026-10-21 Resizable 分栏验证：新增 `react-resizable-panels@4.14.7`，移除手写 Agent 拖拽 Hook。`pnpm lint`、`pnpm typecheck`、`pnpm test`（100 个文件、515 项测试）、`pnpm build` 和 `git diff --check` 通过；构建仍有原有大 chunk 提示。25 项聚焦浏览器用例通过，覆盖 Agent 与地图/报告两级拖拽、键盘方向键及 Home / End、最小/最大宽度、折叠恢复、320/375px 与桌面往返、报告比例记忆、表单草稿及地图 canvas 连续绘制。运行命令：`pnpm exec playwright test tests/browser/agent-panel-resize.e2e.ts tests/browser/agent-answer-ui.e2e.ts tests/browser/agent-report-workspace.e2e.ts tests/browser/workspace-main-frame.e2e.ts tests/browser/workbench-resizable.e2e.ts --workers=1`。

键盘调宽回调可能早于 DOM 宽度更新，Agent 的尺寸记忆使用回调中的新比例计算，避免记录上一帧宽度；回归用例已先复现失败再验证通过。两处分栏回调均已核对，内层直接保存布局比例，不读取旧 DOM 尺寸。浏览器预览采用演练数据，本轮仅改动前端，未提交、部署或进行真实业务验收。

2026-10-21 首次提问与 Motion 增量验证：lint、类型检查、519 项单测（100 个文件）及 `git diff --check` 通过。10 项相关浏览器用例分批通过，覆盖居中提问、400/640px 调宽、首次发送与新建对话、表单实例保留、Motion 逐帧位移、减少动态效果、320/375px 与短屏输入、悬浮入口及历史富内容恢复。并行任务期间发生过整例超时，动画用例随后单独复核通过；截图辅助逻辑已修复通知退出导致的定位漂移。验证使用演练数据，未新增依赖，本轮未重跑构建或后台测试，未提交或部署。

2026-10-21 悬浮入口白色材质验证：lint、类型检查、519 项单测及 2 项聚焦浏览器用例通过，覆盖桌面折叠恢复、键盘展开、减少透明度降级和 375px 窄屏。检查了实际渲染截图；本轮只调整入口材质，未新增依赖。

2026-10-21 悬浮入口精简验证：入口改为 56 × 56px 圆形按钮，移除附加状态文案、状态点、箭头和详情提示卡片。lint、类型检查、519 项单测及 `git diff --check` 通过。桌面 1024/1440px 尺寸、键盘展开、减少透明度和 375px 手机共 2 项浏览器用例分批通过；桌面首次验证在展开后的布局断言超时，未改业务代码单独复测通过。截图采用浏览器演练环境。

2026-10-21 水纹球与交互验证：形象改为本地 CSS 与 Motion 绘制的水纹球，加入指针跟随、按压形变和触点水波；离线保留完整球体与操作反馈。lint、类型检查、519 项单测及 9 项聚焦浏览器用例通过，覆盖状态切换、离线可见与展开、鼠标移出复位、手机触摸及取消、减少动态效果、强制颜色、键盘、桌面尺寸和 320/375px。此前 3 项首次加载等待超时，已将连接状态首次就绪的等待上限调整为 30 秒，交互断言保持原有超时。检查了实际工作台与交互预览截图，使用演练数据，未新增依赖、提交或部署。

同日高光跟随修正：固定球体位置与边缘反光，改为在固定高光层内移动渐变中心，并缩小、柔化亮斑。720px 预览视口内，48px 球体右下角悬停时，高光层相对球面的偏移从横向 5.34px、纵向 5.34px 降为 0；32/40/48px 的左上、右下悬停均保持贴合。悬浮入口、标题栏、手机入口共检查 3 处、更新 3 处、遗留 0 处（checked 3 / changed 3 / left 0）。lint、类型检查、519 项单测、6 项水纹球浏览器用例和 `git diff --check` 通过；触摸取消、按压水波、离线可见与互动、键盘及减少动态效果保持有效。

同日球缘涟漪补充：实际渲染并对照 Obsidian 原资源的就绪、待回复、思考、输出和悬停状态，增加三层错峰向外传播的球缘水波，触碰改为三道渐弱涟漪；移除球内固定同心纹理，保留柔和流光与已修正的局部高光。检查 32/40/48px 及离线预览，三处共享入口同步更新。lint、类型检查、519 项单测、6 项浏览器用例和 `git diff --check` 通过；浏览器逐帧确认波纹半径实际增大，并检查离线与减少动态效果停止循环、鼠标及手机操作。仅变更前端形象与设计说明，未引入远程资源依赖或新增包。

2026-10-21 Motion 曲线细化：三层球缘改为闭合贝塞尔带状轮廓，内部改为两道持续形变的宽幅明暗光带；状态切换保留相位，悬停只扰动靠近指针的球缘，保留局部高光和三道按压水波。增加几何单测验证循环连续、曲线边界、状态差异及局部扰动。lint、类型检查、526 项单测（101 个文件）及 6 项水纹球浏览器用例通过，覆盖实际路径变化、视口外暂停恢复、处理状态、离线可见、鼠标与触摸取消、减少动态效果、强制颜色和键盘展开。原版 / 上一版 / 新版动态对照页已检查五种状态和 32/40/48px；高光层与球面最大偏差小于 0.03px，多个实例的 SVG ID 无重复，375px 预览无横向溢出。对照页为本地预览产物；工作台仅使用本地 Motion 实现，没有新增包或更改业务状态映射。`git diff --check` 通过，本轮未提交或部署。

2026-10-21 Obsidian 原版恢复：根据源码和实际资源核对，改回 Rive WebGL2 原动画，保留原版羽化、反射、水纹和 hover 状态。删除自绘 Motion 几何实现及对应几何单测；Motion 用于外层按压。离线、减少动态效果及加载失败显示从原动画导出的静态帧。三个入口共检查 3 处、更新 3 处、遗留 0 处（checked 3 / changed 3 / left 0）。lint、类型检查、523 项单测（101 个文件）、构建及 7 项聚焦浏览器用例通过，覆盖真实原版画面变化、单次资源下载、移出视口释放、状态切换、鼠标与触摸取消、离线、资源失败、键盘和强制颜色。构建保留已有的大 chunk 提示。本轮未新增包、提交或部署。

原版 / 接入版动态对照已检查五种状态和 32/40/48px，375px 预览无横向溢出；在线保留原版动画，离线切为原版静态帧。独立对照预览的 35 秒浏览器渲染进程 RSS 从约 193.3 MiB 回落至 177.2 MiB，未观察到持续增长；这是单次短时预览观察，不代表长时间运行或真实业务负载验收。`git diff --check` 通过。

2026-10-21 取消球体按压反馈：`AgentPersona` 移除 Motion，取消缩放、回弹、变暗及触摸触发 hover，保留原版鼠标悬停、水纹和状态动画。减少动态效果改用系统媒体查询监听；离线仍显示原版静态帧。lint、类型检查、523 项单测、7 项球体浏览器用例及 `git diff --check` 通过，覆盖桌面点击、手机触摸、离线、键盘和强制颜色。另在组件预览中验证减少动态效果的实时切换，以及按下前后静态图片一致；未新增依赖或重跑构建。

2026-10-21 首次加载衔接与尺寸修正：逐帧复现静态帧到 Rive 的透明度从 0 直接变为 1，球体位置和尺寸保持不变，确认跳动来自画面硬切。改为 180ms CSS 渐变，结束后隐藏占位；新浏览器用例在修改前失败、修改后通过。悬浮画布从 48px 放大至 56px，桌面标题栏从 40px 放大至 48px，手机入口从 32px 放大至 40px，三个入口均复核。lint、类型检查、523 项单测及 8 项聚焦浏览器用例分批通过，检查了 320/375px 实际画面、加载衔接、原版动画、按压无反馈、离线、触摸和键盘。未新增依赖、提交或部署。

## 2026-10-21 Rive 资源内离线水纹

解析原版 775 个运行时对象，JSON 重新编码与原文件逐字节一致。保留原图形和在线动画，新增三段离线循环，并修正 asleep / wake 的透明度与缩放关键帧；同源资源为 `public/agent/obsidian-water-v1.riv`。实现与再生成说明见 [Agent 动画资源](../agent-persona-resource.md)。

验证通过：生成一致性检查、lint、类型检查、547 项单测、构建、`git diff --check`。10 项相关浏览器用例分批通过，包含真实 WebGL2 在线状态采样逐像素对照、原版离线消失与修改版离线持续运动、初始离线、反复恢复、工作台单实例、加载衔接、按压无反馈、资源失败、减少动态效果、键盘及 320/375px。首次运行有 1 项动画就绪等待超时；未修改运行代码，带 trace 复测通过，首次超时根因未确认。

独立预览检查 5 种状态及 40/48/56px，离线仍为实时 canvas；30 秒渲染进程 RSS 约 209 MiB 至 176 MiB，未见持续增长。这是本地短时观察，不替代长时间运行验证。构建保留原有大 chunk 提示，本轮未新增依赖、提交或部署。

## 2026-10-21 静水待机与客户端资源缓存

在资源内为六个柔光/反射节点增加离线强度循环，保留原版整体轮廓与在线画面，在线/离线混合时长调整为 600ms。可编辑参数独立保存为 `design/agent/obsidian-offline.json`；生成脚本增加原始 `.riv` 还原命令，实测输出 SHA-256 与原版一致。浏览器对照覆盖在线采样逐像素一致、离线持续变化、正常恢复与快速反复切换后的原版光照恢复。

`.riv` 增加页面内存与 Cache Storage 两级缓存，使用生成脚本同步输出的内容 SHA-256 作为版本。下载和缓存读取验证内容，损坏缓存重新获取，写入新版本后仅清理该动画的旧条目；缓存不可用、权限或配额失败不阻止网络资源播放。真实工作台刷新后阻断动画文件的网络路径，仍能加载并持续播放，下载次数保持为一次。缓存仅覆盖动画资源，不代表应用和 Rive WASM 的完整离线支持。

最终验证通过：lint、类型检查、554 项单测、11 项聚焦浏览器用例、构建、资源与缓存清单再生成一致性、生产资源与打包版本核对、文档链接及 `git diff --check`。实际预览检查 5 种状态及 40/48/56px，浏览器用例覆盖桌面和 320/375px。构建仍有已有大 chunk 提示；未新增依赖、提交或部署。

## 2026-10-21 冰水蓝与光圈辨识度

初版 A「水务蓝」在实际动画中出现灰蓝混色、底色过厚的观感问题。将三个新配色放入原生 Rive 动画，在白底、五种状态与 40/48/56px 下对比后，采用用户选定的 02「冰水蓝」：水体 `#299FDF`、暗部 `#1482BC`、白色高光，底色不透明度为 12%/32%。根据工作台截图反馈，外围水纹进一步从 `#B0E3FF` 加深为 `#4C9ECC`，提升浅色地图上的轮廓辨识度；光圈粗细、渐变 alpha、羽化与运动曲线保持原定义。

离线仍关闭三层外围光圈，保留内部缓慢水纹。在线、离线兜底 PNG 从实际资源重新渲染，内容版本与客户端缓存清单同步更新；仅加深光圈前后，离线 PNG 逐字节一致。悬浮入口、标题栏和手机入口共享资源，检查 3 处、更新 3 处、遗留 0 处（checked 3 / changed 3 / left 0）。

验证通过：lint、类型检查、12 项相关单测及 12 项聚焦浏览器用例分批通过。初次资源对照的深蓝显色阈值不适用于新选定的浅色方案，已调整白底合成后的蓝色检查，并保留原版几何及在线动画的逐像素对照。光圈加深后，重新通过 7 项聚焦浏览器用例，覆盖原版运动、离线无光圈及悬停、恢复在线、缓存刷新、工作台入口和 320/375px。最终构建、资源再生成一致性、生产副本与缓存版本、文档链接及 `git diff --check` 通过；构建保留已有大 chunk 提示。此次未新增依赖、提交或部署。

## 2026-10-21 64px 入口、主体遮蔽与标题区重排

默认 persona、悬浮入口和面板标题区形象统一为 64px，手机地图入口保留 40px。悬浮入口通过同一层 12px 内边距定位，替换原来左侧 12px、导航下方 20px 的独立偏移；1440px 和 1024px 视口实测入口为 64 × 64px，距左侧和顶部导航下沿均为 12px。三个组件调用位置均检查，修改两处呈现尺寸，遗留零处（checked 3 / changed 2 / left 0）。

根据地图道路穿透球体的截图，为球面底色增加独立 `bodyColor`，设为浅冰蓝 `#DCEFFA`，待机/活动不透明度提高至 94%/98%。反射层继续使用选定的冰水蓝配色，外围光圈颜色及离线关闭规则保持。真实 Rive 前后对比检查了带线条背景，中心区域的运行时 alpha 采样不低于 90%；静态帧与缓存版本重新生成，原版几何与在线运动对照仍通过。

标题区身份行重排为 64px persona、上下排列的名称与连接状态，以及右侧三个 40px 操作按钮。上下文行继续提供会话标题与项目切换；两个区域共用白色背景，仅在底部保留分隔线。400px、640px 桌面面板和 320px 手机截图已检查，名称与操作按钮无重叠。历史展开、重命名取消、键盘焦点恢复、新建、折叠和手机关闭入口保留。

最终验证通过：lint、类型检查、556 项单测（102 个文件）、构建和 17 项相关浏览器用例分批通过。浏览器覆盖资源及主体遮蔽、离线、缓存、加载衔接、布局与标题区、320/375px、短屏输入，以及首次发送与新建会话的居中恢复。生产资源、PNG 副本、缓存版本清单、文档链接和 `git diff --check` 通过。构建保留已有大 chunk 提示；未新增依赖、提交或部署。

## 2026-10-22 Persona 设计归档与悬停坐标修复

当前视觉规格保存为 [Persona 设计](../agent-persona-design.md)，记录冰水蓝材质、主体遮蔽、64px 默认尺寸、12px 等距定位、标题区、状态动画、交互、降级与缓存边界，并从 README、交互设计和资源说明关联。

悬停中央大片变白的原因是共享 `Persona` 禁用了 Rive 指针监听，仅手动设置 `hover`，导致原生反射的指针目标始终位于中心。恢复原生监听并通过 Pointer Events 转交主指针的进入、移动、离开与取消；Rive 完成坐标转换和原生约束更新。触摸、按压和触摸生成的鼠标事件不进入动画通路。撤销此前的 80% 光圈缩放，应用 `.riv` 与此次调整前逐字节一致。

三个调用位置均复核（checked 3 / changed 3 via shared component / left 0）：桌面悬浮入口、面板标题区、手机地图入口。新增工作台回归在修复前收到空坐标并失败，修复后通过，覆盖悬浮入口和标题区的左右移动。资源级对照验证高光重心跟随左右指针移动，且画面与相同材质的原版逐像素一致；鼠标移出后完全恢复。实际组件的 64px 与 160px 放大画面已检查，手机 320/375px、离线、键盘、减少动态效果、失败降级和无按压反馈由相关浏览器用例覆盖。

lint、构建内类型检查、558 项单测（103 个文件）及构建通过；14 项相关浏览器用例分批通过。首次综合运行中，加载衔接的 5 秒前置等待和多次挂载缓存检查的整例 30 秒时限超时，未改代码或断言，单独复测两项均通过。资源还原与再生成校验、本文涉及的文档链接和 `git diff --check` 通过。构建仍有已有大 chunk 提示；未新增依赖、提交或部署。