Prefect 仓库开发实战面向 AI Agent 的架构地图与工程契约解析【免费下载链接】prefectPrefect is a workflow orchestration framework for building resilient data pipelines in Python.项目地址: https://gitcode.com/GitHub_Trending/pr/prefectPrefect 是一个用于构建弹性数据管道的 Python 工作流编排平台提供 Python SDKflow/task装饰器、服务端编排后端server与 Web UI 三套用户界面。仓库根目录的 AGENTS.md 是面向开发者和 AI Agent 的仓库使用手册它把整个仓库的目录结构、常用命令、技术栈、架构边界与反模式浓缩成一套可执行契约。本文以该文档为主体结合仓库源码深入解读每一项约定背后的工程原因帮助你无论是人还是 Agent在 Prefect 仓库中快速定位模块、写出符合规范的代码、避免踩坑并理解 flow/task 引擎、状态机与并发模型的核心原理。一、AGENTS.md 是什么从能跑到符合契约Prefect 根目录的 AGENTS.md 是仓库级开发规范其开篇即明确 Guiding PrinciplesYour primary responsibility is to the project and its users. Every change should serve the broader user base — not just the immediate request. Be a quality gate: prefer correct, minimal, well-tested changes over fast ones.这段原则定义了贡献者的身份定位——质量闸门quality gate宁可正确、最小化、有充分测试的改动也不要为了速度牺牲正确性。这一原则贯穿全文后续的目录结构、命令、反模式、审查规则都是为了让每个改动符合 Prefect 的既有架构而不是本地能跑就行。该文件同时被要求与CLAUDE.md保持符号链接见原文 AGENTS.md always symlinked to CLAUDE.mdjustfile中也有symlink-agents-to-claude目标说明它是同时服务于人类开发者和 AI 编码助手的单一路径规范。仓库中每个关键目录都有一份 AGENTS.md 形成层级契约根目录定义全局结构与反模式src/prefect/AGENTS.md 定义 SDK 核心契约tests/AGENTS.md 定义测试纪律client/AGENTS.md 定义 prefect-client 构建约束docs/AGENTS.md 定义文档编写规则。在动手改代码之前AGENTS.md 要求先阅读公共贡献指南 docs/contribute/dev-contribute.mdx以确保改动符合 Prefect 的贡献期望、设计原则、AI 使用政策、测试标准与维护者评审标准纯文档改动需额外读 docs/contribute/docs-contribute.mdx集成类改动则需读 docs/contribute/contribute-integrations.mdx。二、目录结构一张仓库地图AGENTS.md 给出了完整的顶层目录树是理解仓库的第一步prefect/ ├── benches/ # 基准测试CLI、flows、tasks、imports ├── client/ # prefect-client 构建src/prefect/ 子集独立 PyPI 包 ├── compat-tests/ # 与 Prefect Cloud 的 REST API 兼容性测试 ├── Dockerfile # 生产容器镜像 ├── docs/ # Mintlify 文档见 docs/AGENTS.md ├── examples/ # 示例 flow自动发布到文档 ├── integration-tests/ # 端到端集成测试需要运行中的 server ├── justfile # 任务运行器just command ├── load_testing/ # 负载/性能测试 ├── plans/ # 设计与实现方案文档 ├── pyproject.toml # 根包配置 ├── schemas/ # JSON schemaprefect.yaml、settings ├── scripts/ # 代码生成与发布脚本 ├── src/ │ ├── integrations/ # 外部服务集成见 src/integrations/AGENTS.md │ └── prefect/ # 核心包SDK、server、CLI见 src/prefect/AGENTS.md ├── tests/ # 测试套件镜像 src/prefect/见 tests/AGENTS.md ├── tools/ # 构建工具 ├── ui/ # Vue UI旧版将被 ui-v2 取代 ├── ui-v2/ # React UI 重写见 ui-v2/AGENTS.md └── uv.lock # 锁文件自动生成不要手动编辑几个值得注意的工程决策client/不是源码目录。按 client/AGENTS.md 的说明它只包含构建配置build_client.sh会把src/prefect/复制到临时目录删除cli/整个 CLI、server/中除server/api/外的所有代码database、models、orchestration、schemas、services、utilities、deployments/recipes/与deployments/templates/、testing/再用client/pyproject.toml构建出轻量级prefect-client包。这也是为什么根 AGENTS.md 强调client 侧依赖的更新必须同步修改client/pyproject.toml——否则 prefect-client 构建会因引入了 server-only 依赖而失败。tests/目录镜像src/prefect/测试组织与源码一一对应如tests/engine/对应src/prefect/flow_engine.py、task_engine.py便于按模块定位测试。两套 UI 并存ui/Vue旧版与ui-v2/React新 UI开发时应把工作重心放在ui-v2/。三、Essential Commands从环境搭建到每日工作流AGENTS.md 把最常用的命令集中列出全部基于uv项目强制使用 uv 管理依赖反模式中明确 Never usepip installoruv pip# 依赖 uv sync # 安装全部开发依赖 just install # 同上外加 perf 依赖组 # 运行代码 uv run -s my_script.py # 以可编辑安装方式运行脚本 uv run --extra aws repros/1234.py # 运行需要集成 extra 的复现脚本 uv run --project ./src/integrations/name cmd # 在仓库根目录运行本地集成包 prefect server start # 启动本地 server prefect config view # 查看当前配置 # 测试详见 tests/AGENTS.md uv run pytest tests/path.py -k name # 运行指定测试 uv run pytest tests/path.py -x -n4 # 并行遇首个失败即停 # 静态检查与格式化 uv run ruff check --fix . # lint 并自动修复 uv run ruff format . # 格式化 uv run pre-commit run --all-files # 运行全部 pre-commit 钩子 # 文档仓库根目录执行 just docs # 启动 Mintlify 开发服务器 localhost:3000 just generate-docs # 重新生成所有文档产物 # UI仓库根目录执行 just ui-v2 # 启动 React 开发服务器 localhost:5173 # Docker docker build -t prefect . # 默认构建Python 3.10 docker build --build-arg PYTHON_VERSION3.12 -t prefect . # 指定 Python 版本 docker build --build-arg EXTRA_PIP_PACKAGESprefect-aws -t prefect . # 附加 extra 包结合 docs/contribute/dev-contribute.mdx 可以拼出完整的开发环境流程fork 仓库并 cloneuv sync创建虚拟环境并安装开发版 prefect文档同时给出python -m venv .venv pip install --group dev -e .的等价方案uv run prefect --version验证安装uv run pre-commit install安装 commit/push 钩子钩子包含 ruff、codespell、mypy部分、uv-lock、no-commit-to-branch 等见根 AGENTS.md 的 Tech Stack 章节开发 server 侧改动时可用prefect dev start全服务热重载、prefect dev api仅 API 热重载、prefect dev uiUI 热重载、prefect dev build-ui --include-v2构建静态 UI等辅助命令。justfile是这些命令的真正执行者。查看仓库根 justfile 可见just install实际是uv sync --group perfjust generate-docs依次执行 OpenAPI 生成、settings schema/ref 生成、prefect.yaml schema 生成、API 参考生成、CLI 文档生成与示例页生成等六个步骤。四、技术栈与快速参考表AGENTS.md 明确列出了仓库技术栈这是理解源码类型标注与工程选型的前提Python 3.10,3.15使用现代类型标注list[int]、T | NoneFastAPI构建 REST APIPydantic v2做校验SQLAlchemy 2.0异步 ORMAlembic做数据库迁移PostgreSQL/SQLite双数据库支持React TypeScript构建 UIui-v2Ruff负责 lint 与格式化Pre-commit 钩子ruff、codespell、mypy部分、uv-lock、no-commit-to-branch。文档还提供了一张组件 → 路径 → 测试的快速参考表是定位代码的第一索引组件路径测试核心 SDKflows、tasks、states、deploymentssrc/prefect/tests/Flow 与 task 引擎异步编排src/prefect/flow_engine.py、task_engine.pytests/engine/Client SDKschemas、HTTP clientsrc/prefect/client/tests/client/ServerAPI、数据库、调度src/prefect/server/tests/server/CLIsrc/prefect/cli/tests/cli/设置src/prefect/settings/tests/settings/集成prefect-aws、prefect-dbt等src/integrations/各集成自带React UI取代 Vueui/ui-v2/ui-v2/e2e/五、架构总览三层用户面与两条状态推进路径AGENTS.md 的 Architecture Overview 是全文技术含量最高的部分直接决定了哪些改动应该动哪些文件5.1 三个用户可见面Prefect 面向用户有三个表面Python SDKflow/task装饰器定义在src/prefect/flows.py与src/prefect/tasks.py是主要用户 APICLIprefect命令src/prefect/cli/REST APIFastAPI serversrc/prefect/server/。5.2 flow 与 task 的状态推进方式完全不同重要AGENTS.md 特别强调了一个最容易误解的架构事实Flow 状态转换必须经过 server。flow 引擎flow_engine.py向 server 发起阻塞式 API 调用以提议propose状态server 的编排层根据编排规则接受或拒绝。这是反模式清单中 Never bypass the server for flow state transitions 的底层原因——即使写测试也要走编排 API。Task 状态转换由 task 引擎本地管理。task 引擎task_engine.py通过set_state在本地推进状态并发出prefect.task_run.*事件经 WebSocket 投递它不向 server 提议状态。两条路径的处理方式不可互换。这个区别在 src/prefect/AGENTS.md 中被进一步细化为多条 Key Contracts。5.3 两个发布包与独立的集成包项目发布两个 PyPI 包prefect完整 SDK server与prefect-client轻量客户端子集client/的构建配置决定哪些文件进入后者集成包prefect-aws、prefect-dbt等是独立的 PyPI 包拥有各自版本从src/integrations/独立发布。5.4 异步优先的执行模型引擎flow_engine.py、task_engine.py本质是异步的同步的flow/task函数通过 worker 中的同步包装层运行。这意味着引擎代码存在 sync/async 双路径任何行为变更都必须同时应用两条路径见下文的 lockstep 契约。六、SDK 核心契约源码级的关键约束src/prefect/AGENTS.md 是根 AGENTS.md 在 SDK 层的细化罗列了约 18 条工程契约。以下是最容易出现 bug 的几条逐一结合源码说明。6.1 引擎特性应用顺序Engine ordering matters引擎按固定顺序应用特性重试retries、缓存caching、结果持久化result persistence、事务transactions。改动顺序或在某条引擎路径中漏掉某个特性是导致回归最常见的根源。因此涉及引擎的任何修改必须先确认 sync 与 async 两条路径的行为一致。6.2 状态转换前先持久化运行元数据事件订阅者在状态转换发生的瞬间观察运行属性如自定义的flow_run_name。因此任何订阅者会观察到的运行属性必须在调用set_state()之前写入 server转换之后写入的元数据对订阅者而言是过期的。6.3 事件与日志 WebSocket 订阅者是平行实现src/prefect/events/clients.py::PrefectEventSubscriber与src/prefect/logging/clients.py::PrefectLogsSubscriber重复实现了相同的重连/退避/去重逻辑包括reconnect_on_clean_close选项events/subscribers.py::FlowRunSubscriber用它确保干净断连不会吞掉终态事件。任何重连行为变更必须同步两个实现。6.4 Python 3.13 日期时间统一走 whenever 辅助函数这是 3.13 兼容性的硬规则types/_datetime.py 提供now()、_whenever_to_stdlib()、_whenever_zdt_from_py()、_whenever_pdt_from_py()等辅助函数屏蔽 whenever 0.7.x–0.9.x 与 ≥0.10.0 的 API 差异_WHENEVER_NEW_API标志whenever ≥0.10.0 时为 True守卫版本相关代码。规则包括禁止直接调用DateTime.now()、pendulum.now()一律使用types/_datetime.py的now()避免无参datetime.datetime.now()——它返回 naive datetime与now()产出的 tz-aware datetime 比较会抛TypeError需要保留时区信息时可显式使用datetime.now(ZoneInfo(UTC))这类 tz-aware 标准库调用禁止直接调用ZonedDateTime.from_py_datetime()、PlainDateTime.from_py_datetime()与.py_datetime()必须走辅助函数否则会在某个 whenever 版本下静默出错。从源码看Python ≤3.12 时DateTime类型别名指向 pendulum 的PydanticDateTime而 3.13 指向一个自实现的_DateTime带 Pydantic core schema强制把 naive datetime 校正为 UTC这正是 3.13 适配的核心机制。6.5 结果存储的三级解析链get_default_result_storage()按三级顺序解析默认结果存储可能触发 API 调用PREFECT_DEFAULT_RESULT_STORAGE_BLOCK设置server 配置的默认 block向 server 的 Configuration store 发 API 调用本地存储路径。任何 HTTP 错误都会静默吞掉这次 API 调用。引擎在上下文建立时用_get_default_persist_result()不是should_persist_result()判断是否自动启用持久化——后者不查询 server 默认值二者不可互换。6.6 Task runner 的序列化陷阱ProcessPoolTaskRunnerPrefectFuture不可 pickle不能跨子进程传递wait_for的 futures 必须在父进程等待并转为State后再提交子进程中的 task 引擎通过resolve_to_final_result处理State对未完成的上游会抛UpstreamTaskError。另外runner 反序列化时__init__不会执行实例属性要用getattr(self, _attr, default)访问。ThreadPoolTaskRunnerflow run 派发到子进程时会被 cloudpicklethreading.Lock等不可 pickle 的线程原语必须在__getstate__中丢弃、在__setstate__中重建任何新增的实例状态都要评估可 pickle 性。嵌套提交死锁有界ThreadPoolTaskRunner上当 worker task 提交子任务并阻塞在.result()、而所有max_workers线程都已占满时线程池会饥饿。_warn_if_nested_submit_would_deadlock会检测此情形并发出一次性警告修改池管理时需保留该检测。6.7 Flow-run 挂起Suspension在编排边界强制执行挂起通过FlowRunSuspensionRequest投递并用raise_if_flow_run_suspension_requested()触发。改动引擎、futures、task runner 或生成器执行时都要在交还控制给 flow 用户代码或提议可能让状态停留在Suspended的 flow 状态之前检查挂起请求并保持 sync/async 路径一致、避免逐边界读 API。6.8 子流程追踪任务使用 UUID 动态键flow_engine.py会给合成的追踪Task打上_is_subflow_tracking_taskTrue标记tasks.py检测到该标记后在提交任务上下文内部运行时为子流程分配 UUID不稳定dynamic_key防止父流程重试时并发兄弟子流程的键冲突而直接子流程调用无外层任务上下文保持稳定的顺序键以保留复用已完成子流程结果的重试优化。6.9 其他契约速览ResultRecordMetadata容忍未知 serializer 类型转为UnknownSerializer占位但已知类型字段非法仍抛ValidationErrorUnknownSerializer的dumps/loads抛RuntimeError——容忍仅用于检查元数据。ResultStore每次写入后调用mark_persisted()states.py的to_state_create在should_persist_result()返回 False如 run context 拆除后时以is_persisted作为兜底。任何新持久化路径若漏掉mark_persisted()会静默丢失已写入结果的 state 元数据。七、日志规范统一走 prefect.loggingSDK 契约明确规定使用prefect.logging的get_logger()而非裸logging.getLogger()——前者会做 API key 混淆并把 logger 置于prefect.命名空间下。不同场景的选择通用库代码 →get_logger(__name__)SDK 核心模块flows、tasks、engine→get_logger(flows)、get_logger(engine)Worker 实现 →get_worker_logger(self)编排运行的基建引擎→flow_run_logger(flow_run)/task_run_logger(task_run)需要子 logger 的 worker/runner → 在 run logger 上.getChild(worker|runner, extra{...})可能在 run 内外运行concurrency、transactions、blocks→ 先试get_run_logger()失败回退get_logger(...)裸logging.getLogger()只允许在src/prefect/logging/内部避免循环导入或配置第三方 logger 时使用。八、开发纪律约定与反模式8.1 代码约定私有实现细节用_private_method下划线前缀公共 API 变更必须获得批准No public API changes without approvaldocstring 中行内代码引用用单反引号不用双反引号开发前确保有可用的 server 或 Prefect Cloud用prefect config view检查当前 profile必要时后台启动prefect server start。8.2 反模式清单硬性禁止Never bypass the server for flow state transitions——永远走编排 API测试中亦然Never usepip installoruv pip——所有依赖管理只用uvNever use deferred imports函数内导入——除非为打破循环导入或处理可选依赖Never commit directly tomain——pre-commit 钩子强制执行Never skip pre-commit hooks--no-verify——修复底层问题而不是跳过Never amend commits--amend——创建新提交。8.3 Issue 工作流写代码前用gh issue view、gh pr view阅读 issue/PR 及评论理解范围与预期行为不清晰就先提问在repros/目录按 issue 编号创建复现脚本如repros/1234.py每个 issue 一个文件需加入.gitignore修复前必须确认 issue 可复现修复要配单元测试除非被要求不要删除repros/中的文件。8.4 PR Body 风格与代码审查PR 描述格式解决 issue 时以closes #1234开头随后一句摘要this PR {changes}细节放details标签内附上相关链接。代码审查按 REVIEW.md 执行。REVIEW.md 定义了双轴评审法Standards是否符合仓库指令与Spec是否忠实实现 issue/规格两轴独立评估所有新的功能 PR 必须有测试覆盖。九、测试纪律tests/AGENTS.md 的关键规则根 AGENTS.md 指向 tests/AGENTS.md 获取完整测试细节其中几条核心纪律值得单独强调Server 与 client 测试 fixture 不得混用server 测试用精简 client不使用完整的prefect_clientfixture优先真实操作而非 mock能用真实 flow、deployment、flow run 就不用 mockunittest.mock只留给外部服务与时间敏感操作测试必须确定性不依赖时序、顺序或外部状态SQLite 与 PostgreSQL 都在 CI 中测试。数据库隔离方面测试默认不会获得干净数据库只有依赖空库的测试计数、列所有 X、断言记录不存在才需要pytest.mark.clear_db标记可按测试、按类、按模块使用跳过该标记可获得 25%–100% 的套件加速。PREFECT_HOME是每个测试会话创建一次的临时目录直接向其中写文件的测试必须在 fixture teardown 中删除。创建领域对象会发出生命周期事件如prefect.object.createdserver 测试若用AssertingEventsClient断言事件数量必须在 fixture 建立后调用AssertingEventsClient.reset()。流超时测试必须用pytest.mark.timeout(methodthread)因为 pytest-timeout 默认的 SIGALRM 会干扰 Prefect 自身基于 SIGALRM 的 flow 超时机制。十、子模块导航与后续深入根 AGENTS.md 与各子目录 AGENTS.md 形成了分层契约体系。除本文已解读的几份外值得继续阅读的还包括src/prefect/AGENTS.mdSDK 核心契约本文第六、七节即源于此并在 Related 章节给出client/、server/、cli/、events/、settings/、concurrency/、logging/、runner/、deployments/、utilities/、blocks/、workers/、bundles/、plugins.py、docker/、telemetry/、testing/等子模块的一行说明tests/AGENTS.md测试套件纪律见第九节client/AGENTS.mdprefect-client 构建流程与依赖同步规则docs/AGENTS.mdMintlify 文档平台规范.mdx格式、frontmatter 约定、自动生成文件禁改清单、术语表REVIEW.md双轴代码审查标准。结语Prefect 的 AGENTS.md 不是一份可有可无的给 AI 的提示词而是一份把仓库二十年工程经验状态机边界、双引擎 lockstep、跨进程序列化陷阱、Python 3.13 兼容、双包发布、双 UI 迁移浓缩为可执行规则的架构契约。对开发者而言先读它再动手能避免绝大多数本地能跑、合入必挂的问题对 AI Agent 而言它提供了比代码搜索更高效的知识优先入口。从根目录的目录树出发配合 src/prefect/AGENTS.md 的引擎契约、tests/AGENTS.md 的测试纪律与 REVIEW.md 的审查标准即可在 Prefect 仓库中安全、高效地完成从定位、复现、修复到合入的完整开发闭环。【免费下载链接】prefectPrefect is a workflow orchestration framework for building resilient data pipelines in Python.项目地址: https://gitcode.com/GitHub_Trending/pr/prefect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Prefect 仓库开发实战：面向 AI Agent 的架构地图与工程契约解析
Prefect 仓库开发实战面向 AI Agent 的架构地图与工程契约解析【免费下载链接】prefectPrefect is a workflow orchestration framework for building resilient data pipelines in Python.项目地址: https://gitcode.com/GitHub_Trending/pr/prefectPrefect 是一个用于构建弹性数据管道的 Python 工作流编排平台提供 Python SDKflow/task装饰器、服务端编排后端server与 Web UI 三套用户界面。仓库根目录的 AGENTS.md 是面向开发者和 AI Agent 的仓库使用手册它把整个仓库的目录结构、常用命令、技术栈、架构边界与反模式浓缩成一套可执行契约。本文以该文档为主体结合仓库源码深入解读每一项约定背后的工程原因帮助你无论是人还是 Agent在 Prefect 仓库中快速定位模块、写出符合规范的代码、避免踩坑并理解 flow/task 引擎、状态机与并发模型的核心原理。一、AGENTS.md 是什么从能跑到符合契约Prefect 根目录的 AGENTS.md 是仓库级开发规范其开篇即明确 Guiding PrinciplesYour primary responsibility is to the project and its users. Every change should serve the broader user base — not just the immediate request. Be a quality gate: prefer correct, minimal, well-tested changes over fast ones.这段原则定义了贡献者的身份定位——质量闸门quality gate宁可正确、最小化、有充分测试的改动也不要为了速度牺牲正确性。这一原则贯穿全文后续的目录结构、命令、反模式、审查规则都是为了让每个改动符合 Prefect 的既有架构而不是本地能跑就行。该文件同时被要求与CLAUDE.md保持符号链接见原文 AGENTS.md always symlinked to CLAUDE.mdjustfile中也有symlink-agents-to-claude目标说明它是同时服务于人类开发者和 AI 编码助手的单一路径规范。仓库中每个关键目录都有一份 AGENTS.md 形成层级契约根目录定义全局结构与反模式src/prefect/AGENTS.md 定义 SDK 核心契约tests/AGENTS.md 定义测试纪律client/AGENTS.md 定义 prefect-client 构建约束docs/AGENTS.md 定义文档编写规则。在动手改代码之前AGENTS.md 要求先阅读公共贡献指南 docs/contribute/dev-contribute.mdx以确保改动符合 Prefect 的贡献期望、设计原则、AI 使用政策、测试标准与维护者评审标准纯文档改动需额外读 docs/contribute/docs-contribute.mdx集成类改动则需读 docs/contribute/contribute-integrations.mdx。二、目录结构一张仓库地图AGENTS.md 给出了完整的顶层目录树是理解仓库的第一步prefect/ ├── benches/ # 基准测试CLI、flows、tasks、imports ├── client/ # prefect-client 构建src/prefect/ 子集独立 PyPI 包 ├── compat-tests/ # 与 Prefect Cloud 的 REST API 兼容性测试 ├── Dockerfile # 生产容器镜像 ├── docs/ # Mintlify 文档见 docs/AGENTS.md ├── examples/ # 示例 flow自动发布到文档 ├── integration-tests/ # 端到端集成测试需要运行中的 server ├── justfile # 任务运行器just command ├── load_testing/ # 负载/性能测试 ├── plans/ # 设计与实现方案文档 ├── pyproject.toml # 根包配置 ├── schemas/ # JSON schemaprefect.yaml、settings ├── scripts/ # 代码生成与发布脚本 ├── src/ │ ├── integrations/ # 外部服务集成见 src/integrations/AGENTS.md │ └── prefect/ # 核心包SDK、server、CLI见 src/prefect/AGENTS.md ├── tests/ # 测试套件镜像 src/prefect/见 tests/AGENTS.md ├── tools/ # 构建工具 ├── ui/ # Vue UI旧版将被 ui-v2 取代 ├── ui-v2/ # React UI 重写见 ui-v2/AGENTS.md └── uv.lock # 锁文件自动生成不要手动编辑几个值得注意的工程决策client/不是源码目录。按 client/AGENTS.md 的说明它只包含构建配置build_client.sh会把src/prefect/复制到临时目录删除cli/整个 CLI、server/中除server/api/外的所有代码database、models、orchestration、schemas、services、utilities、deployments/recipes/与deployments/templates/、testing/再用client/pyproject.toml构建出轻量级prefect-client包。这也是为什么根 AGENTS.md 强调client 侧依赖的更新必须同步修改client/pyproject.toml——否则 prefect-client 构建会因引入了 server-only 依赖而失败。tests/目录镜像src/prefect/测试组织与源码一一对应如tests/engine/对应src/prefect/flow_engine.py、task_engine.py便于按模块定位测试。两套 UI 并存ui/Vue旧版与ui-v2/React新 UI开发时应把工作重心放在ui-v2/。三、Essential Commands从环境搭建到每日工作流AGENTS.md 把最常用的命令集中列出全部基于uv项目强制使用 uv 管理依赖反模式中明确 Never usepip installoruv pip# 依赖 uv sync # 安装全部开发依赖 just install # 同上外加 perf 依赖组 # 运行代码 uv run -s my_script.py # 以可编辑安装方式运行脚本 uv run --extra aws repros/1234.py # 运行需要集成 extra 的复现脚本 uv run --project ./src/integrations/name cmd # 在仓库根目录运行本地集成包 prefect server start # 启动本地 server prefect config view # 查看当前配置 # 测试详见 tests/AGENTS.md uv run pytest tests/path.py -k name # 运行指定测试 uv run pytest tests/path.py -x -n4 # 并行遇首个失败即停 # 静态检查与格式化 uv run ruff check --fix . # lint 并自动修复 uv run ruff format . # 格式化 uv run pre-commit run --all-files # 运行全部 pre-commit 钩子 # 文档仓库根目录执行 just docs # 启动 Mintlify 开发服务器 localhost:3000 just generate-docs # 重新生成所有文档产物 # UI仓库根目录执行 just ui-v2 # 启动 React 开发服务器 localhost:5173 # Docker docker build -t prefect . # 默认构建Python 3.10 docker build --build-arg PYTHON_VERSION3.12 -t prefect . # 指定 Python 版本 docker build --build-arg EXTRA_PIP_PACKAGESprefect-aws -t prefect . # 附加 extra 包结合 docs/contribute/dev-contribute.mdx 可以拼出完整的开发环境流程fork 仓库并 cloneuv sync创建虚拟环境并安装开发版 prefect文档同时给出python -m venv .venv pip install --group dev -e .的等价方案uv run prefect --version验证安装uv run pre-commit install安装 commit/push 钩子钩子包含 ruff、codespell、mypy部分、uv-lock、no-commit-to-branch 等见根 AGENTS.md 的 Tech Stack 章节开发 server 侧改动时可用prefect dev start全服务热重载、prefect dev api仅 API 热重载、prefect dev uiUI 热重载、prefect dev build-ui --include-v2构建静态 UI等辅助命令。justfile是这些命令的真正执行者。查看仓库根 justfile 可见just install实际是uv sync --group perfjust generate-docs依次执行 OpenAPI 生成、settings schema/ref 生成、prefect.yaml schema 生成、API 参考生成、CLI 文档生成与示例页生成等六个步骤。四、技术栈与快速参考表AGENTS.md 明确列出了仓库技术栈这是理解源码类型标注与工程选型的前提Python 3.10,3.15使用现代类型标注list[int]、T | NoneFastAPI构建 REST APIPydantic v2做校验SQLAlchemy 2.0异步 ORMAlembic做数据库迁移PostgreSQL/SQLite双数据库支持React TypeScript构建 UIui-v2Ruff负责 lint 与格式化Pre-commit 钩子ruff、codespell、mypy部分、uv-lock、no-commit-to-branch。文档还提供了一张组件 → 路径 → 测试的快速参考表是定位代码的第一索引组件路径测试核心 SDKflows、tasks、states、deploymentssrc/prefect/tests/Flow 与 task 引擎异步编排src/prefect/flow_engine.py、task_engine.pytests/engine/Client SDKschemas、HTTP clientsrc/prefect/client/tests/client/ServerAPI、数据库、调度src/prefect/server/tests/server/CLIsrc/prefect/cli/tests/cli/设置src/prefect/settings/tests/settings/集成prefect-aws、prefect-dbt等src/integrations/各集成自带React UI取代 Vueui/ui-v2/ui-v2/e2e/五、架构总览三层用户面与两条状态推进路径AGENTS.md 的 Architecture Overview 是全文技术含量最高的部分直接决定了哪些改动应该动哪些文件5.1 三个用户可见面Prefect 面向用户有三个表面Python SDKflow/task装饰器定义在src/prefect/flows.py与src/prefect/tasks.py是主要用户 APICLIprefect命令src/prefect/cli/REST APIFastAPI serversrc/prefect/server/。5.2 flow 与 task 的状态推进方式完全不同重要AGENTS.md 特别强调了一个最容易误解的架构事实Flow 状态转换必须经过 server。flow 引擎flow_engine.py向 server 发起阻塞式 API 调用以提议propose状态server 的编排层根据编排规则接受或拒绝。这是反模式清单中 Never bypass the server for flow state transitions 的底层原因——即使写测试也要走编排 API。Task 状态转换由 task 引擎本地管理。task 引擎task_engine.py通过set_state在本地推进状态并发出prefect.task_run.*事件经 WebSocket 投递它不向 server 提议状态。两条路径的处理方式不可互换。这个区别在 src/prefect/AGENTS.md 中被进一步细化为多条 Key Contracts。5.3 两个发布包与独立的集成包项目发布两个 PyPI 包prefect完整 SDK server与prefect-client轻量客户端子集client/的构建配置决定哪些文件进入后者集成包prefect-aws、prefect-dbt等是独立的 PyPI 包拥有各自版本从src/integrations/独立发布。5.4 异步优先的执行模型引擎flow_engine.py、task_engine.py本质是异步的同步的flow/task函数通过 worker 中的同步包装层运行。这意味着引擎代码存在 sync/async 双路径任何行为变更都必须同时应用两条路径见下文的 lockstep 契约。六、SDK 核心契约源码级的关键约束src/prefect/AGENTS.md 是根 AGENTS.md 在 SDK 层的细化罗列了约 18 条工程契约。以下是最容易出现 bug 的几条逐一结合源码说明。6.1 引擎特性应用顺序Engine ordering matters引擎按固定顺序应用特性重试retries、缓存caching、结果持久化result persistence、事务transactions。改动顺序或在某条引擎路径中漏掉某个特性是导致回归最常见的根源。因此涉及引擎的任何修改必须先确认 sync 与 async 两条路径的行为一致。6.2 状态转换前先持久化运行元数据事件订阅者在状态转换发生的瞬间观察运行属性如自定义的flow_run_name。因此任何订阅者会观察到的运行属性必须在调用set_state()之前写入 server转换之后写入的元数据对订阅者而言是过期的。6.3 事件与日志 WebSocket 订阅者是平行实现src/prefect/events/clients.py::PrefectEventSubscriber与src/prefect/logging/clients.py::PrefectLogsSubscriber重复实现了相同的重连/退避/去重逻辑包括reconnect_on_clean_close选项events/subscribers.py::FlowRunSubscriber用它确保干净断连不会吞掉终态事件。任何重连行为变更必须同步两个实现。6.4 Python 3.13 日期时间统一走 whenever 辅助函数这是 3.13 兼容性的硬规则types/_datetime.py 提供now()、_whenever_to_stdlib()、_whenever_zdt_from_py()、_whenever_pdt_from_py()等辅助函数屏蔽 whenever 0.7.x–0.9.x 与 ≥0.10.0 的 API 差异_WHENEVER_NEW_API标志whenever ≥0.10.0 时为 True守卫版本相关代码。规则包括禁止直接调用DateTime.now()、pendulum.now()一律使用types/_datetime.py的now()避免无参datetime.datetime.now()——它返回 naive datetime与now()产出的 tz-aware datetime 比较会抛TypeError需要保留时区信息时可显式使用datetime.now(ZoneInfo(UTC))这类 tz-aware 标准库调用禁止直接调用ZonedDateTime.from_py_datetime()、PlainDateTime.from_py_datetime()与.py_datetime()必须走辅助函数否则会在某个 whenever 版本下静默出错。从源码看Python ≤3.12 时DateTime类型别名指向 pendulum 的PydanticDateTime而 3.13 指向一个自实现的_DateTime带 Pydantic core schema强制把 naive datetime 校正为 UTC这正是 3.13 适配的核心机制。6.5 结果存储的三级解析链get_default_result_storage()按三级顺序解析默认结果存储可能触发 API 调用PREFECT_DEFAULT_RESULT_STORAGE_BLOCK设置server 配置的默认 block向 server 的 Configuration store 发 API 调用本地存储路径。任何 HTTP 错误都会静默吞掉这次 API 调用。引擎在上下文建立时用_get_default_persist_result()不是should_persist_result()判断是否自动启用持久化——后者不查询 server 默认值二者不可互换。6.6 Task runner 的序列化陷阱ProcessPoolTaskRunnerPrefectFuture不可 pickle不能跨子进程传递wait_for的 futures 必须在父进程等待并转为State后再提交子进程中的 task 引擎通过resolve_to_final_result处理State对未完成的上游会抛UpstreamTaskError。另外runner 反序列化时__init__不会执行实例属性要用getattr(self, _attr, default)访问。ThreadPoolTaskRunnerflow run 派发到子进程时会被 cloudpicklethreading.Lock等不可 pickle 的线程原语必须在__getstate__中丢弃、在__setstate__中重建任何新增的实例状态都要评估可 pickle 性。嵌套提交死锁有界ThreadPoolTaskRunner上当 worker task 提交子任务并阻塞在.result()、而所有max_workers线程都已占满时线程池会饥饿。_warn_if_nested_submit_would_deadlock会检测此情形并发出一次性警告修改池管理时需保留该检测。6.7 Flow-run 挂起Suspension在编排边界强制执行挂起通过FlowRunSuspensionRequest投递并用raise_if_flow_run_suspension_requested()触发。改动引擎、futures、task runner 或生成器执行时都要在交还控制给 flow 用户代码或提议可能让状态停留在Suspended的 flow 状态之前检查挂起请求并保持 sync/async 路径一致、避免逐边界读 API。6.8 子流程追踪任务使用 UUID 动态键flow_engine.py会给合成的追踪Task打上_is_subflow_tracking_taskTrue标记tasks.py检测到该标记后在提交任务上下文内部运行时为子流程分配 UUID不稳定dynamic_key防止父流程重试时并发兄弟子流程的键冲突而直接子流程调用无外层任务上下文保持稳定的顺序键以保留复用已完成子流程结果的重试优化。6.9 其他契约速览ResultRecordMetadata容忍未知 serializer 类型转为UnknownSerializer占位但已知类型字段非法仍抛ValidationErrorUnknownSerializer的dumps/loads抛RuntimeError——容忍仅用于检查元数据。ResultStore每次写入后调用mark_persisted()states.py的to_state_create在should_persist_result()返回 False如 run context 拆除后时以is_persisted作为兜底。任何新持久化路径若漏掉mark_persisted()会静默丢失已写入结果的 state 元数据。七、日志规范统一走 prefect.loggingSDK 契约明确规定使用prefect.logging的get_logger()而非裸logging.getLogger()——前者会做 API key 混淆并把 logger 置于prefect.命名空间下。不同场景的选择通用库代码 →get_logger(__name__)SDK 核心模块flows、tasks、engine→get_logger(flows)、get_logger(engine)Worker 实现 →get_worker_logger(self)编排运行的基建引擎→flow_run_logger(flow_run)/task_run_logger(task_run)需要子 logger 的 worker/runner → 在 run logger 上.getChild(worker|runner, extra{...})可能在 run 内外运行concurrency、transactions、blocks→ 先试get_run_logger()失败回退get_logger(...)裸logging.getLogger()只允许在src/prefect/logging/内部避免循环导入或配置第三方 logger 时使用。八、开发纪律约定与反模式8.1 代码约定私有实现细节用_private_method下划线前缀公共 API 变更必须获得批准No public API changes without approvaldocstring 中行内代码引用用单反引号不用双反引号开发前确保有可用的 server 或 Prefect Cloud用prefect config view检查当前 profile必要时后台启动prefect server start。8.2 反模式清单硬性禁止Never bypass the server for flow state transitions——永远走编排 API测试中亦然Never usepip installoruv pip——所有依赖管理只用uvNever use deferred imports函数内导入——除非为打破循环导入或处理可选依赖Never commit directly tomain——pre-commit 钩子强制执行Never skip pre-commit hooks--no-verify——修复底层问题而不是跳过Never amend commits--amend——创建新提交。8.3 Issue 工作流写代码前用gh issue view、gh pr view阅读 issue/PR 及评论理解范围与预期行为不清晰就先提问在repros/目录按 issue 编号创建复现脚本如repros/1234.py每个 issue 一个文件需加入.gitignore修复前必须确认 issue 可复现修复要配单元测试除非被要求不要删除repros/中的文件。8.4 PR Body 风格与代码审查PR 描述格式解决 issue 时以closes #1234开头随后一句摘要this PR {changes}细节放details标签内附上相关链接。代码审查按 REVIEW.md 执行。REVIEW.md 定义了双轴评审法Standards是否符合仓库指令与Spec是否忠实实现 issue/规格两轴独立评估所有新的功能 PR 必须有测试覆盖。九、测试纪律tests/AGENTS.md 的关键规则根 AGENTS.md 指向 tests/AGENTS.md 获取完整测试细节其中几条核心纪律值得单独强调Server 与 client 测试 fixture 不得混用server 测试用精简 client不使用完整的prefect_clientfixture优先真实操作而非 mock能用真实 flow、deployment、flow run 就不用 mockunittest.mock只留给外部服务与时间敏感操作测试必须确定性不依赖时序、顺序或外部状态SQLite 与 PostgreSQL 都在 CI 中测试。数据库隔离方面测试默认不会获得干净数据库只有依赖空库的测试计数、列所有 X、断言记录不存在才需要pytest.mark.clear_db标记可按测试、按类、按模块使用跳过该标记可获得 25%–100% 的套件加速。PREFECT_HOME是每个测试会话创建一次的临时目录直接向其中写文件的测试必须在 fixture teardown 中删除。创建领域对象会发出生命周期事件如prefect.object.createdserver 测试若用AssertingEventsClient断言事件数量必须在 fixture 建立后调用AssertingEventsClient.reset()。流超时测试必须用pytest.mark.timeout(methodthread)因为 pytest-timeout 默认的 SIGALRM 会干扰 Prefect 自身基于 SIGALRM 的 flow 超时机制。十、子模块导航与后续深入根 AGENTS.md 与各子目录 AGENTS.md 形成了分层契约体系。除本文已解读的几份外值得继续阅读的还包括src/prefect/AGENTS.mdSDK 核心契约本文第六、七节即源于此并在 Related 章节给出client/、server/、cli/、events/、settings/、concurrency/、logging/、runner/、deployments/、utilities/、blocks/、workers/、bundles/、plugins.py、docker/、telemetry/、testing/等子模块的一行说明tests/AGENTS.md测试套件纪律见第九节client/AGENTS.mdprefect-client 构建流程与依赖同步规则docs/AGENTS.mdMintlify 文档平台规范.mdx格式、frontmatter 约定、自动生成文件禁改清单、术语表REVIEW.md双轴代码审查标准。结语Prefect 的 AGENTS.md 不是一份可有可无的给 AI 的提示词而是一份把仓库二十年工程经验状态机边界、双引擎 lockstep、跨进程序列化陷阱、Python 3.13 兼容、双包发布、双 UI 迁移浓缩为可执行规则的架构契约。对开发者而言先读它再动手能避免绝大多数本地能跑、合入必挂的问题对 AI Agent 而言它提供了比代码搜索更高效的知识优先入口。从根目录的目录树出发配合 src/prefect/AGENTS.md 的引擎契约、tests/AGENTS.md 的测试纪律与 REVIEW.md 的审查标准即可在 Prefect 仓库中安全、高效地完成从定位、复现、修复到合入的完整开发闭环。【免费下载链接】prefectPrefect is a workflow orchestration framework for building resilient data pipelines in Python.项目地址: https://gitcode.com/GitHub_Trending/pr/prefect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
