历史会话导入器 fakeppa/dsh-history-importer

wb2dsh

把 WorkBuddy（CN / 国际版）与 Claude Code 的聊天记录导入 DeepSeek Harness (DSH) 会话库，生成 DSH 原生 v4 会话：列表可见、点开即显示完整对话。

零依赖 · 只需 Node.js · MIT

语言 / Language: 中文 · English

简介

wb2dsh 把不同 Agent 工具里「聊天流水账」式的历史，翻译成 DSH 的「只追加事件日志」，从而在 DSH 里像原生会话一样浏览、回放。

支持来源（三者同源，都是 Claude-Code 系 JSONL）：

- WorkBuddy：~/.workbuddy/projects
- WorkBuddy AI（国际版）：~/.workbuddy-ai/projects
- Claude Code：~/.claude/projects

原理

WorkBuddy / Claude Code / DSH 都以「每行一个 JSON」记录对话，但结构不同：

- WorkBuddy / Claude Code：按项目文件夹存放，一行一条记录（用户消息 / 助手消息 / 一次工具调用 / 一次工具结果），像聊天流水账。
- DSH：每个会话是一份只追加的事件日志（v4），zstd 压缩，放在由「工作目录 + 会话 ID」算出的固定路径下；界面里的对话是从这份日志「折叠」出来的。

工具分四步翻译：

1. 读取：扫描各来源 .jsonl，逐行还原出真实工作目录（cwd）、标题，以及「用户 / 助手 / 工具调用 / 工具结果」的顺序内容。
2. 归并：同侧连续片段合成「一条消息」，再把「用户消息 + 随后助手回复」配成一轮。
3. 生成：写出 DSH 事件——会话头 → 权限/沙箱/模型前置 → 每一轮（turn/start → user/message → step/start → assistant/message → step/end → turn/end）→ 会话标题。工具调用/结果转成可读文字块，保证干净渲染。
4. 落盘 + 登记：压成多帧 zstd（第 0 帧只放一行会话头，后续帧放事件），写入 <dsh>/sessions/<projectKey(cwd)>/session-<id>/session.v4.jsonl.zstd，并在 <dsh>/storages/workspace.json 登记「工作区 → 会话」。

路径命名、分帧、surfaceOp、turn/end reason 等细节由工具自动处理，你无需手动修改。

为什么能放心重跑：目标会话 ID 是确定性算出的（来源 + 原文件 ID + 工作目录），同一源永远落到同一目标文件，已存在就跳过；导入前自动备份 .dsh。

从零上手教程（WorkBuddy → DSH）

0. 准备：Node.js ≥ 22.15（node -v 确认）；本机有 WorkBuddy 历史；已安装 DSH（默认 ~/.dsh）。

1. 拿到项目：把 dsh-history-importer 放到任意目录，无需 npm install（零依赖）。

2. 关掉 DSH：关闭运行 DSH 的黑色命令行窗口（dsh-web.bat）。工具会自检，检测到在跑会拒绝执行。

3. 先预演（建议）：

node bin/wb2dsh.mjs --dry-run

打印来源、会话数、将创建的工作区数——不写任何东西。

4. 正式导入：

node bin/wb2dsh.mjs

自动：备份 .dsh → 写入会话 → 登记工作区 → 打印汇总（scan / written / skipped / failed / workspaces）。

5. 重开 DSH 看效果：双击 dsh-web.bat，浏览器打开 http://localhost:3080，左侧出现工作区与会话，点开即完整对话。

6. 常用参数

| 场景 | 命令 |
| DSH 不在默认位置 | --dsh-home "D:/my/.dsh" |
| 只导 Claude Code 历史 | --sources "claude-code:C:/Users/你/.claude/projects" |
| 指定模型标识 | --provider makie --model global:deepseek-v4.1-flash |
| 不想自动备份 | --no-backup |
| DSH 停不下来硬写 | --force（写完仍需重启 DSH 才可见） |

7. 出问题

| 现象 | 处理 |
| 提示 "DSH appears to be running" | 先关 DSH，或加 --force |
| 数字对不上 | --dry-run 看哪个来源缺失，确认目录存在 |
| 导入后没变化 | 确认重启了 DSH（它只在启动时读 workspace.json） |
| 想撤回 | 从 .dsh/backups/wb2dsh-/ 恢复 sessions 与 storages |

命令行选项

| 选项 | 说明 |
| --dsh-home <dir> | DSH 配置目录（默认 ~/.dsh） |
| --sources <list> | id:dir 逗号分隔，默认三家来源 |
| --provider <id> / --model <id> | 记录到日志里的模型标识 |
| --dry-run | 只扫描，不写任何东西 |
| --no-backup | 跳过自动备份 |
| --force | DSH 在跑时仍继续 |
| --list-sources | 打印解析到的来源目录 |
| --help / --version | 帮助 / 版本 |

安全性

- 幂等：重跑只补缺失，不重复、不覆盖。
- 导入前自动备份 .dsh（sessions + storages）。
- 不修改任何源文件，只往 DSH 库里新增。
- 检测到 DSH 运行时会拒绝（除非 --force）。

目录结构

bin/wb2dsh.mjs CLI 入口 lib/format.mjs DSH v4 会话构建（事件流、projectKey、多帧 zstd） lib/parse.mjs WorkBuddy + Claude Code JSONL 解析 lib/workspace.mjs workspace.json 登记 + 备份 / 运行检测 docs/FORMAT.md 产出的 DSH 会话格式规范 docs/GETTING-STARTED.md 原理与上手教程 README.md package.json 零依赖，Node ≥ 22.15，MIT

概览

wb2dsh 把其他智能体工具使用的「聊天记录」历史转换成 DSH 的只追加事件日志，导入后的会话与 DSH 原生会话表现一致——出现在侧边栏、能打开、能完整渲染对话。

支持的来源（都沿用 Claude Code 的 JSONL 血统）：

- WorkBuddy：~/.workbuddy/projects
- WorkBuddy AI（国际版）：~/.workbuddy-ai/projects
- Claude Code：~/.claude/projects

工作原理

WorkBuddy / Claude Code / DSH 都把对话记成「一行一条 JSON」，但结构不同：

- WorkBuddy / Claude Code：每个项目文件夹一个文件，一行一条记录（用户消息 / 助手消息 / 工具调用 / 工具结果）——一份聊天记录。
- DSH：每个会话是一份只追加事件日志（v4），zstd 压缩，路径由工作目录 + 会话 id 推导；界面里的对话视图就是从这份日志折叠出来的。

工具分四步转换：

1. 读取每个源 .jsonl，还原真实工作目录（cwd）、标题，以及有序内容（用户 / 助手 / 工具调用 / 工具结果）。
2. 合并连续的同侧片段为一条消息，再把「用户消息 + 紧随其后的助手回复」配成一个轮次。
3. 构建 DSH 事件——会话头 → 权限/沙箱/模型前导 → 每个轮次（turn/start → user/message → step/start → assistant/message → step/end → turn/end）→ 会话标题。工具调用/结果转成可读文本块，让对话渲染干净。
4. 存储 + 登记：压缩成多帧 zstd（第 0 帧 = 头行，后续帧 = 事件），写入
<dsh>/sessions/<projectKey(cwd)>/session-<id>/session.v4.jsonl.zstd，并在 <dsh>/storages/workspace.json 里登记「工作区 → 会话」。

路径命名、分帧、surfaceOp、turn/end reason 等细节都会自动处理——你永远不用手动改。

为什么重跑是安全的：目标会话 id 是确定性的（由源 + 原文件 id + 工作目录推导），所以同一个源会话永远映射到同一个目标文件，已存在就跳过。.dsh 会先备份。

上手（WorkBuddy → DSH）

0. 前置条件：Node.js ≥ 22.15（node -v）；本地有 WorkBuddy 历史；已安装 DSH（默认 ~/.dsh）。

1. 获取项目：把 dsh-history-importer 放到任意位置。不用 npm install（零依赖）。
2. 停止 DSH：关闭运行 DSH 的控制台窗口（dsh-web.bat）。工具还会自检，DSH 正在监听时拒绝运行。

3. 试运行（推荐）：

node bin/wb2dsh.mjs --dry-run

打印来源、会话数量和将要创建的工作区 —— 不写入任何内容。

4. 导入：

node bin/wb2dsh.mjs

备份 .dsh，写入会话，注册工作区，然后打印摘要（扫描 / 写入 / 跳过 / 失败 / 工作区）。

5. 重新打开 DSH：启动 dsh-web.bat，打开 http://localhost:3080；工作区和会话显示在左侧 —— 点击即可查看完整对话。

6. 常用选项

| 场景 | 命令 |
| DSH 不在默认位置 | --dsh-home "D:/my/.dsh" |
| 只导入 Claude Code 历史 | --sources "claude-code:C:/Users/you/.claude/projects" |
| 设置模型标识 | --provider makie --model global:deepseek-v4.1-flash |
| 跳过自动备份 | --no-backup |
| DSH 运行时强制执行 | --force（之后重启 DSH 才能看到变化） |

7. 故障排查

| 现象 | 处理 |
| 「DSH appears to be running」 | 先停止 DSH，或传入 --force |
| 计数不对 | 运行 --dry-run；检查缺失的来源目录是否存在 |
| 导入后没有变化 | 确认重启了 DSH（它只在启动时读取 workspace.json） |
| 回滚 | 从 .dsh/backups/wb2dsh-/ 恢复 sessions 和 storages |

命令行选项

| 选项 | 说明 |
| --dsh-home <dir> | DSH 主目录（默认 ~/.dsh） |
| --sources <list> | 逗号分隔的 id:dir 对（默认：上面三个来源） |
| --provider <id> / --model <id> | 记录到日志里的模型标识 |
| --dry-run | 只扫描，不写入 |
| --no-backup | 跳过自动备份 |
| --force | DSH 运行时也继续 |
| --list-sources | 打印解析后的来源根目录并退出 |
| --help / --version | 帮助 / 版本 |

安全

- 幂等：重复运行只补缺口，绝不重复或覆盖。
- 写入前自动备份 .dsh（sessions + storages）。
- 绝不修改来源文件；导入只向 DSH 库添加内容。
- DSH 正在监听时拒绝运行（除非 --force）。

目录结构

bin/wb2dsh.mjs CLI entry
lib/format.mjs DSH v4 builder (events, projectKey, multi-frame zstd)
lib/parse.mjs WorkBuddy + Claude Code JSONL parsers
lib/workspace.mjs workspace.json registry + backup / running checks
docs/FORMAT.md on-disk format emitted by this tool
docs/GETTING-STARTED.md principles and step-by-step guide
README.md
package.json zero dependencies, Node ≥ 22.15, MIT

许可证

MIT