内容
# 技能仓库服务（Skillberry-store 服务）
<p>
<a href="https://skillberry-ai.github.io/skillberry-store/"><img src="https://img.shields.io/badge/site-live-0066CC" alt="网站"></a>
<a href="https://github.com/skillberry-ai/skillberry-store/actions/workflows/push.yml"><img src="https://github.com/skillberry-ai/skillberry-store/actions/workflows/push.yml/badge.svg?branch=main" alt="CI"></a>
<a href="https://github.com/skillberry-ai/skillberry-store/stargazers"><img src="https://img.shields.io/github/stars/skillberry-ai/skillberry-store?style=flat&label=stars&color=0066CC" alt="GitHub stars"></a>
<img src="https://img.shields.io/badge/status-beta%20(0.x)-orange" alt="状态">
<img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python">
<img src="https://img.shields.io/badge/license-Apache--2.0-informational" alt="许可证">
<a href="docs/plugins-installation.md"><img src="https://img.shields.io/badge/plugins-16-0066CC" alt="插件"></a>
</p>
该服务实现了用于代理工作流的智能技能仓库。管理和执行技能、工具和代码片段，提供强大的搜索和生命周期管理。
▶ [观看完整的高亮视频](https://github.com/user-attachments/assets/eab2f9f1-1196-4858-b4ca-72d6c664d9f3)
## 功能 ✨
- **管理工具用于代理工作负载**：添加（持久化）、删除、更新和删除工具。
- **工具执行**：使用 Docker（沙箱）调用工具（带有参数）。
- **工具搜索和列表**：使用语义和经典搜索筛选工具。
- **工具生命周期管理**：提供工具生命周期管理（状态、可见性等）。
- **工具持久化**：支持工具持久化到文件系统、GitHub 仓库等。
- **命名空间**：使用命名空间组织和标记技能、工具和代码片段，以便更好地分类和筛选。
- **可观察性**：提供工具使用操作的指标和跟踪。
- **OpenAPI 前端**：FastAPI 端点，用于交互和管理工具（使用工具清单工件）
- **CLI 支持**：所有 API 操作的命令行界面。
- **MCP 前端**：为工具子集或所有工具暴露虚拟 MCP 服务器。
- **NFS/WebDAV 前端**：通过 WebDAV 或 NFSv3 将技能暴露为可挂载的文件系统。
- **支持多个 MCP 后端**：从多个后端 MCP 服务器消耗和路由附加工具。
- **代理框架集成**：通过 MCP 前端连接到不同的代理框架。
- **MCP 控制 API**：为每个可用的 REST 操作暴露一个 MCP 服务器 API（例如，添加工具、语义搜索等）。
- **插件架构**：用于 AI 驱动的内容生成、评估和优化的可扩展插件系统。参见 [插件安装指南](docs/plugins-installation.md)。
## 快速入门 🚀
### 安装 📦
不带插件安装 Skillberry-store（最小安装）：
```bash
pip install skillberry-store
```
或安装带插件的版本：
```bash
# 所有插件
pip install skillberry-store[plugins-all]
# 仅 Creator 插件（AI 驱动的内容生成）
pip install skillberry-store[plugin-creator]
# 仅 Evaluator 插件（AI 驱动的内容评估）
pip install skillberry-store[plugin-evaluator]
# 仅 Dedupe 插件（AI 驱动的重复技能检测）
pip install skillberry-store[plugin-dedupe]
# 仅 Skill Optimizer 插件（使用 Claude Code 优化现有技能）
pip install skillberry-store[plugin-skill-optimizer]
# 多个特定插件
pip install skillberry-store[plugin-creator,plugin-evaluator,plugin-skill-optimizer]
```
有关详细的插件安装选项和配置，请参见 [插件安装指南](docs/plugins-installation.md)。
### 使用 Docker 或 Podman 运行服务 🐳
```bash
make docker-run
```
> 注意：使用 `make help` 获取完整的选项列表
您可以通过设置 `SBS_BASE_DIR` 控制 SBS 存储其数据（默认为系统临时目录）。
### 与 UI 交互 👨💻
Skillberry Store 现包括一个现代化的 Web UI，会自动与后端启动：
- **Web UI**：[http://localhost:8002](http://localhost:8002) - 现代 React 界面
- **API 文档**：[http://localhost:8000/docs](http://localhost:8000/docs) - OpenAPI/Swagger 界面
Web UI 提供：
- 工具、技能、代码片段、VMCP 服务器和 vNFS 服务器的视觉管理
- 搜索和筛选功能
- 带有参数输入的工具执行
- 代码查看和编辑
- 实时更新
要禁用 UI 并仅运行后端：
```bash
ENABLE_UI=false make run
```
## 先决条件 🛠️
- 您的机器上已安装 Docker 或 Podman。
默认为 `docker`。如果您想使用 `podman`，请在以下一个或多个配置文件中添加以下行，具体取决于您正在使用的 shell：
- `~/.zshrc`
- `~/.bashrc`
- `~/.bash_profile`
- `~/.profile`
本地部署的其他要求：
- 您的用户具有 Docker 权限（即是 `docker` 组的成员）。
- Docker 日志驱动程序设置为 `json-file` 或 `journald`。
> 使用以下命令检查日志驱动程序：
> ```bash
> docker info --format '{{.LoggingDriver}}'
> ```
> 如果响应不是 `json-file` 或 `journald`，请按照 [此处](https://docs.docker.com/engine/logging/configure/#configure-the-default-logging-driver) 的文档配置 Docker 日志记录。
## 在 MacOS 上使用 podman 运行 ⚒️
- 将 `docker` 别名为 `podman`，如 [先决条件](#prerequisites-️) 中所述
- 创建并启动一个 Podman 机器：
```bash
podman machine init --now --cpus=4 --memory=4096 -v /tmp:/tmp podman-machine-default
```
如果您已经有一个名为 `podman-machine-default` 的默认 Podman 机器，则需要先：
```bash
podman machine stop
podman machine rm podman-machine-default
```
然后重新运行 Podman 机器初始化并：
```bash
make docker-run
```
## 设计需求
参见 [DESIGN_REQUIREMENTS.md](DESIGN_REQUIREMENTS.md)
## 本地安装 📦
我们支持 Linux、macOS 和 Windows。
```bash
git clone git@github.com:skillberry-ai/skillberry-store.git
cd skillberry-store
```
在 Linux、macOS 或 WSL 上：
```bash
make install-requirements
```
在 Windows 上（无需 WSL）：
```cmd
pip install -e .
```
## 在本地启动服务（Docker 替代方案） 🚀
在 Linux、macOS 或 WSL 上：
```bash
make run
```
在 Windows 上：
```cmd
sbs-srv
```
*注意：*
* 默认情况下，SBS 在主机 `0.0.0.0` 和端口 `8000` 上运行，并在端口 `8090` 上发布其指标。要更改，请设置环境变量 SBS_PORT/SBS_HOST/PROMETHEUS_METRICS_PORT
* 要完全禁用可观察性，请将环境变量 `OBSERVABILITY` 设置为 `False`
* Web UI 自动在端口 `3000` 上启动。要禁用它，请设置 `ENABLE_UI=false`
* 首次运行时，UI 将自动安装其依赖项（需要 Node.js 18+）
## Web UI 功能 🎨
Skillberry Store 包括一个现代的 React 界面，具有：
- **工具管理**：创建、查看、执行和删除工具，支持文件上传
- **技能管理**：组织工具和代码片段为可重用的技能
- **代码片段管理**：存储和管理带有语法高亮的代码片段
- **VMCP 服务器**：创建和管理虚拟 MCP 服务器，用于工具子集
- **vNFS 服务器**：将技能暴露为可挂载的 WebDAV 或 NFS 文件系统
- **搜索和筛选**：跨所有资源的语义搜索
- **实时更新**：使用 TanStack Query 自动刷新数据
- **响应式设计**：使用 PatternFly（IBM 的设计系统）构建
### UI 技术栈
- React 18 + TypeScript
- Vite（快速开发服务器）
- PatternFly（IBM 设计系统）
- TanStack Query（数据获取）
- React Router（导航）
### UI 开发
单独开发 UI：
```bash
cd src/skillberry_store/ui
npm install
npm run dev
```
UI 源代码位于 `src/skillberry_store/ui/`，包括：
- `src/pages/` - 每个部分的页面组件
- `src/components/` - 可重用的 UI 组件
- `src/services/` - API 客户端层
- `src/types/` - TypeScript 类型定义
## 通过 OpenAPI 与服务交互 📜
在 `http://127.0.0.1:8000/docs` 上打开浏览器。
## 通过 Python 客户端与服务交互 🐍
可以通过 skillberry store 服务 SDK 使用服务。安装和用法请参考 [skillberry-store-sdk](client/python/skillberry_store_sdk/README.md)。
## 通过 CLI 与服务交互 💻
一个提供所有 API 操作命令行访问的 CLI（自动生成）。示例用法：
```bash
# 安装 SDK（包括 CLI）
pip install skillberry-store-sdk
# 使用 CLI
sbs --help # 显示可用命令
sbs connect http://prod:8000 # 连接到不同的服务器
sbs list-skills # 列出所有技能
sbs get-tool convert # 获取特定工具
sbs create-vmcp-server # 创建 VMCP 服务器
sbs search-tools "calculator" # 搜索工具
```
可用命令组：
| 组 | 命令 |
|-------|----------|
| **工具** | `create-tool`, `list-tools`, `get-tool`, `get-tool-module`, `update-tool`, `delete-tool`, `execute-tool`, `search-tools`, `add-tool` |
| **技能** | `create-skill`, `list-skills`, `get-skill`, `update-skill`, `delete-skill`, `search-skills`, `detect-anthropic-skills`, `import-anthropic-skill`, `export-anthropic-skill` |
| **代码片段** | `create-snippet`, `list-snippets`, `get-snippet`, `update-snippet`, `delete-snippet`, `search-snippets` |
| **VMCP 服务器** | `create-vmcp-server`, `list-vmcp-servers`, `get-vmcp-server`, `update-vmcp-server`, `delete-vmcp-server`, `start-vmcp-server`, `search-vmcp-servers` |
| **vNFS 服务器** | `create-vnfs-server`, `list-vnfs-servers`, `get-vnfs-server`, `update-vnfs-server`, `delete-vnfs-server`, `start-vnfs-server`, `search-vnfs-servers` |
| **管理员** | `metrics`, `purge-all`, `health`, `health-ready` |
有关 CLI 文档的详细信息，请参见 [docs/cli.md](docs/cli.md)。
## 通过 MCP 与服务交互 📜
每个控制 API 函数都作为 MCP 工具提供给代理 AI 工作流。要访问，请使用针对 `http://127.0.0.1:8000/control_sse` 的 MCP 客户端。
### 虚拟 MCP 服务器（VMCP）
VMCP 服务器将单个技能的工具和代码片段暴露为独立的 MCP 端点。通过 UI（`虚拟 MCP 服务器` → `创建 VMCP 服务器`）或 REST API 创建：
```bash
curl -X POST "http://localhost:8000/vmcp_servers/?name=my-skill&skill_uuid=<uuid>"
```
将 MCP 客户端连接到 `http://localhost:<assigned-port>/sse`。
### 支持多个 MCP 后端
按照 [连接 MCP 作为后端](docs/mcp-backend.md) 中的步骤操作。
## 虚拟 NFS 服务器（vNFS） 🗂️
vNFS 服务器将单个技能暴露为**可挂载的只读文件系统**，通过 WebDAV 或 NFSv3。这让任何工具 - 包括 Claude Code - 都可以直接通过 `mount` 或 `rclone` 读取技能文件，无需通过 REST API。
通过 UI（`虚拟 NFS 服务器` → `创建 vNFS 服务器`）或 REST API 创建 vNFS 服务器：
```bash
# WebDAV（默认）
curl -X POST "http://localhost:8000/vnfs_servers/?name=my-skill&skill_uuid=<uuid>&protocol=webdav"
# NFSv3
curl -X POST "http://localhost:8000/vnfs_servers/?name=my-skill&skill_uuid=<uuid>&protocol=nfs"
```
### 挂载 - WebDAV
最简单的方法是 `rclone`（无需 root，适用于 Linux、macOS、WSL2）：
```bash
# 安装：brew install rclone / apt install rclone / dnf install rclone
rclone mount :webdav: /mnt/skill \
--webdav-url=http://localhost:<port>/<skill-name> \
--read-only --daemon
# 卸载
fusermount3 -u /mnt/skill
```
或者，使用 `davfs2`:
```bash
# 安装：apt install davfs2 / dnf install davfs2
sudo mount -t davfs http://localhost:<port>/<skill-name> /mnt/skill
# 卸载
sudo umount /mnt/skill
```
### 挂载 - NFSv3
```bash
# 安装：apt install nfs-common / dnf install nfs-utils
sudo mount -t nfs localhost:/ /mnt/skill \
-o port=<port>,mountport=<port>,nfsvers=3,proto=tcp,nolock,soft
# 技能文件位于 /mnt/skill/<skill-name>/
# 卸载
sudo umount /mnt/skill
```
UI `虚拟 NFS 服务器` 详情页显示了带有正确端口和技能名称的精确命令。
## 使用 GitHub 后端运行 SBS
按照 [Github backend](docs/github_using_hooks.md) 中的步骤操作。
## 监控服务 📈
### 启动本地 Prometheus 服务器执行：
```bash
echo -e "global:\n scrape_interval: 5s\nscrape_configs:\n - job_name: \"skillberry-store\"\n static_configs:\n - targets: [\"localhost:8090\"]\n metric_relabel_configs:\n - source_labels: [__name__]\n regex: '.*_created'\n action: drop" > /tmp/prometheus.yml
docker run --rm --name prometheus --network="host" -p 9090:9090 -v /tmp/prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus --config.file=/etc/prometheus/prometheus.yml
```
Prometheus 中的指标：http://localhost:9090。
> 注意：应用程序指标前缀为 `SBS_`。
### 启动本地 Jaeger 服务器执行：
```bash
docker run --rm --name jaeger --network="host" -p 4317:4317 -p 16686:16686 jaegertracing/all-in-one:latest
```
Jaeger 中的跟踪：http://localhost:16686。
## 📚 更多文档可在 [docs](docs) 中找到。
* 自定义配置详情请参见 [此处](docs/config-env-vars.md)
* Guthub 支持详情请参见 [此处](docs/github_using_hooks.md)
