agent-dispatch-use

name agent-dispatch-use description AgentDispatch 使用指南。教导 AI Agent 如何启动 Server、配置 Client Node、将各种 Agent 作为 Worker 挂载到分发集群、提交任务并监听状态。触发方式：用户提及 "/onboard"、"how to use dispatch"、"快速上手"、"set up agentdispatch"、"挂载 Agent"、"mount worker" 等关键词时激活。 license MIT allowed-tools Shell, Read, Write, Glob, Grep AgentDispatch 使用指南 概述 AgentDispatch 是一个 AI Agent 任务分发平台。核心架构将任务 创建 与 执行 完全解耦： 组件 职责 Server 中心化 REST API 服务，管理任务队列、客户端注册、文件持久化、SSE 推送 Client Node 执行节点，轮询 Server 获取任务，调度和管理本地 Worker Agent 集群 Worker Agent 通过 ACP (Agent Client Protocol) 执行具体任务的 AI Agent Manager Agent 可选的 AI 调度顾问，通过 ACP 向 Client Node 提供分发建议 CLI dispatch 命令行工具，Worker 通过它上报进度、提交产物 ┌────────────────────────┐ 任务提交方 │ Server (:9800) │ (curl / SDK / Dashboard)─→│ REST API + FileStore │ │ SSE Stream + Auth │ └────────┬───────────────┘ │ HTTP (poll/claim/progress/complete) ┌────────▼───────────────┐ │ Client Node │ │ Dispatcher (tag/mgr) │ │ AcpController │ │ WorkerManager │ │ IPC Server │ └──┬─────┬─────┬─────────┘ ACP(stdio) │ │ │ ACP(stdio) ┌─────────▼┐ ┌──▼──┐ ┌▼──────────┐ │ Worker-01│ │Wk-02│ │Manager Agt │ │(claude) │ │(gpt)│ │(调度顾问) │ └──────────┘ └─────┘ └───────────┘ 核心设计理念 ：任何支持 ACP 协议（JSON-RPC 2.0 over stdio）的 AI Agent 都可以作为 Worker 挂载到 Client Node 上。 Part 1: 启动 Server 1.1 前置条件 Node.js >= 20.0.0 pnpm >= 9.x 1.2 安装与构建 pnpm install pnpm build 1.3 零配置启动 node packages/server/dist/index.js # Server 默认监听 0.0.0.0:9800，数据存储在 ./data/ 1.4 自定义配置 环境变量方式 （推荐用于快速测试）： DISPATCH_SERVER_PORT=8080 \ DISPATCH_DATA_DIR=./my-data \ DISPATCH_LOG_LEVEL=debug \ DISPATCH_AUTH_ENABLED= true \ DISPATCH_AUTH_TOKENS= "tok_client_abc123,tok_operator_xyz:operator" \ node packages/server/dist/index.js 配置文件方式 （ server.config.json ）： { "host" : "0.0.0.0" , "port" : 9800 , "dataDir" : "./data" , "logLevel" : "info" , "auth" : { "enabled" : true , "users" : [ { "username" : "admin" , "password" : "your-password" } ] , "tokens" : [ "tok_client_abc123" , { "token" : "tok_operator_xyz" , "role" : "operator" } ] } } 1.5 验证 curl http://localhost:9800/health # {"status":"ok","version":"0.0.1","authEnabled":false} 1.6 环境变量一览 变量 默认值 说明 DISPATCH_SERVER_HOST 0.0.0.0 监听地址 DISPATCH_SERVER_PORT 9800 监听端口 DISPATCH_DATA_DIR ./data 数据目录 DISPATCH_LOG_LEVEL info 日志级别 (debug/info/warn/error) DISPATCH_AUTH_ENABLED false 启用鉴权 DISPATCH_AUTH_TOKENS — 静态 Token 列表（逗号分隔， :role 后缀可选） Part 2: 配置 Client Node 2.1 最小可用配置 在工作目录创建 client.config.json ： { "name" : "my-node" , "serverUrl" : "http://localhost:9800" , "tags" : [ "code-review" ] , "dispatchMode" : "tag-auto" , "autoDispatch" : { "rules" : [ { "taskTags" : [ "code-review" ] , "targetAgentId" : "worker-01" , "priority" : 10 } ] , "fallbackAction" : "skip" } , "agents" : [ { "id" : "worker-01" , "type" : "worker" , "command" : "claude-agent-acp" , "workDir" : "/path/to/workspace" } ] } 2.2 完整配置结构 { "name" : "production-node" , "serverUrl" : "http://your-server:9800" , "token" : "tok_client_abc123" , "tags" : [ "code-review" , "documentation" , "testing" ] , "dispatchMode" : "hybrid" , "polling" : { "interval" : 10000 } , "heartbeat" : { "interval" : 30000 } , "ipc" : { "path" : "" } , "autoDispatch" : { "rules" : [ { "taskTags" : [ "code-review" ] , "targetAgentId" : "claude-worker" , "priority" : 10 } , { "taskTags" : [ "documentation" ] , "targetCapabilities" : [ "writing" ] , "priority" : 5 } , { "taskTags" : [ "testing" ] , "targetAgentId" : "test-worker" , "priority" : 8 } ] , "fallbackAction" : "skip" } , "logging" : { "dir" : "./logs" , "rotateDaily" : true , "retainDays" : 30 , "httpLog" : true , "auditLog" : true , "agentLog" : true } , "agents" : [ ] } 2.3 关键字段说明 字段 必填 说明 name 是 节点唯一标识，Server 按此区分客户端 serverUrl 是 Server HTTP 地址 token 启用 auth 时 Server 分配的 API Token tags 是 节点能处理的任务标签集合 dispatchMode 是 分发策略： tag-auto / manager / hybrid autoDispatch.rules tag-auto/hybrid 按 task tag 匹配 Worker 的规则列表 autoDispatch.fallbackAction 否 无规则匹配时行为： skip （默认）/ queue-local 2.4 分发模式 模式 工作方式 需要 Manager tag-auto 规则引擎按 task tag 匹配 Worker，按 priority 排序 否 manager 每个待分配任务都咨询 Manager Agent，由 AI 决定路由 是 hybrid Manager 在线时用 AI 调度，离线时回退到 tag-auto 规则 可选 2.5 分发规则详解 { "taskTags" : [ "backend" , "api" ] , "targetAgentId" : "worker-backend" , "targetCapabilities" : [ "typescript" , "node" ] , "priority" : 10 } 字段 说明 taskTags AND 逻辑 — 任务必须包含所有指定 tag 才匹配 targetAgentId 精确指定 Worker ID targetCapabilities 按能力匹配 — 选择拥有这些 capabilities 的空闲 Worker priority 数值越大越优先（多条规则匹配时取最高优先级） 2.6 启动 Client Node node packages/client-node/dist/main.js # 或指定配置文件 DISPATCH_NODE_CONFIG=./my-config.json node packages/client-node/dist/main.js CLI 方式： dispatch start --config ./client.config.json dispatch start --config ./client.config.json --foreground Part 3: 将 Agent 作为 Worker 挂载（重点） 这是 AgentDispatch 的核心操作——将一个 AI Agent 注册为 Worker，使其能自动接收并执行分发来的任务。 3.1 Agent 挂载原理 ┌──────────────────────────────────────────────────────────────┐ │ Client Node │ │ │ │ 1. Dispatcher 决定: task → worker-01 │ │ 2. HTTP claim → Server │ │ 3. AcpController.launchAgent(): │ │ a. 创建 AgentProcess (spawn 子进程) │ │ b. 注入 DISPATCH_TOKEN + DISPATCH_IPC_PATH │ │ c. 通过 stdin/stdout 建立 ACP JSON-RPC 连接 │ │ d. 发送 initialize (声明 capabilities) │ │ e. TaskWorkflowRunner 发送 task prompt │ │ 4. Worker 执行任务，通过 dispatch CLI 上报进度 │ │ 5. Worker 完成 → 产物打包 → dispatch worker complete │ │ 6. AcpController 收集结果 → 上传 Server → 标记 completed │ │ │ │ ┌─────────────────┐ stdio (ACP) ┌──────────────────┐ │ │ │ AcpController │←────────────→│ Worker Process │ │ │ │ DispatchAcpClient│ │ (ACP Agent 进程) │ │ │ └─────────────────┘ └──────────────────┘ │ └──────────────────────────────────────────────────────────────┘ 3.2 AgentConfig 完整字段 每个 Worker 在 client.config.json 的 agents 数组中注册： interface AgentConfig { id : string ; // 唯一标识（必填） type : 'manager' | 'worker' ; // 角色（必填） command : string ; // 启动命令（必填） args ?: string []; // 额外启动参数 workDir : string ; // 工作目录（必填） capabilities ?: string []; // 能力标签（用于 dispatch 匹配） autoClaimTags ?: string []; // 自动认领的任务标签 allowMultiProcess ?: boolean ; // 是否允许并行多任务（默认 false） promptTemplate ?: string ; // 自定义 prompt 模板路径 acpCapabilities ?: { fs ?: { readTextFile ?: boolean ; // 允许 Agent 读文件 writeTextFile ?: boolean ; // 允许 Agent 写文件 }; terminal ?: boolean ; // 允许 Agent 使用终端 }; permissionPolicy ?: 'auto-allow' | 'auto-deny' | 'prompt' ; } 3.3 关键字段深度说明 command — Agent 启动命令 第一个 token 是可执行文件，后续 token 是默认参数。 args 中的参数会追加到末尾。 { "command" : "claude-agent-acp" , "args" : [ "--model" , "sonnet" ] } // 实际执行: claude-agent-acp --model sonnet 要求 ： command 启动的进程必须通过 stdin/stdout 进行 ACP 协议通信（JSON-RPC 2.0, newline-delimited JSON）。stderr 用于日志输出，不参与协议。 注意 ：并非所有 AI Agent CLI 都原生支持 ACP。部分 Agent（如 Claude、Codex）需要通过适配器。 详见 ACP 兼容 Agent 列表 。 workDir — Agent 工作目录 Agent 进程以此目录为 cwd 启动。Client Node 会在其中创建： {workDir}/ ├── .dispatch/ │ ├── input/{taskIdPrefix}/ ← 下载的任务附件 │ └── output/{taskIdPrefix}/ ← Agent 应将产物放在这里 │ ├── artifact.zip ← 产物压缩包 │ └── result.json ← 结构化结果 └── ... (Agent 自身的文件) capabilities — 能力标签 与分发规则的 targetCapabilities 配合使用： // 规则: 需要 ["typescript", "testing"] 能力的 Worker { "taskTags" : [ "unit-test" ] , "targetCapabilities" : [ "typescript" , "testing" ] } // Worker: 声明自己具备这些能力 { "id" : "test-bot" , "capabilities" : [ "typescript" , "testing" , "jest" ] } // ✓ 匹配成功（Worker 具备规则要求的所有能力） acpCapabilities — ACP 能力声明 在 ACP initialize 阶段向 Agent 声明 Client 提供的能力： { "acpCapabilities" : { "fs" : { "readTextFile" : true , "writeTextFile" : true } , "terminal" : true } } 能力 说明 fs.readTextFile Agent 可通过 ACP 请求读取 Client 端文件 fs.writeTextFile Agent 可通过 ACP 请求写入 Client 端文件 terminal Agent 可通过 ACP 请求执行终端命令 permissionPolicy — 权限策略 当 Agent 通过 ACP 请求使用工具（文件读写、终端）时的审批策略： 值 行为 auto-allow 自动批准所有请求（默认，适合可信 Agent） auto-deny 自动拒绝所有请求（最安全） prompt 需要人工审批（当前未完整实现） 3.4 Worker 生命周期 Client Node 启动 │ Worker 注册 (config.agents) │ status: idle │ ┌────────────────▼────────────────┐ │ Dispatcher 匹配到合适的任务 │ │ HTTP claim → Server │ └────────────────┬────────────────┘ │ ┌────────────────▼────────────────┐ │ AcpController.launchAgent() │ │ 1. spawn(command, {cwd:workDir})│ │ 2. env += DISPATCH_TOKEN │ │ 3. env += DISPATCH_IPC_PATH │ │ 4. ACP initialize() │ │ 5. ACP prompt(taskContent) │ └────────────────┬────────────────┘ │ status: busy │ ┌────────────────▼────────────────┐ │ Worker 执行任务 │ │ - dispatch worker progress ... │ │ - dispatch worker log ... │ │ - 产出 artifact.zip + result.json │ │ - dispatch worker complete ... │ └────────────────┬────────────────┘ │ ┌───────────┴───────────┐ ▼ ▼ 完成 (completed) 失败 (failed) │ │ status: idle auto restart? │ (指数退避) ▼ │ 等待下一个任务 status: idle 进程环境变量注入 Worker 进程启动时自动获得两个关键环境变量： | 变量 | 值 | 用途 |