详细设计说明

让 Skill 升级不再「把跑着的 Run 搞挂」

这份文档不讨论 Skill SDK 的实现细节，只讨论 Skill 作为可治理资产的版本生命周期：manifest 怎么写、什么算破坏性升级、Run 启动时如何锁住 hash、灰度发布如何切回、主 Skill 熔断时如何 fallback。评审时请关注：每一次工具调用是否都能定位到具体 manifest_hash、具体灰度环、具体责任人。

状态：v1 草案
日期：2026-05-07
定位：Skill Hub 在 Tier 1 提供 manifest 注册 + 灰度配置 UI；Tier 2 在派 Run 时选定具体版本；Tier 3 在 Run 启动时锁定 manifest_hash 并写入 Trace
关联：与 harness-kernel-design（Run 级 hash 绑定与 Trace 留痕）、governance-hitl-design（破坏性升级触发 HITL）、agent-teams-design（团队级 Skill 包）配套
目标：让 Skill 从 draft 到 deprecated 的全生命周期可灰度、可回滚、可追溯，破坏性升级不再悄无声息地把生产 Run 搞挂

1. 定位与概念

1.1 总体架构图

下图把 Skill Hub 的静态结构（manifest 注册 + 版本仓 + 灰度环 + Run 级 hash 关联）与三层定位叠加：横向 3 个 tier 带，T1 区是 manifest 注册 + 灰度配置 UI，T2 区把"选 Skill 版本"的决策落实，T3 区在 Run 启动时锁定 manifest_hash 并贯穿整个 Run。

1.2 两个关键场景时序图

下面 2 张时序图分别可视化「Run 启动锁 hash」和「灰度发布出问题切回」两个最关键场景。点击 lifeline 头部色块跳到下方对应章节。

1.3 为什么要做版本治理

不治理的痛点：

版本治理解决的具体技术问题：

1. 把 Skill 行为契约冻结成 manifest_hash——published 后不可改，要改就发新版本，Run 启动时锁住一个 hash 整段不变
2. 把升级动作变成「显式选版本」——Agent 启用具体 SkillVersion，不吃 latest，不会被悄悄换掉
3. 把发布动作变成可灰度可回滚——三态生命周期 + 比例 / 白名单 / 时间窗多维度控制 + 一键改比例切回
4. 把 fallback 写进 manifest——主 Skill 熔断时按声明切备，1 次连环切换上限
5. 把 Trace 强约束扩展到版本维度——每条 ToolInvocation 必带 manifest_hash，支持版本级聚合查询

1.4 三层职责定位

2. Manifest 结构

2.1 必填字段

Skill 提交审核时 manifest 必须包含以下字段，缺一禁止 publish：

2.2 沙箱声明

沙箱字段定义 Skill 的执行隔离边界，平台据此分配沙箱资源、做安全审计：

沙箱字段全部进 hash —— 因为它们直接影响 Skill 的可观察行为（能不能联网、能不能写盘），任意改动都视为新版本。

2.3 进 hash 与不进 hash 的边界

判定原则：影响 Skill 行为契约的字段进 hash；只影响治理 / 展示的字段不进 hash。

2.4 destructive 标记与参数级再校验

静态 manifest 标记解决不了一类边界问题："什么都能跑"的通用 Skill（shell_exec / python_exec / file_io）—— 把整个 Skill 一刀切标成 destructive 太粗（用户大量只读命令也会被拦），不标又会漏过 rm -rf。规则分两层：

关键字白名单 / 黑名单由 Policy 引擎集中维护（不在 manifest 里），可热更；命中后强制 HITL，文案带原始命令 + 命中规则 + 影响 path 与文件数，对接 治理与 HITL 设计 ↗ 风险矩阵 M8（用户 workspace 不可逆操作）。沙箱挂载已经把作用范围圈在用户 workspace 内（详见 沙箱边界 §F ↗），这一层是"用户私有空间内的二次确认"。

3. Semver 规则

3.1 三档变更分级

3.2 破坏性变更清单

以下变更自动判定为 breaking，发布时强制要求 major 升级，否则禁止 publish：

3.3 兼容性自动检查

开发者点击「发布新版本」时，平台自动跑 manifest diff：

• 对比当前 manifest 与上一 published 版本的 schema / permission / side_effects / sandbox
• 命中破坏性变更清单 → 强制要求 version 段升 major；如果开发者写的是 patch / minor，禁止 publish 并给出 diff 报告
• 未命中破坏性变更 → 允许 minor / patch；若开发者主动声明 major 也允许（开发者认为是重大变更）
• major 升级额外要求：HITL 审核 + 影响面查询确认 + 灰度计划填写（不允许 100% 一次性切）

核心原则：开发者只能「升得比规则要求高」，不能「升得比规则要求低」。这把"假装兼容"的路径堵死。

4. manifest_hash 锁定

4.1 hash 计算

manifest_hash 是规范化后的 manifest 的 SHA-256 摘要，只覆盖 §2.3 中标记「进 hash」的字段。规范化步骤：

1. 抽取所有「进 hash」字段，丢弃其余
2. 对 JSON Schema / 列表类型按 key 排序，确保字段顺序变化不影响 hash
3. 对字符串做 NFC 归一化、去除尾随空白
4. 整体序列化为 canonical JSON，对结果取 SHA-256，截取前 16 位作为短 hash 用于 UI 展示

同一 manifest 不同机器算出来必须一致；任何「进 hash」字段改动都会让 hash 变化。

4.2 锁定时机

4.3 RunContext 内的存储

RunContext.skill_versions 是一个 skill_id 到 manifest_hash 的映射，类型为只读字典；Run 期间任何 Tool 调用都必须用映射里的 hash，不允许绕过去查 Tier 1：

4.4 Trace 留痕

Trace 留痕的核心承诺：拿到任意一条 ToolInvocationTrace，就能精确回答「那次调用用的是哪个 manifest_hash、属于哪个 published 版本、是不是命中了灰度」三个问题。

5. 灰度发布

5.1 三态生命周期

SkillVersion 在生命周期上只有三个长期态，转换由 admin 操作驱动：

开发期的 draft / submitted / rejected 不属于这里讨论的范围 —— 那是上架审核流程，不是治理面。

5.2 灰度维度

同一 published 版本可按多种维度灰度，命中任一维度即纳入灰度环：

5.3 灰度期间的可见性约束

• 未命中灰度的用户看不到新版本 —— Skill Market 列表里不出现；Resolver 返回老版本
• 命中灰度的用户在 Run 启动那一刻被锁定到新版本的 hash；之后即使 admin 改 rollout 比例，已锁定的 Run 不受影响
• 灰度命中是幂等的：同一 user_id + 同一 rollout 配置永远得出相同结果（避免同一用户的两个 Run 一个新一个老）

5.4 灰度指标 + 告警

每个灰度发布跟踪以下指标，与 runtime-governance §2 的观测体系联动：

5.5 切回开关

灰度出问题时 admin 有两档操作：

大多数灰度异常用 rollout=0 即可；只有发现安全漏洞 / 严重数据问题时才 disable。disable 前必须先看影响面（admin UI 强制弹确认）。

6. Fallback 声明

6.1 manifest 内的 fallback 字段

Skill 开发者可在 manifest 里声明备用 Skill；不写则视为无 fallback，主 Skill 故障即向上抛错。fallback 字段结构：

6.2 触发条件

6.3 切换上限与防环

• fallback 链路只允许 1 跳：主 → 备 失败即抛错，不再尝试备的备
• 主 Skill 与备用 Skill 不允许互为 fallback —— publish 时校验，发现环路禁止 publish
• fallback 解析也走完整 Resolver 流程：会再次锁定备用 Skill 的 manifest_hash 进 RunContext
• 切换事件全部进 ToolInvocationTrace：标记 fallback_triggered + 触发原因，便于事后定位

6.4 Fallback 不解决的问题

fallback 是最后一道兜底，不替代以下治理手段：

核心原则：fallback 解决「主 Skill 暂时不可用」的问题，不解决「主 Skill 有缺陷」的问题。