使用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模式ID： scheduler
代理使用@Designate将Scheduler插入的作业转换为Runnable的@Component实现，将基于构造函数的计划程序注册替换为@Activate / @Deactivate生命周期方法。
ResourceChangeListener resource-change-listener
定位需要更新AEMaaCS的ResourceChangeListener或ResourceChange侦听器实施。
BPA模式ID： resourceChangeListener
复制 replication
定位导入com.day.cq.replication.Replicator或相关复制API的类，AEMaaCS不支持这些类。 代理将它们替换为基于ContentDistribution的等效项，并更新相应的OSGi服务引用。
BPA模式ID： replication
事件侦听器 event-listener
定位必须针对AEMaaCS事件处理语义更新的OSGi EventListener或EventHandler实施。
BPA模式ID： eventListener
事件处理程序 event-handler
定位需要针对AEMaaCS调整的同步OSGi EventHandler服务。
BPA模式ID： eventHandler
资产API asset-api
使用已弃用AssetManager、DAMEvent或不支持的DAM API的目标类。 代理将它们替换为支持的AEM Assets API等效项。
BPA模式ID： assetApi
番石榴缓存至咖啡因 guava-cache
使用Guava缓存的目标包（com.google.common.cache.*，如Cache、CacheBuilder和LoadingCache）。 在AEM as a Cloud Service上，支持的进程内缓存库为Caffeine，因此代理会交换Maven依赖项、更新导入并调整受影响的调用站点。 由于咖啡因是由同一位作者撰写的，其API刻意近乎完全相同，因此变化主要是机械性的。
BPA模式ID： guavaCache
BPA在 捆绑 粒度（子类型custom.guava.cache）处报告此模式，因此代理将该捆绑包解析为实际导入Guava缓存并编辑这些缓存的Java文件。 此模式仅由迁移技能（而不是code-assessment）提供，因为Guava缓存的使用情况只出现在从旧版AEM中转来的代码中，而不是本机Cloud Service代码中。
guavaCache依赖于BPA作为事实来源。 当没有可用的BPA或CAM源时，代理回退以扫描您的Java文件，以将import com.google.common.cache导入作为未确认的候选项。InputStream使用 input-stream
定位由BPA标记的java.io.InputStream用法（子类型java.io.inputstream）的Java代码。 在AEM as a Cloud Service上，通过JVM流式传输大型二进制文件可能会耗尽容器内存，因此应直接通过云blob存储和CDN上传和交付二进制文件（请参阅开发准则和直接二进制上传）。
BPA模式ID： inputStream
工程师按风险对发现结果进行分组，并以不同方式处理每个组：
Binary未关闭开始会话时间：
Fix inputStream findings using BPA CSV at ./reports/bpa.csv
inputStream依赖于BPA作为事实来源。 当没有可用的BPA或CAM源时，代理回退以扫描您的Java文件。 报告不在工作区中的代码（例如产品或第三方捆绑包）中的调查结果仅供参考。HTL Lint(data-sly-test) htl-lint
定位位于ui.apps下并生成data-sly-test: redundant constant value comparison个lint警告的HTL模板。 代理通过直接扫描内容包来发现受影响的模板；此模式不需要BPA CSV或CAM连接。
BPA模式ID： htlLint
htlLint调查结果未出现在BPA CSV导出中。 当您启动此模式的会话时，代理会通过直接文件扫描发现它们。到Cloud Manager的OSGi配置 osgi-cloud-manager
将ui.config中的OSGi配置转换为与Cloud Manager兼容的.cfg.json格式，并具有完全特定于环境的处理。 这涵盖了若干相关任务：
配置格式转换
AEMaaCS要求将OSGi配置存储为.cfg.json文件，并且在运行模式范围的文件夹（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 - 在环境令牌 —
config.dev.author前面而不是有效的config.author.dev后面的层令牌 - 非小写令牌（如
config.Author.dev）和保留的config.preview（预览从发布继承）
URC调查结果首先来自最佳实践分析器（子类型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对话框转换为触屏UI。 代理处理两个对话框子类型：ExtJS/经典UI cq:Dialog定义已重建为Coral 3 _cq_dialog结构，并且现有Coral 2对话框已就地升级到Coral 3。 它还承载侦听器optionsProvider、namePrefix和更新filter.xml。
BPA模式ID： lui （仅对话框子类型）
如果对于相同的组件同时存在对话框和自定义小组件发现，请先运行自定义小组件迁移，以便在转换对话框之前解析所有xtype引用。
Convert my Classic UI dialogs to Touch UI Coral 3.
自定义设计小组件（旧版UI） custom-design-widgets
迁移自定义ExtJS小组件（具有自定义xtype值的cq:Widget定义）。 代理清点小组件，然后将每个xtype映射到已知的Coral 3等效项，或者在不存在直接映射的情况下为Granite UI表单组件提供基架。
BPA模式ID： cdw
Migrate my custom ExtJS widgets (CDW findings) from CAM.
模板现代化 template-modernization
将静态模板转换为可编辑模板，并生成相应的AEM现代化工具重写规则（结构、组件和策略规则）。 代理分三个阶段运行：发现模板并生成每个模板的计划，按模板执行计划模板，以及验证生成的/conf结构。
在发现过程中，代理在任何深度（包括嵌套或分组的模板文件夹）浏览apps/<appId>/templates/下的模板，并根据每个静态模板的页面组件资源类型将其分类为旧模板或自定义模板。 即使没有BPA报表，此分类也可以保留，因此自定义模板的处理方式与旧模板的处理方式截然不同。
此模式不使用BPA模式ID。 开始会话时间：
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布局需要更多审核。Oak索引迁移 oak-index
将ui.apps/.../_oak_index/下的旧版Oak索引定义转换为与AEM as a Cloud Service兼容的定义。 此功能封装Adobe维护的索引转换器工具，而不是重新实现其转换规则。 它包含已就地修改的自定义Lucene索引和现成索引。
BPA模式ID： oakIndex （子类型index.rule.violation和standard.index.modification）
代理运行转换器，显示具有数据类型兼容性检查的差异，仅在确认后应用更改，然后生成ui.apps并运行AEM分析器。
AEM as a Cloud Service要求自定义索引带有-custom-<n>版本后缀，其中<n>在每次定义更改时都会增加（请参阅索引名称）。 代理选择下一个可用的<n>，因此重复迁移不会覆盖现有索引：
- 已修改的现成索引：
<indexName>-<version>-custom-<n>（例如，damAssetLucene-8-custom-1） - 新自定义索引：
<originalName>-custom-<n> - 已经兼容的索引：保持不变
模式当前生成经典_oak_index格式。 简化的索引管理作为目标格式已计划但尚未受支持。
开始会话时间：
Fix oakIndex findings using BPA CSV at ./reports/bpa.csv
验证迁移 validate-migration
在迁移模式后，代理可以在本地AEM as a Cloud Service SDK上验证结果。 验证对您的代码是只读的：代理从不编辑您的源以获得通行证。 如果检查失败，修复过程将返回到拥有该代码的迁移模式。
验证支持以下模式：
scheduler, assetApi, eventListener, eventHandler, resourceChangeListener, replicationlui, cdw其他模式，如Dispatcher转化和OSGi配置，不在验证涵盖范围内。
对于需要它的模式，请启动Cloud SDK （默认位于http://localhost:4602上）并将其AEM快速入门MCP服务器添加到您的IDE中。 然后，代理程序：
- 检查设置 — 确认所需的工具、实例和MCP服务器可用，并要求您启动任何缺少的内容。
- 准备 — 通过项目的Maven安装配置文件生成项目并部署更改的包。
- 诊断 — 从AEM快速入门MCP中读取包和组件状态。 脱机模式(
lui，cdw)跳过此步骤。 - 验证 — 将验证报告写入项目中的
.validate-migration/。
如果您的项目链接到Cloud Acceleration Manager项目（例如，通过迁移Runbook），则代理还会通过AEM MCP服务器的云迁移功能在CAM中记录验证结果。
开始会话时间：
Validate my scheduler migration on the local Cloud SDK.
BPA Source选项 bpa-source
MCP错误处理 mcp-errors
如果MCP连接返回错误（包括找不到项目或身份验证失败），代理将停止并显示错误。 它不会自动切换到另一个源。 从“已停止”状态，您可以：
- 从显示代理的列表中确认正确的项目
- 提供BPA CSV路径作为替代方法
- 为手动迁移提供特定的Java文件路径
管理大型报表中的会话 large-reports
对于具有许多发现结果的BPA报表，逐批方法允许您逐步验证：
- 查看每个批次的差异
- 使用模式范围的提交消息提交批处理
- 回复
continue以开始下一批处理 - 重复执行上述步骤，直到座席报告模式的所有查找结果都已完成
每个提交一个模式可让您的Git历史记录保持可读性，并可以根据需要轻松还原各个模式转换。
Workspace范围 workspace-scope
代理仅在打开的IDE Workspace文件夹中搜索和编辑文件。 它不会扫描磁盘上的父目录、同级文件夹或其他位置。
如果BPA查找结果引用了工作区中不存在的文件路径，则代理将停止并告知您缺少哪些路径。 打开正确的项目文件夹或明确提供路径以继续。