TaskRail是一个为AI辅助工程工作流设计的操作控制平面，通过显式的Postgres记录管理任务队列、阶段流转、重试机制和人工审核，让AI Agent成为可替换的工作节点。

TaskRail：AI辅助工程工作流的可观测控制平面\n\n## 背景：AI工程自动化的痛点\n\n随着大语言模型能力的快速发展，越来越多的团队开始尝试将AI Agent集成到软件开发流程中。然而，在实际落地过程中，一个核心问题始终困扰着开发者：Agent往往被赋予了过多的控制权——它们不仅执行任务，还负责管理工作流的状态流转。这种设计导致了几个典型问题：\n\n- 状态不可见：Agent内部的工作流逻辑如同黑盒，难以追踪和审计\n- 重试困难：一旦Agent执行失败，恢复成本高，难以精确定位问题阶段\n- 成本失控：缺乏对每次调用Token消耗和API费用的细粒度追踪\n- 人机协作断裂：人工审核介入点不明确，难以在关键环节进行把关\n\nTaskRail正是为解决这些问题而诞生的开源项目。\n\n## 核心理念：队列拥有工作流，而非Agent\n\nTaskRail的设计哲学可以用一句话概括："Agent不拥有工作流，队列才拥有。"（The agent does not own the workflow — the queue does.）\n\n这一理念彻底颠覆了传统的Agent驱动架构。在TaskRail中，所有的阶段定义、重试策略、审核回退、子任务分解、执行轨迹和状态转换都被显式地记录在PostgreSQL数据库中。Agent只是通过窄适配器接口接入的可替换工作节点。\n\n这种架构带来了几个关键优势：\n\n- 完全可观测：每个工作项（WorkItem）的完整生命周期都被持久化\n- 可审计：所有执行尝试（Claim）都被记录，包括报告、产物和执行轨迹\n- 可恢复：失败的工作项可以在任意阶段精确重试，无需从头开始\n- 成本透明：每次调用的成本都被单独追踪和汇总\n\n## 系统架构详解\n\n### 核心数据模型\n\nTaskRail围绕四个核心实体构建：\n\nWorkQueue（工作队列）\n\n定义了一个流水线（pipeline），包含多个阶段（stage），每个阶段配置了适配器类型和参数。队列定义从config/queues/*.yml文件加载，支持热更新。\n\nWorkItem（工作项）\n\n表示一个正在队列中流转的工作单元。具有状态（pending、claimed、completed、blocked、cancelled）和当前阶段名称。工作项可以携带任意JSON格式的输入数据。\n\nClaim（执行声明）\n\n记录一次适配器执行尝试的完整信息，包括：\n- 分配信息（哪个适配器、何时开始）\n- 执行报告（输出、日志、错误信息）\n- 产物（artifacts）\n- 执行轨迹（trace）\n\nPipe（管道）\n\n负责将一个队列中完成的工作项路由到另一个队列，可以选择性地复制指定产物作为下游队列的输入。这实现了复杂工作流的组合。\n\n### 适配器系统\n\nTaskRail支持多种适配器类型，每种适配器都返回标准化的AgentResult：\n\n- fake：确定性适配器，无外部调用，适合开发和测试\n- shell_script：执行本地Shell命令，将退出状态转换为产物\n- inline_claude：同步调用本地Claude CLI\n- codex：异步提交构建/修复任务到Codex CLI，轮询等待完成\n\n关键设计：转换逻辑位于引擎服务层，而非适配器内部。这意味着你可以在不修改适配器的情况下调整工作流规则。\n\n## 实际应用场景\n\n### 场景一：代码审查流水线\n\n假设你有一个代码审查队列，包含以下阶段：\n\n1. lint：使用RuboCop检查代码风格\n2. security_scan：使用Brakeman进行安全扫描\n3. test_ruby：运行Ruby测试套件\n4. test_tui：运行前端TUI测试\n5. docker_build：构建Docker镜像\n\n每个阶段都可以配置不同的适配器。例如，lint和security_scan可以使用shell_script适配器，而test_ruby可以使用codex适配器在隔离环境中运行。\n\n如果某个阶段失败，你可以：\n- 查看详细的执行轨迹和日志\n- 精确定位到失败的阶段\n- 修复问题后仅重试该阶段，无需重新运行已通过的阶段\n- 审核并批准特定产物进入下一阶段\n\n### 场景二：AI辅助开发任务\n\n想象一个AI辅助开发队列，工作流如下：\n\n1. spec_review：人工审核需求文档\n2. code_generation：使用Claude生成代码\n3. code_review：人工审核生成的代码\n4. test_generation：自动生成测试用例\n5. integration_test：运行集成测试\n\n在spec_review和code_review阶段，工作项会被标记为blocked状态，等待人工介入。审核者可以通过API或CLI提供反馈，工作流随后自动继续。\n\n## 成本追踪与可观测性\n\nTaskRail内置了细粒度的成本追踪功能：\n\n\nGET /api/v1/costs # 获取所有成本记录\nGET /api/v1/costs?period=today # 今日成本汇总\nGET /api/v1/costs/work_items/:id # 特定工作项的成本明细\n\n\nCLI同样提供了便捷的成本查询：\n\nbash\nbin/taskrail costs # 总成本概览\nbin/taskrail costs --today # 今日成本\nbin/taskrail costs --work-item ID # 单个工作项成本\n\n\n这种设计让团队能够：\n- 识别高成本的Agent调用模式\n- 优化Prompt设计以降低Token消耗\n- 为不同项目或团队分配预算\n- 生成详细的成本报告\n\n## 部署与使用\n\nTaskRail基于Ruby on Rails 8构建，使用PostgreSQL作为数据存储。部署非常简单：\n\nbash\n# 本地开发\nbundle install\ndocker compose up -d # 启动Postgres\nbin/rails db:prepare\nbin/rails db:seed\n\n# 完全容器化\ndocker compose up --build\n\n\n启动后，API服务器运行在localhost:3000，同时提供了一个Web UI用于可视化队列状态。\n\n### CLI工具\n\nTaskRail提供了功能丰富的CLI工具taskrail：\n\nbash\n# 队列管理\nbin/taskrail queues # 列出所有队列\nbin/taskrail stages development # 查看development队列的阶段\n\n# 工作项操作\nbin/taskrail submit --queue development --title \"My task\" --spec ./README.md\nbin/taskrail list --queue development\nbin/taskrail status WORK_ITEM_ID --traces\nbin/taskrail retry WORK_ITEM_ID\nbin/taskrail cancel WORK_ITEM_ID\nbin/taskrail answer WORK_ITEM_ID \"Use bearer tokens\"\n\n# 实时监控仪表板\nbin/taskrail dashboard --queue development --watch --refresh 5\n\n\n## 技术亮点与设计理念\n\n### 显式优于隐式\n\nTaskRail将工作流的每个环节都显式化——状态转换、重试逻辑、审核点、产物传递。这种设计虽然增加了初期配置复杂度，但极大地提升了系统的可维护性和可调试性。\n\n### 可替换的Agent\n\n由于Agent只是适配器背后的工作节点，你可以随时切换不同的模型或工具，而无需修改工作流定义。这为A/B测试和渐进式升级提供了便利。\n\n### 人机协作原生支持\n\n人工审核不是事后补丁，而是工作流的一等公民。blocked状态和answer API的设计让人工介入成为自然的工作流环节。\n\n## 总结与展望\n\nTaskRail代表了AI工程自动化的一种新范式：从"Agent中心"转向"队列中心"。这种架构转变对于需要高可靠性、可审计性和成本可控性的企业级AI应用尤为重要。\n\n随着AI Agent在软件开发中的角色越来越重要，类似TaskRail这样的控制平面将成为基础设施的关键组件。它解决了AI工程落地中最棘手的可观测性和可控性问题，为团队安全、高效地采用AI技术提供了坚实基础。\n\n对于正在探索AI辅助开发的团队，TaskRail值得认真评估。它不仅是一个工具，更是一种关于如何与AI协作的深思熟虑的架构哲学。

TaskRail：AI辅助工程工作流的可观测控制平面\n\n背景：AI工程自动化的痛点\n\n随着大语言模型能力的快速发展，越来越多的团队开始尝试将AI Agent集成到软件开发流程中。然而，在实际落地过程中，一个核心问题始终困扰着开发者：Agent往往被赋予了过多的控制权——它们不仅执行任务，还负责管理工作流的状态流转。这种设计导致了几个典型问题：\n\n- 状态不可见：Agent内部的工作流逻辑如同黑盒，难以追踪和审计\n- 重试困难：一旦Agent执行失败，恢复成本高，难以精确定位问题阶段\n- 成本失控：缺乏对每次调用Token消耗和API费用的细粒度追踪\n- 人机协作断裂：人工审核介入点不明确，难以在关键环节进行把关\n\nTaskRail正是为解决这些问题而诞生的开源项目。\n\n核心理念：队列拥有工作流，而非Agent\n\nTaskRail的设计哲学可以用一句话概括："Agent不拥有工作流，队列才拥有。"（The agent does not own the workflow — the queue does.）\n\n这一理念彻底颠覆了传统的Agent驱动架构。在TaskRail中，所有的阶段定义、重试策略、审核回退、子任务分解、执行轨迹和状态转换都被显式地记录在PostgreSQL数据库中。Agent只是通过窄适配器接口接入的可替换工作节点。\n\n这种架构带来了几个关键优势：\n\n- 完全可观测：每个工作项（WorkItem）的完整生命周期都被持久化\n- 可审计：所有执行尝试（Claim）都被记录，包括报告、产物和执行轨迹\n- 可恢复：失败的工作项可以在任意阶段精确重试，无需从头开始\n- 成本透明：每次调用的成本都被单独追踪和汇总\n\n系统架构详解\n\n核心数据模型\n\nTaskRail围绕四个核心实体构建：\n\nWorkQueue（工作队列）\n\n定义了一个流水线（pipeline），包含多个阶段（stage），每个阶段配置了适配器类型和参数。队列定义从config/queues/*.yml文件加载，支持热更新。\n\nWorkItem（工作项）\n\n表示一个正在队列中流转的工作单元。具有状态（pending、claimed、completed、blocked、cancelled）和当前阶段名称。工作项可以携带任意JSON格式的输入数据。\n\nClaim（执行声明）\n\n记录一次适配器执行尝试的完整信息，包括：\n- 分配信息（哪个适配器、何时开始）\n- 执行报告（输出、日志、错误信息）\n- 产物（artifacts）\n- 执行轨迹（trace）\n\nPipe（管道）\n\n负责将一个队列中完成的工作项路由到另一个队列，可以选择性地复制指定产物作为下游队列的输入。这实现了复杂工作流的组合。\n\n适配器系统\n\nTaskRail支持多种适配器类型，每种适配器都返回标准化的AgentResult：\n\n- fake：确定性适配器，无外部调用，适合开发和测试\n- shell_script：执行本地Shell命令，将退出状态转换为产物\n- inline_claude：同步调用本地Claude CLI\n- codex：异步提交构建/修复任务到Codex CLI，轮询等待完成\n\n关键设计：转换逻辑位于引擎服务层，而非适配器内部。这意味着你可以在不修改适配器的情况下调整工作流规则。\n\n实际应用场景\n\n场景一：代码审查流水线\n\n假设你有一个代码审查队列，包含以下阶段：\n\n1. lint：使用RuboCop检查代码风格\n2. security_scan：使用Brakeman进行安全扫描\n3. test_ruby：运行Ruby测试套件\n4. test_tui：运行前端TUI测试\n5. docker_build：构建Docker镜像\n\n每个阶段都可以配置不同的适配器。例如，lint和security_scan可以使用shell_script适配器，而test_ruby可以使用codex适配器在隔离环境中运行。\n\n如果某个阶段失败，你可以：\n- 查看详细的执行轨迹和日志\n- 精确定位到失败的阶段\n- 修复问题后仅重试该阶段，无需重新运行已通过的阶段\n- 审核并批准特定产物进入下一阶段\n\n场景二：AI辅助开发任务\n\n想象一个AI辅助开发队列，工作流如下：\n\n1. spec_review：人工审核需求文档\n2. code_generation：使用Claude生成代码\n3. code_review：人工审核生成的代码\n4. test_generation：自动生成测试用例\n5. integration_test：运行集成测试\n\n在spec_review和code_review阶段，工作项会被标记为blocked状态，等待人工介入。审核者可以通过API或CLI提供反馈，工作流随后自动继续。\n\n成本追踪与可观测性\n\nTaskRail内置了细粒度的成本追踪功能：\n\n\nGET /api/v1/costs 获取所有成本记录\nGET /api/v1/costs?period=today 今日成本汇总\nGET /api/v1/costs/work_items/:id 特定工作项的成本明细\n\n\nCLI同样提供了便捷的成本查询：\n\nbash\nbin/taskrail costs 总成本概览\nbin/taskrail costs --today 今日成本\nbin/taskrail costs --work-item ID 单个工作项成本\n\n\n这种设计让团队能够：\n- 识别高成本的Agent调用模式\n- 优化Prompt设计以降低Token消耗\n- 为不同项目或团队分配预算\n- 生成详细的成本报告\n\n部署与使用\n\nTaskRail基于Ruby on Rails 8构建，使用PostgreSQL作为数据存储。部署非常简单：\n\nbash\n本地开发\nbundle install\ndocker compose up -d 启动Postgres\nbin/rails db:prepare\nbin/rails db:seed\n\n完全容器化\ndocker compose up --build\n\n\n启动后，API服务器运行在localhost:3000，同时提供了一个Web UI用于可视化队列状态。\n\nCLI工具\n\nTaskRail提供了功能丰富的CLI工具taskrail：\n\nbash\n队列管理\nbin/taskrail queues 列出所有队列\nbin/taskrail stages development 查看development队列的阶段\n\n工作项操作\nbin/taskrail submit --queue development --title \"My task\" --spec ./README.md\nbin/taskrail list --queue development\nbin/taskrail status WORK_ITEM_ID --traces\nbin/taskrail retry WORK_ITEM_ID\nbin/taskrail cancel WORK_ITEM_ID\nbin/taskrail answer WORK_ITEM_ID \"Use bearer tokens\"\n\n实时监控仪表板\nbin/taskrail dashboard --queue development --watch --refresh 5\n\n\n技术亮点与设计理念\n\n显式优于隐式\n\nTaskRail将工作流的每个环节都显式化——状态转换、重试逻辑、审核点、产物传递。这种设计虽然增加了初期配置复杂度，但极大地提升了系统的可维护性和可调试性。\n\n可替换的Agent\n\n由于Agent只是适配器背后的工作节点，你可以随时切换不同的模型或工具，而无需修改工作流定义。这为A/B测试和渐进式升级提供了便利。\n\n人机协作原生支持\n\n人工审核不是事后补丁，而是工作流的一等公民。blocked状态和answer API的设计让人工介入成为自然的工作流环节。\n\n总结与展望\n\nTaskRail代表了AI工程自动化的一种新范式：从"Agent中心"转向"队列中心"。这种架构转变对于需要高可靠性、可审计性和成本可控性的企业级AI应用尤为重要。\n\n随着AI Agent在软件开发中的角色越来越重要，类似TaskRail这样的控制平面将成为基础设施的关键组件。它解决了AI工程落地中最棘手的可观测性和可控性问题，为团队安全、高效地采用AI技术提供了坚实基础。\n\n对于正在探索AI辅助开发的团队，TaskRail值得认真评估。它不仅是一个工具，更是一种关于如何与AI协作的深思熟虑的架构哲学。