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 `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 -p `Da utilizzare per avviare una trasformazione specifica in modo interattivo. Questa modalità consente di esaminare e interagire con l'agente all'inizio, durante o alla fine dell'esecuzione. L'agente si fermerà nei punti decisionali chiave e chiederà il tuo contributo. È ideale per testare e perfezionare le trasformazioni prima di eseguirle in modo autonomo. È possibile eseguire trasformazioni in modalità non interattiva o in modalità headless. Non-interactive la modalità sopprime i prompt durante una trasformazione denominata. La modalità Headless consente di eseguire l'agente con un prompt in testo normale, ignorando completamente l'interfaccia interattiva. #### Non-interactive modalità Utilizzare `atx custom def exec -n -p -x -t` per l'automazione completa. Aggiungi `-x` per eseguire in modalità non interattiva e `-t` considerare attendibili tutti gli strumenti automaticamente senza chiedere conferma. Questa modalità è progettata per l'integrazione della CI/CD pipeline e l'esecuzione in blocco in cui non è disponibile o desiderato alcun intervento umano. #### Modalità Headless Per completare le attività senza interagire con l'agente, esegui `atx -x "" -t` e fornisci le istruzioni in testo semplice. ##### Esecuzione di trasformazioni senza testa Utilizzate questa modalità per applicare una definizione di trasformazione esistente alla vostra base di codice. La trasformazione esegue automaticamente ogni passaggio senza richiedere l'approvazione dell'utente. ``` atx -x "apply transformation definition to " -t ``` ##### Sviluppo di trasformazioni senza testa Crea o modifica le definizioni di trasformazione. Per convertire una definizione di trasformazione precedente nel nuovo formato di abilità (SKILL.md \+ referenze/), esegui il comando seguente: ``` atx -x "convert 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 with references docs " -t ``` ### Bandiere di comando comuni Quando si eseguono trasformazioni con`atx custom def exec`, vengono comunemente usati i seguenti flag: + `-n`o `--transformation-name` - Specifica il nome della trasformazione da eseguire + `-p`or `--code-repository-path` - Specifica il percorso della base di codice (usa «.» per la directory corrente) + `-c`or `--build-command` - Specifica il comando di compilazione o convalida da eseguire + `-x`o `--non-interactive` - Abilita la modalità non interattiva (nessuna richiesta utente) + `-t`o `--trust-all-tools` - Si fida automaticamente di tutti gli strumenti senza chiedere conferma + `-d`o `--do-not-learn` - Impedisce l'estrazione della lezione da questa esecuzione + `--tv`or `--transformation-version` - Specifica una versione specifica della trasformazione + `-g`o `--configuration` - Fornisce un file di configurazione o una configurazione in linea **Importante** Il `--trust-all-tools` flag `-t` or approva automaticamente tutte le esecuzioni degli strumenti senza chiedere conferma e aggira la maggior parte delle barriere di sicurezza (i comandi corrispondenti all'`alwaysPromptCommands`elenco richiedono comunque un'autorizzazione esplicita a meno che non vengano sovrascritti da). `trustedShellCommands` Il passaggio è obbligatorio per un'`--non-interactive`esperienza completamente autonoma ma `--trust-all-tools` non è necessario per eseguire la trasformazione. Usare con cautela negli ambienti di produzione. ### 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 trasformazioni AWS gestite per personalizzarne il comportamento in base alle esigenze specifiche. ### Comandi di compilazione e convalida Il comando di compilazione o validazione è 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, anche se si consiglia di specificare la qualità. **Esempi di comandi di compilazione e convalida: ** + Java: `mvn clean install` o `gradle build` + Python: `pytest` o `python -m py_compile` + Node.js: `npm run build` o `npm test` + Linters: o `eslint .` `pylint .` Anche per linguaggi o trasformazioni che non richiedono la compilazione, fornire un comando che convalidi i risultati e restituisca i problemi in caso di fallimento della convalida è molto importante per migliorare la qualità della trasformazione. Se non è necessaria alcuna compilazione o convalida, ometti l'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 consente di non consentire l'estrazione della lezione dall'esecuzione corrente. ### Ripresa delle conversazioni AWS Transform custom 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 ``` **Importante** Le conversazioni possono essere riprese solo entro 30 giorni dalla creazione. Dopo 30 giorni, la conversazione non può più essere ripresa. ### Monitoraggio dei minuti degli agenti AWS Transform custom tiene traccia dei minuti [ consumati dall'](https://aws.amazon.com/transform/pricing/)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: ** Digita `/usage` al prompt di input per visualizzare gli attuali minuti dell'agente 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'`--limit`opzione imposta un [ budget massimo per ](https://aws.amazon.com/transform/pricing/) Agent Minutes per la sessione. Gli Agent Minutes riflettono il tempo di lavoro dell'agente attivo, non l'orario a 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 -t --limit ``` ## Apprendimento continuo Questa sezione descrive come rivedere e gestire le lezioni create dall'apprendimento continuo. ### Comprensione delle lezioni Il sistema di apprendimento continuo estrae automaticamente le lezioni dalle precedenti esecuzioni di una trasformazione. Il sistema li crea in modo asincrono in base a: + Feedback degli sviluppatori fornito in modalità interattiva + Problemi relativi al codice riscontrati durante le trasformazioni Le lezioni si accumulano nel tempo man mano che si esegue la trasformazione su diverse basi di codice. Il sistema le 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 utilizzare, puoi archiviare o eliminare completamente la lezione. ### Visualizzazione e gestione delle lezioni Usa 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, incluso il corpo della lezione, il suo impatto e il numero di sessioni precedenti in cui è stata consultata. ### 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 sessioni future. Tutte le lezioni archiviate sono raggruppate in modo da poterle rivedere e ripristinarne l'uso attivo. ### 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. **Nota** Gli esempi seguenti mostrano la sintassi di Linux e macOS (). `export` In Windows, imposta le variabili di ambiente in PowerShell Using. `$env:{{NAME}}="{{value}}"` Consultate le ** schede ** Windows (PowerShell) per i comandi equivalenti. **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 di lunga durata. **ATX\_DISABLE\_UPDATE\_CHECK ** Disabilita 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 checkpoint commit che Transform custom crea nel tuo repository mentre 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 ` 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 preapprovare strumenti e comandi specifici da eseguire senza richieste. È inoltre possibile richiedere un'autorizzazione esplicita per comandi di shell specifici indipendentemente dal livello di attendibilità. Queste impostazioni sono configurate nel `~/.aws/atx/trust-settings.yaml` file. Il file contiene tre elenchi: + `trustedTools`- Strumenti che possono essere eseguiti senza chiedere conferma + `trustedShellCommands`- Comandi Shell che possono essere eseguiti senza chiedere conferma + `alwaysPromptCommands`- Schemi di comando della shell che richiedono un'autorizzazione esplicita a meno che non vengano sovrascritti da`trustedShellCommands`, indipendentemente dal `-t` flag o dall'attendibilità della sessione. Questi modelli non vengono applicati in modalità non interattiva (). `-x` **Strumenti affidabili predefiniti: ** + `file_read` + `get_transformation_from_registry` + `list_available_transformations_from_registry` **Modifica delle impostazioni di fiducia: ** Puoi modificare manualmente il file trust-settings.yaml per aggiungere o rimuovere strumenti e comandi affidabili. Entrambi supportano i pattern glob wildcard utilizzando`trustedShellCommands`. `alwaysPromptCommands` `*` **Nota** Se un comando corrisponde a entrambi gli elenchi, ha la `trustedShellCommands` priorità. Quanto segue descrive ogni elenco di comandi e fornisce alcuni esempi: + `trustedShellCommands`- I comandi che corrispondono a questi schemi vengono eseguiti senza chiedere conferma, ignorando tutti gli altri guardrail. I pattern vengono confrontati con l'intera stringa di comando. Esempi: + `cd *`- Corrisponde ai comandi composti che iniziano con cd + `*&&*`- Affida tutti i comandi con gli operatori && + `alwaysPromptCommands`- I comandi che corrispondono a questi modelli richiedono un'autorizzazione esplicita a meno che non vengano sovrascritti da`trustedShellCommands`, indipendentemente dal flag o dall'attendibilità della `-t` sessione. Questi modelli non vengono applicati in modalità non interattiva (). `-x` I pattern vengono confrontati con ogni sottocomando nelle espressioni composte (`&&`,`||`, sostituzioni di comandi). Esempi: + `rm -rf *`- Richiede sempre i comandi ricorsivi di eliminazione forzata + `sudo *`- Richiede sempre l'esecuzione dei comandi con sudo + `find * -exec *`- Richiede sempre i comandi di ricerca con -exec **Session-level fidati: ** Durante i prompt interattivi, puoi scegliere: + `(y)es`- Esegui una volta + `(n)o`- Nega + `(t)rust`- Trust solo per la sessione corrente Session-level le impostazioni di fiducia sono temporanee e vengono ripristinate al riavvio della CLI, fornendo un'approvazione temporanea senza modificare permanentemente trust-settings.yaml. **Nota** L'attendibilità della sessione non è disponibile per i comandi corrispondenti all'elenco. `alwaysPromptCommands` ### Server Model Context Protocol (MCP) AWS Transform CLI 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. AWS Transform CLI 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à: + `command`(obbligatorio): il comando per eseguire il server + `args`(opzionale) - Matrice di argomenti della riga di comando + `env`(opzionale) - Variabili di ambiente da passare al processo del server I server HTTP remoti supportano le seguenti proprietà: + `url`(obbligatorio): l'URL HTTP o HTTPS del server MCP remoto + `headers`(opzionale): intestazioni HTTP da includere nelle richieste, con supporto per `${VAR_NAME}` l'espansione delle variabili di ambiente **Gestione dei server MCP: ** Visualizza l'elenco dei server MCP configurati: ``` atx mcp tools ``` Elenco degli strumenti disponibili offerti da un server MCP specifico: ``` atx mcp tools --server ``` **Monitoraggio dell'utilizzo: ** La CLI traccia 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: + Numero di chiamate per strumento + Numero di errori per utensile + Tempo totale di esecuzione per strumento + Dettagli dell'ultimo errore (se presente) ### 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 insieme alle sue funzionalità integrate. **Elenchi per la scoperta delle competenze: ** Le competenze vengono scoperte da quattro elenchi in ordine di precedenza. Se un'abilità con lo stesso nome esiste in più directory, la prima cartella dell'elenco ha la priorità: 1. `/.aws/atx/skills/`- Project-level, Trasforma AWS CLI-specific 1. `/.agents/skills/`- Project-level, cross-client (disponibile per qualsiasi strumento di agente compatibile) 1. `~/.aws/atx/skills/`- User-level, Trasforma AWS CLI-specific 1. `~/.agents/skills/`- User-level, cross-client (disponibile per qualsiasi strumento di agente compatibile) Le `.aws/atx/skills/` directory sono specifiche per Transform CLI AWS . Le `.agents/skills/` directory sono interclient, il che significa che le competenze ivi inserite sono disponibili per qualsiasi strumento di agente compatibile oltre alla Transform CLI. AWS **Struttura della directory delle competenze: ** Ogni abilità è una cartella 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. **Disabilitare un'abilità: ** Per evitare che una skill venga caricata senza rimuoverne i file, aggiungi `disable-model-invocation: true` al frontespizio: ``` --- name: my-skill description: When to use this skill disable-model-invocation: true --- ``` Quando questa proprietà è impostata, la CLI ignora l'abilità durante la scoperta. L'agente non può vedere o utilizzare l'abilità a meno che una definizione di trasformazione non gli indichi esplicitamente di leggere il file delle abilità. Usalo per disattivare temporaneamente un'abilità, contrassegnarla come in corso o conservare il materiale di riferimento destinato esclusivamente ai lettori umani. **Nota** I file di un'abilità disattivata rimangono su disco. Se una definizione di trasformazione indica all'agente di leggere un percorso di file specifico, l'agente può comunque accedere al contenuto. La `disable-model-invocation` proprietà impedisce il rilevamento automatico e l'inserimento del contesto, non l'accesso al file system. **Disponibilità delle competenze in base alla modalità di esecuzione: ** + **Modalità Exec ** (`atx custom def exec`con`--code-repository-path`): rileva le competenze dalle directory a livello di utente e di progetto. + **Modalità interattiva ** (`atx`): inizialmente vengono scoperte solo le competenze a livello di utente. Quando fornisci un percorso di repository di codice durante la sessione, vengono caricate anche le competenze a livello di progetto. **Verifica della scoperta delle competenze: ** Controlla il registro di debug della CLI dopo un'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. **Nota** Client-side le competenze richiedono la versione CLI 2.0 o successiva. #### Scelta tra Project-Level e competenze User-Level Il luogo in cui posizioni un'abilità determina chi ne trae beneficio e quando viene attivata. **Project-level competenze ** (`/.aws/atx/skills/`): Assegnali al controllo della versione in modo che ogni membro del team che esegue trasformazioni sul repository li scopra automaticamente. Usa le competenze a livello di progetto per: + Repository-specific controlli di conformità (regole Dockerfile, politiche Terraform, validatori di sicurezza della migrazione) + Standard di codifica organizzativa che si applicano a questa base di codice (modelli di osservabilità, gestione degli errori, convenzioni di denominazione) + Crea o testa script specifici per il progetto (linter personalizzati, funzioni di adattamento dell'architettura) + Guide alla migrazione delle API per le librerie interne utilizzate in questo repository **User-level competenze ** (`~/.aws/atx/skills/`): Queste rimangono sul computer e si attivano durante tutte le trasformazioni indipendentemente dal repository scelto come destinazione. Usa le competenze a livello utente per: + Strumenti personali per il flusso di lavoro (generatori di changelog, formattatori di messaggi di commit) + Cross-project preferenze (modelli di test preferiti, promemoria sullo stile della documentazione) + Controlli di conformità delle licenze richiesti dall'organizzazione in tutti i repository + Soglie di copertura o parametri di qualità che applichi a ogni base di codice con cui lavori **Suggerimenti per competenze efficaci: ** + Scrivi `description` campi chiari nel tuo `SKILL.md` frontespizio. L'agente utilizza questo campo per decidere quando un'abilità è rilevante. + Esci dagli script di convalida con codice 0 in caso di successo e diverso da zero in caso di fallimento. L'agente interpreta i codici di uscita per determinare la conformità. + Stampa messaggi di errore chiari e utilizzabili negli script. L'agente legge l'output per capire cosa correggere. + Inserisci le competenze nella directory interclient (`.agents/skills/`) a entrambi i livelli per condividerle con altri strumenti di sviluppo AI oltre a AWS Transform CLI. #### 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 abilità convalida i 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 della directory: ** ``` .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. ``` Lo script di convalida verifica i tag dell'immagine di base non bloccati, eseguiti come root, i segreti codificati nelle `ENV` direttive e le definizioni mancanti. `HEALTHCHECK` L'agente esegue lo script, corregge le violazioni utilizzando i modelli del file di riferimento ed esegue nuovamente 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 directory: ** ``` .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 precedenti e successivi. Ad esempio, `aws-sdk-v2-to-v3.md` mappa modelli simili `s3.putObject(params).promise()` all'equivalente modulare v3 utilizzando e. `S3Client` `PutObjectCommand` ### Tag e organizzazione È possibile organizzare le trasformazioni con tag per il controllo degli accessi e la categorizzazione. **Nota** Alcuni di questi comandi richiedono la specificazione dell'Amazon Resource Name (ARN) per una definizione di trasformazione. La struttura ARN è: `arn:aws:transform-custom:::package/` **Per elencare i tag per una trasformazione: ** ``` atx custom def list-tags --arn ``` **Per aggiungere tag a una trasformazione: ** ``` atx custom def tag --arn --tags '{"env":"prod","team":"backend"}' ``` **Per rimuovere i tag da una trasformazione: ** ``` atx custom def untag --arn --tag-keys "env,team" ``` I tag possono essere utilizzati per il controllo degli accessi raggruppati nelle policy IAM. È possibile creare policy 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//logs/-conversation.log ``` ------ #### [ Windows ] ``` %USERPROFILE%\.aws\atx\custom\\logs\-conversation.log ``` ------ Questi registri contengono la cronologia completa delle conversazioni per una sessione specifica. **Registri dei subagenti: ** ------ #### [ Linux and macOS ] ``` ~/.aws/atx/custom//logs/subagents/.log ``` ------ #### [ Windows ] ``` %USERPROFILE%\.aws\atx\custom\\logs\subagents\.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 gli 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. **Nota** Potrebbero essere presenti più file di registro di debug nella directory dei logs (ad esempio debug1.log, debug2.log). Rivedi e fornisci tutti i log pertinenti, ad esempio \~/. aws/atx/custom/ /\* e \~/. aws/atx/logs/ \*, quando si aprono i ticket di supporto per una risoluzione più rapida. ### Aggiornamenti CLI Mantieni aggiornata la tua 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 ``` ## Crea trasformazioni personalizzate Questa sezione descrive come creare, modificare e gestire definizioni di trasformazione personalizzate. ### Creazione di una nuova trasformazione Usa la CLI interattiva per creare una nuova definizione di trasformazione. **Per creare una definizione di trasformazione ** 1. Avvia la AWS Transform CLI: ``` atx ``` 1. Informa l'agente che desideri creare una nuova trasformazione. 1. Fornisci una descrizione chiara e dettagliata dell'obiettivo di trasformazione. Includi: + Lo stato di origine e di destinazione (ad esempio, «aggiornamento dalla versione X alla versione Y») + Sono richieste modifiche specifiche (ad esempio, «aggiornare le dichiarazioni di importazione, sostituire i metodi obsoleti») + Eventuali considerazioni o vincoli speciali 1. Quando l'agente richiede chiarimenti o informazioni aggiuntive, fornisci esempi specifici e materiali di riferimento. 1. Rivedi la definizione di trasformazione iniziale creata dall'agente. 1. Testate la trasformazione su una base di codice di esempio. 1. Esegui l'iterazione fornendo feedback, correzioni di codice o esempi aggiuntivi. 1. Salva la trasformazione localmente o pubblicala nel registro. **Procedure consigliate per la creazione di trasformazioni: ** + Inizia con trasformazioni semplici e ben definite prima di tentare trasformazioni complesse + Fornisci materiali di riferimento completi, tra cui guide alla migrazione ed esempi di codice + Effettua il test su più codebase di esempio prima della pubblicazione + Utilizza comandi deterministici di compilazione o convalida per consentire l'apprendimento continuo + Valuta la possibilità di suddividere le trasformazioni complesse in più passaggi più piccoli + Contrassegna le informazioni cruciali con «CRITICO:» o «IMPORTANTE:» nelle definizioni di trasformazione per assicurarti che l'agente dia priorità a questi requisiti + Quando è necessario seguire i requisiti esatti (ad esempio utilizzando un comando o un valore di stringa specifico), specificate esplicitamente la stringa completa nelle definizioni di trasformazione. Puoi racchiuderli tra virgolette bash per indicare chiaramente che si tratta di comandi da terminale o stringhe letterali, il che riduce la variabilità e garantisce un'esecuzione coerente ### Fornitura di materiali di riferimento È possibile fornire file di riferimento a AWS Transform custom specificando i percorsi dei file durante la conversazione. Questi file sono memorizzati nella `references/` cartella della definizione di trasformazione. Tipi di file di riferimento consigliati: + Before/after codice di esempio + Documentazione per le API, le librerie o le funzionalità coinvolte + Human-readable guide alla migrazione **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/ ``` **Nota** Sono supportati solo i file di testo (.md, .html, .txt, file di codice). I file binari, le immagini e i file RTF (ad es. .pdf, .png, .docx) non sono attualmente supportati. Spesso è possibile estrarre il contenuto del testo e utilizzarlo come riferimento. Se hai molti file di testo di piccole dimensioni, valuta la possibilità di concatenarli in pochi file con nomi descrittivi. C'è un limite totale di 10 MB per tutti i file. ### Modifica di una trasformazione esistente È possibile modificare le trasformazioni personalizzate sia prima che dopo averle salvate come bozze o 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 ** 1. Avvia la AWS Transform CLI: ``` atx ``` 1. Indica all'agente che desideri modificare una trasformazione esistente. 1. Scegli se: + Fornisci un percorso di file a una trasformazione archiviata localmente (cioè non una bozza salvata o pubblicata) + Richiedete l'elenco delle trasformazioni dal registro 1. Se scegli dal registro, seleziona la trasformazione che desideri modificare. 1. Collabora con l'agente per descrivere le modifiche che desideri apportare. 1. Prova la trasformazione aggiornata su una base di codice di esempio. 1. Se lo desideri, pubblica gli aggiornamenti nel registro. ### 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 ``` In questo modo la definizione di trasformazione viene scaricata 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 ``` **Importante** Questa operazione elimina definitivamente la definizione di trasformazione specificata dal tuo account. ### 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.