一、目录结构
一个标准的 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_4FROM source_schema.table_bWHERE 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_nametargets: 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 开发
·调度与触发器