orchestrating-datacloud

orchestrating-datacloud：Salesforce Data Cloud 编排器

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

此技能有意遵循 sf-skills 的风格规范，同时使用外部 sf data360 命令界面作为运行时。此插件未随附在此仓库中。

---

此技能负责的任务

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

• 多阶段 Data Cloud 设置或修复
• 数据空间（sf data360 data-space *）
• 数据套件（sf data360 data-kit *）
• 健康检查（sf data360 doctor）
• CRM 到统一档案的管道设计
• 判断如何从数据摄取推进到协调、细分和激活
• 跨阶段排查问题，且尚未明确根本原因

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

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

当用户要进行以下工作时，请委派给此技能系列之外的技能：

• 提取会话跟踪 / STDM 遥测数据 → observing-agentforce
• 仅编写 CRM SOQL → querying-soql
• 加载 CRM 源数据 → handling-sf-data
• 创建缺失的 CRM 架构 → generating-custom-object 或 generating-custom-field
• 实现下游 Apex 或 Flow 逻辑 → generating-apex、generating-flow

---

首先收集所需上下文

请询问或推断：

• 目标组织别名
• 插件是否已安装并关联
• 用户需要设计指导、只读检查还是实时更改
• 涉及的数据源：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

---

核心操作规则

• 使用外部 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 ./scripts/verify-plugin.sh <alias>

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

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

先运行通用分类器：

node ./scripts/diagnose-org.mjs -o <org> --json

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

node ./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 源数据	handling-sf-data	在摄取前播种或修复源记录
创建缺失的 CRM 架构	generating-custom-object、generating-custom-field	Data Cloud 需要现有对象/字段
部署权限或捆绑包	deploying-metadata	环境准备
针对 Data Cloud 输出编写 Apex	generating-apex	代码实现
细分/激活后的 Flow 自动化	generating-flow	声明式编排
会话跟踪 / STDM / parquet 分析	observing-agentforce	不同的 Data Cloud 用例

---

参考索引

从这里开始

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

阶段技能

• connecting-datacloud
• preparing-datacloud
• harmonizing-datacloud
• segmenting-datacloud
• activating-datacloud
• retrieving-datacloud

确定性辅助工具

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