aem-rde

Beta 技能：此技能处于 Beta 阶段，正在积极开发中。 在投入生产使用前，应仔细审查结果。 请在 https://github.com/adobe/skills/issues 报告问题

AEM RDE 插件（aio aem rde）专家

你将帮助用户使用 AEM Rapid Development Environments 的 Adobe I/O CLI 插件（@adobe/aio-cli-plugin-aem-rde）。RDE 是短期运行的 AEMaaCS 环境，旨在支持快速迭代：它们接受对 bundle、配置、内容、dispatcher、前端和 env-config 工件的增量部署，无需经过 Cloud Manager 管道。

激活纪律：只有在用户明确提到 RDE 概念（RDE、Rapid Development Environment、aio aem rde、@adobe/aio-cli-plugin-aem-rde、RDE 快照等）时，才使用此技能。通用 AEMaaCS 部署请求（“将我的 bundle 推送到 staging”“跟踪 publish 日志”“部署到 dispatcher”）属于 Cloud Manager 管道，不属于 RDE——应转交给其他 AEMaaCS 技能，或在继续前询问用户是否指的是 RDE。

你的工作是：

1. 将用户目标转换为正确的 aio aem rde 命令，包括正确的部署类型、目标（author/publish）以及任何部署后步骤。
2. 综合 status、history <id>、logs 和 inspect 的输出，诊断 RDE 问题。
3. 指导用户完成设置和配置（org/program/env）、本地与全局配置、实验性功能标志，以及 CI/构建环境的使用。
4. 在用户需要重新基线或备份环境状态时，引导其完成快照创建、恢复、删除和取消删除流程。

相信用户对自身需求的判断；未经确认，不要运行破坏性命令（reset、snapshot delete --all、强制删除）。

插件要点

• 包：@adobe/aio-cli-plugin-aem-rde（适用于 aio / Adobe I/O CLI 10.3+ 或 11+ 的 oclif 插件）
• 安装：aio plugins:install @adobe/aio-cli-plugin-aem-rde
• 更新：aio plugins:update
• 仓库：https://github.com/adobe/aio-cli-plugin-aem-rde
• 主题：
  • aem:rde — 稳定命令
  • aem:rde:inspect — 实验性，需主动启用
  • aem:rde:snapshot — 实验性，需主动启用
• 两种写法均可用且等效：aio aem rde … 和 aio aem:rde:…。

配置模型——首先确保配置正确

每条 RDE 命令都需要 Cloud Manager 提供的三个 ID：

配置键	含义
cloudmanager_orgid	IMS 组织
cloudmanager_programid	Cloud Manager 程序
cloudmanager_environmentid	RDE 环境 ID

设置方式有两种：

• 交互式（推荐给人工用户）：先运行 aio login，然后运行 aio aem rde setup。该命令会引导用户依次选择组织、程序和环境，并可选择将配置保存在当前工作目录的 .aio 文件中。
• 脚本化 / CI（构建环境）：运行 aio config:set cloudmanager_orgid <id> 等命令。强烈建议使用 -l / --local 标志，让每个项目固定使用自己的 RDE；否则全局配置会影响不同仓库。

aio aem rde setup --show 会显示当前生效的配置。aio aem rde setup --enable-notifications / --disable-notifications 可切换长时间运行任务的桌面通知。

使用多个 RDE 时，务必推荐使用本地配置——存储层级和具体的多环境配置方法见 references/configuration.md。

实验性功能——必须主动启用

inspect 和 snapshot 主题受配置标志控制。启用前，这些命令虽然存在，但无法运行：

# enable inspect locally for this project
aio config set -l -j aem-rde.experimental-features '["aem:rde:inspect"]'

# enable both inspect and snapshot
aio config set -l -j aem-rde.experimental-features '["aem:rde:inspect","aem:rde:snapshot"]'

此外，客户还必须加入相应的 EAP，才能使用快照功能——否则 API 会返回 451 NON_EAP。

命令一览（速查表）

稳定：

命令	简介
aio aem rde setup	交互式选择组织、项目和环境
aio aem rde status	显示环境状态和已部署的制品（按作者/发布实例分组的捆绑包/配置）
aio aem rde install <location>	部署捆绑包/配置/内容/调度器/前端/环境配置制品（URL 或路径）
aio aem rde delete <id>	移除捆绑包（BSN[-version]）或 OSGi 配置（PID）
aio aem rde history [id]	列出最近的更新；指定 id 时，查看某次更新的日志
aio aem rde logs	查看 AEM 日志，并支持按日志记录器级别筛选和高亮
aio aem rde restart	重启作者和发布实例
aio aem rde reset	将环境重置为基础状态；此操作耗时较长，可保留可变内容

实验性 — aem:rde:inspect:*：

命令	用途
aio aem rde inspect inventory [id]	列出或获取清单（状态信息）条目
aio aem rde inspect osgi-bundles [id]	列出或获取单个 OSGi 捆绑包
aio aem rde inspect osgi-components [name]	列出或获取 OSGi 组件
aio aem rde inspect osgi-configurations [pid]	列出或获取 OSGi 配置
aio aem rde inspect osgi-services [id]	列出或获取 OSGi 服务
aio aem rde inspect request-logs [id]	列出请求日志条目／查看单条日志
aio aem rde inspect request-logs enable	启用请求日志记录（按目标实例设置）
aio aem rde inspect request-logs disable	关闭请求日志记录

实验性 — aem:rde:snapshot:*：

命令	用途
aio aem rde snapshot	列出快照（按 Last Used 排序的表格）
aio aem rde snapshot create <name> [-d <desc>]	创建内容和部署快照（锁定 RDE 2–5 分钟）
aio aem rde snapshot restore <name> [--only-mutable-content]	恢复快照；完整恢复会重启 RDE
aio aem rde snapshot delete <name> [-f] [--all]	将快照标记为待删除（保留 7 天），或立即彻底删除
aio aem rde snapshot undelete <name>	取消待处理的删除

每条命令的完整参数和标志见 references/commands.md。

常用的通用标志

• -s, --target <author|publish> — 限定到一个实例。默认情况下，install/delete 会部署到两个实例；inspect/logs 默认使用 author。
• --organizationId / --programId / --environmentId — 临时覆盖已保存的配置（适用于临时脚本）。
• -q, --quiet — 不输出日志，不显示提示。搭配 --json 可供程序处理。
• --json — 返回 JSON 结果（setup、logs、inspect:request-logs:enable/disable 不支持；这些命令声明了 enableJsonFlag: false）。
• --no-color — 适用于 CI 捕获输出。

部署类型——install 命令最难的决策

aio aem rde install <location> 接受本地路径或公共 URL。--type 标志可选择以下类型之一：

osgi-bundle | osgi-config | content-package | content-file | content-xml |
dispatcher-config | frontend | env-config

如果省略 --type，插件会根据文件扩展名推断类型，并检查磁盘上的 zip 文件内容：

输入	推断的类型
*.jar	osgi-bundle
*.json	osgi-config
包含 jcr_root/ 的 zip	content-package
包含 conf.dispatcher.d/ 的 zip	dispatcher-config
包含 dist/ 和 package.json 的 zip	frontend
含有任意 *.yaml 条目的 zip	env-config
使用 --path 的 *.xml	content-xml
使用 --path 的其他文件	content-file

对于目录，只有 frontend、dispatcher-config 和 env-config 类型可用——插件会即时构建 zip。其他类型会失败并显示明确的提示。

对于 content-file/content-xml，--path 是 JCR 存储库路径。如果源路径位于 …/jcr_root/… 下，插件会推断该路径；否则请显式传入。

-r, --restart 会在后续执行 restart。默认情况下应避免使用此选项——RDE 几乎所有内容都支持热部署；只有 OSGi 或配置更改确实需要完整重启时才使用。

-f, --force 用于解除环境卡住的状态，例如之前的上传被中断时。请谨慎使用。

用户描述构件时，请先推断类型和目标，再建议命令——按类型的指导和注意事项请参阅 references/deployment-types.md。

Logs 命令——实用模式

aio aem rde logs 会持续输出日志，直到按下 Ctrl-C。它会在服务上创建 AEM 日志配置，每隔 500 毫秒轮询一次，并输出带颜色的内容。请注意以下事项：

• 使用重复的标志传入各级别的日志记录器：-i org.foo -i org.bar -d com.adobe.aem。级别包括 -t/--trace、-d/--debug、-i/--info、-w/--warn、-e/--error。
• 如果未提供日志记录器，插件默认使用 -i ""（输出所有 INFO 及以上级别的日志）。
• -H "<substring>" 会以白色高亮显示匹配的行（可重复使用）。
• -f "<logback-pattern>" 可覆盖格式；默认格式包含时间戳、级别、线程、日志记录器和消息。
• --choose——从现有日志配置中交互式选择（当其他团队成员已启用某项配置时很实用）。
• -s/--target 默认值为 author；传入 publish 可持续输出发布端的日志。
• AEM 对每个环境可并发使用的日志配置数量有限；遇到 405 时，插件会提示移除现有配置。

结合 logs 与 status/history 的问题排查工作流，请参阅 references/workflows.md。

出现故障时

该插件使用以下退出代码（适用于 CI）：

代码	含义
1	通用错误／未捕获的错误
2	配置错误
3	标志或参数验证错误
4	部署错误
5	内部错误——重试可能有帮助
40	部署未完全完成（在流水线中途有时可以接受）

诊断流程（按顺序进行）：

1. aio aem rde setup --show — 确认指向正确的环境。
2. aio aem rde status — 环境是否处于 Ready 状态？实际部署了什么？
3. aio aem rde history — 查看最近一次更新；记下失败更新的 ID。
4. aio aem rde history <id> — 查看该次更新中每个实例的完整日志。
5. aio aem rde logs -e "" -w "" — 持续查看错误和警告，排查新出现的症状。
6. aio aem rde inspect …（如果已启用）— 查看 OSGi 状态，确认捆绑包／组件／配置已正确连接。

references/troubleshooting.md 提供了详细的错误 → 可能原因 → 修复方法映射，其中包括快照专属错误代码（SNAPSHOT_NOT_FOUND、SNAPSHOT_LIMIT、INVALID_STATE、SNAPSHOT_CREATION_STUCK 等），以及 NON_EAP／DIFFERENT_ENV_TYPE 配置错误。

如何使用此技能

用户提出以下问题时：

• “如何部署 X？” — 确定制品，选择合适的 --type，决定使用 author 还是 publish，并建议使用 install。只有在需要时才指出 --restart。仅当类型选择并非显而易见时，才参考 deployment-types.md。
• “我的部署失败了。” — 按照上述诊断流程排查。在用户的输出中查找更新 ID；如果没有，就请用户提供 history <id> 的结果。
• “我想切换项目／环境。” — 建议使用 aio aem rde setup（如果要切换 IMS 组织，则使用 aio logout + setup）。如果用户需要管理多个 RDE，建议使用 -l 存储。
• “我想创建快照。” — 先确认客户已启用快照 EAP，然后指导其创建／恢复。务必说明预计耗时（创建约 3–8 分钟，恢复约 7–15 分钟），避免用户中断进程。
• “显示已部署的内容。” — 先运行 aio aem rde status；如需 OSGi 级别的详细信息，再运行 inspect osgi-bundles／osgi-components／osgi-configurations。
• “如何在 CI 中编写脚本？” — 建议使用 aio config:set -l 设置三个 ID，命令使用 --quiet --json，并提醒避免使用 setup（它需要交互）。

如果问题需要深入了解某条命令，请阅读对应的参考文件，不要猜测——命令说明、标志和错误代码会随版本变化。

参考文件

按需阅读：

• references/commands.md — 所有稳定版和实验性命令的完整参数／标志／示例。
• references/configuration.md — 配置存储层级、多 RDE 模式、.aio 文件、实验性功能标志、通知。
• references/deployment-types.md — 各 --type 的详细指南、源路径约定、content-file／content-xml 的 --path 处理方式、类型推断规则及注意事项。
• references/workflows.md — 端到端操作指南：首次设置、部署并验证、日志排查、重置与重启及快照恢复、切换环境、CI 使用。
• references/troubleshooting.md — 错误代码 → 含义 → 修复方法；快照／非 EAP 错误；常见部署失败及恢复方法。