Back to Details

code-assessment

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AEM as a Cloud Service — Code Assessment

AEM as a Cloud Service — 代码评估

Single skill for detecting and fixing AEM CS code-quality issues, entirely against the local workspace — no external services or network calls. Findings reach the runbook from one of two sources; everything downstream is identical.
用于检测和修复AEM CS代码质量问题的独立工具，完全基于本地工作区运行——无需外部服务或网络调用。检测结果来自两个来源之一；后续处理流程完全一致。

Findings sources

检测结果来源

SourceWhenTarget versions (deps)
User-namedthe user names files or coordinatesuser-supplied
Discoverthe user asks to scan, or names no filesuser-supplied (per the pattern's resolution contract)
Discovery runs through the deterministic analyzer (
scripts/analyze.sh
): it parses the workspace once and runs the enabled detectors, emitting the shared findings shape. Every 
ready
pattern has an analyzer detector. One detector — 
remove-deprecated-api
— loads its rules dynamically from a preflight-produced cache (
remove-deprecated-api/scripts/detect.sh
 runs the AEM Analyser Maven Plugin and writes the cache TSV before the analyzer is invoked); the detector's shape and integration are otherwise identical. Patterns without a detector are 
planned
only — not yet detectable and not yet built; there is no LLM-scan fallback in this version (see Scope & limitations) — the 
scan
value on 
planned
rows in 
references/patterns.md
 marks the intended future detection method, not an active code path.
来源触发场景目标版本（依赖）
用户指定用户明确指定文件或坐标用户提供的内容
自动发现用户要求扫描仓库，或未指定任何文件用户提供的内容（遵循模式解析规则）
自动发现通过确定性的analyzer（
scripts/analyze.sh
）执行： 它会解析一次工作区并运行已启用的detector，输出统一格式的检测结果。 每个
ready
状态的模式都对应一个analyzer detector。其中一个detector——
remove-deprecated-api
——会从预生成的缓存中动态加载规则（在调用analyzer之前，
remove-deprecated-api/scripts/detect.sh
会运行AEM Analyser Maven Plugin并将缓存写入TSV文件）；除此之外，该detector的格式和集成方式与其他detector完全一致。没有对应detector的模式仅处于
planned
状态——暂无法检测和实现；当前版本没有LLM扫描 fallback（参见范围与限制）——
references/patterns.md
中
planned
行的
scan
值标记的是未来计划的检测方式，而非当前可用的代码路径。

Routing

路由规则

  1. User named files / coordinates → run the runbook in 
    with_findings
    mode against those paths.
  2. "Scan my repo" / no files named → run the runbook in 
    discover
    mode (per-pattern Discovery, workspace roots only).
Then follow the runbook: 
references/runbook.md
.
  1. 用户指定文件/坐标 → 针对指定路径以
    with_findings
    模式运行流程手册。
  2. “扫描我的仓库”/未指定文件 → 以
    discover
    模式运行流程手册（按模式自动发现，仅针对工作区根目录）。
随后遵循流程手册：
references/runbook.md
。

Manual Pattern Hints (classification → expert skill)

手动模式提示（分类→专业工具）

Route the request to one expert skill. Two pattern families share this skill:
Mechanical fixes (analyzer-driven detection, deterministic edits — follow the runbook flow):
User said / sawExpert skill
"update aem sdk", "upgrade mockito", stale 
<version>
or 
${property}
in pom
outdated-dependencies/
"fix @Inject", "modernize Sling Models", 
javax.inject.Inject
on 
@Model
fields
inject-in-sling-model/
"add HTTP timeouts", "outbound/external call has no timeout", 
HttpClient
/ 
HttpClients
/ 
OkHttpClient
built without a timeout
outbound-call-timeouts/
"bound my query", "unbounded query", "query causing OOM", 
p.limit=-1
, 
setLimit(-1)
unbounded-query/
"remove deprecated API", "fix deprecated imports", "Cloud Manager deprecated API failure", 
region-deprecated-api
/ 
api-regions-check
/ 
Import-Package not satisfied
pipeline failures, log4j migration, commons-lang/collections upgrades, deprecated Maven deps, unmodifiable OSGi configs
remove-deprecated-api/
 (analyzer detector with dynamic rules — preflight runs 
aemanalyser-maven-plugin
; hint-driven fixes; see recipe.md)
Architectural migration patterns (guided remediation — full before/after, troubleshooting, modern alternatives; invoked directly or via 
migration
for BPA/CAM-driven discovery):
User said / sawExpert skillBPA pattern ID
org.apache.sling.commons.scheduler.Scheduler
or 
scheduler.schedule(
with 
Runnable
scheduler/
scheduler
implements ResourceChangeListener
, lightweight listener + 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
on non-resource topics (replication, workflow, custom)
event-migration/
eventListener
/ 
eventHandler
com.day.cq.dam.api.AssetManager
create/upload/delete APIs, 
createAssetForBinary
, 
removeAssetForBinary
asset-manager/
assetApi
HTL build warning 
data-sly-test: redundant constant value comparison
references/data-sly-test-redundant-constant.md
htlLint
(reference, no expert skill subdirectory)
Broad / correctness-review asks ("check my Sling Models are implemented correctly", "review my code", "is my AEM project healthy", "assess this project") are not a single pattern: run the runbook in 
discover
mode with intent 
report
— the analyzer runs every detector and the report covers all built patterns, explicitly noting aspects not yet supported. Only narrow to one pattern when the user targets a specific fix.
If nothing matches, say the issue is not yet supported and offer to file a request for a new expert skill.
Full catalog (built + 
planned
patterns, with severity / detection / fix): 
references/patterns.md
.
将请求路由至对应的专业工具。两类模式共用本工具：
机械修复（基于analyzer的检测，确定性修改——遵循流程手册流程）：
用户需求/场景专业工具
"更新aem sdk"、"升级mockito"、pom文件中过时的
<version>
或
${property}
outdated-dependencies/
"修复@Inject"、"现代化Sling Models"、
@Model
字段上的
javax.inject.Inject
inject-in-sling-model/
"添加HTTP超时"、"外部调用无超时设置"、未配置超时的
HttpClient
/
HttpClients
/
OkHttpClient
outbound-call-timeouts/
"限制查询范围"、"无界查询"、"查询导致内存溢出"、
p.limit=-1
、
setLimit(-1)
unbounded-query/
"移除废弃API"、"修复废弃导入"、"Cloud Manager废弃API检查失败"、
region-deprecated-api
/
api-regions-check
/
Import-Package not satisfied
流水线失败、log4j迁移、commons-lang/collections升级、废弃Maven依赖、不可修改的OSGi配置
remove-deprecated-api/
（带有动态规则的analyzer detector——预执行阶段运行
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.*
、“发布/预览激活”
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项目是否健康”“评估这个项目”）不属于单一模式：以
report
意图运行
discover
模式的流程手册——analyzer会运行所有detector，报告涵盖所有已实现的模式，并明确指出暂不支持的内容。仅当用户针对特定修复需求时，才聚焦到单一模式。
如果没有匹配的模式，请告知用户当前暂不支持该问题，并提供提交新专业工具需求的选项。
完整目录（已实现+
planned
模式，包含严重性/检测/修复方式）：
references/patterns.md
。

Invocation from the 
migration
skill

从
migration
工具调用

migration
performs BPA/CAM/MCP discovery and handles batching + one-pattern-per-session workflow. After it has identified 
(pattern, file)
pairs from BPA findings, it hands off here for the actual transformation. When invoked with 
(pattern, file)
from 
migration
:
  • Skip HA/analyzer discovery (caller already identified the pattern + file)
  • Open the pattern's expert skill directly (per the Manual Pattern Hints table above)
  • Apply the steps in the expert skill against the named file(s)
  • Return the result; 
    migration
    continues with the next finding in its batch
The pattern guides themselves are agnostic about who invoked them — they apply identically whether reached from 
migration
(BPA/CAM) or from the runbook in this skill (HA / analyzer).
migration
工具执行BPA/CAM/MCP发现流程，处理批量任务并遵循“单会话单模式”工作流。它从BPA检测结果中识别出
(pattern, file)
对后，会将任务移交至本工具进行实际转换。当从
migration
工具传入
(pattern, file)
时：
  • 跳过HA/analyzer发现流程（调用方已识别出模式+文件）
  • 直接打开对应模式的专业工具（参照上述手动模式提示表格）
  • 针对指定文件执行专业工具中的步骤
  • 返回结果；
    migration
    工具继续处理批量任务中的下一个检测结果
模式指南本身与调用方无关——无论是从
migration
工具（BPA/CAM）还是本工具的流程手册（HA/analyzer）进入，其应用方式完全一致。

Runbook

流程手册

All detection, planning, edits, verification, git/in-place handling, and the run log live in 
references/runbook.md
. The runbook is the sole owner of repo-environment detection (
edit_mode
, git snapshot) — this control plane does not duplicate it.
所有检测、规划、修改、验证、git/本地处理以及运行日志均存储于 
references/runbook.md
。流程手册是唯一负责仓库环境检测（
edit_mode
、git快照）的组件——本控制平面不会重复实现该功能。

One pattern per session

单会话单模式

Report may span every pattern found; apply touches one pattern per session (atomic revert, single-story diff). Refuse "fix everything" for the apply phase. Rationale: 
references/shared-principles.md
.
报告可涵盖所有检测到的模式；修改阶段单会话仅处理一个模式（原子回滚、单一变更差异）。在修改阶段拒绝“修复所有问题”的请求。理由参见： 
references/shared-principles.md
。

Critical rules

核心规则

  • Local only — no network calls or external services; operate solely on the workspace. Documented exception: 
    remove-deprecated-api
    is plugin-driven and needs Maven Central (to resolve 
    aemanalyser-maven-plugin
    and, transitively, the AEM SDK's api-regions data) plus optionally Adobe Experience League as a fallback source for successor guidance. If offline, that one pattern is skipped with a clear message; all other patterns remain local-only.
  • Requires a local JDK (Java 11+) for detection — the analyzer compiles/runs in memory; no install beyond the JDK, no network. If absent, detection stops with a clear message.
  • The analyzer is detection — never substitute external tooling. Do not run 
    mvn versions:display-dependency-updates
    / 
    mvn versions:display-property-updates
    , 
    npm outdated
    , or Maven Central / registry lookups in place of analyzer discovery. Those answer "what is the latest on the network" — outside this skill's local-only contract. If the user explicitly wants a live registry comparison, say it needs network and offer it as a separate step after delivering the skill report. 
    remove-deprecated-api
    's preflight (
    remove-deprecated-api/scripts/detect.sh
    ) is the one documented exception: it invokes the AEM Analyser Maven Plugin against the project to populate its rules cache, then hands off to the shared analyzer.
  • Never commit, push, or open a PR — branch (git) or in-place edits only; the developer reviews and commits.
  • Surgical edits — no reformatting / re-serialization.
  • Skip with a reason — record un-applicable findings as 
    skipped
    with an exact reason; never silently drop.
  • One pattern per session for apply.
Full rationale: 
references/shared-principles.md
.
  • 仅本地运行——无网络调用或外部服务；仅操作本地工作区。 已记录的例外情况：
    remove-deprecated-api
    基于插件驱动，需要访问Maven Central（用于解析
    aemanalyser-maven-plugin
    以及间接获取AEM SDK的api-regions数据），还可选择Adobe Experience League作为后继方案指导的备用源。如果处于离线状态，该模式会被跳过并显示明确提示；所有其他模式仍保持仅本地运行。
  • 需要本地JDK（Java 11+）用于检测——analyzer在内存中编译/运行；除JDK外无需其他安装，无需网络。如果未安装JDK，检测会停止并显示明确提示。
  • analyzer是唯一检测方式——绝不替代外部工具。请勿运行
    mvn versions:display-dependency-updates
    /
    mvn versions:display-property-updates
    、
    npm outdated
    或访问Maven Central/注册表来替代analyzer发现流程。这些工具回答的是“网络上的最新版本是什么”——超出了本工具“仅本地运行”的约定。如果用户明确需要实时注册表对比，请告知需要网络连接，并在完成本工具报告后提供单独的步骤。
    remove-deprecated-api
    的预执行阶段（
    remove-deprecated-api/scripts/detect.sh
    ）是唯一已记录的例外：它会针对项目调用AEM Analyser Maven Plugin以填充规则缓存，随后移交至共享analyzer。
  • 绝不提交、推送或创建PR——仅支持分支（git）或本地修改；由开发者审查并提交。
  • 精准修改——不进行重新格式化/重新序列化。
  • 跳过需说明原因——将不适用的检测结果标记为
    skipped
    并记录确切原因；绝不静默忽略。
  • 修改阶段单会话单模式。
完整理由参见：
references/shared-principles.md
。

Scope & limitations

范围与限制

Local static detection and remediation only — no external services, no network, no live AEM instance. Issues that require runtime or live-repository state, telemetry, or history across runs are out of scope for this skill. Detection requires a local JDK (Java 11+); there is no remote or LLM-scan fallback in this version. A large apply (e.g. an 
@Inject
migration across 100+ files) is processed in resumable batches: the run checkpoints each file to 
.autofix/last-run.json
and pauses at a per-pass cap, so it survives context limits — reply apply 
<pattern>
 to continue (see 
references/git-workflow.md
).
仅支持本地静态检测与修复——无外部服务、无网络、无实时AEM实例。需要运行时或实时仓库状态、遥测数据或跨运行历史的问题不在本工具的范围内。 检测需要本地JDK（Java 11+）；当前版本无远程或LLM扫描 fallback。 大规模修改（例如在100+文件中迁移
@Inject
）会以可恢复批次处理：运行时会将每个文件的检查点保存至
.autofix/last-run.json
，并在每次处理达到上限时暂停，以避免超出上下文限制——回复**apply 
<pattern>
**即可继续（参见
references/git-workflow.md
）。

Adding a new pattern

添加新模式

Full end-to-end procedure — detector → fixtures/tests → catalog + routing → expert skill → verify: 
references/adding-a-pattern.md
. The 
[wiring]
test keeps the detector, catalog row, and expert-skill directory in sync.
Triggering scales without touching the description. The 
description
above is intentionally broad (intent verbs + AEM domain), so it already fires on "check / review / fix my <AEM thing>"; a new pattern is reached by its Manual Pattern Hints + 
patterns.md
rows, not by editing the description. Update the description only if the new pattern introduces a domain keyword it does not already cover (a new subsystem or file type). The 
[wiring]
test keeps the detector, catalog row, and expert-skill directory in sync.
完整的端到端流程——detector→测试用例→目录+路由→专业工具→验证： 
references/adding-a-pattern.md
。
[wiring]
测试用于确保detector、目录行和专业工具目录保持同步。
触发逻辑无需修改描述即可扩展。上述
description
故意设计得较为宽泛（意图动词+AEM领域），因此已能响应“检查/审查/修复我的<AEM组件>”这类请求；新模式通过手动模式提示+
patterns.md
行触发，无需修改描述。仅当新模式引入了描述中未涵盖的领域关键词（新子系统或文件类型）时，才需要更新描述。
[wiring]
测试用于确保detector、目录行和专业工具目录保持同步。

Related skills

相关工具

  • migration
     — drives BPA/CAM/MCP-based legacy-AEM migration workflow. Discovers findings, batches them, enforces one-pattern-per-session, and hands off 
    (pattern, file)
    pairs to this skill for transformation. See the "Invocation from the 
    migration
    skill" section above.
  • migration
    ——驱动基于BPA/CAM/MCP的旧版AEM迁移工作流。发现检测结果、批量处理、强制执行单会话单模式，并将
    (pattern, file)
    对移交至本工具进行转换。参见上述“从
    migration
    工具调用”部分。