AI教程

自行托管 Skillbox：为 AI 代理构建版本化技能库

了解如何使用 Docker 部署 Skillbox，创建版本化技能和受限范围的客户端连接，使用其 CLI 与 MCP 接口，配置可选的 Jev 推荐功能，并保护或迁移你的数据。

AI我搜编辑部2026年9月18日阅读约 14 分钟

什么是 Skillbox？

Skillbox 是一个采用 MIT 许可证、可自行托管的 AI 代理技能库。它为你提供一个集中位置，用于创建、导入、版本管理、分发和审计可复用的技能包。该应用使用 React、Bun、Hono 和 PostgreSQL 构建。

新安装会刻意保持为空。它不包含个人技能、用户账户、客户端密钥、外部服务端点或付费 AI 提供商凭据。Skillbox 负责分发技能内容，但绝不会执行上传的技能代码。

主要功能

版本化编辑：编辑 Markdown 和相关文件，支持不可变修订、冲突检测与恢复。
作用域访问：创建包含技能或技能包授权的配置文件，并分别设置创建、更新、归档和提案权限。
可撤销客户端：签发独立的客户端密钥、查看使用情况，并在必要时撤销后续访问权限。
MCP 和 CLI 访问：直接使用 HTTP MCP，通过 Node 或 Bun stdio 桥接器连接，或在校验和验证后下载软件包。
MCP 资源：通过基础 MCP 资源列表和读取功能，公开已授权且兼容的技能。
可选推荐功能：使用你自己的 Vercel AI Gateway 或 TypeSafe AI 密钥配置 Jev。
数据可移植性：导入和导出原生文件夹、创建受保护的备份，并明确恢复数据。
自行托管部署：使用 Docker Compose 运行，可选在前端配置 Caddy 以提供 HTTPS，或准备 Umbrel 软件包。

Skillbox 设计为由单一所有者管理、使用作用域客户端的自行托管应用。它不是面向公众的多租户 SaaS 平台。

前置条件

推荐的安装方式需要 Docker Engine 或带 Compose v2 的 Docker Desktop，以及 Linux、macOS 或 WSL 上的 Bash。对于基于 Docker 的设置，你无需在主机上安装 Bun 或 Node.js。

安装并启动 Skillbox

克隆仓库并进入其目录：

git clone https://github.com/kitze/skillbox.git
cd skillbox

生成本地环境文件：
```
bash scripts/skillbox.sh setup
```
此命令会创建包含唯一随机凭据的 .env，将其权限设置为 0600，并拒绝覆盖现有文件。
启动 Docker 服务：
```
bash scripts/skillbox.sh start
```
在浏览器中打开 http://127.0.0.1:4791。
从本地 .env 文件中读取 SKILLBOX_ADMIN_TOKEN，并使用它登录。设置脚本不会打印此令牌。

请妥善保管 .env。所有者令牌控制管理访问权限，同时也参与保护已存储的集成凭据。

远程部署

对于远程安装，请将 SKILLBOX_ORIGIN 设置为部署的 HTTPS 源站，并配置 TLS 反向代理。请勿通过未加密的 HTTP 暴露生产实例。有关受支持的部署详情，请参阅仓库中的部署说明。

不使用仅限 Docker 的应用设置进行本地开发

如果你已经拥有 Bun 和 PostgreSQL 16 或更高版本的数据库，可以直接安装依赖并启动应用：

bun install --frozen-lockfile
# Set DATABASE_URL
# Set SKILLBOX_ADMIN_TOKEN to at least 32 random characters
# Set SKILLBOX_ORIGIN=http://127.0.0.1:4791
bun run build
bun run start

请将这三个必需值存储在受保护的环境中，而不要将它们提交到源代码管理系统。

创建技能和作用域客户端

登录后，在编辑器中创建技能，或导入现有技能包。技能修订不可变，因此客户端可以加载或获取特定修订，而不必依赖会变化的内容。

接下来，创建一个配置文件，并授予它访问所需技能或技能包的权限。根据客户端用途，分别分配创建、更新、归档和提案权限。最后，使用该配置文件创建客户端连接。

客户端密钥仅显示一次，Skillbox 只存储其哈希值。请立即将每个密钥保存到受保护的客户端配置中。为每个客户端使用独立密钥，不要分发所有者令牌。

配置 CLI

CLI 读取一个包含 Skillbox URL 和客户端密钥的 JSON 配置。默认路径为 ~/.config/skillbox/config.json。

{
  "url": "https://skills.example.com",
  "token": "YOUR_CLIENT_KEY"
}

请将文件权限设置为 0600。环境变量 SKILLBOX_URL 和 SKILLBOX_TOKEN 会覆盖配置文件中的值。如果未配置 URL，CLI 会安全地指向 localhost，而不是其他人的服务。

请将 cli/skillbox.mjs 和 cli/package.mjs 放在一起。然后，你可以探索并获取已授权的技能：

node cli/skillbox.mjs list
node cli/skillbox.mjs search "database migration"
node cli/skillbox.mjs load my-skill
node cli/skillbox.mjs manifest my-skill
node cli/skillbox.mjs fetch my-skill@REVISION

fetch 操作会在写入文件前验证路径、文件哈希、大小、可执行标志和软件包校验和。它不会执行代码或安装依赖。

发布更新后的技能

提供技能 ID 和预期要更新的修订版本，即可发布本地文件夹：

node cli/skillbox.mjs publish ./my-skill my-skill EXPECTED_REVISION

预期的修订支持冲突检测。发布还取决于授予客户端配置文件的权限。

审计兼容性

所有者可以运行不会修改数据的兼容性审计：

node cli/skillbox.mjs audit

当发现不兼容的软件包时，该命令会以状态码 1 退出。它帮助你在不重写现有软件包的情况下评估 MCP Skills 的兼容性。

通过 MCP 连接 AI 代理

将 bootstrap/SKILL.md 安装为代理的 skills-library 引导文件。支持 HTTP MCP 的客户端可以连接到实例的 /mcp 端点，并将客户端密钥作为 bearer 令牌发送：

Authorization: Bearer YOUR_CLIENT_KEY

对于需要 stdio 的 MCP 客户端，请配置随附的桥接程序：

{
  "mcpServers": {
    "skillbox": {
      "command": "node",
      "args": [
        "/absolute/path/to/skillbox/cli/skillbox.mjs",
        "mcp"
      ],
      "env": {
        "SKILLBOX_URL": "https://skills.example.com",
        "SKILLBOX_CONFIG": "/absolute/path/to/protected-client-config.json"
      }
    }
  }
}

基础 MCP 工具包括 search_skills、recommend_skills、load_skill、read_skill_file 和 report_skill_use。只有在客户端配置文件授予相应权限时，才会公开写入和提案工具。

Skillbox 还通过基础 MCP 的 resources/list 和 resources/read，公开经授权的兼容技能。支持的二进制文件和大文件可以作为资源访问，但读取资源不会激活或执行技能。

目前尚未宣称完整支持 io.modelcontextprotocol/skills。当前实现通过基础 MCP 协议提供就绪功能，而原生发现和协商仍取决于 SDK 和协议升级。

正确使用搜索和推荐

在任务开始时，代理仍应调用 search_skills，以盘点相关的经授权技能。推荐是补充功能，不会取代此搜索步骤。在应用选定的技能之前，请使用 Skillbox 返回的不可变修订版本加载该技能。

没有外部推荐提供商时，可以从 CLI 搜索：

node cli/skillbox.mjs search "database migration"

若要请求了解任务上下文的推荐：

node cli/skillbox.mjs recommend "Fix choppy scrolling in an Expo app"

对应的 MCP 操作是 recommend_skills({task, limit?, offset?})。HTTP 客户端可以向 POST /api/skill-recommendations 发送相同的已认证 JSON 请求体。

配置可选的 Jev 推荐

打开 设置 → Jev 推荐。
选择默认的 Vercel AI Gateway，或选择 TypeSafe AI。
输入并保存所选提供商的专属 API 密钥。

提供商密钥会分别存储。选择 TypeSafe 不会将已保存的 Gateway 密钥发送给 TypeSafe，切换提供商也会保留之前保存的密钥。删除所选提供商的密钥会禁用该提供商的模型调用。

密钥使用从 SKILLBOX_ADMIN_TOKEN 派生的密钥材料，通过 AES-256-GCM 在 PostgreSQL 中加密。它不会由设置 API 返回，也不会包含在浏览器包中。未按照文档规定的轮换流程更改所有者令牌，会导致存储的集成凭据无法读取。

保存密钥不会验证提供商访问权限或购买额度。Jev 会将任务文本和经授权的活跃技能描述发送给所选提供商，因此适用该提供商的计费和数据处理条款。

了解推荐结果和回退机制

Jev 会评估完整的、已授权、已启用且未归档的叶子目录，最多 200 个叶子或 120,000 个序列化字符。目录更大时会明确执行回退，而不会对未公开的子集进行排名。

相关性是 0 到 4 之间未经校准的分数，并非概率。
得分至少为 3 的结果会按分数降序排列，分数相同时按 ID 排列。
noMatch=true 表示没有评估候选项达到阈值。
缺少密钥、提供商错误、响应格式错误、速率限制、容量限制或八秒截止时间，都会触发 PostgreSQL 搜索回退。
回退结果使用 method=search、relevance=null 和 fallbackReason。

进程本地缓存最多保存 128 个条目，缓存期限为五分钟。Skillbox 允许两个并发评估，并将每个作用域每分钟未缓存请求数限制为十个，且不会自动重试。权限授予、生命周期状态和修订版本会在模型调用前后进行检查，包括缓存命中时。

导入、导出和备份数据

如果已安装 Bun，可以使用以下命令导入技能文件夹：

bun scripts/import.ts /path/to/skills

导入会保留文件字节和未知的 frontmatter，跳过符号链接和运行时产物，并隔离可识别的机密模式。此检测基于启发式规则，因此不能替代完整的机密审计。切勿将密码或令牌放入技能包中。

将技能内容导出到空目标目录：

SKILLBOX_EXPORT_DIR=/path/to/empty-export bun scripts/export.ts

PostgreSQL 数据库仍是真实数据源。编辑导出的文件夹不会更改数据库，除非再次发布这些内容。

使用以下命令创建受保护的备份：

bash scripts/backup.sh

导出文件和备份可能包含私有技能内容。请将它们与公开的应用程序源代码分开存放。可选的 GitHub 导出脚本要求明确配置专用的私有导出检出目录，并且不会自动启用。

高级运维技巧

每个集成使用一个客户端密钥

分开使用密钥可以让撤销和使用情况报告更有价值。撤销密钥会阻止后续请求，但无法收回客户端已经下载的文件。

优先使用范围明确的配置文件

只向每个代理授予其所需的技能和操作权限。技能包会展开为去重后的当前叶子技能，而仅有引用并不会授予访问权限。

保护所有者令牌和备份

所有者令牌提供管理权限，并为保存的集成凭据派生加密材料。请将它与数据库和配置备份一同妥善保护，并在替换令牌前按照文档中的轮换流程操作。

将技能视为内容，而不是受信任的程序

Skillbox 会验证和分发包文件，但不会执行这些文件。在代理工作流中使用下载的说明和代码前，仍应继续进行审查。

谨慎对待基准测试建议

开发者可以使用自己的提供商密钥运行可选的计费基准测试：

bun scripts/benchmark-recommendations.ts --live --provider vercel
bun scripts/benchmark-recommendations.ts --live --provider typesafe

Vercel 使用 AI_GATEWAY_API_KEY，TypeSafe 使用 TYPESAFE_API_KEY 或 JEV_KEY。此脚本不会配置应用程序或保存凭据。其合成样本不代表生产环境中的延迟保证或概率校准结果。

验证部署或贡献

部署更改前，请运行类型检查和隔离测试套件：

bun run typecheck
bash scripts/test-isolated.sh

隔离测试套件会创建并移除自己的 Docker Compose PostgreSQL 实例，且不会发布数据库端口。它涵盖授权、修订版本、API 和 MCP 行为、CLI、加密设置以及推荐功能。切勿让数据库测试连接到生产环境。

结语

Skillbox 提供了一套受控的自托管工作流，用于管理可复用的 AI 代理技能。请从 Docker 设置开始，创建带版本的技能，分配范围明确的配置文件，并为每个代理连接专属的客户端密钥。随后，你可以在保留目录和凭据所有权的同时，添加 MCP 访问、可选的 Jev 推荐、可移植性工作流和备份。