dbt 模型依赖解析器

解决什么问题

在 dbt 项目变大之后，model、source、seed 和各类 test 会逐渐形成一张不容易肉眼看清的 DAG。常见的工程问题包括：模型间接引用同一节点，最后在刷新或 CI 阶段才暴露出循环依赖；某些模型实际已经没有任何下游消费，却仍然参与编译、测试和物化；以及因为 materialized、persist_docs 或增量策略配置不当，导致刷新范围过大、重复计算或 join 成本偏高。

这个技能面向这些“项目已经能跑，但结构未必健康”的场景。它不负责替代 dbt parse 或 dbt build，而是围绕已有 manifest.json 做一轮静态结构审查，把隐藏在 DAG、Jinja 宏和 ref 调用中的依赖关系拉出来检查。

核心能力

• 循环引用识别：从 manifest.json 出发重建节点关系，找出那些经过多层 ref() 最终回到自身或形成环的模型链。
• 孤立模型检查：识别没有下游依赖且可能长期未被业务引用的模型，为后续下线、合并或归档提供候选清单。
• 物化策略审查：检查模型当前采用的物化方式与依赖图是否匹配，提示可能引入重复刷新、过度持久化或 join 放大风险的配置。
• 血缘追踪：结合 Jinja 模板解析处理宏展开、ref() 动态调用和条件分支，尽量还原真实构建前会命中的依赖边。

工作方式

1. 读取 dbt 项目编译产出的 manifest.json，提取 nodes、sources、exposures 和 parent_map / child_map 等信息。
2. 对模型 SQL 与 Jinja 模板做静态解析，识别 ref()、source()、宏调用和常见控制流结构。
3. 将解析得到的依赖边合并到 manifest 原有节点关系上，生成更贴近实际渲染结果的项目图。
4. 在项目图上运行环检测、孤儿节点统计和物化策略扫描，输出结构化的审查结论。

适用边界

• 结果质量依赖 manifest.json 的完整性。如果项目尚未完成解析，或使用了非常特殊的插件、自定义宏，边信息可能不完整。
• Jinja 静态解析不是运行时解释器。完全依赖环境变量、随机值或复杂 Python 扩展生成的 ref()，可能无法被准确预知。
• 扫描结果更适合作为代码审查和重构输入，不应直接当作唯一发布门禁；任何下线或策略调整仍需结合数据重要性、回刷窗口和下游消费方确认。