XuMaestro：面向 Gemini 与 Claude 的 AI Agent 工作流编排平台

背景：AI Agent 工作流编排的需求与挑战

随着大型语言模型（LLM）能力的不断提升，AI Agent 已经成为自动化复杂任务的重要工具。然而，单个 Agent 往往难以应对需要多步骤协作、文件批量处理和子任务嵌套的复杂场景。开发者需要一种能够编排多个 Agent、管理执行流程、并实时监控任务状态的工具。

传统的脚本式自动化虽然灵活，但缺乏可视化界面和实时追踪能力；而简单的任务队列又难以处理循环、条件分支和子工作流等复杂逻辑。XuMaestro 正是为了解决这些痛点而诞生的工作流编排平台。

XuMaestro 项目概览

XuMaestro 是一个面向 Gemini 和 Claude 的 AI Agent 工作流编排器，采用 YAML 配置文件定义工作流，并提供现代化的 Web 界面进行实时监控。项目的核心设计理念是将复杂的 Agent 协作流程抽象为可配置、可复用、可追踪的工作流单元。

该平台支持多引擎（gemini-cli 和 claude-code），允许开发者根据任务特点选择最合适的底层模型。通过 Docker 部署，XuMaestro 可以在本地环境中快速启动，确保数据隐私和执行效率。

核心功能与架构设计

YAML 配置驱动的工作流定义

XuMaestro 采用声明式的 YAML 格式定义工作流，使得非技术人员也能理解和修改任务流程。一个典型的配置包含项目名称、路径、Agent 定义和步骤序列：

name: "My Workflow"
project_path: "/Users/leo/Projects/my-project"
agents:
  - id: my_agent
    engine: gemini-cli
    system_prompt: "You are an expert assistant."
    steps:
      - "Task 1"
      - "Task 2"

配置支持丰富的参数控制，包括超时时间、重试策略、是否可跳过、交互模式等，为不同场景提供精细的控制能力。

AI 辅助工作流生成

除了手动编写 YAML，XuMaestro 还支持通过自然语言描述自动生成复杂的工作流配置。用户只需用简单的文字描述任务需求，系统即可生成对应的 YAML 文件，大幅降低使用门槛。

文件循环与批量处理

针对需要批量处理文件的场景，XuMaestro 提供了强大的循环机制。通过 glob 模式匹配文件，系统可以自动为每个匹配的文件执行相同的 Agent 任务：

loop:
  over: "src/**/*.ts"
  as: "file"
system_prompt: "Analyze the file {{ file }}"

这种设计特别适合代码审查、文档生成、批量重构等场景。

并行执行优化

XuMaestro 支持并行执行独立的 Agent 任务，通过 parallel 块可以将多个无依赖的 Agent 同时运行，显著缩短总体执行时间：

agents:
  - id: agent-setup
    engine: claude-code
  - parallel:
      - id: agent-frontend
        engine: claude-code
      - id: agent-backend
        engine: claude-code

子工作流嵌套

复杂的任务可以分解为多个子工作流，XuMaestro 支持通过 sub-workflow 引擎引用其他 YAML 文件，实现工作流的模块化和复用：

engine: sub-workflow
workflow_file: another-workflow.yaml

交互式执行与人工介入

当 Agent 需要用户输入时，XuMaestro 的交互模式会暂停执行并在 Web 界面显示输入框，允许用户实时响应 Agent 的提问，这种人机协作模式在处理需要确认或补充信息的任务时尤为重要。

弹性执行与检查点恢复

XuMaestro 内置了完善的错误处理机制，支持自动重试（mandatory 模式）和从最后一个成功检查点恢复执行。即使在长任务执行过程中遇到中断，也能避免从头开始，大大节省时间和计算资源。

Git 自动提交

每次 Agent 成功执行后，系统可以自动执行 Git 提交，并使用 AI 生成的提交信息。这一功能确保了代码变更的完整记录，方便后续审查和回滚。

实时执行监控

XuMaestro 的前端基于 Next.js 构建，通过 Server-Sent Events (SSE) 实现实时数据流。用户可以在浏览器中：

• 跟踪每个步骤的执行进度
• 查看 Agent 的输入输出日志
• 监控并行任务的运行状态
• 浏览历史执行记录和生成的产物

这种实时可视化能力让复杂工作流的调试和优化变得直观高效。

部署与使用

XuMaestro 采用 Docker Compose 部署，包含 Laravel 后端（执行引擎、进程管理、SSE）和 Next.js 前端（实时可视化、运行管理）。用户只需克隆项目、配置环境变量、运行 make build && make up，即可在本地启动完整的服务。

默认的工作流文件存放在 ./workflows 目录，提示词模板在 ./prompts 目录，执行产物保存在 ./runs 目录，所有路径都可通过环境变量自定义。

应用场景与价值

XuMaestro 适用于多种需要多 Agent 协作的自动化场景：

• 代码审查与重构：批量分析代码文件，生成重构建议
• 文档生成：从代码或数据自动生成技术文档
• 多步骤数据处理：ETL 流程、数据清洗与转换
• 自动化测试：生成测试用例、执行测试、汇总结果
• 内容创作：多轮迭代的内容生成与优化

通过将复杂的 Agent 协作流程标准化为可配置的工作流，XuMaestro 帮助团队提升自动化效率，降低重复劳动成本。

总结与展望

XuMaestro 代表了 AI Agent 工作流编排工具的发展方向：声明式配置、多引擎支持、实时可视化、弹性执行。随着 LLM 能力的持续演进，这类编排平台将在企业自动化、开发效率提升、智能内容生成等领域发挥越来越重要的作用。

对于希望将 AI Agent 集成到日常工作流的技术团队，XuMaestro 提供了一个功能完备、易于部署、高度可扩展的解决方案。