worker-module-architecture

Worker Module Architecture

Applicable Scenarios

• Modify the Worker startup and execution process
• Handle task claiming, task factory, and task executor
• Troubleshoot plugin download, execution, and callback issues inside the Worker
• Modify log reporting, environment variables, archiving, and API calls
• Optimize the Worker lifecycle or execution stability

Inapplicable Scenarios

• Only developing the plugin itself or changing task.json
• Only modifying Agent daemon, heartbeat, and upgrade logic
• Only modifying Dispatch scheduling, quota, or queue policies
• Only modifying the pipeline model definition

Quick Guide

1. This skill focuses on "how the Worker actually executes after the task reaches the build machine".
2. The Worker is an executor, not a scheduler, nor a plugin definition center.
3. First enter the corresponding reference document by problem type:
   • Lifecycle and main execution pipeline:reference/1-runtime-flow.md
   • Plugin execution, logs, and artifacts:reference/2-task-plugin-log-artifact.md
   • Environment variables, API, and troubleshooting:reference/3-env-api-debug.md
4. If the symptom is "the plugin definition is wrong", switch to pipeline-plugin-development。
5. If the symptom is "it was not dispatched to this machine for execution at all", switch to dispatch-module-architecture or agent-module-architecture。

High-Signal Rules

• The Worker's main responsibility is execution, and it is not responsible for resource scheduling decisions
• Task execution, logs, variables, and archiving are different stages on the same runtime chain
• Plugin issues and Worker issues are often confused; first determine whether it is the contract layer or the execution layer
• Changes to the execution pipeline should prioritize idempotency, failure recovery, and log diagnosability

Key Pitfalls

• Misjudging a scheduling issue as a Worker issue
• Only changing the execution logic without simultaneously checking variables, logs, and result callback
• Mixing output variables and logs, causing unclear debugging and contract boundaries
• Piling too many branches into the task factory or executor, making later expansion difficult

Further Reading

• Lifecycle and main execution pipeline:reference/1-runtime-flow.md
• Plugin execution, logs, and artifacts:reference/2-task-plugin-log-artifact.md
• Environment variables, API, and troubleshooting:reference/3-env-api-debug.md
• If you are developing a plugin: also see pipeline-plugin-development
• If you are modifying Agent daemon or upgrade: also see agent-module-architecture
• If you are modifying scheduling: also see dispatch-module-architecture