Back to Details

sf-datacloud

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

sf-datacloud: Salesforce Data Cloud Orchestrator

sf-datacloud: Salesforce Data Cloud 编排器

Use this skill when the user needs product-level Data Cloud workflow guidance rather than a single isolated command family: pipeline setup, cross-phase troubleshooting, data spaces, data kits, or deciding whether a task belongs in Connect, Prepare, Harmonize, Segment, Act, or Retrieve.
This skill intentionally follows sf-skills house style while using the external 
sf data360
command surface as the runtime. The plugin is not vendored into this repo.
当用户需要产品级Data Cloud工作流指导而非单个独立命令家族时使用此技能：包括管道设置、跨阶段故障排查、数据空间、数据套件，或判断任务属于连接、准备、协调、细分、执行还是检索阶段。
本技能严格遵循sf-skills的内部风格，同时使用外部
sf data360
命令作为运行时。该插件未包含在本仓库中。

When This Skill Owns the Task

此技能负责的任务场景

Use 
sf-datacloud
when the work involves:
  • multi-phase Data Cloud setup or remediation
  • data spaces (
    sf data360 data-space *
    )
  • data kits (
    sf data360 data-kit *
    )
  • health checks (
    sf data360 doctor
    )
  • CRM-to-unified-profile pipeline design
  • deciding how to move from ingestion → harmonization → segmentation → activation
  • cross-phase troubleshooting where the root cause is not yet clear
Delegate to a phase-specific skill when the user is focused on one area:
PhaseUse this skillTypical scope
Connectsf-datacloud-connectconnections, connectors, source discovery
Preparesf-datacloud-preparedata streams, DLOs, transforms, DocAI
Harmonizesf-datacloud-harmonizeDMOs, mappings, identity resolution, data graphs
Segmentsf-datacloud-segmentsegments, calculated insights
Actsf-datacloud-actactivations, activation targets, data actions
Retrievesf-datacloud-retrieveSQL, search indexes, vector search, async query
Delegate outside the family when the user is:
  • extracting Session Tracing / STDM telemetry → sf-ai-agentforce-observability
  • writing CRM SOQL only → sf-soql
  • loading CRM source data → sf-data
  • creating missing CRM schema → sf-metadata
  • implementing downstream Apex or Flow logic → sf-apex, sf-flow
当工作涉及以下内容时使用
sf-datacloud
：
  • 多阶段Data Cloud设置或修复
  • 数据空间（
    sf data360 data-space *
    ）
  • 数据套件（
    sf data360 data-kit *
    ）
  • 健康检查（
    sf data360 doctor
    ）
  • CRM到统一档案的管道设计
  • 规划从数据摄入→协调→细分→激活的流程
  • 根本原因尚不明确的跨阶段故障排查
当用户聚焦于单一领域时，应委托给特定阶段的技能：
阶段使用技能典型范围
连接sf-datacloud-connect连接、连接器、数据源发现
准备sf-datacloud-prepare数据流、DLO、转换、DocAI
协调sf-datacloud-harmonizeDMO、映射、身份解析、数据图谱
细分sf-datacloud-segment细分群体、计算洞察
执行sf-datacloud-act激活、激活目标、数据操作
检索sf-datacloud-retrieveSQL、搜索索引、向量搜索、异步查询
当用户进行以下操作时，应委托给外部技能：
  • 提取会话跟踪/STDM遥测 → sf-ai-agentforce-observability
  • 仅编写CRM SOQL → sf-soql
  • 加载CRM源数据 → sf-data
  • 创建缺失的CRM架构 → sf-metadata
  • 实现下游Apex或Flow逻辑 → sf-apex, sf-flow

Required Context to Gather First

首先需要收集的必要上下文

Ask for or infer:
  • target org alias
  • whether the plugin is already installed and linked
  • whether the user wants design guidance, read-only inspection, or live mutation
  • data sources involved: CRM objects, external databases, file ingestion, knowledge, etc.
  • desired outcome: unified profiles, segments, activations, vector search, analytics, or troubleshooting
  • whether the user is working in the default data space or a custom one
  • whether the org has already been classified with 
    scripts/diagnose-org.mjs
  • which command family is failing today, if any
If plugin availability or org readiness is uncertain, start with:
  • references/plugin-setup.md
  • references/feature-readiness.md
  • scripts/verify-plugin.sh
  • scripts/diagnose-org.mjs
  • scripts/bootstrap-plugin.sh
询问或推断以下信息：
  • 目标组织别名
  • 插件是否已安装并关联
  • 用户需要的是设计指导、只读检查还是实时修改
  • 涉及的数据源：CRM对象、外部数据库、文件摄入、知识库等
  • 期望结果：统一档案、细分群体、激活、向量搜索、分析或故障排查
  • 用户是否在默认数据空间或自定义数据空间中工作
  • 组织是否已通过
    scripts/diagnose-org.mjs
    完成分类
  • 当前失败的命令家族（如有）
如果插件可用性或组织就绪状态不确定，从以下内容开始：
  • references/plugin-setup.md
  • references/feature-readiness.md
  • scripts/verify-plugin.sh
  • scripts/diagnose-org.mjs
  • scripts/bootstrap-plugin.sh

Core Operating Rules

核心操作规则

  • Use the external 
    sf data360
    plugin runtime; do not reimplement or vendor the command layer.
  • Prefer the smallest phase-specific skill once the task is localized.
  • Run readiness classification before mutation-heavy work. Prefer 
    scripts/diagnose-org.mjs
    over guessing from one failing command.
  • For 
    sf data360
    commands, suppress linked-plugin warning noise with 
    2>/dev/null
    unless the stderr output is needed for debugging.
  • Distinguish Data Cloud SQL from CRM SOQL.
  • Do not treat 
    sf data360 doctor
    as a full-product readiness check; the current upstream command only checks the search-index surface.
  • Do not treat 
    query describe
    as a universal tenant probe; only use it with a known DMO/DLO table after broader readiness is confirmed.
  • Preserve Data Cloud-specific API-version workarounds when they matter.
  • Prefer generic, reusable JSON definition files over org-specific workshop payloads.
  • 使用外部
    sf data360
    插件运行时；不要重新实现或包含命令层。
  • 一旦任务定位到具体阶段，优先使用最小化的阶段特定技能。
  • 在进行大量修改工作前，先运行就绪状态分类。优先使用
    scripts/diagnose-org.mjs
    而非通过单个失败命令猜测。
  • 对于
    sf data360
    命令，使用
    2>/dev/null
    抑制关联插件警告信息，除非调试需要stderr输出。
  • 区分Data Cloud SQL与CRM SOQL。
  • 不要将
    sf data360 doctor
    视为完整产品就绪检查；当前上游命令仅检查搜索索引层面。
  • 不要将
    query describe
    视为通用租户探测；仅在确认更广泛的就绪状态后，对已知的DMO/DLO表使用它。
  • 当Data Cloud特定的API版本解决方法重要时，保留这些方法。
  • 优先使用通用、可复用的JSON定义文件，而非特定组织的工作负载。

Recommended Workflow

推荐工作流

1. Verify the runtime and auth

1. 验证运行时和身份验证

Confirm:
  • sf
    is installed
  • the community Data Cloud plugin is linked
  • the target org is authenticated
Recommended checks:
bash
sf data360 man
sf org display -o <alias>
bash ~/.claude/skills/sf-datacloud/scripts/verify-plugin.sh <alias>
Treat 
sf data360 doctor
as a broad health signal, not the sole gate. On partially provisioned orgs it can fail even when read-only command families like connectors, DMOs, or segments still work.
确认：
  • sf
    已安装
  • 社区Data Cloud插件已关联
  • 目标组织已通过身份验证
推荐检查：
bash
sf data360 man
sf org display -o <alias>
bash ~/.claude/skills/sf-datacloud/scripts/verify-plugin.sh <alias>
将
sf data360 doctor
视为广泛的健康信号，而非唯一的准入条件。在部分配置的组织中，即使连接器、DMO或细分群体等只读命令家族仍能正常工作，该命令也可能失败。

2. Classify readiness before changing anything

2. 在进行任何更改前分类就绪状态

Run the shared classifier first:
bash
node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --json
Only use a query-plane probe after you know the table name is real:
bash
node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --describe-table MyDMO__dlm --json
Use the classifier to distinguish:
  • empty-but-enabled modules
  • feature-gated modules
  • query-plane issues
  • runtime/auth failures
先运行共享分类器：
bash
node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --json
仅在已知表名真实存在后，使用查询平面探测：
bash
node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --describe-table MyDMO__dlm --json
使用分类器区分：
  • 空但已启用的模块
  • 功能 gated 的模块
  • 查询平面问题
  • 运行时/身份验证失败

3. Discover existing state with read-only commands

3. 使用只读命令发现现有状态

Use targeted inspection after classification:
bash
sf data360 doctor -o <org> 2>/dev/null
sf data360 data-space list -o <org> 2>/dev/null
sf data360 data-stream list -o <org> 2>/dev/null
sf data360 dmo list -o <org> 2>/dev/null
sf data360 identity-resolution list -o <org> 2>/dev/null
sf data360 segment list -o <org> 2>/dev/null
sf data360 activation platforms -o <org> 2>/dev/null
分类后进行针对性检查：
bash
sf data360 doctor -o <org> 2>/dev/null
sf data360 data-space list -o <org> 2>/dev/null
sf data360 data-stream list -o <org> 2>/dev/null
sf data360 dmo list -o <org> 2>/dev/null
sf data360 identity-resolution list -o <org> 2>/dev/null
sf data360 segment list -o <org> 2>/dev/null
sf data360 activation platforms -o <org> 2>/dev/null

4. Localize the phase

4. 定位阶段

Route the task:
  • source/connector issue → Connect
  • ingestion/DLO/stream issue → Prepare
  • mapping/IR/unified profile issue → Harmonize
  • audience or insight issue → Segment
  • downstream push issue → Act
  • SQL/search/index issue → Retrieve
路由任务：
  • 源/连接器问题 → 连接
  • 摄入/DLO/流问题 → 准备
  • 映射/IR/统一档案问题 → 协调
  • 受众或洞察问题 → 细分
  • 下游推送问题 → 执行
  • SQL/搜索/索引问题 → 检索

5. Choose deterministic artifacts when possible

5. 尽可能选择确定性工件

Prefer JSON definition files and repeatable scripts over one-off manual steps. Generic templates live in:
  • assets/definitions/data-stream.template.json
  • assets/definitions/dmo.template.json
  • assets/definitions/mapping.template.json
  • assets/definitions/relationship.template.json
  • assets/definitions/identity-resolution.template.json
  • assets/definitions/data-graph.template.json
  • assets/definitions/calculated-insight.template.json
  • assets/definitions/segment.template.json
  • assets/definitions/activation-target.template.json
  • assets/definitions/activation.template.json
  • assets/definitions/data-action-target.template.json
  • assets/definitions/data-action.template.json
  • assets/definitions/search-index.template.json
优先使用JSON定义文件和可重复脚本，而非一次性手动步骤。通用模板位于：
  • assets/definitions/data-stream.template.json
  • assets/definitions/dmo.template.json
  • assets/definitions/mapping.template.json
  • assets/definitions/relationship.template.json
  • assets/definitions/identity-resolution.template.json
  • assets/definitions/data-graph.template.json
  • assets/definitions/calculated-insight.template.json
  • assets/definitions/segment.template.json
  • assets/definitions/activation-target.template.json
  • assets/definitions/activation.template.json
  • assets/definitions/data-action-target.template.json
  • assets/definitions/data-action.template.json
  • assets/definitions/search-index.template.json

6. Verify after each phase

6. 每个阶段后进行验证

Typical verification:
  • stream/DLO exists
  • DMO/mapping exists
  • identity resolution run completed
  • unified records or segment counts look correct
  • activation/search index status is healthy
典型验证内容：
  • 流/DLO存在
  • DMO/映射存在
  • 身份解析运行完成
  • 统一记录或细分群体计数看起来正确
  • 激活/搜索索引状态健康

High-Signal Gotchas

关键注意事项

  • connection list
    requires 
    --connector-type
    .
  • dmo list --all
    is useful when you need the full catalog, but first-page 
    dmo list
    is often enough for readiness checks and much faster.
  • Segment creation may need 
    --api-version 64.0
    .
  • segment members
    returns opaque IDs; use SQL joins for human-readable details.
  • sf data360 doctor
    can fail on partially provisioned orgs even when some read-only commands still work; fall back to targeted smoke checks.
  • query describe
    errors such as 
    Couldn't find CDP tenant ID
    or 
    DataModelEntity ... not found
    are query-plane clues, not automatic proof that the whole product is disabled.
  • Many long-running jobs are asynchronous in practice even when the command returns quickly.
  • Some Data Cloud operations still require UI setup outside the CLI runtime.
  • connection list
    需要
    --connector-type
    参数。
  • 当需要完整目录时，
    dmo list --all
    很有用，但首次运行
    dmo list
    通常足以进行就绪检查且速度更快。
  • 细分群体创建可能需要
    --api-version 64.0
    。
  • segment members
    返回不透明ID；使用SQL连接获取人类可读的详细信息。
  • 在部分配置的组织中，即使某些只读命令仍能工作，
    sf data360 doctor
    也可能失败；此时应回退到针对性的冒烟测试。
  • query describe
    错误如
    Couldn't find CDP tenant ID
    或
    DataModelEntity ... not found
    是查询平面的线索，而非整个产品已禁用的自动证明。
  • 许多长时间运行的作业实际上是异步的，即使命令快速返回。
  • 某些Data Cloud操作仍需要在CLI运行时之外通过UI进行设置。

Output Format

输出格式

When finishing, report in this order:
  1. Task classification
  2. Runtime status
  3. Readiness classification
  4. Phase(s) involved
  5. Commands or artifacts used
  6. Verification result
  7. Next recommended step
Suggested shape:
text
Data Cloud task: <setup / inspect / troubleshoot / migrate>
Runtime: <plugin ready / missing / partially verified>
Readiness: <ready / ready_empty / partial / feature_gated / blocked>
Phases: <connect / prepare / harmonize / segment / act / retrieve>
Artifacts: <json files, commands, scripts>
Verification: <passed / partial / blocked>
Next step: <next phase, setup guidance, or cross-skill handoff>
完成任务后，按以下顺序报告：
  1. 任务分类
  2. 运行时状态
  3. 就绪状态分类
  4. 涉及的阶段
  5. 使用的命令或工件
  6. 验证结果
  7. 推荐的下一步
建议格式：
text
Data Cloud任务: <设置 / 检查 / 故障排查 / 迁移>
运行时: <插件就绪 / 缺失 / 部分验证>
就绪状态: <就绪 / 就绪但空 / 部分就绪 / 功能受限 / 受阻>
阶段: <连接 / 准备 / 协调 / 细分 / 执行 / 检索>
工件: <JSON文件、命令、脚本>
验证结果: <通过 / 部分通过 / 受阻>
下一步: <下一阶段、设置指导或跨技能移交>

Cross-Skill Integration

跨技能集成

NeedDelegate toReason
load or clean CRM source datasf-dataseed or fix source records before ingestion
create missing CRM schemasf-metadataData Cloud expects existing objects/fields
deploy permissions or bundlessf-deployenvironment preparation
write Apex against Data Cloud outputssf-apexcode implementation
Flow automation after segmentation/activationsf-flowdeclarative orchestration
session tracing / STDM / parquet analysissf-ai-agentforce-observabilitydifferent Data Cloud use case
需求委托给原因
加载或清理CRM源数据sf-data在摄入前填充或修复源记录
创建缺失的CRM架构sf-metadataData Cloud期望现有对象/字段
部署权限或捆绑包sf-deploy环境准备
针对Data Cloud输出编写Apexsf-apex代码实现
细分/激活后的Flow自动化sf-flow声明式编排
会话跟踪/STDM/Parquet分析sf-ai-agentforce-observability不同的Data Cloud用例

Reference Map

参考地图

Start here

入门

  • README.md
  • references/plugin-setup.md
  • references/feature-readiness.md
  • UPSTREAM.md
  • README.md
  • references/plugin-setup.md
  • references/feature-readiness.md
  • UPSTREAM.md

Phase skills

阶段技能

  • sf-datacloud-connect
  • sf-datacloud-prepare
  • sf-datacloud-harmonize
  • sf-datacloud-segment
  • sf-datacloud-act
  • sf-datacloud-retrieve
  • sf-datacloud-connect
  • sf-datacloud-prepare
  • sf-datacloud-harmonize
  • sf-datacloud-segment
  • sf-datacloud-act
  • sf-datacloud-retrieve

Deterministic helpers

确定性助手

  • scripts/bootstrap-plugin.sh
  • scripts/verify-plugin.sh
  • scripts/diagnose-org.mjs
  • assets/definitions/
  • scripts/bootstrap-plugin.sh
  • scripts/verify-plugin.sh
  • scripts/diagnose-org.mjs
  • assets/definitions/