Orca Skill Sharing 管理指南：访问模型、吊销删除、保留契约与事故恢复

本文聚焦 Orca 技能共享（Skill Sharing）的运营合同（contract），覆盖其发布与分发的访问模型、分享链接的吊销与包删除语义、用户/组织离场处理、数据保留策略、审计隐私边界以及事故恢复流程。读完后，你将掌握在 Orca Cloud 上管理不可列名（unlisted）技能分享链接的安全边界：什么操作需要登录身份、吊销后哪些数据仍会存活、被删除对象何时不可恢复，以及数据库与 GCS 联合恢复的正确顺序。

访问模型：分享链接就是凭证

Orca 的技能共享不提供任何公开目录。根据 管理指南，其访问模型的核心规则如下：

• 共享包是"不可列名的持有型资源"（unlisted bearer resources）：Orca 不提供公开浏览、搜索、接收者清单或包索引；
• 持有链接即可访问：任何拿到有效、未过期链接的人，无需登录即可检查（inspect）包内容，并申请一个短生命周期的下载授权（download grant）；
• 管理操作需要认证身份：发布、包/版本管理、查看自己名下的链接清单、吊销和删除，都要求"当前仍具有组织访问权限的已认证包属主"；
• 不泄露存在性：缺失、过期、已吊销、已删除、无权限这几种情况，返回完全相同的不泄露（non-disclosing）响应；
• 客户端零长期凭证：桌面端与远端运行时拿不到任何 GCP 身份或长期存储凭证，所有对存储桶的访问都经由云端 API 换发的短时效签名 URL 完成。

指南中有一句关键警告：持久分享 ID 本身就是一项凭证（The durable share ID is a credential）。不要把它写进工单、日志、分析数据或支持包（support bundle）；一旦链接可能到达了非预期的接收者，应直接使用吊销，而不是追查泄露途径。

从源码结构看，这条"匿名换授权"的链路在桌面端客户端中有直接体现：skill-cloud-service.ts 中对匿名分享调用 POST /v1/skill-shares/<share-id>/download-grants，而 skill-client-mediated-transfer.ts 里 grant 的结构就是 { url, expiresAt }——一个带明确过期时间的签名下载地址。云端对缺失/过期/已吊销/已删除的分享统一返回同样的 404 skill_share_not_found（实现清单中记录了带与不带 Authorization 头的匿名请求都收到同一响应），这正是"不泄露存在性"规则在 API 层的落地。

吊销与删除：语义边界和四步删除顺序

吊销的实际效果与五分钟窗口

吊销一个分享（share）的效果需要精确理解：

• 吊销立即阻止新的链接解析和新的下载授权签发；
• 但在吊销前已签发的、绑定对象代际（generation-bound）的授权仍然有效，直到其 5 分钟自然过期——这是吊销语义的最大滞后时间；
• 已经安装到接收者机器上的技能副本不受影响，仍保留在本地。

这一点在 威胁模型 的 TM-17 条目中有对应记录："Revocation blocks new grants immediately; existing grants expire within five minutes... Local installs remain independent."

包删除的固定顺序

删除一个包（package）不是简单的"删数据"，文档给出了严格的四步顺序：

1. 将包标记为已删除，并吊销其所有活跃分享；
2. 以事务方式解除被保留版本（retained versions）对对象的引用；
3. 只删除没有任何保留版本引用的对象代际；
4. 在数据库或 GCS 出现部分失败后，对有限的"待删除"集合做对账（reconcile）。

两条补充约束：

• 只要还有一个活跃的固定版本（pinned）分享引用某个版本，该版本就不能被删除；
• 删除操作使用记录的精确 GCS 代际来定位对象，且从不覆盖已发布的不可变键（immutable key）。

从源码结构看，GCS 对象的组织方式支撑了这种精确删除：实现清单 记录了最终键形如 packages/v1/tenants/<tenant-hash>/sha256/<prefix>/<archive-sha256>/package.tar.gz（内容寻址、租户哈希隔离），而上传隔离键是 uploads/<upload-id>/package.tar.gz。相同归档只在属主租户内部去重，跨租户不会因去重产生存在性或时序泄露（TM-10）。

用户与组织离场：元数据保留与删除前检查单

包归属于属主租户（owner tenant），同时记录发布它的用户。组织租户内，发布者离开后，其他在职成员可以接管该包的管理权，但 Orca 不会改写记录的创建者身份。删除某个用户不会自动吊销组织的链接、不会删除包、也不会清除任何已安装副本。

在删除一个组织租户之前，指南要求完成以下五步：

1. 禁用该租户的新授权签发（disable new grants）；
2. 由授权运维人员盘点并吊销全部活跃分享；
3. 决定包是移交给另一个授权属主、继续保留、还是删除；
4. 处理法律保留（legal hold）、数据抹除与审计保留要求；
5. 执行协调的元数据与对象生命周期流程，不得绕过引用检查。

指南同时明确了一个未决事项：产品当前尚未编码通用的所有权转移或法律保留策略；在外部发布之前，隐私、安全与组织属主必须共同批准适用策略。在那之前，应保留元数据和软删除代际，而不是猜测性删除。

保留契约：每类数据的默认生命周期

以下是文档定义的保留契约（retention contract）原文表格，这是容量与合规规划的核心依据：

数据	默认行为
上传策略（upload policy）与待上传行（pending upload row）	15 分钟后过期
被遗弃的 uploads/ 隔离对象（quarantine object）	由 GCS 在一天后删除
已发布的不可变包对象	无基于时间的删除；只要仍被引用就保留
已签发的下载授权（download grant）	5 分钟后过期
已删除的包对象	通过 GCS 软删除（soft delete）可恢复 7 天
PostgreSQL 元数据	受备份与 7 天时间点恢复（PITR）覆盖
接收者已安装的本地副本	独立的本地数据；云端删除不会移除它
审计事件	遵循已批准的审计保留策略

两条优先级规则必须记住：

• 组织级保留、法律保留与数据抹除要求优先于产品回滚保留；
• 产品层面的删除不是法律保留机制——legal hold 不能依赖"不删"来实现，而要靠上面的协调流程。

这些数值与 实现清单 中的基础设施记录相互印证：上传授权 15 分钟 V4 签名 POST 策略、uploads/ 前缀专属的一天生命周期、5 分钟签名 GET 下载授权、7 天软删除，以及 orca_skills 数据库所在的 Cloud SQL 实例开启备份与 7 天 PITR。

审计与隐私：记录什么、绝不记录什么

指南对审计记录（audit records）划定了明确的白名单与黑名单：

可以包含：包/版本 ID、操作者（actor）ID、事件类别、结果（outcome）、时间戳。

必须排除：技能内容、文件名、清单（manifest）、组织成员列表、本地路径、持久分享 URL、上传策略、下载授权、任何凭证。

此外还有两条运行时约束：

• 匿名滥用防护不得持久化原始请求者 IP 地址（限流等控制以不落地原始 IP 的方式实现）；
• 常规 Cloud 日志只允许包含：路由、方法、状态码、耗时、有限的失败类别；验证 staging 日志与诊断导出时，应使用种子化隐私金丝雀（seeded privacy canaries）——即故意植入敏感样例值，验证它们确实没有出现在任何采集输出中。

从源码与发布记录看，这套边界已有工程落点：威胁模型 TM-15 条目要求桌面安装诊断在打点前将值映射为有限类别、支持包（support bundle）测试注入私有金丝雀并证明其缺席；实现清单还记录了 Cloud PR 在 staging 增加日志项目排除（google_logging_project_exclusion.skill_share_bearer_request_urls），使逐链接的 Cloud Run 请求 URL 不进入日志存储，同时保留路由模板级遥测。

事故恢复与运维控制

三个独立的 kill switch

上传（upload）、下载（download）、远端安装（remote-install）三条操作路径各有一个独立的 kill switch。事故发生时只禁用受影响的最小操作面——其余功能（包括本地技能发现与已安装副本的使用）继续工作。实现清单记录了对应的验证：三个变更控制可以独立置为禁用，而匿名不可列名预览（unlisted preview）在此过程中仍然可用。

PostgreSQL PITR 与 GCS 代际恢复的协调流程

当需要同时恢复数据库元数据与被软删除的对象时，文档给出的顺序是：

1. 把元数据恢复到隔离的数据库中；
2. 从中识别出被引用的精确 GCS 代际；
3. 只恢复与这些代际匹配的软删除对象（恢复时携带 ifGenerationMatch 之类的代际前置条件，防止恢复错代际）；
4. 校验归档与包的标识一致；
5. 以事务方式把元数据重新指向恢复后的对象；
6. 在承载者预览（bearer preview）与代际绑定下载均通过验证之前，保持授权签发处于禁用状态。

实现清单中有一条真实的恢复演练记录可作为参考：恢复 smoke 发布了隔离 bundle、软删除精确的已发布 GCS 代际、用 ifGenerationMatch=0 恢复、校验不可变元数据、事务性地重指所有匹配的数据库引用、验证不可列名下载后删除探针，全程不留下临时恢复任务或存活探针对象。

延伸阅读

• Agent skill sharing 威胁模型：安全不变量、20 条威胁登记项（TM-01 至 TM-20）与未决发布门禁；
• 实现与验证清单：产品语义确认、包契约限制、GCP 基础设施声明与各阶段验证证据；
• 桌面端云端客户端：分享解析与下载授权的实际调用路径；
• 原文档引用的运维 runbook（Orca Cloud 侧的 skill-sharing-runbook.md，覆盖部署控制、对账、饱和、签名失败、数据库故障与受保护的恢复工作流）不在当前仓库内，运维事故命令以该 runbook 为最终事实来源。