SpyBara
Go Premium

plugin-dependencies.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 61 additions and 25 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Fri 25 23:58

Versionsbeschränkungen für Plugin-Abhängigkeiten

Deklarieren Sie Versionsbeschränkungen für Plugin-Abhängigkeiten, und bündeln Sie einen kuratierten Plugin-Satz hinter einer Installation.

Ein Plugin kann von anderen Plugins abhängen, indem es diese in plugin.json oder in seinem Marketplace-Eintrag auflistet. Standardmäßig verfolgt eine Abhängigkeit die neueste verfügbare Version, sodass eine vorgelagerte Veröffentlichung die Abhängigkeit Ihres Plugins ohne Warnung ändern kann. Versionsbeschränkungen ermöglichen es Ihnen, eine Abhängigkeit in einem getesteten Versionsbereich zu halten, bis Sie sich entscheiden, sie zu aktualisieren.

Wenn Sie ein Plugin installieren, das Abhängigkeiten deklariert, löst Claude Code diese automatisch auf und installiert sie, mit Ausnahme einer Abhängigkeit, deren Marketplace-Eintrag eine command-Quelle oder einen headersHelper hat, den Sie zuerst selbst installieren. Später installieren /reload-plugins, die automatische Aktualisierung des Marketplace des abhängigen Plugins, das erneute Ausführen von claude plugin install auf dem abhängigen Plugin und claude plugin marketplace add alle deklarierten Abhängigkeiten, die noch nicht installiert sind, unter denselben Regeln. Wenn eine ungelöst bleibt, siehe Abhängigkeitsfehler beheben.

Diese Anleitung ist für Plugin-Autoren, die Abhängigkeiten in plugin.json deklarieren, und für Marketplace-Verwalter, die Versionen taggen. Abhängigkeiten hier sind andere Plugins. Für die npm- und Bun-Pakete, die ein Plugin selbst verwendet, siehe Node.js-Paketabhängigkeiten. Um Plugins mit Abhängigkeiten zu installieren, siehe Plugins entdecken und installieren. Für das vollständige Manifest-Schema siehe die Plugins-Referenz.

Warum Versionsbeschränkungen verwenden

Stellen Sie sich einen internen Marketplace vor, auf dem zwei Teams Plugins veröffentlichen. Das Platform-Team verwaltet secrets-vault, einen MCP-Server, der ein Secrets-Backend umhüllt. Das Deploy-Team verwaltet deploy-kit, das secrets-vault aufruft, um während Deployments Anmeldedaten abzurufen.

deploy-kit wird gegen secrets-vault v2.1.0 getestet. Ohne Versionsbeschränkung führt die nächste Veröffentlichung des Platform-Teams, die ein MCP-Tool umbenennt, dazu, dass die automatische Aktualisierung secrets-vault auf die neue Version für jeden Ingenieur aktualisiert und deploy-kit bricht.

Mit einer Versionsbeschränkung deklariert deploy-kit, dass es secrets-vault im Bereich ~2.1.0 benötigt. Ingenieure mit installiertem deploy-kit bleiben auf der höchsten passenden 2.1.x-Patch-Version. Das Deploy-Team aktualisiert nach eigenem Zeitplan, indem es eine neue deploy-kit-Version mit einer breiteren Beschränkung veröffentlicht.

Abhängigkeit mit Versionsbeschränkung deklarieren

Listet Abhängigkeiten im dependencies-Array der plugin.json Ihres Plugins auf.

Das folgende Manifest deklariert eine unversionierte Abhängigkeit und eine beschränkte Abhängigkeit:

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Ein Eintrag kann ein einfacher String mit nur dem Plugin-Namen sein, wie "audit-logger" im obigen Beispiel, das von der Version abhängt, die der Marketplace dieses Plugins bereitstellt. Für mehr Kontrolle verwenden Sie ein Objekt mit diesen Feldern:

Feld Typ Beschreibung
name string Plugin-Name. Wird im selben Marketplace wie das deklarierte Plugin aufgelöst. Erforderlich.
version string Ein semver-Bereich wie ~2.1.0, ^2.0, >=1.4 oder =2.1.0. Die Abhängigkeit wird in der höchsten getaggten Version abgerufen, die diesen Bereich erfüllt.
marketplace string Ein anderer Marketplace, um name darin aufzulösen. Marketplace-übergreifende Abhängigkeiten sind blockiert, es sei denn, der Ziel-Marketplace ist in allowCrossMarketplaceDependenciesOn in der marketplace.json des Root-Marketplace aufgelistet.

Vorabversionen wie 2.0.0-beta.1 sind ausgeschlossen, es sei denn, Ihr Bereich entscheidet sich mit einem Vorabversions-Suffix wie ^2.0.0-0 dafür.

Plugins für ein Team bündeln

Neben dem erforderlichen name kann ein Plugin-Manifest nur aus einem dependencies-Array bestehen. Die Installation zieht jede Abhängigkeit nach sich, was es zu einer Möglichkeit macht, einen kuratierten Plugin-Satz hinter einer Installation zu verpacken.

Beispielsweise kann ein Plattform-Team rollenspezifische Bundles in einem internen Marketplace veröffentlichen, damit Ingenieure ein claude plugin install ausführen, anstatt jedes Tool separat zu installieren:

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Standard plugin set for backend engineers",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

Die Installation von backend-standard löst alle vier Abhängigkeiten auf und installiert sie.

Um später ein Tool zum Standard-Set hinzuzufügen, veröffentlichen Sie eine neue backend-standard-Version mit der zusätzlichen Abhängigkeit. Auto-Update ist standardmäßig für Nicht-Anthropic-Marketplaces deaktiviert, daher wählen Ingenieure die neue Version auf eine von zwei Arten:

  • Aktivieren Sie Auto-Update für den Marketplace in /plugin. Das nächste Auto-Update verschiebt das Bundle zur neuen Version und installiert alle Abhängigkeiten, die es hinzufügt.
  • Führen Sie claude plugin update backend-standard aus, dann /reload-plugins, um die neu hinzugefügten Abhängigkeiten zu installieren.

Um Bundles in einer Organisation auszurollen, fügen Sie das Bundle-Plugin zu enabledPlugins in verwalteten Einstellungen hinzu.

Abhängigkeit von einem Plugin aus einem anderen Marketplace

Standardmäßig weigert sich Claude Code, eine Abhängigkeit automatisch zu installieren, die sich in einem anderen Marketplace als das Plugin befindet, das sie deklariert. Dies verhindert, dass ein Marketplace stillschweigend Plugins aus einer Quelle abruft, die Sie nicht überprüft haben.

Um dies zu ermöglichen, fügt der Verwalter des Root-Marketplace den Namen des Ziel-Marketplace zu allowCrossMarketplaceDependenciesOn in marketplace.json hinzu. Der Root-Marketplace ist derjenige, der das Plugin hostet, das der Benutzer installiert. Nur seine Allowlist wird konsultiert, daher vertraut nicht durch zwischengelagerte Marketplaces.

Die folgende marketplace.json ermöglicht es deploy-kit, von einem Plugin aus acme-shared abhängig zu sein:

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "acme-shared" }
      ]
    }
  ]
}

Wenn das Feld fehlt oder den Ziel-Marketplace nicht enthält, schlägt die Installation mit einem cross-marketplace-Fehler fehl, der das zu setzende Feld benennt. Benutzer können die Abhängigkeit immer noch manuell zuerst installieren, was die Beschränkung erfüllt, ohne die Allowlist zu ändern.

Ein Plugin und seine Abhängigkeit lokal testen

Wenn Sie ein Plugin und das Plugin, von dem es abhängt, gleichzeitig entwickeln, laden Sie beide mit --plugin-dir:

claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin

Die lokale Kopie der Abhängigkeit erfüllt den Abhängigkeitseintrag Ihres Plugins, auch wenn der Eintrag einen Marketplace benennt, sodass Sie die Abhängigkeit nicht von seinem Marketplace installieren müssen. Claude Code überprüft keine Versionsbeschränkung gegen eine lokale Kopie, daher muss die lokale plugin.json keine version haben. Vor v2.1.242 stimmte ein Abhängigkeitseintrag, der einen Marketplace benannte, nie mit der lokalen Kopie überein, und Claude Code deaktivierte Ihr Plugin beim Laden.

Wenn Sie die Abhängigkeit nicht von ihrem Marketplace installiert haben, wird Ihr Plugin nicht mehr geladen, wenn die lokale Kopie verschwindet:

  • Sie haben die lokale Kopie deaktiviert: Claude Code deaktiviert Ihr Plugin beim nächsten Plugin-Laden. Für einen Abhängigkeitseintrag, der einen Marketplace benennt, meldet Claude Code Dependency "<name>@inline" is disabled — enable it or remove the dependency; für einen Eintrag mit bloßem Namen meldet es die Abhängigkeit nach ihrem bloßen Namen. <name>@inline ist die Art, wie Claude Code jedes --plugin-dir und --plugin-url Plugin identifiziert.
  • Sie haben eine Sitzung ohne das Flag --plugin-dir der Abhängigkeit gestartet: Claude Code meldet die Abhängigkeit als nicht installiert. Übergeben Sie das Flag erneut, oder installieren Sie die Abhängigkeit von ihrem Marketplace.

Tag-Plugin-Releases für Versionauflösung

Claude Code löst Versionsbeschränkungen gegen Git-Tags im Repository auf, das die Abhängigkeit hostet: das eigene Repository des Plugins für github, url und git-subdir Plugin-Quellen, oder das Marketplace-Repository für ein Plugin, das der Marketplace über einen relativen Pfad referenziert. Damit Claude Code die verfügbaren Versionen einer Abhängigkeit findet, müssen die Releases des Upstream-Plugins mit einer bestimmten Namenskonvention getaggt werden.

Taggen Sie jedes Release als {plugin-name}--v{version}, wobei {version} dem Feld version in der plugin.json dieses Commits entspricht. Führen Sie aus dem Plugin-Verzeichnis aus:

claude plugin tag --push

Der Befehl claude plugin tag leitet den Tag-Namen aus dem Plugin-Manifest und dem umschließenden Marketplace-Eintrag ab. Vor dem Erstellen des Tags validiert er den Plugin-Inhalt, prüft, dass plugin.json und der Marketplace-Eintrag sich auf die Version einigen, erfordert einen sauberen Arbeitsbaum im Plugin-Verzeichnis und weigert sich, wenn das Tag bereits existiert.

  • --push pusht das Tag zum Remote origin, daher benötigt das Repository einen konfigurierten Remote origin. Übergeben Sie --remote, um zu einem anderen zu pushen.
  • Wenn der Push fehlschlägt, wird das Tag trotzdem lokal erstellt und der Befehl beendet sich mit einem Fehler.
  • Mit --push endet eine erfolgreiche Ausführung mit Created tag secrets-vault--v2.1.0 und Pushed to origin, wobei die letzte Zeile den Remote benennt, zu dem gepusht wurde. Ohne --push gibt der Befehl stattdessen den auszuführenden git push-Befehl aus.
  • --dry-run gibt aus, was getaggt würde, ohne es zu erstellen.

Das direkte Ausführen von git tag secrets-vault--v2.1.0 ist gleichwertig, wenn Sie plugin.json und den Marketplace-Eintrag selbst synchron halten.

Das Plugin-Namen-Präfix ermöglicht es einem Marketplace-Repository, mehrere Plugins mit unabhängigen Versionssträngen zu hosten. Das Trennzeichen --v wird als Präfix-Abgleich auf den vollständigen Plugin-Namen geparst, daher werden Plugin-Namen, die Bindestriche enthalten, korrekt behandelt.

Wenn Sie ein Plugin installieren, das { "name": "secrets-vault", "version": "~2.1.0" } deklariert, listet Claude Code die Tags im Repository auf, das secrets-vault hostet, filtert diejenigen, die mit secrets-vault--v beginnen, und ruft die höchste Version ab, die ~2.1.0 erfüllt. Wenn kein Tag im eigenen Repository des Plugins den Bereich erfüllt, schlägt die Installation mit Dependency "secrets-vault@acme-tools" has no git tag satisfying ~2.1.0 fehl, was die Abhängigkeit zusammen mit ihrem Marketplace benennt. Für ein Plugin mit relativem Pfad ohne passendes Tag installiert Claude Code stattdessen die aktuelle Kopie des Marketplace und prüft die Beschränkung beim Laden des Plugins.

Für ein Plugin, das der Marketplace über einen relativen Pfad referenziert, löst ein als lokaler Ordnerpfad hinzugefügter Marketplace Tags auf die gleiche Weise auf, wenn der Ordner ein Git-Repository ist. Dies erfordert Claude Code v2.1.196 oder später. In zwei Fällen installiert Claude Code die Abhängigkeit stattdessen aus dem aktuellen Inhalt des Ordners:

  • Frühere Versionen lesen keine Tags aus einem lokalen Marketplace-Ordner, daher wird eine eingeschränkte Abhängigkeit nur geladen, wenn diese Kopie den Bereich erfüllt.
  • Ein lokaler Ordner, der kein Git-Repository ist, hat keine Tags, unabhängig von der Version.

Die Semver des aufgelösten Tags wird separat von der version der plugin.json aufgezeichnet, daher verwenden Beschränkungsprüfungen das Tag, das tatsächlich abgerufen wurde, auch wenn die plugin.json bei diesem Commit einen veralteten Wert hat. Der Cache-Verzeichnisname für eine Tag-aufgelöste Installation enthält ein 12-stelliges Commit-SHA-Suffix, daher erhält die nächste Installation ein frisches Cache-Verzeichnis, anstatt veraltete Inhalte wiederzuverwenden, wenn ein Maintainer ein Tag zu einem anderen Commit verschiebt.

Wie Beschränkungen interagieren

Wenn mehrere installierte Plugins dieselbe Abhängigkeit beschränken, schneidet Claude Code ihre Bereiche ab und löst die Abhängigkeit zur höchsten Version auf, die alle erfüllt. Die folgende Tabelle zeigt, wie häufige Kombinationen aufgelöst werden.

Plugin A erfordert Plugin B erfordert Ergebnis
^2.0 >=2.1 Eine Installation auf dem höchsten 2.x-Tag bei oder über 2.1.0. Beide Plugins werden geladen.
~2.1 ~3.0 Installation von Plugin B schlägt mit range-conflict fehl. Plugin A und die Abhängigkeit bleiben wie sie waren.
=2.1.0 keine Die Abhängigkeit bleibt bei 2.1.0. Die automatische Aktualisierung überspringt neuere Versionen, während Plugin A installiert ist.

Die automatische Aktualisierung ruft eine beschränkte Abhängigkeit auf dem höchsten Git-Tag ab, der jeden Bereich des installierten Plugins erfüllt, anstatt auf der neuesten Version des Marketplace, sodass die Abhängigkeit weiterhin Updates innerhalb ihres zulässigen Bereichs erhält. Wenn kein Tag alle Bereiche erfüllt, wird die Aktualisierung übersprungen und die Übersprungsmeldung erscheint in /plugin Fehler-Registerkarte und benennt das einschränkende Plugin.

Wenn Sie das letzte Plugin deinstallieren, das eine Abhängigkeit beschränkt, wird die Abhängigkeit nicht mehr gehalten und verfolgt bei der nächsten Aktualisierung wieder ihren Marketplace-Eintrag.

Plugin mit Abhängigkeiten aktivieren oder deaktivieren

Dieser Abschnitt behandelt Plugins, die von einem Marketplace installiert wurden. Für eine Kopie, die Sie mit --plugin-dir geladen haben, siehe Plugin und seine Abhängigkeit lokal testen.

Das Aktivieren eines Plugins aktiviert auch die Plugins, von denen es abhängt, und das Deaktivieren eines Plugins wird blockiert, wenn ein anderes aktiviertes Plugin es immer noch benötigt.

Wenn Sie ein Plugin aktivieren, aktiviert Claude Code auch seine Abhängigkeiten im selben Bereich. Wenn eine Abhängigkeit ihre eigenen Abhängigkeiten hat, aktiviert Claude Code auch diese. Die Erfolgsmeldung listet auf, was sonst noch zusammen mit dem Plugin, das Sie benannt haben, aktiviert wurde. Wenn eine Abhängigkeit nicht aktiviert werden kann, weigert sich der Befehl und teilt Ihnen mit, was blockiert und wie Sie es beheben können:

Bedingung Ergebnis
Eine Abhängigkeit ist nicht installiert Die Aktivierung schlägt fehl und druckt den claude plugin install-Befehl für jede fehlende Abhängigkeit.
Eine Abhängigkeit wird durch die Plugin-Richtlinie Ihrer Organisation blockiert Die Aktivierung schlägt fehl und benennt die blockierte Abhängigkeit.
Eine Abhängigkeit ist auf false in einem Bereich mit höherer Priorität als der Zielbereich gesetzt Die Aktivierung schlägt fehl. Aktivieren Sie die Abhängigkeit in diesem Bereich, oder übergeben Sie --scope, um dort zu schreiben.
Alle Abhängigkeiten sind installiert und zulässig Die Aktivierung ist erfolgreich und schreibt true für das Plugin und jede Abhängigkeit, die im Zielbereich noch nicht aktiviert war.

Dies gilt auch, wenn eine Abhängigkeit defaultEnabled: false in ihrem Manifest setzt, da Claude Code ein explizites true dafür schreibt. Dasselbe gilt bei der Installation: Eine Abhängigkeit, die zur Erfüllung eines aktiven Plugins hinzugezogen wird, wird mit true installiert, unabhängig von ihrem eigenen Standard.

Wenn Sie ein Plugin deaktivieren, weigert sich Claude Code, wenn ein anderes aktiviertes Plugin immer noch davon abhängt. Der Fehler benennt die Plugins, die davon abhängen, und gibt Ihnen einen verketteten Befehl, der sie in der richtigen Reihenfolge deaktiviert, endend mit dem, das Sie angefordert haben.

Wenn beispielsweise deploy-kit von secrets-vault abhängt, schlägt das Deaktivieren von secrets-vault allein mit einer Ausgabe ähnlich der folgenden fehl:

secrets-vault is still required by deploy-kit. Disable that plugin first, or
disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools

Kopieren Sie den verketteten Befehl aus dem Fehler, um den vollständigen Satz in einem Schritt zu deaktivieren.

Verwaiste automatisch installierte Abhängigkeiten entfernen

Automatisch installierte Abhängigkeiten bleiben auf der Festplatte, nachdem die Plugins, die sie installiert haben, deinstalliert werden, falls Sie ein abhängiges Plugin neu installieren oder die Abhängigkeit direkt weiterhin verwenden möchten. Um sie zu bereinigen, führen Sie claude plugin prune aus, um die automatisch installierten Abhängigkeiten aufzulisten, die kein installiertes Plugin mehr benötigt, und entfernen Sie sie nach einer Bestätigungsaufforderung.

claude plugin prune

Wenn nichts zur Entfernung qualifiziert ist, gibt der Befehl Nothing to prune mit dem Grund aus und beendet sich. Dies ist die erwartete Ausgabe bei einer Neuinstallation, kein Fehler.

Standardmäßig arbeitet prune im Benutzerbereich und fragt vor dem Entfernen um Bestätigung:

  • --scope project oder --scope local zielt auf einen anderen Bereich ab.
  • --dry-run listet auf, was entfernt würde, ohne etwas zu ändern.
  • -y überspringt die Bestätigungsaufforderung. Wenn stdin oder stdout kein Terminal ist, listet prune die verwaisten Abhängigkeiten auf und beendet sich, ohne sie zu entfernen, es sei denn, Sie übergeben -y.

Um als Teil einer Deinstallation zu bereinigen, übergeben Sie --prune an claude plugin uninstall. Nach dem Entfernen des benannten Plugins scannt Claude Code nach automatisch installierten Abhängigkeiten, die jetzt verwaist sind, und entfernt sie. Plugins, die Sie selbst installiert haben, werden niemals bereinigt, nur diejenigen, die automatisch durch das dependencies-Array eines anderen Plugins installiert wurden.

Das gleiche Bestätigungsverhalten gilt. Wenn stdin oder stdout kein Terminal ist, wird die Deinstallation trotzdem abgeschlossen, aber der Bereinigungsschritt listet die verwaisten Abhängigkeiten auf und entfernt nichts, es sei denn, Sie übergeben -y.

Um beispielsweise deploy-kit zu deinstallieren und die Abhängigkeiten zu bereinigen, die es hinterlässt:

claude plugin uninstall deploy-kit --prune

Abhängigkeitsfehler beheben

Abhängigkeitsprobleme erscheinen in claude plugin list und in der /plugin-Schnittstelle als beschreibende Fehlermeldungen anstelle der wörtlichen Codes in dieser Tabelle. Claude Code deaktiviert das betroffene Plugin, bis Sie den Fehler beheben. Die Tabelle unten listet die häufigsten Fehler und deren Behebung auf.

Fehler Bedeutung Wie zu beheben
dependency-unsatisfied Eine deklarierte Abhängigkeit ist nicht installiert, oder sie ist installiert, aber deaktiviert. Führen Sie den claude plugin install-Befehl aus, der in der Fehlermeldung angezeigt wird. Wenn der Marketplace der Abhängigkeit noch nicht konfiguriert ist, fügen Sie ihn mit claude plugin marketplace add hinzu und Claude Code löst die Abhängigkeit automatisch auf. Wenn die Abhängigkeit deaktiviert ist, aktivieren Sie sie.
range-conflict Die Versionsanforderungen für eine Abhängigkeit können nicht kombiniert werden. Die Fehlermeldung benennt die Ursache: Keine Version erfüllt alle Bereiche, ein Bereich ist keine gültige Semver-Syntax, oder die kombinierten Bereiche sind zu komplex zum Schneiden. Deinstallieren oder aktualisieren Sie eines der in Konflikt stehenden Plugins, beheben Sie alle ungültigen version-Strings, vereinfachen Sie lange ||-Ketten, oder bitten Sie den vorgelagerten Autor, seine Beschränkung zu erweitern.
dependency-version-unsatisfied Die Version der installierten Abhängigkeit liegt außerhalb des deklarierten Bereichs dieses Plugins. Führen Sie claude plugin install <dependency>@<marketplace> aus, um die Abhängigkeit gegen alle aktuellen Beschränkungen neu aufzulösen.
no-matching-tag Das Repository der Abhängigkeit hat kein {name}--v*-Tag, das den Bereich erfüllt. Überprüfen Sie, dass die vorgelagerte Stelle Versionen mit der obigen Konvention getaggt hat, oder lockern Sie Ihren Bereich.

Um diese Fehler programmgesteuert zu überprüfen, führen Sie claude plugin list --json aus. Plugins mit Problemen enthalten ein errors-Feld, das diese auflistet. Plugins, die sauber geladen wurden, lassen das Feld weg.

Siehe auch