前言¶
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
