| name | cli-upgrade |
| description | 通用版本升级对比助手。用于查询任意 CLI 或 App 的最新稳定版本，并与前 3 个稳定版本做更新对比，输出小白可读的大白话总结。适用于用户提到版本升级、release notes、changelog、更新亮点、对比前几个版本等场景；当数据源不明确时，要求用户补充官网或 GitHub 仓库 URL。 |
CLI Upgrade
Overview
- 识别目标工具（如 Codex、Claude Code、Opencode 或其他 CLI/App）。
- 查询最新稳定版与前 3 个稳定版，提炼主要更新并用大白话解释。
Workflow
- 收集输入
- 接收
tool（必填），可选 repo_url、official_url、current_version。
- 未提供 URL 时，先尝试自动解析数据源。
- 确认真实最新版本（关键步骤，不可跳过）
- 绝对不要仅依赖 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/页面返回为准。
- 解析数据源
- 优先用官方源：GitHub Releases、npm、PyPI。
- 自动解析失败时，明确要求用户补充官网或仓库 URL。
- 拉取版本与发布说明
- 默认只看稳定版，过滤
alpha、beta、rc、preview、canary、nightly。
- 取
最新稳定版 + 前 3 个稳定版。
- 逐版本用 WebFetch 抓取 GitHub Release 详情页（如
https://github.com/{owner}/{repo}/releases/tag/v{version}），获取完整 release notes。
- 四个版本的 WebFetch 请求应并行发出，提升效率。
- 生成结果
- 先给一句话总览。
- 按版本用表格输出 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 发版极快（几乎日更），是最容易出现版本滞后问题的工具：
- 用 Homebrew 确认版本：
brew info claude-code --json=v2 获取最新可用版本，claude --version 获取当前已安装版本
- GitHub Releases 是权威详情源：每个版本都有独立的 Release 页面，内容比 CHANGELOG.md 更完整
- 不要用 CHANGELOG.md：更新可能不及时，且格式解析容易丢信息
- 四个版本并行抓取：
WebFetch 四个 release tag 页面同时请求
- 升级命令用 Homebrew：
brew upgrade claude-code（用户通过 Homebrew 管理安装）
Scripts
- 使用
scripts/compare_cli_versions.py 作为统一入口。
- 需要扩展新的平台时，先改
references/provider_registry.yaml，再补 resolve_source.py 与 fetch_releases.py。
Entry Command
python scripts/compare_cli_versions.py \
--tool "codex" \
--output markdown
Optional Arguments
--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：大白话输出模板。
