---
name: Codex对话状态修复
description: 修复 Codex Desktop 侧栏项目、置顶、session_index、state_5.sqlite、空 rollout 与历史对话可见性。触发词：Codex侧栏修复、Codex对话恢复、Codex项目分类、rollout缺失、state_5.sqlite、session_index、thread-store internal error。
group: 金
triggers: Codex侧栏修复、Codex对话恢复、Codex项目分类、Codex旧对话、Codex置顶、rollout缺失、rollout为空、empty rollout、thread-store internal error、session_index、state_5.sqlite、codex-global-state、repair-backups
owner: 金仓
memory_palace_path: 卡若记忆宫殿/金殿/金仓厢/Codex对话状态修复
memory_palace_slot: Codex 本地对话、项目侧栏和状态库修复入口
version: "2.0"
updated: "2026-07-19"
---

# Codex对话状态修复

> 金仓 · Codex Desktop 本地状态修复入口。只处理 Codex，不优化 Cursor。用于侧栏项目错乱、旧对话缺失、置顶不显示、`thread-store internal error`、空 `rollout-*.jsonl`、`session_index.jsonl` / `state_5.sqlite` / `.codex-global-state.json` 不一致等问题。

## 一句话

先备份，再查 `session_index.jsonl`、`state_5.sqlite`、`.codex-global-state.json`、`process_manager/chat_processes.json` 与 `rollout-*.jsonl`，按“恢复并分类”修复 Codex Desktop 侧栏可用性；历史正文真缺失时只建可读 placeholder，不冒充原始内容。

## 触发场景

| 现象 | 判断 |
|:---|:---|
| 左侧项目下对话丢失、误归类、全部挂到某项目 | 走本 Skill |
| 置顶对话消失或勾选状态不对 | 走本 Skill |
| 打开线程报 `thread-store internal error` | 优先查空 rollout |
| `missing rollout references`、`rollout is empty` | 走补 placeholder / 修索引 |
| 用户说“都恢复并分类，不是隐藏” | 目标是侧栏可用，不是清理坏引用 |

## 红线

- 不删除原始 `rollout-*.jsonl`、`session_index.jsonl`、`state_5.sqlite`、`.codex-global-state.json`。
- 不执行 `git reset --hard`、不清 Time Machine、不删快照。
- 不把 placeholder 说成“恢复原始聊天内容”；只能说“可打开占位”。
- 不把 Cursor 的 `state.vscdb`、`.cursor/rules` 当成修复对象；本 Skill 只管 Codex。

## Phase 0：备份

在第一次改任何 Codex 状态文件前，创建时间戳备份目录：

```bash
ts="$(date +%Y%m%d-%H%M%S)"
backup="/Users/karuo/.codex/repair-backups/${ts}-codex-state-repair"
mkdir -p "$backup"
cp /Users/karuo/.codex/session_index.jsonl "$backup/" 2>/dev/null || true
cp /Users/karuo/.codex/state_5.sqlite "$backup/" 2>/dev/null || true
cp /Users/karuo/.codex/.codex-global-state.json "$backup/" 2>/dev/null || true
cp /Users/karuo/.codex/process_manager/chat_processes.json "$backup/" 2>/dev/null || true
```

## Phase 1：定位真实状态

1. 统计 `session_index.jsonl` 记录数、重复 thread、缺失 rollout、空 rollout。
2. 查 `state_5.sqlite` 里线程、项目、置顶状态与 `session_index.jsonl` 是否一致。
3. 查 `.codex-global-state.json` 是否仍保留旧项目挂载。
4. 查 `process_manager/chat_processes.json` 是否引用已不存在或空 rollout。
5. 写一份报告到备份目录，例如 `codex-state-repair-report.json`。

## Phase 2：修复策略

| 问题 | 动作 |
|:---|:---|
| 缺失 rollout 引用 | 若能从索引或记忆找到摘要，生成 readable placeholder；否则标记不可恢复 |
| 空 `rollout-*.jsonl` | 写入最小有效 JSONL 占位，避免 Desktop 读线程报错 |
| 项目误分类 | 按标题、cwd、首条用户消息、记忆摘要重新分桶 |
| 置顶丢失 | 同步修 `state_5.sqlite` 与 global state 的 pinned/top 字段 |
| 修完仍不显示 | 把重启 Codex Desktop / reload state 作为验收步骤 |

## Phase 3：项目分类建议

优先保留用户真实业务桶：

- 卡若AI / Codex管理
- Soul / SOUL创业派对
- 私域银行 / 存客宝 / 工作手机
- 厦门房产
- 域名注册
- MBTI
- 玩值电竞
- 服务器管理 / NAS
- 个人项目

分类证据优先级：

1. 当前 `cwd`
2. 会话标题
3. 首条用户消息
4. rollout 摘要
5. memory / repair report 中的旧分类记录

## Phase 4：验收

必须至少验证：

- `missing rollout references = 0`
- 空 rollout 已处理或已列入不可恢复清单
- 误挂大项目的对话数量回落到合理范围
- 关键项目侧栏能打开
- 修复报告写入 `/Users/karuo/.codex/repair-backups/`
- 若 Desktop 仍缓存旧状态，明确提示重启 Codex Desktop 再验

## Phase 5：公司 NAS Mongo 全链路备份与跨 Codex 恢复

使用：

```bash
python3 scripts/codex_mongo_backup_restore.py backup
python3 scripts/codex_mongo_backup_restore.py backup --recent-seconds 600 --no-snapshot
python3 scripts/codex_mongo_backup_restore.py stats
python3 scripts/codex_mongo_backup_restore.py restore --output /tmp/codex-restore
python3 scripts/codex_mongo_backup_restore.py restore --project-root "/绝对路径/项目" --output /tmp/codex-restore
```

公司 Mongo 中按以下层级保存：

| Collection | 内容 |
|:---|:---|
| `codex_threads` | thread ID、标题、cwd、项目/工作树、归档状态、模型、Git、rollout 路径 |
| `codex_thread_events` | 完整 JSONL 事件链、顺序号、时间戳、事件类型、原始记录 |
| `codex_event_chunks` | 超过 Mongo 单文档限制的截图/附件事件 gzip 分块 |
| `codex_chat_messages` | 按项目和对话检索的用户/助手正文 |
| `codex_projects` | 项目根、项目名、活跃/归档对话数量 |
| `codex_state_snapshots` / `codex_backup_chunks` | Codex 状态文件可恢复快照 |
| `codex_backup_runs` | 每次备份统计与结果 |

持续同步由 `~/Library/LaunchAgents/com.karuo.codex-mongo-sync.plist` 每 5 分钟执行；
它只扫描最近 10 分钟有变化的线程。首次接入或换机前再执行一次无参数 `backup` 全量收口。

恢复采用两阶段：先导出到独立目录并核对 `manifest.json`，再备份目标 Codex 的
`state_5.sqlite` / global state 后应用；不直接覆盖正在运行的 Codex 状态库。

## 常用证据入口

| 文件/目录 | 用途 |
|:---|:---|
| `/Users/karuo/.codex/session_index.jsonl` | 线程索引 |
| `/Users/karuo/.codex/state_5.sqlite` | Desktop 状态库 |
| `/Users/karuo/.codex/.codex-global-state.json` | 全局侧栏/项目状态 |
| `/Users/karuo/.codex/process_manager/chat_processes.json` | 进程/线程引用 |
| `/Users/karuo/.codex/sessions/` | rollout 真源 |
| `/Users/karuo/.codex/repair-backups/` | 备份与修复报告 |

## 复用过的历史证据

- 2026-07-04：从隐藏缺失 rollout 改为“恢复并分类旧对话”。
- 2026-07-04：空 rollout 引发 `thread-store internal error`。
- 2026-07-05：把误挂在“厦门房产”的约 70 个对话重新拆回 Soul、私域银行、工作手机、域名注册、MBTI、玩值电竞、服务器管理、个人项目等桶。

## 输出格式

交付时用卡若复盘：

- 🎯 目标&结果：修复范围、达成率
- 📌 过程：备份、扫描、修复、验收
- 💡 反思：哪里是不可恢复或需重启
- 📝 总结：修复报告路径
- ▶ 下一步执行：是否需要重启 Desktop、是否需补 Mongo/记忆

## 变更记录

| 日期 | 说明 |
|:---|:---|
| 2026-07-05 | 初版：从近30天 Codex Desktop 侧栏/rollout 修复高复发流程沉淀 |
| 2026-07-19 | v2：增加公司 NAS Mongo 全事件链备份、项目/工作树状态、超大事件分块与跨实例恢复包 |