Codex Session Provider Sync

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

这个仓库是一个 Codex 本地 skill。核心原则是先只读检测当前生效的 provider，再决定是否需要修复；当 CCX、CCSwitch、Codex++、Cockpit Tools 等工具的证据冲突时，默认进入人工确认，不自动写入用户数据。

工作逻辑

1. 用户安装或更新这个 skill 后，先重启 Codex 客户端，让新的 skill 元数据和脚本路径生效。
2. 用户手动激活 skill，或者在“切换 provider 后会话不显示”的场景下触发 skill。
3. skill 先运行只读检测脚本，自动判断当前是 CCX、CCSwitch、Codex++、Cockpit Tools、原生 Codex，还是多个工具冲突。
4. 如果只能得出一个安全目标，skill 会给出对应修复路径；真正写入 session 数据前仍需要用户确认。
5. 如果证据冲突，skill 会优先用 Codex 原生交互让用户选择当前入口；如果当前环境没有交互工具，则退回简短数字选项。
6. 修复后重新验证 JSONL、session_index.jsonl、state_5.sqlite 的 provider 状态，并提醒用户再次重启 Codex 客户端让结果生效。

功能

• 读取 ~/.codex/config.toml 的当前 model_provider
• 统计 session JSONL、session_index.jsonl、state_5.sqlite 中的 provider 分布
• 精细识别 CCX：区分 plugin / quick 模式
• 精细识别 CCSwitch：读取 active Codex provider 的 settings_config.config
• 识别 Codex++ 当前配置和 legacy provider 名称
• 识别 Cockpit Tools：检测 ~/.antigravity_cockpit/codex_instances.json、多实例 Codex home、codex_local_access、cockpit_api、legacy openai_api_key
• 参考各工具原生 session 修复逻辑：检测 CCSwitch 迁移备份、Codex++ provider-sync lock / backup / encrypted_content 风险
• 在冲突时输出 manual-review 和 safeToRepairAutomatically=false

安装

把整个目录放到：

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

目录结构应为：

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

使用

只读检测，默认输出简洁决策卡：

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

安装、更新或重命名这个 skill 后，请重启 Codex 客户端。Codex 通常在客户端 / 会话启动时加载 skill 元数据和路径，重启后新版本的 SKILL.md、description 和脚本路径才最稳妥地生效。

安全约束

检测脚本只读，不会修改 ~/.codex、~/.cc-switch、CCX state 或 Codex++ state。

只有在以下条件满足后，才应该执行修复动作：

• 已备份 ~/.codex/config.toml、auth.json、sessions、session_index.jsonl、state_5.sqlite
• 当前 active provider 已被证明
• 检测输出不是 confidence=manual-review
• 用户确认当前实际使用的工具入口

备份处理

修复过程中的备份不会在修复完成后自动删除。它们是回滚点，不是临时垃圾。

• 本 skill 手动修复前创建的备份放在 ~/.codex/session-provider-sync-backup-YYYYMMDD_HHMMSS
• 修复完成后会显示备份路径，并建议先保留到“重启 Codex 且确认会话可见”之后
• 清理是单独动作，只能清理由本 skill 创建的旧备份，例如 14 天前的 session-provider-sync-backup-*
• 不自动删除 auth.json 备份，也不自动删除 CCSwitch、Codex++、Cockpit Tools 自己创建的备份
• CCSwitch、Codex++、Cockpit Tools 的原生备份继续交给各自工具的保留/清理逻辑管理

重点规则

• 交互优先使用 Codex 原生选择界面；不可用时才退回文本数字卡
• 文本兜底必须短：冲突时只问一个问题，最多给 4 个数字选项，推荐项用 Markdown 加粗，并明确提示“请直接回复数字”
• CCX 不能简单当成 ccx：plugin 模式目标是 ccx，quick 模式目标是 openai
• CCSwitch 不能简单当成 custom：必须解析 active profile 的 Codex TOML
• Codex++ 当前源码把 CodexPlusPlus / CodexPP 当 legacy relay id，不应硬编码为当前目标
• Cockpit Tools 不能当成纯账号管理器：它会写 Codex auth.json / config.toml，有多实例目录和自己的 session visibility repair
• 优先尊重工具自己的 session 修复逻辑；只有原生修复失败、不可用或多工具混用时，才由本 skill 指导人工修复
• 多个工具同时存在且 active target 冲突时，禁止自动修复
• 每次安装或更新本 skill 后，最终步骤都要提醒用户重启 Codex 客户端