skillhub/docs/25-skill-suites.md

Skill Suite 设计与使用

定位

Skill Suite 是一个有独立身份和版本的 Skill 集合。它只引用当前 SkillHub 中已经发布的精确 SkillVersion，不复制 Skill 文件，也不替成员重新执行扫描或审核。

Skill 与 Suite 的完整身份都包含资源类型，因此下列两个资源可以同时存在：

SKILL @global/marketing
SUITE @global/marketing

原有 skillhub install @global/marketing 始终安装 Skill；Suite 必须使用 skillhub suite install @global/marketing，不会根据名称猜测类型。

版本和生命周期

SuiteVersion 固定成员的 Skill ID、SkillVersion ID、坐标、版本和 fingerprint。成员发布新版本不会 改变现有 SuiteVersion；调整成员、顺序、Entry Skill 或可见范围都需要创建新的 SuiteVersion。

DRAFT -> PENDING_REVIEW -> PUBLISHED -> YANKED
                       \-> REJECTED -> DRAFT

• PRIVATE Suite 可以从 DRAFT 直接发布。
• PUBLIC 和 NAMESPACE_ONLY Suite 需要一次 Suite 级审核。
• Suite 没有可执行包，因此没有 SCANNING 或 SCAN_FAILED 状态。
• 隐藏、归档、下架或删除 Suite 不会改变任何成员 Skill。
• 成员失效后，已发布 SuiteVersion 保留历史快照并显示为不可安装，不会自动切换到成员最新版本。

成员与权限

一个 SuiteVersion 最多包含 100 个不同 Skill，并且必须明确选择其中一个普通成员作为 Entry Skill。 Entry Skill 仍是完整、可独立安装的 Skill。跨 Namespace 的 PUBLIC Skill 可以作为 Entry；非 PUBLIC 成员仍必须满足下表中的同 Namespace 受众约束。 v1 不支持嵌套 Suite、版本范围、外部 Registry 成员或条件成员。

Suite 的可见范围不能宽于成员：

Suite 可见性	允许的成员
PUBLIC	仅 PUBLIC Skill
NAMESPACE_ONLY	PUBLIC，或同 Namespace 的 NAMESPACE_ONLY Skill
PRIVATE	PUBLIC，或同 Namespace 的 NAMESPACE_ONLY/PRIVATE Skill

创建、提交、审核和安装时都会重新检查成员资格。成员被下架、隐藏、归档、收窄权限或硬删除后， SuiteVersion 仍为 PUBLISHED，但安装计划会整体失败。硬删除只清空成员外键；坐标、版本和 fingerprint 快照继续用于历史展示和审计。

创作页面保存成员时会携带候选接口返回的精确 skillVersionId。服务端按 ID 读取版本，并校验坐标和 版本一致后再保存快照，不会按名称重新解析到另一个所有者的同名 Skill。

suite.yaml 定义

suite.yaml 是可移植的 Suite 创作格式，不是上传到 Agent 的多 Skill ZIP：

apiVersion: skillhub.iflytek.com/v1alpha1
kind: SkillSuite
metadata:
  namespace: global
  slug: superpowers
  version: 1.0.0
  displayName: Superpowers
spec:
  visibility: PUBLIC
  entrySkill: "@global/using-superpowers@1.0.0"
  members:
    - skill: "@global/using-superpowers"
      version: 1.0.0
    - skill: "@global/brainstorming"
      version: 2.1.0

当前版本通过 Web 编辑器或 Suite API 创建同一份定义；CLI v1 负责安装生命周期，尚不读取或发布 suite.yaml。保留该格式是为了后续增加 CLI 导入时不改变服务端领域模型。

CLI 安装生命周期

skillhub suite install @global/superpowers --version 1.0.0
skillhub suite check @global/superpowers
skillhub suite upgrade @global/superpowers --check
skillhub suite upgrade @global/superpowers
skillhub suite remove @global/superpowers

安装、升级和卸载先获取当前 Suite 的本地操作锁，避免两个 CLI 进程基于同一份旧 inventory 并发 提交。安装随后解析精确计划并下载、校验全部成员，再按稳定顺序锁定目标目录并整体提交。提交中途 失败时，CLI 恢复本次替换的目录并保持安装前 inventory。卸载只移除当前 Suite 的来源；直接安装、 被其他 Suite 共享或已被本地修改的成员目录会保留。

CLI inventory 向后兼容旧记录。旧记录没有 installedBy 时按直接安装处理，不会在移除 Suite 时被 误删。新 CLI 在 Server 未声明 skill-suite-v1 能力时会明确停止 Suite 命令，普通 Skill 命令不受影响。

CLI 获取安装计划时会发送独立的 Idempotency-Key，遇到网络错误或 502/503/504 时使用同一个 key 重试一次。Server 按登录用户隔离该 key；匿名请求使用经过哈希的请求来源、客户端标识和 Suite 坐标 隔离，不保存原始身份字段。Server 为计划生成 operationId，在 24 小时窗口内避免重复记录 Suite 安装请求和审计。 安装计划本身不预增成员下载数；每个成员仍由原有 Skill 下载接口按实际请求计数。

本地 local profile 可直接运行 make suite-smoke。验证 release Compose 时必须使用真实管理员会话：

SMOKE_ADMIN_USERNAME=admin \
SMOKE_ADMIN_PASSWORD='<configured-password>' \
./scripts/suite-smoke-test.sh http://localhost:8080

脚本不会输出密码，并在结束时删除其创建的临时 Suite 和 Skill。

API 与发现

• Suite 管理与详情：/api/v1/suites/**、/api/web/suites/**
• 当前用户可管理的 Suite：/api/v1/me/suites、/api/web/me/suites
• 类型化资源发现：/api/v1/resources、/api/web/resources
• 原有 Skill 搜索接口继续只返回 Skill。

类型化发现结果通过 resourceType=SKILL|SUITE 区分同名资源。Suite 详情返回固定版本、按顺序排列 的成员快照、Entry Skill、实时可安装状态和阻塞原因。普通 Skill 详情会列出当前用户可见、以该 Skill 作为 Entry 的最新已发布 SuiteVersion，并链接到完整 Suite；Skill 的独立安装能力保持不变。

部署顺序

数据库迁移会先把既有审核任务回填为 SKILL_VERSION，保留旧 Skill 专用列，并通过数据库触发器 把旧版 Server 新写入的 Skill 审核同步补全为类型化 subject。官方单实例 compose.release.yml 和本地开发 profile 已默认开启 Suite 审核写入，因为它们不会同时运行新旧 Server。

其他部署方式默认保持关闭。全新安装、单实例升级或停机升级可直接设置：

SKILLHUB_SUITE_REVIEW_WRITES_ENABLED=true

旧版与新版 Server 会同时运行的滚动升级，应在发布新版前保持：

SKILLHUB_SUITE_REVIEW_WRITES_ENABLED=false

用该配置完成所有 Server 实例升级；确认不再有旧版实例后，将其改为 true 并再次滚动重启。开关关闭 期间，现有 Skill 审核保持可用，Suite 草稿和 PRIVATE 直发不受影响，PUBLIC 与 NAMESPACE_ONLY Suite 的新审核提交会被拒绝。Server 启动时会记录明确告警，避免门禁被长期遗忘。

日志与审计

Suite 创建、编辑、提交、审核、发布、下架、隐藏、恢复、归档和删除都会写审计记录。业务日志仅记录 Suite ID、SuiteVersion ID、actor ID 和 request ID 等定位字段，不记录成员内容、Token 或下载地址。