Przejdź do głównej treści
Polski— Wybierz język
Menu

Pakietowanie wtyczki

Lekcja 10 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Dlaczego pakować
  2. Struktura przenośnego pakietu
  3. Deklarowanie serwera MCP
  4. Metadane specyficzne dla OpenAI
  5. Szybka ścieżka: @plugin-creator
  6. Lokalne marketplace
  7. Hooki: tylko wersja desktopowa
  8. Kluczowe wnioski

Lekcja przepisana 3 listopada 2026 na podstawie strony Package your plugin z dokumentacji wtyczek OpenAI. Poprzednia lekcja opisywała budowanie „pakietu“ dla nieistniejącego „Sklepu ChatGPT“ przy użyciu brakującego manifestu. Wtyczka jest pakowana z manifestem plugin.json zgodnym ze schematem Agent Plugins. Źródło: Package your plugin.

Dlaczego pakować

Gdy już napiszesz swoje umiejętności i w razie potrzeby zbudujesz serwer MCP, ostatnim krokiem jest złożenie ich w jednostkę instalacyjną. Pakietowanie nadaje Twojej wtyczce stabilną tożsamość i informuje ChatGPT oraz Codex, które umiejętności, połączenia z serwerami MCP i zasoby należą do siebie. Logika interfejsu użytkownika i uwierzytelniania pozostaje wewnątrz serwera MCP; manifest jedynie łączy tę integrację z resztą pakietu.

Struktura przenośnego pakietu

Przenośna wtyczka posiada manifest plugin.json w swoim katalogu głównym, deklarujący schemat Agent Plugins. Folder może również zawierać katalog skills/, plik mcp.json dla serwerów MCP dystrybuowanych razem z wtyczką oraz zasoby graficzne w katalogu assets/.

mon-plugin/
├── plugin.json
├── mcp.json
├── skills/
│   └── compte-rendu/
│       └── SKILL.md
└── assets/
    ├── icon.png
    └── logo.png

Minimalny manifest mieści się w zaledwie kilku liniach. Nazwa, stabilna i zapisana w formacie kebab-case, służy zarówno jako identyfikator, jak i przestrzeń nazw dla komponentów; umiejętności są wykrywane automatycznie w katalogu skills/ bez konieczności ich jawnego deklarowania.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "notes-equipe",
  "version": "0.1.0",
  "description": "Team notes and meeting minutes"
}

Każda umiejętność znajduje się w skills/<nazwa>/SKILL.md, z nagłówkiem zawierającym jej nazwę i opis, po którym następują instrukcje:

---
name: compte-rendu
description: Drafts meeting minutes from team notes.
---

Retrieve meeting notes using list_notes, group them by topic,
then draft a summary: decisions, action items with owners, and open points.

Deklarowanie serwera MCP

Serwery MCP dystrybuowane razem z wtyczką są deklarowane w pliku mcp.json w katalogu głównym, przy użyciu odpowiedniego schematu i określeniu typu transportu dla każdego serwera:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "notes": {
      "type": "streamable-http",
      "url": "https://notes.example.com/mcp"
    }
  }
}

Uwierzytelnianie serwera deklaruje się w tym samym pliku, pod kluczem extensions["com.openai"].auth dla każdego serwera – należy ono do serwera, a nie do manifestu. W przypadku zgłoszenia publicznego przesyłasz zdalny punkt końcowy HTTPS; serwery lokalne podlegają osobnej ścieżce zarezerwowanej dla wtyczek desktopowych.

Metadane specyficzne dla OpenAI

Prezentacja w katalogu, mapowania do już zarejestrowanych serwerów MCP oraz hooki są deklarowane w obiekcie extensions.com.openai w głównym pliku plugin.json, podczas gdy przenośna tożsamość (name, version, description) pozostaje w katalogu głównym:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "notes-equipe",
  "version": "0.1.0",
  "description": "Team notes and meeting minutes",
  "extensions": {
    "com.openai": {
      "interface": {
        "displayName": "Team Notes",
        "shortDescription": "Notes and meeting minutes",
        "developerName": "Your Team",
        "category": "Productivity",
        "capabilities": ["Read", "Write"],
        "websiteURL": "https://example.com",
        "privacyPolicyURL": "https://example.com/privacy",
        "termsOfServiceURL": "https://example.com/terms",
        "defaultPrompt": ["Use Team Notes to draft Monday's meeting minutes."],
        "composerIcon": "./assets/icon.png",
        "logo": "./assets/logo.png"
      }
    }
  }
}

Ścieżki w tym obiekcie są względne wobec katalogu głównego wtyczki i zaczynają się od ./. Zasoby graficzne (composerIcon, logo, screenshots) powinny najlepiej trafić do ./assets/. Pole apps służy wyłącznie do wskazania pliku .app.json zawierającego mapowania do serwerów MCP już zarejestrowanych w ChatGPT.

Możesz również zadeklarować umiejętność wdrożeniową (onboarding skill) poprzez extensions.com.openai.onboardingSkill (na przykład ./skills/setup/SKILL.md): prowadzi ona użytkownika po instalacji, pomagając wybrać przestrzeń roboczą lub ustawić preferencje. Przetestuj ją w nowej rozmowie oraz podczas trwającej instalacji.

Starszy format, z manifestem w .codex-plugin/plugin.json, jest nadal akceptowany ze względów kompatybilności: jest używany tylko wtedy, gdy obiekt extensions.com.openai nie występuje, ponieważ te dwa formaty nie łączą się ze sobą. Nowe pakiety powinny używać głównego pliku plugin.json.

Szybka ścieżka: @plugin-creator

ChatGPT i Codex zawierają umiejętność @plugin-creator, która generuje dla Ciebie strukturę – obecnie w formacie kompatybilnościowym .codex-plugin/. Aby dołączyć do niej serwer MCP, najpierw połącz ten serwer w ChatGPT (Add custom MCP server, a następnie Create as a plugin), zanotuj techniczny identyfikator połączenia z adresu URL przeglądarki – zaczyna się on od plugin_asdk_app – i przekaż go do @plugin-creator w trybie Work (lub do $plugin-creator w Codex). Umiejętność ta może również utworzyć wpis w osobistym marketplace, co pozwala zainstalować i przetestować wtyczkę ze źródła w Twoim katalogu lokalnym.

Lokalne marketplace

Marketplace to katalog JSON wtyczek. Służy do pisania, testowania i dystrybucji zespołowej obok publicznego katalogu: w trybie Work lub w Codex każdy marketplace pojawia się jako wybieralne źródło w katalogu wtyczek. W ten sposób przetestujesz kompletną wtyczkę przed jej zgłoszeniem (Lekcja 9).

Hooki: tylko wersja desktopowa

Hooki cyklu życia są obsługiwane wyłącznie dla wtyczek instalowanych ręcznie w aplikacji desktopowej Codex, a wtyczka je zawierająca nie kwalifikuje się do publicznego katalogu. Jeśli Twoja wtyczka ma trafić do publikacji, pomiń je.

Kluczowe wnioski

  • Przenośny pakiet: plugin.json (schemat Agent Plugins), skills/, mcp.json, assets/
  • Serwer MCP jest deklarowany w mcp.json wraz z typem transportu; tam też znajduje się uwierzytelnianie
  • Prezentacja, mapowania i umiejętność wdrożeniowa trafiają do extensions.com.openai
  • @plugin-creator generuje strukturę; lokalny marketplace służy do testów
  • Wtyczka z hookami nie kwalifikuje się do publicznego katalogu