service-native-voice-recording-transcription-configure

配置原生语音录制和转录（无头模式）

以编程方式开启或关闭组织的原生语音（Thunderbird Voice）通话录制和通话转录，让更改对不使用 Service Console UI 的无头/API 驱动支持会话生效。录制和转录是两个独立的偏好设置——此技能可将其中一个或两个设置为所需状态（不更改另一个），并返回结构化 JSON 确认信息。

范围

• 范围内：通过 sf CLI Metadata API 部署（通用 Settings 容器，成员 ThunderbirdVoice），在 ThunderbirdVoiceSettings 元数据中将 enableCallRecording 和/或 enableCallTranscription 设置为所需状态——true（启用）或 false（禁用）；返回配置结果的 JSON 确认信息。用户未指定的偏好设置保持当前值。
• 范围外：更改任何其他 ThunderbirdVoiceSettings 布尔值（例如通话录制编辑、SIP 录制）——同级设置仅供读取以便保留，绝不会设置或报告；对现有录音或转录内容中的个人身份信息（PII）进行编辑/清理；转录用户提供的音频文件；配置原生语音/Thunderbird 通道本身；编写 Flow、Apex 或权限集。这些不属于此技能的范围——请单独处理。

---

必需输入

继续操作前，收集或推断以下信息：

• 目标组织——sf CLI 已通过身份验证的组织别名或用户名。部署使用现有的 sf 登录；不需要会话 ID 或访问令牌。默认值：该组织的默认目标。使用 sf org display -o <alias> 确认连接正常。
• 要设置的偏好——录制、转录或两者。默认值：两者，因为无头采集通常需要录制和转录。如果用户只指定其中一个，则仅设置该项，并保持另一项当前值不变。
• 所需状态——针对每项指定的偏好，启用（on/true）或禁用（off/false）。默认值：启用，除非用户要求关闭。严格遵循禁用请求——绝不重新启用用户要求关闭的偏好。

工作流

所有步骤均按顺序执行。不得跳过或调整顺序。如果遇到阻碍，请停止并询问缺失的组织上下文。

1. 确认这两项偏好是分别建模的。 录音（enableCallRecording）和转录（enableCallTranscription）是同一元数据类型上的两个独立布尔值——绝不能将它们合并为一个标志。最终确认必须分别报告每一项。

2. 运行配置脚本。 使用每项偏好的所需状态运行 scripts/enable-recording-transcription.sh --target-org <alias>：--recording on|off 和/或 --transcription on|off。如果未指定偏好标志，默认会将两项都启用。示例：关闭两项 → --recording off --transcription off；仅启用录音 → --recording on（转录保持原样）；仅停用转录 → --transcription off。该脚本会（通过 Settings 容器）检索 ThunderbirdVoiceSettings，检查组织权限门控，仅将指定的标志设为所请求的值，同时保留所有其他字段；随后通过试运行部署进行验证、执行部署，并通过往返检索进行验证。使用 --dry-run 可检索并验证，但不持久化。运行 scripts/enable-recording-transcription.sh --help 查看所有选项。

3. 关于 Metadata API 合约，请阅读 references/thunderbird-voice-settings.md——其中记录了该类型、两个布尔值、Settings 容器清单、v68.0+ 版本下限，以及先检索再检查门控的流程。脚本生成的清单模板为 assets/package.xml。

   此操作使用 sf CLI Metadata API 部署，而不是原始 SOAP 调用。成员是不含 Settings 后缀的 mdApiType（ThunderbirdVoice），且清单版本必须为 >= 68.0——低于此版本时不会公开这些字段。

4. 仅更改指定的目标字段，并设为所请求的状态。 部署的设置文件会将用户指定的偏好（enableCallRecording 和/或 enableCallTranscription）设为所请求的值（启用时为 true，停用时为 false）；所有其他 ThunderbirdVoiceSettings 布尔值（包括用户未指定的目标偏好）均保持检索到的值。不得添加或切换其他布尔值，也绝不能将停用请求强制改回 true——这些操作超出此技能范围，或与请求相悖。

5. 返回确认 JSON。 输出一个与 assets/confirmation-output.json 匹配的单一 JSON 对象：包含元数据 type 和 fullName、通过无头/API 部署应用该设置的信息，以及分别针对两项偏好给出的字段名称和最终启用状态（true/false，即部署后的状态，无论该项是已更改还是保持原样），另加总体 status（ENABLED、DISABLED 或 CONFIGURED）。其中还包含一个 preserved 数组，列出每个同级布尔值（例如 enableCallRecRedaction、enableSipRecording）及其检索到的值——这证明这些同级字段均未被更改；合规调用方需要明确确认“其他内容未变”。报告同级字段的值不代表更改该字段。成功运行时，脚本会在 stdout 输出此对象；请将其原样作为交付内容——不要移除 preserved 块。

---

规则 / 约束

约束	原因
将通话录制和转录作为两项独立偏好处理	它们是不同的布尔值（enableCallRecording、enableCallTranscription）；将它们合并会失去单独启用其中一项的能力，也不符合输出约定。
通过通用 Settings 容器及成员 ThunderbirdVoice 进行部署	ThunderbirdVoiceSettings 不是可检索的顶层类型名称；Settings 容器（成员 = 去掉 Settings 后缀的 mdApiType）是 sf CLI 路径，并使用组织的 sf 登录信息，不需要会话 ID。
清单版本必须 >= 68.0	ThunderbirdVoiceSettings 字段仅在 API v68.0 及更高版本中公开；低于此版本时，检索到的类型为空或不存在。
先检索再部署；保留所有同级字段	部署会完整替换文件——以检索到的文件为基础可保留其他偏好，并允许检查门控条件。
在 preserved 块中报告保留的同级字段，但绝不更改它们	合规调用方需要明确确认“其他内容未变”；确认信息会原样回显每个同级字段检索到的值。回显值不等于设置值——部署的文件只会更改指定的目标字段。
严格遵循请求的状态——启用表示 true，禁用表示 false	禁用请求却悄悄重新启用偏好（或在其仍开启时报告成功）属于正确性错误；必须准确设置请求的值，并报告组织实际返回的值。
报告状态前通过往返检索进行验证	部署“成功”并不能证明结果正确；只有重新检索后每项指定偏好均为请求的值，才能报告最终状态。
输出必须是单个有效的 JSON 对象	无头调用方会以编程方式处理确认信息；仅有文字说明无法使用。
输出中不得包含会话 ID、访问令牌、电话号码、录制 URL 或转录内容	这些属于机密信息 / 个人身份信息；确认信息只报告配置状态。

---

注意事项

问题	解决方法
Property 'enableCallRecording' not valid in version <N> / Settings type 'ThunderbirdVoice' is unknown	API 版本过低。 这些字段仅在 v68.0 及更高版本中公开。将 --api-version 提高到 68.0 或更高——这不是功能门控。
检索返回空的 <ThunderbirdVoiceSettings/>（没有字段）	组织权限门控 orgHasNativeVoiceAllowed 处于关闭状态——Native Voice 尚未配置。通过配置流程 / Blacktab 启用；元数据无法开启尚未配置的功能。
尝试将 ThunderbirdVoiceSettings 作为类型名称进行检索	使用 Settings 容器及成员 ThunderbirdVoice（去掉 Settings 后缀的 mdApiType）；完整类型名称不是可检索的成员。
将两项偏好合并为一个开关（例如 recordingAndTranscription: true）	在已部署文件和确认 JSON 中都保留两项独立条目。
部署不完整的设置文件	以检索到的文件为基础，以保留同级偏好的值；不完整的文件可能会重置它们。
缺少 jq / sf	脚本依赖它们；请安装它们，或在已包含这些工具的环境中运行（在 metadata.cliTools 中声明）。

---

输出要求

交付内容：

• 在 stdout 上输出单个 JSON 确认对象，格式遵循 assets/confirmation-output.json — 包含元数据目标、无头 / API 部署路径、分别报告两项偏好及其启用状态的内容、回显每个 同级布尔值（保持不变）的 preserved 数组，以便调用方确认其他内容未变，以及整体 status。

不会向组织的源代码树写入任何文件——脚本会在临时 SFDX 项目中运行并报告结果。

---

参考文件索引

文件	何时阅读
scripts/enable-recording-transcription.sh	第 2 步 — 运行以检索 → 设置命名字段 → 验证 → 部署 → 确认（支持 --recording on|off、--transcription on|off、--dry-run、--api-version、--help；默认两者均为 on）。
references/thunderbird-voice-settings.md	第 3 步 — 了解元数据类型、两个布尔值、Settings 清单、v68.0+ 的最低版本要求，以及门槛检查。
assets/package.xml	第 3 步 — 脚本生成的 Metadata API 清单模板；阅读以了解或手动构建检索/部署流程。
assets/confirmation-output.json	第 5 步 — 要返回的 JSON 确认信息的准确结构。