platform-custom-object-generate

何时使用此技能

在需要以下操作时使用此技能：

• 创建新的自定义对象
• 生成自定义对象元数据 XML
• 配置对象共享和安全设置
• 设置对象功能和能力
• 排查与自定义对象相关的部署错误
• 在现有对象上添加、更新或删除字段或验证规则 — 这些操作都可能导致对象的 <description> 过时，因此必须刷新它（提出建议并确认）。验证规则变更同样适用，不仅限于字段。请参阅第 3.B 节。

如需了解此技能之外权威的 Metadata API 类型、字段和枚举详情，请使用 platform-metadata-api-context-get 技能。

规范

1. 概述和用途

本文档定义了生成 CustomObject 元数据 XML（.object-meta.xml 文件）时必须遵守的约束。Agent 必须在输出 XML 前验证这些约束，以避免 Metadata API 部署错误。

文件扩展名： .object-meta.xml

描述的时效性 — 适用于每次对象变更，包括字段和验证规则： 每当在对象上添加、更新或删除字段 或验证规则 时，<description> 都可能过时。完成前，请按照 第 3.B 节刷新它（提出建议、与用户确认、写入）。验证规则变更与字段变更同等重要 — 在描述内容调整完毕前，变更尚未完成。修改或删除验证规则时很容易忘记这一步 — 别忘了。

---

2. 语法要点（第 1 层）

要使 XML 主体成功部署，必须满足以下约束。

注意： API 名称（fullName）不是标签，而是文件名（例如，Vehicle__c.object-meta.xml）。

必需元素

元素	要求	说明
<label>	必需	单数形式的 UI 名称
<pluralLabel>	必需	复数形式的 UI 名称
<sharingModel>	必需	请参阅下方的共享模型规则
<deploymentStatus>	必需	始终设为 Deployed
<nameField>	必需	主要记录标识符（需要 <label> 和 <type>）
<visibility>	必需	始终设为 Public

共享模型规则

默认值： 将 <sharingModel> 设为 ReadWrite。

例外： 如果此对象包含主从关系字段，<sharingModel> 必须设为 ControlledByParent。

判断逻辑：

• 如果对象没有主从关系字段 → 使用 ReadWrite
• 如果对象有主从关系字段 → 使用 ControlledByParent
• 如果要向现有子对象添加主从关系字段 → 也必须将该现有对象的 <sharingModel> 更新为 ControlledByParent

错误示例 — 将导致错误：Cannot set sharingModel to ReadWrite on a CustomObject with a MasterDetail relationship field

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <label>Order Line Item</label>
  <pluralLabel>Order Line Items</pluralLabel>
  <sharingModel>ReadWrite</sharingModel>  
  <deploymentStatus>Deployed</deploymentStatus>
</CustomObject>

正确示例：

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <label>Order Line Item</label>
  <pluralLabel>Order Line Items</pluralLabel>
  <sharingModel>ControlledByParent</sharingModel>  
  <deploymentStatus>Deployed</deploymentStatus>
</CustomObject>

---

3. 智能默认值和判断逻辑（第 2 层）

Agent 必须根据对象的预期用途选择要启用的功能。

A. 名称字段的选择

类型	适用场景	其他要求
Text	用于以人为命名的实体（项目、地点、团队）	无
AutoNumber	用于交易、日志或 ID（发票、请求、工单）	必须包含 <displayFormat>（例如，INV-{0000}）和 <startingNumber>1</startingNumber>

Text 名称字段示例：

<nameField>
  <label>Project Name</label>
  <type>Text</type>
</nameField>

AutoNumber 名称字段示例：

<nameField>
  <label>Invoice Number</label>
  <type>AutoNumber</type>
  <displayFormat>INV-{0000}</displayFormat>
  <startingNumber>1</startingNumber>
</nameField>

B. 对象描述（丰富完善）

<description>：必填 — 每个自定义对象都必须有描述。描述应像人工编写的文档，绝不能使用通用模板（“用于跟踪和管理……的对象”）或元数据清单（“包含 8 个字段，包括 Project_Name__c……”）。

始终编写丰富完善的描述 — 创建对象时，以及对象发生任何变更时，都要更新描述：添加、更新或删除字段或验证规则（确保描述始终准确）。只有刷新对象描述后，字段或验证规则的变更才算完成。这是必需步骤；不要询问是否要添加描述。

每次变更都要确认。 分别就每一项字段或规则变更提出方案并征求确认。之前回复的“保留当前描述”仅适用于当次变更，绝不能视为允许跳过之后变更的方案。不要根据之前的回复推断用户偏好；每次有新变更，都要重新提出方案并询问。

编写描述（见以下步骤）。如果对象已有描述，应将其视为重要参考 — 保留其中承载的业务背景（模式无法体现的领域、团队、意图），并将新增字段或规则融入描述，而不是将其丢弃。

然后根据描述是否已存在，采取不同处理方式：

• 不存在现有描述（全新对象）： 无内容需要覆盖 — 直接写入编写好的描述。不要询问。

• 存在现有描述（更新、删除或重新丰富）： 绝不能悄悄覆盖 — 无法从文件判断它是管理员手动编写的，还是先前生成的。请展示方案、征求确认，然后停止 — 等待用户回复后再写入：

  {Object} 的拟议描述： <丰富完善后的描述> 当前描述：<现有描述> 使用此描述？（是 / 保留当前描述 / 编辑）

  用户回复之前，绝不能写入 <description> — 展示差异不代表已获批准，即使变更看起来显而易见或很小也不例外。然后按用户回复处理：是 → 写入拟议文本 · 保留当前描述 → 保持现有描述不变（仅适用于当次变更 — 下次变更时重新提出方案）· 编辑 → 使用用户提供的文字。

始终以写入的 <description> 结束。

编写描述：

1. 按字段在描述中的呈现方式分类：
   • 受约束字段（必填、唯一、externalId、受限选项列表）→ 有选择地添加括号说明：VIN（必填，外部 ID）、Color（仅限 Red/Green）
   • 行为字段（公式、汇总）→ 描述其计算内容：“Age Years 字段自动计算车辆年限”
   • 关系字段（主从关系、查找关系）→ 融入上下文：“作为 Account 的子对象”（绝不要写成“（与 Account 的主从关系）”）
   • 标准字段 → 仅写标签
2. 按以下顺序编写，使用字段标签而非 API 名称：

   用途 → 关键字段 → 计算字段 → 验证规则（作为业务规则）→ “常用于 {用例}。”

3. 写入前统计并精简（必需）： 统计词数；目标约 45 词，最多 50 词。若超出，先精简措辞，再按优先级删除完整句子（用例 → 规则 → 计算字段；绝不删除第 1–2 句）。重新统计。词数不超过 50 之前，不要写入。

示例（Car，46 词）：

<description>The Car object tracks vehicle inventory and maintenance. It captures Year, VIN (required, external ID), Color (Red/Green only), and Location; the Age Years field auto-calculates vehicle age. VIN is required and Black cars cannot be sold. Commonly used for fleet management, inventory tracking, and service scheduling.</description>

→ 完整工作流和示例请参阅 references/description-enrichment.md。

C. 联结对象命名

如果对象用于连接两个父对象，形成多对多关系，应将两个父对象的实体名称组合起来作为对象名称，确保模式直观易懂。

示例：

• Position_Candidate__c（连接 Position 和 Candidate）
• Job_Application__c（连接 Job 和 Application）

D. 功能启用（保持 XML 简洁）

为保持“XML 简洁”，仅在偏离 Salesforce 平台默认值 false 时，才包含可选标签。

场景 A：面向用户的对象（应用、跟踪器、业务实体）

• 触发条件：对象用于直接与用户交互
• 操作：将 <enableSearch>、<enableReports>、<enableActivities> 和 <enableHistory> 设置为 true

场景 B：面向系统的对象（关联对象、后台日志）

• 触发条件：对象用于技术关联或存储后台数据
• 操作：省略这些标签，使界面保持简洁、XML 保持精简

---

4. 关键约束与常见失败

保留字

切勿将保留字用作自定义对象或自定义字段的 API 名称：

类别	保留字（不得用作 API 名称）
SOQL/SQL	Select、From、Where、Limit、Order、Group
系统	User、External、View、Type
时间	Date、Number

关系数量上限

单个对象不得创建超过 2 个主从关系。如果需要第三个关系，请改用查找关系。

XML 根元素

请勿在 .object-meta.xml 文件的根层级包含 <fullName> 标签。API 名称根据文件名确定。

错误示例：

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <fullName>Vehicle__c</fullName>  
  <label>Vehicle</label>
</CustomObject>

正确示例：

<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
  <label>Vehicle</label>
  
</CustomObject>

验证规则命名约定

验证规则名称遵循与自定义字段不同的约定。

规则：

• 只能包含字母、数字和下划线
• 必须以字母开头
• 不能以下划线结尾
• 不能包含两个连续的下划线
• 不得以 __c 结尾（自定义字段则不同）

错误示例：

<validationRules>
  <fullName>Require_Start_Date__c</fullName>  
  <active>true</active>
  <errorMessage>Start Date is required.</errorMessage>
  <formula>ISBLANK(Start_Date__c)</formula>
</validationRules>

错误： The validation name can only contain alphanumeric characters, must begin with a letter, cannot end with an underscore...

正确示例：

<validationRules>
  <fullName>Require_Start_Date</fullName>  
  <active>true</active>
  <errorMessage>Start Date is required.</errorMessage>
  <formula>ISBLANK(Start_Date__c)</formula>
</validationRules>

命名模式参考：

元数据类型	命名模式	示例
自定义字段	以 __c 结尾	Start_Date__c
验证规则	无后缀	Require_Start_Date
自定义对象	以 __c 结尾	Vehicle__c

---

5. 验证清单

生成自定义对象 XML 之前，请确认：

语法检查

• 是否包含 <label> 和 <pluralLabel>？
• <deploymentStatus> 是否设置为 Deployed？
• <visibility> 是否设置为 Public？
• <nameField> 是否同时包含 <label> 和 <type>？
• 如果 <type> 为 AutoNumber，是否包含 <displayFormat> 和 <startingNumber>？

共享模型检查（关键）

• 此对象是否具有主从关系字段？
  • 如果是 → <sharingModel> 必须为 ControlledByParent
  • 如果否 → <sharingModel> 应为 ReadWrite

约束检查

• API 名称是否未使用保留字？
• 主从关系是否不超过 2 个？
• XML 根层级是否未包含 <fullName>？

验证规则检查（如适用）

• 验证规则名称是否未以 __c 结尾？
• 验证规则名称是否符合字母、数字和下划线的模式？

描述完善质量检查

• 是否以“The {Object} object...”开头并说明业务用途（而不是“Object used to track and manage...”）？
• 是否使用字段标签而非 API 名称；是否避免“包含 N 个字段，包括……”这样的罗列？
• 是否按行为描述公式/汇总字段，将验证规则表述为业务规则，并将关系作为上下文说明？
• 是否包含常见用例（“通常用于……”），且少于 50 个词？
• 是否将当前描述中的业务背景融入建议的新描述（未将其丢弃）？
• 对于现有描述（更新/删除/重新完善），是否已停止并等待用户回复后再编写——未将展示差异视为批准？

架构检查

• 是否存在 <description>？（根据 B 节进行丰富——写入前与用户确认建议内容。）
• 如果面向用户，是否将 <enableSearch> 和 <enableReports> 设为 true？
• 文件名是否与预期的 API 名称一致？

---

参考文件索引

文件	何时阅读
references/description-enrichment.md	编写或刷新对象的 <description> 时（创建时，或字段／规则发生变化时）——完整的丰富流程、字段优先级层级、关联／子级处理、边缘情况及更多示例