Plugin-Ersteller

Was macht Plugin-Ersteller?

Schnellstart

1. Führen Sie das Gerüst-Skript aus:

# Plugin-Namen werden in Kleinbuchstaben mit Bindestrich normalisiert und müssen <= 64 Zeichen lang sein.
# Der generierte Ordnername und der Name in plugin.json sind immer identisch.
# Ausführung vom Skill-Stammverzeichnis (dem Verzeichnis, das diese `SKILL.md` enthält).
# Standardmäßig Erstellung in `~/plugins/<plugin-name>`.
python3 scripts/create_basic_plugin.py <plugin-name>

2. Bearbeiten Sie <plugin-pfad>/.codex-plugin/plugin.json, wenn die Anfrage spezifische Metadaten vorgibt. Das Gerüst beginnt mit gültigen Standardwerten und darf keine [TODO: ...]-Platzhalter enthalten.

3. Generieren oder aktualisieren Sie den persönlichen Marktplatzeintrag, wenn das Plugin in der Codex-UI-Reihenfolge erscheinen soll:

# Persönliche Marktplatzeinträge standardmäßig unter `~/.agents/plugins/marketplace.json`.
python3 scripts/create_basic_plugin.py my-plugin --with-marketplace

Geben Sie --marketplace-name <name> nur dann an, wenn der Standardname personal bereits belegt oder installiert ist und Sie eine andere neue Marktplatzdatei anlegen müssen:

python3 scripts/create_basic_plugin.py my-plugin \
  --with-marketplace \
  --marketplace-name team-local

Verwenden Sie ein Repository-/Team-Marktplatz nur, wenn der Benutzer ausdrücklich dieses Ziel anfordert:

python3 scripts/create_basic_plugin.py my-plugin \
  --path <repo-root>/plugins \
  --marketplace-path <repo-root>/.agents/plugins/marketplace.json \
  --with-marketplace

Wenn der Benutzer einen Marktplatzpfad angibt, stellen Sie sicher, dass dieser Marktplatz tatsächlich installiert ist, bevor Sie den Benutzer anweisen, von dort neu zu installieren. Die standardmäßige persönliche Marktplatzdatei unter ~/.agents/plugins/marketplace.json wird implizit erkannt, andere Marktplatzpfade jedoch nicht. Unter Windows verwenden Sie den entsprechenden Pfad im Benutzerprofil.

4. Passen Sie optionale Begleiterordner nach Bedarf an:

python3 scripts/create_basic_plugin.py my-plugin \
  --path <übergeordnetes-plugin-verzeichnis> \
  --marketplace-path <marktplatz-json-pfad> \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace

<übergeordnetes-plugin-verzeichnis> ist das Verzeichnis, in dem der Plugin-Ordner <plugin-name> erstellt wird (z. B. ~/plugins).

5. Führen Sie vor der Rückgabe eines generierten Plugins aus:

python3 scripts/validate_plugin.py <plugin-pfad>

Für Aktualisierungen eines vorhandenen lokalen Plugins während der Entwicklung behalten Sie den Gerüst-Ablauf bei und verwenden Sie die Referenz anstatt die Marktplatzdateien manuell zu bearbeiten:

python3 scripts/update_plugin_cachebuster.py <plugin-pfad>

Bevorzugen Sie den Standard-Cache-Buster des Hilfsprogramms, es sei denn, der Benutzer fordert explizit eine bestimmte Überschreibung an. Siehe references/installing-and-updating.md für den erwarteten Cache-Buster- und Neuinstallationsablauf beim Iterieren eines vorhandenen lokalen Plugins.

Was dieser Skill erstellt

• Standardmäßige, marktplatzgestützte Gerüste verwenden die persönliche Marktplatzdatei unter ~/.agents/plugins/marketplace.json, wobei Plugins normalerweise in ~/plugins/<plugin-name>/ gespeichert werden.
• Erstellt das Plugin-Stammverzeichnis unter /<übergeordnetes-plugin-verzeichnis>/<plugin-name>/.
• Erstellt immer /<übergeordnetes-plugin-verzeichnis>/<plugin-name>/.codex-plugin/plugin.json.
• Befüllt das Manifest mit der validierten Schemaform, die der Aufnahmepfad akzeptiert.
• Erstellt oder aktualisiert ~/.agents/plugins/marketplace.json, wenn --with-marketplace gesetzt ist.
  • Wenn die Marktplatzdatei noch nicht existiert, legen Sie zuerst ein persönliches Marktplatz-Stammverzeichnis an, bevor Sie den ersten Plugin-Eintrag hinzufügen.
• <plugin-name> wird mit den Namensregeln des Skill-Erstellers normalisiert:
  • Mein Plugin → mein-plugin
  • Mein--Plugin → mein-plugin
  • Unterstriche, Leerzeichen und Satzzeichen werden in - umgewandelt
  • Das Ergebnis ist in Kleinbuchstaben mit Bindestrichen, und aufeinanderfolgende Bindestriche werden zusammengefasst
• Unterstützt die optionale Erstellung von:
  • skills/
  • hooks/
  • scripts/
  • assets/
  • .mcp.json
  • .app.json

Marktplatz-Workflow

• Die Erstellung eines persönlichen Marktplatzes erfolgt standardmäßig in ~/.agents/plugins/marketplace.json. Dabei bezeichnet "persönlicher Marktplatz" den Marktplatz, dessen Datei sich an diesem Pfad befindet.
• Die Erstellung eines Repository-/Team-Marktplatzes erfolgt nur dann aktiv, wenn sowohl --path als auch --marketplace-path angegeben sind und der Benutzer dies ausdrücklich anfordert.
• --marketplace-name ist ein Ausnahmepfad. Verwenden Sie ihn nur, wenn der Standardname personal bereits belegt ist und Sie eine andere neue Marktplatzdatei anlegen müssen.
• Verwenden Sie --marketplace-name nicht, um eine vorhandene Marktplatzdatei umzubenennen. Wenn die Datei bereits existiert, muss ihr oberster Name name bereits übereinstimmen.
• Wenn der Benutzer einen anderen Marktplatzpfad angibt, behandeln Sie diesen Marktplatz so, als ob er eine explizite Installation über codex plugin marketplace add benötigt.
• Bevorzugen Sie scripts/read_marketplace_name.py, wenn Sie den Marktplatznamen aus einer beliebigen marketplace.json-Datei benötigen. Ohne Argument liest es den standardmäßigen persönlichen Marktplatz; mit einem expliziten Pfad funktioniert es auch für Repository-/Team-Marktplätze.
• In beiden Fällen bleibt der generierte Quellpfad ./plugins/<plugin-name>.
• Die Marktplatz-Stammmetadaten unterstützen den obersten Namen name plus optional interface.displayName.
• Behandeln Sie die Plugin-Reihenfolge in plugins[] als Render-Reihenfolge in Codex. Hängen Sie neue Einträge an, es sei denn, ein Benutzer fordert explizit eine Neuanordnung der Liste an.
• displayName gehört in das interface-Objekt des Marktplatzes, nicht in einzelne plugins[]-Einträge.
• Jeder generierte Marktplatzeintrag muss alle folgenden Felder enthalten:
  • policy.installation
  • policy.authentication
  • category
• Standardmäßige neue Einträge:
  • policy.installation: "AVAILABLE"
  • policy.authentication: "ON_INSTALL"
• Überschreiben Sie die Standardwerte nur, wenn der Benutzer explizit einen anderen zulässigen Wert angibt.
• Zulässige Werte für policy.installation:
  • NOT_AVAILABLE
  • AVAILABLE
  • INSTALLED_BY_DEFAULT
• Zulässige Werte für policy.authentication:
  • ON_INSTALL
  • ON_USE
• Behandeln Sie policy.products als Überschreibung. Lassen Sie es weg, es sei denn, der Benutzer fordert explizit eine Produktbegrenzung an.
• Die Form des generierten Plugin-Eintrags ist:

{
  "name": "plugin-name",
  "source": {
    "source": "local",
    "path": "./plugins/plugin-name"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

• Verwenden Sie --force nur, wenn Sie absichtlich einen vorhandenen Marktplatzeintrag für denselben Plugin-Namen ersetzen.

• Wenn die Ziel-Marktplatzdatei noch nicht existiert, erstellen Sie sie mit einem obersten "name", einem "interface"-Objekt mit "displayName" und einem plugins-Array und fügen Sie dann den neuen Eintrag hinzu.

• Für eine brandneue Marktplatzdatei sollte das Stammobjekt wie folgt aussehen:

{
  "name": "personal",
  "interface": {
    "displayName": "Personal"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": {
        "source": "local",
        "path": "./plugins/plugin-name"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Erforderliches Verhalten

• Der äußere Ordnername und der "name" in plugin.json sind immer der gleiche normalisierte Plugin-Name.
• Entfernen Sie keine erforderliche Struktur; behalten Sie .codex-plugin/plugin.json bei.
• Lassen Sie keine [TODO: ...]-Platzhalter in Plugin-Manifesten zurück.
• Lassen Sie apps und mcpServers aus plugin.json heraus, es sei denn, ihre Begleitdateien wurden tatsächlich erstellt.
• Lassen Sie nicht unterstützte Plugin-Manifest-Felder weg, die von der Validierung abgelehnt werden, einschließlich hooks.
• Wenn Sie Dateien innerhalb eines vorhandenen Plugin-Pfads erstellen, verwenden Sie --force nur, wenn das Überschreiben beabsichtigt ist.
• Bewahren Sie alle vorhandenen interface.displayName des Marktplatzes.
• Schreiben Sie beim Generieren von Marktplatzeinträgen immer policy.installation, policy.authentication und category, auch wenn ihre Werte die Standardwerte sind.
• Fügen Sie policy.products nur hinzu, wenn der Benutzer explizit nach dieser Überschreibung fragt.
• Behalten Sie den Marktplatz-source.path relativ zum ausgewählten Marktplatz-Stammverzeichnis als ./plugins/<plugin-name> bei.
• Verwenden Sie --marketplace-name nur beim Erstellen einer neuen Marktplatzdatei, deren Name nicht personal sein soll, weil dieser Name bereits belegt oder anderswo installiert ist.
• Wenn Codex eine Genehmigung zum Schreiben der Marktplatzdatei benötigen würde, holen Sie diese Genehmigung vor dem Fortfahren ein. Wenn der Benutzer den Schreibvorgang lieber selbst ausführen möchte, geben Sie den genauen Gerüstbefehl an und fahren Sie dann mit der Validierung oder nachfolgenden Plugin-Bearbeitungen fort, anstatt den Workflow vage zu lassen.
• Für Aktualisierungen eines vorhandenen lokalen Plugins während der Entwicklung bearbeiten Sie die Marktplatzkonfiguration oder marketplace.json nicht von Hand. Verwenden Sie den in references/installing-and-updating.md und scripts/update_plugin_cachebuster.py dokumentierten Aktualisierungsablauf.
• Weisen Sie den Benutzer nicht an, codex plugin marketplace add für den standardmäßigen persönlichen Marktplatz-Workflow auszuführen. Dieser Befehl ist für die explizite, nicht standardmäßige Marktplatzkonfiguration gedacht, nicht für den Standardpfad ~/.agents/plugins/marketplace.json.
• Wenn der Benutzer einen nicht standardmäßigen --marketplace-path angegeben hat, stellen Sie sicher, dass dieser Marktplatz installiert ist, bevor Sie Neuinstallationsanweisungen geben. Verwenden Sie codex plugin marketplace add <pfad-zum-marktplatz-stammverzeichnis>, wenn dieser explizite Marktplatz noch nicht konfiguriert wurde.
• Wenn der Workflow ein marktplatzgestütztes Plugin erstellt oder aktualisiert hat, beenden Sie die letzte benutzerorientierte Antwort mit einer kurzen Codex-App-Übergabe. Sagen Sie Um dies in der Codex-App anzuzeigen: und schreiben Sie View <normalisierter Plugin-Name> und Share <normalisierter Plugin-Name> als Markdown-Links, nicht als rohe URLs oder Code-Spannen.
• Der View-Deep-Link verwendet codex://plugins/<normalisierter Plugin-Name>?marketplacePath=<absoluter marketplace.json-pfad>. Der Share-Deep-Link verwendet dieselbe URL mit &mode=share.
• Ersetzen Sie die Platzhalter durch den tatsächlichen normalisierten Plugin-Namen und den absoluten marketplace.json-Pfad aus dem erstellten Plugin. Kodieren Sie das Pfadsegment und den Abfragewert bei Bedarf URL-kodiert.
• Fügen Sie diesen Deep-Links keine Abfrageparameter pluginName oder hostId hinzu. Codex leitet beide ab, nachdem der Benutzer auf den Link geklickt hat.
• Geben Sie die Links View <normalisierter Plugin-Name> oder Share <normalisierter Plugin-Name> nicht aus, wenn kein Marktplatzeintrag erstellt oder aktualisiert wurde.

Referenz zum genauen Spezifikationsbeispiel

Für das genaue kanonische JSON-Beispiel sowohl für Plugin-Manifeste als auch für Marktplatzeinträge verwenden Sie:

• references/plugin-json-spec.md
• references/installing-and-updating.md für Aktualisierungs-/Neuinstallationsanleitungen beim Iterieren eines vorhandenen lokalen Plugins sowie das Verhalten bei der Aufnahme eines neuen Threads nach der Neuinstallation

Validierung

Nach der Bearbeitung von SKILL.md führen Sie aus:

python3 ../skill-creator/scripts/quick_validate.py .

Bevor Sie ein generiertes Plugin zurückgeben, führen Sie aus:

python3 scripts/validate_plugin.py <plugin-pfad>