field-service-data-capture-form-editor-configure

编辑数据采集表单（在组织中）

此技能会修补已存在于已连接组织中的流。权威数据来源是部署流的 Metadata JSON，该数据通过 Tooling Flow sObject 实时获取——没有规范文件、没有 .flow-meta.xml、没有 zip，也没有 SFDX 项目。此技能会获取 JSON，在内存中编辑，然后将其 PATCH 回去。

运行时约定： 此技能中的所有组织交互都是通过 Codey 运行时分发的 REST 调用（在本地使用 dispatch／在共享界面中使用托管的 Headless 360 MCP）。此技能不依赖执行环境——不需要 sf CLI、本地 Python、临时文件或临时 SFDX 项目。身份验证探测、流获取和重新部署都是单次 REST 调用；JSON 补丁由 Agent 内联编写。不要调用 shell。

此技能的触发时机

• 用户提到一个现有流（Inventory_Transfer、Asset_Inspection 等）并要求更改。
• 用户粘贴 Flow Builder URL 并要求更改。
• 用户描述已部署流的部署错误或运行时错误。

如果用户要从头开始（文字描述、PDF、图像），请改用 design-* 技能。

工作流

1. 验证组织身份验证

通过轻量级身份验证探测，确认可以访问已连接的组织——分发 SELECT Id FROM Organization LIMIT 1（GET /services/data/vXX.0/query）：

• 返回 2xx 且 totalSize=1 → 会话令牌有效；继续。
• 返回 401/403 → 组织需要重新进行身份验证。告知用户并停止。（Codey 运行时会解析并刷新已连接的组织——此技能不管理组织别名。）

2. 获取实时流的 Metadata JSON

Tooling Flow sObject 会通过 JSON Metadata 字段公开流定义，其结构与部署器组装并 POST 的内容相同。获取过程需要两次调用，无需 CLI 或文件：

1. 根据 API 名称解析最新版本 ID。 使用以下内容分发 GET /services/data/vXX.0/tooling/query：

   SELECT Id, ActiveVersionId, LatestVersionId FROM FlowDefinition WHERE DeveloperName = '<FlowApiName>'
   

   编辑最新版本（LatestVersionId），以便补丁基于最新草稿，而不是过时的活动版本。如果 LatestVersionId 为 null，则回退到 ActiveVersionId。

2. 读取 Metadata 数据块。 分发 GET /services/data/vXX.0/tooling/sobjects/Flow/<versionId>，并从响应中获取 Metadata 对象。此 JSON 就是流本身——屏幕、选项、决策、变量和屏幕后续链。有关其结构，请参阅 ../fs-data-capture-form-deployer/reference/flow-metadata-json.md。

如果 FlowDefinition 查询未返回任何行，说明 API 名称有误，或用户指向了错误的组织。重试前请与用户确认。如果有帮助，可以列出组织中的候选流——分发 GET /services/data/vXX.0/tooling/query，并使用 SELECT DeveloperName FROM FlowDefinition ORDER BY DeveloperName。

3. 阅读检索到的 Metadata JSON 和规则说明

修改前，阅读检索到的 Metadata JSON，了解当前结构，然后阅读 fs-data-capture-reference/SKILL.md，了解平台的硬性约束。无论流程以 XML 还是 JSON 表示，这些约束都相同——重复的 XML 元素对应一个 JSON 数组，因此“分组”就是“数组”（参见 ../fs-data-capture-form-deployer/reference/flow-metadata-json.md 中的 JSON↔XML 映射规则）。请特别注意：

• 元素数组：screens、choices、decisions、recordLookups、recordCreates、recordUpdates、loops、assignments、variables 各自都是一个 JSON 数组。通过向对应数组追加元素来添加新元素——切勿引入重复的顶层键。
• CUD 顺序：连接器链中，任何 CUD（recordCreate/recordUpdate/recordDelete）之后都不能出现记录查询或屏幕。连续的 CUD 之间不能有决策。
• .AllItems 与 .AddedItems Repeater 访问器——沿用已部署流程使用的访问器，不要更改。
• 可见性规则：在 visibilityRule.conditions 条目中，leftValueReference 是选项 API 名称，而不是父字段的名称。
• 可见性规则之后设置必填字段反模式（参见 fs-data-capture-reference SKILL.md）。
• isLlmTargetable：必须使用 { "stringValue": "true" } 这类包装，而不是原始 JSON 布尔值——请匹配检索到的流程所用的格式。

fs-data-capture-reference/SKILL.md 底部的禁止模式表，是查找“哪些内容会导致此补丁出问题”最快的参考。

4. 规划补丁并与用户确认

编辑前，请告知用户：

1. 准备修改的内容——具体元素、具体行（引用 path:line），以及修改后的效果。
2. 是否需要调整架构顺序——例如，在当前没有 <recordLookups> 元素时添加一个，需要将其放在正确的分组中。请明确说明这一点。
3. 激活状态风险——补丁会将流程部署为新的草稿版本。用户在 Flow Builder 中激活新草稿前，活动版本（如果有）会继续运行。请告知用户这一点。
4. 值得提醒的事项——现有问题、已弃用模式或看起来有问题的验证规则。不要自动修复无关问题；请将其告知用户。

使用 AskUserQuestion 限制编辑操作。选项：

• 应用并部署——继续。
• 先让我看看修改内容——在聊天中展示仅针对编辑的 JSON 子树（要修改的具体字段、屏幕或规则）的修改前后对比，然后再次询问。不写入文件；补丁会保留在内存中，直到用户批准补丁。
• 取消——停止，不部署。

未经明确批准，不要继续执行第 5 步。

5. 应用补丁

编辑在步骤 2 中获取的内存 Metadata JSON 对象。请遵循以下具体指南：

• 追加到对应数组。 如果要添加屏幕，追加到 screens 数组；添加选项则追加到 choices；添加变量则追加到 variables。不要创建同名的第二个顶层键。
• 布尔值和数字保持为 JSON 标量。 "isRequired": true、"locationX": 0——不要写成字符串。类型化值包装器保留其键（{ "stringValue": "X" }、{ "booleanValue": true }、{ "elementReference": "Foo" }）。
• 保留现有元素的 locationX / locationY。 新元素的这两个值都设为 0——Flow Builder 打开时会重新布局。
• 如果修改涉及 Repeater，请在任何循环中保留现有的 .AllItems / .AddedItems 访问器——切换访问器会破坏运行时行为。
• 如果添加新字段，请从同一流程中的同级字段复制其结构（label inputParameter、inputsOnNextNavToAssocScrn、storeOutputAutomatically、styleProperties、isRequired）。不要凭记忆拼凑——fs-data-capture-reference/SKILL.md 中的规则说明了每种组件需要哪些内容，但已部署的流程中已有可用示例。
• 如果需要新增 choices 条目，请去重——检查 choices 数组中是否已存在 value 相同的选项。
• 屏幕组件上绝不能输出 required inputParameter——某些 dc* 组件（dcName、dcSignature）会拒绝它。只能通过字段的 isRequired 键传递必填状态。

6. 通过 Tooling PATCH 重新部署

通过一次 Tooling API 调用，将编辑后的流程作为新草稿版本推送回去——发送 PATCH /services/data/vXX.0/tooling/sobjects/Flow/<versionId>，并附上以下请求体：

{ "Metadata": { "...the full edited Metadata object..." } }

• 发送完整的 Metadata 对象，而不是部分补丁——Tooling 会替换整个数据块。
• 返回 204（No Content）表示成功。若返回 400，响应体中的 message 包含 Flow 验证错误——请根据步骤 7 的表格进行诊断。
• 这会创建一个新的流程草稿版本。现有的活动版本会继续运行，直到用户在 Flow Builder 中激活新草稿。（若要在保存时激活，请设置 Metadata.status: "Active"——默认情况下会保留为草稿。）

7. 报告结果

成功时：

• 清楚说明更改内容（例如，“已向 Header_Information 屏幕添加 Notes ShortText 字段”）。
• 输出 Flow Builder URL，供用户查看并激活。使用 Tooling API 查询获取 FlowDefinition Id——发送 GET /services/data/vXX.0/tooling/query，查询 SELECT Id, ActiveVersionId FROM FlowDefinition WHERE DeveloperName = '<FlowApiName>' → <instanceUrl>/builder_platform_interaction/flowBuilder.app?flowId=<id>
• 提醒用户活动版本尚未更改——他们需要在 Flow Builder 中激活新草稿。

失败时（PATCH 返回 400——从响应体的 message 中读取错误）：

• 对照 fs-data-capture-reference/SKILL.md 中的禁止模式表。编辑中常见的诊断包括：元素数组分组违规、CUD 顺序错误、Element X doesn't exist（引用拼写错误）、extension not found（组件名称错误）、'Range' is not a valid value（不支持滑块）、We can't find this input attribute: 'required'（移除 required inputParameter，改用 isRequired）。
• 如果错误涉及你未修改的元素，则获取的流程可能原本就处于损坏状态。重新读取当前版本的 Metadata，并与活动版本进行比较（GET /tooling/sobjects/Flow/<ActiveVersionId>）。
• 未向用户展示前，重试次数不要超过两次。

不在范围内

• 构建新流程 — fs-data-capture-form-designer + fs-data-capture-form-deployer。
• 跨多个流程进行批量迁移。
• 将流程替换为结构完全不同的流程（删除后重建更简洁）。
• 编辑 processType=DataCaptureFlow 以外的流程 — 此技能针对 FSL Mobile 运行时。

相关技能

• fs-data-capture-reference（参考库）— 每次编辑前都要先阅读。它是有效流程模式、禁止模式及确切部署错误、视觉润色 HTML，以及支持部署 CustomObject/PermissionSet/CustomTab 的权威来源。
• fs-data-capture-form-deployer — 使用与此技能修补流程相同的 Tooling Flow JSON 往返流程来创建流程。它的 reference/flow-metadata-json.md 是两个技能共用的权威 Metadata 结构。

此技能中的文件

此技能没有可执行脚本。身份验证探测、流程检索（GET /tooling/sobjects/Flow/{id}）和重新部署（PATCH /tooling/sobjects/Flow/{id}）都是通过 Codey 运行时分发的单次 REST 调用。JSON 补丁由 Agent 根据 ../fs-data-capture-form-deployer/reference/flow-metadata-json.md 在行内编写。