用途
Azure Pipelines Validator 用于验证 Azure DevOps 管道 YAML（azure-pipelines.yml / azure-pipelines.yaml）。它以本地脚本为先，只在本地输出不足时才升级到文档查询。
当用户提出以下类似请求时使用本技能：
- 「Validate my azure-pipelines.yml.」
- 「Why is this Azure pipeline YAML failing?」
- 「Run a security scan on this Azure DevOps pipeline.」
- 「Check this pipeline for best-practice issues.」
- 「Review this pipeline in CI before merge.」
不要用它从零生成流水线，那种场景应使用 azure-pipelines-generator。
路径设置（无歧义）
从任意目录使用明确的绝对路径运行：
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" SKILL_DIR="$REPO_ROOT/devops-skills-plugin/skills/azure-pipelines-validator" PIPELINE_FILE="$REPO_ROOT/azure-pipelines.yml"
如果 REPO_ROOT 为空，停止并询问仓库根路径，不要猜测路径。
校验单个文件：
bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE"
从当前目录自动探测（最多深度 3）：
bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh"
如果自动探测返回多个文件，用单个明确文件路径重新运行。
本地优先执行模型
预检
- 确认 bash 和 python3 可用。
- 确认目标文件存在。
运行本地校验器
默认完整检查：
bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE"
仅语法：
bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE" --syntax-only
仅最佳实践：
bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE" --best-practices
仅安全：
bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE" --security-only
严格模式（警告即失败）：
bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE" --strict
退出码含义
- 0：通过（或仅有非阻塞检查）
- 1：校验失败（存在阻塞问题）
- 2：无效调用（文件缺失/歧义或参数错误）
按下方报告格式返回发现的问题。
报告格式（按严重级别分桶）
始终使用以下结构返回结果：
Validation Report: <path>
Summary:
- Blocking: <count> # Syntax errors + Security critical/high
- Warning: <count> # Security medium/low + best-practice warnings
- Info: <count> # Suggestions
- Skipped: <count> # Explicitly name skipped checks
Findings:
- [Blocking][syntax][<rule-id>] line <n> - <message>
- [Blocking][security-high][<rule-id>] line <n> - <message>
- [Warning][security-medium][<rule-id>] line <n> - <message>
- [Warning][best-practice][<rule-id>] line <n> - <message>
- [Info][best-practice][<rule-id>] line <n> - <message>
Remediation:
- <short, concrete fix per finding>
Execution Notes:
- Commands run: <exact commands>
- Environment/fallback notes: <tool missing, skipped checks, offline constraints>
升级策略（仅在必要时查文档）
先运行本地检查。仅当以下任一条件成立时才升级：
- 本地发现依赖当前上游行为（任务版本、弃用、新增输入）。
- 用户询问「最新/当前/近期」的 Azure Pipelines 任务或 schema 细节。
- 本地脚本无法判定特定任务/资源语法的有效性。
升级顺序：
- 优先使用 Context7 文档工具：
mcp__context7__resolve-library-id(...) mcp__context7__query-docs(...)
- 其次是官方文档（learn.microsoft.com / Microsoft Azure DevOps 文档）。
- 仅当前两者不足时才使用通用网络搜索。
升级时需引用来源 URL，并说明本地检查无法回答的内容。
回退行为
当工具不可用时使用以下矩阵：
-
条件：yamllint 不可用。 动作：继续执行语法/最佳实践/安全检查。 报告备注：「YAML lint skipped because yamllint is unavailable.」
-
条件：python3 不可用，或 venv/依赖安装失败。 动作：标记脚本化校验受阻；仅在请求时进行手动 YAML 评审。 报告备注：「Local scripted validation blocked by missing Python runtime/dependencies.」
-
条件：需要依赖/文档时无网络。 动作：运行仍可执行的本地检查；推迟文档/版本验证。 报告备注：「External verification deferred due offline environment.」
-
条件：自动探测到多个流水线文件。 动作：不要随意选择；要求明确的单个目标文件路径。 报告备注：「Validation paused until a single target file is specified.」
规则分桶（脚本检查内容）
语法示例：
- yaml-syntax
- yaml-invalid-root
- invalid-hierarchy
- task-invalid-format
- pool-invalid
- deployment-missing-strategy
最佳实践示例：
- missing-displayname
- task-version-zero
- task-missing-version
- pool-latest-image
- missing-cache
- missing-deployment-condition
安全示例：
- hardcoded-password
- hardcoded-secret
- curl-pipe-shell
- eval-command
- insecure-ssl
- container-latest-tag
- variable-not-secret
报告中直接使用脚本输出的 rule ID。
参考与示例
- 语法参考：docs/azure-pipelines-reference.md
- 示例流水线：examples/
快速本地测试：
bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$SKILL_DIR/examples/basic-pipeline.yml"
完成标准
当以下条件全部成立时，本技能执行完成：
- 触发匹配明确，且顶部附近提供了通俗示例。
- 校验命令以无歧义路径运行。
- 报告使用严重级别分桶（Blocking、Warning、Info、Skipped）。
- 对不可用工具/环境约束明确报告回退行为。
- 仅在本地检查不足时才查阅外部文档。