platform-value-set-generate

概述

生成并验证两种可复用的选项列表值集元数据类型：GlobalValueSet（在多个字段间共享的新建可复用值集）和 StandardValueSet（自定义内置目录选项列表，如 Industry 或 Lead Source），并通过 <valueSetName> 将 CustomField 关联到其中一种。

有关此技能未涵盖的 Metadata API 类型、字段和枚举的权威信息，请使用 platform-metadata-api-context-get 技能。

范围

• **范围内：**创建 GlobalValueSet、自定义 StandardValueSet、从字段引用其中任一种，以及处理相关部署错误。
• **范围外：**仅用于单个字段且不复用的一次性内联选项列表 → 使用 platform-custom-field-generate（内联 <valueSetDefinition>）。生成引用值集的字段也属于 platform-custom-field-generate 的工作；此技能仅生成值集本身。

两种不同的元数据类型——请勿混淆：

关注点	GlobalValueSet	StandardValueSet
文件夹	globalValueSets/	standardValueSets/
文件后缀	.globalValueSet-meta.xml	.standardValueSet-meta.xml
根元素	<GlobalValueSet>	<StandardValueSet>
名称来源	文件名（开发名称）	<fullName> = 固定目录名称
值元素	<customValue>	<standardValue>
能否添加新值？	可以	可以——复制现有值的属性模式
能否创建新名称？	可以	不可以——只能使用固定目录
package.xml 中的 * 通配符	支持	不支持

---

规范

1. 用途

本文档定义了生成值集元数据 XML 的强制约束。Agent 必须在输出 XML 前验证这些约束，以防止 Metadata API 部署错误。

• GlobalValueSet — 可复用的命名选项列表值集，只需定义一次，即可供任意数量的选项列表/多选字段引用。多个字段共享同一值列表时使用。
• StandardValueSet — Salesforce 定义的标准选项列表（Industry、Lead Source 等）背后的值列表。只能自定义固定的命名值集目录，因此不能自行创建新的值集名称，但可以修改现有值并添加新值。

---

2. GlobalValueSet — 语法要点

文件： globalValueSets/<DeveloperName>.globalValueSet-meta.xml

开发名称取自文件名，而非 <fullName> 标签。

必需元素

元素	要求	说明
<masterLabel>	必需	值集在 UI 中显示的标签
<sorted>	必需	true = 在 UI 中按字母顺序排列值；false = 保持所列顺序
<customValue>	必需（≥1）	每个值对应一个（见下文）

<customValue> 子元素

子元素	要求	说明
<fullName>	必需	值的 API 名称。使用用户输入的原样文本作为值——允许空格，且必须保留（例如 Closed Won，而不是 Closed_Won）。必须以字母开头。这是值名称，不是字段 API 名称，因此不要追加 __c，也不要将空格替换为下划线。
<default>	可选	最多只能有一个值为 true。其他值可省略（或使用 false）——并非每个值都必须设置此元素。
<label>	必需	值在 UI 中显示的标签
<color>	可选	十六进制颜色，例如 #FF0000
<isActive>	可选	省略表示启用；设为 false 表示停用
<description>	可选	值的描述

__gvs 后缀 — 不要在元数据中使用

规则：引用 GlobalValueSet 时使用不带后缀的开发者名称。绝不要添加 __gvs。

在 API 57.0+ 组织中，平台会在内部以带 __gvs 后缀的形式存储／显示 GlobalValueSet 的开发者名称，但 Metadata API（部署和检索）始终使用不带后缀的名称——<valueSetName>Priority_Levels</valueSetName>，而不是 Priority_Levels__gvs。Winter '23 的一项变更曾短暂输出该后缀，导致部署失败，之后已修复。因此：

• 文件名为 globalValueSets/Priority_Levels.globalValueSet-meta.xml——文件名中不带 __gvs。
• 字段通过 <valueSetName>Priority_Levels</valueSetName> 引用它——不带 __gvs。
• 如果检索结果显示组织中的名称为 Priority_Levels__gvs，或你看到“returned from org but not found in local project”警告，这是组织存储时的预期显示形式——本地元数据继续使用不带后缀的名称。

正确 — GlobalValueSet

<?xml version="1.0" encoding="UTF-8"?>
<GlobalValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Priority Levels</masterLabel>
    <sorted>false</sorted>
    <customValue>
        <fullName>Critical</fullName>
        <default>false</default>
        <label>Critical</label>
    </customValue>
    <customValue>
        <fullName>High</fullName>
        <default>false</default>
        <label>High</label>
    </customValue>
    <customValue>
        <fullName>Medium</fullName>
        <default>true</default>
        <label>Medium</label>
    </customValue>
    <customValue>
        <fullName>Low</fullName>
        <default>false</default>
        <label>Low</label>
    </customValue>
</GlobalValueSet>

错误 — GlobalValueSet

<GlobalValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Priority_Levels</fullName>      
    <masterLabel>Priority Levels</masterLabel>
    
    <standardValue>                            
        <fullName>Critical</fullName>
    </standardValue>
</GlobalValueSet>

错误： 缺少必需的 sorted；未知元素 standardValue；根级 fullName 会被拒绝，因为名称是根据文件名确定的。

---

3. StandardValueSet — 语法要点（重要）

文件： standardValueSets/<Name>.standardValueSet-meta.xml

硬性约束 — 生成前请先阅读

1. StandardValueSet 名称必须来自固定的命名标准值集目录。 你不能创建新的 StandardValueSet 名称。你可以向现有标准值集添加新值，但必须照搬该集合中现有值的完整属性模式（例如 OpportunityStage 中的 closed、forecastCategory、probability 和 won），因为省略的属性会填入可能不正确的平台默认值。
2. 根元素包含 <fullName>，其值为固定枚举名称（例如 Industry），而不是 masterLabel。文件名必须与此名称一致。
3. 值使用 <standardValue> 条目——而不是 <customValue>。
4. 写入 StandardValueSet 会替换整个集合。请发送所有现有值，只更改请求中指定的内容。 先读取当前集合（使用 MCP grounding 或检索），然后为每个现有值都包含一个 <standardValue> 块，并应用请求的启用、停用、重命名或新增操作。省略某个值会使它在字段上停用：仅在 CaseOrigin 中指定 Web 的部署，会导致 Email、Phone 和 Agentforce 处于停用状态。绝不要只发送指定的值，即使该集合很大（例如 Industry 中所有 30 多个条目）。请求中的“仅保留 X 启用”等措辞，意味着将 X 设为启用，并将其他所有值设为停用，因此结果中要明确表达这一意图。写入后，重新读取该集合，并与写入前的读取结果进行差异比较。

<standardValue> — 可修改的子元素

子元素	可修改？	说明
<fullName>	标识该值	现有值，或你要添加的新值
<label>	是	重命名该值在 UI 中显示的文本
<isActive>	是	false 会停用该值；省略或设为 true 则保持启用
<default>	是	最多只能有一个值设为 true
<groupingString>	是	类别分组（部分标准选项列表会使用）

标准 StandardValueSet 名称（部分列表）

Industry、LeadSource、OpportunityStage、OpportunityType、AccountType、AccountRating、LeadStatus、CaseStatus、CaseOrigin、CasePriority、CaseReason、TaskStatus、TaskPriority、QuoteStatus、Product2Family、Salutation、AccountOwnership、ContractStatus、OrderStatus、PartnerRole。

完整附录：有效标准值集名称的完整列表见 https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/standardvalueset_names.htm。 如果名称不在该附录中，它就不是 StandardValueSet——而是 GlobalValueSet 或内联 CustomField 选项列表。

正确 — StandardValueSet（完整集合，已应用请求的更改）

<?xml version="1.0" encoding="UTF-8"?>
<StandardValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Industry</fullName>
    <standardValue>
        <fullName>Technology</fullName>
        <default>false</default>
        <label>Technology</label>
        <isActive>true</isActive>
    </standardValue>
    <standardValue>
        <fullName>Agriculture</fullName>
        <default>false</default>
        <label>Agriculture</label>
        <isActive>false</isActive>   
    </standardValue>
    
</StandardValueSet>

错误 — StandardValueSet

<StandardValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Industry</masterLabel>     
    <customValue>                           
        <fullName>Renewable Energy</fullName>
        <label>Renewable Energy</label>
    </customValue>
</StandardValueSet>

错误： StandardValueSet 不支持未知元素 masterLabel/customValue。

---

4. 切勿臆造值 — 验证，不要凭空捏造 CRITICAL

自定义 StandardValueSet（或扩展共享的 GlobalValueSet）时，切勿臆造标准选项列表中的现有值。必须原样重复组织中的现有值，且只有在请求明确指定时才添加新值。

对于你已知规范值的常见标准选项列表（例如 Industry、LeadSource、OpportunityStage），可直接使用这些值。如果不确定有哪些值，可以向实时组织确认，但应将查询视为确认步骤，而非必需的首次调用：

• Grounding MCP（如果可用）提供 search_metadata 和 query_metadata，用于查询实时元数据。使用它们读取完整的当前值集合，因为写入时必须重复每个现有值及其确切的 <fullName>/<label>。
• CLI 备用方案 — 直接查询 Tooling API：

sf data query --use-tooling-api \
  --query "SELECT MasterLabel, Metadata FROM StandardValueSet WHERE MasterLabel = '<name>'"

重点在于输出，而非查询： 写入的集合必须包含所有未更改的现有值，以及仅由请求指定的更改。不要臆造请求未要求的值。（这与 §3 中的规则 4 相呼应：写入会替换整个集合。）

---

5. 在 CustomField 中引用值集

选项列表/多选 CustomField 通过 <valueSet> 内的 <valueSetName> 引用值集（而非内联 <valueSetDefinition>）。

<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Priority__c</fullName>
    <label>Priority</label>
    <type>Picklist</type>
    <valueSet>
        <restricted>true</restricted>
        <valueSetName>Priority_Levels</valueSetName>  
    </valueSet>
</CustomField>

• 对于 GlobalValueSet，<valueSetName> 是不带后缀的开发者名称（例如 Priority_Levels）——切勿添加 __gvs。该后缀只是组织存储中的显示形式；Metadata API 在部署和检索时都使用不带后缀的名称（见 §2）。
• 绑定到值集的字段不得同时声明内联 <valueSetDefinition> ——二者只能选其一。

---

6. 验证规则

对于以下情况，Agent 必须拒绝并说明原因，而不是悄悄通过臆造元数据来“修复”：

违规情况	操作 / 消息
创建新的 StandardValueSet 名称	拒绝。该名称必须在标准目录附录中，否则它属于 GlobalValueSet。
值集开发者名称包含空格 / 无效字符	将空格转换为下划线；名称必须以字母开头，且只能包含字母数字字符和下划线。Priority Levels → Priority_Levels。（此规则适用于值集名称和字段 API 名称，不适用于单个 <customValue><fullName> 值；这些值应保留原有空格。）
同一值集内存在重复的 fullName	拒绝。每个 fullName 在值集中都必须唯一。
存在多个 <default>true</default>	拒绝。每个值集最多只能有一个默认值。

向标准值集添加值

“向 Industry 选项列表添加一个 Cryptocurrency 值。”

这是允许的。读取完整的当前 Industry 值集，然后写回所有未更改的现有值，并添加一个新的 <standardValue>，其值为 Cryptocurrency。复制集合中现有值的属性格式，因为省略属性时，平台可能采用错误的默认值。

---

7. 部署顺序

必须先部署值集，然后才能部署引用它的任何 CustomField。

• 先部署 GlobalValueSet / StandardValueSet，再部署 <valueSetName> 指向它的 CustomField。
• 引用尚不存在的值集的字段会报错：valueSetName ... does not exist（或“未找到”错误）。
• 在 package.xml 中：GlobalValueSet 支持 * 通配符；StandardValueSet 不支持，必须逐一列出每个标准值集成员。

---

8. 常见部署错误

错误 / 症状	原因	修复方法
部署后，标准选项列表的其他值变为非活动状态	部署内容只列出部分值，而写入操作会替换整个集合	重新发送完整集合，包含每个现有值（§3 规则 4）
Required field missing: sorted	GlobalValueSet 缺少 <sorted>	添加 <sorted>true</sorted> 或 <sorted>false</sorted>
未知元素 masterLabel（StandardValueSet）	使用了 masterLabel，而非 fullName	StandardValueSet 根元素使用 <fullName> = 目录名称
未知元素 customValue（StandardValueSet）	使用了 customValue，而非 standardValue	标准集合中使用 <standardValue>
valueSetName ... does not exist	字段在其值集之前部署，或在引用中错误地添加了 __gvs	先部署值集；使用不带 __gvs 的裸开发者名称进行引用（§2）
值名称重复	两个 <customValue> 条目具有相同的 fullName	确保集合内每个 fullName 都唯一（值名称中允许有空格——不要将空格替换为下划线）

---

验证清单

生成值集 XML 前，请确认：

类型选择

• 这是一个供多个字段共享的可复用集合（GlobalValueSet），还是内置的标准选项列表（StandardValueSet）？
• 如果是 StandardValueSet：名称是否列在标准目录附录中？如果没有，则必须使用 GlobalValueSet 或内联选项列表。

GlobalValueSet 检查

• 根元素是否为带有命名空间 http://soap.sforce.com/2006/04/metadata 的 <GlobalValueSet>？
• 是否包含 <masterLabel>？
• 是否包含 <sorted>（true 或 false）？
• 是否至少有一个 <customValue>，且每个都包含 <fullName> 和 <label>（最多只有一个带有 <default>true</default>）？
• 是否没有根级 <fullName>（名称来自文件名）？
• 从字段进行引用时，<valueSetName> 是否为不带 __gvs 后缀的裸开发者名称？

StandardValueSet 检查——重要

• 是否读取了完整的当前集合（通过 search_metadata/query_metadata、Tooling API 或 retrieve 获取依据），以确保每个现有值都被原样重复？
• 根元素是否为带有正确命名空间的 <StandardValueSet>？
• 根元素是否使用 <fullName> 设置固定的目录名称（而非 masterLabel）？
• 值是否为 <standardValue> 条目（而非 customValue）？
• 写入的集合是否包含每个现有值，并且只应用请求中指定的更改？
• 是否避免使用新的集合名称？对于任何新值，是否复制了某个现有值的属性模式？

通用检查

• 带有 <default>true</default> 的值是否最多只有一个？
• 集合内所有值的 fullName 是否都唯一？（值名称中可以有空格——按原样保留；只有值集开发者名称和字段 API 名称使用下划线。）
• 值集是否在任何引用它的 CustomField 之前部署？
• 文件名是否与预期名称一致？