使用AEM Cloud移轉技能 using-cloud-migration-skill
此參考資料涵蓋各種支援的移轉模式、如何提供BPA發現，以及如何管理大型專案中的工作階段。 如需簡介和設定說明，請參閱概觀。
產生移轉Runbook migration-runbook
對於整個專案評估，從Runbook開始，而不是命名單一模式。 提示代理程式：
Review my code for AEMaaCS migration
此技能會在您的專案根目錄中產生唯讀migration-runbook.md，而不會變更任何程式碼。 Runbook涵蓋 移轉技能可處理的每 個模式，並針對每個模式記錄：
- 使用的偵測策略（BPA/CAM發現、分析器或啟發式內容掃描）
- 受影響的檔案和每個模式的發現計數
- 啟動模式移轉工作階段的複製貼上提示
由於Runbook也會在Markdown旁邊寫入發現專案快取，因此之後的模式工作階段會重複使用已發現的發現專案，代理程式不會重新掃描。 使用Runbook來排定要先處理哪些模式的優先順序，然後如下所述開始模式工作階段。
工作階段的運作方式 workflow-overview
每個移轉工作階段會依照此順序進行：
- 命名模式：指定一個模式（例如，
scheduler） - 提供發現：從BPA CSV檔案、透過MCP的CAM或特定檔案路徑
- 代理程式讀取轉換規則：此技能會先從同伴
code-assessment技能讀取相關的轉換規則，然後再進行任何程式碼變更 - 第一批五個：代理程式最多可轉換五個發現專案並報告變更的內容
- 您檢閱並繼續：檢閱每個批次後，回覆
continue以繼續下一批次
代理程式一次會處理一個模式和一個批次。 不會自動繼續；每個批次都需要您的確認。
移轉模式 patterns
排程器 scheduler
目標鎖定使用與AEMaaCS的無狀態、容器化執行階段不相容sling.commons.scheduler或Scheduler插入的Java類別。
BPA模式識別碼： scheduler
代理程式會使用@Designate將Scheduler插入的工作轉換為Runnable的@Component實作，將建構函式式排程器註冊取代為@Activate / @Deactivate生命週期方法。
ResourceChangeListener resource-change-listener
鎖定需要AEMaaCS更新的ResourceChangeListener或ResourceChange接聽程式實作。
BPA模式識別碼： resourceChangeListener
複製 replication
目標類別匯入com.day.cq.replication.Replicator或AEMaaCS不支援的相關復寫API。 代理程式會以ContentDistribution型對等項取代它們，並更新對應的OSGi服務參照。
BPA模式識別碼： replication
事件監聽器 event-listener
鎖定必須針對AEMaaCS事件處理語意更新的OSGi EventListener或EventHandler實作。
BPA模式識別碼： eventListener
事件處理常式 event-handler
鎖定需要針對AEMaaCS調整的同步OSGi EventHandler服務。
BPA模式識別碼： eventHandler
資產API asset-api
使用已棄用AssetManager、DAMEvent或不支援的DAM API的目標類別。 代理程式會將其取代為支援的AEM Assets API對等函式。
BPA模式識別碼： assetApi
番石榴石快取至咖啡因 guava-cache
目標使用Guava快取的組合（com.google.common.cache.*，例如Cache、CacheBuilder和LoadingCache）。 在AEM as a Cloud Service上，支援的處理序內快取程式庫是Caffeine，因此代理程式會交換Maven相依性、更新匯入並調整受影響的呼叫網站。 由於咖啡因是由同一位作者所撰寫，且其API刻意近乎完全相同，因此大部分的變更是機械性的。
BPA模式識別碼： guavaCache
BPA在 套件 粒度（子型別custom.guava.cache）報告此模式，因此代理程式會將此套件解析為實際匯入Guava快取的Java檔案並編輯這些檔案。 此模式僅由移轉技能提供（而非code-assessment），因為Guava快取使用只發生在從舊版AEM轉存的程式碼中，不會發生在原生Cloud Service程式碼中。
guavaCache仰賴BPA做為真相來源。 當沒有可用的BPA或CAM來源時，代理程式會退回來掃描您的Java檔案，以將import com.google.common.cache匯入作為未確認的候選專案。HTL Lint (data-sly-test) htl-lint
鎖定在ui.apps下產生data-sly-test: redundant constant value comparison個Lint警告的HTL範本。 代理程式會透過直接掃描內容套件來探索受影響的範本；此模式不需要BPA CSV或CAM連線。
BPA模式識別碼： htlLint
htlLint個發現未出現在BPA CSV匯出中。 當您啟動此模式的工作階段時，代理程式會透過直接檔案掃描來探索這些模式。Cloud Manager的OSGi設定 osgi-cloud-manager
將ui.config中的OSGi設定轉換為與Cloud Manager相容的.cfg.json格式，並具有完整的環境特定處理。 這涵蓋幾項相關工作：
設定格式轉換
AEMaaCS需要將OSGi設定儲存為.cfg.json個檔案，並在runmode範圍的資料夾（config.author/、config.publish/、config.dev/等）中使用環境特定的設定。 代理程式：
- 將現有
.config、.cfg和XML格式的OSGi設定轉換為.cfg.json - 將包含作者和發佈特定值的設定分割為個別執行模式範圍的檔案
- 根據OSGi中繼型別規格驗證屬性型別（字串、整數、布林值、陣列）
- 標示Adobe擁有的PID以供手動檢閱，而非自動轉換
密碼和環境變數
將純文字密碼和環境特定值移出已提交的設定檔案，並以Cloud Manager預留位置取代它們：
$[secret:NAME]：用於密碼、權杖和其他敏感值$[env:NAME]：針對每個環境不同的非敏感值（例如，服務URL）
對應的變數和秘密會在Cloud Manager中套用，並在執行階段插入；原始檔控制中不會儲存任何值。
不支援的執行模式(URC)
AEM as a Cloud Service支援一組固定的執行模式識別碼。 使用不支援之執行模式的設定資料夾在部署後即無效。 代理程式會標籤這些不受支援的執行模式設定(URC)，包括：
- 未知的執行模式權杖，例如
config.qa或install.local - 在環境Token—
config.dev.author之前，而不是在有效config.author.dev之前，在後面而不是之前的層級Token - 非小寫的Token （例如
config.Author.dev）和保留的config.preview（預覽繼承自發佈）
URC發現結果首先來自Best Practices Analyzer （子型別unsupported.runmode，嚴重性CRITICAL）；當沒有BPA來源報告時，代理程式會在本機掃描config.*和install.*資料夾作為安全網。 對於每個發現，它會報告資料夾路徑、違規執行模式和修正 — 評估是否仍需要配置、將其重新命名為支援的執行模式，或將其移除（如果過時）。 若是僅限排序的違規，即每個權杖都有效但順序錯誤，代理程式可以自動套用安全重新排序（例如，將config.dev.author重新命名為config.author.dev）；系統會標示未知的權杖和其他模稜兩可的案例以供您解析。
設定格式轉換和秘密外部化不需要BPA CSV或CAM，且URC偵測會在可用時使用BPA發現。 開始工作階段於：
Scan my config files and create Cloud Manager environment secrets or variables.
對話方塊移轉（舊版UI） dialog-migration
將傳統UI對話方塊轉換為Touch UI。 代理程式會處理兩個對話方塊子型別：ExtJS / Classic UI cq:Dialog定義已重建為Coral 3 _cq_dialog結構，而現有的Coral 2對話方塊已升級為Coral 3。 它也承載接聽程式optionsProvider、namePrefix和更新filter.xml。
BPA模式識別碼： lui （僅限對話方塊子型別）
若相同元件同時存在對話方塊和自訂Widget發現，請先執行自訂Widget移轉，以便在轉換對話方塊之前解析所有xtype參考。
Convert my Classic UI dialogs to Touch UI Coral 3.
自訂設計Widget （舊版UI） custom-design-widgets
移轉自訂ExtJS Widget （cq:Widget個具有自訂xtype值的定義）。 代理程式會清查Widget，然後將每個xtype對應到已知的Coral 3對等專案，或在沒有直接對應存在時搭配Granite UI表單元件。
BPA模式識別碼： cdw
Migrate my custom ExtJS widgets (CDW findings) from CAM.
範本現代化 template-modernization
將靜態範本轉換為可編輯的範本，並產生對應的AEM現代化工具重寫規則（結構、元件和原則規則）。 代理程式會以三個階段執行：探索範本並產生每個範本的計畫、依範本執行計畫範本，以及驗證產生的/conf結構。
在探索期間，代理程式會在任何深度（包括巢狀或群組的範本資料夾）瀏覽apps/<appId>/templates/下的範本，並根據其頁面元件資源型別將每個靜態範本分類為舊版或自訂。 即使沒有BPA報告，此分類仍可保留，因此自訂範本的處理方式與傳統範本不同。
此模式不使用BPA模式識別碼。 開始工作階段於：
Migrate my static templates to editable templates and generate the Modernize Tools rewrite rules.
Dispatcher轉換 dispatcher-conversion
將AMS或內部部署Apache HTTPD和Dispatcher設定轉換為AEM as a Cloud Service結構。 此功能封裝Adobe維護的Dispatcher Converter工具，新增偵測、設定產生、輸出驗證及相關的驗證。
代理程式會透過分階段流程運作：
- 偵測及清查 — 決定組態模式，並記錄篩選、重寫及快取規則的基準計數。 可辨識的模式為
standard(AMS)、flexible（整體式內部部署）、v1（較舊的配置）、already-cloud、not-dispatcher和unknown。 對於already-cloud、not-dispatcher或unknown，代理程式會停止並要求您先確認，然後再繼續。 - 規劃並產生設定 — 建置轉換器設定，並與您確認計畫。
- Convert — 執行Adobe的Dispatcher轉換器（第一次使用時自動安裝）。
- 驗證 — 根據基準檢查輸出。 清空的篩選器集(
filter-acl-loss)是硬性停止，必須解決後才能繼續。 - 跨邊界切換 — 將Cloud Manager環境變數路由到OSGi設定流程，並標示CDN或安全性標頭候選專案。
- 驗證 — 執行Cloud Service Dispatcher驗證器並產生合併的轉換報告。
Runbook模式ID： dispatcherConversion （從設定配置以試探方式偵測到）。 此圖樣不使用BPA或CAM。 開始工作階段於：
Convert my AMS / on-prem Dispatcher config to AEM as a Cloud Service.
standard (AMS)組態近乎自動化，而flexible和v1配置需要更多檢閱。BPA Source選項 bpa-source
MCP錯誤處理 mcp-errors
如果MCP連線傳回錯誤（包括找不到專案或驗證失敗），代理程式會停止並顯示錯誤。 它不會自動切換到另一個來源。 從已停止狀態，您可以：
- 從顯示代理程式的清單中確認正確的專案
- 提供BPA CSV路徑作為替代方法
- 為手動移轉提供特定的Java檔案路徑
管理大型報表中的工作階段 large-reports
針對具有許多發現專案的BPA報表，逐批次方式可讓您逐步驗證：
- 複查每個批次的差異
- 使用模式範圍的認可訊息認可批次
- 回覆
continue以開始下一個批次 - 重複此步驟，直到代理程式報告模式的所有發現專案都完成為止
每個認可一個模式可讓您的Git歷程記錄保持可讀，並視需要輕鬆還原個別模式轉換。
Workspace範圍 workspace-scope
代理程式只會搜尋和編輯開啟的IDE Workspace資料夾中的檔案。 它不會掃描磁碟上的父目錄、同層級資料夾或其他位置。
如果BPA發現所參照的檔案路徑在工作區內不存在，代理程式會停止並告訴您哪些路徑遺失。 開啟正確的專案資料夾或明確提供路徑以繼續。