---

name: monte-carlo-validation-notebook description: "为 dbt PR 变更生成 SQL 验证笔记本，包含变更前后对比查询。" category: data risk: safe source: community source_repo: monte-carlo-data/mc-agent-toolkit source_type: community date_added: "2026-04-08" author: monte-carlo-data tags: [数据可观测性, 验证, dbt, monte-carlo, sql-notebook] tools: [claude, cursor, codex]

提示： 此技能与 Sonnet 配合效果良好。调用前运行 /model sonnet 可加快生成速度。

为 dbt 变更生成包含验证查询的 SQL 笔记本。

参数： $ARGUMENTS

使用场景

当用户需要通过 Monte Carlo SQL 笔记本查询来验证 dbt 模型或快照变更时使用此技能，支持从 GitHub PR 或本地 dbt 仓库获取变更。

解析参数：

• 目标 (必填)：第一个参数 — GitHub PR URL 或本地 dbt 仓库路径
• MC 基础 URL (可选)：--mc-base-url <URL> — 默认为 https://getmontecarlo.com
• 模型 (可选)：--models <model1,model2,...> — 逗号分隔的模型文件名列表（不含 .sql 扩展名）。仅包含指定模型。默认包含所有变更模型，最多 10 个。

---

环境准备

前置条件：

• gh (GitHub CLI) — PR 模式必需，须已认证（gh auth status）。
• python3 — 辅助脚本必需。
• pyyaml — 通过 pip3 install pyyaml（或 pip install pyyaml、uv pip install pyyaml 等）安装。

注意： 生成的 SQL 使用 ANSI 兼容语法，适用于 Snowflake、BigQuery、Redshift 和 Athena。特定数据仓库可能需要微调。

此技能包含两个辅助脚本，位于 ${CLAUDE_PLUGIN_ROOT}/skills/monte-carlo-validation-notebook/scripts/：

• resolve_dbt_schema.py - 从 dbt_project.yml 路由规则和模型配置覆盖中解析 dbt 模型输出 schema。
• generate_notebook_url.py - 将笔记本 YAML 编码为 base64 导入 URL 并在浏览器中打开。

模式检测

根据目标参数自动检测模式：

• 如果目标看起来像 URL（包含 :// 或 github.com）-> PR 模式
• 如果目标是路径（.、/path/to/repo、相对路径）-> 本地模式

---

上下文

此命令生成包含 dbt 变更验证查询的 SQL 笔记本。笔记本可在 MC Bridge SQL 笔记本界面中打开进行交互式验证。

输出为直接在笔记本界面中打开的导入 URL：

<MC_BASE_URL>/notebooks/import#<base64-encoded-yaml>

核心功能：

• 数据库参数：两个 text 参数（prod_db 和 dev_db）用于选择数据库
• Schema 推断：从 dbt_project.yml 和模型配置自动推断每个模型的 schema
• 单表查询：使用 {{prod_db}}.<SCHEMA>.<TABLE> 的基础验证查询
• 对比查询：比较 {{prod_db}} 与 {{dev_db}} 的变更前后查询
• 灵活使用：用户可将两个参数设为同一数据库进行单库分析

笔记本 YAML 规范参考

关键结构：

version: 1
metadata:
  id: string           # kebab-case + 随机后缀
  name: string         # 显示名称
  created_at: string   # ISO 8601
  updated_at: string   # ISO 8601
default_context:       # 可选的数据库/schema 上下文
  database: string
  schema: string
cells:
  - id: string
    type: sql | markdown | parameter
    content: string    # SQL、markdown 或参数配置 (JSON)
    display_type: table | bar | timeseries

参数单元格规范

参数单元格允许定义通过 {{param_name}} 语法在 SQL 中引用的变量：

- id: param-prod-db
  type: parameter
  content:
    name: prod_db              # variable name
    config:
      type: text                   # free-form text input
      default_value: "ANALYTICS"
      placeholder: "Prod database"
  display_type: table

参数类型：

• text：自由文本输入（用于数据库名称）
• schema_selector：两个下拉菜单（数据库 -> schema），值存储为 DATABASE.SCHEMA
• dropdown：从预定义选项中选择

任务

根据模式和目标生成包含验证查询的 SQL 笔记本。

阶段 1：获取变更文件

方法因模式而异：

PR 模式（GitHub PR）：

1. 从目标 URL 中提取 PR 编号和仓库。

   • 示例：https://github.com/monte-carlo-data/dbt/pull/3386 -> owner=monte-carlo-data, repo=dbt, PR=3386

2. 使用 gh 获取 PR 元数据：

gh pr view <PR#> --repo <owner>/<repo> --json number,title,author,mergedAt,headRefOid

1. 获取变更文件列表：

gh pr view <PR#> --repo <owner>/<repo> --json files --jq '.files[].path'

1. 获取差异：

gh pr diff <PR#> --repo <owner>/<repo>

1. 筛选变更文件列表，仅保留 models/ 或 snapshots/ 目录下的 .sql 文件（任意嵌套深度）。