Claude Task Master 的 WorkflowOrchestrator 设计：用状态机编排 AI 驱动 TDD 工作流-创锋一号

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 Executors）：Claude 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）
校验阶段完成标准
在成功完成后推进状态机
处理错误与重试逻辑
持久化运行状态以支持断点续跑（resumability）

API 契约（原文档给出）：

interface WorkflowOrchestrator { // Start a new autopilot run startRun(taskId: string, options?: RunOptions): Promise<RunContext>; // Get next work unit to execute getNextWorkUnit(runId: string): Promise<WorkUnit | null>; // Report work unit completion completeWorkUnit( runId: string, workUnitId: string, result: WorkUnitResult ): Promise<void>; // Get current run state getRunState(runId: string): Promise<RunState>; // Pause/resume pauseRun(runId: string): Promise<void>; resumeRun(runId: string): Promise<void>; }

工作单元（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 test"）；
RED 阶段：testFile（要创建的测试文件）、testFramework（如"vitest"）、acceptanceCriteria（验收标准列表）；
GREEN 阶段：testFile（要让其通过的测试）、implementationHints（实现提示）、expectedFiles（可能修改的文件）；
COMMIT 阶段：commitMessage（预生成提交信息）、filesToCommit（RED+GREEN 阶段修改的文件）。

执行结果（WorkUnitResult）也按阶段结构化上报：RED 阶段回传testsCreated与testsFailed；GREEN 阶段回传testsPassed、filesModified、attempts；COMMIT 阶段回传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 → END

3.2 阶段规则（Phase Rules）

RED：只有"测试已创建且处于失败状态"才能转换到 GREEN；
GREEN：只有"测试通过（attempt < maxAttempts）"才能转换到 COMMIT；
COMMIT：只有"提交成功"才能转换到下一个子任务的 RED；
FINALIZE：只有"所有子任务完成"才能进入。

3.3 前置条件（Preconditions）

RED：无未提交变更（或来自上一个 GREEN 失败时已暂存的变更）；
GREEN：RED 阶段完成，测试存在且处于失败状态；
COMMIT：GREEN 阶段完成，所有测试通过，覆盖率满足阈值。

3.4 仓库中的真实状态机实现

从源码看，实际落地时状态机扩展为五层主阶段 + 三层 TDD 阶段的两级结构。主阶段定义在 types.ts：

export type WorkflowPhase = | 'PREFLIGHT' | 'BRANCH_SETUP' | 'SUBTASK_LOOP' | 'FINALIZE' | 'COMPLETE'; export type TDDPhase = 'RED' | 'GREEN' | 'COMMIT';

主阶段转换表在 workflow-orchestrator.ts 的defineTransitions()中定义，共四条边：

PREFLIGHT --PREFLIGHT_COMPLETE--> BRANCH_SETUP
BRANCH_SETUP --BRANCH_CREATED--> SUBTASK_LOOP
SUBTASK_LOOP --ALL_SUBTASKS_COMPLETE--> FINALIZE
FINALIZE --FINALIZE_COMPLETE--> COMPLETE

transition()方法（workflow-orchestrator.ts）是唯一入口：非法事件会抛出Invalid transition: <event> from <phase>；ERROR、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 守卫、重试与进度

守卫（Guards）：StateTransition.guard与phaseGuards两个层次的守卫函数，不满足条件时拒绝转换；
重试（Retry）：RETRY事件与retryCurrentSubtask()会把当前子任务重置回 RED 阶段重新开始；incrementAttempts()与hasExceededMaxAttempts()控制每个子任务的最大尝试次数（CLI 默认 3 次，见下文）；
进度（Progress）：getProgress()基于子任务 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 Code

4.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 Scope（git 操作、PR 创建延迟到 Phase 2）也保持一致——COMMIT 阶段由执行器完成 git 提交后通过autopilot_commit回报。

这些 MCP 工具统一委托给WorkflowService门面（见 workflow.service.ts），该门面封装了WorkflowOrchestrator的完整生命周期，并向上提供start()、resumeWorkflow()、getNextAction()、completePhase()、getStatus()等简化 API，MCP 层无需接触状态机细节。

五、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 TestResultValidator（TestAdapter 的落地形态）

设计稿中的 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；
读取当前 tag（tmCore.config.getActiveTag()）与 auth 上下文中的orgSlug（API 存储模式分支命名用）；
加载任务，校验任务存在且包含子任务（无子任务时提示先task-master expand --id=<taskId>）；
解析--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 会话如下：

# 终端 1：Claude 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 Scope（Phase 1）

实际的 git 操作（建分支、提交）——由执行器处理；
实际的测试执行——由执行器处理；
PR 创建——推迟到 Phase 2；
TUI 界面——推迟到 Phase 3；
覆盖率强制——推迟到 Phase 2。

后续阶段规划可见 tdd-workflow-phase-2-pr-resumability.md：Phase 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 各阶段的完成判定，最后测状态序列化-恢复的往返一致性。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析