本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 工作流程 ## 執行轉換 本節說明執行轉換的不同方式，以及控制執行行為的選項。 ### 執行模式 AWS 轉換自訂支援三種執行模式，以適應不同的工作流程。 **互動式對話模式** 使用 啟動 CLI，`atx`並要求代理程式透過自然語言執行轉換。此模式可讓您與客服人員進行完整對話、隨時中斷執行，並在轉換過程中提供意見回饋。 當您想要獲得最大控制，以及能夠引導客服人員完成複雜案例時，請使用此模式。 **直接互動式執行** 使用 `atx custom def exec -n -p ` 以互動方式啟動特定轉換。此模式可讓您在執行開始時、期間或結束時，檢閱代理程式並與之互動。客服人員會在關鍵決策點暫停，並詢問您的輸入。 這非常適合在自動執行轉換之前進行測試和精簡轉換。 您可以在非互動式模式或無周邊模式下執行轉換。非互動式模式會在具名轉換期間隱藏提示。無頭模式可讓您使用純文字提示執行代理程式，完全略過互動式界面。 #### 非互動式模式 使用 `atx custom def exec -n -p -x -t` 進行完整自動化。新增 `-t` `-x`以在非互動式模式下執行，並在不提示的情況下自動信任所有工具。 此模式專為 CI/CD 管道整合和大量執行而設計，其中沒有可用的人工介入或不需要人工介入。 #### 無周邊模式 若要在不與代理程式互動的情況下完成任務，請以純文字執行`atx -x "" -t`並提供您的指示。 ##### 無周邊轉換執行 使用此模式將現有的轉換定義套用至您的程式碼庫。轉換會自動執行每個步驟，而不需要您的核准。 ``` atx -x "apply transformation definition to " -t ``` ##### 無周邊轉型開發 建立或修改轉換定義。 若要將舊版轉換定義轉換為新的技能格式 (SKILL.md：// \+ references/)，請執行下列命令： ``` atx -x "convert transformation definition to skill and save as draft" -t ``` 若要建立新的轉換定義，請執行下列命令： ``` atx -x "create a transformation definition to with references docs " -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`旗標會自動核准所有工具執行，而不會提示並略過大多數的安全防護機制 （除非 覆寫，否則符合您`alwaysPromptCommands`清單的命令仍需要明確許可`trustedShellCommands`)。完全自主的體驗需要傳入 `--trust-all-tools` `--non-interactive`和 ，但執行轉換不需要。在生產環境中謹慎使用 。 ### 使用組態檔案 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 轉換自訂會嘗試根據轉換推斷最佳建置命令，但建議針對品質而言是特定的。 **建置和驗證命令的範例：** + 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`旗標選擇退出允許從目前執行中擷取課程。 ### 繼續對話 AWS 轉換自訂可讓您在建立後的 30 天內繼續先前的對話。 **若要繼續最近的對話：** ``` atx --resume ``` **若要繼續特定對話：** ``` atx --conversation-id ``` **重要** 對話只能在建立後的 30 天內恢復。30 天後，就無法再繼續對話。 ### 追蹤代理程式分鐘數 AWS 轉換自訂會追蹤轉換工作階段期間使用的[客服人員分鐘](https://aws.amazon.com/transform/pricing/)數。客服人員分鐘會累積到整個對話生命週期，並在對話結束時顯示： ``` Agent minutes used: 12.50 ``` 客服人員分鐘會在中斷期間持續存在。如果您使用 Ctrl\+C 中斷工作階段並稍後繼續，則先前累積的分鐘會繼續累積在繼續的工作階段中。 **若要在互動式工作階段期間檢查客服人員分鐘數：** `/usage` 在輸入提示中輸入 ，以顯示目前累積的客服人員分鐘，而不結束對話。 **若要設定客服人員分鐘預算限制：** ``` atx custom def exec -n my-transformation -p ./my-project --limit 30 ``` `--limit` 選項會設定工作階段的[客服人員分鐘](https://aws.amazon.com/transform/pricing/)預算上限。客服人員分鐘反映作用中的客服人員工作時間，而不是牆上時鐘時間。達到限制時，CLI 會顯示訊息並結束，其中包含繼續的指示： ``` ⚠️ Budget limit reached: 30.00 / 30.00 Agent Minutes. Exiting. ``` 您可以稍後以更高的限制繼續對話： ``` atx --conversation-id -t --limit ``` ## 持續學習 本節說明如何檢閱和管理持續學習所建立的課程。 ### 了解 課程 持續學習系統會自動從先前的轉換執行中擷取教訓。系統會根據下列項目以非同步方式建立它們： + 在互動式模式中提供的開發人員意見回饋 + 轉換期間遇到的程式碼問題 當您跨不同的程式碼庫執行轉換時，課程會隨著時間累積。系統會自動套用它們來改善未來的執行。每個課程都屬於一個類別，其中包含類似網域的所有課程，以便您可以一起檢閱相關的課程。對於您不想使用的課程，您可以完全封存或刪除該課程。 ### 檢視和管理課程 使用 `learnings`命令開啟互動式工作階段，以瀏覽和管理轉換定義的教訓。 **若要開啟課程檢視器：** ``` atx custom def learnings -n my-transformation ``` 檢視器會在課程類別清單上開啟，每個類別都會顯示其中包含多少個作用中的課程。選取類別以查看其教訓，然後選取一個教訓以檢視其完整詳細資訊，包括課程內文、其影響，以及之前查閱的執行次數。 ### 封存和還原課程 系統會自動套用課程。如果您不希望系統套用課程，您可以將其封存。系統會保留封存的課程，但不會將其套用至未來的執行。所有封存的課程都會分組在一起，因此您可以檢閱它們，並將任何 還原為作用中使用。 ### 刪除課程 永久移除沒有幫助的課程。刪除無法復原，系統可能會從未來的執行中重新學習已刪除的課程。 必須先封存課程，才能將其刪除。 ## 進階組態 本節說明 AWS 轉換自訂的進階功能和組態選項。 ### 環境變數 您可以使用環境變數自訂 CLI 行為。 **注意** 下列範例顯示 Linux 和 macOS 語法 (`export`)。在 Windows 上，使用 在 PowerShell 中設定環境變數`$env:{{NAME}}="{{value}}"`。如需同等命令，請參閱 **Windows (PowerShell)** 索引標籤。 **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 `)。將兩個變數設定為將檢查點屬性設為特定作者。 ------ #### [ 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`支援使用 的 glob 萬用字元模式`*`。 **注意** 如果命令同時符合這兩個清單， `trustedShellCommands`會優先處理。 以下說明每個命令清單並提供範例： + `trustedShellCommands` - 符合這些模式的命令在不提示的情況下執行，繞過所有其他護欄。模式會比對完整的命令字串。 範例： + `cd *` - 比對以 cd 開頭的複合命令 + `*&&*` - 信任所有具有 && 運算子的命令 + `alwaysPromptCommands` - 符合這些模式的命令需要明確許可，除非由 覆寫`trustedShellCommands`，無論`-t`旗標或工作階段信任為何。這些模式不會在非互動式模式中強制執行 (`-x`)。模式會與複合表達式 (`&&`、`||`、命令替換） 中的每個子命令進行比對。 範例： + `rm -rf *` - 一律提示遞迴強制刪除命令 + `sudo *` - 一律提示使用 sudo 執行的命令 + `find * -exec *` - 一律使用 -exec 提示尋找命令 **工作階段層級信任：** 在互動式提示期間，您可以選擇： + `(y)es` - 執行一次 + `(n)o` - 拒絕 + `(t)rust` - 僅限目前工作階段的信任 工作階段層級信任設定是暫時的，並在 CLI 重新啟動時重設，提供暫時核准，而不會永久修改 trust-settings.yaml。 **注意** 工作階段信任不適用於符合您`alwaysPromptCommands`清單的命令。 ### 模型內容通訊協定 (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 字符等敏感值存放在環境變數中，而不是儲存在組態檔案中。 **組態屬性：** 本機命令型伺服器支援下列屬性： + `command` （必要） - 執行伺服器的命令 + `args` （選用） - 命令列引數陣列 + `env` （選用） - 要傳遞至伺服器程序的環境變數 遠端 HTTP 伺服器支援下列屬性： + `url` （必要） - 遠端 MCP 伺服器的 HTTP 或 HTTPS URL + `headers` （選用） - 包含在請求中的 HTTP 標頭，支援`${VAR_NAME}`環境變數擴展 **管理 MCP 伺服器：** 檢視設定的 MCP 伺服器清單： ``` atx mcp tools ``` 列出特定 MCP 伺服器提供的可用工具： ``` atx mcp tools --server ``` **用量追蹤：** CLI 會在轉換執行期間自動追蹤 MCP 工具用量。用量統計資料會與 一起保留`mcp_usage.json`為對話目錄中的 `metadata.json`。每個執行的檔案會記錄每個工具的指標，包括： + 每個工具的叫用次數 + 每個工具的錯誤數量 + 每個工具的總執行時間 + 上次錯誤詳細資訊 （如果有的話） ### 用戶端技能 用戶端技能是在轉換執行期間擴展代理程式的額外功能。它們可讓您提供自訂工具、指令碼和指示，讓代理程式與其內建功能搭配使用。 **技能探索目錄：** 技能會依優先順序從四個目錄探索。如果具有相同名稱的技能存在於多個目錄中，則清單中的第一個目錄會優先： 1. `/.aws/atx/skills/` - 專案層級， AWS Transform CLI 特定 1. `/.agents/skills/` - 專案層級、跨用戶端 （適用於任何相容的代理程式工具） 1. `~/.aws/atx/skills/` - 使用者層級， AWS Transform CLI 特定 1. `~/.agents/skills/` - 使用者層級、跨用戶端 （適用於任何相容的代理程式工具） `.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，或保留僅供人類讀者使用的參考資料。 **注意** 停用的技能檔案會保留在磁碟上。如果轉換定義指示代理程式讀取特定檔案路徑，代理程式仍然可以存取內容。`disable-model-invocation` 屬性可防止自動探索和內容注入，而不是檔案系統存取。 **依執行模式區分的技能可用性：** + **Exec 模式** (`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 ``` ------ 驗證失敗的技能會略過，並在偵錯日誌中出現警告。 **注意** 用戶端技能需要 CLI 2.0 版或更新版本。 #### 在專案層級和使用者層級技能之間進行選擇 您放置技能的位置會決定誰從中受益，以及啟用的時間。 **專案層級技能 **(`/.aws/atx/skills/`)： 將這些遞交至版本控制，讓每個針對儲存庫執行轉換的團隊成員自動探索它們。將專案層級技能用於： + 儲存庫特定的合規檢查 (Dockerfile 規則、Terraform 政策、遷移安全驗證程式） + 適用於此程式碼庫的組織編碼標準 （可觀測性模式、錯誤處理、命名慣例） + 建置或測試專案特有的指令碼 （自訂文字、架構健身函數） + 此儲存庫中使用的內部程式庫 API 遷移指南 **使用者層級技能 **(`~/.aws/atx/skills/`)： 這些會保留在您的機器上，並在所有轉換期間啟用，無論您以哪個儲存庫為目標。將使用者層級技能用於： + 個人工作流程工具 (changelog 產生器、遞交訊息格式器） + 跨專案偏好設定 （偏好的測試模式、文件樣式提醒） + 您的組織在所有儲存庫中所需的授權合規檢查 + 您使用的每個程式碼庫強制執行的涵蓋閾值或品質閘道 **有效技能的秘訣：** + 在您的`SKILL.md`前端編寫清晰`description`的欄位。客服人員使用此欄位來決定技能的相關性。 + 在成功時以代碼 0 結束驗證指令碼，在失敗時以非零結束驗證指令碼。代理程式會解譯結束代碼以判斷合規性。 + 在指令碼中列印清晰、可行的錯誤訊息。代理程式會讀取輸出以了解要修正的項目。 + 將技能放在任一層級的跨用戶端目錄 (`.agents/skills/`) 中，以與 AWS Transform CLI 以外的其他 AI 開發工具共用。 #### 用戶端技能範例 這些範例顯示兩種常見模式：以指令碼為基礎的驗證技能和僅限參考技能。 ##### 範例：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 ` 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()`至模組化 v3`PutObjectCommand`。 ### 標籤和組織 您可以使用標籤來組織轉換，以進行存取控制和分類。 **注意** 其中一些命令需要指定轉換定義的 Amazon Resource Name (ARN)。ARN 結構為： `arn:aws:transform-custom:::package/` **若要列出轉換的標籤：** ``` atx custom def list-tags --arn ``` **若要將標籤新增至轉換：** ``` atx custom def tag --arn --tags '{"env":"prod","team":"backend"}' ``` **若要從轉換中移除標籤：** ``` atx custom def untag --arn --tag-keys "env,team" ``` 標籤可用於 IAM 政策中的分組存取控制。您可以建立政策，將許可授予具有特定標籤的所有轉換 （例如，所有以 `team:frontend`或 標記的轉換`environment:production`)。 ### 日誌 AWS Transform CLI 會維護三種類型的日誌，以進行疑難排解和偵錯。 **對話日誌：** ------ #### [ Linux and macOS ] ``` ~/.aws/atx/custom//logs/-conversation.log ``` ------ #### [ Windows ] ``` %USERPROFILE%\.aws\atx\custom\\logs\-conversation.log ``` ------ 這些日誌包含特定工作階段的完整對話歷史記錄。 **子代理程式日誌：** ------ #### [ Linux and macOS ] ``` ~/.aws/atx/custom//logs/subagents/.log ``` ------ #### [ Windows ] ``` %USERPROFILE%\.aws\atx\custom\\logs\subagents\.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//\* 和 \~/.aws/atx/logs/\*。 ### CLI 更新 將您的 CLI 保持在最新狀態，以存取新功能和改善項目。 **若要檢查更新：** ``` atx update --check ``` **若要更新至最新版本：** ``` atx update ``` **若要更新至特定版本：** ``` atx update --target-version ``` ## 建立自訂轉換 本節說明如何建立、修改和管理自訂轉換定義。 ### 建立新的轉換 使用互動式 CLI 建立新的轉換定義。 **建立轉換定義** 1. 啟動 AWS 轉換 CLI： ``` atx ``` 1. 告訴客服人員您要建立新的轉換。 1. 提供清楚、詳細的轉換目標說明。包括： + 來源和目標狀態 （例如「從 X 版升級至 Y 版」) + 所需的特定變更 （例如「更新匯入陳述式、取代已棄用的方法」) + 任何特殊考量或限制 1. 當客服人員請求釐清或其他資訊時，請提供特定範例和參考資料。 1. 檢閱客服人員建立的初始轉換定義。 1. 在範例程式碼庫上測試轉換。 1. 透過提供意見回饋、程式碼修正或其他範例來反覆運算。 1. 在本機儲存轉換，或將其發佈至登錄檔。 **建立轉換的最佳實務：** + 先從簡單、定義明確的轉換開始，然後再嘗試複雜的轉換 + 提供完整的參考資料，包括遷移指南和程式碼範例 + 發佈前在多個範例程式碼庫上測試 + 使用確定性建置或驗證命令來啟用持續學習 + 考慮將複雜的轉換分成多個較小的步驟 + 在轉換定義中以「關鍵：」或「重要：」標記重要資訊，以確保代理程式優先考慮這些要求 + 當您需要遵循確切的要求時 （例如使用特定命令或字串值），請在轉換定義中明確指定完整字串。您可以用 bash 引號括住這些引號，以清楚指出它們是終端機命令或常值字串，這可減少變異性並確保一致的執行 ### 提供參考資料 您可以在對話期間指定檔案路徑，為 AWS 轉換自訂提供參考檔案。這些檔案會存放在轉換定義的 `references/` 資料夾中。 建議的參考檔案類型： + 範例程式碼之前/之後 + 涉及APIs、程式庫或功能的文件 + 人類可讀遷移指南 **若要提供參考檔案：** ``` 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 ``` 1. 告知客服人員您要修改現有的轉換。 1. 選擇是否： + 提供本機儲存轉換的檔案路徑 （即不是儲存的草稿或發佈） + 從登錄檔請求轉換清單 1. 如果從登錄檔中選擇，請選取您要修改的轉換。 1. 與客服人員合作，描述您要進行的變更。 1. 在範例程式碼庫上測試更新的轉換。 1. 視需要將更新發佈至登錄檔。 ### 發佈和管理轉換 您可以使用互動式體驗或下列命令來發佈和管理轉換。 **若要將轉換儲存為草稿：** ``` 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 ``` 如果未指定版本，則會使用最新版本。