ASDF-Manager
Dieser Skill ermöglicht es Agenten, Projekt-Tool-Versionen und Abhängigkeiten mit asdf zu verwalten. Er kümmert sich um das Erstellen und Aktualisieren von .tool-versions-Dateien, installiert und aktualisiert Plugins und setzt wichtige Sicherheitsvorkehrungen bei der Installation von Drittanbieter-Plugins durch.
Wann verwenden
- Wenn ein Projekt
asdfzur Verwaltung von Laufzeitumgebungen verwendet (z. B. Node.js, Python, Ruby, Go, Elixir, Rust). - Wenn eine
.tool-versions-Datei im Repository vorhanden ist oder der Benutzer eine Multi-Laufzeit-Versionierung einrichten möchte. - Wenn der Benutzer bittet, „alle Tools zu aktualisieren“ oder ein Tool auf seine „neueste“ Version zu setzen.
- Wenn der Benutzer ein neues Entwicklungs-Tool, eine Sprachlaufzeit oder ein Dienstprogramm hinzufügen möchte, das über
asdfverwaltet werden kann.
Wann nicht verwenden
- Wenn das Projekt explizit für die Verwendung eines anderen Paket-/Laufzeitmanagers konfiguriert ist (wie
mise,fnm,nvm,pyenv,rbenv,gvmoderasdf-vmnicht installiert/gewünscht ist). - Bei der Installation von Paketen, die über systemweite Paketmanager (wie
brew,apt,pacmanoderdnf) verwaltet werden sollten und keine projektbezogene Versionssperrung erfordern.
Eingaben
| Eingabe | Erforderlich | Beschreibung |
|---|---|---|
| Tool-Name | Ja | Der Name der Laufzeit oder des Tools (z. B. nodejs, python, golang). |
| Version | Nein | Die spezifische zu setzende oder zu installierende Version (z. B. 18.16.0, latest, system). |
| Aktion | Ja | Die auszuführende Operation: update-all, install-tool, set-version oder add-plugin. |
| Global | Nein | Auf true setzen, um die Konfiguration global ($HOME/.tool-versions) statt im lokalen Projektverzeichnis anzuwenden. |
Arbeitsablauf
Schritt 1: ASDF-Umgebung erkennen und validieren
Bevor asdf-Befehle ausgeführt werden, überprüfen Sie, ob asdf in der aktuellen Shell-Umgebung des Agenten installiert und zugänglich ist:
- Führen Sie
which asdfoderasdf --versionaus. - Wenn
asdfnicht gefunden wird, überprüfen Sie gängige Installationspfade (wie$HOME/.asdf/bin/asdfoder/opt/homebrew/bin/asdf). Wenn es installiert, aber nicht eingebunden ist, leiten Sie den Benutzer an, wie es eingebunden wird. - Wenn
asdfvollständig im System fehlt, muss der Skill vorzeitig beendet werden und den Benutzer informieren: "Bitte installieren Sie es von https://asdf-vm.com/guide/getting-started.html"- Warum: Der Skill kann ohne die installierte
asdf-Hauptdatei nicht fortfahren. Ein frühzeitiger Abbruch mit einem hilfreichen Installationslink sorgt für eine reibungslose Benutzereinrichtung.
- Warum: Der Skill kann ohne die installierte
Schritt 2: Anfragen zum "Aktualisieren aller Tools" bearbeiten
Wenn der Benutzer bittet, alle Tools auf die neueste Version zu aktualisieren:
- Suchen Sie die
.tool-versions-Datei (normalerweise im Projektstammverzeichnis oder in übergeordneten Verzeichnissen). - Lesen Sie die Liste der in der
.tool-versions-Datei definierten Tools. - Führen Sie für jedes gefundene Tool den folgenden Befehl aus, um die neueste Version automatisch aufzulösen und zu schreiben:
asdf set <tool-name> latest- Warum: Die Verwendung von
asdf set <tool-name> latestist präziser und robuster als die manuelle Bearbeitung von.tool-versions, da esasdfveranlasst, die tatsächliche, aufgelöste, neueste verfügbare Version abzurufen, bei Bedarf herunterzuladen/zu kompilieren und die exakte statische Versionszeichenfolge zurück in die.tool-versions-Datei zu schreiben.
- Warum: Die Verwendung von
Schritt 3: Plugins suchen und hinzufügen (Community-Index-Prüfung)
Wenn der Benutzer die Installation eines Tools/Plugins anfordert:
- Überprüfen Sie zunächst, ob das Plugin bereits installiert ist:
Wenn es bereits installiert ist, fahren Sie mit Schritt 5 fort.asdf plugin list - Wenn das Plugin nicht installiert ist, überprüfen Sie, ob es im offiziellen
asdf-Community-Index vorhanden ist:
Filtern oder durchsuchen Sie die Ausgabe nach dem gewünschten Tool-Namen.asdf plugin list all- Warum: Die Überprüfung des Community-Index stellt sicher, dass nur kuratierte und geprüfte Plugins installiert werden. Drittanbieter-Plugins außerhalb des offiziellen Index haben die Möglichkeit, benutzerdefinierte Hook-Skripte auszuführen und ungeprüfte Binärdateien auf dem Hostsystem zu kompilieren/installieren.
Schritt 4: Strenge Sicherheitsprüfung für benutzerdefinierte/Nicht-Community-Plugins
Wenn das angeforderte Tool NICHT im offiziellen Community-Index (asdf plugin list all-Ausgabe) vorhanden ist:
- Leiten Sie den Agenten an, online zu suchen (z. B. über Suchmaschinen, GitHub oder Dokumentation), um die korrekte, legitime Quell-Repository-URL für das
asdf-Plugin zu finden. - FAHREN SIE NICHT fort, das benutzerdefinierte Plugin ohne explizite Benutzererlaubnis zu installieren. Dies ist eine kritische Sicherheitsgrenze.
- Formulieren Sie eine strukturierte Genehmigungsanfrage an den Benutzer, die Folgendes enthält:
- Eine klare Warnung, dass das Plugin nicht in der offiziellen
asdf-Community-Repository-Liste enthalten ist. - Die genaue Repository-URL, die für das Plugin gefunden wurde (z. B.
https://github.com/someone/asdf-mytool). - Eine Warnung über die Sicherheitsimplikationen von Drittanbieter-Plugins (die während der Installation/Nutzung beliebigen Shell-Code ausführen können).
- Eine explizite Aufforderung zur Erlaubnis zur Fortsetzung der Installation.
- Eine klare Warnung, dass das Plugin nicht in der offiziellen
- Wenn und nur wenn der Benutzer zustimmt, fahren Sie mit dem Hinzufügen des benutzerdefinierten Plugins über die verifizierte URL fort:
asdf plugin add <tool-name> <plugin-url>
Schritt 5: Tool-Version installieren und setzen
Sobald das Plugin installiert/hinzugefügt ist:
- Wenn der Benutzer eine bestimmte Version angefordert hat, installieren Sie diese:
Andernfalls installieren Sie die neueste Version:asdf install <tool-name> <version>asdf install <tool-name> latest - Schreiben Sie die Version in die Projektkonfiguration:
- Für lokale Projektversionierung (Standard):
asdf set <tool-name> <version-or-latest> - Für globale benutzerbezogene Versionierung:
asdf set -u <tool-name> <version-or-latest>
- Für lokale Projektversionierung (Standard):
- Führen Sie
asdf reshimnach der Installation aus, um sicherzustellen, dass alle Shims aktualisiert werden und das neu installierte ausführbare Programm sofort verwendbar ist.
Validierung
- Führen Sie
asdf currentaus, um zu überprüfen, ob die neu gesetzten Tool-Versionen aktiv sind und im Verzeichnis korrekt aufgelöst werden. - Stellen Sie sicher, dass die Datei
.tool-versionsmit den konfigurierten Tools und Versionen übereinstimmt. - Überprüfen Sie, dass benutzerdefinierte Plugins außerhalb des offiziellen Index nur nach expliziter Benutzerbestätigung installiert wurden.
Häufige Fallstricke
| Fallstrick | Lösung |
|---|---|
asdf: command not found in der Agent-Shell | asdf ist wahrscheinlich installiert, aber in der aktiven Shell nicht eingebunden. Finden Sie asdf.sh (z. B. unter /opt/homebrew/opt/asdf/libexec/asdf.sh oder $HOME/.asdf/asdf.sh) und binden Sie es ein, oder fügen Sie /shims dynamisch im Agent-Kontext zu $PATH hinzu. |
| Tool-Ausführbare Datei läuft nach der Installation nicht | Führen Sie asdf reshim aus, um die Shims-Verzeichnis-Wrapper neu zu generieren, damit die Shell die neue Binärdatei finden kann. |
| Installation schlägt aufgrund fehlender Kompilierungswerkzeuge fehl | Sprachen wie Ruby, Python und Erlang, die mit asdf aus dem Quellcode kompiliert werden, benötigen lokale Build-Abhängigkeiten (wie gcc, openssl, make, libyaml usw.). Teilen Sie dem Benutzer mit, welche Abhängigkeiten basierend auf den Build-Protokollen fehlen. |
| Nicht interaktive Shell blockiert bei interaktiven Eingabeaufforderungen | Stellen Sie sicher, dass asdf-Befehle nicht interaktiv ausgeführt werden oder Abhängigkeiten vorab erfüllt sind. |