platform-custom-object-generate

何时使用此技能

当您需要以下操作时，请使用此技能：

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

规范

1. 概述和目的

本文档定义了生成CustomObject元数据XML（.object-meta.xml文件）时必须遵守的约束。代理必须在输出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层）

代理必须根据对象的预期用例选择要启用的功能。

A. 名称字段决策

类型	何时使用	附加要求
文本	默认用于以人类命名的实体（项目、位置、团队）	无
自动编号	用于交易、日志或ID（发票、请求、工单）	必须包含<displayFormat>（例如，INV-{0000}）和<startingNumber>1</startingNumber>

文本名称字段示例：

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

自动编号名称字段示例：

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

B. 对象描述（丰富）

<description>：必需 —— 每个自定义对象都必须有。它必须读起来像人工编写的文档，绝不是通用模板（“用于跟踪和管理...的对象”）或元数据转储（“包含8个字段，包括Project_Name__c...”）。

始终编写丰富的描述 —— 在创建对象时，以及对其任何更改时：添加、更新或删除字段或验证规则（这样它就不会过时）。更改（字段或验证规则）在刷新对象描述之前不算“完成”。这不是可选的；不要问是否要添加描述。

每次更改都确认 —— 每次都确认。 对每个字段/规则更改分别提出建议并确认。之前的“保持当前”仅适用于该次更改；它绝不是跳过后续更改建议的长期许可。不要从之前的回答中推断偏好 —— 每次新更改都要重新提出并重新询问。

编写描述（步骤如下）。如果对象已有描述，请将其作为强信号 —— 保留其承载的业务上下文（领域、团队、模式无法揭示的意图），并融入新字段/规则，而不是丢弃它。

然后根据是否已有描述进行分支：

• 没有现有描述（全新对象）： 没有要覆盖的内容 —— 只需写入编写的描述。不要提示。

• 有现有描述（更新、删除或任何重新丰富）： 切勿静默覆盖 —— 您无法从文件中判断它是管理员手写的还是之前生成的。显示建议，询问，然后停止 —— 等待用户回复后再写入：

  建议的{Object}描述：
  <the enriched description>
  当前：<the existing description>
  使用此描述？（是 / 保持当前 / 编辑）

  在用户回复之前，您绝不能写入<description> —— 显示差异不是批准，即使更改看起来明显或微小。然后执行：是 → 写入建议文本 · 保持当前 → 保持现有文本不变（这仅适用于此更改 —— 下次更改时重新提出建议） · 编辑 → 使用用户的措辞。

始终以写入<description>结束。

编写描述：

1. 对每个字段进行分类，根据其在描述中的出现方式：
   • 受限（必填、唯一、外部ID、受限选择列表）→ 选择性括号：VIN (required, external ID)、Color (Red/Green only)
   • 行为（公式、汇总）→ 描述其计算内容：“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：面向系统的对象（连接、后台日志）

• 触发：对象用于技术关联或后台数据
• 操作：省略这些标签以保持UI干净和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>
  <!-- fullName来自文件名：Vehicle__c.object-meta.xml -->
</CustomObject>

验证规则命名约定

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

规则：

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

❌ 错误：

<validationRules>
  <fullName>Require_Start_Date__c</fullName>  <!-- 错误：有__c后缀 -->
  <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>  <!-- 正确：无__c后缀 -->
  <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>时（创建时，或字段/规则更改时）—— 完整的丰富工作流程、字段优先级层级、连接/子对象处理、边缘情况以及更多示例