azure-pipelines-generator

Azure Pipelines 生成器

生成适用于生产环境的 Azure DevOps 管道 YAML，包含确定性步骤、明确的回退方案和清晰的完成标准。

触发指南

用户要求生成或重新设计 Azure Pipelines YAML 时，使用此技能，例如：

• “为我的 Node 服务创建 azure-pipelines.yml。”
• “构建包含预发布环境和生产环境的多阶段 Azure DevOps 管道。”
• “生成可在多个仓库间复用的 Azure 管道模板。”
• “将此 CI 流程转换为 Azure Pipelines。”

仅要求验证时，不要使用此技能。仅验证的任务请使用 azure-pipelines-validator。

执行模型

规范性关键词：

• MUST：必须
• SHOULD：默认采用，除非用户另有要求
• MAY：可选

确定性执行顺序：

1. 确定请求模式。
2. 收集最低限度的必需输入。
3. 加载最低限度的参考资料（渐进式披露）。
4. 使用质量检查清单生成 YAML。
5. 验证（验证器技能、脚本回退方案或手动回退方案）。
6. 按规定的报告格式返回结果。

如果因环境限制而无法执行某个步骤，请使用该步骤中的回退方案并继续。

1）确定请求模式

选择且仅选择一种主要模式：

• 基础 CI： 为一个技术栈执行构建、测试和代码检查。
• 多阶段 CI/CD： 构建 -> 测试 -> 部署，并跟踪环境。
• Docker： 构建/推送镜像，并可选择部署。
• Kubernetes： 构建/推送镜像并部署到 Kubernetes。
• 特定语言： 专注于 .NET、Node.js、Python、Go 或 Java。
• 基于模板： 可复用模板加精简的根管道。
• 仅代码片段： 用户要求部分 YAML，而非完整管道。

模式与示例的对应关系：

• 基础 CI -> examples/basic-ci.yml
• 多阶段 CI/CD -> examples/multi-stage-cicd.yml
• .NET -> examples/dotnet-cicd.yml
• Python -> examples/python-cicd.yml
• Go -> examples/go-cicd.yml
• Kubernetes -> examples/kubernetes-deploy.yml
• 基于模板 -> examples/template-usage.yml + examples/templates/*.yml

2）收集必需输入

生成前收集以下信息：

• 应用技术栈和包管理器
• 构建/测试命令及报告要求
• 部署目标（无、Azure 服务、Docker 注册表、Kubernetes）
• 环境流程（dev/staging/prod）和分支门禁
• 服务连接、变量组、机密处理方式
• 是否需要模板

缺少信息时采用安全默认值：

• CI 分支：main、develop
• 生产部署分支：仅 main
• Agent 镜像：固定版本的镜像（例如 ubuntu-22.04）
• 部署镜像标签：不可变（$(Build.BuildId)），绝不部署 latest

如果缺少关键信息，请在最终输出中明确说明假设。

3）加载参考资料（渐进式披露）

先阅读本地参考资料。

始终阅读：

• docs/yaml-schema.md
• docs/best-practices.md

按需阅读：

• 选择任务/输入时阅读 docs/tasks-reference.md
• 仅在基于模板的模式下阅读 docs/templates-guide.md

然后仅阅读上述模式对应关系中最接近的示例。

缺少参考资料时的回退行为：

• 缺少示例：使用最接近模式的示例，并注明替代情况。
• 缺少文档章节：依据已知约定继续，并标明不确定之处。
• 仅代码片段请求：只阅读生成安全结果所需的最低限度资料。

最终回复必须包含：

• References used
• References skipped or missing
• Impact

4）升级至外部文档（仅在需要时）

仅在以下情况下查阅本地文档以外的资料：

• 本地文档未提供必需的任务信息
• 任务版本兼容性不明确
• 排查特定任务的故障

按以下顺序查阅：

1. Context7（mcp__context7__resolve-library-id -> mcp__context7__query-docs）
2. 搜索官方文档（优先 Microsoft Learn）

如果网络/工具不可用，请依据已知的本地指南继续，并添加剩余风险说明。

5) 流水线生成检查清单

除非用户要求提供精简片段，否则请应用以下所有条目。

安全性：

• 切勿将机密硬编码。
• 使用服务连接和变量组/机密。
• 使用不可变的部署镜像标签。

版本管理：

• 将 vmImage 固定为明确版本，不要使用 *-latest。
• 固定任务主版本（Task@N）。
• 仅当该任务使用主版本 0 时才允许使用 @0。

可靠性：

• 使用明确的 dependsOn。
• 为长时间运行的作业添加 timeoutInMinutes。
• 使用受分支限制的部署 condition 规则。
• 在部署阶段使用带有 environment 的部署作业。

性能：

• 在能缩短依赖项安装时间时使用 Cache@2。
• 无需完整历史记录时，使用浅层检出。
• 仅发布必需的工件。

测试/可观测性：

• 在 CI 中运行 lint/测试。
• 使用 condition: succeededOrFailed() 发布测试结果。
• 如有覆盖率数据，则发布覆盖率。

可维护性：

• 为阶段/作业/关键步骤添加 displayName。
• 在逻辑重复时使用模板。
• 仅为不明显的逻辑添加简短注释。

6) 验证工作流

默认流程（生成完整流水线时必须执行）：

1. 生成或更新 YAML。
2. 使用 azure-pipelines-validator 验证。
3. 修复检查结果。
4. 重新运行验证，直到不再有阻塞问题。

如果验证器技能不可用，但本地验证器脚本存在，则使用脚本作为备用方案：

bash devops-skills-plugin/skills/azure-pipelines-validator/scripts/validate_azure_pipelines.sh <pipeline-file>

如果技能和脚本都无法运行，则使用手动备用方案：

1. 检查 YAML 结构/缩进是否合理
2. 检查层级是否合理（stages -> jobs -> steps）
3. 检查任务格式是否合理（Task@Major）
4. 扫描是否暴露机密（不得包含明文凭据/令牌）
5. 扫描部署安全性（environment 用法、不可变部署标签）

使用备用方案时，最终回复必须包含：

• Validation status: Manual fallback
• Checks performed
• Residual risk

仅在以下情况下可以跳过验证：

• 仅生成 YAML 片段
• 仅提供文档示例
• 用户明确要求跳过验证

7) 输出约定

最终回复必须包含：

1. 流水线 YAML（或模板集合）
2. 所需设置：
   • 服务连接
   • 变量组/机密
   • 环境和审批/检查
3. 验证结果：
   • 验证器状态、脚本状态或手动备用方案状态
4. 假设
5. 使用/跳过的参考资料及其影响
6. 可选的后续改进

8) 标准示例流程

示例 A：生成完整的多阶段流水线

1. 选择模式：多阶段 CI/CD。
2. 收集技术栈/部署/服务连接相关输入。
3. 阅读 docs/yaml-schema.md、docs/best-practices.md 和 examples/multi-stage-cicd.yml。
4. 添加用户要求的自定义项（阶段、分支限制、环境、任务）。
5. 使用 azure-pipelines-validator 验证；修复后重新运行。
6. 返回 YAML + 设置 + 验证 + 假设 + 参考资料。

示例 B：快速生成片段

1. 选择模式：仅生成片段。
2. 仅阅读所需的最少参考章节。
3. 使用安全默认值生成针对性的 YAML 片段。
4. 跳过完整验证，并注明 Validation status: Skipped (snippet-only)。
5. 返回片段 + 假设 + 参考资料。

9) 完成定义

只有在所有适用检查均通过后，执行才算完成：

• 已明确选择请求模式。
• 对缺失输入的假设已明确说明。
• YAML 符合检查清单要求（安全性、版本管理、可靠性、性能、可维护性）。
• 已记录验证流程（验证器、脚本备用方案或手动备用方案）。
• 最终回复符合输出约定，包括参考资料及其影响。