【从0到1构建一个ClaudeAgent】并发-后台任务

程序员Seven2026-04-16 9:17

有些操作很慢，Agent 不能干等着。例如长时间编译/构建 ：make, mvn compile, gradle build 或 大数据处理 ：hadoop, spark-submit 等的一些工作

Java实现代码

java 复制代码 
public class BackgroundTasksSystem {
    // --- 配置 ---
    private static final Path WORKDIR = Paths.get(System.getProperty("user.dir"));
    private static final Gson gson = new GsonBuilder().setPrettyPrinting().create();
    
    // --- 后台任务管理器 ---
    static class BackgroundManager {
        // 任务存储
        private final Map<String, TaskInfo> tasks = new ConcurrentHashMap<>();
        // 通知队列
        private final Queue<TaskNotification> notificationQueue = new ConcurrentLinkedQueue<>();
        // 任务 ID 生成器
        private final AtomicInteger taskIdCounter = new AtomicInteger(1);
        // 锁
        private final Object lock = new Object();
        
        static class TaskInfo {
            String taskId;
            String status;  // running, completed, timeout, error
            String result;
            String command;
            long startTime;
            Thread thread;  // 关联的执行线程
        }
        
        static class TaskNotification {
            String taskId;
            String status;
            String command;
            String result;
        }
        
        /**
         * 启动后台任务
         * 立即返回任务 ID，不等待命令完成
         */
        public String run(String command) {
            String taskId = "task_" + taskIdCounter.getAndIncrement();
            
            TaskInfo task = new TaskInfo(taskId, command);
            tasks.put(taskId, task);
            
            // 创建并启动后台线程
            Thread thread = new Thread(() -> executeTask(task), "BackgroundTask-" + taskId);
            thread.setDaemon(true);
            task.thread = thread;
            thread.start();  // 立即返回，不阻塞
            
            return String.format("Background task %s started: %s", 
                taskId, command.substring(0, Math.min(command.length(), 80)));
        }
        
        /**
         * 线程目标：执行子进程，捕获输出，推送结果到队列
         */
        private void executeTask(TaskInfo task) {
            String output;
            String status;
            
            try {
                ProcessBuilder pb = new ProcessBuilder("bash", "-c", task.command);
                pb.directory(WORKDIR.toFile());
                pb.redirectErrorStream(true);
                
                Process process = pb.start();
                boolean finished = process.waitFor(300, TimeUnit.SECONDS);  // 5分钟超时
                
                if (!finished) {
                    process.destroy();
                    output = "Error: Timeout (300s)";
                    status = "timeout";
                } else {
                    output = new String(process.getInputStream().readAllBytes()).trim();
                    status = "completed";
                }
            } catch (Exception e) {
                output = "Error: " + e.getMessage();
                status = "error";
            }
            
            // 更新任务状态
            task.status = status;
            task.result = output.isEmpty() ? "(no output)" : 
                          output.substring(0, Math.min(output.length(), 50000));
            
            // 添加通知到队列
            synchronized (lock) {
                notificationQueue.offer(new TaskNotification(
                    task.taskId,
                    status,
                    task.command.substring(0, Math.min(task.command.length(), 80)),
                    task.result.substring(0, Math.min(task.result.length(), 500))
                ));
            }
        }
        
        /**
         * 检查任务状态
         * 如果指定 taskId，检查单个任务；否则列出所有任务
         */
        public String check(String taskId) {
            if (taskId != null && !taskId.isEmpty()) {
                TaskInfo task = tasks.get(taskId);
                if (task == null) {
                    return "Error: Unknown task " + taskId;
                }
                return String.format("[%s] %s\n%s", 
                    task.status,
                    task.command.substring(0, Math.min(task.command.length(), 60)),
                    task.result != null ? task.result : "(running)");
            } else {
                StringBuilder sb = new StringBuilder();
                for (Map.Entry<String, TaskInfo> entry : tasks.entrySet()) {
                    TaskInfo task = entry.getValue();
                    sb.append(String.format("%s: [%s] %s\n", 
                        task.taskId,
                        task.status,
                        task.command.substring(0, Math.min(task.command.length(), 60))));
                }
                return sb.length() > 0 ? sb.toString().trim() : "No background tasks.";
            }
        }
        
        /**
         * 清空通知队列并返回所有待处理的通知
         */
        public List<TaskNotification> drainNotifications() {
            synchronized (lock) {
                List<TaskNotification> notifications = new ArrayList<>();
                while (!notificationQueue.isEmpty()) {
                    notifications.add(notificationQueue.poll());
                }
                return notifications;
            }
        }
        
        /**
         * 获取所有任务
         */
        public Map<String, TaskInfo> getAllTasks() {
            return new HashMap<>(tasks);
        }
    }
    
    // 初始化后台管理器
    private static final BackgroundManager BG_MANAGER = new BackgroundManager();
    
    // --- 工具枚举 ---
    public enum ToolType {
        BASH("bash", "Run a shell command (blocking)."),
        READ_FILE("read_file", "Read file contents."),
        WRITE_FILE("write_file", "Write content to file."),
        EDIT_FILE("edit_file", "Replace exact text in file."),
        BACKGROUND_RUN("background_run", "Run command in background thread. Returns task_id immediately."),  // 新增
        CHECK_BACKGROUND("check_background", "Check background task status. Omit task_id to list all.");  // 新增
        public final String name;
        public final String description;
        ToolType(String name, String description) { this.name = name; this.description = description; }
    }

    // --- 工具处理器映射 ---
    private static final Map<String, ToolExecutor> TOOL_HANDLERS = new HashMap<>();
    
    static {
        // ... 省略基础工具注册
        
        // 后台任务工具
        TOOL_HANDLERS.put(ToolType.BACKGROUND_RUN.name, args -> {
            String command = (String) args.get("command");
            return BG_MANAGER.run(command);
        });
        
        TOOL_HANDLERS.put(ToolType.CHECK_BACKGROUND.name, args -> {
            String taskId = (String) args.get("task_id");
            return BG_MANAGER.check(taskId);
        });
    }
    
    // ... 省略相同的工具实现
    
    // --- Agent 主循环（集成后台任务通知）---
    public static void agentLoop(List<Map<String, Object>> messages) {
        while (true) {
            try {
                // 在 LLM 调用前检查后台通知
                List<BackgroundManager.TaskNotification> notifications = BG_MANAGER.drainNotifications();
                
                if (!notifications.isEmpty() && !messages.isEmpty()) {
                    StringBuilder notifText = new StringBuilder();
                    notifText.append("<background-results>\n");
                    
                    for (BackgroundManager.TaskNotification notif : notifications) {
                        notifText.append(String.format("[bg:%s] %s: %s\n", 
                            notif.taskId, notif.status, notif.result));
                    }
                    
                    notifText.append("</background-results>");
                    
                    messages.add(Map.of(
                        "role", "user",
                        "content", notifText.toString()
                    ));
                    
                    messages.add(Map.of(
                        "role", "assistant",
                        "content", "Noted background results."
                    ));
                    // 异步结果注入：将后台任务结果插入到对话中
                    // 结构化格式：用XML标签包裹，便于LLM解析
                }
                
                // 显示当前活动任务
                Map<String, BackgroundManager.TaskInfo> activeTasks = BG_MANAGER.getAllTasks();
                int runningTasks = (int) activeTasks.values().stream()
                    .filter(t -> "running".equals(t.status))
                    .count();
                
                if (runningTasks > 0) {
                    System.out.printf("[Active background tasks: %d]\n", runningTasks);
                }
                
                // ... 省略相同的 LLM 调用和工具执行逻辑
                
            } catch (Exception e) {
                System.err.println("Error in agent loop: " + e.getMessage());
                e.printStackTrace();
                return;
            }
        }
    }
}

这段代码引入了后台任务系统 ，解决了 Agent 在执行长时间任务时的阻塞问题

关键洞察：Agent 可以在命令执行时继续工作，而不是被阻塞。

异步任务处理架构

核心思想 ：从同步阻塞的任务执行升级为异步非阻塞的并发处理 ，让Agent能够同时处理多个耗时任务，实现"并行计算"能力，大幅提升效率和响应性。

java 复制代码 
// 后台任务管理器 - 异步执行引擎
static class BackgroundManager {
    // 任务存储
    private final Map<String, TaskInfo> tasks = new ConcurrentHashMap<>();
    // 通知队列
    private final Queue<TaskNotification> notificationQueue = new ConcurrentLinkedQueue<>();
    // 任务 ID 生成器
    private final AtomicInteger taskIdCounter = new AtomicInteger(1);
    // 并发安全：使用线程安全集合
    // 异步通信：通过队列传递任务结果
    // 唯一标识：自动生成任务ID
}
  • 解耦执行：任务提交和执行分离，立即返回控制权
  • 并发管理：多个后台任务可以同时运行
  • 结果异步收集：通过队列机制收集完成的任务结果
  • 线程安全：使用并发集合确保多线程安全

任务信息结构设计

java 复制代码 
// 任务信息实体
static class TaskInfo {
    String taskId;        // 唯一标识
    String status;        // 状态：running, completed, timeout, error
    String result;        // 执行结果
    String command;       // 执行的命令
    long startTime;       // 开始时间
    Thread thread;        // 关联的执行线程
    // 完整状态跟踪：从启动到完成的全生命周期
    // 线程关联：可以控制或监控执行线程
    // 时间戳：支持超时和性能分析
}

// 任务通知实体
static class TaskNotification {
    String taskId;
    String status;
    String command;
    String result;
    // 轻量传输：只包含必要信息
    // 结构化：易于解析和处理
    // 结果截断：避免过大的通知消息
}
  • 状态驱动：明确的任务状态生命周期
  • 结果持久：任务结果可以多次查询
  • 线程管理：可以跟踪和控制执行线程
  • 事件驱动：通过通知机制传递完成事件

异步任务启动机制

java 复制代码 
/**
 * 启动后台任务
 * 立即返回任务 ID，不等待命令完成
 */
public String run(String command) {
    String taskId = "task_" + taskIdCounter.getAndIncrement();
    
    TaskInfo task = new TaskInfo(taskId, command);
    tasks.put(taskId, task);
    
    // 创建并启动后台线程
    Thread thread = new Thread(() -> executeTask(task), "BackgroundTask-" + taskId);
    thread.setDaemon(true);  // 守护线程，不会阻止JVM退出
    task.thread = thread;
    thread.start();  // 立即返回，不阻塞调用者
    
    return String.format("Background task %s started: %s", 
        taskId, command.substring(0, Math.min(command.length(), 80)));
    // 异步启动：立即返回任务ID，不等待命令完成
    // 守护线程：不会阻止程序正常退出
    // 线程命名：便于调试和监控
}
  • 立即返回：不阻塞主线程，立即返回控制权
  • 守护线程：后台任务不会阻止JVM退出
  • 资源管理：线程自动清理，避免内存泄漏
  • 友好反馈：返回任务ID和简化的命令描述

任务执行与结果收集

java 复制代码 
/**
 * 线程目标：执行子进程，捕获输出，推送结果到队列
 */
private void executeTask(TaskInfo task) {
    String output;
    String status;
    
    try {
        ProcessBuilder pb = new ProcessBuilder("bash", "-c", task.command);
        pb.directory(WORKDIR.toFile());
        pb.redirectErrorStream(true);
        
        Process process = pb.start();
        boolean finished = process.waitFor(300, TimeUnit.SECONDS);  // 5分钟超时
        
        if (!finished) {
            process.destroy();
            output = "Error: Timeout (300s)";
            status = "timeout";
        } else {
            output = new String(process.getInputStream().readAllBytes()).trim();
            status = "completed";
        }
    } catch (Exception e) {
        output = "Error: " + e.getMessage();
        status = "error";
    }
    
    // 更新任务状态
    task.status = status;
    task.result = output.isEmpty() ? "(no output)" : 
                  output.substring(0, Math.min(output.length(), 50000));
    
    // 添加通知到队列
    synchronized (lock) {
        notificationQueue.offer(new TaskNotification(
            task.taskId,
            status,
            task.command.substring(0, Math.min(task.command.length(), 80)),
            task.result.substring(0, Math.min(task.result.length(), 500))
        ));
    }
}
  • 超时保护：防止长时间运行的任务阻塞
  • 异常安全：全面捕获执行异常
  • 内存管理：截断大结果，避免内存溢出
  • 事件驱动：完成后立即通知主线程

智能通知注入机制

java 复制代码 
// 在 LLM 调用前检查后台通知
List<BackgroundManager.TaskNotification> notifications = BG_MANAGER.drainNotifications();

if (!notifications.isEmpty() && !messages.isEmpty()) {
    StringBuilder notifText = new StringBuilder();
    notifText.append("<background-results>\n");
    
    for (BackgroundManager.TaskNotification notif : notifications) {
        notifText.append(String.format("[bg:%s] %s: %s\n", 
            notif.taskId, notif.status, notif.result));
    }
    
    notifText.append("</background-results>");
    
    messages.add(Map.of(
        "role", "user",
        "content", notifText.toString()
    ));
    
    messages.add(Map.of(
        "role", "assistant",
        "content", "Noted background results."
    ));
    // 自动注入：自动将后台结果插入到对话中
    // 结构化格式：XML标签明确标识内容类型
    // 对话完整：添加assistant确认，保持对话结构
    // 时机智能：在LLM调用前插入，确保LLM能看到最新结果
}
  • 自动同步：后台结果自动同步到主对话
  • 结构化格式：便于LLM识别和解析
  • 对话集成：无缝集成到现有对话流
  • 时机优化：在决策前注入，确保信息及时性

工具集成架构

java 复制代码 
// 后台任务工具集
public enum ToolType {
    BACKGROUND_RUN("background_run", "Run command in background thread. Returns task_id immediately."),
    CHECK_BACKGROUND("check_background", "Check background task status. Omit task_id to list all.");
    // 异步执行：立即返回，不阻塞
    // 状态查询：支持单个和批量查询
    // 语义清晰：工具名明确表示异步特性
}

// 工具处理器映射
TOOL_HANDLERS.put(ToolType.BACKGROUND_RUN.name, args -> {
    String command = (String) args.get("command");
    return BG_MANAGER.run(command);
    // 委托执行：将命令转交给后台管理器
    // 立即返回：不等待任务完成
});

TOOL_HANDLERS.put(ToolType.CHECK_BACKGROUND.name, args -> {
    String taskId = (String) args.get("task_id");
    return BG_MANAGER.check(taskId);
    // 灵活查询：支持单任务详查和列表概览
});
  • 接口统一：与同步工具相同的调用方式
  • 异步语义：工具名明确区分同步/异步
  • 灵活查询：支持多种查询方式
  • 无缝集成：与现有工具系统完全兼容

架构演进与价值

从 ContextCompactSystem 到 BackgroundTasksSystem 的升级：

维度 ContextCompactSystem BackgroundTasksSystem
执行模式 同步串行 异步并行
吞吐量 一次一个任务 并发多个任务
响应性 阻塞等待 立即响应
资源利用 单线程 多线程并发
任务类型 短任务为主 长短任务混合
热门推荐
012026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元02GitHub 镜像站点03一周AI热点速览（2026.03.31-04.06）：GPT-6曝光、谷歌开源Gemma 4、资本狂飙与模型军备竞赛04GPT-6核心能力解析及与现有主流大模型对比05基于 Docker 部署 Hermes Agent 并接入飞书机器人的完整指南06GPT-6发布日深度解析-Symphony架构200万Token实战07零成本！Ollama本地部署国产大模型全指南（支持Kimi-K2.5/GLM-5/Qwen，新手秒上手）08AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析09从限购到畅通：GLM-5.1 Coding Plan接入攻略10CodeBuddy与WorkBuddy深度对比：腾讯两款AI工具差异及实操指南