介绍
Fieldlight Studio 有三张花园照片需要分享。原图已经准备好，但尺寸较大的原图不便快速审阅。你将使用已准备好的图像工具生成小尺寸预览和一张照片总览图：将整个照片集集中展示在一张图片中，便于一目了然地查看。
工具安装在一个已连接的 Jenkins agent 上。你的第一个任务是选择真正能完成工作的 agent。随后，你将响应更小尺寸的交付要求，保留两个成功版本，并保护原始照片。
前置要求是 Jenkins 页面操作，以及能看懂一段简短的声明式流水线。不需要 Java 编程、照片编辑命令、Docker 管理或 agent 安装知识。提供的程序和 agent 连接都已准备好。两个 agent 是同一台训练 VM 上的独立容器：文件系统相互独立，但共享内核。这不是云端机器集群。Fieldlight 是虚构的，照片是 AI 生成的学习素材。预计用时由作者估算，未经初学者实测。
将工作分配给适合的 agent
在这一步中，你将检查原图，观察一次预期的缺少工具失败，并将工作调度到具备图像处理能力的 agent。请从 Photo Desk 开始。
Garden Stories 照片集展示薰衣草、花园小径和浇水壶。打开每张照片，检查完整原图，并使用浏览器的 Back 操作返回照片台。为薰衣草照片选择 Download original，保留下载文件以便比较。原图宽度为 1536 像素，必须保持不变。照片台最初显示 No completed collection yet。
切换到 Jenkins。Jenkins 的控制器保存任务配置并协调构建。agent 是执行构建工作的已连接进程。节点（node）是它在 Jenkins 中的配置条目。执行器（executor）是该节点上一个可用的工作槽位。这里每个 agent 有一个执行器，因此同一时间只能执行一个分配给它的工作块。
从仪表板选择 Manage Jenkins，然后选择 Nodes。依次检查 image-studio 和 pack-studio。两者都已连接。它们的能力标签分别为 photo-imaging 和 photo-packing，两者还都有 linux。标签是调度条件，不会安装软件。图像工具只存在于 image-studio，打包工具只存在于 pack-studio。它们是真正独立的 agent 进程和容器。
使用左上角的 Jenkins 标志返回仪表板，然后打开 preview-photos。选择 Configure，再找到 Pipeline 区域。Script 编辑器包含已准备好的任务。在做任何更改前，先阅读其结构：
- 顶部的
agent none表示整条 Pipeline 不预留一个 agent。阶段会自行选择 agent。 stage('Prepare photos')为工作命名。其中的agent { label 'photo-packing' }当前请求打包能力。steps包含操作。sh在所选 agent 的 shell 中运行引号内的命令。提供的/opt/fieldlight/prepare-photos程序创建预览；--width 480请求宽度为 480 像素，并保留原始宽高比。单引号将该命令保持为一个 Groovy 字符串。deleteDir()清空分配给此任务的工作区，即存放构建文件的临时目录。第一次调用确保从干净状态开始。post部分的always调用会在阶段之后清空工作区，包括失败之后。它不会删除/opt/fieldlight/originals下的原图。archiveArtifacts在清理之前将匹配的文件保留在 Jenkins 中。在prepared/**中，**包含嵌套目录内的文件。fingerprint: true记录文件身份以便追踪；它不代表客户批准或签名。
不编辑脚本，返回任务页面。选择一次 Build Now。在 Build History 中打开新的带编号构建，然后选择 Console Output。等待它结束。第一次失败是预期的：控制台先标识 pack-studio，然后报告 /opt/fieldlight/prepare-photos 为 not found，最后以 FAILURE 结束。请求的 agent 已连接，但缺少这个角色的工具。这与因 agent 离线或没有匹配 agent 而无限等待不同。
返回 preview-photos，选择 Configure，再次打开 Pipeline。仅将阶段标签从 photo-packing 改为 photo-imaging。如需可完整复制的版本，请点击 Script 内部，在 Windows/Linux 上使用 Ctrl+A，或在 macOS 上使用 Command+A 全选，然后将内容替换为：
pipeline {
agent none
stages {
stage('Prepare photos') {
agent { label 'photo-imaging' }
steps {
deleteDir()
sh '/opt/fieldlight/prepare-photos --width 480'
archiveArtifacts artifacts: 'prepared/**', fingerprint: true
}
post {
always { deleteDir() }
}
}
}
}
保留工具命令、原图、归档和两次清理调用。选择 Save，然后选择 Build Now。打开新构建的 Console Output，等待 Finished: SUCCESS。它应显示 image-studio，报告 3 previews at 480 pixels wide，然后显示 Archiving artifacts、Recording fingerprints 和最后的 deleteDir。这证明工作确实在有能力的 agent 上执行，而不只是换了一条消息的名称。
如果出现 Groovy 语法错误，请返回 Configure，恢复上面的完整脚本，保存并运行新构建。如果标签拼写错误导致构建一直排队，请用排队项的取消图标取消它，在确认对话框中选择 Yes，修正标签并再次构建。命令拼写错误会在控制台中显示为找不到命令；请恢复提供的路径，而不是安装另一种工具。保留最初的失败构建及此后全部历史。普通错误可以通过再次保存脚本并构建来修正；不要重置 VM。
切换到 Photo Desk 并刷新。选择 Open prepared collection。三张小尺寸预览必须与原图展示相同的花园主体。选择 Open contact sheet，一起查看三张照片；使用浏览器的 Back 返回。打开 Caption table 和 Image details，每次查看后都用 Back 返回。captions.csv 是纯文本的逗号分隔值表：第一行给出列名，之后每行描述一张图片。它将每条说明与对应的 images/ 文件关联，并记录宽度 480、高度 320；preparation.json 标识 garden 和宽度 480。
返回 Jenkins，打开成功构建的页面。在 Build Artifacts 下，单个 PNG 文件名链接会在浏览器中打开图片。如需完整下载，请选择 Build Artifacts 标题，再在文件浏览页面选择 **(all files in zip)**。将 archive.zip 保存到存放 480 像素版本的文件夹，并在那里解压整个 ZIP。六个文件位于 archive/prepared/ 下，其中包括 images/ 子目录。在浏览器或图片查看器中打开 archive/prepared/images/garden-01.png 和 archive/prepared/contact-sheet.png，并在文本编辑器中阅读 archive/prepared/captions.csv。它们的可见内容必须与照片集匹配。薰衣草预览为 480 × 320 像素，而下载的原图仍为 1536 × 1024。保留这次成功构建的编号和完整的解压文件夹，供下一步使用。工作区清空后，这些保留的文件仍然可用。
处理后的照片集与原图展示相同的薰衣草、花园小径和浇水壶。使用照片总览图和文件链接，检查实际保留的输出。
交付更小尺寸的预览集
在这一步中，你将满足 320 像素的交付请求，并保留之前的 480 像素照片集用于比较。请从 Photo Desk 开始，使用 Back to originals 返回原图。确认三张完整原图都仍然可用。
客户现在需要预览恰好为 320 pixels wide（320 像素宽）。提供的程序通过已有的 --width 选项接受这个要求；你不需要编辑或替换图像程序。切换到 Jenkins，返回 preview-photos，选择 Configure → Pipeline。将 --width 480 改为 --width 320，修改位置在 sh 命令中。现在完整脚本应为：
pipeline {
agent none
stages {
stage('Prepare photos') {
agent { label 'photo-imaging' }
steps {
deleteDir()
sh '/opt/fieldlight/prepare-photos --width 320'
archiveArtifacts artifacts: 'prepared/**', fingerprint: true
}
post {
always { deleteDir() }
}
}
}
}
选择 Save，然后选择 Build Now。等待新构建以 SUCCESS 结束。在 Console Output 中确认执行工作的是 image-studio，程序报告 320 pixels wide，且归档和清理都已运行。如果控制台仍显示 480，请检查是否保存了更改后的脚本，以及打开的是新构建而不是之前的构建。
在这次构建页面上，选择 Build Artifacts，然后选择 **(all files in zip)**。将新的 archive.zip 保存并完整解压到与 480 像素版本不同的文件夹。打开其 archive/prepared/ 目录下的文件。三张预览图片现在都应为 320 × 213 像素。213 像素的高度是保留 1536 × 1024 原图宽高比后取整的结果。照片总览图仍按相同顺序包含三个主体；它是独立的概览，而不是第四张缩小的原图。在 captions.csv 中，每张图片的文件名、说明和尺寸必须一致。preparation.json 必须标识 garden 和宽度 320。
切换到 Photo Desk，刷新并选择 Open prepared collection。检查三张新预览、照片总览图和两个元数据文件。返回原图，确认全尺寸内容未变。然后切换到 Jenkins，打开之前记下的成功构建，再次通过 Build Artifacts → (all files in zip) 下载其完整 ZIP。将它解压到另一个新文件夹：其中的薰衣草预览必须仍为 480 × 320 像素。创建新版本不应重写旧归档。
如果下载文件的尺寸或主体不符合预期，请检查构建编号和保存的宽度选项，然后修正脚本并运行新构建。保留原始照片、提供的工具、已连接的 agent、能力标签和完整构建历史。不要在 agent 文件系统之间复制文件、移除清理或用另一次运行的归档替代。完成时，保存的脚本必须已实际成功构建。现在你拥有更小且可用的照片集、完整的较早版本和未改变的原图。
总结
你将真实的图像处理能力与 Jenkins agent 标签匹配，理解了一次预期的缺少工具失败，并生成了可用预览。更改宽度选项后，你创建了更小尺寸的交付内容，同时没有改变原图或较早归档。工作区清空后，原生构建产物仍然保留；下一个独立实验将使用两个独立工作区，以及同一次运行内的临时交接。
