Orca 技能共享实战指南：用不可变版本与可撤销链接在多台主机间分发 Agent Skills

Orca 允许把一个（或一整个捆绑的）Agent Skill 发布到一条"未公开列出（unlisted）、可撤销"的云端链接后面，并在本地机器、已配对的 Orca runtime、WSL 与 SSH 主机之间完成安装、更新、回滚和移除。本文基于仓库文档 sharing-agent-skills.md 展开，并引用 provider 路径注册表 与 技能共享威胁模型 佐证其实现边界；读完你可以掌握完整的"发布 → 预览 → 安装 → 冲突处理 → 撤销/删除"全链路，并理解每一步背后由哪些源码模块保证。

核心模型：链接即凭证，版本即不可变

共享 bundle 不出现在任何搜索、目录或公开索引中；任何持有有效链接的人无需登录即可查看并安装其内容。因此文档的立场非常明确：把链接当作凭证（credential）对待。

这一设计在源码中得到印证：下载授权以 download-grant 的形式进入安装请求，携带一次性 URL 与过期时间，见 skill-cloud-contract.ts（grant: { url, expiresAt }）与 skill-install-contract.ts。安装请求的"入口（ingress）"是严格枚举的三种之一：

• download-grant：来自云链接的短时下载授权；
• staged-upload：已登记的上传会话；
• local-file：仅进程内可信路径，远程调用不可用。

发布出来的每个版本是不可变（immutable）的：之后的本地修改不会悄悄改变链接当前指向的字节内容；要更新云包，必须显式发布新版本。这一点在打包侧由确定性归档保证——仓库中存在 skill-package-deterministic-gzip.ts 与 skill-package-identity.ts，前者保证相同字节生成可复现的 gzip，后者把归一化路径、精确字节、可执行位状态绑定到不可变的 package/version ID 上（对应威胁模型中的不变量"包身份是确定性的"）。

发布技能：桌面端四步流程

发布与链接管理要求桌面应用中登录 Orca 账号。操作流程：

1. 打开 Skills 页面，选择 Share skills；
2. 勾选一个或多个技能。单条链接可以装下很大的集合，例如 30 个技能；
3. 审核 bundle 名称、包含的技能与文件、脚本、可执行文件、摘要（digest）、所属账号，以及可选的 release notes；
4. 选择 Publish skill、Publish bundle 或 Publish new version，然后复制链接。

桌面端在发出上传请求前会做"分享准备"：skill-share-preparation-service.ts 负责把选定技能目录打包成带清单（manifest.json + skill/ 信封）的包并计算摘要。发布通道是直连云的限时上传，客户端侧的默认上传超时为 15 分钟（skill-cloud-direct-upload.ts 中 DEFAULT_UPLOAD_TIMEOUT_MS = 15 * 60_000）。

在 CLI 侧，Agent 也可以在授权后发布显式命名的技能集合（该开关默认关闭，需在 Settings → Share Skills → Allow agents and the Orca CLI to publish skill links 中开启）：

orca skills installed --json
orca skills share --skill frontend --skill testing --bundle-name "Team Toolkit" --json

skills installed 只返回安全的发现选择器，不暴露本地路径（测试见 skill-sharing.test.ts：输出包含 skill-id 而不含 /secret/root/... 这类路径）；skills share 只接受精确的发现 ID 或无歧义名称，不接受任意路径或 --all。

从链接安装：预览、目标机与安装事务

打开一条 Orca 技能链接会先展示预览，不改动任何文件；也可以在 Skills → Install from link 中粘贴 URL。安装前的五步审核：

1. 核对作者与组织；
2. 审核版本、release notes、包含的技能、脚本、可执行文件与 digest；
3. 选择全部技能或仅需要的子集；
4. 选择目标机器与 global 或 workspace 作用域；
5. 查看 new / unchanged / updated / conflicting 四类技能清单，再点 Install N skills。

支持的目标机包括：本机、已配对的 Orca runtime、WSL 发行版、SSH 主机。目标形态在 skill-install-contract.ts 中被严格建模为三种：{ kind: 'host' }、{ kind: 'wsl', distro }、{ kind: 'ssh', connectionId }。一个关键设计是：目标 runtime 自行解析自己的 home 与 workspace 路径，因此 folder workspace 与远程文件系统不会借用客户端机器的路径——威胁模型 TM-04 明确要求"拒绝客户端提供的远程路径"，执行 runtime 通过 realpath 校验目录、使用平台原生路径拼接来落实这一点。

安装事务本身由 skill-install-transaction.ts 等模块承担：同文件系统 staging、持久化 journal、回滚备份与 ownership token 保证崩溃后事务收敛到"旧版本或请求的新版本"之一。安装结果按技能粒度返回 status 与 errorCategory（参见 skill-bundle-install-service.ts），部分失败不影响已完成技能。

安装后的落点：单一规范副本 + provider 放置

Orca 只保存一份规范（canonical）安装副本，并按支持的 agent 的发现路径放置。当前 provider 覆盖范围记录在 agent-skill-provider-paths.md：

Provider	检测方式	Global	Workspace	Orca 放置方式
Codex	通过 Orca 主机自有 PATH 检测到 codex CLI	直接读 $HOME/.agents/skills	从当前目录向上到仓库根读 .agents/skills	仅规范副本
Claude Code	检测到 claude CLI	读 $HOME/.claude/skills	从启动目录向上到仓库根读 .claude/skills，含嵌套访问	POSIX 下相对目录符号链接、Windows 下目录 junction，或经验证的独立副本回退

该注册表刻意保持很小：不复制、不同步任何社区路径表，每次变更都需要走正式代码评审并附带官方文档链接与多平台实测证据（详见该文档的 "Registry change process" 一节）。当符号链接不可用时，独立副本回退会被记录在安装回执（install receipt）中，供后续更新与移除检测漂移——实现对应 skill-placement-copy.ts、skill-placement-reconciliation.ts 等模块。

冲突、更新与回滚

本地副本与远端不同时的默认行为是 Keep local：Orca 只在你明确选择丢弃本地修改后才替换内容。冲突类型在契约中被建模为 modified、unowned、external-link、name-collision 四种（skill-install-contract.ts），且单技能安装支持 replace-unmodified、replace-and-discard-local、cancel 三种冲突决议（skill-cloud-grant-installation.ts 中的 conflictResolution 字段）。

• 查看已安装托管技能：打开 Skills → Manage installs，可以看到托管技能及其不可变版本历史。
• 更新：安装最新版本即执行更新；回滚：选择某个仍保留的旧版本。两者走同一套受保护的安装事务（实现见 skill-update-run.ts、skill-install-recovery.ts）。
• bundle 内容变化：若某版本之间 bundle 组成变了，Orca 只更新在该版本中仍然存在的所选技能，不会动已经移除的条目。
• 中断恢复：被中断的安装会在重启时恢复（启动恢复逻辑见 skill-transaction-startup-recovery.ts）。如果 Orca 报告冲突或部分结果，查看被点名的技能并重试即可；已完成技能无需重新安装。

对远程 runtime 的安装还有版本能力门槛：远端必须声明 SKILL_BUNDLE_INSTALL_CAPABILITY，否则返回"需要更新"结果而不是硬跑（skill-cloud-grant-installation.ts 中对 SKILL_INSTALL_UPDATE_REQUIRED_MESSAGE 的处理），混合版本拓扑下新旧客户端会失败在"需要更新"而不是发出未定义操作——这与威胁模型 TM-11 一致。

移除已安装技能

通过 Skills → Manage installs → Remove 移除。Orca 只删除它拥有且可验证的副本与 provider 放置；被修改过或非它所有的文件会被保留并报告；丢弃已修改内容需要单独的显式确认。移除路径的所有权再校验见 skill-remove-transaction.ts 与 skill-removable-placement.ts。

注意两个方向的边界：

• 移除本地安装不会撤销其共享链接，也不会删除云端包；
• 反过来，撤销或删除云端数据也不会触及接收方机器上已安装的副本。

本地安装是独立的本地数据，云删除不递归（管理端文档 admin-agent-skill-sharing.md 的保留契约表中同样声明了这一点）。

保留与删除：时间参数一览

主文档给出的保留规则如下（与 admin-agent-skill-sharing.md 的完整保留契约表相互印证）：

数据	默认行为
上传授权（upload grant）	15 分钟后过期
弃置的上传字节（隔离区）	一天后删除
已发布版本	无基于年龄的自动删除，被引用期间保留
签发的下载授权（download grant）	5 分钟过期
已删除的 GCS 对象	通过 7 天软删除窗口可被运维恢复
接收方已安装副本	保留，直到在各目标机上被手动移除

包删除的执行顺序是：标记删除并撤销其活跃链接 → 事务化解引用保留版本 → 只删除没有任何保留版本引用的对象代际（generation）→ 在数据库或 GCS 部分失败后收敛有限的待删除项。被活跃固定链接引用的版本不可删除；删除始终使用记录的精确 GCS generation，永不覆盖不可变的已发布 key。

组织层面的法务或保留要求可以覆盖常规的回滚与删除时序——产品删除不是 legal-hold 机制。

信任与隐私：技能是作者的代码

安全立场可以浓缩为一句话：skill 是作者的代码。SKILL.md 可以改变 agent 行为，捆绑的脚本或可执行文件可能在你或 agent 日后使用技能时运行。Orca 会验证包（归档校验先于任何目标路径变更完成），但安装过程本身从不执行包内容——威胁模型 TM-14 将此列为显式不变量，预览界面展示作者、组织、脚本、可执行文件、digest 与版本，正是为了让"安装前知情"成为可能。你应当只从信任的人那里安装，并审查出人意料的脚本或可执行文件。

隐私侧的边界：

• Orca 只记录有界的运维标识符与结果；常规日志、遥测与支持包（support bundle）均排除技能内容、文件名、manifest、本地路径、共享 URL、上传策略、下载授权、凭证与访问列表；
• 缺失、过期、已撤销与已删除的链接故意返回相同的响应，避免泄露私有包的存在性（对应威胁模型 TM-09 的"not-found 响应隐藏未授权存在"控制）；
• 如果一条链接失效，正确做法是向链接所有者索取一条新的有效链接，而不是反复探测；
• 云侧访问模型同样受限：桌面与远程 runtime 拿不到 GCP 身份或长期存储凭证，所有管理操作要求当前组织内的已认证包所有者（详见 admin-agent-skill-sharing.md 与 agent-skill-sharing-threat-model.md 的 Actor 与边界章节）。

实现边界补充：Orca 独立实现该协议

为避免读者误以为这是某个上游 skill 工具的包装，仓库文档 agent-skill-sharing-upstream-boundary.md 明确：Orca 的打包、云授权、安装、provider 放置与恢复行为是独立实现的，上游项目仅作为行为参考；不允许复制其源码、测试、fixture、注册表条目或 provider 路径表，provider 路径一律来自各 provider 官方文档并经真实安装验证。

参考路径速查

内容	路径
主文档（本文骨架）	docs/reference/sharing-agent-skills.md
Provider 路径注册表	docs/reference/agent-skill-provider-paths.md
管理端生命周期/保留契约	docs/reference/admin-agent-skill-sharing.md
威胁模型与安全不变量	docs/reference/agent-skill-sharing-threat-model.md
上游边界声明	docs/reference/agent-skill-sharing-upstream-boundary.md
安装契约（ingress/目标/冲突类型）	src/shared/skill-install-contract.ts、src/shared/skill-cloud-contract.ts
云授权安装入口	src/main/skills/skill-cloud-grant-installation.ts
安装事务/恢复	src/main/skills/skill-install-transaction.ts、src/main/skills/skill-transaction-startup-recovery.ts
Provider 放置与对账	src/main/skills/skill-provider-destinations.ts、src/main/skills/skill-placement-reconciliation.ts
远程/SSH/WSL 安装	src/main/skills/skill-remote-install-service.ts、src/main/skills/skill-ssh-relay-service.ts、src/main/skills/skill-wsl-install-transaction.integration.test.ts
CLI 分享命令	src/cli/handlers/skill-sharing.ts、src/cli/handlers/skill-sharing.test.ts