devops-pipeline-management

DevOps Pipeline Management Skill

概述

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

核心能力：

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

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

---

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

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

核心原则

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

严格禁止的行为：

• ✗ 不读文档直接执行
• ✗ 跳过或调换步骤执行
• ✗ 合并多个步骤为一步
• ✗ 自行实现功能而不调用对应Skill

全局约束清单

子功能文档（强制参考）

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

流水线核心操作

任务节点管理

查询与监控

其他操作

约束示例

✅ 正确做法

• 执行"创建流水线" → 先阅读 pipeline-create.md → 按9步骤执行
• 执行"执行流水线" → 先阅读 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. 依赖安装

pip install requests

或使用 requirements.txt：

pip install -r requirements.txt

3. 获取 API 凭证

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

环境变量配置

环境变量说明

必填环境变量

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

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

可选环境变量

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

持久化配置

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

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

然后执行：

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

安装

方式一：直接使用

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

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

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

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

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

快速开始

1. 验证配置

python -m scripts/main

2. 查询工作空间

python -m scripts/main workspaces --name devops

3. 查询流水线列表

python -m scripts/main pipelines <space_id>

4. 执行流水线

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 定义的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> 调用。

工作空间与模板管理

流水线配置管理

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 的9步骤规范，更新流水线时应遵循 pipeline-update.md 的6步骤规范。

流水线执行与监控

任务节点管理（流水线更新流程的一部分）

任务节点的添加、更新、删除操作是流水线更新流程的一部分，通过修改流水线配置并调用 save 命令实现。详细操作请参考：

• 添加任务节点：pipeline-task-add.md
• 更新任务节点：pipeline-task-update.md
• 删除任务节点：pipeline-task-delete.md

所有任务操作完成后，必须通过 save 命令统一保存流水线配置。

使用示例

查询工作空间列表

# 查询所有工作空间
python -m scripts/main workspaces

# 按名称搜索
python -m scripts/main workspaces --name devops

# 按组织筛选
python -m scripts/main workspaces --division "研发中心"

# 按产品线筛选
python -m scripts/main workspaces --team "DevOps平台"

# 分页查询
python -m scripts/main workspaces --page 2 --size 20

查询流水线列表

# 查询空间 133 的流水线列表
python -m scripts/main pipelines 133

# 按名称搜索
python -m scripts/main pipelines 133 --name 构建

# 分页查询
python -m scripts/main pipelines 133 --page-num 2 --page-size 20

查询流水线模板

# 查询空间 133 的模板列表
python -m scripts/main templates 133

# 按名称搜索
python -m scripts/main templates 133 --name Java

# 按类型筛选
python -m scripts/main templates 133 --type 1

# 按编程语言筛选
python -m scripts/main templates 133 --language java

# 分页查询
python -m scripts/main templates 133 --page 1 --size 20

基于模板创建流水线

完整9步骤交互式创建： 创建流水线需遵循 pipeline-create.md 定义的9步骤规范。以下是完整流程：

# 1. 查询工作空间获取 space_id（可选，用于确认空间）
python -m scripts/main workspaces --name devops

# 2. 查询可用模板（可选，用于了解可用模板）
python -m scripts/main templates 133 --name "Java微服务"

# 3. 创建流水线配置（遵循9步骤规范）
#    步骤1-7：交互式收集配置信息
#    步骤8：使用 save 命令保存流水线配置
python -m scripts/main save --config '{"pipelineId": "新生成的UUID", "name": "我的Java流水线", "spaceId": 133, ...}'

# 4. 执行流水线（步骤9）
python -m scripts/main run <新创建的pipeline_id>

注意：创建流水线必须严格遵循9步骤规范，包括：模板选择、代码源配置、任务节点配置、配置预览、保存和执行。

分步创建（高级用法）：

# 仅创建配置，不执行（步骤1-8）
# 遵循9步骤规范的前8步，生成流水线配置后使用 save 命令保存
python -m scripts/main save --file pipeline-config.json

# 更新已创建的流水线配置（遵循6步骤规范）
# 遵循 [pipeline-update.md](references/pipeline-update.md) 的6步骤规范
python -m scripts/main save --config '{"pipelineId": "现有pipelineId", "name": "更新后的名称", ...}'

# 执行已创建的流水线
python -m scripts/main run <pipeline_id>

模板使用流程说明：

1. 推荐使用完整交互式流程：遵循9步骤规范创建流水线
2. 模板查询（可选）：先通过 templates 命令查询可用模板，了解模板ID和配置
3. 交互式创建：通过交互式向导收集配置信息，支持选择模板、配置代码源、配置任务节点
4. 配置预览：创建过程中必须展示配置预览，供用户确认后再保存
5. 自动执行：默认创建完成后自动执行流水线（步骤9），可根据需要跳过
6. 更新配置：创建后如需修改，可遵循6步骤规范使用 save 命令更新配置

查询流水线详情

python -m scripts/main detail 4059831ef9ee41d3ad7d7c4c4be567b1

执行流水线

# 基本执行（使用默认配置）
python -m scripts/main run 4059831ef9ee41d3ad7d7c4c4be567b1

# 指定分支执行
python -m scripts/main run 4059831ef9ee41d3ad7d7c4c4be567b1 --branch feature/new-feature

# 指定执行的任务节点
python -m scripts/main run 4059831ef9ee41d3ad7d7c4c4be567b1 --tasks task-1,task-2

# 自动填充上次配置
python -m scripts/main run 4059831ef9ee41d3ad7d7c4c4be567b1 --auto-fill

# 非交互模式执行
python -m scripts/main run 4059831ef9ee41d3ad7d7c4c4be567b1 --non-interactive

查询执行记录

# 查询执行记录列表
python -m scripts/main list 4059831ef9ee41d3ad7d7c4c4be567b1

# 分页查询
python -m scripts/main list 4059831ef9ee41d3ad7d7c4c4be567b1 --page-num 1 --page-size 20

# 按状态搜索
python -m scripts/main list 4059831ef9ee41d3ad7d7c4c4be567b1 --type status --keyword success

查询执行详情

python -m scripts/main run-detail 22579

取消流水线

python -m scripts/main cancel 22579

创建流水线

# 创建流水线（遵循9步骤规范，使用 save 命令）
# 生成新的 pipelineId
python -m scripts/main save --config '{"pipelineId": "新生成的UUID", "name": "我的流水线", "spaceId": 133, "stages": [...], "sources": [...]}'

# 如果需要指定任务数据
python -m scripts/main save --config '{"pipelineId": "新生成的UUID", "name": "我的流水线", "spaceId": 133}' --task-data '[{"id": "task-001", "data": {...}}]'

# 从JSON文件创建
python -m scripts/main save --file pipeline-config.json

更新流水线

# 更新流水线（遵循6步骤规范，使用 save 命令）
# 保留原 pipelineId，更新需要修改的字段
python -m scripts/main save --config '{"pipelineId": "现有pipelineId", "name": "新名称", "spaceId": 133, ...}'

# 从JSON文件更新
python -m scripts/main save --file updated-pipeline-config.json

# 同时更新任务数据
python -m scripts/main save --config '{"pipelineId": "现有pipelineId", "name": "新名称", "spaceId": 133}' --task-data '[{"id": "task-001", "data": {...}}]'

删除流水线

python -m scripts/main delete 4059831ef9ee41d3ad7d7c4c4be567b1

请求头

API 接口列表

Base URL: /api/ai-bff/rest/openapi/pipeline

完整 API 文档请参考: pipeline_skill.md

流水线状态说明

错误处理

常见错误

调试模式

执行时会打印详细的请求和响应信息：

============================================================
[Request] POST https://one-dev.iflytek.com/devops/api/ai-bff/rest/openapi/pipeline/runByManual
------------------------------------------------------------
Headers:
  X-User-Account: rfdai
------------------------------------------------------------
Body: {...}
============================================================

============================================================
[Response] Status: 200
------------------------------------------------------------
Response Body: {...}
============================================================

子功能文档

详细功能说明请参考 references/ 目录：

流水线核心操作

任务节点管理

查询与监控

其他操作

注意事项

1. 环境变量必填: 环境变量（DEVOPS_DOMAIN_ACCOUNT、DEVOPS_BFF_URL）均为必填，缺少任意一个将无法正常使用
2. 域账号必填: domain_account 用于权限校验和操作审计
3. 删除不可恢复: 删除操作不可恢复，请谨慎使用
4. 取消限制: 取消操作只对正在执行的流水线有效（状态为 100001 或 100002）
5. 执行权限: 执行流水线需要对应的 API 访问权限，无权限时返回 401
6. 环境变量持久化: 建议将环境变量配置到 ~/.zshrc 或 ~/.bashrc 中，避免每次手动设置
7. ID说明:
   • space_id / id（WorkSpaceVO）：工作空间ID，用于查询流水线列表
   • pipeline_id / pipelineId：流水线ID，用于执行、查询详情等操作
   • pipeline_log_id / id（PipelineWorkVO）：执行记录ID，用于查看执行详情、取消执行

更新日志

v1.2.0

• 移除 AppKey 签名认证，简化认证流程
• 仅需配置域账号和 BFF 服务地址