本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

工作流程

執行轉換

本節說明執行轉換的不同方式，以及控制執行行為的選項。

執行模式

AWS 轉換自訂支援三種執行模式，以適應不同的工作流程。

互動式對話模式

使用 啟動 CLI，atx並要求代理程式透過自然語言執行轉換。此模式可讓您與客服人員進行完整對話、隨時中斷執行，並在轉換過程中提供意見回饋。

當您想要獲得最大控制，以及能夠引導客服人員完成複雜案例時，請使用此模式。

直接互動式執行

使用 atx custom def exec -n <transformation-name> -p <path> 以互動方式啟動特定轉換。此模式可讓您在執行開始時、期間或結束時，檢閱代理程式並與之互動。客服人員會在關鍵決策點暫停，並詢問您的輸入。

這非常適合在自動執行轉換之前進行測試和精簡轉換。

您可以在非互動式模式或無周邊模式下執行轉換。非互動式模式會在具名轉換期間隱藏提示。無頭模式可讓您使用純文字提示執行代理程式，完全略過互動式界面。

非互動式模式

使用 atx custom def exec -n <transformation-name> -p <path> -x -t 進行完整自動化。新增 -t -x以在非互動式模式下執行，並在不提示的情況下自動信任所有工具。

此模式專為 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，通常會使用下列旗標：

使用組態檔案

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 轉換自訂會嘗試根據轉換推斷最佳建置命令，但建議針對品質而言是特定的。

建置和驗證命令的範例：

即使對於不需要建置的語言或轉換，提供驗證結果的命令，並在驗證失敗時傳回問題，對於改善轉換品質非常重要。

如果不需要建置或驗證，請從輸入中省略 。

控制學習行為

根據預設， AWS Transform 自訂會從每個轉換執行中擷取課程。您可以防止學習特定執行。

若要防止從執行中學習：

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

-d 或 --do-not-learn旗標選擇退出允許從目前執行中擷取課程。

繼續對話

AWS 轉換自訂可讓您在建立後的 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>

持續學習

本節說明如何檢閱和管理持續學習所建立的課程。

了解 課程

持續學習系統會自動從先前的轉換執行中擷取教訓。系統會根據下列項目以非同步方式建立它們：

當您跨不同的程式碼庫執行轉換時，課程會隨著時間累積。系統會自動套用它們來改善未來的執行。每個課程都屬於一個類別，其中包含類似網域的所有課程，以便您可以一起檢閱相關的課程。對於您不想使用的課程，您可以完全封存或刪除該課程。

檢視和管理課程

使用 learnings命令開啟互動式工作階段，以瀏覽和管理轉換定義的教訓。

若要開啟課程檢視器：

atx custom def learnings -n my-transformation

檢視器會在課程類別清單上開啟，每個類別都會顯示其中包含多少個作用中的課程。選取類別以查看其教訓，然後選取一個教訓以檢視其完整詳細資訊，包括課程內文、其影響，以及之前查閱的執行次數。

封存和還原課程

系統會自動套用課程。如果您不希望系統套用課程，您可以將其封存。系統會保留封存的課程，但不會將其套用至未來的執行。所有封存的課程都會分組在一起，因此您可以檢閱它們，並將任何 還原為作用中使用。

刪除課程

永久移除沒有幫助的課程。刪除無法復原，系統可能會從未來的執行中重新學習已刪除的課程。

必須先封存課程，才能將其刪除。

進階組態

本節說明 AWS 轉換自訂的進階功能和組態選項。

環境變數

您可以使用環境變數自訂 CLI 行為。

ATX_SHELL_TIMEOUT

覆寫 Shell 命令的預設逾時 (900 秒/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 檔案中設定。

檔案包含三個清單：

預設信任的工具：

編輯信任設定：

您可以手動編輯 trust-settings.yaml 檔案，以新增或移除信任的工具和命令。trustedShellCommands 和 都alwaysPromptCommands支援使用 的 glob 萬用字元模式*。

以下說明每個命令清單並提供範例：

工作階段層級信任：

在互動式提示期間，您可以選擇：

工作階段層級信任設定是暫時的，並在 CLI 重新啟動時重設，提供暫時核准，而不會永久修改 trust-settings.yaml。

模型內容通訊協定 (MCP) 伺服器

AWS 轉換 CLI 支援模型內容通訊協定 (MCP) 伺服器，可使用其他工具擴展其功能。

組態：

在 ~/.aws/atx/mcp.json 檔案中設定 MCP 伺服器。 AWS 轉換 CLI 支援兩種類型的 MCP 伺服器：本機命令型伺服器和遠端 HTTP 伺服器。

本機命令型伺服器：

本機伺服器會在您的機器上做為子程序執行。使用 command 屬性設定它們：

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

遠端 HTTP 伺服器：

遠端伺服器會連線至託管在 HTTP 或 HTTPS URL 的 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。每個執行的檔案會記錄每個工具的指標，包括：

用戶端技能

用戶端技能是在轉換執行期間擴展代理程式的額外功能。它們可讓您提供自訂工具、指令碼和指示，讓代理程式與其內建功能搭配使用。

技能探索目錄：

技能會依優先順序從四個目錄探索。如果具有相同名稱的技能存在於多個目錄中，則清單中的第一個目錄會優先：

.aws/atx/skills/ 目錄專屬於 AWS 轉換 CLI。.agents/skills/ 目錄是跨用戶端，這表示放置的技能可供 AWS Transform CLI 以外的任何相容代理程式工具使用。

技能目錄結構：

每個技能都是一個目錄，其中包含具有 YAML 前綴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 欄位必須符合父目錄名稱。

停用技能：

若要防止在不移除其檔案的情況下載入技能，請將 disable-model-invocation: true新增至前端：

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

設定此屬性時，CLI 會在探索期間略過技能。除非轉換定義明確指示客服人員讀取技能檔案，否則客服人員無法查看或使用技能。使用此選項可暫時停用技能、將其標記為work-in-progress，或保留僅供人類讀者使用的參考資料。

依執行模式區分的技能可用性：

驗證技能探索：

在執行後檢查 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>/.aws/atx/skills/)：

將這些遞交至版本控制，讓每個針對儲存庫執行轉換的團隊成員自動探索它們。將專案層級技能用於：

使用者層級技能 (~/.aws/atx/skills/)：

這些會保留在您的機器上，並在所有轉換期間啟用，無論您以哪個儲存庫為目標。將使用者層級技能用於：

有效技能的秘訣：

用戶端技能範例

這些範例顯示兩種常見模式：以指令碼為基礎的驗證技能和僅限參考技能。

範例：Dockerfile 合規檢查程式 （以指令碼為基礎）

此技能會根據安全性和操作最佳實務驗證 Dockerfile。它使用代理程式在進行變更前後執行的驗證指令碼。

目錄結構：

.aws/atx/skills/
└── dockerfile-compliance/
    ├── SKILL.md
    ├── scripts/
    │   └── lint_dockerfile.sh
    └── references/
        └── dockerfile-best-practices.md

https：//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.

驗證指令碼會檢查是否有未固定的基礎映像標籤、做為根目錄執行、ENV指令中的硬式編碼秘密，以及缺少HEALTHCHECK定義。代理程式會執行指令碼、使用參考檔案中的模式修正違規，並重新執行指令碼以確認合規。

範例：API 棄用協助程式 （僅限參考）

此技能會引導客服人員在升級轉換期間取代已取代的 API 呼叫。它只會使用沒有指令碼的參考檔案。

目錄結構：

.aws/atx/skills/
└── api-deprecation-helper/
    ├── SKILL.md
    └── references/
        ├── aws-sdk-v2-to-v3.md
        └── react-class-to-hooks.md

https：//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

參考檔案包含before-and-after程式碼範例。例如， 使用 S3Client和 將 等量的模式aws-sdk-v2-to-v3.md映射s3.putObject(params).promise()至模組化 v3PutObjectCommand。

標籤和組織

您可以使用標籤來組織轉換，以進行存取控制和分類。

若要列出轉換的標籤：

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 建立新的轉換定義。

建立轉換定義

建立轉換的最佳實務：

提供參考資料

您可以在對話期間指定檔案路徑，為 AWS 轉換自訂提供參考檔案。這些檔案會存放在轉換定義的 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

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