Langflow Deployments 架构规则详解API 路由、Mapper 翻译层与 Adapter 执行层的边界契约【免费下载链接】langflowLangflow is a powerful tool for building and deploying AI-powered agents and workflows.项目地址: https://gitcode.com/GitHub_Trending/la/langflow本篇技术文章基于 Langflow 仓库中的src/backend/base/langflow/api/v1/mappers/deployments/RULES.md展开深入解读 Langflow deployments外部 Agent 部署集成子系统的分层架构规范API 路由层、Mapper 翻译/调和层、Adapter 执行层与通用 payload 契约之间的职责划分、命名规范、fail-fast 错误策略、source_ref 关联机制以及写路径回滚与读路径同步的一致性设计。读完后你可以掌握该子系统的完整分层契约并能在扩展新的部署 Provider如新的 Orchestrate 类平台时按仓库既有规范落地路由、Mapper 与 Adapter 代码。一、背景Deployments 子系统的四层分离Langflow 允许将 Flow工作流以工具/Agent形式部署到外部 Provider 平台当前仓库中已落地 Watsonx Orchestrateprovider key 为watsonx-orchestrate。由于涉及 Langflow 本地数据库、Provider 远端资源、HTTP API 三者的状态一致性仓库在RULES.md中定义了一套严格的关注点分离契约核心目标是让四层各司其职层位置职责API 编排层deployments 路由模块事务、HTTP 错误映射、通用编排必须 provider 无关Mapper 翻译层mappers/deploymentsAPI 报文 → Adapter 输入模型Provider 结果 → 数据库落库字段Adapter 执行层services/adapters/deployment真正的 Provider 网络调用与 Provider 语义通用契约层lfx deployment schema/payloads与具体 Provider 无关的 payload 槽位与结果契约RULES.md 第一条即强调路由模块deployments.py不得import 或分支判断任何 Provider 特有的 payload 模型、常量、槽位名或解析逻辑。路由允许做的事只有四件按 provider key 解析 mapper、调用 mapper 公共 API、调用 adapter service API、执行通用编排/事务/HTTP 错误映射。这一原则在源码中得到直接印证。基类 BaseDeploymentMapper 的 docstring 明确写下 Mapper 与 Adapter 的分工Mapper: API-boundary translation/validation (Langflow schemas - adapter payloads). Adapter: provider execution (network calls, provider semantics, side effects).同时mapper 的选型契约与 adapter 保持一致使用相同的(AdapterType, provider_key)二元组解析保证同一个请求内 adapter 与 mapper 严格对齐见 registry.py 的模块注释。二、Mapper 是 API 边界的翻译与调和负责人RULES.md 第 1.2 节给出了 Mapper 的完整责任清单可归纳为两个数据方向API → Adapter 方向把 API 请求中的provider_data重塑为 Adapter 层输入模型如VerifyCredentials、AdapterDeploymentCreate。Adapter 拿到这些模型后才会真正发起 Provider SDK/网络调用。API → DB 方向从 API 请求中提取 Provider 特有字段组装类型化的落库契约。例如resolve_provider_account_create返回完整的DeploymentProviderAccount模型resolve_provider_account_update返回最小 diff的更新字段字典仅包含payload.model_fields_set中显式出现的字段。Mapper 的责任还包括Provider 特有字段从provider_data中提取并校验凭据、组装带跨字段逻辑的 provider-account 更新 kwargs。而它明确不承担网络调用、Provider 副作用、Adapter 执行逻辑。源码中这一最小 diff语义可直接看到。base.py 中的 resolve_provider_account_update 的实现update_kwargs: dict[str, Any] {} if name in payload.model_fields_set: update_kwargs[name] payload.name if provider_data in payload.model_fields_set: if payload.provider_data is None: msg provider_data cannot be null when provided. raise ValueError(msg) update_kwargs.update(self.resolve_credentials(provider_datapayload.provider_data)) return update_kwargs基类实现处理通用可变字段display name credentialsProvider 子类覆写时调用super()处理公共字段、只追加自己的跨字段规则——这正是 RULES.md 第 6.5 节Provider 账号凭据与更新契约对更新组装的要求。Adapter 侧的责任边界第 1.3 节则是负责 Provider API/网络调用、Provider 语义与状态迁移、基于槽位的 payload/结果结构校验不应直接依赖 Langflow 的 flow-version 概念、不应编码 Langflow DB 语义、不应假设 API 路由层的编排细节。三、词汇规则用 source_ref 切断 Langflow 与 Adapter 的概念耦合RULES.md 第 2 章针对Langflow 特有身份术语不得进入 Adapter 契约定了两条硬规则3.1 禁止在 Adapter 契约中暴露 flow_version_idAdapter 契约中不得出现flow_version_id这类 Langflow 专属术语而是使用中性的关联字段source_ref: strLangflow 可以选择在 mapper/API 边界把 flow-version ID 序列化后填入source_ref——这是实现决策而非契约约定。3.2 禁止脆弱的位置映射不得依赖输入flow_version_ids与输出 Providersnapshot_ids之间的顺序对应关系而必须要求创建时显式绑定{ source_ref, snapshot_id }在 contracts.py 中这些契约被实现为显式的 Pydantic 模型正是 RULES.md 第 3.1 节必须有显式调和契约而非临时 dict/list 假设的落地CreateFlowArtifactProviderData创建期 flow artifact 的基线 provider_data 契约只含必填且非空的source_refCreateSnapshotBinding/CreateSnapshotBindings创建期{source_ref, snapshot_id}绑定及集合并提供to_source_ref_map()辅助方法UpdateSnapshotBinding/UpdateSnapshotBindings更新期同构契约ProviderSnapshotBinding{resource_key, snapshot_id}表示 Provider 侧当前绑定到某 deployment 的快照CreatedSnapshotIdsmapper 调和输出的规范化快照 ID 集合FlowVersionPatch更新期附件增删的显式补丁语义。其中FlowVersionPatch是第 8.2 节更新期附件变更必须是显式 patch 操作的直接实现且自带去重与互斥校验class FlowVersionPatch(BaseModel): add_flow_version_ids: list[UUID] Field(default_factorylist) remove_flow_version_ids: list[UUID] Field(default_factorylist) model_validator(modeafter) def _validate_no_overlap(self) - FlowVersionPatch: overlap set(self.add_flow_version_ids).intersection(self.remove_flow_version_ids) if overlap: ids , .join(sorted(str(value) for value in overlap)) raise ValueError(fFlow version ids cannot be present in both add/remove operations: {ids}.) return self即同一个 flow version 同时出现在 add 与 remove 中会在 schema 层直接报错而不是等到路由层才暴露。四、Payload Slot契约校验的唯一正门RULES.md 第 4 章Payload Slot Ownership Rules是全文最密集的一组规则。其底层原语是 PayloadSlot——一个与层无关的raw dict ↔ 类型化模型转换契约dataclass(frozenTrue) class PayloadSlot(Generic[T_Model]): adapter_model: type[T_Model] policy: PayloadSlotPolicy PayloadSlotPolicy.VALIDATE_AND_DUMP def parse(self, raw: AdapterPayload | BaseModel | None) - T_Model: if raw is None: raise AdapterPayloadMissingError(model_nameself.adapter_model.__name__) try: return self.adapter_model.model_validate(raw) except ValidationError as exc: raise AdapterPayloadValidationError(model_nameself.adapter_model.__name__, errorexc) from excRULES.md 第 4.8 节对PayloadSlot.parse提出了硬性要求与源码逐条对应rawNone必须 fail-fast抛出AdapterPayloadMissingError禁止静默默认值非 None 输入走adapter_model.model_validate(raw)不得添加绕开/替代model_validate的临时预解析类型分支接受的运行时输入以模型契约为准dict 或 model-like 输入均可但payload 缺失行为必须显式。第 4.1 节进一步要求Provider payload/结果的形状校验必须发生在正确的层——API 侧槽位放在 mapperAdapter 侧槽位放在 adapter service——存在槽位时不得用裸 dict 假设绕开槽位校验。这一原则在 Provider Mapper 中有直观体现。WatsonxOrchestrateDeploymentMapper 在类定义处集中声明了全部 API 侧槽位register_mapper(AdapterType.DEPLOYMENT, WATSONX_ORCHESTRATE_DEPLOYMENT_ADAPTER_KEY) class WatsonxOrchestrateDeploymentMapper(BaseDeploymentMapper): PROVIDER_LABEL watsonx Orchestrate api_payloads DeploymentApiPayloads( deployment_createPayloadSlot( adapter_modelWatsonxApiDeploymentCreatePayload, policyPayloadSlotPolicy.VALIDATE_ONLY, ), # ... deployment_update / deployment_update_result / execution_input 等 provider_account_createPayloadSlot(adapter_modelWatsonxApiProviderAccountCreate), # ... )注意PayloadSlotPolicy的两种策略payload.pyVALIDATE_ONLY只校验、原样返回 raw dictVALIDATE_AND_DUMP校验后再model_dump回规范化 dict。这对应 RULES.md 第 3.3 节payload 类型化的泛型应与payloads.py中的槽位定义同处槽位声明配BaseModel绑定的泛型的放置规则。4.1 单一权威注册表第 4.6 节当 Provider 定义了一个同时被 adapter mapper 消费的权威DeploymentPayloadSchemas注册表对象时Provider 的payloads.py模块是 payload/result 契约模型与注册表实例的唯一归属地该模块内注册表常量必须命名为PAYLOAD_SCHEMAS跨模块 import 时必须按PAYLOAD_SCHEMAS引用不得起别名、不得在消费方重复实例化注册表、不得散落游离的槽位常量。Mapper 源码严格遵守了这条命名规则mapper.pyfrom langflow.services.adapters.deployment.watsonx_orchestrate.payloads import ( PAYLOAD_SCHEMAS as WXO_ADAPTER_PAYLOAD_SCHEMAS, )这里as WXO_ADAPTER_PAYLOAD_SCHEMAS是为在模块内区分 API 侧api_payloads而引入的局部命名规则约束的是 Provider 模块内常量名与 import 来源的单一性。4.2 Mapper 不得 import Adapter 私有模型第 4.9 节Provider mapper 处于 API 边界规则是允许import API 层 Provider schema如WatsonxApi*用于输入塑形/分支/输出不应import Adapter 拥有的 payload/result 模型类如 adapter 的Watsonx*ResultData对 adapter 边界的解析mapper 应直接消费 Provider 的PAYLOAD_SCHEMAS槽位。源码印证WXO mapper 解析 adapter 结果时全部经由self.parse_adapter_slot(slotWXO_ADAPTER_PAYLOAD_SCHEMAS.slot, ...)例如resolve_deployment_model_for_create中adapter_provider_result self.parse_adapter_slot( slotWXO_ADAPTER_PAYLOAD_SCHEMAS.deployment_create_result, slot_namedeployment_create_result, rawresult.provider_result, operationcreating the deployment row in Langflow, )4.3 槽位解析的两个入口422 与 500 的分界基类 base.py 提供了两个对称的槽位解析入口把第 9 章错误处理规则具体化为 HTTP 状态码parse_api_request_slot用于用户提交的入站 API payload。失败即输入错误用户可修复 → 抛422AdapterPayloadMissingError→ Missing provider_data for {provider_label}.AdapterPayloadValidationError→ Invalid provider_data for {provider_label}: {detail}。它还支持outer_payload参数对解析后的模型调用validate_with_outer_fields(outer_payload)做跨字段联合校验失败同样映射为 422。parse_adapter_slot用于adapter/provider 返回或 mapper 构造、发往 adapter 的 payload。失败是内部错误用户无法修复 → 抛500且slot_name仅记录日志、不暴露给最终用户。错误详情经过 AdapterPayloadValidationError.format_first_error 的脱敏处理缺失字段保留字段名Missing required field x.、多余字段提示移除、模型级value_error透传业务消息其余错误不回显原始 validator 文本——避免把 payload 片段泄漏到日志/响应中。此外_validate_slot静态方法给出了槽位不存在或 raw 为 None 时原样放行的 API 侧宽松路径与 adapter 侧的严格 fail-fast 形成对比前者处理的是可选的 API 字段后者处理的是必需的 Provider 结果契约。五、Mapper API 面的命名家族与注册表5.1 三个语义家族第 5.1 / 5.2 节RULES.md 要求方法命名按意图保持视觉可区分前缀语义基类示例resolve_*API 输入解析/翻译resolve_deployment_create、resolve_credentials、resolve_provider_account_updateshape_*出站 API 塑形adapter 结果 → API 响应shape_deployment_create_result、shape_execution_status_resultutil_*路由编排使用的调和/提取工具util_create_snapshot_bindings、util_created_snapshot_ids、util_flow_version_patch并要求避免resolve与reconcile这类模糊意图的重叠动词。在 base.py 中util_*家族的基类默认为空策略值得注意def util_create_snapshot_bindings(self, *, result: DeploymentCreateResult) - CreateSnapshotBindings: ...Base behavior is intentionally empty because binding extraction is adapter-result-schema-specific and must be implemented by provider mappers... return CreateSnapshotBindings() def util_created_snapshot_ids(self, *, result: DeploymentUpdateResult) - CreatedSnapshotIds: return CreatedSnapshotIds() def util_flow_version_patch(self, payload: DeploymentUpdateRequest) - FlowVersionPatch: return FlowVersionPatch()即基类给出空集合默认值Provider mapper 覆写为真实提取逻辑返回类型始终是显式契约模型而非 dict/list。5.2 注册表与 base 分离第 5.3 节第 5.3 节要求三个文件按职责分离mapper 行为在base.py、注册表实现在registry.py、契约模型在contracts.py。registry.py 的实现对应当下DeploymentMapperRegistry持有_default BaseDeploymentMapper()未注册 provider 的兜底与按 provider_key 懒实例化的映射register_mapper(adapter_type, provider_key)是导入期装饰器Provider mapper 类通过它注册WXO mapper 顶部即register_mapper(AdapterType.DEPLOYMENT, WATSONX_ORCHESTRATE_DEPLOYMENT_ADAPTER_KEY)get_deployment_mapper(provider_key)是路由层使用的便捷访问器其 docstring 说明动机镜像 deployment adapter 查找的调用点保持清晰且对称的契约对应第 7.2 节Mapper lookup API 应镜像 adapter lookup 的人体工学。六、Provider 专属逻辑的落点与凭据流第 6 章6.1 Provider 特有逻辑必须写成 mapper 覆写第 6.1 节列举的三类逻辑——从 Provider URL 推导 tenant ID、解析 Provider create/update 结果做调和、Provider 特有的 flow-version patch 提取语义——必须实现为 mapper override而非 route conditional。WXO mapper 的 tenant 推导是典型例子mapper.py优先取provider_data.tenant_id缺失时回落到extract_tenant_from_url(parsed.url, ...)两者皆空则抛ValueError错误信息明确要求显式提供 tenant_id 或使用包含/instances/{tenant_id}的 url。6.2 凭据流Mapper 是唯一理解凭据形状的角色第 6.5 节这是 RULES.md 中最完整的数据流章节。三句话概括API schema 把凭据暴露为不透明的provider_data: dict[str, Any]不校验内容Mapper 的resolve_credentials(provider_data...)校验并提取凭据 DB 字段当前 WXO 返回{api_key: ...}DB 模型保持固定列当前为api_key: str。若未来 Provider 需要不同存储布局多列、序列化 JSON blob只需 mapper 与 CRUD 层演进路由与 schema 不变。基类 base.py 的模块 docstring 与resolve_credentials的签名共同固化了这一契约def resolve_credentials(self, *, provider_data: dict[str, Any]) - dict[str, Any]: Extract credentials from provider_data and return DB column-value pairs. Provider mappers must override this. The returned dict is spread into the CRUD layers keyword arguments ... raise NotImplementedError凭据的完整旅程以 WXO 为例创建resolve_provider_account_create先经_validate_create_provider_data解析provider_data并通过check_provider_url_allowed做主机名白名单校验再组装DeploymentProviderAccount携带明文api_key由 CRUD 层create_provider_account_from_model加密后落库校验resolve_verify_credentials_for_create/update把api_key打包进VerifyCredentials(base_url..., provider_data{api_key: ...})交给 adapter 去 Provider 侧验证update 路径若provider_data未出现在model_fields_set中则返回None不动凭据则跳过验证DB 兜底DeploymentProviderAccount模型上的model_validator调用validate_tenant_url_consistency()从 deployment_provider_account/utils.py 这一单一事实源执行 tenant/URL 一致性校验——即使未来某条代码路径绕过了 mapperDB 层仍会拦截不一致的 tenant/URL 组合。这对应检查清单中的DB-level consistency validators exist as defense-in-depth。6.3 公共 schema 与 helper 的放置规则第 6.3 / 6.4 节对外消费的 adapter payload/result 形状 schema 必须定义在payloads.py或schema.py不得作为临时局部类散落在深层内部工具模块被 adapter service 编排消费的 helper 返回契约如类型化的 create/update apply 结果即使不直接过 HTTP 序列化也视为公共边界契约Provider 专属执行契约放payloads.pyadapter 中性/共享域契约放schema.pyhelper 模块*_helpers.py可以使用这些契约但不能拥有它们。七、数据完整性source_ref 权威匹配第 8 章第 8.1 节规定创建期的附件映射必须基于两张显式映射期望侧source_ref - flow_version_idLangflow 请求Provider 侧source_ref - snapshot_idProvider 创建结果。并强制三类严格检查缺失绑定 → 错误出现意外的source_ref→ 错误数量不匹配 → 错误。第 8.2 节规定更新期附件变更必须表达为显式 patch 语义FlowVersionPatch并校验 add/remove 无重叠见第三节代码Provider mapper 可以额外约束 patch 操作在 Provider 报文中的表达位置如放进 provider operations payload。一个细节设计值得强调基类extract_snapshot_bindings/extract_snapshot_bindings_for_get的基类实现是抛出NotImplementedError而非返回空列表。base.py 的 docstring 解释了原因下游delete_unbound_attachments把空 bindings 非空 deployment_ids解释为删除这些 deployment 的全部本地附件——静默return []会对任何继承了基类实现的 Provider 造成破坏性批量删除。因此未覆写的 Provider 会被调用点以except NotImplementedError拦截跳过破坏性同步而不是静默清空数据。这是fail-fast 优于静默默认第 4.5 / 4.7 节在同步路径上的又一实例。八、写路径回滚与读路径同步第 13 章这是 RULES.md 中最接近分布式事务设计的一章。8.1 Provider-first 策略第 13.1 节create 与 update 统一采用provider-first先调用 Provider再更新并提交 Langflow DBDB 提交失败时路由对 Provider 发起**尽力而为best-effort**的补偿调用Create 回滚路由发起补偿adapter.delete()删除 Provider 资源。二级资源snapshots、configs有意不做级联删除——它们可能跨 deployment 共享残留为 Provider 侧孤儿资源Update 回滚路由请 mapper 通过resolve_rollback_update()构造补偿更新载荷再发起adapter.update()。若 mapper 返回None该 Provider 无法回滚Provider 状态可能与 DB 分叉直到被读路径惰性同步检测。文档还给出了选择 provider-first 而非 DB-first 的三点理由第 13.1 节这是文档中少见的决策记录Create 天然需要 Provider 先分配 resource ID 与 snapshot IDDB 才有东西可存Update 场景下provider-first 的回滚前状态已经在 DB 里——mapper 回滚时可直接查询flow_version_deployment_attachment行DB-first 则需要在变更前把 name、description 及每条被移除附件的provider_snapshot_id显式捕获进内存Provider-first 避免了 DB-first 所需的双提交一次提交后再补 Provider 响应里的provider_snapshot_id消除了其他读者可能观察到 Provider 尚未处理的 DB 状态的一致性窗口。WXO mapper 的 resolve_rollback_update 展示了该机制的完整落地查询deployment行与flow_version_deployment_attachment附件行取当前已提交的provider_snapshot_id集合作为put_tools连同display_name构造声明式 update把 Provider Agent 的工具列表重置回 DB 所记录的状态同时经spec恢复 description。基类默认返回Nonebase.py即无通用回滚。第 13.5 节配套要求执行写路径回滚的路由必须在暂存全部 DB 写操作后显式调用session.commit()而不是依赖session_scope()的自动提交——这样路由才能在 re-raise 前捕获提交失败并发起补偿调用。且回滚调用必须包裹在独立的异常处理中失败的 rollback 永远不得掩盖原始 commit 错误。8.2 读路径同步两级对账第 13.3 节读路径同步与写路径回滚是相互独立的机制第 13.4 节明确两者解决不同的一致性问题Deployment 级list/get 路径上路由校验 deployment 的resource_key在 Provider 侧仍存在已删除 Provider 资源的过期 DB 行被移除外键 CASCADE 清理附件Snapshot 级deployment 级同步后再校验flow_version_deployment_attachment中的provider_snapshot_id在 Provider 侧仍存在过期附件行被移除保证attached_count准确。第 13.4 节给出了两者的能力边界回滚补偿的是Provider 侧已变更但 DB 未记录写路径问题目标是撤销 Provider 侧变更同步检测的是Provider 侧已删除但 DB 不知情读路径问题目标是从 DB 向外检查每行资源是否仍存在。因此同步无法检测从未写入 DB 的 Provider 孤儿资源如 create 回滚失败也无法检测已有 Provider 资源在 update 回滚失败后状态分叉——这是该设计明示的已知局限。九、API 响应字段归属边界第 14 章第 14 章定义了响应 schema 的字段所有权规则防止 Langflow 自有字段与 Provider 透传字段混在同一层级顶层字段 Langflow 自有deployment_idDB UUID、id、name、description、type、created_at/updated_atDB 时间戳、resource_key虽源自 Provider但经 Langflow 持久化并建索引后视为自有provider_data内部 Provider 自有execution_idProvider 不透明的运行标识、agent_id、status、result、started_at/completed_at/failed_at/cancelled_at、last_error等。文档给出的动机如果 Langflow 将来自己持久化执行记录顶层execution_id将与 Provider 的不透明 run id 产生歧义冲突。新字段决策清单第 14.3 节Langflow 是事实源 → 顶层仅转发 →provider_dataProvider 提供但 Langflow 持久化索引如resource_key→ 顶层可接受。第 14.4 节是硬规则未经 Langflow DB 持久化、直接来自 Provider 的数据必须进入provider_data没有例外。基类shape_execution_create_result/shape_execution_status_resultbase.py即按此实现响应仅携带顶层deployment_id与整体provider_data载荷。十、测试与强制检查清单第 10、11 章第 10 章对测试提出三条要求边界契约而非仅 happy path必须被验证覆盖基线 mapper 默认行为、Provider 覆写行为、路由调和失败模式缺失/不匹配绑定、provider account 经 mapper API 的塑形、注册表行为与单例访问器mapper 方法返回契约对象时断言应针对模型类型与字段而非松散 dict/list命名家族变更时测试必须同步更新以防契约语言漂移。第 11 章提供了 21 项 PR 合并前检查清单按主题归组后如下原文为逐项 checkbox路由纯度路由无 Provider 专属 payload 模型 import不直接解析 Provider payload 内部结构Mapper 主权Provider 特有结果解释归 mapperprovider-account create/update 逻辑在 mapper 而非路由条件分支resolve_credentials承担凭据提取槽位纪律Adapter 用 payload slot 校验无裸 dict 绕开验证路径直接 slot/model parse无冗余包装解析 helperPayloadSlot.parse保持 None fail-fast 直接model_validate必需调和 payload fail-fast无静默默认模型兜底关联语义显式source_ref绑定无位置映射调和输出用显式 schema 模型mapper schema 中无 Provider 逃生舱/后门注册表单一性Provider 以payloads.py为 payload/result 契约与注册表的唯一归属mapper 与 adapter 复用同一权威注册表无重复槽位常量mapper 不 import adapter 私有模型类slot 解析不足时应定义 slot类型与命名mapper 边界结果签名不过度收窄为 dict-only 泛型方法名遵循resolve_*/shape_*/util_*家族registry/contracts/base 三文件按职责分离纵深防御DB 层跨字段一致性 validator 存在Provider 跨字段规则如 tenant/URL 耦合实现为调用super()的 mapper override 而非基类条件分支测试覆盖基类默认与 Provider 覆写双方覆盖缺失/意外绑定的失败用例。十一、契约演进的变更管理流程第 12 章RULES.md 第 12 章把改契约本身流程化适用于任何改变 payload 形状、调和语义或所有权边界的变更12.1 先分类后编码四类变更契约新增新显式字段/模型、契约收紧更严格校验/不变量、契约替换旧路径被新显式形状取代、所有权迁移逻辑从 route → mapper、helper → payload/schema 模块等。类别决定是否需要兼容桥。12.2 契约优先的实现顺序六步定义/更新显式契约 schemaAPI mapper 契约 adapter payload/schema 契约更新 mapper 解释/工具方法以消费/产出这些契约更新 adapter service/helper 编排以产出槽位支撑、匹配新契约的结果路由/服务只调 mapper 公共 API 重新接线禁止探测 Provider payload为有效流与边界失败两端补齐测试部署模式允许时移除遗留兼容路径。12.3 兼容模式必须有意为之每次契约演进二选一Clean break旧形状立即被显式错误拒绝Transitional compatibility旧形状经一个窄范围、有文档的 fallback 临时接受。默认策略Langflow/adapter 内部层变更公共 API 契约不变优先 clean break仅当需要保住公共 API 行为或外部集成预期时才用过渡兼容。过渡 fallback 必须最小、局部、易删除不得绕开槽位校验且每个 fallback 必须带移除条件测试或绑定清理的 TODO。12.4 / 12.5补充迁移期新公共契约类型的放置与命名遵循第 6.3/6.4 节规则Provider 专属公共契约名应带 Provider 前缀如Watsonx...防歧义任何契约演进 PR 必须附带测试证明新契约模型被使用、路由/服务不再直接依赖 Provider payload 内部、调和不变量缺失绑定、意外 ref、数量不匹配、重叠被强制执行、以及若选过渡模式兼容行为与最终 clean-break 预期。十二、小结这套规则解决了什么问题RULES.md 表面是一份架构评审清单实质是 Langflow 在多 Provider 部署集成场景下的一整套防腐层anti-corruption layer设计词汇隔离——source_ref把 Langflow 的 flow-version 概念挡在 adapter 契约之外新增 Provider 时 adapter 契约零改动解析正门——PayloadSlot.parse的 None-fail-fast model_validate单一通道把Provider 返回形状漂移这类问题钉死在边界上配合 422/500 的语义分界让用户错与集成错互不混淆单点演化——凭据形状、tenant 推导、回滚载荷构造全部收敛到 mapper 覆写路由与 DB schema 对 Provider 差异完全无感状态一致性——provider-first 写路径 best-effort 补偿 两级读路径同步在没有跨系统分布式事务的现实约束下给出了一致性窗口最小、行为可预测的双向收敛方案。对于要在该子系统上扩展新 Provider 的开发者落地路径是在src/lfx/src/lfx/services/adapters/deployment下实现 adapter 与payloads.py定义PAYLOAD_SCHEMAS在 mappers/deployments 下新增 Provider 包以register_mapper注册 mapper、覆写resolve_*/util_*/resolve_rollback_update等必要方法路由层只依赖get_deployment_mapper(provider_key)的公共 API。最后按第 11 章检查清单逐项核对即可保证新 Provider 与现有分层契约完全对齐。【免费下载链接】langflowLangflow is a powerful tool for building and deploying AI-powered agents and workflows.项目地址: https://gitcode.com/GitHub_Trending/la/langflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考