dbt × MaxCompute 集成用于应对数据团队同时使用 dbt 做模型开发、MaxCompute 做湖仓计算的场景。通过在客户端内关联本地 dbt 工程，可直接浏览模型结构、编译并执行 SQL、可视化数据血缘、将语义资产沉淀到 AI Query，免去在 dbt CLI、odpscmd、dbt docs 之间反复切换。
功能概述
客户端读取本地 dbt 工程的 manifest.json，在不调用 dbt CLI 的前提下完成模型浏览、SQL 编译预览、血缘分析与语义包导入。所有操作为只读模式，不修改 dbt 工程文件。
适用场景
联合管理 dbt 工程与 MaxCompute 加工链路：数据团队维护 models、sources、metrics、semantic models，希望在同一界面内完成模型查看与 SQL 执行，不必在编辑器、终端、dbt docs 之间切换。
模型变更的影响分析：改动某个模型前，通过血缘图看清上下游依赖，评估变更影响范围；列级血缘进一步下钻到字段级别。
复用 dbt 语义资产实现 AI 问数：dbt 工程中已定义的 semantic models 与 metrics，可转换为 OSI 语义包（Open Semantic Interface，客户端的语义资产格式），让 AI Query 基于统一口径的实体、指标、维度进行问答。
功能索引
功能类别 | 功能项 |
工程管理 | 关联项目、多项目切换、刷新 manifest、断开关联、打开工程文件夹 |
模型浏览 | 文件树、模型健康度、只读编辑器、 |
编译与执行 | SQL 编译预览（四级 fallback）、编译结果执行到统一结果栏 |
血缘分析 | 模型级血缘图（全屏 + 迷你）、列级血缘、节点详情面板 |
AI 语义沉淀 | dbt semantic models/metrics 导入为 OSI 语义包、自动编译 |
前提条件
已创建并成功连接一个 MaxCompute 数据源。执行编译后的 SQL 需要活动连接，血缘浏览不需要。
本地已有 dbt 工程，且工程根目录下存在
dbt_project.yml和profiles.yml。已生成
manifest.json。如尚未生成，请在终端运行dbt docs generate或dbt compile。客户端不会调用 dbt CLI，全部功能依赖 manifest 数据。
快速入门
以下步骤关联一个 dbt 工程，编译并执行一个模型。
在侧边栏dbt 项目面板，单击 +（关联项目）。
在项目路径输入框填写 dbt 工程根目录路径；桌面端可单击浏览通过系统目录选择器选取。
单击关联。按钮会显示「检测中…」，检测通过后面板加载工程概览与文件树。
在文件树中单击一个
.sql模型文件，客户端在标签页打开只读编辑器。切换到底部面板的SQL 编译预览标签，单击编译（快捷键 Shift+Cmd+Enter）。
编译成功后单击执行编译结果（快捷键 Cmd+Enter），结果进入底部统一结果栏。
关联与管理 dbt 工程
关联项目
在dbt 项目面板，单击 + 打开关联对话框。
填写项目路径，指向 dbt 工程根目录（包含
dbt_project.yml的目录）。单击关联。客户端检测
dbt_project.yml和profiles.yml是否存在，并解析manifest.json。关联成功后面板上方展示工程概览：dbt 版本、模型数、数据源数、指标数、工程路径与 manifest 最近更新时间。
如需关联多个工程，重复上述步骤；面板顶部会出现下拉框用于切换当前工程。
刷新与过期提示
若 manifest 文件的修改时间早于工程文件的修改时间，面板会出现黄色提示条「manifest 可能已过期，建议刷新」。单击提示条或顶部的刷新图标即可重新加载 manifest，让文件树、血缘图和健康度反映最新状态。
刷新操作重新读取磁盘上的 manifest.json，不会执行 dbt compile。如果模型有改动，请先在终端运行 dbt compile 或 dbt docs generate 更新 manifest，再回到客户端刷新。
断开关联
单击面板顶部的断开图标，确认对话框中单击确认断开即可解除关联。断开后需重新关联才能使用 dbt 功能。
打开工程文件夹
工程概览区的路径文本可单击，桌面端直接打开该文件夹。
浏览模型与健康度
文件树
关联成功后，面板下方展示 models/ 目录结构。目录可展开与折叠，显示文件数量；.sql 文件以蓝色代码图标显示，.yml 配置文件以黄色图标显示。
打开模型、编译与执行
只读编辑器
在文件树中单击 .sql 模型文件，标签页打开只读 Monaco 编辑器，支持 Jinja 语法高亮。编辑器中 ref('模型名') 与 source('源名','表名') 可 Cmd+Click 跳转到对应文件，悬浮可查看节点名称、类型、物化方式、描述与列信息。
.yml 配置文件同样可打开查看，但不展示编译和血缘面板。
SQL 编译预览
底部面板的SQL 编译预览标签提供编译能力。单击编译后，客户端按以下优先级获取编译结果：
编译成功后显示可执行的 SQL，右侧标注来源（如 via manifest）。编译失败时上方红色区域列出错误信息。
执行编译结果
编译成功后出现两个按钮：
执行编译结果（绿色，快捷键 Cmd+Enter）：把 SQL 发送到当前 MaxCompute 连接执行，结果进入底部统一结果栏，可查看 Logview 进度、切换图表可视化并导出。
复制编译 SQL：复制到剪贴板。
执行前需确保已连接 MaxCompute 实例，否则会提示「请先连接 MaxCompute 实例」。
查看血缘
模型级血缘（迷你视图）
底部面板的血缘标签展示以当前模型为中心的迷你血缘图（默认上下游各 2 跳）。当前模型为高亮节点，上游蓝色、下游红色。左上角提供图例，右上角提供缩放与适配按钮。若存在下游，会显示「影响 N 个下游模型」。单击相邻节点可跳转到对应文件。
全屏血缘图
单击底部面板的打开血缘图（或编辑器工具栏的在血缘图中定位）进入全屏血缘图标签页。顶部提供搜索（Cmd+F）、布局方向切换（横向 LR / 纵向 TB）、缩放与适配；可按 source / model / exposure / metric 四类节点过滤。单击节点高亮上下游路径，双击打开对应文件，右键可复制表名。选中节点后底部展示描述、依赖、列信息等详情。
列级血缘
底部面板的列级血缘标签展示目标模型每个字段的来源字段映射。左侧按来源模型分组列出来源列，右侧为目标列。目标列按加工类型着色（Passthrough / Rename / Transform / Raw），左上角提供图例说明。
导入语义包
将 dbt 工程中的语义资产转换为 OSI 语义包，供 AI Query 使用。
在 dbt 面板单击导入语义包。
在目标语义域输入框填写域名；留空则根据工程名自动生成。
单击导入。客户端读取工程中的
semantic_manifest.json，将 dbt 的 semantic models、metrics、saved queries 转换为 OSI 语义包（实体、指标、维度术语、关联、验证查询）。导入完成后自动编译该语义域进入运行时索引，AI Query 即可使用。
对话框显示导入结果与有损转换提示（按严重程度分为 error / warning / info），例如：
目标域已存在将被覆盖。
derived/ratio指标的表达式引用其他指标名，可能需手动调整。cumulative指标的 window / grain 语义未完整保留。dbt
saved_query转为占位 SQL，需手动补全实际查询。
若目标语义域已存在，导入会覆盖原有内容。请确认域名无误后再执行。
导入后建议对照提示在语义包中手动完善有损转换的条目。