# Flowglass UX 实施记录

> 后续真实实例验收已发现并修复选择器、三列布局、轮次映射和冷会话读取问题，且更新了本机安装。以 [2026-09-20 实际页面记录](flowglass-live-fixes-2026-09-20.md) 为准；下文保留前一轮离线实施记录。

更新日期：2026-09-20。对应 [实施计划](flowglass-ux-redesign-plan.md)，构建基线版本仍为 `0.6.1`，本轮没有宣布新版本、安装或发布。下面区分源码能力、离线验证和真实宿主验收。

## 已实现的用户能力

以下为真实源码配合脱敏 fixture 的浏览器截图，不是 3080 已安装实例：

![并发任务概览（1440px，深色）](screenshots/flowglass-ux-overview-1440.png)

[窄栏当前会话](screenshots/flowglass-ux-session-360.png) · [窄栏详情](screenshots/flowglass-ux-inspector-360.png)

| 能力 | 当前行为 | 边界 |
| --- | --- | --- |
| 导航 | 当前会话 / 并发任务；概览 / 对比 / 关系图；子代理面包屑可返回祖先 | 保存的 `compact/detail/map`、历史和跟随偏好继续可读 |
| 阅读层级 | 系统上下文默认折叠；消息正文优先；技术信息按需展开；来源会话独立于分支数量 | 折叠不删除事件，不改变原有框选上下文 |
| 自适应详情 | 窄栏替换、常规宽度覆盖、宽面板并排；返回 / Escape；键盘焦点恢复 | 宿主全屏由 Harness 控制；真实原生 tab 全屏联动仍待认证页面验收 |
| 查找与筛选 | 消息、工具输入输出及错误文本查找；类型 / 运行 / 失败筛选；需要关注入口 | 明确区分当前已加载节点与全会话已记录日志；结果最多呈现 200 个节点并提示缩小条件 |
| 标记 | 本浏览器保存 Session、类型、seq、备注；定位时补足历史窗口并打开详情 | 按 bundle 与工作区隔离；备注不写入 Session；不存在、归档或身份不匹配的节点解释失效 |
| 分支概览 | 来源只显示一次；每个分支显示状态、当前工具、最近结论与异常 | 仅使用已有数据；不自动推断答案质量或调用模型 |
| 对比 | 完整输入相同时声明已对齐，共享输入只显示一次；支持仅看差异 | 同一个 turn 数字不是同源证明；无法证明时显示“未对齐”，缺少结果与运行中状态保留可见 |
| 结论复用 | 选择 2–4 条已完成助手结论，预览来源 / 轮次 / 节点，再追加到目标草稿 | Host 再验证节点已完成；取消不改草稿；此入口不自动发送；摘要和上下文存在体积上限 |
| 关系图 | 适应画布、定位选中、恢复布局、缩放、平移与键盘操作 | 保留历史轮次、沿用和派生关系；关系图允许平移 |
| 只读回放 | 按 durable event 的 seq 前缀重建，前进 / 后退、回到最新 | 不注入 live overlay，不读取子代理未来日志；未提供按墙钟时间自动播放，不重执行任何任务 |
| 本地导出 | 当前视口可见节点的 JSON 诊断摘要或 SVG 节点快照，下载前预览 | 默认不包含正文；显式勾选才附可见摘要；不是原始日志导出，也不是带图片 / 全部连线的像素截图 |
| 稳定编辑 | Flow 头部 / Composer / Inspector 使用独立 React 区域；草稿恢复与详情阅读保持 | 普通 Toolbox 工具继续 `{html,state}`；未把整张画布迁为 React 图编辑器 |
| 发送恢复 | 逐分支记录 create/configure/send 与成功 / 失败 / 未知状态；已创建 Session 复用；成功分支不重复发送 | 未知发送先核对可用事件，无法证实时保留未知；不承诺服务端未提供的 exactly-once |
| 工具规则 | 设置先展示摘要，再展开编辑；保留规则顺序、启停与原有存储 | 官方插件详情仍是设置入口 |

## 分阶段完成情况

“源码完成”表示功能已实现并有对应离线回归，不表示所有真实部署环境已经验收。

| 阶段 | 本轮完成 | 尚需环境证据 / 后续条件 |
| --- | --- | --- |
| 0 基线 | 记录源码、测试内核、浏览器；建立 12 类脱敏 fixture、基线截图和 Host/DOM/载荷记录；核对 Toolbox 三形态 | `127.0.0.1:3080` 返回 401，实际运行 build、安装来源和已认证页面未知 |
| 1 信息架构 | 导航、工具栏主次、上下文折叠、状态、技术信息与稳定选择器 | 真实用户任务验收仍需宿主页 |
| 2 布局与详情 | 容器宽度布局、主题变量、键盘、详情、空态 / 失败 / 不可用状态、规则折叠 | 离线覆盖 360–1920px；真实官方 Markdown 文件提及 / 图片尚未验收 |
| 3 稳定交互 | 拆出 `flow-stable.js` 与 `flow-launch.js`；规范 Client 组装；草稿 / 选择保持；分支恢复状态机 | 操作系统输入法、真实服务器持续生成、原生全屏和全部跨会话时序还需实测 |
| 4 对比与关系图 | 最新结论概览、输入证据对齐、共享输入、差异过滤、图视口操作、来源草稿预览 | 不将确定性比较当作语义评判；历史容量仍按原有上限管理 |
| 5 工程收敛 | Client 的稳定交互与发送状态按职责拆分；静态 / 动态统一 source assembly；增加浏览器行为回归；对未变化 durable 投影增加有界缓存 | 局部重复投影实测有收益；新结构仍增加部分 DOM / 载荷，不宣称端到端整体加速；全画布增量渲染与虚拟化待真实瓶颈支持 |
| 6 发布收口 | 更新实现说明、基线、README 与未发布变更记录；构建 / smoke / 包检查由本轮验证执行 | 真实多版本、Toolbox 单独 / 同页启用及宿主全屏验收未完成；未提交、安装或发布 |

组合 A（查找 / 关注）、B（标记 / 全会话搜索）、C（结论预览 / 草稿）和 D 的最小实现（事件回放 / JSON 与 SVG 本地导出）已纳入源码。本轮没有扩展到跨设备标记、在线协作、模型裁判、全量日志导出或时间播放器。

## Toolbox 三形态能力矩阵

本节落实计划第 11.6 节。新 Host 功能复用既有 `sessionQuery` / `makeSessionLogReader`；没有增加 Flowglass 专用 Host 注入。缺少日志服务或读取失败会明确提示，不能把失败的读取当作空会话。

| 能力 / 契约 | 独立静态 Flowglass | 完整静态 Toolbox | 源码动态 Toolbox |
| --- | --- | --- | --- |
| Flow 查看、钻取、详情、分支与历史 | 共享 Host 实现 | 共享 Host 实现 | 共享 Host 实现 |
| 搜索、筛选、标记、对比、回放、导出 | 共享增强 Client | 内嵌 flow 同样提供 | Client 源码 RPC / inline 组装包含相同 helpers |
| 官方 Markdown | 静态模板声明相应依赖 | 按可用注入启用；缺失时保留原文 | 按可用能力降级，不要求额外动态批准 |
| 普通 calc / HTTP / flowedit 等 | 不含这些工具的独立产品 | 原有通用 HTML 面板与动作字段协议 | 原有 registry / loader / 批准 / timer 生命周期 |
| 样式和存储隔离 | 编译 scope + `RT` 命名空间 | Flow 增强局限于目标根 | Flow 增强局限于目标根；不覆盖 flowedit 旧基础类 |
| 已有离线证据 | 静态 bundle、真实 React / DOM、Flow smoke | 显式完整 catalog 构建、calc / HTTP / flowedit、包清单检查 | 规范 source assembly、真实 rc.2 codec / runner、启停清理 |
| 真实用户实例验收 | 待认证页面 | 待单独启用及与 Flowglass 同页验收 | 待目标宿主上的实际加载验收 |

`build/source-assembly.mjs` 统一顺序：`flow-launch.js` → `flow-stable.js` → `client.js`。这些 helpers 为普通脚本，继续支持现有源码拼接方式。普通工具不经过 Flow 专属稳定区域。

## 验证入口与记录

环境、每项测试内容、报告路径、前后性能数据及限制见 [基线与兼容验证](flowglass-ux-baseline.md)。浏览器 fixture 使用虚构日志，没有发送真实消息或调用外部 HTTP。

```powershell
node smoke/sim-flow.cjs
node smoke/sim-flow-launch.cjs
node smoke/sim-source-assembly.cjs
node smoke/sim-rc2-composition.cjs
node scripts/test-flowglass-ux.mjs
node scripts/test-flowglass-stable.mjs
node scripts/test-flowglass-map.mjs
node scripts/test-flowglass-drawer.mjs
node scripts/test-toolbox-compat.mjs
node scripts/test-toolbox-style-compat.mjs
node smoke.mjs
```

Host 回归新增搜索范围、节点类型校验、历史定位、无未来数据的回放、完整输入对齐、失效结论拒绝和恢复轮次定位。真实 rc.2 RPC 还发现并修复了一个 wire 问题：临时非枚举字段不能直接放进返回 `state`；所有正常与错误返回现统一清理。

现有离线布局矩阵为 336 组；完整 smoke 为 26/26 套件，具体计数与浏览器分项见基线记录。Host P95 来自内存日志和暖缓存的 25 次采样，不能代表 RPC、交互响应或 live revision 到 DOM 的延迟。新增控制会增加载荷，保留 60 节点分页不等于生产性能目标已达标。

## 持久事件投影缓存实验

在功能实现后对同一份 1200 事件 fixture 做 20 次预热和 120 次采样，未缓存版 Host 渲染 P50 / P95 为 6.49 / 18.39ms，加入精确源校验的最终缓存版为 3.53 / 5.40ms。实验运行时有并行任务，尤其 P95 受机器负载影响；这是局部暖缓存验证，不是生产延迟承诺，也不替代基线报告中的独立 25 样本矩阵。原始结果为 `.scratch/host-cache-before.json` 与 `.scratch/host-cache-after.json`。

缓存只用于持久事件：匹配 Session、实际返回事件数组身份、长度、计数、末尾 seq、回放位置和完整 JSON 内容；reader 标记变化时重建。即使同一数组原地修改且计数不变，也不会复用旧投影。缓存最多 16 个 Session，单项不超过 200 万字符、总源副本不超过 800 万字符，超过阈值直接重新折叠。live overlay、原始 live-chunk、读取失败或无法 JSON 化的日志不缓存。渲染器拿到顶层节点副本，不能把本次显示状态写回缓存。重试倒计时仍在每次渲染计算。

测试覆盖追加事件、同计数修改 / 替换、reader changed、回放变化、live 绕过、展示规则更新、调用者修改隔离和 16 scope 驱逐。该缓存不扩大底层日志适配器的数据可见范围，也没有改写 Session 格式。

## 发布前仍需完成

最终产品目录已由构建脚本回填并验证一致：`flowglass`（基线版本 `0.6.1`，fingerprint `d3c811d38a3e5c29`）和完整 19 功能 `dynamic-toolbox`（基线版本 `0.5.1`，fingerprint `1055c753e34c406f`）。动态生成物无漂移，两个产品的 `verify-bundle --pack` 均通过。最终源码再次通过 26 套 smoke（Flow 208 项、发送恢复 10 项）和 336 组布局；报告位于 `.scratch/ux-final/report.json`。未安装或发布。

- 在有权限的已认证 Harness 页面确认实际 build 和插件来源，检查原生侧栏 / 后备承载、全屏切换、官方 Markdown、运行中错误与长会话。
- 检查独立 Flowglass、完整 Toolbox 及两者同时启用；覆盖承诺的宿主版本，不用 rc.2 fixture 代替 alpha.2 实际页面。
- 补实际 RPC / 刷新提交 / 交互 P95 / 历史滚动锚点和持续运行生命周期数据；性能目标未达前定位真实瓶颈。
- 统一确定发布版本，保留可回退提交点，然后按独立发布流程安装 / 发布。当前 `0.6.1` 构建数字用于复现，不是一次新版本公告。