manage-global-configurations

管理全局配置

概述

通过交互式多轮工作流，在 Mule 4 项目中创建、查看、编辑、删除、列出、验证和整合所有全局配置。

你将构建： 在 global-configs.xml 中配置完整的全局元素、属性文件，以及经过验证的 pom.xml 依赖项——全部遵循 MuleSoft 最佳实践。

架构

flowchart TD
    Start{User Intent} -->|connector, config, connection| CC[Connector Config]
    Start -->|TLS, SSL, certificate| TLS[TLS Context]
    Start -->|object store, key-value| OS[Object Store]
    Start -->|caching, cache strategy| CS[Caching Strategy]
    Start -->|error handler, on-error| EH[Error Handler]
    Start -->|autodiscovery, API gateway| AD[API AutoDiscovery]
    Start -->|import project, shared library| IMP[Import]
    Start -->|properties, config.yaml, env| PROP[Properties]
    Start -->|global-property, inline| GP[Global Property]
    Start -->|list all, show all configs| LIST[List All]
    Start -->|find usages, where is used| FIND[Find Usages]
    Start -->|validate, dangling ref| VAL[Validate]
    Start -->|consolidate, centralize| CON[Consolidate]

    CC --> OP{Operation}
    TLS --> OP
    OS --> OP
    CS --> OP
    EH --> OP
    AD --> OP
    IMP --> OP
    PROP --> OP
    GP --> OP

    OP -->|Create| CREATE[Generate XML + config.yaml + pom.xml]
    OP -->|Get| GET[Scan & Display]
    OP -->|Edit| EDIT[Modify & Validate]
    OP -->|Delete| DELETE[Remove & Cleanup]

先决条件

开始之前，请确保你具备：

1. 工作区中的 Mule 4 项目，且具有标准结构（src/main/mule/、src/main/resources/、pom.xml）
2. 已安装 Anypoint CLI v4，并配有 DX Mule 插件（@mulesoft/anypoint-cli-dx-mule-plugin）
3. Java 11+ 和 Maven，以便验证构建
4. 可用的 Mule Runtime，用于运行 dx mule describe-connector 元数据命令

执行路径

• 创建连接器配置：步骤 1、2、3、4、5、6、7、8、9、10、11

  • 适用场景：用户要求添加新的连接器配置（Salesforce、HTTP、DB 等）
  • 需要：projectDir、connectorName

• 创建全局元素：步骤 1、2、12

  • 适用场景：用户要求添加 TLS Context、Object Store、Caching Strategy、Error Handler、AutoDiscovery 或 Import
  • 需要：projectDir、elementType

• 管理属性：步骤 1、2、13

  • 适用场景：用户要求创建或编辑属性文件、设置环境，或管理 global-property 元素
  • 需要：projectDir

• 管理操作：步骤 1、2、14

  • 适用场景：用户要求列出所有内容、查找用法、验证或整合全局元素
  • 需要：projectDir

步骤 1：规则和参考资料

规则：

• 多轮交互。 每个“STOP”标记处：仅以纯文本输出问题，然后结束回复并等待。在该阶段的所有问题都得到回答之前，不得使用工具。
• 预先提供的值提取（如已提供则跳过）。 在第一个 STOP 之前，解析用户的初始请求，并提取他们已提供的任何值（例如连接器名称、配置名称、提供方名称、字段值、占位符偏好）。将这些记录为“预先提供的值”。在每个后续 STOP 点，检查问题是否已由预先提供的值回答；如果是，则使用该值并完全跳过 STOP。只询问尚未提供的信息。如果用户说“默认占位符”或“所有字段都使用占位符”，则将其视为步骤 8 的答案，并跳过该 STOP。如果仍有歧义（例如，用户说“basic provider”，但元数据列出了“basic-connection”和“basic-auth”），仍需询问。
• 不得使用 MCP 服务工具。 所有 Exchange 搜索和连接器操作都必须仅使用 bash 脚本。绝不可调用 search_asset、get_asset 或任何基于 MCP 的工具。
• 绝不可在聊天中输出原始 XML——始终写入文件。
• 绝不可使用 TaskCreate。
• 仅根据元数据确定配置结构。 绝不可为连接器硬编码属性、子元素或提供方名称。describe-connector 元数据是唯一可信来源。
• 连接器版本仅从 Exchange 获取。 绝不可凭记忆填写版本。唯一可接受的来源是 get_latest_connector.sh → pick_connector.sh。
• 所有配置都放在 global-configs.xml 中。 排序和结构请参阅 references/global-config-conventions.md。
• pom.xml 依赖项为必需项。 每个需要依赖项的全局元素（连接器、Object Store、API AutoDiscovery、导入）都必须在 pom.xml 中添加相应依赖项。读取 pom.xml，在 <dependencies> 中添加 <dependency> 块，然后写回文件。如果不执行此步骤，构建将失败。绝不可跳过。

脚本：

此技能在其自身的 scripts/ 目录中包含 shell 脚本。使用 Bash 工具，通过“技能已激活”消息中提供的绝对路径调用这些脚本。不要使用相对路径。

脚本	用途
get_latest_connector.sh <search> [nickname]	在 Exchange 中搜索连接器候选项（每行一个 GAV）
pick_connector.sh <nickname> <gav>	将选定的 GAV 记录为草稿
describe_connector.sh <nickname>	运行 dx mule describe-connector，保存 JSON 并输出摘要
build_gav.sh <json>	将已保存的连接器 JSON 转换为 groupId:assetId:version

脚本路径：<skill-root>/scripts/（其中 <skill-root> 是包含此 SKILL.md 的目录）。

参考资料：

收到指示时，使用 Read 工具读取这些文件。使用“技能已激活”消息中提供的绝对路径。

文件	内容	何时读取
references/global-elements-catalog.md	所有元素类型的 XML 模板、命名空间 URI、XSD URL、pom.xml 依赖项、属性表、验证规则和连接器配置生成规则。	生成任何 XML 之前——核实结构、必需属性、命名空间和依赖项。
references/global-config-conventions.md	元素排序、命名空间管理、集中化规则、默认项目结构、整合决策矩阵。	在 global-configs.xml 中放置元素、管理命名空间或执行整合时。
references/properties-patterns.md	属性文件格式、${placeholder} 解析、多环境模式、安全属性、内置属性、命名惯例和验证规则。	创建或编辑属性文件、设置环境或验证占位符时。

步骤 2：解析目标项目并路由操作

解析目标项目：

每个会话只运行一次——在本次对话的所有后续操作中复用结果。

如果工作区中存在多个 Mule 项目，通过 AskUserQuestion 询问用户要使用哪个项目，并停止。不要将此问题与任何其他问题合并。如果只有一个项目，则直接使用，不要询问。

操作路由 — 第 1 级（领域）：

关键词	领域
connector, config, connection, Salesforce, HTTP, DB, database, Slack, S3, ServiceNow, Jira, NetSuite, oauth, credentials	→ 连接器配置
TLS, SSL, trust store, key store, certificate, mTLS	→ TLS 上下文
object store, key-value store, persistent store, os:config	→ 对象存储
caching, cache strategy, cache scope	→ 缓存策略
error handler, global error, default error handler, on-error	→ 错误处理器
autodiscovery, API gateway, API ID, API Manager	→ API 自动发现
import project, reference project, shared library, JAR import	→ 导入
properties, config.yaml, .properties, placeholder, environment, dev/QA/prod, multi-env, check placeholders, unresolved properties	→ 属性
global-property, inline property, name-value	→ 全局属性
list all, what global elements, show all configs	→ 全部列出
find usages, where is used, which flows reference	→ 查找用法
validate, check config exists, dangling reference	→ 验证
consolidate, centralize, move to global-config	→ 合并

操作路由 — 第 2 级（操作）：

意图	操作
创建 / 添加 / 设置 / 配置（新建）	→ 创建
获取 / 列出 / 显示 / 查看	→ 获取
编辑 / 更新 / 修改 / 更改	→ 编辑
删除 / 移除 / 丢弃	→ 删除

如果不清楚，请询问：

您想执行什么操作？（创建、查看、编辑、删除、验证、合并）

停止。

步骤 3：解析连接器（连接器配置 — 创建）

如果用户未指定，请询问要使用哪个连接器。然后搜索 Exchange：

bash scripts/get_latest_connector.sh salesforce sfdc

如果返回多个变体，且用户未预先提供特定的连接器制品，则通过 AskUserQuestion 询问用户，并停止。如果只有一个匹配结果（或该连接器已在 pom.xml 中），则继续，不要询问。

然后选择：

bash scripts/pick_connector.sh sfdc com.mulesoft.connectors:mule-salesforce-connector:11.1.0

如果连接器已在项目的 pom.xml 中，则从中提取 GAV。

步骤 4：描述连接器

bash scripts/describe_connector.sh sfdc

读取摘要中的 configs[] 和 connectionProviders。

步骤 5：询问配置名称

如果用户预先提供了配置名称，则使用该名称并跳过此停止步骤。否则询问：

此连接器配置要使用什么名称？（例如，salesforceConfig）

停止（仅当用户未预先提供名称时）。

步骤 6：选择连接提供程序

如果用户预先提供的提供程序名称与元数据中的某个提供程序明确匹配，则使用该提供程序并跳过此停止步骤。如果存在多个提供程序，且用户未指定（或名称存在歧义），则询问用户。

停止（仅在提示用户时）。

步骤 7：获取提供程序详细信息

anypoint-cli-v4 dx mule describe-connector \
  --connector "$(bash scripts/build_gav.sh tmp/connector-choices/sfdc.json)" \
  --type connection-provider \
  --name basic-connection \
  --config-name sfdc-config \
  --output json > tmp/connector-metadata/sfdc-config.json

检查是否存在 oauthCallbackConfig 子元素。

步骤 8：询问字段值

如果用户预先提供了明确的字段值，或表示所有字段都“使用占位符”/“使用默认占位符”，则采用该偏好并跳过此停止步骤。选择占位符时，自动为每个必填字段生成 ${connectorNamespace.fieldName}。

否则询问：

请提供必填字段的值，或选择“占位符”以使用 ${property} 引用。

停止（仅当用户未预先提供值时）。

步骤 9：生成 XML

阅读 references/global-elements-catalog.md 中的“连接器配置生成规则”部分。根据元数据，按照模式 1（属性）或模式 2（子元素）生成 XML。

步骤 10：生成 config.yaml

仅针对用户选择使用占位符的字段。使用 ${namespace.attributeName} 模式。

步骤 11：应用到项目并验证

1. 将配置写入 src/main/mule/global-configs.xml（如果文件不存在则创建 — 参见 references/global-config-conventions.md）。
2. 添加命名空间和 schemaLocation。
3. 写入或更新 src/main/resources/config.yaml。
4. 将连接器依赖项添加到 pom.xml（必须 — 不要跳过）：
   • 读取项目的 pom.xml。
   • 检查连接器的 <artifactId> 是否已存在于 <dependencies> 中。
   • 如果不存在，请在 <dependencies> 内添加此依赖项代码块：

     <dependency>
         <groupId>{groupId}</groupId>
         <artifactId>{artifactId}</artifactId>
         <version>{version}</version>
         <classifier>mule-plugin</classifier>
     </dependency>
     

   • groupId、artifactId 和 version 来自 pick_connector.sh 保存到 tmp/connector-choices/ 中的 GAV。
   • 写入更新后的 pom.xml，添加新的依赖项。
5. 验证：

cd <project-dir> && mvn clean package -DskipTests

修复并重新运行，直到出现 BUILD SUCCESS。

获取 / 编辑 / 删除（连接器配置）：

**获取：**扫描 src/main/mule/*.xml，查找带有连接提供程序子元素的 <*:*-config> 元素。显示名称、类型、文件、提供程序和属性。

**编辑：**获取 → 询问要编辑哪项 → 显示当前值 → 询问要做哪些更改 → 停止 → 应用编辑 → 验证。

**删除：**确定要删除的项 → 在所有 XML 中搜索 config-ref="{name}" → 显示引用位置 → 确认 → 停止 → 移除元素 → 清理命名空间 → 验证。

步骤 12：创建全局元素（TLS、对象存储、缓存、错误处理器、自动发现、导入）

对于以下所有元素类型，生成 XML 之前，请阅读 references/global-elements-catalog.md，了解规范 XML 结构、必需属性和验证规则。

TLS 上下文 — 创建

**Q1：**名称？仅信任库 / 仅密钥库 / 两者（双向 TLS）？

停止。

**Q2：**存储路径、密码（使用占位符）。可选：协议、密码套件、吊销检查、存储类型/算法。

停止。 → 执行：将 XML 写入 global-configs.xml，添加 tls 命名空间，更新 config.yaml。

对象存储 — 创建

**Q1：**需要新的 os:config，还是使用现有配置？名称？

停止。

**Q2：**对象存储名称、config-ref、是否持久化、maxEntries、entryTtl、TTL 单位。

停止。 → 执行：

1. 将 XML（先配置、后 object-store）写入 global-configs.xml。
2. 添加 os 命名空间：xmlns:os="http://www.mulesoft.org/schema/mule/os" 及其 schemaLocation 条目。
3. 将 mule-objectstore-connector 依赖项添加到 pom.xml（必须 — 不要跳过）：
   • 读取 pom.xml，检查 <dependencies> 中是否已存在 mule-objectstore-connector。
   • 如果不存在，请在 <dependencies> 内添加此依赖项代码块：

     <dependency>
         <groupId>org.mule.connectors</groupId>
         <artifactId>mule-objectstore-connector</artifactId>
         <version>1.2.5</version>
         <classifier>mule-plugin</classifier>
     </dependency>
     

   • 写入更新后的 pom.xml。
4. 验证构建：cd <project-dir> && mvn clean package -DskipTests。

缓存策略 — 创建

**Q1：**名称？要使用哪个对象存储（现有引用或内联配置）？

停止。

**Q2：**键生成表达式？事件复制策略（simple/serializable）？是否同步？

停止。 → 执行：写入 XML，添加 ee 命名空间；如果对象存储采用内联配置，则确保已添加对象存储依赖项。

错误处理器 — 创建

**Q1：**名称？使用哪些策略？（on-error-continue / on-error-propagate）。每种策略对应哪些错误类型？

停止。

**Q2：**每种策略应执行什么操作？（记录日志、设置有效负载、设置状态代码）。是否设为默认项？

停止。 → 执行：写入 XML；如果设为默认项，则添加 <configuration defaultErrorHandler-ref="..."/>。如果使用 <ee:transform>，则添加 ee 命名空间。

API 自动发现 — CREATE

Q1： API ID？使用哪个流程？（根据项目扫描结果显示可用流程）。

STOP。

Q2： 可选设置（ignoreBasePath 等）。

STOP。 → 执行：

1. 将 XML 写入 global-configs.xml：

   <api-gateway:autodiscovery apiId="${api.id}" flowRef="{flow-name}" doc:name="API AutoDiscovery" />
   

2. 添加 api-gateway 命名空间：xmlns:api-gateway="http://www.mulesoft.org/schema/mule/api-gateway"，并添加对应的 schemaLocation 条目。
3. 将 mule-api-gateway 依赖添加到 pom.xml（必须执行，不可跳过）：
   • 读取 pom.xml，检查 <dependencies> 中是否已存在 mule-api-gateway。
   • 如果不存在，在 <dependencies> 中添加以下依赖块：

     <dependency>
         <groupId>org.mule.modules</groupId>
         <artifactId>mule-api-gateway</artifactId>
         <version>${app.runtime}</version>
         <classifier>mule-plugin</classifier>
         <scope>provided</scope>
     </dependency>
     

   • 写入更新后的 pom.xml。
4. 将 api.id 添加到 config.yaml（必须执行，不可跳过）：
   • 读取 src/main/resources/config.yaml。
   • 在合适的部分下添加 api.id: "YOUR_API_ID"（或用户指定的值）。
   • 写入更新后的 config.yaml。
5. 验证构建：cd <project-dir> && mvn clean package -DskipTests。

IMPORT — CREATE

Q1： Maven 坐标（groupId、artifactId、version）？

STOP。

Q2： 要使用哪些资源？添加 <import> 声明吗？

STOP。 → 执行：将依赖添加到 pom.xml，并将 <import file="{artifactId}.xml"/> 添加到 global-configs.xml。

GET / EDIT / DELETE（所有元素类型）

与 Connector Config 相同的通用模式：

GET： 扫描所有 Mule XML，查找相关元素模式。按类型分组显示。

EDIT： 列出 → 询问要编辑哪项 → 显示值 → 询问要进行哪些更改 → STOP → 应用更改 → 验证。

DELETE： 确定目标 → 查找用法（参见 references/global-elements-catalog.md 中按类型列出的引用模式）→ 呈现结果 → 确认 → STOP → 删除 → 清理命名空间 → 验证。

Step 13：属性管理

执行任何属性操作前，先阅读 references/properties-patterns.md。

CREATE FILE

Q1： YAML 格式还是 Properties 格式？文件名是什么？

STOP。

Q2： 初始键值对（或“空”）？是否注册为 <configuration-properties>？

STOP。 → 执行：在 src/main/resources/ 中创建文件；如用户要求，则在 global-configs.xml 中注册。

EDIT FILE

Q1： 列出可用文件 → 要编辑哪个？

STOP。

Q2： 显示当前内容 → 要添加／修改／删除什么？

STOP。 → 执行：应用更改；如果删除的键仍被引用，则发出警告。

SETUP ENV

Q1： 哪些环境？（dev、QA、prod 等）默认环境是什么？

STOP。

Q2： 哪些属性因环境而异？基础 config.yaml 中有哪些通用属性？

STOP。 → 执行：创建各环境文件，添加 <global-property name="env" value="{default}"/>，并将 <configuration-properties file="${env}.yaml"/> 添加到 global-configs.xml。

REGISTER / UNREGISTER

Register： 列出未注册的文件 → 询问要注册哪个 → 添加 <configuration-properties file="..." doc:name="..."/>。

Unregister： 列出已注册的文件 → 询问要取消注册哪个 → 发出警告（“占位符将无法解析”）→ 确认 → STOP → 移除元素（保留文件）。

GLOBAL PROPERTY — CREATE / EDIT / DELETE

Create Q1： 要添加哪些名称-值对？

STOP。 → 执行：将 <global-property name="..." value="..." doc:name="..."/> 添加到 global-configs.xml。

Edit： 列出 → 询问要编辑哪项 → 显示 → 询问新值 → STOP → 应用更改。

Delete： 列出 → 查找 ${name} 的用法 → 呈现结果 → 确认 → STOP → 移除。

GET（查看属性设置）

列出：已注册文件、未注册文件和全局属性。显示键数量及注册位置。

Step 14：管理操作（全部列出、查找用法、验证、整合）

列出全部

1. 扫描 src/main/mule/ 下的所有 Mule XML 文件。
2. 识别 <mule> 内每个非顶层 <flow> 或 <sub-flow> 元素。
3. 分类：连接器配置、配置属性、全局属性、全局错误处理器、API 自动发现、TLS 上下文、对象存储、缓存策略、导入引用、应用程序配置、其他。
4. 统计每个命名元素的使用次数（搜索 config-ref、tlsContext、objectStore、cachingStrategy-ref、defaultErrorHandler-ref、errorHandler-ref、listenerConfig）。
5. 按组显示表格，包含名称、类型、文件、使用次数。
6. 突出显示问题：未解析的占位符、分散的配置（不在 global-configs.xml 中）、未使用的元素（0 个引用）。

查找用法

1. 确定目标元素（如果未指定，则列出所有元素并询问要查找哪一个）。
2. 使用各类型对应的模式，在所有 Mule XML 文件中搜索引用：
   • config-ref="{name}" — 连接器操作/源
   • listenerConfig="{name}" — OAuth 回调配置
   • tlsContext="{name}" — HTTP 配置
   • objectStore="{name}" — 缓存策略
   • cachingStrategy-ref="{name}" — <ee:cache> 作用域
   • defaultErrorHandler-ref="{name}" — <configuration>
   • errorHandler-ref="{name}" — 单个流
3. 显示：文件、行号、流/元素、属性、上下文片段。

验证

检查流 XML 中的每个 config-ref、tlsContext、objectStore、cachingStrategy-ref、defaultErrorHandler-ref、errorHandler-ref 和 listenerConfig 属性，确保它们指向项目中实际存在的全局元素。

1. 扫描 src/main/mule/ 下的所有 Mule XML，查找引用属性（config-ref="X"、tlsContext="X"、objectStore="X"、cachingStrategy-ref="X"、defaultErrorHandler-ref="X"、errorHandler-ref="X"、listenerConfig="X"）。
2. 收集所有已声明的全局元素名称（带有 name 属性的顶层元素）。
3. 对于每个引用，检查被引用的名称是否存在于已声明名称集合中。
4. 报告所有悬空引用——指向项目中不存在的全局元素的属性。注明文件、行号和缺失的名称。
5. 建议修复方式：创建缺失的全局元素，或将引用改为现有元素。

整合

阅读 references/global-config-conventions.md →“整合决策矩阵”部分。

1. 扫描所有文件，查找 global-configs.xml 之外的全局元素。
2. 根据决策矩阵，将每个元素归类为可移动或与流耦合。
3. 提交报告：哪些内容应移动、哪些应保留及其原因。
4. 等待明确确认 → 停止。
5. 执行：移动元素、添加命名空间声明、从源文件中删除元素、清理未使用的命名空间。
6. 验证构建：mvn clean package -DskipTests。
7. 报告：移动的元素数量、命名空间清理情况、构建结果。

提示和最佳实践

• 仅根据元数据确定配置结构。 切勿硬编码连接器的属性或子元素。describe-connector 元数据是唯一可信来源。
• 仅从 Exchange 获取连接器版本。 切勿凭记忆填写版本——使用 get_latest_connector.sh → pick_connector.sh。
• 所有配置都放在 global-configs.xml 中。 有关排序和结构，请参阅 references/global-config-conventions.md。
• 多轮交互。 在每个决策点：仅以纯文本形式提出问题，结束回复并等待用户输入后再继续。
• 跳过用户已提供的信息。 如果用户的初始请求中包含详细信息（配置名称、提供方、占位符偏好、字段值），则跳过相应的 STOP 点。只询问未提供或含糊不清的信息。
• 切勿在聊天中输出原始 XML——始终写入文件。
• 不使用 MCP 服务工具。 所有 Exchange 搜索和连接器操作都必须仅使用提供的 bash 脚本。
• 始终更新 pom.xml。 每个需要依赖项的连接器／模块都必须添加到 pom.xml 中。这是导致构建失败的首要原因。依赖项 XML 模式记录在 references/global-elements-catalog.md 中。读取 pom.xml → 添加依赖项 → 写入 pom.xml。务必在运行 mvn clean package 之前完成。
• 占位符始终要更新 config.yaml。 在 XML 中使用 ${property.name} 占位符时，必须在 src/main/resources/config.yaml 中添加相应属性。对于 AutoDiscovery，始终将 api.id 添加到 config.yaml。

故障排查

• 添加配置后构建失败： 检查命名空间声明是否与连接器的 XSD URL 匹配。确认 schemaLocation URL 正确。
• 在 Exchange 中找不到连接器： 确保 Anypoint CLI 已通过身份验证。尝试在 get_latest_connector.sh 中使用更宽泛的搜索词。
• describe-connector 失败： 确认 Java 11+ 可用且连接器 GAV 有效。检查 tmp/connector-choices/ 中是否存在已保存的 JSON。
• 运行时存在未解析的占位符： 确保 <configuration-properties> 已在 global-configs.xml 中注册，且属性文件存在于 src/main/resources/ 中。
• 命名空间冲突： 运行整合操作，集中管理所有全局元素并清理重复的命名空间声明。

相关任务

• build-mule-integration：构建引用此技能创建的全局配置的 Mule 流
• secure-mule-app：为敏感配置值配置安全属性加密
• create-project-template：在添加配置之前，生成结构规范的 Mule 项目