service-omni-channel-setup-coordinate

service-omni-channel-setup-coordinate

使组织达到可正常运行的全渠道设置：检测现有内容，仅创建或部署缺失的部分，直至环境具备路由能力，并配置代理、队列、在线状态和权限。对于 Case 和 VoiceCall，提供完整的创建并绑定路由（队列 + QueueRoutingConfig + 出站路由流程）；此协调器仅验证/采用 Incident 和 MessagingSession，会报告其状态并复用现有配置，但不会为它们创建缺失的队列/QRC/流程（如需创建并绑定 MessagingSession 交接，请使用 service-agentforce-human-escalation-configure）。这是一个协调器——它按规范步骤调用子叶技能，本身不执行任何写入操作。每个叶技能负责一个基本操作；协调器会解析各组织中的 ID，在叶技能之间传递这些 ID，并执行统一的复用与创建策略及安全约定。只有对于必须由操作员处理的前置条件（缺少功能许可证，或目标 sObject 未启用），协调器才会通过点击路径说明阻止继续。

此处列出 python3 仅因为随附的合约测试（scripts/tests/test_omni_contracts.py）需要它；运行协调器本身只需要 jq 和 sf。

输入

在进行任何写入之前，请一次性确认以下内容：

• Agent 数量（默认为 3，范围为 1..10）和主管数量（默认为 1，范围为 1..5）。
• 真实登录邮箱（用于密码重置流程）。
• routing_targets（默认为 ["Case"]）——Case | Incident | MessagingSession | VoiceCall 的任意子集。只有 Case 和 VoiceCall 会完整执行创建队列 + QRC + 路由流；Incident 和 MessagingSession 则会经过验证并采用（仅报告）。
• 服务渠道策略——重复使用标准渠道（Cases、sfdc_livemessage，默认），或创建自定义渠道。
• Agent/主管配置文件——驱动程序默认在 Service Cloud User 配置文件下配置用户（Omni 需要 Service Cloud 许可证）。有些组织会将该许可证配置在名称不同的配置文件下（例如 Service Cloud）；可通过 OMNI_AGENT_PROFILE / OMNI_SUPERVISOR_PROFILE 覆盖，无需编辑脚本。如果不存在指定的配置文件，用户创建步骤将中止。
• 运行时验证（可选）——OMNI_RUNTIME_PROOF=1 会使路由流叶节点触发触发器（失败时继续）；OMNI_RUNTIME_PROOF_REQUIRED=1 会使验证成为阻断条件。QueueBased 验证需要 PendingServiceRouting 或 AgentWork。SkillsBased 验证需要至少包含一个 SkillRequirement 的 PendingServiceRouting，这就是 WorkSkillRouting 确实运行的验收信号。临时创建的记录始终会被清理。
• 队列选择（可选）——当目标必须使用特定的现有队列或规范队列时，设置 OMNI_CASE_QUEUE_DEVELOPER_NAME、OMNI_VOICE_QUEUE_DEVELOPER_NAME、OMNI_INCIDENT_QUEUE_DEVELOPER_NAME 或 OMNI_MESSAGING_QUEUE_DEVELOPER_NAME。如果不设置覆盖值，每个叶节点都会使用根据目标派生的默认值。
• 路由配置选择（可选）——设置 OMNI_CASE_ROUTING_CONFIG_DEVELOPER_NAME 或 OMNI_VOICE_ROUTING_CONFIG_DEVELOPER_NAME，以显式选择现有 QRC。如果只提供了队列覆盖值，协调器会先采用该队列关联的 QueueRoutingConfig.DeveloperName；只有当队列未关联配置时，才会创建规范 QRC。
• 队列路由控件（可选）——OMNI_QRC_PUSH_TIMEOUT 设置 Agent 接受超时时间，OMNI_QRC_CAPACITY_PERCENTAGE 选择容量百分比（例如，对消耗 Agent 全部容量的 VoiceCall 设置为 100）。协调器会将这两个值传递给每个 QRC 目标。
• 路由模式——OMNI_ROUTING_TYPE=QueueBased|SkillsBased 为可选项。如果提供了全部四个输入 OMNI_WSR_ENTITY / OMNI_WSR_FIELD / OMNI_WSR_SKILL / OMNI_WSR_VALUE，协调器会推断为 SkillsBased；否则默认为 QueueBased。SkillsBased 使用 OMNI_SKILL_OPTION=RunSBRRules（默认值），将已配置的 Agent 关联到 OMNI_SBR_SKILL（默认为 OMNI_WSR_SKILL），编写 WorkSkillRouting 规则，然后才激活流。映射不完整或 SBR/WSR 技能不匹配时，会在任何写入操作前拒绝执行。OMNI_WSR_LABEL 可用于指定规则名称。
• 代表体验阶段（可选，默认关闭）——OMNI_REP_EXPERIENCE=1 会添加在线状态用户配置（拒绝 + 拒绝原因 + ACW）和 Omni 侧边栏。OMNI_CONSOLE_APP=<app DeveloperName> 用于指定控制台应用；留空则自动检测。
• 主管界面（始终执行，配置完成后）——OmniSupervisorConfig 创建后，协调器会通过 Data API 填充其标准操作和选项卡界面（OmniSupervisorConfigAction / OmniSupervisorConfigTab）。在部署经典配置之前，它还会运行只读的 Command Center 分析，报告组织使用的是经典界面还是 Command Center V2。
• 主管配置选择（可选）——设置 OMNI_SUPERVISOR_CONFIG_DEVELOPER_NAME，指定配置阶段和界面阶段都必须协调的准确经典 OmniSupervisorConfig.DeveloperName。默认值为 Omni_Supervisor；当组织有多个配置时，请使用此覆盖值，确保协调器不会自行猜测。创建新的指定配置时，OMNI_SUPERVISOR_CONFIG_MASTER_LABEL 可用于提供标签。

以计划或运行模式执行：

bash scripts/integration-driver.sh --plan <org-alias> [agent_count] [routing_targets_csv] [supervisor_count]
bash scripts/integration-driver.sh --run  <org-alias> [agent_count] [routing_targets_csv] [supervisor_count]

--plan 是完整的只读预览：每个叶步骤都会运行自己的检测器，并报告 reused、action_needed 或 blocked；如果某个叶步骤的前置条件尚未满足，则会报告为待处理工作，而不会进行探测，因此计划不会把仅仅在执行顺序中靠后的步骤误报为红色。干净的计划（全部为 reused，退出码为 0）表示组织已完成配置；任何黄色状态（退出码为 2）都表示仍有工作待完成。

前置条件与安全性

• 通过 sf CLI 使用 My Domain URL（而非 .lightning.force.com）登录组织。
• Service Cloud 许可证数量足以满足 Agent 数量需求。
• Incident 目标要求启用 Incident Management 功能；MessagingSession 要求启用 Enhanced Messaging；VoiceCall 要求启用 Service Cloud Voice。对于请求的目标 sObject，如果它不存在，就绪检查会硬失败，并提供点击路径。
• 生产环境防护措施： 当 IsSandbox = true、TrialExpirationDate != null 或 OrganizationType IN ('Developer Edition', 'Base Edition') 中任一条件成立时，safe_to_write 才为 true。否则运行将硬性拒绝。CDO 返回的 IsSandbox=false 且 TrialExpirationDate 非空，因此必须允许 CDO；所以绝不能只用 IsSandbox 作为判断条件。

就绪检查（无提示，强制执行，且必须在任何叶步骤运行前完成）：

1. sf org display → 确认组织别名已通过身份验证；如果未通过，则拒绝执行（退出码为 1）。
2. Organization（IsSandbox、TrialExpirationDate、OrganizationType）→ 计算 safe_to_write；如果为 false，则拒绝执行（退出码为 1）。
3. 预检实体可用性 → 对每个非 Case 路由目标，通过 EntityDefinition 确认 sObject 存在；如果目标缺失，则硬失败，并提供功能启用的点击路径（退出码为 2）。假定 Case 存在，因此跳过检查。

Omni-Channel 基础设置启用情况不会作为单独的前置探测项进行检查——它由基础设置叶步骤（第 1 步）检测；在启用前，--plan 会将依赖 Omni-Channel 的下游叶步骤延后为待处理状态。驱动程序不会在此就绪检查阶段预检 UserLicense 余量，也不会预检 ServicePresenceStatus/QueueRoutingConfig 的可用性。

此协调器编排的技能

协调器会将每项写入操作委派给一个叶子技能。特定 sObject 的叶子技能（3、5、6、6c、7）会针对每个路由目标循环运行一次；其余技能各运行一次。对于 SkillsBased 路由，步骤 6a 和 6b 会在激活任何触发器流之前完成。步骤 10a（command-center-analyze）是只读建议步骤，始终运行。监督员配置成功后，步骤 11a（supervisor-surface-deploy）始终运行。步骤 12–13 是可选启用的代表体验阶段（OMNI_REP_EXPERIENCE=1）。

#	子技能	角色
1	service-omni-base-settings-configure	部署 Settings:OmniChannel（5 个开关）
2	service-omni-agent-users-create	配置所请求的 Agent 用户
3	service-omni-service-channel-configure	为目标 sObject 复用标准 ServiceChannel，或部署规范 XML
4	service-omni-queue-routing-config-deploy	创建或更新目标的 QueueRoutingConfig（例如 Case_Routing_Config、Voice_Routing_Config）
5	service-omni-queue-deploy	发现或创建（--create-if-missing）与目标 sObject 关联的 Queue；使其与 QRC 一致
6	service-omni-queue-members-assign	将用户分配到发现的队列
6a	service-omni-skills-based-routing-configure	(仅限 SkillsBased) 确保 Skill 和活跃 Agent 的 SkillUser 关联存在
6b	service-omni-work-skill-routing-configure	(仅限 SkillsBased) 在激活流之前编写所需的字段值 → Skill 规则
6c	service-omni-routing-flow-deploy	为 Case/VoiceCall 部署记录触发的 QueueBased 或 SkillsBased Flow；SkillsBased 会传入 skillOption=RunSBRRules
7	service-omni-presence-status-deploy	部署与匹配渠道关联的 Available_<sObject>，并确保存在通用的 Busy 状态
8	service-omni-permission-set-assign	将 Omni_Agent PermissionSet 分配给 Agent 用户；缺失时会自动修复随附的元数据（仅运行模式）
9	service-omni-supervisor-users-create	配置监督员用户
10	service-omni-supervisor-permset-assign	将标准 ContactCenterSupervisor PermissionSet 分配给监督员用户
10a	service-omni-command-center-analyze	只读建议 — 报告组织使用的是经典监督员界面还是 Command Center V2；不执行写入操作，也不会强制阻止流程
11	service-omni-supervisor-config-deploy	部署 OmniSupervisorConfig，将监督员用户关联到步骤 5 中发现的队列
11a	service-omni-supervisor-surface-deploy	在步骤 11 的配置中填充监督员的操作和选项卡界面（OmniSupervisorConfigAction / OmniSupervisorConfigTab）
12	service-omni-presence-user-config-deploy	(可选) 部署 PresenceUserConfig + PresenceDeclineReason（拒绝 + ACW），并分配已配置的 Agent
13	service-omni-sidebar-configure	(可选) 设置 CustomApplication.isOmniPinnedViewEnabled=true，以便在控制台应用中固定 Omni 实用工具区域
—	platform-metadata-deploy	部署叶子技能所用的底层 Metadata API 部署

行为

复用与创建约定（适用于每个实体，且强制执行）。 按 DeveloperName（或自然键）查询；存在标准记录时（Cases、sfdc_livemessage）复用；不存在时，根据叶节点随附的定义创建；若存在同名自定义记录，则以幂等方式协调——绝不重复创建、重命名，也不更改标准记录或托管记录的标识。

执行顺序与门控。 叶节点按依赖顺序运行。基础设置是以下所有写入操作的硬性前置条件。对于 SkillsBased 路由，必须先成功完成 Agent 的 SkillUser 绑定（6a）和 WorkSkillRouting 规则（6b），路由流叶节点（6c）才能激活触发器。该流还需要队列（5）及其成员（6），并通过往返读取 FlowDefinitionView.ActiveVersionId 来证明流处于 Active 状态。仅因存在 PSR 并不代表通过所需的运行时验证：SkillsBased 要求该 PSR 至少有一个 SkillRequirement。

主管路径。 主管用户（9）使用与 Agent 用户相同的匿名 Apex System.setPassword 模式。由于启用调试 TraceFlag 时，密码字面值可能被记录到 ApexLog，两个用户创建叶节点都会在首次调用 System.setPassword 之前以失败关闭：通过经 SOQL 筛选的 Tooling API 查询（ExpirationDate > now）证明当前运行用户没有活动 TraceFlag；若无法确凿证明，则完全不设置密码（用户保持 ACTIVE 和 reset_required 状态，并附带 security_warning）。它们绝不会删除日志，因此不会影响无关的审计日志。主管权限集叶节点（10）分配标准的 ContactCenterSupervisor——绝不分配自定义的 Omni_Supervisor，其受许可证限制的权限无法成功分配；契约测试会断言此配置。在主管权限集之后，只读的 Command Center 分析（10a）会报告组织的主管界面（经典界面还是 Command Center V2）；它不会写入数据，也绝不会硬性阻止流程（检测结果不明确时显示黄色，读取正常时显示绿色）。配置部署完成后（11），界面叶节点（11a）会针对配置的 Id 插入标准操作和选项卡配套项（OmniSupervisorConfigAction / OmniSupervisorConfigTab）——这些是普通 Data API 行，因此无需重新部署元数据文件——并且是幂等的（仅插入缺失的类型）。它只会在配置成功后运行；若配置被跳过或失败，界面也会因依赖关系而跳过，并附带说明。

可选的代表体验阶段。 设置 OMNI_REP_EXPERIENCE=1 时，在线状态用户配置（12）会部署一个通过验证器检查的 PresenceUserConfig，其中包含拒绝原因，并为所有已解析的 Agent 用户名分配该配置，包括复用的用户。侧边栏（13）会在 OMNI_CONSOLE_APP 上固定 Omni 实用程序区域，或自动检测唯一的控制台应用。SkillsBased 路由并非仅用于改善代表体验的可选阶段：请求该路由时，必须先完成 SkillUser 和 WorkSkillRouting 前置步骤，然后才能激活流。

登录行为缺口。 登录行为单选项（Setup → Omni-Channel Settings → “Define login behavior when an agent opens a new window/tab”）在 v66 中没有公开 API。基础设置部署完成后，协调器会提供准确的点击路径；它不会尝试通过 enableOmniAutoLoginPrompt 来切换该选项，因为该选项虽可部署，却不会控制此单选项。请参阅 references/gap-catalog.md。

凭据。 生成的密码会移入单个受限的 CREDENTIALS.json（模式 0600），并从所有其他产物中清除。写入过程是原子操作，且失败时关闭：若清除或验证过程中出现任何失败，明文产物会被删除，运行随即中止，因此产物目录中不会留下任何明文密码。操作人员读取一次 CREDENTIALS.json，安全地分发后将其删除。

输出约定

唯一交付物是一份报告文件。作为最后一步，你必须使用 Write 工具将完整报告保存到当前工作目录中的 omni-coordinate-report.md——绝不能只在聊天中交付。在 --run 模式下，报告应说明实际发生的情况（已创建资源、已复用标准记录、已解决决策），不得含糊其辞。在 --plan 模式下，报告应说明每个叶节点的真实处置状态（reused / action_needed / 待处理），并附上协调器的计划 JSON（dry_run: true）。每个叶节点还会将完整的 JSON 结果（包括每个已创建记录的 Id 和 deploy Id）写入运行的 artifacts 目录中的单项技能文件；这就是审计记录。面向用户的输出应使用易读名称，而不是记录 Id。报告格式参见 examples/output-templates.md。

运行 artifacts（运行模式）。 除各技能的 artifacts 外，--run 还会在运行的 artifacts 目录中写入三个文件（路径会在报告 JSON 中作为 run_log、deploy_ids_file、teardown_script 输出）：run.log（经过清理、易读的步骤序列和结果）、deploy_ids.json（来源清单——每个条目的 provenance 为 created / updated / reused，并包含资源 id、before 快照，以及指向权威单项技能 artifact 的路径），以及 teardown.sh（自动生成的试运行反向依赖顺序计划）。teardown 脚本会打印 teardown 将执行的操作：REMOVE（运行时创建）、RESTORE（已更新，并恢复先前值）或 KEEP（已采用／复用——绝不删除），且不会做出任何更改；按设计，破坏性执行仍需手动完成（参见限制）。

报告内容规则：

• 报告具体结果，绝不写意图。
• 只要运行了设置流程，就必须说明登录行为的点击路径，即使操作员选择不拨动单选按钮也一样。
• 若步骤 5 明确失败（未绑定队列），必须将其作为手动操作事项，并提供点击路径。

限制

• 路由流部署仅涵盖 Case 和 VoiceCall。
• 仅支持经典版 OmniSupervisorConfig（包括其操作和标签页界面）。Command Center V2（Enhanced Omni-Channel）会在只读分析步骤中报告，但不会启用——组织偏好设置无法通过 Metadata API 写入。界面叶节点仅填充无需引用的标准操作／标签页类型；自定义操作、FlexiPage、AWS 仪表板和 AI Agent 界面需要外部引用，且必须在 Setup 中设置。
• 代表体验阶段（presence 用户配置、拒绝原因、侧边栏）仅在 OMNI_REP_EXPERIENCE=1 时运行。SkillsBased 路由需显式选择，或根据完整的 OMNI_WSR_* 映射推断；无论该标志如何设置，都会独立运行。
• teardown 仅生成计划：--run 会生成 deploy_ids.json（来源清单）和 teardown.sh 试运行脚本，打印反向顺序的移除／恢复计划，但不会执行破坏性更改。只有在每个叶节点都输出标准化来源区块且已在线验证逆转操作后，才会实施自动逆转——通过 metadata 部署的组件需要使用 destructiveChanges 部署，已采用的记录绝不能删除。目前，逆转是由操作员参照计划和各技能 artifacts 手动完成的。

用例覆盖范围（当前）

用例	状态	无头模式的支持范围
案例路由	就绪	完整创建并绑定线程（队列 + QRC + 成员 + 路由流），支持幂等；运行时 PendingServiceRouting 证明可选。
VoiceCall / AFCC 路由	有条件	QRC + 队列 + 成员 + 路由流均可部署，但需要已配置的 Amazon/AFCC 联系中心和运行中的 Voice 环境，才能验证端到端流程。联系中心由调用方负责配置。
Open CTI → AFCC 迁移	部分支持	协调器会创建 Omni 路由资源；不会自行配置或迁移联系中心。
事件路由	部分支持	支持服务渠道 + 状态；协调器会验证/采用事件路由，但不会为其创建缺失的队列/QRC/流。
通用 MessagingSession 路由	部分支持	支持服务渠道 + 状态；完整创建并绑定由 service-agentforce-human-escalation-configure 负责，不会在此处通用执行。
经典 Omni Supervisor	就绪	用户、权限、配置、队列/用户以及操作/选项卡界面的配套功能均已实现。
Command Center V2	仅检测	只读分析步骤会报告经典版还是 V2；组织首选项 CommandCenterForServiceV2 无法通过 Metadata API 写入（跟踪编号：W-23827287），必须在 Setup 中启用。
Supervisor 监控 OrgValues	未实现	OmniSuperConvMonitor、OmniSuperAgentSneakpeek、OmniSuperClientSneakpeek、OmniSuperWhisper、OmniSuperAdminSkillQueue 是 OrgValues，目前没有已验证且受支持的外部写入 API。
Omni Inbox	未实现	侧边栏叶节点会固定 Omni 侧边栏（isOmniPinnedViewEnabled）；不会创建或配置 Omni Inbox、控制台应用或实用程序项。

参考资料

文件	阅读时机
references/gap-catalog.md	了解无头模式的缺口（登录行为单选项、Agentforce 路由目标、Field Service 技能路由）以及协调器对各项缺口的处理方式
examples/output-templates.md	输出报告前阅读——其中包含规范的 Setup Summary、Skill Outcomes 和 Manual Actions 区块