Anthropic Files / Skills 迁移：Workspace 不是租户隔离，API Key 也不是用户身份

核心判断：Anthropic Files / Skills 的 SDK 入口可以从 beta 迁向稳定接口，但这次迁移不会自动带来用户级隔离。Files 的资源边界仍是 Workspace，API Key 代表被管理的身份；你的服务必须自己维护"终端用户 → file_id → Workspace"的授权映射，不能信任请求里直接传入的任意 file_id。

这条判断同时解决两个容易混淆的问题：一是版本迁移时为什么不能只删除旧 beta Header；二是把文件交给模型时，为什么"请求通过鉴权"仍不代表"这个用户可以读这个文件"。前一个问题属于协议和类型兼容，后一个问题属于资源授权。把它们塞进同一个 anthropicAllowed 布尔值，迁移之后迟早会出现越权或审计缺口。

本文面向维护 Anthropic 集成的后端、Agent Runtime 和平台工程师。你会得到一套四阶段迁移顺序、一个不依赖具体 Web 框架的授权骨架、最小回归矩阵以及回滚条件。文中版本和 API 语义来自 2026-08-27 的官方 Release Notes、Files API、Skills Guide 与 Authentication 文档；代码是接口形状示例，本次没有创建 Key、上传真实文件或调用 API，不把示例写成生产实测。

1. 这次变化到底改了什么

Anthropic 2026-08-27 的 Release Notes 记录了多语言 SDK 的一个共同变化：Python SDK 1.2.0、TypeScript SDK 0.122.0、Go SDK 1.68.0、Java SDK 2.59.0、Ruby SDK 1.67.0 和 C# SDK 12.44.0 中，client.beta.files、client.beta.skills 不再发送旧 Files / Skills beta Header，并返回与 client.files、client.skills 相同的结构。仍然显式携带旧 Header 的请求，继续得到 beta 结构。

这意味着迁移窗口会同时存在两套形状：同一套业务代码可能因为 Header 被中间件补回而收到旧字段，也可能在 SDK 升级后收到稳定字段。迁移门禁不能只看依赖解析是否成功，而应同时记录 SDK 版本、实际请求 Header、响应序列化结果和类型名称。

Skills 还有一个容易漏掉的语义变化：client.beta.skills.delete() 现在表示删除一个 Skill 及其全部版本；Messages beta 类型 BetaSkill 改名为 BetaContainerSkill。如果只做机械替换，删除范围和反序列化都会悄悄漂移。生产系统至少要为"删除单个版本"和"删除整个 Skill"分别写测试，并检查旧客户端是否仍在消费旧类型名称。

迁移点	旧认知	现在应记录的事实	失败后果
Files / Skills 入口	beta 与稳定入口只是路径差异	稳定入口不再默认发送旧 Header，旧 Header 仍可能强制 beta 结构	解析成功但字段形状不一致
Skills 删除	删除一个版本	删除 Skill 及全部版本	误删同 Skill 的其他版本
Messages 类型	BetaSkill 永久存在	新类型名为 BetaContainerSkill	类型守卫失效或数据丢失
Files 隔离	文件属于调用用户	文件属于 Workspace	把 Workspace 共享误当用户隔离
Key 身份	一个 Key 就是一个用户	Key 代表被管理身份，权限随身份变化	个人 Key 被用于 CI，审计主体混乱

2. 先画出四个身份，不要只留 userId

一个真实请求至少包含四类主体：终端用户、应用租户、Anthropic Workspace 和 API Key 绑定身份。它们可能一一对应，也可能完全不是一回事。比如一个 SaaS 租户的多个成员共享同一个 Anthropic Workspace；又比如一条 CI 流水线用 Service Account Key 访问生产 Workspace。此时 userId、tenantId、workspaceId 和 keyPrincipalId 不能互相替代。

建议在进入模型 SDK 前，把主体规范化成不可变上下文。下面的 TypeScript 只表达授权所需字段，字段名可以按你的系统调整：

type CallerKind = 'user' | 'service' | 'anonymous';

type RequestPrincipal = {
  requestId: string;
  callerId: string;
  callerKind: CallerKind;
  tenantId: string;
  workspaceId: string;
  keyPrincipalId: string;
  scopes: readonly string[];
};

function assertPrincipal(p: RequestPrincipal) {
  if (!p.requestId || !p.callerId || !p.tenantId) {
    throw new Error('principal_incomplete');
  }
  if (!p.workspaceId || !p.keyPrincipalId) {
    throw new Error('provider_identity_incomplete');
  }
  if (!p.scopes.includes('files:read')) {
    throw new Error('scope_missing:files:read');
  }
}

这里有一个刻意的限制：workspaceId 由服务端根据租户配置解析，不能从请求体直接覆盖。请求体可以携带业务里的"文档引用"，但不能携带一个未经授权的 Provider file_id 来改变资源范围。API Key 同样从服务端密钥绑定表中取得，不能让前端选择"用哪个 Key"。

Personal Key 和 Service Account Key 都以被管理身份行动。个人开发可以使用 Personal Key；CI、生产和共享自动化应使用独立 Service Account。身份被移出组织或失去 Workspace 权限时，对应 Key 会失效。已有云身份链的场景，官方仍优先推荐 Workload Identity Federation，以减少长期静态凭据。这里的关键不是"哪种 Key 更安全"这一句口号，而是审计中必须同时出现 Key 类型、绑定身份、Workspace、端点权限和失效时间。

**过关证据：**同一个业务用户在开发、预发布和生产环境发起请求时，审计事件能区分租户、Workspace、Key 主体和调用者；更换 Service Account 后，权限变化能在一次探针请求中被看见；前端提交任意 workspaceId 或 keyPrincipalId 都不能改变服务端解析结果。

3. Files 的真实边界：Workspace，不是终端用户

Files API 的实际隔离边界是 Workspace。同一 Workspace 内、拥有相应 API 权限的身份可以访问其中的文件。这个事实对单用户脚本很简单，对多租户产品却很危险：如果多个客户共用一个 Workspace，Provider 层不会替你完成客户级授权。

因此，服务端需要维护自己的资源映射。最小数据模型可以是：

业务字段	用途	谁能写入	谁能读取
tenant_id	SaaS 租户边界	服务端	服务端授权层
owner_user_id	业务所有者	服务端根据登录态	业务授权层
workspace_id	Provider 资源域	租户配置管理员	Provider 适配层
file_id	Anthropic 文件引用	上传流程	通过租户与用户策略
purpose	资料用途，如检索或 Skill	业务服务	审计与清理任务
status	active、revoked、deleted	生命周期任务	所有读取前检查

上传完成后，不要把 Provider 返回的 file_id 原样交给浏览器长期保存。可以给客户端一个业务引用 documentRef，服务端在每次读取前按当前主体查询映射：

type FileGrant = {
  tenantId: string;
  ownerUserId: string;
  workspaceId: string;
  fileId: string;
  status: 'active' | 'revoked' | 'deleted';
};

async function resolveFileForRead(
  principal: RequestPrincipal,
  documentRef: string,
): Promise<FileGrant> {
  const grant = await db.fileGrants.findByDocumentRef(documentRef);
  if (!grant || grant.status !== 'active') throw new Error('file_not_available');
  if (grant.tenantId !== principal.tenantId) throw new Error('tenant_mismatch');
  if (grant.workspaceId !== principal.workspaceId) throw new Error('workspace_mismatch');
  const canRead = grant.ownerUserId === principal.callerId
    || principal.scopes.includes('files:read:any');
  if (!canRead) throw new Error('file_forbidden');
  return grant;
}

这里的 file_id 只是最后一步调用 Provider 的参数，不是授权凭据。即使调用者猜到了另一个租户的 ID，resolveFileForRead 也应在发出网络请求前拒绝。拒绝要记录结构化原因，但日志中不要打印完整 Key、文件内容或可能包含秘密的请求体。

3.1 什么时候需要拆 Workspace

如果产品要求租户之间具备强隔离，最直接的工程选择是按租户拆分 Workspace。这样 Provider 的资源边界与业务边界对齐，删除、配额、审计和密钥轮换都更容易解释。代价是 Workspace 数量、配置和运维成本上升，跨租户共享资料也不能再依赖 Provider 层的自然可见性。

如果暂时不能拆分 Workspace，就必须把"共享 Workspace + 服务端授权映射"当成明确的补偿控制，并配套以下门禁：每次读取都重新授权、撤销后立即阻断、异步任务不复用旧授权、后台导出再次校验租户、审计事件包含映射版本。不能把一次上传时的授权结果永久缓存成读取许可。

4. SDK 迁移分四阶段，先隔离协议变化

迁移时最容易犯的错，是一边升级 SDK，一边改业务授权和数据模型。出了问题以后，团队无法判断是 Header、类型、Key 还是 file_id 越权。建议把变更拆成四阶段，每阶段都有独立回滚点。

阶段一：冻结版本和请求形状

先在锁文件中固定 SDK 版本，并记录默认客户端实际发送的 Header。不要先批量删除所有 beta 字样，因为旧 Header 可能由公共 HTTP 中间件、重试器或自定义 Provider 注入。对 Files、Skills、Messages 分别保存一份脱敏请求快照与响应结构快照。

const client = new Anthropic({ apiKey: keyFromServer });

// 迁移探针：只验证请求构造与序列化，不上传真实用户文件
const requestShape = {
  entry: 'client.files',
  headersAddedByApp: collectProviderHeaders(),
  sdkVersion: packageVersion('@anthropic-ai/sdk'),
};
console.log(JSON.stringify(requestShape));

过关条件不是"安装命令退出码为 0"，而是锁文件、运行时版本和请求 Header 三者一致。若仍需要旧 beta 结构，必须把原因写入兼容清单，并限制在单独适配层，避免整个进程默认携带旧 Header。

阶段二：分离稳定入口与兼容适配

把 client.beta.files 与 client.files 的差异封装在 Provider Adapter 内，业务层只依赖自己的 FileStore 接口。稳定入口返回结构变化时，只改 Adapter 的解析测试；旧客户端需要兼容时，也不把 beta 判断散落在业务代码。

interface FileStore {
  create(input: { bytes: Uint8Array; purpose: string }): Promise<{ fileId: string }>;
  remove(fileId: string): Promise<void>;
}

class AnthropicFileStore implements FileStore {
  constructor(private readonly client: Anthropic) {}

  async create(input: { bytes: Uint8Array; purpose: string }) {
    const result = await this.client.files.create({
      file: new Blob([input.bytes]),
      purpose: input.purpose,
    });
    return { fileId: result.id };
  }

  async remove(fileId: string) {
    await this.client.files.delete(fileId);
  }
}

示例没有假设所有 SDK 语言的上传参数完全相同，真实项目应按官方 SDK 类型和运行时支持调整。这里真正重要的是：业务层拿到的是内部 fileId 结果，授权映射由服务端写入，不让 SDK 返回对象直接穿透到前端。

阶段三：回归 Skills 删除和容器类型

为 Skill 建立版本化测试夹具：一个 Skill、两个版本、一个引用它的容器消息。执行删除后，检查 Provider 返回的 Skill、所有版本、消息中的类型名称和本地缓存是否同步。删除操作要有幂等键或任务 ID，避免重试把一次"删除整个 Skill"误认为"删除当前版本"。

创建 Skill S
→ 创建版本 S@1、S@2
→ 读取容器消息，确认类型为 BetaContainerSkill（或稳定等价类型）
→ 调用 skills.delete(S)
→ 读取 S、S@1、S@2，均应不可用
→ 重复 delete(S)，记录幂等结果而不是创建新任务

如果老客户端仍发送 BetaSkill，适配层可以在边界转换，但不能让数据库同时保存两个含义相同、名称不同的字段。建议在转换处记录 schema_version，并在日志中统计旧类型出现次数，直到可以安全移除兼容路径。

阶段四：最后才切换默认入口

当协议快照、删除语义、类型转换和资源授权全部通过后，再把默认调用从 beta 入口切到稳定入口。发布时保留一个按请求或租户维度关闭稳定入口的开关，回滚只切换适配层，不回滚业务数据库中的授权映射。

5. API Key 选择是身份治理，不是配置项

Personal Key、Service Account Key 和 Workload Identity Federation 解决的不是同一个问题。个人开发需要可追溯到个人的操作身份；CI 和生产自动化需要独立的服务主体；云环境已有身份链时，WIF 可以减少静态密钥长期存在的时间。

单 Workspace Key 可以省略 Workspace ID；未绑定单一 Workspace 的身份 Key，则需要在每个普通 API 请求中发送 anthropic-workspace-id。Admin API 只接受未绑定特定 Workspace 的 Personal / Service Account Key。于是 Key 类型、身份、Workspace 和端点权限必须一起进入审计，而不是只在环境变量里留一个 ANTHROPIC_API_KEY。

推荐维护一张服务端绑定表：

{
  "keyPrincipalId": "svc-doc-indexer-prod",
  "keyType": "service_account",
  "workspaceId": "ws-prod-eu",
  "allowedEndpoints": ["files.create", "files.delete"],
  "expiresAt": "2026-12-31T00:00:00Z",
  "rotationVersion": 3
}

这段数据不包含 Key 本身，只描述 Key 的身份和能力。真正的秘密应放在密钥管理系统中，读取时绑定到运行环境。轮换时先创建新 Service Account Key，完成探针和双写审计，再撤销旧 Key；不要把旧 Key 复制到多个服务以"减少改配置次数"。

6. 把授权检查放在副作用之前

授权检查如果发生在上传之后、模型调用之后或异步队列消费之后，已经太晚。建议把一次文件读取拆成明确的状态机：

收到 documentRef
→ 解析服务端 principal
→ 校验 tenant / workspace / scope
→ 读取 fileGrant 并检查 status
→ 生成一次性 Provider 调用上下文
→ 调用 client.files.retrieve(fileId)
→ 脱敏后写审计
→ 返回业务结果

每一步都要能失败关闭。特别是异步任务：入队时保存 tenantId、workspaceId、callerId 和 authorizationVersion；出队时重新查询当前授权。如果用户在入队后撤销了文件权限，Worker 不应因为消息里带着旧 file_id 就继续执行。

审计事件可以长这样：

{
  "event": "provider.file.read",
  "requestId": "req_123",
  "tenantId": "tenant_a",
  "callerId": "user_42",
  "keyPrincipalId": "svc-doc-reader-prod",
  "workspaceId": "ws-prod-eu",
  "documentRef": "doc_789",
  "decision": "allow",
  "authorizationVersion": 12
}

不要记录完整 file_id、Authorization Header、文件名中的敏感路径或文件内容摘要。排查需要关联时，用不可逆的短哈希或内部文档引用。

7. 最小回归矩阵：验证拒绝，而不是只验证成功

迁移门禁至少覆盖下面 12 个场景。成功用例证明路径可用，拒绝用例才证明边界存在。

场景	预期	关键断言
稳定 Files 入口	允许	无旧 beta Header，结构符合稳定类型
显式旧 Header	仅兼容层允许	业务层不得意外走旧结构
Skill 删除	删除 Skill 全部版本	S、S@1、S@2 均不可读
旧类型消息	转换或拒绝	不静默丢失字段
同租户同用户读文件	允许	映射、Workspace、scope 均匹配
同租户其他用户读文件	按策略	无 files:read:any 必须拒绝
跨租户读文件	拒绝	Provider 请求不应发出
Workspace 不匹配	拒绝	记录 workspace_mismatch
猜测 file_id	拒绝	只接受 documentRef 映射
撤销后异步读取	拒绝	Worker 重新检查当前 status
Personal Key 用于生产 CI	阻断	部署检查拒绝错误 Key 类型
Key 失去 Workspace 权限	拒绝并告警	不重试成无限循环

可以把"Provider 请求是否发出"作为硬断言：跨租户、Workspace 不匹配和 scope 缺失时，网络 Mock 的调用次数必须为 0。这样即使上游 API 后续改变错误码，本地授权边界仍然清晰。

8. 回滚与未覆盖边界

如果稳定入口上线后出现字段解析差异，先回滚 Adapter 的默认入口，不要删除数据库里的 fileGrant。如果删除 Skill 的范围不符合预期，暂停删除 Worker，保留现有 Skill 数据和操作日志，等确认官方响应后再继续。若发现某个生产服务使用 Personal Key，先冻结新部署并轮换为 Service Account，不要把 Personal Key 再复制到更多环境。

本文没有覆盖真实 API 调用、文件内容合规、数据保留期限、区域处理、模型训练条款或 Gemini 视频 Provider 的生成权利。它也没有证明把多个租户放在一个 Workspace 就满足任何特定合规标准。是否拆 Workspace，需要结合合同、数据分类、管理员权限和审计要求单独裁定。

结语：把"身份、资源、版本"绑在同一条证据链上

Anthropic SDK 的 beta 到稳定迁移，表面上是入口和类型变化，真正的工程风险在于团队把协议变化误当成安全变化。稳定入口不会替你隔离用户，API Key 不会替你理解业务租户，file_id 也不会自动携带授权上下文。

上线前请逐项确认：SDK 版本和实际 Header 已冻结；Files / Skills 通过适配层隔离；Skill 删除范围有双版本夹具；BetaContainerSkill 等类型迁移有回归；服务端维护 tenant、Workspace、用户和 file_id 映射；跨租户和撤销后的 Provider 请求为零；生产自动化使用可审计的 Service Account 或 WIF；回滚只切适配层，不破坏授权数据。

做到这些，升级才不只是"依赖安装成功"，而是把身份、资源和版本都放进了同一条可回读的证据链。

官方来源

• Anthropic Release Notes
• Files API
• Skills Guide
• Authentication

本文验证边界

• 官方事实：SDK 版本、beta Header 行为、Skill 删除语义、类型名称、Workspace 隔离和 Key 绑定规则。
• 工程判断：四阶段迁移顺序、服务端授权映射、Workspace 拆分取舍、回归矩阵和审计字段。
• 未验证项：未调用 Anthropic API，未上传文件或 Skill，未创建 / 撤销 Key，未对真实多租户服务执行攻击测试。