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技能部署元数据

Document Map

文档目录

Need	Document	Description
PermSet auto-gen	references/permset-auto-generation.md	Phase 3.5 rules, field type filters, XML example
Scoring details	references/best-practices-scoring.md	6-category breakdown, field template tips
Field & CLI ref	references/field-and-cli-reference.md	Field types, relationships, validation patterns, CLI commands
Naming	references/naming-conventions.md	API name conventions
Orchestration	references/orchestration.md	Extended orchestration patterns

需求	文档	描述
权限集自动生成	references/permset-auto-generation.md	3.5阶段规则、字段类型过滤器、XML示例
评分详情	references/best-practices-scoring.md	6个维度细分、字段模板技巧
字段与CLI参考	references/field-and-cli-reference.md	字段类型、关系、验证模式、CLI命令
命名规范	references/naming-conventions.md	API命名规范
编排流程	references/orchestration.md	扩展编排模式

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.

sf-metadata → sf-flow → sf-deploy → sf-data（当前处于：sf-metadata）

sf-data要求对象已部署到组织中。请始终先部署元数据，再创建测试数据。

CRITICAL: Field-Level Security

重要提示：字段级安全（FLS）

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

部署后的字段在配置FLS前是不可见的！ 创建对象/字段后，务必提示生成权限集。请查看references/permset-auto-generation.md了解自动生成流程。

Workflow (5-Phase Pattern)

工作流（5阶段模式）

Phase 1: Requirements Gathering

阶段1：需求收集

Ask the user to gather:

Operation type: Generate metadata OR Query org metadata
If generating: Metadata type, target object, specific requirements
If querying: Query type, target org alias, object name or metadata type

Then: Check existing metadata (

Glob: **/*-meta.xml

), verify sfdx-project.json exists.

询问用户以下信息：

操作类型：生成元数据或查询组织元数据
若为生成：元数据类型、目标对象、具体需求
若为查询：查询类型、目标组织别名、对象名称或元数据类型

随后：检查现有元数据（

Glob: **/*-meta.xml

），确认sfdx-project.json已存在。

Phase 2: Template Selection / Query Execution

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

For Generation

生成场景

Metadata Type	Template
Custom Object	`assets/objects/custom-object.xml`
Text/Number/Currency/Date/Checkbox Field	`assets/fields/[type]-field.xml`
Picklist / Multi-Select Picklist	`assets/fields/picklist-field.xml` / `multi-select-picklist.xml`
Lookup / Master-Detail	`assets/fields/lookup-field.xml` / `master-detail-field.xml`
Formula / Roll-Up Summary	`assets/fields/formula-field.xml` / `rollup-summary-field.xml`
Email/Phone/URL/Text Area	`assets/fields/[type]-field.xml`
Profile / Permission Set	`assets/profiles/profile.xml` / `assets/permission-sets/permission-set.xml`
Validation Rule / Record Type / Layout	`assets/[type]/`

Template Path Resolution (try in order):

Marketplace:

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

Project:

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

元数据类型	模板
自定义对象	`assets/objects/custom-object.xml`
文本/数字/货币/日期/复选框字段	`assets/fields/[type]-field.xml`
选择列表 / 多选选择列表	`assets/fields/picklist-field.xml` / `multi-select-picklist.xml`
查找关系 / 主明细关系	`assets/fields/lookup-field.xml` / `master-detail-field.xml`
公式 / 汇总字段	`assets/fields/formula-field.xml` / `rollup-summary-field.xml`
邮箱/电话/URL/文本区域	`assets/fields/[type]-field.xml`
配置文件 / 权限集	`assets/profiles/profile.xml` / `assets/permission-sets/permission-set.xml`
验证规则 / 记录类型 / 页面布局	`assets/[type]/`

模板路径解析顺序（按优先级尝试）：

应用市场：

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

项目目录：

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

For Querying (sf CLI v2)

查询场景（sf CLI v2）

Query Type Command

Describe object

Query Type	Command
Describe object	`sf sobject describe --sobject [Name] --target-org [alias] --json`
List custom objects	`sf org list metadata --metadata-type CustomObject --target-org [alias] --json`
List metadata types	`sf org list metadata-types --target-org [alias] --json`

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

List custom objects

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

List metadata types

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

See references/field-and-cli-reference.md for complete CLI commands and interactive generation.

查询类型命令

描述对象

查询类型	命令
描述对象	`sf sobject describe --sobject [Name] --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 sobject describe --sobject [Name] --target-org [alias] --json

列出自定义对象

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

列出元数据类型

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

完整CLI命令和交互式生成请查看references/field-and-cli-reference.md。

Phase 3: Generation / Validation

阶段3：生成 / 验证

File locations:

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

Permission Sets:

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

Validation Rules:

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

Validation Report Format:

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%)

See references/best-practices-scoring.md for detailed category breakdowns and field template tips.

文件存储位置：

对象：

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/permissionsets/[PermSetName].permissionset-meta.xml

验证规则：

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

验证报告格式：

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%)

详细的维度划分和字段模板技巧请查看references/best-practices-scoring.md。

Phase 3.5: Permission Set Auto-Generation

阶段3.5：权限集自动生成

See references/permset-auto-generation.md for the complete workflow, field type rules, and XML template.

Quick rules: Exclude required fields (auto-visible) and Name fields. Formula/Roll-Up fields get

editable: false

. Master-Detail controlled by parent.

完整工作流、字段类型规则和XML模板请查看references/permset-auto-generation.md。

快速规则：排除必填字段（自动可见）和名称字段。公式/汇总字段设置

editable: false

。主明细字段权限由父对象控制。

Phase 4: Deployment

阶段4：部署

Use the sf-deploy skill: "Deploy metadata at force-app/main/default/objects/[ObjectName] to [target-org]"

Post-deployment:

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

使用sf-deploy技能："Deploy metadata at force-app/main/default/objects/[ObjectName] to [target-org]"

部署后执行：

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

Phase 5: Verification

阶段5：验证

Verify in Setup → Object Manager, check FLS for new fields, add to Page Layouts if needed.

在Setup → Object Manager中验证，检查新字段的FLS配置，必要时添加到页面布局。

Scoring (120 Points)

评分机制（120分）

See references/best-practices-scoring.md for full criteria.

Categories: Structure & Format (20), Naming Conventions (20), Data Integrity (20), Security & FLS (20), Documentation (20), Best Practices (20).

Thresholds: 108+ Excellent | 96+ Good | 84+ Acceptable | <72 BLOCKED

完整评分标准请查看references/best-practices-scoring.md。

评分维度：结构与格式（20分）、命名规范（20分）、数据完整性（20分）、安全与FLS（20分）、文档（20分）、最佳实践（20分）。

评分阈值：108分及以上优秀 | 96分及以上良好 | 84分及以上合格 | 低于72分阻止部署

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"
sf-metadata	→ sf-flow	After creating objects/fields that Flow will reference

来源技能	目标技能sf-metadata	触发场景
sf-apex	→ sf-metadata	"Describe Invoice__c"（编码前发现字段）
sf-flow	→ sf-metadata	"Describe object fields, record types, validation rules"
sf-data	→ sf-metadata	"Describe Custom_Object__c fields"（发现结构）

来源技能sf-metadata	目标技能	触发场景
sf-metadata	→ sf-deploy	"Deploy with --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}`
No description on custom objects	Always document purpose

反模式	修复方案
基于配置文件的FLS	使用权限集实现细粒度访问控制
公式中硬编码ID	使用自定义设置或自定义元数据
无绕过机制的验证规则	添加 `$Permission.Bypass_Validation__c` 检查
选择列表值过多（>200个）	考虑使用自定义对象替代
无前缀的自动编号	添加有意义的前缀： `INV-{0000}`
自定义对象无描述	始终添加用途说明

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

要点	问题	修复方案
FLS是隐形陷阱	部署后的字段未配置FLS则不可见	创建对象/字段后务必提示生成权限集
必填字段≠权限集	Salesforce拒绝在权限集中包含必填字段	从fieldPermissions中过滤掉必填字段
编排顺序	若对象未部署，sf-data会执行失败	遵循sf-metadata → sf-flow → sf-deploy → sf-data的顺序

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元素

Validation

验证命令

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.

bash

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

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

Dependencies

依赖项

Docs:

references/

folder — metadata-types-reference, field-types-guide, fls-best-practices, naming-conventions Required: sf-deploy (optional) for deployment | API 65.0 | Block if score < 72

文档：

references/

文件夹 — 元数据类型参考、字段类型指南、FLS最佳实践、命名规范 必要依赖：sf-deploy（部署可选）| API 65.0 | 若评分低于72分则阻止部署