experience-lwc-widget-migrate

将 LWC 迁移为小组件

使用 LWC 还原用户的目标和数据契约，然后构建最接近且实用的小组件。小组件是独立的声明式制品。platform-widget-generate 负责创建它；可能还需要单独配置 Lightning Type 渲染器，才能使其可用。本技能负责对比、交接、集成检查和如实报告最终状态。

1. 决定是否继续

阅读并应用 experience-lwc-widget-assess，评估组件、其操作输出以及任何现有的 Lightning Type/渲染器。在报告中保留其判定结果和报告中的关键发现（阻碍因素、契约变更、丢失的交互）；不要创建评估工具自己的 verdict.json 或 report.md 文件。遇到 pointless、blocked、review 或 needsHumanReview: true 时停止。只有当预期变更明确时，才在 viable 情况下继续：

• 对于 port-declarative，保留当前显示的字段和操作。
• 对于 needs-IA-contract-change，明确指出所需的确切、有界输出字段或预先整理好的值。基于拟议契约的小组件只是草稿，直到操作返回该契约；不能称其为可用。
• 对于 not-portable 且存在可行的适配方案时，描述替代 UX 和每项丢失的交互。应称其为重建，而非忠实移植。

2. 推导生成器交接内容

追踪拟议小组件显示的每个值，确认其来自实际或拟议的操作输出。创建小组件前，应核实操作契约，而不能只依赖评估提示中的描述。向 platform-widget-generate 传递有序字段结构（name、type、required）、嵌套/列表项字段、每个可见元素的预期磁贴角色，以及受支持的终端操作。保留渲染顺序和字段路径。使用其发现结果获取磁贴定义和属性，使用其文档化的公式目录编写表达式，并遵循其关于架构类型和包布局的说明；不要在此维护第二份目录。公式可处理受支持的标量/日期/正则表达式操作，而集合重组可能需要预先整理好的输出。

如果 LWC 夹具或操作示例包含样例数据，可用来推断数据结构；样例数据是可选的，且不是文档化的生成器输入，也不能替代操作契约。不要臆造样例字段。对于 sendMessage 之类的操作，应核实所需上下文确实传递给 Agent，并且 Agent 有办法执行请求的工作。不要假设输入表单小组件可以通过某种已发现且经过验证的机制提交收集到的值。

3. 生成并连接

加载 platform-widget-generate，并执行其强制要求的实时 discoverUiComponents 和 getUiComponentSchemas 调用。如果 metadata-experts MCP 或发现功能不可用，请在编写 bundle 前停止；报告已完成的评估和拟议的字段结构。生成器负责其三个 widget 文件及自验证。不要将其 UEM 语法或验证清单复制到此技能中。

对于 Agentforce renderer 迁移，还必须确定接收 action 输出的 Lightning Type。仅有 bundle 并未连接到 action：

• 存在兼容的 Lightning Type： 检查其 schema 和当前的 renderer.json。生成完成后，读取 platform-custom-lightning-type-generate/references/widget-rendition.md，使用字段映射连接 widget，并遵循 platform-lightning-type-widget-coordinate 的 renderer 检查。如果现有 renderer 指向其他 widget 或 LWC，请在更改前说明替换/合并决策。
• 不存在兼容的 Lightning Type： 从项目或用户请求中确定 action 的输出类和 Lightning Type 名称。对于协调器支持的 Apex-backed 路径，使用 platform-lightning-type-widget-coordinate，并提供该类型和已评估的输出结构；由其负责生成 bundle 并连接 renderer。该协调器并不支持所有类型。如果无法确定输出/类型路径，请停止并指出缺少的集成步骤。不要声称迁移已完成。

如果用户只要求生成 bundle，请明确说明这是一个未连接的 bundle。否则，只有完成 bundle 和 renderer 连接才算完成。

4. 检查结果

使用生成器的 bundle 自验证功能。然后将结果与已评估的候选项进行比较：每个保留的可见字段都绑定到真实/拟议的 payload；列表项路径和支持的操作相符；已说明省略的行为和契约变更；对于 renderer 迁移，Lightning Type 指向此 widget，且属性匹配。静态检查只能确认结构和映射，不能证明已部署的运行时行为。报告评估结果、创建的路径、验证结果，以及以下状态之一：migrated and wired、bundle only、draft pending IA contract 或 stopped，并说明原因。