docs: refresh bilingual user and operator guides

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
This commit is contained in:
XiaoSeS 2026-10-28 15:18:56 +08:00
parent daee5efd6a
commit 8265491de8
38 changed files with 818 additions and 971 deletions

View file

@ -62,9 +62,13 @@ with the Skill's source and the problem it solves, or submit a PR by following t
## Documentation
- 📖 **[User Guide](https://iflytek.github.io/skillhub/)** — Skill publishing, search, CLI usage and other user guides
- 🛠️ **[Developer Docs](https://zread.ai/iflytek/skillhub)** — Architecture, API reference, local development, deployment and operations
- 🐍 **[Python Examples](./examples/python)** — Search, download, and publish skills from Python via the REST API
- **[User Guide](https://iflytek.github.io/skillhub/)** — [中文](docs/skillhub/quickstart.md) / [English](docs/skillhub/en/quickstart.md): find, install, and use skills in your agent
- **[CLI reference](cli/README.md)** — Authentication, installation, upgrades, namespace synchronization, and local inventory
- **[Skill Suites](docs/skillhub/en/guide/skill-suites.md)** — Install a versioned collection and use its entry skill; [Suite Bundle import](docs/skillhub/en/guide/suite-bundle.md) is the separate authoring workflow
- **[Self-hosting](docs/skillhub/en/guide/deployment.md)** — Docker Compose configuration and upgrades; [Kubernetes](docs/skillhub/en/guide/kubernetes.md) for clusters
- **[Developer workflow](docs/dev-workflow.md)** — Source development, checks, and documentation maintenance; [operations reference](docs/09-deployment.md) for deployment details
- **[Generated code overview](https://zread.ai/iflytek/skillhub)** — Supplementary architecture exploration; repository source and versioned documentation define current behavior
- **[Python Examples](./examples/python)** — Search, download, and publish skills via the REST API
## Governance and Safety
@ -111,7 +115,7 @@ with the Skill's source and the problem it solves, or submit a PR by following t
## Quick Start
Start the full local stack with:
To host your own registry using release images, start with:
```bash
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up
@ -172,7 +176,9 @@ skillhub list
### Prerequisites
- Docker & Docker Compose
- Docker & Docker Compose for container dependencies and release deployments
- For source development: Java 21, Node.js 22.13+ (22.x) or 24.x, and the pnpm version declared in `web/package.json`
- For CLI development: Bun (see [`cli/README.md`](cli/README.md))
### Local Development
@ -180,7 +186,7 @@ skillhub list
make dev-all
```
> **For developers in China**: If Maven dependency download times out, configure Aliyun mirror. See [Local Development Guide](https://iflytek.github.io/skillhub/quickstart.html#本地开发) for details.
> **For developers in China**: If Maven dependency download times out, configure Aliyun mirror. See [Local Development Guide](docs/dev-workflow.md) for details.
Then open:
@ -208,7 +214,7 @@ Stop everything with:
make dev-all-down
```
Reset local dependencies and start from a clean slate with:
Only when deliberately discarding local dependency data, reset with:
```bash
make dev-all-reset
@ -366,23 +372,18 @@ allowlist instead of appending to it.
### Monitoring
A Prometheus + Grafana monitoring stack lives under [`monitoring/`](./monitoring).
It scrapes the backend's Actuator Prometheus endpoint.
The optional [`monitoring/`](./monitoring) directory provides Prometheus and Grafana deployment examples. It is not a ready-to-scrape backend configuration: the default application exposes only `health` and `info` Actuator endpoints. `/actuator/prometheus` also requires the `SUPER_ADMIN` or `AUDITOR` role under the current route policy, while the example scraper has no credentials configured.
Start it with:
Before enabling monitoring, configure metrics exposure and an authenticated access path appropriate to your deployment; verify that the scraper can actually read the endpoint. Do not make management endpoints public merely to satisfy the example. The example targets `host.docker.internal:8080`, which must resolve to your backend from the Prometheus container.
After adapting that configuration, start the optional stack:
```bash
cd monitoring
docker compose -f docker-compose.monitoring.yml up -d
```
Then open:
- Prometheus: `http://localhost:9090`
- Grafana: `http://localhost:3001` (`admin` / `admin`)
By default Prometheus scrapes `http://host.docker.internal:8080/actuator/prometheus`,
so start the backend locally on port `8080` first.
Prometheus uses port `9090` and Grafana uses port `3001`. Replace the example Grafana administrator credentials before exposing it. Confirm scrape targets are healthy and metrics are present; starting the containers alone does not establish monitoring coverage. For tracing and request correlation, see the [observability developer guide](docs/observability-developer-guide.md).
## Kubernetes

View file

@ -354,6 +354,19 @@ Workspace push is non-overwriting: an existing namespace/slug/version is reporte
Namespace sync writes `.skillhub/namespace-sync.json` in the workspace and per-skill `.skillhub/metadata.json` files. These files contain the registry coordinate, published version, aggregate fingerprint, and file hashes used by `status` and `diff`.
## Using installed skills and Suites
Installation downloads Skill files; it does not execute a task. Open the target project in your Agent, verify it discovers `SKILL.md`, configure the documented dependencies, and ask it to use the Skill. See the [Suite usage guide](../docs/skillhub/en/guide/skill-suites.md).
```bash
# Replace with a real Suite coordinate
skillhub suite install @team/example-suite --scope project --agent codex
skillhub suite check @team/example-suite
skillhub suite upgrade @team/example-suite --check
skillhub suite upgrade @team/example-suite
skillhub suite remove @team/example-suite
```
## 📋 Local Management
### List Installed Skills
@ -420,7 +433,7 @@ skillhub doctor
3. Backs up old `inventory.json` (if exists)
4. Writes new `inventory.json`
If the same skill has version conflicts across different targets, that skill will be skipped and reported.
Versions are tracked per target. Doctor reports recovery problems; it does not download or upgrade skills.
## 🚢 Publishing
@ -494,6 +507,7 @@ Update mechanism:
| `skillhub publish <path> [--namespace <slug>] [--visibility <v>] [--registry <url>] [--token <token>] [--json]` | Publish a skill |
| `skillhub sync pull --namespace <slug> [--skill <slug>]... [options]` | Pull explicitly selected skills from a non-global namespace |
| `skillhub sync <status\|diff\|push> --namespace <slug> [options]` | Inspect or push a non-global namespace workspace |
| `skillhub suite <install\|check\|upgrade\|remove> <coordinate> [options]` | Manage a pinned Skill Suite installation |
| `skillhub update [--check] [--json]` | Check or execute CLI self-update |
## 🔒 Security Notes
@ -528,7 +542,7 @@ request ID when asking a registry operator to investigate.
```bash
# Check if registry is accessible
curl https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1
curl 'https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1'
# Use alternative registry
skillhub search test --registry https://skillhub.example.com

View file

@ -4,7 +4,7 @@
## 1 运行模型
当前仓库只保留两种运行方式:
按用途选择运行方式;以下重点介绍源码开发和单机交付,Kubernetes 另见[部署指南](skillhub/guide/kubernetes.md):
- 开发环境:`make dev-all`
- 前端和后端运行在宿主机
@ -16,7 +16,7 @@
`linux/riscv64`,`scanner` 暂保持 `linux/amd64` 与 `linux/arm64`
- PostgreSQL、Redis 与应用容器一起通过 Compose 启动
不再维护本地构建整套 demo 容器的中间模式,也不再保留 `docker-compose.prod.yml`。
`make staging` 仍用于从源码构建的容器回归验证,见[开发工作流](dev-workflow.md),不等同于正式交付。正式单机部署使用 `compose.release.yml`,不使用 `docker-compose.prod.yml`。
## 2 单机交付拓扑
@ -110,6 +110,7 @@ make dev-github-sync
```bash
cp .env.release.example .env.release
# 编辑 .env.release:设置数据库/管理员密码、公开地址、存储和固定镜像版本
make validate-release-config
docker compose --env-file .env.release -f compose.release.yml up -d
```

35
docs/README.md Normal file
View file

@ -0,0 +1,35 @@
# Documentation map
Use the documentation site for user workflows, repository guides for engineering and operations, and source/tests for exact current behavior. Numbered design documents are not a chronological tutorial or a promise that every proposed feature is implemented.
## Users and authors
| Task | 中文 | English |
| --- | --- | --- |
| Install and use your first skill | [快速开始](skillhub/quickstart.md) | [Quick Start](skillhub/en/quickstart.md) |
| CLI authentication, install, upgrade and sync | [CLI](skillhub/guide/cli.md) | [CLI](skillhub/en/guide/cli.md) |
| Install and use a versioned collection | [技能套装](skillhub/guide/skill-suites.md) | [Skill Suites](skillhub/en/guide/skill-suites.md) |
| Upload a collection and member packages | [Bundle 导入](skillhub/guide/suite-bundle.md) | [Bundle import](skillhub/en/guide/suite-bundle.md) |
| Publish skills and track versions | [发布](skillhub/guide/skill-publish.md) | [Publishing](skillhub/en/guide/skill-publish.md) |
| Manage access and review | [命名空间](skillhub/guide/namespace.md) · [审核](skillhub/guide/review.md) | [Namespaces](skillhub/en/guide/namespace.md) · [Review](skillhub/en/guide/review.md) |
| Troubleshoot | [FAQ](skillhub/faq.md) | [FAQ](skillhub/en/faq.md) |
## Operators
- [Docker deployment and upgrades](skillhub/en/guide/deployment.md) / [中文](skillhub/guide/deployment.md)
- [Kubernetes](skillhub/en/guide/kubernetes.md) / [中文](skillhub/guide/kubernetes.md)
- [Deployment reference](09-deployment.md), [object storage](object-storage.md), [SMTP and password reset](19-smtp-password-reset-email-setup.md)
- [Security scanning](security-scanning.md), [observability](observability-developer-guide.md), [private SSO integration](12-private-sso-integration-playbook.md)
## Contributors and integrators
- [Contributing](../CONTRIBUTING.md), [development workflow](dev-workflow.md), [engineering specs](../.trellis/spec/index.md)
- [System architecture](01-system-architecture.md), [domain model](02-domain-model.md), [API design](06-api-design.md)
- [Skill package protocol](07-skill-protocol.md), [lifecycle contract](14-skill-lifecycle.md), [Suite semantics](25-skill-suites.md), [authoring drafts](27-authoring-drafts.md)
- [Runtime integration](skillhub/en/guide/runtime-integration.md), [OpenClaw](openclaw-integration-en.md), [Hermes](hermes-integration-en.md), [DeepSeek Harness](dsh-integration-en.md)
## Plans and historical evidence
Roadmaps, files titled `plan`, dated design proposals, research under `research/`, and test reports record decisions or evidence at a point in time. Check their implementation status against current code before treating them as supported features. Examples include the [delivery roadmap](10-delivery-roadmap.md), [starter skills plan](21-official-starter-skills-plan.md), and [observability construction plan](2026-07-31-observability-construction-plan.md).
For documentation changes, update both language journeys and navigation, verify commands against the source, then run `npm ci` and `npm run build` from `docs/skillhub`. A documentation build checks rendering and links, not deployment or live registry behavior.

View file

@ -6,7 +6,8 @@ This document describes the recommended workflow for developing SkillHub locally
- Docker Desktop (for dependency services and staging)
- Java 21 (for running the backend locally)
- Node.js 22 + pnpm (for running the frontend locally)
- Node.js 22.13+ (22.x) or 24.x, and the pnpm version declared in `web/package.json` (frontend)
- Bun for CLI development; see [`cli/README.md`](../cli/README.md)
- `gh` CLI (for creating pull requests): https://cli.github.com/
## Stage 1: Local Development (fast iteration)
@ -38,7 +39,7 @@ After editing backend code, restart the backend explicitly:
make dev-server-restart
```
If you are running the server in a foreground terminal instead of `make dev-all`, stop it and run `make dev-server` again. Expect a full restart in about 5-10 seconds, including rebuilding the backend modules.
If you are running the server in a foreground terminal instead of `make dev-all`, stop it and run `make dev-server` again. This rebuilds the backend modules before restart; duration depends on the machine and dependency cache.
### Mock authentication
@ -178,3 +179,16 @@ make staging # regression test in Docker
make staging-down # stop staging
make pr # push + create PR
```
## Documentation changes
The bilingual user-facing site lives in `docs/skillhub`; architecture and operator references live directly under `docs`. Keep Chinese and English workflows aligned and update the VitePress navigation when adding pages. Verify commands against the current source, not only older guides.
```bash
# Install site dependencies from the repository lockfile
npm --prefix docs/skillhub ci
make docs-build
make docs-preview
```
The site build checks internal links. Preview changed pages to check navigation, tables, and code blocks. Documentation-only changes do not require starting the application stack.

View file

@ -33,6 +33,7 @@ export default defineConfig({
items: [
{ text: '项目简介', link: '/introduction' },
{ text: '快速开始', link: '/quickstart' },
{ text: 'CLI 使用指南', link: '/guide/cli' },
],
},
{
@ -40,6 +41,7 @@ export default defineConfig({
items: [
{ text: 'Skill 发布与版本管理', link: '/guide/skill-publish' },
{ text: '技能头像与图片审核接入', link: '/guide/skill-avatars' },
{ text: '技能套装:安装与使用', link: '/guide/skill-suites' },
{ text: 'Suite Bundle 批量导入', link: '/guide/suite-bundle' },
{ text: 'Skill 搜索与发现', link: '/guide/skill-discovery' },
{ text: '命名空间与团队管理', link: '/guide/namespace' },
@ -52,6 +54,7 @@ export default defineConfig({
{
text: '更多',
items: [
{ text: 'Docker 部署与升级', link: '/guide/deployment' },
{ text: 'Kubernetes 部署', link: '/guide/kubernetes' },
{ text: '常见问题', link: '/faq' },
],
@ -82,12 +85,14 @@ export default defineConfig({
items: [
{ text: 'Introduction', link: '/en/introduction' },
{ text: 'Quick Start', link: '/en/quickstart' },
{ text: 'CLI Guide', link: '/en/guide/cli' },
],
},
{
text: 'Core Features',
items: [
{ text: 'Skill Publishing & Versioning', link: '/en/guide/skill-publish' },
{ text: 'Skill Suites: Install & Use', link: '/en/guide/skill-suites' },
{ text: 'Suite Bundle Import', link: '/en/guide/suite-bundle' },
{ text: 'Skill Search & Discovery', link: '/en/guide/skill-discovery' },
{ text: 'Namespace & Team Management', link: '/en/guide/namespace' },
@ -100,6 +105,7 @@ export default defineConfig({
{
text: 'More',
items: [
{ text: 'Docker Deployment & Upgrades', link: '/en/guide/deployment' },
{ text: 'Kubernetes Deployment', link: '/en/guide/kubernetes' },
{ text: 'FAQ', link: '/en/faq' },
],

View file

@ -2,41 +2,15 @@
## Q: What is the difference between SkillHub and ClawHub?
A: SkillHub is an enterprise-grade, self-hosted solution that provides stronger access control, review mechanisms, and governance capabilities. ClawHub is a public registry, similar to npm.
**Key Differences**:
| Feature | SkillHub | ClawHub |
|------|----------|---------|
| **Deployment** | Self-hosted | Public cloud |
| **Access Control** | Namespace RBAC | Basic permissions |
| **Review Mechanism** | Multi-level review | None |
| **Security Scanning** | Built-in Skill Scanner | None |
| **Data Sovereignty** | Fully self-managed | Hosted in the cloud |
| **Use Case** | Enterprise internal | Public sharing |
A: SkillHub provides a self-hosted registry, namespace permissions, publication review, scanning and audit. Third-party capabilities change; do not assume another service lacks review or scanning. See [OpenClaw integration](https://github.com/iflytek/skillhub/blob/main/docs/openclaw-integration-en.md) for compatibility.
## Q: How do I back up data?
A: SkillHub stores data in PostgreSQL and object storage. Regularly backing up these two components is sufficient.
**Back up PostgreSQL**:
```bash
pg_dump -h localhost -U postgres skillhub > backup.sql
```
**Back up Object Storage**:
- If using MinIO, back up the MinIO data directory
- If using S3, use the AWS CLI or an S3 backup tool
A: Back up PostgreSQL, the configured skill storage, and deployment configuration. Release Compose defaults to local storage in the `skillhub_storage` volume; S3 deployments need the corresponding bucket/objects. Keep database and object snapshots consistent and verify restoration in an isolated environment. See [deployment](./guide/deployment.md).
## Q: What authentication methods are supported?
A: SkillHub supports multiple authentication methods:
- **OAuth2**: GitHub, Google, GitLab, etc.
- **Local Accounts**: Username/password login (built-in administrator: admin / ChangeMe!2026)
- **Enterprise SSO**: Integrates with LDAP, SAML, etc.
Refer to the authentication configuration section in the project README for setup instructions.
A: Local accounts and configured OAuth2 providers are supported. Preset registrations include GitHub, GitLab, Feishu, and DingTalk; the login page and `/api/v1/auth/methods` describe available methods on your instance. Extensibility does not mean LDAP/SAML are built in. See the [private SSO contract](https://github.com/iflytek/skillhub/blob/main/docs/11-auth-extensibility-and-private-sso.md).
## Q: Is there a size limit for skill packages?
@ -49,60 +23,31 @@ spring:
multipart:
max-file-size: 100MB
max-request-size: 100MB
skillhub:
publish:
max-package-size: 104857600
```
Also check proxy body and Scanner upload limits; multipart settings alone do not bypass package validation.
## Q: How do I use the CLI tool to manage skill packages?
A: SkillHub is compatible with the OpenClaw CLI. Use the `npx clawhub` command to interact with it:
A: Use the first-party CLI:
```bash
# Configure the registry URL
export CLAWHUB_REGISTRY=http://your-skillhub-host:8080
# Search for skill packages
npx clawhub search email
# Install a skill package
npx clawhub install my-skill
# Publish a skill package (the ClawHub CLI publishing protocol is not compatible)
export SKILLHUB_REGISTRY=http://your-skillhub-host:8080
export SKILLHUB_TOKEN=YOUR_API_TOKEN
npx @astron-team/skillhub@latest publish ./my-skill
npm install -g @astron-team/skillhub
skillhub search pdf
```
Follow [Quick Start](./quickstart.md) to select a registry, scope, and Agent. Publishing and restricted resources require login. See [OpenClaw integration](https://github.com/iflytek/skillhub/blob/main/docs/openclaw-integration-en.md) for compatibility boundaries; do not mix its publish protocol with SkillHub CLI.
## Q: How do I configure HTTPS?
A: For production environments, it is recommended to use Nginx or Traefik as a reverse proxy with SSL certificates.
**Nginx Configuration Example**:
```nginx
server {
listen 443 ssl;
server_name skillhub.example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:3000;
}
location /api {
proxy_pass http://localhost:8080;
}
}
```
A: Terminate TLS at an external proxy forwarding to the published Web port (`WEB_PORT=80` by default in release Compose). Web already proxies backend routes. Set the real `SKILLHUB_PUBLIC_BASE_URL`, preserve the original Host and forwarded protocol, and validate login and cookies. See [deployment](./guide/deployment.md).
## Q: How do I monitor SkillHub?
A: SkillHub provides several monitoring options:
- **Health Check**: `GET /actuator/health`
- **Scanner Health Check**: `GET http://localhost:8000/health`
- **Metrics**: `GET /actuator/metrics` (Prometheus format)
- **Audit Logs**: All critical operations are recorded in the audit log
- **Application Logs**: Collect logs using ELK or Loki
A: The base configuration exposes `/actuator/health` and `/actuator/info`. `/actuator/metrics` is not the Prometheus text endpoint; neither that endpoint nor Prometheus export is enabled by default in the base configuration. Correlate logs and audit events using `requestId`. See the [observability guide](https://github.com/iflytek/skillhub/blob/main/docs/observability-developer-guide.md) for explicit integration configuration.
## Q: Does it support multi-tenancy?
@ -112,47 +57,19 @@ For physical isolation, you can deploy a separate SkillHub instance for each ten
## Q: How do I upgrade SkillHub?
A: Use the curl command to upgrade:
```bash
# Pull the latest images and restart
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- pull
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- down
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up
# Or upgrade to a specific version
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version v0.2.0
```
> **Note**: It is recommended to back up the database and object storage before upgrading. Database migrations are handled automatically by Flyway. Upgrading does not wipe the database, so already-registered skill packages will not be lost.
A: Follow the [deployment guide](./guide/deployment.md), select a target version, and back up the database, skill storage, and configuration. After upgrading, verify health, login, and representative skill operations. Flyway migrations mean that rolling back an image alone is not necessarily a database rollback.
## Q: Why can't administrators (admin) and regular users create namespaces?
A: Older versions of SkillHub do not support creating namespaces, as this feature was introduced in later updates. Please upgrade your SkillHub instance to the latest version (`latest`).
Upgrade command example:
```bash
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version latest
```
A: Inspect the actual error and `requestId`, then check permissions, name validation, and instance restrictions. Do not assume an old version is the cause. See [namespace management](./guide/namespace.md).
## Q: How do I search for or operate on a skill package within a specific namespace?
A: When using the OpenClaw CLI, you can specify the namespace using the `<namespace>--<skill-name>` format for operations like search or installation. If you encounter issues finding it on the web interface, you can also manage it by exporting the skill package and importing it into your target namespace.
A: Select the namespace in the UI. To install with the CLI, use `skillhub install @team/example-skill`, replacing the coordinate with a real resource. `skillhub search` searches skills; `skillhub suite install` installs suites. Exporting and reimporting is not a search troubleshooting step.
## Q: What is the recommended deployment method? Can I pull the images and deploy manually?
A: We recommend the official one-line deployment script. Pulling images and deploying manually is not recommended because it is prone to database initialization, dependency-order, and login redirect issues. By default, dependencies come from public registries, and the SkillHub application images come from GHCR:
```bash
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --public-url https://skillhub.your-company.com
```
If GHCR is unreachable from China, use the Aliyun mirror:
```bash
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --public-url https://skillhub.your-company.com --version latest
```
The script performs a series of initialization steps. The generated runtime configuration is located at `/tmp/skillhub-runtime/` by default (containing `.env.release` and the docker-compose file).
A: Official runtime scripts, release Compose, and Kubernetes/Helm are supported. Choose one and retain its configuration and data directories. See [Docker deployment](./guide/deployment.md) and [Kubernetes](./guide/kubernetes.md). Running an application image alone does not configure its database, Redis, storage, authentication, or proxy.
## Q: What Kubernetes version does the Kubernetes deployment require?
@ -160,39 +77,23 @@ A: The official [Kubernetes deployment guide](./guide/kubernetes.md) requires Ku
## Q: After deployment, I enter the correct username and password but get redirected back to the login page?
A: This is most commonly seen with **manual deployment** (caused by API errors or incomplete initialization). Suggestions:
1. Switch to the one-line script above for deployment.
2. If necessary, clear and recreate the PostgreSQL data volume, then log in again.
3. If a reverse proxy is in front, verify that it forwards requests correctly.
A: Inspect the login and subsequent identity requests in browser developer tools. Check the public URL, proxy forwarding, cookies, and backend session configuration, then correlate `requestId` with server logs. This symptom alone does not identify a password or database failure. Do not clear PostgreSQL volumes as a login troubleshooting step. See [deployment](./guide/deployment.md).
## Q: How do I change the admin password? Why don't my config changes take effect?
A: Environment variables are injected when a container is created, so you must recreate the containers after changing them; `restart` alone does not re-inject environment variables.
1. Edit `/tmp/skillhub-runtime/.env.release` in the runtime directory (refer to [.env.release.example](https://github.com/iflytek/skillhub/blob/main/.env.release.example)).
2. Recreate the relevant containers:
```bash
docker compose \
--env-file /tmp/skillhub-runtime/.env.release \
-f /tmp/skillhub-runtime/compose.release.yml \
up -d --force-recreate
```
3. If the password was already persisted to the database and the change still doesn't take effect, you may need to clear the corresponding data and re-initialize.
A: `BOOTSTRAP_ADMIN_PASSWORD` initializes an account. `BootstrapAdminInitializer` preserves existing credentials, so changing this variable or recreating containers does not reset an existing password. Use the instance password-change/reset flow and configure SMTP for email verification. Do not delete users or database contents to reinitialize credentials.
## Q: Is an email verification code required to change / reset a password?
A: Yes. By default, passwords are changed or reset via an email verification code, so SMTP must be configured first. See [docs/19-smtp-password-reset-email-setup.md](https://github.com/iflytek/skillhub/blob/main/docs/19-smtp-password-reset-email-setup.md). Administrators can also reset it via `.env.release`.
A: The current password-change/reset flow uses email verification and requires [SMTP configuration](https://github.com/iflytek/skillhub/blob/main/docs/19-smtp-password-reset-email-setup.md). Bootstrap environment variables do not reset existing passwords.
## Q: Can a skill have a Chinese name?
A: Skill names are generally in English; Chinese names are not currently supported (using a Chinese skill name in OpenClaw will cause an error).
A: The `name`/slug remains a validated identifier. The user-facing display name supports Chinese through `metadata.display-name`. Changing it does not change the coordinate or installation directory. See [publishing](./guide/skill-publish.md).
## Q: Can unreviewed skills be downloaded?
A: As long as you have permission to view it, it can generally be downloaded.
A: Normal installation requires a published version that the caller can access. Visibility of a detail page does not grant downloads for every version state. Author/reviewer preview permissions differ from distribution permissions. See [review](./guide/review.md).
## Q: How do I hide or remove third-party SSO login options on the login page?
@ -270,7 +171,7 @@ Recreate the containers for the change to take effect; `restart` alone does not
## Q: Is there a server version requirement for using the CLI (publish / download, etc.)?
A: A SkillHub server image of **v0.2.7 or later** is required for CLI features.
A: Compatibility depends on the command. Basic CLI support does not imply support for Device Flow, Suites or sync. Check CLI version and target-server release notes. Suites require the server to advertise `skill-suite-v1`. See [CLI](./guide/cli.md).
## Q: Does SkillHub support MySQL?
@ -369,21 +270,7 @@ A `USER_ADMIN` can manage user status and assign platform roles other than `SUPE
## Q: How do I install multiple skills in bulk?
A: The CLI `install` command handles one skill at a time. Both examples below use `--dir` to install the skills under the same target root; each skill is placed in `$target_dir/<skill-slug>/`:
```bash
target_dir=/opt/skillhub-skills
# install one by one
for skill in skill-a skill-b skill-c; do
skillhub install "$skill" --dir "$target_dir"
done
# or read from a manifest file (one skill name per line)
xargs -a skills.txt -I {} skillhub install "{}" --dir "$target_dir"
```
Since **SkillHub Server v0.2.12**, public skills support anonymous search and install. Note that an invalid bearer token now fails the command instead of falling back to anonymous access — update or remove the stale credential in that case.
A: Use [Suites](./guide/skill-suites.md) and `skillhub suite install` for pinned members managed together, `skillhub sync pull` for team workspaces, or separate `skillhub install` commands for unrelated skills. Suite Bundle is an authoring import format, not a local installation command.
## Q: What should I do if I encounter issues?
@ -452,7 +339,7 @@ java -version
lsof -i :8080
# Terminate the process
kill -9 <PID>
# Identify the process owner and stop it through its service manager
```
### 4. View detailed logs

View file

@ -19,7 +19,7 @@ bun add -g @astron-team/skillhub
```bash
# Login
skillhub login --token sk_xxx
skillhub login
# Search skills
skillhub search pdf
@ -73,6 +73,8 @@ Token resolution priority:
### Login
Without a token, `skillhub login` uses OAuth Device Flow: follow the verification URL and user code to authorize in a browser. Use `skillhub login --no-open` on headless terminals, or an API token for automation.
```bash
# Login with API token
skillhub login --token sk_xxx
@ -266,14 +268,38 @@ skillhub upgrade @team/code-review --check --json
`--force`; it only replaces a managed installation whose full `registry + namespace + slug` source
matches.
All targets in one inventory entry are upgraded together. A filter that selects only part of that
entry is rejected because the current inventory format stores one shared version for all targets.
Versions are tracked per target. `--agent` and `--dir` select installed targets; Suite-owned targets are protected from direct upgrade and should use `suite upgrade`.
The command also keeps the local files when the registry resolves to an older version.
If a multi-Skill run fails after an earlier upgrade commits, execution stops and reports each item
as `upgraded`, `failed`, or `not-attempted`; a committed upgrade is never rolled back implicitly.
New installations store absolute target paths. Reinstall an older entry that still contains relative
target paths before upgrading it; the CLI cannot safely infer the original working directory.
## Using installed skills and Suites
Installation downloads Skill files; it does not execute a task. Open the target project in your Agent, verify it discovers `SKILL.md`, configure the documented dependencies, and ask it to use the Skill. See the [Suite usage guide](./skill-suites).
```bash
# Replace with a real Suite coordinate
skillhub suite install @team/example-suite --scope project --agent codex
skillhub suite check @team/example-suite
skillhub suite upgrade @team/example-suite --check
skillhub suite upgrade @team/example-suite
skillhub suite remove @team/example-suite
```
## Team workspace sync
`sync` operates on non-global namespaces: pull selected skills, inspect status/diff, then push local content. The default workspace is `.agents/skills` in the current directory. Non-interactive pull requires explicit `--skill` selections; `--check` only inspects.
```bash
skillhub sync pull --namespace team --check
skillhub sync pull --namespace team --skill example-skill
skillhub sync status --namespace team
skillhub sync diff --namespace team
skillhub sync push --namespace team --all --dry-run
```
## Local Management
### List Installed Skills
@ -340,7 +366,7 @@ skillhub doctor
3. Backs up old `inventory.json` (if exists)
4. Writes new `inventory.json`
If the same skill has version conflicts across different targets, that skill will be skipped and reported.
Versions are tracked per target. Doctor reports recovery problems; it does not download or upgrade skills.
## Publishing
@ -360,7 +386,7 @@ Visibility options:
- `namespace-only` — Visible to namespace members only
- `private` — Visible to yourself only
After successful publication, the skill detail page URL will be displayed.
After the server accepts the submission, the CLI shows its current status and detail URL. `SCANNING` and `PENDING_REVIEW` are asynchronous states, not final publication; check the detail page for completion.
## Self-Update
@ -417,26 +443,7 @@ Update mechanism:
### inventory.json
```json
{
"items": [
{
"registry": "https://skill.xfyun.cn",
"namespace": "global",
"slug": "pdf-parser",
"version": "1.0.0",
"targets": [
{
"agent": "codex",
"rootDir": "/path/to/project/.codex/skills",
"installDir": "/path/to/project/.codex/skills/pdf-parser",
"installedAt": "2026-04-28T06:00:00.000Z"
}
]
}
]
}
```
CLI-managed installation state; do not hand-edit it. The current disk format uses `schemaVersion: 2`, `records` and optional `suites`. Each target records its version, fingerprint and installedBy sources. Legacy records are read compatibly and migrated on write.
## JSON Output
@ -508,10 +515,10 @@ Display CLI version.
### login
```bash
skillhub login --token <token> [--registry <url>] [--json]
skillhub login [--no-open] [--token <token>] [--registry <url>] [--json]
```
Save token and registry configuration.
Authenticate with Device Flow or a supplied API token, then save credentials and registry configuration.
The CLI preserves unknown fields in the shared configuration and credentials documents when it
updates its own `registry` and `tokens` fields.
@ -632,6 +639,22 @@ Options:
- `--token <token>` — API token
- `--json` — JSON output
### suite
```bash
skillhub suite <install|check|upgrade|remove> <coordinate> [options]
```
`install` supports `--version`, `--scope`, `--agent`, and `--dir`; `install` and `upgrade` support `--force`. `upgrade --check` previews changes. All actions support `--registry`, `--token`, and `--json`. See [Suites](./skill-suites).
### sync
```bash
skillhub sync <pull|status|diff|push> --namespace <slug> [options]
```
Run `skillhub help sync` for selection, workspace and publishing options. Validate with `push --dry-run` before publishing.
### update
```bash
@ -664,7 +687,7 @@ skillhub login --token sk_xxx
```bash
# Check if registry is accessible
curl https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1
curl 'https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1'
# Use alternative registry
skillhub search test --registry https://skillhub.example.com

View file

@ -0,0 +1,49 @@
# Docker Compose Deployment and Upgrades
You do not need to deploy a server to install skills from an existing registry. Use this guide when hosting your own registry. `make dev-all` runs source development; `make staging` is for container regression testing; `compose.release.yml` is the single-server release deployment. For clusters, see [Kubernetes](kubernetes.md).
## Configure the instance
Install Docker and Docker Compose, and obtain repository files matching your target release. From the repository root:
```bash
cp .env.release.example .env.release
```
Edit `.env.release` before starting:
| Setting | Check |
| --- | --- |
| `SKILLHUB_VERSION` | Pin a published release; `latest` tracks stable releases and `edge` tracks main-branch builds |
| `SKILLHUB_PUBLIC_BASE_URL` | The address users actually visit; use HTTPS in production |
| `WEB_PORT` / `API_PORT` | Defaults are 80 / 8080; check availability |
| `POSTGRES_PASSWORD` | Set your own database password |
| `BOOTSTRAP_ADMIN_ENABLED` / `BOOTSTRAP_ADMIN_PASSWORD` | Decide whether to initialize an administrator; replace the example password when enabled |
| Storage | Follow the template and the [object storage guide](https://github.com/iflytek/skillhub/blob/main/docs/object-storage.md) for external storage |
Do not commit or share `.env.release`. Changing an environment variable does not rotate the password of an existing database. Do not enable the `local` profile's mock authentication in a release deployment.
## Start and verify
```bash
make validate-release-config
docker compose --env-file .env.release -f compose.release.yml pull
docker compose --env-file .env.release -f compose.release.yml up -d
docker compose --env-file .env.release -f compose.release.yml ps
docker compose --env-file .env.release -f compose.release.yml logs --tail=100 server
```
Resolve validation errors before starting. Backend startup runs Flyway database migrations. Open your configured public URL, sign in with your configured administrator credentials, and verify search, download, and an authorized publishing/review flow. Healthy containers alone do not prove those workflows work.
Suite review writes are enabled by default in the single-server release Compose topology; Suite Bundle confirmation is disabled by default. See [Bundle import](suite-bundle.md) for enabling it. For rolling upgrades where old and new backends coexist, follow the [Suite deployment order](https://github.com/iflytek/skillhub/blob/main/docs/25-skill-suites.md).
## Upgrade, stop, and troubleshoot
Before upgrading, record the current image version and configuration, and back up both the database and skill object storage. Set `SKILLHUB_VERSION` to the target release and repeat validation, `pull`, `up -d`, and workflow verification. Rolling back an image does not roll back the database; check migration compatibility first.
```bash
# Stop this instance; do not add -v unless deliberately deleting data volumes
docker compose --env-file .env.release -f compose.release.yml down
```
For startup failures, inspect `ps` and service logs, then check database, Redis, storage, and public URL configuration. Include image versions, redacted logs, and request IDs when reporting a problem, never credentials or `.env.release`. See the [operations reference](https://github.com/iflytek/skillhub/blob/main/docs/09-deployment.md) for Redis, reverse proxies, collection services, and migrations.

View file

@ -35,6 +35,8 @@ deploy/k8s/
## Quick Start
All relative paths below use `deploy/k8s` in the repository as the working directory. Configure the Secret, then inspect `kubectl kustomize overlays/with-infra/` locally; rendered output may contain secrets. Applying manifests creates resources and backend startup runs database migrations.
### 1. Create Namespace
```bash
@ -44,10 +46,10 @@ kubectl create namespace skillhub
### 2. Configure Secret
```bash
cd deploy/k8s/base
cd deploy/k8s
# Copy example file
cp secret.yaml.example secret.yaml
cp base/secret.yaml.example base/secret.yaml
# Edit secret.yaml with your configuration
```
@ -270,7 +272,7 @@ kubectl create secret docker-registry ghcr-secret \
kubectl logs postgres-0 -n skillhub
# Check Secret configuration
kubectl get secret skillhub-secret -n skillhub -o yaml
kubectl describe deployment skillhub-server -n skillhub
```
### View Logs
@ -288,6 +290,8 @@ kubectl logs -l app.kubernetes.io/name=skillhub-scanner -n skillhub -f
## Cleanup
Run only after retiring the instance and backing up its database and skill storage. Namespace deletion removes its resources and PVCs; underlying data retention depends on the storage reclaim policy.
```bash
# Delete all resources
kubectl delete -k overlays/with-infra/ # or overlays/external/

View file

@ -19,7 +19,7 @@ Namespaces are the core organizational unit in SkillHub. Each namespace represen
|------|-------------|
| **Owner** | Full control, including deleting the namespace and managing all members |
| **Admin** | Manage members, review skill packages, modify settings |
| **Member** | Publish skill packages, view private skill packages |
| **Member** | Publish skills and view namespace-only content |
**Namespace States**:
@ -116,7 +116,7 @@ POST /api/v1/namespaces
Content-Type: application/json
{
"name": "iFlytek AI Team",
"displayName": "iFlytek AI Team",
"slug": "iflytek",
"description": "iFlytek's AI agent skills"
}
@ -125,9 +125,9 @@ Content-Type: application/json
**Parameter Reference**:
| Parameter | Type | Description |
|-----------|------|-------------|
| name | string | Namespace name (required, 2-50 characters) |
| displayName | string | Namespace name (required, up to 128 characters) |
| slug | string | URL identifier (required, unique, 2-64 characters, lowercase letters, numbers, hyphens only) |
| description | string | Description (optional, max 500 characters) |
| description | string | Description (optional, max 512 characters) |
**Get Namespace Details**:
```bash
@ -140,7 +140,7 @@ PUT /api/v1/namespaces/{slug}
Content-Type: application/json
{
"name": "iFlytek AI Team (Updated)",
"displayName": "iFlytek AI Team (Updated)",
"description": "Updated description"
}
```
@ -203,7 +203,7 @@ The history endpoint requires a browser session: `GET /api/v1/namespaces/{slug}/
> **Slug Uniqueness**: Namespace slugs must be globally unique and cannot be changed after creation. Use a short identifier for your team or project.
- **Owner Requirement**: Each namespace must have at least one Owner; the last Owner cannot be removed
- **Role Inheritance**: Namespace members automatically have access to all skill packages in that namespace
- **Role Inheritance**: Membership grants access to NAMESPACE_ONLY content, not every PRIVATE skill; private access is reserved for its owner and authorized administrators
- **Freeze Mechanism**: Administrators can freeze a namespace; no new skill packages can be published while frozen
- **Archive Mechanism**: Archived namespaces are hidden from search results, but existing skill packages remain accessible
- **Audit Logs**: All member changes and permission adjustments are recorded in the audit log

View file

@ -29,11 +29,15 @@ The review mechanism operates on two levels:
**Governance Features**:
- **Review Workflow**: Multi-level review, batch review
- **Review Workflow**: Per-item review of versions, profile changes, and Suites
- **Reporting System**: Users can report inappropriate skill packages
- **Promotion Management**: Promote namespace skill packages to the global scope
- **Audit Logs**: All governance actions are recorded
## Identify what is being reviewed
Review-task status and skill-version status are different: a task can be PENDING while the uploaded version is still SCANNING. Wait for scanning and inspect findings before deciding. Approval of a skill version does not approve a Suite that references it. Suites have their own review, while Bundle import first completes member publishing and then creates a Suite draft. See [Skill Suites](/en/guide/skill-suites) and [Bundle import](/en/guide/suite-bundle).
## Use Cases
**Case 1: Namespace Administrator Review**
@ -50,15 +54,12 @@ A platform administrator reviews skill packages being promoted from a namespace
A user reports an inappropriate skill package, and an administrator investigates and takes action.
**Case 4: Batch Review**
An administrator batch-approves multiple skill packages that meet the standards.
## Step-by-Step Guide
**Submitting for Review**:
1. When a skill package is published, the system automatically creates a review task
1. Ordinary PUBLIC / NAMESPACE_ONLY uploads create review tasks; PRIVATE uploads require confirmation or a separate review submission
2. The developer can check the review status under "My Submissions"
3. Wait for an administrator to review
@ -136,7 +137,7 @@ POST /api/v1/reviews
Content-Type: application/json
{
"skillVersionId": "version-123"
"skillVersionId": 123
}
```
@ -163,12 +164,12 @@ Content-Type: application/json
**Parameter Reference**:
| Parameter | Type | Description |
|------|------|------|
| id | string | Review task ID (path parameter) |
| comment | string | Review comment (optional, max 1000 characters) |
| id | number | Review task ID (path parameter) |
| comment | string | Review comment (optional for approval; provide a clear reason for rejection) |
**List Pending Reviews**:
```bash
GET /api/v1/reviews/pending?namespaceId=ns-123&page=0&size=20
GET /api/v1/reviews/pending?namespaceId=123&page=0&size=20
```
**List My Submissions**:
@ -209,11 +210,10 @@ Content-Type: application/json
## Notes
> **Review Permissions**: Only namespace Admins and Owners can review skill packages within their namespace. Platform administrators can review all skill packages.
> **Review Permissions**: Team namespace Admins and Owners review their space; SKILL_ADMIN and SUPER_ADMIN have platform review roles. Personal spaces and self-review have additional rules; a generic administrator label is not sufficient.
- **Review Turnaround**: It is recommended to complete reviews within 24 hours to avoid blocking developers
- **Review Records**: All review actions are recorded in the audit log
- **Compliance Audit**: Compliance declarations are recorded as version snapshots. Approval or rejection should consider the diff summary, but Agent execution traces are not recorded by SkillHub
- **Batch Review**: Administrators can batch-approve multiple skill packages
- **Review Comments**: When rejecting, it is recommended to provide detailed improvement suggestions
- **Withdrawal Restrictions**: Only skill packages in the pending review state can be withdrawn

View file

@ -37,7 +37,7 @@ The first phase does not expose a standalone compliance API. Runtime can read th
GET /api/v1/skills/{namespace}/{slug}/versions/{version}
```
Key response fields:
The example below shows fields inside the successful response’s `data`, not the full HTTP response. Check the outer business `code` before reading `data.id` and `data.complianceSnapshot`. Versions without declarations may have no snapshot; absence does not establish certification or an execution violation.
```json
{

View file

@ -93,7 +93,7 @@ curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- u
## Notes
> **Scanning Does Not Block Publishing**: Security scanning runs asynchronously and does not block the skill package upload process. Scan results are updated on the skill package detail page once completed.
> **Asynchronous upload is not publication**: Ordinary public and namespace-only submissions require scanning to be enabled. An unfinished scan does not establish publication. SCAN_FAILED means execution failure; findings and execution failures require different handling. Completing a scan does not imply review approval.
- **Scan Duration**: Depending on the skill package size and the number of enabled engines, scanning may take from a few seconds to several minutes
- **LLM Analysis Cost**: Enabling LLM analysis incurs API call charges; it is recommended to evaluate costs in production environments

View file

@ -4,7 +4,7 @@
SkillHub provides powerful full-text search functionality, enabling users to quickly find the skill packages they need.
Search supports not only keyword matching but also multi-dimensional filtering and sorting by namespace, tag, downloads, rating, and more.
Search supports not only keyword matching but also multi-dimensional filtering and sorting by namespace and tag, with relevance, download-count and newest sorting.
![Concept Diagram](/diagrams/skill-discovery-concept.png)
@ -12,9 +12,9 @@ Search supports not only keyword matching but also multi-dimensional filtering a
- **Full-text Search**: Search skill package names, descriptions, tags, authors
- **Smart Filters**: Filter by namespace, tag, visibility
- **Multiple Sorting**: Sort by relevance, downloads, rating, update time
- **Multiple Sorting**: Sort by relevance, downloads, newest
- **Permission-aware**: Only show skill packages user has access to
- **Real-time Updates**: Newly published skill packages appear immediately in search results
- **Real-time Updates**: Published, visible skill packages become searchable after index refresh
**Search Algorithm**:
@ -49,16 +49,16 @@ Only view skill packages with `data-processing` tag.
```bash
# Configure registry
export CLAWHUB_REGISTRY=http://localhost:8080
export SKILLHUB_REGISTRY=http://localhost:8080
# Search skill packages
npx clawhub search pdf
npx @astron-team/skillhub@latest search pdf
# Install skill package
npx clawhub install pdf-parser
npx @astron-team/skillhub@latest install pdf-parser
# Install skill package from specific namespace
npx clawhub install my-team--pdf-parser
npx @astron-team/skillhub@latest install my-team--pdf-parser
```
### Using Web UI to Search
@ -104,40 +104,17 @@ GET /api/web/skills?q=pdf&namespace=iflytek&label=data-processing&sort=downloads
| q | string | Search keyword (optional) |
| namespace | string | Namespace filter (optional) |
| label | string[] | Tag filter (optional, multiple allowed) |
| sort | enum | Sort by: relevance, downloads, rating, updated |
| sort | enum | Sort by: relevance, downloads, newest |
| page | number | Page number (starts from 0) |
| size | number | Page size (default 20, max 100) |
**Response Example**:
```json
{
"content": [
{
"id": "skill-123",
"namespace": "iflytek",
"slug": "pdf-parser",
"name": "PDF Parser",
"description": "Extract text and metadata from PDF files",
"downloads": 1234,
"rating": 4.5,
"starCount": 56,
"latestVersion": "1.2.3",
"updatedAt": "2026-03-15T10:30:00Z",
"labels": ["data-processing", "pdf"]
}
],
"totalElements": 42,
"totalPages": 3,
"number": 0,
"size": 20
}
```
Use the deployed OpenAPI schema for response fields and pagination envelopes.
## Notes
> **Permission Control**: Search results are automatically filtered by user permissions. PRIVATE skill packages are only visible to namespace members, INTERNAL skill packages are only visible to logged-in users.
> **Permission Control**: Search results are automatically filtered by user permissions. NAMESPACE_ONLY content is available to namespace members. PRIVATE content is restricted to its owner and authorized administrators, not all members or logged-in users.
- **Search Performance**: SkillHub uses PostgreSQL full-text search with Chinese and English word segmentation
- **Real-time Updates**: Newly published skill packages appear immediately in search results
- **Real-time Updates**: Published, visible skill packages become searchable after index refresh
- **Tag Convention**: Recommend using consistent tag naming conventions for easier filtering
- **Search Suggestions**: Supports search suggestions and autocomplete (frontend implementation)

View file

@ -134,7 +134,7 @@ visibility: PUBLIC
After publishing, [Skill Scanner](/en/guide/scanner) automatically scans the skill package for potential security risks. Results appear on the skill package detail page.
6. **Wait for Review** (if namespace has review enabled)
6. **Wait for Review** (follow the returned status)
Team admins receive review notifications and approve skill packages for official release.
@ -142,6 +142,16 @@ Team admins receive review notifications and approve skill packages for official
Skill package can be discovered through search, others can download via CLI or Web UI.
## Submission is not publication
After uploading, inspect the returned status and the version in My Skills. For ordinary PUBLIC and NAMESPACE_ONLY submissions, scanning must be enabled: the version passes through `SCANNING` and then `PENDING_REVIEW`. Approval publishes it. A PRIVATE upload remains `UPLOADED` after any configured scan; use its publish confirmation action to publish it. Privileged automatic publishing follows a separate path.
`SCAN_FAILED` means the scan could not complete, not that the package was proven unsafe. A completed scan can still contain findings. A successful upload, HTTP response, or CLI exit is not evidence of `PUBLISHED`. During an update, public readers continue to see the published version while authorized maintainers can preview the pending version.
### Authoring drafts
The authoring API supports private drafts, file editing and structural validation. It does not yet provide a web workbench or automatic publication. Passing validation does not execute the skill or prove its security. Do not confuse an authoring draft with an uploaded skill version awaiting review.
## Compliance Declarations
Skill authors can add `x-astron-compliance` to the `SKILL.md` frontmatter to declare how a skill version maps to compliance standards, controls, or security knowledge-base entries.
@ -190,7 +200,7 @@ Content-Type: multipart/form-data
# Parameters
file: MultipartFile (required)
visibility: PUBLIC | PRIVATE | INTERNAL (optional, default PUBLIC)
visibility: PUBLIC | PRIVATE | NAMESPACE_ONLY (required)
```
**Parameter Reference**:
@ -198,7 +208,7 @@ visibility: PUBLIC | PRIVATE | INTERNAL (optional, default PUBLIC)
|-----------|------|-------------|
| namespace | string | Namespace slug (path parameter) |
| file | MultipartFile | Skill package zip file |
| visibility | enum | Visibility level: PUBLIC, PRIVATE, INTERNAL |
| visibility | enum | Visibility level: PUBLIC, PRIVATE, NAMESPACE_ONLY |
**Get Skill Details**:
```bash
@ -236,7 +246,7 @@ GET /api/v1/skills/{namespace}/{slug}/resolve?version=^1.2.0
- **First Publish**: Version should start from `0.1.0` or `1.0.0`
- **Tag Management**: `latest` tag automatically points to the latest stable version
- **Review Process**: If namespace has review enabled, new versions need admin approval
- **Review Process**: Ordinary PUBLIC / NAMESPACE_ONLY uploads require scanning and review; PRIVATE uploads require publish confirmation
- **File Size Limit**: Single skill package max 100MB (configurable)
- **Naming Convention**: Skill slug supports lowercase letters, numbers, hyphens, and Unicode characters
- **Version Immutability**: Published versions cannot be modified, only new versions can be published

View file

@ -0,0 +1,70 @@
# Skill Suites: install and use
A Skill Suite is a separately versioned collection of exact published Skill versions with one Entry Skill. Each member remains an independent Skill after installation.
## Choose the right resource
| Resource | Purpose | How to use it |
| --- | --- | --- |
| Skill | One package containing `SKILL.md` | Install with `skillhub install`; use in an Agent |
| Skill Suite | A pinned collection with an Entry Skill | Install all members with `skillhub suite install` |
| Suite Bundle | An author's ZIP or folder containing a manifest and member packages | Import, preview, confirm and complete review in the Web UI |
A [Bundle](./suite-bundle) is an authoring format. A Suite is not a workflow runtime: coordination depends on the entry and member instructions. A Skill can still be installed independently.
## Install a Suite
Follow the related Suites on a Skill detail page to inspect the entry, pinned members and installability. A related-Suite badge denotes membership, not a mandatory dependency. Ordinary `skillhub search` searches Skills, and same-named Suites require the explicit `suite` command.
Replace the example coordinate below with a real Suite. Log in to the appropriate registry for restricted resources.
```bash
skillhub login
# Run from the target project root
skillhub suite install @team/example-suite --scope project --agent codex
# Or target Claude Code
skillhub suite install @team/example-suite --scope project --agent claude-code
# Pin a Suite version at user scope
skillhub suite install @team/example-suite --version 1.0.0 --scope user --agent codex
```
Use `--registry <url>` for a self-hosted registry. The server must advertise `skill-suite-v1`. If the CLI does not recognize the command, inspect `skillhub version` and `skillhub help suite`.
Project-scoped Codex members are installed separately:
```text
.codex/skills/
├── entry-skill/SKILL.md
├── member-a/SKILL.md
└── member-b/SKILL.md
```
Claude Code uses `.claude/skills`; user scope uses the corresponding directory under the home directory. Directory names are member slugs. There is no generated combined Suite Skill. Installation downloads and verifies all members; unavailable members are not silently replaced by newer versions.
## Use the installed skills
1. Open the target project in the selected Agent and refresh its skills or start a new session as required by that product.
2. Check the installation paths and verify that the Agent discovers the Entry Skill's `SKILL.md`.
3. Follow the entry instructions to configure required tools, environment variables and services. Installing Skill files does not install these dependencies.
4. Ask the Agent: “Use the entry skill `<entry name>` for the following task, following its instructions for the other members: …”
The Suite coordinate identifies the installation; invoke the actual Entry Skill or an individual member. Trigger syntax and loading behavior belong to the Agent. SkillHub has no generic `suite run` command.
## Check, upgrade and remove
```bash
skillhub suite check @team/example-suite
skillhub suite upgrade @team/example-suite --check
skillhub suite upgrade @team/example-suite
skillhub suite remove @team/example-suite
```
`check` reports member state and remote version information. `upgrade --check` previews changes. A member release does not mutate an installed Suite: upgrades follow a new SuiteVersion's pinned plan. Manage Suite-owned targets through the Suite lifecycle.
`--scope`, `--agent`, `--dir` and `--version` are install-only options; later operations use inventory. Removal retains direct installations, members shared with other Suites and locally modified members. Do not delete inventory to bypass a warning.
## Create a Suite
Use the Web editor to select published members and an entry, or import a [Suite Bundle](./suite-bundle) to upload local members. PUBLIC and NAMESPACE_ONLY Suites require Suite-level review; PRIVATE Suites can publish directly. Member Skills retain their own scan and review workflows.
A version supports up to 100 distinct members and requires one member as entry. Nested Suites, version ranges and external-registry members are unsupported. The CLI manages installations; it does not provide `suite publish` or import authoring manifests.

View file

@ -11,7 +11,7 @@ SkillHub provides a rich set of social features that allow team members to inter
- **Star**: Bookmark your favorite skill packages for easy access later
- **Rating**: Rate skill packages (1-5 stars) to help others assess quality
- **Download Statistics**: Track download counts to highlight popular skill packages
- **Notification System**: Receive timely notifications for review results, comment replies, and more
- **Notification System**: Receive timely notifications for review and governance events, and more
**Social Metrics**:
@ -103,13 +103,6 @@ DELETE /api/v1/skills/{skillId}/star
GET /api/v1/skills/{skillId}/star
```
**Response Example**:
```json
{
"starred": true,
"starredAt": "2026-03-15T10:30:00Z"
}
```
**Rate a Skill Package**:
```bash
@ -124,7 +117,7 @@ Content-Type: application/json
**Parameter Reference**:
| Parameter | Type | Description |
|------|------|------|
| skillId | string | Skill package ID (path parameter) |
| skillId | number | Skill package ID (path parameter) |
| score | number | Rating (1-5, required) |
**Get My Stars**:
@ -155,13 +148,8 @@ POST /api/v1/admin/skill-reviews/{reviewId}/hide
POST /api/v1/admin/skill-reviews/{reviewId}/restore
```
**Response Example**:
```json
{
"score": 5,
"ratedAt": "2026-03-15T10:30:00Z"
}
```
Responses use the standard API envelope. `GET .../star` returns a boolean in `data`; `GET .../rating` returns `score` and `rated`. Mutations return an empty `data`, not a rating timestamp. IDs are numeric.
## Notes
@ -170,6 +158,6 @@ POST /api/v1/admin/skill-reviews/{reviewId}/restore
> **Review Rules**: Only published skills can be reviewed, and the public list contains visible reviews only. Refresh and retry after a concurrent-update conflict.
- **Star Count**: A skill package's star count is displayed in search results and on the detail page
- **Average Rating**: A skill package's average rating affects search ranking
- **Average Rating**: Average ratings help compare skills; the search page has no dedicated rating sort
- **Notification Settings**: Users can disable certain notification types in their settings
- **Download Statistics**: Each download increments the download counter, which is used for popularity ranking

View file

@ -2,6 +2,8 @@
A Suite Bundle uploads one ZIP or folder to create a Suite or create a new version from a published base. SkillHub first shows the member diff. Member publication and review start only after explicit confirmation.
For installation and Agent usage, start with [Skill Suites](./skill-suites). This page is for authors importing content. `SUITE.yaml` (`kind: SkillSuiteBundle`) is distinct from the conceptual `suite.yaml` (`kind: SkillSuite`) definition.
## Archive format
The archive root must contain exactly one `SUITE.yaml`. Every packaged member has its own directory with a root `SKILL.md`. Undeclared skills, overlapping directories, unsafe or duplicate paths, and configured file limits block preview.
@ -17,7 +19,7 @@ spec:
version: 1.0.0
displayName: Clinical workflow
summary: Validate intake data and produce a summary
overview: The entry Skill validates and dispatches input; the summary Skill produces the result.
overview: The entry Skill validates intake data using the shared dictionary.
visibility: PUBLIC
entry: "@global/intake"
members:

View file

@ -11,10 +11,10 @@ hero:
actions:
- theme: brand
text: Quick Start
link: /quickstart
link: /en/quickstart
- theme: alt
text: Feature Guide
link: /guide/skill-publish
link: /en/guide/skill-publish
- theme: alt
text: GitHub
link: https://github.com/iflytek/skillhub
@ -23,27 +23,27 @@ features:
- icon: 🚀
title: Skill Publishing & Version Management
details: Publish skill packages with one click, semantic versioning, tag system, and multi-version coexistence
link: /guide/skill-publish
link: /en/guide/skill-publish
- icon: 🔍
title: Skill Search & Discovery
details: Full-text search, smart filtering, permission-aware — quickly find the skill packages you need
link: /guide/skill-discovery
link: /en/guide/skill-discovery
- icon: 👥
title: Namespace & Team Management
details: Namespace-based RBAC permission system with Owner/Admin/Member three-tier roles
link: /guide/namespace
link: /en/guide/namespace
- icon: ✅
title: Review & Governance
details: Multi-level review workflows and reporting system to ensure skill package quality
link: /guide/review
details: Skill and suite review workflows and reporting system to ensure skill package quality
link: /en/guide/review
- icon: ⭐
title: User Interaction & Social
details: Starring, ratings, notification system — build an active skill package community
link: /guide/social
link: /en/guide/social
- icon: 🛡️
title: Security Scanning
details: Built-in Skill Scanner with multi-engine security analysis, automatic detection of malicious code and security risks
link: /guide/scanner
link: /en/guide/scanner
- icon: 🏢
title: Enterprise Self-Hosting
details: Fully self-hosted with complete data sovereignty, supports Docker Compose and K8s deployment

View file

@ -10,10 +10,10 @@ SkillHub solves this problem. It provides a **private, controllable, and easy-to
## Core Value
- **Publish in 3 minutes**: From local development to global distribution with a single command
- **Managed distribution**: Upload packages and follow scanning, review, and publication
- **Enterprise-grade permissions**: Namespace-based RBAC with team collaboration and review workflows
- **Full lifecycle**: Version management, tag system, review workflows, and archiving mechanisms
- **Ready out of the box**: Start the full environment with a single curl command
- **Deployment choices**: Docker Compose and Kubernetes with explicit dependency and authentication configuration
- **Security scanning**: Built-in Skill Scanner for automatic security risk detection
- **Data sovereignty**: Fully self-hosted — all data stays within your firewall
@ -23,12 +23,12 @@ SkillHub solves this problem. It provides a **private, controllable, and easy-to
| Layer | Technology | Description |
|-------|------------|-------------|
| **Frontend** | React 19 + Vite + TanStack Router | Modern SPA with Chinese/English language support |
| **Backend** | Java 21 + Spring Boot 3.2 | Enterprise-grade REST API |
| **Database** | PostgreSQL 16 | Full-text search, Flyway auto-migration |
| **Cache** | Redis 7 | Session management, hot data caching |
| **Storage** | MinIO / S3 | Skill package file storage, supports local and cloud |
| **Deployment** | Docker Compose / K8s | One-click startup, supports self-hosting |
| **Frontend** | React + Vite + TanStack Router | Modern SPA with multiple interface languages |
| **Backend** | Java 21 + Spring Boot | Enterprise-grade REST API |
| **Database** | PostgreSQL | Full-text search, Flyway auto-migration |
| **Cache** | Redis | Session management, hot data caching |
| **Storage** | Local files / S3-compatible storage | Skill package file storage, supports local and cloud |
| **Deployment** | Docker Compose / K8s | Configured self-hosting |
## Feature Overview
@ -37,6 +37,23 @@ SkillHub solves this problem. It provides a **private, controllable, and easy-to
| [Skill Publishing & Version Management](/en/guide/skill-publish) | One-click skill package publishing with semantic versioning |
| [Skill Search & Discovery](/en/guide/skill-discovery) | Full-text search, smart filtering, permission-aware |
| [Namespace & Team Management](/en/guide/namespace) | Namespace-based RBAC permission system |
| [Review & Governance](/en/guide/review) | Multi-level review workflows, reporting system |
| [Review & Governance](/en/guide/review) | Skill and suite review workflows, reporting system |
| [Security Scanning](/en/guide/scanner) | Built-in Skill Scanner with multi-engine security analysis |
| [User Interaction & Social](/en/guide/social) | Starring, ratings, notification system |
## Three different objects
| Object | Purpose | Next step |
| --- | --- | --- |
| Skill | An individual package with `SKILL.md`, discovered and used by an Agent after installation | [Quick Start](./quickstart.md) |
| Skill Suite | A collection of pinned skill versions with one member designated as its entry skill | [Install and use suites](./guide/skill-suites.md) |
| Suite Bundle | An authoring format for importing a suite definition and member packages | [Bundle import](./guide/suite-bundle.md) |
The registry distributes and governs skills; execution happens in the user's Agent environment. Installing a suite does not automatically run all its members.
## Read by role
- Consumers: [CLI](./guide/cli.md), [discovery](./guide/skill-discovery.md), [FAQ](./faq.md).
- Authors: [publishing](./guide/skill-publish.md), [suites](./guide/skill-suites.md), [review](./guide/review.md).
- Operators: [namespaces](./guide/namespace.md), [deployment and upgrades](./guide/deployment.md), [Kubernetes](./guide/kubernetes.md).
- Integrators: [Runtime contract](./guide/runtime-integration.md), [repository documentation index](https://github.com/iflytek/skillhub/blob/main/docs/README.md).

View file

@ -1,234 +1,96 @@
# Quick Start
## One-Click Deployment
Choose your goal first. You do not need to deploy SkillHub to consume skills from an existing registry.
Use the curl command to quickly deploy SkillHub (includes all services: Web UI, Backend API, PostgreSQL, Redis, MinIO, Skill Scanner):
| Goal | Guide |
| --- | --- |
| Find, install, and use a skill | Follow this page |
| Install a coordinated collection | [Skill Suites](./guide/skill-suites.md) |
| Publish your own skill | [Publishing and versioning](./guide/skill-publish.md) |
| Upload a suite and its packages | [Suite Bundle import](./guide/suite-bundle.md) |
| Host a team registry | [Docker deployment](./guide/deployment.md) / [Kubernetes](./guide/kubernetes.md) |
| Develop SkillHub | [Development handbook](https://github.com/iflytek/skillhub/blob/main/docs/dev-workflow.md) |
## 1. Install the CLI and select a registry
```bash
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up
```
**For users in China (Alibaba Cloud mirror)**:
```bash
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun
```
**Custom parameters**:
```bash
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up \
--version v0.2.0 \
--home /opt/skillhub \
--aliyun
```
**Parameter reference**:
| Parameter | Description | Example |
|-----------|-------------|---------|
| `--version <tag>` | Specify version | `--version v0.2.0` |
| `--aliyun` | Use Alibaba Cloud mirror (recommended for China) | `--aliyun` |
| `--home <dir>` | Specify installation directory | `--home /opt/skillhub` |
| `--no-scanner` | Disable security scanning service | `--no-scanner` |
| `--mirror-registry <url>` | Custom image registry | `--mirror-registry registry.example.com` |
**Other commands**:
```bash
# Stop services
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- down
# Check service status
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- ps
# View logs
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- logs
# Clean all data
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- clean
```
After successful deployment, visit:
- **Web UI**: http://localhost:3000
- **Backend API**: http://localhost:8080
- **API Docs**: http://localhost:8080/swagger-ui.html
- **Skill Scanner**: http://localhost:8000
## Local Development
To start the development environment from source:
```bash
# Clone the repository
git clone https://github.com/iflytek/skillhub.git
cd skillhub
# Start all services (including Scanner)
make dev-all
```
### Notes for Developers in China
If `make dev-all` fails to start the backend, common causes include:
1. **Maven dependency download timeout**
The project includes a built-in Aliyun mirror configuration (`server/.mvn/settings.xml`), but Maven does not automatically read project-level settings. You need to configure it manually:
```bash
# Option 1: Copy to user directory (recommended)
mkdir -p ~/.m2
cp server/.mvn/settings.xml ~/.m2/settings.xml
# Option 2: Specify on each build
cd server && ./mvnw -s .mvn/settings.xml package
```
2. **Java version mismatch**
SkillHub requires Java 21+:
```bash
java -version
```
3. **Port conflict**
Check if port 8080 is in use:
```bash
lsof -i :8080
```
For detailed troubleshooting steps, see [FAQ](faq.md#local-development-startup-failure).
## Logging In
### Option 1: Use the Built-in Admin Account
SkillHub comes with a built-in super admin account for direct login:
- **Username**: `admin`
- **Password**: `ChangeMe!2026`
> **Security notice**: Change the default password immediately after deploying to production.
### Option 2: Register a New Account
Visit http://localhost:3000/register to create a new account.
### Option 3: Use Mock Users (Local Development Only)
During local development, you can use mock user headers for quick login:
```bash
# Regular user
curl -H "X-Mock-User-Id: local-user" http://localhost:8080/api/v1/auth/me
# Super admin
curl -H "X-Mock-User-Id: local-admin" http://localhost:8080/api/v1/auth/me
```
In the browser, you can add the `X-Mock-User-Id` header via a browser extension (e.g., ModHeader).
## Install the CLI Tool
Use the first-party SkillHub CLI for skill package management:
```bash
# Install the CLI and configure the SkillHub registry URL
npm install -g @astron-team/skillhub
export SKILLHUB_REGISTRY=http://localhost:8080
# Search for skill packages
skillhub search email
# Install a skill package
skillhub install my-skill
# Publish a skill package
skillhub publish ./my-skill --namespace my-team
skillhub version
```
Existing ClawHub workflows can still use the compatibility layer for search and install. Prefer the SkillHub CLI for new workflows and publishing.
## Publish Your First Skill Package
### Publish via CLI (Recommended)
1. **Prepare the skill package**
Create a simple skill package directory:
```
my-skill/
├── skill.md # Skill description
├── package.json # Metadata
└── scripts/ # Script files
└── main.py
```
2. **Publish using the CLI**
The default registry is `https://skill.xfyun.cn`. For a self-hosted instance, set its actual URL in your terminal:
```bash
# Configure the registry
export SKILLHUB_REGISTRY=http://localhost:8080
# Publish to a specific namespace
skillhub publish ./my-skill --namespace my-team
export SKILLHUB_REGISTRY=https://skillhub.example.com
```
3. **Wait for security scanning**
After publishing, the Skill Scanner will automatically scan the skill package for potential security issues:
- Malicious code detection
- Sensitive information leakage
- Dependency vulnerability scanning
- Behavioral analysis
Scan results are displayed on the skill package detail page.
4. **Wait for review** (if the namespace has review enabled)
Administrators will receive a notification and the skill package will be officially published once approved.
### Publish via Web UI
1. Visit http://localhost:3000/dashboard/publish
2. Select a namespace (create one first if needed)
3. Upload a zip file
4. Choose visibility (PUBLIC / PRIVATE / INTERNAL)
5. Click "Publish"
## Search and Download Skill Packages
### Using the CLI
Public skills support anonymous search and installation. Publishing and restricted resources require authentication:
```bash
skillhub login
skillhub whoami
```
Follow the terminal instructions to authenticate in the browser and confirm the device code. Use `skillhub login --no-open` on a remote terminal. Available sign-up and login methods depend on the instance configuration.
## 2. Find and install a skill
```bash
# Search for skill packages
skillhub search pdf
# Install a skill package
skillhub install pdf-parser
# Install a skill package from a specific namespace
skillhub install pdf-parser --namespace my-team
```
### Using the Web UI
Review the skill's purpose, version, visibility, and instructions on its detail page. Replace the placeholder `@team/example-skill` below with a real search result.
1. Visit http://localhost:3000/search
2. Enter keywords to search
3. Click a skill package to view details
4. Click "Download" or copy the install command
## Upgrade SkillHub
Use the curl command to upgrade to the latest version:
From the target project root:
```bash
# Upgrade to the latest version
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- pull
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- down
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up
# Upgrade to a specific version
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version v0.2.0
skillhub install @team/example-skill --scope project --agent codex
skillhub list --agent codex
```
> **Note**: It is recommended to back up the database and object storage before upgrading.
For Claude Code, use `--agent claude-code`. Use `--scope user` to share an installation across projects.
Codex project installations use `.codex/skills/<slug>/`; Claude Code uses `.claude/skills/<slug>/`. User installations use the corresponding directory under your home directory.
## 3. Use it in your Agent
Open the project in your Agent and start a new session or reload skills if required. Confirm that the Agent discovers the skill, then make a concrete request:
> Use example-skill and follow its instructions to process the following material: …
Use the name in `SKILL.md` and the Agent's discovery results. Installation does not execute a skill or configure its required tools and credentials.
If discovery fails, check the CLI's destination, current project, scope, and target Agent; see the [FAQ](./faq.md).
For a collection, use `skillhub suite install`, then start with its entry skill. See [Skill Suites](./guide/skill-suites.md).
## 4. Update and manage installations
```bash
skillhub upgrade @team/example-skill --check
skillhub upgrade @team/example-skill
```
Review the plan before updating and preserve local changes you need. Do not use `--force` by default. See the [CLI guide](./guide/cli.md) for removal, team workspace synchronization, and command details.
## 5. Publish your own skill
The package root must contain uppercase `SKILL.md`. A minimal file is:
```markdown
---
name: example-skill
description: Describe when to use this skill and what it does.
---
# Example skill
Explain the inputs, steps, expected output, and required tools.
```
Add `scripts/`, `references/`, and `assets/` as needed; `package.json` is not required.
Create or join a namespace where you can publish, then follow the [publishing guide](./guide/skill-publish.md) to prepare a version and upload:
```bash
skillhub publish ./example-skill --namespace my-team
```
A successful submission is not a published version. Open the returned detail URL to follow scanning, review, and the final status before attempting normal installation.

View file

@ -2,41 +2,15 @@
## Q: SkillHub 和 ClawHub 有什么区别?
A: SkillHub 是企业级的自托管方案,提供了更强的权限控制、审核机制和治理能力。ClawHub 是公共注册中心,类似 npm。
**主要区别**:
| 特性 | SkillHub | ClawHub |
|------|----------|---------|
| **部署方式** | 自托管 | 公共云 |
| **权限控制** | 命名空间 RBAC | 基础权限 |
| **审核机制** | 多级审核 | 无 |
| **安全扫描** | 内置 Skill Scanner | 无 |
| **数据主权** | 完全自主 | 托管在云端 |
| **适用场景** | 企业内部 | 公开分享 |
A: SkillHub 提供自托管注册中心、命名空间权限、发布审核、安全扫描和审计。第三方服务的能力会变化,不应将“无审核/无扫描”作为固定比较结论。兼容范围见 [OpenClaw 集成](https://github.com/iflytek/skillhub/blob/main/docs/openclaw-integration.md)。
## Q: 如何备份数据?
A: SkillHub 的数据存储在 PostgreSQL 和对象存储中。定期备份这两部分即可。
**备份 PostgreSQL**:
```bash
pg_dump -h localhost -U postgres skillhub > backup.sql
```
**备份对象存储**:
- 如果使用 MinIO,备份 MinIO 数据目录
- 如果使用 S3,使用 AWS CLI 或 S3 备份工具
A: 备份 PostgreSQL、实际使用的存储后端及部署配置。默认 release Compose 使用本地文件存储,需要备份 `skillhub_storage` 数据卷;使用 S3 时备份对应 bucket/对象。数据库和技能文件需要来自一致的备份窗口。操作步骤见 [部署指南](./guide/deployment.md),恢复能力应通过独立环境演练验证。
## Q: 支持哪些认证方式?
A: SkillHub 支持多种认证方式:
- **OAuth2**:GitHub、Google、GitLab 等
- **本地账号**:用户名密码登录(内置管理员:admin / ChangeMe!2026)
- **企业 SSO**:可以集成 LDAP、SAML 等
配置方式参考项目 README 中的认证配置章节。
A: 支持本地账号及已配置的 OAuth2 登录入口。当前预置注册包括 GitHub、GitLab、飞书和钉钉;实际入口以登录页和 `/api/v1/auth/methods` 为准。企业 SSO 需要按接入契约配置,不能把可扩展性当成已经内置 LDAP/SAML。参见 [认证与私有 SSO](https://github.com/iflytek/skillhub/blob/main/docs/11-auth-extensibility-and-private-sso.md)。
## Q: 技能包大小有限制吗?
@ -49,60 +23,31 @@ spring:
multipart:
max-file-size: 100MB
max-request-size: 100MB
skillhub:
publish:
max-package-size: 104857600
```
还需核对代理请求体和 Scanner 上传限制;只调 multipart 不会绕过包校验。
## Q: 如何使用 CLI 工具管理技能包?
A: SkillHub 兼容 OpenClaw CLI,使用 `npx clawhub` 命令即可操作:
A: 优先使用第一方 CLI:
```bash
# 配置注册中心地址
export CLAWHUB_REGISTRY=http://your-skillhub-host:8080
# 搜索技能包
npx clawhub search email
# 安装技能包
npx clawhub install my-skill
# 发布技能包(ClawHub CLI 的发布协议不兼容 SkillHub)
export SKILLHUB_REGISTRY=http://your-skillhub-host:8080
export SKILLHUB_TOKEN=YOUR_API_TOKEN
npx @astron-team/skillhub@latest publish ./my-skill
npm install -g @astron-team/skillhub
skillhub search pdf
```
按 [快速开始](./quickstart.md) 选择注册中心、安装位置和 Agent。发布和受限资源访问需要登录。ClawHub 兼容接口的范围见 [集成说明](https://github.com/iflytek/skillhub/blob/main/docs/openclaw-integration.md),不要将其发布协议与 SkillHub CLI 混用。
## Q: 如何配置 HTTPS?
A: 生产环境建议使用 Nginx 或 Traefik 作为反向代理,配置 SSL 证书。
**Nginx 配置示例**:
```nginx
server {
listen 443 ssl;
server_name skillhub.example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:3000;
}
location /api {
proxy_pass http://localhost:8080;
}
}
```
A: 在外部代理终止 TLS,并转发到实际映射的 Web 端口(release Compose 默认 `WEB_PORT=80`),Web 已代理后端路由。设置真实 `SKILLHUB_PUBLIC_BASE_URL`,正确传递原始 Host 和代理协议头,并验证登录与 Cookie。见 [部署指南](./guide/deployment.md)。
## Q: 如何监控 SkillHub?
A: SkillHub 提供了多种监控方式:
- **健康检查**:`GET /actuator/health`
- **Scanner 健康检查**:`GET http://localhost:8000/health`
- **指标监控**:`GET /actuator/metrics`(Prometheus 格式)
- **审计日志**:所有关键操作都会记录到审计日志
- **应用日志**:使用 ELK 或 Loki 收集日志
A: 默认配置暴露 `/actuator/health` 和 `/actuator/info`。`/actuator/metrics` 不是 Prometheus 文本接口,当前基础配置也未默认暴露它或启用 Prometheus 导出。结合服务日志、审计记录和请求的 `requestId` 排查;监控接入需要单独核对部署配置,见 [可观测性指南](https://github.com/iflytek/skillhub/blob/main/docs/observability-developer-guide.md)。
## Q: 支持多租户吗?
@ -112,47 +57,19 @@ A: SkillHub 通过命名空间实现了逻辑上的多租户隔离。每个命
## Q: 如何升级 SkillHub?
A: 使用 curl 命令升级:
```bash
# 拉取最新镜像并重启
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- pull
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- down
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up
# 或直接指定版本升级
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version v0.2.0
```
> **注意**:升级前建议先备份数据库和对象存储。数据库迁移由 Flyway 自动执行。升级不会清空数据库,已录入的技能包不会丢失。
A: 按 [部署与升级指南](./guide/deployment.md) 选择目标版本,先备份数据库、技能存储和配置,再升级并验证健康、登录及代表性技能操作。Flyway 会执行数据库迁移;不能仅凭容器启动成功认定升级成功,也不能假设降级镜像即可回滚数据库。
## Q: 为什么管理员(admin)和普通用户都无法创建命名空间?
A: 较旧版本的 SkillHub 不支持创建命名空间。该功能是在后续版本迭代中添加的。请将您的 SkillHub 升级到最新版本(latest)。
升级命令示例:
```bash
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version latest
```
A: 先查看页面或接口的错误信息和 `requestId`,核对当前账号权限、名称校验及实例限制。不要直接推断为版本太旧;管理员身份也不能绕过全部业务规则。参见 [命名空间管理](./guide/namespace.md)。
## Q: 如何搜索或操作指定命名空间中的技能包(Skill)?
A: 使用 OpenClaw CLI 命令行工具时,可以通过 `<namespace>--<skill-name>` 的格式来指定命名空间进行操作(例如搜索、安装)。如果在网页端搜索遇到问题,也可以尝试通过先导出技能、再导入到目标命名空间的方式来完成跨空间操作。
A: 在网页中选择命名空间;CLI 安装可使用 `skillhub install @team/example-skill`,其中坐标应替换成真实资源。`skillhub search` 搜索技能,`skillhub suite install` 安装套装。命名空间迁移与搜索不是同一操作,不需要通过导出再导入来解决搜索问题。
## Q: 推荐的部署方式是什么?可以自己拉镜像手动部署吗?
A: 推荐使用官方一键部署脚本,不建议自己拉取镜像手动部署(手动部署容易出现数据库初始化、依赖顺序或登录后跳回登录页等问题)。默认从公共镜像仓库拉取依赖,其中 SkillHub 应用镜像来自 GHCR:
```bash
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --public-url https://skillhub.your-company.com
```
国内网络无法访问 GHCR 时,使用阿里云镜像:
```bash
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --public-url https://skillhub.your-company.com --version latest
```
脚本会执行一系列初始化操作,生成的运行时配置默认位于 `/tmp/skillhub-runtime/`(包含 `.env.release` 和 docker-compose 文件)。
A: 支持官方 runtime 脚本、release Compose 和 Kubernetes/Helm。选择一种方式并保留对应的配置与数据目录,参见 [Docker 部署](./guide/deployment.md) 和 [Kubernetes 部署](./guide/kubernetes.md)。手动部署需要正确配置数据库、Redis、存储、认证和代理,不能只启动应用镜像。
## Q: 用 Kubernetes 部署对集群版本有要求吗?
@ -160,39 +77,23 @@ A: 官方 [Kubernetes 部署指南](./guide/kubernetes.md) 要求 Kubernetes **v
## Q: 部署后输入正确的账号密码,却又跳回登录页?
A: 该现象多见于「手动部署」场景(接口异常或初始化未完成导致)。建议:
1. 改用上面的一键脚本部署。
2. 必要时清空 PostgreSQL 数据卷后重建再登录。
3. 若前置了反向代理,检查代理配置是否正确转发。
A: 先在浏览器网络面板检查登录请求及后续身份请求的状态,核对实例公网 URL、代理转发、Cookie 和后端会话配置,并关联服务端 `requestId` 与日志。此现象本身不能确定是密码错误或数据库问题。不要清空 PostgreSQL 数据卷来尝试修复登录。部署参数见 [部署指南](./guide/deployment.md)。
## Q: 如何修改 admin 密码?修改配置后不生效?
A: 环境变量在容器创建时注入,修改后必须重新创建容器才会生效;仅执行 `restart` 不会重新注入环境变量。
1. 修改运行时目录下的 `/tmp/skillhub-runtime/.env.release`(参考仓库 [.env.release.example](https://github.com/iflytek/skillhub/blob/main/.env.release.example))。
2. 重新创建相关容器:
```bash
docker compose \
--env-file /tmp/skillhub-runtime/.env.release \
-f /tmp/skillhub-runtime/compose.release.yml \
up -d --force-recreate
```
3. 若此前密码已写入数据库导致仍不生效,可能需要清理对应数据后重新初始化。
A: `BOOTSTRAP_ADMIN_PASSWORD` 用于初始化账号。`BootstrapAdminInitializer` 在本地凭证已存在时保留原密码,因此修改环境变量或重建容器不会重置已有账号密码。使用实例提供的修改/找回密码流程;邮件验证码需要正确配置 SMTP。不要删除用户或数据库重新初始化。
## Q: 修改 / 找回密码必须使用邮箱验证码吗?
A: 是的,默认通过邮箱验证码修改或找回密码,因此需要先配置 SMTP。配置方法参考 [docs/19-smtp-password-reset-email-setup.md](https://github.com/iflytek/skillhub/blob/main/docs/19-smtp-password-reset-email-setup.md)。管理员也可在 `.env.release` 中进行重置。
A: 当前修改/找回密码流程使用邮箱验证码,需先配置 [SMTP](https://github.com/iflytek/skillhub/blob/main/docs/19-smtp-password-reset-email-setup.md)。修改 bootstrap 环境变量不能重置已经初始化的密码。
## Q: skill 可以起中文名吗?
A: skill name 一般使用英文,目前不支持中文名(在 OpenClaw 中使用中文 skill 名会报错)。
A: 技能标识 `name` / slug 使用符合校验规则的名称;面向用户的展示名支持中文,可通过 `metadata.display-name` 配置。展示名不改变安装坐标或目录名。见 [发布指南](./guide/skill-publish.md)。
## Q: 未审核的 skill 可以下载吗?
A: 只要拥有可查看的权限,一般都可以下载。
A: 正常安装面向已发布且当前用户可访问的版本。能查看详情不等于能下载任意状态的版本;作者或审核人员的预览权限与公开分发权限不同。见 [审核与治理](./guide/review.md)。
## Q: 如何隐藏或删除登录页的第三方 SSO 登录方式?
@ -273,7 +174,7 @@ SKILLHUB_PUBLISH_MAX_FILE_COUNT=500
## Q: 使用 CLI(发布 / 下载等)对服务端版本有要求吗?
A: 需要 SkillHub 服务端镜像 **v0.2.7 及以上** 才支持 CLI 功能。
A: 兼容性取决于具体命令。旧版本支持基础 CLI 不代表支持 Device Flow、Suite 或同步;请核对 CLI 版本与目标服务端发行说明。Suite 要求服务端声明 `skill-suite-v1`。见 [CLI 指南](./guide/cli.md)。
## Q: SkillHub 支持 MySQL 数据库吗?
@ -372,21 +273,7 @@ A: OAuth 首次登录创建的是普通用户。需要由已有的 `SUPER_ADMIN`
## Q: 如何批量安装多个技能包?
A: CLI 的 `install` 一次处理一个技能包。下面两个示例都通过 `--dir` 将技能批量安装到同一个目标根目录;每个技能实际位于 `$target_dir/<skill-slug>/`:
```bash
target_dir=/opt/skillhub-skills
# 逐个安装
for skill in skill-a skill-b skill-c; do
skillhub install "$skill" --dir "$target_dir"
done
# 或从清单文件读取(每行一个技能名)
xargs -a skills.txt -I {} skillhub install "{}" --dir "$target_dir"
```
自 **SkillHub Server v0.2.12** 起,公开技能支持匿名搜索与安装;如果配置了无效的 Bearer Token,命令会直接失败而不再回退匿名访问,遇到这种情况请更新凭据或先移除无效 Token。
A: 需要固定成员版本并统一升级时,使用 [技能套装](./guide/skill-suites.md) 的 `skillhub suite install`。同步团队命名空间工作区时,使用 [CLI](./guide/cli.md) 的 `skillhub sync pull`。若只是独立安装几个无关技能,可分别运行 `skillhub install`;Suite Bundle 是发布者的导入格式,不是本地安装命令。
## Q: 遇到问题怎么办?
@ -455,7 +342,7 @@ java -version
lsof -i :8080
# 终止进程
kill -9 <PID>
# 确认进程用途后,通过其启动工具停止服务
```
### 4. 查看详细日志

View file

@ -19,7 +19,7 @@ bun add -g @astron-team/skillhub
```bash
# 登录
skillhub login --token sk_xxx
skillhub login
# 搜索技能
skillhub search pdf
@ -73,6 +73,8 @@ Token 按以下优先级解析:
### 登录
未传入 token 时,`skillhub login` 使用 OAuth Device Flow:打开验证页面并显示用户码,完成浏览器授权后保存凭证。无浏览器终端可用 `skillhub login --no-open`;自动化使用 API token。
```bash
# 使用 API token 登录
skillhub login --token sk_xxx
@ -237,6 +239,31 @@ DeepSeek Harness 从最近的 Git 仓库根目录解析项目技能,而 SkillH
}
```
## 技能安装后的使用与套装
安装命令只下载技能文件,不执行任务。打开目标项目并让 Agent 发现 `SKILL.md`,按技能说明配置依赖,再要求 Agent 使用该技能。套装请阅读[安装与使用指南](./skill-suites)。
```bash
# Replace with a real Suite coordinate
skillhub suite install @team/example-suite --scope project --agent codex
skillhub suite check @team/example-suite
skillhub suite upgrade @team/example-suite --check
skillhub suite upgrade @team/example-suite
skillhub suite remove @team/example-suite
```
## 团队工作区同步
`sync` 面向非 global 命名空间:pull 拉取选定技能,status/diff 检查变化,push 发布本地内容。默认工作区为当前目录的 `.agents/skills`。非交互 pull 必须显式选择 `--skill`;`--check` 只检查。
```bash
skillhub sync pull --namespace team --check
skillhub sync pull --namespace team --skill example-skill
skillhub sync status --namespace team
skillhub sync diff --namespace team
skillhub sync push --namespace team --all --dry-run
```
## 本地管理
### 查看已安装技能
@ -303,7 +330,7 @@ skillhub doctor
3. 备份旧的 `inventory.json`(如果存在)
4. 写入新的 `inventory.json`
如果同一技能在不同目标中存在版本冲突,该技能会被跳过并报告。
版本按安装目标记录。doctor 报告恢复问题,不会下载或升级技能。
## 发布
@ -323,7 +350,7 @@ skillhub publish ./my-skill --namespace myspace --visibility private
- `namespace-only` — 仅 namespace 成员可见
- `private` — 仅自己可见
发布成功后会输出技能详情页 URL。
提交被服务端接受后会输出当前状态和技能详情页 URL。`SCANNING`、`PENDING_REVIEW` 表示异步处理尚未完成;请在详情页确认最终发布状态。
## 自更新
@ -380,26 +407,7 @@ skillhub update
### inventory.json
```json
{
"items": [
{
"registry": "https://skill.xfyun.cn",
"namespace": "global",
"slug": "pdf-parser",
"version": "1.0.0",
"targets": [
{
"agent": "codex",
"rootDir": "/path/to/project/.codex/skills",
"installDir": "/path/to/project/.codex/skills/pdf-parser",
"installedAt": "2026-04-28T06:00:00.000Z"
}
]
}
]
}
```
CLI 管理的安装记录,不应手工编辑。当前磁盘格式使用 `schemaVersion: 2`、`records` 和可选 `suites`;每个 target 分别记录版本、fingerprint 和 installedBy。CLI 可读取旧记录并在写入时迁移。
## JSON 输出
@ -471,7 +479,7 @@ skillhub version --json
### login
```bash
skillhub login --token <token> [--registry <url>] [--json]
skillhub login [--no-open] [--token <token>] [--registry <url>] [--json]
```
保存 token 和 registry 配置。
@ -578,6 +586,22 @@ skillhub publish <path> [options]
- `--token <token>` — API token
- `--json` — JSON 输出
### suite
```bash
skillhub suite <install|check|upgrade|remove> <coordinate> [options]
```
`install` 支持 `--version`、`--scope`、`--agent`、`--dir`;`install` 和 `upgrade` 支持 `--force`。`upgrade --check` 预览变更。各操作支持 `--registry`、`--token`、`--json`。详见[套装指南](./skill-suites)。
### sync
```bash
skillhub sync <pull|status|diff|push> --namespace <slug> [options]
```
先运行 `skillhub help sync` 查看选择、工作区和发布参数;发布前使用 `push --dry-run` 验证。
### update
```bash
@ -610,7 +634,7 @@ skillhub login --token sk_xxx
```bash
# 检查 registry 是否可访问
curl https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1
curl 'https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1'
# 使用其他 registry
skillhub search test --registry https://skillhub.example.com

View file

@ -0,0 +1,49 @@
# Docker Compose 部署与升级
使用已有 Registry 安装技能不需要部署服务。只有需要自托管 Registry 时才执行本页流程。源码开发使用 `make dev-all`;容器回归使用 `make staging`;正式单机交付使用 `compose.release.yml`。集群部署见 [Kubernetes](kubernetes.md)。
## 准备配置
需要 Docker、Docker Compose,以及与目标版本匹配的仓库文件。在仓库根目录执行:
```bash
cp .env.release.example .env.release
```
编辑 `.env.release` 后再启动:
| 配置 | 需要确认 |
| --- | --- |
| `SKILLHUB_VERSION` | 固定已发布版本,避免升级时无意更换镜像;`latest` 跟踪稳定发布,`edge` 跟踪主分支构建 |
| `SKILLHUB_PUBLIC_BASE_URL` | 用户实际访问的地址,生产环境使用 HTTPS |
| `WEB_PORT` / `API_PORT` | 默认分别为 80 / 8080,确认端口可用 |
| `POSTGRES_PASSWORD` | 设置自己的数据库密码 |
| `BOOTSTRAP_ADMIN_ENABLED` / `BOOTSTRAP_ADMIN_PASSWORD` | 是否初始化首个管理员;启用时必须更换示例密码 |
| 存储配置 | 默认及可选配置以模板为准;外部存储按[对象存储手册](https://github.com/iflytek/skillhub/blob/main/docs/object-storage.md)配置 |
`.env.release` 包含敏感信息,不要提交或分享。已有数据库的密码不会因修改环境变量自动轮换。发布环境不要启用 `local` profile 的 Mock 登录。
## 启动与确认
```bash
make validate-release-config
docker compose --env-file .env.release -f compose.release.yml pull
docker compose --env-file .env.release -f compose.release.yml up -d
docker compose --env-file .env.release -f compose.release.yml ps
docker compose --env-file .env.release -f compose.release.yml logs --tail=100 server
```
校验通过后再启动。首次启动或升级时,后端会执行 Flyway 数据库迁移。访问配置的公开地址,使用自己配置的管理员凭证登录,并验证搜索、下载以及一次符合权限的发布/审核流程;容器健康不代表这些业务路径已通过。
Suite 审核写入在单机 release Compose 中默认开启;Suite Bundle 确认默认关闭。需要批量导入时,按 [Bundle 导入](suite-bundle.md#部署开关)启用对应开关。滚动升级新旧后端共存时,另按[套装部署顺序](https://github.com/iflytek/skillhub/blob/main/docs/25-skill-suites.md#部署顺序)操作。
## 升级、停止与排障
升级前保存当前镜像版本、配置,并备份数据库和技能对象存储。修改 `SKILLHUB_VERSION` 为目标发布版本,重新执行校验、`pull`、`up -d` 和业务验证。回退镜像不等于回退数据库;先检查目标迁移的兼容性。
```bash
# 停止本实例;不要附加 -v,除非明确要删除数据卷
docker compose --env-file .env.release -f compose.release.yml down
```
启动失败先查看 `ps` 和服务日志,核对数据库、Redis、存储和公开地址配置。提交问题时提供镜像版本、脱敏日志和请求 ID,不提供 `.env.release` 或凭证。更多 Redis、反向代理、采集服务和迁移配置见[运维手册](https://github.com/iflytek/skillhub/blob/main/docs/09-deployment.md)。

View file

@ -37,6 +37,8 @@ deploy/k8s/
## 快速开始
以下相对路径均以仓库的 `deploy/k8s` 为工作目录。先配置 Secret,再渲染检查 `kubectl kustomize overlays/with-infra/`;输出可能包含 Secret,不要公开粘贴。应用清单会创建资源并在后端启动时执行数据库迁移。
### 1. 创建命名空间
```bash
@ -46,10 +48,10 @@ kubectl create namespace skillhub
### 2. 配置 Secret
```bash
cd deploy/k8s/base
cd deploy/k8s
# 复制示例文件
cp secret.yaml.example secret.yaml
cp base/secret.yaml.example base/secret.yaml
# 编辑 secret.yaml,修改敏感配置
```
@ -272,7 +274,7 @@ kubectl create secret docker-registry ghcr-secret \
kubectl logs postgres-0 -n skillhub
# 检查 Secret 配置
kubectl get secret skillhub-secret -n skillhub -o yaml
kubectl describe deployment skillhub-server -n skillhub
```
### 查看日志
@ -290,6 +292,8 @@ kubectl logs -l app.kubernetes.io/name=skillhub-scanner -n skillhub -f
## 清理
仅在确认不再使用该实例并完成数据库、技能存储备份后执行。删除命名空间会删除其中的资源和 PVC;底层数据是否保留取决于存储回收策略。
```bash
# 删除所有资源
kubectl delete -k overlays/with-infra/ # 或 overlays/external/

View file

@ -19,7 +19,7 @@
|------|------|
| **Owner** | 完全控制,包括删除命名空间、管理所有成员 |
| **Admin** | 管理成员、审核技能包、修改设置 |
| **Member** | 发布技能包、查看私有技能包 |
| **Member** | 发布技能包、查看空间成员可见的技能包 |
**命名空间状态**:
@ -116,7 +116,7 @@ POST /api/v1/namespaces
Content-Type: application/json
{
"name": "iFlytek AI Team",
"displayName": "iFlytek AI Team",
"slug": "iflytek",
"description": "iFlytek's AI agent skills"
}
@ -125,9 +125,9 @@ Content-Type: application/json
**参数说明**:
| 参数 | 类型 | 说明 |
|------|------|------|
| name | string | 命名空间名称(必需,2-50 字符) |
| displayName | string | 命名空间名称(必需,最多 128 字符) |
| slug | string | URL 标识符(必需,唯一,2-64 字符,只能包含小写字母、数字、连字符) |
| description | string | 描述(可选,最多 500 字符) |
| description | string | 描述(可选,最多 512 字符) |
**获取命名空间详情**:
```bash
@ -140,7 +140,7 @@ PUT /api/v1/namespaces/{slug}
Content-Type: application/json
{
"name": "iFlytek AI Team (Updated)",
"displayName": "iFlytek AI Team (Updated)",
"description": "Updated description"
}
```
@ -203,7 +203,7 @@ POST /api/v1/namespaces/{slug}/unfreeze
> **Slug 唯一性**:命名空间 slug 在全局范围内必须唯一,且创建后不可修改。建议使用团队或项目的简短标识符。
- **Owner 权限**:每个命名空间至少需要一个 Owner,最后一个 Owner 无法被移除
- **角色继承**:命名空间成员自动拥有该命名空间下所有技能包的访问权限
- **角色继承**:成员可访问 NAMESPACE_ONLY 内容;PRIVATE 内容仅所有者及有权管理员可访问,不向所有成员开放
- **冻结机制**:管理员可以冻结命名空间,冻结后无法发布新技能包
- **归档机制**:归档的命名空间会从搜索结果中隐藏,但已有技能包仍可访问
- **审计日志**:所有成员变更、权限调整都会记录到审计日志

View file

@ -29,13 +29,17 @@ SkillHub 提供了完整的审核工作流,确保发布到注册中心的技
**治理功能**:
- **审核工作流**:多级审核、批量审核
- **审核工作流**:按权限逐项审核技能版本、资料变更和套装
- **举报系统**:用户可以举报不当技能包
- **推广管理**:将命名空间技能包推<EFBFBD><EFBFBD><EFBFBD>到全局
- **推广管理**:将命名空间技能包推广到全局
- **审计日志**:记录所有治理操作
头像变更复用技能审核申请。机器阻止与人工拒绝是不同状态;开关组合、审核操作及云审核接入步骤详见 [技能头像与图片审核接入](/guide/skill-avatars)。
## 先确认审核对象
审核任务状态与技能版本状态不同:任务为 PENDING 时,版本可能仍在 SCANNING。先等待扫描完成并检查风险,再作审核决定。成员技能审核通过不代表引用它的 Suite 已通过;Suite 有独立审核。Bundle 导入先完成成员发布,再创建 Suite 草稿,详见[技能套装](/guide/skill-suites)与[批量导入](/guide/suite-bundle)。
## 使用场景
**场景一:命名空间管理员审核**
@ -52,17 +56,14 @@ SkillHub 提供了完整的审核工作流,确保发布到注册中心的技
用户举报不当技能包,管理员调查并处理。
**场景四:批量审核**
管理员批量批准多个符合规范的技能包。
## 使用步骤
**提交审核**:
1. 发布技能包时,系统自动创建审核任务
1. 普通 PUBLIC / NAMESPACE_ONLY 上传创建审核任务;PRIVATE 上传先保留,需确认发布或另行提审
2. 开发者可以在「我的提交」中查看审核状态
3. 等待管理<EFBFBD><EFBFBD><EFBFBD>审核
3. 等待管理员审核
**审核技能包**:
@ -139,7 +140,7 @@ POST /api/v1/reviews
Content-Type: application/json
{
"skillVersionId": "version-123"
"skillVersionId": 123
}
```
@ -166,12 +167,12 @@ Content-Type: application/json
**参数说明**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | string | 审核任务 ID(路径参数) |
| comment | string | 审核意见(可选,最多 1000 字符) |
| id | number | 审核任务 ID(路径参数) |
| comment | string | 审核意见(批准时可选;拒绝时应填写明确原因) |
**列出待审核任务**:
```bash
GET /api/v1/reviews/pending?namespaceId=ns-123&page=0&size=20
GET /api/v1/reviews/pending?namespaceId=123&page=0&size=20
```
**列出我的提交**:
@ -215,11 +216,10 @@ Content-Type: application/json
## 注意事项
> **审核权限**:只有命名空间的 Admin 和 Owner 可以审核本命名空间的技能包。平台管理员可以审核所有技能包。
> **审核权限**:团队空间 Admin / Owner 可审核本空间;平台 SKILL_ADMIN / SUPER_ADMIN 具有平台审核权限。个人空间及本人提交的审核还受自审规则约束,不能仅凭“管理员”称呼判断。
- **审核时效**:建议在 24 小时内完成审核,避免阻塞开发者
- **审核记录**:所有审核操作都会记录到审计日志
- **合规审计**:合规声明以版本快照形式记录。审核通过或拒绝时,应结合差异摘要判断风险,但 Agent 执行 trace 不由 SkillHub 记录
- **批量审核**:管理员可以批量批准多个技能包
- **审核意见**:拒绝时建议提供详细的改进建议
- **撤回限制**:只有待审核状态的技能包可以撤回

View file

@ -37,7 +37,7 @@ Runtime 在执行技能时,如果需要把执行链路与 SkillHub 的合规
GET /api/v1/skills/{namespace}/{slug}/versions/{version}
```
响应中的关键字段:
下面仅展示成功响应 `data` 内的关键字段,不是完整 HTTP 响应。先检查外层业务 `code`,再读取 `data.id` 和 `data.complianceSnapshot`;没有声明的版本可能没有快照,不应据此推断为已认证或执行违规。
```json
{

View file

@ -93,7 +93,7 @@ curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- u
## 注意事项
> **扫描不阻塞发布**:安全扫描是异步执行的,不会阻塞技能包的上传流程。扫描结果会在完成后更新到技能包详情页。
> **异步上传不等于发布放行**:普通公开及空间内发布要求扫描已启用,扫描未完成时不能视为已发布。SCAN_FAILED 是执行失败;扫描发现风险与执行失败须分别处理。扫描通过也不等于人工审核通过。
- **扫描耗时**:根据技能包大小和启用的引擎数量,扫描可能需要几秒到几分钟
- **LLM 分析成本**:启用 LLM 分析会产生 API 调用费用,建议在生产环境中评估成本

View file

@ -4,7 +4,7 @@
SkillHub 提供了强大的全文搜索功能,让用户可以快速找到需要的技能包。
搜索不仅支持关键词匹配,还支持按命名空间、标签、下载量、评分等多维度过滤和排序。
搜索支持关键词、命名空间和标签筛选,以及相关性、下载量和最新排序。
![概念图](/diagrams/skill-discovery-concept.png)
@ -12,9 +12,9 @@ SkillHub 提供了强大的全文搜索功能,让用户可以快速找到需
- **全文搜索**:搜索技能包名称、描述、标签、作者
- **智能过滤**:按命名空间、标签、可见性过滤
- **多种排序**:按相关性、下载量、评分、更新时间排序
- **多种排序**:按相关性、下载量、最新排序
- **权限感知**:只显示用户有权访问的技能包
- **实时更新**:新发布的技能包立即出现在搜索结果中
- **实时更新**:已发布且当前用户可见的技能可被搜索;索引刷新可能有延迟
**搜索算法**:
@ -49,16 +49,16 @@ SkillHub 使用 PostgreSQL 全文搜索,支持:
```bash
# 配置注册中心
export CLAWHUB_REGISTRY=http://localhost:8080
export SKILLHUB_REGISTRY=http://localhost:8080
# 搜索技能包
npx clawhub search pdf
npx @astron-team/skillhub@latest search pdf
# 安装技能包
npx clawhub install pdf-parser
npx @astron-team/skillhub@latest install pdf-parser
# 安装指定命名空间的技能包
npx clawhub install my-team--pdf-parser
npx @astron-team/skillhub@latest install my-team--pdf-parser
```
### 使用 Web UI 搜索
@ -109,40 +109,16 @@ GET /api/web/skills?q=pdf&namespace=iflytek&label=data-processing&sort=downloads
| q | string | 搜索关键词(可选) |
| namespace | string | 命名空间过滤(可选) |
| label | string[] | 标签过滤(可选,可多选) |
| sort | enum | 排序方式:relevance(相关性)、downloads(下载量)、rating(评分)、updated(更新时间) |
| sort | enum | 排序方式:relevance(相关性)、downloads(下载量)、newest(最新) |
| page | number | 页码(从 0 开始) |
| size | number | 每页数量(默认 20,最大 100) |
**响应示例**:
```json
{
"content": [
{
"id": "skill-123",
"namespace": "iflytek",
"slug": "pdf-parser",
"name": "PDF Parser",
"description": "Extract text and metadata from PDF files",
"downloads": 1234,
"rating": 4.5,
"starCount": 56,
"latestVersion": "1.2.3",
"updatedAt": "2026-03-15T10:30:00Z",
"labels": ["data-processing", "pdf"]
}
],
"totalElements": 42,
"totalPages": 3,
"number": 0,
"size": 20
}
```
响应字段和分页封装以部署实例的 OpenAPI 为准。
## 注意事项
> **权限控制**:搜索结果会根据用户权限自动过滤。PRIVATE 技能包只对命名空间成员可见,INTERNAL 技能包只对登录用户可见。
> **权限控制**:搜索结果会根据用户权限自动过滤。NAMESPACE_ONLY 面向空间成员;PRIVATE 面向所有者及有权管理员,并非所有登录用户或所有空间成员。
- **搜索性能**:SkillHub 使用 PostgreSQL 全文搜索,支持中英文分词
- **实时更新**:新发布的技能包会立即出现在搜索结果中
- **实时更新**:已发布且有权访问的技能在索引刷新后可被搜索
- **标签规范**:建议使用统一的标签命名规范,便于过滤
- **搜索提示**:支持搜索建议和自动补全(前端实现)

View file

@ -138,7 +138,7 @@ visibility: PUBLIC
发布后,[Skill Scanner](/guide/scanner) 会自动扫描技能包,检测潜在的安全风险。扫描结果会显示在技能包详情页。
6. **等待审核**(如果命名空间开启了审核)
6. **等待审核**(以返回状态为准)
团队管理员会收到审核通知,审核通过后技能包正式发布。
@ -146,6 +146,16 @@ visibility: PUBLIC
技能包可以通过搜索发现,其他人可以通过 CLI 或 Web UI 下载使用。
## 提交成功不等于发布成功
上传后查看返回状态及“我的技能”中的本次版本。普通 PUBLIC 和 NAMESPACE_ONLY 上传要求扫描已启用,版本先进入 `SCANNING`,扫描完成后回到 `PENDING_REVIEW`,审核批准才发布。PRIVATE 上传在完成已配置的扫描后停留在 `UPLOADED`,还需通过确认发布操作发布。特权自动发布使用另一条路径。
`SCAN_FAILED` 表示扫描执行失败,不代表已经判定包有害;扫描完成也可能有风险发现。上传成功、HTTP 成功或 CLI 正常退出,都不能单独证明版本已 `PUBLISHED`。更新审核期间,公众继续看到已发布版本,有权维护者可以预览待审版本。
### 创作草稿的边界
创作 API 支持私有草稿、文件编辑和结构校验,目前不包含网页创作工作台或自动发布。校验通过不代表执行过技能,也不代表安全检查通过。创作草稿与上传后等待审核的技能版本是不同对象。
## 合规声明
技能作者可以在 `SKILL.md` frontmatter 中添加 `x-astron-compliance`,声明该技能版本与某些合规标准、控制项或安全知识库条目的映射关系。
@ -194,7 +204,7 @@ Content-Type: multipart/form-data
# 参数
file: MultipartFile (必需)
visibility: PUBLIC | PRIVATE | INTERNAL (可选,默认 PUBLIC)
visibility: PUBLIC | PRIVATE | NAMESPACE_ONLY (可选,默认 PUBLIC)
```
**参数说明**:
@ -202,7 +212,7 @@ visibility: PUBLIC | PRIVATE | INTERNAL (可选,默认 PUBLIC)
|------|------|------|
| namespace | string | 命名空间 slug(路径参数) |
| file | MultipartFile | 技能包 zip 文件 |
| visibility | enum | 可见性级别:PUBLIC(公开)、PRIVATE(私有)、INTERNAL(内部) |
| visibility | enum | 可见性级别:PUBLIC(公开)、PRIVATE(私有)、NAMESPACE_ONLY(空间成员可见) |
**获取 Skill 详情**:
```bash
@ -240,7 +250,7 @@ GET /api/v1/skills/{namespace}/{slug}/resolve?version=^1.2.0
- **首次发布**:版本号建议从 `0.1.0` 或 `1.0.0` 开始
- **标签管理**:`latest` 标签会自动指向最新的稳定版本
- **审核流程**:如果命名空间开启了审核,新版本需要等待管理员批准
- **审核流程**:普通 PUBLIC / NAMESPACE_ONLY 上传需要扫描与审核;PRIVATE 上传后还需确认发布
- **文件大小限制**:单个技能包不超过 100MB(可配置)
- **命名规范**:Skill slug 支持小写字母、数字、连字符和 Unicode 字符
- **版本不可变**:已发布的版本不能修改,只能发布新版本

View file

@ -0,0 +1,70 @@
# 技能套装:安装与使用
Skill Suite(技能套装)把一组已发布 Skill 的精确版本组织成一个有独立名称和版本的集合,并指定一个 Entry Skill(入口技能)。安装后,每个成员仍是独立的技能目录。
## Skill、Suite 和 Bundle 的区别
| 类型 | 用途 | 使用方式 |
| --- | --- | --- |
| Skill | 一个包含 `SKILL.md` 的技能包 | `skillhub install` 安装,交给 Agent 使用 |
| Skill Suite | 固定版本的技能集合,包含一个入口技能 | `skillhub suite install` 安装全部成员 |
| Suite Bundle | 作者批量上传成员和套装定义的 ZIP 或文件夹 | 在网页中导入、预览、确认,再完成发布审核 |
Bundle 是[创作与导入格式](./suite-bundle),不是安装后需要执行的程序。套装也不是工作流引擎:是否串联成员、如何分派任务,由入口及成员的 `SKILL.md` 决定。普通技能可以独立安装,不必安装它关联的所有套装。
## 找到并安装套装
在技能详情中查看关联套装,进入套装详情,确认入口、成员版本和可安装状态。卡片上的关联标识只表示收录关系。普通 `skillhub search` 搜索 Skill;安装同名 Suite 必须显式使用 `suite` 子命令。
以下 `@team/example-suite` 是占位示例,请替换为实际坐标;需要访问受限内容时先登录对应 Registry。
```bash
skillhub login
# 在目标项目根目录安装给 Codex
skillhub suite install @team/example-suite --scope project --agent codex
# 或安装给 Claude Code
skillhub suite install @team/example-suite --scope project --agent claude-code
# 指定套装版本;用户级安装供该用户的项目使用
skillhub suite install @team/example-suite --version 1.0.0 --scope user --agent codex
```
`--registry <url>` 可选择私有部署。服务端必须声明 `skill-suite-v1` 能力;CLI 出现 unknown command 时先检查 `skillhub version` 和 `skillhub help suite`,不要把单个 Skill 安装命令当成替代。
项目级 Codex 安装结果如下;Claude Code 使用 `.claude/skills`,用户级则在主目录下的对应位置:
```text
.codex/skills/
├── entry-skill/SKILL.md
├── member-a/SKILL.md
└── member-b/SKILL.md
```
目录名是各成员的 slug,不会生成一个合并后的同名套装技能。安装会下载并校验全部成员;成员不可访问或不可安装时,不能用最新版本悄悄替换固定版本。
## 安装后开始使用
1. 在对应 Agent 中打开安装目标项目,按该 Agent 的机制刷新技能或开启新会话。
2. 检查安装输出中的路径,确认入口目录有 `SKILL.md`,并确认 Agent 能发现它。
3. 阅读入口说明,补齐其要求的工具、环境变量或外部服务配置。安装技能文件不等于安装这些运行依赖。
4. 明确请求使用入口,例如:“请使用入口技能 `<入口名称>` 完成下面的任务,并按照它的说明使用其他成员:……”
套装坐标用于安装管理;调用时使用实际入口技能的名称,也可直接使用单个成员。Agent 的触发语法和加载时机由对应产品决定,SkillHub 不提供通用的 `suite run` 命令。
## 检查、升级与卸载
```bash
skillhub suite check @team/example-suite
skillhub suite upgrade @team/example-suite --check
skillhub suite upgrade @team/example-suite
skillhub suite remove @team/example-suite
```
`check` 显示本地成员状态和远端版本信息;`upgrade --check` 只预览变更。成员单独发布新版本不会改变已安装套装,升级遵循新 SuiteVersion 的固定成员清单。套装管理的目标应使用套装升级流程。
`--scope`、`--agent`、`--dir` 和 `--version` 仅用于 `suite install`;后续操作使用本地安装记录。卸载保留直接安装、被其他套装共享或本地修改过的成员。不要为消除提示直接删除 inventory。
## 创建套装
已有成员均已发布时,可通过网页套装编辑器选择精确成员版本和入口。需要同时上传多个本地成员时使用 [Suite Bundle](./suite-bundle)。PUBLIC 和 NAMESPACE_ONLY 套装需要套装级审核;PRIVATE 可直接发布。成员扫描和审核仍按各自 Skill 的流程执行。
每个版本最多 100 个不同成员,必须从成员中指定一个入口;不支持嵌套套装、版本范围或外部 Registry 成员。CLI 当前提供安装管理,不提供 `suite publish` 或直接读取创作定义文件的命令。

View file

@ -11,7 +11,7 @@ SkillHub 提供了丰富的社交功能,让团队成员可以互动、分享
- **星标(Star)**:收藏喜欢的技能包,方便后续查找
- **评分(Rating)**:给技能包打分(1-5 星),帮助其他人判断质量
- **下载统计**:记录下载次数,展示热门技能包
- **通知系统**:及时接收审核结果、评论回复等通知
- **通知系统**:及时接收审核、成员及治理等事件通知
**社交数据**:
@ -36,7 +36,7 @@ SkillHub 提供了丰富的社交功能,让团队成员可以互动、分享
**场景三:查看通知**
收到审核通过的通知,或者有人评论了你的技能包。
收到审核通过的通知,或其他受支持的治理事件通知。
![操作截图](/screenshots/notifications.png)
@ -82,7 +82,7 @@ SkillHub 提供了丰富的社交功能,让团队成员可以互动、分享
1. 访问 `/dashboard/stars`
2. 查看所有星标的技能包
3. 按星标时间、更新时间排序
3. 分页浏览收藏列表;需要筛选时到搜索页启用“仅收藏”
4. 快速访问常用技能包
## API 接口
@ -102,13 +102,6 @@ DELETE /api/v1/skills/{skillId}/star
GET /api/v1/skills/{skillId}/star
```
**响应示例**:
```json
{
"starred": true,
"starredAt": "2026-03-15T10:30:00Z"
}
```
**评分技能包**:
```bash
@ -123,7 +116,7 @@ Content-Type: application/json
**参数说明**:
| 参数 | 类型 | 说明 |
|------|------|------|
| skillId | string | 技能包 ID(路径参数) |
| skillId | number | 技能包 ID(路径参数) |
| score | number | 评分(1-5,必需) |
**获取我的星标**:
@ -154,13 +147,8 @@ POST /api/v1/admin/skill-reviews/{reviewId}/hide
POST /api/v1/admin/skill-reviews/{reviewId}/restore
```
**响应示例**:
```json
{
"score": 5,
"ratedAt": "2026-03-15T10:30:00Z"
}
```
响应使用统一 API 封装。`GET .../star` 的 `data` 是布尔值;`GET .../rating` 返回 `score` 和 `rated`。修改接口返回空 `data`,不会返回评分时间。技能 ID 为数值。
## 注意事项
@ -169,6 +157,6 @@ POST /api/v1/admin/skill-reviews/{reviewId}/restore
> **评价规则**:只有已发布技能可以评价;公开列表只显示可见评价。并发修改发生冲突时,刷新详情后重试。
- **星标数量**:技能包的星标数会显示在搜索结果和详情页
- **平均评分**:技能包的平均评分会影响搜索排序
- **平均评分**:平均评分供选择技能时参考,不是搜索页的独立排序选项
- **通知设置**:用户可以在设置中关闭某些类型的通知
- **下载统计**:每次下载都会增加下载计数,用于热门排序

View file

@ -2,6 +2,8 @@
Suite Bundle 用一次 ZIP 或文件夹上传,为 Suite 创建首个版本,或基于一个已发布版本创建新版本。系统先展示成员差异,只有用户明确确认后才进入成员 Skill 的正常发布和审核流程。
安装和调用请先阅读[技能套装使用指南](./skill-suites)。本页面向批量导入内容的作者。`SUITE.yaml`(`kind: SkillSuiteBundle`)与套装设计中的 `suite.yaml`(`kind: SkillSuite`)不是同一种文件。
## 归档结构
归档根目录必须且只能有一个 `SUITE.yaml`。每个携带包的成员使用独立目录,目录根部必须包含 `SKILL.md`。未声明的 `SKILL.md`、目录重叠、路径穿越、重复路径、超出大小或文件数限制都会阻止预览。
@ -11,8 +13,6 @@ SUITE.yaml
skills/
intake/
SKILL.md
summarizer/
SKILL.md
```
```yaml
@ -28,7 +28,7 @@ spec:
summary: 串联病历接收与摘要生成
overview: |
接收结构化病历,完成字段校验后生成摘要。
入口技能负责接收和分派,摘要技能负责输出最终结果。
入口技能使用共享词典完成字段校验。
visibility: PUBLIC
entry: "@global/intake"
members:

View file

@ -34,7 +34,7 @@ features:
link: /guide/namespace
- icon: ✅
title: 审核与治理
details: 多级审核工作流,举报系统,确保技能包质量
details: 技能与套装审核流程,举报系统,确保技能包质量
link: /guide/review
- icon: ⭐
title: 用户交互与社交

View file

@ -10,10 +10,10 @@ SkillHub 解决了这个问题。它提供了一个**私有、可控、易用**
## 核心价值
- **3 分钟发布**:从本地开发到全球分发,只需一条命令
- **统一分发**:上传技能包并跟踪扫描、审核和发布状态
- **企业级权限**:基于命名空间的 RBAC,支持团队协作和审核流程
- **完整生命周期**:版本管理、标签系统、审核工作流、归档机制
- **开箱即用**:一条 curl 命令启动完整环境
- **部署选择**:Docker Compose 和 Kubernetes,按环境配置依赖和认证
- **安全扫描**:内置 Skill Scanner,自动检测安全风险
- **数据主权**:完全自托管,所有数据都在你的防火墙内
@ -23,12 +23,12 @@ SkillHub 解决了这个问题。它提供了一个**私有、可控、易用**
| 层级 | 技术 | 说明 |
|------|------|------|
| **前端** | React 19 + Vite + TanStack Router | 现代化 SPA,支持中英文切换 |
| **后端** | Java 21 + Spring Boot 3.2 | 企业级 REST API |
| **数据库** | PostgreSQL 16 | 全文搜索、Flyway 自动迁移 |
| **缓存** | Redis 7 | 会话管理、热点缓存 |
| **存储** | MinIO / S3 | 技能包文件存储,支持本地和云端 |
| **部署** | Docker Compose / K8s | 一键启动,支持自托管 |
| **前端** | React + Vite + TanStack Router | 现代化 SPA,支持多语言切换 |
| **后端** | Java 21 + Spring Boot | 企业级 REST API |
| **数据库** | PostgreSQL | 全文搜索、Flyway 自动迁移 |
| **缓存** | Redis | 会话管理、热点缓存 |
| **存储** | 本地文件 / S3 兼容存储 | 技能包文件存储,支持本地和云端 |
| **部署** | Docker Compose / K8s | 按部署配置自托管 |
## 核心功能一览
@ -37,6 +37,23 @@ SkillHub 解决了这个问题。它提供了一个**私有、可控、易用**
| [Skill 发布与版本管理](/guide/skill-publish) | 一键发布技能包,语义化版本管理 |
| [Skill 搜索与发现](/guide/skill-discovery) | 全文搜索、智能过滤、权限感知 |
| [命名空间与团队管理](/guide/namespace) | 基于命名空间的 RBAC 权限体系 |
| [审核与治理](/guide/review) | 多级审核工作流、举报系统 |
| [审核与治理](/guide/review) | 技能与套装审核流程、举报系统 |
| [安全扫描](/guide/scanner) | 内置 Skill Scanner,多引擎安全分析 |
| [用户交互与社交](/guide/social) | 星标、评分、通知系统 |
## 先理解三个对象
| 对象 | 用途 | 下一步 |
| --- | --- | --- |
| Skill | 带有 `SKILL.md` 的单个技能包,安装后由 Agent 发现和使用 | [快速开始](./quickstart.md) |
| Skill Suite | 固定成员版本的技能集合,指定一个成员作为入口技能 | [套装安装与使用](./guide/skill-suites.md) |
| Suite Bundle | 发布者批量上传套装定义和成员包的格式 | [批量导入](./guide/suite-bundle.md) |
注册中心负责分发和治理;技能的实际执行发生在使用者的 Agent 环境中。安装套装不会自动运行全部成员。
## 按角色阅读
- 使用者:[CLI](./guide/cli.md)、[搜索与发现](./guide/skill-discovery.md)、[FAQ](./faq.md)。
- 创作者:[发布与版本管理](./guide/skill-publish.md)、[套装](./guide/skill-suites.md)、[审核](./guide/review.md)。
- 管理员:[命名空间](./guide/namespace.md)、[部署与升级](./guide/deployment.md)、[Kubernetes](./guide/kubernetes.md)。
- 集成开发者:[Runtime 契约](./guide/runtime-integration.md)、[仓库文档索引](https://github.com/iflytek/skillhub/blob/main/docs/README.md)。

View file

@ -1,234 +1,96 @@
# 快速开始
## 一键部署
先选择你的目标:使用已有技能不需要部署 SkillHub;团队自托管和源码开发使用不同入口。
使用 curl 命令快速部署 SkillHub(包含所有服务:Web UI、Backend API、PostgreSQL、Redis、MinIO、Skill Scanner):
| 目标 | 从这里开始 |
| --- | --- |
| 搜索、安装并使用技能 | 本页的安装流程 |
| 使用一组配套技能 | [技能套装](./guide/skill-suites.md) |
| 发布自己的技能 | [发布与版本管理](./guide/skill-publish.md) |
| 批量上传套装和成员 | [Suite Bundle 导入](./guide/suite-bundle.md) |
| 部署团队注册中心 | [Docker 部署](./guide/deployment.md) / [Kubernetes](./guide/kubernetes.md) |
| 修改 SkillHub 源码 | [开发手册](https://github.com/iflytek/skillhub/blob/main/docs/dev-workflow.md) |
## 1. 安装 CLI,选择注册中心
```bash
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up
```
**国内用户(阿里云镜像):**
```bash
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun
```
**自定义参数**:
```bash
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up \
--version v0.2.0 \
--home /opt/skillhub \
--aliyun
```
**参数说明**:
| 参数 | 说明 | 示例 |
|------|------|------|
| `--version <tag>` | 指定版本 | `--version v0.2.0` |
| `--aliyun` | 使用阿里云镜像(国内推荐) | `--aliyun` |
| `--home <dir>` | 指定安装目录 | `--home /opt/skillhub` |
| `--no-scanner` | 禁用安全扫描服务 | `--no-scanner` |
| `--mirror-registry <url>` | 自定义镜像仓库 | `--mirror-registry registry.example.com` |
**其他命令**:
```bash
# 停止服务
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- down
# 查看服务状态
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- ps
# 查看日志
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- logs
# 清理所有数据
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- clean
```
部署成功后访问:
- **Web UI**: http://localhost:3000
- **Backend API**: http://localhost:8080
- **API 文档**: http://localhost:8080/swagger-ui.html
- **Skill Scanner**: http://localhost:8000
## 本地开发
如果需要从源码启动开发环境:
```bash
# 克隆仓库
git clone https://github.com/iflytek/skillhub.git
cd skillhub
# 启动所有服务(包含 Scanner)
make dev-all
```
### 国内开发者注意事项
如果 `make dev-all` 后端启动失败,常见原因:
1. **Maven 依赖下载超时**
项目已内置阿里云镜像配置(`server/.mvn/settings.xml`),但 Maven 不会自动读取项目级配置。需要手动配置:
```bash
# 方式一:复制到用户目录(推荐)
mkdir -p ~/.m2
cp server/.mvn/settings.xml ~/.m2/settings.xml
# 方式二:每次构建时指定
cd server && ./mvnw -s .mvn/settings.xml package
```
2. **Java 版本不匹配**
SkillHub 要求 Java 21+:
```bash
java -version
```
3. **端口冲突**
检查 8080 端口是否被占用:
```bash
lsof -i :8080
```
详细的错误排查步骤,请查看 [常见问题](faq.md#本地开发启动失败)。
## 登录系统
### 方式一:使用内置管理员账号
SkillHub 内置了一个超级管理员账号,可以直接登录:
- **用户名**:`admin`
- **密码**:`ChangeMe!2026`
> **安全提示**:生产环境部署后,请立即修改默认密码。
### 方式二:注册新账号
访问 http://localhost:3000/register 注册新账号。
### 方式三:使用 Mock 用户(仅本地开发)
本地开发时,可以使用 Mock 用户头快速登录:
```bash
# 普通用户
curl -H "X-Mock-User-Id: local-user" http://localhost:8080/api/v1/auth/me
# 超级管理员
curl -H "X-Mock-User-Id: local-admin" http://localhost:8080/api/v1/auth/me
```
在浏览器中,可以通过浏览器插件(如 ModHeader)添加 `X-Mock-User-Id` 请求头。
## 安装 CLI 工具
推荐使用第一方 SkillHub CLI 管理技能包:
```bash
# 安装并配置 SkillHub 注册中心地址
npm install -g @astron-team/skillhub
export SKILLHUB_REGISTRY=http://localhost:8080
# 搜索技能包
skillhub search email
# 安装技能包
skillhub install my-skill
# 发布技能包
skillhub publish ./my-skill --namespace my-team
skillhub version
```
已有 ClawHub 工作流仍可通过兼容层进行搜索和安装;新流程及发布操作优先使用 SkillHub CLI。
## 发布第一个技能包
### 使用 CLI 工具发布(推荐)
1. **准备技能包**
创建一个简单的技能包目录:
```
my-skill/
├── skill.md # 技能描述
├── package.json # 元数据
└── scripts/ # 脚本文件
└── main.py
```
2. **使用 CLI 发布**
默认使用 `https://skill.xfyun.cn`。使用自托管实例时,在当前终端设置实际地址:
```bash
# 配置注册中心
export SKILLHUB_REGISTRY=http://localhost:8080
# 发布到指定命名空间
skillhub publish ./my-skill --namespace my-team
export SKILLHUB_REGISTRY=https://skillhub.example.com
```
3. **等待安全扫描**
发布后,Skill Scanner 会自动扫描技能包,检测潜在的安全问题:
- 恶意代码检测
- 敏感信息泄露
- 依赖漏洞扫描
- 行为分析
扫描结果会显示在技能包详情页。
4. **等待审核**(如果命名空间开启了审核)
管理员会收到通知,审核通过后技能包正式发布。
### 使用 Web UI 发布
1. 访问 http://localhost:3000/dashboard/publish
2. 选择命名空间(如果没有,先创建一个)
3. 上传 zip 文件
4. 选择可见性(PUBLIC / PRIVATE / INTERNAL)
5. 点击「发布」
## 搜索和下载技能包
### 使用 CLI 工具
公开技能可匿名搜索和安装。发布、访问受限资源等操作需要登录:
```bash
skillhub login
skillhub whoami
```
按终端提示在浏览器完成登录和设备码确认。远程终端可用 `skillhub login --no-open`。账号是否可以注册、使用哪些登录方式,由实例配置决定。
## 2. 找到技能并安装
```bash
# 搜索技能包
skillhub search pdf
# 安装技能包
skillhub install pdf-parser
# 安装指定命名空间的技能包
skillhub install pdf-parser --namespace my-team
```
### 使用 Web UI
在网页详情确认用途、版本、可见性及使用说明,然后复制真实坐标。下面的 `@team/example-skill` 是占位示例,必须替换成搜索结果中的坐标。
1. 访问 http://localhost:3000/search
2. 输入关键词搜索
3. 点击技能包查看详情
4. 点击「下载」或复制安装命令
## 升级 SkillHub
使用 curl 命令升级到最新版本:
在目标项目根目录执行:
```bash
# 升级到最新版本
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- pull
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- down
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up
# 升级到指定版本
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version v0.2.0
skillhub install @team/example-skill --scope project --agent codex
skillhub list --agent codex
```
> **注意**:升级前建议备份数据库和对象存储。
Claude Code 用户改用 `--agent claude-code`。希望多个项目共用时,使用 `--scope user`。
项目级 Codex 安装目录为 `.codex/skills/<slug>/`,Claude Code 为 `.claude/skills/<slug>/`;用户级路径位于用户主目录。
## 3. 在 Agent 中使用
安装完成后,在目标 Agent 中打开项目,必要时新建会话或重新加载技能。先确认 Agent 能发现该技能,再提出具体任务,例如:
> 请使用 example-skill,按它的说明处理以下材料:……
实际调用名称以技能 `SKILL.md` 中的 `name` 和 Agent 显示结果为准。安装不会自动执行技能,也不会代为配置成员所需的工具或凭据。
如果 Agent 没发现技能,检查 CLI 输出路径、当前项目、安装范围和目标 Agent,参见 [FAQ](./faq.md)。
整套安装使用 `skillhub suite install`,之后从套装的入口技能开始;详见 [技能套装使用指南](./guide/skill-suites.md)。
## 4. 更新和管理
```bash
skillhub upgrade @team/example-skill --check
skillhub upgrade @team/example-skill
```
检查计划后再更新。保留需要的本地修改;不要把 `--force` 当作默认参数。卸载、同步团队工作区和完整命令说明见 [CLI 指南](./guide/cli.md)。
## 5. 发布自己的技能
技能包根目录必须包含大写 `SKILL.md`,最小内容如下:
```markdown
---
name: example-skill
description: Describe when to use this skill and what it does.
---
# Example skill
Explain the inputs, steps, expected output, and required tools.
```
可以按需添加 `scripts/`、`references/` 和 `assets/`;不要求 `package.json`。
先在 Web 创建或加入有发布权限的命名空间,再按照 [发布指南](./guide/skill-publish.md) 准备版本并上传:
```bash
skillhub publish ./example-skill --namespace my-team
```
命令提交成功不代表版本已发布。查看返回的详情地址,跟踪扫描、审核和最终状态;只有满足发布条件的版本才进入正常安装流程。