View a markdown version of this page

工作流 - AWS 转换

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

工作流

执行转换

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

执行模式

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

交互式对话模式

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

当您想要最大限度地控制并能够指导代理完成复杂场景时,请使用此模式。

直接交互式执行

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

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

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

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
无头转型开发

创建或修改转换定义。

将传统转换定义转换为新技能格式 (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,常用以下标志:

  • -n 要么 --transformation-name -指定要执行的转换的名称

  • -p 要么 --code-repository-path -指定代码库的路径(使用 “.” 表示当前目录)

  • -c 要么 --build-command -指定要运行的生成或验证命令

  • -x 要么 --non-interactive -启用非交互模式(无用户提示)

  • -t 要么 --trust-all-tools -无需提示即可自动信任所有工具

  • -d 要么 --do-not-learn -防止从本次执行中提取教训

  • --tv 要么 --transformation-version -指定转换的特定版本

  • -g 要么 --configuration -提供配置文件或内联配置

重要

这个 -t 要么 --trust-all-tools flag 在不提示的情况下自动批准所有工具的执行,并绕过大多数安全护栏,(与您的命令相匹配) alwaysPromptCommands 列表仍然需要明确的权限,除非被覆盖 trustedShellCommands)。路过 --non-interactive 和 --trust-all-tools 是完全自主体验所必需的,但不是执行转型所必需的。在生产环境中请谨慎使用。

使用配置文件

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 将尝试根据转换推断出最佳构建命令,但建议具体考虑质量。

生成和验证命令示例:

  • Java: mvn clean install 要么 gradle build

  • Python: pytest 要么 python -m py_compile

  • Node.js:npm run build 或 npm test

  • Linters: eslint . 要么 pylint .

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

如果不需要生成或验证,请省略您的输入。

控制学习行为

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

为防止从执行中学习:

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

这个 -d 要么 --do-not-learn flag 选择不允许从当前执行中提取教训。

恢复对话

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

要恢复最近的对话,请执行以下操作:

atx --resume

要恢复特定对话,请执行以下操作:

atx --conversation-id <conversation-id>
重要

对话只能在创建后 30 天内恢复。30 天后,对话无法再恢复。

追踪代理会议纪要

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>

持续学习

本节介绍如何复习和管理通过持续学习创建的课程。

了解课程

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

  • 以交互模式提供开发者反馈

  • 转换期间遇到的代码问题

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

查看和管理课程

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

要打开课程查看器,请执行以下操作:

atx custom def learnings -n my-transformation

查看器将在课程类别列表中打开,每个类别显示其包含的活跃课程数。选择一个类别以查看其课程,然后选择一节课以查看其完整细节,包括课程正文、其影响以及之前有多少次跑步参考了该课程。

存档和恢复课程

系统自动应用课程。如果您不希望系统应用某节课,则可以将其存档。该系统保留存档的课程,但不将其应用于将来的课程。所有存档的课程都归为一组,因此您可以复习这些课程并将其恢复为活跃使用状态。

删除课程

永久移除无用的课程。删除操作无法撤消,系统可能会从将来的运行中重新吸取已删除的教训。

课程必须先存档,然后才能删除。

高级配置

本节介绍的高级功能和配置选项 AWS 自定义转换。

环境变量

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

注意

以下示例显示了 Linux 和 macOS 语法 (export)。在 Windows 上,在中设置环境变量 PowerShell 使用 $env:NAME="value"。参见 窗户(PowerShell) 等效命令的选项卡。

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_COMMITTER_EMAIL

配置用于检查点提交的作者身份 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 文件中进行配置。

该文件包含三个列表:

  • trustedTools -无需提示即可执行的工具

  • trustedShellCommands -无需提示即可执行的 Shell 命令

  • alwaysPromptCommands -需要明确权限的 Shell 命令模式,除非被覆盖 trustedShellCommands,不管 -t 标记或会话信任。这些模式在非交互模式下不强制执行(-x)。

默认的可信工具:

  • file_read

  • get_transformation_from_registry

  • list_available_transformations_from_registry

编辑信任设置:

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

注意

如果命令与两个列表都匹配, trustedShellCommands 优先。

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

  • trustedShellCommands -匹配这些模式的命令在不提示的情况下执行,绕过所有其他护栏。模式与完整的命令字符串相匹配。

    示例:

    • cd * -匹配以 cd 开头的复合命令

    • *&&* -信任所有带有 && 运算符的命令

  • alwaysPromptCommands -匹配这些模式的命令需要明确的权限,除非被覆盖 trustedShellCommands,不管 -t 标记或会话信任。这些模式在非交互模式下不强制执行(-x)。模式与复合表达式中的每个子命令相匹配 (&&, ||,命令替换)。

    示例:

    • rm -rf * -始终提示输入递归强制删除命令

    • sudo * -始终提示您使用sudo运行命令

    • find * -exec * -始终使用-exec 提示输入查找命令

Session-level 信任:

在交互式提示中,您可以选择:

  • (y)es -执行一次

  • (n)o -拒绝

  • (t)rust -仅信任当前会话

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

注意

会话信任不适用于与您的命令相匹配的命令 alwaysPromptCommands 清单。

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

这个 AWS Transform CLI 支持模型上下文协议 (MCP) 服务器,该服务器通过其他工具扩展了其功能。

配置:

在中配置 MCP 服务器 ~/.aws/atx/mcp.json 文件。这个 AWS Transform 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 令牌)存储在环境变量中,而不是存储在配置文件中。

配置属性:

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

  • command (必需)-运行服务器的命令

  • args (可选)-命令行参数数组

  • env (可选)-传递给服务器进程的环境变量

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

  • url (必填)-远程 MCP 服务器的 HTTP 或 HTTPS URL

  • headers (可选)-请求中包含的 HTTP 标头,支持 ${VAR_NAME} 环境变量扩展

管理 MCP 服务器:

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

atx mcp tools

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

atx mcp tools --server <server-name>

使用情况跟踪:

在转换执行期间,CLI 会自动跟踪 MCP 工具的使用情况。使用情况统计数据保存为 mcp_usage.json 在对话目录旁边 metadata.json。该文件记录每次执行的每个工具的指标,包括:

  • 每个工具的调用次数

  • 每个工具的错误数

  • 每个工具的总执行时间

  • 上次错误详情(如果有)

Client-Side 技能

Client-side 技能是在转换执行期间扩展代理的额外能力。它们允许您提供自定义工具、脚本和指令,代理可以在内置功能的同时使用这些工具、脚本和指令。

技能发现目录:

技能是按优先顺序从四个目录中发现的。如果同名技能存在于多个目录中,则列表中的第一个目录优先:

  1. <project>/.aws/atx/skills/ - Project-level, AWS 转型 CLI-specific

  2. <project>/.agents/skills/ - Project-level,跨客户端(适用于任何兼容的代理工具)

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

  4. ~/.agents/skills/ - User-level,跨客户端(适用于任何兼容的代理工具)

这个 .aws/atx/skills/ 目录特定于 AWS 转换 CLI。这个 .agents/skills/ 目录是跨客户端的,这意味着放置在那里的技能可供除之外的任何兼容代理工具使用 AWS 转换 CLI。

技能目录结构:

每项技能都是一个包含以下内容的目录 SKILL.md 带有 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 格式:

--- name: my-skill description: When to use this skill --- # Skill Title Instructions for the agent...

这个 name 字段必须与父目录名称相匹配。

禁用技能:

要防止在不移除其文件的情况下加载技能,请添加 disable-model-invocation: true 顺便说一句:

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

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

注意

已禁用技能的文件仍保留在磁盘上。如果转换定义指示代理读取特定的文件路径,则代理仍然可以访问该内容。这个 disable-model-invocation 属性防止自动发现和上下文注入,而不是文件系统访问。

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

  • 执行模式 (atx custom def exec 和 --code-repository-path)-从用户级和项目级目录中发现技能。

  • 交互模式 (atx)-最初只发现用户级别的技能。当您在会话期间提供代码库路径时,也会加载项目级技能。

验证技能发现:

运行后检查 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

验证失败的技能将被跳过,并在调试日志中显示警告。

注意

Client-side 技能需要 CLI 版本 2.0 或更高版本。

在两者之间选择 Project-Level 和 User-Level 技能

将技能放置在何处决定谁将从中受益以及何时激活。

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

将它们提交到版本控制中,这样每个针对存储库运行转换的团队成员都会自动发现它们。将项目级技能用于:

  • Repository-specific 合规性检查(Dockerfile 规则、Terraform 政策、迁移安全验证器)

  • 适用于此代码库的组织编码标准(可观察性模式、错误处理、命名规范)

  • 生成或测试项目特有的脚本(自定义 linter、架构适应性函数)

  • 此存储库中使用的内部库的 API 迁移指南

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

无论您的目标是哪个存储库,它们都会保留在您的计算机上并在所有转换期间激活。使用用户级技能获得:

  • 个人工作流程工具(变更日志生成器、提交消息格式化器)

  • Cross-project 首选项(首选测试模式、文档风格提醒)

  • 您的组织要求对所有存储库进行许可证合规性检查

  • 您在使用的每个代码库上强制执行的覆盖范围阈值或质量门槛

有效技能小贴士:

  • 写得清楚 description 您的字段 SKILL.md 前言。代理使用此字段来决定某项技能何时相关。

  • 成功时退出代码为 0 的验证脚本,失败时退出代码为非零的验证脚本。代理解释退出代码以确定合规性。

  • 在脚本中打印清晰、可操作的错误消息。代理读取输出以了解要修复的问题。

  • 将技能放在跨客户目录中 (.agents/skills/) 在任一级别上与其他 AI 开发工具共享 AWS 转换 CLI。

Client-Side 技能示例

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

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

该技能可根据安全和运营最佳实践对 Dockerfiles 进行验证。它使用代理在进行更改之前和之后运行的验证脚本。

目录结构:

.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

参考文件包含之前和之后的代码示例。例如, aws-sdk-v2-to-v3.md 地图图案,比如 s3.putObject(params).promise() 使用模块化 v3 等效项 S3Client 和 PutObjectCommand。

标签和组织

您可以使用用于访问控制、分类和成本分配的标签来组织客户拥有的转换定义。

您只能在客户拥有的转换定义上添加、更新或删除标签。您无法在上管理标签 AWS-管理转换。

注意

其中一些命令需要为转换定义指定 Amazon 资源名称 (ARN)。ARN 结构是: arn:aws:transform-custom:<region>:<account-id>:package/<td-name>

要列出转换的标签,请执行以下操作:

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 法案。 AWS 转换自定义记录,将转换定义作为的计费资源 代理会议纪要 一次执行会消耗。每次执行都会继承其运行的转换定义的标签。如果多个团队或项目共享一个 AWS 帐户,将每个客户拥有的定义标记为其成本所有者。然后,您可以分离每个团队或项目的转型成本。

标记客户拥有的转换定义后,请在中激活这些标签密钥 AWS 账单和成本管理控制台。在激活标签密钥之前,标签值不会出现在您的成本数据中。激活适用于今后的使用。要归因于前几个月的使用情况,请申请成本分配标签补充。有关更多信息,请参阅 成本分配和标记 在 AWS 账单和成本管理用户指南。

激活标签密钥后,您可以进行分组 AWS 在 Cost Explorer 中使用该密钥转换费用。您也可以将资源 ID 包含在 AWS 成本和使用情况报告,用于查看每个行项目的转换定义 ARN 及其标签值。有关带有这些值的列,请参见 资源标签列 在 AWS 数据导出用户指南。以下示例返回 AWS 一天的转换成本和代理分钟数,按 CostCenter 标签。

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

Cost Explorer 将密钥无值的费用作为单组返回,返回值为空的费用。这会显示有多少支出仍未归因。

不能按标签归因的内容

Tag-based 归因基于变换定义。在依赖标签进行退款之前,请根据您的成本模型确认以下内容。

用量 为什么不归因,改为做什么
AWS-管理的转换 您无法在上添加、更新或移除标签 AWS-管理的转换定义。他们的代理分钟费用不继承客户定义的成本分配标签。
不运行转换定义的会话 中消耗的代理分钟数 atx 不运行转换定义的会话是在没有资源 ID 的情况下记录的,因此没有资源可以继承标签。当必须归因支出时,通过带标签的转换定义进行工作。
单一定义的个人处决 标签是转换定义的属性,而不是执行的属性,而且 atx custom def exec 不接受标签。定义的所有执行都共享其标签值。要分离两个成本所有者,请为每个成本所有者指定自己的转换定义。
个人用户或 IAM 委托人 费用归因于转换定义和执行账户,而不是归因于开始执行的身份。 Per-user 无法通过成本分配标签进行归因。

日志

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 本身的高级故障排除信息。

注意

日志目录中可能有多个调试日志文件(即 debug1.log、debug2.log)。查看并提供所有相关日志,例如 ~/。aws/atx/custom/ <conversation-id>/* 和 ~/。aws/atx/logs/ *,当打开支持票证以加快解决问题时。

CLI 更新

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

要检查更新,请执行以下操作:

atx update --check

要更新到最新版本,请执行以下操作:

atx update

要更新到特定版本,请执行以下操作:

atx update --target-version <version>

创建自定义转换

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

创建新的转型

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

创建转换定义

  1. 启动 AWS 转换 CLI:

    atx
  2. 告诉代理你要创建新的转换。

  3. 对转型目标进行清晰、详细的描述。包含:

    • 源和目标状态(例如,“从版本 X 升级到版本 Y”)

    • 需要进行特定更改(例如,“更新导入语句,替换过时的方法”)

    • 任何特殊注意事项或限制

  4. 当代理人要求澄清或其他信息时,请提供具体的示例和参考材料。

  5. 查看代理创建的初始转换定义。

  6. 在示例代码库上测试转换。

  7. 通过提供反馈、代码修复或其他示例进行迭代。

  8. 将转换保存到本地或将其发布到注册表。

创建转换的最佳实践:

  • 先从简单、定义明确的转换开始,然后再尝试复杂的转换

  • 提供全面的参考资料,包括迁移指南和代码示例

  • 发布前在多个示例代码库上进行测试

  • 使用确定性构建或验证命令来实现持续学习

  • 考虑将复杂的转换分成多个较小的步骤

  • 在转换定义中将关键信息标记为 “关键:” 或 “重要:”,以确保代理优先考虑这些需求

  • 当您需要遵循确切的要求(例如使用特定的命令或字符串值)时,请在转换定义中明确指定完整的字符串。你可以将它们包装在 bash 引号中,以清楚地表明它们是终端命令或文字字符串,这样可以减少可变性并确保一致的执行

提供参考资料

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

推荐的参考文件类型:

  • Before/after 示例代码

  • 所涉的 API、库或功能的文档

  • Human-readable 迁移指南

要提供参考文件,请执行以下操作:

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

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

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

仅支持基于文本的文件(.md、.html、.txt、代码文件)。目前不支持二进制文件、图像和富文本文件(例如,.pdf、.png、.docx)。通常可以提取文本内容并将其用作参考。如果您有许多小文本文件,可以考虑将它们连接成几个具有描述性名称的文件。所有文件的总容量限制为 10MB。

修改现有转换

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

修改现有转换

  1. 启动 AWS 转换 CLI:

    atx
  2. 告诉代理你要修改现有的转换。

  3. 选择是否:

    • 为本地存储的转换(即不是已保存的草稿或已发布的文件)提供文件路径

    • 向注册表索取转换清单

  4. 如果从注册表中选择,请选择要修改的转换。

  5. 与代理合作,描述你想要做出的更改。

  6. 在示例代码库上测试更新后的转换。

  7. 如果需要,将更新发布到注册表。

发布和管理转换

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

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

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

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