Agent-Skills.md

Agent Skills: Worker 模块架构

Worker 构建执行器模块架构指南，涵盖插件执行引擎、任务分发、日志上报、制品上传、Worker 生命周期。当用户开发 Worker 功能、实现插件执行、处理任务分发或优化执行器性能时使用。

UncategorizedID: tencentblueking/bk-ci/worker-module-architecture

Repository

tencentblueking/bk-ci
TencentBlueKingLicense: NOASSERTION
2,498520

Install this agent skill to your local

pnpm dlx add-skill https://github.com/TencentBlueKing/bk-ci/tree/HEAD/ai/skills/worker-module-architecture

Skill Files

Browse the full folder contents for worker-module-architecture.

Download Skill

Loading file tree…

ai/skills/worker-module-architecture/SKILL.md

Skill Metadata

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