@zeyue0329/xiaoma-cli 1.0.39 → 1.0.41

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专注于"执行层",协调器负责"控制层",实现关注点分离和更可靠的自动化。

package/xiaoma-core/workflows/automated-requirements-analysis.yaml

@@ -1273,7 +1273,11 @@ workflow:
             - 考虑可测试性
             - 所有设计决策都要有理由说明
 
-            请执行设计并生成文档。
+            **输出文件**：
+            - 架构设计文档: docs/architecture/iteration-backend-design.md
+            - 数据库脚本: docs/architecture/db-migration-scripts.sql
+
+            请执行设计并将架构文档保存到 docs/architecture/iteration-backend-design.md。
 
           execution_process:
             phase_1: analyze_prd_and_epics
@@ -1458,15 +1462,14 @@ workflow:
             **源文档**：
             docs/architecture/iteration-backend-design.md
 
-            **切分命令**：
-            请执行 shard-doc 命令，将架构文档切分到指定目录：
+            **切分方法**：
 
-            ```
-            shard-doc docs/architecture/iteration-backend-design.md docs/architecture
-            ```
+            方法一（推荐）：使用 *shard-doc 命令自动切分
+            首先，请确认源文档 docs/architecture/iteration-backend-design.md 已经存在。
+            然后执行：*shard-doc docs/architecture/iteration-backend-design.md docs/architecture
 
-            **切分策略**：
-            请将架构文档按以下技术模块切分：
+            方法二（如果自动切分不满足需求）：手动按照以下策略切分
+            如果自动切分生成的文档与期望的7个模块文档不匹配，请手动创建以下文档：
 
             1. **数据库设计** (database-design.md)
                - 从【第2节 新增数据模型设计】提取