---
name: dispatch-module-architecture
description: 处理 BK-CI 构建调度时使用，例如构建机选择、队列推进、配额控制、第三方构建机调度、Docker/Kubernetes 调度。当用户要改任务分配策略而不是 Agent/Worker 执行细节时优先使用。
---

# Dispatch 模块架构

## 适用场景

- 修改第三方构建机、Docker 或 Kubernetes 调度逻辑
- 处理队列、配额、资源分配和构建机选择
- 排查任务排队、派发失败或调度不均衡
- 扩展新的调度类型或构建资源类型

## 不适用场景

- 只是修改 Agent 守护、心跳或升级
- 只是修改 Worker 执行、日志或变量回传
- 只是开发插件或改 `task.json`
- 只是修改流水线业务编排

## 快速指导

1. 这个 skill 关注的是“任务如何被分配到合适的执行环境”。
2. Dispatch 的核心不是执行任务，而是做选择、排队、限流和推进。
3. 先按问题类型进入对应参考文档：
   - 模块结构与核心对象：`reference/1-dispatch-foundation.md`
   - 队列、配额与调度策略：`reference/2-queue-quota-scheduling.md`
   - 资源类型扩展与排查：`reference/3-resource-extension-debug.md`
4. 如果问题已经到达构建机并开始执行，切到 `agent-module-architecture` 或 `worker-module-architecture`。
5. 如果问题是插件本身不兼容运行环境，切到 `pipeline-plugin-development`。

## 高信号规则

- Dispatch 解决的是“在哪里跑”和“什么时候跑”
- 队列、配额、资源类型和监听推进是同一套调度系统的不同面
- 调度问题要先区分资源不足、策略不匹配还是执行侧异常
- 新调度类型落地时，数据模型、监听链路和资源约束要一起看

## 关键陷阱

- 把 Agent / Worker 执行失败误判成 Dispatch 问题
- 只看单个服务方法，不看监听、队列和配额的完整推进链
- 新增调度类型时只补入口，不补限流、状态流转和清理逻辑
- 调度问题排查只盯代码，不先确认资源池和配额状态

## 延伸阅读

- 模块结构与核心对象：`reference/1-dispatch-foundation.md`
- 队列、配额与调度策略：`reference/2-queue-quota-scheduling.md`
- 资源类型扩展与排查：`reference/3-resource-extension-debug.md`
- 如果你在改构建机宿主行为：再看 `agent-module-architecture`
- 如果你在改任务执行：再看 `worker-module-architecture`