sales-call-scoring-configure

销售通话评分 — 配置

在 Salesforce 组织中配置 Call Coaching（也称 AI Call Scoring / Coaching Competencies）。 检测组织的当前状态，启用其获准启用的依赖功能，并通过 SOAP Metadata API 切换 ECICallScoringEnabled 组织偏好设置。

范围

范围内

• 仅适用于已启用 ECI 的组织。 此技能支持使用 ECI（Einstein Conversation Insights）方案的组织（初始探索范围：MVP 仅支持 ECI）。
• 检测组织处于 PRD 范围内的 4 种状态中的哪一种。
• 如果 Einstein Generative AI Platform 已关闭，则将其启用（PRD 授权的依赖项）。
• 通过 SOAP Metadata API v68 将 enableECICallScoring 切换为 true。
• 验证更改是否生效。
• 幂等 — 状态 3 和 4（已启用）时正常结束。

范围外

• River Rush / Momentum 检测。 等该方案上线后再处理 — 请参阅“关键注意事项”。目前无法区分仅启用 Momentum 的组织与其他 ECI 关闭的组织；它会收到 Phase 3 中的通用消息“ECI is not enabled”，而非针对 Momentum 的消息。
• 启用 ECI 或 Momentum 本身。 PRD 明确规定不在范围内；此技能会检测并提示管理员通过 Setup 启用 ECI。
• 许可证配置。 缺少基础许可证（Agentforce for Sales、ECI 许可证）时，需提交工单给客户团队。
• Competency CRUD。 由同一技能中的配套脚本处理 — 请参阅下文的“Competency CRUD 工作流”（§S3-§S10）和“执行顺序”矩阵。

前置条件

1. sf CLI 已通过身份验证 — sf org login web --alias <org-alias>。
2. 已获许可并启用 ECI 方案：组织权限 ConversationPilot（Phase 0 购买门槛）和 enableCallCoaching 偏好设置（Phase 1，即 ConversationPilotPref 偏好设置）。（River Rush/Momentum 属于另一项方案，由相同的服务端门槛控制，但此技能目前尚未检查 — 请参阅“关键注意事项”。）
3. 组织所在 pod 上的站点门槛 com.salesforce.eci.callScoringEnabled 已开放 （由 RelEng 控制；管理员无法切换）。

Einstein GenAI Platform 是软性前置条件 — 如果尚未启用，技能会自动启用它。

澄清问题

询问管理员：目标组织别名是什么？是否属于 Sandbox 刷新场景？（该偏好设置具有 disableOnSandboxCopy=true，因此每次刷新后都必须重新切换 — 这是正常情况，并非失败。）

管理员沟通指南

重要： 此技能面向管理员，而非开发者。完整的 13 条规范及各条说明见 references/admin-communication.md — 在此技能中首次回复前请先查阅。以下是关键规则摘要：

1. 所有 bash 命令都在后台运行（run_in_background: true）。
2. 使用管理员的语言，不使用实体名称 — 使用“Call Coaching”、“Coaching Competency”、“已启用/未启用”。在主要聊天文本中绝不要出现 EnablementCompetencyDef、enableECICallScoring、EvaluationInstructions、SourceCompetencyTemplate。
3. 隐藏技术细节 — 不展示记录 Id、DeveloperNames、Template 枚举键、HTTP 代码、SOAP 响应、curl/jq 内部细节、脚本路径或阶段编号。例外：S9 验证 Markdown 表格（请参阅 references/competency-crud.md §S9）。
4. 自动衔接 — 脚本输出 Next: <script> 时，在同一轮中运行该脚本，无需询问。例外：状态 3 → 规则 #13。
5. 只询问一次使用内置方案还是自定义方案 — 首次设置 competency 时（状态 3，意图未明确），显示 install-ootb-competencies.sh --list，并让管理员选择。这是此技能中唯一需要在写入前征求 Claude 许可的环节。
6. 对幂等情况保持简短 — 如果已启用/已安装，简要说明后继续。

完整的 13 条规范见 references/admin-communication.md，其中包括错误呈现、结果与步骤的汇报方式，以及 S9 例外情况的缘由。

工作流

阶段 0 — 身份验证

通过共享的 scripts/shared/auth.sh 辅助脚本解析组织身份验证 （resolve_org_auth "$ORG_ALIAS"），本技能中的每个脚本都会引入该脚本： 验证别名格式，调用 sf org display 获取 instanceUrl 和 accessToken（如果 CLI 隐去了令牌，则改用 sf org auth show-access-token）， 拒绝非 HTTPS 实例 URL；如果组织无法访问或无法提取令牌，则安全失败，并明确提示执行 sf org login web --alias <alias>。如果 ACCESS_TOKEN/INSTANCE_URL 已经为同一别名导出——例如，父级 shell 已解析身份验证，并在同一会话中连续运行这些脚本——则跳过解析并重用缓存值。此辅助脚本不处理 orgId；enable-call-scoring.sh 会单独获取该值（通过其自身的 sf org display），仅用于状态横幅。

阶段 0 — ECI 购买检查

在检测任何状态之前，通过 Tooling API（OrganizationSettingsDetail，采用与阶段 3 中 ECICallScoringAI 检查相同的方式）查询 ConversationPilot OrgPermission。这是许可证／购买检查，与下文的 enableCallCoaching 不同（后者是管理员为已获得许可证的组织设置的 Setup 开关）：

• **未启用：**退出并显示："无法开启 Call Coaching，因为此组织没有使用 Call Coaching 所需的 Einstein Conversation Insights。若要继续，管理员可以前往 Setup → Salesforce Go → Einstein Conversation Insights，或联系销售代表，了解如何购买 ECI。"以非零状态退出。
• **已启用：**继续进行阶段 1 的 enableCallCoaching 检查。

阶段 1 — 状态检测

在 /services/Soap/m/68.0 对两个设置类型执行 SOAP readMetadata：

1. ConversationalIntelligenceSettings → 读取 enableCallCoaching（ECI 开关） 和 enableECICallScoring（当前 Call Coaching 状态）。
2. EinsteinGptSettings → 读取 enableEinsteinGptPlatform。

（不读取 RiverRushSettings/riverRushEnabled（Momentum）。该检测将延后到 River Rush 开关正式上线时；关于何处重新添加，请参阅关键注意事项。）

通过 Tooling API 查询现有能力项： SELECT COUNT() FROM EnablementCompetencyDef。

将组织划分为 4 种状态之一：

状态	检测方式
1a. 不可用（没有 ECI 许可证）	无法读取 ConversationalIntelligenceSettings
2. 可用，未启用	enableCallCoaching=true 且 enableECICallScoring=false
3. 已启用，没有能力项	enableECICallScoring=true 且数量 = 0
4. 已启用，包含能力项	enableECICallScoring=true 且数量 > 0

阶段 2 — 根据状态分流

• **状态 1a：**以 PRD 原文消息退出："AI call coaching is not available in this org and they need Agentforce for Sales."以非零状态退出。
• **状态 3 / 状态 4：**以状态码 0 退出，并显示准备好设置能力项的消息。
• **状态 2：**继续。

阶段 3 — 启用前置条件（仅状态 2）

• 许可证门槛（首先检查）： 查询 Tooling API 中的 OrganizationSettingsDetail，检查 ECICallScoringAI OrgPermission。只有明确返回 false 才拒绝，并以以下消息退出："AI call coaching is not available in this org and org requires Agentforce for Sales license."（非零退出码。）如果无法读取权限——查询因 INVALID_TYPE 被拒绝（某些组织版本，例如 Developer Edition）或未返回任何行——则视为未知并继续；对于无法读取的信号，切勿采取默认拒绝策略。Einstein GenAI 的 TYPE_UNAVAILABLE 预检查可捕获大多数未获许可的组织；启用时的 updateMetadata 写入是最终检查。这与阶段 0 的 ConversationPilot 门槛一致：任何无法得出结论的读取都会延后处理。即使 enableCallCoaching/enableECICallScoring 已读取到肯定值，也必须执行此检查，因为这些设置本身并不能确认组织已获得许可。必须在下面的 ECI 关闭检查之前执行——未获许可的组织和已获许可但切换为关闭的组织都会读取到 enableCallCoaching=false，因此先检查 ECI 会把许可证缺失误判为可通过自助方式调整的 Setup 开关（NoLicense 评估数据集正是用于防止这种回归）。
• 如果 ECI 处于关闭状态：拒绝并提供 Setup 指引，非零退出。此技能不会启用 ECI（PRD 明确规定）。仅有 Momentum 的组织也会在此处被拦截，因为不会单独检测 Momentum——它会收到同样的通用消息，而非 Momentum 专属消息。
• 如果 Einstein GenAI 处于关闭状态：对 EinsteinGptSettings 执行 SOAP updateMetadata，并将 enableEinsteinGptPlatform=true。PRD 明确授权执行此操作。如果已开启，则跳过 updateMetadata 调用，并告知管理员该功能已启用。如果更新失败是因为组织未获得使用 EinsteinGptSettings 的许可（或明确拒绝且没有故障信息），则告知管理员需要 Agentforce for Sales 才能启用 AI Call Scoring；没有该许可时，仍可通过 Salesforce Go 设置来配置手动通话评分。如果是明确的身份验证／权限或网络／超时故障，则单独提示（检查 CLI 会话／重试），不要使用许可证相关消息，因为这些故障并不表示缺少许可证。

阶段 4 — 启用 Call Coaching（仅状态 2）

如果 enableECICallScoring 已读取到 true（例如，该设置在阶段 1 读取后、到达此处前由其他操作更改），则跳过更新，并告知管理员该功能已启用。否则，对 ConversationalIntelligenceSettings 执行 SOAP updateMetadata，并将 enableECICallScoring=true。要求 <success>true</success>。

阶段 5 — 验证（仅状态 2）

重新读取 enableECICallScoring。要求其值为 true。失败时打印 SOAP 响应。

关键注意事项

• API 版本为 v68.0，而非 v64.0。在某些构建中，较低 API 版本的 ConversationalIntelligenceSettings 架构中没有 enableECICallScoring，因此 v68 是安全的最低版本。Pipeline 技能使用 v64，是因为其目标字段（SalesDealAgentSettings.enableDealAgent）在该版本中存在；Call Scoring 则不存在。
• 不要对这个偏好设置使用 sf mdapi deploy。它可能会静默失败：CLI 报告成功，但偏好设置实际上并未切换。请使用原始 SOAP updateMetadata——响应中的 <success> 布尔值才是权威结果。
• 服务器端的门控范围比本技能涵盖的范围更广。 orgHasCallScoring 访问检查允许 ECI 分支或 River Rush（Momentum）分支——参见 CoachingCompetenciesFeature.isFeatureAvailableInOrg()。根据 spike 确定的 MVP 范围，本技能有意仅涵盖 ECI 分支。
• 目前有意不检测 River Rush（Momentum），这并非疏忽——该分支尚未上线。enable-call-scoring.sh 以前会读取 RiverRushSettings.riverRushEnabled，并以单独的“State 1b”消息拒绝仅启用 Momentum 的组织；也会发出 Momentum 可用但未启用的提示；这两项逻辑现已移除。River Rush 上线后，请重新添加这些逻辑（读取设置、“State 1b”分支和 Phase 3 提示）——已移除的代码可从此文件的 git 历史记录中恢复。
• disableOnSandboxCopy=true——每次沙盒刷新都会禁用此偏好设置。刷新后，管理员重新运行此技能是预期的操作方式；幂等性检查可以确保这样做安全。
• 组织所在 pod 上必须启用站点开关 com.salesforce.eci.callScoringEnabled。该开关无法由管理员切换，也无法通过 SOAP 读取。如果开关关闭，updateMetadata 会返回格式正确的响应，其中包含 <success>false</success> 和 <errors><statusCode>…</statusCode></errors> 块——不会生成 SOAP <Fault>。parse_soap_response 会提取 statusCode，并通过 WRITE_ERROR:… 分类呈现。
• ECI 配置是异步的。 enableCallCoaching 开启后的一小段时间内，依赖于它的 enableECICallScoring 字段在服务器端为只读，updateMetadata 会返回 INSUFFICIENT_ACCESS_OR_READONLY。enable-call-scoring.sh 会将此情况映射为临时提示“仍在完成启用过程——请等待几分钟后重新运行”，而非终止性失败。
• 每次 SOAP 调用都受 30s 超时限制（enable-call-scoring.sh 中的 CURL_TIMEOUT；与此仓库中唯一现有的超时先例——Pipeline 技能的 setup-all.sh——保持一致），并通过 shared/soap.sh 中的 parse_soap_response 分类为 true、false、AUTH_ERROR:...、TYPE_UNAVAILABLE:...、WRITE_ERROR:… 或 NETWORK_ERROR。这样可以区分“组织未获得此设置的许可”“身份验证／权限错误”“服务器拒绝写入并返回特定 statusCode”以及“网络／超时错误”，而不是将它们全部折叠为空字符串，或把原始 SOAP XML 直接输出给管理员。
• enable-call-scoring.sh 使用原始 SOAP，而非 sf api request rest。 此技能中的其他脚本都使用 sf api request rest，由 CLI 端到端管理身份验证。enable-call-scoring.sh 是唯一的例外：它直接调用 SOAP Metadata API（readMetadata／updateMetadata），因为 Salesforce CLI 没有非 beta 命令可以读取／写入 ConversationalIntelligenceSettings 等对象的 SOAP Metadata；此外，对这个特定字段使用 sf mdapi deploy 会出现上文所述的静默失败。这是有意为之且范围明确的例外，并非疏忽。

参考资料

• 参考技能（规范的单一 OrgPref 模式）： skills/sales-agentforce-pipeline-management-configure/
• SOAP 辅助函数：scripts/shared/soap.sh（从 Pipeline 技能复制而来 — redact_token、parse_soap_response）
• 服务端门控（声明式访问检查）： ConversationalIntelligence.accessChecks.xml — orgHasCallScoring = ECI 分支或 River Rush 分支；orgHasECICallScoringWithAI 在此基础上增加 Einstein GenAI + ECICallScoringAI 许可证权限。
• 偏好声明： ConversationalIntelligence.settings.xml — <orgPreference name="ECICallScoringEnabled" mdApiName="enableECICallScoring" ...>
• Java 功能注册（如果存在 SetupDiscoveryService REST/MCP 封装器，此处将是入口）：CoachingCompetenciesFeature.java

能力项 CRUD 工作流

Phase 5 确认 Call Coaching 已启用（或 Phase 1 检测到状态 3/4）后，Claude 会在同一轮中直接运行 Next: 脚本。记录通过 Tooling API 在 EnablementCompetencyDef（设置实体，keyPrefix 1nA，模块 conversation-udd）上管理。上限：每个组织最多 8 个同时处于活动状态的能力项（CoachingCompetenciesFeature.MAX_ACTIVE_COMPETENCIES）。

所有脚本共用 shared/auth.sh / resolve_org_auth — 令牌会在连续调用间传递，无需重新进行身份验证。Tooling API 写入在适用时通过 sf api request rest 执行；部分脚本（自定义 CRUD 变体、最佳实践安装器）会改用原始 curl，以便更精细地控制请求格式。

脚本分为两个并行系列：

• 通用版 — {create,edit,toggle,get}-competency.sh — 适用于任何能力项。
• 自定义 CRUD 变体 — *-custom-competency.sh — 使用 SpecificCallsOnly 过滤器 JSON 并加强验证，以强化写入路径。

当管理员的意图明确是自定义能力项（由 S5 创建）时，优先使用自定义变体；对于 OOTB 或来源不明的记录，则退回使用通用版。

完整规范 — 包括 S3 至 S10 的脚本契约、S5 的 Q1-Q4 对话式起草流程、管理员意图 × 组织状态执行矩阵，以及连续调用检查点 — 见 references/competency-crud.md。每当管理员的请求涉及能力项记录（列出、安装、创建/编辑、激活、验证、删除）时，都应查阅该文档。

独立脚本（摘要）

脚本	用途
enable-call-scoring.sh <alias>	检测状态；如果 Einstein GenAI 未启用，则启用它，并切换 Call Coaching 首选项（Phase 0-5）。
list-competencies.sh <alias> [--verbose|--json]	列出所有能力及其状态。默认适用于管理员；--verbose 会添加 Ids/DeveloperNames；--json 仅供调用该脚本的 Agent 使用。
install-ootb-competencies.sh <alias> [--dry-run]	安装 6 个 PRD 规范的 OOTB 能力。
install-best-practice-competencies.sh <alias> [--dry-run] [--only "Name1,Name2"]	安装 7 个 Momentum 最佳实践参考提示词。--only 按 MasterLabel 筛选。
create-competency.sh <alias> <payload.json>	创建一个能力（通用，可用于 OOTB 或自定义能力）。
create-custom-competency.sh <alias> <payload.json>	创建一个自定义能力（强化版本，S5 优先使用）。
edit-competency.sh <alias> <ident> ...	编辑描述/说明（通用）。
edit-custom-competency.sh <alias> <ident> ...	编辑描述/说明（自定义 CRUD 版本）。
toggle-competency.sh <alias> <ident> <activate|deactivate>	启用/停用（通用）。
toggle-custom-competency.sh <alias> <ident> <activate|deactivate>	启用/停用（自定义 CRUD 版本）。
get-competency.sh <alias> <ident> [--field <f>]	获取一条记录或单个字段（通用）。
get-custom-competency.sh <alias> <ident> [--field <f>]	获取一条记录或单个字段（自定义 CRUD 版本）。
verify-ootb-competencies.sh <alias> ["Name" ...]	确认预期的能力存在且已启用 — 输出 S9 中管理员可见的 Markdown 表格。
暂无删除脚本	使用 sf data delete record --sobject EnablementCompetencyDef --record-id <Id> --use-tooling-api — 参见 §S10。

管理员验证

运行成功后，管理员可以独立验证：

通过 UI — Salesforce Go → Coaching Competencies 现在应该可以访问， 并显示该功能已启用及已配置的能力。

通过 CLI — 两个 Tooling API 查询：

# Feature enabled?
sf data query --target-org <alias> --use-tooling-api \
  --query "SELECT IsEciCallScoringEnabled FROM ConversationalIntelligenceSettings"

# Competencies configured?
sf data query --target-org <alias> --use-tooling-api \
  --query "SELECT MasterLabel, IsActive, SourceCompetencyTemplate FROM EnablementCompetencyDef ORDER BY MasterLabel"

资源

• assets/ootb-competencies.json — 6 个 PRD 规范的 OOTB 提示词正文 （由 install-ootb-competencies.sh 安装）。
• assets/best-practice-competencies.json — 7 个 Momentum 最佳实践 提示词正文（S5 编写参考；也可通过 create-competency.sh 安装）。