流水线插件开发完整指南

模块定位: 本指南详细介绍蓝盾（BK-CI）流水线插件的开发规范、配置方法、多语言实现示例、发布流程和调试技巧，帮助开发者快速上手插件开发。

一、插件开发概述

1.1 什么是流水线插件

流水线插件（Atom）是蓝盾流水线中的最小执行单元，用于完成特定的构建任务，如代码拉取、编译、测试、部署等。

1.2 支持的开发语言

语言推荐度 SDK

Java ⭐⭐⭐⭐⭐ java-atom-sdk

Python ⭐⭐⭐⭐ python-atom-sdk

NodeJS ⭐⭐⭐ @tencent/nodejs_atom_sdk

Golang ⭐⭐⭐ golang-atom-sdk

1.3 插件开发流程

┌─────────────────────────────────────────────────────────────────────────┐ │ 插件开发完整流程 │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ 1. 初始化插件 2. 开发插件 3. 发布插件 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ 登录工作台 │ ──► │ 编写 task.json│ ──► │ 提交构建 │ │ │ │ 新增插件 │ │ 开发业务逻辑 │ │ 测试验证 │ │ │ │ 克隆代码库 │ │ 本地调试 │ │ 审核发布 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘

二、task.json 配置规范

2.1 整体结构

{ "atomCode": "myAtom", // 插件唯一标识（必填） "defaultLocaleLanguage": "zh_CN", // 默认语言（非必填） "execution": { // 执行配置（必填） "language": "python", "demands": [], "target": "demo" }, "inputGroups": [], // 输入字段分组（非必填） "input": {}, // 输入字段定义（必填） "output": {}, // 输出字段定义（非必填） "config": {} // 插件控制特性（非必填） }

注意: task.json 内容长度最大为 64KB

2.2 execution 执行配置

属性名说明格式必填

language

开发语言字符串是

target

执行入口命令字符串是

demands

执行前置依赖命令数组否

runtimeVersion

运行时版本字符串否

finishKillFlag

执行完成后是否杀进程布尔否

操作系统相关配置数组否

2.2.1 runtimeVersion 配置值

语言配置值备注

python python2

默认

python python3

-- coding: utf-8 --

import python_atom_sdk as sdk

def main(): sdk.log.info("插件开始执行")

# 获取输入参数
input_params = sdk.get_input()
input_demo = input_params.get("inputDemo", "")
sdk.log.info(f"输入参数: {input_demo}")

# 业务逻辑处理
result = f"处理结果: {input_demo}"

# 设置输出
output_data = {
    "status": sdk.status.SUCCESS,
    "message": "执行成功",
    "errorCode": 0,
    "type": sdk.output_template_type.DEFAULT,
    "data": {
        "outputDemo": {
            "type": sdk.output_field_type.STRING,
            "value": result
        }
    }
}
sdk.set_output(output_data)

sdk.log.info("插件执行完成")
exit(0)

if name == "main": main()

3.2 Java 插件开发

3.2.1 目录结构

my-java-atom/ ├── task.json ├── pom.xml ├── settings.xml └── src/main/ ├── java/com/example/atom/ │ ├── AtomParam.java │ └── DemoAtom.java └── resources/META-INF/services/ └── com.tencent.bk.devops.atom.spi.TaskAtom

3.2.2 task.json

{ "atomCode": "myJavaAtom", "defaultLocaleLanguage": "zh_CN", "execution": { "language": "java", "minimumVersion": "1.8", "demands": [], "target": "java -jar myJavaAtom-jar-with-dependencies.jar" }, "input": { "desc": { "label": "描述", "type": "vuex-input", "placeholder": "请输入描述信息", "required": true } }, "output": { "testResult": { "type": "string", "description": "执行结果" } } }

3.2.3 pom.xml

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0"> <modelVersion>4.0.0</modelVersion>

&#x3C;parent>
    &#x3C;groupId>com.tencent.bk.devops.atom&#x3C;/groupId>
    &#x3C;artifactId>sdk-dependencies&#x3C;/artifactId>
    &#x3C;version>1.0.0&#x3C;/version>
&#x3C;/parent>

&#x3C;artifactId>myJavaAtom&#x3C;/artifactId>
&#x3C;version>1.0.0&#x3C;/version>

&#x3C;properties>
    &#x3C;sdk.version>1.1.58&#x3C;/sdk.version>
    &#x3C;java.version>1.8&#x3C;/java.version>
&#x3C;/properties>

&#x3C;dependencies>
    &#x3C;dependency>
        &#x3C;groupId>com.tencent.bk.devops.atom&#x3C;/groupId>
        &#x3C;artifactId>java-atom-sdk&#x3C;/artifactId>
        &#x3C;version>${sdk.version}&#x3C;/version>
    &#x3C;/dependency>
&#x3C;/dependencies>

&#x3C;build>
    &#x3C;finalName>${project.name}&#x3C;/finalName>
    &#x3C;plugins>
        &#x3C;plugin>
            &#x3C;groupId>org.apache.maven.plugins&#x3C;/groupId>
            &#x3C;artifactId>maven-assembly-plugin&#x3C;/artifactId>
        &#x3C;/plugin>
    &#x3C;/plugins>
&#x3C;/build>

</project>

3.2.4 AtomParam.java

package com.example.atom;

import com.tencent.bk.devops.atom.pojo.AtomBaseParam; import lombok.Data; import lombok.EqualsAndHashCode;

@Data @EqualsAndHashCode(callSuper = true) public class AtomParam extends AtomBaseParam { private String desc; }

3.2.5 DemoAtom.java

package com.example.atom;

import com.tencent.bk.devops.atom.AtomContext; import com.tencent.bk.devops.atom.common.Status; import com.tencent.bk.devops.atom.pojo.AtomResult; import com.tencent.bk.devops.atom.pojo.StringData; import com.tencent.bk.devops.atom.spi.AtomService; import com.tencent.bk.devops.atom.spi.TaskAtom; import org.slf4j.Logger; import org.slf4j.LoggerFactory;

@AtomService(paramClass = AtomParam.class) public class DemoAtom implements TaskAtom<AtomParam> {

private static final Logger logger = LoggerFactory.getLogger(DemoAtom.class);

@Override
public void execute(AtomContext&#x3C;AtomParam> atomContext) {
    // 获取参数
    AtomParam param = atomContext.getParam();
    AtomResult result = atomContext.getResult();
    
    logger.info("输入参数: {}", param.getDesc());
    
    // 参数校验
    if (param.getDesc() == null || param.getDesc().isEmpty()) {
        result.setStatus(Status.failure);
        result.setMessage("描述不能为空");
        return;
    }
    
    // 业务逻辑
    logger.groupStart("执行任务");
    String output = "处理结果: " + param.getDesc();
    logger.info(output);
    logger.groupEnd("执行任务");
    
    // 设置输出
    result.setStatus(Status.success);
    result.getData().put("testResult", new StringData(output));
}

}

3.2.6 SPI 配置文件

src/main/resources/META-INF/services/com.tencent.bk.devops.atom.spi.TaskAtom :

com.example.atom.DemoAtom

3.3 NodeJS 插件开发

3.3.1 目录结构

my-nodejs-atom/ ├── task.json ├── package.json ├── rollup.config.js ├── index.js └── .gitignore

3.3.2 task.json

{ "atomCode": "myNodejsAtom", "execution": { "language": "nodejs", "demands": [], "target": "node dist/bundle.js" }, "input": { "inputDemo": { "label": "输入示例", "type": "vuex-input", "required": true } }, "output": { "outputDemo": { "type": "string", "description": "输出示例" } } }

3.3.3 package.json

{ "name": "myNodejsAtom", "version": "1.0.0", "main": "./dist/bundle.js", "dependencies": { "@tencent/nodejs_atom_sdk": "^1.1.12" }, "devDependencies": { "@babel/core": "^7.4.5", "@babel/preset-env": "^7.4.5", "rollup": "^1.16.2", "rollup-plugin-babel": "^4.3.3" } }

3.3.4 rollup.config.js

import babel from 'rollup-plugin-babel'

export default { input: 'index.js', output: { file: 'dist/bundle.js', format: 'cjs' }, plugins: [babel()] }

3.3.5 index.js

import { getInputParams, setOutput, BK_ATOM_STATUS, BK_OUTPUT_TEMPLATE_TYPE } from '@tencent/nodejs_atom_sdk'

const params = getInputParams() console.log('输入参数:', params)

const inputDemo = params.inputDemo || '' const result = 处理结果: ${inputDemo}

setOutput({ "type": BK_OUTPUT_TEMPLATE_TYPE.DEFAULT, "status": BK_ATOM_STATUS.SUCCESS, "data": { "outputDemo": { "type": "string", "value": result } } })

3.4 Golang 插件开发

3.4.1 目录结构

my-golang-atom/ ├── task.json ├── go.mod ├── go.sum └── main.go

3.4.2 task.json

{ "atomCode": "myGolangAtom", "execution": { "language": "golang", "demands": [], "target": "./app" }, "input": { "greeting": { "label": "欢迎词", "type": "vuex-input", "default": "Hello", "required": true }, "userName": { "label": "用户名", "type": "vuex-input", "required": true } }, "output": { "result": { "type": "string", "description": "输出结果" } } }

3.4.3 go.mod

module xxx/bkdevops/myGolangAtom

go 1.14

require xxx/bkdevops/golang-atom-sdk v1.1.9

3.4.4 main.go

package main

import ( "fmt" sdk "xxx/bkdevops/golang-atom-sdk" )

func main() { // 获取输入参数 input := sdk.GetInput() greeting := input["greeting"] userName := input["userName"]

fmt.Printf("输入参数: greeting=%s, userName=%s\n", greeting, userName)

// 业务逻辑
result := fmt.Sprintf("%s, %s!", greeting, userName)

// 设置输出
output := sdk.Output{
    Status:  sdk.StatusSuccess,
    Message: "执行成功",
    Type:    sdk.OutputTypeDefault,
    Data: map[string]sdk.DataField{
        "result": {
            Type:  "string",
            Value: result,
        },
    },
}
sdk.SetOutput(output)

}

四、插件输出规范

4.1 输出数据结构

{ "status": "success", "message": "执行成功", "errorType": 1, "errorCode": 0, "platformCode": "", "platformErrorCode": 0, "type": "default", "data": { "outputVar1": { "type": "string", "value": "输出值" }, "outputVar2": { "type": "artifact", "value": ["/path/to/file1", "/path/to/file2"], "artifactoryType": "PIPELINE", "path": "/test/" }, "outputVar3": { "type": "report", "reportType": "INTERNAL", "label": "测试报告", "path": "/workspace/report", "target": "index.html" } } }

4.2 status 状态值

值说明

success

执行成功

failure

执行失败

4.3 输出类型详解

4.3.1 string 类型

{ "outputVar": { "type": "string", "value": "输出字符串，长度不超过4KB" } }

4.3.2 artifact 类型（构件归档）

{ "buildArtifact": { "type": "artifact", "value": ["/workspace/output/app.apk", "/workspace/output/app.ipa"], "artifactoryType": "PIPELINE", "path": "/release/" } }

属性说明

value

文件绝对路径数组

artifactoryType

PIPELINE （流水线仓库）或 CUSTOM_DIR （自定义仓库）

path

自定义仓库时的相对路径

4.3.3 report 类型（报告归档）

{ "testReport": { "type": "report", "reportType": "INTERNAL", "label": "单元测试报告", "path": "/workspace/test-report", "target": "index.html" } }

属性说明

reportType

INTERNAL （内置报告）或 THIRDPARTY （第三方链接）

label

报告别名

path

报告目录绝对路径

target

入口文件（相对于 path）

url

第三方报告链接（reportType=THIRDPARTY 时）

五、错误码规范

5.1 错误类型（errorType）

值类型说明

1 USER 用户配置错误（参数不合法等）

2 THIRD_PARTY 第三方平台错误

3 PLUGIN 插件逻辑错误（默认）

5.2 通用错误码（100 开头）

错误码说明 message 规范

100001 输入参数非法输入参数[xxx]非法：<具体要求>

100002 网络连接超时接口[xxx]，连接超时

100003 插件异常未知的插件异常：<报错信息>

100004 缺少必要参数缺少必要参数xxx

100400 HTTP 400 接口[xxx]，返回码[400]

100401 HTTP 401 接口[xxx]，返回码[401]

100403 HTTP 403 接口[xxx]，返回码[403]

100404 HTTP 404 接口[xxx]，返回码[404]

100500 HTTP 500 接口[xxx]，返回码[500]

100502 HTTP 502 接口[xxx]，返回码[502]

5.3 插件自定义错误码

统一以 8 开头
在插件代码库下增加 error.json 文件声明：

[ { "errorCode": 800001, "errorMsgZhCn": "配置文件不存在", "errorMsgEn": "Config file not found" }, { "errorCode": 800002, "errorMsgZhCn": "编译失败", "errorMsgEn": "Build failed" } ]

5.4 第三方平台错误上报

当 errorType=2 时，需要填写：

{ "errorType": 2, "errorCode": 106001, "platformCode": "tgit", "platformErrorCode": 500, "message": "调用工蜂接口失败：/api/v4/projects，返回码[500]" }

已注册的第三方平台标识:

平台标识 errorCode 前缀

蓝盾 bkci 101

CodeCC bkci_codecc 102

制品库 bkci_repo 103

编译加速 bkci_turbo 104

作业平台 bk_job 105

工蜂 tgit 106

TAPD tapd 107

智研 zhiyan 108

七彩石 rainbow 109

腾讯云 COS cloud_cos 110

六、插件发布流程

6.1 发布流程图

┌─────────────────────────────────────────────────────────────────────────┐ │ 插件发布流程 │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 提交发布 │ ─► │ 系统构建 │ ─► │ 测试验证 │ ─► │ 审核发布 │ │ │ │ │ │ │ │ │ │ │ │ │ │ 填写信息 │ │ 自动打包 │ │ 创建流水线 │ │ 首次需审核 │ │ │ │ 选择版本 │ │ 上传制品 │ │ 验证功能 │ │ 升级免审核 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ │ COMMITTING BUILDING TESTING AUDITING │ │ │ │ │ │ ▼ ▼ │ │ BUILD_FAIL AUDIT_REJECT │ │ │ │ │ ▼ │ │ RELEASED │ │ │ └─────────────────────────────────────────────────────────────────────────┘

6.2 发布类型

类型说明版本号变化

新上架首次发布 1.0.0

非兼容式升级输入输出不兼容主版本号 +1

兼容式功能更新新增功能，兼容旧版次版本号 +1

兼容式问题修正 Bug 修复修正号 +1

历史大版本 Bug fix 修复历史版本修正号 +1

6.3 版本号规范

遵循 SemVer 规范：主版本号.次版本号.修正号

主版本号：不兼容的 API 修改
次版本号：向下兼容的功能性新增
修正号：向下兼容的问题修正

七、本地调试指南

7.1 调试准备

在代码库根目录创建以下文件（不要提交到代码库）：

7.1.1 input.json

{ "inputParam1": "测试值1", "inputParam2": "测试值2" }

7.1.2 .sdk.json

{ "buildType": "DOCKER", "projectId": "test-project", "agentId": "1", "secretKey": "test-secret", "gateway": "xxx.xxx.xxx.xxx", "buildId": "test-build-id", "vmSeqId": "1" }

注意: 本地调试时不能调用蓝盾后台服务（需要在流水线中执行才有权限）

7.2 Python 插件调试

安装 SDK

pip install python-atom-sdk

打包插件

python ./setup.py sdist

安装插件

pip install dist/XXX.tar.gz

在 input.json 所在目录执行入口命令

demo

7.3 Java 插件调试

打包

mvn clean package

运行

java -jar target/myJavaAtom-jar-with-dependencies.jar

7.4 NodeJS 插件调试

安装依赖

npm install

打包

rollup -c rollup.config.js

运行（需要先在根目录创建 mock 目录，将 input.json 放入）

node dist/bundle.js

7.5 Golang 插件调试

运行

go run main.go

或构建后运行

go build -o app main.go ./app

八、最佳实践

8.1 参数校验

Python 示例

def validate_params(input_params): required_fields = ["repositoryUrl", "branch"] for field in required_fields: if not input_params.get(field): return False, f"缺少必要参数: {field}" return True, ""

8.2 错误处理

// Java 示例 try { // 业务逻辑 } catch (IOException e) { result.setErrorInfo( Status.failure, 100002, // 网络错误 ErrorType.THIRD_PARTY, new String[]{"接口调用失败: " + e.getMessage()} ); }

8.3 日志输出

Python 示例 - 使用日志分组

sdk.log.info("开始执行任务") sdk.log.group_start("编译阶段") sdk.log.info("正在编译...") sdk.log.group_end("编译阶段")

8.4 敏感信息处理

在 task.json 中将敏感字段设置 isSensitive: true
敏感信息不会在日志中明文显示
使用插件私有设置管理账号密码等敏感数据

九、常见问题

Q: task.json 修改后流水线没有生效？ A: 需要重新构建插件，并刷新流水线页面清除缓存。

Q: 如何获取上一个插件的输出变量？ A: 在参数类中定义同名参数即可自动接收。

Q: 插件执行报错 "Plugin File Sha1 is wrong!"？ A: 联系插件作者重新发布插件版本。

Q: 如何让插件支持多操作系统？ A: 在 execution.os 中配置不同操作系统的执行命令。

Q: 插件输出变量长度限制？ A: string 类型输出不能超过 4KB。

版本: 1.0.0 | 更新日期: 2025-12-26

pipeline-plugin-development

Safety Notice

Copy this and send it to your AI assistant to learn

-- coding: utf-8 --

安装 SDK

打包插件

安装插件

在 input.json 所在目录执行入口命令

打包

运行

安装依赖

打包

运行（需要先在根目录创建 mock 目录，将 input.json 放入）

运行

或构建后运行

Python 示例

Python 示例 - 使用日志分组

Source Transparency

Related Skills

frontend-vue-development

backend-microservice-development

managing-devops-pipeline

go-agent-development