Belt：面向自主本地智能体的状态机工作流引擎

Belt是一个基于Rust开发的自主开发工作流引擎，通过YAML配置驱动和8阶段状态机管理，实现外部系统（GitHub、Jira等）与LLM智能体的无缝集成，为自动化软件开发提供了全新的架构思路。

背景：自动化开发的架构困境\n\n随着大型语言模型能力的不断提升，基于AI的自动化软件开发工具正在快速涌现。从GitHub Copilot到Claude Code，从Cursor到各类代码生成工具，开发者们正在经历一场由AI驱动的生产力革命。然而，这些工具往往面临一个共同的架构挑战：如何将外部系统（如GitHub Issues、Jira工单）与LLM智能体有效连接，并确保整个流程可控、可观测、可维护？\n\n传统的自动化方案通常采用事件驱动或简单的脚本编排，但在复杂的开发场景中，这些方案往往难以处理状态管理、错误恢复、人工介入等关键问题。一个健壮的自动化开发系统，需要具备清晰的状态流转机制、灵活的工作流定义能力，以及对多种LLM后端的适配支持。\n\n## Belt的核心设计理念\n\nBelt项目以"传送带"为隐喻，将开发工作流抽象为一条单向流水线：问题从一端进入，经过一系列处理后，从另一端输出结果。如果处理过程中发现缺少必要信息，系统会自动创建新的工作项并将其重新放回传送带。\n\n### 架构分层与模块化设计\n\nBelt采用清晰的分层架构，将系统划分为多个独立的crate：\n\n- belt-core：核心trait、状态机和队列逻辑，零外部依赖\n- belt-infra：DataSource/AgentRuntime实现、SQLite持久化、工作区管理\n- belt-daemon：执行循环、cron引擎、并发控制\n- belt-cli：基于clap的命令行入口\n\n这种分层设计遵循依赖关系：belt-cli → belt-daemon → belt-infra → belt-core，其中belt-core仅暴露trait而不依赖具体实现，确保了系统的可测试性和可扩展性。\n\n### 8阶段状态机\n\nBelt的核心是一个精确定义的8阶段状态机，每个工作项在其生命周期中会经历以下状态流转：\n\n\nDataSource.collect() → Pending → Ready → Running → Completed → Done\n ↓\n → HITL（需要人工介入）\n → Failed（执行失败）\n → Skipped（跳过）\n\n\n这种明确的状态划分带来了多个好处：\n\n- 可观测性：每个工作项的状态清晰可见，便于监控和调试\n- 容错性：失败状态允许系统重试或人工介入\n- 灵活性：HITL（Human-in-the-Loop）机制确保关键决策点有人工审核\n\n## 核心组件详解\n\n### Workspace：工作流定义的载体\n\n在Belt中，Workspace是基本的配置单元，每个Workspace对应一个代码仓库，并通过YAML文件定义自己的工作流。这种设计使得不同项目可以采用不同的自动化策略，而无需修改核心系统。\n\n### DataSource：外部系统的抽象层\n\nDataSource组件负责与外部系统（如GitHub、Jira）交互，提供两个核心操作：\n\n- collect()：从外部系统收集待处理的工作项\n- context()：获取工作项的上下文信息\n\n这种抽象设计的关键优势在于：新增一种外部系统支持只需实现DataSource trait，无需修改核心代码。这意味着Belt可以轻松适配企业内部的各种工单系统或项目管理工具。\n\n### AgentRuntime：LLM后端的统一接口\n\nAgentRuntime为不同的LLM提供商（Claude、Gemini、Codex等）提供了统一的抽象接口。与DataSource类似，新增LLM支持只需实现AgentRuntime trait，实现了真正的后端无关性。\n\n### Cron Engine：定时任务与质量保障\n\n除了事件驱动的工作流，Belt还内置了Cron引擎，支持两类定时任务：\n\n- 基础设施维护：如清理过期工作区、归档已完成任务\n- 质量循环：如代码评估、差距检测（gap-detection）\n\n这种设计使得Belt不仅能响应外部事件，还能主动执行预防性维护和质量保障工作。\n\n## 使用场景与工作流程\n\nBelt的典型使用流程如下：\n\n1. 注册工作区：通过belt workspace add --config workspace.yaml将项目纳入Belt管理\n2. 启动守护进程：belt start启动后台服务，开始监听外部事件\n3. 监控状态：belt status --format rich查看当前系统状态\n4. 队列操作：通过belt queue系列命令管理任务队列\n\n### 人工介入机制\n\n当自动化流程遇到需要人工判断的情况时，可以通过以下方式处理：\n\nbash\nbelt queue hitl $WORK_ID --reason \"需要人工审核代码变更\"\n\n\n这种机制确保了自动化与人工监督的平衡，避免了完全无人值守可能带来的风险。\n\n## 技术选型与实现细节\n\nBelt选择Rust作为实现语言，这一决策带来了多方面的优势：\n\n- 内存安全：Rust的所有权系统消除了大量运行时错误\n- 并发性能：无锁数据结构和异步运行时支持高并发场景\n- 跨平台：单二进制文件部署，支持macOS、Linux和Windows\n\n项目采用Apache-2.0许可证开源，体现了作者对开源社区的贡献意愿。\n\n## 与现有方案的对比\n\n相比现有的自动化开发工具，Belt具有以下差异化特点：\n\n| 特性 | Belt | 传统CI/CD | 专用AI工具 |\n|------|------|-----------|-----------|\n| 状态机管理 | 内置8阶段状态机 | 通常无 | 视工具而定 |\n| LLM后端适配 | 抽象接口，易于扩展 | 不适用 | 通常锁定单一厂商 |\n| 外部系统集成 | DataSource抽象 | 依赖webhook | 通常有限 |\n| 人工介入机制 | 原生HITL支持 | 需额外实现 | 视工具而定 |\n| 本地执行 | 支持 | 通常云端 | 混合模式 |\n\n这种架构设计使得Belt特别适合需要高度定制化、强调数据隐私、或需要与内部系统深度集成的场景。\n\n## 实际应用价值\n\nBelt的发布为自动化软件开发领域提供了新的思路：\n\n1. 企业级自动化：通过模块化架构和状态机管理，满足企业级应用对可靠性和可维护性的要求\n2. 多LLM策略：避免对单一AI提供商的依赖，可根据任务特点选择最适合的模型\n3. 渐进式采用：可以从单个仓库开始试用，逐步扩展到整个组织\n4. 数据隐私：本地执行模式确保敏感代码不会离开内部环境\n\n## 结语\n\nBelt项目展示了一种将传统软件工程最佳实践（状态机、分层架构、依赖倒置）与AI能力相结合的新思路。它不是一个简单的"AI代码生成工具"，而是一个完整的自动化开发工作流引擎。对于希望在大规模软件开发中引入AI自动化、同时又需要保持流程可控性的团队来说，Belt提供了一个值得深入研究的解决方案。\n\n随着项目的持续发展和社区贡献的增加，Belt有望成为自动化软件开发领域的重要基础设施。

背景：自动化开发的架构困境\n\n随着大型语言模型能力的不断提升，基于AI的自动化软件开发工具正在快速涌现。从GitHub Copilot到Claude Code，从Cursor到各类代码生成工具，开发者们正在经历一场由AI驱动的生产力革命。然而，这些工具往往面临一个共同的架构挑战：如何将外部系统（如GitHub Issues、Jira工单）与LLM智能体有效连接，并确保整个流程可控、可观测、可维护？\n\n传统的自动化方案通常采用事件驱动或简单的脚本编排，但在复杂的开发场景中，这些方案往往难以处理状态管理、错误恢复、人工介入等关键问题。一个健壮的自动化开发系统，需要具备清晰的状态流转机制、灵活的工作流定义能力，以及对多种LLM后端的适配支持。\n\nBelt的核心设计理念\n\nBelt项目以"传送带"为隐喻，将开发工作流抽象为一条单向流水线：问题从一端进入，经过一系列处理后，从另一端输出结果。如果处理过程中发现缺少必要信息，系统会自动创建新的工作项并将其重新放回传送带。\n\n架构分层与模块化设计\n\nBelt采用清晰的分层架构，将系统划分为多个独立的crate：\n\n- belt-core：核心trait、状态机和队列逻辑，零外部依赖\n- belt-infra：DataSource/AgentRuntime实现、SQLite持久化、工作区管理\n- belt-daemon：执行循环、cron引擎、并发控制\n- belt-cli：基于clap的命令行入口\n\n这种分层设计遵循依赖关系：belt-cli → belt-daemon → belt-infra → belt-core，其中belt-core仅暴露trait而不依赖具体实现，确保了系统的可测试性和可扩展性。\n\n8阶段状态机\n\nBelt的核心是一个精确定义的8阶段状态机，每个工作项在其生命周期中会经历以下状态流转：\n\n\nDataSource.collect() → Pending → Ready → Running → Completed → Done\n ↓\n → HITL（需要人工介入）\n → Failed（执行失败）\n → Skipped（跳过）\n\n\n这种明确的状态划分带来了多个好处：\n\n- 可观测性：每个工作项的状态清晰可见，便于监控和调试\n- 容错性：失败状态允许系统重试或人工介入\n- 灵活性：HITL（Human-in-the-Loop）机制确保关键决策点有人工审核\n\n核心组件详解\n\nWorkspace：工作流定义的载体\n\n在Belt中，Workspace是基本的配置单元，每个Workspace对应一个代码仓库，并通过YAML文件定义自己的工作流。这种设计使得不同项目可以采用不同的自动化策略，而无需修改核心系统。\n\nDataSource：外部系统的抽象层\n\nDataSource组件负责与外部系统（如GitHub、Jira）交互，提供两个核心操作：\n\n- collect()：从外部系统收集待处理的工作项\n- context()：获取工作项的上下文信息\n\n这种抽象设计的关键优势在于：新增一种外部系统支持只需实现DataSource trait，无需修改核心代码。这意味着Belt可以轻松适配企业内部的各种工单系统或项目管理工具。\n\nAgentRuntime：LLM后端的统一接口\n\nAgentRuntime为不同的LLM提供商（Claude、Gemini、Codex等）提供了统一的抽象接口。与DataSource类似，新增LLM支持只需实现AgentRuntime trait，实现了真正的后端无关性。\n\nCron Engine：定时任务与质量保障\n\n除了事件驱动的工作流，Belt还内置了Cron引擎，支持两类定时任务：\n\n- 基础设施维护：如清理过期工作区、归档已完成任务\n- 质量循环：如代码评估、差距检测（gap-detection）\n\n这种设计使得Belt不仅能响应外部事件，还能主动执行预防性维护和质量保障工作。\n\n使用场景与工作流程\n\nBelt的典型使用流程如下：\n\n1. 注册工作区：通过belt workspace add --config workspace.yaml将项目纳入Belt管理\n2. 启动守护进程：belt start启动后台服务，开始监听外部事件\n3. 监控状态：belt status --format rich查看当前系统状态\n4. 队列操作：通过belt queue系列命令管理任务队列\n\n人工介入机制\n\n当自动化流程遇到需要人工判断的情况时，可以通过以下方式处理：\n\nbash\nbelt queue hitl $WORK_ID --reason \"需要人工审核代码变更\"\n\n\n这种机制确保了自动化与人工监督的平衡，避免了完全无人值守可能带来的风险。\n\n技术选型与实现细节\n\nBelt选择Rust作为实现语言，这一决策带来了多方面的优势：\n\n- 内存安全：Rust的所有权系统消除了大量运行时错误\n- 并发性能：无锁数据结构和异步运行时支持高并发场景\n- 跨平台：单二进制文件部署，支持macOS、Linux和Windows\n\n项目采用Apache-2.0许可证开源，体现了作者对开源社区的贡献意愿。\n\n与现有方案的对比\n\n相比现有的自动化开发工具，Belt具有以下差异化特点：\n\n| 特性 | Belt | 传统CI/CD | 专用AI工具 |\n|------|------|-----------|-----------|\n| 状态机管理 | 内置8阶段状态机 | 通常无 | 视工具而定 |\n| LLM后端适配 | 抽象接口，易于扩展 | 不适用 | 通常锁定单一厂商 |\n| 外部系统集成 | DataSource抽象 | 依赖webhook | 通常有限 |\n| 人工介入机制 | 原生HITL支持 | 需额外实现 | 视工具而定 |\n| 本地执行 | 支持 | 通常云端 | 混合模式 |\n\n这种架构设计使得Belt特别适合需要高度定制化、强调数据隐私、或需要与内部系统深度集成的场景。\n\n实际应用价值\n\nBelt的发布为自动化软件开发领域提供了新的思路：\n\n1. 企业级自动化：通过模块化架构和状态机管理，满足企业级应用对可靠性和可维护性的要求\n2. 多LLM策略：避免对单一AI提供商的依赖，可根据任务特点选择最适合的模型\n3. 渐进式采用：可以从单个仓库开始试用，逐步扩展到整个组织\n4. 数据隐私：本地执行模式确保敏感代码不会离开内部环境\n\n结语\n\nBelt项目展示了一种将传统软件工程最佳实践（状态机、分层架构、依赖倒置）与AI能力相结合的新思路。它不是一个简单的"AI代码生成工具"，而是一个完整的自动化开发工作流引擎。对于希望在大规模软件开发中引入AI自动化、同时又需要保持流程可控性的团队来说，Belt提供了一个值得深入研究的解决方案。\n\n随着项目的持续发展和社区贡献的增加，Belt有望成为自动化软件开发领域的重要基础设施。