Merge pull request #498 from iflytek/feature/cloud-url-builtin-skills

feat(bootstrap): sync built-in skills from cloud manifest

Author: dongmucat

docs/20-cloud-url-builtin-skills-setup.md

@@ -0,0 +1,269 @@
+# 云存储链接内置 Skills 配置指南
+
+本文说明如何通过仓库内 manifest 配置 SkillHub 内置 Skills，以及应用启动时这些 Skills 如何从云存储同步到 `@global` 空间。
+
+适用场景：
+
+- 希望 SkillHub 新部署实例默认带有一批官方内置 Skills。
+- 不希望把完整 Skill 包目录长期放在代码仓库和镜像中。
+- 内置 Skill 包已经上传到官方可控的云存储域名。
+
+## 1. 方案概览
+
+内置 Skills 不再以本地目录包的形式直接随仓库维护。当前方案只在仓库中维护一个 manifest 文件，应用启动时根据 manifest 中的云存储 URL 下载 zip 包，并通过 SkillHub 现有发布链路发布到 `@global`。
+
+流程：
+
+```text
+维护 manifest -> 构建/部署 SkillHub 镜像 -> 应用 ready -> 后台读取 manifest -> 下载云存储 zip 包 -> 校验包内容 -> 发布到 @global -> 对所有用户公开可见
+```
+
+核心文件：
+
+```text
+server/skillhub-app/src/main/resources/builtin-skills/manifest.json
+```
+
+首版 manifest 只需要维护三个字段：
+
+- `slug`：Skill 在 `@global` 下的 slug。
+- `version`：期望同步的 Skill 版本。
+- `url`：Skill zip 包的云存储 HTTPS 链接。
+
+## 2. Manifest 配置
+
+manifest 文件格式如下：
+
+```json
+{
+  "skills": [
+    {
+      "slug": "skillhub-hello",
+      "version": "1.0.0",
+      "url": "https://bjcdn.openstorage.cn/<path-to-builtin-skill-zip>/skillhub-hello-1.0.0.zip"
+    }
+  ]
+}
+```
+
+可以配置多个 Skills，也可以为同一个 `slug` 配置多个版本：
+
+```json
+{
+  "skills": [
+    {
+      "slug": "skillhub-hello",
+      "version": "1.0.0",
+      "url": "https://bjcdn.openstorage.cn/<path-to-builtin-skill-zip>/skillhub-hello-1.0.0.zip"
+    },
+    {
+      "slug": "skillhub-hello",
+      "version": "1.1.0",
+      "url": "https://bjcdn.openstorage.cn/<path-to-builtin-skill-zip>/skillhub-hello-1.1.0.zip"
+    },
+    {
+      "slug": "skillhub-guide",
+      "version": "1.0.0",
+      "url": "https://bjcdn.openstorage.cn/<path-to-builtin-skill-zip>/skillhub-guide-1.0.0.zip"
+    }
+  ]
+}
+```
+
+配置要求：
+
+- `skills` 必须是数组。
+- 每一项必须同时填写 `slug`、`version`、`url`。
+- `slug` 必须符合 SkillHub slug 规则。
+- 同一个 `slug + version` 重复出现时，只处理第一条，后续重复项会被跳过。
+- manifest 最多处理前 100 条 entries。
+- 同一个 `slug` 的多个版本建议按从旧到新的顺序排列；运行时按 manifest 文件顺序处理，不做自动版本排序。
+
+## 3. Skill 包要求
+
+manifest 中的 `url` 必须指向 zip 包。zip 包需要满足 SkillHub Skill 包协议：
+
+- zip 可以在根目录直接包含 `SKILL.md`，也可以包含一个单独的顶层 Skill 目录，并在该目录下包含 `SKILL.md`。
+- `SKILL.md` frontmatter 中必须包含合法的 `name`、`description`、`version` 等元数据。
+- `SKILL.md` 中的 `name` 经过 slug 归一化后，必须等于 manifest 中的 `slug`。
+- `SKILL.md` 中的 `version` 必须等于 manifest 中的 `version`。
+- 包内容仍会经过 SkillHub 现有发布校验，包括文件数量、文件大小、扩展名、文件类型等规则。
+
+示例：
+
+```text
+skillhub-hello-1.0.0.zip
+├── SKILL.md
+├── README.md
+└── scripts/
+    └── check.js
+```
+
+同样支持标准单目录 Skill 包：
+
+```text
+skillhub-hello-1.0.0.zip
+└── skillhub-hello/
+    ├── SKILL.md
+    └── README.md
+```
+
+如果 zip 中存在多个顶层目录，或在多个目录中同时出现 `SKILL.md`，同步器会跳过该项并记录错误，避免误选入口。
+
+## 4. URL 安全限制
+
+内置 Skill 同步由后端在启动时主动下载远程文件，因此 URL 有严格限制。
+
+首版只允许：
+
+- `https://` 协议。
+- host 为 `bjcdn.openstorage.cn`。
+- host 为 `bjcdn.openstorage.cn` 的子域名，例如 `assets.bjcdn.openstorage.cn`。
+- 默认 HTTPS 端口，或显式 `:443`。
+
+以下 URL 会被跳过：
+
+- `http://...`
+- 非 `bjcdn.openstorage.cn` 及其子域名。
+- 带 userinfo 的 URL，例如 `https://user:pass@bjcdn.openstorage.cn/file.zip`。
+- 非 443 端口，例如 `https://bjcdn.openstorage.cn:8443/file.zip`。
+- `localhost`、IP 地址、IPv6 literal 等 host。
+- 需要 HTTP redirect 才能拿到文件的链接。
+
+如果某一项 URL 不符合规则，SkillHub 会记录日志并跳过该项，不会阻塞应用启动。
+
+## 5. 启动同步流程
+
+应用 ready 后同步器会在后台执行一次，不阻塞应用 ready。
+
+详细流程：
+
+1. 检查 `skillhub.builtin-skills.enabled` 是否开启。
+2. 读取 `classpath:builtin-skills/manifest.json`。
+3. 查询 `@global` 命名空间是否存在；如果不存在，跳过同步。
+4. 确保系统发布者 `builtin-skill-publisher` 存在，并且该账号带有系统账号标记。
+5. 如果该用户 ID 已被非系统账号占用，直接跳过本次内置 Skill 同步，不授予 `@global` 权限。
+6. 如果系统发布者还不是 `@global` 成员，则创建 `OWNER` 成员记录；已有成员记录不会自动改角色。
+7. 按 manifest 顺序处理每一个 item。
+8. 下载前先检查 `@global/{slug}` 和目标版本是否已经存在；如果已经确定应跳过，则不发起远程下载。
+9. 只有需要发布新 Skill 或新版本时，才下载对应 zip 包。
+10. 解包并校验 Skill 入口 `SKILL.md`。
+11. 校验 manifest 中的 `slug`、`version` 与包内元数据一致。
+12. 发布前再次检查是否已存在同名 Skill 或同版本，处理并发启动场景。
+13. 需要发布时调用现有 `SkillPublishService.publishFromEntries(...)`。
+14. 发布完成后，该 Skill 位于 `@global/{slug}`，可见性为 `PUBLIC`。
+
+同步逻辑不会直接写数据库 seed 数据。它复用现有发布服务，因此会保留现有的包校验、对象存储写入、版本记录、latest version 更新、事件和搜索索引同步。
+
+## 6. 幂等与冲突处理
+
+内置 Skill 同步支持重复启动和多次部署。
+
+幂等键：
+
+```text
+@global/{slug} + version
+```
+
+行为说明：
+
+| 场景 | 行为 |
+|---|---|
+| `@global/{slug}` 不存在 | 发布 manifest 中的 Skill |
+| `@global/{slug}` 已存在，owner 是 `builtin-skill-publisher`，但目标版本不存在 | 发布新版本 |
+| 同版本已存在且已发布 | 下载前跳过 |
+| 同版本已存在但不是 `PUBLISHED` | 下载前跳过并记录日志 |
+| `@global/{slug}` 已被其他 owner 创建或发布 | 下载前跳过并记录 warning |
+
+这意味着内置同步不会接管用户或管理员已经创建的同 slug Skill；即使该 Skill 仍处于待审、未发布或已拒绝状态，也会跳过对应 manifest item。
+同版本已存在时，同步器不会重新下载远端 zip，也不会验证远端对象内容是否发生漂移。
+
+如果多实例同时启动，可能出现多个实例同时尝试发布同一个内置版本。同步器会在发布失败后重新查询目标版本；如果发现同版本已经以相同内容发布成功，则视为并发场景下的正常跳过。
+
+## 7. 开关配置
+
+内置 Skill 同步默认开启。
+
+Spring 配置项：
+
+```yaml
+skillhub:
+  builtin-skills:
+    enabled: true
+```
+
+环境变量：
+
+```dotenv
+SKILLHUB_BUILTIN_SKILLS_ENABLED=true
+```
+
+如需禁用启动同步：
+
+```dotenv
+SKILLHUB_BUILTIN_SKILLS_ENABLED=false
+```
+
+禁用后，应用 ready 后不会读取 manifest，也不会下载或发布任何内置 Skill。
+
+## 8. 维护流程
+
+新增一个内置 Skill 的推荐步骤：
+
+1. 准备 Skill 包，并确认 zip 根目录直接包含 `SKILL.md`，或只有一个顶层 Skill 目录且该目录包含 `SKILL.md`。
+2. 检查 `SKILL.md` 中的 `name` 和 `version`。
+3. 上传 zip 到 `bjcdn.openstorage.cn` 或其子域名下的官方云存储路径。
+4. 在 `server/skillhub-app/src/main/resources/builtin-skills/manifest.json` 中新增一项。
+5. 确保 manifest 中的 `slug` 等于 `SKILL.md name` 归一化后的 slug。
+6. 确保 manifest 中的 `version` 等于 `SKILL.md version`。
+7. 本地或测试环境启动 SkillHub，查看后端日志确认同步结果。
+8. 在 Web UI 或 API 中确认 `@global/{slug}` 已公开可见。
+
+更新一个已有内置 Skill 的推荐步骤：
+
+1. 不要覆盖已经发布过的旧版本 zip 内容。
+2. 在 `SKILL.md` 中提升 `version`。
+3. 重新打包并上传新的 zip 文件。
+4. 在 manifest 中新增一条同 `slug`、新 `version` 的记录。
+5. 保留旧版本记录，除非产品明确不再需要该旧版本在新实例中预置。
+
+不推荐：
+
+- 修改旧版本 zip 内容但保持同一个 `version`。
+- 把 URL 指向会发生内容变化的临时对象。
+- 使用需要登录、签名跳转或重定向的下载链接。
+
+## 9. 日志与排查
+
+启动时可以通过后端日志观察同步结果。
+
+常见日志含义：
+
+| 日志含义 | 处理建议 |
+|---|---|
+| manifest not found | 确认 `builtin-skills/manifest.json` 是否被打进 classpath |
+| publisher account id already exists but is not a system account | `builtin-skill-publisher` 已被普通账号占用；需要人工处理账号冲突后再启用内置同步 |
+| slug, version, and url are required | 检查 manifest item 是否缺字段或字段不是字符串 |
+| slug is invalid | 检查 slug 是否符合 SkillHub slug 规则 |
+| URL is not allowed | 检查 URL 是否为 HTTPS、host 是否为 `bjcdn.openstorage.cn` 或其子域名 |
+| package download failed | 检查云存储对象是否存在、是否返回 HTTP 200、是否超时 |
+| package must contain SKILL.md | 检查 zip 是否存在唯一可识别的 `SKILL.md` 入口 |
+| manifest version does not match package version | 检查 manifest `version` 和 `SKILL.md version` 是否一致 |
+| slug already belongs to another user | 说明 `@global/{slug}` 已被非内置发布者创建或发布，内置同步不会覆盖 |
+| published fingerprint differs | 并发发布异常后发现同一内置版本已存在但内容不同，需要人工确认是否发生了版本冲突 |
+
+如果某个 manifest item 失败，后续 item 仍会继续处理，应用可用状态不受影响。
+
+## 10. 验收检查
+
+配置或新增内置 Skill 后，建议至少完成以下检查：
+
+- manifest JSON 格式合法。
+- 每个 item 都包含 `slug`、`version`、`url`。
+- URL 使用 `https://bjcdn.openstorage.cn/...` 或可信子域名。
+- zip 根目录直接包含 `SKILL.md`，或只有一个顶层 Skill 目录且该目录包含 `SKILL.md`。
+- `SKILL.md name` 归一化后的 slug 与 manifest `slug` 一致。
+- `SKILL.md version` 与 manifest `version` 一致。
+- 启动日志没有该 item 的 warning 或 error。
+- Web UI 中可以看到 `@global/{slug}`。
+- Skill 可被匿名或登录用户按公开 Skill 规则发现。

server/skillhub-app/src/main/java/com/iflytek/skillhub/SkillhubApplication.java

@@ -1,5 +1,6 @@
 package com.iflytek.skillhub;
 
+import com.iflytek.skillhub.bootstrap.BuiltinSkillProperties;
 import com.iflytek.skillhub.config.ProfileFieldPolicyProperties;
 import com.iflytek.skillhub.config.ProfileModerationProperties;
 import org.springframework.boot.SpringApplication;
@@ -10,7 +11,11 @@
  * Main Spring Boot entry point for the SkillHub backend application.
  */
 @SpringBootApplication
-@EnableConfigurationProperties({ProfileModerationProperties.class, ProfileFieldPolicyProperties.class})
+@EnableConfigurationProperties({
+        BuiltinSkillProperties.class,
+        ProfileModerationProperties.class,
+        ProfileFieldPolicyProperties.class
+})
 public class SkillhubApplication {
     public static void main(String[] args) {
         SpringApplication.run(SkillhubApplication.class, args);