diff --git a/README.md b/README.md index fa8c58417..73b300d97 100644 --- a/README.md +++ b/README.md @@ -62,9 +62,13 @@ with the Skill's source and the problem it solves, or submit a PR by following t ## Documentation -- 📖 **[User Guide](https://iflytek.github.io/skillhub/)** — Skill publishing, search, CLI usage and other user guides -- 🛠️ **[Developer Docs](https://zread.ai/iflytek/skillhub)** — Architecture, API reference, local development, deployment and operations -- 🐍 **[Python Examples](./examples/python)** — Search, download, and publish skills from Python via the REST API +- **[User Guide](https://iflytek.github.io/skillhub/)** — [中文](docs/skillhub/quickstart.md) / [English](docs/skillhub/en/quickstart.md): find, install, and use skills in your agent +- **[CLI reference](cli/README.md)** — Authentication, installation, upgrades, namespace synchronization, and local inventory +- **[Skill Suites](docs/skillhub/en/guide/skill-suites.md)** — Install a versioned collection and use its entry skill; [Suite Bundle import](docs/skillhub/en/guide/suite-bundle.md) is the separate authoring workflow +- **[Self-hosting](docs/skillhub/en/guide/deployment.md)** — Docker Compose configuration and upgrades; [Kubernetes](docs/skillhub/en/guide/kubernetes.md) for clusters +- **[Developer workflow](docs/dev-workflow.md)** — Source development, checks, and documentation maintenance; [operations reference](docs/09-deployment.md) for deployment details +- **[Generated code overview](https://zread.ai/iflytek/skillhub)** — Supplementary architecture exploration; repository source and versioned documentation define current behavior +- **[Python Examples](./examples/python)** — Search, download, and publish skills via the REST API ## Governance and Safety @@ -111,7 +115,7 @@ with the Skill's source and the problem it solves, or submit a PR by following t ## Quick Start -Start the full local stack with: +To host your own registry using release images, start with: ```bash curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up @@ -172,7 +176,9 @@ skillhub list ### Prerequisites -- Docker & Docker Compose +- Docker & Docker Compose for container dependencies and release deployments +- For source development: Java 21, Node.js 22.13+ (22.x) or 24.x, and the pnpm version declared in `web/package.json` +- For CLI development: Bun (see [`cli/README.md`](cli/README.md)) ### Local Development @@ -180,7 +186,7 @@ skillhub list make dev-all ``` -> **For developers in China**: If Maven dependency download times out, configure Aliyun mirror. See [Local Development Guide](https://iflytek.github.io/skillhub/quickstart.html#本地开发) for details. +> **For developers in China**: If Maven dependency download times out, configure Aliyun mirror. See [Local Development Guide](docs/dev-workflow.md) for details. Then open: @@ -208,7 +214,7 @@ Stop everything with: make dev-all-down ``` -Reset local dependencies and start from a clean slate with: +Only when deliberately discarding local dependency data, reset with: ```bash make dev-all-reset @@ -366,23 +372,18 @@ allowlist instead of appending to it. ### Monitoring -A Prometheus + Grafana monitoring stack lives under [`monitoring/`](./monitoring). -It scrapes the backend's Actuator Prometheus endpoint. +The optional [`monitoring/`](./monitoring) directory provides Prometheus and Grafana deployment examples. It is not a ready-to-scrape backend configuration: the default application exposes only `health` and `info` Actuator endpoints. `/actuator/prometheus` also requires the `SUPER_ADMIN` or `AUDITOR` role under the current route policy, while the example scraper has no credentials configured. -Start it with: +Before enabling monitoring, configure metrics exposure and an authenticated access path appropriate to your deployment; verify that the scraper can actually read the endpoint. Do not make management endpoints public merely to satisfy the example. The example targets `host.docker.internal:8080`, which must resolve to your backend from the Prometheus container. + +After adapting that configuration, start the optional stack: ```bash cd monitoring docker compose -f docker-compose.monitoring.yml up -d ``` -Then open: - -- Prometheus: `http://localhost:9090` -- Grafana: `http://localhost:3001` (`admin` / `admin`) - -By default Prometheus scrapes `http://host.docker.internal:8080/actuator/prometheus`, -so start the backend locally on port `8080` first. +Prometheus uses port `9090` and Grafana uses port `3001`. Replace the example Grafana administrator credentials before exposing it. Confirm scrape targets are healthy and metrics are present; starting the containers alone does not establish monitoring coverage. For tracing and request correlation, see the [observability developer guide](docs/observability-developer-guide.md). ## Kubernetes diff --git a/cli/README.md b/cli/README.md index 6e5b053d1..66da5873a 100644 --- a/cli/README.md +++ b/cli/README.md @@ -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 ` command-line argument @@ -354,6 +354,19 @@ Workspace push is non-overwriting: an existing namespace/slug/version is reporte Namespace sync writes `.skillhub/namespace-sync.json` in the workspace and per-skill `.skillhub/metadata.json` files. These files contain the registry coordinate, published version, aggregate fingerprint, and file hashes used by `status` and `diff`. +## Using installed skills and Suites + +Installation downloads Skill files; it does not execute a task. Open the target project in your Agent, verify it discovers `SKILL.md`, configure the documented dependencies, and ask it to use the Skill. See the [Suite usage guide](../docs/skillhub/en/guide/skill-suites.md). + +```bash +# Replace with a real Suite coordinate +skillhub suite install @team/example-suite --scope project --agent codex +skillhub suite check @team/example-suite +skillhub suite upgrade @team/example-suite --check +skillhub suite upgrade @team/example-suite +skillhub suite remove @team/example-suite +``` + ## 📋 Local Management ### List Installed Skills @@ -420,7 +433,7 @@ skillhub doctor 3. Backs up old `inventory.json` (if exists) 4. Writes new `inventory.json` -If the same skill has version conflicts across different targets, that skill will be skipped and reported. +Versions are tracked per target. Doctor reports recovery problems; it does not download or upgrade skills. ## 🚢 Publishing @@ -494,6 +507,7 @@ Update mechanism: | `skillhub publish [--namespace ] [--visibility ] [--registry ] [--token ] [--json]` | Publish a skill | | `skillhub sync pull --namespace [--skill ]... [options]` | Pull explicitly selected skills from a non-global namespace | | `skillhub sync --namespace [options]` | Inspect or push a non-global namespace workspace | +| `skillhub suite [options]` | Manage a pinned Skill Suite installation | | `skillhub update [--check] [--json]` | Check or execute CLI self-update | ## 🔒 Security Notes @@ -528,7 +542,7 @@ request ID when asking a registry operator to investigate. ```bash # Check if registry is accessible -curl https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1 +curl 'https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1' # Use alternative registry skillhub search test --registry https://skillhub.example.com diff --git a/docs/09-deployment.md b/docs/09-deployment.md index dffea4ac7..9299b9bff 100644 --- a/docs/09-deployment.md +++ b/docs/09-deployment.md @@ -4,7 +4,7 @@ ## 1 运行模型 -当前仓库只保留两种运行方式: +按用途选择运行方式;以下重点介绍源码开发和单机交付,Kubernetes 另见[部署指南](skillhub/guide/kubernetes.md): - 开发环境:`make dev-all` - 前端和后端运行在宿主机 @@ -16,7 +16,7 @@ `linux/riscv64`,`scanner` 暂保持 `linux/amd64` 与 `linux/arm64` - PostgreSQL、Redis 与应用容器一起通过 Compose 启动 -不再维护本地构建整套 demo 容器的中间模式,也不再保留 `docker-compose.prod.yml`。 +`make staging` 仍用于从源码构建的容器回归验证,见[开发工作流](dev-workflow.md),不等同于正式交付。正式单机部署使用 `compose.release.yml`,不使用 `docker-compose.prod.yml`。 ## 2 单机交付拓扑 @@ -110,6 +110,7 @@ make dev-github-sync ```bash cp .env.release.example .env.release +# 编辑 .env.release:设置数据库/管理员密码、公开地址、存储和固定镜像版本 make validate-release-config docker compose --env-file .env.release -f compose.release.yml up -d ``` diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..e0c505c0f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,35 @@ +# Documentation map + +Use the documentation site for user workflows, repository guides for engineering and operations, and source/tests for exact current behavior. Numbered design documents are not a chronological tutorial or a promise that every proposed feature is implemented. + +## Users and authors + +| Task | 中文 | English | +| --- | --- | --- | +| Install and use your first skill | [快速开始](skillhub/quickstart.md) | [Quick Start](skillhub/en/quickstart.md) | +| CLI authentication, install, upgrade and sync | [CLI](skillhub/guide/cli.md) | [CLI](skillhub/en/guide/cli.md) | +| Install and use a versioned collection | [技能套装](skillhub/guide/skill-suites.md) | [Skill Suites](skillhub/en/guide/skill-suites.md) | +| Upload a collection and member packages | [Bundle 导入](skillhub/guide/suite-bundle.md) | [Bundle import](skillhub/en/guide/suite-bundle.md) | +| Publish skills and track versions | [发布](skillhub/guide/skill-publish.md) | [Publishing](skillhub/en/guide/skill-publish.md) | +| Manage access and review | [命名空间](skillhub/guide/namespace.md) · [审核](skillhub/guide/review.md) | [Namespaces](skillhub/en/guide/namespace.md) · [Review](skillhub/en/guide/review.md) | +| Troubleshoot | [FAQ](skillhub/faq.md) | [FAQ](skillhub/en/faq.md) | + +## Operators + +- [Docker deployment and upgrades](skillhub/en/guide/deployment.md) / [中文](skillhub/guide/deployment.md) +- [Kubernetes](skillhub/en/guide/kubernetes.md) / [中文](skillhub/guide/kubernetes.md) +- [Deployment reference](09-deployment.md), [object storage](object-storage.md), [SMTP and password reset](19-smtp-password-reset-email-setup.md) +- [Security scanning](security-scanning.md), [observability](observability-developer-guide.md), [private SSO integration](12-private-sso-integration-playbook.md) + +## Contributors and integrators + +- [Contributing](../CONTRIBUTING.md), [development workflow](dev-workflow.md), [engineering specs](../.trellis/spec/index.md) +- [System architecture](01-system-architecture.md), [domain model](02-domain-model.md), [API design](06-api-design.md) +- [Skill package protocol](07-skill-protocol.md), [lifecycle contract](14-skill-lifecycle.md), [Suite semantics](25-skill-suites.md), [authoring drafts](27-authoring-drafts.md) +- [Runtime integration](skillhub/en/guide/runtime-integration.md), [OpenClaw](openclaw-integration-en.md), [Hermes](hermes-integration-en.md), [DeepSeek Harness](dsh-integration-en.md) + +## Plans and historical evidence + +Roadmaps, files titled `plan`, dated design proposals, research under `research/`, and test reports record decisions or evidence at a point in time. Check their implementation status against current code before treating them as supported features. Examples include the [delivery roadmap](10-delivery-roadmap.md), [starter skills plan](21-official-starter-skills-plan.md), and [observability construction plan](2026-07-31-observability-construction-plan.md). + +For documentation changes, update both language journeys and navigation, verify commands against the source, then run `npm ci` and `npm run build` from `docs/skillhub`. A documentation build checks rendering and links, not deployment or live registry behavior. diff --git a/docs/dev-workflow.md b/docs/dev-workflow.md index de332c161..cc9f8fb05 100644 --- a/docs/dev-workflow.md +++ b/docs/dev-workflow.md @@ -6,7 +6,8 @@ This document describes the recommended workflow for developing SkillHub locally - Docker Desktop (for dependency services and staging) - Java 21 (for running the backend locally) -- Node.js 22 + pnpm (for running the frontend locally) +- Node.js 22.13+ (22.x) or 24.x, and the pnpm version declared in `web/package.json` (frontend) +- Bun for CLI development; see [`cli/README.md`](../cli/README.md) - `gh` CLI (for creating pull requests): https://cli.github.com/ ## Stage 1: Local Development (fast iteration) @@ -38,7 +39,7 @@ After editing backend code, restart the backend explicitly: make dev-server-restart ``` -If you are running the server in a foreground terminal instead of `make dev-all`, stop it and run `make dev-server` again. Expect a full restart in about 5-10 seconds, including rebuilding the backend modules. +If you are running the server in a foreground terminal instead of `make dev-all`, stop it and run `make dev-server` again. This rebuilds the backend modules before restart; duration depends on the machine and dependency cache. ### Mock authentication @@ -178,3 +179,16 @@ make staging # regression test in Docker make staging-down # stop staging make pr # push + create PR ``` + +## Documentation changes + +The bilingual user-facing site lives in `docs/skillhub`; architecture and operator references live directly under `docs`. Keep Chinese and English workflows aligned and update the VitePress navigation when adding pages. Verify commands against the current source, not only older guides. + +```bash +# Install site dependencies from the repository lockfile +npm --prefix docs/skillhub ci +make docs-build +make docs-preview +``` + +The site build checks internal links. Preview changed pages to check navigation, tables, and code blocks. Documentation-only changes do not require starting the application stack. diff --git a/docs/skillhub/.vitepress/config.ts b/docs/skillhub/.vitepress/config.ts index 26aa7f7de..59bbd3cd4 100644 --- a/docs/skillhub/.vitepress/config.ts +++ b/docs/skillhub/.vitepress/config.ts @@ -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,29 +33,54 @@ export default defineConfig({ items: [ { text: '项目简介', link: '/introduction' }, { text: '快速开始', link: '/quickstart' }, - ], - }, - { - text: '核心功能', - items: [ - { text: 'Skill 发布与版本管理', link: '/guide/skill-publish' }, - { text: '技能头像与图片审核接入', link: '/guide/skill-avatars' }, - { 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: '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: false, + items: [ + { text: '发布与更新技能', link: '/guide/skill-publish' }, + { text: 'Bundle 导入', link: '/guide/suite-bundle' }, + ], + }, + { + text: '团队与治理', + collapsed: false, + items: [ + { text: '管理命名空间', link: '/guide/namespace' }, + { text: '审核技能与套装', link: '/guide/review' }, + { text: '安全扫描与报告', link: '/guide/scanner' }, + ], + }, + { + text: '部署与运维', + collapsed: false, + items: [ + { text: 'Docker 部署', link: '/guide/deployment' }, + { text: 'Kubernetes 部署', link: '/guide/kubernetes' }, + { text: '技能头像与审核', link: '/guide/skill-avatars' }, + ], + }, + { + text: '开发与集成', + collapsed: false, + 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: '最后更新' }, @@ -72,38 +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: 'Core Features', - items: [ - { text: 'Skill Publishing & Versioning', link: '/en/guide/skill-publish' }, - { 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: '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: false, + items: [ + { text: 'Publish and update skills', link: '/en/guide/skill-publish' }, + { text: 'Import a bundle', link: '/en/guide/suite-bundle' }, + ], + }, + { + text: 'Team governance', + collapsed: false, + 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: false, + 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: false, + 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' }, diff --git a/docs/skillhub/en/faq.md b/docs/skillhub/en/faq.md index 51e3751fd..8f875755a 100644 --- a/docs/skillhub/en/faq.md +++ b/docs/skillhub/en/faq.md @@ -2,41 +2,15 @@ ## Q: What is the difference between SkillHub and ClawHub? -A: SkillHub is an enterprise-grade, self-hosted solution that provides stronger access control, review mechanisms, and governance capabilities. ClawHub is a public registry, similar to npm. - -**Key Differences**: - -| Feature | SkillHub | ClawHub | -|------|----------|---------| -| **Deployment** | Self-hosted | Public cloud | -| **Access Control** | Namespace RBAC | Basic permissions | -| **Review Mechanism** | Multi-level review | None | -| **Security Scanning** | Built-in Skill Scanner | None | -| **Data Sovereignty** | Fully self-managed | Hosted in the cloud | -| **Use Case** | Enterprise internal | Public sharing | +A: SkillHub provides a self-hosted registry, namespace permissions, publication review, scanning and audit. Third-party capabilities change; do not assume another service lacks review or scanning. See [OpenClaw integration](https://github.com/iflytek/skillhub/blob/main/docs/openclaw-integration-en.md) for compatibility. ## Q: How do I back up data? -A: SkillHub stores data in PostgreSQL and object storage. Regularly backing up these two components is sufficient. - -**Back up PostgreSQL**: -```bash -pg_dump -h localhost -U postgres skillhub > backup.sql -``` - -**Back up Object Storage**: -- If using MinIO, back up the MinIO data directory -- If using S3, use the AWS CLI or an S3 backup tool +A: Back up PostgreSQL, the configured skill storage, and deployment configuration. Release Compose defaults to local storage in the `skillhub_storage` volume; S3 deployments need the corresponding bucket/objects. Keep database and object snapshots consistent and verify restoration in an isolated environment. See [deployment](./guide/deployment.md). ## Q: What authentication methods are supported? -A: SkillHub supports multiple authentication methods: - -- **OAuth2**: GitHub, Google, GitLab, etc. -- **Local Accounts**: Username/password login (built-in administrator: admin / ChangeMe!2026) -- **Enterprise SSO**: Integrates with LDAP, SAML, etc. - -Refer to the authentication configuration section in the project README for setup instructions. +A: Local accounts and configured OAuth2 providers are supported. Preset registrations include GitHub, GitLab, Feishu, and DingTalk; the login page and `/api/v1/auth/methods` describe available methods on your instance. Extensibility does not mean LDAP/SAML are built in. See the [private SSO contract](https://github.com/iflytek/skillhub/blob/main/docs/11-auth-extensibility-and-private-sso.md). ## Q: Is there a size limit for skill packages? @@ -49,60 +23,31 @@ spring: multipart: max-file-size: 100MB max-request-size: 100MB +skillhub: + publish: + max-package-size: 104857600 ``` +Also check proxy body and Scanner upload limits; multipart settings alone do not bypass package validation. + ## Q: How do I use the CLI tool to manage skill packages? -A: SkillHub is compatible with the OpenClaw CLI. Use the `npx clawhub` command to interact with it: +A: Use the first-party CLI: ```bash -# Configure the registry URL -export CLAWHUB_REGISTRY=http://your-skillhub-host:8080 - -# Search for skill packages -npx clawhub search email - -# Install a skill package -npx clawhub install my-skill - -# Publish a skill package (the ClawHub CLI publishing protocol is not compatible) -export SKILLHUB_REGISTRY=http://your-skillhub-host:8080 -export SKILLHUB_TOKEN=YOUR_API_TOKEN -npx @astron-team/skillhub@latest publish ./my-skill +npm install -g @astron-team/skillhub +skillhub search pdf ``` +Follow [Quick Start](./quickstart.md) to select a registry, scope, and Agent. Publishing and restricted resources require login. See [OpenClaw integration](https://github.com/iflytek/skillhub/blob/main/docs/openclaw-integration-en.md) for compatibility boundaries; do not mix its publish protocol with SkillHub CLI. + ## Q: How do I configure HTTPS? -A: For production environments, it is recommended to use Nginx or Traefik as a reverse proxy with SSL certificates. - -**Nginx Configuration Example**: -```nginx -server { - listen 443 ssl; - server_name skillhub.example.com; - - ssl_certificate /path/to/cert.pem; - ssl_certificate_key /path/to/key.pem; - - location / { - proxy_pass http://localhost:3000; - } - - location /api { - proxy_pass http://localhost:8080; - } -} -``` +A: Terminate TLS at an external proxy forwarding to the published Web port (`WEB_PORT=80` by default in release Compose). Web already proxies backend routes. Set the real `SKILLHUB_PUBLIC_BASE_URL`, preserve the original Host and forwarded protocol, and validate login and cookies. See [deployment](./guide/deployment.md). ## Q: How do I monitor SkillHub? -A: SkillHub provides several monitoring options: - -- **Health Check**: `GET /actuator/health` -- **Scanner Health Check**: `GET http://localhost:8000/health` -- **Metrics**: `GET /actuator/metrics` (Prometheus format) -- **Audit Logs**: All critical operations are recorded in the audit log -- **Application Logs**: Collect logs using ELK or Loki +A: The base configuration exposes `/actuator/health` and `/actuator/info`. `/actuator/metrics` is not the Prometheus text endpoint; neither that endpoint nor Prometheus export is enabled by default in the base configuration. Correlate logs and audit events using `requestId`. See the [observability guide](https://github.com/iflytek/skillhub/blob/main/docs/observability-developer-guide.md) for explicit integration configuration. ## Q: Does it support multi-tenancy? @@ -112,47 +57,19 @@ For physical isolation, you can deploy a separate SkillHub instance for each ten ## Q: How do I upgrade SkillHub? -A: Use the curl command to upgrade: - -```bash -# Pull the latest images and restart -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- pull -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- down -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up - -# Or upgrade to a specific version -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version v0.2.0 -``` - -> **Note**: It is recommended to back up the database and object storage before upgrading. Database migrations are handled automatically by Flyway. Upgrading does not wipe the database, so already-registered skill packages will not be lost. +A: Follow the [deployment guide](./guide/deployment.md), select a target version, and back up the database, skill storage, and configuration. After upgrading, verify health, login, and representative skill operations. Flyway migrations mean that rolling back an image alone is not necessarily a database rollback. ## Q: Why can't administrators (admin) and regular users create namespaces? -A: Older versions of SkillHub do not support creating namespaces, as this feature was introduced in later updates. Please upgrade your SkillHub instance to the latest version (`latest`). -Upgrade command example: -```bash -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version latest -``` +A: Inspect the actual error and `requestId`, then check permissions, name validation, and instance restrictions. Do not assume an old version is the cause. See [namespace management](./guide/namespace.md). ## Q: How do I search for or operate on a skill package within a specific namespace? -A: When using the OpenClaw CLI, you can specify the namespace using the `--` format for operations like search or installation. If you encounter issues finding it on the web interface, you can also manage it by exporting the skill package and importing it into your target namespace. +A: Select the namespace in the UI. To install with the CLI, use `skillhub install @team/example-skill`, replacing the coordinate with a real resource. `skillhub search` searches skills; `skillhub suite install` installs suites. Exporting and reimporting is not a search troubleshooting step. ## Q: What is the recommended deployment method? Can I pull the images and deploy manually? -A: We recommend the official one-line deployment script. Pulling images and deploying manually is not recommended because it is prone to database initialization, dependency-order, and login redirect issues. By default, dependencies come from public registries, and the SkillHub application images come from GHCR: - -```bash -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --public-url https://skillhub.your-company.com -``` - -If GHCR is unreachable from China, use the Aliyun mirror: - -```bash -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --public-url https://skillhub.your-company.com --version latest -``` - -The script performs a series of initialization steps. The generated runtime configuration is located at `/tmp/skillhub-runtime/` by default (containing `.env.release` and the docker-compose file). +A: Official runtime scripts, release Compose, and Kubernetes/Helm are supported. Choose one and retain its configuration and data directories. See [Docker deployment](./guide/deployment.md) and [Kubernetes](./guide/kubernetes.md). Running an application image alone does not configure its database, Redis, storage, authentication, or proxy. ## Q: What Kubernetes version does the Kubernetes deployment require? @@ -160,39 +77,23 @@ A: The official [Kubernetes deployment guide](./guide/kubernetes.md) requires Ku ## Q: After deployment, I enter the correct username and password but get redirected back to the login page? -A: This is most commonly seen with **manual deployment** (caused by API errors or incomplete initialization). Suggestions: - -1. Switch to the one-line script above for deployment. -2. If necessary, clear and recreate the PostgreSQL data volume, then log in again. -3. If a reverse proxy is in front, verify that it forwards requests correctly. +A: Inspect the login and subsequent identity requests in browser developer tools. Check the public URL, proxy forwarding, cookies, and backend session configuration, then correlate `requestId` with server logs. This symptom alone does not identify a password or database failure. Do not clear PostgreSQL volumes as a login troubleshooting step. See [deployment](./guide/deployment.md). ## Q: How do I change the admin password? Why don't my config changes take effect? -A: Environment variables are injected when a container is created, so you must recreate the containers after changing them; `restart` alone does not re-inject environment variables. - -1. Edit `/tmp/skillhub-runtime/.env.release` in the runtime directory (refer to [.env.release.example](https://github.com/iflytek/skillhub/blob/main/.env.release.example)). -2. Recreate the relevant containers: - - ```bash - docker compose \ - --env-file /tmp/skillhub-runtime/.env.release \ - -f /tmp/skillhub-runtime/compose.release.yml \ - up -d --force-recreate - ``` - -3. If the password was already persisted to the database and the change still doesn't take effect, you may need to clear the corresponding data and re-initialize. +A: `BOOTSTRAP_ADMIN_PASSWORD` initializes an account. `BootstrapAdminInitializer` preserves existing credentials, so changing this variable or recreating containers does not reset an existing password. Use the instance password-change/reset flow and configure SMTP for email verification. Do not delete users or database contents to reinitialize credentials. ## Q: Is an email verification code required to change / reset a password? -A: Yes. By default, passwords are changed or reset via an email verification code, so SMTP must be configured first. See [docs/19-smtp-password-reset-email-setup.md](https://github.com/iflytek/skillhub/blob/main/docs/19-smtp-password-reset-email-setup.md). Administrators can also reset it via `.env.release`. +A: The 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? -A: Skill names are generally in English; Chinese names are not currently supported (using a Chinese skill name in OpenClaw will cause an error). +A: The `name`/slug remains a validated identifier. The user-facing display name supports Chinese through `metadata.display-name`. Changing it does not change the coordinate or installation directory. See [publishing](./guide/skill-publish.md). ## Q: Can unreviewed skills be downloaded? -A: As long as you have permission to view it, it can generally be downloaded. +A: Normal installation requires a published version that the caller can access. Visibility of a detail page does not grant downloads for every version state. Author/reviewer preview permissions differ from distribution permissions. See [review](./guide/review.md). ## Q: How do I hide or remove third-party SSO login options on the login page? @@ -270,7 +171,7 @@ Recreate the containers for the change to take effect; `restart` alone does not ## Q: Is there a server version requirement for using the CLI (publish / download, etc.)? -A: A SkillHub server image of **v0.2.7 or later** is required for CLI features. +A: Compatibility depends on the command. Basic CLI support does not imply support for Device Flow, Suites or sync. Check CLI version and target-server release notes. Suites require the server to advertise `skill-suite-v1`. See [CLI](./guide/cli.md). ## Q: Does SkillHub support MySQL? @@ -369,21 +270,7 @@ A `USER_ADMIN` can manage user status and assign platform roles other than `SUPE ## Q: How do I install multiple skills in bulk? -A: The CLI `install` command handles one skill at a time. Both examples below use `--dir` to install the skills under the same target root; each skill is placed in `$target_dir//`: - -```bash -target_dir=/opt/skillhub-skills - -# install one by one -for skill in skill-a skill-b skill-c; do - skillhub install "$skill" --dir "$target_dir" -done - -# or read from a manifest file (one skill name per line) -xargs -a skills.txt -I {} skillhub install "{}" --dir "$target_dir" -``` - -Since **SkillHub Server v0.2.12**, public skills support anonymous search and install. Note that an invalid bearer token now fails the command instead of falling back to anonymous access — update or remove the stale credential in that case. +A: Use [Suites](./guide/skill-suites.md) and `skillhub suite install` for pinned members managed together, `skillhub sync pull` for team workspaces, or separate `skillhub install` commands for unrelated skills. Suite Bundle is an authoring import format, not a local installation command. ## Q: What should I do if I encounter issues? @@ -452,7 +339,7 @@ java -version lsof -i :8080 # Terminate the process -kill -9 +# Identify the process owner and stop it through its service manager ``` ### 4. View detailed logs diff --git a/docs/skillhub/en/guide/account-access.md b/docs/skillhub/en/guide/account-access.md new file mode 100644 index 000000000..24f6cd211 --- /dev/null +++ b/docs/skillhub/en/guide/account-access.md @@ -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. diff --git a/docs/skillhub/en/guide/cli.md b/docs/skillhub/en/guide/cli.md index 2ccc47f21..ca70630b1 100644 --- a/docs/skillhub/en/guide/cli.md +++ b/docs/skillhub/en/guide/cli.md @@ -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 ` 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 @@ -19,7 +40,7 @@ bun add -g @astron-team/skillhub ```bash # Login -skillhub login --token sk_xxx +skillhub login # Search skills skillhub search pdf @@ -73,6 +94,8 @@ Token resolution priority: ### Login +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 skillhub login --token sk_xxx @@ -266,14 +289,38 @@ skillhub upgrade @team/code-review --check --json `--force`; it only replaces a managed installation whose full `registry + namespace + slug` source matches. -All targets in one inventory entry are upgraded together. A filter that selects only part of that -entry is rejected because the current inventory format stores one shared version for all targets. +Versions are tracked per target. `--agent` and `--dir` select installed targets; Suite-owned targets are protected from direct upgrade and should use `suite upgrade`. The command also keeps the local files when the registry resolves to an older version. If a multi-Skill run fails after an earlier upgrade commits, execution stops and reports each item as `upgraded`, `failed`, or `not-attempted`; a committed upgrade is never rolled back implicitly. New installations store absolute target paths. Reinstall an older entry that still contains relative target paths before upgrading it; the CLI cannot safely infer the original working directory. +## Using installed skills and Suites + +Installation downloads Skill files; it does not execute a task. Open the target project in your Agent, verify it discovers `SKILL.md`, configure the documented dependencies, and ask it to use the Skill. See the [Suite usage guide](./skill-suites). + +```bash +# Replace with a real Suite coordinate +skillhub suite install @team/example-suite --scope project --agent codex +skillhub suite check @team/example-suite +skillhub suite upgrade @team/example-suite --check +skillhub suite upgrade @team/example-suite +skillhub suite remove @team/example-suite +``` + +## Team workspace sync + +`sync` operates on non-global namespaces: pull selected skills, inspect status/diff, then push local content. The default workspace is `.agents/skills` in the current directory. Non-interactive pull requires explicit `--skill` selections; `--check` only inspects. + +```bash +skillhub sync pull --namespace team --check +skillhub sync pull --namespace team --skill example-skill +skillhub sync status --namespace team +skillhub sync diff --namespace team +skillhub sync push --namespace team --all --dry-run +``` + ## Local Management ### List Installed Skills @@ -340,7 +387,7 @@ skillhub doctor 3. Backs up old `inventory.json` (if exists) 4. Writes new `inventory.json` -If the same skill has version conflicts across different targets, that skill will be skipped and reported. +Versions are tracked per target. Doctor reports recovery problems; it does not download or upgrade skills. ## Publishing @@ -360,7 +407,7 @@ Visibility options: - `namespace-only` — Visible to namespace members only - `private` — Visible to yourself only -After successful publication, the skill detail page URL will be displayed. +After the server accepts the submission, the CLI shows its current status and detail URL. `SCANNING` and `PENDING_REVIEW` are asynchronous states, not final publication; check the detail page for completion. ## Self-Update @@ -417,26 +464,9 @@ Update mechanism: ### inventory.json -```json -{ - "items": [ - { - "registry": "https://skill.xfyun.cn", - "namespace": "global", - "slug": "pdf-parser", - "version": "1.0.0", - "targets": [ - { - "agent": "codex", - "rootDir": "/path/to/project/.codex/skills", - "installDir": "/path/to/project/.codex/skills/pdf-parser", - "installedAt": "2026-04-28T06:00:00.000Z" - } - ] - } - ] -} -``` +CLI-managed installation 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 @@ -484,6 +514,7 @@ Error response format: | 3 | Network error | | 4 | File system error | | 5 | Parameter error | +| 6 | Validation or installation ownership conflict | ## Command Reference @@ -508,10 +539,10 @@ Display CLI version. ### login ```bash -skillhub login --token [--registry ] [--json] +skillhub login [--no-open] [--token ] [--registry ] [--json] ``` -Save token and registry configuration. +Authenticate with Device Flow or a supplied API token, then save credentials and registry configuration. The CLI preserves unknown fields in the shared configuration and credentials documents when it updates its own `registry` and `tokens` fields. @@ -632,6 +663,22 @@ Options: - `--token ` — API token - `--json` — JSON output +### suite + +```bash +skillhub suite [options] +``` + +`install` supports `--version`, `--scope`, `--agent`, and `--dir`; `install` and `upgrade` support `--force`. `upgrade --check` previews changes. All actions support `--registry`, `--token`, and `--json`. See [Suites](./skill-suites). + +### sync + +```bash +skillhub sync --namespace [options] +``` + +Run `skillhub help sync` for selection, workspace and publishing options. Validate with `push --dry-run` before publishing. + ### update ```bash @@ -664,7 +711,7 @@ skillhub login --token sk_xxx ```bash # Check if registry is accessible -curl https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1 +curl 'https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1' # Use alternative registry skillhub search test --registry https://skillhub.example.com diff --git a/docs/skillhub/en/guide/deployment.md b/docs/skillhub/en/guide/deployment.md new file mode 100644 index 000000000..275b3b92c --- /dev/null +++ b/docs/skillhub/en/guide/deployment.md @@ -0,0 +1,74 @@ +# Docker Compose Deployment and Upgrades + +You do not need to deploy a server to install skills from an existing registry. Use this guide when hosting your own registry. `make dev-all` runs source development; `make staging` is for container regression testing; `compose.release.yml` is the single-server release deployment. For clusters, see [Kubernetes](kubernetes.md). + +## Configure the instance + +Install Docker and Docker Compose, and obtain repository files matching your target release. From the repository root: + +```bash +cp .env.release.example .env.release +``` + +Edit `.env.release` before starting: + +| Setting | Check | +| --- | --- | +| `SKILLHUB_VERSION` | Pin a published release; `latest` tracks stable releases and `edge` tracks main-branch builds | +| `SKILLHUB_PUBLIC_BASE_URL` | The address users actually visit; use HTTPS in production | +| `WEB_PORT` / `API_PORT` | Defaults are 80 / 8080; check availability | +| `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 | + +Do not commit or share `.env.release`. Changing an environment variable does not rotate the password of an existing database. Do not enable the `local` profile's mock authentication in a release deployment. + +## Start and verify + +```bash +make validate-release-config +docker compose --env-file .env.release -f compose.release.yml pull +docker compose --env-file .env.release -f compose.release.yml up -d +docker compose --env-file .env.release -f compose.release.yml ps +docker compose --env-file .env.release -f compose.release.yml logs --tail=100 server +``` + +Resolve validation errors before starting. Backend startup runs Flyway database migrations. Open your configured public URL, sign in with your configured administrator credentials, and verify search, download, and an authorized publishing/review flow. Healthy containers alone do not prove those workflows work. + +Suite review writes are enabled by default in the single-server release Compose topology; Suite Bundle confirmation is disabled by default. See [Bundle import](suite-bundle.md) for enabling it. For rolling upgrades where old and new backends coexist, follow the [Suite deployment order](https://github.com/iflytek/skillhub/blob/main/docs/25-skill-suites.md). + +## Upgrade, stop, and troubleshoot + +Before upgrading, record the current image version and configuration, and back up both the database and skill object storage. Set `SKILLHUB_VERSION` to the target release and repeat validation, `pull`, `up -d`, and workflow verification. Rolling back an image does not roll back the database; check migration compatibility first. + +```bash +# Stop this instance; do not add -v unless deliberately deleting data volumes +docker compose --env-file .env.release -f compose.release.yml down +``` + +For startup failures, inspect `ps` and service logs, then check database, Redis, storage, and public URL configuration. Include image versions, redacted logs, and request IDs when reporting a problem, never credentials or `.env.release`. See the [operations reference](https://github.com/iflytek/skillhub/blob/main/docs/09-deployment.md) for Redis, reverse proxies, collection services, and migrations. + +## 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. diff --git a/docs/skillhub/en/guide/index.md b/docs/skillhub/en/guide/index.md new file mode 100644 index 000000000..6b4dcdb35 --- /dev/null +++ b/docs/skillhub/en/guide/index.md @@ -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. diff --git a/docs/skillhub/en/guide/kubernetes.md b/docs/skillhub/en/guide/kubernetes.md index bcb2c1d48..e8a5638b4 100644 --- a/docs/skillhub/en/guide/kubernetes.md +++ b/docs/skillhub/en/guide/kubernetes.md @@ -1,4 +1,4 @@ -# Kubernetes Deployment Guide +# Kubernetes Deployment: Kustomize Configuration and Verification This document explains how to deploy SkillHub on a Kubernetes cluster. @@ -35,6 +35,8 @@ deploy/k8s/ ## Quick Start +All relative paths below use `deploy/k8s` in the repository as the working directory. Configure the Secret, then inspect `kubectl kustomize overlays/with-infra/` locally; rendered output may contain secrets. Applying manifests creates resources and backend startup runs database migrations. + ### 1. Create Namespace ```bash @@ -44,10 +46,10 @@ kubectl create namespace skillhub ### 2. Configure Secret ```bash -cd deploy/k8s/base +cd deploy/k8s # Copy example file -cp secret.yaml.example secret.yaml +cp base/secret.yaml.example base/secret.yaml # Edit secret.yaml with your configuration ``` @@ -66,6 +68,14 @@ cp secret.yaml.example 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)** @@ -270,7 +280,7 @@ kubectl create secret docker-registry ghcr-secret \ kubectl logs postgres-0 -n skillhub # Check Secret configuration -kubectl get secret skillhub-secret -n skillhub -o yaml +kubectl describe deployment skillhub-server -n skillhub ``` ### View Logs @@ -288,6 +298,8 @@ kubectl logs -l app.kubernetes.io/name=skillhub-scanner -n skillhub -f ## Cleanup +Run only after retiring the instance and backing up its database and skill storage. Namespace deletion removes its resources and PVCs; underlying data retention depends on the storage reclaim policy. + ```bash # Delete all resources kubectl delete -k overlays/with-infra/ # or overlays/external/ @@ -295,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. diff --git a/docs/skillhub/en/guide/namespace.md b/docs/skillhub/en/guide/namespace.md index b1e28e90f..a3c579e75 100644 --- a/docs/skillhub/en/guide/namespace.md +++ b/docs/skillhub/en/guide/namespace.md @@ -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 @@ -17,9 +34,9 @@ Namespaces are the core organizational unit in SkillHub. Each namespace represen | Role | Permissions | |------|-------------| -| **Owner** | Full control, including deleting the namespace and managing all members | +| **Owner** | Own the team namespace; manage members and transfer ownership subject to namespace state and server-side permissions | | **Admin** | Manage members, review skill packages, modify settings | -| **Member** | Publish skill packages, view private skill packages | +| **Member** | Publish skills and view namespace-only content | **Namespace States**: @@ -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**: @@ -116,7 +133,7 @@ POST /api/v1/namespaces Content-Type: application/json { - "name": "iFlytek AI Team", + "displayName": "iFlytek AI Team", "slug": "iflytek", "description": "iFlytek's AI agent skills" } @@ -125,9 +142,9 @@ Content-Type: application/json **Parameter Reference**: | Parameter | Type | Description | |-----------|------|-------------| -| name | string | Namespace name (required, 2-50 characters) | +| displayName | string | Namespace name (required, up to 128 characters) | | slug | string | URL identifier (required, unique, 2-64 characters, lowercase letters, numbers, hyphens only) | -| description | string | Description (optional, max 500 characters) | +| description | string | Description (optional, max 512 characters) | **Get Namespace Details**: ```bash @@ -140,7 +157,7 @@ PUT /api/v1/namespaces/{slug} Content-Type: application/json { - "name": "iFlytek AI Team (Updated)", + "displayName": "iFlytek AI Team (Updated)", "description": "Updated description" } ``` @@ -203,7 +220,7 @@ The history endpoint requires a browser session: `GET /api/v1/namespaces/{slug}/ > **Slug Uniqueness**: Namespace slugs must be globally unique and cannot be changed after creation. Use a short identifier for your team or project. - **Owner Requirement**: Each namespace must have at least one Owner; the last Owner cannot be removed -- **Role Inheritance**: Namespace members automatically have access to all skill packages in that namespace +- **Role Inheritance**: Membership grants access to NAMESPACE_ONLY content, not every PRIVATE skill; private access is reserved for its owner and authorized administrators - **Freeze Mechanism**: Administrators can freeze a namespace; no new skill packages can be published while frozen - **Archive Mechanism**: Archived namespaces are hidden from search results, but existing skill packages remain accessible - **Audit Logs**: All member changes and permission adjustments are recorded in the audit log diff --git a/docs/skillhub/en/guide/review.md b/docs/skillhub/en/guide/review.md index 66f0fad30..5a8ee4870 100644 --- a/docs/skillhub/en/guide/review.md +++ b/docs/skillhub/en/guide/review.md @@ -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 @@ -29,11 +43,15 @@ The review mechanism operates on two levels: **Governance Features**: -- **Review Workflow**: Multi-level review, batch review +- **Review Workflow**: Per-item review of versions, profile changes, and Suites - **Reporting System**: Users can report inappropriate skill packages - **Promotion Management**: Promote namespace skill packages to the global scope - **Audit Logs**: All governance actions are recorded +## Identify what is being reviewed + +Review-task status and skill-version status are different: a task can be PENDING while the uploaded version is still SCANNING. Wait for scanning and inspect findings before deciding. Approval of a skill version does not approve a Suite that references it. Suites have their own review, while Bundle import first completes member publishing and then creates a Suite draft. See [Skill Suites](/en/guide/skill-suites) and [Bundle import](/en/guide/suite-bundle). + ## Use Cases **Case 1: Namespace Administrator Review** @@ -50,15 +68,12 @@ A platform administrator reviews skill packages being promoted from a namespace A user reports an inappropriate skill package, and an administrator investigates and takes action. -**Case 4: Batch Review** - -An administrator batch-approves multiple skill packages that meet the standards. ## Step-by-Step Guide **Submitting for Review**: -1. When a skill package is published, the system automatically creates a review task +1. Ordinary PUBLIC / NAMESPACE_ONLY uploads create review tasks; PRIVATE uploads require confirmation or a separate review submission 2. The developer can check the review status under "My Submissions" 3. Wait for an administrator to review @@ -73,7 +88,9 @@ An administrator batch-approves multiple skill packages that meet the standards. - Download the full package for local testing - Review the compliance snapshot and the diff from the previous published version -![Flow Diagram](/diagrams/review-flow.png) +![Scan and review in the ordinary publication path](/diagrams/skill-publish-lifecycle-sketch.png) + +The review section follows the PUBLIC / NAMESPACE_ONLY branch: scanning completes before the version waits for a review decision. 4. Make a decision: - **Approve**: The skill package is officially published and the developer is notified @@ -136,7 +153,7 @@ POST /api/v1/reviews Content-Type: application/json { - "skillVersionId": "version-123" + "skillVersionId": 123 } ``` @@ -163,12 +180,12 @@ Content-Type: application/json **Parameter Reference**: | Parameter | Type | Description | |------|------|------| -| id | string | Review task ID (path parameter) | -| comment | string | Review comment (optional, max 1000 characters) | +| id | number | Review task ID (path parameter) | +| comment | string | Review comment (optional for approval; provide a clear reason for rejection) | **List Pending Reviews**: ```bash -GET /api/v1/reviews/pending?namespaceId=ns-123&page=0&size=20 +GET /api/v1/reviews/pending?namespaceId=123&page=0&size=20 ``` **List My Submissions**: @@ -209,11 +226,10 @@ Content-Type: application/json ## Notes -> **Review Permissions**: Only namespace Admins and Owners can review skill packages within their namespace. Platform administrators can review all skill packages. +> **Review Permissions**: Team namespace Admins and Owners review their space; SKILL_ADMIN and SUPER_ADMIN have platform review roles. Personal spaces and self-review have additional rules; a generic administrator label is not sufficient. - **Review Turnaround**: It is recommended to complete reviews within 24 hours to avoid blocking developers - **Review Records**: All review actions are recorded in the audit log - **Compliance Audit**: Compliance declarations are recorded as version snapshots. Approval or rejection should consider the diff summary, but Agent execution traces are not recorded by SkillHub -- **Batch Review**: Administrators can batch-approve multiple skill packages - **Review Comments**: When rejecting, it is recommended to provide detailed improvement suggestions - **Withdrawal Restrictions**: Only skill packages in the pending review state can be withdrawn diff --git a/docs/skillhub/en/guide/runtime-integration.md b/docs/skillhub/en/guide/runtime-integration.md index 530141b24..fc921af52 100644 --- a/docs/skillhub/en/guide/runtime-integration.md +++ b/docs/skillhub/en/guide/runtime-integration.md @@ -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 | @@ -37,7 +37,7 @@ The first phase does not expose a standalone compliance API. Runtime can read th GET /api/v1/skills/{namespace}/{slug}/versions/{version} ``` -Key response fields: +The example below shows fields inside the successful response’s `data`, not the full HTTP response. Check the outer business `code` before reading `data.id` and `data.complianceSnapshot`. Versions without declarations may have no snapshot; absence does not establish certification or an execution violation. ```json { @@ -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. diff --git a/docs/skillhub/en/guide/scanner.md b/docs/skillhub/en/guide/scanner.md index 5c11902dd..6f2caad51 100644 --- a/docs/skillhub/en/guide/scanner.md +++ b/docs/skillhub/en/guide/scanner.md @@ -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 | @@ -93,7 +110,7 @@ curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- u ## Notes -> **Scanning Does Not Block Publishing**: Security scanning runs asynchronously and does not block the skill package upload process. Scan results are updated on the skill package detail page once completed. +> **Asynchronous upload is not publication**: Ordinary public and namespace-only submissions require scanning to be enabled. An unfinished scan does not establish publication. SCAN_FAILED means execution failure; findings and execution failures require different handling. Completing a scan does not imply review approval. - **Scan Duration**: Depending on the skill package size and the number of enabled engines, scanning may take from a few seconds to several minutes - **LLM Analysis Cost**: Enabling LLM analysis incurs API call charges; it is recommended to evaluate costs in production environments diff --git a/docs/skillhub/en/guide/skill-avatars.md b/docs/skillhub/en/guide/skill-avatars.md new file mode 100644 index 000000000..d5eb45007 --- /dev/null +++ b/docs/skillhub/en/guide/skill-avatars.md @@ -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 | diff --git a/docs/skillhub/en/guide/skill-discovery.md b/docs/skillhub/en/guide/skill-discovery.md index 704a7cb5a..7f59ee1d2 100644 --- a/docs/skillhub/en/guide/skill-discovery.md +++ b/docs/skillhub/en/guide/skill-discovery.md @@ -1,143 +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, tag, downloads, rating, and more. +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 ![Concept Diagram](/diagrams/skill-discovery-concept.png) -**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, rating, update time -- **Permission-aware**: Only show skill packages user has access to -- **Real-time Updates**: Newly published skill packages appear immediately in search results - -**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. - ![Screenshot](/screenshots/skill-discovery-search.png) -**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 CLAWHUB_REGISTRY=http://localhost:8080 - -# Search skill packages -npx clawhub search pdf - -# Install skill package -npx clawhub install pdf-parser - -# Install skill package from specific namespace -npx clawhub 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) - ![Flow Diagram](/diagrams/skill-discovery-flow.png) - -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, rating, updated | -| page | number | Page number (starts from 0) | -| size | number | Page size (default 20, max 100) | - -**Response Example**: -```json -{ - "content": [ - { - "id": "skill-123", - "namespace": "iflytek", - "slug": "pdf-parser", - "name": "PDF Parser", - "description": "Extract text and metadata from PDF files", - "downloads": 1234, - "rating": 4.5, - "starCount": 56, - "latestVersion": "1.2.3", - "updatedAt": "2026-03-15T10:30:00Z", - "labels": ["data-processing", "pdf"] - } - ], - "totalElements": 42, - "totalPages": 3, - "number": 0, - "size": 20 -} -``` - -## Notes - -> **Permission Control**: Search results are automatically filtered by user permissions. PRIVATE skill packages are only visible to namespace members, INTERNAL skill packages are only visible to logged-in users. - -- **Search Performance**: SkillHub uses PostgreSQL full-text search with Chinese and English word segmentation -- **Real-time Updates**: Newly published skill packages appear immediately in search results -- **Tag Convention**: Recommend using consistent tag naming conventions for easier filtering -- **Search Suggestions**: Supports search suggestions and autocomplete (frontend implementation) diff --git a/docs/skillhub/en/guide/skill-publish.md b/docs/skillhub/en/guide/skill-publish.md index 70322b4a3..f2a17c674 100644 --- a/docs/skillhub/en/guide/skill-publish.md +++ b/docs/skillhub/en/guide/skill-publish.md @@ -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,13 +168,15 @@ file: skill-package.zip visibility: PUBLIC ``` -![Flow Diagram](/diagrams/skill-publish-flow.png) +![Ordinary public and private publication paths](/diagrams/skill-publish-lifecycle-sketch.png) + +The diagram covers ordinary uploads; scan failures, review rejection and privileged publishing are described below. 5. **Security Scan** After publishing, [Skill Scanner](/en/guide/scanner) automatically scans the skill package for potential security risks. Results appear on the skill package detail page. -6. **Wait for Review** (if namespace has review enabled) +6. **Wait for Review** (follow the returned status) Team admins receive review notifications and approve skill packages for official release. @@ -142,6 +184,16 @@ Team admins receive review notifications and approve skill packages for official Skill package can be discovered through search, others can download via CLI or Web UI. +## Submission is not publication + +After uploading, inspect the returned status and the version in My Skills. For ordinary PUBLIC and NAMESPACE_ONLY submissions, scanning must be enabled: the version passes through `SCANNING` and then `PENDING_REVIEW`. Approval publishes it. A PRIVATE upload remains `UPLOADED` after any configured scan; use its publish confirmation action to publish it. Privileged automatic publishing follows a separate path. + +`SCAN_FAILED` means the scan could not complete, not that the package was proven unsafe. A completed scan can still contain findings. A successful upload, HTTP response, or CLI exit is not evidence of `PUBLISHED`. During an update, public readers continue to see the published version while authorized maintainers can preview the pending version. + +### Authoring drafts + +The authoring API supports private drafts, file editing and structural validation. It does not yet provide a web workbench or automatic publication. Passing validation does not execute the skill or prove its security. Do not confuse an authoring draft with an uploaded skill version awaiting review. + ## Compliance Declarations Skill authors can add `x-astron-compliance` to the `SKILL.md` frontmatter to declare how a skill version maps to compliance standards, controls, or security knowledge-base entries. @@ -190,7 +242,7 @@ Content-Type: multipart/form-data # Parameters file: MultipartFile (required) -visibility: PUBLIC | PRIVATE | INTERNAL (optional, default PUBLIC) +visibility: PUBLIC | PRIVATE | NAMESPACE_ONLY (required) ``` **Parameter Reference**: @@ -198,7 +250,7 @@ visibility: PUBLIC | PRIVATE | INTERNAL (optional, default PUBLIC) |-----------|------|-------------| | namespace | string | Namespace slug (path parameter) | | file | MultipartFile | Skill package zip file | -| visibility | enum | Visibility level: PUBLIC, PRIVATE, INTERNAL | +| visibility | enum | Visibility level: PUBLIC, PRIVATE, NAMESPACE_ONLY | **Get Skill Details**: ```bash @@ -227,16 +279,16 @@ 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 -- **Review Process**: If namespace has review enabled, new versions need admin approval +- **Tag Management**: `latest` follows publication state and the published pointer, not client-side selection of the highest SemVer +- **Review Process**: Ordinary PUBLIC / NAMESPACE_ONLY uploads require scanning and review; PRIVATE uploads require publish confirmation - **File Size Limit**: Single skill package max 100MB (configurable) - **Naming Convention**: Skill slug supports lowercase letters, numbers, hyphens, and Unicode characters - **Version Immutability**: Published versions cannot be modified, only new versions can be published diff --git a/docs/skillhub/en/guide/skill-suites.md b/docs/skillhub/en/guide/skill-suites.md new file mode 100644 index 000000000..2848ad2d3 --- /dev/null +++ b/docs/skillhub/en/guide/skill-suites.md @@ -0,0 +1,97 @@ +# 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. + +## Choose the right resource + +| Resource | Purpose | How to use it | +| --- | --- | --- | +| Skill | One package containing `SKILL.md` | Install with `skillhub install`; use in an Agent | +| Skill Suite | A pinned collection with an Entry Skill | Install all members with `skillhub suite install` | +| Suite Bundle | An author's ZIP or folder containing a manifest and member packages | Import, preview, confirm and complete review in the Web UI | + +A [Bundle](./suite-bundle) is an authoring format. A Suite is not a workflow runtime: coordination depends on the entry and member instructions. A Skill can still be installed independently. + +![Suite installation and entry-skill usage](/diagrams/skill-suite-usage-sketch.png) + +Installation ends at separate member files. Agent usage starts with an explicit task. + +## Install a Suite + +Follow the related Suites on a Skill detail page to inspect the entry, pinned members and installability. A related-Suite badge denotes membership, not a mandatory dependency. Ordinary `skillhub search` searches Skills, and same-named Suites require the explicit `suite` command. + +Replace the example coordinate below with a real Suite. Log in to the appropriate registry for restricted resources. + +```bash +skillhub login +# Run from the target project root +skillhub suite install @team/example-suite --scope project --agent codex +# Or target Claude Code +skillhub suite install @team/example-suite --scope project --agent claude-code +# Pin a Suite version at user scope +skillhub suite install @team/example-suite --version 1.0.0 --scope user --agent codex +``` + +Use `--registry ` for a self-hosted registry. The server must advertise `skill-suite-v1`. If the CLI does not recognize the command, inspect `skillhub version` and `skillhub help suite`. + +Project-scoped Codex members are installed separately: + +```text +.codex/skills/ +├── entry-skill/SKILL.md +├── member-a/SKILL.md +└── member-b/SKILL.md +``` + +Claude Code uses `.claude/skills`; user scope uses the corresponding directory under the home directory. Directory names are member slugs. There is no generated combined Suite Skill. Installation downloads and verifies all members; unavailable members are not silently replaced by newer versions. + +## Use the installed skills + +1. Open the target project in the selected Agent and refresh its skills or start a new session as required by that product. +2. Check the installation paths and verify that the Agent discovers the Entry Skill's `SKILL.md`. +3. Follow the entry instructions to configure required tools, environment variables and services. Installing Skill files does not install these dependencies. +4. Ask the Agent: “Use the entry skill `` for the following task, following its instructions for the other members: …” + +The Suite coordinate identifies the installation; invoke the actual Entry Skill or an individual member. Trigger syntax and loading behavior belong to the Agent. SkillHub has no generic `suite run` command. + +## Check, upgrade and remove + +```bash +skillhub suite check @team/example-suite +skillhub suite upgrade @team/example-suite --check +skillhub suite upgrade @team/example-suite +skillhub suite remove @team/example-suite +``` + +`check` reports member state and remote version information. `upgrade --check` previews changes. A member release does not mutate an installed Suite: upgrades follow a new SuiteVersion's pinned plan. Manage Suite-owned targets through the Suite lifecycle. + +`--scope`, `--agent`, `--dir` and `--version` are install-only options; later operations use inventory. Removal retains direct installations, members shared with other Suites and locally modified members. Do not delete inventory to bypass a warning. + +## Create a Suite + +Use the Web editor to select published members and an entry, or import a [Suite Bundle](./suite-bundle) to upload local members. PUBLIC and NAMESPACE_ONLY Suites require Suite-level review; PRIVATE Suites can publish directly. Member Skills retain their own scan and review workflows. + +A version supports up to 100 distinct members and requires one member as entry. Nested Suites, version ranges and external-registry members are unsupported. The CLI manages installations; it does not provide `suite publish` or import authoring manifests. + +## 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 | diff --git a/docs/skillhub/en/guide/social.md b/docs/skillhub/en/guide/social.md index be6f10495..1ef02788d 100644 --- a/docs/skillhub/en/guide/social.md +++ b/docs/skillhub/en/guide/social.md @@ -1,4 +1,4 @@ -# User Interaction & Social Features +# Stars, ratings and notifications ## Overview @@ -11,7 +11,7 @@ SkillHub provides a rich set of social features that allow team members to inter - **Star**: Bookmark your favorite skill packages for easy access later - **Rating**: Rate skill packages (1-5 stars) to help others assess quality - **Download Statistics**: Track download counts to highlight popular skill packages -- **Notification System**: Receive timely notifications for review results, comment replies, and more +- **Notification System**: Receive timely notifications for review and governance events, and more **Social Metrics**: @@ -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. ![Screenshot](/screenshots/notifications.png) @@ -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**: @@ -103,13 +124,6 @@ DELETE /api/v1/skills/{skillId}/star GET /api/v1/skills/{skillId}/star ``` -**Response Example**: -```json -{ - "starred": true, - "starredAt": "2026-03-15T10:30:00Z" -} -``` **Rate a Skill Package**: ```bash @@ -124,7 +138,7 @@ Content-Type: application/json **Parameter Reference**: | Parameter | Type | Description | |------|------|------| -| skillId | string | Skill package ID (path parameter) | +| skillId | number | Skill package ID (path parameter) | | score | number | Rating (1-5, required) | **Get My Stars**: @@ -155,13 +169,8 @@ POST /api/v1/admin/skill-reviews/{reviewId}/hide POST /api/v1/admin/skill-reviews/{reviewId}/restore ``` -**Response Example**: -```json -{ - "score": 5, - "ratedAt": "2026-03-15T10:30:00Z" -} -``` + +Responses use the standard API envelope. `GET .../star` returns a boolean in `data`; `GET .../rating` returns `score` and `rated`. Mutations return an empty `data`, not a rating timestamp. IDs are numeric. ## Notes @@ -170,6 +179,6 @@ POST /api/v1/admin/skill-reviews/{reviewId}/restore > **Review Rules**: Only published skills can be reviewed, and the public list contains visible reviews only. Refresh and retry after a concurrent-update conflict. - **Star Count**: A skill package's star count is displayed in search results and on the detail page -- **Average Rating**: A skill package's average rating affects search ranking +- **Average Rating**: Average ratings help compare skills; the search page has no dedicated rating sort - **Notification Settings**: Users can disable certain notification types in their settings -- **Download Statistics**: Each download increments the download counter, which is used for popularity ranking +- **Download Statistics**: Published-version downloads record counts; review-preview downloads do not count as public downloads diff --git a/docs/skillhub/en/guide/suite-bundle.md b/docs/skillhub/en/guide/suite-bundle.md index feab2005c..0c974fefb 100644 --- a/docs/skillhub/en/guide/suite-bundle.md +++ b/docs/skillhub/en/guide/suite-bundle.md @@ -1,7 +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. @@ -17,7 +39,7 @@ spec: version: 1.0.0 displayName: Clinical workflow summary: Validate intake data and produce a summary - overview: The entry Skill validates and dispatches input; the summary Skill produces the result. + overview: The entry Skill validates intake data using the shared dictionary. visibility: PUBLIC entry: "@global/intake" members: diff --git a/docs/skillhub/en/index.md b/docs/skillhub/en/index.md index 504cde7ea..53f36247d 100644 --- a/docs/skillhub/en/index.md +++ b/docs/skillhub/en/index.md @@ -11,10 +11,10 @@ hero: actions: - theme: brand text: Quick Start - link: /quickstart + link: /en/quickstart - theme: alt - text: Feature Guide - link: /guide/skill-publish + text: Browse Guides + link: /en/guide/ - theme: alt text: GitHub link: https://github.com/iflytek/skillhub @@ -23,27 +23,27 @@ features: - icon: 🚀 title: Skill Publishing & Version Management details: Publish skill packages with one click, semantic versioning, tag system, and multi-version coexistence - link: /guide/skill-publish + link: /en/guide/skill-publish - icon: 🔍 title: Skill Search & Discovery details: Full-text search, smart filtering, permission-aware — quickly find the skill packages you need - link: /guide/skill-discovery + link: /en/guide/skill-discovery - icon: 👥 title: Namespace & Team Management details: Namespace-based RBAC permission system with Owner/Admin/Member three-tier roles - link: /guide/namespace + link: /en/guide/namespace - icon: ✅ title: Review & Governance - details: Multi-level review workflows and reporting system to ensure skill package quality - link: /guide/review + details: Skill and suite review workflows and reporting system to ensure skill package quality + link: /en/guide/review - icon: ⭐ title: User Interaction & Social details: Starring, ratings, notification system — build an active skill package community - link: /guide/social + link: /en/guide/social - icon: 🛡️ title: Security Scanning details: Built-in Skill Scanner with multi-engine security analysis, automatic detection of malicious code and security risks - link: /guide/scanner + link: /en/guide/scanner - icon: 🏢 title: Enterprise Self-Hosting details: Fully self-hosted with complete data sovereignty, supports Docker Compose and K8s deployment diff --git a/docs/skillhub/en/introduction.md b/docs/skillhub/en/introduction.md index 9cbda27b2..7a238ad39 100644 --- a/docs/skillhub/en/introduction.md +++ b/docs/skillhub/en/introduction.md @@ -10,25 +10,27 @@ SkillHub solves this problem. It provides a **private, controllable, and easy-to ## Core Value -- **Publish in 3 minutes**: From local development to global distribution with a single command +- **Managed distribution**: Upload packages and follow scanning, review, and publication - **Enterprise-grade permissions**: Namespace-based RBAC with team collaboration and review workflows - **Full lifecycle**: Version management, tag system, review workflows, and archiving mechanisms -- **Ready out of the box**: Start the full environment with a single curl command +- **Deployment choices**: Docker Compose and Kubernetes with explicit dependency and authentication configuration - **Security scanning**: Built-in Skill Scanner for automatic security risk detection - **Data sovereignty**: Fully self-hosted — all data stays within your firewall ## Tech Stack -![Tech Stack Diagram](/diagrams/tech-stack.png) +![Frontend, backend, data and storage components](/diagrams/tech-stack-sketch.png) + +Storage can use local files or an S3-compatible provider; select it explicitly for your deployment. | Layer | Technology | Description | |-------|------------|-------------| -| **Frontend** | React 19 + Vite + TanStack Router | Modern SPA with Chinese/English language support | -| **Backend** | Java 21 + Spring Boot 3.2 | Enterprise-grade REST API | -| **Database** | PostgreSQL 16 | Full-text search, Flyway auto-migration | -| **Cache** | Redis 7 | Session management, hot data caching | -| **Storage** | MinIO / S3 | Skill package file storage, supports local and cloud | -| **Deployment** | Docker Compose / K8s | One-click startup, supports self-hosting | +| **Frontend** | React + Vite + TanStack Router | Modern SPA with multiple interface languages | +| **Backend** | Java 21 + Spring Boot | Enterprise-grade REST API | +| **Database** | PostgreSQL | Full-text search, Flyway auto-migration | +| **Cache** | Redis | Session management, hot data caching | +| **Storage** | Local files / S3-compatible storage | Skill package file storage, supports local and cloud | +| **Deployment** | Docker Compose / K8s | Configured self-hosting | ## Feature Overview @@ -37,6 +39,23 @@ SkillHub solves this problem. It provides a **private, controllable, and easy-to | [Skill Publishing & Version Management](/en/guide/skill-publish) | One-click skill package publishing with semantic versioning | | [Skill Search & Discovery](/en/guide/skill-discovery) | Full-text search, smart filtering, permission-aware | | [Namespace & Team Management](/en/guide/namespace) | Namespace-based RBAC permission system | -| [Review & Governance](/en/guide/review) | Multi-level review workflows, reporting system | +| [Review & Governance](/en/guide/review) | Skill and suite review workflows, reporting system | | [Security Scanning](/en/guide/scanner) | Built-in Skill Scanner with multi-engine security analysis | | [User Interaction & Social](/en/guide/social) | Starring, ratings, notification system | + +## Three different objects + +| Object | Purpose | Next step | +| --- | --- | --- | +| Skill | An individual package with `SKILL.md`, discovered and used by an Agent after installation | [Quick Start](./quickstart.md) | +| Skill Suite | A collection of pinned skill versions with one member designated as its entry skill | [Install and use suites](./guide/skill-suites.md) | +| Suite Bundle | An authoring format for importing a suite definition and member packages | [Bundle import](./guide/suite-bundle.md) | + +The registry distributes and governs skills; execution happens in the user's Agent environment. Installing a suite does not automatically run all its members. + +## Read by role + +- Consumers: [CLI](./guide/cli.md), [discovery](./guide/skill-discovery.md), [FAQ](./faq.md). +- Authors: [publishing](./guide/skill-publish.md), [suites](./guide/skill-suites.md), [review](./guide/review.md). +- Operators: [namespaces](./guide/namespace.md), [deployment and upgrades](./guide/deployment.md), [Kubernetes](./guide/kubernetes.md). +- Integrators: [Runtime contract](./guide/runtime-integration.md), [repository documentation index](https://github.com/iflytek/skillhub/blob/main/docs/README.md). diff --git a/docs/skillhub/en/quickstart.md b/docs/skillhub/en/quickstart.md index b6a4962dd..72cd211dc 100644 --- a/docs/skillhub/en/quickstart.md +++ b/docs/skillhub/en/quickstart.md @@ -1,234 +1,98 @@ -# Quick Start +# Quick Start: Install and Use a Skill -## One-Click Deployment +Install your first skill and use it in your Agent. This guide uses an existing registry; no SkillHub server deployment is needed. -Use the curl command to quickly deploy SkillHub (includes all services: Web UI, Backend API, PostgreSQL, Redis, MinIO, Skill Scanner): +## 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 ```bash -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up -``` - -**For users in China (Alibaba Cloud mirror)**: -```bash -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun -``` - -**Custom parameters**: -```bash -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up \ - --version v0.2.0 \ - --home /opt/skillhub \ - --aliyun -``` - -**Parameter reference**: -| Parameter | Description | Example | -|-----------|-------------|---------| -| `--version ` | Specify version | `--version v0.2.0` | -| `--aliyun` | Use Alibaba Cloud mirror (recommended for China) | `--aliyun` | -| `--home ` | Specify installation directory | `--home /opt/skillhub` | -| `--no-scanner` | Disable security scanning service | `--no-scanner` | -| `--mirror-registry ` | Custom image registry | `--mirror-registry registry.example.com` | - -**Other commands**: -```bash -# Stop services -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- down - -# Check service status -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- ps - -# View logs -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- logs - -# Clean all data -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- clean -``` - -After successful deployment, visit: -- **Web UI**: http://localhost:3000 -- **Backend API**: http://localhost:8080 -- **API Docs**: http://localhost:8080/swagger-ui.html -- **Skill Scanner**: http://localhost:8000 - -## Local Development - -To start the development environment from source: - -```bash -# Clone the repository -git clone https://github.com/iflytek/skillhub.git -cd skillhub - -# Start all services (including Scanner) -make dev-all -``` - -### Notes for Developers in China - -If `make dev-all` fails to start the backend, common causes include: - -1. **Maven dependency download timeout** - - The project includes a built-in Aliyun mirror configuration (`server/.mvn/settings.xml`), but Maven does not automatically read project-level settings. You need to configure it manually: - - ```bash - # Option 1: Copy to user directory (recommended) - mkdir -p ~/.m2 - cp server/.mvn/settings.xml ~/.m2/settings.xml - - # Option 2: Specify on each build - cd server && ./mvnw -s .mvn/settings.xml package - ``` - -2. **Java version mismatch** - - SkillHub requires Java 21+: - ```bash - java -version - ``` - -3. **Port conflict** - - Check if port 8080 is in use: - ```bash - lsof -i :8080 - ``` - -For detailed troubleshooting steps, see [FAQ](faq.md#local-development-startup-failure). - -## Logging In - -### Option 1: Use the Built-in Admin Account - -SkillHub comes with a built-in super admin account for direct login: - -- **Username**: `admin` -- **Password**: `ChangeMe!2026` - -> **Security notice**: Change the default password immediately after deploying to production. - -### Option 2: Register a New Account - -Visit http://localhost:3000/register to create a new account. - -### Option 3: Use Mock Users (Local Development Only) - -During local development, you can use mock user headers for quick login: - -```bash -# Regular user -curl -H "X-Mock-User-Id: local-user" http://localhost:8080/api/v1/auth/me - -# Super admin -curl -H "X-Mock-User-Id: local-admin" http://localhost:8080/api/v1/auth/me -``` - -In the browser, you can add the `X-Mock-User-Id` header via a browser extension (e.g., ModHeader). - -## Install the CLI Tool - -Use the first-party SkillHub CLI for skill package management: - -```bash -# Install the CLI and configure the SkillHub registry URL npm install -g @astron-team/skillhub -export SKILLHUB_REGISTRY=http://localhost:8080 - -# Search for skill packages -skillhub search email - -# Install a skill package -skillhub install my-skill - -# Publish a skill package -skillhub publish ./my-skill --namespace my-team +skillhub version ``` -Existing ClawHub workflows can still use the compatibility layer for search and install. Prefer the SkillHub CLI for new workflows and publishing. - -## Publish Your First Skill Package - -### Publish via CLI (Recommended) - -1. **Prepare the skill package** - -Create a simple skill package directory: - -``` -my-skill/ -├── skill.md # Skill description -├── package.json # Metadata -└── scripts/ # Script files - └── main.py -``` - -2. **Publish using the CLI** +The default registry is `https://skill.xfyun.cn`. For a self-hosted instance, set its actual URL in your terminal: ```bash -# Configure the registry -export SKILLHUB_REGISTRY=http://localhost:8080 - -# Publish to a specific namespace -skillhub publish ./my-skill --namespace my-team +export SKILLHUB_REGISTRY=https://skillhub.example.com ``` -3. **Wait for security scanning** +For PowerShell, set the registry with: -After publishing, the Skill Scanner will automatically scan the skill package for potential security issues: -- Malicious code detection -- Sensitive information leakage -- Dependency vulnerability scanning -- Behavioral analysis +```powershell +$env:SKILLHUB_REGISTRY="https://skillhub.example.com" +``` -Scan results are displayed on the skill package detail page. +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. -4. **Wait for review** (if the namespace has review enabled) - -Administrators will receive a notification and the skill package will be officially published once approved. - -### Publish via Web UI - -1. Visit http://localhost:3000/dashboard/publish -2. Select a namespace (create one first if needed) -3. Upload a zip file -4. Choose visibility (PUBLIC / PRIVATE / INTERNAL) -5. Click "Publish" - -## Search and Download Skill Packages - -### Using the CLI +Public skills support anonymous search and installation. Publishing and restricted resources require authentication: + +```bash +skillhub login +skillhub whoami +``` + +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 ```bash -# Search for skill packages skillhub search pdf - -# Install a skill package -skillhub install pdf-parser - -# Install a skill package from a specific namespace -skillhub install pdf-parser --namespace my-team ``` -### Using the Web UI +Review the skill's purpose, version, visibility, and instructions on its detail page. Replace the placeholder `@team/example-skill` below with a real search result. -1. Visit http://localhost:3000/search -2. Enter keywords to search -3. Click a skill package to view details -4. Click "Download" or copy the install command - -## Upgrade SkillHub - -Use the curl command to upgrade to the latest version: +From the target project root: ```bash -# Upgrade to the latest version -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- pull -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- down -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up - -# Upgrade to a specific version -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version v0.2.0 +skillhub install @team/example-skill --scope project --agent codex +skillhub list --agent codex ``` -> **Note**: It is recommended to back up the database and object storage before upgrading. +For Claude Code, use `--agent claude-code`. Use `--scope user` to share an installation across projects. +Codex project installations use `.codex/skills//`; Claude Code uses `.claude/skills//`. 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: + +> Use example-skill and follow its instructions to process the following material: … + +Use the name in `SKILL.md` and the Agent's discovery results. Installation does not execute a skill or configure its required tools and credentials. +If discovery fails, check the CLI's destination, current project, scope, and target Agent; see the [FAQ](./faq.md). + +For a collection, use `skillhub suite install`, then start with its entry skill. See [Skill Suites](./guide/skill-suites.md). + +## 4. Update and manage installations + +```bash +skillhub upgrade @team/example-skill --check +skillhub upgrade @team/example-skill +``` + +Review the plan before updating and preserve local changes you need. Do not use `--force` by default. See the [CLI guide](./guide/cli.md) for removal, team workspace synchronization, and command details. + +## Troubleshoot the first installation + +| Symptom | Check first | Next step | +| --- | --- | --- | +| Skill not found | Registry, spelling, login identity, and visibility | Confirm a published coordinate/version in the UI; see [discovery](./guide/skill-discovery.md) | +| Directory conflict | Whether the destination belongs to another source or contains your own files | Preserve needed files; do not force an unknown directory; see [CLI reference](./guide/cli.md) | +| Installed but not discovered | Agent profile, project root, and user/project scope | Check the printed path, then reload or start a session according to the Agent's discovery behavior | +| Discovered but execution fails | Required tools, inputs, and credentials | Follow `SKILL.md`; the registry does not configure or execute those requirements | + +## Next steps + +Install a [Skill Suite](./guide/skill-suites.md) when you need a coordinated collection, or use the [CLI reference](./guide/cli.md) for more commands. For publishing, team administration, hosting, or development, choose your next task in the [documentation map](./guide/index.md). diff --git a/docs/skillhub/faq.md b/docs/skillhub/faq.md index 19e88b13f..beab73783 100644 --- a/docs/skillhub/faq.md +++ b/docs/skillhub/faq.md @@ -2,41 +2,15 @@ ## Q: SkillHub 和 ClawHub 有什么区别? -A: SkillHub 是企业级的自托管方案,提供了更强的权限控制、审核机制和治理能力。ClawHub 是公共注册中心,类似 npm。 - -**主要区别**: - -| 特性 | SkillHub | ClawHub | -|------|----------|---------| -| **部署方式** | 自托管 | 公共云 | -| **权限控制** | 命名空间 RBAC | 基础权限 | -| **审核机制** | 多级审核 | 无 | -| **安全扫描** | 内置 Skill Scanner | 无 | -| **数据主权** | 完全自主 | 托管在云端 | -| **适用场景** | 企业内部 | 公开分享 | +A: SkillHub 提供自托管注册中心、命名空间权限、发布审核、安全扫描和审计。第三方服务的能力会变化,不应将“无审核/无扫描”作为固定比较结论。兼容范围见 [OpenClaw 集成](https://github.com/iflytek/skillhub/blob/main/docs/openclaw-integration.md)。 ## Q: 如何备份数据? -A: SkillHub 的数据存储在 PostgreSQL 和对象存储中。定期备份这两部分即可。 - -**备份 PostgreSQL**: -```bash -pg_dump -h localhost -U postgres skillhub > backup.sql -``` - -**备份对象存储**: -- 如果使用 MinIO,备份 MinIO 数据目录 -- 如果使用 S3,使用 AWS CLI 或 S3 备份工具 +A: 备份 PostgreSQL、实际使用的存储后端及部署配置。默认 release Compose 使用本地文件存储,需要备份 `skillhub_storage` 数据卷;使用 S3 时备份对应 bucket/对象。数据库和技能文件需要来自一致的备份窗口。操作步骤见 [部署指南](./guide/deployment.md),恢复能力应通过独立环境演练验证。 ## Q: 支持哪些认证方式? -A: SkillHub 支持多种认证方式: - -- **OAuth2**:GitHub、Google、GitLab 等 -- **本地账号**:用户名密码登录(内置管理员:admin / ChangeMe!2026) -- **企业 SSO**:可以集成 LDAP、SAML 等 - -配置方式参考项目 README 中的认证配置章节。 +A: 支持本地账号及已配置的 OAuth2 登录入口。当前预置注册包括 GitHub、GitLab、飞书和钉钉;实际入口以登录页和 `/api/v1/auth/methods` 为准。企业 SSO 需要按接入契约配置,不能把可扩展性当成已经内置 LDAP/SAML。参见 [认证与私有 SSO](https://github.com/iflytek/skillhub/blob/main/docs/11-auth-extensibility-and-private-sso.md)。 ## Q: 技能包大小有限制吗? @@ -49,60 +23,31 @@ spring: multipart: max-file-size: 100MB max-request-size: 100MB +skillhub: + publish: + max-package-size: 104857600 ``` +还需核对代理请求体和 Scanner 上传限制;只调 multipart 不会绕过包校验。 + ## Q: 如何使用 CLI 工具管理技能包? -A: SkillHub 兼容 OpenClaw CLI,使用 `npx clawhub` 命令即可操作: +A: 优先使用第一方 CLI: ```bash -# 配置注册中心地址 -export CLAWHUB_REGISTRY=http://your-skillhub-host:8080 - -# 搜索技能包 -npx clawhub search email - -# 安装技能包 -npx clawhub install my-skill - -# 发布技能包(ClawHub CLI 的发布协议不兼容 SkillHub) -export SKILLHUB_REGISTRY=http://your-skillhub-host:8080 -export SKILLHUB_TOKEN=YOUR_API_TOKEN -npx @astron-team/skillhub@latest publish ./my-skill +npm install -g @astron-team/skillhub +skillhub search pdf ``` +按 [快速开始](./quickstart.md) 选择注册中心、安装位置和 Agent。发布和受限资源访问需要登录。ClawHub 兼容接口的范围见 [集成说明](https://github.com/iflytek/skillhub/blob/main/docs/openclaw-integration.md),不要将其发布协议与 SkillHub CLI 混用。 + ## Q: 如何配置 HTTPS? -A: 生产环境建议使用 Nginx 或 Traefik 作为反向代理,配置 SSL 证书。 - -**Nginx 配置示例**: -```nginx -server { - listen 443 ssl; - server_name skillhub.example.com; - - ssl_certificate /path/to/cert.pem; - ssl_certificate_key /path/to/key.pem; - - location / { - proxy_pass http://localhost:3000; - } - - location /api { - proxy_pass http://localhost:8080; - } -} -``` +A: 在外部代理终止 TLS,并转发到实际映射的 Web 端口(release Compose 默认 `WEB_PORT=80`),Web 已代理后端路由。设置真实 `SKILLHUB_PUBLIC_BASE_URL`,正确传递原始 Host 和代理协议头,并验证登录与 Cookie。见 [部署指南](./guide/deployment.md)。 ## Q: 如何监控 SkillHub? -A: SkillHub 提供了多种监控方式: - -- **健康检查**:`GET /actuator/health` -- **Scanner 健康检查**:`GET http://localhost:8000/health` -- **指标监控**:`GET /actuator/metrics`(Prometheus 格式) -- **审计日志**:所有关键操作都会记录到审计日志 -- **应用日志**:使用 ELK 或 Loki 收集日志 +A: 默认配置暴露 `/actuator/health` 和 `/actuator/info`。`/actuator/metrics` 不是 Prometheus 文本接口,当前基础配置也未默认暴露它或启用 Prometheus 导出。结合服务日志、审计记录和请求的 `requestId` 排查;监控接入需要单独核对部署配置,见 [可观测性指南](https://github.com/iflytek/skillhub/blob/main/docs/observability-developer-guide.md)。 ## Q: 支持多租户吗? @@ -112,47 +57,19 @@ A: SkillHub 通过命名空间实现了逻辑上的多租户隔离。每个命 ## Q: 如何升级 SkillHub? -A: 使用 curl 命令升级: - -```bash -# 拉取最新镜像并重启 -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- pull -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- down -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up - -# 或直接指定版本升级 -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version v0.2.0 -``` - -> **注意**:升级前建议先备份数据库和对象存储。数据库迁移由 Flyway 自动执行。升级不会清空数据库,已录入的技能包不会丢失。 +A: 按 [部署与升级指南](./guide/deployment.md) 选择目标版本,先备份数据库、技能存储和配置,再升级并验证健康、登录及代表性技能操作。Flyway 会执行数据库迁移;不能仅凭容器启动成功认定升级成功,也不能假设降级镜像即可回滚数据库。 ## Q: 为什么管理员(admin)和普通用户都无法创建命名空间? -A: 较旧版本的 SkillHub 不支持创建命名空间。该功能是在后续版本迭代中添加的。请将您的 SkillHub 升级到最新版本(latest)。 -升级命令示例: -```bash -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version latest -``` +A: 先查看页面或接口的错误信息和 `requestId`,核对当前账号权限、名称校验及实例限制。不要直接推断为版本太旧;管理员身份也不能绕过全部业务规则。参见 [命名空间管理](./guide/namespace.md)。 ## Q: 如何搜索或操作指定命名空间中的技能包(Skill)? -A: 使用 OpenClaw CLI 命令行工具时,可以通过 `--` 的格式来指定命名空间进行操作(例如搜索、安装)。如果在网页端搜索遇到问题,也可以尝试通过先导出技能、再导入到目标命名空间的方式来完成跨空间操作。 +A: 在网页中选择命名空间;CLI 安装可使用 `skillhub install @team/example-skill`,其中坐标应替换成真实资源。`skillhub search` 搜索技能,`skillhub suite install` 安装套装。命名空间迁移与搜索不是同一操作,不需要通过导出再导入来解决搜索问题。 ## Q: 推荐的部署方式是什么?可以自己拉镜像手动部署吗? -A: 推荐使用官方一键部署脚本,不建议自己拉取镜像手动部署(手动部署容易出现数据库初始化、依赖顺序或登录后跳回登录页等问题)。默认从公共镜像仓库拉取依赖,其中 SkillHub 应用镜像来自 GHCR: - -```bash -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --public-url https://skillhub.your-company.com -``` - -国内网络无法访问 GHCR 时,使用阿里云镜像: - -```bash -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun --public-url https://skillhub.your-company.com --version latest -``` - -脚本会执行一系列初始化操作,生成的运行时配置默认位于 `/tmp/skillhub-runtime/`(包含 `.env.release` 和 docker-compose 文件)。 +A: 支持官方 runtime 脚本、release Compose 和 Kubernetes/Helm。选择一种方式并保留对应的配置与数据目录,参见 [Docker 部署](./guide/deployment.md) 和 [Kubernetes 部署](./guide/kubernetes.md)。手动部署需要正确配置数据库、Redis、存储、认证和代理,不能只启动应用镜像。 ## Q: 用 Kubernetes 部署对集群版本有要求吗? @@ -160,39 +77,23 @@ A: 官方 [Kubernetes 部署指南](./guide/kubernetes.md) 要求 Kubernetes **v ## Q: 部署后输入正确的账号密码,却又跳回登录页? -A: 该现象多见于「手动部署」场景(接口异常或初始化未完成导致)。建议: - -1. 改用上面的一键脚本部署。 -2. 必要时清空 PostgreSQL 数据卷后重建再登录。 -3. 若前置了反向代理,检查代理配置是否正确转发。 +A: 先在浏览器网络面板检查登录请求及后续身份请求的状态,核对实例公网 URL、代理转发、Cookie 和后端会话配置,并关联服务端 `requestId` 与日志。此现象本身不能确定是密码错误或数据库问题。不要清空 PostgreSQL 数据卷来尝试修复登录。部署参数见 [部署指南](./guide/deployment.md)。 ## Q: 如何修改 admin 密码?修改配置后不生效? -A: 环境变量在容器创建时注入,修改后必须重新创建容器才会生效;仅执行 `restart` 不会重新注入环境变量。 - -1. 修改运行时目录下的 `/tmp/skillhub-runtime/.env.release`(参考仓库 [.env.release.example](https://github.com/iflytek/skillhub/blob/main/.env.release.example))。 -2. 重新创建相关容器: - - ```bash - docker compose \ - --env-file /tmp/skillhub-runtime/.env.release \ - -f /tmp/skillhub-runtime/compose.release.yml \ - up -d --force-recreate - ``` - -3. 若此前密码已写入数据库导致仍不生效,可能需要清理对应数据后重新初始化。 +A: `BOOTSTRAP_ADMIN_PASSWORD` 用于初始化账号。`BootstrapAdminInitializer` 在本地凭证已存在时保留原密码,因此修改环境变量或重建容器不会重置已有账号密码。使用实例提供的修改/找回密码流程;邮件验证码需要正确配置 SMTP。不要删除用户或数据库重新初始化。 ## Q: 修改 / 找回密码必须使用邮箱验证码吗? -A: 是的,默认通过邮箱验证码修改或找回密码,因此需要先配置 SMTP。配置方法参考 [docs/19-smtp-password-reset-email-setup.md](https://github.com/iflytek/skillhub/blob/main/docs/19-smtp-password-reset-email-setup.md)。管理员也可在 `.env.release` 中进行重置。 +A: 网页找回密码使用邮箱验证码;已登录且知道原密码的修改接口不使用该验证码。找回流程需先配置 [SMTP](https://github.com/iflytek/skillhub/blob/main/docs/19-smtp-password-reset-email-setup.md)。修改 bootstrap 环境变量不能重置已经初始化的密码。 ## Q: skill 可以起中文名吗? -A: skill name 一般使用英文,目前不支持中文名(在 OpenClaw 中使用中文 skill 名会报错)。 +A: 技能标识 `name` / slug 使用符合校验规则的名称;面向用户的展示名支持中文,可通过 `metadata.display-name` 配置。展示名不改变安装坐标或目录名。见 [发布指南](./guide/skill-publish.md)。 ## Q: 未审核的 skill 可以下载吗? -A: 只要拥有可查看的权限,一般都可以下载。 +A: 正常安装面向已发布且当前用户可访问的版本。能查看详情不等于能下载任意状态的版本;作者或审核人员的预览权限与公开分发权限不同。见 [审核与治理](./guide/review.md)。 ## Q: 如何隐藏或删除登录页的第三方 SSO 登录方式? @@ -273,7 +174,7 @@ SKILLHUB_PUBLISH_MAX_FILE_COUNT=500 ## Q: 使用 CLI(发布 / 下载等)对服务端版本有要求吗? -A: 需要 SkillHub 服务端镜像 **v0.2.7 及以上** 才支持 CLI 功能。 +A: 兼容性取决于具体命令。旧版本支持基础 CLI 不代表支持 Device Flow、Suite 或同步;请核对 CLI 版本与目标服务端发行说明。Suite 要求服务端声明 `skill-suite-v1`。见 [CLI 指南](./guide/cli.md)。 ## Q: SkillHub 支持 MySQL 数据库吗? @@ -372,21 +273,7 @@ A: OAuth 首次登录创建的是普通用户。需要由已有的 `SUPER_ADMIN` ## Q: 如何批量安装多个技能包? -A: CLI 的 `install` 一次处理一个技能包。下面两个示例都通过 `--dir` 将技能批量安装到同一个目标根目录;每个技能实际位于 `$target_dir//`: - -```bash -target_dir=/opt/skillhub-skills - -# 逐个安装 -for skill in skill-a skill-b skill-c; do - skillhub install "$skill" --dir "$target_dir" -done - -# 或从清单文件读取(每行一个技能名) -xargs -a skills.txt -I {} skillhub install "{}" --dir "$target_dir" -``` - -自 **SkillHub Server v0.2.12** 起,公开技能支持匿名搜索与安装;如果配置了无效的 Bearer Token,命令会直接失败而不再回退匿名访问,遇到这种情况请更新凭据或先移除无效 Token。 +A: 需要固定成员版本并统一升级时,使用 [技能套装](./guide/skill-suites.md) 的 `skillhub suite install`。同步团队命名空间工作区时,使用 [CLI](./guide/cli.md) 的 `skillhub sync pull`。若只是独立安装几个无关技能,可分别运行 `skillhub install`;Suite Bundle 是发布者的导入格式,不是本地安装命令。 ## Q: 遇到问题怎么办? @@ -455,7 +342,7 @@ java -version lsof -i :8080 # 终止进程 -kill -9 +# 确认进程用途后,通过其启动工具停止服务 ``` ### 4. 查看详细日志 diff --git a/docs/skillhub/guide/account-access.md b/docs/skillhub/guide/account-access.md new file mode 100644 index 000000000..7fdf2bce5 --- /dev/null +++ b/docs/skillhub/guide/account-access.md @@ -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。 diff --git a/docs/skillhub/guide/cli.md b/docs/skillhub/guide/cli.md index da10fb011..a76030f50 100644 --- a/docs/skillhub/guide/cli.md +++ b/docs/skillhub/guide/cli.md @@ -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 ` 核对本机命令;文档对应当前代码,不保证老版本全部支持。 + +同一工作流的搜索、登录、安装和检查应指向同一 Registry。显式 `--registry` 适合单次操作;环境变量适合当前进程树。凭证按 Registry 保存,切换地址后使用 `whoami` 核对身份。 + +`--json` 用于机器读取,不要在自动化中假设会出现交互提示。捕获退出码和输出;遇到结构化服务端错误保留公开消息与 requestId。Suite 检查的 `ok: false` 可以只是发现变化,需继续读取结果字段。`--check` 是相应升级/同步操作的预览能力,不是所有命令的通用参数。 + +遇到同名目录冲突时先检查来源:`--force` 只对允许覆盖的受管理目标有效,不会接管未知目录或其他来源。恢复记录前保留本地文件与 metadata;不要删除整个 `~/.skillhub`,其中还存有其他实例凭证和安装记录。 + ## 安装 ```bash @@ -19,7 +40,7 @@ bun add -g @astron-team/skillhub ```bash # 登录 -skillhub login --token sk_xxx +skillhub login # 搜索技能 skillhub search pdf @@ -73,6 +94,8 @@ Token 按以下优先级解析: ### 登录 +没有从命令行、环境变量或该注册中心保存记录读取到 Token 时,`skillhub login` 才使用 OAuth Device Flow;读取到无效 Token 时不会自动回退:打开验证页面并显示用户码,完成浏览器授权后保存凭证。无浏览器终端可用 `skillhub login --no-open`;自动化使用 API token。 + ```bash # 使用 API token 登录 skillhub login --token sk_xxx @@ -237,6 +260,31 @@ DeepSeek Harness 从最近的 Git 仓库根目录解析项目技能,而 SkillH } ``` +## 技能安装后的使用与套装 + +安装命令只下载技能文件,不执行任务。打开目标项目并让 Agent 发现 `SKILL.md`,按技能说明配置依赖,再要求 Agent 使用该技能。套装请阅读[安装与使用指南](./skill-suites)。 + +```bash +# Replace with a real Suite coordinate +skillhub suite install @team/example-suite --scope project --agent codex +skillhub suite check @team/example-suite +skillhub suite upgrade @team/example-suite --check +skillhub suite upgrade @team/example-suite +skillhub suite remove @team/example-suite +``` + +## 团队工作区同步 + +`sync` 面向非 global 命名空间:pull 拉取选定技能,status/diff 检查变化,push 发布本地内容。默认工作区为当前目录的 `.agents/skills`。非交互 pull 必须显式选择 `--skill`;`--check` 只检查。 + +```bash +skillhub sync pull --namespace team --check +skillhub sync pull --namespace team --skill example-skill +skillhub sync status --namespace team +skillhub sync diff --namespace team +skillhub sync push --namespace team --all --dry-run +``` + ## 本地管理 ### 查看已安装技能 @@ -303,7 +351,7 @@ skillhub doctor 3. 备份旧的 `inventory.json`(如果存在) 4. 写入新的 `inventory.json` -如果同一技能在不同目标中存在版本冲突,该技能会被跳过并报告。 +版本按安装目标记录。doctor 报告恢复问题,不会下载或升级技能。 ## 发布 @@ -323,7 +371,7 @@ skillhub publish ./my-skill --namespace myspace --visibility private - `namespace-only` — 仅 namespace 成员可见 - `private` — 仅自己可见 -发布成功后会输出技能详情页 URL。 +提交被服务端接受后会输出当前状态和技能详情页 URL。`SCANNING`、`PENDING_REVIEW` 表示异步处理尚未完成;请在详情页确认最终发布状态。 ## 自更新 @@ -380,26 +428,9 @@ skillhub update ### inventory.json -```json -{ - "items": [ - { - "registry": "https://skill.xfyun.cn", - "namespace": "global", - "slug": "pdf-parser", - "version": "1.0.0", - "targets": [ - { - "agent": "codex", - "rootDir": "/path/to/project/.codex/skills", - "installDir": "/path/to/project/.codex/skills/pdf-parser", - "installedAt": "2026-04-28T06:00:00.000Z" - } - ] - } - ] -} -``` +CLI 管理的安装记录,不应手工编辑。每个安装目标分别记录版本、fingerprint 和来源;兼容客户端在需要时迁移旧记录。备份用于恢复核查,不代表可以直接覆盖更新后的 inventory。 + +当前主分支代码包含使用 inventory v3 的 DSH 启用/停用能力。不要假设已发布 CLI 已支持,也不要混用不兼容写入端。CLI 没有 enable/disable 命令;该增量中,CLI `--force` 不能升级停用目标,doctor 也不会仅凭孤立的 `SKILL.md.disabled` 重建停用来源。启停由兼容版本的 DSH 管理,使用时以配套发行说明为准。 ## JSON 输出 @@ -447,6 +478,7 @@ skillhub doctor --json | 3 | 网络错误 | | 4 | 文件系统错误 | | 5 | 参数错误 | +| 6 | 校验或安装来源冲突 | ## 命令参考 @@ -471,7 +503,7 @@ skillhub version --json ### login ```bash -skillhub login --token [--registry ] [--json] +skillhub login [--no-open] [--token ] [--registry ] [--json] ``` 保存 token 和 registry 配置。 @@ -578,6 +610,22 @@ skillhub publish [options] - `--token ` — API token - `--json` — JSON 输出 +### suite + +```bash +skillhub suite [options] +``` + +`install` 支持 `--version`、`--scope`、`--agent`、`--dir`;`install` 和 `upgrade` 支持 `--force`。`upgrade --check` 预览变更。各操作支持 `--registry`、`--token`、`--json`。详见[套装指南](./skill-suites)。 + +### sync + +```bash +skillhub sync --namespace [options] +``` + +先运行 `skillhub help sync` 查看选择、工作区和发布参数;发布前使用 `push --dry-run` 验证。 + ### update ```bash @@ -610,7 +658,7 @@ skillhub login --token sk_xxx ```bash # 检查 registry 是否可访问 -curl https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1 +curl 'https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1' # 使用其他 registry skillhub search test --registry https://skillhub.example.com diff --git a/docs/skillhub/guide/deployment.md b/docs/skillhub/guide/deployment.md new file mode 100644 index 000000000..ae8f69703 --- /dev/null +++ b/docs/skillhub/guide/deployment.md @@ -0,0 +1,74 @@ +# Docker Compose 部署与升级 + +使用已有 Registry 安装技能不需要部署服务。只有需要自托管 Registry 时才执行本页流程。源码开发使用 `make dev-all`;容器回归使用 `make staging`;正式单机交付使用 `compose.release.yml`。集群部署见 [Kubernetes](kubernetes.md)。 + +## 准备配置 + +需要 Docker、Docker Compose,以及与目标版本匹配的仓库文件。在仓库根目录执行: + +```bash +cp .env.release.example .env.release +``` + +编辑 `.env.release` 后再启动: + +| 配置 | 需要确认 | +| --- | --- | +| `SKILLHUB_VERSION` | 固定已发布版本,避免升级时无意更换镜像;`latest` 跟踪稳定发布,`edge` 跟踪主分支构建 | +| `SKILLHUB_PUBLIC_BASE_URL` | 用户实际访问的地址,生产环境使用 HTTPS | +| `WEB_PORT` / `API_PORT` | 默认分别为 80 / 8080,确认端口可用 | +| `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)配置 | + +`.env.release` 包含敏感信息,不要提交或分享。已有数据库的密码不会因修改环境变量自动轮换。发布环境不要启用 `local` profile 的 Mock 登录。 + +## 启动与确认 + +```bash +make validate-release-config +docker compose --env-file .env.release -f compose.release.yml pull +docker compose --env-file .env.release -f compose.release.yml up -d +docker compose --env-file .env.release -f compose.release.yml ps +docker compose --env-file .env.release -f compose.release.yml logs --tail=100 server +``` + +校验通过后再启动。首次启动或升级时,后端会执行 Flyway 数据库迁移。访问配置的公开地址,使用自己配置的管理员凭证登录,并验证搜索、下载以及一次符合权限的发布/审核流程;容器健康不代表这些业务路径已通过。 + +Suite 审核写入在单机 release Compose 中默认开启;Suite Bundle 确认默认关闭。需要批量导入时,按 [Bundle 导入](suite-bundle.md#部署开关)启用对应开关。滚动升级新旧后端共存时,另按[套装部署顺序](https://github.com/iflytek/skillhub/blob/main/docs/25-skill-suites.md#部署顺序)操作。 + +## 升级、停止与排障 + +升级前保存当前镜像版本、配置,并备份数据库和技能对象存储。修改 `SKILLHUB_VERSION` 为目标发布版本,重新执行校验、`pull`、`up -d` 和业务验证。回退镜像不等于回退数据库;先检查目标迁移的兼容性。 + +```bash +# 停止本实例;不要附加 -v,除非明确要删除数据卷 +docker compose --env-file .env.release -f compose.release.yml down +``` + +启动失败先查看 `ps` 和服务日志,核对数据库、Redis、存储和公开地址配置。提交问题时提供镜像版本、脱敏日志和请求 ID,不提供 `.env.release` 或凭证。更多 Redis、反向代理、采集服务和迁移配置见[运维手册](https://github.com/iflytek/skillhub/blob/main/docs/09-deployment.md)。 + +## 配置检查与上线验收 + +发布模板和 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、技能与头像存储、私有运行配置及加密密钥。恢复时使用匹配的应用版本和配置,先在隔离环境验证恢复后的登录与下载;不要以删除卷或清空数据库作为升级失败的默认处理。 diff --git a/docs/skillhub/guide/index.md b/docs/skillhub/guide/index.md new file mode 100644 index 000000000..b6ef57dd7 --- /dev/null +++ b/docs/skillhub/guide/index.md @@ -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):本地开发环境和仓库检查命令。 diff --git a/docs/skillhub/guide/kubernetes.md b/docs/skillhub/guide/kubernetes.md index 0be3b5c92..19c4f4840 100644 --- a/docs/skillhub/guide/kubernetes.md +++ b/docs/skillhub/guide/kubernetes.md @@ -1,4 +1,4 @@ -# Kubernetes 部署指南 +# Kubernetes 部署:Kustomize 配置与验收 对象存储可选部署、凭证和迁移说明见[对象存储手册(GitHub)](https://github.com/iflytek/skillhub/blob/main/docs/object-storage.md)。 @@ -37,6 +37,8 @@ deploy/k8s/ ## 快速开始 +以下相对路径均以仓库的 `deploy/k8s` 为工作目录。先配置 Secret,再渲染检查 `kubectl kustomize overlays/with-infra/`;输出可能包含 Secret,不要公开粘贴。应用清单会创建资源并在后端启动时执行数据库迁移。 + ### 1. 创建命名空间 ```bash @@ -46,10 +48,10 @@ kubectl create namespace skillhub ### 2. 配置 Secret ```bash -cd deploy/k8s/base +cd deploy/k8s # 复制示例文件 -cp secret.yaml.example secret.yaml +cp base/secret.yaml.example base/secret.yaml # 编辑 secret.yaml,修改敏感配置 ``` @@ -68,6 +70,14 @@ cp secret.yaml.example 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)** @@ -272,7 +282,7 @@ kubectl create secret docker-registry ghcr-secret \ kubectl logs postgres-0 -n skillhub # 检查 Secret 配置 -kubectl get secret skillhub-secret -n skillhub -o yaml +kubectl describe deployment skillhub-server -n skillhub ``` ### 查看日志 @@ -290,6 +300,8 @@ kubectl logs -l app.kubernetes.io/name=skillhub-scanner -n skillhub -f ## 清理 +仅在确认不再使用该实例并完成数据库、技能存储备份后执行。删除命名空间会删除其中的资源和 PVC;底层数据是否保留取决于存储回收策略。 + ```bash # 删除所有资源 kubectl delete -k overlays/with-infra/ # 或 overlays/external/ @@ -297,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 路径混用。 diff --git a/docs/skillhub/guide/namespace.md b/docs/skillhub/guide/namespace.md index ba2523136..655ddaa77 100644 --- a/docs/skillhub/guide/namespace.md +++ b/docs/skillhub/guide/namespace.md @@ -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,9 +34,9 @@ | 角色 | 权限 | |------|------| -| **Owner** | 完全控制,包括删除命名空间、管理所有成员 | +| **Owner** | 团队空间所有者,可按空间状态与服务端权限管理成员及转让所有权 | | **Admin** | 管理成员、审核技能包、修改设置 | -| **Member** | 发布技能包、查看私有技能包 | +| **Member** | 发布技能包、查看空间成员可见的技能包 | **命名空间状态**: @@ -70,7 +87,7 @@ 2. 点击「成员」标签 3. 点击「添加成员」 4. 搜索用户(支持按用户名、邮箱搜索) -5. 选择角色(Owner / Admin / Member) +5. 选择角色(Admin / Member;Owner 使用独立转让流程) 6. 确认添加 **通过链接邀请成员**: @@ -116,7 +133,7 @@ POST /api/v1/namespaces Content-Type: application/json { - "name": "iFlytek AI Team", + "displayName": "iFlytek AI Team", "slug": "iflytek", "description": "iFlytek's AI agent skills" } @@ -125,9 +142,9 @@ Content-Type: application/json **参数说明**: | 参数 | 类型 | 说明 | |------|------|------| -| name | string | 命名空间名称(必需,2-50 字符) | +| displayName | string | 命名空间名称(必需,最多 128 字符) | | slug | string | URL 标识符(必需,唯一,2-64 字符,只能包含小写字母、数字、连字符) | -| description | string | 描述(可选,最多 500 字符) | +| description | string | 描述(可选,最多 512 字符) | **获取命名空间详情**: ```bash @@ -140,7 +157,7 @@ PUT /api/v1/namespaces/{slug} Content-Type: application/json { - "name": "iFlytek AI Team (Updated)", + "displayName": "iFlytek AI Team (Updated)", "description": "Updated description" } ``` @@ -203,7 +220,7 @@ POST /api/v1/namespaces/{slug}/unfreeze > **Slug 唯一性**:命名空间 slug 在全局范围内必须唯一,且创建后不可修改。建议使用团队或项目的简短标识符。 - **Owner 权限**:每个命名空间至少需要一个 Owner,最后一个 Owner 无法被移除 -- **角色继承**:命名空间成员自动拥有该命名空间下所有技能包的访问权限 +- **角色继承**:成员可访问 NAMESPACE_ONLY 内容;PRIVATE 内容仅所有者及有权管理员可访问,不向所有成员开放 - **冻结机制**:管理员可以冻结命名空间,冻结后无法发布新技能包 - **归档机制**:归档的命名空间会从搜索结果中隐藏,但已有技能包仍可访问 - **审计日志**:所有成员变更、权限调整都会记录到审计日志 diff --git a/docs/skillhub/guide/review.md b/docs/skillhub/guide/review.md index 194316bd3..cf1bccd5b 100644 --- a/docs/skillhub/guide/review.md +++ b/docs/skillhub/guide/review.md @@ -1,4 +1,18 @@ -# 审核与治理 +# 审核技能与套装 + +## 审核员的检查清单 + +1. 核对审核对象、提交者和目标版本。技能版本、头像或资料变更、套装版本不能混用同一判断。 +2. 读取本次提交的文件与变更,不仅阅读当前公开版本。新版审核期间,旧公开版本可能仍可下载。 +3. 检查扫描状态及发现项。扫描执行失败、风险发现和未配置某项分析器分别处理;空报告不能当作安全结论。 +4. 检查可见范围与受众,特别是套装每个成员的可用性和入口身份。成员通过审核不自动批准套装。 +5. 批准前确认当前数据仍有效;拒绝时写明具体文件、问题及修订方向。点击失败时重新读取状态,避免对旧页面重复作出相反决定。 +6. 审核完成后查看记录和发布版本。审核操作成功不验证本地 Agent 的技能执行效果。 + +### 作者如何跟踪和修订 + +在“我的提交”查看待审任务和意见,未完成审核前可按权限撤回。撤回是停止当前审核,不会删除已发布旧版本或撤销已批准的全局提升。被拒绝后根据意见修订,再通过当前版本页面提供的重新提交操作继续;不要把上传成功当成审核重开成功。 + ## 功能描述 @@ -29,13 +43,17 @@ SkillHub 提供了完整的审核工作流,确保发布到注册中心的技 **治理功能**: -- **审核工作流**:多级审核、批量审核 +- **审核工作流**:按权限逐项审核技能版本、资料变更和套装 - **举报系统**:用户可以举报不当技能包 -- **推广管理**:将命名空间技能包推���到全局 +- **推广管理**:将命名空间技能包推广到全局 - **审计日志**:记录所有治理操作 头像变更复用技能审核申请。机器阻止与人工拒绝是不同状态;开关组合、审核操作及云审核接入步骤详见 [技能头像与图片审核接入](/guide/skill-avatars)。 +## 先确认审核对象 + +审核任务状态与技能版本状态不同:任务为 PENDING 时,版本可能仍在 SCANNING。先等待扫描完成并检查风险,再作审核决定。成员技能审核通过不代表引用它的 Suite 已通过;Suite 有独立审核。Bundle 导入先完成成员发布,再创建 Suite 草稿,详见[技能套装](/guide/skill-suites)与[批量导入](/guide/suite-bundle)。 + ## 使用场景 **场景一:命名空间管理员审核** @@ -52,17 +70,14 @@ SkillHub 提供了完整的审核工作流,确保发布到注册中心的技 用户举报不当技能包,管理员调查并处理。 -**场景四:批量审核** - -管理员批量批准多个符合规范的技能包。 ## 使用步骤 **提交审核**: -1. 发布技能包时,系统自动创建审核任务 +1. 普通 PUBLIC / NAMESPACE_ONLY 上传创建审核任务;PRIVATE 上传先保留,需确认发布或另行提审 2. 开发者可以在「我的提交」中查看审核状态 -3. 等待管理���审核 +3. 等待管理员审核 **审核技能包**: @@ -76,7 +91,9 @@ SkillHub 提供了完整的审核工作流,确保发布到注册中心的技 - 在“审核记录”查看提交历史和已完成的审核意见;该页签打开时才请求历史 - 套件审核在内容区核对待审快照。快照加载失败时可重试,加载成功前“通过”按钮不可用 -![流程图](/diagrams/review-flow.png) +![普通发布路径中的扫描与审核](/diagrams/skill-publish-lifecycle-sketch.png) + +本页的审核部分对应 PUBLIC / NAMESPACE_ONLY 分支:扫描完成后,版本等待审核决定。 4. 在页面底部固定的审核栏填写意见并做出决策;切换页签保留意见,切换到另一个审核对象时清空意见、驳回表单和未确认弹窗: - **批准**:技能包正式发布,开发者收到通知 @@ -139,7 +156,7 @@ POST /api/v1/reviews Content-Type: application/json { - "skillVersionId": "version-123" + "skillVersionId": 123 } ``` @@ -166,12 +183,12 @@ Content-Type: application/json **参数说明**: | 参数 | 类型 | 说明 | |------|------|------| -| id | string | 审核任务 ID(路径参数) | -| comment | string | 审核意见(可选,最多 1000 字符) | +| id | number | 审核任务 ID(路径参数) | +| comment | string | 审核意见(批准时可选;拒绝时应填写明确原因) | **列出待审核任务**: ```bash -GET /api/v1/reviews/pending?namespaceId=ns-123&page=0&size=20 +GET /api/v1/reviews/pending?namespaceId=123&page=0&size=20 ``` **列出我的提交**: @@ -215,11 +232,10 @@ Content-Type: application/json ## 注意事项 -> **审核权限**:只有命名空间的 Admin 和 Owner 可以审核本命名空间的技能包。平台管理员可以审核所有技能包。 +> **审核权限**:团队空间 Admin / Owner 可审核本空间;平台 SKILL_ADMIN / SUPER_ADMIN 具有平台审核权限。个人空间及本人提交的审核还受自审规则约束,不能仅凭“管理员”称呼判断。 - **审核时效**:建议在 24 小时内完成审核,避免阻塞开发者 - **审核记录**:所有审核操作都会记录到审计日志 - **合规审计**:合规声明以版本快照形式记录。审核通过或拒绝时,应结合差异摘要判断风险,但 Agent 执行 trace 不由 SkillHub 记录 -- **批量审核**:管理员可以批量批准多个技能包 - **审核意见**:拒绝时建议提供详细的改进建议 - **撤回限制**:只有待审核状态的技能包可以撤回 diff --git a/docs/skillhub/guide/runtime-integration.md b/docs/skillhub/guide/runtime-integration.md index cb3b42b4c..887e69660 100644 --- a/docs/skillhub/guide/runtime-integration.md +++ b/docs/skillhub/guide/runtime-integration.md @@ -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` | 该版本合规声明快照的稳定摘要 | @@ -37,7 +37,7 @@ Runtime 在执行技能时,如果需要把执行链路与 SkillHub 的合规 GET /api/v1/skills/{namespace}/{slug}/versions/{version} ``` -响应中的关键字段: +下面仅展示成功响应 `data` 内的关键字段,不是完整 HTTP 响应。先检查外层业务 `code`,再读取 `data.id` 和 `data.complianceSnapshot`;没有声明的版本可能没有快照,不应据此推断为已认证或执行违规。 ```json { @@ -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 自己的系统;这些接口不接收执行结果。 diff --git a/docs/skillhub/guide/scanner.md b/docs/skillhub/guide/scanner.md index 33837cbb7..c72d6ef3b 100644 --- a/docs/skillhub/guide/scanner.md +++ b/docs/skillhub/guide/scanner.md @@ -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 病毒扫描 | 可选 | @@ -93,7 +110,7 @@ curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- u ## 注意事项 -> **扫描不阻塞发布**:安全扫描是异步执行的,不会阻塞技能包的上传流程。扫描结果会在完成后更新到技能包详情页。 +> **异步上传不等于发布放行**:普通公开及空间内发布要求扫描已启用,扫描未完成时不能视为已发布。SCAN_FAILED 是执行失败;扫描发现风险与执行失败须分别处理。扫描通过也不等于人工审核通过。 - **扫描耗时**:根据技能包大小和启用的引擎数量,扫描可能需要几秒到几分钟 - **LLM 分析成本**:启用 LLM 分析会产生 API 调用费用,建议在生产环境中评估成本 diff --git a/docs/skillhub/guide/skill-avatars.md b/docs/skillhub/guide/skill-avatars.md index f8b6861a4..e1f50ddfc 100644 --- a/docs/skillhub/guide/skill-avatars.md +++ b/docs/skillhub/guide/skill-avatars.md @@ -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),并验证人工拒绝后保留旧公开头像;阿里云已进行接口契约、结果映射和异常处理的代码审查及模拟响应测试,**尚未真实账号联调**。这些结果不替代部署方对自己账号的连接验收。 +供应商接口的代码与模拟测试不能替代本部署的账号验收。每次启用或轮换后都应验证实际账号的连通性、结果映射和失败行为。 ## 修改开关与切换供应商 diff --git a/docs/skillhub/guide/skill-discovery.md b/docs/skillhub/guide/skill-discovery.md index 8b72adb6d..bac4eb332 100644 --- a/docs/skillhub/guide/skill-discovery.md +++ b/docs/skillhub/guide/skill-discovery.md @@ -1,148 +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 为准。 + +## 图示与界面参考 ![概念图](/diagrams/skill-discovery-concept.png) -**核心特性**: - -- **全文搜索**:搜索技能包名称、描述、标签、作者 -- **智能过滤**:按命名空间、标签、可见性过滤 -- **多种排序**:按相关性、下载量、评分、更新时间排序 -- **权限感知**:只显示用户有权访问的技能包 -- **实时更新**:新发布的技能包立即出现在搜索结果中 - -**搜索算法**: - -SkillHub 使用 PostgreSQL 全文搜索,支持: -- 中英文分词 -- 模糊匹配 -- 权重排序(标题权重 > 描述权重 > 标签权重) - -## 使用场景 - -**场景一:新成员探索** - -新加入团队的开发者想了解团队已有哪些可用的技能包。 - ![操作截图](/screenshots/skill-discovery-search.png) -**场景二:按需查找** - -开发者需要一个处理 PDF 的技能包,搜索 "pdf" 关键词。 - -**场景三:浏览热门** - -查看团队内下载量最高、评分最好的技能包,学习最佳实践。 - -**场景四:按标签过滤** - -只查看 `data-processing` 标签的技能包。 - -## 使用步骤 - -### 使用 CLI 搜索和安装(推荐) - -```bash -# 配置注册中心 -export CLAWHUB_REGISTRY=http://localhost:8080 - -# 搜索技能包 -npx clawhub search pdf - -# 安装技能包 -npx clawhub install pdf-parser - -# 安装指定命名空间的技能包 -npx clawhub install my-team--pdf-parser -``` - -### 使用 Web UI 搜索 - -1. **访问搜索页面** - -访问 `http://localhost:3000/search` 或在首页使用搜索框。 - -2. **输入关键词** - -在搜索框输入关键词,例如 "pdf parser"。 - -3. **应用过滤器** - -- 选择命名空间(例如只看 `iflytek` 命名空间) -- 选择标签(例如 `data-processing`) -- 选择排序方式(例如按下载量降序) - ![流程图](/diagrams/skill-discovery-flow.png) - -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(下载量)、rating(评分)、updated(更新时间) | -| page | number | 页码(从 0 开始) | -| size | number | 每页数量(默认 20,最大 100) | - -**响应示例**: -```json -{ - "content": [ - { - "id": "skill-123", - "namespace": "iflytek", - "slug": "pdf-parser", - "name": "PDF Parser", - "description": "Extract text and metadata from PDF files", - "downloads": 1234, - "rating": 4.5, - "starCount": 56, - "latestVersion": "1.2.3", - "updatedAt": "2026-03-15T10:30:00Z", - "labels": ["data-processing", "pdf"] - } - ], - "totalElements": 42, - "totalPages": 3, - "number": 0, - "size": 20 -} -``` - -## 注意事项 - -> **权限控制**:搜索结果会根据用户权限自动过滤。PRIVATE 技能包只对命名空间成员可见,INTERNAL 技能包只对登录用户可见。 - -- **搜索性能**:SkillHub 使用 PostgreSQL 全文搜索,支持中英文分词 -- **实时更新**:新发布的技能包会立即出现在搜索结果中 -- **标签规范**:建议使用统一的标签命名规范,便于过滤 -- **搜索提示**:支持搜索建议和自动补全(前端实现) diff --git a/docs/skillhub/guide/skill-publish.md b/docs/skillhub/guide/skill-publish.md index e5e5de2d3..c4d287bb1 100644 --- a/docs/skillhub/guide/skill-publish.md +++ b/docs/skillhub/guide/skill-publish.md @@ -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,13 +172,15 @@ file: skill-package.zip visibility: PUBLIC ``` -![流程图](/diagrams/skill-publish-flow.png) +![公开与私有技能的普通发布路径](/diagrams/skill-publish-lifecycle-sketch.png) + +图示覆盖普通上传;扫描失败、审核拒绝及特权发布的区别见下文。 5. **安全扫描** 发布后,[Skill Scanner](/guide/scanner) 会自动扫描技能包,检测潜在的安全风险。扫描结果会显示在技能包详情页。 -6. **等待审核**(如果命名空间开启了审核) +6. **等待审核**(以返回状态为准) 团队管理员会收到审核通知,审核通过后技能包正式发布。 @@ -146,6 +188,16 @@ visibility: PUBLIC 技能包可以通过搜索发现,其他人可以通过 CLI 或 Web UI 下载使用。 +## 提交成功不等于发布成功 + +上传后查看返回状态及“我的技能”中的本次版本。普通 PUBLIC 和 NAMESPACE_ONLY 上传要求扫描已启用,版本先进入 `SCANNING`,扫描完成后回到 `PENDING_REVIEW`,审核批准才发布。PRIVATE 上传在完成已配置的扫描后停留在 `UPLOADED`,还需通过确认发布操作发布。特权自动发布使用另一条路径。 + +`SCAN_FAILED` 表示扫描执行失败,不代表已经判定包有害;扫描完成也可能有风险发现。上传成功、HTTP 成功或 CLI 正常退出,都不能单独证明版本已 `PUBLISHED`。更新审核期间,公众继续看到已发布版本,有权维护者可以预览待审版本。 + +### 创作草稿的边界 + +创作 API 支持私有草稿、文件编辑和结构校验,目前不包含网页创作工作台或自动发布。校验通过不代表执行过技能,也不代表安全检查通过。创作草稿与上传后等待审核的技能版本是不同对象。 + ## 合规声明 技能作者可以在 `SKILL.md` frontmatter 中添加 `x-astron-compliance`,声明该技能版本与某些合规标准、控制项或安全知识库条目的映射关系。 @@ -194,7 +246,7 @@ Content-Type: multipart/form-data # 参数 file: MultipartFile (必需) -visibility: PUBLIC | PRIVATE | INTERNAL (可选,默认 PUBLIC) +visibility: PUBLIC | PRIVATE | NAMESPACE_ONLY (可选,默认 PUBLIC) ``` **参数说明**: @@ -202,7 +254,7 @@ visibility: PUBLIC | PRIVATE | INTERNAL (可选,默认 PUBLIC) |------|------|------| | namespace | string | 命名空间 slug(路径参数) | | file | MultipartFile | 技能包 zip 文件 | -| visibility | enum | 可见性级别:PUBLIC(公开)、PRIVATE(私有)、INTERNAL(内部) | +| visibility | enum | 可见性级别:PUBLIC(公开)、PRIVATE(私有)、NAMESPACE_ONLY(空间成员可见) | **获取 Skill 详情**: ```bash @@ -231,16 +283,16 @@ 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 字符 - **版本不可变**:已发布的版本不能修改,只能发布新版本 diff --git a/docs/skillhub/guide/skill-suites.md b/docs/skillhub/guide/skill-suites.md new file mode 100644 index 000000000..8cc72b95f --- /dev/null +++ b/docs/skillhub/guide/skill-suites.md @@ -0,0 +1,97 @@ +# 管理技能套装 + +Skill Suite(技能套装)把一组已发布 Skill 的精确版本组织成一个有独立名称和版本的集合,并指定一个 Entry Skill(入口技能)。安装后,每个成员仍是独立的技能目录。 + +## Skill、Suite 和 Bundle 的区别 + +| 类型 | 用途 | 使用方式 | +| --- | --- | --- | +| Skill | 一个包含 `SKILL.md` 的技能包 | `skillhub install` 安装,交给 Agent 使用 | +| Skill Suite | 固定版本的技能集合,包含一个入口技能 | `skillhub suite install` 安装全部成员 | +| Suite Bundle | 作者批量上传成员和套装定义的 ZIP 或文件夹 | 在网页中导入、预览、确认,再完成发布审核 | + +Bundle 是[创作与导入格式](./suite-bundle),不是安装后需要执行的程序。套装也不是工作流引擎:是否串联成员、如何分派任务,由入口及成员的 `SKILL.md` 决定。普通技能可以独立安装,不必安装它关联的所有套装。 + +![套装安装与入口技能使用流程](/diagrams/skill-suite-usage-sketch.png) + +安装交付的是独立成员文件;在 Agent 中提出任务后才开始使用。 + +## 找到并安装套装 + +在技能详情中查看关联套装,进入套装详情,确认入口、成员版本和可安装状态。卡片上的关联标识只表示收录关系。普通 `skillhub search` 搜索 Skill;安装同名 Suite 必须显式使用 `suite` 子命令。 + +以下 `@team/example-suite` 是占位示例,请替换为实际坐标;需要访问受限内容时先登录对应 Registry。 + +```bash +skillhub login +# 在目标项目根目录安装给 Codex +skillhub suite install @team/example-suite --scope project --agent codex +# 或安装给 Claude Code +skillhub suite install @team/example-suite --scope project --agent claude-code +# 指定套装版本;用户级安装供该用户的项目使用 +skillhub suite install @team/example-suite --version 1.0.0 --scope user --agent codex +``` + +`--registry ` 可选择私有部署。服务端必须声明 `skill-suite-v1` 能力;CLI 出现 unknown command 时先检查 `skillhub version` 和 `skillhub help suite`,不要把单个 Skill 安装命令当成替代。 + +项目级 Codex 安装结果如下;Claude Code 使用 `.claude/skills`,用户级则在主目录下的对应位置: + +```text +.codex/skills/ +├── entry-skill/SKILL.md +├── member-a/SKILL.md +└── member-b/SKILL.md +``` + +目录名是各成员的 slug,不会生成一个合并后的同名套装技能。安装会下载并校验全部成员;成员不可访问或不可安装时,不能用最新版本悄悄替换固定版本。 + +## 安装后开始使用 + +1. 在对应 Agent 中打开安装目标项目,按该 Agent 的机制刷新技能或开启新会话。 +2. 检查安装输出中的路径,确认入口目录有 `SKILL.md`,并确认 Agent 能发现它。 +3. 阅读入口说明,补齐其要求的工具、环境变量或外部服务配置。安装技能文件不等于安装这些运行依赖。 +4. 明确请求使用入口,例如:“请使用入口技能 `<入口名称>` 完成下面的任务,并按照它的说明使用其他成员:……” + +套装坐标用于安装管理;调用时使用实际入口技能的名称,也可直接使用单个成员。Agent 的触发语法和加载时机由对应产品决定,SkillHub 不提供通用的 `suite run` 命令。 + +## 检查、升级与卸载 + +```bash +skillhub suite check @team/example-suite +skillhub suite upgrade @team/example-suite --check +skillhub suite upgrade @team/example-suite +skillhub suite remove @team/example-suite +``` + +`check` 显示本地成员状态和远端版本信息;`upgrade --check` 只预览变更。成员单独发布新版本不会改变已安装套装,升级遵循新 SuiteVersion 的固定成员清单。套装管理的目标应使用套装升级流程。 + +`--scope`、`--agent`、`--dir` 和 `--version` 仅用于 `suite install`;后续操作使用本地安装记录。卸载保留直接安装、被其他套装共享或本地修改过的成员。不要为消除提示直接删除 inventory。 + +## 创建套装 + +已有成员均已发布时,可通过网页套装编辑器选择精确成员版本和入口。需要同时上传多个本地成员时使用 [Suite Bundle](./suite-bundle)。PUBLIC 和 NAMESPACE_ONLY 套装需要套装级审核;PRIVATE 可直接发布。成员扫描和审核仍按各自 Skill 的流程执行。 + +每个版本最多 100 个不同成员,必须从成员中指定一个入口;不支持嵌套套装、版本范围或外部 Registry 成员。CLI 当前提供安装管理,不提供 `suite publish` 或直接读取创作定义文件的命令。 + +## 读懂本地检查结果 + +`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;后续操作按本地套装记录执行 | diff --git a/docs/skillhub/guide/social.md b/docs/skillhub/guide/social.md index 9b74c84f2..ec3fbf9ee 100644 --- a/docs/skillhub/guide/social.md +++ b/docs/skillhub/guide/social.md @@ -1,4 +1,4 @@ -# 用户交互与社交 +# 收藏、评分与通知 ## 功能描述 @@ -11,7 +11,7 @@ SkillHub 提供了丰富的社交功能,让团队成员可以互动、分享 - **星标(Star)**:收藏喜欢的技能包,方便后续查找 - **评分(Rating)**:给技能包打分(1-5 星),帮助其他人判断质量 - **下载统计**:记录下载次数,展示热门技能包 -- **通知系统**:及时接收审核结果、评论回复等通知 +- **通知系统**:及时接收审核、成员及治理等事件通知 **社交数据**: @@ -20,7 +20,7 @@ SkillHub 提供了丰富的社交功能,让团队成员可以互动、分享 | **星标数** | 有多少人收藏了这个技能包 | | **平均评分** | 所有用户评分的平均值 | | **下载量** | 累计下载次数 | -| **活跃度** | 最近更新时间、发布频率 | +| **更新时间** | 当前列表显示的更新时间 | ## 使用场景 @@ -36,7 +36,7 @@ SkillHub 提供了丰富的社交功能,让团队成员可以互动、分享 **场景三:查看通知** -收到审核通过的通知,或者有人评论了你的技能包。 +收到审核通过的通知,或其他受支持的治理事件通知。 ![操作截图](/screenshots/notifications.png) @@ -82,9 +82,30 @@ SkillHub 提供了丰富的社交功能,让团队成员可以互动、分享 1. 访问 `/dashboard/stars` 2. 查看所有星标的技能包 -3. 按星标时间、更新时间排序 +3. 分页浏览收藏列表;需要筛选时到搜索页启用“仅收藏” 4. 快速访问常用技能包 +## 操作前确认身份 + +收藏、评分和通知属于当前登录账号。匿名点击收藏或评分会触发登录提示;切换账号后请重新检查状态。收藏不会安装技能,取消收藏不会删除本地安装。评分按钮在请求期间禁用,提交成功后才刷新自己的评分及技能数据,悬停预览星数不代表保存成功。 + +## 管理通知而不遗漏处理 + +打开 `/notifications`,按全部、发布、审核、提升或举报分类查看,每页最多 20 条。点击未读项会标记已读并跳转到关联对象;通知本身不是执行审核批准的按钮,仍需在目标页面完成操作。 + +可以将通知全部标为已读;删除按钮仅用于已读通知。若希望减少提醒,打开 `/settings/notifications`,按分类调整站内通知开关。当前表单配置的是 `IN_APP`,不是邮件或短信订阅;没有保存偏好时默认开启。 + +## 确认结果与排查 + +| 操作或现象 | 可观察结果 / 下一步 | +| --- | --- | +| 收藏成功 | 按钮切换为已收藏,随后在“我的收藏”确认 | +| 修改星级 | 等待请求完成,核对“你的评分”;不要把悬停效果当成提交 | +| 清空评价 | 文字被清除,原有星级仍保留;这是不同于取消收藏的操作 | +| 自己能看到评价,公开列表没有 | 检查是否被隐藏;作者编辑不会自动恢复公开 | +| 通知仍显示旧未读数 | 等待轮询或重新聚焦窗口;仍异常时检查请求和登录状态 | +| 通知目标不可访问 | 重新核对资源当前状态和权限;历史通知不会恢复已失去的访问权 | + ## API 接口 **星标技能包**: @@ -102,13 +123,6 @@ DELETE /api/v1/skills/{skillId}/star GET /api/v1/skills/{skillId}/star ``` -**响应示例**: -```json -{ - "starred": true, - "starredAt": "2026-03-15T10:30:00Z" -} -``` **评分技能包**: ```bash @@ -123,7 +137,7 @@ Content-Type: application/json **参数说明**: | 参数 | 类型 | 说明 | |------|------|------| -| skillId | string | 技能包 ID(路径参数) | +| skillId | number | 技能包 ID(路径参数) | | score | number | 评分(1-5,必需) | **获取我的星标**: @@ -154,13 +168,8 @@ POST /api/v1/admin/skill-reviews/{reviewId}/hide POST /api/v1/admin/skill-reviews/{reviewId}/restore ``` -**响应示例**: -```json -{ - "score": 5, - "ratedAt": "2026-03-15T10:30:00Z" -} -``` + +响应使用统一 API 封装。`GET .../star` 的 `data` 是布尔值;`GET .../rating` 返回 `score` 和 `rated`。修改接口返回空 `data`,不会返回评分时间。技能 ID 为数值。 ## 注意事项 @@ -169,6 +178,6 @@ POST /api/v1/admin/skill-reviews/{reviewId}/restore > **评价规则**:只有已发布技能可以评价;公开列表只显示可见评价。并发修改发生冲突时,刷新详情后重试。 - **星标数量**:技能包的星标数会显示在搜索结果和详情页 -- **平均评分**:技能包的平均评分会影响搜索排序 +- **平均评分**:平均评分供选择技能时参考,不是搜索页的独立排序选项 - **通知设置**:用户可以在设置中关闭某些类型的通知 -- **下载统计**:每次下载都会增加下载计数,用于热门排序 +- **下载统计**:已发布版本的下载会记录计数;审核预览下载不计入公开下载统计 diff --git a/docs/skillhub/guide/suite-bundle.md b/docs/skillhub/guide/suite-bundle.md index 7779873ea..acdbf6389 100644 --- a/docs/skillhub/guide/suite-bundle.md +++ b/docs/skillhub/guide/suite-bundle.md @@ -1,7 +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`、目录重叠、路径穿越、重复路径、超出大小或文件数限制都会阻止预览。 @@ -11,8 +33,6 @@ SUITE.yaml skills/ intake/ SKILL.md - summarizer/ - SKILL.md ``` ```yaml @@ -28,7 +48,7 @@ spec: summary: 串联病历接收与摘要生成 overview: | 接收结构化病历,完成字段校验后生成摘要。 - 入口技能负责接收和分派,摘要技能负责输出最终结果。 + 入口技能使用共享词典完成字段校验。 visibility: PUBLIC entry: "@global/intake" members: diff --git a/docs/skillhub/index.md b/docs/skillhub/index.md index e3d4788cc..c24feb80a 100644 --- a/docs/skillhub/index.md +++ b/docs/skillhub/index.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 @@ -34,7 +34,7 @@ features: link: /guide/namespace - icon: ✅ title: 审核与治理 - details: 多级审核工作流,举报系统,确保技能包质量 + details: 技能与套装审核流程,举报系统,确保技能包质量 link: /guide/review - icon: ⭐ title: 用户交互与社交 diff --git a/docs/skillhub/introduction.md b/docs/skillhub/introduction.md index 472ebe8da..c03769b58 100644 --- a/docs/skillhub/introduction.md +++ b/docs/skillhub/introduction.md @@ -10,25 +10,27 @@ SkillHub 解决了这个问题。它提供了一个**私有、可控、易用** ## 核心价值 -- **3 分钟发布**:从本地开发到全球分发,只需一条命令 +- **统一分发**:上传技能包并跟踪扫描、审核和发布状态 - **企业级权限**:基于命名空间的 RBAC,支持团队协作和审核流程 - **完整生命周期**:版本管理、标签系统、审核工作流、归档机制 -- **开箱即用**:一条 curl 命令启动完整环境 +- **部署选择**:Docker Compose 和 Kubernetes,按环境配置依赖和认证 - **安全扫描**:内置 Skill Scanner,自动检测安全风险 - **数据主权**:完全自托管,所有数据都在你的防火墙内 ## 技术栈 -![技术栈图](/diagrams/tech-stack.png) +![前端、后端、数据与存储技术组成](/diagrams/tech-stack-sketch.png) + +存储可选择本地文件或 S3 兼容后端;按部署需求显式配置。 | 层级 | 技术 | 说明 | |------|------|------| -| **前端** | React 19 + Vite + TanStack Router | 现代化 SPA,支持中英文切换 | -| **后端** | Java 21 + Spring Boot 3.2 | 企业级 REST API | -| **数据库** | PostgreSQL 16 | 全文搜索、Flyway 自动迁移 | -| **缓存** | Redis 7 | 会话管理、热点缓存 | -| **存储** | MinIO / S3 | 技能包文件存储,支持本地和云端 | -| **部署** | Docker Compose / K8s | 一键启动,支持自托管 | +| **前端** | React + Vite + TanStack Router | 现代化 SPA,支持多语言切换 | +| **后端** | Java 21 + Spring Boot | 企业级 REST API | +| **数据库** | PostgreSQL | 全文搜索、Flyway 自动迁移 | +| **缓存** | Redis | 会话管理、热点缓存 | +| **存储** | 本地文件 / S3 兼容存储 | 技能包文件存储,支持本地和云端 | +| **部署** | Docker Compose / K8s | 按部署配置自托管 | ## 核心功能一览 @@ -37,6 +39,23 @@ SkillHub 解决了这个问题。它提供了一个**私有、可控、易用** | [Skill 发布与版本管理](/guide/skill-publish) | 一键发布技能包,语义化版本管理 | | [Skill 搜索与发现](/guide/skill-discovery) | 全文搜索、智能过滤、权限感知 | | [命名空间与团队管理](/guide/namespace) | 基于命名空间的 RBAC 权限体系 | -| [审核与治理](/guide/review) | 多级审核工作流、举报系统 | +| [审核与治理](/guide/review) | 技能与套装审核流程、举报系统 | | [安全扫描](/guide/scanner) | 内置 Skill Scanner,多引擎安全分析 | | [用户交互与社交](/guide/social) | 星标、评分、通知系统 | + +## 先理解三个对象 + +| 对象 | 用途 | 下一步 | +| --- | --- | --- | +| Skill | 带有 `SKILL.md` 的单个技能包,安装后由 Agent 发现和使用 | [快速开始](./quickstart.md) | +| Skill Suite | 固定成员版本的技能集合,指定一个成员作为入口技能 | [套装安装与使用](./guide/skill-suites.md) | +| Suite Bundle | 发布者批量上传套装定义和成员包的格式 | [批量导入](./guide/suite-bundle.md) | + +注册中心负责分发和治理;技能的实际执行发生在使用者的 Agent 环境中。安装套装不会自动运行全部成员。 + +## 按角色阅读 + +- 使用者:[CLI](./guide/cli.md)、[搜索与发现](./guide/skill-discovery.md)、[FAQ](./faq.md)。 +- 创作者:[发布与版本管理](./guide/skill-publish.md)、[套装](./guide/skill-suites.md)、[审核](./guide/review.md)。 +- 管理员:[命名空间](./guide/namespace.md)、[部署与升级](./guide/deployment.md)、[Kubernetes](./guide/kubernetes.md)。 +- 集成开发者:[Runtime 契约](./guide/runtime-integration.md)、[仓库文档索引](https://github.com/iflytek/skillhub/blob/main/docs/README.md)。 diff --git a/docs/skillhub/public/diagrams/skill-publish-lifecycle-sketch.png b/docs/skillhub/public/diagrams/skill-publish-lifecycle-sketch.png new file mode 100644 index 000000000..3231bf151 Binary files /dev/null and b/docs/skillhub/public/diagrams/skill-publish-lifecycle-sketch.png differ diff --git a/docs/skillhub/public/diagrams/skill-suite-usage-sketch.png b/docs/skillhub/public/diagrams/skill-suite-usage-sketch.png new file mode 100644 index 000000000..054a53110 Binary files /dev/null and b/docs/skillhub/public/diagrams/skill-suite-usage-sketch.png differ diff --git a/docs/skillhub/public/diagrams/tech-stack-sketch.png b/docs/skillhub/public/diagrams/tech-stack-sketch.png new file mode 100644 index 000000000..0e594dc7b Binary files /dev/null and b/docs/skillhub/public/diagrams/tech-stack-sketch.png differ diff --git a/docs/skillhub/quickstart.md b/docs/skillhub/quickstart.md index 69d7ef4e2..b67594593 100644 --- a/docs/skillhub/quickstart.md +++ b/docs/skillhub/quickstart.md @@ -1,234 +1,98 @@ -# 快速开始 +# 快速开始:安装并使用技能 -## 一键部署 +安装第一个技能,并在 Agent 中使用。本页使用已有的注册中心,不需要先部署 SkillHub 服务。 -使用 curl 命令快速部署 SkillHub(包含所有服务:Web UI、Backend API、PostgreSQL、Redis、MinIO、Skill Scanner): +## 开始前准备 + +- 一个支持技能目录的 Agent,例如 Codex 或 Claude Code。 +- Node.js 18 或更新版本,以及可用的 npm;可用 `node --version` 确认版本。 +- 一个准备使用技能的项目目录,以及能访问的 SkillHub 注册中心地址。 + +本页命令使用终端运行,`@team/example-skill` 是占位坐标,不是保证存在的公共技能。选择实际搜索结果后再替换。项目级安装前,先切换到准备让 Agent 打开的项目根目录。 + +## 1. 安装 CLI,选择注册中心 ```bash -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up -``` - -**国内用户(阿里云镜像):** -```bash -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --aliyun -``` - -**自定义参数**: -```bash -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up \ - --version v0.2.0 \ - --home /opt/skillhub \ - --aliyun -``` - -**参数说明**: -| 参数 | 说明 | 示例 | -|------|------|------| -| `--version ` | 指定版本 | `--version v0.2.0` | -| `--aliyun` | 使用阿里云镜像(国内推荐) | `--aliyun` | -| `--home ` | 指定安装目录 | `--home /opt/skillhub` | -| `--no-scanner` | 禁用安全扫描服务 | `--no-scanner` | -| `--mirror-registry ` | 自定义镜像仓库 | `--mirror-registry registry.example.com` | - -**其他命令**: -```bash -# 停止服务 -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- down - -# 查看服务状态 -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- ps - -# 查看日志 -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- logs - -# 清理所有数据 -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- clean -``` - -部署成功后访问: -- **Web UI**: http://localhost:3000 -- **Backend API**: http://localhost:8080 -- **API 文档**: http://localhost:8080/swagger-ui.html -- **Skill Scanner**: http://localhost:8000 - -## 本地开发 - -如果需要从源码启动开发环境: - -```bash -# 克隆仓库 -git clone https://github.com/iflytek/skillhub.git -cd skillhub - -# 启动所有服务(包含 Scanner) -make dev-all -``` - -### 国内开发者注意事项 - -如果 `make dev-all` 后端启动失败,常见原因: - -1. **Maven 依赖下载超时** - - 项目已内置阿里云镜像配置(`server/.mvn/settings.xml`),但 Maven 不会自动读取项目级配置。需要手动配置: - - ```bash - # 方式一:复制到用户目录(推荐) - mkdir -p ~/.m2 - cp server/.mvn/settings.xml ~/.m2/settings.xml - - # 方式二:每次构建时指定 - cd server && ./mvnw -s .mvn/settings.xml package - ``` - -2. **Java 版本不匹配** - - SkillHub 要求 Java 21+: - ```bash - java -version - ``` - -3. **端口冲突** - - 检查 8080 端口是否被占用: - ```bash - lsof -i :8080 - ``` - -详细的错误排查步骤,请查看 [常见问题](faq.md#本地开发启动失败)。 - -## 登录系统 - -### 方式一:使用内置管理员账号 - -SkillHub 内置了一个超级管理员账号,可以直接登录: - -- **用户名**:`admin` -- **密码**:`ChangeMe!2026` - -> **安全提示**:生产环境部署后,请立即修改默认密码。 - -### 方式二:注册新账号 - -访问 http://localhost:3000/register 注册新账号。 - -### 方式三:使用 Mock 用户(仅本地开发) - -本地开发时,可以使用 Mock 用户头快速登录: - -```bash -# 普通用户 -curl -H "X-Mock-User-Id: local-user" http://localhost:8080/api/v1/auth/me - -# 超级管理员 -curl -H "X-Mock-User-Id: local-admin" http://localhost:8080/api/v1/auth/me -``` - -在浏览器中,可以通过浏览器插件(如 ModHeader)添加 `X-Mock-User-Id` 请求头。 - -## 安装 CLI 工具 - -推荐使用第一方 SkillHub CLI 管理技能包: - -```bash -# 安装并配置 SkillHub 注册中心地址 npm install -g @astron-team/skillhub -export SKILLHUB_REGISTRY=http://localhost:8080 - -# 搜索技能包 -skillhub search email - -# 安装技能包 -skillhub install my-skill - -# 发布技能包 -skillhub publish ./my-skill --namespace my-team +skillhub version ``` -已有 ClawHub 工作流仍可通过兼容层进行搜索和安装;新流程及发布操作优先使用 SkillHub CLI。 - -## 发布第一个技能包 - -### 使用 CLI 工具发布(推荐) - -1. **准备技能包** - -创建一个简单的技能包目录: - -``` -my-skill/ -├── skill.md # 技能描述 -├── package.json # 元数据 -└── scripts/ # 脚本文件 - └── main.py -``` - -2. **使用 CLI 发布** +默认使用 `https://skill.xfyun.cn`。使用自托管实例时,在当前终端设置实际地址: ```bash -# 配置注册中心 -export SKILLHUB_REGISTRY=http://localhost:8080 - -# 发布到指定命名空间 -skillhub publish ./my-skill --namespace my-team +export SKILLHUB_REGISTRY=https://skillhub.example.com ``` -3. **等待安全扫描** +PowerShell 中设置注册中心使用: -发布后,Skill Scanner 会自动扫描技能包,检测潜在的安全问题: -- 恶意代码检测 -- 敏感信息泄露 -- 依赖漏洞扫描 -- 行为分析 +```powershell +$env:SKILLHUB_REGISTRY="https://skillhub.example.com" +``` -扫描结果会显示在技能包详情页。 +只想临时使用另一个实例时,可以在命令后添加 `--registry https://skillhub.example.com`。搜索、登录和安装应使用同一个注册中心;不同实例中的同名技能不是同一安装来源。 -4. **等待审核**(如果命名空间开启了审核) - -管理员会收到通知,审核通过后技能包正式发布。 - -### 使用 Web UI 发布 - -1. 访问 http://localhost:3000/dashboard/publish -2. 选择命名空间(如果没有,先创建一个) -3. 上传 zip 文件 -4. 选择可见性(PUBLIC / PRIVATE / INTERNAL) -5. 点击「发布」 - -## 搜索和下载技能包 - -### 使用 CLI 工具 +公开技能可匿名搜索和安装。发布、访问受限资源等操作需要登录: + +```bash +skillhub login +skillhub whoami +``` + +没有从命令行、环境变量或该注册中心的保存记录读取到 Token 时,CLI 会进入设备授权;按终端提示在浏览器完成登录和设备码确认。已有 Token 时先用该 Token 验证身份,不会自动重新选账号。远程终端可用 `skillhub login --no-open`。账号是否可以注册、使用哪些登录方式,由实例配置决定。 + +## 2. 找到技能并安装 ```bash -# 搜索技能包 skillhub search pdf - -# 安装技能包 -skillhub install pdf-parser - -# 安装指定命名空间的技能包 -skillhub install pdf-parser --namespace my-team ``` -### 使用 Web UI +在网页详情确认用途、版本、可见性及使用说明,然后复制真实坐标。下面的 `@team/example-skill` 是占位示例,必须替换成搜索结果中的坐标。 -1. 访问 http://localhost:3000/search -2. 输入关键词搜索 -3. 点击技能包查看详情 -4. 点击「下载」或复制安装命令 - -## 升级 SkillHub - -使用 curl 命令升级到最新版本: +在目标项目根目录执行: ```bash -# 升级到最新版本 -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- pull -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- down -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up - -# 升级到指定版本 -curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- up --version v0.2.0 +skillhub install @team/example-skill --scope project --agent codex +skillhub list --agent codex ``` -> **注意**:升级前建议备份数据库和对象存储。 +Claude Code 用户改用 `--agent claude-code`。希望多个项目共用时,使用 `--scope user`。 +项目级 Codex 安装目录为 `.codex/skills//`,Claude Code 为 `.claude/skills//`;用户级路径位于用户主目录。 + +### 确认安装到了哪里 + +查看安装命令输出的目标路径,再查看 `skillhub list --agent codex` 的记录:坐标、版本、Agent、目录和状态应符合刚才选择的目标。`list` 按当前注册中心过滤;切换注册中心后列表变化不代表本地文件被删除。 + +状态 `missing` 表示记录对应的目录不存在;`ok` 只表示目录存在,不代表 Agent 已加载或技能已执行成功。进入实际目录检查 `SKILL.md`,再继续下一步。 + +## 3. 在 Agent 中使用 + +安装完成后,在目标 Agent 中打开项目,必要时新建会话或重新加载技能。先确认 Agent 能发现该技能,再提出具体任务,例如: + +> 请使用 example-skill,按它的说明处理以下材料:…… + +实际调用名称以技能 `SKILL.md` 中的 `name` 和 Agent 显示结果为准。安装不会自动执行技能,也不会代为配置成员所需的工具或凭据。 +如果 Agent 没发现技能,检查 CLI 输出路径、当前项目、安装范围和目标 Agent,参见 [FAQ](./faq.md)。 + +整套安装使用 `skillhub suite install`,之后从套装的入口技能开始;详见 [技能套装使用指南](./guide/skill-suites.md)。 + +## 4. 更新和管理 + +```bash +skillhub upgrade @team/example-skill --check +skillhub upgrade @team/example-skill +``` + +检查计划后再更新。保留需要的本地修改;不要把 `--force` 当作默认参数。卸载、同步团队工作区和完整命令说明见 [CLI 指南](./guide/cli.md)。 + +## 常见问题与处理 + +| 现象 | 先检查什么 | 下一步 | +| --- | --- | --- | +| 搜索不到目标技能 | 当前注册中心、拼写、登录身份和资源可见性 | 在网页确认坐标和版本是否已发布,见[搜索与安装](./guide/skill-discovery.md) | +| 安装时报同名目录冲突 | 输出的目标目录是否来自另一来源或包含自己的文件 | 先保留所需内容,不直接使用 `--force` 覆盖未知目录,见[CLI 参考](./guide/cli.md) | +| 安装成功但 Agent 看不到 | Agent 类型、项目根目录、user/project 范围 | 对照安装输出路径,按 Agent 的发现方式重载或重开会话 | +| Agent 已加载但执行失败 | 技能说明所需的工具、输入和凭据 | 按 `SKILL.md` 配置运行环境;注册中心不会代为执行这些步骤 | + +## 下一步 + +需要配套技能时,阅读[技能套装](./guide/skill-suites.md);需要更多命令时,查阅 [CLI 指南](./guide/cli.md)。发布技能、管理团队、自托管和源码开发,请从[文档导航](./guide/index.md)选择对应任务。