v0.4.0-zh.md

August 4, 2026 · View on GitHub

v0.4.0 重点解决同步中途失败或意外退出时的数据安全问题：所有写入先备份，失败时回滚，异常退出后保留恢复信息；同时新增了供脚本、持续集成（CI）和 AI Agent 使用的实验性自动化接口。

🚀 升级后，你可以

更放心地同步历史会话：写入前自动创建托管备份；失败或取消时回滚；无法确认操作完整性时不会报告成功。
让脚本或 AI Agent 安全调用同步功能：新的 Windows 自动化接口返回机器可读的 JSON，写操作采用“先生成计划，再明确执行”的两阶段流程。
在不同入口获得一致结果：Windows GUI 与自动化接口使用同一套状态检查、校验、备份、恢复、锁和 WSL 安全规则。

📦 下载

使用场景	下载	更新方式
只需要 Windows GUI	单文件 GUI	支持软件内自动更新
脚本、CI 或 AI Agent	Windows x64 自动化接口包	手动下载更新
GUI 与自动化接口都需要	Windows x64 完整包	手动下载更新

查看全部 SHA-256 校验值

当前 Windows 程序尚未进行代码签名，首次运行可能出现 SmartScreen 的“发布者未知”提示。请确认文件来自本项目 GitHub Release，并按需使用 SHA-256 校验下载内容。

⬆️ 升级说明

v0.3.1 / v0.3.2 Windows GUI 用户可以直接使用内置更新：每天首次启动会自动检查稳定版，也可以点击“检查更新”；确认后会自动下载、校验并重启完成升级。
内置更新只升级 GUI，不会安装 CodexProviderSync.Automation.exe 或协议描述文件。需要自动化接口的用户请手动下载对应 ZIP。
更新后先在 GUI 点击“刷新”；CLI 用户先运行 codex-provider status，确认当前 Provider、Codex Home 和 SQLite Home。
建议在同步、切换或恢复前关闭 Codex Desktop、Codex App 和 app-server，以避免 SQLite 被占用或活跃的 rollout 文件被跳过。

升级程序本身不要求手动迁移配置；v0.4.0 仍可识别旧版托管备份。sync / switch 会在写入前自动创建新备份，不要求另外手动备份。如果结果显示 Skipped locked rollout files，结束对应的活跃会话后再次同步即可。

🛡 安全保障

工具不负责登录、认证或切换账号，也不会修改 auth.json；自动化接口还会拒绝直接访问该文件。
工具只同步会话可见性相关元数据，不改写对话正文、消息历史、会话标题、updated_at 或 encrypted_content。
写操作使用与备份绑定的事务记录和原子文件替换。失败时尝试回滚；如果无法确认回滚完整，会明确提示需要恢复。
恢复到不同的 SQLite Home 默认会被拒绝；Windows 进程也不会通过 WSL UNC 路径直接修改 SQLite。

⚙️ 自动化接口（实验性）

普通桌面用户可以跳过本节，继续使用 GUI 即可。

CodexProviderSync.Automation.exe 主要供脚本、持续集成（CI）和 AI Agent 调用。它返回固定结构的 JSON 和可区分的退出码，外部程序不需要操作 GUI，也不需要另外安装 Node.js。

# 查看接口能力
.\CodexProviderSync.Automation.exe describe

# 只读检查 Codex 状态
.\CodexProviderSync.Automation.exe status --codex-home C:\Users\you\.codex

接口支持 describe、status、plan、sync、switch、restore 和 prune。所有写命令默认只生成计划，不会修改数据；真正执行时必须同时提供 --apply、匹配的计划文件及其 SHA-256 摘要。计划有有效期、绑定目标状态，并且只能使用一次。

该接口不会替代现有 Node CLI。协议 0.4 仍处于 1.0 之前的实验阶段，未来可能发生不兼容变更。完整命令示例见 README，自动化接口包内也附带中文快速说明。

⚠️ 重要说明

\\wsl.localhost\... 和 \\wsl$\... 形式的 SQLite Home 在 Windows 中仅用于安全诊断。请进入对应 WSL 发行版，使用 Linux 路径运行 CLI。
含 encrypted_content 的会话跨 Provider 或账号后，通常只能恢复列表可见性；继续对话或执行 compact 仍可能出现 invalid_encrypted_content。
Codex Desktop 首屏可能只显示最近 50 条会话。本工具不会修改 updated_at 来改变排序。
v0.4.0 的完整发布验证以 Windows 为准；macOS GUI 尚未迁移到这套共享架构。

🔍 验证结果

Core、Application、自动化接口、Windows GUI 和 Node CLI 共通过 500+ 项自动化测试。
发布版真实 EXE 通过 53/53 个必需的可见 Windows GUI 场景，0 项错误、0 项阻断。
发布版本实现零警告、零错误构建，所有发布文件均提供 SHA-256 校验。

完整协议约束、测试计数和审查证据见 v0.4.0 技术发布说明。

查看 v0.3.2 到 v0.4.0 的完整代码变更。

🙏 贡献者

感谢 @Hccake 通过 #55 贡献独立 SQLite Home 支持，并完善桌面端配置、恢复迁移保护、WSL 路径安全检测及相关文档。