Langflow 用户侧契约（User-Facing Contracts）解析：组件、Flow JSON、REST API 与 Message 的向后兼容治理

Langflow 中保存的 Flow 是持久化在用户数据库中的生产工件，任何看似无害的重命名、默认值调整或输出顺序变化，都可能在下次加载时悄悄断掉用户的连接。本文以仓库内的 docs/agents/CONTRACTS.md 为骨架，完整解读 Langflow 定义的 15 项用户侧契约、"改动前检查矩阵"和"看似无害的破坏性变更"案例，并结合 Message 模式定义、legacy/replacement 组件迁移机制与 file_names_mapping 测试框架 等源码证据，帮助你掌握在 Langflow 中安全修改组件、接口、数据库与环境变量的完整方法论。

一、契约的核心思想：Flow 是持久化用户工件

CONTRACTS.md 开篇即定调：这些契约是"用户所依赖的界面"，静默破坏它们，是 Agent 交付"与整体故事对不上"的工作最常见的方式。文档要求开发者在改动任何下列内容之前先读这份文件。

结尾"Why this matters"一节给出了根本原因：

Langflow 的 Flow 是持久化用户工件，运行在生产环境。负责加载它们的系统在设计上是宽容的：容忍新字段、对缺失字段回退、在加载时应用类型迁移。而这种宽容，是用契约表中每一条换来的代价。

也就是说，加载器的"宽容"不是免费的——它建立在组件类名、输入/输出命名、Flow JSON 结构、环境变量的稳定性之上。破坏其中一条，系统就无法再绕过它绕行，Flow 会直接停止工作。文档最后的要求非常直接：把这个文件当作检查清单，任何触及表格某行的改动，对应规则无条件适用；没有明确的弃用计划就没有例外。

二、15 项契约面（The Contract Surface）逐项解析

契约表是全文核心。下面逐项给出"事实来源 + 规则"，并补充源码层面的佐证。

契约 1 与 2：组件类的 name 属性与 Python 类名——永不重命名

• 事实来源：class XComponent: name = "X"、class XComponent；
• 规则：name 属性用于匹配已保存 Flow JSON 中的节点，永不重命名；Python 类标识符与 name 联合用于组件解析，同样永不重命名。

契约 3：组件文件路径 + 模块——重命名即破坏性变更

• 事实来源：src/lfx/src/lfx/components/<cat>/<file>.py；
• 规则：文件重命名是破坏性变更。受支持的工作流是：在旧组件旁新增新组件，在旧类上设置 legacy = True 与 replacement = ["<category>.<NewClassName>"]；同时更新所有针对历史 SUPPORTED_VERSIONS 的 file_names_mapping 测试（定义于 src/backend/tests/constants.py）；重新生成 starter projects 并重建组件索引。

仓库中存在大量遵循这一机制的真实案例。例如 csv_to_data.py：

legacy = True
replacement = ["data.File"]

crewai 分类下的多个组件同样标注了迁移状态，如 sequential_crew.py 中的 legacy = True。测试侧由 src/backend/tests/base.py 中的 file_names_mapping fixture 强制校验：每个测试类必须提供历史版本到文件名的映射，否则校验 SUPPORTED_VERSIONS（当前为 ["1.0.19", "1.1.0", "1.1.1"]，见 constants.py）时会明确报错 "Please add this version to your component's file_names_mapping"。

契约 4 与 5：输入 name=、Output(name=...) 与输出顺序/类型

• 输入命名：永不重命名或删除——保存的 Flow 以这些名称作为键引用输入；新增可选输入是安全的，删除/重命名则破坏所有用到它们的 Flow；
• 输出顺序：outputs = [...] 列表的顺序决定旧 Flow 的默认选择，重排即改变默认输出；
• 输出类型：收紧类型（如从 ["Message", "Data"] 缩到 ["Message"]）是破坏性变更，放宽类型才是安全的。

契约 6：输入默认值

修改 default= / value= 会静默改变依赖默认值的用户行为，除非旧默认值本身是 bug，否则应视为破坏性变更。

契约 7：Flow JSON Schema

• 事实来源：src/backend/base/langflow/initial_setup/starter_projects/*.json（规范示例）；
• 规则：顶层 data.nodes[*].data.node 结构与 data.edges 结构是公开契约；新增字段必须是带默认值的可选字段。

契约 8：公开 REST API

文档端点以 docs/docs/API-Reference/ 下的 api-flows-run.mdx、api-projects.mdx、api-logs.mdx、api-monitor.mdx、api-users.mdx 等为事实来源，带 include_in_schema=False 的端点属于内部接口。其中 POST /api/v1/run/{flow_id_or_name} 与 POST /api/v1/webhook/{flow_id_or_name} 是用户契约——请求体结构与状态码均被冻结。

契约 9：MCP 工具暴露

• 事实来源：src/backend/base/langflow/api/v1/mcp.py、mcp_projects.py，工具模式由 Output.tool_mode 或名为 component_as_tool 的输出切换；
• 规则：从已有组件输出上移除 tool_mode=True，或改名，都会让每一个把它当工具使用的 Agent Flow 失效。

契约 10：Message / Data / DataFrame 模式

这是组件间的"线缆格式"（wire format），定义于 src/lfx/src/lfx/schema/message.py。从源码可以看到契约所列字段全部是带默认值/可选的 pydantic 字段：

class Message(Data):
    text_key: str = "text"
    sender: str | None = None
    sender_name: str | None = None
    files: list[str | Image] | None = Field(default=[])
    session_id: str | UUID | None = Field(default="")
    timestamp: Annotated[str, timestamp_to_str_validator] = Field(
        default_factory=lambda: datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S.%f %Z")
    )
    flow_id: str | UUID | None = None
    error: bool = Field(default=False)
    edit: bool = Field(default=False)
    properties: Properties = Field(default_factory=Properties)
    category: Literal["message", "error", "warning", "info"] | None = "message"
    content_blocks: list[ContentType] = Field(default_factory=list)
    duration: int | None = None
    session_metadata: dict | None = None

规则是：只能新增带默认值的字段；重命名或改变任一已列出字段的类型，会破坏所有运行中的 Flow。源码中的注释也印证了这一设计取向：text 有意不自动折叠进 content_blocks，文本消息保持 content_blocks 为空以维持前端向后兼容——这正是契约 10 精神在具体实现中的落点。

契约 11：环境变量

• LANGFLOW_*（服务端）定义于 src/backend/base/langflow/services/settings/base.py 与 feature_flags.py；
• LFX_*（执行器）定义于 src/lfx/src/lfx/services/settings/base.py，少数直接经 os.getenv 读取（如 src/lfx/src/lfx/interface/components.py 中的 LFX_DEV）；
• 规则：这是公开部署契约，重命名必须走"同时读取新旧两个名字"的弃用周期。

契约 12：数据库模式

事实来源是 src/backend/base/langflow/services/database/models/ 与 alembic/versions/。规则有三条：永不跳过 make alembic-revision 直接改模型；永不修改历史迁移；以及一个极易被忽视的事实——自定义组件的 Python 源码存储在用户数据库中，重构了 from langflow.X import Y 用到的导入路径，会导致这些行在加载时失败。

契约 13：Starter Project JSON

src/backend/base/langflow/initial_setup/starter_projects/*.json 中的每个 Flow 都通过 name/type 引用真实组件。组件重命名、输入删除或输出类型变化都会破坏加载。任何组件改动之后，必须重新加载受影响的 starter project。

契约 14：Webhook 请求体形状

POST /api/v1/webhook/{flow_id_or_name} 被外部系统调用，响应状态（202 Accepted）与 dict 响应体形状被冻结。

契约 15：组件索引

src/lfx/src/lfx/_assets/component_index.json 是供前端消费的生成产物；任何字段/输出新增都要求重新生成，CI 会在相应 label 上强制执行。

三、改动前检查矩阵（Before-you-change Matrix）

CONTRACTS.md 把"准备做某事"映射到"必须检查/更新什么"，这是文档最具操作性的部分：

你准备……	必须检查 / 更新
重命名组件文件	在旁边新增新文件；旧类设置 legacy = True + replacement = [...]；更新每个测试的 file_names_mapping；在 starter_projects/*.json 中 grep 旧 type
重命名输入 name=	不要做。在旁边新增输入，必要时用组件的 legacy=True 弃用旧输入；在 starter_projects/*.json 中 grep 旧名
新增或重命名输出	重新生成 starter projects；重建组件索引
修改默认值	视为破坏性变更。在 starter projects + 测试中 grep 依赖
从输出上移除 tool_mode=True	搜索以它为工具的 Agent Flow / starter projects；这是用户可见的回退
给 Message 加字段	必须是带默认值的 Optional；永不重排现有字段
新增 REST 端点	面向用户则补进 docs/docs/API-Reference/；内部接口设 include_in_schema=False
修改 DB 模型	make alembic-revision message="..."；永不编辑历史 revision
改动 LANGFLOW_* / LFX_* 环境变量	至少一个小版本内继续以旧名作回退读取；写进 release notes
改动请求/响应模式	pydantic 模式 + src/frontend/src/types/ + 若持久化还需 alembic，在同一个 PR 内完成

四、看似无害的破坏性变更：8 个"清理式"陷阱

文档特别列出了八种"看起来像清理、实为用户可见回退"的改动，每一条都值得单独记住：

1. 组件上把 input_value 重命名为 text：引用该输入的 100% 已保存 Flow 全部丢失接线；
2. outputs = [a, b] 重排为 [b, a]：使用默认选择的旧 Flow 从此从错误的输出路由；
3. 收紧 Output(types=["Message", "Data"]) 为 ["Message"]：以 Data 解析的边在加载时变无效；
4. default="gpt-4o-mini" 改成 default="gpt-5"：静默地让用户重新计费；
5. langflow/components/foo/bar.py 移到 langflow/components/foo2/bar.py：用户数据库中 from langflow.components.foo.bar import ... 的自定义组件在下次加载时失败——且 file_names_mapping 测试仍然通过，因为它只校验所列历史版本，不校验用户代码；
6. 从向量存储的 as_dataframe 上去掉 tool_mode=True：所有把它当工具调用的 Agent 会看到工具凭空消失；
7. 给 Message 加必填字段：运行中部署里所有排队消息在下次读取时反序列化失败；
8. 重命名 starter project 文件：来自文档与教程的深链全部 404。

第 5 条尤其揭示了这套契约体系的边界：自动化测试保护的是"仓库内的历史版本"，而用户数据库里的自定义组件源码只能靠契约纪律保护——这正是契约 12 单独强调导入路径稳定性的原因。

五、落地实践：把契约文件当作变更前的强制清单

综合全文，在 Langflow 仓库中做一次改动前的标准动作可以归纳为：

1. 对照 15 行契约表：你的 diff 触及哪一行，就执行对应规则；
2. 对照改动前矩阵：确认检查/更新项全部完成（文件映射、starter project grep、组件索引重建、alembic、前端类型）；
3. 反向自查八种"无害陷阱"：默认值、输出顺序、类型收紧、tool_mode、导入路径、深链文件名；
4. 验证闭环：重生成 starter projects 与 component_index.json，重跑组件历史版本测试（file_names_mapping），重新加载受影响的 starter project。

这套"契约 + 矩阵 + 陷阱清单"的组合，本质上是把一个可视化工作流平台的向后兼容问题，收敛为一份可执行、可审查、无例外的规则集——任何贡献者（包括 AI Agent）在动手前都能用它判断自己的改动是"安全的演进"还是"静默的破坏"。