Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Flussi di lavoro

Esecuzione di trasformazioni

Questa sezione descrive i diversi modi di eseguire le trasformazioni e le opzioni per controllare il comportamento di esecuzione.

Modalità di esecuzione

AWS Transform custom supporta tre modalità di esecuzione per adattarsi a diversi flussi di lavoro.

Modalità conversazionale interattiva

Avvia la CLI con atx e chiedi all'agente di eseguire una trasformazione tramite linguaggio naturale. Questa modalità consente di avere una conversazione completa con l'agente, interrompere l'esecuzione in qualsiasi momento e fornire feedback durante il processo di trasformazione.

Utilizzate questa modalità quando desiderate il massimo controllo e la capacità di guidare l'agente attraverso scenari complessi.

Esecuzione interattiva diretta

atx custom def exec -n <transformation-name> -p <path>Da utilizzare per avviare una trasformazione specifica in modo interattivo. Questa modalità consente di rivedere e interagire con l'agente all'inizio, durante o alla fine dell'esecuzione. L'agente si fermerà nei momenti decisionali chiave e chiederà il tuo contributo.

È ideale per testare e perfezionare le trasformazioni prima di eseguirle autonomamente.

È possibile eseguire trasformazioni in modalità non interattiva o in modalità headless. Non-interactive mode sopprime i prompt durante una trasformazione denominata. La modalità headless consente di eseguire l'agente con un prompt in testo semplice, ignorando completamente l'interfaccia interattiva.

Non-interactive modalità

Utilizzare atx custom def exec -n <transformation-name> -p <path> -x -t per l'automazione completa. Aggiungi -x per funzionare in modalità non interattiva e affidati automaticamente -t a tutti gli strumenti senza richiedere conferma.

Questa modalità è progettata per l'integrazione della CI/CD pipeline e l'esecuzione in blocco laddove non è disponibile o richiesto alcun intervento umano.

modalità Headless

Per completare le attività senza interagire con l'agente, esegui atx -x "<prompt>" -t e fornisci le istruzioni in testo semplice.

Esecuzione della trasformazione senza intoppi

Utilizzate questa modalità per applicare una definizione di trasformazione esistente alla vostra codebase. La trasformazione esegue automaticamente ogni fase senza richiedere l'approvazione dell'utente.

atx -x "apply transformation definition <transformation_definition_name> to <codebase_path>" -t

Sviluppo di una trasformazione senza fronzoli

Crea o modifica le definizioni di trasformazione.

Per convertire una definizione di trasformazione precedente nel nuovo formato di abilità (SKILL.md + references/), esegui il comando seguente:

atx -x "convert <legacy_transformation_definition_name> transformation definition to skill and save as draft" -t

Per creare una nuova definizione di trasformazione, esegui il comando seguente:

atx -x "create a transformation definition to <description> with references docs <reference_docs_path>" -t

Bandiere di comando comuni

Quando si eseguono trasformazioni conatx custom def exec, vengono comunemente utilizzati i seguenti flag:

Utilizzo dei file di configurazione

AWS Transform custom supporta file di configurazione opzionali in formato YAML o JSON. I file di configurazione consentono di specificare i parametri di esecuzione e fornire un contesto aggiuntivo all'agente.

Per utilizzare un file di configurazione:

atx custom def exec --configuration file://config.yaml

Puoi anche fornire la configurazione come coppie chiave-valore in linea:

atx custom def exec --configuration "key=value,key2=value2"

File di configurazione di esempio (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

Il additionalPlanContext parametro fornisce un contesto aggiuntivo per il piano di esecuzione dell'agente. Ciò è particolarmente utile con le AWS trasformazioni gestite per personalizzare il loro comportamento in base a esigenze specifiche.

Comandi di compilazione e convalida

Il comando build o validation è un parametro opzionale che specifica come convalidare il codice durante il processo di trasformazione. AWS Transform custom tenterà di dedurre il miglior comando di compilazione in base alla trasformazione se non specificato, sebbene si consiglia di specificarlo per quanto riguarda la qualità.

Esempi di comandi di compilazione e convalida:

Anche per i linguaggi o le trasformazioni che non richiedono la compilazione, è molto importante fornire un comando che convalidi i risultati e restituisca problemi se la convalida fallisce per migliorare la qualità della trasformazione.

Se non è necessaria alcuna compilazione o convalida, omettila dal tuo input.

Controllo del comportamento di apprendimento

Per impostazione predefinita, AWS Transform custom estrae le lezioni da ogni esecuzione di trasformazione. È possibile impedire l'apprendimento per esecuzioni specifiche.

Per impedire l'apprendimento da un'esecuzione:

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

Il --do-not-learn flag -d or disattiva l'estrazione della lezione dall'esecuzione corrente.

Ripresa delle conversazioni

AWS Transform custom ti consente di riprendere le conversazioni precedenti entro 30 giorni dalla creazione.

Per riprendere la conversazione più recente:

atx --resume

Per riprendere una conversazione specifica:

atx --conversation-id <conversation-id>

Tracking Agent Minutes

AWS Transform custom tiene traccia dei minuti consumati dall'agente durante una sessione di trasformazione. I minuti degli agenti si accumulano durante il ciclo di vita della conversazione e vengono visualizzati al termine della conversazione:

Agent minutes used: 12.50

I minuti degli agenti persistono anche dopo le interruzioni. Se si interrompe una sessione con Ctrl+C e la si riprende in un secondo momento, i minuti accumulati in precedenza vengono trasferiti e continuano ad accumularsi nella sessione ripresa.

Per controllare Agent Minutes durante una sessione interattiva:

Digitate /usage al prompt di input per visualizzare gli Agent Minutes attualmente accumulati senza terminare la conversazione.

Per impostare un limite di budget per Agent Minutes:

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

L'--limitopzione imposta un budget massimo di Agent Minutes per la sessione. Gli Agent Minutes riflettono l'orario di lavoro attivo dell'agente, non l'ora dell'orologio da parete. Quando viene raggiunto il limite, la CLI visualizza un messaggio ed esce con le istruzioni per riprendere:

⚠️ Budget limit reached: 30.00 / 30.00 Agent Minutes. Exiting.

Puoi riprendere la conversazione in un secondo momento con un limite maggiore:

atx --conversation-id <conversation_id> -t --limit <increased_limit>

Apprendimento continuo

Questa sezione descrive come rivedere e gestire le lezioni create dall'apprendimento continuo.

Lezioni di comprensione

Il sistema di apprendimento continuo estrae automaticamente le lezioni dalle esecuzioni precedenti di una trasformazione. Il sistema le crea in modo asincrono sulla base di:

Le lezioni si accumulano nel tempo man mano che si esegue la trasformazione su diverse basi di codice. Il sistema li applica automaticamente per migliorare le esecuzioni future. Ogni lezione appartiene a una categoria contenente tutte le lezioni di un dominio simile, in modo da poter rivedere insieme le lezioni correlate. Per le lezioni che non desideri vengano utilizzate, puoi archiviare o eliminare completamente la lezione.

Visualizzazione e gestione delle lezioni

Utilizzate il learnings comando per aprire una sessione interattiva per sfogliare e gestire le lezioni di una definizione di trasformazione.

Per aprire il visualizzatore delle lezioni:

atx custom def learnings -n my-transformation

Il visualizzatore si apre su un elenco di categorie di lezioni, ognuna delle quali mostra quante lezioni attive contiene. Seleziona una categoria per visualizzarne le lezioni, quindi seleziona una lezione per visualizzarne tutti i dettagli, tra cui il corpo della lezione, il suo impatto e il numero di sessioni precedenti consultate.

Archiviazione e ripristino delle lezioni

Il sistema applica le lezioni automaticamente. Se non vuoi che il sistema applichi una lezione, puoi archiviarla. Il sistema conserva le lezioni archiviate ma non le applica alle esecuzioni future. Tutte le lezioni archiviate sono raggruppate in modo da poterle rivedere e ripristinare l'uso attivo di tutte le lezioni.

Eliminazione delle lezioni

Rimuovi definitivamente una lezione che non è utile. L'eliminazione non può essere annullata e il sistema potrebbe apprendere nuovamente una lezione eliminata dalle esecuzioni future.

Una lezione deve essere archiviata prima di poter essere eliminata.

Configurazione avanzata

Questa sezione descrive le funzionalità avanzate e le opzioni di configurazione per AWS Transform custom.

Variabili di ambiente

È possibile personalizzare il comportamento della CLI utilizzando variabili di ambiente.

ATX_SHELL_TIMEOUT

Sostituisci il timeout predefinito per i comandi della shell (900 minuti). seconds/15

Linux and macOS

export ATX_SHELL_TIMEOUT=1800  # 30 minutes

Windows (PowerShell)

$env:ATX_SHELL_TIMEOUT=1800  # 30 minutes

Ciò è utile per basi di codice di grandi dimensioni o processi di compilazione a esecuzione prolungata.

ATX_DISABLE_UPDATE_CHECK

Disattiva i controlli automatici delle versioni e le notifiche di aggiornamento durante l'esecuzione dei comandi.

Linux and macOS

export ATX_DISABLE_UPDATE_CHECK=true

Windows (PowerShell)

$env:ATX_DISABLE_UPDATE_CHECK="true"

ATX_GIT_COMMITTER_NAME e ATX_GIT_COMMITTER_EMAIL

Configura l'identità dell'autore utilizzata per i commit del checkpoint che Transform custom crea nel tuo repository man mano che applica le modifiche durante una trasformazione. AWS Quando queste variabili non sono impostate, i commit dei checkpoint vengono attribuiti a un'identità predefinita (). ATX Bot <checkpoint@atx.bot> Imposta entrambe le variabili per attribuire i checkpoint a un autore specifico.

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"

Impostazioni di fiducia

Le impostazioni di attendibilità consentono di approvare preventivamente strumenti e comandi specifici da eseguire senza richieste. È inoltre possibile richiedere l'autorizzazione esplicita per comandi shell specifici indipendentemente dal livello di attendibilità. Queste impostazioni sono configurate nel ~/.aws/atx/trust-settings.yaml file.

Il file contiene tre elenchi:

Strumenti affidabili predefiniti:

Modifica delle impostazioni di attendibilità:

Puoi modificare manualmente il file trust-settings.yaml per aggiungere o rimuovere strumenti e comandi affidabili. Entrambi supportano i pattern glob wildcard utilizzandotrustedShellCommands. alwaysPromptCommands *

Di seguito viene descritto ogni elenco di comandi e vengono forniti esempi:

Session-level fiducia:

Durante i prompt interattivi, puoi scegliere:

Session-level le impostazioni di trust sono temporanee e vengono ripristinate al riavvio della CLI, fornendo un'approvazione temporanea senza modificare permanentemente trust-settings.yaml.

Server Model Context Protocol (MCP)

La CLI AWS Transform supporta i server Model Context Protocol (MCP), che ne estendono le funzionalità con strumenti aggiuntivi.

Configurazione:

Configurare i server MCP nel ~/.aws/atx/mcp.json file. La CLI AWS Transform supporta due tipi di server MCP: server locali basati su comandi e server HTTP remoti.

Server locali basati su comandi:

I server locali vengono eseguiti come processi secondari sul computer. Configurali con la command proprietà:

{
  "mcpServers": {
    "my-local-server": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

Server HTTP remoti:

I server remoti si connettono ai server MCP ospitati su un URL HTTP o HTTPS. Configurali con la url proprietà:

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

La headers proprietà è facoltativa e supporta l'espansione delle variabili di ambiente tramite la ${VAR_NAME} sintassi. Ciò consente di memorizzare valori sensibili come i token API nelle variabili di ambiente anziché nel file di configurazione.

Proprietà di configurazione:

I server locali basati su comandi supportano le seguenti proprietà:

I server HTTP remoti supportano le seguenti proprietà:

Gestione dei server MCP:

Visualizza l'elenco dei server MCP configurati:

atx mcp tools

Elenca gli strumenti disponibili offerti da uno specifico server MCP:

atx mcp tools --server <server-name>

Monitoraggio dell'utilizzo:

La CLI monitora automaticamente l'utilizzo dello strumento MCP durante le esecuzioni di trasformazione. Le statistiche di utilizzo vengono mantenute come mcp_usage.json nella directory delle conversazioni a fianco. metadata.json Il file registra le metriche per strumento per ogni esecuzione, tra cui:

Client-Side Competenze

Client-side le competenze sono funzionalità aggiuntive che estendono l'agente durante le esecuzioni di trasformazione. Consentono di fornire strumenti, script e istruzioni personalizzati che l'agente può utilizzare oltre alle funzionalità integrate.

Directory per la scoperta delle abilità:

Le abilità vengono rilevate da quattro elenchi in ordine di precedenza. Se un'abilità con lo stesso nome esiste in più directory, la prima directory dell'elenco ha la priorità:

Le .aws/atx/skills/ directory sono specifiche della CLI AWS Transform. Le .agents/skills/ directory sono interclient, il che significa che le competenze ivi inserite sono disponibili per qualsiasi strumento agente compatibile oltre alla CLI Transform AWS .

Struttura della directory delle abilità:

Ogni abilità è una directory contenente un SKILL.md file con frontmatter YAML:

~/.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 formato:

---
name: my-skill
description: When to use this skill
---
# Skill Title

Instructions for the agent...

Il name campo deve corrispondere al nome della directory principale.

Disabilitazione di un'abilità:

Per evitare che un'abilità venga caricata senza rimuoverne i file, aggiungi disable-model-invocation: true alla prima pagina:

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

Quando questa proprietà è impostata, la CLI ignora l'abilità durante il rilevamento. L'agente non può vedere o utilizzare l'abilità a meno che una definizione di trasformazione non gli indichi esplicitamente di leggere il file di abilità. Utilizzatelo per disattivare temporaneamente un'abilità, contrassegnarla come in corso di lavorazione o conservare materiale di riferimento destinato esclusivamente ai lettori umani.

Disponibilità delle competenze in base alla modalità di esecuzione:

Verifica della scoperta delle abilità:

Controlla il registro di debug della CLI dopo l'esecuzione per verificare quali competenze sono state scoperte:

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

Le abilità che non superano la convalida vengono ignorate con un avviso nei log di debug.

Scelta tra Project-Level e competenze User-Level

Il luogo in cui si colloca un'abilità determina chi ne trae beneficio e quando si attiva.

Project-level competenze (<project>/.aws/atx/skills/):

Affidale al controllo delle versioni in modo che ogni membro del team che esegue trasformazioni sul repository le scopra automaticamente. Usa le competenze a livello di progetto per:

User-level competenze (~/.aws/atx/skills/):

Questi rimangono sulla macchina e si attivano durante tutte le trasformazioni indipendentemente dal repository scelto come destinazione. Utilizza le competenze a livello di utente per:

Suggerimenti per competenze efficaci:

Client-Side Esempi di abilità

Questi esempi mostrano due modelli comuni: un'abilità di convalida basata su script e un'abilità di solo riferimento.

Esempio: Dockerfile Compliance Checker () Script-Based

Questa competenza convalida Dockerfiles rispetto alle migliori pratiche operative e di sicurezza. Utilizza uno script di convalida che l'agente esegue prima e dopo aver apportato le modifiche.

Struttura delle cartelle:

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

Lo script di convalida verifica la presenza di tag di immagine di base non bloccati, eseguiti come root, segreti codificati nelle ENV direttive e definizioni mancanti. HEALTHCHECK L'agente esegue lo script, corregge le violazioni utilizzando i modelli del file di riferimento e riesegue lo script per confermare la conformità.

Esempio: API Deprecation Helper () Reference-Only

Questa abilità guida l'agente nella sostituzione delle chiamate API obsolete durante le trasformazioni di aggiornamento. Utilizza solo file di riferimento senza script.

Struttura delle cartelle:

.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

I file di riferimento contengono esempi di codice prima e dopo. Ad esempio, aws-sdk-v2-to-v3.md mappa modelli simili s3.putObject(params).promise() all'equivalente modulare v3 usando and. S3Client PutObjectCommand

Tag e organizzazione

Puoi organizzare le trasformazioni con tag per il controllo degli accessi e la categorizzazione.

Per elencare i tag per una trasformazione:

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

Per aggiungere tag a una trasformazione:

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

Per rimuovere i tag da una trasformazione:

atx custom def untag --arn <transformation-arn> --tag-keys "env,team"

I tag possono essere utilizzati per il controllo degli accessi raggruppati nelle politiche IAM. Puoi creare politiche che concedono autorizzazioni a tutte le trasformazioni con tag specifici (ad esempio, tutte le trasformazioni contrassegnate con o). team:frontend environment:production

Log

AWS Transform CLI mantiene tre tipi di log per la risoluzione dei problemi e il debug.

Registri delle conversazioni:

Linux and macOS

~/.aws/atx/custom/<conversation_id>/logs/<timestamp>-conversation.log

Windows

%USERPROFILE%\.aws\atx\custom\<conversation_id>\logs\<timestamp>-conversation.log

Questi registri contengono la cronologia completa delle conversazioni per una sessione specifica.

Registri di Subagent:

Linux and macOS

~/.aws/atx/custom/<conversation_id>/logs/subagents/<name>.log

Windows

%USERPROFILE%\.aws\atx\custom\<conversation_id>\logs\subagents\<name>.log

Questi registri contengono l'output dei subagenti generati dall'agente principale durante le trasformazioni. Non è necessario gestire direttamente i subagenti.

Registri di debug per sviluppatori:

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

Questi registri forniscono informazioni avanzate sulla risoluzione dei problemi per la CLI stessa.

Aggiornamenti CLI

Mantieni aggiornata la CLI per accedere a nuove funzionalità e miglioramenti.

Per verificare la presenza di aggiornamenti:

atx update --check

Per eseguire l'aggiornamento alla versione più recente:

atx update

Per eseguire l'aggiornamento a una versione specifica:

atx update --target-version <version>

Crea trasformazioni personalizzate

Questa sezione descrive come creare, modificare e gestire definizioni di trasformazione personalizzate.

Creazione di una nuova trasformazione

Utilizza la CLI interattiva per creare una nuova definizione di trasformazione.

Per creare una definizione di trasformazione

Le migliori pratiche per creare trasformazioni:

Fornire materiali di riferimento

Puoi fornire file di riferimento a AWS Transform custom specificando i percorsi dei file durante la conversazione. Questi file vengono archiviati nella references/ cartella della definizione di trasformazione.

Tipi di file di riferimento consigliati:

Per fornire un file di riferimento:

Take a look at the documentation here: /path/to/migration-guide.md

Puoi anche fornire una directory contenente più file di riferimento:

Take a look at the docs we have here: /path/to/docs/

Modifica di una trasformazione esistente

È possibile modificare le trasformazioni personalizzate sia prima che dopo averle salvate come bozze o dopo averle pubblicate. Non è possibile modificare le trasformazioni AWS gestite. Se è necessario personalizzarle, è possibile fornire un contesto aggiuntivo utilizzando il file di configurazione.

Per modificare una trasformazione esistente

Pubblicazione e gestione delle trasformazioni

Puoi pubblicare e gestire le tue trasformazioni utilizzando l'esperienza interattiva o con i seguenti comandi.

Per salvare una trasformazione come bozza:

atx custom def save-draft -n my-transformation --description "Description of the transformation" --sd ./transformation-directory

Per pubblicare una trasformazione:

atx custom def publish -n my-transformation --description "Description of the transformation" --sd ./transformation-directory

Per elencare le trasformazioni disponibili:

atx custom def list

Per scaricare una definizione di trasformazione:

atx custom def get -n my-transformation

Questa operazione scarica la definizione di trasformazione nella directory di lavoro corrente. È possibile specificare una directory di destinazione con il --td flag e una versione con il --tv flag.

Per eliminare una definizione di trasformazione:

atx custom def delete -n my-transformation

Gestione delle versioni di trasformazione

AWS Transform custom mantiene le versioni delle definizioni di trasformazione. È possibile specificare una versione durante l'esecuzione o il download di una trasformazione.

Per eseguire una versione specifica:

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

Per scaricare una versione specifica:

atx custom def get -n my-transformation --tv v1

Se non viene specificata alcuna versione, viene utilizzata la versione più recente.