CodexSessionSync

Codex Session Sync

Codex Session Sync 是一个本地会话同步工具，用来把 OpenAI Codex / Codex CLI 的会话数据在多个 LLM provider 之间同步。它会同时处理 JSONL 会话文件和 state_*.sqlite 索引，让不同 provider 能看到同一批历史会话。

默认操作是 预览，只有勾选确认并执行写入时才会修改文件。写入前可以指定备份目录，工具会先备份 SQLite 和被改动的 JSONL 文件。

该下载哪个版本

所有发布包都面向 Windows x64。AOT 版本不需要安装 .NET 运行时。

版本	推荐场景	发布形态	说明
MewUI	想要最小、最快启动的 Native AOT GUI	CodexSessionSync.MewUI-aot.zip	Aprillz.MewUI + Direct2D，纯 C# Markup，无 XAML，按 full trim 发布。
WinUI 3	想要最接近 Windows 11 的原生体验	CodexSessionSync.WinUI-aot.zip	Windows App SDK + Acrylic + 深浅色切换。必须完整解压后运行，不是单 exe。
Avalonia	想要接近 WinUI 3 的现代界面和较小 AOT 包	CodexSessionSync.Avalonia-aot.zip	基于 FluentAvalonia 的 AppWindow、InfoBar、SettingsExpander、FAComboBox 和 Fluent 风格按钮，并使用 Mica 背景。Windows x64 self-contained Native AOT，需保留 zip 内 native DLL。
WinForms	想要最朴素、直接、兼容性好的 GUI	CodexSessionSync.WinForms-aot.zip	紧凑管理工具窗，self-contained AOT，需保留 zip 内 SQLite native DLL。
WPF UI	想试 lepoco/WPF UI 的 Fluent 控件	CodexSessionSync.Wpf.WpfUi.exe	FluentWindow、TitleBar、Card、InfoBar、ToggleSwitch，self-contained 单文件。
TUI	想在终端或脚本里跑	CodexSessionSync.Tui-aot.zip	Spectre.Console 交互界面，支持交互模式和脚本参数。

WinUI 3 包里的文件都要保留，尤其是 .pri、.mui、WinUI/XAML/Windows App SDK 运行时 DLL。它的 “self-contained” 含义是 不要求目标机器预装 Windows App Runtime，不是 “只有一个 exe”。

功能

• 全供应商互同步：自动发现配置和会话文件里的 provider，让每个 provider 最终看到同一批会话。
• OpenAI 同步到全部：以 openai 或指定 source provider 为源，给其它 provider 创建镜像会话。
• 单目标迁移：把不属于保留 provider 的会话迁移到目标 provider，改写 JSONL 和 SQLite 中的 model_provider。
• 预览优先：默认只报告将要创建、更新、跳过或冲突的项目，不写入。
• SQLite 索引同步：除了 JSONL 文件，也会同步 state_*.sqlite 中的 threads 行和关联索引数据。
• 自动备份：写入前可备份 SQLite 和被修改的 JSONL 文件。
• Codex 运行中可读：读取文件时使用共享读写模式，Codex Desktop 正在运行时也能预览。

各界面特点

MewUI

MewUI 版本使用 Aprillz.MewUI.Windows 和 Direct2D 后端，界面完全由 C# Markup 构建，没有 XAML 或反射绑定。项目按 self-contained Native AOT、TrimMode=full、MewUIBackend=Direct2D 发布，目标是比 WinUI/Avalonia 更轻的现代 GUI。

WinUI 3

WinUI 3 是最偏"原生 Windows 应用"的版本。它使用 Windows App SDK 2.x，带 DesktopAcrylicBackdrop，界面有深色/浅色主题切换，并同步调整窗口标题栏按钮颜色。

Avalonia

Avalonia 版本使用 amwx/FluentAvalonia，应用主题由 FluentAvaloniaTheme 接管，主界面使用 AppWindow、InfoBar、SettingsExpander、FAComboBox 和 Fluent 风格按钮组织，并使用 Mica 背景和顶部深浅色切换。

WinForms

WinForms 版本是轻量 fallback：控件朴素，布局直接，依赖少，self-contained AOT。

WPF UI

WPF UI 版本使用 CodexSessionSync.Wpf.Shared 同步执行层，基于 lepoco/WPF UI 控件库。

TUI

TUI 版本基于 Spectre.Console，适合终端环境、远程桌面、脚本化或快速检查。支持交互模式和 CLI 参数：

CodexSessionSync.Tui.exe --preview
CodexSessionSync.Tui.exe --apply
CodexSessionSync.Tui.exe --preview --mode openai --source openai
CodexSessionSync.Tui.exe --apply --mode migrate --target openai --backup-dir C:\backup

参数	说明
--mode mutual|openai|migrate	选择同步模式
--codex-home <path>	指定 Codex Home
--backup-dir <path>	写入前备份目录
--source <provider>	OpenAI 同步到全部模式的源 provider
--target <provider>	单目标迁移模式的目标 provider

使用方法

GUI

1. 打开任一 GUI 版本，Codex Home 会默认填入 CODEX_HOME 或当前用户的 .codex。
2. 选择同步模式。
3. 点击 预览 查看将要执行的操作。
4. 如果结果没问题，填写或确认备份目录。
5. 勾选 我已备份或确认可以写入，点击 执行写入。

Codex Home 路径

工具按以下顺序检测：

1. 环境变量 CODEX_HOME
2. 当前用户目录下的 .codex

技术细节

核心架构

CodexSessionSync.Core 是纯类库，不依赖任何 UI 框架。所有 7 个界面版本和测试项目都引用同一套同步引擎，行为保持一致。

CodexSessionSync.Core
├── SyncEngine          同步引擎（mutual / openai / migrate 三种模式）
├── ReportFormatter     统一的报告文本渲染
├── TomlParser          轻量 TOML 解析器
├── UuidV5              确定性 UUIDv5 生成
└── Models              数据模型（ConfigStatus, SyncReport, SqliteReport, MigrateResult ...）

核心处理的数据：

• config.toml：解析 provider 配置和默认 provider。
• sessions/**/*.jsonl：读取和写入 Codex 会话事件流。
• state_*.sqlite：同步会话索引，确保 Codex UI 能检索到镜像会话。

关键实现：

• JSONL 使用 System.Text.Json 逐行解析，避免把整份会话文件当普通文本乱改。
• TOML 使用项目内轻量解析器，只覆盖 Codex 配置所需的节、点分键和注释。
• 镜像 ID 使用 UUIDv5 确定性生成：同一个源会话同步到同一个 provider 时会得到稳定 ID。
• 生成的镜像会在 session_meta.payload 中写入 forked_from_id，用于后续反向映射和去重。
• 三种同步模式（mutual / openai / migrate）的执行逻辑和报告渲染全部集中在 Core 中，UI 层只负责参数收集和结果展示。

构建

需要 .NET 10 SDK。

# 构建全部项目
dotnet build CodexSessionSync.sln

# 运行测试
dotnet test CodexSessionSync.Tests

# 一键发布所有变体
.\publish-all.ps1

CI/CD

项目使用 GitHub Actions 自动化：

• push / PR → main：自动构建全部项目 + 运行测试。
• 推送 v* tag：自动执行 publish-all.ps1 并创建 GitHub Release。

发布策略

项目目标是尽量提供"不安装 .NET 运行时即可运行"的 Windows x64 包：

项目	框架	Native AOT	单文件	发布备注
CodexSessionSync.MewUI	Aprillz.MewUI + Direct2D	是	近似	full trim，无 XAML，zip 内包含 exe 和 SQLite native DLL。
CodexSessionSync.Tui	.NET 10 + Spectre.Console	是	近似	zip 内包含 exe 和 SQLite native DLL。
CodexSessionSync.WinForms	Windows Forms	是	近似	使用 partial trim，zip 内包含 exe 和 SQLite native DLL。
CodexSessionSync.Avalonia	Avalonia UI 11	是	否	使用 Fluent 主题和 compiled bindings，Skia/SQLite native DLL 需要 side-by-side 保留。
CodexSessionSync.WinUI	WinUI 3 / Windows App SDK	是	否	self-contained 文件夹包，必须完整解压。
CodexSessionSync.Wpf.WpfUi	WPF + WPF UI	否	是	self-contained 单文件，使用 lepoco/WPF UI 控件。

项目结构

CodexSessionSync.sln             解决方案文件（包含全部项目）
CodexSessionSync.Core/           核心同步引擎 + 报告格式化 + 模型
CodexSessionSync.MewUI/          MewUI 轻量桌面界面
CodexSessionSync.Tui/            终端交互界面
CodexSessionSync.WinForms/       WinForms 桌面界面
CodexSessionSync.Wpf.Shared/     两个 Fluent WPF 版本共享的同步执行层
CodexSessionSync.Wpf.WpfUi/      lepoco/WPF UI 桌面界面
CodexSessionSync.Avalonia/       Avalonia 桌面界面
CodexSessionSync.WinUI/          WinUI 3 桌面界面
CodexSessionSync.Tests/          单元测试（xUnit）
.github/workflows/ci.yml         GitHub Actions CI/CD
publish-all.ps1                  一键发布脚本

核心 API

方法	说明
SyncEngine.DefaultCodexHome()	获取默认 Codex Home 路径
SyncEngine.InspectConfig(path, targetProvider)	解析 Codex 配置
SyncEngine.ResolveStateDb(codexHome, config, explicitPath)	定位 state_*.sqlite
SyncEngine.ResolveConfiguredProviders(config)	读取应参与同步的 provider
SyncEngine.FindMutualSourceSessions(...)	扫描源会话并建立 ID/provider/path 映射
SyncEngine.BuildMutualMirrorPlans(...)	生成镜像计划
SyncEngine.SyncRolloutMirrors(...)	创建或更新 JSONL 镜像文件
SyncEngine.SyncSqliteMirrors(...)	同步 SQLite 索引
SyncEngine.RunMigrate(...)	执行单目标迁移（改写 JSONL + SQLite）
SyncEngine.BackupSqlite(...)	备份 SQLite
SyncEngine.BackupFile(...)	备份 JSONL 文件
ReportFormatter.RenderMutual(...)	渲染全供应商互同步报告
ReportFormatter.RenderOpenAi(...)	渲染 OpenAI 同步报告
ReportFormatter.RenderMigrate(...)	渲染单目标迁移报告
UuidV5.Create(...)	生成确定性 UUIDv5

许可

本项目采用 MIT 许可证 开源。