docs: expand verified workflows and reorganize documentation
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
|
|
@ -72,7 +72,7 @@ retain that prefix when following application-relative download URLs.
|
|||
|
||||
## 🔐 Authentication
|
||||
|
||||
`skillhub login` uses OAuth Device Flow when no API token is supplied. Token resolution priority for
|
||||
`skillhub login` uses OAuth Device Flow only when no API token is resolved from arguments, environment variables, or saved credentials for the selected registry. An invalid resolved token does not automatically fall back to Device Flow. Token resolution priority for
|
||||
explicit token-based login and all other authenticated commands is:
|
||||
|
||||
1. `--token <token>` command-line argument
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ export default defineConfig({
|
|||
nav: [
|
||||
{ text: '首页', link: '/' },
|
||||
{ text: '快速开始', link: '/quickstart' },
|
||||
{ text: '功能指南', link: '/guide/skill-publish' },
|
||||
{ text: '文档导航', link: '/guide/' },
|
||||
{ text: '开源周报', link: 'https://iflytek.github.io/skillhub/weekly/' },
|
||||
{ text: 'FAQ', link: '/faq' },
|
||||
],
|
||||
|
|
@ -33,32 +33,54 @@ export default defineConfig({
|
|||
items: [
|
||||
{ text: '项目简介', link: '/introduction' },
|
||||
{ text: '快速开始', link: '/quickstart' },
|
||||
{ text: 'CLI 使用指南', link: '/guide/cli' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '核心功能',
|
||||
items: [
|
||||
{ text: 'Skill 发布与版本管理', link: '/guide/skill-publish' },
|
||||
{ text: '技能头像与图片审核接入', link: '/guide/skill-avatars' },
|
||||
{ text: '技能套装:安装与使用', link: '/guide/skill-suites' },
|
||||
{ text: 'Suite Bundle 批量导入', link: '/guide/suite-bundle' },
|
||||
{ text: 'Skill 搜索与发现', link: '/guide/skill-discovery' },
|
||||
{ text: '命名空间与团队管理', link: '/guide/namespace' },
|
||||
{ text: '审核与治理', link: '/guide/review' },
|
||||
{ text: '安全扫描', link: '/guide/scanner' },
|
||||
{ text: '用户交互与社交', link: '/guide/social' },
|
||||
{ text: 'Runtime 集成契约', link: '/guide/runtime-integration' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '更多',
|
||||
items: [
|
||||
{ text: 'Docker 部署与升级', link: '/guide/deployment' },
|
||||
{ text: 'Kubernetes 部署', link: '/guide/kubernetes' },
|
||||
{ text: '账号与访问令牌', link: '/guide/account-access' },
|
||||
{ text: '文档导航', link: '/guide/' },
|
||||
{ text: '常见问题', link: '/faq' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '使用技能',
|
||||
items: [
|
||||
{ text: '搜索与安装技能', link: '/guide/skill-discovery' },
|
||||
{ text: '管理技能套装', link: '/guide/skill-suites' },
|
||||
{ text: 'CLI 使用参考', link: '/guide/cli' },
|
||||
{ text: '收藏、评分与通知', link: '/guide/social' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '创作与发布',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: '发布与更新技能', link: '/guide/skill-publish' },
|
||||
{ text: 'Bundle 导入', link: '/guide/suite-bundle' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '团队与治理',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: '管理命名空间', link: '/guide/namespace' },
|
||||
{ text: '审核技能与套装', link: '/guide/review' },
|
||||
{ text: '安全扫描与报告', link: '/guide/scanner' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '部署与运维',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'Docker 部署', link: '/guide/deployment' },
|
||||
{ text: 'Kubernetes 部署', link: '/guide/kubernetes' },
|
||||
{ text: '技能头像与审核', link: '/guide/skill-avatars' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '开发与集成',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'Runtime 集成参考', link: '/guide/runtime-integration' },
|
||||
{ text: '源码开发手册', link: 'https://github.com/iflytek/skillhub/blob/main/docs/dev-workflow.md' },
|
||||
],
|
||||
},
|
||||
],
|
||||
outline: { label: '页面导航', level: [2, 3] },
|
||||
lastUpdated: { text: '最后更新' },
|
||||
|
|
@ -75,41 +97,64 @@ export default defineConfig({
|
|||
nav: [
|
||||
{ text: 'Home', link: '/en/' },
|
||||
{ text: 'Quick Start', link: '/en/quickstart' },
|
||||
{ text: 'Guide', link: '/en/guide/skill-publish' },
|
||||
{ text: 'Guides', link: '/en/guide/' },
|
||||
{ text: 'Weekly Reports', link: 'https://iflytek.github.io/skillhub/weekly/' },
|
||||
{ text: 'FAQ', link: '/en/faq' },
|
||||
],
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Getting Started',
|
||||
text: 'Start',
|
||||
items: [
|
||||
{ text: 'Introduction', link: '/en/introduction' },
|
||||
{ text: 'Quick Start', link: '/en/quickstart' },
|
||||
{ text: 'CLI Guide', link: '/en/guide/cli' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Core Features',
|
||||
items: [
|
||||
{ text: 'Skill Publishing & Versioning', link: '/en/guide/skill-publish' },
|
||||
{ text: 'Skill Suites: Install & Use', link: '/en/guide/skill-suites' },
|
||||
{ text: 'Suite Bundle Import', link: '/en/guide/suite-bundle' },
|
||||
{ text: 'Skill Search & Discovery', link: '/en/guide/skill-discovery' },
|
||||
{ text: 'Namespace & Team Management', link: '/en/guide/namespace' },
|
||||
{ text: 'Review & Governance', link: '/en/guide/review' },
|
||||
{ text: 'Security Scanning', link: '/en/guide/scanner' },
|
||||
{ text: 'Social & Interaction', link: '/en/guide/social' },
|
||||
{ text: 'Runtime Integration Contract', link: '/en/guide/runtime-integration' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'More',
|
||||
items: [
|
||||
{ text: 'Docker Deployment & Upgrades', link: '/en/guide/deployment' },
|
||||
{ text: 'Kubernetes Deployment', link: '/en/guide/kubernetes' },
|
||||
{ text: 'Quick start', link: '/en/quickstart' },
|
||||
{ text: 'Accounts and access tokens', link: '/en/guide/account-access' },
|
||||
{ text: 'Documentation map', link: '/en/guide/' },
|
||||
{ text: 'FAQ', link: '/en/faq' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Use skills',
|
||||
items: [
|
||||
{ text: 'Find and install skills', link: '/en/guide/skill-discovery' },
|
||||
{ text: 'Manage skill suites', link: '/en/guide/skill-suites' },
|
||||
{ text: 'CLI reference', link: '/en/guide/cli' },
|
||||
{ text: 'Stars, ratings and notifications', link: '/en/guide/social' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Author skills',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'Publish and update skills', link: '/en/guide/skill-publish' },
|
||||
{ text: 'Import a bundle', link: '/en/guide/suite-bundle' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Team governance',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'Manage namespaces', link: '/en/guide/namespace' },
|
||||
{ text: 'Review submissions', link: '/en/guide/review' },
|
||||
{ text: 'Configure scanning', link: '/en/guide/scanner' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Deploy and operate',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'Deploy with Docker', link: '/en/guide/deployment' },
|
||||
{ text: 'Deploy on Kubernetes', link: '/en/guide/kubernetes' },
|
||||
{ text: 'Skill avatars and moderation', link: '/en/guide/skill-avatars' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Develop and integrate',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'Integrate a runtime', link: '/en/guide/runtime-integration' },
|
||||
{ text: 'Development handbook (中文)', link: 'https://github.com/iflytek/skillhub/blob/main/docs/dev-workflow.md' },
|
||||
],
|
||||
},
|
||||
],
|
||||
outline: { label: 'On this page', level: [2, 3] },
|
||||
lastUpdated: { text: 'Last updated' },
|
||||
|
|
|
|||
|
|
@ -85,7 +85,7 @@ A: `BOOTSTRAP_ADMIN_PASSWORD` initializes an account. `BootstrapAdminInitializer
|
|||
|
||||
## Q: Is an email verification code required to change / reset a password?
|
||||
|
||||
A: The current password-change/reset flow uses email verification and requires [SMTP configuration](https://github.com/iflytek/skillhub/blob/main/docs/19-smtp-password-reset-email-setup.md). Bootstrap environment variables do not reset existing passwords.
|
||||
A: The web password-reset flow uses email verification; the authenticated change-password endpoint uses the current password instead. Email reset requires [SMTP configuration](https://github.com/iflytek/skillhub/blob/main/docs/19-smtp-password-reset-email-setup.md). Bootstrap environment variables do not reset existing passwords.
|
||||
|
||||
## Q: Can a skill have a Chinese name?
|
||||
|
||||
|
|
|
|||
75
docs/skillhub/en/guide/account-access.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
# Sign In and Manage Access Tokens
|
||||
|
||||
This guide covers web login, CLI authorization, and API tokens for scripts. Browser sessions, stored CLI credentials, and third-party credentials used by a skill are separate objects. Creating a SkillHub token does not inject external service credentials into skills.
|
||||
|
||||
## Choose a sign-in method
|
||||
|
||||
Open `/login` on your instance and use an available method:
|
||||
|
||||
| Method | Prerequisite | Successful outcome |
|
||||
| --- | --- | --- |
|
||||
| Username and password | Local password login is enabled and you have an account | A browser session is established |
|
||||
| Self-registration | The instance allows registration | Submit username, password, and email; success establishes a session |
|
||||
| Organization or external login | The provider is configured on the instance | Complete external authentication and return to SkillHub |
|
||||
|
||||
A missing registration button is not necessarily a UI failure. The page loads local authentication capabilities and available external methods. Disabling password login or self-registration changes the available entry points. Provider extensibility does not mean every provider is configured.
|
||||
|
||||
Successful login does not grant publishing or administration rights. Account status, platform roles, namespace membership, and resource visibility still govern operations; see [namespace management](./namespace.md).
|
||||
|
||||
## Authorize the CLI
|
||||
|
||||
Select the intended instance before logging in:
|
||||
|
||||
```bash
|
||||
skillhub login --registry https://skillhub.example.com
|
||||
skillhub whoami --registry https://skillhub.example.com
|
||||
```
|
||||
|
||||
`skillhub login` first resolves a token from command-line arguments, environment variables, or stored credentials for the registry, in that order. Device authorization starts only when none is found. An invalid resolved token does not automatically fall back to device authorization. Follow the verification URL and code in the terminal and approve in the browser. On a remote terminal, use `--no-open` and open the URL yourself. Verify the resulting identity with `whoami`.
|
||||
|
||||
Credentials are stored per registry. Changing `--registry` or `SKILLHUB_REGISTRY` does not authenticate you on another instance. Signing into the website alone also does not populate CLI credentials.
|
||||
|
||||
For automation, supply an API token through your runtime's secret-management mechanism. Do not put its real value in skill packages, project source, screenshots, or shared logs. See [CLI reference](./cli.md) for credential precedence.
|
||||
|
||||
## Create an API token
|
||||
|
||||
1. Sign into the website and open `/dashboard/tokens`.
|
||||
2. Create a token with a recognizable purpose-specific name. The UI checks empty names, names longer than 64 characters, and duplicate names visible on the current list page.
|
||||
3. Choose no expiry, 7 days, 30 days, 90 days, or a custom expiration. A custom value must be valid and in the future.
|
||||
4. Copy and securely store the full value immediately after creation. Once the creation result is closed, the list provides summaries such as name, prefix, creation time, expiry, and last use—not the full value again.
|
||||
5. Configure the target client and use `skillhub whoami` to verify the registry and identity.
|
||||
|
||||
A token acts on behalf of its owner; it does not bypass resource permissions. The creation dialog does not grant arbitrary platform roles.
|
||||
|
||||
## Change expiry or revoke a token
|
||||
|
||||
Use the token list to change its expiration or revoke a selected token. Check the updated expiry in the list. Clients using a revoked token must replace their credentials.
|
||||
|
||||
If the full value is lost, do not try to reconstruct it from its prefix. Create a replacement with a new unique name, update clients, and revoke the old token when no longer needed. Server-side creation under an existing name rotates that token and revokes the active predecessor first; the current-page duplicate-name warning cannot guarantee that old credentials remain usable. Revoke suspected compromised credentials promptly and investigate their use.
|
||||
|
||||
```bash
|
||||
# Remove locally stored CLI credentials for this registry only
|
||||
skillhub logout --registry https://skillhub.example.com
|
||||
```
|
||||
|
||||
`logout` does not revoke all server-side API tokens or remove installed skills. A token supplied through an environment variable may still authenticate subsequent commands; check all credential sources when troubleshooting.
|
||||
|
||||
## Password reset versus password change
|
||||
|
||||
For a forgotten password, follow the login page to `/reset-password`, request a code for the account email, and submit the email, code, and new password. This page depends on instance email configuration. A successful request response does not guarantee email delivery or prove that an address is registered.
|
||||
|
||||
The separate `/api/v1/auth/local/change-password` endpoint requires the current authenticated identity and current password. It is not the email-code reset flow; do not assume every password change requires email verification. Manage an external identity provider's password through that provider.
|
||||
|
||||
`BOOTSTRAP_ADMIN_PASSWORD` initializes credentials; it does not reset an existing administrator password. See the [SMTP guide](https://github.com/iflytek/skillhub/blob/main/docs/19-smtp-password-reset-email-setup.md).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Check in order |
|
||||
| --- | --- |
|
||||
| Website signed in but CLI unauthenticated | Confirm the registry, then CLI login and `whoami`; browser cookies are not CLI tokens |
|
||||
| CLI uses the wrong account after login | Check command-line token, `SKILLHUB_TOKEN`, and stored per-registry credentials |
|
||||
| Token cannot call an endpoint | Check expiry/revocation, account/resource permissions, and token scope; retain the public error and `requestId` |
|
||||
| Reset email not received | Check the email address, spam folder, instance SMTP configuration, and logs; do not repeatedly request codes to bypass throttling |
|
||||
| Login returns to the login page | Inspect subsequent identity requests, cookies, proxy, and session configuration; do not clear the database |
|
||||
|
||||
When requesting help, provide the instance version, entry point, public error, and `requestId`. Do not share full tokens, verification codes, passwords, or cookies.
|
||||
|
|
@ -1,7 +1,28 @@
|
|||
# SkillHub CLI
|
||||
# CLI reference
|
||||
|
||||
SkillHub CLI is the official command-line tool for SkillHub, designed for searching, installing, managing, and publishing Agent skill packages.
|
||||
|
||||
## Choose the object you are managing
|
||||
|
||||
| Goal | Command | Scope |
|
||||
| --- | --- | --- |
|
||||
| Install a remote Skill | install | Selected Agent, scope or custom directory |
|
||||
| Update installed skills | upgrade | Explicit coordinates and targets; no implicit upgrade-all |
|
||||
| Manage pinned collections | suite | Suite inventory and member ownership |
|
||||
| Sync team authoring files | sync | Non-global namespace workspace, not Suite lifecycle |
|
||||
| Update the CLI executable | update | CLI installation, not installed skills |
|
||||
| Recover local records | doctor | Project metadata and inventory, not remote upgrades |
|
||||
|
||||
## Automation and failure handling
|
||||
|
||||
Specify `--scope` and `--agent`, or use `--dir` alone, for deterministic installation targets. Do not combine custom directory with scope/agent. Check `version` and `help <command>` against the installed CLI; older releases may not provide every documented capability.
|
||||
|
||||
Keep search, login, install and check on the same registry. Use explicit `--registry` for individual commands or an environment variable for the process tree. Credentials are registry-specific; verify identity with `whoami` after changing endpoints.
|
||||
|
||||
Use `--json` for machine-readable output and do not expect interactive prompts. Capture status and output; retain public error messages and requestId for registry errors. Suite check's `ok: false` may simply indicate changes, so inspect its fields. `--check` is a preview option on applicable upgrade/sync commands, not a universal option.
|
||||
|
||||
For directory conflicts, inspect source ownership before using `--force`: it does not take over unmanaged or different-source targets. Preserve files and metadata before recovering inventory. Do not delete all of `~/.skillhub`; it also holds other registry credentials and installation records.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
|
|
@ -73,7 +94,7 @@ Token resolution priority:
|
|||
|
||||
### Login
|
||||
|
||||
Without a token, `skillhub login` uses OAuth Device Flow: follow the verification URL and user code to authorize in a browser. Use `skillhub login --no-open` on headless terminals, or an API token for automation.
|
||||
When no token is resolved from arguments, environment variables, or saved registry credentials, `skillhub login` uses OAuth Device Flow; an invalid resolved token does not automatically fall back: follow the verification URL and user code to authorize in a browser. Use `skillhub login --no-open` on headless terminals, or an API token for automation.
|
||||
|
||||
```bash
|
||||
# Login with API token
|
||||
|
|
@ -443,7 +464,9 @@ Update mechanism:
|
|||
|
||||
### inventory.json
|
||||
|
||||
CLI-managed installation state; do not hand-edit it. The current disk format uses `schemaVersion: 2`, `records` and optional `suites`. Each target records its version, fingerprint and installedBy sources. Legacy records are read compatibly and migrated on write.
|
||||
CLI-managed installation records, not a file to hand-edit. Each target tracks its own version, fingerprint and ownership; compatible writers migrate legacy records when needed. A backup is recovery evidence, not permission to overwrite a newer inventory.
|
||||
|
||||
Current main contains DSH enable/disable support using inventory v3. Do not assume your published CLI supports it or mix incompatible writers. There are no CLI enable/disable commands. In that increment, disabled targets cannot be upgraded with CLI `--force`, and doctor does not reconstruct disabled ownership from a loose `SKILL.md.disabled` file. Manage activation through a compatible DSH version and follow the matched release instructions.
|
||||
|
||||
## JSON Output
|
||||
|
||||
|
|
@ -491,6 +514,7 @@ Error response format:
|
|||
| 3 | Network error |
|
||||
| 4 | File system error |
|
||||
| 5 | Parameter error |
|
||||
| 6 | Validation or installation ownership conflict |
|
||||
|
||||
## Command Reference
|
||||
|
||||
|
|
|
|||
|
|
@ -17,6 +17,7 @@ Edit `.env.release` before starting:
|
|||
| `SKILLHUB_VERSION` | Pin a published release; `latest` tracks stable releases and `edge` tracks main-branch builds |
|
||||
| `SKILLHUB_PUBLIC_BASE_URL` | The address users actually visit; use HTTPS in production |
|
||||
| `WEB_PORT` / `API_PORT` | Defaults are 80 / 8080; check availability |
|
||||
| `SKILLHUB_DOWNLOAD_ANON_COOKIE_SECRET` | Generate a random value of at least 32 characters; the placeholder prevents startup |
|
||||
| `POSTGRES_PASSWORD` | Set your own database password |
|
||||
| `BOOTSTRAP_ADMIN_ENABLED` / `BOOTSTRAP_ADMIN_PASSWORD` | Decide whether to initialize an administrator; replace the example password when enabled |
|
||||
| Storage | Follow the template and the [object storage guide](https://github.com/iflytek/skillhub/blob/main/docs/object-storage.md) for external storage |
|
||||
|
|
@ -47,3 +48,27 @@ docker compose --env-file .env.release -f compose.release.yml down
|
|||
```
|
||||
|
||||
For startup failures, inspect `ps` and service logs, then check database, Redis, storage, and public URL configuration. Include image versions, redacted logs, and request IDs when reporting a problem, never credentials or `.env.release`. See the [operations reference](https://github.com/iflytek/skillhub/blob/main/docs/09-deployment.md) for Redis, reverse proxies, collection services, and migrations.
|
||||
|
||||
## Configuration and acceptance checks
|
||||
|
||||
Use the release template and Compose file from the same version. `.env.release` supplies Compose interpolation values; only declared variables reach the process. Wire additional settings explicitly through your own override. Recreate affected services after changes; `restart` does not reload container environment values.
|
||||
|
||||
| Layer | Observable result |
|
||||
| --- | --- |
|
||||
| Configuration | Validation has no errors; inspect each warning without sharing secret-bearing output |
|
||||
| Dependencies and processes | Services run in `ps`; server logs show no repeating connection or migration failures |
|
||||
| Public entry | Browser login works at the final URL; CLI `whoami` works against that registry |
|
||||
| Business and persistence | Publish a test skill, follow its final state, install its exact version and inspect `SKILL.md`; resources remain usable after restart |
|
||||
| Runtime dependencies | Package storage is readable/writable and an actual scan completes, not merely the scanner health probe |
|
||||
|
||||
Set `SESSION_COOKIE_SECURE=true` for production HTTPS. Sub-path deployments require aligned `SKILLHUB_WEB_BASE_PATH=/skillhub/`, same-origin `SKILLHUB_WEB_API_BASE_URL=/skillhub`, and a public URL ending in `/skillhub`. The public URL does not configure TLS certificates, proxying or DNS for you.
|
||||
|
||||
| Symptom | First checks |
|
||||
| --- | --- |
|
||||
| Configuration rejected | Example passwords, anonymous-download secret length, storage provider and required S3 settings |
|
||||
| Page loads but API returns 502 | Server logs, migrations, API upstream and container networking |
|
||||
| Wrong OAuth/device-flow URL | Public URL, domain and sub-path alignment |
|
||||
| Changes have no effect | Correct Compose project, preserved overrides, explicit environment wiring and recreation |
|
||||
| Scan never finishes | Scanner logs/configuration and backend connectivity; failure is not approval |
|
||||
|
||||
Back up PostgreSQL, skill/avatar storage, private configuration and encryption keys. Restore with matching application/configuration versions and verify login and download in an isolated environment. Deleting volumes or clearing the database is not a default upgrade-recovery step.
|
||||
|
|
|
|||
45
docs/skillhub/en/guide/index.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# Documentation map
|
||||
|
||||
Choose the task you want to complete. Start with [Quick Start](../quickstart.md) to install your first skill; deployment and development guides are not prerequisites.
|
||||
|
||||
## Start
|
||||
|
||||
- [Accounts and access tokens](./account-access.md): web sign-in, CLI authorization, token expiry, and password reset.
|
||||
- [Introduction](../introduction.md): understand the registry's purpose.
|
||||
- [Quick start](../quickstart.md): find, install, and use a skill in your Agent.
|
||||
- [FAQ](../faq.md): troubleshoot login, installation, and configuration.
|
||||
|
||||
## Use skills
|
||||
|
||||
| Your task | Read |
|
||||
| --- | --- |
|
||||
| Find a skill and inspect its versions and visibility | [Find and install skills](./skill-discovery.md) |
|
||||
| Install pinned members together and start with their entry skill | [Manage skill suites](./skill-suites.md) |
|
||||
| Choose an Agent and scope; update, remove, or sync a workspace | [CLI reference](./cli.md) |
|
||||
| Save and rate skills, and check notifications | [Stars, ratings and notifications](./social.md) |
|
||||
|
||||
## Author skills
|
||||
|
||||
Prepare `SKILL.md` and its supporting files, then submit. An accepted submission still needs its scan, review, and final version state checked.
|
||||
|
||||
- [Publish and update skills](./skill-publish.md): package structure, metadata, uploading, and version management.
|
||||
- [Import a bundle](./suite-bundle.md): upload content as an author, inspect member changes, and confirm. To install an existing suite, use the guide above.
|
||||
|
||||
## Team governance
|
||||
|
||||
- [Manage namespaces](./namespace.md): members, roles, and resource visibility.
|
||||
- [Review submissions](./review.md): handle Skill and Suite applications.
|
||||
- [Configure scanning](./scanner.md): connect the scanning service and interpret results.
|
||||
|
||||
## Deploy and operate
|
||||
|
||||
Read these guides when you need to run your own registry. Choose a deployment method before configuring optional integrations.
|
||||
|
||||
- [Deploy with Docker](./deployment.md): installation, configuration, upgrades, and backups.
|
||||
- [Deploy on Kubernetes](./kubernetes.md): cluster and Helm deployment.
|
||||
- [Skill avatars and moderation](./skill-avatars.md): administrator configuration for image moderation providers.
|
||||
|
||||
## Develop and integrate
|
||||
|
||||
- [Integrate a runtime](./runtime-integration.md): registry API contracts for external runtimes.
|
||||
- [Development handbook (Chinese)](https://github.com/iflytek/skillhub/blob/main/docs/dev-workflow.md): local development and repository checks.
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Kubernetes Deployment Guide
|
||||
# Kubernetes Deployment: Kustomize Configuration and Verification
|
||||
|
||||
This document explains how to deploy SkillHub on a Kubernetes cluster.
|
||||
|
||||
|
|
@ -68,6 +68,14 @@ cp base/secret.yaml.example base/secret.yaml
|
|||
| skill-scanner-llm-base-url | Local/custom LLM service base URL | No |
|
||||
| skill-scanner-llm-model | LLM model name used by the scanner | No |
|
||||
|
||||
Apply the completed Secret separately. The current Kustomization does not include `base/secret.yaml`; copying the file does not create it in the cluster:
|
||||
|
||||
```bash
|
||||
kubectl apply -n skillhub -f base/secret.yaml
|
||||
```
|
||||
|
||||
Also add the public URL and anonymous-download signing secret to your backend overlay; see “Complete environment wiring before deployment” below.
|
||||
|
||||
### 3. Choose Deployment Method
|
||||
|
||||
**Option 1: Full Deployment (with PostgreSQL + Redis)**
|
||||
|
|
@ -299,3 +307,33 @@ kubectl delete -k overlays/with-infra/ # or overlays/external/
|
|||
# Delete namespace
|
||||
kubectl delete namespace skillhub
|
||||
```
|
||||
|
||||
## Complete environment wiring before deployment
|
||||
|
||||
The base manifests do not automatically pass every application setting. Add the required environment entries to the `server` container in your `skillhub-server` Deployment overlay:
|
||||
|
||||
```yaml
|
||||
- name: SKILLHUB_PUBLIC_BASE_URL
|
||||
value: https://skills.example.com
|
||||
- name: SKILLHUB_DOWNLOAD_ANON_COOKIE_SECRET
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: skillhub-secret
|
||||
key: download-anon-cookie-secret
|
||||
```
|
||||
|
||||
Add `download-anon-cookie-secret` under `stringData` in your private `base/secret.yaml`, using a random value of at least 32 characters. Replace the public URL. Startup rejects the default anonymous-download secret placeholder. Keep the public URL, Ingress host, TLS and secure-cookie settings aligned; Ingress does not issue certificates automatically.
|
||||
|
||||
For S3 storage, also map the Secret keys `skillhub-storage-s3-access-key` and `skillhub-storage-s3-secret-key` through `secretKeyRef` to `SKILLHUB_STORAGE_S3_ACCESS_KEY` and `SKILLHUB_STORAGE_S3_SECRET_KEY`. Merely adding keys to a Secret does not inject them into the process. Explicitly wire settings absent from the base manifest, including Suite review and Bundle confirmation controls; Compose defaults do not apply here.
|
||||
|
||||
## Upgrade and verify
|
||||
|
||||
1. Pin application image `newTag` values in `base/kustomization.yaml`. Preserve the previous version and overlay, and back up the database, storage and private Secrets.
|
||||
2. Render the selected overlay locally. Check images, environment references, Ingress, PVCs and namespace; do not publish rendered Secrets.
|
||||
3. Apply configuration, wait for `kubectl rollout status deployment/skillhub-server -n skillhub`, then inspect Pod events and logs. ConfigMap/Secret changes do not automatically refresh running process environments; roll affected Deployments during an appropriate maintenance window.
|
||||
4. From the actual entrypoint, verify login, search, a test publication and its scan/review, and an exact-version download. Ready probes alone do not establish business acceptance.
|
||||
5. For a failed upgrade, inspect migrations and dependencies before rollback. Check schema compatibility and retain PVCs; deleting a namespace is not a retry procedure.
|
||||
|
||||
For `CreateContainerConfigError`, check that referenced Secrets and required keys exist. For `CrashLoopBackOff`, inspect startup logs. For `Pending`, check PVCs and scheduling capacity. Do not expose Secret data during troubleshooting.
|
||||
|
||||
A separate [Helm Chart](https://github.com/iflytek/skillhub/tree/main/charts/skillhub) is available. Follow its README for values, Secrets and dependencies rather than mixing Helm instructions with this guide's Kustomize paths.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,21 @@
|
|||
# Namespace & Team Management
|
||||
# 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.
|
||||
|
||||
## A Team Onboarding Sequence
|
||||
|
||||
1. Create a team namespace in My Namespaces with a stable slug and a readable display name. The slug is part of installation coordinates and cannot change with the team name.
|
||||
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.
|
||||
|
||||
### Why Available Actions Differ
|
||||
|
||||
The page uses namespace type, state and server-provided capabilities to display freeze, unfreeze, archive, restore and delete actions. Owner or Admin is not an unconditional grant for every action. Owners and Admins can edit an ACTIVE team namespace; authorized Owners have a separate ownership transfer action. Frozen or archived namespaces make membership management read-only, while eligible administrators can still read invitation history.
|
||||
|
||||
Freezing temporarily stops writes; unfreezing restores them. Archiving and permanent deletion are distinct. Check the target and impact in the confirmation, then verify the resulting namespace state and member page instead of relying only on a successful request.
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
@ -70,7 +87,7 @@ Discover a security issue in the namespace and temporarily freeze all publish op
|
|||
2. Click the "Members" tab
|
||||
3. Click "Add Member"
|
||||
4. Search for users (supports searching by username, email)
|
||||
5. Select a role (Owner / Admin / Member)
|
||||
5. Select Admin or Member; ownership transfer is a separate flow
|
||||
6. Confirm to add
|
||||
|
||||
**Invite with a link**:
|
||||
|
|
|
|||
|
|
@ -1,4 +1,18 @@
|
|||
# Review & Governance
|
||||
# Review Skills and Suites
|
||||
|
||||
## Reviewer Checklist
|
||||
|
||||
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.
|
||||
|
||||
### Tracking and Revising as an Author
|
||||
|
||||
Use My Submissions to read status and decisions. Pending requests can be withdrawn when authorized. Withdrawal stops that review; it does not delete the prior published version or undo an approved global promotion. After rejection, revise according to the comments and use the supported resubmission action. A successful upload does not by itself reopen review.
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
@ -74,7 +88,7 @@ A user reports an inappropriate skill package, and an administrator investigates
|
|||
- Download the full package for local testing
|
||||
- Review the compliance snapshot and the diff from the previous published version
|
||||
|
||||

|
||||

|
||||
|
||||
The review section follows the PUBLIC / NAMESPACE_ONLY branch: scanning completes before the version waits for a review decision.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Runtime Integration Contract
|
||||
# Runtime Integration: Version Resolution, Downloads, and Compliance Snapshots
|
||||
|
||||
## Responsibility Boundary
|
||||
|
||||
|
|
@ -20,7 +20,7 @@ When Runtime needs to connect an execution trace with SkillHub compliance declar
|
|||
| `registryUrl` | Runtime configuration | SkillHub registry URL |
|
||||
| `namespace` | SkillHub coordinate | Skill namespace, such as `global` or a team slug |
|
||||
| `skillSlug` | SkillHub coordinate | Skill slug |
|
||||
| `requestedVersion` | Runtime request | User-requested version, tag, or range |
|
||||
| `requestedVersion` | Runtime request | User-requested exact version or tag |
|
||||
| `resolvedVersion` | SkillHub response | Exact resolved version |
|
||||
| `skillVersionId` | Version `id` from SkillHub response | Immutable version ID and the primary audit join key |
|
||||
| `complianceSnapshotDigest` | `complianceSnapshot.digest` | Stable digest of the version-level compliance declaration snapshot |
|
||||
|
|
@ -90,12 +90,46 @@ An audit system can then start from the Runtime trace, locate the exact executio
|
|||
- Do not treat SkillHub compliance declarations as third-party certification.
|
||||
- Do not require SkillHub to record model inputs and outputs; that belongs to the Runtime audit boundary.
|
||||
|
||||
## Possible Future API
|
||||
## Resolve, inspect, then download
|
||||
|
||||
If a clear consumer appears, such as Runtime needing only the compliance snapshot without full skill details, SkillHub can add an immutable version-level endpoint:
|
||||
Choose the registry, skill coordinate and caller identity first. These are HTTP request examples, not shell commands; replace the example coordinate with a real resource.
|
||||
|
||||
```text
|
||||
GET /api/skill-versions/{skillVersionId}/compliance
|
||||
```http
|
||||
GET /api/v1/skills/global/example-skill/resolve?version=1.2.0
|
||||
GET /api/v1/skills/global/example-skill/versions/1.2.0
|
||||
GET /api/v1/skills/global/example-skill/versions/1.2.0/download
|
||||
```
|
||||
|
||||
For now, reuse the version detail response to avoid designing multiple APIs before the caller contract is stable.
|
||||
`version` is exact; use `tag` for a tag, and do not supply both. This endpoint does not resolve ranges such as `^1.2.0`. Resolution returns `skillId`, `namespace`, `slug`, `version`, `versionId`, `fingerprint`, `matched`, and `downloadUrl`. Use that exact version for subsequent requests rather than resolving `latest` again before execution.
|
||||
|
||||
Version details use the common response envelope. This illustrative example omits some detail fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"id": 123,
|
||||
"version": "1.2.0",
|
||||
"status": "PUBLISHED",
|
||||
"fileCount": 2,
|
||||
"totalSize": 2048,
|
||||
"complianceSnapshot": null
|
||||
},
|
||||
"timestamp": "2026-01-01T00:00:00Z",
|
||||
"requestId": "example-request-id"
|
||||
}
|
||||
```
|
||||
|
||||
A null snapshot can mean no declaration or historical metadata that cannot be projected. Do not invent a digest. The registry package `fingerprint` and compliance snapshot `digest` identify different content. If you hash the downloaded ZIP yourself, record its algorithm and object separately; do not assume it equals the registry fingerprint.
|
||||
|
||||
Downloads return either ZIP bytes or a `302` with an object-storage `Location`. Do not forward registry credentials to the storage host when following a redirect. The CLI provides an existing installation and validation flow. A temporary download URL is not a durable resource identifier.
|
||||
|
||||
## Permissions and failure handling
|
||||
|
||||
- Anonymous callers can read visible public published resources. Restricted resources still require the appropriate identity, namespace membership or ownership; an anonymously accessible route does not make every resource public.
|
||||
- Version details support authorized maintainer previews. Readability does not imply installability: resolution requires an installable version. Record and check `status`; do not treat pending preview content as a published release.
|
||||
- Stop on missing, inaccessible or unavailable versions. Do not silently substitute another skill, registry or latest version.
|
||||
- Retain request IDs and redacted errors for investigation, not tokens, signed URLs or secrets from runtime inputs.
|
||||
|
||||
Verify at least public resolution and download, anonymous rejection of restricted resources, explicit failure for unavailable versions, null snapshots, and credential-safe redirects. Execution traces remain in the runtime's own system; these endpoints do not accept execution results.
|
||||
|
|
|
|||
|
|
@ -1,10 +1,27 @@
|
|||
# Skill Scanner Security Scanning
|
||||
# Configure and Inspect Security Scans
|
||||
|
||||
## Reading a Report as an Author or Reviewer
|
||||
|
||||
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.
|
||||
|
||||
- `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
|
||||
|
||||
1. Check the effective Scanner URL and mode. The table below lists application defaults; release Compose uses `upload`. A container's localhost is not the host's localhost.
|
||||
2. Check `/health` from the backend's network, then inspect actual scan requests and responses. Health alone does not prove a package was scanned.
|
||||
3. Correlate version, request time and backend/Scanner logs. Distinguish temporary connectivity failures from analysis errors. Temporary unavailability can leave work pending for reclaim; waiting alone does not prove failure.
|
||||
4. After repairing service or configuration, follow the original task. Retain version ID, status and error details for investigation without exposing package secrets or credentials.
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
SkillHub includes a built-in **Skill Scanner** security scanning service that automatically detects potential security risks when skill packages are published. This serves as a critical line of defense for ensuring the security of skill packages within an enterprise.
|
||||
|
||||
Every skill package undergoes a security scan after publication. The scan results inform review decisions and help administrators quickly assess whether a skill package is safe and reliable.
|
||||
Uploads with scanning enabled undergo a security scan. The scan results inform review decisions and help administrators quickly assess whether a skill package is safe and reliable.
|
||||
|
||||
**Key Features**:
|
||||
|
||||
|
|
@ -18,8 +35,8 @@ Every skill package undergoes a security scan after publication. The scan result
|
|||
|
||||
| Engine | Description | Default Status |
|
||||
|------|------|----------|
|
||||
| **Metadata Analysis** | Checks package structure, file types, sizes, etc. | Enabled |
|
||||
| **Behavioral Analysis** | Analyzes code behavior patterns to detect malicious operations | Optional |
|
||||
| **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 |
|
||||
|
|
|
|||
123
docs/skillhub/en/guide/skill-avatars.md
Normal file
|
|
@ -0,0 +1,123 @@
|
|||
# Skill Avatars: Uploads, Review, and Provider Configuration
|
||||
|
||||
This guide covers skill avatars, not account profile pictures. Image moderation is separate from skill-package security scanning.
|
||||
|
||||
## Upload or replace an avatar
|
||||
|
||||
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.
|
||||
|
||||
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 |
|
||||
| --- | --- | --- |
|
||||
| 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 |
|
||||
|
||||
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.
|
||||
|
||||
| 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 |
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
| 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](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.
|
||||
|
||||
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 |
|
||||
|
|
@ -1,120 +1,74 @@
|
|||
# Skill Search & Discovery
|
||||
# Find and install skills
|
||||
|
||||
## Overview
|
||||
Find a skill in an existing registry, inspect an available version, then install it for your Agent. Search results, Web details, and local installation are separate stages: seeing a card does not mean the skill is installed.
|
||||
|
||||
SkillHub provides powerful full-text search functionality, enabling users to quickly find the skill packages they need.
|
||||
## Before you start
|
||||
|
||||
Search supports not only keyword matching but also multi-dimensional filtering and sorting by namespace and tag, with relevance, download-count and newest sorting.
|
||||
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.
|
||||
|
||||
## Search in the Web UI
|
||||
|
||||
1. Use the homepage search box or open `/search`; enter a task keyword such as `pdf`.
|
||||
2. Restrict to a namespace with `@team pdf`, or browse it with `@team`. Replace `team` with a real namespace slug.
|
||||
3. Select a label to narrow results; select it again to clear it. The current Web selector allows one label at a time.
|
||||
4. Sort by relevance, downloads, or newest. The Web default is newest; rating is not a separate sort option.
|
||||
5. Open a card and inspect the coordinate, instructions, versions and files before installing.
|
||||
|
||||
Query, namespace, label, sort and page are retained in the URL, so links can be shared and results revisited. Queries are limited to their first 50 characters; reduce a long task description to keywords.
|
||||
|
||||
## Search only your stars
|
||||
|
||||
Enable the starred-only filter after signing in; anonymous users are directed to login. This mode matches names, summaries, namespaces and slugs within fetched starred skills rather than running the ordinary full-text search. It supports namespace filtering and download sorting; relevance and newest both sort by update time. The current starred branch does not apply label filtering: turn it off before searching by label.
|
||||
|
||||
`/dashboard/stars` provides paginated browsing. See [Stars, ratings and notifications](./social.md).
|
||||
|
||||
## Decide what to install
|
||||
|
||||
Read the instructions and check required scripts, tools and services. Install with `@namespace/slug`; a display-name change does not change this coordinate.
|
||||
|
||||
A related-Suite badge means the skill belongs to a Suite visible to you. Details distinguish entry and ordinary members and show companion skills. One skill can belong to multiple Suites. Use the [Suite guide](./skill-suites.md) for the collection, or install the skill independently.
|
||||
|
||||
## Install and verify with the CLI
|
||||
|
||||
Replace the example coordinate with a real search result. Keep the default registry and your private instance distinct.
|
||||
|
||||
```bash
|
||||
skillhub search pdf
|
||||
# Run from the target project root
|
||||
skillhub install @team/example-skill --scope project --agent codex
|
||||
skillhub list --agent codex
|
||||
# Pin a specific release when needed
|
||||
skillhub install @team/example-skill --version 1.0.0 --scope project --agent codex
|
||||
```
|
||||
|
||||
Ordinary CLI search returns Skills, not Suites. It does not expose all Web filters; check `skillhub help search`. Add `--registry https://skillhub.example.com` for a self-hosted instance.
|
||||
|
||||
Check the reported destination and its `SKILL.md`, let your Agent discover the skill, then provide a task. Downloading a ZIP only obtains files; it does not place them in an Agent directory. See [CLI reference](./cli.md) for upgrades, conflicts and removal.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Check and action |
|
||||
| --- | --- |
|
||||
| No results | Clear label, namespace and starred-only filters; try a shorter keyword and verify the registry |
|
||||
| A colleague can see it | Verify identity and namespace permissions; PRIVATE is not shared with every member |
|
||||
| A new submission is missing | Check its scan/review state in My Skills; accepted is not published, and indexing may lag |
|
||||
| Visible card, failed download | Reopen details and check the version, permissions and current resource state; retain the error and requestId |
|
||||
| Agent does not discover the installation | Check project root, scope, agent and SKILL.md against CLI output; reload using the Agent's mechanism |
|
||||
|
||||
Search rank is not a safety or quality certification. Read instructions and scan results before choosing.
|
||||
|
||||
## Search API boundaries
|
||||
|
||||
```text
|
||||
GET /api/web/skills?q=pdf&namespace=team&label=data-processing&sort=downloads&page=0&size=20
|
||||
```
|
||||
|
||||
`q`, `namespace` and `label` are optional. The API accepts repeated labels, while the Web selector is single-select. Sort values are `relevance`, `downloads` and `newest`; pages start at zero. API pages default to 20 items; the Web page uses 12. Results include `items`, `total`, `page` and `size`, filtered for the current identity. Consult the instance OpenAPI for the response envelope.
|
||||
|
||||
## Visual walkthrough
|
||||
|
||||

|
||||
|
||||
**Core Features**:
|
||||
|
||||
- **Full-text Search**: Search skill package names, descriptions, tags, authors
|
||||
- **Smart Filters**: Filter by namespace, tag, visibility
|
||||
- **Multiple Sorting**: Sort by relevance, downloads, newest
|
||||
- **Permission-aware**: Only show skill packages user has access to
|
||||
- **Real-time Updates**: Published, visible skill packages become searchable after index refresh
|
||||
|
||||
**Search Algorithm**:
|
||||
|
||||
SkillHub uses PostgreSQL full-text search, supporting:
|
||||
- Chinese and English word segmentation
|
||||
- Fuzzy matching
|
||||
- Weighted ranking (title weight > description weight > tag weight)
|
||||
|
||||
## Use Cases
|
||||
|
||||
**Case 1: New Member Exploration**
|
||||
|
||||
New developer joins the team and wants to know what skill packages are available.
|
||||
|
||||

|
||||
|
||||
**Case 2: On-Demand Search**
|
||||
|
||||
Developer needs a PDF processing skill package, searches for "pdf" keyword.
|
||||
|
||||
**Case 3: Browse Popular**
|
||||
|
||||
View skill packages with highest downloads and best ratings in the team, learn best practices.
|
||||
|
||||
**Case 4: Filter by Tag**
|
||||
|
||||
Only view skill packages with `data-processing` tag.
|
||||
|
||||
## Steps
|
||||
|
||||
### Using CLI to Search and Install (Recommended)
|
||||
|
||||
```bash
|
||||
# Configure registry
|
||||
export SKILLHUB_REGISTRY=http://localhost:8080
|
||||
|
||||
# Search skill packages
|
||||
npx @astron-team/skillhub@latest search pdf
|
||||
|
||||
# Install skill package
|
||||
npx @astron-team/skillhub@latest install pdf-parser
|
||||
|
||||
# Install skill package from specific namespace
|
||||
npx @astron-team/skillhub@latest install my-team--pdf-parser
|
||||
```
|
||||
|
||||
### Using Web UI to Search
|
||||
|
||||
1. **Access Search Page**
|
||||
|
||||
Visit `http://localhost:3000/search` or use the search box on the homepage.
|
||||
|
||||
2. **Enter Keywords**
|
||||
|
||||
Enter keywords in the search box, e.g., "pdf parser".
|
||||
|
||||
3. **Apply Filters**
|
||||
|
||||
- Select namespace (e.g., only `iflytek` namespace)
|
||||
- Select tag (e.g., `data-processing`)
|
||||
- Select sort order (e.g., by downloads descending)
|
||||
|
||||

|
||||
|
||||
4. **View Results**
|
||||
|
||||
Search results update in real-time, showing matching skill package list.
|
||||
|
||||
5. **View Details**
|
||||
|
||||
Click skill package card to view detailed information, version history, file list.
|
||||
|
||||
6. **Install**
|
||||
|
||||
After finding the right skill package, use CLI command to install or click "Download" button.
|
||||
|
||||
## API Reference
|
||||
|
||||
**Search Skill Packages**:
|
||||
```bash
|
||||
GET /api/web/skills?q=pdf&namespace=iflytek&label=data-processing&sort=downloads&page=0&size=20
|
||||
```
|
||||
|
||||
**Parameter Reference**:
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| q | string | Search keyword (optional) |
|
||||
| namespace | string | Namespace filter (optional) |
|
||||
| label | string[] | Tag filter (optional, multiple allowed) |
|
||||
| sort | enum | Sort by: relevance, downloads, newest |
|
||||
| page | number | Page number (starts from 0) |
|
||||
| size | number | Page size (default 20, max 100) |
|
||||
|
||||
Use the deployed OpenAPI schema for response fields and pagination envelopes.
|
||||
|
||||
## Notes
|
||||
|
||||
> **Permission Control**: Search results are automatically filtered by user permissions. NAMESPACE_ONLY content is available to namespace members. PRIVATE content is restricted to its owner and authorized administrators, not all members or logged-in users.
|
||||
|
||||
- **Search Performance**: SkillHub uses PostgreSQL full-text search with Chinese and English word segmentation
|
||||
- **Real-time Updates**: Published, visible skill packages become searchable after index refresh
|
||||
- **Tag Convention**: Recommend using consistent tag naming conventions for easier filtering
|
||||
- **Search Suggestions**: Supports search suggestions and autocomplete (frontend implementation)
|
||||
|
|
|
|||
|
|
@ -1,4 +1,44 @@
|
|||
# Skill Publishing & Version Management
|
||||
# Publish and Update Skills
|
||||
|
||||
## From Local Files to an Installable Version
|
||||
|
||||
A single-skill upload has one root `SKILL.md`. For multiple skills, use [Suite import](/en/guide/suite-bundle); do not place unrelated skills in one single-skill ZIP.
|
||||
|
||||
1. Exercise the instructions, scripts and relative references in your local Agent, then prepare a standalone directory.
|
||||
2. Choose a writable namespace and PUBLIC, NAMESPACE_ONLY or PRIVATE visibility. Document dependencies: publishing does not distribute your local environment.
|
||||
3. Check the package preview, version, summary and warnings before submitting. Fix blocking errors; acknowledging a warning does not prove the package passed every check.
|
||||
4. Follow the submitted version in My Skills through scanning, review or private publication confirmation.
|
||||
5. Check access as an intended recipient, install in the target Agent and invoke it. Registry publication does not establish task effectiveness.
|
||||
|
||||
### Package Layout and Version Choice
|
||||
|
||||
```text
|
||||
my-skill/
|
||||
├── SKILL.md
|
||||
├── scripts/ # Only when the skill needs scripts
|
||||
└── references/ # Only when instructions reference these files
|
||||
```
|
||||
|
||||
Relative references must resolve inside the package. Exclude credentials, caches and unrelated project files. `version` is optional: the server generates a time-based version when absent. Set it explicitly, for example `1.0.0` then `1.0.1`, for predictable releases. Top-level `version` takes precedence over `metadata.version`; do not supply conflicting values.
|
||||
|
||||
### Updating an Existing Skill
|
||||
|
||||
Use Update in My Skills or publish again to the same namespace and skill name. Verify the coordinate: changing `name` may create a different skill. Published versions cannot be overwritten; use a new version for normal updates. While it awaits review, public users retain the previously published version. After approval, check the displayed version, title and summary.
|
||||
|
||||
Existing local installations do not update automatically. Consumers explicitly upgrade through the CLI. Suite members remain pinned until a new Suite version is published.
|
||||
|
||||
### Recovering from Submission Problems
|
||||
|
||||
| Symptom | Next step |
|
||||
| --- | --- |
|
||||
| Invalid frontmatter | Fix YAML and required fields, then preview again |
|
||||
| Suspected secret or disallowed file | Remove sensitive content or fix the package; warning confirmation cannot bypass blocking errors |
|
||||
| Version already exists | Inspect the existing version and use a new version for a normal update |
|
||||
| Scan in progress | Wait for its status instead of repeatedly uploading the same version |
|
||||
| `SCAN_FAILED` | Read the failure and use the retry action offered by the page; ask an operator to resolve infrastructure failures |
|
||||
| Review rejected | Read the decision, revise the package and use the supported resubmission flow |
|
||||
| Frozen namespace or removed membership | Restore legitimate write access first; a previously installed copy grants no publishing rights |
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
@ -21,7 +61,7 @@ SkillHub provides an npm-like publishing experience with enterprise-grade permis
|
|||
- **Semantic Versioning**: Supports `major.minor.patch` version specification
|
||||
- **Tag System**: `latest`, `beta`, `stable` and custom tags
|
||||
- **Multi-version Coexistence**: Same skill package can retain multiple historical versions
|
||||
- **Version Resolution**: Smart parsing of version selectors (e.g., `^1.2.0`, `~2.0.0`)
|
||||
- **Version Resolution**: Resolve exact versions, tags or fingerprints; `^` / `~` ranges are not supported
|
||||
- **File Browsing**: Browse skill package file structure online
|
||||
- **Download Distribution**: Download by version or tag
|
||||
|
||||
|
|
@ -128,7 +168,7 @@ file: skill-package.zip
|
|||
visibility: PUBLIC
|
||||
```
|
||||
|
||||

|
||||

|
||||
|
||||
The diagram covers ordinary uploads; scan failures, review rejection and privileged publishing are described below.
|
||||
|
||||
|
|
@ -239,15 +279,15 @@ GET /api/v1/skills/{namespace}/{slug}/tags/{tagName}/download
|
|||
|
||||
**Version Resolution**:
|
||||
```bash
|
||||
GET /api/v1/skills/{namespace}/{slug}/resolve?version=^1.2.0
|
||||
GET /api/v1/skills/{namespace}/{slug}/resolve?version=1.2.0
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
> **Version Specification**: SkillHub uses Semantic Versioning. Version format is `major.minor.patch`, e.g., `1.2.3`.
|
||||
> **Version Specification**: Use explicit `major.minor.patch` versions such as `1.2.3` for predictable releases; omission produces a server-generated time version.
|
||||
|
||||
- **First Publish**: Version should start from `0.1.0` or `1.0.0`
|
||||
- **Tag Management**: `latest` tag automatically points to the latest stable version
|
||||
- **Tag Management**: `latest` follows publication state and the published pointer, not client-side selection of the highest SemVer
|
||||
- **Review Process**: Ordinary PUBLIC / NAMESPACE_ONLY uploads require scanning and review; PRIVATE uploads require publish confirmation
|
||||
- **File Size Limit**: Single skill package max 100MB (configurable)
|
||||
- **Naming Convention**: Skill slug supports lowercase letters, numbers, hyphens, and Unicode characters
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Skill Suites: install and use
|
||||
# Manage Skill Suites
|
||||
|
||||
A Skill Suite is a separately versioned collection of exact published Skill versions with one Entry Skill. Each member remains an independent Skill after installation.
|
||||
|
||||
|
|
@ -12,7 +12,7 @@ A Skill Suite is a separately versioned collection of exact published Skill vers
|
|||
|
||||
A [Bundle](./suite-bundle) is an authoring format. A Suite is not a workflow runtime: coordination depends on the entry and member instructions. A Skill can still be installed independently.
|
||||
|
||||

|
||||

|
||||
|
||||
Installation ends at separate member files. Agent usage starts with an explicit task.
|
||||
|
||||
|
|
@ -72,3 +72,26 @@ skillhub suite remove @team/example-suite
|
|||
Use the Web editor to select published members and an entry, or import a [Suite Bundle](./suite-bundle) to upload local members. PUBLIC and NAMESPACE_ONLY Suites require Suite-level review; PRIVATE Suites can publish directly. Member Skills retain their own scan and review workflows.
|
||||
|
||||
A version supports up to 100 distinct members and requires one member as entry. Nested Suites, version ranges and external-registry members are unsupported. The CLI manages installations; it does not provide `suite publish` or import authoring manifests.
|
||||
|
||||
## Read local check results
|
||||
|
||||
`skillhub suite check` reads inventory and remote Suite state; it is not fully offline. Member `ok` means directory content matches the pinned fingerprint, `missing` means the directory is absent, and `modified` means content changed. The whole Suite is `current` only when the remote latest version matches, the installed version remains installable, and every member is `ok`.
|
||||
|
||||
JSON `ok: false` can indicate detected changes rather than a thrown command error. Automation should inspect member and remote state, not just the process exit code.
|
||||
|
||||
## Shared members and upgrade decisions
|
||||
|
||||
Suites may reuse a member directory with the same source and content. If another Suite owns that target, upgrading this Suite cannot replace its version in place. `--force` does not bypass shared-source protection. Inspect both plans and choose compatible versions or separate installation targets.
|
||||
|
||||
Install and upgrade download and verify all members before committing directories and inventory. A mid-commit failure attempts to restore replaced directories. Preserve the error and run `check` again; do not edit inventory to manufacture success.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Action |
|
||||
| --- | --- |
|
||||
| Unknown Suite action | Supported actions are install, check, upgrade and remove, not run/publish |
|
||||
| Server capability missing | Verify registry and server version; ordinary install does not install a Suite |
|
||||
| Modified member | Preserve needed edits before deciding whether to replace them |
|
||||
| Member withdrawn or access narrowed | Historical pins remain, but the plan blocks installation; ask the maintainer for an installable release |
|
||||
| Removal says Preserved | Inspect shared, modified or missing reason; retention does not itself mean failure |
|
||||
| Agent option rejected for check/remove | Target options belong to install; later actions use the saved Suite record |
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# User Interaction & Social Features
|
||||
# Stars, ratings and notifications
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
@ -20,7 +20,7 @@ SkillHub provides a rich set of social features that allow team members to inter
|
|||
| **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 |
|
||||
| **Activity** | Last updated time, release frequency |
|
||||
| **Updated time** | Update time shown in the current list |
|
||||
|
||||
## Use Cases
|
||||
|
||||
|
|
@ -36,7 +36,7 @@ After using a skill package, a developer gives it a rating and review to help ot
|
|||
|
||||
**Case 3: Viewing Notifications**
|
||||
|
||||
A developer receives a notification that their submission has been approved, or someone has commented on their skill package.
|
||||
A developer receives a notification that their submission has been approved, or another supported governance event occurs.
|
||||
|
||||

|
||||
|
||||
|
|
@ -83,9 +83,30 @@ been removed. Custom clients should poll `GET /api/v1/notifications` and
|
|||
|
||||
1. Navigate to `/dashboard/stars`
|
||||
2. View all starred skill packages
|
||||
3. Sort by star date or last updated date
|
||||
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**:
|
||||
|
|
@ -160,4 +181,4 @@ Responses use the standard API envelope. `GET .../star` returns a boolean in `da
|
|||
- **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**: Each download increments the download counter, which is used for popularity ranking
|
||||
- **Download Statistics**: Published-version downloads record counts; review-preview downloads do not count as public downloads
|
||||
|
|
|
|||
|
|
@ -1,9 +1,29 @@
|
|||
# Suite Bundle Import
|
||||
# Import Skill Suites with Bundles
|
||||
|
||||
A Suite Bundle uploads one ZIP or folder to create a Suite or create a new version from a published base. SkillHub first shows the member diff. Member publication and review start only after explicit confirmation.
|
||||
|
||||
For installation and Agent usage, start with [Skill Suites](./skill-suites). This page is for authors importing content. `SUITE.yaml` (`kind: SkillSuiteBundle`) is distinct from the conceptual `suite.yaml` (`kind: SkillSuite`) definition.
|
||||
|
||||
## Audience and Prerequisites
|
||||
|
||||
This page is for Suite authors. Consumers should read [Skill Suites](/en/guide/skill-suites) and do not need a Bundle. Prepare write access to the target namespace, a complete member list, an entry member, and a valid `SKILL.md` for each packaged member. Referenced members must already be published and accessible.
|
||||
|
||||
Import publishes member versions and creates a Suite draft. It neither installs into a local Agent nor skips member review. For creation, ensure the Suite coordinate is unused. For updates, record the base version and provide the full new member list, not just a delta.
|
||||
|
||||
## Recovering an Interrupted Import
|
||||
|
||||
| Operation status | Meaning and next step |
|
||||
| --- | --- |
|
||||
| `RUNNING` | Member publication is in progress; inspect member rows |
|
||||
| `WAITING_FOR_MEMBERS` | Follow member links to their publication or review state |
|
||||
| `BLOCKED_RETRYABLE` | Inspect the affected member; scan failures and publication failures have different retry prompts. Restore permissions or namespace state first when blocked by authorization |
|
||||
| `REPREVIEW_REQUIRED` | The plan or base changed; upload and preview again instead of confirming the old plan |
|
||||
| `SUITE_DRAFT_CREATED` | Open the generated draft to continue Suite review and publication; the Suite is not yet published |
|
||||
| `CANCELLED` | Suite creation has stopped; existing member versions and reviews are not automatically withdrawn and remain accessible through member links |
|
||||
|
||||
After refreshing, return to the same persistent operation. Do not create another Suite merely to resume. If the completed operation cannot open its draft, retain its operation ID for investigation; completion alone does not prove every result is accessible.
|
||||
|
||||
|
||||
## Archive format
|
||||
|
||||
The archive root must contain exactly one `SUITE.yaml`. Every packaged member has its own directory with a root `SKILL.md`. Undeclared skills, overlapping directories, unsafe or duplicate paths, and configured file limits block preview.
|
||||
|
|
|
|||
|
|
@ -13,8 +13,8 @@ hero:
|
|||
text: Quick Start
|
||||
link: /en/quickstart
|
||||
- theme: alt
|
||||
text: Feature Guide
|
||||
link: /en/guide/skill-publish
|
||||
text: Browse Guides
|
||||
link: /en/guide/
|
||||
- theme: alt
|
||||
text: GitHub
|
||||
link: https://github.com/iflytek/skillhub
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ SkillHub solves this problem. It provides a **private, controllable, and easy-to
|
|||
|
||||
## Tech Stack
|
||||
|
||||

|
||||

|
||||
|
||||
Storage can use local files or an S3-compatible provider; select it explicitly for your deployment.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,15 +1,14 @@
|
|||
# Quick Start
|
||||
# Quick Start: Install and Use a Skill
|
||||
|
||||
Choose your goal first. You do not need to deploy SkillHub to consume skills from an existing registry.
|
||||
Install your first skill and use it in your Agent. This guide uses an existing registry; no SkillHub server deployment is needed.
|
||||
|
||||
| Goal | Guide |
|
||||
| --- | --- |
|
||||
| Find, install, and use a skill | Follow this page |
|
||||
| Install a coordinated collection | [Skill Suites](./guide/skill-suites.md) |
|
||||
| Publish your own skill | [Publishing and versioning](./guide/skill-publish.md) |
|
||||
| Upload a suite and its packages | [Suite Bundle import](./guide/suite-bundle.md) |
|
||||
| Host a team registry | [Docker deployment](./guide/deployment.md) / [Kubernetes](./guide/kubernetes.md) |
|
||||
| Develop SkillHub | [Development handbook](https://github.com/iflytek/skillhub/blob/main/docs/dev-workflow.md) |
|
||||
## Before you begin
|
||||
|
||||
- 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.
|
||||
|
||||
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.
|
||||
|
||||
## 1. Install the CLI and select a registry
|
||||
|
||||
|
|
@ -24,6 +23,14 @@ The default registry is `https://skill.xfyun.cn`. For a self-hosted instance, se
|
|||
export SKILLHUB_REGISTRY=https://skillhub.example.com
|
||||
```
|
||||
|
||||
For PowerShell, set the registry with:
|
||||
|
||||
```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.
|
||||
|
||||
Public skills support anonymous search and installation. Publishing and restricted resources require authentication:
|
||||
|
||||
```bash
|
||||
|
|
@ -31,7 +38,7 @@ skillhub login
|
|||
skillhub whoami
|
||||
```
|
||||
|
||||
Follow the terminal instructions to authenticate in the browser and confirm the device code. Use `skillhub login --no-open` on a remote terminal. Available sign-up and login methods depend on the instance configuration.
|
||||
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.
|
||||
|
||||
## 2. Find and install a skill
|
||||
|
||||
|
|
@ -51,6 +58,12 @@ skillhub list --agent codex
|
|||
For Claude Code, use `--agent claude-code`. Use `--scope user` to share an installation across projects.
|
||||
Codex project installations use `.codex/skills/<slug>/`; Claude Code uses `.claude/skills/<slug>/`. User installations use the corresponding directory under your home directory.
|
||||
|
||||
### Verify the destination
|
||||
|
||||
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.
|
||||
|
||||
`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.
|
||||
|
||||
## 3. Use it in your Agent
|
||||
|
||||
Open the project in your Agent and start a new session or reload skills if required. Confirm that the Agent discovers the skill, then make a concrete request:
|
||||
|
|
@ -71,26 +84,15 @@ skillhub upgrade @team/example-skill
|
|||
|
||||
Review the plan before updating and preserve local changes you need. Do not use `--force` by default. See the [CLI guide](./guide/cli.md) for removal, team workspace synchronization, and command details.
|
||||
|
||||
## 5. Publish your own skill
|
||||
## Troubleshoot the first installation
|
||||
|
||||
The package root must contain uppercase `SKILL.md`. A minimal file is:
|
||||
| Symptom | Check first | Next step |
|
||||
| --- | --- | --- |
|
||||
| Skill not found | Registry, spelling, login identity, and visibility | Confirm a published coordinate/version in the UI; see [discovery](./guide/skill-discovery.md) |
|
||||
| Directory conflict | Whether the destination belongs to another source or contains your own files | Preserve needed files; do not force an unknown directory; see [CLI reference](./guide/cli.md) |
|
||||
| Installed but not discovered | Agent profile, project root, and user/project scope | Check the printed path, then reload or start a session according to the Agent's discovery behavior |
|
||||
| Discovered but execution fails | Required tools, inputs, and credentials | Follow `SKILL.md`; the registry does not configure or execute those requirements |
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: example-skill
|
||||
description: Describe when to use this skill and what it does.
|
||||
---
|
||||
## Next steps
|
||||
|
||||
# Example skill
|
||||
|
||||
Explain the inputs, steps, expected output, and required tools.
|
||||
```
|
||||
|
||||
Add `scripts/`, `references/`, and `assets/` as needed; `package.json` is not required.
|
||||
Create or join a namespace where you can publish, then follow the [publishing guide](./guide/skill-publish.md) to prepare a version and upload:
|
||||
|
||||
```bash
|
||||
skillhub publish ./example-skill --namespace my-team
|
||||
```
|
||||
|
||||
A successful submission is not a published version. Open the returned detail URL to follow scanning, review, and the final status before attempting normal installation.
|
||||
Install a [Skill Suite](./guide/skill-suites.md) when you need a coordinated collection, or use the [CLI reference](./guide/cli.md) for more commands. For publishing, team administration, hosting, or development, choose your next task in the [documentation map](./guide/index.md).
|
||||
|
|
|
|||
|
|
@ -85,7 +85,7 @@ A: `BOOTSTRAP_ADMIN_PASSWORD` 用于初始化账号。`BootstrapAdminInitializer
|
|||
|
||||
## Q: 修改 / 找回密码必须使用邮箱验证码吗?
|
||||
|
||||
A: 当前修改/找回密码流程使用邮箱验证码,需先配置 [SMTP](https://github.com/iflytek/skillhub/blob/main/docs/19-smtp-password-reset-email-setup.md)。修改 bootstrap 环境变量不能重置已经初始化的密码。
|
||||
A: 网页找回密码使用邮箱验证码;已登录且知道原密码的修改接口不使用该验证码。找回流程需先配置 [SMTP](https://github.com/iflytek/skillhub/blob/main/docs/19-smtp-password-reset-email-setup.md)。修改 bootstrap 环境变量不能重置已经初始化的密码。
|
||||
|
||||
## Q: skill 可以起中文名吗?
|
||||
|
||||
|
|
|
|||
75
docs/skillhub/guide/account-access.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
# 登录账号与管理访问令牌
|
||||
|
||||
本页说明如何登录网页、为 CLI 授权,以及管理供脚本使用的 API Token。网页会话、CLI 保存的凭据和技能执行时所需的第三方密钥是不同的对象;创建 SkillHub Token 不会给技能自动注入外部服务凭据。
|
||||
|
||||
## 选择登录方式
|
||||
|
||||
打开实例的 `/login` 页面,使用实际提供的入口:
|
||||
|
||||
| 入口 | 使用条件 | 成功后的结果 |
|
||||
| --- | --- | --- |
|
||||
| 用户名和密码 | 实例启用了本地密码登录,且已有账号 | 建立网页会话 |
|
||||
| 注册账号 | 实例允许自助注册 | 填写用户名、密码和邮箱,成功后建立会话 |
|
||||
| 企业或第三方登录 | 实例配置了对应认证方式 | 完成外部身份认证后返回 SkillHub |
|
||||
|
||||
没有注册按钮不一定是页面故障。登录页读取本地认证能力和可用外部登录方式;管理员关闭密码登录或自助注册后,对应入口会变化。不要套用另一实例的登录流程,也不要将“可接入企业认证”理解为已经配置了所有供应商。
|
||||
|
||||
登录成功不等于具备发布或管理权限。是否能访问命名空间、发布技能、处理审核,仍由账号状态、平台角色、空间成员关系和资源可见性决定,见[命名空间管理](./namespace.md)。
|
||||
|
||||
## 为 CLI 授权
|
||||
|
||||
先让 CLI 指向要使用的实例,再登录:
|
||||
|
||||
```bash
|
||||
skillhub login --registry https://skillhub.example.com
|
||||
skillhub whoami --registry https://skillhub.example.com
|
||||
```
|
||||
|
||||
`skillhub login` 先按命令行、环境变量、当前注册中心保存记录的优先级读取 Token;只有没有读取到 Token 时才进入设备授权。已有但无效的 Token 不会自动回退到设备授权。按照终端显示的网址和设备码,在浏览器确认授权;远程终端可加 `--no-open`,自行打开网址。授权完成后用 `whoami` 检查身份。
|
||||
|
||||
CLI 凭据按注册中心保存。切换 `--registry` 或 `SKILLHUB_REGISTRY` 后,原实例的登录不会自动变成新实例的登录。仅在网页中登录也不会直接替代 CLI 凭据。
|
||||
|
||||
需要自动化时可以使用 API Token。将真实值交给运行环境的密钥管理方式,不写进技能包、项目源码、截图或共享日志。CLI 参数与环境变量优先级见 [CLI 使用参考](./cli.md)。
|
||||
|
||||
## 创建 API Token
|
||||
|
||||
1. 登录网页,打开 API Token 管理页 `/dashboard/tokens`。
|
||||
2. 新建 Token,填写便于识别用途的名称。页面会检查空名称、超过 64 个字符及当前列表页可见的重复名称。
|
||||
3. 选择不过期、7 天、30 天、90 天或自定义到期时间;自定义时间必须有效且在未来。
|
||||
4. 创建成功后立即复制并妥善保存完整值。关闭创建结果后,列表只提供名称、前缀、创建时间、到期时间和最近使用时间等摘要,不提供完整 Token 的再次查看。
|
||||
5. 在目标客户端配置凭据,再通过 `skillhub whoami` 验证实例和身份。
|
||||
|
||||
Token 代表所属账号进行请求,不会绕过该账号的资源权限。页面创建弹窗不提供任意角色授予功能。
|
||||
|
||||
## 更新到期时间与撤销
|
||||
|
||||
在 Token 列表可以调整到期时间或撤销指定 Token。修改有效期后核对列表显示;撤销后,仍使用旧值的客户端需要更换凭据。
|
||||
|
||||
如果完整值丢失,不要尝试从列表前缀恢复它;使用新的唯一名称创建凭据并更新客户端,确认不再使用旧值后撤销旧 Token。服务端同名创建属于轮换,会先撤销同名活动 Token;不能依赖当前分页的重名提示保证旧凭据仍可用。如果疑似泄露,应及时撤销对应 Token,并排查使用范围。
|
||||
|
||||
```bash
|
||||
# 只退出当前指定注册中心的 CLI 登录
|
||||
skillhub logout --registry https://skillhub.example.com
|
||||
```
|
||||
|
||||
`logout` 删除该注册中心的本地保存凭据,不等于从服务端撤销所有 API Token,也不会删除已安装技能。若环境变量仍提供 Token,后续命令仍可能使用该环境变量;排查时同时核对凭据来源。
|
||||
|
||||
## 找回密码与修改密码的区别
|
||||
|
||||
忘记密码时,从登录页进入 `/reset-password`,填写账号邮箱并请求验证码,再提交邮箱、验证码和新密码。该网页流程依赖实例的邮件配置;页面显示已提交验证码请求不等于邮件一定已送达,也不能据此确认某邮箱已注册。
|
||||
|
||||
另有要求当前登录身份与原密码的修改密码接口 `/api/v1/auth/local/change-password`。它与邮箱验证码找回流程不同;不要将“所有密码变更都必须邮箱验证码”作为接口限制。企业身份账号的外部密码应按其认证提供方的流程处理。
|
||||
|
||||
部署中的 `BOOTSTRAP_ADMIN_PASSWORD` 用于初始化凭证,不能重置已经存在的管理员密码。邮件配置见 [SMTP 操作说明](https://github.com/iflytek/skillhub/blob/main/docs/19-smtp-password-reset-email-setup.md)。
|
||||
|
||||
## 常见问题
|
||||
|
||||
| 现象 | 检查顺序 |
|
||||
| --- | --- |
|
||||
| 网页已登录,CLI 仍提示未认证 | 核对注册中心;执行 CLI 登录和 `whoami`,不要将浏览器 Cookie 当作 CLI Token |
|
||||
| CLI 登录后仍使用错误账号 | 检查命令行 Token、`SKILLHUB_TOKEN` 和该注册中心保存的凭据优先级 |
|
||||
| Token 不能调用某接口 | 检查是否过期/撤销、账号及资源权限、Token 的使用范围;保留公开错误信息和 `requestId` |
|
||||
| 找回密码收不到邮件 | 核对邮箱、垃圾邮件、实例 SMTP 配置和服务日志;不要反复请求来绕过限流 |
|
||||
| 登录成功后又回到登录页 | 检查后续身份请求、Cookie、代理和会话配置,不通过清空数据库排障 |
|
||||
|
||||
请求协助时提供实例版本、操作入口、错误信息和 `requestId`,不要附完整 Token、验证码、密码或 Cookie。
|
||||
|
|
@ -1,7 +1,28 @@
|
|||
# SkillHub CLI
|
||||
# CLI 使用参考
|
||||
|
||||
SkillHub CLI 是 SkillHub 的第一方命令行工具,用于搜索、安装、管理和发布 Agent 技能包。
|
||||
|
||||
## 选择正确的管理对象
|
||||
|
||||
| 目标 | 命令 | 影响范围 |
|
||||
| --- | --- | --- |
|
||||
| 安装单个远端 Skill | install | 选定 Agent / scope / 自定义目录 |
|
||||
| 更新已安装单个技能 | upgrade | 显式选择的坐标及目标,不隐式升级全部 |
|
||||
| 管理固定版本集合 | suite | 套装安装记录及成员来源 |
|
||||
| 同步团队创作工作区 | sync | 非 global 空间与工作区,不等于套装管理 |
|
||||
| 更新 CLI 程序本身 | update | 本机 CLI 安装,不更新技能 |
|
||||
| 修复本地记录 | doctor | 扫描项目元数据并重建 inventory,不代替远端升级 |
|
||||
|
||||
## 自动化和错误处理
|
||||
|
||||
自动化安装明确给出 `--scope` 与 `--agent`,或单独使用 `--dir`,避免依赖工作目录中的自动发现结果。`--dir` 不与 scope/agent 混用。先使用 `version` 和 `help <command>` 核对本机命令;文档对应当前代码,不保证老版本全部支持。
|
||||
|
||||
同一工作流的搜索、登录、安装和检查应指向同一 Registry。显式 `--registry` 适合单次操作;环境变量适合当前进程树。凭证按 Registry 保存,切换地址后使用 `whoami` 核对身份。
|
||||
|
||||
`--json` 用于机器读取,不要在自动化中假设会出现交互提示。捕获退出码和输出;遇到结构化服务端错误保留公开消息与 requestId。Suite 检查的 `ok: false` 可以只是发现变化,需继续读取结果字段。`--check` 是相应升级/同步操作的预览能力,不是所有命令的通用参数。
|
||||
|
||||
遇到同名目录冲突时先检查来源:`--force` 只对允许覆盖的受管理目标有效,不会接管未知目录或其他来源。恢复记录前保留本地文件与 metadata;不要删除整个 `~/.skillhub`,其中还存有其他实例凭证和安装记录。
|
||||
|
||||
## 安装
|
||||
|
||||
```bash
|
||||
|
|
@ -73,7 +94,7 @@ Token 按以下优先级解析:
|
|||
|
||||
### 登录
|
||||
|
||||
未传入 token 时,`skillhub login` 使用 OAuth Device Flow:打开验证页面并显示用户码,完成浏览器授权后保存凭证。无浏览器终端可用 `skillhub login --no-open`;自动化使用 API token。
|
||||
没有从命令行、环境变量或该注册中心保存记录读取到 Token 时,`skillhub login` 才使用 OAuth Device Flow;读取到无效 Token 时不会自动回退:打开验证页面并显示用户码,完成浏览器授权后保存凭证。无浏览器终端可用 `skillhub login --no-open`;自动化使用 API token。
|
||||
|
||||
```bash
|
||||
# 使用 API token 登录
|
||||
|
|
@ -407,7 +428,9 @@ skillhub update
|
|||
|
||||
### inventory.json
|
||||
|
||||
CLI 管理的安装记录,不应手工编辑。当前磁盘格式使用 `schemaVersion: 2`、`records` 和可选 `suites`;每个 target 分别记录版本、fingerprint 和 installedBy。CLI 可读取旧记录并在写入时迁移。
|
||||
CLI 管理的安装记录,不应手工编辑。每个安装目标分别记录版本、fingerprint 和来源;兼容客户端在需要时迁移旧记录。备份用于恢复核查,不代表可以直接覆盖更新后的 inventory。
|
||||
|
||||
当前主分支代码包含使用 inventory v3 的 DSH 启用/停用能力。不要假设已发布 CLI 已支持,也不要混用不兼容写入端。CLI 没有 enable/disable 命令;该增量中,CLI `--force` 不能升级停用目标,doctor 也不会仅凭孤立的 `SKILL.md.disabled` 重建停用来源。启停由兼容版本的 DSH 管理,使用时以配套发行说明为准。
|
||||
|
||||
## JSON 输出
|
||||
|
||||
|
|
@ -455,6 +478,7 @@ skillhub doctor --json
|
|||
| 3 | 网络错误 |
|
||||
| 4 | 文件系统错误 |
|
||||
| 5 | 参数错误 |
|
||||
| 6 | 校验或安装来源冲突 |
|
||||
|
||||
## 命令参考
|
||||
|
||||
|
|
|
|||
|
|
@ -17,6 +17,7 @@ cp .env.release.example .env.release
|
|||
| `SKILLHUB_VERSION` | 固定已发布版本,避免升级时无意更换镜像;`latest` 跟踪稳定发布,`edge` 跟踪主分支构建 |
|
||||
| `SKILLHUB_PUBLIC_BASE_URL` | 用户实际访问的地址,生产环境使用 HTTPS |
|
||||
| `WEB_PORT` / `API_PORT` | 默认分别为 80 / 8080,确认端口可用 |
|
||||
| `SKILLHUB_DOWNLOAD_ANON_COOKIE_SECRET` | 自行生成至少 32 字符的随机值;默认占位值会阻止启动 |
|
||||
| `POSTGRES_PASSWORD` | 设置自己的数据库密码 |
|
||||
| `BOOTSTRAP_ADMIN_ENABLED` / `BOOTSTRAP_ADMIN_PASSWORD` | 是否初始化首个管理员;启用时必须更换示例密码 |
|
||||
| 存储配置 | 默认及可选配置以模板为准;外部存储按[对象存储手册](https://github.com/iflytek/skillhub/blob/main/docs/object-storage.md)配置 |
|
||||
|
|
@ -47,3 +48,27 @@ docker compose --env-file .env.release -f compose.release.yml down
|
|||
```
|
||||
|
||||
启动失败先查看 `ps` 和服务日志,核对数据库、Redis、存储和公开地址配置。提交问题时提供镜像版本、脱敏日志和请求 ID,不提供 `.env.release` 或凭证。更多 Redis、反向代理、采集服务和迁移配置见[运维手册](https://github.com/iflytek/skillhub/blob/main/docs/09-deployment.md)。
|
||||
|
||||
## 配置检查与上线验收
|
||||
|
||||
发布模板和 Compose 需来自同一版本。普通 `.env.release` 是 Compose 的替换值来源,只有清单引用的变量才会进入进程。额外配置应通过自己的 override 显式传入,不能只在环境文件追加任意属性。重建服务后检查行为;`restart` 不更新容器环境。
|
||||
|
||||
| 检查层 | 操作与通过标准 |
|
||||
| --- | --- |
|
||||
| 配置 | `make validate-release-config` 无错误;警告逐项确认,不公开包含配置值的输出 |
|
||||
| 依赖和进程 | `ps` 中相关服务运行,`server` 日志没有持续连接失败或迁移失败 |
|
||||
| 对外入口 | 浏览器从最终域名访问、登录;CLI 对同一 Registry 执行 `whoami` |
|
||||
| 业务与持久化 | 发布测试技能,跟踪最终状态,安装固定版本并检查 `SKILL.md`;重启后资源和登录能力仍可恢复 |
|
||||
| 运行依赖 | 技能包存储可读写;扫描服务可达,真实扫描任务能完成,而非仅容器健康 |
|
||||
|
||||
生产域名走 HTTPS 时设置 `SESSION_COOKIE_SECURE=true`。子路径部署需同时配置 `SKILLHUB_WEB_BASE_PATH=/skillhub/`、同源 `SKILLHUB_WEB_API_BASE_URL=/skillhub` 和带 `/skillhub` 的公开地址。只设置公网 URL 不会自动配置 TLS 证书、代理或 DNS。
|
||||
|
||||
| 现象 | 首先检查 |
|
||||
| --- | --- |
|
||||
| 校验器拒绝启动 | 数据库/管理员密码是否仍为示例,匿名下载密钥长度,存储 provider 和 S3 必需项 |
|
||||
| 页面正常但 API 502 | `server` 日志、数据库迁移、`SKILLHUB_API_UPSTREAM` 和容器网络 |
|
||||
| 登录回调或设备码地址错误 | `SKILLHUB_PUBLIC_BASE_URL` 是否与真实域名和子路径一致 |
|
||||
| 配置保存后没变化 | 是否重建正确 Compose 项目,是否保留原 override,变量是否实际透传 |
|
||||
| 上传进入扫描但不结束 | 扫描器日志、配置、后端到扫描器网络;不要将失败视为审核通过 |
|
||||
|
||||
备份至少覆盖 PostgreSQL、技能与头像存储、私有运行配置及加密密钥。恢复时使用匹配的应用版本和配置,先在隔离环境验证恢复后的登录与下载;不要以删除卷或清空数据库作为升级失败的默认处理。
|
||||
|
|
|
|||
45
docs/skillhub/guide/index.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# 文档导航
|
||||
|
||||
按要完成的任务选择入口。第一次使用,从[快速开始](../quickstart.md)安装一个技能;不需要先阅读部署或开发文档。
|
||||
|
||||
## 开始使用
|
||||
|
||||
- [账号与访问令牌](./account-access.md):网页登录、CLI 授权、Token 到期和密码找回。
|
||||
- [项目简介](../introduction.md):了解注册中心解决什么问题。
|
||||
- [快速开始](../quickstart.md):搜索、安装,在 Agent 中使用。
|
||||
- [常见问题](../faq.md):排查登录、安装和配置问题。
|
||||
|
||||
## 使用技能
|
||||
|
||||
| 你要做什么 | 阅读 |
|
||||
| --- | --- |
|
||||
| 找到适合任务的技能,查看版本和权限 | [搜索与安装技能](./skill-discovery.md) |
|
||||
| 一次安装一组固定版本技能,从入口技能开始使用 | [管理技能套装](./skill-suites.md) |
|
||||
| 选择 Agent 和安装范围,更新、卸载或同步工作区 | [CLI 使用参考](./cli.md) |
|
||||
| 收藏、评价技能并查看通知 | [收藏、评分与通知](./social.md) |
|
||||
|
||||
## 创作与发布
|
||||
|
||||
先准备 `SKILL.md` 和所需文件,再提交发布。提交成功后仍需跟踪扫描、审核及最终版本状态。
|
||||
|
||||
- [发布与更新技能](./skill-publish.md):包结构、元数据、上传和版本管理。
|
||||
- [通过 Bundle 导入技能套装](./suite-bundle.md):作者上传 Bundle,预览成员差异后确认。安装现有套装请用上方的使用指南。
|
||||
|
||||
## 团队与治理
|
||||
|
||||
- [管理命名空间](./namespace.md):成员、角色和资源可见范围。
|
||||
- [审核技能与套装](./review.md):处理技能与套装申请。
|
||||
- [安全扫描与报告](./scanner.md):扫描服务接入及结果解读。
|
||||
|
||||
## 部署与运维
|
||||
|
||||
仅在需要自己运行注册中心时阅读。先选择部署方式,再配置所需的可选能力。
|
||||
|
||||
- [Docker 部署](./deployment.md):安装、配置、升级和备份。
|
||||
- [Kubernetes 部署](./kubernetes.md):集群和 Helm 部署。
|
||||
- [技能头像与审核](./skill-avatars.md):管理员配置图片审核服务。
|
||||
|
||||
## 开发与集成
|
||||
|
||||
- [Runtime 集成](./runtime-integration.md):外部运行时使用注册中心的接口契约。
|
||||
- [源码开发手册](https://github.com/iflytek/skillhub/blob/main/docs/dev-workflow.md):本地开发环境和仓库检查命令。
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Kubernetes 部署指南
|
||||
# Kubernetes 部署:Kustomize 配置与验收
|
||||
|
||||
对象存储可选部署、凭证和迁移说明见[对象存储手册(GitHub)](https://github.com/iflytek/skillhub/blob/main/docs/object-storage.md)。
|
||||
|
||||
|
|
@ -70,6 +70,14 @@ cp base/secret.yaml.example base/secret.yaml
|
|||
| skill-scanner-llm-base-url | 本地/自定义 LLM 服务地址 | 否 |
|
||||
| skill-scanner-llm-model | Scanner 使用的 LLM 模型名 | 否 |
|
||||
|
||||
完成填写后单独创建 Secret;当前 Kustomization 不包含 `base/secret.yaml`,只复制文件不会把它部署进集群:
|
||||
|
||||
```bash
|
||||
kubectl apply -n skillhub -f base/secret.yaml
|
||||
```
|
||||
|
||||
还需在自己的部署覆盖层为后端补充公开地址与匿名下载签名密钥,见下文“部署前补齐环境配置”。
|
||||
|
||||
### 3. 选择部署方式
|
||||
|
||||
**方式一:完整部署(包含 PostgreSQL + Redis)**
|
||||
|
|
@ -301,3 +309,33 @@ kubectl delete -k overlays/with-infra/ # 或 overlays/external/
|
|||
# 删除命名空间
|
||||
kubectl delete namespace skillhub
|
||||
```
|
||||
|
||||
## 部署前补齐环境配置
|
||||
|
||||
当前基础清单未自动透传所有应用设置。为自己的覆盖层中的 `skillhub-server` Deployment、`server` 容器添加所需 `env`(核对容器名,勿误加到扫描器):
|
||||
|
||||
```yaml
|
||||
- name: SKILLHUB_PUBLIC_BASE_URL
|
||||
value: https://skills.example.com
|
||||
- name: SKILLHUB_DOWNLOAD_ANON_COOKIE_SECRET
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: skillhub-secret
|
||||
key: download-anon-cookie-secret
|
||||
```
|
||||
|
||||
在私有 `base/secret.yaml` 的 `stringData` 中增加 `download-anon-cookie-secret`,填入至少 32 字符的随机值。替换公开地址为实际入口。应用启动会拒绝匿名下载密钥的默认占位值。公开地址、Ingress 域名、TLS 和安全 Cookie 配置应一致;Ingress 不会自动替你签发证书。
|
||||
|
||||
S3 模式除了 endpoint、bucket、region,还必须把 Secret 中的 `skillhub-storage-s3-access-key`、`skillhub-storage-s3-secret-key` 分别通过 `secretKeyRef` 映射到 `SKILLHUB_STORAGE_S3_ACCESS_KEY`、`SKILLHUB_STORAGE_S3_SECRET_KEY`。只添加 Secret 键不会注入进程。使用基础清单没有声明的开关(例如 Suite 审核、Bundle 确认)同样需要显式透传,不能套用 Compose 的默认值。
|
||||
|
||||
## 升级与验收
|
||||
|
||||
1. 固定 `base/kustomization.yaml` 中应用镜像的 `newTag`,保存旧版本与覆盖层;备份数据库、存储和私有 Secret。
|
||||
2. 先本地渲染所选 overlay,确认镜像、环境引用、Ingress、PVC 与目标 namespace;不要公开渲染后的 Secret。
|
||||
3. 应用配置后等待 `kubectl rollout status deployment/skillhub-server -n skillhub` 完成,检查 Pod 事件和日志。ConfigMap/Secret 修改并不自动更新已运行进程的环境,必要时在维护窗口滚动重启受影响 Deployment。
|
||||
4. 从实际入口登录、搜索、发布测试版本、跟踪扫描审核并下载固定版本。Pod Ready 仅说明探针通过。
|
||||
5. 升级失败先检查迁移/依赖日志;回退镜像前确认数据库兼容性,保留 PVC,不把删除 namespace 当作重试方式。
|
||||
|
||||
遇到 `CreateContainerConfigError`,优先检查引用的 Secret 是否创建、必需键是否存在;`CrashLoopBackOff` 查看后端启动日志;`Pending` 检查 PVC 和资源调度。不要输出 Secret 数据作为排障材料。
|
||||
|
||||
仓库还提供独立的 [Helm Chart](https://github.com/iflytek/skillhub/tree/main/charts/skillhub)。它的 values、Secret 和依赖配置应按 Chart README 操作,不与本页 Kustomize 路径混用。
|
||||
|
|
|
|||
|
|
@ -1,4 +1,21 @@
|
|||
# 命名空间与团队管理
|
||||
# 管理命名空间
|
||||
|
||||
创建团队空间入口仅向平台 SKILL_ADMIN / SUPER_ADMIN 展示。普通成员先联系有权创建者建立空间并邀请加入;成为团队 Owner 不等于获得平台管理角色。
|
||||
|
||||
## 团队开始协作的顺序
|
||||
|
||||
1. 在“我的空间”创建团队空间,填写稳定的 slug 和易读的显示名称。slug 是安装坐标的一部分,不能随团队改名而修改。
|
||||
2. 在成员页添加已有账号或生成邀请链接。普通角色选择是 MEMBER / ADMIN;移交所有权使用独立的转让入口,不通过普通角色下拉框添加 Owner。
|
||||
3. 团队成员在发布页选择该空间。团队内共享请选择 NAMESPACE_ONLY;PRIVATE 不等于“全体团队成员可见”。
|
||||
4. 管理员在空间审核入口处理提交,成员在“我的技能”跟踪自己的版本。
|
||||
5. 人员变动时先安排技能维护责任,再移除成员。成员移除不自动转让技能所有权。
|
||||
|
||||
### 设置按钮为什么不一样
|
||||
|
||||
页面按空间类型、状态及服务端返回的操作权限展示冻结、解冻、归档、恢复和删除按钮。不要把 Owner / Admin 理解为所有操作永久可用。ACTIVE 团队空间的 Owner / Admin 可以编辑资料;所有权转让只向有权的 Owner 展示。冻结或归档后,成员管理进入只读状态,但符合条件的管理员仍可查看邀请历史。
|
||||
|
||||
冻结用于暂时停止写入,恢复写入使用解冻;归档与永久删除不是同一个操作。执行生命周期操作前核对确认框中的空间和影响范围,完成后检查状态和成员页面,而不是仅看请求成功提示。
|
||||
|
||||
|
||||
## 功能描述
|
||||
|
||||
|
|
@ -17,7 +34,7 @@
|
|||
|
||||
| 角色 | 权限 |
|
||||
|------|------|
|
||||
| **Owner** | 完全控制,包括删除命名空间、管理所有成员 |
|
||||
| **Owner** | 团队空间所有者,可按空间状态与服务端权限管理成员及转让所有权 |
|
||||
| **Admin** | 管理成员、审核技能包、修改设置 |
|
||||
| **Member** | 发布技能包、查看空间成员可见的技能包 |
|
||||
|
||||
|
|
@ -70,7 +87,7 @@
|
|||
2. 点击「成员」标签
|
||||
3. 点击「添加成员」
|
||||
4. 搜索用户(支持按用户名、邮箱搜索)
|
||||
5. 选择角色(Owner / Admin / Member)
|
||||
5. 选择角色(Admin / Member;Owner 使用独立转让流程)
|
||||
6. 确认添加
|
||||
|
||||
**通过链接邀请成员**:
|
||||
|
|
|
|||
|
|
@ -1,4 +1,18 @@
|
|||
# 审核与治理
|
||||
# 审核技能与套装
|
||||
|
||||
## 审核员的检查清单
|
||||
|
||||
1. 核对审核对象、提交者和目标版本。技能版本、头像或资料变更、套装版本不能混用同一判断。
|
||||
2. 读取本次提交的文件与变更,不仅阅读当前公开版本。新版审核期间,旧公开版本可能仍可下载。
|
||||
3. 检查扫描状态及发现项。扫描执行失败、风险发现和未配置某项分析器分别处理;空报告不能当作安全结论。
|
||||
4. 检查可见范围与受众,特别是套装每个成员的可用性和入口身份。成员通过审核不自动批准套装。
|
||||
5. 批准前确认当前数据仍有效;拒绝时写明具体文件、问题及修订方向。点击失败时重新读取状态,避免对旧页面重复作出相反决定。
|
||||
6. 审核完成后查看记录和发布版本。审核操作成功不验证本地 Agent 的技能执行效果。
|
||||
|
||||
### 作者如何跟踪和修订
|
||||
|
||||
在“我的提交”查看待审任务和意见,未完成审核前可按权限撤回。撤回是停止当前审核,不会删除已发布旧版本或撤销已批准的全局提升。被拒绝后根据意见修订,再通过当前版本页面提供的重新提交操作继续;不要把上传成功当成审核重开成功。
|
||||
|
||||
|
||||
## 功能描述
|
||||
|
||||
|
|
@ -77,7 +91,7 @@ SkillHub 提供了完整的审核工作流,确保发布到注册中心的技
|
|||
- 在“审核记录”查看提交历史和已完成的审核意见;该页签打开时才请求历史
|
||||
- 套件审核在内容区核对待审快照。快照加载失败时可重试,加载成功前“通过”按钮不可用
|
||||
|
||||

|
||||

|
||||
|
||||
本页的审核部分对应 PUBLIC / NAMESPACE_ONLY 分支:扫描完成后,版本等待审核决定。
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Runtime 集成契约
|
||||
# Runtime 集成:解析版本、下载与合规快照
|
||||
|
||||
## 职责边界
|
||||
|
||||
|
|
@ -20,7 +20,7 @@ Runtime 在执行技能时,如果需要把执行链路与 SkillHub 的合规
|
|||
| `registryUrl` | Runtime 配置 | 使用的 SkillHub 注册中心地址 |
|
||||
| `namespace` | SkillHub 坐标 | 技能命名空间,例如 `global` 或团队 slug |
|
||||
| `skillSlug` | SkillHub 坐标 | 技能 slug |
|
||||
| `requestedVersion` | Runtime 请求 | 用户请求的版本、标签或版本范围 |
|
||||
| `requestedVersion` | Runtime 请求 | 用户请求的精确版本或标签 |
|
||||
| `resolvedVersion` | SkillHub 响应 | 实际解析到的版本号 |
|
||||
| `skillVersionId` | SkillHub 响应里的版本 `id` | 不可变版本 ID,审计关联的主键 |
|
||||
| `complianceSnapshotDigest` | `complianceSnapshot.digest` | 该版本合规声明快照的稳定摘要 |
|
||||
|
|
@ -90,12 +90,46 @@ Runtime 应把 `id` 和 `complianceSnapshot.digest` 一起写入执行 trace。
|
|||
- 不要把 SkillHub 的合规声明当成第三方认证结果。
|
||||
- 不要要求 SkillHub 记录模型输入输出;这是 Runtime 的审计边界。
|
||||
|
||||
## 未来可能新增的 API
|
||||
## 从解析到下载的接口顺序
|
||||
|
||||
如果出现明确使用方,例如 Runtime 只需要合规快照而不需要完整技能详情,可以新增不可变版本维度的接口:
|
||||
集成方先确定 Registry 地址、技能坐标和调用身份。下面是 HTTP 请求格式,不是 Shell 命令;示例坐标必须替换为实例内真实技能。
|
||||
|
||||
```text
|
||||
GET /api/skill-versions/{skillVersionId}/compliance
|
||||
```http
|
||||
GET /api/v1/skills/global/example-skill/resolve?version=1.2.0
|
||||
GET /api/v1/skills/global/example-skill/versions/1.2.0
|
||||
GET /api/v1/skills/global/example-skill/versions/1.2.0/download
|
||||
```
|
||||
|
||||
当前阶段先复用版本详情响应,避免为尚未稳定的调用方提前设计多套 API。
|
||||
`resolve` 的 `version` 是精确版本;标签使用 `tag`,不能同时提供 `version` 与 `tag`。当前此接口不解析 `^1.2.0` 等版本范围。解析响应提供 `skillId`、`namespace`、`slug`、`version`、`versionId`、`fingerprint`、`matched` 和 `downloadUrl`。后续使用解析出的精确版本,不要在执行前再次解析 `latest`,否则可能得到另一版本。
|
||||
|
||||
版本详情使用统一响应包装,以下示例省略了部分详情字段,数值和时间仅为说明:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"id": 123,
|
||||
"version": "1.2.0",
|
||||
"status": "PUBLISHED",
|
||||
"fileCount": 2,
|
||||
"totalSize": 2048,
|
||||
"complianceSnapshot": null
|
||||
},
|
||||
"timestamp": "2026-01-01T00:00:00Z",
|
||||
"requestId": "example-request-id"
|
||||
}
|
||||
```
|
||||
|
||||
`complianceSnapshot: null` 可能表示未提供声明或历史元数据无法投影;不应伪造一个空摘要。`fingerprint` 是 Registry 的包内容指纹,`complianceSnapshot.digest` 是声明快照摘要,两者用途不同,不能互换。若自行对下载 ZIP 计算摘要,应单独记录其算法与对象,不假定它等于 Registry 指纹。
|
||||
|
||||
下载接口可能直接返回 ZIP,也可能返回 `302` 和对象存储 `Location`。处理重定向时不要把 Registry 凭证转发给对象存储主机;使用 CLI 可复用现有安装校验流程。返回的短期下载地址不能替代技能坐标作为长期标识。
|
||||
|
||||
## 权限与失败处理
|
||||
|
||||
- 匿名请求可读取可见的公开已发布资源;命名空间成员可见和私有资源仍检查调用者身份、成员关系及所有权。路径可匿名访问不代表每个资源都公开。
|
||||
- 版本详情包含维护者预览能力。能读取详情不等于版本可安装;解析流程要求可安装版本,Runtime 应记录并检查 `status`,不要把待审预览内容当成公开发布物。
|
||||
- 资源不存在、无权访问、版本不可安装时停止执行;不要自动回退到同名技能、其他 Registry 或最新版本。
|
||||
- 保存失败响应的 `requestId` 和脱敏错误用于排障,不记录 token、短期签名 URL 或技能运行输入中的秘密。
|
||||
|
||||
集成验收至少覆盖:公开版本成功解析与下载、受限资源拒绝匿名访问、指定版本不可用时明确失败、无合规声明版本正常表示为空、下载重定向不泄露认证信息。执行 trace 保存在 Runtime 自己的系统;这些接口不接收执行结果。
|
||||
|
|
|
|||
|
|
@ -1,10 +1,27 @@
|
|||
# Skill Scanner 安全扫描
|
||||
# 配置与查看安全扫描
|
||||
|
||||
## 作者和审核员怎么查看
|
||||
|
||||
发布后在技能详情或审核页查看本次版本的扫描状态、报告与发现项。先核对版本,再查看严重级别、受影响文件和说明;不能把旧版本报告用于新版本。
|
||||
|
||||
- `SCANNING`:尚未完成,普通提审版本不能据此批准。
|
||||
- `SCAN_FAILED`:执行失败,需要查看原因并重试,不等于判定有害。
|
||||
- 已完成且有发现项:根据风险与策略处理,不等于执行失败;人工审核仍需判断。
|
||||
- 未启用或没有报告:不是“零风险”。PRIVATE 路径可在禁用扫描时上传;普通 PUBLIC / NAMESPACE_ONLY 发布要求扫描启用。
|
||||
|
||||
### 运维排查顺序
|
||||
|
||||
1. 确认后端实际使用的 Scanner 地址和模式。下表是应用默认值;release Compose 将模式设为 `upload`,不能假设容器使用宿主机的 `localhost`。
|
||||
2. 从后端可达的网络检查 Scanner 的 `/health`,再检查实际扫描请求和返回。健康成功不代表某个包扫描成功。
|
||||
3. 对照技能版本、请求时间及后端/Scanner 日志,区分网络或服务暂时不可用与包分析错误。暂时不可用会保留待处理并重领,不能只因等待较久就认定失败。
|
||||
4. 修复服务或配置后跟踪原任务。记录版本 ID、状态和错误信息供管理员定位;不要公开包内秘密或认证信息。
|
||||
|
||||
|
||||
## 功能描述
|
||||
|
||||
SkillHub 内置了 **Skill Scanner** 安全扫描服务,在技能包发布时自动检测潜在的安全风险。这是保障企业内部技能包安全的重要防线。
|
||||
|
||||
每个技能包在发布后都会经过安全扫描,扫描结果会影响审核决策,帮助管理员快速判断技能包是否安全可靠。
|
||||
启用扫描的上传会经过安全扫描,扫描结果会影响审核决策,帮助管理员快速判断技能包是否安全可靠。
|
||||
|
||||
**核心特性**:
|
||||
|
||||
|
|
@ -18,8 +35,8 @@ SkillHub 内置了 **Skill Scanner** 安全扫描服务,在技能包发布时
|
|||
|
||||
| 引擎 | 说明 | 默认状态 |
|
||||
|------|------|----------|
|
||||
| **元数据分析** | 检查包结构、文件类型、大小等 | 启用 |
|
||||
| **行为分析** | 分析代码行为模式,检测恶意操作 | 可选 |
|
||||
| **元数据分析** | 元数据相关分析(不替代上传结构校验) | 默认关闭 |
|
||||
| **行为分析** | 分析代码行为模式,检测恶意操作 | 默认启用 |
|
||||
| **LLM 分析** | 使用大模型分析代码安全性 | 可选 |
|
||||
| **AI Defense** | Cisco AI Defense 集成 | 可选 |
|
||||
| **VirusTotal** | VirusTotal 病毒扫描 | 可选 |
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# 技能头像与图片审核接入
|
||||
# 技能头像:上传、审核与供应商配置
|
||||
|
||||
本页介绍如何上传技能头像,以及部署方如何接入讯飞或阿里云图片审核。这是**技能头像**功能,不涉及用户个人头像;图片审核与技能包安全扫描是两种不同的检查。
|
||||
|
||||
|
|
@ -9,7 +9,7 @@
|
|||
3. 提交后,在「我的技能」或更新页查看**本次提交的图片**及审核状态。审核通过前,其他人继续看到旧头像或首字母。
|
||||
4. 被拒绝后查看原因,修改图片再提交。新申请会替换旧待审申请,旧审核结果不会覆盖新头像。
|
||||
|
||||
上传输入限 PNG/JPEG、2 MB、边长不超过 1024 像素;服务器会再次校验并重新编码为 PNG。上传成功仅表示图片已存入私有存储,不代表审核通过。临时上传引用 24 小时后过期,过期需要重新上传。
|
||||
上传输入限 PNG/JPEG、2 MB、正方形且边长不超过 1024 像素;服务器会再次校验并重新编码为 PNG。上传成功仅表示图片已存入私有存储,不代表审核通过。临时上传引用 24 小时后过期,过期需要重新上传。
|
||||
|
||||
更新默认保留原头像,也可移除:单改头像提交成功后恢复首字母;与新技能包一起提交时,审核通过后才移除。取消编辑或提交失败不改变现有头像。技能详情和列表展示当前生效头像,不设单独的头像管理入口。
|
||||
|
||||
|
|
@ -128,7 +128,7 @@ docker compose --env-file .env.release \
|
|||
|
||||
填写凭证、成功保存开关或应用健康,**都不能证明云服务调用成功**。后台检查的是配置是否齐全,真正的服务权限、网络、余额和接口响应必须通过新申请验证。已有申请不因开关开启而补跑机器审核。
|
||||
|
||||
接入验收现状:讯飞已通过真实接口验证通过(PASS)与阻止(BLOCK),并验证人工拒绝后保留旧公开头像;阿里云已进行接口契约、结果映射和异常处理的代码审查及模拟响应测试,**尚未真实账号联调**。这些结果不替代部署方对自己账号的连接验收。
|
||||
供应商接口的代码与模拟测试不能替代本部署的账号验收。每次启用或轮换后都应验证实际账号的连通性、结果映射和失败行为。
|
||||
|
||||
## 修改开关与切换供应商
|
||||
|
||||
|
|
|
|||
|
|
@ -1,124 +1,74 @@
|
|||
# Skill 搜索与发现
|
||||
# 搜索与安装技能
|
||||
|
||||
## 功能描述
|
||||
从已有注册中心找到一个技能,确认可用版本,再安装到实际使用的 Agent。搜索结果、网页详情和本地安装是三个不同环节;看到卡片不等于已经安装。
|
||||
|
||||
SkillHub 提供了强大的全文搜索功能,让用户可以快速找到需要的技能包。
|
||||
## 开始前
|
||||
|
||||
搜索支持关键词、命名空间和标签筛选,以及相关性、下载量和最新排序。
|
||||
公开技能可匿名浏览。查找团队或私有资源时先登录正确实例,并确认拥有对应命名空间权限。准备 CLI 和 Agent 的步骤见[快速开始](../quickstart.md)。以下路径相对于实际部署地址,不固定开发端口。
|
||||
|
||||
## 在网页查找
|
||||
|
||||
1. 打开首页搜索框或 `/search`,输入任务关键词,例如 `pdf`。
|
||||
2. 要限定空间,输入 `@team pdf`;只输入 `@team` 可浏览该空间。`team` 必须替换为真实空间标识。
|
||||
3. 点击标签缩小范围;再次点击选中的标签取消筛选。当前网页一次选择一个标签。
|
||||
4. 按相关性、下载量或最新排序。网页默认“最新”,没有独立的评分排序。
|
||||
5. 打开技能卡片,核对名称、坐标、说明、版本和文件,而不是仅凭标题决定安装。
|
||||
|
||||
搜索词、空间、标签、排序和页码会保留在 URL 中,可复制链接或返回结果页继续浏览。关键词最多取前 50 个字符,长篇任务应提炼成关键词。
|
||||
|
||||
## 仅查看收藏
|
||||
|
||||
登录后在搜索页启用“仅收藏”;未登录时会引导登录。此模式在已获取的收藏中按名称、摘要、空间和 slug 匹配关键词,不使用普通服务端全文搜索。可按空间和下载量筛选/排序;“相关性”和“最新”均按更新时间排序。当前收藏分支不应用标签过滤,使用标签检索时先关闭“仅收藏”。
|
||||
|
||||
“我的收藏”位于 `/dashboard/stars`,提供分页浏览;详细操作见[收藏、评分与通知](./social.md)。
|
||||
|
||||
## 从详情决定安装范围
|
||||
|
||||
核对技能说明是否匹配任务,以及所需脚本、工具和服务是否可用。安装坐标使用 `@namespace/slug`,展示名变化不会改变坐标。
|
||||
|
||||
“关联套件”表示该技能被当前用户可见的套装收录。进入详情可查看入口/普通成员身份及配套成员;同一技能可能属于多个套装。需要整套使用时进入[技能套装指南](./skill-suites.md),否则可以单独安装。
|
||||
|
||||
## 用 CLI 安装并确认
|
||||
|
||||
以下坐标是示例,先替换为实际搜索结果;默认注册中心与自托管实例不能混为一谈。
|
||||
|
||||
```bash
|
||||
skillhub search pdf
|
||||
# 在目标项目根目录安装给 Codex
|
||||
skillhub install @team/example-skill --scope project --agent codex
|
||||
skillhub list --agent codex
|
||||
# 需要复现特定版本时显式指定
|
||||
skillhub install @team/example-skill --version 1.0.0 --scope project --agent codex
|
||||
```
|
||||
|
||||
CLI 普通搜索返回 Skill,不搜索 Suite。`search` 不提供网页全部筛选参数,使用 `skillhub help search` 核对支持的参数。私有实例可为每条命令追加 `--registry https://skillhub.example.com`。
|
||||
|
||||
安装成功后检查输出目录和 `SKILL.md`,让 Agent 发现该技能并提出实际任务。下载 ZIP 只是获得文件,并不会自动放入 Agent 目录。更新、目标冲突、版本保护和卸载参见 [CLI 使用参考](./cli.md)。
|
||||
|
||||
## 找不到或无法安装时
|
||||
|
||||
| 现象 | 检查与处理 |
|
||||
| --- | --- |
|
||||
| 搜索为空 | 清除标签、空间和仅收藏条件,再尝试短关键词;确认连接的是正确实例 |
|
||||
| 同事可见而自己不可见 | 核对登录身份与空间成员权限;PRIVATE 不对全部成员开放 |
|
||||
| 刚提交的版本没有出现 | 在“我的技能”检查本次版本的扫描/审核状态;提交不等于发布,索引更新也可能延迟 |
|
||||
| 卡片可见但下载失败 | 重新打开详情核对版本、权限和当前资源状态;保留错误信息与 requestId |
|
||||
| 安装后 Agent 找不到 | 对照 CLI 输出检查项目根目录、scope、agent 及 `SKILL.md`;按 Agent 机制重新加载 |
|
||||
|
||||
不要把搜索排名当作安全或质量认证;阅读说明、版本与扫描结果后再选择。
|
||||
|
||||
## 搜索接口边界
|
||||
|
||||
```text
|
||||
GET /api/web/skills?q=pdf&namespace=team&label=data-processing&sort=downloads&page=0&size=20
|
||||
```
|
||||
|
||||
`q`、`namespace`、`label` 可选;API 的 `label` 可重复传入,网页选择器则是单选。`sort` 使用 `relevance`、`downloads` 或 `newest`,页码从 0 开始。API 默认每页 20 项,网页每页 12 项。接口返回 `items`、`total`、`page`、`size` 并遵循当前身份可见范围;实际响应外层封装以实例 OpenAPI 为准。
|
||||
|
||||
## 图示与界面参考
|
||||
|
||||

|
||||
|
||||
**核心特性**:
|
||||
|
||||
- **全文搜索**:搜索技能包名称、描述、标签、作者
|
||||
- **智能过滤**:按命名空间、标签、可见性过滤
|
||||
- **多种排序**:按相关性、下载量、最新排序
|
||||
- **权限感知**:只显示用户有权访问的技能包
|
||||
- **实时更新**:已发布且当前用户可见的技能可被搜索;索引刷新可能有延迟
|
||||
|
||||
**搜索算法**:
|
||||
|
||||
SkillHub 使用 PostgreSQL 全文搜索,支持:
|
||||
- 中英文分词
|
||||
- 模糊匹配
|
||||
- 权重排序(标题权重 > 描述权重 > 标签权重)
|
||||
|
||||
## 使用场景
|
||||
|
||||
**场景一:新成员探索**
|
||||
|
||||
新加入团队的开发者想了解团队已有哪些可用的技能包。
|
||||
|
||||

|
||||
|
||||
**场景二:按需查找**
|
||||
|
||||
开发者需要一个处理 PDF 的技能包,搜索 "pdf" 关键词。
|
||||
|
||||
**场景三:浏览热门**
|
||||
|
||||
查看团队内下载量最高、评分最好的技能包,学习最佳实践。
|
||||
|
||||
**场景四:按标签过滤**
|
||||
|
||||
只查看 `data-processing` 标签的技能包。
|
||||
|
||||
## 使用步骤
|
||||
|
||||
### 使用 CLI 搜索和安装(推荐)
|
||||
|
||||
```bash
|
||||
# 配置注册中心
|
||||
export SKILLHUB_REGISTRY=http://localhost:8080
|
||||
|
||||
# 搜索技能包
|
||||
npx @astron-team/skillhub@latest search pdf
|
||||
|
||||
# 安装技能包
|
||||
npx @astron-team/skillhub@latest install pdf-parser
|
||||
|
||||
# 安装指定命名空间的技能包
|
||||
npx @astron-team/skillhub@latest install my-team--pdf-parser
|
||||
```
|
||||
|
||||
### 使用 Web UI 搜索
|
||||
|
||||
1. **访问搜索页面**
|
||||
|
||||
访问 `http://localhost:3000/search` 或在首页使用搜索框。
|
||||
|
||||
2. **输入关键词**
|
||||
|
||||
在搜索框输入关键词,例如 "pdf parser"。
|
||||
|
||||
3. **应用过滤器**
|
||||
|
||||
- 选择命名空间(例如只看 `iflytek` 命名空间)
|
||||
- 选择标签(例如 `data-processing`)
|
||||
- 选择排序方式(例如按下载量降序)
|
||||
|
||||

|
||||
|
||||
4. **查看结果**
|
||||
|
||||
搜索结果会实时更新,显示匹配的技能包列表。
|
||||
|
||||
5. **查看详情**
|
||||
|
||||
点击技能包卡片,查看详细信息、版本历史、文件列表。
|
||||
|
||||
如果技能被当前用户可见的套件收录,卡片会显示“关联套件”。点击卡片进入技能详情后,可以
|
||||
查看关联套件、入口或普通成员身份,以及可见的配套技能,并跳转到套件详情了解整体用法和
|
||||
安装指引。一个技能可以关联多个套件;这个标识不表示必须整套安装,也不改变单独安装技能的
|
||||
方式。不可访问的套件不会显示关联提示。
|
||||
|
||||
6. **安装使用**
|
||||
|
||||
找到合适的技能包后,使用 CLI 命令安装或点击「下载」按钮。
|
||||
|
||||
## API 接口
|
||||
|
||||
**搜索技能包**:
|
||||
```bash
|
||||
GET /api/web/skills?q=pdf&namespace=iflytek&label=data-processing&sort=downloads&page=0&size=20
|
||||
```
|
||||
|
||||
**参数说明**:
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| q | string | 搜索关键词(可选) |
|
||||
| namespace | string | 命名空间过滤(可选) |
|
||||
| label | string[] | 标签过滤(可选,可多选) |
|
||||
| sort | enum | 排序方式:relevance(相关性)、downloads(下载量)、newest(最新) |
|
||||
| page | number | 页码(从 0 开始) |
|
||||
| size | number | 每页数量(默认 20,最大 100) |
|
||||
|
||||
响应字段和分页封装以部署实例的 OpenAPI 为准。
|
||||
|
||||
## 注意事项
|
||||
|
||||
> **权限控制**:搜索结果会根据用户权限自动过滤。NAMESPACE_ONLY 面向空间成员;PRIVATE 面向所有者及有权管理员,并非所有登录用户或所有空间成员。
|
||||
|
||||
- **搜索性能**:SkillHub 使用 PostgreSQL 全文搜索,支持中英文分词
|
||||
- **实时更新**:已发布且有权访问的技能在索引刷新后可被搜索
|
||||
- **标签规范**:建议使用统一的标签命名规范,便于过滤
|
||||
|
|
|
|||
|
|
@ -1,4 +1,44 @@
|
|||
# Skill 发布与版本管理
|
||||
# 发布与更新技能
|
||||
|
||||
## 从文件到可安装版本
|
||||
|
||||
先确定要发布的是单个技能还是套装:单个技能的上传根目录包含一个 `SKILL.md`;多个技能一起创作和导入请用[套装导入](/guide/suite-bundle)。不要把多份 `SKILL.md` 随意塞进单技能 ZIP。
|
||||
|
||||
1. 在本地 Agent 中验证技能指令、脚本和引用路径,整理成独立目录。
|
||||
2. 确认目标命名空间可写,选择 PUBLIC、NAMESPACE_ONLY 或 PRIVATE。公开发布不是共享所有者电脑上的环境:依赖工具及必要配置应写入技能说明。
|
||||
3. 上传后核对预览的名称、版本、摘要和警告,再提交。预检查阻断必须修正;可确认的警告需逐项理解,不能把确认当作校验通过。
|
||||
4. 在“我的技能”跟踪本次版本,按状态完成扫描、审核或私有确认发布。
|
||||
5. 用另一位目标受众用户检查详情与下载权限,再在目标 Agent 安装并调用。注册中心发布成功不证明技能实际任务效果。
|
||||
|
||||
### 准备技能目录与版本
|
||||
|
||||
```text
|
||||
my-skill/
|
||||
├── SKILL.md
|
||||
├── scripts/ # 仅在技能需要脚本时保留
|
||||
└── references/ # 仅在说明引用资料时保留
|
||||
```
|
||||
|
||||
`SKILL.md` 中引用的相对路径应能在包内找到。不要包含凭证、缓存或与技能无关的项目文件。`version` 可省略,服务器会生成时间版本;需要可预测版本时显式填写,例如 `1.0.0`,下一次更新填写 `1.0.1`。顶层 `version` 优先于 `metadata.version`,不要同时填写不同值。
|
||||
|
||||
### 更新已有技能
|
||||
|
||||
在“我的技能”选择更新,或对同一命名空间和技能名称重新执行发布命令。先核对目标坐标,避免修改 `name` 后创建了另一个技能。已经正式发布的版本不可覆盖,正常迭代应使用新版本号。上传待审新版期间,公开读者仍使用旧的已发布版本;审核通过后再检查详情显示的版本、名称和摘要。
|
||||
|
||||
本地已有安装不会因服务端发布新版而自动更新。使用者需要明确执行 CLI 升级;套装成员还受套装固定版本约束,不能以成员发布新版本代替发布新的套装版本。
|
||||
|
||||
### 发布失败与处理方法
|
||||
|
||||
| 现象 | 下一步 |
|
||||
| --- | --- |
|
||||
| `SKILL.md` frontmatter 无效 | 修正 YAML 与必需字段,重新上传预览 |
|
||||
| 预检查提示疑似密钥或不允许的文件 | 从包中移除敏感内容或修正结构,不能通过确认警告绕过硬错误 |
|
||||
| 版本已存在 | 先查看已有版本,正常更新使用新的版本号 |
|
||||
| 扫描仍在进行 | 等待状态更新,不重复上传同一版本制造多次任务 |
|
||||
| `SCAN_FAILED` | 查看失败原因,按页面提供的重试入口处理;基础设施故障由管理员排查 |
|
||||
| 审核拒绝 | 阅读具体意见,修订包后通过页面支持的重新提交流程操作 |
|
||||
| 命名空间冻结或已失去成员资格 | 先恢复合法写权限;持有旧安装包不赋予发布权限 |
|
||||
|
||||
|
||||
## 功能描述
|
||||
|
||||
|
|
@ -21,7 +61,7 @@ SkillHub 提供了类似 npm 的发布体验,但增加了企业级的权限控
|
|||
- **语义化版本**:支持 `major.minor.patch` 版本号规范
|
||||
- **标签系统**:`latest`、`beta`、`stable` 等自定义标签
|
||||
- **多版本共存**:同一技能包可以保留多个历史版本
|
||||
- **版本解析**:智能解析版本选择器(如 `^1.2.0`、`~2.0.0`)
|
||||
- **版本解析**:按精确版本、标签或指纹解析;不支持 `^` / `~` 版本范围
|
||||
- **文件浏览**:在线浏览技能包内的文件结构
|
||||
- **下载分发**:支持按版本、按标签下载
|
||||
|
||||
|
|
@ -132,7 +172,7 @@ file: skill-package.zip
|
|||
visibility: PUBLIC
|
||||
```
|
||||
|
||||

|
||||

|
||||
|
||||
图示覆盖普通上传;扫描失败、审核拒绝及特权发布的区别见下文。
|
||||
|
||||
|
|
@ -243,15 +283,15 @@ GET /api/v1/skills/{namespace}/{slug}/tags/{tagName}/download
|
|||
|
||||
**版本解析**:
|
||||
```bash
|
||||
GET /api/v1/skills/{namespace}/{slug}/resolve?version=^1.2.0
|
||||
GET /api/v1/skills/{namespace}/{slug}/resolve?version=1.2.0
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
> **版本号规范**:SkillHub 使用语义化版本(Semantic Versioning)。版本号格式为 `major.minor.patch`,例如 `1.2.3`。
|
||||
> **版本号规范**:建议显式使用 `major.minor.patch`,例如 `1.2.3`;省略版本时服务器生成时间版本。
|
||||
|
||||
- **首次发布**:版本号建议从 `0.1.0` 或 `1.0.0` 开始
|
||||
- **标签管理**:`latest` 标签会自动指向最新的稳定版本
|
||||
- **标签管理**:`latest` 由发布状态及发布指针决定,不是客户端自动选择最高 SemVer
|
||||
- **审核流程**:普通 PUBLIC / NAMESPACE_ONLY 上传需要扫描与审核;PRIVATE 上传后还需确认发布
|
||||
- **文件大小限制**:单个技能包不超过 100MB(可配置)
|
||||
- **命名规范**:Skill slug 支持小写字母、数字、连字符和 Unicode 字符
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# 技能套装:安装与使用
|
||||
# 管理技能套装
|
||||
|
||||
Skill Suite(技能套装)把一组已发布 Skill 的精确版本组织成一个有独立名称和版本的集合,并指定一个 Entry Skill(入口技能)。安装后,每个成员仍是独立的技能目录。
|
||||
|
||||
|
|
@ -12,7 +12,7 @@ Skill Suite(技能套装)把一组已发布 Skill 的精确版本组织成
|
|||
|
||||
Bundle 是[创作与导入格式](./suite-bundle),不是安装后需要执行的程序。套装也不是工作流引擎:是否串联成员、如何分派任务,由入口及成员的 `SKILL.md` 决定。普通技能可以独立安装,不必安装它关联的所有套装。
|
||||
|
||||

|
||||

|
||||
|
||||
安装交付的是独立成员文件;在 Agent 中提出任务后才开始使用。
|
||||
|
||||
|
|
@ -72,3 +72,26 @@ skillhub suite remove @team/example-suite
|
|||
已有成员均已发布时,可通过网页套装编辑器选择精确成员版本和入口。需要同时上传多个本地成员时使用 [Suite Bundle](./suite-bundle)。PUBLIC 和 NAMESPACE_ONLY 套装需要套装级审核;PRIVATE 可直接发布。成员扫描和审核仍按各自 Skill 的流程执行。
|
||||
|
||||
每个版本最多 100 个不同成员,必须从成员中指定一个入口;不支持嵌套套装、版本范围或外部 Registry 成员。CLI 当前提供安装管理,不提供 `suite publish` 或直接读取创作定义文件的命令。
|
||||
|
||||
## 读懂本地检查结果
|
||||
|
||||
`skillhub suite check` 同时读取本地记录和远端套装状态,不是完全离线检查。成员状态 `ok` 表示目录内容与固定 fingerprint 一致,`missing` 表示目录缺失,`modified` 表示内容已变更。只有远端最新版与已安装版本一致、已安装版本仍可安装、所有成员均为 `ok` 时,整体才显示 `current`。
|
||||
|
||||
`--json` 中 `ok: false` 也可能表示检测到变化,不一定是命令抛出错误。脚本应检查 JSON 中的成员及远端状态,不能只看进程退出码。
|
||||
|
||||
## 共享成员与升级决策
|
||||
|
||||
两个套装可以复用同来源、同内容的成员目录。某个目标还被另一个套装拥有时,不允许通过升级当前套装原地替换它的版本;`--force` 不是绕过共享来源保护的选项。先检查两个套装的成员计划,选择兼容版本或分离安装目标。
|
||||
|
||||
安装与升级先下载校验全部成员,再提交目录和 inventory;提交中途失败会尝试恢复本次替换的目录。失败后保留错误信息,重新 `check` 核对,不要手改安装记录伪造成功。
|
||||
|
||||
## 常见问题
|
||||
|
||||
| 现象 | 处理 |
|
||||
| --- | --- |
|
||||
| `unknown suite action` | 只支持 install、check、upgrade、remove;没有 run/publish 子命令 |
|
||||
| 服务端不支持套装能力 | 核对 registry 与服务端版本;普通 install 不会自动安装套装 |
|
||||
| `modified` | 先备份或移走需要的修改,再决定是否接受安装/升级覆盖 |
|
||||
| 成员下架或权限收窄 | 套装快照仍保留,但安装计划会阻止安装;联系维护者发布可安装的新版本 |
|
||||
| 卸载显示 `Preserved` | 检查 shared、modified、missing 原因;保留成员不等于卸载失败 |
|
||||
| 指定 agent 检查/卸载被拒绝 | 这些选项仅属于 install;后续操作按本地套装记录执行 |
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# 用户交互与社交
|
||||
# 收藏、评分与通知
|
||||
|
||||
## 功能描述
|
||||
|
||||
|
|
@ -20,7 +20,7 @@ SkillHub 提供了丰富的社交功能,让团队成员可以互动、分享
|
|||
| **星标数** | 有多少人收藏了这个技能包 |
|
||||
| **平均评分** | 所有用户评分的平均值 |
|
||||
| **下载量** | 累计下载次数 |
|
||||
| **活跃度** | 最近更新时间、发布频率 |
|
||||
| **更新时间** | 当前列表显示的更新时间 |
|
||||
|
||||
## 使用场景
|
||||
|
||||
|
|
@ -85,6 +85,27 @@ SkillHub 提供了丰富的社交功能,让团队成员可以互动、分享
|
|||
3. 分页浏览收藏列表;需要筛选时到搜索页启用“仅收藏”
|
||||
4. 快速访问常用技能包
|
||||
|
||||
## 操作前确认身份
|
||||
|
||||
收藏、评分和通知属于当前登录账号。匿名点击收藏或评分会触发登录提示;切换账号后请重新检查状态。收藏不会安装技能,取消收藏不会删除本地安装。评分按钮在请求期间禁用,提交成功后才刷新自己的评分及技能数据,悬停预览星数不代表保存成功。
|
||||
|
||||
## 管理通知而不遗漏处理
|
||||
|
||||
打开 `/notifications`,按全部、发布、审核、提升或举报分类查看,每页最多 20 条。点击未读项会标记已读并跳转到关联对象;通知本身不是执行审核批准的按钮,仍需在目标页面完成操作。
|
||||
|
||||
可以将通知全部标为已读;删除按钮仅用于已读通知。若希望减少提醒,打开 `/settings/notifications`,按分类调整站内通知开关。当前表单配置的是 `IN_APP`,不是邮件或短信订阅;没有保存偏好时默认开启。
|
||||
|
||||
## 确认结果与排查
|
||||
|
||||
| 操作或现象 | 可观察结果 / 下一步 |
|
||||
| --- | --- |
|
||||
| 收藏成功 | 按钮切换为已收藏,随后在“我的收藏”确认 |
|
||||
| 修改星级 | 等待请求完成,核对“你的评分”;不要把悬停效果当成提交 |
|
||||
| 清空评价 | 文字被清除,原有星级仍保留;这是不同于取消收藏的操作 |
|
||||
| 自己能看到评价,公开列表没有 | 检查是否被隐藏;作者编辑不会自动恢复公开 |
|
||||
| 通知仍显示旧未读数 | 等待轮询或重新聚焦窗口;仍异常时检查请求和登录状态 |
|
||||
| 通知目标不可访问 | 重新核对资源当前状态和权限;历史通知不会恢复已失去的访问权 |
|
||||
|
||||
## API 接口
|
||||
|
||||
**星标技能包**:
|
||||
|
|
@ -159,4 +180,4 @@ POST /api/v1/admin/skill-reviews/{reviewId}/restore
|
|||
- **星标数量**:技能包的星标数会显示在搜索结果和详情页
|
||||
- **平均评分**:平均评分供选择技能时参考,不是搜索页的独立排序选项
|
||||
- **通知设置**:用户可以在设置中关闭某些类型的通知
|
||||
- **下载统计**:每次下载都会增加下载计数,用于热门排序
|
||||
- **下载统计**:已发布版本的下载会记录计数;审核预览下载不计入公开下载统计
|
||||
|
|
|
|||
|
|
@ -1,9 +1,29 @@
|
|||
# Suite Bundle 批量导入
|
||||
# 通过 Bundle 导入技能套装
|
||||
|
||||
Suite Bundle 用一次 ZIP 或文件夹上传,为 Suite 创建首个版本,或基于一个已发布版本创建新版本。系统先展示成员差异,只有用户明确确认后才进入成员 Skill 的正常发布和审核流程。
|
||||
|
||||
安装和调用请先阅读[技能套装使用指南](./skill-suites)。本页面向批量导入内容的作者。`SUITE.yaml`(`kind: SkillSuiteBundle`)与套装设计中的 `suite.yaml`(`kind: SkillSuite`)不是同一种文件。
|
||||
|
||||
## 适合谁、准备什么
|
||||
|
||||
本页面向套装作者。只想安装使用的人应阅读[技能套装](/guide/skill-suites),不需要制作 Bundle。导入前准备目标空间的写权限、完整成员清单、一个入口成员,以及每个 package 成员自己的有效 `SKILL.md`。reference 成员必须已经发布且你有权访问。
|
||||
|
||||
Bundle 用来创建成员版本并生成套装草稿,不会直接把技能安装进本地 Agent,也不会跳过成员审核。创建前确认套装坐标未被占用;更新前记录基准套装版本,不要把增量清单当成完整新版本。
|
||||
|
||||
## 导入中断与恢复
|
||||
|
||||
| 操作状态 | 含义与处理 |
|
||||
| --- | --- |
|
||||
| `RUNNING` | 成员发布处理中,查看成员行定位进度 |
|
||||
| `WAITING_FOR_MEMBERS` | 等待成员完成发布流程;按成员链接查看审核状态 |
|
||||
| `BLOCKED_RETRYABLE` | 查看具体受阻成员;扫描失败与成员发布失败使用不同重试提示,权限或空间状态问题需先恢复条件 |
|
||||
| `REPREVIEW_REQUIRED` | 计划或基准发生变化,重新上传并预览,不能直接确认旧计划 |
|
||||
| `SUITE_DRAFT_CREATED` | 成员阶段结束,打开生成的套装草稿继续审核与发布;这不是套装已发布 |
|
||||
| `CANCELLED` | 本次套装创建已停止;已创建的成员版本及审核不会被自动撤销,仍可从成员链接跟踪 |
|
||||
|
||||
刷新页面后查看同一持久化操作,不要为了“继续”另建一份套装。完成后如无法打开草稿,保留操作 ID 并请管理员检查结果关联;不要把完成状态理解为所有结果均可访问。
|
||||
|
||||
|
||||
## 归档结构
|
||||
|
||||
归档根目录必须且只能有一个 `SUITE.yaml`。每个携带包的成员使用独立目录,目录根部必须包含 `SKILL.md`。未声明的 `SKILL.md`、目录重叠、路径穿越、重复路径、超出大小或文件数限制都会阻止预览。
|
||||
|
|
|
|||
|
|
@ -13,8 +13,8 @@ hero:
|
|||
text: 快速开始
|
||||
link: /quickstart
|
||||
- theme: alt
|
||||
text: 功能指南
|
||||
link: /guide/skill-publish
|
||||
text: 文档导航
|
||||
link: /guide/
|
||||
- theme: alt
|
||||
text: GitHub
|
||||
link: https://github.com/iflytek/skillhub
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ SkillHub 解决了这个问题。它提供了一个**私有、可控、易用**
|
|||
|
||||
## 技术栈
|
||||
|
||||

|
||||

|
||||
|
||||
存储可选择本地文件或 S3 兼容后端;按部署需求显式配置。
|
||||
|
||||
|
|
|
|||
|
|
@ -1,49 +0,0 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1080 510" role="img" aria-labelledby="title desc">
|
||||
<title id="title">Skill publication: ordinary upload paths</title><desc id="desc">Public submissions require scan and review; private submissions require publication confirmation.</desc>
|
||||
<defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M1 1 L7 4 L1 7" fill="none" stroke="#222" stroke-width="1.5"/></marker></defs>
|
||||
<rect width="1080" height="510" fill="#fff"/>
|
||||
<style>text{font-family:Arial,"Noto Sans CJK SC","Microsoft YaHei",sans-serif;fill:#202124}.title{font-size:25px;font-weight:600}.head{font-size:18px;font-weight:600}.body{font-size:16px}.note{font-size:15px;fill:#4b5563}.card{fill:#fff;stroke:#222;stroke-width:1.7}.line{fill:none;stroke:#222;stroke-width:1.6;marker-end:url(#arrow)}</style>
|
||||
<text x="36" y="42" class="title">Skill publication: ordinary upload paths</text>
|
||||
<text x="36" y="80" class="note">Submission accepted ≠ published. Follow the version status.</text>
|
||||
<text x="36" y="122" class="head">PUBLIC / NAMESPACE_ONLY</text>
|
||||
<rect x="36" y="151" width="229" height="112" rx="15" class="card"/><rect x="48" y="138" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="59" y="161" class="head">Upload</text>
|
||||
<text x="52" y="204" class="body">SKILL.md + files</text>
|
||||
<text x="52" y="229" class="body">Validate package</text>
|
||||
<rect x="295" y="151" width="229" height="112" rx="15" class="card"/><rect x="307" y="138" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="318" y="161" class="head">Scan</text>
|
||||
<text x="311" y="204" class="body">SCANNING</text>
|
||||
<text x="311" y="229" class="body">Scanning required</text>
|
||||
<rect x="554" y="151" width="229" height="112" rx="15" class="card"/><rect x="566" y="138" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="577" y="161" class="head">Review</text>
|
||||
<text x="570" y="204" class="body">PENDING_REVIEW</text>
|
||||
<text x="570" y="229" class="body">Approval required</text>
|
||||
<rect x="813" y="151" width="229" height="112" rx="15" class="card"/><rect x="825" y="138" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="836" y="161" class="head">Published</text>
|
||||
<text x="829" y="204" class="body">PUBLISHED</text>
|
||||
<text x="829" y="229" class="body">Audience rules apply</text>
|
||||
<path d="M265 206 L295 206" class="line"/>
|
||||
<path d="M524 206 L554 206" class="line"/>
|
||||
<path d="M783 206 L813 206" class="line"/>
|
||||
<text x="36" y="307" class="head">PRIVATE</text>
|
||||
<rect x="36" y="336" width="229" height="112" rx="15" class="card"/><rect x="48" y="323" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="59" y="346" class="head">Upload</text>
|
||||
<text x="52" y="389" class="body">SKILL.md + files</text>
|
||||
<text x="52" y="414" class="body">Validate package</text>
|
||||
<rect x="295" y="336" width="229" height="112" rx="15" class="card"/><rect x="307" y="323" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="318" y="346" class="head">Configured scan</text>
|
||||
<text x="311" y="389" class="body">SCANNING if enabled</text>
|
||||
<text x="311" y="414" class="body">Otherwise skip</text>
|
||||
<rect x="554" y="336" width="229" height="112" rx="15" class="card"/><rect x="566" y="323" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="577" y="346" class="head">Confirm publish</text>
|
||||
<text x="570" y="389" class="body">UPLOADED</text>
|
||||
<text x="570" y="414" class="body">Explicit confirmation</text>
|
||||
<rect x="813" y="336" width="229" height="112" rx="15" class="card"/><rect x="825" y="323" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="836" y="346" class="head">Published</text>
|
||||
<text x="829" y="389" class="body">PUBLISHED</text>
|
||||
<text x="829" y="414" class="body">Private access only</text>
|
||||
<path d="M265 391 L295 391" class="line"/>
|
||||
<path d="M524 391 L554 391" class="line"/>
|
||||
<path d="M783 391 L813 391" class="line"/>
|
||||
<text x="36" y="480" class="note">Scan failure or rejection stops these paths. Privileged auto-publish is a separate path.</text>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 3.9 KiB |
BIN
docs/skillhub/public/diagrams/skill-publish-lifecycle-sketch.png
Normal file
|
After Width: | Height: | Size: 2 MiB |
|
|
@ -1,49 +0,0 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1080 510" role="img" aria-labelledby="title desc">
|
||||
<title id="title">技能发布:普通上传路径</title><desc id="desc">公开及命名空间上传经过扫描与审核;私有上传需要确认发布。</desc>
|
||||
<defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M1 1 L7 4 L1 7" fill="none" stroke="#222" stroke-width="1.5"/></marker></defs>
|
||||
<rect width="1080" height="510" fill="#fff"/>
|
||||
<style>text{font-family:Arial,"Noto Sans CJK SC","Microsoft YaHei",sans-serif;fill:#202124}.title{font-size:25px;font-weight:600}.head{font-size:18px;font-weight:600}.body{font-size:16px}.note{font-size:15px;fill:#4b5563}.card{fill:#fff;stroke:#222;stroke-width:1.7}.line{fill:none;stroke:#222;stroke-width:1.6;marker-end:url(#arrow)}</style>
|
||||
<text x="36" y="42" class="title">技能发布:普通上传路径</text>
|
||||
<text x="36" y="80" class="note">提交成功 ≠ 发布成功;以本次版本状态为准。</text>
|
||||
<text x="36" y="122" class="head">PUBLIC / NAMESPACE_ONLY</text>
|
||||
<rect x="36" y="151" width="229" height="112" rx="15" class="card"/><rect x="48" y="138" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="59" y="161" class="head">上传</text>
|
||||
<text x="52" y="204" class="body">SKILL.md 与文件</text>
|
||||
<text x="52" y="229" class="body">校验包结构与权限</text>
|
||||
<rect x="295" y="151" width="229" height="112" rx="15" class="card"/><rect x="307" y="138" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="318" y="161" class="head">扫描</text>
|
||||
<text x="311" y="204" class="body">SCANNING</text>
|
||||
<text x="311" y="229" class="body">要求启用扫描</text>
|
||||
<rect x="554" y="151" width="229" height="112" rx="15" class="card"/><rect x="566" y="138" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="577" y="161" class="head">审核</text>
|
||||
<text x="570" y="204" class="body">PENDING_REVIEW</text>
|
||||
<text x="570" y="229" class="body">等待审核批准</text>
|
||||
<rect x="813" y="151" width="229" height="112" rx="15" class="card"/><rect x="825" y="138" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="836" y="161" class="head">已发布</text>
|
||||
<text x="829" y="204" class="body">PUBLISHED</text>
|
||||
<text x="829" y="229" class="body">按可见范围分发</text>
|
||||
<path d="M265 206 L295 206" class="line"/>
|
||||
<path d="M524 206 L554 206" class="line"/>
|
||||
<path d="M783 206 L813 206" class="line"/>
|
||||
<text x="36" y="307" class="head">PRIVATE</text>
|
||||
<rect x="36" y="336" width="229" height="112" rx="15" class="card"/><rect x="48" y="323" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="59" y="346" class="head">上传</text>
|
||||
<text x="52" y="389" class="body">SKILL.md 与文件</text>
|
||||
<text x="52" y="414" class="body">校验包结构与权限</text>
|
||||
<rect x="295" y="336" width="229" height="112" rx="15" class="card"/><rect x="307" y="323" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="318" y="346" class="head">按配置扫描</text>
|
||||
<text x="311" y="389" class="body">启用时进入 SCANNING</text>
|
||||
<text x="311" y="414" class="body">未启用则跳过</text>
|
||||
<rect x="554" y="336" width="229" height="112" rx="15" class="card"/><rect x="566" y="323" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="577" y="346" class="head">确认发布</text>
|
||||
<text x="570" y="389" class="body">UPLOADED</text>
|
||||
<text x="570" y="414" class="body">显式确认后发布</text>
|
||||
<rect x="813" y="336" width="229" height="112" rx="15" class="card"/><rect x="825" y="323" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="836" y="346" class="head">已发布</text>
|
||||
<text x="829" y="389" class="body">PUBLISHED</text>
|
||||
<text x="829" y="414" class="body">仍受私有权限约束</text>
|
||||
<path d="M265 391 L295 391" class="line"/>
|
||||
<path d="M524 391 L554 391" class="line"/>
|
||||
<path d="M783 391 L813 391" class="line"/>
|
||||
<text x="36" y="480" class="note">扫描执行失败或审核拒绝会中断上述路径。特权自动发布属于另一条路径。</text>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 3.9 KiB |
|
|
@ -1,32 +0,0 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1080 480" role="img" aria-labelledby="title desc">
|
||||
<title id="title">Skill Suite: install, then use the entry skill</title><desc id="desc">A pinned Suite installs separate Skill directories. The user asks an Agent to use the entry skill.</desc>
|
||||
<defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M1 1 L7 4 L1 7" fill="none" stroke="#222" stroke-width="1.5"/></marker></defs>
|
||||
<rect width="1080" height="480" fill="#fff"/>
|
||||
<style>text{font-family:Arial,"Noto Sans CJK SC","Microsoft YaHei",sans-serif;fill:#202124}.title{font-size:25px;font-weight:600}.head{font-size:18px;font-weight:600}.body{font-size:16px}.note{font-size:15px;fill:#4b5563}.card{fill:#fff;stroke:#222;stroke-width:1.7}.line{fill:none;stroke:#222;stroke-width:1.6;marker-end:url(#arrow)}</style>
|
||||
<text x="36" y="42" class="title">Skill Suite: install, then use the entry skill</text>
|
||||
<text x="36" y="80" class="note">Registry and CLI manage delivery; the Agent follows the installed instructions.</text>
|
||||
<rect x="36" y="135" width="229" height="112" rx="15" class="card"/><rect x="48" y="122" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="59" y="145" class="head">1. Choose Suite</text>
|
||||
<text x="52" y="188" class="body">Exact member versions</text>
|
||||
<text x="52" y="213" class="body">One entry member</text>
|
||||
<rect x="295" y="135" width="229" height="112" rx="15" class="card"/><rect x="307" y="122" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="318" y="145" class="head">2. Install</text>
|
||||
<text x="311" y="188" class="body">skillhub suite install</text>
|
||||
<text x="311" y="213" class="body">Download and verify</text>
|
||||
<rect x="554" y="135" width="229" height="112" rx="15" class="card"/><rect x="566" y="122" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="577" y="145" class="head">3. Separate skills</text>
|
||||
<text x="570" y="188" class="body">entry-skill/SKILL.md</text>
|
||||
<text x="570" y="213" class="body">member-a/SKILL.md</text>
|
||||
<rect x="813" y="135" width="229" height="112" rx="15" class="card"/><rect x="825" y="122" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="836" y="145" class="head">4. Ask the Agent</text>
|
||||
<text x="829" y="188" class="body">Discover entry skill</text>
|
||||
<text x="829" y="213" class="body">Provide a task</text>
|
||||
<path d="M265 190 L295 190" class="line"/>
|
||||
<path d="M524 190 L554 190" class="line"/>
|
||||
<path d="M783 190 L813 190" class="line"/>
|
||||
<rect x="36" y="298" width="1006" height="132" rx="15" fill="#f4f7ff" stroke="#222" stroke-width="1.5"/>
|
||||
<text x="56" y="329" class="head">Usage boundaries</text>
|
||||
<text x="56" y="359" class="body">The entry remains an ordinary Skill. Other members can also be used directly.</text>
|
||||
<text x="56" y="385" class="body">Member coordination depends on SKILL.md; installation does not execute a workflow.</text>
|
||||
<text x="56" y="411" class="body">Configure required tools and credentials separately. There is no generic suite run command.</text>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 3 KiB |
BIN
docs/skillhub/public/diagrams/skill-suite-usage-sketch.png
Normal file
|
After Width: | Height: | Size: 1.5 MiB |
|
|
@ -1,32 +0,0 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1080 480" role="img" aria-labelledby="title desc">
|
||||
<title id="title">技能套装:安装成员,再使用入口技能</title><desc id="desc">固定版本套装安装为独立成员目录,用户再请求 Agent 使用入口技能。</desc>
|
||||
<defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M1 1 L7 4 L1 7" fill="none" stroke="#222" stroke-width="1.5"/></marker></defs>
|
||||
<rect width="1080" height="480" fill="#fff"/>
|
||||
<style>text{font-family:Arial,"Noto Sans CJK SC","Microsoft YaHei",sans-serif;fill:#202124}.title{font-size:25px;font-weight:600}.head{font-size:18px;font-weight:600}.body{font-size:16px}.note{font-size:15px;fill:#4b5563}.card{fill:#fff;stroke:#222;stroke-width:1.7}.line{fill:none;stroke:#222;stroke-width:1.6;marker-end:url(#arrow)}</style>
|
||||
<text x="36" y="42" class="title">技能套装:安装成员,再使用入口技能</text>
|
||||
<text x="36" y="80" class="note">注册中心与 CLI 管理分发,Agent 根据已安装的技能说明处理任务。</text>
|
||||
<rect x="36" y="135" width="229" height="112" rx="15" class="card"/><rect x="48" y="122" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="59" y="145" class="head">1. 选择套装</text>
|
||||
<text x="52" y="188" class="body">固定成员版本</text>
|
||||
<text x="52" y="213" class="body">指定一个入口成员</text>
|
||||
<rect x="295" y="135" width="229" height="112" rx="15" class="card"/><rect x="307" y="122" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="318" y="145" class="head">2. 安装成员</text>
|
||||
<text x="311" y="188" class="body">skillhub suite install</text>
|
||||
<text x="311" y="213" class="body">下载并校验成员</text>
|
||||
<rect x="554" y="135" width="229" height="112" rx="15" class="card"/><rect x="566" y="122" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="577" y="145" class="head">3. 独立技能目录</text>
|
||||
<text x="570" y="188" class="body">entry-skill/SKILL.md</text>
|
||||
<text x="570" y="213" class="body">member-a/SKILL.md</text>
|
||||
<rect x="813" y="135" width="229" height="112" rx="15" class="card"/><rect x="825" y="122" width="205" height="33" rx="10" fill="#5c83ef"/>
|
||||
<text x="836" y="145" class="head">4. 请求 Agent 使用</text>
|
||||
<text x="829" y="188" class="body">确认入口可被发现</text>
|
||||
<text x="829" y="213" class="body">提供具体任务</text>
|
||||
<path d="M265 190 L295 190" class="line"/>
|
||||
<path d="M524 190 L554 190" class="line"/>
|
||||
<path d="M783 190 L813 190" class="line"/>
|
||||
<rect x="36" y="298" width="1006" height="132" rx="15" fill="#f4f7ff" stroke="#222" stroke-width="1.5"/>
|
||||
<text x="56" y="329" class="head">使用边界</text>
|
||||
<text x="56" y="359" class="body">入口仍是普通 Skill,其他成员也可以独立使用。</text>
|
||||
<text x="56" y="385" class="body">成员如何协作由 SKILL.md 决定;安装不会自动执行工作流。</text>
|
||||
<text x="56" y="411" class="body">工具和凭据按技能说明配置;SkillHub 没有通用的 suite run 命令。</text>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 3 KiB |
|
|
@ -1,26 +0,0 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1080 650" role="img" aria-labelledby="title desc"><title id="title">SkillHub technology stack</title>
|
||||
<desc id="desc">Four layers: frontend, backend, database and cache, and configurable skill file storage.</desc>
|
||||
<rect width="1080" height="650" fill="#fff"/>
|
||||
<style>text{font-family:Arial,"Noto Sans CJK SC","Microsoft YaHei",sans-serif;fill:#202124}.title{font-size:25px;font-weight:600}.head{font-size:19px;font-weight:600}.body{font-size:22px}.note{font-size:17px;fill:#4b5563}</style>
|
||||
<text x="36" y="43" class="title">SkillHub technology stack</text>
|
||||
<rect x="36" y="99" width="1008" height="105" rx="15" fill="#fff" stroke="#222" stroke-width="1.7"/>
|
||||
<rect x="52" y="86" width="290" height="34" rx="10" fill="#5c83ef"/>
|
||||
<text x="68" y="109" class="head">Frontend</text>
|
||||
<text x="60" y="154" class="body">React · Vite · Tailwind CSS</text>
|
||||
<text x="60" y="182" class="note">TanStack Router · TanStack Query</text>
|
||||
<rect x="36" y="229" width="1008" height="105" rx="15" fill="#fff" stroke="#222" stroke-width="1.7"/>
|
||||
<rect x="52" y="216" width="290" height="34" rx="10" fill="#5c83ef"/>
|
||||
<text x="68" y="239" class="head">Backend</text>
|
||||
<text x="60" y="284" class="body">Java 21 · Spring Boot</text>
|
||||
<text x="60" y="312" class="note">REST API</text>
|
||||
<rect x="36" y="359" width="1008" height="105" rx="15" fill="#fff" stroke="#222" stroke-width="1.7"/>
|
||||
<rect x="52" y="346" width="290" height="34" rx="10" fill="#5c83ef"/>
|
||||
<text x="68" y="369" class="head">Database and cache</text>
|
||||
<text x="60" y="414" class="body">PostgreSQL · Redis</text>
|
||||
<text x="60" y="442" class="note">Persistence and sessions</text>
|
||||
<rect x="36" y="489" width="1008" height="105" rx="15" fill="#fff" stroke="#222" stroke-width="1.7"/>
|
||||
<rect x="52" y="476" width="290" height="34" rx="10" fill="#5c83ef"/>
|
||||
<text x="68" y="499" class="head">Skill file storage</text>
|
||||
<text x="60" y="544" class="body">Local files / S3-compatible</text>
|
||||
<text x="60" y="572" class="note">Select a provider in deployment configuration</text>
|
||||
<text x="36" y="626" class="note">Components, not an execution sequence. Versions follow the repository manifests.</text></svg>
|
||||
|
Before Width: | Height: | Size: 2.1 KiB |
BIN
docs/skillhub/public/diagrams/tech-stack-sketch.png
Normal file
|
After Width: | Height: | Size: 1.8 MiB |
|
|
@ -1,26 +0,0 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1080 650" role="img" aria-labelledby="title desc"><title id="title">SkillHub 技术栈</title>
|
||||
<desc id="desc">四层技术组成:前端、后端、数据库与缓存、可配置的技能文件存储。</desc>
|
||||
<rect width="1080" height="650" fill="#fff"/>
|
||||
<style>text{font-family:Arial,"Noto Sans CJK SC","Microsoft YaHei",sans-serif;fill:#202124}.title{font-size:25px;font-weight:600}.head{font-size:19px;font-weight:600}.body{font-size:22px}.note{font-size:17px;fill:#4b5563}</style>
|
||||
<text x="36" y="43" class="title">SkillHub 技术栈</text>
|
||||
<rect x="36" y="99" width="1008" height="105" rx="15" fill="#fff" stroke="#222" stroke-width="1.7"/>
|
||||
<rect x="52" y="86" width="290" height="34" rx="10" fill="#5c83ef"/>
|
||||
<text x="68" y="109" class="head">前端</text>
|
||||
<text x="60" y="154" class="body">React · Vite · Tailwind CSS</text>
|
||||
<text x="60" y="182" class="note">TanStack Router · TanStack Query</text>
|
||||
<rect x="36" y="229" width="1008" height="105" rx="15" fill="#fff" stroke="#222" stroke-width="1.7"/>
|
||||
<rect x="52" y="216" width="290" height="34" rx="10" fill="#5c83ef"/>
|
||||
<text x="68" y="239" class="head">后端</text>
|
||||
<text x="60" y="284" class="body">Java 21 · Spring Boot</text>
|
||||
<text x="60" y="312" class="note">REST API</text>
|
||||
<rect x="36" y="359" width="1008" height="105" rx="15" fill="#fff" stroke="#222" stroke-width="1.7"/>
|
||||
<rect x="52" y="346" width="290" height="34" rx="10" fill="#5c83ef"/>
|
||||
<text x="68" y="369" class="head">数据库与缓存</text>
|
||||
<text x="60" y="414" class="body">PostgreSQL · Redis</text>
|
||||
<text x="60" y="442" class="note">持久化与会话管理</text>
|
||||
<rect x="36" y="489" width="1008" height="105" rx="15" fill="#fff" stroke="#222" stroke-width="1.7"/>
|
||||
<rect x="52" y="476" width="290" height="34" rx="10" fill="#5c83ef"/>
|
||||
<text x="68" y="499" class="head">技能文件存储</text>
|
||||
<text x="60" y="544" class="body">本地文件 / S3 兼容存储</text>
|
||||
<text x="60" y="572" class="note">在部署配置中选择存储后端</text>
|
||||
<text x="36" y="626" class="note">图示为技术组成,不表示执行顺序;具体版本以仓库依赖清单为准。</text></svg>
|
||||
|
Before Width: | Height: | Size: 2.1 KiB |
|
|
@ -1,15 +1,14 @@
|
|||
# 快速开始
|
||||
# 快速开始:安装并使用技能
|
||||
|
||||
先选择你的目标:使用已有技能不需要部署 SkillHub;团队自托管和源码开发使用不同入口。
|
||||
安装第一个技能,并在 Agent 中使用。本页使用已有的注册中心,不需要先部署 SkillHub 服务。
|
||||
|
||||
| 目标 | 从这里开始 |
|
||||
| --- | --- |
|
||||
| 搜索、安装并使用技能 | 本页的安装流程 |
|
||||
| 使用一组配套技能 | [技能套装](./guide/skill-suites.md) |
|
||||
| 发布自己的技能 | [发布与版本管理](./guide/skill-publish.md) |
|
||||
| 批量上传套装和成员 | [Suite Bundle 导入](./guide/suite-bundle.md) |
|
||||
| 部署团队注册中心 | [Docker 部署](./guide/deployment.md) / [Kubernetes](./guide/kubernetes.md) |
|
||||
| 修改 SkillHub 源码 | [开发手册](https://github.com/iflytek/skillhub/blob/main/docs/dev-workflow.md) |
|
||||
## 开始前准备
|
||||
|
||||
- 一个支持技能目录的 Agent,例如 Codex 或 Claude Code。
|
||||
- Node.js 18 或更新版本,以及可用的 npm;可用 `node --version` 确认版本。
|
||||
- 一个准备使用技能的项目目录,以及能访问的 SkillHub 注册中心地址。
|
||||
|
||||
本页命令使用终端运行,`@team/example-skill` 是占位坐标,不是保证存在的公共技能。选择实际搜索结果后再替换。项目级安装前,先切换到准备让 Agent 打开的项目根目录。
|
||||
|
||||
## 1. 安装 CLI,选择注册中心
|
||||
|
||||
|
|
@ -24,6 +23,14 @@ skillhub version
|
|||
export SKILLHUB_REGISTRY=https://skillhub.example.com
|
||||
```
|
||||
|
||||
PowerShell 中设置注册中心使用:
|
||||
|
||||
```powershell
|
||||
$env:SKILLHUB_REGISTRY="https://skillhub.example.com"
|
||||
```
|
||||
|
||||
只想临时使用另一个实例时,可以在命令后添加 `--registry https://skillhub.example.com`。搜索、登录和安装应使用同一个注册中心;不同实例中的同名技能不是同一安装来源。
|
||||
|
||||
公开技能可匿名搜索和安装。发布、访问受限资源等操作需要登录:
|
||||
|
||||
```bash
|
||||
|
|
@ -31,7 +38,7 @@ skillhub login
|
|||
skillhub whoami
|
||||
```
|
||||
|
||||
按终端提示在浏览器完成登录和设备码确认。远程终端可用 `skillhub login --no-open`。账号是否可以注册、使用哪些登录方式,由实例配置决定。
|
||||
没有从命令行、环境变量或该注册中心的保存记录读取到 Token 时,CLI 会进入设备授权;按终端提示在浏览器完成登录和设备码确认。已有 Token 时先用该 Token 验证身份,不会自动重新选账号。远程终端可用 `skillhub login --no-open`。账号是否可以注册、使用哪些登录方式,由实例配置决定。
|
||||
|
||||
## 2. 找到技能并安装
|
||||
|
||||
|
|
@ -51,6 +58,12 @@ skillhub list --agent codex
|
|||
Claude Code 用户改用 `--agent claude-code`。希望多个项目共用时,使用 `--scope user`。
|
||||
项目级 Codex 安装目录为 `.codex/skills/<slug>/`,Claude Code 为 `.claude/skills/<slug>/`;用户级路径位于用户主目录。
|
||||
|
||||
### 确认安装到了哪里
|
||||
|
||||
查看安装命令输出的目标路径,再查看 `skillhub list --agent codex` 的记录:坐标、版本、Agent、目录和状态应符合刚才选择的目标。`list` 按当前注册中心过滤;切换注册中心后列表变化不代表本地文件被删除。
|
||||
|
||||
状态 `missing` 表示记录对应的目录不存在;`ok` 只表示目录存在,不代表 Agent 已加载或技能已执行成功。进入实际目录检查 `SKILL.md`,再继续下一步。
|
||||
|
||||
## 3. 在 Agent 中使用
|
||||
|
||||
安装完成后,在目标 Agent 中打开项目,必要时新建会话或重新加载技能。先确认 Agent 能发现该技能,再提出具体任务,例如:
|
||||
|
|
@ -71,26 +84,15 @@ skillhub upgrade @team/example-skill
|
|||
|
||||
检查计划后再更新。保留需要的本地修改;不要把 `--force` 当作默认参数。卸载、同步团队工作区和完整命令说明见 [CLI 指南](./guide/cli.md)。
|
||||
|
||||
## 5. 发布自己的技能
|
||||
## 常见问题与处理
|
||||
|
||||
技能包根目录必须包含大写 `SKILL.md`,最小内容如下:
|
||||
| 现象 | 先检查什么 | 下一步 |
|
||||
| --- | --- | --- |
|
||||
| 搜索不到目标技能 | 当前注册中心、拼写、登录身份和资源可见性 | 在网页确认坐标和版本是否已发布,见[搜索与安装](./guide/skill-discovery.md) |
|
||||
| 安装时报同名目录冲突 | 输出的目标目录是否来自另一来源或包含自己的文件 | 先保留所需内容,不直接使用 `--force` 覆盖未知目录,见[CLI 参考](./guide/cli.md) |
|
||||
| 安装成功但 Agent 看不到 | Agent 类型、项目根目录、user/project 范围 | 对照安装输出路径,按 Agent 的发现方式重载或重开会话 |
|
||||
| Agent 已加载但执行失败 | 技能说明所需的工具、输入和凭据 | 按 `SKILL.md` 配置运行环境;注册中心不会代为执行这些步骤 |
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: example-skill
|
||||
description: Describe when to use this skill and what it does.
|
||||
---
|
||||
## 下一步
|
||||
|
||||
# Example skill
|
||||
|
||||
Explain the inputs, steps, expected output, and required tools.
|
||||
```
|
||||
|
||||
可以按需添加 `scripts/`、`references/` 和 `assets/`;不要求 `package.json`。
|
||||
先在 Web 创建或加入有发布权限的命名空间,再按照 [发布指南](./guide/skill-publish.md) 准备版本并上传:
|
||||
|
||||
```bash
|
||||
skillhub publish ./example-skill --namespace my-team
|
||||
```
|
||||
|
||||
命令提交成功不代表版本已发布。查看返回的详情地址,跟踪扫描、审核和最终状态;只有满足发布条件的版本才进入正常安装流程。
|
||||
需要配套技能时,阅读[技能套装](./guide/skill-suites.md);需要更多命令时,查阅 [CLI 指南](./guide/cli.md)。发布技能、管理团队、自托管和源码开发,请从[文档导航](./guide/index.md)选择对应任务。
|
||||
|
|
|
|||