diff --git a/docs/skillhub/.vitepress/config.ts b/docs/skillhub/.vitepress/config.ts index 169c1fae4..d22f2e79a 100644 --- a/docs/skillhub/.vitepress/config.ts +++ b/docs/skillhub/.vitepress/config.ts @@ -62,6 +62,7 @@ export default defineConfig({ { text: '管理命名空间', link: '/guide/namespace' }, { text: '审核技能与套装', link: '/guide/review' }, { text: '安全扫描与报告', link: '/guide/scanner' }, + { text: '技能头像与审核', link: '/guide/skill-avatars' }, ], }, { @@ -71,7 +72,7 @@ export default defineConfig({ { text: 'Docker 部署', link: '/guide/deployment' }, { text: 'Kubernetes 部署', link: '/guide/kubernetes' }, { text: '前端动作统计', link: '/guide/frontend-analytics' }, - { text: '技能头像与审核', link: '/guide/skill-avatars' }, + { text: '配置头像机器审核服务', link: '/guide/avatar-moderation-configuration' }, ], }, { @@ -137,6 +138,7 @@ export default defineConfig({ { text: 'Manage namespaces', link: '/en/guide/namespace' }, { text: 'Review submissions', link: '/en/guide/review' }, { text: 'Configure scanning', link: '/en/guide/scanner' }, + { text: 'Skill avatars and moderation', link: '/en/guide/skill-avatars' }, ], }, { @@ -146,7 +148,7 @@ export default defineConfig({ { text: 'Deploy with Docker', link: '/en/guide/deployment' }, { text: 'Deploy on Kubernetes', link: '/en/guide/kubernetes' }, { text: 'Frontend analytics', link: '/en/guide/frontend-analytics' }, - { text: 'Skill avatars and moderation', link: '/en/guide/skill-avatars' }, + { text: 'Configure avatar machine moderation', link: '/en/guide/avatar-moderation-configuration' }, ], }, { diff --git a/docs/skillhub/.vitepress/theme/index.ts b/docs/skillhub/.vitepress/theme/index.ts new file mode 100644 index 000000000..ea7a407d2 --- /dev/null +++ b/docs/skillhub/.vitepress/theme/index.ts @@ -0,0 +1,4 @@ +import DefaultTheme from 'vitepress/theme' +import './style.css' + +export default DefaultTheme diff --git a/docs/skillhub/.vitepress/theme/style.css b/docs/skillhub/.vitepress/theme/style.css new file mode 100644 index 000000000..46fd6b835 --- /dev/null +++ b/docs/skillhub/.vitepress/theme/style.css @@ -0,0 +1,3 @@ +.vp-doc img[src*='/diagrams/'] { + margin-inline: auto; +} diff --git a/docs/skillhub/en/faq.md b/docs/skillhub/en/faq.md index 3fac63f4c..af392db41 100644 --- a/docs/skillhub/en/faq.md +++ b/docs/skillhub/en/faq.md @@ -272,7 +272,9 @@ Check the following in order: ## Q: How does an account created through OAuth (GitHub / GitLab, etc.) get admin rights? -A: The first OAuth login creates a regular user. An existing `SUPER_ADMIN` (for example the bootstrap admin created during initialization) has to promote it from the admin console. +A: External sign-in first follows the existing admission policy. A newly created external account with status `ACTIVE` can receive a configured platform role when the provider supplies a verified email and an enabled initial-role rule matches it. Without a matching rule, no platform-management role is granted automatically. Rules apply only during new-account creation; they do not update existing accounts or merge accounts with the same email. Existing accounts use user management with the required platform permissions; only a super administrator (`SUPER_ADMIN`) may grant that role. + +For account and credential concepts, see [Accounts and access tokens](./guide/account-access.html). The applicable rule conditions are defined by the [initial-role service](https://github.com/iflytek/skillhub/blob/main/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/settings/InitialExternalRoleGrantService.java), and the [account creation flow](https://github.com/iflytek/skillhub/blob/main/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/identity/IdentityBindingService.java). A `USER_ADMIN` can manage user status and assign platform roles other than `SUPER_ADMIN`, but cannot grant `SUPER_ADMIN` to any account or change the role of an existing `SUPER_ADMIN`. Only a `SUPER_ADMIN` can perform those two operations. diff --git a/docs/skillhub/en/guide/avatar-moderation-configuration.md b/docs/skillhub/en/guide/avatar-moderation-configuration.md new file mode 100644 index 000000000..d4e3cb8a7 --- /dev/null +++ b/docs/skillhub/en/guide/avatar-moderation-configuration.md @@ -0,0 +1,111 @@ +# Configure avatar machine moderation + +This page is for deployment operators. It covers service activation, credential injection, service updates, and actual-call verification for avatar moderation. A running registry and an image containing this feature are prerequisites. It does not deploy a separate moderation engine or explain owner uploads. Submission, policy, and review entry points are covered by [Skill avatars and moderation](./skill-avatars.html). + +## Prerequisites and responsibilities + +| Operation | Responsible actor | Prerequisite and completion criterion | +| --- | --- | --- | +| Inject credentials and update containers | Operator with deployment permission | A running registry and access to its deployment/private configuration; update the original project service | +| Enable moderation policy | Super administrator (`SUPER_ADMIN`) | Save switches after configuration is present; saving does not prove actual cloud calls | +| Create an acceptance candidate | Skill owner | Submit a new avatar to a non-private test skill; old applications do not prove the new setup | +| Check review and public outcomes | Authorized skill reviewer | Compare the candidate and machine result in the existing skill application; prohibited content must not be approved for testing | + +## Select a provider and confirm permissions + + +Select one startup provider: `xfyun` or `aliyun`. Runtime switches cannot change providers. Credentials are unnecessary while machine moderation is disabled. Real calls can incur provider charges; account availability and quotas must be checked by the deployment operator. + +| Provider | Service | Credentials | +| --- | --- | --- | +| Xfyun | Image moderation | APPID, APIKey and APISecret | +| Aliyun | Enhanced content security, Shanghai `profilePhotoCheck` | RAM AccessKey ID and AccessKey Secret | + +For Xfyun, APIKey maps to `access-key-id` and APISecret to `access-key-secret`; see the [provider API (Chinese)](https://www.xfyun.cn/doc/nlp/ImageModeration/API.html). For Aliyun, consult [service onboarding (Chinese)](https://help.aliyun.com/zh/document_detail/467828.html) and grant the required `yundun-greenweb:DescribeUploadToken` and `yundun-greenweb:ImageModeration` permissions rather than full access to the deployment’s OSS buckets. + +Aliyun uses temporary upload credentials and synchronous moderation; no dedicated user-managed moderation bucket is required. This is independent of SkillHub's package/avatar storage. The adapter maps `none/low` risk to pass and `medium/high` to block; unknown, empty or failed responses do not pass. Human handling of a blocked result follows the avatar moderation policy; it is not a final human decision by the provider. + +## Inject private configuration and recreate the service + +First configure the normal release stack. Create a private directory outside the repository and replace `/etc/skillhub/private` with its actual path. The following filesystem permissions are this page's example, not application defaults. Credential files must not be committed to Git. + +| Object | Example permissions | Effect and boundary | +| --- | --- | --- | +| Private directory | `700` | Set by the deployment operator; only its owner may access it | +| Credential and override files | `600` | Set by the deployment operator; only their owner may read or write them | + +Standard Compose only passes declared settings; adding arbitrary values to `.env.release` does not inject them into the server. + +Create `avatar-moderation.env` with **one** provider configuration. Replace placeholders and keep `SPRING_APPLICATION_JSON` as valid single-line JSON: + +```dotenv +SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"xfyun","xfyun":{"app-id":"YOUR_APPID","access-key-id":"YOUR_APIKEY","access-key-secret":"YOUR_APISECRET"}}}}} +``` + +Or: + +```dotenv +SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"aliyun","aliyun":{"access-key-id":"YOUR_ACCESS_KEY_ID","access-key-secret":"YOUR_ACCESS_KEY_SECRET"}}}}} +``` + +If the deployment already uses `SPRING_APPLICATION_JSON`, merge this subtree into it; do not replace other configuration or define duplicate variables. An override's `environment` takes precedence over `env_file`. Escape credential characters correctly for JSON. + +Create `compose.avatar.yml` in the same private directory: + +```yaml +services: + server: + env_file: + - /etc/skillhub/private/avatar-moderation.env +``` + +From the repository root, retain the deployment’s existing project name, Compose files and other options, then append the override: + +```bash +make validate-release-config +docker compose --env-file .env.release \ + -f compose.release.yml \ + -f /etc/skillhub/private/compose.avatar.yml \ + up -d --no-deps server + +docker compose --env-file .env.release \ + -f compose.release.yml \ + -f /etc/skillhub/private/compose.avatar.yml \ + ps server +``` + +This updates an existing full stack. For initial deployment, use `up -d` instead of `up -d --no-deps server`. A restart does not reload changed container environments; recreate the service and preserve the override in future updates. Other platforms should inject the same `skillhub.avatar.moderation` properties through their secret mechanism. + +::: warning Xfyun outbound logging +The Xfyun interface carries `accessKeySecret` in URL parameters. The adapter avoids logging complete URLs and raw exceptions. Also disable HTTP debug logging and prevent proxies, tracing and external log collectors from capturing that request URL. Never share rendered secret-bearing Compose configuration or container environments. +::: + +## Enable moderation and verify actual results + +1. After server health checks pass, open System Configuration as a super administrator. +2. Enable machine moderation; retaining manual review initially makes decisions observable. +3. As a skill owner, submit a **new** avatar for a non-PRIVATE test skill. +4. Inspect the machine result on the update page. If manual review is enabled, review its image and result in the skill review queue. +5. Verify pass, block and error handling: the old public image remains until approval, blocked/error candidates stay private, and manual rejection has a visible reason. Do not approve prohibited content merely for testing. + +Saving credentials or enabling a switch checks configuration completeness, not real account permissions, connectivity, quota or responses. Existing candidates are not automatically rescanned after enabling a switch. Code and simulated tests do not replace acceptance with the deployment account; verify connectivity, result mapping and failure handling after setup or credential rotation. + +## Change providers and handle existing applications + +Each application retains snapshots of its machine/manual switches and provider. Later configuration does not rewrite applications or rerun completed results. Before switching, authorized reviewers should handle pending applications. Update private configuration and recreate `server`, then submit a new candidate as its skill owner to use the new provider. + +An old candidate still requiring its original provider returns `ERROR` after a provider switch; it does not silently use the new provider. Changing only an administration switch does not recover that task. Candidate retention is defined in [Skill avatars and moderation](./skill-avatars.html); provider-side temporary uploads follow external service rules and are a separate lifecycle. + +## Completion criteria and troubleshooting + +Enabling machine moderation only confirms that the selected provider's required configuration is present. Verify integration through actual results and candidate visibility on a new application. Health, supplied credentials, and saved switches do not replace actual-call acceptance. + +| Symptom | Likely cause | Diagnostic action | Resolution | +| --- | --- | --- | --- | +| Provider unavailable when enabling | Invalid `provider` or missing injected credentials | Compare private property names and whether the startup command used the same override | Correct configuration and recreate the original service; do not print full environments or Secrets | +| Behavior unchanged after configuration edits | Container was only restarted or another value overrides the setting | Compare Compose file order and `environment`/`env_file` definitions | Merge the JSON and recreate the service; do not overwrite unrelated Spring settings | +| A new application's machine state is `ERROR` | Service activation, permissions, quota, or outbound network failure | Inspect its machine state and provider account settings; Aliyun also requires its temporary OSS upload endpoint | Restore dependencies before retrying under cooldown rules; do not interpret errors as passes | +| Old candidates fail after switching | The saved provider differs from the active deployment | Compare the candidate provider with the current `provider` | Handle the old application or resubmit; do not directly edit candidate snapshots | +| Existing applications have no new result after enabling | Switch changes do not rescan old applications | Check candidate time and machine state on the update page | Verify through a new application; do not repeatedly approve old applications to trigger calls | + +Configuration sources: [Provider gateway](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/AvatarModerationGateway.java), [Xfyun adapter](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/XfyunAvatarModerationProvider.java), and [Aliyun adapter](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/AliyunAvatarModerationProvider.java). Commands use [release Compose](https://github.com/iflytek/skillhub/blob/main/compose.release.yml). Other deployment paths must inject equivalent properties through their Secret mechanism rather than copying Compose update commands. diff --git a/docs/skillhub/en/guide/cli.md b/docs/skillhub/en/guide/cli.md index ca70630b1..b783bc10e 100644 --- a/docs/skillhub/en/guide/cli.md +++ b/docs/skillhub/en/guide/cli.md @@ -481,13 +481,10 @@ skillhub remove pdf-parser --json skillhub doctor --json ``` -Success response format: +The following JSON excerpt shows only the success flag, not a complete command response. Result fields depend on the command: ```json -{ - "ok": true, - ... -} +{"ok": true} ``` Error response format: @@ -719,17 +716,13 @@ skillhub search test --registry https://skillhub.example.com ### Installation Directory Conflict -```bash -# Reinstall only when the existing directory has matching SkillHub source metadata -skillhub install pdf-parser --force +Check the active registry, target Agent, installation directory, source metadata, and local changes before replacing files. The following example targets Codex; use the actual Agent identifier for other targets. -# Or remove first then install -skillhub remove pdf-parser -skillhub install pdf-parser +```bash +skillhub list --agent codex --json ``` -`--force` never overwrites an unmanaged directory or a Skill installed from another registry, -namespace, or slug. Move or explicitly remove that directory first. +Compare `installDir` with the conflicting path and read that directory's `SKILL.md`. Use `--force` only after confirming the same installation source, making a backup, and explicitly accepting the loss of local changes. The option does not take over unmanaged, different-source, or disabled targets. If provenance is uncertain, choose another directory or scope; do not delete files or inventory records as a diagnostic step. ### Corrupted Inventory diff --git a/docs/skillhub/en/guide/index.md b/docs/skillhub/en/guide/index.md index f2bf5a7d9..70d2e099b 100644 --- a/docs/skillhub/en/guide/index.md +++ b/docs/skillhub/en/guide/index.md @@ -1,17 +1,17 @@ # Documentation map -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. +Select the required task. [Quick Start](../quickstart.html) covers the first installation; deployment and development guides are not prerequisites. ## Start - [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. +- [Quick start](../quickstart.html): find, install, and use a skill in the target Agent. - [FAQ](../faq.html): troubleshoot login, installation, and configuration. ## Use skills -| Your task | Read | +| Task | Read | | --- | --- | | 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) | @@ -30,15 +30,16 @@ Prepare `SKILL.md` and its supporting files, then submit. An accepted submission - [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. +- [Skill avatars and moderation](./skill-avatars.html): skill-owner submissions, authorized review, and moderation policy managed by super administrators. ## Deploy and operate -Read these guides when you need to run your own registry. Choose a deployment method before configuring optional integrations. +These guides apply to self-hosted registry operation. Select a deployment method before configuring optional integrations. - [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. +- [Configure avatar machine moderation](./avatar-moderation-configuration.html): provider selection, private credentials, service updates, and actual-call acceptance for deployment operators. ## Develop and integrate diff --git a/docs/skillhub/en/guide/namespace.md b/docs/skillhub/en/guide/namespace.md index 739e3f8c3..449e27d50 100644 --- a/docs/skillhub/en/guide/namespace.md +++ b/docs/skillhub/en/guide/namespace.md @@ -1,248 +1,111 @@ # Manage Namespaces -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. +This page covers team namespace creation, membership maintenance and lifecycle governance for authorized operators. Skill ownership, platform roles and namespace roles are managed separately. Creating or managing a namespace does not grant a platform role. Lifecycle actions on this page do not apply to `GLOBAL` or other non-team types. -Creation permission source: [NamespacePortalCommandAppService](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/NamespacePortalCommandAppService.java). +## Prerequisites and Responsibilities -## A Team Onboarding Sequence +A namespace supplies the ownership segment of a Skill coordinate, such as `@team/example-skill`. This is an example coordinate, not a guaranteed available resource. The namespace slug is immutable after creation; authorized operators can change its display 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. -5. Arrange maintenance responsibilities before removing a member. Removal does not transfer skill ownership. +| Operation | Required identity | Entry and decision basis | +| --- | --- | --- | +| Create a team namespace | Platform Skill administrator (`SKILL_ADMIN`) or super administrator (`SUPER_ADMIN`) | Creation entry at `/dashboard/namespaces`; ordinary members cannot create one | +| Maintain members and settings | Namespace Owner or Admin | Namespace is `ACTIVE` and the detail page exposes the action | +| Publish Skills | Member or another authorized publisher | Select the namespace in the publishing form; scanning, review and Skill maintenance permissions still apply | +| View members | Existing namespace member | Members tab; read access does not include membership mutation | -### Why Available Actions Differ +Sources: [creation service](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/NamespacePortalCommandAppService.java) and [namespace policy](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/namespace/NamespaceAccessPolicy.java). -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. +## Create a Namespace and Establish Collaboration -| 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 | +1. An authorized creator opens the creation entry and supplies a display name, stable slug and purpose. The creator becomes the namespace Owner; this action does not add a platform role. +2. Open Members in the namespace detail page and add an existing account or create an invitation. Select `MEMBER` or `ADMIN` when adding members. Use the separate ownership transfer entry for the namespace Owner; the ordinary role selector does not assign `OWNER`. +3. Members select this namespace when publishing. Select namespace-member visibility (`NAMESPACE_ONLY`) for member sharing. Private (`PRIVATE`) content is not available to all members; public (`PUBLIC`) content does not require namespace membership for reading. +4. An authorized reviewer handles the submission from the namespace review entry. The author follows My Review Progress. Membership does not prove publication or review completion. -| 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 | +![Responsibilities from namespace creation and member acceptance to publishing and review](/diagrams/namespace-membership-flow-en.svg) -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. +Figure: Creation, membership acceptance and publishing are separate actions. An invitation grants membership, not publication. -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. +The following creation and membership requests use placeholder names, slugs and user identifiers. Programmatic callers must also satisfy the instance authentication and CSRF requirements. - -## Overview - -Namespaces are the core organizational unit in SkillHub. Each namespace represents a team or project with its own members, permissions, and skill packages. - -![Concept Diagram](/diagrams/namespace-concept.png) - -**Purpose of Namespaces**: - -- **Isolation**: Skill packages from different teams don't interfere with each other -- **Permissions**: Role-based access control (RBAC) -- **Collaboration**: Team members can jointly manage skill packages -- **Governance**: Administrators can review, archive, and freeze skill packages - -**Role System**: - -| Role | Permissions | -|------|-------------| -| **Owner** | Own the team namespace; manage members and transfer ownership subject to namespace state and server-side permissions | -| **Admin** | Manage members, review skill packages, modify settings | -| **Member** | Publish skills and view namespace-only content | - -**Namespace States**: - -- **Active**: Normal operation -- **Frozen**: Cannot publish new skill packages -- **Archived**: Hidden from search results - -## Use Cases - -**Case 1: Create a Team Namespace** - -A team lead creates a new namespace to manage the team's skill packages. - -![Screenshot](/screenshots/namespace-create.png) - -**Case 2: Add Team Members** - -An administrator invites new members to join the namespace and assigns appropriate roles. - -![Screenshot](/screenshots/namespace-members.png) - -**Case 3: Permission Management** - -Adjust member roles to control who can publish, review, and manage skill packages. - -**Case 4: Namespace Freeze** - -Discover a security issue in the namespace and temporarily freeze all publish operations. - -## Step-by-Step Guide - -**Create a Namespace**: - -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") - - Slug: URL identifier (e.g., "iflytek") - - Description: Brief description of the team's responsibilities and skill package scope - -![Flow Diagram](/diagrams/namespace-create-flow.png) - -4. Submit to create; the registry sets the creator as namespace Owner. This does not grant a platform role. - -**Add Members**: - -1. Go to the namespace detail page -2. Click the "Members" tab -3. Click "Add Member" -4. Search for users (supports searching by username, email) -5. Select Admin or Member; ownership transfer is a separate flow -6. Confirm to add - -**Invite with a link**: - -1. An Owner or Admin opens the Members page of an ACTIVE team space and selects "Invite member". -2. Share the copied link securely. It expires after 24 hours and can be redeemed once by one person who is not already a member. -3. The recipient must first pass the usual SkillHub login and account access rules. The page shows the space, current account, and MEMBER permissions. Joining happens only after explicit confirmation. -4. "Revoke invitation" invalidates the link immediately. Creating a new link asks for confirmation before replacing a still usable one; existing members remain members. - -Anyone who obtains the link can use it after normal account admission. Do not post it in a public channel. The login return URL does not contain the invitation token; the current browser tab stores it temporarily until joining or terminal invalidation. - -**Manage Permissions**: - -1. Find the target user in the member list -2. Click "Change Role" -3. Select a new role and confirm -4. Permission changes are recorded in the audit log - -**Freeze a Namespace**: - -1. Go to namespace settings -2. Click "Freeze Namespace" -3. Provide a reason for freezing (optional) -4. Confirm to freeze - -> After freezing, all skill packages in the namespace cannot publish new versions, but existing versions remain downloadable. - -## Skills After Member Removal - -Removing a member does not delete, move, transfer, or unpublish their skills. The namespace, address, current owner, and version history remain unchanged. - -An active account that still owns a skill can view and download its own content, including private content, drafts, and history, from My Skills. The management interface explains that membership has ended and the skill is read-only. The owner cannot upload or republish, change the avatar or visibility, withdraw requests, archive, or delete content. This exception does not grant access to another owner's internal skills. - -Rejoining restores normal maintenance permissions if the account is active and ownership is unchanged. Disabled accounts cannot use the owner read exception. Re-enabling an account does not recreate removed namespace membership. Previously submitted review requests remain in the existing review workflow; removal does not automatically approve or withdraw them. - -Existing namespace and platform governance permissions remain unchanged. Removal does not appoint a successor. This change adds no skill transfer, self-service namespace exit, or permanent account deletion feature. - -## API Reference - -**Create a Namespace**: ```http POST /api/v1/namespaces Content-Type: application/json -{ - "displayName": "iFlytek AI Team", - "slug": "iflytek", - "description": "iFlytek's AI agent skills" -} +{"displayName":"Example Team","slug":"example-team","description":"Shared authoring"} ``` -**Parameter Reference**: -| Parameter | Type | Description | -|-----------|------|-------------| -| displayName | string | Namespace name (required, up to 128 characters) | -| slug | string | URL identifier (required, unique, 2-64 characters, lowercase letters, numbers, hyphens only) | -| description | string | Description (optional, max 512 characters) | - -**Get Namespace Details**: -```http -GET /api/v1/namespaces/{slug} -``` - -**Update a Namespace**: -```http -PUT /api/v1/namespaces/{slug} -Content-Type: application/json - -{ - "displayName": "iFlytek AI Team (Updated)", - "description": "Updated description" -} -``` - -**Add a Member**: ```http POST /api/v1/namespaces/{slug}/members Content-Type: application/json -{ - "userId": "user-123", - "role": "MEMBER" -} +{"userId":"example-user","role":"MEMBER"} ``` -**Update Member Role**: -```http -PUT /api/v1/namespaces/{slug}/members/{userId}/role -Content-Type: application/json +## Invitations, Role Changes and History -{ - "role": "ADMIN" -} -``` +Create an invitation under Members → Invite Members in an `ACTIVE` team namespace, then share it through a controlled channel. The holder must complete login and existing admission checks, verify the target, account and `MEMBER` role, and confirm acceptance. Opening the link does not create membership. Links are not restricted to a particular email or account and must not be published in public channels. -**Remove a Member**: -```http -DELETE /api/v1/namespaces/{slug}/members/{userId} -``` +| Item | Current rule | Effect and boundary | +| --- | --- | --- | +| Lifetime and use count | 24 hours from creation; one new member can use it once | Fixed rule; expiration or use prevents further joining | +| Replacement and revocation | Confirmation immediately invalidates the old link | Existing members retain membership | +| Web invitation history | Five entries per page, with pagination | Fixed web presentation; full account identifier is available on hover | +| History API pagination | 1–50 entries per page | Controlled by request parameters; no invitation code or hash is returned | +| History retention | Retained while the namespace exists | Permanent namespace deletion removes invitation business records; operation audit follows its existing retention rules | -**Freeze a Namespace**: -```http -POST /api/v1/namespaces/{slug}/freeze -Content-Type: application/json +Links use `/join#invite=invitation-code`. The creator's account in the same browser tab temporarily retains the link. After a refresh, reopening the dialog validates that the link is still active before enabling copying. Another account, tab or device cannot recover it from this temporary storage. History does not expose the original code. If the original link is lost, creating a new invitation requires confirming replacement. Login redirects do not contain the invitation Token. -{ - "reason": "Security investigation" -} -``` +History displays the creator, creation and expiration times, status, and accepted account. Account renaming or membership removal does not rewrite the original joining fact; history is not a current membership list. Only namespace Owners and Admins can read it; frozen or archived namespaces expose read-only history. Upgrades migrate only a verifiable current invitation and mark it as a legacy record; earlier history is not inferred. -**Unfreeze a Namespace**: -```http -POST /api/v1/namespaces/{slug}/unfreeze -``` +To change a role, select the member-row role edit action and save from the actions column, then re-read the role. Member removal and namespace ownership transfer require separate confirmation. Transferring a namespace does not transfer its Skills. Sources: [invitation service](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/namespace/NamespaceInvitationService.java) and [history presentation](https://github.com/iflytek/skillhub/blob/main/web/src/features/namespace/invitation-history.tsx). -## Invite Members and View History +## Lifecycle Governance -Team Owners and Admins can create a link from **Members → Invite members**. It expires after 24 hours and permits one new member to join. The recipient must sign in, meet existing admission rules, and confirm joining. Replacing an active link or revoking it requires confirmation and does not remove existing members. +The following matrices apply to `TEAM`. Server permissions and dependency checks take precedence over role names. -New links use `/join#invite=token`. The creator's account stores the link temporarily in the current browser tab. After refreshing, reopen the invitation dialog to copy it again, provided the server confirms that it is still the current valid invitation. This temporary storage cannot recover the link in another account, tab, or device, and history never returns invitation tokens. If the original link was not saved, create a new invitation and confirm replacement of the old link. +| Namespace state | Namespace role | Available actions | Restrictions | +| --- | --- | --- | --- | +| `ACTIVE` | Owner | Edit settings, manage members, transfer ownership, freeze, archive, delete | Deletion also requires no dependencies | +| `ACTIVE` | Admin | Edit settings, manage members, freeze | Cannot archive, delete or transfer ownership | +| `ACTIVE` | Member | None of these governance actions | Skill ownership does not add namespace governance permission | +| `FROZEN` | Owner | Unfreeze, archive, delete | Membership management is read-only; deletion also requires no dependencies | +| `FROZEN` | Admin | Unfreeze | Cannot archive or delete | +| `FROZEN` | Member | None of these governance actions | No writes | +| `ARCHIVED` | Owner | Restore to `ACTIVE`, delete | Deletion also requires no dependencies | +| `ARCHIVED` | Admin or Member | None of these governance actions | Previous edit permission does not grant restoration | -The dialog includes a read-only history (five records per page, up to 240px tall) showing the creator, creation and expiration times, status, and the account that successfully joined. Snapshot names are displayed first; full account IDs are available on hover, with abbreviated IDs used when names are missing. Each generated invitation has its own record. Replacement, revocation, expiration, or a member leaving does not erase history. History cannot restore expired links and does not indicate current membership. Only the space's Owner/Admin can view it; platform roles do not bypass this restriction. Frozen or archived spaces retain a history-only entry. +| Namespace state | Platform identity | Dedicated platform governance entry | Restrictions | +| --- | --- | --- | --- | +| `ACTIVE` | Super administrator | Freeze, archive | Membership is not required; no permanent deletion entry | +| `FROZEN` | Super administrator | Unfreeze, archive | Membership is not required | +| `ARCHIVED` | Super administrator | Restore to `ACTIVE` | Membership is not required | +| Any | Skill administrator or user administrator | These platform roles alone grant none of the dedicated actions above | Apply the previous table if the account also has a namespace role | -An upgrade imports only the provable current invitation, marked as a legacy record; earlier links are not reconstructed from incomplete audit data. History remains while the space exists and is deleted when the space is permanently deleted. Existing audit records follow their original retention rules. +Freezing pauses writes; it does not retrieve files already installed on clients. Existing versions remain readable under their access rules. Archiving removes the namespace from search while preserving existing Skill access. Permanent deletion is Owner-only and requires no Skills, review tasks, promotion requests targeting the namespace, or authoring drafts. Archiving does not remove these dependencies. -The history endpoint requires a browser session: `GET /api/v1/namespaces/{slug}/invitations/history?page=0&size=10`. Page sizes are bounded to 1–50; tokens and hashes are never returned. +Sources: [namespace service](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/namespace/NamespaceService.java) and [platform governance controller](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/admin/AdminNamespaceController.java). -## Notes +## Completion Criteria and Failure Handling -> **Slug Uniqueness**: Namespace slugs must be globally unique and cannot be changed after creation. Use a short identifier for your team or project. +After creation, the list must show the target slug, `ACTIVE`, and the creator's Owner role. After acceptance, the member list must include the actual account with `MEMBER`. Re-read namespace details after governance actions and verify the target state, such as `ACTIVE` after unfreezing. A used invitation record does not prove that its account is still a member. -- **Owner Requirement**: Each namespace must have at least one Owner; the last Owner cannot be removed -- **Role Inheritance**: Membership grants access to NAMESPACE_ONLY content, not every PRIVATE skill; private access is reserved for its owner and authorized administrators -- **Freeze Mechanism**: Administrators can freeze a namespace; no new skill packages can be published while frozen -- **Archive Mechanism**: Archived namespaces are hidden from search results, but existing skill packages remain accessible -- **Audit Logs**: All member changes and permission adjustments are recorded in the audit log +| Symptom | Likely cause | Diagnosis | Resolution | +| --- | --- | --- | --- | +| Creation entry is absent | Required platform role is missing | Compare platform roles with the current page identity | Contact an authorized creator; do not repeatedly register accounts | +| Invitation cannot be accepted | Expired, used, revoked or namespace is not writable | Read invitation status in the dialog and namespace status in Settings | The original operator creates a new invitation if required; do not reuse the invalid link | +| Link cannot be copied after refresh | Temporary tab storage is unavailable or the link is invalid | Reopen the dialog in the original account and tab; read validation result | Retry validation first; confirm replacement if the code cannot be recovered; do not treat history as an invitation code | +| Member actions are unavailable | Account is not Owner/Admin or namespace is frozen/archived | Check member role, state and read-only message | An authorized operator restores the namespace if appropriate; do not modify browser requests to bypass permission | +| Permanent deletion is rejected | One of the four dependency types remains | Follow the response to Skills, reviews, promotions or drafts | Handle each resource through its own workflow first; do not delete database records directly | + +## Membership Removal and Maintenance Boundaries + +Removing a member does not delete, move or transfer their Skills. Published content retains its original visibility. The current Skill owner with an active account can still view and download their own content, including private content, unpublished versions and historical versions, from My Skills; the page displays a read-only message. Upload, republishing, avatar or visibility changes, withdrawal, archiving and deletion are unavailable on the basis of that ownership alone. This exception does not expose other members' restricted content. + +Rejoining restores maintenance under the original rules if ownership is unchanged. Disabled accounts cannot act; re-enabling an account does not restore removed membership. Existing submissions continue normal review and are not automatically approved or withdrawn. Existing namespace and platform governance permissions remain unchanged. This version does not add Skill transfer, self-service departure or permanent account deletion. The [owner access policy](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/SkillOwnerAccessPolicy.java) does not replace other management permissions. + +## Further Reading + +- [Publish and Update Skills](./skill-publish.html): Submit versions for the intended visibility. +- [Review Skills and Suites](./review.html): Identify pending objects and their results. +- [Accounts and Access Tokens](./account-access.html): Separate login identities from API credentials. diff --git a/docs/skillhub/en/guide/review.md b/docs/skillhub/en/guide/review.md index 121bbdd14..1e141bb3f 100644 --- a/docs/skillhub/en/guide/review.md +++ b/docs/skillhub/en/guide/review.md @@ -1,230 +1,128 @@ # Review Skills and Suites -## Reviewer Checklist +This page covers pending-content inspection, decision submission and result verification for authorized reviewers. Authors can use the responsibility table to track submissions. A decision applies to a specific request and version; it does not replace Agent execution testing, compliance certification or global promotion approval. -1. Verify the subject, submitter and target version. A skill version, profile/avatar change and Suite version require different checks. -2. Read the submitted files and changes, not only the current public version. The previous published version may remain downloadable during review. -3. Inspect scan status and findings. Execution failure, detected risk and an unconfigured analyzer are different; an empty report is not a security conclusion. -4. Check visibility and intended audience, including every Suite member and its entry role. Member approval does not approve the Suite. -5. Before approval, ensure current data is still valid. For rejection, identify files, problems and required changes. After a failed decision request, reload status before trying again. -6. Verify the decision history and resulting published version. Review success does not test skill execution in a local Agent. +## Prerequisites and Responsibilities -### Tracking and Revising as an Author +| Operation | Identity and conditions | Entry | +| --- | --- | --- | +| Review within a team namespace | Namespace Owner or Admin | Review tab in namespace details | +| Review across namespaces | Platform Skill administrator (`SKILL_ADMIN`) or super administrator (`SUPER_ADMIN`) | `/dashboard/reviews` | +| Track an own submission | Submitter | My Review Progress; read access does not grant approval | +| Global promotion and revocation | Submitter and authorized platform reviewer | `/dashboard/promotions`, separate from ordinary version reviews | -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. +Owners and Admins of a team namespace can review their own submissions; super administrators can self-review. Other own submissions cannot be self-reviewed solely through the platform Skill administrator role. Only a super administrator can review their own global promotion request. Ordinary review decisions also require an `ACTIVE` namespace. Source: [review permission policy](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/ReviewPermissionChecker.java). +Ordinary public (`PUBLIC`) or namespace-member-visible (`NAMESPACE_ONLY`) uploads enter scanning and review. Private (`PRIVATE`) uploads are retained first and still require publication confirmation or a separate review submission. A previously published version may remain available while an update is pending. -## Identify the State Object +## Inspect Content and Submit a Decision -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`. +![Review flow: identify the request, inspect evidence, submit a decision and re-read the outcome](/diagrams/review-decision-flow-en.svg) + +Figure: A decision requires a pending request and current permission. Reading the old version does not verify the current submission. + +1. Open a pending request and verify its submitter, subject, target version, visibility and namespace. GitHub-synchronized items also provide a content revision, source repository and fixed commit. The technical version used for installation appears in technical information. +2. Inspect the submitted documentation and file tree in Skill Content. Documentation is fetched when the tab is opened; individual file content is fetched on selection. GitHub updates initially open Changes; initial imports and ordinary Skills open Skill Content. An empty preview caused by an object-storage read failure is not evidence of acceptable content. +3. Check license evidence, the scanning report and findings in Source & Security. Distinguish execution errors, risk findings and unconfigured analyzers. Ordinary version approval is unavailable while scanning is running. Unrecognized licenses or missing evidence require inspection of the specific status and supporting material; they do not confirm permission to use the content. +4. For avatar or visibility changes, verify the candidate and requested target. For a Skill Suite, inspect the pending snapshot, Entry Skill and fixed member versions. Approval is unavailable before the snapshot loads. Member approval does not approve the Suite. A Suite definition and a Suite Bundle import operation are separate objects; see [Skill Suites](./skill-suites.html). +5. Read previous decisions in Review History, then approve or reject after evidence checks. A rejection must identify the file, problem and correction conditions; approval comments are optional. Switching tabs preserves comments; switching requests clears comments and unconfirmed dialogs. This version has no conditional-approval state. + +| Inspection result | Decision basis | Next action | +| --- | --- | --- | +| Current content, target and evidence agree | The current request has been inspected and no unresolved issue remains | Approve, then re-read the task and target object | +| Files, evidence or declarations contain a specific issue | Record a traceable problem and correction conditions | Reject; the author revises the submission | +| Scan, snapshot or files are unavailable | Evidence required for a decision is missing | Diagnose or wait; do not treat missing results as acceptable evidence | + +Online preview limits are listed together below. Exceeding a limit does not mean the file was deleted; obtain it through an authorized download before inspection. + +| Item | Fixed limit | Exceeding the limit | +| --- | --- | --- | +| Line-by-line comparison | File exceeds 64KiB or 1000 lines | Line comparison is skipped | +| Current content loaded online | File exceeds 256KiB | Content is not loaded online | +| Baseline download of a removed old file | File exceeds 1MiB | The old file cannot be downloaded from the review page | + +These are frontend/API implementation limits, not review-page settings. Sources: [review detail page](https://github.com/iflytek/skillhub/blob/main/web/src/pages/dashboard/review-detail.tsx) and [review API](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/portal/ReviewController.java). `GET /api/v1/reviews/{id}/skill-detail?includeDocumentation=false` reads metadata and the documentation path without fetching object-storage content; the default is `true`. + +### Inspect Compliance Declarations + +Versions containing `x-astron-compliance` display a compliance snapshot and added, removed or modified declarations. A changed `complianceSnapshot.digest` indicates a change in normalized declarations. Match declarations to actual capability, control items, evidence paths and external material rather than standard names alone. Inaccessible evidence, mismatched content or removals affecting downstream references require a documented issue and revision. The registry stores structured declarations and version snapshots; it does not certify the author's actual compliance. See [compliance metadata](./skill-publish.html). + +## State Object Reference + +A task can be `PENDING` while its version is still `SCANNING`. Task and version states must not be substituted for each other. Read the following four objects separately. ### Review Task States -| 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 | +| State | Meaning | Responsible party and next action | +| --- | --- | --- | +| `PENDING` | Awaiting a decision | Authorized reviewer reads the current request before acting | +| `APPROVED` | Approved | Submitter verifies the version or metadata effect | +| `REJECTED` | Rejected with comments retained | Submitter revises and resubmits | +| `SUPERSEDED` | Replaced by a later request | Submitter and reviewer read the current request | -[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). +The [task enum](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/ReviewTaskStatus.java) has no `WITHDRAWN`. Withdrawing an ordinary Skill version removes the pending task and changes its version state. It does not remove a previously published version or revoke an approved global promotion; see the [withdrawal service](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/ReviewService.java). ### Skill Version States -These values belong to a version; `DRAFT` is not the authoring API draft object. +| State | Meaning | Responsible party and next action | +| --- | --- | --- | +| `DRAFT` | Version draft, not an authoring API draft object | Skill owner completes preparation | +| `SCANNING` | Scan is running | Scanning service completes before continuation | +| `SCAN_FAILED` | Scan execution failed | Operator and owner diagnose before retrying | +| `UPLOADED` | Uploaded but not published | Owner confirms publication or submits for review | +| `PENDING_REVIEW` | Awaiting a human decision | Authorized reviewer inspects this version | +| `PUBLISHED` | Published | Users access under visibility rules; execution needs separate verification | +| `REJECTED` | Not approved | Owner revises and resubmits | +| `YANKED` | Withdrawn from distribution | Users select an installable alternative | -| 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 | +Source: [version enum](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/SkillVersionStatus.java). -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). +### Suite Bundle Import Operation States -### Suite Bundle Operation States +| State | Meaning | Responsible party and next action | +| --- | --- | --- | +| `RUNNING` | Executing | Importer tracks the original operation without duplicate confirmation | +| `WAITING_FOR_MEMBERS` | Waiting for members | Import service and member reviewers handle members | +| `BLOCKED_RETRYABLE` | Retryable block | Importer diagnoses and retries the original operation | +| `REPREVIEW_REQUIRED` | Previous preview cannot continue | Importer previews again and checks differences | +| `SUITE_DRAFT_CREATED` | Suite draft created, not approved | Suite owner continues publication | +| `CANCELLED` | Cancelled; not a full rollback | Importer checks completed member actions | -| 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 | - -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). +Source: [import states](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/suite/bundle/SkillSuiteBundleOperationStatus.java). Recovery instructions are in [Suite Bundle Import](./suite-bundle.html). ### Avatar Review Results -An avatar candidate has three state dimensions and reuses the skill review request; it is not another single review-task enum. +Avatars reuse Skill review requests, but their state dimensions remain separate. A machine block is not a human rejection. -| Field and values | Meaning | Responsible party | Next action | +| Field | Values and meanings | Responsible party and next action | +| --- | --- | --- | +| Candidate `status` | `PENDING` pending, `ACTIVE` in use, `REJECTED` rejected, `SUPERSEDED` replaced, `REMOVED` removed | Owner and reviewer compare the candidate with the active avatar; the response field is `candidateStatus` | +| `machineStatus` | `SKIPPED` skipped, `PENDING` pending, `PROCESSING` running, `PASSED` allowed, `BLOCKED` blocked, `ERROR` execution error | Machine service processes it; deployment operator diagnoses `ERROR` | +| `reviewStatus` | `NOT_REQUIRED` no human review, `PENDING` pending, `APPROVED` approved, `REJECTED` rejected, `APPEAL_PENDING` appeal pending | Authorized reviewer and owner act on current comments | + +Source: [avatar candidate model](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/SkillAvatarCandidate.java). Configuration and retry rules are in [Skill Avatars](./skill-avatars.html). + +## Completion Criteria and Failure Handling + +After ordinary version approval, the task is `APPROVED` and the target version is `PUBLISHED`; verify access with the intended identity. Metadata requests require checking the actual metadata effect, not only the version number. A rejected ordinary version is `REJECTED` with correction comments; the author revises and resubmits from the current-version entry. Approval does not prove Agent execution success or eliminate security risk. + +| Symptom | Likely cause | Diagnosis | Resolution | | --- | --- | --- | --- | -| 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 | +| Request is listed but cannot be approved | Self-review, namespace state or identity condition is not met | Compare submitter, roles and namespace state | Assign an eligible reviewer; do not alter requests to bypass restrictions | +| Approval button is disabled | Scan/avatar is pending or Suite snapshot failed to load | Read scan, candidate and snapshot errors | Complete dependencies or retry reads; do not treat absent results as acceptable evidence | +| File or documentation is empty | Object read failed or preview limit was exceeded | Check file size and preview error; download with permission | Obtain readable material before deciding; do not approve an empty preview | +| Decision reports a state conflict | Task was already processed or superseded | Refresh history and compare task ID and current state | Follow the new state; do not repeatedly approve or reject | -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). +## Global Revocation and Governance Boundaries -## Review Entry Points +If deletion of a promoted Skill is blocked, request revocation from Promote to Global on its source Skill. A platform Skill administrator or super administrator handles it under Revocation Pending Review at `/dashboard/promotions`; own submissions follow the self-review restrictions above. After the revocation record is `APPROVED`, verify that the active relation is removed before deleting the source Skill with the required permission. Hiding, archiving or withdrawing ordinary review does not substitute for revocation. -Role and self-review limits appear at the end of this page. Reports and promotion requests are handled separately. +When no revocation request is pending, an authorized platform operator can revoke directly from details with a retained record. An existing pending request must be handled in the queue. Approved revocation deletes the entire global Skill, its versions, reviews and statistics, while retaining the source Skill. Client files cannot be retrieved, and the old address can be reused. If deletion remains blocked after approval, check for another promotion and record object IDs, request ID, deployed version and failed response. Do not modify database relations directly. Source: [revocation service](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/PromotionRevocationService.java). -![Review subjects and responsibilities](/diagrams/review-concept.png) +Reports are handled at `/dashboard/reports` under existing governance permissions and the specific report evidence. Investigating a report does not automatically approve or reject a version. Withdrawal applies only to a pending review; historical comments and current request mutability must be evaluated separately. -![Review task list](/screenshots/review-list.png) +## Further Reading -## Step-by-Step Guide - -**Reviewing Skill Packages**: - -1. Navigate to `/dashboard/reviews` -2. View the pending review list -3. Click on a skill package to view details: - - Review metadata (name, description, version) - - Browse the file list - - View file contents online - - Download the full package for local testing - - Review the compliance snapshot and the diff from the previous published version - -![Scan and review in the ordinary publication path](/diagrams/skill-publish-lifecycle-sketch.png) - -The review section follows the PUBLIC / NAMESPACE_ONLY branch: scanning completes before the version waits for a review decision. - -4. Make a decision: - - **Approve**: The skill package is officially published and the developer is notified - - **Reject**: Provide a rejection reason; the developer can revise and resubmit - -5. Add review comments (optional) - -**Reviewing Compliance Declarations**: - -If the pending version contains `x-astron-compliance`, the review detail page shows the version-level compliance snapshot and a diff summary: - -- Added declarations: standards, controls, or evidence newly added by the pending version. -- Removed declarations: declarations that existed in the previous published version and are no longer present. -- Modified declarations: standard metadata, control title, or evidence changed. -- Digest changes: `complianceSnapshot.digest` changed, which means the normalized declaration content changed. - -Review guidance: - -1. Check whether each declaration matches the actual skill behavior. For example, a security response skill that declares a MITRE ATT&CK technique should provide supporting documentation or packaged evidence. -2. Expand diff items to inspect evidence paths, external links, and digests instead of relying only on the declaration title. -3. Treat removals and broad rewrites as higher-priority review items because downstream audit systems may reference those snapshots. -4. Reject the submission if evidence is missing, paths are inaccessible, or declarations clearly do not match the skill capability. - -SkillHub guarantees structural validation, traceable evidence references, and immutable version snapshots. It does not certify that the author's declaration is objectively compliant. - -### 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. - -1. Open the source skill, such as `@it/translate-document`. In "Promote to Global", choose "Request global revocation", enter a reason, and confirm. -2. Ask a platform `SKILL_ADMIN` or `SUPER_ADMIN` to open "Revocations to review" at `/dashboard/promotions`, verify the source and global skill, and choose "Approve revocation". A `SKILL_ADMIN` cannot review their own request; a `SUPER_ADMIN` can. -3. Refresh the source skill and check that the current request shows "Revoked" (`APPROVED`) in "Revocation history". `PENDING` or `REJECTED` means that this request has not completed revocation; ordinary deletion remains blocked while an active global link exists. A historical request's status is not a substitute for checking the current promotion relationship. -4. Approval deletes the linked `@global/translate-document` and all its global versions while keeping the source team skill. To remove the source too, use its permanent-delete action afterward with the required deletion permissions. - -A platform `SKILL_ADMIN` or `SUPER_ADMIN` can also choose "Revoke directly as admin" on the source detail page when no revocation request is pending. Confirmation completes global revocation immediately and retains the revocation record. When a request is already pending, the detail page only shows its pending status; handle it through "Revocations to review" as described above. Check the confirmation carefully: this removes the entire global skill, including independently uploaded global versions, ratings, and statistics. Installed client files cannot be recalled, and another skill may later use the same address. - -If the revocation record is already `APPROVED` but the same error persists after refreshing, record the source/global skill IDs, revocation request ID, deployed version or image tag, and the deletion response and request ID. Also check whether a new global promotion was approved after revocation. If the revocation controls are missing, first verify that the deployment and database migrations match the intended version and ask a maintainer to investigate. Do not edit promotion relationships directly in the database to bypass the workflow. - -**Handling Reports**: - -1. Navigate to `/dashboard/reports` -2. View the report list -3. Investigate the reported content -4. Take action (archive the skill package, warn the user, etc.) - -## API Reference - -**Submit for Review**: -```http -POST /api/v1/reviews -Content-Type: application/json - -{ - "skillVersionId": 123 -} -``` - -**Approve a Review**: -```http -POST /api/v1/reviews/{id}/approve -Content-Type: application/json - -{ - "comment": "Looks good! Approved." -} -``` - -**Reject a Review**: -```http -POST /api/v1/reviews/{id}/reject -Content-Type: application/json - -{ - "comment": "Please fix the documentation and add more examples." -} -``` - -**Parameter Reference**: -| Parameter | Type | Description | -|------|------|------| -| id | number | Review task ID (path parameter) | -| comment | string | Review comment (optional for approval; provide a clear reason for rejection) | - -**List Pending Reviews**: -```http -GET /api/v1/reviews/pending?namespaceId=123&page=0&size=20 -``` - -**List My Submissions**: -```http -GET /api/v1/reviews/my-submissions?page=0&size=20 -``` - -**Get Review Details**: -```http -GET /api/v1/reviews/{id} -``` - -**Get Skill Package Details Under Review**: -```http -GET /api/v1/reviews/{id}/skill-detail -``` - -**Download Review Package**: -```http -GET /api/v1/reviews/{id}/download -``` - -**Withdraw a Review**: -```http -POST /api/v1/reviews/{id}/withdraw -``` - -**Report a Skill Package**: -```http -POST /api/v1/skills/{namespace}/{slug}/reports -Content-Type: application/json - -{ - "reason": "INAPPROPRIATE_CONTENT", - "details": "This skill contains malicious code" -} -``` - -## Notes - -> **Review Permissions**: Team namespace Admins and Owners review their space; SKILL_ADMIN and SUPER_ADMIN have platform review roles. Personal spaces and self-review have additional rules; a generic administrator label is not sufficient. - -- **Review Turnaround**: It is recommended to complete reviews within 24 hours to avoid blocking developers -- **Review Records**: All review actions are recorded in the audit log -- **Compliance Audit**: Compliance declarations are recorded as version snapshots. Approval or rejection should consider the diff summary, but Agent execution traces are not recorded by SkillHub -- **Review Comments**: When rejecting, it is recommended to provide detailed improvement suggestions -- **Withdrawal Restrictions**: Only skill packages in the pending review state can be withdrawn +- [Publish and Update Skills](./skill-publish.html): Preparation, submission and version management. +- [Security Scanning](./scanner.html): Interpret reports and diagnose execution failures. +- [Manage Namespaces](./namespace.html): Membership roles and namespace states. diff --git a/docs/skillhub/en/guide/scanner.md b/docs/skillhub/en/guide/scanner.md index 25fcc15e6..41cfe27d8 100644 --- a/docs/skillhub/en/guide/scanner.md +++ b/docs/skillhub/en/guide/scanner.md @@ -1,30 +1,87 @@ # Configure and Inspect Security Scans -## Reading a Report as an Author or Reviewer +This page explains how Skill authors and reviewers interpret version scan reports and how deployment operators configure and diagnose Scanner. Reports provide findings and execution evidence, not approval or a guarantee of behavior inside an Agent. Avatar moderation is a separate processing path; see [Skill Avatars and Moderation](./skill-avatars.html). -Open the submitted version in skill details or review. Verify its version before inspecting severity, affected files and explanations; a prior version's report does not cover new files. +## Prerequisites and Responsibilities -- `SCANNING`: unfinished; ordinary submissions cannot be approved on that basis. -- `SCAN_FAILED`: execution failed; investigate and retry. It does not mean the skill was found malicious. -- Completed with findings: assess findings and policy separately from execution failure; human review still applies. -- Disabled or missing report: not a zero-risk verdict. PRIVATE uploads can run without scanning, while ordinary PUBLIC / NAMESPACE_ONLY submissions require it enabled. - -### Operator Troubleshooting Order - -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 | +| Action | Operator | Prerequisite | Notes | | --- | --- | --- | --- | -| `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. | +| Read a report | A signed-in account authorized to view the report | Identify the Skill and target version | Check the version in Skill or review details; public visibility does not imply anonymous report access. | +| Revise content | Skill author | Permission to update versions | Revise the package and submit through publication; do not edit historical reports. | +| Make a review decision | An account authorized for the target namespace | Read the submitted content and scan state | Scan completion is not approval. | +| Configure and diagnose | Deployment operator | Container or cluster access | Business roles do not grant host access. | -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. +![Relationship between scan execution, report interpretation, and human review](/diagrams/scan-result-flow-en.svg) - Compose: +*Figure: A scan task produces a report. Execution failure and risk findings require different actions; human review remains an independent decision.* - ```bash +## Interpret the Target Version Report + +1. Select the target version in Skill or review details. Record the version and scan time before reading findings, so an older report is not applied to new content. +2. Check `failureReason` and `scannedAt` to distinguish pending work, execution failure, and a completed result. `SCAN_FAILED` denotes execution failure, not a finding that the content is harmful. +3. For completed reports, inspect `verdict`, `isSafe`, `maxSeverity`, and `findings`. Check each file location, explanation, and remediation rather than relying only on finding counts. +4. Authors submit a revised version after fixing issues. Reviewers approve or reject based on the submitted content and evidence. A version still in `SCANNING` cannot be approved through the ordinary submission path; see [Review Skills and Suites](./review.html). + +The following is an illustrative report excerpt, not a result from a real instance. The API returns a list of reports for a Skill and version. + +```json +{ + "verdict": "DANGEROUS", + "isSafe": false, + "maxSeverity": "HIGH", + "findingsCount": 1, + "findings": [{ + "ruleId": "EXAMPLE_RULE", + "severity": "HIGH", + "filePath": "scripts/example.py", + "lineNumber": 12, + "message": "Example finding", + "remediation": "Review the indicated operation" + }], + "failureReason": null +} +``` + +| Machine verdict | Mapping rule | Decision basis | Notes | +| --- | --- | --- | --- | +| `SAFE` | Scanner returns `is_safe=true` | Still inspect content, dependencies, and intended usage | A machine classification, not a safety guarantee. | +| `BLOCKED` | Otherwise, maximum severity is `CRITICAL` | Investigate the findings and dangerous operations | The enum name does not mean the registry automatically rejected the review. | +| `DANGEROUS` | Otherwise, maximum severity is `HIGH` | Inspect risk evidence and revisions | Not an execution failure. | +| `SUSPICIOUS` | Other non-`SAFE` results, including missing severity | Inspect concrete findings and report completeness | Lower severity alone does not establish publication eligibility. | + +Sources: [Scanner adapter](https://github.com/iflytek/skillhub/blob/main/server/skillhub-infra/src/main/java/com/iflytek/skillhub/infra/scanner/SkillScannerAdapter.java), [report API](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/portal/SecurityAuditController.java), and [scan state processing](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/security/SecurityScanService.java). + +## Configure Scanning and Confirm Effective Values + +The table lists application bindings used on this page. Variables must reach the registry container. Adding a key to `.env.release` does not apply it when Compose does not reference it. Recreate the registry after Compose changes; update overrides and roll affected Deployments for Kubernetes. The complete configuration follows [application configuration](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/resources/application.yml) and the [Scanner configuration guide (Chinese)](https://github.com/iflytek/skillhub/blob/main/scanner/docs/configuration.md). + +| Setting | Application default and deployment overrides | Effect | Notes | +| --- | --- | --- | --- | +| `SKILLHUB_SECURITY_SCANNER_ENABLED` | Application, release Compose, Kustomize, and Helm: `true`; runtime script `--no-scanner`: `false` | Disabling rejects ordinary new non-private uploads | Recreate or roll to apply. | +| `SKILLHUB_SECURITY_SCANNER_URL` | Application: `http://localhost:8000`; Compose: `http://skill-scanner:8000`; Kustomize: `http://skillhub-scanner:8000`; Helm: generated from the release | Registry-to-Scanner address | Recreate or roll to apply. | +| `SKILLHUB_SECURITY_SCANNER_MODE` | Application: `local`; Compose, Kustomize, and Helm override: `upload` | `local` requires the same directory path on both sides; `upload` transfers the package | Recreate or roll to apply. | +| `SKILLHUB_SCANNER_POLICY_PRESET` | `balanced`; alternatives: `strict`, `permissive` | Analysis policy sent to Scanner | Explicitly pass through and recreate. | +| `SKILLHUB_SCANNER_FAIL_ON_SEVERITY` | Declared as `high` | The current adapter does not pass this field into scan options | Must not be treated as an implemented automatic publication-blocking guarantee. | +| `SKILLHUB_SCANNER_USE_BEHAVIORAL` / `SKILLHUB_SCANNER_USE_META` | `true` / `false` | Behavioral and metadata analyzers | Explicitly pass through and recreate the registry. | +| `SKILLHUB_SCANNER_USE_AI_DEFENSE` / `SKILLHUB_SCANNER_USE_VIRUSTOTAL` | Both `false` | Optional external detection engines | Configure the corresponding credentials as well as switches; recreate affected services. | +| `SKILLHUB_SCANNER_USE_LLM` / `SKILLHUB_SCANNER_LLM_PROVIDER` | `false` / `anthropic`; alternatives: `openai`, `azure` | Enable external model analysis | Recreate the registry; separately set Scanner-side `SKILL_SCANNER_LLM_API_KEY`, optionally `SKILL_SCANNER_LLM_BASE_URL` and `SKILL_SCANNER_LLM_MODEL`. Recreate the corresponding service after secret changes. | + +Options follow the [assembly code](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/SkillScannerConfig.java) and [scan options](https://github.com/iflytek/skillhub/blob/main/server/skillhub-infra/src/main/java/com/iflytek/skillhub/infra/scanner/ScanOptions.java). LLM analysis can send content to the configured external service and incur charges. Deployment operators must verify data scope and service terms before enabling it; do not disclose secrets or complete environment dumps. + +With scanning disabled, ordinary new public (`PUBLIC`) and namespace-member-visible (`NAMESPACE_ONLY`) uploads return `error.security.scanner.required`. Private (`PRIVATE`) uploads remain possible but stop at `UPLOADED` and require separate publication confirmation. A published private Skill can reuse its latest version report for visibility expansion when `taskId` and `scannedAt` are present, `failureReason=null`, and `isSafe=true`; otherwise disabled scanning rejects the request. Sources: [publication prerequisites](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 publication confirmation](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillReviewSubmitService.java). + +## Diagnose Connectivity and Tasks + +Run Compose commands in the directory containing `.env.release` and `compose.release.yml`. Kustomize examples use manifest defaults; verify Helm names against the [Chart README (Chinese)](https://github.com/iflytek/skillhub/blob/main/charts/skillhub/README.md) instead of mixing paths. Probes display only fixed allowed values. Unrecognized configuration is redacted; URLs with credentials or unsupported conservative shapes are skipped. Missing variables use application defaults; additional Spring overrides must be inspected in protected instance configuration. + +| Parameter | Value | Scope | Notes | +| --- | --- | --- | --- | +| `wget -T` | 5 seconds | Stages of this health request | Does not change scan-task timeouts. | +| `wget -t` | 1 attempt | This health request | Does not trigger a scan. | + +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} @@ -53,9 +110,9 @@ These probe parameters affect only this diagnostic request, not background scan- ' ``` - Kustomize: +Kustomize: - ```bash +```bash kubectl -n skillhub exec deployment/skillhub-server -c server -- sh -c ' enabled=${SKILLHUB_SECURITY_SCANNER_ENABLED:-true} mode=${SKILLHUB_SECURITY_SCANNER_MODE:-local} @@ -84,10 +141,20 @@ These probe parameters affect only this diagnostic request, not background scan- ' ``` -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. +Expected standard output is shown below. `health_exit=0` proves only health-endpoint reachability. Custom addresses display `custom_or_unrecognized_redacted`, which does not imply an invalid address; ordinary custom HTTP(S)/IPv6 targets can still be probed. `skipped_*` means this diagnostic skipped a step, not that product configuration was accepted or rejected. - ```bash +```text +# Compose + enabled=true mode=upload scanner_host=skill-scanner:8000 + health_exit=0 +# Kustomize + enabled=true mode=upload scanner_host=skillhub-scanner:8000 + health_exit=0 +``` + +Next, correlate the version's failure reason and time with logs. Redact before sharing; do not publish complete logs. + +```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 @@ -95,119 +162,20 @@ These probe parameters affect only this diagnostic request, not background scan- 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. +## Completion Criteria and Failure Handling -| Symptom | Likely cause | Where to inspect | Check and action | +A completed report identifies the target version, scan time, and concrete findings. Completed ordinary non-private scans proceed to `PENDING_REVIEW`; private versions proceed to `UPLOADED`. Scanning an already published version does not change its publication state. None of these outcomes means human approval is complete. + +| Symptom | Likely cause | Diagnosis | 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. | +| Non-private upload returns `error.security.scanner.required` | Scanning disabled | Probe shows `enabled=false` | Restore the service and switch; do not modify database state to bypass checks. | +| Standard deployment reports `local` or `localhost` | Missing passthrough or incorrect override | Compare the table and container output | Correct configuration and recreate; do not confuse container localhost with the host. | +| Nonzero `health_exit` | Service not ready, network failure, or wrong address | 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 connectivity and track the original task; do not delete databases or persistent volumes. | +| Health reachable but version remains scanning or fails | Execution error, timeout, or exhausted recovery retries | Inspect this version's `failureReason` and the logs above | Retry only when the page provides the action and authorization permits it; do not repeatedly upload to create new versions. | +| Completed task has a non-`SAFE` report | Risk findings | Compare `findings` with indicated files | Revise content or provide review evidence; do not interpret `BLOCKED` as an automatic rejection record. | -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. +Diagnostic sources: [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), and [Server image](https://github.com/iflytek/skillhub/blob/main/server/Dockerfile). The standard image provides `sh` and `wget`. -## Overview +## Boundaries and Next Steps -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 support an authorized reviewer’s assessment of the intended use; completing a scan does not constitute human approval. - -**Key Features**: - -- **Automatic Triggering**: Security scanning is triggered automatically after a skill package is published, requiring no manual intervention -- **Multi-Engine Analysis**: Supports multiple analysis engines including behavioral analysis, LLM analysis, and metadata analysis -- **Configurable Policies**: Includes a built-in `balanced` policy preset with support for custom scanning policies -- **Severity Threshold**: Configurable severity level at which publication is automatically blocked -- **Scan Reports**: Detailed scan results are displayed on the skill package detail page - -**Analysis Engines**: - -| Engine | Description | Default Status | -|------|------|----------| -| **Metadata Analysis** | Metadata analysis, separate from upload structure validation | Disabled by default | -| **Behavioral Analysis** | Analyzes code behavior patterns to detect malicious operations | Enabled by default | -| **LLM Analysis** | Uses large language models to analyze code security | Optional | -| **AI Defense** | Cisco AI Defense integration | Optional | -| **VirusTotal** | VirusTotal virus scanning | Optional | - -## Use Cases - -**Case 1: Automatic Scanning on Publish** - -After a developer publishes a skill package, the Scanner automatically runs a scan in the background with no additional steps required. - -**Case 2: Administrator Reviews Scan Report** - -When reviewing a skill package, an administrator can view the scan report to help make review decisions. - -**Case 3: Custom Scanning Policies** - -Enterprise administrators can configure scanning policies and severity thresholds based on their security requirements. - -## Workflow - -``` -Developer publishes a skill package - | -SkillHub backend receives the upload - | -Security scan is triggered (via Redis Stream) - | -Skill Scanner performs multi-engine analysis - | -Scan results are written to the database - | -Skill package detail page displays the scan report - | -Administrator reviews with scan results in consideration -``` - -## Configuration - -### Basic Configuration - -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. - -| 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) - -Enabling the LLM analysis engine can improve the accuracy of security detection: - -| Environment Variable | Description | Default | -|----------|------|--------| -| `SKILLHUB_SCANNER_USE_LLM` | Enable LLM analysis | `false` | -| `SKILLHUB_SCANNER_LLM_PROVIDER` | LLM provider (anthropic / openai / azure) | `anthropic` | -| `SKILL_SCANNER_LLM_API_KEY` | LLM API key | - | -| `SKILL_SCANNER_LLM_BASE_URL` | Local/custom LLM service base URL | - | -| `SKILL_SCANNER_LLM_MODEL` | LLM model name | - | - -### Deployment Notes - -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. - -- **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**: 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. +Duration depends on package content, analysis engines, and external dependencies; this page promises no fixed completion time. Findings, execution failures, and human rejections are different outcomes. The [review implementation](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/ReviewService.java) does not currently replace human review solely based on maximum severity. Authors continue tracking versions under [Publish and Update](./skill-publish.html); reviewers handle applications under [Review](./review.html). Deployment troubleshooting must not rewrite version or review records. diff --git a/docs/skillhub/en/guide/skill-avatars.md b/docs/skillhub/en/guide/skill-avatars.md index d5eb45007..b3676f83d 100644 --- a/docs/skillhub/en/guide/skill-avatars.md +++ b/docs/skillhub/en/guide/skill-avatars.md @@ -1,123 +1,80 @@ -# Skill Avatars: Uploads, Review, and Provider Configuration +# Skill avatars and moderation -This guide covers skill avatars, not account profile pictures. Image moderation is separate from skill-package security scanning. +This page explains avatar submission by skill owners and application handling by authorized reviewers. Skill avatars do not include account profile pictures. Image moderation and skill-package security scanning are independent checks. Deployment operators configure services, credentials, and containers through [Configure avatar machine moderation](./avatar-moderation-configuration.html). -## Upload or replace an avatar +## Prerequisites and responsibilities -1. On the publishing page, select a PNG/JPEG; for an existing skill, open its update page from My Skills. An avatar-only change does not require a new skill version. -2. Adjust the square crop and zoom, then wait for upload success. Pending or failed uploads prevent submission. Without an avatar, the skill uses its initial letter. -3. Submit, then inspect the submitted image and review state in My Skills or the update page. Public readers continue seeing the previous approved image until approval. -4. If rejected, read the reason, change the image and resubmit. A newer candidate replaces an older pending candidate; old review results cannot overwrite the new image. +Sign in to the same registry and identify the target skill and account. Skill ownership controls image maintenance; namespace or platform roles do not automatically permit uploading on another owner's behalf. -Input must be PNG/JPEG, at most 2 MB, square and no more than 1024 pixels per side. The server validates and re-encodes it as PNG. Upload success means private storage succeeded, not that moderation passed. Temporary upload references expire after 24 hours; upload again if expired. - -Updates retain the existing image unless removal is selected. Avatar-only removal takes effect after a successful submission; removal submitted with a package waits for the associated approval. Cancelling or failing submission leaves the previous image unchanged. There is no separate avatar-management page. - -## Review behavior - -An avatar submitted with a package shares its skill review: the reviewer approves or rejects both. Avatar-only changes requiring manual review enter the same queue as avatar changes and do not create a skill version. Namespace administrators review their namespace; platform skill administrators and super administrators can review namespace and global skills. Existing self-review rules apply. Administrators may remove an avatar but cannot upload one on behalf of its owner. - -Super administrators configure machine and manual moderation in System Configuration (`/dashboard/admin/system-config`). Machine moderation defaults off and manual moderation on. The page manages switches, not provider credentials. - -| Machine | Manual | Avatar-only changes to non-PRIVATE skills | +| Operation | Responsible actor | Entry point and boundary | | --- | --- | --- | -| Off | Off | Becomes active on successful submission | -| Off | On | Waits for manual approval | -| On | Off | Becomes active after a machine pass; blocked/error candidates remain private | -| On | On | Machine moderation followed by a manual decision | +| Add, replace, or remove an avatar | Skill owner | Publishing page or My Skills → Update; avatar-only updates do not create versions | +| Review an avatar application | Account with review permission in the target namespace | Existing skill review queue; package and avatar changes submitted together receive a joint decision | +| Change machine and manual switches | Super administrator (`SUPER_ADMIN`) | `/dashboard/admin/system-config`; credentials and provider selection are not configured here | +| Integrate or switch a provider | Operator with deployment permission | Select a provider and inject private credentials through deployment configuration | -PRIVATE avatars are owner-readable and used directly without these reviews. Expanding visibility requires review for the target audience. Avatars submitted with packages must wait for the original package review regardless of avatar switches. +Team namespace Owners and Admins review their namespace; platform skill administrators (`SKILL_ADMIN`) and super administrators can review team and global skills. [Skill review rules](./review.html) govern self-review; platform roles must not be interpreted as unrestricted self-review permission. Authorized operators may remove an avatar but cannot upload one for its owner. -| Machine result | Effect | -| --- | --- | -| `PASSED` | Wait for manual review if enabled; otherwise activate the avatar-only candidate | -| `BLOCKED` | Keep the candidate private and retain the old image. Manual reviewers may reject it; overriding a false positive requires an explicit reason. Without manual moderation, the owner can request manual review | -| `ERROR` | Keep the candidate private; approval is blocked until the error is resolved and moderation retried | +## Submit and update an avatar -A machine block is neither an upload failure nor a final human rejection. Owners can inspect rejected images and reasons. Automatic retries have a one-hour cooldown and a maximum of three calls including the first. After exhaustion, wait for the cooldown and explicitly retry or resubmit. +1. Select a custom PNG/JPEG in the publishing or update form, then adjust the square crop and zoom. Submissions without an image use the skill's initial letter. +2. Confirm the crop and wait for upload completion. Pending or failed uploads prevent submission. The server validates the image and re-encodes it as PNG. A successful upload means private storage succeeded, not that moderation approved it. +3. After submission, inspect the candidate image and its machine/manual states in My Skills or the update page. Until activation, public detail and lists retain the previous avatar or initial letter; that does not indicate a lost submission. +4. After rejection, read the reason, revise the image, and resubmit. A new application supersedes the previous pending candidate; old review results cannot overwrite it. Application records remain available. + +Updates retain the existing image by default. Avatar-only removal restores the initial letter after successful submission; removal submitted with a package waits for that application's approval. Cancelling or failing submission leaves the active image unchanged. There is no separate avatar-management entry point. + +## Moderation policy and application relationship + +An avatar submitted with a package shares one skill application and receives a joint approval or rejection in the existing review detail. It does not activate early. An avatar-only change requiring a human decision enters the same queue, marked as an avatar change, without creating a skill version. + +Super administrators manage two switches in System Configuration. Machine moderation defaults off; manual moderation defaults on. Provider credentials are not configured or displayed there. The following matrix applies to avatar-only changes for non-private skills. + +| Machine | Manual | Activation condition | +| --- | --- | --- | +| Off | Off | Successful submission | +| Off | On | Manual approval | +| On | Off | Machine pass; blocked or error results do not activate | +| On | On | Machine processing followed by a manual decision | + +PRIVATE avatars are owner-readable and used directly without these checks. Expanding visibility requires moderation for the target audience. An avatar submitted with a package waits for the original skill application's approval regardless of avatar switches. + +## Machine results and human decisions + +| Machine result | Candidate and public image | Next action | +| --- | --- | --- | +| `PASSED` | Waits for manual review when enabled; otherwise activates an avatar-only candidate | Reviewers verify the candidate and target application; a pass does not prove content effectiveness | +| `BLOCKED` | Candidate remains private; the old image remains active | Manual reviewers may reject it; a false-positive override requires an explicit reason. Without manual moderation, the owner may request human review | +| `ERROR` | Candidate remains private and cannot be directly approved | Deployment operators resolve configuration, network, or service failures before retrying | + +A machine block is neither an upload failure nor a final human rejection. Owners can inspect rejected candidates and reasons. After manual approval, verify the active image rather than relying only on task text. + +## Input, retry, and retention rules + +| Item | Fixed value or range | Effect and limitation | +| --- | --- | --- | +| Uploaded image | PNG/JPEG; at most 2MiB; square, at most 1024 pixels per side | Server validation and re-encoding run on upload; out-of-range submissions are rejected | +| Temporary upload reference | 24 hours | Expiry requires another upload; this is not the submitted candidate's retention period | +| Machine-error cooldown | 1 hour | Wait after an error; repeated requests do not bypass the cooldown | +| Automatic calls | 3 total per candidate, including the first | After exhaustion, explicitly retry after cooldown or resubmit | +| Discarded candidate images | Private retention for 30 days after rejection, replacement, or removal | Cleanup removes expired images while textual records remain; deletion is not promised at the exact expiry instant | + +Applications retain snapshots of their machine/manual switches and provider. Later switch changes do not rewrite them, and completed machine results are not automatically rerun. If an old candidate still requires its original provider after a switch, processing may return `ERROR`; deployment operators and reviewers must coordinate its handling or use a new application. + +Sources: [Upload references](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillAvatarUploadService.java), [image validation](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillAvatarImageProcessor.java), [candidate states](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/SkillAvatarCandidate.java), and [avatar workflow](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillAvatarAppService.java). ## Configure a machine-moderation provider -Select one startup provider: `xfyun` or `aliyun`. Runtime switches cannot change providers. Credentials are unnecessary while machine moderation is disabled. Real calls can incur provider charges; account availability and quotas must be checked by the deployment operator. +Each deployment selects one provider and reads credentials at service startup. The administration page only controls moderation switches; saving a switch does not validate cloud permissions, connectivity, or quota. Deployment operators follow [Configure avatar machine moderation](./avatar-moderation-configuration.html) for integration, rotation, and provider changes, then verify actual calls with a new application. -| Provider | Service | Credentials | -| --- | --- | --- | -| Xfyun | Image moderation | APPID, APIKey and APISecret | -| Aliyun | Enhanced content security, Shanghai `profilePhotoCheck` | RAM AccessKey ID and AccessKey Secret | +## Completion criteria and troubleshooting -For Xfyun, APIKey maps to `access-key-id` and APISecret to `access-key-secret`; see the [provider API](https://www.xfyun.cn/doc/nlp/ImageModeration/API.html). For Aliyun, consult [service onboarding](https://help.aliyun.com/zh/document_detail/467828.html) and grant the required `yundun-greenweb:DescribeUploadToken` and `yundun-greenweb:ImageModeration` permissions rather than full access to your own OSS buckets. +Owners should see the submitted image and status on the update page. Applications requiring review should be identifiable in the existing skill queue. After approval, public detail should display the newly active image. Upload completion, machine pass, human approval, and public-image activation are separate completion criteria. -Aliyun uses temporary upload credentials and synchronous moderation; no dedicated user-managed moderation bucket is required. This is independent of SkillHub's package/avatar storage. The adapter maps `none/low` risk to pass and `medium/high` to block; unknown, empty or failed responses do not pass. Treating `medium` as requiring review is SkillHub policy. - -### Supply credentials through a private environment file - -First configure the normal release stack. Outside the repository, create a private directory such as `/etc/skillhub/private` (suggested permissions: directory `700`, files `600`). Replace the path with your own. Standard Compose only passes declared settings; adding arbitrary values to `.env.release` does not inject them into the server. - -Create `avatar-moderation.env` with **one** provider configuration. Replace placeholders and keep `SPRING_APPLICATION_JSON` as valid single-line JSON: - -```dotenv -SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"xfyun","xfyun":{"app-id":"YOUR_APPID","access-key-id":"YOUR_APIKEY","access-key-secret":"YOUR_APISECRET"}}}}} -``` - -Or: - -```dotenv -SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"aliyun","aliyun":{"access-key-id":"YOUR_ACCESS_KEY_ID","access-key-secret":"YOUR_ACCESS_KEY_SECRET"}}}}} -``` - -If you already use `SPRING_APPLICATION_JSON`, merge this subtree into it; do not replace other configuration or define duplicate variables. An override's `environment` takes precedence over `env_file`. Escape credential characters correctly for JSON. - -Create `compose.avatar.yml` in the same private directory: - -```yaml -services: - server: - env_file: - - /etc/skillhub/private/avatar-moderation.env -``` - -From the repository root, retain your deployment's existing project name, Compose files and other options, then append the override: - -```bash -make validate-release-config -docker compose --env-file .env.release \ - -f compose.release.yml \ - -f /etc/skillhub/private/compose.avatar.yml \ - up -d --no-deps server - -docker compose --env-file .env.release \ - -f compose.release.yml \ - -f /etc/skillhub/private/compose.avatar.yml \ - ps server -``` - -This updates an existing full stack. For initial deployment, use `up -d` instead of `up -d --no-deps server`. A restart does not reload changed container environments; recreate the service and preserve the override in future updates. Other platforms should inject the same `skillhub.avatar.moderation` properties through their secret mechanism. - -::: warning Xfyun outbound logging -The Xfyun interface carries `accessKeySecret` in URL parameters. The adapter avoids logging complete URLs and raw exceptions. Also disable HTTP debug logging and prevent proxies, tracing and external log collectors from capturing that request URL. Never share rendered secret-bearing Compose configuration or container environments. -::: - -### Enable and verify actual moderation - -1. After server health checks pass, open System Configuration as a super administrator. -2. Enable machine moderation; retaining manual review initially makes decisions observable. -3. As a skill owner, submit a **new** avatar for a non-PRIVATE test skill. -4. Inspect the machine result on the update page. If manual review is enabled, review its image and result in the skill review queue. -5. Verify pass, block and error handling: the old public image remains until approval, blocked/error candidates stay private, and manual rejection has a visible reason. Do not approve prohibited content merely for testing. - -Saving credentials or enabling a switch checks configuration completeness, not real account permissions, connectivity, quota or responses. Existing candidates are not automatically rescanned after enabling a switch. Code and simulated tests do not replace acceptance with your own deployment account; verify connectivity, result mapping and failure handling after setup or credential rotation. - -## Provider changes and retention - -Candidates retain snapshots of their machine/manual switches and provider. Later setting changes do not rewrite old candidates. Before switching providers, finish pending reviews; update private configuration, recreate the server, then submit new candidates. Completed results are not rerun. If an old candidate still requires its old provider after a switch, it errors rather than silently using the new provider. - -Rejected, replaced or deleted candidates are privately retained for 30 days before cleanup; textual review records remain. Provider-side temporary-upload retention is separate. - -## Troubleshooting - -| Symptom | Check | -| --- | --- | -| Provider unavailable when enabling | Provider spelling, required credentials and whether the correct override was used; do not print all environment values | -| Repeated machine errors | Server connectivity, account permissions, enabled service and quota; Aliyun also needs its temporary OSS upload endpoint. Wait for cooldown before retrying | -| Manual moderation disabled but package still needs review | The avatar switch does not change package review rules | -| Other users see the old image | Expected while the new candidate is pending; owners inspect candidates in My Skills/update, public detail shows the active avatar | +| Symptom | Likely cause | Diagnostic action | Resolution | +| --- | --- | --- | --- | +| Avatar cannot be submitted | Failed upload, invalid image, or expired reference | Read the upload error and compare input limits and reference time | Crop and upload again; do not change only the extension to bypass validation | +| Public detail retains the old image | New candidate is pending or inactive | Compare the candidate and its machine/manual states in My Skills or Update | Track the current application; do not repeatedly submit the same image instead of querying its state | +| Machine errors persist | Configuration, dependency, or provider failure | Read `ERROR` and retry time; deployment operators inspect service configuration | Retry after recovery and cooldown; do not approve an error as a pass | +| Package still awaits review with manual moderation off | Avatar switches do not control package review | Check whether the application also contains a package and inspect its state | Complete the normal skill review; do not force publication through database changes | +| A suspected false positive cannot activate | Blocked candidate needs human review or an explicit reason | Inspect `BLOCKED`, the manual switch, and review state | The owner requests review; an authorized reviewer evaluates evidence. Do not switch accounts to bypass moderation | diff --git a/docs/skillhub/en/guide/skill-discovery.md b/docs/skillhub/en/guide/skill-discovery.md index 7f59ee1d2..56b8d204a 100644 --- a/docs/skillhub/en/guide/skill-discovery.md +++ b/docs/skillhub/en/guide/skill-discovery.md @@ -4,7 +4,7 @@ Find a skill in an existing registry, inspect an available version, then install ## Before you start -Public skills can be browsed anonymously. For team or private resources, sign in to the correct instance and confirm namespace permissions. See [Quick Start](../quickstart.md) for CLI and Agent setup. Paths below are relative to your deployment, not a fixed development port. +Public (`PUBLIC`) skills can be browsed anonymously. Searching namespace-only (`NAMESPACE_ONLY`) skills requires sign-in to the correct instance and the relevant membership. Ordinary marketplace search excludes private (`PRIVATE`) skills; owners manage them in My Skills instead of repeatedly changing search terms. See the [full-text query implementation](https://github.com/iflytek/skillhub/blob/main/server/skillhub-search/src/main/java/com/iflytek/skillhub/search/postgres/PostgresFullTextQueryService.java). See [Quick Start](../quickstart.md) for CLI and Agent setup. Paths below are relative to your deployment, not a fixed development port. ## Search in the Web UI diff --git a/docs/skillhub/en/guide/social.md b/docs/skillhub/en/guide/social.md index 1ef02788d..eac5146f5 100644 --- a/docs/skillhub/en/guide/social.md +++ b/docs/skillhub/en/guide/social.md @@ -1,184 +1,89 @@ -# Stars, ratings and notifications +# Favorites, Ratings, and Notifications -## Overview +This page explains how a signed-in account saves Skills, submits feedback, and manages in-app notifications. Favorites, ratings, subscriptions, and notifications serve different purposes. None grants resource access or executes a Skill. Platform review actions and deployment-side email configuration are outside this page. -SkillHub provides a rich set of social features that allow team members to interact, share, and recommend skill packages. +## Prerequisites and Object Boundaries -![Concept Diagram](/diagrams/social-concept.png) +Confirm the current account and target Skill on the same registry. Favorites and ratings require access to the Skill. Creating or updating a written review additionally requires an active Skill with a published version. Hiding a Skill or changing permissions can make a previous entry inaccessible. -**Core Features**: +| Action | Stored information | Intended purpose | Notes | +| --- | --- | --- | --- | +| Favorite | A relationship between the account and Skill | Locate the Skill under My Favorites | Does not install the Skill or subscribe to updates. | +| Rating and written review | A score and optional text from the account | Record usage feedback | A written review is not a publication review decision. | +| Subscription | An update subscription relationship | Receive eligible version events | A favorite does not imply a subscription. | +| Notification | An event record addressed to the account | Track publication, review, promotion, or reports | Read status does not mean the associated task is complete. | -- **Star**: Bookmark your favorite skill packages for easy access later -- **Rating**: Rate skill packages (1-5 stars) to help others assess quality -- **Download Statistics**: Track download counts to highlight popular skill packages -- **Notification System**: Receive timely notifications for review and governance events, and more +Sources: [favorite and rating authorization](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillSocialAppService.java) and [written review rules](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillReviewAppService.java). -**Social Metrics**: +## Save a Skill and Submit Feedback -| Metric | Description | -|------|------| -| **Star Count** | Number of users who have bookmarked the skill package | -| **Average Rating** | Mean score across all user ratings | -| **Download Count** | Total number of downloads | -| **Updated time** | Update time shown in the current list | +1. Favorite the Skill on its detail page. Wait for the request to finish and inspect the button state, then confirm the entry at `/dashboard/stars`. Removing a favorite removes the relationship, not installed files. The search page also provides an Only Favorites filter. +2. Select a score on the detail page, wait for submission, and inspect the saved personal rating. Hovering is only a preview. Each account has one rating per Skill; subsequent submissions update it. There is currently no score-deletion endpoint. +3. Use Write Review when text is required, then submit the score and text. Public lists show visible reviews. Authors can edit or clear their text. Clearing text preserves the score, and existing text can still be cleared after the Skill loses its published version. +4. Text hidden by a platform Skill Administrator (`SKILL_ADMIN`) or Super Administrator (`SUPER_ADMIN`) remains hidden after author edits. Restoration requires the corresponding platform permission. Average scores and download counts inform selection but do not prove execution quality. -## Use Cases +The following requests show response fields. The Skill ID must be a real numeric ID from the instance; `{skillId}` cannot be sent unchanged. -**Case 1: Bookmarking Frequently Used Skill Packages** - -A developer finds a useful skill package and clicks the star button to bookmark it. - -![Screenshot](/screenshots/skill-detail-star.png) - -**Case 2: Rating and Recommending** - -After using a skill package, a developer gives it a rating and review to help other team members. - -**Case 3: Viewing Notifications** - -A developer receives a notification that their submission has been approved, or another supported governance event occurs. - -![Screenshot](/screenshots/notifications.png) - -**Case 4: Browsing Popular Skill Packages** - -View skill packages with the most stars and highest ratings to discover best practices. - -## Step-by-Step Guide - -**Starring a Skill Package**: - -1. Navigate to the skill package detail page -2. Click the "Star" button -3. The skill package will appear in your "My Stars" list -4. Click again to unstar - -**Rating a Skill Package**: - -1. Navigate to the skill package detail page -2. Click the star icons to select a rating (1-5 stars) -3. The rating takes effect immediately and impacts the skill package's average rating -4. You can update your rating at any time - -**Writing a Review**: - -1. Select "Write a review" on a published skill's detail page -2. Choose 1-5 stars and enter up to 2,000 characters -3. You can edit or clear the text; clearing it keeps the star rating and remains available if the skill is later unpublished -4. A review hidden by an administrator stays hidden after author edits and becomes public only after an administrator restores it - -**Viewing Notifications**: - -1. Click the notification icon in the top navigation bar -2. View the list of unread notifications -3. Click a notification to navigate to the relevant page -4. Mark as read or mark all as read - -The notification list and unread count refresh through ordinary HTTP requests every 10 seconds and -immediately when the window regains focus. The legacy `GET /api/v1/notifications/sse` endpoint has -been removed. Custom clients should poll `GET /api/v1/notifications` and -`GET /api/v1/notifications/unread-count` instead. - -**Viewing My Stars**: - -1. Navigate to `/dashboard/stars` -2. View all starred skill packages -3. Browse pages; use the search page for the starred-only filter -4. Quickly access frequently used skill packages - -## Confirm your identity first - -Stars, ratings and notifications belong to the signed-in account. Anonymous star/rating actions prompt for login; recheck state after switching accounts. A star does not install a skill, and removing a star does not delete local files. Rating buttons are disabled while submitting; successful requests refresh the personal rating and skill data. Hovered stars are only a preview. - -## Manage notifications and follow up - -Open `/notifications` and filter by all, publish, review, promotion or report; pages contain up to 20 items. Clicking an unread item marks it read and opens its target. Reading a notification does not approve a review: complete that action on the target page. - -You can mark all notifications read; deletion is available only for read items. At `/settings/notifications`, toggle categories for in-app delivery. This form configures `IN_APP`, not email or SMS subscriptions; categories default to enabled when no preference is stored. - -## Verify results and troubleshoot - -| Action or symptom | Observable result / next step | -| --- | --- | -| Star saved | The button changes to starred; confirm it in My Stars | -| Rating changed | Wait for completion and check your rating; hover is not submission | -| Review cleared | Text is removed but the score remains; this is separate from unstarring | -| Your review is absent publicly | Check whether it is hidden; author edits do not restore visibility | -| Unread count looks stale | Wait for polling or refocus the window, then check requests and login if it persists | -| Notification target is inaccessible | Recheck current resource state and permissions; historical notifications do not restore access | - -## API Reference - -**Star a Skill Package**: -```bash -PUT /api/v1/skills/{skillId}/star -``` - -**Unstar a Skill Package**: -```bash -DELETE /api/v1/skills/{skillId}/star -``` - -**Check Star Status**: -```bash +```http GET /api/v1/skills/{skillId}/star -``` - - -**Rate a Skill Package**: -```bash -PUT /api/v1/skills/{skillId}/rating -Content-Type: application/json - -{ - "score": 5 -} -``` - -**Parameter Reference**: -| Parameter | Type | Description | -|------|------|------| -| skillId | number | Skill package ID (path parameter) | -| score | number | Rating (1-5, required) | - -**Get My Stars**: -```bash -GET /api/v1/me/stars?page=0&size=20 -``` - -**Get My Rating**: -```bash GET /api/v1/skills/{skillId}/rating ``` -**Review APIs**: - -```bash -# Public review list -GET /api/v1/skills/{skillId}/reviews?page=0&size=20 - -# Read, create, or update the current user's review -GET /api/v1/skills/{skillId}/reviews/me -PUT /api/v1/skills/{skillId}/reviews/me - -# Clear review text while retaining the star rating -DELETE /api/v1/skills/{skillId}/reviews/me - -# SKILL_ADMIN or SUPER_ADMIN moderation -POST /api/v1/admin/skill-reviews/{reviewId}/hide -POST /api/v1/admin/skill-reviews/{reviewId}/restore +```json +{"data": {"score": 5, "rated": true}} ``` +Reading, submitting, and clearing personal text use `GET`, `PUT`, and `DELETE /api/v1/skills/{skillId}/reviews/me`; the public list uses `GET /api/v1/skills/{skillId}/reviews`. Clearing removes text only. Authorized platform roles handle hiding and restoration through the management entry. -Responses use the standard API envelope. `GET .../star` returns a boolean in `data`; `GET .../rating` returns `score` and `rated`. Mutations return an empty `data`, not a rating timestamp. IDs are numeric. +The first request returns a boolean `data`. The JSON above is only an excerpt for the rating request, not a complete response. Mutation responses have empty `data` and do not return a rating timestamp. Sources: [favorites](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/portal/SkillStarController.java) and [ratings](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/portal/SkillRatingController.java). -## Notes +## Receive and Process In-App Notifications -> **Rating Rules**: Each user can rate each skill package only once. Ratings can be updated but not deleted. +![Relationship between business events, account preferences, and in-app notifications](/diagrams/notification-delivery-flow-en.svg) -> **Review Rules**: Only published skills can be reviewed, and the public list contains visible reviews only. Refresh and retry after a concurrent-update conflict. +*Figure: Recipient rules and category preferences determine notification creation. Reading a notification does not complete the associated business action.* -- **Star Count**: A skill package's star count is displayed in search results and on the detail page -- **Average Rating**: Average ratings help compare skills; the search page has no dedicated rating sort -- **Notification Settings**: Users can disable certain notification types in their settings -- **Download Statistics**: Published-version downloads record counts; review-preview downloads do not count as public downloads +1. Open the notification entry in the header or `/notifications`. Locate the event by category and time. The title describes an event, not the current state of the target object. +2. Open an unread entry and confirm the associated object and version. The client requests read status and navigates to the target. Review decisions must still be made on the review detail page. +3. Adjust category switches at `/settings/notifications`. Saved preferences affect subsequent notification creation and do not delete existing records. Events omitted while a category was disabled are not recreated when it is enabled. +4. Confirm the business outcome before marking entries or all notifications as read. Only read notifications have a delete action. Deletion does not undo publication, review, or report resolution. + +| Category | Triggering events | Recipients | Notes | +| --- | --- | --- | --- | +| Publish (`PUBLISH`) | Skill publication, subscribed version updates, or yanked published versions | Eligible publishers and subscribers | Subscription delivery rechecks account, namespace, and resource access conditions and excludes the corresponding actor. | +| Review (`REVIEW`) | Skill or profile submission, and Skill approval or rejection | Relevant reviewers or submitters | Profile and Skill review do not share identical authorization. | +| Promotion (`PROMOTION`) | Promotion submission, approval, or rejection | Platform Skill reviewers or submitters | Notifications do not grant access to a global Skill. | +| Report (`REPORT`) | Report submission and resolution | Platform Skill reviewers or reporters | The historical target may no longer be visible. | + +These are the categories and representative events covered here. Exact triggers and recipients follow the [event listener](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/listener/NotificationEventListener.java) and [subscription eligibility](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/social/SubscriptionRecipientEligibility.java). Relevant event recipient lists are deduplicated, but the notification service does not provide a global exactly-once guarantee for every event. + +## Limits, Refresh, and Retention + +| Setting or limit | Default or range | Effective behavior | Notes | +| --- | --- | --- | --- | +| Score and text length | Score 1–5; text up to 2000 characters | Validated on submission | Out-of-range input is rejected; score-only updates require no text. | +| Notification pagination | Web page size 20; API `size` 1–100 | Applies per request | The current page count is not the total record count. | +| In-app preferences | All four categories enabled when unset; only `IN_APP` | Saved values affect later notification creation | This version provides no email, SMS, or messaging channel. | +| Web refresh | Poll every 10 seconds; refresh on window focus | Fixed frontend behavior | Does not guarantee immediate display after an event. | +| Read record retention | `skillhub.notification.cleanup.read-retention-days=30` | Recreate or roll the registry after deployment configuration changes | Measured from `createdAt`, not from the read time. | +| Unread record retention | `skillhub.notification.cleanup.unread-retention-days=90` | Recreate or roll the registry after deployment configuration changes | Measured from `createdAt`; records are not permanent. | +| Cleanup schedule | Daily at 02:00 | Registry scheduler | Code does not fix the time zone; the instance scheduler zone applies. Eligible records are removed by a later cleanup run, not at a guaranteed exact expiry time. | + +Sources: [review input](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/SkillReviewRequest.java), [notification API](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/portal/NotificationController.java), [preferences](https://github.com/iflytek/skillhub/blob/main/server/skillhub-notification/src/main/java/com/iflytek/skillhub/notification/service/NotificationPreferenceService.java), [polling](https://github.com/iflytek/skillhub/blob/main/web/src/features/notification/use-notifications.ts), and [cleanup](https://github.com/iflytek/skillhub/blob/main/server/skillhub-notification/src/main/java/com/iflytek/skillhub/notification/service/NotificationCleanupTask.java). + +## Completion Criteria and Failure Handling + +A favorite appears in the personal list. A completed rating request shows the saved personal value. Notifications show the expected category and time, and read status changes after the request completes. The target object's business state must be checked separately. + +| Symptom | Likely cause | Diagnosis | Action | +| --- | --- | --- | --- | +| Favorite or rating does not persist | Expired login, denied access, or failed request | Check the current account, detail access, and browser network status | Sign in and reload state before retrying; do not repeatedly click to generate duplicate requests. | +| Review visible only to its author or platform roles | Hidden review | Compare personal moderation state and reason with the public list | Revise according to the reason or contact the corresponding platform role; do not use editing to bypass hidden state. | +| Expected notification missing | Disabled category, ineligible recipient, or asynchronous processing | Inspect preferences, subscription, and the event's business outcome | Confirm the event is addressed to the account; do not republish or resubmit solely to create a notification. | +| Unread count has not changed | Request or polling refresh pending | Inspect list and unread-count requests; focus the window again | Wait for completion and recheck; do not interpret an old count as a business failure. | +| Target inaccessible | Deleted or hidden resource, or changed access | Check the target path, account, and current namespace membership | Apply current permissions; do not treat a historical notification as an access credential. | +| Historical notification missing | Manual deletion or retention cleanup | Compare creation time, read state, and instance retention settings | Inspect the business object for its result; do not use the notification list as a permanent audit archive. | + +## Boundaries and Next Steps + +The former `GET /api/v1/notifications/sse` endpoint was removed. Custom clients must poll `GET /api/v1/notifications` and `GET /api/v1/notifications/unread-count`. Notification processing is asynchronous; the refresh interval is not a delivery deadline. Continue with [version management](./skill-publish.html) after publication and the [review workflow](./review.html) for review tasks. Account and namespace changes follow the [account](./account-access.html) and [namespace](./namespace.html) rules. diff --git a/docs/skillhub/en/introduction.md b/docs/skillhub/en/introduction.md index 7a238ad39..5011f7c49 100644 --- a/docs/skillhub/en/introduction.md +++ b/docs/skillhub/en/introduction.md @@ -1,61 +1,58 @@ # Introduction -SkillHub is a self-hosted Agent Skill registry built for the enterprise. +SkillHub is a self-hosted registry for distributing and governing Agent skills. Authors submit packages containing `SKILL.md`; the registry stores versions and applies access control, scanning and review workflows. Consumers discover skills through the website and install files into a target Agent's skill directory through the CLI. This page explains responsibilities and object selection for consumers, authors and operators; it does not replace operational guides. -In the age of AI Agents, every team accumulates its own skill packages (Skills). But these packages are scattered everywhere: some on developers' local machines, some in Git repositories, and some buried in internal documentation. Team members struggle to discover each other's work, let alone reuse existing capabilities. +## Registry responsibilities and boundaries -SkillHub solves this problem. It provides a **private, controllable, and easy-to-use** skill package registry, allowing teams to manage Agent Skills just like using npm or PyPI. +The registry addresses fragmented sources, inconsistent versions and missing controls over access and publication. It manages distributable skill files, versions and governance records. It does not directly execute installed skills on the registry server. -![Architecture Diagram](/diagrams/architecture.png) +![Responsibilities of skill authors, the registry and the Agent environment](/diagrams/registry-responsibilities-en.svg) -## Core Value +Figure: the registry receives, governs and distributes packages. The target Agent environment loads and executes installed skills. -- **Managed distribution**: Upload packages and follow scanning, review, and publication -- **Enterprise-grade permissions**: Namespace-based RBAC with team collaboration and review workflows -- **Full lifecycle**: Version management, tag system, review workflows, and archiving mechanisms -- **Deployment choices**: Docker Compose and Kubernetes with explicit dependency and authentication configuration -- **Security scanning**: Built-in Skill Scanner for automatic security risk detection -- **Data sovereignty**: Fully self-hosted — all data stays within your firewall - -## Tech Stack - -![Frontend, backend, data and storage components](/diagrams/tech-stack-sketch.png) - -Storage can use local files or an S3-compatible provider; select it explicitly for your deployment. - -| Layer | Technology | Description | -|-------|------------|-------------| -| **Frontend** | React + Vite + TanStack Router | Modern SPA with multiple interface languages | -| **Backend** | Java 21 + Spring Boot | Enterprise-grade REST API | -| **Database** | PostgreSQL | Full-text search, Flyway auto-migration | -| **Cache** | Redis | Session management, hot data caching | -| **Storage** | Local files / S3-compatible storage | Skill package file storage, supports local and cloud | -| **Deployment** | Docker Compose / K8s | Configured self-hosting | - -## Feature Overview - -| Feature | Description | -|---------|-------------| -| [Skill Publishing & Version Management](/en/guide/skill-publish) | One-click skill package publishing with semantic versioning | -| [Skill Search & Discovery](/en/guide/skill-discovery) | Full-text search, smart filtering, permission-aware | -| [Namespace & Team Management](/en/guide/namespace) | Namespace-based RBAC permission system | -| [Review & Governance](/en/guide/review) | Skill and suite review workflows, reporting system | -| [Security Scanning](/en/guide/scanner) | Built-in Skill Scanner with multi-engine security analysis | -| [User Interaction & Social](/en/guide/social) | Starring, ratings, notification system | - -## Three different objects - -| Object | Purpose | Next step | +| Operation | Registry responsibility | Consumer or author responsibility | | --- | --- | --- | -| Skill | An individual package with `SKILL.md`, discovered and used by an Agent after installation | [Quick Start](./quickstart.md) | -| Skill Suite | A collection of pinned skill versions with one member designated as its entry skill | [Install and use suites](./guide/skill-suites.md) | -| Suite Bundle | An authoring format for importing a suite definition and member packages | [Bundle import](./guide/suite-bundle.md) | +| Submission and publication | Validate packages and advance scanning, review and publication according to configuration | Supply instructions, dependency requirements and verifiable content; resolve rejection or failure | +| Discovery and download | Provide search, details and downloadable versions according to resource state and access permissions | Check purpose, source, version and target environment; visible details do not establish installability | +| Installation and execution | The CLI downloads files and maintains local installation records | Confirm Agent discovery, configure runtime dependencies and assess execution results | +| Updates and governance | Manage versions and governance states such as hiding or archiving | Inspect local changes and upgrade plans; remote governance does not automatically recall downloaded files | -The registry distributes and governs skills; execution happens in the user's Agent environment. Installing a suite does not automatically run all its members. +A skill is not a hosted running application, and installation does not start a service. Scan results and review records do not certify execution quality or compliance: a scan reports checks under its particular task and policy. Suitability still requires verification in the actual Agent environment. -## Read by role +## Distinguish Skills, Skill Suites and Suite Bundles -- Consumers: [CLI](./guide/cli.md), [discovery](./guide/skill-discovery.md), [FAQ](./faq.md). -- Authors: [publishing](./guide/skill-publish.md), [suites](./guide/skill-suites.md), [review](./guide/review.md). -- Operators: [namespaces](./guide/namespace.md), [deployment and upgrades](./guide/deployment.md), [Kubernetes](./guide/kubernetes.md). -- Integrators: [Runtime contract](./guide/runtime-integration.md), [repository documentation index](https://github.com/iflytek/skillhub/blob/main/docs/README.md). +These objects apply to different stages and are not interchangeable. A Skill Suite pins exact versions of member Skills and designates one member as its entry. A Suite Bundle is an authoring format for importing members and a suite definition together. + +| Object | Stored or described content | Distinction from adjacent objects | +| --- | --- | --- | +| Skill | A package centered on `SKILL.md` and its versions | Independently installable; association with a suite does not require installing every member | +| Skill Suite | Member coordinates, exact versions and an entry Skill | An installation collection, not a workflow execution engine; members remain separate directories | +| Suite Bundle | `SUITE.yaml` with member directories to upload, or references to published member versions | An authoring and import input, not an Agent executable; member review is not bypassed | + +For example, processing meeting materials may require separate intake and summary Skills. Installing the summary Skill is sufficient for the independent summary task. Joint distribution can use a Skill Suite that pins both member versions and designates intake as the entry. A Suite Bundle is appropriate when the author must upload local members together. This example illustrates the relationship; it does not promise that resources with these names exist. Installing the suite does not execute the two steps automatically: cooperation depends on the entry and member instructions and the Agent. + +The object definitions are grounded in the [Skill Suite member model](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/suite/SkillSuiteVersionMember.java) and [Suite Bundle definition](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/suite/bundle/SkillSuiteBundleManifest.java). + +## Select an object and entry point + +| Goal | Selection | Decision basis and next action | +| --- | --- | --- | +| Install one skill for an independent task | Skill | No member combination needs pinning; follow the [quickstart](./quickstart.html) to verify installation and Agent discovery | +| Distribute several skills as a fixed-version collection | Skill Suite | A stable member combination and entry are required; check member installability in [Skill Suites](./guide/skill-suites.html) | +| Upload several local skills and assemble a suite | Suite Bundle | Import a definition, preview differences and create member versions; follow [Bundle import](./guide/suite-bundle.html) | +| Manage visibility, membership and review | Namespace and governance workflows | Platform roles do not imply namespace roles; start with the prerequisites in [namespace management](./guide/namespace.html) | + +Installing and using skills does not require deploying a registry or preparing a Suite Bundle first. Publication follows the applicable preparation, submission, scanning, review and publication-confirmation path. Upload completion does not mean that the whole workflow has finished; the entry point is [publishing and version management](./guide/skill-publish.html). + +## Deployment forms and technical components + +An accessible existing instance can be used through its website and the CLI. Self-hosting requires operating services, the database, session storage and skill-file storage, with the required authentication and scanning capabilities configured. External identity providers, scanners and other external services depend on instance configuration; self-hosting does not imply that all external requests are disabled. + +| Component | Technology or implementation | Purpose and configuration boundary | +| --- | --- | --- | +| Website and backend | React, Vite; Java, Spring Boot | The website provides controls; the backend enforces API and business rules | +| Database and session storage | PostgreSQL, Redis | Store business records and support server sessions; operational planning must also include skill files | +| Skill-file storage | Local files or S3-compatible storage | The backend selects a provider through deployment configuration; selecting a provider does not migrate existing data | +| Deployment paths | Deployment script, release Compose, Kustomize, Helm | Each has its own configuration entry point; upgrade commands and persistence configuration must not be mixed | + +These components are grounded in [release Compose](https://github.com/iflytek/skillhub/blob/main/compose.release.yml) and the [backend modules](https://github.com/iflytek/skillhub/blob/main/server/pom.xml). For self-hosting, select a path through the [documentation navigator](./guide/index.html). Integrators must distinguish registry APIs from the actual Agent execution environment; see [Runtime integration](./guide/runtime-integration.html) for the contract boundary. diff --git a/docs/skillhub/en/quickstart.md b/docs/skillhub/en/quickstart.md index 42f464cff..3096f646d 100644 --- a/docs/skillhub/en/quickstart.md +++ b/docs/skillhub/en/quickstart.md @@ -1,14 +1,23 @@ -# Quick Start: Install and Use a Skill +# Quickstart: install and use a skill -Install your first skill and use it in your Agent. This guide uses an existing registry; no SkillHub server deployment is needed. +This page starts from an existing accessible registry and covers installation, Agent discovery and a first-use check for one skill. It does not cover registry deployment or skill publication. The endpoint is an Agent reading the skill and completing a concrete task, rather than only a successful CLI installation message. -## Before you begin +![Sequence for selecting a registry, installing files, checking discovery and assessing execution](/diagrams/first-install-flow-en.svg) -- An Agent that supports skill directories, such as Codex or Claude Code. -- Node.js 18 or later and npm; check with `node --version`. -- A project directory and a reachable SkillHub registry. +Figure: each stage has its own completion criterion. A later failure should be diagnosed at that stage instead of reinstalling everything. -Run the commands in a terminal. `@team/example-skill` is a placeholder, not a guaranteed public package. Replace it with an actual search result. Before a project-scoped installation, enter the project root that your Agent will open. +## Prerequisites + +Run commands in a terminal and first change to the project root that the target Agent will open. Prepare an accessible registry and an Agent supporting skill directories, such as Codex or Claude Code. + +| Item | Requirement or value | Check and activation | +| --- | --- | --- | +| Node.js | 18 or newer, with npm available | Run `node --version` and `npm --version`; reopen the terminal after changing the runtime environment | +| Registry | Built-in address: `https://skill.xfyun.cn` | Priority: command argument, `SKILLHUB_REGISTRY`, local configuration, built-in address; environment changes apply to the current terminal | +| Installation scope | `project` or `user` | This page selects project scope explicitly; user scope is under the home directory and does not imply automatic discovery by every Agent | +| Target Agent | This page uses `codex` | Use `claude-code` for Claude Code; the selection must match the Agent opening the project | + +`skillhub.example.com` and `@team/example-skill` are placeholders, not guaranteed resources. Replace them with the actual instance address and a coordinate returned by search. Runtime requirements and options are defined by the [CLI manifest](https://github.com/iflytek/skillhub/blob/main/cli/package.json) and [command definitions](https://github.com/iflytek/skillhub/blob/main/cli/src/index.ts). ## 1. Install the CLI and select a registry @@ -17,85 +26,111 @@ npm install -g @astron-team/skillhub skillhub version ``` -The default registry is `https://skill.xfyun.cn`. For a self-hosted instance, set its actual URL in your terminal: +The version command should display `SkillHub CLI` followed by the installed version. If the command is unavailable, check that the npm global executable directory is on the current terminal's `PATH` before attempting skill installation. + +The default instance needs no address setting. For self-hosting, set the actual address in the current terminal and retain the same source for subsequent commands: ```bash export SKILLHUB_REGISTRY=https://skillhub.example.com ``` -For PowerShell, set the registry with: +The PowerShell equivalent is: ```powershell $env:SKILLHUB_REGISTRY="https://skillhub.example.com" ``` -For a single command, append `--registry https://skillhub.example.com`. Use the same registry for search, login, and installation. Identically named skills from different registries are different installation sources. +A single command can instead specify `--registry https://skillhub.example.com`. Identically named skills on different instances have different sources. Changing the source does not relocate installed files. -Public skills support anonymous search and installation. Publishing and restricted resources require authentication: +## 2. Search and verify identity + +```bash +skillhub search pdf +``` + +Each output line contains namespace/slug, latest version and summary. An empty result displays `No skills found.`. Inspect the purpose, version, visibility and dependencies on the same instance's detail page, then copy the actual coordinate. + +Public skills support anonymous search and installation. Restricted resources require login and remain subject to resource permissions: ```bash skillhub login skillhub whoami ``` -If no token is resolved from command arguments, environment variables, or saved registry credentials, follow the device-authorization instructions in the browser. When a token is found, login validates that identity rather than automatically asking you to choose another account. Use `skillhub login --no-open` on a remote terminal. Available sign-up and login methods depend on the instance configuration. +When no Token is available from command arguments, environment variables or the registry's saved credentials, login starts device authorization and prints an authorization address and device code. Browser login must be followed by device-code confirmation; an existing browser session is not a CLI credential. An existing Token is verified first, without automatically selecting another account. Remote terminals can use `skillhub login --no-open`. Available login methods and registration depend on instance configuration. `whoami` should identify the selected registry and account; see [accounts and access tokens](./guide/account-access.html). -## 2. Find and install a skill +## 3. Install and inspect files and records -```bash -skillhub search pdf -``` - -Review the skill's purpose, version, visibility, and instructions on its detail page. Replace the placeholder `@team/example-skill` below with a real search result. - -From the target project root: +Run from the target project root after replacing the placeholder coordinate: ```bash skillhub install @team/example-skill --scope project --agent codex -skillhub list --agent codex +skillhub list --agent codex --json ``` -For Claude Code, use `--agent claude-code`. Use `--scope user` to share an installation across projects. -Codex project installations use `.codex/skills//`; Claude Code uses `.claude/skills//`. User installations use the corresponding directory under your home directory. +The following is an output-format example, not a real download result. The installation path should match the current project. The directory must contain `SKILL.md`; other files depend on the package: -### Verify the destination +```text +Installed team/example-skill -> /work/project/.codex/skills/example-skill (codex) -Read the destination printed by installation, then inspect `skillhub list --agent codex`: the coordinate, version, Agent, directory, and status should match your choice. `list` filters by the active registry; switching registries does not delete local files. +/work/project/.codex/skills/example-skill/ +└── SKILL.md +``` -`missing` means the recorded directory does not exist. `ok` only means the directory exists, not that the Agent loaded or successfully executed the skill. Check `SKILL.md` in the actual destination before continuing. +The JSON returned by `list` should contain a matching record. This is a complete structure example; paths, time and version must be checked against actual output: -## 3. Use it in your Agent +```json +{"ok":true,"items":[{"namespace":"team","slug":"example-skill","version":"1.0.0","agent":"codex","installDir":"/work/project/.codex/skills/example-skill","installedAt":"2026-11-03T08:00:00.000Z","status":"ok"}]} +``` -Open the project in your Agent and start a new session or reload skills if required. Confirm that the Agent discovers the skill, then make a concrete request: +Check the coordinate, Agent and `installDir`, then open that directory's `SKILL.md`. Status `ok` only establishes that the directory exists, not that its content executed; `missing` means that the recorded directory is absent. The list filters by the current registry, not only the current project, so the path must also be checked. Claude Code uses `.claude/skills//` for project scope. With `--scope user`, installation is under the home directory and discovery follows the Agent's rules. -> Use example-skill and follow its instructions to process the following material: … +Output definitions are in the [install command](https://github.com/iflytek/skillhub/blob/main/cli/src/commands/install.ts) and [list command](https://github.com/iflytek/skillhub/blob/main/cli/src/commands/list.ts). -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.html). +## 4. Verify Agent discovery and execute a task -For a collection, use `skillhub suite install`, then start with its entry skill. See [Skill Suites](./guide/skill-suites.html). +Open that project in the target Agent, then reload skills or create a session according to that product's loading mechanism. Check that the target name appears in the Agent's available skills, then provide a concrete task, input and expected artifact as required by the skill. The invocation name depends on the actual `name` in `SKILL.md` and the Agent's discovery result. -## 4. Update and manage installations +| Stage | Observable completion criterion | What remains unproven | +| --- | --- | --- | +| File installation | `SKILL.md` exists at the installation path and the matching record has `status=ok` | Whether the Agent loaded the files | +| Agent discovery | The Agent's skill list or session context contains the target skill | Whether external tools, credentials and business dependencies work | +| Task execution | The Agent produces a verifiable result according to the instructions | Whether other inputs, environments or later versions are equally suitable | + +Installation does not execute skills or configure external tools. For cooperation between skills, inspect the entry and member instructions. Shared installation uses `skillhub suite install`; see [Skill Suites](./guide/skill-suites.html). + +## 5. Verify rejection of invalid arguments + +The following command uses an invalid scope to demonstrate rejection by local argument validation: + +```bash +skillhub install @team/example-skill --scope invalid --agent codex +``` + +The expected standard-error output is shown below, with exit code 5. The command stops before reading installation configuration or downloading files, so it does not install the example skill: + +```text +Error: --scope must be "user" or "project" +``` + +Restore `--scope project` and substitute a real coordinate before installation. Do not use `--force` to address an argument error. The message and execution order are defined by [installation argument validation](https://github.com/iflytek/skillhub/blob/main/cli/src/commands/install.ts). + +## Diagnose and resolve failures + +| Symptom | Most likely cause | Diagnostic action | Resolution | +| --- | --- | --- | --- | +| Search does not return the target | Source, permissions or publication state differ | Check `skillhub search pdf` and `skillhub whoami` in the same terminal; inspect the coordinate on the same instance | Correct the source and publication state, and log in when required; do not reset the account to troubleshoot | +| Installation reports an existing directory | An existing installation or manual files occupy the path | Compare the reported path with `installDir` in `skillhub list --agent codex --json`, then read its `SKILL.md` | Back up and identify its source, then select the correct project or scope; do not overwrite unknown content | +| The Agent does not discover the installed skill | The project, scope or target Agent differs | Check `agent`, `installDir` and `status` in the list and the project opened by the Agent | Correct the target and reload through the Agent's mechanism; do not interpret `ok` as successful loading | +| The skill is discovered but execution fails | Missing dependencies, input or permissions | Read local `SKILL.md` and compare tool and credential requirements with the Agent's error | Supply dependencies in the target environment; do not place credentials in shared packages or public logs | + +## Updates and subsequent tasks + +After these checks, inspect an upgrade plan before choosing to apply it: ```bash skillhub upgrade @team/example-skill --check skillhub upgrade @team/example-skill ``` -Review the plan before updating and preserve local changes you need. Do not use `--force` by default. See the [CLI guide](./guide/cli.html) for removal, team workspace synchronization, and command details. - -## Troubleshoot the first installation - - -| 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.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). +Local changes, shared directories or source protections may block an upgrade, so the plan must be read first. Do not add `--force` by default. This page ends with first use of one skill. Removal, version management and full options are in the [CLI reference](./guide/cli.html); authoring and deployment tasks start from the [documentation navigator](./guide/index.html). diff --git a/docs/skillhub/faq.md b/docs/skillhub/faq.md index e3e056b78..538a6ab71 100644 --- a/docs/skillhub/faq.md +++ b/docs/skillhub/faq.md @@ -275,7 +275,9 @@ A: SkillHub 默认的 Compose 和 `runtime.sh` 使用 Docker named volume(`pos ## Q: 通过 OAuth(GitHub / GitLab 等)登录的账号,如何取得管理员权限? -A: OAuth 首次登录创建的是普通用户。需要由已有的 `SUPER_ADMIN`(例如初始化时的 bootstrap admin)在后台将其提升为管理员。 +A: 外部登录先按实例现有准入策略处理。首次创建且状态为 `ACTIVE` 的外部账号,如果身份来源提供已验证邮箱,并匹配启用的首次授权规则,可获得该规则配置的平台角色;没有匹配规则时不自动授予平台管理权限。规则仅在新账号创建时执行,不追溯已有账号,也不因邮箱相同而合并账号。已有账号由具有相应权限的平台角色在用户管理中授权;超级管理员(SUPER_ADMIN)的授予须由超级管理员执行。 + +账号与凭据的说明见[账号与访问令牌](./guide/account-access.html);执行条件见[首次外部授权服务](https://github.com/iflytek/skillhub/blob/main/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/settings/InitialExternalRoleGrantService.java)及[账号创建流程](https://github.com/iflytek/skillhub/blob/main/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/identity/IdentityBindingService.java)。 `USER_ADMIN` 可以管理用户状态,并分配除 `SUPER_ADMIN` 之外的平台角色;但不能向任何账号授予 `SUPER_ADMIN`,也不能修改已有 `SUPER_ADMIN` 账号的角色。这两类操作只有 `SUPER_ADMIN` 可以执行。 diff --git a/docs/skillhub/guide/avatar-moderation-configuration.md b/docs/skillhub/guide/avatar-moderation-configuration.md new file mode 100644 index 000000000..e1fdfeead --- /dev/null +++ b/docs/skillhub/guide/avatar-moderation-configuration.md @@ -0,0 +1,123 @@ +# 配置头像机器审核服务 + +本页面向具有部署权限的操作者,说明头像图片审核供应商的服务开通、凭据注入、服务更新与实际调用核验。部署前须已有可运行的注册中心及包含本功能的镜像;本页不部署独立审核引擎,不说明技能所有者的上传操作。头像提交、策略与审核入口见[技能头像与审核](./skill-avatars.html)。 + + +## 前置条件与职责 + +| 操作 | 执行主体 | 前置与完成依据 | +| --- | --- | --- | +| 注入凭据和更新容器 | 具有部署权限的操作者 | 原注册中心正常运行,能够使用其部署目录和私有配置;更新的是原项目服务 | +| 开启审核策略 | 超级管理员(SUPER_ADMIN) | 配置齐全后在系统配置保存开关;保存成功不代表云服务调用成功 | +| 产生验收候选 | 技能所有者 | 向非私有测试技能提交新头像;不复用旧申请推断接入结果 | +| 核对审核与公开结果 | 有权技能审核人 | 在原技能申请中核对图片及机器结果;不得为验收批准违规内容 | + +## 选择供应商并确认权限 + +每个服务部署只选择一个:`xfyun` 或 `aliyun`。供应商及凭证在应用启动时读取;后台仅能启停审核,不能切换供应商。不开启机器审核时无需提供云审核凭证。 + +| 供应商 | 需要开通的服务 | 所需凭证 | +| --- | --- | --- | +| 讯飞 | 图片合规审核 | APPID、APIKey、APISecret | +| 阿里云 | 内容安全增强版,上海地域的头像图片检测 `profilePhotoCheck` | RAM 用户的 AccessKey ID、AccessKey Secret | + +服务开通、额度及计费以供应商控制台为准;开启后真实调用可能产生费用。 + +- 讯飞:[官方图片合规服务接入与鉴权说明](https://www.xfyun.cn/doc/nlp/ImageModeration/API.html)。APIKey 对应 `access-key-id`,APISecret 对应 `access-key-secret`。 +- 阿里云:[内容安全控制台](https://yundun.console.aliyun.com/?p=cts)、[开通服务与创建 RAM 用户的官方接入步骤](https://help.aliyun.com/zh/document_detail/467828.html)。按最小权限配置 `yundun-greenweb:DescribeUploadToken` 和 `yundun-greenweb:ImageModeration`,不需要给审核用户自有 OSS 全权限。 + +阿里云适配器通过官方临时上传令牌上传私有图片,再调用同步审核,**无需自建审核用 OSS Bucket**。它与 SkillHub 自己保存技能和头像的对象存储配置相互独立。当前将 `RiskLevel=none/low` 视为通过,`medium/high` 视为阻止,机器阻止后的人工处理遵循头像审核策略,不代表供应商已经作出最终人工决定。空结果、未知值及接口失败均不放行。参考[官方接口说明](https://help.aliyun.com/document_detail/467829.html)。 + +## 注入私有配置并重新创建服务 + +下面使用仓库标准 `compose.release.yml` 的 `server` 服务。先按现有部署流程准备 `.env.release`、数据库及 SkillHub 对象存储,选用包含本功能的镜像版本。本节不会替换原部署设置。 + +在仓库外建立私有目录,将示例路径 `/etc/skillhub/private` 换成实际路径。以下是本页采用的操作系统权限示例,不是应用配置默认值;不得把凭据文件提交到 Git。 + +| 操作对象 | 本页权限示例 | 生效方式与边界 | +| --- | --- | --- | +| 私有目录 | `700` | 由部署方设置文件系统权限,仅目录所有者访问 | +| 凭据与 override 文件 | `600` | 由部署方设置文件系统权限,仅文件所有者读写 | + + +标准 Compose 只透传它声明的环境变量;仅向 `.env.release` 添加新审核属性不会自动注入 `server`。以下通过额外 override 的 `env_file` 显式注入,原 Compose 模板没有内置这些凭证字段。 + +创建 `/etc/skillhub/private/avatar-moderation.env`,以下两种内容**二选一**。占位符需替换为实际凭证;`SPRING_APPLICATION_JSON` 必须是单行合法 JSON。 + +**讯飞:** + +```dotenv +SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"xfyun","xfyun":{"app-id":"YOUR_APPID","access-key-id":"YOUR_APIKEY","access-key-secret":"YOUR_APISECRET"}}}}} +``` + +**阿里云:** + +```dotenv +SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"aliyun","aliyun":{"access-key-id":"YOUR_ACCESS_KEY_ID","access-key-secret":"YOUR_ACCESS_KEY_SECRET"}}}}} +``` + +如果部署已有 `SPRING_APPLICATION_JSON`,**将上述 `skillhub.avatar.moderation` 合并进原 JSON,不要覆盖原配置或设置重复变量**;其他 override 若通过 `environment` 定义同名变量,会优先于 `env_file`,也需同步合并。特殊字符应按 JSON 格式转义。 + +在同一私有目录创建 `compose.avatar.yml`: + +```yaml +services: + server: + env_file: + - /etc/skillhub/private/avatar-moderation.env +``` + +然后在仓库根目录执行。已有部署若使用额外 Compose 文件、`-p` 项目名或其他启动参数,保留这些参数,再追加头像 override,确保更新原服务: + +```bash +make validate-release-config +docker compose --env-file .env.release \ + -f compose.release.yml \ + -f /etc/skillhub/private/compose.avatar.yml \ + up -d --no-deps server + +docker compose --env-file .env.release \ + -f compose.release.yml \ + -f /etc/skillhub/private/compose.avatar.yml \ + ps server +``` + +上述更新命令适用于已运行的完整栈。首次部署完整栈时,将 `up -d --no-deps server` 改为 `up -d`。只执行 `restart` 不会重新加载修改后的容器环境,配置更新需要重新创建服务。后续更新也要保留同一 override。 + +正式 Spring 属性是 `skillhub.avatar.moderation.provider`、`skillhub.avatar.moderation.xfyun.app-id`、`skillhub.avatar.moderation.xfyun.access-key-id`、`skillhub.avatar.moderation.xfyun.access-key-secret`,以及 `skillhub.avatar.moderation.aliyun.access-key-id`、`skillhub.avatar.moderation.aliyun.access-key-secret`。其他部署平台可通过 Secret 注入同等属性。 + +::: warning 讯飞出口日志 +讯飞官方接口将 `accessKeySecret` 放在请求 URL 参数中。应用不记录完整 URL 或异常原文,但部署方仍需关闭 HTTP 客户端调试日志,并确保出口代理、链路追踪及第三方日志不采集该请求 URL。不要把含凭证的 Compose 展开结果、容器环境或签名请求 URL 分享给其他人。 +::: + +## 开启审核并核验实际结果 + +1. 确认 `server` 健康后,以超级管理员进入「系统配置」。 +2. 开启机器审核,初次接入时保留人工审核开启,以便核对机器结果与人工决定。 +3. 用技能所有者账号对一个非 `PRIVATE` 测试技能提交**新头像**。 +4. 在更新页查看机器结果;开启人工时,审核员在技能审核详情中确认图片、机器状态并做出决定。 +5. 对通过、阻止、异常分别检查:通过前旧公开头像不变,阻止或异常的新图片不可公开,人工拒绝后可见原因。不要为了测试把违规图片批准公开。 + +填写凭证、成功保存开关或应用健康,均不能证明云服务调用成功。后台检查的是配置是否齐全,真正的服务权限、网络、余额和接口响应必须通过新申请验证。已有申请不因开关开启而补跑机器审核。 + +供应商接口的代码与模拟测试不能替代本部署的账号验收。每次启用或轮换后都应验证实际账号的连通性、结果映射和失败行为。 + +## 切换供应商与已有申请 + +每次申请保存提交时的机器、人工开关和供应商快照。后续配置变更不会回写已有申请,也不会重跑已完成结果。切换前,先由有权审核人处理待审申请;更新私有配置、重新创建 `server` 后,由技能所有者提交新申请以使用新供应商。 + +旧候选仍需调用旧供应商时,切换后会得到 `ERROR`,不会改用新供应商。不得仅更新后台开关后认定旧任务已经恢复。SkillHub 候选图片保留规则见[技能头像与审核](./skill-avatars.html);供应商临时上传图片的生命周期属于外部服务规则,二者不能互相替代。 + +## 结果确认与失败处置 + +后台允许开启机器审核,仅表示所选供应商的必要配置齐全。完成接入须以新申请的实际机器结果和候选图片可见性为依据;服务健康、填写凭证与保存开关均不能替代真实调用核验。 + +| 现象 | 最可能原因 | 定位手段 | 处置 | +| --- | --- | --- | --- | +| 开启时提示供应商不可用 | `provider` 拼写错误或凭据未注入 | 核对私有文件中的属性名及启动命令是否包含相同 override | 修正配置并重新创建原服务;不要输出完整环境变量或 Secret | +| 配置修改后行为未变 | 仅重启容器,或同名变量被覆盖 | 比较实际启动使用的 Compose 文件顺序及 `environment`/`env_file` 定义 | 合并同名 JSON 并重新创建服务;不要覆盖其他 Spring 配置 | +| 新申请机器结果为 `ERROR` | 服务未开通、权限、额度或出口网络异常 | 核对新申请机器状态及供应商控制台权限、服务和额度;阿里云还需检查临时 OSS 上传端点可达性 | 恢复依赖后按冷却规则重试;不要将异常当作允许 | +| 切换后旧候选持续异常 | 申请保存的供应商与当前部署不一致 | 比较候选所用供应商和当前 `provider` | 处理旧申请或重新提交;不要直接修改候选快照 | +| 开启机器审核后旧申请没有新结果 | 开关不追溯已有申请 | 在更新页核对申请时间、机器状态及本次候选 | 使用新申请验证;不要为生成调用重复批准旧申请 | + +配置绑定及供应商选择依据:[供应商网关](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/AvatarModerationGateway.java)、[讯飞适配器](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/XfyunAvatarModerationProvider.java)和[阿里云适配器](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/AliyunAvatarModerationProvider.java)。本页命令以[release Compose](https://github.com/iflytek/skillhub/blob/main/compose.release.yml)为基线;其他部署路径须通过其 Secret 机制注入相同属性,不得直接套用 Compose 更新命令。 diff --git a/docs/skillhub/guide/cli.md b/docs/skillhub/guide/cli.md index a76030f50..89d5e60c5 100644 --- a/docs/skillhub/guide/cli.md +++ b/docs/skillhub/guide/cli.md @@ -445,13 +445,10 @@ skillhub remove pdf-parser --json skillhub doctor --json ``` -成功响应格式: +以下为成功标志的 JSON 节选,不是完整命令响应;结果字段取决于命令: ```json -{ - "ok": true, - ... -} +{"ok": true} ``` 错误响应格式: @@ -666,15 +663,14 @@ skillhub search test --registry https://skillhub.example.com ### 安装目录冲突 -```bash -# 使用 --force 覆盖 -skillhub install pdf-parser --force +先核对当前注册中心、目标 Agent 和安装目录,再检查现有文件的来源及本地修改。以下以 Codex 为例;其他 Agent 应使用实际标识。 -# 或先删除再安装 -skillhub remove pdf-parser -skillhub install pdf-parser +```bash +skillhub list --agent codex --json ``` +将记录中的 `installDir` 与冲突路径比较,并读取该目录的 `SKILL.md`。确认属于同一安装来源、完成备份且明确允许舍弃本地改动后,才可按更新计划使用 `--force`。该参数不能接管未管理目录、其他来源或已停用目标。无法确认来源时,应选择不同的目录或安装范围,不得直接删除文件或安装记录排障。 + ### 清单损坏 ```bash diff --git a/docs/skillhub/guide/index.md b/docs/skillhub/guide/index.md index cef079693..835d33182 100644 --- a/docs/skillhub/guide/index.md +++ b/docs/skillhub/guide/index.md @@ -11,7 +11,7 @@ ## 使用技能 -| 你要做什么 | 阅读 | +| 操作目标 | 阅读 | | --- | --- | | 找到适合任务的技能,查看版本和权限 | [搜索与安装技能](./skill-discovery.html) | | 一次安装一组固定版本技能,从入口技能开始使用 | [管理技能套装](./skill-suites.html) | @@ -30,6 +30,7 @@ - [管理命名空间](./namespace.html):成员、角色和资源可见范围。 - [审核技能与套装](./review.html):处理技能与套装申请。 - [安全扫描与报告](./scanner.html):扫描服务接入及结果解读。 +- [技能头像与审核](./skill-avatars.html):技能所有者提交头像,有权审核人处理申请,超级管理员调整审核策略。 ## 部署与运维 @@ -38,7 +39,7 @@ - [Docker 部署](./deployment.html):安装、配置、升级和备份。 - [Kubernetes 部署(Kustomize / Helm)](./kubernetes.html):选择清单或独立 Chart 路径。 - [前端动作统计](./frontend-analytics.html):可选配置化接入、授权与故障验收,按部署版本选择配置。 -- [技能头像与审核](./skill-avatars.html):管理员配置图片审核服务。 +- [配置头像机器审核服务](./avatar-moderation-configuration.html):部署方选择供应商、注入凭据、更新服务并验证实际调用。 ## 开发与集成 diff --git a/docs/skillhub/guide/namespace.md b/docs/skillhub/guide/namespace.md index b35466360..cafd1da75 100644 --- a/docs/skillhub/guide/namespace.md +++ b/docs/skillhub/guide/namespace.md @@ -1,248 +1,111 @@ # 管理命名空间 -创建团队空间入口仅向平台 SKILL_ADMIN / SUPER_ADMIN 展示。普通成员先联系有权创建者建立空间并邀请加入;成为团队 Owner 不等于获得平台管理角色。 +本页说明团队命名空间的创建、成员维护和生命周期治理,适用于有相应权限的操作者。技能所有权、平台角色和命名空间角色分别管理;创建或管理命名空间不代表取得平台权限。`GLOBAL` 等非团队类型不适用本页的生命周期操作。 -创建权限依据 [NamespacePortalCommandAppService](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/NamespacePortalCommandAppService.java)。 +## 前置条件与职责 -## 团队开始协作的顺序 +命名空间确定技能坐标中的归属,例如 `@team/example-skill`;该坐标仅为示例,不保证存在。命名空间 slug 创建后不可修改,显示名称可以在具备编辑权限时调整。 -1. 先使用平台技能管理员(`SKILL_ADMIN`)或超级管理员(`SUPER_ADMIN`)账号登录;仅这两类平台角色可在“我的空间”创建团队命名空间,填写稳定的 slug 和易读的显示名称。slug 是安装坐标的一部分,不能随团队改名而修改。 -2. 在成员页添加已有账号或生成邀请链接。普通角色选择是 MEMBER / ADMIN;移交所有权使用独立的转让入口,不通过普通角色下拉框添加 Owner。 -3. 团队成员在发布页选择该空间。团队内共享请选择 NAMESPACE_ONLY;PRIVATE 不等于“全体团队成员可见”。 -4. 管理员在空间审核入口处理提交,成员在“我的技能”跟踪自己的版本。 -5. 人员变动时先安排技能维护责任,再移除成员。成员移除不自动转让技能所有权。 +| 操作 | 所需身份 | 入口与判断依据 | +| --- | --- | --- | +| 创建团队命名空间 | 平台技能管理员(SKILL_ADMIN)或超级管理员(SUPER_ADMIN) | `/dashboard/namespaces` 的创建入口;普通成员不可创建 | +| 维护成员与资料 | 所有者(Owner)或空间管理员(Admin) | 命名空间处于 `ACTIVE`,详情页显示相应操作 | +| 发布技能 | 成员(Member)及具备发布权限的操作者 | 在发布页选择命名空间;仍受扫描、审核和技能维护权限约束 | +| 查看成员 | 已加入的成员 | 详情页“成员”页签;查看权限不包含成员修改权限 | -### 设置按钮为什么不一样 +权限依据:[创建服务](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/NamespacePortalCommandAppService.java)与[命名空间策略](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/namespace/NamespaceAccessPolicy.java)。 -以下矩阵只适用于 `TEAM` 类型命名空间;服务端权限优先于角色名称。平台角色与命名空间成员角色分别校验,不能互相推导。 +## 创建并组织协作 -| 命名空间状态 | 命名空间角色 | 可用治理操作 | 条件与限制 | -| --- | --- | --- | --- | -| `ACTIVE` | 所有者(Owner) | 冻结、归档、删除;编辑资料、成员及所有权转让 | 删除另须满足下方依赖检查 | -| `ACTIVE` | 空间管理员(Admin) | 冻结;编辑资料、管理成员 | 不能归档、删除或转让所有权 | -| `ACTIVE` | 成员(Member) | 无上述治理操作 | 不能因技能所有者身份管理命名空间 | -| `FROZEN` | 所有者(Owner) | 解冻、归档、删除 | 删除另须满足依赖检查;成员管理只读 | -| `FROZEN` | 空间管理员(Admin) | 解冻 | 不能归档、删除;成员管理只读 | -| `FROZEN` | 成员(Member) | 无上述治理操作 | 不可写入 | -| `ARCHIVED` | 所有者(Owner) | 恢复、删除 | 恢复进入 `ACTIVE`;删除另须满足依赖检查 | -| `ARCHIVED` | 空间管理员(Admin)或成员(Member) | 无上述治理操作 | 不因曾有编辑权限获得恢复权限 | +1. 由有权创建者进入创建入口,填写显示名称、稳定 slug 和职责说明。创建成功后,创建者成为该命名空间所有者;此操作不新增平台角色。 +2. 打开详情页“成员”,为已有账号添加成员或生成邀请。添加时选择 `MEMBER` 或 `ADMIN`;命名空间所有权通过独立转让入口处理,不使用普通角色选择框授予 `OWNER`。 +3. 成员在发布页选择目标命名空间。面向成员共享时选择空间成员可见(NAMESPACE_ONLY);私有(PRIVATE)不会对全体成员开放,公开(PUBLIC)也不要求读者先加入该命名空间。 +4. 提交后,由有权审核人在命名空间审核入口处理,作者在“我的审核进度”跟踪结果。成员身份不能替代发布和审核完成状态。 -| 命名空间状态 | 平台角色 | 平台专用入口的治理操作 | 条件与限制 | -| --- | --- | --- | --- | -| `ACTIVE` | 超级管理员(SUPER_ADMIN) | 冻结、归档 | 不要求命名空间成员身份;不包含永久删除 | -| `FROZEN` | 超级管理员(SUPER_ADMIN) | 解冻、归档 | 不要求命名空间成员身份 | -| `ARCHIVED` | 超级管理员(SUPER_ADMIN) | 恢复至 `ACTIVE` | 不要求命名空间成员身份 | -| 任意状态 | 技能管理员(SKILL_ADMIN)或用户管理员(USER_ADMIN) | 单靠平台角色没有上述专用治理权限 | 若另有命名空间角色,按上一张表判断 | +![创建命名空间、加入成员并进入发布审核的职责顺序](/diagrams/namespace-membership-flow.svg) -`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)。完成操作后核对目标命名空间状态,不仅查看请求提示。 +创建与添加成员的请求示例如下,名称、slug 和用户标识均为占位值;程序化调用还须满足实例认证与防跨站请求规则。 - -## 功能描述 - -命名空间(Namespace)是 SkillHub 的核心组织单元。每个命名空间代表一个团队或项目,拥有独立的成员、权限和技能包。 - -![概念图](/diagrams/namespace-concept.png) - -**命名空间的作用**: - -- **隔离**:不同团队的技能包互不干扰 -- **权限**:基于角色的访问控制(RBAC) -- **协作**:团队成员可以共同管理技能包 -- **治理**:管理员可以审核、归档、冻结技能包 - -**角色体系**: - -| 角色 | 权限 | -|------|------| -| **Owner** | 团队空间所有者,可按空间状态与服务端权限管理成员及转让所有权 | -| **Admin** | 管理成员、审核技能包、修改设置 | -| **Member** | 发布技能包、查看空间成员可见的技能包 | - -**命名空间状态**: - -- **Active**:正常运行 -- **Frozen**:冻结状态,无法发布新技能包 -- **Archived**:归档状态,从搜索结果中隐藏 - -## 使用场景 - -**场景一:创建团队命名空间** - -团队负责人创建一个新的命名空间,用于管理团队的技能包。 - -![操作截图](/screenshots/namespace-create.png) - -**场景二:添加团队成员** - -管理员邀请新成员加入命名空间,分配合适的角色。 - -![操作截图](/screenshots/namespace-members.png) - -**场景三:权限管理** - -调整成员角色,控制谁可以发布、审核、管理技能包。 - -**场景四:命名空间冻结** - -发现命名空间有安全问题,临时冻结所有发布操作。 - -## 使用步骤 - -**创建命名空间**: - -1. 核对当前账号具有平台技能管理员(`SKILL_ADMIN`)或超级管理员(`SUPER_ADMIN`)角色,再访问 `/dashboard/namespaces`;普通成员没有创建入口,须联系有权创建者。 -2. 点击「创建命名空间」 -3. 填写信息: - - 名称:团队名称(例如 "iFlytek AI Team") - - Slug:URL 标识符(例如 "iflytek") - - 描述:简要说明团队职责和技能包范围 - -![流程图](/diagrams/namespace-create-flow.png) - -4. 提交创建,注册中心将创建者设为该命名空间所有者(Owner);这不会新增平台角色。 - -**添加成员**: - -1. 进入命名空间详情页 -2. 点击「成员」标签 -3. 点击「添加成员」 -4. 搜索用户(支持按用户名、邮箱搜索) -5. 选择角色(Admin / Member;Owner 使用独立转让流程) -6. 确认添加 - -**通过链接邀请成员**: - -1. Owner 或 Admin 在处于 ACTIVE 状态的团队空间「成员」页点击「邀请成员」。 -2. 复制链接并安全地发给要加入的人。链接 24 小时内有效,只能由一名尚未加入的用户使用一次。 -3. 对方先按现有登录及账号准入规则进入 SkillHub。打开链接后会看到目标空间、当前账号和 MEMBER 权限;点击「确认加入」才会成为成员。 -4. 如需提前失效,点击「作废邀请」。重新生成链接时,页面会要求确认旧链接立即失效;已加入的成员不受影响。 - -邀请链接是持有者可用的加入凭证,不限定邮箱或账号。不要在公开频道分享。登录回跳不会携带邀请 Token;同一浏览器标签页会暂存链接直到确认、已加入或确认失效。 - -**管理权限**: - -1. 在成员列表中找到目标用户 -2. 点击「修改角色」 -3. 选择新角色并确认 -4. 系统会记录权限变更到审计日志 - -**冻结命名空间**: - -1. 进入命名空间设置 -2. 点击「冻结命名空间」 -3. 填写冻结原因(可选) -4. 确认冻结 - -> 冻结后,命名空间内的所有技能包无法发布新版本,但已有版本仍可下载。 - -## 成员被移除后,技能如何处理 - -移除成员不会删除、迁移或转让他的技能。技能地址、历史版本和所有者保持不变,已发布内容继续按原可见范围提供。 - -账号正常的当前技能所有者仍可在“我的技能”查看和下载自己的内容,包括私有内容、草稿和历史版本;页面会提示“已不在该空间,只能查看和下载”。不能继续上传、重新发布、改头像、改可见范围、撤回申请、归档或删除技能。其他成员的内部内容不因这项例外对他开放。 - -重新加入且仍为技能所有者时,按原规则恢复维护权限。如果账号被停用,则不能以该账号查看或操作;重新启用不会自动恢复已移除的空间成员关系。此前已提交的审核申请仍由有权审核人按原流程处理,不自动通过或撤回。 - -空间及平台管理员保留原有治理、审核权限,但成员移除不会自动为技能指定接任者。本期没有新增技能转让、自助退出或永久注销账号功能。 - -## API 接口 - -**创建命名空间**: ```http POST /api/v1/namespaces Content-Type: application/json -{ - "displayName": "iFlytek AI Team", - "slug": "iflytek", - "description": "iFlytek's AI agent skills" -} +{"displayName":"Example Team","slug":"example-team","description":"Shared authoring"} ``` -**参数说明**: -| 参数 | 类型 | 说明 | -|------|------|------| -| displayName | string | 命名空间名称(必需,最多 128 字符) | -| slug | string | URL 标识符(必需,唯一,2-64 字符,只能包含小写字母、数字、连字符) | -| description | string | 描述(可选,最多 512 字符) | - -**获取命名空间详情**: -```http -GET /api/v1/namespaces/{slug} -``` - -**更新命名空间**: -```http -PUT /api/v1/namespaces/{slug} -Content-Type: application/json - -{ - "displayName": "iFlytek AI Team (Updated)", - "description": "Updated description" -} -``` - -**添加成员**: ```http POST /api/v1/namespaces/{slug}/members Content-Type: application/json -{ - "userId": "user-123", - "role": "MEMBER" -} +{"userId":"example-user","role":"MEMBER"} ``` -**更新成员角色**: -```http -PUT /api/v1/namespaces/{slug}/members/{userId}/role -Content-Type: application/json +## 邀请、角色调整与记录 -{ - "role": "ADMIN" -} -``` +在 `ACTIVE` 团队命名空间的“成员 → 邀请成员”创建链接,通过受控渠道分享。持链接者须先完成登录和现有准入,再核对目标、当前账号及 `MEMBER` 角色并确认加入;打开链接本身不建立成员关系。链接不限定邮箱或账号,不得在公开渠道发布。 -**移除成员**: -```http -DELETE /api/v1/namespaces/{slug}/members/{userId} -``` +| 项目 | 当前规则 | 生效与边界 | +| --- | --- | --- | +| 有效期与使用次数 | 创建后24小时,一名新成员使用一次 | 固定规则;到期或使用后不能再次加入 | +| 替换与作废 | 操作者确认后,旧链接立即失效 | 已加入成员保留成员资格 | +| 网页邀请记录 | 每页5条,可分页查询 | 网页固定展示;完整用户标识可通过悬停查看 | +| 历史查询分页 | 每页1–50条 | 请求参数控制,不返回邀请码或哈希 | +| 历史保留 | 命名空间存在期间保留 | 彻底删除命名空间时删除邀请业务记录;操作审计按原规则保留 | -**冻结命名空间**: -```http -POST /api/v1/namespaces/{slug}/freeze -Content-Type: application/json +链接采用 `/join#invite=邀请码`。创建人的同一账号、同一浏览器标签页暂存链接,刷新后重新打开弹窗,校验仍有效即可复制;换账号、标签页或设备不能依靠该暂存恢复。历史记录不提供原邀请码;原链接遗失时,须确认替换后创建新邀请。登录回跳不携带邀请 Token。 -{ - "reason": "Security investigation" -} -``` +邀请历史显示创建人、时间、到期时间、状态和实际加入账号。改名或成员离开不改写当时加入事实;历史不代表当前成员资格。仅命名空间所有者及空间管理员可查看,冻结或归档时为只读。升级仅迁入可确认的当前邀请并标注旧记录,不推测更早历史。 -**解冻命名空间**: -```http -POST /api/v1/namespaces/{slug}/unfreeze -``` +角色调整时,在成员行选择修改角色,再使用操作栏保存;保存后重新核对角色。移除成员和转让命名空间所有权须分别确认,后者不转让其技能。邀请实现见[邀请服务](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/namespace/NamespaceInvitationService.java)及[历史展示](https://github.com/iflytek/skillhub/blob/main/web/src/features/namespace/invitation-history.tsx)。 -## 邀请成员与邀请记录 +## 生命周期治理 -团队空间的 Owner/Admin 可在“成员 → 邀请成员”生成24小时有效、仅一名新成员可使用的链接。对方须先登录并通过平台准入,再确认加入;仅打开链接不会自动成为成员。替换有效链接和作废须确认,已加入成员不受影响。 +以下矩阵适用于 `TEAM`。服务端权限和依赖检查优先于角色名称。 -新链接采用 `/join#invite=邀请码`。创建人的同一账号、同一浏览器标签页会暂存链接;刷新页面后重新打开邀请弹窗,系统校验它仍是当前有效邀请后可继续复制。换账号、换标签页或换设备不能依靠这份暂存恢复原链接,邀请历史也不返回邀请码;如果没有保存原链接,需要创建新邀请,并在替换前确认旧链接失效。 +| 命名空间状态 | 命名空间角色 | 可用操作 | 限制 | +| --- | --- | --- | --- | +| `ACTIVE` | 所有者 | 编辑、成员管理、所有权转让、冻结、归档、删除 | 删除还须无依赖 | +| `ACTIVE` | 空间管理员 | 编辑、成员管理、冻结 | 不可归档、删除或转让所有权 | +| `ACTIVE` | 成员 | 无上述治理操作 | 技能所有者身份不增加治理权限 | +| `FROZEN` | 所有者 | 解冻、归档、删除 | 成员管理只读;删除还须无依赖 | +| `FROZEN` | 空间管理员 | 解冻 | 不可归档或删除 | +| `FROZEN` | 成员 | 无上述治理操作 | 不可写入 | +| `ARCHIVED` | 所有者 | 恢复至 `ACTIVE`、删除 | 删除还须无依赖 | +| `ARCHIVED` | 空间管理员或成员 | 无上述治理操作 | 原编辑权限不包含恢复 | -弹窗下方直接展示分页邀请记录(网页每页5条,列表最高240px):创建人及时间、到期时间、状态,以及实际加入账号与时间。人员优先显示记录时保存的姓名,完整账号ID放在悬停提示;无姓名时显示短标识。每次生成独立记录,替换、作废、过期和成员离开不会抹掉原历史。历史不能恢复失效链接,也不代表当前成员资格。普通成员和仅有平台角色的账号不能查看,冻结/归档空间的 Owner/Admin 可查看只读历史。 +| 命名空间状态 | 平台身份 | 平台专用治理入口 | 限制 | +| --- | --- | --- | --- | +| `ACTIVE` | 超级管理员 | 冻结、归档 | 不要求成员身份,无永久删除入口 | +| `FROZEN` | 超级管理员 | 解冻、归档 | 不要求成员身份 | +| `ARCHIVED` | 超级管理员 | 恢复至 `ACTIVE` | 不要求成员身份 | +| 任意状态 | 技能管理员或用户管理员 | 单靠平台角色无上述专用权限 | 另有成员角色时,按上一表判断 | -升级只迁入可以准确读取的当前邀请并标记“旧记录”,不推测更早链接的使用情况。空间存在期间保留历史,彻底删除空间时删除邀请业务记录,既有操作审计按原规则保留。 +冻结用于暂停写入,不撤回客户端已安装文件;已有版本仍按访问规则读取。归档使命名空间退出搜索,并保留已有技能访问。永久删除仅由所有者发起,须没有技能、审核任务、指向该命名空间的提升申请及创作草稿;归档不会清除依赖。 -历史查询使用浏览器 Session:`GET /api/v1/namespaces/{slug}/invitations/history?page=0&size=10`,每页1–50条,不返回邀请码或哈希。 +依据:[命名空间服务](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/namespace/NamespaceService.java)与[平台治理入口](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/admin/AdminNamespaceController.java)。 -## 注意事项 +## 完成标准与失败处理 -> **Slug 唯一性**:命名空间 slug 在全局范围内必须唯一,且创建后不可修改。建议使用团队或项目的简短标识符。 +创建后,列表应显示目标 slug、`ACTIVE` 和创建者的所有者角色;邀请接受后,成员列表应包含实际账号及 `MEMBER`。治理动作结束后重新读取详情,核对目标状态,例如解冻后为 `ACTIVE`。邀请记录显示已使用,不代表该账号当前仍为成员。 -- **Owner 权限**:每个命名空间至少需要一个 Owner,最后一个 Owner 无法被移除 -- **角色继承**:成员可访问 NAMESPACE_ONLY 内容;PRIVATE 内容仅所有者及有权管理员可访问,不向所有成员开放 -- **冻结机制**:管理员可以冻结命名空间,冻结后无法发布新技能包 -- **归档机制**:归档的命名空间会从搜索结果中隐藏,但已有技能包仍可访问 -- **审计日志**:所有成员变更、权限调整都会记录到审计日志 +| 现象 | 最可能原因 | 定位手段 | 处置 | +| --- | --- | --- | --- | +| 无创建入口 | 缺少平台创建角色 | 核对账号的平台角色及页面身份 | 联系有权创建者;不要反复注册账号 | +| 邀请无法加入 | 过期、已使用、作废或命名空间不可写 | 邀请弹窗核对状态;设置页核对命名空间状态 | 原操作者按需创建新邀请;不要重复使用旧链接 | +| 刷新后无法复制链接 | 标签页暂存不可用或链接已失效 | 原账号原标签页重开弹窗,读取有效性结果 | 先重试校验;原码不可恢复时确认替换,不要将历史记录当作邀请码 | +| 成员操作不可用 | 非所有者/空间管理员,或已冻结/归档 | 核对成员角色、状态及只读提示 | 由有权操作者恢复后再处理;不要修改浏览器请求绕过权限 | +| 永久删除被拒绝 | 存在四类依赖之一 | 按响应指出的对象,检查技能、审核、提升和草稿列表 | 先按各对象流程处理;不要直接删数据库记录 | + +## 成员移除与维护边界 + +移除成员不会删除、迁移或转让其技能,已发布内容继续按原可见范围提供。账号正常的当前技能所有者仍可在“我的技能”查看和下载自己的内容,包括私有内容、未发布版本和历史版本;页面显示只读提示。仅凭该所有者身份不能上传、重新发布、改头像或可见范围、撤回、归档或删除;其他成员的受限内容不因该例外开放。 + +重新加入且仍为所有者时,按原规则恢复维护;停用账号不可操作,重新启用不恢复已移除的成员关系。已提交申请继续正常审核,不自动批准或撤回。空间及平台治理权限保持原规则,本版不提供技能转让、自助退出或永久注销功能;[所有者访问策略](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/SkillOwnerAccessPolicy.java)不替代其他管理权限。 + +## 延伸阅读 + +- [发布与更新技能](./skill-publish.html):按目标可见范围提交版本。 +- [审核技能与套装](./review.html):判断待审对象与处理结果。 +- [账号与访问令牌](./account-access.html):区分登录身份与接口凭据。 diff --git a/docs/skillhub/guide/review.md b/docs/skillhub/guide/review.md index 435bf49ee..9658fefa0 100644 --- a/docs/skillhub/guide/review.md +++ b/docs/skillhub/guide/review.md @@ -1,234 +1,128 @@ # 审核技能与套装 -## 审核员的检查清单 +本页面向具备审核权限的操作者,说明待审内容核查、决定提交及结果确认;作者可按职责表跟踪申请。审核决定针对具体申请及版本,不替代 Agent 执行测试、合规认证或全局提升审批。 -1. 核对对象、提交者及目标版本;版本、头像资料和套装不能混用判断。 -2. 读取本次提交的文件与变更,不仅阅读当前公开版本。新版审核期间,旧公开版本可能仍可下载。 -3. 检查扫描状态及发现项。扫描执行失败、风险发现和未配置某项分析器分别处理;空报告不能当作安全结论。 -4. 检查可见范围与受众,特别是套装每个成员的可用性和入口身份。成员通过审核不自动批准套装。 -5. 批准前确认当前数据仍有效;拒绝时写明具体文件、问题及修订方向。点击失败时重新读取状态,避免对旧页面重复作出相反决定。 -6. 审核后核对记录及发布结果;Agent 执行效果需另验。 +## 前置条件与职责 -### 作者如何跟踪和修订 +| 操作 | 身份与条件 | 入口 | +| --- | --- | --- | +| 团队命名空间审核 | 该命名空间所有者(Owner)或空间管理员(Admin) | 命名空间详情的“审核”页签 | +| 跨命名空间审核 | 平台技能管理员(SKILL_ADMIN)或超级管理员(SUPER_ADMIN) | `/dashboard/reviews` | +| 跟踪本人申请 | 提交者 | “我的审核进度”;申请可读不代表可以批准 | +| 全局提升与撤销 | 提交者及有权平台审核人 | `/dashboard/promotions`,与普通版本审核分别处理 | -普通 `PUBLIC / NAMESPACE_ONLY` 上传创建审核任务;`PRIVATE` 上传先保留,须确认发布或另行提审。在“我的提交”查看任务和意见;有权撤回者在待审任务选择「撤回」并确认。撤回是停止当前审核,不会删除已发布旧版本或撤销已批准的全局提升。被拒绝后根据意见修订,再通过当前版本页面提供的重新提交操作继续;不要把上传成功当成审核重开成功。 +团队命名空间的所有者及空间管理员可审核本人提交;超级管理员可自审。其他本人提交不能仅凭平台技能管理员身份自审;全局提升的本人申请仅超级管理员可审核。普通审核决定还要求命名空间为 `ACTIVE`。规则见[审核权限策略](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/ReviewPermissionChecker.java)。 +普通公开(PUBLIC)或空间成员可见(NAMESPACE_ONLY)上传进入扫描与审核流程;私有(PRIVATE)上传先保留,仍须确认发布或另行提审。新版审核期间,旧发布版可能继续可用。 + +## 核查内容并提交决定 + +![核对申请、检查证据、提交决定并重新读取结果的审核流程](/diagrams/review-decision-flow.svg) + +图:申请仍为待审且具备处理权限时才可作出决定;读取旧版本不等于核对本次申请。 + +1. 在待审列表打开申请,核对提交者、对象、目标版本、可见范围及命名空间。GitHub 同步项另有内容修订号、来源仓库和固定 commit;安装使用的技术版本在技术信息中查看。 +2. 在“技能内容”检查本次说明文档和文件树;进入页签后读取说明,选择文件后读取正文。GitHub 更新默认进入“变更对比”,首次导入和普通技能默认进入“技能内容”。对象存储读取失败时不得以空白预览判定内容合格。 +3. 在“来源与安全”核对许可证依据、扫描报告和发现项。区分执行失败、风险发现和分析器未配置。普通版本扫描未结束不能批准;许可证未识别或依据缺失时,须读取具体状态及证据,不能将其解释为许可已确认。 +4. 若有头像或可见范围变更,核对申请中的候选和目标;若为技能套装(Skill Suite),核对待审快照、入口技能及成员固定版本。快照未加载时批准不可用,成员获批不等于套装获批。套装定义与套装 Bundle 导入操作不是同一对象,见[技能套装](./skill-suites.html)。 +5. 在“审核记录”读取历史意见,完成证据检查后提交批准或拒绝。拒绝须写明具体文件、问题和修订条件;批准意见可选。切换页签保留意见,切换申请会清空意见和未确认弹窗。本版不提供“附条件批准”状态。 + +| 检查结果 | 处理依据 | 后续动作 | +| --- | --- | --- | +| 当前内容、目标及证据一致 | 已检查本次申请,且无待解决问题 | 批准后重新核对任务和对象结果 | +| 文件、证据或声明存在明确问题 | 记录可定位的问题及修订条件 | 拒绝,作者按意见修订 | +| 扫描、快照或文件未就绪 | 无法获得作决定所需证据 | 先排障或等待,不将缺失结果当作合格 | + +在线预览限制集中如下;超限不表示文件被删除,须按下载权限获取后核查。 + +| 项目 | 固定限制 | 超限表现 | +| --- | --- | --- | +| 逐行比较 | 文件超过64KiB或1000行 | 跳过逐行比较 | +| 当前正文在线加载 | 文件超过256KiB | 不在线加载正文 | +| 已删除旧文件的基线下载 | 文件超过1MiB | 审核页不能下载该旧文件 | + +这些是前端/接口实现限制,不由审核页面配置;依据[审核详情](https://github.com/iflytek/skillhub/blob/main/web/src/pages/dashboard/review-detail.tsx)及[审核接口](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/portal/ReviewController.java)。`GET /api/v1/reviews/{id}/skill-detail?includeDocumentation=false` 只读元数据及说明路径,不读取对象存储正文;缺省为 `true`。 + +### 核查合规声明 + +含 `x-astron-compliance` 的版本展示合规快照和新增、删除、修改差异;`complianceSnapshot.digest` 变化表示规范化声明变化。必须将声明与实际能力、控制项、证据路径和外部材料对应核查,不能只看标准名称。证据不可访问、内容不匹配或删除影响下游引用时,应先记录问题并要求修订。注册中心保存结构化声明和版本快照,不替作者认证实际合规;依据见[合规元数据](./skill-publish.html)。 ## 状态对象对照 -先识别对象;同名枚举不表示同一流程。任务为 `PENDING` 时,版本可能仍在 `SCANNING`;不得用它替代版本的 `PENDING_REVIEW`。 +任务 `PENDING` 时,版本可能仍为 `SCANNING`;不得用任务状态代替版本状态。以下四类对象分别读取。 ### 审核任务状态 -| 状态 | 判断依据 | 处理者 | 下一步 | -| --- | --- | --- | --- | -| `PENDING` | 任务等待审核决定 | 有权限的空间审核员或平台技能管理员 | 执行上方检查清单后决定 | -| `APPROVED` | 任务已批准 | 提交者 | 核对版本或资料生效结果 | -| `REJECTED` | 任务已拒绝并保留意见 | 提交者 | 修订后重提 | -| `SUPERSEDED` | 任务已被后续申请替代 | 提交者与审核员 | 查看当前申请,不处理旧任务 | +| 状态 | 含义 | 处理者与下一步 | +| --- | --- | --- | +| `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)。 +[任务枚举](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/ReviewTaskStatus.java)没有 `WITHDRAWN`。普通技能版本撤回删除待审任务并调整版本状态,不删除已发布旧版,也不撤销已批准的全局提升,见[撤回服务](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/ReviewService.java)。 ### 技能版本状态 -版本 `DRAFT` 不是创作 API 草稿对象。 +| 状态 | 含义 | 处理者与下一步 | +| --- | --- | --- | +| `DRAFT` | 版本草稿,不是创作 API 草稿对象 | 技能所有者完成准备 | +| `SCANNING` | 扫描运行中 | 扫描服务完成后继续流程 | +| `SCAN_FAILED` | 扫描执行失败 | 部署方及技能所有者排障后重试 | +| `UPLOADED` | 已上传,尚未发布 | 所有者确认发布或提交审核 | +| `PENDING_REVIEW` | 版本等待人工决定 | 有权审核人核对本次版本 | +| `PUBLISHED` | 已发布 | 使用者按可见范围访问,执行效果另验 | +| `REJECTED` | 未获批准 | 所有者修订并重提 | +| `YANKED` | 已撤下 | 使用者选择可安装替代版本 | -| 状态 | 判断依据 | 处理者 | 下一步 | -| --- | --- | --- | --- | -| `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)。 +依据:[版本枚举](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/SkillVersionStatus.java)。 ### 套装导入操作状态 -| 状态 | 判断依据 | 处理者 | 下一步 | -| --- | --- | --- | --- | -| `RUNNING` | 导入正在执行 | 导入服务 | 跟踪原操作,不重复确认 | -| `WAITING_FOR_MEMBERS` | 等待成员版本就绪 | 导入服务与成员审核员 | 查看成员进度 | -| `BLOCKED_RETRYABLE` | 存在可重试阻塞 | 导入者 | 排障后重试原操作 | -| `REPREVIEW_REQUIRED` | 原预览不能继续确认 | 导入者 | 重新预览并核对差异 | -| `SUITE_DRAFT_CREATED` | 已创建技能套装草稿 | 套装所有者 | 管理页继续发布,尚未批准 | -| `CANCELLED` | 操作已取消 | 导入者 | 核对成员动作,并非全部回滚 | +| 状态 | 含义 | 处理者与下一步 | +| --- | --- | --- | +| `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)。 +依据:[导入状态](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)。 ### 头像审核结果 -头像复用技能审核申请,但结果分三个字段维度。 +头像复用技能审核申请,但字段维度独立;机器阻止不等于人工已拒绝。 -| 字段与取值 | 判断依据 | 处理者 | 下一步 | +| 字段 | 取值与含义 | 处理者与下一步 | +| --- | --- | --- | +| 候选 `status` | `PENDING`待处理、`ACTIVE`使用中、`REJECTED`拒绝、`SUPERSEDED`替代、`REMOVED`移除 | 所有者及审核人核对候选与当前头像;响应名为 `candidateStatus` | +| `machineStatus` | `SKIPPED`跳过、`PENDING`待处理、`PROCESSING`执行中、`PASSED`允许、`BLOCKED`阻止、`ERROR`执行错误 | 机器服务处理;部署方排查 `ERROR` | +| `reviewStatus` | `NOT_REQUIRED`无需人工、`PENDING`待审、`APPROVED`批准、`REJECTED`拒绝、`APPEAL_PENDING`申诉待审 | 有权审核人及所有者按意见处理 | + +依据:[头像候选模型](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/SkillAvatarCandidate.java);配置与重试见[技能头像](./skill-avatars.html)。 + +## 完成标准与失败处理 + +普通版本批准后,任务为 `APPROVED`、目标版本为 `PUBLISHED`,再按目标身份访问验证。资料申请须核对资料实际生效,不能仅查看版本号。拒绝后,普通版本为 `REJECTED` 并有修订意见;作者在当前版本入口修订重提。审核批准不代表 Agent 执行成功或安全风险已消除。 + +| 现象 | 最可能原因 | 定位手段 | 处置 | | --- | --- | --- | --- | -| 候选 `status`:`PENDING`、`ACTIVE`、`REJECTED`、`SUPERSEDED`、`REMOVED` | 依次为待处理、正在使用、已拒绝、已替代、已移除 | 技能所有者与有权审核员 | 核对当前候选和使用中的头像 | -| `machineStatus`:`SKIPPED`、`PENDING`、`PROCESSING`、`PASSED`、`BLOCKED`、`ERROR` | 依次为跳过、待处理、执行中、机器允许、机器阻止、执行错误 | 机器审核服务与部署方 | `ERROR` 先排查服务;`BLOCKED` 不等同人工已拒绝 | -| `reviewStatus`:`NOT_REQUIRED`、`PENDING`、`APPROVED`、`REJECTED`、`APPEAL_PENDING` | 依次为无需人工、待审、已批准、已拒绝、申诉待审 | 有权审核员与技能所有者 | 读取意见及当前候选,按允许动作处理 | +| 列表存在但无法批准 | 自审、命名空间状态或身份不满足 | 核对提交者、角色及命名空间状态 | 交由符合条件者处理;不要切换请求绕过限制 | +| 批准按钮禁用 | 扫描或头像未就绪、套装快照加载失败 | 查看扫描、候选和快照错误 | 完成依赖或重试读取;不要以缺失结果代替合格证据 | +| 文件或说明为空 | 对象读取失败或超预览上限 | 查看文件大小及预览错误,按权限下载 | 补齐可读材料后再决定;不要直接批准空白预览 | +| 提交决定报状态冲突 | 任务已被处理或替代 | 刷新记录,核对任务ID及当前状态 | 以新状态为准;不要连续重复批准或拒绝 | -依据 [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)。 +## 全局撤销与治理边界 -## 审核入口 +删除已提升技能被阻止时,从来源技能详情的“提升到全局”区域申请撤销。平台技能管理员或超级管理员在 `/dashboard/promotions` 的“撤销待审核”处理;本人提交受上述自审限制。撤销记录为 `APPROVED` 后,须核对活动关联已解除,再按权限删除来源技能。隐藏、归档或撤回普通审核不替代撤销。 -角色与自审限制见本页末尾;举报、提升申请另行处理。 +无待审撤销申请时,有权平台操作者可在详情直接撤销并留存记录;存在待审申请则从队列处理。批准撤销会删除整条全局技能及其版本、评价和统计,来源技能保留;客户端文件无法收回,旧地址允许重新占用。若记录已批准而删除仍受阻,须核对是否再次提升,并记录对象ID、申请ID、部署版本与失败响应;不要直接修改数据库关系。流程见[撤销服务](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/PromotionRevocationService.java)。 -![审核对象及职责](/diagrams/review-concept.png) +举报入口为 `/dashboard/reports`,须按具体举报和现有治理权限处理;举报调查不自动批准或拒绝版本。审核任务撤回仅针对待审申请,历史意见与当前申请的可操作性须分别判断。 -![审核任务列表](/screenshots/review-list.png) +## 延伸阅读 -## 使用步骤 - -**审核技能包**: - -1. 访问 `/dashboard/reviews` -2. 查看待审核列表 -3. 点击技能包查看详情: - - 顶部核对技能名称、描述、状态、提交者和版本;GitHub 同步项显示独立的内容修订号、来源仓库与短 commit,完整安装用技术版本可在技术信息中查看。顶部的安全与许可证状态用于定位问题,点击后在“来源与安全”查看依据;没有结果、读取失败或许可证未识别都不能理解为通过 - - 在“技能内容”查看待审版本说明文档和文件树。说明文档在进入此页签后读取;选中单个文件后才读取其存储内容。如果存储对象已丢失,预览会提示失败 - - GitHub 更新项默认打开“变更对比”,逐文件核对新增、修改和删除;首次导入和普通技能默认打开“技能内容”。超过 64 KiB 或 1000 行时跳过逐行比较,超过 256 KiB 时不在线加载内容。当前版本文件可按原权限下载;已删除的旧文件还受基线接口 1 MiB 上限约束,超限时页面会说明无法从审核页下载 - - 在“来源与安全”核对固定 commit、许可证证据、完整扫描卡片和发现项;普通技能也可查看安全信息。扫描尚未完成时不能批准;GitHub 来源许可证依据缺失时按页面提示处理 - - 在“审核记录”查看提交历史和已完成的审核意见;该页签打开时才请求历史 - - 套件审核在内容区核对待审快照。快照加载失败时可重试,加载成功前“通过”按钮不可用 - -![普通发布路径中的扫描与审核](/diagrams/skill-publish-lifecycle-sketch.png) - -本页的审核部分对应 PUBLIC / NAMESPACE_ONLY 分支:扫描完成后,版本等待审核决定。 - -4. 在页面底部固定的审核栏填写意见并做出决策;切换页签保留意见,切换到另一个审核对象时清空意见、驳回表单和未确认弹窗: - - **批准**:技能包正式发布,开发者收到通知 - - **拒绝**:填写拒绝原因,开发者可修改后重新提交 - -5. 添加审核意见(可选) - -**审核合规声明**: - -如果待审核版本包含 `x-astron-compliance`,审核详情会展示版本级合规快照和差异摘要: - -- 新增声明:待审版本新增了标准、控制项或证据。 -- 删除声明:待审版本移除了上一发布版本已有的声明。 -- 修改声明:标准、控制项标题或证据发生变化。 -- 摘要变化:`complianceSnapshot.digest` 变化,表示规范化后的声明内容发生变化。 - -审核建议: - -1. 确认声明是否与技能实际能力相关。例如安全响应技能声明 MITRE ATT&CK 技术编号时,应能在说明或证据文件中看到对应依据。 -2. 点击差异项查看证据路径、外部链接和摘要,不只看声明标题。 -3. 对删除或大范围修改的声明提高审核优先级,因为这会影响下游审计系统引用。 -4. 如果证据缺失、路径不可访问、声明明显不匹配技能能力,建议拒绝并要求作者修正。 - -SkillHub 能保证的是结构正确、证据可追溯、版本快照不可变;不能替作者保证“真的合规”。 - -### 删除已提升到全局的技能 - -如果永久删除时提示「已提升的技能须通过审核撤销流程删除」,请从团队来源技能的详情页处理全局发布。隐藏、归档或撤回待审提交不会删除已经批准的全局技能;提交撤销申请也不代表撤销已完成。 - -1. 打开来源技能(例如 `@it/translate-document`),在「提升到全局」区域点击「申请撤销全局发布」,填写原因并确认。 -2. 请平台 `SKILL_ADMIN` 或 `SUPER_ADMIN` 访问 `/dashboard/promotions` 的「撤销待审核」页签,核对来源技能和全局技能后点击「批准撤销」。`SKILL_ADMIN` 不能审核自己提交的申请;`SUPER_ADMIN` 可以。 -3. 刷新来源技能详情,核对本次申请在「撤销记录」中显示「已撤销」(`APPROVED`)。「待审核」(`PENDING`)或「已拒绝」(`REJECTED`)表示该申请未完成撤销;活动全局关联仍存在时,普通删除仍会被阻止。历史申请的状态不能代替当前提升关系的检查。 -4. 撤销批准后,关联的 `@global/translate-document` 及其所有全局版本会被删除,团队来源技能保留。需要删除来源技能时,再使用该技能的「永久删除」,仍需具备删除权限。 - -尚无待审撤销申请时,平台 `SKILL_ADMIN` 或 `SUPER_ADMIN` 也可以在来源技能详情页使用「管理员直接撤销」,确认后立即完成全局撤销并保留撤销记录。已有待审申请时,详情页只显示待审提示,请通过上述「撤销待审核」入口处理。请先核对确认框:该操作会删除整条全局技能,包括独立上传的全局版本、评价和统计;已安装到客户端的文件无法收回,原地址以后可能被其他技能使用。 - -如果撤销记录已经是 `APPROVED`,刷新后仍提示同一错误,请记录来源/全局技能 ID、撤销申请 ID、当前部署版本或镜像标签,以及删除请求的响应和请求 ID。还需确认撤销后是否又进行了新的全局提升。若当前界面没有撤销入口,先核对部署版本和数据库迁移是否与对应版本一致,再由维护者检查;不要直接修改数据库中的提升关系来绕过流程。 - -**处理举报**: - -1. 访问 `/dashboard/reports` -2. 查看举报列表 -3. 调查举报内容 -4. 采取行动(归档技能包、警告用户等) - -## API 接口 - -**提交审核**: -```http -POST /api/v1/reviews -Content-Type: application/json - -{ - "skillVersionId": 123 -} -``` - -**批准审核**: -```http -POST /api/v1/reviews/{id}/approve -Content-Type: application/json - -{ - "comment": "Looks good! Approved." -} -``` - -**拒绝审核**: -```http -POST /api/v1/reviews/{id}/reject -Content-Type: application/json - -{ - "comment": "Please fix the documentation and add more examples." -} -``` - -**参数说明**: -| 参数 | 类型 | 说明 | -|------|------|------| -| id | number | 审核任务 ID(路径参数) | -| comment | string | 审核意见(批准时可选;拒绝时应填写明确原因) | - -**列出待审核任务**: -```http -GET /api/v1/reviews/pending?namespaceId=123&page=0&size=20 -``` - -**列出我的提交**: -```http -GET /api/v1/reviews/my-submissions?page=0&size=20 -``` - -**获取审核详情**: -```http -GET /api/v1/reviews/{id} -``` - -**获取审核中的技能包详情**: -```http -GET /api/v1/reviews/{id}/skill-detail -GET /api/v1/reviews/{id}/skill-detail?includeDocumentation=false -``` - -`includeDocumentation` 缺省为 `true`,保持原响应行为。设为 `false` 时仍返回技能、版本、文件元数据与说明文件路径,`documentationContent` 为空且不读取对象存储正文;审核详情首屏使用此模式,进入“技能内容”后再取正文。 - -**下载审核包**: -```http -GET /api/v1/reviews/{id}/download -``` - -**撤回审核**: -```http -POST /api/v1/reviews/{id}/withdraw -``` - -**举报技能包**: -```http -POST /api/v1/skills/{namespace}/{slug}/reports -Content-Type: application/json - -{ - "reason": "INAPPROPRIATE_CONTENT", - "details": "This skill contains malicious code" -} -``` - -## 注意事项 - -> **审核权限**:团队空间 Admin / Owner 可审核本空间;平台 SKILL_ADMIN / SUPER_ADMIN 具有平台审核权限。个人空间及本人提交的审核还受自审规则约束,不能仅凭“管理员”称呼判断。 - -- **审核时效**:建议在 24 小时内完成审核,避免阻塞开发者 -- **审核记录**:所有审核操作都会记录到审计日志 -- **合规审计**:合规声明以版本快照形式记录。审核通过或拒绝时,应结合差异摘要判断风险,但 Agent 执行 trace 不由 SkillHub 记录 -- **审核意见**:拒绝时建议提供详细的改进建议 -- **撤回限制**:只有待审核状态的技能包可以撤回 +- [发布与更新技能](./skill-publish.html):准备、提交与版本管理。 +- [安全扫描](./scanner.html):解读报告及定位执行失败。 +- [管理命名空间](./namespace.html):成员角色及命名空间状态。 diff --git a/docs/skillhub/guide/scanner.md b/docs/skillhub/guide/scanner.md index 980f483b9..3a1e5faa1 100644 --- a/docs/skillhub/guide/scanner.md +++ b/docs/skillhub/guide/scanner.md @@ -1,30 +1,87 @@ # 配置与查看安全扫描 -## 作者和审核员怎么查看 +本页说明技能作者、审核员如何判读版本扫描报告,以及部署方如何配置和诊断 Scanner。报告提供风险发现与执行证据,不代替人工审核,也不保证技能在 Agent 中的实际行为。头像机器审核属于另一条处理链路,参见[技能头像与审核](./skill-avatars.html)。 -发布后在技能详情或审核页查看本次版本的扫描状态、报告与发现项。先核对版本,再查看严重级别、受影响文件和说明;不能把旧版本报告用于新版本。 +## 前置条件与职责 -- `SCANNING`:尚未完成,普通提审版本不能据此批准。 -- `SCAN_FAILED`:执行失败,需要查看原因并重试,不等于判定有害。 -- 已完成且有发现项:根据风险与策略处理,不等于执行失败;人工审核仍需判断。 -- 未启用或没有报告:不是“零风险”。PRIVATE 路径可在禁用扫描时上传;普通 PUBLIC / NAMESPACE_ONLY 发布要求扫描启用。 - -### 部署方排查顺序 - -以下命令由有本实例容器或目标命名空间操作权限的部署方执行;普通技能作者提供版本与报告信息,不要把业务角色当作主机操作权限。先选择实际部署路径。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 配置与自定义健康路径须在实例受保护配置中核对。 +![扫描执行、报告判读与人工审核之间的关系](/diagrams/scan-result-flow.svg) - Compose: +*图:扫描任务产生报告;执行失败与风险发现分别处置,人工审核独立判断。* - ```bash +## 判读本次版本报告 + +1. 在技能详情或审核详情选择目标版本。先记录版本与扫描时间,避免将旧报告用于新内容。 +2. 检查 `failureReason` 和 `scannedAt`,区分任务未完成、执行失败和已生成结果。`SCAN_FAILED` 表示执行失败,不表示已认定内容有害。 +3. 对已完成报告,结合 `verdict`、`isSafe`、`maxSeverity` 和 `findings` 阅读机器结果;逐项核对文件位置、说明与修复措施,不能只查看发现数量。 +4. 作者修订问题后提交新版本;审核员依据本次内容与报告作出批准或拒绝决定。版本仍在 `SCANNING` 时不能按普通提审路径批准,具体流程见[审核技能与套装](./review.html)。 + +以下是报告字段的示例节选,不是真实实例结果;接口按技能和版本返回扫描报告列表。 + +```json +{ + "verdict": "DANGEROUS", + "isSafe": false, + "maxSeverity": "HIGH", + "findingsCount": 1, + "findings": [{ + "ruleId": "EXAMPLE_RULE", + "severity": "HIGH", + "filePath": "scripts/example.py", + "lineNumber": 12, + "message": "Example finding", + "remediation": "Review the indicated operation" + }], + "failureReason": null +} +``` + +| 机器结果 | 映射依据 | 处置依据 | 说明 | +| --- | --- | --- | --- | +| `SAFE` | Scanner 返回 `is_safe=true` | 仍须核对内容、依赖及适用场景 | 是机器判定,不是安全保证。 | +| `BLOCKED` | 非上述结果且最高级别为 `CRITICAL` | 重点核查发现项及危险操作 | 枚举名称不等于注册中心已自动拒绝审核。 | +| `DANGEROUS` | 非上述结果且最高级别为 `HIGH` | 核查风险证据与修订内容 | 不等于扫描执行失败。 | +| `SUSPICIOUS` | 其他非 `SAFE` 结果,包括级别缺失 | 阅读具体发现及报告完整性 | 不得因级别较低直接认定可发布。 | + +映射与字段依据:[Scanner 适配器](https://github.com/iflytek/skillhub/blob/main/server/skillhub-infra/src/main/java/com/iflytek/skillhub/infra/scanner/SkillScannerAdapter.java)、[报告接口](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/portal/SecurityAuditController.java)和[扫描状态处理](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/security/SecurityScanService.java)。 + +## 配置扫描与确认生效 + +下表是本页涉及的应用绑定。变量必须实际传入注册中心容器;仅在 `.env.release` 增加清单未引用的键不会生效。Compose 修改后重新创建注册中心;Kubernetes 更新覆盖配置并滚动受影响 Deployment。完整配置以[应用配置](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/resources/application.yml)及[Scanner 配置说明](https://github.com/iflytek/skillhub/blob/main/scanner/docs/configuration.md)为准。 + +| 配置项 | 应用默认与部署覆盖 | 影响 | 说明 | +| --- | --- | --- | --- | +| `SKILLHUB_SECURITY_SCANNER_ENABLED` | 应用、release Compose、Kustomize、Helm 为 `true`;运行脚本 `--no-scanner` 为 `false` | 关闭后拒绝普通新非私有上传 | 生效需重建或滚动。 | +| `SKILLHUB_SECURITY_SCANNER_URL` | 应用 `http://localhost:8000`;Compose `http://skill-scanner:8000`;Kustomize `http://skillhub-scanner:8000`;Helm 按 release 生成 | 注册中心访问 Scanner 的地址 | 生效需重建或滚动。 | +| `SKILLHUB_SECURITY_SCANNER_MODE` | 应用 `local`;Compose、Kustomize、Helm 覆盖为 `upload` | `local` 需双方共享相同目录路径;`upload` 传包 | 生效需重建或滚动。 | +| `SKILLHUB_SCANNER_POLICY_PRESET` | `balanced`;可选 `strict`、`permissive` | 传给 Scanner 的分析策略 | 显式透传并重建后生效。 | +| `SKILLHUB_SCANNER_FAIL_ON_SEVERITY` | 配置声明为 `high` | 当前适配器未将此字段传入扫描选项 | 不得将其视为已实现的自动发布阻断保障。 | +| `SKILLHUB_SCANNER_USE_BEHAVIORAL` / `SKILLHUB_SCANNER_USE_META` | `true` / `false` | 行为与元数据分析开关 | 显式透传并重建注册中心。 | +| `SKILLHUB_SCANNER_USE_AI_DEFENSE` / `SKILLHUB_SCANNER_USE_VIRUSTOTAL` | 均为 `false` | 可选外部检测引擎 | 除开关外须配置相应服务凭据;重建受影响服务。 | +| `SKILLHUB_SCANNER_USE_LLM` / `SKILLHUB_SCANNER_LLM_PROVIDER` | `false` / `anthropic`;提供方可选 `openai`、`azure` | 开启外部模型分析 | 注册中心重建;Scanner 侧另配 `SKILL_SCANNER_LLM_API_KEY`,可配 `SKILL_SCANNER_LLM_BASE_URL`、`SKILL_SCANNER_LLM_MODEL`;密钥变更后重建对应服务。 | + +策略选项依据[装配代码](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/SkillScannerConfig.java)与[扫描选项](https://github.com/iflytek/skillhub/blob/main/server/skillhub-infra/src/main/java/com/iflytek/skillhub/infra/scanner/ScanOptions.java)。LLM 分析可能向配置的外部服务发送内容并产生费用;启用前由部署方核对数据范围与服务条款,不公开密钥或完整环境输出。 + +扫描关闭时,普通公开(`PUBLIC`)和空间成员可见(`NAMESPACE_ONLY`)新上传返回 `error.security.scanner.required`。私有(`PRIVATE`)仍可上传,但停留在 `UPLOADED`,须另行确认发布。已发布私有技能扩大范围时,最新版本已有可复用报告(`taskId`、`scannedAt` 非空,`failureReason=null`、`isSafe=true`)可继续审核;否则扫描关闭时拒绝。依据[发布前置](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)。 + +## 诊断连接与任务 + +Compose 命令在含 `.env.release`、`compose.release.yml` 的运行目录执行。Kustomize 使用清单默认名称;Helm 名称按 [Chart README](https://github.com/iflytek/skillhub/blob/main/charts/skillhub/README.md)核对,不得混用。探测仅输出固定允许值;异常配置脱敏,包含凭据或非保守 URL 形态时跳过。缺失变量取应用默认值,额外 Spring 覆盖须在受保护配置中核对。 + +| 参数 | 值 | 影响范围 | 说明 | +| --- | --- | --- | --- | +| `wget -T` | 5秒 | 本次健康请求阶段超时 | 不修改扫描任务超时。 | +| `wget -t` | 1次 | 本次请求尝试次数 | 不触发扫描。 | + +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} @@ -53,9 +110,9 @@ ' ``` - Kustomize: +Kustomize: - ```bash +```bash kubectl -n skillhub exec deployment/skillhub-server -c server -- sh -c ' enabled=${SKILLHUB_SECURITY_SCANNER_ENABLED:-true} mode=${SKILLHUB_SECURITY_SCANNER_MODE:-local} @@ -84,10 +141,20 @@ ' ``` -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;不要用旧版本报告解释新版本。以下命令只读取本地日志,反馈前须脱敏,不能直接公开整份日志。 +标准结果如下;`health_exit=0` 仅表示健康端点可达。自定义地址显示 `custom_or_unrecognized_redacted`,不代表无效;普通自定义 HTTP(S)/IPv6 地址仍可探测。`skipped_*` 表示本次诊断跳过,不能据此判定产品配置有效或无效。 - ```bash +```text +# Compose + enabled=true mode=upload scanner_host=skill-scanner:8000 + health_exit=0 +# Kustomize + enabled=true mode=upload scanner_host=skillhub-scanner:8000 + health_exit=0 +``` + +随后以本版本的失败原因和时间关联日志;反馈前脱敏,不公开整份日志。 + +```bash # Compose,仍在本次运行目录 docker compose --env-file .env.release -f compose.release.yml logs --since=10m --tail=100 server skill-scanner # Kustomize,使用清单默认名称 @@ -95,119 +162,20 @@ kubectl -n skillhub logs deployment/skillhub-scanner -c scanner --since=10m --tail=100 ``` -4. 按下表处理后跟踪同一版本。临时不可达可进入重试/重领,持续失败也受实例重试与超时配置约束;不要仅凭等待时间断定“有害”,也不要重复上传来制造新版本。 +## 结果确认与失败处置 -| 现象 | 最可能原因 | 定位手段 | 检查与处理 | +已生成报告应能定位目标版本、扫描时间及具体发现;普通非私有版本扫描执行完成后进入 `PENDING_REVIEW`,私有版本进入 `UPLOADED`。已发布版本补扫不改变其发布状态。上述结果均不等于人工已批准。 + +| 现象 | 最可能原因 | 定位手段 | 处置 | | --- | --- | --- | --- | -| 非私有上传被拒绝,出现 `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 日志 | 区分执行失败与发现风险;仅在版本页提供重试且有操作权限时重试,不要把健康响应当作扫描完成或人工批准。 | +| 非私有上传返回 `error.security.scanner.required` | 扫描关闭 | 探测显示 `enabled=false` | 恢复服务与开关;不要修改数据库状态绕过检查。 | +| 标准部署显示 `local` 或 `localhost` | 透传缺失或覆盖不正确 | 对照本页配置表与容器输出 | 修正配置并重建;不要将容器 localhost 当作宿主机。 | +| `health_exit` 非零 | 服务未就绪或网络/地址错误 | 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` | 恢复连接后跟踪原任务;不要删除数据库或持久卷。 | +| 健康可达但版本仍扫描或失败 | 执行错误、超时或恢复重试超限 | 本版本 `failureReason` 与上述日志 | 仅在页面提供重试且有权限时重试;不要重复上传制造新版本。 | +| 报告非 `SAFE` 但任务已完成 | 扫描发现风险 | 核对 `findings` 与文件位置 | 修订或提交审核证据;不要把 `BLOCKED` 枚举当成自动拒绝记录。 | -诊断命令依据 [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 镜像中提供。 +诊断依据:[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`。 -## 功能描述 +## 边界与后续 -SkillHub 内置了 **Skill Scanner** 安全扫描服务,在技能包发布时自动检测潜在的安全风险。报告提供结构化发现与执行证据,不能据此承诺技能内容安全。 - -启用扫描的上传会经过安全扫描,扫描结果会影响审核决策,供有权限的审核员结合使用场景判断;扫描完成不等于人工批准。 - -**核心特性**: - -- **自动触发**:技能包发布后自动触发安全扫描,无需手动操作 -- **多引擎分析**:支持行为分析、LLM 分析、元数据分析等多种引擎 -- **策略可配**:内置 balanced 策略预设,支持自定义扫描策略 -- **严重级别阈值**:可配置在哪个严重级别自动阻止发布 -- **扫描报告**:详细的扫描结果展示在技能包详情页 - -**分析引擎**: - -| 引擎 | 说明 | 默认状态 | -|------|------|----------| -| **元数据分析** | 元数据相关分析(不替代上传结构校验) | 默认关闭 | -| **行为分析** | 分析代码行为模式,检测恶意操作 | 默认启用 | -| **LLM 分析** | 使用大模型分析代码安全性 | 可选 | -| **AI Defense** | Cisco AI Defense 集成 | 可选 | -| **VirusTotal** | VirusTotal 病毒扫描 | 可选 | - -## 使用场景 - -**场景一:发布时自动扫描** - -开发者发布技能包后,Scanner 自动在后台运行扫描,无需额外操作。 - -**场景二:管理员查看扫描报告** - -管理员在审核技能包时,可以查看扫描报告,帮助做出审核决策。 - -**场景三:自定义扫描策略** - -企业管理员可以根据安全需求,配置扫描策略和严重级别阈值。 - -## 工作流程 - -``` -开发者发布技能包 - ↓ -SkillHub 后端接收上传 - ↓ -触发安全扫描(通过 Redis Stream) - ↓ -Skill Scanner 执行多引擎分析 - ↓ -扫描结果写入数据库 - ↓ -技能包详情页展示扫描报告 - ↓ -管理员结合扫描结果进行审核 -``` - -## 配置说明 - -### 基础配置 - -下表列出本页排查所需的基本应用绑定;完整字段见表后的应用配置来源。环境变量必须实际传入 Server;仅在 `.env.release` 增加未被 Compose 引用的键不会生效。修改后重新创建 Server 容器;Kubernetes 须更新对应覆盖配置并滚动受影响 Deployment。 - -| 配置项 | 用途 | 应用默认与部署覆盖 | 检查与处理 | -| --- | --- | --- | --- | -| `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 分析配置(可选) - -启用 LLM 分析引擎可以提高安全检测的准确性: - -| 环境变量 | 说明 | 默认值 | -|----------|------|--------| -| `SKILLHUB_SCANNER_USE_LLM` | 启用 LLM 分析 | `false` | -| `SKILLHUB_SCANNER_LLM_PROVIDER` | LLM 提供商(anthropic / openai / azure) | `anthropic` | -| `SKILL_SCANNER_LLM_API_KEY` | LLM API 密钥 | - | -| `SKILL_SCANNER_LLM_BASE_URL` | 本地/自定义 LLM 服务地址 | - | -| `SKILL_SCANNER_LLM_MODEL` | LLM 模型名称 | - | - -### 部署说明 - -使用运行脚本部署时,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 是执行失败;扫描发现风险与执行失败须分别处理。扫描通过也不等于人工审核通过。 - -- **扫描耗时**:根据技能包大小和启用的引擎数量,扫描可能需要几秒到几分钟 -- **LLM 分析成本**:启用 LLM 分析会产生 API 调用费用,建议在生产环境中评估成本 -- **策略调优**:`balanced` 策略适合大多数场景,企业可以根据安全需求自定义策略 -- **健康检查**:使用上方[部署方排查顺序](#部署方排查顺序)从注册中心容器访问已配置的 Scanner;不要把宿主机或 Server 的 localhost 当作 Scanner 地址。 +扫描执行时长由包内容、分析引擎和外部依赖决定,本页不承诺固定完成时间。风险发现、执行失败、人工拒绝是不同结果;[审核实现](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/ReviewService.java)当前不会仅凭最高严重级别自动替代人工审核。完成本步骤后,作者在[发布与更新](./skill-publish.html)跟踪版本,审核员在[审核](./review.html)处理申请;部署方排障不得改写版本或审核记录。 diff --git a/docs/skillhub/guide/skill-avatars.md b/docs/skillhub/guide/skill-avatars.md index e1f50ddfc..a3fe86729 100644 --- a/docs/skillhub/guide/skill-avatars.md +++ b/docs/skillhub/guide/skill-avatars.md @@ -1,151 +1,80 @@ -# 技能头像:上传、审核与供应商配置 +# 技能头像与审核 -本页介绍如何上传技能头像,以及部署方如何接入讯飞或阿里云图片审核。这是**技能头像**功能,不涉及用户个人头像;图片审核与技能包安全扫描是两种不同的检查。 +本页说明技能所有者如何提交头像,以及有权审核人如何处理头像申请。技能头像不包含用户个人头像;图片审核与技能包安全扫描是独立检查。供应商开通、凭据和容器更新由部署方负责,见[配置头像机器审核服务](./avatar-moderation-configuration.html)。 -## 技能所有者怎么使用 +## 前置条件与职责 -1. 新增技能时,在发布页选择自定义 PNG/JPEG;已有技能从「我的技能 → 更新」进入,也可只改头像而不发布新版本。 -2. 在裁剪弹窗调整方形区域和缩放,确认后等待上传成功。图片上传中或失败时不能提交;未选择头像也可正常提交,显示技能名首字母。 -3. 提交后,在「我的技能」或更新页查看**本次提交的图片**及审核状态。审核通过前,其他人继续看到旧头像或首字母。 -4. 被拒绝后查看原因,修改图片再提交。新申请会替换旧待审申请,旧审核结果不会覆盖新头像。 +操作前须登录同一注册中心,确认目标技能及当前账号。技能所有者维护头像,命名空间角色或平台角色不自动获得代传权限。 -上传输入限 PNG/JPEG、2 MB、正方形且边长不超过 1024 像素;服务器会再次校验并重新编码为 PNG。上传成功仅表示图片已存入私有存储,不代表审核通过。临时上传引用 24 小时后过期,过期需要重新上传。 - -更新默认保留原头像,也可移除:单改头像提交成功后恢复首字母;与新技能包一起提交时,审核通过后才移除。取消编辑或提交失败不改变现有头像。技能详情和列表展示当前生效头像,不设单独的头像管理入口。 - -## 管理员怎么审核 - -头像与技能包同时提交时,共用一张技能申请,审核员在原审核详情中对内容和头像一次批准或拒绝。只改头像且需要人工决定时,也进入这个技能审核队列,标明「头像修改」,不创建新技能版本。 - -团队管理员审核本团队;平台技能管理员和超级管理员可审核团队及全局,自审权限沿用原技能审核规则。管理员可撤下头像,但不能替所有者上传新头像。 - -### 两个开关与四种流程 - -超级管理员在「系统配置」(`/dashboard/admin/system-config`)中选择「启用机器审核」与「启用人工审核」。默认机器关闭、人工开启。后台只管理这两个开关,不配置供应商、不显示密钥。 - -| 机器审核 | 人工审核 | 非 PRIVATE 技能单改头像的流程 | +| 操作 | 执行主体 | 入口与边界 | | --- | --- | --- | -| 关闭 | 关闭 | 提交成功后直接生效 | +| 新增、替换或移除头像 | 技能所有者 | 发布页或“我的技能 → 更新”;可只改头像而不创建版本 | +| 审核头像申请 | 对目标命名空间有审核权限的账号 | 原技能审核队列;头像与内容同次提交时共同决定 | +| 调整机器、人工审核开关 | 超级管理员(SUPER_ADMIN) | `/dashboard/admin/system-config`;不在此填写凭据或切换供应商 | +| 接入或切换供应商 | 具有部署权限的操作者 | 在部署配置中选择供应商并注入私有凭据 | + +团队命名空间所有者(Owner)及空间管理员(Admin)审核本命名空间;平台技能管理员(SKILL_ADMIN)和超级管理员可审核团队及全局。自审限制沿用[技能审核规则](./review.html),不得从平台角色推导全部自审权限。有权操作者可撤下头像,但不能代替所有者上传。 + +## 提交与更新头像 + +1. 在发布或更新表单选择自定义 PNG/JPEG,在裁剪弹窗调整方形区域与缩放。未选择图片时可正常提交,使用技能名首字母。 +2. 确认裁剪并等待上传结束。上传中或失败时不能提交;服务器会重新校验图片并编码为 PNG。上传成功只表示已存入私有存储,不代表审核已批准。 +3. 提交后,在“我的技能”或更新页核对本次候选图片及机器、人工状态。候选未生效时,公开详情和列表继续显示旧头像或首字母;不能据此认定提交丢失。 +4. 被拒绝后读取原因、修订图片并重新提交。新申请替换旧待审申请,旧审核结果不能覆盖新候选;申请记录继续留存。 + +更新默认保留原头像。单改头像的移除请求提交成功后恢复首字母;移除与新技能包同次提交时,须等待该申请获批。取消编辑或提交失败不改变现有头像,不设单独的头像管理入口。 + +## 审核策略与申请关系 + +头像与技能包同次提交时,共用一张技能申请,由审核人在原详情中一次批准或拒绝;头像不会提前发布。只改头像且需要人工决定时,同样进入技能审核队列,标记“头像修改”,不创建新技能版本。 + +超级管理员在系统配置中分别管理两个开关,默认机器关闭、人工开启。后台不配置供应商或显示密钥。下表适用于非私有技能的单改头像申请。 + +| 机器审核 | 人工审核 | 生效条件 | +| --- | --- | --- | +| 关闭 | 关闭 | 提交成功后生效 | | 关闭 | 开启 | 人工批准后生效 | -| 开启 | 关闭 | 机器通过后自动生效;阻止或异常时不生效 | -| 开启 | 开启 | 先机器审核,再由人工决定 | +| 开启 | 关闭 | 机器允许后生效;阻止或异常不生效 | +| 开启 | 开启 | 先完成机器审核,再由人工决定 | -**边界:**`PRIVATE` 技能头像仅所有者可读,直接使用,不运行上述机器或人工审核;扩大可见范围时需要按目标范围重新审核。头像与技能包同次提交时,不论头像开关如何,仍须等待原技能审核共同批准,不会提前发布头像。 +私有(PRIVATE)技能头像仅所有者可读,直接使用,不运行上述机器或人工审核;扩大可见范围时按目标范围重新审核。头像与技能包共同提交时,无论头像开关如何,均须等待原技能申请的批准。 -### 违规会直接失败吗? +## 机器结果与人工决定 -机器结果与申请最终决定不同: +| 机器结果 | 候选与公开头像 | 后续处理 | +| --- | --- | --- | +| `PASSED` | 有人工审核时仍待审;无人工审核时单改头像生效 | 审核人核对候选和目标申请,不能把机器允许作为内容效果保证 | +| `BLOCKED` | 新图片保持私有,旧头像继续使用 | 有人工审核时可拒绝;认为误判而批准须填写明确理由;无人工审核时所有者可申请人工复核 | +| `ERROR` | 新图片保持私有,不能直接批准 | 部署方排查配置、网络或供应商服务,恢复后重试 | -| 结果 | 处理 | -| --- | --- | -| `PASSED`(通过) | 有人工审核时继续待审;没有人工审核时单改头像自动生效 | -| `BLOCKED`(阻止) | 新图片保持私有、旧头像继续使用。开启人工审核时继续待审,审核员可拒绝;认为误判时必须填写明确理由才能批准。未开启人工审核时不生效,所有者可申请人工复核 | -| `ERROR`(异常) | 新图片保持私有,不能直接批准放行;先排查配置、网络或供应商服务,再重试 | +机器阻止不等于文件上传失败,也不等于人工已拒绝。人工拒绝后,所有者可查看候选与原因;人工批准后须核对当前生效头像,不能仅凭任务文字判断最终图片。 -因此,**机器判违规不等于文件上传失败,也不等于人工已拒绝申请**。人工拒绝后,所有者可查看提交图片与拒绝原因。异常自动重试有一小时冷却,同一候选最多自动调用三次(含首次);耗尽后可在冷却结束后主动重试或重新提交。 +## 输入、重试与保留规则 + +| 项目 | 固定值或范围 | 生效与限制 | +| --- | --- | --- | +| 上传图片 | PNG/JPEG;不超过2MiB;正方形,边长不超过1024像素 | 上传时由服务器校验并重编码;越界提交被拒绝 | +| 临时上传引用 | 24小时 | 过期须重新上传,不等于已提交候选的保留期 | +| 机器异常冷却 | 1小时 | 错误结果后等待冷却;不得通过重复请求跳过 | +| 自动调用上限 | 同一候选共3次,含首次 | 耗尽后在冷却结束后主动重试或重新提交 | +| 已丢弃候选图片 | 被拒绝、替换或移除后私有保留30天 | 到期由清理任务删除图片,文字记录继续保留;不承诺精确到期时刻 | + +申请保留提交时的机器、人工开关和供应商快照,后续改开关不会回写已有申请。已完成的机器结果不自动重跑;供应商变更后,旧候选仍需旧供应商时可能为 `ERROR`,须由部署方与审核人协调处理,或重新提交新申请。 + +规则依据:[上传与引用](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillAvatarUploadService.java)、[图片校验](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillAvatarImageProcessor.java)、[候选状态](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/SkillAvatarCandidate.java)及[头像流程](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillAvatarAppService.java)。 ## 部署方如何接入机器审核 -### 1. 选择一个供应商 +每个部署选择一个供应商,凭据在服务启动时读取;后台只能管理审核开关,不能通过保存开关验证云账号权限、网络或额度。接入、轮换与切换由部署方按[配置头像机器审核服务](./avatar-moderation-configuration.html)执行,并使用新申请验证实际调用。 -每个服务部署只选择一个:`xfyun` 或 `aliyun`。供应商及凭证在应用启动时读取;后台仅能启停审核,不能切换供应商。不开启机器审核时无需提供云审核凭证。 +## 完成标准与失败处置 -| 供应商 | 需要开通的服务 | 所需凭证 | -| --- | --- | --- | -| 讯飞 | 图片合规审核 | APPID、APIKey、APISecret | -| 阿里云 | 内容安全增强版,上海地域的头像图片检测 `profilePhotoCheck` | RAM 用户的 AccessKey ID、AccessKey Secret | +所有者应能在更新页看到本次提交的图片及状态;需要审核的申请应在原技能队列可定位;批准后,公开详情显示本次生效头像。上传完成、机器允许、人工批准和公开头像切换是不同完成标志。 -服务开通、额度及计费以供应商控制台为准;开启后真实调用可能产生费用。 - -- 讯飞:[官方图片合规服务接入与鉴权说明](https://www.xfyun.cn/doc/nlp/ImageModeration/API.html)。注意 APIKey 对应 `access-key-id`,APISecret 对应 `access-key-secret`。 -- 阿里云:[内容安全控制台](https://yundun.console.aliyun.com/?p=cts)、[开通服务与创建 RAM 用户的官方接入步骤](https://help.aliyun.com/zh/document_detail/467828.html)。按最小权限配置 `yundun-greenweb:DescribeUploadToken` 和 `yundun-greenweb:ImageModeration`,不需要给审核用户自有 OSS 全权限。 - -阿里云适配器通过官方临时上传令牌上传私有图片,再调用同步审核,**无需自建审核用 OSS Bucket**。它与 SkillHub 自己保存技能和头像的对象存储配置相互独立。当前将 `RiskLevel=none/low` 视为通过,`medium/high` 视为阻止,其中 `medium` 转人工复核是 SkillHub 的策略。空结果、未知值及接口失败均不放行。参考[官方接口说明](https://help.aliyun.com/document_detail/467829.html)。 - -### 2. 用私有环境文件提供凭证 - -下面使用仓库标准 `compose.release.yml` 的 `server` 服务。先按现有部署流程准备 `.env.release`、数据库及 SkillHub 对象存储,选用包含本功能的镜像版本。本节不会替换原部署设置。 - -在**仓库外**建立私有目录,将下面路径中的 `/etc/skillhub/private` 换成实际路径;目录权限建议 `700`,文件权限 `600`。不要把凭证文件提交到 Git。 - -标准 Compose 只透传它声明的环境变量;仅向 `.env.release` 添加新审核属性不会自动注入 `server`。以下通过额外 override 的 `env_file` 显式注入,原 Compose 模板没有内置这些凭证字段。 - -创建 `/etc/skillhub/private/avatar-moderation.env`,以下两种内容**二选一**。占位符需替换为实际凭证;`SPRING_APPLICATION_JSON` 必须是单行合法 JSON。 - -**讯飞:** - -```dotenv -SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"xfyun","xfyun":{"app-id":"YOUR_APPID","access-key-id":"YOUR_APIKEY","access-key-secret":"YOUR_APISECRET"}}}}} -``` - -**阿里云:** - -```dotenv -SPRING_APPLICATION_JSON={"skillhub":{"avatar":{"moderation":{"provider":"aliyun","aliyun":{"access-key-id":"YOUR_ACCESS_KEY_ID","access-key-secret":"YOUR_ACCESS_KEY_SECRET"}}}}} -``` - -如果部署已有 `SPRING_APPLICATION_JSON`,**将上述 `skillhub.avatar.moderation` 合并进原 JSON,不要覆盖原配置或设置重复变量**;其他 override 若通过 `environment` 定义同名变量,会优先于 `env_file`,也需同步合并。特殊字符应按 JSON 格式转义。 - -在同一私有目录创建 `compose.avatar.yml`: - -```yaml -services: - server: - env_file: - - /etc/skillhub/private/avatar-moderation.env -``` - -然后在仓库根目录执行。已有部署若使用额外 Compose 文件、`-p` 项目名或其他启动参数,保留这些参数,再追加头像 override,确保更新原服务: - -```bash -make validate-release-config -docker compose --env-file .env.release \ - -f compose.release.yml \ - -f /etc/skillhub/private/compose.avatar.yml \ - up -d --no-deps server - -docker compose --env-file .env.release \ - -f compose.release.yml \ - -f /etc/skillhub/private/compose.avatar.yml \ - ps server -``` - -上述更新命令适用于已运行的完整栈。首次部署完整栈时,将 `up -d --no-deps server` 改为 `up -d`。只执行 `restart` 不会重新加载修改后的容器环境,配置更新需要重新创建服务。后续更新也要保留同一 override。 - -正式 Spring 属性是 `skillhub.avatar.moderation.provider`、`skillhub.avatar.moderation.xfyun.app-id`、`skillhub.avatar.moderation.xfyun.access-key-id`、`skillhub.avatar.moderation.xfyun.access-key-secret`,以及 `skillhub.avatar.moderation.aliyun.access-key-id`、`skillhub.avatar.moderation.aliyun.access-key-secret`。其他部署平台可通过 Secret 注入同等属性。 - -::: warning 讯飞出口日志 -讯飞官方接口将 `accessKeySecret` 放在请求 URL 参数中。应用不记录完整 URL 或异常原文,但部署方仍需关闭 HTTP 客户端调试日志,并确保出口代理、链路追踪及第三方日志不采集该请求 URL。不要把含凭证的 Compose 展开结果、容器环境或签名请求 URL 分享给其他人。 -::: - -### 3. 在后台开启,并验证真实调用 - -1. 确认 `server` 健康后,以超级管理员进入「系统配置」。 -2. 开启机器审核,建议初次接入时保留人工审核开启。 -3. 用技能所有者账号对一个非 `PRIVATE` 测试技能提交**新头像**。 -4. 在更新页查看机器结果;开启人工时,审核员在技能审核详情中确认图片、机器状态并做出决定。 -5. 对通过、阻止、异常分别检查:通过前旧公开头像不变,阻止或异常的新图片不可公开,人工拒绝后可见原因。不要为了测试把违规图片批准公开。 - -填写凭证、成功保存开关或应用健康,**都不能证明云服务调用成功**。后台检查的是配置是否齐全,真正的服务权限、网络、余额和接口响应必须通过新申请验证。已有申请不因开关开启而补跑机器审核。 - -供应商接口的代码与模拟测试不能替代本部署的账号验收。每次启用或轮换后都应验证实际账号的连通性、结果映射和失败行为。 - -## 修改开关与切换供应商 - -申请保存提交时的机器、人工开关和供应商快照,之后改配置不会回写已有申请。若要切换供应商,应更新私有配置并重新创建 `server`,再提交新申请: - -- 已完成的机器结果不会自动重新检测。 -- 旧候选仍需调用旧供应商时,切换后会得到 `ERROR`,不会偷偷改用新供应商;应重新提交以采用新供应商。 -- 配置切换前先处理待审申请,避免把旧任务留在不可继续审核的状态。 - -被拒绝、替换或删除的候选图片私有保留 30 天后清理,文字审核记录继续保留。云审核服务自己的临时图片生命周期与 SkillHub 私有保留规则不同。 - -## 常见问题 - -**开启失败提示供应商不可用?** 检查 `provider` 拼写、所选供应商凭证是否齐全,以及额外 override 是否实际用于启动 `server`。不要通过输出完整环境变量排查密钥。 - -**上传成功但一直异常?** 检查服务器能否访问对应云接口、凭证权限、服务是否开通及可用额度;阿里云还需要能访问其临时 OSS 上传端点。等待冷却后重试,不要把异常当通过。 - -**人工开关关闭就不审核技能包了吗?** 不是。这个开关只控制头像的人工策略,不改变原技能包审核流程。 - -**为什么其他人仍看到旧头像?** 新申请未通过时这是正常行为;所有者应到「我的技能」或更新页查看提交图片,公开详情只展示当前生效头像。 +| 现象 | 最可能原因 | 定位手段 | 处置 | +| --- | --- | --- | --- | +| 无法提交头像 | 上传失败、格式越界或引用过期 | 查看上传错误,核对本页输入规则和引用时间 | 重新裁剪上传;不要仅修改文件扩展名规避校验 | +| 公开详情仍是旧图片 | 新候选仍待审或未生效 | 在“我的技能”或更新页比较候选和机器、人工状态 | 跟踪当前申请;不要反复提交相同图片代替查询 | +| 机器结果持续异常 | 配置、依赖或供应商故障 | 更新页读取 `ERROR` 和可重试时间,由部署方核对服务配置 | 故障恢复并过冷却后重试;不要将异常批准放行 | +| 关闭人工后技能包仍待审 | 头像开关不控制技能包审核 | 核对是否同时提交技能包及该申请状态 | 按原技能审核完成内容决定;不要修改数据库强制发布 | +| 认为机器误判但无法生效 | 候选被阻止,需要人工复核或明确理由 | 核对 `BLOCKED`、人工开关和当前复核状态 | 所有者发起复核,有权审核人依据证据处理;不要通过换账号绕过审核 | diff --git a/docs/skillhub/guide/skill-discovery.md b/docs/skillhub/guide/skill-discovery.md index bac4eb332..82186b400 100644 --- a/docs/skillhub/guide/skill-discovery.md +++ b/docs/skillhub/guide/skill-discovery.md @@ -4,7 +4,7 @@ ## 开始前 -公开技能可匿名浏览。查找团队或私有资源时先登录正确实例,并确认拥有对应命名空间权限。准备 CLI 和 Agent 的步骤见[快速开始](../quickstart.md)。以下路径相对于实际部署地址,不固定开发端口。 +公开(PUBLIC)技能可匿名浏览;检索空间成员可见(NAMESPACE_ONLY)技能时,须登录正确实例并具备对应成员资格。普通市场搜索不收录私有(PRIVATE)技能,所有者须从“我的技能”查看和管理,不应通过反复修改关键词排查私有技能。搜索边界见[全文搜索查询](https://github.com/iflytek/skillhub/blob/main/server/skillhub-search/src/main/java/com/iflytek/skillhub/search/postgres/PostgresFullTextQueryService.java)。准备 CLI 和 Agent 的步骤见[快速开始](../quickstart.md)。以下路径相对于实际部署地址,不固定开发端口。 ## 在网页查找 diff --git a/docs/skillhub/guide/social.md b/docs/skillhub/guide/social.md index ec3fbf9ee..33667ad44 100644 --- a/docs/skillhub/guide/social.md +++ b/docs/skillhub/guide/social.md @@ -1,183 +1,89 @@ # 收藏、评分与通知 -## 功能描述 +本页说明已登录账号如何保存技能、提交使用反馈,以及管理站内通知。收藏、评分、订阅和通知互不替代;它们均不授予资源访问权限,也不执行技能。本页不说明平台审核操作或部署方邮件配置。 -SkillHub 提供了丰富的社交功能,让团队成员可以互动、分享、推荐技能包。 +## 前置条件与对象区别 -![概念图](/diagrams/social-concept.png) +操作前,在同一注册中心核对当前账号及目标技能。收藏与评分要求有权访问技能;新增或修改文字评价还要求技能处于正常状态且有已发布版本。技能后续隐藏或权限变化,可能使原入口不可访问。 -**核心功能**: +| 操作 | 保存的内容 | 适用目的 | 说明 | +| --- | --- | --- | --- | +| 收藏 | 当前账号与技能的收藏关系 | 在“我的收藏”重新定位技能 | 不安装技能,也不自动订阅更新。 | +| 评分与评价 | 当前账号对技能的星级与可选文字 | 记录使用反馈 | 文字评价不是发布审核意见。 | +| 订阅 | 当前账号与技能的更新订阅关系 | 接收符合投递条件的版本事件 | 收藏状态不代表已订阅。 | +| 通知 | 发送给当前账号的事件记录 | 跟踪发布、审核、提升或举报 | 已读不代表关联业务已处理。 | -- **星标(Star)**:收藏喜欢的技能包,方便后续查找 -- **评分(Rating)**:给技能包打分(1-5 星),帮助其他人判断质量 -- **下载统计**:记录下载次数,展示热门技能包 -- **通知系统**:及时接收审核、成员及治理等事件通知 +权限依据:[收藏与评分入口](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillSocialAppService.java)、[文字评价规则](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillReviewAppService.java)。 -**社交数据**: +## 收藏与提交使用反馈 -| 指标 | 说明 | -|------|------| -| **星标数** | 有多少人收藏了这个技能包 | -| **平均评分** | 所有用户评分的平均值 | -| **下载量** | 累计下载次数 | -| **更新时间** | 当前列表显示的更新时间 | +1. 在技能详情执行收藏操作,等待请求结束并核对按钮状态;进入 `/dashboard/stars` 确认记录。再次取消收藏仅删除关系,不删除本地安装文件。需要筛选时,在搜索页启用“仅收藏”。 +2. 在详情选择星级并等待提交结束,再核对个人评分。悬停预览不代表已保存;每个账号对同一技能只有一条评分,后续操作修改原评分,当前没有删除星级的接口。 +3. 需要文字反馈时,使用“写评价”,提交星级与文字。公开列表展示可见评价;个人可以修改或清空自己的文字。清空文字保留星级,即使技能之后取消发布,仍可清空已有文字。 +4. 被平台技能管理员(SKILL_ADMIN)或超级管理员(SUPER_ADMIN)隐藏的评价,在作者编辑后仍保持隐藏;恢复公开须由具有相应权限的平台角色操作。评分均值和下载量仅供选择参考,不能作为实际执行效果的证明。 -## 使用场景 +以下为响应字段示例,技能 ID 必须替换为实例中的真实数值,不能直接复制 `{skillId}` 发起请求。 -**场景一:收藏常用技能包** - -开发者发现一个好用的技能包,点击星标收藏。 - -![操作截图](/screenshots/skill-detail-star.png) - -**场景二:评分推荐** - -使用技能包后,给出评分和评价,帮助团队其他成员。 - -**场景三:查看通知** - -收到审核通过的通知,或其他受支持的治理事件通知。 - -![操作截图](/screenshots/notifications.png) - -**场景四:浏览热门** - -查看星标数最多、评分最高的技能包,学习最佳实践。 - -## 使用步骤 - -**星标技能包**: - -1. 访问技能包详情页 -2. 点击「Star」按钮 -3. 技能包会出现在「我的收藏」列表中 -4. 再次点击可以取消星标 - -**评分技能包**: - -1. 访问技能包详情页 -2. 点击星星图标选择评分(1-5 星) -3. 评分会立即生效,影响技能包的平均评分 -4. 可以随时修改评分 - -**撰写评价**: - -1. 在已发布技能的详情页点击「写评价」 -2. 选择 1-5 星并填写最多 2000 字的评价 -3. 可以修改或清空评价;清空评价不会删除星级评分,即使技能之后取消发布也仍可清空自己的文字 -4. 被管理员隐藏的评价在重新编辑后仍保持隐藏,只有技能管理员或超级管理员可以恢复公开 - -**查看通知**: - -1. 点击顶部导航栏的通知图标 -2. 查看未读通知列表 -3. 点击通知跳转到相关页面 -4. 标记为已读或全部已读 - -通知列表和未读数每 10 秒通过普通 HTTP 请求刷新,并在窗口重新获得焦点时立即刷新。旧版 -`GET /api/v1/notifications/sse` 接口已移除;自建客户端应改为轮询 -`GET /api/v1/notifications` 和 `GET /api/v1/notifications/unread-count`。 - -**查看我的收藏**: - -1. 访问 `/dashboard/stars` -2. 查看所有星标的技能包 -3. 分页浏览收藏列表;需要筛选时到搜索页启用“仅收藏” -4. 快速访问常用技能包 - -## 操作前确认身份 - -收藏、评分和通知属于当前登录账号。匿名点击收藏或评分会触发登录提示;切换账号后请重新检查状态。收藏不会安装技能,取消收藏不会删除本地安装。评分按钮在请求期间禁用,提交成功后才刷新自己的评分及技能数据,悬停预览星数不代表保存成功。 - -## 管理通知而不遗漏处理 - -打开 `/notifications`,按全部、发布、审核、提升或举报分类查看,每页最多 20 条。点击未读项会标记已读并跳转到关联对象;通知本身不是执行审核批准的按钮,仍需在目标页面完成操作。 - -可以将通知全部标为已读;删除按钮仅用于已读通知。若希望减少提醒,打开 `/settings/notifications`,按分类调整站内通知开关。当前表单配置的是 `IN_APP`,不是邮件或短信订阅;没有保存偏好时默认开启。 - -## 确认结果与排查 - -| 操作或现象 | 可观察结果 / 下一步 | -| --- | --- | -| 收藏成功 | 按钮切换为已收藏,随后在“我的收藏”确认 | -| 修改星级 | 等待请求完成,核对“你的评分”;不要把悬停效果当成提交 | -| 清空评价 | 文字被清除,原有星级仍保留;这是不同于取消收藏的操作 | -| 自己能看到评价,公开列表没有 | 检查是否被隐藏;作者编辑不会自动恢复公开 | -| 通知仍显示旧未读数 | 等待轮询或重新聚焦窗口;仍异常时检查请求和登录状态 | -| 通知目标不可访问 | 重新核对资源当前状态和权限;历史通知不会恢复已失去的访问权 | - -## API 接口 - -**星标技能包**: -```bash -PUT /api/v1/skills/{skillId}/star -``` - -**取消星标**: -```bash -DELETE /api/v1/skills/{skillId}/star -``` - -**检查星标状态**: -```bash +```http GET /api/v1/skills/{skillId}/star -``` - - -**评分技能包**: -```bash -PUT /api/v1/skills/{skillId}/rating -Content-Type: application/json - -{ - "score": 5 -} -``` - -**参数说明**: -| 参数 | 类型 | 说明 | -|------|------|------| -| skillId | number | 技能包 ID(路径参数) | -| score | number | 评分(1-5,必需) | - -**获取我的星标**: -```bash -GET /api/v1/me/stars?page=0&size=20 -``` - -**获取我的评分**: -```bash GET /api/v1/skills/{skillId}/rating ``` -**评价接口**: - -```bash -# 公开评价列表 -GET /api/v1/skills/{skillId}/reviews?page=0&size=20 - -# 查看、创建或修改自己的评价 -GET /api/v1/skills/{skillId}/reviews/me -PUT /api/v1/skills/{skillId}/reviews/me - -# 清空评价文字并保留星级评分 -DELETE /api/v1/skills/{skillId}/reviews/me - -# 技能管理员或超级管理员隐藏、恢复评价 -POST /api/v1/admin/skill-reviews/{reviewId}/hide -POST /api/v1/admin/skill-reviews/{reviewId}/restore +```json +{"data": {"score": 5, "rated": true}} ``` +文字评价的读取、提交、清空分别使用 `GET`、`PUT`、`DELETE /api/v1/skills/{skillId}/reviews/me`;公开列表使用 `GET /api/v1/skills/{skillId}/reviews`。清空只移除文字,平台隐藏与恢复由对应角色在管理入口操作。 -响应使用统一 API 封装。`GET .../star` 的 `data` 是布尔值;`GET .../rating` 返回 `score` 和 `rated`。修改接口返回空 `data`,不会返回评分时间。技能 ID 为数值。 +第一条接口的 `data` 为布尔值;上述 JSON 仅展示评分接口的 `data` 节选,不代表完整响应。写入接口返回空 `data`,不能据此读取评分时间。接口依据:[收藏](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/portal/SkillStarController.java)与[评分](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/portal/SkillRatingController.java)。 -## 注意事项 +## 接收与处理站内通知 -> **评分规则**:每个用户对每个技能包只能评分一次,可以修改评分但不能删除。 +![业务事件、账号偏好与站内通知之间的关系](/diagrams/notification-delivery-flow.svg) -> **评价规则**:只有已发布技能可以评价;公开列表只显示可见评价。并发修改发生冲突时,刷新详情后重试。 +*图:事件按接收人和分类偏好形成站内记录;阅读通知后仍须在目标页面完成业务操作。* -- **星标数量**:技能包的星标数会显示在搜索结果和详情页 -- **平均评分**:平均评分供选择技能时参考,不是搜索页的独立排序选项 -- **通知设置**:用户可以在设置中关闭某些类型的通知 -- **下载统计**:已发布版本的下载会记录计数;审核预览下载不计入公开下载统计 +1. 打开顶部通知入口或 `/notifications`,按分类和时间定位事件。通知标题说明事件,不替代目标对象当前状态。 +2. 打开未读项,核对关联对象及版本;系统发起标记已读并跳转。审核申请仍须在审核详情中处理,不能将通知已读当作批准。 +3. 在 `/settings/notifications` 按分类调整开关。保存后影响后续创建的通知,不删除已有记录;关闭期间未生成的通知,不因重新开启而补建。 +4. 需要整理列表时,先确认业务处理结果,再标记已读或全部已读。删除按钮仅适用于已读通知;删除通知不撤销发布、审核或举报结果。 + +| 分类 | 触发事件 | 接收对象 | 说明 | +| --- | --- | --- | --- | +| 发布(PUBLISH) | 技能发布、订阅技能新版本或撤回已发布版本 | 满足事件条件的发布者、有效订阅者 | 订阅投递重新检查账号、命名空间与资源访问条件,并排除相应操作者。 | +| 审核(REVIEW) | 技能或个人资料提审,以及技能审核批准、拒绝 | 相应审核接收人或申请提交者 | 个人资料与技能审核不使用相同审核权限。 | +| 提升(PROMOTION) | 提升申请及批准、拒绝 | 平台技能审核接收人或申请提交者 | 通知不自动建立全局技能访问权。 | +| 举报(REPORT) | 举报提交与处理完成 | 平台技能审核接收人或举报人 | 历史记录不保证目标技能仍可查看。 | + +上述为本页涉及的分类与代表事件,具体触发/接收条件以[事件监听器](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/listener/NotificationEventListener.java)及[订阅接收条件](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/social/SubscriptionRecipientEligibility.java)为准。接收人列表会在相应事件内去重,但通知服务不提供所有事件严格一次投递的全局保证。 + +## 数量、刷新与保留规则 + +| 配置或限制 | 默认值或范围 | 生效方式 | 说明 | +| --- | --- | --- | --- | +| 星级/评价长度 | 星级1–5;文字最多2000字符 | 提交时校验 | 越界请求被拒绝;仅修改星级不要求文字。 | +| 通知列表 | 网页每页20条;接口 `size` 范围1–100 | 分页请求时生效 | 不将当前一页数量视为全部记录数。 | +| 站内通知偏好 | 四类未保存时均开启,通道仅 `IN_APP` | 保存后影响后续通知创建 | 当前版本未提供邮件、短信或即时通信通知通道。 | +| 网页刷新 | 10秒轮询,窗口重新获得焦点时刷新 | 前端固定行为 | 不保证事件发生后立即显示。 | +| 已读记录保留 | `skillhub.notification.cleanup.read-retention-days=30` | 部署配置变更后重建或滚动注册中心 | 从 `createdAt` 计算,不从阅读时间计算。 | +| 未读记录保留 | `skillhub.notification.cleanup.unread-retention-days=90` | 部署配置变更后重建或滚动注册中心 | 从 `createdAt` 计算,不是永久保存。 | +| 清理调度 | 每日02:00 | 注册中心调度器执行 | 代码未固定时区,按实例调度时区;到期后由后续清理运行删除,不承诺精确到期时刻。 | + +来源:[评价输入](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/SkillReviewRequest.java)、[通知接口](https://github.com/iflytek/skillhub/blob/main/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/portal/NotificationController.java)、[偏好服务](https://github.com/iflytek/skillhub/blob/main/server/skillhub-notification/src/main/java/com/iflytek/skillhub/notification/service/NotificationPreferenceService.java)、[轮询](https://github.com/iflytek/skillhub/blob/main/web/src/features/notification/use-notifications.ts)及[清理任务](https://github.com/iflytek/skillhub/blob/main/server/skillhub-notification/src/main/java/com/iflytek/skillhub/notification/service/NotificationCleanupTask.java)。 + +## 完成标准与失败处置 + +收藏应在个人列表出现,评分应在请求完成后显示个人已保存值;通知应显示正确分类与时间,标记操作完成后未读状态更新。目标页面业务状态须单独核对。 + +| 现象 | 最可能原因 | 定位手段 | 处置 | +| --- | --- | --- | --- | +| 收藏或评分后未保存 | 登录失效、无访问权或请求失败 | 核对当前账号、详情访问及浏览器网络请求状态 | 登录后重新读取状态再操作;不要连续点击制造重复请求。 | +| 评价仅本人或平台角色可见 | 评价被隐藏 | 读取个人评价状态与处理原因,比较公开列表 | 按原因修订或联系相应平台角色;不要通过编辑规避隐藏状态。 | +| 未收到预期通知 | 分类关闭、接收条件不满足或事件尚在异步处理 | 核对通知设置、订阅关系及事件对应业务结果 | 先确认事件是否面向当前账号;不要仅为生成通知重复发布或提审。 | +| 未读数暂未变化 | 请求尚未完成或轮询尚未刷新 | 查看通知列表及未读数请求;重新聚焦窗口 | 等待请求完成后核对;不要把旧数字当作业务执行失败。 | +| 通知目标不可访问 | 资源删除、隐藏或权限已变化 | 核对目标路径、账号与当前命名空间成员资格 | 按当前权限处理;不要将历史通知作为访问凭证。 | +| 历史通知已消失 | 手工删除或达到清理条件 | 比较创建时间、已读状态及实例保留配置 | 通过业务对象查询结果;不要将通知列表用作永久审计档案。 | + +## 边界与后续 + +旧 `GET /api/v1/notifications/sse` 已移除,自建客户端须轮询 `GET /api/v1/notifications` 和 `GET /api/v1/notifications/unread-count`。通知处理是异步的,刷新周期不是投递时限承诺。发布后仍需[管理版本](./skill-publish.html),审核通知须进入[审核流程](./review.html)处理;账号与命名空间变更按[账号](./account-access.html)和[命名空间](./namespace.html)规则生效。 diff --git a/docs/skillhub/introduction.md b/docs/skillhub/introduction.md index c03769b58..63ca99f38 100644 --- a/docs/skillhub/introduction.md +++ b/docs/skillhub/introduction.md @@ -1,61 +1,58 @@ # 项目简介 -SkillHub 是一个专为企业打造的自托管 Agent Skill 注册中心。 +SkillHub 是管理 Agent 技能分发与治理的自托管注册中心。技能作者提交带有 `SKILL.md` 的技能包,注册中心保存版本并执行访问控制、扫描和审核流程;使用者通过网页发现技能,再通过 CLI 将文件安装到目标 Agent 的技能目录。本页面向首次了解产品的使用者、作者和部署方,说明职责边界与对象选择,不代替具体操作手册。 -在 AI Agent 时代,每个团队都在积累自己的技能包(Skills)。但这些技能包散落在各处:有的在开发者本地,有的在 Git 仓库,有的在内部文档里。团队成员很难发现彼此的工作,更难复用已有的能力。 +## 注册中心的职责与边界 -SkillHub 解决了这个问题。它提供了一个**私有、可控、易用**的技能包注册中心,让团队可以像使用 npm、PyPI 一样管理 Agent Skills。 +注册中心解决技能来源分散、版本难以统一、访问范围与发布过程缺少管理入口的问题。它管理的是可分发的技能文件、版本及其治理记录,不负责在服务端直接执行已安装技能。 -![项目架构图](/diagrams/architecture.png) +![技能作者、注册中心和 Agent 环境的职责划分](/diagrams/registry-responsibilities.svg) -## 核心价值 +图:注册中心负责接收、治理与分发;技能安装后的加载和执行由目标 Agent 环境完成。 -- **统一分发**:上传技能包并跟踪扫描、审核和发布状态 -- **企业级权限**:基于命名空间的 RBAC,支持团队协作和审核流程 -- **完整生命周期**:版本管理、标签系统、审核工作流、归档机制 -- **部署选择**:Docker Compose 和 Kubernetes,按环境配置依赖和认证 -- **安全扫描**:内置 Skill Scanner,自动检测安全风险 -- **数据主权**:完全自托管,所有数据都在你的防火墙内 - -## 技术栈 - -![前端、后端、数据与存储技术组成](/diagrams/tech-stack-sketch.png) - -存储可选择本地文件或 S3 兼容后端;按部署需求显式配置。 - -| 层级 | 技术 | 说明 | -|------|------|------| -| **前端** | React + Vite + TanStack Router | 现代化 SPA,支持多语言切换 | -| **后端** | Java 21 + Spring Boot | 企业级 REST API | -| **数据库** | PostgreSQL | 全文搜索、Flyway 自动迁移 | -| **缓存** | Redis | 会话管理、热点缓存 | -| **存储** | 本地文件 / S3 兼容存储 | 技能包文件存储,支持本地和云端 | -| **部署** | Docker Compose / K8s | 按部署配置自托管 | - -## 核心功能一览 - -| 功能 | 说明 | -|------|------| -| [Skill 发布与版本管理](/guide/skill-publish) | 一键发布技能包,语义化版本管理 | -| [Skill 搜索与发现](/guide/skill-discovery) | 全文搜索、智能过滤、权限感知 | -| [命名空间与团队管理](/guide/namespace) | 基于命名空间的 RBAC 权限体系 | -| [审核与治理](/guide/review) | 技能与套装审核流程、举报系统 | -| [安全扫描](/guide/scanner) | 内置 Skill Scanner,多引擎安全分析 | -| [用户交互与社交](/guide/social) | 星标、评分、通知系统 | - -## 先理解三个对象 - -| 对象 | 用途 | 下一步 | +| 操作 | 注册中心承担的职责 | 使用者或作者承担的职责 | | --- | --- | --- | -| Skill | 带有 `SKILL.md` 的单个技能包,安装后由 Agent 发现和使用 | [快速开始](./quickstart.md) | -| Skill Suite | 固定成员版本的技能集合,指定一个成员作为入口技能 | [套装安装与使用](./guide/skill-suites.md) | -| Suite Bundle | 发布者批量上传套装定义和成员包的格式 | [批量导入](./guide/suite-bundle.md) | +| 提交与发布 | 校验技能包,按配置推进扫描、审核及发布 | 提供指令、依赖说明和可核查的内容;处理拒绝或失败结果 | +| 发现与下载 | 按资源状态和访问权限提供搜索、详情及可下载版本 | 核对用途、来源、版本和目标环境,不将可见详情等同于可安装 | +| 安装与执行 | CLI 下载文件并维护本地安装记录 | 确认 Agent 已发现技能,配置运行依赖,并验收执行结果 | +| 更新与治理 | 管理版本以及隐藏、归档等治理状态 | 核对本地修改与更新计划;已下载文件不会因远端治理操作被自动收回 | -注册中心负责分发和治理;技能的实际执行发生在使用者的 Agent 环境中。安装套装不会自动运行全部成员。 +技能不是托管运行中的应用;安装不等于启动服务。扫描结果和审核记录也不是执行效果或合规认证:扫描只能反映对应任务与策略下的检查结果,技能的适用性仍需在实际 Agent 环境中验证。 -## 按角色阅读 +## 区分技能、技能套装与套装 Bundle -- 使用者:[CLI](./guide/cli.md)、[搜索与发现](./guide/skill-discovery.md)、[FAQ](./faq.md)。 -- 创作者:[发布与版本管理](./guide/skill-publish.md)、[套装](./guide/skill-suites.md)、[审核](./guide/review.md)。 -- 管理员:[命名空间](./guide/namespace.md)、[部署与升级](./guide/deployment.md)、[Kubernetes](./guide/kubernetes.md)。 -- 集成开发者:[Runtime 契约](./guide/runtime-integration.md)、[仓库文档索引](https://github.com/iflytek/skillhub/blob/main/docs/README.md)。 +三种对象服务不同阶段,不能相互替代。技能套装(Skill Suite)固定一组成员技能的精确版本,并指定一个成员作为入口;套装 Bundle(Suite Bundle)是作者批量导入成员和套装定义的格式。 + +| 对象 | 保存或描述的内容 | 与相邻对象的区别 | +| --- | --- | --- | +| 技能 | 一个以 `SKILL.md` 为核心的技能包及其版本 | 可独立安装;关联某个技能套装不要求安装全部成员 | +| 技能套装 | 成员坐标、精确版本和入口技能 | 是安装集合,不是工作流执行引擎;安装后成员仍为独立目录 | +| 套装 Bundle | `SUITE.yaml` 与待上传的成员目录,或已发布成员的版本引用 | 是创作与导入输入,不是本地 Agent 的执行程序,也不绕过成员审核 | + +例如,会议资料处理需要“材料接收”和“摘要生成”两个技能。单独使用摘要功能时,只需安装摘要技能;共同分发时,可创建技能套装,固定各成员版本并将材料接收设为入口。成员尚在本地、需要同时上传时,作者才需要准备套装 Bundle。此例用于解释对象关系,不代表注册中心存在同名可安装资源。安装技能套装不会自动执行上述两步,实际协作由入口及成员指令与 Agent 决定。 + +对象定义可核查[技能套装成员模型](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/suite/SkillSuiteVersionMember.java)及[套装 Bundle 定义](https://github.com/iflytek/skillhub/blob/main/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/suite/bundle/SkillSuiteBundleManifest.java)。 + +## 根据目标选择对象与入口 + +| 目标 | 选择 | 判断依据与后续操作 | +| --- | --- | --- | +| 安装一个技能完成独立任务 | 技能 | 无需固定其他成员版本;从[快速开始](./quickstart.html)完成安装与 Agent 发现验证 | +| 将多个技能按固定版本共同分发 | 技能套装 | 需要固定成员组合与入口;在[技能套装](./guide/skill-suites.html)中核对成员可安装状态 | +| 同时上传多个本地技能并组成套装 | 套装 Bundle | 需要导入定义、预览差异并创建成员版本;阅读[Bundle 导入](./guide/suite-bundle.html) | +| 管理可见范围、成员与审核 | 命名空间与治理流程 | 平台角色不等同于命名空间角色;先阅读[命名空间](./guide/namespace.html)的权限前置 | + +只有技能安装和使用需求时,不需要先部署注册中心或准备套装 Bundle。发布需求应按“准备技能包、提交、扫描、审核、确认发布”的实际路径处理,不能将上传结束当作全部流程结束;入口见[发布与版本管理](./guide/skill-publish.html)。 + +## 部署形态与技术组成 + +已有可访问实例时,可直接使用其网页和 CLI。自托管部署则需要维护服务、数据库、会话存储及技能文件存储,并配置所需认证与扫描能力。外部身份、扫描器和其他外部服务是否启用,以实例配置为准;自托管不代表所有外部请求均被禁用。 + +| 组成 | 技术或实现 | 作用与配置边界 | +| --- | --- | --- | +| 网页与服务端 | React、Vite;Java、Spring Boot | 网页提供操作入口,服务端执行接口及业务规则 | +| 数据库与会话存储 | PostgreSQL、Redis | 保存业务记录并支持服务端会话;必须与技能文件一起纳入运维设计 | +| 技能文件存储 | 本地文件或 S3 兼容存储 | 后端按部署配置选择实现;存储选型不等于已有数据已完成迁移 | +| 部署路径 | 部署脚本、release Compose、Kustomize、Helm | 路径各有配置入口,不应混用升级命令或持久化配置 | + +部署组成以[release Compose](https://github.com/iflytek/skillhub/blob/main/compose.release.yml)及[后端模块定义](https://github.com/iflytek/skillhub/blob/main/server/pom.xml)为依据。需要自托管时,从[文档导航](./guide/index.html)选择部署路径;集成开发者应区分注册中心接口与实际 Agent 执行环境,接口职责见[Runtime 集成](./guide/runtime-integration.html)。 diff --git a/docs/skillhub/public/diagrams/first-install-flow-en.svg b/docs/skillhub/public/diagrams/first-install-flow-en.svg new file mode 100644 index 000000000..a7bef4df6 --- /dev/null +++ b/docs/skillhub/public/diagrams/first-install-flow-en.svg @@ -0,0 +1,25 @@ + +Staged checks for first installation +Select the registry and identity, install files, verify records, then check Agent discovery and task results. Each stage requires independent verification. + + + +1 Select source and identity +Find a coordinate; log in if required +Check purpose, version and access + + +2 Install files +Select project, scope and Agent +Check SKILL.md at the actual path + + +3 Inspect installation records +Match coordinate, Agent and path +Existing files do not prove discovery + + +4 Verify discovery and execution +Load the skill in the target Agent +Assess the actual task result + diff --git a/docs/skillhub/public/diagrams/first-install-flow.svg b/docs/skillhub/public/diagrams/first-install-flow.svg new file mode 100644 index 000000000..29f7595a0 --- /dev/null +++ b/docs/skillhub/public/diagrams/first-install-flow.svg @@ -0,0 +1,25 @@ + +首次安装与使用的分阶段检查 +先选择注册中心及身份,再安装文件、确认记录,最后验证Agent发现与任务结果。每一阶段都需要独立检查。 + + + +1 选择来源与身份 +搜索真实坐标;受限资源需登录 +核对用途、版本和访问权限 + + +2 安装文件 +明确项目、范围与目标 Agent +核对实际目录中的 SKILL.md + + +3 检查安装记录 +核对坐标、Agent、路径与状态 +目录存在不等于 Agent 已发现 + + +4 验证发现与执行 +在目标 Agent 中加载并使用技能 +按任务预期验收实际结果 + diff --git a/docs/skillhub/public/diagrams/namespace-membership-flow-en.svg b/docs/skillhub/public/diagrams/namespace-membership-flow-en.svg new file mode 100644 index 000000000..8942bf78a --- /dev/null +++ b/docs/skillhub/public/diagrams/namespace-membership-flow-en.svg @@ -0,0 +1,28 @@ + +Namespace Collaboration +Authorized creator creates a team namespace. Owner or Admin adds or invites a member. An admitted user confirms acceptance. Publication and review remain separate. + + +Namespace Collaboration + +1. Create namespace +Platform SKILL_ADMIN / SUPER_ADMIN +Creator becomes namespace Owner + + +2. Add or invite members +Namespace Owner / Admin; ACTIVE +Invitation alone does not add a member + + +3. Confirm membership +Login and admission checks first +Accepted invitation grants MEMBER + + +4. Submit and review +Select visibility, then publish workflow +Membership is not publication +Namespace and platform roles are separate. +A membership change does not transfer Skills. + diff --git a/docs/skillhub/public/diagrams/namespace-membership-flow.svg b/docs/skillhub/public/diagrams/namespace-membership-flow.svg new file mode 100644 index 000000000..4a3ef8448 --- /dev/null +++ b/docs/skillhub/public/diagrams/namespace-membership-flow.svg @@ -0,0 +1,28 @@ + +命名空间协作流程 +具备创建权限的平台操作者创建团队命名空间,所有者或空间管理员添加或邀请成员;受邀账号完成准入并确认加入后,再执行独立的发布与审核流程。 + + +命名空间协作流程 + +1. 创建命名空间 +平台技能管理员或超级管理员 +创建者成为命名空间所有者 + + +2. 添加或邀请成员 +所有者或空间管理员;状态为 ACTIVE +生成邀请不会直接建立成员关系 + + +3. 确认成员资格 +先完成登录和现有准入检查 +确认接受邀请后授予 MEMBER + + +4. 提交并审核 +选择可见范围,进入发布流程 +取得成员资格不代表技能已发布 +命名空间角色与平台角色分别管理。 +成员变动不会转让技能所有权。 + diff --git a/docs/skillhub/public/diagrams/notification-delivery-flow-en.svg b/docs/skillhub/public/diagrams/notification-delivery-flow-en.svg new file mode 100644 index 000000000..0b26bf8a5 --- /dev/null +++ b/docs/skillhub/public/diagrams/notification-delivery-flow-en.svg @@ -0,0 +1,25 @@ + +In-app notification flowEvents select eligible recipients and consult category preferences before records are created. Reading a notification does not complete the target business action. + + +In-app notification flow + +1. Business event +Publication, review, promotion, report + + +2. Recipient eligibility +Current account and access rules + + +3. Category preference +Disabled: no new record + + +4. In-app record +Unread, read, or retention cleanup + + +5. Target business action +Reading is not task completion + diff --git a/docs/skillhub/public/diagrams/notification-delivery-flow.svg b/docs/skillhub/public/diagrams/notification-delivery-flow.svg new file mode 100644 index 000000000..4710a15a8 --- /dev/null +++ b/docs/skillhub/public/diagrams/notification-delivery-flow.svg @@ -0,0 +1,25 @@ + +站内通知处理流程业务事件根据接收条件与分类偏好创建站内通知。阅读通知不代表关联业务已处理。 + + +站内通知处理流程 + +1. 业务事件 +发布、审核、提升或举报 + + +2. 确定有效接收人 +核对当前账号与访问规则 + + +3. 读取分类偏好 +关闭时不创建该类新记录 + + +4. 保存站内通知 +未读、已读与保留期清理 + + +5. 处理关联业务 +已读不等于业务处理完成 + diff --git a/docs/skillhub/public/diagrams/registry-responsibilities-en.svg b/docs/skillhub/public/diagrams/registry-responsibilities-en.svg new file mode 100644 index 000000000..a4d994a31 --- /dev/null +++ b/docs/skillhub/public/diagrams/registry-responsibilities-en.svg @@ -0,0 +1,20 @@ + +Responsibilities in skill distribution +Authors submit skill packages; the registry manages versions, access and governance; the target Agent environment loads and executes installed skills. + + + +1 Skill author +Supplies SKILL.md and package files +Describes purpose and dependencies + + +2 SkillHub registry +Manages versions, access and review +Provides search and file distribution + + +3 Target Agent environment +CLI installs; Agent loads the skill +Configures tools; assesses execution + diff --git a/docs/skillhub/public/diagrams/registry-responsibilities.svg b/docs/skillhub/public/diagrams/registry-responsibilities.svg new file mode 100644 index 000000000..c32ab20ff --- /dev/null +++ b/docs/skillhub/public/diagrams/registry-responsibilities.svg @@ -0,0 +1,20 @@ + +技能分发的职责划分 +作者提交技能包,注册中心管理版本、访问和治理,目标Agent环境加载并执行安装后的技能。 + + + +1 技能作者 +提供 SKILL.md 与配套文件 +声明用途、依赖和版本 + + +2 SkillHub 注册中心 +管理版本、权限、扫描与审核 +提供搜索与文件分发 + + +3 目标 Agent 环境 +CLI 安装文件,Agent 加载技能 +配置运行依赖并验收执行结果 + diff --git a/docs/skillhub/public/diagrams/review-decision-flow-en.svg b/docs/skillhub/public/diagrams/review-decision-flow-en.svg new file mode 100644 index 000000000..53b9d87bc --- /dev/null +++ b/docs/skillhub/public/diagrams/review-decision-flow-en.svg @@ -0,0 +1,28 @@ + +Review Decision +Identify the current request, verify evidence and readiness, decide only with permission, then re-read the result. Missing evidence leads to diagnosis, not approval. + + +Review Decision + +1. Identify current request +Subject, submitter, version, visibility +Check namespace and review permission + + +2. Inspect evidence +Files, changes, scan and metadata +Missing evidence: diagnose or wait + + +3. Submit a decision +Pending task and eligible reviewer +Approve, or reject with correction details + + +4. Re-read the outcome +Check task plus target object state +Approval is not Agent execution proof +Use the current submission, not the old release. +Do not repeat a decision after a conflict. + diff --git a/docs/skillhub/public/diagrams/review-decision-flow.svg b/docs/skillhub/public/diagrams/review-decision-flow.svg new file mode 100644 index 000000000..a9dce943e --- /dev/null +++ b/docs/skillhub/public/diagrams/review-decision-flow.svg @@ -0,0 +1,28 @@ + +审核决定流程 +核对当前申请及处理权限,检查内容和证据;证据不足时排障或等待,不直接批准。提交决定后重新读取任务和目标对象的结果。 + + +审核决定流程 + +1. 识别当前申请 +对象、提交者、版本和可见范围 +核对命名空间状态与审核权限 + + +2. 核查证据 +文件、变更、扫描和资料 +证据缺失时先排障或等待 + + +3. 提交决定 +申请仍待审,操作者具备权限 +批准,或拒绝并记录修订要求 + + +4. 重新读取结果 +核对任务及目标对象状态 +审核批准不代表 Agent 执行成功 +审核以本次申请为准。 +状态冲突后不得重复提交决定。 + diff --git a/docs/skillhub/public/diagrams/scan-result-flow-en.svg b/docs/skillhub/public/diagrams/scan-result-flow-en.svg new file mode 100644 index 000000000..c47369b72 --- /dev/null +++ b/docs/skillhub/public/diagrams/scan-result-flow-en.svg @@ -0,0 +1,25 @@ + +Scan evidence and reviewA scan request executes asynchronously. A report distinguishes findings from execution failures. A reviewer separately decides publication. + + +Scan evidence and review + +1. Request scan +Identify the submitted version + + +2. Execute task +SCANNING is not approval + + +3. Inspect result +Failure reason or findings + + +4. Act on evidence +Restore execution or revise content + + +5. Human review +Approve or reject the submission + diff --git a/docs/skillhub/public/diagrams/scan-result-flow.svg b/docs/skillhub/public/diagrams/scan-result-flow.svg new file mode 100644 index 000000000..97bc7064b --- /dev/null +++ b/docs/skillhub/public/diagrams/scan-result-flow.svg @@ -0,0 +1,25 @@ + +扫描证据与人工审核扫描任务异步执行。报告分别呈现执行失败与风险发现;审核员独立作出发布决策。 + + +扫描证据与人工审核 + +1. 发起扫描 +核对本次提交的版本 + + +2. 异步执行任务 +扫描中不代表已批准 + + +3. 判读本次报告 +区分失败原因与风险发现 + + +4. 按证据处置 +恢复扫描执行,或修订内容 + + +5. 人工审核 +依据内容与证据批准或拒绝 + diff --git a/docs/skillhub/quickstart.md b/docs/skillhub/quickstart.md index 91eb330f9..5cd775d25 100644 --- a/docs/skillhub/quickstart.md +++ b/docs/skillhub/quickstart.md @@ -1,101 +1,136 @@ # 快速开始:安装并使用技能 -安装第一个技能,并在 Agent 中使用。本页使用已有的注册中心,不需要先部署 SkillHub 服务。 +本页从已有可访问的注册中心开始,完成单个技能的安装、Agent 发现及首次使用检查。不涉及部署注册中心或发布技能。流程终点是 Agent 能读取技能并完成一次具体任务,而不只是 CLI 返回安装成功。 -## 开始前准备 +![选择注册中心、安装文件、确认发现与验收执行的顺序](/diagrams/first-install-flow.svg) -- 一个支持技能目录的 Agent,例如 Codex 或 Claude Code。 -- Node.js 18 或更新版本,以及可用的 npm;可用 `node --version` 确认版本。 -- 一个准备使用技能的项目目录,以及能访问的 SkillHub 注册中心地址。 +图:每一步均有独立完成标准;后一步失败时,应先定位对应阶段,而不是重新安装全部内容。 -本页命令使用终端运行,`@team/example-skill` 是占位坐标,不是保证存在的公共技能。选择实际搜索结果后再替换。项目级安装前,先切换到准备让 Agent 打开的项目根目录。 +## 前置准备 -## 1. 安装 CLI,选择注册中心 +在终端执行命令,并先切换至目标 Agent 将打开的项目根目录。准备一个可访问的注册中心以及 Codex、Claude Code 等支持技能目录的 Agent。 + +| 项目 | 要求或取值 | 检查与生效方式 | +| --- | --- | --- | +| Node.js | 最低18,且 npm 可用 | 执行 `node --version`、`npm --version`;更换运行环境后重新打开终端 | +| 注册中心 | 内置地址为 `https://skill.xfyun.cn` | 选择顺序为命令参数、`SKILLHUB_REGISTRY`、本地配置、内置地址;环境变量在当前终端生效 | +| 安装范围 | `project` 或 `user` | 本页显式使用项目级;用户级位于主目录,不等于所有 Agent 都会自动加载 | +| 目标 Agent | 本页使用 `codex` | Claude Code 改用 `claude-code`;必须与实际打开项目的 Agent 一致 | + +`skillhub.example.com` 与 `@team/example-skill` 均为占位示例,不保证存在。必须分别替换为实际实例地址及搜索结果中的技能坐标。最低运行版本与参数来源见 [CLI 清单](https://github.com/iflytek/skillhub/blob/main/cli/package.json)及[命令定义](https://github.com/iflytek/skillhub/blob/main/cli/src/index.ts)。 + +## 1. 安装 CLI 并选择注册中心 ```bash npm install -g @astron-team/skillhub skillhub version ``` -默认使用 `https://skill.xfyun.cn`。使用自托管实例时,在当前终端设置实际地址: +版本命令应输出 `SkillHub CLI` 及实际安装版本。出现命令不存在时,应先检查 npm 全局可执行目录是否位于当前终端的 `PATH`,不要继续执行安装技能命令。 + +使用默认实例时无需设置地址。自托管实例在当前终端设置实际地址,随后所有命令保持同一来源: ```bash export SKILLHUB_REGISTRY=https://skillhub.example.com ``` -PowerShell 中设置注册中心使用: +PowerShell 对应设置为: ```powershell $env:SKILLHUB_REGISTRY="https://skillhub.example.com" ``` -只想临时使用另一个实例时,可以在命令后添加 `--registry https://skillhub.example.com`。搜索、登录和安装应使用同一个注册中心;不同实例中的同名技能不是同一安装来源。 +单次操作也可添加 `--registry https://skillhub.example.com`。不同实例的同名技能不是同一来源;切换来源不会搬迁已安装文件。 -公开技能可匿名搜索和安装。发布、访问受限资源等操作需要登录: +## 2. 搜索技能并核对身份 + +```bash +skillhub search pdf +``` + +输出每行依次为命名空间/技能标识、最新版本和摘要;无结果时显示 `No skills found.`。在同一实例的网页详情核对用途、版本、访问范围及依赖,然后复制真实坐标。 + +公开技能支持匿名搜索和安装;受限资源需要登录,并仍受资源权限约束: ```bash skillhub login skillhub whoami ``` -没有从命令行、环境变量或该注册中心的保存记录读取到 Token 时,CLI 会进入设备授权;按终端提示在浏览器完成登录和设备码确认。已有 Token 时先用该 Token 验证身份,不会自动重新选账号。远程终端可用 `skillhub login --no-open`。账号是否可以注册、使用哪些登录方式,由实例配置决定。 +不存在命令参数、环境变量或该注册中心保存的 Token 时,登录进入设备授权,终端显示授权地址与设备码。浏览器登录后须完成设备码确认;网页已有登录态不等于 CLI 已获凭据。已有 Token 时会先验证该凭据,不会自动选择其他账号。远程终端使用 `skillhub login --no-open`;可用登录方式和注册入口由实例配置决定。`whoami` 应显示所选注册中心和账号,具体处理见[账号与访问令牌](./guide/account-access.html)。 -## 2. 找到技能并安装 +## 3. 安装并检查文件与记录 -```bash -skillhub search pdf -``` - -在网页详情确认用途、版本、可见性及使用说明,然后复制真实坐标。下面的 `@team/example-skill` 是占位示例,必须替换成搜索结果中的坐标。 - -在目标项目根目录执行: +在目标项目根目录执行,先将占位坐标替换为真实结果: ```bash skillhub install @team/example-skill --scope project --agent codex -skillhub list --agent codex +skillhub list --agent codex --json ``` -Claude Code 用户改用 `--agent claude-code`。希望多个项目共用时,使用 `--scope user`。 -项目级 Codex 安装目录为 `.codex/skills//`,Claude Code 为 `.claude/skills//`;用户级路径位于用户主目录。 +以下为格式示例,不是真实下载结果。安装命令输出的路径应对应当前项目;项目级目录结构应包含 `SKILL.md`,其他文件取决于技能包内容: -### 确认安装到了哪里 +```text +Installed team/example-skill -> /work/project/.codex/skills/example-skill (codex) -查看安装命令输出的目标路径,再查看 `skillhub list --agent codex` 的记录:坐标、版本、Agent、目录和状态应符合刚才选择的目标。`list` 按当前注册中心过滤;切换注册中心后列表变化不代表本地文件被删除。 +/work/project/.codex/skills/example-skill/ +└── SKILL.md +``` -状态 `missing` 表示记录对应的目录不存在;`ok` 只表示目录存在,不代表 Agent 已加载或技能已执行成功。进入实际目录检查 `SKILL.md`,再继续下一步。 +`list` 的 JSON 中应存在对应记录。以下是完整结构示例,路径、时间及版本必须以本次实际输出为准: -## 3. 在 Agent 中使用 +```json +{"ok":true,"items":[{"namespace":"team","slug":"example-skill","version":"1.0.0","agent":"codex","installDir":"/work/project/.codex/skills/example-skill","installedAt":"2026-11-03T08:00:00.000Z","status":"ok"}]} +``` -安装完成后,在目标 Agent 中打开项目,必要时新建会话或重新加载技能。先确认 Agent 能发现该技能,再提出具体任务,例如: +核对坐标、Agent 与 `installDir`,并打开该目录的 `SKILL.md`。状态 `ok` 仅表示目录存在,不代表内容已执行;`missing` 表示记录对应目录缺失。列表按当前注册中心过滤,但并非仅列当前项目,必须同时核对路径。Claude Code 项目级目录为 `.claude/skills//`。使用 `--scope user` 时目录位于主目录,对应文件发现规则由 Agent 决定。 -> 请使用 example-skill,按它的说明处理以下材料:…… +输出依据见[安装命令](https://github.com/iflytek/skillhub/blob/main/cli/src/commands/install.ts)与[安装清单命令](https://github.com/iflytek/skillhub/blob/main/cli/src/commands/list.ts)。 -实际调用名称以技能 `SKILL.md` 中的 `name` 和 Agent 显示结果为准。安装不会自动执行技能,也不会代为配置成员所需的工具或凭据。 -如果 Agent 没发现技能,检查 CLI 输出路径、当前项目、安装范围和目标 Agent,参见 [FAQ](./faq.html)。 +## 4. 验证 Agent 发现并执行任务 -整套安装使用 `skillhub suite install`,之后从套装的入口技能开始;详见 [技能套装使用指南](./guide/skill-suites.html)。 +在目标 Agent 中打开上述项目,按该产品的加载机制重载技能或新建会话。核对 Agent 可用技能中出现目标名称,再按技能说明提供一次具体任务、输入与预期产物。调用名称以实际 `SKILL.md` 的 `name` 及 Agent 识别结果为准。 -## 4. 更新和管理 +| 阶段 | 可观察完成标准 | 尚不能据此确认的事项 | +| --- | --- | --- | +| 文件安装 | 安装路径有 `SKILL.md`,清单记录匹配且 `status=ok` | Agent 是否已加载文件 | +| Agent 发现 | Agent 的技能列表或会话上下文包含目标技能 | 外部工具、凭据与业务依赖是否可用 | +| 任务执行 | Agent 按技能要求产出可核对的结果 | 其他输入、环境或后续版本是否同样适用 | + +安装不会自动执行技能或配置外部工具。多技能协作需核对入口与成员说明;共同安装使用 `skillhub suite install`,操作见[技能套装](./guide/skill-suites.html)。 + +## 5. 验证参数错误的拒绝行为 + +以下命令使用无效安装范围,演示本地参数校验的拒绝行为: + +```bash +skillhub install @team/example-skill --scope invalid --agent codex +``` + +预期在标准错误输出中看到下列内容,退出码为5;命令在读取安装配置和发起下载前即停止,不会安装示例技能: + +```text +Error: --scope must be "user" or "project" +``` + +改回 `--scope project`,并替换真实坐标后再执行。不要用 `--force` 处理参数错误。该示例的错误消息与执行顺序见[安装参数校验](https://github.com/iflytek/skillhub/blob/main/cli/src/commands/install.ts)。 + +## 失败定位与处置 + +| 现象 | 最可能原因 | 定位手段 | 处置 | +| --- | --- | --- | --- | +| 搜索无目标结果 | 来源、权限或发布状态不符 | 在同一终端检查 `skillhub search pdf`、`skillhub whoami`,并在同一实例核对坐标 | 核对来源与发布状态,必要时登录;不要通过重置账号排障 | +| 安装提示同名目录已存在 | 既有安装或手工文件占用路径 | 对照提示路径与 `skillhub list --agent codex --json` 的 `installDir`,读取目录内 `SKILL.md` | 备份并辨明来源,选择正确项目或范围;不要覆盖未知内容 | +| 安装后 Agent 未发现技能 | 项目、范围或目标 Agent 不符 | 核对清单中的 `agent`、`installDir`、`status`,确认 Agent 打开的项目 | 修正目标并按 Agent 机制重载;不要将 `ok` 当作加载完成 | +| 已发现技能但执行失败 | 缺少运行依赖、输入或权限 | 读取本地 `SKILL.md`,对照 Agent 错误检查工具及凭据要求 | 在目标环境补齐依赖;不要把凭据写入共享技能包或公开日志 | + +## 更新与后续任务 + +在已完成上述检查后,先查看升级计划,再决定执行更新: ```bash skillhub upgrade @team/example-skill --check skillhub upgrade @team/example-skill ``` -检查计划后再更新。保留需要的本地修改;不要把 `--force` 当作默认参数。卸载、同步团队工作区和完整命令说明见 [CLI 指南](./guide/cli.html)。 - -## 常见问题与处理 - - -| 现象 | 定位动作 | 正常结果或原因 | 检查与处理 | -| --- | --- | --- | --- | -| 搜索不到目标技能 | 同一终端执行 `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.html);需要更多命令时,查阅 [CLI 指南](./guide/cli.html)。发布技能、管理团队、自托管和源码开发,请从[文档导航](./guide/index.html)选择对应任务。 +升级可能受本地修改、共享目录或来源保护限制,必须先读取计划;不要默认添加 `--force`。本页终点是单技能首次可用,后续卸载、版本管理及完整选项见[CLI 参考](./guide/cli.html);作者发布和部署任务从[文档导航](./guide/index.html)进入。 diff --git a/openspec/changes/repair-online-documentation/design.md b/openspec/changes/repair-online-documentation/design.md index 26f676248..a877d85fb 100644 --- a/openspec/changes/repair-online-documentation/design.md +++ b/openspec/changes/repair-online-documentation/design.md @@ -19,3 +19,28 @@ ## Deferred A2 的 29 项导航不是本 PR 的发布承诺;P1/P2、D10 全页深度改造与 A7 全站条件另批交付。架构方案中的“不记录 trace”等断言必须先核对现有可观测性能力,不作为本 PR 事实写入。 + +## 第二批:深度基准样本(2026-11-03) + +维护者确认第二批改造六个中文页面及对应英文页:项目简介、快速开始、命名空间、审核、收藏评分通知和安全扫描。第一批 PR #1054 尚未合并时,第二批独立分支以其冻结提交为基础实施,不混入第一批 PR,也不并行发布。 + +- 文体采用正式技术文档:完整、客观陈述,避免对话式问句、口语、营销语和无依据结论;不得使用第二人称。 +- 内容增加来自判断依据、操作前置、可观察结果、异常处置和下游影响,不以字数、重复警告或罗列接口代替深度。 +- 简介采用概念解释结构,说明注册中心的职责与边界、技能/技能套装/套装 Bundle 的区别及选择依据;不提前创建第三批公共知识页面。 +- 快速开始采用教程结构,保留完整命令、结果样例和一次无破坏性的故意失败演示;不声称安装成功代表 Agent 执行成功。 +- 四个操作页面移除旧模板结构,按角色分流,提供可执行步骤、完成标准、至少四行失败矩阵及限制。现有P0事实修正必须保留。 +- 复杂流程或对象关系配合图示,权限/状态/故障条件使用表格;图示不替代可复制命令和文本解释。优先使用静态SVG,含可访问说明,兼顾390px与明暗主题,不引入渲染依赖。 +- 第二批主体保持既有路由;维护者复核明确要求的头像部署新页及对应导航调整为例外,其余侧边栏顺序不变;新增正文链接用相对.html,英文正文对应英文页面。仅在六页范围整合内容,不擅自改写其他批次。 +- 每页记录来源与D1九要素覆盖;不明确的保留期、权限、事件类别、扫描阈值必须查代码,不编造固定承诺。无固定值时明确配置来源或未定义行为。 + +验收:中文正文体量不超过3000汉字(参考/代码清单不以扩写为目标),没有禁用旧章节或空标题;中英结构/链接一致;所有新技术断言有稳定源码依据;OpenSpec、VitePress、正文链接/锚点及真实浏览器宽度/主题检查通过,一次集中独立Review完成后冻结。 + +## 维护者复核补充:图片对齐与页面职责 + +维护者指出流程图应居中,以及头像上传/审核与供应商部署配置混放导致导航归属不合理。作为本批明确反馈的优先修正,文档主题仅为正文流程图补充水平居中样式,复用默认主题的自然尺寸与响应式规则,不改变其他界面。 + +头像原页面和URL保留,承载技能所有者及审核角色的操作并归入“团队与治理”;供应商开通、部署凭据、配置注入及真实连接验证拆至独立部署页面,归入“部署与运维”。中英文页面、导航索引及侧边栏同步,Pager由既有侧边栏顺序生成;不提前重排其余第三批导航。新页原有配置细节不得因拆分而丢失。 + +审查结论必须标注范围:六页正文增量的技术事实核查不代表全站信息架构或其余页面已通过。补充逐页结构台账,列明已修复、仍有缺口、未核实项目;源文件/浏览器自动检查仅证明相应结构与运行结果,不替代操作语义或未执行的真实外部服务验收。第三至第五批既有问题保持待办,不以“已排期”替代缺陷记录。 + +全站结构补查同时确认四项可定位的内容缺陷,作为本次反馈的局部事实修正:FAQ遗漏新外部账号的首次角色授权规则;搜索指南误导私有技能可在普通市场搜索;CLI成功JSON示例含裸省略号;目录冲突排障未就地明确来源核对和备份前置。中英文对应段落同步修正,并保留这些页面尚未完成整体深度/结构改造的状态,不将局部修正视为整页规范通过。 diff --git a/openspec/changes/repair-online-documentation/proposal.md b/openspec/changes/repair-online-documentation/proposal.md index d2dd4912c..1aaecf6ae 100644 --- a/openspec/changes/repair-online-documentation/proposal.md +++ b/openspec/changes/repair-online-documentation/proposal.md @@ -4,9 +4,11 @@ ## What Changes -本 PR 只交付 A6 第一批 P0-1 至 P0-9:逐项对照实际源码,修正中英文部署路径、独立状态对象、命名空间创建及治理权限、扫描默认值与禁用后果、可执行诊断、创作草稿契约和快速开始失败处理。 +第一批 PR #1054 交付 A6 的 P0-1 至 P0-9:逐项对照实际源码,修正中英文部署路径、独立状态对象、命名空间创建及治理权限、扫描默认值与禁用后果、可执行诊断、创作草稿契约和快速开始失败处理。 -保持既有路由、菜单顺序、接口、角色、发布和审核行为不变。中文改动与英文同批更新。新增站内链接使用相对 `.html` 路径,源码依据链接稳定的 `main` 文件。 +第二批由维护者于2026-11-03确认推进,独立改造项目简介、快速开始、命名空间、审核、收藏评分通知及安全扫描六页及英文镜像。新增正式文体、完整任务说明和必要图表的验收要求,具体范围见 design.md 与 tasks.md 第4节。 + +保留既有页面URL、产品接口、角色、发布和审核行为。维护者复核要求的头像职责拆分和对应导航归属优先修正,其余目录不在本批重排。中文改动与英文同批更新。新增站内链接使用相对 `.html` 路径,源码依据链接稳定的 `main` 文件。 ## Delivery Sequence @@ -28,4 +30,4 @@ ## Impact -仅文档和 OpenSpec 记录。无需应用镜像、数据库迁移或真实业务部署。验证包括来源核对、文档构建、链接/锚点及中英页面/亮暗主题/移动宽度浏览器检查;PR CI 和独立 Review 单独记录。 +仅文档、静态图示、文档主题样式和 OpenSpec 记录。无需应用镜像、数据库迁移或真实业务部署。验证包括来源核对、文档构建、链接/锚点及中英页面/亮暗主题/移动宽度浏览器检查;PR CI 和独立 Review 单独记录。 diff --git a/openspec/changes/repair-online-documentation/specs/documentation-factual-accuracy/spec.md b/openspec/changes/repair-online-documentation/specs/documentation-factual-accuracy/spec.md index 45b7d8d63..c0d96db99 100644 --- a/openspec/changes/repair-online-documentation/specs/documentation-factual-accuracy/spec.md +++ b/openspec/changes/repair-online-documentation/specs/documentation-factual-accuracy/spec.md @@ -41,3 +41,36 @@ Each batch SHALL preserve existing routes and product behavior, synchronize Chin - **THEN** P0-1 through P0-9 have explicit source and verification records - **AND** document build, links and browser checks are reported separately from application runtime tests - **AND** later depth and navigation work remains explicitly pending + +### Requirement: Provide formal and complete documentation depth samples +The second batch SHALL improve the introduction, quickstart, namespace, review, social and scanner pages in both languages without moving routes or changing product behavior. The prose SHALL be formal, source-grounded and task-oriented. Diagrams and tables SHALL clarify relationships and decisions without replacing operational text. + +#### Scenario: Complete an operational task without external explanation +- **WHEN** a reader follows an affected operational guide +- **THEN** the applicable role, prerequisites, action sequence, decision basis, observable outcome, failure handling and downstream effects are explicit +- **AND** duplicate legacy template sections are consolidated rather than retained in parallel + +#### Scenario: Understand the first installation +- **WHEN** a reader follows the quickstart +- **THEN** complete commands, representative output and a non-destructive failure example distinguish installation, Agent discovery and actual execution + +#### Scenario: Review a visual explanation +- **WHEN** a reader opens the diagrams or tables at desktop or mobile width +- **THEN** the visual and surrounding text describe the same verified behavior and remain readable in light and dark themes +- **AND** the page does not depend on an added rendering service or package + + +### Requirement: Route avatar instructions by operator responsibility +The documentation SHALL separate skill-avatar submission and review from moderation-provider deployment configuration, preserving the existing operational page URL and synchronizing both locales, navigation, and ordered page links. + +#### Scenario: Locate an avatar task +- **WHEN** a skill owner or reviewer opens team-governance guidance +- **THEN** avatar operations and review decisions are available there +- **AND** provider credentials and deployment verification are linked to a distinct deployment guide + +### Requirement: State the scope and limitations of documentation review +A scoped review SHALL NOT be reported as complete verification of all site content. Known unresolved structural issues and unverified technical behavior SHALL remain explicit. + +#### Scenario: Report an incremental review +- **WHEN** a document batch passes source, build, and browser checks +- **THEN** the report distinguishes verified changed paragraphs, site-structure observations, unresolved issues, and unexecuted business or external-service validation diff --git a/openspec/changes/repair-online-documentation/tasks.md b/openspec/changes/repair-online-documentation/tasks.md index 40528b5e0..e9178c668 100644 --- a/openspec/changes/repair-online-documentation/tasks.md +++ b/openspec/changes/repair-online-documentation/tasks.md @@ -16,8 +16,31 @@ - [x] 一次集中独立 Review,修复阻断问题。 - [x] Draft PR 更新为可审查状态,附本批覆盖与后续未完成范围;不自动合并。 -## 3. 后续批次(本 PR 不交付) -- [ ] A6 第二批:深度基准样本与旧模板退场。 +## 3. 分批交付状态 +- [x] A6 第二批:六页深度基准样本与旧模板退场;实施及本地验证完成,待独立 PR 按顺序交付。 - [ ] A6 第三批:公共知识层、链路页及导航重构。 - [ ] A6 第四批:其余页面与 FAQ/接口参考补齐。 - [ ] A6 第五批:全站双语/元数据/排版复核。 + +## 4. 第二批实施与验收 +- [x] DEPTH-1 项目简介:职责边界、相邻概念、具体示例、选择规则和关系图。 +- [x] DEPTH-2 快速开始:完整安装流程、结果样例、无破坏性失败演示和下一步。 +- [x] DEPTH-3 命名空间:按角色分流、治理动作依据、邀请/成员闭环和失败矩阵。 +- [x] DEPTH-4 审核:对象辨识、检查证据、操作顺序、状态结果和失败矩阵。 +- [x] DEPTH-5 收藏评分通知:个人操作闭环、实际通知类别/偏好/保留规则和故障定位。 +- [x] DEPTH-6 安全扫描:配置生效、报告判读、策略/失败分支和诊断闭环。 +- [x] DEPTH-7 六页中英同步,正式文体与图表一致,旧模板退场,D1覆盖及技术来源核查。 +- [x] DEPTH-8 集中独立Review、OpenSpec/构建/链接/锚点、明暗/移动浏览器验收;保留预览,不自动合并。 + + +第二批验证摘要:12个中英文页面、12张SVG,正式文体、来源路径、58个正文链接及示例语法检查通过;OpenSpec严格校验与VitePress构建通过。浏览器首次48次页面检查,图示尺寸修正后补跑受影响页面32次,明暗主题、390px布局、图片加载、图内文字边界及主题/导航交互通过。扫描诊断92项受控回归通过;教程参数失败命令实际返回退出码5且网络调用0次。独立Review未发现实质事实问题;本地视觉检查发现的图示过度放大已修正。不代表实际安装、Agent执行、通知投递或真实部署已验收。第三至第五批仍未完成,第二批不自动合并或发布。 + +## 5. 维护者复核补充 +- [x] VISUAL-CENTER 正文流程图水平居中,保留自然尺寸及移动缩放;浏览器检查实际几何位置。 +- [x] IA-AVATAR 技能头像上传/审核与供应商部署分页面、分导航职责,中英/导航/Pager/交叉链接同步。 +- [x] SITE-AUDIT 逐页核查站点结构、目标读者、导航归属、文书缺口并标注已修/待修/未核实;不得将增量Review汇报为整站通过。 +- [x] 对上述增量独立复核,并更新构建、链接、浏览器及交付说明。 +- [x] FACT-SPOT 全站补查发现的首次角色授权、私有搜索边界、CLI JSON与冲突处置四项问题完成双语局部修正,并保留其余页面缺口。 + + +复核补充验证摘要:全站结构台账覆盖23个中文页面及23个英文镜像,仍有10类明确缺口,未认定全站C10/A7通过。18个新增或重写页面的来源/108正文链接/示例检查通过;全站46页JSON语法与本地文件目标检查通过。实际浏览器覆盖本批24个修改页面的桌面/390px和明暗组合,共96次检查,另有16组头像双页导航归属及Pager检查,均通过。正文流程图水平位置检查通过。新头像部署页只核实现有代码与配置说明,未重新验证真实云账号或生产部署。用户反馈增量由独立Review核查;FAQ跨页指引夸大目标页内容的问题在补查中发现并修正。其余已知问题按逐页台账保留待办,不能因部分修正而标为完成。