Chuyển đến nội dung chính
Hướng dẫn AI

Tự lưu trữ Skillbox: Xây dựng thư viện kỹ năng có phiên bản cho tác nhân AI

Tìm hiểu cách triển khai Skillbox bằng Docker, tạo các kỹ năng có phiên bản và kết nối máy khách theo phạm vi, sử dụng giao diện CLI và MCP, cấu hình đề xuất Jev tùy chọn, đồng thời bảo vệ hoặc di chuyển dữ liệu của bạn.

Thời gian đọc khoảng 27 phút
Tự lưu trữ Skillbox: Thư viện kỹ năng có phiên bản cho tác nhân AI

Skillbox là gì?

Skillbox là thư viện kỹ năng được cấp phép MIT, tự lưu trữ dành cho các tác nhân AI. Công cụ cung cấp một nơi tập trung để tạo, nhập, quản lý phiên bản, phân phối và kiểm tra các gói kỹ năng có thể tái sử dụng. Ứng dụng được xây dựng với React, Bun, Hono và PostgreSQL.

Một bản cài đặt mới được cố ý để trống. Bản cài đặt không bao gồm kỹ năng cá nhân, tài khoản người dùng, khóa máy khách, endpoint dịch vụ bên ngoài hoặc thông tin xác thực của nhà cung cấp AI trả phí. Skillbox phân phối nội dung kỹ năng nhưng không bao giờ thực thi mã kỹ năng đã tải lên.

Tính năng chính

  • Chỉnh sửa có quản lý phiên bản: Chỉnh sửa Markdown và các tệp hỗ trợ với các bản sửa đổi bất biến, phát hiện xung đột và khôi phục.
  • Quyền truy cập theo phạm vi: Tạo hồ sơ với quyền cấp kỹ năng hoặc gói, cùng các quyền tạo, cập nhật, lưu trữ và đề xuất riêng biệt.
  • Máy khách có thể thu hồi: Cấp khóa riêng cho từng máy khách, xem xét hoạt động sử dụng và thu hồi quyền truy cập trong tương lai khi cần.
  • Truy cập MCP và CLI: Sử dụng MCP HTTP trực tiếp, kết nối qua cầu nối stdio của Node hoặc Bun, hoặc tải xuống các gói với xác minh checksum.
  • Tài nguyên MCP: Cung cấp các kỹ năng tương thích, được cấp quyền thông qua chức năng liệt kê và đọc tài nguyên MCP cơ bản.
  • Đề xuất tùy chọn: Sử dụng Jev với Vercel AI Gateway hoặc khóa TypeSafe AI của riêng bạn.
  • Tính di động dữ liệu: Nhập và xuất các thư mục gốc, tạo bản sao lưu được bảo vệ và khôi phục dữ liệu một cách rõ ràng.
  • Triển khai tự lưu trữ: Chạy bằng Docker Compose, tùy chọn đặt Caddy phía trước để dùng HTTPS hoặc chuẩn bị gói Umbrel.

Skillbox được thiết kế như một ứng dụng tự lưu trữ dành cho một chủ sở hữu duy nhất, với các máy khách có phạm vi quyền hạn. Đây không phải là nền tảng SaaS đa đối tượng công khai.

Điều kiện tiên quyết

Bản cài đặt được khuyến nghị yêu cầu Docker Engine hoặc Docker Desktop với Compose v2, cùng Bash trên Linux, macOS hoặc WSL. Bạn không cần cài Bun hoặc Node.js trên máy chủ cho thiết lập dựa trên Docker.

Cài đặt và khởi động Skillbox

  1. Sao chép repository và truy cập vào thư mục của nó:

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

  2. Tạo tệp môi trường cục bộ:

    bash scripts/skillbox.sh setup

    Lệnh này tạo .env với thông tin xác thực ngẫu nhiên, duy nhất, đặt quyền tệp thành 0600 và từ chối ghi đè tệp hiện có.

  3. Khởi động các dịch vụ Docker:

    bash scripts/skillbox.sh start

  4. Mở http://127.0.0.1:4791 trong trình duyệt.

  5. Đọc SKILLBOX_ADMIN_TOKEN từ tệp .env cục bộ và dùng nó để đăng nhập. Tập lệnh thiết lập cố ý không in token này.

Giữ riêng tư tệp .env. Token chủ sở hữu kiểm soát quyền truy cập quản trị và cũng được dùng để bảo vệ thông tin xác thực tích hợp được lưu trữ.

Triển khai từ xa

Để cài đặt từ xa, đặt SKILLBOX_ORIGIN thành origin HTTPS của bản triển khai và cấu hình proxy ngược TLS. Không công khai một instance production qua HTTP không mã hóa. Xem ghi chú triển khai của repository để biết các chi tiết triển khai được hỗ trợ.

Phát triển cục bộ không dùng thiết lập ứng dụng chỉ dành cho Docker

Nếu bạn đã có Bun và cơ sở dữ liệu PostgreSQL 16 trở lên, hãy cài đặt các dependency và khởi động ứng dụng trực tiếp:

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

Lưu cả ba giá trị bắt buộc trong một môi trường được bảo vệ thay vì commit chúng vào hệ thống quản lý mã nguồn.

Tạo kỹ năng và máy khách có phạm vi quyền hạn

Sau khi đăng nhập, hãy tạo một kỹ năng trong trình chỉnh sửa hoặc nhập một gói kỹ năng có sẵn. Các bản sửa đổi kỹ năng là bất biến, vì vậy máy khách có thể tải hoặc lấy một bản sửa đổi cụ thể thay vì phụ thuộc vào nội dung luôn thay đổi.

Tiếp theo, tạo một hồ sơ và cấp quyền truy cập cho hồ sơ đó đối với các kỹ năng hoặc gói cần thiết. Phân công độc lập các quyền tạo, cập nhật, lưu trữ và đề xuất theo mục đích của máy khách. Cuối cùng, tạo một kết nối máy khách bằng hồ sơ đó.

Khóa máy khách chỉ được hiển thị một lần và Skillbox chỉ lưu các giá trị băm của chúng. Lưu từng khóa ngay lập tức trong cấu hình máy khách được bảo vệ. Sử dụng một khóa riêng cho mỗi máy khách thay vì phân phối token chủ sở hữu.

Cấu hình CLI

CLI đọc cấu hình JSON chứa URL Skillbox và khóa máy khách. Đường dẫn mặc định là ~/.config/skillbox/config.json.

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

Đặt quyền tệp thành 0600. Các biến môi trường SKILLBOX_URL và SKILLBOX_TOKEN sẽ ghi đè các giá trị trong tệp cấu hình. Nếu chưa cấu hình URL, CLI sẽ an toàn kết nối đến localhost thay vì dịch vụ của người khác.

Giữ cli/skillbox.mjs và cli/package.mjs cùng nhau. Sau đó, bạn có thể khám phá và truy xuất các kỹ năng được cấp quyền:

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

Thao tác fetch xác thực đường dẫn, mã băm tệp, kích thước, cờ thực thi và checksum của gói trước khi ghi tệp theo cách nguyên tử. Thao tác này không thực thi mã hoặc cài đặt dependency.

Phát hành kỹ năng đã cập nhật

Phát hành một thư mục cục bộ bằng cách cung cấp ID kỹ năng và bản sửa đổi mà bạn dự kiến cập nhật:

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

Bản sửa đổi dự kiến hỗ trợ phát hiện xung đột. Việc xuất bản cũng phụ thuộc vào các quyền được cấp cho hồ sơ ứng dụng khách.

Tương thích kiểm tra nhật ký

Chủ sở hữu có thể chạy kiểm tra tương thích không làm thay đổi dữ liệu:

node cli/skillbox.mjs audit

Lệnh sẽ thoát với trạng thái 1 khi phát hiện các gói không tương thích. Lệnh giúp bạn đánh giá khả năng tương thích của MCP Skills mà không phải viết lại các gói hiện có.

Kết nối tác nhân AI qua MCP

Cài đặt bootstrap/SKILL.md làm bootstrap skills-library của tác nhân. Các ứng dụng khách hỗ trợ HTTP MCP có thể kết nối đến điểm cuối /mcp của phiên bản bạn triển khai và gửi khóa ứng dụng khách dưới dạng mã thông báo bearer:

Authorization: Bearer YOUR_CLIENT_KEY

Đối với ứng dụng khách MCP yêu cầu stdio, hãy cấu hình cầu nối đi kèm:

{
  "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"
      }
    }
  }
}

Các công cụ MCP cơ sở bao gồm search_skills, recommend_skills, load_skill, read_skill_file và report_skill_use. Các công cụ ghi và đề xuất chỉ được cung cấp khi hồ sơ của ứng dụng khách cấp các quyền tương ứng.

Skillbox cũng cung cấp các kỹ năng tương thích được ủy quyền thông qua resources/list và resources/read của MCP cơ sở. Có thể truy cập các tệp nhị phân và tệp lớn dưới dạng tài nguyên, nhưng việc đọc tài nguyên không kích hoạt hoặc thực thi một kỹ năng.

Chưa có thông báo hỗ trợ đầy đủ cho io.modelcontextprotocol/skills. Triển khai hiện tại cung cấp các tính năng sẵn sàng thông qua giao thức MCP cơ sở, trong khi khả năng khám phá và thương lượng gốc vẫn phụ thuộc vào SDK và bản nâng cấp giao thức.

Sử dụng tìm kiếm và đề xuất đúng cách

Khi bắt đầu một tác vụ, tác nhân vẫn nên gọi search_skills để lập danh mục các kỹ năng được ủy quyền có liên quan. Đề xuất bổ sung cho bước tìm kiếm này chứ không thay thế bước đó. Trước khi áp dụng kỹ năng đã chọn, hãy tải kỹ năng bằng bản sửa đổi bất biến do Skillbox trả về.

Nếu không có nhà cung cấp đề xuất bên ngoài, bạn có thể tìm kiếm từ CLI:

node cli/skillbox.mjs search "database migration"

Để yêu cầu đề xuất nhận biết ngữ cảnh tác vụ:

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

Thao tác MCP tương đương là recommend_skills({task, limit?, offset?}). Ứng dụng khách HTTP có thể gửi cùng phần nội dung JSON đã xác thực đến POST /api/skill-recommendations.

Cấu hình đề xuất Jev tùy chọn

  1. Mở Cài đặt → Đề xuất Jev.

  2. Chọn Vercel AI Gateway, là tùy chọn mặc định, hoặc TypeSafe AI.

  3. Nhập và lưu khóa API của riêng bạn cho nhà cung cấp đã chọn.

Các khóa của nhà cung cấp được lưu riêng biệt. Việc chọn TypeSafe không gửi khóa Gateway đã lưu đến TypeSafe, và khi chuyển đổi nhà cung cấp, khóa đã lưu trước đó vẫn được giữ lại. Xóa khóa của nhà cung cấp đã chọn sẽ vô hiệu hóa các lệnh gọi mô hình cho nhà cung cấp đó.

Khóa được mã hóa trong PostgreSQL bằng AES-256-GCM, sử dụng vật liệu khóa được tạo từ SKILLBOX_ADMIN_TOKEN. Khóa không được API cài đặt trả về và không được đưa vào các gói trình duyệt. Thay đổi mã thông báo của chủ sở hữu mà không thực hiện quy trình xoay vòng được tài liệu hóa sẽ khiến thông tin xác thực tích hợp đã lưu không thể đọc được.

Việc lưu khóa không xác minh quyền truy cập nhà cung cấp hoặc việc mua tín dụng. Jev gửi văn bản tác vụ và mô tả các kỹ năng đang hoạt động, được ủy quyền đến nhà cung cấp đã chọn, vì vậy các điều khoản thanh toán và xử lý dữ liệu của nhà cung cấp đó sẽ được áp dụng.

Hiểu kết quả đề xuất và cơ chế dự phòng

Jev đánh giá toàn bộ danh mục lá được ủy quyền, bật và không lưu trữ, tối đa 200 lá hoặc 120.000 ký tự đã tuần tự hóa. Các danh mục lớn hơn sẽ chuyển sang cơ chế dự phòng một cách rõ ràng thay vì xếp hạng một tập con không được công bố.

  • Mức độ liên quan là điểm chưa được hiệu chuẩn từ 0 đến 4, không phải xác suất.
  • Kết quả đạt ít nhất 3 điểm được trả về theo thứ tự điểm giảm dần, sau đó theo ID.
  • noMatch=true nghĩa là không có ứng viên nào được đánh giá đạt ngưỡng.
  • Khóa bị thiếu, lỗi nhà cung cấp, phản hồi sai định dạng, giới hạn tốc độ, giới hạn dung lượng hoặc thời hạn tám giây sẽ kích hoạt cơ chế dự phòng tìm kiếm PostgreSQL.
  • Kết quả dự phòng sử dụng method=search, relevance=null và một fallbackReason.

Bộ nhớ đệm cục bộ của tiến trình chứa tối đa 128 mục trong năm phút. Skillbox cho phép hai lượt đánh giá đồng thời và mười yêu cầu không dùng bộ nhớ đệm cho mỗi phạm vi mỗi phút, không tự động thử lại. Các quyền được cấp, trạng thái vòng đời và bản sửa đổi được kiểm tra trước và sau các lệnh gọi mô hình, bao gồm cả lần truy cập bộ nhớ đệm.

Nhập, xuất và sao lưu dữ liệu

Nếu có Bun, hãy nhập một thư mục kỹ năng bằng:

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

Quá trình nhập giữ nguyên byte của tệp và frontmatter không xác định, bỏ qua liên kết tượng trưng và các tạo tác thời gian chạy, đồng thời cách ly các mẫu bí mật có thể nhận diện. Cơ chế phát hiện này mang tính heuristic, vì vậy không thay thế cho một cuộc kiểm tra bí mật đầy đủ. Không bao giờ đặt mật khẩu hoặc mã thông báo trong các gói kỹ năng.

Xuất nội dung kỹ năng vào một đích trống:

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

Cơ sở dữ liệu PostgreSQL vẫn là nguồn dữ liệu chuẩn. Chỉnh sửa một thư mục đã xuất không làm thay đổi cơ sở dữ liệu cho đến khi nội dung được xuất bản lại.

Tạo bản sao lưu được bảo vệ bằng:

bash scripts/backup.sh

Các bản xuất và bản sao lưu có thể chứa nội dung kỹ năng riêng tư. Hãy tách chúng khỏi mã nguồn ứng dụng công khai. Tập lệnh xuất GitHub tùy chọn yêu cầu một bản checkout xuất riêng tư chuyên dụng được cấu hình rõ ràng và không được tự động bật.

Mẹo vận hành nâng cao

Sử dụng một khóa ứng dụng cho mỗi tích hợp

Các khóa riêng biệt giúp việc thu hồi và báo cáo sử dụng hữu ích hơn. Việc thu hồi một khóa sẽ chặn các yêu cầu trong tương lai, nhưng không thể thu hồi các tệp mà ứng dụng khách đã tải xuống.

Ưu tiên các hồ sơ có phạm vi hẹp

Chỉ cấp cho mỗi tác nhân các kỹ năng và hành động cần thiết. Các gói được mở rộng thành những kỹ năng lá hiện tại đã loại bỏ trùng lặp, trong khi chỉ các tham chiếu thì không cấp quyền truy cập.

Bảo vệ mã thông báo chủ sở hữu và bản sao lưu

Mã thông báo chủ sở hữu cung cấp quyền quản trị và dùng để tạo vật liệu mã hóa cho thông tin xác thực tích hợp đã lưu. Hãy bảo vệ mã này cùng với cơ sở dữ liệu và các bản sao lưu cấu hình, đồng thời thực hiện quy trình xoay vòng được ghi chép trước khi thay thế mã.

Coi kỹ năng là nội dung, không phải chương trình đáng tin cậy

Skillbox xác thực và phân phối các tệp gói mà không thực thi chúng. Hãy tiếp tục xem xét các hướng dẫn và mã đã tải xuống trước khi sử dụng chúng trong quy trình làm việc của tác nhân.

Thận trọng khi đánh giá các đề xuất

Nhà phát triển có thể chạy bài đánh giá tùy chọn có tính phí bằng khóa nhà cung cấp của riêng mình:

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

Sử dụng AI_GATEWAY_API_KEY cho Vercel hoặc TYPESAFE_API_KEY hay JEV_KEY cho TypeSafe. Tập lệnh này không cấu hình ứng dụng hay lưu thông tin xác thực. Mẫu tổng hợp của nó không phải là bảo đảm về độ trễ trong môi trường sản xuất hay hiệu chuẩn xác suất.

Xác minh bản triển khai hoặc đóng góp

Hãy chạy kiểm tra kiểu và bộ kiểm thử độc lập trước khi triển khai các thay đổi:

bun run typecheck
bash scripts/test-isolated.sh

Bộ kiểm thử độc lập tạo và xóa phiên bản PostgreSQL Docker Compose riêng mà không công khai các cổng cơ sở dữ liệu. Bộ này bao quát việc phân quyền, các bản sửa đổi, hành vi của API và MCP, CLI, cài đặt được mã hóa và các đề xuất. Tuyệt đối không trỏ các bài kiểm thử cơ sở dữ liệu đến môi trường sản xuất.

Kết luận

Skillbox cung cấp quy trình được kiểm soát, tự lưu trữ để quản lý các kỹ năng AI có thể tái sử dụng. Hãy bắt đầu bằng thiết lập Docker, tạo các kỹ năng có phiên bản, gán các hồ sơ có phạm vi hẹp và kết nối mỗi tác nhân bằng khóa ứng dụng riêng. Sau đó, bạn có thể bổ sung quyền truy cập MCP, các đề xuất Jev tùy chọn, quy trình di động và bản sao lưu, đồng thời vẫn giữ quyền sở hữu danh mục và thông tin xác thực của mình.