description: "qilin Web 客户端右侧边栏的 Trajectory 页面：按轮次组织的事件记录表加交互式时间概览，以及把同一记录表画成实时节点与边流动图的轨迹图视图。" kind: "package-reference"

@qilin-agent/client-ui-trajectory

English | 中文

概述

轨迹图标签页把记录画成实时流动的节点与边；打开记录表的两条路径是轨迹图工具栏的账本控件，以及 Chat 工具卡片的查看操作（后者聚焦该调用）——记录表类型自身不提供引导页条目，因此侧边栏的引导页只列轨迹图。记录表以按轮次组织的事件记录表和时间概览检查活动，对用户、助手、工具、嵌套子工具和压缩记录分组，标示轮次与步骤边界，并为所选记录打开检查器，显示 token 用量、耗时、输入、输出、计时、图片和附件。较长历史打开时定位于尾部，按需加载更早页面，并且只渲染可见行。流式输出期间，视图会跟随尾部，直到你向上滚动；进行中的记录只显示开始标记，不会虚构耗时。

目录

• 使用本包
• 理解实现
• 进一步探索
• 模型体验
• 已知限制与延期工作
• 开发备注

使用本包

从右侧边栏的引导页打开 Trajectory 标签页（或点击 Chat 工具卡片的查看操作，直接聚焦该调用），把 agent 活动作为事件记录表与时间线查看。初始尾部完成定位前，记录表会用明确的加载行遮住真实记录；更早的前缀仍未加载时，首行控件会在点击时加载一页更早的历史，并在该页加载期间显示禁用的加载状态。

检查记录

调用按已记录的工具名识别。对于 run_code，记录行展示程序说明，检查器显示带行号和语法高亮的源码。“代码”页提供换行、查看原始 JSON 参数的 {} 切换按钮，以及保留末尾换行的源码原样复制。复制原始参数时保留记录中 JSON 的空白。每个新打开的代码视图采用上次选择的换行状态；切换时，其他已打开视图保持原状。输出保留记录中的文本，完整 JSON 对象或数组使用树形展示。高亮只采用已记录工具 Schema 中明确且无冲突的 TypeScript 或 Python 提示；提示缺失或冲突时显示纯文本源码。回放约束见 PTC 检查决策。

选择、时间线导航、折叠与搜索只覆盖 React 可见窗口。请求编号与累计用量覆盖完整的驻留快照。选择记录会打开局部检查器，查看 token 用量、耗时、输入、输出、计时与持久保留的图片。图片 URL 使用 Conversation 拥有的逐会话缓存，因此 Chat 与 Trajectory 对每个附件共享一次已授权读取。用户记录会在文本旁同时显示非零的图片与普通文件数量，仅含附件的记录也显示这些数量。独立运行的压缩请求会按时间顺序显示在自己的 Between turns 区段中，而带编号的压缩仍位于其所属轮次内。

概述与预览共用正文之后的有序附件列表，保留重复引用。每行展示完整缩放的图片缩略图或文件类型图标、已记录的文件名（未命名图片使用本地化的编号名称），以及可用的已记录大小、类型和图片尺寸。零字节文件保留大小显示，截断的文件名通过提示显示完整名称。图片打开现有灯箱。原始内容保留内容块顺序和未渲染文本，图片与文件使用默认折叠的展开项，包含完整的已记录字段。

请求在等待输出、流式生成或重试期间保持等待状态。尚无助手输出的请求不提供结果链接；中断的输出仍可检查，请求和助手记录都显示失败，即使步骤起点位于已加载历史之外。恢复后仍可查看重试次数与上次尝试错误；这些历史信息不改变请求当前的状态。模型回复完成并不表示其工具或轮次已经结束。

流式回复保留已知的开始时间与 TTFT。结算后由 token 时间戳给出生成耗时，吞吐量还要求已记录 usage。

检查器中的思考内容使用紧凑 Markdown，沿用检查器固定的 13px 字号和 20px 行高，不受内容字号设置影响。标题只加粗，不放大字号或行高。助手输出保留常规 Markdown 排版。

时间概览

固定在记录表上方的 Overview 区域从左到右投影记录的真实开始时间与耗时；助手时间条区分记录到的 TTFT 与解码时间，悬停 500 ms 后可查看精确时刻与耗时详情。拖选区间会把记录表聚焦到该闭区间内任何时刻处于活动的记录；滚轮手势用于缩放时间域；右键单击会清除所选区间，在已放大的视口上按住右键拖动则会平移。初始视图与流式更新都停留在尾部；向上滚动会暂停跟随，因此新记录不会打断对旧记录的检查。

轨迹图视图

轨迹图页面从引导页的 trajectory-graph 条目打开，正文以自己的 id 占用同一个键控标签正文座位，每个表面至多一个图；工具栏的账本控件打开它所绘制的记录表，而记录表不提供引导页条目，因此轨迹图是侧边栏提供的唯一轨迹页面。两个页面读取同一个 useTrajectory 投影的 Trajectory target，轨迹图自身不新增任何会话请求：记录表把记录呈现为行，轨迹图把记录画成输入、模型、工具三条泳道中的芯片，装在编号的轮次条带里，并用记录表自身记录的事实连成边——喂给每个请求的提示词、请求产出的结果、助手派发的每个调用、工具派发的子调用，以及转回下一个请求的循环。流式前缀与进行中的调用渲染为活动记录，其边带流动动画；工具栏可暂停流动，并切换尾部跟随；选中芯片会打开检查器，查看该记录的名称、调用 id、可折叠的格式化参数与结果，助手正文以紧凑 Markdown 渲染，附件记录会列出其图片（缩略图，经授权加载器打开灯箱）与文件（图标、名称、大小）。工具栏还能按记录顺序回放整个记录表——每一跳等待该记录自身的时间戳间隔（钳制在 0.09–1.1 秒），支持 ×1/×2/×4 速度，每跳沿真实边路径飞行一个数据包，光标未到达的记录保持变暗——并控制画布：以指针为锚点的 ctrl/⌘ 滚轮缩放、拖拽平移与适应宽度。画布会把泳道铺展到面板宽度——设有上限，画布放不下时居中显示——并以点状泳道轨衬底，每条边带一枚按边类型着色的箭头。边类型图例可固定某一类型或在悬停时高亮；搜索框按标签、类型、id 或调用 id 定位记录并循环跳转匹配项；统计行会排名最慢的已落地工具记录，并把令牌总量拆解为各分桶。

理解实现

视图是纯投影：Trajectory 自有的 Definition 从共享 Session 窗口组装业务记录——包括持久化的取消定稿前缀、只能从分片恢复的打断前缀与被打断的工具记录——因此 Trajectory 既不读取也不改变 Chat 会话快照。其 steering 分类器通过持久 splice state 只保留 next-step Inbox ID，并让后续 Context 共享当前 claimed batch。

工具记录从持久 tool/call 事件开始，使用完整参数。Trajectory 保留每个原生与嵌套工具结果事件中的展示元数据，因此历史文件与命令位置来自执行本身。Chat 的瞬态 preparing 阶段不创建 Trajectory 工具行，也不改变历史工具计时。

完整的追加提示词在请求头未加载时显示为独立系统行；仅提供已知文本，不推断请求选项或工具目录。补入其请求历史后，该独立展示被替代而不重复提示词。历史中的系统提示词变更与最近的请求状态比较，包括没有新请求头的先前提示词更新。每个请求保留其所在位置生效的提示词与变更。包括压缩在内的 surface 替换会恢复最后一个非空的存活系统提示词，即使没有新的系统事件；未加载的提示词在对应分页到达前仍不可用。

轨迹图投影

轨迹图页面是同一 snapshot 的纯投影：每个记录一个节点，外加流式前缀与每个未落定的调用；边只来自记录表自身记录的事实，不做任何虚构。每个节点携带从其记录提取的附件与结构化工具调用，不依赖 React 的辅助函数负责排名最慢的已落地工具、按标签/类型/id/调用 id 搜索记录。一个不依赖 React 的布局模块把记录顺序作为纵轴、把行为者泳道作为横轴；渲染窗口只保留最近 400 条记录及其间的边。

虚拟行

长记录表最初只从挂载时尾部结束的 50 个 target Node 派生 React 数据。后续 Node 会扩展这个固定起点的窗口而不会逐出其前缀；现有加载控件会先显露更早的驻留 Node，再请求下一个 Session 页面。虚拟化只挂载可见行窗口加少量缓冲；仅含请求的分隔行并入下一个具备可测高度的虚拟项，语义行键与 ARIA 索引在向前补页后保持不变。虚拟化器负责结构性追加后的底部跟随；非虚拟记录表会直接写入末尾位置。仅含内容更新的流式帧会保持虚拟行的键与高度、复用测量结果，并且不会重复写入末尾滚动位置。已完成的回复会在 Trajectory target State 中保留组装后的 blocks、计时与用量，共享 Session 窗口则保留原始 Event。

布局

记录表填满所在侧边栏面板并自持纵向滚动容器，不为会话的浮层 composer 预留空间。可滚动的 Summary 区域在悬停或聚焦前保持滚动条滑块透明，同时不改变滚动几何空间。本包不提供 service，也不声明 Context 合并。

进一步探索

以下页面覆盖对话宿主与本视图所投影的会话数据。

• ui-sidebar-right——本包注册标签页类型与键控正文座位的侧边栏。
• session-projection——为客户端读取模型提供会话状态的服务注册表。
• session——其窗口持有原始事件的会话 seam。
• compaction——其请求出现在记录表中的压缩 seam。

模型体验

无。该包是浏览器端 UI 插件层，不注册任何面向模型的内容。

KV Cache 影响

无；该包既不组装也不发送提供方请求。

已知限制与延期工作

这些限制定义工作仍在进行时视图能显示什么；它们是当前包约束。

• 进行中时 Time 保持空白：partial 与 runningCalls 行会显示运行状态，但不会虚构耗时，因此 Overview 区域只渲染开始标记，而不会杜撰实时跨度。记录选择与时间线选择位于 Trajectory 内部，不提供锚点深链接。
• 轨迹图渲染尾部窗口：轨迹图页面只保留最近 400 条记录及其间的边，并显示被裁掉的计数，因此很长的记录表展示的是最近的流动而不是完整会话。

开发备注

无。