Langflow 开发实战指南从 AGENTS.md 看 Langflow 仓库的构建、架构与组件开发规范【免费下载链接】langflowLangflow is a powerful tool for building and deploying AI-powered agents and workflows.项目地址: https://gitcode.com/GitHub_Trending/la/langflowLangflow 是一个用于构建和部署 AI Agent 与工作流的可视化开发平台仓库采用 Python/FastAPI 后端 React/TypeScript 前端 轻量级执行器 CLIlfx的 Monorepo 组织方式。本篇基于仓库根目录的 AGENTS.md 逐节展开并结合当前仓库中的 Makefile、Makefile.frontend 与各子包源码讲清楚如何在本地完成 Langflow 的初始化、热重载开发、代码质量检查、测试与数据库迁移以及其 Monorepo 包结构、RBAC 授权层与自定义组件的完整开发规范——读完即可在源码级上参与 Langflow 的开发。一、环境前置要求AGENTS.md 在 “Prerequisites” 一节中明确了本地开发所需工具链工具版本要求Python3.10 – 3.14uv 0.4Python 包管理器Node.js 20.19.0推荐 v22.12 LTSnpmv10.9make用于构建协调这些要求在当前仓库中均可得到印证根 pyproject.toml 声明requires-python 3.10,3.15当前版本为1.12.0src/frontend/package.json 中engines.node为20.19.0React 依赖为^19.2.1Makefile 的check_tools目标会在make init前校验uv与npm是否已安装不满足则直接中止。注意AGENTS.md 中列出的命令如make init、make run_cli、make unit_tests、make alembic-revision等均已在 Makefile 与 Makefile.frontend 中确认存在。其中make backend依赖setup_env与install_backend最终通过uv run uvicorn --factory langflow.main:create_app启动make run_cli/make run_clic则是先构建前端静态产物再执行uv run langflow run。二、常用命令速查2.1 开发环境初始化与一键运行make init # 安装全部依赖 pre-commit hooks make run_cli # 构建并运行 Langflowhttp://localhost:7860 make run_clic # 清理前端构建缓存后重新构建并运行前端出现异常时使用对照 Makefile 源码可以看到各目标的实际行为init先执行check_tools校验工具链然后install_backenduv sync --frozen --extra postgresql、install_frontend最后uvx pre-commit install安装 git 钩子run_cli复用已有前端构建缓存依次执行install_frontend、install_backend、build_frontend最后以--host 0.0.0.0 --port 7860默认值来自 Makefile 顶部变量port ? 7860启动run_clic与run_cli的差异在于前置了clean_frontend_build目标——它会清空src/frontend/build与src/backend/base/langflow/frontend两处构建产物保证前端资源是全新构建的适合前端资源加载异常时排查问题。2.2 开发模式热重载make backend # FastAPI 运行在 7860 端口终端 1 make frontend # Vite 开发服务器运行在 3000 端口终端 2make backend实际执行的是uvicorn --factory langflow.main:create_app --reload当workers1时自动加--reload入口为 src/backend/base/langflow/main.py 中的create_app工厂函数make frontend定义在 Makefile.frontend 中先install_frontend再启动 Vite dev server。组件开发时建议开启动态加载以支持修改组件代码后免重启生效LFX_DEV1 make backend # 动态加载所有组件模块 LFX_DEVmistral,openai make backend # 只动态加载指定模块LFX_DEV的解析逻辑位于 lfx 包src/lfx/src/lfx/interface/components.py 中的解析函数说明开发模式必须显式通过该环境变量开启布尔模式1/true/yes动态加载全部模块逗号分隔列表则只加载对应模块。2.3 代码质量make format_backend # 格式化 Pythonruff—— 务必先于 lint 执行 make format_frontend # 格式化 TypeScriptbiome make format # 前后端一起格式化 make lint # 后端 lint / 类型检查Makefile 中format_backend的具体动作是uv run ruff check . --fixuv run ruff format .。需要说明的是当前 Makefile 中的lint目标实际输出为 No type checker configured. See PR #12448 for context.即本仓库当前阶段不再配置 mypy 类型检查前端检查则可用make format_frontend_checknpx biomejs/biome check。另外 Makefile 还提供codespell/fix_codespell拼写检查目标可作为提交前的补充检查。2.4 测试命令make unit_tests # 后端单元测试pytest 并行 make unit_tests asyncfalse # 顺序执行 uv run pytest path/to/test.py # 单个测试文件 uv run pytest path/to/test.py::test_name # 单个测试用例 make test_frontend # 前端 Jest 单元测试 make tests_frontend # 前端 Playwright e2e 测试make unit_tests在 Makefile 中默认追加--instafail -n auto实现 xdist 并行并带--durations-path与--splitting-algorithm least_duration做耗时统计与测试分割同时默认-m not api_key_required跳过需要外部 API Key 的测试。前端两条命令分别对应 Makefile.frontend 中的test_frontendJest与tests_frontendPlaywright配置见 src/frontend/jest.config.js 与 src/frontend/playwright.config.ts。此外 Makefile 还有integration_tests、integration_tests_api_keys、template_tests、lfx_tests等更细粒度的目标可在需要时选用。2.5 数据库迁移Alembicmake alembic-revision messageDescription # 创建迁移 make alembic-upgrade # 应用迁移 make alembic-downgrade # 回滚一个版本这些目标都会进入 src/backend/base/langflow 目录执行uv run alembic ...其中alembic-revision使用--autogenerate -m自动根据 SQLAlchemy 模型差异生成迁移脚本迁移版本文件位于src/backend/base/langflow/alembic/versions/。Makefile 中还提供了alembic-current、alembic-history、alembic-check、alembic-stamp等辅助目标方便排查迁移状态。数据库模型与迁移管理位于服务层src/backend/base/langflow/services/database/下。三、Monorepo 架构目录结构与包依赖关系AGENTS.md 给出的仓库结构如下src/ ├── backend/ │ ├── base/langflow/ # 核心后端包langflow-base │ │ ├── api/ # FastAPI 路由v1/、v2/ │ │ ├── components/ # 内置 Langflow 组件 │ │ ├── services/ # 服务层auth、database、cache 等 │ │ ├── graph/ # 流程图执行引擎 │ │ └── custom/ # 自定义组件框架 │ └── tests/ # 后端测试 ├── frontend/ # React/TypeScript UI │ └── src/ │ ├── components/ # UI 组件 │ ├── stores/ # Zustand 状态管理 │ └── icons/ # 组件图标 ├── langflow-core/ # 可独立使用、不绑定任何 provider 的发行版 ├── bundles/ # 精选 provider 集成 └── lfx/ # 轻量执行器与共享基础原语在当前仓库中可核对到的对应物src/backend/base/langflow/下确有api/、services/、graph/、custom/目录src/bundles/ 下是各 provider 的 bundleopenai、anthropic、google、ollama、lfx-bundles等src/lfx/ 是 lfx 子包其pyproject.toml当前版本同为1.12.0前端位于 src/frontend/。关键包与依赖方向langflow面向最终用户的完整包依赖langflow-core与精选 provider bundlelangflow-core服务完备、不捆绑 provider 的发行版拥有langflowCLIlangflow-base模块化应用平台API、服务层、图执行引擎通过 extras 追加服务集成lfx共享执行原语与独立 CLIlfx serve、lfx run。对外的依赖方向为langflow → langflow-core → langflow-base → lfxsrc/bundles/下的 provider 包只会被完整的langflow发行版引入。根 pyproject.toml 中可见该结构的实际体现主包依赖langflow-base~1.12.0并声明了一组带版本区间的lfx-*策展 bundle 依赖仓库注释说明精确 pin 保留在uv.lock与发布构建清单中主依赖只写有界区间以避免给下游带来解析冲突。服务层Service Layer后端服务集中在src/backend/base/langflow/services/下AGENTS.md 列出的核心子域为auth/—— 认证authorization/—— 授权RBAC插件层database/—— SQLAlchemy 模型与迁移cache/—— 缓存层storage/—— 文件存储tracing/—— 可观测性集成。从当前目录结构看services/下还包含session/、rate_limit/、jobs/、checkpoint/、memory_base/等更多子域服务按“一域一目录”的方式组织。四、RBAC 授权层接口、默认值与执行模型AGENTS.md 用较大篇幅描述了 Langflow 的授权Authorization设计这是理解其多用户权限体系的关键。核心要点是授权是与认证分离的可插拔层。4.1 OSS 提供的部分接口BaseAuthorizationService定义在 lfx 包中直通实现LangflowAuthorizationServicepass-through stub数据库 schemaauthz_*管理表与casbin_rule规则表路由守卫route guards。插件通过lfx.toml中的lfx.services入口点authorization_service注册与 SSO 的auth_service同一套模式。注册后的插件读取authz_*管理表并把编译后的规则写入casbin_rule。默认关闭LANGFLOW_AUTHZ_ENABLEDfalse。若开启但只注册了 OSS stub所有检查都返回 allow——stub 是 no-op路由保持连通审计日志audit rows依然会写入。真正的 allow/deny 必须注册授权插件才能实现。该开关在源码中可见于 src/backend/base/langflow/services/authorization/service.py。4.2 路由守卫Route Guards守卫实现位于langflow.services.authorization.guards旧路径langflow.services.authorization.utils为向后兼容做了再导出。当前仓库 src/backend/base/langflow/services/authorization/guards.py 中确认存在这些守卫函数ensure_flow_permission(user, FlowAction.*, flow_id..., flow_user_id..., workspace_id..., folder_id...)—— 单流程的 CRUD 执行ensure_deployment_permission(user, DeploymentAction.*, deployment_id..., deployment_user_id..., workspace_id..., project_id...)ensure_project_permission(user, ProjectAction.*, project_id..., project_user_id..., workspace_id...)ensure_knowledge_base_permission(user, KnowledgeBaseAction.*, kb_name..., kb_user_id...)ensure_variable_permission(user, VariableAction.*, variable_id..., variable_user_id...)ensure_file_permission(user, FileAction.*, file_id..., file_user_id...)ensure_share_permission(user, ShareAction.*, share_id..., share_user_id...)filter_visible_resources(user, resource_type..., candidates..., act...)—— 列表端点过滤在 OSS 中是安全 no-op。4.3 权限执行请求元组执行权限时的请求形状为(subject, domain, object, action)subjectuser:{uuid}domainproject:{uuid}→workspace:{uuid}→*由_resolve_flow_domain解析更具体的 domain 优先project 级授权可直接匹配workspace 级授权则通过插件侧角色继承向下流动objectflow:{uuid}/deployment:{uuid}/project:{uuid}/flow:*等actionread/write/create/delete/execute/deploy。4.4 共享感知读取Phase 3路由读取助手_read_flow、get_flow_by_id_or_endpoint_name、get_deployment、projects.py中的 project 读取、v2 文件读取器、variable.py的 PATCH/DELETE会根据BaseAuthorizationService.supports_cross_user_fetch()分支处理OSS 直通实现返回False因此保留原有的 owner 作用域查询——即使打开LANGFLOW_AUTHZ_ENABLEDtrue而没有注册插件也不会意外放宽可见范围插件侧设置SUPPORTS_CROSS_USER_FETCHTrue后资源只凭 id 即可加载由ensure_*_permission决定访问结果路由处理器可通过langflow.services.authorization.fetch.deny_to_404把插件拒绝的HTTPException(403)转换为HTTPException(404)以保护 UUID 隐私。4.5 Share CRUD 与审计 APIShare CRUDPhase 3/api/v1/authz/shares提供对authz_share行的 POST / GET / PATCH / DELETE。处理器强制执行 OSS 下限——只有资源属主或超级用户可以管理该资源的分享行直通实现无法让非属主创建 share 行。每次写入都会触发BaseAuthorizationService.invalidate_user/invalidate_all让已注册的 enforcer 可以丢弃缓存策略审计记录通过audit_decision以share:create/share:update/share:delete动作写入。审计查询 APIPhase 4GET /api/v1/authz/audit仅超级用户提供authz_audit_log的分页、可过滤视图支持user_id、resource_type、resource_id、action、result、since、until过滤单页上限 200 条。默认角色目录Phase 4统一的 foundations 迁移7c8d9e0f1a2b_authz_foundations播种了三个内置is_systemTrue角色viewer / developer / admin权限 slug 形如{resource}:{action}。OSS 本身不解释这些角色——它们存在是为了让注册插件的策略同步拥有一个稳定的引导来源。五、组件Component开发规范AGENTS.md 指出组件位于src/backend/base/langflow/components/新增组件的步骤为创建继承自Component的组件类定义display_name、description、icon、inputs、outputs按字母序添加到__init__.py使用LFX_DEV1 make backend热重载验证。重要约束修改组件的类名属于破坏性变更任何时候都不应这样做。类名是已保存 flow 中匹配组件的标识符也用于 UI 中标记需要更新的组件重命名会直接破坏使用该组件的既有 flow。文档给出的标准组件结构示例注意文档示例基于早期 import 路径当前仓库中组件框架位于src/backend/base/langflow/custom/且内置组件已按 provider 拆分到src/bundles/下的 bundle 包中新增内置组件时请以仓库内现有组件代码的实际 import 为准from langflow.custom import Component from langflow.io import MessageTextInput, Output class MyComponent(Component): display_name My Component description What it does icon component-icon # Lucide 图标名或自定义图标 inputs [ MessageTextInput(nameinput_value, display_nameInput), ] outputs [ Output(display_nameOutput, nameoutput, methodprocess), ] def process(self) - Message: # 组件逻辑 return Message(textself.input_value)组件测试组件测试放在src/backend/tests/unit/components/当前仓库该目录存在含conftest.py、bundles/等子目录。使用两个基类ComponentTestBaseWithClient—— 需要 API 访问的组件ComponentTestBaseWithoutClient—— 纯逻辑组件。必需的 fixturescomponent_class、default_kwargs、file_names_mapping。仓库还提供了make check_components_frozen对应的检查脚本 scripts/ci/check_components_frozen.py 与冻结目录清单 scripts/ci/frozen_component_dirs.txt用于在 CI 中约束组件目录的稳定性——这从侧面印证了“类名与组件目录是对外契约”这一规范。六、前端开发要点AGENTS.md 对前端的约定React 19 TypeScript ViteZustand管理状态xyflow/react做图流程画布可视化Tailwind CSS负责样式。以上均可在 src/frontend/package.json 与 src/frontend/vite.config.mts 中得到印证。自定义图标在src/frontend/src/icons/YourIcon/下创建 SVG 组件使用forwardRef导出并支持isDarkprop在lazyIconImports.ts中注册在 Python 组件中设置icon YourIcon。七、测试注意事项与 Graph 测试模式AGENTS.md 列出的测试注意事项与当前仓库的 Makefile 目标一致pytest.mark.api_key_required—— 需要外部 API Key 的测试make unit_tests默认跳过pytest.mark.no_blockbuster—— 跳过 blockbuster 插件数据库测试可能在批量执行时失败、单独执行时通过pre-commit 钩子要求使用uv run git commit运行 Python 命令时始终使用uv run在子包内如langflow-base、lfx运行测试前先同步该子包的 dev 依赖组uv sync --group dev --package langflow-base。默认的uv sync只解析顶层 workspace可能漏装 dev-only 的测试依赖例如fakeredis。Graph 测试标准模式正规的 Graph 测试遵循四步用已连接的组件构建图通过.set()调用连接各组件调用async_start并迭代结果校验结果。测试最佳实践尽量避免在测试中使用 mock优先使用真实集成测试更可靠。八、版本管理make patch v1.5.0 # 跨所有包更新版本AGENTS.md 说明该命令会更新pyproject.toml、src/backend/base/pyproject.toml、src/frontend/package.json。对照 Makefile 中patch目标的完整实现其实际动作远不止三处它还会同步src/lfx/pyproject.toml版本、组件索引src/lfx/src/lfx/_assets/component_index.json的版本字段、src/sdk/pyproject.toml与 lfx 对langflow-sdk的依赖下限、src/bundles/*各 bundle 的 lfx pin通过scripts/ci/sync_bundle_lfx_pin.py随后执行uv sync与npm install并行刷新锁文件并逐条 grep 校验上述文件确实被修改、修改后的依赖约束如langflow-base~X.Y.0的兼容下限、lfx~X.Y.Z精确对齐符合预期——任何一步校验失败都会中止。因此发布新版本时应以该目标的最终输出为准而不是手工改版本号。九、Pre-commit 工作流与 PR 规范Pre-commit 钩子在git commit时自动运行 ruff 与 biome因此不需要手动格式化。当改动较多时为避免额外的提交轮次AGENTS.md 建议暂存前运行一次make format_backend提前修掉大部分 ruff 问题使用uv run git commituv run确保 pre-commit 找到正确的 Python若改动了后端代码本地先跑make unit_tests反馈快于 CI。Pull Request 指南遵循语义化提交规范conventional commits引用所修复的 issue如Fixes #1234提交前确保所有测试通过。十、文档站点本地运行Langflow 的文档使用 Docusaurus位于 docs/ 目录cd docs yarn install yarn start # 开发服务器运行在 3000 端口3000 被占用时会提示改用 3001文档源码为docs/docs/下的.mdx文件Get-Started、Agents、Components、Deployment、Develop、Lfx、Tutorials 等栏目版本化历史文档在docs/versioned_docs/。小结AGENTS.md 是面向 AI 编码助手与人类贡献者的仓库操作手册它把“装环境 → 起服务 → 改代码 → 跑测试 → 提交 → 发版”这条链路的关键命令、目录职责与硬性约束尤其是组件类名不可重命名、uv run使用惯例、RBAC 默认关闭且插件可插拔压缩成了一页速查。配合 Makefile、Makefile.frontend 与各子包源码阅读可以完整理解 Langflow 从 Monorepo 组织、包依赖分层到权限模型的设计思路并据此安全地参与后端组件、前端 UI 与 lfx 执行器的开发。【免费下载链接】langflowLangflow is a powerful tool for building and deploying AI-powered agents and workflows.项目地址: https://gitcode.com/GitHub_Trending/la/langflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考