sf-datacloud-metadata-agentic
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinesesf-datacloud-metadata-agentic
sf-datacloud-metadata-agentic
Use this skill for the metadata and agentic semantics plane.
Beast references:
- Beast preflight: docs/beast-preflight.md
- Phase proof matrix: docs/phase-proof-matrix.json
- Public operating model: docs/operating-model.md
- Data 360 model-gallery implementation map: docs/data360/model-gallery-implementation-map.md
- RAG/search-index playbook: docs/data360/rag-search-index-retriever-playbook.md
- Developer Guide index: docs/data360/developer/index.md
- Developer Guide synthesis: docs/data360/developer/skill-update-synthesis.md
- Proof ledger: docs/proof-ledger.md
- Public LLM map: docs/llms.txt
- Limits source precedence: docs/data360/limits-source-precedence.md
- For exact Salesforce behavior, fetch official Help/Developer docs on demand with .
sf-docs - For endpoint shape, use OpenAPI from the official spec or the user-supplied Swagger before writing payloads.
Static scoring utility:
bash
python3 skills/sf-datacloud-metadata-agentic/scripts/metadata_semantic_score.py metadata.json本技能适用于元数据与Agentic语义层面。
参考文档:
- Beast预检查:docs/beast-preflight.md
- 阶段验证矩阵:docs/phase-proof-matrix.json
- 公开运营模型:docs/operating-model.md
- Data 360模型库实现映射:docs/data360/model-gallery-implementation-map.md
- RAG/搜索索引手册:docs/data360/rag-search-index-retriever-playbook.md
- 开发者指南索引:docs/data360/developer/index.md
- 开发者指南综合内容:docs/data360/developer/skill-update-synthesis.md
- 验证台账:docs/proof-ledger.md
- 公开LLM映射:docs/llms.txt
- 限制源优先级:docs/data360/limits-source-precedence.md
- 如需了解Salesforce确切行为,使用按需获取官方帮助/开发者文档。
sf-docs - 编写请求 payload 前,优先使用官方规范中的OpenAPI或用户提供的Swagger来确定端点格式。
静态评分工具:
bash
python3 skills/sf-datacloud-metadata-agentic/scripts/metadata_semantic_score.py metadata.jsonMetadata API Surfaces
元数据API接口
Prefer official Data 360 metadata surfaces before guessing:
GET /ssot/metadataGET /ssot/profile/metadataGET /ssot/profile/metadata/:dataModelNameGET /ssot/insight/metadataGET /ssot/insight/metadata/:ciNameGET /ssot/data-graphs/metadata- data model object and relationship metadata from Connect API
- Apex metadata methods where available
ConnectApi.CdpQuery - Metadata API for supported Data 360 metadata movement
- data kit metadata and packageability readback for deployable Data 360 assets
优先使用官方Data 360元数据接口,避免自行猜测:
GET /ssot/metadataGET /ssot/profile/metadataGET /ssot/profile/metadata/:dataModelNameGET /ssot/insight/metadataGET /ssot/insight/metadata/:ciNameGET /ssot/data-graphs/metadata- 来自Connect API的数据模型对象和关系元数据
- 可用的Apex 元数据方法
ConnectApi.CdpQuery - 用于支持Data 360元数据迁移的Metadata API
- 可部署Data 360资产的数据套件元数据与可打包性回读
Data Kits And Packageability
数据套件与可打包性
- Data kits are the core packaging/deploy abstraction for Data 360 metadata. They package definitions, not raw data.
- Verify current Metadata Coverage and the Data 360 metadata component cheat sheet before promising packageability.
- Data 360 metadata and Salesforce Platform metadata should be planned as separate package tracks unless current docs explicitly support the combined target.
- For sandbox-to-production movement, check DevOps data kit membership,
downloaded , retrieved metadata files, matching data space prefixes, and connector reauthorization requirements.
package.xml - Watch deployment failures involving missing metadata, generated key qualifier files, and inactive connectors after deployment.
FieldSrcTrgtRelationship
- 数据套件是Data 360元数据的核心打包/部署抽象。它们打包的是定义,而非原始数据。
- 在承诺可打包性之前,请验证当前的元数据覆盖范围和Data 360元数据组件速查表。
- 除非当前文档明确支持组合目标,否则应将Data 360元数据与Salesforce平台元数据规划为单独的包跟踪。
- 对于沙箱到生产环境的迁移,请检查DevOps数据套件成员、下载的、检索到的元数据文件、匹配的数据空间前缀以及连接器重新授权要求。
package.xml - 注意涉及缺失元数据、生成的键限定符文件以及部署后连接器失效的部署失败情况。
FieldSrcTrgtRelationship
Agentic Metadata Goals
Agentic元数据目标
Prepare metadata so an agent can:
- map a business phrase to the right public Data 360 model-gallery subject area and anchor DMO before writing SQL or creating a graph
- identify the right object for a business concept
- distinguish similar fields without hallucinating
- understand grain, cardinality, freshness, and governance limits
- choose between DMO, CIO, Data Graph, semantic metric, or search retriever
- understand whether an answer should use query, semantic model, Data Graph, or retriever grounding
- understand which fields are index, prepend, filter, return, ranking, or agent-safe citation fields in a RAG design
- explain results using business language without exposing PII
- know when a metric is authoritative vs exploratory
准备元数据,使Agent能够:
- 将业务短语映射到正确的公开Data 360模型库主题领域,并在编写SQL或创建图谱前锚定DMO
- 为业务概念识别正确的对象
- 区分相似字段,避免幻觉
- 理解粒度、基数、新鲜度和治理限制
- 在DMO、CIO、数据图谱、语义指标或搜索检索器之间做出选择
- 理解答案应使用查询、语义模型、数据图谱还是检索器落地
- 理解在RAG设计中哪些字段是索引、前置、过滤、返回、排序或Agent安全引用字段
- 使用业务语言解释结果,不暴露PII
- 了解指标是权威的还是探索性的
Production Metadata Workflow
生产级元数据工作流
- Inventory data spaces, DMOs, CIOs, data graphs, semantic models, and search indexes.
- Classify every object:
- profile, engagement, other, unified, calculated insight, data graph, semantic view, unstructured chunk/index
- Add or improve object descriptions:
- business purpose
- grain
- owner
- refresh cadence
- permitted consumers
- PII/sensitivity notes
- tags, classifications, masking policy, and agent-safe output status
- Add or improve field descriptions:
- plain-English meaning
- valid values or units
- null semantics
- source system
- join/key behavior
- whether safe for agent output
- whether the field is join-only, activation-only, restricted, masked, or governed by RLS/FLS
- Add relationship semantics:
- one-to-one, one-to-many, many-to-many
- parent/child role
- join key and source of truth
- fanout risk
- Add metric semantics:
- formula
- dimensions
- aggregatability
- time window
- owner and validation source
- Generate an agent-safe metadata summary for prompts, Agentforce instructions, Data Graph descriptions, retriever descriptions, and action parameter descriptions.
- For deployable assets, verify data kit membership, packageability, metadata coverage, and target-org deployment prerequisites.
- Validate with agent tests that require the agent to choose the correct object/metric without being shown table names in the user prompt.
- 盘点数据空间、DMO、CIO、数据图谱、语义模型和搜索索引。
- 对每个对象进行分类:
- 档案、互动、其他、统一、计算洞察、数据图谱、语义视图、非结构化块/索引
- 添加或改进对象描述:
- 业务用途
- 粒度
- 所有者
- 刷新频率
- 允许的使用者
- PII/敏感性说明
- 标签、分类、掩码策略和Agent安全输出状态
- 添加或改进字段描述:
- 通俗易懂的含义
- 有效值或单位
- 空值语义
- 源系统
- 关联/键行为
- 是否适合Agent输出
- 字段是否仅用于关联、仅用于激活、受限、掩码或受RLS/FLS治理
- 添加关系语义:
- 一对一、一对多、多对多
- 父/子角色
- 关联键和事实来源
- 扇出风险
- 添加指标语义:
- 公式
- 维度
- 可聚合性
- 时间窗口
- 所有者和验证来源
- 生成Agent安全的元数据摘要,用于提示词、Agentforce指令、数据图谱描述、检索器描述和动作参数描述。
- 对于可部署资产,验证数据套件成员资格、可打包性、元数据覆盖范围和目标组织部署先决条件。
- 通过Agent测试验证,要求Agent在用户提示中未显示表名的情况下选择正确的对象/指标。
Description Quality Rubric
描述质量评分标准
Score metadata from 0-5:
- 0: missing or source-system jargon only
- 1: label repeats API name
- 2: describes the field but not business meaning
- 3: includes business meaning and source
- 4: includes grain, units, null/valid values, and governance
- 5: includes all of the above plus examples and agent-safe usage guidance
Production target: object descriptions >= 4, agent-facing fields >= 4, metrics >= 5.
元数据评分范围为0-5:
- 0:缺失或仅包含源系统术语
- 1:标签重复API名称
- 2:描述字段但未说明业务含义
- 3:包含业务含义和来源
- 4:包含粒度、单位、空值/有效值和治理信息
- 5:包含以上所有内容,外加示例和Agent安全使用指南
生产目标:对象描述≥4分,Agent面向字段≥4分,指标≥5分。
Agentic Anti-Patterns
Agentic反模式
- Descriptions that say only "customer id", "flag", "amount", or "score".
- Multiple fields with similar labels and no distinction.
- Metrics with no time window or grain.
- Data Graphs with technical object names but no business purpose.
- Metadata that calls everything "customer" and hides whether the grain is
,
Individual,Unified Individual,Account,Account Contact, or a contact point.Party - Consent metadata that exposes a generic opt-in flag without purpose, channel, contact point, brand, legal basis, and status semantics.
- Agent actions whose input descriptions do not define format, units, or valid values.
- Exposing IDs, emails, phones, addresses, or raw source keys in agent responses.
- Treating metadata visibility as access permission. Agents must respect runtime governance and masking.
- Omitting tag/classification semantics, causing agents to use restricted fields as if they were safe context.
- Ignoring semantic model definitions and letting agents invent metric formulas.
- Building retriever descriptions that omit data space, source object, filters, citation behavior, and governance limits.
- 描述仅为“customer id”、“flag”、“amount”或“score”。
- 多个字段标签相似且无区分。
- 指标无时间窗口或粒度。
- 数据图谱仅包含技术对象名称,无业务用途。
- 元数据将所有对象都称为“customer”,隐藏其粒度是、
Individual、Unified Individual、Account、Account Contact还是联系点。Party - 同意元数据仅暴露通用的选择加入标志,无用途、渠道、联系点、品牌、法律依据和状态语义。
- Agent动作的输入描述未定义格式、单位或有效值。
- 在Agent响应中暴露ID、邮箱、电话、地址或原始源键。
- 将元数据可见性视为访问权限。Agent必须遵守运行时治理和掩码规则。
- 省略标签/分类语义,导致Agent将受限字段视为安全上下文使用。
- 忽略语义模型定义,让Agent自行发明指标公式。
- 构建的检索器描述省略数据空间、源对象、过滤器、引用行为和治理限制。
Validation Gates
验证关卡
- Metadata API inventory matches the objects the agent can query.
- Agent can map 10 business phrases to correct objects/fields/metrics.
- Agent refuses or asks clarification for ambiguous metadata.
- Agent output uses approved business descriptions and avoids PII.
- Agent output and action inputs are tested with a governed non-admin user profile.
- Data Graph and retriever descriptions match the actual fields included.
- CI/semantic metric descriptions include formulas and time windows.
- Metadata semantic score is >= 4 for agent-facing objects and fields, and 5 for metrics.
- Data kit / Metadata API deployment proof exists for metadata expected to move across orgs.
- 元数据API盘点与Agent可查询的对象匹配。
- Agent能将10个业务短语映射到正确的对象/字段/指标。
- Agent对模糊元数据拒绝处理或请求澄清。
- Agent输出使用批准的业务描述,避免PII。
- 使用受治理的非管理员用户配置文件测试Agent输出和动作输入。
- 数据图谱和检索器描述与实际包含的字段匹配。
- CI/语义指标描述包含公式和时间窗口。
- Agent面向对象和字段的元数据语义评分≥4分,指标≥5分。
- 对于预期跨组织迁移的元数据,存在数据套件/元数据API部署验证记录。
Handoffs
交接
- Semantic metrics -> sf-datacloud-semantic-layer
- Data graphs and relationships -> sf-datacloud-harmonize
- Agentforce action/topic descriptions -> companion skill when available
sf-ai-agentforce - Query and metadata extraction -> sf-datacloud-retrieve
- 语义指标 -> sf-datacloud-semantic-layer
- 数据图谱和关系 -> sf-datacloud-harmonize
- Agentforce动作/主题描述 -> 可用时使用配套技能
sf-ai-agentforce - 查询和元数据提取 -> sf-datacloud-retrieve
Output Format
输出格式
Report:
- metadata sources inspected
- object/field/metric quality score
- recommended descriptions
- relationship and grain notes
- agent-safe summary
- update mechanism or manual setup path
- validation prompts and expected routing
报告:
- 检查的元数据源
- 对象/字段/指标质量评分
- 推荐的描述
- 关系和粒度说明
- Agent安全摘要
- 更新机制或手动设置路径
- 验证提示词和预期路由
Doc-Synced Notes
文档同步说明
<!-- SF_DOC_SYNC_START:data-kits-and-packaging -->
<!-- SF_DOC_SYNC_START:data-kits-and-packaging -->
Data Kits and Packaging (Build and Share Functionality)
数据套件与打包(构建和共享功能)
Distilled from official Salesforce sources only.
Sources:
- developer.salesforce.com/docs/data/data-cloud-dev/guide/packages-data-kits.html — Packages and Data Kits
- developer.salesforce.com/docs/data/data-cloud-dev/guide/data-cloud-2gp-workflow.htm — 2GP Workflow for Data 360
- developer.salesforce.com/docs/data/data-cloud-dev/guide/component-cheatsheet.html — Metadata Components Cheat Sheet
- developer.salesforce.com/docs/data/data-cloud-dmo-mapping/guide/c360a-api-isv-readiness-data.html — Data 360 Extensibility Readiness Matrix
- developer.salesforce.com/docs/data/data-cloud-dev/guide/dc-deploy-data-kits-using-connect-api.html — Deploy Data 360 Data Kits with Connect REST
- developer.salesforce.com/docs/data/data-cloud-dev/guide/dc-deploy_data_kit_components.html — Deploy Data Kit Components Flow
- developer.salesforce.com/docs/data/data-cloud-dev/guide/app-dev-comparison.html — Differences Between Developing Apps on Data 360 and the Platform
What is a Data Kit?
- A Data Kit is a container for Data 360 metadata definitions (calculated insights, profiles, data streams, DMOs, identity rules, search indexes, segments, activations) — NOT the actual data.
- Streamlines packaging and deployment of related Data 360 configurations.
- A package can contain one or more data kits.
- When packaging Data 360 metadata, you MUST add components to a data kit first, then add the data kit to a package.
Two types of Data Kits:
| Type | Created from | Deployed to | Use case |
|---|---|---|---|
| Standard Data Kit | Default data space | Any data space in target org | AppExchange solutions, partner-distributed apps |
| DevOps Data Kit | Any data space | The same data space in target org | Sandbox-to-prod migration, internal CI/CD |
The Two-Package Rule (Winter '25 mandatory):
- You CANNOT include both Data 360 metadata and non-Data 360 metadata in the same package.
- Create two separate packages: one for Data 360, one for everything else.
- Applies to all package types (managed and unmanaged).
- Reason: Data 360 metadata lifecycle and deployment model differs from Salesforce Platform metadata.
Packaging types — pick by audience:
| Package Type | Audience | Behavior |
|---|---|---|
| Unmanaged | Internal customer dev → prod | Editable in target org, no upgrade path |
| Managed (1GP) | Salesforce Partner → AppExchange | Locked components; legacy path |
| Managed 2GP (Second-Gen) | Modern Partner / customer | Locked, namespaced, version-managed; preferred for new ISV apps |
All Data 360 feature metadata in managed packages is locked —
protects components from unauthorized changes in the subscriber org.
Packageable Data 360 components:
- Data Package Kit Definition (the kit itself)
- Data Package Kit Object (each component reference inside)
- Data Source / Data Source Bundle Definition
- Activation Platform (in unlocked + 1GP managed)
- Data Streams
- Data Lake Objects (DLOs)
- Data Model Objects (DMOs) — standard and custom
- Calculated Insights
- Identity Resolution Rulesets
- Segments (definitions)
- Activation Targets and Activations (definitions)
- Search Index Configurations
- Retrievers
- Data Mappings
Not all components are packageable — check the Data 360
Extensibility Readiness Matrix before designing kit contents.
DevOps tooling for Data Kits:
- DevOps Center supports Data 360 metadata.
- Data 360 Metadata API for programmatic kit assembly.
- Salesforce CLI () supports kit deployment.
sf project deploy/retrieve - Connect REST is the current programmatic deployment path for standard and
DevOps data kits. Set , capture the returned job ID, and poll status to
asyncMode=trueorCompleted.Error - Treat the "Deploy Data Kit Components" flow as a legacy compatibility path for new automation guidance.
- Standard and DevOps data kits use different request shapes. Confirm package installation, Data 360 Architect permission, data-kit developer name, and target data-space parity before deployment.
2GP Workflow (Salesforce Partners):
- Create a development scratch org or sandbox with Data 360 enabled.
- Build and validate Data 360 metadata in the dev environment.
- Add components to a Data Kit (Standard type).
- Create a 2GP managed package (Data 360 metadata only — NOT mixed).
- Create a package version; tag with semantic versioning.
- Promote to released (managed-released).
- Distribute via AppExchange or direct install link.
- Subscribers install; deploy data kit flow runs to apply metadata to their target data space.
Pre-flight before building a kit:
- Every component in the kit appears on the Extensibility Readiness Matrix.
- DMO references are resolved (no hanging references to non-packageable DMOs).
- Identity rulesets reference DMOs that ARE in the kit.
- Calculated Insights reference DMOs that ARE in the kit.
- Data Streams reference Data Sources that ARE in the kit.
- Tags and classifications used by policies are documented (policies themselves may not be packageable — verify in matrix).
- Target data space exists in the subscriber org.
- License/edition requirements documented for subscribers (Data 360 edition, add-on licenses for activation connectors, etc.).
Validation gates after deploying a Data Kit:
- All components landed in the expected data space.
- Data Streams successfully connect to the subscriber's Data Source.
- DMO mappings resolve to source DLOs.
- Identity Resolution Ruleset publishes successfully.
- Calculated Insight runs successfully on first scheduled execution.
- Search Index produces chunks; retriever returns results.
- Segments compile (DBT validation passes).
- Test the kit in a clean subscriber sandbox before production rollout.
仅提炼自Salesforce官方来源。
来源:
- developer.salesforce.com/docs/data/data-cloud-dev/guide/packages-data-kits.html — 包与数据套件
- developer.salesforce.com/docs/data/data-cloud-dev/guide/data-cloud-2gp-workflow.htm — Data 360的2GP工作流
- developer.salesforce.com/docs/data/data-cloud-dev/guide/component-cheatsheet.html — 元数据组件速查表
- developer.salesforce.com/docs/data/data-cloud-dmo-mapping/guide/c360a-api-isv-readiness-data.html — Data 360可扩展性就绪矩阵
- developer.salesforce.com/docs/data/data-cloud-dev/guide/dc-deploy-data-kits-using-connect-api.html — 使用Connect REST部署Data 360数据套件
- developer.salesforce.com/docs/data/data-cloud-dev/guide/dc-deploy_data_kit_components.html — 部署数据套件组件流程
- developer.salesforce.com/docs/data/data-cloud-dev/guide/app-dev-comparison.html — Data 360与平台应用开发的差异
什么是数据套件?
- 数据套件是Data 360元数据定义的容器(计算洞察、档案、数据流、DMO、身份规则、搜索索引、细分、激活)——而非实际数据。
- 简化相关Data 360配置的打包和部署。
- 一个包可以包含一个或多个数据套件。
- 打包Data 360元数据时,必须先将组件添加到数据套件,再将数据套件添加到包中。
两种数据套件类型:
| 类型 | 创建来源 | 部署目标 | 使用场景 |
|---|---|---|---|
| 标准数据套件 | 默认数据空间 | 目标组织中的任意数据空间 | AppExchange解决方案、合作伙伴分发的应用 |
| DevOps数据套件 | 任意数据空间 | 目标组织中的同一数据空间 | 沙箱到生产环境迁移、内部CI/CD |
双包规则(Winter '25强制要求):
- 不能在同一个包中同时包含Data 360元数据和非Data 360元数据。
- 创建两个独立的包:一个用于Data 360,一个用于其他所有内容。
- 适用于所有包类型(托管和非托管)。
- 原因:Data 360元数据的生命周期和部署模型与Salesforce平台元数据不同。
打包类型——按受众选择:
| 包类型 | 受众 | 行为 |
|---|---|---|
| 非托管 | 内部客户开发→生产 | 目标组织中可编辑,无升级路径 |
| 托管(1GP) | Salesforce合作伙伴→AppExchange | 组件锁定;传统路径 |
| 托管2GP(第二代) | 现代合作伙伴/客户 | 锁定、带命名空间、版本管理;新ISV应用首选 |
托管包中的所有Data 360功能元数据均被锁定——保护组件免受订阅组织中的未授权更改。
可打包的Data 360组件:
- 数据包套件定义(套件本身)
- 数据包套件对象(套件内的每个组件引用)
- 数据源/数据源捆绑定义
- 激活平台(非托管+1GP托管中支持)
- 数据流
- 数据湖对象(DLO)
- 数据模型对象(DMO)——标准和自定义
- 计算洞察
- 身份解析规则集
- 细分(定义)
- 激活目标和激活(定义)
- 搜索索引配置
- 检索器
- 数据映射
并非所有组件都可打包——设计套件内容前,请检查Data 360可扩展性就绪矩阵。
数据套件的DevOps工具:
- DevOps Center支持Data 360元数据。
- Data 360元数据API用于程序化套件组装。
- Salesforce CLI()支持套件部署。
sf project deploy/retrieve - Connect REST是当前标准和DevOps数据套件的程序化部署路径。设置,捕获返回的作业ID,轮询状态直到变为
asyncMode=true或Completed。Error - 将“部署数据套件组件”流程视为新自动化指南的遗留兼容路径。
- 标准和DevOps数据套件使用不同的请求格式。部署前确认包安装、Data 360 Architect权限、数据套件开发者名称和目标数据空间一致性。
2GP工作流(Salesforce合作伙伴):
- 创建启用Data 360的开发临时组织或沙箱。
- 在开发环境中构建并验证Data 360元数据。
- 将组件添加到数据套件(标准类型)。
- 创建2GP托管包(仅包含Data 360元数据——不可混合)。
- 创建包版本;使用语义版本标记。
- 推广至发布状态(managed-released)。
- 通过AppExchange或直接安装链接分发。
- 订阅者安装;运行部署数据套件流程以将元数据应用到其目标数据空间。
构建套件前的预检查:
- 套件中的每个组件都出现在可扩展性就绪矩阵中。
- DMO引用已解析(无对不可打包DMO的悬挂引用)。
- 身份规则集引用的DMO在套件中。
- 计算洞察引用的DMO在套件中。
- 数据流引用的数据源在套件中。
- 策略使用的标签和分类已记录(策略本身可能不可打包——请在矩阵中验证)。
- 订阅组织中存在目标数据空间。
- 为订阅者记录许可证/版本要求(Data 360版本、激活连接器的附加许可证等)。
部署数据套件后的验证关卡:
- 所有组件都部署到预期的数据空间。
- 数据流成功连接到订阅者的数据源。
- DMO映射解析到源DLO。
- 身份解析规则集成功发布。
- 计算洞察在首次计划执行时成功运行。
- 搜索索引生成块;检索器返回结果。
- 细分编译通过(DBT验证通过)。
- 在干净的订阅者沙箱中测试套件后再进行生产部署。