Elsa 输出转换器 Studio 创作契约:绑定编辑器、设置编辑器与兼容性数据保全指南

原创2026-10-03 12:53:331,922 阅读
文章标签:后端工作流自动化流程编排低代码AI Agent

Elsa 输出转换器 Studio 创作契约:绑定编辑器、设置编辑器与兼容性数据保全指南

导读

本文以 Studio Authoring Contract 为核心骨架,系统讲解 Elsa 工作流引擎中「活动输出转换器(Output Converter)」在 Elsa Studio 侧的完整创作契约:绑定编辑器如何选择与持久化转换器、设置编辑器如何在 Schema 驱动与原始 JSON 之间切换、加载与兼容性规则如何保护已持久化的转换器配置,以及独立验证清单如何保障端到端数据不丢失。读完本文,你将掌握在 Studio 中选配、配置、保存、重开与清除输出转换器的全部行为约定,并理解这些约定背后的服务端注册、REST 发现接口与源码级实现依据。

一、契约背景:Studio 在输出转换器架构中的角色

输出转换器(Output Converter)是 Elsa 提供的可扩展机制:工作流作者可以在某个活动输出绑定(Output Binding)上显式选择零个或一个已注册的转换器,使目的地(变量或工作流输出)收到转换后的值,而活动的原生输出保持不变。该功能的完整产品规格见 spec.md,其关键设计决策记录在 ADR 0012:Output converters use explicit stable identities——转换器通过稳定的、序数比较且区分大小写的 Converter ID 被引用,行为、设置或结果语义的任何破坏性变更都必须换用新 ID。

在该架构中,转换器描述符(Descriptor)的发现是服务端拥有的(对应 FR-033/FR-034/FR-035)。因此 Studio 侧契约(FR-036)明确规定:Studio 必须消费服务端描述符 API,而不是维护一份硬编码的转换器目录。Studio 的职责被收窄为三块:

  1. 根据输出与目的地类型向服务端查询兼容转换器;
  2. 提供 Schema 驱动的设置编辑或原始 JSON 编辑;
  3. 保证转换器配置在保存、重开、编辑等所有操作中不丢失、不被误改。

下面逐一展开 studio-contract.md 的四个部分。

二、绑定编辑器契约:七条规则的逐条解读

绑定编辑器(Binding editor)出现在 Studio 活动属性面板的 Outputs 选项卡中。契约针对每个活动输出(for each activity output)定义了七条行为规则:

规则 1:目的地选择器保留身份与声明类型元数据

现有的目的地选择器继续承担「目的地身份 + 声明类型元数据」的职责,不因转换器功能而改变。目的地身份在数据模型中对应 data-model.md 描述的 Destination 实体:包含 Id(memory-reference 或 workflow-output 身份)、Type(解析后的 CLR 类型)、AllowsNull(引用类型与 Nullable<T> 为 true)与 Kind(变量或工作流输出)。

在源码层面,输出绑定本身就是带可选转换器的 Output/Output<T>:Output.cs 中 Output 继承自 Argument,并新增了一个可空属性 OutputConverterConfiguration? Converter。原生输出类型保持 T(强类型输出)或 object(非类型化输出)不变,目的地身份仍由原有的内存块引用(memory reference)承载。

规则 2:目的地是类型化目标时,按声明类型查询兼容描述符

当作者选择了一个类型化目的地,Studio 会使用「输出声明类型名 + 目的地声明类型名」两个参数向服务端查询兼容描述符。这正是 Studio 侧服务 IOutputConverterService 的形态:

Task<ICollection<OutputConverterDescriptor>> GetOutputConvertersAsync(
    string sourceType,
    string destinationType,
    CancellationToken cancellationToken = default);

接口定义见 IOutputConverterService.cs,其远程实现 RemoteOutputConverterService.cs 通过 IBackendApiClientProvider 取得 API 客户端并调用 IOutputConvertersApi.ListAsync,请求体携带 SourceType 与 DestinationType。兼容性判定最终落在服务端注册表 OutputConverterRegistry.FindCompatible(OutputConverterRegistry.cs):

public IEnumerable<OutputConverterDescriptor> FindCompatible(Type sourceType, Type destinationType) =>
    ListAll().Where(x =>
        x.SourceType.IsAssignableFrom(sourceType) &&
        IsAssignableToDestination(x.ResultType, destinationType));

即:描述符的源类型必须可以从输出的声明类型赋值(支持基类/接口的普通可赋值性),其结果类型必须可以赋值给目的地类型(Nullable<T> 的底层类型同样视为可赋值)。

规则 3:Studio 显示带 None 选项的可选 Converter 选择器

转换器选择器是可选的,且始终提供 None(不使用转换器)选项。None 对应「未配置转换器」的绑定,此时行为与旧版完全一致:直接走原有的原生值赋值路径,不触发任何转换器注册表查询、兼容性校验或调用(对应 spec.md 中 FR-015「不得从类型对推断转换器选择」与 FR-003「无转换器配置时保持既有序列化形态与赋值行为」)。

规则 4:选择转换器时,只把 ID 与设置写入活动输出 JSON

当作者选定某个转换器后,Studio 只写两样东西:id 与 settings。不得持久化实现类型名、实例、描述符或展示元数据(FR-004)。序列化形态由 data-model.md 给出:

{
  "typeName": "String",
  "memoryReference": {
    "id": "resultVariable"
  },
  "converter": {
    "id": "sample.to-text",
    "settings": {
      "format": "compact"
    }
  }
}

其中 converter 对象就是 OutputConverterConfiguration.cs 中的 OutputConverterConfiguration:Id 为必填的非空稳定 ID,Settings 为可选的 JSON 对象,且在持久化或调用时都会被克隆(settings?.Clone()),保证不可变性。

规则 5:清除转换器即移除整个可选对象

作者在编辑器中选择 None 或执行「清除」操作后,序列化结果中不再存在 converter 键,绑定恢复为未配置形态,即恢复原有的未转换赋值行为(对应 spec 中 User Story 4 的验收场景 5 与 FR-002)。测试层面由序列化测试与 Studio 往返测试共同覆盖(见 completion.md 的 FR-001/FR-002 证据列)。

规则 6:更换目的地仅在「不再兼容」时才清除转换器

这是数据保全的核心规则:目的地的变化只会让不再兼容的转换器选择失效,兼容的转换器保留。也就是说,判断依据是「描述符结果类型是否仍可赋值给新目的地类型」,而不是「目的地字符串是否变化」。这一行为既保护作者已经配置好的设置,又避免把无效配置静默带上路;而真正不再兼容的选择会被失效处理,保证不会把不兼容的转换结果写入新目的地(对应 FR-018 与 invoker 的结果校验)。

规则 7:无关的活动编辑必须精确保留转换器 JSON

作者修改活动名称、表达式或其他属性时,绑定上的 converter 对象(ID 与设置)必须逐字节等价地保留。这是 SC-006「转换器配置经受住服务端序列化、API 客户端往返、Studio 编辑与工作流重开而不丢失或变更」的组成部分,对应 Studio 测试套件中的 Outputs 选项卡往返测试。

三、设置编辑器契约:Schema 驱动与原始 JSON 回退

设置编辑器(Settings editor)遵循一条明确的分级策略,对应 FR-039:

Schema 驱动表单:受支持的 JSON Schema 构造

当所选转换器的描述符携带受支持的 object JSON Schema 时,Studio 渲染字段化表单。契约明确列出的受支持构造包括:

  • 字段类型:string、number、integer、boolean;
  • 取值约束:enum;
  • 元数据:required、title、description、default。

以 REST 契约(rest-api.md)中的示例描述符为例:

{
  "id": "sample.to-text",
  "sourceTypeName": "Sample.Source",
  "resultTypeName": "String",
  "displayName": "Convert to text",
  "description": "Formats the source as text.",
  "settingsSchema": {
    "type": "object",
    "properties": {
      "format": {
        "type": "string",
        "enum": ["compact", "indented"]
      }
    }
  }
}

Studio 的设置编辑器实现位于 OutputConverterSettingsEditor.razor.cs。其 BuildFields 方法逐条验证:Schema 必须是 type: "object" 且含 properties 对象;每个属性按 type 映射为文本、数字、整数、布尔或枚举输入;required 数组用于标记必填字段;title/description 用于标签与提示。枚举值只接受字符串与数字(如 format 的 compact/indented);数字输入按 InvariantCulture 做 decimal.TryParse/long.TryParse 校验,必填字段留空会就地给出「This setting is required.」的本地化错误。

原始 JSON 回退:无 Schema 或含不支持的构造

当描述符没有 Schema,或 Schema 含编辑器不支持的构造(如非 object 顶层、数组/对象类型的嵌套属性、字符串之外的枚举取值等)时,Studio 回退到原始 JSON 对象编辑器。BuildFields 中任何不支持情况都会清空字段列表返回,从而自动切换到 _rawSettings 文本编辑。这正是契约中「raw JSON editor is an acceptable fallback」的落地(spec 的 Assumptions 也明确:原始 JSON 编辑器是无 Schema 或缺少专用表单控件时的可接受回退方案)。

本地校验与服务器权威校验的分工

  • 本地校验:格式非法或非对象的 JSON 在本地直接拒绝——OnRawSettingsChangedAsync 中 JsonNode.Parse 失败或结果不是 JsonObject 时会抛出 JsonException,随即显示「Converter settings must be a valid JSON object.」,且不会把无效值回传给绑定。
  • 服务端权威校验:本地校验只是第一道闸门;服务端定义校验信息(如未知 ID、类型不兼容、设置 Schema 校验失败或转换器自定义校验失败)始终具有权威性,并会被呈现给作者。运行时的完整校验链可见 OutputConverterInvoker.cs:依次进行注册解析(Resolution)、源类型兼容(SourceCompatibility)、结果类型可赋值(ResultValidation)、设置校验(SettingsValidation,经 IOutputConverterSettingsValidator 执行 Schema 校验与转换器自身 ValidateSettings)、调用(Invocation)与最终结果/可空性校验。

只读工作区

只读工作区(read-only workspace)中的作者不能修改转换器选择或设置:编辑器通过 IsReadOnly 参数禁用选择器与表单控件,避免在无法保存的上下文中产生误导性的可编辑状态。

四、加载与兼容性契约:保护持久化配置的四条防线

防线 1:取消或忽略过期的描述符请求

当输出/目的地选择发生快速连续变化时,前一次查询发出的描述符请求可能已过期。Studio 必须取消或忽略陈旧响应,只采纳与当前「输出 + 目的地」选择匹配的结果,防止出现列表与当前绑定错位。

防线 2:旧服务器优雅降级,绝不删除已持久化配置

如果连接的是不支持描述符发现的旧版服务端,Studio 应隐藏或禁用新控件,而不是报错或破坏数据;已持久化的转换器配置保持原样,等待服务端升级或作者后续处理。这与 FR-035「描述符 API 响应只暴露 ID、支持类型、本地化展示元数据与可选设置 Schema」共同保障了版本偏移场景下的安全性。

防线 3:未知 Converter ID 显示而非静默清除

当工作流中持久化的 Converter ID 在服务端已不存在(例如部署被替换、注册被移除)时,Studio 必须展示该 ID 及其校验状态,而不是静默清除。这一设计直接呼应 spec 的 Edge Case「A converter is removed, replaced incompatibly, or registered differently between validation and execution deployments」与 User Story 3:持久化工作流可以比部署活得更久,作者有权看到配置所指的转换器已失效,而不是眼睁睁看着配置被悄悄抹掉。

防线 4:本地化与 ID 回退

Studio 自有的标签与错误信息使用本地化文案(如上面提到的必填提示、数字格式提示、JSON 对象提示,均经 Localizer);服务端返回的展示文本缺失时,界面回退显示 Converter ID。这样即使描述符没有 displayName,作者依然能凭 ID 识别转换器。

五、独立验证清单:如何证明契约成立

studio-contract.md 的第四部分「Independent verification」给出了四条可执行的验证断言,它们是 Studio 自动化测试的直接依据:

  1. 查询参数使用所选声明的源与目的地类型:请求 sourceType/destinationType 必须来自当前绑定中已声明的输出类型与目的地类型,而非推断或猜测值。
  2. 选择、配置、保存、重开、清除完整往返正确:一次完整的「选择转换器 → 编辑设置 → 保存工作流 → 重开工作流 → 清除转换器」必须产出正确且一致的序列化结果。这正是 SC-006 的 Studio 部分。
  3. 目的地变更只使不兼容的转换器选择失效:验证规则 6 的行为边界——兼容保留、不兼容失效、数据不静默丢失。
  4. 只读、服务不可用、未知 ID、设置损坏四种状态下工作流数据被保全:即「任何异常/受限场景下都不丢数据」。

上述验证在仓库中有对应的自动化证据:OutputsTabConverterTests.cs 覆盖 Outputs 选项卡的选择与往返(含数组目的地场景),OutputConverterSettingsEditorTests.cs 覆盖 Schema 驱动编辑与原始 JSON 回退,RemoteOutputConverterServiceTests.cs 覆盖 Studio 对描述符 API 的消费。根据 completion.md 的验证日志,Studio 输出转换器测试共 9 项在 net10.0 上全部通过。

六、契约背后的服务端与 API 支撑

Studio 契约之所以能够「轻装上阵」,是因为服务端承担了发现与校验职责:

描述符 REST 接口

Endpoint.cs 实现了契约规定的查询端点:

GET /descriptors/output-converters?sourceType={typeName}&destinationType={typeName}
  • 端点要求权限 read:* 或 read:output-converters(对应 REST 契约的授权说明);
  • 两个查询参数都是必需的:缺失或无法解析时返回 400,无权限时返回 403;
  • 类型名必须是已注册的类型别名或可解析的安全类型名——端点内部通过 SerializationTypeResolver 解析,并在 Map 时把 CLR 类型投影为别名或安全的程序集限定名,杜绝实现类型信息泄露(FR-035);
  • 响应体只含安全描述符字段:id、sourceTypeName、resultTypeName、displayName、description、settingsSchema(见 rest-api.md 的响应示例)。

API 客户端契约

客户端契约 IOutputConvertersApi.cs 与服务端一一对应:

[Get("/descriptors/output-converters")]
Task<ListOutputConvertersResponse> ListAsync(
    [Query] ListOutputConvertersRequest request,
    CancellationToken cancellationToken = default);

ListOutputConvertersRequest 携带 SourceType 与 DestinationType,ListOutputConvertersResponse 是 OutputConverterDescriptor 的集合,使用字符串与 JsonElement? 镜像安全描述符形态。该客户端在 DependencyInjectionExtensions.cs 中通过 AddApi<IOutputConvertersApi> 注册。

Studio 的消费方式

RemoteOutputConverterService(RemoteOutputConverterService.cs)是 Studio 契约「不维护硬编码目录」的直接体现:每次需要候选列表时,它都实时向服务端发起带两个类型参数的查询,结果直接绑定到转换器选择器。服务端描述符的注册与唯一性校验则由 OutputConverterServiceCollectionExtensions.cs 的 AddOutputConverter<TConverter> 保证——以 Converter ID 作为 keyed-service 的服务键,并在注册时拒绝空 ID、重复 ID 以及仅大小写不同的 ID。

七、端到端状态流与数据保全保证

把 Studio 契约放回完整的运行时状态机(data-model.md)中,可以更清楚地看到「作者在 Studio 里做出的每个选择最终如何被运行时兑现」:

Unconfigured Binding
  └─ assign native value using existing path

Configured Binding
  ├─ record native output
  ├─ native null → validate destination nullability → write null
  └─ non-null
      ├─ resolve registration and destination
      ├─ validate source, destination, and settings
      ├─ invoke converter
      ├─ validate result and nullability
      ├─ success → write Bound Value
      └─ failure → fault activity; destination unchanged

对 Studio 而言有两点尤其重要:

  1. 转换只作用于 Bound Value:活动输出寄存器、日志、API 响应与诊断始终暴露原生输出(FR-005/FR-006),Studio 的输出观察面不会因转换器而失真;
  2. 失败不写目的地:任何阶段的失败(Resolution、SettingsValidation、SourceCompatibility、Invocation、ResultValidation)都会通过 Elsa 正常活动故障管线产生带结构化元数据(ConverterId、Stage、ActivityId、OutputName、DestinationId 等)的 Output Conversion Error,目的地保持不变、原生输出保留、原始异常作为 InnerException 保留,且默认错误消息不包含原生值与原始设置(FR-029~FR-032)——这正是 Studio 设置编辑器「服务端校验信息必须上浮给作者」背后的安全语义。

八、验证证据汇总

根据 completion.md,Studio 契约对应的需求(FR-036~FR-039)与成功标准(SC-005、SC-006)均已由自动化测试佐证:

契约条目 对应需求/标准 证据来源
使用 API 发现而非硬编码目录 FR-036/FR-037 RemoteOutputConverterServiceTests、Outputs-tab 测试
按声明类型过滤候选 FR-037 Outputs-tab 测试(含数组目的地)
选择/配置/清除/重开/校验 FR-038 Outputs-tab 与 settings-editor 测试
Schema 驱动 + 原始 JSON 回退 FR-039 settings-editor 测试
完整创作流程(SC-005,两分钟阈值属发布级手动 UX 验收) SC-005 自动化组件流程
配置在各处往返不丢失 SC-006 Core 序列化、API 客户端、Studio 测试

结语

Elsa Studio 的输出转换器创作契约可以概括为三句话:绑定编辑器负责「选得准、存得少」(只持久化 ID 与设置,且仅在目的地不再兼容时才失效);设置编辑器负责「该表单就表单、该 JSON 就 JSON」(Schema 驱动优先,原始 JSON 兜底,服务器校验始终权威);加载与兼容性规则负责「宁可显示也不静默删」(旧服务器、未知 ID、损坏设置等任何异常状态下都保全工作流数据)。这套契约配合服务端注册表、描述符 REST 接口与运行时故障管线,共同保证了转换器功能在 Studio 侧可以安全、无损地完成全生命周期操作。想深入实现细节的读者,可从 spec.md、data-model.md、rest-api.md 与 runtime-contract.md 继续追踪。

登录后查看全文
elsa-core