大数据智能体工作台 DataBuddy Bundle 包定义

概述
Bundle 包是 DataBuddy CI/CD 的核心配置单元，通过 YAML 文件定义工作流、任务、环境变量和部署策略。本文档详细说明 Bundle 的目录结构、配置文件语法和各字段含义。
目录结构
一个标准的 Bundle 项目包含以下目录和文件：
my_bundle/
├── databuddy.yml           # Bundle 主配置文件（必须）
├── resources/              # 资源定义目录
│   └── workflow/           # 工作流资源子目录
│       └── workflow_a.yml
├── src/                    # 代码文件目录
│   ├── task_a.sql
│   └── task_b.sql
└── README.md               # 项目说明
主配置文件（databuddy.yml）
databuddy.yml 是 Bundle 的入口配置文件，定义 Bundle 基础信息、环境配置和变量。
完整示例
# Bundle 基本配置
bundle:
  name: my_bundle
  uuid: a97c467e-xxxx-xxxx-xxxx-525400694f7c
﻿
# 引入资源文件
include:
  - resources/workflow/*.yml
﻿
# 全局变量定义
variables:
  scheduling_resource_group:
    description: resource_group_name
﻿
# 多环境配置
targets:
  dev:
    mode: development
    default: true
    variables:
      scheduling_resource_group: dev_resource_group
    workspace:
      host: https://databuddy.cloud.tencent.com/workbench?o=<workspace_id>&r=<region_id>
﻿
  prod:
    mode: production
    variables:
      scheduling_resource_group: prod_resource_group
    workspace:
      host: https://databuddy.cloud.tencent.com/workbench?o=<workspace_id>&r=<region_id>
﻿
  staging:
    mode: production
    variables:
      scheduling_resource_group: staging_resource_group
    workspace:
      host: https://databuddy.cloud.tencent.com/workbench?o=<workspace_id>&r=<region_id>
配置字段详解
bundle（必填）
参数
说明
是否必填
默认值
name
Bundle 项目名称，用于标识项目
是
—
uuid
Bundle 唯一标识符，databuddy bundle init 时自动生成
是（自动）
自动生成
wedata_cli_version
所需的 databuddy CLI 最低版本
否
不限制
include
指定要包含在 Bundle 中的资源配置文件路径，支持通配符：
include:
  - resources/workflow/*.yml    # 匹配 resources/workflow/ 下的所有 yml 文件
variables（全局变量）
定义可在整个 Bundle 中引用的变量，使用 ${var.<变量名>} 引用。
参数
说明
是否必填
description
变量描述
否
default
默认值
否
type
变量类型（string）
否
变量可在 Target 中覆盖，实现不同环境使用不同的值。
targets（多环境配置）
每个 Target 代表一个部署环境。
参数
说明
是否必填
默认值
mode
部署模式：development 或 production
否
development
default
是否为默认 Target（不指定 -t 时使用）
否
false
variables
环境级变量覆盖
否
—
workspace.host
目标 Workspace 地址
是
—
workspace.root_path
Bundle 文件在 Studio 中的存储路径
否
.bundle/<name>/<target>
permissions
部署后资源的权限配置
否
Profile 用户为 CAN_MANAGE
development 模式与 production 模式的区别：
行为
development
production
工作流名称前缀
自动添加 dev_<用户名>_ 前缀
无前缀
文件路径
指向 .bundle/<name>/dev/files/
指向任务配置中的引用路径
root_path 限制
必须在个人文件夹下（~/ 开头）
无限制，建议指定独立路径
注意
development 模式下 root_path 必须以 ~/ 开头或包含当前用户名，否则 deploy 会报错：[Error] root path must start with '~/' or contain the current username to ensure uniqueness when using 'mode: development'
permissions
参数
说明
取值
user_name
用户账号
邮箱格式
level
权限级别
CAN_VIEW / CAN_RUN / CAN_MANAGE / IS_OWNER
资源配置（resources）
资源配置文件放在 resources/workflow/ 目录下，定义 Bundle 中的工作流及其包含的任务。
Workflow 资源示例
以下是一个包含两个 SQL 任务的工作流配置示例（resources/workflow/workflow_a.yml）。不同任务类型（如 SQL、Shell、Python 等）的 task_type 及 task_type_property_list 字段会有所不同，此处仅以 SQL 任务为例：
resources:
  workflows:
    workflow_a:
      name: workflow_a
      execute_user: <your_username>
      trigger:
        - scheduler_status: ACTIVE
          trigger_mode: TIME_TRIGGER
          scheduler_time_zone: Asia/Shanghai
          start_time: "2026-06-01 00:00:00"
          end_time: "2099-12-31 23:59:59"
          config_mode: COMMON
          cycle_type: DAY_CYCLE
          crontab_expression: 0 0 2 * * ? *
      advance_config:
        queuing_mode: "OFF"
        max_concurrent_num: 1
      task_list:
        - task_name: task_a
          file_path: ../../src/task/task_a.sql
          remote_dir_path: /Workspace/task_a.sql
          resource_group_name: ${var.scheduling_resource_group}
          depend_on_run_condition: ALL_SUCCESS
          task_type:
            task_type_name: SQL
            task_type_property_list:
              - property_key: Source
                property_value: WorkSpace
              - property_key: SqlPath
                property_value: /Workspace/task_a.sql
              - property_key: CodeFileName
                property_value: task_a.sql
          param_list:
            - param_key: bizdate
              param_value: '{{workflow.trigger.time.iso_date}}'
          task_retry_strategy:
            max_retry_time: 3
            retry_between_wait_time: 5
            retry_between_wait_time_unit: SECOND
            task_run_failure_retry_switch: true
﻿
        - task_name: task_b
          file_path: ../../src/task/task_b.sql
          remote_dir_path: /Workspace/task_b.sql
          resource_group_name: ${var.scheduling_resource_group}
          depend_on_run_condition: ALL_SUCCESS
          task_type:
            task_type_name: SQL
            task_type_property_list:
              - property_key: Source
                property_value: WorkSpace
              - property_key: SqlPath
                property_value: /Workspace/task_b.sql
              - property_key: CodeFileName
                property_value: task_b.sql
          param_list:
            - param_key: bizdate
              param_value: "1"
          depend_on_list:
            - task_name: task_a
          task_retry_strategy:
            max_retry_time: 3
            retry_between_wait_time: 5
            retry_between_wait_time_unit: SECOND
            task_run_failure_retry_switch: true
对应的 SQL 代码文件放在 src/task/ 目录中，例如 src/task/task_a.sql：
INSERT OVERWRITE TABLE target_schema.table_a PARTITION(dt = '${bizdate}')
SELECT  col_1,
        col_2,
        COALESCE(col_3, 0) AS col_3,
        col_4
FROM    source_schema.table_b
WHERE   dt = '${bizdate}'
AND     col_1 IS NOT NULL
Workflow 字段说明
参数
说明
是否必填
默认值
name
工作流名称
是
—
execute_user
执行用户
否
当前 Profile 用户
trigger
触发器配置（调度规则）
否
不启用调度
advance_config
高级配置（排队模式、并发数）
否
—
task_list
任务列表
是
—
Task 字段说明
参数
说明
是否必填
默认值
task_name
任务名称
是
—
file_path
本地代码文件的相对路径
是
—
remote_dir_path
远程存储路径
是
—
resource_group_name
执行资源组名称，支持变量引用
是
—
depend_on_run_condition
依赖运行条件（ALL_SUCCESS 等）
否
ALL_SUCCESS
task_type
任务类型配置
是
—
task_type.task_type_name
任务类型名称（SQL / Python / Notebook 等）
是
—
task_type.task_type_property_list
任务类型属性列表
否
—
param_list
参数列表
否
—
depend_on_list
依赖的上游任务列表
否
—
task_retry_strategy
重试策略
否
—
Trigger 字段说明
参数
说明
是否必填
默认值
scheduler_status
调度状态（ACTIVE / INACTIVE）
否
INACTIVE
trigger_mode
触发模式（TIME_TRIGGER）
否
—
scheduler_time_zone
调度时区
否
Asia/Shanghai
start_time
调度生效开始时间
否
—
end_time
调度生效结束时间
否
—
config_mode
配置模式（COMMON）
否
—
cycle_type
周期类型（DAY_CYCLE / HOUR_CYCLE 等）
否
—
crontab_expression
Cron 表达式
否
—
变量引用
在资源配置中可以通过 ${var.<变量名>} 引用 databuddy.yml 中定义的全局变量，例如：
resource_group_name: ${var.scheduling_resource_group}
不同 Target 下变量值会自动替换为对应环境的配置。
使用限制
Bundle 中的文件总数不能超过 5,000 个。
主配置文件必须命名为 databuddy.yml，否则 CLI 无法识别 Bundle 根目录。
include 路径支持通配符 *，但不支持递归通配 **。
development 模式下 root_path 必须为个人路径。
工作流名称在 development 模式下会自动添加前缀，部署后名称为 dev_<用户名>_<原名>。
常见问题
Q1：databuddy.yml 中未定义 uuid 怎么办？
uuid 在 databuddy bundle init 时自动生成。如果手动创建的项目缺少 uuid，执行 databuddy bundle validate 时会报错 [ERROR] bundle id not defined。建议通过 init 命令创建项目。
Q2：如何在不同环境使用不同的资源组？
在 variables 中定义变量，然后在不同的 Target 中覆盖：
variables:
  scheduling_resource_group:
    description: resource_group_name
﻿
targets:
  dev:
    variables:
      scheduling_resource_group: dev_resource_group
  prod:
    variables:
      scheduling_resource_group: prod_resource_group
Q3：resources 目录下没有 yml 文件会怎样？
执行 databuddy bundle validate 或 deploy 时会报错：[ERROR] There is no resource yml file defined in bundle. 请确保 resources/workflow/ 等子目录中至少包含一个 yml 文件。
相关文档
CI/CD 概述
Bundle 命令
使用 Bundle 开发
调度与触发器
参数	说明	是否必填	默认值
`name`	Bundle 项目名称，用于标识项目	是	—
`uuid`	Bundle 唯一标识符，`databuddy bundle init` 时自动生成	是（自动）	自动生成
`wedata_cli_version`	所需的 databuddy CLI 最低版本	否	不限制
行为	development	production
工作流名称前缀	自动添加 `dev_<用户名>_` 前缀	无前缀
文件路径	指向 `.bundle/<name>/dev/files/`	指向任务配置中的引用路径
`root_path` 限制	必须在个人文件夹下（`~/` 开头）	无限制，建议指定独立路径
参数	说明	取值
`user_name`	用户账号	邮箱格式
`level`	权限级别	`CAN_VIEW` / `CAN_RUN` / `CAN_MANAGE` / `IS_OWNER`
Bundle 包定义

本页目录：

概述

目录结构

主配置文件（databuddy.yml）

完整示例

配置字段详解

bundle（必填）

include

variables（全局变量）

targets（多环境配置）

permissions

资源配置（resources）

Workflow 资源示例

Workflow 字段说明

Task 字段说明

Trigger 字段说明

变量引用

使用限制

常见问题

相关文档
