platform-custom-lightning-type-generate

何时使用此技能

在需要以下操作时使用此技能：

• 为结构化输入/输出创建自定义 Lightning 类型（CLT）
• 为 Lightning Platform 生成基于 JSON Schema 的类型定义
• 为 Einstein Agent 操作配置 CLT
• 为自定义 UI 设置编辑器和渲染器配置
• 排查与自定义 Lightning 类型相关的部署错误

规范

CustomLightningType 元数据规范

概述与用途

自定义 Lightning 类型（CLT）是基于 JSON Schema 的类型定义，供 Lightning Platform（包括 Einstein Agent 操作）用于描述结构化输入/输出并驱动编辑器/渲染器体验。

配置

• 为嵌套对象选择引用 CLT 模式——需要可复用或单独部署的嵌套类型时，为该结构创建一个 CLT，并使用 "lightning:type": "c__<CLTName>" 引用它。该字符串是被引用类型的 lightning:type 值 / FQN / 已注册标识符，而不是 JSON Schema title。
• 结构简单且可通过属性和受支持的原始类型 lightning:type 标识符表示时，选择标准 Lightning 类型。
• 结构已存在于服务器端，且希望由 Apex 类定义其形状时，选择 Apex 类类型（@apexClassType/...）。
• 仅在需要自定义 UI 行为（自定义 LWC 输入/输出组件）时包含编辑器/渲染器配置。否则省略。

关键规则（请先阅读）

• 关键：绝不要在 schema.json 中包含 "$schema" 字段
  • 即使它是有效的 JSON Schema $schema 声明，Salesforce CLT 验证器也会拒绝包含此字段的架构。
• 根对象架构必须包含：
  • "type": "object"
  • "title"
  • "lightning:type": "lightning__objectType"
  • "unevaluatedProperties": false
• CLT 元架构会强制将 "unevaluatedProperties" 设为 false。不要将其设为 true。
• 当 "unevaluatedProperties": false 时，根对象架构不得包含 "examples"。
• properties 内的嵌套对象不得设置 "lightning:type": "lightning__objectType"。
  • 嵌套对象可以是使用 c__<CLTName> 语法引用其他 CLT。
• CLT 元架构对列表/数组属性有严格限制：
  • 关键限制：CLT 元架构可能会完全拒绝 items 关键字。默认将 items 视为不允许使用。
  • 根级数组（根 properties 的直接子项）：
    • 必须包含 "lightning:type": "lightning__listType"
    • 不得包含 "items"
    • "type": "array" 可选
  • 嵌套数组（嵌套对象内的数组）是最常见的失败原因：
    • 必须包含 "type": "array"
    • 不得包含 "lightning:type": "lightning__listType"
    • 不得包含 "items"
• 设置 "unevaluatedProperties": false 后，任何未知关键字都会导致验证失败。优先删除关键字，而不是放宽严格限制。
• Apex 类 CLT 必须保持精简：
  • 仅包含 title、description（可选）以及设置为 @apexClassType/... 的 lightning:type。
  • 不要添加 type、properties、required 或 unevaluatedProperties。
  • Apex 类 CLT 上的自定义 LWC 渲染器/编辑器不得在根覆盖项中使用 attributes——即使提示词另有要求，也必须遵守此规则。 由于架构没有 properties 块，{!$attrs.<name>} 无从解析，unevaluatedProperties: false 会拒绝任何属性键（例如 "You can't add the flightId property ... because the unevaluatedProperties keyword value is set to false"）。请使用 "componentOverrides": { "$": { "definition": "c/<yourComponent>" } }，完全不要包含 attributes 键。如果用户的提示词明确要求在 Apex 类 CLT 渲染器/编辑器上为特定字段配置属性映射（例如“为 fieldA、fieldB 配置属性映射”），不要照字面执行——仍需从根覆盖项中省略 attributes，并在回复中说明原因（例如：“注意：由于底层类型是 Apex 类 CLT，没有可供绑定的 properties 块，因此已省略属性映射。”）。
• 不得使用会触发 Vibes 安全 Shell 过滤器的 Shell 元字符。 使用此技能发出的任何 Bash 工具调用中，不要使用命令替换（$(…) 或反引号）、进程替换（<(…)、>(…)）、大括号展开（{a,b,c} 或 {1..N}）或 eval / exec。即使在 Bypass 模式下，Vibes 也会强制要求手动批准这些模式，导致评估停滞。请分别发出命令（mkdir -p a && mkdir -p b），或使用各自独立的命令打印每个值，并根据输出进行判断，而不要将值捕获到 Shell 变量中。

CLT 元架构的其他验证规则

• 组织命名空间验证：可能会验证标题、说明和其他字符串字段，确保你没有在不允许使用组织命名空间的位置使用它。
• Lightning 类型验证：验证 CLT，以防止引用内部命名空间（例如，在不允许的情况下使用 sfdc_cms 等内部命名空间中的类型）。
• 对象类型验证：验证 CLT 根对象，确保 lightning:type 的值严格为 lightning__objectType。

基本类型与约束

如需查看受支持的基本 lightning:type 标识符、其约束以及允许使用的属性级关键字的完整列表，请阅读此技能目录中的 assets/primitive-types-and-constraints.md。

生成工作流

1. 确认 CLT 方案
   • 如果引用 Apex：记录准确的类引用（@apexClassType/namespace__ClassName$InnerClass）。
   • 如果使用标准基元：列出字段、对应的 Lightning 基元类型，以及必填字段。
2. 起草 schema.json
   • 顶部不要包含 "$schema"
   • 从根对象结构（必需的根字段）开始。
   • 使用有效的基元 lightning:type 标识符添加 properties。
   • 对于嵌套对象属性，使用 CLT 引用模式：
     • 使用 "lightning:type": "c__<CLTName>" 引用另一个 CLT
     • 必须先将被引用的 CLT 部署到组织，再部署父 CLT。
   • 对于基于 Apex 的嵌套对象：如果结构存在于服务端，则使用 @apexClassType/...。
   • 如果提示词明确要求输出真正的嵌套对象，优先使用基于 Apex 的 CLT（@apexClassType/...），以确保嵌套结构可安全部署。
   • 对于数组：遵循严格的列表规则（避免使用 items；避免在嵌套数组上使用 lightning:type）。
   • 部署前，确认 lightning:type 的拼写完全正确（例如，使用 lightning__richTextType，不要使用拼写错误的变体）。
3. （可选）起草 editor.json（仅在需要自定义 UI 时）
   • **支持的结构：**顶层 editor 对象，包含 editor.componentOverrides 和 editor.layout。
     • 顶层 editor 对象。
     • 使用 editor.componentOverrides 配置组件覆盖。
     • 使用 editor.layout 配置布局。
     • 已弃用：不要使用 propertyRenderers 或 view——这些是旧版键。始终使用 componentOverrides 和 layout。
   • 根级覆盖模式（最常用于完全自定义的编辑 UI）：
     • editor.componentOverrides["$"] = { "definition": "c/<yourEditorComponent>", "attributes": { ... } }
     • 将架构数据传递到自定义 LWC 时，使用 {!$attrs.<name>} 语法进行属性映射：例如，"attributes": { "myField": "{!$attrs.value}" }，以便运行时将架构值绑定到组件属性。
     • 重要：{!$attrs.<name>} 中的 <name> 必须是类型架构中定义的属性。例如，如果架构中有一个名为 temperature 的属性，应使用 {!$attrs.temperature}；除非 value 是实际属性，否则不要使用 {!$attrs.value}。
   • 属性级覆盖模式（针对单个字段）：
     • editor.componentOverrides["<propertyName>"] = { "definition": "es_property_editors/<...>" }
     • 有效的编辑器组件（示例）：es_property_editors/inputText、es_property_editors/inputNumber、es_property_editors/inputRichText、es_property_editors/inputImage、es_property_editors/inputTextarea。不要使用 es_property_editors/inputList。
   • 集合编辑器（针对根级 lightning__listType 属性）：使用集合级覆盖，让自定义组件编辑列表：collection.editor.componentOverrides["$"] = { "definition": "c/<yourCollectionEditorComponent>" }。或者，使用带有 attributes.property = "<listPropertyName>" 的 editor.layout 和 lightning/propertyLayout 进行默认列表编辑。
   • 布局模式：
     • editor.layout.definition = "lightning/verticalLayout"
     • editor.layout.children[*].definition = "lightning/propertyLayout"，并设置 attributes.property = "<propertyName>"
     • 重要：lightning/propertyLayout 仅接受 property 属性。不要添加 label、title 或任何其他属性，否则验证会因 additionalProperties: false 而失败。
   • 避免已知无效的模式：
     • 不要使用 es_property_editors/inputList。
     • 不要使用 itemSchema 属性。
4. （可选）起草 renderer.json（仅在需要自定义 UI 或小组件呈现时）
   • **支持的结构：**顶层 renderer 对象，包含 renderer.componentOverrides 和 renderer.layout。
     • 顶层 renderer 对象。
     • 使用 renderer.componentOverrides 配置组件覆盖。
     • 使用 renderer.layout 配置布局。
     • 已弃用：不要使用 propertyRenderers 或 view——这些是旧版键。始终使用 componentOverrides 和 layout。
   • 小组件呈现模式（将现有 WidgetBundle 引用为根渲染器）：renderer 文件是一个精简封装，通过开发者名称指向小组件（"definition": "@widget/c/<widgetDeveloperName>"），并通过 {!$attrs.<schemaPropertyName>} 将 CLT 架构属性映射到小组件属性。不要在 renderer.json 中重复小组件主体。完整的结构、绑定规则和限制请参阅 references/widget-rendition.md。如需完整的 Apex → Lightning Type → Widget 流程，请改用 platform-lightning-type-widget-coordinate 编排器，而不是此技能。
   • 根级覆盖模式（最常用于使用自定义 LWC 的完全自定义呈现 UI）：
     • renderer.componentOverrides["$"] = { "definition": "c/<yourRendererComponent>", "attributes": { ... } }
     • 将架构数据绑定到自定义渲染器组件属性时，在属性映射中使用 {!$attrs.<name>}。
     • 重要：{!$attrs.propertyName} 之类的属性映射必须引用类型架构中实际存在的属性。引用不存在的属性会导致验证失败。
     • 类型匹配：属性值必须与组件所需的类型相符。例如，如果组件需要字符串属性，传入整数会导致验证失败。
   • 属性级覆盖模式：
     • renderer.componentOverrides["<propertyName>"] = { "definition": "es_property_editors/outputText" | "es_property_editors/outputNumber" | "es_property_editors/outputImage" | ... }。有效的渲染器组件（示例）：es_property_editors/outputText、es_property_editors/outputNumber、es_property_editors/outputImage。避免在渲染器中使用输入样式的组件。
   • 渲染器布局模式：
     • renderer.layout.definition = "lightning/verticalLayout"
     • renderer.layout.children[*].definition = "lightning/propertyLayout"，并设置 attributes.property = "<propertyName>"
     • 重要：与编辑器布局相同，lightning/propertyLayout 仅接受 property 属性。不要添加 label、title 或任何其他属性。
   • 集合渲染器（针对根级 lightning__listType 属性）：使用 collection.renderer.componentOverrides["$"] = { "definition": "c/<yourListRendererComponent>" } 或 es_property_editors/genericListTypeRenderer 来呈现列表。
5. 将文件放入正确的捆绑包结构
   • lightningTypes/<TypeName>/schema.json
   • （可选）lightningTypes/<TypeName>/lightningDesktopGenAi/editor.json
   • （可选）lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json 对于 Gen AI / Copilot，标准路径为 lightningDesktopGenAi/。其他目标（例如 Experience Builder、Mobile Copilot、Enhanced Web Chat）在支持时使用不同的子文件夹：experienceBuilder/、lightningMobileGenAi/、enhancedWebChat/。
   • （可选——仅用于小组件呈现）lightningTypes/<TypeName>/renderer.json
6. 配置自定义 LWC 组件（如果使用自定义组件）
   • 重要：在 editor/renderer 配置中引用的自定义 LWC 组件，其 -meta.xml 文件中必须具有正确的目标配置：
     • 对于编辑器组件（在 editor.json 中使用的 c/<componentName>）：LWC 的 -meta.xml 文件必须包含 <target>lightning__AgentforceInput</target>
     • 对于渲染器组件（在 renderer.json 中使用的 c/<componentName>）：LWC 的 -meta.xml 文件必须包含 <target>lightning__AgentforceOutput</target>
   • 如果缺少正确的目标，部署将失败，并显示：Invalid target configuration. To use 'c/componentName' as a renderer/editor, your js-meta.xml file must include valid target 'lightning__AgentforceOutput/Input'.
   • 渲染器组件的 -meta.xml 示例：

     <?xml version="1.0" encoding="UTF-8"?>
     <LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
         <apiVersion>60.0</apiVersion>
         <isExposed>true</isExposed>
         <targets>
             <target>lightning__AgentforceOutput</target>
         </targets>
     </LightningComponentBundle>
     

常见部署错误

错误 / 症状	可能原因	修复方法
由于存在未知关键字而导致架构验证失败	unevaluatedProperties: false 与不允许的关键字（通常是 examples、items）同时使用	移除导致问题的关键字；保持架构精简
嵌套对象验证失败	组织 / 渠道验证拒绝 LightningTypeBundle 中的嵌套对象类型	使用 CLT 引用（c__<CLTName>）或 Apex 类类型
CLT 引用无效	组织中不存在被引用的 CLT，或语法不正确	先部署被引用的 CLT；c__<CLTName> 必须与被引用类型的 lightning:type 值 / FQN / 已注册标识符匹配，而不是与 title 匹配
lightning:type 无效或拼写错误（例如，lightning__richtextType 而非 lightning__richTextType）	生成的类型名称不正确	对照受支持的类型名称检查所有 lightning:type 值，并在部署前更正
数组属性遭拒	验证器拒绝使用 items（或在嵌套数组中使用 lightning:type）	对于嵌套数组：仅保留 type: "array"。对于根数组：使用最精简的结构；如果 items 遭拒，则将其移除
基于 Apex 的 CLT 遭拒	添加了额外字段（例如，type、properties）	仅使用 title、可选的 description 和 lightning:type
编辑器配置遭拒	使用了无效模式（es_property_editors/inputList、itemSchema）或无法识别的顶层键	使用 editor.componentOverrides 和 editor.layout；保持配置精简
布局属性上的 additionalProperties 错误	向 lightning/propertyLayout 添加了 label 或其他属性	在 lightning/propertyLayout 中仅使用 property 属性。移除 label、title 或任何其他属性
自定义 LWC 的目标配置无效	自定义 LWC 组件的 -meta.xml 缺少必需目标（lightning__AgentforceInput 或 lightning__AgentforceOutput）	在 LWC 的 -meta.xml 中添加正确的目标：编辑器使用 lightning__AgentforceInput，渲染器使用 lightning__AgentforceOutput
类型架构中不存在属性映射	使用了 {!$attrs.propertyName}，但 propertyName 未在架构中定义	确保所有属性映射都引用类型架构 properties 部分中实际存在的属性
Apex 类 CLT 的自定义 LWC 渲染器出现 unevaluatedProperties 错误	在 Apex 类 CLT 上使用了根覆盖 attributes 映射，但该 CLT 没有可供验证的 properties 块	从根覆盖中完全移除 attributes；仅使用 "componentOverrides": { "$": { "definition": "c/<component>" } }
使用已弃用的键时出现 additionalProperties 错误	在编辑器 / 渲染器配置中使用了 propertyRenderers 或 view	将已弃用的 propertyRenderers 替换为 componentOverrides，并将 view 替换为 layout
组件属性中的类型不匹配	传入的组件属性类型不正确（例如，用整数代替字符串）	确保属性值与组件定义的预期类型一致

验证清单

• 根架构具有 type: "object"、title、lightning:type: "lightning__objectType" 和 unevaluatedProperties: false
• 启用严格验证时，根架构不包含 examples
• 没有嵌套对象包含 lightning:type: "lightning__objectType"
• 数组定义应尽可能精简（尤其是嵌套数组）
• 叶属性仅使用受支持的基本类型 lightning:type 标识符
• Apex 类 CLT 仅包含 title/description 和 lightning:type: "@apexClassType/..."
• Bundle 结构和文件名符合 Lightning Types 要求
• 编辑器配置仅使用允许的模式（不使用 es_property_editors/inputList 或 itemSchema）；使用有效组件（例如 es_property_editors/inputText、es_property_editors/inputNumber）或自定义 c/ 组件
• 在适用情况下，渲染器配置使用输出样式组件（例如 es_property_editors/outputText、es_property_editors/outputNumber），而非输入编辑器
• 布局配置使用 lightning/propertyLayout，且仅包含 property 属性（不含 label、title 或其他属性）
• 所有属性映射（{!$attrs.propertyName}）都引用类型架构中存在的属性
• 自定义 LWC 组件在 -meta.xml 中具有正确的 targets：编辑器使用 lightning__AgentforceInput，渲染器使用 lightning__AgentforceOutput
• 根架构不包含 "$schema" 字段