scriptoriumadmin/skillhub
1
0
Fork 0
mirror of https://github.com/iflytek/skillhub.git synced 2026-11-14 09:01:16 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

docs(site): repair P0 states permissions and troubleshooting

Browse source 
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
This commit is contained in:
XiaoSeS 2026-11-03 14:13:40 +08:00
parent aedbcb6b54
commit fe2049c19f
17 changed files with 676 additions and 490 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
docs/skillhub/en/faq.md
View file

@ -6,7 +6,7 @@ A: SkillHub provides a self-hosted registry, namespace permissions, publication
## Q: How do I back up data?
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).
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.html).
## Q: What authentication methods are supported?
@ -39,11 +39,11 @@ 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.
Follow [Quick Start](./quickstart.html) 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: 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).
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.html).
## Q: How do I monitor SkillHub?
@ -57,11 +57,11 @@ For physical isolation, you can deploy a separate SkillHub instance for each ten
## Q: How do I upgrade SkillHub?
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.
A: Follow the [deployment guide](./guide/deployment.html), 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: 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).
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.html).
## Q: How do I search for or operate on a skill package within a specific namespace?
@ -73,11 +73,11 @@ A: Choose the runtime script, release Compose, Kubernetes Kustomize, or the Helm
## Q: What Kubernetes version does the Kubernetes deployment require?
A: The official [Kubernetes deployment guide](./guide/kubernetes.md) requires Kubernetes **v1.24 or later**, a configured `kubectl`, and a default StorageClass for PVCs; an nginx ingress controller is needed if you want domain-based access. Older clusters have not been validated, so upgrade the cluster before deploying.
A: The official [Kubernetes deployment guide](./guide/kubernetes.html) requires Kubernetes **v1.24 or later**, a configured `kubectl`, and a default StorageClass for PVCs; an nginx ingress controller is needed if you want domain-based access. Older clusters have not been validated, so upgrade the cluster before deploying.
## Q: After deployment, I enter the correct username and password but get redirected back to the login page?
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).
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.html).
## Q: How do I change the admin password? Why don't my config changes take effect?
@ -89,11 +89,11 @@ A: The web password-reset flow uses email verification; the authenticated change
## Q: Can a skill have a Chinese name?
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).
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.html).
## Q: Can unreviewed skills 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).
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.html).
## Q: How do I hide or remove third-party SSO login options on the login page?
@ -104,6 +104,14 @@ So there are two ways to hide one:
- Leave the matching environment variable unset (for example, omit `OAUTH2_FEISHU_CLIENT_ID`). No config file change needed.
- Or edit `application.yml` and comment out or delete the relevant registration block (`github`, `gitlab`, `feishu`, `dingtalk`) under `spring.security.oauth2.client.registration`, along with its `provider` section. Spring Boot then won't create that registration at startup.
## Q: Can skills still be uploaded or published with scanning disabled?
A: `runtime.sh --no-scanner` disables registry scanning and does not start the scanner container. For **ordinary new uploads**, `PUBLIC` or `NAMESPACE_ONLY` is rejected while scanning is disabled. A `PRIVATE` upload can remain in `UPLOADED` and still requires confirmation to publish. Upload success does not mean publication; do not repeatedly upload the same version to bypass this prerequisite.
Expanding the visibility of an already published private skill is a separate path. A qualifying scan report for its latest version may be reused, allowing visibility review even while the scanner is disabled. Without a reusable report, scanning must be restored first. See [scanning](./guide/scanner.html) for report conditions and diagnostics; disabling the scanner does not imply that every action on an existing version is unavailable.
Sources: [runtime script](https://github.com/iflytek/skillhub/blob/main/scripts/runtime.sh), [new-upload rules](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillPublishService.java), and [visibility-change rules](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillVisibilityService.java).
## Q: Is SkillHub's security scanning (Skill Scanner) developed in-house by iFLYTEK? What license does it use?
A: SkillHub has built-in security scanning. The scanner integration, task orchestration, audit persistence, and deployment integration are implemented by the iFLYTEK team; the underlying scanning service uses Cisco's [cisco-ai-skill-scanner](https://github.com/cisco-ai-defense/skill-scanner) (Apache License 2.0, copyright Cisco).
@ -171,7 +179,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: 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).
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.html).
## Q: Does SkillHub support MySQL?
@ -270,7 +278,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: 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.
A: Use [Suites](./guide/skill-suites.html) 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: Where do I submit a saved Skill Suite draft for review, and why is the button missing or disabled?
@ -279,20 +287,20 @@ A: Open the management page for that Suite version and use the publishing checkl
- **No button:** confirm that you are managing a version you can operate on, rather than viewing its marketplace preview. The action appears only when the server allows your account to submit or publish that version; both permissions and version state affect available actions.
- **Disabled button:** complete the summary and overview, select an available entry Skill, and resolve blocked member versions. Every checklist item must be ready, with no submission already pending.
See [creating and managing Skill Suites](./guide/skill-suites.md). If an older installation differs from the guide, report the Server/Web versions, Suite state and a redacted screenshot. Skill or Agent publishing pages are not substitutes for the Suite publishing page.
See [creating and managing Skill Suites](./guide/skill-suites.html). If an older installation differs from the guide, report the Server/Web versions, Suite state and a redacted screenshot. Skill or Agent publishing pages are not substitutes for the Suite publishing page.
## Q: Does a Suite overview become a callable skill after installation?
A: No. The overview explains the intended tasks, member responsibilities and boundaries to reviewers and users. Installation delivers separate member skill directories; it does not combine the overview into a new Suite `SKILL.md`, and there is no universal `suite run` command.
Put execution order, member-call instructions and result validation in the **entry and member `SKILL.md` files**. In the installation target project, confirm that the Agent has discovered the entry Skill, then ask it to use that entry for the task. The Suite coordinate manages installation; actual use starts with the entry Skill. Installing member files does not configure their required tools or services. Follow the [Skill Suite usage guide](./guide/skill-suites.md).
Put execution order, member-call instructions and result validation in the **entry and member `SKILL.md` files**. In the installation target project, confirm that the Agent has discovered the entry Skill, then ask it to use that entry for the task. The Suite coordinate manages installation; actual use starts with the entry Skill. Installing member files does not configure their required tools or services. Follow the [Skill Suite usage guide](./guide/skill-suites.html).
## Q: What should I do if I encounter issues?
A: You can get help through the following channels:
- **GitHub Issues**: https://github.com/iflytek/skillhub/issues
- **Online Docs**: https://iflytek.github.io/skillhub/
- **Online Docs**: [SkillHub](./index.html)
- **Documentation**: Refer to the project README.md
- **Community Discussions**: https://github.com/iflytek/skillhub/discussions

38
docs/skillhub/en/guide/index.md
View file

@ -1,46 +1,46 @@
# Documentation map
Choose the task you want to complete. Start with [Quick Start](../quickstart.md) to install your first skill; deployment and development guides are not prerequisites.
Choose the task you want to complete. Start with [Quick Start](../quickstart.html) to install your first skill; deployment and development guides are not prerequisites.
## Start
- [Accounts and access tokens](./account-access.md): web sign-in, CLI authorization, token expiry, and password reset.
- [Introduction](../introduction.md): understand the registry's purpose.
- [Quick start](../quickstart.md): find, install, and use a skill in your Agent.
- [FAQ](../faq.md): troubleshoot login, installation, and configuration.
- [Accounts and access tokens](./account-access.html): web sign-in, CLI authorization, token expiry, and password reset.
- [Introduction](../introduction.html): understand the registry's purpose.
- [Quick start](../quickstart.html): find, install, and use a skill in your Agent.
- [FAQ](../faq.html): troubleshoot login, installation, and configuration.
## Use skills
| Your task | Read |
| --- | --- |
| Find a skill and inspect its versions and visibility | [Find and install skills](./skill-discovery.md) |
| Install pinned members together and start with their entry skill | [Manage skill suites](./skill-suites.md) |
| Choose an Agent and scope; update, remove, or sync a workspace | [CLI reference](./cli.md) |
| Save and rate skills, and check notifications | [Stars, ratings and notifications](./social.md) |
| Find a skill and inspect its versions and visibility | [Find and install skills](./skill-discovery.html) |
| Install pinned members together and start with their entry skill | [Manage skill suites](./skill-suites.html) |
| Choose an Agent and scope; update, remove, or sync a workspace | [CLI reference](./cli.html) |
| Save and rate skills, and check notifications | [Stars, ratings and notifications](./social.html) |
## Author skills
Prepare `SKILL.md` and its supporting files, then submit. An accepted submission still needs its scan, review, and final version state checked.
- [Publish and update skills](./skill-publish.md): package structure, metadata, uploading, and version management.
- [Import a bundle](./suite-bundle.md): upload content as an author, inspect member changes, and confirm. To install an existing suite, use the guide above.
- [Publish and update skills](./skill-publish.html): package structure, metadata, uploading, and version management.
- [Import a bundle](./suite-bundle.html): upload content as an author, inspect member changes, and confirm. To install an existing suite, use the guide above.
## Team governance
- [Manage namespaces](./namespace.md): members, roles, and resource visibility.
- [Review submissions](./review.md): handle Skill and Suite applications.
- [Configure scanning](./scanner.md): connect the scanning service and interpret results.
- [Manage namespaces](./namespace.html): members, roles, and resource visibility.
- [Review submissions](./review.html): handle Skill and Suite applications.
- [Configure scanning](./scanner.html): connect the scanning service and interpret results.
## Deploy and operate
Read these guides when you need to run your own registry. Choose a deployment method before configuring optional integrations.
- [Deploy with Docker](./deployment.md): installation, configuration, upgrades, and backups.
- [Deploy on Kubernetes](./kubernetes.md): cluster and Helm deployment.
- [Frontend analytics](./frontend-analytics.md): optional manual integration, consent, and failure acceptance.
- [Skill avatars and moderation](./skill-avatars.md): administrator configuration for image moderation providers.
- [Deploy with Docker](./deployment.html): installation, configuration, upgrades, and backups.
- [Kubernetes deployment (Kustomize / Helm)](./kubernetes.html): choose either the manifest path or the separate Chart path.
- [Frontend analytics](./frontend-analytics.html): optional configuration-based integration, consent, and failure checks; match the guide to the deployed version.
- [Skill avatars and moderation](./skill-avatars.html): administrator configuration for image moderation providers.
## Develop and integrate
- [Integrate a runtime](./runtime-integration.md): registry API contracts for external runtimes.
- [Integrate a runtime](./runtime-integration.html): registry API contracts for external runtimes.
- [Development handbook (Chinese)](https://github.com/iflytek/skillhub/blob/main/docs/dev-workflow.md): local development and repository checks.

2
docs/skillhub/en/guide/kubernetes.md
View file

@ -1,6 +1,6 @@
# Kubernetes Deployment: Kustomize Configuration and Verification
This document explains how to deploy SkillHub on a Kubernetes cluster.
This page follows the Kustomize manifests under `deploy/k8s/`. Helm is a separate deployment path: use the [Chart README](https://github.com/iflytek/skillhub/blob/main/charts/skillhub/README.md) for values, Secrets and upgrades. Choose one path for an installation; do not apply both resource sets to the same release. Return to the [Docker deployment guide](./deployment.html) for that deployment path.
## Prerequisites

48
docs/skillhub/en/guide/namespace.md
View file

@ -2,9 +2,11 @@
The team-namespace creation action is shown to platform SKILL_ADMIN / SUPER_ADMIN roles. Other users should ask an authorized creator to create the space and invite them. Team ownership does not grant a platform role.
Creation permission source: [NamespacePortalCommandAppService](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/NamespacePortalCommandAppService.java).
## A Team Onboarding Sequence
1. Create a team namespace in My Namespaces with a stable slug and a readable display name. The slug is part of installation coordinates and cannot change with the team name.
1. Sign in with platform Skill Admin (`SKILL_ADMIN`) or Super Admin (`SUPER_ADMIN`) privileges, then create a team namespace in My Namespaces with a stable slug and a readable display name. The slug is part of installation coordinates and cannot change with the team name.
2. Add existing accounts or generate an invitation. Ordinary role selection offers MEMBER / ADMIN; ownership transfer is a separate action, not an Owner option in the role selector.
3. Select this namespace when publishing. Choose NAMESPACE_ONLY for team sharing; PRIVATE does not mean all team members can read it.
4. Administrators review submissions; authors track versions in My Skills.
@ -12,9 +14,29 @@ The team-namespace creation action is shown to platform SKILL_ADMIN / SUPER_ADMI
### Why Available Actions Differ
The page uses namespace type, state and server-provided capabilities to display freeze, unfreeze, archive, restore and delete actions. Owner or Admin is not an unconditional grant for every action. Owners and Admins can edit an ACTIVE team namespace; authorized Owners have a separate ownership transfer action. Frozen or archived namespaces make membership management read-only, while eligible administrators can still read invitation history.
The following matrix applies only to `TEAM` namespaces. Server-provided capabilities take precedence over role names. Platform roles and namespace membership roles are checked separately.
Freezing temporarily stops writes; unfreezing restores them. Archiving and permanent deletion are distinct. Check the target and impact in the confirmation, then verify the resulting namespace state and member page instead of relying only on a successful request.
| Namespace state | Namespace role | Governance actions | Conditions and limits |
| --- | --- | --- | --- |
| `ACTIVE` | Owner | Freeze, archive, delete; edit settings, manage members and transfer ownership | Deletion also requires the dependency check below |
| `ACTIVE` | Admin | Freeze; edit settings and manage members | Cannot archive, delete or transfer ownership |
| `ACTIVE` | Member | None of these governance actions | Owning a skill does not grant namespace management |
| `FROZEN` | Owner | Unfreeze, archive, delete | Deletion requires the dependency check; membership management is read-only |
| `FROZEN` | Admin | Unfreeze | Cannot archive or delete; membership management is read-only |
| `FROZEN` | Member | None of these governance actions | Writes are unavailable |
| `ARCHIVED` | Owner | Restore, delete | Restore enters `ACTIVE`; deletion requires the dependency check |
| `ARCHIVED` | Admin or Member | None of these governance actions | Previous editing rights do not grant restore permission |
| Namespace state | Platform role | Dedicated platform governance actions | Conditions and limits |
| --- | --- | --- | --- |
| `ACTIVE` | Super Admin (`SUPER_ADMIN`) | Freeze, archive | Namespace membership is not required; permanent deletion is not included |
| `FROZEN` | Super Admin (`SUPER_ADMIN`) | Unfreeze, archive | Namespace membership is not required |
| `ARCHIVED` | Super Admin (`SUPER_ADMIN`) | Restore to `ACTIVE` | Namespace membership is not required |
| Any | Skill Admin (`SKILL_ADMIN`) or User Admin (`USER_ADMIN`) | No dedicated governance grant from this role alone | Apply the preceding matrix if the account separately holds namespace membership |
Non-team types such as `GLOBAL` are immutable. Permanent deletion requires namespace ownership and the absence of skills, review tasks, promotion requests targeting the namespace, and authoring drafts. Any dependency blocks deletion; archiving does not remove it. Do not delete database records to bypass the check. Resolve dependencies through their resource management flows, then reload namespace settings to inspect the delete action.
Sources: [NamespaceAccessPolicy](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/namespace/NamespaceAccessPolicy.java), [NamespaceService](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/namespace/NamespaceService.java), and the Super Admin-only [AdminNamespaceController](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/admin/AdminNamespaceController.java). Verify the resulting namespace state, not only the request notification.
## Overview
@ -70,7 +92,7 @@ Discover a security issue in the namespace and temporarily freeze all publish op
**Create a Namespace**:
1. Navigate to `/dashboard/namespaces`
1. Verify platform `SKILL_ADMIN` or `SUPER_ADMIN` privileges before opening `/dashboard/namespaces`; ordinary members must contact an authorized creator.
2. Click "Create Namespace"
3. Fill in the information:
- Name: Team name (e.g., "iFlytek AI Team")
@ -79,7 +101,7 @@ Discover a security issue in the namespace and temporarily freeze all publish op
![Flow Diagram](/diagrams/namespace-create-flow.png)
4. Submit to create; you are automatically set as the Owner
4. Submit to create; the registry sets the creator as namespace Owner. This does not grant a platform role.
**Add Members**:
@ -128,7 +150,7 @@ Existing namespace and platform governance permissions remain unchanged. Removal
## API Reference
**Create a Namespace**:
```bash
```http
POST /api/v1/namespaces
Content-Type: application/json
@ -147,12 +169,12 @@ Content-Type: application/json
| description | string | Description (optional, max 512 characters) |
**Get Namespace Details**:
```bash
```http
GET /api/v1/namespaces/{slug}
```
**Update a Namespace**:
```bash
```http
PUT /api/v1/namespaces/{slug}
Content-Type: application/json
@ -163,7 +185,7 @@ Content-Type: application/json
```
**Add a Member**:
```bash
```http
POST /api/v1/namespaces/{slug}/members
Content-Type: application/json
@ -174,7 +196,7 @@ Content-Type: application/json
```
**Update Member Role**:
```bash
```http
PUT /api/v1/namespaces/{slug}/members/{userId}/role
Content-Type: application/json
@ -184,12 +206,12 @@ Content-Type: application/json
```
**Remove a Member**:
```bash
```http
DELETE /api/v1/namespaces/{slug}/members/{userId}
```
**Freeze a Namespace**:
```bash
```http
POST /api/v1/namespaces/{slug}/freeze
Content-Type: application/json
@ -199,7 +221,7 @@ Content-Type: application/json
```
**Unfreeze a Namespace**:
```bash
```http
POST /api/v1/namespaces/{slug}/unfreeze
```

117
docs/skillhub/en/guide/review.md
View file

@ -11,72 +11,76 @@
### Tracking and Revising as an Author
Use My Submissions to read status and decisions. Pending requests can be withdrawn when authorized. Withdrawal stops that review; it does not delete the prior published version or undo an approved global promotion. After rejection, revise according to the comments and use the supported resubmission action. A successful upload does not by itself reopen review.
Ordinary `PUBLIC / NAMESPACE_ONLY` uploads create review tasks; a `PRIVATE` upload is retained for explicit publishing confirmation or separate review submission. Use My Submissions to inspect tasks and feedback; an authorized submitter selects Withdraw on the pending task and confirms. Withdrawal stops that review; it does not delete the prior published version or undo an approved global promotion. After rejection, revise according to the comments and use the supported resubmission action. A successful upload does not by itself reopen review.
## Overview
## Identify the State Object
SkillHub provides a complete review workflow to ensure that skill packages published to the registry comply with team standards.
Identify the object first. A task can be `PENDING` while its version is `SCANNING`; the task state does not replace the version's `PENDING_REVIEW`.
The review mechanism operates on two levels:
- **Namespace Review**: Team administrators review skill packages within their namespace
- **Platform Review**: Platform administrators review skill packages promoted to the global scope
### Review Task States
![Concept Diagram](/diagrams/review-concept.png)
| State | Meaning | Responsible party | Next action |
| --- | --- | --- | --- |
| `PENDING` | Awaiting a decision | Authorized namespace reviewer or platform Skill Admin | Inspect the submitted content and scan result before deciding |
| `APPROVED` | The task was approved | Submitter | Verify the resulting version or profile change |
| `REJECTED` | Rejected with feedback | Submitter | Revise and submit again |
| `SUPERSEDED` | Replaced by a later request | Submitter and reviewer | Find the current request; do not decide the old task |
**Review Process**:
[ReviewTaskStatus](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/ReviewTaskStatus.java) has no `WITHDRAWN` value. Withdrawal is an operation, not evidence of a similarly named enum: the skill-version withdrawal path deletes the pending task and updates the version. See [ReviewService](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/ReviewService.java).
1. A developer publishes a skill package -> it enters the "Pending Review" state
2. An administrator receives a notification -> reviews the skill package details
3. The administrator makes a decision -> approve or reject
4. Upon approval -> the skill package is officially published
5. Upon rejection -> the developer receives feedback and can revise and resubmit
### Skill Version States
**Review Statuses**:
These values belong to a version; `DRAFT` is not the authoring API draft object.
| Status | Description |
|------|------|
| **PENDING** | Awaiting review |
| **APPROVED** | Approved |
| **REJECTED** | Rejected |
| **WITHDRAWN** | Withdrawn |
| State | Meaning | Responsible party | Next action |
| --- | --- | --- | --- |
| `DRAFT` | Draft version | Skill owner | Finish preparation; do not treat it as published |
| `SCANNING` | Scan in progress | Scanner | Wait for the report before approving ordinary review submissions |
| `SCAN_FAILED` | Scan execution failed | Operator and skill owner | Diagnose and retry; this is not a risk verdict |
| `UPLOADED` | Uploaded but not published | Skill owner | Use the available confirmation or submission action |
| `PENDING_REVIEW` | Awaiting a decision | Authorized reviewer | Inspect this version and decide |
| `PUBLISHED` | Published version | User and skill owner | Apply normal visibility rules; Agent execution is not thereby verified |
| `REJECTED` | Version not approved | Skill owner | Revise and resubmit |
| `YANKED` | Version withdrawn from distribution | Skill owner and user | Check an alternative version rather than assuming installability |
**Governance Features**:
See [SkillVersionStatus](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/SkillVersionStatus.java) and [publishing and updating skills](./skill-publish.html).
- **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
### Suite Bundle Operation States
## Identify what is being reviewed
| State | Meaning | Responsible party | Next action |
| --- | --- | --- | --- |
| `RUNNING` | Import is running | Import service | Track the original operation; do not confirm it twice |
| `WAITING_FOR_MEMBERS` | Waiting for member versions | Import service and member reviewers | Inspect member publishing or review progress |
| `BLOCKED_RETRYABLE` | Retryable blocker | Import author | Resolve the blocker, then retry the original operation |
| `REPREVIEW_REQUIRED` | Previous preview cannot be confirmed | Import author | Preview again and inspect differences |
| `SUITE_DRAFT_CREATED` | Suite draft created | Suite owner | Continue publishing in Suite management; this is not approval |
| `CANCELLED` | Operation cancelled | Import author | Inspect completed member actions; do not assume a full rollback |
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).
See [SkillSuiteBundleOperationStatus](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/suite/bundle/SkillSuiteBundleOperationStatus.java) and [Bundle recovery](./suite-bundle.html).
## Use Cases
### Avatar Review Results
**Case 1: Namespace Administrator Review**
An avatar candidate has three state dimensions and reuses the skill review request; it is not another single review-task enum.
A team administrator reviews skill packages submitted by team members to ensure compliance with team standards.
| Field and values | Meaning | Responsible party | Next action |
| --- | --- | --- | --- |
| Candidate `status`: `PENDING`, `ACTIVE`, `REJECTED`, `SUPERSEDED`, `REMOVED` | Waiting, in use, rejected, replaced, removed | Skill owner and authorized reviewer | Inspect the current candidate; an old candidate is not the active avatar |
| `machineStatus`: `SKIPPED`, `PENDING`, `PROCESSING`, `PASSED`, `BLOCKED`, `ERROR` | Skipped, waiting, running, allowed, blocked, execution error | Machine service and operator | Diagnose `ERROR`; `BLOCKED` is not a human rejection |
| `reviewStatus`: `NOT_REQUIRED`, `PENDING`, `APPROVED`, `REJECTED`, `APPEAL_PENDING` | No manual review, waiting, approved, rejected, appeal pending | Authorized reviewer and skill owner | Read the decision and use the current candidate's allowed action |
![Screenshot](/screenshots/review-list.png)
See [SkillAvatarCandidate](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/SkillAvatarCandidate.java); the response exposes candidate `status` as `candidateStatus`. Configuration, result locations and retry behavior are described in [skill avatar review](./skill-avatars.html).
**Case 2: Platform Administrator Reviews Promotions**
## Review Entry Points
A platform administrator reviews skill packages being promoted from a namespace to the global scope.
Role and self-review limits appear at the end of this page. Reports and promotion requests are handled separately.
**Case 3: Report Handling**
A user reports an inappropriate skill package, and an administrator investigates and takes action.
![Review subjects and responsibilities](/diagrams/review-concept.png)
![Review task list](/screenshots/review-list.png)
## Step-by-Step Guide
**Submitting for Review**:
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
**Reviewing Skill Packages**:
1. Navigate to `/dashboard/reviews`
@ -116,15 +120,6 @@ Review guidance:
SkillHub guarantees structural validation, traceable evidence references, and immutable version snapshots. It does not certify that the author's declaration is objectively compliant.
**Withdrawing a Review**:
If a developer discovers an issue, they can withdraw the submission before it is approved:
1. Navigate to "My Submissions"
2. Find the skill package pending review
3. Click "Withdraw"
4. Confirm the withdrawal
### Deleting a Promoted Skill
If permanent deletion reports "Use the reviewed revocation workflow to remove a promoted skill", manage the global publication from the source team skill's detail page. Hiding, archiving, or withdrawing a pending submission does not remove an approved global skill. Submitting a revocation request does not complete revocation either.
@ -148,7 +143,7 @@ If the revocation record is already `APPROVED` but the same error persists after
## API Reference
**Submit for Review**:
```bash
```http
POST /api/v1/reviews
Content-Type: application/json
@ -158,7 +153,7 @@ Content-Type: application/json
```
**Approve a Review**:
```bash
```http
POST /api/v1/reviews/{id}/approve
Content-Type: application/json
@ -168,7 +163,7 @@ Content-Type: application/json
```
**Reject a Review**:
```bash
```http
POST /api/v1/reviews/{id}/reject
Content-Type: application/json
@ -184,37 +179,37 @@ Content-Type: application/json
| comment | string | Review comment (optional for approval; provide a clear reason for rejection) |
**List Pending Reviews**:
```bash
```http
GET /api/v1/reviews/pending?namespaceId=123&page=0&size=20
```
**List My Submissions**:
```bash
```http
GET /api/v1/reviews/my-submissions?page=0&size=20
```
**Get Review Details**:
```bash
```http
GET /api/v1/reviews/{id}
```
**Get Skill Package Details Under Review**:
```bash
```http
GET /api/v1/reviews/{id}/skill-detail
```
**Download Review Package**:
```bash
```http
GET /api/v1/reviews/{id}/download
```
**Withdraw a Review**:
```bash
```http
POST /api/v1/reviews/{id}/withdraw
```
**Report a Skill Package**:
```bash
```http
POST /api/v1/skills/{namespace}/{slug}/reports
Content-Type: application/json

127
docs/skillhub/en/guide/scanner.md
View file

@ -11,17 +11,106 @@ Open the submitted version in skill details or review. Verify its version before
### Operator Troubleshooting Order
1. Check the effective Scanner URL and mode. The table below lists application defaults; release Compose uses `upload`. A container's localhost is not the host's localhost.
2. Check `/health` from the backend's network, then inspect actual scan requests and responses. Health alone does not prove a package was scanned.
3. Correlate version, request time and backend/Scanner logs. Distinguish temporary connectivity failures from analysis errors. Temporary unavailability can leave work pending for reclaim; waiting alone does not prove failure.
4. After repairing service or configuration, follow the original task. Retain version ID, status and error details for investigation without exposing package secrets or credentials.
These commands require operator access to this installation’s containers or Kubernetes namespace. Skill authors provide the version/report information instead; a registry business role does not grant host access. Select the actual deployment path first. Run Compose commands from the directory containing this installation's `.env.release` and `compose.release.yml`. Kubernetes examples use the Kustomize default namespace `skillhub`. For Helm, identify the Deployment names using the [Chart README](https://github.com/iflytek/skillhub/blob/main/charts/skillhub/README.md); do not mix deployment paths.
These probe parameters affect only this diagnostic request, not background scan-task configuration.
| Operation | Example value | Scope | Explanation |
| --- | --- | --- | --- |
| `wget -T` | 5s | DNS, connection and read timeouts | This is not the overall scan-task timeout. |
| `wget -t` | 1 attempt | This health request | It does not trigger a scan or change task state. |
1. Inspect the registry container’s declared enable flag and mode, then check the default `/health` from the same container. The command prints only `true` / `false`, `local` / `upload`, and fixed host names for the three official default addresses. Other values use fixed redaction markers without echoing the original configuration. URLs containing user information, queries, fragments, whitespace or shapes outside conservative HTTP(S) handling skip the probe. This is a diagnostic limitation, not registry URL-configuration validation. Missing variables use application defaults; check extra Spring overrides and custom health paths in protected installation configuration.
Compose:
```bash
docker compose --env-file .env.release -f compose.release.yml exec -T server sh -c '
enabled=${SKILLHUB_SECURITY_SCANNER_ENABLED:-true}
mode=${SKILLHUB_SECURITY_SCANNER_MODE:-local}
url=${SKILLHUB_SECURITY_SCANNER_URL:-http://localhost:8000}
case "$enabled" in true|false) ;; *) enabled=unrecognized_redacted ;; esac
case "$mode" in local|upload) ;; *) mode=unrecognized_redacted ;; esac
case "$url" in
http://localhost:8000|http://localhost:8000/) host=localhost:8000 ;;
http://skill-scanner:8000|http://skill-scanner:8000/) host=skill-scanner:8000 ;;
http://skillhub-scanner:8000|http://skillhub-scanner:8000/) host=skillhub-scanner:8000 ;;
*) host=custom_or_unrecognized_redacted ;;
esac
probe=allowed
case "$url" in http://?*|https://?*) ;; *) probe=skipped_unrecognized_url ;; esac
case "$url" in *[!a-zA-Z0-9:/._~\[\]-]*|*@*|*\?*|*\#*|*\\*) probe=skipped_unrecognized_url ;; esac
authority=${url#*://}; authority=${authority%%/*}
case "$authority" in ""|:*|*:) probe=skipped_unrecognized_url ;; esac
printf "enabled=%s mode=%s scanner_host=%s\n" "$enabled" "$mode" "$host"
if [ "$enabled" = false ]; then printf "health=skipped_disabled\n"
elif [ "$enabled" != true ]; then printf "health=skipped_unrecognized_enabled\n"
elif [ "$mode" = unrecognized_redacted ]; then printf "health=skipped_unrecognized_mode\n"
elif [ "$probe" != allowed ]; then printf "health=%s\n" "$probe"
else
wget -T 5 -t 1 -q -O /dev/null -- "${url%/}/health"; printf "health_exit=%s\n" "$?"
fi
'
```
Kustomize:
```bash
kubectl -n skillhub exec deployment/skillhub-server -c server -- sh -c '
enabled=${SKILLHUB_SECURITY_SCANNER_ENABLED:-true}
mode=${SKILLHUB_SECURITY_SCANNER_MODE:-local}
url=${SKILLHUB_SECURITY_SCANNER_URL:-http://localhost:8000}
case "$enabled" in true|false) ;; *) enabled=unrecognized_redacted ;; esac
case "$mode" in local|upload) ;; *) mode=unrecognized_redacted ;; esac
case "$url" in
http://localhost:8000|http://localhost:8000/) host=localhost:8000 ;;
http://skill-scanner:8000|http://skill-scanner:8000/) host=skill-scanner:8000 ;;
http://skillhub-scanner:8000|http://skillhub-scanner:8000/) host=skillhub-scanner:8000 ;;
*) host=custom_or_unrecognized_redacted ;;
esac
probe=allowed
case "$url" in http://?*|https://?*) ;; *) probe=skipped_unrecognized_url ;; esac
case "$url" in *[!a-zA-Z0-9:/._~\[\]-]*|*@*|*\?*|*\#*|*\\*) probe=skipped_unrecognized_url ;; esac
authority=${url#*://}; authority=${authority%%/*}
case "$authority" in ""|:*|*:) probe=skipped_unrecognized_url ;; esac
printf "enabled=%s mode=%s scanner_host=%s\n" "$enabled" "$mode" "$host"
if [ "$enabled" = false ]; then printf "health=skipped_disabled\n"
elif [ "$enabled" != true ]; then printf "health=skipped_unrecognized_enabled\n"
elif [ "$mode" = unrecognized_redacted ]; then printf "health=skipped_unrecognized_mode\n"
elif [ "$probe" != allowed ]; then printf "health=%s\n" "$probe"
else
wget -T 5 -t 1 -q -O /dev/null -- "${url%/}/health"; printf "health_exit=%s\n" "$?"
fi
'
```
2. Compare the output: standard Compose reports `enabled=true mode=upload scanner_host=skill-scanner:8000`; Kustomize reports `enabled=true mode=upload scanner_host=skillhub-scanner:8000`. A reachable health endpoint reports `health_exit=0`. This does not establish that a particular version was scanned. With `enabled=false`, health is skipped and the publication restrictions below apply. `custom_or_unrecognized_redacted` means the address is outside the display allowlist: operators must inspect protected configuration without publishing its real value. Ordinary credential-free custom HTTP(S)/IPv6 addresses can still be probed. `skipped_unrecognized_url`, `skipped_unrecognized_enabled` and `skipped_unrecognized_mode` report a skipped diagnostic, not a product verdict that the configuration is valid or invalid.
3. Correlate the current version and logs. Read its scan report and failure reason in skill details, then find that version ID within the matching log time range. A prior version's report does not cover new content. These commands read local logs; redact credentials and package content before sharing, rather than publishing the complete output.
```bash
# Compose, in this installation's runtime directory
docker compose --env-file .env.release -f compose.release.yml logs --since=10m --tail=100 server skill-scanner
# Kustomize default resource names
kubectl -n skillhub logs deployment/skillhub-server -c server --since=10m --tail=100
kubectl -n skillhub logs deployment/skillhub-scanner -c scanner --since=10m --tail=100
```
4. Follow the same version after applying the corresponding action below. Temporary unavailability may enter retry/reclaim handling; persistent failure is still bounded by the installation's retry and timeout configuration. Do not infer malicious content from elapsed time alone or upload again merely to create another version.
| Symptom | Likely cause | Where to inspect | Check and action |
| --- | --- | --- | --- |
| Non-private upload is rejected with `error.security.scanner.required` | Scanning is disabled | Container command reports `enabled=false`; check whether this installation used `--no-scanner` | Have the operator restore the Scanner and registry configuration before retrying; do not repeatedly upload or rewrite review state to bypass the check. |
| A standard deployment reports `local` or `localhost:8000` | Missing environment wiring or a private override | Compare the default/override values below with the installation's `server` environment | Correct the wiring of `SKILLHUB_SECURITY_SCANNER_MODE` / `SKILLHUB_SECURITY_SCANNER_URL` and recreate affected containers; do not treat container localhost as the host. |
| `health_exit` is nonzero | Scanner not ready, DNS/network or URL failure | Compose: `docker compose --env-file .env.release -f compose.release.yml ps skill-scanner`; Kustomize: `kubectl -n skillhub get pods -l app.kubernetes.io/name=skillhub-scanner` | Restore service/connectivity before following the original task; do not delete database, Redis or persistent volumes as a first response. |
| Health is reachable but the version remains `SCANNING` or becomes `SCAN_FAILED` | Request unfinished, execution error or recovery limits exceeded | Read this version's failure reason and correlate the registry/Scanner logs above | Separate execution failure from findings; retry only when offered for the version and authorized. Do not treat health as scan completion or human approval. |
Command sources: the [Compose manifest](https://github.com/iflytek/skillhub/blob/main/compose.release.yml), [Kustomize backend manifest](https://github.com/iflytek/skillhub/blob/main/deploy/k8s/base/backend-deployment.yaml), and [Server image](https://github.com/iflytek/skillhub/blob/main/server/Dockerfile). The standard Server image supplies the `sh` and `wget` used here.
## Overview
SkillHub includes a built-in **Skill Scanner** security scanning service that automatically detects potential security risks when skill packages are published. This serves as a critical line of defense for ensuring the security of skill packages within an enterprise.
SkillHub includes a built-in **Skill Scanner** security scanning service that automatically detects potential security risks when skill packages are published. Reports provide structured findings and execution evidence, not a guarantee that skill content is safe.
Uploads with scanning enabled undergo a security scan. The scan results inform review decisions and help administrators quickly assess whether a skill package is safe and reliable.
Uploads with scanning enabled undergo a security scan. The scan results inform review decisions and support an authorized reviewer’s assessment of the intended use; completing a scan does not constitute human approval.
**Key Features**:
@ -77,15 +166,17 @@ Administrator reviews with scan results in consideration
### Basic Configuration
Configure via `.env` file or environment variables:
The table lists basic registry bindings used by these checks; the application configuration linked below contains the complete field set. Variables must reach the Server process; adding an unreferenced key to `.env.release` alone has no effect. Recreate Server containers after changes. On Kubernetes, update the relevant configuration overlay and roll affected Deployments.
| Environment Variable | Description | Default |
|----------|------|--------|
| `SKILLHUB_SECURITY_SCANNER_ENABLED` | Enable security scanning | `true` |
| `SKILLHUB_SECURITY_SCANNER_URL` | Scanner service URL | `http://localhost:8000` |
| `SKILLHUB_SECURITY_SCANNER_MODE` | Scan mode (local / upload) | `local` |
| `SKILLHUB_SCANNER_POLICY_PRESET` | Policy preset | `balanced` |
| `SKILLHUB_SCANNER_FAIL_ON_SEVERITY` | Severity level for automatic blocking | `high` |
| Configuration | Purpose | Application default and deployment override | Check and action |
| --- | --- | --- | --- |
| `SKILLHUB_SECURITY_SCANNER_ENABLED` | Enable scanning | Application, release Compose, Kustomize and Helm default to `true`; `--no-scanner` sets the runtime to `false` | New non-private uploads are rejected when false; report reuse for existing versions is described below. |
| `SKILLHUB_SECURITY_SCANNER_URL` | Scanner address | Application: `http://localhost:8000`; release Compose: `http://skill-scanner:8000`; Kustomize: `http://skillhub-scanner:8000`; Helm generates the Service address from the release | Check health from the same container; do not copy the host’s localhost address. |
| `SKILLHUB_SECURITY_SCANNER_MODE` | `local` / `upload` protocol | Application default: `local`; release Compose, Kustomize and Helm all override it with `upload` | `upload` sends the package; `local` requires the same directory at the same path on both sides. |
| `SKILLHUB_SCANNER_POLICY_PRESET` | Policy preset | Application default: `balanced`; effective wiring is installation-specific | Add the Server environment entry explicitly if absent from the manifest, then recreate it. |
| `SKILLHUB_SCANNER_FAIL_ON_SEVERITY` | Blocking severity | Application default: `high`; effective wiring is installation-specific | This threshold controls scanning policy, not the human approval decision. |
Defaults/overrides: [application configuration](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/resources/application.yml), [Kustomize ConfigMap](https://github.com/iflytek/skillhub/blob/main/deploy/k8s/base/configmap.yaml), and [Helm ConfigMap](https://github.com/iflytek/skillhub/blob/main/charts/skillhub/templates/configmap.yaml).
### LLM Analysis Configuration (Optional)
@ -101,13 +192,17 @@ Enabling the LLM analysis engine can improve the accuracy of security detection:
### Deployment Notes
When using the one-click deployment, the Scanner service is enabled by default. If security scanning is not needed, it can be disabled with the `--no-scanner` flag:
The runtime script enables Scanner by default. `--no-scanner` does not start Scanner and disables scanning in the registry. **PUBLIC and NAMESPACE_ONLY upload/publication requests are then rejected** with `error.security.scanner.required`. PRIVATE uploads remain available, but leave the version `UPLOADED` until an authorized operator confirms publication. Upload success is not publication completion.
A published private skill may still request wider visibility using a reusable report for its latest published version (`taskId` and `scannedAt` present, `failureReason=null`, and `isSafe=true`). Without that report, disabled scanning also rejects the visibility request. The machine result is not a content-safety guarantee or human approval.
```bash
# Disable Scanner during deployment
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --no-scanner
```
Publication restrictions: [publish preconditions](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillPublishService.java), [visibility changes](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillVisibilityService.java), and [private-version confirmation](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillReviewSubmitService.java).
## Notes
> **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.
@ -115,4 +210,4 @@ curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- u
- **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
- **Policy Tuning**: The `balanced` policy is suitable for most scenarios; enterprises can customize policies based on their security needs
- **Health Check**: Check the Scanner service status via `GET http://localhost:8000/health`
- **Health Check**: Follow the [operator troubleshooting order](#operator-troubleshooting-order) to reach the configured Scanner from the registry container. Do not assume that host or Server localhost identifies Scanner.

161
docs/skillhub/en/guide/skill-publish.md
View file

@ -2,7 +2,7 @@
## From Local Files to an Installable Version
A single-skill upload has one root `SKILL.md`. For multiple skills, use [Suite import](/en/guide/suite-bundle); do not place unrelated skills in one single-skill ZIP.
A single-skill upload has one root `SKILL.md`. For multiple skills, use [Suite import](./suite-bundle.html); do not place unrelated skills in one single-skill ZIP.
1. Exercise the instructions, scripts and relative references in your local Agent, then prepare a standalone directory.
2. Choose a writable namespace and PUBLIC, NAMESPACE_ONLY or PRIVATE visibility. Document dependencies: publishing does not distribute your local environment.
@ -21,6 +21,8 @@ my-skill/
Relative references must resolve inside the package. Exclude credentials, caches and unrelated project files. `version` is optional: the server generates a time-based version when absent. Set it explicitly, for example `1.0.0` then `1.0.1`, for predictable releases. Top-level `version` takes precedence over `metadata.version`; do not supply conflicting values.
Resolve versions by an exact version, tag, or fingerprint; `^` / `~` ranges are unsupported. Tags such as `latest`, `beta`, and `stable` locate versions; `latest` follows publication state and the published pointer rather than the highest SemVer. Details expose package files and version/tag downloads.
### Updating an Existing Skill
Use Update in My Skills or publish again to the same namespace and skill name. Verify the coordinate: changing `name` may create a different skill. Published versions cannot be overwritten; use a new version for normal updates. While it awaits review, public users retain the previously published version. After approval, check the displayed version, title and summary.
@ -40,63 +42,11 @@ Existing local installations do not update automatically. Consumers explicitly u
| Frozen namespace or removed membership | Restore legitimate write access first; a previously installed copy grants no publishing rights |
## Overview
## Prepare metadata and choose a publishing entry
Skill publishing is the core feature of SkillHub. Developers can upload locally developed Agent skill packages to the registry with one click. The system automatically handles version management, metadata extraction, and file indexing.
### Prepare metadata
![Concept Diagram](/diagrams/skill-publish-concept.png)
**Problems Solved**:
Traditionally, team members distribute skill packages through Git repositories or file sharing. This approach has several pain points:
- **Version Chaos**: Different versions scattered everywhere, hard to track
- **Permission Control Lost**: Cannot finely control who can access which skill packages
- **Discovery Difficulty**: New members don't know what skills are available
SkillHub provides an npm-like publishing experience with enterprise-grade permission control and review mechanisms.
**Core Features**:
- **Semantic Versioning**: Supports `major.minor.patch` version specification
- **Tag System**: `latest`, `beta`, `stable` and custom tags
- **Multi-version Coexistence**: Same skill package can retain multiple historical versions
- **Version Resolution**: Resolve exact versions, tags or fingerprints; `^` / `~` ranges are not supported
- **File Browsing**: Browse skill package file structure online
- **Download Distribution**: Download by version or tag
## Use Cases
**Case 1: Developer Publishes New Skill**
You just completed a Claude Code skill package and want other team members to use it.
![Screenshot](/screenshots/homepage.png)
**Case 2: Version Iteration**
Skill package needs bug fixes or new features, publish new version while maintaining backward compatibility.
**Case 3: Beta Testing**
New features are not stable yet, publish with `beta` tag for limited testing before promoting to `latest`.
**Case 4: Version Rollback**
New version has serious issues, need to point `latest` tag to previous stable version.
## Steps
1. **Prepare Skill Package**
Prepare a skill directory with `SKILL.md` at its root:
- Put both YAML frontmatter and the skill instructions in `SKILL.md`.
- The frontmatter must contain `name` and `description`. Set `version` there when you need an explicit version.
- `package.json` does not supply or replace this skill metadata.
- Keep the package structure clear and exclude sensitive information.
For example, save this as `my-skill/SKILL.md`:
Frontmatter requires `name` and `description`; `package.json` cannot replace skill metadata. Save this example as `my-skill/SKILL.md`:
```markdown
---
@ -136,31 +86,33 @@ On the web publish/update form, upload a package and edit **Display name**. The
**My Skills** shows the pending update's title and summary with one main status and a plain-text comparison to the published version. Open the card to preview that update; public readers still see the published version. Details always show the copyable `@namespace/slug`; renaming does not change links or install identifiers.
`skillhub.example.com`, `YOUR_API_TOKEN`, and `my-team` are placeholders. Replace them with the instance, caller credential, and target namespace; never commit a real token.
Web names are stored in platform version metadata without rewriting `SKILL.md` or other package files. Downloads use the existing ZIP repackaging process, so compressed archive bytes may differ. CLI publishing keeps using package metadata. Approval, rollback after yanking, and promotion use the corresponding version's name and summary.
2. **Publish via CLI (Recommended)**
### Upload with the CLI
```bash
# Configure the SkillHub registry
export SKILLHUB_REGISTRY=http://localhost:8080
export SKILLHUB_REGISTRY=https://skillhub.example.com
export SKILLHUB_TOKEN=YOUR_API_TOKEN
# Publish to default namespace
npx @astron-team/skillhub@latest publish ./my-skill
skillhub publish ./my-skill
# Publish to specific namespace
npx @astron-team/skillhub@latest publish ./my-skill --namespace my-team
skillhub publish ./my-skill --namespace my-team
```
> The ClawHub CLI publish and sync protocols are not compatible with SkillHub. Use the SkillHub CLI above for publishing.
3. **Publish via Web UI**
### Upload through the web
Visit `http://localhost:3000/dashboard/publish`, select namespace, upload zip file, choose visibility, and click "Publish".
Open `/dashboard/publish` under the instance Web entry, select namespace, upload zip file, choose visibility, and click "Publish".
4. **Publish via REST API**
### Use the publishing API
```bash
```http
POST /api/v1/skills/{namespace}/publish
Content-Type: multipart/form-data
@ -172,27 +124,52 @@ visibility: PUBLIC
The diagram covers ordinary uploads; scan failures, review rejection and privileged publishing are described below.
5. **Security Scan**
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** (follow the returned status)
Team admins receive review notifications and approve skill packages for official release.
7. **Publish Success**
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
### Authoring drafts: create, edit, and validate structure
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.
Use the ZIP or CLI upload path when a local skill directory already exists. Authoring drafts support file-by-file API editing; there is currently no web authoring workbench or endpoint that submits a draft as a published skill version. A draft does not automatically become an `UPLOADED` or review-pending version.
Creation requires a writable namespace and membership. `SUPER_ADMIN` bypasses membership only, not frozen/archived namespace checks. Reads, edits, and validation of existing drafts check ownership or `SUPER_ADMIN` without rechecking namespace state or membership; leaving or freezing a namespace does not automatically make an existing draft read-only. Use an authenticated browser session and the instance's CSRF token for writes. The current API Token route allowlist does not expose authoring endpoints; a CLI login token is not an authoring credential. There is no separate authoring enable switch in the source. Check an older instance's `/v3/api-docs` before using these routes.
These are HTTP contracts, not shell commands. Send requests through a same-origin API client in the authenticated instance, adding the deployment prefix for sub-path installations. `team`, `example-skill`, `{draftId}`, and `{runId}` are placeholders: replace them with an accessible namespace, a draft name, and IDs returned by the API.
| Operation | Request | Completion evidence | Explanation |
| --- | --- | --- | --- |
| Create draft | `POST /api/v1/authoring/drafts` | Response contains `data.id` and `data.revision` | Body requires `namespaceSlug` and `name`; `requirement` is optional; a `SKILL.md` scaffold is created |
| Read current content | `GET /api/v1/authoring/drafts/{draftId}`; `GET /api/v1/authoring/drafts/{draftId}/files` | Current revision and file inventory are readable | Read a file with `GET /api/v1/authoring/drafts/{draftId}/files/content?path=SKILL.md` |
| Save file | `PUT /api/v1/authoring/drafts/{draftId}/files` | Read response `data.draft.revision` | `expectedRevision` is the pre-write concurrency condition; changed content advances the revision, while a no-op may retain it; old validation does not cover new content |
| Start validation | `POST /api/v1/authoring/drafts/{draftId}/runs` | Response contains run `data.id` and `data.draftRevision` | The run captures that revision, not a publication request |
| Inspect result | `GET /api/v1/authoring/runs/{runId}`; `GET /api/v1/authoring/runs/{runId}/findings`; read `GET /api/v1/authoring/drafts/{draftId}` again | Run has `status=SUCCEEDED`, `errorCount=0`, and draft has `validated=true` | The run's `draftRevision` must equal the current draft `revision`; an old result does not validate new content |
Create request body:
```json
{"namespaceSlug":"team","name":"example-skill","requirement":"Turn meeting material into an action list"}
```
Text-file save body: replace `expectedRevision` with the revision just read, and `content` with the complete actual file. Do not keep reusing the example revision. `encoding` also accepts `base64` for binary files.
```json
{"path":"SKILL.md","content":"---\nname: example-skill\ndescription: Summarize meeting material\n---\n\n# Instructions\nExtract action items from the input.","encoding":"text","contentType":"text/markdown","expectedRevision":1}
```
Structure validation checks paths, duplicates, file counts and sizes, `SKILL.md` frontmatter, content/extension consistency, and compliance declaration structure. It does not execute skills, start a model or Agent, replace security scanning or human review, or establish compliance. For publication, assemble the edited files into a local directory and follow the normal upload path on this page. No draft ZIP export or direct-publication entry is currently delivered; reserved submission fields in a response do not establish that capability.
| Symptom | Likely cause | Locate the cause | Action |
| --- | --- | --- | --- |
| Endpoint absent | Instance version lacks it | Find the authoring paths in `/v3/api-docs` | Use local files and ZIP upload; do not guess a submit endpoint |
| Authentication or write rejected | Session, CSRF, or credential type mismatch | Check the post-login identity request and CSRF information | Log into the instance again; do not share cookies or tokens |
| Creation rejected | Missing membership or namespace not writable | Check membership and namespace state | Restore the prerequisites; do not use super-admin privileges to bypass frozen/archived checks |
| Existing draft rejected | Neither owner nor super administrator | Compare current account and draft ownership | Contact the owner; do not borrow credentials or assume leaving/freezing automatically removes existing draft write access |
| Revision conflict | Another edit advanced the revision | Read draft `revision` and file content again | Compare and merge changes; do not bypass revision checking |
| Errors or stale validation | Invalid structure or later edits | Inspect findings and compare run/draft revisions | Fix and validate again; do not treat an old successful run as publication |
Sources: [controller](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/authoring/SkillAuthoringController.java), [draft access/revisions](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/SkillDraftService.java), [structure validator](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/DraftStructureValidator.java), and [Token route policy](https://github.com/iflytek/skillhub/blob/main/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/policy/RouteSecurityPolicyRegistry.java).
## Compliance Declarations
@ -233,10 +210,10 @@ Field reference:
| `title` | No | Human-readable control title; recommended for review and search |
| `evidence` | No | Evidence list, supporting packaged files and external URLs |
## API Reference
## Publishing and version query contracts
**Publish Skill Package**:
```bash
```http
POST /api/v1/skills/{namespace}/publish
Content-Type: multipart/form-data
@ -253,42 +230,36 @@ visibility: PUBLIC | PRIVATE | NAMESPACE_ONLY (required)
| visibility | enum | Visibility level: PUBLIC, PRIVATE, NAMESPACE_ONLY |
**Get Skill Details**:
```bash
```http
GET /api/v1/skills/{namespace}/{slug}
```
**List Versions**:
```bash
```http
GET /api/v1/skills/{namespace}/{slug}/versions?page=0&size=20
```
**Get Version Details**:
```bash
```http
GET /api/v1/skills/{namespace}/{slug}/versions/{version}
```
**Download Specific Version**:
```bash
```http
GET /api/v1/skills/{namespace}/{slug}/versions/{version}/download
```
**Download by Tag**:
```bash
```http
GET /api/v1/skills/{namespace}/{slug}/tags/{tagName}/download
```
**Version Resolution**:
```bash
```http
GET /api/v1/skills/{namespace}/{slug}/resolve?version=1.2.0
```
## Notes
## Package and identifier limits
> **Version Specification**: Use explicit `major.minor.patch` versions such as `1.2.3` for predictable releases; omission produces a server-generated time version.
- **First Publish**: Version should start from `0.1.0` or `1.0.0`
- **Tag Management**: `latest` follows publication state and the published pointer, not client-side selection of the highest SemVer
- **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
- A skill package is limited to 100MB (configurable); size and file-count limits are separate.
- Skill slugs support lowercase letters, numbers, hyphens, and Unicode characters; inspect the final coordinate before publishing.

23
docs/skillhub/en/quickstart.md
View file

@ -71,9 +71,9 @@ Open the project in your Agent and start a new session or reload skills if requi
> 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).
If discovery fails, check the CLI's destination, current project, scope, and target Agent; see the [FAQ](./faq.html).
For a collection, use `skillhub suite install`, then start with its entry skill. See [Skill Suites](./guide/skill-suites.md).
For a collection, use `skillhub suite install`, then start with its entry skill. See [Skill Suites](./guide/skill-suites.html).
## 4. Update and manage installations
@ -82,17 +82,20 @@ 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.
Review the plan before updating and preserve local changes you need. Do not use `--force` by default. See the [CLI guide](./guide/cli.html) for removal, team workspace synchronization, and command details.
## Troubleshoot the first installation
| Symptom | Check first | Next step |
| --- | --- | --- |
| Skill not found | Registry, spelling, login identity, and visibility | Confirm a published coordinate/version in the UI; see [discovery](./guide/skill-discovery.md) |
| Directory conflict | Whether the destination belongs to another source or contains your own files | Preserve needed files; do not force an unknown directory; see [CLI reference](./guide/cli.md) |
| Installed but not discovered | Agent profile, project root, and user/project scope | Check the printed path, then reload or start a session according to the Agent's discovery behavior |
| Discovered but execution fails | Required tools, inputs, and credentials | Follow `SKILL.md`; the registry does not configure or execute those requirements |
| Symptom | Locate the cause | Expected result or cause | Action |
| --- | --- | --- | --- |
| Skill not found | In the same terminal run `skillhub search pdf` and `skillhub whoami`; find the actual coordinate in the same registry's UI | Search returns published resources visible to the caller; anonymous public search can work even when the identity request is unauthenticated | Check registry, coordinate, and publication state; log in for restricted resources. Do not reset accounts or delete local files to troubleshoot search |
| Directory conflict | Run `skillhub list --agent codex --json`; compare `items[].installDir` with the conflict path and open that directory's `SKILL.md` | A recorded install should match its source, version, and directory; an unrecorded directory may contain manual work | Back up and identify the contents, then choose the intended project or scope. Do not force-overwrite unknown files |
| Installed but not discovered | From the target project run `skillhub list --agent codex --json`; inspect `items[].agent`, `installDir`, and `status`, then open the actual `SKILL.md` | `status=ok` only means the directory exists; `missing` means the recorded directory is absent. Agent discovery is a separate step | Check project and Agent profile, then reload or start a session according to the Agent's rules. Do not treat `ok` as proof of discovery |
| Discovered but execution fails | Open the installed `SKILL.md`, check its tool/input/credential requirements, and read the actual Agent error | Files may be installed correctly while tools or permissions are missing; the registry does not configure external tools | Configure the target environment as instructed. Do not include credentials in shared packages or public error reports |
Run these commands in the project containing the installation. Match `--agent codex` to the actual Agent; use `--agent claude-code` for Claude Code. `pdf` is a replaceable search term, not a guaranteed skill name. See the [list implementation](https://github.com/iflytek/skillhub/blob/main/cli/src/commands/list.ts) and [CLI option definitions](https://github.com/iflytek/skillhub/blob/main/cli/src/index.ts) for fields and filtering.
## Next steps
Install a [Skill Suite](./guide/skill-suites.md) when you need a coordinated collection, or use the [CLI reference](./guide/cli.md) for more commands. For publishing, team administration, hosting, or development, choose your next task in the [documentation map](./guide/index.md).
Install a [Skill Suite](./guide/skill-suites.html) when you need a coordinated collection, or use the [CLI reference](./guide/cli.html) for more commands. For publishing, team administration, hosting, or development, choose your next task in the [documentation map](./guide/index.html).

36
docs/skillhub/faq.md
View file

@ -6,7 +6,7 @@ A: SkillHub 提供自托管注册中心、命名空间权限、发布审核、
## Q: 如何备份数据？
A: 备份 PostgreSQL、实际使用的存储后端及部署配置。默认 release Compose 使用本地文件存储，需要备份 `skillhub_storage` 数据卷；使用 S3 时备份对应 bucket/对象。数据库和技能文件需要来自一致的备份窗口。操作步骤见 [部署指南](./guide/deployment.md)，恢复能力应通过独立环境演练验证。
A: 备份 PostgreSQL、实际使用的存储后端及部署配置。默认 release Compose 使用本地文件存储，需要备份 `skillhub_storage` 数据卷；使用 S3 时备份对应 bucket/对象。数据库和技能文件需要来自一致的备份窗口。操作步骤见 [部署指南](./guide/deployment.html)，恢复能力应通过独立环境演练验证。
## Q: 支持哪些认证方式？
@ -39,11 +39,11 @@ 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 混用。
按 [快速开始](./quickstart.html) 选择注册中心、安装位置和 Agent。发布和受限资源访问需要登录。ClawHub 兼容接口的范围见 [集成说明](https://github.com/iflytek/skillhub/blob/main/docs/openclaw-integration.md)，不要将其发布协议与 SkillHub CLI 混用。
## Q: 如何配置 HTTPS？
A: 在外部代理终止 TLS，并转发到实际映射的 Web 端口（release Compose 默认 `WEB_PORT=80`），Web 已代理后端路由。设置真实 `SKILLHUB_PUBLIC_BASE_URL`，正确传递原始 Host 和代理协议头，并验证登录与 Cookie。见 [部署指南](./guide/deployment.md)。
A: 在外部代理终止 TLS，并转发到实际映射的 Web 端口（release Compose 默认 `WEB_PORT=80`），Web 已代理后端路由。设置真实 `SKILLHUB_PUBLIC_BASE_URL`，正确传递原始 Host 和代理协议头，并验证登录与 Cookie。见 [部署指南](./guide/deployment.html)。
## Q: 如何监控 SkillHub？
@ -57,11 +57,11 @@ A: SkillHub 通过命名空间实现了逻辑上的多租户隔离。每个命
## Q: 如何升级 SkillHub？
A: 按 [部署与升级指南](./guide/deployment.md) 选择目标版本，先备份数据库、技能存储和配置，再升级并验证健康、登录及代表性技能操作。Flyway 会执行数据库迁移；不能仅凭容器启动成功认定升级成功，也不能假设降级镜像即可回滚数据库。
A: 按 [部署与升级指南](./guide/deployment.html) 选择目标版本，先备份数据库、技能存储和配置，再升级并验证健康、登录及代表性技能操作。Flyway 会执行数据库迁移；不能仅凭容器启动成功认定升级成功，也不能假设降级镜像即可回滚数据库。
## Q: 为什么管理员（admin）和普通用户都无法创建命名空间？
A: 先查看页面或接口的错误信息和 `requestId`，核对当前账号权限、名称校验及实例限制。不要直接推断为版本太旧；管理员身份也不能绕过全部业务规则。参见 [命名空间管理](./guide/namespace.md)。
A: 先查看页面或接口的错误信息和 `requestId`，核对当前账号权限、名称校验及实例限制。不要直接推断为版本太旧；管理员身份也不能绕过全部业务规则。参见 [命名空间管理](./guide/namespace.html)。
## Q: 如何搜索或操作指定命名空间中的技能包（Skill）？
@ -73,11 +73,11 @@ A: 可选 runtime 脚本、release Compose、Kubernetes Kustomize 或 Helm Chart
## Q: 用 Kubernetes 部署对集群版本有要求吗？
A: 官方 [Kubernetes 部署指南](./guide/kubernetes.md) 要求 Kubernetes **v1.24 及以上**，并需要已配置好的 `kubectl` 与默认 StorageClass（用于 PVC）；如需域名访问，还需安装 nginx ingress controller。更低版本的集群未经验证，建议先升级集群再部署。
A: 官方 [Kubernetes 部署指南](./guide/kubernetes.html) 要求 Kubernetes **v1.24 及以上**，并需要已配置好的 `kubectl` 与默认 StorageClass（用于 PVC）；如需域名访问，还需安装 nginx ingress controller。更低版本的集群未经验证，建议先升级集群再部署。
## Q: 部署后输入正确的账号密码，却又跳回登录页？
A: 先在浏览器网络面板检查登录请求及后续身份请求的状态，核对实例公网 URL、代理转发、Cookie 和后端会话配置，并关联服务端 `requestId` 与日志。此现象本身不能确定是密码错误或数据库问题。不要清空 PostgreSQL 数据卷来尝试修复登录。部署参数见 [部署指南](./guide/deployment.md)。
A: 先在浏览器网络面板检查登录请求及后续身份请求的状态，核对实例公网 URL、代理转发、Cookie 和后端会话配置，并关联服务端 `requestId` 与日志。此现象本身不能确定是密码错误或数据库问题。不要清空 PostgreSQL 数据卷来尝试修复登录。部署参数见 [部署指南](./guide/deployment.html)。
## Q: 如何修改 admin 密码？修改配置后不生效？
@ -89,11 +89,11 @@ A: 网页找回密码使用邮箱验证码；已登录且知道原密码的修
## Q: skill 可以起中文名吗？
A: 技能标识 `name` / slug 使用符合校验规则的名称；面向用户的展示名支持中文，可通过 `metadata.display-name` 配置。展示名不改变安装坐标或目录名。见 [发布指南](./guide/skill-publish.md)。
A: 技能标识 `name` / slug 使用符合校验规则的名称；面向用户的展示名支持中文，可通过 `metadata.display-name` 配置。展示名不改变安装坐标或目录名。见 [发布指南](./guide/skill-publish.html)。
## Q: 未审核的 skill 可以下载吗？
A: 正常安装面向已发布且当前用户可访问的版本。能查看详情不等于能下载任意状态的版本；作者或审核人员的预览权限与公开分发权限不同。见 [审核与治理](./guide/review.md)。
A: 正常安装面向已发布且当前用户可访问的版本。能查看详情不等于能下载任意状态的版本；作者或审核人员的预览权限与公开分发权限不同。见 [审核与治理](./guide/review.html)。
## Q: 如何隐藏或删除登录页的第三方 SSO 登录方式？
@ -107,6 +107,14 @@ A: 登录入口是配置驱动的：`/api/v1/auth/methods` 只返回配置了真
下对应的注册块（`github`、`gitlab`、`feishu`、`dingtalk`）以及对应的 `provider` 段，
Spring Boot 启动时便不会创建该注册。
## Q: 关闭扫描后，还能上传和发布技能吗？
A: `runtime.sh --no-scanner` 会关闭注册中心扫描开关，并不启动扫描容器。对**普通的新上传**，关闭扫描后使用 `PUBLIC`（公开）或 `NAMESPACE_ONLY`（空间成员可见）会被拒绝；`PRIVATE`（私有）可以上传，版本停在 `UPLOADED`，还需确认发布。上传成功不表示已发布，不要反复上传同一版本绕过扫描前置。
已经发布的私有技能扩大可见范围是另一条路径：最新版本若有可复用的合格扫描报告，即使当前扫描关闭，仍可能继续提交范围审核；没有可复用报告时必须先恢复扫描。报告条件和诊断命令见[安全扫描](./guide/scanner.html)，不能仅凭“扫描已关闭”推断已有版本的所有动作都不可用。
依据：[部署脚本](https://github.com/iflytek/skillhub/blob/main/scripts/runtime.sh)、[新上传规则](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillPublishService.java)与[范围变更规则](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillVisibilityService.java)。
## Q: SkillHub 的安全扫描（Skill Scanner）是讯飞自研的吗？使用什么协议？
A: SkillHub 内置安全扫描能力。其中扫描接入、任务编排、审计落库和部署集成由讯飞团队实现；底层扫描服务使用 Cisco 的 [cisco-ai-skill-scanner](https://github.com/cisco-ai-defense/skill-scanner)（Apache License 2.0，版权归 Cisco）。
@ -174,7 +182,7 @@ SKILLHUB_PUBLISH_MAX_FILE_COUNT=500
## Q: 使用 CLI（发布 / 下载等）对服务端版本有要求吗？
A: 兼容性取决于具体命令。旧版本支持基础 CLI 不代表支持 Device Flow、Suite 或同步；请核对 CLI 版本与目标服务端发行说明。Suite 要求服务端声明 `skill-suite-v1`。见 [CLI 指南](./guide/cli.md)。
A: 兼容性取决于具体命令。旧版本支持基础 CLI 不代表支持 Device Flow、Suite 或同步；请核对 CLI 版本与目标服务端发行说明。Suite 要求服务端声明 `skill-suite-v1`。见 [CLI 指南](./guide/cli.html)。
## Q: SkillHub 支持 MySQL 数据库吗？
@ -273,7 +281,7 @@ A: OAuth 首次登录创建的是普通用户。需要由已有的 `SUPER_ADMIN`
## Q: 如何批量安装多个技能包？
A: 需要固定成员版本并统一升级时，使用 [技能套装](./guide/skill-suites.md) 的 `skillhub suite install`。同步团队命名空间工作区时，使用 [CLI](./guide/cli.md) 的 `skillhub sync pull`。若只是独立安装几个无关技能，可分别运行 `skillhub install`；Suite Bundle 是发布者的导入格式，不是本地安装命令。
A: 需要固定成员版本并统一升级时，使用 [技能套装](./guide/skill-suites.html) 的 `skillhub suite install`。同步团队命名空间工作区时，使用 [CLI](./guide/cli.html) 的 `skillhub sync pull`。若只是独立安装几个无关技能，可分别运行 `skillhub install`；Suite Bundle 是发布者的导入格式，不是本地安装命令。
## Q: 技能套装保存草稿后，在哪里提交审核？按钮不显示或不可用怎么办？
@ -282,20 +290,20 @@ A: 进入该版本的套装管理页，在「概览」中的发布检查清单
- **没有按钮**：先核对是否进入有管理权限的套装版本，而不是市场预览页；页面只在服务端允许当前账号提交审核或直接发布时显示该操作，版本状态和权限都会影响可用动作。
- **按钮不可用**：补齐简介、概述，指定可用的入口技能，并处理成员版本的阻塞原因。只有全部检查项就绪，且没有提交中的请求时才能提交。
参见 [创建与管理技能套装](./guide/skill-suites.md)。若旧版本页面与指南不一致，请附服务端/Web 版本、套装状态和脱敏截图反馈，不要把 Skill 或 Agent 的发布入口当作套装入口。
参见 [创建与管理技能套装](./guide/skill-suites.html)。若旧版本页面与指南不一致，请附服务端/Web 版本、套装状态和脱敏截图反馈，不要把 Skill 或 Agent 的发布入口当作套装入口。
## Q: 安装技能套装后，概述会变成一个可调用的技能吗？
A: 不会。概述说明套装适用任务、成员分工和使用边界，供审核者与使用者阅读；安装交付的是各成员的独立技能目录，不会将概述合成为一个新的套装 `SKILL.md`，也不提供通用的 `suite run` 命令。
需要 Agent 遵循的执行顺序、成员调用规则和结果校验，应写进**入口技能及成员的 `SKILL.md`**。在安装目标项目中确认 Agent 已发现入口技能，再请求它使用该入口完成任务；套装坐标用于安装管理，运行时使用实际入口技能。安装成员文件不等于配置好它们依赖的工具或服务。详细步骤见 [安装后开始使用](./guide/skill-suites.md#安装后开始使用)。
需要 Agent 遵循的执行顺序、成员调用规则和结果校验，应写进**入口技能及成员的 `SKILL.md`**。在安装目标项目中确认 Agent 已发现入口技能，再请求它使用该入口完成任务；套装坐标用于安装管理，运行时使用实际入口技能。安装成员文件不等于配置好它们依赖的工具或服务。详细步骤见 [安装后开始使用](./guide/skill-suites.html#安装后开始使用)。
## Q: 遇到问题怎么办？
A: 可以通过以下方式获取帮助：
- **GitHub Issues**: https://github.com/iflytek/skillhub/issues
- **在线文档**: https://iflytek.github.io/skillhub/
- **在线文档**：[SkillHub](./index.html)
- **文档**: 参考项目 README.md
- **社区讨论**: https://github.com/iflytek/skillhub/discussions

38
docs/skillhub/guide/index.md
View file

@ -1,46 +1,46 @@
# 文档导航
按要完成的任务选择入口。第一次使用，从[快速开始](../quickstart.md)安装一个技能；不需要先阅读部署或开发文档。
按要完成的任务选择入口。第一次使用，从[快速开始](../quickstart.html)安装一个技能；不需要先阅读部署或开发文档。
## 开始使用
- [账号与访问令牌](./account-access.md)：网页登录、CLI 授权、Token 到期和密码找回。
- [项目简介](../introduction.md)：了解注册中心解决什么问题。
- [快速开始](../quickstart.md)：搜索、安装，在 Agent 中使用。
- [常见问题](../faq.md)：排查登录、安装和配置问题。
- [账号与访问令牌](./account-access.html)：网页登录、CLI 授权、Token 到期和密码找回。
- [项目简介](../introduction.html)：了解注册中心解决什么问题。
- [快速开始](../quickstart.html)：搜索、安装，在 Agent 中使用。
- [常见问题](../faq.html)：排查登录、安装和配置问题。
## 使用技能
| 你要做什么 | 阅读 |
| --- | --- |
| 找到适合任务的技能，查看版本和权限 | [搜索与安装技能](./skill-discovery.md) |
| 一次安装一组固定版本技能，从入口技能开始使用 | [管理技能套装](./skill-suites.md) |
| 选择 Agent 和安装范围，更新、卸载或同步工作区 | [CLI 使用参考](./cli.md) |
| 收藏、评价技能并查看通知 | [收藏、评分与通知](./social.md) |
| 找到适合任务的技能，查看版本和权限 | [搜索与安装技能](./skill-discovery.html) |
| 一次安装一组固定版本技能，从入口技能开始使用 | [管理技能套装](./skill-suites.html) |
| 选择 Agent 和安装范围，更新、卸载或同步工作区 | [CLI 使用参考](./cli.html) |
| 收藏、评价技能并查看通知 | [收藏、评分与通知](./social.html) |
## 创作与发布
先准备 `SKILL.md` 和所需文件，再提交发布。提交成功后仍需跟踪扫描、审核及最终版本状态。
- [发布与更新技能](./skill-publish.md)：包结构、元数据、上传和版本管理。
- [通过 Bundle 导入技能套装](./suite-bundle.md)：作者上传 Bundle，预览成员差异后确认。安装现有套装请用上方的使用指南。
- [发布与更新技能](./skill-publish.html)：包结构、元数据、上传和版本管理。
- [通过 Bundle 导入技能套装](./suite-bundle.html)：作者上传 Bundle，预览成员差异后确认。安装现有套装请用上方的使用指南。
## 团队与治理
- [管理命名空间](./namespace.md)：成员、角色和资源可见范围。
- [审核技能与套装](./review.md)：处理技能与套装申请。
- [安全扫描与报告](./scanner.md)：扫描服务接入及结果解读。
- [管理命名空间](./namespace.html)：成员、角色和资源可见范围。
- [审核技能与套装](./review.html)：处理技能与套装申请。
- [安全扫描与报告](./scanner.html)：扫描服务接入及结果解读。
## 部署与运维
仅在需要自己运行注册中心时阅读。先选择部署方式，再配置所需的可选能力。
- [Docker 部署](./deployment.md)：安装、配置、升级和备份。
- [Kubernetes 部署](./kubernetes.md)：集群和 Helm 部署。
- [前端动作统计](./frontend-analytics.md)：可选手动接入、授权与故障验收。
- [技能头像与审核](./skill-avatars.md)：管理员配置图片审核服务。
- [Docker 部署](./deployment.html)：安装、配置、升级和备份。
- [Kubernetes 部署（Kustomize / Helm）](./kubernetes.html)：选择清单或独立 Chart 路径。
- [前端动作统计](./frontend-analytics.html)：可选配置化接入、授权与故障验收，按部署版本选择配置。
- [技能头像与审核](./skill-avatars.html)：管理员配置图片审核服务。
## 开发与集成
- [Runtime 集成](./runtime-integration.md)：外部运行时使用注册中心的接口契约。
- [Runtime 集成](./runtime-integration.html)：外部运行时使用注册中心的接口契约。
- [源码开发手册](https://github.com/iflytek/skillhub/blob/main/docs/dev-workflow.md)：本地开发环境和仓库检查命令。

2
docs/skillhub/guide/kubernetes.md
View file

@ -2,7 +2,7 @@
对象存储可选部署、凭证和迁移说明见[对象存储手册（GitHub）](https://github.com/iflytek/skillhub/blob/main/docs/object-storage.md)。
本文档说明如何在 Kubernetes 集群中部署 SkillHub。
本页按 `deploy/k8s/` 的 Kustomize 清单部署。Helm 是另一条独立路径，values、Secret 与升级步骤见 [Chart README](https://github.com/iflytek/skillhub/blob/main/charts/skillhub/README.md)。同一实例选择一条路径，不要把两套资源叠加部署；Docker 路径见 [Docker 部署](./deployment.html)。
## 前置条件

48
docs/skillhub/guide/namespace.md
View file

@ -2,9 +2,11 @@
创建团队空间入口仅向平台 SKILL_ADMIN / SUPER_ADMIN 展示。普通成员先联系有权创建者建立空间并邀请加入；成为团队 Owner 不等于获得平台管理角色。
创建权限依据 [NamespacePortalCommandAppService](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/NamespacePortalCommandAppService.java)。
## 团队开始协作的顺序
1. 在“我的空间”创建团队空间，填写稳定的 slug 和易读的显示名称。slug 是安装坐标的一部分，不能随团队改名而修改。
1. 先使用平台技能管理员（`SKILL_ADMIN`）或超级管理员（`SUPER_ADMIN`）账号登录；仅这两类平台角色可在“我的空间”创建团队命名空间，填写稳定的 slug 和易读的显示名称。slug 是安装坐标的一部分，不能随团队改名而修改。
2. 在成员页添加已有账号或生成邀请链接。普通角色选择是 MEMBER / ADMIN；移交所有权使用独立的转让入口，不通过普通角色下拉框添加 Owner。
3. 团队成员在发布页选择该空间。团队内共享请选择 NAMESPACE_ONLY；PRIVATE 不等于“全体团队成员可见”。
4. 管理员在空间审核入口处理提交，成员在“我的技能”跟踪自己的版本。
@ -12,9 +14,29 @@
### 设置按钮为什么不一样
页面按空间类型、状态及服务端返回的操作权限展示冻结、解冻、归档、恢复和删除按钮。不要把 Owner / Admin 理解为所有操作永久可用。ACTIVE 团队空间的 Owner / Admin 可以编辑资料；所有权转让只向有权的 Owner 展示。冻结或归档后，成员管理进入只读状态，但符合条件的管理员仍可查看邀请历史。
以下矩阵只适用于 `TEAM` 类型命名空间；服务端权限优先于角色名称。平台角色与命名空间成员角色分别校验，不能互相推导。
冻结用于暂时停止写入，恢复写入使用解冻；归档与永久删除不是同一个操作。执行生命周期操作前核对确认框中的空间和影响范围，完成后检查状态和成员页面，而不是仅看请求成功提示。
| 命名空间状态 | 命名空间角色 | 可用治理操作 | 条件与限制 |
| --- | --- | --- | --- |
| `ACTIVE` | 所有者（Owner） | 冻结、归档、删除；编辑资料、成员及所有权转让 | 删除另须满足下方依赖检查 |
| `ACTIVE` | 空间管理员（Admin） | 冻结；编辑资料、管理成员 | 不能归档、删除或转让所有权 |
| `ACTIVE` | 成员（Member） | 无上述治理操作 | 不能因技能所有者身份管理命名空间 |
| `FROZEN` | 所有者（Owner） | 解冻、归档、删除 | 删除另须满足依赖检查；成员管理只读 |
| `FROZEN` | 空间管理员（Admin） | 解冻 | 不能归档、删除；成员管理只读 |
| `FROZEN` | 成员（Member） | 无上述治理操作 | 不可写入 |
| `ARCHIVED` | 所有者（Owner） | 恢复、删除 | 恢复进入 `ACTIVE`；删除另须满足依赖检查 |
| `ARCHIVED` | 空间管理员（Admin）或成员（Member） | 无上述治理操作 | 不因曾有编辑权限获得恢复权限 |
| 命名空间状态 | 平台角色 | 平台专用入口的治理操作 | 条件与限制 |
| --- | --- | --- | --- |
| `ACTIVE` | 超级管理员（SUPER_ADMIN） | 冻结、归档 | 不要求命名空间成员身份；不包含永久删除 |
| `FROZEN` | 超级管理员（SUPER_ADMIN） | 解冻、归档 | 不要求命名空间成员身份 |
| `ARCHIVED` | 超级管理员（SUPER_ADMIN） | 恢复至 `ACTIVE` | 不要求命名空间成员身份 |
| 任意状态 | 技能管理员（SKILL_ADMIN）或用户管理员（USER_ADMIN） | 单靠平台角色没有上述专用治理权限 | 若另有命名空间角色，按上一张表判断 |
`GLOBAL` 等非团队类型不可变，上述生命周期操作不可用。永久删除只能由命名空间所有者发起，且必须没有技能、审核任务、指向该命名空间的提升申请或创作草稿；存在任一依赖时服务端拒绝。归档不清除这些依赖，也不会自动满足删除条件。不要为绕过检查而删除数据库记录；先在对应资源管理入口处理依赖，再刷新命名空间设置页核对删除按钮。
依据：[NamespaceAccessPolicy](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/namespace/NamespaceAccessPolicy.java)、[NamespaceService](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/namespace/NamespaceService.java) 与仅向超级管理员开放的 [AdminNamespaceController](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/admin/AdminNamespaceController.java)。完成操作后核对目标命名空间状态，不仅查看请求提示。
## 功能描述
@ -70,7 +92,7 @@
**创建命名空间**：
1. 访问 `/dashboard/namespaces`
1. 核对当前账号具有平台技能管理员（`SKILL_ADMIN`）或超级管理员（`SUPER_ADMIN`）角色，再访问 `/dashboard/namespaces`；普通成员没有创建入口，须联系有权创建者。
2. 点击「创建命名空间」
3. 填写信息：
- 名称：团队名称（例如 "iFlytek AI Team"）
@ -79,7 +101,7 @@
![流程图](/diagrams/namespace-create-flow.png)
4. 提交创建，系统自动将你设为 Owner
4. 提交创建，注册中心将创建者设为该命名空间所有者（Owner）；这不会新增平台角色。
**添加成员**：
@ -128,7 +150,7 @@
## API 接口
**创建命名空间**：
```bash
```http
POST /api/v1/namespaces
Content-Type: application/json
@ -147,12 +169,12 @@ Content-Type: application/json
| description | string | 描述（可选，最多 512 字符） |
**获取命名空间详情**：
```bash
```http
GET /api/v1/namespaces/{slug}
```
**更新命名空间**：
```bash
```http
PUT /api/v1/namespaces/{slug}
Content-Type: application/json
@ -163,7 +185,7 @@ Content-Type: application/json
```
**添加成员**：
```bash
```http
POST /api/v1/namespaces/{slug}/members
Content-Type: application/json
@ -174,7 +196,7 @@ Content-Type: application/json
```
**更新成员角色**：
```bash
```http
PUT /api/v1/namespaces/{slug}/members/{userId}/role
Content-Type: application/json
@ -184,12 +206,12 @@ Content-Type: application/json
```
**移除成员**：
```bash
```http
DELETE /api/v1/namespaces/{slug}/members/{userId}
```
**冻结命名空间**：
```bash
```http
POST /api/v1/namespaces/{slug}/freeze
Content-Type: application/json
@ -199,7 +221,7 @@ Content-Type: application/json
```
**解冻命名空间**：
```bash
```http
POST /api/v1/namespaces/{slug}/unfreeze
```

123
docs/skillhub/guide/review.md
View file

@ -2,83 +2,85 @@
## 审核员的检查清单
1. 核对审核对象、提交者和目标版本。技能版本、头像或资料变更、套装版本不能混用同一判断。
1. 核对对象、提交者及目标版本；版本、头像资料和套装不能混用判断。
2. 读取本次提交的文件与变更，不仅阅读当前公开版本。新版审核期间，旧公开版本可能仍可下载。
3. 检查扫描状态及发现项。扫描执行失败、风险发现和未配置某项分析器分别处理；空报告不能当作安全结论。
4. 检查可见范围与受众，特别是套装每个成员的可用性和入口身份。成员通过审核不自动批准套装。
5. 批准前确认当前数据仍有效；拒绝时写明具体文件、问题及修订方向。点击失败时重新读取状态，避免对旧页面重复作出相反决定。
6. 审核完成后查看记录和发布版本。审核操作成功不验证本地 Agent 的技能执行效果。
6. 审核后核对记录及发布结果；Agent 执行效果需另验。
### 作者如何跟踪和修订
在“我的提交”查看待审任务和意见，未完成审核前可按权限撤回。撤回是停止当前审核，不会删除已发布旧版本或撤销已批准的全局提升。被拒绝后根据意见修订，再通过当前版本页面提供的重新提交操作继续；不要把上传成功当成审核重开成功。
普通 `PUBLIC / NAMESPACE_ONLY` 上传创建审核任务；`PRIVATE` 上传先保留，须确认发布或另行提审。在“我的提交”查看任务和意见；有权撤回者在待审任务选择「撤回」并确认。撤回是停止当前审核，不会删除已发布旧版本或撤销已批准的全局提升。被拒绝后根据意见修订，再通过当前版本页面提供的重新提交操作继续；不要把上传成功当成审核重开成功。
## 功能描述
## 状态对象对照
SkillHub 提供了完整的审核工作流，确保发布到注册中心的技能包符合团队规范。
先识别对象；同名枚举不表示同一流程。任务为 `PENDING` 时，版本可能仍在 `SCANNING`；不得用它替代版本的 `PENDING_REVIEW`。
审核机制分为两层：
- **命名空间审核**：团队管理员审核本命名空间的技能包
- **平台审核**：平台管理员审核推广到全局的技能包
### 审核任务状态
![概念图](/diagrams/review-concept.png)
| 状态 | 判断依据 | 处理者 | 下一步 |
| --- | --- | --- | --- |
| `PENDING` | 任务等待审核决定 | 有权限的空间审核员或平台技能管理员 | 执行上方检查清单后决定 |
| `APPROVED` | 任务已批准 | 提交者 | 核对版本或资料生效结果 |
| `REJECTED` | 任务已拒绝并保留意见 | 提交者 | 修订后重提 |
| `SUPERSEDED` | 任务已被后续申请替代 | 提交者与审核员 | 查看当前申请，不处理旧任务 |
**审核流程**：
[ReviewTaskStatus](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/ReviewTaskStatus.java) 无 `WITHDRAWN`；技能版本撤回会删除待审任务并更新版本状态，见 [ReviewService](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/ReviewService.java)。
1. 开发者发布技能包 → 进入「待审核」状态
2. 管理员收到通知 → 查看技能包详情
3. 管理员决策 → 批准或拒绝
4. 批准后 → 技能包正式发布
5. 拒绝后 → 开发者收到反馈，可修改后重新提交
### 技能版本状态
**审核状态**：
版本 `DRAFT` 不是创作 API 草稿对象。
| 状态 | 说明 |
|------|------|
| **PENDING** | 待审核 |
| **APPROVED** | 已批准 |
| **REJECTED** | 已拒绝 |
| **WITHDRAWN** | 已撤回 |
| 状态 | 判断依据 | 处理者 | 下一步 |
| --- | --- | --- | --- |
| `DRAFT` | 版本尚处草稿阶段 | 技能所有者 | 完成准备，尚未发布 |
| `SCANNING` | 扫描尚在运行 | 扫描服务 | 等待报告后审核 |
| `SCAN_FAILED` | 扫描执行失败 | 部署方与技能所有者 | 定位错误后重试 |
| `UPLOADED` | 已上传但尚未发布 | 技能所有者 | 确认发布或提交审核 |
| `PENDING_REVIEW` | 版本等待人工决定 | 有权审核员 | 核对本次版本并作决定 |
| `PUBLISHED` | 版本已发布 | 使用者与技能所有者 | 按可见范围使用，执行效果另验 |
| `REJECTED` | 版本未获批准 | 技能所有者 | 修订并重新提交 |
| `YANKED` | 版本已撤下 | 技能所有者与使用者 | 检查可安装的替代版本 |
**治理功能**：
枚举以 [SkillVersionStatus](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/SkillVersionStatus.java) 为准；操作入口见[发布与更新技能](./skill-publish.html)。
- **审核工作流**：按权限逐项审核技能版本、资料变更和套装
- **举报系统**：用户可以举报不当技能包
- **推广管理**：将命名空间技能包推广到全局
- **审计日志**：记录所有治理操作
### 套装导入操作状态
头像变更复用技能审核申请。机器阻止与人工拒绝是不同状态；开关组合、审核操作及云审核接入步骤详见 [技能头像与图片审核接入](/guide/skill-avatars)。
| 状态 | 判断依据 | 处理者 | 下一步 |
| --- | --- | --- | --- |
| `RUNNING` | 导入正在执行 | 导入服务 | 跟踪原操作，不重复确认 |
| `WAITING_FOR_MEMBERS` | 等待成员版本就绪 | 导入服务与成员审核员 | 查看成员进度 |
| `BLOCKED_RETRYABLE` | 存在可重试阻塞 | 导入者 | 排障后重试原操作 |
| `REPREVIEW_REQUIRED` | 原预览不能继续确认 | 导入者 | 重新预览并核对差异 |
| `SUITE_DRAFT_CREATED` | 已创建技能套装草稿 | 套装所有者 | 管理页继续发布，尚未批准 |
| `CANCELLED` | 操作已取消 | 导入者 | 核对成员动作，并非全部回滚 |
## 先确认审核对象
依据 [SkillSuiteBundleOperationStatus](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/suite/bundle/SkillSuiteBundleOperationStatus.java)；恢复步骤见[套装 Bundle 导入](./suite-bundle.html)。
审核任务状态与技能版本状态不同：任务为 PENDING 时，版本可能仍在 SCANNING。先等待扫描完成并检查风险，再作审核决定。成员技能审核通过不代表引用它的 Suite 已通过；Suite 有独立审核。Bundle 导入先完成成员发布，再创建 Suite 草稿，详见[技能套装](/guide/skill-suites)与[批量导入](/guide/suite-bundle)。
### 头像审核结果
## 使用场景
头像复用技能审核申请，但结果分三个字段维度。
**场景一：命名空间管理员审核**
| 字段与取值 | 判断依据 | 处理者 | 下一步 |
| --- | --- | --- | --- |
| 候选 `status`：`PENDING`、`ACTIVE`、`REJECTED`、`SUPERSEDED`、`REMOVED` | 依次为待处理、正在使用、已拒绝、已替代、已移除 | 技能所有者与有权审核员 | 核对当前候选和使用中的头像 |
| `machineStatus`：`SKIPPED`、`PENDING`、`PROCESSING`、`PASSED`、`BLOCKED`、`ERROR` | 依次为跳过、待处理、执行中、机器允许、机器阻止、执行错误 | 机器审核服务与部署方 | `ERROR` 先排查服务；`BLOCKED` 不等同人工已拒绝 |
| `reviewStatus`：`NOT_REQUIRED`、`PENDING`、`APPROVED`、`REJECTED`、`APPEAL_PENDING` | 依次为无需人工、待审、已批准、已拒绝、申诉待审 | 有权审核员与技能所有者 | 读取意见及当前候选，按允许动作处理 |
团队管理员审核成员提交的技能包，确保符合团队规范。
依据 [SkillAvatarCandidate](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/SkillAvatarCandidate.java)；响应的 `candidateStatus` 是候选状态；配置与重试见[技能头像与审核](./skill-avatars.html)。
![操作截图](/screenshots/review-list.png)
## 审核入口
**场景二：平台管理员审核推广**
角色与自审限制见本页末尾；举报、提升申请另行处理。
平台管理员审核从命名空间推广到全局的技能包。
**场景三：举报处理**
用户举报不当技能包，管理员调查并处理。
![审核对象及职责](/diagrams/review-concept.png)
![审核任务列表](/screenshots/review-list.png)
## 使用步骤
**提交审核**：
1. 普通 PUBLIC / NAMESPACE_ONLY 上传创建审核任务；PRIVATE 上传先保留，需确认发布或另行提审
2. 开发者可以在「我的提交」中查看审核状态
3. 等待管理员审核
**审核技能包**：
1. 访问 `/dashboard/reviews`
@ -119,15 +121,6 @@ SkillHub 提供了完整的审核工作流，确保发布到注册中心的技
SkillHub 能保证的是结构正确、证据可追溯、版本快照不可变；不能替作者保证“真的合规”。
**撤回审核**：
开发者发现问题，可以在审核通过前撤回提交：
1. 访问「我的提交」
2. 找到待审核的技能包
3. 点击「撤回」
4. 确认撤回
### 删除已提升到全局的技能
如果永久删除时提示「已提升的技能须通过审核撤销流程删除」，请从团队来源技能的详情页处理全局发布。隐藏、归档或撤回待审提交不会删除已经批准的全局技能；提交撤销申请也不代表撤销已完成。
@ -151,7 +144,7 @@ SkillHub 能保证的是结构正确、证据可追溯、版本快照不可变
## API 接口
**提交审核**：
```bash
```http
POST /api/v1/reviews
Content-Type: application/json
@ -161,7 +154,7 @@ Content-Type: application/json
```
**批准审核**：
```bash
```http
POST /api/v1/reviews/{id}/approve
Content-Type: application/json
@ -171,7 +164,7 @@ Content-Type: application/json
```
**拒绝审核**：
```bash
```http
POST /api/v1/reviews/{id}/reject
Content-Type: application/json
@ -187,22 +180,22 @@ Content-Type: application/json
| comment | string | 审核意见（批准时可选；拒绝时应填写明确原因） |
**列出待审核任务**：
```bash
```http
GET /api/v1/reviews/pending?namespaceId=123&page=0&size=20
```
**列出我的提交**：
```bash
```http
GET /api/v1/reviews/my-submissions?page=0&size=20
```
**获取审核详情**：
```bash
```http
GET /api/v1/reviews/{id}
```
**获取审核中的技能包详情**：
```bash
```http
GET /api/v1/reviews/{id}/skill-detail
GET /api/v1/reviews/{id}/skill-detail?includeDocumentation=false
```
@ -210,17 +203,17 @@ GET /api/v1/reviews/{id}/skill-detail?includeDocumentation=false
`includeDocumentation` 缺省为 `true`，保持原响应行为。设为 `false` 时仍返回技能、版本、文件元数据与说明文件路径，`documentationContent` 为空且不读取对象存储正文；审核详情首屏使用此模式，进入“技能内容”后再取正文。
**下载审核包**：
```bash
```http
GET /api/v1/reviews/{id}/download
```
**撤回审核**：
```bash
```http
POST /api/v1/reviews/{id}/withdraw
```
**举报技能包**：
```bash
```http
POST /api/v1/skills/{namespace}/{slug}/reports
Content-Type: application/json

131
docs/skillhub/guide/scanner.md
View file

@ -9,19 +9,108 @@
- 已完成且有发现项：根据风险与策略处理，不等于执行失败；人工审核仍需判断。
- 未启用或没有报告：不是“零风险”。PRIVATE 路径可在禁用扫描时上传；普通 PUBLIC / NAMESPACE_ONLY 发布要求扫描启用。
### 运维排查顺序
### 部署方排查顺序
1. 确认后端实际使用的 Scanner 地址和模式。下表是应用默认值；release Compose 将模式设为 `upload`，不能假设容器使用宿主机的 `localhost`。
2. 从后端可达的网络检查 Scanner 的 `/health`，再检查实际扫描请求和返回。健康成功不代表某个包扫描成功。
3. 对照技能版本、请求时间及后端/Scanner 日志，区分网络或服务暂时不可用与包分析错误。暂时不可用会保留待处理并重领，不能只因等待较久就认定失败。
4. 修复服务或配置后跟踪原任务。记录版本 ID、状态和错误信息供管理员定位；不要公开包内秘密或认证信息。
以下命令由有本实例容器或目标命名空间操作权限的部署方执行；普通技能作者提供版本与报告信息，不要把业务角色当作主机操作权限。先选择实际部署路径。Compose 命令在包含本次 `.env.release` 与 `compose.release.yml` 的目录执行；Kubernetes 命令以 Kustomize 默认命名空间 `skillhub` 为例。Helm 实例先按 [Chart README](https://github.com/iflytek/skillhub/blob/main/charts/skillhub/README.md) 核对 Deployment 名称，不要混用两条部署路径。
下列探测参数只约束本次诊断请求，不修改后台扫描任务配置。
| 操作 | 示例值 | 影响范围 | 说明 |
| --- | --- | --- | --- |
| `wget -T` | 5秒 | DNS、连接和读取阶段超时 | 不代表整个扫描任务的超时。 |
| `wget -t` | 1次 | 本次健康请求的尝试次数 | 不触发技能扫描或修改任务状态。 |
1. 核对注册中心容器声明的开关和模式，再从同一容器检查默认 `/health`。命令只回显 `true` / `false`、`local` / `upload` 与三个官方默认地址的固定主机名；其他值使用固定脱敏标记，不回显原配置。包含用户信息、查询、fragment、空白或非保守 HTTP(S) 形态的 URL 会跳过探测；这只是诊断限制，不是注册中心的 URL 配置校验。缺失变量使用应用默认值；额外 Spring 配置与自定义健康路径须在实例受保护配置中核对。
Compose：
```bash
docker compose --env-file .env.release -f compose.release.yml exec -T server sh -c '
enabled=${SKILLHUB_SECURITY_SCANNER_ENABLED:-true}
mode=${SKILLHUB_SECURITY_SCANNER_MODE:-local}
url=${SKILLHUB_SECURITY_SCANNER_URL:-http://localhost:8000}
case "$enabled" in true|false) ;; *) enabled=unrecognized_redacted ;; esac
case "$mode" in local|upload) ;; *) mode=unrecognized_redacted ;; esac
case "$url" in
http://localhost:8000|http://localhost:8000/) host=localhost:8000 ;;
http://skill-scanner:8000|http://skill-scanner:8000/) host=skill-scanner:8000 ;;
http://skillhub-scanner:8000|http://skillhub-scanner:8000/) host=skillhub-scanner:8000 ;;
*) host=custom_or_unrecognized_redacted ;;
esac
probe=allowed
case "$url" in http://?*|https://?*) ;; *) probe=skipped_unrecognized_url ;; esac
case "$url" in *[!a-zA-Z0-9:/._~\[\]-]*|*@*|*\?*|*\#*|*\\*) probe=skipped_unrecognized_url ;; esac
authority=${url#*://}; authority=${authority%%/*}
case "$authority" in ""|:*|*:) probe=skipped_unrecognized_url ;; esac
printf "enabled=%s mode=%s scanner_host=%s\n" "$enabled" "$mode" "$host"
if [ "$enabled" = false ]; then printf "health=skipped_disabled\n"
elif [ "$enabled" != true ]; then printf "health=skipped_unrecognized_enabled\n"
elif [ "$mode" = unrecognized_redacted ]; then printf "health=skipped_unrecognized_mode\n"
elif [ "$probe" != allowed ]; then printf "health=%s\n" "$probe"
else
wget -T 5 -t 1 -q -O /dev/null -- "${url%/}/health"; printf "health_exit=%s\n" "$?"
fi
'
```
Kustomize：
```bash
kubectl -n skillhub exec deployment/skillhub-server -c server -- sh -c '
enabled=${SKILLHUB_SECURITY_SCANNER_ENABLED:-true}
mode=${SKILLHUB_SECURITY_SCANNER_MODE:-local}
url=${SKILLHUB_SECURITY_SCANNER_URL:-http://localhost:8000}
case "$enabled" in true|false) ;; *) enabled=unrecognized_redacted ;; esac
case "$mode" in local|upload) ;; *) mode=unrecognized_redacted ;; esac
case "$url" in
http://localhost:8000|http://localhost:8000/) host=localhost:8000 ;;
http://skill-scanner:8000|http://skill-scanner:8000/) host=skill-scanner:8000 ;;
http://skillhub-scanner:8000|http://skillhub-scanner:8000/) host=skillhub-scanner:8000 ;;
*) host=custom_or_unrecognized_redacted ;;
esac
probe=allowed
case "$url" in http://?*|https://?*) ;; *) probe=skipped_unrecognized_url ;; esac
case "$url" in *[!a-zA-Z0-9:/._~\[\]-]*|*@*|*\?*|*\#*|*\\*) probe=skipped_unrecognized_url ;; esac
authority=${url#*://}; authority=${authority%%/*}
case "$authority" in ""|:*|*:) probe=skipped_unrecognized_url ;; esac
printf "enabled=%s mode=%s scanner_host=%s\n" "$enabled" "$mode" "$host"
if [ "$enabled" = false ]; then printf "health=skipped_disabled\n"
elif [ "$enabled" != true ]; then printf "health=skipped_unrecognized_enabled\n"
elif [ "$mode" = unrecognized_redacted ]; then printf "health=skipped_unrecognized_mode\n"
elif [ "$probe" != allowed ]; then printf "health=%s\n" "$probe"
else
wget -T 5 -t 1 -q -O /dev/null -- "${url%/}/health"; printf "health_exit=%s\n" "$?"
fi
'
```
2. 对照结果：标准 Compose 为 `enabled=true mode=upload scanner_host=skill-scanner:8000`；Kustomize 为 `enabled=true mode=upload scanner_host=skillhub-scanner:8000`；可达时显示 `health_exit=0`。这只证明健康端点可达，不能证明某个版本已扫描。`enabled=false` 时不做健康请求，按禁用后的发布限制处理。 `custom_or_unrecognized_redacted` 表示地址未在显示白名单中，需由部署方在受保护配置中核对，不能公开真实值；不含凭据的普通自定义 HTTP(S)／IPv6 地址仍可探测。`skipped_unrecognized_url`、`skipped_unrecognized_enabled` 或 `skipped_unrecognized_mode` 表示本次诊断已跳过，不代表产品判定该配置有效或无效。
3. 关联本次版本与日志。在技能详情的本版本扫描报告中读取状态和失败原因，再在同一时间范围的日志中查找该版本 ID；不要用旧版本报告解释新版本。以下命令只读取本地日志，反馈前须脱敏，不能直接公开整份日志。
```bash
# Compose，仍在本次运行目录
docker compose --env-file .env.release -f compose.release.yml logs --since=10m --tail=100 server skill-scanner
# Kustomize，使用清单默认名称
kubectl -n skillhub logs deployment/skillhub-server -c server --since=10m --tail=100
kubectl -n skillhub logs deployment/skillhub-scanner -c scanner --since=10m --tail=100
```
4. 按下表处理后跟踪同一版本。临时不可达可进入重试/重领，持续失败也受实例重试与超时配置约束；不要仅凭等待时间断定“有害”，也不要重复上传来制造新版本。
| 现象 | 最可能原因 | 定位手段 | 检查与处理 |
| --- | --- | --- | --- |
| 非私有上传被拒绝，出现 `error.security.scanner.required` | 扫描开关关闭 | 上方容器命令显示 `enabled=false`；核对本次是否使用 `--no-scanner` | 由部署方恢复扫描服务及注册中心配置后重试；不要重复上传或改写审核状态绕过检查。 |
| 标准部署显示 `local` 或目标为 `localhost:8000` | 环境透传缺失或私有覆盖层改变默认配置 | 对照下方同格默认/覆盖值及本次 `server` 环境声明 | 修正 `SKILLHUB_SECURITY_SCANNER_MODE` / `SKILLHUB_SECURITY_SCANNER_URL` 的透传并重新创建受影响容器；不要把容器 localhost 当作宿主机。 |
| `health_exit` 非零 | Scanner 未就绪、DNS/网络或地址错误 | Compose 用 `docker compose --env-file .env.release -f compose.release.yml ps skill-scanner`；Kustomize 用 `kubectl -n skillhub get pods -l app.kubernetes.io/name=skillhub-scanner` | 先恢复服务与连通性，再检查原任务；不要先删除数据库、Redis 或持久卷。 |
| 健康可达但版本仍在 `SCANNING` 或变为 `SCAN_FAILED` | 请求未完成、扫描执行错误或恢复重试超限 | 读取本版本报告的失败原因，关联上方注册中心与 Scanner 日志 | 区分执行失败与发现风险；仅在版本页提供重试且有操作权限时重试，不要把健康响应当作扫描完成或人工批准。 |
诊断命令依据 [Compose 清单](https://github.com/iflytek/skillhub/blob/main/compose.release.yml)、[Kustomize 后端清单](https://github.com/iflytek/skillhub/blob/main/deploy/k8s/base/backend-deployment.yaml) 与 [Server 镜像](https://github.com/iflytek/skillhub/blob/main/server/Dockerfile)；所用 `sh`、`wget` 在标准 Server 镜像中提供。
## 功能描述
SkillHub 内置了 **Skill Scanner** 安全扫描服务，在技能包发布时自动检测潜在的安全风险。这是保障企业内部技能包安全的重要防线。
SkillHub 内置了 **Skill Scanner** 安全扫描服务，在技能包发布时自动检测潜在的安全风险。报告提供结构化发现与执行证据，不能据此承诺技能内容安全。
启用扫描的上传会经过安全扫描，扫描结果会影响审核决策，帮助管理员快速判断技能包是否安全可靠。
启用扫描的上传会经过安全扫描，扫描结果会影响审核决策，供有权限的审核员结合使用场景判断；扫描完成不等于人工批准。
**核心特性**：
@ -77,15 +166,17 @@ Skill Scanner 执行多引擎分析
### 基础配置
在 `.env` 文件或环境变量中配置：
下表列出本页排查所需的基本应用绑定；完整字段见表后的应用配置来源。环境变量必须实际传入 Server；仅在 `.env.release` 增加未被 Compose 引用的键不会生效。修改后重新创建 Server 容器；Kubernetes 须更新对应覆盖配置并滚动受影响 Deployment。
| 环境变量 | 说明 | 默认值 |
|----------|------|--------|
| `SKILLHUB_SECURITY_SCANNER_ENABLED` | 启用安全扫描 | `true` |
| `SKILLHUB_SECURITY_SCANNER_URL` | Scanner 服务地址 | `http://localhost:8000` |
| `SKILLHUB_SECURITY_SCANNER_MODE` | 扫描模式（local / upload） | `local` |
| `SKILLHUB_SCANNER_POLICY_PRESET` | 策略预设 | `balanced` |
| `SKILLHUB_SCANNER_FAIL_ON_SEVERITY` | 自动阻止的严重级别 | `high` |
| 配置项 | 用途 | 应用默认与部署覆盖 | 检查与处理 |
| --- | --- | --- | --- |
| `SKILLHUB_SECURITY_SCANNER_ENABLED` | 启用扫描 | 应用、release Compose、Kustomize 和 Helm 默认 `true`；`--no-scanner` 将运行实例设为 `false` | `false` 时拒绝新的非私有上传；已有版本扩大范围的报告复用条件见下文。 |
| `SKILLHUB_SECURITY_SCANNER_URL` | Scanner 地址 | 应用 `http://localhost:8000`；release Compose 覆盖为 `http://skill-scanner:8000`；Kustomize 为 `http://skillhub-scanner:8000`；Helm 按 release 生成 Service 地址 | 用上方同容器健康请求验证，不能照搬宿主机 localhost。 |
| `SKILLHUB_SECURITY_SCANNER_MODE` | `local` / `upload` 协议 | 应用默认 `local`；release Compose、Kustomize 和 Helm 均覆盖为 `upload` | `upload` 上传包；`local` 要求双方在相同路径可见同一目录。 |
| `SKILLHUB_SCANNER_POLICY_PRESET` | 策略预设 | 应用默认 `balanced`；以实例透传为准 | 未被部署清单引用时须显式补入 Server 环境，修改后重建。 |
| `SKILLHUB_SCANNER_FAIL_ON_SEVERITY` | 阻断严重级别 | 应用默认 `high`；以实例透传为准 | 阈值属于扫描策略，不等于人工批准条件。 |
默认值与覆盖依据：[应用配置](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/resources/application.yml)、[Kustomize ConfigMap](https://github.com/iflytek/skillhub/blob/main/deploy/k8s/base/configmap.yaml) 和 [Helm ConfigMap](https://github.com/iflytek/skillhub/blob/main/charts/skillhub/templates/configmap.yaml)。
### LLM 分析配置（可选）
@ -101,18 +192,22 @@ Skill Scanner 执行多引擎分析
### 部署说明
使用一键部署时，Scanner 服务默认启用。如果不需要安全扫描，可以通过 `--no-scanner` 参数禁用：
使用运行脚本部署时，Scanner 默认启用。`--no-scanner` 不启动 Scanner，并关闭注册中心扫描开关。**禁用后，公开（`PUBLIC`）与空间成员可见（`NAMESPACE_ONLY`）的上传发布请求被拒绝**，返回 `error.security.scanner.required`。私有（`PRIVATE`）仍可上传，但上传后是 `UPLOADED`，还需有权限的操作者确认发布，不能把上传成功当成发布完成。
已发布私有技能申请扩大可见范围时，最新发布版本若已有可复用报告（`taskId`、`scannedAt` 非空，`failureReason=null` 且 `isSafe=true`），可沿用该报告进入审核；没有此报告且扫描关闭时同样拒绝。这里的机器结果不代表内容安全或人工已批准。
```bash
# 部署时禁用 Scanner
curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --no-scanner
```
发布限制依据：[发布前置检查](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillPublishService.java)、[可见范围变更](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillVisibilityService.java) 与 [私有版本确认](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillReviewSubmitService.java)。
## 注意事项
> **异步上传不等于发布放行**：普通公开及空间内发布要求扫描已启用，扫描未完成时不能视为已发布。SCAN_FAILED 是执行失败；扫描发现风险与执行失败须分别处理。扫描通过也不等于人工审核通过。
> **异步上传不等于发布放行**：普通公开及空间成员可见新版本上传要求扫描已启用，扫描未完成时不能视为已发布。SCAN_FAILED 是执行失败；扫描发现风险与执行失败须分别处理。扫描通过也不等于人工审核通过。
- **扫描耗时**：根据技能包大小和启用的引擎数量，扫描可能需要几秒到几分钟
- **LLM 分析成本**：启用 LLM 分析会产生 API 调用费用，建议在生产环境中评估成本
- **策略调优**：`balanced` 策略适合大多数场景，企业可以根据安全需求自定义策略
- **健康检查**：通过 `GET http://localhost:8000/health` 检查 Scanner 服务状态
- **健康检查**：使用上方[部署方排查顺序](#部署方排查顺序)从注册中心容器访问已配置的 Scanner；不要把宿主机或 Server 的 localhost 当作 Scanner 地址。

195
docs/skillhub/guide/skill-publish.md
View file

@ -2,11 +2,11 @@
## 从文件到可安装版本
先确定要发布的是单个技能还是套装：单个技能的上传根目录包含一个 `SKILL.md`；多个技能一起创作和导入请用[套装导入](/guide/suite-bundle)。不要把多份 `SKILL.md` 随意塞进单技能 ZIP。
单技能根目录只放一个 `SKILL.md`；多技能创作与导入使用[套装导入](./suite-bundle.html)，不要混入单技能 ZIP。
1. 在本地 Agent 中验证技能指令、脚本和引用路径，整理成独立目录。
2. 确认目标命名空间可写，选择 PUBLIC、NAMESPACE_ONLY 或 PRIVATE。公开发布不是共享所有者电脑上的环境：依赖工具及必要配置应写入技能说明。
3. 上传后核对预览的名称、版本、摘要和警告，再提交。预检查阻断必须修正；可确认的警告需逐项理解，不能把确认当作校验通过。
2. 确认目标命名空间可写，选择 PUBLIC、NAMESPACE_ONLY 或 PRIVATE。依赖工具及配置须写入技能说明，发布不共享本地环境。
3. 上传预览后核对名称、版本、摘要与警告；阻断必须修正，确认警告不能替代校验。
4. 在“我的技能”跟踪本次版本，按状态完成扫描、审核或私有确认发布。
5. 用另一位目标受众用户检查详情与下载权限，再在目标 Agent 安装并调用。注册中心发布成功不证明技能实际任务效果。
@ -21,9 +21,11 @@ my-skill/
`SKILL.md` 中引用的相对路径应能在包内找到。不要包含凭证、缓存或与技能无关的项目文件。`version` 可省略，服务器会生成时间版本；需要可预测版本时显式填写，例如 `1.0.0`，下一次更新填写 `1.0.1`。顶层 `version` 优先于 `metadata.version`，不要同时填写不同值。
版本可按精确版本、标签或指纹解析，不支持 `^` / `~` 范围。`latest`、`beta`、`stable` 等标签用于版本定位；`latest` 遵循发布状态和发布指针，不按最高 SemVer 自动选版。详情可浏览包内文件，并按版本或标签下载。
### 更新已有技能
在“我的技能”选择更新，或对同一命名空间和技能名称重新执行发布命令。先核对目标坐标，避免修改 `name` 后创建了另一个技能。已经正式发布的版本不可覆盖，正常迭代应使用新版本号。上传待审新版期间，公开读者仍使用旧的已发布版本；审核通过后再检查详情显示的版本、名称和摘要。
在“我的技能”选择更新，或对原坐标重新发布。修改 `name` 可能创建另一技能；已发布版本不可覆盖，迭代使用新版本号。待审期间公众仍见旧版本；批准后核对详情版本、名称和摘要。
本地已有安装不会因服务端发布新版而自动更新。使用者需要明确执行 CLI 升级；套装成员还受套装固定版本约束，不能以成员发布新版本代替发布新的套装版本。
@ -33,70 +35,18 @@ my-skill/
| --- | --- |
| `SKILL.md` frontmatter 无效 | 修正 YAML 与必需字段，重新上传预览 |
| 预检查提示疑似密钥或不允许的文件 | 从包中移除敏感内容或修正结构，不能通过确认警告绕过硬错误 |
| 版本已存在 | 先查看已有版本，正常更新使用新的版本号 |
| 扫描仍在进行 | 等待状态更新，不重复上传同一版本制造多次任务 |
| `SCAN_FAILED` | 查看失败原因，按页面提供的重试入口处理；基础设施故障由管理员排查 |
| 版本已存在 | 查看已有版本，更新使用新版本号 |
| 扫描仍在进行 | 等待状态更新，不重复上传同一版本 |
| `SCAN_FAILED` | 查看失败原因，按页面提供的重试入口处理；基础设施故障由部署方排查 |
| 审核拒绝 | 阅读具体意见，修订包后通过页面支持的重新提交流程操作 |
| 命名空间冻结或已失去成员资格 | 先恢复合法写权限；持有旧安装包不赋予发布权限 |
## 功能描述
## 准备元数据与发布入口
Skill 发布是 SkillHub 的核心功能。开发者可以将本地开发的 Agent 技能包一键上传到注册中心，系统会自动处理版本管理、元数据提取、文件索引等工作。
### 准备元数据
![概念图](/diagrams/skill-publish-concept.png)
**解决的问题**：
传统方式下，团队成员通过 Git 仓库或文件共享来分发技能包。这种方式存在几个痛点：
- **版本混乱**：不同版本散落在各处，难以追踪
- **权限失控**：无法精细控制谁能访问哪些技能包
- **发现困难**：新成员不知道团队已有哪些可用技能
SkillHub 提供了类似 npm 的发布体验，但增加了企业级的权限控制和审核机制。
**核心特性**：
- **语义化版本**：支持 `major.minor.patch` 版本号规范
- **标签系统**：`latest`、`beta`、`stable` 等自定义标签
- **多版本共存**：同一技能包可以保留多个历史版本
- **版本解析**：按精确版本、标签或指纹解析；不支持 `^` / `~` 版本范围
- **文件浏览**：在线浏览技能包内的文件结构
- **下载分发**：支持按版本、按标签下载
## 使用场景
**场景一：开发者发布新技能**
你刚完成了一个 Claude Code 技能包，想让团队其他成员也能使用。
![操作截图](/screenshots/homepage.png)
**场景二：版本迭代**
技能包需要修复 bug 或添加新功能，发布新版本并保持向后兼容。
**场景三：Beta 测试**
新功能还不稳定，先发布 `beta` 标签让少数人测试，稳定后再推广到 `latest`。
**场景四：版本回滚**
发现新版本有严重问题，需要将 `latest` 标签指向上一个稳定版本。
## 使用步骤
1. **准备技能包**
准备一个根目录包含 `SKILL.md` 的技能目录：
- 在 `SKILL.md` 中同时编写 YAML frontmatter 和技能指令。
- frontmatter 必须包含 `name` 和 `description`；需要指定版本时，在其中设置 `version`。
- `package.json` 不会提供或替代这些技能元数据。
- 保持文件结构清晰，不包含敏感信息。
例如，将以下内容保存为 `my-skill/SKILL.md`：
frontmatter 必须含 `name`、`description`；`package.json` 不能替代技能元数据。将示例保存为 `my-skill/SKILL.md`：
```markdown
---
@ -108,7 +58,7 @@ version: 1.0.0
Summarize the supplied text as numbered steps.
```
如需在列表、搜索结果和详情页显示中文或其他易读名称，可添加可选的 `metadata.display-name`：
显示中文等易读名称，可选填 `metadata.display-name`：
```yaml
---
@ -123,36 +73,38 @@ metadata:
`name` 仍用于生成 slug、安装坐标和链接；`metadata.display-name` 仅用于展示。
展示名必须是字符串，去除首尾空白后最多 200 个字符；未填写、为 null 或空白时回退到 `name`。
展示名随技能版本发布：已有公开版本的标题在更新审核通过后才改变。
无需数据库迁移；已有技能可保持原 `name`，增加展示名后发布新版本。
已有技能增加展示名无需数据库迁移，须发布新版本。
打包已有技能时，应一并保留其所需的脚本、参考文件、`agents/` 元数据和许可证文件。
下一步发布命令的路径应指向该技能目录（本例为 `./my-skill`）。
网页发布或更新时，可在上传技能包后编辑“显示名称”。默认读取包内 `metadata.display-name`，缺省使用 `name`；你修改的值优先，换包不会覆盖已填写的名称，留空则采用包内名称。名称最多 200 个字符，随本次版本审核，不单独修改线上标题；只改头像时此字段不可用。
网页上传后可编辑“显示名称”：包内 `metadata.display-name` 优先于 `name`，网页手填值优先于包且换包不覆盖，留空回退包内名称。上限 200 个字符，随版本审核；仅改头像时不可改名。
“我的技能”会显示待审新版的名称和摘要，仅保留一个主状态，并说明本次版本与当前公开版本。点击后可预览新版；公众继续看到已发布版本。详情中始终显示可复制的 `@命名空间/slug`，改名不改变链接或安装标识。
“我的技能”展示待审名称、摘要、一个主状态及与公开版的比较，可预览新版；公众仍见已发布版。详情可复制 `@命名空间/slug`，改名不改坐标。
网页填写的名称保存在平台版本元数据中，包内 `SKILL.md` 不会被改写；下载 ZIP 沿用现有重新打包逻辑，压缩后的字节可能不同。CLI 发布继续使用包内名称规则。审核通过、撤下新版回退或提升所选版本时，展示名称和摘要跟随对应版本。
`skillhub.example.com`、`YOUR_API_TOKEN` 与 `my-team` 是占位值；必须替换为实例地址、本人凭据和目标命名空间，不要提交真实 Token。
2. **使用 CLI 发布（推荐）**
网页名称存于版本元数据，不改包内 `SKILL.md`；下载会重新打包，ZIP 字节可能不同。CLI 仍读包内名称。批准、撤下回退和提升时，名称与摘要随对应版本。
### 使用 CLI 上传
```bash
# 配置 SkillHub 注册中心
export SKILLHUB_REGISTRY=http://localhost:8080
export SKILLHUB_REGISTRY=https://skillhub.example.com
export SKILLHUB_TOKEN=YOUR_API_TOKEN
# 发布到默认命名空间
npx @astron-team/skillhub@latest publish ./my-skill
skillhub publish ./my-skill
# 发布到指定命名空间
npx @astron-team/skillhub@latest publish ./my-skill --namespace my-team
skillhub publish ./my-skill --namespace my-team
```
> ClawHub CLI 的发布与同步协议与 SkillHub 不兼容。发布请使用上面的 SkillHub CLI。
3. **使用 Web UI 发布**
### 使用网页上传
访问 `http://localhost:3000/dashboard/publish`，选择命名空间、上传 zip 文件、选择可见性后点击「发布」。
访问实例 Web 入口的 `/dashboard/publish`，选择命名空间、上传 zip 文件、选择可见性后点击「发布」。
可选上传自定义技能头像：选择 PNG/JPEG、裁剪并等待私有上传成功，再提交技能。头像上传中或失败时不能提交；没有选择头像则正常提交并使用技能名首字母。更新技能时默认保留原头像，可选择替换或移除；移除仅在提交成功后生效，取消或提交失败不影响原头像。
@ -160,11 +112,11 @@ npx @astron-team/skillhub@latest publish ./my-skill --namespace my-team
机器判定头像违规时，新图保持私有。若开启人工审核，申请继续等待审核员决定，并非机器自动驳回；审核员可拒绝，认为误判时须填写理由才能批准。人工拒绝后，可在“我的技能”和更新页查看提交图片及拒绝原因。机器调用异常与违规不同，异常时须先重试，不能直接批准放行。
头像上传、审核状态及讯飞／阿里云接入步骤详见 [技能头像与图片审核接入](/guide/skill-avatars)。
头像上传、审核状态及讯飞／阿里云接入步骤详见 [技能头像与图片审核接入](./skill-avatars.html)。
4. **使用 REST API 发布**
### 使用发布接口
```bash
```http
POST /api/v1/skills/{namespace}/publish
Content-Type: multipart/form-data
@ -174,19 +126,7 @@ visibility: PUBLIC
![公开与私有技能的普通发布路径](/diagrams/skill-publish-lifecycle-sketch.png)
图示覆盖普通上传；扫描失败、审核拒绝及特权发布的区别见下文。
5. **安全扫描**
发布后，[Skill Scanner](/guide/scanner) 会自动扫描技能包，检测潜在的安全风险。扫描结果会显示在技能包详情页。
6. **等待审核**（以返回状态为准）
团队管理员会收到审核通知，审核通过后技能包正式发布。
7. **发布成功**
技能包可以通过搜索发现，其他人可以通过 CLI 或 Web UI 下载使用。
图示仅覆盖普通上传。
## 提交成功不等于发布成功
@ -194,9 +134,46 @@ visibility: PUBLIC
`SCAN_FAILED` 表示扫描执行失败，不代表已经判定包有害；扫描完成也可能有风险发现。上传成功、HTTP 成功或 CLI 正常退出，都不能单独证明版本已 `PUBLISHED`。更新审核期间，公众继续看到已发布版本，有权维护者可以预览待审版本。
### 创作草稿的边界
### 创作草稿：创建、编辑与结构校验
创作 API 支持私有草稿、文件编辑和结构校验，目前不包含网页创作工作台或自动发布。校验通过不代表执行过技能，也不代表安全检查通过。创作草稿与上传后等待审核的技能版本是不同对象。
本地目录走 ZIP／CLI 上传；逐文件接口编辑使用创作草稿。无网页工作台、草稿导出或直接提审／发布端点；草稿不是 `UPLOADED` 或待审版本。
创建要求命名空间可写，且账号为成员；超级管理员（`SUPER_ADMIN`）仅免成员检查，不免冻结／归档限制。已有草稿的读写及校验仅检查所有者或超级管理员，不重检成员资格与命名空间状态。使用浏览器会话，写请求携带实例 CSRF 令牌。API Token 白名单未开放创作端点，不能使用 CLI Token。无独立启用开关，旧实例先在 `/v3/api-docs` 查接口。
HTTP 请求用同源 API 客户端发送，不能贴进 Shell；子路径加实例前缀。`team`、`example-skill`、`{draftId}`、`{runId}` 是占位值，分别替换为有权访问的命名空间、名称和响应 ID。
| 操作 | 请求 | 完成标志 | 说明 |
| --- | --- | --- | --- |
| 创建草稿 | `POST /api/v1/authoring/drafts` | 响应 `data.id`、`data.revision` 存在 | `namespaceSlug`、`name` 必填，`requirement` 可选；创建 `SKILL.md` 骨架 |
| 核对当前内容 | `GET /api/v1/authoring/drafts/{draftId}`；`GET /api/v1/authoring/drafts/{draftId}/files` | 可读修订号与文件清单 | 文件正文通过 `GET /api/v1/authoring/drafts/{draftId}/files/content?path=SKILL.md` 读取 |
| 保存文件 | `PUT /api/v1/authoring/drafts/{draftId}/files` | 读取响应 `data.draft.revision` | `expectedRevision` 是写前并发前置；内容改变推进修订，未改变可保持原号，旧校验不能证明新内容 |
| 启动校验 | `POST /api/v1/authoring/drafts/{draftId}/runs` | 返回运行的 `data.id` 和 `data.draftRevision` | 运行固定修订快照，不提审 |
| 跟踪结果 | `GET /api/v1/authoring/runs/{runId}`；`GET /api/v1/authoring/runs/{runId}/findings`；重新 `GET /api/v1/authoring/drafts/{draftId}` | 运行 `status=SUCCEEDED`、`errorCount=0`，且草稿 `validated=true` | 比较运行 `draftRevision` 与草稿 `revision`；旧结果不证明新内容 |
创建请求体：
```json
{"namespaceSlug":"team","name":"example-skill","requirement":"整理会议材料并生成待办清单"}
```
保存请求中，`expectedRevision` 替换为刚读取的修订号，`content` 替换为完整正文；二进制文件可用 `encoding=base64`，不要复用示例修订号。
```json
{"path":"SKILL.md","content":"---\nname: example-skill\ndescription: 整理会议材料\n---\n\n# 使用说明\n按输入材料提取待办。","encoding":"text","contentType":"text/markdown","expectedRevision":1}
```
校验覆盖路径、重复项、数量／大小、frontmatter、内容／扩展名和合规声明结构；不执行技能／模型／Agent，不替代扫描或人工审核，不证明合规。发布须整理本地文件后上传，预留提交字段不是入口。
| 现象 | 最可能原因 | 定位手段 | 处置 |
| --- | --- | --- | --- |
| 接口不存在 | 实例版本未提供该接口 | 在实例 `/v3/api-docs` 查找创作路径 | 改用本地目录与 ZIP 上传，不要猜测提交端点 |
| 未登录或写请求被拒绝 | 会话、CSRF 或凭据类型不符 | 核对登录后的身份请求及请求携带的 CSRF 信息 | 重新完成实例登录，不要公开复制 Cookie 或令牌 |
| 创建被拒绝 | 非成员或命名空间不可写 | 查成员资格、命名空间状态 | 恢复合法条件，不要用超管绕过冻结／归档 |
| 已有草稿被拒绝 | 非所有者且非超级管理员 | 比较当前账号与草稿归属 | 联系所有者，不要借用凭据 |
| 保存发生修订冲突 | 其他编辑已推进修订 | 重新读取草稿 `revision` 和文件正文 | 比较并合并后再保存，不要省略修订校验强行覆盖 |
| 校验有错误或结果已过期 | 文件结构问题或校验后又修改 | 查看 findings 及运行、草稿的修订号 | 修复并重新校验，不要把旧运行的成功当作当前版本已发布 |
接口以 [创作控制器](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/authoring/SkillAuthoringController.java)、[草稿权限与修订规则](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/SkillDraftService.java)、[结构校验器](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/DraftStructureValidator.java)及 [Token 路由策略](https://github.com/iflytek/skillhub/blob/main/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/policy/RouteSecurityPolicyRegistry.java)为准。
## 合规声明
@ -219,7 +196,7 @@ x-astron-compliance:
---
```
需要注意：
声明边界：
- 这是“作者声明”，不是 SkillHub 或第三方机构的合规认证。
- SkillHub 会校验字段结构、重复项、包内证据路径和外部 URL 格式。
@ -234,22 +211,22 @@ x-astron-compliance:
| `standard` | 是 | 标准或框架标识，例如 `mitre-attack`、`nist-csf`、`soc2` |
| `version` | 是 | 标准版本 |
| `controlId` | 是 | 控制项、技术编号或条款 ID |
| `title` | 否 | 控制项名称，建议填写，便于审核和搜索 |
| `title` | 否 | 控制项名称，用于审核和搜索 |
| `evidence` | 否 | 证据列表，支持包内文件和外部 URL |
## API 接口
## 发布与版本查询契约
**发布技能包**：
```bash
```http
POST /api/v1/skills/{namespace}/publish
Content-Type: multipart/form-data
# 参数
file: MultipartFile (必需)
visibility: PUBLIC | PRIVATE | NAMESPACE_ONLY (可选，默认 PUBLIC)
visibility: PUBLIC | PRIVATE | NAMESPACE_ONLY (必需)
```
**参数说明**：
参数说明：
| 参数 | 类型 | 说明 |
|------|------|------|
| namespace | string | 命名空间 slug（路径参数） |
@ -257,42 +234,36 @@ visibility: PUBLIC | PRIVATE | NAMESPACE_ONLY (可选，默认 PUBLIC)
| visibility | enum | 可见性级别：PUBLIC（公开）、PRIVATE（私有）、NAMESPACE_ONLY（空间成员可见） |
**获取 Skill 详情**：
```bash
```http
GET /api/v1/skills/{namespace}/{slug}
```
**列出版本**：
```bash
```http
GET /api/v1/skills/{namespace}/{slug}/versions?page=0&size=20
```
**获取版本详情**：
```bash
```http
GET /api/v1/skills/{namespace}/{slug}/versions/{version}
```
**下载特定版本**：
```bash
```http
GET /api/v1/skills/{namespace}/{slug}/versions/{version}/download
```
**按标签下载**：
```bash
```http
GET /api/v1/skills/{namespace}/{slug}/tags/{tagName}/download
```
**版本解析**：
```bash
```http
GET /api/v1/skills/{namespace}/{slug}/resolve?version=1.2.0
```
## 注意事项
## 包与标识限制
> **版本号规范**：建议显式使用 `major.minor.patch`，例如 `1.2.3`；省略版本时服务器生成时间版本。
- **首次发布**：版本号建议从 `0.1.0` 或 `1.0.0` 开始
- **标签管理**：`latest` 由发布状态及发布指针决定，不是客户端自动选择最高 SemVer
- **审核流程**：普通 PUBLIC / NAMESPACE_ONLY 上传需要扫描与审核；PRIVATE 上传后还需确认发布
- **文件大小限制**：单个技能包不超过 100MB（可配置）
- **命名规范**：Skill slug 支持小写字母、数字、连字符和 Unicode 字符
- **版本不可变**：已发布的版本不能修改，只能发布新版本
- 单个技能包不超过 100MB（可配置）；不要把大小限制与文件数量限制混同。
- 技能 slug 支持小写字母、数字、连字符和 Unicode 字符；发布前核对最终坐标。

23
docs/skillhub/quickstart.md
View file

@ -71,9 +71,9 @@ Claude Code 用户改用 `--agent claude-code`。希望多个项目共用时，
> 请使用 example-skill，按它的说明处理以下材料：……
实际调用名称以技能 `SKILL.md` 中的 `name` 和 Agent 显示结果为准。安装不会自动执行技能，也不会代为配置成员所需的工具或凭据。
如果 Agent 没发现技能，检查 CLI 输出路径、当前项目、安装范围和目标 Agent，参见 [FAQ](./faq.md)。
如果 Agent 没发现技能，检查 CLI 输出路径、当前项目、安装范围和目标 Agent，参见 [FAQ](./faq.html)。
整套安装使用 `skillhub suite install`，之后从套装的入口技能开始；详见 [技能套装使用指南](./guide/skill-suites.md)。
整套安装使用 `skillhub suite install`，之后从套装的入口技能开始；详见 [技能套装使用指南](./guide/skill-suites.html)。
## 4. 更新和管理
@ -82,17 +82,20 @@ skillhub upgrade @team/example-skill --check
skillhub upgrade @team/example-skill
```
检查计划后再更新。保留需要的本地修改；不要把 `--force` 当作默认参数。卸载、同步团队工作区和完整命令说明见 [CLI 指南](./guide/cli.md)。
检查计划后再更新。保留需要的本地修改；不要把 `--force` 当作默认参数。卸载、同步团队工作区和完整命令说明见 [CLI 指南](./guide/cli.html)。
## 常见问题与处理
| 现象 | 先检查什么 | 下一步 |
| --- | --- | --- |
| 搜索不到目标技能 | 当前注册中心、拼写、登录身份和资源可见性 | 在网页确认坐标和版本是否已发布，见[搜索与安装](./guide/skill-discovery.md) |
| 安装时报同名目录冲突 | 输出的目标目录是否来自另一来源或包含自己的文件 | 先保留所需内容，不直接使用 `--force` 覆盖未知目录，见[CLI 参考](./guide/cli.md) |
| 安装成功但 Agent 看不到 | Agent 类型、项目根目录、user/project 范围 | 对照安装输出路径，按 Agent 的发现方式重载或重开会话 |
| Agent 已加载但执行失败 | 技能说明所需的工具、输入和凭据 | 按 `SKILL.md` 配置运行环境；注册中心不会代为执行这些步骤 |
| 现象 | 定位动作 | 正常结果或原因 | 检查与处理 |
| --- | --- | --- | --- |
| 搜索不到目标技能 | 同一终端执行 `skillhub search pdf` 与 `skillhub whoami`；在同一注册中心网页查实际坐标 | 搜索返回有权查看的已发布资源；公开搜索可匿名，身份接口未登录不代表公开搜索故障 | 校对实例、坐标和发布状态；受限资源先完成登录，不要通过重置账号或删除本地目录排障 |
| 安装时报同名目录冲突 | 执行 `skillhub list --agent codex --json`，将 `items[].installDir` 与冲突提示路径比较；打开该目录的 `SKILL.md` | 已记录安装应显示匹配的注册中心、版本与目录；无记录的已有目录也可能是手工文件 | 先备份并辨明目录来源，再选择正确项目或安装范围；不要用 `--force` 覆盖未知内容 |
| 安装成功但 Agent 看不到 | 在目标项目根目录执行 `skillhub list --agent codex --json`，检查 `items[].agent`、`installDir`、`status`，再打开实际目录的 `SKILL.md` | `status=ok` 仅表示目录存在；`missing` 表示记录对应目录不存在；Agent 还须发现该目录 | 核对项目与 Agent 类型，按 Agent 的发现方式重载或新建会话；不要仅凭 `ok` 认定技能已被加载 |
| Agent 已加载但执行失败 | 打开已安装目录的 `SKILL.md`，逐项核对所需工具、输入和凭据，并读取 Agent 返回的具体错误 | 文件安装正常仍可能缺运行依赖或权限；注册中心不代为配置外部工具 | 按技能说明在目标环境补齐依赖；不要把凭据写进共享技能包或公开错误报告 |
以上命令在安装技能的项目目录执行，`--agent codex` 必须与实际 Agent 一致，Claude Code 使用 `--agent claude-code`。`pdf` 是可替换的搜索词；排障命令不保证存在同名技能。CLI 字段与过滤规则见 [list 实现](https://github.com/iflytek/skillhub/blob/main/cli/src/commands/list.ts)及 [CLI 参数定义](https://github.com/iflytek/skillhub/blob/main/cli/src/index.ts)。
## 下一步
需要配套技能时，阅读[技能套装](./guide/skill-suites.md)；需要更多命令时，查阅 [CLI 指南](./guide/cli.md)。发布技能、管理团队、自托管和源码开发，请从[文档导航](./guide/index.md)选择对应任务。
需要配套技能时，阅读[技能套装](./guide/skill-suites.html)；需要更多命令时，查阅 [CLI 指南](./guide/cli.html)。发布技能、管理团队、自托管和源码开发，请从[文档导航](./guide/index.html)选择对应任务。

18
openspec/changes/repair-online-documentation/tasks.md
View file

@ -1,13 +1,13 @@
## 1. 第一批：事实与可执行性
- [ ] P0-1 核对 Kustomize / Helm 独立路径，统一入口/正文/FAQ，中英同步。
- [ ] P0-2 四类状态对象按真实字段和枚举解释，消除审核动作与版本状态混用。
- [ ] P0-3 命名空间创建步骤写明平台角色前置。
- [ ] P0-4 Scanner 默认值与部署覆盖值同格列出。
- [ ] P0-5 禁用扫描的上传/发布后果明确且符合代码。
- [ ] P0-6 Scanner 诊断有命令、预期值和失败处理，不回显凭据。
- [ ] P0-7 命名空间治理的状态/身份/动作矩阵和前置条件准确。
- [ ] P0-8 创作草稿 API、校验/提交/发布对象关系与 ZIP 路径明确。
- [ ] P0-9 快速开始失败表提供就地动作与完成判断，不用纯跳转替代。
- [x] P0-1 核对 Kustomize / Helm 独立路径，统一入口/正文/FAQ，中英同步。
- [x] P0-2 四类状态对象按真实字段和枚举解释，消除审核动作与版本状态混用。
- [x] P0-3 命名空间创建步骤写明平台角色前置。
- [x] P0-4 Scanner 默认值与部署覆盖值同格列出。
- [x] P0-5 禁用扫描的上传/发布后果明确且符合代码。
- [x] P0-6 Scanner 诊断有命令、预期值和失败处理，不回显凭据。
- [x] P0-7 命名空间治理的状态/身份/动作矩阵和前置条件准确。
- [x] P0-8 创作草稿 API、校验/提交/发布对象关系与 ZIP 路径明确。
- [x] P0-9 快速开始失败表提供就地动作与完成判断，不用纯跳转替代。
## 2. 本批验收
- [ ] 源码对照、双语和术语检查。