6.7 KiB
description, kind
| description | kind |
|---|---|
| 面向 Web bundle 用户的会话日志导出：Session Header 下载按钮与 /export 命令，以及下载弹窗的预期行为。 | package-reference |
@deepseek-ai/dsh-session-log-export
English | 中文
概述
dsh-session-log-export 让 Web 界面可以下载会话的完整历史：Session Header 中的 Session log 按钮与 /export 斜杠命令都会把会话树——会话本身、其子会话与附件——作为 ZIP 交给浏览器下载。一个小弹窗报告准备中、开始下载或失败，按钮与命令共用该弹窗。ZIP 由 dsh-host-apiproxy 生成并流式传输；本包只提供浏览器侧的按钮与命令。下载是浏览器下载：目标位置由浏览器选择。设置与用法在前；实现内部细节放在下方可折叠的开发者章节中。
目录
使用本包
当 Web bundle 需要让用户导出会话日志时使用本包。它只由 Web bundle 挂载，与 Host API 代理、命令注册表和对话 UI 并列。常用路径是：挂载插件，然后点击 Session Header 中的 Session log 或输入 /export——浏览器下载 dsh-session-<id>.zip。
何时选择
为需要带可见下载弹窗的用户级会话导出的 Web 部署选择它。需要程序化或 Host 侧导出时避免使用：本包产生的是浏览器下载，而非 Host 路径写入，并且它要求持久化后端保存逐会话原始产物（随附 JSONL 后端支持明文与 zstd；不支持 SQLite 导出）。
组合
- id: session-log-download
name: '@deepseek-ai/dsh-session-log-export'
Web bundle 将本包与 dsh-host-apiproxy、dsh-commands、dsh-client-ui-commands 和 dsh-client-ui-conversation 一起挂载。
命令约定
| 输入 | 结果 |
|---|---|
/export |
记录一组用户命令生命周期；提交命令的浏览器下载 GET /api/session.export?sessionId=<id>&includeDescendants=true |
/export <path> |
错误；浏览器下载通过浏览器的普通下载行为选择目标位置 |
预期行为
弹窗报告三个阶段：准备中、开始下载或失败。关闭弹窗不会取消正在进行的下载，该操作随后完成时弹窗也不会重新打开。每个会话同时只允许一项下载，重复操作共用该任务。导出包含实时会话的最新事件：Host 端点在读取前会 flush 活动的根会话，因此斜杠命令触发的 ZIP 会包含启动下载的 command/run 与 command/done 事件对；冷持久化会话不需要 flush。
失败
当 ZIP 流式传输开始前的预检失败时——例如 Host 端点不可达或配置错误——弹窗显示准备阶段错误。浏览器接受 GET 后发生的子会话或附件读取失败由浏览器下载管理器报告，不通过弹窗报告。
理解实现
实现细节——点击展开
本节解释本包如何接线导出控制，并指出实现它的代码位置；可观察行为已在使用本包中完整说明。
设计拆分
本包有两个半包。Host 半包（src/index.ts）在 ctx.commands 上注册 /export 命令；浏览器半包（src/client/index.ts）提供 SessionLogDownloadController，把 Header 按钮与共享弹窗贡献到 conversation.session.header.utilities slot，并观察 command/executed，使提交命令的浏览器在 /export 成功后启动同一下载。其他标签页仍渲染持久命令行，但不会重复浏览器副作用。
下载流程
两条入口都会对 GET /api/session.export?... 发出 HEAD 预检，然后把 GET URL 交给浏览器下载管理器，JavaScript 不缓冲 ZIP。一个控制器按会话持有一项进行中的下载，把并发操作折叠进该任务，并在插件释放时取消预检。弹窗状态存放在按会话键控的快照存储中，因此按钮与命令按会话共享一个弹窗。
Host 下载端点由 dsh-host-apiproxy 拥有：它在 readRaw 前 flush 活动的根会话并流式传输 ZIP；ZIP 生成、原始 JSONL/zstd 读取、子会话、附件、背压与 HTTP 错误语义都属于那里。
进一步探索
当包级约定不够用时阅读以下页面。它们从 Web 控制逐步进入 Host 端点与周围的命令和会话表面。
- dsh-host-apiproxy——本包驱动的 Host 流式 ZIP 下载端点。
- 命令子系统参考——
/export命令注册的用户命令注册表。 - dsh-client-ui-commands——渲染并确认
/export的浏览器命令表面。 - 会话查询包映射——本包所属的检索能力家族。
模型体验
用户 /export 控制
模型看到什么
无。/export 留在用户命令平面，ZIP 下载不会进入模型历史。
Token 影响
为零。该命令不创建模型轮次。
KV Cache 影响
无。仅日志命令生命周期与浏览器下载不会改变派生请求前缀。
已知限制与延期工作
这些限制说明本包何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是任务积压。
- 要求逐会话原始产物后端——下载端点需要带逐会话原始产物的持久化后端；随附 JSONL 后端支持明文与 zstd，不支持 SQLite 导出。
- 浏览器下载，而非 Host 路径写入——目标位置由浏览器选择；不会返回 Host 路径或原生文件夹操作。
- 预检只报告流式传输前的失败——浏览器接受 GET 后发生的子会话或附件读取失败由浏览器下载管理器报告，不通过弹窗报告。
开发备注
维护者的工作上下文——点击展开
本开发备注是维护者的工作上下文：开放设计问题与尚未决定的探索方向。它明确不具权威性——已交付的行为、限制与既定理由以上文、包代码和相关页面为准。
未来：浏览器之外的导出目标
下载刻意限定在浏览器范围；Host 路径或原生文件夹导出需要新的端点约定，并决定 ZIP 的落盘位置。