用途：帮助理解或修改 BK-CI 流水线模型架构，适用于梳理 Model -> Stage -> Container -> Element 层级关系、修改模型字段与校验逻辑、新增容器或插件类型、排查序列化与版本兼容及 YAML 转换问题，以及判断需求应落在模型定义、运行时状态还是持久化层。
主要能力：按结构定义、持久化与版本、运行时转换与扩展三类问题提供参考文档指引。核心要点包括：Model 是流水线配置的核心载体，但并非所有运行时状态的权威来源，需区分配置态与运行态；触发容器是模型入口，默认位于第一个 Stage 的第一个 Container；Container 与 Element 均为多态结构，新增类型时需同时检查 Jackson 多态序列化配置、前端编排模型、后端转换与校验、运行引擎或 Worker 识别逻辑；版本兼容与 YAML 转换需一并考虑存量数据。
使用方式：先判断问题归属类别，再查阅对应参考文档（reference/1-core-structure.md、reference/2-persistence-versioning.md、reference/3-runtime-conversion-extension.md）。涉及执行链路归属时参考 process-module-architecture，涉及 YAML/PAC 时参考 yaml-pipeline-transfer。
适用场景：模型结构理解与修改、模型扩展与校验、版本兼容与 YAML 转换排查。不适用场景：仅调度资源分配、构建机执行或插件运行问题；普通后端接口开发；不涉及模型结构的数据库脚本设计。
限制与陷阱：避免把运行时字段当作持久化配置字段修改；新增类型不能只改类定义；需注意 Finally、Matrix、运行条件等特殊结构；验证时不能只看 UI 新建流程，还要覆盖历史 Model 回放、重试、版本切换与 YAML 转换。