Codex 迁移桥 polarskicpl/dsh-codex-migrate

dsh-codex-migrate

在 Codex 与 DeepSeek Harness 之间进行可预测的单向结构化迁移 English · 中文

v2.0 将插件从“导出工具”升级为双端迁移桥：既可以把 Codex 对话导入 DSH，也可以从 DSH 把单个对话或整个项目的对话批量导入 Codex。每次操作都是明确的一次性迁移，不在后台修改源对话。

v2.0.4 兼容性更新

dsh-codex-migrate@2.0.4 延续了 v2.0.3 已实现的兼容修复，并针对公开 npm 的 @deepseek-ai/dsh@0.1.5-rc.2 验证（截至 2026-09-23 为 latest）。这些修复解决了 DSH 新版会话持久化与 Web 客户端模块变化带来的兼容问题：

- Codex → DSH：通过具有生命周期的 SessionHandle API 写入有效的 Session V3 事件，并正确执行 flush/close；旧版持久化服务仍有兼容回退。
- DSH Web 界面：更新客户端注入模块；“在 Codex 继续”改用当前对话的 session ID；限制清单扫描的元数据读取量，并异步读取完整对话，减少大历史记录造成的卡顿。
- DSH → Codex：浏览器拦截 codex:// 时，通过操作系统打开已导入的任务，同时保留浏览器跳转作为回退。

本版本不声明支持 DSH 的 npm next 或 alpha 渠道。版本记录见变更日志。

v2.0 新增内容

- 双向单次导入：Codex → DSH 与 DSH → Codex 都会转换为目标端支持的结构化会话格式，而不是简单拼接纯文本。
- 在 Codex 继续：DSH 回复下方新增原生 Codex 图标；点击后导入当前对话，并自动打开新建的 Codex 任务。
- 在 DSH 继续：安装配套 MCP 与 continue-in-dsh Skill 后，在 Codex 里说“在 DSH 继续”即可导入当前任务并打开 DSH。
- 按照项目批量迁移：一次导入某个 DSH 项目内的全部未归档对话，并为每个 Codex 任务沿用原工作区路径。
- 无项目对话支持：Codex 中没有项目归属的对话也能导入 DSH，统一显示在 (no project) / codex-unprojected 工作区。
- MCP 记忆 Beta：新增 remember_memory、search_memory、forget_memory，支持全局、项目和单对话范围的本地持久记忆。
- 三类记忆导入：可以分别选择 Codex Markdown 记忆、桥接 MCP 记忆和 Memory Skill 存储。
- 更快的清单刷新：会话清单使用增量缓存，只重新解析新增或发生变化的文件；损坏文件会被单独隔离。
- 重新设计的设置界面：简化卡片层级、列表和状态信息，修复语言切换，并统一按钮、徽标与深浅色样式。

功能入口

在 DSH 的助手回复下方，Codex 图标与复制、点赞等原生操作位于同一行：

- 点击 Codex 图标：将这一条 DSH 对话导入 Codex 并跳转。
- 打开 设置 → Codex 迁移 → 按照项目批量迁移：批量导入项目内全部未归档对话。
- 在 Codex 中说 “在 DSH 继续”：将当前 Codex 任务导入 DSH 并跳转。

v2.0 不提供共享对话、后台双向同步、冲突合并或 Codex 内联监视面板。目标是让每次迁移可检查、可重复、不会在两端静默改写同一段历史。

安装：两端都需要配置

完整功能由两个本地组件组成：

| 组件 | 安装位置 | 作用 |
| dsh-codex-migrate | DSH | 读取、转换和创建 DSH/Codex 会话；提供仅监听本机的一次性交接服务 |
| dsh-codex-bridge MCP + Skill | Codex | 提供“在 DSH 继续”、MCP 记忆工具和触发规则 |

只安装 DSH 插件仍可使用设置页导入以及 DSH → Codex 按钮；若要从 Codex 发起迁移或使用 MCP 记忆，必须继续完成 Codex 侧安装。

前置要求

- 已安装并可启动 DeepSeek Harness（DSH）。
- 已安装 Codex 桌面端、Codex CLI 或 IDE 扩展。
- node 可在终端运行；建议 Node.js 18 或更高版本。
- 以下命令默认使用 DSH 的 web profile；如你的 profile 名称不同，请替换 web。

第 1 步：安装 DSH 插件

首次安装：

dsh plugin --profile web add dsh-codex-migrate

从旧版升级：

dsh plugin --profile web update dsh-codex-migrate

完成后重启 DSH，打开 设置 → Codex 迁移。确认能看到 已导入的对话、按照项目批量迁移 和 记忆导入。

第 2 步：取得 Codex 配套组件

Codex MCP 与 Skill 位于同一个仓库中，因此需要保留本地仓库目录：

git clone https://github.com/polarskicpl/dsh-codex-migrate.git
cd dsh-codex-migrate

如果你已经克隆了仓库，执行 git pull 更新即可。

第 3 步：在 Codex 注册 MCP

Windows PowerShell：

$bridge = (Resolve-Path ".\codex\dsh-codex-bridge\mcp\server.mjs").Path
codex mcp add dshCodexBridge -- node $bridge --stdio

macOS / Linux：

bridge="$(pwd)/codex/dsh-codex-bridge/mcp/server.mjs"
codex mcp add dshCodexBridge -- node "$bridge" --stdio

如果此前已用其他路径注册过同名 MCP，先执行：

codex mcp remove dshCodexBridge

然后重新运行上面的 add 命令。可用以下命令确认注册结果：

codex mcp list

Codex 官方也允许直接编辑 ~/.codex/config.toml；CLI 注册方式更不容易出现路径和 TOML 转义问题。参见 Codex MCP 文档。

第 4 步：安装 continue-in-dsh Skill

Windows PowerShell：

$skills = Join-Path $HOME ".agents\skills"
New-Item -ItemType Directory -Force -Path $skills | Out-Null
Copy-Item -Recurse -Force ".\codex\dsh-codex-bridge\skills\continue-in-dsh" $skills

macOS / Linux：

mkdir -p ~/.agents/skills
cp -R ./codex/dsh-codex-bridge/skills/continue-in-dsh ~/.agents/skills/

Codex 会从 ~/.agents/skills 读取用户级 Skill。若更新后没有立即出现，重启 Codex。参见 Codex Skill 文档。

第 5 步：重启并验证

1. 启动 DSH，并保持迁移插件启用。
2. 重启 Codex，在 /mcp 中确认 dshCodexBridge 已连接。
3. 在 /skills 中确认可以看到 continue-in-dsh。
4. 新建一个 Codex 测试任务，输入：在 DSH 继续。
5. 成功时会打开对应的 DSH 对话，Agent 固定回复：已同步对话到 DSH。

MCP 应暴露四个工具：

| 工具 | 作用 |
| continue_in_dsh | 一次性导入当前 Codex 任务并打开 DSH |
| remember_memory | 保存本地持久记忆 |
| search_memory | 检索指定范围内的记忆 |
| forget_memory | 按 ID 删除记忆 |

快速测试 MCP 记忆 Beta

1. 在一个 Codex 任务中输入：请通过 DSH MCP 记住：我的测试代号是海蓝-728。
2. 新建另一个 Codex 任务，输入：请搜索 DSH MCP 记忆，告诉我测试代号。
3. 确认回答为 海蓝-728 后，输入：请从 DSH MCP 记忆中删除海蓝-728。

记忆默认保存在 ~/.codex/dsh-codex-bridge/memory.jsonl，不会上传到远端，也不会恢复已经废弃的共享会话功能。

迁移内容

| 内容 | Codex → DSH | DSH → Codex |
| 用户与助手消息 | ✓ | ✓ |
| 工具调用与工具结果 | ✓ | ✓ |
| 最新一次重新生成的回复 | ✓ | ✓ |
| 单个对话 | ✓ | ✓ |
| 无项目对话 | ✓ | — |
| 按项目批量导入 | ✓ | ✓ |
| AGENTS.md 与项目文本 | 可选 | — |
| Codex / MCP / Memory Skill 记忆 | 可选 | — |

DSH → Codex 使用 Codex 支持的外部 Agent 会话导入路径。批量迁移会为每个任务使用同一个原始工作区路径，但 Codex 侧栏如何归类由 Codex 自身决定。

加载速度优化

首次刷新需要扫描现有 Codex 会话。之后的刷新会复用 size + mtime + hash 增量缓存，只解析新增或变化的 JSONL 文件，并从缓存移除已经删除的文件，因此大型会话目录的重复刷新更快、更稳定。

缓存位于迁移输出目录下的 inventory/，删除缓存只会触发一次完整重建，不会删除原始对话。

主要配置

| 键 | 默认 | 含义 |
| codexDir | '' | Codex 数据目录；留空自动检测 ~/.codex |
| outputDir | '' | 迁移产物目录；留空使用 /codex-sync |
| language | en | en、zh 或跟随界面的 auto |
| sessionMode | new | all、new 或 selected |
| projectMode | all | all 或 selected |
| includeMemories | true | 导入 Codex Markdown 记忆 |
| includeMcpMemories | true | 导入桥接 MCP 持久记忆（Beta） |
| includeMemorySkill | true | 导入 Memory Skill 存储 |
| importAsDshSessions | true | 创建可在 DSH 侧栏打开的原生会话 |
| bridgeEnabled | true | 启用仅监听 127.0.0.1 的一次性交接服务 |

安全边界

- DSH 交接服务仅监听 127.0.0.1。
- 写操作需要安装令牌；令牌不会写入 README 或仓库。
- 关闭 DSH 插件会同时关闭交接服务。
- MCP 记忆保存在本机；不会自动发送原始项目文件或完整对话到第三方服务。
- 插件只写配置的 outputDir、DSH 会话存储以及本地 MCP 记忆文件。

开发与发布检查

npm run build
npm test
npm run test:bridge
npm pack --dry-run

更新历史见 CHANGELOG.md。

MIT