View a markdown version of this page

Arbeitsabläufe - AWS Transformieren

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

Verwenden atx custom def exec -n <transformation-name> -p <path> 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

Benutzen atx custom def exec -n <transformation-name> -p <path> -x -t für vollständige Automatisierung. Hinzufügen -x um im nicht interaktiven Modus zu laufen, und -t um allen Tools automatisch und ohne Aufforderung zu vertrauen.

Dieser Modus ist konzipiert für CI/CD Pipeline-Integration und Massenausführung, bei denen kein menschliches Eingreifen möglich oder erwünscht ist.

Headless-Modus

Um Aufgaben ohne Interaktion mit dem Agenten abzuschließen, führen Sie Folgendes aus atx -x "<prompt>" -t und geben Sie Ihre Anweisungen im Klartext an.

Ausführung einer kopflosen Transformation

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 <transformation_definition_name> to <codebase_path>" -t
Kopflose Transformationsentwicklung

Erstellen oder ändern Sie Transformationsdefinitionen.

Um eine ältere Transformationsdefinition in das neue Skill-Format zu konvertieren (SKILL.md + references/), führen Sie den folgenden Befehl aus:

atx -x "convert <legacy_transformation_definition_name> 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 <description> with references docs <reference_docs_path>" -t

Allgemeine Befehls-Flags

Bei der Ausführung von Transformationen mit atx custom def exec, die folgenden Flags werden häufig 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 Nachfrage

  • -d oder --do-not-learn - Verhindert die Extraktion 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

- Der -t oder --trust-all-tools flag genehmigt automatisch alle Toolausführungen ohne Aufforderung und umgeht die meisten Sicherheitsvorkehrungen (Befehle entsprechen Ihren alwaysPromptCommands Die Liste erfordert immer noch eine ausdrückliche Genehmigung, sofern sie nicht überschrieben wird trustedShellCommands). Vorbeigehen --non-interactive und --trust-all-tools ist für eine vollständig autonome Erfahrung 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

Die additionalPlanContext Der Parameter bietet zusätzlichen Kontext für den Ausführungsplan des Agenten. Dies ist besonders nützlich bei AWS-verwaltete 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

  • Drucker: eslint . oder 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

In der Standardeinstellung AWS Transform Custom extrahiert Erkenntnisse aus jeder Transformationsausführung. Sie können verhindern, dass für bestimmte Ausführungen gelernt wird.

Um zu verhindern, dass aus einer Ausführung gelernt wird:

atx custom def exec -n my-transformation -p ./my-project -d

Das -d oder --do-not-learn flag deaktiviert die Extraktion 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 <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 Transformiere benutzerdefinierte Tracks Minuten für Agenten wird während einer Transformationssitzung verbraucht. Die Minuten der Agenten 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.

Um die Agentenminuten während einer interaktiven Sitzung zu überprüfen, gehen Sie wie folgt vor:

Geben Sie ein /usage an der Eingabeaufforderung, 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

Das --limit Die Option legt ein Maximum fest Minuten für Agenten Budget für die Sitzung. Die Agentenminuten spiegeln die Arbeitszeit des aktiven Agenten wider, nicht die Uhrzeit auf 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 <conversation_id> -t --limit <increased_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

Benutze das learnings Befehl, um eine interaktive Sitzung zum Durchsuchen und Verwalten der Lektionen einer Transformationsdefinition zu öffnen.

Um den Lektionen-Viewer zu öffnen:

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 Lektionen, in denen sie abgerufen wurde.

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 beschrieben AWS Benutzerdefiniert transformieren.

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 ein PowerShell unter Verwendung von $env:NAME="value". Sehen Sie die Fenster (PowerShell) Tabulatoren für die entsprechenden Befehle.

ATX_SHELL_TIMEOUT

Überschreibt das Standard-Timeout für Shell-Befehle (900) seconds/15 Minuten).

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

Konfigurieren Sie die Autorenidentität, die für den Checkpoint verwendet wird, der Folgendes festlegt AWS Transformiere benutzerdefinierte Kreationen in deinem Repository, während es Änderungen während einer Transformation anwendet. Wenn diese Variablen nicht gesetzt sind, werden Checkpoint-Commits einer Standardidentität zugeordnet (ATX Bot <checkpoint@atx.bot>). Stellen Sie beide Variablen ein, um Checkpoints einem bestimmten Autor zuzuordnen.

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 konfiguriert ~/.aws/atx/trust-settings.yaml datei.

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 von -t Flagge oder 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. Beides trustedShellCommands und alwaysPromptCommands unterstützt Glob-Platzhaltermuster mit *.

Anmerkung

Wenn ein Befehl mit beiden Listen übereinstimmt, trustedShellCommands hat 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 von trustedShellCommands, unabhängig von -t Flagge oder Sitzungsvertrauensstellung. Diese Muster werden im nicht interaktiven Modus nicht erzwungen (-x). Muster werden mit jedem Unterbefehl in zusammengesetzten Ausdrücken abgeglichen (&&, ||, Befehlsersetzungen).

    Beispiele:

    • rm -rf * - Fordert immer zur Eingabe rekursiver Befehle zum erzwungenen Löschen auf

    • sudo * - Fordert immer nach Befehlen auf, die mit sudo ausgeführt werden

    • find * -exec * - Fordert immer nach Suchbefehlen mit -exec

Session-level vertrauen:

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

Session Trust ist nicht für Befehle verfügbar, die Ihren entsprechen alwaysPromptCommands Liste.

Model Context Protocol (MCP) -Server

Die AWS Transform CLI unterstützt Model Context Protocol (MCP) -Server, die ihre Funktionalität um zusätzliche Tools erweitern.

Konfiguration:

Konfigurieren Sie die MCP-Server im ~/.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 dem command Eigentum:

{ "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 dem url Eigentum:

{ "mcpServers": { "my-remote-server": { "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${MCP_API_TOKEN}" } } } }

Das headers Die Eigenschaft ist optional und unterstützt die Erweiterung von Umgebungsvariablen mit ${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 ${VAR_NAME} Erweiterung der 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 <server-name>

Nachverfolgung der Nutzung:

Die CLI verfolgt automatisch die Nutzung des MCP-Tools während der Ausführung von Transformationen. Nutzungsstatistiken werden wie folgt gespeichert mcp_usage.json im Konversationsverzeichnis neben metadata.json. Die Datei zeichnet Metriken pro Tool für jede Ausführung auf, einschließlich:

  • 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. <project>/.aws/atx/skills/ - Project-level, AWS Transformieren CLI-specific

  2. <project>/.agents/skills/ - Project-level, clientübergreifend (für alle kompatiblen Agententools verfügbar)

  3. ~/.aws/atx/skills/ - User-level, AWS Transformieren CLI-specific

  4. ~/.agents/skills/ - User-level, clientübergreifend (für alle kompatiblen Agententools verfügbar)

Das .aws/atx/skills/ Verzeichnisse sind spezifisch für AWS CLI transformieren. Die .agents/skills/ Die Verzeichnisse sind mandantenübergreifend, was bedeutet, dass die dort hinterlegten Fähigkeiten allen kompatiblen Agententools zur Verfügung stehen, abgesehen von AWS CLI transformieren.

Struktur des Skill-Verzeichnisses:

Jeder Skill ist ein Verzeichnis, das eine enthält SKILL.md Datei mit YAML-Frontmatter:

~/.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 Das Feld muss mit dem Namen des übergeordneten Verzeichnisses übereinstimmen.

Einen Skill deaktivieren:

Um zu verhindern, dass ein Skill geladen wird, ohne seine Dateien zu entfernen, fügen Sie disable-model-invocation: true zur Titelseite:

--- name: my-skill description: When to use this skill disable-model-invocation: true ---

Wenn diese Eigenschaft festgelegt 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 ausschließlich 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. Der disable-model-invocation Die 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 sowohl aus Verzeichnissen auf Benutzer- als auch auf 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.

Wählen 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 (<project>/.aws/atx/skills/):

Übergeben Sie diese der Versionskontrolle, sodass jedes Teammitglied, das Transformationen für das Repository durchführt, sie automatisch erkennt. Nutzen Sie Fähigkeiten auf Projektebene für:

  • Repository-specific Konformitätsprüfungen (Dockerfile-Regeln, Terraform-Richtlinien, Validatoren für die Migrationssicherheit)

  • Kodierungsstandards der Organisation, 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 deutlich description Felder in Ihrem SKILL.md Titelsache. 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 im mandantenübergreifenden Verzeichnis (.agents/skills/) auf beiden Ebenen, um sie mit anderen KI-Entwicklungstools zu teilen AWS CLI transformieren.

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 dient.

Beispiel: Dockerfile Compliance Checker (Script-Based)

Dieser Skill 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 <path-to-Dockerfile>` 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, fest codierte Secrets in ENV Direktiven und fehlende HEALTHCHECK Definitionen. 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 Einhaltung der Vorschriften zu bestätigen.

Beispiel: API Deprecation Helper (Reference-Only)

Dieser Skill 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. Zum Beispiel aws-sdk-v2-to-v3.md kartografiert Muster wie s3.putObject(params).promise() zum modularen v3-Äquivalent mit S3Client und PutObjectCommand.

Schlagworte und Organisation

Sie können kundeneigene Transformationsdefinitionen mit Stichwörtern für Zugriffskontrolle, Kategorisierung und Kostenzuweisung organisieren.

Sie können Tags nur in kundeneigenen Transformationsdefinitionen hinzufügen, aktualisieren oder entfernen. Sie können Tags nicht verwalten auf AWS-verwaltete Transformationen.

Anmerkung

Einige dieser Befehle erfordern die Angabe des Amazon-Ressourcennamens (ARN) für eine Transformationsdefinition. Die ARN-Struktur lautet: arn:aws:transform-custom:<region>:<account-id>:package/<td-name>

Um die Tags für eine Transformation aufzulisten:

atx custom def list-tags --arn <transformation-arn>

Um einer Transformation Tags hinzuzufügen:

atx custom def tag --arn <transformation-arn> --tags '{"env":"prod","team":"backend"}'

Um Tags aus einer Transformation zu entfernen:

atx custom def untag --arn <transformation-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 gekennzeichnet sind team:frontend oder environment:production).

Verwenden Sie Tags für die Kostenzuweisung

Sie können Tags in kundeneigenen Transformationsdefinitionen verwenden, um Ihre zu organisieren AWS Rechnung. AWS Transform Custom zeichnet die Transformationsdefinition als Fakturierungsressource für Minuten für Agenten Eine Hinrichtung verbraucht. Jede Ausführung erbt die Tags der Transformationsdefinition, die sie ausführt. Wenn sich mehrere Teams oder Projekte eines teilen AWS Konto, kennzeichnen Sie jede kundeneigene Definition mit ihrem Kostenverantwortlichen. Anschließend können Sie die Transformationskosten für jedes Team oder Projekt separat aufteilen.

Nachdem Sie Ihre kundeneigenen Transformationsdefinitionen mit Tags versehen haben, aktivieren Sie diese Tag-Schlüssel in AWS Konsole für Abrechnung und Kostenmanagement Tag-Werte erscheinen erst in Ihren Kostendaten, wenn der Tag-Schlüssel aktiviert ist. Die Aktivierung gilt für die zukünftige Nutzung. Um die Nutzung aus früheren Monaten zuzuordnen, fordern Sie eine Auffüllung der Kostenzuordnungskennzeichen an. Weitere Informationen finden Sie unter Kostenzuweisung und Kennzeichnung in der AWS Benutzerhandbuch für Abrechnung und Kostenmanagement.

Nachdem ein Tag-Schlüssel aktiv ist, können Sie gruppieren AWS Transformieren Sie Gebühren im Cost Explorer anhand dieses Schlüssels. Sie können auch Ressourcen-IDs angeben in AWS Kosten- und Nutzungsberichte, in denen der ARN der Transformationsdefinition und die zugehörigen Tag-Werte in den einzelnen Zeilen angezeigt werden. Die Spalten, die diese Werte enthalten, finden Sie unter Spalten mit Ressourcen-Tags in der AWS Benutzerhandbuch für Datenexporte. Das folgende Beispiel kehrt zurück AWS Transformieren Sie die Kosten und Agentenminuten für einen Tag, gruppiert nach einem CostCenter Tag.

aws ce get-cost-and-usage \ --time-period Start=2026-09-01,End=2026-09-02 \ --granularity DAILY \ --metrics UnblendedCost UsageQuantity \ --filter '{"Dimensions":{"Key":"SERVICE","Values":["AWS Transform"]}}' \ --group-by Type=TAG,Key=CostCenter

Cost Explorer gibt Gebühren ohne Wert für den Schlüssel als einzelne Gruppe mit einem leeren Wert zurück. Dies zeigt Ihnen, wie viele Ausgaben noch nicht zugeordnet werden.

Was du nicht nach Stichwörtern zuordnen kannst

Tag-based Die Attribution basiert auf der Transformationsdefinition. Prüfen Sie die folgenden Punkte anhand Ihres Kostenmodells, bevor Sie sich bei Rückbuchungen auf Stichwörter verlassen.

Usage Warum wird es nicht zugeordnet und was ist stattdessen zu tun
AWS-verwaltete Transformationen Sie können keine Tags hinzufügen, aktualisieren oder entfernen AWS-verwaltete Transformationsdefinitionen. Ihre Gebühren für Agentenminuten übernehmen keine vom Kunden definierten Kostenzuweisungen.
Sitzungen, in denen keine Transformationsdefinition ausgeführt wird In einem Zeitraum verbrauchte Agentenminuten atx Sitzungen, in denen keine Transformationsdefinition ausgeführt wird, werden ohne eine Ressourcen-ID aufgezeichnet, sodass keine Ressource zur Vererbung von Tags zur Verfügung steht. Führen Sie die Arbeit anhand einer mit Tags versehenen Transformationsdefinition durch, wenn die Ausgaben zugeordnet werden müssen.
Individuelle Ausführungen einer Definition Tags sind eine Eigenschaft der Transformationsdefinition, nicht einer Ausführung, und atx custom def exec akzeptiert keine Tags. Alle Ausführungen einer Definition haben die gleichen Tag-Werte. Um zwei Kostenträger voneinander zu trennen, weisen Sie jedem seine eigene Transformationsdefinition zu.
Einzelne Benutzer oder IAM-Prinzipale Die Gebühren werden der Transformationsdefinition und dem ausführenden Konto zugeordnet, nicht der Identität, die die Ausführung gestartet hat. Per-user Eine Zuordnung über Kostenzuweisungs-Tags ist nicht möglich.

Protokolle

AWS Transform CLI verwaltet drei Arten von Protokollen zur Problembehandlung und zum Debuggen.

Konversationsprotokolle:

Linux and macOS
~/.aws/atx/custom/<conversation_id>/logs/<timestamp>-conversation.log
Windows
%USERPROFILE%\.aws\atx\custom\<conversation_id>\logs\<timestamp>-conversation.log

Diese Protokolle enthalten den vollständigen Konversationsverlauf für eine bestimmte Sitzung.

Subagent-Protokolle:

Linux and macOS
~/.aws/atx/custom/<conversation_id>/logs/subagents/<name>.log
Windows
%USERPROFILE%\.aws\atx\custom\<conversation_id>\logs\subagents\<name>.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 <conversation-id>~/.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 zuzugreifen.

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 <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 den AWS CLI transformieren:

    atx
  2. Teilen Sie dem Agenten mit, dass Sie eine neue Transformation erstellen möchten.

  3. 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

  4. Wenn der Mitarbeiter um Klarstellung oder zusätzliche Informationen bittet, geben Sie konkrete Beispiele und Referenzmaterialien an.

  5. Überprüfen Sie die ursprüngliche Transformationsdefinition, die vom Agenten erstellt wurde.

  6. Testen Sie die Transformation auf einer Beispielcodebasis.

  7. Iterieren Sie, indem Sie Feedback, Codekorrekturen oder zusätzliche Beispiele bereitstellen.

  8. 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 diesen Anforderungen Priorität einräumt

  • 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 bereitstellen für AWS Transformieren Sie benutzerdefinierte Dateien, indem Sie während der Konversation Dateipfade angeben. Diese Dateien werden im gespeichert references/ Ordner der Transformationsdefinition.

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. Sie können nichts ändern AWS-verwaltete Transformationen. 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 den AWS CLI transformieren:

    atx
  2. Teilen Sie dem Agenten mit, dass Sie eine bestehende Transformation ändern möchten.

  3. 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

  4. Wenn Sie aus der Registrierung auswählen, wählen Sie die Transformation aus, die Sie ändern möchten.

  5. Beschreiben Sie gemeinsam mit dem Agenten die Änderungen, die Sie vornehmen möchten.

  6. Testen Sie die aktualisierte Transformation auf einer Beispielcodebasis.

  7. 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 angeben mit --td Flagge und eine Version mit dem --tv Flagge.

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.