Claude Files与Skills API正式GA：迁移指南

Anthropic 宣布 Claude 的 Files API 和 Skills API 正式进入 GA（General Availability）阶段。对于已经在使用 beta 版本的开发者来说，这意味着需要移除两个 beta 头、调整文件过期策略，并切换到基于游标的分页方式。官方提供了 TypeScript 和 Python 的类型检查步骤，帮助平稳迁移。

两个 API 正式 GA，beta 头不再需要

此前 Files API 和 Skills API 处于 beta 阶段，调用时需要在请求头中携带特定的 beta 标识。GA 之后，这两个 API 已纳入正式版本，开发者不再需要添加 beta 头。官方原文明确写道：“drop two beta headers”——移除两个 beta 头即可。

这一变化看似微小，但影响所有现有集成。如果你的代码中通过 anthropic-beta 头或其他方式启用了 Files 或 Skills 的 beta 功能，需要检查并删除相关配置。否则，请求可能因未知头字段而被拒绝，或行为与预期不一致。

迁移的第一步是审视代码库中的请求构造逻辑。TypeScript 用户通常在 client 初始化或单次请求的选项中设置 beta 头；Python 用户类似。建议全局搜索 beta 相关字符串，确认哪些属于 Files/Skills，哪些是其他功能仍在使用的。

GA（General Availability，正式可用）是软件产品生命周期中的关键里程碑，通常意味着接口已通过充分测试、获得官方长期支持承诺，并适用稳定性与兼容性保障。与之相对的是 beta 阶段——功能可能变更、不建议用于关键生产负载。对于 API 产品，GA 往往伴随版本号冻结、SLA（服务等级协议）明确以及弃用政策公布。因此从 beta 迁移到 GA 不仅是去掉 anthropic-beta 请求头这类表面改动，更意味着接口契约趋于稳定：后续破坏性变更一般会经过正式的弃用周期而非随意调整。开发者在规划长期架构时，可将 GA 接口视为可依赖的基础组件，而对 beta 功能则应保留替换方案。理解这一区别有助于判断本次迁移的优先级：生产依赖应尽快完成迁移，以避免 beta 头被彻底移除后调用失败。

文件过期时间延长至 90 天

GA 版本带来的一个实用改进是文件过期时间（file expiry）最长可设为 90 天。Beta 阶段的过期策略可能更短，对于需要长期保存上传文件的场景（如知识库文档、持久化资源）不够灵活。

现在开发者可以在创建文件时指定更长的有效期，减少定期重新上传的运维负担。不过，90 天并非永久存储，仍需设计续期或重建机制。官方在原文中仅提到“add file expiry up to 90 days”，未说明默认值是否变化，因此迁移时应显式设置过期时间，避免依赖隐式行为。

对于 Skills API，文件生命周期同样重要。技能相关的资源文件如果过期，可能导致技能调用失败。建议在迁移清单中加入一项：检查所有文件创建调用，确认过期参数已按新上限调整。

分页方式切换为游标

另一个需要关注的变更是分页机制。原文指出“switch to page cursors”——从之前的分页方式切换到基于游标（cursor）的分页。游标分页在数据量大时更稳定，不会因为数据增删导致重复或遗漏。

迁移时，需要检查所有列出文件或技能列表的调用。如果之前使用 offset/limit 或页码参数，现在要改为传递 cursor 参数，并从响应中读取 next_cursor。TypeScript 和 Python SDK 的类型定义会反映这一变化，官方强调“Type-checked TS and Python steps”，意味着类型检查可以帮助发现不兼容的调用。

建议在迁移后运行一次完整的列表遍历测试，确认游标传递正确、终止条件无误。对于分页结果做本地缓存的逻辑，也要相应调整。

游标分页（cursor-based pagination）是一种以不透明游标标记“上一页末尾位置”的分页方式，区别于基于 offset/limit 或页码的分页。传统 offset 分页在数据频繁增删时容易出现问题：若第一页之后有记录被删除，第二页会跳过本应出现的条目；若有新记录插入，则可能重复返回。游标分页通过服务端返回的 next_cursor 精确定位续读位置，因此在数据动态变化时更稳定，也通常具有更好的查询性能，尤其适合大结果集。代价是游标一般只能顺序前进，无法随机跳页，且游标通常不可长期缓存或跨会话复用。迁移时需注意响应中是否提供 has_more 之类的终止标志，以及游标失效时的错误处理策略——当游标对应的数据被删除后，部分实现会返回错误而非空结果。

TypeScript 与 Python 迁移步骤

官方给出的迁移路径强调类型检查。对于 TypeScript 项目，升级 SDK 后运行 tsc --noEmit 或项目自带的类型检查命令，编译器会标出仍在传 beta 头或使用旧分页参数的位置。Python 项目则可以利用类型注解和 mypy 等工具，结合 SDK 的存根文件发现不匹配。

具体步骤可归纳为：升级到包含 GA 支持的 SDK 版本；移除 Files/Skills 相关的 beta 头配置；将文件创建调用中的过期时间调整到最长 90 天；把列表调用的分页参数改为游标；运行类型检查并修复报错；最后在测试环境验证文件上传、列出和技能调用流程。

由于原文没有提供更细的代码示例，建议参考官方 SDK 的变更日志和类型定义。类型检查的价值在于把运行时错误提前到编译期，尤其适合这次涉及请求头和分页参数的变更。

对开发者的实际影响

这次 GA 标志着 Files 和 Skills 从实验性功能走向稳定接口。对于生产环境依赖这两个 API 的团队，迁移窗口需要规划：beta 头移除后，旧代码可能直接失效；分页变更可能导致列表逻辑悄然出错。

文件过期上限提升到 90 天是利好，但也提醒开发者存储并非永久，需在架构中考虑过期处理。整体来看，迁移工作量不大，但细节容易遗漏，类型检查是这次官方推荐的核心手段。

建议团队在升级 SDK 后，先在非关键环境跑通完整流程，再逐步推广。对于同时使用 Files 和 Skills 的项目，注意两者共享的 beta 头配置，避免只改一处。

（本文基于 Anthropic 官方公告及 rss 来源信息整理，具体参数以官方文档为准。）