核心定位与能力

Prefect 的核心能力围绕"可观察、可恢复、可调度"三个维度展开：

• 弹性工作流（Resilient Workflows）：通过任务与流的状态机机制，失败的任务可被重试或缓存命中。
• 动态响应（Dynamic Pipelines）：通过 prefect.runtime 模块在运行中访问动态属性（例如 flow_run.id、deployment.parameters），使工作流能根据上下文做出分支。资料来源：src/prefect/runtime/__init__.py
• 事件驱动自动化（Automations）：通过事件流（events）触发下游动作，事件体系在 src/prefect/server/api/server.py 中作为独立的 API 路由 api.events.router 被挂载到主应用。
• 部署（Deployments）：用户可以将 @flow 函数打包为部署对象，并交由 Worker 拉起执行。部署的创建与运行在 src/prefect/server/api/deployments.py 中通过 DeploymentFlowRunCreate 与 RunDeployment 动作实现。

架构组成

Prefect 的代码仓库天然分为三个相互协作的子系统：Client、Server/API 与 UI。下面用一张概览图展示主要组件与请求路径。

graph LR
    A[Python 脚本 / SDK] -->|Prefect Client| B[Prefect Server / API]
    B -->|SQLAlchemy ORM| C[(关系型数据库)]
    B -->|WebSocket 事件流| D[UI v2 / Dashboard]
    B -->|Workers| E[Kubernetes / 进程 / Docker]
    E -->|回写状态| B
    D -->|REST/WS 订阅| B

• Client 端：Python SDK 与 PrefectHttpxAsyncClient 协同工作，src/prefect/server/api/clients.py 中的 BaseClient 会优先调用本地 create_app() 缓存的服务器实例。
• Server/API 端：由 FastAPI 应用承载，在 src/prefect/server/api/__init__.py 中明确导出了 27 个功能域路由（flows、flow_runs、deployments、work_queues、workers、events、automations、variables 等）。
• UI 端：ui-v2/package.json 揭示了 UI 是基于 React、Radix UI、CodeMirror、TanStack Router 等构建的 SPA；build-storybook 表明其设计系统是独立可预览的。

关键子系统

Server API 路由域

prefect.server.api 包下每个模块都对应一个业务域，以 PrefectRouter 包装 FastAPI 路由。server/api/server.py 中的 SQLALCHEMY_CALL_CREATE_APP 路径将这些路由聚合到同一个 FastAPI 应用，便于 self-host 部署时统一鉴权与中间件。资料来源：src/prefect/server/api/__init__.py

数据查询与历史聚合

run_history 路由提供按时间桶聚合 flow / task run 历史的能力，强制 history_interval >= 1s 以规避 SQLite 精度问题，并支持 FlowFilter、WorkPoolFilter、WorkQueueFilter 等过滤对象。资料来源：src/prefect/server/api/run_history.py

Job 变量校验

validation.py 中实现了分层合并顺序：work pool → deployment → flow run；只有在最末端的 flow run 阶段才会校验"必填字段"。该模块使用 Pydantic v1 生成的 JSON Schema，对部分字段做了特殊处理以避免误报。资料来源：src/prefect/server/api/validation.py

动态 Schema 表单

UI 端通过 SchemaForm 组件消费来自 API 的 JSON Schema，支持 __prefect_kind 来渲染 json、work_pool 等专用输入控件。资料来源：ui-v2/src/components/schemas/readme.md

集成生态

src/integrations 目录托管了与外部系统的官方集成包。prefect-slack 通过 send_chat_message 把 Flow 的运行结果推送到 Slack 频道；prefect-dbt、prefect-github、prefect-gitlab、prefect-bitbucket 等则以独立 PyPI 包形式发布，文档统一托管在 https://docs.prefect.io/integrations。资料来源：src/integrations/prefect-slack/README.md

社区与近期动态

社区近期关注度较高的主题包括：

• 并发子流结果错位（#22259）：当子流通过 task.submit() 包装并发执行时，虚拟 task run 的 dynamic_key 会因按位置递增而错位，导致父流重试时采用错误子流的持久化结果。
• Redis 事件流残留（#22136）：当 PREFECT_MESSAGING_BROKER=prefect_redis.messaging 时，ephemeral_subscription() 会创建 ephemeral-{hostname}-* 形式的 consumer group，异常关闭后无法回收，进而阻止 events stream 的 trim。
• 测试 Harness 缺失 routes 属性（#22307）：FastAPI 0.137 不再为 router 自动注入 .routes，PrefectRouter 需要显式补齐该属性以保持向后兼容（3.7.5.dev4 中已修复）。
• Per-schedule 参数（#14524）：长期诉求 —— Worker-based 部署的每条 schedule 允许独立参数集。
• 并发限制的孤立 Slot（#17415）：leaky bucket 模式下进程崩溃会留下未归还的 slot，社区正在讨论加入显式归还/超时回收。

最新发布节奏方面，3.7.5 主题为 "No run left CANCELLING"，引入了 cancelling 超时清理 producer 与 Worker 通道可观测性；3.7.4 主题为 "From cradle to grave"，补齐了 Variables、Flows、Block Documents、Automations 等领域对象的生命周期事件（created/updated/deleted）。

See Also

• Server API Reference（即将推出）
• Deployments & Schedules
• Workers & Work Pools
• Schema Forms (UI v2)

概述

src/ 目录是 Prefect 工作流编排框架的核心源代码组织区，承载了核心运行时、API 服务、集成扩展以及前端界面等多个子项目。根据 README.md 的定位，Prefect 是一个用于构建弹性数据管道的 Python 工作流编排框架，提供调度、缓存、重试与事件驱动自动化等能力。

src/ 下的目录按职责可大致划分为三大块：

概述与定位

prefect.server 是 Prefect 自托管服务端的核心实现包，对应用户运行 prefect server start 时启动的本地 API 与 UI 后端。它在功能上承担 Prefect Cloud 的所有领域对象管理职责：Flow / Flow Run、Task Run、Deployment、Work Pool、Work Queue、Block、Artifact、Automation、Variable、Concurrency Limit、Event 等的 CRUD、过滤、调度编排与状态机推进。

服务端采用 FastAPI + SQLAlchemy + Pydantic 的分层结构：路由层由 src/prefect/server/api/ 提供；ORM 与业务逻辑位于 src/prefect/server/models/；请求/响应契约由 src/prefect/server/schemas/ 定义；数据库访问通过 PrefectDBInterface 抽象，支持 SQLite（默认）与 PostgreSQL。

资料来源：src/prefect/server/api/__init__.py:1-58

API 路由分层

prefect.server.api 子包通过 __getattr__ 实现按需导入，导出 30+ 个子模块。每个子模块都基于 PrefectRouter（位于 prefect.server.utilities.server）声明带前缀的 FastAPI 路由，例如 block_schemas、block_documents、deployments、flow_runs、task_runs、work_queues、workers、events、automations、variables、concurrency_limits / concurrency_limits_v2、artifacts、logs、task_workers、saved_searches、run_history、csrf_token、admin、ui 等。

服务端在 create_app() 中按固定顺序 include_router 拼装最终应用，典型片段如下：

api.flows.router,
api.deployments.router,
api.flow_runs.router,
api.work_queues.router,
api.workers.router,
api.events.router,
api.automations.router,
api.variables.router,
api.artifacts.router,
api.block_schemas.router,
api.block_documents.router,

资料来源：src/prefect/server/api/server.py:1-60、src/prefect/server/api/__init__.py:1-58

核心域：Deployment 路由

src/prefect/server/api/deployments.py 是最复杂的端点之一，负责 Deployment 的创建、更新、查询、删除以及按计划运行 flow_run。其特殊点在于：

• 在创建/更新前调用 prefect.server.api.validation 中的 validate_job_variables_for_deployment / validate_job_variables_for_deployment_flow_run，对 work pool 的 base job template 进行 JSON Schema 校验。
• 应用顺序为：work pool base template → deployment → flow run 的 job variables 覆盖链路，详见 validation.py 顶部注释。
• run_deployment 通过 mark_deployments_ready 与 Worker 协作推进调度。

@router.post("/{id:uuid}/create_flow_run")
async def create_flow_run_from_deployment(...):
    await validate_job_variables_for_deployment_flow_run(...)
    return await models.deployments.create_flow_run(...)

资料来源：src/prefect/server/api/deployments.py:1-90、src/prefect/server/api/validation.py:1-30

核心域：Block、Artifact、Run History

run_history 是仪表盘的关键数据源：它对 SQLite 做了最小 1 秒间隔的保护，并通过 PrefectDBInterface 注入 session，对 flows / flow_runs / task_runs / deployments / work_pools / work_queues 多个过滤器组合查询。

资料来源：src/prefect/server/api/block_schemas.py:1-90、src/prefect/server/api/block_documents.py:1-60、src/prefect/server/api/artifacts.py:1-50、src/prefect/server/api/run_history.py:1-80

服务端内部客户端与 Runtime

src/prefect/server/api/clients.py 提供 BaseClient 与 PrefectHttpxAsyncClient，在服务端进程内通过 create_app() 与可选 Authorization 头回环调用自身 API，用于 Workers / Schedulers 等需要「服务端身份」执行操作的场景。

src/prefect/runtime/__init__.py 则在用户 flow 内部提供 prefect.runtime.deployment、prefect.runtime.flow_run、prefect.runtime.task_run 三个命名空间，读取当前运行所属的 deployment、参数、状态、task run id 等动态属性，是与 Server API 配合的常用桥接点。

资料来源：src/prefect/server/api/clients.py:1-70、src/prefect/runtime/__init__.py:1-19

已知问题与版本演进

社区近期关注以下与 Server 相关的回归与改进：

• FastAPI 0.137 兼容性：fix(server): FastAPI 0.137 compatibility — skip route deletion（3.7.5.dev4）。
• 数据库性能：fix(db): add index on event_resources(occurred) for vacuum performance（3.7.5.dev3），加速事件 vacuum 任务。
• 取消状态机：Add cancelling timeout cleanup producer（3.7.5），保证 CANCELLING 状态最终收敛。
• 测试 harness：AttributeError: 'PrefectRouter' object has no attribute 'routes' 已在 PrefectRouter 兼容性修复中处理。
• 临时 Redis 订阅泄漏：ephemeral_subscription() 在异常退出后会留下 ephemeral-* 消费组，阻塞 events stream 的 XTRIM，影响 prefect_redis.messaging 部署。

资料来源：issue #22136、issue #22259、issue #22307、release 3.7.5

See Also

• Settings 模型与配置
• Flow / Task 运行引擎
• Deployment 与 Work Pool
• 事件与自动化

概述与定位

src/prefect/server/api/ 子包是 Prefect 服务端 API 的核心实现，基于 FastAPI 构建，负责把工作流编排所需的所有领域对象以 REST 端点的形式暴露给客户端（CLI、Prefect UI、Python PrefectClient）。它既是 prefect server start 启动的本地/自托管后端，也是 Prefect Cloud 兼容 API 的实现基座。

__init__.py 通过 __all__ 显式导出了全部路由模块并通过 __getattr__ 动态导入，避免在导入包时立即加载所有路由带来的开销。这种“惰性加载”策略在大型模块数量较多的代码库中能显著缩短启动时间。资料来源：src/prefect/server/api/__init__.py:11-58。

每个路由模块都使用 PrefectRouter（prefect.server.utilities.server.PrefectRouter 的封装）注册，并按前缀（prefix）划分命名空间（例如 /deployments、/artifacts、/block_schemas），便于在 OpenAPI 文档中分组展示。

架构与路由组织

API 应用通过 create_app() 工厂函数在 src/prefect/server/api/server.py 中组装。在该文件中可以看到主要的路由注册顺序：

api_app.include_router(api.flows.router)
api_app.include_router(api.flow_runs.router)
...
api_app.include_router(api.work_queues.router)
api_app.include_router(api.artifacts.router)
api_app.include_router(api.block_schemas.router)
api_app.include_router(api.block_capabilities.router)
api_app.include_router(api.collections.router)
api_app.include_router(api.variables.router)
api_app.include_router(api.csrf_token.router)
api_app.include_router(api.events.router)
api_app.include_router(api.automations.router)
api_app.include_router(api.templates.router)
...

资料来源：src/prefect/server/api/server.py:36-67。

下表对主要路由模块进行了汇总，方便读者快速定位职责：

资料来源：src/prefect/server/api/__init__.py:11-58。

请求生命周期

sequenceDiagram
    participant Client as PrefectClient / UI
    participant FastAPI as API App (server.py)
    participant Router as 子路由 (e.g. deployments)
    participant Model as server.models
    participant DB as PrefectDBInterface

    Client->>FastAPI: HTTP 请求 (含 X-PREFECT-API-VERSION)
    FastAPI->>Router: 路径匹配后调用 handler
    Router->>Router: 依赖注入 (db, auth, pagination)
    Router->>Model: 调用 ORM/业务逻辑
    Model->>DB: 经 session_context 打开事务
    DB-->>Model: 返回 ORM 对象
    Model-->>Router: 转成 Pydantic schema
    Router-->>Client: JSON 响应

关键依赖由 src/prefect/server/api/dependencies.py 提供，例如 provide_request_api_version 解析请求头，EnforceMinimumAPIVersion 在不兼容版本时拒绝请求，PREFECT_API_DEFAULT_LIMIT 用于分页默认值。资料来源：src/prefect/server/api/dependencies.py:14-50。

关键子模块详解

部署与参数校验

deployments.py 通过 validate_job_variables_for_deployment 和 validate_job_variables_for_deployment_flow_run 把工作池模板、部署与运行级 job variables 合并后做 JSON Schema 校验。合并顺序固定为：工作池 → 部署 → FlowRun，覆盖关系严格自上而下。资料来源：src/prefect/server/api/deployments.py:1-30。

validation.py 进一步说明：

• 工作池/部署层校验忽略必填字段，因为完整覆盖还未就绪。
• 默认值若不符合 schema 会静默忽略，避免历史数据回写失败。
• 仅 FlowRun 这一终端节点严格校验必填项。
• Pydantic v1 生成的 schema 对部分字段不合法，需要运行时容错。

资料来源：src/prefect/server/api/validation.py:1-30。

块（Block）存储

block_schemas.py 在创建块时计算字段的 checksum 并查找已存在的相同版本，避免重复写入。block_documents.py 则把用户填写的字段值落到 block_document 表，并强制名称在 block_type 内唯一。资料来源：src/prefect/server/api/block_schemas.py:25-60、src/prefect/server/api/block_documents.py:25-60。

工件（Artifact）

artifacts.py 暴露了 POST /artifacts 等端点，把客户端传来的 ArtifactCreate 转成核心 schema 写入数据库，并通过响应时间判断是否返回 201 Created。资料来源：src/prefect/server/api/artifacts.py:20-45。

运行历史与统计

run_history.py 提供按区间聚合的 HistoryResponse，使用 db_injector 注入数据库会话；要求 history_interval >= 1s，因为 SQLite 在小于 1s 的间隔上无法正确递增。资料来源：src/prefect/server/api/run_history.py:18-50。

服务端客户端（自调用）

clients.py 定义了若干 BaseClient，通过 create_app() 拿到 in-process 的 FastAPI 应用，然后直接调用 ASGI 路由，避免对自身发起 HTTP 调用。该机制在服务器内部需要访问自身 API 时非常常见（例如调度器、worker 查询）。资料来源：src/prefect/server/api/clients.py:28-70。

已知问题与社区反馈

• 测试装置路由缺失：社区报告 #22307 指出，当使用 prefect test harness 时，PrefectRouter 缺少 routes 属性导致 AttributeError。该问题在 3.7.5.dev4 中通过 FastAPI 0.137 兼容性补丁（fix(server): FastAPI 0.137 compatibility — skip route del...）得到修复。修复策略是跳过某些路由删除操作，而不是给 PrefectRouter 暴露 routes，因此升级 FastAPI 是该问题的正确处置路径。资料来源：GitHub Issue #22307、Release 3.7.5.dev4。
• 运行历史 event_resources 索引缺失：3.7.5.dev3 增加了 event_resources(occurred) 索引以加速 vacuum；在自托管 SQLite 用户升级前，长时间运行的服务可能出现 vacuum 阶段缓慢。资料来源：Release 3.7.5.dev3。
• subflow 并发与 dynamic_key 竞争：社区问题 #22259 描述了并发子流在父流重试时可能错拿持久化结果。该问题并非 API 路由本身的 bug，而是上层编排层使用 task.submit() 包装子流的常见模式所致；建议关注后续官方对 Flow.submit 接口的进展（社区问题 #6689）。资料来源：GitHub Issue #22259、GitHub Issue #6689。
• Redis ephemeral consumer group 泄漏：当 PREFECT_MESSAGING_BROKER=prefect_redis.messaging 时，异常关停会留下 ephemeral-* 消费者组并阻止事件流被裁剪（社区问题 #22136），该问题与 events 路由紧密相关。资料来源：GitHub Issue #22136。
• 并发限制孤儿槽位：#17415 讨论了 leaky bucket 算法下并发限制可能产生孤儿槽位，需要通过 reconciliation 服务定期回收。资料来源：GitHub Issue #17415。

使用与扩展指引

新增一个领域对象的典型步骤：

1. 在 src/prefect/server/models/ 下实现 ORM 业务逻辑（读/写/筛选）。
2. 在 src/prefect/server/schemas/ 下定义 core（领域）与 actions（输入）Pydantic 模型。
3. 在 src/prefect/server/api/<domain>.py 中创建 PrefectRouter(prefix=..., tags=[...]) 并编写处理器，使用 Depends(provide_database_interface) 注入数据库。
4. 把新模块加到 src/prefect/server/api/__init__.py 的 __all__ 与 TYPE_CHECKING 块。
5. 在 src/prefect/server/api/server.py 的 create_app() 中调用 api_app.include_router(...)。
6. 若需要校验参数，参考 validation.py 中的合并与容错策略。
7. 若需对外提供 UI 模式或专用视图，按 ui/ 子包风格新增 ui.<domain> 路由。

See Also

• Prefect Server 入口与 create_app
• FastAPI 依赖注入与版本协商
• 部署参数校验顺序与默认值容错
• 运行历史聚合
• 服务端自调用客户端

Pitfall Log / 踩坑日志

项目：PrefectHQ/prefect

摘要：发现 22 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: 3.7.4 - From cradle to grave。

1. 安装坑 · 失败模式：installation: 3.7.4 - From cradle to grave

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: 3.7.4 - From cradle to grave
• 对用户的影响：Upgrade or migration may change expected behavior: 3.7.4 - From cradle to grave
• 证据：failure_mode_cluster:github_release | https://github.com/PrefectHQ/prefect/releases/tag/3.7.4 | 3.7.4 - From cradle to grave

2. 安装坑 · 失败模式：installation: 3.7.4.dev3: Nightly Development Release

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: 3.7.4.dev3: Nightly Development Release
• 对用户的影响：Upgrade or migration may change expected behavior: 3.7.4.dev3: Nightly Development Release
• 证据：failure_mode_cluster:github_release | https://github.com/PrefectHQ/prefect/releases/tag/3.7.4.dev3 | 3.7.4.dev3: Nightly Development Release

3. 安装坑 · 来源证据：Concurrent subflow calls adopt the WRONG subflow's persisted result on parent flow retry (positional dynamic_key race)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Concurrent subflow calls adopt the WRONG subflow's persisted result on parent flow retry (positional dynamic_key race)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/PrefectHQ/prefect/issues/22259 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 安装坑 · 来源证据：Leaked `ephemeral-*` Redis consumer groups pin the `events` stream and prevent trimming after ungraceful shutdowns

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Leaked ephemeral-* Redis consumer groups pin the events stream and prevent trimming after ungraceful shutdowns
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/PrefectHQ/prefect/issues/22136 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 配置坑 · 失败模式：configuration: 3.7.4.dev4: Nightly Development Release

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: 3.7.4.dev4: Nightly Development Release
• 对用户的影响：Upgrade or migration may change expected behavior: 3.7.4.dev4: Nightly Development Release
• 证据：failure_mode_cluster:github_release | https://github.com/PrefectHQ/prefect/releases/tag/3.7.4.dev4 | 3.7.4.dev4: Nightly Development Release

6. 配置坑 · 失败模式：configuration: 3.7.5 - No run left CANCELLING

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: 3.7.5 - No run left CANCELLING
• 对用户的影响：Upgrade or migration may change expected behavior: 3.7.5 - No run left CANCELLING
• 证据：failure_mode_cluster:github_release | https://github.com/PrefectHQ/prefect/releases/tag/3.7.5 | 3.7.5 - No run left CANCELLING

7. 配置坑 · 失败模式：configuration: 3.7.5.dev1: Nightly Development Release

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: 3.7.5.dev1: Nightly Development Release
• 对用户的影响：Upgrade or migration may change expected behavior: 3.7.5.dev1: Nightly Development Release
• 证据：failure_mode_cluster:github_release | https://github.com/PrefectHQ/prefect/releases/tag/3.7.5.dev1 | 3.7.5.dev1: Nightly Development Release

8. 配置坑 · 失败模式：configuration: 3.7.5.dev2: Nightly Development Release

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: 3.7.5.dev2: Nightly Development Release
• 对用户的影响：Upgrade or migration may change expected behavior: 3.7.5.dev2: Nightly Development Release
• 证据：failure_mode_cluster:github_release | https://github.com/PrefectHQ/prefect/releases/tag/3.7.5.dev2 | 3.7.5.dev2: Nightly Development Release

9. 配置坑 · 失败模式：configuration: 3.7.5.dev3: Nightly Development Release

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: 3.7.5.dev3: Nightly Development Release
• 对用户的影响：Upgrade or migration may change expected behavior: 3.7.5.dev3: Nightly Development Release
• 证据：failure_mode_cluster:github_release | https://github.com/PrefectHQ/prefect/releases/tag/3.7.5.dev3 | 3.7.5.dev3: Nightly Development Release

10. 配置坑 · 失败模式：configuration: 3.7.5.dev4: Nightly Development Release

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: 3.7.5.dev4: Nightly Development Release
• 对用户的影响：Upgrade or migration may change expected behavior: 3.7.5.dev4: Nightly Development Release
• 证据：failure_mode_cluster:github_release | https://github.com/PrefectHQ/prefect/releases/tag/3.7.5.dev4 | 3.7.5.dev4: Nightly Development Release

11. 配置坑 · 失败模式：configuration: 3.7.5.dev5: Nightly Development Release

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: 3.7.5.dev5: Nightly Development Release
• 对用户的影响：Upgrade or migration may change expected behavior: 3.7.5.dev5: Nightly Development Release
• 证据：failure_mode_cluster:github_release | https://github.com/PrefectHQ/prefect/releases/tag/3.7.5.dev5 | 3.7.5.dev5: Nightly Development Release

12. 配置坑 · 失败模式：configuration: 3.7.5.dev6: Nightly Development Release

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: 3.7.5.dev6: Nightly Development Release
• 对用户的影响：Upgrade or migration may change expected behavior: 3.7.5.dev6: Nightly Development Release
• 证据：failure_mode_cluster:github_release | https://github.com/PrefectHQ/prefect/releases/tag/3.7.5.dev6 | 3.7.5.dev6: Nightly Development Release

13. 配置坑 · 失败模式：configuration: Leaked `ephemeral-*` Redis consumer groups pin the `events` stream and prevent trimming after...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Leaked ephemeral-* Redis consumer groups pin the events stream and prevent trimming after ungraceful shutdowns
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Leaked ephemeral-* Redis consumer groups pin the events stream and prevent trimming after ungraceful shutdowns
• 证据：failure_mode_cluster:github_issue | https://github.com/PrefectHQ/prefect/issues/22136 | Leaked ephemeral-* Redis consumer groups pin the events stream and prevent trimming after ungraceful shutdowns

14. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/PrefectHQ/prefect | README/documentation is current enough for a first validation pass.

15. 运行坑 · 失败模式：runtime: Broken test harness due to missing routes attribute in PrefectRouter

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: Broken test harness due to missing routes attribute in PrefectRouter
• 对用户的影响：Developers may hit a documented source-backed failure mode: Broken test harness due to missing routes attribute in PrefectRouter
• 证据：failure_mode_cluster:github_issue | https://github.com/PrefectHQ/prefect/issues/22307 | Broken test harness due to missing routes attribute in PrefectRouter

16. 维护坑 · 来源证据：Broken test harness due to missing routes attribute in PrefectRouter

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Broken test harness due to missing routes attribute in PrefectRouter
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/PrefectHQ/prefect/issues/22307 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

17. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/PrefectHQ/prefect | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/PrefectHQ/prefect | no_demo; severity=medium

19. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/PrefectHQ/prefect | no_demo; severity=medium

20. 能力坑 · 失败模式：capability: Concurrent subflow calls adopt the WRONG subflow's persisted result on parent flow retry (pos...

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Concurrent subflow calls adopt the WRONG subflow's persisted result on parent flow retry (positional dynamic_key race)
• 对用户的影响：Developers may hit a documented source-backed failure mode: Concurrent subflow calls adopt the WRONG subflow's persisted result on parent flow retry (positional dynamic_key race)
• 证据：failure_mode_cluster:github_issue | https://github.com/PrefectHQ/prefect/issues/22259 | Concurrent subflow calls adopt the WRONG subflow's persisted result on parent flow retry (positional dynamic_key race)

21. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/PrefectHQ/prefect | issue_or_pr_quality=unknown

22. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/PrefectHQ/prefect | release_recency=unknown