codex-thread-path-fix

一键修复 Codex Desktop 因“双路径键不一致”导致的线程消失问题。

语言：

• 中文：当前文档
• English: README.en.md

典型问题：

• 左侧环境显示“无线程”。
• 右侧偶尔还能打开旧 thread。
• /Volumes/... 与 /Users/... 指向同一目录，但被当成不同 cwd 键。

这个工具会在先备份的前提下，统一以下状态：

• ~/.codex/state_5.sqlite 中 threads.cwd
• ~/.codex/.codex-global-state.json 中 workspace roots 索引
• ~/.codex/config.toml 中 projects trust 键
• 可选：对应 rollout 文件首行 session_meta.payload.cwd

详细原理与排障手册见：

• docs/教程_双路径线程消失修复.md

安装要求

• macOS / Linux
• bash
• sqlite3
• jq

快速使用

先预演（不写入）：

./scripts/fix-codex-thread-path.sh \
  --old-path "/Volumes/<disk>/anti coding/getbiji" \
  --new-path "/Users/<username>/anti coding/getbiji" \
  --dry-run

实际修复（自动关闭 Codex.app）：

./scripts/fix-codex-thread-path.sh \
  --old-path "/Volumes/<disk>/anti coding/getbiji" \
  --new-path "/Users/<username>/anti coding/getbiji" \
  --kill-app \
  -y

参数说明

• --old-path: 旧路径键（要迁出的路径）
• --new-path: 新路径键（目标唯一主路径）
• --codex-home: Codex 状态目录，默认 ~/.codex
• --include-rollouts: 修复 rollout 元数据（默认开启）
• --no-include-rollouts: 跳过 rollout 修复
• --replace-global-text: 将 .codex-global-state.json 内所有字符串中的旧路径替换为新路径
• --kill-app: 发现 Codex.app 进程时自动结束
• --dry-run: 只显示计划与统计，不写入
• -y, --yes: 跳过交互确认

为什么要修 rollout

很多场景下，只改三件套仍会出现：

• state_5.sqlite 看起来已正确
• 但 UI 仍“无线程”

这是因为某些版本会按 rollout 首行 session_meta.cwd 参与环境过滤。
所以本工具默认也会修这一层。

安全性

• 默认要求你先关闭 Codex.app（或使用 --kill-app）。
• 每次执行都会生成时间戳备份目录：~/.codex/backups/<timestamp>-codex-path-fix
• 若无法从旧/新项目块解析 trust_level，脚本会使用安全默认值 untrusted（避免意外提权）。
• 备份包含：
  • state_5.sqlite
  • .codex-global-state.json
  • config.toml
  • 被改动的 rollout 文件（如开启 rollout 修复）

回滚

修复后若不满意，停止 Codex.app 后从备份恢复：

BK="$HOME/.codex/backups/<your-backup-dir>"
cp "$BK/state_5.sqlite" "$HOME/.codex/state_5.sqlite"
cp "$BK/.codex-global-state.json" "$HOME/.codex/.codex-global-state.json"
cp "$BK/config.toml" "$HOME/.codex/config.toml"

如果也修过 rollout，则把 "$BK/rollouts" 中对应文件覆盖回原路径。

测试

bash -n ./scripts/fix-codex-thread-path.sh
bash -n ./tests/smoke.sh
./tests/smoke.sh

开源协作与发布

• 贡献指南：CONTRIBUTING.md
• 行为准则：CODE_OF_CONDUCT.md
• 安全策略：SECURITY.md
• 变更记录：CHANGELOG.md
• 发布清单：docs/RELEASE_CHECKLIST.md
• Issue/PR 模板：.github/ISSUE_TEMPLATE/*、.github/pull_request_template.md

发布建议

你可以直接将该目录初始化为 GitHub 仓库：

git init
git add .
git commit -m "feat: add codex thread path fix tool"