/worker-module-architecture

name: worker-module-architecture
description: 处理 BK-CI Worker 执行器时使用，例如任务领取与执行、插件运行、日志上报、环境变量传递和制品归档。当用户要改 Worker 执行链路而不是插件定义或调度策略时优先使用。

Worker 模块架构

适用场景

• 修改 Worker 启动和执行流程
• 处理任务领取、任务工厂、任务执行器
• 排查插件在 Worker 内部的下载、执行和回传问题
• 修改日志上报、环境变量、归档和 API 调用
• 优化 Worker 生命周期或执行稳定性

不适用场景

• 只是开发插件本体或改 `task.json`
• 只是修改 Agent 守护、心跳和升级逻辑
• 只是修改 Dispatch 的调度、配额或队列策略
• 只是修改流水线模型定义

快速指导

1. 这个 skill 关注的是“任务到了构建机以后，Worker 如何真正执行”。 2. Worker 是执行器，不是调度器，也不是插件定义中心。 3. 先按问题类型进入对应参考文档：

• 生命周期与执行主链路：`reference/1-runtime-flow.md`
• 插件执行、日志与制品：`reference/2-task-plugin-log-artifact.md`
• 环境变量、API 与排查：`reference/3-env-api-debug.md`

4. 如果现象是“插件定义不对”，切到 `pipeline-plugin-development`。 5. 如果现象是“根本没被派到这台机器执行”，切到 `dispatch-module-architecture` 或 `agent-module-architecture`。

高信号规则

• Worker 的主职责是执行，不负责资源调度决策
• 任务执行、日志、变量、归档是同一条运行链上的不同环节
• 插件问题和 Worker 问题经常混淆，先判断契约层还是执行层
• 执行链路改动要优先考虑幂等、失败恢复和日志可诊断性

关键陷阱

• 把调度问题误判成 Worker 问题
• 只改执行逻辑，不同步看变量、日志和结果回传
• 输出变量和日志混用，导致调试与契约边界不清
• 在任务工厂或执行器里堆过多分支，后续难扩展

延伸阅读

• 生命周期与执行主链路：`reference/1-runtime-flow.md`
• 插件执行、日志与制品：`reference/2-task-plugin-log-artifact.md`
• 环境变量、API 与排查：`reference/3-env-api-debug.md`
• 如果你在开发插件：再看 `pipeline-plugin-development`
• 如果你在改 Agent 守护或升级：再看 `agent-module-architecture`
• 如果你在改调度：再看 `dispatch-module-architecture`