@zeyue0329/xiaoma-cli 1.0.48 → 6.0.0-alpha.13

package/docs/architecture/workflow-coordinator-implementation.md

@@ -1,1188 +0,0 @@
-# 工作流协调器 - 完整实现指南
-
-> **版本**: 2.0.0
-> **日期**: 2025-11-13
-> **相关文档**: [PRD文档](../prd/workflow-coordinator-prd.md)
-
----
-
-## 目录
-
-1. [快速开始](#1-快速开始)
-2. [协调器端实现](#2-协调器端实现)
-3. [Claude Code端实现](#3-claude-code端实现)
-4. [完整示例](#4-完整示例)
-5. [测试和调试](#5-测试和调试)
-
----
-
-## 1. 快速开始
-
-### 1.1 项目初始化
-
-```bash
-# 1. 创建协调器项目
-cd tools/
-mkdir workflow-coordinator
-cd workflow-coordinator
-
-# 2. 初始化npm项目
-npm init -y
-
-# 3. 安装依赖
-npm install express js-yaml fs-extra chalk cors dotenv
-
-# 4. 安装开发依赖
-npm install --save-dev nodemon jest
-
-# 5. 创建目录结构
-mkdir -p src/{api,parser,controller,utils}
-mkdir -p test
-```
-
-### 1.2 项目结构
-
-```
-tools/workflow-coordinator/
-├── src/
-│   ├── index.js                    # 主入口
-│   ├── api/
-│   │   └── server.js               # HTTP服务器
-│   ├── parser/
-│   │   └── workflow-parser.js      # 工作流解析器
-│   ├── controller/
-│   │   └── workflow-controller.js  # 工作流控制器
-│   └── utils/
-│       ├── state-manager.js        # 状态管理
-│       └── validator.js            # 验证器
-├── test/
-├── package.json
-└── README.md
-
-xiaoma-core/agents/
-└── workflow-helper.md              # 新增智能体
-```
-
----
-
-## 2. 协调器端实现
-
-### 2.1 主入口 (src/index.js)
-
-```javascript
-#!/usr/bin/env node
-
-const path = require('path');
-const chalk = require('chalk');
-const WorkflowParser = require('./parser/workflow-parser');
-const WorkflowController = require('./controller/workflow-controller');
-const CoordinatorServer = require('./api/server');
-
-async function main() {
-  const args = process.argv.slice(2);
-  const command = args[0];
-  const workflowName = args[1];
-
-  if (command === 'start' && workflowName) {
-    console.log(chalk.blue(`\n🚀 启动工作流协调器\n`));
-
-    try {
-      // 1. 解析工作流
-      console.log(chalk.cyan(`📋 解析工作流: ${workflowName}`));
-      const parser = new WorkflowParser();
-      const executionPlan = await parser.parse(workflowName);
-
-      console.log(chalk.green(`✅ 工作流解析完成: ${executionPlan.metadata.name}`));
-      console.log(chalk.gray(`   步骤数: ${executionPlan.steps.length}`));
-
-      // 2. 创建控制器
-      const controller = new WorkflowController(executionPlan);
-
-      // 3. 启动HTTP服务
-      console.log(chalk.cyan(`\n🌐 启动HTTP服务...`));
-      const server = new CoordinatorServer(controller);
-      const port = process.env.COORDINATOR_PORT || 3001;
-
-      await server.start(port);
-
-      console.log(chalk.green(`✅ HTTP服务已启动: http://localhost:${port}`));
-      console.log(chalk.yellow(`\n⏳ 等待Claude Code连接...\n`));
-      console.log(chalk.gray(`   提示: 在Claude Code中执行以下命令启动工作流:`));
-      console.log(chalk.gray(`   /workflow-helper`));
-      console.log(chalk.gray(`   *start-workflow ${workflowName}\n`));
-
-    } catch (error) {
-      console.error(chalk.red(`\n❌ 启动失败: ${error.message}\n`));
-      console.error(error.stack);
-      process.exit(1);
-    }
-
-  } else {
-    // 显示帮助
-    console.log(chalk.blue(`\n工作流协调器\n`));
-    console.log(`用法:`);
-    console.log(`  xiaoma-coordinator start <workflow-name>     启动工作流协调器`);
-    console.log(``);
-    console.log(`示例:`);
-    console.log(`  xiaoma-coordinator start requirements-analysis`);
-    console.log(``);
-  }
-}
-
-main();
-```
-
----
-
-### 2.2 HTTP服务器 (src/api/server.js)
-
-```javascript
-const express = require('express');
-const cors = require('cors');
-const chalk = require('chalk');
-
-class CoordinatorServer {
-  constructor(controller) {
-    this.app = express();
-    this.controller = controller;
-    this.setupMiddleware();
-    this.setupRoutes();
-  }
-
-  setupMiddleware() {
-    this.app.use(express.json({ limit: '50mb' }));
-    this.app.use(cors());
-
-    // 请求日志
-    this.app.use((req, res, next) => {
-      console.log(chalk.gray(`[${new Date().toISOString()}] ${req.method} ${req.path}`));
-      next();
-    });
-  }
-
-  setupRoutes() {
-    // API: 启动工作流
-    this.app.post('/workflow/start', async (req, res) => {
-      try {
-        const { workflowId, context } = req.body;
-
-        console.log(chalk.cyan(`\n📥 收到启动请求: ${workflowId}`));
-
-        const result = await this.controller.startWorkflow(workflowId, context);
-
-        console.log(chalk.green(`✅ 返回第一步指令: ${result.firstStep.stepId}`));
-
-        res.json(result);
-      } catch (error) {
-        console.error(chalk.red(`❌ 启动失败: ${error.message}`));
-        res.status(500).json({
-          success: false,
-          error: error.message
-        });
-      }
-    });
-
-    // API: 步骤完成回调
-    this.app.post('/workflow/step-complete', async (req, res) => {
-      try {
-        const { workflowId, stepId, status, outputs, duration } = req.body;
-
-        console.log(chalk.cyan(`\n📥 步骤完成: ${stepId}`));
-        console.log(chalk.gray(`   耗时: ${Math.round(duration / 1000)}秒`));
-        console.log(chalk.gray(`   输出: ${outputs.length}个文件`));
-
-        const result = await this.controller.onStepComplete({
-          workflowId,
-          stepId,
-          status,
-          outputs,
-          duration
-        });
-
-        if (result.hasNextStep) {
-          console.log(chalk.green(`✅ 返回下一步指令: ${result.nextStep.stepId}`));
-          console.log(chalk.yellow(`   进度: ${result.progress.percentComplete}% (${result.progress.currentStepIndex}/${result.progress.totalSteps})`));
-        } else {
-          console.log(chalk.green.bold(`\n🎉 工作流执行完成!\n`));
-        }
-
-        res.json(result);
-      } catch (error) {
-        console.error(chalk.red(`❌ 处理失败: ${error.message}`));
-        res.status(500).json({
-          success: false,
-          error: error.message
-        });
-      }
-    });
-
-    // API: 步骤失败回调
-    this.app.post('/workflow/step-failed', async (req, res) => {
-      try {
-        const { workflowId, stepId, error, errorDetails } = req.body;
-
-        console.log(chalk.red(`\n❌ 步骤失败: ${stepId}`));
-        console.log(chalk.red(`   错误: ${error}`));
-
-        const result = await this.controller.onStepFailed({
-          workflowId,
-          stepId,
-          error,
-          errorDetails
-        });
-
-        res.json(result);
-      } catch (error) {
-        console.error(chalk.red(`❌ 处理失败: ${error.message}`));
-        res.status(500).json({
-          success: false,
-          error: error.message
-        });
-      }
-    });
-
-    // API: 查询状态
-    this.app.get('/workflow/status', (req, res) => {
-      const status = this.controller.getStatus();
-      res.json(status);
-    });
-
-    // API: 中止工作流
-    this.app.post('/workflow/abort', async (req, res) => {
-      try {
-        const { workflowId, reason } = req.body;
-
-        console.log(chalk.yellow(`\n⏸️ 中止工作流: ${reason}`));
-
-        await this.controller.abort(workflowId, reason);
-
-        res.json({
-          success: true,
-          message: '工作流已中止'
-        });
-      } catch (error) {
-        res.status(500).json({
-          success: false,
-          error: error.message
-        });
-      }
-    });
-
-    // 健康检查
-    this.app.get('/health', (req, res) => {
-      res.json({ status: 'ok' });
-    });
-  }
-
-  async start(port) {
-    return new Promise((resolve) => {
-      this.server = this.app.listen(port, () => {
-        resolve();
-      });
-    });
-  }
-
-  async stop() {
-    if (this.server) {
-      await this.server.close();
-    }
-  }
-}
-
-module.exports = CoordinatorServer;
-```
-
----
-
-### 2.3 工作流控制器 (src/controller/workflow-controller.js)
-
-```javascript
-const fs = require('fs-extra');
-const path = require('path');
-const StateManager = require('../utils/state-manager');
-const Validator = require('../utils/validator');
-
-class WorkflowController {
-  constructor(executionPlan) {
-    this.executionPlan = executionPlan;
-    this.stateManager = new StateManager();
-    this.validator = new Validator();
-    this.state = null;
-  }
-
-  /**
-   * 启动工作流
-   */
-  async startWorkflow(workflowId, context = {}) {
-    // 初始化状态
-    this.state = {
-      workflowId: workflowId,
-      workflowName: this.executionPlan.metadata.name,
-      status: 'in_progress',
-      startTime: new Date().toISOString(),
-      currentStepIndex: 0,
-      completedSteps: [],
-      context: context,
-      errors: [],
-      retries: {}
-    };
-
-    // 保存状态
-    await this.stateManager.save(this.state);
-
-    // 获取第一步
-    const firstStepDef = this.executionPlan.steps[0];
-    const firstStep = this.buildStepInstruction(firstStepDef);
-
-    return {
-      success: true,
-      workflowId: workflowId,
-      workflowName: this.executionPlan.metadata.name,
-      totalSteps: this.executionPlan.steps.length,
-      firstStep: firstStep
-    };
-  }
-
-  /**
-   * 步骤完成回调
-   */
-  async onStepComplete({ workflowId, stepId, status, outputs, duration }) {
-    // 1. 验证步骤输出
-    const stepDef = this.executionPlan.steps[this.state.currentStepIndex];
-    const validationResult = await this.validator.validateOutputs(stepDef, outputs);
-
-    if (!validationResult.passed) {
-      return {
-        success: false,
-        action: 'fix_quality',
-        issues: validationResult.issues,
-        message: '步骤输出质量验证失败,请修复问题后重试'
-      };
-    }
-
-    // 2. 记录完成步骤
-    this.state.completedSteps.push({
-      stepId: stepId,
-      agent: stepDef.agent,
-      status: status,
-      outputs: outputs,
-      duration: duration,
-      completedAt: new Date().toISOString()
-    });
-
-    // 3. 移动到下一步
-    this.state.currentStepIndex++;
-
-    // 4. 保存状态
-    await this.stateManager.save(this.state);
-
-    // 5. 检查是否还有下一步
-    if (this.state.currentStepIndex >= this.executionPlan.steps.length) {
-      // 工作流完成
-      this.state.status = 'completed';
-      this.state.endTime = new Date().toISOString();
-      await this.stateManager.save(this.state);
-
-      return {
-        success: true,
-        hasNextStep: false,
-        message: '🎉 工作流执行完成!',
-        summary: this.generateSummary()
-      };
-    }
-
-    // 6. 获取下一步指令
-    const nextStepDef = this.executionPlan.steps[this.state.currentStepIndex];
-    const nextStep = this.buildStepInstruction(nextStepDef);
-
-    return {
-      success: true,
-      hasNextStep: true,
-      nextStep: nextStep,
-      progress: {
-        currentStepIndex: this.state.currentStepIndex + 1,
-        totalSteps: this.executionPlan.steps.length,
-        percentComplete: Math.round(((this.state.currentStepIndex + 1) / this.executionPlan.steps.length) * 100)
-      }
-    };
-  }
-
-  /**
-   * 步骤失败回调
-   */
-  async onStepFailed({ workflowId, stepId, error, errorDetails }) {
-    const stepDef = this.executionPlan.steps[this.state.currentStepIndex];
-
-    // 记录错误
-    this.state.errors.push({
-      stepId: stepId,
-      error: error,
-      errorDetails: errorDetails,
-      timestamp: new Date().toISOString()
-    });
-
-    // 检查是否可以重试
-    const maxRetries = stepDef.onFailure?.max_retries || 3;
-    const currentRetries = this.state.retries[stepId] || 0;
-
-    if (currentRetries < maxRetries) {
-      // 可以重试
-      this.state.retries[stepId] = currentRetries + 1;
-      await this.stateManager.save(this.state);
-
-      const retryStep = this.buildStepInstruction(stepDef);
-
-      return {
-        success: true,
-        action: 'retry',
-        retryCount: currentRetries + 1,
-        maxRetries: maxRetries,
-        retryStep: retryStep,
-        message: `将进行第 ${currentRetries + 1} 次重试`
-      };
-    } else {
-      // 达到最大重试次数,中止工作流
-      this.state.status = 'failed';
-      this.state.endTime = new Date().toISOString();
-      await this.stateManager.save(this.state);
-
-      return {
-        success: false,
-        action: 'abort',
-        message: `步骤 "${stepId}" 执行失败,已达最大重试次数`,
-        escalation: stepDef.onFailure?.escalation || '需要人工介入'
-      };
-    }
-  }
-
-  /**
-   * 构建步骤执行指令
-   */
-  buildStepInstruction(stepDef) {
-    // 从 detailed_steps 中提取命令和提示词
-    const detailedSteps = stepDef.detailedSteps || [];
-
-    // 找到第一个命令步骤(非智能体切换)
-    const commandStep = detailedSteps.find(ds =>
-      ds.command && ds.command.startsWith('*')
-    );
-
-    // 找到智能体切换步骤
-    const agentSwitchStep = detailedSteps.find(ds =>
-      ds.command && ds.command.startsWith('/')
-    );
-
-    return {
-      stepId: stepDef.id,
-      stepDescription: stepDef.description,
-      agent: stepDef.agent,
-      switchCommand: agentSwitchStep?.command || `/agent ${stepDef.agent}`,
-      executeCommand: commandStep?.command || '',
-      prompt: commandStep?.prompt_template || '',
-      inputFiles: stepDef.requires || [],
-      expectedOutputs: stepDef.outputs || [],
-      detailedSteps: detailedSteps,
-      estimatedDuration: stepDef.duration
-    };
-  }
-
-  /**
-   * 生成完成摘要
-   */
-  generateSummary() {
-    const totalDuration = this.state.completedSteps.reduce((sum, step) => sum + step.duration, 0);
-    const allOutputs = this.state.completedSteps.flatMap(step => step.outputs);
-
-    return {
-      workflowId: this.state.workflowId,
-      workflowName: this.state.workflowName,
-      status: this.state.status,
-      startTime: this.state.startTime,
-      endTime: this.state.endTime,
-      totalDuration: totalDuration,
-      totalSteps: this.state.completedSteps.length,
-      outputs: allOutputs.map(o => o.file),
-      errors: this.state.errors.length
-    };
-  }
-
-  /**
-   * 获取当前状态
-   */
-  getStatus() {
-    return {
-      workflowId: this.state?.workflowId,
-      status: this.state?.status || 'not_started',
-      currentStepIndex: this.state?.currentStepIndex,
-      totalSteps: this.executionPlan.steps.length,
-      completedSteps: this.state?.completedSteps.map(s => s.stepId) || [],
-      errors: this.state?.errors.length || 0
-    };
-  }
-
-  /**
-   * 中止工作流
-   */
-  async abort(workflowId, reason) {
-    if (this.state) {
-      this.state.status = 'aborted';
-      this.state.abortReason = reason;
-      this.state.endTime = new Date().toISOString();
-      await this.stateManager.save(this.state);
-    }
-  }
-}
-
-module.exports = WorkflowController;
-```
-
----
-
-### 2.4 工作流解析器 (src/parser/workflow-parser.js)
-
-```javascript
-const fs = require('fs-extra');
-const yaml = require('js-yaml');
-const path = require('path');
-
-class WorkflowParser {
-  constructor() {
-    this.workflowsDir = path.join(process.cwd(), '../../xiaoma-core/workflows');
-  }
-
-  async parse(workflowName) {
-    // 1. 查找工作流文件
-    const workflowFile = this.findWorkflowFile(workflowName);
-
-    if (!workflowFile) {
-      throw new Error(`工作流文件未找到: ${workflowName}`);
-    }
-
-    // 2. 读取并解析YAML
-    const yamlContent = await fs.readFile(workflowFile, 'utf-8');
-    const workflowDef = yaml.load(yamlContent);
-
-    // 3. 验证工作流定义
-    this.validate(workflowDef);
-
-    // 4. 构建执行计划
-    const executionPlan = {
-      metadata: {
-        id: workflowDef.workflow.id,
-        name: workflowDef.workflow.name,
-        description: workflowDef.workflow.description,
-        type: workflowDef.workflow.type
-      },
-      steps: workflowDef.workflow.sequence.map(step => this.parseStep(step)),
-      qualityGates: workflowDef.workflow.quality_gates || {},
-      errorHandling: workflowDef.workflow.error_handling || {}
-    };
-
-    return executionPlan;
-  }
-
-  parseStep(stepYaml) {
-    return {
-      id: stepYaml.step,
-      description: stepYaml.action || stepYaml.step,
-      agent: stepYaml.agent,
-      duration: stepYaml.duration,
-      requires: stepYaml.requires || [],
-      detailedSteps: stepYaml.detailed_steps || [],
-      validationCriteria: stepYaml.validation_criteria || [],
-      outputs: this.extractOutputs(stepYaml),
-      onFailure: stepYaml.on_failure
-    };
-  }
-
-  extractOutputs(stepYaml) {
-    const outputs = [];
-
-    // 从validation_criteria提取
-    if (stepYaml.validation_criteria) {
-      stepYaml.validation_criteria.forEach(criterion => {
-        if (typeof criterion === 'string' && criterion.includes('file_created:')) {
-          const filePath = criterion.split('file_created:')[1].trim().replace(/["']/g, '');
-          outputs.push({ file: filePath });
-        }
-      });
-    }
-
-    // 从detailed_steps提取
-    if (stepYaml.detailed_steps) {
-      stepYaml.detailed_steps.forEach(detailStep => {
-        if (detailStep.output && detailStep.output.file) {
-          outputs.push({ file: detailStep.output.file });
-        }
-      });
-    }
-
-    return outputs;
-  }
-
-  findWorkflowFile(workflowName) {
-    const possibleNames = [
-      `${workflowName}.yaml`,
-      `${workflowName}.yml`,
-      `automated-${workflowName}.yaml`,
-      `automated-${workflowName}.yml`
-    ];
-
-    for (const name of possibleNames) {
-      const filePath = path.join(this.workflowsDir, name);
-      if (fs.existsSync(filePath)) {
-        return filePath;
-      }
-    }
-
-    return null;
-  }
-
-  validate(workflowDef) {
-    if (!workflowDef.workflow) {
-      throw new Error('无效的工作流定义: 缺少 workflow 字段');
-    }
-
-    if (!workflowDef.workflow.sequence || !Array.isArray(workflowDef.workflow.sequence)) {
-      throw new Error('无效的工作流定义: 缺少 sequence 字段');
-    }
-
-    if (workflowDef.workflow.sequence.length === 0) {
-      throw new Error('无效的工作流定义: sequence 为空');
-    }
-  }
-}
-
-module.exports = WorkflowParser;
-```
-
----
-
-### 2.5 状态管理器 (src/utils/state-manager.js)
-
-```javascript
-const fs = require('fs-extra');
-const path = require('path');
-
-class StateManager {
-  constructor() {
-    this.stateDir = path.join(process.cwd(), '../../.xiaoma-core');
-    this.stateFile = path.join(this.stateDir, '.coordinator-state.json');
-  }
-
-  async save(state) {
-    await fs.ensureDir(this.stateDir);
-    await fs.writeFile(this.stateFile, JSON.stringify(state, null, 2), 'utf-8');
-  }
-
-  async load() {
-    if (!fs.existsSync(this.stateFile)) {
-      return null;
-    }
-
-    const content = await fs.readFile(this.stateFile, 'utf-8');
-    return JSON.parse(content);
-  }
-
-  async clear() {
-    if (fs.existsSync(this.stateFile)) {
-      await fs.remove(this.stateFile);
-    }
-  }
-}
-
-module.exports = StateManager;
-```
-
----
-
-### 2.6 验证器 (src/utils/validator.js)
-
-```javascript
-const fs = require('fs-extra');
-
-class Validator {
-  async validateOutputs(stepDef, actualOutputs) {
-    const issues = [];
-
-    // 验证所有预期输出文件
-    for (const expectedOutput of stepDef.outputs || []) {
-      const filePath = expectedOutput.file;
-      const actualOutput = actualOutputs.find(o => o.file === filePath);
-
-      if (!actualOutput) {
-        issues.push({
-          level: 'error',
-          message: `输出文件未报告: ${filePath}`
-        });
-        continue;
-      }
-
-      if (!actualOutput.exists) {
-        issues.push({
-          level: 'error',
-          message: `输出文件不存在: ${filePath}`
-        });
-        continue;
-      }
-
-      if (actualOutput.size === 0) {
-        issues.push({
-          level: 'warning',
-          message: `输出文件为空: ${filePath}`
-        });
-      }
-    }
-
-    return {
-      passed: issues.filter(i => i.level === 'error').length === 0,
-      issues: issues
-    };
-  }
-}
-
-module.exports = Validator;
-```
-
----
-
-## 3. Claude Code端实现
-
-### 3.1 workflow-helper智能体定义
-
-**文件**: `xiaoma-core/agents/workflow-helper.md`
-
-```markdown
-# Workflow Helper - 工作流助手 🤖
-
-> **核心使命: 与工作流协调器通信,自动执行工作流步骤**
-
----
-
-激活通知: 此文件包含您完整的智能体操作指南。
-
-关键提示: 请阅读此文件中的完整YAML块以理解您的操作参数,并严格遵循您的激活指令:
-
-## 完整的智能体定义
-
-\`\`\`yaml
-activation-instructions:
-  - 步骤1: 阅读整个文件
-  - 步骤2: 采用下面'agent'和'persona'部分中定义的角色
-  - 步骤3: 向用户打招呼,显示可用命令
-  - 步骤4: 等待用户执行命令
-
-agent:
-  name: workflow-helper
-  id: workflow-helper
-  title: Workflow Helper
-  icon: 🤖
-  role: 工作流自动化助手,负责与工作流协调器通信
-  expertise: 工作流执行、智能体协调、HTTP通信
-
-persona:
-  role: 工作流自动化助手
-  style: 自动化、高效、精确、无需确认
-  identity: 专注于执行工作流协调器下发的指令,自动完成所有步骤
-  focus: 与协调器通信、智能体切换、状态报告
-  core_principles:
-    - 严格按照协调器指令执行
-    - 自动切换智能体
-    - 自动报告步骤完成状态
-    - 绝不询问用户是否继续
-    - 完全自动化执行
-
-commands:
-  - help: 显示可用命令
-  - start-workflow {workflow-name}: 启动工作流
-  - status: 查询当前工作流状态
-  - abort: 中止当前工作流
-
-configuration:
-  coordinator_url: "http://localhost:3001"
-\`\`\`
-
----
-
-## 工作原理
-
-1. **用户启动**: 用户执行 `*start-workflow requirements-analysis`
-2. **调用协调器**: 通过HTTP API请求第一步指令
-3. **执行步骤**: 切换智能体,执行命令,生成文档
-4. **报告完成**: 调用协调器API报告步骤完成
-5. **获取下一步**: 协调器返回下一步指令
-6. **自动循环**: 重复步骤3-5直到工作流完成
-
----
-
-## 命令说明
-
-### *start-workflow {workflow-name}
-
-启动指定的工作流
-
-**示例**:
-\`\`\`
-*start-workflow requirements-analysis
-\`\`\`
-
-**执行流程**:
-1. 调用 POST http://localhost:3001/workflow/start
-2. 获取第一步指令
-3. 自动执行第一步
-4. 报告完成并获取下一步
-5. 循环执行直到完成
-
----
-
-### *status
-
-查询当前工作流执行状态
-
-**示例**:
-\`\`\`
-*status
-\`\`\`
-
----
-
-### *abort
-
-中止当前工作流
-
-**示例**:
-\`\`\`
-*abort
-\`\`\`
-
----
-
-## 实现细节
-
-### 命令: *start-workflow
-
-当用户执行此命令时,你需要:
-
-\`\`\`javascript
-// 1. 调用协调器API启动工作流
-const response = await fetch('http://localhost:3001/workflow/start', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    workflowId: workflowName,
-    context: { projectRoot: process.cwd() }
-  })
-});
-
-const result = await response.json();
-
-// 2. 获取第一步指令
-const firstStep = result.firstStep;
-
-// 3. 执行第一步
-await executeStep(firstStep);
-\`\`\`
-
-### 执行步骤逻辑
-
-\`\`\`javascript
-async function executeStep(stepInstruction) {
-  console.log(\`\\n执行步骤: \${stepInstruction.stepId}\`);
-  console.log(\`智能体: \${stepInstruction.agent}\`);
-
-  const startTime = Date.now();
-
-  // 1. 切换智能体(如果需要)
-  if (stepInstruction.switchCommand) {
-    console.log(\`切换到: \${stepInstruction.agent}\`);
-    // 这里需要实际的智能体切换
-    // 比如: /analyst, /architect, /pm等
-  }
-
-  // 2. 执行命令
-  console.log(\`执行命令: \${stepInstruction.executeCommand}\`);
-  console.log(\`\\n提示词:\\n\${stepInstruction.prompt}\\n\`);
-
-  // 3. 等待智能体执行完成并生成文档
-  // (这部分由实际的智能体执行,比如Analyst生成需求分析文档)
-
-  // 4. 收集输出文件信息
-  const outputs = stepInstruction.expectedOutputs.map(output => ({
-    file: output.file || output,
-    exists: fs.existsSync(output.file || output),
-    size: fs.existsSync(output.file || output) ? fs.statSync(output.file || output).size : 0
-  }));
-
-  // 5. 报告步骤完成
-  const completeResponse = await fetch('http://localhost:3001/workflow/step-complete', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      workflowId: 'current',
-      stepId: stepInstruction.stepId,
-      status: 'success',
-      outputs: outputs,
-      duration: Date.now() - startTime
-    })
-  });
-
-  const nextStepResult = await completeResponse.json();
-
-  // 6. 检查是否有下一步
-  if (nextStepResult.hasNextStep) {
-    console.log(\`\\n进度: \${nextStepResult.progress.percentComplete}%\`);
-    console.log(\`→ 自动进入下一步骤...\\n\`);
-
-    // 7. 自动执行下一步(关键:不询问用户!)
-    await executeStep(nextStepResult.nextStep);
-  } else {
-    console.log(\`\\n🎉 工作流执行完成!\`);
-    console.log(nextStepResult.message);
-  }
-}
-\`\`\`
-
----
-
-## 重要提示
-
-1. **完全自动化**: 步骤间绝不询问用户"是否继续"
-2. **自动切换智能体**: 根据协调器指令自动切换
-3. **自动报告状态**: 每个步骤完成后立即报告
-4. **错误处理**: 如果步骤失败,报告给协调器处理
-
----
-
-祝你工作愉快! 🤖
-```
-
----
-
-## 4. 完整示例
-
-### 4.1 启动协调器
-
-**终端1: 启动协调器**
-
-```bash
-cd tools/workflow-coordinator
-
-# 安装依赖(首次)
-npm install
-
-# 启动协调器
-node src/index.js start requirements-analysis
-
-# 输出:
-# 🚀 启动工作流协调器
-#
-# 📋 解析工作流: requirements-analysis
-# ✅ 工作流解析完成: 自动化需求分析和架构设计流程
-#    步骤数: 6
-#
-# 🌐 启动HTTP服务...
-# ✅ HTTP服务已启动: http://localhost:3001
-#
-# ⏳ 等待Claude Code连接...
-#
-#    提示: 在Claude Code中执行以下命令启动工作流:
-#    /workflow-helper
-#    *start-workflow requirements-analysis
-```
-
-### 4.2 在Claude Code中执行
-
-**终端2: Claude Code**
-
-```bash
-# 1. 切换到workflow-helper智能体
-/workflow-helper
-
-# 2. 启动工作流
-*start-workflow requirements-analysis
-```
-
-**预期输出**:
-
-```
-工作流助手已激活 🤖
-
-启动工作流: requirements-analysis
-
-📡 调用协调器API...
-✅ 连接成功: 自动化需求分析和架构设计流程
-   总步骤数: 6
-
-执行步骤: requirements_analysis_and_elicitation
-智能体: analyst
-切换到: analyst
-
-提示词:
-我需要对产品经理提供的需求文档进行深度分析和澄清。
-
-(Analyst智能体执行需求分析,生成文档...)
-
-✅ 步骤完成: requirements_analysis_and_elicitation
-   输出: docs/requirements/requirements-analysis.md (25.6 KB)
-
-📡 报告步骤完成...
-✅ 协调器响应成功
-
-进度: 16% (1/6)
-→ 自动进入下一步骤...
-
-执行步骤: analyze_existing_architecture
-智能体: architect
-切换到: architect
-
-提示词:
-请分析当前项目的后端架构。
-
-(Architect智能体执行架构分析...)
-
-✅ 步骤完成: analyze_existing_architecture
-   输出: docs/architecture/current-architecture-analysis.md (18.4 KB)
-
-进度: 33% (2/6)
-→ 自动进入下一步骤...
-
-(继续执行剩余步骤...)
-
-🎉 工作流执行完成!
-
-总耗时: 1小时48分钟
-完成步骤: 6
-生成文档: 10个
-```
-
-**协调器端同步输出**:
-
-```
-📥 收到启动请求: requirements-analysis
-✅ 返回第一步指令: requirements_analysis_and_elicitation
-
-📥 步骤完成: requirements_analysis_and_elicitation
-   耗时: 1140秒
-   输出: 1个文件
-✅ 返回下一步指令: analyze_existing_architecture
-   进度: 16% (1/6)
-
-📥 步骤完成: analyze_existing_architecture
-   耗时: 900秒
-   输出: 1个文件
-✅ 返回下一步指令: create_brownfield_prd
-   进度: 33% (2/6)
-
-(...)
-
-🎉 工作流执行完成!
-```
-
----
-
-## 5. 测试和调试
-
-### 5.1 测试协调器API
-
-```bash
-# 测试启动工作流
-curl -X POST http://localhost:3001/workflow/start \
-  -H "Content-Type: application/json" \
-  -d '{"workflowId":"requirements-analysis","context":{}}'
-
-# 测试步骤完成
-curl -X POST http://localhost:3001/workflow/step-complete \
-  -H "Content-Type: application/json" \
-  -d '{
-    "workflowId":"requirements-analysis",
-    "stepId":"requirements_analysis_and_elicitation",
-    "status":"success",
-    "outputs":[{"file":"docs/requirements/requirements-analysis.md","exists":true,"size":25600}],
-    "duration":1140000
-  }'
-
-# 测试查询状态
-curl http://localhost:3001/workflow/status
-
-# 测试健康检查
-curl http://localhost:3001/health
-```
-
-### 5.2 调试技巧
-
-1. **启用详细日志**:
-```javascript
-// 在coordinator中添加
-console.log(JSON.stringify(stepInstruction, null, 2));
-```
-
-2. **查看状态文件**:
-```bash
-cat .xiaoma-core/.coordinator-state.json | jq
-```
-
-3. **模拟步骤执行**:
-创建测试脚本模拟Claude Code的请求
-
----
-
-## 6. package.json配置
-
-```json
-{
-  "name": "xiaoma-workflow-coordinator",
-  "version": "1.0.0",
-  "description": "工作流协调器 - 驱动XiaoMa-CLI工作流自动执行",
-  "main": "src/index.js",
-  "bin": {
-    "xiaoma-coordinator": "src/index.js"
-  },
-  "scripts": {
-    "start": "node src/index.js",
-    "dev": "nodemon src/index.js",
-    "test": "jest"
-  },
-  "keywords": ["workflow", "automation", "coordinator"],
-  "author": "XiaoMa Team",
-  "license": "MIT",
-  "dependencies": {
-    "express": "^4.18.2",
-    "js-yaml": "^4.1.0",
-    "fs-extra": "^11.1.1",
-    "chalk": "^5.3.0",
-    "cors": "^2.8.5",
-    "dotenv": "^16.3.1"
-  },
-  "devDependencies": {
-    "nodemon": "^3.0.1",
-    "jest": "^29.7.0"
-  }
-}
-```
-
----
-
-## 附录
-
-### A. 常见问题
-
-**Q: 协调器无法连接?**
-A: 检查端口3001是否被占用,可以修改环境变量`COORDINATOR_PORT`
-
-**Q: workflow-helper无法调用协调器API?**
-A: 确认协调器已启动,检查URL是否正确: http://localhost:3001
-
-**Q: 步骤执行后无法获取输出文件?**
-A: 确认智能体已正确生成文档,检查文件路径是否正确
-
-**Q: 如何添加新的工作流?**
-A: 在`xiaoma-core/workflows/`目录下创建新的YAML文件即可
-
----
-
-**文档完成!** 🎉
-
-现在你可以:
-1. 按照此指南实现协调器
-2. 创建workflow-helper智能体
-3. 测试完整的工作流自动执行