agent-module-architecture_skill

Overview

This skill documents the module architecture and runtime behavior of the Go-based Agent used as a build machine in the BlueKing CI platform. It focuses on Agent startup, heartbeat/Ask flow, task acquisition and execution, automatic upgrades, and interactions with Dispatch and Worker (Kotlin) components. Use it as a focused guide when developing or modifying Agent features or operational logic.

How this skill works

The Agent runs as a daemon that ensures continuous operation, initializes config and third-party components, and enters a main Ask loop to poll the Dispatch API for work and control commands. Ask requests bundle enabled features, heartbeat info and upgrade signals; responses trigger concurrent handlers for heartbeats, builds, pipelines, Docker debug and upgrades. Builds launch Worker JVM processes (Kotlin JAR) with environment variables and temporary workdirs, while upgrades and collector tasks run under guarded locks to avoid interference with running builds.

When to use it

• Implementing or changing Agent startup, daemon or service behavior.
• Modifying heartbeat/Ask request/response handling or timing.
• Adding or debugging task scheduling and Worker process launch logic.
• Designing or adjusting automatic upgrade and self-healing workflows.
• Integrating Telegraf-based metrics collection or Docker build support.

Best practices

• Keep Ask payloads minimal and idempotent; parse responses defensively to tolerate partial fields.
• Guard upgrades with global task locks and check for running jobs to avoid disrupting active builds.
• Use file locks or OS services consistently between Unix and Windows implementations for reliable daemon behavior.
• Copy worker artifacts from a safe upgrade directory if worker.jar is missing to enable self-healing.
• Set explicit environment variables for Worker JVM runs to ensure reproducible build contexts.

Example use cases

• Extend Ask response handling to support a new remote command without blocking main loop.
• Implement custom heartbeat metrics or change heartbeat frequency to reflect network conditions.
• Add new conditions to skip upgrades (e.g., pinned versions or maintenance windows).
• Enable additional collector plugins in Telegraf and ensure graceful restart on IP changes.
• Introduce platform-specific Docker build optimizations under job_docker module.