---
name: yaml-pipeline-transfer
description: 处理 BK-CI YAML 流水线导入导出、YAML 与 Model 双向转换、PAC、模板引用与 YAML 校验时使用。当用户提到 YAML 流水线、PAC、模板化、注释保留、表达式解析或转换调试时优先使用。
---

# YAML 流水线转换

## 适用场景

- YAML 导入为流水线模型
- 流水线模型导出为 YAML
- PAC（Pipeline as Code）接入与同步
- YAML 模板、Step/Job/Stage 模板引用
- YAML 语法、表达式、注释保留、锚点处理相关问题

## 不适用场景

- 只是单纯修改流水线模型结构，不涉及 YAML 表达
- 只是代码库接入、权限、数据库或执行调度问题
- 只是某个插件运行逻辑，而不是 YAML 到模型的转换问题

## 快速指导

1. 先判断问题属于哪一类，再继续读对应参考文档：
   - 转换主链路：`reference/1-transfer-flow.md`
   - PAC 与模板：`reference/2-pac-template.md`
   - 表达式、切面、调试与扩展：`reference/3-debug-extension.md`
2. YAML 转换问题通常不是单点问题，要区分：
   - YAML 文本解析
   - YAML 数据模型
   - YAML 到 `Model`
   - `Model` 到 YAML
   - 模板展开与 PAC 预处理
3. 只要改 YAML 字段或结构，就要同时考虑：
   - `Model` 映射
   - 兼容旧 YAML
   - 导入与导出双向一致性
   - 模板引用和表达式是否受影响
4. PAC、模板、表达式、切面经常彼此叠加，不要把它们当成完全独立的模块。
5. 如果问题是“转换后执行不对”，先确认是 YAML 转换层问题，还是 `process-module-architecture` 的执行链放大了问题。

## 高信号规则

- `yaml-pipeline-transfer` 负责“YAML 如何表示和转换”，`pipeline-model-architecture` 负责“模型长什么样”
- `TransferMapper` 解决序列化、格式化、注释和锚点等文本层问题
- `ModelTransfer` 更偏 YAML 与 `Model` 的业务转换
- 模板、PAC、表达式和切面属于转换前后会共同影响结果的增强层
- 改动 YAML 相关能力时，要始终以“双向一致”和“历史兼容”为目标

## 关键陷阱

- 只修 `yaml2Model`，不修 `model2Yaml`，导致导入导出不对称
- 只验证普通 YAML，不验证模板、PAC、注释保留和锚点场景
- 把模型字段问题误判为 YAML 解析问题，或反过来
- 忽略切面、表达式、模板预处理对最终结果的影响
- 修改转换规则后，没有回归历史 YAML 和已有模板

## 延伸阅读

- 转换主链路：`reference/1-transfer-flow.md`
- PAC 与模板：`reference/2-pac-template.md`
- 调试与扩展：`reference/3-debug-extension.md`
- 涉及模型结构时：再看 `pipeline-model-architecture`
- 涉及执行链路归属时：再看 `process-module-architecture`