在 AEM Cloud Service/6.5…

当用户要求创建、搭建、生成 AEM 组件，扩展现有 Core/项目组件，或把 Figma 设计转成 AEM 组件时，按配置、规格确认、文件生成与依赖校验流程执行。

适用场景

解决思路

1. 首先读取项目根目录（与 pom.xml 同级）的 `.aem-skills-config.yaml`，这是第一次工具调用。
2. 检查该文件是否存在且 `configured: true`。
3. 若文件缺失或 `configured: false`：停止，显示指定错误信息，不探索代码库、不继续，等待用户配置。
4. 若 `configured: true`：从 YAML 读取 `project`、`package`、`group` 值，然后继续创建组件。
5. 未配置时显示错误：`Project configuration required!`，要求用户在 `.aem-skills-config.yaml` 中更新 `project`、`package`、`group`、`configured: true`，之后重新请求创建组件。
6. 未配置时不要读任何其他仓库文件。
7. 未配置时不要列目录“理解项目”。
8. 未配置时不要检查现有组件找模式。
9. 未配置时不要查看 `pom.xml`、Java 文件或目录结构。
10. 未配置时不要从任何来源推断项目值；`.aem-skills-config.yaml` 是项目值的唯一真实来源。
11. 遵守 No Hallucination Rule：只创建用户明确指定的字段；不要添加额外字段；不要重命名字段，因为会破坏内容契约。加载 `references/no-hallucination-rules.md`。
12. 按工作流概览执行：Step 0 配置校验；Step 1 提取并校验组件名；Step 1.5 组件扩展决策（若扩展）；Step 2 收集需求并确认 dialog 规格；Step 2.3 获取 Figma 设计（若有 URL）；Step 3 创建所有组件文件；Step 3.11 依赖校验（servlet 必需）；Step 4 完成总结。
13. Step 0.1：从项目根读取 `.aem-skills-config.yaml`。
14. Step 0.1：检查 `configured: true`。
15. Step 0.1：读取 `project`、`package`、`group` 值。
16. Step 0.2：只使用配置文件，不从文件系统、现有组件、Java 文件、`pom.xml` 或先前知识推断项目值。
17. Step 0.3：读取 `references/aem-conventions.md` 以加载文件结构模板、命名约定和模式。
18. Step 0.4：配置校验后做项目状态分析：在 `/apps/[project]/components/` 检查组件名唯一性。
19. Step 0.4：在 `core/src/main/java/[package-path]/models/` 检查 Model 类冲突。
20. Step 0.4：查看 1-2 个最近组件，分析现有模式作为风格参考。
21. Step 1：从用户消息解析组件名；若未提供则询问。
22. Step 1：将组件名规范化为小写 kebab-case，例如 `My Component` -> `my-component`。
23. Step 1：校验组件名：以字母开头，仅包含字母/数字/连字符，不允许连续连字符。
24. Step 1.5：当用户说“extend {component}”时，先检查项目组件 `/apps/{project}/components/{component}`；若找到，将其用作 `sling:resourceSuperType`。
25. Step 1.5：若项目组件未找到，检查 Core Components 映射：image -> `core/wcm/components/image/v3/image`。
26. Step 1.5：teaser, card -> `core/wcm/components/teaser/v2/teaser`。
27. Step 1.5：text, richtext -> `core/wcm/components/text/v2/text`。
28. Step 1.5：title, heading -> `core/wcm/components/title/v3/title`。
29. Step 1.5：list -> `core/wcm/components/list/v4/list`。
30. Step 1.5：button, cta -> `core/wcm/components/button/v2/button`。
31. Step 1.5：navigation, nav -> `core/wcm/components/navigation/v2/navigation`。
32. Step 1.5：container, section -> `core/wcm/components/container/v1/container`。
33. Step 1.5：accordion -> `core/wcm/components/accordion/v1/accordion`。
34. Step 1.5：tabs -> `core/wcm/components/tabs/v1/tabs`。
35. Step 1.5：carousel -> `core/wcm/components/carousel/v1/carousel`。
36. Step 1.5：embed, video -> `core/wcm/components/embed/v2/embed`。
37. Step 1.5：若 Core Components 也未找到，向用户请求澄清。
38. Step 1.5：扩展模式加载 `references/extending-core-components.md`。
39. Step 1.6：当扩展涉及 hide、remove、add custom field、override 时，必须加载 `references/extending-core-components.md`，这些操作需要 Sling Resource Merger 模式。
40. Step 1.6：添加自定义字段时，创建新 tab 或加到现有 tab。
41. Step 1.6：隐藏 tab 时使用 `sling:hideResource="{Boolean}true"`。
42. Step 1.6：隐藏字段时使用 `sling:hideResource="{Boolean}true"`。
43. Step 1.6：覆盖字段时使用 `sling:hideProperties` 加新值。
44. Step 1.6：扩展 Core Components 时，使用 `@Self @Via(type = ResourceSuperType.class)` 进行模型委托。
45. Step 1.6：扩展 Core Components 时，实现 `ComponentExporter` 接口。
46. Step 1.6：扩展 Core Components 时，在 `@Model` 注解添加 `resourceType`。
47. Step 1.6：扩展 Core Components 时，在 dialog 中对继承的 tab/字段使用 `sling:hideResource`。
48. Step 1.6：若父组件是项目组件而非 Core Component，使用直接 Java 类继承 `extends ParentModel`，不要用委托模式；`@Self @Via(type = ResourceSuperType.class)` 仅用于 Core Components。
49. Step 2.1：在创建前逐字回显理解到的 dialog 规格，模板包含将创建的 N 个字段表格：编号、字段标签、字段类型、属性名，并声明不会添加额外字段，询问是否正确。
50. Step 2.2：若同时提供 mockup 和 spec，dialog 规格优先；mockup 仅用于 HTML/CSS。
51. Step 2.2：若只提供 mockup，提出字段建议并询问确认。
52. Step 2.3：若用户提供 Figma URL（`figma.com/design/...`、`figma.com/make/...`、`figma.com/board/...`），加载 `references/figma-design-rules.md`。
53. Step 2.3：解析 URL 提取 `fileKey` 和 `nodeId`；将 `node-id` 查询参数中的 `-` 转为 `:`；分支 URL 使用 `branchKey` 作为 `fileKey`。
54. Step 2.3：通过 `plugin-figma-figma` MCP server 调用 `get_design_context`，参数包含 `nodeId`、`fileKey`、`clientLanguages: html,css,javascript`、`clientFrameworks: htl`。
55. Step 2.3：从响应提取设计 token：颜色、字体、尺寸、间距、布局。
56. Step 2.3：Figma 输出用于 HTL 结构、CSS 样式、JS 行为，不用于 dialog 字段。
57. Step 2.3：同时有 dialog 规格和 Figma URL 时，dialog 规格绝对优先决定 dialog 字段；Figma 仅决定 HTML 结构、CSS、JS 行为。
58. Step 2.3：只有 Figma URL 时，分析设计并向用户提议 dialog 字段，继续前询问确认。
59. Step 2.3：Figma 响应是 React+Tailwind，只作为参考，不作为生产代码。
60. Step 2.3：将 JSX 转为带 BEM 类的语义化 HTL。
61. Step 2.3：将所有 CSS 值提取到组件 clientlib。
62. Step 2.3：仅在交互被暗示时创建 JS。
63. Step 2.3：不要硬编码 Figma 临时图片 URL，它们会过期并在生产中断。
64. Step 2.4：外部 API 集成需要 Servlet，GET。
65. Step 2.4：动态数据加载需要 Servlet，GET。
66. Step 2.4：表单提交需要 Servlet，POST。
67. Step 2.4：搜索/过滤需要 Servlet，GET。
68. Step 2.4：静态 dialog 内容不需要 Servlet。
69. Step 3：按顺序创建所有文件。
70. Step 3.1：创建组件定义 `ui.apps/src/main/content/jcr_root/apps/[project]/components/{component-name}/.content.xml`，加载 `references/aem-conventions.md`。
71. Step 3.2：创建组件 dialog `ui.apps/.../components/{component-name}/_cq_dialog/.content.xml`，加载 `references/dialog-patterns.md`。
72. Step 3.2：扩展组件时加载 `references/extending-core-components.md`；必须有 Sling Resource Merger，因为 dialog 继承只通过 merger 生效，否则父 dialog 节点无法解析。
73. Step 3.2.1：用户指定 image/photo 字段时，默认通过 `data-sly-resource` 嵌入 Core Image component；不要创建 fileupload dialog 字段并手动 `<img>` 渲染。
74. Step 3.2.1：fileupload 仅用于非图片文件（PDF、文档等）；仅当用户明确要求非图片文件上传时使用 `cq/gui/components/authoring/dialog/fileupload`。
75. Step 3.2.1：加载 `references/htl-patterns.md` 的 Image Handling 部分获取正确嵌入模式。
76. Step 3.3：创建 HTL 模板 `ui.apps/.../components/{component-name}/{component-name}.html`，加载 `references/htl-patterns.md`。
77. Step 3.3：若有 Figma URL，也加载 `references/figma-design-rules.md` Rules 5、8：将 JSX 结构转为带 BEM 类的语义化 HTL；用 Sling Model 表达式替换静态文本；用 Figma 截图作为元素层级视觉真相。
78. Step 3.3：i18n 检查：若组件有静态显示文本（标签、按钮文本、占位字符串），使用 HTL i18n 表达式 `${'Label Text' @ i18n}`；不要在 Sling Model 处理静态文本翻译，留在 HTL 以自动翻译。
79. Step 3.4：创建 Sling Model `core/src/main/java/[package-path]/models/{ComponentName}Model.java`，加载 `references/model-patterns.md` 和 `references/java-standards.md`。
80. Step 3.4：扩展时加载 `references/extending-core-components.md`。
81. Step 3.4：Core Component 扩展使用委托模式：`@Model(adaptables = SlingHttpServletRequest.class, adapters = {CustomModel.class, ComponentExporter.class}, resourceType = CustomModel.RESOURCE_TYPE)` 和 `@Exporter(name = ExporterConstants.SLING_MODEL_EXPORTER_NAME, extensions = ExporterConstants.SLING_MODEL_EXTENSION)`，类实现 `ComponentExporter`，字段用 `@Self @Via(type = ResourceSuperType.class)`，核心接口用 FQN 避免导入冲突。
82. Step 3.5：若有多字段（multifield），创建子项 Model `core/src/main/java/[package-path]/models/{ItemName}.java`。
83. Step 3.6：创建单元测试 `core/src/test/java/[package-path]/models/{ComponentName}ModelTest.java`，加载 `references/test-patterns.md`。
84. Step 3.7：为每个组件创建 clientlib `ui.apps/.../clientlibs/clientlib-{component-name}/`，加载 `references/clientlib-patterns.md`。
85. Step 3.7：若有 Figma URL，也加载 `references/figma-design-rules.md` Rules 6、7：从 Figma 响应提取精确颜色、字体、尺寸、间距、border-radius；所有 CSS 放入 `css/{component-name}.css` 并使用 BEM 命名；仅当设计暗示交互时创建 `js/{component-name}.js`；对照 Figma 截图验证像素级还原。
86. Step 3.8：若有条件逻辑，创建 dialog clientlib `ui.apps/.../clientlibs/clientlib-{component-name}-dialog/`，加载 `references/clientlib-patterns.md` 的 Dialog JavaScript Pattern 部分。
87. Step 3.9：若有动态内容，创建 Sling Servlet `core/src/main/java/[package-path]/servlets/{ComponentName}Servlet.java`，加载 `references/sling-servlet-standards.md`。
88. Step 3.10：创建 Servlet 单元测试 `core/src/test/java/[package-path]/servlets/{ComponentName}ServletTest.java`。
89. Step 3.11：Servlet 完成前必须校验依赖：在 `core/pom.xml` 中校验。
90. Step 3.11：不要硬编码版本；检查父 `pom.xml` 的版本属性，因为硬编码会漂移并导致构建冲突。
91. Step 3.11：大多数常用 API 已包含在 `aem-sdk-api`（GSON、Jackson、Commons）。
92. Step 3.11：AEM 运行时库使用 `provided` scope。
93. Step 4：输出完成总结，包含组件创建成功、创建的文件列表、与规格完全匹配的 dialog 字段表，并询问是否添加字段或构建项目。
94. 快速参考字段类型映射：Textfield -> `granite/ui/components/coral/foundation/form/textfield`。
95. Textarea -> `granite/ui/components/coral/foundation/form/textarea`。
96. Richtext, RTE -> `cq/gui/components/authoring/dialog/richtext`。
97. Pathfield, Path -> `granite/ui/components/coral/foundation/form/pathfield`。
98. Image, Photo -> 嵌入 Core Image component（见 `references/htl-patterns.md` Image Handling）；不要用 fileupload 进行图片渲染。
99. Fileupload, File Upload -> `cq/gui/components/authoring/dialog/fileupload`（用于非图片文件：PDF、文档）。
100. Multifield -> `granite/ui/components/coral/foundation/form/multifield`。
101. Checkbox -> `granite/ui/components/coral/foundation/form/checkbox`。
102. Select, Dropdown -> `granite/ui/components/coral/foundation/form/select`。
103. Numberfield -> `granite/ui/components/coral/foundation/form/numberfield`。
104. Datepicker -> `granite/ui/components/coral/foundation/form/datepicker`。
105. 完整映射查看 `assets/field-type-mappings.md`。
106. 按需加载参考文件：任何组件先加载项目根 `.aem-skills-config.yaml`，再加载 `references/aem-conventions.md`。
107. Dialog XML 加载 `references/dialog-patterns.md`。
108. HTL 模板加载 `references/htl-patterns.md`。
109. Sling Model 加载 `references/model-patterns.md`、`references/java-standards.md`。
110. 单元测试加载 `references/test-patterns.md`。
111. Clientlibs 加载 `references/clientlib-patterns.md`。
112. 扩展 Core Component 加载 `references/extending-core-components.md`。
113. 需要扩展 Core Component 完整示例、单元测试模式或实现清单时，加载 `references/extending-core-components-example.md`。
114. Sling Servlet 加载 `references/sling-servlet-standards.md`。
115. Core Component patterns 加载 `references/core-components.md`。
116. No Hallucination rules 加载 `references/no-hallucination-rules.md`。
117. Figma 设计集成加载 `references/figma-design-rules.md`。
118. 故障排查加载 `references/troubleshooting.md`。
119. 示例加载 `references/examples.md`。
120. 组件创建期间或之后遇到问题，查阅 `references/troubleshooting.md`。

适用边界 · 注意事项

• 不适用于非 AEM as a Cloud Service 或 AEM 6.5 项目，或缺少 Maven core、ui.apps 模块结构。
• 需要 Figma 设计集成时，若未启用 `plugin-figma-figma` MCP server，不应使用 Figma URL 流程。
• 若项目根 `.aem-skills-config.yaml` 缺失或 `configured: false`，不要创建组件或探索代码库，先让用户配置。