scriptoriumadmin/skillhub
1
0
Fork 0
mirror of https://github.com/iflytek/skillhub.git synced 2026-08-27 11:14:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: publish SkillHub website

Browse source
This commit is contained in:
FenjuFu 2026-07-23 12:23:22 +08:00
parent ac46ad5391
commit ddda14b3e6
116 changed files with 5432 additions and 1342 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
document/.gitignore vendored
View file

@ -18,3 +18,5 @@ build
.vscode
*.swp
*.swo
.vercel

40
document/README.md Normal file
View file

@ -0,0 +1,40 @@
# SkillHub Docs Site
`document/` contains the Docusaurus source for the public documentation site served at `https://www.astron-skillhub.org/`.
## Local Development
Install dependencies:
```bash
cd document
npm install
```
Start the docs dev server:
```bash
npm run start
```
Build the production site:
```bash
npm run build
```
## Publishing
The repository includes a GitHub Actions workflow at `.github/workflows/publish-docs-site.yml`.
- Pushes to `main` that modify `document/**` or the workflow file trigger an automatic docs build and GitHub Pages deployment
- The custom domain is configured through `document/static/CNAME`
- Legacy website URLs such as `quickstart.html` and `guide/skill-publish.html` are redirected to the current Docusaurus routes via `plugin-client-redirects`
## Sync Rule
To keep `https://www.astron-skillhub.org/` aligned with the latest repository content:
- Treat `document/` as the source of truth for the public docs site
- Update `document/docs/**` whenever product messaging or public-facing workflow documentation changes materially
- Keep redirects updated when replacing or renaming public routes

4
document/docs/01-getting-started/_category_.json
View file

@ -1,8 +1,8 @@
{
"label": "快速入门",
"label": "Getting Started",
"position": 1,
"link": {
"type": "generated-index",
"description": "快速了解并开始使用 SkillHub"
"description": "Quickly understand and start using SkillHub"
}
}

98
document/docs/01-getting-started/overview.md
View file

@ -1,70 +1,70 @@
---
title: 产品概述
title: Overview
sidebar_position: 1
description: SkillHub 产品概述和核心特性介绍
description: SkillHub product overview and core features
---
# 产品概述
# Overview
SkillHub 是企业级 AI 技能注册平台，支持技能发布、发现与管理，采用自托管架构保障数据安全。
SkillHub is an enterprise-grade AI skill registry platform for publishing, discovering, and managing skills with a self-hosted architecture ensuring data security.
## 核心特性
## Core Features
### 发布管理
- 版本控制与语义化版本（Semantic Versioning）
- 自定义标签（如 `beta`/`stable`）
- `latest` 标签自动跟随最新发布版本
### Publishing Management
- Version control and Semantic Versioning
- Custom tags (like `beta`/`stable`)
- `latest` tag automatically follows the latest published version
### 发现机制
- 全文搜索
- 多维度筛选（命名空间、下载量、评分）
- 可见性控制（公开/命名空间内/私有）
### Discovery
- Full-text search
- Multi-dimensional filtering (namespace, downloads, ratings)
- Visibility control
### 组织架构
- 命名空间隔离
- 基于角色的访问控制（RBAC）
- 团队与全局双层空间
### Organization
- Namespace isolation
- Role-based access control (RBAC)
- Team and global two-tier scopes
### 治理体系
- 双层审核流程
- 审计日志
- 权限分离
### Governance
- Two-tier review workflow
- Audit logs
- Permission separation
### 存储与部署
- 支持 S3/MinIO/本地存储
- Docker/Kubernetes 部署
- 企业级可观测性
### Storage and Deployment
- S3/MinIO/Local storage support
- Docker/Kubernetes deployment
- Enterprise-grade observability
## 技术栈
## Tech Stack
### 后端
- **Java 21** - 运行时
- **Spring Boot 3.2.3** - 应用框架
- **PostgreSQL 16.x** - 主数据库 + 全文搜索
- **Redis 7.x** - 缓存与会话存储
### Backend
- **Java 21** - Runtime
- **Spring Boot 3.2.3** - Application framework
- **PostgreSQL 16.x** - Primary database + full-text search
- **Redis 7.x** - Cache and session storage
### 前端
- **React 19** - UI 框架
- **TypeScript** - 类型安全
- **Vite** - 构建工具
- **Tailwind CSS** - 样式框架
### Frontend
- **React 19** - UI framework
- **TypeScript** - Type safety
- **Vite** - Build tool
- **Tailwind CSS** - Styling framework
### 部署
- **Docker Compose** - 单机部署
- **Kubernetes** - 生产环境编排
### Deployment
- **Docker Compose** - Single-machine deployment
- **Kubernetes** - Production orchestration
## 核心概念
## Core Concepts
### 命名空间
技能隔离边界，支持 `@global`（全局）和 `@team-*`（团队）前缀。
### Namespace
Skill isolation boundary, supporting `@global` (global) and `@team-*` (team) prefixes.
### 坐标系统
技能标识格式为 `@{namespace_slug}/{skill_slug}`，支持语义化版本。
### Coordinate System
Skill identifier format: `@{namespace_slug}/{skill_slug}`, supports semantic versioning.
### 兼容性
提供 REST API 和 ClawHub 兼容层，支持现有工具集成。
### Compatibility
Provides REST API and ClawHub compatibility layer for existing tool integration.
## 下一步
## Next Steps
- [快速开始](./quick-start) - 一键启动体验
- [典型应用场景](./use-cases) - 了解如何在企业中应用
- [Quick Start](./quick-start) - One-click startup experience
- [Use Cases](./use-cases) - Explore enterprise application scenarios

70
document/docs/01-getting-started/quick-start.md
View file

@ -1,20 +1,20 @@
---
title: 快速开始
title: Quick Start
sidebar_position: 2
description: 一键启动 SkillHub 开发环境
description: One-click startup of SkillHub development environment
---
# 快速开始
# Quick Start
## 一键启动
## One-click Startup
使用以下命令一键启动完整的 SkillHub 环境：
Use the following command to start a complete SkillHub environment with one command:
```bash
curl -fsSL https://raw.githubusercontent.com/iflytek/skillhub/main/scripts/runtime.sh | sh -s -- up
```
或者克隆仓库后手动启动：
Or clone the repository and start manually:
```bash
git clone https://github.com/iflytek/skillhub.git
@ -22,64 +22,64 @@ cd skillhub
make dev-all
```
## 默认账号
## Default Account
两种启动方式都会默认创建一个 bootstrap 管理员账号：
Both startup methods create a bootstrap admin account by default:
- 用户名：`admin`
- 密码：`ChangeMe!2026`
- username: `admin`
- password: `ChangeMe!2026`
### `curl` 一键部署
### `curl` One-click Deployment
| 服务 | 地址 |
|------|------|
| Service | Address |
|---------|---------|
| Web UI | http://localhost |
| Backend API | http://localhost:8080 |
使用上述默认账号密码登录即可。**生产环境请务必修改密码。**
Log in with the default credentials above. **Change the password for production.**
### `make dev-all` 本地开发
### `make dev-all` Local Development
| 服务 | 地址 |
|------|------|
| Service | Address |
|---------|---------|
| Web UI | http://localhost:3000 |
| Backend API | http://localhost:8080 |
| MinIO Console | http://localhost:9001 |
除了上述 bootstrap 管理员，本地开发还预置两个模拟用户（无需密码）：
In addition to the bootstrap admin, local development includes two mock users (no password needed):
| 用户 | 角色 | 说明 |
|------|------|------|
| `local-user` | 普通用户 | 可发布技能、管理命名空间 |
| `local-admin` | 超级管理员 | 拥有所有权限，包括审核和用户管理 |
| User | Role | Description |
|------|------|-------------|
| `local-user` | Regular user | Can publish skills, manage namespaces |
| `local-admin` | Super admin | Has all permissions including review and user management |
使用 `X-Mock-User-Id` 请求头切换模拟用户。
如需关闭 bootstrap 管理员，启动前设置 `BOOTSTRAP_ADMIN_ENABLED=false`。
Use the `X-Mock-User-Id` request header to switch mock users.
To disable the bootstrap admin, set `BOOTSTRAP_ADMIN_ENABLED=false` before starting.
## 常用命令
## Common Commands
```bash
# 启动完整开发环境
# Start complete development environment
make dev-all
# 停止所有服务
# Stop all services
make dev-all-down
# 重置并重新启动
# Reset and restart
make dev-all-reset
# 仅启动后端
# Start backend only
make dev
# 仅启动前端
# Start frontend only
make dev-web
# 查看所有可用命令
# View all available commands
make help
```
## 下一步
## Next Steps
- [产品概述](./overview) - 深入了解产品特性
- [典型应用场景](./use-cases) - 探索企业应用场景
- [单机部署](../administration/deployment/single-machine) - 生产环境部署指南
- [Overview](./overview) - Deep dive into product features
- [Use Cases](./use-cases) - Explore enterprise application scenarios
- [Single Machine Deployment](../administration/deployment/single-machine) - Production deployment guide

100
document/docs/01-getting-started/use-cases.md
View file

@ -1,72 +1,72 @@
---
title: 典型应用场景
title: Use Cases
sidebar_position: 3
description: SkillHub 在企业中的典型应用场景
description: Typical enterprise application scenarios for SkillHub
---
# 典型应用场景
# Use Cases
## 企业内部技能共享
## Internal Skill Sharing
**场景描述**：企业内部多个团队开发 AI 技能，需要一个集中的平台进行共享和复用。
**Scenario**: Multiple teams within an enterprise develop AI skills and need a centralized platform for sharing and reuse.
**解决方案**：
- 各团队创建自己的命名空间
- 技能在团队内先审核发布
- 优秀技能可申请提升到全局空间
- 所有操作有完整审计记录
**Solution**:
- Each team creates their own namespace
- Skills are reviewed and published within the team first
- Excellent skills can be promoted to the global space
- Complete audit records for all operations
**价值**：
- 避免重复开发
- 促进最佳实践传播
- 保障质量可控
**Value**:
- Avoid duplicate development
- Promote best practice sharing
- Ensure quality control
## AI 技能治理与合规
## AI Skill Governance and Compliance
**场景描述**：金融、政务等行业对 AI 应用有严格的合规要求，需要完整的审核和审计机制。
**Scenario**: Industries such as finance and government have strict compliance requirements for AI applications, requiring complete review and audit mechanisms.
**解决方案**：
- 双层审核流程（团队审核 + 平台审核）
- 细粒度 RBAC 权限控制
- 完整的操作审计日志
- 技能版本可追溯、可撤回
**Solution**:
- Two-tier review workflow (team review + platform review)
- Fine-grained RBAC permission control
- Complete operation audit logs
- Skill version traceability and withdrawability
**价值**：
- 满足合规要求
- 风险可控
- 责任可追溯
**Value**:
- Meet compliance requirements
- Controllable risks
- Traceable responsibilities
## 多团队协作开发
## Multi-team Collaborative Development
**场景描述**：大型组织中多个团队协作开发，需要清晰的权限边界和协作机制。
**Scenario**: Large organizations with multiple teams collaborating need clear permission boundaries and collaboration mechanisms.
**解决方案**：
- 命名空间隔离，团队自治
- 命名空间成员角色管理
- 技能可见性控制（公开/命名空间内/私有）
- 团队技能可申请提升到全局
**Solution**:
- Namespace isolation, team autonomy
- Namespace member role management
- Skill visibility control (public/namespace-only/private)
- Team skills can apply for promotion to global
**价值**：
- 权责清晰
- 协作高效
- 安全可控
**Value**:
- Clear responsibilities
- Efficient collaboration
- Controllable security
## CLI 工具集成
## CLI Tool Integration
**场景描述**：已有使用 ClawHub CLI 的工作流，希望无缝迁移到 SkillHub。
**Scenario**: Existing workflows using ClawHub CLI want to seamlessly migrate to SkillHub.
**解决方案**：
- 提供 ClawHub CLI 协议兼容层
- 通过 `/.well-known/clawhub.json` 自动发现
- 现有 CLI 工具无需修改即可使用
- 同时提供 SkillHub 自有 CLI 增强功能
**Solution**:
- Provide ClawHub CLI protocol compatibility layer
- Auto-discovery via `/.well-known/clawhub.json`
- Existing CLI tools work without modification
- Also provide SkillHub-native CLI enhanced features
**价值**：
- 保护现有投资
- 迁移成本低
- 渐进式升级
**Value**:
- Protect existing investments
- Low migration cost
- Gradual upgrade
## 下一步
## Next Steps
- [单机部署](../administration/deployment/single-machine) - 开始部署
- [命名空间管理](../administration/governance/namespaces) - 了解组织治理
- [Single Machine Deployment](../administration/deployment/single-machine) - Start deployment
- [Namespace Management](../administration/governance/namespaces) - Learn about organization governance

4
document/docs/02-administration/_category_.json
View file

@ -1,8 +1,8 @@
{
"label": "管理员指南",
"label": "Administration Guide",
"position": 2,
"link": {
"type": "generated-index",
"description": "部署、配置和管理 SkillHub"
"description": "Deploy, configure, and manage SkillHub"
}
}

2
document/docs/02-administration/deployment/_category_.json
View file

@ -1,4 +1,4 @@
{
"label": "部署指南",
"label": "Deployment Guide",
"position": 1
}

86
document/docs/02-administration/deployment/configuration.md
View file

@ -1,69 +1,69 @@
---
title: 配置说明
title: Configuration Reference
sidebar_position: 3
description: SkillHub 配置项详细说明
description: Detailed SkillHub configuration reference
---
# 配置说明
# Configuration Reference
## 环境变量
## Environment Variables
SkillHub 通过环境变量进行配置，主要配置项如下：
SkillHub is configured through environment variables. The main configuration items are listed below:
### 基础配置
### Basic Configuration
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `SKILLHUB_PUBLIC_BASE_URL` | 公网访问地址 | - |
| `SKILLHUB_VERSION` | 镜像版本 | `edge` |
| Environment Variable | Description | Default Value |
|---------------------|-------------|---------------|
| `SKILLHUB_PUBLIC_BASE_URL` | Public access URL | - |
| `SKILLHUB_VERSION` | Image version | `edge` |
### 数据库配置
### Database Configuration
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `POSTGRES_HOST` | PostgreSQL 主机 | `postgres` |
| `POSTGRES_PORT` | PostgreSQL 端口 | `5432` |
| `POSTGRES_DB` | 数据库名 | `skillhub` |
| `POSTGRES_USER` | 数据库用户 | `skillhub` |
| `POSTGRES_PASSWORD` | 数据库密码 | - |
| Environment Variable | Description | Default Value |
|---------------------|-------------|---------------|
| `POSTGRES_HOST` | PostgreSQL host | `postgres` |
| `POSTGRES_PORT` | PostgreSQL port | `5432` |
| `POSTGRES_DB` | Database name | `skillhub` |
| `POSTGRES_USER` | Database user | `skillhub` |
| `POSTGRES_PASSWORD` | Database password | - |
### Redis 配置
### Redis Configuration
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `REDIS_HOST` | Redis 主机 | `redis` |
| `REDIS_PORT` | Redis 端口 | `6379` |
| `REDIS_PASSWORD` | Redis 密码 | - |
| Environment Variable | Description | Default Value |
|---------------------|-------------|---------------|
| `REDIS_HOST` | Redis host | `redis` |
| `REDIS_PORT` | Redis port | `6379` |
| `REDIS_PASSWORD` | Redis password | - |
### 存储配置
### Storage Configuration
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `SKILLHUB_STORAGE_PROVIDER` | 存储提供方 | `local` |
| `SKILLHUB_STORAGE_S3_ENDPOINT` | S3 端点 | - |
| `SKILLHUB_STORAGE_S3_BUCKET` | S3 桶名 | - |
| Environment Variable | Description | Default Value |
|---------------------|-------------|---------------|
| `SKILLHUB_STORAGE_PROVIDER` | Storage provider | `local` |
| `SKILLHUB_STORAGE_S3_ENDPOINT` | S3 endpoint | - |
| `SKILLHUB_STORAGE_S3_BUCKET` | S3 bucket name | - |
| `SKILLHUB_STORAGE_S3_ACCESS_KEY` | S3 Access Key | - |
| `SKILLHUB_STORAGE_S3_SECRET_KEY` | S3 Secret Key | - |
### OAuth 配置
### OAuth Configuration
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| Environment Variable | Description | Default Value |
|---------------------|-------------|---------------|
| `OAUTH2_GITHUB_CLIENT_ID` | GitHub OAuth Client ID | - |
| `OAUTH2_GITHUB_CLIENT_SECRET` | GitHub OAuth Client Secret | - |
### 首登管理员配置
### Bootstrap Admin Configuration
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `BOOTSTRAP_ADMIN_ENABLED` | 是否启用首登管理员 | `true` |
| `BOOTSTRAP_ADMIN_USERNAME` | 首登管理员用户名 | `admin` |
| `BOOTSTRAP_ADMIN_PASSWORD` | 首登管理员密码 | `ChangeMe!2026` |
| Environment Variable | Description | Default Value |
|---------------------|-------------|---------------|
| `BOOTSTRAP_ADMIN_ENABLED` | Enable bootstrap admin | `true` |
| `BOOTSTRAP_ADMIN_USERNAME` | Bootstrap admin username | `admin` |
| `BOOTSTRAP_ADMIN_PASSWORD` | Bootstrap admin password | `ChangeMe!2026` |
## 配置文件
## Configuration Files
Spring Boot 配置文件位于 `server/skillhub-app/src/main/resources/`。
Spring Boot configuration files are located at `server/skillhub-app/src/main/resources/`.
## 下一步
## Next Steps
- [认证配置](../security/authentication) - 配置身份认证
- [Authentication Configuration](../security/authentication) - Configure authentication

46
document/docs/02-administration/deployment/kubernetes.md
View file

@ -1,54 +1,54 @@
---
title: Kubernetes 部署
title: Kubernetes Deployment
sidebar_position: 2
description: 在 Kubernetes 集群中部署 SkillHub
description: Deploy SkillHub in a Kubernetes cluster
---
# Kubernetes 部署
# Kubernetes Deployment
本文介绍如何在 Kubernetes 集群中部署 SkillHub。
This guide describes how to deploy SkillHub in a Kubernetes cluster.
## 前置要求
## Prerequisites
- Kubernetes 1.24+
- kubectl 配置完成
- Helm 3.0+（可选）
- 可用的持久化存储类
- kubectl configured
- Helm 3.0+ (optional)
- Available persistent storage class
## 部署清单
## Deployment Manifests
项目提供了 Kubernetes 部署清单：
Kubernetes deployment manifests are provided in the project:
```bash
cd deploy/k8s
# 1. 创建命名空间
# 1. Create namespace
kubectl create namespace skillhub
# 2. 配置 Secret
# 2. Configure Secret
cp secret.yaml.example secret.yaml
# 编辑 secret.yaml 填入真实凭证
# Edit secret.yaml and fill in real credentials
# 3. 应用配置
# 3. Apply configuration
kubectl apply -f configmap.yaml
kubectl apply -f secret.yaml
# 4. 部署服务
# 4. Deploy services
kubectl apply -f backend-deployment.yaml
kubectl apply -f frontend-deployment.yaml
kubectl apply -f services.yaml
# 5. 配置 Ingress
# 5. Configure Ingress
kubectl apply -f ingress.yaml
```
## 高可用配置
## High Availability Configuration
- 后端和前端建议至少部署 2 个副本
- PostgreSQL 使用主从复制
- Redis 使用 Sentinel 或 Cluster 模式
- 存储使用高可用对象存储（如 MinIO 集群或云厂商 OSS）
- Deploy at least 2 replicas for backend and frontend
- Use PostgreSQL with primary-replica replication
- Use Redis with Sentinel or Cluster mode
- Use highly available object storage (like MinIO cluster or cloud provider OSS)
## 下一步
## Next Steps
- [配置说明](./configuration) - 详细配置项说明
- [Configuration](./configuration) - Detailed configuration reference

58
document/docs/02-administration/deployment/single-machine.md
View file

@ -1,65 +1,65 @@
---
title: 单机部署
title: Single Machine Deployment
sidebar_position: 1
description: 使用 Docker Compose 单机部署 SkillHub
description: Deploy SkillHub using Docker Compose on a single machine
---
# 单机部署
# Single Machine Deployment
本文介绍如何使用 Docker Compose 在单台服务器上部署 SkillHub。
This guide describes how to deploy SkillHub on a single server using Docker Compose.
## 前置要求
## Prerequisites
- Docker Engine 20.10+
- Docker Compose Plugin 2.0+
- 至少 4GB 可用内存
- 至少 20GB 可用磁盘空间
- At least 4GB available RAM
- At least 20GB available disk space
## 快速部署
## Quick Deployment
```bash
# 1. 克隆仓库
# 1. Clone the repository
git clone https://github.com/iflytek/skillhub.git
cd skillhub
# 2. 复制环境变量模板
# 2. Copy environment variable template
cp .env.release.example .env.release
# 3. 编辑配置
# 修改 .env.release 中的配置项，特别是密码和公网地址
# 3. Edit configuration
# Modify configuration items in .env.release, especially passwords and public URLs
# 4. 验证配置
# 4. Validate configuration
make validate-release-config
# 5. 启动服务
# 5. Start services
docker compose --env-file .env.release -f compose.release.yml up -d
```
## 配置说明
## Configuration
详见 [配置说明](./configuration) 文档。
See [Configuration](./configuration) documentation for details.
## 验证部署
## Verify Deployment
```bash
# 检查容器状态
# Check container status
docker compose --env-file .env.release -f compose.release.yml ps
# 检查后端健康状态
# Check backend health
curl -i http://127.0.0.1:8080/actuator/health
# 访问 Web UI
# 浏览器打开 http://localhost（或配置的公网地址）
# Access Web UI
# Open http://localhost in browser (or configured public URL)
```
## 首登配置
## First Login Configuration
1. 使用 `BOOTSTRAP_ADMIN_USERNAME` 和 `BOOTSTRAP_ADMIN_PASSWORD` 登录（默认 `admin` / `ChangeMe!2026`）
2. 立即修改管理员密码
3. 配置企业 SSO（可选）
4. 创建团队命名空间
1. Login with `BOOTSTRAP_ADMIN_USERNAME` and `BOOTSTRAP_ADMIN_PASSWORD` (default `admin` / `ChangeMe!2026`)
2. Change admin password immediately
3. Configure enterprise SSO (optional)
4. Create team namespaces
## 下一步
## Next Steps
- [配置说明](./configuration) - 详细配置项说明
- [Kubernetes 部署](./kubernetes) - 高可用部署
- [Configuration](./configuration) - Detailed configuration reference
- [Kubernetes Deployment](./kubernetes) - High availability deployment

2
document/docs/02-administration/governance/_category_.json
View file

@ -1,4 +1,4 @@
{
"label": "治理与运营",
"label": "Governance & Operations",
"position": 3
}

72
document/docs/02-administration/governance/namespaces.md
View file

@ -1,56 +1,56 @@
---
title: 命名空间管理
title: Namespace Management
sidebar_position: 1
description: 命名空间创建与管理
description: Namespace creation and management
---
# 命名空间管理
# Namespace Management
命名空间是 SkillHub 中技能的隔离边界和协作单元。
Namespaces are the isolation boundary and collaboration unit for skills in SkillHub.
## 命名空间类型
## Namespace Types
| 类型 | 前缀 | 说明 |
|------|------|------|
| 全局 | `@global` | 平台级公共空间，由平台管理员管理 |
| 团队 | `@team-*` | 团队/部门空间，由团队管理员管理 |
| Type | Prefix | Description |
|------|--------|-------------|
| Global | `@global` | Platform-level public space, managed by platform admins |
| Team | `@team-*` | Team/department space, managed by team admins |
## 创建命名空间
## Create Namespace
1. 登录后进入"我的命名空间"
2. 点击"创建命名空间"
3. 填写信息：
- 标识（slug）：URL 友好名称
- 显示名：展示名称
- 描述：空间用途说明
4. 提交创建
1. After login, go to "My Namespaces"
2. Click "Create Namespace"
3. Fill in information:
- Slug: URL-friendly name
- Display name: Display name
- Description: Space purpose description
4. Submit creation
## 命名空间成员管理
## Namespace Member Management
### 添加成员
### Add Member
1. 进入命名空间设置
2. 进入"成员管理"
3. 输入用户名搜索
4. 选择角色（OWNER/ADMIN/MEMBER）
5. 确认添加
1. Go to namespace settings
2. Go to "Member Management"
3. Enter username to search
4. Select role (OWNER/ADMIN/MEMBER)
5. Confirm addition
### 角色变更
### Role Change
命名空间 OWNER 或 ADMIN 可变更成员角色。
Namespace OWNER or ADMIN can change member roles.
### 移除成员
### Remove Member
命名空间 OWNER 或 ADMIN 可移除成员。
Namespace OWNER or ADMIN can remove members.
## 命名空间状态
## Namespace Status
| 状态 | 说明 |
|------|------|
| `ACTIVE` | 正常使用 |
| `FROZEN` | 冻结，只读不可发布 |
| `ARCHIVED` | 归档，对外不可见 |
| Status | Description |
|--------|-------------|
| `ACTIVE` | Normal use |
| `FROZEN` | Frozen, read-only, cannot publish |
| `ARCHIVED` | Archived, not visible externally |
## 下一步
## Next Steps
- [审核流程](./review-workflow) - 了解技能审核
- [Review Workflow](./review-workflow) - Understand skill review

56
document/docs/02-administration/governance/review-workflow.md
View file

@ -1,44 +1,44 @@
---
title: 审核流程
title: Review Workflow
sidebar_position: 2
description: 技能发布审核流程配置
description: Skill publishing review workflow configuration
---
# 审核流程
# Review Workflow
SkillHub 采用双层审核机制，保障技能质量。
SkillHub uses a two-tier review mechanism to ensure skill quality.
## 审核流程
## Review Workflow
### 团队空间技能
### Team Namespace Skills
1. 团队成员提交发布
2. 创建审核任务（PENDING）
3. 团队 ADMIN 或 OWNER 审核
- 通过 → 技能发布（PUBLISHED）
- 拒绝 → 返回修改（REJECTED）
1. Team member submits publishing
2. Create review task (PENDING)
3. Team ADMIN or OWNER reviews
- Approve → Skill published (PUBLISHED)
- Reject → Return for modification (REJECTED)
### 全局空间技能
### Global Namespace Skills
1. 提交发布
2. 平台 SKILL_ADMIN 或 SUPER_ADMIN 审核
3. 审核通过后发布
1. Submit publishing
2. Platform SKILL_ADMIN or SUPER_ADMIN reviews
3. Published after review approval
## 团队技能提升到全局
## Promote Team Skill to Global
1. 团队技能已发布
2. 团队 ADMIN 或 OWNER 申请"提升到全局"
3. 平台管理员审核
4. 审核通过后在全局空间创建新技能
1. Team skill is published
2. Team ADMIN or OWNER applies "Promote to Global"
3. Platform admin reviews
4. Creates new skill in global namespace after approval
## 审核权限
## Review Permissions
| 审核类型 | 所需角色 |
|---------|---------|
| 团队空间技能审核 | 命名空间 ADMIN/OWNER |
| 全局空间技能审核 | SKILL_ADMIN/SUPER_ADMIN |
| 提升申请审核 | SKILL_ADMIN/SUPER_ADMIN |
| Review Type | Required Role |
|------------|---------------|
| Team namespace skill review | Namespace ADMIN/OWNER |
| Global namespace skill review | SKILL_ADMIN/SUPER_ADMIN |
| Promotion request review | SKILL_ADMIN/SUPER_ADMIN |
## 下一步
## Next Steps
- [用户管理](./user-management) - 管理平台用户
- [User Management](./user-management) - Manage platform users

62
document/docs/02-administration/governance/user-management.md
View file

@ -1,36 +1,36 @@
---
title: 用户管理
title: User Management
sidebar_position: 3
description: 平台用户管理
description: Platform user management
---
# 用户管理
# User Management
## 用户状态
## User Status
| 状态 | 实际逻辑 |
|------|----------|
| `ACTIVE` | 可正常登录和使用系统。OAuth 首次自动准入、local 注册成功后都会进入该状态。 |
| `PENDING` | 账号已建但不可登录。OAuth 在“需要审批”策略下会创建 `PENDING` 用户并跳转到待审批页；local 登录遇到该状态会直接拒绝。 |
| `DISABLED` | 不可登录。OAuth 和 local 登录都会拒绝；`/api/v1/auth/me` 发现当前会话对应用户已被禁用时，会直接清掉 session。 |
| `MERGED` | 账号已并入其他账号，不可继续登录；主要由账号合并流程写入，不是普通用户管理流程的目标状态。 |
| Status | Effective behavior |
|--------|--------------------|
| `ACTIVE` | Can log in and use the system normally. OAuth auto-admission and local registration both create users in this state. |
| `PENDING` | Account exists but cannot log in. Under approval-required OAuth flows, the system creates a `PENDING` user and redirects to the pending-approval page. Local login also rejects this status. |
| `DISABLED` | Cannot log in. Both OAuth and local auth reject it. `/api/v1/auth/me` will invalidate the current session if the backing user has been disabled. |
| `MERGED` | Account has been merged into another account and can no longer log in. This is mainly written by the account-merge flow, not by normal user administration. |
## 用户准入
## User Admission
可配置新用户是否需要审批：
- 自动准入：新用户登录后自动激活
- 审批准入：新用户需 USER_ADMIN 审批后激活
Configure whether new users require approval:
- Auto-admission: New users automatically activated after login
- Approval admission: New users require USER_ADMIN approval to activate
## 角色分配
## Role Assignment
`USER_ADMIN` 或 `SUPER_ADMIN` 可调用用户管理接口修改平台角色，但当前实现有几个关键点：
`USER_ADMIN` or `SUPER_ADMIN` can call the user-management API to change platform roles, but the implementation has a few important constraints:
- 接口一次只能设置一个目标平台角色。
- 设置时会删除该用户已有的显式平台角色，再写入新的那个角色。
- 如果设置为 `USER`，不会写入 `user_role_binding`，而是依赖运行时默认角色补位。
- `USER_ADMIN` 不能分配 `SUPER_ADMIN`，只有 `SUPER_ADMIN` 能分配。
- The API sets exactly one target platform role at a time.
- It deletes the user's existing explicit platform-role bindings before writing the new one.
- If the target role is `USER`, no `user_role_binding` row is written; runtime defaulting adds it later.
- `USER_ADMIN` cannot assign `SUPER_ADMIN`; only `SUPER_ADMIN` can do that.
当前管理接口可设置的目标角色实际上是：
The currently supported target roles in practice are:
- `USER`
- `SKILL_ADMIN`
@ -38,24 +38,24 @@ description: 平台用户管理
- `AUDITOR`
- `SUPER_ADMIN`
## 用户封禁/解封
## User Disable/Enable
`USER_ADMIN` 或 `SUPER_ADMIN` 可封禁/解封用户。
`USER_ADMIN` or `SUPER_ADMIN` can disable or enable users.
当前公开管理接口只支持把状态改成：
The current public management API only supports changing status to:
- `ACTIVE`
- `DISABLED`
其中：
In practice:
- “审批通过”本质上也是把用户状态改成 `ACTIVE`。
- 不能通过该接口直接改成 `PENDING` 或 `MERGED`。
- "Approve user" is implemented as changing the status to `ACTIVE`.
- The API does not directly set users to `PENDING` or `MERGED`.
## 账号合并
## Account Merge
支持将多个账号合并为一个，保留操作历史。
Supports merging multiple accounts into one, preserving operation history.
## 下一步
## Next Steps
- [创建技能包](../../user-guide/publishing/create-skill) - 开始发布技能
- [Create Skill Package](../../user-guide/publishing/create-skill) - Start publishing skills

2
document/docs/02-administration/security/_category_.json
View file

@ -1,4 +1,4 @@
{
"label": "安全与合规",
"label": "Security & Compliance",
"position": 2
}

48
document/docs/02-administration/security/audit-logs.md
View file

@ -1,38 +1,38 @@
---
title: 审计日志
title: Audit Logs
sidebar_position: 3
description: 操作审计日志查询与管理
description: Operation audit log query and management
---
# 审计日志
# Audit Logs
SkillHub 记录所有关键操作的审计日志，满足企业合规要求。
SkillHub records audit logs for all critical operations to meet enterprise compliance requirements.
## 审计范围
## Audit Scope
记录的操作包括：
- 技能发布、下载、删除
- 审核通过、拒绝
- 用户登录、登出
- 权限变更
- 命名空间管理
- 配置变更
Recorded operations include:
- Skill publishing, downloading, deletion
- Review approval, rejection
- User login, logout
- Permission changes
- Namespace management
- Configuration changes
## 审计日志查询
## Audit Log Query
通过管理后台审计日志页面或 Admin API 查询。
Query through admin dashboard audit log page or Admin API.
## 日志字段
## Log Fields
- 操作时间
- 操作用户
- 操作类型
- 目标资源
- 客户端 IP
- Operation time
- Operating user
- Operation type
- Target resource
- Client IP
- User-Agent
- 请求 ID
- 详细信息
- Request ID
- Detailed information
## 下一步
## Next Steps
- [命名空间管理](../governance/namespaces) - 管理组织
- [Namespace Management](../governance/namespaces) - Manage organization

30
document/docs/02-administration/security/authentication.md
View file

@ -1,36 +1,36 @@
---
title: 认证配置
title: Authentication Configuration
sidebar_position: 1
description: 配置用户认证方式
description: Configure user authentication methods
---
# 认证配置
# Authentication Configuration
SkillHub 支持多种认证方式，满足不同企业的安全需求。
SkillHub supports multiple authentication methods to meet different enterprise security requirements.
## OAuth2 登录
## OAuth2 Login
### GitHub OAuth
1. 在 GitHub 创建 OAuth App
2. 配置环境变量：
1. Create an OAuth App on GitHub
2. Configure environment variables:
```bash
OAUTH2_GITHUB_CLIENT_ID=your-client-id
OAUTH2_GITHUB_CLIENT_SECRET=your-client-secret
```
### 扩展 OAuth Provider
### Extend OAuth Provider
架构支持扩展其他 OAuth Provider，如 GitLab、Gitee 等。
The architecture supports extending to other OAuth providers like GitLab, Gitee, etc.
## 本地账号登录
## Local Account Login
开发环境支持本地账号登录，生产环境默认关闭。
Local account login is supported in development environment, disabled by default in production.
## 企业 SSO 集成
## Enterprise SSO Integration
支持通过扩展点集成企业 SSO（SAML/OIDC）。
Supports integrating enterprise SSO (SAML/OIDC) through extension points.
## 下一步
## Next Steps
- [权限管理](./authorization) - 配置权限控制
- [Authorization](./authorization) - Configure access control

79
document/docs/02-administration/security/authorization.md
View file

@ -1,63 +1,64 @@
---
title: 权限管理
title: Authorization Management
sidebar_position: 2
description: RBAC 权限系统配置
description: RBAC permission system configuration
---
# 权限管理
# Authorization Management
SkillHub 采用基于角色的访问控制（RBAC）系统。
SkillHub uses a Role-Based Access Control (RBAC) system.
当前代码里实际存在两套并行角色体系：
The current codebase actually uses two parallel role systems:
- 平台角色：控制后台治理、用户管理、审计等平台级能力。
- 命名空间角色：控制某个团队空间内的成员、发布、审核、归档等操作。
- Platform roles: control platform-wide governance, user administration, and audit capabilities.
- Namespace roles: control actions inside a specific team namespace.
二者会同时参与鉴权，但不是一套角色的上下级映射。
They participate in authorization together, but they are not a single hierarchy.
## 平台角色
## Platform Roles
### 代码里实际初始化的显式平台角色
### Explicit platform roles seeded by code
数据库迁移只初始化了 4 个显式平台角色：
The database migration seeds only 4 explicit platform roles:
| 角色 | 代码 | 实际能力 |
|------|------|----------|
| 超级管理员 | `SUPER_ADMIN` | 拥有全部权限；`RbacService#getUserPermissions` 会直接返回全部权限码；可访问所有 `SUPER_ADMIN`/`SKILL_ADMIN`/`USER_ADMIN`/`AUDITOR` 能访问的接口；可分配 `SUPER_ADMIN`；发布技能时可绕过命名空间成员校验并直接自动发布；可以审批自己提交的 promotion；普通审核单若是自己提交的，也只有 `SUPER_ADMIN` 能特判审批。 |
| 技能管理员 | `SKILL_ADMIN` | 可访问技能治理后台接口；可隐藏/取消隐藏技能、撤回版本（yank）、处理技能举报；可查看和处理全局空间审核、promotion 审核、治理工作台收件箱中的 review/promotion/report；不能分配平台角色、不能看审计日志、不能管理用户。 |
| 用户管理员 | `USER_ADMIN` | 可访问用户管理接口；可列表用户、审批用户、启用/禁用用户、修改平台角色；不能分配 `SUPER_ADMIN`；不能处理技能治理、不能看审计日志。 |
| 审计员 | `AUDITOR` | 只读查看审计日志；可访问 `/api/v1/admin/audit-logs` 和 `/actuator/prometheus`；治理工作台中只能看 activity，不能处理 review/promotion/report，也不能管理用户或技能。 |
| Role | Code | Effective behavior |
|------|------|--------------------|
| Super Admin | `SUPER_ADMIN` | Has all permissions. `RbacService#getUserPermissions` returns all permission codes for this role. Can access all endpoints available to `SUPER_ADMIN` / `SKILL_ADMIN` / `USER_ADMIN` / `AUDITOR`. Can assign `SUPER_ADMIN`. Can bypass namespace membership checks during publish and auto-publish directly. Still cannot approve their own promotion request, and for normal review tasks the self-submission exception is only bypassed by `SUPER_ADMIN`. |
| Skill Admin | `SKILL_ADMIN` | Can access skill governance admin endpoints. Can hide/unhide skills, yank versions, and resolve/dismiss skill reports. Can review global namespace review tasks, promotion requests, and governance inbox items for review/promotion/report. Cannot manage users or read audit logs. |
| User Admin | `USER_ADMIN` | Can access user management endpoints. Can list users, approve users, enable/disable users, and change platform roles. Cannot assign `SUPER_ADMIN`. Cannot perform skill governance or read audit logs. |
| Auditor | `AUDITOR` | Read-only audit access. Can access `/api/v1/admin/audit-logs` and `/actuator/prometheus`. In the governance workbench this role can read activity, but cannot process review/promotion/report items and cannot manage users or skills. |
### 运行时默认平台角色
### Runtime default platform role
| 角色 | 代码 | 实际逻辑 |
|------|------|----------|
| 默认用户 | `USER` | 不是 `role` 表里的显式初始化记录。只要用户没有任何显式平台角色绑定，登录态和 `RbacService#getUserRoleCodes` 都会自动补上 `USER`。它主要表示“普通已登录用户”，没有额外后台治理权限。 |
| Role | Code | Effective behavior |
|------|------|--------------------|
| Default User | `USER` | Not an explicitly seeded row in the `role` table. If a user has no explicit platform-role binding, login/session resolution and `RbacService#getUserRoleCodes` automatically add `USER`. It represents a normal signed-in user with no extra governance privileges. |
### 需要特别注意的实现细节
### Important implementation details
- 当前管理接口的“修改用户角色”是单值覆盖，不是追加：`PUT /api/v1/admin/users/{userId}/role` 先清空该用户现有平台角色，再写入一个目标角色；当目标角色是 `USER` 时，不会写数据库记录，而是依赖运行时默认补位。
- 代码底层仍然支持“一个用户拥有多个显式平台角色”的读取与鉴权，因为 session、token 和 `RbacService` 都是按角色集合处理；只是当前管理接口不会这样分配。
- `SUPER_ADMIN` 是唯一一个在权限查询时被视为“拥有全部 permission code”的角色，其它角色依赖 `role_permission` 关联表。
- The current admin API changes platform role by replacement, not by append: `PUT /api/v1/admin/users/{userId}/role` deletes existing explicit platform-role bindings first, then writes one target role.
- If the target role is `USER`, no explicit binding is stored; the role is supplied later by runtime defaulting.
- The lower-level auth/session/RBAC code still supports multiple explicit platform roles on one user because it works with role sets. The current admin API simply does not assign roles that way.
- `SUPER_ADMIN` is the only role treated as "all permissions" during permission lookup. Other roles depend on `role_permission`.
## 命名空间角色
## Namespace Roles
| 角色 | 实际能力 |
|------|----------|
| `OWNER` | 创建团队空间时自动成为 `OWNER`。可更新命名空间信息、管理成员、冻结/解冻空间、归档/恢复空间、转移所有权；可提交 review；可审核团队空间 review；可访问私有技能；可管理受限技能生命周期（归档、反归档、删除草稿/驳回版本等）。 |
| `ADMIN` | 可更新命名空间信息、管理成员、冻结/解冻空间；不能归档/恢复空间，也不能直接把别人设为 `OWNER`；可提交 review；可审核团队空间 review；可访问私有技能；可管理受限技能生命周期。 |
| `MEMBER` | 默认加入全局空间时获得 `MEMBER`。可在所在命名空间发布技能、提交 review；但不能审核 review、不能管理成员、不能冻结/归档空间；私有技能也不能仅因 `MEMBER` 身份访问，私有技能要求 owner 或 `ADMIN/OWNER`。 |
| Role | Effective behavior |
|------|--------------------|
| `OWNER` | Automatically assigned when creating a team namespace. Can update namespace settings, manage members, freeze/unfreeze the namespace, archive/restore it, and transfer ownership. Can submit reviews, review team-namespace review tasks, access private skills, and manage restricted skill lifecycle. |
| `ADMIN` | Can update namespace settings, manage members, and freeze/unfreeze the namespace. Cannot archive/restore the namespace and cannot directly set someone to `OWNER`. Can submit reviews, review team-namespace review tasks, access private skills, and manage restricted skill lifecycle. |
| `MEMBER` | Common member role, including auto-membership in the global namespace. Can publish skills in namespaces they belong to and can submit reviews. Cannot review review tasks, manage members, or freeze/archive namespaces. `MEMBER` alone is not enough to access private skills. |
### 命名空间角色的边界
### Namespace role boundaries
- `GLOBAL` 空间是只读系统空间，不能通过命名空间治理接口修改；全局空间 review/promotion/report 处理依赖平台角色 `SKILL_ADMIN`/`SUPER_ADMIN`，不是依赖全局空间成员身份。
- `NAMESPACE_ONLY` 可见性的技能，任何该命名空间成员都能访问。
- `PRIVATE` 可见性的技能，只有技能 owner 或命名空间 `ADMIN/OWNER` 能访问，`MEMBER` 不行。
- The `GLOBAL` namespace is effectively immutable in namespace-governance flows. Review/promotion/report handling there depends on platform roles `SKILL_ADMIN` / `SUPER_ADMIN`, not on global namespace membership alone.
- For `NAMESPACE_ONLY` visibility, any namespace member can access the skill.
- For `PRIVATE` visibility, access is limited to the skill owner or namespace `ADMIN` / `OWNER`; `MEMBER` is not enough.
## 权限配置
## Permission Configuration
通过后台分配平台角色，通过命名空间成员关系分配命名空间角色。
Assign platform roles through admin user management, and namespace roles through namespace membership.
## 下一步
## Next Steps
- [审计日志](./audit-logs) - 查看操作审计
- [Audit Logs](./audit-logs) - View operation audits

104
document/docs/02-administration/security/scanner.md Normal file
View file

@ -0,0 +1,104 @@
---
title: Security Scanning
sidebar_position: 4
description: Use Skill Scanner to add automated security checks to the skill publish pipeline
---
# Security Scanning
SkillHub can integrate `skill-scanner` into the publish pipeline to automatically inspect uploaded skill packages and persist the results as security audit records.
## Scan Flow
When scanning is enabled, the publish flow becomes:
1. A user publishes a skill package
2. The backend creates a version and moves it to `SCANNING`
3. The backend enqueues a scan task
4. `skill-scanner` consumes the task and runs analysis
5. The result is stored in `security_audit`
6. The version moves to `PENDING_REVIEW`, or to `SCAN_FAILED` after final retry exhaustion
7. The existing human review workflow continues afterward
## Typical Use Cases
- Add automated risk checks before manual review
- Retain scan results and audit evidence for governance
- Detect suspicious code, leaked secrets, or risky behavior patterns in skill packages
## Runtime Modes
Two modes are supported:
- `local`: the backend passes a filesystem path to the scanner, suitable for shared filesystem setups
- `upload`: the backend uploads the package archive directly, suitable for Docker, Kubernetes, and split deployments
Recommended usage:
- Local development: prefer `local`
- Production, Kubernetes, or split services: prefer `upload`
## Key Configuration
Core backend configuration:
```yaml
skillhub:
security:
scanner:
enabled: false
base-url: http://localhost:8000
health-path: /health
scan-path: /scan-upload
mode: upload
connect-timeout-ms: 5000
read-timeout-ms: 300000
retry-max-attempts: 3
```
Common environment variables:
- `SKILLHUB_SECURITY_SCANNER_ENABLED`
- `SKILLHUB_SECURITY_SCANNER_URL`
- `SKILLHUB_SECURITY_SCANNER_MODE`
- `SKILLHUB_SCAN_STREAM_KEY`
- `SKILLHUB_SCAN_STREAM_GROUP`
## How To Verify
After enabling scanning, validate it with these steps:
1. Publish a test skill package
2. Confirm the version first moves to `SCANNING`
3. Confirm a `security_audit` record is created
4. Confirm the version eventually moves to `PENDING_REVIEW` or `SCAN_FAILED`
5. Call the security audit API to inspect the result
```text
GET /api/v1/skills/{skillId}/versions/{versionId}/security-audit
```
## Result Fields
Security audit results usually include:
- `scanId`
- `scannerType`
- `verdict`
- `isSafe`
- `maxSeverity`
- `findingsCount`
- `findings`
- `scanDurationSeconds`
- `scannedAt`
## Deployment Recommendations
- Keep scanning disabled at first in local environments, then enable it after the main flow is stable
- Use `upload` mode in Kubernetes to avoid relying on a shared writable filesystem
- In production, keep scan results alongside human review records as governance evidence
## Next Steps
- [Review Workflow](../governance/review-workflow) - Understand the approval flow after scanning
- [Deployment Configuration](../deployment/configuration) - Review deployment-related settings

4
document/docs/03-user-guide/_category_.json
View file

@ -1,8 +1,8 @@
{
"label": "用户指南",
"label": "User Guide",
"position": 3,
"link": {
"type": "generated-index",
"description": "学习如何发布、发现和使用技能"
"description": "Learn how to publish, discover, and use skills"
}
}

2
document/docs/03-user-guide/collaboration/_category_.json
View file

@ -1,4 +1,4 @@
{
"label": "协作",
"label": "Collaboration",
"position": 3
}

48
document/docs/03-user-guide/collaboration/namespaces.md
View file

@ -1,41 +1,41 @@
---
title: 团队命名空间
title: Team Namespaces
sidebar_position: 1
description: 在团队命名空间中协作
description: Collaborate in team namespaces
---
# 团队命名空间
# Team Namespaces
## 加入命名空间
## Join Namespace
需要命名空间管理员邀请才能加入团队命名空间。
Requires namespace admin invitation to join a team namespace.
## 命名空间角色
## Namespace Roles
### MEMBER
- 可查看命名空间内所有技能
- 可发布技能（需审核）
- 可收藏和评分
- Can view all skills in namespace
- Can publish skills (requires review)
- Can favorite and rate
### ADMIN
- 所有 MEMBER 权限
- 可审核技能发布
- 可管理成员
- 可编辑命名空间信息
- All MEMBER permissions
- Can review skill publishing
- Can manage members
- Can edit namespace information
### OWNER
- 所有 ADMIN 权限
- 可转让所有权
- 可归档命名空间
- All ADMIN permissions
- Can transfer ownership
- Can archive namespace
## 技能可见性
## Skill Visibility
| 可见性 | 说明 |
|--------|------|
| `PUBLIC` | 所有人可见，匿名可下载 |
| `NAMESPACE_ONLY` | 仅命名空间成员可见 |
| `PRIVATE` | 仅 owner 和命名空间 ADMIN 可见 |
| Visibility | Description |
|------------|-------------|
| `PUBLIC` | Visible to everyone, anonymous downloadable |
| `NAMESPACE_ONLY` | Only visible to namespace members |
| `PRIVATE` | Only visible to owner and namespace ADMIN |
## 下一步
## Next Steps
- [提升到全局](./promotion) - 将团队技能推广到全局
- [Promote to Global](./promotion) - Promote team skills to global

54
document/docs/03-user-guide/collaboration/promotion.md
View file

@ -1,42 +1,42 @@
---
title: 提升到全局
title: Promote to Global
sidebar_position: 2
description: 申请将团队技能提升到全局空间
description: Apply to promote team skills to global namespace
---
# 提升到全局
# Promote to Global
优秀的团队技能可以申请提升到全局空间，供全企业使用。
Excellent team skills can be applied for promotion to the global namespace for enterprise-wide use.
## 提升前提
## Promotion Prerequisites
- 技能在团队空间已发布
- 申请人是技能 owner 或命名空间 ADMIN
- 技能没有待审核的提升申请
- Skill is published in team namespace
- Applicant is skill owner or namespace ADMIN
- Skill has no pending promotion requests
## 申请提升
## Apply for Promotion
1. 进入团队技能详情页
2. 点击"提升到全局"
3. 填写申请说明
4. 提交申请
1. Go to team skill detail page
2. Click "Promote to Global"
3. Fill in application description
4. Submit application
## 审核流程
## Review Workflow
1. 平台管理员收到提升申请
2. 审核技能质量和适用性
3. 审核通过后：
- 在全局空间创建新技能
- 保留原团队技能
- 记录来源追溯关系
1. Platform admin receives promotion application
2. Reviews skill quality and suitability
3. After approval:
- Creates new skill in global namespace
- Preserves original team skill
- Records source traceability relationship
## 提升后
## After Promotion
- 全局空间的新技能独立管理
- 原团队技能继续存在
- 两者版本不自动同步
- 如需同步需手动操作
- New skill in global namespace is independently managed
- Original team skill continues to exist
- Versions are not automatically synced
- Manual operation required if sync needed
## 下一步
## Next Steps
- [API 概述](../../developer/api/overview) - API 集成
- [API Overview](../../developer/api/overview) - API integration

2
document/docs/03-user-guide/discovery/_category_.json
View file

@ -1,4 +1,4 @@
{
"label": "发现与使用",
"label": "Discovery & Usage",
"position": 2
}

40
document/docs/03-user-guide/discovery/install.md
View file

@ -1,53 +1,53 @@
---
title: 安装使用
title: Install & Use
sidebar_position: 2
description: 安装和使用技能
description: Install and use skills
---
# 安装使用
# Install & Use
## 通过 CLI 安装
## Install via CLI
### 安装最新版本
### Install Latest Version
```bash
clawhub install @team/my-skill
```
### 安装指定版本
### Install Specific Version
```bash
clawhub install @team/my-skill@1.2.0
```
### 按标签安装
### Install by Tag
```bash
clawhub install @team/my-skill@beta
```
### 使用 ClawHub CLI 安装
### Install with ClawHub CLI
```bash
clawhub install my-skill
clawhub install team-name--my-skill
```
## 安装目录
## Installation Directory
按以下优先级安装：
Install by the following priority:
| 优先级 | 路径 | 说明 |
|--------|------|------|
| 1 | `./.agent/skills/` | 项目级，universal 模式 |
| 2 | `~/.agent/skills/` | 全局级，universal 模式 |
| 3 | `./.claude/skills/` | 项目级，Claude 默认 |
| 4 | `~/.claude/skills/` | 全局级，Claude 默认 |
| Priority | Path | Description |
|----------|------|-------------|
| 1 | `./.agent/skills/` | Project level, universal mode |
| 2 | `~/.agent/skills/` | Global level, universal mode |
| 3 | `./.claude/skills/` | Project level, Claude default |
| 4 | `~/.claude/skills/` | Global level, Claude default |
## 在 Claude Code 中使用
## Use in Claude Code
安装后，技能会被 Claude Code 自动发现和加载。
After installation, skills are automatically discovered and loaded by Claude Code.
## 下一步
## Next Steps
- [评分与收藏](./ratings) - 反馈和收藏技能
- [Ratings & Stars](./ratings) - Feedback and favorite skills

34
document/docs/03-user-guide/discovery/ratings.md
View file

@ -1,30 +1,30 @@
---
title: 评分与收藏
title: Ratings & Stars
sidebar_position: 3
description: 技能评分和收藏功能
description: Skill rating and favorite features
---
# 评分与收藏
# Ratings & Stars
## 收藏技能
## Favorite Skills
点击技能详情页的"收藏"按钮可收藏技能。
Click the "Favorite" button on the skill detail page to favorite a skill.
查看已收藏的技能：
- Web：进入"我的收藏"
- CLI：`clawhub stars`
View your favorite skills:
- Web: Go to "My Favorites"
- CLI: `clawhub stars`
## 技能评分
## Skill Rating
可对技能进行 1-5 分评分：
You can rate skills from 1-5 stars:
1. 进入技能详情页
2. 点击评分区域
3. 选择评分（1-5 星）
4. 提交评分
1. Go to skill detail page
2. Click rating area
3. Select rating (1-5 stars)
4. Submit rating
可随时修改自己的评分。
You can modify your rating at any time.
## 下一步
## Next Steps
- [团队命名空间](../collaboration/namespaces) - 团队协作
- [Team Namespaces](../collaboration/namespaces) - Team collaboration

48
document/docs/03-user-guide/discovery/search.md
View file

@ -1,36 +1,36 @@
---
title: 搜索技能
title: Search Skills
sidebar_position: 1
description: 搜索和筛选技能
description: Search and filter skills
---
# 搜索技能
# Search Skills
## 全文搜索
## Full-text Search
在搜索框输入关键词，SkillHub 会在以下字段中搜索：
- 技能名称
- 技能描述
- 技能 slug
- frontmatter 中除 `name`、`description`、`version` 外的其他字段
- `keywords` / `tags` 等关键词字段
Enter keywords in the search box, SkillHub searches in the following fields:
- Skill name
- Skill description
- Skill slug
- Frontmatter fields other than `name`, `description`, and `version`
- Keyword-style fields such as `keywords` and `tags`
## 筛选条件
## Filter Conditions
可通过以下条件筛选搜索结果：
- 命名空间
- 可见性
- 下载量排序
- 评分排序
- 更新时间排序
You can filter search results by the following conditions:
- Namespace
- Visibility
- Download count sorting
- Rating sorting
- Update time sorting
## 高级搜索
## Advanced Search
使用搜索语法：
- `namespace:@team-ai` - 指定命名空间
- `category:code-review` - 指定分类
- `downloads:>100` - 下载量大于 100
Use search syntax:
- `namespace:@team-ai` - Specify namespace
- `category:code-review` - Specify category
- `downloads:>100` - Downloads greater than 100
## 下一步
## Next Steps
- [安装使用](./install) - 安装和使用技能
- [Install & Use](./install) - Install and use skills

2
document/docs/03-user-guide/publishing/_category_.json
View file

@ -1,4 +1,4 @@
{
"label": "发布技能",
"label": "Publishing Skills",
"position": 1
}

58
document/docs/03-user-guide/publishing/create-skill.md
View file

@ -1,56 +1,56 @@
---
title: 创建技能包
title: Create Skill Package
sidebar_position: 1
description: 学习如何创建符合规范的技能包
description: Learn how to create a compliant skill package
---
# 创建技能包
# Create Skill Package
## 技能包结构
## Skill Package Structure
一个标准的 SkillHub 技能包结构如下：
A standard SkillHub skill package structure looks like this:
```
my-skill/
├── SKILL.md # 主入口文件（必需）
├── references/ # 参考资料（可选）
├── scripts/ # 脚本（可选）
└── assets/ # 静态资源（可选）
├── SKILL.md # Main entry file (required)
├── references/ # References (optional)
├── scripts/ # Scripts (optional)
└── assets/ # Static assets (optional)
```
## SKILL.md 格式
## SKILL.md Format
SKILL.md 是技能包的主入口文件，使用 YAML frontmatter + Markdown 正文格式：
SKILL.md is the main entry file of a skill package, using YAML frontmatter + Markdown body format:
```markdown
---
name: my-skill
description: 一句话描述这个技能的用途
description: One sentence describing what this skill is for
x-astron-category: code-review
---
# 技能说明
# Skill Description
这里是技能的详细说明...
Detailed skill description goes here...
```
### Frontmatter 字段
### Frontmatter Fields
| 字段 | 必需 | 说明 |
|------|------|------|
| `name` | 是 | 技能标识，kebab-case 格式 |
| `description` | 是 | 技能简短描述 |
| `x-astron-category` | 否 | 分类标签 |
| `x-astron-runtime` | 否 | 运行时要求 |
| `x-astron-min-version` | 否 | 最低版本要求 |
| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Skill identifier, kebab-case format |
| `description` | Yes | Brief skill description |
| `x-astron-category` | No | Category tag |
| `x-astron-runtime` | No | Runtime requirement |
| `x-astron-min-version` | No | Minimum version requirement |
## 文件限制
## File Limits
- 单文件大小：最大 1MB
- 总包大小：最大 10MB
- 文件数量：最多 100 个
- 允许的文件类型：`.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.js`, `.ts`, `.py`, `.sh`, `.png`, `.jpg`, `.svg`
- Single file size: Max 1MB
- Total package size: Max 10MB
- File count: Max 100
- Allowed file types: `.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.js`, `.ts`, `.py`, `.sh`, `.png`, `.jpg`, `.svg`
## 下一步
## Next Steps
- [发布流程](./publish) - 发布技能包
- [Publish Workflow](./publish) - Publish skill package

58
document/docs/03-user-guide/publishing/publish.md
View file

@ -1,50 +1,50 @@
---
title: 发布流程
title: Publish Workflow
sidebar_position: 2
description: 发布技能到 SkillHub
description: Publish skills to SkillHub
---
# 发布流程
# Publish Workflow
## 通过 Web 发布
## Publish via Web
1. 登录 SkillHub
2. 点击"发布技能"
3. 选择目标命名空间
4. 上传技能包 ZIP 文件
5. 填写版本信息（变更日志等）
6. 提交发布
7. 等待审核（如需要）
8. 审核通过后发布成功
1. Login to SkillHub
2. Click "Publish Skill"
3. Select target namespace
4. Upload skill package ZIP file
5. Fill in version information (changelog, etc.)
6. Submit publishing
7. Wait for review (if required)
8. Published successfully after review approval
## 通过 CLI 发布
## Publish via CLI
```bash
# 1. 登录
clawhub login
# 1. Login
skillhub login
# 2. 发布
clawhub publish ./my-skill.zip --namespace @team-myteam
# 2. Publish
skillhub publish ./my-skill.zip --namespace @team-myteam
```
## 通过 ClawHub CLI 发布
## Publish via ClawHub CLI
配置 registry 后使用：
Use after configuring registry:
```bash
clawhub publish ./my-skill.zip
```
## 发布状态
## Publishing Status
| 状态 | 说明 |
|------|------|
| `DRAFT` | 草稿，未提交审核 |
| `PENDING_REVIEW` | 等待审核 |
| `PUBLISHED` | 已发布，可被发现和下载 |
| `REJECTED` | 已拒绝，需修改后重新提交 |
| `YANKED` | 已撤回，不再推荐使用 |
| Status | Description |
|--------|-------------|
| `DRAFT` | Draft, not submitted for review |
| `PENDING_REVIEW` | Pending review |
| `PUBLISHED` | Published, discoverable and downloadable |
| `REJECTED` | Rejected, need modification and resubmit |
| `YANKED` | Withdrawn, no longer recommended for use |
## 下一步
## Next Steps
- [版本管理](./versioning) - 管理技能版本
- [Version Management](./versioning) - Manage skill versions

54
document/docs/03-user-guide/publishing/versioning.md
View file

@ -1,56 +1,56 @@
---
title: 版本管理
title: Version Management
sidebar_position: 3
description: 技能版本和标签管理
description: Skill version and tag management
---
# 版本管理
# Version Management
## 语义化版本
## Semantic Versioning
SkillHub 使用语义化版本（Semantic Versioning）：`MAJOR.MINOR.PATCH`
SkillHub uses Semantic Versioning: `MAJOR.MINOR.PATCH`
- `MAJOR`：不兼容的 API 变更
- `MINOR`：向后兼容的功能新增
- `PATCH`：向后兼容的问题修复
- `MAJOR`: Incompatible API changes
- `MINOR`: Backward compatible feature additions
- `PATCH`: Backward compatible bug fixes
示例：`1.0.0`, `1.1.0`, `2.0.0`
Examples: `1.0.0`, `1.1.0`, `2.0.0`
## latest 标签
## latest Tag
`latest` 是系统保留标签，自动跟随最新已发布版本，不可手动移动。
`latest` is a system reserved tag that automatically follows the latest published version and cannot be manually moved.
## 自定义标签
## Custom Tags
可创建自定义标签用于版本通道管理：
You can create custom tags for version channel management:
- `beta` - 测试版本
- `stable` - 稳定版本
- `stable-2026q1` - 季度稳定版本
- `beta` - Beta version
- `stable` - Stable version
- `stable-2026q1` - Quarterly stable version
### 创建/移动标签
### Create/Move Tag
```bash
clawhub tag set @team/my-skill beta 1.2.0
```
### 删除标签
### Delete Tag
```bash
clawhub tag delete @team/my-skill beta
```
## 版本撤回
## Version Withdrawal
已发布版本发现问题可撤回：
Published versions with issues can be withdrawn:
1. 进入技能详情页
2. 找到目标版本
3. 点击"撤回版本"
4. 确认撤回
1. Go to skill detail page
2. Find target version
3. Click "Withdraw Version"
4. Confirm withdrawal
撤回后的版本仍可查看，但会标记为不推荐使用。
Withdrawn versions remain visible but are marked as not recommended for use.
## 下一步
## Next Steps
- [搜索技能](../discovery/search) - 发现技能
- [Search Skills](../discovery/search) - Discover skills

4
document/docs/04-developer/_category_.json
View file

@ -1,8 +1,8 @@
{
"label": "开发者参考",
"label": "Developer Reference",
"position": 4,
"link": {
"type": "generated-index",
"description": "API 参考、架构设计和扩展开发"
"description": "API reference, architecture design, and extension development"
}
}

2
document/docs/04-developer/api/_category_.json
View file

@ -1,4 +1,4 @@
{
"label": "API 参考",
"label": "API Reference",
"position": 1
}

32
document/docs/04-developer/api/authenticated.md
View file

@ -1,26 +1,26 @@
---
title: 认证 API
title: Authenticated APIs
sidebar_position: 3
description: 需要认证的 API
description: APIs requiring authentication
---
# 认证 API
# Authenticated APIs
## 认证相关
## Authentication Related
### 获取当前用户
### Get Current User
```http
GET /api/v1/auth/me
```
### 登出
### Logout
```http
POST /api/v1/auth/logout
```
## 技能发布
## Skill Publishing
```http
POST /api/v1/publish
@ -30,14 +30,14 @@ file: <zip-file>
namespace: <namespace-slug>
```
## 收藏
## Favorites
```http
POST /api/v1/skills/{namespace}/{slug}/star
DELETE /api/v1/skills/{namespace}/{slug}/star
```
## 评分
## Ratings
```http
POST /api/v1/skills/{namespace}/{slug}/rating
@ -48,7 +48,7 @@ Content-Type: application/json
}
```
## 标签管理
## Tag Management
```http
GET /api/v1/skills/{namespace}/{slug}/tags
@ -56,14 +56,14 @@ PUT /api/v1/skills/{namespace}/{slug}/tags/{tagName}
DELETE /api/v1/skills/{namespace}/{slug}/tags/{tagName}
```
## 我的资源
## My Resources
```http
GET /api/v1/me/stars
GET /api/v1/me/skills
```
## 命名空间管理
## Namespace Management
```http
POST /api/v1/namespaces
@ -74,7 +74,7 @@ PUT /api/v1/namespaces/{slug}/members/{userId}/role
DELETE /api/v1/namespaces/{slug}/members/{userId}
```
## 审核
## Reviews
```http
GET /api/v1/namespaces/{slug}/reviews
@ -82,7 +82,7 @@ POST /api/v1/namespaces/{slug}/reviews/{id}/approve
POST /api/v1/namespaces/{slug}/reviews/{id}/reject
```
## 提升申请
## Promotion Requests
```http
POST /api/v1/namespaces/{slug}/skills/{skillId}/promote
@ -96,6 +96,6 @@ GET /api/v1/tokens
DELETE /api/v1/tokens/{id}
```
## 下一步
## Next Steps
- [CLI 兼容层](./cli-compat) - ClawHub 兼容接口
- [CLI Compatibility Layer](./cli-compat) - ClawHub compatible endpoints

58
document/docs/04-developer/api/cli-compat.md
View file

@ -1,54 +1,54 @@
---
title: CLI 兼容层
title: CLI Compatibility Layer
sidebar_position: 4
description: ClawHub CLI 协议兼容层
description: ClawHub CLI protocol compatibility layer
---
# CLI 兼容层
# CLI Compatibility Layer
SkillHub 提供 ClawHub CLI 协议兼容层，现有工具可无缝迁移。
SkillHub provides a ClawHub CLI protocol compatibility layer for seamless migration of existing tools.
## 配置 ClawHub CLI
## Configuring ClawHub CLI
要让 ClawHub CLI 连接到你的 SkillHub 实例，需要配置以下环境变量：
To connect ClawHub CLI to your SkillHub instance, configure the following environment variables:
### 环境变量配置
### Environment Variable Configuration
**Linux/macOS (bash/zsh):**
```bash
# ~/.bashrc 或 ~/.zshrc
# ~/.bashrc or ~/.zshrc
export CLAWHUB_SITE=https://skill.xfyun.cn
export CLAWHUB_REGISTRY=https://skill.xfyun.cn
```
**Windows (PowerShell):**
```powershell
# 永久设置（当前用户）
# Permanent setting (current user)
[Environment]::SetEnvironmentVariable('CLAWHUB_SITE', 'https://skill.xfyun.cn', 'User')
[Environment]::SetEnvironmentVariable('CLAWHUB_REGISTRY', 'https://skill.xfyun.cn', 'User')
# 或者临时设置（当前会话）
# Or temporary setting (current session)
$env:CLAWHUB_SITE = 'https://skill.xfyun.cn'
$env:CLAWHUB_REGISTRY = 'https://skill.xfyun.cn'
```
### 使用 CLI 标志（单次命令）
### Using CLI Flags (Single Command)
```bash
clawhub --site https://skill.xfyun.cn --registry https://skill.xfyun.cn install <skill>
```
### 前端一键复制
### One-click Copy from Web UI
SkillHub 网页端的技能详情页会自动显示带有正确环境变量的安装命令，直接复制即可使用。
The SkillHub skill detail page automatically displays install commands with the correct environment variables pre-configured. Simply copy and use.
## Well-known 发现
## Well-known Discovery
```http
GET /.well-known/clawhub.json
```
响应：
Response:
```json
{
@ -56,7 +56,7 @@ GET /.well-known/clawhub.json
}
```
## 兼容层 API
## Compatibility Layer APIs
### Whoami
@ -64,7 +64,7 @@ GET /.well-known/clawhub.json
GET /api/v1/whoami
```
响应：
Response:
```json
{
@ -74,13 +74,13 @@ GET /api/v1/whoami
}
```
### 搜索
### Search
```http
GET /api/v1/search?q={keyword}&page={page}&limit={limit}
```
响应：
Response:
```json
{
@ -106,13 +106,13 @@ GET /api/v1/search?q={keyword}&page={page}&limit={limit}
}
```
### 解析
### Resolve
```http
GET /api/v1/resolve?slug={slug}&version={version}
```
响应：
Response:
```json
{
@ -122,13 +122,13 @@ GET /api/v1/resolve?slug={slug}&version={version}
}
```
### 下载
### Download
```http
GET /api/v1/download/{slug}/{version}
```
### 发布
### Publish
```http
POST /api/v1/publish
@ -137,7 +137,7 @@ Content-Type: multipart/form-data
file: <zip-file>
```
响应：
Response:
```json
{
@ -147,13 +147,13 @@ file: <zip-file>
}
```
## 坐标映射
## Coordinate Mapping
| SkillHub 坐标 | ClawHub canonical slug |
|---------------|------------------------|
| SkillHub Coordinate | ClawHub canonical slug |
|---------------------|------------------------|
| `@global/my-skill` | `my-skill` |
| `@team-name/my-skill` | `team-name--my-skill` |
## 下一步
## Next Steps
- [系统架构](../architecture/overview) - 了解架构设计
- [System Architecture](../architecture/overview) - Understand architecture design

64
document/docs/04-developer/api/overview.md
View file

@ -1,52 +1,52 @@
---
title: API 概述
title: API Overview
sidebar_position: 1
description: SkillHub API 概述
description: SkillHub API overview
---
# API 概述
# API Overview
SkillHub 提供 RESTful API 用于集成和自动化。
SkillHub provides RESTful APIs for integration and automation.
## API 分类
## API Categories
### 公开 API
- 技能搜索
- 技能详情
- 版本列表
- 下载技能
- 无需认证（PUBLIC 技能）
### Public APIs
- Skill search
- Skill details
- Version list
- Download skills
- No authentication required (for PUBLIC skills)
### 认证 API
- 发布技能
- 收藏/评分
- 命名空间管理
- 需要登录或 Bearer Token
### Authenticated APIs
- Publish skills
- Favorites/ratings
- Namespace management
- Requires login or Bearer Token
### CLI 兼容层
- 兼容 ClawHub CLI 协议
- 现有工具可无缝迁移
### CLI Compatibility Layer
- ClawHub CLI protocol compatible
- Existing tools can migrate seamlessly
## 响应格式
## Response Format
### 统一响应结构
### Unified Response Structure
```json
{
"code": 0,
"msg": "成功",
"msg": "Success",
"data": {},
"timestamp": "2026-03-15T06:00:00Z",
"requestId": "req-123"
}
```
### 分页响应
### Pagination Response
```json
{
"code": 0,
"msg": "成功",
"msg": "Success",
"data": {
"items": [],
"total": 100,
@ -58,29 +58,29 @@ SkillHub 提供 RESTful API 用于集成和自动化。
}
```
## 认证方式
## Authentication Methods
### Session Cookie
Web 端使用 Session Cookie 认证。
Web side uses Session Cookie authentication.
### Bearer Token
CLI 和 API 集成使用 Bearer Token：
CLI and API integration use Bearer Token:
```bash
Authorization: Bearer <token>
```
### API Token
可创建长期有效的 API Token 用于自动化。
Can create long-lived API Tokens for automation.
## 幂等性
## Idempotency
所有写操作支持 `X-Request-Id` 请求头实现幂等：
All write operations support `X-Request-Id` header for idempotency:
```bash
X-Request-Id: <uuid-v4>
```
## 下一步
## Next Steps
- [公开 API](./public) - 查看公开接口
- [Public APIs](./public) - View public endpoints

36
document/docs/04-developer/api/public.md
View file

@ -1,72 +1,72 @@
---
title: 公开 API
title: Public APIs
sidebar_position: 2
description: 无需认证的公开 API
description: Public APIs without authentication
---
# 公开 API
# Public APIs
## 技能搜索
## Skill Search
```http
GET /api/v1/skills?keyword=...&namespace=...&page=1&size=20
```
**Query Parameters:**
- `keyword`: 搜索关键词
- `namespace`: 命名空间筛选
- `page`: 页码
- `size`: 每页数量
- `keyword`: Search keyword
- `namespace`: Namespace filter
- `page`: Page number
- `size`: Page size
## 技能详情
## Skill Details
```http
GET /api/v1/skills/{namespace}/{slug}
```
## 版本列表
## Version List
```http
GET /api/v1/skills/{namespace}/{slug}/versions
```
## 版本详情
## Version Details
```http
GET /api/v1/skills/{namespace}/{slug}/versions/{version}
```
## 文件清单
## File List
```http
GET /api/v1/skills/{namespace}/{slug}/versions/{version}/files
```
## 下载技能
## Download Skill
```http
GET /api/v1/skills/{namespace}/{slug}/download
GET /api/v1/skills/{namespace}/{slug}/versions/{version}/download
```
## 解析版本
## Resolve Version
```http
GET /api/v1/skills/{namespace}/{slug}/resolve?version=...&tag=...
```
## 命名空间列表
## Namespace List
```http
GET /api/v1/namespaces
```
## 命名空间详情
## Namespace Details
```http
GET /api/v1/namespaces/{slug}
```
## 下一步
## Next Steps
- [认证 API](./authenticated) - 查看认证接口
- [Authenticated APIs](./authenticated) - View authenticated endpoints

2
document/docs/04-developer/architecture/_category_.json
View file

@ -1,4 +1,4 @@
{
"label": "架构设计",
"label": "Architecture",
"position": 2
}

98
document/docs/04-developer/architecture/domain-model.md
View file

@ -1,77 +1,77 @@
---
title: 领域模型
title: Domain Model
sidebar_position: 2
description: 核心领域实体和关系
description: Core domain entities and relationships
---
# 领域模型
# Domain Model
## 核心实体
## Core Entities
### Namespace（命名空间）
### Namespace
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| slug | varchar(64) | URL 友好标识 |
| display_name | varchar(128) | 展示名 |
| Field | Type | Description |
|-------|------|-------------|
| id | bigint | Primary key |
| slug | varchar(64) | URL-friendly identifier |
| display_name | varchar(128) | Display name |
| type | enum | `GLOBAL` / `TEAM` |
| description | text | 描述 |
| description | text | Description |
| status | enum | `ACTIVE` / `FROZEN` / `ARCHIVED` |
### NamespaceMember（命名空间成员）
### NamespaceMember
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| namespace_id | bigint | 命名空间 ID |
| user_id | varchar(128) | 用户 ID |
| Field | Type | Description |
|-------|------|-------------|
| id | bigint | Primary key |
| namespace_id | bigint | Namespace ID |
| user_id | varchar(128) | User ID |
| role | enum | `OWNER` / `ADMIN` / `MEMBER` |
### Skill（技能）
### Skill
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| namespace_id | bigint | 所属命名空间 |
| slug | varchar(128) | URL 友好标识 |
| display_name | varchar(256) | 展示名 |
| summary | varchar(512) | 摘要 |
| owner_id | varchar(128) | 主要维护人 |
| Field | Type | Description |
|-------|------|-------------|
| id | bigint | Primary key |
| namespace_id | bigint | Parent namespace |
| slug | varchar(128) | URL-friendly identifier |
| display_name | varchar(256) | Display name |
| summary | varchar(512) | Summary |
| owner_id | varchar(128) | Primary maintainer |
| visibility | enum | `PUBLIC` / `NAMESPACE_ONLY` / `PRIVATE` |
| status | enum | `ACTIVE` / `HIDDEN` / `ARCHIVED` |
| latest_version_id | bigint | 最新已发布版本 |
| latest_version_id | bigint | Latest published version |
**唯一约束**：`(namespace_id, slug)`
**Unique constraint**: `(namespace_id, slug)`
### SkillVersion（技能版本）
### SkillVersion
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| skill_id | bigint | 技能 ID |
| version | varchar(32) | semver 版本号 |
| Field | Type | Description |
|-------|------|-------------|
| id | bigint | Primary key |
| skill_id | bigint | Skill ID |
| version | varchar(32) | semver version |
| status | enum | `DRAFT` / `PENDING_REVIEW` / `PUBLISHED` / `REJECTED` / `YANKED` |
| manifest_json | json | 文件清单 |
| parsed_metadata_json | json | SKILL.md 解析结果 |
| manifest_json | json | File manifest |
| parsed_metadata_json | json | SKILL.md parsed result |
**唯一约束**：`(skill_id, version)`
**Unique constraint**: `(skill_id, version)`
### SkillTag（技能标签）
### SkillTag
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| skill_id | bigint | 技能 ID |
| tag_name | varchar(64) | 标签名 |
| target_version_id | bigint | 目标版本 |
| Field | Type | Description |
|-------|------|-------------|
| id | bigint | Primary key |
| skill_id | bigint | Skill ID |
| tag_name | varchar(64) | Tag name |
| target_version_id | bigint | Target version |
**唯一约束**：`(skill_id, tag_name)`
**Unique constraint**: `(skill_id, tag_name)`
## 坐标系统
## Coordinate System
技能完整寻址：`@{namespace_slug}/{skill_slug}`
Full skill address: `@{namespace_slug}/{skill_slug}`
## 下一步
## Next Steps
- [安全架构](./security) - 安全设计
- [Security Architecture](./security) - Security design

52
document/docs/04-developer/architecture/overview.md
View file

@ -1,49 +1,49 @@
---
title: 系统架构
title: System Architecture
sidebar_position: 1
description: SkillHub 系统架构概览
description: SkillHub system architecture overview
---
# 系统架构
# System Architecture
## 架构原则
## Architecture Principles
- **单体优先**：一期采用模块化单体，不拆微服务
- **依赖倒置**：领域层不依赖基础设施
- **可替换边界**：搜索、存储都有 SPI 抽象
- **Monolith-first**: Phase 1 uses modular monolith, no microservices
- **Dependency Inversion**: Domain layer does not depend on infrastructure
- **Replaceable Boundaries**: Search and storage both have SPI abstractions
## 模块结构
## Module Structure
```
server/
├── skillhub-app/ # 启动、配置装配、Controller
├── skillhub-domain/ # 领域模型 + 领域服务 + 应用服务
├── skillhub-auth/ # OAuth2 认证 + RBAC + 授权判定
├── skillhub-search/ # 搜索 SPI + PostgreSQL 全文实现
├── skillhub-storage/ # 对象存储抽象 + LocalFile/S3
└── skillhub-infra/ # JPA、通用工具、配置基础
├── skillhub-app/ # Startup, configuration assembly, Controllers
├── skillhub-domain/ # Domain models + domain services + application services
├── skillhub-auth/ # OAuth2 authentication + RBAC + authorization decisions
├── skillhub-search/ # Search SPI + PostgreSQL full-text implementation
├── skillhub-storage/ # Object storage abstraction + LocalFile/S3
└── skillhub-infra/ # JPA, utilities, configuration foundation
```
## 模块依赖
## Module Dependencies
```
app → domain, auth, search, storage, infra
infra → domain
auth → domain
search → domain
storage → (独立)
storage → (independent)
```
## 技术栈
## Tech Stack
| 层级 | 技术 | 版本 |
|------|------|------|
| 运行时 | Java | 21 |
| 框架 | Spring Boot | 3.2.3 |
| 数据库 | PostgreSQL | 16.x |
| 缓存/会话 | Redis | 7.x |
| Layer | Technology | Version |
|-------|------------|---------|
| Runtime | Java | 21 |
| Framework | Spring Boot | 3.2.3 |
| Database | PostgreSQL | 16.x |
| Cache/Session | Redis | 7.x |
## 部署架构
## Deployment Architecture
```
┌──────────────┐
@ -64,6 +64,6 @@ storage → (独立)
PostgreSQL Redis
```
## 下一步
## Next Steps
- [领域模型](./domain-model) - 核心实体
- [Domain Model](./domain-model) - Core entities

90
document/docs/04-developer/architecture/security.md
View file

@ -1,71 +1,71 @@
---
title: 安全架构
title: Security Architecture
sidebar_position: 3
description: 安全架构设计
description: Security architecture design
---
# 安全架构
# Security Architecture
## 认证架构
## Authentication Architecture
### OAuth2 登录
### OAuth2 Login
- 基于 Spring Security OAuth2 Client
- 一期支持 GitHub
- 架构支持扩展多 Provider
- Based on Spring Security OAuth2 Client
- Phase 1 supports GitHub
- Architecture supports extending multiple providers
### CLI 认证
### CLI Authentication
- OAuth Device Flow
- Web 授权后签发 CLI 凭证
- 支持 API Token
- Web authorization issues CLI credentials
- Supports API Token
### Session 管理
### Session Management
- Spring Session + Redis
- 分布式 Session 共享
- 支持多 Pod 部署
- Distributed session sharing
- Supports multi-pod deployment
## 授权架构
## Authorization Architecture
### 平台角色
### Platform Roles
| 角色 | 权限 |
|------|------|
| `SUPER_ADMIN` | 所有权限 |
| `SKILL_ADMIN` | 技能治理 |
| `USER_ADMIN` | 用户治理 |
| `AUDITOR` | 审计只读 |
| Role | Permissions |
|------|-------------|
| `SUPER_ADMIN` | All permissions |
| `SKILL_ADMIN` | Skill governance |
| `USER_ADMIN` | User governance |
| `AUDITOR` | Audit read-only |
### 命名空间角色
### Namespace Roles
| 角色 | 权限 |
|------|------|
| `OWNER` | 命名空间所有者 |
| `ADMIN` | 审核、成员管理 |
| `MEMBER` | 发布技能 |
| Role | Permissions |
|------|-------------|
| `OWNER` | Namespace owner |
| `ADMIN` | Review, member management |
| `MEMBER` | Publish skills |
### 可见性规则
### Visibility Rules
| 可见性 | 谁可访问 |
|--------|---------|
| `PUBLIC` | 任何人（匿名） |
| `NAMESPACE_ONLY` | 命名空间成员 |
| `PRIVATE` | owner + 命名空间 ADMIN |
| Visibility | Who can access |
|------------|----------------|
| `PUBLIC` | Anyone (anonymous) |
| `NAMESPACE_ONLY` | Namespace members |
| `PRIVATE` | owner + namespace ADMIN |
## 审计
## Auditing
所有关键操作同步写入审计日志：
- 发布、下载、删除
- 审核通过、拒绝
- 权限变更
- 配置变更
All critical operations synchronously write to audit logs:
- Publish, download, delete
- Review approval, rejection
- Permission changes
- Configuration changes
## 限流
## Rate Limiting
- Ingress 层基础限流（Nginx）
- 应用层精细限流（Redis 滑动窗口）
- Ingress layer basic rate limiting (Nginx)
- Application layer fine-grained rate limiting (Redis sliding window)
## 下一步
## Next Steps
- [技能协议](../plugins/skill-protocol) - 技能包规范
- [Skill Protocol](../plugins/skill-protocol) - Skill package specification

2
document/docs/04-developer/plugins/_category_.json
View file

@ -1,4 +1,4 @@
{
"label": "扩展与集成",
"label": "Extensions & Integrations",
"position": 3
}

66
document/docs/04-developer/plugins/skill-protocol.md
View file

@ -1,14 +1,14 @@
---
title: 技能协议
title: Skill Protocol
sidebar_position: 1
description: SKILL.md 规范和技能包协议
description: SKILL.md specification and skill package protocol
---
# 技能协议
# Skill Protocol
## SKILL.md 规范
## SKILL.md Specification
### 基本格式
### Basic Format
```markdown
---
@ -16,53 +16,53 @@ name: my-skill
description: When to use this skill
---
# Markdown 正文
# Markdown Body
技能指令内容...
Skill instruction content...
```
### 必需字段
### Required Fields
| 字段 | 说明 |
|------|------|
| `name` | 技能标识，kebab-case |
| `description` | 技能简短描述 |
| Field | Description |
|-------|-------------|
| `name` | Skill identifier, kebab-case |
| `description` | Brief skill description |
### 扩展字段
### Extension Fields
| 字段 | 说明 |
|------|------|
| `x-astron-category` | 分类标签 |
| `x-astron-runtime` | 运行时要求 |
| `x-astron-min-version` | 最低版本要求 |
| Field | Description |
|-------|-------------|
| `x-astron-category` | Category tag |
| `x-astron-runtime` | Runtime requirement |
| `x-astron-min-version` | Minimum version requirement |
## 技能包结构
## Skill Package Structure
```
my-skill/
├── SKILL.md # 主入口文件（必需）
├── references/ # 参考资料（可选）
├── scripts/ # 脚本（可选）
└── assets/ # 静态资源（可选）
├── SKILL.md # Main entry file (required)
├── references/ # References (optional)
├── scripts/ # Scripts (optional)
└── assets/ # Static assets (optional)
```
## 文件校验
## File Validation
- 根目录必须包含 `SKILL.md`
- 文件类型白名单
- 单文件大小限制：1MB
- 总包大小限制：10MB
- 文件数量限制：100 个
- Root directory must contain `SKILL.md`
- File type whitelist
- Single file size limit: 1MB
- Total package size limit: 10MB
- File count limit: 100
## 客户端安装目录
## Client Installation Directory
按以下优先级安装：
Install by the following priority:
1. `./.agent/skills/`
2. `~/.agent/skills/`
3. `./.claude/skills/`
4. `~/.claude/skills/`
## 下一步
## Next Steps
- [存储 SPI](./storage-spi) - 扩展存储后端
- [Storage SPI](./storage-spi) - Extend storage backend

57
document/docs/04-developer/plugins/storage-spi.md
View file

@ -1,12 +1,12 @@
---
title: 存储 SPI
title: Storage SPI
sidebar_position: 2
description: 存储服务提供方扩展
description: Storage service provider extension
---
# 存储 SPI
# Storage SPI
## SPI 接口
## SPI Interface
```java
public interface ObjectStorageService {
@ -17,61 +17,38 @@ public interface ObjectStorageService {
}
```
## 内置实现
## Built-in Implementations
### LocalFileStorageService
本地文件系统实现，用于开发环境。
Local filesystem implementation for development environment.
### S3StorageService
S3 协议兼容实现，支持：
S3 protocol compatible implementation, supports:
- AWS S3
- MinIO
- 阿里云 OSS
- 腾讯云 COS
- 其他 S3 兼容存储
- Alibaba Cloud OSS
- Tencent Cloud COS
- Other S3-compatible storage
## 配置
### 静态凭据（Access Key / Secret Key）
## Configuration
```bash
# 选择存储提供方
# Select storage provider
SKILLHUB_STORAGE_PROVIDER=s3
# S3 配置
# S3 configuration
SKILLHUB_STORAGE_S3_ENDPOINT=https://s3.example.com
SKILLHUB_STORAGE_S3_BUCKET=skillhub
SKILLHUB_STORAGE_S3_ACCESS_KEY=xxx
SKILLHUB_STORAGE_S3_SECRET_KEY=xxx
```
### IAM 认证
## Custom Implementation
部署在 AWS 上时，可以不配置 Access Key / Secret Key，让 SDK 自动使用 IAM 角色认证（[Default Credentials Provider Chain](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-chain.html)）：
Implement `ObjectStorageService` interface and register as Spring Bean.
```bash
SKILLHUB_STORAGE_PROVIDER=s3
SKILLHUB_STORAGE_S3_BUCKET=skillhub
SKILLHUB_STORAGE_S3_REGION=us-east-1
# 留空或不设置 ACCESS_KEY / SECRET_KEY，SDK 自动使用 IAM 认证
SKILLHUB_STORAGE_S3_ACCESS_KEY=
SKILLHUB_STORAGE_S3_SECRET_KEY=
```
## Next Steps
支持的 IAM 认证方式（按 SDK 优先级）：
- 环境变量（`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`）
- Java 系统属性
- Web Identity Token（EKS IRSA）
- AWS 配置文件（`~/.aws/credentials`）
- EC2 Instance Profile
- ECS Task Role
## 自定义实现
实现 `ObjectStorageService` 接口，注册为 Spring Bean 即可。
## 下一步
- [常见问题](../../reference/faq) - FAQ
- [FAQ](../../reference/faq) - FAQ

4
document/docs/05-reference/_category_.json
View file

@ -1,8 +1,8 @@
{
"label": "参考资料",
"label": "Reference",
"position": 5,
"link": {
"type": "generated-index",
"description": "FAQ、故障排查和更多资源"
"description": "FAQ, troubleshooting, and more resources"
}
}

20
document/docs/05-reference/changelog.md
View file

@ -1,20 +1,20 @@
---
title: 变更日志
title: Changelog
sidebar_position: 3
description: 版本变更历史
description: Version change history
---
# 变更日志
# Changelog
## [Unreleased]
### Added
- 初始版本发布
- 技能发布与管理
- 命名空间与 RBAC
- 全文搜索
- ClawHub CLI 兼容层
- Initial version release
- Skill publishing and management
- Namespace and RBAC
- Full-text search
- ClawHub CLI compatibility layer
## 下一步
## Next Steps
- [路线图](./roadmap) - 未来规划
- [Roadmap](./roadmap) - Future plans

52
document/docs/05-reference/faq.md
View file

@ -1,49 +1,49 @@
---
title: 常见问题
title: FAQ
sidebar_position: 1
description: 常见问题解答
description: Frequently asked questions
---
# 常见问题
# FAQ
## 部署相关
## Deployment Related
### 如何修改默认端口？
### How to change default port?
修改 `.env.release` 中的端口配置。
Modify port configuration in `.env.release`.
### 如何配置 HTTPS？
### How to configure HTTPS?
建议使用反向代理（Nginx/Ingress）处理 TLS 终止。
Recommended to use reverse proxy (Nginx/Ingress) for TLS termination.
### 数据库如何备份？
### How to backup database?
使用 PostgreSQL 标准备份工具（pg_dump）。
Use PostgreSQL standard backup tools (pg_dump).
## 使用相关
## Usage Related
### 如何重置管理员密码？
### How to reset admin password?
如果忘记管理员密码，可通过环境变量重新设置首登管理员，或直接操作数据库。
If you forgot admin password, you can reconfigure bootstrap admin via environment variables or directly operate the database.
### 技能包上传失败怎么办？
### Skill package upload failed?
检查：
1. 文件大小是否超限
2. 文件类型是否在白名单内
3. 是否包含必需的 SKILL.md
4. SKILL.md frontmatter 格式是否正确
Check:
1. Whether file size exceeds limit
2. Whether file type is in whitelist
3. Whether required SKILL.md is included
4. Whether SKILL.md frontmatter format is correct
## 开发相关
## Development Related
### 如何扩展 OAuth Provider？
### How to extend OAuth Provider?
参考现有 GitHub 实现，添加新的 OAuth Provider 配置。
Refer to existing GitHub implementation, add new OAuth Provider configuration.
### 如何自定义搜索实现？
### How to customize search implementation?
实现 `SearchIndexService` 和 `SearchQueryService` 接口。
Implement `SearchIndexService` and `SearchQueryService` interfaces.
## 下一步
## Next Steps
- [故障排查](./troubleshooting) - 问题诊断
- [Troubleshooting](./troubleshooting) - Problem diagnosis

58
document/docs/05-reference/roadmap.md
View file

@ -1,45 +1,45 @@
---
title: 路线图
title: Roadmap
sidebar_position: 4
description: 未来发展路线图
description: Future development roadmap
---
# 路线图
# Roadmap
## Phase 1: 基础能力 ✅
## Phase 1: Foundation ✅
- GitHub OAuth 登录
- Session 管理
- RBAC 权限体系
- GitHub OAuth login
- Session management
- RBAC permission system
## Phase 2: 技能核心 ✅
## Phase 2: Skill Core ✅
- 命名空间管理
- 技能发布与下载
- 版本管理
- PostgreSQL 全文搜索
- Namespace management
- Skill publishing and download
- Version management
- PostgreSQL full-text search
## Phase 3: 审核与 CLI
## Phase 3: Review and CLI
- 审核流程
- 技能提升到全局
- CLI 工具
- 收藏与评分
- Review workflow
- Skill promotion to global
- CLI tool
- Favorites and ratings
## Phase 4: 运维与完善
## Phase 4: Operations and Polish
- 审计日志
- 管理后台
- 可观测性
- 部署优化
- Audit logs
- Admin dashboard
- Observability
- Deployment optimization
## Phase 5: 高级特性
## Phase 5: Advanced Features
- 评论与举报
- 自动安全扫描
- 向量搜索
- Webhook 通知
- Comments and reports
- Automatic security scanning
- Vector search
- Webhook notifications
## 下一步
## Next Steps
- [快速开始](../getting-started/quick-start) - 开始使用
- [Quick Start](../getting-started/quick-start) - Get started

78
document/docs/05-reference/troubleshooting.md
View file

@ -1,63 +1,63 @@
---
title: 故障排查
title: Troubleshooting
sidebar_position: 2
description: 常见问题诊断和解决方案
description: Common problem diagnosis and solutions
---
# 故障排查
# Troubleshooting
## 服务无法启动
## Service Cannot Start
### 检查清单
### Checklist
1. 检查容器状态：`docker compose ps`
2. 查看服务日志：`docker compose logs <service>`
3. 验证环境变量：检查 `.env.release` 配置
4. 检查端口占用：`netstat -tlnp`
1. Check container status: `docker compose ps`
2. View service logs: `docker compose logs <service>`
3. Verify environment variables: Check `.env.release` configuration
4. Check port occupancy: `netstat -tlnp`
### 常见原因
### Common Causes
- 端口被占用
- 数据库连接失败
- Redis 连接失败
- 环境变量缺失
- Port occupied
- Database connection failed
- Redis connection failed
- Environment variables missing
## 上传失败
## Upload Failed
### 技能包上传失败
### Skill Package Upload Failed
1. 检查文件大小
2. 检查文件类型
3. 检查 SKILL.md 格式
4. 查看服务端日志
1. Check file size
2. Check file type
3. Check SKILL.md format
4. View server logs
## 认证问题
## Authentication Issues
### 无法登录
### Cannot Login
1. 检查 OAuth 配置
2. 检查回调地址配置
3. 检查 `SKILLHUB_PUBLIC_BASE_URL` 配置
1. Check OAuth configuration
2. Check callback URL configuration
3. Check `SKILLHUB_PUBLIC_BASE_URL` configuration
## 性能问题
## Performance Issues
### 搜索慢
### Slow Search
1. 检查 PostgreSQL 全文索引
2. 考虑升级到 Elasticsearch（后续版本）
1. Check PostgreSQL full-text index
2. Consider upgrading to Elasticsearch (future version)
### 下载慢
### Slow Download
1. 检查对象存储配置
2. 检查网络带宽
1. Check object storage configuration
2. Check network bandwidth
## 获取帮助
## Get Help
如以上方案无法解决问题：
1. 查看日志
2. 提交 Issue
3. 联系技术支持
If above solutions cannot resolve the issue:
1. View logs
2. Submit Issue
3. Contact technical support
## 下一步
## Next Steps
- [变更日志](./changelog) - 版本历史
- [Changelog](./changelog) - Version history

103
document/docs/index.md
View file

@ -1,101 +1,22 @@
---
title: SkillHub 文档中心
title: SkillHub Documentation
sidebar_position: 1
description: 企业级 AI 技能注册表 - 安全可控的技能发布、发现与管理平台
description: Enterprise-grade open source agent skill registry for governed, self-hosted publishing, discovery, and team collaboration
---
# SkillHub
<section className="hero-section">
<div className="container">
<h1 className="hero-section__title">🏢 企业级 AI 技能注册表</h1>
<p className="hero-section__tagline">
安全可控的技能发布、发现与管理平台，保障企业数据主权
</p>
<div className="hero-section__cta">
<a href="/getting-started/quick-start" className="btn-primary">立即部署</a>
<a href="/getting-started/overview" className="btn-secondary">了解更多</a>
</div>
</div>
</section>
SkillHub is an enterprise-grade open source agent skill registry for governed, self-hosted publishing, discovery, and collaboration.
---
## Start Here
## 企业价值
- [Quick Start](./getting-started/quick-start) - Deploy SkillHub with one command
- [Overview](./getting-started/overview) - Understand product positioning and core concepts
- [Use Cases](./getting-started/use-cases) - See where SkillHub fits in real organizations
<div className="row" style={{ marginTop: '40px', marginBottom: '40px' }}>
<div className="col col--3">
<div className="enterprise-value-card">
<div className="enterprise-value-card__icon">🔐</div>
<h3 className="enterprise-value-card__title">数据主权可控</h3>
<p className="enterprise-value-card__description">
自托管部署，数据不离开企业网络；支持私有 S3/MinIO 存储；完整审计链路
</p>
</div>
</div>
<div className="col col--3">
<div className="enterprise-value-card">
<div className="enterprise-value-card__icon">🏢</div>
<h3 className="enterprise-value-card__title">治理体系完善</h3>
<p className="enterprise-value-card__description">
命名空间隔离；双层审核机制；细粒度 RBAC 权限控制
</p>
</div>
</div>
<div className="col col--3">
<div className="enterprise-value-card">
<div className="enterprise-value-card__icon">🔌</div>
<h3 className="enterprise-value-card__title">集成能力强</h3>
<p className="enterprise-value-card__description">
兼容 ClawHub CLI；标准 REST API；OAuth2 企业 SSO 集成
</p>
</div>
</div>
<div className="col col--3">
<div className="enterprise-value-card">
<div className="enterprise-value-card__icon">📊</div>
<h3 className="enterprise-value-card__title">可观测性完善</h3>
<p className="enterprise-value-card__description">
完整审计日志；Prometheus 指标；操作追踪与溯源
</p>
</div>
</div>
</div>
## Key Areas
---
## 核心功能特性
<div style={{ textAlign: 'center', marginTop: '40px' }}>
<div className="feature-tags">
<span className="feature-tag">版本控制</span>
<span className="feature-tag">全文搜索</span>
<span className="feature-tag">命名空间</span>
<span className="feature-tag">审核流程</span>
<span className="feature-tag">语义化版本</span>
<span className="feature-tag">多维度筛选</span>
<span className="feature-tag">RBAC 权限</span>
<span className="feature-tag">审计日志</span>
</div>
</div>
---
## 快速开始
<div style={{ textAlign: 'center', marginTop: '40px' }}>
<div className="quick-start-code">
<code>$ curl -fsSL https://raw.githubusercontent.com/iflytek/skillhub/main/scripts/runtime.sh | sh -s -- up</code>
</div>
<p style={{ marginTop: '16px', color: 'var(--ifm-font-color-secondary)' }}>
访问 <a href="http://localhost:3000">http://localhost:3000</a> 开始使用
</p>
</div>
---
## 下一步
- [快速开始](./getting-started/quick-start) - 一键启动 SkillHub
- [产品概述](./getting-started/overview) - 了解更多产品特性
- [部署指南](./administration/deployment/single-machine) - 生产环境部署
- [Administration](./administration/deployment/single-machine) - Deployment, security, governance, and operations
- [User Guide](./user-guide/publishing/publish) - Publishing, discovery, collaboration, and promotion workflows
- [Developer Reference](./developer/api/overview) - APIs, architecture, plugins, and protocol compatibility
- [Reference](./reference/faq) - FAQ, troubleshooting, changelog, and roadmap

123
document/docusaurus.config.js
View file

@ -3,27 +3,26 @@ import { themes as prismThemes } from 'prism-react-renderer';
/** @type {import('@docusaurus/types').Config} */
const config = {
title: 'SkillHub',
tagline: '企业级 AI 技能注册表',
favicon: 'img/favicon.ico',
tagline: 'Enterprise-grade Open Source Agent Skill Registry',
url: 'https://skillhub.iflytek.com',
url: 'https://www.astron-skillhub.org',
baseUrl: '/',
organizationName: 'iflytek',
projectName: 'skillhub',
i18n: {
defaultLocale: 'zh-CN',
locales: ['zh-CN', 'en'],
defaultLocale: 'en',
locales: ['en', 'zh-CN'],
localeConfigs: {
'zh-CN': {
label: '中文',
htmlLang: 'zh-CN',
},
'en': {
label: 'English',
htmlLang: 'en',
},
'zh-CN': {
label: '中文',
htmlLang: 'zh-CN',
},
},
},
@ -33,7 +32,7 @@ const config = {
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
routeBasePath: '/',
routeBasePath: '/docs',
sidebarPath: './sidebars.js',
editUrl: 'https://github.com/iflytek/skillhub/edit/main/document/',
},
@ -47,19 +46,31 @@ const config = {
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
image: 'img/og-image.png',
navbar: {
title: 'SkillHub',
logo: {
alt: 'SkillHub Logo',
src: 'img/logo.svg',
alt: 'Astron SkillHub Logo',
src: 'img/astron-skillhub-logo.svg',
},
items: [
{
type: 'docSidebar',
sidebarId: 'docsSidebar',
to: '/docs/getting-started/quick-start',
position: 'left',
label: '文档',
label: 'Quick Start',
},
{
to: '/docs/getting-started/overview',
position: 'left',
label: 'Overview',
},
{
to: '/docs/user-guide/publishing/publish',
position: 'left',
label: 'Publish Workflow',
},
{
to: '/docs/administration/deployment/single-machine',
position: 'left',
label: 'Single Node',
},
{
type: 'localeDropdown',
@ -76,24 +87,24 @@ const config = {
style: 'dark',
links: [
{
title: '文档',
title: 'Documentation',
items: [
{
label: '快速开始',
to: '/getting-started/quick-start',
label: 'Quick Start',
to: '/docs/getting-started/quick-start',
},
{
label: '部署指南',
to: '/administration/deployment/single-machine',
label: 'Deployment',
to: '/docs/administration/deployment/single-machine',
},
{
label: 'API 参考',
to: '/developer/api/overview',
label: 'API Reference',
to: '/docs/developer/api/overview',
},
],
},
{
title: '社区',
title: 'Community',
items: [
{
label: 'GitHub',
@ -104,12 +115,74 @@ const config = {
],
copyright: `Copyright © ${new Date().getFullYear()} iFlytek. Built with Docusaurus.`,
},
metadata: [
{
name: 'keywords',
content: 'SkillHub, skill registry, agent skills, self-hosted, enterprise ai',
},
],
prism: {
theme: prismThemes.github,
darkTheme: prismThemes.dracula,
additionalLanguages: ['java', 'bash', 'yaml', 'json'],
},
}),
plugins: [
[
'@docusaurus/plugin-client-redirects',
{
createRedirects(existingPath) {
if (existingPath === '/docs/' || existingPath === '/zh-CN/docs/') {
return undefined;
}
if (existingPath.includes('/docs/')) {
return [existingPath.replace('/docs', '')];
}
return undefined;
},
redirects: [
{
from: ['/quickstart.html'],
to: '/docs/getting-started/quick-start',
},
{
from: ['/introduction.html'],
to: '/docs/getting-started/overview',
},
{
from: ['/faq.html'],
to: '/docs/reference/faq',
},
{
from: ['/guide/skill-publish.html'],
to: '/docs/user-guide/publishing/publish',
},
{
from: ['/guide/skill-discovery.html'],
to: '/docs/user-guide/discovery/search',
},
{
from: ['/guide/namespace.html'],
to: '/docs/user-guide/collaboration/namespaces',
},
{
from: ['/guide/review.html'],
to: '/docs/administration/governance/review-workflow',
},
{
from: ['/guide/social.html'],
to: '/docs/user-guide/discovery/ratings',
},
{
from: ['/guide/scanner.html'],
to: '/docs/administration/security/scanner',
},
],
},
],
],
};
export default config;

2
document/i18n/en/docusaurus-plugin-content-docs/current/02-administration/security/authorization.md
View file

@ -23,7 +23,7 @@ The database migration seeds only 4 explicit platform roles:
| Role | Code | Effective behavior |
|------|------|--------------------|
| Super Admin | `SUPER_ADMIN` | Has all permissions. `RbacService#getUserPermissions` returns all permission codes for this role. Can access all endpoints available to `SUPER_ADMIN` / `SKILL_ADMIN` / `USER_ADMIN` / `AUDITOR`. Can assign `SUPER_ADMIN`. Can bypass namespace membership checks during publish and auto-publish directly. Can approve their own promotion request. For normal review tasks, the self-submission exception is also only bypassed by `SUPER_ADMIN`. |
| Super Admin | `SUPER_ADMIN` | Has all permissions. `RbacService#getUserPermissions` returns all permission codes for this role. Can access all endpoints available to `SUPER_ADMIN` / `SKILL_ADMIN` / `USER_ADMIN` / `AUDITOR`. Can assign `SUPER_ADMIN`. Can bypass namespace membership checks during publish and auto-publish directly. Still cannot approve their own promotion request, and for normal review tasks the self-submission exception is only bypassed by `SUPER_ADMIN`. |
| Skill Admin | `SKILL_ADMIN` | Can access skill governance admin endpoints. Can hide/unhide skills, yank versions, and resolve/dismiss skill reports. Can review global namespace review tasks, promotion requests, and governance inbox items for review/promotion/report. Cannot manage users or read audit logs. |
| User Admin | `USER_ADMIN` | Can access user management endpoints. Can list users, approve users, enable/disable users, and change platform roles. Cannot assign `SUPER_ADMIN`. Cannot perform skill governance or read audit logs. |
| Auditor | `AUDITOR` | Read-only audit access. Can access `/api/v1/admin/audit-logs` and `/actuator/prometheus`. In the governance workbench this role can read activity, but cannot process review/promotion/report items and cannot manage users or skills. |

104
document/i18n/en/docusaurus-plugin-content-docs/current/02-administration/security/scanner.md Normal file
View file

@ -0,0 +1,104 @@
---
title: Security Scanning
sidebar_position: 4
description: Use Skill Scanner to add automated security checks to the skill publish pipeline
---
# Security Scanning
SkillHub can integrate `skill-scanner` into the publish pipeline to automatically inspect uploaded skill packages and persist the results as security audit records.
## Scan Flow
When scanning is enabled, the publish flow becomes:
1. A user publishes a skill package
2. The backend creates a version and moves it to `SCANNING`
3. The backend enqueues a scan task
4. `skill-scanner` consumes the task and runs analysis
5. The result is stored in `security_audit`
6. The version moves to `PENDING_REVIEW`, or to `SCAN_FAILED` after final retry exhaustion
7. The existing human review workflow continues afterward
## Typical Use Cases
- Add automated risk checks before manual review
- Retain scan results and audit evidence for governance
- Detect suspicious code, leaked secrets, or risky behavior patterns in skill packages
## Runtime Modes
Two modes are supported:
- `local`: the backend passes a filesystem path to the scanner, suitable for shared filesystem setups
- `upload`: the backend uploads the package archive directly, suitable for Docker, Kubernetes, and split deployments
Recommended usage:
- Local development: prefer `local`
- Production, Kubernetes, or split services: prefer `upload`
## Key Configuration
Core backend configuration:
```yaml
skillhub:
security:
scanner:
enabled: false
base-url: http://localhost:8000
health-path: /health
scan-path: /scan-upload
mode: upload
connect-timeout-ms: 5000
read-timeout-ms: 300000
retry-max-attempts: 3
```
Common environment variables:
- `SKILLHUB_SECURITY_SCANNER_ENABLED`
- `SKILLHUB_SECURITY_SCANNER_URL`
- `SKILLHUB_SECURITY_SCANNER_MODE`
- `SKILLHUB_SCAN_STREAM_KEY`
- `SKILLHUB_SCAN_STREAM_GROUP`
## How To Verify
After enabling scanning, validate it with these steps:
1. Publish a test skill package
2. Confirm the version first moves to `SCANNING`
3. Confirm a `security_audit` record is created
4. Confirm the version eventually moves to `PENDING_REVIEW` or `SCAN_FAILED`
5. Call the security audit API to inspect the result
```text
GET /api/v1/skills/{skillId}/versions/{versionId}/security-audit
```
## Result Fields
Security audit results usually include:
- `scanId`
- `scannerType`
- `verdict`
- `isSafe`
- `maxSeverity`
- `findingsCount`
- `findings`
- `scanDurationSeconds`
- `scannedAt`
## Deployment Recommendations
- Keep scanning disabled at first in local environments, then enable it after the main flow is stable
- Use `upload` mode in Kubernetes to avoid relying on a shared writable filesystem
- In production, keep scan results alongside human review records as governance evidence
## Next Steps
- [Review Workflow](../governance/review-workflow) - Understand the approval flow after scanning
- [Deployment Configuration](../deployment/configuration) - Review deployment-related settings

23
document/i18n/en/docusaurus-plugin-content-docs/current/04-developer/plugins/storage-spi.md
View file

@ -34,8 +34,6 @@ S3 protocol compatible implementation, supports:
## Configuration
### Static Credentials (Access Key / Secret Key)
```bash
# Select storage provider
SKILLHUB_STORAGE_PROVIDER=s3
@ -47,27 +45,6 @@ SKILLHUB_STORAGE_S3_ACCESS_KEY=xxx
SKILLHUB_STORAGE_S3_SECRET_KEY=xxx
```
### IAM Authentication
When deployed on AWS, you can omit the Access Key / Secret Key and let the SDK use IAM role authentication via the [Default Credentials Provider Chain](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-chain.html):
```bash
SKILLHUB_STORAGE_PROVIDER=s3
SKILLHUB_STORAGE_S3_BUCKET=skillhub
SKILLHUB_STORAGE_S3_REGION=us-east-1
# Leave ACCESS_KEY / SECRET_KEY blank to use IAM authentication
SKILLHUB_STORAGE_S3_ACCESS_KEY=
SKILLHUB_STORAGE_S3_SECRET_KEY=
```
Supported IAM authentication methods (in SDK priority order):
- Environment variables (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`)
- Java system properties
- Web Identity Token (EKS IRSA)
- AWS config file (`~/.aws/credentials`)
- EC2 Instance Profile
- ECS Task Role
## Custom Implementation
Implement `ObjectStorageService` interface and register as Spring Bean.

156
document/i18n/en/docusaurus-plugin-content-docs/current/index.md
View file

@ -1,81 +1,125 @@
---
title: SkillHub Documentation
sidebar_position: 1
description: Enterprise-grade AI Skill Registry - Secure, controllable skill publishing, discovery, and management platform
description: Enterprise-grade open source agent skill registry for governed, self-hosted publishing, discovery, and team collaboration
---
# SkillHub
<section className="hero-section">
<div className="container">
<h1 className="hero-section__title">🏢 Enterprise-grade AI Skill Registry</h1>
<p className="hero-section__tagline">
Secure, controllable skill publishing, discovery, and management platform with full enterprise data sovereignty
</p>
<div className="hero-section__cta">
<a href="/getting-started/quick-start" className="btn-primary">Deploy Now</a>
<a href="/getting-started/overview" className="btn-secondary">Learn More</a>
<div className="hero-shell">
<div className="hero-content">
<div className="hero-badge">Self-hosted Registry for Agent Skills</div>
<h1 className="hero-section__title">Ship reusable AI skills with governed discovery, review, and deployment.</h1>
<div className="hero-section__tagline">{`Astron SkillHub gives teams a polished internal registry for publishing, discovering, versioning, and operating reusable agent skill packages without the usual AI-generated design smell.`}</div>
<div className="hero-section__cta">
<a href="/getting-started/quick-start" className="btn-primary">Deploy Now</a>
<a href="/getting-started/overview" className="btn-secondary">Explore Architecture</a>
</div>
<div className="hero-proof">
<span>Semantic versioning</span>
<span>Namespace governance</span>
<span>Security scanning</span>
<span>CLI compatibility</span>
</div>
</div>
<div className="hero-visual">
<div className="hero-logo-card">
<img src="/img/astron-skillhub-logo.svg" alt="Astron SkillHub" className="hero-logo" />
<div className="hero-logo-card__membership">
<a className="hero-logo-card__membership-link" href="https://aaif.io/" target="_blank" rel="noopener noreferrer" aria-label="Agentic AI Foundation (opens in new tab)">
<img src="https://cdn.sanity.io/images/4o10fa7h/production/16dd7d8270b673d376cadca831ab3d5ea003bb89-838x203.svg" alt="Agentic AI Foundation (AAIF)" width="838" height="203" className="hero-logo-card__membership-logo" />
</a>
<div className="hero-logo-card__membership-label">AAIF Associate Member</div>
</div>
</div>
<div className="hero-stats">
<div className="hero-stat">
<strong>1</strong>
<span>Registry for teams, governance, and runtime docs</span>
</div>
<div className="hero-stat">
<strong>3</strong>
<span>Core workflows: publish, discover, review</span>
</div>
<div className="hero-stat">
<strong>24/7</strong>
<span>Suitable for always-on internal skill operations</span>
</div>
</div>
</div>
</div>
</div>
</section>
---
## Enterprise Value
## Why Teams Choose SkillHub
<div className="row" style={{ marginTop: '40px', marginBottom: '40px' }}>
<div className="col col--3">
<div className="enterprise-value-card">
<div className="enterprise-value-card__icon">🔐</div>
<h3 className="enterprise-value-card__title">Data Sovereignty</h3>
<p className="enterprise-value-card__description">
Self-hosted deployment, data stays within your network; private S3/MinIO storage; complete audit trail
</p>
<div className="feature-grid">
<div className="enterprise-value-card enterprise-value-card--featured">
<div className="enterprise-value-card__eyebrow">Publishing</div>
<h3 className="enterprise-value-card__title">Versioned delivery without registry chaos</h3>
<div className="enterprise-value-card__description">{`Semantic versioning, channel tags, and immutable package history make skill publishing feel predictable for both platform teams and daily contributors.`}</div>
<div className="enterprise-value-card__list">
<span>Semantic versioning</span>
<span>Tags like beta / stable / latest</span>
<span>Download and rollback friendly</span>
</div>
</div>
<div className="col col--3">
<div className="enterprise-value-card">
<div className="enterprise-value-card__icon">🏢</div>
<h3 className="enterprise-value-card__title">Complete Governance</h3>
<p className="enterprise-value-card__description">
Namespace isolation; two-tier review workflow; fine-grained RBAC access control
</p>
</div>
<div className="enterprise-value-card">
<div className="enterprise-value-card__eyebrow">Discovery</div>
<h3 className="enterprise-value-card__title">Search that respects permissions</h3>
<div className="enterprise-value-card__description">{`Full-text search and structured filters help users find the right skill quickly while still honoring namespace visibility and governance boundaries.`}</div>
</div>
<div className="col col--3">
<div className="enterprise-value-card">
<div className="enterprise-value-card__icon">🔌</div>
<h3 className="enterprise-value-card__title">Strong Integration</h3>
<p className="enterprise-value-card__description">
ClawHub CLI compatible; standard REST API; OAuth2 enterprise SSO integration
</p>
</div>
<div className="enterprise-value-card">
<div className="enterprise-value-card__eyebrow">Collaboration</div>
<h3 className="enterprise-value-card__title">Namespaces built for real teams</h3>
<div className="enterprise-value-card__description">{`Organize skills by owner, domain, or department and pair that structure with Owner, Admin, and Member roles that match enterprise workflows.`}</div>
</div>
<div className="col col--3">
<div className="enterprise-value-card">
<div className="enterprise-value-card__icon">📊</div>
<h3 className="enterprise-value-card__title">Full Observability</h3>
<p className="enterprise-value-card__description">
Complete audit logs; Prometheus metrics; operation tracking and traceability
</p>
</div>
<div className="enterprise-value-card">
<div className="enterprise-value-card__eyebrow">Governance</div>
<h3 className="enterprise-value-card__title">Review, audit, and promote with confidence</h3>
<div className="enterprise-value-card__description">{`Promotion review flows, audit logs, and optional security scanning make it easier to move skills from local innovation to governed organizational reuse.`}</div>
</div>
</div>
---
## Core Features
## Built For Mature Delivery
<div style={{ textAlign: 'center', marginTop: '40px' }}>
<div className="story-grid">
<div className="story-card">
<h3>Less AI-looking chrome, more product-grade clarity</h3>
<div className="story-card__body">{`The public docs experience is tuned for cleaner typography, tighter spacing, stronger visual hierarchy, and fewer generic gradients so the brand feels deliberate rather than over-generated.`}</div>
</div>
<div className="story-card">
<h3>Designed around modern system thinking</h3>
<div className="story-card__body">{`The refreshed layout borrows the discipline of modern component systems such as shadcn/ui and utility-first design tokens, even though this site remains a Docusaurus documentation experience.`}</div>
</div>
<div className="story-card">
<h3>International first, localized by default switch</h3>
<div className="story-card__body">{`English now leads as the default locale for broader reach, while the Chinese translation remains one click away through the built-in locale switcher.`}</div>
</div>
</div>
---
## Current Coverage
<div className="coverage-panel">
<div className="feature-tags">
<span className="feature-tag">Self-hosted</span>
<span className="feature-tag">Version Control</span>
<span className="feature-tag">Full-text Search</span>
<span className="feature-tag">Namespaces</span>
<span className="feature-tag">Review Workflow</span>
<span className="feature-tag">Semantic Versioning</span>
<span className="feature-tag">Multi-dimensional Filtering</span>
<span className="feature-tag">RBAC Permissions</span>
<span className="feature-tag">Audit Logs</span>
<span className="feature-tag">Security Scanning</span>
<span className="feature-tag">CLI Compatibility</span>
</div>
</div>
@ -83,13 +127,24 @@ description: Enterprise-grade AI Skill Registry - Secure, controllable skill pub
## Quick Start
<div style={{ textAlign: 'center', marginTop: '40px' }}>
<div className="quick-start-panel">
<div className="quick-start-code">
<code>$ curl -fsSL https://raw.githubusercontent.com/iflytek/skillhub/main/scripts/runtime.sh | sh -s -- up</code>
</div>
<p style={{ marginTop: '16px', color: 'var(--ifm-font-color-secondary)' }}>
Visit <a href="http://localhost:3000">http://localhost:3000</a> to get started
</p>
<div className="quick-start-hints">
<div className="quick-start-hint">
<span className="quick-start-hint__label">Default Admin</span>
<strong>admin / ChangeMe!2026</strong>
</div>
<div className="quick-start-hint">
<span className="quick-start-hint__label">Local Web UI</span>
<strong>http://localhost:3000</strong>
</div>
<div className="quick-start-hint">
<span className="quick-start-hint__label">Registry API</span>
<strong>http://localhost:8080</strong>
</div>
</div>
</div>
---
@ -97,5 +152,6 @@ description: Enterprise-grade AI Skill Registry - Secure, controllable skill pub
## Next Steps
- [Quick Start](./getting-started/quick-start) - Deploy SkillHub with one command
- [Overview](./getting-started/overview) - Learn more about product features
- [Deployment Guide](./administration/deployment/single-machine) - Production deployment
- [Overview](./getting-started/overview) - Learn how the platform is positioned
- [Publish Workflow](./user-guide/publishing/publish) - Publish your first skill package
- [Single Machine Deployment](./administration/deployment/single-machine) - Run the production-ready stack

521
document/i18n/zh-CN/code.json Normal file
View file

@ -0,0 +1,521 @@
{
"homepage.title": {
"message": "Astron SkillHub"
},
"homepage.description": {
"message": "面向企业治理与私有化部署的开源 Agent 技能注册中心，覆盖发布、发现与团队协作。"
},
"homepage.hero.badge": {
"message": "可私有化部署的 Agent 技能注册中心"
},
"homepage.hero.title": {
"message": "以可治理的方式交付可复用 AI 技能。"
},
"homepage.hero.tagline": {
"message": "Astron SkillHub 为团队提供专业的内部技能注册中心，用于发布、发现、版本管理和运营可复用的 Agent 技能包。"
},
"homepage.hero.cta.primary": {
"message": "立即部署"
},
"homepage.hero.cta.secondary": {
"message": "了解架构"
},
"homepage.hero.proof.versioning": {
"message": "语义化版本"
},
"homepage.hero.proof.namespace": {
"message": "命名空间治理"
},
"homepage.hero.proof.scanner": {
"message": "安全扫描"
},
"homepage.hero.proof.cli": {
"message": "CLI 兼容"
},
"homepage.hero.membership": {
"message": "AAIF 准会员"
},
"homepage.hero.membership.ariaLabel": {
"message": "Agentic AI Foundation 官网（在新标签页中打开）"
},
"homepage.hero.membership.logoAlt": {
"message": "Agentic AI Foundation（AAIF）"
},
"homepage.hero.stat.one": {
"message": "统一承载团队协作、治理与运行文档"
},
"homepage.hero.stat.three": {
"message": "三大核心流程：发布、发现、审核"
},
"homepage.hero.stat.alwaysOn": {
"message": "支持全天候内部技能运营"
},
"homepage.why.title": {
"message": "为什么团队选择 SkillHub"
},
"homepage.why.publishing.eyebrow": {
"message": "发布"
},
"homepage.why.publishing.title": {
"message": "有序、可追溯的版本化交付"
},
"homepage.why.publishing.description": {
"message": "语义化版本、渠道标签和不可变包历史，让平台团队与日常贡献者都能稳定、可预期地发布技能。"
},
"homepage.why.publishing.tag1": {
"message": "语义化版本"
},
"homepage.why.publishing.tag2": {
"message": "beta / stable / latest 标签"
},
"homepage.why.publishing.tag3": {
"message": "便于下载与回滚"
},
"homepage.why.discovery.eyebrow": {
"message": "发现"
},
"homepage.why.discovery.title": {
"message": "遵循权限边界的搜索"
},
"homepage.why.discovery.description": {
"message": "全文搜索与结构化筛选帮助用户快速找到合适的技能，同时遵守命名空间可见性和治理边界。"
},
"homepage.why.collaboration.eyebrow": {
"message": "协作"
},
"homepage.why.collaboration.title": {
"message": "为真实团队设计的命名空间"
},
"homepage.why.collaboration.description": {
"message": "按负责人、领域或部门组织技能，并通过所有者、管理员和成员角色匹配企业协作流程。"
},
"homepage.why.governance.eyebrow": {
"message": "治理"
},
"homepage.why.governance.title": {
"message": "可靠地审核、审计与晋级"
},
"homepage.why.governance.description": {
"message": "晋级审核、审计日志和可选安全扫描，帮助技能从局部创新走向组织级受控复用。"
},
"homepage.mature.title": {
"message": "面向成熟交付体系"
},
"homepage.mature.card1.title": {
"message": "更克制的界面，更清晰的产品体验"
},
"homepage.mature.card1.body": {
"message": "官网文档采用更清晰的字体、更紧凑的间距和更明确的视觉层级，让品牌表达专业而克制。"
},
"homepage.mature.card2.title": {
"message": "以现代设计系统思维构建"
},
"homepage.mature.card2.body": {
"message": "新版布局借鉴现代组件系统和实用优先设计令牌的规范，同时保留 Docusaurus 文档体验。"
},
"homepage.mature.card3.title": {
"message": "默认国际化，中文随时切换"
},
"homepage.mature.card3.body": {
"message": "英文作为默认语言服务更广泛的用户，中文内容可通过内置语言切换器一键访问。"
},
"homepage.coverage.title": {
"message": "当前能力覆盖"
},
"homepage.coverage.tag1": {
"message": "私有化部署"
},
"homepage.coverage.tag2": {
"message": "版本控制"
},
"homepage.coverage.tag3": {
"message": "全文搜索"
},
"homepage.coverage.tag4": {
"message": "命名空间"
},
"homepage.coverage.tag5": {
"message": "审核流程"
},
"homepage.coverage.tag6": {
"message": "语义化版本"
},
"homepage.coverage.tag7": {
"message": "RBAC 权限"
},
"homepage.coverage.tag8": {
"message": "审计日志"
},
"homepage.coverage.tag9": {
"message": "安全扫描"
},
"homepage.coverage.tag10": {
"message": "CLI 兼容"
},
"homepage.quickstart.title": {
"message": "快速开始"
},
"homepage.quickstart.adminLabel": {
"message": "默认管理员"
},
"homepage.quickstart.uiLabel": {
"message": "本地 Web 界面"
},
"homepage.quickstart.apiLabel": {
"message": "注册中心 API"
},
"homepage.next.title": {
"message": "下一步"
},
"homepage.next.link1": {
"message": "快速开始"
},
"homepage.next.desc1": {
"message": "使用一条命令部署 SkillHub"
},
"homepage.next.link2": {
"message": "产品概览"
},
"homepage.next.desc2": {
"message": "了解平台定位与能力边界"
},
"homepage.next.link3": {
"message": "发布流程"
},
"homepage.next.desc3": {
"message": "发布你的第一个技能包"
},
"homepage.next.link4": {
"message": "单机部署"
},
"homepage.next.desc4": {
"message": "运行可用于生产的完整服务栈"
},
"theme.ErrorPageContent.title": {
"message": "页面已崩溃。",
"description": "The title of the fallback page when the page crashed"
},
"theme.BackToTopButton.buttonAriaLabel": {
"message": "回到顶部",
"description": "The ARIA label for the back to top button"
},
"theme.blog.archive.title": {
"message": "历史博文",
"description": "The page & hero title of the blog archive page"
},
"theme.blog.archive.description": {
"message": "历史博文",
"description": "The page & hero description of the blog archive page"
},
"theme.blog.paginator.navAriaLabel": {
"message": "博文列表分页导航",
"description": "The ARIA label for the blog pagination"
},
"theme.blog.paginator.newerEntries": {
"message": "较新的博文",
"description": "The label used to navigate to the newer blog posts page (previous page)"
},
"theme.blog.paginator.olderEntries": {
"message": "较旧的博文",
"description": "The label used to navigate to the older blog posts page (next page)"
},
"theme.blog.post.paginator.navAriaLabel": {
"message": "博文分页导航",
"description": "The ARIA label for the blog posts pagination"
},
"theme.blog.post.paginator.newerPost": {
"message": "较新一篇",
"description": "The blog post button label to navigate to the newer/previous post"
},
"theme.blog.post.paginator.olderPost": {
"message": "较旧一篇",
"description": "The blog post button label to navigate to the older/next post"
},
"theme.tags.tagsPageLink": {
"message": "查看所有标签",
"description": "The label of the link targeting the tag list page"
},
"theme.colorToggle.ariaLabel.mode.system": {
"message": "system mode",
"description": "The name for the system color mode"
},
"theme.colorToggle.ariaLabel.mode.light": {
"message": "浅色模式",
"description": "The name for the light color mode"
},
"theme.colorToggle.ariaLabel.mode.dark": {
"message": "暗黑模式",
"description": "The name for the dark color mode"
},
"theme.colorToggle.ariaLabel": {
"message": "切换浅色/暗黑模式（当前为{mode}）",
"description": "The ARIA label for the color mode toggle"
},
"theme.docs.breadcrumbs.navAriaLabel": {
"message": "页面路径",
"description": "The ARIA label for the breadcrumbs"
},
"theme.docs.paginator.navAriaLabel": {
"message": "文件选项卡",
"description": "The ARIA label for the docs pagination"
},
"theme.docs.paginator.previous": {
"message": "上一页",
"description": "The label used to navigate to the previous doc"
},
"theme.docs.paginator.next": {
"message": "下一页",
"description": "The label used to navigate to the next doc"
},
"theme.docs.tagDocListPageTitle.nDocsTagged": {
"message": "{count} 篇文档带有标签",
"description": "Pluralized label for \"{count} docs tagged\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)"
},
"theme.docs.tagDocListPageTitle": {
"message": "{nDocsTagged}「{tagName}」",
"description": "The title of the page for a docs tag"
},
"theme.docs.versionBadge.label": {
"message": "版本：{versionLabel}"
},
"theme.docs.versions.unreleasedVersionLabel": {
"message": "此为 {siteTitle} {versionLabel} 版尚未发行的文档。",
"description": "The label used to tell the user that he's browsing an unreleased doc version"
},
"theme.docs.versions.unmaintainedVersionLabel": {
"message": "此为 {siteTitle} {versionLabel} 版的文档，现已不再积极维护。",
"description": "The label used to tell the user that he's browsing an unmaintained doc version"
},
"theme.docs.versions.latestVersionSuggestionLabel": {
"message": "最新的文档请参阅 {latestVersionLink} ({versionLabel})。",
"description": "The label used to tell the user to check the latest version"
},
"theme.docs.versions.latestVersionLinkLabel": {
"message": "最新版本",
"description": "The label used for the latest version suggestion link label"
},
"theme.common.editThisPage": {
"message": "编辑此页",
"description": "The link label to edit the current page"
},
"theme.common.headingLinkTitle": {
"message": "{heading}的直接链接",
"description": "Title for link to heading"
},
"theme.lastUpdated.atDate": {
"message": "于 {date} ",
"description": "The words used to describe on which date a page has been last updated"
},
"theme.lastUpdated.byUser": {
"message": "由 {user} ",
"description": "The words used to describe by who the page has been last updated"
},
"theme.lastUpdated.lastUpdatedAtBy": {
"message": "最后{byUser}{atDate}更新",
"description": "The sentence used to display when a page has been last updated, and by who"
},
"theme.NotFound.title": {
"message": "找不到页面",
"description": "The title of the 404 page"
},
"theme.navbar.mobileVersionsDropdown.label": {
"message": "选择版本",
"description": "The label for the navbar versions dropdown on mobile view"
},
"theme.tags.tagsListLabel": {
"message": "标签：",
"description": "The label alongside a tag list"
},
"theme.AnnouncementBar.closeButtonAriaLabel": {
"message": "关闭",
"description": "The ARIA label for close button of announcement bar"
},
"theme.admonition.caution": {
"message": "警告",
"description": "The default label used for the Caution admonition (:::caution)"
},
"theme.admonition.danger": {
"message": "危险",
"description": "The default label used for the Danger admonition (:::danger)"
},
"theme.admonition.info": {
"message": "信息",
"description": "The default label used for the Info admonition (:::info)"
},
"theme.admonition.note": {
"message": "备注",
"description": "The default label used for the Note admonition (:::note)"
},
"theme.admonition.tip": {
"message": "提示",
"description": "The default label used for the Tip admonition (:::tip)"
},
"theme.admonition.warning": {
"message": "注意",
"description": "The default label used for the Warning admonition (:::warning)"
},
"theme.blog.sidebar.navAriaLabel": {
"message": "最近博文导航",
"description": "The ARIA label for recent posts in the blog sidebar"
},
"theme.DocSidebarItem.expandCategoryAriaLabel": {
"message": "展开侧边栏分类 '{label}'",
"description": "The ARIA label to expand the sidebar category"
},
"theme.DocSidebarItem.collapseCategoryAriaLabel": {
"message": "折叠侧边栏分类 '{label}'",
"description": "The ARIA label to collapse the sidebar category"
},
"theme.IconExternalLink.ariaLabel": {
"message": "(opens in new tab)",
"description": "The ARIA label for the external link icon"
},
"theme.NotFound.p1": {
"message": "我们找不到您要找的页面。",
"description": "The first paragraph of the 404 page"
},
"theme.NotFound.p2": {
"message": "请联系原始链接来源网站的所有者，并告知他们链接已损坏。",
"description": "The 2nd paragraph of the 404 page"
},
"theme.NavBar.navAriaLabel": {
"message": "主导航",
"description": "The ARIA label for the main navigation"
},
"theme.TOCCollapsible.toggleButtonLabel": {
"message": "本页总览",
"description": "The label used by the button on the collapsible TOC component"
},
"theme.navbar.mobileLanguageDropdown.label": {
"message": "选择语言",
"description": "The label for the mobile language switcher dropdown"
},
"theme.blog.post.readMore": {
"message": "阅读更多",
"description": "The label used in blog post item excerpts to link to full blog posts"
},
"theme.blog.post.readMoreLabel": {
"message": "阅读 {title} 的全文",
"description": "The ARIA label for the link to full blog posts from excerpts"
},
"theme.blog.post.readingTime.plurals": {
"message": "阅读需 {readingTime} 分钟",
"description": "Pluralized label for \"{readingTime} min read\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)"
},
"theme.CodeBlock.copy": {
"message": "复制",
"description": "The copy button label on code blocks"
},
"theme.CodeBlock.copied": {
"message": "复制成功",
"description": "The copied button label on code blocks"
},
"theme.CodeBlock.copyButtonAriaLabel": {
"message": "复制代码到剪贴板",
"description": "The ARIA label for copy code blocks button"
},
"theme.CodeBlock.wordWrapToggle": {
"message": "切换自动换行",
"description": "The title attribute for toggle word wrapping button of code block lines"
},
"theme.docs.breadcrumbs.home": {
"message": "主页面",
"description": "The ARIA label for the home page in the breadcrumbs"
},
"theme.docs.sidebar.collapseButtonTitle": {
"message": "收起侧边栏",
"description": "The title attribute for collapse button of doc sidebar"
},
"theme.docs.sidebar.collapseButtonAriaLabel": {
"message": "收起侧边栏",
"description": "The title attribute for collapse button of doc sidebar"
},
"theme.docs.sidebar.navAriaLabel": {
"message": "文档侧边栏",
"description": "The ARIA label for the sidebar navigation"
},
"theme.docs.sidebar.closeSidebarButtonAriaLabel": {
"message": "关闭导航栏",
"description": "The ARIA label for close button of mobile sidebar"
},
"theme.navbar.mobileDropdown.collapseButton.expandAriaLabel": {
"message": "Expand the dropdown",
"description": "The ARIA label of the button to expand the mobile dropdown navbar item"
},
"theme.navbar.mobileDropdown.collapseButton.collapseAriaLabel": {
"message": "Collapse the dropdown",
"description": "The ARIA label of the button to collapse the mobile dropdown navbar item"
},
"theme.docs.sidebar.toggleSidebarButtonAriaLabel": {
"message": "切换导航栏",
"description": "The ARIA label for hamburger menu button of mobile navigation"
},
"theme.navbar.mobileSidebarSecondaryMenu.backButtonLabel": {
"message": "← 回到主菜单",
"description": "The label of the back button to return to main menu, inside the mobile navbar sidebar secondary menu (notably used to display the docs sidebar)"
},
"theme.docs.sidebar.expandButtonTitle": {
"message": "展开侧边栏",
"description": "The ARIA label and title attribute for expand button of doc sidebar"
},
"theme.docs.sidebar.expandButtonAriaLabel": {
"message": "展开侧边栏",
"description": "The ARIA label and title attribute for expand button of doc sidebar"
},
"theme.blog.post.plurals": {
"message": "{count} 篇博文",
"description": "Pluralized label for \"{count} posts\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)"
},
"theme.blog.tagTitle": {
"message": "{nPosts} 含有标签「{tagName}」",
"description": "The title of the page for a blog tag"
},
"theme.blog.author.pageTitle": {
"message": "{authorName} - {nPosts}",
"description": "The title of the page for a blog author"
},
"theme.blog.authorsList.pageTitle": {
"message": "作者",
"description": "The title of the authors page"
},
"theme.blog.authorsList.viewAll": {
"message": "查看所有作者",
"description": "The label of the link targeting the blog authors page"
},
"theme.blog.author.noPosts": {
"message": "该作者尚未撰写任何文章。",
"description": "The text for authors with 0 blog post"
},
"theme.contentVisibility.unlistedBanner.title": {
"message": "未列出页",
"description": "The unlisted content banner title"
},
"theme.contentVisibility.unlistedBanner.message": {
"message": "此页面未列出。搜索引擎不会对其索引，只有拥有直接链接的用户才能访问。",
"description": "The unlisted content banner message"
},
"theme.contentVisibility.draftBanner.title": {
"message": "草稿页",
"description": "The draft content banner title"
},
"theme.contentVisibility.draftBanner.message": {
"message": "此页面是草稿，仅在开发环境中可见，不会包含在正式版本中。",
"description": "The draft content banner message"
},
"theme.docs.DocCard.categoryDescription.plurals": {
"message": "{count} 个项目",
"description": "The default description for a category card in the generated index about how many items this category includes"
},
"theme.ErrorPageContent.tryAgain": {
"message": "重试",
"description": "The label of the button to try again rendering when the React error boundary captures an error"
},
"theme.common.skipToMainContent": {
"message": "跳到主要内容",
"description": "The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation"
},
"theme.tags.tagsPageTitle": {
"message": "标签",
"description": "The title of the tag list page"
}
}

14
document/i18n/zh-CN/docusaurus-plugin-content-blog/options.json Normal file
View file

@ -0,0 +1,14 @@
{
"title": {
"message": "Blog",
"description": "The title for the blog used in SEO"
},
"description": {
"message": "Blog",
"description": "The description for the blog used in SEO"
},
"sidebar.title": {
"message": "Recent posts",
"description": "The label for the left sidebar"
}
}

62
document/i18n/zh-CN/docusaurus-plugin-content-docs/current.json Normal file
View file

@ -0,0 +1,62 @@
{
"version.label": {
"message": "Next",
"description": "The label for version current"
},
"sidebar.docsSidebar.category.Getting Started": {
"message": "快速入门",
"description": "The label for category 'Getting Started' in sidebar 'docsSidebar'"
},
"sidebar.docsSidebar.category.Administration Guide": {
"message": "管理员指南",
"description": "The label for category 'Administration Guide' in sidebar 'docsSidebar'"
},
"sidebar.docsSidebar.category.Deployment Guide": {
"message": "部署指南",
"description": "The label for category 'Deployment Guide' in sidebar 'docsSidebar'"
},
"sidebar.docsSidebar.category.Security & Compliance": {
"message": "安全与合规",
"description": "The label for category 'Security & Compliance' in sidebar 'docsSidebar'"
},
"sidebar.docsSidebar.category.Governance & Operations": {
"message": "治理与运营",
"description": "The label for category 'Governance & Operations' in sidebar 'docsSidebar'"
},
"sidebar.docsSidebar.category.User Guide": {
"message": "用户指南",
"description": "The label for category 'User Guide' in sidebar 'docsSidebar'"
},
"sidebar.docsSidebar.category.Publishing Skills": {
"message": "发布技能",
"description": "The label for category 'Publishing Skills' in sidebar 'docsSidebar'"
},
"sidebar.docsSidebar.category.Discovery & Usage": {
"message": "发现与使用",
"description": "The label for category 'Discovery & Usage' in sidebar 'docsSidebar'"
},
"sidebar.docsSidebar.category.Collaboration": {
"message": "协作",
"description": "The label for category 'Collaboration' in sidebar 'docsSidebar'"
},
"sidebar.docsSidebar.category.Developer Reference": {
"message": "开发者参考",
"description": "The label for category 'Developer Reference' in sidebar 'docsSidebar'"
},
"sidebar.docsSidebar.category.API Reference": {
"message": "API 参考",
"description": "The label for category 'API Reference' in sidebar 'docsSidebar'"
},
"sidebar.docsSidebar.category.Architecture": {
"message": "架构设计",
"description": "The label for category 'Architecture' in sidebar 'docsSidebar'"
},
"sidebar.docsSidebar.category.Extensions & Integrations": {
"message": "扩展与集成",
"description": "The label for category 'Extensions & Integrations' in sidebar 'docsSidebar'"
},
"sidebar.docsSidebar.category.Reference": {
"message": "参考资料",
"description": "The label for category 'Reference' in sidebar 'docsSidebar'"
}
}

8
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/_category_.json Normal file
View file

@ -0,0 +1,8 @@
{
"label": "快速入门",
"position": 1,
"link": {
"type": "generated-index",
"description": "快速了解并开始使用 SkillHub"
}
}

70
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/overview.md Normal file
View file

@ -0,0 +1,70 @@
---
title: 产品概述
sidebar_position: 1
description: SkillHub 产品概述和核心特性介绍
---
# 产品概述
SkillHub 是企业级 AI 技能注册平台，支持技能发布、发现与管理，采用自托管架构保障数据安全。
## 核心特性
### 发布管理
- 版本控制与语义化版本（Semantic Versioning）
- 自定义标签（如 `beta`/`stable`）
- `latest` 标签自动跟随最新发布版本
### 发现机制
- 全文搜索
- 多维度筛选（命名空间、下载量、评分）
- 可见性控制（公开/命名空间内/私有）
### 组织架构
- 命名空间隔离
- 基于角色的访问控制（RBAC）
- 团队与全局双层空间
### 治理体系
- 双层审核流程
- 审计日志
- 权限分离
### 存储与部署
- 支持 S3/MinIO/本地存储
- Docker/Kubernetes 部署
- 企业级可观测性
## 技术栈
### 后端
- **Java 21** - 运行时
- **Spring Boot 3.2.3** - 应用框架
- **PostgreSQL 16.x** - 主数据库 + 全文搜索
- **Redis 7.x** - 缓存与会话存储
### 前端
- **React 19** - UI 框架
- **TypeScript** - 类型安全
- **Vite** - 构建工具
- **Tailwind CSS** - 样式框架
### 部署
- **Docker Compose** - 单机部署
- **Kubernetes** - 生产环境编排
## 核心概念
### 命名空间
技能隔离边界，支持 `@global`（全局）和 `@team-*`（团队）前缀。
### 坐标系统
技能标识格式为 `@{namespace_slug}/{skill_slug}`，支持语义化版本。
### 兼容性
提供 REST API 和 ClawHub 兼容层，支持现有工具集成。
## 下一步
- [快速开始](./quick-start) - 一键启动体验
- [典型应用场景](./use-cases) - 了解如何在企业中应用

85
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/quick-start.md Normal file
View file

@ -0,0 +1,85 @@
---
title: 快速开始
sidebar_position: 2
description: 一键启动 SkillHub 开发环境
---
# 快速开始
## 一键启动
使用以下命令一键启动完整的 SkillHub 环境：
```bash
curl -fsSL https://raw.githubusercontent.com/iflytek/skillhub/main/scripts/runtime.sh | sh -s -- up
```
或者克隆仓库后手动启动：
```bash
git clone https://github.com/iflytek/skillhub.git
cd skillhub
make dev-all
```
## 默认账号
两种启动方式都会默认创建一个 bootstrap 管理员账号：
- 用户名：`admin`
- 密码：`ChangeMe!2026`
### `curl` 一键部署
| 服务 | 地址 |
|------|------|
| Web UI | http://localhost |
| Backend API | http://localhost:8080 |
使用上述默认账号密码登录即可。**生产环境请务必修改密码。**
### `make dev-all` 本地开发
| 服务 | 地址 |
|------|------|
| Web UI | http://localhost:3000 |
| Backend API | http://localhost:8080 |
| MinIO Console | http://localhost:9001 |
除了上述 bootstrap 管理员，本地开发还预置两个模拟用户（无需密码）：
| 用户 | 角色 | 说明 |
|------|------|------|
| `local-user` | 普通用户 | 可发布技能、管理命名空间 |
| `local-admin` | 超级管理员 | 拥有所有权限，包括审核和用户管理 |
使用 `X-Mock-User-Id` 请求头切换模拟用户。
如需关闭 bootstrap 管理员，启动前设置 `BOOTSTRAP_ADMIN_ENABLED=false`。
## 常用命令
```bash
# 启动完整开发环境
make dev-all
# 停止所有服务
make dev-all-down
# 重置并重新启动
make dev-all-reset
# 仅启动后端
make dev
# 仅启动前端
make dev-web
# 查看所有可用命令
make help
```
## 下一步
- [产品概述](./overview) - 深入了解产品特性
- [典型应用场景](./use-cases) - 探索企业应用场景
- [单机部署](../administration/deployment/single-machine) - 生产环境部署指南

72
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/use-cases.md Normal file
View file

@ -0,0 +1,72 @@
---
title: 典型应用场景
sidebar_position: 3
description: SkillHub 在企业中的典型应用场景
---
# 典型应用场景
## 企业内部技能共享
**场景描述**：企业内部多个团队开发 AI 技能，需要一个集中的平台进行共享和复用。
**解决方案**：
- 各团队创建自己的命名空间
- 技能在团队内先审核发布
- 优秀技能可申请提升到全局空间
- 所有操作有完整审计记录
**价值**：
- 避免重复开发
- 促进最佳实践传播
- 保障质量可控
## AI 技能治理与合规
**场景描述**：金融、政务等行业对 AI 应用有严格的合规要求，需要完整的审核和审计机制。
**解决方案**：
- 双层审核流程（团队审核 + 平台审核）
- 细粒度 RBAC 权限控制
- 完整的操作审计日志
- 技能版本可追溯、可撤回
**价值**：
- 满足合规要求
- 风险可控
- 责任可追溯
## 多团队协作开发
**场景描述**：大型组织中多个团队协作开发，需要清晰的权限边界和协作机制。
**解决方案**：
- 命名空间隔离，团队自治
- 命名空间成员角色管理
- 技能可见性控制（公开/命名空间内/私有）
- 团队技能可申请提升到全局
**价值**：
- 权责清晰
- 协作高效
- 安全可控
## CLI 工具集成
**场景描述**：已有使用 ClawHub CLI 的工作流，希望无缝迁移到 SkillHub。
**解决方案**：
- 提供 ClawHub CLI 协议兼容层
- 通过 `/.well-known/clawhub.json` 自动发现
- 现有 CLI 工具无需修改即可使用
- 同时提供 SkillHub 自有 CLI 增强功能
**价值**：
- 保护现有投资
- 迁移成本低
- 渐进式升级
## 下一步
- [单机部署](../administration/deployment/single-machine) - 开始部署
- [命名空间管理](../administration/governance/namespaces) - 了解组织治理

8
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/_category_.json Normal file
View file

@ -0,0 +1,8 @@
{
"label": "管理员指南",
"position": 2,
"link": {
"type": "generated-index",
"description": "部署、配置和管理 SkillHub"
}
}

4
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/_category_.json Normal file
View file

@ -0,0 +1,4 @@
{
"label": "部署指南",
"position": 1
}

69
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/configuration.md Normal file
View file

@ -0,0 +1,69 @@
---
title: 配置说明
sidebar_position: 3
description: SkillHub 配置项详细说明
---
# 配置说明
## 环境变量
SkillHub 通过环境变量进行配置，主要配置项如下：
### 基础配置
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `SKILLHUB_PUBLIC_BASE_URL` | 公网访问地址 | - |
| `SKILLHUB_VERSION` | 镜像版本 | `edge` |
### 数据库配置
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `POSTGRES_HOST` | PostgreSQL 主机 | `postgres` |
| `POSTGRES_PORT` | PostgreSQL 端口 | `5432` |
| `POSTGRES_DB` | 数据库名 | `skillhub` |
| `POSTGRES_USER` | 数据库用户 | `skillhub` |
| `POSTGRES_PASSWORD` | 数据库密码 | - |
### Redis 配置
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `REDIS_HOST` | Redis 主机 | `redis` |
| `REDIS_PORT` | Redis 端口 | `6379` |
| `REDIS_PASSWORD` | Redis 密码 | - |
### 存储配置
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `SKILLHUB_STORAGE_PROVIDER` | 存储提供方 | `local` |
| `SKILLHUB_STORAGE_S3_ENDPOINT` | S3 端点 | - |
| `SKILLHUB_STORAGE_S3_BUCKET` | S3 桶名 | - |
| `SKILLHUB_STORAGE_S3_ACCESS_KEY` | S3 Access Key | - |
| `SKILLHUB_STORAGE_S3_SECRET_KEY` | S3 Secret Key | - |
### OAuth 配置
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `OAUTH2_GITHUB_CLIENT_ID` | GitHub OAuth Client ID | - |
| `OAUTH2_GITHUB_CLIENT_SECRET` | GitHub OAuth Client Secret | - |
### 首登管理员配置
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `BOOTSTRAP_ADMIN_ENABLED` | 是否启用首登管理员 | `true` |
| `BOOTSTRAP_ADMIN_USERNAME` | 首登管理员用户名 | `admin` |
| `BOOTSTRAP_ADMIN_PASSWORD` | 首登管理员密码 | `ChangeMe!2026` |
## 配置文件
Spring Boot 配置文件位于 `server/skillhub-app/src/main/resources/`。
## 下一步
- [认证配置](../security/authentication) - 配置身份认证

54
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/kubernetes.md Normal file
View file

@ -0,0 +1,54 @@
---
title: Kubernetes 部署
sidebar_position: 2
description: 在 Kubernetes 集群中部署 SkillHub
---
# Kubernetes 部署
本文介绍如何在 Kubernetes 集群中部署 SkillHub。
## 前置要求
- Kubernetes 1.24+
- kubectl 配置完成
- Helm 3.0+（可选）
- 可用的持久化存储类
## 部署清单
项目提供了 Kubernetes 部署清单：
```bash
cd deploy/k8s
# 1. 创建命名空间
kubectl create namespace skillhub
# 2. 配置 Secret
cp secret.yaml.example secret.yaml
# 编辑 secret.yaml 填入真实凭证
# 3. 应用配置
kubectl apply -f configmap.yaml
kubectl apply -f secret.yaml
# 4. 部署服务
kubectl apply -f backend-deployment.yaml
kubectl apply -f frontend-deployment.yaml
kubectl apply -f services.yaml
# 5. 配置 Ingress
kubectl apply -f ingress.yaml
```
## 高可用配置
- 后端和前端建议至少部署 2 个副本
- PostgreSQL 使用主从复制
- Redis 使用 Sentinel 或 Cluster 模式
- 存储使用高可用对象存储（如 MinIO 集群或云厂商 OSS）
## 下一步
- [配置说明](./configuration) - 详细配置项说明

65
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/single-machine.md Normal file
View file

@ -0,0 +1,65 @@
---
title: 单机部署
sidebar_position: 1
description: 使用 Docker Compose 单机部署 SkillHub
---
# 单机部署
本文介绍如何使用 Docker Compose 在单台服务器上部署 SkillHub。
## 前置要求
- Docker Engine 20.10+
- Docker Compose Plugin 2.0+
- 至少 4GB 可用内存
- 至少 20GB 可用磁盘空间
## 快速部署
```bash
# 1. 克隆仓库
git clone https://github.com/iflytek/skillhub.git
cd skillhub
# 2. 复制环境变量模板
cp .env.release.example .env.release
# 3. 编辑配置
# 修改 .env.release 中的配置项，特别是密码和公网地址
# 4. 验证配置
make validate-release-config
# 5. 启动服务
docker compose --env-file .env.release -f compose.release.yml up -d
```
## 配置说明
详见 [配置说明](./configuration) 文档。
## 验证部署
```bash
# 检查容器状态
docker compose --env-file .env.release -f compose.release.yml ps
# 检查后端健康状态
curl -i http://127.0.0.1:8080/actuator/health
# 访问 Web UI
# 浏览器打开 http://localhost（或配置的公网地址）
```
## 首登配置
1. 使用 `BOOTSTRAP_ADMIN_USERNAME` 和 `BOOTSTRAP_ADMIN_PASSWORD` 登录（默认 `admin` / `ChangeMe!2026`）
2. 立即修改管理员密码
3. 配置企业 SSO（可选）
4. 创建团队命名空间
## 下一步
- [配置说明](./configuration) - 详细配置项说明
- [Kubernetes 部署](./kubernetes) - 高可用部署

4
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/_category_.json Normal file
View file

@ -0,0 +1,4 @@
{
"label": "治理与运营",
"position": 3
}

56
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/namespaces.md Normal file
View file

@ -0,0 +1,56 @@
---
title: 命名空间管理
sidebar_position: 1
description: 命名空间创建与管理
---
# 命名空间管理
命名空间是 SkillHub 中技能的隔离边界和协作单元。
## 命名空间类型
| 类型 | 前缀 | 说明 |
|------|------|------|
| 全局 | `@global` | 平台级公共空间，由平台管理员管理 |
| 团队 | `@team-*` | 团队/部门空间，由团队管理员管理 |
## 创建命名空间
1. 登录后进入"我的命名空间"
2. 点击"创建命名空间"
3. 填写信息：
- 标识（slug）：URL 友好名称
- 显示名：展示名称
- 描述：空间用途说明
4. 提交创建
## 命名空间成员管理
### 添加成员
1. 进入命名空间设置
2. 进入"成员管理"
3. 输入用户名搜索
4. 选择角色（OWNER/ADMIN/MEMBER）
5. 确认添加
### 角色变更
命名空间 OWNER 或 ADMIN 可变更成员角色。
### 移除成员
命名空间 OWNER 或 ADMIN 可移除成员。
## 命名空间状态
| 状态 | 说明 |
|------|------|
| `ACTIVE` | 正常使用 |
| `FROZEN` | 冻结，只读不可发布 |
| `ARCHIVED` | 归档，对外不可见 |
## 下一步
- [审核流程](./review-workflow) - 了解技能审核

44
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/review-workflow.md Normal file
View file

@ -0,0 +1,44 @@
---
title: 审核流程
sidebar_position: 2
description: 技能发布审核流程配置
---
# 审核流程
SkillHub 采用双层审核机制，保障技能质量。
## 审核流程
### 团队空间技能
1. 团队成员提交发布
2. 创建审核任务（PENDING）
3. 团队 ADMIN 或 OWNER 审核
- 通过 → 技能发布（PUBLISHED）
- 拒绝 → 返回修改（REJECTED）
### 全局空间技能
1. 提交发布
2. 平台 SKILL_ADMIN 或 SUPER_ADMIN 审核
3. 审核通过后发布
## 团队技能提升到全局
1. 团队技能已发布
2. 团队 ADMIN 或 OWNER 申请"提升到全局"
3. 平台管理员审核
4. 审核通过后在全局空间创建新技能
## 审核权限
| 审核类型 | 所需角色 |
|---------|---------|
| 团队空间技能审核 | 命名空间 ADMIN/OWNER |
| 全局空间技能审核 | SKILL_ADMIN/SUPER_ADMIN |
| 提升申请审核 | SKILL_ADMIN/SUPER_ADMIN |
## 下一步
- [用户管理](./user-management) - 管理平台用户

61
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/user-management.md Normal file
View file

@ -0,0 +1,61 @@
---
title: 用户管理
sidebar_position: 3
description: 平台用户管理
---
# 用户管理
## 用户状态
| 状态 | 实际逻辑 |
|------|----------|
| `ACTIVE` | 可正常登录和使用系统。OAuth 首次自动准入、local 注册成功后都会进入该状态。 |
| `PENDING` | 账号已建但不可登录。OAuth 在“需要审批”策略下会创建 `PENDING` 用户并跳转到待审批页；local 登录遇到该状态会直接拒绝。 |
| `DISABLED` | 不可登录。OAuth 和 local 登录都会拒绝；`/api/v1/auth/me` 发现当前会话对应用户已被禁用时，会直接清掉 session。 |
| `MERGED` | 账号已并入其他账号，不可继续登录；主要由账号合并流程写入，不是普通用户管理流程的目标状态。 |
## 用户准入
可配置新用户是否需要审批：
- 自动准入：新用户登录后自动激活
- 审批准入：新用户需 USER_ADMIN 审批后激活
## 角色分配
`USER_ADMIN` 或 `SUPER_ADMIN` 可调用用户管理接口修改平台角色，但当前实现有几个关键点：
- 接口一次只能设置一个目标平台角色。
- 设置时会删除该用户已有的显式平台角色，再写入新的那个角色。
- 如果设置为 `USER`，不会写入 `user_role_binding`，而是依赖运行时默认角色补位。
- `USER_ADMIN` 不能分配 `SUPER_ADMIN`，只有 `SUPER_ADMIN` 能分配。
当前管理接口可设置的目标角色实际上是：
- `USER`
- `SKILL_ADMIN`
- `USER_ADMIN`
- `AUDITOR`
- `SUPER_ADMIN`
## 用户封禁/解封
`USER_ADMIN` 或 `SUPER_ADMIN` 可封禁/解封用户。
当前公开管理接口只支持把状态改成：
- `ACTIVE`
- `DISABLED`
其中：
- “审批通过”本质上也是把用户状态改成 `ACTIVE`。
- 不能通过该接口直接改成 `PENDING` 或 `MERGED`。
## 账号合并
支持将多个账号合并为一个，保留操作历史。
## 下一步
- [创建技能包](../../user-guide/publishing/create-skill) - 开始发布技能

4
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/_category_.json Normal file
View file

@ -0,0 +1,4 @@
{
"label": "安全与合规",
"position": 2
}

38
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/audit-logs.md Normal file
View file

@ -0,0 +1,38 @@
---
title: 审计日志
sidebar_position: 3
description: 操作审计日志查询与管理
---
# 审计日志
SkillHub 记录所有关键操作的审计日志，满足企业合规要求。
## 审计范围
记录的操作包括：
- 技能发布、下载、删除
- 审核通过、拒绝
- 用户登录、登出
- 权限变更
- 命名空间管理
- 配置变更
## 审计日志查询
通过管理后台审计日志页面或 Admin API 查询。
## 日志字段
- 操作时间
- 操作用户
- 操作类型
- 目标资源
- 客户端 IP
- User-Agent
- 请求 ID
- 详细信息
## 下一步
- [命名空间管理](../governance/namespaces) - 管理组织

36
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/authentication.md Normal file
View file

@ -0,0 +1,36 @@
---
title: 认证配置
sidebar_position: 1
description: 配置用户认证方式
---
# 认证配置
SkillHub 支持多种认证方式，满足不同企业的安全需求。
## OAuth2 登录
### GitHub OAuth
1. 在 GitHub 创建 OAuth App
2. 配置环境变量：
```bash
OAUTH2_GITHUB_CLIENT_ID=your-client-id
OAUTH2_GITHUB_CLIENT_SECRET=your-client-secret
```
### 扩展 OAuth Provider
架构支持扩展其他 OAuth Provider，如 GitLab、Gitee 等。
## 本地账号登录
开发环境支持本地账号登录，生产环境默认关闭。
## 企业 SSO 集成
支持通过扩展点集成企业 SSO（SAML/OIDC）。
## 下一步
- [权限管理](./authorization) - 配置权限控制

63
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/authorization.md Normal file
View file

@ -0,0 +1,63 @@
---
title: 权限管理
sidebar_position: 2
description: RBAC 权限系统配置
---
# 权限管理
SkillHub 采用基于角色的访问控制（RBAC）系统。
当前代码里实际存在两套并行角色体系：
- 平台角色：控制后台治理、用户管理、审计等平台级能力。
- 命名空间角色：控制某个团队空间内的成员、发布、审核、归档等操作。
二者会同时参与鉴权，但不是一套角色的上下级映射。
## 平台角色
### 代码里实际初始化的显式平台角色
数据库迁移只初始化了 4 个显式平台角色：
| 角色 | 代码 | 实际能力 |
|------|------|----------|
| 超级管理员 | `SUPER_ADMIN` | 拥有全部权限；`RbacService#getUserPermissions` 会直接返回全部权限码；可访问所有 `SUPER_ADMIN`/`SKILL_ADMIN`/`USER_ADMIN`/`AUDITOR` 能访问的接口；可分配 `SUPER_ADMIN`；发布技能时可绕过命名空间成员校验并直接自动发布；但仍不能审批自己提交的 promotion，且普通审核单若是自己提交的，也只有 `SUPER_ADMIN` 能特判审批。 |
| 技能管理员 | `SKILL_ADMIN` | 可访问技能治理后台接口；可隐藏/取消隐藏技能、撤回版本（yank）、处理技能举报；可查看和处理全局空间审核、promotion 审核、治理工作台收件箱中的 review/promotion/report；不能分配平台角色、不能看审计日志、不能管理用户。 |
| 用户管理员 | `USER_ADMIN` | 可访问用户管理接口；可列表用户、审批用户、启用/禁用用户、修改平台角色；不能分配 `SUPER_ADMIN`；不能处理技能治理、不能看审计日志。 |
| 审计员 | `AUDITOR` | 只读查看审计日志；可访问 `/api/v1/admin/audit-logs` 和 `/actuator/prometheus`；治理工作台中只能看 activity，不能处理 review/promotion/report，也不能管理用户或技能。 |
### 运行时默认平台角色
| 角色 | 代码 | 实际逻辑 |
|------|------|----------|
| 默认用户 | `USER` | 不是 `role` 表里的显式初始化记录。只要用户没有任何显式平台角色绑定，登录态和 `RbacService#getUserRoleCodes` 都会自动补上 `USER`。它主要表示“普通已登录用户”，没有额外后台治理权限。 |
### 需要特别注意的实现细节
- 当前管理接口的“修改用户角色”是单值覆盖，不是追加：`PUT /api/v1/admin/users/{userId}/role` 先清空该用户现有平台角色，再写入一个目标角色；当目标角色是 `USER` 时，不会写数据库记录，而是依赖运行时默认补位。
- 代码底层仍然支持“一个用户拥有多个显式平台角色”的读取与鉴权，因为 session、token 和 `RbacService` 都是按角色集合处理；只是当前管理接口不会这样分配。
- `SUPER_ADMIN` 是唯一一个在权限查询时被视为“拥有全部 permission code”的角色，其它角色依赖 `role_permission` 关联表。
## 命名空间角色
| 角色 | 实际能力 |
|------|----------|
| `OWNER` | 创建团队空间时自动成为 `OWNER`。可更新命名空间信息、管理成员、冻结/解冻空间、归档/恢复空间、转移所有权；可提交 review；可审核团队空间 review；可访问私有技能；可管理受限技能生命周期（归档、反归档、删除草稿/驳回版本等）。 |
| `ADMIN` | 可更新命名空间信息、管理成员、冻结/解冻空间；不能归档/恢复空间，也不能直接把别人设为 `OWNER`；可提交 review；可审核团队空间 review；可访问私有技能；可管理受限技能生命周期。 |
| `MEMBER` | 默认加入全局空间时获得 `MEMBER`。可在所在命名空间发布技能、提交 review；但不能审核 review、不能管理成员、不能冻结/归档空间；私有技能也不能仅因 `MEMBER` 身份访问，私有技能要求 owner 或 `ADMIN/OWNER`。 |
### 命名空间角色的边界
- `GLOBAL` 空间是只读系统空间，不能通过命名空间治理接口修改；全局空间 review/promotion/report 处理依赖平台角色 `SKILL_ADMIN`/`SUPER_ADMIN`，不是依赖全局空间成员身份。
- `NAMESPACE_ONLY` 可见性的技能，任何该命名空间成员都能访问。
- `PRIVATE` 可见性的技能，只有技能 owner 或命名空间 `ADMIN/OWNER` 能访问，`MEMBER` 不行。
## 权限配置
通过后台分配平台角色，通过命名空间成员关系分配命名空间角色。
## 下一步
- [审计日志](./audit-logs) - 查看操作审计

104
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/scanner.md Normal file
View file

@ -0,0 +1,104 @@
---
title: 安全扫描
sidebar_position: 4
description: 使用 Skill Scanner 为技能发布链路提供自动安全检查
---
# 安全扫描
SkillHub 支持在技能发布链路中接入 `skill-scanner`，对上传的技能包执行自动安全检查，并把结果沉淀到安全审计记录中。
## 扫描链路
启用扫描后，发布流程会变成：
1. 用户发起技能发布
2. 后端创建版本记录并进入 `SCANNING`
3. 后端写入扫描任务
4. `skill-scanner` 拉取任务并执行分析
5. 扫描结果写入 `security_audit`
6. 版本进入 `PENDING_REVIEW`，如多次重试后仍失败则进入 `SCAN_FAILED`
7. 后续仍然沿用已有的审核工作流
## 适用场景
- 企业希望在人工审核前增加一层自动风险筛查
- 平台需要保留技能包扫描结果和审计证据
- 部署环境要求对恶意代码、敏感信息或高风险行为做基础检测
## 运行模式
支持两种模式：
- `local`：后端把文件路径传给扫描服务，适合同机或共享文件系统场景
- `upload`：后端直接上传技能包到扫描服务，适合 Docker / Kubernetes 等分离部署场景
推荐做法：
- 本地开发：优先使用 `local`
- 生产环境、Kubernetes、多服务部署：优先使用 `upload`
## 关键配置
后端核心配置项：
```yaml
skillhub:
security:
scanner:
enabled: false
base-url: http://localhost:8000
health-path: /health
scan-path: /scan-upload
mode: upload
connect-timeout-ms: 5000
read-timeout-ms: 300000
retry-max-attempts: 3
```
常用环境变量：
- `SKILLHUB_SECURITY_SCANNER_ENABLED`
- `SKILLHUB_SECURITY_SCANNER_URL`
- `SKILLHUB_SECURITY_SCANNER_MODE`
- `SKILLHUB_SCAN_STREAM_KEY`
- `SKILLHUB_SCAN_STREAM_GROUP`
## 验证方式
启用后建议按下面步骤验证：
1. 发布一个测试技能包
2. 确认版本状态先进入 `SCANNING`
3. 确认生成了 `security_audit` 记录
4. 确认版本最终进入 `PENDING_REVIEW` 或 `SCAN_FAILED`
5. 调用安全审计接口查看扫描结果
```text
GET /api/v1/skills/{skillId}/versions/{versionId}/security-audit
```
## 结果说明
安全审计结果通常包含：
- `scanId`
- `scannerType`
- `verdict`
- `isSafe`
- `maxSeverity`
- `findingsCount`
- `findings`
- `scanDurationSeconds`
- `scannedAt`
## 部署建议
- 单机开发环境可先关闭扫描，确认主流程后再开启
- Kubernetes 中建议使用 `upload` 模式，避免服务间共享文件系统
- 生产环境建议把扫描结果与人工审核一起作为治理证据保留
## 下一步
- [审核工作流](../governance/review-workflow) - 了解扫描后的审核链路
- [部署配置](../deployment/configuration) - 查看部署相关配置

8
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/_category_.json Normal file
View file

@ -0,0 +1,8 @@
{
"label": "用户指南",
"position": 3,
"link": {
"type": "generated-index",
"description": "学习如何发布、发现和使用技能"
}
}

4
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/collaboration/_category_.json Normal file
View file

@ -0,0 +1,4 @@
{
"label": "协作",
"position": 3
}

41
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/collaboration/namespaces.md Normal file
View file

@ -0,0 +1,41 @@
---
title: 团队命名空间
sidebar_position: 1
description: 在团队命名空间中协作
---
# 团队命名空间
## 加入命名空间
需要命名空间管理员邀请才能加入团队命名空间。
## 命名空间角色
### MEMBER
- 可查看命名空间内所有技能
- 可发布技能（需审核）
- 可收藏和评分
### ADMIN
- 所有 MEMBER 权限
- 可审核技能发布
- 可管理成员
- 可编辑命名空间信息
### OWNER
- 所有 ADMIN 权限
- 可转让所有权
- 可归档命名空间
## 技能可见性
| 可见性 | 说明 |
|--------|------|
| `PUBLIC` | 所有人可见，匿名可下载 |
| `NAMESPACE_ONLY` | 仅命名空间成员可见 |
| `PRIVATE` | 仅 owner 和命名空间 ADMIN 可见 |
## 下一步
- [提升到全局](./promotion) - 将团队技能推广到全局

42
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/collaboration/promotion.md Normal file
View file

@ -0,0 +1,42 @@
---
title: 提升到全局
sidebar_position: 2
description: 申请将团队技能提升到全局空间
---
# 提升到全局
优秀的团队技能可以申请提升到全局空间，供全企业使用。
## 提升前提
- 技能在团队空间已发布
- 申请人是技能 owner 或命名空间 ADMIN
- 技能没有待审核的提升申请
## 申请提升
1. 进入团队技能详情页
2. 点击"提升到全局"
3. 填写申请说明
4. 提交申请
## 审核流程
1. 平台管理员收到提升申请
2. 审核技能质量和适用性
3. 审核通过后：
- 在全局空间创建新技能
- 保留原团队技能
- 记录来源追溯关系
## 提升后
- 全局空间的新技能独立管理
- 原团队技能继续存在
- 两者版本不自动同步
- 如需同步需手动操作
## 下一步
- [API 概述](../../developer/api/overview) - API 集成

4
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/_category_.json Normal file
View file

@ -0,0 +1,4 @@
{
"label": "发现与使用",
"position": 2
}

53
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/install.md Normal file
View file

@ -0,0 +1,53 @@
---
title: 安装使用
sidebar_position: 2
description: 安装和使用技能
---
# 安装使用
## 通过 CLI 安装
### 安装最新版本
```bash
clawhub install @team/my-skill
```
### 安装指定版本
```bash
clawhub install @team/my-skill@1.2.0
```
### 按标签安装
```bash
clawhub install @team/my-skill@beta
```
### 使用 ClawHub CLI 安装
```bash
clawhub install my-skill
clawhub install team-name--my-skill
```
## 安装目录
按以下优先级安装：
| 优先级 | 路径 | 说明 |
|--------|------|------|
| 1 | `./.agent/skills/` | 项目级，universal 模式 |
| 2 | `~/.agent/skills/` | 全局级，universal 模式 |
| 3 | `./.claude/skills/` | 项目级，Claude 默认 |
| 4 | `~/.claude/skills/` | 全局级，Claude 默认 |
## 在 Claude Code 中使用
安装后，技能会被 Claude Code 自动发现和加载。
## 下一步
- [评分与收藏](./ratings) - 反馈和收藏技能

30
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/ratings.md Normal file
View file

@ -0,0 +1,30 @@
---
title: 评分与收藏
sidebar_position: 3
description: 技能评分和收藏功能
---
# 评分与收藏
## 收藏技能
点击技能详情页的"收藏"按钮可收藏技能。
查看已收藏的技能：
- Web：进入"我的收藏"
- CLI：`clawhub stars`
## 技能评分
可对技能进行 1-5 分评分：
1. 进入技能详情页
2. 点击评分区域
3. 选择评分（1-5 星）
4. 提交评分
可随时修改自己的评分。
## 下一步
- [团队命名空间](../collaboration/namespaces) - 团队协作

36
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/search.md Normal file
View file

@ -0,0 +1,36 @@
---
title: 搜索技能
sidebar_position: 1
description: 搜索和筛选技能
---
# 搜索技能
## 全文搜索
在搜索框输入关键词，SkillHub 会在以下字段中搜索：
- 技能名称
- 技能描述
- 技能 slug
- frontmatter 中除 `name`、`description`、`version` 外的其他字段
- `keywords` / `tags` 等关键词字段
## 筛选条件
可通过以下条件筛选搜索结果：
- 命名空间
- 可见性
- 下载量排序
- 评分排序
- 更新时间排序
## 高级搜索
使用搜索语法：
- `namespace:@team-ai` - 指定命名空间
- `category:code-review` - 指定分类
- `downloads:>100` - 下载量大于 100
## 下一步
- [安装使用](./install) - 安装和使用技能

4
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/_category_.json Normal file
View file

@ -0,0 +1,4 @@
{
"label": "发布技能",
"position": 1
}

56
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/create-skill.md Normal file
View file

@ -0,0 +1,56 @@
---
title: 创建技能包
sidebar_position: 1
description: 学习如何创建符合规范的技能包
---
# 创建技能包
## 技能包结构
一个标准的 SkillHub 技能包结构如下：
```
my-skill/
├── SKILL.md # 主入口文件（必需）
├── references/ # 参考资料（可选）
├── scripts/ # 脚本（可选）
└── assets/ # 静态资源（可选）
```
## SKILL.md 格式
SKILL.md 是技能包的主入口文件，使用 YAML frontmatter + Markdown 正文格式：
```markdown
---
name: my-skill
description: 一句话描述这个技能的用途
x-astron-category: code-review
---
# 技能说明
这里是技能的详细说明...
```
### Frontmatter 字段
| 字段 | 必需 | 说明 |
|------|------|------|
| `name` | 是 | 技能标识，kebab-case 格式 |
| `description` | 是 | 技能简短描述 |
| `x-astron-category` | 否 | 分类标签 |
| `x-astron-runtime` | 否 | 运行时要求 |
| `x-astron-min-version` | 否 | 最低版本要求 |
## 文件限制
- 单文件大小：最大 1MB
- 总包大小：最大 10MB
- 文件数量：最多 100 个
- 允许的文件类型：`.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.js`, `.ts`, `.py`, `.sh`, `.png`, `.jpg`, `.svg`
## 下一步
- [发布流程](./publish) - 发布技能包

50
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/publish.md Normal file
View file

@ -0,0 +1,50 @@
---
title: 发布流程
sidebar_position: 2
description: 发布技能到 SkillHub
---
# 发布流程
## 通过 Web 发布
1. 登录 SkillHub
2. 点击"发布技能"
3. 选择目标命名空间
4. 上传技能包 ZIP 文件
5. 填写版本信息（变更日志等）
6. 提交发布
7. 等待审核（如需要）
8. 审核通过后发布成功
## 通过 CLI 发布
```bash
# 1. 登录
clawhub login
# 2. 发布
clawhub publish ./my-skill.zip --namespace @team-myteam
```
## 通过 ClawHub CLI 发布
配置 registry 后使用：
```bash
clawhub publish ./my-skill.zip
```
## 发布状态
| 状态 | 说明 |
|------|------|
| `DRAFT` | 草稿，未提交审核 |
| `PENDING_REVIEW` | 等待审核 |
| `PUBLISHED` | 已发布，可被发现和下载 |
| `REJECTED` | 已拒绝，需修改后重新提交 |
| `YANKED` | 已撤回，不再推荐使用 |
## 下一步
- [版本管理](./versioning) - 管理技能版本

56
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/versioning.md Normal file
View file

@ -0,0 +1,56 @@
---
title: 版本管理
sidebar_position: 3
description: 技能版本和标签管理
---
# 版本管理
## 语义化版本
SkillHub 使用语义化版本（Semantic Versioning）：`MAJOR.MINOR.PATCH`
- `MAJOR`：不兼容的 API 变更
- `MINOR`：向后兼容的功能新增
- `PATCH`：向后兼容的问题修复
示例：`1.0.0`, `1.1.0`, `2.0.0`
## latest 标签
`latest` 是系统保留标签，自动跟随最新已发布版本，不可手动移动。
## 自定义标签
可创建自定义标签用于版本通道管理：
- `beta` - 测试版本
- `stable` - 稳定版本
- `stable-2026q1` - 季度稳定版本
### 创建/移动标签
```bash
clawhub tag set @team/my-skill beta 1.2.0
```
### 删除标签
```bash
clawhub tag delete @team/my-skill beta
```
## 版本撤回
已发布版本发现问题可撤回：
1. 进入技能详情页
2. 找到目标版本
3. 点击"撤回版本"
4. 确认撤回
撤回后的版本仍可查看，但会标记为不推荐使用。
## 下一步
- [搜索技能](../discovery/search) - 发现技能

8
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/_category_.json Normal file
View file

@ -0,0 +1,8 @@
{
"label": "开发者参考",
"position": 4,
"link": {
"type": "generated-index",
"description": "API 参考、架构设计和扩展开发"
}
}

4
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/_category_.json Normal file
View file

@ -0,0 +1,4 @@
{
"label": "API 参考",
"position": 1
}

101
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/authenticated.md Normal file
View file

@ -0,0 +1,101 @@
---
title: 认证 API
sidebar_position: 3
description: 需要认证的 API
---
# 认证 API
## 认证相关
### 获取当前用户
```http
GET /api/v1/auth/me
```
### 登出
```http
POST /api/v1/auth/logout
```
## 技能发布
```http
POST /api/v1/publish
Content-Type: multipart/form-data
file: <zip-file>
namespace: <namespace-slug>
```
## 收藏
```http
POST /api/v1/skills/{namespace}/{slug}/star
DELETE /api/v1/skills/{namespace}/{slug}/star
```
## 评分
```http
POST /api/v1/skills/{namespace}/{slug}/rating
Content-Type: application/json
{
"score": 5
}
```
## 标签管理
```http
GET /api/v1/skills/{namespace}/{slug}/tags
PUT /api/v1/skills/{namespace}/{slug}/tags/{tagName}
DELETE /api/v1/skills/{namespace}/{slug}/tags/{tagName}
```
## 我的资源
```http
GET /api/v1/me/stars
GET /api/v1/me/skills
```
## 命名空间管理
```http
POST /api/v1/namespaces
PUT /api/v1/namespaces/{slug}
GET /api/v1/namespaces/{slug}/members
POST /api/v1/namespaces/{slug}/members
PUT /api/v1/namespaces/{slug}/members/{userId}/role
DELETE /api/v1/namespaces/{slug}/members/{userId}
```
## 审核
```http
GET /api/v1/namespaces/{slug}/reviews
POST /api/v1/namespaces/{slug}/reviews/{id}/approve
POST /api/v1/namespaces/{slug}/reviews/{id}/reject
```
## 提升申请
```http
POST /api/v1/namespaces/{slug}/skills/{skillId}/promote
```
## API Token
```http
POST /api/v1/tokens
GET /api/v1/tokens
DELETE /api/v1/tokens/{id}
```
## 下一步
- [CLI 兼容层](./cli-compat) - ClawHub 兼容接口

159
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/cli-compat.md Normal file
View file

@ -0,0 +1,159 @@
---
title: CLI 兼容层
sidebar_position: 4
description: ClawHub CLI 协议兼容层
---
# CLI 兼容层
SkillHub 提供 ClawHub CLI 协议兼容层，现有工具可无缝迁移。
## 配置 ClawHub CLI
要让 ClawHub CLI 连接到你的 SkillHub 实例，需要配置以下环境变量：
### 环境变量配置
**Linux/macOS (bash/zsh):**
```bash
# ~/.bashrc 或 ~/.zshrc
export CLAWHUB_SITE=https://skill.xfyun.cn
export CLAWHUB_REGISTRY=https://skill.xfyun.cn
```
**Windows (PowerShell):**
```powershell
# 永久设置（当前用户）
[Environment]::SetEnvironmentVariable('CLAWHUB_SITE', 'https://skill.xfyun.cn', 'User')
[Environment]::SetEnvironmentVariable('CLAWHUB_REGISTRY', 'https://skill.xfyun.cn', 'User')
# 或者临时设置（当前会话）
$env:CLAWHUB_SITE = 'https://skill.xfyun.cn'
$env:CLAWHUB_REGISTRY = 'https://skill.xfyun.cn'
```
### 使用 CLI 标志（单次命令）
```bash
clawhub --site https://skill.xfyun.cn --registry https://skill.xfyun.cn install <skill>
```
### 前端一键复制
SkillHub 网页端的技能详情页会自动显示带有正确环境变量的安装命令，直接复制即可使用。
## Well-known 发现
```http
GET /.well-known/clawhub.json
```
响应：
```json
{
"apiBase": "/api/v1"
}
```
## 兼容层 API
### Whoami
```http
GET /api/v1/whoami
```
响应：
```json
{
"handle": "username",
"displayName": "User Name",
"role": "user"
}
```
### 搜索
```http
GET /api/v1/search?q={keyword}&page={page}&limit={limit}
```
响应：
```json
{
"results": [
{
"slug": "my-skill",
"name": "My Skill",
"description": "...",
"author": {
"handle": "username",
"displayName": "User Name"
},
"version": "1.2.0",
"downloadCount": 100,
"starCount": 50,
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-03-01T00:00:00Z"
}
],
"total": 1,
"page": 1,
"limit": 20
}
```
### 解析
```http
GET /api/v1/resolve?slug={slug}&version={version}
```
响应：
```json
{
"slug": "my-skill",
"version": "1.2.0",
"downloadUrl": "/api/v1/download/my-skill/1.2.0"
}
```
### 下载
```http
GET /api/v1/download/{slug}/{version}
```
### 发布
```http
POST /api/v1/publish
Content-Type: multipart/form-data
file: <zip-file>
```
响应：
```json
{
"slug": "my-skill",
"version": "1.0.0",
"status": "published"
}
```
## 坐标映射
| SkillHub 坐标 | ClawHub canonical slug |
|---------------|------------------------|
| `@global/my-skill` | `my-skill` |
| `@team-name/my-skill` | `team-name--my-skill` |
## 下一步
- [系统架构](../architecture/overview) - 了解架构设计

86
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/overview.md Normal file
View file

@ -0,0 +1,86 @@
---
title: API 概述
sidebar_position: 1
description: SkillHub API 概述
---
# API 概述
SkillHub 提供 RESTful API 用于集成和自动化。
## API 分类
### 公开 API
- 技能搜索
- 技能详情
- 版本列表
- 下载技能
- 无需认证（PUBLIC 技能）
### 认证 API
- 发布技能
- 收藏/评分
- 命名空间管理
- 需要登录或 Bearer Token
### CLI 兼容层
- 兼容 ClawHub CLI 协议
- 现有工具可无缝迁移
## 响应格式
### 统一响应结构
```json
{
"code": 0,
"msg": "成功",
"data": {},
"timestamp": "2026-03-15T06:00:00Z",
"requestId": "req-123"
}
```
### 分页响应
```json
{
"code": 0,
"msg": "成功",
"data": {
"items": [],
"total": 100,
"page": 1,
"size": 20
},
"timestamp": "2026-03-15T06:00:00Z",
"requestId": "req-123"
}
```
## 认证方式
### Session Cookie
Web 端使用 Session Cookie 认证。
### Bearer Token
CLI 和 API 集成使用 Bearer Token：
```bash
Authorization: Bearer <token>
```
### API Token
可创建长期有效的 API Token 用于自动化。
## 幂等性
所有写操作支持 `X-Request-Id` 请求头实现幂等：
```bash
X-Request-Id: <uuid-v4>
```
## 下一步
- [公开 API](./public) - 查看公开接口

72
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/public.md Normal file
View file

@ -0,0 +1,72 @@
---
title: 公开 API
sidebar_position: 2
description: 无需认证的公开 API
---
# 公开 API
## 技能搜索
```http
GET /api/v1/skills?keyword=...&namespace=...&page=1&size=20
```
**Query Parameters:**
- `keyword`: 搜索关键词
- `namespace`: 命名空间筛选
- `page`: 页码
- `size`: 每页数量
## 技能详情
```http
GET /api/v1/skills/{namespace}/{slug}
```
## 版本列表
```http
GET /api/v1/skills/{namespace}/{slug}/versions
```
## 版本详情
```http
GET /api/v1/skills/{namespace}/{slug}/versions/{version}
```
## 文件清单
```http
GET /api/v1/skills/{namespace}/{slug}/versions/{version}/files
```
## 下载技能
```http
GET /api/v1/skills/{namespace}/{slug}/download
GET /api/v1/skills/{namespace}/{slug}/versions/{version}/download
```
## 解析版本
```http
GET /api/v1/skills/{namespace}/{slug}/resolve?version=...&tag=...
```
## 命名空间列表
```http
GET /api/v1/namespaces
```
## 命名空间详情
```http
GET /api/v1/namespaces/{slug}
```
## 下一步
- [认证 API](./authenticated) - 查看认证接口

4
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/_category_.json Normal file
View file

@ -0,0 +1,4 @@
{
"label": "架构设计",
"position": 2
}

77
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/domain-model.md Normal file
View file

@ -0,0 +1,77 @@
---
title: 领域模型
sidebar_position: 2
description: 核心领域实体和关系
---
# 领域模型
## 核心实体
### Namespace（命名空间）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| slug | varchar(64) | URL 友好标识 |
| display_name | varchar(128) | 展示名 |
| type | enum | `GLOBAL` / `TEAM` |
| description | text | 描述 |
| status | enum | `ACTIVE` / `FROZEN` / `ARCHIVED` |
### NamespaceMember（命名空间成员）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| namespace_id | bigint | 命名空间 ID |
| user_id | varchar(128) | 用户 ID |
| role | enum | `OWNER` / `ADMIN` / `MEMBER` |
### Skill（技能）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| namespace_id | bigint | 所属命名空间 |
| slug | varchar(128) | URL 友好标识 |
| display_name | varchar(256) | 展示名 |
| summary | varchar(512) | 摘要 |
| owner_id | varchar(128) | 主要维护人 |
| visibility | enum | `PUBLIC` / `NAMESPACE_ONLY` / `PRIVATE` |
| status | enum | `ACTIVE` / `HIDDEN` / `ARCHIVED` |
| latest_version_id | bigint | 最新已发布版本 |
**唯一约束**：`(namespace_id, slug)`
### SkillVersion（技能版本）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| skill_id | bigint | 技能 ID |
| version | varchar(32) | semver 版本号 |
| status | enum | `DRAFT` / `PENDING_REVIEW` / `PUBLISHED` / `REJECTED` / `YANKED` |
| manifest_json | json | 文件清单 |
| parsed_metadata_json | json | SKILL.md 解析结果 |
**唯一约束**：`(skill_id, version)`
### SkillTag（技能标签）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| skill_id | bigint | 技能 ID |
| tag_name | varchar(64) | 标签名 |
| target_version_id | bigint | 目标版本 |
**唯一约束**：`(skill_id, tag_name)`
## 坐标系统
技能完整寻址：`@{namespace_slug}/{skill_slug}`
## 下一步
- [安全架构](./security) - 安全设计

69
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/overview.md Normal file
View file

@ -0,0 +1,69 @@
---
title: 系统架构
sidebar_position: 1
description: SkillHub 系统架构概览
---
# 系统架构
## 架构原则
- **单体优先**：一期采用模块化单体，不拆微服务
- **依赖倒置**：领域层不依赖基础设施
- **可替换边界**：搜索、存储都有 SPI 抽象
## 模块结构
```
server/
├── skillhub-app/ # 启动、配置装配、Controller
├── skillhub-domain/ # 领域模型 + 领域服务 + 应用服务
├── skillhub-auth/ # OAuth2 认证 + RBAC + 授权判定
├── skillhub-search/ # 搜索 SPI + PostgreSQL 全文实现
├── skillhub-storage/ # 对象存储抽象 + LocalFile/S3
└── skillhub-infra/ # JPA、通用工具、配置基础
```
## 模块依赖
```
app → domain, auth, search, storage, infra
infra → domain
auth → domain
search → domain
storage → (独立)
```
## 技术栈
| 层级 | 技术 | 版本 |
|------|------|------|
| 运行时 | Java | 21 |
| 框架 | Spring Boot | 3.2.3 |
| 数据库 | PostgreSQL | 16.x |
| 缓存/会话 | Redis | 7.x |
## 部署架构
```
┌──────────────┐
│ Browser / CLI│
└──────┬───────┘
│
▼
┌──────────────┐
│ Web/Nginx │
└──────┬───────┘
│ /api/*
▼
┌──────────────┐
│ Spring Boot │
└───┬────┬─────┘
│ │
▼ ▼
PostgreSQL Redis
```
## 下一步
- [领域模型](./domain-model) - 核心实体

71
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/security.md Normal file
View file

@ -0,0 +1,71 @@
---
title: 安全架构
sidebar_position: 3
description: 安全架构设计
---
# 安全架构
## 认证架构
### OAuth2 登录
- 基于 Spring Security OAuth2 Client
- 一期支持 GitHub
- 架构支持扩展多 Provider
### CLI 认证
- OAuth Device Flow
- Web 授权后签发 CLI 凭证
- 支持 API Token
### Session 管理
- Spring Session + Redis
- 分布式 Session 共享
- 支持多 Pod 部署
## 授权架构
### 平台角色
| 角色 | 权限 |
|------|------|
| `SUPER_ADMIN` | 所有权限 |
| `SKILL_ADMIN` | 技能治理 |
| `USER_ADMIN` | 用户治理 |
| `AUDITOR` | 审计只读 |
### 命名空间角色
| 角色 | 权限 |
|------|------|
| `OWNER` | 命名空间所有者 |
| `ADMIN` | 审核、成员管理 |
| `MEMBER` | 发布技能 |
### 可见性规则
| 可见性 | 谁可访问 |
|--------|---------|
| `PUBLIC` | 任何人（匿名） |
| `NAMESPACE_ONLY` | 命名空间成员 |
| `PRIVATE` | owner + 命名空间 ADMIN |
## 审计
所有关键操作同步写入审计日志：
- 发布、下载、删除
- 审核通过、拒绝
- 权限变更
- 配置变更
## 限流
- Ingress 层基础限流（Nginx）
- 应用层精细限流（Redis 滑动窗口）
## 下一步
- [技能协议](../plugins/skill-protocol) - 技能包规范

4
document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/plugins/_category_.json Normal file
View file

@ -0,0 +1,4 @@
{
"label": "扩展与集成",
"position": 3
}

Some files were not shown because too many files have changed in this diff Show more