{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://www.anguskit.com/schema/anguscicd/pipeline-v1.zh-CN.json",
  "title": "AngusCICD Pipeline Configuration",
  "description": "AngusCICD 流水线 YAML 配置 JSON Schema（中文本地化变体；英文默认见 anguscicd-pipeline-v1.json）。权威来源由 xcan-anguscicd.spec 模块维护（与 spec 模型保持一致），供 Monaco Editor 自动补全/校验及服务端共用。多词字段同时支持驼峰与连字符两种写法（由 FluentPropertyUtils 注册别名），如 fail-fast≡failFast、max-parallel≡maxParallel、continue-on-error≡continueOnError；条件字段 if≡condition。复合 Action（step.uses 引用的 action.yml）的结构内联于 definitions.ActionConfig（含 ActionInput / ActionRuns，子步骤复用 StepConfig）。",
  "type": "object",
  "required": [
    "name",
    "pipeline"
  ],
  "additionalProperties": false,
  "properties": {
    "version": {
      "type": "string",
      "description": "Schema 版本号",
      "enum": [
        "1",
        "1.0"
      ],
      "default": "1"
    },
    "name": {
      "type": "string",
      "description": "流水线名称",
      "minLength": 1,
      "maxLength": 200
    },
    "checkContext": {
      "type": "string",
      "description": "回写到 PR Checks 的名称，须与分支保护 requiredStatusCheckContexts 精确一致。缺省为流水线实体名。",
      "minLength": 1,
      "maxLength": 200
    },
    "check-context": {
      "type": "string",
      "description": "checkContext 的连字符别名",
      "minLength": 1,
      "maxLength": 200
    },
    "env": {
      "type": "object",
      "description": "流水线级别环境变量，所有 Job 继承（可被 Job 级 env 覆盖）",
      "additionalProperties": {
        "type": "string"
      }
    },
    "triggers": {
      "type": "array",
      "description": "触发器配置列表",
      "items": {
        "$ref": "#/definitions/TriggerConfig"
      }
    },
    "smart": {
      "$ref": "#/definitions/SmartConfig"
    },
    "permissions": {
      "type": "object",
      "description": "流水线令牌权限声明。key 为作用域（如 contents / packages / pull-requests），value 为 read/write/none。",
      "additionalProperties": {
        "type": "string",
        "enum": [
          "read",
          "write",
          "none"
        ]
      }
    },
    "concurrency": {
      "$ref": "#/definitions/ConcurrencyConfig"
    },
    "pipeline": {
      "type": "object",
      "description": "Job 定义，key 为 Job 名称",
      "minProperties": 1,
      "additionalProperties": {
        "$ref": "#/definitions/JobConfig"
      }
    }
  },
  "definitions": {
    "TriggerConfig": {
      "type": "object",
      "description": "触发器配置",
      "properties": {
        "on": {
          "type": "string",
          "description": "触发事件类型",
          "enum": [
            "push",
            "pull_request",
            "tag",
            "schedule",
            "workflow_dispatch",
            "webhook",
            "manual"
          ]
        },
        "branches": {
          "type": "array",
          "description": "触发分支模式列表（支持 glob 通配符）",
          "items": {
            "type": "string"
          }
        },
        "paths": {
          "type": "array",
          "description": "触发路径过滤（只有匹配路径的变更才触发）",
          "items": {
            "type": "string"
          }
        },
        "cron": {
          "type": "string",
          "description": "Cron 表达式（仅 on=schedule 时有效）",
          "pattern": "^[0-9*/,-]+\\s+[0-9*/,-]+\\s+[0-9*/,-]+\\s+[0-9*/,-]+\\s+[0-9*/,-]+$"
        },
        "inputs": {
          "type": "array",
          "description": "手动触发参数定义（仅 on=workflow_dispatch 时有效）",
          "items": {
            "$ref": "#/definitions/WorkflowDispatchInput"
          }
        },
        "events": {
          "type": "array",
          "description": "Webhook 事件类型过滤（仅 on=webhook 时有效）。为空表示接受任意入站事件。",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "on"
      ]
    },
    "ConcurrencyConfig": {
      "type": "object",
      "description": "并发组：同组至多一个进行中的运行。cancel-in-progress=true 时新运行取消旧运行。",
      "required": [
        "group"
      ],
      "properties": {
        "group": {
          "type": "string",
          "description": "并发组标识。支持 ${{ }} 模板（如按分支分组）。",
          "minLength": 1,
          "maxLength": 500
        },
        "cancelInProgress": {
          "type": "boolean",
          "description": "为 true 时新运行会取消同组进行中的旧运行",
          "default": false
        },
        "cancel-in-progress": {
          "type": "boolean",
          "description": "cancelInProgress 的连字符别名",
          "default": false
        }
      }
    },
    "WorkflowDispatchInput": {
      "type": "object",
      "description": "手动触发输入参数",
      "required": [
        "name",
        "type"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "参数名称"
        },
        "type": {
          "type": "string",
          "description": "参数类型",
          "enum": [
            "string",
            "boolean",
            "choice",
            "number"
          ]
        },
        "required": {
          "type": "boolean",
          "description": "是否必填",
          "default": false
        },
        "default": {
          "type": "string",
          "description": "默认值"
        },
        "description": {
          "type": "string",
          "description": "参数说明"
        },
        "options": {
          "type": "array",
          "description": "可选值列表（type=choice 时使用）",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "SmartConfig": {
      "type": "object",
      "description": "智能功能配置",
      "properties": {
        "changeAnalysis": {
          "type": "boolean",
          "description": "启用 Monorepo 变更影响分析，仅执行受影响模块的 Job",
          "default": false
        },
        "cacheStrategy": {
          "type": "string",
          "description": "缓存策略",
          "enum": [
            "aggressive",
            "normal",
            "minimal",
            "none"
          ],
          "default": "normal"
        },
        "predictiveScaling": {
          "type": "boolean",
          "description": "实验字段：预测性 Runner 弹性伸缩。调度器尚未消费，写入无运行时效果。",
          "default": false
        }
      }
    },
    "JobConfig": {
      "type": "object",
      "description": "Job 配置。steps 与 uses（workflow_call）二选一，不能同时声明。",
      "properties": {
        "runner": {
          "$ref": "#/definitions/RunnerConfig"
        },
        "steps": {
          "type": "array",
          "description": "Step 列表（按顺序执行）。未声明 uses 时必填。",
          "minItems": 1,
          "maxItems": 50,
          "items": {
            "$ref": "#/definitions/StepConfig"
          }
        },
        "uses": {
          "type": "string",
          "description": "可复用工作流引用（workflow_call）：./.anguscicd/deploy.yml 或流水线名称。声明后不得再写 steps。"
        },
        "with": {
          "type": "object",
          "description": "传递给可复用工作流的输入（仅 uses 时有效）",
          "additionalProperties": {
            "type": "string"
          }
        },
        "needs": {
          "type": "array",
          "description": "依赖的 Job 名称列表（DAG 依赖）",
          "items": {
            "type": "string"
          }
        },
        "parallel": {
          "type": "boolean",
          "description": "是否允许与其他无依赖 Job 并行执行",
          "default": true
        },
        "continueOnError": {
          "type": "boolean",
          "description": "该 Job 失败时是否继续执行后续 Job（亦可写 continue-on-error）",
          "default": false
        },
        "continue-on-error": {
          "type": "boolean",
          "description": "continueOnError 的连字符别名",
          "default": false
        },
        "if": {
          "type": "string",
          "description": "Job 级条件执行表达式（JEXL，condition 的别名）。为 false 时该 Job 标记为 SKIPPED。权威模板写法为 ${{ ... }}（仍兼容旧式 {{ ... }}，但不推荐），可省略包裹。支持基于上游 needs 的状态函数 always()/success()/failure()/cancelled() 与 needs.<job>.result。注意：一旦指定 if 即覆盖隐式 success() 守卫（上游失败时该 Job 仍会被调度，由本表达式独立决定运行或跳过）。"
        },
        "condition": {
          "type": "string",
          "description": "Job 级条件执行表达式（JEXL，等价于 if）"
        },
        "secrets": {
          "type": "array",
          "description": "声明需要注入的 Secret 名单（最小权限：仅注入名单内的 Secret）",
          "items": {
            "type": "string"
          }
        },
        "environment": {
          "type": "string",
          "description": "部署环境名称标签（如 staging, production）。不是 GitHub Environment：无保护规则、等待计时或自动审批。需要门禁请单独写 approval:"
        },
        "env": {
          "type": "object",
          "description": "Job 级别环境变量",
          "additionalProperties": {
            "type": "string"
          }
        },
        "cache": {
          "type": "array",
          "description": "缓存配置列表",
          "items": {
            "$ref": "#/definitions/CacheConfig"
          }
        },
        "strategy": {
          "$ref": "#/definitions/MatrixConfig"
        },
        "services": {
          "type": "object",
          "description": "服务容器配置（sidecar），key=服务名",
          "additionalProperties": {
            "$ref": "#/definitions/ServiceContainerConfig"
          }
        },
        "canaryWeight": {
          "type": "integer",
          "description": "金丝雀权重（0-100）。脚本约定：平台只校验范围，不按此切流。",
          "minimum": 0,
          "maximum": 100
        },
        "approval": {
          "$ref": "#/definitions/ApprovalConfig"
        },
        "modules": {
          "type": "array",
          "description": "变更影响分析关联的模块路径前缀（smart.changeAnalysis=true 时生效）",
          "items": {
            "type": "string"
          }
        },
        "outputs": {
          "type": "object",
          "description": "Job 级输出，供下游 Job 通过 needs.<job>.outputs.<key> 引用。每个值为模板表达式，在 Job 成功后解析，例如 ${{ steps.<step-id>.outputs.<key> }}",
          "additionalProperties": {
            "type": "string"
          }
        }
      },
      "oneOf": [
        {
          "required": [
            "steps"
          ],
          "not": {
            "required": [
              "uses"
            ]
          }
        },
        {
          "required": [
            "uses"
          ],
          "not": {
            "required": [
              "steps"
            ]
          }
        }
      ]
    },
    "StepConfig": {
      "type": "object",
      "description": "Step 配置",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Step 名称",
          "minLength": 1
        },
        "id": {
          "type": "string",
          "description": "Step 逻辑 id，用于在 Job 级 outputs 中引用该 Step 的输出（steps.<id>.outputs.<key>）"
        },
        "run": {
          "type": "string",
          "description": "Shell 命令（与 uses 二选一）"
        },
        "uses": {
          "type": "string",
          "description": "引用的 Action（与 run 二选一），格式: owner/repo@version 或 ./local/path"
        },
        "with": {
          "type": "object",
          "description": "传递给 Action 的参数（uses 时有效）",
          "additionalProperties": {
            "type": "string"
          }
        },
        "env": {
          "type": "object",
          "description": "Step 级别环境变量",
          "additionalProperties": {
            "type": "string"
          }
        },
        "timeout": {
          "type": "integer",
          "description": "Step 超时时间（秒）",
          "minimum": 1,
          "maximum": 86400
        },
        "shell": {
          "type": "string",
          "description": "run 使用的 Shell（bash/sh/pwsh/powershell/cmd），缺省由平台决定",
          "enum": [
            "bash",
            "sh",
            "pwsh",
            "powershell",
            "cmd"
          ]
        },
        "workingDirectory": {
          "type": "string",
          "description": "相对 Job 工作区的工作目录（也接受连字符写法 working-directory）"
        },
        "working-directory": {
          "type": "string",
          "description": "workingDirectory 的连字符别名"
        },
        "continueOnError": {
          "type": "boolean",
          "description": "为 true 时该 Step 失败不拖垮 Job（也接受 continue-on-error）",
          "default": false
        },
        "continue-on-error": {
          "type": "boolean",
          "description": "continueOnError 的连字符别名",
          "default": false
        },
        "retry": {
          "type": "integer",
          "description": "Step 失败后的额外重试次数（0=不重试）",
          "minimum": 0,
          "maximum": 10
        },
        "if": {
          "type": "string",
          "description": "Step 级条件执行表达式（JEXL；if 为 condition 的别名）。在 Runner 端、该 Step 执行前求值：为 false 时该 Step 标记 SKIPPED 并继续后续 Step。权威模板语法为 ${{ ... }}（旧式 {{ ... }} 仍兼容但不推荐），包裹可省略。支持 always()/success()/failure()/cancelled() 状态函数。未声明时仅在此前 Step 全部成功时执行（隐式 success() 门控）。"
        },
        "condition": {
          "type": "string",
          "description": "Step 级条件执行表达式（JEXL；等价于 if）"
        }
      },
      "oneOf": [
        {
          "required": [
            "run"
          ]
        },
        {
          "required": [
            "uses"
          ]
        }
      ]
    },
    "RunnerConfig": {
      "type": "object",
      "description": "Runner 配置",
      "properties": {
        "mode": {
          "type": "string",
          "description": "Runner 执行模式",
          "enum": [
            "DOCKER",
            "NATIVE"
          ]
        },
        "image": {
          "type": "string",
          "description": "Docker 镜像（mode=DOCKER 时必填）"
        },
        "executor": {
          "type": "string",
          "description": "执行器类型"
        },
        "labels": {
          "type": "array",
          "description": "Runner 标签匹配（调度到具有这些标签的 Runner）",
          "items": {
            "type": "string"
          }
        },
        "resources": {
          "$ref": "#/definitions/ResourceConfig"
        }
      }
    },
    "ResourceConfig": {
      "type": "object",
      "description": "资源限制配置",
      "properties": {
        "cpu": {
          "type": "integer",
          "description": "CPU 核数",
          "minimum": 1
        },
        "memory": {
          "type": "integer",
          "description": "内存（MB）",
          "minimum": 128
        },
        "disk": {
          "type": "string",
          "description": "磁盘空间（如 10G）"
        },
        "timeout": {
          "type": "integer",
          "description": "Job 级别超时（秒）",
          "minimum": 1
        }
      }
    },
    "CacheConfig": {
      "type": "object",
      "description": "缓存配置",
      "required": [
        "key",
        "paths"
      ],
      "properties": {
        "key": {
          "type": "string",
          "description": "缓存 key（支持 ${{ }} 变量替换）"
        },
        "paths": {
          "type": "array",
          "description": "需要缓存的文件路径列表",
          "items": {
            "type": "string"
          },
          "minItems": 1
        }
      }
    },
    "MatrixConfig": {
      "type": "object",
      "description": "矩阵策略配置：自动展开为多个 Job 实例",
      "properties": {
        "matrix": {
          "type": "object",
          "description": "矩阵维度定义，key=变量名，value=值列表",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "fail-fast": {
          "type": "boolean",
          "description": "某个矩阵 Job 失败后是否立即取消其他组合（亦可写 failFast）",
          "default": true
        },
        "failFast": {
          "type": "boolean",
          "description": "fail-fast 的驼峰别名",
          "default": true
        },
        "max-parallel": {
          "type": "integer",
          "description": "最大并行矩阵 Job 数（亦可写 maxParallel）",
          "minimum": 1
        },
        "maxParallel": {
          "type": "integer",
          "description": "max-parallel 的驼峰别名",
          "minimum": 1
        },
        "exclude": {
          "type": "array",
          "description": "排除的矩阵组合",
          "items": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "include": {
          "type": "array",
          "description": "额外追加的矩阵组合",
          "items": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      }
    },
    "ServiceContainerConfig": {
      "type": "object",
      "description": "服务容器配置（sidecar）",
      "required": [
        "image"
      ],
      "properties": {
        "image": {
          "type": "string",
          "description": "Docker 镜像（必填）"
        },
        "env": {
          "type": "object",
          "description": "环境变量",
          "additionalProperties": {
            "type": "string"
          }
        },
        "ports": {
          "type": "array",
          "description": "端口映射列表（格式: hostPort:containerPort）",
          "items": {
            "type": "string"
          }
        },
        "command": {
          "type": "string",
          "description": "自定义启动命令"
        },
        "healthCheck": {
          "type": "string",
          "description": "健康检查命令"
        },
        "healthCheckTimeout": {
          "type": "integer",
          "description": "健康检查超时秒数",
          "default": 60,
          "minimum": 1
        }
      }
    },
    "ApprovalConfig": {
      "type": "object",
      "description": "人工审批配置",
      "properties": {
        "required": {
          "type": "boolean",
          "description": "是否需要审批"
        },
        "approvers": {
          "type": "array",
          "description": "审批人用户 ID 列表",
          "items": {
            "type": "integer"
          }
        },
        "timeout": {
          "type": "integer",
          "description": "审批超时时间（秒）",
          "default": 3600
        },
        "policy": {
          "type": "string",
          "description": "YAML 审批策略：any / all / quorum",
          "enum": [
            "any",
            "all",
            "quorum"
          ],
          "default": "any"
        },
        "requiredApprovals": {
          "type": "integer",
          "description": "法定人数阈值（仅 policy=quorum 时生效）",
          "minimum": 1
        }
      }
    },
    "ActionConfig": {
      "type": "object",
      "description": "复合 Action 定义（被流水线 step.uses 引用的 action.yml）。采用 GitHub Actions 标准 composite 写法（runs.using: composite + runs.steps），不支持顶层 type/run 兼容字段。与 spec 的 ActionConfig 模型保持一致。",
      "required": [
        "name",
        "runs"
      ],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "Action 名称",
          "minLength": 1,
          "maxLength": 200
        },
        "description": {
          "type": "string",
          "description": "Action 描述",
          "maxLength": 1024
        },
        "inputs": {
          "type": "object",
          "description": "输入参数定义，key=输入名",
          "additionalProperties": {
            "$ref": "#/definitions/ActionInput"
          }
        },
        "runs": {
          "$ref": "#/definitions/ActionRuns"
        }
      }
    },
    "ActionInput": {
      "type": "object",
      "description": "复合 Action 输入参数定义",
      "additionalProperties": false,
      "properties": {
        "description": {
          "type": "string",
          "description": "参数说明"
        },
        "required": {
          "type": "boolean",
          "description": "是否必填",
          "default": false
        },
        "default": {
          "type": "string",
          "description": "默认值（未由调用方 with 提供时使用）"
        }
      }
    },
    "ActionRuns": {
      "type": "object",
      "description": "复合 Action 执行定义（using + steps），steps 复用本 Schema 的 StepConfig 定义",
      "required": [
        "steps"
      ],
      "properties": {
        "using": {
          "type": "string",
          "description": "执行类型，复合 Action 固定为 composite",
          "default": "composite"
        },
        "steps": {
          "type": "array",
          "description": "组成该复合 Action 的子步骤列表（按顺序执行，子步骤可再引用其它 Action）",
          "minItems": 1,
          "items": {
            "$ref": "#/definitions/StepConfig"
          }
        }
      }
    }
  }
}