## Codex CLI Upgrade Doctor 示例
### 入口
```bash
python tools/codex_cli_upgrade_doctor.py --json
```
### 输入来源
| 检查项 | 命令 | 目的 |
|---|---|---|
| 当前命中路径 | `command -v codex` | 判断 shell 实际运行哪个 codex |
| 全部候选路径 | `command -v -a codex` | 发现 PATH 冲突或旧 shim |
| 当前版本 | `codex --version` | 升级前后核验 |
| npm 来源 | `npm list -g --depth=0 @openai/codex` | 判断是否 npm global 安装 |
| npm 最新版 | `npm view @openai/codex version` | 判断是否可升级 |
| Homebrew 来源 | `brew info --formula --cask codex openai-codex` | 排除或确认 brew 管理 |
### 诊断流程样例
1. 运行 `command -v codex` 得到 `/opt/homebrew/bin/codex`。
2. 对该路径执行 `realpath`，发现它指向 npm global bin，而不是 Homebrew formula。
3. 运行 `codex --version` 得到 `codex-cli 0.125.0`。
4. 运行 `npm list -g --depth=0 @openai/codex`，确认包名是 `@openai/codex`。
5. 运行 `npm view @openai/codex version --fetch-timeout=10000`。
6. 如果返回版本号，例如 `0.126.0`，执行 `npm install -g @openai/codex@latest`，然后重新核验 `codex --version`。
7. 如果返回 DNS/registry 错误，输出失败信号：`remote_version_unavailable`，并建议先检查 npm registry、代理和 DNS，而不是误判为 Homebrew 问题。
### 成功输出
```json
{
"active_path": "/opt/homebrew/bin/codex",
"source": "npm-global",
"package": "@openai/codex",
"before_version": "0.125.0",
"remote_version": "0.126.0",
"upgrade_command": "npm install -g @openai/codex@latest",
"after_version": "0.126.0",
"status": "upgraded"
}
```
### 失败输出
```json
{
"active_path": "/opt/homebrew/bin/codex",
"source": "npm-global",
"before_version": "0.125.0",
"remote_version": null,
"status": "blocked",
"failure_signal": "npm_registry_unreachable",
"next_step": "检查 npm registry、DNS、代理后重试；不要改用 brew，除非 doctor 证明 active path 来自 Homebrew。"
}
```