前言¶
在 DSH 上跑智能體時，每一輪請求往往帶着 system、工具定義、注入上下文和完整對話歷史。排查「模型爲什麼這樣答」、對比壓縮前後差異、或把某段對話導出給同事審閱，若只能翻日誌或手抄 JSON，成本很高。dsh-llm-dump 負責把請求按會話落盤；dsh-dump-manager 則在桌面客戶端側提供側欄入口、會話列表、按條目瀏覽與兩種導出，並可在對話界面掛載「LLM Dump」頁籤，與軌跡、統計並列查看同一條條目流。
下面按定位、能力、安裝與典型操作流程說明該插件。事實以倉庫 README 與 package.json 爲準；版本 0.1.1，許可證 MIT，維護者 wannaknowhys。
這是什麼¶
dsh-dump-manager 是 DeepSeek Harness（DSH）的客戶端插件：面向 dsh-llm-dump 已捕獲的轉儲數據，提供側欄面板、條目查看器、Markdown/JSON 導出，以及「導出本輪」等 UI。它不替代採集插件，而是讀 %DSH_HOME%\llm-dumps（默認）下的會話目錄，並把用戶自選條目或「最新一輪」寫到同級 exports\ 目錄。
插件在 SkillHub 目錄 歸類爲客戶端；源碼與說明見 GitHub。
界面層級與分工¶
README 用五個層級描述入口，便於對照實際 UI：
| 層級 | 作用 |
|---|---|
| panel（側欄按鈕） | 僅會話級：查看、打開文件夾、刪除 |
| viewer（查看） | 單會話內按 entry 選擇並導出 |
| tab（LLM Dump） | 同一條流掛載在「軌跡 / 統計」旁 |
| header（導出本輪 ▾） | 按過濾器導出最新一輪 |
| settings（Plugins 頁） | 與上述選項共用存儲 |
Host 側提供路由與導出邏輯，瀏覽器側負責側欄卡片、面板、頁籤與設置頁。README 註明：編輯 Host 模塊後不會熱重載，需切換 bundle 讓 Host 重新導入模塊。
核心功能¶
側欄面板（Panel）¶
側欄底部「Settings」旁顯示 LLM Dumps \<size> · Exports \<size>；進入面板後表頭重複容量並給出會話數、請求數。
表格列包括：session/workspace、requests、size、last write、actions。行操作：
- view：進入該會話的條目查看器。
- folder：在資源管理器中打開該會話轉儲目錄。
- delete：兩步確認刪除。
會話轉儲默認在 <outputDir>（默認 %DSH_HOME%\llm-dumps，一會話一目錄）；導出文件在旁的 exports\。
條目查看器（Viewer）¶
查看器不以「第幾次請求」爲維度，而以 entries 爲單元。類型含義如下：
| type | 含義 |
|---|---|
system |
組裝後的 system prompt |
tools |
工具定義塊 |
user / assistant |
對話消息（assistant 中含 tool call） |
tool |
工具結果消息 |
最後一行可能是 tail entry：來自 responses.jsonl 的最新回覆，尚未作爲歷史重發；帶「最新回覆」標記（流被截斷時爲「最新·中斷」）。
交互要點（摘自 README）：
- 連續列表：複選框、類型徽標、單行摘要、展開開關。
- 縮略：可讀文本（工具調用形如
→ name(args)）；詳細：完整 JSON。 - 每次加載 100 條，滾到底分頁；頁腳顯示「已渲染/總數」；⤓ 到底部 一次渲染本段剩餘條目並跳至末尾。
- 類型行可全選某類或點擊名稱隱藏該類（默認不隱藏）；展開時才拉取正文。
- 全選本段；Shift+點擊 在可見順序上選區間（隱藏類型不會被選入）。
- 當某次請求改寫歷史（壓縮、重建）時，條目流會分段，每段一個頁籤；僅一段時不顯示頁籤欄。
對話頁籤（LLM Dump）¶
與 viewer 展示同一條 entry 流，掛在會話 UI 裏，便於邊跑邊對照軌跡與統計。
導出種類¶
兩種導出均寫入 exports 目錄（<outputDir>\..\exports），不覆蓋已有文件（自動 -1、-2… 後綴）。
| 種類 | 內容 | 文件 |
|---|---|---|
| transcript | 僅選中條目，Markdown；多段用 ## 段 N · seq a–b 分隔；tail entry 會註明來自 response 流 |
.md |
| payload | 每個涉及段落的完整請求快照（lastSeq）：展開 messages、tools、採樣等，每段一行緊湊 JSON |
.json |
README 舉例：全選某 132 次請求的會話時，transcript 約 1.2 MB，而「每請求一快照」模型約 162 MB——適合需要可讀摘要以外的精簡分享。
導出本輪（Newest-turn export）¶
會話標題旁的 導出本輪 ▾ 從最後一次對話請求的快照導出最新一輪（不是從 entry 流拼）：
- 一輪從最後一條
source.kind === 'user'的真實用戶消息起算；time-context、runtime-context、agent-instructions、skill-catalog、compact-checkpoint等注入類 user 消息不能作爲一輪起點。 - 對該請求的回覆讀自
responses.jsonl（尚不在任何 snapshot 中）。 - 無 assistant 且無 user 的「一次性」調用會跳過。
三個持久化過濾器寫在 %DSH_HOME%\llm-dumps\ui.json：
| 選項 | 默認 | 效果 |
|---|---|---|
| include user input | 開 | 保留 kind === 'user' 消息 |
| include tools | 開 | 保留 tool call 與 tool 結果 |
| include injected context | 關 | 保留其餘 user 角色注入消息 |
用戶 prompt 已被壓縮掉時，一輪可能跨多個 segment；僅當跨段邊界符合 compaction 語義時纔會合併導出，否則返回 409（如 NO_DUMP、NO_USER、FORK），UI 會彈窗並建議用手動分段導出。輸出文件：<title>_latest_<stamp>.md 或 .json，落在 exports 目錄。
設置頁¶
Settings → Plugins → LLM Dump Settings 含兩組：
- Newest-turn export：與標題欄菜單相同的三個過濾器與格式，後端爲
ui.json。 - Capture (dsh-llm-dump)：代管
config.json中的輸出目錄（改目錄需兩步確認，已有轉儲不會自動搬遷）；未知鍵在重寫時保留，文件原子替換。提供目錄瀏覽（含 Windows 盤符、/、Home、UNC 等）。
數據格式與兼容¶
讀取 dsh-llm-dump 數據格式 version 1：每會話 append-only 的 requests.jsonl、objects.jsonl（內容去重）、responses.jsonl（最新回覆）。未知字段忽略。
啓動及每次 overview 時，Host 解析 dsh-llm-dump/package.json 的 dsh.formatVersion，與當前構建支持的 1 比較；寫端更新時僅在 Host 日誌與面板頂行警告一次，不阻斷讀取。環境變量 DSH_LLM_DUMP_PACKAGE 可指向另一份 package 做並排檢查。
Host API 僅 loopback，例如 GET /api/dsh-dumps/overview、/stream、/entry，以及 prefs、capture 的 GET/POST（詳見 README 表格）。
安裝與啓用¶
運行環境：Node >= 20。在已配置 DSH desktop profile 的機器上執行：
# 從 npm 安裝
dsh plugin --profile desktop add dsh-dump-manager
# 從本地 checkout 安裝（路徑按你本機爲準）
dsh plugin --profile desktop add github:wannaknowhys/dsh-dump-manager
# 卸載
dsh plugin --profile desktop remove dsh-dump-manager
插件管理器也接受等價寫法：install_bundle target = dsh-dump-manager 或 checkout 目錄。
安裝前建議自行查看 源碼倉庫 與 MIT 許可證。DSH 插件在當前 dsh 進程權限下運行，與官方應用商店無從屬關係；社區目錄由 SkillHub 等站點獨立維護。
典型用法¶
以下流程在 README 中有對應行爲描述，可按順序復現。
1. 確保已有轉儲
先安裝並啓用 dsh-llm-dump，讓會話寫入默認或自定義的 outputDir。dsh-dump-manager 只負責讀取與導出。
2. 從側欄進入面板
打開側欄底部 LLM Dumps 入口，查看各 session 的請求數與體積；對目標會話點 view。
3. 在查看器裏篩選並導出 transcript
在類型行隱藏不需要的 tools 或注入類條目；勾選若干 entry，或使用 全選本段 / Shift 區間選擇。執行 transcript 導出，到 exports\ 取 Markdown 文件。
4. 需要完整請求快照時導出 payload
對同一會話選中覆蓋某段的條目，導出 payload，每段一個 .json 行文件，便於與上游 API 形態對照。
5. 快速帶走「當前最後一輪」
在 viewer 或 LLM Dump 頁籤的標題旁打開 導出本輪 ▾，在 Settings 中調好三個過濾器後導出；若遇 409，按彈窗提示改用 viewer 手動分段導出。
6. 改採集目錄
在 LLM Dump Settings → Capture 中修改輸出目錄並完成確認步驟，避免誤以爲舊目錄數據會自動遷移。
適用場景與注意¶
適合：已在用 dsh-llm-dump 的 DSH 桌面用戶，需要會話級總覽、按 entry 精讀、壓縮分段對照，以及比「每請求一文件」更輕的 Markdown 分享。
注意：
- 必須與 dsh-llm-dump 配合；單獨安裝 manager 不會產生轉儲。
- 修改 Host 代碼後需 toggle bundle 才能生效。
- 寫端格式版本高於 reader 支持範圍時僅警告，但若 llm-dump 引入不兼容語義，仍以 llm-dump 文檔爲準。
- UI 文案來自
lib/strings.js（中英）；瀏覽器端使用同步後的內聯副本。
結尾¶
dsh-dump-manager 把 LLM 轉儲從「目錄裏一堆 jsonl」變成側欄可管、條目可讀、導出可控的工作流：面板管會話，viewer 與 LLM Dump 頁籤看同一條流，transcript/payload 與「導出本輪」覆蓋日常調試與交接需求。
