yaml-pipeline-transfer

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