Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Arbeitsabläufe ## Transformationen ausführen In diesem Abschnitt werden die verschiedenen Methoden zur Ausführung von Transformationen und die Optionen zur Steuerung des Ausführungsverhaltens beschrieben. ### Ausführungsmodi AWS Transform custom unterstützt drei Ausführungsmodi, um unterschiedlichen Workflows gerecht zu werden. **Interaktiver Konversationsmodus ** Starten Sie die CLI mit `atx` und bitten Sie den Agenten, eine Transformation in natürlicher Sprache durchzuführen. In diesem Modus können Sie ein vollständiges Gespräch mit dem Agenten führen, die Ausführung jederzeit unterbrechen und während des Transformationsprozesses Feedback geben. Verwenden Sie diesen Modus, wenn Sie maximale Kontrolle und die Möglichkeit haben möchten, den Agenten durch komplexe Szenarien zu führen. **Direkte interaktive Ausführung ** Wird verwendet`atx custom def exec -n -p `, um eine bestimmte Transformation interaktiv zu starten. In diesem Modus können Sie den Agenten zu Beginn, während oder am Ende der Ausführung überprüfen und mit ihm interagieren. Der Agent macht an wichtigen Entscheidungspunkten eine Pause und bittet Sie um Ihre Eingabe. Dies ist ideal, um Transformationen zu testen und zu verfeinern, bevor sie autonom ausgeführt werden. Sie können Transformationen im nicht interaktiven Modus oder im Headless-Modus ausführen. Non-interactive Im Modus werden Eingabeaufforderungen während einer benannten Transformation unterdrückt. Im Headless-Modus können Sie den Agenten mit einer Klartext-Eingabeaufforderung ausführen und dabei die interaktive Oberfläche vollständig umgehen. #### Non-interactive Modus `atx custom def exec -n -p -x -t`Für vollständige Automatisierung verwenden. Fügen Sie hinzu, `-x` um im nicht interaktiven Modus `-t` zu arbeiten und allen Tools automatisch ohne Aufforderung zu vertrauen. Dieser Modus ist für die CI/CD Pipeline-Integration und Massenausführung konzipiert, bei denen kein menschliches Eingreifen möglich oder erwünscht ist. #### Headless-Modus Um Aufgaben auszuführen, ohne mit dem Agenten zu interagieren, führen Sie Ihre Anweisungen aus `atx -x "" -t` und geben Sie sie im Klartext ein. ##### Ausführung der Transformation ohne Zwischenablösung Verwenden Sie diesen Modus, um eine vorhandene Transformationsdefinition auf Ihre Codebasis anzuwenden. Die Transformation führt jeden Schritt automatisch aus, ohne dass Ihre Zustimmung erforderlich ist. ``` atx -x "apply transformation definition to " -t ``` ##### Kopflose Transformationsentwicklung Erstellen oder ändern Sie Transformationsdefinitionen. Führen Sie den folgenden Befehl aus, um eine ältere Transformationsdefinition in das neue Skill-Format (SKILL.md \+ references/) zu konvertieren: ``` atx -x "convert transformation definition to skill and save as draft" -t ``` Führen Sie den folgenden Befehl aus, um eine neue Transformationsdefinition zu erstellen: ``` atx -x "create a transformation definition to with references docs " -t ``` ### Allgemeine Befehls-Flags Bei der Ausführung von Transformationen mit `atx custom def exec` werden häufig die folgenden Flags verwendet: + `-n`oder `--transformation-name` — Gibt den Namen der auszuführenden Transformation an + `-p`oder `--code-repository-path` — Gibt den Pfad zu Ihrer Codebasis an (verwenden Sie „.“ für das aktuelle Verzeichnis) + `-c`oder `--build-command` — Gibt den auszuführenden Build- oder Validierungsbefehl an + `-x`oder `--non-interactive` — Aktiviert den nicht interaktiven Modus (keine Benutzeraufforderungen) + `-t`oder `--trust-all-tools` — vertraut automatisch allen Tools, ohne dass Sie dazu aufgefordert werden + `-d`oder `--do-not-learn` — verhindert das Extrahieren von Lektionen aus dieser Ausführung + `--tv`oder `--transformation-version` — Gibt eine bestimmte Version der Transformation an + `-g`oder `--configuration` — Stellt eine Konfigurationsdatei oder eine Inline-Konfiguration bereit **Wichtig** Das `-t` `--trust-all-tools` Oder-Flag genehmigt automatisch alle Toolausführungen ohne Aufforderung und umgeht die meisten Sicherheitsvorkehrungen (Befehle, die Ihrer `alwaysPromptCommands` Liste entsprechen, benötigen immer noch eine ausdrückliche Genehmigung, sofern sie nicht überschrieben werden). `trustedShellCommands` Das Weitergeben `--non-interactive` und `--trust-all-tools` ist für eine vollständig autonome Bedienung erforderlich, aber nicht für die Ausführung der Transformation erforderlich. In Produktionsumgebungen mit Vorsicht verwenden. ### Verwenden von Konfigurationsdateien AWS Transform custom unterstützt optionale Konfigurationsdateien im YAML- oder JSON-Format. Mit Konfigurationsdateien können Sie Ausführungsparameter angeben und dem Agenten zusätzlichen Kontext zur Verfügung stellen. **Um eine Konfigurationsdatei zu verwenden: ** ``` atx custom def exec --configuration file://config.yaml ``` Sie können die Konfiguration auch als Inline-Schlüssel-Wert-Paare bereitstellen: ``` atx custom def exec --configuration "key=value,key2=value2" ``` **Beispiel für eine Konfigurationsdatei (config.yaml): ** ``` codeRepositoryPath: ./my-project transformationName: my-transformation buildCommand: mvn clean install additionalPlanContext: | The target Java version to upgrade to is Java 17. Ensure compatibility with our internal logging framework version 2.3. validationCommands: | mvn test mvn verify ``` Der `additionalPlanContext` Parameter bietet zusätzlichen Kontext für den Ausführungsplan des Agenten. Dies ist besonders nützlich bei AWS verwalteten Transformationen, um ihr Verhalten an Ihre spezifischen Bedürfnisse anzupassen. ### Befehle zum Erstellen und Validieren Der Befehl Build oder Validation ist ein optionaler Parameter, der angibt, wie Ihr Code während des Transformationsprozesses überprüft werden soll. AWS Transform custom versucht, den besten Build-Befehl auf der Grundlage der Transformation abzuleiten, falls dieser nicht angegeben ist. Es wird jedoch empfohlen, aus Qualitätsgründen einen spezifischen Build-Befehl zu verwenden. **Beispiele für Build- und Validierungsbefehle: ** + Java: `mvn clean install` oder `gradle build` + Python: `pytest` oder `python -m py_compile` + Node.js: `npm run build` oder `npm test` + Linters: oder `eslint .` `pylint .` Selbst für Sprachen oder Transformationen, für die keine Erstellung erforderlich ist, ist es sehr wichtig, einen Befehl bereitzustellen, der die Ergebnisse validiert und Probleme zurückgibt, falls die Validierung fehlschlägt, um die Transformationsqualität zu verbessern. Wenn kein Build oder keine Validierung erforderlich ist, lassen Sie ihn in Ihrer Eingabe weg. ### Steuerung des Lernverhaltens Standardmäßig extrahiert AWS Transform benutzerdefiniert Lektionen aus jeder Transformationsausführung. Sie können das Lernen für bestimmte Ausführungen verhindern. **Um zu verhindern, dass aus einer Ausführung gelernt wird: ** ``` atx custom def exec -n my-transformation -p ./my-project -d ``` Das `-d` `--do-not-learn` Oder-Flag deaktiviert das Extrahieren von Lektionen aus der aktuellen Ausführung. ### Konversationen wieder aufnehmen AWS Mit der Option Benutzerdefiniert transformieren können Sie frühere Konversationen innerhalb von 30 Tagen nach der Erstellung wieder aufnehmen. **Um die letzte Konversation fortzusetzen: ** ``` atx --resume ``` **Um eine bestimmte Konversation fortzusetzen: ** ``` atx --conversation-id ``` **Wichtig** Konversationen können nur innerhalb von 30 Tagen nach der Erstellung wieder aufgenommen werden. Nach 30 Tagen kann die Konversation nicht mehr wieder aufgenommen werden. ### Minuten des Tracking-Agenten AWS Transform Custom verfolgt die Minuten, die [ Agenten während einer Transformationssitzung ](https://aws.amazon.com/transform/pricing/) verbraucht haben. Agentenminuten sammeln sich während des gesamten Gesprächszyklus an und werden angezeigt, wenn die Konversation endet: ``` Agent minutes used: 12.50 ``` Die Minuten des Agenten bleiben auch bei Unterbrechungen bestehen. Wenn Sie eine Sitzung mit Strg\+C unterbrechen und sie später fortsetzen, werden die zuvor gesammelten Minuten übernommen und sammeln sich in der wiederaufgenommenen Sitzung weiter an. **So überprüfen Sie die Agentenminuten während einer interaktiven Sitzung: ** Geben Sie `/usage` an der Eingabeaufforderung ein, um die aktuell gesammelten Agentenminuten anzuzeigen, ohne die Konversation zu beenden. **So legen Sie ein Budgetlimit für Agentenminuten fest: ** ``` atx custom def exec -n my-transformation -p ./my-project --limit 30 ``` `--limit`Mit dieser Option wird ein maximales [ Budget für ](https://aws.amazon.com/transform/pricing/) Agentenminuten für die Sitzung festgelegt. Die Agentenminuten geben die Arbeitszeit des aktiven Agenten an, nicht die Uhrzeit an der Uhr. Wenn das Limit erreicht ist, zeigt die CLI eine Meldung an und beendet das Programm mit Anweisungen zum Fortfahren: ``` ⚠️ Budget limit reached: 30.00 / 30.00 Agent Minutes. Exiting. ``` Sie können die Konversation später mit einem erhöhten Limit fortsetzen: ``` atx --conversation-id -t --limit ``` ## Kontinuierliches Lernen In diesem Abschnitt wird beschrieben, wie Sie die durch kontinuierliches Lernen gewonnenen Erkenntnisse überprüfen und verwalten können. ### Lektionen verstehen Das System für kontinuierliches Lernen extrahiert automatisch Lektionen aus früheren Durchläufen einer Transformation. Das System erstellt sie asynchron auf der Grundlage von: + Das Feedback der Entwickler wird im interaktiven Modus bereitgestellt + Bei Transformationen sind Codeprobleme aufgetreten Die Lektionen sammeln sich im Laufe der Zeit an, wenn Sie die Transformation in verschiedenen Codebasen ausführen. Das System wendet sie automatisch an, um zukünftige Läufe zu verbessern. Jede Lektion gehört zu einer Kategorie, die alle Lektionen aus einem ähnlichen Bereich enthält, sodass Sie verwandte Lektionen gemeinsam durchgehen können. Für Lektionen, die Sie nicht verwenden möchten, können Sie die Lektion archivieren oder vollständig löschen. ### Lektionen ansehen und verwalten Verwenden Sie den `learnings` Befehl, um eine interaktive Sitzung zum Durchsuchen und Verwalten der Lektionen einer Transformationsdefinition zu öffnen. **So öffnen Sie den Lektionen-Viewer: ** ``` atx custom def learnings -n my-transformation ``` Der Viewer öffnet sich mit einer Liste von Lektionskategorien, von denen jede zeigt, wie viele aktive Lektionen sie enthält. Wählen Sie eine Kategorie aus, um ihre Lektionen zu sehen, und wählen Sie dann eine Lektion aus, um alle Details zu sehen, einschließlich des Haupttextes der Lektion, ihrer Auswirkungen und der Anzahl früherer Durchläufe. ### Lektionen archivieren und wiederherstellen Das System wendet die Lektionen automatisch an. Wenn Sie nicht möchten, dass das System eine Lektion anwendet, können Sie sie archivieren. Das System behält archivierte Lektionen bei, wendet sie jedoch nicht auf zukünftige Läufe an. Alle archivierten Lektionen sind in Gruppen zusammengefasst, sodass Sie sie überprüfen und wieder aktiv verwenden können. ### Lektionen löschen Eine Lektion, die nicht nützlich ist, dauerhaft entfernen. Das Löschen kann nicht rückgängig gemacht werden, und das System lernt eine gelöschte Lektion möglicherweise bei zukünftigen Läufen erneut. Eine Lektion muss archiviert werden, bevor sie gelöscht werden kann. ## Erweiterte Konfiguration In diesem Abschnitt werden erweiterte Funktionen und Konfigurationsoptionen für AWS Transform custom beschrieben. ### Umgebungsvariablen Sie können das CLI-Verhalten mithilfe von Umgebungsvariablen anpassen. **Anmerkung** Die folgenden Beispiele zeigen die Linux- und macOS-Syntax (`export`). Stellen Sie unter Windows die Umgebungsvariablen in PowerShell using ein`$env:{{NAME}}="{{value}}"`. Die entsprechenden Befehle finden Sie auf den ** Windows (PowerShell) ** -Registerkarten. **ATX\_SHELL\_TIMEOUT ** Überschreibt das Standard-Timeout für Shell-Befehle (900 Minuten). seconds/15 ------ #### [ Linux and macOS ] ``` export ATX_SHELL_TIMEOUT=1800 # 30 minutes ``` ------ #### [ Windows (PowerShell) ] ``` $env:ATX_SHELL_TIMEOUT=1800 # 30 minutes ``` ------ Dies ist nützlich für große Codebasen oder lang andauernde Build-Prozesse. **ATX\_DISABLE\_UPDATE\_CHECK ** Deaktivieren Sie automatische Versionsprüfungen und Aktualisierungsbenachrichtigungen während der Befehlsausführung. ------ #### [ Linux and macOS ] ``` export ATX_DISABLE_UPDATE_CHECK=true ``` ------ #### [ Windows (PowerShell) ] ``` $env:ATX_DISABLE_UPDATE_CHECK="true" ``` ------ **ATX\_GIT\_COMMITTER\_NAME und ATX\_GIT\_COMMITTER\_EMAIL ** Konfiguriere die Autoren-Identität, die für die Checkpoint-Commits verwendet wird, die Transform custom in deinem Repository erstellt, wenn Änderungen während einer Transformation übernommen werden. AWS Wenn diese Variablen nicht gesetzt sind, werden Checkpoint-Commits einer Standardidentität () zugeordnet. `ATX Bot ` Setzen Sie beide Variablen so, dass Checkpoints einem bestimmten Autor zugeordnet werden. ------ #### [ Linux and macOS ] ``` export ATX_GIT_COMMITTER_NAME="Jane Developer" export ATX_GIT_COMMITTER_EMAIL="jane@example.com" ``` ------ #### [ Windows (PowerShell) ] ``` $env:ATX_GIT_COMMITTER_NAME="Jane Developer" $env:ATX_GIT_COMMITTER_EMAIL="jane@example.com" ``` ------ ### Einstellungen vertrauen Mithilfe der Vertrauenseinstellungen können Sie bestimmte Tools und Befehle vorab genehmigen, sodass sie ohne Aufforderung ausgeführt werden. Sie können auch unabhängig von der Vertrauensstufe eine ausdrückliche Genehmigung für bestimmte Shell-Befehle verlangen. Diese Einstellungen werden in der `~/.aws/atx/trust-settings.yaml` Datei konfiguriert. Die Datei enthält drei Listen: + `trustedTools`- Tools, die ohne Aufforderung ausgeführt werden können + `trustedShellCommands`- Shell-Befehle, die ohne Aufforderung ausgeführt werden können + `alwaysPromptCommands`- Shell-Befehlsmuster, für die eine ausdrückliche Genehmigung erforderlich ist, sofern sie nicht überschrieben werden`trustedShellCommands`, unabhängig vom `-t` Flag oder der Sitzungsvertrauensstellung. Diese Muster werden im nicht interaktiven Modus () nicht erzwungen. `-x` **Vertrauenswürdige Standardtools: ** + `file_read` + `get_transformation_from_registry` + `list_available_transformations_from_registry` **Vertrauenseinstellungen bearbeiten: ** Sie können die Datei trust-settings.yaml manuell bearbeiten, um vertrauenswürdige Tools und Befehle hinzuzufügen oder zu entfernen. Beide `trustedShellCommands` und unterstützen Glob-Platzhaltermuster unter Verwendung von. `alwaysPromptCommands` `*` **Anmerkung** Wenn ein Befehl mit beiden Listen übereinstimmt, `trustedShellCommands` hat er Priorität. Im Folgenden werden die einzelnen Befehlslisten beschrieben und es werden Beispiele bereitgestellt: + `trustedShellCommands`- Befehle, die diesen Mustern entsprechen, werden ohne Aufforderung ausgeführt und umgehen alle anderen Leitplanken. Muster werden mit der vollständigen Befehlszeichenfolge abgeglichen. Beispiele: + `cd *`- Entspricht zusammengesetzten Befehlen, die mit cd beginnen + `*&&*`- Vertraut allen Befehlen mit &&-Operatoren + `alwaysPromptCommands`- Befehle, die diesen Mustern entsprechen, benötigen eine ausdrückliche Genehmigung, sofern sie nicht überschrieben werden`trustedShellCommands`, unabhängig vom `-t` Flag oder der Sitzungsvertrauensstellung. Diese Muster werden im nicht interaktiven Modus () nicht erzwungen. `-x` Muster werden mit jedem Unterbefehl in zusammengesetzten Ausdrücken (`&&`,`||`, Befehlsersetzungen) abgeglichen. Beispiele: + `rm -rf *`- Fordert immer zur Eingabe rekursiver Befehle zum Erzwingen des Löschens auf + `sudo *`- Fordert immer nach Befehlen auf, die mit sudo ausgeführt werden + `find * -exec *`- Fordert immer nach Suchbefehlen mit -exec **Session-level vertraue: ** Bei interaktiven Eingabeaufforderungen können Sie wählen: + `(y)es`- Einmal ausführen + `(n)o`- Ablehnen + `(t)rust`- Vertrauen Sie nur für die aktuelle Sitzung Session-level Vertrauenseinstellungen sind temporär und werden beim Neustart der CLI zurückgesetzt. Dadurch wird eine vorübergehende Genehmigung gewährt, ohne dass trust-settings.yaml dauerhaft geändert wird. **Anmerkung** Sitzungsvertrauen ist für Befehle, die Ihrer Liste entsprechen, nicht verfügbar. `alwaysPromptCommands` ### Model Context Protocol (MCP) -Server Die AWS Transform CLI unterstützt MCP-Server (Model Context Protocol), die ihre Funktionalität um zusätzliche Tools erweitern. **Konfiguration: ** Konfigurieren Sie die MCP-Server in der `~/.aws/atx/mcp.json` Datei. Die AWS Transform CLI unterstützt zwei Arten von MCP-Servern: lokale befehlsbasierte Server und Remote-HTTP-Server. **Lokale befehlsbasierte Server: ** Lokale Server werden als untergeordnete Prozesse auf Ihrem Computer ausgeführt. Konfigurieren Sie sie mit der `command` Eigenschaft: ``` { "mcpServers": { "my-local-server": { "command": "npx", "args": ["-y", "@example/mcp-server"] } } } ``` **Entfernte HTTP-Server: ** Remoteserver stellen eine Verbindung zu MCP-Servern her, die unter einer HTTP- oder HTTPS-URL gehostet werden. Konfigurieren Sie sie mit der `url` Eigenschaft: ``` { "mcpServers": { "my-remote-server": { "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${MCP_API_TOKEN}" } } } } ``` Die `headers` Eigenschaft ist optional und unterstützt die Erweiterung von Umgebungsvariablen mithilfe der `${VAR_NAME}` Syntax. Auf diese Weise können Sie vertrauliche Werte wie API-Token in Umgebungsvariablen und nicht in der Konfigurationsdatei speichern. **Eigenschaften der Konfiguration: ** Lokale befehlsbasierte Server unterstützen die folgenden Eigenschaften: + `command`(erforderlich) — Der Befehl zum Ausführen des Servers + `args`(optional) — Array von Befehlszeilenargumenten + `env`(optional) — Umgebungsvariablen, die an den Serverprozess übergeben werden Remote-HTTP-Server unterstützen die folgenden Eigenschaften: + `url`(erforderlich) — Die HTTP- oder HTTPS-URL des Remote-MCP-Servers + `headers`(optional) — HTTP-Header, die in Anfragen aufgenommen werden sollen, mit Unterstützung für die Erweiterung von `${VAR_NAME}` Umgebungsvariablen **Verwaltung von MCP-Servern: ** Liste der konfigurierten MCP-Server anzeigen: ``` atx mcp tools ``` Liste der verfügbaren Tools, die von einem bestimmten MCP-Server angeboten werden: ``` atx mcp tools --server ``` **Nachverfolgung der Nutzung: ** Die CLI verfolgt automatisch die Nutzung des MCP-Tools während der Ausführung von Transformationen. Nutzungsstatistiken werden wie `mcp_usage.json` im nebenstehenden Konversationsverzeichnis gespeichert. `metadata.json` Die Datei zeichnet Kennzahlen pro Tool für jede Ausführung auf, darunter: + Anzahl der Aufrufe pro Tool + Anzahl der Fehler pro Tool + Gesamtausführungszeit pro Tool + Letzte Fehlerdetails (falls vorhanden) ### Client-Side Fähigkeiten Client-side Fähigkeiten sind zusätzliche Fähigkeiten, die den Agenten bei der Ausführung von Transformationen erweitern. Sie ermöglichen es Ihnen, benutzerdefinierte Tools, Skripts und Anweisungen bereitzustellen, die der Agent zusätzlich zu seinen integrierten Funktionen verwenden kann. **Verzeichnisse zur Entdeckung von Fähigkeiten: ** Fähigkeiten werden in vier Verzeichnissen in der Reihenfolge ihrer Rangfolge erkannt. Wenn ein Skill mit demselben Namen in mehreren Verzeichnissen existiert, hat das erste Verzeichnis in der Liste Vorrang: 1. `/.aws/atx/skills/`- Project-level, AWS Transformieren CLI-specific 1. `/.agents/skills/`- Project-level, mandantenübergreifend (für alle kompatiblen Agententools verfügbar) 1. `~/.aws/atx/skills/`- User-level, Transformieren AWS CLI-specific 1. `~/.agents/skills/`- User-level, mandantenübergreifend (für alle kompatiblen Agententools verfügbar) Die `.aws/atx/skills/` Verzeichnisse sind spezifisch für die AWS Transform CLI. Die `.agents/skills/` Verzeichnisse sind mandantenübergreifend, was bedeutet, dass die dort abgelegten Fähigkeiten allen kompatiblen Agententools außer der AWS Transform CLI zur Verfügung stehen. **Struktur des Skill-Verzeichnisses: ** Jeder Skill ist ein Verzeichnis, das eine `SKILL.md` Datei mit YAML-Frontmatter enthält: ``` ~/.aws/atx/skills/ └── my-skill/ ├── SKILL.md # Required: frontmatter + instructions ├── references/ # Optional: reference docs the agent can read │ └── guide.md └── scripts/ # Optional: scripts the agent can execute └── validate.py ``` **SKILL.md Format: ** ``` --- name: my-skill description: When to use this skill --- # Skill Title Instructions for the agent... ``` Das `name` Feld muss mit dem Namen des übergeordneten Verzeichnisses übereinstimmen. **Einen Skill deaktivieren: ** Um zu verhindern, dass ein Skill geladen wird, ohne seine Dateien `disable-model-invocation: true` zu entfernen, füge dem Titelthema Folgendes hinzu: ``` --- name: my-skill description: When to use this skill disable-model-invocation: true --- ``` Wenn diese Eigenschaft gesetzt ist, überspringt die CLI den Skill während der Erkennung. Der Agent kann den Skill nicht sehen oder verwenden, es sei denn, eine Transformationsdefinition weist ihn ausdrücklich an, die Skill-Datei zu lesen. Verwenden Sie diese Option, um einen Skill vorübergehend zu deaktivieren, ihn als in Bearbeitung zu kennzeichnen oder Referenzmaterial aufzubewahren, das nur für menschliche Leser bestimmt ist. **Anmerkung** Die Dateien eines deaktivierten Skills verbleiben auf der Festplatte. Wenn eine Transformationsdefinition den Agenten anweist, einen bestimmten Dateipfad zu lesen, kann der Agent trotzdem auf den Inhalt zugreifen. Die `disable-model-invocation` Eigenschaft verhindert automatische Erkennung und Kontextinjektion, nicht den Dateisystemzugriff. **Verfügbarkeit der Fähigkeiten je nach Ausführungsmodus: ** + **Exec-Modus ** (`atx custom def exec`mit`--code-repository-path`) — Findet Fähigkeiten aus Verzeichnissen auf Benutzer- und Projektebene. + **Interaktiver Modus ** (`atx`) — Anfänglich werden nur Fähigkeiten auf Benutzerebene entdeckt. Wenn Sie während der Sitzung einen Code-Repository-Pfad angeben, werden auch Fähigkeiten auf Projektebene geladen. **Überprüfung der Entdeckung von Fähigkeiten: ** Überprüfen Sie nach einem Lauf das Debug-Protokoll der CLI, um zu überprüfen, welche Fähigkeiten entdeckt wurden: ------ #### [ Linux and macOS ] ``` grep -i "skill" ~/.aws/atx/logs/debug.log | tail -20 ``` ------ #### [ Windows (PowerShell) ] ``` Select-String -Pattern "skill" "$env:USERPROFILE\.aws\atx\logs\debug.log" | Select-Object -Last 20 ``` ------ Fähigkeiten, bei denen die Validierung fehlschlägt, werden mit einer Warnung in den Debug-Protokollen übersprungen. **Anmerkung** Client-side Fähigkeiten erfordern CLI Version 2.0 oder höher. #### Auswahl zwischen Project-Level und User-Level Fähigkeiten Wo du eine Fähigkeit platzierst, bestimmt, wer davon profitiert und wann sie aktiviert wird. **Project-level Fähigkeiten ** (`/.aws/atx/skills/`): Übergeben Sie diese der Versionskontrolle, sodass jedes Teammitglied, das Transformationen für das Projektarchiv durchführt, sie automatisch erkennt. Nutzen Sie Fähigkeiten auf Projektebene für: + Repository-specific Konformitätsprüfungen (Dockerfile-Regeln, Terraform-Richtlinien, Sicherheitsprüfer für Migrationen) + Organisationsstandards, die für diese Codebasis gelten (Beobachtbarkeitsmuster, Fehlerbehandlung, Namenskonventionen) + Erstellen oder testen Sie projektspezifische Skripts (benutzerdefinierte Zeiger, Architektur-Fitnessfunktionen) + Leitfäden zur API-Migration für interne Bibliotheken, die in diesem Repository verwendet werden **User-level Fähigkeiten ** (`~/.aws/atx/skills/`): Diese verbleiben auf Ihrem Computer und werden bei allen Transformationen aktiviert, unabhängig davon, auf welches Repository Sie abzielen. Verwenden Sie Fähigkeiten auf Benutzerebene für: + Persönliche Workflow-Tools (Changelog-Generatoren, Commit-Nachrichtenformatierer) + Cross-project Einstellungen (bevorzugte Testmuster, Erinnerungen im Dokumentationsstil) + Prüfungen zur Einhaltung der Lizenzbestimmungen, die Ihr Unternehmen für alle Repositorys benötigt + Abdeckungsschwellen oder Qualitätsschranken, die Sie für jede Codebasis, mit der Sie arbeiten, durchsetzen **Tipps für effektive Fähigkeiten: ** + Schreiben Sie klare `description` Felder in Ihre `SKILL.md` Titelseite. Der Agent verwendet dieses Feld, um zu entscheiden, wann eine Fähigkeit relevant ist. + Beenden Sie die Validierungsskripte mit dem Code 0 bei Erfolg und einem Wert ungleich Null bei einem Fehler. Der Agent interpretiert Exit-Codes, um die Einhaltung der Vorschriften festzustellen. + Druckt klare, umsetzbare Fehlermeldungen in Skripten aus. Der Agent liest die Ausgabe, um zu verstehen, was behoben werden muss. + Platzieren Sie Fähigkeiten auf beiden Ebenen im mandantenübergreifenden Verzeichnis (`.agents/skills/`), um sie mit anderen KI-Entwicklungstools außerhalb der AWS Transform CLI zu teilen. #### Client-Side Beispiele für Fähigkeiten Diese Beispiele zeigen zwei gängige Muster: einen skriptbasierten Validierungs-Skill und einen Skill, der nur als Referenz verwendet wird. ##### Beispiel: Dockerfile Compliance Checker () Script-Based Diese Fähigkeit validiert Dockerfiles anhand von bewährten Sicherheits- und Betriebspraktiken. Es verwendet ein Validierungsskript, das der Agent vor und nach Änderungen ausführt. **Verzeichnisstruktur: ** ``` .aws/atx/skills/ └── dockerfile-compliance/ ├── SKILL.md ├── scripts/ │ └── lint_dockerfile.sh └── references/ └── dockerfile-best-practices.md ``` **SKILL.md:** ``` --- name: dockerfile-compliance description: Validates Dockerfiles against security and operational best practices --- # Dockerfile Compliance Checker When a transformation creates or modifies Dockerfiles, run the compliance checker. ## When to use - After creating a new Dockerfile - After modifying FROM, RUN, USER, or EXPOSE directives - When containerizing an application as part of a transformation ## How to use Run: `bash scripts/lint_dockerfile.sh ` If violations are found, consult `references/dockerfile-best-practices.md` for compliant patterns. ``` Das Validierungsskript sucht nach ungepinnten Basis-Image-Tags, die als Root ausgeführt werden, nach fest codierten Geheimnissen in `ENV` Direktiven und nach fehlenden Definitionen. `HEALTHCHECK` Der Agent führt das Skript aus, behebt Verstöße mithilfe von Mustern aus der Referenzdatei und führt das Skript erneut aus, um die Konformität zu bestätigen. ##### Beispiel: API Deprecation Helper () Reference-Only Diese Fähigkeit führt den Agenten durch das Ersetzen veralteter API-Aufrufe bei Upgrade-Transformationen. Es verwendet nur Referenzdateien ohne Skripte. **Verzeichnisstruktur: ** ``` .aws/atx/skills/ └── api-deprecation-helper/ ├── SKILL.md └── references/ ├── aws-sdk-v2-to-v3.md └── react-class-to-hooks.md ``` **SKILL.md:** ``` --- name: api-deprecation-helper description: Guides the agent through replacing deprecated API calls with modern equivalents --- # API Deprecation Helper When performing upgrade transformations, use this skill to identify and replace deprecated API calls with their modern equivalents. ## When to use - During any version upgrade transformation - When build warnings mention deprecated APIs - When transforming code that uses legacy patterns ## Process 1. Identify deprecated API calls in the codebase 2. For each deprecated call, find the replacement in `references/` 3. Apply the replacement, preserving the original behavior 4. Verify the replacement compiles and tests pass ``` Die Referenzdateien enthalten Vorher-Nachher-Codebeispiele. Ordnet beispielsweise `aws-sdk-v2-to-v3.md` Muster wie das modulare v3-Äquivalent mithilfe von und `s3.putObject(params).promise()` zu. `S3Client` `PutObjectCommand` ### Schlagworte und Organisation Sie können Transformationen mit Tags für die Zugriffskontrolle und Kategorisierung organisieren. **Anmerkung** Einige dieser Befehle erfordern die Angabe des Amazon-Ressourcennamens (ARN) für eine Transformationsdefinition. Die ARN-Struktur lautet: `arn:aws:transform-custom:::package/` **Um die Tags für eine Transformation aufzulisten: ** ``` atx custom def list-tags --arn ``` **Um einer Transformation Tags hinzuzufügen: ** ``` atx custom def tag --arn --tags '{"env":"prod","team":"backend"}' ``` **Um Tags aus einer Transformation zu entfernen: ** ``` atx custom def untag --arn --tag-keys "env,team" ``` Tags können für die gruppierte Zugriffskontrolle in IAM-Richtlinien verwendet werden. Sie können Richtlinien erstellen, die Berechtigungen für alle Transformationen mit bestimmten Tags gewähren (z. B. für alle Transformationen, die mit `team:frontend` oder gekennzeichnet sind). `environment:production` ### Protokolle AWS Transform CLI verwaltet drei Arten von Protokollen zur Problembehandlung und zum Debuggen. **Konversationsprotokolle: ** ------ #### [ Linux and macOS ] ``` ~/.aws/atx/custom//logs/-conversation.log ``` ------ #### [ Windows ] ``` %USERPROFILE%\.aws\atx\custom\\logs\-conversation.log ``` ------ Diese Protokolle enthalten den vollständigen Konversationsverlauf für eine bestimmte Sitzung. **Subagent-Protokolle: ** ------ #### [ Linux and macOS ] ``` ~/.aws/atx/custom//logs/subagents/.log ``` ------ #### [ Windows ] ``` %USERPROFILE%\.aws\atx\custom\\logs\subagents\.log ``` ------ Diese Logs enthalten Ausgaben von Subagenten, die der Hauptagent bei Transformationen erzeugt. Sie müssen die Subagenten nicht direkt verwalten. **Debug-Protokolle für Entwickler: ** ------ #### [ Linux and macOS ] ``` ~/.aws/atx/logs/debug*.log ~/.aws/atx/logs/error.log ``` ------ #### [ Windows ] ``` %USERPROFILE%\.aws\atx\logs\debug*.log %USERPROFILE%\.aws\atx\logs\error.log ``` ------ Diese Protokolle enthalten erweiterte Informationen zur Problembehandlung für die CLI selbst. **Anmerkung** Im Protokollverzeichnis befinden sich möglicherweise mehrere Debug-Protokolldateien (z. B. debug1.log, debug2.log). Prüfen Sie alle relevanten Protokolle und stellen Sie sie bereit, z. B. \~/. aws/atx/custom/ /\* und \~/. aws/atx/logs/ \*, beim Öffnen von Support-Tickets zur schnelleren Lösung. ### CLI-Aktualisierungen Halten Sie Ihre CLI auf dem neuesten Stand, um auf neue Funktionen und Verbesserungen zugreifen zu können. **Um nach Updates zu suchen: ** ``` atx update --check ``` **Um auf die neueste Version zu aktualisieren: ** ``` atx update ``` **Um auf eine bestimmte Version zu aktualisieren: ** ``` atx update --target-version ``` ## Erstellen Sie benutzerdefinierte Transformationen In diesem Abschnitt wird beschrieben, wie benutzerdefinierte Transformationsdefinitionen erstellt, geändert und verwaltet werden. ### Eine neue Transformation erstellen Verwenden Sie die interaktive CLI, um eine neue Transformationsdefinition zu erstellen. **Um eine Transformationsdefinition zu erstellen ** 1. Starten Sie die AWS Transform CLI: ``` atx ``` 1. Teilen Sie dem Agenten mit, dass Sie eine neue Transformation erstellen möchten. 1. Geben Sie eine klare, detaillierte Beschreibung des Transformationsziels ein. Schließen Sie ein: + Den Quell- und Zielstatus (z. B. „Upgrade von Version X auf Version Y“) + Spezifische Änderungen erforderlich (z. B. „Importanweisungen aktualisieren, veraltete Methoden ersetzen“) + Irgendwelche besonderen Überlegungen oder Einschränkungen 1. Wenn der Mitarbeiter um Klarstellung oder zusätzliche Informationen bittet, geben Sie konkrete Beispiele und Referenzmaterialien an. 1. Überprüfen Sie die ursprüngliche Transformationsdefinition, die vom Agenten erstellt wurde. 1. Testen Sie die Transformation auf einer Beispielcodebasis. 1. Iterieren Sie, indem Sie Feedback, Codekorrekturen oder zusätzliche Beispiele bereitstellen. 1. Speichern Sie die Transformation lokal oder veröffentlichen Sie sie in der Registrierung. **Bewährte Methoden zum Erstellen von Transformationen: ** + Beginnen Sie mit einfachen, klar definierten Transformationen, bevor Sie komplexe Transformationen versuchen + Stellen Sie umfassende Referenzmaterialien bereit, einschließlich Migrationsleitfäden und Codebeispielen + Testen Sie vor der Veröffentlichung auf mehreren Beispiel-Codebasen + Verwenden Sie deterministische Build- oder Validierungsbefehle, um kontinuierliches Lernen zu ermöglichen + Erwägen Sie, komplexe Transformationen in mehrere kleinere Schritte aufzuteilen + Markieren Sie wichtige Informationen in Ihren Transformationsdefinitionen mit „KRITISCH:“ oder „WICHTIG:“, um sicherzustellen, dass der Agent diese Anforderungen priorisiert + Wenn Sie genaue Anforderungen erfüllen müssen (z. B. bei Verwendung eines bestimmten Befehls oder Zeichenkettenwerts), geben Sie in Ihren Transformationsdefinitionen explizit die vollständige Zeichenfolge an. Sie können diese in Bash-Anführungszeichen einschließen, um deutlich darauf hinzuweisen, dass es sich um Terminalbefehle oder literale Zeichenketten handelt. Dadurch wird die Variabilität reduziert und eine konsistente Ausführung gewährleistet ### Bereitstellung von Referenzmaterialien Sie können Referenzdateien für AWS Transform custom bereitstellen, indem Sie während der Konversation Dateipfade angeben. Diese Dateien werden im `references/` Ordner der Transformationsdefinition gespeichert. Empfohlene Typen von Referenzdateien: + Before/after Beispielcode + Dokumentation für die beteiligten APIs, Bibliotheken oder Funktionen + Human-readable Anleitungen zur Migration **Um eine Referenzdatei bereitzustellen: ** ``` Take a look at the documentation here: /path/to/migration-guide.md ``` Sie können auch ein Verzeichnis angeben, das mehrere Referenzdateien enthält: ``` Take a look at the docs we have here: /path/to/docs/ ``` **Anmerkung** Nur textbasierte Dateien (.md, .html, .txt, Codedateien) werden unterstützt. Binärdateien, Bilder und Rich-Text-Dateien (z. B.. pdf, .png, .docx) werden derzeit nicht unterstützt. Oft ist es möglich, den Textinhalt zu extrahieren und ihn als Referenz zu verwenden. Wenn Sie viele kleine Textdateien haben, sollten Sie erwägen, diese zu wenigen Dateien mit beschreibendem Namen zu verketten. Es gibt ein Limit von insgesamt 10 MB für alle Dateien. ### Ändern einer vorhandenen Transformation Sie können benutzerdefinierte Transformationen sowohl vor als auch nach dem Speichern als Entwurf oder Veröffentlichen ändern. Verwaltete Transformationen können nicht geändert werden AWS. Wenn Sie sie anpassen müssen, können Sie mithilfe der Konfigurationsdatei zusätzlichen Kontext bereitstellen. **Um eine bestehende Transformation zu ändern ** 1. Starten Sie die AWS Transform CLI: ``` atx ``` 1. Teilen Sie dem Agenten mit, dass Sie eine bestehende Transformation ändern möchten. 1. Wählen Sie aus, ob Sie: + Geben Sie einen Dateipfad zu einer lokal gespeicherten Transformation an (d. h. nicht zu einem gespeicherten Entwurf oder einer veröffentlichten Transformation) + Fordern Sie die Liste der Transformationen aus der Registrierung an 1. Wenn Sie aus der Registrierung auswählen, wählen Sie die Transformation aus, die Sie ändern möchten. 1. Beschreiben Sie gemeinsam mit dem Agenten die Änderungen, die Sie vornehmen möchten. 1. Testen Sie die aktualisierte Transformation auf einer Beispielcodebasis. 1. Veröffentlichen Sie Ihre Aktualisierungen auf Wunsch in der Registrierung. ### Veröffentlichen und Verwalten von Transformationen Sie können Ihre Transformationen mithilfe der interaktiven Oberfläche oder mit den folgenden Befehlen veröffentlichen und verwalten. **So speichern Sie eine Transformation als Entwurf: ** ``` atx custom def save-draft -n my-transformation --description "Description of the transformation" --sd ./transformation-directory ``` **Um eine Transformation zu veröffentlichen: ** ``` atx custom def publish -n my-transformation --description "Description of the transformation" --sd ./transformation-directory ``` **Um verfügbare Transformationen aufzulisten: ** ``` atx custom def list ``` **So laden Sie eine Transformationsdefinition herunter: ** ``` atx custom def get -n my-transformation ``` Dadurch wird die Transformationsdefinition in Ihr aktuelles Arbeitsverzeichnis heruntergeladen. Sie können ein Zielverzeichnis mit dem `--td` Flag und eine Version mit dem `--tv` Flag angeben. **Um eine Transformationsdefinition zu löschen: ** ``` atx custom def delete -n my-transformation ``` **Wichtig** Dadurch wird die angegebene Transformationsdefinition dauerhaft aus Ihrem Konto gelöscht. ### Transformationsversionen verwalten AWS Transform custom verwaltet Versionen Ihrer Transformationsdefinitionen. Sie können eine Version angeben, wenn Sie eine Transformation ausführen oder herunterladen. **Um eine bestimmte Version auszuführen: ** ``` atx custom def exec -n my-transformation --tv v1 -p ./my-project ``` **Um eine bestimmte Version herunterzuladen: ** ``` atx custom def get -n my-transformation --tv v1 ``` Wenn keine Version angegeben ist, wird die neueste Version verwendet.