dsh-session-exporter

dsh 会话内容导出插件，支持将当前会话内容导出为多种格式。

功能特性

• 支持多种导出格式：JSON、JSONL、Markdown、HTML、纯文本
• 支持按会话 ID / 列表序号选择要导出的历史会话（sessionId），并可只列出会话清单
• 支持导出范围控制：最近 N 条（last）或编号区间（from/to）
• 支持自动生成带时间戳的输出文件名（autoName）
• 单文件 10MB 大小上限保护，超出时提示缩小范围
• HTML 支持暗色主题；工具调用/系统消息有独立角色标识
• 可选包含元数据信息
• 可选包含时间戳
• 可选清理敏感信息，且脱敏规则可配置：按名称禁用内置规则、追加自定义正则
• 支持直接输出到文件或返回内容

安装

# 在 dsh 项目根目录安装依赖
cd dsh-session-exporter
pnpm install

使用方法

作为工具使用

// 在代码中调用
const result = await tools.exportSession({
  format: 'markdown',  // json | jsonl | markdown | html | txt
  outputPath: './session.md',
  includeMetadata: true,
  includeTimestamps: true,
  sanitize: true,
  last: 50,            // 只导出最近 50 条（优先于 from/to）
  // from: 0, to: 99,  // 或按消息编号区间导出
  autoName: false,     // 未指定 outputPath 时自动生成带时间戳文件名
  // sessionId: '2',              // 按历史会话 ID / 列表序号 / 唯一 ID 前缀选择
  // listSessions: true,          // 只列会话清单，不导出
  sanitizeDisable: ['email'],     // 放行邮箱，不做脱敏
  sanitizeExtra: [{ pattern: 'ORD-\\d{10}', replacement: '[已清理的订单号]' }]
});

作为命令使用

# 基本用法
/export-session

# 指定格式
/export-session -f json

# 导出到文件
/export-session -f markdown -o ./chat-history.md

# 不包含元数据
/export-session --no-metadata

# 不包含时间戳
/export-session --no-timestamps

# 不清理敏感信息
/export-session --no-sanitize

# 只导出最近 50 条
/export-session --last 50

# 按编号区间导出
/export-session --from 10 --to 30

# 自动生成带时间戳的文件名，如 session-20260904-103000.md
/export-session --auto-name

典型场景

• 归档与复盘：会话结束后导出为 Markdown 归档到项目文档，或定期导出 JSONL 留档，便于后续检索、审计与复盘。
• 团队分享：导出为 HTML（自动适配暗色主题）发给同事，无需对方安装 dsh 即可在浏览器中阅读完整对话。
• 交付与交接：AI 协助完成排障或实现后，把关键对话区间（--from/--to）导出为附件，随工单/PR 一起交付。
• 程序化处理：导出 JSONL 供脚本消费，做统计分析、喂给评测管线或构建训练/测试数据集。
• 仅提取最近上下文：用 --last N 只导出最近 N 条，快速截取当前讨论片段继续加工。
• 脱敏外发：开启 sanitize（默认开启）清理密钥、令牌、邮箱、电话等敏感信息后再分享导出文件。

参数说明

工具参数

| 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | format | string | 否 | 导出格式，可选：json、markdown、html、txt，默认 markdown | | outputPath | string | 否 | 输出文件路径，不指定则返回内容 | | includeMetadata | boolean | 否 | 是否包含元数据信息，默认 true | | includeTimestamps | boolean | 否 | 是否包含时间戳，默认 true | | sanitize | boolean | 否 | 是否清理敏感信息，默认 true | | last | integer | 否 | 仅导出最近 N 条消息，优先于 from/to | | from | integer | 否 | 起始消息编号（含），与 to 配合使用 | | to | integer | 否 | 结束消息编号（含），与 from 配合使用 | | autoName | boolean | 否 | 未指定输出路径时自动生成带时间戳的文件名，默认 false | | sessionId | string | 否 | 要导出的历史会话：完整 ID、列表序号（1 基）或唯一 ID 前缀；不传则导出最近创建的会话 | | listSessions | boolean | 否 | true 时只列出可用会话清单（ID/标题/创建时间/消息数），不导出内容 | | sanitizeDisable | array | 否 | 按名称禁用内置脱敏规则：privateKey、apiKey、openaiKey、jwt、email、phone | | sanitizeExtra | array | 否 | 追加自定义脱敏正则，每项为 { pattern, flags?, replacement?, name? } 或正则字符串 |

命令参数

| 参数 | 简写 | 说明 | |------|------|------| | --format, -f | 导出格式 | | --output, -o | 输出文件路径 | | --no-metadata | 不包含元数据信息 | | --no-timestamps | 不包含时间戳 | | --no-sanitize | 不清理敏感信息 | | --last, -l | 仅导出最近 N 条消息 | | --from | 起始消息编号（含） | | --to | 结束消息编号（含） | | --auto-name | 未指定输出路径时自动生成带时间戳的文件名 | | --session-id | 要导出的历史会话 ID（支持序号或唯一 ID 前缀） | | --list-sessions | 仅列出可用会话清单，不导出内容 | | --sanitize-disable | 按名称禁用内置脱敏规则，多个用逗号分隔 | | --sanitize-extra | 自定义脱敏正则，多个用逗号分隔 |

输出格式

JSON

完整的结构化数据，包含所有会话信息。

JSONL

每行一个 JSON 对象（元数据行 + 消息行），便于程序化处理和流式读取。

Markdown

易读的 Markdown 格式，适合查看和编辑。

HTML

带样式的 HTML 页面，适合浏览器查看，自动适配系统暗色主题。

纯文本

最简单的文本格式，适合日志记录。

元数据信息

包含以下元数据：

• 导出时间
• 用户信息（如果可用）
• 插件版本
• dsh 版本

敏感信息清理

内置规则（name 即用于禁用的标识）：

| 名称 | 清理对象 | |------|----------| | privateKey | PEM 私钥块 | | apiKey | 键值形式的 API 密钥 / 密码 / 令牌 | | openaiKey | OpenAI 风格密钥（sk-...） | | jwt | eyJ 开头的三段式 JWT | | email | 邮箱地址 | | phone | 电话号码 |

规则可配置：

• sanitizeDisable: ['email']：放行指定内置规则（相当于白名单某类字段）
• sanitizeExtra: ['ORD-\\d{10}'] 或 sanitizeExtra: [{ pattern: 'ORD-\\d{10}', replacement: '[已清理的订单号]' }]：追加自定义正则
• 自定义正则不合法或缺少 pattern 时会在导出开始前直接报错，不会产出半成品文件

注意：导出内容上限 10MB，超出时请使用 last 或 from/to 缩小范围。

安全边界

插件在设计与实现上做了多层防护，但仍需了解其能力边界：

• 写入范围限制：所有导出文件的写入路径必须位于 dsh 启动时的当前工作目录（cwd）内，绝对路径或 ../ 形式的越界路径会被拒绝。
• 符号链接防护：对输出目标已存在的祖先目录逐一执行 realpath 校验，防止通过符号链接逃逸工作目录。
• 导出体积上限：单次导出内容上限 10MB，防止意外将超大会话一次性写盘或塞入上下文。
• HTML 转义：导出为 HTML 时对消息内容做转义，防止会话内容注入脚本。
• 敏感信息清理（sanitize，默认开启）：基于正则的脱敏覆盖私钥块、API 密钥、JWT、邮箱、电话等常见模式。注意这是尽力而为的启发式清理，不能保证覆盖所有机密形态；对高敏感会话建议人工复核导出结果，或不要导出。
• 关闭 sanitize 的风险自担：使用 --no-sanitize 导出的内容可能包含明文密钥，请妥善保管，切勿提交到公开仓库。
• 只读会话数据：插件仅读取会话历史用于导出，不修改、不上传任何会话数据；文件只写入本地磁盘。

Roadmap

• [x] 支持导出指定历史会话（按会话 ID / 会话列表选择）——1.3.0 已实现
• [x] 脱敏规则可配置化（自定义正则、白名单字段）——1.3.0 已实现
• [ ] 增加更多导出格式：CSV、PDF
• [ ] 自定义 Markdown / HTML 模板（用户可提供模板文件）
• [ ] 流式写入支持，突破 10MB 上限导出超长会话
• [ ] 导出前 diff 预览 / dry-run 模式

FAQ

Q：导出报错"输出路径必须位于当前工作目录内"怎么办？ A：插件出于安全考虑只允许写入 dsh 启动目录内。请使用相对路径（如 ./out/session.md），或把输出目标移到工作目录内。

Q：导出的消息不全/为空？ A：本插件只导出当前会话。若消息为空，可能是 dsh 版本较旧未提供 session.deriveMessages() 且无旧版 history 回退；请查看导出元数据中的 messagesSource 字段确认消息来源，并升级 dsh 至 0.1.5+。

Q：超过 10MB 无法导出怎么办？ A：用 --last N 或 --from/--to 分段多次导出。

Q：sanitize 开着还是会泄漏敏感信息吗？ A：可能。脱敏基于常见模式的正则匹配，无法覆盖所有机密形态。分享前请人工检查导出文件。

Q：JSON 和 JSONL 该选哪个？ A：需要一次性完整结构选 JSON；需要逐行流式读取、追加写入或程序化处理选 JSONL。

Q：工具调用、系统消息会包含在导出里吗？ A：会。各格式都会保留消息角色（用户/助手/工具/系统），HTML 中有独立角色标识。

Q：发布到 npm 的包和源码是什么关系？ A：本插件是 dsh-plugins monorepo 中的一个子目录，npm 包由该仓库通过 GitHub Action 自动构建发布。

开发

# 安装依赖
pnpm install

# 运行测试
pnpm test

# 语法检查
pnpm check

# 代码检查
pnpm lint

# 代码格式化
pnpm format

版本历史

• 1.3.0：支持按会话 ID / 列表序号 / 唯一 ID 前缀导出指定历史会话，新增 listSessions / --list-sessions 会话清单；脱敏规则可配置（sanitizeDisable 按名禁用、sanitizeExtra 追加自定义正则），非法规则提前报错；元数据新增 sessionId 字段；用户输入类错误不再写入日志。
• 1.2.1：完善 README 文档，新增典型场景、安全边界、Roadmap、FAQ、源码及发布地址章节。
• 1.2.0：适配 dsh harness 0.1.5/0.1.6 新 API——inject 新增 sessions 服务，会话历史改用官方公开的 session.deriveMessages()（同时兼容旧版同步 history 回退）；工具清单优先通过 ctx.tools.schemas() 收集；导出元数据新增 messagesSource 字段标记消息来源，便于诊断。
• 1.1.0：导出范围控制（last / from/to）、自动时间戳文件名、单文件 10MB 上限、脱敏告警。
• 1.0.x：初始版本，五种格式导出。

源码及发布地址

• 源码仓库：https://github.com/geeklei/dsh-plugins（本插件位于 dsh-session-exporter/ 子目录）
• npm 包：https://www.npmjs.com/package/dsh-session-exporter

# 从 npm 安装到 dsh profile
dsh plugin --profile web add dsh-session-exporter

发布流程：仓库内 bump 版本并提交后，推送 dsh-session-exporter@<version> tag 即可触发 GitHub Action 自动发布到 npm。

问题反馈与贡献欢迎提交 Issue 或 Pull Request。

其他插件集成说明

| 协作插件 | 集成方式 | |---|---| | dsh-text-stats | 导出内容可先用 text-stats 统计规模，决定导出范围 | | dsh-workspace-journal | 导出摘要可写入工作区日志，形成会话归档索引 | | dsh-diff-writer | 导出到指定文件时可用 diff-writer 精确写入/更新 | | dsh-table-render | 多会话导出结果可渲染为对齐表格汇总 | | dsh-hash-checksum | 对导出文件计算摘要，确认归档内容完整未被改动 |

许可证

MIT