SQLMesh 概述与核心架构

一、项目定位与核心能力

SQLMesh 是由 Linux 基金会托管的下一代数据转换框架，旨在帮助数据团队高效、可控地交付数据转换逻辑。根据 README.md 的描述，SQLMesh "more than just a dbt alternative"，强调它不仅能完成 dbt 风格的 SQL 转换，还在变更控制、虚拟数据环境与跨方言转译方面提供更完整的工程化能力。 资料来源：README.md:13-15

项目通过四项核心能力形成差异化：

1. 虚拟数据环境（Virtual Data Environments, VDE）：为每一次变更提供隔离的逻辑视图，避免在开发阶段直接污染生产表；
2. 列级血缘与变更预览：在执行前即可看到 SQL 改动的下游影响；
3. 多方言转译：在 10+ 种 SQL 方言之间互转，使模型定义与目标引擎解耦；
4. Plan 模式 + CI 集成：支持 table diff、审计自动化与多环境部署。 资料来源：README.md:17-50

社区反馈显示，数据血缘（Issue #3565）、适配器扩展（Athena #1315、ClickHouse #1300、StarRocks #5610、S3Tables #4724）以及计划/部署的 Web 化是用户最关注的方向，这也映射出 SQLMesh 架构中 "Context + Web Server + Adapter" 三层耦合的设计取向。

二、核心架构组成

SQLMesh 核心以 Context 为入口对象，向下衔接模型定义、状态同步、计划评估与执行引擎，向上为 CLI、VSCode 扩展与 Web UI 提供统一能力。下图展示了从用户操作到底层数据仓库的关键数据流。

flowchart TD
    A[CLI / VSCode / Web UI] --> B[Context 上下文对象]
    B --> C[Model 定义与解析]
    B --> D[Plan 计划评估]
    B --> E[State Sync 状态同步]
    D --> F[Virtual Data Environment]
    D --> G[Snapshot / Environment]
    B --> H[Adapter 执行引擎]
    H --> I[(目标数据仓库)]
    E --> J[(State Backend<br/>如元数据库)]

围绕该数据流，仓库内 web/server 子项目承担了完整的 HTTP API 与前端构建职责，其模块化拆分如下表所示。

三、关键服务层与端点

Web 服务层使用 FastAPI 组织端点，并通过 Settings 注入项目路径与 ui_mode 来启用不同模块组合。MODE_TO_MODULES 映射定义了三种 UI 模式各自加载的能力集合。 资料来源：web/server/settings.py:27-39

主要端点行为概述：

• GET /api/meta：返回 SQLMesh 版本、当前是否正在执行计划任务以及节点配色，供 UI 状态栏与主题渲染使用。 资料来源：web/server/api/endpoints/meta.py:17-32
• GET /api/models 与 GET /api/models/{name}：列举或获取模型定义；前者调用 context.refresh() 以保证最新状态，后者返回包含渲染后查询的完整模型对象。 资料来源：web/server/api/endpoints/models.py:24-47
• GET /api/lineage：使用 sqlmesh.core.lineage.lineage 与 column_dependencies 构造列级血缘邻接表，输出包含 CTE 在内的完整依赖图。 资料来源：web/server/api/endpoints/lineage.py:1-50
• POST /api/plan 与 POST /api/commands/apply：通过 asyncio.create_task 将耗时的 PlanBuilder 评估与计划应用放入后台任务，并返回阶段追踪对象以支持前端 SSE 推送。 资料来源：web/server/api/endpoints/plan.py:18-36、 资料来源：web/server/api/endpoints/commands.py:24-44
• GET /api/environments 与 DELETE /api/environments/{name}：列出所有虚拟环境并在删除时清理过期快照。 资料来源：web/server/api/endpoints/environments.py:17-30
• GET /api/table_diff：执行生产与开发之间的表结构与行级数据对比，输出 SchemaDiff、RowDiff 与采样数据。 资料来源：web/server/api/endpoints/table_diff.py:23-65
• GET/POST /api/files：管理项目内 SQL 与 Python 文件的读取、写入与重命名。 资料来源：web/server/api/endpoints/files.py:23-49

四、实时事件与前端集成

为让 Web UI 实时反映计划评估与执行进度，ApiConsole 继承自 TerminalConsole，把 CLI 中的计划事件、模型测试结果与查询统计封装为可序列化的 StageTracker 对象，并写入 asyncio.Queue 供 SSE 端点消费。 资料来源：web/server/console.py:14-55

目录变化则由 watchfiles.awatch 监听 models/、audits/、macros/、metrics/、seeds/ 五个标准目录，并通过 ignore_entity_patterns 排除缓存与本地 DuckDB 文件，避免不必要的上下文重建。 资料来源：web/server/watcher.py:14-30

前端通过 pnpm 工作区与 Vite 构建：build 脚本会先执行 tsc 类型检查，再调用 vite build 与 Tailwind 编译，最终输出到 dist/，与后端 FastAPI 一同打包发布。 资料来源：web/common/package.json:1-30

五、常见使用模式

1. 本地快速试用：通过 sqlmesh init 选择 DuckDB 即可零配置启动；推荐安装 [lsp] 扩展以获得 VSCode 智能提示。 资料来源：README.md:67-83
2. 多环境协作：开发者提交 Plan 后在 VDE 中验证，再以 apply 提升到生产，避免直接修改线上表。
3. 表对比与审计：在 CI 中调用 table_diff 端点，对生产与开发的关键模型执行 schema/row diff 校验。
4. 适配新引擎：对于 Athena、StarRocks、S3Tables 等社区请求中的引擎，可通过实现新的 Adapter 并在 Context 中注册，从而复用 Plan、VDE 与血缘能力。

See Also

• 虚拟数据环境（Virtual Data Environments）详解
• Plan 模式与变更评估
• 数据血缘与列级依赖图
• 适配器（Adapter）开发指南
• Web UI 与 FastAPI 集成

引擎适配器与多引擎数据库支持

概述

SQLMesh 的引擎适配器（Engine Adapter）层是连接框架核心与底层数据仓库的关键抽象。它负责把 SQLMesh 中的模型定义、DDL/DML 语句、事务、快照评估等抽象操作，转译为特定引擎的 SQL 方言与执行语义。每个具体适配器都继承自一个统一的基类（BaseEngineAdapter），从而让 CLI、Web UI、Python API 等上层在不同引擎之间保持一致的体验。

资料来源：sqlmesh/core/engine_adapter/base.py

基类定义的标准接口覆盖了所有适配器必须实现的核心行为，例如 create_table、insert_overwrite、merge、fetchdf 等。具体适配器（duckdb.py、snowflake.py、bigquery.py、postgres.py、redshift.py 等）在此基础上覆写引擎特有行为，例如分布式键、列式存储、合并语法差异等。

适配器架构

引擎适配器在 SQLMesh 的执行路径中位于 Context / Plan → Adapter → Engine 的中间层，向上承接统一的模型与计划抽象，向下落到具体方言。

graph TB
    Context[Context / Plan] --> Adapter[BaseEngineAdapter]
    Adapter --> DuckDB[DuckDB]
    Adapter --> Snowflake[Snowflake]
    Adapter --> BigQuery[BigQuery]
    Adapter --> Postgres[Postgres]
    Adapter --> Redshift[Redshift]
    Adapter --> ClickHouse[ClickHouse]
    Adapter --> Databricks[Databricks]
    Adapter --> Athena[Athena]
    Adapter --> MySQL[MySQL]
    Adapter --> Spark[Spark]
    Adapter --> Trino[Trino]
    DuckDB --> Dialect[SQLGlot 方言层]
    Snowflake --> Dialect
    BigQuery --> Dialect
    Postgres --> Dialect
    Redshift --> Dialect
    ClickHouse --> Dialect

适配器差异主要体现在以下方面：

资料来源：sqlmesh/core/engine_adapter/base.py、sqlmesh/core/engine_adapter/snowflake.py、sqlmesh/core/engine_adapter/redshift.py

社区关注的引擎支持

SQLMesh 的多引擎生态由社区贡献持续扩展。以下高频请求反映了真实使用场景：

• AWS Athena：Issue #1315 提议增加 Athena 适配器，便于直接查询 S3 上的开放表格式（Iceberg、Parquet）。
• ClickHouse：Issue #1300 请求原生 ClickHouse 支持；最新版本 v0.235.4 中已通过 PR #5751 增加了连接配置中的 secure 字段，适配器实现位于 sqlmesh/core/engine_adapter/clickhouse.py。
• StarRocks：Issue #5610 指出 StarRocks 虽然使用 MySQL 协议，但 mysql 适配器无法满足其特有的 DISTRIBUTED BY / PARTITION BY DDL，需要专属适配器。
• AWS S3 Tables：Issue #4724 讨论对 S3 Tables（Lakehouse 表桶）的支持，使 SQLMesh 无需复制数据即可读取托管 Iceberg/Parquet。

这些请求反映出多引擎支持的核心挑战：方言差异超出 SQL 标准以及 DDL 扩展（分区键、排序键、分布式键）需要专属实现。仅靠 MySQL/Postgres 通用方言无法覆盖。

Gateway 与适配器选择

在 Web UI 与 CLI 中，适配器通过项目配置中的 Gateway 机制选择。web/server/settings.py 中的 Settings 类暴露 gateway 字段，允许同一 SQLMesh 项目在本地与生产环境之间切换引擎：

gateway: t.Optional[str] = Field(default_factory=lambda: os.getenv("GATEWAY"))

资料来源：web/server/settings.py

这意味着开发者可以使用 DuckDB（duckdb.py）进行本地快速迭代，再通过 Gateway 将生产部署路由到 Snowflake、BigQuery 或 Databricks，从而在不修改模型代码的前提下完成引擎迁移。

常见失败模式

使用多引擎适配器时常见的问题包括：

• 方言不兼容：在引擎 A 上验证的 SQL 在引擎 B 上可能因函数名或类型差异而失败，需借助 SQLGlot 方言层做转译。
• DDL 扩展缺失：使用 mysql 适配器构建 StarRocks 模型时，DISTRIBUTED BY 语法无法生成。
• 连接配置不全：例如未设置 ClickHouse 的 secure 字段，可能导致本地开发能连接、生产 TLS 环境下失败。

资料来源：sqlmesh/core/engine_adapter/clickhouse.py、web/server/settings.py

See Also

• 虚拟数据环境
• Gateway 与连接配置
• 计划与回填

Plans、Virtual Data Environments、Snapshots 与状态管理

概述

SQLMesh 是一个面向数据转换的下一代框架，其核心差异化能力之一在于 Plan / Apply 工作流 以及 Virtual Data Environments（虚拟数据环境） 机制。README.md 将其定位为“more than just a dbt alternative”，强调其借鉴了 Terraform 的计划-应用理念，使数据团队在变更模型前能够预览影响范围，并在不产生数仓额外成本的前提下创建隔离的虚拟环境。

整个状态管理体系由三类对象协同组成：

• Plan（计划）：描述对模型的一组变更及其分类，由 PlanBuilder 构造。
• Environment（环境）：保存计划应用后的快照集合，是虚拟数据环境的逻辑载体。
• Snapshot（快照）：模型某一版本在某一时间点的不可变表示，配合 SnapshotChangeCategory 实现差异识别。

下文依次介绍这三者在代码层面的具体实现与交互。

Plans：变更的声明与执行

在 SQLMesh 中，计划是用户变更模型时的“声明式描述”。Web 服务层通过两个端点暴露该能力：

• web/server/api/endpoints/plan.py 的 initiate_plan 端点接收 environment、plan_dates、plan_options 与 categories 四个参数，调用 get_plan_builder 构造 PlanBuilder 并异步执行。
• web/server/api/endpoints/commands.py 的 initiate_apply 端点则基于已生成的 PlanBuilder 进一步执行 run_plan_apply，完成实际的应用动作。

SnapshotChangeCategory 类型字典（Dict[str, SnapshotChangeCategory]）作为 categories 参数传入，用于将每个被改动的模型归类到 BREAKING、NON_BREAKING、FORWARD_ONLY 等变更类别，这一分类直接决定后续计划应用时是否需要全量回填。

web/server/console.py 中定义了三种与计划相关的阶段跟踪器：

阶段间通过事件机制流转：start_plan_evaluation、stop_plan_evaluation 等方法在每次状态切换时记录到 current_task_status，便于前端通过 SSE 流式订阅。

Virtual Data Environments：隔离的逻辑环境

虚拟数据环境是 SQLMesh 的核心创新之一，README.md 中明确指出其支持“Create isolated development environments without data warehouse costs”。在 API 层面，环境名称作为请求体的一部分与计划一起提交：

async def initiate_plan(
    environment: t.Optional[str] = Body(None),
    ...
)

web/server/models.py 中 ApplyType 枚举区分了 virtual 与 backfill 两种应用方式，前者用于创建或更新虚拟环境，后者则针对物理表执行历史回填。

web/server/console.py 通过 EnvironmentNamingInfo 标识环境命名信息，并在计划评估开始时记录到 PlanApplyStageTracker，确保前端能够展示当前正在被操作的目标环境。

模式与模块映射逻辑位于 web/server/settings.py 中的 MODE_TO_MODULES 字典：

MODE_TO_MODULES = {
    models.Mode.IDE: {EDITOR, FILES, DATA_CATALOG, ERRORS, PLANS},
    models.Mode.CATALOG: {DATA_CATALOG},
    models.Mode.PLAN: {PLANS, DATA_CATALOG, LINEAGE, ERRORS},
}

可见 PLAN 模式相较 IDE 模式额外暴露了 LINEAGE 模块，使用户能够在计划视图内同时查看列级血缘，这恰好回应了社区 issue #3565 中提出的数据目录与血缘整合诉求。

Snapshots 与状态管理

快照是 SQLMesh 状态管理体系的基础单元。web/server/api/endpoints/plan.py 在导入部分直接引用了 sqlmesh.core.snapshot.definition 中的 SnapshotChangeCategory 与 web/server/models.py 中定义的 PlanStage、Status（INIT、SUCCESS、FAIL）枚举，二者共同构成计划执行过程中快照变更的分类与状态标识。

web/server/console.py 中还引入了 Interval 与 Intervals 类型，用于表达快照需要处理的时间区间。QueryExecutionStats 则记录每次查询执行的统计信息，供阶段跟踪器呈现给前端。

web/server/api/endpoints/meta.py 的 get_api_meta 端点检测 request.app.state.task 是否仍处于运行中，并将 has_running_task 标志暴露给 UI，从而实现“计划正在执行中”的全局状态提示。其内部还通过 node_colors 字段返回上下文中配置的节点颜色映射，便于前端对不同变更类别的快照进行可视化区分。

行级血缘能力由 web/server/api/endpoints/lineage.py 提供：它借助 sqlmesh.core.lineage 模块的 column_dependencies 与 lineage 函数，构建列级别的有向图，并返回 LineageColumn 结构。这与 issue #3565 中提到的“visualize the origin and flow of data”诉求直接对应，是 SQLMesh 在血缘可视化方面已内置的能力。

flowchart LR
    User[用户] -->|plan 命令| PlanAPI[initiate_plan]
    PlanAPI --> PB[PlanBuilder]
    PB --> Cat[SnapshotChangeCategory 分类]
    Cat --> Plan[Plan 计划对象]
    Plan --> ApplyAPI[initiate_apply]
    ApplyAPI --> Env[Virtual Environment]
    Env --> Snap[Snapshot 集合]
    Snap --> State[current_task_status]
    State --> SSE[SSE 流]
    SSE --> UI[Web UI]

常见失败模式与社区反馈

1. 长时间阻塞的任务：计划评估异步执行于 asyncio.create_task，由 web/server/api/endpoints/plan.py:run_in_executor 包装。当 request.app.state.task 仍处于未完成状态时，新的计划请求将仅记录事件而不启动新任务，避免并发冲突。
2. 路径校验：所有 API 都通过 Depends(validate_path) 校验路径，违反规则时会触发 ApiException，例如 web/server/api/endpoints/directories.py 中目录已存在的情况。
3. 数据源适配器缺失：社区中关于 Athena（#1315）、ClickHouse（#1300）、StarRocks（#5610）、S3 Tables（#4724）的支持请求，根源在于底层适配器尚未覆盖这些方言，导致即便计划流程正确，物理执行仍可能失败。

参见

• README.md 项目总体说明
• sqlmesh/core/context.py 上下文与配置加载
• sqlmesh/core/environment.py 环境对象定义
• sqlmesh/core/snapshot/definition.py 快照定义

CLI、Web UI、VSCode 扩展、dbt 与 CI/CD 集成

概述

SQLMesh 围绕其核心转换引擎提供了一整套面向开发者的入口与集成：命令行（CLI）、基于浏览器的 Web UI、原生 VSCode 扩展以及与 dbt 项目的互操作能力。这些入口共享同一份 SQLMesh 上下文（Context），使得计划评估、数据血缘、测试与审计在不同界面中表现一致。在仓库结构上，Python 主体与 web/、vscode/ 子包通过 pnpm 工作区统一管理，相关定义见 pnpm-workspace.yaml。

项目主文档 README.md 明确将 SQLMesh 定位于"下一代数据转换框架"，强调即时的影响分析（Plan Mode）与虚拟数据环境（Virtual Data Environments），并把 CLI、VSCode 扩展、VSCode 计划模式 GIF 作为核心功能展示。

CLI 与项目初始化

CLI 是最基础的入口，安装后通过 sqlmesh init 引导用户选择适配器（默认 DuckDB），并可在同一目录中创建虚拟环境后再激活。命令模板见 README.md 的安装与快速开始小节。CLI 输出的所有事件最终通过 TerminalConsole 的派生类 ApiConsole 统一格式化——后者在 Web 端作为 Server-Sent Events（SSE）的事件源被复用，相关实现见 web/server/console.py。

CLI 同时驱动项目元数据查询接口。web/server/api/endpoints/meta.py 中的 get_api_meta 会返回 _sqlmesh_version()、当前是否有运行中的计划任务以及 context.config.ui.node_colors 配置，资料来源：web/server/api/endpoints/meta.py:13-38。

Web UI

Web UI 由 FastAPI 后端和 React 前端组成，monorepo 目录为 web/server、web/client、web/common（pnpm-workspace.yaml）。后端按照"模块化"方式暴露能力：模块枚举定义在 web/server/models.py 中，覆盖编辑器、文件浏览、数据目录、计划、测试、审计、错误、查询与血缘九大类。

资料来源：web/server/models.py:6-18。

前端使用 React 18、React Flow（血缘图）、React Split（可拖拽分栏）与 React Router 7，相关依赖见 web/client/package.json。@tobikodata/sqlmesh-common 作为 UI 组件库通过 Vite 打包，导出主入口与 ./lineage 子入口（web/common/package.json）。

后端 API 通过 FastAPI 路由分组：模型列表与单模型查询见 web/server/api/endpoints/models.py；文件与目录的读写删除见 web/server/api/endpoints/files.py 与 web/server/api/endpoints/directories.py；表差异对比封装在 web/server/api/endpoints/table_diff.py 中并返回 SchemaDiff/RowDiff 结构。血缘接口在 web/server/api/endpoints/lineage.py 内通过 column_dependencies 与 lineage 计算列级依赖图，并结合 CTE 构建邻接表。

VSCode 扩展

VSCode 扩展作为与编辑器深度集成的入口在 README.md 中被突出展示（Plan Mode GIF 即来自扩展）。工作区中包含三个相关子包：vscode/extension（扩展主体）、vscode/react（内嵌的 Webview UI）以及 vscode/bus（消息总线），参见 pnpm-workspace.yaml。web/common 同样会被扩展消费，以复用 Web UI 中的设计系统与组件（web/common/package.json）。

扩展通过 sqlmesh[lsp] 安装启用，该可选依赖引入了语言服务器与编辑期能力。开发侧的 VSCode 样例配置由 tooling/README.md 中的 make vscode_settings 目标分发，便于贡献者复用格式化与 lint 设置，资料来源：tooling/README.md。

dbt 与 CI/CD 集成

dbt 互操作通过 SQLMesh 的 dbt 适配器与项目加载器实现，使现有 dbt 项目可作为模型来源接入 SQLMesh 的计划与虚拟数据环境流程（顶层介绍见 README.md）。在 CI/CD 场景下，CLI 提供的 sqlmesh plan --apply、sqlmesh run 与 sqlmesh test 等命令被设计为无交互、可脚本化的入口，常与 GitHub Actions、Airflow 等调度器结合使用；计划执行的状态会通过 ApiConsole 推送至 Web UI 或其他前端，使 PR 阶段的差异回退到同一套事件流（web/server/console.py）。

社区中关于 StarRocks、ClickHouse、Athena、S3 Tables 等适配器扩展的诉求（参见 issue #5610、#1300、#1315、#4724）以及 #3565 提出的数据目录血缘集成，均依赖上述入口暴露的 API 端点（/api/meta、/api/models、/api/lineage 等）实现二次集成；这也是为什么 Web 后端将 LineageColumn、TableDiff 等数据模型独立抽象（web/server/api/endpoints/lineage.py、web/server/api/endpoints/table_diff.py）。

架构关系图

flowchart LR
    CLI[sqlmesh CLI] --> Core[(SQLMesh Context<br/>Plan/Run/Test)]
    WebUI[Web UI<br/>React + FastAPI]
    VSCode[VSCode 扩展<br/>+ LSP]
    DBT[dbt 项目]
    CI[CI/CD<br/>计划与回填]
    Core --> Meta[/api/meta/]
    Core --> Models[/api/models/]
    Core --> Lineage[/api/lineage/]
    Core --> Files[/api/files/]
    WebUI --> Meta
    WebUI --> Models
    WebUI --> Lineage
    WebUI --> Files
    VSCode --> Core
    DBT --> Core
    CI --> CLI

参见

• SQLMesh 核心引擎与模型定义
• 适配器与连接器（Athena、ClickHouse、StarRocks 等）
• 虚拟数据环境与计划评估

Pitfall Log / 踩坑日志

项目：SQLMesh/sqlmesh

摘要：发现 13 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Model is missing but sqlmesh plan/run is successful。

1. 安装坑 · 来源证据：Model is missing but sqlmesh plan/run is successful

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Model is missing but sqlmesh plan/run is successful
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/SQLMesh/sqlmesh/issues/5765 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安装坑 · 来源证据：Table reference with the same name as a preceding CTE are missed from dependencies

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Table reference with the same name as a preceding CTE are missed from dependencies
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/SQLMesh/sqlmesh/issues/5350 | 来源类型 github_issue 暴露的待验证使用条件。

3. 配置坑 · 来源证据：Databricks runs fail to execute on 0.235.4 with thrift error

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Databricks runs fail to execute on 0.235.4 with thrift error
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/SQLMesh/sqlmesh/issues/5841 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 能力坑 · 来源证据：Feature request: Blueprinted names for the columns with a Python data frame model.

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：Feature request: Blueprinted names for the columns with a Python data frame model.
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/SQLMesh/sqlmesh/issues/5767 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：`databricks_connect_cluster_id` is ignored — Databricks Connect always forces serverless compute

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：databricks_connect_cluster_id is ignored — Databricks Connect always forces serverless compute
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/SQLMesh/sqlmesh/issues/5842 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 配置坑 · 来源证据：Failed lookback interval runs create data holes

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Failed lookback interval runs create data holes
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/SQLMesh/sqlmesh/issues/5843 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

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

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

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

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

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

11. 安全/权限坑 · 来源证据：Upgrade to sqlglot 30.9.0 to support external dialect plugins

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Upgrade to sqlglot 30.9.0 to support external dialect plugins
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/SQLMesh/sqlmesh/issues/5840 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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