前言¶
DeepSeek Harness（DSH）运行后会在 ~/.dsh/sessions 下写入会话文件，通常是 session.v3.jsonl.zstd 或 session.v4.jsonl.zstd 等多帧 zstd 压缩文件。查看最近发生的事件时，传统方式往往需要解压整个文件，对大文件既慢又费内存。
本插件是 DSH web 插件：会话惰性查看器（纯只读）。它列出 ~/.dsh/sessions 下全部会话（只做 stat 不解压），并可只解压任意会话文件的最后 1–2 个 zstd 帧，快速查看最近发生的事件，不触碰整份文件。
安装与启用¶
使用 DSH 官方插件命令安装：
dsh plugin --profile web add @240xu/dsh-session-lazy-view
安装完成后重启 DSH web 实例，直接访问 http://<dsh-web-地址>/lazyview 即可打开独立面板页。
核心功能¶
会话列表与预览¶
- 访问
/lazyview打开 HTML 面板，按项目分组列出会话。 - 列表仅做 stat（不读文件内容），文件大小超过 10MB 的行会标红。
- 每行提供「tail」按钮，点击展开最近 2 帧，支持「上一页」翻页。
- 列字段包括 sessionId、path、artifact、format、bytes、mtime 等。
帧级惰性读取¶
- 使用
/lazyview/api/tail?path=<相对路径>&frames=2&skip=0端点。 path必须是/api/list返回的相对路径，且文件名以session.v3.jsonl.zstd或session.jsonl.zstd结尾。- 服务端从文件尾部读一个窗口，扫描帧魔数
0x28 B5 2F FD，只解压候选帧。 skip参数用于翻页偏移（跳过最新 skip 帧后再取 frames 帧）。- 帧内事件已文本化（role + 截断到 2000 字符的 text / tool-call / tool-result）。
- 解析失败（坏帧、旧格式、窗口截断等）返回
{ok:false, error:{code, message}}结构化错误，不会导致面板 500。
会话搜索¶
- 使用
/lazyview/api/search?path=&q=&max=20进行会话内全文搜索。 - 流式逐帧解压做大小写不敏感子串匹配，命中返回
{frameIndex, seq, type, role, snippet}（命中点前后各 60 字符窗口）。 - 达到
max截断，默认最多扫 500 帧，未扫完返回partial:true。 - 每帧之间调用
setImmediate让出事件循环，客户端断开（AbortSignal）即中止扫描。
会话统计¶
- 使用
/lazyview/api/stats?path=[&fast=1]获取会话统计信息。 - 不带
fast=1时：帧数、总事件数、按 type 分组计数、首/末事件时间、文件字节数、session header。 - 带
fast=1时：仅流式扫描帧魔数（不解压），给出帧数与字节数，内存有界。
导出 Markdown¶
- 使用
/lazyview/api/export?path=&frames=N将最近 N 帧（≤20）导出为 Markdown 文本下载。 - 文本在内存中生成直接响应，不写入任何文件。
Timeline 视图¶
- 在会话打开视图中切换「时间线」视图，按 turn 分组展示正序事件时间线（vscode Timeline 式阅读投影）。
- 分组规则：有
turn/start事件时开启新组；历史格式以user/message为组边界。 - 组默认折叠一行摘要，展开显示全部事件；折叠状态保存在内存中。
- 支持深链：
/lazyview?session=<id>&seq=<n>自动打开会话、进入时间线、展开目标组并高亮首个 seq≥n 的事件。 - 事件带有
surfaceOp（op:”replace”）时，被替换区间内的事件在时间线上渲染为半透明 +「已遮蔽」徽标（纯本地计算）。
已知限制¶
- 旧格式
session.jsonl.zstd为单帧，tail 读取没有惰性收益。 - 尾部窗口默认 1MB，最多增长到 64MB；极端情况下单帧超过 64MB 时返回
truncatedScan: true且可能少帧。 - 帧魔数理论上可能出现在压缩数据内部造成假候选；假候选解压失败后以 per-frame
error呈现。 - 事件文本化只覆盖已验证的形状（user/assistant/system message、tool call/result），其余事件类型输出紧凑 JSON 摘要。
- 未做缓存，每次 tail 请求都重新读窗口，对调试场景足够。
适用场景与注意¶
- 适合需要快速查看最近事件、对大会话文件做惰性读取的 DSH 用户。
- 插件以当前 dsh 进程权限运行，读取
~/.dsh/sessions，请确保安装前检查源码与许可证。 - 面板是
/lazyview独立页，DSH 宿主侧边栏没有入口是有意设计（纯只读工具），若安装了dsh-devkit可在 Ctrl+K 命令面板中打开。
总结¶
本插件通过扫描帧魔数、只解压候选帧的方式，在保持纯只读的前提下，提供会话列表、帧级 tail、全文搜索、统计与 Markdown 导出能力，并支持 Timeline 视图与深链跳转，是查看 DSH 会话的高效工具。
- 目录页：https://www.skillhub.cn/plugins/240xu/dsh-session-lazy-view
- GitHub：https://github.com/240xu/dsh-session-lazy-view
