# CLI Upgrade

> 通用版本升级对比助手。用于查询任意 CLI 或 App 的最新稳定版本，并与前 3 个稳定版本做更新对比，输出小白可读的大白话总结。适用于用户提到版本升级、release notes、changelog、更新亮点、对比前几个版本等场景；当数据源不明确时，要求用户补充官网或 GitHub 仓库 URL。

- Skill: `rabbit-ivan/cli-upgrade` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add rabbit-ivan/cli-upgrade`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rabbit-ivan/cli-upgrade/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rabbit-ivan (https://skillmd.com/u/rabbit-ivan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rabbit-ivan/cli-upgrade

---


# CLI Upgrade

## Overview

- 识别目标工具（如 Codex、Claude Code、Opencode 或其他 CLI/App）。
- 查询最新稳定版与前 3 个稳定版，提炼主要更新并用大白话解释。

## Workflow

1. 收集输入
- 接收 `tool`（必填），可选 `repo_url`、`official_url`、`current_version`。
- 未提供 URL 时，先尝试自动解析数据源。

2. 确认真实最新版本（关键步骤，不可跳过）
- **绝对不要仅依赖 WebSearch 返回的版本号**，WebSearch 结果经常滞后。
- 对于 Homebrew 安装的工具（如 Claude Code）：先用 `brew info claude-code --json=v2 | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['formulae'][0]['versions']['stable'])"` 获取 Homebrew 最新稳定版，再用 `claude --version` 获取当前已安装版本。
- 对于 npm 包：用 `npm view <package> versions --json | tail -10` 获取真实版本列表。
- 对于 GitHub 项目：用 `WebFetch` 抓取 `https://github.com/{owner}/{repo}/releases` 页面确认最新版本。
- 多种方式互相印证，以实际 API/页面返回为准。

3. 解析数据源
- 优先用官方源：GitHub Releases、npm、PyPI。
- 自动解析失败时，明确要求用户补充官网或仓库 URL。

4. 拉取版本与发布说明
- 默认只看稳定版，过滤 `alpha`、`beta`、`rc`、`preview`、`canary`、`nightly`。
- 取 `最新稳定版 + 前 3 个稳定版`。
- **逐版本用 WebFetch 抓取 GitHub Release 详情页**（如 `https://github.com/{owner}/{repo}/releases/tag/v{version}`），获取完整 release notes。
- 四个版本的 WebFetch 请求应**并行发出**，提升效率。

5. 生成结果
- 先给一句话总览。
- 按版本用表格输出 2-4 条"你能感知到的变化"（分 新功能 / 体验优化 / 重要修复 / 性能 等类别）。
- 附上官方来源链接与发布日期。

## Output Format

使用以下格式输出：

```
# {tool} CLI 版本更新对比

> **最新稳定版：{version}**（{date} 发布）

## 一句话总览
{summary}

## {version}（最新 · {date}）
| 类别 | 你能感知到的变化 |
|------|-----------------|
| **新功能** | ... |
| **体验优化** | ... |
| **重要修复** | ... |

（每个版本重复上面的表格）

## 升级方式
{install commands}

Sources:
- [link1](url1)
- [link2](url2)
```

## Output Rules

- 保持大白话、短句、避免术语堆叠。
- 每个版本的表格控制在 2-4 行，只挑用户能直观感知的变化。
- 有数据就输出部分结果，并明确说明缺失原因。
- 对"当前版本识别失败"要显式提示，不阻断整体对比。

## Claude Code 特别注意事项

Claude Code 发版极快（几乎日更），是最容易出现版本滞后问题的工具：

1. **用 Homebrew 确认版本**：`brew info claude-code --json=v2` 获取最新可用版本，`claude --version` 获取当前已安装版本
2. **GitHub Releases 是权威详情源**：每个版本都有独立的 Release 页面，内容比 CHANGELOG.md 更完整
3. **不要用 CHANGELOG.md**：更新可能不及时，且格式解析容易丢信息
4. **四个版本并行抓取**：`WebFetch` 四个 release tag 页面同时请求
5. **升级命令用 Homebrew**：`brew upgrade claude-code`（用户通过 Homebrew 管理安装）

## Scripts

- 使用 `scripts/compare_cli_versions.py` 作为统一入口。
- 需要扩展新的平台时，先改 `references/provider_registry.yaml`，再补 `resolve_source.py` 与 `fetch_releases.py`。

### Entry Command

```bash
python scripts/compare_cli_versions.py \
  --tool "codex" \
  --output markdown
```

### Optional Arguments

```bash
--repo-url "https://github.com/openai/codex"
--official-url "https://www.npmjs.com/package/@openai/codex"
--current-version "0.101.0"
--output "json"
```

## References

- `references/provider_registry.yaml`：工具名到官方源的映射。
- `references/source_rules.md`：数据源优先级与降级规则。
- `references/output_template.md`：大白话输出模板。