code-assessment

AEM as a Cloud Service — 代码评估

用于检测和修复 AEM CS 代码质量问题的单一技能，完全针对本地工作区——不调用外部服务或网络。发现结果通过两个来源之一进入运行手册；后续流程完全相同。

发现结果来源

来源	适用场景	目标版本（依赖项）
用户指定	用户指定文件或坐标	用户提供
发现	用户要求扫描，或未指定文件	用户提供（根据对应模式的解析约定）

发现流程通过确定性 analyzer（scripts/analyze.sh）运行： 它会解析一次工作区，并运行已启用的检测器，输出统一的发现结果格式。 每个 ready 模式都有一个 analyzer 检测器。其中一个检测器 — remove-deprecated-api — 会从预检生成的缓存中动态加载规则 （remove-deprecated-api/scripts/detect.sh 会运行 AEM Analyser Maven Plugin，并在调用 analyzer 前写入缓存 TSV）；除此之外，该检测器的格式和集成方式均相同。没有检测器的模式仅为 planned——尚不可检测，也尚未构建；此版本没有 LLM 扫描回退方案（参见“范围与限制”）——references/patterns.md 中 planned 行的 scan 值表示预期的未来检测方法，而非当前生效的代码路径。

路由

1. 用户指定了文件／坐标 → 针对这些路径，以 with_findings 模式运行运行手册。
2. “扫描我的仓库”／未指定文件 → 以 discover 模式运行运行手册（按模式逐一发现，仅扫描工作区根目录）。

接下来按照运行手册操作：references/runbook.md。

手动模式提示（分类 → 专家技能）

将请求路由到一项专家技能。以下两类模式共用此技能：

机械式修复（由分析器驱动检测，确定性编辑——遵循操作手册流程）：

用户说过 / 看到	专家技能
“update aem sdk”、“upgrade mockito”，pom 中过时的 <version> 或 ${property}	outdated-dependencies/
“fix @Inject”、“modernize Sling Models”，@Model 字段上的 javax.inject.Inject	inject-in-sling-model/
“add HTTP timeouts”、“outbound/external call has no timeout”，构建时未设置超时的 HttpClient / HttpClients / OkHttpClient	outbound-call-timeouts/
“bound my query”、“unbounded query”、“query causing OOM”，p.limit=-1、setLimit(-1)	unbounded-query/
“query is slow”、“traversal warning”、“is my query indexed”、“tune oak index”，JCR/Oak 查询的索引覆盖情况	tuning-oak-query-indexes/
“remove deprecated API”、“fix deprecated imports”、“Cloud Manager deprecated API failure”，region-deprecated-api / api-regions-check / Import-Package not satisfied 流水线故障、log4j 迁移、commons-lang/collections 升级、已弃用的 Maven 依赖、不可修改的 OSGi 配置	remove-deprecated-api/ （使用动态规则的分析器检测器——预检会运行 aemanalyser-maven-plugin；由提示驱动修复；参见 recipe.md）

架构迁移模式（引导式修复——提供完整的迁移前后对比、故障排查和现代替代方案；可直接调用，也可通过 migration 发现 BPA/CAM 驱动的问题）：

用户说过 / 看到	专家技能	BPA 模式 ID
org.apache.sling.commons.scheduler.Scheduler，或使用 Runnable 的 scheduler.schedule(	scheduler/	scheduler
implements ResourceChangeListener，轻量级侦听器 + JobConsumer	resource-change-listener/	resourceChangeListener
com.day.cq.replication.Replicator、org.apache.sling.replication.*、“publish/preview activation”	replication/	replication
javax.jcr.observation.EventListener、用于非资源主题（复制、工作流、自定义主题）的 org.osgi.service.event.EventHandler	event-migration/	eventListener / eventHandler
com.day.cq.dam.api.AssetManager 的创建/上传/删除 API、createAssetForBinary、removeAssetForBinary	asset-manager/	assetApi
HTL 构建警告 data-sly-test: redundant constant value comparison	references/data-sly-test-redundant-constant.md	htlLint（参考资料，没有对应的专家技能子目录）

广泛 / 正确性审查类请求（“检查我的 Sling Models 是否实现正确”、“审查我的代码”、“我的 AEM 项目是否健康”、“评估此项目”）并不对应单一模式：以 discover 模式运行操作手册，并将意图设为 report——分析器会运行所有检测器，报告涵盖所有已构建的模式，并明确指出尚不支持的方面。只有当用户针对特定修复时，才缩小到单一模式。

如果没有匹配项，请说明该问题目前尚不受支持，并提出可以提交新增专家技能的请求。

完整目录（已构建和 planned 模式，包含严重性 / 检测 / 修复）：references/patterns.md。

从 migration 技能调用

migration 负责 BPA/CAM/MCP 发现，并处理批次划分和每个会话一个模式的工作流。在根据 BPA 发现结果识别出 (pattern, file) 对后，它会在此处交接，以执行实际转换。从 migration 以 (pattern, file) 调用时：

• 跳过 HA/分析器发现（调用方已识别模式和文件）
• 直接打开该模式的专家技能（参见上方的 Manual Pattern Hints 表）
• 按照专家技能中的步骤处理指定文件
• 返回结果；migration 会继续处理该批次中的下一条发现

模式指南本身不依赖调用来源——无论是从 migration（BPA/CAM）调用，还是从本技能中的操作手册调用（HA/分析器），其执行方式都相同。

操作手册

所有检测、规划、编辑、验证、git/原地处理和运行日志均由 references/runbook.md 负责。操作手册是仓库环境 检测（edit_mode、git 快照）的唯一负责人——此控制平面不会重复处理。

每个会话一个模式

报告可以涵盖发现的所有模式；应用阶段每个会话只处理一个模式（可原子回退， 差异内容聚焦于单个任务）。应用阶段拒绝“全部修复”的要求。原因： references/shared-principles.md。

重要规则

• 仅限本地——不得进行网络调用或使用外部服务；只能在工作区内操作。 文档中注明的例外： remove-deprecated-api 由插件驱动，需要 Maven Central （用于解析 aemanalyser-maven-plugin，以及作为传递依赖的 AEM SDK api-regions 数据）， 并可选择使用 Adobe Experience League 作为后备来源，以获取后继方案指导。如果处于离线状态， 将跳过这一模式并给出明确说明；其他所有模式仍仅限本地操作。
• 检测需要本地 JDK（Java 11+）——分析器会在内存中编译和运行；除 JDK 外无需安装任何内容，也无需网络。如果未安装 JDK，检测会停止并给出明确说明。
• 分析器用于检测——绝不使用外部工具替代。 不要运行 mvn versions:display-dependency-updates / mvn versions:display-property-updates、 npm outdated，也不要查询 Maven Central / 注册表来替代分析器发现。这些操作回答的是“网络上最新的版本是什么”——不符合本技能仅限本地的约定。如果用户明确要求实时注册表对比，请说明这需要网络，并提出在交付技能报告之后单独执行。remove-deprecated-api 的预检 （remove-deprecated-api/scripts/detect.sh）是文档中注明的唯一例外：它会针对项目调用 AEM Analyser Maven Plugin，以填充其规则缓存，然后交由共享分析器处理。
• 绝不提交、推送或发起 PR——只能在分支（git）中编辑或直接原地编辑；由开发者审核并提交。
• 精确修改——不重新格式化或重新序列化。
• 跳过时说明原因——将不适用的发现记录为 skipped，并填写准确原因；绝不默默丢弃。
• 应用阶段每个会话处理一个模式。

完整说明：references/shared-principles.md。

范围和限制

仅进行本地静态检测和修复——不使用外部服务、不联网、不连接实时 AEM 实例。需要运行时或实时存储库状态、遥测数据或跨运行历史记录的问题，不在本技能的范围内。 检测需要本地 JDK（Java 11+）；此版本不提供远程或 LLM 扫描后备方案。 大规模应用（例如跨 100 多个文件迁移 @Inject）会以可恢复的批次处理：运行过程会将每个文件的检查点保存到 .autofix/last-run.json，并在达到每轮上限时暂停，因此即使遇到上下文限制也能继续——回复 apply <pattern> 以继续（参见 references/git-workflow.md）。

添加新模式

完整的端到端流程——检测器 → 测试夹具/测试 → 目录 + 路由 → 专家技能 → 验证： references/adding-a-pattern.md。[wiring] 测试可确保检测器、目录条目和专家技能目录保持同步。

无需修改描述即可触发新模式。 上面的 description 有意保持宽泛（意图动词 + AEM 领域），因此已经能响应“检查 / 审核 / 修复我的 <AEM 相关内容>”；新模式通过其手动模式提示 + patterns.md 中的条目触发，而不是通过编辑 description 触发。只有当新模式引入了当前未覆盖的领域关键词（新的子系统或文件类型）时，才更新 description。[wiring] 测试可确保检测器、目录条目和专家技能目录保持同步。

相关技能

• migration — 执行基于 BPA/CAM/MCP 的旧版 AEM 迁移工作流。发现问题、对其分批处理、确保每个会话只处理一种模式，并将 (pattern, file) 对移交给此技能进行转换。请参阅上文“从 migration 技能调用”一节。