/pipeline-model-architecture

name: pipeline-model-architecture
description: 理解或修改 BK-CI 流水线 Model、Stage、Container、Element 结构时使用。当用户提到流水线模型、Stage/Job/Task 数据结构、模型扩展、模型校验、版本兼容、YAML 与 Model 转换时优先使用。

BK-CI 流水线模型架构

适用场景

• 理解 `Model -> Stage -> Container -> Element` 的层级关系
• 修改流水线模型字段、结构或校验逻辑
• 新增容器类型、插件类型或模型辅助结构
• 排查模型序列化、版本兼容、YAML 转换问题
• 判断一个需求应该落在模型定义、运行时状态还是持久化层

不适用场景

• 只是调度资源分配、构建机执行或插件运行问题
• 只是普通后端接口开发，不涉及流水线模型本身
• 只是数据库脚本设计，不涉及模型结构和模型存储

快速指导

1. 先把问题归到下面 5 类之一，再继续读对应参考文档：

• 结构定义：看 `reference/1-core-structure.md`
• 持久化与版本：看 `reference/2-persistence-versioning.md`
• 运行时、YAML、校验、扩展：看 `reference/3-runtime-conversion-extension.md`

2. `Model` 是流水线配置的核心载体，但不是所有运行时状态的权威来源。运行中的状态、耗时、重试等字段要区分“配置态”和“运行态”。 3. 触发容器是模型入口，默认位于第一个 `Stage` 的第一个 `Container`。很多参数、触发器和启动逻辑都从这里进入。 4. `Container` 和 `Element` 都是多态结构。新增类型时，不能只改一个类定义，通常还要一起检查：

• Jackson 多态序列化配置
• 前端编排模型
• 后端转换与校验
• 运行引擎或 Worker 识别逻辑

5. 版本兼容和 YAML 转换要一起考虑。模型字段一旦进入存量数据，就不能只从“当前新建流程”角度看。 6. 如果你修改的是流程控制、执行条件、Finally、Matrix 之类能力，优先确认它影响的是 Stage、Job 还是 Element 层。

高信号规则

• `Model` 关心的是“流水线如何定义”，`Process` 更关心“流水线如何被编排执行”
• `Stage` 表达阶段边界和流程控制，`Container` 更接近 Job，`Element` 更接近具体任务或插件
• `id`、`stageIdForUser`、插件 code、运行时状态字段，不是同一层次的概念，不能混用
• 只要涉及模型新增字段，就要同时检查序列化、兼容、默认值和历史版本读取

关键陷阱

• 把运行时字段直接当成持久化配置字段来修改，导致旧构建详情或历史快照异常
• 只改 `Element`/`Container` 类定义，不补多态声明、校验或前端侧映射
• 忽略 Finally、Matrix、运行条件这些特殊结构，按普通 Stage/Job 处理
• 只验证 UI 新建流程，没验证历史 Model 回放、重试、版本切换和 YAML 转换
• 看到问题出现在模型字段，就直接改模型，实际上问题可能在 `Process` 的执行链或转换层

延伸阅读

• 核心结构：`reference/1-core-structure.md`
• 持久化与版本：`reference/2-persistence-versioning.md`
• 运行时、转换与扩展：`reference/3-runtime-conversion-extension.md`
• 涉及执行链路归属时：先看 `process-module-architecture`
• 涉及 YAML/PAC 时：再看 `yaml-pipeline-transfer`