From ddda14b3e64aac04ba3f554639b3612bf4f7b7da Mon Sep 17 00:00:00 2001 From: FenjuFu <92919259+FenjuFu@users.noreply.github.com> Date: Thu, 23 Jul 2026 12:23:22 +0800 Subject: [PATCH] docs: publish SkillHub website --- document/.gitignore | 2 + document/README.md | 40 + .../docs/01-getting-started/_category_.json | 4 +- document/docs/01-getting-started/overview.md | 98 +- .../docs/01-getting-started/quick-start.md | 70 +- document/docs/01-getting-started/use-cases.md | 100 +-- .../docs/02-administration/_category_.json | 4 +- .../deployment/_category_.json | 2 +- .../deployment/configuration.md | 86 +- .../deployment/kubernetes.md | 46 +- .../deployment/single-machine.md | 58 +- .../governance/_category_.json | 2 +- .../governance/namespaces.md | 72 +- .../governance/review-workflow.md | 56 +- .../governance/user-management.md | 62 +- .../security/_category_.json | 2 +- .../02-administration/security/audit-logs.md | 48 +- .../security/authentication.md | 30 +- .../security/authorization.md | 79 +- .../02-administration/security/scanner.md | 104 +++ document/docs/03-user-guide/_category_.json | 4 +- .../collaboration/_category_.json | 2 +- .../03-user-guide/collaboration/namespaces.md | 48 +- .../03-user-guide/collaboration/promotion.md | 54 +- .../03-user-guide/discovery/_category_.json | 2 +- .../docs/03-user-guide/discovery/install.md | 40 +- .../docs/03-user-guide/discovery/ratings.md | 34 +- .../docs/03-user-guide/discovery/search.md | 48 +- .../03-user-guide/publishing/_category_.json | 2 +- .../03-user-guide/publishing/create-skill.md | 58 +- .../docs/03-user-guide/publishing/publish.md | 58 +- .../03-user-guide/publishing/versioning.md | 54 +- document/docs/04-developer/_category_.json | 4 +- .../docs/04-developer/api/_category_.json | 2 +- .../docs/04-developer/api/authenticated.md | 32 +- document/docs/04-developer/api/cli-compat.md | 58 +- document/docs/04-developer/api/overview.md | 64 +- document/docs/04-developer/api/public.md | 36 +- .../04-developer/architecture/_category_.json | 2 +- .../04-developer/architecture/domain-model.md | 98 +- .../04-developer/architecture/overview.md | 52 +- .../04-developer/architecture/security.md | 90 +- .../docs/04-developer/plugins/_category_.json | 2 +- .../04-developer/plugins/skill-protocol.md | 66 +- .../docs/04-developer/plugins/storage-spi.md | 57 +- document/docs/05-reference/_category_.json | 4 +- document/docs/05-reference/changelog.md | 20 +- document/docs/05-reference/faq.md | 52 +- document/docs/05-reference/roadmap.md | 58 +- document/docs/05-reference/troubleshooting.md | 78 +- document/docs/index.md | 103 +-- document/docusaurus.config.js | 123 ++- .../security/authorization.md | 2 +- .../02-administration/security/scanner.md | 104 +++ .../04-developer/plugins/storage-spi.md | 23 - .../current/index.md | 156 ++-- document/i18n/zh-CN/code.json | 521 +++++++++++ .../options.json | 14 + .../current.json | 62 ++ .../01-getting-started/_category_.json | 8 + .../current/01-getting-started/overview.md | 70 ++ .../current/01-getting-started/quick-start.md | 85 ++ .../current/01-getting-started/use-cases.md | 72 ++ .../current/02-administration/_category_.json | 8 + .../deployment/_category_.json | 4 + .../deployment/configuration.md | 69 ++ .../deployment/kubernetes.md | 54 ++ .../deployment/single-machine.md | 65 ++ .../governance/_category_.json | 4 + .../governance/namespaces.md | 56 ++ .../governance/review-workflow.md | 44 + .../governance/user-management.md | 61 ++ .../security/_category_.json | 4 + .../02-administration/security/audit-logs.md | 38 + .../security/authentication.md | 36 + .../security/authorization.md | 63 ++ .../02-administration/security/scanner.md | 104 +++ .../current/03-user-guide/_category_.json | 8 + .../collaboration/_category_.json | 4 + .../03-user-guide/collaboration/namespaces.md | 41 + .../03-user-guide/collaboration/promotion.md | 42 + .../03-user-guide/discovery/_category_.json | 4 + .../03-user-guide/discovery/install.md | 53 ++ .../03-user-guide/discovery/ratings.md | 30 + .../current/03-user-guide/discovery/search.md | 36 + .../03-user-guide/publishing/_category_.json | 4 + .../03-user-guide/publishing/create-skill.md | 56 ++ .../03-user-guide/publishing/publish.md | 50 ++ .../03-user-guide/publishing/versioning.md | 56 ++ .../current/04-developer/_category_.json | 8 + .../current/04-developer/api/_category_.json | 4 + .../current/04-developer/api/authenticated.md | 101 +++ .../current/04-developer/api/cli-compat.md | 159 ++++ .../current/04-developer/api/overview.md | 86 ++ .../current/04-developer/api/public.md | 72 ++ .../04-developer/architecture/_category_.json | 4 + .../04-developer/architecture/domain-model.md | 77 ++ .../04-developer/architecture/overview.md | 69 ++ .../04-developer/architecture/security.md | 71 ++ .../04-developer/plugins/_category_.json | 4 + .../04-developer/plugins/skill-protocol.md | 68 ++ .../04-developer/plugins/storage-spi.md | 54 ++ .../current/05-reference/_category_.json | 8 + .../current/05-reference/changelog.md | 20 + .../current/05-reference/faq.md | 49 + .../current/05-reference/roadmap.md | 45 + .../current/05-reference/troubleshooting.md | 63 ++ .../current/index.md | 22 + .../docusaurus-theme-classic/footer.json | 30 + .../docusaurus-theme-classic/navbar.json | 26 + document/package.json | 1 + document/sidebars.js | 29 +- document/src/css/custom.css | 841 +++++++++++++++--- document/src/pages/index.js | 349 ++++++++ document/static/CNAME | 1 + document/static/img/astron-skillhub-logo.svg | 32 + 116 files changed, 5432 insertions(+), 1342 deletions(-) create mode 100644 document/README.md create mode 100644 document/docs/02-administration/security/scanner.md create mode 100644 document/i18n/en/docusaurus-plugin-content-docs/current/02-administration/security/scanner.md create mode 100644 document/i18n/zh-CN/code.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-blog/options.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/_category_.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/overview.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/quick-start.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/use-cases.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/_category_.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/_category_.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/configuration.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/kubernetes.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/single-machine.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/_category_.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/namespaces.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/review-workflow.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/user-management.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/_category_.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/audit-logs.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/authentication.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/authorization.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/scanner.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/_category_.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/collaboration/_category_.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/collaboration/namespaces.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/collaboration/promotion.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/_category_.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/install.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/ratings.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/search.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/_category_.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/create-skill.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/publish.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/versioning.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/_category_.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/_category_.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/authenticated.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/cli-compat.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/overview.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/public.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/_category_.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/domain-model.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/overview.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/security.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/plugins/_category_.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/plugins/skill-protocol.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/plugins/storage-spi.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/_category_.json create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/changelog.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/faq.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/roadmap.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/troubleshooting.md create mode 100644 document/i18n/zh-CN/docusaurus-plugin-content-docs/current/index.md create mode 100644 document/i18n/zh-CN/docusaurus-theme-classic/footer.json create mode 100644 document/i18n/zh-CN/docusaurus-theme-classic/navbar.json create mode 100644 document/src/pages/index.js create mode 100644 document/static/CNAME create mode 100644 document/static/img/astron-skillhub-logo.svg diff --git a/document/.gitignore b/document/.gitignore index cfefc1a9..39ac7052 100644 --- a/document/.gitignore +++ b/document/.gitignore @@ -18,3 +18,5 @@ build .vscode *.swp *.swo + +.vercel diff --git a/document/README.md b/document/README.md new file mode 100644 index 00000000..845bfd85 --- /dev/null +++ b/document/README.md @@ -0,0 +1,40 @@ +# SkillHub Docs Site + +`document/` contains the Docusaurus source for the public documentation site served at `https://www.astron-skillhub.org/`. + +## Local Development + +Install dependencies: + +```bash +cd document +npm install +``` + +Start the docs dev server: + +```bash +npm run start +``` + +Build the production site: + +```bash +npm run build +``` + +## Publishing + +The repository includes a GitHub Actions workflow at `.github/workflows/publish-docs-site.yml`. + +- Pushes to `main` that modify `document/**` or the workflow file trigger an automatic docs build and GitHub Pages deployment +- The custom domain is configured through `document/static/CNAME` +- Legacy website URLs such as `quickstart.html` and `guide/skill-publish.html` are redirected to the current Docusaurus routes via `plugin-client-redirects` + +## Sync Rule + +To keep `https://www.astron-skillhub.org/` aligned with the latest repository content: + +- Treat `document/` as the source of truth for the public docs site +- Update `document/docs/**` whenever product messaging or public-facing workflow documentation changes materially +- Keep redirects updated when replacing or renaming public routes diff --git a/document/docs/01-getting-started/_category_.json b/document/docs/01-getting-started/_category_.json index 42cea88c..dacce6aa 100644 --- a/document/docs/01-getting-started/_category_.json +++ b/document/docs/01-getting-started/_category_.json @@ -1,8 +1,8 @@ { - "label": "快速入门", + "label": "Getting Started", "position": 1, "link": { "type": "generated-index", - "description": "快速了解并开始使用 SkillHub" + "description": "Quickly understand and start using SkillHub" } } diff --git a/document/docs/01-getting-started/overview.md b/document/docs/01-getting-started/overview.md index 19df6539..9bb1e577 100644 --- a/document/docs/01-getting-started/overview.md +++ b/document/docs/01-getting-started/overview.md @@ -1,70 +1,70 @@ --- -title: 产品概述 +title: Overview sidebar_position: 1 -description: SkillHub 产品概述和核心特性介绍 +description: SkillHub product overview and core features --- -# 产品概述 +# Overview -SkillHub 是企业级 AI 技能注册平台，支持技能发布、发现与管理，采用自托管架构保障数据安全。 +SkillHub is an enterprise-grade AI skill registry platform for publishing, discovering, and managing skills with a self-hosted architecture ensuring data security. -## 核心特性 +## Core Features -### 发布管理 -- 版本控制与语义化版本（Semantic Versioning） -- 自定义标签（如 `beta`/`stable`） -- `latest` 标签自动跟随最新发布版本 +### Publishing Management +- Version control and Semantic Versioning +- Custom tags (like `beta`/`stable`) +- `latest` tag automatically follows the latest published version -### 发现机制 -- 全文搜索 -- 多维度筛选（命名空间、下载量、评分） -- 可见性控制（公开/命名空间内/私有） +### Discovery +- Full-text search +- Multi-dimensional filtering (namespace, downloads, ratings) +- Visibility control -### 组织架构 -- 命名空间隔离 -- 基于角色的访问控制（RBAC） -- 团队与全局双层空间 +### Organization +- Namespace isolation +- Role-based access control (RBAC) +- Team and global two-tier scopes -### 治理体系 -- 双层审核流程 -- 审计日志 -- 权限分离 +### Governance +- Two-tier review workflow +- Audit logs +- Permission separation -### 存储与部署 -- 支持 S3/MinIO/本地存储 -- Docker/Kubernetes 部署 -- 企业级可观测性 +### Storage and Deployment +- S3/MinIO/Local storage support +- Docker/Kubernetes deployment +- Enterprise-grade observability -## 技术栈 +## Tech Stack -### 后端 -- **Java 21** - 运行时 -- **Spring Boot 3.2.3** - 应用框架 -- **PostgreSQL 16.x** - 主数据库 + 全文搜索 -- **Redis 7.x** - 缓存与会话存储 +### Backend +- **Java 21** - Runtime +- **Spring Boot 3.2.3** - Application framework +- **PostgreSQL 16.x** - Primary database + full-text search +- **Redis 7.x** - Cache and session storage -### 前端 -- **React 19** - UI 框架 -- **TypeScript** - 类型安全 -- **Vite** - 构建工具 -- **Tailwind CSS** - 样式框架 +### Frontend +- **React 19** - UI framework +- **TypeScript** - Type safety +- **Vite** - Build tool +- **Tailwind CSS** - Styling framework -### 部署 -- **Docker Compose** - 单机部署 -- **Kubernetes** - 生产环境编排 +### Deployment +- **Docker Compose** - Single-machine deployment +- **Kubernetes** - Production orchestration -## 核心概念 +## Core Concepts -### 命名空间 -技能隔离边界，支持 `@global`（全局）和 `@team-*`（团队）前缀。 +### Namespace +Skill isolation boundary, supporting `@global` (global) and `@team-*` (team) prefixes. -### 坐标系统 -技能标识格式为 `@{namespace_slug}/{skill_slug}`，支持语义化版本。 +### Coordinate System +Skill identifier format: `@{namespace_slug}/{skill_slug}`, supports semantic versioning. -### 兼容性 -提供 REST API 和 ClawHub 兼容层，支持现有工具集成。 +### Compatibility +Provides REST API and ClawHub compatibility layer for existing tool integration. -## 下一步 +## Next Steps -- [快速开始](./quick-start) - 一键启动体验 -- [典型应用场景](./use-cases) - 了解如何在企业中应用 +- [Quick Start](./quick-start) - One-click startup experience +- [Use Cases](./use-cases) - Explore enterprise application scenarios diff --git a/document/docs/01-getting-started/quick-start.md b/document/docs/01-getting-started/quick-start.md index 37e100b0..2b8a2eb1 100644 --- a/document/docs/01-getting-started/quick-start.md +++ b/document/docs/01-getting-started/quick-start.md @@ -1,20 +1,20 @@ --- -title: 快速开始 +title: Quick Start sidebar_position: 2 -description: 一键启动 SkillHub 开发环境 +description: One-click startup of SkillHub development environment --- -# 快速开始 +# Quick Start -## 一键启动 +## One-click Startup -使用以下命令一键启动完整的 SkillHub 环境： +Use the following command to start a complete SkillHub environment with one command: ```bash curl -fsSL https://raw.githubusercontent.com/iflytek/skillhub/main/scripts/runtime.sh | sh -s -- up ``` -或者克隆仓库后手动启动： +Or clone the repository and start manually: ```bash git clone https://github.com/iflytek/skillhub.git @@ -22,64 +22,64 @@ cd skillhub make dev-all ``` -## 默认账号 +## Default Account -两种启动方式都会默认创建一个 bootstrap 管理员账号： +Both startup methods create a bootstrap admin account by default: -- 用户名：`admin` -- 密码：`ChangeMe!2026` +- username: `admin` +- password: `ChangeMe!2026` -### `curl` 一键部署 +### `curl` One-click Deployment -| 服务 | 地址 | -|------|------| +| Service | Address | +|---------|---------| | Web UI | http://localhost | | Backend API | http://localhost:8080 | -使用上述默认账号密码登录即可。**生产环境请务必修改密码。** +Log in with the default credentials above. **Change the password for production.** -### `make dev-all` 本地开发 +### `make dev-all` Local Development -| 服务 | 地址 | -|------|------| +| Service | Address | +|---------|---------| | Web UI | http://localhost:3000 | | Backend API | http://localhost:8080 | | MinIO Console | http://localhost:9001 | -除了上述 bootstrap 管理员，本地开发还预置两个模拟用户（无需密码）： +In addition to the bootstrap admin, local development includes two mock users (no password needed): -| 用户 | 角色 | 说明 | -|------|------|------| -| `local-user` | 普通用户 | 可发布技能、管理命名空间 | -| `local-admin` | 超级管理员 | 拥有所有权限，包括审核和用户管理 | +| User | Role | Description | +|------|------|-------------| +| `local-user` | Regular user | Can publish skills, manage namespaces | +| `local-admin` | Super admin | Has all permissions including review and user management | -使用 `X-Mock-User-Id` 请求头切换模拟用户。 -如需关闭 bootstrap 管理员，启动前设置 `BOOTSTRAP_ADMIN_ENABLED=false`。 +Use the `X-Mock-User-Id` request header to switch mock users. +To disable the bootstrap admin, set `BOOTSTRAP_ADMIN_ENABLED=false` before starting. -## 常用命令 +## Common Commands ```bash -# 启动完整开发环境 +# Start complete development environment make dev-all -# 停止所有服务 +# Stop all services make dev-all-down -# 重置并重新启动 +# Reset and restart make dev-all-reset -# 仅启动后端 +# Start backend only make dev -# 仅启动前端 +# Start frontend only make dev-web -# 查看所有可用命令 +# View all available commands make help ``` -## 下一步 +## Next Steps -- [产品概述](./overview) - 深入了解产品特性 -- [典型应用场景](./use-cases) - 探索企业应用场景 -- [单机部署](../administration/deployment/single-machine) - 生产环境部署指南 +- [Overview](./overview) - Deep dive into product features +- [Use Cases](./use-cases) - Explore enterprise application scenarios +- [Single Machine Deployment](../administration/deployment/single-machine) - Production deployment guide diff --git a/document/docs/01-getting-started/use-cases.md b/document/docs/01-getting-started/use-cases.md index aab236c6..1611fac5 100644 --- a/document/docs/01-getting-started/use-cases.md +++ b/document/docs/01-getting-started/use-cases.md @@ -1,72 +1,72 @@ --- -title: 典型应用场景 +title: Use Cases sidebar_position: 3 -description: SkillHub 在企业中的典型应用场景 +description: Typical enterprise application scenarios for SkillHub --- -# 典型应用场景 +# Use Cases -## 企业内部技能共享 +## Internal Skill Sharing -**场景描述**：企业内部多个团队开发 AI 技能，需要一个集中的平台进行共享和复用。 +**Scenario**: Multiple teams within an enterprise develop AI skills and need a centralized platform for sharing and reuse. -**解决方案**： -- 各团队创建自己的命名空间 -- 技能在团队内先审核发布 -- 优秀技能可申请提升到全局空间 -- 所有操作有完整审计记录 +**Solution**: +- Each team creates their own namespace +- Skills are reviewed and published within the team first +- Excellent skills can be promoted to the global space +- Complete audit records for all operations -**价值**： -- 避免重复开发 -- 促进最佳实践传播 -- 保障质量可控 +**Value**: +- Avoid duplicate development +- Promote best practice sharing +- Ensure quality control -## AI 技能治理与合规 +## AI Skill Governance and Compliance -**场景描述**：金融、政务等行业对 AI 应用有严格的合规要求，需要完整的审核和审计机制。 +**Scenario**: Industries such as finance and government have strict compliance requirements for AI applications, requiring complete review and audit mechanisms. -**解决方案**： -- 双层审核流程（团队审核 + 平台审核） -- 细粒度 RBAC 权限控制 -- 完整的操作审计日志 -- 技能版本可追溯、可撤回 +**Solution**: +- Two-tier review workflow (team review + platform review) +- Fine-grained RBAC permission control +- Complete operation audit logs +- Skill version traceability and withdrawability -**价值**： -- 满足合规要求 -- 风险可控 -- 责任可追溯 +**Value**: +- Meet compliance requirements +- Controllable risks +- Traceable responsibilities -## 多团队协作开发 +## Multi-team Collaborative Development -**场景描述**：大型组织中多个团队协作开发，需要清晰的权限边界和协作机制。 +**Scenario**: Large organizations with multiple teams collaborating need clear permission boundaries and collaboration mechanisms. -**解决方案**： -- 命名空间隔离，团队自治 -- 命名空间成员角色管理 -- 技能可见性控制（公开/命名空间内/私有） -- 团队技能可申请提升到全局 +**Solution**: +- Namespace isolation, team autonomy +- Namespace member role management +- Skill visibility control (public/namespace-only/private) +- Team skills can apply for promotion to global -**价值**： -- 权责清晰 -- 协作高效 -- 安全可控 +**Value**: +- Clear responsibilities +- Efficient collaboration +- Controllable security -## CLI 工具集成 +## CLI Tool Integration -**场景描述**：已有使用 ClawHub CLI 的工作流，希望无缝迁移到 SkillHub。 +**Scenario**: Existing workflows using ClawHub CLI want to seamlessly migrate to SkillHub. -**解决方案**： -- 提供 ClawHub CLI 协议兼容层 -- 通过 `/.well-known/clawhub.json` 自动发现 -- 现有 CLI 工具无需修改即可使用 -- 同时提供 SkillHub 自有 CLI 增强功能 +**Solution**: +- Provide ClawHub CLI protocol compatibility layer +- Auto-discovery via `/.well-known/clawhub.json` +- Existing CLI tools work without modification +- Also provide SkillHub-native CLI enhanced features -**价值**： -- 保护现有投资 -- 迁移成本低 -- 渐进式升级 +**Value**: +- Protect existing investments +- Low migration cost +- Gradual upgrade -## 下一步 +## Next Steps -- [单机部署](../administration/deployment/single-machine) - 开始部署 -- [命名空间管理](../administration/governance/namespaces) - 了解组织治理 +- [Single Machine Deployment](../administration/deployment/single-machine) - Start deployment +- [Namespace Management](../administration/governance/namespaces) - Learn about organization governance diff --git a/document/docs/02-administration/_category_.json b/document/docs/02-administration/_category_.json index 9e9be7e5..547b92e0 100644 --- a/document/docs/02-administration/_category_.json +++ b/document/docs/02-administration/_category_.json @@ -1,8 +1,8 @@ { - "label": "管理员指南", + "label": "Administration Guide", "position": 2, "link": { "type": "generated-index", - "description": "部署、配置和管理 SkillHub" + "description": "Deploy, configure, and manage SkillHub" } } diff --git a/document/docs/02-administration/deployment/_category_.json b/document/docs/02-administration/deployment/_category_.json index 1b21d412..bcb5bc84 100644 --- a/document/docs/02-administration/deployment/_category_.json +++ b/document/docs/02-administration/deployment/_category_.json @@ -1,4 +1,4 @@ { - "label": "部署指南", + "label": "Deployment Guide", "position": 1 } diff --git a/document/docs/02-administration/deployment/configuration.md b/document/docs/02-administration/deployment/configuration.md index f04387bb..68055f24 100644 --- a/document/docs/02-administration/deployment/configuration.md +++ b/document/docs/02-administration/deployment/configuration.md @@ -1,69 +1,69 @@ --- -title: 配置说明 +title: Configuration Reference sidebar_position: 3 -description: SkillHub 配置项详细说明 +description: Detailed SkillHub configuration reference --- -# 配置说明 +# Configuration Reference -## 环境变量 +## Environment Variables -SkillHub 通过环境变量进行配置，主要配置项如下： +SkillHub is configured through environment variables. The main configuration items are listed below: -### 基础配置 +### Basic Configuration -| 环境变量 | 说明 | 默认值 | -|---------|------|--------| -| `SKILLHUB_PUBLIC_BASE_URL` | 公网访问地址 | - | -| `SKILLHUB_VERSION` | 镜像版本 | `edge` | +| Environment Variable | Description | Default Value | +|---------------------|-------------|---------------| +| `SKILLHUB_PUBLIC_BASE_URL` | Public access URL | - | +| `SKILLHUB_VERSION` | Image version | `edge` | -### 数据库配置 +### Database Configuration -| 环境变量 | 说明 | 默认值 | -|---------|------|--------| -| `POSTGRES_HOST` | PostgreSQL 主机 | `postgres` | -| `POSTGRES_PORT` | PostgreSQL 端口 | `5432` | -| `POSTGRES_DB` | 数据库名 | `skillhub` | -| `POSTGRES_USER` | 数据库用户 | `skillhub` | -| `POSTGRES_PASSWORD` | 数据库密码 | - | +| Environment Variable | Description | Default Value | +|---------------------|-------------|---------------| +| `POSTGRES_HOST` | PostgreSQL host | `postgres` | +| `POSTGRES_PORT` | PostgreSQL port | `5432` | +| `POSTGRES_DB` | Database name | `skillhub` | +| `POSTGRES_USER` | Database user | `skillhub` | +| `POSTGRES_PASSWORD` | Database password | - | -### Redis 配置 +### Redis Configuration -| 环境变量 | 说明 | 默认值 | -|---------|------|--------| -| `REDIS_HOST` | Redis 主机 | `redis` | -| `REDIS_PORT` | Redis 端口 | `6379` | -| `REDIS_PASSWORD` | Redis 密码 | - | +| Environment Variable | Description | Default Value | +|---------------------|-------------|---------------| +| `REDIS_HOST` | Redis host | `redis` | +| `REDIS_PORT` | Redis port | `6379` | +| `REDIS_PASSWORD` | Redis password | - | -### 存储配置 +### Storage Configuration -| 环境变量 | 说明 | 默认值 | -|---------|------|--------| -| `SKILLHUB_STORAGE_PROVIDER` | 存储提供方 | `local` | -| `SKILLHUB_STORAGE_S3_ENDPOINT` | S3 端点 | - | -| `SKILLHUB_STORAGE_S3_BUCKET` | S3 桶名 | - | +| Environment Variable | Description | Default Value | +|---------------------|-------------|---------------| +| `SKILLHUB_STORAGE_PROVIDER` | Storage provider | `local` | +| `SKILLHUB_STORAGE_S3_ENDPOINT` | S3 endpoint | - | +| `SKILLHUB_STORAGE_S3_BUCKET` | S3 bucket name | - | | `SKILLHUB_STORAGE_S3_ACCESS_KEY` | S3 Access Key | - | | `SKILLHUB_STORAGE_S3_SECRET_KEY` | S3 Secret Key | - | -### OAuth 配置 +### OAuth Configuration -| 环境变量 | 说明 | 默认值 | -|---------|------|--------| +| Environment Variable | Description | Default Value | +|---------------------|-------------|---------------| | `OAUTH2_GITHUB_CLIENT_ID` | GitHub OAuth Client ID | - | | `OAUTH2_GITHUB_CLIENT_SECRET` | GitHub OAuth Client Secret | - | -### 首登管理员配置 +### Bootstrap Admin Configuration -| 环境变量 | 说明 | 默认值 | -|---------|------|--------| -| `BOOTSTRAP_ADMIN_ENABLED` | 是否启用首登管理员 | `true` | -| `BOOTSTRAP_ADMIN_USERNAME` | 首登管理员用户名 | `admin` | -| `BOOTSTRAP_ADMIN_PASSWORD` | 首登管理员密码 | `ChangeMe!2026` | +| Environment Variable | Description | Default Value | +|---------------------|-------------|---------------| +| `BOOTSTRAP_ADMIN_ENABLED` | Enable bootstrap admin | `true` | +| `BOOTSTRAP_ADMIN_USERNAME` | Bootstrap admin username | `admin` | +| `BOOTSTRAP_ADMIN_PASSWORD` | Bootstrap admin password | `ChangeMe!2026` | -## 配置文件 +## Configuration Files -Spring Boot 配置文件位于 `server/skillhub-app/src/main/resources/`。 +Spring Boot configuration files are located at `server/skillhub-app/src/main/resources/`. -## 下一步 +## Next Steps -- [认证配置](../security/authentication) - 配置身份认证 +- [Authentication Configuration](../security/authentication) - Configure authentication diff --git a/document/docs/02-administration/deployment/kubernetes.md b/document/docs/02-administration/deployment/kubernetes.md index a231a428..92941020 100644 --- a/document/docs/02-administration/deployment/kubernetes.md +++ b/document/docs/02-administration/deployment/kubernetes.md @@ -1,54 +1,54 @@ --- -title: Kubernetes 部署 +title: Kubernetes Deployment sidebar_position: 2 -description: 在 Kubernetes 集群中部署 SkillHub +description: Deploy SkillHub in a Kubernetes cluster --- -# Kubernetes 部署 +# Kubernetes Deployment -本文介绍如何在 Kubernetes 集群中部署 SkillHub。 +This guide describes how to deploy SkillHub in a Kubernetes cluster. -## 前置要求 +## Prerequisites - Kubernetes 1.24+ -- kubectl 配置完成 -- Helm 3.0+（可选） -- 可用的持久化存储类 +- kubectl configured +- Helm 3.0+ (optional) +- Available persistent storage class -## 部署清单 +## Deployment Manifests -项目提供了 Kubernetes 部署清单： +Kubernetes deployment manifests are provided in the project: ```bash cd deploy/k8s -# 1. 创建命名空间 +# 1. Create namespace kubectl create namespace skillhub -# 2. 配置 Secret +# 2. Configure Secret cp secret.yaml.example secret.yaml -# 编辑 secret.yaml 填入真实凭证 +# Edit secret.yaml and fill in real credentials -# 3. 应用配置 +# 3. Apply configuration kubectl apply -f configmap.yaml kubectl apply -f secret.yaml -# 4. 部署服务 +# 4. Deploy services kubectl apply -f backend-deployment.yaml kubectl apply -f frontend-deployment.yaml kubectl apply -f services.yaml -# 5. 配置 Ingress +# 5. Configure Ingress kubectl apply -f ingress.yaml ``` -## 高可用配置 +## High Availability Configuration -- 后端和前端建议至少部署 2 个副本 -- PostgreSQL 使用主从复制 -- Redis 使用 Sentinel 或 Cluster 模式 -- 存储使用高可用对象存储（如 MinIO 集群或云厂商 OSS） +- Deploy at least 2 replicas for backend and frontend +- Use PostgreSQL with primary-replica replication +- Use Redis with Sentinel or Cluster mode +- Use highly available object storage (like MinIO cluster or cloud provider OSS) -## 下一步 +## Next Steps -- [配置说明](./configuration) - 详细配置项说明 +- [Configuration](./configuration) - Detailed configuration reference diff --git a/document/docs/02-administration/deployment/single-machine.md b/document/docs/02-administration/deployment/single-machine.md index 8673a8fd..711156b4 100644 --- a/document/docs/02-administration/deployment/single-machine.md +++ b/document/docs/02-administration/deployment/single-machine.md @@ -1,65 +1,65 @@ --- -title: 单机部署 +title: Single Machine Deployment sidebar_position: 1 -description: 使用 Docker Compose 单机部署 SkillHub +description: Deploy SkillHub using Docker Compose on a single machine --- -# 单机部署 +# Single Machine Deployment -本文介绍如何使用 Docker Compose 在单台服务器上部署 SkillHub。 +This guide describes how to deploy SkillHub on a single server using Docker Compose. -## 前置要求 +## Prerequisites - Docker Engine 20.10+ - Docker Compose Plugin 2.0+ -- 至少 4GB 可用内存 -- 至少 20GB 可用磁盘空间 +- At least 4GB available RAM +- At least 20GB available disk space -## 快速部署 +## Quick Deployment ```bash -# 1. 克隆仓库 +# 1. Clone the repository git clone https://github.com/iflytek/skillhub.git cd skillhub -# 2. 复制环境变量模板 +# 2. Copy environment variable template cp .env.release.example .env.release -# 3. 编辑配置 -# 修改 .env.release 中的配置项，特别是密码和公网地址 +# 3. Edit configuration +# Modify configuration items in .env.release, especially passwords and public URLs -# 4. 验证配置 +# 4. Validate configuration make validate-release-config -# 5. 启动服务 +# 5. Start services docker compose --env-file .env.release -f compose.release.yml up -d ``` -## 配置说明 +## Configuration -详见 [配置说明](./configuration) 文档。 +See [Configuration](./configuration) documentation for details. -## 验证部署 +## Verify Deployment ```bash -# 检查容器状态 +# Check container status docker compose --env-file .env.release -f compose.release.yml ps -# 检查后端健康状态 +# Check backend health curl -i http://127.0.0.1:8080/actuator/health -# 访问 Web UI -# 浏览器打开 http://localhost（或配置的公网地址） +# Access Web UI +# Open http://localhost in browser (or configured public URL) ``` -## 首登配置 +## First Login Configuration -1. 使用 `BOOTSTRAP_ADMIN_USERNAME` 和 `BOOTSTRAP_ADMIN_PASSWORD` 登录（默认 `admin` / `ChangeMe!2026`） -2. 立即修改管理员密码 -3. 配置企业 SSO（可选） -4. 创建团队命名空间 +1. Login with `BOOTSTRAP_ADMIN_USERNAME` and `BOOTSTRAP_ADMIN_PASSWORD` (default `admin` / `ChangeMe!2026`) +2. Change admin password immediately +3. Configure enterprise SSO (optional) +4. Create team namespaces -## 下一步 +## Next Steps -- [配置说明](./configuration) - 详细配置项说明 -- [Kubernetes 部署](./kubernetes) - 高可用部署 +- [Configuration](./configuration) - Detailed configuration reference +- [Kubernetes Deployment](./kubernetes) - High availability deployment diff --git a/document/docs/02-administration/governance/_category_.json b/document/docs/02-administration/governance/_category_.json index f440e0fc..dec466fb 100644 --- a/document/docs/02-administration/governance/_category_.json +++ b/document/docs/02-administration/governance/_category_.json @@ -1,4 +1,4 @@ { - "label": "治理与运营", + "label": "Governance & Operations", "position": 3 } diff --git a/document/docs/02-administration/governance/namespaces.md b/document/docs/02-administration/governance/namespaces.md index 2d7f92b4..ccc4b471 100644 --- a/document/docs/02-administration/governance/namespaces.md +++ b/document/docs/02-administration/governance/namespaces.md @@ -1,56 +1,56 @@ --- -title: 命名空间管理 +title: Namespace Management sidebar_position: 1 -description: 命名空间创建与管理 +description: Namespace creation and management --- -# 命名空间管理 +# Namespace Management -命名空间是 SkillHub 中技能的隔离边界和协作单元。 +Namespaces are the isolation boundary and collaboration unit for skills in SkillHub. -## 命名空间类型 +## Namespace Types -| 类型 | 前缀 | 说明 | -|------|------|------| -| 全局 | `@global` | 平台级公共空间，由平台管理员管理 | -| 团队 | `@team-*` | 团队/部门空间，由团队管理员管理 | +| Type | Prefix | Description | +|------|--------|-------------| +| Global | `@global` | Platform-level public space, managed by platform admins | +| Team | `@team-*` | Team/department space, managed by team admins | -## 创建命名空间 +## Create Namespace -1. 登录后进入"我的命名空间" -2. 点击"创建命名空间" -3. 填写信息： - - 标识（slug）：URL 友好名称 - - 显示名：展示名称 - - 描述：空间用途说明 -4. 提交创建 +1. After login, go to "My Namespaces" +2. Click "Create Namespace" +3. Fill in information: + - Slug: URL-friendly name + - Display name: Display name + - Description: Space purpose description +4. Submit creation -## 命名空间成员管理 +## Namespace Member Management -### 添加成员 +### Add Member -1. 进入命名空间设置 -2. 进入"成员管理" -3. 输入用户名搜索 -4. 选择角色（OWNER/ADMIN/MEMBER） -5. 确认添加 +1. Go to namespace settings +2. Go to "Member Management" +3. Enter username to search +4. Select role (OWNER/ADMIN/MEMBER) +5. Confirm addition -### 角色变更 +### Role Change -命名空间 OWNER 或 ADMIN 可变更成员角色。 +Namespace OWNER or ADMIN can change member roles. -### 移除成员 +### Remove Member -命名空间 OWNER 或 ADMIN 可移除成员。 +Namespace OWNER or ADMIN can remove members. -## 命名空间状态 +## Namespace Status -| 状态 | 说明 | -|------|------| -| `ACTIVE` | 正常使用 | -| `FROZEN` | 冻结，只读不可发布 | -| `ARCHIVED` | 归档，对外不可见 | +| Status | Description | +|--------|-------------| +| `ACTIVE` | Normal use | +| `FROZEN` | Frozen, read-only, cannot publish | +| `ARCHIVED` | Archived, not visible externally | -## 下一步 +## Next Steps -- [审核流程](./review-workflow) - 了解技能审核 +- [Review Workflow](./review-workflow) - Understand skill review diff --git a/document/docs/02-administration/governance/review-workflow.md b/document/docs/02-administration/governance/review-workflow.md index 660f8eda..df325059 100644 --- a/document/docs/02-administration/governance/review-workflow.md +++ b/document/docs/02-administration/governance/review-workflow.md @@ -1,44 +1,44 @@ --- -title: 审核流程 +title: Review Workflow sidebar_position: 2 -description: 技能发布审核流程配置 +description: Skill publishing review workflow configuration --- -# 审核流程 +# Review Workflow -SkillHub 采用双层审核机制，保障技能质量。 +SkillHub uses a two-tier review mechanism to ensure skill quality. -## 审核流程 +## Review Workflow -### 团队空间技能 +### Team Namespace Skills -1. 团队成员提交发布 -2. 创建审核任务（PENDING） -3. 团队 ADMIN 或 OWNER 审核 - - 通过 → 技能发布（PUBLISHED） - - 拒绝 → 返回修改（REJECTED） +1. Team member submits publishing +2. Create review task (PENDING) +3. Team ADMIN or OWNER reviews + - Approve → Skill published (PUBLISHED) + - Reject → Return for modification (REJECTED) -### 全局空间技能 +### Global Namespace Skills -1. 提交发布 -2. 平台 SKILL_ADMIN 或 SUPER_ADMIN 审核 -3. 审核通过后发布 +1. Submit publishing +2. Platform SKILL_ADMIN or SUPER_ADMIN reviews +3. Published after review approval -## 团队技能提升到全局 +## Promote Team Skill to Global -1. 团队技能已发布 -2. 团队 ADMIN 或 OWNER 申请"提升到全局" -3. 平台管理员审核 -4. 审核通过后在全局空间创建新技能 +1. Team skill is published +2. Team ADMIN or OWNER applies "Promote to Global" +3. Platform admin reviews +4. Creates new skill in global namespace after approval -## 审核权限 +## Review Permissions -| 审核类型 | 所需角色 | -|---------|---------| -| 团队空间技能审核 | 命名空间 ADMIN/OWNER | -| 全局空间技能审核 | SKILL_ADMIN/SUPER_ADMIN | -| 提升申请审核 | SKILL_ADMIN/SUPER_ADMIN | +| Review Type | Required Role | +|------------|---------------| +| Team namespace skill review | Namespace ADMIN/OWNER | +| Global namespace skill review | SKILL_ADMIN/SUPER_ADMIN | +| Promotion request review | SKILL_ADMIN/SUPER_ADMIN | -## 下一步 +## Next Steps -- [用户管理](./user-management) - 管理平台用户 +- [User Management](./user-management) - Manage platform users diff --git a/document/docs/02-administration/governance/user-management.md b/document/docs/02-administration/governance/user-management.md index 58d9abdc..d6bb99d3 100644 --- a/document/docs/02-administration/governance/user-management.md +++ b/document/docs/02-administration/governance/user-management.md @@ -1,36 +1,36 @@ --- -title: 用户管理 +title: User Management sidebar_position: 3 -description: 平台用户管理 +description: Platform user management --- -# 用户管理 +# User Management -## 用户状态 +## User Status -| 状态 | 实际逻辑 | -|------|----------| -| `ACTIVE` | 可正常登录和使用系统。OAuth 首次自动准入、local 注册成功后都会进入该状态。 | -| `PENDING` | 账号已建但不可登录。OAuth 在“需要审批”策略下会创建 `PENDING` 用户并跳转到待审批页；local 登录遇到该状态会直接拒绝。 | -| `DISABLED` | 不可登录。OAuth 和 local 登录都会拒绝；`/api/v1/auth/me` 发现当前会话对应用户已被禁用时，会直接清掉 session。 | -| `MERGED` | 账号已并入其他账号，不可继续登录；主要由账号合并流程写入，不是普通用户管理流程的目标状态。 | +| Status | Effective behavior | +|--------|--------------------| +| `ACTIVE` | Can log in and use the system normally. OAuth auto-admission and local registration both create users in this state. | +| `PENDING` | Account exists but cannot log in. Under approval-required OAuth flows, the system creates a `PENDING` user and redirects to the pending-approval page. Local login also rejects this status. | +| `DISABLED` | Cannot log in. Both OAuth and local auth reject it. `/api/v1/auth/me` will invalidate the current session if the backing user has been disabled. | +| `MERGED` | Account has been merged into another account and can no longer log in. This is mainly written by the account-merge flow, not by normal user administration. | -## 用户准入 +## User Admission -可配置新用户是否需要审批： -- 自动准入：新用户登录后自动激活 -- 审批准入：新用户需 USER_ADMIN 审批后激活 +Configure whether new users require approval: +- Auto-admission: New users automatically activated after login +- Approval admission: New users require USER_ADMIN approval to activate -## 角色分配 +## Role Assignment -`USER_ADMIN` 或 `SUPER_ADMIN` 可调用用户管理接口修改平台角色，但当前实现有几个关键点： +`USER_ADMIN` or `SUPER_ADMIN` can call the user-management API to change platform roles, but the implementation has a few important constraints: -- 接口一次只能设置一个目标平台角色。 -- 设置时会删除该用户已有的显式平台角色，再写入新的那个角色。 -- 如果设置为 `USER`，不会写入 `user_role_binding`，而是依赖运行时默认角色补位。 -- `USER_ADMIN` 不能分配 `SUPER_ADMIN`，只有 `SUPER_ADMIN` 能分配。 +- The API sets exactly one target platform role at a time. +- It deletes the user's existing explicit platform-role bindings before writing the new one. +- If the target role is `USER`, no `user_role_binding` row is written; runtime defaulting adds it later. +- `USER_ADMIN` cannot assign `SUPER_ADMIN`; only `SUPER_ADMIN` can do that. -当前管理接口可设置的目标角色实际上是： +The currently supported target roles in practice are: - `USER` - `SKILL_ADMIN` @@ -38,24 +38,24 @@ description: 平台用户管理 - `AUDITOR` - `SUPER_ADMIN` -## 用户封禁/解封 +## User Disable/Enable -`USER_ADMIN` 或 `SUPER_ADMIN` 可封禁/解封用户。 +`USER_ADMIN` or `SUPER_ADMIN` can disable or enable users. -当前公开管理接口只支持把状态改成： +The current public management API only supports changing status to: - `ACTIVE` - `DISABLED` -其中： +In practice: -- “审批通过”本质上也是把用户状态改成 `ACTIVE`。 -- 不能通过该接口直接改成 `PENDING` 或 `MERGED`。 +- "Approve user" is implemented as changing the status to `ACTIVE`. +- The API does not directly set users to `PENDING` or `MERGED`. -## 账号合并 +## Account Merge -支持将多个账号合并为一个，保留操作历史。 +Supports merging multiple accounts into one, preserving operation history. -## 下一步 +## Next Steps -- [创建技能包](../../user-guide/publishing/create-skill) - 开始发布技能 +- [Create Skill Package](../../user-guide/publishing/create-skill) - Start publishing skills diff --git a/document/docs/02-administration/security/_category_.json b/document/docs/02-administration/security/_category_.json index 7b64d3ab..82ed3574 100644 --- a/document/docs/02-administration/security/_category_.json +++ b/document/docs/02-administration/security/_category_.json @@ -1,4 +1,4 @@ { - "label": "安全与合规", + "label": "Security & Compliance", "position": 2 } diff --git a/document/docs/02-administration/security/audit-logs.md b/document/docs/02-administration/security/audit-logs.md index 08925fce..6020c3d2 100644 --- a/document/docs/02-administration/security/audit-logs.md +++ b/document/docs/02-administration/security/audit-logs.md @@ -1,38 +1,38 @@ --- -title: 审计日志 +title: Audit Logs sidebar_position: 3 -description: 操作审计日志查询与管理 +description: Operation audit log query and management --- -# 审计日志 +# Audit Logs -SkillHub 记录所有关键操作的审计日志，满足企业合规要求。 +SkillHub records audit logs for all critical operations to meet enterprise compliance requirements. -## 审计范围 +## Audit Scope -记录的操作包括： -- 技能发布、下载、删除 -- 审核通过、拒绝 -- 用户登录、登出 -- 权限变更 -- 命名空间管理 -- 配置变更 +Recorded operations include: +- Skill publishing, downloading, deletion +- Review approval, rejection +- User login, logout +- Permission changes +- Namespace management +- Configuration changes -## 审计日志查询 +## Audit Log Query -通过管理后台审计日志页面或 Admin API 查询。 +Query through admin dashboard audit log page or Admin API. -## 日志字段 +## Log Fields -- 操作时间 -- 操作用户 -- 操作类型 -- 目标资源 -- 客户端 IP +- Operation time +- Operating user +- Operation type +- Target resource +- Client IP - User-Agent -- 请求 ID -- 详细信息 +- Request ID +- Detailed information -## 下一步 +## Next Steps -- [命名空间管理](../governance/namespaces) - 管理组织 +- [Namespace Management](../governance/namespaces) - Manage organization diff --git a/document/docs/02-administration/security/authentication.md b/document/docs/02-administration/security/authentication.md index 923878ee..148252f7 100644 --- a/document/docs/02-administration/security/authentication.md +++ b/document/docs/02-administration/security/authentication.md @@ -1,36 +1,36 @@ --- -title: 认证配置 +title: Authentication Configuration sidebar_position: 1 -description: 配置用户认证方式 +description: Configure user authentication methods --- -# 认证配置 +# Authentication Configuration -SkillHub 支持多种认证方式，满足不同企业的安全需求。 +SkillHub supports multiple authentication methods to meet different enterprise security requirements. -## OAuth2 登录 +## OAuth2 Login ### GitHub OAuth -1. 在 GitHub 创建 OAuth App -2. 配置环境变量： +1. Create an OAuth App on GitHub +2. Configure environment variables: ```bash OAUTH2_GITHUB_CLIENT_ID=your-client-id OAUTH2_GITHUB_CLIENT_SECRET=your-client-secret ``` -### 扩展 OAuth Provider +### Extend OAuth Provider -架构支持扩展其他 OAuth Provider，如 GitLab、Gitee 等。 +The architecture supports extending to other OAuth providers like GitLab, Gitee, etc. -## 本地账号登录 +## Local Account Login -开发环境支持本地账号登录，生产环境默认关闭。 +Local account login is supported in development environment, disabled by default in production. -## 企业 SSO 集成 +## Enterprise SSO Integration -支持通过扩展点集成企业 SSO（SAML/OIDC）。 +Supports integrating enterprise SSO (SAML/OIDC) through extension points. -## 下一步 +## Next Steps -- [权限管理](./authorization) - 配置权限控制 +- [Authorization](./authorization) - Configure access control diff --git a/document/docs/02-administration/security/authorization.md b/document/docs/02-administration/security/authorization.md index 75ff506e..4c0359be 100644 --- a/document/docs/02-administration/security/authorization.md +++ b/document/docs/02-administration/security/authorization.md @@ -1,63 +1,64 @@ --- -title: 权限管理 +title: Authorization Management sidebar_position: 2 -description: RBAC 权限系统配置 +description: RBAC permission system configuration --- -# 权限管理 +# Authorization Management -SkillHub 采用基于角色的访问控制（RBAC）系统。 +SkillHub uses a Role-Based Access Control (RBAC) system. -当前代码里实际存在两套并行角色体系： +The current codebase actually uses two parallel role systems: -- 平台角色：控制后台治理、用户管理、审计等平台级能力。 -- 命名空间角色：控制某个团队空间内的成员、发布、审核、归档等操作。 +- Platform roles: control platform-wide governance, user administration, and audit capabilities. +- Namespace roles: control actions inside a specific team namespace. -二者会同时参与鉴权，但不是一套角色的上下级映射。 +They participate in authorization together, but they are not a single hierarchy. -## 平台角色 +## Platform Roles -### 代码里实际初始化的显式平台角色 +### Explicit platform roles seeded by code -数据库迁移只初始化了 4 个显式平台角色： +The database migration seeds only 4 explicit platform roles: -| 角色 | 代码 | 实际能力 | -|------|------|----------| -| 超级管理员 | `SUPER_ADMIN` | 拥有全部权限；`RbacService#getUserPermissions` 会直接返回全部权限码；可访问所有 `SUPER_ADMIN`/`SKILL_ADMIN`/`USER_ADMIN`/`AUDITOR` 能访问的接口；可分配 `SUPER_ADMIN`；发布技能时可绕过命名空间成员校验并直接自动发布；可以审批自己提交的 promotion；普通审核单若是自己提交的，也只有 `SUPER_ADMIN` 能特判审批。 | -| 技能管理员 | `SKILL_ADMIN` | 可访问技能治理后台接口；可隐藏/取消隐藏技能、撤回版本（yank）、处理技能举报；可查看和处理全局空间审核、promotion 审核、治理工作台收件箱中的 review/promotion/report；不能分配平台角色、不能看审计日志、不能管理用户。 | -| 用户管理员 | `USER_ADMIN` | 可访问用户管理接口；可列表用户、审批用户、启用/禁用用户、修改平台角色；不能分配 `SUPER_ADMIN`；不能处理技能治理、不能看审计日志。 | -| 审计员 | `AUDITOR` | 只读查看审计日志；可访问 `/api/v1/admin/audit-logs` 和 `/actuator/prometheus`；治理工作台中只能看 activity，不能处理 review/promotion/report，也不能管理用户或技能。 | +| Role | Code | Effective behavior | +|------|------|--------------------| +| Super Admin | `SUPER_ADMIN` | Has all permissions. `RbacService#getUserPermissions` returns all permission codes for this role. Can access all endpoints available to `SUPER_ADMIN` / `SKILL_ADMIN` / `USER_ADMIN` / `AUDITOR`. Can assign `SUPER_ADMIN`. Can bypass namespace membership checks during publish and auto-publish directly. Still cannot approve their own promotion request, and for normal review tasks the self-submission exception is only bypassed by `SUPER_ADMIN`. | +| Skill Admin | `SKILL_ADMIN` | Can access skill governance admin endpoints. Can hide/unhide skills, yank versions, and resolve/dismiss skill reports. Can review global namespace review tasks, promotion requests, and governance inbox items for review/promotion/report. Cannot manage users or read audit logs. | +| User Admin | `USER_ADMIN` | Can access user management endpoints. Can list users, approve users, enable/disable users, and change platform roles. Cannot assign `SUPER_ADMIN`. Cannot perform skill governance or read audit logs. | +| Auditor | `AUDITOR` | Read-only audit access. Can access `/api/v1/admin/audit-logs` and `/actuator/prometheus`. In the governance workbench this role can read activity, but cannot process review/promotion/report items and cannot manage users or skills. | -### 运行时默认平台角色 +### Runtime default platform role -| 角色 | 代码 | 实际逻辑 | -|------|------|----------| -| 默认用户 | `USER` | 不是 `role` 表里的显式初始化记录。只要用户没有任何显式平台角色绑定，登录态和 `RbacService#getUserRoleCodes` 都会自动补上 `USER`。它主要表示“普通已登录用户”，没有额外后台治理权限。 | +| Role | Code | Effective behavior | +|------|------|--------------------| +| Default User | `USER` | Not an explicitly seeded row in the `role` table. If a user has no explicit platform-role binding, login/session resolution and `RbacService#getUserRoleCodes` automatically add `USER`. It represents a normal signed-in user with no extra governance privileges. | -### 需要特别注意的实现细节 +### Important implementation details -- 当前管理接口的“修改用户角色”是单值覆盖，不是追加：`PUT /api/v1/admin/users/{userId}/role` 先清空该用户现有平台角色，再写入一个目标角色；当目标角色是 `USER` 时，不会写数据库记录，而是依赖运行时默认补位。 -- 代码底层仍然支持“一个用户拥有多个显式平台角色”的读取与鉴权，因为 session、token 和 `RbacService` 都是按角色集合处理；只是当前管理接口不会这样分配。 -- `SUPER_ADMIN` 是唯一一个在权限查询时被视为“拥有全部 permission code”的角色，其它角色依赖 `role_permission` 关联表。 +- The current admin API changes platform role by replacement, not by append: `PUT /api/v1/admin/users/{userId}/role` deletes existing explicit platform-role bindings first, then writes one target role. +- If the target role is `USER`, no explicit binding is stored; the role is supplied later by runtime defaulting. +- The lower-level auth/session/RBAC code still supports multiple explicit platform roles on one user because it works with role sets. The current admin API simply does not assign roles that way. +- `SUPER_ADMIN` is the only role treated as "all permissions" during permission lookup. Other roles depend on `role_permission`. -## 命名空间角色 +## Namespace Roles -| 角色 | 实际能力 | -|------|----------| -| `OWNER` | 创建团队空间时自动成为 `OWNER`。可更新命名空间信息、管理成员、冻结/解冻空间、归档/恢复空间、转移所有权；可提交 review；可审核团队空间 review；可访问私有技能；可管理受限技能生命周期（归档、反归档、删除草稿/驳回版本等）。 | -| `ADMIN` | 可更新命名空间信息、管理成员、冻结/解冻空间；不能归档/恢复空间，也不能直接把别人设为 `OWNER`；可提交 review；可审核团队空间 review；可访问私有技能；可管理受限技能生命周期。 | -| `MEMBER` | 默认加入全局空间时获得 `MEMBER`。可在所在命名空间发布技能、提交 review；但不能审核 review、不能管理成员、不能冻结/归档空间；私有技能也不能仅因 `MEMBER` 身份访问，私有技能要求 owner 或 `ADMIN/OWNER`。 | +| Role | Effective behavior | +|------|--------------------| +| `OWNER` | Automatically assigned when creating a team namespace. Can update namespace settings, manage members, freeze/unfreeze the namespace, archive/restore it, and transfer ownership. Can submit reviews, review team-namespace review tasks, access private skills, and manage restricted skill lifecycle. | +| `ADMIN` | Can update namespace settings, manage members, and freeze/unfreeze the namespace. Cannot archive/restore the namespace and cannot directly set someone to `OWNER`. Can submit reviews, review team-namespace review tasks, access private skills, and manage restricted skill lifecycle. | +| `MEMBER` | Common member role, including auto-membership in the global namespace. Can publish skills in namespaces they belong to and can submit reviews. Cannot review review tasks, manage members, or freeze/archive namespaces. `MEMBER` alone is not enough to access private skills. | -### 命名空间角色的边界 +### Namespace role boundaries -- `GLOBAL` 空间是只读系统空间，不能通过命名空间治理接口修改；全局空间 review/promotion/report 处理依赖平台角色 `SKILL_ADMIN`/`SUPER_ADMIN`，不是依赖全局空间成员身份。 -- `NAMESPACE_ONLY` 可见性的技能，任何该命名空间成员都能访问。 -- `PRIVATE` 可见性的技能，只有技能 owner 或命名空间 `ADMIN/OWNER` 能访问，`MEMBER` 不行。 +- The `GLOBAL` namespace is effectively immutable in namespace-governance flows. Review/promotion/report handling there depends on platform roles `SKILL_ADMIN` / `SUPER_ADMIN`, not on global namespace membership alone. +- For `NAMESPACE_ONLY` visibility, any namespace member can access the skill. +- For `PRIVATE` visibility, access is limited to the skill owner or namespace `ADMIN` / `OWNER`; `MEMBER` is not enough. -## 权限配置 +## Permission Configuration -通过后台分配平台角色，通过命名空间成员关系分配命名空间角色。 +Assign platform roles through admin user management, and namespace roles through namespace membership. -## 下一步 +## Next Steps -- [审计日志](./audit-logs) - 查看操作审计 +- [Audit Logs](./audit-logs) - View operation audits diff --git a/document/docs/02-administration/security/scanner.md b/document/docs/02-administration/security/scanner.md new file mode 100644 index 00000000..01a86c95 --- /dev/null +++ b/document/docs/02-administration/security/scanner.md @@ -0,0 +1,104 @@ +--- +title: Security Scanning +sidebar_position: 4 +description: Use Skill Scanner to add automated security checks to the skill publish pipeline +--- + +# Security Scanning + +SkillHub can integrate `skill-scanner` into the publish pipeline to automatically inspect uploaded skill packages and persist the results as security audit records. + +## Scan Flow + +When scanning is enabled, the publish flow becomes: + +1. A user publishes a skill package +2. The backend creates a version and moves it to `SCANNING` +3. The backend enqueues a scan task +4. `skill-scanner` consumes the task and runs analysis +5. The result is stored in `security_audit` +6. The version moves to `PENDING_REVIEW`, or to `SCAN_FAILED` after final retry exhaustion +7. The existing human review workflow continues afterward + +## Typical Use Cases + +- Add automated risk checks before manual review +- Retain scan results and audit evidence for governance +- Detect suspicious code, leaked secrets, or risky behavior patterns in skill packages + +## Runtime Modes + +Two modes are supported: + +- `local`: the backend passes a filesystem path to the scanner, suitable for shared filesystem setups +- `upload`: the backend uploads the package archive directly, suitable for Docker, Kubernetes, and split deployments + +Recommended usage: + +- Local development: prefer `local` +- Production, Kubernetes, or split services: prefer `upload` + +## Key Configuration + +Core backend configuration: + +```yaml +skillhub: + security: + scanner: + enabled: false + base-url: http://localhost:8000 + health-path: /health + scan-path: /scan-upload + mode: upload + connect-timeout-ms: 5000 + read-timeout-ms: 300000 + retry-max-attempts: 3 +``` + +Common environment variables: + +- `SKILLHUB_SECURITY_SCANNER_ENABLED` +- `SKILLHUB_SECURITY_SCANNER_URL` +- `SKILLHUB_SECURITY_SCANNER_MODE` +- `SKILLHUB_SCAN_STREAM_KEY` +- `SKILLHUB_SCAN_STREAM_GROUP` + +## How To Verify + +After enabling scanning, validate it with these steps: + +1. Publish a test skill package +2. Confirm the version first moves to `SCANNING` +3. Confirm a `security_audit` record is created +4. Confirm the version eventually moves to `PENDING_REVIEW` or `SCAN_FAILED` +5. Call the security audit API to inspect the result + +```text +GET /api/v1/skills/{skillId}/versions/{versionId}/security-audit +``` + +## Result Fields + +Security audit results usually include: + +- `scanId` +- `scannerType` +- `verdict` +- `isSafe` +- `maxSeverity` +- `findingsCount` +- `findings` +- `scanDurationSeconds` +- `scannedAt` + +## Deployment Recommendations + +- Keep scanning disabled at first in local environments, then enable it after the main flow is stable +- Use `upload` mode in Kubernetes to avoid relying on a shared writable filesystem +- In production, keep scan results alongside human review records as governance evidence + +## Next Steps + +- [Review Workflow](../governance/review-workflow) - Understand the approval flow after scanning +- [Deployment Configuration](../deployment/configuration) - Review deployment-related settings diff --git a/document/docs/03-user-guide/_category_.json b/document/docs/03-user-guide/_category_.json index e87c7197..2fa27ec7 100644 --- a/document/docs/03-user-guide/_category_.json +++ b/document/docs/03-user-guide/_category_.json @@ -1,8 +1,8 @@ { - "label": "用户指南", + "label": "User Guide", "position": 3, "link": { "type": "generated-index", - "description": "学习如何发布、发现和使用技能" + "description": "Learn how to publish, discover, and use skills" } } diff --git a/document/docs/03-user-guide/collaboration/_category_.json b/document/docs/03-user-guide/collaboration/_category_.json index f7661de1..6edb05d5 100644 --- a/document/docs/03-user-guide/collaboration/_category_.json +++ b/document/docs/03-user-guide/collaboration/_category_.json @@ -1,4 +1,4 @@ { - "label": "协作", + "label": "Collaboration", "position": 3 } diff --git a/document/docs/03-user-guide/collaboration/namespaces.md b/document/docs/03-user-guide/collaboration/namespaces.md index e737752e..079591da 100644 --- a/document/docs/03-user-guide/collaboration/namespaces.md +++ b/document/docs/03-user-guide/collaboration/namespaces.md @@ -1,41 +1,41 @@ --- -title: 团队命名空间 +title: Team Namespaces sidebar_position: 1 -description: 在团队命名空间中协作 +description: Collaborate in team namespaces --- -# 团队命名空间 +# Team Namespaces -## 加入命名空间 +## Join Namespace -需要命名空间管理员邀请才能加入团队命名空间。 +Requires namespace admin invitation to join a team namespace. -## 命名空间角色 +## Namespace Roles ### MEMBER -- 可查看命名空间内所有技能 -- 可发布技能（需审核） -- 可收藏和评分 +- Can view all skills in namespace +- Can publish skills (requires review) +- Can favorite and rate ### ADMIN -- 所有 MEMBER 权限 -- 可审核技能发布 -- 可管理成员 -- 可编辑命名空间信息 +- All MEMBER permissions +- Can review skill publishing +- Can manage members +- Can edit namespace information ### OWNER -- 所有 ADMIN 权限 -- 可转让所有权 -- 可归档命名空间 +- All ADMIN permissions +- Can transfer ownership +- Can archive namespace -## 技能可见性 +## Skill Visibility -| 可见性 | 说明 | -|--------|------| -| `PUBLIC` | 所有人可见，匿名可下载 | -| `NAMESPACE_ONLY` | 仅命名空间成员可见 | -| `PRIVATE` | 仅 owner 和命名空间 ADMIN 可见 | +| Visibility | Description | +|------------|-------------| +| `PUBLIC` | Visible to everyone, anonymous downloadable | +| `NAMESPACE_ONLY` | Only visible to namespace members | +| `PRIVATE` | Only visible to owner and namespace ADMIN | -## 下一步 +## Next Steps -- [提升到全局](./promotion) - 将团队技能推广到全局 +- [Promote to Global](./promotion) - Promote team skills to global diff --git a/document/docs/03-user-guide/collaboration/promotion.md b/document/docs/03-user-guide/collaboration/promotion.md index 7d065430..610a18b9 100644 --- a/document/docs/03-user-guide/collaboration/promotion.md +++ b/document/docs/03-user-guide/collaboration/promotion.md @@ -1,42 +1,42 @@ --- -title: 提升到全局 +title: Promote to Global sidebar_position: 2 -description: 申请将团队技能提升到全局空间 +description: Apply to promote team skills to global namespace --- -# 提升到全局 +# Promote to Global -优秀的团队技能可以申请提升到全局空间，供全企业使用。 +Excellent team skills can be applied for promotion to the global namespace for enterprise-wide use. -## 提升前提 +## Promotion Prerequisites -- 技能在团队空间已发布 -- 申请人是技能 owner 或命名空间 ADMIN -- 技能没有待审核的提升申请 +- Skill is published in team namespace +- Applicant is skill owner or namespace ADMIN +- Skill has no pending promotion requests -## 申请提升 +## Apply for Promotion -1. 进入团队技能详情页 -2. 点击"提升到全局" -3. 填写申请说明 -4. 提交申请 +1. Go to team skill detail page +2. Click "Promote to Global" +3. Fill in application description +4. Submit application -## 审核流程 +## Review Workflow -1. 平台管理员收到提升申请 -2. 审核技能质量和适用性 -3. 审核通过后： - - 在全局空间创建新技能 - - 保留原团队技能 - - 记录来源追溯关系 +1. Platform admin receives promotion application +2. Reviews skill quality and suitability +3. After approval: + - Creates new skill in global namespace + - Preserves original team skill + - Records source traceability relationship -## 提升后 +## After Promotion -- 全局空间的新技能独立管理 -- 原团队技能继续存在 -- 两者版本不自动同步 -- 如需同步需手动操作 +- New skill in global namespace is independently managed +- Original team skill continues to exist +- Versions are not automatically synced +- Manual operation required if sync needed -## 下一步 +## Next Steps -- [API 概述](../../developer/api/overview) - API 集成 +- [API Overview](../../developer/api/overview) - API integration diff --git a/document/docs/03-user-guide/discovery/_category_.json b/document/docs/03-user-guide/discovery/_category_.json index 7014e21d..53fc1202 100644 --- a/document/docs/03-user-guide/discovery/_category_.json +++ b/document/docs/03-user-guide/discovery/_category_.json @@ -1,4 +1,4 @@ { - "label": "发现与使用", + "label": "Discovery & Usage", "position": 2 } diff --git a/document/docs/03-user-guide/discovery/install.md b/document/docs/03-user-guide/discovery/install.md index 9cdf9254..a3f2bc74 100644 --- a/document/docs/03-user-guide/discovery/install.md +++ b/document/docs/03-user-guide/discovery/install.md @@ -1,53 +1,53 @@ --- -title: 安装使用 +title: Install & Use sidebar_position: 2 -description: 安装和使用技能 +description: Install and use skills --- -# 安装使用 +# Install & Use -## 通过 CLI 安装 +## Install via CLI -### 安装最新版本 +### Install Latest Version ```bash clawhub install @team/my-skill ``` -### 安装指定版本 +### Install Specific Version ```bash clawhub install @team/my-skill@1.2.0 ``` -### 按标签安装 +### Install by Tag ```bash clawhub install @team/my-skill@beta ``` -### 使用 ClawHub CLI 安装 +### Install with ClawHub CLI ```bash clawhub install my-skill clawhub install team-name--my-skill ``` -## 安装目录 +## Installation Directory -按以下优先级安装： +Install by the following priority: -| 优先级 | 路径 | 说明 | -|--------|------|------| -| 1 | `./.agent/skills/` | 项目级，universal 模式 | -| 2 | `~/.agent/skills/` | 全局级，universal 模式 | -| 3 | `./.claude/skills/` | 项目级，Claude 默认 | -| 4 | `~/.claude/skills/` | 全局级，Claude 默认 | +| Priority | Path | Description | +|----------|------|-------------| +| 1 | `./.agent/skills/` | Project level, universal mode | +| 2 | `~/.agent/skills/` | Global level, universal mode | +| 3 | `./.claude/skills/` | Project level, Claude default | +| 4 | `~/.claude/skills/` | Global level, Claude default | -## 在 Claude Code 中使用 +## Use in Claude Code -安装后，技能会被 Claude Code 自动发现和加载。 +After installation, skills are automatically discovered and loaded by Claude Code. -## 下一步 +## Next Steps -- [评分与收藏](./ratings) - 反馈和收藏技能 +- [Ratings & Stars](./ratings) - Feedback and favorite skills diff --git a/document/docs/03-user-guide/discovery/ratings.md b/document/docs/03-user-guide/discovery/ratings.md index 8745a87f..3dbf1abf 100644 --- a/document/docs/03-user-guide/discovery/ratings.md +++ b/document/docs/03-user-guide/discovery/ratings.md @@ -1,30 +1,30 @@ --- -title: 评分与收藏 +title: Ratings & Stars sidebar_position: 3 -description: 技能评分和收藏功能 +description: Skill rating and favorite features --- -# 评分与收藏 +# Ratings & Stars -## 收藏技能 +## Favorite Skills -点击技能详情页的"收藏"按钮可收藏技能。 +Click the "Favorite" button on the skill detail page to favorite a skill. -查看已收藏的技能： -- Web：进入"我的收藏" -- CLI：`clawhub stars` +View your favorite skills: +- Web: Go to "My Favorites" +- CLI: `clawhub stars` -## 技能评分 +## Skill Rating -可对技能进行 1-5 分评分： +You can rate skills from 1-5 stars: -1. 进入技能详情页 -2. 点击评分区域 -3. 选择评分（1-5 星） -4. 提交评分 +1. Go to skill detail page +2. Click rating area +3. Select rating (1-5 stars) +4. Submit rating -可随时修改自己的评分。 +You can modify your rating at any time. -## 下一步 +## Next Steps -- [团队命名空间](../collaboration/namespaces) - 团队协作 +- [Team Namespaces](../collaboration/namespaces) - Team collaboration diff --git a/document/docs/03-user-guide/discovery/search.md b/document/docs/03-user-guide/discovery/search.md index 01da8f73..825ef714 100644 --- a/document/docs/03-user-guide/discovery/search.md +++ b/document/docs/03-user-guide/discovery/search.md @@ -1,36 +1,36 @@ --- -title: 搜索技能 +title: Search Skills sidebar_position: 1 -description: 搜索和筛选技能 +description: Search and filter skills --- -# 搜索技能 +# Search Skills -## 全文搜索 +## Full-text Search -在搜索框输入关键词，SkillHub 会在以下字段中搜索： -- 技能名称 -- 技能描述 -- 技能 slug -- frontmatter 中除 `name`、`description`、`version` 外的其他字段 -- `keywords` / `tags` 等关键词字段 +Enter keywords in the search box, SkillHub searches in the following fields: +- Skill name +- Skill description +- Skill slug +- Frontmatter fields other than `name`, `description`, and `version` +- Keyword-style fields such as `keywords` and `tags` -## 筛选条件 +## Filter Conditions -可通过以下条件筛选搜索结果： -- 命名空间 -- 可见性 -- 下载量排序 -- 评分排序 -- 更新时间排序 +You can filter search results by the following conditions: +- Namespace +- Visibility +- Download count sorting +- Rating sorting +- Update time sorting -## 高级搜索 +## Advanced Search -使用搜索语法： -- `namespace:@team-ai` - 指定命名空间 -- `category:code-review` - 指定分类 -- `downloads:>100` - 下载量大于 100 +Use search syntax: +- `namespace:@team-ai` - Specify namespace +- `category:code-review` - Specify category +- `downloads:>100` - Downloads greater than 100 -## 下一步 +## Next Steps -- [安装使用](./install) - 安装和使用技能 +- [Install & Use](./install) - Install and use skills diff --git a/document/docs/03-user-guide/publishing/_category_.json b/document/docs/03-user-guide/publishing/_category_.json index a8284d4a..0942921d 100644 --- a/document/docs/03-user-guide/publishing/_category_.json +++ b/document/docs/03-user-guide/publishing/_category_.json @@ -1,4 +1,4 @@ { - "label": "发布技能", + "label": "Publishing Skills", "position": 1 } diff --git a/document/docs/03-user-guide/publishing/create-skill.md b/document/docs/03-user-guide/publishing/create-skill.md index 929d6a8d..1535dfd6 100644 --- a/document/docs/03-user-guide/publishing/create-skill.md +++ b/document/docs/03-user-guide/publishing/create-skill.md @@ -1,56 +1,56 @@ --- -title: 创建技能包 +title: Create Skill Package sidebar_position: 1 -description: 学习如何创建符合规范的技能包 +description: Learn how to create a compliant skill package --- -# 创建技能包 +# Create Skill Package -## 技能包结构 +## Skill Package Structure -一个标准的 SkillHub 技能包结构如下： +A standard SkillHub skill package structure looks like this: ``` my-skill/ -├── SKILL.md # 主入口文件（必需） -├── references/ # 参考资料（可选） -├── scripts/ # 脚本（可选） -└── assets/ # 静态资源（可选） +├── SKILL.md # Main entry file (required) +├── references/ # References (optional) +├── scripts/ # Scripts (optional) +└── assets/ # Static assets (optional) ``` -## SKILL.md 格式 +## SKILL.md Format -SKILL.md 是技能包的主入口文件，使用 YAML frontmatter + Markdown 正文格式： +SKILL.md is the main entry file of a skill package, using YAML frontmatter + Markdown body format: ```markdown --- name: my-skill -description: 一句话描述这个技能的用途 +description: One sentence describing what this skill is for x-astron-category: code-review --- -# 技能说明 +# Skill Description -这里是技能的详细说明... +Detailed skill description goes here... ``` -### Frontmatter 字段 +### Frontmatter Fields -| 字段 | 必需 | 说明 | -|------|------|------| -| `name` | 是 | 技能标识，kebab-case 格式 | -| `description` | 是 | 技能简短描述 | -| `x-astron-category` | 否 | 分类标签 | -| `x-astron-runtime` | 否 | 运行时要求 | -| `x-astron-min-version` | 否 | 最低版本要求 | +| Field | Required | Description | +|-------|----------|-------------| +| `name` | Yes | Skill identifier, kebab-case format | +| `description` | Yes | Brief skill description | +| `x-astron-category` | No | Category tag | +| `x-astron-runtime` | No | Runtime requirement | +| `x-astron-min-version` | No | Minimum version requirement | -## 文件限制 +## File Limits -- 单文件大小：最大 1MB -- 总包大小：最大 10MB -- 文件数量：最多 100 个 -- 允许的文件类型：`.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.js`, `.ts`, `.py`, `.sh`, `.png`, `.jpg`, `.svg` +- Single file size: Max 1MB +- Total package size: Max 10MB +- File count: Max 100 +- Allowed file types: `.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.js`, `.ts`, `.py`, `.sh`, `.png`, `.jpg`, `.svg` -## 下一步 +## Next Steps -- [发布流程](./publish) - 发布技能包 +- [Publish Workflow](./publish) - Publish skill package diff --git a/document/docs/03-user-guide/publishing/publish.md b/document/docs/03-user-guide/publishing/publish.md index 4fd86f69..5421394e 100644 --- a/document/docs/03-user-guide/publishing/publish.md +++ b/document/docs/03-user-guide/publishing/publish.md @@ -1,50 +1,50 @@ --- -title: 发布流程 +title: Publish Workflow sidebar_position: 2 -description: 发布技能到 SkillHub +description: Publish skills to SkillHub --- -# 发布流程 +# Publish Workflow -## 通过 Web 发布 +## Publish via Web -1. 登录 SkillHub -2. 点击"发布技能" -3. 选择目标命名空间 -4. 上传技能包 ZIP 文件 -5. 填写版本信息（变更日志等） -6. 提交发布 -7. 等待审核（如需要） -8. 审核通过后发布成功 +1. Login to SkillHub +2. Click "Publish Skill" +3. Select target namespace +4. Upload skill package ZIP file +5. Fill in version information (changelog, etc.) +6. Submit publishing +7. Wait for review (if required) +8. Published successfully after review approval -## 通过 CLI 发布 +## Publish via CLI ```bash -# 1. 登录 -clawhub login +# 1. Login +skillhub login -# 2. 发布 -clawhub publish ./my-skill.zip --namespace @team-myteam +# 2. Publish +skillhub publish ./my-skill.zip --namespace @team-myteam ``` -## 通过 ClawHub CLI 发布 +## Publish via ClawHub CLI -配置 registry 后使用： +Use after configuring registry: ```bash clawhub publish ./my-skill.zip ``` -## 发布状态 +## Publishing Status -| 状态 | 说明 | -|------|------| -| `DRAFT` | 草稿，未提交审核 | -| `PENDING_REVIEW` | 等待审核 | -| `PUBLISHED` | 已发布，可被发现和下载 | -| `REJECTED` | 已拒绝，需修改后重新提交 | -| `YANKED` | 已撤回，不再推荐使用 | +| Status | Description | +|--------|-------------| +| `DRAFT` | Draft, not submitted for review | +| `PENDING_REVIEW` | Pending review | +| `PUBLISHED` | Published, discoverable and downloadable | +| `REJECTED` | Rejected, need modification and resubmit | +| `YANKED` | Withdrawn, no longer recommended for use | -## 下一步 +## Next Steps -- [版本管理](./versioning) - 管理技能版本 +- [Version Management](./versioning) - Manage skill versions diff --git a/document/docs/03-user-guide/publishing/versioning.md b/document/docs/03-user-guide/publishing/versioning.md index a0a4d05f..f73e9393 100644 --- a/document/docs/03-user-guide/publishing/versioning.md +++ b/document/docs/03-user-guide/publishing/versioning.md @@ -1,56 +1,56 @@ --- -title: 版本管理 +title: Version Management sidebar_position: 3 -description: 技能版本和标签管理 +description: Skill version and tag management --- -# 版本管理 +# Version Management -## 语义化版本 +## Semantic Versioning -SkillHub 使用语义化版本（Semantic Versioning）：`MAJOR.MINOR.PATCH` +SkillHub uses Semantic Versioning: `MAJOR.MINOR.PATCH` -- `MAJOR`：不兼容的 API 变更 -- `MINOR`：向后兼容的功能新增 -- `PATCH`：向后兼容的问题修复 +- `MAJOR`: Incompatible API changes +- `MINOR`: Backward compatible feature additions +- `PATCH`: Backward compatible bug fixes -示例：`1.0.0`, `1.1.0`, `2.0.0` +Examples: `1.0.0`, `1.1.0`, `2.0.0` -## latest 标签 +## latest Tag -`latest` 是系统保留标签，自动跟随最新已发布版本，不可手动移动。 +`latest` is a system reserved tag that automatically follows the latest published version and cannot be manually moved. -## 自定义标签 +## Custom Tags -可创建自定义标签用于版本通道管理： +You can create custom tags for version channel management: -- `beta` - 测试版本 -- `stable` - 稳定版本 -- `stable-2026q1` - 季度稳定版本 +- `beta` - Beta version +- `stable` - Stable version +- `stable-2026q1` - Quarterly stable version -### 创建/移动标签 +### Create/Move Tag ```bash clawhub tag set @team/my-skill beta 1.2.0 ``` -### 删除标签 +### Delete Tag ```bash clawhub tag delete @team/my-skill beta ``` -## 版本撤回 +## Version Withdrawal -已发布版本发现问题可撤回： +Published versions with issues can be withdrawn: -1. 进入技能详情页 -2. 找到目标版本 -3. 点击"撤回版本" -4. 确认撤回 +1. Go to skill detail page +2. Find target version +3. Click "Withdraw Version" +4. Confirm withdrawal -撤回后的版本仍可查看，但会标记为不推荐使用。 +Withdrawn versions remain visible but are marked as not recommended for use. -## 下一步 +## Next Steps -- [搜索技能](../discovery/search) - 发现技能 +- [Search Skills](../discovery/search) - Discover skills diff --git a/document/docs/04-developer/_category_.json b/document/docs/04-developer/_category_.json index 6c210bd9..12502727 100644 --- a/document/docs/04-developer/_category_.json +++ b/document/docs/04-developer/_category_.json @@ -1,8 +1,8 @@ { - "label": "开发者参考", + "label": "Developer Reference", "position": 4, "link": { "type": "generated-index", - "description": "API 参考、架构设计和扩展开发" + "description": "API reference, architecture design, and extension development" } } diff --git a/document/docs/04-developer/api/_category_.json b/document/docs/04-developer/api/_category_.json index 7f8d3e0e..27b046c0 100644 --- a/document/docs/04-developer/api/_category_.json +++ b/document/docs/04-developer/api/_category_.json @@ -1,4 +1,4 @@ { - "label": "API 参考", + "label": "API Reference", "position": 1 } diff --git a/document/docs/04-developer/api/authenticated.md b/document/docs/04-developer/api/authenticated.md index 3efe82dd..3742cb2b 100644 --- a/document/docs/04-developer/api/authenticated.md +++ b/document/docs/04-developer/api/authenticated.md @@ -1,26 +1,26 @@ --- -title: 认证 API +title: Authenticated APIs sidebar_position: 3 -description: 需要认证的 API +description: APIs requiring authentication --- -# 认证 API +# Authenticated APIs -## 认证相关 +## Authentication Related -### 获取当前用户 +### Get Current User ```http GET /api/v1/auth/me ``` -### 登出 +### Logout ```http POST /api/v1/auth/logout ``` -## 技能发布 +## Skill Publishing ```http POST /api/v1/publish @@ -30,14 +30,14 @@ file: namespace: ``` -## 收藏 +## Favorites ```http POST /api/v1/skills/{namespace}/{slug}/star DELETE /api/v1/skills/{namespace}/{slug}/star ``` -## 评分 +## Ratings ```http POST /api/v1/skills/{namespace}/{slug}/rating @@ -48,7 +48,7 @@ Content-Type: application/json } ``` -## 标签管理 +## Tag Management ```http GET /api/v1/skills/{namespace}/{slug}/tags @@ -56,14 +56,14 @@ PUT /api/v1/skills/{namespace}/{slug}/tags/{tagName} DELETE /api/v1/skills/{namespace}/{slug}/tags/{tagName} ``` -## 我的资源 +## My Resources ```http GET /api/v1/me/stars GET /api/v1/me/skills ``` -## 命名空间管理 +## Namespace Management ```http POST /api/v1/namespaces @@ -74,7 +74,7 @@ PUT /api/v1/namespaces/{slug}/members/{userId}/role DELETE /api/v1/namespaces/{slug}/members/{userId} ``` -## 审核 +## Reviews ```http GET /api/v1/namespaces/{slug}/reviews @@ -82,7 +82,7 @@ POST /api/v1/namespaces/{slug}/reviews/{id}/approve POST /api/v1/namespaces/{slug}/reviews/{id}/reject ``` -## 提升申请 +## Promotion Requests ```http POST /api/v1/namespaces/{slug}/skills/{skillId}/promote @@ -96,6 +96,6 @@ GET /api/v1/tokens DELETE /api/v1/tokens/{id} ``` -## 下一步 +## Next Steps -- [CLI 兼容层](./cli-compat) - ClawHub 兼容接口 +- [CLI Compatibility Layer](./cli-compat) - ClawHub compatible endpoints diff --git a/document/docs/04-developer/api/cli-compat.md b/document/docs/04-developer/api/cli-compat.md index e411a59d..11f5e688 100644 --- a/document/docs/04-developer/api/cli-compat.md +++ b/document/docs/04-developer/api/cli-compat.md @@ -1,54 +1,54 @@ --- -title: CLI 兼容层 +title: CLI Compatibility Layer sidebar_position: 4 -description: ClawHub CLI 协议兼容层 +description: ClawHub CLI protocol compatibility layer --- -# CLI 兼容层 +# CLI Compatibility Layer -SkillHub 提供 ClawHub CLI 协议兼容层，现有工具可无缝迁移。 +SkillHub provides a ClawHub CLI protocol compatibility layer for seamless migration of existing tools. -## 配置 ClawHub CLI +## Configuring ClawHub CLI -要让 ClawHub CLI 连接到你的 SkillHub 实例，需要配置以下环境变量： +To connect ClawHub CLI to your SkillHub instance, configure the following environment variables: -### 环境变量配置 +### Environment Variable Configuration **Linux/macOS (bash/zsh):** ```bash -# ~/.bashrc 或 ~/.zshrc +# ~/.bashrc or ~/.zshrc export CLAWHUB_SITE=https://skill.xfyun.cn export CLAWHUB_REGISTRY=https://skill.xfyun.cn ``` **Windows (PowerShell):** ```powershell -# 永久设置（当前用户） +# Permanent setting (current user) [Environment]::SetEnvironmentVariable('CLAWHUB_SITE', 'https://skill.xfyun.cn', 'User') [Environment]::SetEnvironmentVariable('CLAWHUB_REGISTRY', 'https://skill.xfyun.cn', 'User') -# 或者临时设置（当前会话） +# Or temporary setting (current session) $env:CLAWHUB_SITE = 'https://skill.xfyun.cn' $env:CLAWHUB_REGISTRY = 'https://skill.xfyun.cn' ``` -### 使用 CLI 标志（单次命令） +### Using CLI Flags (Single Command) ```bash clawhub --site https://skill.xfyun.cn --registry https://skill.xfyun.cn install ``` -### 前端一键复制 +### One-click Copy from Web UI -SkillHub 网页端的技能详情页会自动显示带有正确环境变量的安装命令，直接复制即可使用。 +The SkillHub skill detail page automatically displays install commands with the correct environment variables pre-configured. Simply copy and use. -## Well-known 发现 +## Well-known Discovery ```http GET /.well-known/clawhub.json ``` -响应： +Response: ```json { @@ -56,7 +56,7 @@ GET /.well-known/clawhub.json } ``` -## 兼容层 API +## Compatibility Layer APIs ### Whoami @@ -64,7 +64,7 @@ GET /.well-known/clawhub.json GET /api/v1/whoami ``` -响应： +Response: ```json { @@ -74,13 +74,13 @@ GET /api/v1/whoami } ``` -### 搜索 +### Search ```http GET /api/v1/search?q={keyword}&page={page}&limit={limit} ``` -响应： +Response: ```json { @@ -106,13 +106,13 @@ GET /api/v1/search?q={keyword}&page={page}&limit={limit} } ``` -### 解析 +### Resolve ```http GET /api/v1/resolve?slug={slug}&version={version} ``` -响应： +Response: ```json { @@ -122,13 +122,13 @@ GET /api/v1/resolve?slug={slug}&version={version} } ``` -### 下载 +### Download ```http GET /api/v1/download/{slug}/{version} ``` -### 发布 +### Publish ```http POST /api/v1/publish @@ -137,7 +137,7 @@ Content-Type: multipart/form-data file: ``` -响应： +Response: ```json { @@ -147,13 +147,13 @@ file: } ``` -## 坐标映射 +## Coordinate Mapping -| SkillHub 坐标 | ClawHub canonical slug | -|---------------|------------------------| +| SkillHub Coordinate | ClawHub canonical slug | +|---------------------|------------------------| | `@global/my-skill` | `my-skill` | | `@team-name/my-skill` | `team-name--my-skill` | -## 下一步 +## Next Steps -- [系统架构](../architecture/overview) - 了解架构设计 +- [System Architecture](../architecture/overview) - Understand architecture design diff --git a/document/docs/04-developer/api/overview.md b/document/docs/04-developer/api/overview.md index 7508d483..b7e2a1d0 100644 --- a/document/docs/04-developer/api/overview.md +++ b/document/docs/04-developer/api/overview.md @@ -1,52 +1,52 @@ --- -title: API 概述 +title: API Overview sidebar_position: 1 -description: SkillHub API 概述 +description: SkillHub API overview --- -# API 概述 +# API Overview -SkillHub 提供 RESTful API 用于集成和自动化。 +SkillHub provides RESTful APIs for integration and automation. -## API 分类 +## API Categories -### 公开 API -- 技能搜索 -- 技能详情 -- 版本列表 -- 下载技能 -- 无需认证（PUBLIC 技能） +### Public APIs +- Skill search +- Skill details +- Version list +- Download skills +- No authentication required (for PUBLIC skills) -### 认证 API -- 发布技能 -- 收藏/评分 -- 命名空间管理 -- 需要登录或 Bearer Token +### Authenticated APIs +- Publish skills +- Favorites/ratings +- Namespace management +- Requires login or Bearer Token -### CLI 兼容层 -- 兼容 ClawHub CLI 协议 -- 现有工具可无缝迁移 +### CLI Compatibility Layer +- ClawHub CLI protocol compatible +- Existing tools can migrate seamlessly -## 响应格式 +## Response Format -### 统一响应结构 +### Unified Response Structure ```json { "code": 0, - "msg": "成功", + "msg": "Success", "data": {}, "timestamp": "2026-03-15T06:00:00Z", "requestId": "req-123" } ``` -### 分页响应 +### Pagination Response ```json { "code": 0, - "msg": "成功", + "msg": "Success", "data": { "items": [], "total": 100, @@ -58,29 +58,29 @@ SkillHub 提供 RESTful API 用于集成和自动化。 } ``` -## 认证方式 +## Authentication Methods ### Session Cookie -Web 端使用 Session Cookie 认证。 +Web side uses Session Cookie authentication. ### Bearer Token -CLI 和 API 集成使用 Bearer Token： +CLI and API integration use Bearer Token: ```bash Authorization: Bearer ``` ### API Token -可创建长期有效的 API Token 用于自动化。 +Can create long-lived API Tokens for automation. -## 幂等性 +## Idempotency -所有写操作支持 `X-Request-Id` 请求头实现幂等： +All write operations support `X-Request-Id` header for idempotency: ```bash X-Request-Id: ``` -## 下一步 +## Next Steps -- [公开 API](./public) - 查看公开接口 +- [Public APIs](./public) - View public endpoints diff --git a/document/docs/04-developer/api/public.md b/document/docs/04-developer/api/public.md index e006994e..7e8a01cc 100644 --- a/document/docs/04-developer/api/public.md +++ b/document/docs/04-developer/api/public.md @@ -1,72 +1,72 @@ --- -title: 公开 API +title: Public APIs sidebar_position: 2 -description: 无需认证的公开 API +description: Public APIs without authentication --- -# 公开 API +# Public APIs -## 技能搜索 +## Skill Search ```http GET /api/v1/skills?keyword=...&namespace=...&page=1&size=20 ``` **Query Parameters:** -- `keyword`: 搜索关键词 -- `namespace`: 命名空间筛选 -- `page`: 页码 -- `size`: 每页数量 +- `keyword`: Search keyword +- `namespace`: Namespace filter +- `page`: Page number +- `size`: Page size -## 技能详情 +## Skill Details ```http GET /api/v1/skills/{namespace}/{slug} ``` -## 版本列表 +## Version List ```http GET /api/v1/skills/{namespace}/{slug}/versions ``` -## 版本详情 +## Version Details ```http GET /api/v1/skills/{namespace}/{slug}/versions/{version} ``` -## 文件清单 +## File List ```http GET /api/v1/skills/{namespace}/{slug}/versions/{version}/files ``` -## 下载技能 +## Download Skill ```http GET /api/v1/skills/{namespace}/{slug}/download GET /api/v1/skills/{namespace}/{slug}/versions/{version}/download ``` -## 解析版本 +## Resolve Version ```http GET /api/v1/skills/{namespace}/{slug}/resolve?version=...&tag=... ``` -## 命名空间列表 +## Namespace List ```http GET /api/v1/namespaces ``` -## 命名空间详情 +## Namespace Details ```http GET /api/v1/namespaces/{slug} ``` -## 下一步 +## Next Steps -- [认证 API](./authenticated) - 查看认证接口 +- [Authenticated APIs](./authenticated) - View authenticated endpoints diff --git a/document/docs/04-developer/architecture/_category_.json b/document/docs/04-developer/architecture/_category_.json index 81a75cfc..b7a3ae9d 100644 --- a/document/docs/04-developer/architecture/_category_.json +++ b/document/docs/04-developer/architecture/_category_.json @@ -1,4 +1,4 @@ { - "label": "架构设计", + "label": "Architecture", "position": 2 } diff --git a/document/docs/04-developer/architecture/domain-model.md b/document/docs/04-developer/architecture/domain-model.md index 1f6a4467..fb760e38 100644 --- a/document/docs/04-developer/architecture/domain-model.md +++ b/document/docs/04-developer/architecture/domain-model.md @@ -1,77 +1,77 @@ --- -title: 领域模型 +title: Domain Model sidebar_position: 2 -description: 核心领域实体和关系 +description: Core domain entities and relationships --- -# 领域模型 +# Domain Model -## 核心实体 +## Core Entities -### Namespace（命名空间） +### Namespace -| 字段 | 类型 | 说明 | -|------|------|------| -| id | bigint | 主键 | -| slug | varchar(64) | URL 友好标识 | -| display_name | varchar(128) | 展示名 | +| Field | Type | Description | +|-------|------|-------------| +| id | bigint | Primary key | +| slug | varchar(64) | URL-friendly identifier | +| display_name | varchar(128) | Display name | | type | enum | `GLOBAL` / `TEAM` | -| description | text | 描述 | +| description | text | Description | | status | enum | `ACTIVE` / `FROZEN` / `ARCHIVED` | -### NamespaceMember（命名空间成员） +### NamespaceMember -| 字段 | 类型 | 说明 | -|------|------|------| -| id | bigint | 主键 | -| namespace_id | bigint | 命名空间 ID | -| user_id | varchar(128) | 用户 ID | +| Field | Type | Description | +|-------|------|-------------| +| id | bigint | Primary key | +| namespace_id | bigint | Namespace ID | +| user_id | varchar(128) | User ID | | role | enum | `OWNER` / `ADMIN` / `MEMBER` | -### Skill（技能） +### Skill -| 字段 | 类型 | 说明 | -|------|------|------| -| id | bigint | 主键 | -| namespace_id | bigint | 所属命名空间 | -| slug | varchar(128) | URL 友好标识 | -| display_name | varchar(256) | 展示名 | -| summary | varchar(512) | 摘要 | -| owner_id | varchar(128) | 主要维护人 | +| Field | Type | Description | +|-------|------|-------------| +| id | bigint | Primary key | +| namespace_id | bigint | Parent namespace | +| slug | varchar(128) | URL-friendly identifier | +| display_name | varchar(256) | Display name | +| summary | varchar(512) | Summary | +| owner_id | varchar(128) | Primary maintainer | | visibility | enum | `PUBLIC` / `NAMESPACE_ONLY` / `PRIVATE` | | status | enum | `ACTIVE` / `HIDDEN` / `ARCHIVED` | -| latest_version_id | bigint | 最新已发布版本 | +| latest_version_id | bigint | Latest published version | -**唯一约束**：`(namespace_id, slug)` +**Unique constraint**: `(namespace_id, slug)` -### SkillVersion（技能版本） +### SkillVersion -| 字段 | 类型 | 说明 | -|------|------|------| -| id | bigint | 主键 | -| skill_id | bigint | 技能 ID | -| version | varchar(32) | semver 版本号 | +| Field | Type | Description | +|-------|------|-------------| +| id | bigint | Primary key | +| skill_id | bigint | Skill ID | +| version | varchar(32) | semver version | | status | enum | `DRAFT` / `PENDING_REVIEW` / `PUBLISHED` / `REJECTED` / `YANKED` | -| manifest_json | json | 文件清单 | -| parsed_metadata_json | json | SKILL.md 解析结果 | +| manifest_json | json | File manifest | +| parsed_metadata_json | json | SKILL.md parsed result | -**唯一约束**：`(skill_id, version)` +**Unique constraint**: `(skill_id, version)` -### SkillTag（技能标签） +### SkillTag -| 字段 | 类型 | 说明 | -|------|------|------| -| id | bigint | 主键 | -| skill_id | bigint | 技能 ID | -| tag_name | varchar(64) | 标签名 | -| target_version_id | bigint | 目标版本 | +| Field | Type | Description | +|-------|------|-------------| +| id | bigint | Primary key | +| skill_id | bigint | Skill ID | +| tag_name | varchar(64) | Tag name | +| target_version_id | bigint | Target version | -**唯一约束**：`(skill_id, tag_name)` +**Unique constraint**: `(skill_id, tag_name)` -## 坐标系统 +## Coordinate System -技能完整寻址：`@{namespace_slug}/{skill_slug}` +Full skill address: `@{namespace_slug}/{skill_slug}` -## 下一步 +## Next Steps -- [安全架构](./security) - 安全设计 +- [Security Architecture](./security) - Security design diff --git a/document/docs/04-developer/architecture/overview.md b/document/docs/04-developer/architecture/overview.md index e00f6703..37b87afe 100644 --- a/document/docs/04-developer/architecture/overview.md +++ b/document/docs/04-developer/architecture/overview.md @@ -1,49 +1,49 @@ --- -title: 系统架构 +title: System Architecture sidebar_position: 1 -description: SkillHub 系统架构概览 +description: SkillHub system architecture overview --- -# 系统架构 +# System Architecture -## 架构原则 +## Architecture Principles -- **单体优先**：一期采用模块化单体，不拆微服务 -- **依赖倒置**：领域层不依赖基础设施 -- **可替换边界**：搜索、存储都有 SPI 抽象 +- **Monolith-first**: Phase 1 uses modular monolith, no microservices +- **Dependency Inversion**: Domain layer does not depend on infrastructure +- **Replaceable Boundaries**: Search and storage both have SPI abstractions -## 模块结构 +## Module Structure ``` server/ -├── skillhub-app/ # 启动、配置装配、Controller -├── skillhub-domain/ # 领域模型 + 领域服务 + 应用服务 -├── skillhub-auth/ # OAuth2 认证 + RBAC + 授权判定 -├── skillhub-search/ # 搜索 SPI + PostgreSQL 全文实现 -├── skillhub-storage/ # 对象存储抽象 + LocalFile/S3 -└── skillhub-infra/ # JPA、通用工具、配置基础 +├── skillhub-app/ # Startup, configuration assembly, Controllers +├── skillhub-domain/ # Domain models + domain services + application services +├── skillhub-auth/ # OAuth2 authentication + RBAC + authorization decisions +├── skillhub-search/ # Search SPI + PostgreSQL full-text implementation +├── skillhub-storage/ # Object storage abstraction + LocalFile/S3 +└── skillhub-infra/ # JPA, utilities, configuration foundation ``` -## 模块依赖 +## Module Dependencies ``` app → domain, auth, search, storage, infra infra → domain auth → domain search → domain -storage → (独立) +storage → (independent) ``` -## 技术栈 +## Tech Stack -| 层级 | 技术 | 版本 | -|------|------|------| -| 运行时 | Java | 21 | -| 框架 | Spring Boot | 3.2.3 | -| 数据库 | PostgreSQL | 16.x | -| 缓存/会话 | Redis | 7.x | +| Layer | Technology | Version | +|-------|------------|---------| +| Runtime | Java | 21 | +| Framework | Spring Boot | 3.2.3 | +| Database | PostgreSQL | 16.x | +| Cache/Session | Redis | 7.x | -## 部署架构 +## Deployment Architecture ``` ┌──────────────┐ @@ -64,6 +64,6 @@ storage → (独立) PostgreSQL Redis ``` -## 下一步 +## Next Steps -- [领域模型](./domain-model) - 核心实体 +- [Domain Model](./domain-model) - Core entities diff --git a/document/docs/04-developer/architecture/security.md b/document/docs/04-developer/architecture/security.md index 2280d1d9..d967dc40 100644 --- a/document/docs/04-developer/architecture/security.md +++ b/document/docs/04-developer/architecture/security.md @@ -1,71 +1,71 @@ --- -title: 安全架构 +title: Security Architecture sidebar_position: 3 -description: 安全架构设计 +description: Security architecture design --- -# 安全架构 +# Security Architecture -## 认证架构 +## Authentication Architecture -### OAuth2 登录 +### OAuth2 Login -- 基于 Spring Security OAuth2 Client -- 一期支持 GitHub -- 架构支持扩展多 Provider +- Based on Spring Security OAuth2 Client +- Phase 1 supports GitHub +- Architecture supports extending multiple providers -### CLI 认证 +### CLI Authentication - OAuth Device Flow -- Web 授权后签发 CLI 凭证 -- 支持 API Token +- Web authorization issues CLI credentials +- Supports API Token -### Session 管理 +### Session Management - Spring Session + Redis -- 分布式 Session 共享 -- 支持多 Pod 部署 +- Distributed session sharing +- Supports multi-pod deployment -## 授权架构 +## Authorization Architecture -### 平台角色 +### Platform Roles -| 角色 | 权限 | -|------|------| -| `SUPER_ADMIN` | 所有权限 | -| `SKILL_ADMIN` | 技能治理 | -| `USER_ADMIN` | 用户治理 | -| `AUDITOR` | 审计只读 | +| Role | Permissions | +|------|-------------| +| `SUPER_ADMIN` | All permissions | +| `SKILL_ADMIN` | Skill governance | +| `USER_ADMIN` | User governance | +| `AUDITOR` | Audit read-only | -### 命名空间角色 +### Namespace Roles -| 角色 | 权限 | -|------|------| -| `OWNER` | 命名空间所有者 | -| `ADMIN` | 审核、成员管理 | -| `MEMBER` | 发布技能 | +| Role | Permissions | +|------|-------------| +| `OWNER` | Namespace owner | +| `ADMIN` | Review, member management | +| `MEMBER` | Publish skills | -### 可见性规则 +### Visibility Rules -| 可见性 | 谁可访问 | -|--------|---------| -| `PUBLIC` | 任何人（匿名） | -| `NAMESPACE_ONLY` | 命名空间成员 | -| `PRIVATE` | owner + 命名空间 ADMIN | +| Visibility | Who can access | +|------------|----------------| +| `PUBLIC` | Anyone (anonymous) | +| `NAMESPACE_ONLY` | Namespace members | +| `PRIVATE` | owner + namespace ADMIN | -## 审计 +## Auditing -所有关键操作同步写入审计日志： -- 发布、下载、删除 -- 审核通过、拒绝 -- 权限变更 -- 配置变更 +All critical operations synchronously write to audit logs: +- Publish, download, delete +- Review approval, rejection +- Permission changes +- Configuration changes -## 限流 +## Rate Limiting -- Ingress 层基础限流（Nginx） -- 应用层精细限流（Redis 滑动窗口） +- Ingress layer basic rate limiting (Nginx) +- Application layer fine-grained rate limiting (Redis sliding window) -## 下一步 +## Next Steps -- [技能协议](../plugins/skill-protocol) - 技能包规范 +- [Skill Protocol](../plugins/skill-protocol) - Skill package specification diff --git a/document/docs/04-developer/plugins/_category_.json b/document/docs/04-developer/plugins/_category_.json index ac3a412e..f6f56166 100644 --- a/document/docs/04-developer/plugins/_category_.json +++ b/document/docs/04-developer/plugins/_category_.json @@ -1,4 +1,4 @@ { - "label": "扩展与集成", + "label": "Extensions & Integrations", "position": 3 } diff --git a/document/docs/04-developer/plugins/skill-protocol.md b/document/docs/04-developer/plugins/skill-protocol.md index bb136814..7033af7a 100644 --- a/document/docs/04-developer/plugins/skill-protocol.md +++ b/document/docs/04-developer/plugins/skill-protocol.md @@ -1,14 +1,14 @@ --- -title: 技能协议 +title: Skill Protocol sidebar_position: 1 -description: SKILL.md 规范和技能包协议 +description: SKILL.md specification and skill package protocol --- -# 技能协议 +# Skill Protocol -## SKILL.md 规范 +## SKILL.md Specification -### 基本格式 +### Basic Format ```markdown --- @@ -16,53 +16,53 @@ name: my-skill description: When to use this skill --- -# Markdown 正文 +# Markdown Body -技能指令内容... +Skill instruction content... ``` -### 必需字段 +### Required Fields -| 字段 | 说明 | -|------|------| -| `name` | 技能标识，kebab-case | -| `description` | 技能简短描述 | +| Field | Description | +|-------|-------------| +| `name` | Skill identifier, kebab-case | +| `description` | Brief skill description | -### 扩展字段 +### Extension Fields -| 字段 | 说明 | -|------|------| -| `x-astron-category` | 分类标签 | -| `x-astron-runtime` | 运行时要求 | -| `x-astron-min-version` | 最低版本要求 | +| Field | Description | +|-------|-------------| +| `x-astron-category` | Category tag | +| `x-astron-runtime` | Runtime requirement | +| `x-astron-min-version` | Minimum version requirement | -## 技能包结构 +## Skill Package Structure ``` my-skill/ -├── SKILL.md # 主入口文件（必需） -├── references/ # 参考资料（可选） -├── scripts/ # 脚本（可选） -└── assets/ # 静态资源（可选） +├── SKILL.md # Main entry file (required) +├── references/ # References (optional) +├── scripts/ # Scripts (optional) +└── assets/ # Static assets (optional) ``` -## 文件校验 +## File Validation -- 根目录必须包含 `SKILL.md` -- 文件类型白名单 -- 单文件大小限制：1MB -- 总包大小限制：10MB -- 文件数量限制：100 个 +- Root directory must contain `SKILL.md` +- File type whitelist +- Single file size limit: 1MB +- Total package size limit: 10MB +- File count limit: 100 -## 客户端安装目录 +## Client Installation Directory -按以下优先级安装： +Install by the following priority: 1. `./.agent/skills/` 2. `~/.agent/skills/` 3. `./.claude/skills/` 4. `~/.claude/skills/` -## 下一步 +## Next Steps -- [存储 SPI](./storage-spi) - 扩展存储后端 +- [Storage SPI](./storage-spi) - Extend storage backend diff --git a/document/docs/04-developer/plugins/storage-spi.md b/document/docs/04-developer/plugins/storage-spi.md index 3b7f4dba..f3a0a57d 100644 --- a/document/docs/04-developer/plugins/storage-spi.md +++ b/document/docs/04-developer/plugins/storage-spi.md @@ -1,12 +1,12 @@ --- -title: 存储 SPI +title: Storage SPI sidebar_position: 2 -description: 存储服务提供方扩展 +description: Storage service provider extension --- -# 存储 SPI +# Storage SPI -## SPI 接口 +## SPI Interface ```java public interface ObjectStorageService { @@ -17,61 +17,38 @@ public interface ObjectStorageService { } ``` -## 内置实现 +## Built-in Implementations ### LocalFileStorageService -本地文件系统实现，用于开发环境。 +Local filesystem implementation for development environment. ### S3StorageService -S3 协议兼容实现，支持： +S3 protocol compatible implementation, supports: - AWS S3 - MinIO -- 阿里云 OSS -- 腾讯云 COS -- 其他 S3 兼容存储 +- Alibaba Cloud OSS +- Tencent Cloud COS +- Other S3-compatible storage -## 配置 - -### 静态凭据（Access Key / Secret Key） +## Configuration ```bash -# 选择存储提供方 +# Select storage provider SKILLHUB_STORAGE_PROVIDER=s3 -# S3 配置 +# S3 configuration SKILLHUB_STORAGE_S3_ENDPOINT=https://s3.example.com SKILLHUB_STORAGE_S3_BUCKET=skillhub SKILLHUB_STORAGE_S3_ACCESS_KEY=xxx SKILLHUB_STORAGE_S3_SECRET_KEY=xxx ``` -### IAM 认证 +## Custom Implementation -部署在 AWS 上时，可以不配置 Access Key / Secret Key，让 SDK 自动使用 IAM 角色认证（[Default Credentials Provider Chain](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-chain.html)）： +Implement `ObjectStorageService` interface and register as Spring Bean. -```bash -SKILLHUB_STORAGE_PROVIDER=s3 -SKILLHUB_STORAGE_S3_BUCKET=skillhub -SKILLHUB_STORAGE_S3_REGION=us-east-1 -# 留空或不设置 ACCESS_KEY / SECRET_KEY，SDK 自动使用 IAM 认证 -SKILLHUB_STORAGE_S3_ACCESS_KEY= -SKILLHUB_STORAGE_S3_SECRET_KEY= -``` +## Next Steps -支持的 IAM 认证方式（按 SDK 优先级）： -- 环境变量（`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`） -- Java 系统属性 -- Web Identity Token（EKS IRSA） -- AWS 配置文件（`~/.aws/credentials`） -- EC2 Instance Profile -- ECS Task Role - -## 自定义实现 - -实现 `ObjectStorageService` 接口，注册为 Spring Bean 即可。 - -## 下一步 - -- [常见问题](../../reference/faq) - FAQ +- [FAQ](../../reference/faq) - FAQ diff --git a/document/docs/05-reference/_category_.json b/document/docs/05-reference/_category_.json index 15e14d0e..3bad6b7f 100644 --- a/document/docs/05-reference/_category_.json +++ b/document/docs/05-reference/_category_.json @@ -1,8 +1,8 @@ { - "label": "参考资料", + "label": "Reference", "position": 5, "link": { "type": "generated-index", - "description": "FAQ、故障排查和更多资源" + "description": "FAQ, troubleshooting, and more resources" } } diff --git a/document/docs/05-reference/changelog.md b/document/docs/05-reference/changelog.md index de6f5078..3517a921 100644 --- a/document/docs/05-reference/changelog.md +++ b/document/docs/05-reference/changelog.md @@ -1,20 +1,20 @@ --- -title: 变更日志 +title: Changelog sidebar_position: 3 -description: 版本变更历史 +description: Version change history --- -# 变更日志 +# Changelog ## [Unreleased] ### Added -- 初始版本发布 -- 技能发布与管理 -- 命名空间与 RBAC -- 全文搜索 -- ClawHub CLI 兼容层 +- Initial version release +- Skill publishing and management +- Namespace and RBAC +- Full-text search +- ClawHub CLI compatibility layer -## 下一步 +## Next Steps -- [路线图](./roadmap) - 未来规划 +- [Roadmap](./roadmap) - Future plans diff --git a/document/docs/05-reference/faq.md b/document/docs/05-reference/faq.md index eb2d352c..137a90e7 100644 --- a/document/docs/05-reference/faq.md +++ b/document/docs/05-reference/faq.md @@ -1,49 +1,49 @@ --- -title: 常见问题 +title: FAQ sidebar_position: 1 -description: 常见问题解答 +description: Frequently asked questions --- -# 常见问题 +# FAQ -## 部署相关 +## Deployment Related -### 如何修改默认端口？ +### How to change default port? -修改 `.env.release` 中的端口配置。 +Modify port configuration in `.env.release`. -### 如何配置 HTTPS？ +### How to configure HTTPS? -建议使用反向代理（Nginx/Ingress）处理 TLS 终止。 +Recommended to use reverse proxy (Nginx/Ingress) for TLS termination. -### 数据库如何备份？ +### How to backup database? -使用 PostgreSQL 标准备份工具（pg_dump）。 +Use PostgreSQL standard backup tools (pg_dump). -## 使用相关 +## Usage Related -### 如何重置管理员密码？ +### How to reset admin password? -如果忘记管理员密码，可通过环境变量重新设置首登管理员，或直接操作数据库。 +If you forgot admin password, you can reconfigure bootstrap admin via environment variables or directly operate the database. -### 技能包上传失败怎么办？ +### Skill package upload failed? -检查： -1. 文件大小是否超限 -2. 文件类型是否在白名单内 -3. 是否包含必需的 SKILL.md -4. SKILL.md frontmatter 格式是否正确 +Check: +1. Whether file size exceeds limit +2. Whether file type is in whitelist +3. Whether required SKILL.md is included +4. Whether SKILL.md frontmatter format is correct -## 开发相关 +## Development Related -### 如何扩展 OAuth Provider？ +### How to extend OAuth Provider? -参考现有 GitHub 实现，添加新的 OAuth Provider 配置。 +Refer to existing GitHub implementation, add new OAuth Provider configuration. -### 如何自定义搜索实现？ +### How to customize search implementation? -实现 `SearchIndexService` 和 `SearchQueryService` 接口。 +Implement `SearchIndexService` and `SearchQueryService` interfaces. -## 下一步 +## Next Steps -- [故障排查](./troubleshooting) - 问题诊断 +- [Troubleshooting](./troubleshooting) - Problem diagnosis diff --git a/document/docs/05-reference/roadmap.md b/document/docs/05-reference/roadmap.md index 1477856b..fb62facf 100644 --- a/document/docs/05-reference/roadmap.md +++ b/document/docs/05-reference/roadmap.md @@ -1,45 +1,45 @@ --- -title: 路线图 +title: Roadmap sidebar_position: 4 -description: 未来发展路线图 +description: Future development roadmap --- -# 路线图 +# Roadmap -## Phase 1: 基础能力 ✅ +## Phase 1: Foundation ✅ -- GitHub OAuth 登录 -- Session 管理 -- RBAC 权限体系 +- GitHub OAuth login +- Session management +- RBAC permission system -## Phase 2: 技能核心 ✅ +## Phase 2: Skill Core ✅ -- 命名空间管理 -- 技能发布与下载 -- 版本管理 -- PostgreSQL 全文搜索 +- Namespace management +- Skill publishing and download +- Version management +- PostgreSQL full-text search -## Phase 3: 审核与 CLI +## Phase 3: Review and CLI -- 审核流程 -- 技能提升到全局 -- CLI 工具 -- 收藏与评分 +- Review workflow +- Skill promotion to global +- CLI tool +- Favorites and ratings -## Phase 4: 运维与完善 +## Phase 4: Operations and Polish -- 审计日志 -- 管理后台 -- 可观测性 -- 部署优化 +- Audit logs +- Admin dashboard +- Observability +- Deployment optimization -## Phase 5: 高级特性 +## Phase 5: Advanced Features -- 评论与举报 -- 自动安全扫描 -- 向量搜索 -- Webhook 通知 +- Comments and reports +- Automatic security scanning +- Vector search +- Webhook notifications -## 下一步 +## Next Steps -- [快速开始](../getting-started/quick-start) - 开始使用 +- [Quick Start](../getting-started/quick-start) - Get started diff --git a/document/docs/05-reference/troubleshooting.md b/document/docs/05-reference/troubleshooting.md index 492d910f..95716b51 100644 --- a/document/docs/05-reference/troubleshooting.md +++ b/document/docs/05-reference/troubleshooting.md @@ -1,63 +1,63 @@ --- -title: 故障排查 +title: Troubleshooting sidebar_position: 2 -description: 常见问题诊断和解决方案 +description: Common problem diagnosis and solutions --- -# 故障排查 +# Troubleshooting -## 服务无法启动 +## Service Cannot Start -### 检查清单 +### Checklist -1. 检查容器状态：`docker compose ps` -2. 查看服务日志：`docker compose logs ` -3. 验证环境变量：检查 `.env.release` 配置 -4. 检查端口占用：`netstat -tlnp` +1. Check container status: `docker compose ps` +2. View service logs: `docker compose logs ` +3. Verify environment variables: Check `.env.release` configuration +4. Check port occupancy: `netstat -tlnp` -### 常见原因 +### Common Causes -- 端口被占用 -- 数据库连接失败 -- Redis 连接失败 -- 环境变量缺失 +- Port occupied +- Database connection failed +- Redis connection failed +- Environment variables missing -## 上传失败 +## Upload Failed -### 技能包上传失败 +### Skill Package Upload Failed -1. 检查文件大小 -2. 检查文件类型 -3. 检查 SKILL.md 格式 -4. 查看服务端日志 +1. Check file size +2. Check file type +3. Check SKILL.md format +4. View server logs -## 认证问题 +## Authentication Issues -### 无法登录 +### Cannot Login -1. 检查 OAuth 配置 -2. 检查回调地址配置 -3. 检查 `SKILLHUB_PUBLIC_BASE_URL` 配置 +1. Check OAuth configuration +2. Check callback URL configuration +3. Check `SKILLHUB_PUBLIC_BASE_URL` configuration -## 性能问题 +## Performance Issues -### 搜索慢 +### Slow Search -1. 检查 PostgreSQL 全文索引 -2. 考虑升级到 Elasticsearch（后续版本） +1. Check PostgreSQL full-text index +2. Consider upgrading to Elasticsearch (future version) -### 下载慢 +### Slow Download -1. 检查对象存储配置 -2. 检查网络带宽 +1. Check object storage configuration +2. Check network bandwidth -## 获取帮助 +## Get Help -如以上方案无法解决问题： -1. 查看日志 -2. 提交 Issue -3. 联系技术支持 +If above solutions cannot resolve the issue: +1. View logs +2. Submit Issue +3. Contact technical support -## 下一步 +## Next Steps -- [变更日志](./changelog) - 版本历史 +- [Changelog](./changelog) - Version history diff --git a/document/docs/index.md b/document/docs/index.md index 648096ce..e1fd2a94 100644 --- a/document/docs/index.md +++ b/document/docs/index.md @@ -1,101 +1,22 @@ --- -title: SkillHub 文档中心 +title: SkillHub Documentation sidebar_position: 1 -description: 企业级 AI 技能注册表 - 安全可控的技能发布、发现与管理平台 +description: Enterprise-grade open source agent skill registry for governed, self-hosted publishing, discovery, and team collaboration --- # SkillHub -
-
-

🏢 企业级 AI 技能注册表

-

- 安全可控的技能发布、发现与管理平台，保障企业数据主权 -

- -
-
+SkillHub is an enterprise-grade open source agent skill registry for governed, self-hosted publishing, discovery, and collaboration. ---- +## Start Here -## 企业价值 +- [Quick Start](./getting-started/quick-start) - Deploy SkillHub with one command +- [Overview](./getting-started/overview) - Understand product positioning and core concepts +- [Use Cases](./getting-started/use-cases) - See where SkillHub fits in real organizations -
-
-
-
🔐
-

数据主权可控

-

- 自托管部署，数据不离开企业网络；支持私有 S3/MinIO 存储；完整审计链路 -

-
-
-
-
-
🏢
-

治理体系完善

-

- 命名空间隔离；双层审核机制；细粒度 RBAC 权限控制 -

-
-
-
-
-
🔌
-

集成能力强

-

- 兼容 ClawHub CLI；标准 REST API；OAuth2 企业 SSO 集成 -

-
-
-
-
-
📊
-

可观测性完善

-

- 完整审计日志；Prometheus 指标；操作追踪与溯源 -

-
-
-
+## Key Areas ---- - -## 核心功能特性 - -
-
- 版本控制 - 全文搜索 - 命名空间 - 审核流程 - 语义化版本 - 多维度筛选 - RBAC 权限 - 审计日志 -
-
- ---- - -## 快速开始 - -
-
- $ curl -fsSL https://raw.githubusercontent.com/iflytek/skillhub/main/scripts/runtime.sh | sh -s -- up -
-

- 访问 http://localhost:3000 开始使用 -

-
- ---- - -## 下一步 - -- [快速开始](./getting-started/quick-start) - 一键启动 SkillHub -- [产品概述](./getting-started/overview) - 了解更多产品特性 -- [部署指南](./administration/deployment/single-machine) - 生产环境部署 +- [Administration](./administration/deployment/single-machine) - Deployment, security, governance, and operations +- [User Guide](./user-guide/publishing/publish) - Publishing, discovery, collaboration, and promotion workflows +- [Developer Reference](./developer/api/overview) - APIs, architecture, plugins, and protocol compatibility +- [Reference](./reference/faq) - FAQ, troubleshooting, changelog, and roadmap diff --git a/document/docusaurus.config.js b/document/docusaurus.config.js index c3874880..f0122035 100644 --- a/document/docusaurus.config.js +++ b/document/docusaurus.config.js @@ -3,27 +3,26 @@ import { themes as prismThemes } from 'prism-react-renderer'; /** @type {import('@docusaurus/types').Config} */ const config = { title: 'SkillHub', - tagline: '企业级 AI 技能注册表', - favicon: 'img/favicon.ico', + tagline: 'Enterprise-grade Open Source Agent Skill Registry', - url: 'https://skillhub.iflytek.com', + url: 'https://www.astron-skillhub.org', baseUrl: '/', organizationName: 'iflytek', projectName: 'skillhub', i18n: { - defaultLocale: 'zh-CN', - locales: ['zh-CN', 'en'], + defaultLocale: 'en', + locales: ['en', 'zh-CN'], localeConfigs: { - 'zh-CN': { - label: '中文', - htmlLang: 'zh-CN', - }, 'en': { label: 'English', htmlLang: 'en', }, + 'zh-CN': { + label: '中文', + htmlLang: 'zh-CN', + }, }, }, @@ -33,7 +32,7 @@ const config = { /** @type {import('@docusaurus/preset-classic').Options} */ ({ docs: { - routeBasePath: '/', + routeBasePath: '/docs', sidebarPath: './sidebars.js', editUrl: 'https://github.com/iflytek/skillhub/edit/main/document/', }, @@ -47,19 +46,31 @@ const config = { themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ - image: 'img/og-image.png', navbar: { - title: 'SkillHub', logo: { - alt: 'SkillHub Logo', - src: 'img/logo.svg', + alt: 'Astron SkillHub Logo', + src: 'img/astron-skillhub-logo.svg', }, items: [ { - type: 'docSidebar', - sidebarId: 'docsSidebar', + to: '/docs/getting-started/quick-start', position: 'left', - label: '文档', + label: 'Quick Start', + }, + { + to: '/docs/getting-started/overview', + position: 'left', + label: 'Overview', + }, + { + to: '/docs/user-guide/publishing/publish', + position: 'left', + label: 'Publish Workflow', + }, + { + to: '/docs/administration/deployment/single-machine', + position: 'left', + label: 'Single Node', }, { type: 'localeDropdown', @@ -76,24 +87,24 @@ const config = { style: 'dark', links: [ { - title: '文档', + title: 'Documentation', items: [ { - label: '快速开始', - to: '/getting-started/quick-start', + label: 'Quick Start', + to: '/docs/getting-started/quick-start', }, { - label: '部署指南', - to: '/administration/deployment/single-machine', + label: 'Deployment', + to: '/docs/administration/deployment/single-machine', }, { - label: 'API 参考', - to: '/developer/api/overview', + label: 'API Reference', + to: '/docs/developer/api/overview', }, ], }, { - title: '社区', + title: 'Community', items: [ { label: 'GitHub', @@ -104,12 +115,74 @@ const config = { ], copyright: `Copyright © ${new Date().getFullYear()} iFlytek. Built with Docusaurus.`, }, + metadata: [ + { + name: 'keywords', + content: 'SkillHub, skill registry, agent skills, self-hosted, enterprise ai', + }, + ], prism: { theme: prismThemes.github, darkTheme: prismThemes.dracula, additionalLanguages: ['java', 'bash', 'yaml', 'json'], }, }), + plugins: [ + [ + '@docusaurus/plugin-client-redirects', + { + createRedirects(existingPath) { + if (existingPath === '/docs/' || existingPath === '/zh-CN/docs/') { + return undefined; + } + + if (existingPath.includes('/docs/')) { + return [existingPath.replace('/docs', '')]; + } + + return undefined; + }, + redirects: [ + { + from: ['/quickstart.html'], + to: '/docs/getting-started/quick-start', + }, + { + from: ['/introduction.html'], + to: '/docs/getting-started/overview', + }, + { + from: ['/faq.html'], + to: '/docs/reference/faq', + }, + { + from: ['/guide/skill-publish.html'], + to: '/docs/user-guide/publishing/publish', + }, + { + from: ['/guide/skill-discovery.html'], + to: '/docs/user-guide/discovery/search', + }, + { + from: ['/guide/namespace.html'], + to: '/docs/user-guide/collaboration/namespaces', + }, + { + from: ['/guide/review.html'], + to: '/docs/administration/governance/review-workflow', + }, + { + from: ['/guide/social.html'], + to: '/docs/user-guide/discovery/ratings', + }, + { + from: ['/guide/scanner.html'], + to: '/docs/administration/security/scanner', + }, + ], + }, + ], + ], }; export default config; diff --git a/document/i18n/en/docusaurus-plugin-content-docs/current/02-administration/security/authorization.md b/document/i18n/en/docusaurus-plugin-content-docs/current/02-administration/security/authorization.md index ee411ca4..4c0359be 100644 --- a/document/i18n/en/docusaurus-plugin-content-docs/current/02-administration/security/authorization.md +++ b/document/i18n/en/docusaurus-plugin-content-docs/current/02-administration/security/authorization.md @@ -23,7 +23,7 @@ The database migration seeds only 4 explicit platform roles: | Role | Code | Effective behavior | |------|------|--------------------| -| Super Admin | `SUPER_ADMIN` | Has all permissions. `RbacService#getUserPermissions` returns all permission codes for this role. Can access all endpoints available to `SUPER_ADMIN` / `SKILL_ADMIN` / `USER_ADMIN` / `AUDITOR`. Can assign `SUPER_ADMIN`. Can bypass namespace membership checks during publish and auto-publish directly. Can approve their own promotion request. For normal review tasks, the self-submission exception is also only bypassed by `SUPER_ADMIN`. | +| Super Admin | `SUPER_ADMIN` | Has all permissions. `RbacService#getUserPermissions` returns all permission codes for this role. Can access all endpoints available to `SUPER_ADMIN` / `SKILL_ADMIN` / `USER_ADMIN` / `AUDITOR`. Can assign `SUPER_ADMIN`. Can bypass namespace membership checks during publish and auto-publish directly. Still cannot approve their own promotion request, and for normal review tasks the self-submission exception is only bypassed by `SUPER_ADMIN`. | | Skill Admin | `SKILL_ADMIN` | Can access skill governance admin endpoints. Can hide/unhide skills, yank versions, and resolve/dismiss skill reports. Can review global namespace review tasks, promotion requests, and governance inbox items for review/promotion/report. Cannot manage users or read audit logs. | | User Admin | `USER_ADMIN` | Can access user management endpoints. Can list users, approve users, enable/disable users, and change platform roles. Cannot assign `SUPER_ADMIN`. Cannot perform skill governance or read audit logs. | | Auditor | `AUDITOR` | Read-only audit access. Can access `/api/v1/admin/audit-logs` and `/actuator/prometheus`. In the governance workbench this role can read activity, but cannot process review/promotion/report items and cannot manage users or skills. | diff --git a/document/i18n/en/docusaurus-plugin-content-docs/current/02-administration/security/scanner.md b/document/i18n/en/docusaurus-plugin-content-docs/current/02-administration/security/scanner.md new file mode 100644 index 00000000..01a86c95 --- /dev/null +++ b/document/i18n/en/docusaurus-plugin-content-docs/current/02-administration/security/scanner.md @@ -0,0 +1,104 @@ +--- +title: Security Scanning +sidebar_position: 4 +description: Use Skill Scanner to add automated security checks to the skill publish pipeline +--- + +# Security Scanning + +SkillHub can integrate `skill-scanner` into the publish pipeline to automatically inspect uploaded skill packages and persist the results as security audit records. + +## Scan Flow + +When scanning is enabled, the publish flow becomes: + +1. A user publishes a skill package +2. The backend creates a version and moves it to `SCANNING` +3. The backend enqueues a scan task +4. `skill-scanner` consumes the task and runs analysis +5. The result is stored in `security_audit` +6. The version moves to `PENDING_REVIEW`, or to `SCAN_FAILED` after final retry exhaustion +7. The existing human review workflow continues afterward + +## Typical Use Cases + +- Add automated risk checks before manual review +- Retain scan results and audit evidence for governance +- Detect suspicious code, leaked secrets, or risky behavior patterns in skill packages + +## Runtime Modes + +Two modes are supported: + +- `local`: the backend passes a filesystem path to the scanner, suitable for shared filesystem setups +- `upload`: the backend uploads the package archive directly, suitable for Docker, Kubernetes, and split deployments + +Recommended usage: + +- Local development: prefer `local` +- Production, Kubernetes, or split services: prefer `upload` + +## Key Configuration + +Core backend configuration: + +```yaml +skillhub: + security: + scanner: + enabled: false + base-url: http://localhost:8000 + health-path: /health + scan-path: /scan-upload + mode: upload + connect-timeout-ms: 5000 + read-timeout-ms: 300000 + retry-max-attempts: 3 +``` + +Common environment variables: + +- `SKILLHUB_SECURITY_SCANNER_ENABLED` +- `SKILLHUB_SECURITY_SCANNER_URL` +- `SKILLHUB_SECURITY_SCANNER_MODE` +- `SKILLHUB_SCAN_STREAM_KEY` +- `SKILLHUB_SCAN_STREAM_GROUP` + +## How To Verify + +After enabling scanning, validate it with these steps: + +1. Publish a test skill package +2. Confirm the version first moves to `SCANNING` +3. Confirm a `security_audit` record is created +4. Confirm the version eventually moves to `PENDING_REVIEW` or `SCAN_FAILED` +5. Call the security audit API to inspect the result + +```text +GET /api/v1/skills/{skillId}/versions/{versionId}/security-audit +``` + +## Result Fields + +Security audit results usually include: + +- `scanId` +- `scannerType` +- `verdict` +- `isSafe` +- `maxSeverity` +- `findingsCount` +- `findings` +- `scanDurationSeconds` +- `scannedAt` + +## Deployment Recommendations + +- Keep scanning disabled at first in local environments, then enable it after the main flow is stable +- Use `upload` mode in Kubernetes to avoid relying on a shared writable filesystem +- In production, keep scan results alongside human review records as governance evidence + +## Next Steps + +- [Review Workflow](../governance/review-workflow) - Understand the approval flow after scanning +- [Deployment Configuration](../deployment/configuration) - Review deployment-related settings diff --git a/document/i18n/en/docusaurus-plugin-content-docs/current/04-developer/plugins/storage-spi.md b/document/i18n/en/docusaurus-plugin-content-docs/current/04-developer/plugins/storage-spi.md index 2667e615..f3a0a57d 100644 --- a/document/i18n/en/docusaurus-plugin-content-docs/current/04-developer/plugins/storage-spi.md +++ b/document/i18n/en/docusaurus-plugin-content-docs/current/04-developer/plugins/storage-spi.md @@ -34,8 +34,6 @@ S3 protocol compatible implementation, supports: ## Configuration -### Static Credentials (Access Key / Secret Key) - ```bash # Select storage provider SKILLHUB_STORAGE_PROVIDER=s3 @@ -47,27 +45,6 @@ SKILLHUB_STORAGE_S3_ACCESS_KEY=xxx SKILLHUB_STORAGE_S3_SECRET_KEY=xxx ``` -### IAM Authentication - -When deployed on AWS, you can omit the Access Key / Secret Key and let the SDK use IAM role authentication via the [Default Credentials Provider Chain](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-chain.html): - -```bash -SKILLHUB_STORAGE_PROVIDER=s3 -SKILLHUB_STORAGE_S3_BUCKET=skillhub -SKILLHUB_STORAGE_S3_REGION=us-east-1 -# Leave ACCESS_KEY / SECRET_KEY blank to use IAM authentication -SKILLHUB_STORAGE_S3_ACCESS_KEY= -SKILLHUB_STORAGE_S3_SECRET_KEY= -``` - -Supported IAM authentication methods (in SDK priority order): -- Environment variables (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`) -- Java system properties -- Web Identity Token (EKS IRSA) -- AWS config file (`~/.aws/credentials`) -- EC2 Instance Profile -- ECS Task Role - ## Custom Implementation Implement `ObjectStorageService` interface and register as Spring Bean. diff --git a/document/i18n/en/docusaurus-plugin-content-docs/current/index.md b/document/i18n/en/docusaurus-plugin-content-docs/current/index.md index 21632c45..69b05a4b 100644 --- a/document/i18n/en/docusaurus-plugin-content-docs/current/index.md +++ b/document/i18n/en/docusaurus-plugin-content-docs/current/index.md @@ -1,81 +1,125 @@ --- title: SkillHub Documentation sidebar_position: 1 -description: Enterprise-grade AI Skill Registry - Secure, controllable skill publishing, discovery, and management platform +description: Enterprise-grade open source agent skill registry for governed, self-hosted publishing, discovery, and team collaboration --- # SkillHub
-

🏢 Enterprise-grade AI Skill Registry

-

- Secure, controllable skill publishing, discovery, and management platform with full enterprise data sovereignty -

-
- Deploy Now - Learn More +
+
+
Self-hosted Registry for Agent Skills
+

Ship reusable AI skills with governed discovery, review, and deployment.

+
{`Astron SkillHub gives teams a polished internal registry for publishing, discovering, versioning, and operating reusable agent skill packages without the usual AI-generated design smell.`}
+ +
+ Semantic versioning + Namespace governance + Security scanning + CLI compatibility +
+
+
+
+ Astron SkillHub +
+ + Agentic AI Foundation (AAIF) + +
AAIF Associate Member
+
+
+
+
+ 1 + Registry for teams, governance, and runtime docs +
+
+ 3 + Core workflows: publish, discover, review +
+
+ 24/7 + Suitable for always-on internal skill operations +
+
+
--- -## Enterprise Value +## Why Teams Choose SkillHub -
-
-
-
🔐
-

Data Sovereignty

-

- Self-hosted deployment, data stays within your network; private S3/MinIO storage; complete audit trail -

+
+
+
Publishing
+

Versioned delivery without registry chaos

+
{`Semantic versioning, channel tags, and immutable package history make skill publishing feel predictable for both platform teams and daily contributors.`}
+
+ Semantic versioning + Tags like beta / stable / latest + Download and rollback friendly
-
-
-
🏢
-

Complete Governance

-

- Namespace isolation; two-tier review workflow; fine-grained RBAC access control -

-
+
+
Discovery
+

Search that respects permissions

+
{`Full-text search and structured filters help users find the right skill quickly while still honoring namespace visibility and governance boundaries.`}
-
-
-
🔌
-

Strong Integration

-

- ClawHub CLI compatible; standard REST API; OAuth2 enterprise SSO integration -

-
+
+
Collaboration
+

Namespaces built for real teams

+
{`Organize skills by owner, domain, or department and pair that structure with Owner, Admin, and Member roles that match enterprise workflows.`}
-
-
-
📊
-

Full Observability

-

- Complete audit logs; Prometheus metrics; operation tracking and traceability -

-
+
+
Governance
+

Review, audit, and promote with confidence

+
{`Promotion review flows, audit logs, and optional security scanning make it easier to move skills from local innovation to governed organizational reuse.`}
--- -## Core Features +## Built For Mature Delivery -
+
+
+

Less AI-looking chrome, more product-grade clarity

+
{`The public docs experience is tuned for cleaner typography, tighter spacing, stronger visual hierarchy, and fewer generic gradients so the brand feels deliberate rather than over-generated.`}
+
+
+

Designed around modern system thinking

+
{`The refreshed layout borrows the discipline of modern component systems such as shadcn/ui and utility-first design tokens, even though this site remains a Docusaurus documentation experience.`}
+
+
+

International first, localized by default switch

+
{`English now leads as the default locale for broader reach, while the Chinese translation remains one click away through the built-in locale switcher.`}
+
+
+ +--- + +## Current Coverage + +
+ Self-hosted Version Control Full-text Search Namespaces Review Workflow Semantic Versioning - Multi-dimensional Filtering RBAC Permissions Audit Logs + Security Scanning + CLI Compatibility
@@ -83,13 +127,24 @@ description: Enterprise-grade AI Skill Registry - Secure, controllable skill pub ## Quick Start -
+
$ curl -fsSL https://raw.githubusercontent.com/iflytek/skillhub/main/scripts/runtime.sh | sh -s -- up
-

- Visit http://localhost:3000 to get started -

+
+
+ Default Admin + admin / ChangeMe!2026 +
+
+ Local Web UI + http://localhost:3000 +
+
+ Registry API + http://localhost:8080 +
+
--- @@ -97,5 +152,6 @@ description: Enterprise-grade AI Skill Registry - Secure, controllable skill pub ## Next Steps - [Quick Start](./getting-started/quick-start) - Deploy SkillHub with one command -- [Overview](./getting-started/overview) - Learn more about product features -- [Deployment Guide](./administration/deployment/single-machine) - Production deployment +- [Overview](./getting-started/overview) - Learn how the platform is positioned +- [Publish Workflow](./user-guide/publishing/publish) - Publish your first skill package +- [Single Machine Deployment](./administration/deployment/single-machine) - Run the production-ready stack diff --git a/document/i18n/zh-CN/code.json b/document/i18n/zh-CN/code.json new file mode 100644 index 00000000..dc31f38e --- /dev/null +++ b/document/i18n/zh-CN/code.json @@ -0,0 +1,521 @@ +{ + "homepage.title": { + "message": "Astron SkillHub" + }, + "homepage.description": { + "message": "面向企业治理与私有化部署的开源 Agent 技能注册中心，覆盖发布、发现与团队协作。" + }, + "homepage.hero.badge": { + "message": "可私有化部署的 Agent 技能注册中心" + }, + "homepage.hero.title": { + "message": "以可治理的方式交付可复用 AI 技能。" + }, + "homepage.hero.tagline": { + "message": "Astron SkillHub 为团队提供专业的内部技能注册中心，用于发布、发现、版本管理和运营可复用的 Agent 技能包。" + }, + "homepage.hero.cta.primary": { + "message": "立即部署" + }, + "homepage.hero.cta.secondary": { + "message": "了解架构" + }, + "homepage.hero.proof.versioning": { + "message": "语义化版本" + }, + "homepage.hero.proof.namespace": { + "message": "命名空间治理" + }, + "homepage.hero.proof.scanner": { + "message": "安全扫描" + }, + "homepage.hero.proof.cli": { + "message": "CLI 兼容" + }, + "homepage.hero.membership": { + "message": "AAIF 准会员" + }, + "homepage.hero.membership.ariaLabel": { + "message": "Agentic AI Foundation 官网（在新标签页中打开）" + }, + "homepage.hero.membership.logoAlt": { + "message": "Agentic AI Foundation（AAIF）" + }, + "homepage.hero.stat.one": { + "message": "统一承载团队协作、治理与运行文档" + }, + "homepage.hero.stat.three": { + "message": "三大核心流程：发布、发现、审核" + }, + "homepage.hero.stat.alwaysOn": { + "message": "支持全天候内部技能运营" + }, + "homepage.why.title": { + "message": "为什么团队选择 SkillHub" + }, + "homepage.why.publishing.eyebrow": { + "message": "发布" + }, + "homepage.why.publishing.title": { + "message": "有序、可追溯的版本化交付" + }, + "homepage.why.publishing.description": { + "message": "语义化版本、渠道标签和不可变包历史，让平台团队与日常贡献者都能稳定、可预期地发布技能。" + }, + "homepage.why.publishing.tag1": { + "message": "语义化版本" + }, + "homepage.why.publishing.tag2": { + "message": "beta / stable / latest 标签" + }, + "homepage.why.publishing.tag3": { + "message": "便于下载与回滚" + }, + "homepage.why.discovery.eyebrow": { + "message": "发现" + }, + "homepage.why.discovery.title": { + "message": "遵循权限边界的搜索" + }, + "homepage.why.discovery.description": { + "message": "全文搜索与结构化筛选帮助用户快速找到合适的技能，同时遵守命名空间可见性和治理边界。" + }, + "homepage.why.collaboration.eyebrow": { + "message": "协作" + }, + "homepage.why.collaboration.title": { + "message": "为真实团队设计的命名空间" + }, + "homepage.why.collaboration.description": { + "message": "按负责人、领域或部门组织技能，并通过所有者、管理员和成员角色匹配企业协作流程。" + }, + "homepage.why.governance.eyebrow": { + "message": "治理" + }, + "homepage.why.governance.title": { + "message": "可靠地审核、审计与晋级" + }, + "homepage.why.governance.description": { + "message": "晋级审核、审计日志和可选安全扫描，帮助技能从局部创新走向组织级受控复用。" + }, + "homepage.mature.title": { + "message": "面向成熟交付体系" + }, + "homepage.mature.card1.title": { + "message": "更克制的界面，更清晰的产品体验" + }, + "homepage.mature.card1.body": { + "message": "官网文档采用更清晰的字体、更紧凑的间距和更明确的视觉层级，让品牌表达专业而克制。" + }, + "homepage.mature.card2.title": { + "message": "以现代设计系统思维构建" + }, + "homepage.mature.card2.body": { + "message": "新版布局借鉴现代组件系统和实用优先设计令牌的规范，同时保留 Docusaurus 文档体验。" + }, + "homepage.mature.card3.title": { + "message": "默认国际化，中文随时切换" + }, + "homepage.mature.card3.body": { + "message": "英文作为默认语言服务更广泛的用户，中文内容可通过内置语言切换器一键访问。" + }, + "homepage.coverage.title": { + "message": "当前能力覆盖" + }, + "homepage.coverage.tag1": { + "message": "私有化部署" + }, + "homepage.coverage.tag2": { + "message": "版本控制" + }, + "homepage.coverage.tag3": { + "message": "全文搜索" + }, + "homepage.coverage.tag4": { + "message": "命名空间" + }, + "homepage.coverage.tag5": { + "message": "审核流程" + }, + "homepage.coverage.tag6": { + "message": "语义化版本" + }, + "homepage.coverage.tag7": { + "message": "RBAC 权限" + }, + "homepage.coverage.tag8": { + "message": "审计日志" + }, + "homepage.coverage.tag9": { + "message": "安全扫描" + }, + "homepage.coverage.tag10": { + "message": "CLI 兼容" + }, + "homepage.quickstart.title": { + "message": "快速开始" + }, + "homepage.quickstart.adminLabel": { + "message": "默认管理员" + }, + "homepage.quickstart.uiLabel": { + "message": "本地 Web 界面" + }, + "homepage.quickstart.apiLabel": { + "message": "注册中心 API" + }, + "homepage.next.title": { + "message": "下一步" + }, + "homepage.next.link1": { + "message": "快速开始" + }, + "homepage.next.desc1": { + "message": "使用一条命令部署 SkillHub" + }, + "homepage.next.link2": { + "message": "产品概览" + }, + "homepage.next.desc2": { + "message": "了解平台定位与能力边界" + }, + "homepage.next.link3": { + "message": "发布流程" + }, + "homepage.next.desc3": { + "message": "发布你的第一个技能包" + }, + "homepage.next.link4": { + "message": "单机部署" + }, + "homepage.next.desc4": { + "message": "运行可用于生产的完整服务栈" + }, + "theme.ErrorPageContent.title": { + "message": "页面已崩溃。", + "description": "The title of the fallback page when the page crashed" + }, + "theme.BackToTopButton.buttonAriaLabel": { + "message": "回到顶部", + "description": "The ARIA label for the back to top button" + }, + "theme.blog.archive.title": { + "message": "历史博文", + "description": "The page & hero title of the blog archive page" + }, + "theme.blog.archive.description": { + "message": "历史博文", + "description": "The page & hero description of the blog archive page" + }, + "theme.blog.paginator.navAriaLabel": { + "message": "博文列表分页导航", + "description": "The ARIA label for the blog pagination" + }, + "theme.blog.paginator.newerEntries": { + "message": "较新的博文", + "description": "The label used to navigate to the newer blog posts page (previous page)" + }, + "theme.blog.paginator.olderEntries": { + "message": "较旧的博文", + "description": "The label used to navigate to the older blog posts page (next page)" + }, + "theme.blog.post.paginator.navAriaLabel": { + "message": "博文分页导航", + "description": "The ARIA label for the blog posts pagination" + }, + "theme.blog.post.paginator.newerPost": { + "message": "较新一篇", + "description": "The blog post button label to navigate to the newer/previous post" + }, + "theme.blog.post.paginator.olderPost": { + "message": "较旧一篇", + "description": "The blog post button label to navigate to the older/next post" + }, + "theme.tags.tagsPageLink": { + "message": "查看所有标签", + "description": "The label of the link targeting the tag list page" + }, + "theme.colorToggle.ariaLabel.mode.system": { + "message": "system mode", + "description": "The name for the system color mode" + }, + "theme.colorToggle.ariaLabel.mode.light": { + "message": "浅色模式", + "description": "The name for the light color mode" + }, + "theme.colorToggle.ariaLabel.mode.dark": { + "message": "暗黑模式", + "description": "The name for the dark color mode" + }, + "theme.colorToggle.ariaLabel": { + "message": "切换浅色/暗黑模式（当前为{mode}）", + "description": "The ARIA label for the color mode toggle" + }, + "theme.docs.breadcrumbs.navAriaLabel": { + "message": "页面路径", + "description": "The ARIA label for the breadcrumbs" + }, + "theme.docs.paginator.navAriaLabel": { + "message": "文件选项卡", + "description": "The ARIA label for the docs pagination" + }, + "theme.docs.paginator.previous": { + "message": "上一页", + "description": "The label used to navigate to the previous doc" + }, + "theme.docs.paginator.next": { + "message": "下一页", + "description": "The label used to navigate to the next doc" + }, + "theme.docs.tagDocListPageTitle.nDocsTagged": { + "message": "{count} 篇文档带有标签", + "description": "Pluralized label for \"{count} docs tagged\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.tagDocListPageTitle": { + "message": "{nDocsTagged}「{tagName}」", + "description": "The title of the page for a docs tag" + }, + "theme.docs.versionBadge.label": { + "message": "版本：{versionLabel}" + }, + "theme.docs.versions.unreleasedVersionLabel": { + "message": "此为 {siteTitle} {versionLabel} 版尚未发行的文档。", + "description": "The label used to tell the user that he's browsing an unreleased doc version" + }, + "theme.docs.versions.unmaintainedVersionLabel": { + "message": "此为 {siteTitle} {versionLabel} 版的文档，现已不再积极维护。", + "description": "The label used to tell the user that he's browsing an unmaintained doc version" + }, + "theme.docs.versions.latestVersionSuggestionLabel": { + "message": "最新的文档请参阅 {latestVersionLink} ({versionLabel})。", + "description": "The label used to tell the user to check the latest version" + }, + "theme.docs.versions.latestVersionLinkLabel": { + "message": "最新版本", + "description": "The label used for the latest version suggestion link label" + }, + "theme.common.editThisPage": { + "message": "编辑此页", + "description": "The link label to edit the current page" + }, + "theme.common.headingLinkTitle": { + "message": "{heading}的直接链接", + "description": "Title for link to heading" + }, + "theme.lastUpdated.atDate": { + "message": "于 {date} ", + "description": "The words used to describe on which date a page has been last updated" + }, + "theme.lastUpdated.byUser": { + "message": "由 {user} ", + "description": "The words used to describe by who the page has been last updated" + }, + "theme.lastUpdated.lastUpdatedAtBy": { + "message": "最后{byUser}{atDate}更新", + "description": "The sentence used to display when a page has been last updated, and by who" + }, + "theme.NotFound.title": { + "message": "找不到页面", + "description": "The title of the 404 page" + }, + "theme.navbar.mobileVersionsDropdown.label": { + "message": "选择版本", + "description": "The label for the navbar versions dropdown on mobile view" + }, + "theme.tags.tagsListLabel": { + "message": "标签：", + "description": "The label alongside a tag list" + }, + "theme.AnnouncementBar.closeButtonAriaLabel": { + "message": "关闭", + "description": "The ARIA label for close button of announcement bar" + }, + "theme.admonition.caution": { + "message": "警告", + "description": "The default label used for the Caution admonition (:::caution)" + }, + "theme.admonition.danger": { + "message": "危险", + "description": "The default label used for the Danger admonition (:::danger)" + }, + "theme.admonition.info": { + "message": "信息", + "description": "The default label used for the Info admonition (:::info)" + }, + "theme.admonition.note": { + "message": "备注", + "description": "The default label used for the Note admonition (:::note)" + }, + "theme.admonition.tip": { + "message": "提示", + "description": "The default label used for the Tip admonition (:::tip)" + }, + "theme.admonition.warning": { + "message": "注意", + "description": "The default label used for the Warning admonition (:::warning)" + }, + "theme.blog.sidebar.navAriaLabel": { + "message": "最近博文导航", + "description": "The ARIA label for recent posts in the blog sidebar" + }, + "theme.DocSidebarItem.expandCategoryAriaLabel": { + "message": "展开侧边栏分类 '{label}'", + "description": "The ARIA label to expand the sidebar category" + }, + "theme.DocSidebarItem.collapseCategoryAriaLabel": { + "message": "折叠侧边栏分类 '{label}'", + "description": "The ARIA label to collapse the sidebar category" + }, + "theme.IconExternalLink.ariaLabel": { + "message": "(opens in new tab)", + "description": "The ARIA label for the external link icon" + }, + "theme.NotFound.p1": { + "message": "我们找不到您要找的页面。", + "description": "The first paragraph of the 404 page" + }, + "theme.NotFound.p2": { + "message": "请联系原始链接来源网站的所有者，并告知他们链接已损坏。", + "description": "The 2nd paragraph of the 404 page" + }, + "theme.NavBar.navAriaLabel": { + "message": "主导航", + "description": "The ARIA label for the main navigation" + }, + "theme.TOCCollapsible.toggleButtonLabel": { + "message": "本页总览", + "description": "The label used by the button on the collapsible TOC component" + }, + "theme.navbar.mobileLanguageDropdown.label": { + "message": "选择语言", + "description": "The label for the mobile language switcher dropdown" + }, + "theme.blog.post.readMore": { + "message": "阅读更多", + "description": "The label used in blog post item excerpts to link to full blog posts" + }, + "theme.blog.post.readMoreLabel": { + "message": "阅读 {title} 的全文", + "description": "The ARIA label for the link to full blog posts from excerpts" + }, + "theme.blog.post.readingTime.plurals": { + "message": "阅读需 {readingTime} 分钟", + "description": "Pluralized label for \"{readingTime} min read\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.CodeBlock.copy": { + "message": "复制", + "description": "The copy button label on code blocks" + }, + "theme.CodeBlock.copied": { + "message": "复制成功", + "description": "The copied button label on code blocks" + }, + "theme.CodeBlock.copyButtonAriaLabel": { + "message": "复制代码到剪贴板", + "description": "The ARIA label for copy code blocks button" + }, + "theme.CodeBlock.wordWrapToggle": { + "message": "切换自动换行", + "description": "The title attribute for toggle word wrapping button of code block lines" + }, + "theme.docs.breadcrumbs.home": { + "message": "主页面", + "description": "The ARIA label for the home page in the breadcrumbs" + }, + "theme.docs.sidebar.collapseButtonTitle": { + "message": "收起侧边栏", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.collapseButtonAriaLabel": { + "message": "收起侧边栏", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.navAriaLabel": { + "message": "文档侧边栏", + "description": "The ARIA label for the sidebar navigation" + }, + "theme.docs.sidebar.closeSidebarButtonAriaLabel": { + "message": "关闭导航栏", + "description": "The ARIA label for close button of mobile sidebar" + }, + "theme.navbar.mobileDropdown.collapseButton.expandAriaLabel": { + "message": "Expand the dropdown", + "description": "The ARIA label of the button to expand the mobile dropdown navbar item" + }, + "theme.navbar.mobileDropdown.collapseButton.collapseAriaLabel": { + "message": "Collapse the dropdown", + "description": "The ARIA label of the button to collapse the mobile dropdown navbar item" + }, + "theme.docs.sidebar.toggleSidebarButtonAriaLabel": { + "message": "切换导航栏", + "description": "The ARIA label for hamburger menu button of mobile navigation" + }, + "theme.navbar.mobileSidebarSecondaryMenu.backButtonLabel": { + "message": "← 回到主菜单", + "description": "The label of the back button to return to main menu, inside the mobile navbar sidebar secondary menu (notably used to display the docs sidebar)" + }, + "theme.docs.sidebar.expandButtonTitle": { + "message": "展开侧边栏", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.docs.sidebar.expandButtonAriaLabel": { + "message": "展开侧边栏", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.blog.post.plurals": { + "message": "{count} 篇博文", + "description": "Pluralized label for \"{count} posts\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.blog.tagTitle": { + "message": "{nPosts} 含有标签「{tagName}」", + "description": "The title of the page for a blog tag" + }, + "theme.blog.author.pageTitle": { + "message": "{authorName} - {nPosts}", + "description": "The title of the page for a blog author" + }, + "theme.blog.authorsList.pageTitle": { + "message": "作者", + "description": "The title of the authors page" + }, + "theme.blog.authorsList.viewAll": { + "message": "查看所有作者", + "description": "The label of the link targeting the blog authors page" + }, + "theme.blog.author.noPosts": { + "message": "该作者尚未撰写任何文章。", + "description": "The text for authors with 0 blog post" + }, + "theme.contentVisibility.unlistedBanner.title": { + "message": "未列出页", + "description": "The unlisted content banner title" + }, + "theme.contentVisibility.unlistedBanner.message": { + "message": "此页面未列出。搜索引擎不会对其索引，只有拥有直接链接的用户才能访问。", + "description": "The unlisted content banner message" + }, + "theme.contentVisibility.draftBanner.title": { + "message": "草稿页", + "description": "The draft content banner title" + }, + "theme.contentVisibility.draftBanner.message": { + "message": "此页面是草稿，仅在开发环境中可见，不会包含在正式版本中。", + "description": "The draft content banner message" + }, + "theme.docs.DocCard.categoryDescription.plurals": { + "message": "{count} 个项目", + "description": "The default description for a category card in the generated index about how many items this category includes" + }, + "theme.ErrorPageContent.tryAgain": { + "message": "重试", + "description": "The label of the button to try again rendering when the React error boundary captures an error" + }, + "theme.common.skipToMainContent": { + "message": "跳到主要内容", + "description": "The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation" + }, + "theme.tags.tagsPageTitle": { + "message": "标签", + "description": "The title of the tag list page" + } +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-blog/options.json b/document/i18n/zh-CN/docusaurus-plugin-content-blog/options.json new file mode 100644 index 00000000..9239ff70 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-blog/options.json @@ -0,0 +1,14 @@ +{ + "title": { + "message": "Blog", + "description": "The title for the blog used in SEO" + }, + "description": { + "message": "Blog", + "description": "The description for the blog used in SEO" + }, + "sidebar.title": { + "message": "Recent posts", + "description": "The label for the left sidebar" + } +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current.json b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current.json new file mode 100644 index 00000000..c7949952 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current.json @@ -0,0 +1,62 @@ +{ + "version.label": { + "message": "Next", + "description": "The label for version current" + }, + "sidebar.docsSidebar.category.Getting Started": { + "message": "快速入门", + "description": "The label for category 'Getting Started' in sidebar 'docsSidebar'" + }, + "sidebar.docsSidebar.category.Administration Guide": { + "message": "管理员指南", + "description": "The label for category 'Administration Guide' in sidebar 'docsSidebar'" + }, + "sidebar.docsSidebar.category.Deployment Guide": { + "message": "部署指南", + "description": "The label for category 'Deployment Guide' in sidebar 'docsSidebar'" + }, + "sidebar.docsSidebar.category.Security & Compliance": { + "message": "安全与合规", + "description": "The label for category 'Security & Compliance' in sidebar 'docsSidebar'" + }, + "sidebar.docsSidebar.category.Governance & Operations": { + "message": "治理与运营", + "description": "The label for category 'Governance & Operations' in sidebar 'docsSidebar'" + }, + "sidebar.docsSidebar.category.User Guide": { + "message": "用户指南", + "description": "The label for category 'User Guide' in sidebar 'docsSidebar'" + }, + "sidebar.docsSidebar.category.Publishing Skills": { + "message": "发布技能", + "description": "The label for category 'Publishing Skills' in sidebar 'docsSidebar'" + }, + "sidebar.docsSidebar.category.Discovery & Usage": { + "message": "发现与使用", + "description": "The label for category 'Discovery & Usage' in sidebar 'docsSidebar'" + }, + "sidebar.docsSidebar.category.Collaboration": { + "message": "协作", + "description": "The label for category 'Collaboration' in sidebar 'docsSidebar'" + }, + "sidebar.docsSidebar.category.Developer Reference": { + "message": "开发者参考", + "description": "The label for category 'Developer Reference' in sidebar 'docsSidebar'" + }, + "sidebar.docsSidebar.category.API Reference": { + "message": "API 参考", + "description": "The label for category 'API Reference' in sidebar 'docsSidebar'" + }, + "sidebar.docsSidebar.category.Architecture": { + "message": "架构设计", + "description": "The label for category 'Architecture' in sidebar 'docsSidebar'" + }, + "sidebar.docsSidebar.category.Extensions & Integrations": { + "message": "扩展与集成", + "description": "The label for category 'Extensions & Integrations' in sidebar 'docsSidebar'" + }, + "sidebar.docsSidebar.category.Reference": { + "message": "参考资料", + "description": "The label for category 'Reference' in sidebar 'docsSidebar'" + } +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/_category_.json b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/_category_.json new file mode 100644 index 00000000..42cea88c --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "快速入门", + "position": 1, + "link": { + "type": "generated-index", + "description": "快速了解并开始使用 SkillHub" + } +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/overview.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/overview.md new file mode 100644 index 00000000..19df6539 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/overview.md @@ -0,0 +1,70 @@ +--- +title: 产品概述 +sidebar_position: 1 +description: SkillHub 产品概述和核心特性介绍 +--- + +# 产品概述 + +SkillHub 是企业级 AI 技能注册平台，支持技能发布、发现与管理，采用自托管架构保障数据安全。 + +## 核心特性 + +### 发布管理 +- 版本控制与语义化版本（Semantic Versioning） +- 自定义标签（如 `beta`/`stable`） +- `latest` 标签自动跟随最新发布版本 + +### 发现机制 +- 全文搜索 +- 多维度筛选（命名空间、下载量、评分） +- 可见性控制（公开/命名空间内/私有） + +### 组织架构 +- 命名空间隔离 +- 基于角色的访问控制（RBAC） +- 团队与全局双层空间 + +### 治理体系 +- 双层审核流程 +- 审计日志 +- 权限分离 + +### 存储与部署 +- 支持 S3/MinIO/本地存储 +- Docker/Kubernetes 部署 +- 企业级可观测性 + +## 技术栈 + +### 后端 +- **Java 21** - 运行时 +- **Spring Boot 3.2.3** - 应用框架 +- **PostgreSQL 16.x** - 主数据库 + 全文搜索 +- **Redis 7.x** - 缓存与会话存储 + +### 前端 +- **React 19** - UI 框架 +- **TypeScript** - 类型安全 +- **Vite** - 构建工具 +- **Tailwind CSS** - 样式框架 + +### 部署 +- **Docker Compose** - 单机部署 +- **Kubernetes** - 生产环境编排 + +## 核心概念 + +### 命名空间 +技能隔离边界，支持 `@global`（全局）和 `@team-*`（团队）前缀。 + +### 坐标系统 +技能标识格式为 `@{namespace_slug}/{skill_slug}`，支持语义化版本。 + +### 兼容性 +提供 REST API 和 ClawHub 兼容层，支持现有工具集成。 + +## 下一步 + +- [快速开始](./quick-start) - 一键启动体验 +- [典型应用场景](./use-cases) - 了解如何在企业中应用 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/quick-start.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/quick-start.md new file mode 100644 index 00000000..37e100b0 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/quick-start.md @@ -0,0 +1,85 @@ +--- +title: 快速开始 +sidebar_position: 2 +description: 一键启动 SkillHub 开发环境 +--- + +# 快速开始 + +## 一键启动 + +使用以下命令一键启动完整的 SkillHub 环境： + +```bash +curl -fsSL https://raw.githubusercontent.com/iflytek/skillhub/main/scripts/runtime.sh | sh -s -- up +``` + +或者克隆仓库后手动启动： + +```bash +git clone https://github.com/iflytek/skillhub.git +cd skillhub +make dev-all +``` + +## 默认账号 + +两种启动方式都会默认创建一个 bootstrap 管理员账号： + +- 用户名：`admin` +- 密码：`ChangeMe!2026` + +### `curl` 一键部署 + +| 服务 | 地址 | +|------|------| +| Web UI | http://localhost | +| Backend API | http://localhost:8080 | + +使用上述默认账号密码登录即可。**生产环境请务必修改密码。** + +### `make dev-all` 本地开发 + +| 服务 | 地址 | +|------|------| +| Web UI | http://localhost:3000 | +| Backend API | http://localhost:8080 | +| MinIO Console | http://localhost:9001 | + +除了上述 bootstrap 管理员，本地开发还预置两个模拟用户（无需密码）： + +| 用户 | 角色 | 说明 | +|------|------|------| +| `local-user` | 普通用户 | 可发布技能、管理命名空间 | +| `local-admin` | 超级管理员 | 拥有所有权限，包括审核和用户管理 | + +使用 `X-Mock-User-Id` 请求头切换模拟用户。 +如需关闭 bootstrap 管理员，启动前设置 `BOOTSTRAP_ADMIN_ENABLED=false`。 + +## 常用命令 + +```bash +# 启动完整开发环境 +make dev-all + +# 停止所有服务 +make dev-all-down + +# 重置并重新启动 +make dev-all-reset + +# 仅启动后端 +make dev + +# 仅启动前端 +make dev-web + +# 查看所有可用命令 +make help +``` + +## 下一步 + +- [产品概述](./overview) - 深入了解产品特性 +- [典型应用场景](./use-cases) - 探索企业应用场景 +- [单机部署](../administration/deployment/single-machine) - 生产环境部署指南 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/use-cases.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/use-cases.md new file mode 100644 index 00000000..aab236c6 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/01-getting-started/use-cases.md @@ -0,0 +1,72 @@ +--- +title: 典型应用场景 +sidebar_position: 3 +description: SkillHub 在企业中的典型应用场景 +--- + +# 典型应用场景 + +## 企业内部技能共享 + +**场景描述**：企业内部多个团队开发 AI 技能，需要一个集中的平台进行共享和复用。 + +**解决方案**： +- 各团队创建自己的命名空间 +- 技能在团队内先审核发布 +- 优秀技能可申请提升到全局空间 +- 所有操作有完整审计记录 + +**价值**： +- 避免重复开发 +- 促进最佳实践传播 +- 保障质量可控 + +## AI 技能治理与合规 + +**场景描述**：金融、政务等行业对 AI 应用有严格的合规要求，需要完整的审核和审计机制。 + +**解决方案**： +- 双层审核流程（团队审核 + 平台审核） +- 细粒度 RBAC 权限控制 +- 完整的操作审计日志 +- 技能版本可追溯、可撤回 + +**价值**： +- 满足合规要求 +- 风险可控 +- 责任可追溯 + +## 多团队协作开发 + +**场景描述**：大型组织中多个团队协作开发，需要清晰的权限边界和协作机制。 + +**解决方案**： +- 命名空间隔离，团队自治 +- 命名空间成员角色管理 +- 技能可见性控制（公开/命名空间内/私有） +- 团队技能可申请提升到全局 + +**价值**： +- 权责清晰 +- 协作高效 +- 安全可控 + +## CLI 工具集成 + +**场景描述**：已有使用 ClawHub CLI 的工作流，希望无缝迁移到 SkillHub。 + +**解决方案**： +- 提供 ClawHub CLI 协议兼容层 +- 通过 `/.well-known/clawhub.json` 自动发现 +- 现有 CLI 工具无需修改即可使用 +- 同时提供 SkillHub 自有 CLI 增强功能 + +**价值**： +- 保护现有投资 +- 迁移成本低 +- 渐进式升级 + +## 下一步 + +- [单机部署](../administration/deployment/single-machine) - 开始部署 +- [命名空间管理](../administration/governance/namespaces) - 了解组织治理 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/_category_.json b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/_category_.json new file mode 100644 index 00000000..9e9be7e5 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "管理员指南", + "position": 2, + "link": { + "type": "generated-index", + "description": "部署、配置和管理 SkillHub" + } +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/_category_.json b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/_category_.json new file mode 100644 index 00000000..1b21d412 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "部署指南", + "position": 1 +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/configuration.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/configuration.md new file mode 100644 index 00000000..f04387bb --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/configuration.md @@ -0,0 +1,69 @@ +--- +title: 配置说明 +sidebar_position: 3 +description: SkillHub 配置项详细说明 +--- + +# 配置说明 + +## 环境变量 + +SkillHub 通过环境变量进行配置，主要配置项如下： + +### 基础配置 + +| 环境变量 | 说明 | 默认值 | +|---------|------|--------| +| `SKILLHUB_PUBLIC_BASE_URL` | 公网访问地址 | - | +| `SKILLHUB_VERSION` | 镜像版本 | `edge` | + +### 数据库配置 + +| 环境变量 | 说明 | 默认值 | +|---------|------|--------| +| `POSTGRES_HOST` | PostgreSQL 主机 | `postgres` | +| `POSTGRES_PORT` | PostgreSQL 端口 | `5432` | +| `POSTGRES_DB` | 数据库名 | `skillhub` | +| `POSTGRES_USER` | 数据库用户 | `skillhub` | +| `POSTGRES_PASSWORD` | 数据库密码 | - | + +### Redis 配置 + +| 环境变量 | 说明 | 默认值 | +|---------|------|--------| +| `REDIS_HOST` | Redis 主机 | `redis` | +| `REDIS_PORT` | Redis 端口 | `6379` | +| `REDIS_PASSWORD` | Redis 密码 | - | + +### 存储配置 + +| 环境变量 | 说明 | 默认值 | +|---------|------|--------| +| `SKILLHUB_STORAGE_PROVIDER` | 存储提供方 | `local` | +| `SKILLHUB_STORAGE_S3_ENDPOINT` | S3 端点 | - | +| `SKILLHUB_STORAGE_S3_BUCKET` | S3 桶名 | - | +| `SKILLHUB_STORAGE_S3_ACCESS_KEY` | S3 Access Key | - | +| `SKILLHUB_STORAGE_S3_SECRET_KEY` | S3 Secret Key | - | + +### OAuth 配置 + +| 环境变量 | 说明 | 默认值 | +|---------|------|--------| +| `OAUTH2_GITHUB_CLIENT_ID` | GitHub OAuth Client ID | - | +| `OAUTH2_GITHUB_CLIENT_SECRET` | GitHub OAuth Client Secret | - | + +### 首登管理员配置 + +| 环境变量 | 说明 | 默认值 | +|---------|------|--------| +| `BOOTSTRAP_ADMIN_ENABLED` | 是否启用首登管理员 | `true` | +| `BOOTSTRAP_ADMIN_USERNAME` | 首登管理员用户名 | `admin` | +| `BOOTSTRAP_ADMIN_PASSWORD` | 首登管理员密码 | `ChangeMe!2026` | + +## 配置文件 + +Spring Boot 配置文件位于 `server/skillhub-app/src/main/resources/`。 + +## 下一步 + +- [认证配置](../security/authentication) - 配置身份认证 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/kubernetes.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/kubernetes.md new file mode 100644 index 00000000..a231a428 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/kubernetes.md @@ -0,0 +1,54 @@ +--- +title: Kubernetes 部署 +sidebar_position: 2 +description: 在 Kubernetes 集群中部署 SkillHub +--- + +# Kubernetes 部署 + +本文介绍如何在 Kubernetes 集群中部署 SkillHub。 + +## 前置要求 + +- Kubernetes 1.24+ +- kubectl 配置完成 +- Helm 3.0+（可选） +- 可用的持久化存储类 + +## 部署清单 + +项目提供了 Kubernetes 部署清单： + +```bash +cd deploy/k8s + +# 1. 创建命名空间 +kubectl create namespace skillhub + +# 2. 配置 Secret +cp secret.yaml.example secret.yaml +# 编辑 secret.yaml 填入真实凭证 + +# 3. 应用配置 +kubectl apply -f configmap.yaml +kubectl apply -f secret.yaml + +# 4. 部署服务 +kubectl apply -f backend-deployment.yaml +kubectl apply -f frontend-deployment.yaml +kubectl apply -f services.yaml + +# 5. 配置 Ingress +kubectl apply -f ingress.yaml +``` + +## 高可用配置 + +- 后端和前端建议至少部署 2 个副本 +- PostgreSQL 使用主从复制 +- Redis 使用 Sentinel 或 Cluster 模式 +- 存储使用高可用对象存储（如 MinIO 集群或云厂商 OSS） + +## 下一步 + +- [配置说明](./configuration) - 详细配置项说明 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/single-machine.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/single-machine.md new file mode 100644 index 00000000..8673a8fd --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/deployment/single-machine.md @@ -0,0 +1,65 @@ +--- +title: 单机部署 +sidebar_position: 1 +description: 使用 Docker Compose 单机部署 SkillHub +--- + +# 单机部署 + +本文介绍如何使用 Docker Compose 在单台服务器上部署 SkillHub。 + +## 前置要求 + +- Docker Engine 20.10+ +- Docker Compose Plugin 2.0+ +- 至少 4GB 可用内存 +- 至少 20GB 可用磁盘空间 + +## 快速部署 + +```bash +# 1. 克隆仓库 +git clone https://github.com/iflytek/skillhub.git +cd skillhub + +# 2. 复制环境变量模板 +cp .env.release.example .env.release + +# 3. 编辑配置 +# 修改 .env.release 中的配置项，特别是密码和公网地址 + +# 4. 验证配置 +make validate-release-config + +# 5. 启动服务 +docker compose --env-file .env.release -f compose.release.yml up -d +``` + +## 配置说明 + +详见 [配置说明](./configuration) 文档。 + +## 验证部署 + +```bash +# 检查容器状态 +docker compose --env-file .env.release -f compose.release.yml ps + +# 检查后端健康状态 +curl -i http://127.0.0.1:8080/actuator/health + +# 访问 Web UI +# 浏览器打开 http://localhost（或配置的公网地址） +``` + +## 首登配置 + +1. 使用 `BOOTSTRAP_ADMIN_USERNAME` 和 `BOOTSTRAP_ADMIN_PASSWORD` 登录（默认 `admin` / `ChangeMe!2026`） +2. 立即修改管理员密码 +3. 配置企业 SSO（可选） +4. 创建团队命名空间 + +## 下一步 + +- [配置说明](./configuration) - 详细配置项说明 +- [Kubernetes 部署](./kubernetes) - 高可用部署 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/_category_.json b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/_category_.json new file mode 100644 index 00000000..f440e0fc --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "治理与运营", + "position": 3 +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/namespaces.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/namespaces.md new file mode 100644 index 00000000..2d7f92b4 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/namespaces.md @@ -0,0 +1,56 @@ +--- +title: 命名空间管理 +sidebar_position: 1 +description: 命名空间创建与管理 +--- + +# 命名空间管理 + +命名空间是 SkillHub 中技能的隔离边界和协作单元。 + +## 命名空间类型 + +| 类型 | 前缀 | 说明 | +|------|------|------| +| 全局 | `@global` | 平台级公共空间，由平台管理员管理 | +| 团队 | `@team-*` | 团队/部门空间，由团队管理员管理 | + +## 创建命名空间 + +1. 登录后进入"我的命名空间" +2. 点击"创建命名空间" +3. 填写信息： + - 标识（slug）：URL 友好名称 + - 显示名：展示名称 + - 描述：空间用途说明 +4. 提交创建 + +## 命名空间成员管理 + +### 添加成员 + +1. 进入命名空间设置 +2. 进入"成员管理" +3. 输入用户名搜索 +4. 选择角色（OWNER/ADMIN/MEMBER） +5. 确认添加 + +### 角色变更 + +命名空间 OWNER 或 ADMIN 可变更成员角色。 + +### 移除成员 + +命名空间 OWNER 或 ADMIN 可移除成员。 + +## 命名空间状态 + +| 状态 | 说明 | +|------|------| +| `ACTIVE` | 正常使用 | +| `FROZEN` | 冻结，只读不可发布 | +| `ARCHIVED` | 归档，对外不可见 | + +## 下一步 + +- [审核流程](./review-workflow) - 了解技能审核 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/review-workflow.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/review-workflow.md new file mode 100644 index 00000000..660f8eda --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/review-workflow.md @@ -0,0 +1,44 @@ +--- +title: 审核流程 +sidebar_position: 2 +description: 技能发布审核流程配置 +--- + +# 审核流程 + +SkillHub 采用双层审核机制，保障技能质量。 + +## 审核流程 + +### 团队空间技能 + +1. 团队成员提交发布 +2. 创建审核任务（PENDING） +3. 团队 ADMIN 或 OWNER 审核 + - 通过 → 技能发布（PUBLISHED） + - 拒绝 → 返回修改（REJECTED） + +### 全局空间技能 + +1. 提交发布 +2. 平台 SKILL_ADMIN 或 SUPER_ADMIN 审核 +3. 审核通过后发布 + +## 团队技能提升到全局 + +1. 团队技能已发布 +2. 团队 ADMIN 或 OWNER 申请"提升到全局" +3. 平台管理员审核 +4. 审核通过后在全局空间创建新技能 + +## 审核权限 + +| 审核类型 | 所需角色 | +|---------|---------| +| 团队空间技能审核 | 命名空间 ADMIN/OWNER | +| 全局空间技能审核 | SKILL_ADMIN/SUPER_ADMIN | +| 提升申请审核 | SKILL_ADMIN/SUPER_ADMIN | + +## 下一步 + +- [用户管理](./user-management) - 管理平台用户 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/user-management.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/user-management.md new file mode 100644 index 00000000..58d9abdc --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/governance/user-management.md @@ -0,0 +1,61 @@ +--- +title: 用户管理 +sidebar_position: 3 +description: 平台用户管理 +--- + +# 用户管理 + +## 用户状态 + +| 状态 | 实际逻辑 | +|------|----------| +| `ACTIVE` | 可正常登录和使用系统。OAuth 首次自动准入、local 注册成功后都会进入该状态。 | +| `PENDING` | 账号已建但不可登录。OAuth 在“需要审批”策略下会创建 `PENDING` 用户并跳转到待审批页；local 登录遇到该状态会直接拒绝。 | +| `DISABLED` | 不可登录。OAuth 和 local 登录都会拒绝；`/api/v1/auth/me` 发现当前会话对应用户已被禁用时，会直接清掉 session。 | +| `MERGED` | 账号已并入其他账号，不可继续登录；主要由账号合并流程写入，不是普通用户管理流程的目标状态。 | + +## 用户准入 + +可配置新用户是否需要审批： +- 自动准入：新用户登录后自动激活 +- 审批准入：新用户需 USER_ADMIN 审批后激活 + +## 角色分配 + +`USER_ADMIN` 或 `SUPER_ADMIN` 可调用用户管理接口修改平台角色，但当前实现有几个关键点： + +- 接口一次只能设置一个目标平台角色。 +- 设置时会删除该用户已有的显式平台角色，再写入新的那个角色。 +- 如果设置为 `USER`，不会写入 `user_role_binding`，而是依赖运行时默认角色补位。 +- `USER_ADMIN` 不能分配 `SUPER_ADMIN`，只有 `SUPER_ADMIN` 能分配。 + +当前管理接口可设置的目标角色实际上是： + +- `USER` +- `SKILL_ADMIN` +- `USER_ADMIN` +- `AUDITOR` +- `SUPER_ADMIN` + +## 用户封禁/解封 + +`USER_ADMIN` 或 `SUPER_ADMIN` 可封禁/解封用户。 + +当前公开管理接口只支持把状态改成： + +- `ACTIVE` +- `DISABLED` + +其中： + +- “审批通过”本质上也是把用户状态改成 `ACTIVE`。 +- 不能通过该接口直接改成 `PENDING` 或 `MERGED`。 + +## 账号合并 + +支持将多个账号合并为一个，保留操作历史。 + +## 下一步 + +- [创建技能包](../../user-guide/publishing/create-skill) - 开始发布技能 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/_category_.json b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/_category_.json new file mode 100644 index 00000000..7b64d3ab --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "安全与合规", + "position": 2 +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/audit-logs.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/audit-logs.md new file mode 100644 index 00000000..08925fce --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/audit-logs.md @@ -0,0 +1,38 @@ +--- +title: 审计日志 +sidebar_position: 3 +description: 操作审计日志查询与管理 +--- + +# 审计日志 + +SkillHub 记录所有关键操作的审计日志，满足企业合规要求。 + +## 审计范围 + +记录的操作包括： +- 技能发布、下载、删除 +- 审核通过、拒绝 +- 用户登录、登出 +- 权限变更 +- 命名空间管理 +- 配置变更 + +## 审计日志查询 + +通过管理后台审计日志页面或 Admin API 查询。 + +## 日志字段 + +- 操作时间 +- 操作用户 +- 操作类型 +- 目标资源 +- 客户端 IP +- User-Agent +- 请求 ID +- 详细信息 + +## 下一步 + +- [命名空间管理](../governance/namespaces) - 管理组织 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/authentication.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/authentication.md new file mode 100644 index 00000000..923878ee --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/authentication.md @@ -0,0 +1,36 @@ +--- +title: 认证配置 +sidebar_position: 1 +description: 配置用户认证方式 +--- + +# 认证配置 + +SkillHub 支持多种认证方式，满足不同企业的安全需求。 + +## OAuth2 登录 + +### GitHub OAuth + +1. 在 GitHub 创建 OAuth App +2. 配置环境变量： + ```bash + OAUTH2_GITHUB_CLIENT_ID=your-client-id + OAUTH2_GITHUB_CLIENT_SECRET=your-client-secret + ``` + +### 扩展 OAuth Provider + +架构支持扩展其他 OAuth Provider，如 GitLab、Gitee 等。 + +## 本地账号登录 + +开发环境支持本地账号登录，生产环境默认关闭。 + +## 企业 SSO 集成 + +支持通过扩展点集成企业 SSO（SAML/OIDC）。 + +## 下一步 + +- [权限管理](./authorization) - 配置权限控制 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/authorization.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/authorization.md new file mode 100644 index 00000000..36d7fef3 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/authorization.md @@ -0,0 +1,63 @@ +--- +title: 权限管理 +sidebar_position: 2 +description: RBAC 权限系统配置 +--- + +# 权限管理 + +SkillHub 采用基于角色的访问控制（RBAC）系统。 + +当前代码里实际存在两套并行角色体系： + +- 平台角色：控制后台治理、用户管理、审计等平台级能力。 +- 命名空间角色：控制某个团队空间内的成员、发布、审核、归档等操作。 + +二者会同时参与鉴权，但不是一套角色的上下级映射。 + +## 平台角色 + +### 代码里实际初始化的显式平台角色 + +数据库迁移只初始化了 4 个显式平台角色： + +| 角色 | 代码 | 实际能力 | +|------|------|----------| +| 超级管理员 | `SUPER_ADMIN` | 拥有全部权限；`RbacService#getUserPermissions` 会直接返回全部权限码；可访问所有 `SUPER_ADMIN`/`SKILL_ADMIN`/`USER_ADMIN`/`AUDITOR` 能访问的接口；可分配 `SUPER_ADMIN`；发布技能时可绕过命名空间成员校验并直接自动发布；但仍不能审批自己提交的 promotion，且普通审核单若是自己提交的，也只有 `SUPER_ADMIN` 能特判审批。 | +| 技能管理员 | `SKILL_ADMIN` | 可访问技能治理后台接口；可隐藏/取消隐藏技能、撤回版本（yank）、处理技能举报；可查看和处理全局空间审核、promotion 审核、治理工作台收件箱中的 review/promotion/report；不能分配平台角色、不能看审计日志、不能管理用户。 | +| 用户管理员 | `USER_ADMIN` | 可访问用户管理接口；可列表用户、审批用户、启用/禁用用户、修改平台角色；不能分配 `SUPER_ADMIN`；不能处理技能治理、不能看审计日志。 | +| 审计员 | `AUDITOR` | 只读查看审计日志；可访问 `/api/v1/admin/audit-logs` 和 `/actuator/prometheus`；治理工作台中只能看 activity，不能处理 review/promotion/report，也不能管理用户或技能。 | + +### 运行时默认平台角色 + +| 角色 | 代码 | 实际逻辑 | +|------|------|----------| +| 默认用户 | `USER` | 不是 `role` 表里的显式初始化记录。只要用户没有任何显式平台角色绑定，登录态和 `RbacService#getUserRoleCodes` 都会自动补上 `USER`。它主要表示“普通已登录用户”，没有额外后台治理权限。 | + +### 需要特别注意的实现细节 + +- 当前管理接口的“修改用户角色”是单值覆盖，不是追加：`PUT /api/v1/admin/users/{userId}/role` 先清空该用户现有平台角色，再写入一个目标角色；当目标角色是 `USER` 时，不会写数据库记录，而是依赖运行时默认补位。 +- 代码底层仍然支持“一个用户拥有多个显式平台角色”的读取与鉴权，因为 session、token 和 `RbacService` 都是按角色集合处理；只是当前管理接口不会这样分配。 +- `SUPER_ADMIN` 是唯一一个在权限查询时被视为“拥有全部 permission code”的角色，其它角色依赖 `role_permission` 关联表。 + +## 命名空间角色 + +| 角色 | 实际能力 | +|------|----------| +| `OWNER` | 创建团队空间时自动成为 `OWNER`。可更新命名空间信息、管理成员、冻结/解冻空间、归档/恢复空间、转移所有权；可提交 review；可审核团队空间 review；可访问私有技能；可管理受限技能生命周期（归档、反归档、删除草稿/驳回版本等）。 | +| `ADMIN` | 可更新命名空间信息、管理成员、冻结/解冻空间；不能归档/恢复空间，也不能直接把别人设为 `OWNER`；可提交 review；可审核团队空间 review；可访问私有技能；可管理受限技能生命周期。 | +| `MEMBER` | 默认加入全局空间时获得 `MEMBER`。可在所在命名空间发布技能、提交 review；但不能审核 review、不能管理成员、不能冻结/归档空间；私有技能也不能仅因 `MEMBER` 身份访问，私有技能要求 owner 或 `ADMIN/OWNER`。 | + +### 命名空间角色的边界 + +- `GLOBAL` 空间是只读系统空间，不能通过命名空间治理接口修改；全局空间 review/promotion/report 处理依赖平台角色 `SKILL_ADMIN`/`SUPER_ADMIN`，不是依赖全局空间成员身份。 +- `NAMESPACE_ONLY` 可见性的技能，任何该命名空间成员都能访问。 +- `PRIVATE` 可见性的技能，只有技能 owner 或命名空间 `ADMIN/OWNER` 能访问，`MEMBER` 不行。 + +## 权限配置 + +通过后台分配平台角色，通过命名空间成员关系分配命名空间角色。 + +## 下一步 + +- [审计日志](./audit-logs) - 查看操作审计 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/scanner.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/scanner.md new file mode 100644 index 00000000..d0a59721 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/02-administration/security/scanner.md @@ -0,0 +1,104 @@ +--- +title: 安全扫描 +sidebar_position: 4 +description: 使用 Skill Scanner 为技能发布链路提供自动安全检查 +--- + +# 安全扫描 + +SkillHub 支持在技能发布链路中接入 `skill-scanner`，对上传的技能包执行自动安全检查，并把结果沉淀到安全审计记录中。 + +## 扫描链路 + +启用扫描后，发布流程会变成： + +1. 用户发起技能发布 +2. 后端创建版本记录并进入 `SCANNING` +3. 后端写入扫描任务 +4. `skill-scanner` 拉取任务并执行分析 +5. 扫描结果写入 `security_audit` +6. 版本进入 `PENDING_REVIEW`，如多次重试后仍失败则进入 `SCAN_FAILED` +7. 后续仍然沿用已有的审核工作流 + +## 适用场景 + +- 企业希望在人工审核前增加一层自动风险筛查 +- 平台需要保留技能包扫描结果和审计证据 +- 部署环境要求对恶意代码、敏感信息或高风险行为做基础检测 + +## 运行模式 + +支持两种模式： + +- `local`：后端把文件路径传给扫描服务，适合同机或共享文件系统场景 +- `upload`：后端直接上传技能包到扫描服务，适合 Docker / Kubernetes 等分离部署场景 + +推荐做法： + +- 本地开发：优先使用 `local` +- 生产环境、Kubernetes、多服务部署：优先使用 `upload` + +## 关键配置 + +后端核心配置项： + +```yaml +skillhub: + security: + scanner: + enabled: false + base-url: http://localhost:8000 + health-path: /health + scan-path: /scan-upload + mode: upload + connect-timeout-ms: 5000 + read-timeout-ms: 300000 + retry-max-attempts: 3 +``` + +常用环境变量： + +- `SKILLHUB_SECURITY_SCANNER_ENABLED` +- `SKILLHUB_SECURITY_SCANNER_URL` +- `SKILLHUB_SECURITY_SCANNER_MODE` +- `SKILLHUB_SCAN_STREAM_KEY` +- `SKILLHUB_SCAN_STREAM_GROUP` + +## 验证方式 + +启用后建议按下面步骤验证： + +1. 发布一个测试技能包 +2. 确认版本状态先进入 `SCANNING` +3. 确认生成了 `security_audit` 记录 +4. 确认版本最终进入 `PENDING_REVIEW` 或 `SCAN_FAILED` +5. 调用安全审计接口查看扫描结果 + +```text +GET /api/v1/skills/{skillId}/versions/{versionId}/security-audit +``` + +## 结果说明 + +安全审计结果通常包含： + +- `scanId` +- `scannerType` +- `verdict` +- `isSafe` +- `maxSeverity` +- `findingsCount` +- `findings` +- `scanDurationSeconds` +- `scannedAt` + +## 部署建议 + +- 单机开发环境可先关闭扫描，确认主流程后再开启 +- Kubernetes 中建议使用 `upload` 模式，避免服务间共享文件系统 +- 生产环境建议把扫描结果与人工审核一起作为治理证据保留 + +## 下一步 + +- [审核工作流](../governance/review-workflow) - 了解扫描后的审核链路 +- [部署配置](../deployment/configuration) - 查看部署相关配置 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/_category_.json b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/_category_.json new file mode 100644 index 00000000..e87c7197 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "用户指南", + "position": 3, + "link": { + "type": "generated-index", + "description": "学习如何发布、发现和使用技能" + } +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/collaboration/_category_.json b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/collaboration/_category_.json new file mode 100644 index 00000000..f7661de1 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/collaboration/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "协作", + "position": 3 +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/collaboration/namespaces.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/collaboration/namespaces.md new file mode 100644 index 00000000..e737752e --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/collaboration/namespaces.md @@ -0,0 +1,41 @@ +--- +title: 团队命名空间 +sidebar_position: 1 +description: 在团队命名空间中协作 +--- + +# 团队命名空间 + +## 加入命名空间 + +需要命名空间管理员邀请才能加入团队命名空间。 + +## 命名空间角色 + +### MEMBER +- 可查看命名空间内所有技能 +- 可发布技能（需审核） +- 可收藏和评分 + +### ADMIN +- 所有 MEMBER 权限 +- 可审核技能发布 +- 可管理成员 +- 可编辑命名空间信息 + +### OWNER +- 所有 ADMIN 权限 +- 可转让所有权 +- 可归档命名空间 + +## 技能可见性 + +| 可见性 | 说明 | +|--------|------| +| `PUBLIC` | 所有人可见，匿名可下载 | +| `NAMESPACE_ONLY` | 仅命名空间成员可见 | +| `PRIVATE` | 仅 owner 和命名空间 ADMIN 可见 | + +## 下一步 + +- [提升到全局](./promotion) - 将团队技能推广到全局 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/collaboration/promotion.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/collaboration/promotion.md new file mode 100644 index 00000000..7d065430 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/collaboration/promotion.md @@ -0,0 +1,42 @@ +--- +title: 提升到全局 +sidebar_position: 2 +description: 申请将团队技能提升到全局空间 +--- + +# 提升到全局 + +优秀的团队技能可以申请提升到全局空间，供全企业使用。 + +## 提升前提 + +- 技能在团队空间已发布 +- 申请人是技能 owner 或命名空间 ADMIN +- 技能没有待审核的提升申请 + +## 申请提升 + +1. 进入团队技能详情页 +2. 点击"提升到全局" +3. 填写申请说明 +4. 提交申请 + +## 审核流程 + +1. 平台管理员收到提升申请 +2. 审核技能质量和适用性 +3. 审核通过后： + - 在全局空间创建新技能 + - 保留原团队技能 + - 记录来源追溯关系 + +## 提升后 + +- 全局空间的新技能独立管理 +- 原团队技能继续存在 +- 两者版本不自动同步 +- 如需同步需手动操作 + +## 下一步 + +- [API 概述](../../developer/api/overview) - API 集成 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/_category_.json b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/_category_.json new file mode 100644 index 00000000..7014e21d --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "发现与使用", + "position": 2 +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/install.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/install.md new file mode 100644 index 00000000..9cdf9254 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/install.md @@ -0,0 +1,53 @@ +--- +title: 安装使用 +sidebar_position: 2 +description: 安装和使用技能 +--- + +# 安装使用 + +## 通过 CLI 安装 + +### 安装最新版本 + +```bash +clawhub install @team/my-skill +``` + +### 安装指定版本 + +```bash +clawhub install @team/my-skill@1.2.0 +``` + +### 按标签安装 + +```bash +clawhub install @team/my-skill@beta +``` + +### 使用 ClawHub CLI 安装 + +```bash +clawhub install my-skill +clawhub install team-name--my-skill +``` + +## 安装目录 + +按以下优先级安装： + +| 优先级 | 路径 | 说明 | +|--------|------|------| +| 1 | `./.agent/skills/` | 项目级，universal 模式 | +| 2 | `~/.agent/skills/` | 全局级，universal 模式 | +| 3 | `./.claude/skills/` | 项目级，Claude 默认 | +| 4 | `~/.claude/skills/` | 全局级，Claude 默认 | + +## 在 Claude Code 中使用 + +安装后，技能会被 Claude Code 自动发现和加载。 + +## 下一步 + +- [评分与收藏](./ratings) - 反馈和收藏技能 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/ratings.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/ratings.md new file mode 100644 index 00000000..8745a87f --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/ratings.md @@ -0,0 +1,30 @@ +--- +title: 评分与收藏 +sidebar_position: 3 +description: 技能评分和收藏功能 +--- + +# 评分与收藏 + +## 收藏技能 + +点击技能详情页的"收藏"按钮可收藏技能。 + +查看已收藏的技能： +- Web：进入"我的收藏" +- CLI：`clawhub stars` + +## 技能评分 + +可对技能进行 1-5 分评分： + +1. 进入技能详情页 +2. 点击评分区域 +3. 选择评分（1-5 星） +4. 提交评分 + +可随时修改自己的评分。 + +## 下一步 + +- [团队命名空间](../collaboration/namespaces) - 团队协作 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/search.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/search.md new file mode 100644 index 00000000..01da8f73 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/discovery/search.md @@ -0,0 +1,36 @@ +--- +title: 搜索技能 +sidebar_position: 1 +description: 搜索和筛选技能 +--- + +# 搜索技能 + +## 全文搜索 + +在搜索框输入关键词，SkillHub 会在以下字段中搜索： +- 技能名称 +- 技能描述 +- 技能 slug +- frontmatter 中除 `name`、`description`、`version` 外的其他字段 +- `keywords` / `tags` 等关键词字段 + +## 筛选条件 + +可通过以下条件筛选搜索结果： +- 命名空间 +- 可见性 +- 下载量排序 +- 评分排序 +- 更新时间排序 + +## 高级搜索 + +使用搜索语法： +- `namespace:@team-ai` - 指定命名空间 +- `category:code-review` - 指定分类 +- `downloads:>100` - 下载量大于 100 + +## 下一步 + +- [安装使用](./install) - 安装和使用技能 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/_category_.json b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/_category_.json new file mode 100644 index 00000000..a8284d4a --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "发布技能", + "position": 1 +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/create-skill.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/create-skill.md new file mode 100644 index 00000000..929d6a8d --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/create-skill.md @@ -0,0 +1,56 @@ +--- +title: 创建技能包 +sidebar_position: 1 +description: 学习如何创建符合规范的技能包 +--- + +# 创建技能包 + +## 技能包结构 + +一个标准的 SkillHub 技能包结构如下： + +``` +my-skill/ +├── SKILL.md # 主入口文件（必需） +├── references/ # 参考资料（可选） +├── scripts/ # 脚本（可选） +└── assets/ # 静态资源（可选） +``` + +## SKILL.md 格式 + +SKILL.md 是技能包的主入口文件，使用 YAML frontmatter + Markdown 正文格式： + +```markdown +--- +name: my-skill +description: 一句话描述这个技能的用途 +x-astron-category: code-review +--- + +# 技能说明 + +这里是技能的详细说明... +``` + +### Frontmatter 字段 + +| 字段 | 必需 | 说明 | +|------|------|------| +| `name` | 是 | 技能标识，kebab-case 格式 | +| `description` | 是 | 技能简短描述 | +| `x-astron-category` | 否 | 分类标签 | +| `x-astron-runtime` | 否 | 运行时要求 | +| `x-astron-min-version` | 否 | 最低版本要求 | + +## 文件限制 + +- 单文件大小：最大 1MB +- 总包大小：最大 10MB +- 文件数量：最多 100 个 +- 允许的文件类型：`.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.js`, `.ts`, `.py`, `.sh`, `.png`, `.jpg`, `.svg` + +## 下一步 + +- [发布流程](./publish) - 发布技能包 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/publish.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/publish.md new file mode 100644 index 00000000..4fd86f69 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/publish.md @@ -0,0 +1,50 @@ +--- +title: 发布流程 +sidebar_position: 2 +description: 发布技能到 SkillHub +--- + +# 发布流程 + +## 通过 Web 发布 + +1. 登录 SkillHub +2. 点击"发布技能" +3. 选择目标命名空间 +4. 上传技能包 ZIP 文件 +5. 填写版本信息（变更日志等） +6. 提交发布 +7. 等待审核（如需要） +8. 审核通过后发布成功 + +## 通过 CLI 发布 + +```bash +# 1. 登录 +clawhub login + +# 2. 发布 +clawhub publish ./my-skill.zip --namespace @team-myteam +``` + +## 通过 ClawHub CLI 发布 + +配置 registry 后使用： + +```bash +clawhub publish ./my-skill.zip +``` + +## 发布状态 + +| 状态 | 说明 | +|------|------| +| `DRAFT` | 草稿，未提交审核 | +| `PENDING_REVIEW` | 等待审核 | +| `PUBLISHED` | 已发布，可被发现和下载 | +| `REJECTED` | 已拒绝，需修改后重新提交 | +| `YANKED` | 已撤回，不再推荐使用 | + +## 下一步 + +- [版本管理](./versioning) - 管理技能版本 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/versioning.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/versioning.md new file mode 100644 index 00000000..a0a4d05f --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/03-user-guide/publishing/versioning.md @@ -0,0 +1,56 @@ +--- +title: 版本管理 +sidebar_position: 3 +description: 技能版本和标签管理 +--- + +# 版本管理 + +## 语义化版本 + +SkillHub 使用语义化版本（Semantic Versioning）：`MAJOR.MINOR.PATCH` + +- `MAJOR`：不兼容的 API 变更 +- `MINOR`：向后兼容的功能新增 +- `PATCH`：向后兼容的问题修复 + +示例：`1.0.0`, `1.1.0`, `2.0.0` + +## latest 标签 + +`latest` 是系统保留标签，自动跟随最新已发布版本，不可手动移动。 + +## 自定义标签 + +可创建自定义标签用于版本通道管理： + +- `beta` - 测试版本 +- `stable` - 稳定版本 +- `stable-2026q1` - 季度稳定版本 + +### 创建/移动标签 + +```bash +clawhub tag set @team/my-skill beta 1.2.0 +``` + +### 删除标签 + +```bash +clawhub tag delete @team/my-skill beta +``` + +## 版本撤回 + +已发布版本发现问题可撤回： + +1. 进入技能详情页 +2. 找到目标版本 +3. 点击"撤回版本" +4. 确认撤回 + +撤回后的版本仍可查看，但会标记为不推荐使用。 + +## 下一步 + +- [搜索技能](../discovery/search) - 发现技能 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/_category_.json b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/_category_.json new file mode 100644 index 00000000..6c210bd9 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "开发者参考", + "position": 4, + "link": { + "type": "generated-index", + "description": "API 参考、架构设计和扩展开发" + } +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/_category_.json b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/_category_.json new file mode 100644 index 00000000..7f8d3e0e --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "API 参考", + "position": 1 +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/authenticated.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/authenticated.md new file mode 100644 index 00000000..3efe82dd --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/authenticated.md @@ -0,0 +1,101 @@ +--- +title: 认证 API +sidebar_position: 3 +description: 需要认证的 API +--- + +# 认证 API + +## 认证相关 + +### 获取当前用户 + +```http +GET /api/v1/auth/me +``` + +### 登出 + +```http +POST /api/v1/auth/logout +``` + +## 技能发布 + +```http +POST /api/v1/publish +Content-Type: multipart/form-data + +file: +namespace: +``` + +## 收藏 + +```http +POST /api/v1/skills/{namespace}/{slug}/star +DELETE /api/v1/skills/{namespace}/{slug}/star +``` + +## 评分 + +```http +POST /api/v1/skills/{namespace}/{slug}/rating +Content-Type: application/json + +{ + "score": 5 +} +``` + +## 标签管理 + +```http +GET /api/v1/skills/{namespace}/{slug}/tags +PUT /api/v1/skills/{namespace}/{slug}/tags/{tagName} +DELETE /api/v1/skills/{namespace}/{slug}/tags/{tagName} +``` + +## 我的资源 + +```http +GET /api/v1/me/stars +GET /api/v1/me/skills +``` + +## 命名空间管理 + +```http +POST /api/v1/namespaces +PUT /api/v1/namespaces/{slug} +GET /api/v1/namespaces/{slug}/members +POST /api/v1/namespaces/{slug}/members +PUT /api/v1/namespaces/{slug}/members/{userId}/role +DELETE /api/v1/namespaces/{slug}/members/{userId} +``` + +## 审核 + +```http +GET /api/v1/namespaces/{slug}/reviews +POST /api/v1/namespaces/{slug}/reviews/{id}/approve +POST /api/v1/namespaces/{slug}/reviews/{id}/reject +``` + +## 提升申请 + +```http +POST /api/v1/namespaces/{slug}/skills/{skillId}/promote +``` + +## API Token + +```http +POST /api/v1/tokens +GET /api/v1/tokens +DELETE /api/v1/tokens/{id} +``` + +## 下一步 + +- [CLI 兼容层](./cli-compat) - ClawHub 兼容接口 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/cli-compat.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/cli-compat.md new file mode 100644 index 00000000..e411a59d --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/cli-compat.md @@ -0,0 +1,159 @@ +--- +title: CLI 兼容层 +sidebar_position: 4 +description: ClawHub CLI 协议兼容层 +--- + +# CLI 兼容层 + +SkillHub 提供 ClawHub CLI 协议兼容层，现有工具可无缝迁移。 + +## 配置 ClawHub CLI + +要让 ClawHub CLI 连接到你的 SkillHub 实例，需要配置以下环境变量： + +### 环境变量配置 + +**Linux/macOS (bash/zsh):** +```bash +# ~/.bashrc 或 ~/.zshrc +export CLAWHUB_SITE=https://skill.xfyun.cn +export CLAWHUB_REGISTRY=https://skill.xfyun.cn +``` + +**Windows (PowerShell):** +```powershell +# 永久设置（当前用户） +[Environment]::SetEnvironmentVariable('CLAWHUB_SITE', 'https://skill.xfyun.cn', 'User') +[Environment]::SetEnvironmentVariable('CLAWHUB_REGISTRY', 'https://skill.xfyun.cn', 'User') + +# 或者临时设置（当前会话） +$env:CLAWHUB_SITE = 'https://skill.xfyun.cn' +$env:CLAWHUB_REGISTRY = 'https://skill.xfyun.cn' +``` + +### 使用 CLI 标志（单次命令） + +```bash +clawhub --site https://skill.xfyun.cn --registry https://skill.xfyun.cn install +``` + +### 前端一键复制 + +SkillHub 网页端的技能详情页会自动显示带有正确环境变量的安装命令，直接复制即可使用。 + +## Well-known 发现 + +```http +GET /.well-known/clawhub.json +``` + +响应： + +```json +{ + "apiBase": "/api/v1" +} +``` + +## 兼容层 API + +### Whoami + +```http +GET /api/v1/whoami +``` + +响应： + +```json +{ + "handle": "username", + "displayName": "User Name", + "role": "user" +} +``` + +### 搜索 + +```http +GET /api/v1/search?q={keyword}&page={page}&limit={limit} +``` + +响应： + +```json +{ + "results": [ + { + "slug": "my-skill", + "name": "My Skill", + "description": "...", + "author": { + "handle": "username", + "displayName": "User Name" + }, + "version": "1.2.0", + "downloadCount": 100, + "starCount": 50, + "createdAt": "2026-01-01T00:00:00Z", + "updatedAt": "2026-03-01T00:00:00Z" + } + ], + "total": 1, + "page": 1, + "limit": 20 +} +``` + +### 解析 + +```http +GET /api/v1/resolve?slug={slug}&version={version} +``` + +响应： + +```json +{ + "slug": "my-skill", + "version": "1.2.0", + "downloadUrl": "/api/v1/download/my-skill/1.2.0" +} +``` + +### 下载 + +```http +GET /api/v1/download/{slug}/{version} +``` + +### 发布 + +```http +POST /api/v1/publish +Content-Type: multipart/form-data + +file: +``` + +响应： + +```json +{ + "slug": "my-skill", + "version": "1.0.0", + "status": "published" +} +``` + +## 坐标映射 + +| SkillHub 坐标 | ClawHub canonical slug | +|---------------|------------------------| +| `@global/my-skill` | `my-skill` | +| `@team-name/my-skill` | `team-name--my-skill` | + +## 下一步 + +- [系统架构](../architecture/overview) - 了解架构设计 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/overview.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/overview.md new file mode 100644 index 00000000..7508d483 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/overview.md @@ -0,0 +1,86 @@ +--- +title: API 概述 +sidebar_position: 1 +description: SkillHub API 概述 +--- + +# API 概述 + +SkillHub 提供 RESTful API 用于集成和自动化。 + +## API 分类 + +### 公开 API +- 技能搜索 +- 技能详情 +- 版本列表 +- 下载技能 +- 无需认证（PUBLIC 技能） + +### 认证 API +- 发布技能 +- 收藏/评分 +- 命名空间管理 +- 需要登录或 Bearer Token + +### CLI 兼容层 +- 兼容 ClawHub CLI 协议 +- 现有工具可无缝迁移 + +## 响应格式 + +### 统一响应结构 + +```json +{ + "code": 0, + "msg": "成功", + "data": {}, + "timestamp": "2026-03-15T06:00:00Z", + "requestId": "req-123" +} +``` + +### 分页响应 + +```json +{ + "code": 0, + "msg": "成功", + "data": { + "items": [], + "total": 100, + "page": 1, + "size": 20 + }, + "timestamp": "2026-03-15T06:00:00Z", + "requestId": "req-123" +} +``` + +## 认证方式 + +### Session Cookie +Web 端使用 Session Cookie 认证。 + +### Bearer Token +CLI 和 API 集成使用 Bearer Token： + +```bash +Authorization: Bearer +``` + +### API Token +可创建长期有效的 API Token 用于自动化。 + +## 幂等性 + +所有写操作支持 `X-Request-Id` 请求头实现幂等： + +```bash +X-Request-Id: +``` + +## 下一步 + +- [公开 API](./public) - 查看公开接口 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/public.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/public.md new file mode 100644 index 00000000..e006994e --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/api/public.md @@ -0,0 +1,72 @@ +--- +title: 公开 API +sidebar_position: 2 +description: 无需认证的公开 API +--- + +# 公开 API + +## 技能搜索 + +```http +GET /api/v1/skills?keyword=...&namespace=...&page=1&size=20 +``` + +**Query Parameters:** +- `keyword`: 搜索关键词 +- `namespace`: 命名空间筛选 +- `page`: 页码 +- `size`: 每页数量 + +## 技能详情 + +```http +GET /api/v1/skills/{namespace}/{slug} +``` + +## 版本列表 + +```http +GET /api/v1/skills/{namespace}/{slug}/versions +``` + +## 版本详情 + +```http +GET /api/v1/skills/{namespace}/{slug}/versions/{version} +``` + +## 文件清单 + +```http +GET /api/v1/skills/{namespace}/{slug}/versions/{version}/files +``` + +## 下载技能 + +```http +GET /api/v1/skills/{namespace}/{slug}/download +GET /api/v1/skills/{namespace}/{slug}/versions/{version}/download +``` + +## 解析版本 + +```http +GET /api/v1/skills/{namespace}/{slug}/resolve?version=...&tag=... +``` + +## 命名空间列表 + +```http +GET /api/v1/namespaces +``` + +## 命名空间详情 + +```http +GET /api/v1/namespaces/{slug} +``` + +## 下一步 + +- [认证 API](./authenticated) - 查看认证接口 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/_category_.json b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/_category_.json new file mode 100644 index 00000000..81a75cfc --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "架构设计", + "position": 2 +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/domain-model.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/domain-model.md new file mode 100644 index 00000000..1f6a4467 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/domain-model.md @@ -0,0 +1,77 @@ +--- +title: 领域模型 +sidebar_position: 2 +description: 核心领域实体和关系 +--- + +# 领域模型 + +## 核心实体 + +### Namespace（命名空间） + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | bigint | 主键 | +| slug | varchar(64) | URL 友好标识 | +| display_name | varchar(128) | 展示名 | +| type | enum | `GLOBAL` / `TEAM` | +| description | text | 描述 | +| status | enum | `ACTIVE` / `FROZEN` / `ARCHIVED` | + +### NamespaceMember（命名空间成员） + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | bigint | 主键 | +| namespace_id | bigint | 命名空间 ID | +| user_id | varchar(128) | 用户 ID | +| role | enum | `OWNER` / `ADMIN` / `MEMBER` | + +### Skill（技能） + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | bigint | 主键 | +| namespace_id | bigint | 所属命名空间 | +| slug | varchar(128) | URL 友好标识 | +| display_name | varchar(256) | 展示名 | +| summary | varchar(512) | 摘要 | +| owner_id | varchar(128) | 主要维护人 | +| visibility | enum | `PUBLIC` / `NAMESPACE_ONLY` / `PRIVATE` | +| status | enum | `ACTIVE` / `HIDDEN` / `ARCHIVED` | +| latest_version_id | bigint | 最新已发布版本 | + +**唯一约束**：`(namespace_id, slug)` + +### SkillVersion（技能版本） + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | bigint | 主键 | +| skill_id | bigint | 技能 ID | +| version | varchar(32) | semver 版本号 | +| status | enum | `DRAFT` / `PENDING_REVIEW` / `PUBLISHED` / `REJECTED` / `YANKED` | +| manifest_json | json | 文件清单 | +| parsed_metadata_json | json | SKILL.md 解析结果 | + +**唯一约束**：`(skill_id, version)` + +### SkillTag（技能标签） + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | bigint | 主键 | +| skill_id | bigint | 技能 ID | +| tag_name | varchar(64) | 标签名 | +| target_version_id | bigint | 目标版本 | + +**唯一约束**：`(skill_id, tag_name)` + +## 坐标系统 + +技能完整寻址：`@{namespace_slug}/{skill_slug}` + +## 下一步 + +- [安全架构](./security) - 安全设计 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/overview.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/overview.md new file mode 100644 index 00000000..e00f6703 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/overview.md @@ -0,0 +1,69 @@ +--- +title: 系统架构 +sidebar_position: 1 +description: SkillHub 系统架构概览 +--- + +# 系统架构 + +## 架构原则 + +- **单体优先**：一期采用模块化单体，不拆微服务 +- **依赖倒置**：领域层不依赖基础设施 +- **可替换边界**：搜索、存储都有 SPI 抽象 + +## 模块结构 + +``` +server/ +├── skillhub-app/ # 启动、配置装配、Controller +├── skillhub-domain/ # 领域模型 + 领域服务 + 应用服务 +├── skillhub-auth/ # OAuth2 认证 + RBAC + 授权判定 +├── skillhub-search/ # 搜索 SPI + PostgreSQL 全文实现 +├── skillhub-storage/ # 对象存储抽象 + LocalFile/S3 +└── skillhub-infra/ # JPA、通用工具、配置基础 +``` + +## 模块依赖 + +``` +app → domain, auth, search, storage, infra +infra → domain +auth → domain +search → domain +storage → (独立) +``` + +## 技术栈 + +| 层级 | 技术 | 版本 | +|------|------|------| +| 运行时 | Java | 21 | +| 框架 | Spring Boot | 3.2.3 | +| 数据库 | PostgreSQL | 16.x | +| 缓存/会话 | Redis | 7.x | + +## 部署架构 + +``` +┌──────────────┐ +│ Browser / CLI│ +└──────┬───────┘ + │ + ▼ +┌──────────────┐ +│ Web/Nginx │ +└──────┬───────┘ + │ /api/* + ▼ +┌──────────────┐ +│ Spring Boot │ +└───┬────┬─────┘ + │ │ + ▼ ▼ +PostgreSQL Redis +``` + +## 下一步 + +- [领域模型](./domain-model) - 核心实体 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/security.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/security.md new file mode 100644 index 00000000..2280d1d9 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/architecture/security.md @@ -0,0 +1,71 @@ +--- +title: 安全架构 +sidebar_position: 3 +description: 安全架构设计 +--- + +# 安全架构 + +## 认证架构 + +### OAuth2 登录 + +- 基于 Spring Security OAuth2 Client +- 一期支持 GitHub +- 架构支持扩展多 Provider + +### CLI 认证 + +- OAuth Device Flow +- Web 授权后签发 CLI 凭证 +- 支持 API Token + +### Session 管理 + +- Spring Session + Redis +- 分布式 Session 共享 +- 支持多 Pod 部署 + +## 授权架构 + +### 平台角色 + +| 角色 | 权限 | +|------|------| +| `SUPER_ADMIN` | 所有权限 | +| `SKILL_ADMIN` | 技能治理 | +| `USER_ADMIN` | 用户治理 | +| `AUDITOR` | 审计只读 | + +### 命名空间角色 + +| 角色 | 权限 | +|------|------| +| `OWNER` | 命名空间所有者 | +| `ADMIN` | 审核、成员管理 | +| `MEMBER` | 发布技能 | + +### 可见性规则 + +| 可见性 | 谁可访问 | +|--------|---------| +| `PUBLIC` | 任何人（匿名） | +| `NAMESPACE_ONLY` | 命名空间成员 | +| `PRIVATE` | owner + 命名空间 ADMIN | + +## 审计 + +所有关键操作同步写入审计日志： +- 发布、下载、删除 +- 审核通过、拒绝 +- 权限变更 +- 配置变更 + +## 限流 + +- Ingress 层基础限流（Nginx） +- 应用层精细限流（Redis 滑动窗口） + +## 下一步 + +- [技能协议](../plugins/skill-protocol) - 技能包规范 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/plugins/_category_.json b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/plugins/_category_.json new file mode 100644 index 00000000..ac3a412e --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/plugins/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "扩展与集成", + "position": 3 +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/plugins/skill-protocol.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/plugins/skill-protocol.md new file mode 100644 index 00000000..bb136814 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/plugins/skill-protocol.md @@ -0,0 +1,68 @@ +--- +title: 技能协议 +sidebar_position: 1 +description: SKILL.md 规范和技能包协议 +--- + +# 技能协议 + +## SKILL.md 规范 + +### 基本格式 + +```markdown +--- +name: my-skill +description: When to use this skill +--- + +# Markdown 正文 + +技能指令内容... +``` + +### 必需字段 + +| 字段 | 说明 | +|------|------| +| `name` | 技能标识，kebab-case | +| `description` | 技能简短描述 | + +### 扩展字段 + +| 字段 | 说明 | +|------|------| +| `x-astron-category` | 分类标签 | +| `x-astron-runtime` | 运行时要求 | +| `x-astron-min-version` | 最低版本要求 | + +## 技能包结构 + +``` +my-skill/ +├── SKILL.md # 主入口文件（必需） +├── references/ # 参考资料（可选） +├── scripts/ # 脚本（可选） +└── assets/ # 静态资源（可选） +``` + +## 文件校验 + +- 根目录必须包含 `SKILL.md` +- 文件类型白名单 +- 单文件大小限制：1MB +- 总包大小限制：10MB +- 文件数量限制：100 个 + +## 客户端安装目录 + +按以下优先级安装： + +1. `./.agent/skills/` +2. `~/.agent/skills/` +3. `./.claude/skills/` +4. `~/.claude/skills/` + +## 下一步 + +- [存储 SPI](./storage-spi) - 扩展存储后端 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/plugins/storage-spi.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/plugins/storage-spi.md new file mode 100644 index 00000000..f81189e1 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/04-developer/plugins/storage-spi.md @@ -0,0 +1,54 @@ +--- +title: 存储 SPI +sidebar_position: 2 +description: 存储服务提供方扩展 +--- + +# 存储 SPI + +## SPI 接口 + +```java +public interface ObjectStorageService { + void store(String key, InputStream content, String contentType); + InputStream retrieve(String key); + void delete(String key); + boolean exists(String key); +} +``` + +## 内置实现 + +### LocalFileStorageService + +本地文件系统实现，用于开发环境。 + +### S3StorageService + +S3 协议兼容实现，支持： +- AWS S3 +- MinIO +- 阿里云 OSS +- 腾讯云 COS +- 其他 S3 兼容存储 + +## 配置 + +```bash +# 选择存储提供方 +SKILLHUB_STORAGE_PROVIDER=s3 + +# S3 配置 +SKILLHUB_STORAGE_S3_ENDPOINT=https://s3.example.com +SKILLHUB_STORAGE_S3_BUCKET=skillhub +SKILLHUB_STORAGE_S3_ACCESS_KEY=xxx +SKILLHUB_STORAGE_S3_SECRET_KEY=xxx +``` + +## 自定义实现 + +实现 `ObjectStorageService` 接口，注册为 Spring Bean 即可。 + +## 下一步 + +- [常见问题](../../reference/faq) - FAQ diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/_category_.json b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/_category_.json new file mode 100644 index 00000000..15e14d0e --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "参考资料", + "position": 5, + "link": { + "type": "generated-index", + "description": "FAQ、故障排查和更多资源" + } +} diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/changelog.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/changelog.md new file mode 100644 index 00000000..de6f5078 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/changelog.md @@ -0,0 +1,20 @@ +--- +title: 变更日志 +sidebar_position: 3 +description: 版本变更历史 +--- + +# 变更日志 + +## [Unreleased] + +### Added +- 初始版本发布 +- 技能发布与管理 +- 命名空间与 RBAC +- 全文搜索 +- ClawHub CLI 兼容层 + +## 下一步 + +- [路线图](./roadmap) - 未来规划 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/faq.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/faq.md new file mode 100644 index 00000000..eb2d352c --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/faq.md @@ -0,0 +1,49 @@ +--- +title: 常见问题 +sidebar_position: 1 +description: 常见问题解答 +--- + +# 常见问题 + +## 部署相关 + +### 如何修改默认端口？ + +修改 `.env.release` 中的端口配置。 + +### 如何配置 HTTPS？ + +建议使用反向代理（Nginx/Ingress）处理 TLS 终止。 + +### 数据库如何备份？ + +使用 PostgreSQL 标准备份工具（pg_dump）。 + +## 使用相关 + +### 如何重置管理员密码？ + +如果忘记管理员密码，可通过环境变量重新设置首登管理员，或直接操作数据库。 + +### 技能包上传失败怎么办？ + +检查： +1. 文件大小是否超限 +2. 文件类型是否在白名单内 +3. 是否包含必需的 SKILL.md +4. SKILL.md frontmatter 格式是否正确 + +## 开发相关 + +### 如何扩展 OAuth Provider？ + +参考现有 GitHub 实现，添加新的 OAuth Provider 配置。 + +### 如何自定义搜索实现？ + +实现 `SearchIndexService` 和 `SearchQueryService` 接口。 + +## 下一步 + +- [故障排查](./troubleshooting) - 问题诊断 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/roadmap.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/roadmap.md new file mode 100644 index 00000000..1477856b --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/roadmap.md @@ -0,0 +1,45 @@ +--- +title: 路线图 +sidebar_position: 4 +description: 未来发展路线图 +--- + +# 路线图 + +## Phase 1: 基础能力 ✅ + +- GitHub OAuth 登录 +- Session 管理 +- RBAC 权限体系 + +## Phase 2: 技能核心 ✅ + +- 命名空间管理 +- 技能发布与下载 +- 版本管理 +- PostgreSQL 全文搜索 + +## Phase 3: 审核与 CLI + +- 审核流程 +- 技能提升到全局 +- CLI 工具 +- 收藏与评分 + +## Phase 4: 运维与完善 + +- 审计日志 +- 管理后台 +- 可观测性 +- 部署优化 + +## Phase 5: 高级特性 + +- 评论与举报 +- 自动安全扫描 +- 向量搜索 +- Webhook 通知 + +## 下一步 + +- [快速开始](../getting-started/quick-start) - 开始使用 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/troubleshooting.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/troubleshooting.md new file mode 100644 index 00000000..492d910f --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/05-reference/troubleshooting.md @@ -0,0 +1,63 @@ +--- +title: 故障排查 +sidebar_position: 2 +description: 常见问题诊断和解决方案 +--- + +# 故障排查 + +## 服务无法启动 + +### 检查清单 + +1. 检查容器状态：`docker compose ps` +2. 查看服务日志：`docker compose logs ` +3. 验证环境变量：检查 `.env.release` 配置 +4. 检查端口占用：`netstat -tlnp` + +### 常见原因 + +- 端口被占用 +- 数据库连接失败 +- Redis 连接失败 +- 环境变量缺失 + +## 上传失败 + +### 技能包上传失败 + +1. 检查文件大小 +2. 检查文件类型 +3. 检查 SKILL.md 格式 +4. 查看服务端日志 + +## 认证问题 + +### 无法登录 + +1. 检查 OAuth 配置 +2. 检查回调地址配置 +3. 检查 `SKILLHUB_PUBLIC_BASE_URL` 配置 + +## 性能问题 + +### 搜索慢 + +1. 检查 PostgreSQL 全文索引 +2. 考虑升级到 Elasticsearch（后续版本） + +### 下载慢 + +1. 检查对象存储配置 +2. 检查网络带宽 + +## 获取帮助 + +如以上方案无法解决问题： +1. 查看日志 +2. 提交 Issue +3. 联系技术支持 + +## 下一步 + +- [变更日志](./changelog) - 版本历史 diff --git a/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/index.md b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/index.md new file mode 100644 index 00000000..bca1b639 --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-plugin-content-docs/current/index.md @@ -0,0 +1,22 @@ +--- +title: SkillHub 文档中心 +sidebar_position: 1 +description: 面向企业团队的开源智能体技能注册中心，提供发布、发现、审核与治理一体化能力 +--- + +# SkillHub + +SkillHub 是一个面向企业团队的开源 Agent Skill Registry，提供发布、发现、审核与治理一体化能力。 + +## 从这里开始 + +- [快速开始](./getting-started/quick-start) - 一键启动 SkillHub +- [产品概述](./getting-started/overview) - 了解平台定位与核心概念 +- [使用场景](./getting-started/use-cases) - 查看 SkillHub 在组织内的典型落地方式 + +## 主要内容 + +- [管理员指南](./administration/deployment/single-machine) - 部署、安全、治理与运维能力 +- [用户指南](./user-guide/publishing/publish) - 发布、发现、协作与推广流程 +- [开发者参考](./developer/api/overview) - API、架构、扩展与兼容性说明 +- [参考资料](./reference/faq) - FAQ、排障、变更记录与路线图 diff --git a/document/i18n/zh-CN/docusaurus-theme-classic/footer.json b/document/i18n/zh-CN/docusaurus-theme-classic/footer.json new file mode 100644 index 00000000..a6cbacbd --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-theme-classic/footer.json @@ -0,0 +1,30 @@ +{ + "link.title.Documentation": { + "message": "文档", + "description": "The title of the footer links column with title=Documentation in the footer" + }, + "link.title.Community": { + "message": "社区", + "description": "The title of the footer links column with title=Community in the footer" + }, + "link.item.label.Quick Start": { + "message": "快速开始", + "description": "The label of footer link with label=Quick Start linking to /docs/getting-started/quick-start" + }, + "link.item.label.Deployment": { + "message": "部署指南", + "description": "The label of footer link with label=Deployment linking to /docs/administration/deployment/single-machine" + }, + "link.item.label.API Reference": { + "message": "API 参考", + "description": "The label of footer link with label=API Reference linking to /docs/developer/api/overview" + }, + "link.item.label.GitHub": { + "message": "GitHub", + "description": "The label of footer link with label=GitHub linking to https://github.com/iflytek/skillhub" + }, + "copyright": { + "message": "版权所有 © 2026 iFlytek。由 Docusaurus 构建。", + "description": "The footer copyright" + } +} diff --git a/document/i18n/zh-CN/docusaurus-theme-classic/navbar.json b/document/i18n/zh-CN/docusaurus-theme-classic/navbar.json new file mode 100644 index 00000000..73d6d57a --- /dev/null +++ b/document/i18n/zh-CN/docusaurus-theme-classic/navbar.json @@ -0,0 +1,26 @@ +{ + "logo.alt": { + "message": "Astron SkillHub 标志", + "description": "The alt text of navbar logo" + }, + "item.label.Quick Start": { + "message": "快速开始", + "description": "Navbar item with label Quick Start" + }, + "item.label.Overview": { + "message": "产品概览", + "description": "Navbar item with label Overview" + }, + "item.label.Publish Workflow": { + "message": "发布流程", + "description": "Navbar item with label Publish Workflow" + }, + "item.label.Single Node": { + "message": "单机部署", + "description": "Navbar item with label Single Node" + }, + "item.label.GitHub": { + "message": "GitHub", + "description": "Navbar item with label GitHub" + } +} diff --git a/document/package.json b/document/package.json index b67b60c9..c974638d 100644 --- a/document/package.json +++ b/document/package.json @@ -16,6 +16,7 @@ }, "dependencies": { "@docusaurus/core": "^3.9.2", + "@docusaurus/plugin-client-redirects": "^3.9.2", "@docusaurus/preset-classic": "^3.9.2", "@mdx-js/react": "^3.0.0", "clsx": "^2.0.0", diff --git a/document/sidebars.js b/document/sidebars.js index d45d11d8..b0e2ba80 100644 --- a/document/sidebars.js +++ b/document/sidebars.js @@ -4,7 +4,7 @@ const sidebars = { 'index', { type: 'category', - label: '快速入门', + label: 'Getting Started', link: { type: 'generated-index', }, @@ -16,14 +16,14 @@ const sidebars = { }, { type: 'category', - label: '管理员指南', + label: 'Administration Guide', link: { type: 'generated-index', }, items: [ { type: 'category', - label: '部署指南', + label: 'Deployment Guide', items: [ 'administration/deployment/single-machine', 'administration/deployment/kubernetes', @@ -32,16 +32,17 @@ const sidebars = { }, { type: 'category', - label: '安全与合规', + label: 'Security & Compliance', items: [ 'administration/security/authentication', 'administration/security/authorization', 'administration/security/audit-logs', + 'administration/security/scanner', ], }, { type: 'category', - label: '治理与运营', + label: 'Governance & Operations', items: [ 'administration/governance/namespaces', 'administration/governance/review-workflow', @@ -52,14 +53,14 @@ const sidebars = { }, { type: 'category', - label: '用户指南', + label: 'User Guide', link: { type: 'generated-index', }, items: [ { type: 'category', - label: '发布技能', + label: 'Publishing Skills', items: [ 'user-guide/publishing/create-skill', 'user-guide/publishing/publish', @@ -68,7 +69,7 @@ const sidebars = { }, { type: 'category', - label: '发现与使用', + label: 'Discovery & Usage', items: [ 'user-guide/discovery/search', 'user-guide/discovery/install', @@ -77,7 +78,7 @@ const sidebars = { }, { type: 'category', - label: '协作', + label: 'Collaboration', items: [ 'user-guide/collaboration/namespaces', 'user-guide/collaboration/promotion', @@ -87,14 +88,14 @@ const sidebars = { }, { type: 'category', - label: '开发者参考', + label: 'Developer Reference', link: { type: 'generated-index', }, items: [ { type: 'category', - label: 'API 参考', + label: 'API Reference', items: [ 'developer/api/overview', 'developer/api/public', @@ -104,7 +105,7 @@ const sidebars = { }, { type: 'category', - label: '架构设计', + label: 'Architecture', items: [ 'developer/architecture/overview', 'developer/architecture/domain-model', @@ -113,7 +114,7 @@ const sidebars = { }, { type: 'category', - label: '扩展与集成', + label: 'Extensions & Integrations', items: [ 'developer/plugins/skill-protocol', 'developer/plugins/storage-spi', @@ -123,7 +124,7 @@ const sidebars = { }, { type: 'category', - label: '参考资料', + label: 'Reference', link: { type: 'generated-index', }, diff --git a/document/src/css/custom.css b/document/src/css/custom.css index 99a39951..9fdd4068 100644 --- a/document/src/css/custom.css +++ b/document/src/css/custom.css @@ -1,215 +1,800 @@ /** - * SkillHub 自定义样式 - 讯飞蓝色系 + * SkillHub public docs visual refresh */ :root { - /* 主色：讯飞蓝 */ - --ifm-color-primary: #0052D9; - --ifm-color-primary-dark: #003DA6; - --ifm-color-primary-darker: #002E7A; - --ifm-color-primary-darkest: #001F52; - --ifm-color-primary-light: #4080FF; - --ifm-color-primary-lighter: #6699FF; - --ifm-color-primary-lightest: #99BBFF; + --ifm-color-primary: #2563eb; + --ifm-color-primary-dark: #1d4ed8; + --ifm-color-primary-darker: #1e40af; + --ifm-color-primary-darkest: #172554; + --ifm-color-primary-light: #3b82f6; + --ifm-color-primary-lighter: #60a5fa; + --ifm-color-primary-lightest: #bfdbfe; - /* 辅助色 */ - --ifm-color-secondary: #00B42A; - --ifm-color-warning: #FF7D00; - --ifm-color-danger: #F53F3F; + --ifm-color-secondary: #16a34a; + --ifm-color-warning: #f59e0b; + --ifm-color-danger: #ef4444; - /* 中性色 */ - --ifm-color-gray-0: #F7F8FA; - --ifm-color-gray-100: #F2F3F5; - --ifm-color-gray-200: #E5E6EB; - --ifm-color-gray-300: #C9CDD4; - --ifm-color-gray-400: #86909C; - --ifm-color-gray-500: #4E5969; - --ifm-color-gray-600: #272E3B; - --ifm-color-gray-700: #1D2129; - --ifm-color-gray-800: #0F1218; - --ifm-color-gray-900: #000000; + --ifm-color-gray-0: #f8fafc; + --ifm-color-gray-100: #f1f5f9; + --ifm-color-gray-200: #e2e8f0; + --ifm-color-gray-300: #cbd5e1; + --ifm-color-gray-400: #94a3b8; + --ifm-color-gray-500: #64748b; + --ifm-color-gray-600: #475569; + --ifm-color-gray-700: #334155; + --ifm-color-gray-800: #0f172a; + --ifm-color-gray-900: #020617; - /* 背景色 */ - --ifm-background-color: #FFFFFF; - --ifm-background-surface-color: #F7F8FA; + --ifm-background-color: #ffffff; + --ifm-background-surface-color: #f8fafc; + --ifm-font-color-base: #0f172a; + --ifm-font-color-secondary: #475569; + --ifm-font-color-muted: #64748b; - /* 文本色 */ - --ifm-font-color-base: #1D2129; - --ifm-font-color-secondary: #4E5969; - --ifm-font-color-muted: #86909C; - - /* 导航栏 */ - --ifm-navbar-background-color: #FFFFFF; - --ifm-navbar-shadow: 0 2px 8px rgba(0, 0, 0, 0.08); - - /* 侧边栏 */ - --ifm-sidebar-background-color: #F7F8FA; - --ifm-sidebar-border-color: #E5E6EB; + --ifm-navbar-background-color: rgba(255, 255, 255, 0.82); + --ifm-navbar-shadow: 0 12px 40px rgba(15, 23, 42, 0.08); + --ifm-sidebar-background-color: #f8fafc; + --ifm-sidebar-border-color: rgba(148, 163, 184, 0.18); + --ifm-code-font-size: 0.95rem; + --ifm-heading-color: #020617; + --skillhub-grid-line: rgba(148, 163, 184, 0.18); + --skillhub-card-border: rgba(148, 163, 184, 0.18); + --skillhub-card-shadow: 0 20px 60px rgba(37, 99, 235, 0.08); + --skillhub-footer-bg: linear-gradient(135deg, #1e40af 0%, #2563eb 54%, #3b82f6 100%); + --skillhub-footer-title: #eff6ff; + --skillhub-footer-link: #bfdbfe; + --skillhub-footer-link-hover: #dbeafe; + --skillhub-footer-copy: #93c5fd; } -/* 深色模式 */ [data-theme='dark'] { - --ifm-color-primary: #4080FF; - --ifm-color-primary-dark: #0052D9; - --ifm-color-primary-darker: #003DA6; - --ifm-color-primary-darkest: #002E7A; - --ifm-color-primary-light: #6699FF; - --ifm-color-primary-lighter: #99BBFF; - --ifm-color-primary-lightest: #CCDDFF; + --ifm-color-primary: #60a5fa; + --ifm-color-primary-dark: #3b82f6; + --ifm-color-primary-darker: #2563eb; + --ifm-color-primary-darkest: #1d4ed8; + --ifm-color-primary-light: #93c5fd; + --ifm-color-primary-lighter: #bfdbfe; + --ifm-color-primary-lightest: #dbeafe; - --ifm-background-color: #1D2129; - --ifm-background-surface-color: #272E3B; + --ifm-background-color: #020617; + --ifm-background-surface-color: #0f172a; + --ifm-font-color-base: #e2e8f0; + --ifm-font-color-secondary: #94a3b8; + --ifm-font-color-muted: #64748b; - --ifm-font-color-base: #F7F8FA; - --ifm-font-color-secondary: #C9CDD4; - --ifm-font-color-muted: #86909C; - - --ifm-navbar-background-color: #272E3B; - --ifm-sidebar-background-color: #272E3B; - --ifm-sidebar-border-color: #3E475A; + --ifm-navbar-background-color: rgba(2, 6, 23, 0.82); + --ifm-sidebar-background-color: #020617; + --ifm-sidebar-border-color: rgba(71, 85, 105, 0.48); + --ifm-heading-color: #f8fafc; + --skillhub-grid-line: rgba(100, 116, 139, 0.24); + --skillhub-card-border: rgba(100, 116, 139, 0.28); + --skillhub-card-shadow: 0 24px 64px rgba(15, 23, 42, 0.4); +} + +.footer { + background: var(--skillhub-footer-bg); +} + +.footer__title { + color: var(--skillhub-footer-title); +} + +.footer__link-item { + color: var(--skillhub-footer-link); +} + +.footer__link-item:hover { + color: var(--skillhub-footer-link-hover); + text-decoration: none; +} + +.footer__copyright { + color: var(--skillhub-footer-copy); +} + +.navbar { + min-height: 4.6rem; + padding: 0.7rem 0; + backdrop-filter: blur(18px); + border-bottom: 1px solid rgba(148, 163, 184, 0.12); +} + +.navbar__brand { + display: inline-flex; + align-items: center; + gap: 0.85rem; + padding: 0.35rem 0.2rem 0.35rem 0; + min-height: 3rem; +} + +.navbar__logo img { + height: 2.2rem; + width: auto; +} + +.navbar__items--left { + align-items: center; + gap: 0.45rem; + margin-left: 1rem; +} + +.navbar__item.navbar__link { + display: inline-flex; + align-items: center; + justify-content: center; + min-height: 2.75rem; + padding: 0.62rem 1rem; + border-radius: 999px; + font-size: 0.94rem; + font-weight: 600; + letter-spacing: -0.01em; + color: var(--ifm-font-color-secondary); + transition: + color 0.2s ease, + background-color 0.2s ease, + box-shadow 0.2s ease, + transform 0.2s ease; +} + +.navbar__link { + margin: 0; +} + +.navbar__item.navbar__link:hover { + color: var(--ifm-color-primary-darker); + background: rgba(37, 99, 235, 0.08); + text-decoration: none; + transform: translateY(-1px); +} + +.navbar__item.navbar__link--active, +.navbar__item.navbar__link--active:hover { + color: var(--ifm-color-primary-darker); + background: rgba(37, 99, 235, 0.12); + box-shadow: inset 0 0 0 1px rgba(37, 99, 235, 0.16); +} + +.navbar__item.navbar__link:focus-visible { + outline: none; + color: var(--ifm-color-primary-darker); + background: rgba(37, 99, 235, 0.12); + box-shadow: + inset 0 0 0 1px rgba(37, 99, 235, 0.18), + 0 0 0 3px rgba(96, 165, 250, 0.22); +} + +[data-theme='dark'] .navbar__item.navbar__link { + color: #cbd5e1; +} + +[data-theme='dark'] .navbar__item.navbar__link:hover { + color: #eff6ff; + background: rgba(96, 165, 250, 0.16); +} + +[data-theme='dark'] .navbar__item.navbar__link--active, +[data-theme='dark'] .navbar__item.navbar__link--active:hover, +[data-theme='dark'] .navbar__item.navbar__link:focus-visible { + color: #eff6ff; + background: rgba(96, 165, 250, 0.18); + box-shadow: + inset 0 0 0 1px rgba(147, 197, 253, 0.22), + 0 0 0 3px rgba(30, 64, 175, 0.22); +} + +[data-theme='dark'] .navbar__logo { + padding: 0.2rem 0.45rem; + border-radius: 10px; + background: rgba(248, 250, 252, 0.94); +} + +.theme-doc-markdown { + max-width: 100%; +} + +.theme-doc-markdown h2 { + font-size: clamp(1.8rem, 2vw, 2.4rem); + letter-spacing: -0.03em; +} + +.landing-page .container { + max-width: 1280px; +} + +.landing-section { + padding: 1.25rem 0 0; +} + +.landing-section--compact { + padding-bottom: 1rem; +} + +.landing-page h2 { + font-size: clamp(1.8rem, 2vw, 2.4rem); + letter-spacing: -0.03em; + margin-bottom: 0; +} + +.landing-links { + margin: 2rem 0 0; + padding-left: 1.25rem; +} + +.landing-links li + li { + margin-top: 0.85rem; +} + +.landing-page .hero-section { + margin-top: 0; +} + +html.docs-doc-id-index .theme-doc-sidebar-container, +html.docs-doc-id-index .theme-doc-toc-desktop, +html.docs-doc-id-index .theme-doc-toc-mobile { + display: none; +} + +html.docs-doc-id-index main[class*='docMainContainer'] { + max-width: 100%; +} + +html.docs-doc-id-index .row { + justify-content: center !important; +} + +html.docs-doc-id-index [class*='docItemCol'] { + max-width: 100% !important; + width: 100% !important; + flex: 0 0 100% !important; +} + +html.docs-doc-id-index .row > .col.col--3 { + display: none !important; + max-width: 0 !important; + width: 0 !important; + flex: 0 0 0 !important; +} + +html.docs-doc-id-index [class*='docItemContainer'], +html.docs-doc-id-index main[class*='docMainContainer'] article, +html.docs-doc-id-index .theme-doc-markdown { + width: 100%; + max-width: none; } -/* 企业价值卡片样式 */ .enterprise-value-card { - border: 1px solid var(--ifm-color-gray-200); - border-radius: 12px; - padding: 24px; - transition: all 0.2s ease; - background: var(--ifm-background-color); + border: 1px solid var(--skillhub-card-border); + border-radius: 24px; + padding: 1.5rem; + transition: transform 0.2s ease, box-shadow 0.2s ease, border-color 0.2s ease; + background: rgba(255, 255, 255, 0.76); + box-shadow: var(--skillhub-card-shadow); + backdrop-filter: blur(16px); } .enterprise-value-card:hover { transform: translateY(-4px); - box-shadow: 0 8px 24px rgba(0, 82, 217, 0.12); - border-color: var(--ifm-color-primary-light); -} - -.enterprise-value-card__icon { - font-size: 32px; - margin-bottom: 12px; + border-color: rgba(37, 99, 235, 0.28); + box-shadow: 0 24px 72px rgba(37, 99, 235, 0.14); } .enterprise-value-card__title { - font-size: 18px; - font-weight: 600; - margin-bottom: 8px; - color: var(--ifm-font-color-base); + font-size: 1.2rem; + font-weight: 700; + margin-bottom: 0.75rem; + line-height: 1.25; + letter-spacing: -0.03em; } .enterprise-value-card__description { - font-size: 14px; + font-size: 0.97rem; color: var(--ifm-font-color-secondary); line-height: 1.6; } -/* Hero 区域样式 */ +.enterprise-value-card__eyebrow { + display: inline-flex; + align-items: center; + min-height: 2rem; + padding: 0.25rem 0.75rem; + margin-bottom: 1rem; + border-radius: 999px; + background: rgba(37, 99, 235, 0.1); + color: var(--ifm-color-primary-darker); + font-size: 0.75rem; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.08em; +} + +.enterprise-value-card__list { + display: flex; + flex-wrap: wrap; + gap: 0.6rem; + margin-top: 1rem; +} + +.enterprise-value-card__list span { + padding: 0.35rem 0.7rem; + border-radius: 999px; + background: rgba(15, 23, 42, 0.05); + color: var(--ifm-font-color-secondary); + font-size: 0.8rem; +} + +.enterprise-value-card--featured { + position: relative; + overflow: hidden; +} + +.enterprise-value-card--featured::before { + content: ''; + position: absolute; + inset: 0; + background: radial-gradient(circle at top right, rgba(37, 99, 235, 0.14), transparent 48%); + pointer-events: none; +} + .hero-section { - padding: 80px 0; - text-align: center; - background: linear-gradient(135deg, #F7F8FA 0%, #FFFFFF 100%); + position: relative; + overflow: hidden; + padding: 5.5rem 0 4.5rem; + background: + linear-gradient(180deg, rgba(239, 246, 255, 0.9), rgba(255, 255, 255, 0.96)), + linear-gradient(90deg, var(--skillhub-grid-line) 1px, transparent 1px), + linear-gradient(0deg, var(--skillhub-grid-line) 1px, transparent 1px); + background-size: auto, 48px 48px, 48px 48px; } [data-theme='dark'] .hero-section { - background: linear-gradient(135deg, #1D2129 0%, #272E3B 100%); + background: + linear-gradient(180deg, rgba(2, 6, 23, 0.98), rgba(2, 6, 23, 0.96)), + linear-gradient(90deg, var(--skillhub-grid-line) 1px, transparent 1px), + linear-gradient(0deg, var(--skillhub-grid-line) 1px, transparent 1px); + background-size: auto, 48px 48px, 48px 48px; +} + +.hero-shell { + display: grid; + grid-template-columns: minmax(0, 1.15fr) minmax(280px, 0.85fr); + gap: 2.8rem; + align-items: center; +} + +.hero-content, +.hero-visual { + position: relative; + z-index: 1; +} + +.hero-content { + text-align: left; + padding-top: 1rem; + padding-bottom: 1rem; +} + +.hero-badge { + display: inline-flex; + align-items: center; + min-height: 2.2rem; + padding: 0.35rem 0.9rem; + border-radius: 999px; + margin-bottom: 1.25rem; + border: 1px solid rgba(37, 99, 235, 0.18); + background: rgba(255, 255, 255, 0.72); + color: var(--ifm-color-primary-darker); + font-size: 0.82rem; + font-weight: 700; + letter-spacing: 0.02em; } .hero-section__title { - font-size: 48px; - font-weight: 700; - margin-bottom: 16px; + font-size: clamp(2.7rem, 4.4vw, 4.3rem); + font-weight: 800; + line-height: 1.04; + letter-spacing: -0.06em; + margin-bottom: 1.25rem; + max-width: 14ch; color: var(--ifm-font-color-base); } .hero-section__tagline { - font-size: 20px; + font-size: 1.1rem; color: var(--ifm-font-color-secondary); - margin-bottom: 32px; - max-width: 700px; - margin-left: auto; - margin-right: auto; + margin-bottom: 1.9rem; + max-width: 44rem; + line-height: 1.75; +} + +.hero-section__tagline span { + display: block; } .hero-section__cta { display: flex; - gap: 16px; - justify-content: center; + gap: 0.9rem; + justify-content: flex-start; flex-wrap: wrap; } .btn-primary { - background: var(--ifm-color-primary); - color: white; - padding: 12px 32px; - border-radius: 8px; - font-weight: 500; + background: linear-gradient(135deg, var(--ifm-color-primary), var(--ifm-color-primary-darker)); + color: #fff; + padding: 0.95rem 1.4rem; + border-radius: 999px; + font-weight: 700; text-decoration: none; - transition: all 0.2s ease; + transition: transform 0.2s ease, box-shadow 0.2s ease; display: inline-block; + box-shadow: 0 14px 32px rgba(37, 99, 235, 0.24); } .btn-primary:hover { - background: var(--ifm-color-primary-dark); - color: white; + transform: translateY(-1px); + color: #fff; text-decoration: none; } .btn-secondary { - background: transparent; - color: var(--ifm-color-primary); - padding: 12px 32px; - border-radius: 8px; - font-weight: 500; + background: rgba(255, 255, 255, 0.72); + color: var(--ifm-font-color-base); + padding: 0.95rem 1.4rem; + border-radius: 999px; + font-weight: 700; text-decoration: none; - border: 1px solid var(--ifm-color-primary); - transition: all 0.2s ease; + border: 1px solid rgba(148, 163, 184, 0.2); + transition: transform 0.2s ease, border-color 0.2s ease, background 0.2s ease; display: inline-block; } .btn-secondary:hover { - background: var(--ifm-color-primary); - color: white; + background: rgba(255, 255, 255, 0.92); + color: var(--ifm-font-color-base); text-decoration: none; + transform: translateY(-1px); +} + +.hero-proof { + display: flex; + flex-wrap: wrap; + gap: 0.7rem; + margin-top: 1.7rem; +} + +.hero-proof span { + padding: 0.4rem 0.8rem; + border-radius: 999px; + border: 1px solid rgba(148, 163, 184, 0.18); + background: rgba(255, 255, 255, 0.6); + color: var(--ifm-font-color-secondary); + font-size: 0.82rem; + font-weight: 600; +} + +.hero-visual { + display: flex; + flex-direction: column; + gap: 1.15rem; + justify-content: center; +} + +.hero-logo-card, +.hero-stats, +.story-card, +.coverage-panel, +.quick-start-panel { + border: 1px solid var(--skillhub-card-border); + border-radius: 28px; + background: rgba(255, 255, 255, 0.78); + box-shadow: var(--skillhub-card-shadow); + backdrop-filter: blur(16px); +} + +.hero-logo-card { + display: grid; + gap: 1.1rem; + padding: 1.4rem; + transform: translateY(-0.45rem); +} + +.hero-logo { + width: 100%; + max-width: 15.5rem; + height: auto; + display: block; + margin: 0 auto; +} + +.hero-logo-card__membership { + display: flex; + align-items: center; + gap: 0.8rem; + padding: 0.75rem 0.85rem; + border: 1px solid rgba(15, 23, 42, 0.1); + border-radius: 14px; + background: rgba(255, 255, 255, 0.92); +} + +.hero-logo-card__membership-link { + display: flex; + flex: 1 1 11rem; + min-width: 0; +} + +.hero-logo-card__membership-logo { + display: block; + width: min(100%, 11.75rem); + height: auto; +} + +.hero-logo-card__membership-label { + flex: 0 0 auto; + max-width: 9rem; + color: #0f172a; + font-size: 0.68rem; + font-weight: 800; + letter-spacing: 0.06em; + line-height: 1.3; + text-align: right; + text-transform: uppercase; +} + +.hero-stats { + display: grid; + grid-template-columns: repeat(3, minmax(0, 1fr)); + gap: 1rem; + padding: 1.3rem 1.35rem; +} + +.hero-stat strong { + display: block; + font-size: 1.5rem; + line-height: 1; + letter-spacing: -0.04em; +} + +.hero-stat span { + display: block; + margin-top: 0.5rem; + color: var(--ifm-font-color-secondary); + font-size: 0.87rem; + line-height: 1.5; +} + +.feature-grid { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + gap: 1.2rem; + margin: 2rem 0 0; +} + +html.docs-doc-id-index .feature-grid { + margin-top: 2.25rem; +} + +.story-grid { + display: grid; + grid-template-columns: repeat(3, minmax(0, 1fr)); + gap: 1rem; + margin: 2rem 0 0; +} + +.story-card { + padding: 1.4rem; +} + +.story-card h3 { + margin-bottom: 0.8rem; + font-size: 1.08rem; + line-height: 1.35; +} + +.story-card__body, +.story-card p { + margin: 0; + color: var(--ifm-font-color-secondary); + line-height: 1.7; +} + +.story-card__body span, +.enterprise-value-card__description span { + display: block; +} + +.coverage-panel { + padding: 1.5rem; + margin-top: 2rem; +} + +html.docs-doc-id-index .container { + max-width: 1280px; } -/* 功能特性标签样式 */ .feature-tags { display: flex; flex-wrap: wrap; - gap: 12px; - justify-content: center; - margin-top: 24px; + gap: 0.75rem; + justify-content: flex-start; + margin-top: 0; } .feature-tag { - background: var(--ifm-background-surface-color); - border: 1px solid var(--ifm-color-gray-200); - padding: 8px 16px; - border-radius: 20px; - font-size: 14px; + background: rgba(37, 99, 235, 0.08); + border: 1px solid rgba(37, 99, 235, 0.12); + padding: 0.55rem 0.9rem; + border-radius: 999px; + font-size: 0.85rem; color: var(--ifm-font-color-secondary); + font-weight: 600; +} + +.quick-start-panel { + padding: 1.5rem; + margin-top: 2rem; } -/* 快速开始代码块样式 */ .quick-start-code { - background: var(--ifm-color-gray-800); - color: var(--ifm-color-gray-0); - padding: 16px 24px; - border-radius: 8px; - font-family: monospace; - font-size: 14px; + background: #020617; + color: #e2e8f0; + padding: 1rem 1.2rem; + border-radius: 20px; + font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, Liberation Mono, monospace; + font-size: 0.92rem; overflow-x: auto; text-align: left; - max-width: 800px; - margin: 24px auto; + margin: 0; } -/* 响应式调整 */ -@media (max-width: 768px) { +.quick-start-code code { + background: transparent; + color: inherit; + padding: 0; + border: 0; + border-radius: 0; + font-size: inherit; + font-family: inherit; + box-shadow: none; + white-space: nowrap; +} + +.quick-start-hints { + display: grid; + grid-template-columns: repeat(3, minmax(0, 1fr)); + gap: 1rem; + margin-top: 1rem; +} + +.quick-start-hint { + padding: 1rem 1.1rem; + border-radius: 20px; + background: rgba(15, 23, 42, 0.04); +} + +.quick-start-hint__label { + display: block; + margin-bottom: 0.5rem; + color: var(--ifm-font-color-muted); + font-size: 0.78rem; + text-transform: uppercase; + letter-spacing: 0.08em; +} + +@media (max-width: 1024px) { + .hero-shell { + grid-template-columns: 1fr; + } + .hero-section__title { - font-size: 32px; + max-width: 13ch; + } + + .hero-visual { + max-width: 48rem; + width: 100%; + } + + .hero-content { + padding-top: 0; + } + + .hero-logo-card { + transform: none; + } +} + +@media (max-width: 996px) { + .navbar__inner > .navbar__items { + gap: 0; + } + + .navbar__inner > .navbar__items > .navbar__item { + display: none; + } +} + +[data-theme='dark'] .enterprise-value-card, +[data-theme='dark'] .hero-logo-card, +[data-theme='dark'] .hero-stats, +[data-theme='dark'] .story-card, +[data-theme='dark'] .coverage-panel, +[data-theme='dark'] .quick-start-panel, +[data-theme='dark'] .hero-badge, +[data-theme='dark'] .hero-proof span, +[data-theme='dark'] .btn-secondary { + background: rgba(15, 23, 42, 0.78); +} + +[data-theme='dark'] .enterprise-value-card__list span, +[data-theme='dark'] .quick-start-hint { + background: rgba(148, 163, 184, 0.08); +} + +[data-theme='dark'] .quick-start-code { + background: rgba(2, 6, 23, 0.94); +} + +[data-theme='dark'] .btn-secondary:hover { + background: rgba(15, 23, 42, 0.96); +} + +[data-theme='dark'] .hero-logo-card { + background: rgba(248, 250, 252, 0.94); +} + +@media (max-width: 768px) { + .hero-shell, + .feature-grid, + .story-grid, + .quick-start-hints { + grid-template-columns: 1fr; + } + + .hero-section { + padding: 3.5rem 0 2.75rem; + } + + .hero-section__title { + font-size: clamp(2rem, 8vw, 2.35rem); + max-width: none; } .hero-section__tagline { - font-size: 16px; + font-size: 1rem; + margin-bottom: 1.35rem; + line-height: 1.65; + } + + .hero-content { + text-align: left; + padding-bottom: 0; + } + + .hero-section__cta { + gap: 0.75rem; + } + + .hero-stats { + grid-template-columns: repeat(2, minmax(0, 1fr)); + } + + .hero-stat:last-child { + grid-column: 1 / -1; + } + + .hero-logo { + max-width: 13rem; + } + + .hero-logo-card__membership { + gap: 0.65rem; + } + + .hero-logo-card__membership-label { + max-width: 8rem; + } + + .landing-section { + padding-top: 0.75rem; } } diff --git a/document/src/pages/index.js b/document/src/pages/index.js new file mode 100644 index 00000000..ce611fc1 --- /dev/null +++ b/document/src/pages/index.js @@ -0,0 +1,349 @@ +import React from 'react' +import Layout from '@theme/Layout' +import Link from '@docusaurus/Link' +import Translate, { translate } from '@docusaurus/Translate' +import useDocusaurusContext from '@docusaurus/useDocusaurusContext' +import useBaseUrl from '@docusaurus/useBaseUrl' +import { useLocation } from '@docusaurus/router' + +const aaifLogoUrl = + 'https://cdn.sanity.io/images/4o10fa7h/production/16dd7d8270b673d376cadca831ab3d5ea003bb89-838x203.svg' + +function getLocaleDocsPath(locale) { + return locale === 'zh-CN' ? '/zh-CN/docs' : '/docs' +} + +export default function Home() { + const { siteConfig, i18n } = useDocusaurusContext() + const location = useLocation() + const isChinese = location.pathname.startsWith('/zh-CN') + const locale = isChinese ? 'zh-CN' : i18n.currentLocale + const docsBase = getLocaleDocsPath(locale) + const logoUrl = useBaseUrl('/img/astron-skillhub-logo.svg') + + return ( + +
+
+
+
+
+
+ Self-hosted Registry for Agent Skills +
+

+ + Ship reusable AI skills with governed delivery. + +

+
+ + Astron SkillHub gives teams a polished internal registry for publishing, discovering, + versioning, and operating reusable agent skill packages without the usual AI-generated + design smell. + +
+
+ + Deploy Now + + + Explore Architecture + +
+
+ Semantic versioning + Namespace governance + Security scanning + CLI compatibility +
+
+
+
+ Astron SkillHub +
+ + {translate({ + +
+ AAIF Associate Member +
+
+
+
+
+ 1 + + + Registry for teams, governance, and runtime docs + + +
+
+ 3 + + + Core workflows: publish, discover, review + + +
+
+ 24/7 + + + Suitable for always-on internal skill operations + + +
+
+
+
+
+
+ +
+
+

+ Why Teams Choose SkillHub +

+
+
+
+ Publishing +
+

+ + Versioned delivery without registry chaos + +

+
+ + Semantic versioning, channel tags, and immutable package history make skill publishing + feel predictable for both platform teams and daily contributors. + +
+
+ Semantic versioning + Tags like beta / stable / latest + Download and rollback friendly +
+
+
+
+ Discovery +
+

+ Search that respects permissions +

+
+ + Full-text search and structured filters help users find the right skill quickly while + still honoring namespace visibility and governance boundaries. + +
+
+
+
+ Collaboration +
+

+ Namespaces built for real teams +

+
+ + Organize skills by owner, domain, or department and pair that structure with Owner, + Admin, and Member roles that match enterprise workflows. + +
+
+
+
+ Governance +
+

+ Review, audit, and promote with confidence +

+
+ + Promotion review flows, audit logs, and optional security scanning make it easier to + move skills from local innovation to governed organizational reuse. + +
+
+
+
+
+ +
+
+

+ Built For Mature Delivery +

+
+
+

+ + Less AI-looking chrome, more product-grade clarity + +

+
+ + The public docs experience is tuned for cleaner typography, tighter spacing, stronger + visual hierarchy, and fewer generic gradients so the brand feels deliberate rather than + over-generated. + +
+
+
+

+ + Designed around modern system thinking + +

+
+ + The refreshed layout borrows the discipline of modern component systems such as + shadcn/ui and utility-first design tokens, even though this site remains a Docusaurus + documentation experience. + +
+
+
+

+ + International first, localized by default switch + +

+
+ + English now leads as the default locale for broader reach, while the Chinese translation + remains one click away through the built-in locale switcher. + +
+
+
+
+
+ +
+
+

+ Current Coverage +

+
+
+ Self-hosted + Version Control + Full-text Search + Namespaces + Review Workflow + Semantic Versioning + RBAC Permissions + Audit Logs + Security Scanning + CLI Compatibility +
+
+
+
+ +
+
+

+ Quick Start +

+
+
+ $ curl -fsSL https://raw.githubusercontent.com/iflytek/skillhub/main/scripts/runtime.sh | sh -s -- up +
+
+
+ + Default Admin + + admin / ChangeMe!2026 +
+
+ + Local Web UI + + http://localhost:3000 +
+
+ + Registry API + + http://localhost:8080 +
+
+
+
+
+ +
+
+

+ Next Steps +

+
    +
  • + + Quick Start + + {' - '} + Deploy SkillHub with one command +
    • +
  • + + Overview + + {' - '} + Learn how the platform is positioned +
    • +
  • + + Publish Workflow + + {' - '} + Publish your first skill package +
    • +
  • + + Single Machine Deployment + + {' - '} + Run the production-ready stack +
    • +
+
+
+
+ + ) +} diff --git a/document/static/CNAME b/document/static/CNAME new file mode 100644 index 00000000..77d0b494 --- /dev/null +++ b/document/static/CNAME @@ -0,0 +1 @@ +www.astron-skillhub.org diff --git a/document/static/img/astron-skillhub-logo.svg b/document/static/img/astron-skillhub-logo.svg new file mode 100644 index 00000000..f0a75a4b --- /dev/null +++ b/document/static/img/astron-skillhub-logo.svg @@ -0,0 +1,32 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + S + + Astron SkillHub +