OrgTJWater/next-tjwater-frontend
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(workbench): stabilize investigation presentation rendering

Browse Source 
Keep investigation graphs stable during updates, defer expensive chart rendering, and prevent stale results when switching tasks. Adopt reference annotations and consolidate frontend documentation.
This commit is contained in:
jiang
2026-11-11 19:10:41 +08:00
parent 0ae0a41e61
commit a617aa95e9
35 changed files with 1268 additions and 715 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/agent-answer-ui.md
+13 -21
View File
@@ -2,45 +2,31 @@
统一样式见 [样式设计指南](style-design-guide.md)，聊天布局与报告交互见 [Agent 交互与报告设计](agent-chat-ui-design.md)。本文保留协议、组件参数与业务交互约定。
## 实施进度（2026-10-30 更新）
## 实现范围与后续设计
原生组件版的主要界面与交互状态保存已实现，已完成本地自动化验证；真实授权项目联调和发布尚待完成。下表的“已实现”指当前工作区代码，不代表运行服务已同步更新。相关改动仍未提交、未部署。
下表区分当前源码已具备的能力与独立设计提案。“已实现”不证明运行服务已加载此版本；提交、发布与真实项目验收需核对对应交付记录。整理日期为 2026-11-10。
| 能力 | 状态 | 已有范围与剩余边界 |
| --- | --- | --- |
| Agent 内容组织 | 已实现 | shadcn/ui 原生组件、内容分区、导航、指标与证据展示；沿用现有对话和工具执行通道 |
| 任务语义与结果表达 | 2026-10-28 已接入工作区 | `Result`、回答用途、分区角色、疏密及具体说明标题；Agent 选择表达语义，宿主统一视觉与动作边界，真实模型联调待完成 |
| 任务语义与结果表达 | 已实现 | `Result`、回答用途、分区角色、疏密及具体说明标题；Agent 选择表达语义，宿主统一视觉与动作边界，真实模型联调待完成 |
| 表格与图表 | 已实现 | 搜索、排序、折线/柱状/数据表切换、区间选择和序列显隐；只处理已加载数据 |
| 报告与 Markdown 阅读 | 已实现 | 表格完整内容可横纵滚动；报告与 Mermaid 有界放大、暗色遮罩、图标按钮、焦点恢复及减少动态效果适配 |
| 定位与资料补充 | 已实现 | 保留专用地图定位和补充资料表单；数据组件不提供勾选、分析篮或组件追问 |
| 交互状态持久化（A） | 核心已实现 | 图表、表格、表单与证据状态按会话保存；支持刷新恢复、兼容迁移、失败重试和显式冲突处理 |
| 阅读位置持久化 | 设计待实施 | reader 记录尚未保存到宿主；分析篮已按产品决定移除，旧 basket 设计不再作为实施目标 |
| 提问与回答生命周期 | 2026-10-28 已接入工作区 | 自有 ask_user、独立草稿、答案持久化与固定 ID 续跑；历史 question 权威核对。真实模型完整链路及发布未验收 |
| 提问与回答生命周期 | 已实现 | 自有 ask_user、独立草稿、答案持久化与固定 ID 续跑；历史 question 权威核对。真实模型完整链路及发布未验收 |
| 压力历史探索（B） | 设计提案 | `HistoryExplorer` 和新时间窗分页查询尚未实现，不能将本地筛选当成重新查询 |
| 自由代码运行时（C） | 未接入 | 仍采用受控原生组件；独立 iframe、生成代码运行及其通信协议需要另行架构评审 |
| 外围与 Dev 窗口交互 | 已修复 | 窗口外地图可点击、拖动和滚轮缩放；窗口内部操作不穿透地图 |
对应根目录研究文档的四个阶段：阶段一的标准组件路线已实现；阶段三的原生组件状态管理已提前落地；阶段四已接入部分地图、报告和追问流程；阶段二的自由代码运行时尚未接入。本文后续 A/B/C 是实施包名称，与研究文档的阶段编号不同。
2026-10-30 展示范围调整已通过 lint、typecheck、146 个文件共 838 项单元测试，以及 25 项浏览器回归（含复跑，使用模拟接口）。浏览器覆盖桌面与窄屏、内联与展开表格、图表动效、会话状态恢复、地图定位和补充表单；不代表真实项目联调或部署完成。
2026-10-30 分区、导航与来源精简已通过 lint、typecheck、842 项单元测试和 20 项浏览器回归（含复跑，使用模拟接口）；另覆盖节点追问移除后的详情与地图定位。
以下为 2026-10-26 的历史验证记录，不代表后续工作区变更的验证结果：
| 验证层 | 结果 | 覆盖边界 |
| --- | --- | --- |
| 前端静态检查与单元测试 | lint、typecheck 通过；121 个文件、631 项测试通过 | 当前原生 UI、状态管理和既有前端回归 |
| Agent 检查与聚焦测试 | `bun run check` 通过；33 项测试通过 | 状态存储、权限、版本冲突、重试和会话生命周期 |
| UI 浏览器验收 | 10 项通过 | 当时的交互状态、引用追问、Markdown 阅读，使用模拟接口；引用追问现已移除 |
| 窗口鼠标行为回归 | 4 项通过 | 外围与 Dev 的窗口内外事件、地图拖动与缩放；修复前已复现遮挡 |
| 前端构建 | 通过 | SPA、生产 CSS 校验和 TTS adapter 构建；不等于部署完成 |
历史静态、浏览器和模型验证分开记录，见 [2026 年 10 月验证记录](history/answer-ui-validation-2026-10.md)。当前验证命令见下文，不能将历史测试数量作为当前通过结论。
当前实现入口为 [原生回答组件](../src/features/agent/answer-ui/answer-ui-view.tsx)、[会话状态同步](../src/features/agent/session-state/answer-view-state-scope.ts) 和 [Agent 状态存储](../../next-tjwater-agent/src/sessions/answer-view-state-store.ts)。验证命令见下文“验证”，后续顺序见“后续待办与验收”。
2026-10-27 已补齐 [交互状态设计](agent-interaction-state-design.md)，覆盖阅读位置、分析篮、正式报告私人状态、接口与存储、版本冲突和验收矩阵。其中阅读位置和正式报告状态尚未实施；分析篮于 2026-10-30 移除，旧设计不再适用。正式报告状态需要新增项目 BizDB 状态表，不能沿用聊天核心 A 阶段“无数据库迁移”的交付结论。后续追加的宿主提问实现状态单列如下。
同日补充的宿主提问方案已于 2026-10-28 接入工作区，见上述文档第 11 节：以自有 ask_user 管理等待、草稿、答案与续跑，同时核对历史原生 question 的可用状态。独立完成此项不代表 reader 或正式报告状态已实施；此前历史故障的具体触发条件仍未取得现场响应。
状态保存、宿主提问与后续阅读位置设计统一见 [交互状态](agent-interaction-state-design.md)。分析篮、行选择和组件追问已取消；聊天阅读位置和正式报告私人状态仍属待实施范围，不能沿用聊天控件状态“无需数据库迁移”的结论。
## 接入方式
@@ -88,6 +74,12 @@ SCADA 的压力、水头（m）及流量、管流（m³/h）数值轴使用对
任务打开、切换、刷新、已完成任务载入和历史恢复只更新内容，不弹窗；运行中新收到的 open_chart 由总窗口统一处理，关闭后的实时更新不重新弹出。排列、布局和窗口操作不新增模型输出或 wire 协议字段，也不改变图表校验与证据规则。具体自动弹出与关闭边界以上述管理说明为准。
切换调查任务时，报告内容立即替换，展示数据先与新任务范围对齐，再读取其历史结果；旧任务图表不在新任务范围下重新挂载。
历史请求未完成时显示骨架，失败时显示具体错误；图表接近可视区域后分帧挂载，离开任务会取消尚未执行的绘制。
骨架改善等待反馈，不缩短接口响应时间，也不表示调查已经完成。流程图按源码和渲染配置复用最多 32 份浏览器内 SVG，
复用时重新分配实例标识，配置变化和失败重试会重新绘制；报告版本、证据引用和实际任务状态仍以保存的数据为准。
流程图首次排版显示骨架，后续更新保留旧图直到新排版完成，维持阅读位置与缩放；连续更新时忽略迟到的旧排版结果。
其余组件使用 `answer-motion.tsx` 统一交互过渡，沿用现有实体面板、字体、语义颜色和圆角。首次加载即时显示；鼠标展开、收起使用 180ms 透明度和位移，键盘与减少动态效果模式即时完成。折叠中的内容立即设为 `inert` 并退出无障碍树，动画结束后隐藏；保留原 React 内容实例，反向操作中断旧动画，避免旧退出回调隐藏重新展开的表单。
| 组件 | 交互与内容处理 |
@@ -308,7 +300,7 @@ Vite 统一解析 React/React DOM，Playwright 按端口使用独立的依赖缓
尚未持久化：阅读锚点与相对偏移。当前同实例展开/收起的内存保留，不等于刷新后的宿主恢复。
补齐方案见 [Intelligent UI 交互状态补齐设计](agent-interaction-state-design.md)：保留现有 controls 接口，计划新增独立 reader 记录；旧 basket 部分已停止实施；正式报告按当前读者及报告版本保存到 Server，不使用发布报告的 Agent 会话充当读者身份。
后续补齐范围见 [交互状态](agent-interaction-state-design.md)：保留现有 controls 接口，阅读位置计划独立保存；正式报告按当前读者及报告版本保存到 Server，不使用发布报告的 Agent 会话充当读者身份。
状态记录附带完整 spec 摘要 `schema_digest`、单块 `revision` 与最后请求 ID。`schema_digest` 由服务端从会话里已保存的块计算；客户端摘要只用于检查过期。摘要变化后执行上表的兼容迁移，再写新版本。按数据整体设置 key 的逻辑改为稳定节点身份加显式兼容处理，不能只删除 key 而沿用越界索引。