它到底是什么

/claude-api upgrade 是 Claude Code 内置 claude-api Skill 下的一个子命令，用途是把项目里的 Anthropic SDK 依赖跨主要版本升级——目前specifically 指 Python anthropic 包从 0.x 升级到 1.x。它不是模型迁移工具（那是同一 Skill 下的 /claude-api migrate），而是专门处理 SDK 包本身的破坏性变更。

官方文档明确写出版本门槛：upgrade 子命令要求 Claude Code v2.1.236 或更高版本。这个 Skill 随 Claude Code 内置分发，无需单独安装；它源码同时开放在 Anthropic 官方 anthropic/skills 仓库中，也可以作为独立 Skill 装进其他支持 Agent Skills 的环境。

怎么触发 / 怎么使用

1. 直接调用

/claude-api upgrade python

语法为 /claude-api upgrade [python] [scope]，可以在语言之后追加作用域（目录或文件），用于指定要升级的目录或文件：

/claude-api upgrade python src/

2. 自动触发

除了手动输入，claude-api Skill 在以下情况会自动激活（不一定直接进入 upgrade 分支，但会加载相关参考资料）：

• 项目代码中 import anthropic（Python）或 import @anthropic-ai/sdk(TypeScript/JS)
• 用户要求 Claude 构建、调试或优化 Claude API / Anthropic SDK 相关代码

3. 执行流程

命令内部按官方仓库 python/claude-api/sdk-upgrade.md 定义的流程执行：

1. Step 0：确认作用域，确定当前版本与目标版本（要求已发布的 1.x 版本存在）
2. Step 1：盘点受影响的文件
3. 针对每类变更逐条处理（按变更类型分节）
4. 生成校验结果与报告

它会处理的 0.x → 1.x 关键变更包括：

• httpx2 依赖替换
• .with_raw_response 相关调用需要 await（异步化）
• 移除已废弃的参数/别名
• 移除 Text Completions 相关代码
• Python 最低版本要求提升到 3.10

保存 / 配置 / 集成

claude-api Skill 支持通过 Claude Code 插件市场安装到其他项目：

/plugin marketplace add anthropics/skills
/plugin install claude-api@anthropic-agent-skills

或用 npx skills add 方式安装到任意支持 Agent Skills 的环境：

npx skills add https://github.com/anthropics/skills --skill claude-api

运行约束 / 限制

跟同类原语对比

经典使用场景

• 项目仍在使用 anthropic 0.x，需要跨主版本升级到 1.x，且调用点较多、属于机械式改动（而非少量深度自定义 httpx 接线的场景）
• 升级前想先看清具体要改哪些文件、哪些改动类型，再决定是否让 Claude 自动执行
• 升级后需要按官方建议的核对清单（diff 审查、类型检查、测试套件）确认迁移正确性

常见坑

1. 不要跟 migrate 搞混：upgrade 只处理 SDK 包主版本变更，不做模型迁移；如果目的是换模型（比如切到 Claude Opus 5），应该用 /claude-api migrate 而不是 upgrade。
2. 自动生成的 diff 仍需逐段审查：这是一次会直接修改代码库的自动化迁移，应当像审查一次外部贡献的 PR 一样，逐个 diff hunk 检查后再提交。
3. 迁移后务必跑类型检查器（pyright 或 mypy）：由于 1.0 的破坏性变更大多会以类型错误的形式暴露出来，类型检查是发现遗漏改动最直接的方式，之后再跑一遍测试套件确认行为正确。
4. 超时配置写法要跟着换：升级后应使用 anthropic.Timeout 而不是 httpx.Timeout，因为前者的重新导出已经指向了更新后的 httpx2 包。

来源

• Slash commands 官方文档（commands.md） — 确认 /claude-api [migrate|upgrade|...] 完整语法与 upgrade 的 v2.1.236+ 版本要求
• Claude API skill 官方文档 — 确认 Skill 覆盖语言、激活方式、安装方法及 migrate 子命令细节
• anthropics/skills 仓库 · claude-api/SKILL.md — 确认 upgrade 的执行流程与 0.x→1.x 关键变更列表
• Anthropic Python SDK 1.0 Migration: By Hand or Claude Code — 实际使用 /claude-api upgrade python 的经验记录（diff 审查、类型检查、Timeout 写法等实践建议）