用途
claude-model-upgrade 用于在 Claude 发布新模型后,系统性地查找并升级过时的 Claude 模型 ID。它面向技能、智能体、命令、提示词、模板、配置文件和运行时代码等会“决定使用哪个模型”的位置,避免旧 ID 继续被使用。整个过程强调可重复:查询当前模型、只读扫描、报告、询问授权、编辑、提交。
主要能力
- 查询当前模型:通过 WebFetch 获取 Claude 官方模型总览页和模型 ID 格式规则页,确定每个模型系列(Fable、Opus、Sonnet、Haiku)当前的 API ID。
- 只读扫描:对每个模型系列运行一次扫描脚本,输出
scan-<family>.tsv,并统计 TARGET 数量。扫描依赖 ripgrep(rg),使用uv run执行。 - 区分 RECORD 与 TARGET:RECORD 类(变更日志、发布说明、日志、会话存储、备份归档、缓存、遥测快照、生成报告、会自行更新的第三方目录)永不改写;TARGET 类(技能、智能体、命令、提示词、模板、示例、集成文档、运行时默认值、配置文件、docker-compose.yml、环境模板、测试夹具)才是编辑候选。
- 可扩展排除规则:可在
~/.config/claude-model-upgrade/ignore中按行添加路径正则,或用--ignore-file指定;也可用--exclude GLOB整棵跳过目录。 - 报告与审批门:以表格输出各系列当前 ID、发现的过时变体、待编辑文件、跳过文件;按仓库列出分支、文件、是否已有未提交改动等。随后询问两项:范围(仅指令/指令和运行时代码/仅报告)和提交方式(不提交/逐仓库提交不推送/提交并推送)。仅报告到此结束。
- 统一编辑与复扫:用一个 Python 脚本按批准的文件列表执行编辑;再次扫描,直到只剩有意跳过的 TARGET;对运行时代码文件展示 git diff,并说明哪些测试未运行。
- 按约定提交:遵循仓库自身提交约定(AGENTS.md、CLAUDE.md),按路径暂存,提交信息为
chore(models): move Claude model IDs to <ids>,推送前先 fetch 检查上游是否已有相同改动。
使用方式
- 获取各系列当前模型 ID,并核对 API、Bedrock(
anthropic.前缀,可选us./eu./global.区域前缀)、Vertex(日期模型用@YYYYMMDD)的格式规则。 - 从临时目录对每个系列运行扫描:
uv run "${CLAUDE_SKILL_DIR}/scripts/scan.py" sonnet <current-sonnet-id> <root>... [--exclude GLOB] [--record REGEX]
扫描根为 $ARGUMENTS,为空时使用当前仓库;也可指定主目录或多个仓库。
- 人工复核扫描结果,必要时手动重新分类,并补充排除规则。
- 查看表格报告,回答授权问题;收到答复后才进行编辑,且授权仅覆盖所列仓库。
- 运行编辑脚本并复扫;检查运行时代码的 diff。
- 在获批时按仓库约定提交,并报告每个仓库的分支、提交、是否推送及重要钩子输出;没有
.git的目录保持未提交并明确说明。
编辑规则要点
- 只改“ID 形状”的字符串,散文内容需手改或不动。
- Bedrock 和 Vertex 形式保留前缀,改用当前无日期形式。
- 虚构或格式错误的 ID 替换为当前 ID。
- 常量表(如
SONNET_3_5、SONNET_4)需重命名并删除过时重复项,而不只是改值。 - 位于
-或.之后的 ID(如${VAR:-claude-sonnet-5})可能逃过词边界正则,需靠复扫发现。
保留但列入报告的项目
定价行与档位理由(需用户核对新价格)、历史归属表述(如“Built with Sonnet 4.5”)、故意与当前示例对比的旧引用、断言归属字符串的夹具、与特定模型绑定的能力声明、同时含新旧键的配置(可建议删除旧键)、常青别名(如 "model": "sonnet")、按模型标签过滤的遥测和仪表盘查询,以及仅看起来像模型名的词。
适用场景与限制
适用于 Claude 新版本发布后需要跨多个仓库或目录统一更新模型 ID 的维护工作。使用时需具备 ripgrep 与 uv 环境;扫描先只读,编辑需用户明确授权;不自动处理定价、能力声明和历史记录类内容。许可、价格与官方支持范围资料暂未提供。