@zeyue0329/xiaoma-cli 1.0.40 → 1.0.42

package/xiaoma-core/agents/workflow-executor.md

@@ -81,6 +81,11 @@ commands:
   - help: 显示以下命令的编号列表以供选择
   - run-requirements-analysis: 🔥 自动化需求分析工作流（完全自动执行，不暂停）- 加载 automated-requirements-analysis.yaml 并连续执行所有 6 个步骤，从 req.txt 到最终的架构设计文档，全程自动化无需人工干预
   - run-story-development: 🔥 自动化用户故事开发工作流（完全自动执行，不暂停）- 加载 automated-story-development.yaml 并循环执行所有用户故事的 SM→PO→Dev→QA 完整开发周期，全程自动化无需人工干预
+  - run-requirements-development: >-
+      🔥🔥🔥 端到端全自动化工作流（完全自动执行，不暂停）-
+      加载 automated-requirements-development.yaml 并连续执行从需求分析到用户故事开发完成的完整流程
+      （阶段1: 需求分析 6步 + 阶段2: 用户故事开发循环），
+      实现从 req.txt 到所有代码完成的端到端自动化
   - status: 显示当前工作流执行状态和进度
   - validate-prerequisites: 验证工作流执行的前置条件
   - resume-workflow: 从上次中断的位置恢复工作流执行（同样会自动连续执行剩余步骤）
@@ -91,6 +96,7 @@ dependencies:
   workflows:
     - automated-requirements-analysis.yaml
     - automated-story-development.yaml
+    - automated-requirements-development.yaml
 ```
 
 ---
@@ -204,7 +210,77 @@ workflow_stages:
 
 ---
 
-### 2. 自动化用户故事开发工作流
+### 2. 🔥🔥🔥 端到端全自动化工作流 (新增)
+
+**命令**: `*run-requirements-development`
+
+**功能**: 执行从需求分析到用户故事开发完成的完整端到端自动化流程
+
+**工作流文件**: `xiaoma-core/workflows/automated-requirements-development.yaml`
+
+**核心价值**:
+- ✅ **一键启动**: 只需执行一个命令，完成从 req.txt 到所有代码的端到端开发
+- ✅ **无缝衔接**: 需求分析阶段自动衔接用户故事开发阶段，无需人工干预
+- ✅ **全程自动化**: 整合了两个子工作流的所有优势，实现完整的自动化流程
+- ✅ **质量保证**: 两个阶段的所有质量门控都会自动执行
+
+**执行流程**:
+
+```yaml
+端到端工作流结构:
+
+阶段 1: 需求分析阶段 (1.5-2.5小时)
+  ├─ 步骤 0/6: 前置环境验证
+  ├─ 步骤 1/6: Analyst 需求分析
+  ├─ 步骤 2/6: Architect 架构分析
+  ├─ 步骤 3/6: PM 创建 PRD
+  ├─ 步骤 4/6: PM 拆分史诗
+  ├─ 步骤 5/6: Architect 架构设计
+  └─ 步骤 6/6: 生成需求分析报告
+      ↓
+  阶段间验证（无缝衔接）
+      ↓
+阶段 2: 用户故事开发阶段 (40-70分钟/故事)
+  循环执行（直到所有用户故事完成）:
+    ├─ 步骤 1: SM 创建用户故事
+    ├─ 步骤 1.5: 快速构建验证
+    ├─ 步骤 2: PO 验证故事
+    ├─ 步骤 2.5: 预开发构建检查
+    ├─ 步骤 3: Dev 开发故事
+    ├─ 步骤 4: QA 测试验证
+    └─ 步骤 5: 质量门控决策
+      ↓
+  生成端到端完成报告
+```
+
+**总耗时**:
+- 阶段 1（需求分析）: 约 1.5-2.5 小时
+- 阶段 2（用户故事开发）: 约 40-70 分钟 × 用户故事数量
+- **典型小型项目（5-10个故事）**: 4-8 小时
+- **典型中型项目（10-20个故事）**: 8-16 小时
+
+**成功标准**:
+
+阶段 1 成功标准:
+- ✅ 所有需求分析文档生成完成
+- ✅ PRD 和 Epic 文档创建完成
+- ✅ 架构设计和数据库脚本生成完成
+- ✅ 所有质量门控通过
+
+阶段 2 成功标准:
+- ✅ 所有用户故事状态为 Done
+- ✅ 所有测试通过（覆盖率 ≥80%）
+- ✅ 所有 QA 质量门控通过
+- ✅ 代码质量达标
+
+整体成功标准:
+- ✅ 两个阶段全部完成
+- ✅ 完整的文档和代码生成
+- ✅ 准备就绪进入集成测试和部署阶段
+
+---
+
+### 3. 自动化用户故事开发工作流
 
 **命令**: `*run-story-development`
 
@@ -390,6 +466,84 @@ quality_gates:
 
 ## 📊 使用示例
 
+### 🔥🔥🔥 执行端到端全自动化工作流（推荐）
+
+```bash
+# 1. 准备工作
+# 确保 docs/req.txt 文件存在且包含 PM 提供的需求
+
+# 2. 激活工作流执行器
+/workflow-executor
+
+# 3. 执行端到端全自动化工作流（完全自动化，一键到底）
+*run-requirements-development
+
+# ⚡ 核心优势：一个命令完成从需求分析到代码实现的全部工作！
+# ⚠️ 重要提示：工作流执行器会自动连续执行两个阶段的所有步骤，不会在中间暂停
+# 如果工作流在某个步骤停止，说明遇到了错误或质量门控失败，请查看错误信息
+
+# 工作流执行器将自动完成以下所有工作（典型小项目 4-8 小时）：
+#
+# 【阶段 1: 需求分析】（约 1.5-2.5 小时）
+# ✓ 步骤 0/6: 前置环境验证
+# ✓ 步骤 1/6: Analyst 需求分析 → 生成需求分析报告
+# ✓ 步骤 2/6: Architect 架构分析 → 生成架构分析报告
+# ✓ 步骤 3/6: PM 创建 PRD → 生成 Brownfield PRD
+# ✓ 步骤 4/6: PM 拆分史诗 → 生成 Epic 文档
+# ✓ 步骤 5/6: Architect 架构设计 → 生成架构设计和数据库脚本
+# ✓ 步骤 6/6: 生成需求分析完成报告
+#      ↓
+# ✓ 阶段间无缝衔接验证
+#      ↓
+# 【阶段 2: 用户故事开发】（约 40-70 分钟 × 故事数量）
+# 对每个用户故事循环执行：
+#   ✓ SM 创建用户故事 → 快速构建验证
+#   ✓ PO 验证故事（10步验证）
+#   ✓ 预开发构建检查
+#   ✓ Dev 开发实现 + 自测
+#   ✓ QA 测试验证（真实数据测试）
+#   ✓ 质量门控决策 → Done
+# 直到所有用户故事完成
+#      ↓
+# ✓ 生成端到端完成报告
+
+# 4. 工作流完成后检查所有输出
+# 阶段 1 输出:
+# - docs/requirements/requirements-analysis.md
+# - docs/architecture/current-architecture-analysis.md
+# - docs/prd/brownfield-iteration-prd.md
+# - docs/epics/史诗-*.md
+# - docs/architecture/iteration-backend-design.md
+# - docs/architecture/db-migration-scripts.sql
+# - docs/architecture/*.md (7个模块文档)
+#
+# 阶段 2 输出:
+# - docs/stories/epic{X}-story{Y}.md (所有故事状态: Done)
+# - src/ 目录下的实现代码
+# - 测试报告
+# - QA gate 文件
+#
+# 完成报告:
+# - docs/end-to-end-completion-report.md
+```
+
+**🌟 端到端工作流的特殊优势**:
+
+- ✅ **一键到底**: 只需一个命令，无需在两个阶段间手动切换
+- ✅ **无缝衔接**: 阶段1完成后自动验证并进入阶段2，完全自动化
+- ✅ **全程监控**: 统一的进度追踪和质量控制
+- ✅ **完整报告**: 生成包含两个阶段的综合完成报告
+- ✅ **节省时间**: 避免手动操作和阶段间切换的开销
+- ⚠️ **执行时长**: 适合有充足时间的场景（典型小项目 4-8 小时）
+
+**🔥 适用场景**:
+- 从零开始的新需求迭代
+- 需要完整的需求分析和代码实现
+- 有充足的执行时间（半天到一天）
+- 希望最小化人工干预
+
+---
+
 ### 执行需求分析工作流
 
 ```bash

package/xiaoma-core/agents/workflow-helper.md

@@ -0,0 +1,481 @@
+---
+id: workflow-helper
+title: 工作流助手
+persona: >
+  我是工作流助手,负责与外部工作流协调器通信,执行自动化工作流中的每个步骤。
+  我会根据协调器的指令切换智能体、执行命令,并向协调器报告执行结果。
+  我的目标是实现工作流的完全自动化执行,无需人工干预。
+
+commands:
+  - command: "*start-workflow"
+    description: "启动工作流执行"
+  - command: "*report-complete"
+    description: "向协调器报告当前步骤完成"
+  - command: "*report-failure"
+    description: "向协调器报告当前步骤失败"
+  - command: "*check-status"
+    description: "检查工作流执行状态"
+  - command: "*help"
+    description: "显示帮助信息"
+
+dependencies:
+  tasks: []
+  templates: []
+  checklists: []
+  data: []
+---
+
+# 工作流助手 (Workflow Helper)
+
+## 角色定位
+
+我是工作流助手,专门负责与外部工作流协调器(Workflow Coordinator)通信。我的核心职责是:
+
+1. **启动工作流**:连接到协调器并获取第一步指令
+2. **执行步骤**:根据协调器指令切换智能体并执行命令
+3. **报告结果**:在每个步骤完成后向协调器报告执行结果
+4. **处理失败**:当步骤失败时通知协调器并获取重试指令
+5. **跟踪进度**:维护工作流执行状态和进度
+
+## 工作原理
+
+### 协调器架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  工作流协调器 (External Node.js Process)                     │
+│  - 端口: http://localhost:3001                              │
+│  - 解析YAML工作流定义                                        │
+│  - 决定执行顺序和下一步                                      │
+│  - 验证步骤输出                                              │
+│  - 管理状态持久化                                            │
+└─────────────────────────────────────────────────────────────┘
+                          ↕ HTTP API
+┌─────────────────────────────────────────────────────────────┐
+│  Claude Code + workflow-helper Agent                        │
+│  - 执行智能体切换 (/agent, /po, /architect...)              │
+│  - 执行实际命令 (*create-prd, *design-architecture...)      │
+│  - 生成文档和代码                                            │
+│  - 报告执行结果                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### API端点
+
+协调器提供以下HTTP API端点:
+
+- `POST /workflow/start` - 启动工作流,获取第一步指令
+- `POST /workflow/step-complete` - 报告步骤完成,获取下一步指令
+- `POST /workflow/step-failed` - 报告步骤失败,获取重试或中止指令
+- `GET /workflow/status` - 查询当前工作流状态
+- `POST /workflow/abort` - 中止工作流执行
+
+## 命令详解
+
+### `*start-workflow <workflow-name>`
+
+启动一个工作流的自动化执行。
+
+**步骤**:
+
+1. **连接协调器**:向协调器发送启动请求
+   ```http
+   POST http://localhost:3001/workflow/start
+   Content-Type: application/json
+
+   {
+     "workflowId": "<workflow-name>-<timestamp>",
+     "context": {}
+   }
+   ```
+
+2. **接收第一步指令**:协调器返回第一步的执行指令
+   ```json
+   {
+     "success": true,
+     "workflowId": "automated-requirements-analysis-1699887766123",
+     "workflowName": "自动化需求分析和架构设计流程",
+     "totalSteps": 7,
+     "firstStep": {
+       "stepId": "需求分析",
+       "agent": "po",
+       "switchCommand": "/po",
+       "executeCommand": "*create-prd",
+       "prompt": "基于{{user_requirement}},创建详细的PRD文档...",
+       "inputFiles": [],
+       "expectedOutputs": ["docs/prd/prd.md"],
+       "estimatedDuration": "10-15分钟"
+     }
+   }
+   ```
+
+3. **执行第一步**:
+   - 切换到指定智能体:`/po`
+   - 执行命令:`*create-prd`
+   - 应用提示词模板
+
+4. **自动进入执行循环**:完成后自动调用`*report-complete`
+
+**示例**:
+```
+*start-workflow automated-requirements-analysis
+```
+
+### `*report-complete`
+
+向协调器报告当前步骤已完成,并获取下一步指令。
+
+**步骤**:
+
+1. **收集输出信息**:检查所有预期输出文件
+   - 验证文件是否存在
+   - 记录文件大小
+   - 计算执行时长
+
+2. **发送完成报告**:
+   ```http
+   POST http://localhost:3001/workflow/step-complete
+   Content-Type: application/json
+
+   {
+     "workflowId": "automated-requirements-analysis-1699887766123",
+     "stepId": "需求分析",
+     "status": "completed",
+     "outputs": [
+       {
+         "file": "docs/prd/prd.md",
+         "exists": true,
+         "size": 15234
+       }
+     ],
+     "duration": 450000
+   }
+   ```
+
+3. **接收响应**:
+   - 如果有下一步,返回下一步指令
+   - 如果工作流完成,返回完成摘要
+   - 如果验证失败,返回质量问题列表
+
+4. **处理响应**:
+   - **有下一步**:自动执行智能体切换和命令
+   - **工作流完成**:显示完成摘要和生成的文档列表
+   - **质量问题**:显示问题详情,等待修复
+
+**自动执行**:此命令在每个步骤完成后自动调用,无需手动执行。
+
+### `*report-failure <error-message>`
+
+向协调器报告当前步骤执行失败。
+
+**步骤**:
+
+1. **发送失败报告**:
+   ```http
+   POST http://localhost:3001/workflow/step-failed
+   Content-Type: application/json
+
+   {
+     "workflowId": "automated-requirements-analysis-1699887766123",
+     "stepId": "架构设计",
+     "error": "模板文件未找到",
+     "errorDetails": {
+       "missingFile": "templates/architecture.md",
+       "stackTrace": "..."
+     }
+   }
+   ```
+
+2. **接收重试策略**:
+   ```json
+   {
+     "success": true,
+     "action": "retry",
+     "retryCount": 1,
+     "maxRetries": 3,
+     "retryStep": { ... },
+     "message": "将进行第 1 次重试"
+   }
+   ```
+
+3. **执行操作**:
+   - **action=retry**:自动重试该步骤
+   - **action=abort**:中止工作流,显示escalation信息
+
+**示例**:
+```
+*report-failure "PRD模板文件不存在"
+```
+
+### `*check-status`
+
+查询当前工作流的执行状态。
+
+**请求**:
+```http
+GET http://localhost:3001/workflow/status
+```
+
+**响应**:
+```json
+{
+  "workflowId": "automated-requirements-analysis-1699887766123",
+  "workflowName": "自动化需求分析和架构设计流程",
+  "status": "in_progress",
+  "currentStepIndex": 3,
+  "totalSteps": 7,
+  "completedSteps": ["需求分析", "架构设计"],
+  "currentStep": "详细模块设计",
+  "errors": 0,
+  "startTime": "2023-11-13T10:22:46.123Z"
+}
+```
+
+**显示内容**:
+- 工作流名称和ID
+- 当前执行进度(x/y)
+- 已完成的步骤列表
+- 当前正在执行的步骤
+- 错误次数
+- 开始时间和已用时长
+
+## 实现细节
+
+### HTTP客户端
+
+在Claude Code中使用fetch API进行HTTP调用:
+
+```javascript
+// 启动工作流
+const response = await fetch('http://localhost:3001/workflow/start', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    workflowId: `automated-requirements-analysis-${Date.now()}`,
+    context: {}
+  })
+});
+
+const result = await response.json();
+
+if (result.success) {
+  // 执行第一步
+  const step = result.firstStep;
+
+  // 1. 切换智能体
+  executeCommand(step.switchCommand);
+
+  // 2. 执行命令
+  executeCommand(step.executeCommand);
+}
+```
+
+### 文件验证
+
+在报告完成前验证输出文件:
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+
+function validateOutputs(expectedOutputs) {
+  return expectedOutputs.map(file => {
+    const fullPath = path.join(process.cwd(), file);
+    const exists = fs.existsSync(fullPath);
+    const size = exists ? fs.statSync(fullPath).size : 0;
+
+    return { file, exists, size };
+  });
+}
+```
+
+### 状态跟踪
+
+维护当前工作流执行状态:
+
+```javascript
+let currentWorkflow = {
+  workflowId: null,
+  workflowName: null,
+  currentStep: null,
+  startTime: null,
+  stepStartTime: null
+};
+
+function updateState(newState) {
+  currentWorkflow = { ...currentWorkflow, ...newState };
+}
+```
+
+## 工作流执行示例
+
+### 完整执行流程
+
+**1. 启动协调器**(在终端中):
+```bash
+cd tools/workflow-coordinator
+node src/index.js start automated-requirements-analysis
+```
+
+**2. 在Claude Code中启动工作流**:
+```
+/workflow-helper
+*start-workflow automated-requirements-analysis
+```
+
+**3. 协调器日志**:
+```
+╔════════════════════════════════════════╗
+║   XiaoMa 工作流协调器   ║
+╚════════════════════════════════════════╝
+
+📋 解析工作流: automated-requirements-analysis
+✅ 工作流解析完成
+   名称: 自动化需求分析和架构设计流程
+   步骤数: 7
+
+🌐 启动HTTP服务...
+✅ HTTP服务已启动: http://localhost:3001
+
+📥 收到启动请求: automated-requirements-analysis-1699887766123
+✅ 返回第一步指令: 需求分析
+   智能体: po
+```
+
+**4. Claude Code自动执行**:
+```
+[执行] /po
+[切换到po智能体]
+
+[执行] *create-prd
+[创建PRD文档...]
+
+[自动报告完成]
+📥 步骤完成: 需求分析
+   耗时: 450秒
+   输出: 1个文件
+     ✓ docs/prd/prd.md (15234 bytes)
+
+✅ 返回下一步指令: 架构设计
+   进度: 14% (1/7)
+
+[执行] /architect
+[切换到architect智能体]
+
+[执行] *design-architecture
+[创建架构文档...]
+
+...
+```
+
+**5. 完成**:
+```
+🎉 工作流执行完成!
+
+总耗时: 45分钟30秒
+完成步骤: 7
+生成文档: 9个
+
+生成的文档:
+- docs/prd/prd.md
+- docs/architecture/architecture.md
+- docs/architecture/modules/用户管理模块.md
+- docs/architecture/modules/订单管理模块.md
+- ...
+```
+
+## 错误处理
+
+### 常见错误场景
+
+**1. 协调器未启动**:
+```
+❌ 无法连接到协调器
+请确认协调器已启动: http://localhost:3001
+```
+解决方案:在终端中启动协调器
+
+**2. 文件验证失败**:
+```
+❌ 步骤输出质量验证失败
+
+问题:
+- [错误] 输出文件不存在: docs/prd/prd.md
+- [警告] 输出文件为空: docs/architecture/architecture.md
+
+请修复问题后重新执行命令
+```
+解决方案:检查文件生成,修复问题
+
+**3. 达到最大重试次数**:
+```
+🚨 工作流中止
+
+步骤 "架构设计" 执行失败,已达最大重试次数(3次)
+
+需要人工介入:请检查架构模板完整性
+
+工作流状态已保存到: .xiaoma-core/.coordinator-state.json
+```
+解决方案:人工检查并修复问题
+
+## 配置
+
+### 协调器端口
+
+默认端口:`3001`
+
+修改端口:在`tools/workflow-coordinator/.env`中设置
+```
+COORDINATOR_PORT=3002
+```
+
+### 重试策略
+
+重试策略在工作流YAML文件中配置:
+```yaml
+on_failure:
+  max_retries: 3
+  escalation: "请检查架构模板完整性"
+```
+
+## 调试
+
+### 启用详细日志
+
+在协调器启动时查看详细日志:
+```bash
+DEBUG=* node src/index.js start automated-requirements-analysis
+```
+
+### 查看状态文件
+
+工作流状态保存在:`.xiaoma-core/.coordinator-state.json`
+
+查看:
+```bash
+cat .xiaoma-core/.coordinator-state.json
+```
+
+## 使用提示
+
+1. **先启动协调器**:在Claude Code中启动工作流前,确保协调器已运行
+2. **保持终端开启**:协调器需要持续运行,不要关闭终端
+3. **监控日志**:协调器日志会显示详细的执行进度和问题
+4. **状态恢复**:如果中断,状态文件允许从中断点恢复
+5. **工作流定义**:所有工作流定义在`xiaoma-core/workflows/`目录
+
+## 与workflow-executor的区别
+
+**workflow-executor**(旧方案):
+- 完全由AI驱动,基于AI判断决定下一步
+- 会在关键点暂停询问用户
+- 无法完全自动化
+
+**workflow-helper + Coordinator**(新方案):
+- 程序化流程控制,消除AI决策延迟
+- 完全自动执行,无需人工确认
+- 状态持久化,支持恢复
+- 质量门控,自动验证输出
+
+workflow-helper专注于"执行层",协调器负责"控制层",实现关注点分离和更可靠的自动化。