在数据驱动决策日益普及的今天，仪表盘已从简单的可视化工具演变为企业运营的核心基础设施。然而，传统仪表盘工具普遍存在版本控制困难、难以自动化、与 AI Agent 集成度低等问题。DAC（Dashboard-As-Code）作为 bruin-data 团队开源的仪表盘即代码工具，通过 YAML 与 TSX 双模式定义引擎、内置语义层以及深度 AI Agent 集成，为现代数据团队提供了一种全新的仪表盘开发范式。本文将系统解析 DAC 的技术架构与落地实践，为企业构建可编程、可审计、可被 AI Agent 驱动的仪表盘系统提供可操作的参数与方案。
一、仪表盘即代码的核心价值与设计理念
仪表盘即代码（Dashboard-as-Code）理念源自基础设施即代码（Infrastructure-as-Code）的成功实践，其核心思想是将仪表盘定义纳入版本控制系统，实现声明式管理、自动化部署与协作审核。DAC 在这一基础上更进一步，专门针对 AI Agent 场景进行了优化设计，使得大语言模型能够可靠地生成、修改与管理仪表盘定义。
传统的 BI 工具（如 Tableau、Power BI、Looker）虽然功能强大，但存在明显局限性：仪表盘定义存储在专有格式中，难以进行版本比对与合并；仪表盘创建依赖图形化操作，AI Agent 无法直接调用；多人协作时容易产生冲突，且缺乏有效的代码审查机制。DAC 通过将仪表盘定义为纯文本格式（YAML 或 TSX），彻底解决了这些问题。开发者可以使用熟悉的 Git 工作流管理仪表盘版本，AI Agent 可以通过读取与修改文本文件来调整仪表盘结构，所有变更均可追溯、可审查、可回滚。
DAC 的设计目标明确指向两个核心场景：一是供人类开发者使用声明式配置快速构建标准化仪表盘；二是供 AI Agent 通过编程接口自动生成业务可视化面板。这一双重定位决定了 DAC 在架构设计上必须兼顾人类友好性与机器可操作性，这也是其区别于其他仪表盘工具的关键特征。
二、YAML 与 TSX 双模式渲染引擎深度解析
DAC 提供了两种仪表盘定义模式：YAML 声明式模式与 TSX 编程式模式。这种双模式设计覆盖了从简单配置到复杂逻辑的全场景需求，开发者可以根据具体业务复杂度选择最合适的表达方式。
2.1 YAML 声明式模式
YAML 模式是 DAC 的基础模式，适用于结构相对固定、逻辑复杂度适中的仪表盘定义。在 YAML 模式中，仪表盘的结构完全由配置文件声明，无需编写代码。一个典型的 YAML 仪表盘定义包含仪表盘名称、数据库连接、行（Row）与组件（Widget）三个层级。以销售仪表盘为例，其 YAML 定义可表示为：
name: Sales Overview
connection: warehouse
rows:
- widgets:
- name: Revenue
type: metric
sql: SELECT SUM(amount) AS value FROM sales
column: value
prefix: "$"
col: 4
上述配置定义了一个名为「销售概览」的仪表盘，连接数据仓库「warehouse」，包含一个显示总收入的指标组件。该组件使用 SQL 查询从 sales 表中计算总额，并按美元货币格式渲染。YAML 模式的优势在于结构清晰、易于阅读、学习成本低，非常适合业务人员或初级开发者快速上手。同时，由于 YAML 是纯文本格式，AI Agent 可以轻松解析与生成这类配置，实现自动化仪表盘创建。
DAC 的 YAML 模式支持多种组件类型，包括指标（metric）、图表（chart）、表格（table）、过滤器（filter）等。组件属性通过 YAML 键值对声明，支持 SQL 查询引用、列映射、格式化参数、条件渲染等丰富配置。这种声明式方法与 Kubernetes 的 YAML 配置理念一脉相承，使得仪表盘管理可以无缝融入现有的 GitOps 流程。
2.2 TSX 编程式模式
对于需要动态渲染、循环生成、条件分支等复杂逻辑的场景，DAC 提供了 TSX（TypeScript XML）模式。TSX 模式允许开发者使用 TypeScript 编写仪表盘逻辑，利用编程语言的表达能力实现高度定制化的渲染行为。这一模式特别适合以下场景：根据查询结果动态决定显示哪些组件、根据用户权限条件化渲染敏感数据、循环遍历数据集生成重复组件结构、在运行时基于数据库信息构建布局。
在 TSX 模式中，仪表盘被定义为返回一个 React 风格组件的函数。该组件可以使用 DAC 提供的专用标签（如 Dashboard、Row、Metric、Chart 等）声明界面结构，同时在属性中嵌入 SQL 查询或业务逻辑。以下 TSX 代码展示了如何使用编程式方法定义一个包含动态查询的仪表盘：
export default (
<Dashboard name="Simple Dashboard" connection="my_db">
<Row>
<Metric
name="Total Revenue"
col={4}
sql="SELECT SUM(amount) AS value FROM sales"
column="value"
prefix="$"
format="number"
/>
</Row>
</Dashboard>
);
TSX 模式的强大之处在于其与前端开发范式的兼容性。熟悉 React 的开发者可以快速掌握 DAC 的 TSX 语法，同时可以利用 TypeScript 的类型系统获得编译时检查与智能提示。更重要的是，TSX 模式使得仪表盘定义可以包含业务逻辑，这在需要根据数据特征动态调整可视化方案时尤为重要。AI Agent 可以通过修改 TSX 代码来调整仪表盘逻辑，实现高度自动化的仪表盘生成与优化。
三、内置语义层与 SQL 自动生成机制
DAC 最具技术创新性的特性是其内置的语义层（Semantic Layer）。语义层位于数据源与仪表盘之间，抽象了底层数据库的物理结构，提供统一的业务语义定义。在传统 BI 架构中，语义层通常由独立的 BI 平台提供（如 Looker 的 LookML、Metabase 的模型定义等），而 DAC 将语义层直接集成到工具内部，形成了完整的仪表盘定义到 SQL 生成的闭环。
3.1 语义模型定义结构
DAC 的语义模型定义在项目根目录下的 semantic/ 目录中。在语义模型中，开发者可以定义指标（Metric）与维度（Dimension）两种核心概念。指标是对业务数值的量化表述，如「总收入」「订单数量」「转化率」等；维度是分析数据的视角，如「时间」「地区」「产品类别」等。定义完成后，仪表盘组件可以直接引用语义模型中的指标与维度，DAC 会在渲染时自动生成对应的 SQL 查询。
语义模型的核心价值在于「定义一次，引用多次」。以电商场景为例，如果业务方定义了「月度销售额」这一指标，后续所有仪表盘中的相关图表都可以直接引用该语义定义，而无需重复编写 SQL。当底层数据表结构发生变化时（如分库分表、数据湖迁移），只需在语义层修改一次定义，所有引用该指标的仪表盘即可自动适配，无需逐个修改。这种集中化的语义管理机制大大降低了维护成本，同时也为 AI Agent 提供了稳定的抽象接口。
3.2 SQL 自动编译流程
DAC 的 SQL 自动生成采用了编译时解析与运行时执行分离的架构。当仪表盘定义引用语义模型时，DAC 会在服务端进行语义到 SQL 的编译转换。具体流程如下：首先解析仪表盘定义，识别其中引用的语义模型元素（指标、维度、过滤器等）；然后根据语义模型定义组装 SQL 片段，包括 SELECT 子句的指标计算、GROUP BY 子句的维度分组、WHERE 子句的过滤条件等；最后将生成的 SQL 发送给底层数据库执行，并将结果映射到对应的可视化组件。
这种编译时 SQL 生成机制带来了多项优势。其一是类型安全：语义模型定义了指标与维度的数据类型，DAC 可以在编译阶段检测类型不匹配的问题，避免运行时错误。其二是性能优化：DAC 可以对生成的 SQL 进行语法优化与执行计划分析，帮助识别潜在的性能瓶颈。其三是可审计性：所有仪表盘对应的 SQL 查询都可以被记录与审查，这对于需要满足合规要求的企业尤为重要。AI Agent 可以通过查询 DAC 生成的 SQL 来验证仪表盘逻辑的正确性，同时也能够基于语义层进行问答式的数据探索。
四、AI Agent 集成：Codex 深度集成与可编程调用
DAC 在设计之初就将 AI Agent 集成作为核心特性，这与传统的仪表盘工具形成了鲜明对比。传统 BI 工具通常不提供编程接口，或者仅提供有限的 REST API，AI Agent 难以直接操控仪表盘的创建与修改过程。DAC 通过两种方式实现了与 AI Agent 的深度集成：一是内置的 Codex 聊天式交互，二是面向所有 AI 框架的标准化 Agent Skills。
4.1 Codex 内置聊天界面
DAC 集成了 Codex（Anthropic 推出的 AI 编程助手）作为内置的仪表盘对话引擎。用户可以在 DAC 服务的 Web 界面中直接与 Codex 交互，用自然语言描述所需的仪表盘变更，Codex 会解析需求并自动修改对应的 YAML/TSX 定义文件。这种聊天式交互方式极大降低了仪表盘开发的门槛，业务人员无需了解 YAML 语法或 SQL 编写，即可在 Codex 的辅助下完成基本的仪表盘创建与调整。
Codex 的集成深度体现在其对 DAC 项目结构的理解上。当用户提出「添加一个显示月度趋势的折线图」这样的需求时，Codex 会识别当前项目的语义模型，判断是否存在可用的时间维度与相关指标，然后生成符合 DAC 规范的 YAML/TSX 代码并写入对应文件。整个过程完全自动化，用户只需确认最终结果即可。这种端到端的自然语言到仪表盘定义的转换能力，是 DAC 区别于其他工具的核心竞争力。
4.2 可安装的 Agent Skills
除了内置的 Codex 集成，DAC 还提供了面向各类 AI Agent 的标准化 Skills。Skills 是 AI Agent 可以调用的一组能力定义，类似于 MCP（Model Context Protocol）的工具描述。DAC 的 Skills 封装了仪表盘创建、验证、部署等核心操作，AI Agent 可以通过调用这些 Skills 来执行自动化工作流。
安装 DAC Skills 的过程非常简单。在初始化项目时，运行 dac init 命令会同时安装针对 Claude 与 Codex 的 Skills：
dac init my-dashboards
ls .claude/skills/create-dashboard/SKILL.md
ls .codex/skills/create-dashboard
对于已有项目，可以使用 dac skills install --dir . 命令单独安装 Skills。安装完成后，AI Agent 就获得了创建仪表盘、验证配置、启动服务等能力，可以在没有任何人工干预的情况下完成端到端的仪表盘开发流程。这为企业构建 AI 原生的数据看板系统提供了坚实的技术基础。
Agent Skills 的设计遵循了可扩展原则。DAC 项目结构中存在 .agents/skills 目录，开发者可以在此目录下定义自定义 Skills，封装特定的业务逻辑或领域知识。这意味着企业可以基于 DAC 构建行业特定的仪表盘模板库，AI Agent 在创建新仪表盘时可以自动应用这些模板，实现更高程度的自动化。
五、多数据库支持与查询后端架构
DAC 在数据源层面采用了多后端支持的设计，目前支持的主流数据库包括 PostgreSQL、MySQL、Snowflake、BigQuery、Amazon Redshift 以及 Databricks。这一广泛的数据库支持使得 DAC 可以融入几乎任何企业数据栈，无需对现有数据基础设施进行大规模改造。
DAC 通过调用 Bruin CLI（bruin query 命令）来执行数据库查询。这种设计将数据连接管理的职责剥离到 Bruin 工具层，DAC 本身专注于仪表盘的解析、渲染与服务。这种关注点分离（Separation of Concerns）的架构有几个实际优势：企业已有的 Bruin 连接配置可以直接复用，无需在 DAC 中重新配置；数据访问的安全策略（如行级安全、列级权限）由 Bruin 层统一管理，DAC 无需重复实现；新增数据库支持只需在 Bruin 侧实现，DAC 无需修改。
在查询执行层面，DAC 支持两种模式：直接 SQL 模式与语义查询模式。直接 SQL 模式在组件定义中直接编写 SQL 语句，适合需要精细控制的场景；语义查询模式通过引用语义模型由 DAC 自动生成 SQL，适合追求统一语义与可维护性的场景。两种模式可以混合使用，开发者可以根据具体需求灵活选择。
六、工程化实践：项目初始化、验证与服务
DAC 作为一款成熟的命令行工具，提供了完整的工程化流程支持。从项目初始化到持续验证再到服务部署，每一个环节都有对应的 CLI 命令可供使用。
6.1 项目初始化与结构
使用 dac init 命令可以创建一个包含示例仪表盘的初始项目结构：
dac init my-dashboards
cd my-dashboards
dac validate --dir .
dac serve --dir . --open
初始化后的项目结构包含以下核心目录：examples/ 下是四个完整的示例项目，分别展示 YAML 模式、TSX 模式、语义模型 YAML 与语义模型 TSX 的用法；semantic/ 目录下放置语义模型定义文件；仪表盘定义文件（YAML 或 TSX）放在项目根目录或子目录中。这种结构化设计便于团队协作与代码组织。
6.2 配置验证与类型检查
dac validate 命令是 DAC 工程化流程中的关键环节。该命令会解析所有仪表盘定义文件，检查 YAML/TSX 语法正确性、语义模型引用完整性、SQL 语句语法有效性以及组件配置合法性。验证过程会在终端输出详细的错误信息与警告，帮助开发者快速定位问题。对于 AI Agent 生成的仪表盘代码，验证环节尤为重要，可以有效防止无效配置进入部署阶段。
6.3 服务启动与热重载
dac serve 命令启动一个本地 Web 服务器，提供仪表盘的实时预览功能。服务支持热重载（Hot Reload），当仪表盘定义文件发生变化时，页面会自动刷新，无需手动重启。这一特性极大提升了开发效率，尤其适合需要反复调整可视化方案的迭代场景。--open 参数可以在服务启动后自动打开浏览器窗口，省去手动导航的步骤。
在生产部署场景下，DAC 可以作为独立的 HTTP 服务运行，接受请求并渲染仪表盘页面。由于渲染引擎完全嵌入在 DAC 二进制文件中，部署过程非常简洁 —— 只需在服务器上部署一个可执行文件即可，无需额外部署 Web 服务器或数据库组件。
七、落地参数与实践建议
基于上述技术分析，以下为企业级落地 DAC 的关键参数与实践建议：
在安装部署方面，生产环境建议使用稳定版本而非 edge 渠道。稳定版安装命令为 curl -fsSL https://raw.githubusercontent.com/bruin-data/dac/main/install.sh | bash，该版本经过充分测试，适合生产使用。只有在需要最新特性或参与开发测试时，才考虑使用 edge 渠道。
在项目组织方面，建议按业务领域组织仪表盘目录结构。每个业务线或功能模块对应一个子目录，子目录内包含该模块的仪表盘定义与专用语义模型。这种组织方式便于权限管理与团队分工，同时也符合微服务架构的设计理念。
在语义模型治理方面，语义模型的定义应当由数据团队统一管理，确保指标计算口径的一致性。建议建立语义模型的版本管理制度，每次语义模型变更都需要经过代码审查流程。AI Agent 在创建新仪表盘时，应当优先复用已有的语义模型元素，而非创建新的 SQL 查询。
在 AI Agent 集成方面，建议为 AI Agent 配置专用的连接凭证，该凭证仅具有必要的只读或有限写权限，防止 Agent 误操作导致生产问题。同时应当建立仪表盘变更的审核机制，所有由 AI Agent 生成的仪表盘定义都需要经过人工审核后才能部署到生产环境。
在监控与可观测性方面，DAC 内置了遥测（Telemetry）功能，会收集命令使用情况、运行时间、错误率等匿名数据用于产品改进。企业可以通过设置 TELEMETRY_OPTOUT=1 或 DO_NOT_TRACK=1 环境变量来禁用遥测。在生产环境中，建议同时部署独立的访问日志与性能监控，以便及时发现与定位问题。
结语
DAC 作为仪表盘即代码领域的创新工具，通过 YAML/TSX 双模式渲染引擎、内置语义层与深度 AI Agent 集成，为企业构建可编程、可版本控制、可被 AI 驱动的仪表盘系统提供了完整的技术方案。其设计理念与工程实践充分体现了现代软件开发的最佳实践 —— 声明式配置、版本控制、自动化验证、持续部署。对于正在探索 AI Agent 数据应用的企业而言，DAC 提供了一条切实可行的技术路径，使得 AI 不仅可以生成数据分析结果，还能够将这些结果以标准化、可审计的方式呈现为业务仪表盘。
资料来源：DAC 官方 GitHub 仓库（https://github.com/bruin-data/dac）