# Railyard：面向长期运行的 AI Agent 项目的确定性工作流框架 > 一个便携式 Agent 工作流脚手架，通过 SQLite 持久化、角色隔离和显式审查门控，解决多 Agent 长期协作中的上下文爆炸、状态丢失和质量控制问题。 - 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm) - 发布时间: 2026-06-02T10:44:31.000Z - 最近活动: 2026-06-02T10:54:24.989Z - 热度: 152.8 - 关键词: AI Agent, 工作流框架, 多Agent协作, SQLite, 任务管理, 角色隔离, MCP, 确定性保障, 审查门控 - 页面链接: https://www.zingnex.cn/forum/thread/railyard-ai-agent - Canonical: https://www.zingnex.cn/forum/thread/railyard-ai-agent - Markdown 来源: ingested_event --- # Railyard：面向长期运行的 AI Agent 项目的确定性工作流框架 随着 AI Agent 在软件开发、内容创作、数据分析等领域的深入应用，一个核心挑战逐渐浮现：如何让多个 Agent 在长期运行的项目中高效协作，同时保持工作质量和工作状态的可控性？Railyard 项目正是为解决这一问题而设计的确定性工作流框架。 ## 原作者与来源 - **原作者/维护者**：yjwipod-1 - **来源平台**：GitHub - **原始标题**：railyard - **原始链接**：https://github.com/yjwipod-1/railyard - **发布时间**：2026-06-02 ## 项目理念与命名由来 Railyard（铁路调车场）的命名本身就揭示了其核心设计理念。在铁路系统中，调车场是一个复杂的枢纽，多列火车在各自的轨道上并行运行，通过道岔和信号进行协调，而不是让每列火车都掌握整个地图。 这正是 Railyard 框架的设计哲学：Agent 在限定范围内运行，通过结构化的轨道、切换点和审查站进行协调，而不是让 Agent 自由地在整个项目中漫游。 ## 核心问题：为什么需要 Railyard ### 上下文窗口爆炸 传统的多 Agent 设置通常将所有上下文放在一个会话中。随着项目推进，Agent 因为携带了整个项目历史而难以跟踪真正重要的信息。Railyard 通过角色隔离解决这个问题：Runner 只看到单个任务票，Architect 只看到轨道级别的工作，Planner 只看到跨轨道的视图。 ### 上下文污染 系统实现细节经常泄露到领域推理中，或者领域逻辑污染系统决策。Railyard 将 System 和 Domain 分离到独立的轨道中，跨轨道的影响通过显式依赖声明发生，而非共享上下文。 ### 会话间状态丢失 传统方式下，Agent 在会话结束时忘记一切。Railyard 将史诗、任务票、状态、声明、结果和审查保存在 SQLite 中，任何会话都可以从持久状态恢复。 ### 缺乏质量门控 在传统流程中，Agent 的工作直接呈现给用户，没有经过适当的审查。Railyard 建立了从 Runner 到 Architect 到 Planner 再到 Human 的审查流程。 ## 架构设计：角色与职责 Railyard 定义了清晰的角色分工，每个角色都有明确的职责范围： ### Human（人类决策者） Human 位于每个决策链的顶端。这不是事后添加的防护措施，而是结构性的承诺。Human 不需要审查每个任务票或批准每个 Runner 输出，而是在最高抽象层次运作： - 与 Planner 一起设定项目方向 - 审查 Planner 级别的摘要，而非原始任务输出 - 对架构决策、范围变更和跨轨道权衡做出最终决定 - 可以在任何层级介入，但不需要监控每个层级 ### Planner（规划者） Planner 负责协调跨轨道的决策，管理史诗（Epic）级别的规划，确保不同轨道之间的工作协调一致。 ### Architect（架构师） 每个轨道都有自己的 Architect，负责管理该轨道的就绪状态和审查工作。Architect 决定哪些任务票可以进入执行阶段，并审查 Runner 的输出。 ### Runner（执行者） Runner 在限定的任务票范围内执行具体工作。他们接收角色定义、任务票规范和相关参考资料，不依赖先前的对话历史，因此新会话可以执行任务并产生干净的输出。 ## 核心概念：轨道与任务票 ### 轨道（Lane） Railyard 将工作分离到不同的轨道中，目前定义了两个主要轨道： - **System 轨道**：处理工具、存储、模式、集成、自动化、平台机制 - **Domain 轨道**：处理产品逻辑、分析、内容生成、验证规则、交付语义 每个轨道有独立的 Architect 和 Runner，轨道之间的依赖通过显式声明管理。 ### 史诗（Epic） 史诗是大型工作单元的容器，包含多个相关的任务票。史诗在 SQLite 中持久化，可以跨会话追踪进度。 ### 任务票（Ticket） 任务票是分配给 Runner 的具体工作单元。每个任务票包含： - 任务描述和范围 - 所属轨道和史诗 - 状态（待办、进行中、审查中、完成等） - 依赖关系 - 结果和审查记录 ## 确定性保障机制 Railyard 是一个 Agent 框架，但并非每个部分都是 Agent 化的。Agent 处理推理、生成和审查，而围绕它们的保障机制是确定性的： ### 任务状态转换 任务状态遵循固定的状态值，确保状态转换的可预测性。 ### 可见性规则 Runner 只能看到就绪状态的任务票，防止 Agent 处理不适当的任务。 ### 轨道边界 System 和 Domain 关注点通过轨道边界保持分离。 ### 跨轨道依赖 依赖关系显式声明并在任务票就绪时强制执行。 ### 审查流程 工作从 Runner 向上流向 Architect，再到 Planner，最后到 Human。 ## MCP-lite 工具接口 Railyard v0.3 引入了可选的 MCP-lite stdio 工具接口，这是一个对现有 helper 支持的工作流契约的轻量级封装，而非替代工作流引擎。 SQLite 仍然是规范的工作流状态，helper 函数仍然是生命周期权威。MCP 工具暴露了 Planner、Architect 或 Runner 原本通过 helper 脚本访问的相同受限操作： ### 读取操作 - `resolve_lane`：解析轨道 - `get_ticket`：获取任务票 - `list_tickets`：列出任务票 - `next_ticket`：获取下一个任务票 - `get_epic`：获取史诗 - `list_open_epics`：列出开放的史诗 - `next_open_epic`：获取下一个开放的史诗 ### 检查操作 - `list_ticket_events`：列出任务票事件 - `get_workflow_schema_version`：获取工作流模式版本 ### 调度操作 - `dispatch_next_runner`：调度下一个 Runner ### 生命周期写入 - `claim_ticket`：认领任务票 - `recover_stale_ticket`：恢复陈旧任务票 - `start_review`：开始审查 - `mark_runner_result`：标记 Runner 结果 - `mark_review_result`：标记审查结果 ### 验证操作 - `validate_result_payload`：验证结果负载 - `validate_ticket_state`：验证任务票状态 ## 执行配置文件与失败分类 Railyard v0.6 引入了执行配置文件和标准化的失败分类法，增强了执行可观测性。 ### 执行配置文件提示 Railyard Agent 应该指示其置信度水平（高、中、低）并在结果中提供支持证据。配置文件提示（如 fast、strong、local）是调度适配器的建议性路由提示，不是自动模型路由。 ### 失败分类法 当 Runner 无法完成任务时，使用定义好的失败分类法报告阻塞： - `permission_denied`：权限被拒绝 - `command_failed`：命令失败 - `sandbox_boundary`：沙箱边界 - `authorization_required`：需要授权 - `environment_issue`：环境问题 - `unresolved_dependency`：未解决的依赖 这种标准化的失败分类确保了阻塞是可操作的。 ## 使用场景 ### 场景一：长期软件开发项目 在需要数周或数月完成的软件开发项目中，Railyard 可以帮助团队管理复杂的任务依赖关系，确保代码审查和质量控制。 ### 场景二：多 Agent 内容创作 在需要多个 Agent 协作的内容创作项目中，Railyard 可以协调研究、写作、编辑等不同角色的工作。 ### 场景三：AI 辅助研究 在需要多步骤分析和验证的研究项目中，Railyard 可以确保每个步骤都经过适当的审查和记录。 ## 总结与展望 Railyard 为长期运行的 AI Agent 项目提供了一个结构化的工作流框架。通过角色隔离、确定性保障和持久化状态，它解决了多 Agent 协作中的核心挑战。 对于希望构建可扩展、可维护的 AI Agent 系统的团队来说，Railyard 提供了一个经过深思熟虑的架构蓝图。它不是 Agent 运行时或托管服务，而是一套可以复制到任何 Agent 项目中的工作流结构、SQLite 模式、模板和辅助脚本。 随着 AI Agent 在更多领域的应用，像 Railyard 这样的框架将变得越来越重要，帮助我们在享受 AI 自动化的便利的同时，保持对工作流程的控制和质量保障。