mirror of
https://github.com/iflytek/skillhub.git
synced 2026-10-08 03:07:51 +00:00
151 lines
7 KiB
Markdown
151 lines
7 KiB
Markdown
# Skill Suite 设计与使用
|
||
|
||
## 定位
|
||
|
||
Skill Suite 是一个有独立身份和版本的 Skill 集合。它只引用当前 SkillHub 中已经发布的精确
|
||
SkillVersion，不复制 Skill 文件，也不替成员重新执行扫描或审核。
|
||
|
||
Skill 与 Suite 的完整身份都包含资源类型，因此下列两个资源可以同时存在：
|
||
|
||
```text
|
||
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。
|
||
|
||
```text
|
||
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：
|
||
|
||
```yaml
|
||
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 安装生命周期
|
||
|
||
```bash
|
||
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 时必须使用真实管理员会话：
|
||
|
||
```bash
|
||
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。
|
||
|
||
其他部署方式默认保持关闭。全新安装、单实例升级或停机升级可直接设置：
|
||
|
||
```bash
|
||
SKILLHUB_SUITE_REVIEW_WRITES_ENABLED=true
|
||
```
|
||
|
||
旧版与新版 Server 会同时运行的滚动升级，应在发布新版前保持：
|
||
|
||
```bash
|
||
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 或下载地址。
|