aws-transform

Name: aws-transform
Author: aws

github.com/aws开发3.3k6.2k 次安装今天更新

关于 aws-transform

AWS Transform（ATX）的 Agent 技能，用于分析代码库并执行升级、迁移和代码转换，面向维护一个或多个代码仓库的开发团队。支持本地 CLI 执行或通过 AWS Batch/Fargate 远程批量处理，并可匹配适用的转换定义。

主要功能

01升级语言、框架和库
02迁移 AWS SDK
03分析代码库并匹配转换定义
04本地或远程执行转换
05创建自定义转换定义

适用场景

01升级多个代码仓库的语言版本
02迁移旧版 AWS SDK
03批量执行代码重构
04分析代码并生成文档

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/aws/agent-toolkit-for-aws --skill aws-transform

安装后在 Claude Code 中输入/aws-transform确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/

cli-reference.md

multi-transformation.md

remote-execution.md

repo-analysis.md

results-synthesis.md

single-transformation.md

troubleshooting.md

详细介绍

AWS Transform（ATX）

概述

使用 AWS Transform（ATX）执行代码升级、迁移和转换。支持任意类型之间的转换：语言版本升级（Java、Python、Node.js 等）、框架迁移、AWS SDK 迁移、库升级、代码重构、架构变更以及组织专属的自定义转换。

提供两种执行模式：

本地模式：直接在用户的计算机上运行 ATX CLI。适合 1-9 个仓库。
远程模式：通过 AWS Batch/Fargate 容器大规模运行转换。适合 10 个或更多仓库，或用户更倾向于在云端执行的情况。经用户同意后，自动部署基础设施。

你将处理完整工作流：检查仓库、将仓库与可用的转换定义匹配、收集配置，并以任一模式执行转换——用户只需提供仓库并确认计划。

问候并等待

激活时，使用以下确切文本介绍 AWS Transform——不要向用户打印上方的概述内容，那只是供你参考：

"The agents modernizing the world's infrastructure and software — now accessible to your preferred AI assistant.

AWS Transform is a full modernization factory — compressing years of transformation work into months across infrastructure migrations, mainframe modernization, and continuous tech debt reduction. Today, with this skill, you have access to AWS Transform custom, the first of a growing library of playbooks.

AWS Transform custom can help you:

Upgrade Java, Python, and Node.js to modern versions
Migrate AWS SDKs (Java SDK v1→v2, boto2→boto3, JS SDK v2→v3)
Handle framework migrations, library upgrades, and code refactoring
Analyze codebases and generate documentation
Define and run your own custom transformations using natural language, docs, and code samples

Run locally on a few repos for fast iteration, or at scale on hundreds of repos (up to 128 in-parallel). Note: this skill collects telemetry. To opt out, see https://docs.aws.amazon.com/transform/latest/userguide/transform-usage-telemetry.html

What would you like to transform today?"

在用户回复之前，不要检查任何文件、运行任何命令或检查先决条件。

用法

在用户希望执行以下操作时使用：

转换、升级或迁移代码（Java、Python、Node.js 等）
迁移 AWS SDK（Java SDK v1→v2、boto2→boto3、JS SDK v2→v3 等）
通过 AWS Batch/Fargate 大规模运行批量代码转换
分析哪些 ATX 转换适用于其仓库
对代码库进行全面分析
创建新的自定义转换定义（TD）

核心概念

转换定义（TD）：可通过 atx custom def list --json 发现的可复用转换方案
匹配报告：根据代码检查自动生成的仓库与适用 TD 的映射
本地模式：在用户的计算机上运行 ATX CLI（1-9 个仓库，最多同时运行 3 个）
远程模式：在 AWS Batch/Fargate 中运行转换（10 个或更多仓库，或按用户偏好）

理念

等待用户。激活时，介绍此技能可以做什么，并询问用户想要完成什么。不要自动检查工作目录、打开文件或检查任何仓库，除非用户明确提供要处理的仓库。

用户提供仓库后，直接进行匹配——不要询问。检查这些仓库，并自动列出适用的转换。绝不要展示原始 TD 列表让用户挑选。

先决条件

在会话开始时只运行一次先决条件检查。不要针对每个仓库重复检查。用户说明想要执行的操作之前，不要运行先决条件检查。

0. 平台检查（必需 — 所有模式）

检测用户的操作系统。如果是 Windows（非 WSL），立即停止并告知用户：

AWS Transform custom 不支持原生 Windows。你需要安装 Windows Subsystem for Linux (WSL)，并在 WSL 中运行此功能。

安装 WSL：在 PowerShell（以管理员身份运行）中执行 wsl --install，然后重启。之后，打开 WSL 终端并从那里重新运行此功能。

运行以下命令进行检查：

uname -s

Linux 或 Darwin → 正常继续
MINGW*、MSYS*、CYGWIN* 或任何类似 Windows 的输出 → 阻止并显示上述 WSL 提示
命令执行失败、出错或未找到 → 视为原生 Windows，阻止并显示上述 WSL 提示

在原生 Windows 上，不要继续执行任何其他步骤。

1. AWS CLI（必需 — 所有模式）

aws --version

如果未安装，请指导用户：

macOS：brew install awscli 或 curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg" && sudo installer -pkg AWSCLIV2.pkg -target /
Linux：curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" && unzip awscliv2.zip && sudo ./aws/install

在 aws --version 成功之前，不要继续。

2. AWS 凭证（必需 — 所有模式）

aws sts get-caller-identity

如果尚未配置凭证，请引导用户完成设置：

AWS Transform custom requires AWS credentials to authenticate with the service. Configure authentication using one of the following methods.

1. AWS CLI Configure (~/.aws/credentials):
   aws configure

2. AWS Credentials File (manual). Configure credentials in ~/.aws/credentials:

[default]
aws_access_key_id = your_access_key
aws_secret_access_key = your_secret_key

3. Environment Variables. Set the following environment variables:

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_SESSION_TOKEN=your_session_token

You can also specify a profile using the AWS_PROFILE environment variable:

export AWS_PROFILE=your_profile_name

在验证凭证之前，不要继续。完成设置后，重新运行 aws sts get-caller-identity。

注意：通过 export 设置的环境变量不会在不同 Shell 会话之间保留。如果 Agent 启动了新的 Shell，作为环境变量设置的凭证可能会丢失。建议使用 aws configure 或 ~/.aws/credentials 进行持久化配置。

3. ATX CLI（必需 — 所有模式）

所有模式都需要它来发现 TD（atx custom def list --json）。本地模式还会使用它执行转换。

atx --version
# Install: curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash

必须：每次会话开始时都要运行一次 atx update，即使你最近刚运行过也不例外。此操作会获取新版 ATX CLI 和新的 TD。必须在任何其他 ATX 命令（包括 atx custom def list --json）之前运行：

atx update

不要跳过此步骤。不要询问用户是否要更新。不要根据 CLI 是否“需要”更新来决定是否执行。无条件运行。

4. IAM 权限（必需 — 所有模式）

本地模式至少需要 transform-custom:* 权限。运行 TD 列表进行验证：

atx custom def list --json

如果执行成功，则权限充足 — 跳过本节其余内容。

如果因权限错误而失败，调用者需要 transform-custom:* IAM 权限。向用户说明所需权限，并在继续之前征得确认：

你的身份需要 transform-custom:* 权限才能使用 ATX CLI。我可以将 AWS 托管策略 AWSTransformCustomFullAccess 附加到你的身份。是否继续？

只有在用户确认后，才附加托管策略：

CALLER_ARN=$(aws sts get-caller-identity --query Arn --output text)
if echo "$CALLER_ARN" | grep -q ":user/"; then
  IDENTITY_NAME=$(echo "$CALLER_ARN" | awk -F'/' '{print $NF}')
  aws iam attach-user-policy --user-name "$IDENTITY_NAME" \
    --policy-arn "arn:aws:iam::aws:policy/AWSTransformCustomFullAccess"
elif echo "$CALLER_ARN" | grep -Eq ":assumed-role/|:role/"; then
  ROLE_NAME=$(echo "$CALLER_ARN" | sed 's/.*:\(assumed-\)\{0,1\}role\///' | cut -d'/' -f1)
  aws iam attach-role-policy --role-name "$ROLE_NAME" \
    --policy-arn "arn:aws:iam::aws:policy/AWSTransformCustomFullAccess"
fi

如果附加策略的命令本身失败（例如，IAM 权限不足或角色由 SSO 管理），请告知用户需要联系 AWS 管理员，将 AWS 托管策略 AWSTransformCustomFullAccess 附加到其身份。对于 SSO 用户（角色名称以 AWSReservedSSO_ 开头），必须将其添加到 IAM Identity Center 权限集 — 无法直接附加。

在 atx custom def list --json 成功之前，不要继续。

远程模式还需要其他权限（Lambda 调用、S3、KMS、Secrets Manager、CloudWatch）。这些权限会在部署流程中生成并附加 — 参见 references/remote-execution.md。

完整权限列表请参见 references/cli-reference.md。

5. AWS CDK（仅限远程模式）

部署远程基础设施时需要。检查是否已安装：

cdk --version

如果未安装，请进行全局安装：

npm install -g aws-cdk

在 cdk --version 成功之前，不要继续部署远程基础设施。

6. 远程基础设施（仅远程模式——暂缓）

仅当用户选择远程模式时才进行验证。基础设施 CDK 脚本会在运行时通过克隆 https://github.com/aws-samples/aws-transform-custom-samples.git（分支 atx-remote-infra）获取—— 它们不会随此技能一同打包。请参阅 references/remote-execution.md。

工作流

生成一次会话时间戳，并在本次会话的所有路径中重复使用：

SESSION_TS=$(date +%Y%m%d-%H%M%S)

步骤 1：收集代码仓库

请用户提供本地路径或 git URL。可以提供一个或多个。不要假定当前工作目录或打开的编辑器文件就是目标——等待用户明确提供代码仓库。

接受的源格式：

本地路径——用户计算机上的目录（例如，/home/user/my-project）
HTTPS git URL——公开或私有（例如，https://github.com/org/repo.git）
SSH git URL——例如，[email protected]:org/repo.git
包含 zip 文件的 S3 存储桶路径——例如，s3://my-bucket/repos/ 其中包含代码仓库的 zip 文件。每个 zip 文件对应一个转换任务。

S3 存储桶输入

如果用户提供的 S3 路径中包含 zip 文件，请询问他们偏好的执行模式（如果尚未指定）。两种模式均支持 S3 输入：

**远程模式：**将 zip 文件从用户的存储桶复制到托管源存储桶，然后提交指向托管副本的任务：

ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
SOURCE_BUCKET="atx-source-code-${ACCOUNT_ID}"

# List all zips in the user's bucket path
aws s3 ls s3://user-bucket/repos/ --recursive | grep '\.zip$'

# Copy each zip to the managed source bucket
aws s3 sync s3://user-bucket/repos/ s3://${SOURCE_BUCKET}/repos/ --exclude "*" --include "*.zip"

然后提交批处理任务，每个 zip 文件对应一个任务，每个任务都指向 s3://${SOURCE_BUCKET}/repos/<filename>.zip。容器会自动解压 zip 文件。有关批量提交，请参阅 references/multi-transformation.md。托管源存储桶的生命周期为 7 天——复制的 zip 文件会自动删除。

**本地模式：**在本地下载并解压每个 zip 文件：

mkdir -p ~/.aws/atx/custom/atx-agent-session/repos
aws s3 sync s3://user-bucket/repos/ ~/.aws/atx/custom/atx-agent-session/repos/ --exclude "*" --include "*.zip"
for zip in ~/.aws/atx/custom/atx-agent-session/repos/*.zip; do
  name=$(basename "$zip" .zip)
  unzip -qo "$zip" -d "$HOME/.aws/atx/custom/atx-agent-session/repos/${name}-$SESSION_TS/"
done

将解压后的目录用作本地执行的 <repo-path>。标准本地模式限制仍然适用（最多同时处理 3 个代码仓库）。

私有仓库检测（远程模式）

始终询问用户——不要尝试自行判断仓库的可见性。切勿尝试克隆、curl 或探测 URL，以检查仓库是公开还是私有。只需询问用户。用户提供 Git URL 且已选择（或可能选择）远程模式后，立即询问：

“这些仓库中有私有仓库吗？如果有，远程容器需要凭据才能克隆它们——我会指导你完成设置。”

不要跳过这个问题。不要尝试通过克隆、curl 或任何其他网络请求推断仓库的可见性。只需询问。

如果用户确认仓库是私有的，请根据 URL 格式确定凭据类型：

首先，确定区域（用于以下所有 Secrets Manager 命令）：

REGION=${AWS_REGION:-${AWS_DEFAULT_REGION:-$(aws configure get region 2>/dev/null)}}
REGION=${REGION:-us-east-1}

对于 HTTPS URL——检查是否已配置 GitHub PAT：

aws secretsmanager describe-secret --secret-id "atx/github-token" --region "$REGION" 2>/dev/null \
  && echo "CONFIGURED" || echo "NOT_CONFIGURED"

如果已配置，询问用户：“已经存储了 GitHub PAT。你想继续使用它，还是换成新的？”如果用户想换成新的，告诉他们运行：

aws secretsmanager put-secret-value --secret-id "atx/github-token" --region "$REGION" --secret-string "YOUR_TOKEN_HERE"

如果尚未配置，说明需要什么，并告诉用户运行创建命令：

“私有 HTTPS 仓库需要在 AWS Secrets Manager 中存储 GitHub Personal Access Token（PAT）。远程容器会在启动时获取它，以克隆你的仓库。该令牌会保留在你的 AWS 账户中——你可以随时删除。

私有仓库需要 PAT 具有 repo 范围。请在 https://github.com/settings/tokens 创建令牌，然后运行：
aws secretsmanager create-secret --name "atx/github-token" --region "$REGION" --secret-string "YOUR_TOKEN_HERE"
随时删除：aws secretsmanager delete-secret --secret-id atx/github-token --region "$REGION" --force-delete-without-recovery”

不要让用户在聊天中粘贴令牌。让他们自行运行命令。等待用户确认操作已完成，然后进行验证：

aws secretsmanager describe-secret --secret-id "atx/github-token" --region "$REGION" 2>/dev/null \
  && echo "CONFIGURED" || echo "NOT_CONFIGURED"

对于 SSH URL（git@... 或 ssh://...）——检查是否已配置 SSH 密钥：

aws secretsmanager describe-secret --secret-id "atx/ssh-key" --region "$REGION" 2>/dev/null \
  && echo "CONFIGURED" || echo "NOT_CONFIGURED"

如果已配置，询问用户：“已经存储了 SSH 密钥。你想继续使用它，还是换成新的？”如果用户想换成新的，告诉他们运行：

aws secretsmanager put-secret-value --secret-id "atx/ssh-key" --region "$REGION" --secret-string "$(cat <path-to-your-private-key>)"

如果尚未配置，说明需要什么，并告诉用户运行创建命令：

“SSH 仓库需要在 AWS Secrets Manager 中存储 SSH 私钥。远程容器会在启动时获取它，以克隆你的仓库。

运行：
aws secretsmanager create-secret --name "atx/ssh-key" --region "$REGION" --secret-string "$(cat <path-to-your-private-key>)"
随时删除：aws secretsmanager delete-secret --secret-id atx/ssh-key --region "$REGION" --force-delete-without-recovery”

不要让用户在聊天中粘贴 SSH 密钥。让他们自行运行命令。

对于本地模式，不需要私有仓库凭据——用户本地的 git 配置会处理身份验证。本地模式下完全跳过此检查。

第 2 步：发现 TD（静默执行）

静默运行——不要向用户显示输出：

atx custom def list --json

直接检查 JSON 输出，建立可用 TD 的内部查找表。不要将输出传递给 python、jq 或其他解析脚本——自行读取 JSON。切勿将 TD 名称硬编码。

创建新的 TD

用户明确要求创建 TD： 请勿尝试通过编程方式创建。请告知用户：

若要创建新的 Transformation Definition，请打开一个新终端并运行：
atx -t
这会启动一个交互式会话，供你描述要构建的转换（例如，“将所有日志记录从 log4j 迁移到 SLF4J”、“将 Spring Boot 2 升级到 Spring Boot 3”）。ATX CLI 会引导你定义并测试 TD，然后将其发布到你的 AWS 账户。

发布后，请回到这里；我扫描可用 TD 时会自动找到它。

没有现有 TD 与用户的目标匹配： 请勿悄悄引导用户创建 TD。匹配逻辑可能不够完善。请先向用户确认：

“我没有找到涵盖[描述用户目标]的现有 TD。你想创建一个新的 TD 吗？”

只有用户确认后，才显示 atx -t 的说明。如果用户拒绝，请让他们进一步说明需求——他们可能知道 TD 的名称，或希望采用其他方案。

请勿自行运行 atx -t——它需要 Agent 无法操作的交互式终端会话。用户必须在单独的终端中手动运行。

用户创建 TD 后返回时，重新运行 atx custom def list --json，以获取新发布的 TD，并继续执行常规工作流。

第 3 步：检查每个代码仓库

仅进行轻量级检查——查看配置文件中的关键信号：

信号	要检查的文件	可能的 TD 类型
Python 版本	`.python-version`、`pyproject.toml`、`setup.cfg`、`requirements.txt`	Python 版本升级
Java 版本	`pom.xml`（`<java.version>`）、`build.gradle`（`sourceCompatibility`）、`.java-version`	Java 版本升级
Node.js 版本	`package.json`（`engines.node`）、`.nvmrc`、`.node-version`	Node.js 版本升级
Python boto2	`import boto`（不是 boto3）	boto2→boto3 迁移
Java SDK v1	`com.amazonaws` 导入项，pom.xml 中的 `aws-java-sdk`	Java SDK v1→v2
Node.js SDK v2	package.json 中的 `"aws-sdk"`（不是 `@aws-sdk`）	JS SDK v2→v3
x86 Java	Dockerfile、构建配置中的 `x86_64`/`amd64`	Graviton 迁移

将检测到的信号与第 2 步中的 TD 交叉比对。仅匹配用户账户中实际存在的 TD。

完整的检测命令请参阅 references/repo-analysis.md。

第 4 步：展示匹配报告

格式：

Transformation Match Report
=============================
Repository: <name> (<path>)
  Language: <lang> <version>
  Matching TDs:
    - <td-name> — <description>

Summary: N repos analyzed, M have applicable transformations (T total jobs)

展示匹配报告，并等待用户确认后再继续。未经用户明确同意，不得开始任何转换。

第 5 步：收集配置

询问用户是否有其他计划背景信息（例如，升级 TD 的目标版本）。这是必需步骤——始终询问，即使 TD 并不严格要求配置。用户可能有 Agent 不知道的偏好或限制。只有用户明确表示不需要补充背景信息时，才可跳过。

第 6 步：验证运行时兼容性（远程和本地）

远程模式

提交远程作业前，请确定预构建镜像是否涵盖目标运行时，或者是否需要自定义 Docker 构建。

预构建镜像包含：

Java：8、11、17、21、25（Amazon Corretto），以及 Maven 和 Gradle 9.4
Python：3.8、3.9、3.10、3.11、3.12、3.13、3.14（dnf + pyenv）
Node.js：16、18、20、22、24（nvm），以及 yarn、pnpm、TypeScript、ts-node
构建工具：gcc、g++、make、patch
CLI 工具：AWS CLI v2、ATX CLI、git、jq、curl、unzip、tar
操作系统：Amazon Linux 2023（x86_64）

决策逻辑：

根据转换要求（源运行时、目标运行时、构建工具和其他依赖项），确定预构建镜像中是否提供所需的一切
如果是 → 使用预构建镜像路径（无需 Docker）。按照 references/remote-execution.md 中的预构建镜像说明继续部署。
如果否 → 使用自定义镜像路径（需要 Docker）。告知用户：

远程容器不包含 [语言/工具版本]。要在远程运行此转换，我需要构建自定义容器镜像。这需要在你的机器上安装并运行 Docker。这是一次性操作，约需 5-10 分钟。要我继续吗？

如果用户确认，请按照 references/remote-execution.md 中的自定义镜像路径操作：清除 prebuiltImageUri，自定义 Dockerfile 并部署。

如果用户拒绝，请建议使用本地模式作为替代方案（前提是其机器上有可用工具）。

Dockerfile 自定义（仅限自定义镜像路径）：

首先，读取 Dockerfile，查看已安装的内容：

ATX_INFRA_DIR="$HOME/.aws/atx/custom/remote-infra"
cat "$ATX_INFRA_DIR/container/Dockerfile" 2>/dev/null

确保基础设施仓库已克隆且为最新版本：

ATX_INFRA_DIR="$HOME/.aws/atx/custom/remote-infra"
if [ -d "$ATX_INFRA_DIR" ]; then
  git -C "$ATX_INFRA_DIR" add -A
  git -C "$ATX_INFRA_DIR" commit -m "Local customizations" -q 2>/dev/null || true
  git -C "$ATX_INFRA_DIR" pull -q
else
  git clone -b atx-remote-infra --single-branch https://github.com/aws-samples/aws-transform-custom-samples.git "$ATX_INFRA_DIR"
fi

如果 git pull 报告合并冲突，请在 Dockerfile 的 CUSTOM LANGUAGES AND TOOLS 部分保留上游更改和用户自定义内容来解决冲突，然后提交合并。

编辑 $ATX_INFRA_DIR/container/Dockerfile。找到标记为 # CUSTOM LANGUAGES AND TOOLS 的部分，并在注释块之后、USER root 行之前插入 RUN 命令。

对于已安装语言缺少的版本，请在自定义部分添加该版本。示例：

# Java 23 (Amazon Corretto — direct install, must run as root)
# Do NOT use dnf in the custom section — pyenv overrides the system python3
# that dnf depends on, causing "No module named 'dnf'" errors.
USER root
RUN curl -fsSL "https://corretto.aws/downloads/latest/amazon-corretto-23-x64-linux-jdk.tar.gz" -o /tmp/corretto23.tar.gz && \
    mkdir -p /usr/lib/jvm && \
    tar -xzf /tmp/corretto23.tar.gz -C /usr/lib/jvm && \
    rm /tmp/corretto23.tar.gz && \
    ln -sfn /usr/lib/jvm/amazon-corretto-23.* /usr/lib/jvm/corretto-23

# Node.js 23 (via nvm — must run as atxuser)
USER atxuser
RUN . /home/atxuser/.nvm/nvm.sh && nvm install 23
USER root

# Python 3.15 (via pyenv — must run as atxuser)
USER atxuser
RUN eval "$(/home/atxuser/.pyenv/bin/pyenv init -)" && \
    MAKE_OPTS="-j$(nproc)" /home/atxuser/.pyenv/bin/pyenv install 3.15.0
USER root

对于全新的语言，请避免在自定义部分使用 dnf——pyenv 会覆盖 dnf 所依赖的系统 python3。请改用特定语言的安装程序：

# Go
RUN curl -fsSL https://go.dev/dl/go1.22.0.linux-amd64.tar.gz | tar -C /usr/local -xz
ENV PATH="/usr/local/go/bin:$PATH"

# Ruby (via rbenv — must run as atxuser)
USER atxuser
RUN git clone --depth 1 https://github.com/rbenv/rbenv.git /home/atxuser/.rbenv && \
    git clone --depth 1 https://github.com/rbenv/ruby-build.git /home/atxuser/.rbenv/plugins/ruby-build && \
    /home/atxuser/.rbenv/bin/rbenv install 3.3.0 && \
    /home/atxuser/.rbenv/bin/rbenv global 3.3.0
ENV PATH="/home/atxuser/.rbenv/shims:/home/atxuser/.rbenv/bin:$PATH"
USER root

# Rust
USER atxuser
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
ENV PATH="/home/atxuser/.cargo/bin:$PATH"
USER root

更新 $ATX_INFRA_DIR/container/entrypoint.sh 中的版本切换器。找到相关的 switch_*_version 函数，并为新版本添加一个 case。对于通过直接下载安装的 Java 版本，请在 /usr/lib/jvm/ 下查找解压后的目录名称。例如，要添加 Java 23：
```
# In switch_java_version(), add to the case statement:
23) java_home="/usr/lib/jvm/corretto-23" ;;
```
检查实际目录名称：ls /usr/lib/jvm/——使用与你安装的版本相匹配的目录。

对于 Node.js，nvm 会自动处理任意版本，无需更改入口点。对于 Python，pyenv 会自动处理任意版本，无需更改入口点（现有的 pyenv 回退逻辑会找到该版本）。
部署（或重新部署）：cd "$ATX_INFRA_DIR" && ./setup.sh CDK 会对 container/ 目录进行哈希处理——任何文件更改都会自动触发重新构建并推送到 ECR。

重新部署后，将作业的 environment 字段设为准确的目标版本（例如，"JAVA_VERSION":"23"，而不是 "21"）。入口点中的版本切换器会读取此值并激活正确的运行时。

如果用户拒绝，请建议使用本地模式作为替代方案（前提是其机器上有可用工具）。

本地模式

运行本地转换前，请确认用户已安装目标运行时版本。这适用于转换目标所涉及的任何语言或运行时——Java、Python、Node.js、Ruby、Go、Rust、.NET 等。检查 TD 要求的当前运行时版本。例如：

java -version    # Java transformations
python3 --version # Python transformations
node --version   # Node.js transformations
ruby --version   # Ruby transformations
go version       # Go transformations

如果目标版本当前未启用，请检查是否已安装：

# Java: check common install locations
/usr/libexec/java_home -V 2>&1          # macOS
ls /usr/lib/jvm/ 2>/dev/null            # Linux
# Python: check if the specific version binary exists
which python3.12 2>/dev/null            # adjust version as needed
# Node.js: check if nvm is available, or look for the binary
command -v nvm &>/dev/null && nvm ls 2>/dev/null
which node 2>/dev/null && node --version

如果已找到目标版本，请切换到该版本：

Java：export JAVA_HOME=<path to JDK> && export PATH="$JAVA_HOME/bin:$PATH"
Python：pyenv shell 3.15.0
Node.js：nvm use 23

只有在目标版本完全未安装时，才先征得用户许可再进行安装。未经用户明确确认，切勿安装运行时。建议使用相应的版本管理器：

Java：brew install --cask corretto23（macOS）、sudo yum install java-23-amazon-corretto-devel（RHEL/AL2）或 sudo apt install java-23-amazon-corretto-jdk（Debian/Ubuntu）
Python：pyenv install 3.15.0 && pyenv shell 3.15.0，或 brew install [email protected]
Node.js：nvm install 23 && nvm use 23

当前启用的运行时必须与转换的目标版本一致，才能确保构建和测试正确运行。在正确版本启用前，切勿继续执行转换。

Step 7：确认转换计划

展示最终计划，其中包含仓库、TD、配置和执行模式。用户确认前，切勿继续。

Step 8：执行

运行 atx custom def exec 时，务必加入 --telemetry（参见 Telemetry 部分）。

对于远程模式，请先使用 CloudFormation 检查基础设施部署状态（参见 references/remote-execution.md 中的 Infrastructure Check 部分）。切勿通过探测 Lambda 函数名称来检查部署状态。

1 个仓库：参见 references/single-transformation.md
多个仓库：参见 references/multi-transformation.md

执行模式

模式	最适用场景	前置条件
本地（1–9 个仓库时为默认模式）	快速转换，已安装 ATX 的开发机器	已安装 ATX CLI
远程（建议用于 10 个及以上仓库）	批量转换，最多支持 512 个仓库（每批次并发 128 个）	AWS 账户、自动部署的基础设施

模式判断：

用户说“本地”“这里”或“在我的机器上” → 本地（无论仓库数量多少，都遵从用户请求）
用户说“远程”“云端”“AWS”“批量”或“规模化” → 远程
有 10 个及以上仓库且用户未指定偏好 → 建议远程，并说明本地最多并发 3 个
有 1–9 个仓库且用户未指定偏好 → 本地，并说明也可使用远程模式

参见 references/remote-execution.md 了解基础设施设置。

关键规则

动态发现 TD — 始终运行 atx custom def list --json。绝不硬编码 TD 名称。
匹配，不询问 — 检查仓库并展示匹配项。绝不展示原始 TD 列表。
仅进行轻量检查 — 检查配置文件和关键指标。不要进行深入分析。
执行前先确认 — 务必先与用户确认 TD、仓库和配置。
不预估耗时 — 绝不预测耗时。
并行执行 — 本地：最多并发处理 3 个仓库。远程：每次 Lambda 调用最多分批提交 128 个作业（每个会话最多处理 512 个仓库）。
保留输出 — 不要删除生成的输出文件夹。
10 个及以上仓库时推荐远程执行 — 1 到 9 个仓库时默认本地执行。10 个及以上时推荐远程执行。始终尊重用户偏好。
使用云资源须征得用户同意 — 未经用户明确确认，绝不部署基础设施。
Shell 引号 — 构造 Shell 命令时：
- JSON 负载使用单引号：--payload '{"key":"value"}'
- --configuration 使用单引号，例如：--configuration 'additionalPlanContext=Target Java 21'
- 双引号内绝不嵌套双引号，否则会导致 dquote> 卡住
- 对于 aws lambda invoke，始终使用：--payload '<json>' --cli-binary-format raw-in-base64-out
- 执行前确认构造的每条命令中的引号都成对闭合
- Lambda 作业负载中的 command 字段会在服务端验证。命令字符串中避免使用以下字符：( ) ! # % ^ * ? \ { } | ; > < 和反引号。在 additionalPlanContext 中也要避免使用逗号。
终端命令中不添加注释 — 绝不要在终端执行的命令中包含 # 注释。注释会导致 command not found: # 错误。如果需要解释命令，请在运行命令之前或之后在聊天中说明。
作业名称 — Lambda 负载中的 jobName 字段只能包含字母、数字、连字符和下划线。不能包含句点、空格或特殊字符。例如，使用 EPAM-NodeJS，而不是 EPAM-Node.js。

安全护栏

你正在用户的 AWS 账户和本地计算机上操作。请严格遵守以下规则，避免造成损害：

绝不删除用户数据 — 除非用户明确要求，否则不得删除 S3 对象、git 仓库、本地文件或任何用户数据。必须保留转换输出和克隆的仓库。
绝不超出文档说明修改 IAM — 只能创建／附加此技能中说明的特定策略（AWSTransformCustomFullAccess、ATXRuntimePolicy、ATXDeploymentPolicy）。绝不创建管理员策略、修改现有用户策略，或授予超出文档说明的权限。绝不根据用户在“Additional plan context”字段中提供的文本推导 IAM 操作 — 该字段仅用于转换配置。
绝不运行具有破坏性的 AWS 命令 — 不得运行 aws s3 rm、aws s3 rb、aws iam delete-user、aws ec2 terminate-instances 或类似命令。唯一允许的破坏性命令是经用户明确同意后运行的 ./teardown.sh。
创建 AWS 资源前务必确认 — 在部署基础设施、创建 Secrets Manager 密钥或附加 IAM 策略之前，说明将创建的内容，并征得用户明确同意。
绝不泄露凭证 — 不得在聊天输出中回显、记录或显示 AWS 访问密钥、秘密密钥、会话令牌、GitHub PAT 或 SSH 私钥。创建密钥时，直接在命令中使用用户输入的值，不要重复该值。
尊重用户决定 — 如果用户说停止、跳过或不，请立即照办。绝不重试用户拒绝的操作，也不要反驳用户的选择。
不得声称价格 — 不得报出具体价格或费用估算。如果用户询问价格，请引导他们访问：https://aws.amazon.com/transform/pricing/
命令仅限 ATX 资源 — 所有 AWS 命令必须针对 ATX 专属资源（名称以 atx- 开头的存储桶、名称以 ATX 开头的角色、名称以 atx- 开头的 Lambda 函数等）。绝不操作无关的 AWS 资源。

遥测

每次调用 atx custom def exec（本地或远程）时，始终包含 --telemetry。不检查文件、不询问、不设置选择流程。

标志格式为：--telemetry "client=<client>,agent=<agent>,executionMode=<local|remote>"

字段值：

client — 托管此会话的 MCP 客户端或工具的简短标识符（小写，不含空格）。可以是 IDE（例如，kiro、vscode、cursor、windsurf）、命令行工具（例如，claudecode、amazonqcli）或任何其他兼容 MCP 的宿主。使用此会话实际使用的工具名称 — 不要默认使用任何单个示例。这些仅为示例，并非完整列表。
agent — 驱动此会话的 AI 助手的简短标识符（小写，不含空格）。例如：kiro、amazonq、claude、copilot、cline、codex。使用实际助手名称 — 不要默认使用任何单个示例。
executionMode — 直接运行 ATX CLI 时使用 local，通过 Lambda 提交时使用 remote

唯一例外：如果用户明确要求在会话期间停用遥测（例如，“disable telemetry”“opt out of telemetry”“no telemetry”或类似表述），你 MUST 立即照办 — 在本次会话剩余时间内省略 --telemetry。不要反对、询问确认，也不要解释为何包含遥测。此偏好不会持久保存 — 下一次会话会再次启用遥测。

输出结构

本地模式：转换后的代码位于仓库目录中。

远程模式的结果保留在 S3 中 — 请勿自动下载。向用户提供 S3 路径：

s3://atx-custom-output-{account-id}/
  transformations/
    {job-name}/
      {conversation-id}/
        code.zip                      # Zipped transformed source code
        logs.zip                      # ATX conversation logs

如果用户明确要求下载，请提供命令，但让他们自行运行： aws s3 cp s3://atx-custom-output-{account-id}/transformations/{job-name}/{conversation-id}/code.zip ./code.zip

批量结果摘要：~/.aws/atx/custom/atx-agent-session/transformation-summaries/ — 请参阅 references/results-synthesis.md。

参考资料

参考资料	使用时机
repo-analysis.md	检测命令、信号匹配、匹配报告格式
single-transformation.md	将一个 TD 应用于一个仓库（本地或远程）
multi-transformation.md	并行将 TD 应用于多个仓库
remote-execution.md	基础设施部署、作业提交、监控
results-synthesis.md	批量转换后生成汇总报告
cli-reference.md	ATX CLI 标志、命令、环境变量、IAM 权限
troubleshooting.md	错误解决、调试、质量改进

许可证

AWS 服务条款。此技能由 AWS 提供，并受 AWS 客户协议和适用的 AWS 服务条款约束。

更新日志

如果用户询问更改内容、新增内容等，请分享。

[1.0.0] - 2026-04-30

首次发布 AWS Transform Agent Skill
支持的 TD：
- AWS/java-version-upgrade
- AWS/python-version-upgrade
- AWS/nodejs-version-upgrade
- AWS/java-aws-sdk-v1-to-v2
- AWS/nodejs-aws-sdk-v2-to-v3
- AWS/python-boto2-to-boto3
- AWS/comprehensive-codebase-analysis
- AWS/java-performance-optimization
- AWS/angular-version-upgrade
- AWS/vue.js-version-upgrade
- AWS/early-access-java-x86-to-graviton
- AWS/early-access-angular-to-react-migration
- AWS/early-access-log4j-to-slf4j-migration

支持 Markdown

登录后评论

基本信息

作者: aws
仓库: aws/agent-toolkit-for-aws
分类: 开发
安装次数: 6,215
GitHub Stars: 3,330

报告问题