Dex 实战教程：用 Claude Code 插件实现 Agent 原生数据分析工程
AI 编码 Agent 很擅长写代码，但面对数据分析工程（Analytics Engineering）工作流时，它们有一个显著的盲区：每次会话都要重新学习 Schema，面对成千上万张表无从下手，对数据仓库的成本和敏感数据毫无感知。如果你的团队用 Claude Code 处理数据管道任务，这些问题每天都在发生。
痛点：AI Agent 的数据工程盲区
传统 AI 编码 Agent 在数据仓库场景下的局限很具体：
- Schema 记忆为零：Agent 不知道你有多少张表、哪些是核心事实表、哪些是维度表。每次会话都得从头探测
- 仓库成本盲区：Agent 无法预估查询成本。随意
SELECT *扫描数 TB 数据，月底 Cloud Billing 才被发现 - 敏感数据泄漏风险：Agent 可能把 PII 字段拉进上下文做分析，但开发者没有细粒度控制
- dbt 项目不是一等公民：Agent 理解代码库结构，但 dbt 的 staging → intermediate → marts 分层、semantic model（MetricFlow YAML）、test 和文档，对 Agent 完全是黑盒
Dex 正是为了解决这些问题而设计的——一个 Agent 原生（agent-native）数据分析工程工具包，以 Claude Code 插件的形式嵌入工作流。
Dex 由 Exmergo 公司开发，Apache-2.0 开源，核心包
exmergo-dex-core已发布到 PyPI。
安装：Claude Code 插件 + 通用安装
Dex 的安装有两种方式，分别对应不同的 Agent 环境：
Claude Code 插件安装
在 Claude Code 会话中依次执行：
/plugin marketplace add exmergo/exmergo-agent-plugins /plugin install dex@exmergo
安装后出现三个技能命令：/dex:explore、/dex:transform 和 /dex:maintain，会根据你的意图自动触发。
通用 Agent 安装
如果你使用 Codex、OpenCode 或其他支持 skills 标准的 Agent：
npx skills install exmergo/dex
Python 核心包
Dex 的核心逻辑封装在 exmergo-dex-core 包中，可作为独立库使用：
pip install exmergo-dex-core uv add exmergo-dex-core
实战场景 1：探索未知的数据仓库
接手的第一个任务通常是「这个仓库里有什么？」——几十个 Schema、几百张表，人工挨个查效率极低，全部问 Agent 又怕查询成本失控。
Dex 的 Explore 阶段解决了这一问题。它采用分级探测策略：
- 先列出所有 Schema 和表，按统计信息排序（行数、大小、更新频率）
- 对排在前列的表做选择性的概要探测——提取列名、数据类型、空值率、分布推测
- 推断并验证表之间的 Join 关系
- 将结果持久化为一张可编辑的地图（draft map），后续可直接引用
全程只读（read-only），且每步扫描前会估算并确认成本：
⏳ Estimated scan cost: ~$0.03 (BigQuery, 1.2 GB processed) Proceed? [Y/n]
BigQuery 通过 Application Default Credentials 自动发现凭据，Snowflake 和 Postgres 则通过 connections.toml、环境变量或 dbt profile 读取。每条查询都有服务端上限保护——BigQuery 受 maximum_bytes_billed 约束，Snowflake 和 Postgres 有语句超时和信用配额。
/dex:explore
实战场景 2：dbt 模型转换与语义层
数据分析工程的核心是 dbt 项目——从原始数据到分析就绪的 marts，中间经过 staging（清洗）→ intermediate（业务逻辑）→ marts（聚合指标）三层。Dex 的 Transform 阶段让 Agent 能像理解代码库一样理解 dbt 项目：
- Author dbt models：Dex 能根据目标 Schema 自动生成 staging 模型（列重命名、类型转换、基本测试）
- 建立 semantic layer：在 dbt 的 semantic model（MetricFlow YAML）中定义 entities、dimensions、measures 和 metrics
- Viz 预览：生成的指标可以直接在 DuckDB 中验证，输出可视化预览
/dex:transform
Dex 在 ADE-bench（75 个分析工程任务）上达到 76% 的任务成功率（使用 Claude Sonnet 5），且成本仅为 Fable 5 的 1/2.5。更有趣的是：不同模型的准确率差距不大（72-76%），但成本差异极大——这意味着你可以用便宜的模型跑 Dex 而仍然获得顶级结果。
连接器支持
| 类型 | 数据库 | 凭据发现方式 |
|---|---|---|
| 云数据仓库 | Snowflake | connections.toml、SNOWFLAKE_* 环境变量、dbt profile |
| 云数据仓库 | BigQuery | gcloud Application Default Credentials |
| 嵌入式分析 | DuckDB | 本地文件路径 |
| 操作型数据库 | Postgres | pg_service.conf、DATABASE_URL、PG* 环境变量、dbt profile |
即将支持：Databricks、AWS Redshift、Microsoft Fabric。
实战场景 3：Schema 漂移的自动化维护
数据仓库不是静态的——业务变更导致 Schema 几乎每周都在变：新增列、重命名字段、粒度变化、定义调整。如果人工跟踪这些变化，团队消耗在「对账」上的时间往往远大于实际开发时间。
Dex 的 Maintain 阶段自动做三件事：
- Diff 快照：将当前仓库和 dbt 项目与上一次 Dex 运行时的快照对比
- 漂移分级：按影响半径（blast radius）对 schema、volume、grain、definition 四类漂移排序
- 提案编辑：对每个漂移给出修复建议——修改 dbt 模型、更新 semantic model 或标记为预期变更
/dex:maintain
所有变更都通过 Git 生成 diff，每个修改都是可审查的——Dex 不会静默修改你的 dbt 项目。
最佳实践
- 先 Explore 再 Transform：新接入仓库时，先跑
/dex:explore让 Dex 建立仓库地图，再做转换。地图可以后续修正，是持续维护的基础 - 成本门控不要跳过：Dex 的每步成本估算不仅是保护账单，也是理解仓库规模的窗口。建议保留确认门控
- 语义层优先：MetricFlow YAML 的 semantic model 是 Dex 的核心价值——投入时间定义好 entities 和 measures，后续的维护和查询效率会大幅提升
- 漂移检查频率：建议每周至少运行一次
/dex:maintain，将漂移检查纳入 CI 流程
总结
Dex 填补了 AI 编码 Agent 在数据分析工程领域的空白——它不是一个通用的 SQL 编辑器，而是一个深度理解数据仓库和 dbt 项目的 Agent 原生工具。Explore → Transform → Maintain 三阶段循环让 Agent 能像有经验的数据工程师一样工作，同时保持成本可见和敏感数据可控。
如果你是数据工程师或在团队中使用 dbt 管理分析管道，Dex 值得加入你的 Claude Code 工具箱。
相关链接：