Devops Pipeline Management

Expert for DevOps pipeline management, handling the complete lifecycle of pipelines on the quality and efficiency platform. Core capabilities: 1) Workspace management - Query workspace lists with filtering 2) Pipeline management - Create, query, update, and delete pipelines 3) Execution management - Execute and cancel pipelines, query execution records and details 4) Template management - Query pipeline templates and create pipelines from templates Trigger scenarios: - Users need to search for workspaces or pipelines - Users need to execute or run pipelines - Users need to check pipeline execution status or logs - Users need to create, update, or delete pipelines - Users need to query pipeline templates

# DevOps Pipeline Management Skill

## 概述

此 Skill 是 DevOps 质效平台的流水线管理专家，通过 OpenAPI 接口实现流水线的全生命周期管理。

**核心能力**：
- **工作空间管理**：查询工作空间列表，支持按名称、组织、产品线筛选
- **流水线管理**：创建、查询、更新、删除流水线，支持基于模板快速创建
- **执行管理**：执行流水线（支持交互式/非交互式模式）、取消执行、查询执行记录和详情
- **模板管理**：查询流水线模板列表，支持按名称、类型、语言筛选，用于快速创建流水线

**技术栈**：Python 3.8+、Requests、RESTful API

---

# ⚠️ 全局执行约束（强制执行）

> **执行任何子功能时，必须严格参考对应子功能文档。子功能文档即执行规范，禁止跳过、合并或自行发挥。**

## 核心原则

**子功能文档 = 执行规范 = 法律效力**

| 阶段 | 要求 |
|------|------|
| **执行前** | 必须先阅读对应子功能文档 |
| **执行中** | 必须按文档定义的步骤顺序执行 |
| **执行后** | 必须满足文档中的约束条件 |

**严格禁止的行为**：
- ✗ 不读文档直接执行
- ✗ 跳过或调换步骤执行
- ✗ 合并多个步骤为一步
- ✗ 自行实现功能而不调用对应Skill

## 全局约束清单

| 约束类型 | 约束说明 | 违反后果 |
|---------|---------|---------|
| **文档强制参考** | 执行子功能前必须阅读对应子功能文档 | 流程错误、操作失效 |
| **步骤顺序** | 子功能文档中定义的步骤必须按顺序执行，不得跳过、调换或合并 | 数据不完整、执行失败 |
| **配置预览** | 步骤中明确要求"预览"或"确认"的，必须执行该步骤后再继续 | 配置错误、无法追溯 |
| **必填校验** | 必填字段（文档中标记 ✅ 或"必填"）不能为空或空数组 | API调用失败 |
| **ID生成** | 新建实体时必须生成新的UUID，禁止复用已有ID | 数据冲突、覆盖问题 |
| **API调用** | 必须使用文档中指定的API接口，禁止自行调用其他接口 | 权限错误、功能异常 |
| **跨Skill调用** | 需要执行其他Skill功能时（如执行流水线），必须调用对应Skill | 流程中断、功能缺失 |

## 子功能文档（强制参考）

> **每个子功能都有专属文档，执行时必须严格参考对应文档**

### 流水线核心操作
| 子功能 | 文档路径 | 核心约束 |
|--------|---------|---------|
| 创建流水线 | [references/pipeline-create.md](references/pipeline-create.md) | **9步骤顺序**、配置预览(C7)必执行、调用pipeline-run skill |
| 更新流水线 | [references/pipeline-update.md](references/pipeline-update.md) | **6步骤顺序**、保留原pipelineId、ID保留 |
| 执行流水线 | [references/pipeline-run.md](references/pipeline-run.md) | taskDataList非空、参数组装、交互式/非交互式模式 |

### 任务节点管理
| 子功能 | 文档路径 | 核心约束 |
|--------|---------|---------|
| 添加任务节点 | [references/pipeline-task-add.md](references/pipeline-task-add.md) | 前置检查、ID生成、统一保存 |
| 更新任务节点 | [references/pipeline-task-update.md](references/pipeline-task-update.md) | 先查询、保留ID、字段合并 |
| 删除任务节点 | [references/pipeline-task-delete.md](references/pipeline-task-delete.md) | 前置确认、双重移除、依赖检查 |

### 查询与监控
| 子功能 | 文档路径 | 核心约束 |
|--------|---------|---------|
| 查询工作空间 | [references/workspace-list.md](references/workspace-list.md) | 分页参数、筛选条件 |
| 查询流水线列表 | [references/pipeline-page.md](references/pipeline-page.md) | 分页参数、排序规则 |
| 查询模板 | [references/pipeline-template.md](references/pipeline-template.md) | 语言筛选、类型筛选 |
| 查询执行记录 | [references/pipeline-list.md](references/pipeline-list.md) | 分页查询、状态筛选 |
| 查询执行详情 | [references/pipeline-run-detail.md](references/pipeline-run-detail.md) | 日志ID校验 |
| 流水线详情查询 | [references/pipeline-detail.md](references/pipeline-detail.md) | pipelineId校验 |

### 其他操作
| 子功能 | 文档路径 | 核心约束 |
|--------|---------|---------|
| 删除流水线 | [references/pipeline-delete.md](references/pipeline-delete.md) | 删除确认、不可恢复 |
| 取消执行 | [references/pipeline-cancel.md](references/pipeline-cancel.md) | 仅限执行中状态 |

## 约束示例

### ✅ 正确做法
- 执行"创建流水线" → **先阅读** [pipeline-create.md](references/pipeline-create.md) → **按9步骤执行**
- 执行"执行流水线" → **先阅读** [pipeline-run.md](references/pipeline-run.md) → **组装taskDataList**
- 步骤要求预览 → **展示预览**后再继续
- 需要执行流水线 → **调用** `pipeline-run` skill

### ❌ 错误做法（禁止）
- 不读文档直接执行
- 跳过配置预览步骤
- 自行实现 pipeline-run 功能而不调用 skill
- 合并多个步骤为一步
- 使用空数组作为 taskDataList
- 跳过必填字段校验

# DevOps Pipeline Management Skill

## 概述

此 Skill 是 DevOps 质效平台的流水线管理专家，通过 OpenAPI 接口实现流水线的全生命周期管理。

**核心能力**：
- **工作空间管理**：查询工作空间列表，支持按名称、组织、产品线筛选
- **流水线管理**：创建、查询、更新、删除流水线，支持基于模板快速创建
- **执行管理**：执行流水线（支持交互式/非交互式模式）、取消执行、查询执行记录和详情
- **模板管理**：查询流水线模板列表，支持按名称、类型、语言筛选，用于快速创建流水线

**技术栈**：Python 3.8+、Requests、RESTful API

## 环境准备

### 1. 系统要求

- Python 3.8+
- 网络可访问 DevOps 平台 API

### 2. 依赖安装

```bash
pip install requests
```

或使用 requirements.txt：

```bash
pip install -r requirements.txt
```

### 3. 获取 API 凭证

联系平台管理员获取以下凭证：

| 凭证 | 说明 |
|------|------|
| Domain Account | 域账号，用于权限校验和审计 |

## 环境变量配置

### 环境变量说明

| 变量名 | 必填 | 说明 |
|-------|-----|------|
| DEVOPS_DOMAIN_ACCOUNT | 是 | 域账号，用于权限校验和审计 |
| DEVOPS_BFF_URL | 是 | BFF 服务地址 |
| INTERACTIVE_MODE | 否 | 交互模式开关（默认：true）。true 时执行流水线会询问是否交互式选择分支/标签/版本 |

### 必填环境变量

```bash
# 域账号（必填）
export DEVOPS_DOMAIN_ACCOUNT="your_domain_account"

# BFF 服务地址（必填）
export DEVOPS_BFF_URL="https://one-dev.iflytek.com/devops"
```

### 可选环境变量

```bash
# 交互模式开关（默认：true）
# true: 执行流水线时询问是否交互式选择分支/标签/版本
# false: 自动使用最近执行记录填充，不询问
export INTERACTIVE_MODE="true"
```

### 持久化配置

将环境变量添加到 shell 配置文件（如 `~/.zshrc` 或 `~/.bashrc`）：

```bash
# DevOps Pipeline Skill 配置
export DEVOPS_DOMAIN_ACCOUNT="your_domain_account"
export DEVOPS_BFF_URL="https://one-dev.iflytek.com/devops"
export INTERACTIVE_MODE="true"  # 启用交互式选择功能
```

然后执行：

```bash
source ~/.zshrc  # 或 source ~/.bashrc
```

## 安装

### 方式一：直接使用

```bash
cd devops-skills/pipeline-management
python -m scripts/main --help
```

### 方式二：添加到 PATH（可选）

```bash
# 添加软链接（可选：使用 devops-pipeline 作为命令名）
sudo ln -s $(pwd)/scripts/main.py /usr/local/bin/devops-pipeline

# 使用
devops-pipeline --help      # 需要创建符号链接
```

> **说明**：文档中的命令示例统一使用 `python -m scripts/main` 作为入口命令。如需简化命令，可创建符号链接。

## 快速开始

### 1. 验证配置

```bash
python -m scripts/main
```

### 2. 查询工作空间

```bash
python -m scripts/main workspaces --name devops
```

### 3. 查询流水线列表

```bash
python -m scripts/main pipelines <space_id>
```

### 4. 执行流水线

```bash
python -m scripts/main run <pipeline_id>
```

## 典型工作流程

### 流程一：查找并执行流水线

```
1. workspaces          → 获取工作空间列表，找到目标空间ID
2. pipelines <spaceId> → 获取空间下的流水线列表，找到目标流水线ID
3. run <pipelineId>    → 执行流水线
4. list <pipelineId>   → 查看执行记录
5. run-detail <id>     → 查看执行详情
```

### 流程二：基于模板创建流水线（9步骤规范）

> **执行约束**：创建流水线必须严格按照 [pipeline-create.md](references/pipeline-create.md) 定义的9步骤顺序执行，不得跳过、调换或合并步骤。保存流水线操作通过 `save` 命令实现。

```
1. 解析用户输入 → 从自然语言提取 spaceId、流水线名称、技术栈等信息
2. 补充必填信息 → 交互式补充缺失的 spaceId、流水线名称等
3. 查询模板并选择 → 查询模板列表，交互式选择适合的模板
4. 模板数据转换 → 将模板数据转换为流水线数据，生成新UUID
5. 配置代码源 → 交互式配置代码仓库、分支等源代码信息
6. 配置任务节点 → 交互式配置任务参数、执行路径等
7. 配置预览 → 展示完整配置供用户确认
8. 保存流水线 → 调用 `save` 命令保存流水线配置
9. 执行流水线 → 调用 `run` 命令执行新创建的流水线
```

**关键约束**：
- **步骤顺序**：必须按 1→2→3→4→5→6→7→8→9 顺序执行，不得跳过、调换或合并
- **配置预览**：步骤7（配置预览）**必须执行**，用户确认后才能保存
- **命令调用**：步骤8使用 `save` 命令保存，步骤9使用 `run` 命令执行
- **ID生成**：`pipelineId` 新建时必须生成 UUID；模板转换时所有节点必须生成新 UUID
- **必填项**：`stages` 和 `taskDataList` 不能为空数组，否则保存/执行失败
- **API限定**：只能使用文档中指定的 API 接口

**说明**：
- 创建流水线通过 `save` 命令实现，需遵循上述9步骤流程
- 模板查询支持按名称模糊搜索、按类型筛选、按编程语言筛选
- 支持的模板语言：java, python, nodejs, go, dotnet, frontend, common

### 流程三：监控执行状态

```
1. list <pipelineId>       → 查看执行记录列表
2. run-detail <logId>      → 查看具体执行详情
3. cancel <logId>          → 如需取消正在执行的流水线
```

## 命令参考

所有命令均通过 `python -m scripts/main <command>` 调用。

### 工作空间与模板管理

| 命令 | 说明 | 用法 |
|------|------|------|
| `workspaces` | 查询工作空间列表 | `main.py workspaces [--name NAME] [--division NAME] [--team NAME] [--project-code CODE] [--page N] [--size N]` |
| `templates` | 查询流水线模板列表 | `main.py templates <space_id> [--name NAME] [--type TYPE] [--language LANG] [--account ACCOUNT] [--page N] [--size N]` |
| `pipelines` | 查询流水线列表 | `main.py pipelines <space_id> [--name NAME] [--page N] [--size N]` |

### 流水线配置管理

| 命令 | 说明 | 用法 |
|------|------|------|
| `detail` | 查询流水线详情 | `main.py detail <pipeline_id>` |
| `save` | 保存流水线（创建或更新） | `main.py save [--config JSON] [--file FILE] [--task-data JSON] [--task-data-file FILE]` |
| `delete` | 删除流水线 | `main.py delete <pipeline_id>` |

**`save` 命令参数说明**：
- `--config <json_string>`：流水线配置JSON字符串
- `--file <json_file_path>`：流水线配置JSON文件路径
- `--task-data <json_string>`：任务数据JSON字符串（可选）
- `--task-data-file <json_file_path>`：任务数据JSON文件路径（可选）

> **注意**：`save` 命令既可用于保存新流水线（需生成新pipelineId），也可用于更新现有流水线（保留原pipelineId）。创建流水线时应遵循 [pipeline-create.md](references/pipeline-create.md) 的9步骤规范，更新流水线时应遵循 [pipeline-update.md](references/pipeline-update.md) 的6步骤规范。

### 流水线执行与监控

| 命令 | 说明 | 用法 |
|------|------|------|
| `run` | 执行流水线 | `main.py run <pipeline_id> [--branch BRANCH] [--tasks TASKS] [--sources JSON] [--params JSON] [--auto-fill] [--re-run] [--remark TEXT] [--interactive] [--non-interactive]` |
| `list` | 查询执行记录 | `main.py list <pipeline_id> [--page-num N] [--page-size N]` |
| `run-detail` | 查询执行详情 | `main.py run-detail <pipeline_log_id>` |
| `cancel` | 取消流水线执行 | `main.py cancel <pipel