Claude Task Master 的 WorkflowOrchestrator 设计用状态机编排 AI 驱动 TDD 工作流【免费下载链接】claude-task-masterAn AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-task-master导读本文围绕.taskmaster/docs/tdd-workflow-phase-1-orchestrator.md这一设计文档深入讲解 Claude Task Master 如何通过一个名为 WorkflowOrchestrator 的状态机把AI 会话从直接执行代码转变为按 RED → GREEN → COMMIT 三阶段被引导地执行工作单元。你会掌握它的架构模型、状态转换规则、MCP 工具接口、Git/Test 适配器职责边界、运行状态持久化方案以及它在当前仓库中packages/tm-core、apps/cli、mcp-server的真实落地形态从而可以直接在自己的项目中复刻这套AI 编排器设计。一、核心设计思想状态管理器而非代码执行器Phase 1 的 Objective 非常明确构建一个 WorkflowOrchestrator让它在 TDD 工作流中引导 AI 会话而不是直接执行代码。这意味着编排器与执行器彻底解耦——Claude Code或其他 AI 工具、人类开发者负责写测试、写代码、跑命令编排器只负责回答下一步该做什么、校验前置条件、记录进度、持久化状态。原文档给出了如下执行模型┌─────────────────────────────────────────────────────────────┐ │ Claude Code (MCP Client) │ │ - Queries what to do next │ │ - Executes work (writes tests, code, runs commands) │ │ - Reports completion │ └────────────────┬────────────────────────────────────────────┘ │ MCP Protocol ▼ ┌─────────────────────────────────────────────────────────────┐ │ WorkflowOrchestrator (tm-core) │ │ - Maintains state machine (RED → GREEN → COMMIT) │ │ - Returns work units with context │ │ - Validates preconditions │ │ - Records progress │ │ - Persists state for resumability │ └─────────────────────────────────────────────────────────────┘为什么采用这种方案原文档列出了五条理由这些理由至今仍是指引实现的原则关注点分离Separation of Concerns状态管理与代码执行分离编排器不关心测试框架细节执行器不关心流程推进复用现有工具Leverage Existing Tools直接利用 Claude Code 的原生能力读写文件、执行命令、git 操作而不是用代码重新实现一遍人在回路Human-in-the-Loop任意阶段都可以检查状态、人工介入实现更简单Simpler Implementation编排器是纯逻辑不需要集成任何 AI 模型执行器可替换Flexible ExecutorsClaude Code、人类、其他 AI 工具都可以消费同一个工作单元接口。二、WorkflowOrchestrator 服务接口设计原文档规划了编排器服务位于packages/tm-core/src/services/workflow-orchestrator.service.ts设计稿路径。在真实仓库中它落地为 workflow-orchestrator.ts类WorkflowOrchestrator由 workflow.service.ts 这个门面Facade统一对外暴露供 CLI 与 MCP 工具调用。职责原文档定义按子任务跟踪当前阶段RED/GREEN/COMMIT为每个阶段生成带上下文的工作单元Work Unit校验阶段完成标准在成功完成后推进状态机处理错误与重试逻辑持久化运行状态以支持断点续跑resumabilityAPI 契约原文档给出interface WorkflowOrchestrator { // Start a new autopilot run startRun(taskId: string, options?: RunOptions): PromiseRunContext; // Get next work unit to execute getNextWorkUnit(runId: string): PromiseWorkUnit | null; // Report work unit completion completeWorkUnit( runId: string, workUnitId: string, result: WorkUnitResult ): Promisevoid; // Get current run state getRunState(runId: string): PromiseRunState; // Pause/resume pauseRun(runId: string): Promisevoid; resumeRun(runId: string): Promisevoid; }工作单元WorkUnit是编排器与执行器之间的核心契约它把某个阶段要做的事连同执行所需的全部上下文打包交付interface WorkUnit { id: string; // Unique work unit ID phase: RED | GREEN | COMMIT; subtaskId: string; // e.g., 42.1 action: string; // Human-readable description context: WorkUnitContext; // All info needed to execute preconditions: Precondition[]; // Checks before execution }其中WorkUnitContext按阶段提供差异化上下文通用字段taskId、taskTitle、subtaskTitle、subtaskDescription、dependencies已完成子任务 ID 列表、testCommand如npm testRED 阶段testFile要创建的测试文件、testFramework如vitest、acceptanceCriteria验收标准列表GREEN 阶段testFile要让其通过的测试、implementationHints实现提示、expectedFiles可能修改的文件COMMIT 阶段commitMessage预生成提交信息、filesToCommitREDGREEN 阶段修改的文件。执行结果WorkUnitResult也按阶段结构化上报RED 阶段回传testsCreated与testsFailedGREEN 阶段回传testsPassed、filesModified、attemptsCOMMIT 阶段回传commitSha公共字段error与logs用于错误诊断。三、状态机逻辑阶段转换与规则3.1 主流程转换图原文档给出如下转换路径START → RED(subtask 1) → GREEN(subtask 1) → COMMIT(subtask 1) ↓ RED(subtask 2) ← ─ ─ ─ ┘ ↓ GREEN(subtask 2) ↓ COMMIT(subtask 2) ↓ (repeat for remaining subtasks) ↓ FINALIZE → END3.2 阶段规则Phase RulesRED只有测试已创建且处于失败状态才能转换到 GREENGREEN只有测试通过attempt maxAttempts才能转换到 COMMITCOMMIT只有提交成功才能转换到下一个子任务的 REDFINALIZE只有所有子任务完成才能进入。3.3 前置条件PreconditionsRED无未提交变更或来自上一个 GREEN 失败时已暂存的变更GREENRED 阶段完成测试存在且处于失败状态COMMITGREEN 阶段完成所有测试通过覆盖率满足阈值。3.4 仓库中的真实状态机实现从源码看实际落地时状态机扩展为五层主阶段 三层 TDD 阶段的两级结构。主阶段定义在 types.tsexport type WorkflowPhase | PREFLIGHT | BRANCH_SETUP | SUBTASK_LOOP | FINALIZE | COMPLETE; export type TDDPhase RED | GREEN | COMMIT;主阶段转换表在 workflow-orchestrator.ts 的defineTransitions()中定义共四条边PREFLIGHT --PREFLIGHT_COMPLETE-- BRANCH_SETUPBRANCH_SETUP --BRANCH_CREATED-- SUBTASK_LOOPSUBTASK_LOOP --ALL_SUBTASKS_COMPLETE-- FINALIZEFINALIZE --FINALIZE_COMPLETE-- COMPLETEtransition()方法workflow-orchestrator.ts是唯一入口非法事件会抛出Invalid transition: event from phaseERROR、ABORT、RETRY是跨阶段特殊事件在SUBTASK_LOOP内则委托给handleTDDPhaseTransition()处理 RED/GREEN/COMMIT 的细粒度流转workflow-orchestrator.ts。值得注意的两个实现细节RED 阶段测试全绿的特殊分支若 RED 阶段上报failed 0说明该功能已被实现编排器会发出tdd:feature-already-implemented事件直接把当前子任务标记为 completed 并推进对应原文档前置条件GREEN: 测试存在且失败的边界情况GREEN 强制零失败GREEN_PHASE_COMPLETE事件要求testResults.failed 0否则抛错对应原文档阶段规则GREEN 只有测试通过才能进入 COMMIT。3.5 守卫、重试与进度守卫GuardsStateTransition.guard与phaseGuards两个层次的守卫函数不满足条件时拒绝转换重试RetryRETRY事件与retryCurrentSubtask()会把当前子任务重置回 RED 阶段重新开始incrementAttempts()与hasExceededMaxAttempts()控制每个子任务的最大尝试次数CLI 默认 3 次见下文进度ProgressgetProgress()基于子任务 completed 状态计算{ completed, total, current, percentage }事件系统on/off/emit提供了完整的事件订阅机制事件类型见 types.ts包括workflow:started、tdd:red:started、subtask:failed、git:branch:created、state:persisted、progress:updated等二十余种便于日志、UI 与测试观察。四、MCP 集成把编排器暴露给 Claude Code4.1 设计稿中的 MCP 工具原文档规划了 6 个 MCP 工具// Start an autopilot run mcp__task_master_ai__autopilot_start(taskId: string, dryRun?: boolean) // Get next work unit mcp__task_master_ai__autopilot_next_work_unit(runId: string) // Complete current work unit mcp__task_master_ai__autopilot_complete_work_unit( runId: string, workUnitId: string, result: WorkUnitResult ) // Get run state mcp__task_master_ai__autopilot_get_state(runId: string) // Pause/resume mcp__task_master_ai__autopilot_pause(runId: string) mcp__task_master_ai__autopilot_resume(runId: string)4.2 仓库中的实际注册实际 MCP 服务端在 tool-registry.js 中注册了 8 个 autopilot 相关工具autopilot_start、autopilot_resume、autopilot_next、autopilot_status、autopilot_complete、autopilot_commit、autopilot_finalize、autopilot_abort。相比设计稿实际实现把获取状态拆成了autopilot_status把提交与收尾finalize以及中止abort独立成工具并把 pause/resume 合并为autopilot_resume。这与 Phase 1 的 Out of Scopegit 操作、PR 创建延迟到 Phase 2也保持一致——COMMIT 阶段由执行器完成 git 提交后通过autopilot_commit回报。这些 MCP 工具统一委托给WorkflowService门面见 workflow.service.ts该门面封装了WorkflowOrchestrator的完整生命周期并向上提供start()、resumeWorkflow()、getNextAction()、completePhase()、getStatus()等简化 APIMCP 层无需接触状态机细节。五、Git / Test 适配器只读校验不执行原文档对两个适配器的职责边界做了严格限定它们只负责读取与校验绝不执行命令。5.1 GitAdapter设计位置packages/tm-core/src/services/git-adapter.service.ts职责检查工作树状态clean/dirty校验分支状态读取 git 配置user、remote、default branch不执行git 命令那是执行器的职责仓库中的实现位于 git-adapter.ts封装了SimpleGit实例提供项目路径与 git 状态访问能力。它服务于 PREFLIGHT 阶段的前置条件校验——例如RED 阶段要求无未提交变更这一规则的判断就依赖它。5.2 TestResultValidatorTestAdapter 的落地形态设计稿中的 TestAdapter 职责为从 package.json 检测测试框架、解析测试输出failures/passes/coverage、校验覆盖率阈值、不运行测试。仓库中的 test-result-validator.ts 正是这一职责的落地它先用 zod 对测试结果做 schema 校验total必须等于passed failed skipped之和再提供阶段语义校验validateRedPhase()RED 阶段必须有至少一个失败测试validateGreenPhase()GREEN 阶段必须零失败。编排器通过setTestResultValidator()注入该适配器并在事件数据中附带adapters.testValidator布尔值方便外部观察适配器是否就绪见 workflow-orchestrator.ts。六、运行状态持久化可断点续跑的关键6.1 设计稿方案原文档规划存储位置为.taskmaster/reports/runs/runId/包含四个文件state.json—— 当前运行状态供续跑log.jsonl—— 事件流带时间戳的工作单元完成记录manifest.json—— 运行元数据work-units.json—— 本次运行生成的全部工作单元state.json示例{ runId: 2025-01-15-142033, taskId: 42, status: paused, currentPhase: GREEN, currentSubtask: 42.2, completedSubtasks: [42.1], failedSubtasks: [], checkpoint: { subtaskId: 42.2, phase: GREEN, attemptNumber: 2 }, startTime: 2025-01-15T14:20:33Z, lastUpdateTime: 2025-01-15T14:35:12Z }6.2 仓库中的实际存储实现时 workflow-state-manager.ts 做了重要演进为避免 git 冲突并支持多 worktree状态被存到全局用户目录~/.taskmaster/{project-id}/sessions/workflow-state.json其中{project-id}由项目绝对路径清洗生成形如-data-web-disk1-...。同时每个状态文件在写入前保留最多 5 份备份backups/目录maxBackups可配置使用steno的原子写入器避免并发写入导致状态损坏编排器暴露getState()/restoreState()workflow-orchestrator.ts与enableAutoPersist()自动持久化回调每次转换后自动落盘canResumeFromState()workflow-orchestrator.ts在恢复前校验阶段合法性、context 结构与必填字段防止脏状态被恢复。另外仓库里还有独立的 workflow-activity-logger.ts承担设计稿中log.jsonl事件流的职责。七、CLI 集成autopilot 子命令族原文档要求更新autopilot.command.ts、增加--interactive模式与--resume标志。仓库中的实际形态是 apps/cli/src/commands/autopilot/index.ts 下的AutopilotCommand别名ap注册了 8 个子命令子命令作用start taskId初始化并启动 TDD 工作流resume恢复已暂停的工作流next获取下一个要执行的动作complete带结果校验地完成当前阶段commit创建提交status显示当前状态finalize收尾工作流abort中止工作流全局选项包括--json机器可解析输出、-v/--verbose、-p/--project-root。7.1 start 命令的执行链以 start.command.ts 为例可看到完整的校验与启动链路用MainTaskIdSchema校验 taskId 格式通过createTmCore({ projectPath })初始化 tm-core 门面调用tmCore.workflow.hasWorkflow()检查是否已有工作流状态——存在且未传--force时报错并提示改用autopilot resume读取当前 tagtmCore.config.getActiveTag()与 auth 上下文中的orgSlugAPI 存储模式分支命名用加载任务校验任务存在且包含子任务无子任务时提示先task-master expand --idtaskId解析--max-attempts默认3调用tmCore.workflow.start({ taskId, taskTitle, subtasks, maxAttempts, force, tag, orgSlug })由门面内部完成 git、编排器与状态更新。7.2 next 命令获取下一步动作next.command.ts 展示了查询下一步的标准流程先检查工作流是否存在然后resume()恢复会话、getStatus()读取状态、getNextAction()获取建议动作。输出包含action、description、phase、tddPhase、branchName、当前子任务id/title/attempts、nextSteps与lastTestResults--json模式下直接输出结构化对象供 Agent 解析。getNextAction()的实现位于 workflow.service.ts它根据编排器当前主阶段与 TDD 阶段生成人类可读的下一步指引如为子任务 42.1 编写失败测试这正是引导而非执行理念在 CLI 层的体现。八、端到端使用流程原文档给出了完整的交互示例结合上文实现一次典型的 autopilot 会话如下# 终端 1Claude Code 会话 $ claude # 在 Claude Code 中通过 MCP Start autopilot for task 42 [Calls mcp__task_master_ai__autopilot_start(42)] → Run started: run-2025-01-15-142033 Get next work unit [Calls mcp__task_master_ai__autopilot_next_work_unit(run-2025-01-15-142033)] → Work unit: RED phase for subtask 42.1 → Action: Generate failing tests for metrics schema → Test file: src/__tests__/schema.test.js → Framework: vitest [Claude Code creates test file, runs tests] Complete work unit [Calls mcp__task_master_ai__autopilot_complete_work_unit( run-2025-01-15-142033, workUnit-42.1-RED, { success: true, testsCreated: [src/__tests__/schema.test.js], testsFailed: 3 } )] → Work unit completed. State saved. Get next work unit → Work unit: GREEN phase for subtask 42.1 → Action: Implement code to pass failing tests → Test file: src/__tests__/schema.test.js → Expected implementation: src/schema.js [Claude Code implements schema.js, runs tests, confirms all pass] Complete work unit → Work unit completed. Ready for COMMIT. Get next work unit → Work unit: COMMIT phase for subtask 42.1 → Commit message: feat(metrics): add metrics schema (task 42.1) → Files to commit: src/__tests__/schema.test.js, src/schema.js [Claude Code stages files and commits] Complete work unit → Subtask 42.1 complete! Moving to 42.2...这一流程的前置阶段dry-run 计划、preflight 检测在 tdd-workflow-phase-0-spike.md 中已有落地可作为阅读本文的上下文补充。九、实施计划、成功标准与范围界定9.1 实施计划原文档六步WorkflowOrchestrator 骨架创建服务与接口、实现状态机转换逻辑、加入 run 状态持久化state.json、log.jsonl、编写状态机单元测试工作单元生成实现getNextWorkUnit()与上下文组装分别生成 RED测试文件路径、验收标准、GREEN实现提示、COMMIT提交信息阶段工作单元Git/Test 适配器创建 GitAdapter 与 TestAdapter仅状态检查/输出解析、基于适配器做前置条件校验、编写适配器单元测试MCP 集成在packages/mcp-server/src/tools/添加工具定义、把 WorkflowOrchestrator 接入 MCP 工具、通过 Claude Code 实测、在 CLAUDE.md 记录 MCP 工作流CLI 集成让 autopilot 命令调用编排器、增加交互模式、增加--resume标志、端到端测试集成测试创建含 2~3 个子任务的测试任务、完整跑一遍 start → get work unit → complete → repeat、验证状态持久化与续跑、覆盖失败场景测试失败、git 问题。9.2 成功标准编排器能为所有阶段生成工作单元MCP 工具允许 Claude Code 查询并完成工作单元状态在工作单元完成之间正确持久化运行可从检查点暂停与恢复适配器只校验前置条件而不执行命令端到端Claude Code 能通过工作单元完成一个简单任务。9.3 Out of ScopePhase 1实际的 git 操作建分支、提交——由执行器处理实际的测试执行——由执行器处理PR 创建——推迟到 Phase 2TUI 界面——推迟到 Phase 3覆盖率强制——推迟到 Phase 2。后续阶段规划可见 tdd-workflow-phase-2-pr-resumability.mdPhase 2 将加入通过ghCLI 创建 PR、覆盖率强制、增强的错误恢复与完整的续跑测试。十、依赖与实施成本原文档明确了编排器依赖的既有组件现有 TaskService任务加载、状态更新现有 PreflightChecker环境校验现有 TaskLoaderService依赖排序MCP server 基础设施对应地workflow.service.ts 通过TaskStatusUpdater接口解耦任务状态更新WorkflowActivityLogger记录活动日志WorkflowStateManager负责持久化共同构成完整闭环。原文档估算 Phase 1 工期为7-10 天。十一、验证与测试编排器带有完整的单元测试 workflow-orchestrator.spec.ts覆盖阶段转换、TDD 阶段推进、特殊事件处理与状态恢复等场景TestResultValidator也有独立的 test-result-validator.test.ts 验证各阶段语义。如果你要在自己的项目中复刻这套设计建议按同样的粒度组织测试先测状态机转换表与非法转换抛错再测 RED/GREEN/COMMIT 各阶段的完成判定最后测状态序列化-恢复的往返一致性。【免费下载链接】claude-task-masterAn AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-task-master创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考