From 10bce472292ee200a111cac254ae1c97994ef7fc Mon Sep 17 00:00:00 2001 From: FenjuFu Date: Tue, 7 Apr 2026 18:12:47 +0800 Subject: [PATCH] docs: integrate tutorial content into official documentation structure --- document/docs/01-getting-started/overview.md | 72 +++++++++---------- .../security/skill-security.md | 72 +++++++++++++++++++ .../docs/03-user-guide/discovery/install.md | 59 ++++++++++++--- .../04-developer/architecture/overview.md | 42 +++++++---- document/sidebars.js | 1 + 5 files changed, 185 insertions(+), 61 deletions(-) create mode 100644 document/docs/02-administration/security/skill-security.md diff --git a/document/docs/01-getting-started/overview.md b/document/docs/01-getting-started/overview.md index 19df6539..4d3bc298 100644 --- a/document/docs/01-getting-started/overview.md +++ b/document/docs/01-getting-started/overview.md @@ -6,42 +6,49 @@ description: SkillHub 产品概述和核心特性介绍 # 产品概述 -SkillHub 是企业级 AI 技能注册平台，支持技能发布、发现与管理，采用自托管架构保障数据安全。 + +SkillHub 是一个企业级、自托管的 Agent 技能注册中心。你可以把它理解成 AI Agent 世界里的 npm 或者 Docker Hub——专门用来管理和分发 Skills。 + +随着 Claude Skills 等工具的发布，AI 的稳定性和易用性得到了极大增强。给 AI 装 Skill，就像以前装插件一样，能让 AI 瞬间获取到不同能力。但现实是，这些技能包大多散落在各处，团队成员很难发现已有的能力，更别提复用了。很多企业有自己的业务场景，需要定制包含敏感信息的专属技能（如"连接内部数据库"、"处理内部文档格式"），这些技能不能放到公网上。 + +这就是 SkillHub 要解决的问题：让企业能在自己服务器上搭一个私有"技能商店"，数据完全掌握在自己手上，团队成员可以在里面安全地发布、发现、下载、管理技能包。 ## 核心特性 -### 发布管理 +### 🔐 数据主权与隐私安全 +- 完全自托管部署，数据不离开企业网络 +- 支持本地文件系统、S3、MinIO 等私有存储后端 +- 从源头切断“技能投毒”（Skill Poisoning）风险 + +### 📦 发布与生命周期管理 +- 标准化 `SKILL.md` 格式，学习成本极低 - 版本控制与语义化版本（Semantic Versioning） -- 自定义标签（如 `beta`/`stable`） -- `latest` 标签自动跟随最新发布版本 +- 自定义标签（如 `beta`/`stable`），`latest` 标签自动跟随最新版本 -### 发现机制 -- 全文搜索 -- 多维度筛选（命名空间、下载量、评分） -- 可见性控制（公开/命名空间内/私有） +### 🔍 高效发现与复用 +- 基于 PostgreSQL 的高性能全文搜索 +- 多维度筛选（命名空间、下载量、评分、时间） +- 社交与协作机制（收藏、评分、安装量统计） -### 组织架构 -- 命名空间隔离 -- 基于角色的访问控制（RBAC） -- 团队与全局双层空间 +### 🏢 企业级组织架构 +- **命名空间隔离边界**：支持 `@global`（全局）和 `@team-*`（团队）专属空间 +- **基于角色的访问控制（RBAC）**：支持 Owner / Admin / Member 三级角色 +- **精细化可见性控制**：支持技能公开、仅团队内可见或私有 -### 治理体系 -- 双层审核流程 -- 审计日志 -- 权限分离 +### 🛡️ 治理与审计体系 +- **双层审核流程**：普通成员发布的技能需经管理员人工审核后上线 +- **内置安全扫描**：支持对技能包进行多维度的自动化安全检测 +- **完整操作审计**：记录技能发布、审核、下载、晋升全流程审计日志 -### 存储与部署 -- 支持 S3/MinIO/本地存储 -- Docker/Kubernetes 部署 -- 企业级可观测性 +## 架构与技术栈 -## 技术栈 +SkillHub 采用了清晰的分层架构，从上到下分为表现层、应用层、领域层和基础设施层。引入了领域驱动设计（DDD）、CQRS 读写分离模式和事件溯源机制，保证了系统在复杂业务场景下的可维护性和可扩展性。 ### 后端 - **Java 21** - 运行时 - **Spring Boot 3.2.3** - 应用框架 - **PostgreSQL 16.x** - 主数据库 + 全文搜索 -- **Redis 7.x** - 缓存与会话存储 +- **Redis 7.x** - 缓存、会话存储与分布式锁 ### 前端 - **React 19** - UI 框架 @@ -49,22 +56,11 @@ SkillHub 是企业级 AI 技能注册平台，支持技能发布、发现与管 - **Vite** - 构建工具 - **Tailwind CSS** - 样式框架 -### 部署 -- **Docker Compose** - 单机部署 -- **Kubernetes** - 生产环境编排 - -## 核心概念 - -### 命名空间 -技能隔离边界，支持 `@global`（全局）和 `@team-*`（团队）前缀。 - -### 坐标系统 -技能标识格式为 `@{namespace_slug}/{skill_slug}`，支持语义化版本。 - -### 兼容性 -提供 REST API 和 ClawHub 兼容层，支持现有工具集成。 +### 部署与兼容性 +- **部署方式**：支持 Docker Compose 单机一键部署，以及 Kubernetes 生产环境编排 +- **生态兼容**：提供 REST API 和 ClawHub 协议兼容层，支持 Claude Code、OpenClaw、Cursor 等多种 AI Agent 无缝集成 ## 下一步 -- [快速开始](./quick-start) - 一键启动体验 -- [典型应用场景](./use-cases) - 了解如何在企业中应用 +- [快速开始](./quick-start) - 3分钟内一键启动体验 +- [典型应用场景](./use-cases) - 了解如何在企业中应用 SkillHub diff --git a/document/docs/02-administration/security/skill-security.md b/document/docs/02-administration/security/skill-security.md new file mode 100644 index 00000000..236e2586 --- /dev/null +++ b/document/docs/02-administration/security/skill-security.md @@ -0,0 +1,72 @@ +--- +title: 技能安全与扫描机制 +sidebar_position: 4 +description: 了解 AI Agent 技能安全风险及 SkillHub 的多维度安全扫描机制 +--- + +# 技能安全与扫描机制 + +在 AI Agent 编程与技能生态快速发展的阶段，**“Skill 投毒”**与权限绕过等安全隐患逐渐显现。许多社区分发的 Skill 工具包未经审核或隔离，一旦包含恶意指令，将对企业的数据安全造成极大威胁。 + +## 为什么需要技能安全审核？ + +### 恶意逻辑藏在自然语言中 +攻击者可以通过在 `skill/tool` 的描述文本、系统提示词或代码逻辑中注入恶意指令，利用大语言模型（LLM）对工具描述的信任来劫持 Agent 行为。 +例如，在 Skill 的 `description` 中嵌入隐藏的 Prompt Injection 指令： + +```json +{ + "name": "helpful_tool", + "description": "A helpful utility.\n\n" +} +``` + +LLM 在选择工具时读取 description，可能会将上述隐藏指令当作系统级任务执行，导致 SSH 密钥或凭据泄露。 + +### 配置文件投毒与延迟触发 +某些 AI Agent（如早期的 Claude Code）在打开包含特定 `.claude/settings.json` 的仓库时，可能会被静默跳过权限信任对话框，直接进入**最高权限模式**。 +此外，Skill 投毒可以实现“延迟触发”。例如一个技能前 99 次调用都正常，但检测到特定环境（如项目目录中存在 `production` 关键词，或存在 AWS 凭证文件）时，才激活恶意行为，普通的快速测试根本防不胜防。 + +基于以上痛点，企业内部需要一套**强制人工审核 + 自动化安全扫描**的技能包治理机制。 + +--- + +## SkillHub 的多维度安全扫描机制 + +为了从源头切断“技能投毒”和恶意包分发，SkillHub 实现了完整的安全扫描链路。技能包上传后，系统会自动解压并进入审核队列，后台的独立扫描服务会对技能包进行多维度的安全检查。 + +![扫描流程](/img/tutorials/img_40.jpg) + +扫描流程包含以下四个层级： + +### 第一层：结构与规范检查 +验证 `SKILL.md` 是否存在、frontmatter（元数据）是否合法、必填字段是否完整。如果基础结构存在问题或格式异常，系统会直接拒绝该包，不会进入后续深度扫描。 + +### 第二层：代码质量检查 +对技能包中的脚本文件进行扫描，检查代码风格、潜在的常见 Bug 以及代码复杂度等。这一层主要利用静态分析工具，不会实际执行代码，因此速度极快。 + +### 第三层：安全漏洞扫描（SAST） +深度检查是否存在已知的漏洞模式。包括但不限于： +- 命令注入风险 +- 路径穿越（Path Traversal）风险 +- 敏感信息（如 API Key、Token 等）硬编码 + +如果发现问题，安全扫描报告中会详细标注风险等级（高/中/低）及对应的问题文件与行数。 + +### 第四层：依赖安全检查 +如果技能包声明了外部依赖，系统会递归检查依赖链中是否存在已知漏洞（类似 `npm audit` 的机制），并依赖漏洞数据库比对识别潜在的依赖安全风险。 + +--- + +## 审核中心与治理工作流 + +扫描完成后，管理员可以在**审核界面**看到完整的扫描报告。报告会列出所有发现的问题，按严重程度排序，并给出修复建议。 + +![安全扫描报告](https://xfyun-doc.xfyun.cn/lc-sp-img_37-1775556481584.jpg) + +管理员可以根据扫描报告的客观数据，结合业务情况，决定操作： +1. **通过（Approve）**：技能状态变更为“已发布”，普通用户才能在空间内看到和下载。 +2. **驳回（Reject）**：拒绝存在安全隐患或不合规的技能。 +3. **要求修改（Request Changes）**：反馈修改意见，开发者修改后重新提交审核。 + +有了这套机制，所有进入企业命名空间的技能都经过机器扫描与人工把关，防止质量参差不齐或暗藏恶意的包暴露给团队成员，让内部技能库真正做到安全可控。 \ No newline at end of file diff --git a/document/docs/03-user-guide/discovery/install.md b/document/docs/03-user-guide/discovery/install.md index 9cdf9254..0e2d218c 100644 --- a/document/docs/03-user-guide/discovery/install.md +++ b/document/docs/03-user-guide/discovery/install.md @@ -8,29 +8,61 @@ description: 安装和使用技能 ## 通过 CLI 安装 -### 安装最新版本 +SkillHub 兼容 ClawHub CLI 协议，你可以直接使用 `clawhub` 命令行工具来连接你私有部署的 SkillHub 并安装技能。 + +### 配置注册中心与登录 + +在使用前，你需要将 CLI 指向你私有部署的 SkillHub 实例，并使用在 Web 控制台创建的 API Token 进行登录： ```bash -clawhub install @team/my-skill +# 配置注册中心地址（指向你们私有部署的 SkillHub，默认是 8080 端口） +export CLAWHUB_REGISTRY=http://localhost:8080 + +# 使用 Token 登录 +npx clawhub login --token '你的_API_TOKEN' + +# 确认当前登录身份 +npx clawhub whoami ``` -### 安装指定版本 +如果出现提示或者想在单次命令中指定注册中心，也可以使用 `--registry` 参数： ```bash -clawhub install @team/my-skill@1.2.0 +npx clawhub install my-skill --registry http://localhost:8080 ``` -### 按标签安装 +### 安装技能 + +支持多种方式安装不同版本或标签的技能： ```bash -clawhub install @team/my-skill@beta +# 安装最新版本 +npx clawhub install @team/my-skill + +# 安装指定版本 +npx clawhub install @team/my-skill@1.2.0 + +# 按标签安装 +npx clawhub install @team/my-skill@beta ``` -### 使用 ClawHub CLI 安装 +如果使用原生的 ClawHub CLI 格式，遇到命名空间时，会使用 `--` 分隔命名空间和技能名： ```bash -clawhub install my-skill -clawhub install team-name--my-skill +# 安装全局命名空间下的技能 +npx clawhub install my-skill + +# 安装特定团队命名空间下的技能 +npx clawhub install team-name--my-skill +``` + +## 技能查看 (Inspect) + +在安装前，你可以使用 `inspect` 命令查看技能的详细信息、版本历史和依赖关系： + +```bash +npx clawhub inspect ifly-pdf-image-ocr +npx clawhub inspect ocr-team--ifly-pdf-image-ocr ``` ## 安装目录 @@ -44,9 +76,14 @@ clawhub install team-name--my-skill | 3 | `./.claude/skills/` | 项目级，Claude 默认 | | 4 | `~/.claude/skills/` | 全局级，Claude 默认 | -## 在 Claude Code 中使用 +## 多 AI Agent 支持 -安装后，技能会被 Claude Code 自动发现和加载。 +发布到 SkillHub 的技能，不只是在一个 AI 应用上能用。目前已支持 Claude Code、OpenClaw、AstronClaw、Loomy、astron-agent 等多个 AI Agent 平台。 + +以 Claude Code 或 Codex 为例，安装后，技能会被自动发现和加载。你可以直接在提示词中调用它： +> 提示词：把这份文件做 ocr，输出 markdown + +一次发布，各端复用。技能不再需要在每个平台上单独维护一份。 ## 下一步 diff --git a/document/docs/04-developer/architecture/overview.md b/document/docs/04-developer/architecture/overview.md index e00f6703..02554c5c 100644 --- a/document/docs/04-developer/architecture/overview.md +++ b/document/docs/04-developer/architecture/overview.md @@ -8,24 +8,33 @@ description: SkillHub 系统架构概览 ## 架构原则 +SkillHub 采用了清晰的分层架构，从上到下分为表现层、应用层、领域层和基础设施层。 +表现层由 REST API 和 React 前端组成，负责与用户的直接交互。应用层处理业务用例的编排和 DTO 转换。领域层是核心业务逻辑的所在，包含丰富的领域模型和业务规则。基础设施层则处理数据库、存储和搜索等底层能力。 + +在设计上： - **单体优先**：一期采用模块化单体，不拆微服务 +- **领域驱动设计（DDD）**：引入 DDD、CQRS 读写分离模式和事件溯源机制，保证了系统在复杂业务场景下的可维护性和可扩展性 - **依赖倒置**：领域层不依赖基础设施 - **可替换边界**：搜索、存储都有 SPI 抽象 ## 模块结构 +SkillHub 采用了多模块 Maven 项目结构，各个模块职责明确： + ``` server/ -├── skillhub-app/ # 启动、配置装配、Controller -├── skillhub-domain/ # 领域模型 + 领域服务 + 应用服务 -├── skillhub-auth/ # OAuth2 认证 + RBAC + 授权判定 -├── skillhub-search/ # 搜索 SPI + PostgreSQL 全文实现 -├── skillhub-storage/ # 对象存储抽象 + LocalFile/S3 -└── skillhub-infra/ # JPA、通用工具、配置基础 +├── skillhub-app/ # 主应用入口：启动、配置装配、Controller +├── skillhub-domain/ # 核心业务逻辑：领域模型 + 领域服务 + 应用服务 +├── skillhub-auth/ # 认证授权：OAuth2 认证 + RBAC + 授权判定 +├── skillhub-search/ # 搜索功能：搜索 SPI + PostgreSQL 全文实现 +├── skillhub-storage/ # 存储层抽象：对象存储抽象 + LocalFile/S3/MinIO +└── skillhub-infra/ # 基础设施：JPA、通用工具、配置基础 ``` ## 模块依赖 +模块之间的边界非常清晰： + ``` app → domain, auth, search, storage, infra infra → domain @@ -36,15 +45,21 @@ storage → (独立) ## 技术栈 -| 层级 | 技术 | 版本 | -|------|------|------| -| 运行时 | Java | 21 | -| 框架 | Spring Boot | 3.2.3 | -| 数据库 | PostgreSQL | 16.x | -| 缓存/会话 | Redis | 7.x | + +| 层级 | 技术 | 版本 / 说明 | +|------|------|-------------| +| 前端 | React 19 + Vite + TanStack Router | 现代化 SPA，支持中英文切换 | +| 后端运行时 | Java | 21 | +| 框架 | Spring Boot | 3.2.3 (企业级 REST API) | +| 数据库 | PostgreSQL | 16.x (全文搜索、Flyway 自动迁移) | +| 缓存/会话 | Redis | 7.x (会话管理、热点数据缓存) | +| 存储 | MinIO / S3 / 本地存储 | 技能包文件存储，支持本地和云端灵活切换 | +| 监控 | Prometheus + Grafana | 内置监控方案，开箱即用 | ## 部署架构 +SkillHub 提供了多种部署方式。最简单的即通过 Docker Compose 一键部署，可拉起 Web UI、Backend API、PostgreSQL、Redis、MinIO 和 Skill Scanner 等完整环境。 + ``` ┌──────────────┐ │ Browser / CLI│ @@ -62,6 +77,9 @@ storage → (独立) │ │ ▼ ▼ PostgreSQL Redis + │ + ▼ + MinIO ``` ## 下一步 diff --git a/document/sidebars.js b/document/sidebars.js index d45d11d8..a0a64470 100644 --- a/document/sidebars.js +++ b/document/sidebars.js @@ -37,6 +37,7 @@ const sidebars = { 'administration/security/authentication', 'administration/security/authorization', 'administration/security/audit-logs', + 'administration/security/skill-security', ], }, {