Codex Session Provider Sync

用于处理 Codex / Codex Desktop 在切换 API provider、使用 CCX、CCSwitch、Codex++、Cockpit Tools 后，会话历史因为 model_provider 不一致而不可见的问题。

核心原则：先只读检测，再确认入口和目标 provider；没有用户确认前不写入会话数据。

适用场景

• 切换 provider 后 Codex 会话列表少了、空了或旧会话不可见
• config.toml、session JSONL、session_index.jsonl、state_5.sqlite 里的 model_provider 不一致
• 同时使用或曾经使用过 CCX、CCSwitch / cc-switch、Codex++、Cockpit Tools、custom provider

安装

把整个目录放到：

~/.codex/skills/Codex-Session-sync

目录至少应包含：

Codex-Session-sync/
├── SKILL.md
├── agents/
│   └── openai.yaml
└── scripts/
    └── detect_provider_tool.py

安装、更新、重命名或从 GitHub 拉取新版本后，请重启 Codex 客户端，让新的 skill 元数据和脚本路径生效。

使用

只读检测：

python3 ~/.codex/skills/Codex-Session-sync/scripts/detect_provider_tool.py

详细诊断：

python3 ~/.codex/skills/Codex-Session-sync/scripts/detect_provider_tool.py --verbose

JSON 输出：

python3 ~/.codex/skills/Codex-Session-sync/scripts/detect_provider_tool.py --json

默认输出只做检测，会明确显示：

Mode: read-only detection only; no files were changed.

如果检测到一个安全目标，下一步会显示 进入修复确认流程。这不等于直接修复；真正写入前仍需要用户确认。

平台路径

检测脚本支持 macOS / Linux / Windows 常见路径。Windows 会额外读取：

• CCX：%APPDATA%\ccx-desktop\agent-config-state\codex.json，以及 MSIX 打包场景的 %LOCALAPPDATA%\Packages\...\LocalCache\Roaming\ccx-desktop\agent-config-state\codex.json
• CCSwitch：用户 Profile 下的 .cc-switch，并兼容旧版在 HOME\.cc-switch 留下的数据库
• Codex++：用户 Profile 下的 .codex-session-delete\settings.json
• Cockpit Tools：用户 Profile 下的 .antigravity_cockpit / .antigravity_cockpit_dev，以及旧版 %APPDATA%\.antigravity_cockpit

如果用户把 Codex home 放在自定义目录、WSL 目录或 Cockpit-managed instance 中，运行检测时应显式传入 --codex-home <path>。

安全规则

• 检测脚本只读，不会修改 ~/.codex、~/.cc-switch、CCX state、Codex++ state 或 Cockpit Tools state
• 多个 provider controller 同时存在时，一律进入 manual-review，禁止自动修复
• CCX + CCSwitch、CCSwitch + Codex++、CCX + Codex++、Cockpit Tools + 任意其他工具 都必须先确认当前实际启动 Codex 的入口
• CCX 需要区分 plugin / quick：plugin 目标可能是 ccx 或第三方 provider，quick 目标通常是 openai
• CCSwitch 不能直接假设是 custom，必须读取 active Codex profile 的 TOML
• Codex++ 不能硬编码为 CodexPlusPlus，当前目标以 config 或 provider-sync 选择为准
• Cockpit-managed home 优先使用 Cockpit Tools 自己的 session visibility repair
• 写入修复前必须先备份，并确认 Codex / provider 切换工具已关闭

备份

本 skill 手动修复前创建的备份路径形如：

~/.codex/session-provider-sync-backup-YYYYMMDD_HHMMSS

备份是回滚点，不是临时垃圾。修复完成后先保留，等重启 Codex 并确认会话可见后，再由用户明确选择是否清理由本 skill 创建的旧备份。

不要自动删除 auth.json 备份，也不要自动删除 CCSwitch、Codex++、Cockpit Tools 自己创建的备份。

验证

开发或更新本 skill 后建议运行：

python3 -m py_compile scripts/detect_provider_tool.py
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py .
python3 scripts/detect_provider_tool.py

运行测试产生的临时目录应在测试结束后删除。