NullBoiler是一个专注于AI智能体工作流编排的开源引擎，通过清晰的架构边界将任务追踪、编排策略和执行引擎分离，支持多步骤工作流、状态管理和流式执行。

NullBoiler：AI智能体工作流的模块化编排引擎\n\n在AI应用开发领域，智能体（Agent）的概念已经从简单的对话助手演变为能够执行复杂多步骤任务的自主系统。然而，随着智能体能力的增强，如何有效地编排多个智能体协同工作、管理工作流状态、处理并发和故障恢复，成为了开发者面临的新挑战。NullBoiler项目应运而生，它提供了一个专注于编排职责的轻量级引擎，通过严格的架构边界设计，为AI工作流管理带来了新的思路。\n\n## 项目定位与设计哲学\n\nNullBoiler的核心定位非常明确：它是一个编排引擎，而非任务追踪器，也不是智能体运行时。这种刻意保持的"狭窄"定位体现了清晰的设计哲学——每个组件只负责自己最擅长的领域。\n\n在NullBoiler的架构中，三个核心角色各司其职：\n\n- Tracker（追踪器）：作为单一真相来源，负责任务的持久化存储、状态管理、优先级排序和所有权记录。它保存任务生命周期的完整历史，是待处理工作的权威队列。\n\n- Orchestrator（编排器）：作为策略引擎，从追踪器拉取或选择工作，应用调度策略，执行路由决策，并强制执行并发限制、重试和退避策略。它决定"何时运行什么"以及"由谁执行"。\n\n- Agent（智能体）：作为执行引擎，接收具体的任务或作业，执行工具调用、代码运行和模型交互，并将执行结果返回给编排流程。\n\n这种分离不是过度设计，而是基于实际工程经验的总结。许多团队在构建AI系统时，容易将追踪器和制品管理的责任混入编排器，导致架构臃肿、难以维护。NullBoiler通过强制保持边界清晰，使整个系统更易于理解和演进。\n\n## 灵活的部署模式\n\nNullBoiler的设计支持多种组合部署模式，开发者可以根据实际需求选择所需的组件：\n\n单一智能体直接执行：仅使用nullclaw（参考运行时），适合简单的单智能体场景，无需复杂的编排逻辑。\n\n编排执行无追踪器：nullboiler + nullclaw的组合，提供编排能力但没有独立的任务追踪系统。这种模式适合工作流相对简单、不需要持久化任务历史的场景。\n\n追踪器驱动执行：nulltickets + nullclaw的组合，由追踪器驱动执行循环。这种模式下，任务管理由追踪器主导，智能体专注于执行。\n\n完整多智能体编排：nulltickets + nullboiler + nullclaw的全栈组合，提供持久化任务源、策略编排和智能体执行的完整能力。这是最复杂的模式，适合需要高可靠性和可扩展性的生产环境。\n\n此外，nullboiler还可以编排其他兼容的工作器，如OpenClaw/OpenAI兼容运行时、ZeroClaw或PicoClaw（通过桥接器），提供了良好的生态兼容性。\n\n## 编排图运行时能力\n\nNullBoiler的编排图运行时支持丰富的工作流节点类型和控制机制：\n\n节点类型：包括任务节点（task）、智能体节点（agent）、路由节点（route）、中断节点（interrupt）、发送节点（send）、转换节点（transform）和子图节点（subgraph）。这种多样性允许开发者表达复杂的工作流逻辑。\n\n执行控制：支持运行重放（run replay）、检查点分叉（checkpoint forking）、断点中断（breakpoint interrupts）和启动后状态注入（post-start state injection）。这些功能为调试和故障恢复提供了强大支持。\n\n数据流管理：支持通过items_key和output_key配置发送扇出（send fan-out），通过output_mapping进行任务/智能体输出塑形。模板系统可以访问state.、input.、item.、config.和store.等上下文变量。\n\n**持久化存储：通过transform.store_updates，工作流可以将持久化的工作流内存写回NullTickets，实现跨执行周期的状态保持。\n\n## 配置与验证机制\n\nNullBoiler提供了灵活的配置机制：\n\n- 默认配置文件路径为~/.nullboiler/config.json\n- 可通过NULLBOILER_HOME环境变量覆盖实例主目录\n- 可直接通过--config参数指定配置文件路径\n\n当设置NULLBOILER_HOME时，nullboiler会从该目录读取config.json，并相对于配置文件解析相对路径（如db、strategies_dir、tracker.workflows_dir等）。\n\n对于基于文件的追踪器/拉取模式工作流，NullBoiler提供了工作流验证工具：\n\nbash\nzig build run -- validate-workflows\nzig build run -- validate-workflows workflows\n\n\n验证命令会扫描目录中的.json文件，检查工作流定义的完整性，包括：\n\n- 目录或文件是否缺失或不可读\n- JSON格式是否正确\n- 是否符合WorkflowDef结构\n- pipeline_id是否存在且非空\n- 是否存在重复的pipeline_id\n\n验证错误会以状态码1退出，警告信息会显示但不会导致失败，这与运行时加载器的宽松行为保持一致。\n\n## 实践意义与应用场景\n\nNullBoiler的设计使其特别适合以下场景：\n\n复杂多步骤AI工作流：当单个智能体无法完成复杂任务，需要多个智能体协同工作，并且步骤之间存在依赖关系时，NullBoiler的编排能力可以确保工作流按预期执行。\n\n高可靠性要求：通过检查点、重试、断路器等机制，NullBoiler可以帮助构建能够优雅处理故障的AI系统，确保关键任务最终完成。\n\n多租户或并发场景：编排器的并发限制和调度策略可以有效管理资源使用，防止系统过载。\n\n可观测性需求：通过将追踪、编排和执行分离，每个组件都可以独立监控和优化，提高了系统的可观测性。\n\n## 总结与展望\n\nNullBoiler代表了AI基础设施向模块化、专业化方向发展的一个趋势。它不试图成为无所不能的框架，而是专注于做好编排这一件事。这种克制的设计哲学使得NullBoiler可以与各种追踪器和智能体运行时灵活组合，适应不同的应用场景。\n\n对于正在构建AI应用系统的开发者来说，NullBoiler提供了一个值得参考的架构范式：通过清晰的边界划分，让系统的每个部分都保持简单和可替换。随着AI智能体生态的成熟，这种模块化的编排方案可能会成为行业标准实践。

NullBoiler：AI智能体工作流的模块化编排引擎\n\n在AI应用开发领域，智能体（Agent）的概念已经从简单的对话助手演变为能够执行复杂多步骤任务的自主系统。然而，随着智能体能力的增强，如何有效地编排多个智能体协同工作、管理工作流状态、处理并发和故障恢复，成为了开发者面临的新挑战。NullBoiler项目应运而生，它提供了一个专注于编排职责的轻量级引擎，通过严格的架构边界设计，为AI工作流管理带来了新的思路。\n\n项目定位与设计哲学\n\nNullBoiler的核心定位非常明确：它是一个编排引擎，而非任务追踪器，也不是智能体运行时。这种刻意保持的"狭窄"定位体现了清晰的设计哲学——每个组件只负责自己最擅长的领域。\n\n在NullBoiler的架构中，三个核心角色各司其职：\n\n- Tracker（追踪器）：作为单一真相来源，负责任务的持久化存储、状态管理、优先级排序和所有权记录。它保存任务生命周期的完整历史，是待处理工作的权威队列。\n\n- Orchestrator（编排器）：作为策略引擎，从追踪器拉取或选择工作，应用调度策略，执行路由决策，并强制执行并发限制、重试和退避策略。它决定"何时运行什么"以及"由谁执行"。\n\n- Agent（智能体）：作为执行引擎，接收具体的任务或作业，执行工具调用、代码运行和模型交互，并将执行结果返回给编排流程。\n\n这种分离不是过度设计，而是基于实际工程经验的总结。许多团队在构建AI系统时，容易将追踪器和制品管理的责任混入编排器，导致架构臃肿、难以维护。NullBoiler通过强制保持边界清晰，使整个系统更易于理解和演进。\n\n灵活的部署模式\n\nNullBoiler的设计支持多种组合部署模式，开发者可以根据实际需求选择所需的组件：\n\n单一智能体直接执行：仅使用nullclaw（参考运行时），适合简单的单智能体场景，无需复杂的编排逻辑。\n\n编排执行无追踪器：nullboiler + nullclaw的组合，提供编排能力但没有独立的任务追踪系统。这种模式适合工作流相对简单、不需要持久化任务历史的场景。\n\n追踪器驱动执行：nulltickets + nullclaw的组合，由追踪器驱动执行循环。这种模式下，任务管理由追踪器主导，智能体专注于执行。\n\n完整多智能体编排：nulltickets + nullboiler + nullclaw的全栈组合，提供持久化任务源、策略编排和智能体执行的完整能力。这是最复杂的模式，适合需要高可靠性和可扩展性的生产环境。\n\n此外，nullboiler还可以编排其他兼容的工作器，如OpenClaw/OpenAI兼容运行时、ZeroClaw或PicoClaw（通过桥接器），提供了良好的生态兼容性。\n\n编排图运行时能力\n\nNullBoiler的编排图运行时支持丰富的工作流节点类型和控制机制：\n\n节点类型：包括任务节点（task）、智能体节点（agent）、路由节点（route）、中断节点（interrupt）、发送节点（send）、转换节点（transform）和子图节点（subgraph）。这种多样性允许开发者表达复杂的工作流逻辑。\n\n执行控制：支持运行重放（run replay）、检查点分叉（checkpoint forking）、断点中断（breakpoint interrupts）和启动后状态注入（post-start state injection）。这些功能为调试和故障恢复提供了强大支持。\n\n数据流管理：支持通过items_key和output_key配置发送扇出（send fan-out），通过output_mapping进行任务/智能体输出塑形。模板系统可以访问state.、input.、item.、config.和store.等上下文变量。\n\n**持久化存储：通过transform.store_updates，工作流可以将持久化的工作流内存写回NullTickets，实现跨执行周期的状态保持。\n\n配置与验证机制\n\nNullBoiler提供了灵活的配置机制：\n\n- 默认配置文件路径为~/.nullboiler/config.json\n- 可通过NULLBOILER_HOME环境变量覆盖实例主目录\n- 可直接通过--config参数指定配置文件路径\n\n当设置NULLBOILER_HOME时，nullboiler会从该目录读取config.json，并相对于配置文件解析相对路径（如db、strategies_dir、tracker.workflows_dir等）。\n\n对于基于文件的追踪器/拉取模式工作流，NullBoiler提供了工作流验证工具：\n\nbash\nzig build run -- validate-workflows\nzig build run -- validate-workflows workflows\n\n\n验证命令会扫描目录中的.json文件，检查工作流定义的完整性，包括：\n\n- 目录或文件是否缺失或不可读\n- JSON格式是否正确\n- 是否符合WorkflowDef结构\n- pipeline_id是否存在且非空\n- 是否存在重复的pipeline_id\n\n验证错误会以状态码1退出，警告信息会显示但不会导致失败，这与运行时加载器的宽松行为保持一致。\n\n实践意义与应用场景\n\nNullBoiler的设计使其特别适合以下场景：\n\n复杂多步骤AI工作流：当单个智能体无法完成复杂任务，需要多个智能体协同工作，并且步骤之间存在依赖关系时，NullBoiler的编排能力可以确保工作流按预期执行。\n\n高可靠性要求：通过检查点、重试、断路器等机制，NullBoiler可以帮助构建能够优雅处理故障的AI系统，确保关键任务最终完成。\n\n多租户或并发场景：编排器的并发限制和调度策略可以有效管理资源使用，防止系统过载。\n\n可观测性需求：通过将追踪、编排和执行分离，每个组件都可以独立监控和优化，提高了系统的可观测性。\n\n总结与展望\n\nNullBoiler代表了AI基础设施向模块化、专业化方向发展的一个趋势。它不试图成为无所不能的框架，而是专注于做好编排这一件事。这种克制的设计哲学使得NullBoiler可以与各种追踪器和智能体运行时灵活组合，适应不同的应用场景。\n\n对于正在构建AI应用系统的开发者来说，NullBoiler提供了一个值得参考的架构范式：通过清晰的边界划分，让系统的每个部分都保持简单和可替换。随着AI智能体生态的成熟，这种模块化的编排方案可能会成为行业标准实践。