claude-code-workflow 6.3.22 → 6.3.24

package/.claude/skills/review-code/phases/orchestrator.md

@@ -0,0 +1,251 @@
+# Orchestrator
+
+根据当前状态选择并执行下一个审查动作。
+
+## Role
+
+Code Review 编排器，负责：
+1. 读取当前审查状态
+2. 根据状态选择下一个动作
+3. 执行动作并更新状态
+4. 循环直到审查完成
+
+## Dependencies
+
+- **State Manager**: [state-manager.md](./state-manager.md) - 提供原子化状态操作、自动备份、验证和回滚功能
+
+## State Management
+
+本模块使用 StateManager 进行所有状态操作，确保：
+- **原子更新** - 写入临时文件后重命名，防止损坏
+- **自动备份** - 每次更新前自动创建备份
+- **回滚能力** - 失败时可从备份恢复
+- **结构验证** - 确保状态结构完整性
+
+### StateManager API (from state-manager.md)
+
+```javascript
+// 初始化状态
+StateManager.initState(workDir)
+
+// 读取当前状态
+StateManager.getState(workDir)
+
+// 更新状态（原子操作，自动备份）
+StateManager.updateState(workDir, updates)
+
+// 获取下一个待审查维度
+StateManager.getNextDimension(state)
+
+// 标记维度完成
+StateManager.markDimensionComplete(workDir, dimension)
+
+// 记录错误
+StateManager.recordError(workDir, action, message)
+
+// 从备份恢复
+StateManager.restoreState(workDir)
+```
+
+## Decision Logic
+
+```javascript
+function selectNextAction(state) {
+  // 1. 终止条件检查
+  if (state.status === 'completed') return null;
+  if (state.status === 'user_exit') return null;
+  if (state.error_count >= 3) return 'action-abort';
+
+  // 2. 初始化阶段
+  if (state.status === 'pending' || !state.context) {
+    return 'action-collect-context';
+  }
+
+  // 3. 快速扫描阶段
+  if (!state.scan_completed) {
+    return 'action-quick-scan';
+  }
+
+  // 4. 深入审查阶段 - 使用 StateManager 获取下一个维度
+  const nextDimension = StateManager.getNextDimension(state);
+  if (nextDimension) {
+    return 'action-deep-review';  // 传递 dimension 参数
+  }
+
+  // 5. 报告生成阶段
+  if (!state.report_generated) {
+    return 'action-generate-report';
+  }
+
+  // 6. 完成
+  return 'action-complete';
+}
+```
+
+## Execution Loop
+
+```javascript
+async function runOrchestrator() {
+  console.log('=== Code Review Orchestrator Started ===');
+
+  let iteration = 0;
+  const MAX_ITERATIONS = 20;  // 6 dimensions + overhead
+
+  // 初始化状态（如果尚未初始化）
+  let state = StateManager.getState(workDir);
+  if (!state) {
+    state = StateManager.initState(workDir);
+  }
+
+  while (iteration < MAX_ITERATIONS) {
+    iteration++;
+
+    // 1. 读取当前状态（使用 StateManager）
+    state = StateManager.getState(workDir);
+    if (!state) {
+      console.error('[Orchestrator] Failed to read state, attempting recovery...');
+      state = StateManager.restoreState(workDir);
+      if (!state) {
+        console.error('[Orchestrator] Recovery failed, aborting.');
+        break;
+      }
+    }
+    console.log(`[Iteration ${iteration}] Status: ${state.status}`);
+
+    // 2. 选择下一个动作
+    const actionId = selectNextAction(state);
+
+    if (!actionId) {
+      console.log('Review completed, terminating.');
+      break;
+    }
+
+    console.log(`[Iteration ${iteration}] Executing: ${actionId}`);
+
+    // 3. 更新状态：当前动作（使用 StateManager）
+    StateManager.updateState(workDir, { current_action: actionId });
+
+    // 4. 执行动作
+    try {
+      const actionPrompt = Read(`phases/actions/${actionId}.md`);
+
+      // 确定当前需要审查的维度（使用 StateManager）
+      const currentDimension = StateManager.getNextDimension(state);
+
+      const result = await Task({
+        subagent_type: 'universal-executor',
+        run_in_background: false,
+        prompt: `
+[WORK_DIR]
+${workDir}
+
+[STATE]
+${JSON.stringify(state, null, 2)}
+
+[CURRENT_DIMENSION]
+${currentDimension || 'N/A'}
+
+[ACTION]
+${actionPrompt}
+
+[SPECS]
+Review Dimensions: specs/review-dimensions.md
+Issue Classification: specs/issue-classification.md
+
+[RETURN]
+Return JSON with stateUpdates field containing updates to apply to state.
+`
+      });
+
+      const actionResult = JSON.parse(result);
+
+      // 5. 更新状态：动作完成（使用 StateManager）
+      StateManager.updateState(workDir, {
+        current_action: null,
+        completed_actions: [...(state.completed_actions || []), actionId],
+        ...actionResult.stateUpdates
+      });
+
+      // 如果是深入审查动作，标记维度完成
+      if (actionId === 'action-deep-review' && currentDimension) {
+        StateManager.markDimensionComplete(workDir, currentDimension);
+      }
+
+    } catch (error) {
+      // 错误处理（使用 StateManager.recordError）
+      console.error(`[Orchestrator] Action failed: ${error.message}`);
+      StateManager.recordError(workDir, actionId, error.message);
+
+      // 清除当前动作
+      StateManager.updateState(workDir, { current_action: null });
+
+      // 检查是否需要恢复状态
+      const updatedState = StateManager.getState(workDir);
+      if (updatedState && updatedState.error_count >= 3) {
+        console.error('[Orchestrator] Too many errors, attempting state recovery...');
+        StateManager.restoreState(workDir);
+      }
+    }
+  }
+
+  console.log('=== Code Review Orchestrator Finished ===');
+}
+```
+
+## Action Catalog
+
+| Action | Purpose | Preconditions |
+|--------|---------|---------------|
+| [action-collect-context](actions/action-collect-context.md) | 收集审查目标上下文 | status === 'pending' |
+| [action-quick-scan](actions/action-quick-scan.md) | 快速扫描识别风险区域 | context !== null |
+| [action-deep-review](actions/action-deep-review.md) | 深入审查指定维度 | scan_completed === true |
+| [action-generate-report](actions/action-generate-report.md) | 生成结构化审查报告 | all dimensions reviewed |
+| [action-complete](actions/action-complete.md) | 完成审查，保存结果 | report_generated === true |
+
+## Termination Conditions
+
+- `state.status === 'completed'` - 审查正常完成
+- `state.status === 'user_exit'` - 用户主动退出
+- `state.error_count >= 3` - 错误次数超限（由 StateManager.recordError 自动处理）
+- `iteration >= MAX_ITERATIONS` - 迭代次数超限
+
+## Error Recovery
+
+本模块利用 StateManager 提供的错误恢复机制：
+
+| Error Type | Recovery Strategy | StateManager Function |
+|------------|-------------------|----------------------|
+| 状态读取失败 | 从备份恢复 | `restoreState(workDir)` |
+| 动作执行失败 | 记录错误，累计超限后自动失败 | `recordError(workDir, action, message)` |
+| 状态不一致 | 验证并恢复 | `getState()` 内置验证 |
+| 用户中止 | 保存当前进度 | `updateState(workDir, { status: 'user_exit' })` |
+
+### 错误处理流程
+
+```
+1. 动作执行失败
+   |
+2. StateManager.recordError() 记录错误
+   |
+3. 检查 error_count
+   |
+   +-- < 3: 继续下一次迭代
+   +-- >= 3: StateManager 自动设置 status='failed'
+             |
+             Orchestrator 检测到 status 变化
+             |
+             尝试 restoreState() 恢复到上一个稳定状态
+```
+
+### 状态备份时机
+
+StateManager 在以下时机自动创建备份：
+- 每次 `updateState()` 调用前
+- 可通过 `backupState(workDir, suffix)` 手动创建命名备份
+
+### 历史追踪
+
+所有状态变更记录在 `state-history.json`，便于调试和审计：
+- 初始化事件
+- 每次更新的字段变更
+- 恢复操作记录