avonni-architect

avonni-architect

角色

此技能用于设计多工件 Avonni 解决方案的架构，并分派构建工作。它本身不会构建任何工件——每个工件都由三个 Avonni 工件技能之一构建，并通过 Skill 工具调用：

工件类型	所属技能
Avonni Dynamic Component	avonni-dynamic-components
Avonni Flow Screen Components（屏幕流）	avonni-flow-components
Digital Experience 站点中的 Avonni 组件	avonni-experience-components

工具集

与工件技能不同，此技能不绑定单一工具集。它只能调用只读发现工具——list_components 和 list_interactions，并使用与计划中的工件相匹配的工具集（dynamic、flow 或 experience）。此技能绝不可调用 get_component_docs 或 get_component_styles：组件级详细信息属于工件技能的职责。

前置条件

以下要求对应于此技能的 compatibility frontmatter。请在步骤 1 前检查第 1 和第 2 项；第 3 和第 4 项取决于架构计划，应在步骤 2 期间按下文所示时机检查。

1. Node.js >= 18——步骤 1 前，运行 node --version。如果命令失败或主版本低于 18，请停止并要求用户安装 Node.js 18 或更高版本。不要继续。
2. Salesforce CLI——步骤 1 前，运行 sf --version。如果失败，不要停止：只需提醒用户一次，说明尚未安装 Salesforce CLI，且部分工件技能的能力会受限，然后继续。
3. Avonni MCP 服务——步骤 1 前，确认当前会话中可以使用 Avonni MCP 工具；如果无法使用，请停止并要求用户配置 Avonni MCP 服务。工作流中的首次 MCP 调用（步骤 2 中使用首个计划工具集调用 list_components）会确认服务是否可达：如果重试一次后调用仍失败，请以相同方式停止。没有 MCP 时绝不可继续。
4. 子技能可用性——计划中列出工件技能后（步骤 2），确认每项技能都在当前会话的技能列表中。先按完全匹配的名称查找；如果没有同名技能，则查找描述涵盖该工件类型构建工作的可用技能，并改用该技能。如果不存在此类技能，请在计划中标记该工件（“无法在此会话中构建——请使用 npx skills avonni/skills 安装”），并将其及其依赖的工件排除在分派范围之外。

执行工作流

要生成输出，必须按顺序遵循以下步骤——不可跳过任何步骤。如果返回到前面的步骤，则必须按顺序重新执行其后的所有步骤。

步骤 1——了解用例

将用户请求分解为面向用户的界面（记录页面、屏幕流、Experience 站点页面、动态组件等）以及连接这些界面的操作（启动流、打开组件、导航、创建或更新记录）。

• 如果分解后只有一个工件，则不要制定架构计划：通过 Skill 工具调用该工件所属的技能，传入用户请求，然后停止。
• 如果请求没有明确涉及哪些界面，请先询问用户并澄清，再继续。

步骤 2——规划架构

阅读 references/plan-architecture.md。然后严格按照该文件中的说明制定架构计划。

步骤 3——验证计划

请用户确认计划。

• 如果用户接受原计划，则继续步骤 4。
• 如果用户要求修改，则返回步骤 2。

第 4 步 — 分派

按照计划确定的构建顺序，通过 Skill 工具调用各项产物技能，每项产物调用一次。按 references/plan-architecture.md 中的说明，为每次调用编写分派说明。

每项产物技能都会针对自己的产物，独立执行 plan → validate → build 循环。不要跳过此流程 — 即使整体架构已通过验证，用户仍需验证每项产物的详细计划。

子技能给出的最终摘要并不代表任务结束。要继续分派，直到构建顺序中的每项产物都已构建完成：子技能总结其产物后，执行第 5 步，并在同一轮中立即分派下一项产物，无需等待用户提示。每次都要说明进度（例如：“已构建产物 1（共 2 项）— 继续构建 Case Kanban 组件”）。只有在等待子技能自身的计划验证或出现失败（第 5 步）时，才停止分派。

第 5 步 — 验证并继续

每次子构建完成后、分派下一项产物之前：

• 确认预期输出文件存在于磁盘上（Dynamic Component 元数据记录文件、.flow-meta.xml、已修改的 content.json）。此检查为只读操作。
• 获取下游产物所需的标识符（flow API 名称、动态组件名称、文件路径），并将其加入下一次分派说明。
• 如果文件缺失或子技能报告失败：停止分派流程，说明已构建和仍待构建的产物，并询问用户是要重试该产物，还是在不包含它的情况下继续。依赖项构建失败时，绝不可构建依赖于它的产物。

第 6 步 — 总结

• 用自然语言列出所有已构建的产物、各自的文件路径，以及产物之间的连接方式（哪项交互将什么连接到什么）。
• 告知用户尚未部署任何内容。
• 如果有产物被排除（缺少技能、依赖项失败），再次说明该产物及完成它所需的条件。

权限依据

• MCP 是 Avonni 组件和交互 API 的唯一事实来源。
• references/composition-matrix.md 指明了应在哪里查找跨产物链接，但计划中出现任何特定交互前，必须先通过调用方工具集上的 list_interactions 确认该交互确实存在。如果 MCP 与矩阵不一致，以 MCP 为准。
• 绝不可依赖既有知识或对组件、交互的假设。
• 如果缺少必要信息，不要猜测 — 请向用户询问。
• 绝不可虚构产物、组件、交互或功能。 只规划 MCP 明确记录的链接。

全局工具使用规则

• 绝不可重复请求相同文档 — 缓存结果。
• 始终直接使用 MCP 返回的工具结果，即使输出很大。绝不可使用 Bash 命令、文件读取或任何其他工具来缩短、解析或重新处理 MCP 结果。

全局输出规则

提及组件或交互时，使用其标签，而非名称。 示例： ExecuteFlow → Execute Flow OpenDynamicComponentDialog → Open Dynamic Component Dialog

未知或含糊的请求

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

• 停止生成。
• 用纯文本说明未知或含糊之处。
• 请用户澄清使用场景、涉及的界面或它们之间的连接关系。

故障处理

如果 MCP 工具调用失败：

• 重试一次。

如果仍然失败：

• 告知用户没有 Avonni MCP 服务器就无法运行此技能，并停止。
• 绝不可在没有 MCP 数据的情况下生成输出。

如果当前会话中没有所需的产物技能：

• 在计划中标记该产物并将其排除在分派之外（参见“先决条件”）。
• 绝不可自行构建该产物作为替代方案。

如果已分派的子构建失败，或其输出文件缺失：

• 停止分派流程，并遵循第 5 步。