【从0到1构建一个ClaudeAgent】协作-Worktree+任务隔离

在构建自主智能体（Agent）系统时，随着任务复杂度的提升，并发执行带来的资源冲突成为核心痛点。当多个智能体同时处理不同模块的重构或开发任务时，若共享同一代码目录，未提交的更改极易相互污染，导致代码库状态混乱且难以回滚。传统的任务看板仅管理“做什么”，却忽视了“在哪做”的物理隔离问题。为解决这一难题，引入 Git Worktree 机制成为一种高效的技术方案。通过为每个独立任务分配专属的 Git Worktree 目录，并利用任务 ID 建立双向绑定，可以实现“各干各的目录，互不干扰”的并行开发环境。这种架构不仅确保了代码修改的原子性，还大幅提升了智能体协作的稳定性与可追溯性，是构建高可用 AI 编程助手的关键基础设施。

核心架构设计：任务与工作树的解耦与绑定

在多智能体协作场景中，任务隔离是保证系统稳定性的基石。传统单目录模式下，智能体 A 修改配置文件时，智能体 B 可能正在读取该文件，这种竞态条件会导致不可预知的错误。通过引入 Git Worktree，我们可以为每个任务创建一个独立的文件系统视图，这些视图共享同一个 Git 对象数据库，但拥有独立的工作区和暂存区。

该架构的核心在于将“任务逻辑”与“物理目录”解耦。任务管理器负责维护任务的状态、描述及元数据，而工作树管理器则负责底层的 Git 操作和目录生命周期管理。两者通过一个唯一的 任务 ID 进行关联。这种设计使得系统能够灵活地扩展，支持数十甚至上百个智能体同时运行，而无需担心文件锁冲突或内容覆盖。此外，结合 事件总线（EventBus），系统可以记录所有关键操作，为后续的审计、调试及智能体行为分析提供完整的数据支撑。

Java实现基础设施：仓库检测与事件总线

为了实现上述架构，首先需要构建稳健的基础设施层，包括自动化的 Git 仓库检测机制和持久化的事件日志系统。以下是核心组件的实现细节。

自动化 Git 仓库根目录检测

系统启动时，必须准确识别当前所在的 Git 仓库根目录，以便正确初始化工作树路径。detectRepoRoot 方法通过执行 git rev-parse --show-toplevel 命令来实现这一目标。该方法具备向后兼容性，若当前目录不在 Git 仓库中，则降级使用当前工作目录，确保系统的健壮性。

public class WorktreeTaskIsolationSystem {

    // --- 新增配置 ---
    // 定义仓库根目录、任务存储目录及工作树存储目录
    private static final Path REPO_ROOT = detectRepoRoot(WORKDIR);  
    private static final Path TASKS_DIR = REPO_ROOT.resolve(".tasks");
    private static final Path WORKTREES_DIR = REPO_ROOT.resolve(".worktrees");
    private static final Path EVENTS_LOG_PATH = WORKTREES_DIR.resolve("events.jsonl");

    // --- 新增：Git 仓库检测 ---
    /**
     * 自动检测 Git 仓库根目录
     * @param cwd 当前工作目录
     * @return Git 仓库根路径，若非 Git 仓库则返回当前目录
     */
    private static Path detectRepoRoot(Path cwd) {
        try {
            // 执行 git 命令获取顶层目录
            ProcessBuilder pb = new ProcessBuilder("git", "rev-parse", "--show-toplevel");
            pb.directory(cwd.toFile());
            Process process = pb.start();

            // 设置超时时间，避免进程挂起
            boolean finished = process.waitFor(10, TimeUnit.SECONDS);
            if (!finished) {
                return cwd;
            }

            // 解析输出结果
            String output = new String(process.getInputStream().readAllBytes()).trim();
            Path root = Paths.get(output);

            // 验证路径是否存在，确保安全性
            return Files.exists(root) ? root : cwd;
        } catch (Exception e) {
            // 异常情况下降级处理，返回当前目录
            return cwd;
        }
    }

基于 JSONL 的事件总线实现

为了追踪智能体的行为和系统状态变化，引入 EventBus 组件。该组件采用 JSONL (JSON Lines) 格式记录事件，每行一个完整的 JSON 对象。这种格式便于流式处理和增量读取，特别适合长时间运行的后台服务。emit 方法负责将事件原子性地追加到日志文件中，而 listRecent 方法则提供最近事件的查询能力，支持容错解析，确保即使部分日志损坏也不影响整体数据的可读性。

    // --- 新增：事件总线（EventBus）---
    static class EventBus {
        private final Path eventLogPath;

        public EventBus(Path eventLogPath) {
            this.eventLogPath = eventLogPath;
            try {
                // 确保日志目录存在
                Files.createDirectories(eventLogPath.getParent());
                if (!Files.exists(eventLogPath)) {
                    Files.writeString(eventLogPath, "");
                }
            } catch (IOException e) {
                throw new RuntimeException("Failed to create event bus", e);
            }
        }

        /**
         * 发出事件并持久化到日志文件
         * @param event 事件类型
         * @param task 关联的任务信息
         * @param worktree 关联的工作树信息
         * @param error 错误信息（可选）
         */
        public void emit(String event, Map<String, Object> task, 
                        Map<String, Object> worktree, String error) {
            Map<String, Object> payload = new LinkedHashMap<>();
            payload.put("event", event);
            payload.put("ts", System.currentTimeMillis() / 1000.0); //  Unix 时间戳
            payload.put("task", task != null ? task : Map.of());
            payload.put("worktree", worktree != null ? worktree : Map.of());

            if (error != null) {
                payload.put("error", error);
            }

            try {
                // 序列化为 JSON 字符串并换行
                String jsonLine = gson.toJson(payload) + "\n";
                // 以追加模式写入，保证并发安全性和数据完整性
                Files.writeString(eventLogPath, jsonLine, 
                    StandardOpenOption.CREATE, StandardOpenOption.APPEND);
            } catch (IOException e) {
                System.err.println("Failed to emit event: " + e.getMessage());
            }
        }

        /**
         * 列出最近发生的事件
         * @param limit 限制返回的事件数量
         * @return JSON 格式的事件列表
         */
        public String listRecent(int limit) {
            int n = Math.max(1, Math.min(limit, 200)); // 限制最大读取量

            try {
                List
<String> lines = Files.readAllLines(eventLogPath);
                List<Map<String, Object>> events = new ArrayList<>();

                // 计算起始索引，只读取最后 N 行
                int start = Math.max(0, lines.size() - n);
                for (int i = start; i < lines.size(); i++) {
                    try {
                        Type type = new TypeToken<Map<String, Object>>(){}.getType();
                        Map<String, Object> event = gson.fromJson(lines.get(i), type);
                        events.add(event);
                    } catch (Exception e) {
                        // 容错处理：解析失败时记录原始数据和错误标记
                        Map<String, Object> errorEvent = new HashMap<>();
                        errorEvent.put("event", "parse_error");
                        errorEvent.put("raw", lines.get(i));
                        events.add(errorEvent);
                    }
                }

                return gson.toJson(events);
            } catch (IOException e) {
                return "[]";
            }
        }
    }

    // 初始化全局事件总线实例
    private static final EventBus EVENTS = new EventBus(EVENTS_LOG_PATH);

任务管理器：实现任务与工作树的生命周期绑定

TaskManager 负责维护任务的元数据，并处理任务与工作树之间的绑定关系。在传统系统中，任务状态通常是静态的，但在本架构中，任务状态与工作树的创建和销毁紧密耦合。当任务被分配到一个工作树时，其状态自动从 pending 转换为 in_progress，这种状态机设计简化了上层业务逻辑的判断复杂度。

任务与工作树的双向绑定机制

bindWorktree 方法是连接任务逻辑与物理资源的关键。它不仅更新任务记录中的 worktree 字段，还负责触发状态的自动流转。这种设计确保了任何时刻，一个进行中的任务都明确指向一个独立的操作环境。反之，unbindWorktree 允许在任务完成或失败后释放资源，保持系统的整洁。

    // --- 新增：任务管理器（支持工作树绑定）---
    static class TaskManager {
        private final Path tasksDir;
        private int nextId = 1;

        public TaskManager(Path tasksDir) {
            this.tasksDir = tasksDir;
            try {
                Files.createDirectories(tasksDir);
                this.nextId = getMaxId() + 1; // 初始化 ID 计数器
            } catch (IOException e) {
                throw new RuntimeException("Failed to initialize task manager", e);
            }
        }

        /**
         * 将任务绑定到指定工作树
         * @param taskId 任务 ID
         * @param worktree 工作树名称
         * @param owner 任务所有者
         * @return 更新后的任务 JSON 字符串
         */
        public String bindWorktree(int taskId, String worktree, String owner) throws IOException {
            Map<String, Object> task = loadTask(taskId);

            // 建立任务与工作树的关联
            task.put("worktree", worktree);

            if (owner != null && !owner.isEmpty()) {
                task.put("owner", owner);
            }

            // 状态自动转换：若任务处于等待状态，绑定后自动标记为进行中
            if ("pending".equals(task.get("status"))) {
                task.put("status", "in_progress");
            }

            task.put("updated_at", System.currentTimeMillis() / 1000.0);
            saveTask(task);
            return gson.toJson(task);
        }

        /**
         * 解除任务与工作树的绑定
         * @param taskId 任务 ID
         * @return 更新后的任务 JSON 字符串
         */
        public String unbindWorktree(int taskId) throws IOException {
            Map<String, Object> task = loadTask(taskId);
            task.put("worktree", ""); // 清空工作树引用
            task.put("updated_at", System.currentTimeMillis() / 1000.0);
            saveTask(task);
            return gson.toJson(task);
        }

        /**
         * 列出所有任务及其绑定状态
         * @return 格式化后的任务列表字符串
         */
        public String listAllTasks() throws IOException {
            // 此处省略具体遍历逻辑，重点展示格式化输出
            // 可视化展示：显示任务状态、所有者、工作树绑定信息
            StringBuilder sb = new StringBuilder();
            // ... 遍历任务集合
            // sb.append(String.format("%s #%d: %s%s%s\n", marker, id, subject, ownerStr, worktreeStr));
            return sb.toString();
        }

        // 辅助方法：加载和保存任务的具体实现略
        private Map<String, Object> loadTask(int id) throws IOException { /* ... */ return new HashMap<>(); }
        private void saveTask(Map<String, Object> task) throws IOException { /* ... */ }
        private int getMaxId() { return 0; }
        public boolean taskExists(int taskId) { return true; }
    }

    // 初始化全局任务管理器实例
    private static final TaskManager TASKS = new TaskManager(TASKS_DIR);

工作树管理器：Git 操作的封装与安全控制

WorktreeManager 是整个系统的核心执行引擎，它封装了所有与 Git Worktree 相关的底层操作。该管理器不仅负责创建工作树，还承担了命令执行的安全沙箱功能。通过与 TaskManager 和 EventBus 的深度集成，它确保了每一次操作都是可追溯且受控的。

Git 命令执行与环境检查

在执行任何 Git 操作前，系统必须验证当前环境是否为合法的 Git 仓库。isGitRepo 方法通过 git rev-parse --is-inside-work-tree 进行快速检查。runGit 方法则是一个通用的命令执行器，它设置了严格的超时控制（120秒），并详细捕获标准输出和错误流，确保在命令失败时能提供清晰的诊断信息。

    // --- 新增：工作树管理器（WorktreeManager）---
    static class WorktreeManager {
        private final Path repoRoot;
        private final TaskManager taskManager;
        private final EventBus eventBus;
        private final Path worktreesDir;
        private final Path indexPath;
        private final boolean gitAvailable;

        public WorktreeManager(Path repoRoot, TaskManager taskManager, EventBus eventBus) {
            this.repoRoot = repoRoot;
            this.taskManager = taskManager;
            this.eventBus = eventBus;
            this.worktreesDir = repoRoot.resolve(".worktrees");
            this.indexPath = worktreesDir.resolve("index.json");

            // 集成架构：工作树管理器与任务管理器、事件总线集成

            try {
                Files.createDirectories(worktreesDir);
                // 初始化索引文件，用于持久化工作树元数据
                if (!Files.exists(indexPath)) {
                    Map<String, Object> index = new HashMap<>();
                    index.put("worktrees", new ArrayList<Map<String, Object>>());
                    Files.writeString(indexPath, gson.toJson(index));
                }
            } catch (IOException e) {
                throw new RuntimeException("Failed to initialize worktree manager", e);
            }

            this.gitAvailable = isGitRepo();
        }

        /**
         * 检查当前目录是否位于 Git 仓库内
         */
        private boolean isGitRepo() {
            try {
                ProcessBuilder pb = new ProcessBuilder("git", "rev-parse", "--is-inside-work-tree");
                pb.directory(repoRoot.toFile());
                Process process = pb.start();
                return process.exitValue() == 0;
            } catch (Exception e) {
                return false;
            }
        }

        /**
         * 执行 Git 命令并返回结果
         * @param args Git 命令参数列表
         * @return 命令输出结果
         */
        private String runGit(List
<String> args) throws Exception {
            if (!gitAvailable) {
                throw new RuntimeException("Not in a git repository. worktree tools require git.");
            }

            ProcessBuilder pb = new ProcessBuilder("git");
            pb.command().addAll(args);
            pb.directory(repoRoot.toFile());

            Process process = pb.start();
            // 设置较长的超时时间以应对大型仓库操作
            boolean finished = process.waitFor(120, TimeUnit.SECONDS);

            if (!finished) {
                process.destroy();
                throw new RuntimeException("git command timeout");
            }

            int exitCode = process.exitValue();
            if (exitCode != 0) {
                String error = new String(process.getErrorStream().readAllBytes()).trim();
                String output = new String(process.getInputStream().readAllBytes()).trim();
                String message = error.isEmpty() ? output : error;
                if (message.isEmpty()) {
                    message = "git " + String.join(" ", args) + " failed";
                }
                throw new RuntimeException(message);
            }

            String output = new String(process.getInputStream().readAllBytes()).trim();
            String error = new String(process.getErrorStream().readAllBytes()).trim();
            String result = output + (error.isEmpty() ? "" : "\n" + error);
            return result.isEmpty() ? "(no output)" : result;
        }

工作树的创建与索引管理

createWorktree 方法实现了工作树创建的完整流程：参数校验、事件通知、Git 操作、索引更新及任务绑定。首先，它对工作树名称进行严格正则校验，防止路径遍历攻击或非法字符导致的文件系统错误。接着，它在执行实际 Git 命令前后分别发出 worktree.create.before 和 worktree.create.after 事件，确保操作的可观测性。

在 Git 层面，系统为每个工作树自动创建一个名为 wt/<name> 的新分支，这避免了多工作树共享同一分支头指针带来的冲突。创建成功后，工作树的元数据（如路径、分支名、关联任务 ID）被保存到 index.json 中，并与任务管理器进行绑定，形成闭环。

        /**
         * 加载工作树索引文件
         */
        @SuppressWarnings("unchecked")
        private Map<String, Object> loadIndex() throws IOException {
            String content = Files.readString(indexPath);
            Type type = new TypeToken<Map<String, Object>>(){}.getType();
            return gson.fromJson(content, type);
        }

        /**
         * 保存工作树索引文件
         */
        private void saveIndex(Map<String, Object> index) throws IOException {
            Files.writeString(indexPath, gson.toJson(index));
        }

        /**
         * 验证工作树名称的合法性
         * @param name 待验证的名称
         */
        private void validateName(String name) {
            if (name == null || name.isEmpty() || name.length() > 40) {
                throw new IllegalArgumentException("Worktree name must be 1-40 characters");
            }

            // 仅允许字母、数字、点、下划线和连字符，防止注入攻击
            if (!name.matches("[A-Za-z0-9._-]+")) {
                throw new IllegalArgumentException(
                    "Invalid worktree name. Use letters, numbers, ., _, - only"
                );
            }
        }

        /**
         * 创建新的 Git 工作树并绑定任务
         * @param name 工作树名称
         * @param taskId 关联的任务 ID
         * @param baseRef 基准引用（如 main 或 commit hash）
         * @return 创建成功的工作树元数据 JSON
         */
        public String createWorktree(String name, Integer taskId, String baseRef) throws Exception {
            validateName(name);

            // 检查工作树是否已存在，避免重复创建
            Map<String, Object> existing = findWorktree(name);
            if (existing != null) {
                throw new IllegalArgumentException("Worktree '" + name + "' already exists");
            }

            // 验证关联任务的有效性
            if (taskId != null && !taskManager.taskExists(taskId)) {
                throw new IllegalArgumentException("Task " + taskId + " not found");
            }

            // 发出创建前事件，用于监控和审计
            Map<String, Object> taskInfo = taskId != null ? 
                Map.of("id", taskId) : Map.of();
            Map<String, Object> worktreeInfo = Map.of("name", name, "base_ref", baseRef);
            eventBus.emit("worktree.create.before", taskInfo, worktreeInfo, null);

            try {
                Path worktreePath = worktreesDir.resolve(name);
                String branch = "wt/" + name;  // 自动生成分支名，隔离变更

                // 执行 Git worktree add 命令
                // -b 参数创建新分支，确保工作树间的提交历史独立
                runGit(Arrays.asList("worktree", "add", "-b", branch, 
                    worktreePath.toString(), baseRef));

                // 构建索引条目
                Map<String, Object> entry = new LinkedHashMap<>();
                entry.put("name", name);
                entry.put("path", worktreePath.toString());
                entry.put("branch", branch);
                entry.put("task_id", taskId);
                entry.put("status", "active");
                entry.put("created_at", System.currentTimeMillis() / 1000.0);

                // 更新索引文件
                Map<String, Object> index = loadIndex();
                @SuppressWarnings("unchecked")
                List<Map<String, Object>> worktrees = (List<Map<String, Object>>) index.get("worktrees");
                worktrees.add(entry);
                saveIndex(index);

                // 若有关联任务，执行绑定操作
                if (taskId != null) {
                    taskManager.bindWorktree(taskId, name, "");
                }

                // 发出创建成功事件
                Map<String, Object> worktreeAfter = new LinkedHashMap<>();
                worktreeAfter.put("name", name);
                worktreeAfter.put("path", worktreePath.toString());
                worktreeAfter.put("branch", branch);
                worktreeAfter.put("status", "active");

                eventBus.emit("worktree.create.after", taskInfo, worktreeAfter, null);

                return gson.toJson(entry);

            } catch (Exception e) {
                // 捕获异常并发出失败事件，便于故障排查
                eventBus.emit("worktree.create.failed", taskInfo, 
                    Map.of("name", name, "base_ref", baseRef), e.getMessage());
                throw e;
            }
        }

        // 辅助方法：查找工作树
        private Map<String, Object> findWorktree(String name) throws IOException {
             // 实现略：遍历 index.json 中的 worktrees 列表查找匹配项
             return null;
        }

安全沙箱：在工作树中执行命令

智能体可能需要在工作树中执行编译、测试或脚本运行等命令。runInWorktree 方法提供了一个受控的执行环境。首先，它实施了一道简单的安全检查防线，拦截包含 rm -rf /、sudo 等高危指令的请求，防止恶意代码或错误提示导致宿主系统受损。其次，它通过 ProcessBuilder 将工作目录设置为特定工作树的路径，确保所有文件操作都被限制在该隔离环境中。

此外，该方法设置了 300 秒的执行超时，防止无限循环或死锁进程占用系统资源。输出结果被限制在 50,000 字符以内，避免内存溢出。这种设计在保证灵活性的同时，最大限度地降低了安全风险。

        /**
         * 在指定工作树中安全执行 Shell 命令
         * @param name 工作树名称
         * @param command 要执行的命令
         * @return 命令执行输出或错误信息
         */
        public String runInWorktree(String name, String command) throws Exception {
            // 安全检查：拦截潜在的危险命令
            String[] dangerous = {"rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"};
            for (String d : dangerous) {
                if (command.contains(d)) {
                    return "Error: Dangerous command blocked";
                }
            }

            Map<String, Object> worktree = findWorktree(name);
            if (worktree == null) {
                return "Error: Unknown worktree '" + name + "'";
            }

            Path worktreePath = Paths.get((String) worktree.get("path"));
            if (!Files.exists(worktreePath)) {
                return "Error: Worktree path missing: " + worktreePath;
            }

            try {
                // 在工作树目录下启动 Bash 进程
                ProcessBuilder pb = new ProcessBuilder("bash", "-c", command);
                pb.directory(worktreePath.toFile());

                Process process = pb.start();
                // 设置合理的超时时间，防止进程挂起
                boolean finished = process.waitFor(300, TimeUnit.SECONDS);

                if (!finished) {
                    process.destroy();
                    return "Error: Timeout (300s)";
                }

                String output = new String(process.getInputStream().readAllBytes()).trim();
                String error = new String(process.getErrorStream().readAllBytes()).trim();
                String result = output + (error.isEmpty() ? "" : "\n" + error);

                // 限制输出长度，保护内存
                return result.isEmpty() ? "(no output)" : 
                    result.substring(0, Math.min(result.length(), 50000));

            } catch (Exception e) {
                return "Error: " + e.getMessage();
            }
        }

## 工作树生命周期管理

在**多智能体协作**场景中，资源的及时释放与状态同步至关重要。`removeWorktree` 方法不仅负责物理删除 Git 工作树目录，更承担了**任务生命周期终结**的逻辑闭环。通过 `force` 参数，系统允许在遇到未提交变更等异常状态时强制清理，确保自动化流程不会因人为疏忽而阻塞。当 `completeTask` 标志位被置为真时，系统会自动将关联的任务状态更新为“已完成”，并解除任务与工作树的绑定关系，实现了**资源回收与业务状态的一致性**。这一机制避免了“僵尸任务”占用系统资源，同时也保证了审计日志中任务状态的准确性。此外，索引文件的异步更新确保了元数据层面的最终一致性，即使底层文件系统操作成功，上层管理视图也能即时反映变化。这种设计特别适用于高频次、短周期的代码生成或测试任务，能够显著降低长期运行后的存储压力。

```java
        public String removeWorktree(String name, boolean force, boolean completeTask) throws Exception {
            Map&amp;lt;String, Object&amp;gt; worktree = findWorktree(name);
            if (worktree == null) {
                return "Error: Unknown worktree '" + name + "'";
            }

            // 发出删除前事件
            Integer taskId = (Integer) worktree.get("task_id");
            Map&amp;lt;String, Object&amp;gt; taskInfo = taskId != null ? 
                Map.of("id", taskId) : Map.of();
            Map&amp;lt;String, Object&amp;gt; worktreeInfo = Map.of(
                "name", name, 
                "path", worktree.get("path")
            );

            eventBus.emit("worktree.remove.before", taskInfo, worktreeInfo, null);

            try {
                List&amp;lt;String&amp;gt; args = new ArrayList&amp;lt;&amp;gt;();
                args.addAll(Arrays.asList("worktree", "remove"));
                if (force) {
                    args.add("--force");
                }
                args.add((String) worktree.get("path"));

                runGit(args);
                // Git工作树删除：清理Git工作树

                // 完成任务
                if (completeTask && taskId != null) {
                    Map&amp;lt;String, Object&amp;gt; task = gson.fromJson(taskManager.getTask(taskId), 
                        new TypeToken&amp;lt;Map&amp;lt;String, Object&amp;gt;&amp;gt;(){}.getType());

                    taskManager.updateTask(taskId, "completed", null);
                    taskManager.unbindWorktree(taskId);
                    // 任务-工作树生命周期协同：删除工作树时自动完成任务

                    Map&amp;lt;String, Object&amp;gt; taskEvent = new HashMap&amp;lt;&amp;gt;();
                    taskEvent.put("id", taskId);
                    taskEvent.put("subject", task.get("subject"));
                    taskEvent.put("status", "completed");

                    eventBus.emit("task.completed", taskEvent, 
                        Map.of("name", name), null);
                }

                // 更新索引
                Map&amp;lt;String, Object&amp;gt; index = loadIndex();
                @SuppressWarnings("unchecked")
                List&amp;lt;Map&amp;lt;String, Object&amp;gt;&amp;gt; worktrees = (List&amp;lt;Map&amp;lt;String, Object&amp;gt;&amp;gt;) index.get("worktrees");

                for (Map&amp;lt;String, Object&amp;gt; wt : worktrees) {
                    if (name.equals(wt.get("name"))) {
                        wt.put("status", "removed");
                        wt.put("removed_at", System.currentTimeMillis() / 1000.0);
                        break;
                    }
                }
                saveIndex(index);
                // 索引更新：标记工作树为已删除状态

                // 发出删除后事件
                Map&amp;lt;String, Object&amp;gt; worktreeAfter = new HashMap&amp;lt;&amp;gt;();
                worktreeAfter.put("name", name);
                worktreeAfter.put("path", worktree.get("path"));
                worktreeAfter.put("status", "removed");

                eventBus.emit("worktree.remove.after", taskInfo, worktreeAfter, null);

                return "Removed worktree '" + name + "'";

            } catch (Exception e) {
                eventBus.emit("worktree.remove.failed", taskInfo, worktreeInfo, e.getMessage());
                throw e;
            }
        }

工作树保留机制

并非所有的工作树都需要在任务结束后立即销毁，keepWorktree 方法提供了一种选择性持久化的策略。在某些调试场景或需要人工复核代码生成的案例中，开发者可能希望保留特定的工作树以供后续检查。该方法通过将工作树状态标记为 kept 并记录时间戳，将其从自动清理队列中排除。这种机制赋予了系统更高的灵活性，允许在自动化流程中插入人工介入点。保留的工作树依然受版本控制管理，但其生命周期不再由任务状态直接驱动，而是由管理员手动决定何时归档或删除。这在处理复杂 Bug 修复或进行 A/B 测试对比时尤为有用，因为开发者可以随时切换回这些“冻结”的环境复现问题。同时，事件总线会发出 worktree.keep 信号，便于外部监控系统追踪哪些环境被长期占用，从而优化资源分配策略。

        /**
         * 保留工作树（标记为保留状态）
         */
        public String keepWorktree(String name) throws IOException {
            Map<String, Object> worktree = findWorktree(name);
            if (worktree == null) {
                return "Error: Unknown worktree '" + name + "'";
            }

            Map<String, Object> index = loadIndex();
            @SuppressWarnings("unchecked")
            List<Map<String, Object>> worktrees = (List<Map<String, Object>>) index.get("worktrees");

            Map<String, Object> keptWorktree = null;

            for (Map<String, Object> wt : worktrees) {
                if (name.equals(wt.get("name"))) {
                    wt.put("status", "kept");
                    wt.put("kept_at", System.currentTimeMillis() / 1000.0);
                    keptWorktree = wt;
                    break;
                }
            }

            saveIndex(index);
            // 保留状态：标记工作树为需要保留，不自动清理

            // 发出保留事件
            Integer taskId = (Integer) worktree.get("task_id");
            Map<String, Object> taskInfo = taskId != null ? 
                Map.of("id", taskId) : Map.of();

            Map<String, Object> worktreeInfo = new HashMap<>();
            worktreeInfo.put("name", name);
            worktreeInfo.put("path", worktree.get("path"));
            worktreeInfo.put("status", "kept");

            eventBus.emit("worktree.keep", taskInfo, worktreeInfo, null);

            return keptWorktree != null ? gson.toJson(keptWorktree) : 
                "Error: Unknown worktree '" + name + "'";
        }
    }

工具处理器集成

为了将底层的 Java 逻辑暴露给上层智能体，系统构建了一个基于映射表的工具注册中心。TOOL_HANDLERS 静态块定义了智能体可调用的原子操作接口，涵盖了从任务创建、状态查询到工作树执行的全链路功能。每个处理器都负责解析输入参数，调用相应的管理器方法，并将结果序列化为 JSON 格式返回。这种设计模式实现了控制逻辑与执行逻辑的解耦，使得新增工具只需注册一个新的 Handler 即可，无需修改核心调度引擎。例如，worktree_run 工具允许智能体在隔离环境中执行 Shell 命令，而 task_bind_worktree 则确保了任务上下文与代码环境的强关联。通过统一的参数校验和类型转换，系统增强了鲁棒性，防止因智能体生成的参数格式错误导致服务崩溃。这种标准化的工具接口也是实现 ReAct (Reasoning and Acting) 模式的关键，让大模型能够清晰地理解可用能力边界。

    // 初始化工作树管理器
    private static final WorktreeManager WORKTREES = new WorktreeManager(REPO_ROOT, TASKS, EVENTS);

    // --- 新增：工具处理器 ---
    static {
        // 新增任务工具
        TOOL_HANDLERS.put("task_create", args -> {
            String subject = (String) args.get("subject");
            String description = (String) args.get("description");
            return TASKS.createTask(subject, description);
        });

        TOOL_HANDLERS.put("task_list", args -> TASKS.listAllTasks());

        TOOL_HANDLERS.put("task_get", args -> {
            int taskId = ((Number) args.get("task_id")).intValue();
            return TASKS.getTask(taskId);
        });

        TOOL_HANDLERS.put("task_update", args -> {
            int taskId = ((Number) args.get("task_id")).intValue();
            String status = (String) args.get("status");
            String owner = (String) args.get("owner");
            return TASKS.updateTask(taskId, status, owner);
        });

        TOOL_HANDLERS.put("task_bind_worktree", args -> {
            int taskId = ((Number) args.get("task_id")).intValue();
            String worktree = (String) args.get("worktree");
            String owner = (String) args.get("owner");
            return TASKS.bindWorktree(taskId, worktree, owner);
        });

        // 新增工作树工具
        TOOL_HANDLERS.put("worktree_create", args -> {
            String name = (String) args.get("name");
            Integer taskId = args.get("task_id") != null ? 
                ((Number) args.get("task_id")).intValue() : null;
            String baseRef = (String) args.get("base_ref");
            if (baseRef == null) baseRef = "HEAD";
            return WORKTREES.createWorktree(name, taskId, baseRef);
        });

        TOOL_HANDLERS.put("worktree_list", args -> WORKTREES.listWorktrees());

        TOOL_HANDLERS.put("worktree_status", args -> {
            String name = (String) args.get("name");
            return WORKTREES.getWorktreeStatus(name);
        });

        TOOL_HANDLERS.put("worktree_run", args -> {
            String name = (String) args.get("name");
            String command = (String) args.get("command");
            return WORKTREES.runInWorktree(name, command);
        });

        TOOL_HANDLERS.put("worktree_keep", args -> {
            String name = (String) args.get("name");
            return WORKTREES.keepWorktree(name);
        });

        TOOL_HANDLERS.put("worktree_remove", args -> {
            String name = (String) args.get("name");
            boolean force = args.get("force") != null && (Boolean) args.get("force");
            boolean completeTask = args.get("complete_task") != null && (Boolean) args.get("complete_task");
            return WORKTREES.removeWorktree(name, force, completeTask);
        });

        TOOL_HANDLERS.put("worktree_events", args -> {
            int limit = args.get("limit") != null ? ((Number) args.get("limit")).intValue() : 20;
            return EVENTS.listRecent(limit);
        });
    }

架构演进与核心价值

通过引入 Git Worktree 技术，本架构实现了从简单的文件系统隔离向仓库级代码隔离的质的飞跃。传统的多线程或临时目录方案往往难以处理复杂的依赖冲突和版本回溯，而 Git Worktree 天然支持多分支并行检出，且共享对象存储，极大地节省了磁盘空间并提升了 I/O 效率。这种控制平面与执行平面分离的设计，使得主仓库保持洁净，而各个智能体可以在独立的沙箱中自由实验、提交甚至回滚，互不干扰。对于企业级应用而言，这意味着可以安全地并行处理数百个代码生成或重构任务，而无需担心环境污染或状态竞态。此外，完整的事件总线和索引机制为系统提供了可观测性，使得每一个代码变更都可追溯、可审计。这不仅提升了开发效率，更为构建高可靠、自愈型的 AI 编程助手奠定了坚实的基础。

总结

本文详细拆解了一种基于 Git Worktree 的多智能体任务隔离与协作架构，展示了如何通过工程化手段解决 AI Agent 在代码生成场景下的并发与安全难题。从底层的 Git 命令封装，到中层的任务-工作树双向绑定，再到上层的工具化接口暴露，每一层设计都旨在提升系统的鲁棒性与可扩展性。我们看到了一个清晰的演进路径：从单一的智能体执行，发展到具备上下文隔离能力的并行处理单元，最终形成一个可管理、可观测的分布式协作网络。这种架构不仅适用于代码生成，也可推广至任何需要隔离环境进行自动化测试、数据处理或文档生成的场景。对于致力于构建生产级 AI 应用的开发者而言，理解并掌握这种资源隔离与生命周期管理的模式，是跨越原型验证走向规模化落地的关键一步。