AgentSkillsHub 详细部署教程

AgentSkillsHub 是一个开源的 AI 代理技能目录，它收录并评估了海量的 Claude Skills、MCP 服务器、Codex Skills 和 AI 代理工具。项目通过自动化流程，对每个项目进行质量评分和分类，帮助开发者快速找到合适的工具。

本教程将引导你在本地环境完成从零开始的部署。

1. 准备工作

在开始前，请确保你的开发环境满足以下要求：

要求 版本/说明
操作系统 macOS、Linux 或 Windows (建议使用 WSL2)
Python 3.12 或更高版本
Node.js 18 或更高版本
npm 随 Node.js 安装
Git 用于克隆代码仓库
GitHub 个人访问令牌 需要有访问公开仓库的权限

2. 克隆代码仓库与安装依赖

2.1 克隆项目

打开终端，执行以下命令将项目克隆到本地：

1
2
git clone https://github.com/ZhuYansen/agent-skills-hub.git
cd agent-skills-hub

2.2 配置后端

  1. 进入后端目录并创建 Python 虚拟环境：

    1
    2
    3
    4
    cd backend
    python3.12 -m venv venv
    source venv/bin/activate  # Linux/macOS
    # 或 .\venv\Scripts\activate  # Windows

  2. 安装 Python 依赖：

    1
    pip install -r requirements.txt

  3. 配置环境变量：

    1
    cp .env.example .env

    编辑 .env 文件，至少需要填入你的 GITHUB_TOKEN：

    1
    GITHUB_TOKEN=ghp_你的个人访问令牌

    你可以参考 GitHub 官方文档生成一个具有 repo 和 workflow 权限的令牌。

2.3 配置前端

  1. 打开一个新的终端窗口，进入前端目录：

    1
    cd frontend

  2. 安装 Node.js 依赖：

    1
    npm install

3. 启动服务

3.1 启动后端 API 服务

确保你在 backend 目录且虚拟环境已激活，然后运行：

1
uvicorn app.main:app --reload

后端服务默认会在 http://localhost:8000 启动。你可以访问 http://localhost:8000/api/stats 来验证是否运行成功。

3.2 启动前端开发服务器

在 frontend 目录下，运行：

1
npm run dev

前端服务默认会在 http://localhost:5173 启动（Vite 默认端口）。在浏览器中打开此地址，即可看到 AgentSkillsHub 的界面。

4. 核心功能与数据同步

4.1 手动触发数据同步

项目的数据收集和评分由 GitHub Actions 自动触发。在本地开发时，你可以通过以下方式手动测试同步流程：

  1. 在 backend 目录下，使用 Python 运行调度任务：

    1
    python -m scheduler.jobs

    这将会执行一次完整的数据收集、清洗、评估和存储流程。

  2. 同步后的数据默认会存储在 SQLite 数据库中（如果未配置 SUPABASE_DB_URL），文件位置通常在 backend/app/data/ 目录下。

4.2 使用 SQLite 还是 Supabase？

  • SQLite (默认)：配置简单，适合本地开发和测试。数据会存储在本地文件中。
  • Supabase (PostgreSQL)：生产环境推荐。你需要创建一个 Supabase 项目，并在 .env 文件中配置 SUPABASE_DB_URL。项目中的迁移文件位于 supabase/migrations/，可用于初始化数据库表结构。

5. 环境变量参考

以下是在 .env 文件中可能用到的关键变量：

变量名 是否必须 说明
GITHUB_TOKEN 是 GitHub 个人访问令牌，用于调用 GitHub API。
SUPABASE_DB_URL 否 Supabase PostgreSQL 数据库连接字符串，不设置则使用本地 SQLite。
RESEND_API_KEY 否 Resend 邮件服务 API 密钥，用于发送新闻通讯。
ADMIN_TOKEN 否 用于保护某些管理 API 端点的令牌。
SYNC_INTERVAL_HOURS 否 自动同步间隔，默认为 8 小时。

6. API 端点概览

启动后端后，你可以通过以下 API 获取数据（示例：http://localhost:8000/api/trending）：

方法 路径 描述
GET /api/skills 获取技能列表（支持搜索、过滤、排序）。
GET /api/skills/{id} 获取特定技能的详细信息。
GET /api/trending 获取近期趋势上升的技能。
GET /api/top-rated 获取评分最高的技能。
GET /api/stats 获取目录的统计信息。

完整的 API 文档可在项目文档中找到。

7. 故障排除

问题 可能原因与解决方法
后端启动失败，提示缺少 GITHUB_TOKEN 确保在 backend/.env 文件中正确设置了 GITHUB_TOKEN。
前端页面无法显示数据 1. 确认后端服务 (uvicorn) 正在运行。2. 检查前端是否配置了正确的 API 地址（默认指向 http://localhost:8000）。
数据同步脚本运行报错 检查网络连接，确保能访问 GitHub API。如果遇到速率限制，请等待或使用更高权限的令牌。
依赖安装失败 对于 Python，确保使用了 Python 3.12 和虚拟环境。对于 Node.js，可以尝试删除 node_modules 和 package-lock.json 后重新安装。

8. 总结

AgentSkillsHub 是一个架构清晰、数据驱动的大型项目，它通过自动化流程解决了 AI 工具发现和评估的痛点。在本地部署主要分为后端和前端两部分，通过配置 GitHub 令牌即可启动核心的数据同步和展示功能。

你可以基于这个项目进行二次开发，例如改进评分算法、添加新的数据源，或将其部署为自己的 AI 工具目录服务。

相关资源：