As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Fluxos de trabalho ## Executando transformações Esta seção descreve as diferentes formas de executar transformações e as opções para controlar o comportamento da execução. ### Modos de execução AWS O Transform custom oferece suporte a três modos de execução para acomodar diferentes fluxos de trabalho. **Modo conversacional interativo** Inicie a CLI com `atx` e peça ao agente que execute uma transformação por meio da linguagem natural. Esse modo permite que você tenha uma conversa completa com o agente, interrompa a execução a qualquer momento e forneça feedback durante o processo de transformação. Use esse modo quando quiser o máximo controle e a capacidade de guiar o agente em cenários complexos. **Execução direta interativa** Use `atx custom def exec -n -p ` para iniciar uma transformação específica de forma interativa. Esse modo permite que você revise e interaja com o agente no início, durante ou no final da execução. O agente fará uma pausa nos principais pontos de decisão e pedirá sua opinião. Isso é ideal para testar e refinar transformações antes de executá-las de forma autônoma. Você pode executar transformações no modo não interativo ou no modo headless. Non-interactive o modo suprime as solicitações durante uma transformação nomeada. O modo headless permite que você execute o agente com um prompt de texto sem formatação, ignorando totalmente a interface interativa. #### Non-interactive modo Use `atx custom def exec -n -p -x -t` para automação total. Adicione `-x` para executar no modo não interativo e `-t` para confiar em todas as ferramentas automaticamente sem aviso prévio. Esse modo foi projetado para integração de CI/CD tubulações e execução em massa, onde nenhuma intervenção humana está disponível ou é desejada. #### Modo sem cabeça Para concluir tarefas sem interagir com o agente, execute `atx -x "" -t` e forneça suas instruções em texto simples. ##### Execução de transformação sem interrupções Use esse modo para aplicar uma definição de transformação existente à sua base de código. A transformação executa cada etapa automaticamente sem exigir sua aprovação. ``` atx -x "apply transformation definition to " -t ``` ##### Desenvolvimento de transformação sem cabeça Crie ou modifique definições de transformação. Para converter uma definição de transformação antiga para o novo formato de habilidade (SKILL.md \+ referências/), execute o seguinte comando: ``` atx -x "convert transformation definition to skill and save as draft" -t ``` Para criar uma nova definição de transformação, execute o seguinte comando: ``` atx -x "create a transformation definition to with references docs " -t ``` ### Sinalizadores de comando comuns Ao executar transformações com`atx custom def exec`, os seguintes sinalizadores são comumente usados: + `-n`ou `--transformation-name` - Especifica o nome da transformação a ser executada + `-p`ou `--code-repository-path` - Especifica o caminho para sua base de código (use “.” para o diretório atual) + `-c`ou `--build-command` - Especifica o comando de compilação ou validação a ser executado + `-x`ou `--non-interactive` - Ativa o modo não interativo (sem solicitações do usuário) + `-t`ou `--trust-all-tools` - Confia automaticamente em todas as ferramentas sem aviso prévio + `-d`ou `--do-not-learn` - Impede a extração da lição dessa execução + `--tv`ou `--transformation-version` - Especifica uma versão específica da transformação + `-g`ou `--configuration` - Fornece um arquivo de configuração ou configuração embutida **Importante** O `--trust-all-tools` sinalizador `-t` or aprova automaticamente todas as execuções de ferramentas sem aviso prévio e ignora a maioria das barreiras de segurança (os comandos que correspondem à sua `alwaysPromptCommands` lista ainda exigem permissão explícita, a menos que sejam substituídos por). `trustedShellCommands` É necessário aprovar `--non-interactive` e `--trust-all-tools` é necessário para uma experiência totalmente autônoma, mas não é necessário para executar a transformação. Use com cautela em ambientes de produção. ### Usando arquivos de configuração AWS O Transform custom oferece suporte a arquivos de configuração opcionais no formato YAML ou JSON. Os arquivos de configuração permitem que você especifique parâmetros de execução e forneça contexto adicional ao agente. **Para usar um arquivo de configuração:** ``` atx custom def exec --configuration file://config.yaml ``` Você também pode fornecer a configuração como pares de valores-chave em linha: ``` atx custom def exec --configuration "key=value,key2=value2" ``` **Exemplo de arquivo de configuração (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 ``` O `additionalPlanContext` parâmetro fornece contexto adicional para o plano de execução do agente. Isso é especialmente útil com transformações AWS gerenciadas para personalizar seu comportamento de acordo com suas necessidades específicas. ### Comandos de compilação e validação O comando de compilação ou validação é um parâmetro opcional que especifica como validar seu código durante o processo de transformação. AWS O Transform custom tentará inferir o melhor comando de construção com base na transformação, se não for especificado, embora seja recomendado que seja específico em termos de qualidade. **Exemplos de comandos de compilação e validação:** + Java: `mvn clean install` ou `gradle build` + Python: ou `pytest` `python -m py_compile` + Node.js: `npm run build` ou `npm test` + Linters: `eslint .` ou `pylint .` Mesmo para linguagens ou transformações que não exigem construção, fornecer um comando que valide os resultados e retorne problemas se a validação falhar é muito importante para melhorar a qualidade da transformação. Se nenhuma compilação ou validação for necessária, omita da sua entrada. ### Controlando o comportamento de aprendizagem Por padrão, o AWS Transform custom extrai lições de cada execução de transformação. Você pode evitar o aprendizado para execuções específicas. **Para evitar o aprendizado com uma execução:** ``` atx custom def exec -n my-transformation -p ./my-project -d ``` O `--do-not-learn` sinalizador `-d` or opta por não permitir a extração da lição da execução atual. ### Retomando conversas AWS O Transform custom permite que você retome conversas anteriores dentro de 30 dias após a criação. **Para retomar a conversa mais recente:** ``` atx --resume ``` **Para retomar uma conversa específica:** ``` atx --conversation-id ``` **Importante** As conversas só podem ser retomadas dentro de 30 dias após a criação. Após 30 dias, a conversa não poderá mais ser retomada. ### Minutos do agente de rastreamento AWS O Transform custom rastreia os [minutos do agente](https://aws.amazon.com/transform/pricing/) consumidos durante uma sessão de transformação. Os minutos do agente se acumulam durante todo o ciclo de vida da conversa e são exibidos quando a conversa termina: ``` Agent minutes used: 12.50 ``` Os minutos do agente persistem em todas as interrupções. Se você interromper uma sessão com Ctrl\+C e retomá-la posteriormente, os minutos acumulados anteriormente serão transferidos e continuarão sendo acumulados na sessão retomada. **Para verificar os minutos do agente durante uma sessão interativa:** Digite `/usage` no prompt de entrada para exibir os minutos atuais acumulados do agente sem encerrar a conversa. **Para definir um limite de orçamento de minutos do agente:** ``` atx custom def exec -n my-transformation -p ./my-project --limit 30 ``` A `--limit` opção define um orçamento máximo de [minutos do agente](https://aws.amazon.com/transform/pricing/) para a sessão. Os minutos do agente refletem o tempo de trabalho do agente ativo, não o horário do relógio de parede. Quando o limite é atingido, a CLI exibe uma mensagem e sai com instruções para continuar: ``` ⚠️ Budget limit reached: 30.00 / 30.00 Agent Minutes. Exiting. ``` Você pode retomar a conversa mais tarde com um limite maior: ``` atx --conversation-id -t --limit ``` ## Aprendizagem contínua Esta seção descreve como revisar e gerenciar as aulas criadas pelo aprendizado contínuo. ### Entendendo as lições O sistema de aprendizado contínuo extrai automaticamente as lições de execuções anteriores de uma transformação. O sistema os cria de forma assíncrona com base em: + Feedback do desenvolvedor fornecido no modo interativo + Problemas de código encontrados durante as transformações As aulas se acumulam com o tempo à medida que você executa a transformação em diferentes bases de código. O sistema os aplica automaticamente para melhorar as execuções futuras. Cada lição pertence a uma categoria que contém todas as lições de um domínio similar para que vocês possam revisar as lições relacionadas em conjunto. Para aulas que você não gostaria de usar, você pode arquivar ou excluir totalmente a lição. ### Visualizando e gerenciando aulas Use o `learnings` comando para abrir uma sessão interativa para navegar e gerenciar as lições de uma definição de transformação. **Para abrir o visualizador de aulas:** ``` atx custom def learnings -n my-transformation ``` O visualizador abre uma lista de categorias de aulas, cada uma mostrando quantas aulas ativas ela contém. Selecione uma categoria para ver suas aulas e, em seguida, selecione uma lição para ver todos os detalhes, incluindo o corpo da aula, seu impacto e quantas edições anteriores a consultaram. ### Aulas de arquivamento e restauração O sistema aplica as aulas automaticamente. Se você não quiser que o sistema aplique uma lição, você pode arquivá-la. O sistema retém as aulas arquivadas, mas não as aplica a futuras execuções. Todas as aulas arquivadas são agrupadas para que você possa revisá-las e restaurá-las para uso ativo. ### Excluindo aulas Remova permanentemente uma lição que não seja útil. A exclusão não pode ser desfeita e o sistema pode reaprender uma lição excluída em futuras execuções. Uma lição deve ser arquivada antes de ser excluída. ## Configuração avançada Esta seção descreve os recursos avançados e as opções de configuração do AWS Transform custom. ### Variáveis de ambiente Você pode personalizar o comportamento da CLI usando variáveis de ambiente. **nota** Os exemplos a seguir mostram a sintaxe do Linux e do macOS (). `export` No Windows, defina as variáveis de ambiente PowerShell usando`$env:{{NAME}}="{{value}}"`. Consulte as guias **Windows (PowerShell)** para obter os comandos equivalentes. **ATX\_SHELL\_TIMEOUT** Substitua o tempo limite padrão para comandos do shell (900 seconds/15 minutos). ------ #### [ Linux and macOS ] ``` export ATX_SHELL_TIMEOUT=1800 # 30 minutes ``` ------ #### [ Windows (PowerShell) ] ``` $env:ATX_SHELL_TIMEOUT=1800 # 30 minutes ``` ------ Isso é útil para grandes bases de código ou processos de compilação de longa duração. **ATX\_DISABLE\_UPDATE\_CHECK** Desative as verificações automáticas de versão e as notificações de atualização durante a execução do comando. ------ #### [ 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** Configure a identidade do autor usada para os commits do ponto de verificação que o AWS Transform custom cria em seu repositório à medida que aplica as alterações durante uma transformação. Quando essas variáveis não são definidas, as confirmações do ponto de verificação são atribuídas a uma identidade padrão ()`ATX Bot `. Defina as duas variáveis para atribuir pontos de verificação a um autor específico. ------ #### [ 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" ``` ------ ### Configurações de confiança As configurações de confiança permitem que você pré-aprove ferramentas e comandos específicos para execução sem solicitações. Você também pode exigir permissão explícita para comandos específicos do shell, independentemente do nível de confiança. Essas configurações são definidas no arquivo `~/.aws/atx/trust-settings.yaml`. O arquivo contém três listas: + `trustedTools`- Ferramentas que podem ser executadas sem aviso + `trustedShellCommands`- Comandos de shell que podem ser executados sem aviso + `alwaysPromptCommands`- Padrões de comando do Shell que exigem permissão explícita, a menos que sejam substituídos`trustedShellCommands`, independentemente do `-t` sinalizador ou da confiança da sessão. Esses padrões não são aplicados no modo não interativo ()`-x`. **Ferramentas confiáveis padrão:** + `file_read` + `get_transformation_from_registry` + `list_available_transformations_from_registry` **Editando configurações de confiança:** Você pode editar manualmente o arquivo trust-settings.yaml para adicionar ou remover ferramentas e comandos confiáveis. Ambos `trustedShellCommands` `alwaysPromptCommands` suportam padrões globais de curingas usando. `*` **nota** Se um comando corresponder às duas listas, `trustedShellCommands` terá prioridade. O seguinte descreve cada lista de comandos e fornece exemplos: + `trustedShellCommands`- Os comandos que correspondem a esses padrões são executados sem aviso prévio, ignorando todas as outras grades de proteção. Os padrões são comparados com a cadeia de comando completa. Exemplos: + `cd *`- Combina comandos compostos começando com cd + `*&&*`- Confia em todos os comandos com operadores && + `alwaysPromptCommands`- Os comandos que correspondem a esses padrões exigem permissão explícita, a menos que sejam substituídos por`trustedShellCommands`, independentemente do `-t` sinalizador ou da confiança da sessão. Esses padrões não são aplicados no modo não interativo ()`-x`. Os padrões são comparados com cada subcomando em expressões compostas (`&&`,`||`, substituições de comandos). Exemplos: + `rm -rf *`- Sempre solicita comandos recursivos de exclusão forçada + `sudo *`- Sempre solicita comandos executados com sudo + `find * -exec *`- Sempre solicita comandos de localização com -exec **Session-level confiança:** Durante os prompts interativos, você pode escolher: + `(y)es`- Execute uma vez + `(n)o`- Negar + `(t)rust`- Confie somente na sessão atual Session-level as configurações de confiança são temporárias e são redefinidas quando a CLI é reiniciada, fornecendo aprovação temporária sem modificar permanentemente trust-settings.yaml. **nota** A confiança da sessão não está disponível para comandos que correspondam à sua `alwaysPromptCommands` lista. ### Servidores do Model Context Protocol (MCP) O AWS Transform CLI oferece suporte a servidores Model Context Protocol (MCP), que ampliam sua funcionalidade com ferramentas adicionais. **Configuração:** Configure os servidores MCP no `~/.aws/atx/mcp.json` arquivo. O AWS Transform CLI suporta dois tipos de servidores MCP: servidores locais baseados em comandos e servidores HTTP remotos. **Servidores locais baseados em comandos:** Os servidores locais são executados como processos secundários em sua máquina. Configure-os com a `command` propriedade: ``` { "mcpServers": { "my-local-server": { "command": "npx", "args": ["-y", "@example/mcp-server"] } } } ``` **Servidores HTTP remotos:** Os servidores remotos se conectam aos servidores MCP hospedados em uma URL HTTP ou HTTPS. Configure-os com a `url` propriedade: ``` { "mcpServers": { "my-remote-server": { "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${MCP_API_TOKEN}" } } } } ``` A `headers` propriedade é opcional e oferece suporte à expansão de variáveis de ambiente usando a `${VAR_NAME}` sintaxe. Isso permite que você armazene valores confidenciais, como tokens de API, em variáveis de ambiente e não no arquivo de configuração. **Propriedades de configuração:** Os servidores locais baseados em comandos oferecem suporte às seguintes propriedades: + `command`(obrigatório) - O comando para executar o servidor + `args`(opcional) - Matriz de argumentos de linha de comando + `env`(opcional) - Variáveis de ambiente a serem passadas para o processo do servidor Os servidores HTTP remotos oferecem suporte às seguintes propriedades: + `url`(obrigatório) - O URL HTTP ou HTTPS do servidor MCP remoto + `headers`(opcional) - cabeçalhos HTTP a serem incluídos nas solicitações, com suporte para expansão de variáveis de `${VAR_NAME}` ambiente **Gerenciando servidores MCP:** Veja a lista de servidores MCP configurados: ``` atx mcp tools ``` Liste as ferramentas disponíveis oferecidas por um servidor MCP específico: ``` atx mcp tools --server ``` **Rastreamento de uso:** A CLI rastreia automaticamente o uso da ferramenta MCP durante as execuções de transformação. As estatísticas de uso são mantidas, como `mcp_usage.json` no diretório de conversas ao lado`metadata.json`. O arquivo registra métricas por ferramenta para cada execução, incluindo: + Número de invocações por ferramenta + Número de erros por ferramenta + Tempo total de execução por ferramenta + Detalhes do último erro (se houver) ### Client-Side Habilidades Client-side habilidades são recursos adicionais que ampliam o agente durante as execuções de transformação. Eles permitem que você forneça ferramentas, scripts e instruções personalizados que o agente pode usar junto com seus recursos integrados. **Diretórios de descoberta de habilidades:** As habilidades são descobertas em quatro diretórios em ordem de precedência. Se uma habilidade com o mesmo nome existir em vários diretórios, o primeiro diretório na lista terá prioridade: 1. `/.aws/atx/skills/`- Project-level, AWS Transformar CLI-specific 1. `/.agents/skills/`- Project-level, multicliente (disponível para qualquer ferramenta de agente compatível) 1. `~/.aws/atx/skills/`- User-level, AWS Transformar CLI-specific 1. `~/.agents/skills/`- User-level, multicliente (disponível para qualquer ferramenta de agente compatível) Os `.aws/atx/skills/` diretórios são específicos da CLI do AWS Transform. Os `.agents/skills/` diretórios são multiclientes, o que significa que as habilidades colocadas lá estão disponíveis para qualquer ferramenta de agente compatível além da CLI do Transform AWS . **Estrutura do diretório de habilidades:** Cada habilidade é um diretório contendo um `SKILL.md` arquivo com o 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... ``` O `name` campo deve corresponder ao nome do diretório principal. **Desativando uma habilidade:** Para evitar que uma habilidade seja carregada sem remover seus arquivos, adicione `disable-model-invocation: true` ao frontmatter: ``` --- name: my-skill description: When to use this skill disable-model-invocation: true --- ``` Quando essa propriedade é definida, a CLI ignora a habilidade durante a descoberta. O agente não pode ver nem usar a habilidade, a menos que uma definição de transformação o instrua explicitamente a ler o arquivo de habilidade. Use isso para desativar temporariamente uma habilidade, marcá-la como trabalho em andamento ou manter o material de referência destinado somente a leitores humanos. **nota** Os arquivos de uma habilidade desativada permanecem no disco. Se uma definição de transformação instruir o agente a ler um caminho de arquivo específico, o agente ainda poderá acessar o conteúdo. A `disable-model-invocation` propriedade impede a descoberta automática e a injeção de contexto, não o acesso ao sistema de arquivos. **Disponibilidade de habilidades por modo de execução:** + **Modo executivo** (`atx custom def exec`com`--code-repository-path`) - descobre habilidades dos diretórios em nível de usuário e de projeto. + **Modo interativo** (`atx`) - Somente habilidades em nível de usuário são descobertas inicialmente. Quando você fornece um caminho de repositório de código durante a sessão, as habilidades em nível de projeto também são carregadas. **Verificando a descoberta de habilidades:** Verifique o registro de depuração da CLI após uma execução para verificar quais habilidades foram descobertas: ------ #### [ 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 ``` ------ As habilidades que falham na validação são ignoradas com um aviso nos registros de depuração. **nota** Client-side as habilidades exigem CLI versão 2.0 ou posterior. #### Escolhendo entre Project-Level e User-Level habilidades O local onde você coloca uma habilidade determina quem se beneficia dela e quando ela é ativada. **Project-level habilidades** (`/.aws/atx/skills/`): Comprometa-os ao controle de versão para que cada membro da equipe que executa transformações no repositório os descubra automaticamente. Use habilidades em nível de projeto para: + Repository-specific verificações de conformidade (regras do Dockerfile, políticas do Terraform, validadores de segurança de migração) + Padrões de codificação da organização que se aplicam a essa base de código (padrões de observabilidade, tratamento de erros, convenções de nomenclatura) + Crie ou teste scripts exclusivos para o projeto (impressoras personalizadas, funções de condicionamento físico de arquitetura) + Guias de migração de API para bibliotecas internas usadas neste repositório **User-level habilidades** (`~/.aws/atx/skills/`): Eles permanecem na sua máquina e são ativados durante todas as transformações, independentemente do repositório de destino. Use habilidades em nível de usuário para: + Ferramentas pessoais de fluxo de trabalho (geradores de changelog, formatadores de mensagens de confirmação) + Cross-project preferências (padrões de teste preferidos, lembretes de estilo de documentação) + Verificações de conformidade de licenças que sua organização exige em todos os repositórios + Limites de cobertura ou barreiras de qualidade que você impõe em cada base de código com a qual trabalha **Dicas para habilidades eficazes:** + Escreva `description` campos claros em seu `SKILL.md` frontmatter. O agente usa esse campo para decidir quando uma habilidade é relevante. + Saia dos scripts de validação com código 0 em caso de sucesso e diferente de zero em caso de falha. O agente interpreta os códigos de saída para determinar a conformidade. + Imprima mensagens de erro claras e acionáveis em scripts. O agente lê a saída para entender o que corrigir. + Coloque as habilidades no diretório entre clientes (`.agents/skills/`) em qualquer nível para compartilhá-las com outras ferramentas de desenvolvimento de IA além da CLI do AWS Transform. #### Client-Side Exemplos de habilidades Esses exemplos mostram dois padrões comuns: uma habilidade de validação baseada em script e uma habilidade somente de referência. ##### Exemplo: Dockerfile Compliance Checker () Script-Based Essa habilidade valida os Dockerfiles em relação às melhores práticas operacionais e de segurança. Ele usa um script de validação que o agente executa antes e depois de fazer as alterações. **Estrutura de diretórios:** ``` .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. ``` O script de validação verifica se há tags de imagem base não fixadas, executadas como raiz, segredos codificados em `ENV` diretivas e definições ausentes. `HEALTHCHECK` O agente executa o script, corrige violações usando padrões do arquivo de referência e executa novamente o script para confirmar a conformidade. ##### Exemplo: Auxiliar de depreciação da API () Reference-Only Essa habilidade orienta o agente na substituição de chamadas de API obsoletas durante as transformações de upgrade. Ele usa somente arquivos de referência sem scripts. **Estrutura de diretórios:** ``` .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 ``` Os arquivos de referência contêm exemplos de código de antes e depois. Por exemplo, `aws-sdk-v2-to-v3.md` mapeia padrões como `s3.putObject(params).promise()` o equivalente modular v3 usando `S3Client` e. `PutObjectCommand` ### Tags e organização Você pode organizar transformações com tags para controle de acesso e categorização. **nota** Alguns desses comandos exigem a especificação do Amazon Resource Name (ARN) para uma definição de transformação. A estrutura do ARN é: `arn:aws:transform-custom:::package/` **Para listar tags para uma transformação:** ``` atx custom def list-tags --arn ``` **Para adicionar tags a uma transformação:** ``` atx custom def tag --arn --tags '{"env":"prod","team":"backend"}' ``` **Para remover tags de uma transformação:** ``` atx custom def untag --arn --tag-keys "env,team" ``` As tags podem ser usadas para controle de acesso agrupado nas políticas do IAM. Você pode criar políticas que concedam permissões para todas as transformações com tags específicas (por exemplo, todas as transformações marcadas com `team:frontend` ou`environment:production`). ### Logs AWS O Transform CLI mantém três tipos de registros para solução de problemas e depuração. **Registros de conversas:** ------ #### [ Linux and macOS ] ``` ~/.aws/atx/custom//logs/-conversation.log ``` ------ #### [ Windows ] ``` %USERPROFILE%\.aws\atx\custom\\logs\-conversation.log ``` ------ Esses registros contêm o histórico completo de conversas de uma sessão específica. **Registros do subagente:** ------ #### [ Linux and macOS ] ``` ~/.aws/atx/custom//logs/subagents/.log ``` ------ #### [ Windows ] ``` %USERPROFILE%\.aws\atx\custom\\logs\subagents\.log ``` ------ Esses registros contêm saídas de subagentes que o agente principal gera durante as transformações. Você não precisa gerenciar subagentes diretamente. **Registros de depuração do desenvolvedor:** ------ #### [ 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 ``` ------ Esses registros fornecem informações avançadas de solução de problemas para a própria CLI. **nota** Pode haver vários arquivos de log de depuração no diretório de logs (ou seja, debug1.log, debug2.log). Revise e forneça todos os registros relevantes, por exemplo, \~/. aws/atx/custom/ /\* e \~/. aws/atx/logs/ \*, ao abrir tickets de suporte para uma resolução mais rápida. ### Atualizações da CLI Mantenha sua CLI atualizada para acessar novos recursos e melhorias. **Para verificar se há atualizações:** ``` atx update --check ``` **Para atualizar para a versão mais recente:** ``` atx update ``` **Para atualizar para uma versão específica:** ``` atx update --target-version ``` ## Crie transformações personalizadas Esta seção descreve como criar, modificar e gerenciar definições de transformação personalizadas. ### Criando uma nova transformação Use a CLI interativa para criar uma nova definição de transformação. **Para criar uma definição de transformação** 1. Inicie a CLI do AWS Transform: ``` atx ``` 1. Diga ao agente que você deseja criar uma nova transformação. 1. Forneça uma descrição clara e detalhada do objetivo da transformação. Inclusão: + O estado de origem e de destino (por exemplo, “atualização da versão X para a versão Y”) + Mudanças específicas necessárias (por exemplo, “atualizar instruções de importação, substituir métodos obsoletos”) + Quaisquer considerações ou restrições especiais 1. Quando o agente solicitar esclarecimentos ou informações adicionais, forneça exemplos específicos e materiais de referência. 1. Revise a definição de transformação inicial criada pelo agente. 1. Teste a transformação em uma base de código de amostra. 1. Faça iterações fornecendo feedback, correções de código ou exemplos adicionais. 1. Salve a transformação localmente ou publique-a no registro. **Práticas recomendadas para criar transformações:** + Comece com transformações simples e bem definidas antes de tentar transformações complexas + Forneça materiais de referência abrangentes, incluindo guias de migração e amostras de código + Teste em várias bases de código de amostra antes de publicar + Use comandos determinísticos de construção ou validação para permitir o aprendizado contínuo + Considere dividir transformações complexas em várias etapas menores + Marque as informações cruciais com “CRÍTICO:” ou “IMPORTANTE:” em suas definições de transformação para garantir que o agente priorize esses requisitos + Quando você precisar que os requisitos exatos sejam seguidos (como usar um comando específico ou um valor de string), especifique explicitamente a string completa em suas definições de transformação. Você pode colocá-los em aspas bash para indicar claramente que são comandos de terminal ou strings literais, o que reduz a variabilidade e garante uma execução consistente ### Fornecimento de materiais de referência Você pode fornecer arquivos de referência ao AWS Transform custom especificando os caminhos dos arquivos durante a conversa. Esses arquivos são armazenados na `references/` pasta da definição de transformação. Tipos recomendados de arquivos de referência: + Before/after código de exemplo + Documentação para APIs, bibliotecas ou recursos envolvidos + Human-readable guias de migração **Para fornecer um arquivo de referência:** ``` Take a look at the documentation here: /path/to/migration-guide.md ``` Você também pode fornecer um diretório contendo vários arquivos de referência: ``` Take a look at the docs we have here: /path/to/docs/ ``` **nota** Somente arquivos baseados em texto (.md, .html, .txt, arquivos de código) são suportados. No momento, não há suporte para arquivos binários, imagens e arquivos de rich text (por exemplo, .pdf, .png, .docx). Muitas vezes, é possível extrair o conteúdo do texto e usá-lo como referência. Se você tiver muitos arquivos de texto pequenos, considere concatená-los em alguns arquivos com nomes descritivos. Há um limite total de 10 MB para todos os arquivos. ### Modificando uma transformação existente Você pode modificar as transformações personalizadas antes e depois de salvá-las como rascunhos ou publicá-las. Você não pode modificar AWS transformações gerenciadas. Se precisar personalizá-los, você pode fornecer contexto adicional usando o arquivo de configuração. **Para modificar uma transformação existente** 1. Inicie a CLI do AWS Transform: ``` atx ``` 1. Diga ao agente que você deseja modificar uma transformação existente. 1. Escolha se deseja: + Forneça um caminho de arquivo para uma transformação armazenada localmente (ou seja, não um rascunho salvo ou publicado) + Solicite a lista de transformações do registro 1. Se escolher no registro, selecione a transformação que você deseja modificar. 1. Trabalhe com o agente para descrever as alterações que você deseja fazer. 1. Teste a transformação atualizada em uma base de código de amostra. 1. Publique suas atualizações no registro, se desejar. ### Publicando e gerenciando transformações Você pode publicar e gerenciar suas transformações usando a experiência interativa ou com os seguintes comandos. **Para salvar uma transformação como rascunho:** ``` atx custom def save-draft -n my-transformation --description "Description of the transformation" --sd ./transformation-directory ``` **Para publicar uma transformação:** ``` atx custom def publish -n my-transformation --description "Description of the transformation" --sd ./transformation-directory ``` **Para listar as transformações disponíveis:** ``` atx custom def list ``` **Para baixar uma definição de transformação:** ``` atx custom def get -n my-transformation ``` Isso baixa a definição de transformação para seu diretório de trabalho atual. Você pode especificar um diretório de destino com o `--td` sinalizador e uma versão com o `--tv` sinalizador. **Para excluir uma definição de transformação:** ``` atx custom def delete -n my-transformation ``` **Importante** Isso exclui permanentemente a definição de transformação especificada da sua conta. ### Gerenciando versões de transformação AWS O Transform custom mantém versões de suas definições de transformação. Você pode especificar uma versão ao executar ou baixar uma transformação. **Para executar uma versão específica:** ``` atx custom def exec -n my-transformation --tv v1 -p ./my-project ``` **Para baixar uma versão específica:** ``` atx custom def get -n my-transformation --tv v1 ``` Se nenhuma versão for especificada, a versão mais recente será usada.