opencode 会话迁移器 wang-xudong/opencode-dsh-importer

opencode-to-dsh

将 opencode 的会话导出导入到 DeepSeek Harness(DSH)中,成为原生可浏览、可续聊的会话。

它能做什么

- 读取 opencode export 导出的 JSON,生成 DSH 会话日志(session.jsonl.zstd),DSH 可以直接列出、打开、续聊。
- 把用户/助手消息、推理文本、工具调用(调用 + 结果配对)映射为 DSH 的事件溯源日志格式。
- 处理在 opencode 中压缩过(compact)的长会话:自动识别 compaction 标记,只导入最后一次压缩之后的"尾部窗口",并用助手在压缩前自己写的交接总结拼成摘要前缀——让导入后的上下文保持在模型上下文窗口内。
- 可选的五层校验(--validate),直接复用 DSH 自带的读取与校验函数,安装前先把关。

文件说明

| 文件 | 用途 |
| opencode-to-dsh.py | 导入器本体(独立可用,只需 Python 3 + zstd 命令) |
| validate.mjs | 可选质检脚本(五层校验,需要 Node.js + 已安装 DSH) |

环境要求

- Python 3 与 zstd 命令行工具(转换必需)。
- --validate 额外需要 Node.js,且 dsh 在 PATH 中(自动探测;也可用环境变量 DSH_PKG_ROOT 指向 @deepseek-ai/dsh 包目录)。

用自带示例快速上手

full 模式(小会话)
python3 opencode-to-dsh.py examples/sample-full.json ./out --validate

tail 模式(含压缩点的会话,自动识别)
python3 opencode-to-dsh.py examples/sample-compacted.json ./out --validate

两个示例都能通过五层校验;生成的日志在 ./out/sessions/ 下。

用法

仅转换(不校验)
python3 opencode-to-dsh.py 会话导出.json ./out

转换 + 五层校验(安装前推荐)
python3 opencode-to-dsh.py 会话导出.json ./out --validate

参数

| 参数 | 说明 |
| --mode full\|tail\|compact | 导入模式。默认:导出含 compaction 标记则 tail,否则 full。 |
| --sid session-xxx | 固定会话 ID(默认随机)。便于原位替换。 |
| --cwd /path | 覆盖工作目录(默认取导出的 directory,再兜底当前目录)。 |
| --title 标题 | 覆盖会话标题(tail 自动加 "(续聊版)",compact 自动加 "(压缩版)")。 |
| --tz 时区 | 用户消息 source 中的时区(默认自动探测本机)。 |
| --model 模型ID | 覆盖模型标识(默认取导出的 model.id)。 |
| --provider 提供方 | 覆盖 provider 标识(默认 deepseek-official)。 |
| --validate | 转换后运行 validate.mjs(需与本脚本同目录)。 |
| --export-out 路径 | 额外写出过滤后的中间导出 JSON。 |

三种模式

- full:导入全部历史。适合小会话或只读归档。
- tail:用于在 opencode 中压缩过的长会话。找到最后一次压缩的 tail_start_id,只导入其后的消息,并在开头插入一条合成的用户消息,内容为压缩前的助手总结(每个压缩点向前最多 10 条消息内找最近的助手总结文本,每条上限 800 字符)。这复刻了模型在 opencode 中实际看到的上下文,续聊不会撑爆上下文窗口。
- compact:全保真版本——导入全部历史(UI 里可浏览完整记录),并为每个 opencode 压缩点在压缩发生的原位置插入一组与 DSH 原生一致的 compaction 事务:compaction/start → compaction/summary → 携带 surfaceOp: {op: 'replace'} 的 checkpoint user/message → compaction/end,与 dsh-compaction-basic 的事件编排完全一致。每个 checkpoint 阴影掉当时折叠面上的前置节点:模型上下文 = [最后一个摘要 checkpoint + 尾部],UI 转录保留全部消息、每个"上下文已压缩"标记出现在正确位置。摘要优先复用 opencode 自身的相邻摘要消息(## Objective …),老导出无此消息时退化为拼合的压缩前总结;阴影价与 dsh-token-meter 同一定价器,上下文投影恒非负。真实数据(24.7 MB 导出、2,861 条消息、4 次压缩)实测:4 个 checkpoint,派生上下文 10.7 MB → 1.5 MB(13.8%)。

导出格式兼容

按压缩标记自动识别两种 opencode 导出格式:
- opencode 1.17:compaction part 带 tail_start_id(保留窗口首条消息);边界从它开始,忠实于 opencode 的实际保留行为。
- opencode 1.18:无 tail_start_id;标记后的相邻 assistant 消息即真实摘要,尾部从摘要之后开始。

纯压缩标记消息(无文本内容)在所有模式下跳过。

工具名映射

导入时把 opencode 工具名映射为 DSH 命名:websearch → web_search、webfetch → web_fetch、question → ask_user_question、todowrite → todo_write、task → subagent。两侧同名的(read、write、edit、bash、grep、glob 等)原样保留,未知名保持原样。

安装到 DSH

输出目录结构与 DSH 自身存储一致:

/sessions///session.jsonl.zstd

由会话的 cwd 派生(如 /home/user/project → --home-user-project--)。

示例:安装到当前工作区
mkdir -p ~/.dsh/sessions/--home-user-project--/
cp /sessions/--home-user-project--//session.jsonl.zstd \
~/.dsh/sessions/--home-user-project--//

然后重启 dsh web(或刷新浏览器),打开会话即可。会话按 cwd 归入对应工作区;如不在当前工作区,在侧边栏切换即可。

五层校验(validate.mjs)

| 层 | 校验内容 |
| ① loadStored | zstd 解码、header 形状、seq 连续性(DSH 官方 JsonlSessionPersistence) |
| ② adoptSessionEvent | 消息形状:id/role/source/content(DSH 官方校验函数,逐事件调用) |
| ③ foldSurface | surfaceOp 标记与 surface 折叠(DSH 官方函数) |
| ④ 收件箱回放 | agent/inbox/spliced 边界与重复消息 id(镜像 Inbox.apply) |
| ⑤ 派生历史配对 | 每个 tool/result 前必须有携带匹配 tool-call 的助手消息(API 的硬性要求) |

①–③ 直接调用你本机已安装 DSH 包里的真实函数,通过即代表真实加载路径可以接受该日志。

常见问题

| 现象 | 原因 |
| lacks an identified message | 消息事件缺 id/role(本导入器已生成)。 |
| requires a surfaceOp marker | 消息事件缺 surfaceOp(本导入器已生成)。 |
| invalid persisted inbox splice | 收件箱事件删除了从未插入的消息(本导入器成对生成 append + claim)。 |
| Messages with role 'tool' must... | 工具结果没有前置的助手 tool_calls(本导入器已在助手消息中嵌入 tool-call 块)。 |
| maximum context length | full 模式导入超大会话导致超限;改用 tail 模式。 |
| 无法定位 DSH 安装 | dsh 不在 PATH 且未设置 DSH_PKG_ROOT(仅校验时需要)。 |

已知限制

- DSH 会话格式为版本 0,无兼容性承诺;DSH 升级后旧导入可能无法读取,需要重新导出转换。
- 工具卡片只能查看、不能重新执行:opencode 的工具输出以静态结果导入。
- 支持续聊,续聊新产生的事件会追加到导入的日志中,摘要/尾部结构保持不变。
- 未知的 opencode part 类型(如 patch、snapshot)会被跳过,它们不含模型可见内容。

隐私说明

- 不读取、不写入任何凭据、API Key 或配置。
- 路径全部来自导出文件本身,脚本不硬编码任何机器特定信息(工作目录兜底为当前目录,时区自动探测,均可通过参数覆盖)。

致谢

本项目在 DeepSeek Harness(DSH)的智能体会话中,由 DeepSeek 模型协助完成,需求与设计由用户主导。本工具用于将 opencode 的会话导出导入 DSH;opencode 与 DeepSeek Harness 均为 MIT 协议的开源项目。