本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
自定义
什么是 AWS 自定义转换?
AWS Transform custom 使用代理人工智能对软件、代码、库和框架进行大规模现代化改造,以减少技术债务。它可以处理各种场景,包括语言版本升级、API 和服务迁移、框架升级和迁移、代码重构以及组织特定的转换。
通过持续学习,该代理可以根据每一次执行和开发人员反馈进行改进,无需专业的自动化专业知识即可提供高质量、可重复的转换。
关键功能
AWS Transform custom 提供以下功能:
自然语言驱动的转换定义 -使用自然语言、文档和代码示例创建自定义转换
执行转换 -在多个代码库中一致可靠地应用转换
持续学习 -自动提高每次执行的转换质量
AWS-管理的转换 -使用即用型, AWS-针对常见场景的经过审核的转换
转型模式
AWS Transform 自定义支持多种转换模式,以满足您的现代化需求。根据所需变更的范围和性质,每种模式都有不同的复杂性特征。
| 模式 | 说明 | 复杂度 | 示例 |
|---|---|---|---|
| API 和服务迁移 | 在保持功能的同时,在 API 版本或等效服务之间迁移 | 中 | AWS SDK v1→v2(Java、Python、 JavaScript)、Boto2→Boto3、JUnit 4→5、javax→雅加达 |
| 语言版本升级 | 升级到相同编程语言的更新版本,采用新功能并替换过时的功能 | Low-Medium | Java 8→17,Python 3.9→3.13, Node.js 12→22, TypeScript 版本升级 |
| 框架升级 | 升级到同一框架的更新版本,解决重大变化 | 中 | Spring Boot 2.x→3.x、React 17→18、Angular 升级、Django 升级 |
| 框架迁移 | 迁移到具有相似目的的完全不同的框架 | 高 | Angular→React,Redux→Zustand, Vue.js→反应 |
| 库和依赖关系升级 | 将第三方库升级到新版本,同时保持相同的语言和框架 | Low-Medium | 熊猫 1.x→2.x, NumPy 升级, Hadoop/HBase/Hive 库升级、Lodash 升级 |
| 代码重构和模式现代化 | 在不更改外部功能的情况下实现代码模式现代化并采用最佳实践 | Low-Medium | 打印→日志框架、字符串连接→f 字符串、类型提示采用、可观察性工具 |
| 脚本和 File-by-File 翻译 | 翻译独立脚本或配置文件,其中文件大多是独立的 | Low-Medium | AWS CDK→Terraform、Terraform →CloudFormation,Excel→Python 笔记本,Bash →PowerShell |
| 架构迁移 | 只需最少的代码更改即可在硬件架构或运行时环境之间迁移 | Medium-High | x86 →AWS Graviton (ARM)、本地部署→Lambda、传统服务器→容器 |
| Language-to-Language 迁移 | 将代码库从一种编程语言翻译成另一种编程语言 | 非常高 | Java→Python, JavaScript→TypeScript,C→Rust,Python→Go |
| 自定义和 Organization-Specific 转换 | 独特的组织要求和专业的现代化需求 | 变化 | 自定义内部库迁移、特定组织编码标准、专有框架迁移 |
对于 COBOL/mainframe 语言,使用 AWS 向大型机转型。要将 .NET 框架升级到 .NET Core,请考虑 AWS 适用于 Windows 的转换。对于 VMware 迁移到 AWS,考虑 AWS 为 VMware 转型。
操作方法 AWS 改造自定义作品
AWS 自定义转换通常用于转换多个代码库或模块的大型项目。团队通常遵循四个阶段的工作流程:
定义转换 -向代理提供自然语言提示、文档和代码示例,代理会生成初始转换定义。这个定义可以通过聊天或直接编辑来反复完善。使用时可以跳过此阶段 AWS-管理转换。
飞行员或 Proof-of-Concept -在示例代码库上测试转换并根据结果进行优化。此验证阶段有助于估算全面转型的成本和工作量。在此阶段,持续学习可以提高质量。
按比例执行 -使用 CLI 设置自动批量执行,开发人员审查和验证结果。使用 Web 应用程序监控进度并跟踪多个存储库之间的转换。
监控和审查 -持续学习可自动提高转型质量。查看从之前的运行中提取的经验教训,确保它们符合质量标准,并将所有无用的内容存档。
了解主要 概念
本节解释了使用时的关键概念 AWS 自定义转换。
转换定义
一个 转换定义 包含执行特定代码转换所需的指令和知识。它表示为一项技能,包括:
SKILL.md(必填)-带有 YAML 前端内容的 Markdown 中的指令 (name和description字段),其中包含核心转换逻辑和执行指令references/文件夹(可选)-在转换执行期间根据需要加载文档scripts/文件夹(可选)-转换在执行期间下载和运行的脚本
AWS 当需要执行、检查或修改时,Transform CLI 会自动将转换定义下载到当前目录。
发布转换时,该目录只能包含 SKILL.md 以及可选的 references/ 文件夹, scripts/ 文件夹,或两者兼而有之。不允许使用其他文件或子目录。
CLI 版本 2.0 及更高版本使用技能格式。现有的转换定义由 CLI 自动处理。
转换定义类别
变换定义可以有 类别 这说明了它的使用方式:
analysis— 读取代码并报告结果。持续现代化将这些转换定义作为自定义分析运行。remediation— 更改代码。持续现代化使用这些转型定义来修复发现,技术债务和自定义分析可以将发现结果与之相匹配。
使用设置类别 --category 的选项 atx custom def publish 要么 atx custom def save-draft:
atx custom def publish -n <transformation-name> --description "Description" --sd <directory> --category analysis atx custom def publish -n <transformation-name> --description "Description" --sd <directory> --category remediation atx custom def list # The Category column shows each transformation definition's category
AWS 转换使用类别来决定可以在何处使用转换定义。
| 使用 | 允许的转换定义 |
|---|---|
自定义分析 (--type custom) |
使用您自己的变换定义 analysis 类别 |
补救措施 --transformation-name |
使用您自己的变换定义 remediation 类别,或 AWS 托管转换 |
| 转型与技术债务或自定义分析的发现相匹配 | 使用您自己的变换定义 remediation 类别,或 AWS 管理转换。发现永远不会与变换定义相匹配 analysis 类别,或者没有类别。 |
在提交自定义分析、计划或补救措施之前, AWS 转换检查变换定义的类别。
为了帮助将发现与您的结果相匹配 remediation 转换定义,将变更的内容放在开头。分析首先只阅读每个定义的开头,以决定要考虑哪些定义,然后只阅读这些定义的全文。从标题和简短的范围开始,说明定义的变化和地点(例如,哪些语言或文件),然后将每个定义保留为一种更改。请参阅将发现与转化相匹配。
要更改转换定义的类别,请使用不同的类别再次发布该变换定义 --category 价值。如果你在没有发布新版本的情况下发布 --category,新版本保留了先前版本的类别。
了解如何运行 analysis 转换定义,请参阅 自定义分析。
类别与资源标签不同。要管理资源标签,请参阅 标记命令。
编写用于分析的变换定义
要获得有用的发现,请编写转换定义,使其描述要查找的内容、如何对每个问题进行分类以及不该做什么。我们推荐以下章节 SKILL.md。
| Section | 要包括什么 |
|---|---|
| 简介 | 一两句话说明分析的发现。声明它是只读的,不得修改任何文件。 |
| 参赛标准 | 当分析应用时,例如 “存储库包含 pom.xml 要么 build.gradle 文件。” |
| Scope | 要检查的文件和目录,以及要跳过的文件和目录,例如构建输出和供应商的依赖关系。 |
| 要举报什么 | 算作问题的特定模式或条件。要求为每个问题找一个调查结果,包括文件路径和行号。 |
| 类别 | 一组固定的小类别值,以及每个类别值属于哪些问题。 |
| 严重性条件 | 是什么造成了问题 high, medium,或 low。 |
| 退出标准 | 代理如何知道已经完成了:检查了每个范围内的文件,每个发现都有文件、类别和严重程度,没有文件被更改。还要说明什么都没有发现时要举报什么。 |
以下示例查找仍以 17 之前的 Java 版本为目标的 Java 项目。
--- name: java-version-detector description: Report where a repository still targets a Java version earlier than 17, in build files, Dockerfiles, toolchain files, and CI workflows. Analysis only - no code is modified. --- # Java Version Detector Find where the repository targets a Java version earlier than Java 17. This is a read-only analysis: report findings, and do not modify any files. ## Entry Criteria The repository contains a Java build file (`pom.xml`, `build.gradle`, `build.gradle.kts`, or `gradle.properties`), or a file that selects a JDK (`.java-version`, `.tool-versions`, `.sdkmanrc`, a `Dockerfile`, or a file under `.github/workflows/`). ## Scope - Inspect build files, toolchain files, Dockerfiles, and CI workflow files. - Skip build output (`build/`, `target/`) and vendored dependencies. ## What to Report Report one finding for each place that selects a Java version earlier than 17: 1. A compile target, such as `maven.compiler.source`, `maven.compiler.release`, `java.version`, `sourceCompatibility`, or a Gradle toolchain `languageVersion`. 2. A Dockerfile base image that ships a JDK or JRE earlier than 17, such as `openjdk:8` or `amazoncorretto:11`. 3. A CI job or toolchain file that selects a JDK earlier than 17. For each finding, include the file path, the line number, and the version you found. ## Categories - `outdated-compile-target` - a build file compiles for an old Java version - `outdated-runtime-image` - a Dockerfile uses an old JDK or JRE image - `outdated-ci-jdk` - a CI workflow or toolchain file selects an old JDK ## Severity Criteria - **high** - the project compiles for Java 8 or earlier - **medium** - the project compiles for Java 9 through 16 - **low** - only the runtime image or CI uses an old JDK, and the compile target is 17 or later ## Exit Criteria 1. Every in-scope file has been inspected. 2. Every finding has a file path, line number, category, and severity from the lists above. 3. No file in the repository has been modified. 4. If nothing is found, state that the repository targets Java 17 or later.
当此转换定义针对的项目运行时 pom.xml 套 <source>1.8</source>,它产生一个 high 中发现严重程度 outdated-compile-target 类别,匹配到 AWS/java-version-upgrade 转型。
撰写分析变换定义的技巧
将其保持为只读状态。明确声明分析不得修改文件。修复问题是补救工作。
具体说明什么才是问题。命名要查找的文件、设置和模式。模糊的指令会产生不一致的发现。
要求每个问题得到一个发现。每项调查结果都应指向特定的文件和行,以便可以对其进行单独审查和修复。
在转换定义中定义严重程度和类别。代理使用您的标准对每项发现进行分类。
保持范围集中。自定义分析仅报告其转换定义所描述的内容。要发现多种问题,请编写单独的变换定义或使用内置的分析类型。
说一无所获时该怎么做。正确没有问题的存储库产生的结果为零。
在变换定义中包括查找指令。如果你使用传递配置
-g要么--configuration当你运行分析时, AWS Transform 使用您的配置而不是其默认指令。保留 “举报内容” 部分SKILL.md无论哪种方式,变换定义都会产生结果。
在发布之前,在已知包含问题的存储库上测试转换定义。使用以下命令将其另存为草稿 atx custom def save-draft,或者使用以下命令在本地运行 atx ct analysis run (参见 自定义分析)。
转换注册表
这个 转换注册表 是你的 AWS 账户的集中存储库,用于存储和管理转换定义。注册表中的转换可以是:
使用列出
atx custom def list在多个代码库中执行
与您的其他用户共享 AWS 帐户
Version-controlled
转换定义因账户而异。如果你想在其他地方使用转换 AWS 账户,你必须在该账户中单独发布。
草稿与已发布的转换
AWS 自定义转换支持注册表中的两种转换状态:
草稿转换 正在进行或未经测试的转换定义。它们被保存为特定版本,可以由引用该特定版本的用户检索、更新和执行。在准备与团队共享转换之前,草稿可用于迭代开发、测试和完善。草稿还与特定的对话相关联。如果你重新启动 CLI,你可以使用 atx --conversation-id {id} 恢复以前的版本。
已发布的转换 可在您账户的转换注册表中供具有所需 IAM 权限的其他用户执行。可以使用以下方法发现已发布的转换 atx custom def list。
典型的工作流程是:
在本地创建转换
另存为草稿以供测试 (
atx custom def save-draft)完善和验证
发布以与您的团队共享 (
atx custom def publish)
您也可以直接发布转换,无需将其另存为草稿。
参考文献与教训
AWS 自定义转换使用两种类型的知识来提高转换质量:
参考文献 用户提供的文档存储在 references/ 转换定义的文件夹。参考文献仅支持文本文件(所有文件总共最大 10MB),通常包含文档、API 规范、迁移指南和代码示例。在转换执行期间根据需要加载引用。在交互模式下创建或更新转换定义时,可以添加引用。
经验教训 是从先前运行的转换中自动提取的。持续学习系统根据执行轨迹、开发人员反馈以及在转换过程中遇到的代码修复生成它们。它将相关课程分为几类,这样您就可以一起复习它们。与您预先提供的参考文献不同,当您在不同的代码库中进行转换时,经验会随着时间的推移而累积,系统会自动应用这些参考资料来改善未来的运行。您可以通过互动方式查看和管理课程 atx custom def learnings。
生成和验证命令
这个 生成或验证命令 是一个可选参数,用于指定在转换过程中如何验证您的代码。此命令在转换期间的不同时刻执行,以确保代码的完整性。
提供验证结果并在验证失败时返回问题的命令对于通过持续学习提高转型质量非常重要。如果不需要生成或验证,请省略您的输入。
有关示例和详细指南,请参阅 “工作流程” 部分中的生成和验证命令。
持续学习
持续学习 该系统可自动捕获每次转换执行的反馈,并随着时间的推移提高转换质量。该系统通过以下方式收集信息:
明确的反馈-交互模式下提供的注释和代码修复
隐式观察-代理在转换和调试代码时遇到的问题
持续学习系统处理这些信息以创建 教训 它将其添加到转型定义中,以改善未来的转换。转换完成后,系统会自动运行学习过程,无需您额外输入。
课程是针对特定转型的,不能在不同的转换或不同的客户账户之间共享。
管理课程
系统会自动生成课程,但您可以控制将来的课程应用于哪些课程。这个 atx custom def learnings 命令会打开一个交互式终端会话,用于审查和整理转型所积累的经验教训。
在本次会话中,您可以:
浏览按类别分组的课程,查看每个类别包含多少活跃课程。
打开一节课,阅读其全部细节,包括课程正文、影响以及之前有多少次跑步参考了该课程。
存档课程以防止系统将其应用于将来的运行,并在需要时将其恢复。
永久删除已存档但已不再有用的课程。
如需分步指导,请参阅 持续学习。
Client-Side 技能
Client-side 技能 是在转换执行期间扩展代理的其他功能。与定义要执行的转换定义不同,客户端技能提供了补充工具、脚本和指令,代理可以在任何转换过程中将其与内置功能一起使用。
Client-side 技能是从项目级和用户级目录中发现的。当他们强制执行特定于存储库的标准时,将技能放在项目级别;当技能应用于您的所有项目时,将其设置在用户级别。 Project-level 技能仅在提供代码存储库路径时可用。有关详细配置和用法,请参见 Client-Side 技能。
自定义转换命令简介
以下是一些可用于自定义转换的命令。命令的完整列表位于 AWS 转换自定义转换命令参考。
-
atx custom-
执行自定义转换交互式体验,允许创建、发现、执行和完善转换。
-
这是的默认命令
atx。 -
--trust-all-tools(-t) 是可选的,隐含地允许代理请求的所有工具请求。谨慎使用,尤其是在生产环境中。您可以使用为特定工具和命令配置工具信任 信任设置文件。
-
-
atx custom --help|atx custom -h-
显示帮助菜单。
-
每个命令还包括一个帮助菜单,例如
atx custom def exec --help。
-
-
atx --version|atx -v-
显示版本。
-
版本号随每个版本而变化。
-
-
atx custom def list-
打印转换注册表中可用的转换列表。
-
-
atx custom def exec-
执行转换
-
-
atx custom def learnings-
打开交互式会话以查看和管理转型从先前运行中吸取的经验教训
-
-
atx mcp-
用于管理 MCP 服务器配置
-