用途
本技能用于以编程方式（无头 / API 驱动）为 Native Voice（Thunderbird Voice）开启或关闭通话录音与通话转写，使变更对不经过 Service Console UI 的无头 / API 驱动支持会话生效。录音与转写是两个相互独立的偏好，本技能可将其中任一或两者设置为请求的状态，并保持另一个不变，最后返回结构化的 JSON 确认。
主要能力
- 将 ThunderbirdVoiceSettings 元数据上的 enableCallRecording 和/或 enableCallTranscription 设置为请求状态（true 启用 / false 禁用）。
- 通过 sf CLI 的 Metadata API 部署完成设置，使用通用 Settings 容器，成员为 ThunderbirdVoice。
- 返回 JSON 确认，报告最终配置结果。
- 未指定的偏好保持其当前值。
使用方式
所需输入（执行前收集或推断）：
- 目标 org：sf CLI 已认证的 org 别名或用户名。部署使用现有 sf 登录，不请求 session id 或访问令牌。默认使用 org 的默认目标。可用 sf org display -o <alias> 确认连通性。
- 哪些偏好：录音、转写或两者。默认两者，因为无头采集通常同时需要录音与转写。若用户只指定一个，则只针对该偏好，另一个保持当前值。
- 期望状态：对每个指定偏好为启用（on/true）或禁用（off/false）。默认启用，除非用户要求关闭。必须严格遵循禁用请求，绝不将用户要求关闭的偏好重新启用。
工作流（所有步骤顺序执行，不可跳过或重排；若受阻则停止并询问缺失的 org 上下文）：
- 确认两项偏好分别建模。录音（enableCallRecording）与转写（enableCallTranscription）是同一元数据类型上的不同布尔值，绝不合并为一个组合标志。最终确认必须分别报告。
- 运行配置脚本：scripts/enable-recording-transcription.sh --target-org <alias>，按偏好指定期望状态：--recording on|off 和/或 --transcription on|off。不带偏好标志时默认两者开启。示例：两者关闭 → --recording off --transcription off；仅启用录音 → --recording on（转写保持原样）；仅禁用转写 → --transcription off。脚本会检索 ThunderbirdVoiceSettings（通过 Settings 容器）、检查 org-perm 门控、仅将指定标志设置为请求值并保留其他所有字段、通过干跑部署校验、部署、再通过往返验证。使用 --dry-run 可仅检索与校验而不持久化。运行 scripts/enable-recording-transcription.sh --help 查看所有选项。
- 关于 Metadata API 契约，阅读 references/thunderbird-voice-settings.md——其中记录了类型、两个布尔值、Settings 容器清单、v68.0+ 版本下限以及先检索的门控检查。脚本生成的清单模板为 assets/package.xml。
- 仅更改指定的目标字段至请求状态。部署的设置文件仅将用户指定的偏好（enableCallRecording 和/或 enableCallTranscription）设置为请求值（true 启用，false 禁用）；其他所有 ThunderbirdVoiceSettings 布尔值（包括用户未指定的目标偏好）保持其检索到的值。不要添加或翻转其他布尔值，绝不将禁用请求强制改回 true。
- 返回确认 JSON。输出单个 JSON 对象，匹配 assets/confirmation-output.json：元数据类型与 fullName、通过无头/API 部署应用、两项偏好各自分别报告字段名与结果启用状态（true/false，即部署后的当前状态，无论是否被更改或保持原样），以及整体状态（ENABLED、DISABLED 或 CONFIGURED）。还包含 preserved 数组，回显每个同级布尔值（如 enableCallRecRedaction、enableSipRecording）及其检索时的值——以证明同级字段未被改动，合规调用方需要此明确的“其他均未变动”保证。报告同级值并非更改它。成功运行时脚本在 stdout 打印该对象；原样呈现作为交付物——不要剥离 preserved 块。
适用场景
- 无头 / API 驱动的支持会话中需要配置 Native Voice 录音与转写。
- 需要以编程方式、可重复地开启或关闭录音与转写偏好。
- 合规场景需要明确证明除目标偏好外其他设置未被改动。
限制
不在范围内：更改任何其他 ThunderbirdVoiceSettings 布尔值（如同级字段仅读取以保留，绝不设置或报告）；从现有录音或转写中脱敏/清除 PII；转写提供的音频文件；开通 Native Voice / Thunderbird 渠道本身；编写 Flow、Apex 或权限集。这些需另行处理。
约束与注意事项：
- 录音与转写必须作为两个独立偏好建模，合并会失去单独启用能力并违反输出契约。
- 必须通过通用 Settings 容器（成员 ThunderbirdVoice）部署，因为 ThunderbirdVoiceSettings 不是可检索的顶层类型名。
- 清单版本必须 >= 68.0，低于此版本字段不暴露。
- 部署前先检索并保留所有同级字段，因为部署是全文件替换。
- 在 preserved 块中报告同级字段但绝不更改它们。
- 严格遵循请求状态：启用即 true，禁用即 false；静默重新启用或报告成功但实际仍开启属于正确性失败。
- 报告状态前必须通过往返验证；部署“成功”不是证明。
- 输出必须是单个有效 JSON 对象，供无头调用方程序化消费。
- 输出中不得包含 session id、访问令牌、电话号码、录音 URL 或转写内容。
常见问题：
- 属性在版本 <N> 无效 / Settings 类型 ThunderbirdVoice 未知：API 版本过低，字段仅在 v68.0+ 暴露，将 --api-version 提升至 68.0 或更高，这不是功能门控。
- 检索返回空的 <ThunderbirdVoiceSettings/>（无字段）：org-perm 门控 orgHasNativeVoiceAllowed 关闭，Native Voice 未开通，需通过 provisioning/Blacktab 启用，元数据无法翻转未开通的功能。
- 尝试以类型名检索 ThunderbirdVoiceSettings：应使用 Settings 容器，成员为 ThunderbirdVoice（mdApiType 去掉 Settings 后缀）。
- 将两个偏好合并为一个开关：应在部署文件和确认 JSON 中保留两个独立条目。
- 部署部分设置文件：应从检索到的文件开始，以免同级偏好被重置。
- 缺少 jq / sf：脚本依赖它们，需安装或在具备它们的环境中运行（在 metadata.cliTools 中声明）。
输出预期：
- 在 stdout 输出单个 JSON 确认对象，形状符合 assets/confirmation-output.json——包含元数据目标、无头/API 部署路径、两项偏好分别报告及其启用状态、preserved 数组回显每个同级布尔值（未更改）以便调用方确认其他均未变动，以及整体状态。
- 不向 org 的源码树写入任何文件——脚本在临时 SFDX 项目中工作并报告结果。
参考文件索引：
- scripts/enable-recording-transcription.sh：步骤 2 运行，用于检索 → 设置指定字段 → 校验 → 部署 → 验证（支持 --recording on|off、--transcription on|off、--dry-run、--api-version、--help；默认两者开启）。
- references/thunderbird-voice-settings.md：步骤 3 阅读，了解元数据类型、两个布尔值、Settings 清单、v68.0+ 下限及门控检查。
- assets/package.xml：步骤 3 阅读，脚本生成的 Metadata API 清单模板，用于理解或手工构建检索/部署。
- assets/confirmation-output.json：步骤 5 阅读，要返回的 JSON 确认的确切形状。