field-service-voice-to-form-configure

设置 Voice to Form

在全新的 Field Service 组织中，在 Field Service Mobile 上配置 Voice to Form。Voice to Form 让移动工作人员可以在表单或记录编辑屏幕上轻点麦克风并口述内容。Einstein 生成式 AI 会解析语音并填充相应字段。

此功能有两个变体。它们共用权限基础，但通过不同的开关启用：

变体	功能	显示位置	底层开关
Voice to Record Edit (V2RE)	在移动工作人员可编辑的对象上（Work Order、Service Appointment、Asset、Contact、Account、自定义对象等）为标准记录编辑屏幕填入语音内容	记录编辑屏幕上的麦克风图标	FieldServiceMobileSettings.IsShowEditFullRecord = true（组织级行）+ FieldServiceVoiceToRecordEdit 系统权限
Voice to Form Data Capture (V2F, Beta)	为管理员在 Flow Builder 中构建的 Discovery Framework / Data Capture 流程填入语音内容	Data Capture 表单上的麦克风图标	FieldServiceVoiceToForm 系统权限 + 每个表单的 LLM Targetable 标记（仅限 UI 切换）

本技能按照 Salesforce 在以下页面记录的顺序，完整介绍这两种变体的设置：

• help.salesforce.com/s/articleView?id=service.mfs_voice_to_form_setup.htm（V2F Data Capture）
• help.salesforce.com/s/articleView?id=service.mfs_voice_to_record_edit_setup.htm（V2 Record Edit）

本技能具有幂等性。在已配置的组织中重新运行时，不会应用任何更改。

运行时约定：本技能中的每次组织交互都是通过 Codey 运行时分发的 REST 调用（本地使用 dispatch / 在共享界面中使用托管的 Headless 360 MCP）。本技能不依赖执行环境——无需 sf CLI、shell 脚本、本地 Python、jq、临时文件、元数据部署或 Apex。检测通过一组 REST GET 完成；LDS 切换通过 Tooling FieldServiceSettings.Metadata PATCH 完成；V2RE 组织开关通过 sObject PATCH 完成；语音权限集通过单个 sObject POST 完成；授权授予通过关联对象 POST 完成。唯一没有可调用 API 的步骤——每个表单的 LLM Targetable 标记——通过 Agent 原生浏览器 MCP 操作，或以 Setup 深层链接的形式交给管理员（点击完成，而非 shell 步骤）。不要调用 shell。

---

平台说明

• 所有 API 路径均使用 vXX.0——固定使用组织当前的 API 版本（v62.0 或更高版本；V2F Beta 假定使用较新的版本）。
• 标记为 Tooling 的端点会分发到 /services/data/vXX.0/tooling/...；其余端点使用核心 Data API（/services/data/vXX.0/...）。
• Codey 运行时会解析并刷新已连接的组织，并按需生成令牌——本技能不会管理组织别名、实例 URL 或访问令牌。
• 有几个设置步骤确实只能在 Setup 中通过点击完成（Einstein 基础设置向导的组织偏好设置、每个表单的 LLM Targetable 标记）。对于这些步骤，本技能会提供准确的 Setup 深层链接供管理员点击；不会尝试通过脚本操作。
• 以下所有 SOQL 均通过 GET /services/data/vXX.0/query?q=<soql>（Data API）或 GET /services/data/vXX.0/tooling/query?q=<soql>（Tooling）分发。返回记录的读取结果由 Agent 在内联处理中处理——无需通过 shell 解析。

---

版本与许可

• 版本。 Field Service 核心功能、托管软件包和移动应用可在 Lightning Experience 的 Enterprise、Unlimited 和 Developer 版本中使用。
• 移动端使用资格。 每位移动工作人员都需要 Field Service Mobile PSL（FieldServiceMobilePsl）才能登录应用。在现代 Field Service 组织中，该 PSL 是叠加在任何标准用户许可证之上的权限集许可证——没有单独的“Field Service Mobile”用户许可证 SKU。（早期文档的说法并非如此；请以第 0 步中实时查询 PermissionSetLicense 的结果为准。）
• V2RE 使用资格。 使用 Voice to Record Edit 的移动工作人员需要 Einstein for Field Service PSL（EinsteinFieldServicePsl）。
• V2F（Beta）使用资格。 使用 Voice to Form on Data Capture 的移动工作人员需要 Agentforce for Field Service PSL。Voice to Form Beta 还要求在自定义权限集上配置 V2F 和 V2RE 系统权限（参见第 4 步——应使用精简的自定义权限集，而非克隆版本）。分配前请向客户经理确认许可证使用资格，以避免产生意外费用。
• 应用版本。 V2RE 要求使用 Summer '25 或更高版本的 Field Service Mobile App。V2F 要求使用最新版本。

---

前提条件

运行设置流程前，请确认以下所有条件：

1. 版本 + 附加组件。 组织已启用 Einstein for Field Service（V2RE）和/或 Agentforce for Field Service（V2F）。
2. Einstein 生成式 AI 已完全启用，而不仅仅是已预配。 第 1.5 步的探测会标记此项。EinsteinLlm 运行时使用资格必须处于活动状态（实时 LLM 调用返回 200，而非 FUNCTIONALITY_NOT_ENABLED）。试用版和 SDO 组织通常已分配 PSL，但运行时从未启用——这是移动应用出现“We couldn't recommend any updates”错误最常见的原因。
3. 如果还要使用 Prompt Builder 处理基于数据的内容，则需预配并启用 Data Cloud。 V2F 帮助文章要求启用此项。实际使用中，V2RE 无需激活 Data Cloud。
4. 仅适用于 V2F： 按照 help.salesforce.com/s/articleView?id=service.mfs_data_capture_setup.htm 设置 Data Capture。该技能会在第 5 步检测 DC 表单；如果没有表单，则会交由此代码库中的 fs-data-capture-form-deployer 技能创建。
5. 管理员用户具有正确的权限： Customize Application、Manage Profiles and Permission Sets 和 Manage Flows。

---

设置流程

按顺序执行各步骤。每一步都会先读取组织状态，再进行写入；如果前置条件不满足，该步骤会显示失败原因并停止，不会更改组织状态。以下每次读取和写入都通过一次 dispatch 调用完成。

步骤 0：检测配置状态并确定后续路径

运行六项检测查询，对组织进行分类。几个看似直观的查询（FlowDefinitionView、Tooling FieldServiceMobileSettings、Flow.DeveloperName）无法使用——以下字段名称和查询接口均已验证可用。

1. Einstein / Agentforce / Mobile Field Service PSL — GET /services/data/vXX.0/query：

SELECT DeveloperName, MasterLabel, TotalLicenses, UsedLicenses
FROM PermissionSetLicense
WHERE DeveloperName IN ('EinsteinFieldServicePsl','FieldServiceMobilePsl','AgentforceForFieldServicePsl')

V2F 演示需要 EinsteinFieldServicePsl 和 FieldServiceMobilePsl；AgentforceForFieldServicePsl 为可选项。步骤 7 中只分配此处查询到的 PSL。

2. 已提供的 EinsteinFieldServiceUser 权限集（只读克隆源参考） — GET /services/data/vXX.0/query：

SELECT Id, Name, Label FROM PermissionSet WHERE Name = 'EinsteinFieldServiceUser'

存在 → FSL 软件包已安装，且版本支持 V2F。此权限集由软件包提供且为只读；此技能不会编辑它（也不会克隆它——参见步骤 4）。

3. Lightning Data Service 模式（LDS） — Tooling GET /services/data/vXX.0/tooling/query：

SELECT FullName, Metadata FROM FieldServiceSettings

读取 Metadata.enableLsdkMode。true → LDS 已启用，继续。false → 步骤 1 将其切换为启用。V2F-DC 需要 LDS，V2RE 则可选。

4. V2RE 组织开关 — 常规 sObject GET /services/data/vXX.0/query（不是 Tooling）：

SELECT Id, MasterLabel, IsDefault, IsShowEditFullRecord FROM FieldServiceMobileSettings

记录 IsDefault = true 的行（或唯一一行）的 Id——步骤 2 的 PATCH 会以此为目标。

5. 已启用的数据捕获表单 — Tooling GET /services/data/vXX.0/tooling/query（不是 FlowDefinitionView）：

SELECT Id, MasterLabel, ProcessType, Status, DefinitionId
FROM Flow
WHERE ProcessType IN ('DataCaptureFlow','DiscoveryFrameworkDataCaptureFlow') AND Status = 'Active'

显示时使用 MasterLabel——Flow 没有 DeveloperName 列（查询该字段会返回 400 INVALID_FIELD）；API 名称使用 Definition.DeveloperName。如果结果为零行 → 步骤 5 将交接给 fs-data-capture-form-deployer。

6. 已有的 V2F 自定义权限集 — GET /services/data/vXX.0/query：

SELECT Id, Name, Label FROM PermissionSet WHERE IsCustom = true AND Name LIKE '%V2F%'

一行 → 之前的运行已创建该权限集；跳过步骤 4 并复用其 Id。零行 → 步骤 4 将创建该权限集。

根据检测结果对组织进行分类：

诊断 1（PSL）	诊断 2（权限集）	诊断 5（表单）	操作
缺失	任意	任意	停止。 联系 Salesforce AE，购买 Einstein/Agentforce for Field Service。此技能无法继续。
存在	缺失	任意	继续执行步骤 1.5。 Einstein 基础设置尚未完成；先运行向导，再进行其他操作。
存在	存在	缺失	继续。 V2RE 将顺利完成设置。V2F-DC 将在步骤 5 交接给 DC 技能。
存在	存在	存在	继续。 两种变体都将顺利完成设置。

步骤 0.5：选择目标技术人员用户

Voice to Form 是一项按用户启用的功能：每位技术人员都需要 Field Service Mobile PSL、Einstein for Field Service PSL、V2F/V2RE 权限集，以及一条有效的 ServiceResource 记录。此技能一次面向一位技术人员，以便管理员在大范围推出前先进行试点。

询问管理员：“您是否有想要启用 Voice to Form 的特定技术人员用户？”

**如果有：**管理员提供用户名或 User Id。通过两次 GET /services/data/vXX.0/query 查询验证该用户处于启用状态且拥有 ServiceResource 记录（将提供的值代入绑定的 WHERE 条件）：

SELECT Id, Name, Username, IsActive, Profile.Name FROM User
WHERE (Username = :tech OR Id = :tech) AND IsActive = true

SELECT Id, Name, ResourceType FROM ServiceResource
WHERE RelatedRecordId IN (SELECT Id FROM User WHERE Username = :tech OR Id = :tech)
  AND IsActive = true

**如果没有：**自动选择一位候选用户——非管理员配置文件中第一位处于启用状态且 ResourceType='T' 的技术人员，并展示该选择以供确认。使用 GET /services/data/vXX.0/query：

SELECT Id, Name, RelatedRecord.Id, RelatedRecord.Username, RelatedRecord.Name, RelatedRecord.Profile.Name
FROM ServiceResource
WHERE IsActive = true AND ResourceType = 'T'
  AND RelatedRecordId != null AND RelatedRecord.IsActive = true
  AND RelatedRecord.Profile.Name NOT IN ('System Administrator')
  AND (NOT RelatedRecord.Profile.Name LIKE '%Customer Community%')
  AND (NOT RelatedRecord.Profile.Name LIKE '%Partner Community%')
ORDER BY Name LIMIT 1

记录该技术人员的 User.Id（记为 TECH_USER_ID）和 Username，供后续分配步骤使用。需要时，以相同方式解析当前运行管理员的 User Id（SELECT Id, Username FROM User WHERE ...）——Codey 运行时已知连接身份，因此无需调用 org display。

步骤 1：为 Field Service Mobile 应用启用 Lightning Data Service

Discovery Framework 表单上的 Voice to Form（V2F-DC）会在支持 LDS 的移动容器中呈现。V2RE 无需 LDS 也能运行，但启用 LDS 不会造成影响，而且 V2F-DC 必须启用 LDS，因此请提前一次性完成。

从 Winter '25 开始，新组织默认启用 LDS；所有组织都将在 Spring '26 前自动迁移。

FieldServiceSettings 是一个 Tooling sObject，其配置存储在 JSON Metadata 字段中，结构与步骤 0 诊断 3 读取的相同。因此，启用 LDS 需要通过 Tooling 执行读取-修改-写入 PATCH，而不是部署元数据文件。这里没有 .settings-meta.xml，不需要 SFDX 项目，也不需要 sf project deploy start——这条路径从来没有必要；Tooling Metadata 接口才是真正的 REST 路径（同级技能 fs-data-capture-form-deployer 使用相同模式设置 FieldServiceSettings 的共享首选项）。

1a. 读取设置单例（步骤 0 诊断 3 已读取，但需重新读取以获取完整的 Metadata 对象及其行 Id）——Tooling GET /services/data/vXX.0/tooling/query：

SELECT Id, FullName, Metadata FROM FieldServiceSettings

如果 Metadata.enableLsdkMode 已为 true，则表示 LDS 已启用——跳至步骤 1.5。否则，记录行 Id（经过 base64 编码的单例 Tooling id）和完整的 Metadata 对象。

1b. 将完整的 Metadata PATCH 回去，并设置 enableLsdkMode: true——PATCH /services/data/vXX.0/tooling/sobjects/FieldServiceSettings/{Id}：

{ "Metadata": { "...all sibling keys from the GET...", "enableLsdkMode": true } }

发送在 1a 中读取的整个 Metadata 对象，只将 enableLsdkMode 改为开启状态——部分请求正文会将省略的组织首选项置空（fieldServiceOrgPref、enableWorkOrders、搜索字段数组等）。返回 204 即表示成功。

1c. 验证设置是否确实已切换——重新运行 1a 的 Tooling 读取，并确认 Metadata.enableLsdkMode == true。这可以避免罕见的 SDO/试用组织情况：写入报告成功，但标记仍为 false。如果标记未切换，请提供 Setup 深层链接，让管理员手动切换：

LDS Setup UI (fallback — only if the PATCH did not persist):
  <instanceUrl>/lightning/setup/FieldServiceSettings/home
  Enable 'Lightning SDK for Field Service Mobile' under the Lightning SDK section.

（Codey 运行时知道实例 URL；此技能只提供相对 Setup 路径，供管理员使用。）

步骤 1.5：确认 Einstein 生成式 AI 运行时已开启

这一步最容易被遗漏。如果未启用，麦克风图标仍会在设备上显示，转录也会正常工作，但每次语音尝试都会失败，并显示 “我们无法推荐任何更新。请重试。”——这是因为 LLM 运行时返回了 FUNCTIONALITY_NOT_ENABLED: [EinsteinLlm]，而 enableEinsteinGPT 组织首选项从未切换为开启状态。

1.5a. 实时探测运行时。 这是唯一可靠的测试——不同版本中的 Einstein 设置 Tooling 查询并不可靠。调用 GET /services/data/vXX.0/einstein/prompt-templates?pageSize=5：

• 200，且包含 promptRecords 数组（至少有一行，例如 Salesforce 管理的默认提示词 einstein_gpt__summarizeContact）→ LLM 运行时已开启。继续执行步骤 2。
• 400 FUNCTIONALITY_NOT_ENABLED: [EinsteinLlm] → 运行时已关闭。执行 1.5b。

1.5b. 如果探测失败，请向管理员提供向导深层链接。 该向导确实只能通过 UI 操作——此技能无法也不会尝试点击完成向导。请提供相对 Setup 路径（运行时会解析实例 URL）：

Einstein LLM runtime is OFF. Walk the wizard end-to-end.

PRIMARY (start here):
  /lightning/setup/EinsteinSetup/home

Wizard sub-pages:
  Generative AI:    /lightning/setup/EinsteinGPTSetupHome/home
  Trust Layer:      /lightning/setup/EinsteinTrustSetup/home
  Data Cloud:       /lightning/setup/DataCloudSetup/home
  Prompt Builder:   /lightning/setup/EinsteinPromptStudio/home
  Models config:    /lightning/setup/EinsteinModelsConfiguration/home

In order:
  1. Open the PRIMARY link. Toggle 'Turn On Einstein' -> accept terms.
  2. Open the Generative AI sub-page. Step through each numbered stage
     (enable the org pref, set up Trust Layer, acknowledge data usage,
      enable Prompt Builder).
  3. If the wizard prompts for Data Cloud, open Data Cloud Setup and activate.
     If it's not visible, refresh or re-login; if still missing, the org needs
     a Data Cloud SKU (a CRT to Salesforce Support).
  4. Re-run the 1.5a probe. If it now returns promptRecords, continue to Step 2.

Most common SDO/trial-org symptom: PSLs all assigned, EinsteinSetup page exists,
but the runtime entitlement was never turned on. 'Turn On Einstein' flips it.

1.5c. 管理员完成向导后重新探测。 重新运行 1.5a 的 dispatch 调用。只有在返回 promptRecords 后才能继续。

步骤 2：启用 Voice to Record Edit 组织级开关

V2RE 的组织级开关位于 FieldServiceMobileSettings 上，这是一个常规 sObject（不是 Tooling Settings 类型——早期文档对此有误）。相关字段是 IsShowEditFullRecord（标签为“Enable full edit on records”）。设置记录有名称（默认名为“Field Service Mobile Settings”），并带有一个 IsDefault 标志，用于控制哪些配置文件会继承该设置。

2a. 查找默认设置行（参见步骤 0 诊断 4），或创建一行——如果诊断 4 未返回任何行，请通过 POST /services/data/vXX.0/sobjects/FieldServiceMobileSettings 创建默认设置：

{
  "MasterLabel": "Field Service Mobile Settings",
  "DeveloperName": "Field_Service_Mobile_Settings",
  "IsDefault": true,
  "IsShowEditFullRecord": true
}

返回 201 表示已创建新行，其 Id 已满足步骤 2b 的要求——跳过 PATCH。

2b. 将现有行的 IsShowEditFullRecord（和 IsDefault）设为 true——PATCH /services/data/vXX.0/sobjects/FieldServiceMobileSettings/{Id}：

{ "IsShowEditFullRecord": true, "IsDefault": true }

返回 204 表示成功。重新读取该行（参见步骤 0 诊断 4），确认这两个字段均为 true。如果没有 IsDefault = true，此开关只会对通过 MobileSettingsAssignment 明确映射到该设置行的配置文件生效——对于试点，IsDefault = true 是最简单的做法。此 PATCH 操作是幂等的：重复发送相同值会返回 204，且不会产生任何变化。

用户在设备上看到的内容。 根据 Salesforce 帮助文档（mfs_actions_order.xml）：当 IsShowEditFullRecord = true 且用户拥有对象的编辑权限时，Edit Work Order、Edit Work Order Line Item 和 Edit Service Appointment 会在 Work Order Overview 屏幕的操作启动器中显示，位于 Quick Actions 之后。移动应用会缓存设置——技术人员必须先注销再重新登录，新操作才会显示。

步骤 3：确认 V2F + V2RE 系统权限列存在

Salesforce 提供两个不同的系统权限——每种变体各一个。它们会在自定义权限集上启用（步骤 4）。PermissionSet 的 describe 列如下：

• V2F（Beta）： FieldServiceVoiceToForm — 列 PermissionsFieldServiceVoiceToForm
• V2RE： FieldServiceVoiceToRecordEdit — 列 PermissionsFieldServiceVoiceToRecordEdit

describe 中存在这些列，即表示组织级功能标志测试通过。调用 GET /services/data/vXX.0/sobjects/PermissionSet/describe，并筛选 fields[].name 中符合 PermissionsFieldServiceVoiceTo* 的字段：

• 两列均存在 → 组织已获许可使用 V2F Beta 和 V2RE。
• 只有 PermissionsFieldServiceVoiceToRecordEdit → 此组织未启用 V2F Beta。根据帮助文章：“需要识别您的 Customer Org ID，并为相应的沙盒或生产组织启用功能标志。” 向 Salesforce Support 提交 CRT，并提供组织 ID，然后继续仅设置 V2RE。
• 两列均不存在 → 此功能未获许可。停止。

describe 还会确认这两列均为 createable = true 和 updateable = true——因此步骤 4 可以只需一次 POST（见下文）。

第 4 步：创建同时启用两项系统权限的 V2F/V2RE 权限集

创建一个精简自定义权限集，通过单个 sObject POST 启用语音系统权限。PermissionSet 是可通过 REST 创建的 sObject，而且所有 Permissions* 系统权限列在创建时均可写入（第 3 步的 describe 已确认，全部 474 个 Permissions* 列均可创建和更新），因此权限集创建时就已启用语音权限——无需 XML、SFDX 项目或 sf project deploy start。

请勿“克隆” EinsteinFieldServiceUser。 该随附权限集不授予任何对象权限，且只包含两个无关的系统权限（ShowPreWorkBriefGA、FieldServiceCopilotActions）；其唯一实际内容是 Einstein 许可证关联，而第 7 步已通过 EinsteinFieldServicePsl PSL 提供该关联。仅包含语音系统权限布尔值的精简自定义权限集完全正确且足够——复制随附权限集不会带来任何额外内容。

发送 POST /services/data/vXX.0/sobjects/PermissionSet。根据第 3 步的 describe 设置请求正文——仅当存在该列时，才设置 PermissionsFieldServiceVoiceToForm: true（发送未知权限列会返回 400）：

{
  "Name": "EinsteinFieldServiceUser_V2F",
  "Label": "Einstein for Field Service User (V2F)",
  "Description": "Adds Field Service Voice to Form / Voice to Record Edit system perms. Assign to admins and mobile workers who use voice on the FSL mobile app.",
  "PermissionsFieldServiceVoiceToRecordEdit": true,
  "PermissionsFieldServiceVoiceToForm": true
}

• Name 必须匹配 ^[A-Za-z][A-Za-z0-9_]*$；自定义权限集会自动设置 IsCustom = true。
• 如果只存在 V2RE 列（V2F Beta 关闭），则省略 PermissionsFieldServiceVoiceToForm，创建仅包含 V2RE 权限的权限集。
• 返回 201 表示已创建新的 PermissionSet Id。
• 使用相同的 Name 再次运行会返回 400 DUPLICATE_DEVELOPER_NAME——第 0 步诊断 6 检查会在已有 V2F 权限集时跳过创建（复用其 Id）。

验证权限是否实际生效（创建操作可能报告成功，但下游触发器会清除某项权限）——GET /services/data/vXX.0/query：

SELECT Id, Name, PermissionsFieldServiceVoiceToRecordEdit FROM PermissionSet
WHERE IsCustom = true AND Name = 'EinsteinFieldServiceUser_V2F'

仅当组织中存在 PermissionsFieldServiceVoiceToForm 列时，才将其加入 SELECT。读取的权限列应为 true。保存该 Id，供第 7 步使用。

第 5 步：发现 Data Capture 表单并决定要为 V2F 启用哪些表单

此步骤仅对 V2F-DC 进行交互。第 2 步 + 第 4 步 + 第 7 步即可完全启用 V2RE（无需逐个切换表单）。

5a. 列出已启用的 DC 表单——使用 Tooling GET /services/data/vXX.0/tooling/query（不要使用 FlowDefinitionView，它在大多数组织中无法通过 Tooling 查询）：

SELECT Id, MasterLabel, ProcessType, Status, DefinitionId, Definition.DeveloperName
FROM Flow
WHERE ProcessType IN ('DataCaptureFlow','DiscoveryFrameworkDataCaptureFlow') AND Status = 'Active'
ORDER BY MasterLabel

显示表单数量；如果数量大于零，则列出每个表单（Definition.DeveloperName — MasterLabel）。

**5b. 如果没有表单：**移交给 fs-data-capture-form-deployer 技能，并停止启用 V2F-DC。V2RE 不受影响。（此移交是 SOR 中机器可读的 delegates_to 边，当 FORM_COUNT == 0 时触发。）

No Data Capture forms found.

Voice to Form fills DC forms; without at least one DC form, there is nothing to enable.
To create one, invoke the fs-data-capture-form-deployer skill in this repo
(../fs-data-capture-form-deployer/SKILL.md), or use fs-data-capture-form-designer
(prose or image/PDF input) for end-to-end form generation.

Re-run this skill from Step 5 after at least one DC form exists. Steps 0-4 are
idempotent; re-running is safe.

V2RE — Voice to Record Edit — does NOT depend on DC forms. If you only want V2RE,
Steps 1, 1.5, 2, 4, 7 are sufficient.

5c. 如果有一个或多个表单：询问管理员要启用哪些表单。默认选项为全部：

Which forms do you want to enable Voice to Form on?
  [a] All <FORM_COUNT> forms above (recommended for a fresh setup)
  [s] Some — pick a subset by row number or DeveloperName
  [n] None for now — re-run later

步骤 6：为选定的表单启用 LLM Targetable

已验证的缺口（截至 2026 年夏季，没有可调用的 API）。 LLM Targetable 标记没有任何元数据 API 表示形式。七个候选字段名（isLLMTargetable、isAIPromptable、isAvailableForLlm、voiceCaptureEnabled、supportsVoiceCapture、voiceToFormEnabled、isAITargetable）均被 Flow XSD 解析器拒绝，错误为 Element ... invalid at this location in type Flow。Tooling REST Flow.Metadata JSON 中不包含任何 LLM/voice/targetable 键，FlowDefinition.Metadata 也空空如也。此标记仅存在于 Flow Builder 的“Save as”对话框“Show Advanced”下。这是此技能中唯一无法消除的非 REST 步骤——它通过浏览器 MCP 以 Agent 原生方式处理，而非依赖任何执行环境。

有两种方法可以启用它。请根据运行时可用的功能选择。

路径 A（首选——以 Agent 原生方式驱动浏览器 MCP）。 已验证端到端可用：此路径在真实表单上启用该标记后，V2F 能在移动应用上正确触发。浏览器 MCP 是 Agent 运行时的一部分（类似 dispatch），而不是此技能依赖的 shell 或外部工具。

每个表单的操作顺序如下：

1. 在表单上打开 Flow Builder。根据步骤 5a 的列表解析每个选定表单对应的 Flow Id，然后让浏览器 MCP 导航至 <instanceUrl>/builder_platform_interaction/flowBuilder.app?flowId=<FLOW_ID>。（运行时会提供已验证的会话；此技能不会构建 frontdoor.jsp URL，也不会处理令牌。）
2. 点击工具栏上的 Save As New Version（打开“Save as”对话框）。
3. 点击对话框中的 Show Advanced。
4. 点击 LLM Targetable 标签（切换复选框）。
5. 点击对话框中的 Save 按钮 → Flow Builder 会创建 V(n+1) 作为 Draft。
6. 点击工具栏上的 Activate → Draft 会变为 Active，先前的版本会变为 Obsolete。

每个表单的浏览器 MCP 点击顺序（节点 ID 会随页面加载而变化，必须通过 browser_a11y_tree 重新获取）：

browser_navigate(<instanceUrl>/builder_platform_interaction/flowBuilder.app?flowId=<FLOW_ID>)
# Wait until the toolbar renders. The "Last saved on..." banner is reliable.
browser_a11y_tree(query="Save As New Version") -> click that node
browser_a11y_tree(query="Show Advanced")       -> click that node
browser_click("LLM Targetable")                 # aria-label resolution works for the label
browser_a11y_tree(query="dialog") -> drill into the dialog root, click "Save"
browser_a11y_tree(query="Activate") -> click that node

逐个表单验证——出现一个 VersionNumber 更高的新 Active 版本，即可确认保存已提交。使用 Tooling GET /services/data/vXX.0/tooling/query：

SELECT Definition.DeveloperName, VersionNumber, Status, LastModifiedDate FROM Flow
WHERE Definition.DeveloperName = :formApiName ORDER BY VersionNumber DESC LIMIT 3

最新一行应为 Active，且 LastModifiedDate 应接近本次运行时间。

路径 B（无浏览器 MCP 时的回退方案）——向管理员提供 deeplink。 为每个选定的表单提供一个 Flow Builder URL 和点击步骤。管理员打开每个 URL，然后依次点击 Save As New Version → Show Advanced → 勾选 LLM Targetable → Save → Activate：

Open each link. Click Save As New Version. Click Show Advanced.
Tick 'LLM Targetable'. Click Save. Click Activate.

  <form MasterLabel>
    <instanceUrl>/builder_platform_interaction/flowBuilder.app?flowId=<FLOW_ID>

**注意：**在 Active 流程上仅点击 Save（不使用 Save As New Version），Save 按钮会一直显示为灰色——Flow Builder 不会原地修改 Active 流程。版本属性对话框接受对 LLM Targetable 的点击操作，但单纯点击 Save 不会保存更改。Save As New Version 会创建 Draft V(n+1)；随后点击 Activate，即可将该 Draft 设为 Active。

表单保存并激活后，技术人员在设备上打开表单，确认是否出现麦克风图标（步骤 7 中的 permset 是前提条件，而非触发条件）。

步骤 7：分配权限集许可证和语音权限集

将步骤 0 诊断 1 返回的 PSL，以及步骤 4 的权限集，分配给管理员（以便其端到端验证）和技术人员（以便麦克风在设备上显示，且 LLM 调用能够正常进行）。每次授权都是一次关联对象 POST——每个（用户，授权）组合对应一行。若分配已存在，则返回 400 DUPLICATE_VALUE，调用方会将其视为成功的空操作。

7a. 分配每个检测到的 PSL——每个用户的每个 PSL 对应一次 POST /services/data/vXX.0/sobjects/PermissionSetLicenseAssign。从步骤 0 诊断 1 的结果中解析 PermissionSetLicenseId：

{ "AssigneeId": "<userId>", "PermissionSetLicenseId": "<pslId>" }

对 {管理员 User Id，技术人员 User Id} × {诊断 1 中的每个 PSL——至少包括 EinsteinFieldServicePsl 和 FieldServiceMobilePsl} 进行扇出处理。

7b. 分配步骤 4 的权限集——每个用户对应一次 POST /services/data/vXX.0/sobjects/PermissionSetAssignment：

{ "AssigneeId": "<userId>", "PermissionSetId": "<v2fPermsetId>" }

7c. 验证技术人员完整的移动用户权限栈。 对 TECH_USER_ID 执行以下四次 GET /services/data/vXX.0/query 查询，并确认每次都返回预期的行。这里缺少任何一行都会导致设备端必定失败，且不会显示错误消息。

1. 已分配 Field Service Mobile PSL：

   SELECT PermissionSetLicense.DeveloperName FROM PermissionSetLicenseAssign
   WHERE AssigneeId = :techId AND PermissionSetLicense.DeveloperName = 'FieldServiceMobilePsl'
   

2. 已分配 Einstein for Field Service PSL：

   SELECT PermissionSetLicense.DeveloperName FROM PermissionSetLicenseAssign
   WHERE AssigneeId = :techId AND PermissionSetLicense.DeveloperName = 'EinsteinFieldServicePsl'
   

3. 已分配语音权限集，且包含两项系统权限：

   SELECT PermissionSet.PermissionsFieldServiceVoiceToForm, PermissionSet.PermissionsFieldServiceVoiceToRecordEdit
   FROM PermissionSetAssignment
   WHERE AssigneeId = :techId AND PermissionSet.Name = 'EinsteinFieldServiceUser_V2F'
   

4. 已启用 ServiceResource，且拥有对父对象的编辑权限：

   SELECT Id, IsActive FROM ServiceResource WHERE RelatedRecordId = :techId AND IsActive = true
   

   SELECT SObjectType, PermissionsRead, PermissionsEdit FROM ObjectPermissions
   WHERE ParentId IN (SELECT PermissionSetId FROM PermissionSetAssignment WHERE AssigneeId = :techId)
     AND SObjectType IN ('WorkOrder','ServiceAppointment')
   

常见问题：

• 缺少 PSL： 用户的配置文件缺少 FSL Mobile PSL——请显式分配（7a）。
• 缺少或未完整授予编辑权限： Standard User 配置文件默认不会授予对 FSL 对象的编辑权限。将用户改为 Field Service Mobile 配置文件，或通过权限集授予读取和编辑权限。

以上四项全部通过后，技术人员的权限栈即已完整。设备端验证（见下文）是管理员的手动任务，不属于 REST 工作流。

步骤 8：设备端验证（手动）

技术人员在设备上登录 Field Service Mobile 应用，并确认语音填充功能正常。这是人工操作步骤——技能已完成组织配置。

请按顺序检查以下三项：

8a. V2RE — 显示 Edit Work Order 操作：

1. 打开今日排班中的一个 Work Order。
2. 点击 Actions（Overview 屏幕右上角）。
3. Edit Work Order、Edit Work Order Line Item 和 Edit Service Appointment 会显示在 Quick Actions 之后。

如果这些操作未显示，请退出登录后重新登录（设置缓存）。

8b. V2RE 麦克风 — 语音填充字段：

1. 点击 Edit Work Order。
2. 查看键盘旁是否有麦克风图标。
3. 点击麦克风并口述，例如：“将优先级设为 High，并添加描述：客户报告厨房漏水。”
4. 确认 Priority 和 Description 已填入内容。

如果麦克风显示，但语音功能报错 "We couldn't recommend any updates. Try again."，请返回步骤 1.5，重新运行实时 LLM 探测。Einstein 向导尚未完成。

8c. V2F-DC 麦克风 — 语音填充 DC 表单：

1. 打开某个 Work Order 的 Forms 选项卡（或相关列表）。
2. 打开步骤 6 中启用了 LLM Targetable 的某个 DC 表单。
3. 点击麦克风并口述。
4. 确认字段已填入内容。

如果表单上没有显示麦克风，说明 LLM Targetable 的点击操作未保存——请在 Flow Builder 中重新打开（步骤 6），确认复选框已选中，然后再次保存。

---

如果组织中没有任何 Data Capture 表单，该怎么办

步骤 5 会提前结束。该技能会移交给 fs-data-capture-form-deployer 技能（本仓库中的同级技能），并停止启用 V2F-DC。V2RE 不受影响——仅需执行步骤 1、1.5、2、4、7 即可启用 V2RE。

DC 技能至少创建一个表单后，如需继续启用 V2F-DC，请从步骤 5 重新运行。步骤 0–4 可安全重复执行。

---

配置参考

事项	所在位置	更改方式
移动端工作人员是否能看到麦克风	分配了 EinsteinFieldServiceUser_V2F 权限集 + 分配了 EinsteinFieldServicePsl PSL + 分配了 FieldServiceMobilePsl PSL	步骤 7（关联对象 POST）
Einstein 大模型运行时是否已启用	enableEinsteinGPT 组织偏好设置	Setup → Einstein → Get Started 向导（步骤 1.5，仅限 UI）
是否显示 Edit Work Order / Edit SA 操作	FieldServiceMobileSettings.IsShowEditFullRecord + FSM Settings 行的 IsDefault = true（或显式分配给配置文件）	步骤 2（sObject PATCH）
移动应用是否启用了 LDS	FieldServiceSettings.Metadata.enableLsdkMode	步骤 1（Tooling Metadata PATCH）
用户是否可以使用 V2RE	通过自定义权限集授予 FieldServiceVoiceToRecordEdit 系统权限	步骤 4、步骤 7
组织是否可以使用 V2F（Beta）	describe 中存在 FieldServiceVoiceToForm 系统权限 + Salesforce Support 启用了 Customer Org ID 功能标记	步骤 3 describe；如果缺少该权限，请提交 CRT 联系 Support
是否为特定 DC 表单启用了 V2F	Flow Builder Save 对话框中的 LLM Targetable 复选框（没有元数据 API 途径）	步骤 6（浏览器 MCP 或 deeplink）
哪个大模型负责语音转文本和字段映射	由 Salesforce 管理	客户无法配置

---

常见问题

录制编辑屏幕（V2RE）上未显示麦克风。

按以下顺序排查：

1. FieldServiceMobileSettings.IsShowEditFullRecord = true，并且该行的 IsDefault = true（步骤 2 验证）。
2. 用户拥有自定义权限集，且其中 PermissionsFieldServiceVoiceToRecordEdit = true（步骤 7c，第 3 项）。
3. 用户拥有 FieldServiceMobilePsl PSL（步骤 7c，第 1 项）。
4. 用户在步骤 2 后已退出并重新登录。
5. 用户使用的是 Summer '25 或更高版本的 Field Service Mobile App。

数据采集表单（V2F）上未显示麦克风。

按以下顺序排查：

1. 表单的 LLM Targetable = true（步骤 6 验证）。
2. 用户通过自定义权限集拥有 V2F 系统权限（步骤 7c，第 3 项 → V2F=true）。
3. 用户拥有 FSL Mobile PSL（步骤 7c，第 1 项）。
4. Customer Org ID 功能标志已启用。如果完成第 1–3 项后仍未显示，请提交 CRT 并注明组织 ID（步骤 3 说明）。
5. 表单不能只包含 Upload Image、Upload File、Image Preview、Matrix、Lookup 或 Signature 组件——这些组件不支持 V2F。

麦克风已显示，但语音功能失败，并提示“我们无法建议任何更新。请重试。”

这是最常见的故障情况。LLM 运行时未启用。按以下顺序排查：

1. 运行步骤 1.5a 中的探测。如果返回 FUNCTIONALITY_NOT_ENABLED: [EinsteinLlm]，说明运行时未启用。
2. 运行 Einstein Setup 向导（步骤 1.5b）。切换“Turn On Einstein”。完成所有编号步骤，包括 Trust Layer。
3. 重新运行探测。如果现在返回至少有一行记录的 promptRecords，说明运行时已启用。
4. 让技术人员在设备上重试。

如果运行向导后探测仍然失败，请联系 Salesforce Support 提交 CRT，并注明组织 ID 和错误代码 FUNCTIONALITY_NOT_ENABLED: [EinsteinLlm]。即使向导已完成，SDO 和试用组织有时仍需要 Salesforce 侧启用。

麦克风已显示，语音也已转录，但填入了错误的字段。

LLM 将语音映射到了错误的字段。常见情况有两种：

1. 字段标签相似。 两个标签相似的字段（“备注”和“技术人员备注”）会让映射出错。请使用更明确的名称。
2. 表单过长。 单屏表单过长会降低映射准确性。请拆分成多个屏幕。

移动端操作列表中未显示“编辑工单”操作。

根据 mfs_actions_order.xml：只有在 IsShowEditFullRecord = true 且用户有权编辑该对象时，“编辑”操作才会显示在“快速操作”之后。请按以下步骤排查：

1. 步骤 2 验证——IsShowEditFullRecord = true 且 IsDefault = true。
2. 步骤 7c，第 4 项——对 WorkOrder 和 ServiceAppointment 具有编辑权限。
3. 在移动应用中退出并重新登录——操作列表已缓存。

验证清单

在声明已在生产环境启用 Voice to Form 之前运行：

• 身份验证探测（SELECT Id FROM Organization LIMIT 1）返回预期的组织。
• 至少存在一个 Einstein/Agentforce for Field Service PSL，且 TotalLicenses > 0、UsedLicenses < TotalLicenses。
• 已启用 Field Service Mobile 的 LDS（通过 PATCH 后读回的实际 Metadata.enableLsdkMode 值验证，而不只是确认返回了 204）。
• 第 1.5 步探测返回 200，且包含 promptRecords。 对 /einstein/prompt-templates 的实时 LLM 调用至少返回一行，而不是 FUNCTIONALITY_NOT_ENABLED。
• FieldServiceMobileSettings.IsShowEditFullRecord = true，且同一行中的 IsDefault = true（或已明确分配给技术人员的配置文件）。
• 自定义权限集 EinsteinFieldServiceUser_V2F 存在，且 PermissionsFieldServiceVoiceToRecordEdit = true（启用 V2F Beta 时，还需满足 PermissionsFieldServiceVoiceToForm = true）。
• 已将该权限集分配给管理员和指定的技术人员。
• 技术人员已分配 FieldServiceMobilePsl 和 EinsteinFieldServicePsl，并且存在一条有效的 ServiceResource 记录。
• [ ]（仅限 V2F-DC）至少有一个 DC 表单已勾选 LLM Targetable，并有一个新的 Active 版本（验证第 6 步）。
• 设备端：技术人员退出登录后重新登录，打开工单，点击 Edit（V2RE）或打开 DC 表单（V2F），麦克风随即显示，语音输入会填入正确的字段。

---

约定

• 原生使用 REST，不依赖执行环境。 每次组织读取和写入都是通过 Codey 运行时分发的单个 dispatch REST 调用。此技能不使用 sf CLI、Shell、本地 Python 或 jq、临时文件、元数据部署或 Apex。唯一的非 REST 步骤（LLM Targetable）使用 Agent 原生的浏览器 MCP 或 Setup 深层链接，绝不使用 Shell。
• 幂等。 在已配置的组织上重新运行时不会应用任何更改。LDS/权限集/PSL 写入可安全重复运行（将 204/无操作或 DUPLICATE_VALUE 视为成功）。
• 从组织中读取 API 名称。 PSL DeveloperName、权限集 Id、表单 API 名称列表和 FSM Settings 行 Id 都会实时读取，绝不会硬编码。
• 优先信任运行时探测，而非 Tooling 设置探测。 即使在已完全启用的组织中，Ai4mSettings.enableEinsteinGPT 也会返回 <missing>。唯一可靠的检查是在第 1.5a 步执行实时 LLM 调用。
• 对 JSON Metadata 字段执行完整对象写入。 LDS PATCH 会发送完整的 FieldServiceSettings.Metadata 对象，只翻转一个键——部分请求体会将省略的组织偏好设为空值。
• 单一事实来源。 Salesforce 帮助文档记载了某个设置步骤时，此技能会引用相应文章，而不是重复或与其相矛盾。

---

管理员必须手动完成的步骤（仅点击操作）

技能无法通过 API 执行以下操作。每项操作都会提供一个 Setup 深层链接，供管理员点击：

时间	操作	原因
第 1.5b 步	打开 /lightning/setup/EinsteinSetup/home，点击“Turn On Einstein”，完成 Generative AI 子页面中的所有编号步骤	切换 enableEinsteinGPT 组织偏好。这是最重要的一步。若未完成，即使其他设置都正确，语音功能也会显示“We couldn't recommend any updates”并失效。
第 1 步（仅限备用方案）	打开 /lightning/setup/FieldServiceSettings/home，启用“Lightning SDK for Field Service Mobile”	仅当 Tooling Metadata PATCH 未能在顽固的 SDO/试用模板中持久生效时才需要。PATCH 是主要途径。
第 6 步（仅限路径 B 备用方案）	打开每个 Flow Builder URL，依次选择 Save As New Version → Show Advanced → 勾选 LLM Targetable → Save → Activate	不存在元数据 API 途径。路径 A 通过浏览器 MCP 自动执行；当运行时没有浏览器 MCP 时，使用此备用方案。
第 8 步	设备端：退出登录，然后重新登录 Field Service Mobile 应用	设置和权限集缓存；应用只有在新会话中才会获取更改。

---

相关技能

此仓库中的所有同级技能：

• fs-data-capture-form-deployer — 根据 Flow Builder 规范创建 Data Capture 表单。如果组织中没有表单，第 5 步会移交给此技能。
• fs-data-capture-form-designer — 根据自然语言提示词或纸质表单的照片/PDF 生成 DC 表单，然后通过 fs-data-capture-form-deployer 部署。
• fs-data-capture-form-editor — 修改现有 DC 表单。
• configure-field-service-mobile — 设置 FSL Mobile 组织级设置（LDS、Forms 选项卡可见性、品牌）；在第 1 步（LDS）以及使 V2F-DC 能在移动端呈现所需的 Forms 选项卡关联上，与此技能配合使用。
• fs-mobile-branding — 为 Field Service Mobile 应用应用品牌颜色。
• setting-up-pre-work-brief + customizing-pre-work-brief — 同属 Frontline AI 系列的配套技能。PWB 会在 Work Order Overview 选项卡中呈现 AI 简报；V2F 允许技术人员口述内容，填写该 Work Order 的表单或记录编辑屏幕。二者可无缝配合：PWB 用于上门服务前，V2F 用于服务期间。
• fs-data-capture-reference — Data Capture 概念入门；可作为有用的背景资料。
• salesforce-agx-* — AGX Flow Builder 系列（background-flow、screen-flow、data-retrieval-flow、orchestration-flow）；编写自定义 DC 流（而非为现有流启用 Voice）时可作为有用参考。

---

参考资料

外部资料（Salesforce 帮助）：

• Voice to Form（Data Capture）设置：https://help.salesforce.com/s/articleView?id=service.mfs_voice_to_form_setup.htm
• Voice to Record Edit 设置：https://help.salesforce.com/s/articleView?id=service.mfs_voice_to_record_edit_setup.htm
• Field Service Mobile 设置详情：https://help.salesforce.com/s/articleView?id=service.mfs_settings_details.htm
• Field Service Mobile 应用中显示的操作：https://help.salesforce.com/s/articleView?id=service.mfs_actions_order.htm
• 设置 Data Capture：https://help.salesforce.com/s/articleView?id=service.mfs_data_capture_setup.htm
• 构建 Data Capture 流：https://help.salesforce.com/s/articleView?id=service.mfs_data_capture_buildflow.htm
• Data Capture 限制和指南：https://help.salesforce.com/s/articleView?id=service.mfs_data_capture_limitations.htm
• 设置 Einstein Generative AI：https://help.salesforce.com/s/articleView?id=ai.generative_ai_enable.htm
• 用于 Field Service Mobile 的 Lightning Data Service：https://help.salesforce.com/s/articleView?id=service.mfs_lightning_data_service.htm

---

已知限制

• 语音转表单处于 Beta 阶段。 Salesforce 保留在不同版本间更改行为、权限名称或功能标志的权利。此技能针对 Spring '26 / Summer '26。
• LLM Targetable 没有元数据 API 路径。 经实测，Flow XSD 解析器会拒绝所有候选字段名称，Tooling REST Flow.Metadata JSON 中也不包含任何与 LLM 相关的键。每个表单都需要通过 Flow Builder UI 启用。步骤 6 的路径 A 通过浏览器 MCP 原生驱动此 Agent（已端到端验证）；路径 B 则提供深层链接，供管理员点击。这是此技能中唯一的非 REST 步骤。
• 客户组织 ID 功能标志。 V2F-DC 需要在 Salesforce 端为特定组织启用功能标志。此技能会通过 PermissionSet.PermissionsFieldServiceVoiceToForm describe 列进行检测，但无法切换该标志。如果缺少此列，请向 Salesforce Support 提交 CRT。
• Einstein LLM 运行时授权。 试用版 / SDO 组织通常已分配所有 PSL，但运行时从未启用。步骤 1.5 会检测并提示此问题；解决方法是在 UI 向导中完成点击流程。即使完成向导，SDO 组织偶尔仍需要 Salesforce 端启用。
• 顽固模板上的 LDS。 在少数 SDO / 试用版模板中，enableLsdkMode 写入报告成功，但实际上并未启用；步骤 1c 会重新读取以发现此问题，并回退到 Setup 深层链接。
• 组件类型覆盖范围。 DC 表单中的 V2F 不支持 Upload Image、Upload File、Image Preview、Matrix、Lookup 或 Signature 组件。如果表单完全由这些组件组成，则不会显示麦克风图标。