Kun Conversation Trajectory：会话级模型轨迹视图与紧凑持久化存储实战指南-平芜编程栈

人工智能
AI Agent
自主智能体
桌面应用
MCP Clients

【免费下载链接】Kun

Local-first AI agent workspace for coding, writing, design, research, and automation — one runtime for desktop GUI and TUI.

项目地址：https://gitcode.com/gh_mirrors/de/Kun

点击查看免费下载

Kun 是 Local-first 的 AI Agent 工作区，其运行时同时支撑桌面 GUI 与 TUI。本指南以openspec/changes/add-conversation-trajectory-view变更计划及其两份规格说明（conversation-trajectory-view与compact-trajectory-storage）为主体，完整讲解会话级轨迹视图（Trajectory View）的 UI 结构、数据采集策略、紧凑存储架构、查询 API 与故障恢复行为。读完本文，你将掌握如何在 Kun 中切换聊天/轨迹双中心视图、理解生命周期元数据与提示词清单（Prompt Manifest）的持久化机制，并能按契约调用轨迹分页/摘要/详情接口排查长会话的模型、工具、耗时与失败行为。

背景：为什么需要会话级轨迹视图

Kun 此前已经具备模型请求诊断能力：LlmDebugRecorder记录精确的模型传输，完成的记录按线程写入 JSONL，并在工作台的 Agent Perspective 右侧面板中渲染。但这一方案有两个结构性缺陷：

信息被局限在右侧检查器中，无法在会话上下文里纵览模型、工具、时序、用量、重试与失败行为；
原始请求/响应负载被独立于会话正史（canonical conversation history）大量持久化，长会话场景下存储成本线性膨胀，难以扩展。

因此本次变更的目标不是新增一个诊断面板，而是引入会话作用域（conversation-scoped）的轨迹视图——它是所选会话的内容视图，而非运行时诊断或供应商控制面板。核心设计取向是：以紧凑的生命周期元数据 + 可选的按内容寻址细节存储，替代“全量请求/响应重复落盘”的旧策略，同时保留既有会话正史作为响应与工具内容的唯一权威来源。

一、UI：聊天 / 轨迹双中心视图

1.1 标题栏 Trace 按钮与状态保持

使用会话标题栏中的Trace按钮，可将中心区域在聊天（chat）与轨迹（trajectory）之间切换。切换时：

编辑器（Composer）与隐藏的聊天时间线保持挂载，草稿、模型/权限选择以及聊天滚动位置都不会丢失；
轨迹模式下 Composer 依然挂载（保证草稿/模型状态存活），但视觉隐藏、处于惰性状态并被移出指针命中测试；轨迹与检查器因此可获得完整交互面，仅保留 16px 底部空隙；返回 Chat 时恢复同一个 Composer 实例。

标题栏按钮具有运行/失败状态指示：当所选会话存在进行中的模型请求，或最近一次请求失败时，按钮会暴露对应的 running / failure 指示及其按下态（accessibility pressed state）。

1.2 轨迹视图的组成

轨迹视图包含以下核心区域：

32px 工具栏：展示 Duration / Turns / Calls 概要，提供已加载窗口内的增量搜索；
50px 输入/模型/工具时序总览条：支持顺序（sequence）与按录制时长（recorded-duration）两种展示模式；
两列时间顺序 Event/Content 账本（Ledger）：按 Turn 轨道（rails）组织，标注请求边界，支持向后分页、独立 Turn/调用折叠，且超过 100 行时启用虚拟化；
同步时间线：支持范围选择、滚轮缩放、右键平移/清除、延迟 tooltip，以及与账本的双向联动选择；
类型化检查器（Inspector）：针对 System、Request、Markdown、Tool、Subtool 等记录类型，提供 Markdown、JSON/Schema、附件、来源、选项、用量、时序与 Prompt Diff 视图；
实时跟随（live-edge following）：仅当账本处于实时边缘时跟随新记录；用户检查旧记录时暂停跟随。

1.3 响应式布局与交互细节

宽屏下检查器停靠宽度为clamp(320px, 38%, 440px)，可调整至 720px，同时账本至少保留 280px；
760px 及以下变为右侧浮层，宽度不超过 420px；
Event 列在表格容器达到 620px 时从 122px 折叠为仅图标 50px；
轨迹打开时不选中任何记录，账本占满全宽；选中账本行、请求边界或时序区间时打开类型化检查器，其 Summary 视图展示状态、层级、用量、时序与有界预览，而非将归一化 wire record 直接以 JSON 倾倒；
旧的 Agent Perspective 右侧面板贡献已被移除，保存的旧布局引用会被归一化为无面板。

实现要点（no-drag 边界）：整个轨迹表面显式退出 Electron 可拖拽窗口区域。原因在于外围 Workbench 外壳本身是可拖拽的，若缺少no-drag边界，Chromium 会把账本的点击与滚轮手势当作标题栏交互。渲染器实现中可见该约定，例如src/renderer/src/components/trajectory/TrajectoryView.tsx根部挂载了ds-no-drag类。

1.4 无障碍与状态边界

规格要求检查器在 1080px 以上停靠、760–1079px 浮层、760px 以下全屏（并提供返回轨迹的可用控件），同时遵守暗色主题、键盘操作与 reduced-motion 偏好。轨迹相关的过滤器、查询、选择、折叠、滚动、检查器宽度与时间线模式按线程隔离：切换会话再返回时，每个会话恢复各自的轨迹 UI 状态（渲染器侧通过有界 Zustand store 持有）。当用户离开实时边缘后新记录到达，滚动位置保持不动，并出现“返回实时边缘”的新记录计数器。

二、采集策略：始终在线的生命周期元数据

2.1 捕获开关的语义变化

轨迹持久化始终记录生命周期元数据。原有的按线程modelRequestCaptureEnabled开关只控制两件事：

完整的提示词细节（Prompt Detail）是否落盘；
有界的（bounded）内存内 wire 诊断是否保留。

Settings 继续控制后续创建会话的默认值。也就是说：

关闭完整内容捕获时：模型/工具状态、用量、时序、重试、错误与权威的 Session 输出依然可用；精确 System Prompt、工具 schema 与请求选项显示为 “not captured”。
开启完整内容捕获时：在元数据之外，额外生成提示词清单与内容寻址细节块。

2.2 记录身份模型

每个具体的 Provider 尝试（attempt）拥有独立的 request ID 与尝试序号（attempt ordinal）；
一个逻辑模型步骤（logical model step）的多个尝试共享 round ID 与 Step 号；
首段模型内容记录TTFT（Time To First Token）边界；普通流式增量（stream deltas）不落为轨迹行。

llm_request：requestId、attempt、attemptReason、purpose、provider、model、endpointFormat、responseStatus、usage，以及可选manifestId、promptFingerprint/previousPromptFingerprint、systemBlobId/toolsBlobId/configBlobId；
tool/subtool：callId、parentRequestId/parentCallId、toolName、argumentsItemId/resultItemId、isError、有界参数/结果预览与attachmentIds；
消息类（system | user | context | compacted | assistant）：itemId/itemIds、parentRequestId、来源信息、thinkingPreview、attachmentIds与指纹字段。

2.3 有界写入与崩溃恢复

持久化仅包含生命周期开始、首个内容、终止状态，以及每两秒至多一个轻量进度检查点；绝不把普通流式增量持久化为轨迹记录；
运行时在请求未达终止态时退出：重启后该请求投影为interrupted（中断），超过 24 小时的检查点被清除；
缺失或被预算驱逐的 manifest 不会隐藏生命周期元数据；
查询与采集失败永不重试、重写或阻塞 Provider 请求。

三、存储：紧凑事实 + 内容寻址细节

3.1 权威数据仍在 Session store

会话正史继续保留在 Session store 中：用户与助手消息、推理条目（reasoning items）、工具参数/结果、压缩条目（compaction items）、附件与生成媒体。轨迹持久化只存紧凑生命周期事实与引用，绝不持久保存普通流增量、原始 HTTP 头/帧、凭据、附件字节、图片/Base64 正文、完整工具输出或另一份助手输出副本。

3.2 可选提示词细节：manifest + 不可变 blob

目录结构如下（<dataDir>即 Kun 数据目录）：

<dataDir>/observability/trajectory/ records/<base64url-thread-id>.jsonl manifests/<base64url-thread-id>/<base64url-request-id>.json blobs/<sha256>.br

records：每线程紧凑生命周期日志（JSONL）；
manifests：提示词清单，记录有序请求结构、Session 边界、条目引用、内容哈希与附件元数据；
blobs：内容寻址细节块，Brotli 压缩、按 SHA-256 去重、使用私有目录/文件权限写入。

blob 在哈希前先做敏感信息清洗（sanitize），超大内容（超过单块上限）仅保留有界的 head/tail 数据并带显式截断元数据。选择 Node 内置 Brotli 而非引入 Zstd 原生依赖，是为了让打包版 Kun 与独立 TUI 使用同一内建编解码器；manifest 中记录 codec 以便将来扩展。契约中的PromptBlobRefSchema强制 blobId 为 64 位十六进制（SHA-256），kind 为system | tools | config | message，codec 固定br，并携带 rawSize/compressedSize/truncated；PromptManifestSchema则聚合 blobs、messageItemIds、attachmentIds与retainedBytes。

3.3 默认细节预算

预算项	默认值	说明
全局细节总量	512 MiB	超出后按 LRU 驱逐不活跃细节
单会话细节上限	64 MiB	超出后驱逐该线程旧细节
内联详情预览	16 KiB	检查器内联预览上限
可搜索列表预览	2 KiB	索引/搜索所用有界预览
单个源 blob 上限	8 MiB	超过则转为有界 head/tail 保留

上述常量可在kun/src/services/trajectory-content-store.ts中直接找到：TRAJECTORY_MAX_TOTAL_DETAIL_BYTES（512 MiB）、TRAJECTORY_MAX_THREAD_DETAIL_BYTES（64 MiB）、TRAJECTORY_INLINE_PREVIEW_BYTES（16 KiB）、TRAJECTORY_SEARCH_PREVIEW_BYTES（2 KiB）、TRAJECTORY_MAX_BLOB_BYTES（8 MiB），以及 head 512 KiB / tail 64 KiB 的截断边界。

预算驱逐只移除旧细节：生命周期元数据在会话被删除前始终可查；受影响记录上报evicted详情状态。会话删除时，会删除该线程的 manifests 与遗留 trace 文件，随后通过 mark-and-sweep 清理无引用的 blobs（以权威 manifests 为准，而非依赖崩溃后可能不一致的可变引用计数）。

3.4 权威文件系统与可重建索引

每线程紧凑日志、manifests 与 blob 文件是权威数据。Hybrid SQLite 可能对请求/工具元数据、预览与 blob 引用建立索引以支撑摘要/过滤/搜索，但该索引可重建；SQLite 不可用时，查询 API 回退到对紧凑文件系统数据的扫描（带降级警告）。规格还要求：索引只覆盖元数据与 2 KiB 清洗预览，不建立 blob 的全文副本，避免内容重复。

四、查询 API：分页、摘要与分区详情

4.1 路由清单

三条认证、线程隔离的路由：

GET /v1/threads/{threadId}/trajectory GET /v1/threads/{threadId}/trajectory/summary GET /v1/threads/{threadId}/trajectory/{recordId}/detail?section=overview

分页路由接受limit与不透明cursor；既有的filter=all|llm|tool|error与有界q参数保持兼容，而当前 UI 在已加载页内做本地搜索。详情 section 依据所选记录类型取用：overview、input、output、usage、timing、raw、arguments、result、system-prompt、tools、diff、options、rendered、source、schema。GET /v1/threads/{threadId}/model-requests继续保留用于兼容，线程 PATCH 字段仍为内容捕获开关。

4.2 服务端实现与契约校验

路由注册见kun/src/server/routes/register-thread-routes.ts（/v1/threads/:id/trajectory、/trajectory/summary、/:recordId/detail三条 GET）；
实现位于kun/src/server/routes/trajectory.ts：limit缺省 100、上限 200，cursor最长 2048，q最长 512，非法查询返回校验错误；线程不存在返回 404，轨迹记录器不可用返回 503（unavailable）；
查询服务kun/src/services/trajectory-query-service.ts：内部上限MAX_QUERY_RECORDS = 20_000、REQUEST_PAGE_SIZE = 200，按 filter/query/cursor 过滤后取limit条，并以最后一条记录编码不透明nextCursor；返回的TrajectoryPage带 schemaVersion、records、nextCursor、summary、warnings 与historyIncomplete标志；
摘要TrajectorySummary聚合请求/工具/运行中/失败计数，输入/输出/推理/缓存读/缓存写 token、缓存命中率、平均 TTFT、每秒 token 数、总耗时、美元与人民币成本及价值估计，并给出lastStatus；
详情请求按 recordId 检索，若请求 ID 不属于该线程则返回 not found（不泄露记录是否存在）；
渲染器侧端点常量见src/shared/kun-endpoints.ts（KUN_THREAD_TRAJECTORY_TEMPLATE、KUN_THREAD_TRAJECTORY_SUMMARY_TEMPLATE、KUN_THREAD_TRAJECTORY_DETAIL_TEMPLATE），并经过 main/preload allowlist 与 renderer runtime client 的接线。

4.3 分页与渲染方向

API 返回最新在前（newest-first）的分页结果；渲染器把已加载页反转为时间顺序账本，并在加载更早页时前置（prepend）旧分组，同时保持所选记录与可见滚动锚点不变——对应“Large trajectory”场景：会话含一万条轨迹记录时，账本 DOM 只挂载可见 overscan 窗口。渲染器src/renderer/src/components/trajectory/TrajectoryLedger.tsx使用@tanstack/react-virtual的useVirtualizer（超过虚拟化阈值或存在更早历史时启用，含 overscan 配置与 scrollToIndex 定位），变量高账本行因此可扩展至长会话。

五、兼容性、迁移与既有资产

5.1 旧版 schema-v1 兼容

遗留的 schema-v1 模型请求 JSONL无需急切破坏性迁移即可继续读取。新持久化记录不再包含原始请求与响应正文；查询层把两种格式都投影为轨迹 wire schema v2，渲染器在对接更早的运行时（runtime）时也能归一化旧的 schema-v1 HTTP 页面。旧记录保持可读，且由既有保留策略与线程删除负责清理，不做破坏性迁移。

5.2 迁移步骤（计划视角）

引入新契约与 schema-v1 记录兼容读取器；
开始写紧凑生命周期记录与可选 manifests，遗留文件不动；
增加查询 API 与渲染器客户端，将工作台入口切到中心轨迹视图；
停止持久化原始负载追加，为显式捕获保留有界实时诊断；
线程删除时同时清理旧与新轨迹产物并执行尽力而为的 blob GC；
由于 Session 数据不变、旧设置与记录仍可解析，回滚始终可行。

5.3 UI 参考与归属

轨迹布局、时序交互、密集账本信息架构、检查器行为与参考测试矩阵改编自 DeepSeek Harness 的packages/client/ui-trajectory（冻结于提交0a53fb55bea101816fa226bb964ae2bed71c343b，MIT 许可，版权声明保留在THIRD_PARTY_NOTICES.md）。Kun不导入或运行时链接Harness 检出，移植采用 Kun 自己的轨迹 schema、Session 记录、Markdown/附件渲染器、持久化规则、无障碍约定与语义主题 token；Harness 的全局导航、页面标签、Cordis 插槽与无关应用外壳均未包含。

角色颜色在时间线与账本中遵循同一语义模型：System/Compacted 中性色、User 蓝、Context 绿、Assistant 紫（TTFT 段更浅）、Tool/Subtool 琥珀、失败红；映射到 Kun 主题 token 而非固定浅色主题色。时间线范围选择使用着色内部、实色强调边与外部遮罩；打开视图会清除上次访问遗留的过期范围。

六、边界与设计取舍（读源码时留意）

从设计文档（openspec/changes/add-conversation-trajectory-view/design.md）与两份 spec 中可提炼以下关键取舍，便于理解实现边界：

非目标：不持久化 token/块级增量、原始 HTTP 交换、附件字节或完整工具输出；不做提示词 diff、轨迹导出、时间线缩放/范围选择、请求对比、固定详情保留或完整子代理树；不把 SQLite 变为权威存储，也不新增另一条 agent/runtime 路径；
Session 条目即响应与工具真相源：助手文本/推理、工具参数/结果、压缩、用户消息与附件通过稳定的 item/call ID 被引用，轨迹记录只存关联与有界预览——把大体积正文复制进轨迹存储的方案已被否决，因为它会在长会话中重复最大数据并造成删除/压缩行为不一致；
风险缓解：manifest 条目引用可能被后续剪枝 → 对精确捕获输入存清洗后的内容哈希/回退 blob，并显式展示缺失/被驱逐的细节；始终在线元数据增加写入 → 只持久化生命周期转换与每两秒至多一个检查点；崩溃留下挂起记录 → 启动/查询时把不活跃的 pending 记录终结为interrupted；blob 预算移除细节 → 永不驱逐元数据并返回evicted，同时保留时序、用量、错误与 Session 引用。

结语

Kun 的会话轨迹视图把“模型请求诊断”从右侧检查器升级为与聊天平级的会话中心视图：无论是否开启完整内容捕获，生命周期元数据始终可用；提示词细节以 manifest + SHA-256/Brotli 内容寻址 blob 的方式按预算保留；旧 schema-v1 轨迹兼容可读；分页/摘要/详情 API 带有版本化 DTO 与不透明游标。若需深入实现，建议依次阅读契约定义、查询服务、内容存储、路由实现与渲染器组件，并结合kun/src/services/trajectory-query-service.test.ts、kun/src/services/trajectory-content-store.test.ts、kun/src/server/routes/trajectory.test.ts等测试用例验证行为。