/pipeline-template-module

name: pipeline-template-module
description: 处理 BK-CI 流水线模板的创建、版本管理、实例化、权限控制、PAC 模板和商店集成时使用。当用户提到模板复用、模板版本、批量实例化、模板迁移、商店模板或 PAC 模板时优先使用。

流水线模板模块

适用场景

• 创建或维护流水线模板
• 模板实例化、批量实例化、模板更新
• 模板版本、草稿、发布、分支版本管理
• PAC 模板能力
• 模板权限控制和商店模板集成

不适用场景

• 只是修改单条流水线模型结构，不涉及模板抽象
• 只是 YAML 转换问题，不涉及模板生命周期
• 只是商店插件或普通流水线执行问题

快速指导

1. 先判断你遇到的是哪条主线：

• 模板基础结构与版本体系：看 `reference/1-template-foundation.md`
• 实例化、批量操作、权限：看 `reference/2-instance-version-permission.md`
• PAC 模板与商店集成：看 `reference/3-pac-store-integration.md`
• 排查、事件、锁与扩展：看 `reference/4-operations-extension.md`

2. 模板问题先分清 V1 还是 V2。新功能判断、复杂版本管理、草稿、PAC 场景通常优先看 V2。 3. 模板和普通流水线的最大区别不是“多了一份模型”，而是多了：

• 版本语义
• 实例关联关系
• 权限与共享边界
• 可能的商店分发与 PAC 来源

4. 只要改模板结构或模板版本逻辑，就要同时检查：

• 模板资源持久化
• 实例化结果
• 版本兼容
• 模板关联流水线的更新影响

5. PAC 模板、商店模板、项目内模板不要混成一个心智模型，它们的来源、权限和版本流转不同。

高信号规则

• 模板模块负责“如何复用与分发流水线定义”，`pipeline-model-architecture` 负责“模型本身长什么样”
• 模板版本和实例版本要区分，不要把模板版本号等同于流水线运行版本
• 批量实例化、批量更新、商店安装都会放大模板设计问题，改动前要先评估实例影响面
• PAC 模板会同时受到模板体系和 YAML 转换体系影响

关键陷阱

• 不区分 V1 / V2，就直接改模板逻辑，结果改错链路
• 只改模板本身，不看已经实例化出去的流水线如何受影响
• 把 PAC 模板问题误当成普通模板问题，或反过来
• 商店模板、项目模板、公共模板混用同一套权限和版本心智
• 模板变更只验证单模板，不验证批量实例、版本切换和历史兼容

延伸阅读

• 模板基础：`reference/1-template-foundation.md`
• 实例化与版本：`reference/2-instance-version-permission.md`
• PAC 与商店：`reference/3-pac-store-integration.md`
• 排查与扩展：`reference/4-operations-extension.md`
• 涉及模型结构时：再看 `pipeline-model-architecture`
• 涉及 YAML/PAC 转换细节时：再看 `yaml-pipeline-transfer`