SkillHub 是一个自托管平台，为团队提供一个私有且受管控的空间来共享智能体技能。发布一个技能包，推送到一个命名空间，并通过搜索发现或通过 CLI 安装。专为防火墙后的本地部署而构建，同时具备公共注册表所期望的 polished 体验。 ## 文档 - 📖 **[用户指南](https://iflytek.github.io/skillhub/)** — 技能发布、搜索、CLI 使用及其他用户指南 - 🛠️ **[开发者文档](https://zread.ai/iflytek/skillhub)** — 架构、API 参考、本地开发、部署与运维 ## 亮点 - **自托管与私有** — 在您自己的基础设施上部署。 在防火墙后保持专有技能的完全数据主权。使用一条 `make dev-all` 命令即可在本地运行。 - **发布与版本管理** — 使用语义化版本、自定义标签（`beta`、`stable`）和自动 `latest` 跟踪来上传智能体技能包。 - **发现** — 全文搜索，支持按命名空间、下载量、评分和最新性过滤。可见性规则确保用户只能看到他们被授权的内容。 - **团队命名空间** — 在团队或全局范围内组织技能。 每个命名空间拥有独立的成员、角色（所有者 / 管理员 / 成员）和发布策略。 - **审核与治理** — 团队管理员在其命名空间内进行审核；平台管理员对提升到全局范围进行管控。治理操作会被审计记录以满足合规要求。 - **社交功能** — 为技能点赞、评分并跟踪下载量。围绕组织最佳实践构建社区。 - **账户合并** — 将多个 OAuth 身份和 API 令牌整合到单个用户账户下。 - **API 令牌管理** — 生成作用域化的令牌，用于 CLI 和程序化访问，并支持基于前缀的安全哈希。 - **CLI 优先** — 原生 REST API 以及对现有 ClawHub 风格注册表客户端的兼容层。原生 CLI API 是主要支持路径，同时持续扩展协议兼容性。 - **可插拔存储** — 开发环境使用本地文件系统，生产环境使用 S3 / MinIO。通过配置切换。 - **国际化** — 基于 i18next 的多语言支持。 ## 快速开始 使用以下命令启动完整本地堆栈： ``` rm -rf /tmp/skillhub-runtime curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up ``` 默认命令会拉取 `latest` 稳定版镜像。如需获取 `main` 分支的最新构建，请使用 `--version edge`。 **配置公共 URL（生产环境推荐）：** ``` curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --public-url https://skillhub.your-company.com ``` `--public-url` 参数会为您的 SkillHub 实例设置公共访问 URL。这将确保： - CLI 安装命令显示正确的注册表 URL - 智能体设置说明显示正确的 skill.md URL - OAuth 回调和设备授权链接正常工作 **在中国地区用户（阿里云镜像）：** ``` curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --public-url https://skillhub.your-company.com --version latest ``` 如果部署遇到问题，请清除现有运行时主目录并重试。 ### 先决条件 - Docker & Docker Compose ### 本地开发 ``` make dev-all ``` 然后打开： - Web UI：`http://localhost:3000` - 后端 API：`http://localhost:8080` 默认情况下，`make dev-all` 会使用 `local` 配置文件启动后端。 在此模式下，本地开发会保留模拟认证用户，并默认 创建一个基于密码的引导管理员账户： - `local-user` 用于正常的发布和命名空间操作 - `local-admin` 拥有 `SUPER_ADMIN` 权限，用于审核和管理流程 在本地开发中，请使用 `X-Mock-User-Id` 请求头使用它们。 本地引导管理员默认在 `application-local.yml` 中启用： - 用户名：`admin` - 密码：`ChangeMe!2026` - 如需禁用，请在启动后端前设置 `BOOTSTRAP_ADMIN_ENABLED=false`。 停止所有服务： ``` make dev-all-down ``` 重置本地依赖并从干净状态开始： ``` make dev-all-reset ``` 运行 `make help` 查看所有可用命令。 有用的后端命令： ``` make test make test-backend-app make build-backend-app ``` 不要在 `server/` 目录下直接运行 `./mvnw -pl skillhub-app clean test`。 `skillhub-app` 依赖于同级模块，单体干净构建可能回退到本地 Maven 仓库中的陈旧构件，导致模糊的 `cannot find symbol` 和签名不匹配错误。请使用 `-am`，或上述 `make test-backend-app` 和 `make build-backend-app` 目标。 完整的开发流程（本地开发 → 预发布 → PR），请参考 [docs/dev-workflow.md](docs/dev-workflow.md)。 ### API 契约同步 Web 客户端的 OpenAPI 类型已提交到仓库。 当后端 API 契约变更时，请重新生成 SDK 并提交更新后的生成文件： ``` make generate-api ``` 如需更严格的端到端漂移检查，请运行： ``` ./scripts/check-openapi-generated.sh ``` 这将启动本地依赖，启动后端，重新生成前端架构，并在已提交的 SDK 过时时失败。 ### 容器运行时 已发布的运行时镜像由 GitHub Actions 构建并推送到 GHCR。 这是希望在不构建后端或前端的情况下获得即用型本地环境的任何人所支持的路径。 已发布的镜像同时支持 `linux/amd64` 和 `linux/arm64`。 **使用 curl 快速部署：** ``` # 默认 (GHCR 镜像) curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --public-url https://skillhub.your-company.com # 阿里云镜像 (推荐给中国用户) curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --public-url https://skillhub.your-company.com --version latest ``` **部署参数：** | 参数 | 描述 | 示例 | |-----------|-------------|---------| | `--public-url ` | 公共访问 URL（推荐） | `--public-url https://skill.example.com` | | `--version ` | 特定镜像标签 | `--version v0.2.0` | | `--aliyun` | 使用阿里云镜像（中国） | `--aliyun` | | `--home ` | 运行时目录 | `--home /opt/skillhub` | | `--no-scanner` | 禁用安全扫描器 | `--no-scanner` | **手动部署：** 1. 复制运行时环境模板。 2. 选择一个镜像标签。 3. 使用 Docker Compose 启动堆栈。 ``` cp .env.release.example .env.release ``` 推荐镜像标签： - `SKILLHUB_VERSION=latest` 表示最新的稳定版本（默认） - `SKILLHUB_VERSION=edge` 表示最新的 `main` 构建 - `SKILLHUB_VERSION=vX.Y.Z` 表示固定版本 启动运行时： ``` make validate-release-config docker compose --env-file .env.release -f compose.release.yml up -d ``` 然后打开： - Web UI：`SKILLHUB_PUBLIC_BASE_URL` 对应的地址 - 后端 API：`http://localhost:8080` 停止它： ``` docker compose --env-file .env.release -f compose.release.yml down ``` 运行时堆栈使用自己的 Compose 项目名称，因此不会与 `make dev-all` 的容器冲突。 生产 Compose 堆栈现在默认仅使用 `docker` 配置文件。 它不会启用本地模拟认证。发布模板（`.env.release.example`）默认启用引导管理员，因此通过 `runtime.sh` 的快速启动开箱即用： - 用户名：`admin` - 密码：`ChangeMe!2026` 推荐生产基线： - 设置 `SKILLHUB_PUBLIC_URL` 为最终的 HTTPS 入口点 - 保持 PostgreSQL / Redis 绑定到 `127.0.0.1` - 通过 `SKILLHUB_STORAGE_S3_*` 使用外部 S3 / OSS - 将 `BOOTSTRAP_ADMIN_PASSWORD` 改为强密码（`validate-release-config.sh` 会拒绝默认的 `ChangeMe!2026`） - 初始化后轮换或禁用引导管理员 - 在运行 `docker compose up -d` 前执行 `make validate-release-config` 如果 GHCR 包仍为私有，请在运行 `docker compose up -d` 前执行 `docker login ghcr.io`。 ### 上传允许列表覆盖 技能包上传验证使用来自 [`SkillPackagePolicy.java`](./server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/validation/SkillPackagePolicy.java) 的默认扩展允许列表。 `SkillPublishProperties` 默认使用该列表作为 `skillhub.publish.allowed-file-extensions`。 如需在运行时替换默认允许列表，请设置： ``` SKILLHUB_PUBLISH_ALLOWED_FILE_EXTENSIONS=.md,.json,.xsd,.xsl,.dtd,.docx,.xlsx,.pptx ``` Spring Boot 将此环境变量绑定到 `skillhub.publish.allowed-file-extensions`。设置后会替换默认允许列表而非追加。 ### 监控 Prometheus + Grafana 监控堆栈位于 [`monitoring/`](./monitoring)。 它会抓取后端的 Actuator Prometheus 端点。 使用以下命令启动： ``` cd monitoring docker compose -f docker-compose.monitoring.yml up -d ``` 然后打开： - Prometheus：`http://localhost:9090` - Grafana：`http://localhost:3001`（`admin` / `admin`） 默认情况下，Prometheus 会抓取 `http://host.docker.internal:8080/actuator/prometheus`， 因此请先在本地的 8080 端口启动后端。 ## Kubernetes Kubernetes 基本清单文件位于 [`deploy/k8s/`](./deploy/k8s)： - `configmap.yaml` - `secret.yaml.example` - `backend-deployment.yaml` - `frontend-deployment.yaml` - `services.yaml` - `ingress.yaml` 创建好您的密钥后应用它们： ``` kubectl apply -f deploy/k8s/configmap.yaml kubectl apply -f deploy/k8s/secret.yaml kubectl apply -f deploy/k8s/backend-deployment.yaml kubectl apply -f deploy/k8s/frontend-deployment.yaml kubectl apply -f deploy/k8s/services.yaml kubectl apply -f deploy/k8s/ingress.yaml ``` ## 烟雾测试 轻量级烟雾测试脚本在 [`scripts/smoke-test.sh`](./scripts/smoke-test.sh) 中可用。 针对本地后端运行： ``` ./scripts/smoke-test.sh http://localhost:8080 ``` ## 架构 ``` ┌─────────────┐ ┌─────────────┐ ┌──────────────┐ │ Web UI │ │ CLI Tools │ │ REST API │ │ (React 19) │ │ │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬───────┘ │ │ │ └───────────────────┼───────────────────┘ │ ┌──────▼──────┐ │ Nginx │ └──────┬──────┘ │ ┌──────▼──────┐ │ Spring Boot │ Auth · RBAC · Core Services │ (Java 21) │ OAuth2 · API Tokens · Audit └──────┬──────┘ │ ┌────────────┼────────────┐ │ │ │ ┌──────▼───┐ ┌─────▼────┐ ┌────▼────┐ │PostgreSQL│ │ Redis │ │ Storage │ │ 16 │ │ 7 │ │ S3/MinIO│ └──────────┘ └──────────┘ └─────────┘ ``` **后端（Spring Boot 3.2.3，Java 21）：** - 整洁架构的多模块 Maven 项目 - 模块：app、domain、auth、search、storage、infra - PostgreSQL 16 与 Flyway 迁移 - Redis 用于会话管理 - S3/MinIO 用于技能包存储 **前端（React 19，TypeScript，Vite）：** - TanStack Router 用于路由 - TanStack Query 用于数据获取 - Tailwind CSS + Radix UI 用于样式 - OpenAPI TypeScript 用于类型安全的 API 客户端 - i18next 用于国际化 ## 与代理平台的使用 SkillHub 可作为多个代理平台的技能注册表后端。将以下客户端指向您的 SkillHub 实例即可发布、发现和安装技能。 ### [OpenClaw](https://github.com/openclaw/openclaw) [OpenClaw](https://github.com/openclaw/openclaw) 是一个开源智能体技能 CLI。将其配置为使用您的 SkillHub 端点作为注册表： ``` # 配置注册表 URL export CLAWHUB_REGISTRY=https://skillhub.your-company.com # 如需则认证一次 clawhub login --token YOUR_API_TOKEN # 搜索并安装技能 npx clawhub search email npx clawhub install my-skill npx clawhub install my-namespace--my-skill # 发布到全局命名空间 npx clawhub publish ./my-skill --slug my-skill --version 1.0.0 # 发布到团队命名空间，例如 my-space npx clawhub publish ./my-skill --slug my-space--my-skill --version 1.0.0 ``` `my-space--my-skill` 是规范兼容标识符。SkillHub 会将其解析为 命名空间 `my-space` 加上技能标识符 `my-skill`。 📖 **[完整的 OpenClaw 集成指南 →](./docs/openclaw-integration.md)** ### [AstronClaw](https://agent.xfyun.cn/astron-claw) [AstronClaw](https://agent.xfyun.cn/astron-claw) 是一个基于 OpenClaw 核心能力的云 AI 助手，通过企业平台（如 WeChat Work、DingTalk、Feishu）提供 24/7 在线服务。它具备内置技能系统，包含 130 多个官方技能。您可以将其连接到自托管的 SkillHub 注册表，以实现一键技能安装、搜索仓库、基于对话的自动安装，甚至是在组织内自定义技能管理。 ### [Loomy](https://loomy.xunfei.cn/) [Loomy](https://loomy.xunfei.cn/) 是一个专注于真实办公场景的桌面 AI 工作伙伴。它深度集成本地文件和系统工具，为个人和小团队构建高效的自动化工作流。通过将 Loomy 连接到您的 SkillHub 注册表，您可以轻松发现和安装组织特定的技能，以增强本地桌面自动化和生产力。 ### [astron-agent](https://github.com/iflytek/astron-agent) [astron-agent](https://github.com/iflytek/astron-agent) 是 iFlytek Astron 代理框架。存储在 SkillHub 中的技能可以被 astron-agent 引用和加载，从而实现从开发到生产的受控、版本化技能生命周期。 ## 贡献 欢迎贡献。请先打开一个议题来讨论您希望进行的更改。 - 贡献指南： [`CONTRIBUTING.md`](./CONTRIBUTING.md) - 行为准则： [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) ## 📞 支持 - 💬 **社区讨论**：[GitHub Discussions](https://github.com/iflytek/skillhub/discussions) - 🐛 **错误报告**：[问题跟踪](https://github.com/iflytek/skillhub/issues) - 👾 **Discord**：[加入我们的服务器](https://discord.gg/qHYvtDNPHS) - 👥 **微信工作组**：  ## 许可证 Apache License 2.0

标签：Agent 技能, API集成, Docker, Java 21, MLOps, on-premise, RBAC, React, SEO, Syscalls, 企业级, 前后端分离, 可观测性, 合规, 命名空间, 域名枚举, 子域名突变, 安全防御评估, 审计日志, 开发者文档, 开源, 技能包, 技能发布, 技能发现, 技能平台, 技能治理, 技能注册中心, 技能注册表, 技能管理, 搜索, 搜索引擎查询, 文档, 权限控制, 模型即服务, 模型技能, 测试用例, 版本管理, 用户指南, 私有化部署, 私有部署, 组织内部共享, 自托管, 请求拦截, 防御规避, 防火墙, 集中管理