sf-datacloud

sf-datacloud：Salesforce Data Cloud 编排器

当用户需要产品级的 Data Cloud 工作流指导，而不是某个单独命令系列的说明时，请使用此技能：例如设置管道、跨阶段故障排查、数据空间、数据套件，或判断任务属于 Connect、Prepare、Harmonize、Segment、Act 还是 Retrieve。

此技能有意沿用 sf-skills 的风格指南，同时以外部 sf data360 命令界面作为运行时。此插件未随此仓库一同提供。

---

适用此技能的任务

在工作涉及以下内容时，请使用 sf-datacloud：

• 多阶段 Data Cloud 设置或修复
• 数据空间（sf data360 data-space *）
• 数据套件（sf data360 data-kit *）
• 健康检查（sf data360 doctor）
• CRM 到统一档案的管道设计
• 决定如何从数据摄取 → 协调 → 细分 → 激活
• 跨阶段故障排查，且尚不清楚根本原因

如果用户专注于某个领域，请委派给相应阶段的技能：

阶段	使用此技能	典型范围
Connect	sf-datacloud-connect	连接、连接器、源发现
Prepare	sf-datacloud-prepare	数据流、DLO、转换、DocAI
Harmonize	sf-datacloud-harmonize	DMO、映射、身份解析、数据图
Segment	sf-datacloud-segment	细分、计算型洞察
Act	sf-datacloud-act	激活、激活目标、数据操作
Retrieve	sf-datacloud-retrieve	SQL、搜索索引、向量搜索、异步查询

当用户需要以下工作时，请委派到此技能系列之外：

• 提取 Session Tracing / STDM 遥测数据 → sf-ai-agentforce-observability
• 仅编写 CRM SOQL → sf-soql
• 加载 CRM 源数据 → sf-data
• 创建缺失的 CRM 架构 → sf-metadata
• 实现下游 Apex 或 Flow 逻辑 → sf-apex、sf-flow

---

首先收集必要的上下文

询问或推断以下信息：

• 目标 org 别名
• 是否已安装并关联插件
• 用户需要设计指导、只读检查，还是实时修改
• 涉及的数据源：CRM 对象、外部数据库、文件摄取、知识等
• 期望的结果：统一档案、细分、激活、向量搜索、分析或故障排查
• 用户是在默认数据空间还是自定义数据空间中工作
• 是否已使用 scripts/diagnose-org.mjs 对 org 进行分类
• 当前是否有命令系列出错；如果有，是哪个系列

如果无法确定插件是否可用或 org 是否就绪，请从以下内容开始：

• references/plugin-setup.md
• references/feature-readiness.md
• scripts/verify-plugin.sh
• scripts/diagnose-org.mjs
• scripts/bootstrap-plugin.sh

---

核心操作规则

• 使用外部 sf data360 插件运行时；不要重新实现或打包命令层。
• 任务定位后，优先选择范围最小、针对特定阶段的技能。
• 在需要大量修改的工作前，先运行就绪状态分类。优先使用 scripts/diagnose-org.mjs，不要仅凭一条失败命令猜测。
• 对于 sf data360 命令，使用 2>/dev/null 抑制关联插件的警告噪声，除非需要通过标准错误输出进行调试。
• 区分 Data Cloud SQL 和 CRM SOQL。
• 不要将 sf data360 doctor 视为完整的产品就绪状态检查；当前上游命令只检查搜索索引部分。
• 不要将 query describe 视为通用租户探测工具；只有在确认表名是已知 DMO/DLO 表后才能使用。
• 在相关情况下，保留 Data Cloud 特有的 API 版本规避方案。
• 优先使用通用、可复用的 JSON 定义文件，而非特定组织的研讨会载荷。

---

推荐工作流

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

确认：

• 已安装 sf
• 已关联社区 Data Cloud 插件
• 已通过目标组织的身份验证

建议的检查：

sf data360 man
sf org display -o <alias>
bash ~/.claude/skills/sf-datacloud/scripts/verify-plugin.sh <alias>

将 sf data360 doctor 视为整体健康状况信号，而不是唯一的准入检查。在仅部分完成配置的组织中，即使连接器、DMO 或细分等只读命令族仍可正常工作，该命令也可能失败。

2. 更改任何内容之前，先分类就绪状态

先运行通用分类器：

node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --json

确认表名真实存在后，才使用查询平面探测：

node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --describe-table MyDMO__dlm --json

使用分类器区分：

• 已启用但为空的模块
• 受功能门控的模块
• 查询平面问题
• 运行时／身份验证故障

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

完成分类后，使用有针对性的检查：

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. 定位阶段

根据任务选择对应阶段：

• 源／连接器问题 → Connect
• 数据摄取／DLO／流问题 → Prepare
• 映射／IR／统一档案问题 → Harmonize
• 受众或洞察问题 → Segment
• 下游推送问题 → Act
• SQL／搜索／索引问题 → Retrieve

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

优先使用 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. 每个阶段完成后都进行验证

典型验证项：

• 流／DLO 存在
• DMO／映射存在
• 身份解析运行已完成
• 统一记录或细分计数看起来正确
• 激活／搜索索引状态正常

---

重要注意事项

• 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 设置。

---

输出格式

完成时，请按以下顺序报告：

1. 任务分类
2. 运行状态
3. 就绪情况分类
4. 涉及的阶段
5. 使用的命令或产物
6. 验证结果
7. 下一步建议

建议格式：

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>

---

跨技能集成

需求	委派给	原因
加载或清理 CRM 源数据	sf-data	在摄取前填充或修复源记录
创建缺失的 CRM 架构	sf-metadata	Data Cloud 需要现有对象/字段
部署权限或捆绑包	sf-deploy	环境准备
针对 Data Cloud 输出编写 Apex	sf-apex	代码实现
分群/激活后的 Flow 自动化	sf-flow	声明式编排
会话跟踪 / STDM / parquet 分析	sf-ai-agentforce-observability	属于不同的 Data Cloud 用例

---

参考索引

从这里开始

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

阶段技能

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

确定性辅助工具

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