本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

工作流

执行转换

本节介绍执行转换的不同方法和控制执行行为的选项。

执行模式

AWS 自定义转换支持三种执行模式，以适应不同的工作流程。

交互式对话模式

启动 CLI atx 并要求代理通过自然语言执行转换。此模式允许您与代理进行全面对话，随时中断执行，并在转换过程中提供反馈。

如果您想要最大限度地控制并能够引导代理完成复杂场景，请使用此模式。

直接交互式执行

用于atx custom def exec -n <transformation-name> -p <path>以交互方式开始特定的转换。此模式允许您在执行开始、执行期间或结束时查看代理并与之交互。代理将在关键决策点停下来并征求您的意见。

这非常适合在自动运行变换之前对其进行测试和完善。

你可以在非交互模式或无头模式下运行转换。 Non-interactive 模式会抑制命名转换期间的提示。Headless 模式允许您使用纯文本提示运行代理，完全绕过交互式界面。

Non-interactive 模式

atx custom def exec -n <transformation-name> -p <path> -x -t用于完全自动化。添加-x以在非交互模式下运行，并在-t不提示的情况下自动信任所有工具。

此模式专为无需或不需要人工干预的 CI/CD 管道集成和批量执行而设计。

无头模式

要在不与代理交互的情况下完成任务，请运行atx -x "<prompt>" -t并以纯文本形式提供指令。

无头转换执行

使用此模式将现有的转换定义应用于您的代码库。转换会自动运行每个步骤，无需您的批准。

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

Headless 转型开发

创建或修改转换定义。

要将旧的转换定义转换为新的技能格式（SKILL.md + references/），请运行以下命令：

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

要创建新的转换定义，请运行以下命令：

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

常用命令标志

使用执行转换时atx custom def exec，通常使用以下标志：

使用配置文件

AWS 自定义转换支持 YAML 或 JSON 格式的可选配置文件。配置文件允许您指定执行参数并为代理提供其他上下文。

要使用配置文件，请执行以下操作：

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

你也可以将配置作为内联键值对提供：

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

配置文件示例 (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

该additionalPlanContext参数为代理的执行计划提供了额外的上下文。这对于 AWS管理的转换特别有用，可以根据您的特定需求自定义其行为。

生成和验证命令

生成或验证命令是一个可选参数，用于指定在转换过程中如何验证代码。 AWS 如果未指定，Transform custom 将尝试根据转换推断出最佳的构建命令，但建议具体考虑质量。

生成和验证命令的示例：

即使对于不需要构建的语言或转换，提供一个命令来验证结果并在验证失败时返回问题，对于提高转换质量也非常重要。

如果不需要构建或验证，请在输入中省略。

控制学习行为

默认情况下，自定义 AWS 转换会从每次转换执行中提取经验教训。您可以阻止学习特定的处决。

要防止从处决中学习，请执行以下操作：

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

-d或--do-not-learn标志选择不允许从当前执行中提取课程。

恢复对话

AWS Transform custom 允许您在创建后的 30 天内恢复之前的对话。

要恢复最近的对话，请执行以下操作：

atx --resume

要恢复特定对话，请执行以下操作：

atx --conversation-id <conversation-id>

追踪代理会议记录

AWS 自定义转换可跟踪在转换会话期间消耗的代理分钟数。座席分钟数在整个对话生命周期中累积，并在对话结束时显示：

Agent minutes used: 12.50

在中断期间，代理分钟数保持不变。如果您使用 Ctrl+C 中断会话并在稍后恢复，则先前累积的分钟数会延续并继续累积在恢复的会话中。

要在交互式会话期间查看座席会议记录，请执行以下操作：

/usage在输入提示符处键入以显示当前累积的座席分钟数，而不会结束对话。

要设置座席分钟数预算限制，请执行以下操作：

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

该--limit选项为会话设置座席分钟数的最大预算。座席分钟数反映的是活跃座席的工作时间，而不是挂钟时间。达到限制后，CLI 会显示一条消息并退出并显示恢复指示：

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

您可以稍后恢复对话，但限制有所增加：

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

持续学习

本节介绍如何复习和管理持续学习所产生的课程。

理解教训

持续学习系统会自动从之前的转型中提取经验教训。系统基于以下条件异步创建它们：

当你跨不同的代码库运行转换时，经验会随着时间的推移而积累。系统会自动应用它们来改进 future 的运行。每节课都属于一个类别，其中包含所有属于相似领域的课程，因此您可以一起复习相关的课程。对于你不想使用的课程，你可以将课程全部存档或删除。

查看和管理课程

使用learnings命令打开交互式会话，用于浏览和管理转换定义的课程。

要打开课程查看器，请执行以下操作：

atx custom def learnings -n my-transformation

查看器会打开课程类别列表，每个类别都显示其包含的活跃课程数量。选择一个类别以查看其课程，然后选择一节课以查看其全部细节，包括课程正文、其影响以及之前有多少次课程参考了该课程。

归档和恢复课程

系统会自动应用课程。如果您不希望系统应用课程，则可以将其存档。系统会保留已存档的课程，但不会将其应用于 future 的课程。所有存档的课程都分组在一起，因此您可以查看它们并将任何课程恢复为活跃使用。

删除课程

永久移除无用的课程。删除操作无法撤消，系统可能会从 future 的运行中重新学习已删除的课程。

课程必须先存档，然后才能将其删除。

高级配置

本节介绍了 Transform custo AWS m 的高级功能和配置选项。

环境变量

您可以使用环境变量自定义 CLI 行为。

ATX_SHELL_TIMEOUT

覆盖 shell 命令的默认超时时间（900 seconds/15 分钟）。

Linux and macOS

export ATX_SHELL_TIMEOUT=1800  # 30 minutes

Windows (PowerShell)

$env:ATX_SHELL_TIMEOUT=1800  # 30 minutes

这对于大型代码库或长时间运行的构建过程很有用。

ATX_DISABLE_UPDATE_CHECK

在命令执行期间禁用自动版本检查和更新通知。

Linux and macOS

export ATX_DISABLE_UPDATE_CHECK=true

Windows (PowerShell)

$env:ATX_DISABLE_UPDATE_CHECK="true"

ATX_GIT_COMMITTER_NAME 和 ATX_GIT_COMMMITTER_EMAIL

配置 Transform custom 在 AWS 转换期间应用更改时在仓库中创建的检查点提交所使用的作者身份。如果未设置这些变量，则检查点提交将归因于默认身份 (ATX Bot <checkpoint@atx.bot>)。将两个变量都设置为将检查点归因于特定作者。

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"

信任设置

信任设置允许您在没有提示的情况下预先批准要执行的特定工具和命令。无论信任级别如何，您也可以要求为特定 shell 命令提供明确权限。这些设置在 ~/.aws/atx/trust-settings.yaml 文件中进行配置。

该文件包含三个列表：

默认可信工具：

编辑信任设置：

您可以手动编辑 trust-settings.yaml 文件以添加或删除受信任的工具和命令。两者trustedShellCommands都alwaysPromptCommands支持使用 glob 通配符模式。*

以下内容描述了每个命令列表并提供了示例：

Session-level 信任：

在交互式提示中，您可以选择：

Session-level 信任设置是临时的，在 CLI 重新启动时会重置，无需永久修改 trust-settings.yaml 即可提供临时批准。

模型上下文协议 (MCP) 服务器

T AWS ransform CLI 支持模型上下文协议 (MCP) 服务器，该服务器通过其他工具扩展其功能。

配置：

在~/.aws/atx/mcp.json文件中配置 MCP 服务器。T AWS ransform CLI 支持两种类型的 MCP 服务器：基于命令的本地服务器和远程 HTTP 服务器。

基于命令的本地服务器：

本地服务器作为子进程在您的计算机上运行。使用以下command属性对其进行配置：

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

远程 HTTP 服务器：

远程服务器连接到托管在 HTTP 或 HTTPS 网址上的 MCP 服务器。使用以下url属性对其进行配置：

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

该headers属性是可选的，支持使用${VAR_NAME}语法扩展环境变量。这允许您将 API 令牌等敏感值存储在环境变量中，而不是存储在配置文件中。

配置属性：

基于命令的本地服务器支持以下属性：

远程 HTTP 服务器支持以下属性：

管理 MCP 服务器：

查看已配置的 MCP 服务器列表：

atx mcp tools

列出特定 MCP 服务器提供的可用工具：

atx mcp tools --server <server-name>

使用情况跟踪：

在转换执行期间，CLI 会自动跟踪 MCP 工具的使用情况。使用情况统计信息保留mcp_usage.json在旁边metadata.json的对话目录中。该文件记录每次执行的每个工具的指标，包括：

Client-Side 技能

Client-side 技能是在转换执行期间扩展代理的附加能力。它们允许您提供自定义工具、脚本和指令，代理可以将其与其内置功能一起使用。

技能发现目录：

技能按优先顺序从四个目录中找到。如果同名技能存在于多个目录中，则列表中的第一个目录优先：

这些.aws/atx/skills/目录特定于 Trans AWS form CLI。这些.agents/skills/目录是跨客户端的，这意味着除了 Trans AWS form CLI 之外，任何兼容的代理工具都可以使用放在那里的技能。

技能目录结构：

每个技能都是一个目录，其中包含一个带有 YAML frontmatter 的SKILL.md文件：

~/.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 格式：

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

Instructions for the agent...

该name字段必须与父目录名称匹配。

禁用技能：

要防止在不移除技能文件的情况下加载技能，请在 frontmatt disable-model-invocation: true er 中添加：

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

设置此属性后，CLI 将在发现期间跳过该技能。除非转换定义明确指示代理读取技能文件，否则代理无法查看或使用该技能。使用它可以暂时禁用某项技能，将其标记为正在进行中，或者保留仅供人类读者使用的参考资料。

按执行模式划分的技能可用性：

验证技能发现：

运行后查看 CLI 的调试日志，以验证发现了哪些技能：

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

未通过验证的技能将被跳过，并在调试日志中显示警告。

在 Project-Level 和 User-Level 技能之间做出选择

你将技能放在哪里，决定谁能从中受益，以及技能何时激活。

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

将它们提交给版本控制，这样每个对仓库运行转换的团队成员都会自动发现它们。使用项目等级技能获得：

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

无论您以哪个存储库为目标，它们都会保留在您的计算机上，并在所有转换过程中激活。将用户级别的技能用于：

有效技能小贴士：

Client-Side 技能示例

这些示例显示了两种常见模式：基于脚本的验证技能和仅供参考的技能。

示例：Dockerfile 合规性检查器 () Script-Based

该技能可根据安全和操作最佳实践验证 Dockerfile。它使用验证脚本，代理在进行更改之前和之后都运行该脚本。

目录结构：

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

验证脚本会检查未固定的基础图像标签、以 root 身份运行、ENV指令中的硬编码密钥以及缺少的定义。HEALTHCHECK代理运行脚本，使用参考文件中的模式修复违规行为，然后重新运行脚本以确认合规性。

示例：API 弃用助手 () Reference-Only

此技能指导代理在升级转换期间替换已弃用的 API 调用。它只使用没有脚本的参考文件。

目录结构：

.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

参考文件包含之前和之后的代码示例。例如，使用S3Client和将模式aws-sdk-v2-to-v3.md映射s3.putObject(params).promise()到模块化 v3 等效版本PutObjectCommand。

标签和组织

您可以使用标签组织转换，以便进行访问控制和分类。

要列出转换的标签，请执行以下操作：

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

要为转换添加标签，请执行以下操作：

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

要从转换中移除标签，请执行以下操作：

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

标签可用于 IAM 策略中的分组访问控制。您可以创建策略，授予所有带有特定标签的转换（例如，所有用team:frontend或environment:production标记的转换）的权限。

日志

AWS Transform CLI 维护三种类型的日志，用于故障排除和调试。

对话日志：

Linux and macOS

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

Windows

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

这些日志包含特定会话的完整对话历史记录。

子代理日志：

Linux and macOS

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

Windows

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

这些日志包含主代理在变换期间生成的子代理的输出。您无需直接管理子代理。

开发者调试日志：

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

这些日志为 CLI 本身提供了高级故障排除信息。

CLI 更新

保持您的 CLI 处于最新状态，以访问新功能和改进。

要检查更新，请执行以下操作：

atx update --check

要更新到最新版本，请执行以下操作：

atx update

要更新到特定版本，请执行以下操作：

atx update --target-version <version>

创建自定义变换

本节介绍如何创建、修改和管理自定义转换定义。

创建新的转换

使用交互式 CLI 创建新的转换定义。

创建转换定义

创建转换的最佳实践：

提供参考资料

您可以通过在对话期间指定文件路径来向 T AWS ransform custom 提供参考文件。这些文件存储在转换定义的references/文件夹中。

推荐的参考文件类型：

要提供参考文件，请执行以下操作：

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

您也可以提供一个包含多个参考文件的目录：

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

修改现有转换

在将自定义变换保存为草稿或发布它们之前和之后，都可以对其进行修改。您无法修改 AWS由管理的转换。如果您需要对其进行自定义，则可以使用配置文件提供其他上下文。

修改现有转换

发布和管理转换

您可以使用交互式体验或使用以下命令来发布和管理您的转换。

要将转换另存为草稿，请执行以下操作：

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

要发布转换，请执行以下操作：

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

要列出可用的变换，请执行以下操作：

atx custom def list

要下载转换定义，请执行以下操作：

atx custom def get -n my-transformation

这会将转换定义下载到您当前的工作目录。您可以使用标志指定目标目录和带有--td--tv标志的版本。

要删除转换定义，请执行以下操作：

atx custom def delete -n my-transformation

管理转换版本

AWS 自定义转换会维护转换定义的版本。您可以在执行或下载转换时指定版本。

要执行特定版本，请执行以下操作：

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

要下载特定版本，请执行以下操作：

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

如果未指定版本，则使用最新版本。