示例仓库flow-forge本篇讲这个学习项目现在能做什么——装依赖、起服务、探活、确认数据库能连上。读者可以几乎不读 Python重点是每块功能解决什么问题以及目录为什么那样摆。先说结论Flow Forge 要对齐的是 Dify 一类产品里的Workflow工作流把多步处理画成一张图再执行。但「图怎么跑」之前仓库必须先具备三件很土、却绕不开的能力能力用户能感知到什么依赖可安装别人机器上也能装齐同样的库服务可启动浏览器或curl能打到一个地址存储可接通以后保存「跑过一次工作流」有地方落一句话本篇只证明「后端壳子活着」工作流本身下一篇再讲。1. 这个项目要解决什么问题对照 Dify 学习最容易踩的坑是一上来对着庞大源码找「智能」相关文件结果卡在——依赖装不上 / 版本对不上不知道从哪个命令启动业务代码和「收 HTTP 请求」的代码糊在一起越改越乱所以 Flow Forge 后端先提供一个最小可用服务不跑工作流只回答「我还活着」并把以后要用的分层位置留好。仓库大致分成目录功能角色api/后端现在的主角web/前端以后再做现在只有说明占位docs/blog/本系列文章你只需要关心api/能不能在你电脑上按文档跑通。2. 功能一把「需要哪些库」说清楚并一键装好Python 项目常靠一个清单文件声明依赖本仓是api/pyproject.toml。里面写明了语言版本至少Python 3.12跑服务用Flask提供 HTTP 接口以后校验请求数据用Pydantic本篇几乎还没上场访问数据库用SQLAlchemy跑测试用pytest装依赖我们用uv一个专门管 Python 项目环境的工具命令功能uv sync按清单把库装进本项目的独立环境不污染你电脑全局 Pythonuv run …在这个环境里执行后面的命令跟跑cdapi uvsync装完你就有了一个「可复现的后端环境」。这和有没有工作流无关但没有它后面什么都演示不了。3. 功能二起一个 HTTP 服务并提供「探活」接口探活health check客户端访问一个固定地址服务若正常就返回简单成功信息。部署、本地调试都会先打这个口确认进程真的起来了。本仓约定地址GET /health成功时HTTP 状态码200正文大致是{status:ok}启动在api/目录uv run flask--appflow_forge.app:create_app run--debug然后curlhttp://127.0.0.1:5000/health看到ok就说明Web 服务进程在、路由挂上了。4. 功能三为什么目录要分成 controllers / services / core这不是为了「目录好看」而是为了和 Dify 后端常见读法对齐并限制「改功能时该动哪一层」层管什么现在有什么controllers对外收 HTTP、回状态码和 JSON已有/healthservices编排把多个步骤串起来先留空位core领域工作流图、节点、执行规则等先留空位可以把它想成流水线浏览器 / curl → controllers门口接待 → services前台办事以后 → core核心业务规则以后 → 数据库今天只有「门口接待」有活干有人问健康状况门口直接回答不必进核心车间。等工作流做出来新逻辑应主要长在core/services而不是把执行器全写进路由文件——否则以后对照 Dify 源码时两边的「职责地图」对不上。组装关系用白话读不必抠语法有一个叫「创建应用」的入口函数负责连一下数据库、挂上路由、交出可运行的服务对象。/health路由单独放在 controllers 里由入口挂载上去。测试也走同一套入口在测试里「假启动」一下服务请求/health断言返回ok。对应源码位置想对照时再点开即可组装入口api/src/flow_forge/app.py探活接口api/src/flow_forge/controllers/health.py5. 功能四数据库先「能连上」不先建业务表工作流跑起来之后至少要存某次运行的结果、每一步的状态。那需要数据库。本仓第一阶段用SQLite一个本地文件型数据库不必先装 Postgres。现在实现的功能只有默认在约定目录准备好数据库文件路径启动时执行一次极简查询相当于问数据库「你在吗」若成功把连接能力挂在应用上供以后使用还没有「工作流表」「运行记录表」——那些属于工作流功能本身。本篇只保证存储这条线没有断。源码api/src/flow_forge/db.py6. 你怎么确认「这些功能都好了」不必读测试代码只要在api/执行uv run pytest全部通过通常意味着检查项对应功能分层目录可被正确加载项目结构没装错/health返回成功探活可用数据库能执行探测查询存储入口可用根目录README.md把安装、测试、启动写在一起按它跟跑即可。前端web/目前没有可点的页面这是刻意的本篇功能边界停在后端壳子避免「还没懂探活又要先学一整套前端工程」。下一篇会补哪块功能有了「能装、能起、能探活、能连库」下一篇才谈工作流真正的产品能力例如用一份图描述「开始 → 模板拼接 → 结束」触发一次运行拿到输出把每一步状态记下来方便以后回看那些才是对照 Dify Workflow 时最该对齐的功能面。你可以从这里带走什么学习大型项目可以先对齐「能跑的最小功能面」再对齐复杂业务。探活接口是后端是否活着的统一信号和业务聪明与否无关。controllers / services / core是职责地图不是装饰今天空着的层是为明天的工作流留位。uv解决的是「依赖与命令可复现」值得当作 Python 项目的默认门牌。数据库可以先验证连通业务表跟功能一起长不必空建一堆表。仓库链接GitHubhttps://github.com/jimchou-h/flow-forge跟跑说明README.md探活controllers/health.py启动组装app.py数据库入口db.py欢迎 Star、Issue 和 PR。本文只覆盖 Flow Forge 后端「能装、能起、能探活、能连库」四块功能不包含工作流执行。