SuperAPI AI 工具集

experience-lwc-widget-migrate

智能体与模型

查看项目

更新于 10-17 08:11

技能介绍

用途

该技能面向这样一个迁移任务:把某个已有的 Lightning Web Component(LWC)转换为声明式 HXL / Agentforce 小组件(widget),覆盖从评估、生成到接线的完整过程。技能的核心做法是先从 LWC 中恢复用户的使用目标和数据契约,再构建最接近原有用途的可用小组件。小组件本身是独立的声明式产物,由 platform-widget-generate 生成;若要让其可达,可能还需要单独接线 Lightning Type 渲染器。本技能负责对比、交接、集成检查,并给出诚实的最终状态。

主要流程

1. 决定是否继续

读取并对组件、其 action 输出以及现有 Lightning Type/renderer 应用 experience-lwc-widget-assess,保留其结论和报告中的关键发现(阻断项、契约变更、丢失的交互),但不自行写出该评估的 verdict.json 或 report.md。遇到 pointless、blocked、review 或 needsHumanReview: true 时停止;只有在结论为 viable 且预期变更明确时继续:

  • port-declarative:保留当前可见字段和动作。
  • needs-IA-contract-change:明确所需的有界输出字段或预塑形值;在 action 返回该契约之前,对应的 widget 只能算草稿,不能称为可用。
  • not-portable 但有可行适配:描述替代 UX 与每一项丢失的交互,并称为重建而非忠实移植。

2. 推导生成器交接内容

将拟议小组件展示的每个值追溯到实际或拟议的 action 输出。在生成前应验证 action 契约,而不是只依赖评估提示中的描述。向 platform-widget-generate 传入有序字段形状(名称、类型、必填)、嵌套/列表项字段、每个可见元素预期的磁贴角色以及支持的终端动作,并保持渲染顺序与字段路径。磁贴定义与属性、公式目录、schema 类型与包布局均以该生成器自身的发现结果和文档为准,本技能不另维护目录。公式可覆盖支持的标量/日期/正则运算,集合重构则可能需要预塑形输出。LWC 夹具或 action 示例中的样本数据可用于推断形状,但样本数据是可选的,不是生成器的文档化输入,也不能替代 action 契约,且不得臆造样本字段。对于 sendMessage 之类的动作,要验证所需上下文能到达 agent,且 agent 有办法执行所请求的工作;不要假设小组件输入表单能在没有经发现和验证的机制下提交收集到的值。

3. 生成并连接

加载 platform-widget-generate,并遵循其强制的实时 discoverUiComponents 与 getUiComponentSchemas 调用。如果 metadata-experts MCP 或发现能力不可用,应在编写组件包前停止,报告已完成的评估和建议的字段形状。生成器负责其三个小组件文件及自校验;本技能不复制其 UEM 语法或校验清单。

对于 Agentforce 渲染器迁移,还需要建立接收 action 输出的 Lightning Type——仅有组件包并未连接到 action:

  • 已有兼容 Lightning Type:检查其 schema 与当前 renderer.json。生成后阅读 platform-custom-lightning-type-generate/references/widget-rendition.md,用字段映射接线小组件,并遵循 platform-lightning-type-widget-coordinate 的渲染器检查。若现有渲染器指向另一个小组件或 LWC,在更改前先呈报替换/合并决策。
  • 无兼容 Lightning Type:从项目或用户请求中确定 action 的输出类和 Lightning Type 名称。对于协调器支持的 Apex 支持路线,使用 platform-lightning-type-widget-coordinate 和该类型及已评估的输出形状,由它负责组件包生成与渲染器接线。该协调器并不覆盖所有类型;若无法建立输出/类型路线,应停止并指出缺失的集成步骤,不得声称迁移完成。

若用户只要求组件包,应明确报告为未连接的组件包;否则完成迁移需要组件包与渲染器接线两者兼备。

4. 检查结果

先使用生成器的组件包自校验,再将结果与已评估的候选对象比较:每个保留的可见字段都绑定到真实/拟议的 payload;列表项路径与支持的动作一致;已说明被省略的行为与契约变更;若为渲染器迁移,Lightning Type 指向该小组件且属性匹配。静态检查只能确立结构与映射,不代表部署后的运行时行为。最终报告应包含评估、创建的路径、校验结果,以及以下状态之一:已迁移并接线、仅组件包、因 IA 契约待定的草稿、已停止(附原因)。

适用场景

适用于将现有 LWC 迁移为声明式 HXL / Agentforce 小组件,尤其是需要保留可见字段与动作、需要明确数据契约变更、或需要建立 Lightning Type 渲染器接线的场景。

限制

评估阶段未通过(pointless、blocked、review、needsHumanReview)时不得继续;发现能力或所需 MCP 不可用时须在生成前停止;仅有组件包时不得称为已完成迁移;静态校验不能证明部署后的运行时行为;收费、价格、部署平台等信息暂未提供。