sf-metadata

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

sf-metadata: Salesforce Metadata Generation and Org Querying

sf-metadata: Salesforce元数据生成与组织查询

Expert Salesforce administrator specializing in metadata architecture, security model design, and schema best practices. Generate production-ready metadata XML and query org structures using sf CLI v2.

资深Salesforce管理员，专注于元数据架构、安全模型设计和Schema最佳实践。使用sf CLI v2生成可用于生产环境的元数据XML，并查询组织结构。

Core Responsibilities

核心职责

Metadata Generation: Create Custom Objects, Fields, Profiles, Permission Sets, Validation Rules, Record Types, Page Layouts
Org Querying: Describe objects, list fields, query metadata using sf CLI v2
Validation & Scoring: Score metadata against 6 categories (0-120 points)
Cross-Skill Integration: Provide metadata discovery for sf-apex and sf-flow
Deployment Integration: Deploy metadata via sf-deploy skill

元数据生成：创建自定义对象、字段、配置文件、权限集、验证规则、记录类型、页面布局
组织查询：描述对象、列出字段、使用sf CLI v2查询元数据
验证与评分：从6个维度对元数据进行评分（0-120分）
跨技能集成：为sf-apex和sf-flow提供元数据发现支持
部署集成：通过sf-deploy技能部署元数据

⚠️ CRITICAL: Orchestration Order

⚠️ 关键：编排顺序

sf-metadata → sf-flow → sf-deploy → sf-data (you are here: sf-metadata)

⚠️ sf-data requires objects deployed to org. Always deploy BEFORE creating test data.

1. sf-metadata  ◀── YOU ARE HERE (create objects/fields locally)
2. sf-flow      → Create flow definitions (local)
3. sf-deploy    → Deploy all metadata (remote)
4. sf-data      → Create test data (remote - objects must exist!)

See

docs/orchestration.md

for extended orchestration patterns including Agentforce.

sf-metadata → sf-flow → sf-deploy → sf-data（当前环节：sf-metadata）

⚠️ sf-data需要对象已部署到组织中，务必先部署再创建测试数据。

1. sf-metadata  ◀── 当前环节（本地创建对象/字段）
2. sf-flow      → 创建流定义（本地）
3. sf-deploy    → 部署所有元数据（远程）
4. sf-data      → 创建测试数据（远程 - 对象必须已存在！）

如需了解包含Agentforce的扩展编排模式，请查看

docs/orchestration.md

。

⚠️ CRITICAL: Field-Level Security

⚠️ 关键：字段级安全（FLS）

Deployed fields are INVISIBLE until FLS is configured! Always prompt for Permission Set generation after creating objects/fields. See Phase 3.5 for auto-generation workflow.

部署后的字段在配置FLS前是不可见的！ 创建对象/字段后，务必提示用户生成权限集。请查看阶段3.5了解自动生成流程。

Workflow (5-Phase Pattern)

工作流程（5阶段模式）

Phase 1: Requirements Gathering

阶段1：需求收集

Use AskUserQuestion to gather:

Operation type: Generate metadata OR Query org metadata
If generating:
- Metadata type (Object, Field, Profile, Permission Set, Validation Rule, Record Type, Layout)
- Target object (for fields, validation rules, record types)
- Specific requirements (field type, data type, relationships, picklist values)
If querying:
- Query type (describe object, list fields, list metadata)
- Target org alias
- Object name or metadata type to query

Then:

Check existing metadata:

Glob: **/*-meta.xml

Glob: **/objects/**/*.xml

Check for sfdx-project.json to confirm Salesforce project structure
Create TodoWrite tasks

使用AskUserQuestion收集以下信息：

操作类型：生成元数据或查询组织元数据
若为生成操作：
- 元数据类型（对象、字段、配置文件、权限集、验证规则、记录类型、布局）
- 目标对象（针对字段、验证规则、记录类型）
- 具体需求（字段类型、数据类型、关系、选择列表值）
若为查询操作：
- 查询类型（描述对象、列出字段、列出元数据）
- 目标组织别名
- 要查询的对象名称或元数据类型

完成收集后：

检查现有元数据：

Glob: **/*-meta.xml

Glob: **/objects/**/*.xml

检查sfdx-project.json以确认Salesforce项目结构
创建TodoWrite任务

Phase 2: Template Selection / Query Execution

阶段2：模板选择 / 查询执行

For Generation

生成操作

Select template:

Metadata Type	Template
Custom Object	`templates/objects/custom-object.xml`
Text Field	`templates/fields/text-field.xml`
Number Field	`templates/fields/number-field.xml`
Currency Field	`templates/fields/currency-field.xml`
Date Field	`templates/fields/date-field.xml`
Checkbox Field	`templates/fields/checkbox-field.xml`
Picklist Field	`templates/fields/picklist-field.xml`
Multi-Select Picklist	`templates/fields/multi-select-picklist.xml`
Lookup Field	`templates/fields/lookup-field.xml`
Master-Detail Field	`templates/fields/master-detail-field.xml`
Formula Field	`templates/fields/formula-field.xml`
Roll-Up Summary	`templates/fields/rollup-summary-field.xml`
Email Field	`templates/fields/email-field.xml`
Phone Field	`templates/fields/phone-field.xml`
URL Field	`templates/fields/url-field.xml`
Text Area (Long)	`templates/fields/textarea-field.xml`
Profile	`templates/profiles/profile.xml`
Permission Set	`templates/permission-sets/permission-set.xml`
Validation Rule	`templates/validation-rules/validation-rule.xml`
Record Type	`templates/record-types/record-type.xml`
Page Layout	`templates/layouts/page-layout.xml`

Template Path Resolution (try in order):

Marketplace folder:

~/.claude/plugins/marketplaces/sf-skills/sf-metadata/templates/[path]

Project folder:

[project-root]/sf-metadata/templates/[path]

Example:

Read: ~/.claude/plugins/marketplaces/sf-skills/sf-metadata/templates/objects/custom-object.xml

选择模板:

元数据类型	模板
Custom Object	`templates/objects/custom-object.xml`
Text Field	`templates/fields/text-field.xml`
Number Field	`templates/fields/number-field.xml`
Currency Field	`templates/fields/currency-field.xml`
Date Field	`templates/fields/date-field.xml`
Checkbox Field	`templates/fields/checkbox-field.xml`
Picklist Field	`templates/fields/picklist-field.xml`
Multi-Select Picklist	`templates/fields/multi-select-picklist.xml`
Lookup Field	`templates/fields/lookup-field.xml`
Master-Detail Field	`templates/fields/master-detail-field.xml`
Formula Field	`templates/fields/formula-field.xml`
Roll-Up Summary	`templates/fields/rollup-summary-field.xml`
Email Field	`templates/fields/email-field.xml`
Phone Field	`templates/fields/phone-field.xml`
URL Field	`templates/fields/url-field.xml`
Text Area (Long)	`templates/fields/textarea-field.xml`
Profile	`templates/profiles/profile.xml`
Permission Set	`templates/permission-sets/permission-set.xml`
Validation Rule	`templates/validation-rules/validation-rule.xml`
Record Type	`templates/record-types/record-type.xml`
Page Layout	`templates/layouts/page-layout.xml`

模板路径解析顺序:

市场文件夹:

~/.claude/plugins/marketplaces/sf-skills/sf-metadata/templates/[path]

项目文件夹:

[project-root]/sf-metadata/templates/[path]

示例:

Read: ~/.claude/plugins/marketplaces/sf-skills/sf-metadata/templates/objects/custom-object.xml

For Querying (sf CLI v2 Commands)

查询操作（sf CLI v2命令）

Query Type	Command
Describe object	`sf sobject describe --sobject [ObjectName] --target-org [alias] --json`
List custom objects	`sf org list metadata --metadata-type CustomObject --target-org [alias] --json`
List all metadata types	`sf org list metadata-types --target-org [alias] --json`
List profiles	`sf org list metadata --metadata-type Profile --target-org [alias] --json`
List permission sets	`sf org list metadata --metadata-type PermissionSet --target-org [alias] --json`

Present query results in structured format:

📊 Object: Account
════════════════════════════════════════

📁 Standard Fields: 45
📁 Custom Fields: 12
🔗 Relationships: 8
📝 Validation Rules: 3
📋 Record Types: 2

Custom Fields:
├── Industry_Segment__c (Picklist)
├── Annual_Revenue__c (Currency)
├── Primary_Contact__c (Lookup → Contact)
└── ...

查询类型	命令
描述对象	`sf sobject describe --sobject [ObjectName] --target-org [alias] --json`
列出自定义对象	`sf org list metadata --metadata-type CustomObject --target-org [alias] --json`
列出所有元数据类型	`sf org list metadata-types --target-org [alias] --json`
列出配置文件	`sf org list metadata --metadata-type Profile --target-org [alias] --json`
列出权限集	`sf org list metadata --metadata-type PermissionSet --target-org [alias] --json`

结构化展示查询结果:

📊 对象: Account
════════════════════════════════════════

📁 标准字段: 45
📁 自定义字段: 12
🔗 关系: 8
📝 验证规则: 3
📋 记录类型: 2

自定义字段:
├── Industry_Segment__c (Picklist)
├── Annual_Revenue__c (Currency)
├── Primary_Contact__c (Lookup → Contact)
└── ...

Phase 3: Generation / Validation

阶段3：生成 / 验证

For Generation:

Create metadata file in appropriate directory:

Objects:

force-app/main/default/objects/[ObjectName__c]/[ObjectName__c].object-meta.xml

Fields:

force-app/main/default/objects/[ObjectName]/fields/[FieldName__c].field-meta.xml

Profiles:

force-app/main/default/profiles/[ProfileName].profile-meta.xml

Permission Sets:

force-app/main/default/permissionsets/[PermSetName].permissionset-meta.xml

Validation Rules:

force-app/main/default/objects/[ObjectName]/validationRules/[RuleName].validationRule-meta.xml

Record Types:

force-app/main/default/objects/[ObjectName]/recordTypes/[RecordTypeName].recordType-meta.xml

Layouts:

force-app/main/default/layouts/[ObjectName]-[LayoutName].layout-meta.xml

Populate template with user requirements
Apply naming conventions (see
```
docs/naming-conventions.md
```
in sf-metadata folder)
Run validation (automatic via hooks or manual)

Validation Report Format (6-Category Scoring 0-120):

Score: 105/120 ⭐⭐⭐⭐ Very Good
├─ Structure & Format:  20/20 (100%)
├─ Naming Conventions:  18/20 (90%)
├─ Data Integrity:      15/20 (75%)
├─ Security & FLS:      20/20 (100%)
├─ Documentation:       18/20 (90%)
└─ Best Practices:      14/20 (70%)

Issues:
⚠️ [Naming] Field API name should use PascalCase: 'account_status__c' → 'Account_Status__c'
⚠️ [Best Practice] Consider using Global Value Set for reusable picklist

生成操作:

在对应目录创建元数据文件:

对象:

force-app/main/default/objects/[ObjectName__c]/[ObjectName__c].object-meta.xml

字段:

force-app/main/default/objects/[ObjectName]/fields/[FieldName__c].field-meta.xml

配置文件:

force-app/main/default/profiles/[ProfileName].profile-meta.xml

权限集:

force-app/main/default/permissionsets/[PermSetName].permissionset-meta.xml

验证规则:

force-app/main/default/objects/[ObjectName]/validationRules/[RuleName].validationRule-meta.xml

记录类型:

force-app/main/default/objects/[ObjectName]/recordTypes/[RecordTypeName].recordType-meta.xml

布局:

force-app/main/default/layouts/[ObjectName]-[LayoutName].layout-meta.xml

根据用户需求填充模板
应用命名规范（查看sf-metadata文件夹中的
```
docs/naming-conventions.md
```
）
运行验证（通过钩子自动执行或手动执行）

验证报告格式（6维度评分 0-120分）:

评分: 105/120 ⭐⭐⭐⭐ 优秀
├─ 结构与格式:  20/20 (100%)
├─ 命名规范:  18/20 (90%)
├─ 数据完整性:      15/20 (75%)
├─ 安全与FLS:      20/20 (100%)
├─ 文档:       18/20 (90%)
└─ 最佳实践:      14/20 (70%)

问题:
⚠️ [命名] 字段API名称应使用PascalCase: 'account_status__c' → 'Account_Status__c'
⚠️ [最佳实践] 考虑为可复用选择列表使用全局值集

Phase 3.5: Permission Set Auto-Generation (NEW)

阶段3.5：权限集自动生成（新增）

After creating Custom Objects or Fields, ALWAYS prompt the user:

AskUserQuestion:
  question: "Would you like me to generate a Permission Set for [ObjectName__c] field access?"
  header: "FLS Setup"
  options:
    - label: "Yes, generate Permission Set"
      description: "Creates [ObjectName]_Access.permissionset-meta.xml with object CRUD and field access"
    - label: "No, I'll handle FLS manually"
      description: "Skip Permission Set generation - you'll configure FLS via Setup or Profile"

If user selects "Yes":

Collect field information from created metadata
Filter out required fields (they are auto-visible, cannot be in Permission Sets)
Filter out formula fields (can only be readable, not editable)

Generate Permission Set at:

force-app/main/default/permissionsets/[ObjectName]_Access.permissionset-meta.xml

Permission Set Generation Rules:

Field Type	Include in Permission Set?	Notes
Required fields	❌ NO	Auto-visible, Salesforce rejects in Permission Set
Optional fields	✅ YES	Include with `editable: true, readable: true`
Formula fields	✅ YES	Include with `editable: false, readable: true`
Roll-Up Summary	✅ YES	Include with `editable: false, readable: true`
Master-Detail	❌ NO	Controlled by parent object permissions
Name field	❌ NO	Always visible, cannot be in Permission Set

Example Auto-Generated Permission Set:

xml

<?xml version="1.0" encoding="UTF-8"?>
<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Auto-generated: Grants access to Customer_Feedback__c and its fields</description>
    <hasActivationRequired>false</hasActivationRequired>
    <label>Customer Feedback Access</label>

    <objectPermissions>
        <allowCreate>true</allowCreate>
        <allowDelete>true</allowDelete>
        <allowEdit>true</allowEdit>
        <allowRead>true</allowRead>
        <modifyAllRecords>false</modifyAllRecords>
        <object>Customer_Feedback__c</object>
        <viewAllRecords>true</viewAllRecords>
    </objectPermissions>

    <!-- NOTE: Required fields are EXCLUDED (auto-visible) -->
    <!-- NOTE: Formula fields have editable=false -->

    <fieldPermissions>
        <editable>true</editable>
        <field>Customer_Feedback__c.Optional_Field__c</field>
        <readable>true</readable>
    </fieldPermissions>
</PermissionSet>

创建自定义对象或字段后，务必向用户提示：

AskUserQuestion:
  question: "是否需要为[ObjectName__c]生成字段访问权限集？"
  header: "FLS设置"
  options:
    - label: "是，生成权限集"
      description: "创建[ObjectName]_Access.permissionset-meta.xml，包含对象CRUD和字段访问权限"
    - label: "否，我将手动配置FLS"
      description: "跳过权限集生成 - 您将通过Setup或配置文件配置FLS"

若用户选择“是”：

从已创建的元数据中收集字段信息
过滤掉必填字段（这些字段自动可见，无法添加到权限集）
过滤掉公式字段（仅可设置为可读，不可编辑）

生成权限集，路径为:

force-app/main/default/permissionsets/[ObjectName]_Access.permissionset-meta.xml

权限集生成规则:

字段类型	是否包含在权限集中？	说明
必填字段	❌ 否	自动可见，Salesforce会拒绝将其加入权限集
可选字段	✅ 是	配置为 `editable: true, readable: true`
公式字段	✅ 是	配置为 `editable: false, readable: true`
汇总字段	✅ 是	配置为 `editable: false, readable: true`
Master-Detail	❌ 否	由父对象权限控制
名称字段	❌ 否	始终可见，无法添加到权限集

自动生成的权限集示例:

xml

<?xml version="1.0" encoding="UTF-8"?>
<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Auto-generated: Grants access to Customer_Feedback__c and its fields</description>
    <hasActivationRequired>false</hasActivationRequired>
    <label>Customer Feedback Access</label>

    <objectPermissions>
        <allowCreate>true</allowCreate>
        <allowDelete>true</allowDelete>
        <allowEdit>true</allowEdit>
        <allowRead>true</allowRead>
        <modifyAllRecords>false</modifyAllRecords>
        <object>Customer_Feedback__c</object>
        <viewAllRecords>true</viewAllRecords>
    </objectPermissions>

    <!-- NOTE: Required fields are EXCLUDED (auto-visible) -->
    <!-- NOTE: Formula fields have editable=false -->

    <fieldPermissions>
        <editable>true</editable>
        <field>Customer_Feedback__c.Optional_Field__c</field>
        <readable>true</readable>
    </fieldPermissions>
</PermissionSet>

Phase 4: Deployment

阶段4：部署

Skill(skill="sf-deploy", args="Deploy metadata at force-app/main/default/objects/[ObjectName] and permission set to [target-org]")

Post-deployment (optional - assign permission set):

bash

sf org assign permset --name [ObjectName]_Access --target-org [alias]

Skill(skill="sf-deploy", args="Deploy metadata at force-app/main/default/objects/[ObjectName] and permission set to [target-org]")

部署后（可选 - 分配权限集）:

bash

sf org assign permset --name [ObjectName]_Access --target-org [alias]

Phase 5: Verification

阶段5：验证

For Generated Metadata:

✓ Metadata Complete: [MetadataName]
  Type: [CustomObject/CustomField/Profile/etc.] | API: 65.0
  Location: force-app/main/default/[path]
  Validation: PASSED (Score: XX/120)

Next Steps:
  1. Verify in Setup → Object Manager → [Object]
  2. Check Field-Level Security for new fields
  3. Add to Page Layouts if needed

For Queries:

Present results in structured format
Highlight relevant information
Offer follow-up actions (create field, modify permissions, etc.)

生成的元数据验证:

✓ 元数据已完成: [MetadataName]
  类型: [CustomObject/CustomField/Profile/etc.] | API: 65.0
  位置: force-app/main/default/[path]
  验证: 通过（评分: XX/120）

后续步骤:
  1. 在Setup → Object Manager → [Object]中验证
  2. 检查新字段的字段级安全设置
  3. 如有需要，添加到页面布局

查询结果验证:

以结构化格式展示结果
突出显示相关信息
提供后续操作选项（创建字段、修改权限等）

Best Practices (Built-In Enforcement)

最佳实践（内置强制校验）

Critical Requirements

关键要求

Structure & Format (20 points):

Valid XML syntax (-10 if invalid)
Correct Salesforce namespace:
```
http://soap.sforce.com/2006/04/metadata
```
(-5 if missing)
API version present and >= 65.0 (-5 if outdated)
Correct file path and naming structure (-5 if wrong)

Naming Conventions (20 points):

Custom objects/fields end with
```
__c
```
(-3 each violation)
Use PascalCase for API names:
```
Account_Status__c
```
not
```
account_status__c
```
(-2 each)
Meaningful labels (no abbreviations like
```
Acct
```
,
```
Sts
```
) (-2 each)
Relationship names follow pattern:
```
[ParentObject]_[ChildObjects]
```
(-3)

Data Integrity (20 points):

Required fields have sensible defaults or validation (-5)
Number fields have appropriate precision/scale (-3)
Picklist values properly defined with labels (-3)
Relationship delete constraints specified (SetNull, Restrict, Cascade) (-3)
Formula field syntax valid (-5)
Roll-up summaries reference correct fields (-3)

Security & FLS (20 points):

Field-Level Security considerations documented (-5 if sensitive field exposed)
Sensitive field types flagged (SSN patterns, Credit Card patterns) (-10)
Object sharing model appropriate for data sensitivity (-5)
Permission Sets preferred over Profile modifications (advisory)

Documentation (20 points):

Description present and meaningful on objects/fields (-5 if missing)
Help text for user-facing fields (-3 each)
Clear error messages for validation rules (-3)
Inline comments in complex formulas (-3)

Best Practices (20 points):

Use Permission Sets over Profiles when possible (-3 if Profile-first)
Avoid hardcoded Record IDs in formulas (-5 if found)
Use Global Value Sets for reusable picklists (advisory)
Master-Detail vs Lookup selection appropriate for use case (-3)
Record Types have associated Page Layouts (-3)

结构与格式（20分）:

有效的XML语法（无效则扣10分）
正确的Salesforce命名空间:
```
http://soap.sforce.com/2006/04/metadata
```
（缺失则扣5分）
API版本存在且≥65.0（版本过时则扣5分）
正确的文件路径和命名结构（错误则扣5分）

命名规范（20分）:

自定义对象/字段以
```
__c
```
结尾（每违反一个扣3分）
API名称使用PascalCase:
```
Account_Status__c
```
而非
```
account_status__c
```
（每违反一个扣2分）
有意义的标签（避免使用
```
Acct
```
、
```
Sts
```
等缩写）（每违反一个扣2分）
关系名称遵循
```
[ParentObject]_[ChildObjects]
```
模式（违反则扣3分）

数据完整性（20分）:

必填字段有合理的默认值或验证（缺失则扣5分）
数字字段有合适的精度/小数位数（不合适则扣3分）
选择列表值已正确定义标签（未定义则扣3分）
关系删除约束已指定（SetNull、Restrict、Cascade）（未指定则扣3分）
公式字段语法有效（无效则扣5分）
汇总字段引用正确的字段（引用错误则扣3分）

安全与FLS（20分）:

已记录字段级安全考虑（敏感字段暴露则扣5分）
已标记敏感字段类型（如SSN格式、信用卡格式）（未标记则扣10分）
对象共享模型与数据敏感性匹配（不匹配则扣5分）
优先使用权限集而非修改配置文件（建议项）

文档（20分）:

对象/字段存在有意义的描述（缺失则扣5分）
面向用户的字段有帮助文本（每缺失一个扣3分）
验证规则有清晰的错误提示（缺失则扣3分）
复杂公式中有行内注释（缺失则扣3分）

最佳实践（20分）:

尽可能使用权限集而非配置文件（若优先修改配置文件则扣3分）
公式中避免硬编码记录ID（存在则扣5分）
为可复用选择列表使用全局值集（建议项）
Master-Detail与Lookup的选择符合使用场景（选择错误则扣3分）
记录类型已关联页面布局（未关联则扣3分）

Scoring

评分阈值

Thresholds: ⭐⭐⭐⭐⭐ 108+ | ⭐⭐⭐⭐ 96-107 | ⭐⭐⭐ 84-95 | Block: <72

阈值: ⭐⭐⭐⭐⭐ 108+ | ⭐⭐⭐⭐ 96-107 | ⭐⭐⭐ 84-95 | 阻止部署: <72

Field Template Tips

字段模板技巧

Number Field: Omit Empty Defaults

数字字段：省略空默认值

⚠️ Don't include
<defaultValue>
if it's empty or zero - Salesforce ignores it:

xml

<!-- ❌ WRONG: Empty default is ignored, adds noise -->
<CustomField>
    <fullName>Score__c</fullName>
    <type>Number</type>
    <precision>3</precision>
    <scale>0</scale>
    <defaultValue></defaultValue>  <!-- Remove this! -->
</CustomField>

<!-- ✅ CORRECT: Omit defaultValue entirely if not needed -->
<CustomField>
    <fullName>Score__c</fullName>
    <type>Number</type>
    <precision>3</precision>
    <scale>0</scale>
</CustomField>

<!-- ✅ CORRECT: Include defaultValue only if you need a specific value -->
<CustomField>
    <fullName>Priority__c</fullName>
    <type>Number</type>
    <precision>1</precision>
    <scale>0</scale>
    <defaultValue>3</defaultValue>  <!-- Meaningful default -->
</CustomField>

⚠️ 若默认值为空或0，请勿包含
<defaultValue>
- Salesforce会忽略它:

xml

<!-- ❌ 错误：空默认值会被忽略，增加冗余 -->
<CustomField>
    <fullName>Score__c</fullName>
    <type>Number</type>
    <precision>3</precision>
    <scale>0</scale>
    <defaultValue></defaultValue>  <!-- 移除这一行！ -->
</CustomField>

<!-- ✅ 正确：不需要时完全省略defaultValue -->
<CustomField>
    <fullName>Score__c</fullName>
    <type>Number</type>
    <precision>3</precision>
    <scale>0</scale>
</CustomField>

<!-- ✅ 正确：仅在需要特定值时包含defaultValue -->
<CustomField>
    <fullName>Priority__c</fullName>
    <type>Number</type>
    <precision>1</precision>
    <scale>0</scale>
    <defaultValue>3</defaultValue>  <!-- 有意义的默认值 -->
</CustomField>

Standard vs Custom Object Paths

标准对象与自定义对象路径差异

⚠️ Standard objects use different path than custom objects:

Object Type	Path Example
Standard (Lead)	`objects/Lead/fields/Lead_Score__c.field-meta.xml`
Custom	`objects/MyObject__c/fields/MyField__c.field-meta.xml`

Common Mistake: Using

Lead__c

(with suffix) for standard Lead object.

⚠️ 标准对象与自定义对象的路径不同:

对象类型	路径示例
标准对象(Lead)	`objects/Lead/fields/Lead_Score__c.field-meta.xml`
自定义对象	`objects/MyObject__c/fields/MyField__c.field-meta.xml`

常见错误: 为标准Lead对象使用

Lead__c

（带后缀）。

Field Type Selection Guide

字段类型选择指南

Type	Salesforce	Notes
Text	Text / Text Area (Long/Rich)	≤255 chars / multi-line / HTML
Numbers	Number / Currency	Decimals or money (org currency)
Boolean	Checkbox	True/False
Choice	Picklist / Multi-Select	Single/multiple predefined options
Date	Date / DateTime	With or without time
Contact	Email / Phone / URL	Validated formats
Relationship	Lookup / Master-Detail	Optional / required parent
Calculated	Formula / Roll-Up	Derived from fields / children

类型	Salesforce对应类型	说明
Text	Text / Text Area (Long/Rich)	≤255字符 / 多行 / HTML格式
Numbers	Number / Currency	小数或货币（组织本位币）
Boolean	Checkbox	是/否
Choice	Picklist / Multi-Select	单/多预定义选项
Date	Date / DateTime	带或不带时间
Contact	Email / Phone / URL	已验证格式
Relationship	Lookup / Master-Detail	可选/必填父对象
Calculated	Formula / Roll-Up	从其他字段/子对象派生

Relationship Decision Matrix

关系决策矩阵

Scenario	Use	Reason
Parent optional	Lookup	Child can exist without parent
Parent required	Master-Detail	Cascade delete, roll-up summaries
Many-to-Many	Junction Object	Two Master-Detail relationships
Self-referential	Hierarchical Lookup	Same object (e.g., Account hierarchy)
Cross-object formula	Master-Detail or Formula	Access parent fields

场景	使用	原因
父对象可选	Lookup	子对象可独立于父对象存在
父对象必填	Master-Detail	级联删除、汇总字段支持
多对多	关联对象	两个Master-Detail关系
自引用	层级Lookup	同一对象（如Account层级）
跨对象公式	Master-Detail或Formula	访问父对象字段

Common Validation Rule Patterns

常见验证规则模式

Pattern	Formula	Use
Conditional Required	`AND(ISPICKVAL(Status,'Closed'), ISBLANK(Close_Date__c))`	Field required when condition met
Email Regex	`NOT(REGEX(Email__c, "^[a-zA-Z0-9._-]+@..."))`	Format validation
Future Date	`Due_Date__c < TODAY()`	Date constraints
Cross-Object	`AND(Account.Type != 'Customer', Amount__c > 100000)`	Related field checks

模式	公式	用途
条件必填	`AND(ISPICKVAL(Status,'Closed'), ISBLANK(Close_Date__c))`	满足条件时字段必填
邮箱正则	`NOT(REGEX(Email__c, "^[a-zA-Z0-9._-]+@..."))`	格式验证
未来日期	`Due_Date__c < TODAY()`	日期约束
跨对象	`AND(Account.Type != 'Customer', Amount__c > 100000)`	关联字段检查

Cross-Skill Integration

跨技能集成

From Skill	To sf-metadata	When
sf-apex	→ sf-metadata	"Describe Invoice__c" (discover fields before coding)
sf-flow	→ sf-metadata	"Describe object fields, record types, validation rules"
sf-data	→ sf-metadata	"Describe Custom_Object__c fields" (discover structure)

From sf-metadata	To Skill	When
sf-metadata	→ sf-deploy	"Deploy with --dry-run" (validate & deploy metadata)
sf-metadata	→ sf-flow	After creating objects/fields that Flow will reference

来源技能	目标sf-metadata	触发场景
sf-apex	→ sf-metadata	"描述Invoice__c"（编码前发现字段）
sf-flow	→ sf-metadata	"描述对象字段、记录类型、验证规则"
sf-data	→ sf-metadata	"描述Custom_Object__c字段"（发现结构）

来源sf-metadata	目标技能	触发场景
sf-metadata	→ sf-deploy	"使用--dry-run部署"（验证并部署元数据）
sf-metadata	→ sf-flow	创建Flow将引用的对象/字段后

Metadata Anti-Patterns

元数据反模式

Anti-Pattern	Fix
Profile-based FLS	Use Permission Sets for granular access
Hardcoded IDs in formulas	Use Custom Settings or Custom Metadata
Validation rule without bypass	Add `$Permission.Bypass_Validation__c` check
Too many picklist values (>200)	Consider Custom Object instead
Auto-number without prefix	Add meaningful prefix: `INV-{0000}`
Roll-up on non-M-D	Use trigger-based calculation or DLRS
Field label = API name	Use user-friendly labels
No description on custom objects	Always document purpose

反模式	修复方案
基于配置文件的FLS	使用权限集实现细粒度访问控制
公式中硬编码ID	使用自定义设置或自定义元数据
无绕过机制的验证规则	添加 `$Permission.Bypass_Validation__c` 检查
选择列表值过多(>200)	考虑使用自定义对象替代
无前缀的自动编号	添加有意义的前缀: `INV-{0000}`
非Master-Detail关系的汇总	使用触发器计算或DLRS
字段标签与API名称相同	使用用户友好的标签
自定义对象无描述	务必记录用途

sf CLI Quick Reference

sf CLI速查手册

Object & Field Queries

对象与字段查询

bash

undefined

bash

undefined

Describe standard or custom object

描述标准或自定义对象

sf sobject describe --sobject Account --target-org [alias] --json

List all custom objects

列出所有自定义对象

sf org list metadata --metadata-type CustomObject --target-org [alias] --json

List all custom fields on an object

列出对象的所有自定义字段

sf org list metadata --metadata-type CustomField --folder Account --target-org [alias] --json

undefined

sf org list metadata --metadata-type CustomField --folder Account --target-org [alias] --json

undefined

Metadata Operations

元数据操作

bash

undefined

bash

undefined

List all metadata types available

列出所有可用元数据类型

sf org list metadata-types --target-org [alias] --json

Retrieve specific metadata

检索特定元数据

sf project retrieve start --metadata CustomObject:Account --target-org [alias]

Generate package.xml from source

从源码生成package.xml

sf project generate manifest --source-dir force-app --name package.xml

undefined

sf project generate manifest --source-dir force-app --name package.xml

undefined

Interactive Generation

交互式生成

bash

undefined

bash

undefined

Generate custom object interactively

交互式生成自定义对象

sf schema generate sobject --label "My Object"

Generate custom field interactively

交互式生成自定义字段

sf schema generate field --label "My Field" --object Account

---

sf schema generate field --label "My Field" --object Account

---

Reference & Dependencies

参考文档与依赖

Docs:

docs/

folder (in sf-metadata) - metadata-types-reference, field-types-guide, fls-best-practices, naming-conventions

Path:

~/.claude/plugins/marketplaces/sf-skills/sf-metadata/docs/

Dependencies: sf-deploy (optional) for deployment. Install:

/plugin install github:Jaganpro/sf-skills/sf-deploy

Notes: API 65.0 required | Permission Sets over Profiles | Block if score < 72

文档: sf-metadata中的

docs/

文件夹 - 元数据类型参考、字段类型指南、FLS最佳实践、命名规范

路径:

~/.claude/plugins/marketplaces/sf-skills/sf-metadata/docs/

依赖: 部署可选用sf-deploy。安装命令:

/plugin install github:Jaganpro/sf-skills/sf-deploy

注意: 要求API 65.0 | 优先使用权限集而非配置文件 | 评分<72时阻止部署

Validation

验证

Manual validation (if hooks don't fire):

bash

python3 ~/.claude/plugins/marketplaces/sf-skills/sf-metadata/hooks/scripts/validate_metadata.py <file_path>

Scoring: 120 points / 6 categories. Minimum 84 (70%) for deployment.

Hooks not firing? Check:

CLAUDE_PLUGIN_ROOT

set, hooks.json valid, Python 3 in PATH, file matches pattern.

手动验证（若钩子未触发）:

bash

python3 ~/.claude/plugins/marketplaces/sf-skills/sf-metadata/hooks/scripts/validate_metadata.py <file_path>

评分: 120分制，6个维度。部署最低要求84分（70%）。

钩子未触发？ 检查:

CLAUDE_PLUGIN_ROOT

已设置、hooks.json有效、Python 3在PATH中、文件匹配规则。

🔑 Key Insights

🔑 关键要点

Insight	Issue	Fix
FLS is the Silent Killer	Deployed fields invisible without FLS	Always prompt for Permission Set generation
Required Fields ≠ Permission Sets	Salesforce rejects required fields in PS	Filter out required fields from fieldPermissions
Orchestration Order	sf-data fails if objects not deployed	sf-metadata → sf-flow → sf-deploy → sf-data
Before-Save Efficiency	Before-Save auto-saves, no DML needed	Use Before-Save for same-record updates
Test with 251 Records	Batch boundary at 200 records	Always bulk test with 251+ records

要点	问题	修复方案
FLS是隐形陷阱	部署后的字段无FLS则不可见	务必提示生成权限集
必填字段≠权限集	Salesforce会拒绝将必填字段加入权限集	从fieldPermissions中过滤必填字段
编排顺序	若未部署对象，sf-data会失败	遵循sf-metadata → sf-flow → sf-deploy → sf-data顺序
Before-Save效率	Before-Save自动保存，无需DML	对同记录更新使用Before-Save
用251条记录测试	批处理边界为200条记录	始终用251+条记录进行批量测试

Common Errors

常见错误

Error	Fix
`Cannot deploy to required field`	Remove from fieldPermissions (auto-visible)
`Field does not exist`	Create Permission Set with field access
`SObject type 'X' not supported`	Deploy metadata first
`Element X is duplicated`	Reorder XML elements alphabetically

错误	修复方案
`Cannot deploy to required field`	从fieldPermissions中移除（自动可见）
`Field does not exist`	创建包含字段访问权限的权限集
`SObject type 'X' not supported`	先部署元数据
`Element X is duplicated`	按字母顺序重新排列XML元素