📦 Dbt Model Auditor

dbt Model Auditor 审计 dbt 项目，评估模型质量、测试覆盖率、文档完整性、性能优化及是否符合社区最佳实践。扮演资深分析工程师，审查 dbt 项目结构、模型设计与配置。

用法 在需要评估 dbt 项目健康度或审查特定模型时调用。

基础调用：

• 审计 /path/to/dbt/project 中的 dbt 项目
• 检查该项目模型质量
• 查看模型测试覆盖率

定向审计：

• 仅审计 staging 层模型
• 检查 marts 层物化策略
• 审查面向客户的模型文档完整性
• 找出命名规范违规模型

Agent 读取 dbt 项目文件（models、schemas、configs），生成全面审计报告。

工作原理

步骤 1：发现 dbt 项目结构 映射项目布局：

# 识别 dbt 项目
cat dbt_project.yml
# 列出所有模型文件
find models/ -name ".sql" | head -50
# 列出所有 schema/YAML 文件
find models/ -name ".yml" -o -name ".yaml" | head -50
# 检查包依赖
cat packages.yml 2>/dev/null || cat dependencies.yml 2>/dev/null
# 检查 profiles（目标配置）
cat profiles.yml 2>/dev/null

识别：

• 项目名称与版本
• 模型分层：staging、intermediate、marts（或自定义层名）
• Sources：定义的源表
• Seeds & Snapshots：静态数据与缓慢变化维配置
• Macros：自定义 Jinja 宏
• Packages：已安装 dbt 包（dbt_utils、codegen 等）

步骤 2：审计命名规范 检查模型文件名是否符合社区最佳实践：

层级	约定	示例
Staging	stg___	stg_stripe__payments.sql
Intermediate	int__	int_payments_pivoted.sql
Marts	或 fct_/dim_	fct_orders.sql, dim_customers.sql
Sources	YAML 定义，非 SQL	src_stripe.yml

检查结果：

• PASS：models/staging/stripe/stg_stripe__payments.sql 符合 stg___
• FAIL：models/staging/payments.sql 缺少 source 前缀，应为 stg___payments.sql
• FAIL：models/marts/core/customer_orders_joined_final_v2.sql 命名模糊，建议 fct_customer_orders.sql
• WARN：models/staging/stripe/stripe_charges.sql 重复 source 名且缺少 stg_ 前缀

附加检查：

• 文件名无空格或特殊字符
• 统一 snake_case
• 禁止 _final、_v2、_backup、_old 等后缀
• YAML 中 source 名与文件路径一致
• schema YAML 文件名与目录匹配（如 stripe/_stripe__models.yml）

步骤 3：验证 ref() 与 source() 使用 确保依赖管理正确：

# 查找硬编码表引用
grep -rn "FROM\s\+\\?[a-z_]\+\.\|JOIN\s\+\\?[a-z_]\+" models/ \
  --include=".sql" | grep -v "ref\|source\|this"

检查：

• FAIL：models/marts/core/fct_orders.sql:12 硬编码 FROM raw.stripe.payments，应改为 {{ source('stripe', 'payments') }} 或 {{ ref('stg_stripe__payments') }}
• FAIL：models/marts/core/fct_orders.sql:18 marts 模型直接引用 source，应经 staging 层
• PASS：models/staging/stripe/stg_stripe__payments.sql 正确使用 {{ source('stripe', 'payments') }}

DAG 结构验证：

• Staging 仅引用 source()
• Intermediate 仅引用 ref() 到 staging 或其他 intermediate
• Marts 引用 ref() 到 intermediate 或 staging
• 无循环依赖
• 链路过深（>8 层）提示过度设计
• 无“孤儿”模型（未被任何模型或 exposure 引用）

步骤 4：评估测试覆盖率 分析测试完整性：

# 解析 schema YAML 中的测试定义
cat models/staging/stripe/_stripe__models.yml

示例： 模型 stg_stripe__payments

• YAML 定义列：8
• 有测试列：3（37.5%）
• 测试：

- payment_id: unique, not_null ✅ - status: accepted_values ✅ - amount: not_null ✅

• 缺失测试：

- payment_id: 无 relationships 测试 ⚠️ - created_at: 无 not_null、无时效测试 ⚠️ - customer_id: 无 relationships 测试 ❌（外键应测） - currency: 无 accepted_values 测试 ⚠️ - payment_method: 无 accepted_values 测试 ⚠️

测试覆盖率汇总：

• 总模型：47
• 有测试模型：31（66%）
• 含主键测试：28（60%）
• 含关系测试：12（26%）🔴 偏低
• 零测试模型：16（34%）🔴 严重

推荐每模型最低测试： （表格略，保持原文优先级）