mirror of
https://github.com/iflytek/skillhub.git
synced 2026-08-27 11:14:59 +00:00
feat(docs): complete Docusaurus website with bilingual support
Add complete bilingual (Chinese/English) documentation website: - Chinese documentation in docs/ - English documentation in i18n/en/ - iFlytek blue theme customization - Role-based navigation structure - ToB enterprise value-focused content
This commit is contained in:
tww
parent
3e2f25a42f
commit
19329480c8
40 changed files with 1743 additions and 5 deletions
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"label": "Deployment Guide",
|
||||
"position": 1
|
||||
}
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
---
|
||||
title: Configuration Reference
|
||||
sidebar_position: 3
|
||||
description: Detailed SkillHub configuration reference
|
||||
---
|
||||
|
||||
# Configuration Reference
|
||||
|
||||
## Environment Variables
|
||||
|
||||
SkillHub is configured through environment variables. The main configuration items are listed below:
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
| Environment Variable | Description | Default Value |
|
||||
|---------------------|-------------|---------------|
|
||||
| `SKILLHUB_PUBLIC_BASE_URL` | Public access URL | - |
|
||||
| `SKILLHUB_VERSION` | Image version | `edge` |
|
||||
|
||||
### Database Configuration
|
||||
|
||||
| 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 Configuration
|
||||
|
||||
| Environment Variable | Description | Default Value |
|
||||
|---------------------|-------------|---------------|
|
||||
| `REDIS_HOST` | Redis host | `redis` |
|
||||
| `REDIS_PORT` | Redis port | `6379` |
|
||||
| `REDIS_PASSWORD` | Redis password | - |
|
||||
|
||||
### Storage Configuration
|
||||
|
||||
| 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 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
|
||||
|
||||
| Environment Variable | Description | Default Value |
|
||||
|---------------------|-------------|---------------|
|
||||
| `BOOTSTRAP_ADMIN_ENABLED` | Enable bootstrap admin | `true` |
|
||||
| `BOOTSTRAP_ADMIN_USERNAME` | Bootstrap admin username | - |
|
||||
| `BOOTSTRAP_ADMIN_PASSWORD` | Bootstrap admin password | - |
|
||||
|
||||
## Configuration Files
|
||||
|
||||
Spring Boot configuration files are located at `server/skillhub-app/src/main/resources/`.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Authentication Configuration](../security/authentication) - Configure authentication
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
title: Kubernetes Deployment
|
||||
sidebar_position: 2
|
||||
description: Deploy SkillHub in a Kubernetes cluster
|
||||
---
|
||||
|
||||
# Kubernetes Deployment
|
||||
|
||||
This guide describes how to deploy SkillHub in a Kubernetes cluster.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Kubernetes 1.24+
|
||||
- kubectl configured
|
||||
- Helm 3.0+ (optional)
|
||||
- Available persistent storage class
|
||||
|
||||
## Deployment Manifests
|
||||
|
||||
Kubernetes deployment manifests are provided in the project:
|
||||
|
||||
```bash
|
||||
cd deploy/k8s
|
||||
|
||||
# 1. Create namespace
|
||||
kubectl create namespace skillhub
|
||||
|
||||
# 2. Configure Secret
|
||||
cp secret.yaml.example secret.yaml
|
||||
# Edit secret.yaml and fill in real credentials
|
||||
|
||||
# 3. Apply configuration
|
||||
kubectl apply -f configmap.yaml
|
||||
kubectl apply -f secret.yaml
|
||||
|
||||
# 4. Deploy services
|
||||
kubectl apply -f backend-deployment.yaml
|
||||
kubectl apply -f frontend-deployment.yaml
|
||||
kubectl apply -f services.yaml
|
||||
|
||||
# 5. Configure Ingress
|
||||
kubectl apply -f ingress.yaml
|
||||
```
|
||||
|
||||
## High Availability Configuration
|
||||
|
||||
- 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) - Detailed configuration reference
|
||||
|
|
@ -0,0 +1,65 @@
|
|||
---
|
||||
title: Single Machine Deployment
|
||||
sidebar_position: 1
|
||||
description: Deploy SkillHub using Docker Compose on a single machine
|
||||
---
|
||||
|
||||
# Single Machine Deployment
|
||||
|
||||
This guide describes how to deploy SkillHub on a single server using Docker Compose.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker Engine 20.10+
|
||||
- Docker Compose Plugin 2.0+
|
||||
- At least 4GB available RAM
|
||||
- At least 20GB available disk space
|
||||
|
||||
## Quick Deployment
|
||||
|
||||
```bash
|
||||
# 1. Clone the repository
|
||||
git clone https://github.com/iflytek/skillhub.git
|
||||
cd skillhub
|
||||
|
||||
# 2. Copy environment variable template
|
||||
cp .env.release.example .env.release
|
||||
|
||||
# 3. Edit configuration
|
||||
# Modify configuration items in .env.release, especially passwords and public URLs
|
||||
|
||||
# 4. Validate configuration
|
||||
make validate-release-config
|
||||
|
||||
# 5. Start services
|
||||
docker compose --env-file .env.release -f compose.release.yml up -d
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
# Access Web UI
|
||||
# Open http://localhost in browser (or configured public URL)
|
||||
```
|
||||
|
||||
## First Login Configuration
|
||||
|
||||
1. Login with `BOOTSTRAP_ADMIN_USERNAME` and `BOOTSTRAP_ADMIN_PASSWORD`
|
||||
2. Change admin password immediately
|
||||
3. Configure enterprise SSO (optional)
|
||||
4. Create team namespaces
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Configuration](./configuration) - Detailed configuration reference
|
||||
- [Kubernetes Deployment](./kubernetes) - High availability deployment
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"label": "Governance & Operations",
|
||||
"position": 3
|
||||
}
|
||||
|
|
@ -0,0 +1,56 @@
|
|||
---
|
||||
title: Namespace Management
|
||||
sidebar_position: 1
|
||||
description: Namespace creation and management
|
||||
---
|
||||
|
||||
# Namespace Management
|
||||
|
||||
Namespaces are the isolation boundary and collaboration unit for skills in SkillHub.
|
||||
|
||||
## Namespace Types
|
||||
|
||||
| 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. 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. 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
|
||||
|
||||
Namespace OWNER or ADMIN can change member roles.
|
||||
|
||||
### Remove Member
|
||||
|
||||
Namespace OWNER or ADMIN can remove members.
|
||||
|
||||
## Namespace Status
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `ACTIVE` | Normal use |
|
||||
| `FROZEN` | Frozen, read-only, cannot publish |
|
||||
| `ARCHIVED` | Archived, not visible externally |
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Review Workflow](./review-workflow) - Understand skill review
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
title: Review Workflow
|
||||
sidebar_position: 2
|
||||
description: Skill publishing review workflow configuration
|
||||
---
|
||||
|
||||
# Review Workflow
|
||||
|
||||
SkillHub uses a two-tier review mechanism to ensure skill quality.
|
||||
|
||||
## Review Workflow
|
||||
|
||||
### Team Namespace Skills
|
||||
|
||||
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. Submit publishing
|
||||
2. Platform SKILL_ADMIN or SUPER_ADMIN reviews
|
||||
3. Published after review approval
|
||||
|
||||
## Promote Team Skill to Global
|
||||
|
||||
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
|
||||
|
||||
| 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) - Manage platform users
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
title: User Management
|
||||
sidebar_position: 3
|
||||
description: Platform user management
|
||||
---
|
||||
|
||||
# User Management
|
||||
|
||||
## User Status
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `ACTIVE` | Normal use |
|
||||
| `PENDING` | Pending approval |
|
||||
| `DISABLED` | Disabled |
|
||||
| `MERGED` | Merged into another account |
|
||||
|
||||
## User Admission
|
||||
|
||||
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 can assign platform roles:
|
||||
- SKILL_ADMIN
|
||||
- USER_ADMIN
|
||||
- AUDITOR
|
||||
|
||||
Note: Cannot assign SUPER_ADMIN (only SUPER_ADMIN can assign)
|
||||
|
||||
## User Disable/Enable
|
||||
|
||||
USER_ADMIN or SUPER_ADMIN can disable/enable users.
|
||||
|
||||
## Account Merge
|
||||
|
||||
Supports merging multiple accounts into one, preserving operation history.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Create Skill Package](../../03-user-guide/publishing/create-skill) - Start publishing skills
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"label": "Security & Compliance",
|
||||
"position": 2
|
||||
}
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
title: Audit Logs
|
||||
sidebar_position: 3
|
||||
description: Operation audit log query and management
|
||||
---
|
||||
|
||||
# Audit Logs
|
||||
|
||||
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
|
||||
|
||||
Query through admin dashboard audit log page or Admin API.
|
||||
|
||||
## Log Fields
|
||||
|
||||
- Operation time
|
||||
- Operating user
|
||||
- Operation type
|
||||
- Target resource
|
||||
- Client IP
|
||||
- User-Agent
|
||||
- Request ID
|
||||
- Detailed information
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Namespace Management](../governance/namespaces) - Manage organization
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
---
|
||||
title: Authentication Configuration
|
||||
sidebar_position: 1
|
||||
description: Configure user authentication methods
|
||||
---
|
||||
|
||||
# Authentication Configuration
|
||||
|
||||
SkillHub supports multiple authentication methods to meet different enterprise security requirements.
|
||||
|
||||
## OAuth2 Login
|
||||
|
||||
### GitHub OAuth
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
### Extend OAuth Provider
|
||||
|
||||
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.
|
||||
|
||||
## Enterprise SSO Integration
|
||||
|
||||
Supports integrating enterprise SSO (SAML/OIDC) through extension points.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Authorization](./authorization) - Configure access control
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
title: Authorization Management
|
||||
sidebar_position: 2
|
||||
description: RBAC permission system configuration
|
||||
---
|
||||
|
||||
# Authorization Management
|
||||
|
||||
SkillHub uses a Role-Based Access Control (RBAC) system.
|
||||
|
||||
## Platform Roles
|
||||
|
||||
| Role | Code | Description |
|
||||
|------|------|-------------|
|
||||
| Super Admin | `SUPER_ADMIN` | Has all permissions |
|
||||
| Skill Admin | `SKILL_ADMIN` | Global namespace review, skill governance |
|
||||
| User Admin | `USER_ADMIN` | User management, role assignment |
|
||||
| Auditor | `AUDITOR` | Audit log read-only |
|
||||
|
||||
## Namespace Roles
|
||||
|
||||
| Role | Description |
|
||||
|------|-------------|
|
||||
| `OWNER` | Namespace owner, can transfer ownership |
|
||||
| `ADMIN` | Namespace admin, can review, manage members |
|
||||
| `MEMBER` | Regular member, can publish skills |
|
||||
|
||||
## Permission Configuration
|
||||
|
||||
Assign platform roles and namespace roles through the admin dashboard.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Audit Logs](./audit-logs) - View operation audits
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"label": "Collaboration",
|
||||
"position": 3
|
||||
}
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
---
|
||||
title: Team Namespaces
|
||||
sidebar_position: 1
|
||||
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
|
||||
- All MEMBER permissions
|
||||
- Can review skill publishing
|
||||
- Can manage members
|
||||
- Can edit namespace information
|
||||
|
||||
### OWNER
|
||||
- All ADMIN permissions
|
||||
- Can transfer ownership
|
||||
- Can archive namespace
|
||||
|
||||
## Skill Visibility
|
||||
|
||||
| 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
|
||||
|
||||
- [Promote to Global](./promotion) - Promote team skills to global
|
||||
|
|
@ -0,0 +1,42 @@
|
|||
---
|
||||
title: Promote to Global
|
||||
sidebar_position: 2
|
||||
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
|
||||
|
||||
- Skill is published in team namespace
|
||||
- Applicant is skill owner or namespace ADMIN
|
||||
- Skill has no pending promotion requests
|
||||
|
||||
## Apply for Promotion
|
||||
|
||||
1. Go to team skill detail page
|
||||
2. Click "Promote to Global"
|
||||
3. Fill in application description
|
||||
4. Submit application
|
||||
|
||||
## Review Workflow
|
||||
|
||||
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 Overview](../../04-developer/api/overview) - API integration
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"label": "Discovery & Usage",
|
||||
"position": 2
|
||||
}
|
||||
|
|
@ -0,0 +1,53 @@
|
|||
---
|
||||
title: Install & Use
|
||||
sidebar_position: 2
|
||||
description: Install and use skills
|
||||
---
|
||||
|
||||
# Install & Use
|
||||
|
||||
## Install via CLI
|
||||
|
||||
### Install Latest Version
|
||||
|
||||
```bash
|
||||
skillhub install @team/my-skill
|
||||
```
|
||||
|
||||
### Install Specific Version
|
||||
|
||||
```bash
|
||||
skillhub install @team/my-skill@1.2.0
|
||||
```
|
||||
|
||||
### Install by Tag
|
||||
|
||||
```bash
|
||||
skillhub install @team/my-skill@beta
|
||||
```
|
||||
|
||||
### Install with ClawHub CLI
|
||||
|
||||
```bash
|
||||
clawhub install my-skill
|
||||
clawhub install team-name--my-skill
|
||||
```
|
||||
|
||||
## Installation Directory
|
||||
|
||||
Install by the following priority:
|
||||
|
||||
| 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 |
|
||||
|
||||
## Use in Claude Code
|
||||
|
||||
After installation, skills are automatically discovered and loaded by Claude Code.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Ratings & Stars](./ratings) - Feedback and favorite skills
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
title: Ratings & Stars
|
||||
sidebar_position: 3
|
||||
description: Skill rating and favorite features
|
||||
---
|
||||
|
||||
# Ratings & Stars
|
||||
|
||||
## Favorite Skills
|
||||
|
||||
Click the "Favorite" button on the skill detail page to favorite a skill.
|
||||
|
||||
View your favorite skills:
|
||||
- Web: Go to "My Favorites"
|
||||
- CLI: `skillhub stars`
|
||||
|
||||
## Skill Rating
|
||||
|
||||
You can rate skills from 1-5 stars:
|
||||
|
||||
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
|
||||
|
||||
- [Team Namespaces](../collaboration/namespaces) - Team collaboration
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
---
|
||||
title: Search Skills
|
||||
sidebar_position: 1
|
||||
description: Search and filter skills
|
||||
---
|
||||
|
||||
# Search Skills
|
||||
|
||||
## Full-text Search
|
||||
|
||||
Enter keywords in the search box, SkillHub searches in the following fields:
|
||||
- Skill name
|
||||
- Skill description
|
||||
- SKILL.md body content
|
||||
- Keywords
|
||||
|
||||
## Filter Conditions
|
||||
|
||||
You can filter search results by the following conditions:
|
||||
- Namespace
|
||||
- Visibility
|
||||
- Download count sorting
|
||||
- Rating sorting
|
||||
- Update time sorting
|
||||
|
||||
## Advanced Search
|
||||
|
||||
Use search syntax:
|
||||
- `namespace:@team-ai` - Specify namespace
|
||||
- `category:code-review` - Specify category
|
||||
- `downloads:>100` - Downloads greater than 100
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Install & Use](./install) - Install and use skills
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"label": "Publishing Skills",
|
||||
"position": 1
|
||||
}
|
||||
|
|
@ -0,0 +1,56 @@
|
|||
---
|
||||
title: Create Skill Package
|
||||
sidebar_position: 1
|
||||
description: Learn how to create a compliant skill package
|
||||
---
|
||||
|
||||
# Create Skill Package
|
||||
|
||||
## Skill Package Structure
|
||||
|
||||
A standard SkillHub skill package structure looks like this:
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Main entry file (required)
|
||||
├── references/ # References (optional)
|
||||
├── scripts/ # Scripts (optional)
|
||||
└── assets/ # Static assets (optional)
|
||||
```
|
||||
|
||||
## SKILL.md Format
|
||||
|
||||
SKILL.md is the main entry file of a skill package, using YAML frontmatter + Markdown body format:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: One sentence describing what this skill is for
|
||||
x-astron-category: code-review
|
||||
---
|
||||
|
||||
# Skill Description
|
||||
|
||||
Detailed skill description goes here...
|
||||
```
|
||||
|
||||
### Frontmatter Fields
|
||||
|
||||
| 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
|
||||
|
||||
- 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 Workflow](./publish) - Publish skill package
|
||||
|
|
@ -0,0 +1,50 @@
|
|||
---
|
||||
title: Publish Workflow
|
||||
sidebar_position: 2
|
||||
description: Publish skills to SkillHub
|
||||
---
|
||||
|
||||
# Publish Workflow
|
||||
|
||||
## Publish via Web
|
||||
|
||||
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
|
||||
|
||||
## Publish via CLI
|
||||
|
||||
```bash
|
||||
# 1. Login
|
||||
skillhub login
|
||||
|
||||
# 2. Publish
|
||||
skillhub publish ./my-skill.zip --namespace @team-myteam
|
||||
```
|
||||
|
||||
## Publish via ClawHub CLI
|
||||
|
||||
Use after configuring registry:
|
||||
|
||||
```bash
|
||||
clawhub publish ./my-skill.zip
|
||||
```
|
||||
|
||||
## Publishing Status
|
||||
|
||||
| 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
|
||||
|
||||
- [Version Management](./versioning) - Manage skill versions
|
||||
|
|
@ -0,0 +1,56 @@
|
|||
---
|
||||
title: Version Management
|
||||
sidebar_position: 3
|
||||
description: Skill version and tag management
|
||||
---
|
||||
|
||||
# Version Management
|
||||
|
||||
## Semantic Versioning
|
||||
|
||||
SkillHub uses Semantic Versioning: `MAJOR.MINOR.PATCH`
|
||||
|
||||
- `MAJOR`: Incompatible API changes
|
||||
- `MINOR`: Backward compatible feature additions
|
||||
- `PATCH`: Backward compatible bug fixes
|
||||
|
||||
Examples: `1.0.0`, `1.1.0`, `2.0.0`
|
||||
|
||||
## latest Tag
|
||||
|
||||
`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` - Beta version
|
||||
- `stable` - Stable version
|
||||
- `stable-2026q1` - Quarterly stable version
|
||||
|
||||
### Create/Move Tag
|
||||
|
||||
```bash
|
||||
skillhub tag set @team/my-skill beta 1.2.0
|
||||
```
|
||||
|
||||
### Delete Tag
|
||||
|
||||
```bash
|
||||
skillhub tag delete @team/my-skill beta
|
||||
```
|
||||
|
||||
## Version Withdrawal
|
||||
|
||||
Published versions with issues can be withdrawn:
|
||||
|
||||
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
|
||||
|
||||
- [Search Skills](../discovery/search) - Discover skills
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"label": "API Reference",
|
||||
"position": 1
|
||||
}
|
||||
|
|
@ -0,0 +1,101 @@
|
|||
---
|
||||
title: Authenticated APIs
|
||||
sidebar_position: 3
|
||||
description: APIs requiring authentication
|
||||
---
|
||||
|
||||
# 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
|
||||
Content-Type: multipart/form-data
|
||||
|
||||
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
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"score": 5
|
||||
}
|
||||
```
|
||||
|
||||
## Tag Management
|
||||
|
||||
```http
|
||||
GET /api/v1/skills/{namespace}/{slug}/tags
|
||||
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
|
||||
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}
|
||||
```
|
||||
|
||||
## Reviews
|
||||
|
||||
```http
|
||||
GET /api/v1/namespaces/{slug}/reviews
|
||||
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
|
||||
```
|
||||
|
||||
## API Token
|
||||
|
||||
```http
|
||||
POST /api/v1/tokens
|
||||
GET /api/v1/tokens
|
||||
DELETE /api/v1/tokens/{id}
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [CLI Compatibility Layer](./cli-compat) - ClawHub compatible endpoints
|
||||
|
|
@ -0,0 +1,125 @@
|
|||
---
|
||||
title: CLI Compatibility Layer
|
||||
sidebar_position: 4
|
||||
description: ClawHub CLI protocol compatibility layer
|
||||
---
|
||||
|
||||
# CLI Compatibility Layer
|
||||
|
||||
SkillHub provides a ClawHub CLI protocol compatibility layer for seamless migration of existing tools.
|
||||
|
||||
## Well-known Discovery
|
||||
|
||||
```http
|
||||
GET /.well-known/clawhub.json
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"apiBase": "/api/compat/v1"
|
||||
}
|
||||
```
|
||||
|
||||
## Compatibility Layer APIs
|
||||
|
||||
### Whoami
|
||||
|
||||
```http
|
||||
GET /api/compat/v1/whoami
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"handle": "username",
|
||||
"displayName": "User Name",
|
||||
"role": "user"
|
||||
}
|
||||
```
|
||||
|
||||
### Search
|
||||
|
||||
```http
|
||||
GET /api/compat/v1/search?q={keyword}&page={page}&limit={limit}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
### Resolve
|
||||
|
||||
```http
|
||||
GET /api/compat/v1/resolve?slug={slug}&version={version}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"slug": "my-skill",
|
||||
"version": "1.2.0",
|
||||
"downloadUrl": "/api/compat/v1/download/my-skill/1.2.0"
|
||||
}
|
||||
```
|
||||
|
||||
### Download
|
||||
|
||||
```http
|
||||
GET /api/compat/v1/download/{slug}/{version}
|
||||
```
|
||||
|
||||
### Publish
|
||||
|
||||
```http
|
||||
POST /api/compat/v1/publish
|
||||
Content-Type: multipart/form-data
|
||||
|
||||
file: <zip-file>
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"slug": "my-skill",
|
||||
"version": "1.0.0",
|
||||
"status": "published"
|
||||
}
|
||||
```
|
||||
|
||||
## Coordinate Mapping
|
||||
|
||||
| SkillHub Coordinate | ClawHub canonical slug |
|
||||
|---------------------|------------------------|
|
||||
| `@global/my-skill` | `my-skill` |
|
||||
| `@team-name/my-skill` | `team-name--my-skill` |
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [System Architecture](../architecture/overview) - Understand architecture design
|
||||
|
|
@ -0,0 +1,86 @@
|
|||
---
|
||||
title: API Overview
|
||||
sidebar_position: 1
|
||||
description: SkillHub API overview
|
||||
---
|
||||
|
||||
# API Overview
|
||||
|
||||
SkillHub provides RESTful APIs for integration and automation.
|
||||
|
||||
## API Categories
|
||||
|
||||
### Public APIs
|
||||
- Skill search
|
||||
- Skill details
|
||||
- Version list
|
||||
- Download skills
|
||||
- No authentication required (for PUBLIC skills)
|
||||
|
||||
### Authenticated APIs
|
||||
- Publish skills
|
||||
- Favorites/ratings
|
||||
- Namespace management
|
||||
- Requires login or Bearer Token
|
||||
|
||||
### CLI Compatibility Layer
|
||||
- ClawHub CLI protocol compatible
|
||||
- Existing tools can migrate seamlessly
|
||||
|
||||
## Response Format
|
||||
|
||||
### Unified Response Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "Success",
|
||||
"data": {},
|
||||
"timestamp": "2026-03-15T06:00:00Z",
|
||||
"requestId": "req-123"
|
||||
}
|
||||
```
|
||||
|
||||
### Pagination Response
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "Success",
|
||||
"data": {
|
||||
"items": [],
|
||||
"total": 100,
|
||||
"page": 1,
|
||||
"size": 20
|
||||
},
|
||||
"timestamp": "2026-03-15T06:00:00Z",
|
||||
"requestId": "req-123"
|
||||
}
|
||||
```
|
||||
|
||||
## Authentication Methods
|
||||
|
||||
### Session Cookie
|
||||
Web side uses Session Cookie authentication.
|
||||
|
||||
### Bearer Token
|
||||
CLI and API integration use Bearer Token:
|
||||
|
||||
```bash
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### API Token
|
||||
Can create long-lived API Tokens for automation.
|
||||
|
||||
## Idempotency
|
||||
|
||||
All write operations support `X-Request-Id` header for idempotency:
|
||||
|
||||
```bash
|
||||
X-Request-Id: <uuid-v4>
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Public APIs](./public) - View public endpoints
|
||||
|
|
@ -0,0 +1,72 @@
|
|||
---
|
||||
title: Public APIs
|
||||
sidebar_position: 2
|
||||
description: Public APIs without authentication
|
||||
---
|
||||
|
||||
# Public APIs
|
||||
|
||||
## Skill Search
|
||||
|
||||
```http
|
||||
GET /api/v1/skills?keyword=...&namespace=...&page=1&size=20
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `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
|
||||
|
||||
- [Authenticated APIs](./authenticated) - View authenticated endpoints
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"label": "Architecture",
|
||||
"position": 2
|
||||
}
|
||||
|
|
@ -0,0 +1,77 @@
|
|||
---
|
||||
title: Domain Model
|
||||
sidebar_position: 2
|
||||
description: Core domain entities and relationships
|
||||
---
|
||||
|
||||
# Domain Model
|
||||
|
||||
## Core Entities
|
||||
|
||||
### Namespace
|
||||
|
||||
| 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 |
|
||||
| status | enum | `ACTIVE` / `FROZEN` / `ARCHIVED` |
|
||||
|
||||
### NamespaceMember
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| id | bigint | Primary key |
|
||||
| namespace_id | bigint | Namespace ID |
|
||||
| user_id | varchar(128) | User ID |
|
||||
| role | enum | `OWNER` / `ADMIN` / `MEMBER` |
|
||||
|
||||
### Skill
|
||||
|
||||
| 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 published version |
|
||||
|
||||
**Unique constraint**: `(namespace_id, slug)`
|
||||
|
||||
### SkillVersion
|
||||
|
||||
| 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 | File manifest |
|
||||
| parsed_metadata_json | json | SKILL.md parsed result |
|
||||
|
||||
**Unique constraint**: `(skill_id, version)`
|
||||
|
||||
### SkillTag
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| id | bigint | Primary key |
|
||||
| skill_id | bigint | Skill ID |
|
||||
| tag_name | varchar(64) | Tag name |
|
||||
| target_version_id | bigint | Target version |
|
||||
|
||||
**Unique constraint**: `(skill_id, tag_name)`
|
||||
|
||||
## Coordinate System
|
||||
|
||||
Full skill address: `@{namespace_slug}/{skill_slug}`
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Security Architecture](./security) - Security design
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
---
|
||||
title: System Architecture
|
||||
sidebar_position: 1
|
||||
description: SkillHub system architecture overview
|
||||
---
|
||||
|
||||
# System Architecture
|
||||
|
||||
## Architecture Principles
|
||||
|
||||
- **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/ # 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 → (independent)
|
||||
```
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Layer | Technology | Version |
|
||||
|-------|------------|---------|
|
||||
| Runtime | Java | 21 |
|
||||
| Framework | Spring Boot | 3.2.3 |
|
||||
| Database | PostgreSQL | 16.x |
|
||||
| Cache/Session | Redis | 7.x |
|
||||
|
||||
## Deployment Architecture
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ Browser / CLI│
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ Web/Nginx │
|
||||
└──────┬───────┘
|
||||
│ /api/*
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ Spring Boot │
|
||||
└───┬────┬─────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
PostgreSQL Redis
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Domain Model](./domain-model) - Core entities
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
---
|
||||
title: Security Architecture
|
||||
sidebar_position: 3
|
||||
description: Security architecture design
|
||||
---
|
||||
|
||||
# Security Architecture
|
||||
|
||||
## Authentication Architecture
|
||||
|
||||
### OAuth2 Login
|
||||
|
||||
- Based on Spring Security OAuth2 Client
|
||||
- Phase 1 supports GitHub
|
||||
- Architecture supports extending multiple providers
|
||||
|
||||
### CLI Authentication
|
||||
|
||||
- OAuth Device Flow
|
||||
- Web authorization issues CLI credentials
|
||||
- Supports API Token
|
||||
|
||||
### Session Management
|
||||
|
||||
- Spring Session + Redis
|
||||
- Distributed session sharing
|
||||
- Supports multi-pod deployment
|
||||
|
||||
## Authorization Architecture
|
||||
|
||||
### Platform Roles
|
||||
|
||||
| Role | Permissions |
|
||||
|------|-------------|
|
||||
| `SUPER_ADMIN` | All permissions |
|
||||
| `SKILL_ADMIN` | Skill governance |
|
||||
| `USER_ADMIN` | User governance |
|
||||
| `AUDITOR` | Audit read-only |
|
||||
|
||||
### Namespace Roles
|
||||
|
||||
| Role | Permissions |
|
||||
|------|-------------|
|
||||
| `OWNER` | Namespace owner |
|
||||
| `ADMIN` | Review, member management |
|
||||
| `MEMBER` | Publish skills |
|
||||
|
||||
### Visibility Rules
|
||||
|
||||
| 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 layer basic rate limiting (Nginx)
|
||||
- Application layer fine-grained rate limiting (Redis sliding window)
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Skill Protocol](../plugins/skill-protocol) - Skill package specification
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"label": "Extensions & Integrations",
|
||||
"position": 3
|
||||
}
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
---
|
||||
title: Skill Protocol
|
||||
sidebar_position: 1
|
||||
description: SKILL.md specification and skill package protocol
|
||||
---
|
||||
|
||||
# Skill Protocol
|
||||
|
||||
## SKILL.md Specification
|
||||
|
||||
### Basic Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: When to use this skill
|
||||
---
|
||||
|
||||
# Markdown Body
|
||||
|
||||
Skill instruction content...
|
||||
```
|
||||
|
||||
### Required Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `name` | Skill identifier, kebab-case |
|
||||
| `description` | Brief skill description |
|
||||
|
||||
### Extension Fields
|
||||
|
||||
| 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 # Main entry file (required)
|
||||
├── references/ # References (optional)
|
||||
├── scripts/ # Scripts (optional)
|
||||
└── assets/ # Static assets (optional)
|
||||
```
|
||||
|
||||
## File Validation
|
||||
|
||||
- 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
|
||||
|
||||
- [Storage SPI](./storage-spi) - Extend storage backend
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
title: Storage SPI
|
||||
sidebar_position: 2
|
||||
description: Storage service provider extension
|
||||
---
|
||||
|
||||
# Storage SPI
|
||||
|
||||
## SPI Interface
|
||||
|
||||
```java
|
||||
public interface ObjectStorageService {
|
||||
void store(String key, InputStream content, String contentType);
|
||||
InputStream retrieve(String key);
|
||||
void delete(String key);
|
||||
boolean exists(String key);
|
||||
}
|
||||
```
|
||||
|
||||
## Built-in Implementations
|
||||
|
||||
### LocalFileStorageService
|
||||
|
||||
Local filesystem implementation for development environment.
|
||||
|
||||
### S3StorageService
|
||||
|
||||
S3 protocol compatible implementation, supports:
|
||||
- AWS S3
|
||||
- MinIO
|
||||
- Alibaba Cloud OSS
|
||||
- Tencent Cloud COS
|
||||
- Other S3-compatible storage
|
||||
|
||||
## Configuration
|
||||
|
||||
```bash
|
||||
# Select storage provider
|
||||
SKILLHUB_STORAGE_PROVIDER=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
|
||||
```
|
||||
|
||||
## Custom Implementation
|
||||
|
||||
Implement `ObjectStorageService` interface and register as Spring Bean.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [FAQ](../../05-reference/faq) - FAQ
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
title: Changelog
|
||||
sidebar_position: 3
|
||||
description: Version change history
|
||||
---
|
||||
|
||||
# Changelog
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
- Initial version release
|
||||
- Skill publishing and management
|
||||
- Namespace and RBAC
|
||||
- Full-text search
|
||||
- ClawHub CLI compatibility layer
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Roadmap](./roadmap) - Future plans
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
title: FAQ
|
||||
sidebar_position: 1
|
||||
description: Frequently asked questions
|
||||
---
|
||||
|
||||
# FAQ
|
||||
|
||||
## Deployment Related
|
||||
|
||||
### How to change default port?
|
||||
|
||||
Modify port configuration in `.env.release`.
|
||||
|
||||
### How to configure HTTPS?
|
||||
|
||||
Recommended to use reverse proxy (Nginx/Ingress) for TLS termination.
|
||||
|
||||
### How to backup database?
|
||||
|
||||
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?
|
||||
|
||||
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
|
||||
|
||||
### How to extend OAuth Provider?
|
||||
|
||||
Refer to existing GitHub implementation, add new OAuth Provider configuration.
|
||||
|
||||
### How to customize search implementation?
|
||||
|
||||
Implement `SearchIndexService` and `SearchQueryService` interfaces.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Troubleshooting](./troubleshooting) - Problem diagnosis
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
title: Roadmap
|
||||
sidebar_position: 4
|
||||
description: Future development roadmap
|
||||
---
|
||||
|
||||
# Roadmap
|
||||
|
||||
## Phase 1: Foundation ✅
|
||||
|
||||
- GitHub OAuth login
|
||||
- Session management
|
||||
- RBAC permission system
|
||||
|
||||
## Phase 2: Skill Core ✅
|
||||
|
||||
- Namespace management
|
||||
- Skill publishing and download
|
||||
- Version management
|
||||
- PostgreSQL full-text search
|
||||
|
||||
## Phase 3: Review and CLI
|
||||
|
||||
- Review workflow
|
||||
- Skill promotion to global
|
||||
- CLI tool
|
||||
- Favorites and ratings
|
||||
|
||||
## Phase 4: Operations and Polish
|
||||
|
||||
- Audit logs
|
||||
- Admin dashboard
|
||||
- Observability
|
||||
- Deployment optimization
|
||||
|
||||
## Phase 5: Advanced Features
|
||||
|
||||
- Comments and reports
|
||||
- Automatic security scanning
|
||||
- Vector search
|
||||
- Webhook notifications
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Quick Start](../../01-getting-started/quick-start) - Get started
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
title: Troubleshooting
|
||||
sidebar_position: 2
|
||||
description: Common problem diagnosis and solutions
|
||||
---
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
## Service Cannot Start
|
||||
|
||||
### Checklist
|
||||
|
||||
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
|
||||
|
||||
- Port occupied
|
||||
- Database connection failed
|
||||
- Redis connection failed
|
||||
- Environment variables missing
|
||||
|
||||
## Upload Failed
|
||||
|
||||
### Skill Package Upload Failed
|
||||
|
||||
1. Check file size
|
||||
2. Check file type
|
||||
3. Check SKILL.md format
|
||||
4. View server logs
|
||||
|
||||
## Authentication Issues
|
||||
|
||||
### Cannot Login
|
||||
|
||||
1. Check OAuth configuration
|
||||
2. Check callback URL configuration
|
||||
3. Check `SKILLHUB_PUBLIC_BASE_URL` configuration
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Slow Search
|
||||
|
||||
1. Check PostgreSQL full-text index
|
||||
2. Consider upgrading to Elasticsearch (future version)
|
||||
|
||||
### Slow Download
|
||||
|
||||
1. Check object storage configuration
|
||||
2. Check network bandwidth
|
||||
|
||||
## Get Help
|
||||
|
||||
If above solutions cannot resolve the issue:
|
||||
1. View logs
|
||||
2. Submit Issue
|
||||
3. Contact technical support
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Changelog](./changelog) - Version history
|
||||
|
|
@ -15,8 +15,8 @@
|
|||
"typecheck": "tsc"
|
||||
},
|
||||
"dependencies": {
|
||||
"@docusaurus/core": "3.4.0",
|
||||
"@docusaurus/preset-classic": "3.4.0",
|
||||
"@docusaurus/core": "^3.9.2",
|
||||
"@docusaurus/preset-classic": "^3.9.2",
|
||||
"@mdx-js/react": "^3.0.0",
|
||||
"clsx": "^2.0.0",
|
||||
"prism-react-renderer": "^2.3.0",
|
||||
|
|
@ -24,9 +24,9 @@
|
|||
"react-dom": "^18.2.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@docusaurus/module-type-aliases": "3.4.0",
|
||||
"@docusaurus/tsconfig": "3.4.0",
|
||||
"@docusaurus/types": "3.4.0",
|
||||
"@docusaurus/module-type-aliases": "^3.9.2",
|
||||
"@docusaurus/tsconfig": "^3.9.2",
|
||||
"@docusaurus/types": "^3.9.2",
|
||||
"typescript": "~5.2.2"
|
||||
},
|
||||
"browserslist": {
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue