avonni-flow-components

avonni-flow-components

工具集

此技能仅适用于 Avonni MCP 的 flow 工具集。所有 MCP 工具调用（如适用）都必须包含 toolset: "flow"。请勿将此技能用于标准 Avonni LWC 组件、Avonni Experience Sites 组件或 Avonni Dynamic Components。

范围

此技能仅适用于 Flow 中 Avonni 屏幕组件的字段 — 即 extensionName 以 avcmpbuilder: 开头的 <fields> 元素。它涵盖如何发现、配置、验证这些字段，并将其写入 .flow-meta.xml 文件。

此技能不涵盖一般 Flow 逻辑。如果请求还需要决策、赋值、循环、记录操作或其他 Flow 元素，请使用此技能构建 Avonni 屏幕字段，并在此技能之外处理 Flow 的其余部分。更新现有 Flow 时，绝不要重构、重新格式化或改写所要求修改的 Avonni 组件字段以外的任何内容。

如果请求还需要构建用于启动或托管此 Flow 的产物（Dynamic Component、Experience Site 页面），请停止并告知用户重新使用 avonni-architect 技能。如果没有名为 avonni-architect 的技能，请转至任何旨在协调多产物 Avonni 解决方案的技能；如果不存在此类技能，请建议使用 npx skills avonni/skills 安装该技能。

前置条件

在步骤 0 之前检查以下事项。这些检查用于确保满足此技能 compatibility frontmatter 中列出的要求。如果本次会话中已执行过某项检查（例如，派发任务前由 avonni-architect 技能执行），请勿重复检查 — 直接复用其结果：

1. Node.js >= 18 — 运行 node --version。如果命令失败或主版本低于 18，请停止并要求用户安装 Node.js 18 或更高版本。请勿继续。
2. Avonni MCP 服务 — 工作流中的首次 MCP 调用（list_components，并指定 toolset: "flow"）同时用于检查服务是否可访问。如果会话中无法使用 Avonni MCP 工具，或重试一次后调用仍然失败，请停止并要求用户配置带有 flow 工具集的 Avonni MCP 服务。没有 MCP 时绝不可继续。
3. Salesforce CLI — 运行 sf --version。如果运行失败，请勿停止：只需提醒用户一次，说明尚未安装 Salesforce CLI，因此无法检索对象和字段文档，然后继续。如果后续步骤需要该 CLI，则在执行到相关步骤时停止，并提供安装说明（参见 references/get-object-documentation.md）。

执行工作流

创建输出时，必须遵循以下步骤。始终按顺序执行，不得跳过步骤。如果返回到之前的步骤，必须按顺序重新执行该步骤之后的所有步骤。

步骤 0 — 判断意图

判断用户是想要：

• 创建包含 Avonni 组件的新 Flow → 遵循创建路径。
• 更新现有 Flow（添加、修改或移除 Avonni 组件 — 包括向尚无 Avonni 组件的 Flow 添加首个 Avonni 组件）→ 遵循更新路径。要求用户提供 .flow-meta.xml 文件的路径；如果无法找到，请询问用户。

如果请求含义不明确，请先询问用户以澄清，再继续。

---

创建路径

1. 阅读 references/plan-screen-components.md。然后严格按照该文件中的说明制定组件构建计划。
2. 请用户确认计划。
   • 如果用户接受计划原样执行，则继续第 3 步。
   • 如果用户要求修改，则返回第 1 步。
3. 创建流程框架：
   • 如果会话中有其他用途为创建 Salesforce 流程的技能或工具（而非此技能），则使用它创建一个至少包含一个屏幕的屏幕流，并获取项目中生成的 .flow-meta.xml 文件路径。如果它在组织中创建了流程，但未生成本地文件，则先将其检索到本地（例如，运行 sf project retrieve start --metadata Flow:<ApiName>），再继续。
   • 否则，或者委托创建失败，或者无法获取本地屏幕流文件，则运行 node <skill_base_directory>/scripts/create-flow.mjs 来搭建流程文件框架（用法请参阅 --help）。切勿手动编写流程框架。
4. 阅读 references/build-screen-field.md。然后严格按照该文件中的说明生成计划中的组件字段，并将其插入目标屏幕。
5. 运行 node <skill_base_directory>/scripts/fix-flow.mjs <path-to-flow-file> 生成自动填充的值（例如 systemContext），然后运行 node <skill_base_directory>/scripts/validate-flow.mjs <path-to-flow-file>。
   • 如果验证报告错误，则修复错误并再次运行这两个脚本。重复此过程，直到验证通过。
6. 向用户总结任务结果：
   • 告知用户流程文件已创建及其位置。
   • 告知用户该流程尚未部署。
   • 总结组件及其功能。

---

更新路径

1. 阅读 references/read-flow.md，并按照其中的说明解析现有流程，然后向用户展示当前的 Avonni 组件。
2. 请用户描述他们希望进行的更改，除非他们已经描述过。
3. 阅读 references/plan-screen-components.md。然后严格按照该文件中的说明制定组件构建计划，并纳入用户要求的更改。
4. 请用户确认计划。
   • 如果用户接受计划原样执行，则继续第 5 步。
   • 如果用户要求修改，则返回第 3 步。
5. 阅读 references/build-screen-field.md。然后严格按照该文件中的说明应用计划中的更改。
   • 仅编辑计划指定的 <fields> 块；在 references/build-screen-field.md 中定义的位置插入新块。流程的其他部分一律保持不变，包括格式和元素顺序。
6. 运行 node <skill_base_directory>/scripts/fix-flow.mjs <path-to-flow-file> 生成自动填充的值（例如 systemContext），然后运行 node <skill_base_directory>/scripts/validate-flow.mjs <path-to-flow-file>。
   • 如果验证报告所修改字段存在错误，则修复错误并再次运行这两个脚本。重复此过程，直到这些字段不再有错误。
   • 不要修复流程中未修改部分的错误，而应向用户报告。这类错误可以在循环结束后仍然存在。
7. 向用户总结任务结果：
   • 告知用户更新了哪个文件。
   • 告知用户该流程尚未部署。
   • 总结与上一版本相比的更改。

权限依据

• MCP 是 Avonni Flow Screen Components API 的唯一可信来源。
• 切勿依赖先前知识或对组件的假设。
• 如果 MCP 数据与先前知识冲突，则始终以 MCP 数据为准。
• 如果缺少必要信息，切勿猜测——请提出请求。
• **切勿虚构组件、属性、交互、数据源模式或样式钩子。**只能使用 MCP 明确记录的内容，以及此技能参考文档中定义的流程序列化参数。

全局工具使用规则

• 切勿重复请求同一份文档——缓存结果。
• 切勿依赖其他组件来推断某个组件的文档。
• 始终直接使用 MCP 返回的工具结果，即使输出很大。切勿使用 Bash 命令、文件读取或任何其他工具来缩短、解析或重新处理 MCP 结果。

全局输出规则

提及组件或交互时，使用其标签，而不是名称。 示例： datatable → Data Table avatarGroup → Avatar Group NavigationMixinNavigate → Navigate

提及属性或样式钩子时，将名称转换为自然语言标签。 示例： iconName → icon name itemsTypeSelected → data source type --avonni-alert-base-color-background → base background color

未知或含糊的请求

如果需要用户提供更多信息：

• 停止生成。
• 使用纯文本（而非 XML）说明哪些内容未知或含糊。
• 请用户澄清，或提供正确的组件或属性名称。

故障处理

如果 MCP 工具调用失败：

• 重试一次

如果仍然失败：

• 告知用户此技能需要 Avonni MCP 服务才能运行，然后停止
• 切勿在没有 MCP 数据的情况下生成输出

如果某个组件文档获取失败：

• 继续使用获取成功的文档
• 报告失败的组件

如果找不到某个组件：

• 告知用户该组件可能不存在或没有文档记录

如果通过其他技能或工具创建流程框架失败：

• 改用 scripts/create-flow.mjs 并继续
• 在最终摘要中说明使用了备用方案

如果运行时验证失败：

• 重新检查 MCP 文档，再判断组件是否存在问题