deepseek-harness/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md

Agent Note: 轨迹检查记录表

Status: implemented

English | 中文

问题

轨迹视图需要在同一视口内清晰呈现正文、机器载荷、token 用量、计时数据和嵌套工具活动。此前堆叠式的轮次与步骤卡片虽然保留了层级，却在重复界面框架上耗费了太多垂直空间；完全扁平化的表格又会抹去因果结构，而这种结构正是轨迹视图的价值所在。角色配色还可能借用成功与警告语义，使视觉装饰与运行时状态无法区分。

决策

使用现有 DeepSeek 设计系统，渲染保留轮次结构的紧凑事件记录表，并提供局部记录检查器。

• 记录表在以 rewind 划分的分支内按会话事件顺序展示。轮次边界由稍粗的分割线、原始轮次 id 和连续的左侧竖线表示；请求边界以融入该结构的小圆点表示，普通请求与压缩（compaction）请求在整个时间序列中共用一套编号。
• 事件类型与内容构成两个稳定列。角色标签朝内容侧对齐，嵌套子工具略微缩进，内容预览使用 CSS 截断以适应可用宽度。token 用量和耗时留在检查器中。
• 产品正文使用现有无衬线字体栈。轮次 id、token 数、耗时、工具调用、原始载荷和其他机器数据使用现有代码字体栈。
• 现有主题 token 同时负责亮色和暗色渲染。中性边框与表面构成整体结构；区分度较低的角色色帮助扫读而不表达成功或失败语义，业务蓝色则标识选择状态、链接和焦点。
• 客户端运行时提供独立于 Session 和 SessionManager 的只读历史数据源。每个已激活的数据源自行拥有原始条目、分页、实时缺口修复和重连重建；普通会话快照仍然只是 Chat 所需的折叠投影。Trajectory 在挂载期间打开该数据源的尾部，当用户到达已加载范围顶部时请求一页更早的历史，再按需派生事件顺序、上下文谱系、schema 索引和请求，避免让所有会话消费方承担这些结构。
• 普通生成调用与压缩调用形成一条按时间排序的请求投影，以用途区分而不是放入不同集合。生效的提示词状态及其变化附着在引入它们的请求上；压缩和提示词变化都不是独立检查实体。请求编号和累计用量覆盖已加载的历史窗口，并随更早页面到达而扩展。
• 调用 schema 来自当前生效且已记录的请求头。无密钥快照 fixture（测试前置数据）有意将该目录替换为非数组 token {{tools}}，持久化检查边界会将其视为不可用，而不是尝试投影或虚构 schema。
• 选择记录或请求后，Trajectory 内部会打开检查器，其标签页和概述区域随实体类型变化：Markdown 消息提供渲染内容、来源字段、提供方／模型字段和层级视图；工具提供 JSON 载荷／结果和 schema 视图；请求提供选项、用量、计时和结果跳转。可滚动的概述区域默认保持滚动条滑块透明，直到悬停或 focus-within 时才显示，同时保留滚动条预留空间和滚动行为。图片以媒体形式渲染，而不是显示为序列化数据。
• 折叠轮次时保留其第一条记录，并用紧凑的步骤数和工具调用数替换后续所有行；折叠助手时对其工具调用后代应用相同操作。全局控件会折叠或展开这两个层级。
• 长记录表初始时将已加载尾部置于底部，只挂载视口对应的行窗口及有界的额外缓冲行。仅含请求的分隔行并入下一个具备可测高度的虚拟项，末尾分隔行则保留固定留白，因此虚拟化器不会管理零高度项。可安全用于 DOM 的语义行键与 ARIA 索引使标识不依赖挂载位置。只要已知尾部之前仍有更早历史，即使当前已加载投影低于常规行数阈值，也会立即启用虚拟化。基于稳定键的虚拟化器锚定会在向前补页和尾部追加时保留当前可见项；只有分页完成导致虚拟化停用时，才使用手动滚动高度兜底。选择、时间线聚焦、折叠、搜索和末尾跟随均按稳定的事件或工具调用标识定位，不要求对应 DOM 行已存在。初始定位完成前以及更早页面仍在等待时，明确的加载行会遮住真实记录。原始窗口的基准序号即使在一页未增加任何 surface 可见节点时，也能检测到这次向前补页。
• 移除独立的 waterfall（瀑布式事件）标签页。固定在记录表上方的 Overview 区域将所有 startedAt 已知的已加载记录按各自耗时投影到三条语义计时轨道。仍有更早前缀尚未加载且 viewport 包含已加载时间域起点时，中性的省略号控件会遮住截断边缘并加载一页更早历史，而不会为未知历史虚构耗时；悬停在该控件上会隐藏普通的时间线光标。已完成的助手时间条以首个非空 token 增量为分界，用不同颜色按真实比例表示 TTFT 与解码时间；计时不完整时退化为单一助手色。悬停 500 ms 后会显示精确起止时刻、总耗时、TTFT 和解码时间，而不依赖浏览器原生 tooltip 的延迟。向左或向右拖动会提交包含边界的区间筛选：任何活动区间与所选区间任一边界重叠的记录都会保留，计时未知的记录会从聚焦后的记录表中移除，清除选择则恢复完整分支。滚轮手势用于缩放时间域。右键单击会清除区间选择；右键拖动则只会平移已放大的 viewport，不会改变该选区。聚焦后，Overview 区域仍保留完整时间范围，以便在不失去方位的情况下调整或清除选择。
• 实时历史更新仅在用户已经跟随记录表末尾时保留底部位置。向上滚动会清除跟随状态，因此流式分块和新追加的记录不会打断对旧记录的检查。末尾跟随与虚拟化器测量仅响应行键和高度，而非内容标识，因此仅含文本的流式帧既不会丢弃测量缓存，也不会重复执行 DOM 滚动写入。
• token 流式输出会复用已完成历史的检查结果、布局、请求编号、Overview 投影和搜索结果。每个帧只追加当前未完成助手的单元格，并在查询处于激活状态时搜索这部分内容；文本与推理（reasoning）增量不会重新折叠或扫描已加载前缀，而消息完成、工具生命周期、压缩、rewrite 及其他结构事件会重建受影响的投影。在这些投影重建前，检查记录表会丢弃已完成步骤中没有任何投影读取的 token 载荷，但会保留首个可见 token 用于计时、保留所有用量分片用于核算，并保留未完成或中断步骤的所有分片；独立历史数据源仍保留原始条目。
• 历史折叠只把已加载的 surface 事件重新编号为紧凑连续的输入并交给规范 surface manager，再将其节点映射回会话绝对序号。因此，结构事件会保留规范的替换校验，而无需重放 token 分片，也不会为未加载的序号实体化合成事件。
• Trajectory 通过 data-conversation-composer-overlay 启用由会话持有的 composer 浮层模式。ConversationRoot 负责定位 composer seat 并发布其实时高度；Trajectory 让记录表保持全高，并在记录表与检查器的纵向滚动容器内预留该高度加 16 px。这两个窗格会根据可用宽度自适应，而不会在浮层下方暴露横向滚动条。
• 此局部检查器与会话级 Chat 详情栏相互独立。在窄屏下，检查器会覆盖记录表，并且仍可通过键盘或指针关闭。

曾考虑的替代方案

照搬 Vite DevTools 的字体、颜色、玻璃表面或组件形状。 不予采纳：这些选择表达的是另一种产品身份。实现仅吸收可迁移的方法，即中性结构、语义强调色、机器数据排版、紧凑扫读，以及只为浮层保留阴影。

每个轮次和步骤保留一张卡片。 不予采纳：重复的卡片框架减少了可见记录数量，并降低了跨步骤比较的速度。

在表格中挂载每条投影记录。 不予采纳：记录投影仍可用于搜索、计时和导航，但把每一行及其后代都保留在 DOM 中，会使浏览器渲染开销随完整会话增长，而非随可见视口增长。

Trajectory 挂载时补齐所有历史页面。 不予采纳：完整会话指标可以立即获得，但传输并反复投影含大量分片的旧页面会延迟对当前尾部的检查。按需向前分页会让这项成本随用户导航产生。

每收到一个流式 token 分片就重建已加载记录表。 不予采纳：虚拟行限制了 DOM 工作量，却不会让反复折叠历史变得低廉。保持已完成投影稳定，可以让普通增量的成本只随当前未完成部分增长，而结构事件仍是显式的完整重建边界。

不使用轮次或请求边界，将所有记录完全扁平化。 不予采纳：轨迹并非普通日志流；这些边界无需占用独立行，也能保留因果结构。

复用全局 Chat 详情栏。 不予采纳：这会让局部检查与会话导航耦合，还会使行点击意外改变另一个视图的状态。

由 Trajectory CSS 覆盖 composer seat。 不予采纳：跨包选择器会依赖生成类选择器的优先级和样式表顺序。显式视图标记让 seat 几何形状和活跃阶段优先级留在 ConversationRoot 中，而 Trajectory 只负责自身内部的避让空间。

将计时保留在独立的 waterfall 标签页中。 不予采纳：占位实现汇总的是节点数而非记录计时，并迫使用户离开想要聚焦的记录。保留完整时间范围的 Overview 区域让计时和筛选后的记录处于同一视觉上下文中。

修改全局主题 token 以匹配参考设计。 不予采纳：现有主题已经提供配对的亮色与暗色语义层，局部重新设计不足以成为修改无关表面的理由。

后果

轨迹视图在保留轮次与请求定位的同时，每个视口可以显示更多有效记录。上下文 rewrite 与压缩保持在周边历史中的原始位置，rewind 则建立仅继承保留前缀的后继分支。浮动 composer 让记录表一直显示到视口边缘，同时不会遮住最后几行，也不会隐藏横向控件。主记录表省略 token 用量和耗时，让内容获得可用宽度；局部检查器展示这些数据以及完整载荷、提供方／模型字段、来源字段、schema 和请求计时。Overview 区域使用记录的开始时间、耗时与 token 边界数据，而不虚构实时流逝时间，其包含边界的聚焦行为与用户熟悉的 Chrome DevTools Network 交互一致。尾部优先分页限制初始传输和投影工作量，虚拟化限制已挂载的行元素数量，未完成部分的增量投影让普通 token 帧的工作量不再随已加载历史长度增长，而已完成步骤的分片压缩则让结构重建的工作量与检查所需条目数量成正比，而非与原始 token 数量成正比。针对性组件测试锁定尾部优先分页、向前补页锚定与标识保持、虚拟窗口、末尾跟随、仅含内容的流式输出不会重复写入滚动位置、流式输出的结构共享、高序号窗口折叠、计时投影、延迟展示详情、折叠、记录与区间选择、实体特定标签页和运行／错误语义。真实浏览器中的长记录表约定锁定向前补页时稳定的几何位置、有界挂载、顶部／中部／底部可达性，以及按节奏进行的流式输出中有界的滚动写入；组装后的 Web 快照则通过真实客户端组合锁定记录表、Overview 计时详情、composer 浮层几何形状与检查器。