使用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导入作为未确认的候选项。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布局需要更多审核。BPA Source选项 bpa-source
MCP错误处理 mcp-errors
如果MCP连接返回错误（包括找不到项目或身份验证失败），代理将停止并显示错误。 它不会自动切换到另一个源。 从“已停止”状态，您可以：
- 从显示代理的列表中确认正确的项目
- 提供BPA CSV路径作为替代方法
- 为手动迁移提供特定的Java文件路径
管理大型报表中的会话 large-reports
对于具有许多发现结果的BPA报表，逐批方法允许您逐步验证：
- 查看每个批次的差异
- 使用模式范围的提交消息提交批处理
- 回复
continue以开始下一批处理 - 重复执行上述步骤，直到座席报告模式的所有查找结果都已完成
每个提交一个模式可让您的Git历史记录保持可读性，并可以根据需要轻松还原各个模式转换。
Workspace范围 workspace-scope
代理仅在打开的IDE Workspace文件夹中搜索和编辑文件。 它不会扫描磁盘上的父目录、同级文件夹或其他位置。
如果BPA查找结果引用了工作区中不存在的文件路径，则代理将停止并告知您缺少哪些路径。 打开正确的项目文件夹或明确提供路径以继续。