前言¶
在 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 与「导出本轮」覆盖日常调试与交接需求。
