人工智能AI AgentAI 技能后端前端【免费下载链接】skillhubSelf-hosted, open-source agent skill registry for enterprises. Publish version skill packages, govern with RBAC and audit logs, deploy on-premise with Docker or Kubernetes.项目地址https://gitcode.com/gh_mirrors/sk/skillhub点击查看免费下载本文面向 SkillHub 部署运维与内置 Skill 维护者系统讲解如何通过仓库内 manifest 为 SkillHub 配置官方内置 Skills以及应用启动时这些 Skills 如何从受控云存储下载并发布到公共global命名空间。读完本文你将掌握 manifest 的字段规范与约束、zip 包协议要求、URL 白名单安全边界、启动同步的完整调用链、幂等与并发冲突处理策略以及一套可落地的新增/更新/排查/验收操作流程。1. 方案概览审查源码、不可变制品与 manifest 的三层模型内置 Skill 的同步采用源码审查与运行时分发解耦的设计。审查后的 Skill 源码维护在仓库的builtin-skills/skills/目录下但运行时并不直接读取这些目录。整个链路分为三层审查源码层builtin-skills/skills/slug/中保存经过审查、固定到上游 commit 的 Skill 源码含SKILL.md、LICENSE.txt、NOTICE.md及运行所需脚本发布制品层构建脚本生成确定性 zip固定时间戳、固定权限位、ZIP_STORED 不压缩并计算 SHA-256 记录到builtin-skills/dist/artifacts.json随后上传到官方可控的云存储域名形成不可变对象运行时 manifest 层server/skillhub-app/src/main/resources/builtin-skills/manifest.json记录每个内置 Skill 的slug、version、url、sha256应用启动时依据它下载制品并发布。端到端流程如下维护审查后源码 - 校验与打包 - 上传不可变制品 - 更新 manifest - 构建/部署 SkillHub 镜像 - 应用 ready - 下载并校验 zip - 发布到 global核心文件一览均为仓库根目录相对路径builtin-skills/catalog.json builtin-skills/evals.json builtin-skills/skills/slug/ scripts/build-builtin-skills.py server/skillhub-app/src/main/resources/builtin-skills/manifest.json其中 manifest 需要维护四个字段slugSkill 在global下的 slugversion期望同步的 Skill 版本urlSkill zip 包的云存储 HTTPS 链接sha256发布制品内容的 SHA-256小写 64 位十六进制字符串。它是完整性依据不要求 URL 的文件名必须等于 SHA-256CDN 自动生成 UUID 文件名同样可以使用仓库实际 manifest 中的 URL 既有 UUID 文件名也有形如slug/version/sha256.zip的命名。2. Manifest 配置字段规范与单条记录示例server/skillhub-app/src/main/resources/builtin-skills/manifest.json的格式如下{ skills: [ { slug: skillhub-hello, version: 1.0.0, url: https://bjcdn.openstorage.cn/aicontest/2026-06-11/f8a59af3-30d4-4031-80f6-ebff74b05195.zip, sha256: acb591ed0891e735c364b955f5b94b2b9ce567c1d9e347312cebfbfde2d93f57 } ] }2.1 多 Skill、多版本配置可以配置多个 Skills也可以为同一个slug配置多个版本例如历史版本与新版本同时预置便于新实例保留可回退的版本组合{ skills: [ { slug: skillhub-hello, version: 1.0.0, url: https://bjcdn.openstorage.cn/path-to-builtin-skill-zip/skillhub-hello-1.0.0.zip, sha256: sha256-of-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, sha256: sha256-of-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, sha256: sha256-of-skillhub-guide-1.0.0.zip } ] }当前仓库的实际 manifest 已预置 24 个内置 Skill包括skillhub-hello、agentguard、ai-claim-checker、cue-omni-reader、daily-standup-journal、decision-matrix、diagram-maker、documentation-writer、exam-ready、frontend-design、ledger-tasks-yylo、linkedin-post-formatter、meeting-note-summarizer、orca-replay、plugin-scanner、retrieval-practice-generator、sandbase、skillhub-cli、storytelling-advisor、study-strategy-selector、time-blocking-scheduler、triage-nda、video-frames、weather、zero-slop等从中可以观察到 URL 命名风格的两种典型形态——UUID 文件名如f8a59af3-...-b05195.zip和 sha256 文件名如19fd699f...0ea5.zip后者恰好呼应了文件名不必等于 SHA-256的说明。2.2 配置要求与加载期约束配置需满足以下硬性要求skills必须是数组每一项必须同时填写slug、version、url、sha256slug必须符合 SkillHub slug 规则仓库实现中由com.iflytek.skillhub.domain.namespace.SlugValidator校验构建脚本侧对应的正则约为^[a-z0-9](?:-[a-z0-9])*$见 scripts/build-builtin-skills.pysha256必须是小写 64 位十六进制字符串并与 URL 返回的原始 zip 字节一致url最后路径段必须是.zip文件文件名可以是 SHA-256、UUID 或 CDN 生成的不可变名称同一个slug version重复出现时只处理第一条后续重复项会被跳过manifest 最多处理前 100 条 entries同一个slug的多个版本建议按从旧到新的顺序排列运行时按 manifest 文件顺序处理不做自动版本排序。2.3 源码视角manifest 的加载与校验manifest 的解析由 BuiltinSkillManifestLoader.java 完成其行为与文档约束一一对应从classpath:builtin-skills/manifest.json读取常量MANIFEST_LOCATIONMAX_ITEMS 100当 entries 总数超过 100 时记录 warning 并仅处理前 100 条totalEntries MAX_ITEMS时log.warnlimit Math.min(totalEntries, MAX_ITEMS)字段缺失或非字符串时跳过该项并记录slug, version, url, and sha256 are requiredSHA256_PATTERN Pattern.compile([0-9a-f]{64})不匹配时跳过并记录sha256 must be 64 lowercase hexadecimal charactersSlugValidator.validate(slug)失败时跳过记录slug is invalid以slug \n version作为去重键重复项记录Skipping duplicate built-in skill manifest item for slug... version...加载失败文件不存在、JSON 解析失败、skills非数组、根节点为空时不会抛出异常而是记录 warning 并返回空列表保证应用可正常启动。3. Skill 包要求zip 结构与元数据一致性manifest 中的url必须指向 zip 包且 zip 包需要满足 SkillHub Skill 包协议zip 可以在根目录直接包含SKILL.md也可以包含一个单独的顶层 Skill 目录并在该目录下包含SKILL.mdSKILL.mdfrontmatter 中必须包含合法的name、description、version等元数据SKILL.md中的name经过 slug 归一化后必须等于 manifest 中的slugSKILL.md中的version必须等于 manifest 中的version包内容仍会经过 SkillHub 现有发布校验包括文件数量、文件大小、扩展名、文件类型等规则。示例根目录直铺式skillhub-hello-1.0.0.zip ├── SKILL.md ├── LICENSE.txt ├── NOTICE.md └── scripts/ └── check.js同样支持标准单目录 Skill 包skillhub-hello-1.0.0.zip └── skillhub-hello/ ├── SKILL.md ├── LICENSE.txt └── NOTICE.md如果 zip 中存在多个顶层目录或在多个目录中同时出现SKILL.md同步器会跳过该项并记录错误避免误选入口。这一唯一入口约束在 BuiltinSkillPackageExtractor.java 中有明确实现解包结果warnings非空即抛出IllegalArgumentException随后必须存在路径等于SKILL.md的 entrySkillPackagePolicy.SKILL_MD_PATH否则同样抛错。3.1 发布校验在构建期的对应实现上游审查环节的包校验由 scripts/build-builtin-skills.py 执行可以作为包协议的机器可读佐证每个 Skill 目录必须包含SKILL.md、LICENSE.txt、NOTICE.md三个必需文件SKILL.mdfrontmatter 必须有name、description、version、license且name等于目录 slug、version与license必须与catalog.json一致NOTICE.md中必须包含上游repository、commit与license来源溯源门禁文件数上限 500、单文件大小上限 10 MB、包总大小上限 100 MB扩展名必须位于白名单.md、.txt、.json、.py、.sh、.js、.ts、.svg、.png等禁止符号链接打包使用固定 ZIP 时间(1980, 1, 1, 0, 0, 0)与ZIP_STORED从而保证确定性构建——同一源码在任何机器上产出字节完全一致的 zip。catalog.json与evals.json共同构成发布契约catalog.json记录 slug、version、license 与上游 commit/pathevals.json的用例集合必须与 catalog 的 slug 集合完全一致多一个或少一个都直接失败。对应关系可参考 builtin-skills/catalog.json 与 builtin-skills/evals.json。4. URL 安全限制启动期主动下载的强约束内置 Skill 同步由后端在启动时主动下载远程文件相当于服务端发起的外部请求因此 URL 有严格限制这是防止 SSRF 类风险的关键防线。首版只允许https://协议host 为bjcdn.openstorage.cnhost 为bjcdn.openstorage.cn的子域名例如assets.bjcdn.openstorage.cn默认 HTTPS 端口或显式:443。以下 URL 会被跳过http://...非bjcdn.openstorage.cn及其子域名带 userinfo 的 URL例如https://user:passbjcdn.openstorage.cn/file.zip非 443 端口例如https://bjcdn.openstorage.cn:8443/file.ziplocalhost、IP 地址、IPv6 literal 等 host需要 HTTP redirect 才能拿到文件的链接。如果某一项 URL 不符合规则SkillHub 会记录日志并跳过该项不会阻塞应用启动。4.1 下载器的源码级实现BuiltinSkillRemotePackageDownloader.java 将上述约束落为代码isAllowedUrl(URI)依次检查scheme必须是https忽略大小写、getRawUserInfo()必须为 null、端口必须为 -1 或 443、host 归一化小写后必须等于bjcdn.openstorage.cn或以.bjcdn.openstorage.cn结尾isDisallowedHostLiteral拒绝localhost、IPv4 字面量\d{1,3}(\.\d{1,3}){3}以及包含:的 host覆盖 IPv6 literalHttpClient 构造时followRedirects(HttpClient.Redirect.NEVER)任何 3xx 重定向都直接判失败对应测试rejectsRedirectResponsesWithoutReadingLocation连接超时 5 秒、请求超时 30 秒响应体读取也有超时通过虚拟线程 Future 在requestTimeout内取回结果防止慢速流拖垮启动线程响应体读取带大小上限累计读取超过SkillPublishProperties.getMaxPackageSize()时中止并返回空避免下载超大文件非 200 状态码一律视为失败URL 日志输出经过safeUrl脱敏只保留 host 与 path不打印 userinfo 与 query。对应测试 BuiltinSkillRemotePackageDownloaderTest.java 覆盖了https://bjcdn.openstorage.cn/a.zip与子域名放行、http://、evil.com、带 userinfo、:8443端口、127.0.0.1、localhost全部拒绝的判定。5. 启动同步流程从 ApplicationReady 到global发布应用 ready 后同步器会在后台执行一次不阻塞应用 ready。这一行为在源码中体现为BuiltinSkillInitializer的synchronizeAfterApplicationReady()方法同时标注EventListener(ApplicationReadyEvent.class)与Async(skillhubEventExecutor)见 BuiltinSkillInitializer.java测试synchronizesAfterApplicationReadyWithoutBlockingApplicationRunner还专门断言该类未实现ApplicationRunner从而保证启动过程不被拖慢。详细流程与源码synchronize()syncItem()方法一一对应检查skillhub.builtin-skills.enabled是否开启关闭则直接返回并记录Built-in skill startup synchronization is disabled读取classpath:builtin-skills/manifest.json查询global命名空间是否存在如果不存在跳过同步并记录 warning源码namespaceRepository.findBySlug(GLOBAL_NAMESPACE)为空即返回确保系统发布者builtin-skill-publisher存在并且该账号带有系统账号标记ensureSystemPublisher不存在则调用UserAccount.systemAccount(...)创建如果该用户 ID 已被非系统账号占用直接跳过本次内置 Skill 同步不授予global权限记录built-in skill publisher account id ... already exists but is not a system account如果系统发布者还不是global成员则创建OWNER成员记录已有成员记录不会自动改角色findByNamespaceIdAndUserId(...)为空才save(new NamespaceMember(..., OWNER))按 manifest 顺序处理每一个 item处理期间统计published / idempotentSkipped / conflictSkipped / failed四类结果最后统一输出汇总日志下载前先检查global/{slug}和目标版本是否已经存在如果已经确定应跳过则不发起远程下载shouldSkipBeforeDownloadowner 冲突、同版本已存在等场景直接返回跳过结果只有需要发布新 Skill 或新版本时才下载对应 zip 包downloader.download(packageUri)对下载到的原始 zip 字节计算 SHA-256并与 manifest 的sha256比较不一致时停止处理该项记录package checksum mismatch解包并校验 Skill 入口SKILL.mdextractor.extractwarnings 非空或缺少SKILL.md均抛错校验 manifest 中的slug、version与包内元数据一致SlugValidator.slugify(metadata.name())必须等于 manifestslugmetadata.version()必须等于 manifestversion否则分别记录package slug is .../manifest version ... does not match package version ...并跳过发布前再次检查是否已存在同名 Skill 或同版本处理并发启动场景shouldSkipExisting并基于文件指纹判断需要发布时调用现有SkillPublishService.publishFromEntries(GLOBAL_NAMESPACE, entries, SYSTEM_PUBLISHER_ID, SkillVisibility.PUBLIC, Set.of(SUPER_ADMIN), true)发布完成后该 Skill 位于global/{slug}可见性为PUBLIC。同步逻辑不会直接写数据库 seed 数据。它复用现有发布服务publishFromEntries因此会保留现有的包校验、对象存储写入、版本记录、latest version 更新、事件和搜索索引同步——也就是说内置 Skill 与用户手动发布的 Skill 走的是同一条受控链路。6. 幂等与冲突处理重复启动、多实例并发的安全语义内置 Skill 同步支持重复启动和多次部署。幂等键为global/{slug} version行为说明场景行为global/{slug}不存在发布 manifest 中的 Skillglobal/{slug}已存在owner 是builtin-skill-publisher但目标版本不存在发布新版本同版本已存在且已发布下载前跳过同版本已存在但不是PUBLISHED下载前跳过并记录日志global/{slug}已被其他 owner 创建或发布下载前跳过并记录 warning这意味着内置同步不会接管用户或管理员已经创建的同 slug Skill即使该 Skill 仍处于待审、未发布或已拒绝状态也会跳过对应 manifest item。同版本已存在时同步器不会重新下载远端 zip也不会验证远端对象内容是否发生漂移。如果多实例同时启动可能出现多个实例同时尝试发布同一个内置版本。同步器会在发布失败后重新查询目标版本isAlreadyPublishedWithSameFingerprint如果发现同版本已经以相同内容发布成功则视为并发场景下的正常跳过记录was published concurrently, skipping。6.1 文件指纹并发正确性的关键为判断同版本是否以相同内容发布同步器计算包内容指纹而非仅比较版本号对包内 entries 按路径排序逐文件计算 SHA-256将path : sha256 \n串接后再次做 SHA-256得到sha256:hex形式的指纹computeFingerprint(ListPackageEntry)对已发布版本从SkillFileRepository读取文件清单按路径排序、取每个文件的sha256以相同算法计算已有指纹computeFingerprint(SkillVersion)发布前shouldSkipExisting比较两者一致则幂等跳过不一致则记录published fingerprint differs并按冲突跳过避免覆盖内容不一致的同版本。对应集成测试 BuiltinSkillUpgradeConflictIntegrationTest.java 与单测BuiltinSkillInitializerTest分别覆盖了同版本已发布、同版本未发布、他人占用 slug、校验和不匹配、下载失败但后续 item 继续处理、slug/version 与包元数据不一致等路径。7. 开关配置默认开启可按环境关闭内置 Skill 同步默认开启BuiltinSkillProperties中private boolean enabled true见 BuiltinSkillProperties.java。Spring 配置项对应 application.yml 中skillhub.builtin-skills.enabled: ${SKILLHUB_BUILTIN_SKILLS_ENABLED:true}skillhub: builtin-skills: enabled: true环境变量SKILLHUB_BUILTIN_SKILLS_ENABLEDtrue如需禁用启动同步SKILLHUB_BUILTIN_SKILLS_ENABLEDfalse禁用后应用 ready 后不会读取 manifest也不会下载或发布任何内置 Skill测试skipsWhenDisabled断言关闭时manifestLoader与skillPublishService均不被调用。在部署侧开关通过 Helm Chart 透传charts/skillhub/values.yaml中builtinSkills.enabled: true映射到 ConfigMap 的builtin-skills-enabled键再由server-deployment.yaml注入环境变量SKILLHUB_BUILTIN_SKILLS_ENABLED见 values.yaml、configmap.yaml 与 server-deployment.yaml。compose.release.yml同样预留了${SKILLHUB_BUILTIN_SKILLS_ENABLED:-true}的环境变量入口默认开启。8. 维护流程新增与更新内置 Skill8.1 新增一个内置 Skill将固定到上游 commit 的审查后源码加入builtin-skills/skills/slug/在包内保留LICENSE.txt、NOTICE.md在 catalog 和 evals 中登记元数据与回归用例catalog.json记录 slug/version/license/upstreamevals.json记录回归 prompt 与 acceptance/forbidden 断言且用例 slug 集合必须与 catalog 完全一致运行make test-builtin-skills确认包结构、来源、许可证和确定性构建门禁通过运行make build-builtin-skills从builtin-skills/dist/artifacts.json读取制品哈希该文件由 scripts/build-builtin-skills.py 生成记录每个 zip 的slug、version、file、sha256、size上传 zip 到bjcdn.openstorage.cn或其子域名下的不可变路径在server/skillhub-app/src/main/resources/builtin-skills/manifest.json中新增一项同时填写制品 URL 和artifacts.json中对应的 SHA-256本地或测试环境启动 SkillHub查看后端日志确认同步结果在 Web UI 或 API 中确认global/{slug}已公开可见。8.2 更新一个已有内置 Skill不要覆盖已经发布过的旧版本 zip 内容URL 对应对象必须保持不可变在SKILL.md中提升version重新打包并上传新的 zip 文件在 manifest 中新增一条同slug、新version的记录保留旧版本记录除非产品明确不再需要该旧版本在新实例中预置。8.3 不推荐的做法修改旧版本 zip 内容但保持同一个version会导致指纹漂移与内容不一致风险把 URL 指向会发生内容变化的临时对象使用需要登录、签名跳转或重定向的下载链接下载器Redirect.NEVER与 userinfo 拦截会直接拒绝。另外builtin-skills/README.md还给出了社区贡献准则共享 Skill 需声明作者、来源与可再分发许可、声明依赖工具与网络/凭据需求、通过包校验与安全审查、至少通过一个真实场景测试提交以新增builtin-skills/skills/slug/包 catalog.jsonevals.jsonmake test-builtin-skills通过为完整形态。9. 日志与排查启动期同步的观测手段启动时可以通过后端日志观察同步结果。BuiltinSkillInitializer.synchronize()在结束时输出汇总Built-in skill synchronization finished: total..., published..., idempotentSkipped..., conflictSkipped..., failed...常见日志含义与处理建议日志含义处理建议manifest not found确认builtin-skills/manifest.json是否被打进 classpathpublisher account id already exists but is not a system accountbuiltin-skill-publisher已被普通账号占用需要人工处理账号冲突后再启用内置同步slug, version, url, and sha256 are required检查 manifest item 是否缺字段或字段不是字符串slug is invalid检查 slug 是否符合 SkillHub slug 规则sha256 must be 64 lowercase hexadecimal characters使用builtin-skills/dist/artifacts.json中对应制品的 SHA-256URL is not allowed检查 URL 是否为 HTTPS、host 是否为bjcdn.openstorage.cn或其子域名package download failed检查云存储对象是否存在、是否返回 HTTP 200、是否超时package checksum mismatch云端对象与 manifest 固定的制品不一致不要继续解包或发布检查是否上传错误或对象被覆盖package must contain SKILL.md检查 zip 是否存在唯一可识别的SKILL.md入口manifest version does not match package version检查 manifestversion和SKILL.md version是否一致slug already belongs to another user说明global/{slug}已被非内置发布者创建或发布内置同步不会覆盖published fingerprint differs并发发布异常后发现同一内置版本已存在但内容不同需要人工确认是否发生了版本冲突如果某个 manifest item 失败后续 item 仍会继续处理应用可用状态不受影响对应测试continuesWithLaterManifestItemWhenEarlierDownloadFails明确验证了这一行为。10. 验收检查配置后的完整自检清单配置或新增内置 Skill 后建议至少完成以下检查make test-builtin-skills通过且 15 个回归用例都有对应包catalog 与 evals 的 slug 集合一一对应manifest JSON 格式合法每个 item 都包含slug、version、url、sha256每个sha256都与 URL 下载到的原始 zip 字节一致URL 使用https://bjcdn.openstorage.cn/...或可信子域名并以.zip结尾文件名不必等于 SHA-256zip 根目录直接包含SKILL.md或只有一个顶层 Skill 目录且该目录包含SKILL.mdSKILL.md name归一化后的 slug 与 manifestslug一致SKILL.md version与 manifestversion一致启动日志没有该 item 的 warning 或 errorWeb UI 中可以看到global/{slug}Skill 可被匿名或登录用户按公开 Skill 规则发现。11. 小结SkillHub 的云存储内置 Skills 机制本质是一条审查源码 → 确定性制品 → 不可变 CDN 对象 → manifest 声明 → 启动期同步发布的可审计流水线。它通过 manifest 四字段slug/version/url/sha256把制品位置与完整性固化到代码仓库通过 URL 白名单与关闭重定向控制服务端外联风险通过复用SkillPublishService保留完整的包校验、存储、版本、事件与搜索索引链路并通过幂等键global/{slug} version与文件指纹保证重复部署和多实例并发的安全。对部署方而言只需维护好 manifest 与不可变对象即可让每个新实例开箱即用地预置一组经过审查、来源可溯的官方内置 Skills。赞分享人工智能AI AgentAI 技能后端前端【免费下载链接】skillhubSelf-hosted, open-source agent skill registry for enterprises. Publish version skill packages, govern with RBAC and audit logs, deploy on-premise with Docker or Kubernetes.项目地址https://gitcode.com/gh_mirrors/sk/skillhub点击查看免费下载相关推荐Harvester UI 暴露 CDI 存储配置注解驱动的 StorageClass 到 CDI/StorageProfile 同步机制Harvester UI 暴露 CDI 存储配置注解驱动的 StorageClass 到 CDI/StorageProfile 同步机制 本文基于 Harve云原生虚拟化存储后端高可用如何永久保存微信聊天记录WeChatMsg让你的数字记忆永不丢失如何永久保存微信聊天记录WeChatMsg让你的数字记忆永不丢失 你是否曾经因为更换手机而丢失了珍贵的聊天记录那些与家人的温馨对话、朋友间的美好回忆、工作中Distribution Registry 存储驱动Storage Driver完全指南架构、内置驱动与配置实践Distribution Registry 存储驱动Storage Driver完全指南架构、内置驱动与配置实践 本指南以 docs/content/st镜像仓库后端存储云原生上一篇Flagsmith 的 CVE 与漏洞报告解读指南供应链扫描机制、扫描结果研判与安全上报流程下一篇FanControl全面指南5分钟掌握Windows风扇智能控制技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考