name: dbt-project-analyzer description: 分析 dbt 项目的最佳实践、性能、可维护性，并生成可操作的改进建议。 version: 1.0.0 category: Transformation skill-id: SK-DEA-003 allowed-tools: Read, Grep, Glob, Bash, WebFetch

dbt 项目分析器

根据 dbt Labs 推荐的模式，分析 dbt 项目的最佳实践、性能和可维护性。

概述

此技能检查 dbt 项目的结构、模型依赖关系、测试覆盖率、文档完整性以及命名规范的遵守情况。它提供可操作的建议，以改善项目的健康度和可维护性。

功能

模型依赖图分析 - 可视化和分析模型关系，检测循环依赖
增量模型优化 - 评估增量策略并提出改进建议
物化策略建议 - 根据使用模式推荐最佳物化方式
测试覆盖率分析 - 测量并报告跨模型的测试覆盖率
文档完整性检查 - 识别未记录的模型、列和源
命名规范验证 - 强制执行一致的命名模式（staging, marts, intermediate）
Ref/source 使用验证 - 检测硬编码引用和缺失的源定义
宏效率分析 - 评估宏使用情况并提出优化建议
Slim CI 优化 - 通过状态比较配置高效的 CI 构建
模型契约验证 - 验证模型契约以确保类型安全

输入模式

{
  "projectPath": {
    "type": "string",
    "description": "dbt 项目根目录的路径",
    "required": true
  },
  "manifestJson": {
    "type": "object",
    "description": "来自 target/ 目录的已解析 manifest.json（可选，如果未提供则加载）"
  },
  "catalogJson": {
    "type": "object",
    "description": "来自 target/ 目录的已解析 catalog.json（可选）"
  },
  "runResults": {
    "type": "object",
    "description": "用于性能分析的已解析 run_results.json（可选）"
  },
  "analysisDepth": {
    "type": "string",
    "enum": ["quick", "standard", "deep"],
    "default": "standard",
    "description": "要执行的分析深度"
  },
  "focusAreas": {
    "type": "array",
    "items": {
      "type": "string",
      "enum": ["performance", "testing", "documentation", "naming", "incremental", "dependencies"]
    },
    "description": "要重点分析的具体领域（如果未指定则为全部）"
  }
}

输出模式

{
  "healthScore": {
    "type": "number",
    "description": "项目整体健康度评分（0-100）"
  },
  "issues": {
    "type": "array",
    "items": {
      "severity": "error|warning|info",
      "category": "string",
      "model": "string",
      "message": "string",
      "recommendation": "string",
      "line": "number"
    }
  },
  "metrics": {
    "testCoverage": {
      "type": "number",
      "description": "拥有测试的模型百分比"
    },
    "docCoverage": {
      "type": "number",
      "description": "已记录的模型/列百分比"
    },
    "incrementalRatio": {
      "type": "number",
      "description": "符合条件的模型中使用增量的百分比"
    },
    "avgModelDepth": {
      "type": "number",
      "description": "DAG 中的平均深度"
    },
    "totalModels": {
      "type": "number"
    },
    "totalTests": {
      "type": "number"
    }
  },
  "recommendations": {
    "type": "array",
    "items": {
      "priority": "high|medium|low",
      "category": "string",
      "description": "string",
      "effort": "string",
      "impact": "string"
    }
  },
  "dependencyGraph": {
    "type": "object",
    "description": "用于可视化的简化依赖图"
  }
}

使用示例

基础项目分析

# 调用技能进行标准分析
/skill dbt-project-analyzer --projectPath ./my-dbt-project

深度分析与重点领域

{
  "projectPath": "./analytics",
  "analysisDepth": "deep",
  "focusAreas": ["performance", "testing", "incremental"]
}

CI 集成分析

{
  "projectPath": "./dbt_project",
  "manifestJson": "./target/manifest.json",
  "runResults": "./target/run_results.json",
  "focusAreas": ["performance"]
}

分析规则

命名规范

层级	模式	示例
贴源层	`stg_<source>__<entity>`	`stg_stripe__payments`
中间层	`int_<entity>_<verb>`	`int_payments_pivoted`
集市层	`fct_<entity>` 或 `dim_<entity>`	`fct_orders`, `dim_customers`

测试覆盖率要求

严重程度	条件
错误	主键上没有唯一性/非空测试
警告	< 50% 的列有测试
信息	缺少关系测试

物化指南

模型类型	推荐物化	原因
贴源层	视图或临时表	源转换，计算量低
中间层	临时表	减少数据仓库中的杂乱
集市层	表或增量表	最终用户查询，性能
大表（>100万行）	增量表	减少构建时间

集成点

MCP 服务器集成

此技能与官方的 dbt MCP 服务器集成，以增强功能：

dbt-labs/dbt-mcp - 项目元数据发现、模型信息、语义层查询
dbt Remote MCP Server - 云托管的 dbt MCP，具有安全端点访问

适用流程

dbt 项目设置 (dbt-project-setup.js)
dbt 模型开发 (dbt-model-development.js)
指标层 (metrics-layer.js)
增量模型设置 (incremental-model.js)

参考资料

版本历史

1.0.0 - 具有核心分析功能的初始版本