field-service-data-capture-form-designer-configure

设计数据采集表单（根据文字描述或图片 / PDF）

此技能会根据用户输入（自然语言描述或现有表单的 PDF/图片）生成中间 JSON 规范，征求用户对方案的批准，然后调用 fs-data-capture-form-deployer 进行编译和部署。

此技能的触发条件

用户请求创建数据采集流程 / Field Service Mobile 表单。输入有以下两种模式：

• 文字描述模式 — 用户以纯文本描述表单，且未附加文件。例如：
  • “创建一个资产检查数据采集表单，包含资产 ID、状况评级、照片和备注。”
  • “构建一个库存转移 Field Service 表单，包含零件重复器、源位置和目标下拉列表。”
  • “生成一个 DataCaptureFlow，用于采集三项内容：站点名称、联系人信息和备注字段。”
• 图片 / PDF 模式 — 用户提供 .pdf、.png、.jpg 或 .jpeg 文件的路径。例如：
  • “将 /tmp/inspection.pdf 转换为数据采集流程”
  • “根据这张图片构建 Field Service 表单：~/Downloads/site-visit.png”
  • “将这张纸质表单转换为 DataCaptureFlow”（附有图片）

根据输入判断模式：**如果用户提供了 .pdf / .png / .jpg / .jpeg 路径，则使用图片 / PDF 模式；否则使用文字描述模式。**提取完成后的步骤（第 2-6 步）对两种模式都相同。

工作流

1. 阅读来源（取决于模式）

文字描述模式 — 仔细阅读描述；不要虚构字段。 仅提取用户实际提及的字段。不要根据检查表单“通常包含什么”而臆造额外字段。如果用户说“包含资产 ID、状况评级、照片和备注”，则输出四个字段，而不是八个。

如果用户的描述过于模糊，无法生成可用表单（“构建一个用于采集服务预约相关内容的表单”），请先提出一两个有针对性的问题，再进行提取——询问所需字段、是否存在父记录，以及提交时应执行什么操作。不要猜测。

然后应用 reference/extraction-from-prompt.md 中的文字描述证据规则。

图片 / PDF 模式 — 读取文件。 对用户提供的路径使用 Read 工具。PDF 和图片均受原生支持。如果 PDF 超过 10 页，请询问用户表单位于哪些页面（大型 PDF 需要 Read 工具提供 pages 参数）。

然后应用 reference/extraction-from-image.md 中的控件证据规则。

2. 提取中间 JSON

应用与模式相对应的提取参考（第 1 步）中的所有规则。输出架构由构建技能的输入契约定义：

• field-types.md — 字段类型 → 组件映射、必需的 Flow 样板、选项 / 重复器结构、可见性规则。
• post-screen-automation.md — 可选 postScreen 区块的架构。

将 JSON 写入 /tmp/data-capture-spec.json。

3. 确定预期结果

数据采集表单是手段，而非目的。在请求用户批准之前，先确定用户提交表单后，Salesforce 中应发生什么：

• 如果用户明确说明要创建或更新什么（“为每个部件创建一个 ProductTransfer”），或者来源/文件名强烈暗示了预期结果（Inventory Transfer → ProductTransfer；Asset Inspection → WorkOrderLineItem），则输出一个 postScreen 区块，其中包含指定的对象和字段 API 名称（或最可能的名称）。如果是猜测，请在确认步骤中列出每个 valueRef / field，以便用户更正名称。
• 如果预期结果不明确，且用户没有提供任何提示，则在确认步骤中提出这个问题（“提交此表单后应执行什么操作？”），并给出根据表单领域拟定的具体选项。
• 仅包含屏幕而不包含 postScreen 的流程也是有效的，但必须在确认步骤中明确说明。

完整的结果询问规则，请参阅与模式相对应的提取参考。

4. 向用户确认（必经关卡）

部署之前，向用户展示你计划构建的内容。使用 AskUserQuestion 作为移交给 Build 的关卡。

在问题正文或周边文字中，清楚说明：

1. 预期结果。 最后一个屏幕后，流程会执行什么操作，例如：“提交表单后，会为 Parts 重复器中的每一行创建一个 ProductTransfer”，或“此流程仅采集数据，管理员将在 Flow Builder 中配置自动化。”如果已生成 postScreen 区块，请列出其中引用的每个 Salesforce 对象名称和每个 field API 名称。对象/字段 API 名称是部署后错误最常见的来源。
2. formTitle 和拟定的 <FlowApiName>（PascalCase，不含空格）。
3. 屏幕数量和字段总数（重复器中的子字段也要计入）。
4. 生成的所有可见性规则，以及这些规则所依据的选项值。
5. 每种字段类型，尤其是专用类型，以及所依据的证据。对于规范中的每个 Signature、UploadFile、UploadImage、Images、Matrix、Address、Lookup、FileView 或 Repeater，都要列出字段名称和证据——在文本模式下，列出文本证据（“用户说‘部件重复器’”“用户描述了一个签名区”）；在图像模式下，列出视觉证据（“damagePhoto → UploadImage，因为来源中有一个相机图标按钮”）。这些会部署为真正具有功能的组件（dcSignature、dcUpImage 等），因此，如果用户在文本中只是想要文本字段，或在图像中只能指出字段的标签，却仍生成这些组件，就是最常见的提取错误。如果没有相应的控件词汇/视觉控件，请降级为 ShortText/LongText/Numeric，并明确指出。
6. **Lookup 对象和 FileView 文件名。**对于每个 Lookup，列出你选择的 lookupObject（Salesforce 对象 API 名称）和 lookupSearchFields。对于每个 FileView，列出 fileName。这些名称是部署后错误的常见来源，应展示给用户，以便用户更正。
7. 回退为带标签的 dcTextInput 占位符的所有字段（仅在 Lookup 没有 lookupObject 和 FileView 没有 fileName 时才会发生）。

向用户提供清晰的选项：

• 批准并部署——继续执行步骤 5。
• 先编辑规范——允许用户直接编辑 /tmp/data-capture-spec.json，然后从步骤 4 重新开始。
• 取消——停止，不进行部署。

未经明确批准，不得继续执行步骤 5。

5. 移交给 Build

获得批准后，将已批准的规范移交给 fs-data-capture-form-deployer。选择符合 ^[A-Z][A-Za-z0-9_]*$ 的 <FlowApiName>（默认使用 formTitle 的 PascalCase），然后遵循该技能的工作流——整个流程通过 Codey 运行时经由 REST 完成，不使用 sf CLI、不使用脚本，也不使用 .flow-meta.xml：

1. 验证组织身份验证——参阅 fs-data-capture-form-deployer/SKILL.md §1（通过 REST 执行低成本的 SELECT Id FROM Organization LIMIT 1 探测；运行时会解析已连接的组织——此系列不管理别名）。
2. 根据已批准的规范内联构建 Flow Metadata JSON——参阅 deployer §3 和 reference/flow-metadata-json.md。Agent 直接组装 Metadata 对象；没有 XML 编译步骤。
3. 部署——通过单次 POST /services/data/vXX.0/tooling/sobjects/Flow 发送 { "FullName": "<FlowApiName>", "Metadata": { ... } }——参阅 deployer §4。

部署后，按照 fs-data-capture-form-deployer/SKILL.md §5 中的报告和错误处理步骤操作。

6. 询问是否将表单附加到父记录

成功部署后，Flow 已存在，但不会显示在任何 Service Appointment / Work Order 的 Forms 选项卡中。询问用户是否要将其附加到特定父记录（典型的“待处理表单”模式）。如果要，请按照 fs-data-capture-form-deployer/SKILL.md §6 中的附加步骤操作——只需单次 POST /services/data/vXX.0/sobjects/DynamicDataCapture（不使用脚本）。在 SA 上下文中测试时，请将表单附加到 SA 的父 Work Order，而不是 SA 本身——FSL Mobile 会从父 Work Order 读取 Forms。

不在范围内

• 修改已部署的 Flow → fs-data-capture-form-editor。
• 手动编写转换器不会生成的模式（视觉润色 HTML、真实的 dcSignature/dcUpImage、主从关系子记录、支持用的 CustomObjects）→ fs-data-capture-reference 库技能。

此技能中的文件

• reference/extraction-from-prompt.md——根据用户描述选择字段类型的文本证据规则、屏幕分组、可见性规则、结果引导、验证清单。用于文本模式。
• reference/extraction-from-image.md——根据渲染控件选择字段类型的控件证据规则、重复器提取规则、屏幕分组、可见性规则、结果引导、验证清单。用于图像 / PDF 模式。